From 7083d8199887eaa265807730dedf441b93eb6305 Mon Sep 17 00:00:00 2001 From: Chuan-kai Lin Date: Mon, 14 Jul 2025 14:32:21 -0700 Subject: [PATCH] Shared: Overhaul the AlertFiltering QLDoc 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. --- shared/util/codeql/util/AlertFiltering.qll | 87 ++++++++++------------ 1 file changed, 38 insertions(+), 49 deletions(-) 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] pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy