line-suppression-directives

Files (1)

• SKILL.md

SKILL.md (first lines)

# Line Suppression Directives

Use this for scanners, linters, and analyzers that suppress findings from comments or directive markers.

## Critical Rule

For AST-backed or parser-backed analyzers, suppression is usually semantic, not just physical. Build a `line -> statement range` map before applying directives. A directive found inside a multi-line statement must be projected through that whole statement range, including earlier lines where findings may be reported.

Before finishing, run a literal probe with `subprocess.Popen(` on one line and `shell=True,  # nosec-begin B602` on a later argument line, followed by `# nosec-end`. The expected remaining IDs for that probe are `[]`; `B602` must be suppressed even though the directive appears on a later physical line than the call expression.

Do not substitute a nearby multi-line case for that probe. A marker on a separate preceding line, or `# nosec-end` inside the statement, does not prove the same behavior. The marker must be on the later argument line itself.

Common failure to avoid: adding a statement-line range to issue filtering is not enough if the directive is never recorded on that statement range. Expand the directive's physical line into its semantic statement range while building the suppression table, before issue filtering and metrics.

## Core Workflow

1. Preserve the existing suppression contract first. If an empty set or sentinel already means "suppress all", keep that meaning stable.
2. Model directives as structured data before applying them: kind, physical line, selector, and scope.
3. Parse selectors separately from scope. Support exact IDs/names first; add globs or boolean operators only when the task asks for them.
4. Convert directive scope to the analyzer's semantic range, not just the directive's physical line.
5. Combine all applicable suppressions for a finding. Blanket suppression dominates specific suppression; specific sets union unless the spec says intersection.
6. Keep metrics aligned with the final suppression decision. Count blanket suppression and specific skipped tests the same way existing inline suppression does.

## Multi-Line Statement Rules

- For AST-backed analyzers, build statement ranges from `lineno` through `end_lineno`, including decorators when relevant.
- Build a `line -> statement range` map. Every directive target line should be expanded through this map before insertion into the suppression table.
- If any line in a multi-line statement carries an applicable inline, region, or next-statement suppression, apply that suppression to the whole statement range before evaluating issues. This includes statement lines before and after the physical directive line.
- Do not implement regions as only active physical lines. A region directive found on line `L` inside a multi-line statement must be projected through `statement_range_for_line[L]`, so a finding reported on the statement's first line is suppressed even when the directive appears on a later argument line.
- `next-line` means the next executable statement, not the next physical nonblank line. Skip comments, blank lines, and grouping-only continuation lines.
- Regions must not leak outside their intended block or file. If the spec supports dedent auto-end, end the active region before applying it to the dedented line.
- Region begin/end marker lines should only suppress themselves when the legacy inline behavior already would.

## Implementation Pattern

Use this pattern unless the repository already has an equivalent semantic range helper:

1. Build `statement_range_for_line` from the parser/AST before parsing suppression comments.
2. Resolve each suppression event to a selector state: `None`, empty set, or non-empty set.
3. When adding a suppression for physical line `L`, call `expand(L)` where `expand` returns the full statement range containing `L`, or `{L}` when no range is known.
4. Insert the suppression on every line returned by `expand(L)`, combining with existing entries.
5. For active regions, apply step 3 on every covered physical line, including the line where the region starts if the marker is inside a statement. Do this immediately when the begin marker is parsed, before advancing to later lines.
6. After the line table is built, issue filtering should inspect all lines in the issue's statement/context range and union the suppressions found there. Do not inspect only `issue.lineno`.

## Selector and Metrics Guardrails

- Keep three states distinct: `None` means no suppression, empty set means blanket suppression, and a non-empty set means specific suppression.
- Do not downgrade a recognized specific selector to blanket suppression. If a selector such as `B602` resolves to a specific rule, metrics should count `skipped_tests`, not `nosec`.
- Do not infer blanket suppression just because the selected specific IDs equal the current enabled-test universe. `# nosec B602` remains a specific suppression even in a profile where B602 is the only enabled check. Only an omitted selector or explicit `all` should produce the blanket sentinel.
- For analyzers with separate plugin and blacklist registries, include both plugin IDs and blacklist/check IDs in selector resolution. In Bandit-like analyzers, rules such as `B602`, `B603`, and `B607` can come from blacklist data, not only plugin functions.
- Unknown free text after legacy inline comments may preserve existing blanket behavior, but explicit directive selectors should only become blanket for omitted selector or `all`.
- When several specific suppressions apply to one issue through region, inline, or next-statement rules, union the specific IDs and keep the result specific.
- Metrics must be checked against the actual sentinel used at skip time. Specific region, next-statement, and inline suppressions should increment the same per-rule skipped counter as existing inline `# nosec B602`; blanket region, next-statement, and inline suppressions should increment the same blanket `nosec` counter.

## Required Local Probes

Before finishing, run probes that mirror the hard semantic boundaries in the prompt, not only adjacent easy cases:

- existing inline suppression compatibility;
- region begin/end with blanket and per-rule selectors;
- next-statement suppression across blank/comment/grouping lines;
- multi-line calls, assignments, decorators, and chained expressions where the finding is reported on a different line than the directive;
- overlapping region, inline, and next-line directives;
- region begin inside a multi-line statement where the issue is reported on an earlier line in the same statement;
- a literal case shaped like `subprocess.Popen(` on one line and `shell=True,  # nosec-begin B602` on a later argument line, expecting no `B602`;
- `none` or no-op selectors;
- unknown selector text preserving legacy blanket behavior only when the prior analyzer treated it that way;
- `ignore_nosec` or equivalent global disable flags;
- suppression metrics for blanket and per-rule cases;
- metrics where a specific selector is the only enabled check, to prove it still counts as specific rather than blanket;
- per-rule selectors for blacklist-style checks, not only ordinary plugin functions.

From Calvin-Corbett/thomas, MIT.

More from Calvin-Corbett/thomas