Add -W/--strict flag and shared suppress_warnings to codelinks analyse#93
Draft
ubmarco wants to merge 10 commits into
Draft
Add -W/--strict flag and shared suppress_warnings to codelinks analyse#93ubmarco wants to merge 10 commits into
ubmarco wants to merge 10 commits into
Conversation
… matcher Introduce CODELINKS_WARNING_SLUGS (the canonical set of warning slugs the analyse layer can emit) and is_suppressed(), a dot-boundary hierarchical matcher so a parent slug silences the family below it. Groundwork for the -W/--strict flag (#90).
_CliBackend now drops warnings matching its suppress_warnings list and counts the survivors, appending each slug to the message so users know what to suppress. Adds configure_cli(suppress_warnings=), set_cli_suppress_warnings() and cli_warning_count() so the CLI can apply suppression once the TOML config is parsed and later gate the exit code on the count (#90).
…git.* Emit the six git-metadata warnings with dotted subtypes (git.root, git.config, git.remote, git.head, git.ref, git.host) so they share the hierarchical codelinks.git.* namespace with marker warnings and are suppressible as a family. These slugs are effectively undocumented today, so the blast radius is small (#90).
The CLI previously printed marker warnings via the rich logger directly, bypassing the suppress/count choke point and dropping the subtype. Route them through get_logger().warning(subtype="marker.<subtype>") so they surface as codelinks.marker.* on stderr, are suppressible, and are counted for --strict (#90).
A list of hierarchical warning slugs, read by both frontends from the single [codelinks] config. Registered as src_trace_suppress_warnings for conf.py and schema-validated as an array of strings. Default empty, so behavior is unchanged (#90).
With -W/--strict, analyse exits 1 if any non-suppressed warning was emitted (git-metadata or marker), mirroring sphinx-build -W; crashes stay 1 and BadParameter stays 2. Suppression comes from the shared [codelinks] suppress_warnings, applied once the config is parsed. Default (no flag) is unchanged. Closes #90.
…arnings At config-inited the shared [codelinks] suppress_warnings is merged into Sphinx's native suppress_warnings so sphinx-build and sphinx-build -W honour the same list. Sphinx's matcher is flat (exact type/type.subtype or type.*), so expand_suppress_for_sphinx() expands hierarchical slugs to the concrete tokens it understands; the merge is additive so conf.py entries survive. emit_warnings now uses the codelinks.marker.* slug for consistency (#90).
Add a suppress_warnings config reference (slug table, hierarchy, both frontends), a 'Treating warnings as errors' CLI section with the exit-code contract, and a changelog entry. The docs' own src_trace.toml now sets suppress_warnings = ["codelinks.git"] so the strict -nW build is not tripped by best-effort git-metadata warnings when building from a worktree (#90).
Combine PLR0913 into the analyse command's noqa (a CLI command legitimately takes many options), simplify the .* suffix strip with str.removesuffix, and apply ruff-format to the new tests.
A per-user Claude Code permissions file was accidentally committed via git add -A. Untrack it and gitignore it.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #93 +/- ##
==========================================
+ Coverage 91.40% 92.38% +0.98%
==========================================
Files 34 34
Lines 3012 3193 +181
Branches 322 333 +11
==========================================
+ Hits 2753 2950 +197
+ Misses 160 149 -11
+ Partials 99 94 -5 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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
2 participants
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.
Summary
Implements the agreed proposal in #90 (comment 4967873974): a
-W/--strictflag forcodelinks analysethat turns warnings into a non-zero exit, plus a shared, suppressible warning-slug system so CI can enforce traceability quality gates.Closes #90.
What changed
-W/--strictflag. Without it, behaviour is unchanged (exit0). With it,analyseexits1if any non-suppressed warning was emitted — mirroringsphinx-build -W.-W-W000111BadParameter)22One suppression list, both frontends. A new
[codelinks] suppress_warningsconfig field (onCodeLinksConfig) is read by both the CLI and the Sphinx extension:-W.suppress_warningsatconfig-inited, sosphinx-build/sphinx-build -Whonour the same list; existingconf.pyentries are preserved (additive).Hierarchical, normalized slugs. All warnings now live under one namespace, matched hierarchically (
codelinks→ all,codelinks.git→ the git family,codelinks.git.root→ one):codelinks.git.{root,config,remote,head,ref,host}(wascodelinks.git_*)codelinks.marker.{too_many_fields,too_few_fields,missing_square_brackets,not_start_or_end_with_square_brackets,newline_in_field}(wasneed.*)Single choke point. All standalone warnings now flow through the logging facade's CLI backend, which is where suppression + counting happen. Previously git warnings dropped their subtype and one-line warnings bypassed the facade entirely.
Design note — Sphinx's matcher is flat
The proposal assumed Sphinx's
suppress_warningsmatches hierarchically. It doesn't: Sphinx 8.2 matches only an exacttype,type.*, ortype.subtype. So a family entry likecodelinks.gitwould silence nothing under Sphinx on its own. To keep the same list working in both frontends, the fold expands hierarchical entries to the concrete slugs Sphinx understands (via a single slug registry inlogger.py). The standalone matcher is genuinely hierarchical.Out of scope (follow-ups)
--suppress-warningCLI override (proposal marked "optional").3) for-Wfailures — proposal decided to reuse1.Backwards compatibility
Default behaviour is unchanged;
-Wis strictly opt-in. The only behavioural change is the slug rename, and those slugs were effectively undocumented, so the blast radius is small. The one-lineWarningSubTypeEnumvalues are unchanged (themarker.prefix is added only where warnings are surfaced), so this needs no ubCode parser change.The docs' own
src_trace.tomlnow setssuppress_warnings = ["codelinks.git"], dogfooding the feature and keeping the strict (-nW) docs build green when built from a git worktree (packed refs would otherwise emit a spuriouscodelinks.git.ref).Testing
expand_suppress_for_sphinxhelper, and a real Sphinx build asserting the fold is additive.codelinksbinary (help text + exit codes).mypyclean,pre-commit(ruff lint+format) clean, strict docs build succeeds.