From 96caa686fc1f4a1b6d8841e1062f5f6a89fb840d Mon Sep 17 00:00:00 2001
From: Chuan-kai Lin <cklin@github.com>
Date: Wed, 29 Jan 2025 07:50:45 -0800
Subject: [PATCH] AlertFiltering: add restrictAlertsToExactLocation

This commit introduces a new extensible predicate
restrictAlertsToExactLocation, which is similar to the existing
restrictAlertsTo predicate but matches alert locations exactly.
---
 shared/util/codeql/util/AlertFiltering.qll | 47 +++++++++++++++++++++-
 shared/util/ext/default-alert-filter.yml   |  6 +++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/shared/util/codeql/util/AlertFiltering.qll b/shared/util/codeql/util/AlertFiltering.qll
index e7c01807e6f..97acd803f01 100644
--- a/shared/util/codeql/util/AlertFiltering.qll
+++ b/shared/util/codeql/util/AlertFiltering.qll
@@ -29,15 +29,54 @@ private import codeql.util.Location
  *
  * A query should either perform no alert filtering, or adhere to all the filtering rules in this
  * module and return all and only the accepted alerts.
+ *
+ * This predicate is suitable for situations where we want to filter alerts at line granularity,
+ * such as based on the pull request diff.
+ *
+ * See also: `restrictAlertsToExactLocation`.
  */
 extensible predicate restrictAlertsTo(string filePath, int startLineStart, int startLineEnd);
 
+/**
+ * Holds if the query should produce alerts that match the given locations.
+ *
+ * This predicate is active if and only if it is nonempty. If this predicate is inactive, it has no
+ * effect. If it is active, it accepts any alert that has at least one matching location.
+ *
+ * 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.
+ *
+ * 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`.
+ *
+ * - 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).
+ *
+ * A query should either perform no alert filtering, or adhere to all the filtering rules in this
+ * module and return all and only the accepted alerts.
+ *
+ * This predicate is suitable for situations where we want to filter by the exact alert location,
+ * distinguishing between alerts on the same line.
+ *
+ * See also: `restrictAlertsTo`.
+ */
+extensible predicate restrictAlertsToExactLocation(
+  string filePath, int startLine, int startColumn, int endLine, int endColumn
+);
+
 /** Module for applying alert location filtering. */
 module AlertFilteringImpl<LocationSig Location> {
   /** Applies alert filtering to the given location. */
   bindingset[location]
   predicate filterByLocation(Location location) {
-    not restrictAlertsTo(_, _, _)
+    not restrictAlertsTo(_, _, _) and not restrictAlertsToExactLocation(_, _, _, _, _)
     or
     exists(string filePath, int startLineStart, int startLineEnd |
       restrictAlertsTo(filePath, startLineStart, startLineEnd)
@@ -48,5 +87,11 @@ module AlertFilteringImpl<LocationSig Location> {
       or
       location.hasLocationInfo(filePath, [startLineStart .. startLineEnd], _, _, _)
     )
+    or
+    exists(string filePath, int startLine, int startColumn, int endLine, int endColumn |
+      restrictAlertsToExactLocation(filePath, startLine, startColumn, endLine, endColumn)
+    |
+      location.hasLocationInfo(filePath, startLine, startColumn, endLine, endColumn)
+    )
   }
 }
diff --git a/shared/util/ext/default-alert-filter.yml b/shared/util/ext/default-alert-filter.yml
index 0ae5a2f4eb5..1c4dd263d05 100644
--- a/shared/util/ext/default-alert-filter.yml
+++ b/shared/util/ext/default-alert-filter.yml
@@ -5,3 +5,9 @@ extensions:
       extensible: restrictAlertsTo
     # Empty predicate means no restrictions on alert locations
     data: []
+
+  - addsTo:
+      pack: codeql/util
+      extensible: restrictAlertsToExactLocation
+    # Empty predicate means no restrictions on alert locations
+    data: []