Repository navigation
ci(lint): enforce Stage 2 complexity limits with a shrink-only ratchet - #3615
Daniel Meppiel (danielmeppiel) wants to merge 11 commits into
Conversation
New and changed functions must meet the Stage 2 Ruff limits (max-statements 120, max-branches 40, max-complexity 35, max-args 12, max-returns 8). Existing violators are grandfathered in tests/quality/complexity_baseline.json, keyed by file and function qualname with no line numbers. The Lint job fails on new violations, baseline growth against the base commit, or stale entries. Extends scripts/ratchet_baseline.py with load_baseline_at_ref so the growth check reuses the shared baseline lifecycle. Refs #1076 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…076-complexity-ratchet
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues block approval of the complexity-ratchet changes.
No open issues 🎉
What changed in this PR
This PR replaces the broad Stage 2 refactoring effort with an incremental complexity ratchet in APM's lint pipeline. It preserves existing violations while preventing new function-and-rule violations and requiring resolved baseline entries to be removed.
Changes:
- Adds a Stage 2 Ruff checker and shrink-only baseline covering 181 existing violations across 126 functions.
- Integrates base-commit comparison into CI and adds regression tests for growth, pruning, stable function identities, and
noqahandling. - Updates contributor guidance and lint instructions without changing runtime behavior or Stage 1 thresholds.
| File | Description |
|---|---|
tests/unit/scripts/test_check_complexity_ratchet.py |
Adds fixture-based ratchet regression tests. |
tests/quality/complexity_baseline.json |
Records grandfathered violations by file, function, and rule. |
scripts/ratchet_baseline.py |
Adds shared baseline loading from a Git ref. |
scripts/check_complexity_ratchet.py |
Implements Stage 2 checks, growth detection, and pruning. |
scripts/architecture_linter/checks/contracts_structural_authorities.py |
Registers the checker as a shared-baseline consumer. |
pyproject.toml |
Clarifies Stage 1 and Stage 2 enforcement in comments only. |
docs/src/content/docs/contributing/development-guide.md |
Documents limits, failures, and baseline maintenance. |
CONTRIBUTING.md |
Links contributors to the complexity guidance. |
CHANGELOG.md |
Records the new contributor-facing lint requirement. |
.github/workflows/ci.yml |
Runs the ratchet against the base commit and includes its tests. |
.github/instructions/linting.instructions.md |
Adds the ratchet to lint instructions. |
.github/copilot-instructions.md |
Updates generated lint guidance. |
.apm/instructions/linting.instructions.md |
Updates canonical lint instructions and local verification commands. |
Review effort: Balanced
…076-complexity-ratchet
Main gained eight Stage 2 violators since the baseline was cut (local bundle detection, plugin export, deps scope resolution, init, marketplace add, GitLab policy ancestry, remote policy URL parsing, extends host extraction), and _parse_remote_url moved from policy/discovery.py to policy/_remote.py. The bootstrap baseline must list exactly the current violators, so it is regenerated from the merge with main: 188 entries across 132 functions. The growth check is a no-op until this baseline exists on main; after that only shrinking is allowed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 1 | 1 | Correctly reuses ratchet_baseline as the canonical lifecycle owner; set algebra is sound. git-show None path conflates absent with errored. |
| Test Coverage Expert | 0 | 0 | 1 | All three Done-when scenarios (fail-on-new, fail-on-growth, pass-on-shrink) pass at integration-with-fixtures tier; 10 tests. |
| Doc Writer | 0 | 1 | 2 | Docs match the script and the mirrors are identical; the guide's local command does not run the base-branch growth check. |
| Supply Chain Security Expert | 0 | 0 | 2 | Env-only SHA interpolation, list-form subprocess, no secrets, fail-closed defaults; growth/noqa/rename bypasses blocked. |
| Devx Ux Expert | 0 | 1 | 1 | Failure messages are clear and actionable; one prefix misuse blurs error vs guidance in the stale-entry path. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Python Architect] Distinguish git-show "absent at ref" from git errors in
load_baseline_at_ref; raiseBaselineErroron unexpected failures instead of returningNone. -- Closes the one fail-open seam in an otherwise fail-closed gate (three-persona convergence). - [Doc Writer] Show the CI form with
--base-ref origin/mainin the development guide and mirror it in the linting instruction. -- Without it the documented growth failure cannot be reproduced locally. - [Devx Ux Expert] Print the stale-entry remediation line with
[i]instead of[x]. -- Guidance should be visually distinct from the failure. - [Devx Ux Expert] Print the concrete Stage 2 limits in the growth-failure message. -- Parity with the new-violation path.
- [Python Architect] Comment in
_validated_entriesthat a base-ref limits mismatch is intentional and how a future limit-tightening PR handles it. -- Prevents misreading it as a bug.
Architecture
classDiagram
direction LR
class ratchet_baseline {
<<LifecycleOwner>>
+load_baseline(path, label) dict
+load_baseline_at_ref(root, path, ref, label) dict_or_None
+validate_provisional(payload, path, allow, label) dict_or_None
+write_baseline(path, payload, label) None
}
class BaselineError {
<<Exception>>
}
class check_complexity_ratchet {
<<Consumer>>
+main(argv) int
+observe(root) set_Entry
-_check_base_growth(root, baseline, ref, current) bool
-_validated_entries(payload, where) set_Entry
}
class check_test_assertions {
<<Consumer>>
}
class contracts_structural_authorities {
<<BoundaryGuard>>
}
ratchet_baseline ..> BaselineError : raises
check_complexity_ratchet ..> ratchet_baseline : imports lifecycle
check_test_assertions ..> ratchet_baseline : imports lifecycle
contracts_structural_authorities ..> check_complexity_ratchet : guards import
flowchart TD
A["CI: check_complexity_ratchet.py --base-ref BASE_SHA"] --> B["load_baseline complexity_baseline.json"]
B --> D{"base ref set?"}
D -- yes --> E["git rev-parse + git show ref:baseline"]
E -- absent --> G
E -- present --> E4{"baseline minus base baseline empty?"}
E4 -- no --> E5["grew"]
E4 -- yes --> G
E5 --> G
D -- no --> G["ruff --ignore-noqa at Stage 2 limits, map to path::qualname"]
G --> H{"new?"}
H -- yes --> H1["exit 1: new violation"]
H -- no --> I{"grew?"}
I -- yes --> I1["exit 1: baseline grew"]
I -- no --> J{"stale?"}
J -- "yes, no --update-baseline" --> J1["exit 1: stale entries"]
J -- "yes, --update-baseline" --> K["prune-only write"]
J -- no --> L["exit 0"]
K --> L
Recommendation
The ratchet is architecturally sound, CI-safe, and well-tested at integration tier. Fold the in-scope items (git-show error distinction, doc --base-ref command, [x] to [i] prefix, growth-message limits, _validated_entries comment) before landing; the merge-worker handles them in one pass. Sequencing: this PR lands last in the 0.36.0 push and its baseline is regenerated from final main right before landing.
Full per-persona findings
Python Architect
- [recommended]
load_baseline_at_refreturns None on ANY git-show failure, silently skipping the growth check for non-absence errors atscripts/ratchet_baseline.py:76
The None path is the intended bootstrap case, but a shallow-fetch tree gap, permission error or corrupt blob takes the same path and the gate opens with only an[i]line. - [nit]
_validated_entriesrejects a limits mismatch on the base-ref payload, which a future limit-tightening PR will hit atscripts/check_complexity_ratchet.py:150
Worth a code comment so the next author does not debug it from scratch.
Test Coverage Expert
- [nit]
load_baseline_at_referror branches have no dedicated unit test attests/unit/scripts/test_ratchet_baseline.py
Happy and None paths are exercised at integration-with-fixtures tier through the complexity ratchet tests; unknown-ref, outside-root and absent-at-ref are not asserted directly.
Proof (missing at):tests/unit/scripts/test_ratchet_baseline.py::test_load_baseline_at_ref_raises_on_unknown_ref-- proves: the shared growth-detection helper rejects invalid refs instead of silently skipping. [governed-by-policy]
Doc Writer
- [recommended] The development guide says the check fails on baseline growth, but its local command never runs that check at
docs/src/content/docs/contributing/development-guide.md:349
_check_base_growthonly runs with--base-ref. - [nit] "Moving or renaming a grandfathered function counts as new code" is broader than
path::qualnameidentity atdocs/src/content/docs/contributing/development-guide.md:357
Moving within the same file and scope keeps the key. - [nit] The CHANGELOG entry repeats the full limit list that the guide owns at
CHANGELOG.md:34
Supply Chain Security Expert
- [nit] git-show failure conflation in
load_baseline_at_refatscripts/ratchet_baseline.py:72
Fail-closed would refuse rather than skip when the check cannot be verified. - [nit] LIMITS/RULES/SCOPE are editable in the same PR as the baseline at
scripts/check_complexity_ratchet.py:36
Inherent to any in-repo CI gate; mitigated by CODEOWNERS review. Not a regression.
Devx Ux Expert
- [recommended] Stale-entry remediation line uses the
[x]error prefix atscripts/check_complexity_ratchet.py:223 - [nit] Growth failure omits the concrete Stage 2 limits at
scripts/check_complexity_ratchet.py:181
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
load_baseline_at_ref returned None for any git show failure, so a corrupt object or partial tree silently skipped the growth check. It now treats only a path absent from the ref's tree (git ls-tree) as "no baseline yet" and raises BaselineError for every other git failure. Output: the stale-entry remediation line uses [i] instead of [x], and the growth failure prints the Stage 2 limits like the new-violation path. A comment records that the base copy must carry the same limits, rules and scope, which stops a change from loosening the constants and re-baselining in one step. Tests cover the fail-closed path (deleted blob), changed limits against the base ref, and the load_baseline_at_ref contract (absent -> None, present -> payload, unknown ref, path outside root). Each new guard was mutation-broken and its test failed. Addresses panel follow-ups 1, 3, 4, 5 (python-architect, supply-chain-security-expert, test-coverage-expert, devx-ux-expert) on the iteration-1 advisory. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The documented local command skipped the baseline-growth check because it ran without --base-ref, so contributors could not reproduce that CI failure. The development guide and the lint contract now show the --base-ref origin/main form. The identity note now says renaming or moving to another file or class counts as new code (moving lines within the same scope does not). The CHANGELOG entry drops the duplicated limit list. Generated mirrors and the lockfile content hash are refreshed. Addresses panel follow-up 2 and doc-writer nits on the iteration-1 advisory. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…076-complexity-ratchet
Regenerated from the merge with main fe6f089 (includes #3610) so the grandfathered set is exactly the current violators: 188 entries across 131 functions. Main fixed two (audit _audit_ci_gate statements, marketplace add) and added two (install/drift _materialize_install_path args, one extra branch count on an already listed function). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | Both prior findings resolved cleanly; no new architectural fault. |
| Test Coverage Expert | 0 | 0 | 0 | Prior nit closed: four new tests cover load_baseline_at_ref error branches with mutation-break proof. |
| Doc Writer | 0 | 0 | 0 | All three prior doc findings fixed and accurate; the .github linting mirror is byte-identical to .apm canonical. |
| Supply Chain Security Expert | 0 | 0 | 0 | Fail-closed ls-tree check, base-ref limits validation, list-form argv with verified ref; no new surface. |
| Devx Ux Expert | 0 | 0 | 0 | Remediation now uses [i]; growth message prints the numeric limits; new error messages are actionable. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Recommendation
All five prior follow-ups are folded and verified by their owning personas. Zero new findings, CI green on merged main, no review threads outstanding. Ready to land as the final piece of the 0.36.0 push.
Folded in this run
- (panel) Fail closed when the base baseline cannot be read; only a path absent from the ref tree means bootstrap -- resolved in 0f1b90e.
- (panel) Stale-entry remediation printed with
[i]; growth failure prints the Stage 2 limits -- resolved in 0f1b90e. - (panel) Comment and test: base-ref limits/rules/scope must match, so constants cannot be loosened and re-baselined in one step -- resolved in 0f1b90e.
- (panel) Tests for the
load_baseline_at_refcontract (absent, present, unknown ref, outside root) -- resolved in 0f1b90e. - (panel) Guide and lint contract show
--base-ref origin/main; rename/move wording; CHANGELOG trimmed; mirrors and lock hash refreshed -- resolved in 5a0114c. - (merge-worker) Baseline regenerated from current main twice -- resolved in 66365bc and f4e8bc9.
Copilot signals reviewed
- Copilot overview review on
0159297reported no open issues and left zero inline comments (two fetches; drained).
Regression-trap evidence (mutation-break gate)
test_unreadable_base_baseline_fails_closed-- deletedraise BaselineErroron git show failure (returned None); test FAILED as expected; guard restored.test_changed_limits_against_base_ref_are_rejected-- deleted_validated_entrieson the base payload; test FAILED as expected; guard restored.test_load_baseline_at_ref_contract,test_bootstrap_without_base_baseline_skips_growth_check-- deleted the ls-tree absence check; tests FAILED as expected; guard restored.test_baseline_growth_against_base_ref_fails,test_added_rule_on_grandfathered_function_counts_as_growth-- forcedadded = set(); tests FAILED as expected; guard restored.test_fixed_function_must_leave_baseline-- forcedstale = set(); test FAILED as expected; guard restored.
Lint contract
ruff check and ruff format --check (ruff 0.15.12, CI paths), pylint R0801, lint-auth-signals.sh and lint-architecture-boundaries.sh all silent on the merged head.
CI
All checks green at f4e8bc9 (CI incl. Lint with "complexity ratchet clean: 188", CodeQL, Spec conformance, Merge Gate, license/cla) (after 0 CI fix iteration(s)).
Mergeability status
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3615 | f4e8bc9 |
ship_now | 2 | 6 | 0 | 2 | green | MERGEABLE | BLOCKED | pending required review |
Convergence
2 outer iteration(s); 2 Copilot round(s). Final panel stance: ship_now.
Ready for maintainer review.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
Description
TL;DR
New and changed functions must now meet the Stage 2 Ruff complexity limits (max-statements 120, max-branches 40, max-complexity 35, max-args 12, max-returns 8). The 181 existing violations (126 functions) are grandfathered in a shrink-only JSON baseline, keyed by file and function qualname with no line numbers. The CI
Lintjob fails on a new violation, on baseline growth against the base commit, or on a stale entry. Existing code is not refactored.Note
Local preflight skipped by maintainer instruction (2026-11-12); CI is the gate.
Problem (WHY)
pyproject.tomlstill enforced only Stage 1 ceilings (200 statements, 60 branches, complexity 50), so new code could add functions close to those limits.The maintainer decided (#1076 record below) to replace the program with a ratchet. The record's Done-when: "Adding an entry fails CI; a fixed function must be removed from the baseline."
Approach (WHAT)
scripts/check_complexity_ratchet.pyruns Ruff with only C901/PLR0911/PLR0912/PLR0913/PLR0915 at Stage 2 limits over the same paths as theRuff lintstep, then maps each diagnostic topath::qualnamethrough the AST.scripts/ratchet_baseline.pylifecycle (load, provisional validation, atomic LF write). That module gains one shared helper,load_baseline_at_ref, for the growth check.--base-ref <sha>compares the working baseline with the committed one at the base commit, so editing the JSON cannot grandfather new debt.--update-baselineonly prunes fixed entries and refuses to add new ones, matching the existing ratchets.--ignore-noqastops a# noqa: C901from bypassing the ratchet. Stage 1ruff checkstill honors noqa.Implementation (HOW)
scripts/check_complexity_ratchet.py(new): Ruff invocation with--configoverrides, qualname mapping (Outer.<locals>.inner,Class.method), and shape validation. The baseline'slimits,rulesandscopemust equal the script constants, so a loosened limit fails with exit 2.scripts/ratchet_baseline.py: addsload_baseline_at_ref(gitrev-parse+show,Nonewhen the file is absent at the ref, which lets this PR bootstrap the baseline). The existing functions are unchanged.tests/quality/complexity_baseline.json(new): 181 entries generated from this branch merged withmain..github/workflows/ci.yml: newLintstep afterRuff format check. It fetchespull_request.base.sha || merge_group.base_shaand runs the check with--base-ref. The new test file is added toArchitecture Ratchet Contracts.scripts/architecture_linter/checks/contracts_structural_authorities.py: registers the new script as a ratchet-authority consumer (it must importratchet_baseline).pyproject.toml: comments only. Stage 1 thresholds stay as absolute ceilings.#complexity-ratchet),CONTRIBUTING.mdpointer, lint contract in.apm/instructions/linting.instructions.mdwith identical edits to the generated.github/instructions/linting.instructions.mdand.github/copilot-instructions.md, plus a CHANGELOG entry.Diagram
The decision path the check takes on each run:
flowchart LR A["Ruff at Stage 2 limits<br/>--ignore-noqa"] --> B["Map row to path::qualname"] B --> C{"Observed minus baseline<br/>is empty?"} C -- no --> F1["Fail: new violation"] C -- yes --> D{"Baseline minus base-ref<br/>baseline is empty?"} D -- no --> F2["Fail: baseline grew"] D -- yes --> E{"Baseline minus observed<br/>is empty?"} E -- no --> F3["Fail: stale entry<br/>(prune with --update-baseline)"] E -- yes --> P["Pass"]Trade-offs
pyproject.toml: tightening the config would fail on every grandfathered function unless each got a noqa, which touches 126 functions. That is out of scope.Lintafter mergingmain, and will need to split that function. They cannot add it to the baseline.Validation
Local validation only, following the maintainer directive. CI is the authority.
Commands and results
pytest -p no:xdist tests/unit/scripts/test_check_complexity_ratchet.py tests/unit/scripts/test_ratchet_baseline.pypytest -p no:xdist tests/quality/test_ci_topology.py tests/unit/test_windows_native_symlink_workflow.py(+ the two above)python scripts/check_complexity_ratchet.py --base-ref origin/main(after mergingmain)[i] no complexity baseline at origin/main; skipping baseline growth check/[+] complexity ratchet clean: 181 grandfathered violation(s)ruff check+ruff format --checkon the CI lint scopepylint --enable=R0801 ... --fail-on=R0801bash scripts/lint-auth-signals.sh[+] auth-signal lint cleanbash scripts/lint-architecture-boundaries.shadded = set()in the growth checktest_baseline_growth_against_base_ref_failsandtest_added_rule_on_grandfathered_function_counts_as_growthFAIL; restoredstale = set()test_fixed_function_must_leave_baselineFAILS; restoredScenario evidence (
tests/unit/scripts/test_check_complexity_ratchet.py):test_new_violation_outside_baseline_fails,test_noqa_does_not_bypass_the_ratchettest_baseline_growth_against_base_ref_fails,test_added_rule_on_grandfathered_function_counts_as_growth,test_update_refuses_to_add_new_violationtest_shrink_passes_against_base_ref,test_fixed_function_must_leave_baselinetest_grandfathered_violations_pass_without_line_numbers(shifting the function down keeps it matched)test_loosened_limits_are_rejectedIssue and approved scope
Issue: Fixes #1076
Human scope-approval comment: #1076 (comment) (apm-scope:v1, Decision approve, review contact Daniel Meppiel (@danielmeppiel); reconfirmed by Daniel Meppiel (@danielmeppiel) on 2026-11-12, W2-6, Tier 2).
This PR completes the issue. Out of scope, as recorded: refactoring existing violators, Stage 3/4 limits, file-length guardrail changes, reviving PR #1681, and any behavior change.
Type of change
Testing
How to test
src/, runuv run --frozen --extra dev python scripts/check_complexity_ratchet.py, and see exit 1 withnew complexity violation.tests/quality/complexity_baseline.jsonand run with--base-ref origin/mainafter this merges; seecomplexity baseline grew.--update-baselineand see it pass.Spec conformance (OpenAPM v0.1)
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com