diff --git a/docs/codeql/codeql-language-guides/basic-query-for-csharp-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-csharp-code.rst index b8749d1c3f8..18c76ed4f52 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-csharp-code.rst +++ b/docs/codeql/codeql-language-guides/basic-query-for-csharp-code.rst @@ -112,7 +112,7 @@ 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. diff --git a/docs/codeql/codeql-language-guides/basic-query-for-go-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-go-code.rst index 6280cec234f..b15e2224065 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-go-code.rst +++ b/docs/codeql/codeql-language-guides/basic-query-for-go-code.rst @@ -113,7 +113,7 @@ 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. diff --git a/docs/codeql/codeql-language-guides/basic-query-for-java-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-java-code.rst index a6b0f9ac9fb..017067e0094 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-java-code.rst +++ b/docs/codeql/codeql-language-guides/basic-query-for-java-code.rst @@ -31,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 `__. +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 `__.) - - .. 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 +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 `__ - - .. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,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 `__ - 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:: hhttps://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. \ No newline at end of file diff --git a/docs/codeql/codeql-language-guides/basic-query-for-javascript-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-javascript-code.rst index 123336d699e..230d8016510 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-javascript-code.rst +++ b/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 `__. +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 `__.) - - .. 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 view the expression in the code viewer. - .. 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 `__ - - .. 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 `__: +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. \ No newline at end of file diff --git a/docs/codeql/codeql-language-guides/basic-query-for-python-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-python-code.rst index f8424b00d4e..4c727082ec5 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-python-code.rst +++ b/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,31 @@ The query we're going to run performs a basic search of the code for ``if`` stat if error: pass -Running the query ------------------ +Running a quick query +--------------------- -#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching `__. +.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst -#. Click the project in the search results. - -#. Click **Query this project**. - - This opens the query console. (For information about using this, see `Using the 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 view the ``if`` statement in the code viewer. - .. 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 `__ - - .. 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 +104,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 `__ - 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. \ No newline at end of file diff --git a/docs/codeql/codeql-language-guides/basic-query-for-ruby-code.rst b/docs/codeql/codeql-language-guides/basic-query-for-ruby-code.rst index 4acc85e6a85..14c65b445a0 100644 --- a/docs/codeql/codeql-language-guides/basic-query-for-ruby-code.rst +++ b/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,12 @@ 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 ------------------ +Running a quick query +--------------------- -#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching `__. +.. include:: ../reusables/vs-code-basic-instructions/run-quick-query-1.rst -#. Click the project in the search results. - -#. Click **Query this project**. - - This opens the query console. (For information about using this, see `Using the 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 +30,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 view the ``if`` statement in the code viewer. - .. 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 `__ - - .. 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 +104,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 `__ - 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. diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-1.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-1.png new file mode 100644 index 00000000000..e32ce790d77 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-1.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-2.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-2.png new file mode 100644 index 00000000000..48057a6035a Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-java-query-results-2.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-1.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-1.png new file mode 100644 index 00000000000..1f989279759 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-1.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-2.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-2.png new file mode 100644 index 00000000000..59d38f8a2eb Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-2.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-3.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-3.png new file mode 100644 index 00000000000..97f2df4dac8 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-js-query-results-3.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-1.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-1.png new file mode 100644 index 00000000000..84e5dee757c Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-1.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-2.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-2.png new file mode 100644 index 00000000000..d92f8e3000f Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-python-query-results-2.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-1.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-1.png new file mode 100644 index 00000000000..13d5e137baf Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-1.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-2.png b/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-2.png new file mode 100644 index 00000000000..f4f3393dc58 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/basic-ruby-query-results-2.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-java.png b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-java.png new file mode 100644 index 00000000000..68ea2ba4914 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-java.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-js.png b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-js.png new file mode 100644 index 00000000000..4e066bfbf46 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-js.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-python.png b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-python.png new file mode 100644 index 00000000000..195d401d6a7 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-python.png differ diff --git a/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-ruby.png b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-ruby.png new file mode 100644 index 00000000000..25819aec141 Binary files /dev/null and b/docs/codeql/images/codeql-for-visual-studio-code/quick-query-tab-ruby.png differ