feat(cli): add inline suppression comments for findings - #393
Merged
Conversation
Add `# docvet: ignore[rule]` and `# docvet: ignore-file[rule]` syntax to suppress specific findings without disabling entire rules. Suppression operates as a post-filter on the findings list using tokenize-based comment extraction — no check functions are modified. - Add _suppression.py with parse_suppression_directives() and filter_findings() - Wire _apply_suppressions() into _output_and_exit() before flatten - Add verbose suppressed listing and JSON "suppressed" array - Add scaffold-incomplete rule to MCP catalog (was missing) - Add 44 tests (39 unit + 5 integration), total 1811 - Add suppression.md docs page and CLI reference section
…ssion Widen _DIRECTIVE_RE bracket character class from [a-z0-9, -] to [^\]]+ so non-standard input (uppercase, underscores) is captured and forwarded to _parse_rules for validation, rather than silently falling back to blanket suppression. Add 4 regression tests.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
Adds an inline-suppression mechanism to the docvet CLI so users can suppress specific findings via source comments, while keeping checks unchanged and filtering results only at the reporting/exit stage.
Changes:
- Introduce tokenize-based parsing for
# docvet: ignore[...]/# docvet: ignore-file[...]directives and post-filter findings into active vs suppressed. - Wire suppression into the CLI output pipeline (affecting output, JSON schema, and exit code) and expose suppressed findings in verbose + JSON output.
- Update the MCP rule catalog/tests and documentation to include the
scaffold-incompleterule and suppression reference material.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_mcp.py | Updates rule category validation and expected rule catalog contents/count. |
| tests/unit/test_cli_suppression.py | Adds unit coverage for parsing directives, filtering, and output-pipeline suppression behavior. |
| tests/unit/test_cli.py | Updates JSON formatter invocation expectations to include the new suppressed kwarg. |
| tests/integration/test_suppression_cli.py | Adds end-to-end CLI tests to validate suppression affects JSON output and exit code. |
| tests/integration/test_mcp.py | Updates MCP integration expectations for the new rule count. |
| src/docvet/reporting.py | Extends format_json() to optionally emit a suppressed array. |
| src/docvet/mcp/_catalog.py | Adds scaffold-incomplete to the static rule catalog and updates catalog docstring. |
| src/docvet/cli/_suppression.py | New module implementing directive parsing and finding filtering. |
| src/docvet/cli/_output.py | Integrates suppression into _output_and_exit() and passes suppressed findings to JSON output. |
| mkdocs.yml | Adds suppression.md and scaffold-incomplete to the docs nav. |
| docs/site/suppression.md | New documentation page describing suppression syntax/behavior. |
| docs/site/cli-reference.md | Documents suppression in CLI reference and notes JSON suppressed output. |
| _bmad-output/implementation-artifacts/sprint-status.yaml | Updates story status to review. |
| _bmad-output/implementation-artifacts/32-4-inline-suppression-comments.md | Adds story artifact with AC mapping, tasks, and implementation notes. |
…ption Reword "fail-safe" language in suppression docs and docstring to clarify that unknown rule IDs are recorded for forward-compatibility but only matching rules suppress findings. Fix pre-existing inaccuracy in JSON schema description: severity has three values (high/medium/low) and by_category includes scaffold.
…string Guard _RULE_TO_CHECK import with try/except so CLI suppression works without the mcp extra installed. Skip rule validation when the registry is unavailable. Catch UnicodeDecodeError alongside OSError in _apply_suppressions for non-UTF-8 files. Update RuleCatalogEntry docstring to include scaffold category.
Change _DIRECTIVE_RE bracket quantifier from + to * so empty brackets are captured. Return empty set from _parse_rules for empty/whitespace bracket content instead of None (blanket). Update JSON example in cli-reference to show scaffold category and suppressed array. Clarify exit code wording for suppressed findings. Add 3 parametrized regression tests for empty-bracket edge cases.
Alberto-Codes
added a commit
that referenced
this pull request
Mar 27, 2026
🤖 I have created a release *beep* *boop* --- ## [1.15.0](v1.14.1...v1.15.0) (2026-03-27) ### Features * **cli:** add docvet fix subcommand with dry-run and discovery ([#386](#386)) ([7f76477](7f76477)) * **cli:** add inline suppression comments for findings ([#393](#393)) ([14ba0b7](14ba0b7)) * **enrichment:** add scaffold category, scaffolding engine, and scaffold-incomplete rule ([#385](#385)) ([782cd27](782cd27)) * **enrichment:** add scaffold-incomplete enrichment rule ([782cd27](782cd27)) ### Bug Fixes * **cli:** address code review findings for fix subcommand ([7f76477](7f76477)) * **cli:** prevent uppercase rule IDs from degrading to blanket ([14ba0b7](14ba0b7)) * **config:** address PR [#379](#379) review feedback ([#380](#380)) ([134e428](134e428)) * **enrichment:** handle docstring-only stubs, multi-statement stubs, and deprecated abstract decorators ([#391](#391)) ([bc2445d](bc2445d)), closes [#387](#387) [#388](#388) [#389](#389) * **griffe:** replace production assert, fix dep vulns, add vuln handling docs ([#395](#395)) ([7273e56](7273e56)) * **test:** move _active_style reset to shared conftest fixture ([#363](#363)) ([b8b6586](b8b6586)) ### Documentation * **cli:** add missing subcommands to quick references ([#397](#397)) ([d92af72](d92af72)), closes [#396](#396) * **enrichment:** add scaffold-incomplete rule page and config docs ([782cd27](782cd27)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This was referenced Aug 14, 2026
Alberto-Codes
added a commit
that referenced
this pull request
Aug 14, 2026
Story 32.4 shipped in #393 but its status was never advanced past `review`, leaving Epic 32 open months after the work landed. - Mark 32-4-inline-suppression-comments done; all 10 acceptance criteria re-verified against the CLI, not just the task checkboxes - Mark epic-32 done now that all four stories are complete
Alberto-Codes
added a commit
that referenced
this pull request
Aug 14, 2026
Epic 32's final story shipped in #393 back in March, but its status was never advanced past `review`, so the epic has read as in-progress ever since. Separately, the five existing issue templates cover features, bugs, enhancements, stories, and retro actions — but nothing fits dependency sweeps, toolchain upgrades, or internal restructuring, even though `chore` and `refactor` labels already exist and #392 was filed as a bare refactor with no template behind it. - Mark `32-4-inline-suppression-comments` done and close out `epic-32` - Add `chore.md` template for dependency, toolchain, CI, and packaging maintenance - Add `refactor.md` template with a behavior-contract checklist - List both new templates in CONTRIBUTING.md so contributors can find them Test: CI only (docs and status files). Story 32.4's ten acceptance criteria were re-verified by hand against the CLI before flipping the status — see Review Focus. chore(docs): add chore and refactor issue templates docs(contributing): list chore and refactor issue templates
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
# docvet: ignore[rule]and# docvet: ignore-file[rule]inline suppression comments, letting developers acknowledge known deviations without disabling entire rules or inflating the noise floor. Suppression operates as a post-filter on the findings list — no check functions are modified._suppression.pymodule with tokenize-based comment parser and finding filter_output_and_exit()before flattening, so both output and exit code exclude suppressed findings"suppressed"array to JSON formatscaffold-incompleterule to MCP catalog (was missing)suppression.mddocs page and inline suppression section to CLI referencefix(cli): prevent uppercase rule IDs from degrading to blanket suppression
Widen
_DIRECTIVE_REbracket character class from[a-z0-9, -]to[^\]]+so non-standard input (uppercase, underscores) is captured and forwarded to_parse_rulesfor validation, rather than silently falling back to blanket suppression. Add 4 regression tests.Test:
uv run pytest tests/unit/test_cli_suppression.py tests/integration/test_suppression_cli.py -vPR Review
Checklist
uv run pytest)uv run ruff check .)uv run ty check)!in title andBREAKING CHANGE:in bodyReview Focus
_suppression.py: regex correctness, tokenize edge cases,_is_suppressedNone-vs-absent dict logic_output.py: suppression wired before flatten loop, source file cachingRelated
_bmad-output/implementation-artifacts/32-4-inline-suppression-comments.md