Skip to content

refactor(tools): decompose oversized governance checkers into support packages - #1157

Merged
doublewhy merged 1 commit into
1152-sonar-mechanical-exemptionsfrom
1154-sonar-structural-decomposition
Aug 14, 2026
Merged

refactor(tools): decompose oversized governance checkers into support packages#1157
doublewhy merged 1 commit into
1152-sonar-mechanical-exemptionsfrom
1154-sonar-structural-decomposition

Conversation

@doublewhy

Copy link
Copy Markdown

Plain-language summary

Issue mapping

Summary

  • tools/check_sdl_catalog_parity.pytools/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_level complexity 23 → per-field/per-aspect helpers; _check_references 21 → five focused failure collectors).
  • tools/check_specification_coverage.pytools/specification_coverage/: closed key sets, shape/digest/JSON-pointer primitives (pointer walk restructured around a step function), the 417-line/complexity-94 _validate_protocol decomposed 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_snapshot decomposed around a frozen context dataclass, and recompute_analysis (complexity 34) split into counting/summary/status helpers.
  • tools/check_formal_semantic_validation.pytools/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-line validate_satisfiability_analysis and complexity-42/7-return _validate_baseline_drift become staged pipelines of guarded helpers; the two 8-parameter snapshot validators take frozen scope dataclasses; evaluate and the remaining >3-return functions are restructured to ≤3 exits.
  • Entry scripts keep their paths (nox invokes them by path) and their import surfaces (tests import tools.check_<name>), with explicit __all__ re-exports.

Test changes

Three monkeypatch sites in test_formal_semantic_validation.py patched replay_case, load_bounded_json_object, and subprocess.run through 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 (_snapshot and _retest).

Compatibility

  • No SDL field, schema, portable contract, CLI surface, or experiment surface changes; no validation rule changes.
  • nox script invocation paths and all test-facing import names are unchanged.

Verification

  • Equivalence: all three checkers produce byte-identical output and exit status on this repo before and after — including the formal checker's full offline integrity + replay pass (exit 0).
  • nox -s tests: green (includes the 80-test formal-validation suite, 25-test parity suite, 13-test coverage suite, and the coverage gate).
  • Ruff 0.15.9 format and lint clean across tools/.
  • tools/check_repo_policy.py: pass.
  • Every new module ≤ 500 lines; decomposed helpers hold to complexity ≤ 10, ≤ 100 lines, ≤ 3 returns, ≤ 7 parameters.

🤖 Generated with Claude Code

… 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>
@doublewhy
doublewhy merged commit a9076ad into 1152-sonar-mechanical-exemptions Aug 14, 2026
1 check passed
@doublewhy

Copy link
Copy Markdown
Author

Note: this PR shows as merged because its commit was folded into #1155's branch (its base) — Sonar's per-PR gate kept #1155 red for mega-function findings that only this decomposition removes, so the two layers now ship as one tools-scoped PR whose own gate can go green. #1155 closes #1154.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant