diff --git a/shared/util/codeql/util/AlertFiltering.qll b/shared/util/codeql/util/AlertFiltering.qll index bfc9d901b2fa..772285f8f270 100644 --- 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 { } /** - * 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]