Merge branch 'main' into patch-1

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

@@ -5,6 +5,8 @@
 About CodeQL for Visual Studio Code
 =================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 CodeQL for Visual Studio Code is an extension that lets you write, run, and test CodeQL queries in Visual Studio Code.
 
 Features

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

@@ -5,6 +5,8 @@
 About telemetry in CodeQL for Visual Studio Code
 =================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 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.
 
 This data will not be shared with any parties outside of GitHub. IP addresses and installation IDs will be retained for a maximum of 30 days. Anonymous data will be retained for a maximum of 180 days.
@@ -30,6 +32,7 @@ If you opt in, GitHub collects the following information related to the usage of
 - Randomly generated GUID that uniquely identifies a CodeQL extension installation. (Discarded before aggregation.)
 - IP address of the client sending the telemetry data. (Discarded before aggregation.)
 - Whether or not the ``codeQL.canary`` setting is enabled and set to ``true``.
+- Whether any :doc:`CodeQL extension settings <customizing-settings>` are configured.
 
 How long data is retained
 --------------------------
@@ -62,7 +65,7 @@ When telemetry collection is disabled, no data will be sent to GitHub servers.
 
 You can disable telemetry collection by setting ``codeQL.telemetry.enableTelemetry`` to ``false`` in your settings. For more information about CodeQL settings, see ":doc:`Customizing settings <customizing-settings>`." 
 
-Additionally, telemetry collection will be disabled if the global ``telemetry.enableTelemetry`` setting is set to ``false``. For more information about global telemetry collection, see "`Microsoft's documentation <https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting>`__."
+Additionally, telemetry collection will be disabled if the global ``telemetry.telemetryLevel`` setting is set to ``off``. For more information about global telemetry collection, see "`Microsoft's documentation <https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting>`__."
 
 Further reading
 ----------------

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

@@ -5,6 +5,8 @@
 Analyzing your projects
 =================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 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
@@ -42,14 +44,47 @@ Downloading a database from GitHub
 
 .. include:: ../reusables/download-github-database.rst
 
+.. _filtering-databases-and-queries-by-language:
+
+Filtering databases and queries by language
+-------------------------------------------
+
+Optionally, to see databases containing a specific language and queries written for that language, you can apply a language filter using the language selector.
+
+#. To see available language filters, in the sidebar, click the **Language** title bar.
+#. Hover over the language filter you would like to apply, then click **Select**.
+
+   .. image:: ../images/codeql-for-visual-studio-code/choose-language-filter.png
+      :width: 350
+      :alt: Screenshot of the language selector. The "Select" button for a language filter is outlined in dark orange.
+
+Creating a custom query
+------------------------
+
+You can generate a query template for a specific language from the queries panel, then write your own code to quickly create a custom query.
+
+#. Optionally, to create a custom query in an existing directory, in the sidebar, click the **Queries** title bar to expand the queries panel, then select the desired directory.
+#. In the sidebar, hover over the **Queries** title bar, then click the **Create query** icon.
+
+   .. image:: ../images/codeql-for-visual-studio-code/create-query-icon.png
+      :width: 350
+      :alt: Screenshot of the queries panel. The "Create query" icon is outlined in dark orange.
+
+#. In the Command Palette, select the target language for your query. If you've chosen not to create your custom query in an existing directory, selecting a language will autogenerate a directory labeled ``codeql-custom-queries-<language>``, where ``<language>`` is the name of the selected language. A query template labeled ``example.ql`` will then be added to the existing or autogenerated directory.
+#. In the template, write your custom query, then save the file. Once your query is finished, you can run it from the queries panel.
+
 Running a query
 ------------------------
 
 The `CodeQL repository <https://github.com/github/codeql>`__ on GitHub contains lots of example queries.
-If you have that folder (or a different CodeQL pack) available in your workspace, you can access existing queries under ``<language>/ql/src/<category>``, for example ``java/ql/src/Likely Bugs``.
+You can access any existing queries in your workspace through the queries panel.
 
-#. Open a query (``.ql``) file. It is displayed in the editor, with IntelliSense features such as syntax highlighting and autocomplete suggestions.
-#. Right-click in the query window and select **CodeQL: Run Query on Selected Database**. (Alternatively, run the command from the Command Palette.)
+#. In the sidebar, to expand the queries panel, click the **Queries** title bar.
+#. To run a query against the selected database, hover over the desired query, then click the **Run local query** icon.
+
+   .. image:: ../images/codeql-for-visual-studio-code/run-local-query-icon.png
+      :width: 350
+      :alt: Screenshot of the mouse pointer hovering over a query in the queries panel. The "Run local query" icon is outlined in dark orange.
 
 The CodeQL extension runs the query on the current database and reports progress in the bottom right corner of the application.
 When the results are ready, they're displayed in the Results view.
