Merge pull request #1748 from asger-semmle/type-tracking-tutorial

JS: Type tracking tutorial

Author: jf205

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

@@ -160,6 +160,49 @@ String matching
 -  x.\ `regexpMatch <https://help.semmle.com/qldoc/javascript/predicate.string$regexpMatch.1.html>`__\ ("(?i).*escape.*") -- holds if x contains
    "escape" (case insensitive)
 
+Type tracking
+-------------
+
+See also: :doc:`Type tracking tutorial <type-tracking>`.
+
+Use the following template to define forward type tracking predicates:
+
+.. code-block:: ql
+
+  import DataFlow
+
+  SourceNode myType(TypeTracker t) {
+    t.start() and
+    result = /* SourceNode to track */
+    or
+    exists(TypeTracker t2 |
+      result = myType(t2).track(t2, t)
+    )
+  }
+
+  SourceNode myType() {
+    result = myType(TypeTracker::end())
+  }
+
+Use the following template to define backward type tracking predicates:
+
+.. code-block:: ql
+
+  import DataFlow
+
+  SourceNode myType(TypeBackTracker t) {
+    t.start() and
+    result = (/* argument to track */).getALocalSource()
+    or
+    exists(TypeBackTracker t2 |
+      result = myType(t2).backtrack(t2, t)
+    )
+  }
+
+  SourceNode myType() {
+    result = myType(TypeBackTracker::end())
+  }
+
 Troubleshooting
 ---------------
 

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

@@ -1,5 +1,5 @@
-Advanced data-flow analysis using flow labels
-=============================================
+Tutorial: Precise data-flow analysis using flow labels
+======================================================
 
 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
@@ -393,6 +393,6 @@ string may be an absolute path and whether it may contain ``..`` components.
 What next?
 ----------
 
--  Learn about the QL standard libraries used to write queries for JavaScript in :doc:`Introducing the Javacript libraries <introduce-libraries-js>`.
+-  Learn about the QL standard libraries used to write queries for JavaScript in :doc:`Introducing the JavaScript libraries <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/ql-for-javascript.rst

@@ -9,6 +9,7 @@ QL for JavaScript
    introduce-libraries-ts
    dataflow
    flow-labels
+   type-tracking
    ast-class-reference
    dataflow-cheat-sheet