Merge pull request #11468 from github/felicitymay-8441-basic-query-2

LGTM deprecation: Update basic queries to use VS Code

docs/codeql/codeql-language-guides/basic-query-for-cpp-code.rst

@@ -3,7 +3,9 @@
 Basic query for C and C++ code
 ==============================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -14,62 +16,33 @@ The query we're going to run performs a basic search of the code for ``if`` stat
 
    if (error) { }
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **C/C++** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import cpp``.
 
    .. code-block:: ql
 
-      import cpp
-
       from IfStmt ifstmt, BlockStmt block
       where ifstmt.getThen() = block and
         block.getNumStmt() = 0
       select ifstmt, "This 'if' statement is redundant."
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-cpp-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``ifstmt`` column to open the file and highlight the matching ``if`` statement.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-cpp-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/4242591143131494898/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
-
-   The matching ``if`` statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -120,7 +93,7 @@ In this case, identifying the ``if`` statement with the empty ``then`` branch as
 
 To exclude ``if`` statements that have an ``else`` branch:
 
-#. Extend the ``where`` clause to include the following extra condition:
+#. Edit your query and extend the ``where`` clause to include the following extra condition:
 
    .. code-block:: ql
 
@@ -134,14 +107,24 @@ To exclude ``if`` statements that have an ``else`` branch:
         block.getNumStmt() = 0 and
         not ifstmt.hasElse()
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``if`` statements with an ``else`` branch are no longer reported.
 
-➤ `See this in the query console <https://lgtm.com/query/1899933116489579248/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/cpp-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: C/C++
+
+.. |language-code| replace:: ``cpp``
+
+.. |example-url| replace:: https://github.com/protocolbuffers/protobuf
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-cpp.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs.

docs/codeql/codeql-language-guides/basic-query-for-csharp-code.rst

@@ -3,7 +3,9 @@
 Basic query for C# code
 =======================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -14,62 +16,33 @@ The query we're going to run performs a basic search of the code for ``if`` stat
 
    if (error) { }
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **C#** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import csharp``.
 
    .. code-block:: ql
 
-      import csharp
-
       from IfStmt ifstmt, BlockStmt block
       where ifstmt.getThen() = block and
         block.isEmpty()
       select ifstmt, "This 'if' statement is redundant."  
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+ .. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-csharp-query-results-1.png
+    :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``ifstmt`` column to open the file and highlight the matching ``if`` statement.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-csharp-query-results-2.png
+    :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/1214010107827821393/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
-
-   The matching ``if`` statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -139,14 +112,23 @@ To exclude ``if`` statements that have an ``else`` branch:
         block.isEmpty() and
         not exists(ifstmt.getElse())
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``if`` statements with an ``else`` branch are no longer included.
 
-➤ `See this in the query console <https://lgtm.com/query/6233102733683510530/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/csharp-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+.. |language-text| replace:: C#
+
+.. |language-code| replace:: ``csharp``
+
+.. |example-url| replace:: https://github.com/PowerShell/PowerShell
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-csharp.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs.

docs/codeql/codeql-language-guides/basic-query-for-go-code.rst

@@ -3,7 +3,9 @@
 Basic query for Go code
 =======================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -22,29 +24,17 @@ This is problematic because the receiver argument is passed by value, not by ref
 
 For further information on using methods on values or pointers in Go, see the `Go FAQ <https://golang.org/doc/faq#methods_on_values_or_pointers>`__.
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **Go** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import go``.
 
    .. code-block:: ql
 
-      import go
-
       from Method m, Variable recv, Write w, Field f
       where
         recv = m.getReceiver() and
@@ -52,34 +42,17 @@ Running the query
         not recv.getType() instanceof PointerType
       select w, "This update to " + f + " has no effect, because " + recv + " is not a pointer."
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-go-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``w`` column to open the file and highlight the matching location.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-go-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to ``w``, which is the location in the source code where the receiver ``recv`` is modified. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/6221190009056970603/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``w`` column to view it in the code viewer.
-
-   The matching ``w`` is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -140,14 +113,24 @@ To exclude these values:
         not recv.getType() instanceof PointerType and
         not exists(ReturnStmt ret | ret.getExpr() = recv.getARead().asExpr())
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because value methods that return their receiver variable are no longer reported.
 
-➤ `See this in the query console <https://lgtm.com/query/9110448975027954322/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/go-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: Go
+
+.. |language-code| replace:: ``go``
+
+.. |example-url| replace:: https://github.com/go-gorm/gorm
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-go.png
+
+.. |result-col-1| replace:: The first column corresponds to ``w``, which is the location in the source code where the receiver ``recv`` is modified.

docs/codeql/codeql-language-guides/basic-query-for-java-code.rst

@@ -3,7 +3,9 @@
 Basic query for Java and Kotlin code
 ====================================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -29,65 +31,36 @@ or Kotlin code such as:
 In either case, replacing ``s.equals("")`` with ``s.isEmpty()``
 would be more efficient.
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **Java** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import java``.
 
    .. code-block:: ql
 
-      import java
-
-      from MethodAccess ma
-      where
-        ma.getMethod().hasName("equals") and
-        ma.getArgument(0).(StringLiteral).getValue() = ""
-      select ma, "This comparison to empty string is inefficient, use isEmpty() instead."
+        from MethodAccess ma
+        where
+            ma.getMethod().hasName("equals") and
+            ma.getArgument(0).(StringLiteral).getValue() = ""
+        select ma, "This comparison to empty string is inefficient, use isEmpty() instead."
 
    Note that CodeQL treats Java and Kotlin as part of the same language, so even though this query starts with ``import java``, it will work for both Java and Kotlin code.
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+ .. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-java-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``ma`` column to view the ``.equals`` expression in the code viewer.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-java-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ma`` and is linked to the location in the source code of the project where ``ma`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/6863787472564633674/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``ma`` column to view the ``.equals`` expression in the code viewer.
-
-   The matching ``.equals`` expression is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -148,14 +121,24 @@ In this case, it is not possible to simply use ``o.isEmpty()`` instead, as ``o``
         ma.getMethod().hasName("equals") and
         ma.getArgument(0).(StringLiteral).getValue() = ""
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``.equals`` expressions with different types are no longer included.
 
-➤ `See this in the query console <https://lgtm.com/query/3716567543394265485/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/java-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: Java
+
+.. |language-code| replace:: ``java``
+
+.. |example-url| replace:: https://github.com/apache/activemq
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-java.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``ma`` and is linked to the location in the source code of the project where ``ma`` occurs.

docs/codeql/codeql-language-guides/basic-query-for-javascript-code.rst

@@ -3,7 +3,9 @@
 Basic query for JavaScript code
 ===============================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -12,62 +14,33 @@ In JavaScript, any expression can be turned into an expression statement. While
 
 The query you will run finds instances of this problem. The query searches for expressions ``e`` that are pure—that is, their evaluation does not lead to any side effects—but appear as an expression statement.
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **JavaScript** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import javascript``.
 
    .. code-block:: ql
 
-      import javascript
-
       from Expr e
       where e.isPure() and
         e.getParent() instanceof ExprStmt
       select e, "This expression has no effect."
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-js-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click one of the links in the ``e`` column to open the file and highlight the matching expression.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-js-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``e`` and is linked to the location in the source code of the project where ``e`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/5137013631828816943/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click one of the links in the ``e`` column to view the expression in the code viewer.
-
-   The matching statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -119,11 +92,14 @@ To remove directives from the results:
         e.getParent() instanceof ExprStmt and 
         not e.getParent() instanceof Directive
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results as ``use strict`` directives are no longer reported.
 
-The improved query finds several results on the example project including `this result <https://lgtm.com/projects/g/ajaxorg/ace/rev/ad50673d7137c09d1a5a6f0ef83633a149f9e3d1/files/lib/ace/keyboard/vim.js#L320>`__:
+The improved query finds several results on the example project including the result below:
+
+.. image:: ../images/codeql-for-visual-studio-code/basic-js-query-results-1.png
+   :align: center
 
 .. code-block:: javascript
 
