Skip to content

Commit 8e8c43a

Browse files
shati-patelshati-patel
committed
Add basic query for JavaScript
1 parent 9edf164 commit 8e8c43a

File tree

2 files changed

+138
-1
lines changed

2 files changed

+138
-1
lines changed

‎docs/language/learn-ql/javascript/basic-query-javascript.rst

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
Basic query for JavaScript code
2+
===============================
3+
4+
Learn to write and run a simple CodeQL query using LGTM.
5+
6+
About the query
7+
---------------
8+
9+
In JavaScript, any expression can be turned into an expression statement. While this is sometimes convenient, it can be dangerous. For example, imagine a programmer wants to assign a new value to a variable ``x`` by means of an assignment ``x = 42``. However, they accidentally type two equals signs, producing the comparison statement ``x == 42``. This is valid JavaScript, so no error is generated. The statement simply compares ``x`` to ``42``, and then discards the result of the comparison.
10+
11+
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.
12+
13+
Running the query
14+
-----------------
15+
16+
#. 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>`__.
17+
18+
#. Click the project in the search results.
19+
20+
#. Click **Query this project**.
21+
22+
This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
23+
24+
.. pull-quote::
25+
26+
Note
27+
28+
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.
29+
30+
#. Copy the following query into the text box in the query console:
31+
32+
.. code-block:: ql
33+
34+
import javascript
35+
36+
from Expr e
37+
where e.isPure() and
38+
e.getParent() instanceof ExprStmt
39+
select e, "This expression has no effect."
40+
41+
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.
42+
43+
#. Click **Run**.
44+
45+
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:
46+
47+
.. image:: ../../images/query-progress.png
48+
:align: center
49+
50+
.. pull-quote::
51+
52+
Note
53+
54+
Your query is always run against the most recently analyzed commit to the selected project.
55+
56+
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.
57+
58+
➤ `Example query results <https://lgtm.com/query/5137013631828816943/>`__
59+
60+
.. pull-quote::
61+
62+
Note
63+
64+
An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
65+
66+
#. If any matching code is found, click one of the links in the ``e`` column to view the expression in the code viewer.
67+
68+
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.
69+
70+
About the query structure
71+
~~~~~~~~~~~~~~~~~~~~~~~~~
72+
73+
After the initial ``import`` statement, this simple query comprises three parts that serve similar purposes to the FROM, WHERE, and SELECT parts of an SQL query.
74+
75+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
76+
| Query part | Purpose | Details |
77+
+===============================================================+===================================================================================================================+========================================================================================================================+
78+
| ``import javascript`` | Imports the standard CodeQL libraries for JavaScript. | Every query begins with one or more ``import`` statements. |
79+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
80+
| ``from Expr e`` | Defines the variables for the query. | ``e`` is declared as a variable that ranges over expressions. |
81+
| | Declarations are of the form: | |
82+
| | ``<type> <variable name>`` | |
83+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
84+
| ``where e.isPure() and e.getParent() instanceof ExprStmt`` | Defines a condition on the variables. | ``e.isPure()``: The expression is side-effect-free. |
85+
| | | |
86+
| | | ``e.getParent() instanceof ExprStmt``: The parent of the expression is an expression statement. |
87+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
88+
| ``select e, "This expression has no effect."`` | Defines what to report for each match. | Report the expression with a string that explains the problem. |
89+
| | | |
90+
| | ``select`` statements for queries that are used to find instances of poor coding practice are always in the form: | |
91+
| | ``select <program element>, "<alert message>"`` | |
92+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
93+
94+
Extend the query
95+
----------------
96+
97+
Query writing is an inherently iterative process. You write a simple query and then, when you run it, you discover examples that you had not previously considered, or opportunities for improvement.
98+
99+
Remove false positive results
100+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101+
102+
Browsing the results of our basic query shows that it could be improved. Among the results you are likely to find ``use strict`` directives. These are interpreted specially by modern browsers with strict mode support and so these expressions *do* have an effect.
103+
104+
To remove directives from the results:
105+
106+
#. Extend the ``where`` clause to include the following extra condition:
107+
108+
.. code-block:: ql
109+
110+
and not e.getParent() instanceof Directive
111+
112+
The ``where`` clause is now:
113+
114+
.. code-block:: ql
115+
116+
where e.isPure() and
117+
e.getParent() instanceof ExprStmt and
118+
not e.getParent() instanceof Directive
119+
120+
#. Click **Run**.
121+
122+
There are now fewer results as ``use strict`` directives are no longer reported.
123+
124+
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>`__:
125+
126+
.. code-block:: javascript
127+
128+
point.bias == -1;
129+
130+
As written, this statement compares ``point.bias`` against ``-1`` and then discards the result. Most likely, it was instead meant to be an assignment ``point.bias = -1``.
131+
132+
Further reading
133+
---------------
134+
135+
.. include:: ../../reusables/javascript-further-reading.rst
136+
.. include:: ../../reusables/codeql-ref-tools-further-reading.rst

‎docs/language/learn-ql/javascript/ql-for-javascript.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
66
.. toctree::
77
:hidden:
88

9+
basic-query-javascript
910
introduce-libraries-js
1011
introduce-libraries-ts
1112
dataflow
@@ -14,7 +15,7 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
1415
ast-class-reference
1516
dataflow-cheat-sheet
1617

17-
- `Basic JavaScript query <https://lgtm.com/help/lgtm/console/ql-javascript-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
18+
- :doc:`Basic query for JavaScript code <basic-query-javascript>`: Learn to write and run a simple CodeQL query using LGTM.
1819

1920
- :doc:`CodeQL library for JavaScript <introduce-libraries-js>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
2021

0 commit comments

Comments
 (0)