Merge pull request #2294 from felicitymay/1.22-mergeback-master

1.22 mergeback master

docs/language/global-sphinx-files/global-conf.py

@@ -56,9 +56,9 @@ def setup(sphinx):
 # built documents.
 #
 # The short X.Y version.
-version = u'1.22'
+version = u'1.22.1'
 # The full version, including alpha/beta/rc tags.
-release = u'1.22'
+release = u'1.22.1'
 copyright = u'2019 Semmle Ltd'
 author = u'Semmle Ltd'
 

docs/language/learn-ql/cpp/zero-space-terminator.rst

@@ -87,6 +87,10 @@ Now we can write a query using these classes:
 
 Note that there is no need to check whether anything is added to the ``strlen`` expression, as it would be in the corrected C code ``malloc(strlen(string) + 1)``. This is because the corrected code would in fact be an ``AddExpr`` containing a ``StrlenCall``, not an instance of ``StrlenCall`` itself. A side-effect of this approach is that we omit certain unlikely patterns such as ``malloc(strlen(string) + 0``). In practice we can always come back and extend our query to cover this pattern if it is a concern.
 
+.. pull-quote::
+
+   Tip
+
    For some projects, this query may not return any results. Possibly the project you are querying does not have any problems of this kind, but it is also important to make sure the query itself is working properly. One solution is to set up a test project with examples of correct and incorrect code to run the query against (the C code at the very top of this page makes a good starting point). Another approach is to test each part of the query individually to make sure everything is working.
 
 When you have defined the basic query then you can refine the query to include further coding patterns or to exclude false positives:

docs/language/learn-ql/csharp/ql-for-csharp.rst

@@ -20,17 +20,6 @@ These topics provide an overview of the CodeQL libraries for C# and show example
 
 -  :doc:`Tutorial: Analyzing data flow in C# <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for C#.
 
-.. raw:: html
-
-   <!-- Working with call graphs(call-graph) - how to construct and query call graphs, and work with dynamic and virtual dispatch. -->
-
-.. raw:: html
-
-   <!-- Working with control flow(control-flow) - how to query intra-procedural control flow. -->
-
-.. raw:: html
-
-   <!-- Working with comments(comments) - how to query comments and XML documentation. -->
 
 Other resources
 ---------------

docs/language/learn-ql/java/call-graph.rst

@@ -78,6 +78,8 @@ Given this API, we can easily write a query that finds methods that are not call
 
 ➤ `See this in the query console <https://lgtm.com/query/665280012/>`__. This simple query typically returns a large number of results.
 
+.. pull-quote::
+
    Note
 
    We have to use ``polyCalls`` instead of ``calls`` here: we want to be reasonably sure that ``callee`` is not called, either directly or via overriding.

docs/language/learn-ql/java/expressions-statements.rst

@@ -18,6 +18,8 @@ Specifically, consider the following code snippet:
 
 If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``int``), then this loop will never terminate: ``i`` will start at zero, being incremented all the way up to 2\ :sup:`31`\ - 1, which is still smaller than ``l``. When it is incremented once more, an arithmetic overflow occurs, and ``i`` becomes -2\ :sup:`31`\, which also is smaller than ``l``! Eventually, ``i`` will reach zero again, and the cycle repeats.
 
+.. pull-quote::   
+
    More about overflow
 
    All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.

docs/language/learn-ql/java/introduce-libraries-java.rst

@@ -14,6 +14,10 @@ The library is implemented as a set of QL modules, that is, files with the exten
 
 The rest of this topic briefly summarizes the most important classes and predicates provided by this library.
 
+.. pull-quote::
+
+   Note
+
    The example queries in this topic illustrate the types of results returned by different library classes. The results themselves are not interesting but can be used as the basis for developing a more complex query. The tutorial topics show how you can take a simple query and fine-tune it to find precisely the results you're interested in.
 
 Summary of the library classes
@@ -315,7 +319,11 @@ Class ``Javadoc`` represents an entire Javadoc comment as a tree of ``JavadocEle
 
 ➤ `See this in the query console <https://lgtm.com/query/670490015/>`__. None of the LGTM.com demo projects uses the ``@author`` tag on private fields.
 