@@ -61,6 +96,23 @@ For more information, see ":doc:`Troubleshooting CodeQL for Visual Studio Code <
 Running multiple queries
 --------------------------
 
+You can quickly run multiple queries against the database you've selected using the queries panel or a single command.
+
+Running all queries in a directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can easily run every query in a directory using the queries panel.
+
+#. In the sidebar, to expand the queries panel, click the **Queries** title bar.
+#. Hover over the desired directory of queries, then click the **Run local queries** icon.
+
+   .. image:: ../images/codeql-for-visual-studio-code/run-local-queries-icon.png
+      :width: 350
+      :alt: Screenshot of the mouse pointer hovering over a directory of queries in the queries panel. The "Run local queries" icon is outlined in dark orange.
+
+Running a selection of queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 You can run multiple queries with a single command.
 
 #. Go to the File Explorer.
@@ -122,6 +174,7 @@ To see the queries that you have run in the current session, open the Query Hist
 
 The Query History contains information including the date and time when the query was run, the name of the query, the database on which it was run, and how long it took to run the query.
 To customize the information that is displayed, right-click an entry and select **Rename**.
+You can also filter the Query History view by language using the language selector. For more information, see ":ref:`Filtering databases and queries by language <filtering-databases-and-queries-by-language>`."
 
 Click an entry to display the corresponding results in the Query Results view, and double-click
 to display the query itself in the editor (or right-click and select **View Query**).
@@ -153,7 +206,7 @@ To use standard code navigation features in the source code, you can right-click
 
      If you're using an older database, code navigation commands such as **Go to Definition** and **Go to References** may not work.
      To use code navigation, try unzipping the database and running ``codeql database cleanup <database>`` on the unzipped database using the CodeQL CLI. Then, re-add the database to Visual Studio Code.
-     For more information, see the `database cleanup <../../codeql-cli/manual/database-cleanup>`__ reference documentation.
+     For more information, see `database cleanup <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-manual/database-cleanup>`__ in the documentation for CodeQL CLI.
 
 Comparing query results
 ------------------------

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

@@ -5,6 +5,8 @@
 Customizing settings
 ====================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 You can edit the settings for the CodeQL extension to suit your needs.
 
 About CodeQL extension settings
@@ -39,7 +41,7 @@ Changing the labels of query history items
 
 The query history **Format** setting controls how the extension lists queries in the query history. By default, each item has a label with the following format::
     
-    %q on %d - %s, %r result count [%t]
+    %q on %d - %s %r [%t]
 
 - ``%q`` is the query name
 - ``%d`` is the database name
@@ -107,12 +109,25 @@ You can also edit the items shown in the Variant Analysis Repositories panel by
 
 You can change the items shown in the panel or add new items by directly editing this file.
 
+Configuring settings for adding databases
+------------------------------------------------
+
+To automatically add database source folders to your workspace, you can enable the **Adding Databases > Add Database Source to Workspace** setting.
+
+This setting is disabled by default. You may want to enable the setting if you regularly browse the source code of databases, for example to view the abstract syntax tree of the code. For more information, see ":ref:`Exploring the structure of your source code <exploring-the-structure-of-your-source-code>`."
+
+.. pull-quote:: Note
+
+   If you are in a single-folder workspace, adding database source folders will cause the workspace to reload as a multi-root workspace. This may cause query history and database lists to be reset.
+
+   Before enabling this setting, we recommend that you save your workspace as a multi-root workspace. For more information, see "`Multi-root Workspaces <https://code.visualstudio.com/docs/editor/multi-root-workspaces>`__" in the Visual Studio Code help.
+
 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.
 
-To pass additional arguments to the CodeQL CLI when running tests, you can update the **Running Tests > Additional Test Arguments** setting. For more information about the available arguments, see "`test run <https://codeql.github.com/docs/codeql-cli/manual/test-run/>`_" in the CodeQL CLI help. 
+To pass additional arguments to the CodeQL CLI when running tests, you can update the **Running Tests > Additional Test Arguments** setting. For more information about the available arguments, see `test run <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-manual/test-run/>`_ in the documentation for CodeQL CLI. 
 
 Configuring settings for telemetry and data collection
 --------------------------------------------------------

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

@@ -5,6 +5,8 @@
 Exploring data flow with path queries
 =====================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 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.
 
 About path queries

docs/codeql/codeql-for-visual-studio-code/exploring-the-structure-of-your-source-code.rst

@@ -5,6 +5,8 @@
 Exploring the structure of your source code
 =================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 You can use the AST viewer to display the abstract syntax tree of a CodeQL database.
 
 About the abstract syntax tree
@@ -18,20 +20,26 @@ CodeQL for Visual Studio Code contains an AST viewer. The viewer consists of a g
 Viewing the abstract syntax tree of a source file
 --------------------------------------------------
 
-1. Open a source file from a CodeQL database. For example, you can navigate to a source file in the File Explorer.
+1. Open the CodeQL Databases view and right-click the database that you want to explore. Click **Add Database Source to Workspace**.
+
+   .. image:: ../images/codeql-for-visual-studio-code/add-database-source-to-workspace.png
+      :width: 350
+      :alt: Add database source to workspace
+
+2. Navigate to a CodeQL database's source file in the File Explorer.
 
    .. image:: ../images/codeql-for-visual-studio-code/open-source-file.png
       :width: 350
       :alt: Open a source file
 
-2. Run **CodeQL: View AST** from the Command Palette. This runs a CodeQL query (usually called ``printAST.ql``) over the active file, which may take a few seconds.
+3. Run **CodeQL: View AST** from the Command Palette. This runs a CodeQL query (usually called ``printAST.ql``) over the active file, which may take a few seconds.
    
    .. pull-quote:: Note
 
       If you don't have an appropriate ``printAST.ql`` query in your workspace, the **CodeQL: View AST** command won't work. To fix this, you can update your copy of the `CodeQL <https://github.com/github/codeql>`__ repository from ``main``. If you do this, you may need to upgrade your databases. Also, query caches may be discarded and your next query runs could be slower.
 
-3. Once the query has run, the AST viewer displays the structure of the source file.
-4. To see the nested structure, click the arrows and expand the nodes.
+4. Once the query has run, the AST viewer displays the structure of the source file.
+5. To see the nested structure, click the arrows and expand the nodes.
 
    .. image:: ../images/codeql-for-visual-studio-code/explore-ast.png
       :alt: Explore the AST

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

@@ -3,6 +3,8 @@
 CodeQL for Visual Studio Code
 =============================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 The CodeQL extension for Visual Studio Code adds rich language support for CodeQL and allows you to easily find problems in codebases.
 
 - :doc:`About CodeQL for Visual Studio Code
@@ -37,7 +39,10 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
   CodeQL queries using the Visual Studio Code extension.
 
 - :doc:`Working with CodeQL packs in Visual Studio Code
-  <working-with-codeql-packs-in-visual-studio-code>`: You can view and edit CodeQL packs in Visual Studio Code.
+  <working-with-codeql-packs-in-visual-studio-code>`: You can view, create, and edit all types of CodeQL pack in Visual Studio Code.
+
+- :doc:`Using the CodeQL model editor
+  <using-the-codeql-model-editor>`: You can view, create, and edit CodeQL model packs using a dedicated editor.
 
 - :doc:`Customizing settings
   <customizing-settings>`: You can edit the settings for the 
@@ -67,6 +72,7 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
    running-codeql-queries-at-scale-with-mrva
    testing-codeql-queries-in-visual-studio-code
    working-with-codeql-packs-in-visual-studio-code
+   using-the-codeql-model-editor
    customizing-settings
    troubleshooting-codeql-for-visual-studio-code
    troubleshooting-variant-analysis

docs/codeql/codeql-for-visual-studio-code/running-codeql-queries-at-scale-with-mrva.rst

@@ -5,6 +5,8 @@
 Running CodeQL queries at scale with multi-repository variant analysis
 ======================================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 .. include:: ../reusables/beta-note-mrva.rst
 
 About multi-repository variant analysis
@@ -23,7 +25,7 @@ If you want to run variant analysis on your repositories, you need to enable cod
 Setting a controller repository for variant analysis
 ----------------------------------------------------
 
-When you run variant analysis, the analysis is run entirely using GitHub Actions. You don't need to create any workflows, but you must specify which GitHub repository the CodeQL extension should use as the "controller repository." Controller repositories can be empty, but they must have at least one commit. The ``GITHUB_TOKEN`` must also have "Read and write permissions" to run workflows in that repository. For more information, see "`Managing GitHub Actions settings for a repository <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository>`__."
+When you run variant analysis, the analysis is run entirely using GitHub Actions. You don't need to create any workflows, but you must specify which GitHub repository the CodeQL extension should use as the "controller repository." Controller repositories can be empty, but they must have at least one commit. 
 
 .. pull-quote::
    
@@ -85,7 +87,6 @@ For each repository, you can see:
 - Visibility of the repository
 - Whether analysis is still running (black, moving circle) or finished (green checkmark)
 - Number of stars the repository has on GitHub
-- When the repository was last updated
 
 To see the results for a repository:
 
@@ -153,6 +154,36 @@ For example, if you want to continue analyzing a set of repositories that had re
 
 You can then insert the ``new-repo-list`` of repositories into your list of custom repository lists for easy access in the Variant Analysis Repositories panel.
 
+Using GitHub code search to add repositories to a custom list 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use code search directly in the CodeQL extension to add a subset of repositories from GitHub.com to a custom list. 
+
+.. pull-quote::
+
+    Note
+
+    This feature uses the legacy code search via the code search API. For more information on the syntax to use, see "`Searching code (legacy) <https://docs.github.com/en/search-github/searching-on-github/searching-code>`__."
+
+For example, to add all repositories in the ``rails`` organization on GitHub, you can search ``org:rails``. 
+
+You can add a maximum of 1000 repositories to a custom list per search. 
+
+#. In the Variant Analysis Repositories panel, choose the list that you want to add repositories to. You can create a new list or choose an existing list that already contains repositories.
+
+#. Right-click on the list you have chosen and then click **Add repositories with GitHub Code Search**. 
+
+#. In the pop-up that appears at the top of the application, under the search bar, select a language for your search from the choices in the dropdown. 
+
+    .. image:: ../images/codeql-for-visual-studio-code/variant-analysis-code-search-language.png
+        :alt: Screenshot of the search bar for using code search to add repositories to a custom list. The search bar asks you to choose a language for your search and has a dropdown list of languages to choose from.
+
+#. In the search bar, type the search query that you want to use and press **Enter**.
+
+You can view the progress of your search in the bottom right corner of the application in a box with the text "Searching for repositories...". If you click **Cancel**, no repositories will be added to your list. Once complete, you will see the resulting repositories appear in the dropdown under your custom list in the Variant Analysis Repositories panel.
+
+Some of the resulting repositories will not have CodeQL databases and some may not allow access by the CodeQL extension for Visual Studio Code. When you run an analysis on the list, the Variant Analysis Results view will show you which repositories were analyzed, which denied access, and which had no CodeQL database.
+
 Troubleshooting variant analysis
 --------------------------------
 

docs/codeql/codeql-for-visual-studio-code/setting-up-codeql-in-visual-studio-code.rst

@@ -5,6 +5,8 @@
 Setting up CodeQL in Visual Studio Code
 =================================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 You can install and configure the CodeQL extension in Visual Studio Code.
 
 .. include:: ../reusables/license-note.rst
@@ -74,6 +76,8 @@ To use the starter workspace:
 
 #. In VS Code, use the **File** > **Open Workspace from File** option to open the ``vscode-codeql-starter.code-workspace`` file from your checkout of the workspace repository.
 
+Remember to update the ``ql`` submodule in the starter workspace periodically to ensure that it remains compatible with newer versions of the VS Code extension and the CodeQL CLI.
+
 .. _existing-workspace:
 
 Updating an existing workspace for CodeQL

docs/codeql/codeql-for-visual-studio-code/testing-codeql-queries-in-visual-studio-code.rst

