refactor(tools): decompose oversized governance checkers into support packages - #1157
Merged
doublewhy merged 1 commit intoAug 14, 2026
Conversation
… packages The three checkers that predate the 500-line policy carried the remaining structural Sonar violations on dev (S104 file length, S138 function length, cyclomatic/cognitive complexity up to 70/66, S1142 return counts, S107 parameter counts). Each is now an import-stable entry point over a support package of focused modules, all under the 500-line cap: - tools/check_sdl_catalog_parity.py (2,039 lines) -> tools/sdl_catalog_parity/ (paths, expectation registry split at section boundaries with a merged-registry overlap guard, table rows, expected classifications, typed-model traversal, checks) - tools/check_specification_coverage.py (1,640 lines) -> tools/specification_coverage/ (keys, primitives, protocol, concepts, artifacts, snapshot, analysis) - tools/check_formal_semantic_validation.py (3,121 lines) -> tools/formal_semantic_validation/ (types, shape, replay, claims, protocol, corpus, snapshot, analysis, loading, releases, baseline, retest, production, satisfiability, supplement loading) Mega-functions are decomposed into single-responsibility helpers under the thresholds (complexity <= 10, <= 100 lines, <= 3 returns, <= 7 parameters); the two 8-parameter snapshot validators now take frozen scope dataclasses. Pure restructuring: no validation rule changes. Test updates: the three monkeypatch sites that patched replay_case, load_bounded_json_object, and subprocess.run through the old monolithic module now patch the consumer modules, preserving what each test proves (the no-replay-of-historical-evidence guarantee now pins both consumer modules). Verification: each checker produces identical output and exit status on this repo before and after (the formal checker's full offline integrity and replay pass included); nox -s tests green (7,005+ tests incl. the 80-test formal-validation suite and 25-test parity suite); ruff format and lint clean; tools/check_repo_policy.py pass. Closes #1154 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Author
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.
Plain-language summary
devSonar quality gate green (mechanical slice: ci(sonar): clear the tools new-code violations and exempt false positives #1155; package modules: refactor: resolve sonar complexity and length violations in package modules #1156).Issue mapping
1152-sonar-mechanical-exemptions; it retargets todevwhen ci(sonar): clear the tools new-code violations and exempt false positives #1155 merges and should be rebased then). Merge order: ci(sonar): clear the tools new-code violations and exempt false positives #1155 → this → the gate needs refactor: resolve sonar complexity and length violations in package modules #1156 too.Summary
tools/check_sdl_catalog_parity.py→tools/sdl_catalog_parity/: paths/regex constants, the ~1,080-line reference-edge expectation dict split at SDL-section boundaries into three parts with a merged-registry overlap guard, table dataclasses/parsers, expected-classification helpers (return-count fixes via lookup tables), typed-model traversal, and decomposed checks (_check_top_levelcomplexity 23 → per-field/per-aspect helpers;_check_references21 → five focused failure collectors).tools/check_specification_coverage.py→tools/specification_coverage/: closed key sets, shape/digest/JSON-pointer primitives (pointer walk restructured around a step function), the 417-line/complexity-94_validate_protocoldecomposed into per-section validators with a concepts sibling module, artifacts/implementation-surface validation with extracted digest and execution helpers, the 270-line/complexity-89_validate_snapshotdecomposed around a frozen context dataclass, andrecompute_analysis(complexity 34) split into counting/summary/status helpers.tools/check_formal_semantic_validation.py→tools/formal_semantic_validation/: fifteen modules (types, shape, replay, claims, protocol, corpus, snapshot, analysis, loading, releases, baseline, retest, production, satisfiability, supplement loading). The complexity-70/302-linevalidate_satisfiability_analysisand complexity-42/7-return_validate_baseline_driftbecome staged pipelines of guarded helpers; the two 8-parameter snapshot validators take frozen scope dataclasses;evaluateand the remaining >3-return functions are restructured to ≤3 exits.testsimporttools.check_<name>), with explicit__all__re-exports.Test changes
Three monkeypatch sites in
test_formal_semantic_validation.pypatchedreplay_case,load_bounded_json_object, andsubprocess.runthrough the old monolithic module; they now patch the consumer modules so each test still pins the behavior it proves. Notably, the historical-releases-never-replay-current-code guarantee now pins both replay consumers (_snapshotand_retest).Compatibility
noxscript invocation paths and all test-facing import names are unchanged.Verification
nox -s tests: green (includes the 80-test formal-validation suite, 25-test parity suite, 13-test coverage suite, and the coverage gate).tools/.tools/check_repo_policy.py: pass.🤖 Generated with Claude Code