-   Note that on line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment.
+.. pull-quote::
+
+   Note
+
+   On line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment.
 
 For more information on working with Javadoc, see the :doc:`tutorial on Javadoc <javadoc>`.
 
@@ -369,7 +377,7 @@ Conversely, ``Callable.getAReference`` returns a ``Call`` that refers to it. So
    where not exists(c.getAReference())
    select c
 
-➤ `See this in the query console <https://lgtm.com/query/666680036/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see `Navigating the call graph <call-graph>`__.
+➤ `See this in the query console <https://lgtm.com/query/666680036/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see :doc:`Navigating the call graph <call-graph>`.
 
 For more information about callables and calls, see the :doc:`call graph tutorial <call-graph>`.
 

docs/language/learn-ql/java/types-class-hierarchy.rst

@@ -32,6 +32,8 @@ To determine ancestor types (including immediate super types, and also *their* s
 
 ➤ `See this in the query console <https://lgtm.com/query/674620010/>`__. If this query were run on the example snippet above, the query would return ``A``, ``I``, and ``java.lang.Object``.
 
+.. pull-quote::
+
    Tip
 
    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.

docs/language/learn-ql/javascript/introduce-libraries-js.rst

@@ -224,7 +224,7 @@ The `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.ql
 
 .. pull-quote::
 
-    Note
+   Note
 
    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.
 

docs/language/learn-ql/python/functions.rst

@@ -10,6 +10,8 @@ In this example we look for all the "getters" in a program. Programmers moving t
 
 Using the member predicate ``Function.getName()``, we can list all of the getter functions in a database:
 
+.. pull-quote::
+
    Tip
 
    Instead of copying this query, try typing the code. As you start to write a name that matches a library class, a pop-up is displayed making it easy for you to select the class that you want.

docs/language/learn-ql/python/introduce-libraries-python.rst

@@ -106,12 +106,12 @@ Examples
 
 Each syntactic element in Python source is recorded in the CodeQL database. These can be queried via the corresponding class. Let us start with a couple of simple examples.
 
-1. Finding all finally blocks
-'''''''''''''''''''''''''''''
+1. Finding all ``finally`` blocks
+'''''''''''''''''''''''''''''''''
 
 For our first example, we can find all ``finally`` blocks by using the ``Try`` class:
 
-**Find all ``finally`` blocks**
+**Find all** ``finally`` **blocks**
 
 .. code-block:: ql
 
@@ -122,8 +122,8 @@ 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
-''''''''''''''''''''''''''''''''''''''''''
+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.
 
@@ -141,7 +141,7 @@ where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass`
 
 Both forms are equivalent. Using the positive expression, the whole query looks like this:
 
-**Find pass-only ``except`` blocks**
+**Find pass-only** ``except`` **blocks**
 
 .. code-block:: ql
 

docs/language/learn-ql/python/pointsto-type-infer.rst

@@ -37,7 +37,8 @@ The predicate ``ControlFlowNode.pointsTo(...)`` shows which object a control flo
    predicate pointsTo(Context context, Value object, ControlFlowNode origin)
 
 ``object`` is an object that the control flow node refers to, and ``origin`` is where the object comes from, which is useful for displaying meaningful results.
- The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored.
+
+The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored.
 
 .. pull-quote::
 
@@ -62,7 +63,7 @@ We want to find ``except`` blocks in a ``try`` statement that are in the wrong o
 
 First we can write a query to find ordered pairs of ``except`` blocks for a ``try`` statement.
 
-**Ordered except blocks in same ``try`` statement**
+**Ordered except blocks in same** ``try`` **statement**
 
 .. code-block:: ql
 
@@ -81,7 +82,7 @@ Here ``ex1`` and ``ex2`` are both ``except`` handlers in the ``try`` statement `
 
 The results of this query need to be filtered to return only results where ``ex1`` is more general than ``ex2``. We can use the fact that an ``except`` block is more general than another block if the class it handles is a superclass of the other.
 
-**More general ``except`` block**
+**More general** ``except`` **block**
 
 .. code-block:: ql
 
@@ -102,7 +103,7 @@ ensures that ``cls1`` is a ``ClassValue`` that the ``except`` block would handle
 
 Combining the parts of the query we get this:
 
-**More general ``except`` block precedes more specific**
+**More general** ``except`` **block precedes more specific**
 
 .. code-block:: ql
 

docs/language/learn-ql/python/statements-expressions.rst

@@ -143,7 +143,7 @@ Python implementations commonly cache small integers and single character string
 
 We can check for these as follows:
 
-**Find comparisons to integer or string literals using ``is``**
+**Find comparisons to integer or string literals using** ``is``
 
 .. code-block:: ql
 
@@ -158,6 +158,8 @@ We can check for these as follows:
 
 The clause ``cmp.getOp(0) instanceof Is and cmp.getComparator(0) = literal`` checks that the first comparison operator is "is" and that the first comparator is a literal.
 
+.. pull-quote::
+
    Tip
 
    We have to use ``cmp.getOp(0)`` and ``cmp.getComparator(0)``\ as there is no ``cmp.getOp()`` or ``cmp.getComparator()``. The reason for this is that a ``Compare`` expression can have multiple operators. For example, the expression ``3 < x < 7`` has two operators and two comparators. You use ``cmp.getComparator(0)`` to get the first comparator (in this example the ``3``) and ``cmp.getComparator(1)`` to get the second comparator (in this example the ``7``).
@@ -253,9 +255,7 @@ checks that the value of the attribute (the expression to the left of the dot in
 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 ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()``
-
-``FunctionDef``, ``Function`` are handled similarly.
+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 ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()``. ``FunctionDef`` and ``Function`` are handled similarly.
 
 Here is the relevant part of the class hierarchy:
 

docs/language/support/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# QL and LGTM support info build configuration file, created 
+# CodeQL and LGTM support info build configuration file, created 
 # on Tuesday 19th February.
 #
 # This file is execfile()d with the current directory set to its

docs/language/support/framework-support.rst

@@ -1,7 +1,7 @@
 Frameworks and libraries
 ########################
 
-The QL libraries and queries in version |version| have been explicitly checked against the libraries and frameworks listed below.
+The libraries and queries in version |version| have been explicitly checked against the libraries and frameworks listed below.
 
 .. pull-quote::
 

docs/language/support/index.rst

@@ -1,7 +1,7 @@
 Supported languages and frameworks
 ##################################
 
-These pages describe the languages and frameworks supported in the latest enterprise release of QL and LGTM. 
+These pages describe the languages and frameworks supported in the latest enterprise release of CodeQL and LGTM. (CodeQL was previously known as QL.) 
 Users of `LGTM.com <https://lgtm.com/>`_ may find that additional features are supported because it's updated more frequently.
 
 For details see:
@@ -11,4 +11,4 @@ For details see:
   language-support.rst
   framework-support.rst
 
-For details of the QL libraries, see `QL standard libraries <https://help.semmle.com/QL/ql-libraries.html>`_.
+For details of the CodeQL libraries, see `CodeQL standard libraries <https://help.semmle.com/QL/ql-libraries.html>`_.

docs/language/support/language-support.rst

@@ -1,7 +1,8 @@
 Languages and compilers
 #######################
 
-QL and LGTM version |version| support analysis of the following languages compiled by the following compilers.
+CodeQL and LGTM version |version| support analysis of the following languages compiled by the following compilers.
+(CodeQL was previously known as QL.)
 
 Note that where there are several versions or dialects of a language, the supported variants are listed.
 If your code requires a particular version of a compiler, check that this version is included below. 

docs/language/support/versions-compilers.csv

@@ -10,6 +10,7 @@ C#,C# up to 7.3. with .NET up to 4.8 [3]_.,"Microsoft Visual Studio up to 2019,
 
 .NET Core up to 2.2","``.sln``, ``.csproj``, ``.cs``, ``.cshtml``, ``.xaml``"
 COBOL,ANSI 85 or newer [4]_.,Not applicable,"``.cbl``, ``.CBL``, ``.cpy``, ``.CPY``, ``.copy``, ``.COPY``"
+Go (aka Golang), "Go up to 1.13", "Go 1.11 or more recent", ``.go``
 Java,"Java 6 to 12 [5]_.","javac (OpenJDK and Oracle JDK),
 
 Eclipse compiler for Java (ECJ) [6]_.",``.java``