Merge pull request #993 from asger-semmle/getacallee

JS: document new behavior of overriding InvokeNode.getACallee()

Author: Max Schaefer

change-notes/1.20/analysis-javascript.md

@@ -58,4 +58,5 @@
 * `DataFlow::SourceNode` is no longer an abstract class; to add new source nodes, extend `DataFlow::SourceNode::Range` instead.
 * Subclasses of `DataFlow::PropRead` are no longer automatically made source nodes; you now need to additionally define a corresponding subclass of `DataFlow::SourceNode::Range` to achieve this.
 * The deprecated libraries `semmle.javascript.DataFlow` and `semmle.javascript.dataflow.CallGraph` have been removed; they are both superseded by `semmle.javascript.dataflow.DataFlow`.
+* Overriding `DataFlow::InvokeNode.getACallee()` no longer affects the call graph seen by the interprocedural data flow libraries. To do this, the 1-argument version `getACallee(int imprecision)` can be overridden instead.
 * The predicate `DataFlow::returnedPropWrite` was intended for internal use only and is no longer available.

javascript/ql/src/semmle/javascript/dataflow/Nodes.qll

@@ -83,7 +83,12 @@ class InvokeNode extends DataFlow::SourceNode {
   /** Gets an abstract value representing possible callees of this call site. */
   AbstractValue getACalleeValue() { result = InvokeNode::getACalleeValue(this) }
 
-  /** Gets a potential callee of this call site. */
+  /**
+   * Gets a potential callee of this call site.
+   *
+   * To alter the call graph as seen by the interprocedural data flow libraries, override
+   * the `getACallee(int imprecision)` predicate instead.
+   */
   Function getACallee() { result = InvokeNode::getACallee(this) }
 
   /**
@@ -93,6 +98,9 @@ class InvokeNode extends DataFlow::SourceNode {
    *
    * Callees with imprecision zero, in particular, have either been derived without
    * considering global variables, or are calls to a global variable within the same file.
+   *
+   * This predicate can be overridden to alter the call graph used by the interprocedural
+   * data flow libraries.
    */
   Function getACallee(int imprecision) { result = InvokeNode::getACallee(this, imprecision) }