JavaScript: Replace Custom* with *::Range.

The old names are kept as deprecated aliases.

Author: Max Schaefer

javascript/ql/src/semmle/javascript/frameworks/ClientRequests.qll

@@ -7,58 +7,66 @@
 
 import javascript
 
-/**
- * A call that performs a request to a URL.
- *
- * Example: An HTTP POST request is a client request that sends some
- * `data` to a `url`, where both the headers and the body of the request
- * contribute to the `data`.
- */
-abstract class CustomClientRequest extends DataFlow::InvokeNode {
-  /**
-   * Gets the URL of the request.
-   */
-  abstract DataFlow::Node getUrl();
-
-  /**
-   * Gets the host of the request.
-   */
-  abstract DataFlow::Node getHost();
-
-  /**
-   * Gets a node that contributes to the data-part this request.
-   */
-  abstract DataFlow::Node getADataNode();
-}
-
 /**
  * A call that performs a request to a URL.
  *
  * Example: An HTTP POST request is client request that sends some
  * `data` to a `url`, where both the headers and the body of the request
  * contribute to the `data`.
+ *
+ * Extend this class to work with client request APIs for which there is already a model.
+ * To model additional APIs, extend `ClientRequest::Range` and implement its abstract member
+ * predicates.
  */
 class ClientRequest extends DataFlow::InvokeNode {
-  CustomClientRequest custom;
+  ClientRequest::Range self;
 
-  ClientRequest() { this = custom }
+  ClientRequest() { this = self }
 
   /**
    * Gets the URL of the request.
    */
-  DataFlow::Node getUrl() { result = custom.getUrl() }
+  DataFlow::Node getUrl() { result = self.getUrl() }
 
   /**
    * Gets the host of the request.
    */
-  DataFlow::Node getHost() { result = custom.getHost() }
+  DataFlow::Node getHost() { result = self.getHost() }
 
   /**
    * Gets a node that contributes to the data-part this request.
    */
-  DataFlow::Node getADataNode() { result = custom.getADataNode() }
+  DataFlow::Node getADataNode() { result = self.getADataNode() }
 }
 
+module ClientRequest {
+  /**
+   * A call that performs a request to a URL.
+   *
+   * Extend this class and implement its abstract member predicates to model additional
+   * client request APIs. To work with APIs for which there is already a model, extend
+   * `ClientRequest` instead.
+   */
+  abstract class Range extends DataFlow::InvokeNode {
+    /**
+     * Gets the URL of the request.
+     */
+    abstract DataFlow::Node getUrl();
+
+    /**
+     * Gets the host of the request.
+     */
+    abstract DataFlow::Node getHost();
+
+    /**
+     * Gets a node that contributes to the data-part this request.
+     */
+    abstract DataFlow::Node getADataNode();
+  }
+}
+
+deprecated class CustomClientRequest = ClientRequest::Range;
+
 /**
  * Gets name of an HTTP request method, in all-lowercase.
  */
