JS: Mark API as experimental

asger-semmle · asger-semmle · commit 732ddbcbbd0c · 2019-03-06T13:04:34.000Z
diff --git a/javascript/ql/src/semmle/javascript/dataflow/Sources.qll b/javascript/ql/src/semmle/javascript/dataflow/Sources.qll
@@ -156,6 +156,8 @@ class SourceNode extends DataFlow::Node {
   }
 
   /**
+   * EXPERIMENTAL.
+   *
    * Gets a node that this node may flow to using one heap and/or interprocedural step.
    *
    * See `TypeTracker` for more details about how to use this.
@@ -168,6 +170,8 @@ class SourceNode extends DataFlow::Node {
   }
 
   /**
+   * EXPERIMENTAL.
+   *
    * Gets a node that may flow into this one using one heap and/or interprocedural step.
    *
    * See `TypeBackTracker` for more details about how to use this.
diff --git a/javascript/ql/src/semmle/javascript/dataflow/TypeTracking.qll b/javascript/ql/src/semmle/javascript/dataflow/TypeTracking.qll
@@ -20,6 +20,8 @@ private newtype TStepSummary = MkStepSummary(boolean hasReturn, boolean hasCall)
 }
 
 /**
+ * INTERNAL: Use `TypeTracker` or `TypeBackTracker` instead.
+ *
  * Summary of the steps needed to track a value to a given dataflow node.
  */
 class StepSummary extends TStepSummary {
@@ -84,7 +86,7 @@ module StepSummary {
   StepSummary return() { result = MkStepSummary(true, false) }
 
   /**
-   * INTERNAL: Use `SourceNode.track()` instead.
+   * INTERNAL: Use `SourceNode.track()` or `SourceNode.backtrack()` instead.
    */
   predicate step(DataFlow::SourceNode pred, DataFlow::SourceNode succ, StepSummary summary) {
     exists (DataFlow::Node predNode | pred.flowsTo(predNode) |
@@ -136,6 +138,8 @@ private newtype TTypeTracker = MkTypeTracker(boolean hasCall) {
 }
 
 /**
+ * EXPERIMENTAL.
+ *
  * Summary of the steps needed to track a value to a given dataflow node.
  *
  * This can be used to track objects that implement a certain API in order to
@@ -194,6 +198,8 @@ private newtype TTypeBackTracker = MkTypeBackTracker(boolean hasReturn) {
 }
 
 /**
+ * EXPERIMENTAL.
+ *
  * Summary of the steps needed to back-track a use of a value to a given dataflow node.
  *
  * This can be used to track callbacks that are passed to a certian API call, and are

Original file line number	Diff line number	Diff line change
`@@ -156,6 +156,8 @@ class SourceNode extends DataFlow::Node {`
`156`	`156`	`}`
`157`	`157`
`158`	`158`	`/**`
	`159`	`+ * EXPERIMENTAL.`
	`160`	`+ *`
`159`	`161`	`* Gets a node that this node may flow to using one heap and/or interprocedural step.`
`160`	`162`	`*`
`161`	`163`	* See `TypeTracker` for more details about how to use this.
`@@ -168,6 +170,8 @@ class SourceNode extends DataFlow::Node {`
`168`	`170`	`}`
`169`	`171`
`170`	`172`	`/**`
	`173`	`+ * EXPERIMENTAL.`
	`174`	`+ *`
`171`	`175`	`* Gets a node that may flow into this one using one heap and/or interprocedural step.`
`172`	`176`	`*`
`173`	`177`	* See `TypeBackTracker` for more details about how to use this.
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,8 @@ private newtype TStepSummary = MkStepSummary(boolean hasReturn, boolean hasCall)`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`/**`
	`23`	+ * INTERNAL: Use `TypeTracker` or `TypeBackTracker` instead.
	`24`	`+ *`
`23`	`25`	`* Summary of the steps needed to track a value to a given dataflow node.`
`24`	`26`	`*/`
`25`	`27`	`class StepSummary extends TStepSummary {`
`@@ -84,7 +86,7 @@ module StepSummary {`
`84`	`86`	`StepSummary return() { result = MkStepSummary(true, false) }`
`85`	`87`
`86`	`88`	`/**`
`87`		- * INTERNAL: Use `SourceNode.track()` instead.
	`89`	+ * INTERNAL: Use `SourceNode.track()` or `SourceNode.backtrack()` instead.
`88`	`90`	`*/`
`89`	`91`	`predicate step(DataFlow::SourceNode pred, DataFlow::SourceNode succ, StepSummary summary) {`
`90`	`92`	`exists (DataFlow::Node predNode \| pred.flowsTo(predNode) \|`
`@@ -136,6 +138,8 @@ private newtype TTypeTracker = MkTypeTracker(boolean hasCall) {`
`136`	`138`	`}`
`137`	`139`
`138`	`140`	`/**`
	`141`	`+ * EXPERIMENTAL.`
	`142`	`+ *`
`139`	`143`	`* Summary of the steps needed to track a value to a given dataflow node.`
`140`	`144`	`*`
`141`	`145`	`* This can be used to track objects that implement a certain API in order to`
`@@ -194,6 +198,8 @@ private newtype TTypeBackTracker = MkTypeBackTracker(boolean hasReturn) {`
`194`	`198`	`}`
`195`	`199`
`196`	`200`	`/**`
	`201`	`+ * EXPERIMENTAL.`
	`202`	`+ *`
`197`	`203`	`* Summary of the steps needed to back-track a use of a value to a given dataflow node.`
`198`	`204`	`*`
`199`	`205`	`* This can be used to track callbacks that are passed to a certian API call, and are`