diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-ruby.rst b/docs/codeql/codeql-language-guides/codeql-library-for-ruby.rst index 9d8f218edca..2ff7a62b2ac 100644 --- a/docs/codeql/codeql-language-guides/codeql-library-for-ruby.rst +++ b/docs/codeql/codeql-language-guides/codeql-library-for-ruby.rst @@ -73,7 +73,7 @@ The CodeQL examples in this article are only excerpts and are not meant to repre Abstract syntax --------------- -The abstract syntax tree (AST) represents the elements of the source code organized into a tree. The `AST viewer `__ +The abstract syntax tree (AST) represents the elements of the source code organized into a tree. The `AST viewer `__ in Visual Studio Code shows the AST nodes, including the relevant CodeQL classes and predicates. All CodeQL AST classes inherit from the `AstNode` class, which provides the following member predicates diff --git a/docs/codeql/codeql-overview/about-codeql.rst b/docs/codeql/codeql-overview/about-codeql.rst index db48990e96c..eccc81c8754 100644 --- a/docs/codeql/codeql-overview/about-codeql.rst +++ b/docs/codeql/codeql-overview/about-codeql.rst @@ -71,7 +71,7 @@ After you've created a CodeQL database, one or more queries are executed against it. CodeQL queries are written in a specially-designed object-oriented query language called QL. You can run the queries checked out from the CodeQL repo (or custom queries that you've written yourself) using the `CodeQL -for VS Code extension ` or the `CodeQL CLI +for VS Code extension `__ or the `CodeQL CLI `__. For more information about queries, see ":ref:`About CodeQL queries `." .. _interpret-query-results: diff --git a/docs/codeql/codeql-overview/codeql-changelog/codeql-cli-2.8.1.rst b/docs/codeql/codeql-overview/codeql-changelog/codeql-cli-2.8.1.rst index 5197b2f6165..c59a3e6498e 100644 --- a/docs/codeql/codeql-overview/codeql-changelog/codeql-cli-2.8.1.rst +++ b/docs/codeql/codeql-overview/codeql-changelog/codeql-cli-2.8.1.rst @@ -82,7 +82,7 @@ Bug Fixes Python """""" -* The `View AST functionality `__ no longer prints detailed information about regular expressions, greatly improving performance. +* The `View AST functionality `__ no longer prints detailed information about regular expressions, greatly improving performance. Minor Analysis Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/codeql/codeql-overview/codeql-tools.rst b/docs/codeql/codeql-overview/codeql-tools.rst index 0adb630bf25..d58730e4702 100644 --- a/docs/codeql/codeql-overview/codeql-tools.rst +++ b/docs/codeql/codeql-overview/codeql-tools.rst @@ -54,4 +54,4 @@ CodeQL for Visual Studio Code You can analyze CodeQL databases in Visual Studio Code using the CodeQL extension, which provides an enhanced environment for writing and running custom queries and viewing the results. For more information, see "`CodeQL -for Visual Studio Code `." \ No newline at end of file +for Visual Studio Code `__." \ No newline at end of file diff --git a/docs/codeql/reusables/deprecation-note.rst b/docs/codeql/reusables/deprecation-note.rst index 1cff31f2385..3019939baa1 100644 --- a/docs/codeql/reusables/deprecation-note.rst +++ b/docs/codeql/reusables/deprecation-note.rst @@ -2,5 +2,5 @@ Note - This documentation has been migrated to docs.github.com/en/code-security/codeql-for-vs-code. This version is no longer maintained, and it will be removed on TODOCS. + This documentation was migrated to docs.github.com/en/code-security/codeql-for-vs-code on 2024/05/08, and this version is no longer maintained. \ No newline at end of file diff --git a/docs/codeql/writing-codeql-queries/creating-path-queries.rst b/docs/codeql/writing-codeql-queries/creating-path-queries.rst index 0ab162a59c2..41f0683594c 100644 --- a/docs/codeql/writing-codeql-queries/creating-path-queries.rst +++ b/docs/codeql/writing-codeql-queries/creating-path-queries.rst @@ -20,7 +20,7 @@ This topic provides information on how to structure a path query file so you can Note - The alerts generated by path queries are included in the results generated using the `CodeQL CLI `__ and in `code scanning `__. You can also view the path explanations generated by your path query in the `CodeQL extension for VS Code `. + The alerts generated by path queries are included in the results generated using the `CodeQL CLI `__ and in `code scanning `__. You can also view the path explanations generated by your path query in the `CodeQL extension for VS Code `__. To learn more about modeling data flow with CodeQL, see ":doc:`About data flow analysis `." @@ -171,7 +171,7 @@ Select clauses for path queries consist of four 'columns', with the following st select element, source, sink, string The ``element`` and ``string`` columns represent the location of the alert and the alert message respectively, as explained in ":doc:`About CodeQL queries `." The second and third columns, ``source`` and ``sink``, are nodes on the path graph selected by the query. -Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in the `CodeQL extension for VS Code `. +Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in the `CodeQL extension for VS Code `__. The ``element`` that you select in the first column depends on the purpose of the query and the type of issue that it is designed to find. This is particularly important for security issues. For example, if you believe the ``source`` value to be globally invalid or malicious it may be best to display the alert at the ``source``. In contrast, you should consider displaying the alert at the ``sink`` if you believe it is the element that requires sanitization. diff --git a/docs/codeql/writing-codeql-queries/defining-the-results-of-a-query.rst b/docs/codeql/writing-codeql-queries/defining-the-results-of-a-query.rst index 94a949ce076..560505506f2 100644 --- a/docs/codeql/writing-codeql-queries/defining-the-results-of-a-query.rst +++ b/docs/codeql/writing-codeql-queries/defining-the-results-of-a-query.rst @@ -9,7 +9,7 @@ About query results ------------------- The information contained in the results of a query is controlled by the ``select`` statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand. -When you write your own queries in the CodeQL `extension for VS Code ` there are no constraints on what can be selected. +When you write your own queries in the CodeQL `extension for VS Code `__ there are no constraints on what can be selected. However, if you want to use a query to create alerts for code scanning or generate valid analysis results using the `CodeQL CLI `__, you'll need to make the ``select`` statement report results in the required format. You must also ensure that the query has the appropriate metadata properties defined. This topic explains how to write your select statement to generate helpful analysis results. diff --git a/docs/codeql/writing-codeql-queries/introduction-to-ql.rst b/docs/codeql/writing-codeql-queries/introduction-to-ql.rst index fa4736ec706..203f590f761 100644 --- a/docs/codeql/writing-codeql-queries/introduction-to-ql.rst +++ b/docs/codeql/writing-codeql-queries/introduction-to-ql.rst @@ -19,7 +19,7 @@ QL also supports recursion and aggregates. This allows you to write complex recu Running a query --------------- -You can try out the following examples and exercises using `CodeQL for VS Code ` or the `CodeQL template `__ on GitHub Codespaces. +You can try out the following examples and exercises using `CodeQL for VS Code `__ or the `CodeQL template `__ on GitHub Codespaces. Here is an example of a basic query: @@ -114,7 +114,7 @@ The following example queries *do* use these databases and give you an idea of h Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases. Visit `GitHub Security Lab `__ to read about examples of vulnerabilities that we have recently found in open source projects. -Before you can run the following examples, you will need to install the CodeQL extension for Visual Studio Code. For more information, see :ref:`Setting up CodeQL in Visual Studio Code `. You will also need to import and select a database in the corresponding programming language. For more information about obtaining CodeQL databases, see `Managing CodeQL databases `__ in the CodeQL for VS Code documentation. +Before you can run the following examples, you will need to install the CodeQL extension for Visual Studio Code. For more information, see :ref:`Setting up CodeQL in Visual Studio Code `. You will also need to import and select a database in the corresponding programming language. For more information about obtaining CodeQL databases, see `Managing CodeQL databases `__ in the CodeQL for VS Code documentation. To import the CodeQL library for a specific programming language, type ``import `` at the start of the query. diff --git a/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst b/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst index 731a5195ae7..34907e3910c 100644 --- a/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst +++ b/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst @@ -9,7 +9,7 @@ About query metadata -------------------- Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a QLDoc comment. -This metadata tells the CodeQL `extension for VS Code ` and the `Code scanning feature in GitHub `__ how to handle the query and display its results correctly. +This metadata tells the CodeQL `extension for VS Code `__ and the `Code scanning feature in GitHub `__ how to handle the query and display its results correctly. It also gives other users information about what the query results mean. For more information on query metadata, see the `query metadata style guide `__ in our `open source repository `__ on GitHub. .. pull-quote:: diff --git a/docs/supported-queries.md b/docs/supported-queries.md index 4335d819413..fa4cf1ea5d8 100644 --- a/docs/supported-queries.md +++ b/docs/supported-queries.md @@ -45,7 +45,7 @@ The process must begin with the first step and must conclude with the final step - Understand [the evaluation model of QL](https://codeql.github.com/docs/ql-language-reference/evaluation-of-ql-programs/). It's more similar to SQL than to any mainstream programming language. - Most performance tuning in QL boils down to computing as few tuples (rows of data) as possible. As a mental model, think of predicate evaluation as enumerating all combinations of parameters that satisfy the predicate body. This includes the implicit parameters `this` and `result`. - The major libraries in CodeQL are _cached_ and will only be computed once for the entire suite of queries. The first query that needs a cached _stage_ will trigger its evaluation. This means that query authors should usually only look at the run time of the last stage of evaluation. - - In [the settings for the VSCode extension](https://docs.github.com/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings), check the box "Running Queries: Debug" (`codeQL.runningQueries.debug`). Then find "CodeQL Query Server" in the VSCode Output panel (View -> Output) and capture the output when running the query. That output contains timing and tuple counts for all computed predicates. + - In [the settings for the VSCode extension](https://docs.github.com/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings/), check the box "Running Queries: Debug" (`codeQL.runningQueries.debug`). Then find "CodeQL Query Server" in the VSCode Output panel (View -> Output) and capture the output when running the query. That output contains timing and tuple counts for all computed predicates. - To clear the entire cache, invoke "CodeQL: Clear Cache" from the VSCode command palette. 6. **Make sure your query has the correct metadata**