AlertFiltering: allow multiple filtering predicates

This commit rephrases the documentation for the restrictAlertsTo
predicate and renames the predicate columns for clarity. The new
documentation should be equivalent to the old documentation, except
allowing for the possibility that there may be multiple alert filtering
predicates.

Author: cklin

shared/util/codeql/util/AlertFiltering.qll

@@ -6,22 +6,31 @@
 private import codeql.util.Location
 
 /**
- * Restricts alerts to a specific location in specific files.
+ * Holds if the query should produce alerts that match the given line ranges.
  *
- * If this predicate is empty, accept all alerts. Otherwise, accept alerts only at the specified
- * locations. Note that alert restrictions apply only to the start line of an alert (even if the
- * alert location spans multiple lines) because alerts are displayed on their start lines.
+ * 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.
  *
- * - filePath: Absolute path of the file to restrict alerts to.
- * - startLine: Start line number (starting with 1, inclusive) to restrict alerts to.
- * - endLine: End line number (starting with 1, inclusive) to restrict alerts to.
+ * 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.
  *
- * If startLine and endLine are both 0, accept alerts anywhere in the file.
+ * 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
+ * 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.)
  *
- * A query should either completely ignore this predicate (i.e., perform no filtering whatsoever),
- * or only return alerts that meet the filtering criteria as specified above.
+ * - 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).
+ *
+ * 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.
  */
-extensible predicate restrictAlertsTo(string filePath, int startLine, int endLine);
+extensible predicate restrictAlertsTo(string filePath, int startLineStart, int startLineEnd);
 
 /** Module for applying alert location filtering. */
 module AlertFilteringImpl<LocationSig Location> {
@@ -30,14 +39,14 @@ module AlertFilteringImpl<LocationSig Location> {
   predicate filterByLocation(Location location) {
     not restrictAlertsTo(_, _, _)
     or
-    exists(string filePath, int startLine, int endLine |
-      restrictAlertsTo(filePath, startLine, endLine)
+    exists(string filePath, int startLineStart, int startLineEnd |
+      restrictAlertsTo(filePath, startLineStart, startLineEnd)
     |
-      startLine = 0 and
-      endLine = 0 and
+      startLineStart = 0 and
+      startLineEnd = 0 and
       location.hasLocationInfo(filePath, _, _, _, _)
       or
-      location.hasLocationInfo(filePath, [startLine .. endLine], _, _, _)
+      location.hasLocationInfo(filePath, [startLineStart .. startLineEnd], _, _, _)
     )
   }
 }