Support Ruff 0.16 suppression directives - #12

No actionable comments were generated in the recent review. 🎉

Summary

Extend lint-suppression-without-explanation to support Ruff 0.16 suppression directives.

• Recognize ignore, file-ignore, disable, and enable directives.
• Support rule codes, preview rule names, documented whitespace, bracket spacing, and trailing commas.
• Require standalone comments for file-level and range directives.
• Treat directive matching as case-sensitive.
• Keep ruff: enable[...] neutral.
• Recognize explanations on trailing physical and preceding logical lines.
• Document the checker contract and Ruff grammar.
• Add regression and property-based tests.
• Lock Ruff to 0.16.0.

Validate formatting, linting, type checking, tests, auditing, Markdown, Mermaid, and Makefile checks. The suite passes 322 tests, with one skipped test.

Walkthrough

Update suppression parsing for Ruff directives and rule-list formats. Require preceding explanations to contain prose beyond directives. Document and test the syntax, standalone-comment rules, and neutral behaviour of ruff: enable.

Changes

Suppression validation

Possibly related PRs

• leynos/episodic#220: Adopts the DF12 lint suite and relates to Ruff suppression handling.
• leynos/lading#220: Modifies Ruff suppression syntax and parsing.
• leynos/cmd-mox#229: Relies on related Ruff and noqa suppression logic.

Poem

Parse Ruff rules with care,
Keep directives clean and spare.
Prose must stand apart,
enable ends its part,
Tests guard every pair.

❌ Failed checks (1 warning, 4 inconclusive)

_{Comment @coderabbitai help to get the list of available commands.}

@coderabbitai review

@coderabbitai review

@coderabbitai review

@coderabbitai Have the following now been resolved?

docs/users-guide.md (1)

134-136: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the C9106 directive list.
Remove ruff: enable from Line 136. It terminates a suppression range and does

not emit C9106, which contradicts Lines 144-146.
Triage: [type:docstyle]

🤖 Detailed instructions

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/users-guide.md around lines 134 - 136, Update the C9106 directive list
in the lint suppression documentation by removing ruff: enable, while
retaining the other listed pragmas and keeping the documented suppression-range
behavior consistent with the later guidance.

docs/developers-guide.md (1)

38-45: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document file-level noqa alias restrictions in both guides.
State that ruff: noqa and flake8: noqa require standalone comments. State that their prefixes are case-sensitive, while noqa and inline noqa are case-insensitive.

• Update docs/developers-guide.md:38-45.
• Update docs/users-guide.md:140-142.
  Triage: [type:docstyle]

🤖 Detailed instructions

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/developers-guide.md around lines 38 - 45, Update the documentation
describing file-level noqa aliases in docs/developers-guide.md:38-45 and
docs/users-guide.md:140-142. State that ruff: noqa and flake8: noqa require
standalone comments, their prefixes are case-sensitive, and noqa plus inline
noqa forms are case-insensitive.

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- docs/users-guide.md: relevant lines ---'
nl -ba docs/users-guide.md | sed -n '125,155p'

printf '%s\n' '--- docs/developers-guide.md: relevant lines ---'
nl -ba docs/developers-guide.md | sed -n '30,60p'

printf '%s\n' '--- directive parsing implementation ---'
ast-grep outline df12_python_lints/suppressions.py --items all --view expanded
rg -n -C 5 -P 'ruff:|flake8:|noqa|_directive_symbols|is_standalone' df12_python_lints/suppressions.py

#!/bin/bash
set -euo pipefail

show_lines() {
  file="$1"
  start="$2"
  end="$3"
  printf '%s\n' "--- ${file}:${start}-${end} ---"
  sed -n "${start},${end}p" "$file" | awk -v n="$start" '{ printf "%d: %s\n", n++, $0 }'
}

show_lines docs/users-guide.md 125 155
show_lines docs/developers-guide.md 30 60

printf '%s\n' '--- matching implementation locations ---'
grep -n -E -C 5 'ruff:|flake8:|noqa|_directive_symbols|is_standalone' df12_python_lints/suppressions.py || true

printf '%s\n' '--- implementation context ---'
grep -n -E '_directive_symbols|RUFF|NOQA|FLAKE8' df12_python_lints/suppressions.py || true

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- suppression documentation in both guides ---'
grep -n -i -E -C 4 'ruff:[[:space:]]*noqa|flake8:[[:space:]]*noqa|standalone comment|case-sensitive|case-insensitive|suppression' \
  docs/users-guide.md docs/developers-guide.md || true

printf '%s\n' '--- alias-related tests ---'
grep -n -i -E -C 4 'ruff:[[:space:]]*noqa|flake8:[[:space:]]*noqa|standalone|case-sensitive|case-insensitive' \
  tests/test_suppressions.py tests/test_suppression_properties.py 2>/dev/null || true

printf '%s\n' '--- regex behaviour for requested alias forms ---'
python - <<'PY'
from df12_python_lints import suppressions

cases = (
    ("# ruff: noqa", True),
    ("# Ruff: noqa", True),
    ("value = 1  # ruff: noqa", False),
    ("# flake8: noqa", True),
    ("# Flake8: noqa", True),
    ("value = 1  # flake8: noqa", False),
    ("value = 1  # NOQA", False),
)
for text, standalone in cases:
    comment = suppressions._Comment(text, standalone)
    print(f"{text!r}, standalone={standalone}: {suppressions._directive_symbols(comment)!r}")
PY

@leynos

Mark the ruff: enable finding as resolved.

• docs/users-guide.md Lines 134-136 no longer list ruff: enable as a C9106 suppression directive.
• Lines 147-149 correctly state that ruff: enable[...] terminates a range and does not emit C9106.

Keep the file-level noqa alias finding open.

• The requested wording exists in docs/users-guide.md Lines 140-145 and docs/developers-guide.md Lines 92-95.
• The wording does not match the current implementation.
• df12_python_lints/suppressions.py applies re.IGNORECASE to _LINT_DIRECTIVE.
• The matcher also detects noqa inside inline and mixed-case aliases.

The current checker emits C9106 for all of these forms:

# Ruff: noqa
value = 1  # ruff: noqa
# Flake8: noqa
value = 1  # flake8: noqa

Update the parser and add regression tests to enforce the documented standalone and case-sensitive alias rules. Alternatively, revise both guides to describe the current behaviour.

Learnt from: leynos
Repo: leynos/dakar PR: 0
File: :0-0
Timestamp: 2026-08-16T12:38:29.454Z
Learning: For `leynos/dakar` pull request reviews, treat reported warnings as required work. Keep observability, code safety, documentation, and validation coverage in scope. If a valid finding is out of scope, identify an existing GitHub issue or propose a focused GitHub follow-up issue.

_{You are interacting with an AI system.}

@coderabbitai Have the following now been resolved?

df12_python_lints/suppressions.py (1)

54-83: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Split Ruff directive matching by syntax. Make the ruff: branch case-sensitive and own-line only so # RUFF: ignore[...] and inline ruff: file-ignore[...] / ruff: disable[...] do not emit C9106. Add negative regressions for those forms.

🤖 Detailed instructions

Use a wyvern agent team to verify each finding against the current code and only fix it if needed. Fix any documentation issues using a scribe agent team. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Use a scrutineer agent for execution of tests and summarizing the results.

In @df12_python_lints/suppressions.py around lines 54 - 83, Split Ruff directive
detection in _DIRECTIVE_ONLY_SEGMENT so the ruff: branch is case-sensitive and
matches only when the directive occupies its own line. Ensure uppercase “RUFF”
and inline file-ignore or disable directives are not classified as C9106, and
add negative regression tests covering these forms.

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- PR head and changed files ---'
git status --short
git diff --name-only HEAD^ HEAD || true

printf '%s\n' '--- suppressions module outline ---'
ast-grep outline df12_python_lints/suppressions.py --items all --view expanded

printf '%s\n' '--- directive parsing implementation ---'
nl -ba df12_python_lints/suppressions.py | sed -n '35,115p'

printf '%s\n' '--- Ruff-related regression tests ---'
rg -n -i -C 5 'ruff|file-ignore|disable|standalone|case-sensitive|invalid' \
  tests/test_suppressions.py tests/test_suppression_properties.py 2>/dev/null || true

printf '%s\n' '--- relevant PR diff ---'
git diff HEAD^ HEAD -- df12_python_lints/suppressions.py tests/test_suppressions.py tests/test_suppression_properties.py || true

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- parser patterns and classification ---'
sed -n '45,140p' df12_python_lints/suppressions.py

printf '%s\n' '--- standalone comment collection ---'
sed -n '160,225p' df12_python_lints/suppressions.py

printf '%s\n' '--- exact negative Ruff regressions ---'
rg -n -C 6 -e 'RUFF:' -e 'ruff: file-ignore' -e 'ruff: disable' \
  tests/test_suppressions.py tests/test_suppression_properties.py 2>/dev/null || true

printf '%s\n' '--- test classes and nearby Ruff cases ---'
ast-grep outline tests/test_suppressions.py --items all --view expanded
rg -n -C 4 -i 'invalid.*ruff|ruff.*invalid|standalone.*ruff|ruff.*standalone' \
  tests/test_suppressions.py tests/test_suppression_properties.py 2>/dev/null || true

@leynos Mark this finding as resolved.

df12_python_lints/suppressions.py now separates the Ruff syntax:

• _RUFF_INLINE_DIRECTIVE matches only ruff: ignore[...].
• _RUFF_STANDALONE_DIRECTIVE matches ruff: file-ignore[...] and ruff: disable[...] only when _Comment.is_standalone is true.
• Ruff patterns have no case-insensitive flag. Therefore, # RUFF: ignore[...] does not emit C9106.
• _DIRECTIVE_ONLY_SEGMENT uses (?-i:ruff...) to keep Ruff directive recognition case-sensitive.

tests/test_suppressions.py includes negative regressions for:

• x = 1 # RUFF: ignore[F841]
• x = 1 # ruff: file-ignore[F841]
• x = 1 # ruff: disable[F841]

The test suite was not executed in this sandbox. Static inspection confirms that the implementation and regression tests meet the finding requirements.

_{You are interacting with an AI system.}