Shared: Overhaul the AlertFiltering QLDoc

cklin · cklin · commit 7083d8199887 · 2025-07-14T14:32:21.000-07:00
This commit strengthens the contract for the restrictAlertsTo and the
restrictAlertsToExactLocation extensible predicates.

- restrictAlertsTo is now documented to match any alert location that
  intersects with a specified line range. (Previously an alert location
  matches only when its first line is in a specified line range.)

- restrictAlertsToExactLocation is now documented to match any alert
  location that wholly contains a specific character range. (Previously
  an alert location matchis only when it is exactly the same as a
  specified character range.)

It also contains misc wording changes for clarity.
diff --git a/shared/util/codeql/util/AlertFiltering.qll b/shared/util/codeql/util/AlertFiltering.qll
@@ -1,6 +1,7 @@
 /**
- * Provides the `restrictAlertsTo` extensible predicate to restrict alerts to specific source
- * locations, and the `AlertFilteringImpl` parameterized module to apply the filtering.
+ * Provides the `restrictAlertsTo` and `restrictAlertsToExactLocation` extensible predicate to
+ * restrict alerts to specific source locations, and the `AlertFilteringImpl` parameterized module
+ * to apply the filtering.
  */
 overlay[local?]
 module;
@@ -13,55 +14,54 @@ private import codeql.util.Location
  * GitHub Code Scanning.
  *
  * This predicate is active if and only if it is nonempty. If this predicate is inactive, it has no
- * effect. If it is active, queries may omit alerts that don't have a _primary_ or _related_
- * location (in SARIF terminology) whose start line is within a specified range. Queries are allowed
- * to produce alerts outside this range.
+ * effect. If it is active, queries may omit alerts that don't have a matching (see below) _primary_
+ * or _related_ location (in SARIF terminology). Queries are still allowed to produce alerts that
+ * have no matching locations, but they are not required to do so.
  *
- * An alert location is a match if it matches a row in this predicate. If `startLineStart` and
- * `startLineEnd` are both 0, the row specifies a whole-file match, and a location is a match if
+ * An alert location is a match if it matches a row in this predicate. If `lineStart` and
+ * `lineEnd` are both 0, the row specifies a whole-file match, and a location is a match if
  * its file path matches `filePath`. Otherwise, the row specifies a line-range match, and a
- * location is a match if its file path matches `filePath`, and its start line is between
- * `startLineStart` and `startLineEnd`, inclusive. (Note that only start line of the location is
- * used for matching because an alert is displayed on the first line of its location.)
+ * location is a match if its file path matches `filePath`, and its character range intersects
+ * with the range from the beginning of `lineStart` to the end of `lineEnd`.
  *
  * - filePath: alert location file path (absolute).
- * - startLineStart: inclusive start of the range for alert location start line number (1-based).
- * - startLineEnd: inclusive end of the range for alert location start line number (1-based).
+ * - lineStart: inclusive start of the line range (1-based).
+ * - lineEnd: inclusive end of the line range (1-based).
  *
- * Note that an alert that is not accepted by this filtering predicate may still be included in the
- * query results if it is accepted by another active filtering predicate in this module. An alert is
- * excluded from the query results if only if (1) there is at least one active filtering predicate,
- * and (2) it is not accepted by any active filtering predicate.
+ * Note that even if an alert has no matching locations for this filtering predicate, it could still
+ * have matching locations for other filtering predicates in this module. In that case, queries must
+ * still produce such an alert. An alert can be omitted if only if (1) there is at least one active
+ * filtering predicate, and (2) it has no matching locations for any active filtering predicate.
  *
  * See also: `restrictAlertsToExactLocation`.
  */
-extensible predicate restrictAlertsTo(string filePath, int startLineStart, int startLineEnd);
+extensible predicate restrictAlertsTo(string filePath, int lineStart, int lineEnd);
 
 /**
  * Holds if the query may restrict its computation to only produce alerts that match the given
- * character ranges. This predicate is suitable for testing, where we want to filter by the exact
- * alert location, distinguishing between alerts on the same line.
+ * character ranges. This predicate is suitable for testing, where we want to distinguish between
+ * alerts on the same line.
  *
  * This predicate is active if and only if it is nonempty. If this predicate is inactive, it has no
- * effect. If it is active, queries may omit alerts that don't have a _primary_ or _related_
- * location (in SARIF terminology) whose location equals a tuple from this predicate. Queries are
- * allowed to produce alerts outside this range.
+ * effect. If it is active, queries may omit alerts that don't have a matching (see below) _primary_
+ * or _related_ location (in SARIF terminology). Queries are still allowed to produce alerts that
+ * have no matching locations, but they are not required to do so.
  *
- * An alert location is a match if it matches a row in this predicate. Each row specifies an exact
- * location: an alert location is a match if its file path matches `filePath`, its start line and
- * column match `startLine` and `startColumn`, and its end line and column match `endLine` and
- * `endColumn`.
+ * An alert location is a match if it matches a row in this predicate. Each row specifies a
+ * character-range match, and a location is a match if its file path matches `filePath`, and its
+ * character range wholly contains the character range from `startColumn` on `startLine` to
+ * `endColumn` on `endLine` (inclusive).
  *
  * - filePath: alert location file path (absolute).
- * - startLine:  alert location start line number (1-based).
- * - startColumn: alert location start column number (1-based).
- * - endLine: alert location end line number (1-based).
- * - endColumn: alert location end column number (1-based).
+ * - startLine: inclusive start line of the character range (1-based).
+ * - startColumn: inclusive start column of the character range (1-based).
+ * - endLine: inclusive end line of the character range (1-based).
+ * - endColumn: inclusive end column of the character range (1-based).
  *
- * Note that an alert that is not accepted by this filtering predicate may still be included in the
- * query results if it is accepted by another active filtering predicate in this module. An alert is
- * excluded from the query results if only if (1) there is at least one active filtering predicate,
- * and (2) it is not accepted by any active filtering predicate.
+ * Note that even if an alert has no matching locations for this filtering predicate, it could still
+ * have matching locations for other filtering predicates in this module. In that case, queries must
+ * still produce such an alert. An alert can be omitted if only if (1) there is at least one active
+ * filtering predicate, and (2) it has no matching locations for any active filtering predicate.
  *
  * See also: `restrictAlertsTo`.
  */
@@ -83,22 +83,11 @@ module AlertFilteringImpl<LocationSig Location> {
   }
 
   /**
-   * Holds if the given location intersects the diff range. When that is the
-   * case, ensuring that alerts mentioning this location are included in the
-   * query results is a valid overapproximation of the requirements for
-   * _diff-informed queries_ as documented under `restrictAlertsTo`.
+   * Holds if the given location is a match for one of the active filtering
+   * predicates in this module, or if all filtering predicates are inactive
+   * (which means that all alerts must be produced).
    *
-   * Testing for full intersection rather than only matching the start line
-   * means that this predicate is more broadly useful than just checking whether
-   * a specific element is considered to be in the diff range of GitHub Code
-   * Scanning:
-   * - If it's inconvenient to pass the exact `Location` of the element of
-   *   interest, it's valid to use a `Location` of an enclosing element.
-   * - This predicate could be useful for other systems of alert presentation
-   *   where the rules don't exactly match GitHub Code Scanning.
-   *
-   * If there is no diff range, this predicate holds for all locations. Note
-   * that this predicate has a bindingset and will therefore be inlined;
+   * Note that this predicate has a bindingset and will therefore be inlined;
    * callers should include enough context to ensure efficient evaluation.
    */
   bindingset[location]
