From cdcb4a959971f3604917419d3320314e2fda2a92 Mon Sep 17 00:00:00 2001 From: Shati Patel <42641846+shati-patel@users.noreply.github.com> Date: Wed, 6 Jan 2021 16:34:54 +0000 Subject: [PATCH] Fix redirects from Sphinx linkcheck --- .../analyzing-control-flow-in-python.rst | 4 ++-- .../codeql-library-for-go.rst | 2 +- .../codeql-library-for-javascript.rst | 24 +++++++++---------- .../codeql-library-for-python.rst | 6 ++--- .../detecting-a-potential-buffer-overflow.rst | 2 +- ...-analysis-and-type-inference-in-python.rst | 2 +- .../about-the-ql-language.rst | 6 ++--- docs/codeql/support/index.rst | 2 +- .../about-codeql-queries.rst | 4 ++-- 9 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/codeql/codeql-language-guides/analyzing-control-flow-in-python.rst b/docs/codeql/codeql-language-guides/analyzing-control-flow-in-python.rst index a2780350a02..22b7cd1edb5 100644 --- a/docs/codeql/codeql-language-guides/analyzing-control-flow-in-python.rst +++ b/docs/codeql/codeql-language-guides/analyzing-control-flow-in-python.rst @@ -8,7 +8,7 @@ You can write CodeQL queries to explore the control-flow graph of a Python progr About analyzing control flow -------------------------------------- -To analyze the control-flow graph of a ``Scope`` we can use the two CodeQL 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. For more information, see `Control-flow graph `__ on Wikipedia. +To analyze the control-flow graph of a ``Scope`` we can use the two CodeQL 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. For more information, see `Control-flow graph `__ on Wikipedia. The ``ControlFlowNode`` class ----------------------------- @@ -65,7 +65,7 @@ Example finding unreachable statements The ``BasicBlock`` class ------------------------ -The ``BasicBlock`` class represents a 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 what, but there are fewer basic blocks than control flow nodes - resulting in queries that are faster and use less memory. For more information, see `Basic block `__ and `Dominator `__ on Wikipedia. +The ``BasicBlock`` class represents a 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 what, but there are fewer basic blocks than control flow nodes - resulting in queries that are faster and use less memory. For more information, see `Basic block `__ and `Dominator `__ on Wikipedia. Example finding mutually exclusive basic blocks ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-go.rst b/docs/codeql/codeql-language-guides/codeql-library-for-go.rst index fa50eaefc8d..f1f77c5150e 100644 --- a/docs/codeql/codeql-language-guides/codeql-library-for-go.rst +++ b/docs/codeql/codeql-language-guides/codeql-library-for-go.rst @@ -22,7 +22,7 @@ library by beginning your query with: Broadly speaking, the CodeQL library for Go provides two views of a Go code base: at the `syntactic level`, source code is represented as an `abstract syntax tree -`__ (AST), while at the `data-flow level` it is +`__ (AST), while at the `data-flow level` it is represented as a `data-flow graph `__ (DFG). In between, there is also an intermediate representation of the program as a control-flow graph (CFG), though this representation is rarely useful on its own and mostly used to construct the higher-level diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-javascript.rst b/docs/codeql/codeql-language-guides/codeql-library-for-javascript.rst index 1a3fd411dd6..d88b8b10d57 100644 --- a/docs/codeql/codeql-language-guides/codeql-library-for-javascript.rst +++ b/docs/codeql/codeql-language-guides/codeql-library-for-javascript.rst @@ -184,7 +184,7 @@ As an example of a query using only lexical information, consider the following Syntactic level ~~~~~~~~~~~~~~~ -The majority of classes in the JavaScript library is concerned with representing a JavaScript program as a collection of `abstract syntax trees `__ (ASTs). +The majority of classes in the JavaScript library is concerned with representing a JavaScript program as a collection of `abstract syntax trees `__ (ASTs). The class `ASTNode `__ contains all entities representing nodes in the abstract syntax trees and defines generic tree traversal predicates: @@ -560,10 +560,10 @@ The structure of the control flow graph is reflected in the member predicates of - ``ControlFlowNode.isJoin()`` determines whether this node has more than one predecessor. - ``ControlFlowNode.isStart()`` determines whether this node is a start node. -Many control-flow-based analyses are phrased in terms of `basic blocks `__ rather than single control flow nodes, where a basic block is a maximal sequence of control flow nodes without branches or joins. The class `BasicBlock `__ from `BasicBlocks.qll `__ represents all such basic blocks. Similar to `ControlFlowNode `__, it provides member predicates ``getASuccessor()`` and ``getAPredecessor()`` to navigate the control flow graph at the level of basic blocks, and member predicates ``getANode()``, ``getNode(int)``, ``getFirstNode()`` and ``getLastNode()`` to access individual control flow nodes within a basic block. The predicate +Many control-flow-based analyses are phrased in terms of `basic blocks `__ rather than single control flow nodes, where a basic block is a maximal sequence of control flow nodes without branches or joins. The class `BasicBlock `__ from `BasicBlocks.qll `__ represents all such basic blocks. Similar to `ControlFlowNode `__, it provides member predicates ``getASuccessor()`` and ``getAPredecessor()`` to navigate the control flow graph at the level of basic blocks, and member predicates ``getANode()``, ``getNode(int)``, ``getFirstNode()`` and ``getLastNode()`` to access individual control flow nodes within a basic block. The predicate ``Function.getEntryBB()`` returns the entry basic block in a function, that is, the basic block containing the function's entry node. Similarly, ``Function.getStartBB()`` provides access to the start basic block, which contains the function's start node. As for CFG nodes, ``getStartBB()`` should normally be preferred over ``getEntryBB()``. -As an example of an analysis using basic blocks, ``BasicBlock.isLiveAtEntry(v, u)`` determines whether variable ``v`` is `live `__ at the entry of the given basic block, and if so binds ``u`` to a use of ``v`` that refers to its value at the entry. We can use it to find global variables that are used in a function where they are not live (that is, every read of the variable is preceded by a write), suggesting that the variable was meant to be declared as a local variable instead: +As an example of an analysis using basic blocks, ``BasicBlock.isLiveAtEntry(v, u)`` determines whether variable ``v`` is `live `__ at the entry of the given basic block, and if so binds ``u`` to a use of ``v`` that refers to its value at the entry. We can use it to find global variables that are used in a function where they are not live (that is, every read of the variable is preceded by a write), suggesting that the variable was meant to be declared as a local variable instead: .. code-block:: ql @@ -582,7 +582,7 @@ Data flow Definitions and uses ^^^^^^^^^^^^^^^^^^^^ -Library `DefUse.qll `__ provides classes and predicates to determine `def-use `__ relationships between definitions and uses of variables. +Library `DefUse.qll `__ provides classes and predicates to determine `def-use `__ relationships between definitions and uses of variables. Classes `VarDef `__ and `VarUse `__ contain all expressions that define and use a variable, respectively. For the former, you can use predicate ``VarDef.getAVariable()`` to find out which variables are defined by a given variable definition (recall that destructuring assignments in ECMAScript 2015 define several variables at the same time). Similarly, predicate ``VarUse.getVariable()`` returns the (single) variable being accessed by a variable use. @@ -686,7 +686,7 @@ You can add custom type inference rules by defining new subclasses of ``DataFlow Call graph ~~~~~~~~~~ -The JavaScript library implements a simple `call graph `__ construction algorithm to statically approximate the possible call targets of function calls and ``new`` expressions. Due to the dynamically typed nature of JavaScript and its support for higher-order functions and reflective language features, building static call graphs is quite difficult. Simple call graph algorithms tend to be incomplete, that is, they often fail to resolve all possible call targets. More sophisticated algorithms can suffer from the opposite problem of imprecision, that is, they may infer many spurious call targets. +The JavaScript library implements a simple `call graph `__ construction algorithm to statically approximate the possible call targets of function calls and ``new`` expressions. Due to the dynamically typed nature of JavaScript and its support for higher-order functions and reflective language features, building static call graphs is quite difficult. Simple call graph algorithms tend to be incomplete, that is, they often fail to resolve all possible call targets. More sophisticated algorithms can suffer from the opposite problem of imprecision, that is, they may infer many spurious call targets. The call graph is represented by the member predicate ``getACallee()`` of class `DataFlow::InvokeNode `__, which computes possible callees of the given invocation, that is, functions that may at runtime be invoked by this expression. @@ -801,7 +801,7 @@ Frameworks AngularJS ^^^^^^^^^ -The ``semmle.javascript.frameworks.AngularJS`` library provides support for working with `AngularJS (Angular 1.x) `__ code. Its most important classes are: +The ``semmle.javascript.frameworks.AngularJS`` library provides support for working with `AngularJS (Angular 1.x) `__ code. Its most important classes are: - `AngularJS::AngularModule `__: an Angular module - `AngularJS::DirectiveDefinition `__, `AngularJS::FactoryRecipeDefinition `__, `AngularJS::FilterDefinition `__, `AngularJS::ControllerDefinition `__: a definition of a directive, service, filter or controller, respectively @@ -812,7 +812,7 @@ HTTP framework libraries The library ``semmle.javacript.frameworks.HTTP`` provides classes modeling common concepts from various HTTP frameworks. -Currently supported frameworks are `Express `__, the standard Node.js ``http`` and ``https`` modules, `Connect `__, `Koa `__, `Hapi `__ and `Restify `__. +Currently supported frameworks are `Express `__, the standard Node.js ``http`` and ``https`` modules, `Connect `__, `Koa `__, `Hapi `__ and `Restify `__. The most important classes include (all in module ``HTTP``): @@ -848,7 +848,7 @@ As an example of the use of these classes, here is a query that counts for every NPM ^^^ -The ``semmle.javascript.NPM`` library provides support for working with `NPM `__ packages through the following classes: +The ``semmle.javascript.NPM`` library provides support for working with `NPM `__ packages through the following classes: - `PackageJSON `__: a ``package.json`` file describing an NPM package; various getter predicates are available for accessing detailed information about the package, which are described in the `online API documentation `__. - `BugTrackerInfo `__, `ContributorInfo `__, `RepositoryInfo `__: these classes model parts of the ``package.json`` file providing information on bug tracking systems, contributors and repositories. @@ -877,7 +877,7 @@ As an example of the use of these classes, here is a query that identifies unuse React ^^^^^ -The ``semmle.javascript.frameworks.React`` library provides support for working with `React `__ code through the `ReactComponent `__ class, which models a React component defined either in the functional style or the class-based style (both ECMAScript 2015 classes and old-style ``React.createClass`` classes are supported). +The ``semmle.javascript.frameworks.React`` library provides support for working with `React `__ code through the `ReactComponent `__ class, which models a React component defined either in the functional style or the class-based style (both ECMAScript 2015 classes and old-style ``React.createClass`` classes are supported). Databases ^^^^^^^^^ @@ -940,7 +940,7 @@ Both ``HTML::Element`` and ``HTML::Attribute`` have a predicate ``getRoot()`` th JSDoc ^^^^^ -The ``semmle.javascript.JSDoc`` library provides support for working with `JSDoc comments `__. Documentation comments are parsed into an abstract syntax tree representation closely following the format employed by the `Doctrine `__ JSDoc parser. +The ``semmle.javascript.JSDoc`` library provides support for working with `JSDoc comments `__. Documentation comments are parsed into an abstract syntax tree representation closely following the format employed by the `Doctrine `__ JSDoc parser. A JSDoc comment as a whole is represented by an entity of class `JSDoc `__, while individual tags are represented by class `JSDocTag `__. Important member predicates of these two classes include: @@ -972,7 +972,7 @@ For full details on these and other classes representing JSDoc comments and type JSX ^^^ -The ``semmle.javascript.JSX`` library provides support for working with `JSX code `__. +The ``semmle.javascript.JSX`` library provides support for working with `JSX code `__. Similar to the representation of HTML documents, JSX fragments are modeled as a tree of `JSXElement `__\ s, each of which may have zero or more `JSXAttribute `__\ s. @@ -1011,7 +1011,7 @@ Various subclasses of `RegExpTerm `__ files that were processed by the JavaScript extractor when building the CodeQL database. +The ``semmle.javascript.YAML`` library provides support for working with `YAML `__ files that were processed by the JavaScript extractor when building the CodeQL database. YAML files are modeled as trees of YAML nodes. Each YAML node is represented by an entity of class `YAMLNode `__, which provides, among others, the following member predicates: diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-python.rst b/docs/codeql/codeql-language-guides/codeql-library-for-python.rst index 0e51ca186af..466e100b146 100644 --- a/docs/codeql/codeql-language-guides/codeql-library-for-python.rst +++ b/docs/codeql/codeql-language-guides/codeql-library-for-python.rst @@ -26,7 +26,7 @@ The CodeQL library for Python incorporates a large number of classes. Each class Syntactic classes ----------------- -This part of the library represents the Python source code. The ``Module``, ``Class``, and ``Function`` classes correspond to Python modules, classes, and functions respectively, collectively these are known as ``Scope`` classes. Each ``Scope`` contains a list of statements each of which is represented by a subclass of the class ``Stmt``. Statements themselves can contain other statements or expressions which are represented by subclasses of ``Expr``. Finally, there are a few additional classes for the parts of more complex expressions such as list comprehensions. Collectively these classes are subclasses of ``AstNode`` and form an Abstract syntax tree (AST). The root of each AST is a ``Module``. Symbolic information is attached to the AST in the form of variables (represented by the class ``Variable``). For more information, see `Abstract syntax tree `__ and `Symbolic information `__ on Wikipedia. +This part of the library represents the Python source code. The ``Module``, ``Class``, and ``Function`` classes correspond to Python modules, classes, and functions respectively, collectively these are known as ``Scope`` classes. Each ``Scope`` contains a list of statements each of which is represented by a subclass of the class ``Stmt``. Statements themselves can contain other statements or expressions which are represented by subclasses of ``Expr``. Finally, there are a few additional classes for the parts of more complex expressions such as list comprehensions. Collectively these classes are subclasses of ``AstNode`` and form an Abstract syntax tree (AST). The root of each AST is a ``Module``. Symbolic information is attached to the AST in the form of variables (represented by the class ``Variable``). For more information, see `Abstract syntax tree `__ and `Symbolic information `__ on Wikipedia. Scope ^^^^^ @@ -241,7 +241,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. For more information, see `Basic block `__ on Wikipedia. +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. For more information, see `Basic block `__ on Wikipedia. Example ^^^^^^^ @@ -311,7 +311,7 @@ For example, which ``ClassValue``\ s are iterable can be determined using the qu where cls.hasAttribute("__iter__") select cls -➤ `See this in the query console on LGTM.com `__ This query returns a list of classes for the projects analyzed. If you want to include the results for ``builtin`` classes, which do not have any Python source code, show the non-source results. For more information, see `builtin classes `__ in the Python documentation. +➤ `See this in the query console on LGTM.com `__ This query returns a list of classes for the projects analyzed. If you want to include the results for ``builtin`` classes, which do not have any Python source code, show the non-source results. For more information, see `builtin classes `__ in the Python documentation. Summary ^^^^^^^ diff --git a/docs/codeql/codeql-language-guides/detecting-a-potential-buffer-overflow.rst b/docs/codeql/codeql-language-guides/detecting-a-potential-buffer-overflow.rst index 6edb08e7e4d..ca52df98f73 100644 --- a/docs/codeql/codeql-language-guides/detecting-a-potential-buffer-overflow.rst +++ b/docs/codeql/codeql-language-guides/detecting-a-potential-buffer-overflow.rst @@ -97,7 +97,7 @@ When you have defined the basic query then you can refine the query to include f Improving the query using the 'SSA' library ------------------------------------------- -The ``SSA`` library represents variables in static single assignment (SSA) form. In this form, each variable is assigned exactly once and every variable is defined before it is used. The use of SSA variables simplifies queries considerably as much of the local data flow analysis has been done for us. For more information, see `Static single assignment `__ on Wikipedia. +The ``SSA`` library represents variables in static single assignment (SSA) form. In this form, each variable is assigned exactly once and every variable is defined before it is used. The use of SSA variables simplifies queries considerably as much of the local data flow analysis has been done for us. For more information, see `Static single assignment `__ on Wikipedia. Including examples where the string size is stored before use ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/codeql/codeql-language-guides/pointer-analysis-and-type-inference-in-python.rst b/docs/codeql/codeql-language-guides/pointer-analysis-and-type-inference-in-python.rst index 61a4ea3f1e5..85896bc5479 100644 --- a/docs/codeql/codeql-language-guides/pointer-analysis-and-type-inference-in-python.rst +++ b/docs/codeql/codeql-language-guides/pointer-analysis-and-type-inference-in-python.rst @@ -24,7 +24,7 @@ Class hierarchy for ``Value``: Points-to analysis and type inference ------------------------------------- -Points-to analysis, sometimes known as pointer analysis, allows us to determine which objects an expression may "point to" at runtime. Type inference allows us to infer what the types (classes) of an expression may be at runtime. For more information, see `Pointer analysis `__ and `Type inference `__ on Wikipedia. +Points-to analysis, sometimes known as pointer analysis, allows us to determine which objects an expression may "point to" at runtime. Type inference allows us to infer what the types (classes) of an expression may be at runtime. For more information, see `Pointer analysis `__ and `Type inference `__ on Wikipedia. The predicate ``ControlFlowNode.pointsTo(...)`` shows which object a control flow node may "point to" at runtime. diff --git a/docs/codeql/ql-language-reference/about-the-ql-language.rst b/docs/codeql/ql-language-reference/about-the-ql-language.rst index cc292154311..59d5a31201f 100644 --- a/docs/codeql/ql-language-reference/about-the-ql-language.rst +++ b/docs/codeql/ql-language-reference/about-the-ql-language.rst @@ -64,9 +64,9 @@ Here are a few prominent conceptual and functional differences between general p Further reading --------------- -`Academic references `__ also provide an overview of QL and its semantics. Other useful references on database query languages and Datalog: +`Academic references `__ also provide an overview of QL and its semantics. Other useful references on database query languages and Datalog: -- `Database theory: Query languages `__ -- `Logic Programming and Databases book - Amazon page `__ +- `Database theory: Query languages `__ +- `Logic Programming and Databases book - Amazon page `__ - `Foundations of Databases `__ - `Datalog `__ diff --git a/docs/codeql/support/index.rst b/docs/codeql/support/index.rst index 3eac7708109..f9cdf40e227 100644 --- a/docs/codeql/support/index.rst +++ b/docs/codeql/support/index.rst @@ -11,7 +11,7 @@ For details see: language-support.rst framework-support.rst -For details of the CodeQL libraries, see `CodeQL standard libraries `_. +For details of the CodeQL libraries, see `CodeQL standard libraries `_. .. toctree:: :hidden: diff --git a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst index 09124a61f90..171d2596b3f 100644 --- a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst +++ b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst @@ -79,7 +79,7 @@ When writing your own alert queries, you would typically import the standard lib There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see ":doc:`Creating path queries `." -You can explore the contents of all the standard libraries in the `CodeQL library reference documentation `__ or in the `GitHub repository `__. +You can explore the contents of all the standard libraries in the `CodeQL library reference documentation `__ or in the `GitHub repository `__. Optional CodeQL classes and predicates -------------------------------------- @@ -119,7 +119,7 @@ Viewing the standard CodeQL queries One of the easiest ways to get started writing your own queries is to modify an existing query. To view the standard CodeQL queries, or to try out other examples, visit the `CodeQL `__ and `CodeQL for Go `__ repositories on GitHub. -You can also find examples of queries developed to find security vulnerabilities and bugs in open source software projects on the `GitHub Security Lab website `__ and in the associated `repository `__. +You can also find examples of queries developed to find security vulnerabilities and bugs in open source software projects on the `GitHub Security Lab website `__ and in the associated `repository `__. Contributing queries ********************