Merge pull request #2897 from mchammer01/js-migration-work

Code QL pre-migration tasks: update articles relating to CodeQL for JavaScript

Author: mchammer01

docs/language/learn-ql/javascript/ast-class-reference.rst

@@ -1,5 +1,7 @@
-AST class reference
-===================
+Abstract syntax tree classes for JavaScript and TypeScript
+==========================================================
+
+CodeQL has a large selection of classes for working with JavaScript and TypeScript statements and expressions.
 
 Statement classes
 -----------------

docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst

@@ -1,7 +1,7 @@
-Data flow cheat sheet
-=====================
+Data flow cheat sheet for JavaScript
+====================================
 
-This page describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.
+This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.
 
 Taint tracking path queries
 ---------------------------
@@ -39,7 +39,7 @@ See also: `Global data flow <https://help.semmle.com/QL/learn-ql/javascript/data
 DataFlow module
 ---------------
 
-Use data flow nodes to match program elements independently of syntax. See also: :doc:`Analyzing data flow in JavaScript/TypeScript <dataflow>`.
+Use data flow nodes to match program elements independently of syntax. See also: :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`.
 
 Predicates in the ``DataFlow::`` module:
 
@@ -142,7 +142,7 @@ Files
 AST nodes
 ---------
 
-See also: :doc:`AST class reference <ast-class-reference>`.
+See also: :doc:`Abstract syntax tree classes for JavaScript and TypeScript <ast-class-reference>`.
 
 Conversion between DataFlow and AST nodes:
 
@@ -163,7 +163,7 @@ String matching
 Type tracking
 -------------
 
-See also: :doc:`Type tracking tutorial <type-tracking>`.
+See also: :doc:`Using type tracking for API modeling <type-tracking>`.
 
 Use the following template to define forward type tracking predicates:
 

docs/language/learn-ql/javascript/dataflow.rst

@@ -1,12 +1,11 @@
 Analyzing data flow in JavaScript and TypeScript
 ================================================
 
-Overview
---------
-
 This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
-The following sections describe how to utilize the libraries for local data flow, global data flow, and taint tracking.
 
+Overview
+--------
+The various sections in this article describe how to utilize the libraries for local data flow, global data flow, and taint tracking.
 As our running example, we will develop a query that identifies command-line arguments that are passed as a file path to the standard Node.js ``readFile`` function.
 While this is not a problematic pattern as such, it is typical of the kind of reasoning that is frequently used in security queries.
 
@@ -470,7 +469,7 @@ What next?
 
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
--  Learn about writing more precise data-flow analyses in :doc:`Advanced data-flow analysis using flow labels <flow-labels>`
+-  Learn about writing more precise data-flow analyses in :doc:`Using flow labels for precise data flow analysis <flow-labels>`
 
 Answers
 -------

docs/language/learn-ql/javascript/flow-labels.rst

@@ -1,8 +1,13 @@
-Tutorial: Precise data-flow analysis using flow labels
-======================================================
+Using flow labels for precise data flow analysis
+================================================
+
+You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
+
+Overview
+--------
 
 You can use basic inter-procedural data-flow analysis and taint tracking as described in
-:doc:`Analyzing data flow in JavaScript/TypeScript <dataflow>` to check whether there is a path in
+:doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>` to check whether there is a path in
 the data-flow graph from some source node to a sink node that does not pass through any sanitizer
 nodes. Another way of thinking about this is that it statically models the flow of data through the
 program, and associates a flag with every data value telling us whether it might have come from a
@@ -390,9 +395,9 @@ tainted objects from partially tainted objects. The `Uncontrolled data used in p
 <https://lgtm.com/rules/1971530250>`_ query uses four flow labels to track whether a user-controlled
 string may be an absolute path and whether it may contain ``..`` components.
 
-What next?
-----------
+Further reading
+---------------
 
--  Learn about the standard CodeQL libraries used to write queries for JavaScript in :doc:`Introducing the JavaScript libraries <introduce-libraries-js>`.
+-  Learn about the standard CodeQL libraries used to write queries for JavaScript in :doc:`CodeQL libraries for JavaScript <introduce-libraries-js>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.

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

@@ -1,5 +1,7 @@
-Introducing the CodeQL libraries for JavaScript
-===============================================
+CodeQL libraries for JavaScript
+===============================
+
+You can use the extensive libraries described in this article to analyze databases generated from JavaScript codebases. Using these libraries makes it easier for you to write queries.
 
 Overview
 --------
@@ -1026,9 +1028,9 @@ Alias nodes are represented by class `YAMLAliasNode <https://help.semmle.com/qld
 
 Predicate ``YAMLMapping.maps(key, value)`` models the key-value relation represented by a mapping, taking merge keys into account.
 
-What next?
-----------
+Further reading
+---------------
 
--  Learn about the standard CodeQL libraries used to write queries for TypeScript in :doc:`Introducing the TypeScript libraries <introduce-libraries-ts>`.
+-  Learn about the standard CodeQL libraries used to write queries for TypeScript in :doc:`CodeQL libraries for TypeScript <introduce-libraries-ts>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.

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

@@ -1,5 +1,7 @@
-Introducing the CodeQL libraries for TypeScript
-===============================================
+CodeQL libraries for TypeScript
+===============================
+
+You can use libraries to analyze databases generated from TypeScript codebases. Using these libraries makes it easier for you to write queries.
 
 Overview
 --------
@@ -10,7 +12,7 @@ Support for analyzing TypeScript code is bundled with the CodeQL libraries for J
 
    import javascript
 
-The :doc:`CodeQL library introduction for JavaScript <introduce-libraries-js>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
+:doc:`CodeQL libraries for JavaScript <introduce-libraries-js>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
 
 Syntax
 ------
@@ -134,7 +136,7 @@ The CodeQL class `ClassOrInterface <https://help.semmle.com/qldoc/javascript/sem
 
 Note that the superclass of a class is an expression, not a type annotation. If the superclass has type arguments, it will be an expression of kind `ExpressionWithTypeArguments <https://help.semmle.com/qldoc/javascript/semmle/javascript/TypeScript.qll/type.TypeScript$ExpressionWithTypeArguments.html>`__.
 
