Merge pull request github#12342 from github/codeql-cli-2.12.3-mergeback

Mergeback: codeql-cli-2.12.3 into main

Author: adityasharad

docs/codeql/codeql-for-visual-studio-code/about-codeql-for-visual-studio-code.rst

@@ -14,7 +14,7 @@ CodeQL for Visual Studio Code provides an easy way to run queries from the large
 With these queries, or your own custom queries, you can analyze databases generated from source code to find errors and security vulnerabilities.
 The Results view shows the flow of data through the results of path queries, which is essential for triaging security results.
 
-The CodeQL extension also adds a **CodeQL** sidebar view to VS Code. This contains a list of databases, and an overview of the queries that you have run in the current session.
+The CodeQL extension also adds a **CodeQL** sidebar view to VS Code. This contains a list of local CodeQL databases, an overview of the queries that you have run in the current session, and a variant analysis view for large scale analysis.
 
 The extension provides standard `IntelliSense <https://code.visualstudio.com/docs/editor/intellisense>`__
 features for query files (extension ``.ql``) and library files (extension ``.qll``) that you open in the Visual Studio Code editor.
@@ -36,4 +36,5 @@ Further reading
 -------------------
 
 - ":doc:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`"
-- ":doc:`Analyzing your projects <analyzing-your-projects>`"
+- ":doc:`Analyzing your projects <analyzing-your-projects>`"
+- ":doc:`Running CodeQL queries at scale with multi-repository variant analysis <running-codeql-queries-at-scale-with-mrva>`"

docs/codeql/codeql-for-visual-studio-code/analyzing-your-projects.rst

@@ -5,7 +5,7 @@
 Analyzing your projects
 =================================================
 
-You can run queries on CodeQL databases and view the results in Visual Studio Code.
+You can run queries on CodeQL databases and view the results in Visual Studio Code. This article explains how to get a CodeQL database and analyze it on your local machine. For information on running analysis at scale across many CodeQL databases, see ":ref:`Running CodeQL queries at scale with multi-repository variant analysis <running-codeql-queries-at-scale-with-mrva>`."
 
 Choosing a database
 ------------------------
@@ -24,8 +24,8 @@ To analyze a project, you need to add a :ref:`CodeQL database <codeql-database>`
 
 #. Once you've chosen a database, it is displayed in the Databases view. To see the menu options for interacting with a database, right-click an entry in the list. You can select multiple databases using **Ctrl/Cmd+click**.
 
-Obtaining a local database
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Importing a local database
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you have a CodeQL database saved locally, as an unarchived folder or as a ZIP file, you can add it to Visual Studio Code. There are several ways to obtain a local CodeQL database.
 
@@ -37,6 +37,9 @@ If you have a CodeQL database saved locally, as an unarchived folder or as a ZIP
 
   For more information about running query tests, see "`Testing custom queries <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries>`__" in the CodeQL CLI help.
 
+Downloading a database from GitHub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. include:: ../reusables/download-github-database.rst
 
 Running a query

docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst

@@ -25,6 +25,8 @@ Editing settings
 
 3. Edit a setting. The new settings are saved automatically.
 
+Alternatively, you can edit the settings in JSON format by opening the command palette and selecting **Preferences: Open User Settings (JSON)**.
+
 Choosing a version of the CodeQL CLI
 --------------------------------------
 
@@ -55,17 +57,58 @@ By default, items in the query history view are retained for 30 days. You can se
 
 .. _configuring-settings-for-running-queries:
 
-Configuring settings for running queries
------------------------------------------
+Configuring settings for running queries locally
+------------------------------------------------
 
 There are a number of settings for **Running Queries**. If your queries run too slowly and time out frequently, you may want to increase the memory. 
 
 .. include:: ../reusables/running-queries-debug.rst
 
 To save query server logs in a custom location, edit the **Running Queries: Custom Log Directory** setting. If you use a custom log directory, the extension saves the logs permanently, instead of deleting them automatically after each workspace session. This is useful if you want to investigate these logs to improve the performance of your queries.
 