@@ -5,6 +5,8 @@
 Testing CodeQL queries in Visual Studio Code
 ============================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 You can run unit tests for CodeQL queries using the Visual Studio Code extension. When you are sure that your query finds the results you want to identify, you can use variant analysis to run it at scale. 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>`."
 
 About testing queries in VS Code
@@ -12,27 +14,31 @@ About testing queries in VS Code
 
 To ensure that your CodeQL queries produce the expected results, you can run tests that compare the expected query results with the actual results.
 
-The CodeQL extension automatically prompts VS Code to install the Test Explorer extension as a dependency. The Test Explorer displays any workspace folders with a name ending in ``-tests`` and provides a UI for exploring and running tests in those folders.
+The CodeQL extension automatically registers itself with the **Testing** view. The **Testing** view displays all tests found in your current workspace and provides a UI for exploring and running tests in your workspace.
 
 For more information about how CodeQL tests work, see "`Testing custom queries <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries>`__" in the CLI help.
 
 Testing the results of your queries
 -----------------------------------
 
-1. Open the Test Explorer view in the sidebar.
+1. Open the **Testing** view in the sidebar.
 
-   .. image:: ../images/codeql-for-visual-studio-code/open-test-explorer.png
+   .. image:: ../images/codeql-for-visual-studio-code/open-testing-view.png
       :width: 350
-      :alt: Open the Test Explorer view
+      :alt: Open the Testing view
 
 2. To run a specific test, hover over the file or folder name and click the play button. To run all tests in your workspace, click the play button at the top of the view. If a test takes too long to run, you can click the stop button at the top of the view to cancel the test.
-3. The icons show whether a test passed or failed. If it failed, right-click the failed test and click **CodeQL: Show Test Output Differences** to display the differences between the expected output and the actual output.
+3. The icons show whether a test passed or failed. If it failed, click the test in the **Test Results** panel to display the differences between the expected output and the actual output.
 
-   .. image:: ../images/codeql-for-visual-studio-code/show-test-diff.png
+   .. image:: ../images/codeql-for-visual-studio-code/test-results-panel.png
+      :width: 800
+      :alt: View the Test Results panel
+
+4. Compare the results. If you want to update the test with the actual output, right-click the test in the **Testing** view and click **Accept Test Output**.
+
+   .. image:: ../images/codeql-for-visual-studio-code/accept-test-output.png
       :width: 400
-      :alt: Show test output differences
-
-4. Compare the results. If you want to update the test with the actual output, click **CodeQL: Accept Test Output**.
+      :alt: Acccept test output in the Testing view
 
 Monitoring the performance of your queries
 ------------------------------------------

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

@@ -5,6 +5,8 @@
 Troubleshooting CodeQL for Visual Studio Code
 =============================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 This article explains how to debug problems with the analysis of CodeQL databases that are stored on your local
 machine. For information on troubleshooting variant analysis, which runs on GitHub.com, see
 ":ref:`Troubleshooting variant analysis <troubleshooting-variant-analysis>`."

docs/codeql/codeql-for-visual-studio-code/troubleshooting-variant-analysis.rst

@@ -5,6 +5,8 @@
 Troubleshooting variant analysis
 ================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 .. include:: ../reusables/beta-note-mrva.rst
 
 This article explains how to debug problems with variant analysis, that is, analysis run using GitHub Actions
@@ -24,7 +26,7 @@ If there are problems with the variant analysis run, you will see a warning bann
 
 .. image:: ../images/codeql-for-visual-studio-code/variant-analysis-results-warning.png
     :width: 600
-    :alt: Screenshot of the "Variant Analysis Results" view showing a warning banner with the text "warning: Problem with controller repository" and "Publicly visible controller repository can't be used to analyze private repositories. 1 private repository was not analyzed." The "Show logs" button is highlighted with a dark orange outline.
+    :alt: Screenshot of the "Variant Analysis Results" view showing a warning banner with the text "warning: Problem with controller repository" and "Publicly visible controller repository can't be used to analyze private repositories. 1 private repository was not analyzed." The "View logs" button is highlighted with a dark orange outline.
 
 In this example, the user ran variant analysis on a custom list of two repositories. One of the repositories was a private repository and could not be analyzed because they had a public controller repository. Only the public repository was analyzed. To analyze both repositories, this user needs to edit their settings and update the controller repository to a private repository. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
 

docs/codeql/codeql-for-visual-studio-code/using-the-codeql-model-editor.rst

@@ -0,0 +1,169 @@
+:tocdepth: 1
+
+.. _using-the-codeql-model-editor:
+
+Using the CodeQL model editor
+=============================
+
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
+.. include:: ../reusables/beta-note-model-pack-editor-vsc.rst
+
+You can view, write, and edit CodeQL packs in Visual Studio Code using the CodeQL extension. The model editor is designed to help you model external dependencies of your codebase that are not supported by the standard CodeQL Libraries.
+
+About the CodeQL model editor
+-----------------------------
+
+The CodeQL model editor guides you through modeling the calls to external dependencies in your application or fully modeling all the public entry and exit points in an external dependency.
+
+When you open the model editor, it analyzes the currently selected CodeQL database and identifies where the application uses external APIs and all public methods. An external (or third party) API is any API that is not part of the CodeQL database you have selected.
+
+The model editor has two different modes:
+
+- **Application mode (default view):** The editor lists each external framework used by the selected CodeQL database. When you expand a framework, a list of all calls to and from the external API is shown with the options available to model dataflow through each call. This mode is most useful for improving the CodeQL results for a specific codebase.
+
+- **Dependency mode:** The editor identifies all of the publicly accessible APIs in the selected CodeQL database. This view guides you through modeling each public API that the codebase makes available. When you have finished modeling the entire API, you can save the model and use it to improve the CodeQL analysis for all codebases that use the dependency.
+
+Displaying the CodeQL model editor
+----------------------------------
+
+#. Open your CodeQL workspace in VS Code, for example, the ``vscode-codeql-starter`` workspace.
+   If you haven't updated the ``ql`` submodule for a while, update it from ``main`` to ensure that you have the queries used to gather data for the model editor.
+#. Open the CodeQL extension and select the CodeQL database that you want to model from the "Databases" section of the left side pane.
+#. In the left side panel, expand the "CodeQL method modeling" section and click **Start modeling** to display the model editor. Alternatively, use the command palette to run the “CodeQL: Open Model Editor (Beta)” command.
+#. The CodeQL model editor runs a series of telemetry queries to identify APIs in the code and the editor is displayed in a new tab.
+#. When the telemetry queries are complete, the APIs that have been identified are shown in the editor.
+
+.. pull-quote:: Tip
+
+   The "CodeQL method modeling" section is a view that you can move from the primary sidebar to the secondary sidebar, when you want more space while you are modeling calls or methods. If you close the view, you can reopen it from the "Open Views" option in the **View** menu.
+
+Modeling the calls your codebase makes to external APIs
+-------------------------------------------------------
+
+You typically use this approach when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is useful when the codebase uses frameworks or libraries that are not supported by CodeQL and if the source code of the framework or library is not included in the analysis.
+
+This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling calls to external APIs written in other static languages is similar.
+
+#. Select the CodeQL database that you want to improve CodeQL coverage for.
+#. Display the CodeQL model editor. By default the editor runs in application mode, so the list of external APIs used by the selected codebase is shown.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode.png
+      :width: 800
+      :alt: Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing two of the external Java frameworks used by the "sofa-jraft" codebase.
+
+#. Click to expand an external API and view the list of calls from the codebase to the external dependency.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode-expanded.png
+      :width: 800
+      :alt: Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing the calls to the "rocksdbjni" framework ready for modeling. The "View" option for the first call is highlighted with a dark orange outline.
+
+#. Click **View** associated with an API call or method to show where it is used in your codebase.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode-view-code.png
+      :width: 800
+      :alt: Screenshot of a file showing a place where your codebase calls the API is highlighted with a dark orange outline.
+
+#. The file containing the first call from your codebase to the API is opened and a "CodeQL methods usage" view is displayed in the VS Code Panel (where the "Problems" and "Terminal" views are usually displayed). The "CodeQL methods usage" view lists of all the calls from your code to the API, grouped by method. You can click through each use to decide how to model your use of the method.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode-view-list.png
+      :width: 800
+      :alt: Screenshot of the "CodeQL methods usage" view. The currently displayed call to an external method is highlighted blue.
+
+#. When you have determined how to model your use of the method, you can define the **Model type** in the "CodeQL method modeling" tab of the CodeQL extension. This change is automatically reflected in the main model editor.
+#. The remaining fields are updated with available options:
+
+   - **Source**: choose the **Output** element to model.
+   - **Sink**: choose the **Input** element to model.
+   - **Flow summary**: choose the **Input** and **Output** elements to model.
+
+#. Define the **Kind** of dataflow for the model.
+#. When you have finished modeling, display the main model editor and click **Save all** or **Save** (shown at the bottom right of each expanded list of methods). The percentage of methods modeled in the editor is updated.
+
+The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-pack>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL. For more information, see "`Using CodeQL model packs with code scanning <#using-codeql-model-packs-with-code-scanning>`__".
+
+The models are stored in a series of YAML data extension files, one for each external API. For example:
+
+.. code-block:: none
+
+   .github/codeql/extensions/sofa-jraft-java # the model pack directory
+      models
+         jmh-core.model.yml                  # models calls to jmh-core@1.20
+         rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3
+
+Modeling the public API of a codebase
+-------------------------------------
+
+This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling the public API written using other static languages is similar.
+
+You typically use this method when you want to model a framework or library that your organization uses in more than one codebase. Once you have finished creating and testing the model, you can publish the CodeQL model pack to the GitHub Container Registry for your whole organization to use.
+
+#. Select the CodeQL database that you want to model.
+#. Display the CodeQL model editor. By default the editor runs in application mode. Click **Model as dependency** to display dependency mode. The screen changes to show the public API of the framework or library.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing three of the packages published by the "sofa-jraft" codebase.
+
+#. Click to expand a package and view the list of available methods.
+#. Click **View** associated with a method to show its definition.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode-expanded.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing the public methods available in the "com.alipay.soft.jraft.option" package ready for modeling. The "View" option for the first method is highlighted with a dark orange outline.
+
+#. When you have determined how to model the method, define the **Model type**.
+#. The remaining fields are updated with available options:
+
+   - **Source**: choose the **Output** element to model.
+   - **Sink**: choose the **Input** element to model.
+   - **Flow summary**: choose the **Input** and **Output** elements to model.
+
+#. Define the **Kind** of dataflow for the model.
+#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
+
+The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-pack>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL. For more information, see "`Using CodeQL model packs with code scanning <#using-codeql-model-packs-with-code-scanning>`__".
+
+The models are stored in a series of YAML data extension files, one for each public method. For example:
+
+.. code-block:: none
+
+   .github/codeql/extensions/sofa-jraft-java          # the model pack directory
+      models
+         com.alipay.sofa.jraft.option.model.yml       # models public methods in package
+         com.alipay.sofa.jraft.rhea.options.model.yml # models public methods in package
+
+The editor will create a separate model file for each package that you model.
+
+Modeling methods with multiple potential flows
+----------------------------------------------
+
+Some methods support more than one data flow. It is important to model all the data flows for a method, otherwise you cannot detect all the potential problems associated with using the method. First you model one data flow for the method, and then use the **+** button in the method row to specify a second data flow model.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode-plus.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing one model for the ``com.alipay.sofa.jraft.option.BallotBoxOptions.getClosureQueue()`` method. The "+" button is outlined in dark orange. Click this button to create a second model for the method.
+
+Testing CodeQL model packs in VS Code
+-------------------------------------
+
+You can test any CodeQL model packs you create in VS Code by turning the "use model packs" setting on and off. This method works for both databases and for variant analysis repositories.
+
+- To run queries on a CodeQL database with any model packs that are stored within the ``.github/codeql/extensions`` directory of the workspace, update your ``settings.json`` file with: ``"codeQL.runningQueries.useExtensionPacks": "all",``
+- To run queries on a CodeQL database without using model packs, update your ``settings.json`` file with: ``"codeQL.runningQueries.useExtensionPacks": "none",``
+
+If your model is working well, you should see a difference in the results of the two different runs. If you don't see any differences in results, you may need to introduce a known bug to verify that the model behaves as expected.
+
+Using CodeQL model packs with code scanning
+-------------------------------------------
+
+There are two methods for using CodeQL model packs with code scanning:
+
+#. Copy the model pack directory into the ``.github/codeql/extensions`` directory of the repository. It will automatically be used by all future code scanning analysis for the repository (default setup or advanced setup).
+#. Publish the model pack to the GitHub Container Registry as a CodeQL model pack. This can be downloaded and used by advanced setup for code scanning or by the CodeQL CLI running in an external CI system.
+
+For more information, see the following articles on the GitHub Docs site:
+
+- Default setup of code scanning: `Extending CodeQL coverage with CodeQL model packs in default setup <https://docs.github.com/en/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup>`__
+- Advanced setup of code scanning: `Extending CodeQL coverage with CodeQL model packs <https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs>`__
+- CodeQL CLI setup in external CI system: `Using model packs to analyze calls to custom dependencies <https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies>`__

docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst

@@ -5,35 +5,53 @@
 Working with CodeQL packs in Visual Studio Code
 ===============================================
 
+.. include:: ../reusables/vs-code-deprecation-note.rst
+
 .. include:: ../reusables/beta-note-package-management.rst
 
-You can view CodeQL packs and write and edit queries for them in Visual Studio Code. 
+You can view, write, and edit all types of CodeQL packs in Visual Studio Code using the CodeQL extension. 
 
 About CodeQL packs
 ------------------
-CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. You can publish your own CodeQL packs and download packs created by others. For more information, see "`About CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs>`__."
+You use CodeQL packs to share your expertise in query writing, CodeQL library development, and modeling dependencies with other users. The CodeQL package management system ensures that when you publish a CodeQL pack it is ready to use, without any compilation. Anything the CodeQL pack depends on is explicitly defined within the pack. You can publish your own CodeQL packs and download packs created by others. For more information, see "`About CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs>`__."
 
-Using standard CodeQL packs in Visual Studio Code
---------------------------------------------------------------
+There are three types of CodeQL packs, each with a specific purpose.
+
+- Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and pre-compiled representations of each query, in addition to the query sources. This ensures consistent and efficient execution of the queries in the pack.
+- Model packs are used to model dependencies that are not supported by the standard CodeQL libraries. When you add a model pack to your analysis, all relevant queries also recognize the sources, sinks and flow steps of the dependencies defined in the pack.
+- Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled separately.
+
+Using the CodeQL packs shipped with the CLI in Visual Studio Code
+-----------------------------------------------------------------
 To install dependencies for a CodeQL pack in your Visual Studio Code workspace, run the **CodeQL: Install Pack Dependencies** command from the Command Palette and select the packs you want to install dependencies for.
 
 You can write and run query packs that depend on the CodeQL standard libraries, without needing to check out the standard libraries in your workspace. Instead, you can install only the dependencies required by the query packs you want to use.
 