-Also see the documentation for classes in the `Introduction to the CodeQL libraries for JavaScript <introduce-libraries-js#classes>`__.
+Also see the documentation for classes in the `CodeQL libraries for JavaScript <introduce-libraries-js#classes>`__.
 
 To select the type references to a class or an interface, use ``getTypeName()``.
 
@@ -444,9 +446,9 @@ A `LocalNamespaceName <https://help.semmle.com/qldoc/javascript/semmle/javascrip
 -  ``LocalNamespaceName.getADeclaration()`` gets an identifier that declares this local name.
 -  ``LocalNamespaceName.getNamespace()`` gets the namespace to which this name refers.
 
-What next?
-----------
+Further reading
+---------------
 
--  Learn about the standard CodeQL libraries used to write queries for JavaScript in :doc:`Introducing the JavaScript libraries <introduce-libraries-js>`.
+-  Learn about the standard CodeQL libraries used to write queries for JavaScript in :doc:`CodeQL libraries for JavaScript <introduce-libraries-js>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
--  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
+-  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.

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

@@ -1,6 +1,8 @@
 CodeQL for JavaScript
 =====================
 
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from JavaScript codebases.
+
 .. toctree::
    :glob:
    :hidden:
@@ -17,19 +19,19 @@ These documents provide an overview of the CodeQL libraries for JavaScript and T
 
 -  `Basic JavaScript query <https://lgtm.com/help/lgtm/console/ql-javascript-basic-example>`__ describes how to write and run queries using LGTM.
 
--  :doc:`Introducing the CodeQL libraries for JavaScript <introduce-libraries-js>` introduces the standard libraries used to write queries for JavaScript code. There is an extensive CodeQL library for analyzing JavaScript code. This tutorial briefly summarizes the most important classes and predicates provided by this library.
+-  :doc:`CodeQL libraries for JavaScript <introduce-libraries-js>` introduces the standard libraries used to write queries for JavaScript code. There is an extensive CodeQL library for analyzing JavaScript code. This tutorial briefly summarizes the most important classes and predicates provided by this library.
 
--  :doc:`Introducing the CodeQL libraries for TypeScript <introduce-libraries-ts>` introduces the standard libraries used to write queries for TypeScript code.
+-  :doc:`CodeQL libraries for TypeScript <introduce-libraries-ts>` introduces the standard libraries used to write queries for TypeScript code.
 
--  :doc:`Analyzing data flow in JavaScript/TypeScript <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for JavaScript/TypeScript.
+-  :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for JavaScript/TypeScript.
 
--  :doc:`Advanced data-flow analysis using flow labels <flow-labels>` shows a more advanced example of data flow analysis using flow labels.
+-  :doc:`Using flow labels for precise data flow analysis <flow-labels>` shows a more advanced example of data flow analysis using flow labels.
 
--  :doc:`AST class reference <ast-class-reference>` gives an overview of all AST classes in the standard CodeQL library for JavaScript.
+-  :doc:`Abstract syntax tree classes for JavaScript and TypeScript <ast-class-reference>` gives an overview of all AST classes in the standard CodeQL library for JavaScript.
 
--  :doc:`Data flow cheat sheet <dataflow-cheat-sheet>` lists parts of the CodeQL libraries that are commonly used for variant analysis and in data flow queries.
+-  :doc:`Data flow cheat sheet for JavaScript <dataflow-cheat-sheet>` lists parts of the CodeQL libraries that are commonly used for variant analysis and in data flow queries.
 
-Other resources
+Further reading
 ---------------
 
 -  For examples of how to query common JavaScript elements, see the `JavaScript cookbook <https://help.semmle.com/wiki/display/CBJS>`__.

docs/language/learn-ql/javascript/type-tracking.rst

@@ -1,9 +1,11 @@
-Tutorial: API modelling using type tracking
-===========================================
+Using type tracking for API modeling
+====================================
 
-This tutorial demonstrates how to build a simple model of the Firebase API
+You can track data through an API by creating a model 
 using the CodeQL type-tracking library for JavaScript.
 
+Overview
+--------
 The type-tracking library makes it possible to track values through properties and function calls,
 usually to recognize method calls and properties accessed on a specific type of object.
 
@@ -489,7 +491,7 @@ Prefer type tracking when:
 Prefer data-flow configurations when:
 
 - Tracking user-controlled data -- use `taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-taint-tracking>`__.
-- Differentiating between different kinds of user-controlled data -- use :doc:`flow labels <flow-labels>`.
+- Differentiating between different kinds of user-controlled data -- see :doc:`Using flow labels for precise data flow analysis <flow-labels>`.
 - Tracking transformations of a value through generic utility functions.
 - Tracking values through string manipulation.
 - Generating a path from source to sink -- see :doc:`constructing path queries <../writing-queries/path-queries>`.
@@ -522,4 +524,4 @@ What next?
 
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
--  Learn about writing precise data-flow analyses in :doc:`Advanced data-flow analysis using flow labels <flow-labels>`.
+-  Learn about writing precise data-flow analyses in :doc:`Using flow labels for precise data flow analysis <flow-labels>`.