@@ -136,3 +112,15 @@ Further reading
 
 .. include:: ../reusables/javascript-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: JavaScript/TypeScript
+
+.. |language-code| replace:: ``javascript``
+
+.. |example-url| replace:: https://github.com/ajaxorg/ace
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-js.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``e`` and is linked to the location in the source code of the project where ``e`` occurs.

docs/codeql/codeql-language-guides/basic-query-for-python-code.rst

@@ -3,7 +3,9 @@
 Basic query for Python code
 ===========================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -14,62 +16,33 @@ The query we're going to run performs a basic search of the code for ``if`` stat
 
    if error: pass
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **Python** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete ``select ""`` and paste the following query beneath the import statement ``import python``.
 
    .. code-block:: ql
 
-      import python
-
       from If ifstmt, Stmt pass
       where pass = ifstmt.getStmt(0) and
         pass instanceof Pass
       select ifstmt, "This 'if' statement is redundant."
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-python-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``ifstmt`` column to open the file and highlight the matching ``if`` statement.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-python-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/3592297537117272922/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
-
-   The matching ``if`` statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -133,14 +106,24 @@ To exclude ``if`` statements that have an ``else`` branch:
         pass instanceof Pass and
         not exists(ifstmt.getOrelse())
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``if`` statements with an ``else`` branch are no longer included.
 
-➤ `See this in the query console <https://lgtm.com/query/3424727946018612474/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/python-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: Python
+
+.. |language-code| replace:: ``python``
+
+.. |example-url| replace:: https://github.com/saltstack/salt
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-python.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs.

docs/codeql/codeql-language-guides/basic-query-for-ruby-code.rst

@@ -3,7 +3,9 @@
 Basic query for Ruby code
 =========================
 
-Learn to write and run a simple CodeQL query.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/vs-code-basic-instructions/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -15,24 +17,14 @@ The query we're going to run performs a basic search of the code for ``if`` expr
    if error
      # Handle the error
 
-Running the query
------------------
+.. include:: ../reusables/vs-code-basic-instructions/find-database.rst
 
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Running a quick query
+---------------------
 
-#. Click the project in the search results.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst
 
-#. Click **Query this project**.
-
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
-
-   .. pull-quote::
-
-      Note
-
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **Ruby** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
+#. In the quick query tab, delete the content and paste in the following query.
 
    .. code-block:: ql
 
@@ -40,37 +32,20 @@ Running the query
 
       from IfExpr ifexpr
       where
-        not exists(ifexpr.getThen())
+      not exists(ifexpr.getThen())
       select ifexpr, "This 'if' expression is redundant."
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-2.rst
 
-#. Click **Run**.
+.. image:: ../images/codeql-for-visual-studio-code/basic-ruby-query-results-1.png
+   :align: center
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+If any matching code is found, click a link in the ``ifexpr`` column to open the file and highlight the matching ``if`` statement.
 
-   .. image:: ../images/query-progress.png
-       :align: center
+.. image:: ../images/codeql-for-visual-studio-code/basic-ruby-query-results-2.png
+   :align: center
 
-   .. pull-quote::
-
-      Note
-
-      Your query is always run against the most recently analyzed commit to the selected project.
-
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifexpr`` and is linked to the location in the source code of the project where ``ifexpr`` occurs. The second column is the alert message.
-
-   ➤ `Example query results <https://lgtm.com/query/4416853782037269427/>`__
-
-   .. pull-quote::
-
-      Note
-
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
-
-#. If any matching code is found, click a link in the ``ifexpr`` column to view the ``if`` statement in the code viewer.
-
-   The matching ``if`` expression is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. include:: ../reusables/vs-code-basic-instructions/note-store-quick-query.rst
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -131,14 +106,24 @@ To exclude ``if`` statements that have an ``else`` branch:
          not exists(ifexpr.getThen()) and
          not exists(ifexpr.getElse())
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``if`` expressions with an ``else`` branch are no longer included.
 