-Configuring settings for testing queries
------------------------------------------
+Configuring settings for variant analysis
+------------------------------------------
+
+You can define or edit lists of GitHub repositories for variant analysis, and change to a different controller repository using the **Variant analysis** settings.
+
+For information on the purpose and requirements for a controller repository, see ":ref:`Setting up a controller repository for variant analysis <controller-repository>`."
+
+You can also edit the items shown in the Variant Analysis Repositories panel by editing a file in your Visual Studio Code workspace called ``databases.json``. This file contains a JSON representation of all the items displayed in the panel. To open your ``databases.json`` file in an editor window, click the **{ }** icon in the top right of the Variant Analysis Repositories panel. You can then see a structured representation of the repos, orgs and lists in your panel. For example:
+
+.. code-block:: json
+
+  {
+    "version": 1,
+    "databases": {
+      "variantAnalysis": {
+        "repositoryLists": [
+          {
+            "name": "My favorite JavaScript repos",
+            "repositories": [
+              "facebook/react",
+              "babel/babel",
+              "angular/angular"
+            ]
+          }
+        ],
+        "owners": [
+          "microsoft"
+        ],
+        "repositories": [
+          "apache/hadoop"
+        ]
+      }
+    },
+    "selected": {
+      "kind": "variantAnalysisSystemDefinedList",
+      "listName": "top_10"
+    }
+  }
+
+You can change the items shown in the panel or add new items by directly editing this file.
+
+Configuring settings for testing queries locally
+------------------------------------------------
 
 To increase the number of threads used for testing queries, you can update the **Running Tests > Number Of Threads** setting.
 

docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst

@@ -3,7 +3,7 @@
 .. _exploring-data-flow-with-path-queries:
 
 Exploring data flow with path queries
-=================================================
+=====================================
 
 You can run CodeQL queries in VS Code to help you track the flow of data through a program, highlighting areas that are potential security vulnerabilities.
 
@@ -20,8 +20,8 @@ You can also modify the existing queries to model data flow more precisely for t
 To ensure that your path query uses the correct format and metadata, follow the instructions in ":ref:`Creating path queries <creating-path-queries>`."
 This topic also contains detailed information about how to define new sources and sinks, as well as templates and examples of how to extend the CodeQL libraries to suit your analysis.
 
-Running path queries in VS Code
------------------------------------
+Running path queries in VS Code locally
+---------------------------------------
 
 #. Open a path query in the editor.
 #. Right-click in the query window and select **CodeQL: Run Query on Selected Database**. (Alternatively, run the command from the Command Palette.)
@@ -30,6 +30,8 @@ Running path queries in VS Code
 #. Click each step to jump to it in the source code and investigate the problem further.
 #. To navigate the results from your keyboard, you can bind shortcuts to the **CodeQL: Navigate Up/Down/Left/Right in Result Viewer** commands.
 
+When you are ready to run a path query at scale, you can use the Variant Analysis Repositories panel to run the query against up to 1,000 repositories on GitHub.com. For information on running analysis at scale across many CodeQL databases, see ":ref:`Running CodeQL queries at scale with multi-repository variant analysis <running-codeql-queries-at-scale-with-mrva>`."
+
 Further reading
 -----------------
 

docs/codeql/codeql-for-visual-studio-code/index.rst

@@ -27,6 +27,11 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
   VS Code to help you track the flow of data through a program, highlighting
   areas that are potential security vulnerabilities.  
 
+- :doc:`Running CodeQL queries at scale with multi-repository variant analysis
+  <running-codeql-queries-at-scale-with-mrva>`: You can run queries against groups
+  of repositories on GitHub.com and view results in Visual Studio Code as each analysis
+  finishes. 
+
 - :doc:`Testing CodeQL queries in Visual Studio Code
   <testing-codeql-queries-in-visual-studio-code>`: You can run unit tests for
   CodeQL queries using the Visual Studio Code extension.
@@ -40,7 +45,13 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
 
 - :doc:`Troubleshooting CodeQL for Visual Studio Code
   <troubleshooting-codeql-for-visual-studio-code>`: You can use the detailed 
-  information written to the extension's log files if you need to troubleshoot problems.
+  information written to the extension's log files if you need to troubleshoot problems with
+  analysis of local CodeQL databases.
+
+- :doc:`Troubleshooting variant analysis
+  <troubleshooting-variant-analysis>`: You can use the detailed 
+  information written to workflow log files in your controller repository if you need to
+  troubleshoot problems with analysis of CodeQL databases stored on GitHub.com.
 
 - :doc:`About telemetry in CodeQL for Visual Studio Code <about-telemetry-in-codeql-for-visual-studio-code>`: If you specifically opt in to permit GitHub to do so, GitHub will collect usage data and metrics for the purposes of helping the core developers to improve the CodeQL extension for VS Code.
 
@@ -53,8 +64,10 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
    analyzing-your-projects
    exploring-the-structure-of-your-source-code
    exploring-data-flow-with-path-queries
+   running-codeql-queries-at-scale-with-mrva
    testing-codeql-queries-in-visual-studio-code
    working-with-codeql-packs-in-visual-studio-code
    customizing-settings
    troubleshooting-codeql-for-visual-studio-code
+   troubleshooting-variant-analysis
    about-telemetry-in-codeql-for-visual-studio-code