-Creating and editing CodeQL packs in Visual Studio Code
--------------------------------------------------------
-To create a new CodeQL pack, you will need to use the CodeQL CLI from a terminal, which you can do within Visual Studio Code or outside of it with the ``codeql pack init`` command. Once you create an empty pack, you can edit the ``qlpack.yml`` file or run the ``codeql pack add`` command to add dependencies or change the name or version. For more information, see "`Creating and working with CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs>`__."
+Working with CodeQL query packs
+-------------------------------
+
+One of the main benefits of working with a CodeQL query pack is that all dependencies are resolved, not just those defined within the query and standard libraries.
+
+Creating and editing CodeQL query packs 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To create a new query pack, you will need to use the CodeQL CLI from a terminal, which you can do within Visual Studio Code or outside of it with the ``codeql pack init`` command. Once you create an empty pack, you can edit the ``qlpack.yml`` file or run the ``codeql pack add`` command to add dependencies or change the name or version. For detailed information, see "`Creating and working with CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs>`__."
 
 You can create or edit queries in a CodeQL pack in Visual Studio Code as you would with any CodeQL query, using the standard code editing features such as autocomplete suggestions to find elements to use from the pack's dependencies. 
 
-You can then use the CodeQL CLI to publish your pack to share with others. For more information, see "`Publishing and using CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs>`__."
+You can then use the CodeQL CLI to publish your pack to share with others. For detailed information, see "`Publishing and using CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs>`__."
 
-Viewing CodeQL packs and their dependencies in Visual Studio Code
------------------------------------------------------------------
-To download a CodeQL pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette.
-You can download all the core CodeQL query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java or Kotlin, enter ``codeql/java-queries``.
+Viewing CodeQL query packs and their dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To download a query pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette.
+You can download all the core query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java and Kotlin, enter ``codeql/java-queries``.
 
 Whether you have downloaded a CodeQL pack or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on.
 
 If you want to understand a query in a CodeQL pack better, you can open the query file and view the code, using the IntelliSense code editing features of Visual Studio Code. For example, if you hover over an element from a library depended on by the pack, Visual Studio Code will resolve it so you can see documentation about the element. 
 
 To view the full definition of an element of a query, you can right-click and choose **Go to Definition**. If the library pack is present within the same Visual Studio Code workspace, this will take you to the definition within the workspace. Otherwise it will take you to the definition within your package cache, the shared location where downloaded dependencies are stored, which is in your home directory by default.
+
+Working with CodeQL model packs
+-------------------------------
+
+The CodeQL extension for Visual Studio Code includes a dedicated editor for creating and editing model packs. For information on using the model editor, see ":ref:`Using the CodeQL model editor <using-the-codeql-model-editor>`."