@@ -75,7 +83,7 @@ private string urlPropertyName() {
 /**
  * A model of a URL request made using the `request` library.
  */
-private class RequestUrlRequest extends CustomClientRequest {
+private class RequestUrlRequest extends ClientRequest::Range {
   DataFlow::Node url;
 
   RequestUrlRequest() {
@@ -106,7 +114,7 @@ private class RequestUrlRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using the `axios` library.
  */
-private class AxiosUrlRequest extends CustomClientRequest {
+private class AxiosUrlRequest extends ClientRequest::Range {
   string method;
 
   AxiosUrlRequest() {
@@ -149,7 +157,7 @@ private class AxiosUrlRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using an implementation of the `fetch` API.
  */
-private class FetchUrlRequest extends CustomClientRequest {
+private class FetchUrlRequest extends ClientRequest::Range {
   DataFlow::Node url;
 
   FetchUrlRequest() {
@@ -179,7 +187,7 @@ private class FetchUrlRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using the `got` library.
  */
-private class GotUrlRequest extends CustomClientRequest {
+private class GotUrlRequest extends ClientRequest::Range {
   GotUrlRequest() {
     exists(string moduleName, DataFlow::SourceNode callee | this = callee.getACall() |
       moduleName = "got" and
@@ -214,7 +222,7 @@ private class GotUrlRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using the `superagent` library.
  */
-private class SuperAgentUrlRequest extends CustomClientRequest {
+private class SuperAgentUrlRequest extends ClientRequest::Range {
   DataFlow::Node url;
 
   SuperAgentUrlRequest() {
@@ -239,7 +247,7 @@ private class SuperAgentUrlRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using the `XMLHttpRequest` browser class.
  */
-private class XMLHttpRequest extends CustomClientRequest {
+private class XMLHttpRequest extends ClientRequest::Range {
   XMLHttpRequest() {
     this = DataFlow::globalVarRef("XMLHttpRequest").getAnInstantiation()
     or
@@ -257,7 +265,7 @@ private class XMLHttpRequest extends CustomClientRequest {
 /**
  * A model of a URL request made using the `XhrIo` class from the closure library.
  */
-private class ClosureXhrIoRequest extends CustomClientRequest {
+private class ClosureXhrIoRequest extends ClientRequest::Range {
   ClosureXhrIoRequest() {
     exists(DataFlow::SourceNode xhrIo | xhrIo = Closure::moduleImport("goog.net.XhrIo") |
       this = xhrIo.getAMethodCall("send")

javascript/ql/src/semmle/javascript/frameworks/Electron.qll

@@ -60,9 +60,7 @@ module Electron {
     t.start() and
     result instanceof NewBrowserObject
     or
-    exists(DataFlow::TypeTracker t2 |
-      result = browserObject(t2).track(t2, t)
-    )
+    exists(DataFlow::TypeTracker t2 | result = browserObject(t2).track(t2, t))
   }
 
   /**
@@ -122,9 +120,7 @@ module Electron {
       string getChannelName() { result = channel.asExpr().getStringValue() }
 
       /** Gets the data flow node containing the message received by the callback. */
-      DataFlow::Node getMessage() {
-        result = getParameter(1)
-      }
+      DataFlow::Node getMessage() { result = getParameter(1) }
     }
 
     /**
@@ -174,9 +170,7 @@ module Electron {
       SyncDirectMessage() { isSync = true }
 
       /** Gets the data flow node holding the reply to the message. */
-      DataFlow::Node getReply() {
-        result = mc
-      }
+      DataFlow::Node getReply() { result = mc }
     }
 
     /**
@@ -262,28 +256,32 @@ module Electron {
     private class IPCAdditionalFlowStep extends DataFlow::AdditionalFlowStep {
       IPCAdditionalFlowStep() { ipcFlowStep(this, _) }
 
-      override predicate step(DataFlow::Node pred, DataFlow::Node succ) {
-        ipcFlowStep(pred, succ)
-      }
+      override predicate step(DataFlow::Node pred, DataFlow::Node succ) { ipcFlowStep(pred, succ) }
     }
   }
 
-  /**
-   * A Node.js-style HTTP or HTTPS request made using an Electron module.
-   */
-  abstract class CustomElectronClientRequest extends NodeJSLib::CustomNodeJSClientRequest { }
-
   /**
    * A Node.js-style HTTP or HTTPS request made using an Electron module.
    */
   class ElectronClientRequest extends NodeJSLib::NodeJSClientRequest {
-    ElectronClientRequest() { this instanceof CustomElectronClientRequest }
+    override ElectronClientRequest::Range self;
+  }
+
+  module ElectronClientRequest {
+    /**
+     * A Node.js-style HTTP or HTTPS request made using an Electron module.
+     *
+     * Extends this class to add support for new Electron client-request APIs.
+     */
+    abstract class Range extends NodeJSLib::NodeJSClientRequest::Range { }
   }
 
+  deprecated class CustomElectronClientRequest = ElectronClientRequest::Range;
+
   /**
    * A Node.js-style HTTP or HTTPS request made using `electron.ClientRequest`.
    */
-  private class NewClientRequest extends CustomElectronClientRequest {
+  private class NewClientRequest extends ElectronClientRequest::Range {
     NewClientRequest() {
       this = DataFlow::moduleMember("electron", "ClientRequest").getAnInstantiation() or
       this = DataFlow::moduleMember("electron", "net").getAMemberCall("request") // alias

javascript/ql/src/semmle/javascript/frameworks/NodeJSLib.qll

@@ -685,21 +685,29 @@ module NodeJSLib {
   }
 
   /**
-   * A data flow node that is an HTTP or HTTPS client request made by a Node.js application, for example `http.request(url)`.
-   */
-  abstract class CustomNodeJSClientRequest extends CustomClientRequest { }
-
-  /**
-   * A data flow node that is an HTTP or HTTPS client request made by a Node.js application, for example `http.request(url)`.
+   * A data flow node that is an HTTP or HTTPS client request made by a Node.js application,
+   * for example `http.request(url)`.
    */
   class NodeJSClientRequest extends ClientRequest {
-    NodeJSClientRequest() { this instanceof CustomNodeJSClientRequest }
+    override NodeJSClientRequest::Range self;
+  }
+
+  module NodeJSClientRequest {
+    /**
+     * A data flow node that is an HTTP or HTTPS client request made by a Node.js application,
+     * for example `http.request(url)`.
+     *
+     * Extend this class to add support for new Node.js client request APIs.
+     */
+    abstract class Range extends ClientRequest::Range { }
   }
 
+  deprecated class CustomNodeJSClientRequest = NodeJSClientRequest::Range;
+
   /**
    * A model of a URL request in the Node.js `http` library.
    */
-  private class NodeHttpUrlRequest extends CustomNodeJSClientRequest {
+  private class NodeHttpUrlRequest extends NodeJSClientRequest::Range {
     DataFlow::Node url;
 
     NodeHttpUrlRequest() {

javascript/ql/src/semmle/javascript/frameworks/PropertyProjection.qll

@@ -9,41 +9,25 @@ import javascript
 
 /**
  * A property projection call such as `_.get(o, 'a.b')`, which is equivalent to `o.a.b`.
- */
-abstract class CustomPropertyProjection extends DataFlow::CallNode {
-  /**
-   * Gets the argument for the object to project properties from, such as `o` in `_.get(o, 'a.b')`.
-   */
-  abstract DataFlow::Node getObject();
-
-  /**
-   * Gets an argument that selects the properties to project, such as `'a.b'` in `_.get(o, 'a.b')`.
-   */
-  abstract DataFlow::Node getASelector();
-
-  /**
-   * Holds if this call returns the value of a single projected property, as opposed to an object that can contain multiple projected properties.
-   */
-  abstract predicate isSingletonProjection();
-}
-
-/**
- * A property projection call such as `_.get(o, 'a.b')`, which is equivalent to `o.a.b`.
+ *
+ * Extend this class to work with property project APIs for which there is already a model.
+ * To model additional APIs, extend `PropertyProjection::Range` and implement its abstract member
+ * predicates.
  */
 class PropertyProjection extends DataFlow::CallNode {
-  CustomPropertyProjection custom;
+  PropertyProjection::Range self;
 
-  PropertyProjection() { this = custom }
+  PropertyProjection() { this = self }
 
   /**
    * Gets the argument for the object to project properties from, such as `o` in `_.get(o, 'a.b')`.
    */
-  DataFlow::Node getObject() { result = custom.getObject() }
+  DataFlow::Node getObject() { result = self.getObject() }
 
   /**
    * Gets an argument that selects the properties to project, such as `'a.b'` in `_.get(o, 'a.b')`.
    */
-  DataFlow::Node getASelector() { result = custom.getASelector() }
+  DataFlow::Node getASelector() { result = self.getASelector() }
 
   /**
    * Holds if this call returns the value of a single projected property, as opposed to an object that can contain multiple projected properties.
@@ -52,13 +36,39 @@ class PropertyProjection extends DataFlow::CallNode {
    * - This predicate holds for `_.get({a: 'b'}, 'a')`, which returns `'b'`,
    * - This predicate does not hold for `_.pick({a: 'b', c: 'd'}}, 'a')`, which returns `{a: 'b'}`,
    */
-  predicate isSingletonProjection() { custom.isSingletonProjection() }
+  predicate isSingletonProjection() { self.isSingletonProjection() }
+}
+
+module PropertyProjection {
+  /**
+   * A property projection call such as `_.get(o, 'a.b')`, which is equivalent to `o.a.b`.
+   *
+   * Extends this class to add support for new property projection APIs.
+   */
+  abstract class Range extends DataFlow::CallNode {
+    /**
+     * Gets the argument for the object to project properties from, such as `o` in `_.get(o, 'a.b')`.
+     */
+    abstract DataFlow::Node getObject();
+
+    /**
+     * Gets an argument that selects the properties to project, such as `'a.b'` in `_.get(o, 'a.b')`.
+     */
+    abstract DataFlow::Node getASelector();
+
+    /**
+     * Holds if this call returns the value of a single projected property, as opposed to an object that can contain multiple projected properties.
+     */
+    abstract predicate isSingletonProjection();
+  }
 }
 
+deprecated class CustomPropertyProjection = PropertyProjection::Range;
+
 /**
  * A simple model of common property projection functions.
  */
-private class SimplePropertyProjection extends CustomPropertyProjection {
+private class SimplePropertyProjection extends PropertyProjection::Range {
   int objectIndex;
 
   int selectorIndex;

javascript/ql/src/semmle/javascript/frameworks/jQuery.qll

@@ -267,7 +267,7 @@ private class JQueryChainedElement extends DOM::Element {
 /**
  * A model of a URL request made using the `jQuery.ajax` or `jQuery.getJSON`.
  */
-private class JQueryClientRequest extends CustomClientRequest {
+private class JQueryClientRequest extends ClientRequest::Range {
   JQueryClientRequest() {
     exists(string name |
       name = "ajax" or