hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-28 10:15:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1653 from felicity-semmle/learn-ql/SD-3690-vale-corrections

Browse Source 
Learn QL: corrections for issues found using Vale
This commit is contained in:
jf205
2019-07-30 16:43:40 +01:00
committed by GitHub
parent bf0201a36e 2060fdc581
commit 6d10731b8f
37 changed files with 287 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/ql-documentation/learn-ql/advanced/abstract-classes.rst
View File

@@ -10,7 +10,7 @@ A classic example where this approach is useful is when modeling ASTs (Abstract
Each value in a concrete class satisfies a particular logical property - the *characteristic predicate* (or *character* for short) of that class. This characteristic predicate consists of the conjunction (``and``) of its own body (if any) and the characteristic predicates of its superclasses.
For example, we could derive a subclass ``MainMethod`` from the standard QL class ``Method`` that contains precisely those Java functions called "main":
For example, we could derive a subclass ``MainMethod`` from the standard QL class ``Method`` that contains precisely those Java functions called ``"main"``:
.. code-block:: ql
@@ -33,7 +33,7 @@ Letting ``cp(C)`` denote the characteristic predicate of class ``C``, it is clea
cp(MainMethod) = cp(Method) and hasName("main")
That is, entities are "main" methods if and only if they are methods that are also called "main".
That is, entities are *main* methods if and only if they are methods that are also called ``"main"``.
Abstract classes
----------------

2
docs/ql-documentation/learn-ql/advanced/folding-predicates.rst
View File

@@ -16,7 +16,7 @@ Example
e1.getLocation().getStartLine() = e2.getLocation().getStartLine()
}
Here we are doing some lookups on ``Element``\ s. Going from ``Element -> File`` and ``Element -> Location -> StartLine`` are linear: there is only one ``File`` for each ``Element``, and one ``Location`` for each ``Element``, etc. However, as written it is difficult for the optimizer to pick out the best ordering here. We want to do the quick, linear parts first, and then join on the resultant larger tables, rather than joining first and then doing the linear lookups. We can precipitate this kind of ordering by rewriting the above predicate as follows:
Here we explore some lookups on ``Element``\ s. Going from ``Element -> File`` and ``Element -> Location -> StartLine`` are linear: there is only one ``File`` for each ``Element``, and one ``Location`` for each ``Element``, etc. However, as written it is difficult for the optimizer to pick out the best ordering here. We want to do the quick, linear parts first, and then join on the resultant larger tables, rather than joining first and then doing the linear lookups. We can precipitate this kind of ordering by rewriting the above predicate as follows:
.. code-block:: ql

4
docs/ql-documentation/learn-ql/advanced/monotonic-aggregates.rst
View File

@@ -42,7 +42,7 @@ For most usages, aggregates have very straightforward behavior. They can be thou
For every combination of values for the declared **variables**, for which the **range** holds, take one value of the **expression** and apply the **aggregation function** to the resulting values.
How does this work? Let us take the simple example given above of calculating the sum of your employees' salaries. Suppose that your employees are Alice, Ben and Charles, whose salaries are $30k, $40k, and $50k respectively. Then to calculate ``result``, we follow our recipe:
How does this work? Let us take the simple example given above of calculating the sum of your employees' salaries. Suppose that your employees are Alice, Ben, and Charles, whose salaries are $30k, $40k, and $50k respectively. Then to calculate ``result``, we follow our recipe:
+----------------------------------------------------------------+-------------------------------------+
| For every combination of values for the declared **variables** | Alice, Ben, Charles, Denis, Edna... |
@@ -192,7 +192,7 @@ Rank is a slightly unusual aggregate. It takes the possible values of the expres
where salary = rank[salaryRank](Employee e | managedByMe(e) | e.getSalary())
select salary, salaryRank
assigns, for each of my managees, their salary to ``salary``, and the rank of their salary to ``salaryRank``. In our running example, the results would be:
assigns, for each person I manage, their salary to ``salary``, and the rank of their salary to ``salaryRank``. In our running example, the results would be:
+------------+----------------+
| ``salary`` | ``salaryRank`` |

2
docs/ql-documentation/learn-ql/beginner/find-thief-1.rst
View File

@@ -45,7 +45,7 @@ There is too much information to search through by hand, so you decide to use yo
#. Select a language and a demo project. For this tutorial, any language and project will do.
#. Delete the default code ``import <language> select "hello world"``.
QL Libraries
QL libraries
------------
We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.

2
docs/ql-documentation/learn-ql/beginner/find-thief-2.rst
View File

@@ -1,7 +1,7 @@
Find the thief: Start the search
================================
The villagers answered "yes" to the question "Is the thief taller than 150cm?". To use this information, you can write the following query to list all villagers taller than 150cm. These are all possible suspects.
The villagers answered "yes" to the question "Is the thief taller than 150cm?" To use this information, you can write the following query to list all villagers taller than 150cm. These are all possible suspects.
.. code-block:: ql

2
docs/ql-documentation/learn-ql/beginner/fire-1.rst
View File

@@ -55,7 +55,7 @@ The expression ``southern(this)`` defines the logical property represented by th
Note
If you are familiar with object-oriented programming languages, you might be tempted to think of the characteristic predicate as a "constructor". However, this is **not** the case - it is a logical property which does not create any objects.
If you are familiar with object-oriented programming languages, you might be tempted to think of the characteristic predicate as a *constructor*. However, this is **not** the case - it is a logical property which does not create any objects.
You always need to define a class in QL in terms of an existing (larger) class. In our example, a ``Southerner`` is a special kind of ``Person``, so we say that ``Southerner`` *extends* ("is a subset of") ``Person``.

2
docs/ql-documentation/learn-ql/beginner/heir.rst
View File

@@ -89,7 +89,7 @@ This is getting complicated. Ideally, you want to define a predicate ``relativeO
How could you do that?
It helps to think of a precise definition of "relative". A possible definition is that two people are related if they have a common ancestor.
It helps to think of a precise definition of *relative*. A possible definition is that two people are related if they have a common ancestor.
You can introduce a predicate ``ancestorOf(Person p)`` that lists all ancestors of ``p``. An ancestor of ``p`` is just a parent of ``p``, or a parent of a parent of ``p``, or a parent of a parent of a parent of ``p``, and so on. Unfortunately, this leads to an endless list of parents. You can't write an infinite QL query, so there must be an easier approach.

2
docs/ql-documentation/learn-ql/cpp/dataflow.rst
View File

@@ -12,7 +12,7 @@ For a more general introduction to modeling data flow in QL, see :doc:`Introduct
Local data flow
---------------
Local data flow is data flow within a single function. Local data flow is usually easier, faster and more precise than global data flow, and is sufficient for many queries.
Local data flow is data flow within a single function. Local data flow is usually easier, faster, and more precise than global data flow, and is sufficient for many queries.
Using local data flow
~~~~~~~~~~~~~~~~~~~~~

2
docs/ql-documentation/learn-ql/cpp/expressions-types.rst
View File

@@ -4,7 +4,7 @@ Tutorial: Expressions, types and statements
Overview
--------
This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ expressions, types and statements.
This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ expressions, types, and statements.
Expressions and types
---------------------

2
docs/ql-documentation/learn-ql/cpp/introduce-libraries-cpp.rst
View File

@@ -49,7 +49,7 @@ Symbol table
- ``TypedefType`` — typedefs
- ``ArrayType`` — arrays
- ``PointerType`` — pointers
- ``SpecifiedType`` — qualifiers such as const, volatile, or restrict
- ``SpecifiedType`` — qualifiers such as ``const``, ``volatile``, or ``restrict``
- ``Namespace`` — namespaces (defined in the `Namespace.qll <https://help.semmle.com/qldoc/cpp/semmle/code/cpp/Namespace.qll/module.Namespace.html>`__ library)

2
docs/ql-documentation/learn-ql/cpp/private-field-initialization.rst
View File

@@ -62,7 +62,7 @@ These can be excluded by adding an extra condition to check for this special con
Refinement 2—excluding fields initialized by external libraries
---------------------------------------------------------------
When you test the revised query, you may discover that fields from classes in external libraries are over-reported. This is often because a header file declares a constructor that is defined in a source file that is not analyzed (external libraries are often excluded from analysis). When the source code is analyzed, the snapshot is populated with a ``Constructor`` entry with no body. This ``constructor`` therefore contains no assignments and consequently the query reports that any fields initialized by the constructor are "uninitialized". There is no particular reason to be suspicious of these cases, and we can exclude them from the results by defining a condition to exclude constructors that have no body:
When you test the revised query, you may discover that fields from classes in external libraries are over-reported. This is often because a header file declares a constructor that is defined in a source file that is not analyzed (external libraries are often excluded from analysis). When the source code is analyzed, the snapshot is populated with a ``Constructor`` entry with no body. This ``constructor`` therefore contains no assignments and consequently the query reports that any fields initialized by the constructor are "uninitialized." There is no particular reason to be suspicious of these cases, and we can exclude them from the results by defining a condition to exclude constructors that have no body:
.. code-block:: ql

8
docs/ql-documentation/learn-ql/cpp/zero-space-terminator.rst
View File