-➤ `See this in the query console <https://lgtm.com/query/4694253275631320752/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/ruby-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. Article-specific substitutions for the reusables used in docs/codeql/reusables/vs-code-basic-instructions
+
+.. |language-text| replace:: Ruby
+
+.. |language-code| replace:: ``ruby``
+
+.. |example-url| replace:: https://github.com/discourse/discourse
+
+.. |image-quick-query| image:: ../images/codeql-for-visual-studio-code/quick-query-tab-ruby.png
+
+.. |result-col-1|  replace:: The first column corresponds to the expression ``ifexpr`` and is linked to the location in the source code of the project where ``ifexpr`` occurs.

docs/codeql/reusables/vs-code-basic-instructions/find-database.rst

@@ -0,0 +1,23 @@
+Finding a CodeQL database to experiment with
+--------------------------------------------
+
+Before you start writing queries for |language-text| code, you need a CodeQL database to run them against. The simplest way to do this is to download a database for a repository that uses |language-text| directly from GitHub.com.
+
+#. In Visual Studio Code, click the **QL** icon |codeql-ext-icon| in the left sidebar to display the CodeQL extension. 
+
+#. Click **From GitHub** or the GitHub logo |github-db| at the top of the CodeQL extension to open an entry field.
+
+#. Copy the URL for the repository into the field and press the keyboard **Enter** key. For example, |example-url|.
+
+#. Optionally, if the repository has more than one CodeQL database available, select |language-code| to download the database created from the |language-text| code. 
+
+Information about the download progress for the database is shown in the bottom right corner of Visual Studio Code. When the download is complete, the database is shown with a check mark in the **Databases** section of the CodeQL extension (see screenshot below).
+
+.. |codeql-ext-icon| image:: ../images/codeql-for-visual-studio-code/codeql-extension-icon.png
+  :width: 20
+  :alt: Icon for the CodeQL extension.
+
+.. |github-db| image:: ../images/codeql-for-visual-studio-code/add-codeql-db-github.png
+  :width: 20
+  :alt: Icon for the CodeQL extension option to download a CodeQL database from GitHub.
+

docs/codeql/reusables/vs-code-basic-instructions/note-store-quick-query.rst

@@ -0,0 +1,5 @@
+.. pull-quote::
+
+   Note
+
+   If you want to move your experimental query somewhere more permanent, you need to move the whole ``Quick Queries`` directory. The directory is a CodeQL pack with a ``qlpack.yml`` file that defines the content as queries for |language-text| CodeQL databases. For more information about CodeQL packs, see ":ref:`Working with CodeQL packs in Visual Studio Code <working-with-codeql-packs-in-visual-studio-code>`."

docs/codeql/reusables/vs-code-basic-instructions/run-quick-query-1.rst

@@ -0,0 +1,7 @@
+The CodeQL extension for Visual Studio Code adds several **CodeQL:** commands to the command palette including **Quick Query**, which you can use to run a query without any set up.
+
+#. From the command palette in Visual Studio Code, select **CodeQL: Quick Query**.
+
+#. After a moment, a new tab *quick-query.ql* is opened, ready for you to write a query for your currently selected CodeQL database (here a |language-code| database). If you are prompted to reload your workspace as a multi-folder workspace to allow Quick queries, accept or create a new workspace using the starter workflow.
+
+   |image-quick-query|

docs/codeql/reusables/vs-code-basic-instructions/run-quick-query-2.rst

@@ -0,0 +1,7 @@
+4. Save the query in its default location (a temporary "Quick Queries" directory under the workspace for ``GitHub.vscode-codeql/quick-queries``).
+
+#. Right-click in the query tab and select **CodeQL: Run Query**. (Alternatively, run the command from the Command Palette.)
+
+   The query will take a few moments to return results. When the query completes, the results are displayed in a CodeQL Query Results view, next to the main editor view.
+
+   The query results are listed in two columns, corresponding to the expressions in the ``select`` clause of the query. |result-col-1| The second column is the alert message.

docs/codeql/reusables/vs-code-basic-instructions/setup-to-run-queries.rst

@@ -0,0 +1 @@
+For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."