JS: Deprecations and related refactorings

javascript/ql/lib/semmle/javascript/dataflow/AdditionalFlowSteps.qll

@@ -28,9 +28,10 @@ private import semmle.javascript.internal.CachedStages
  *
  * This class is a singleton, and thus subclasses do not need to specify a characteristic predicate.
  *
+ * As an alternative to this class, consider using `DataFlow::SummarizedCallable`.
+ *
  * Note: For performance reasons, all subclasses of this class should be part
- * of the standard library. Override `Configuration::isAdditionalFlowStep`
- * for analysis-specific flow steps.
+ * of the standard library. Use `isAdditionalFlowStep` for query-specific flow steps.
  */
 class AdditionalFlowStep extends Unit {
   /**

javascript/ql/lib/semmle/javascript/dataflow/AdditionalTaintSteps.qll

@@ -11,9 +11,10 @@ private import semmle.javascript.internal.CachedStages
  *
  * This class is a singleton, and thus subclasses do not need to specify a characteristic predicate.
  *
+ * As an alternative to this class, consider using `DataFlow::SummarizedCallable`.
+ *
  * Note: For performance reasons, all subclasses of this class should be part
- * of the standard library. Override `Configuration::isAdditionalTaintStep`
- * for analysis-specific taint steps.
+ * of the standard library. Use `isAdditionalFlowStep` for query-specific taint steps.
  */
 class AdditionalTaintStep extends Unit {
   /**

javascript/ql/lib/semmle/javascript/dataflow/DataFlow.qll

@@ -1935,4 +1935,5 @@ module DataFlow {
   import internal.FunctionWrapperSteps
   import internal.sharedlib.DataFlow
   import internal.BarrierGuards
+  import FlowSummary
 }

javascript/ql/lib/semmle/javascript/dataflow/FlowSummary.qll

@@ -6,7 +6,49 @@ private import semmle.javascript.dataflow.internal.FlowSummaryPrivate
 private import semmle.javascript.dataflow.internal.sharedlib.DataFlowImplCommon as DataFlowImplCommon
 private import semmle.javascript.dataflow.internal.DataFlowPrivate
 
-/** A callable with a flow summary, identified by a unique string. */
+/**
+ * A model for a function that can propagate data flow.
+ *
+ * This class makes it possible to model flow through functions, using the same mechanism as
+ * `summaryModel` as described in the [library customization docs](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-javascript).
+ *
+ * Extend this class to define summary models directly in CodeQL.
+ * Data extensions and `summaryModel` are usually preferred; but there are a few cases where direct use of this class may be needed:
+ *
+ * - The relevant call sites cannot be matched by the access path syntax, and require the full power of CodeQL.
+ *   For example, complex overloading patterns might require more local reasoning at the call site.
+ * - The input/output behaviour cannot be described statically in the access path syntax, but the relevant access paths
+ *   can be generated dynamically in CodeQL, based on the usages found in the codebase.
+ *
+ * Subclasses should bind `this` to a unique identifier for the function being modelled. There is no special
+ * interpreation of the `this` value, it should just not clash with the `this`-value used by other classes.
+ *
+ * For example, this models flow through calls such as `require("my-library").myFunction()`:
+ * ```codeql
+ * class MyFunction extends SummarizedCallable {
+ *   MyFunction() { this = "MyFunction" }
+ *
+ *   override predicate propagatesFlow(string input, string output, boolean preservesValues) {
+ *     input = "Argument[0]" and
+ *     output = "ReturnValue" and
+ *     preservesValue = false
+ *   }
+ *
+ *   override DataFlow::InvokeNode getACall() {
+ *     result = API::moduleImport("my-library").getMember("myFunction").getACall()
+ *   }
+ * }
+ * ```
+ * This would be equivalent to the following model written as a data extension:
+ * ```yaml
+ * extensions:
+ *  - addsTo:
+ *      pack: codeql/javascript-all
+ *      extensible: summaryModel
+ *    data:
+ *      - ["my-library", "Member[myFunction]", "Argument[0]", "ReturnValue", "taint"]
+ * ```
+ */
 abstract class SummarizedCallable extends LibraryCallable, Impl::Public::SummarizedCallable {
   bindingset[this]
   SummarizedCallable() { any() }
@@ -15,6 +57,9 @@ abstract class SummarizedCallable extends LibraryCallable, Impl::Public::Summari
    * Holds if data may flow from `input` to `output` through this callable.
    *
    * `preservesValue` indicates whether this is a value-preserving step or a taint-step.
+   *
+   * See the [library customization docs](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-javascript) for
+   * the syntax of the `input` and `output` parameters.
    */
   pragma[nomagic]
   predicate propagatesFlow(string input, string output, boolean preservesValue) { none() }