@@ -1,5 +1,5 @@
Example: Checking for allocations equal to 'strlen(string)' without space for a null terminator
===============================================================================================
Example: Checking for allocations equal to ``strlen(string)`` without space for a null terminator
=================================================================================================
Overview
--------
@@ -49,8 +49,8 @@ Calls to ``strlen`` can be identified using the library `StrlenCall <https://hel
You could easily extend this class to include similar functions such as ``realloc``, or your own custom allocator. With a little effort they could even include C++ ``new`` expressions (to do this, ``MallocCall`` would need to extend a common superclass of both ``FunctionCall`` and ``NewExpr``, such as ``Expr``).
Finding the 'strlen(string)' pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finding the ``strlen(string)`` pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before we start to write our query, there's one remaining task. We need to modify our new ``MallocCall`` class, so it returns an expression for the size of the allocation. Currently this will be the first argument to the ``malloc`` call, ``FunctionCall.getArgument(0)``, but converting this into a QL predicate makes it more flexible for future refinements.

4
docs/ql-documentation/learn-ql/csharp/dataflow.rst
View File

@@ -12,7 +12,7 @@ For a more general introduction to modeling data flow in QL, see :doc:`Introduct
Local data flow
---------------
Local data flow is data flow within a single method or callable. Local data flow is easier, faster and more precise than global data flow, and is sufficient for many queries.
Local data flow is data flow within a single method or callable. Local data flow is easier, faster, and more precise than global data flow, and is sufficient for many queries.
Using local data flow
~~~~~~~~~~~~~~~~~~~~~
@@ -330,7 +330,7 @@ Class hierarchy
- ``CallableFlowSinkQualifier`` - the output is to the object itself
- ``CallableFlowSinkReturn`` - the output is returned from the call
- ``CallableFlowSinkArg`` - the output is an argument
- ``CallableFlowSinkDelegateArg`` - the output flows through a delegate argument (e.g. LINQ)
- ``CallableFlowSinkDelegateArg`` - the output flows through a delegate argument (for example, LINQ)
Example
~~~~~~~

20
docs/ql-documentation/learn-ql/csharp/introduce-libraries-csharp.rst
View File

@@ -14,7 +14,7 @@ The core library is imported at the top of each query using:
Since this is required for all C# queries, it is omitted from QL snippets below.
The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__ and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. See :doc:`QL for C# <ql-for-csharp>` for information about these additional libraries.
The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. See :doc:`QL for C# <ql-for-csharp>` for information about these additional libraries.
Class hierarchies
~~~~~~~~~~~~~~~~~
@@ -50,7 +50,7 @@ QL classes can also be considered to be *sets*, and the ``extends`` relation bet
This overview omits some of the less important or intermediate classes from the class hierarchy.
Each class has "predicates", which are logical propositions about that class. They also define navigable relationships between classes. Predicates are inherited, so for example the ``AddExpr`` class inherits the predicates ``getLeftOperand()`` and ``getRightOperand()`` from ``BinaryArithmeticOperation``, and ``getType()`` from class ``Expr``. This is similar to how methods are inherited in object-oriented programming languages.
Each class has predicates, which are logical propositions about that class. They also define navigable relationships between classes. Predicates are inherited, so for example the ``AddExpr`` class inherits the predicates ``getLeftOperand()`` and ``getRightOperand()`` from ``BinaryArithmeticOperation``, and ``getType()`` from class ``Expr``. This is similar to how methods are inherited in object-oriented programming languages.
In this overview, we present the most common and useful predicates. Consult the reference, QL source code, and autocomplete in the editor for the complete list of predicates available on each class.
@@ -118,7 +118,7 @@ Exercise 2: Write a query to find the source file with the largest number of lin
Elements
--------
The class `Element <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Element.qll/type.Element$Element.html>`__ is the base class for all parts of a C# program, and it is the root of the element class hierarchy. All program elements (such as types, methods, statements and expressions) ultimately derive from this common base class.
The class `Element <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Element.qll/type.Element$Element.html>`__ is the base class for all parts of a C# program, and it is the root of the element class hierarchy. All program elements (such as types, methods, statements, and expressions) ultimately derive from this common base class.
``Element`` forms a hierarchical structure of the program, which can be navigated using the ``getParent()`` and ``getChild()`` predicates. This is much like an abstract syntax tree, and also applies to elements in assemblies.
@@ -247,7 +247,7 @@ Class hierarchy
- ``Field`` - a field in a ``class``/``struct``
- ``MemberConstant`` - a const field
- ``MemberConstant`` - a ``const`` field
- ``EnumConstant`` - a field in an ``enum``
@@ -283,7 +283,7 @@ Find all unused local variables:
Types
-----
Types are represented by the QL class `Type <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Type.qll/type.Type$Type.html>`__ and consist of builtin types, interfaces, classes, structs, enums and type parameters. The database contains types from the program and all referenced assemblies including mscorlib and the .NET framework.
Types are represented by the QL class `Type <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Type.qll/type.Type$Type.html>`__ and consist of builtin types, interfaces, classes, structs, enums, and type parameters. The database contains types from the program and all referenced assemblies including mscorlib and the .NET framework.
The builtin types (``object``, ``int``, ``double`` etc.) have corresponding types (``System.Object``, ``System.Int32`` etc.) in mscorlib.
@@ -374,7 +374,7 @@ Useful members of ``ValueOrRefType`` include:
- ``getQualifiedName()/hasQualifiedName(string)`` - gets the qualified name of the type (for example, ``"System.String"``)
- ``getABaseInterface()`` - gets an immediate interface of this type, if any
- ``getABaseType()`` - gets an immediate base class or interface of this type, if any
- ``getBaseClass()`` - gets the immmediate base class of this type, if any
- ``getBaseClass()`` - gets the immediate base class of this type, if any
- ``getASubType()`` - gets an immediate subtype, a type which directly inherits from this type, if any
- ``getAMember()`` - gets any member (field/method/property etc), if any
- ``getAMethod()`` - gets a method, if any
@@ -438,7 +438,7 @@ Exercise 5: Write a query to find all classes starting with the letter ``A``. (`
Callables
---------
Callables are represented by the QL class `Callable <https://help.semmle.com/qldoc/csharp/semmle/code/csharp/Callable.qll/type.Callable$Callable.html>`__ and are anything that can be called independently, such as methods, constructors, destructors, operators, anonymous functions, indexers and property accessors.
Callables are represented by the QL class `Callable <https://help.semmle.com/qldoc/csharp/semmle/code/csharp/Callable.qll/type.Callable$Callable.html>`__ and are anything that can be called independently, such as methods, constructors, destructors, operators, anonymous functions, indexers, and property accessors.
The database contains all of the callables in your program and in all referenced assemblies.
@@ -695,7 +695,7 @@ The ``Access`` class represents any use or cross-reference of another ``Declarat
The ``Call`` class represents a call to a ``Callable``, for example to a ``Method`` or an ``Accessor``, and the ``getTarget()`` method gets the ``Callable`` being called. The ``Operation`` class consists of arithmetic, bitwise operations and logical operations.
Some expressions use a "qualifier", which is the object on which the expression operates. A typical example is a ``MethodCall``. In this case, the ``getQualifier()`` predicate is used to get the expression on the left of the ``.``, and ``getArgument(int)`` is used to get the arguments of the call.
Some expressions use a qualifier, which is the object on which the expression operates. A typical example is a ``MethodCall``. In this case, the ``getQualifier()`` predicate is used to get the expression on the left of the ``.``, and ``getArgument(int)`` is used to get the arguments of the call.
Class hierarchy
~~~~~~~~~~~~~~~
@@ -922,7 +922,7 @@ Exercise 9: Limit the previous query to string types. Exclude empty passwords or
Attributes
----------
C# attributes are represented by the QL class `Attribute <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Attribute.qll/type.Attribute$Attribute.html>`__. They can be present on many C# elements, such as classes, methods, fields and parameters. The database contains attributes from the source code and all assembly references.
C# attributes are represented by the QL class `Attribute <https://help.semmle.com/qldoc/csharp/semmle/code/cil/Attribute.qll/type.Attribute$Attribute.html>`__. They can be present on many C# elements, such as classes, methods, fields, and parameters. The database contains attributes from the source code and all assembly references.
The attribute of any ``Element`` can be obtained via ``getAnAttribute()``, whereas if you have an attribute, you can find its element via ``getTarget()``. The following two query fragments are identical:
@@ -943,7 +943,7 @@ Predicates
- ``getTarget()`` - gets the ``Element`` to which this attribute applies
- ``getArgument(int)`` - gets the given argument of the attribute
- ``getType()`` - gets the type of this attribute. Note that the class name must end in "Attribute".
- ``getType()`` - gets the type of this attribute. Note that the class name must end in ``"Attribute"``.
Examples
~~~~~~~~

2
docs/ql-documentation/learn-ql/intro-to-data-flow.rst
View File

@@ -7,7 +7,7 @@ Overview
Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used.
Many of Semmle's built-in security queries implement data flow analysis, which can highlight the fate of potentially malicious or insecure data that can cause vulnerabilities in your code base.
These queries help you understand if data is used in an insecure way, whether dangerous arguments are passed to functions, or whether sensitive data can leak.
As well as highlighting potential security issues, you can also use data flow analysis to understand other aspects of how a program behaves, by finding, for example, uses of unititialised variables and resource leaks.
As well as highlighting potential security issues, you can also use data flow analysis to understand other aspects of how a program behaves, by finding, for example, uses of unititialized variables and resource leaks.
The following sections provide a brief introduction to data flow analysis in QL.

8
docs/ql-documentation/learn-ql/introduction-to-ql.rst
View File

@@ -22,7 +22,7 @@ Once you have selected a language, the query console is populated with the query
select "hello world"
This query simply returns the string "hello world".
This query simply returns the string ``"hello world"``.
More complicated queries typically look like this:
@@ -50,7 +50,7 @@ You can try to write simple queries using the some of the basic functions that a
Exercise 1
~~~~~~~~~~
Write a query which returns the length of the string "lgtm". (Hint: `here <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
➤ `Answer <https://lgtm.com/query/2103060623/>`__
@@ -77,7 +77,7 @@ Write a query which returns the opposite of the boolean ``false``.
Exercise 4
~~~~~~~~~~
Write a query which computes the number of days between 10 June 2017 and 28 September 2017.
Write a query which computes the number of days between June 10 and September 28, 2017.
➤ `Answer <https://lgtm.com/query/2100260596/>`__
@@ -138,7 +138,7 @@ JavaScript
where c.getText().regexpMatch("(?si).*\\bTODO\\b.*")
select c
➤ `See this in the query console <https://lgtm.com/query/2101530483/>`__. The ``from`` clause defines a variable ``c`` representing a comment. The ``where`` part limits the comments ``c`` to those containing the word "TODO". The ``select`` clause lists these comments.
➤ `See this in the query console <https://lgtm.com/query/2101530483/>`__. The ``from`` clause defines a variable ``c`` representing a comment. The ``where`` part limits the comments ``c`` to those containing the word ``"TODO"``. The ``select`` clause lists these comments.
Java
~~~~

4
docs/ql-documentation/learn-ql/java/annotations.rst
View File

@@ -66,8 +66,8 @@ As another example, this query finds all annotation types that only have a singl
➤ `See the full query in the query console <https://lgtm.com/query/669220001>`__.
Example: Finding missing @Override annotations
----------------------------------------------
Example: Finding missing ``@Override`` annotations
--------------------------------------------------
In newer versions of Java, it is recommended (though not required) to annotate methods that override another method with an ``@Override`` annotation. These annotations, which are checked by the compiler, serve as documentation, and also help you avoid accidental overloading where overriding was intended.

182
docs/ql-documentation/learn-ql/java/ast-class-reference.rst
View File

@@ -1,67 +1,85 @@
AST class reference
===================
.. _Expr: https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Expr.html
.. _Stmt: https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$Stmt.html
.. _VarAccess: https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$VarAccess.html
.. _SwitchCase: https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SwitchCase.html
.. _TypeAccess: https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$TypeAccess.html
.. _Member: https://help.semmle.com/qldoc/java/semmle/code/java/Member.qll/type.Member$Member.html
.. _Literal: https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Literal.html
Statement classes
-----------------
This table lists all subclasses of `Stmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$Stmt.html>`__.
This table lists all subclasses of `Stmt`_.
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| Statement syntax | QL class | Superclasses | Remarks |
+======================================================================================================================+===========================================================================================================================================================+===================================+=============================================+
| ``;`` | `EmptyStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$EmptyStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| *``Expr``* ``;`` | `ExprStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ExprStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``{`` *``Stmt``* ``... }`` | `Block <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$Block.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``if``** ``(`` *``Expr``* ``)`` *``Stmt``* **``else``** *``Stmt``*\ \ **``if``** ``(`` *``Expr``* ``)`` *``Stmt``* | `IfStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$IfStmt.html>`__ | ``ConditionalStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``while``** ``(`` *``Expr``* ``)`` *``Stmt``* | `WhileStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$WhileStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``do``** *``Stmt``* **``while``** ``(`` *``Expr``* ``)`` | `DoStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$DoStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``for``** ``(`` *``Expr``* ``;`` *``Expr``* ``;`` *``Expr``* ``)`` *``Stmt``* | `ForStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ForStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``for``** ``(`` *``VarAccess``* ``:`` *``Expr``* ``)`` *``Stmt``* | `EnhancedForStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$EnhancedForStmt.html>`__ | ``LoopStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``switch``** ``(`` *``Expr``* ``) {`` *``SwitchCase``* ``... }`` | `SwitchStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SwitchStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``try``** ``{`` *``Stmt``* ``... }`` **``finally``** ``{`` *``Stmt``* ``... }`` | `TryStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$TryStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``return``** *``Expr``* ``;``\ \ **``return``** ``;`` | `ReturnStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ReturnStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``throw``** *``Expr``* ``;`` | `ThrowStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ThrowStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``break``** ``;``\ \ **``break``** ``label ;`` | `BreakStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$BreakStmt.html>`__ | ``JumpStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``continue``** ``;``\ \ **``continue``** ``label ;`` | `ContinueStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ContinueStmt.html>`__ | ``JumpStmt`` | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``label :`` *``Stmt``* | `LabeledStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LabeledStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``synchronized``** ``(`` *``Expr``* ``)`` *``Stmt``* | `SynchronizedStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SynchronizedStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``assert``** *``Expr``* ``:`` *``Expr``* ``;``\ \ **``assert``** *``Expr``* ``;`` | `AssertStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$AssertStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| *``TypeAccess``* ``name ;`` | `LocalVariableDeclStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LocalVariableDeclStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``class``** ``name {`` *``Member``* ``... } ;`` | `LocalClassDeclStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LocalClassDeclStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``this``** ``(`` *``Expr``* ``, ... ) ;`` | `ThisConstructorInvocationStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ThisConstructorInvocationStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``super``** ``(`` *``Expr``* ``, ... ) ;`` | `SuperConstructorInvocationStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SuperConstructorInvocationStmt.html>`__ | | |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``catch``** ``(`` *``TypeAccess``* ``name ) {`` *``Stmt``* ``... }`` | `CatchClause <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$CatchClause.html>`__ | | can only occur as child of a ``TryStmt`` |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``case``** *``Literal``* ``:`` *``Stmt``* ``...`` | `ConstCase <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ConstCase.html>`__ | | can only occur as child of a ``SwitchStmt`` |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| **``default``** ``:`` *``Stmt``* ``...`` | `DefaultCase <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$DefaultCase.html>`__ | | can only occur as child of a ``SwitchStmt`` |
+----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| Statement syntax | QL class | Superclasses | Remarks |
+========================================================================+===========================================================================================================================================================+===================================+=============================================+
| ``;`` | `EmptyStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$EmptyStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| `Expr`_ ``;`` | `ExprStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ExprStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``{`` `Stmt`_ ``... }`` | `Block <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$Block.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``if (`` `Expr`_ ``)`` `Stmt`_ ``else`` `Stmt`_ | `IfStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$IfStmt.html>`__ | ``ConditionalStmt`` | |
+------------------------------------------------------------------------+ + + +
| ``if (`` `Expr`_ ``)`` `Stmt`_ | | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``while (`` `Expr`_ ``)`` `Stmt`_ | `WhileStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$WhileStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``do`` `Stmt`_ ``while (`` `Expr`_ ``)`` | `DoStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$DoStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``for (`` `Expr`_ ``;`` `Expr`_ ``;`` `Expr`_ ``)`` `Stmt`_ | `ForStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ForStmt.html>`__ | ``ConditionalStmt``, ``LoopStmt`` | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``for (`` `VarAccess`_ ``:`` `Expr`_ ``)`` `Stmt`_ | `EnhancedForStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$EnhancedForStmt.html>`__ | ``LoopStmt`` | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``switch (`` `Expr`_ ``) {`` `SwitchCase`_ ``... }`` | `SwitchStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SwitchStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``try {`` `Stmt`_ ``... } finally {`` `Stmt`_ ``... }`` | `TryStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$TryStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``return`` `Expr`_ ``;`` | `ReturnStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ReturnStmt.html>`__ | | |
+------------------------------------------------------------------------+ + + +
| ``return ;`` | | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``throw`` `Expr`_ ``;`` | `ThrowStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ThrowStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``break ;`` | `BreakStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$BreakStmt.html>`__ | ``JumpStmt`` | |
+------------------------------------------------------------------------+ + + +
| ``break label ;`` | | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``continue ;`` | `ContinueStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ContinueStmt.html>`__ | ``JumpStmt`` | |
+------------------------------------------------------------------------+ + + +
| ``continue label ;`` | | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``label :`` `Stmt`_ | `LabeledStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LabeledStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``synchronized (`` `Expr`_ ``)`` `Stmt`_ | `SynchronizedStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SynchronizedStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``assert`` `Expr`_ ``:`` `Expr`_ ``;`` | `AssertStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$AssertStmt.html>`__ | | |
+------------------------------------------------------------------------+ + + +
| ``assert`` `Expr`_ ``;`` | | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| `TypeAccess`_ ``name ;`` | `LocalVariableDeclStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LocalVariableDeclStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``class name {`` `Member`_ ``... } ;`` | `LocalClassDeclStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$LocalClassDeclStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``this (`` `Expr`_ ``, ... ) ;`` | `ThisConstructorInvocationStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ThisConstructorInvocationStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``super (`` `Expr`_ ``, ... ) ;`` | `SuperConstructorInvocationStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$SuperConstructorInvocationStmt.html>`__ | | |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``catch (`` `TypeAccess`_ ``name ) {`` `Stmt`_ ``... }`` | `CatchClause <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$CatchClause.html>`__ | | can only occur as child of a ``TryStmt`` |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``case`` `Literal`_ ``:`` `Stmt`_ ``...`` | `ConstCase <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$ConstCase.html>`__ | | can only occur as child of a ``SwitchStmt`` |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
| ``default :`` `Stmt`_ ``...`` | `DefaultCase <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$DefaultCase.html>`__ | | can only occur as child of a ``SwitchStmt`` |
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
Expression classes
------------------
There is a large number of expression classes, so we present them by category. All classes in this section are subclasses of `Expr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Expr.html>`__.
There are many expression classes, so we present them by category. All classes in this section are subclasses of `Expr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Expr.html>`__.
Literals
~~~~~~~~
@@ -196,23 +214,35 @@ All classes in this table are subclasses of `Assignment <https://help.semmle.com
Accesses
~~~~~~~~
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| Expression syntax examples | QL class |
+====================================================================+=========================================================================================================================+
| **``this``**\ \ ``Outer.``\ **``this``** | `ThisAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ThisAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| **``super``**\ \ ``Outer``.\ **``super``** | `SuperAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$SuperAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``x``\ \ ``e.f`` | `VarAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$VarAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``a[i]`` | `ArrayAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ArrayAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``f(...)``\ \ ``e.m(...)`` | `MethodAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$MethodAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``String``\ \ ``java.lang.String`` | `TypeAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$TypeAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``?`` **``extends``** ``Number``\ \ ``?`` **``super``** ``Double`` | `WildcardTypeAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$WildcardTypeAccess.html>`__ |
+--------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| Expression syntax examples | QL class |
+======================================+=========================================================================================================================+
| ``this`` | `ThisAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ThisAccess.html>`__ |
+--------------------------------------+ +
| ``Outer.this`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``super`` | `SuperAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$SuperAccess.html>`__ |
+--------------------------------------+ +
| ``Outer.super`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``x`` | `VarAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$VarAccess.html>`__ |
+--------------------------------------+ +
| ``e.f`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``a[i]`` | `ArrayAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ArrayAccess.html>`__ |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``f(...)`` | `MethodAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$MethodAccess.html>`__ |
+--------------------------------------+ +
| ``e.m(...)`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``String`` | `TypeAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$TypeAccess.html>`__ |
+--------------------------------------+ +
| ``java.lang.String`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
| ``? extends Number`` | `WildcardTypeAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$WildcardTypeAccess.html>`__ |
+--------------------------------------+ +
| ``? super Double`` | |
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
A ``VarAccess`` that refers to a field is a `FieldAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$FieldAccess.html>`__.
@@ -226,15 +256,17 @@ Miscellaneous
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| ``(23 + 42)`` | `ParExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ParExpr.html>`__ | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| ``o`` **``instanceof``** ``String`` | `InstanceOfExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$InstanceOfExpr.html>`__ | |
| ``o instanceof String`` | `InstanceOfExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$InstanceOfExpr.html>`__ | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| *``Expr``* ``?`` *``Expr``* ``:`` *``Expr``* | `ConditionalExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ConditionalExpr.html>`__ | |
| `Expr`_ ``?`` `Expr`_ ``:`` `Expr`_ | `ConditionalExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ConditionalExpr.html>`__ | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| ``String.``\ **``class``** | `TypeLiteral <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$TypeLiteral.html>`__ | |
| ``String. class`` | `TypeLiteral <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$TypeLiteral.html>`__ | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| **``new``** ``A()`` | `ClassInstanceExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ClassInstanceExpr.html>`__ | |
| ``new A()`` | `ClassInstanceExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ClassInstanceExpr.html>`__ | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| **``new``** ``String[3][2]``\ \ **``new``** ``int[] { 23, 42 }`` | `ArrayCreationExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ArrayCreationExpr.html>`__ | |
| ``new String[3][2]`` | `ArrayCreationExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ArrayCreationExpr.html>`__ | |
+------------------------------------------------------------------+ + +
| ``new int[] { 23, 42 }`` | | |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
| ``{ 23, 42 }`` | `ArrayInit <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ArrayInit.html>`__ | can only appear as an initializer or as a child of an ``ArrayCreationExpr`` |
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+

4
docs/ql-documentation/learn-ql/java/dataflow.rst
View File

@@ -12,7 +12,7 @@ For a more general introduction to modeling data flow in QL, see :doc:`Introduct
Local data flow
---------------
Local data flow is data flow within a single method or callable. Local data flow is usually easier, faster and more precise than global data flow, and is sufficient for many queries.
Local data flow is data flow within a single method or callable. Local data flow is usually easier, faster, and more precise than global data flow, and is sufficient for many queries.
Using local data flow
~~~~~~~~~~~~~~~~~~~~~
@@ -173,7 +173,7 @@ The following predicates are defined in the configuration:
- ``isBarrier``—optional, restricts the data flow
- ``isAdditionalFlowStep``—optional, adds additional flow steps
The characteristic predicate ``MyDataFlowConfiguration()`` defines the name of the configuration, so ``"MyDataFlowConfiguration"`` should be a unique name, e.g. the name of your class.
The characteristic predicate ``MyDataFlowConfiguration()`` defines the name of the configuration, so ``"MyDataFlowConfiguration"`` should be a unique name, for example, the name of your class.
The data flow analysis is performed using the predicate ``hasFlow(DataFlow::Node source, DataFlow::Node sink)``:

4
docs/ql-documentation/learn-ql/java/introduce-libraries-java.rst
View File

@@ -201,7 +201,7 @@ Class ``Variable`` represents a variable `in the Java sense <http://docs.oracle.
- ``LocalVariableDecl`` represents a local variable.
- ``Parameter`` represents a parameter of a method or constructor.
Abstract Syntax Tree
Abstract syntax tree
--------------------
Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). See the :doc:`AST class reference <ast-class-reference>` for an exhaustive list of all expression and statement types available in the standard QL library.
@@ -339,7 +339,7 @@ For example, the following query finds methods with a `cyclomatic complexity <ht
➤ `See this in the query console <https://lgtm.com/query/670720174/>`__. Most large projects include some methods with a very high cyclomatic complexity. These methods are likely to be difficult to understand and test.
Call Graph
Call graph
----------
Snapshots databases generated from Java code bases include precomputed information about the program's call graph, that is, which methods or constructors a given call may dispatch to at runtime.

2
docs/ql-documentation/learn-ql/java/source-locations.rst
View File

@@ -46,7 +46,7 @@ For example, assume the following Java class is defined in compilation unit ``Sa
Invoking ``getFile`` on the expression statement in the body of ``main`` will return a ``File`` object representing the file ``SayHello.java``. The statement spans four lines in total ``(getTotalNumberOfLines``), of which one is a comment line (``getNumberOfCommentLines``), while three lines contain code (``getNumberOfLinesOfCode``).
Class ``Location`` defines member predicates ``getStartLine``, ``getEndLine``, ``getStartColumn`` and ``getEndColumn`` to retrieve the line and column number an entity starts and ends at, respectively. Both lines and columns are counted starting from 1 (not 0), and the end position is inclusive, i.e., it is the position of the last character belonging to the source code of the entity.
Class ``Location`` defines member predicates ``getStartLine``, ``getEndLine``, ``getStartColumn`` and ``getEndColumn`` to retrieve the line and column number an entity starts and ends at, respectively. Both lines and columns are counted starting from 1 (not 0), and the end position is inclusive, that is, it is the position of the last character belonging to the source code of the entity.
In our example, the expression statement starts at line 5, column 3 (the first two characters on the line are tabs, which each count as one character), and it ends at line 8, column 4.

4
docs/ql-documentation/learn-ql/java/types-class-hierarchy.rst
View File

@@ -36,7 +36,7 @@ To determine ancestor types (including immediate super types, and also *their* s
If you want to see the location of ``B`` as well as ``A``, you can replace ``B.getASupertype+()`` with ``B.getASupertype*()`` and re-run the query.
Besides class hierarchy modeling, ``RefType`` also provides member predicate ``getAMember`` for accessing members (that is, fields, constructors and methods) declared in the type, and predicate ``inherits(Method m)`` for checking whether the type either declares or inherits a method ``m``.
Besides class hierarchy modeling, ``RefType`` also provides member predicate ``getAMember`` for accessing members (that is, fields, constructors, and methods) declared in the type, and predicate ``inherits(Method m)`` for checking whether the type either declares or inherits a method ``m``.
Example: Finding problematic array casts
----------------------------------------
@@ -81,7 +81,7 @@ Note that by casting ``target.getElementType()`` to a ``RefType``, we eliminate
Improvements
~~~~~~~~~~~~
Running this query on pre-Java 5 code often returns many false positive results arising from uses of the method ``Collection.toArray(T[])``, which converts a collection into an array of type ``T[]``.
Running this query on old Java code, before version 5, often returns many false positive results arising from uses of the method ``Collection.toArray(T[])``, which converts a collection into an array of type ``T[]``.
In code that does not use generics, this method is often used in the following way:

2
docs/ql-documentation/learn-ql/javascript/ast-class-reference.rst
View File

@@ -338,7 +338,6 @@ All classes in this table are subclasses of `UpdateExpr <https://help.semmle.com
| ``--`` `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__ | `PreDecExpr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$PreDecExpr.html>`__ |
+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
Miscellaneous
~~~~~~~~~~~~~
@@ -355,4 +354,3 @@ All classes in this table are subclasses of `Expr <https://help.semmle.com/qldoc
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| ``yield`` `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__ | `YieldExpr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$YieldExpr.html>`__ |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+

12
docs/ql-documentation/learn-ql/javascript/dataflow.rst
View File

@@ -1,5 +1,5 @@
Analyzing data flow in JavaScript/TypeScript
============================================
Analyzing data flow in JavaScript and TypeScript
================================================
Overview
--------
@@ -19,11 +19,11 @@ Both local and global data flow, as well as taint tracking, work on a representa
Nodes on the data flow flow graph may also correspond to nodes on the abstract syntax tree, but they are not the same.
While AST nodes belong to class ``ASTNode`` and its subclasses, data flow nodes belong to class ``DataFlow::Node`` and its subclasses:
- ``DataFlow::ValueNode``: a "value node", that is, a data flow node that corresponds either to an expression, or to a declaration of a function, class, TypeScript namespace,
- ``DataFlow::ValueNode``: a *value node*, that is, a data flow node that corresponds either to an expression, or to a declaration of a function, class, TypeScript namespace,
or TypeScript enum.
- ``DataFlow::SsaDefinitionNode``: a data flow node that corresponds to an SSA variable, that is, a local variable with additional information to reason more precisely
about different assignments to the same variable. This kind of data flow node does not correspond to an AST node.
- ``DataFlow::PropRef``: a data flow node that corresponds to a read or a write of an object property, for example in an assignment, in an object literal, or in a
- ``DataFlow::PropRef``: a data flow node that corresponds to a read or a write of an object property, for example, in an assignment, in an object literal, or in a
destructuring assignment.
- ``DataFlow::PropRead``, ``DataFlow::PropWrite``: subclasses of ``DataFlow::PropRef`` that correspond to reads and writes, respectively.
@@ -33,7 +33,7 @@ Apart from these fairly general classes, there are some more specialized classes
- ``DataFlow::InvokeNode``: a data flow node that corresponds to a function call; its subclasses ``DataFlow::NewNode`` and ``DataFlow::CallNode`` represent calls with
and without ``new`` respectively, while ``DataFlow::MethodCallNode`` represents method calls. Note that these classes also model reflective calls using ``.call`` and
``.apply``, which do not correspond to any AST nodes.
- ``DataFlow::ThisNode``: a data flow node that corresponds to the value of ``this`` in a function or toplevel. This kind of data flow node also does not correspond to an AST node.
- ``DataFlow::ThisNode``: a data flow node that corresponds to the value of ``this`` in a function or top level. This kind of data flow node also does not correspond to an AST node.
- ``DataFlow::GlobalVarRefNode``: a data flow node that corresponds to a direct reference to a global variable. This class is rarely used directly, instead you would normally
use the predicate ``globalVarRef`` (introduced below), which also considers indirect references through ``window`` or global ``this``.
- ``DataFlow::FunctionNode``, ``DataFlow::ObjectLiteralNode``, ``DataFlow::ArrayLiteralNode``: a data flow node that corresponds to a function (expression or declaration),
@@ -47,7 +47,7 @@ The following predicates are available for mapping from AST nodes and other elem
- ``DataFlow::valueNode(x)``: maps ``x``, which must be an expression or a declaration of a function, class, namespace or enum, to its corresponding ``DataFlow::ValueNode``.
- ``DataFlow::ssaDefinitionNode(ssa)``: maps an SSA definition ``ssa`` to its corresponding ``DataFlow::SsaDefinitionNode``.
- ``DataFlow::parameterNode(p)``: maps a function parameter ``p`` to its corresponding ``DataFlow::ParameterNode``.
- ``DataFlow::thisNode(s)``: maps a function or toplevel ``s`` to the ``DataFlow::ThisNode`` representing the value of ``this`` in ``s``.
- ``DataFlow::thisNode(s)``: maps a function or top-level ``s`` to the ``DataFlow::ThisNode`` representing the value of ``this`` in ``s``.
Class ``DataFlow::Node`` also has a member predicate ``asExpr()`` that you can use to map from a ``DataFlow::ValueNode`` to the expression it corresponds to. Note that
this predicate is undefined for other kinds of nodes, and for value nodes that do not correspond to expressions.

63
docs/ql-documentation/learn-ql/javascript/introduce-libraries-js.rst
View File

@@ -32,7 +32,7 @@ The QL JavaScript library presents information about JavaScript source code at d
Note that representations above the textual level (for example the lexical representation or the flow graphs) are only available for JavaScript code that does not contain fatal syntax errors. For code with such errors, the only information available is at the textual level, as well as information about the errors themselves.
Additionally, there is library support for working with HTML documents, JSON and YAML data, JSDoc comments, and regular expressions.
Additionally, there is library support for working with HTML documents, JSON, and YAML data, JSDoc comments, and regular expressions.
Textual level
~~~~~~~~~~~~~
@@ -194,10 +194,10 @@ The QL class `ASTNode <https://help.semmle.com/qldoc/javascript/semmle/javascrip
These predicates should only be used to perform generic AST traversal. To access children of specific AST node types, the specialized predicates introduced below should be used instead. In particular, queries should not rely on the numeric indices of child nodes relative to their parent nodes: these are considered an implementation detail that may change between versions of the library.
Toplevels
^^^^^^^^^
Top-levels
^^^^^^^^^^
From a syntactic point of view, each JavaScript program is composed of one or more top-level code blocks (or *toplevels* for short), which are blocks of JavaScript code that do not belong to a larger code block. Toplevels are represented by the class `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ and its subclasses:
From a syntactic point of view, each JavaScript program is composed of one or more top-level code blocks (or *top-levels* for short), which are blocks of JavaScript code that do not belong to a larger code block. Top-levels are represented by the class `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ and its subclasses:
- `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__
@@ -213,20 +213,20 @@ From a syntactic point of view, each JavaScript program is composed of one or mo
- `Externs <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$Externs.html>`__: a JavaScript file containing `externs <https://developers.google.com/closure/compiler/docs/api-tutorial3#externs>`__ definitions
Every `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ class is contained in a `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__ class, but a single `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__ may contain more than one `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__. To go from a ``TopLevel tl`` to its `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__, use ``tl.getFile()``; conversely, for a ``File f``, predicate ``f.getATopLevel()`` returns a toplevel contained in ``f``. For every AST node, predicate ``ASTNode.getTopLevel()`` can be used to find the toplevel it belongs to.
Every `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ class is contained in a `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__ class, but a single `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__ may contain more than one `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__. To go from a ``TopLevel tl`` to its `File <https://help.semmle.com/qldoc/javascript/semmle/javascript/Files.qll/type.Files$File.html>`__, use ``tl.getFile()``; conversely, for a ``File f``, predicate ``f.getATopLevel()`` returns a top-level contained in ``f``. For every AST node, predicate ``ASTNode.getTopLevel()`` can be used to find the top-level it belongs to.
The `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ class additionally provides the following member predicates:
- ``TopLevel.getNumberOfLines()`` returns the total number of lines (including code, comments and whitespace) in the toplevel.
- ``TopLevel.getNumberOfLines()`` returns the total number of lines (including code, comments and whitespace) in the top-level.
- ``TopLevel.getNumberOfLinesOfCode()`` returns the number of lines of code, that is, lines that contain at least one token.
- ``TopLevel.getNumberOfLinesOfComments()`` returns the number of lines containing or belonging to a comment.
- ``TopLevel.isMinified()`` determines whether the toplevel contains minified code, using a heuristic based on the average number of statements per line.
- ``TopLevel.isMinified()`` determines whether the top-level contains minified code, using a heuristic based on the average number of statements per line.
.. pull-quote::
Note
By default, LGTM filters out alerts in minified toplevels, since they are often hard to interpret. When writing your own queries in the LGTM query console, this filtering is *not* done automatically, so you may want to explicitly add a condition of the form ``and not e.getTopLevel().isMinified()`` or similar to your query to exclude results in minified code.
By default, LGTM filters out alerts in minified top-levels, since they are often hard to interpret. When writing your own queries in the LGTM query console, this filtering is *not* done automatically, so you may want to explicitly add a condition of the form ``and not e.getTopLevel().isMinified()`` or similar to your query to exclude results in minified code.
Statements and expressions
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -234,7 +234,7 @@ Statements and expressions
The most important subclasses of `ASTNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$ASTNode.html>`__ besides `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html>`__ are `Stmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html>`__ and `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__, which, together with their subclasses, represent statements and expressions, respectively. This section briefly discusses some of the more important classes and predicates. For a full reference of all the subclasses of `Stmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html>`__ and `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__ and their API, see
`Stmt.qll <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/module.Stmt.html>`__ and `Expr.qll <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/module.Expr.html>`__.
- `Stmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html>`__: use ``Stmt.getContainer()`` to access the innermost function or toplevel in which the statement is contained.
- `Stmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html>`__: use ``Stmt.getContainer()`` to access the innermost function or top-level in which the statement is contained.
- `ControlStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$ControlStmt.html>`__: a statement that controls the execution of other statements, that is, a conditional, loop, ``try`` or ``with`` statement; use ``ControlStmt.getAControlledStmt()`` to access the statements that it controls.
@@ -264,7 +264,7 @@ The most important subclasses of `ASTNode <https://help.semmle.com/qldoc/javascr
- `ClassDeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Classes.qll/type.Classes$ClassDeclStmt.html>`__: a class declaration statement; see below for available member predicates.
- `DeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$DeclStmt.html>`__: a declaration statement containing one or more declarators which can be accessed by predicate ``DeclStmt.getDeclarator(int)``.
- `VarDeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$VarDeclStmt.html>`__, `ConstDeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$ConstDeclStmt.html>`__, `LetStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$LetStmt.html>`__: a "var", "const" or "let" declaration statement.
- `VarDeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$VarDeclStmt.html>`__, `ConstDeclStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$ConstDeclStmt.html>`__, `LetStmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$LetStmt.html>`__: a ``var``, ``const`` or ``let`` declaration statement.
- `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__: use ``Expr.getEnclosingStmt()`` to obtain the innermost statement to which this expression belongs; ``Expr.isPure()`` determines whether the expression is side-effect-free.
@@ -420,10 +420,10 @@ Often, the binding pattern is a simple identifier, as in ``var x = 42``. In ECMA
The various kinds of binding patterns are represented by class `BindingPattern <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$BindingPattern.html>`__ and its subclasses:
- `VarRef <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$VarRef.html>`__: a simple identifier in an lvalue position, for example the ``x`` in ``var x`` or in ``x = 42``
- `VarRef <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$VarRef.html>`__: a simple identifier in an l-value position, for example the ``x`` in ``var x`` or in ``x = 42``
- `Parameter <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$Parameter.html>`__: a function or catch clause parameter
- `ArrayPattern <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$ArrayPattern.html>`__: an array pattern, for example the left hand side of ``[x, y] = arr``
- `ObjectPattern <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$ObjectPattern.html>`__: an object pattern, for example the left hand side of ``{x, y: z} = o``
- `ArrayPattern <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$ArrayPattern.html>`__: an array pattern, for example, the left-hand side of ``[x, y] = arr``
- `ObjectPattern <https://help.semmle.com/qldoc/javascript/semmle/javascript/Variables.qll/type.Variables$ObjectPattern.html>`__: an object pattern, for example, the left-hand side of ``{x, y: z} = o``
Here is an example of a query to find declaration statements that declare the same variable more than once, excluding results in minified code:
@@ -476,7 +476,7 @@ The JavaScript library has support for working with ECMAScript 2015 modules, as
The most important member predicates defined by `Module <https://help.semmle.com/qldoc/javascript/semmle/javascript/Modules.qll/type.Modules$Module.html>`__ are:
- ``Module.getName()``: gets the name of the module, which is just the stem (that is, basename without extension) of the enclosing file.
- ``Module.getName()``: gets the name of the module, which is just the stem (that is, the basename without extension) of the enclosing file.
- ``Module.getAnImportedModule()``: gets another module that is imported (through ``import`` or ``require``) by this module.
- ``Module.getAnExportedSymbol()``: gets the name of a symbol that this module exports.
@@ -538,13 +538,13 @@ As an example, consider the following query which finds distinct function declar
Control flow
~~~~~~~~~~~~
A different program representation in terms of intra-procedural control flow graphs (CFGs) is provided by the QL classes in library `CFG.qll <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/module.CFG.html>`__.
A different program representation in terms of intraprocedural control flow graphs (CFGs) is provided by the QL classes in library `CFG.qll <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/module.CFG.html>`__.
Class `ControlFlowNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html>`__ represents a single node in the control flow graph, which is either an expression, a statement, or a synthetic control flow node. Note that `Expr <https://help.semmle.com/qldoc/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html>`__ and `Stmt <https://help.semmle.com/qldoc/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html>`__ do not inherit from `ControlFlowNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html>`__ at the QL level, although their entity types are compatible, so you can explicitly cast from one to the other if you need to map between the AST-based and the CFG-based program representations.
There are two kinds of synthetic control flow nodes: entry nodes (class `ControlFlowEntryNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowEntryNode.html>`__), which represent the beginning of a toplevel or function, and exit nodes (class `ControlFlowExitNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowExitNode.html>`__), which represent their end. They do not correspond to any AST nodes, but simply serve as the unique entry point and exit point of a control flow graph. Entry and exit nodes can be accessed through the predicates ``StmtContainer.getEntry()`` and ``StmtContainer.getExit()``.
There are two kinds of synthetic control flow nodes: entry nodes (class `ControlFlowEntryNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowEntryNode.html>`__), which represent the beginning of a top-level or function, and exit nodes (class `ControlFlowExitNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowExitNode.html>`__), which represent their end. They do not correspond to any AST nodes, but simply serve as the unique entry point and exit point of a control flow graph. Entry and exit nodes can be accessed through the predicates ``StmtContainer.getEntry()`` and ``StmtContainer.getExit()``.
Most, but not all, toplevels and functions have another distinguished CFG node, the *start node*. This is the CFG node at which execution begins. Unlike the entry node, which is a synthetic construct, the start node corresponds to an actual program element: for toplevels, it is the first CFG node of the first statement; for functions, it is the CFG node corresponding to their first parameter or, if there are no parameters, the first CFG node of the body. Empty toplevels do not have a start node.
Most, but not all, top-levels and functions have another distinguished CFG node, the *start node*. This is the CFG node at which execution begins. Unlike the entry node, which is a synthetic construct, the start node corresponds to an actual program element: for top-levels, it is the first CFG node of the first statement; for functions, it is the CFG node corresponding to their first parameter or, if there are no parameters, the first CFG node of the body. Empty top-levels do not have a start node.
For most purposes, using start nodes is preferable to using entry nodes.
@@ -607,10 +607,10 @@ In SSA form, each use of a local variable has exactly one (SSA) definition that
Altogether, there are five kinds of SSA definitions:
#. Explicit definitions (`SsaExplicitDefinition <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaExplicitDefinition.html>`__): these simply wrap a `VarDef <https://help.semmle.com/qldoc/javascript/semmle/javascript/DefUse.qll/type.DefUse$VarDef.html>`__, that is, a definition like ``x = 1`` appearing explicitly in the source code.
#. Implicit inits (`SsaImplicitInit <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaImplicitInit.html>`__): these represent the implicit initialization of local variables with ``undefined`` at the beginning of their scope.
#. Implicit initializations (`SsaImplicitInit <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaImplicitInit.html>`__): these represent the implicit initialization of local variables with ``undefined`` at the beginning of their scope.
#. Phi nodes (`SsaPhiNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaPhiNode.html>`__): these are pseudo-definitions that merge two or more SSA definitions where necessary; see the Wikipedia page linked to above for an explanation.
#. Variable captures (`SsaVariableCapture <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaVariableCapture.html>`__): these are pseudo-definitions appearing at places in the code where the value of a captured variable may change without there being an explicit assignment, for example due to a function call.
#. Refinement nodes (`SsaRefinementNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaRefinementNode.html>`__): these are pseudo-definitions appearing at places in the code where something becomes known about a variable; for example, a conditional ``if (x === null)`` induces a refinement node at the beginning of its "then" branch recording the fact that ``x`` is known to be ``null`` there. (In the literature, these are sometimes known as "pi nodes".)
#. Refinement nodes (`SsaRefinementNode <https://help.semmle.com/qldoc/javascript/semmle/javascript/SSA.qll/type.SSA$SsaRefinementNode.html>`__): these are pseudo-definitions appearing at places in the code where something becomes known about a variable; for example, a conditional ``if (x === null)`` induces a refinement node at the beginning of its "then" branch recording the fact that ``x`` is known to be ``null`` there. (In the literature, these are sometimes known as "pi nodes.")
Data flow nodes
^^^^^^^^^^^^^^^
@@ -638,20 +638,20 @@ For example, here is a query that finds all invocations of a method called ``sen
send.getMethodName() = "send"
select send
➤ `See this in the query console <https://lgtm.com/query/1506058347056/>`__. The query finds HTTP response sends in the `amphtml <https://lgtm.com/projects/g/ampproject/amphtml>`__ project.
➤ `See this in the query console <https://lgtm.com/query/1506058347056/>`__. The query finds HTTP response sends in the `AMP HTML <https://lgtm.com/projects/g/ampproject/amphtml>`__ project.
Note that the data flow modeling in this library is intra-procedural, that is, flow across function calls and returns is *not* modeled. Likewise, flow through object properties and global variables is not modeled.
Note that the data flow modeling in this library is intraprocedural, that is, flow across function calls and returns is *not* modeled. Likewise, flow through object properties and global variables is not modeled.
Type inference
~~~~~~~~~~~~~~
The library ``semmle.javascript.dataflow.TypeInference`` implements a simple type inference for JavaScript based on intra-procedural, heap-insensitive flow analysis. Basically, the inference algorithm approximates the possible concrete runtime values of variables and expressions as sets of abstract values (represented by QL class `AbstractValue <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/AbstractValues.qll/type.AbstractValues$AbstractValue.html>`__), each of which stands for a set of concrete values.
The library ``semmle.javascript.dataflow.TypeInference`` implements a simple type inference for JavaScript based on intraprocedural, heap-insensitive flow analysis. Basically, the inference algorithm approximates the possible concrete runtime values of variables and expressions as sets of abstract values (represented by QL class `AbstractValue <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/AbstractValues.qll/type.AbstractValues$AbstractValue.html>`__), each of which stands for a set of concrete values.
For example, there is an abstract value representing all non-zero numbers, and another representing all non-empty strings except for those that can be converted to a number. Both of these abstract values are fairly coarse approximations that represent very large sets of concrete values.
Other abstract values are more precise, to the point where they represent single concrete values: for example, there is an abstract value representing the concrete ``null`` value, and another representing the number zero.
There is a special group of abstract values called *indefinite* abstract values that represent all concrete values. The analysis uses these to handle expressions for which it cannot infer a more precise value, such as function parameters (as mentioned above, the analysis is intra-procedural and hence does not model argument passing) or property reads (the analysis does not model property values either).
There is a special group of abstract values called *indefinite* abstract values that represent all concrete values. The analysis uses these to handle expressions for which it cannot infer a more precise value, such as function parameters (as mentioned above, the analysis is intraprocedural and hence does not model argument passing) or property reads (the analysis does not model property values either).
Each indefinite abstract value is associated with a string value describing the cause of imprecision. In the above examples, the indefinite value for the parameter would have cause ``"call"``, while the indefinite value for the property would have cause ``"heap"``.
@@ -708,13 +708,13 @@ As an example of a call-graph-based query, here is a query to find call sites fo
Inter-procedural data flow
~~~~~~~~~~~~~~~~~~~~~~~~~~
The data flow graph-based analyses described so far are all intra-procedural: they do not take flow from function arguments to parameters or from a ``return`` to the function's caller into account. The data flow library also provides a framework for constructing custom inter-procedural analyses.
The data flow graph-based analyses described so far are all intraprocedural: they do not take flow from function arguments to parameters or from a ``return`` to the function's caller into account. The data flow library also provides a framework for constructing custom inter-procedural analyses.
We distinguish here between data flow proper, and *taint tracking*: the latter not only considers value-preserving flow (such as from variable definitions to uses), but also cases where one value influences ("taints") another without determining it entirely. For example, in the assignment ``s2 = s1.substring(i)``, the value of ``s1`` influences the value of ``s2``, because ``s2`` is assigned a substring of ``s1``. In general, ``s2`` will not be assigned ``s1`` itself, so there is no data flow from ``s1`` to ``s2``, but ``s1`` still taints ``s2``.
The simplest way of implementing an inter-procedural data flow analysis is to extend either class ``DataFlow::TrackedNode`` or ``DataFlow::TrackedExpr``. The former is a subclass of ``DataFlow::Node``, the latter of ``Expr``, and extending them ensures that the newly added values are tracked inter-procedurally. You can use the predicate ``flowsTo`` to find out which nodes/expressions the tracked value flows to.
The simplest way of implementing an interprocedural data flow analysis is to extend either class ``DataFlow::TrackedNode`` or ``DataFlow::TrackedExpr``. The former is a subclass of ``DataFlow::Node``, the latter of ``Expr``, and extending them ensures that the newly added values are tracked interprocedurally. You can use the predicate ``flowsTo`` to find out which nodes/expressions the tracked value flows to.
For example, suppose that we are developing an analysis to find hard-coded passwords. We might start by writing a simple query that looks for string constants flowing into variables named "password". To do this, we can extend ``TrackedExpr`` to track all constant strings, ``flowsTo`` to find cases where such a string flows into a (SSA) definition of a password variable:
For example, suppose that we are developing an analysis to find hard-coded passwords. We might start by writing a simple query that looks for string constants flowing into variables named ``"password"``. To do this, we can extend ``TrackedExpr`` to track all constant strings, ``flowsTo`` to find cases where such a string flows into a (SSA) definition of a password variable:
.. code-block:: ql
@@ -789,7 +789,7 @@ Syntax errors
JavaScript code that contains syntax errors cannot usually be analyzed. For such code, the lexical and syntactic representations are not available, and hence no name binding information, call graph or control and data flow. All that is available in this case is a value of class `JSParseError <https://help.semmle.com/qldoc/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html>`__ representing the syntax error. It provides information about the syntax error location (`JSParseError <https://help.semmle.com/qldoc/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html>`__ is a subclass of `Locatable <https://help.semmle.com/qldoc/javascript/semmle/javascript/Locations.qll/type.Locations$Locatable.html>`__) and the error message through predicate ``JSParseError.getMessage``.
Note that for some very simple syntax errors the parser can recover and continue parsing. In this case, lexical and syntactic information is available in addition to the `JSParseError <https://help.semmle.com/qldoc/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html>`__ values representing the (recoverable) syntax errors encountered during parsing.
Note that for some very simple syntax errors the parser can recover and continue parsing. If this happens, lexical and syntactic information is available in addition to the `JSParseError <https://help.semmle.com/qldoc/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html>`__ values representing the (recoverable) syntax errors encountered during parsing.
Frameworks
~~~~~~~~~~
@@ -806,7 +806,9 @@ The ``semmle.javascript.frameworks.AngularJS`` library provides support for work
HTTP framework libraries
^^^^^^^^^^^^^^^^^^^^^^^^
The library ``semmle.javacript.frameworks.HTTP`` provides classes modeling common concepts from various HTTP frameworks. Currently supported frameworks are `Express <https://expressjs.com/>`__, the standard Node.js ``http`` and ``https`` modules, `Connect <https://github.com/senchalabs/connect>`__, `Koa <https://koajs.com>`__, `Hapi <https://hapijs.com/>`__ and `Restify <https://restify.com/>`__.
The library ``semmle.javacript.frameworks.HTTP`` provides classes modeling common concepts from various HTTP frameworks.
Currently supported frameworks are `Express <https://expressjs.com/>`__, the standard Node.js ``http`` and ``https`` modules, `Connect <https://github.com/senchalabs/connect>`__, `Koa <https://koajs.com>`__, `Hapi <https://hapijs.com/>`__ and `Restify <https://restify.com/>`__.
The most important classes include (all in module ``HTTP``):
@@ -825,7 +827,7 @@ Node.js
The ``semmle.javascript.NodeJS`` library provides support for working with `Node.js <http://nodejs.org/>`__ modules through the following QL classes:
- `NodeModule <https://help.semmle.com/qldoc/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$NodeModule.html>`__: a toplevel that defines a Node.js module; see the section on `Modules <#modules>`__ for more information.
- `NodeModule <https://help.semmle.com/qldoc/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$NodeModule.html>`__: a top-level that defines a Node.js module; see the section on `Modules <#modules>`__ for more information.
- `Require <https://help.semmle.com/qldoc/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$Require.html>`__: a call to the special ``require`` function that imports a module.
As an example of the use of these classes, here is a query that counts for every module how many other modules it imports:
@@ -876,7 +878,8 @@ The ``semmle.javascript.frameworks.React`` library provides support for working
Databases
^^^^^^^^^
The class ``SQL::SqlString`` represents an expression that is interpreted as a SQL command. Currently, we model SQL commands issued through the following npm packages: `mysql <https://www.npmjs.com/package/mysql>`__, `pg <https://www.npmjs.com/package/pg>`__, ```pg-pool`` <https://www.npmjs.com/package/pg-pool>`__, `sqlite3 <https://www.npmjs.com/package/sqlite3>`__, `mssql <https://www.npmjs.com/package/mssql>`__ and `sequelize <https://www.npmjs.com/package/sequelize>`__.
The class ``SQL::SqlString`` represents an expression that is interpreted as a SQL command. Currently, we model SQL commands issued through the following npm packages:
`mysql <https://www.npmjs.com/package/mysql>`__, `pg <https://www.npmjs.com/package/pg>`__, `pg-pool <https://www.npmjs.com/package/pg-pool>`__, `sqlite3 <https://www.npmjs.com/package/sqlite3>`__, `mssql <https://www.npmjs.com/package/mssql>`__ and `sequelize <https://www.npmjs.com/package/sequelize>`__.
Similarly, the class ``NoSQL::Query`` represents an expression that is interpreted as a NoSQL query by the ``mongodb`` or ``mongoose`` package.

6
docs/ql-documentation/learn-ql/locations.rst
View File

@@ -59,7 +59,7 @@ The following, less-common types of URL are valid QL but are not supported by LG
- **HTTP URLs** are supported in some client applications. For an example, see the code snippet above.
- **Folder URLs** can be useful, for example to provide folder-level metrics. They may use a file URL, for example ``file:///opt/src:0:0:0:0``, but they may also start with a scheme of ``folder://``, and no trailing numbers, for example ``folder:///opt/src``.
- **Relative file URLs** are like normal file URLs, but start with the scheme ``relative://``. They are typically only meaningful in the context of a particular snapshot, and are taken to be implicitly prefixed by the snapshot's source location. Note that, in particular, the relative URL for a file will stay constant regardless of where the snapshot is analyzed. It is often most convenient to produce these URLs as input when importing external information; selecting one from a QL class would be unusual, and client applications may not handle it appropriately.
- **Relative file URLs** are like normal file URLs, but start with the scheme ``relative://``. They are typically only meaningful in the context of a particular snapshot, and are taken to be implicitly prefixed by the snapshot's source location. Note that, in particular, the relative URL of a file will stay constant regardless of where the snapshot is analyzed. It is often most convenient to produce these URLs as input when importing external information; selecting one from a QL class would be unusual, and client applications may not handle it appropriately.
Providing location information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -106,7 +106,7 @@ Finally, if the above two predicates fail, client applications will attempt to c
By convention, the return value of the ``getLocation()`` predicate should be a QL class called ``Location``, and it should define a version of ``hasLocationInfo(..)`` (or ``getURL()``, though the former is preferable). If the ``Location`` class does not provide either of these member predicates, then no location information will be available.
The toString() predicate
------------------------
The ``toString()`` predicate
----------------------------
All classes except those that extend primitive types, must provide a ``string toString()`` member predicate. The query compiler will complain if you don't. The uniqueness warning, noted above for locations, applies here too.

8
docs/ql-documentation/learn-ql/python/control-flow.rst
View File

@@ -3,8 +3,8 @@ Tutorial: Control flow analysis
In order to analyze the `Control-flow graph <http://en.wikipedia.org/wiki/Control_flow_graph>`__ of a ``Scope`` we can use the two QL classes ``ControlFlowNode`` and ``BasicBlock``. These classes allow you to ask such questions as "can you reach point A from point B?" or "Is it possible to reach point B *without* going through point A?". To report results we use the class ``AstNode``, which represents a syntactic element and corresponds to the source code - allowing the results of the query to be more easily understood.
The 'ControlFlowNode' class
---------------------------
The ``ControlFlowNode`` class
-----------------------------
The ``ControlFlowNode`` class represents nodes in the control flow graph. There is a one-to-many relation between AST nodes and control flow nodes. Each syntactic element, the ``AstNode,`` maps to zero, one or many ``ControlFlowNode`` classes, but each ControlFlowNode maps to exactly one ``AstNode``.
@@ -47,8 +47,8 @@ The simplest use of the ``ControlFlowNode`` and ``AstNode`` classes is to find u
➤ `See this in the query console <https://lgtm.com/query/670720181/>`__. This query gives fewer results, but most of the projects have some unreachable nodes. These are also highlighted by the standard query: `Unreachable code <https://lgtm.com/rules/3980095>`__.
The 'BasicBlock' class
----------------------
The ``BasicBlock`` class
------------------------
The ``BasicBlock`` class represents a `basic block <http://en.wikipedia.org/wiki/Basic_block>`__ of control flow nodes. The ``BasicBlock`` class is not that useful for writing queries directly, but is very useful for building complex analyses, such as data flow. The reason it is useful is that it shares many of the interesting properties of control flow nodes, such as what can reach what and what `dominates <http://en.wikipedia.org/wiki/Dominator_%28graph_theory%29>`__ what, but there are fewer basic blocks than control flow nodes - resulting in queries that are faster and use less memory.

2
docs/ql-documentation/learn-ql/python/functions.rst
View File

@@ -37,7 +37,7 @@ You can modify the query above to return more interesting results. As we are onl
where f.getName().matches("get%") and f.isMethod()
select f, "This is a method called get..."
➤ `See this in the query console <https://lgtm.com/query/690010035/>`__. This finds methods whose name starts with "get", but many of those are not the sort of simple getters we are interested in.
➤ `See this in the query console <https://lgtm.com/query/690010035/>`__. This finds methods whose name starts with ``"get"``, but many of those are not the sort of simple getters we are interested in.
Finding one line methods called "get..."
----------------------------------------

10
docs/ql-documentation/learn-ql/python/introduce-libraries-python.rst
View File

@@ -127,7 +127,7 @@ For our first example, we can find all ``finally`` blocks by using the ``Try`` c
➤ `See this in the query console <https://lgtm.com/query/659662193/>`__. Many projects include examples of this pattern.
2. Finding 'except' blocks that do nothing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
''''''''''''''''''''''''''''''''''''''''''
For our second example, we can use a simplified version of a query from the standard query set. We look for all ``except`` blocks that do nothing.
@@ -137,7 +137,7 @@ A block that does nothing is one that contains no statements except ``pass`` sta
not exists(Stmt s | s = ex.getAStmt() | not s instanceof Pass)
where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass`` statements. Instead of using the double negative, **"no**\ *statements that are*\ **not**\ *pass statements"*, this can also be expressed positively, "all statements must be pass statements". The positive form is expressed in QL using the ``forall`` quantifier:
where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass`` statements. Instead of using the double negative, **"no**\ *statements that are*\ **not**\ *pass statements"*, this can also be expressed positively, "all statements must be pass statements." The positive form is expressed in QL using the ``forall`` quantifier:
.. code-block:: ql
@@ -164,7 +164,7 @@ The most commonly used standard QL library classes in the syntactic part of the
``Module``, ``Class``, ``Function``, ``Stmt`` and ``Expr`` - they are all subclasses of `AstNode <https://help.semmle.com/qldoc/python/semmle/python/AST.qll/type.AST$AstNode.html>`__.
Abstract Syntax Tree
Abstract syntax tree
''''''''''''''''''''
- ``AstNode``
@@ -243,7 +243,7 @@ Other
Control flow classes
~~~~~~~~~~~~~~~~~~~~
This part of the library represents the control flow graph of each ``Scope`` (classes, functions and modules). Each ``Scope`` contains a graph of ``ControlFlowNode`` elements. Each scope has a single entry point and at least one (potentially many) exit points. To speed up control and data flow analysis, control flow nodes are grouped into `basic blocks <http://en.wikipedia.org/wiki/Basic_block>`__.
This part of the library represents the control flow graph of each ``Scope`` (classes, functions, and modules). Each ``Scope`` contains a graph of ``ControlFlowNode`` elements. Each scope has a single entry point and at least one (potentially many) exit points. To speed up control and data flow analysis, control flow nodes are grouped into `basic blocks <http://en.wikipedia.org/wiki/Basic_block>`__.
As an example, we might want to find the longest sequence of code without any branches. A ``BasicBlock`` is, by definition, a sequence of code without any branches, so we just need to find the longest ``BasicBlock``.
@@ -273,7 +273,7 @@ Using this predicate we can select the longest ``BasicBlock`` by selecting the `
where bb_length(b) = max(bb_length(_))
select b
➤ `See this in the query console <https://lgtm.com/query/666730036/>`__. When we ran it on the LGTM.com demo projects, the *openstack/nova* and *rg3/youtube-dl* projects both contained source code results for this query.
➤ `See this in the query console <https://lgtm.com/query/666730036/>`__. When we ran it on the LGTM.com demo projects, the *openstack/nova* and *ytdl-org/youtube-dl* projects both contained source code results for this query.
.. pull-quote::

12
docs/ql-documentation/learn-ql/python/pointsto-type-infer.rst
View File

@@ -3,8 +3,8 @@ Tutorial: Points-to analysis and type inference
This topic contains worked examples of how to write queries using the standard QL library classes for Python type inference.
The Object class
----------------
The ``Object`` class
--------------------
The ``Object`` class and its subclasses ``FunctionObject``, ``ClassObject`` and ``ModuleObject`` represent the values an expression may hold at runtime.
@@ -119,7 +119,7 @@ Combining the parts of the query we get this:
)
select t, ex1, ex2
➤ `See this in the query console <https://lgtm.com/query/669950027/>`__. This query finds only one result in the demo projects on LGTM.com (`rg3/youtub-dl <https://lgtm.com/projects/g/rg3/youtube-dl/rev/39e9d524e5fe289936160d4c599a77f10f6e9061/files/devscripts/buildserver.py#L413>`__). The result is also highlighted by the standard query: `Unreachable 'except' block <https://lgtm.com/rules/7900089>`__.
➤ `See this in the query console <https://lgtm.com/query/669950027/>`__. This query finds only one result in the demo projects on LGTM.com (`youtube-dl <https://lgtm.com/projects/g/ytdl-org/youtube-dl/rev/39e9d524e5fe289936160d4c599a77f10f6e9061/files/devscripts/buildserver.py?sort=name&dir=ASC&mode=heatmap#L413>`__). The result is also highlighted by the standard query: `Unreachable 'except' block <https://lgtm.com/rules/7900089>`__.
.. pull-quote::
@@ -130,7 +130,7 @@ Combining the parts of the query we get this:
Using type inference
--------------------
In this example we use type inference to determine when an object is used as a sequence in a ``for`` statement, but that object might not be an iterable.
In this example we use type inference to determine when an object is used as a sequence in a ``for`` statement, but that object might not be an ``"iterable"``.
First of all find what object is used in the ``for`` loop:
@@ -142,7 +142,7 @@ First of all find what object is used in the ``for`` loop:
Then we need to determine if a ``ClassObject`` is iterable. ``ClassObject`` provides the predicate ``isIterable()`` which we can combine with the longer form of ``ControlFlowNode.refersTo()`` to get the class of the loop iterator, giving us this:
**Find non-iterable used as a loop iterator**
**Find non-iterable object used as a loop iterator**
.. code-block:: ql
@@ -157,7 +157,7 @@ Then we need to determine if a ``ClassObject`` is iterable. ``ClassObject`` prov
Many of the results shown will have ``cls`` as ``NoneType``. It is more informative to show where these ``None`` values may come from. To do this we use the final field of ``refersTo``, as follows:
**Find non-iterable used as a loop iterator 2**
**Find non-iterable object used as a loop iterator 2**
.. code-block:: ql

4
docs/ql-documentation/learn-ql/python/statements-expressions.rst
View File

@@ -250,12 +250,12 @@ The condition:
attr.getObject() = self and self.getId() = "self"
checks that the value of the attribute (the expression to the left of the dot in ``value.attr``) is an access to a variable called "self".
checks that the value of the attribute (the expression to the left of the dot in ``value.attr``) is an access to a variable called ``"self"``.
Class and function definitions
------------------------------
As Python is a dynamically typed language, class and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The right hand side of the ``ClassDef`` is a ``ClassExpr`` representing the creation of the class. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassExpr.getInnerScope()``
As Python is a dynamically typed language, class, and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The right hand side of the ``ClassDef`` is a ``ClassExpr`` representing the creation of the class. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassExpr.getInnerScope()``
``FunctionDef``, ``FunctionExpr`` and ``Function`` are handled similarly.

6
docs/ql-documentation/learn-ql/python/taint-tracking.rst
View File

@@ -79,8 +79,8 @@ A simple taint tracking query has the basic form:
where config.hasFlow(src, sink)
select sink, "Alert message, including reference to $@.", src, "string describing the source"
As a contrived example, here is a query that looks for flow from a HTTP request to a function called "unsafe".
The sources are pre-defined and accessed by importing library ``semmle.python.web.HttpRequest``.
As a contrived example, here is a query that looks for flow from a HTTP request to a function called ``"unsafe"``.
The sources are predefined and accessed by importing library ``semmle.python.web.HttpRequest``.
The sink is defined by using a custom ``TaintTracking::Sink`` class.
.. code-block:: ql
@@ -226,7 +226,7 @@ The ``TaintKind`` itself is just a string (a QL string, not a QL entity represen
which provides methods to extend flow and allow the kind of taint to change along the path.
The ``TaintKind`` class has many predicates allowing flow to be modified.
This simplest ``TaintKind`` does not override any predicates, meaning that it only flows as opaque data.
An example of this is the `Hardcoded credentials query <https://lgtm.com/query/rule:1506421276400/lang:python/>`_,
An example of this is the `Hard-coded credentials query <https://lgtm.com/query/rule:1506421276400/lang:python/>`_,
which defines the simplest possible taint kind class, ``HardcodedValue``, and custom source and sink classes.
.. code-block:: ql

2
docs/ql-documentation/learn-ql/snapshot.rst
View File

@@ -1,5 +1,5 @@
What's in a snapshot database?
==============================
===============================
A snapshot database contains a variety of data related to a particular code base at a particular point in time. For details of how the database is generated see `Database generation <https://lgtm.com/help/lgtm/generate-database>`__.

2
docs/ql-documentation/learn-ql/writing-queries/path-queries.rst
View File

@@ -45,7 +45,7 @@ Constructing a path query
Path queries require certain metadata, query predicates, and ``select`` statement structures.
Many of the built-in path queries included in the Semmle tools follow a simple structure, which depends on how the language you are analyzing is modeled in QL.
For C/C++, C#, Java and JavaScript you should use the following template::
For C/C++, C#, Java, and JavaScript you should use the following template::
/**
* ...

2
docs/ql-documentation/learn-ql/writing-queries/writing-queries.rst
View File

@@ -2,7 +2,7 @@ Writing QL queries
##################
If you are familiar with QL, you can modify the existing Semmle queries or write custom queries to analyze, improve and secure your own projects. Get started by reading the information for query writers and viewing the examples provided below.
If you are familiar with QL, you can modify the existing Semmle queries or write custom queries to analyze, improve, and secure your own projects. Get started by reading the information for query writers and viewing the examples provided below.
Information for query writers
*****************************

6
docs/ql-documentation/vale-styles/Semmle/Headings.yml
View File

@@ -32,4 +32,10 @@ exceptions:
- Windows
# Semmle exceptions:
- AngularJS
- Java
- JavaScript
- JSDoc
- Node.js
- Python
- QLDoc

66
docs/ql-documentation/vale-styles/Semmle/ignore.txt
View File

@@ -1,24 +1,88 @@
# Ignore these words during spellchecking
accessors
activemq
arity
arities
autoboxing
bitwise
boolean
booleans
callable
callables
callee
callees
cyclomatic
Datalog
declarator
declarators
dereferenced
destructor
destructors
destructuring
downcasting
downcasts
enum
enums
Expr
falsy
finalizer
finalizers
getter
getters
globals
Gradle
initializer
initializers
inline
inlining
interprocedural
interprocedurally
intraprocedural
iterable
Javadoc
LGTM
lookup
lookups
monospace
monospaced
mscorlib
multiline
multimap
multimaps
multivalued
namespace
namespaces
Naur
npm
Openstack
orderable
Postgres
pragma
pragmas
preformatted
preprocessor
preprocessors
Qhelp
reachability
Saltstack
sanitization
Semmle
Stmt
subexpression
subexpressions
subtyping
supertype
supertypes
syntaxes
tokenization
unary
tooltip
tooltips
truthy
typedef
typedefs
unary
unconstructed
unititialized
untrusted
youtube