maintainability-agent 2.0.0__tar.gz → 2.2.0__tar.gz

{maintainability_agent-2.0.0/src/maintainability_agent.egg-info → maintainability_agent-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.0.0
+Version: 2.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.0.0**.
+Version **2.2.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.2.0}/README.md

@@ -5,7 +5,7 @@
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.0.0**.
+Version **2.2.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "2.0.0"
+version = "2.2.0"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import

{maintainability_agent-2.0.0 → maintainability_agent-2.2.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.0.0
+Version: 2.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.0.0**.
+Version **2.2.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.2.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ src/maintainability_audit/_catalog.py
 src/maintainability_audit/_charts.py
 src/maintainability_audit/_cognitive.py
 src/maintainability_audit/_config_defaults.py
+src/maintainability_audit/_conformance.py
 src/maintainability_audit/_corroborate.py
 src/maintainability_audit/_coverage_notes.py
 src/maintainability_audit/_derive.py
@@ -32,6 +33,7 @@ src/maintainability_audit/_evidence_view.py
 src/maintainability_audit/_finding_match.py
 src/maintainability_audit/_first_run.py
 src/maintainability_audit/_formula.py
+src/maintainability_audit/_gates.py
 src/maintainability_audit/_generic.py
 src/maintainability_audit/_grant_ledger.py
 src/maintainability_audit/_history_view.py
@@ -61,6 +63,7 @@ src/maintainability_audit/_ranges_csharp.py
 src/maintainability_audit/_ranges_fortran.py
 src/maintainability_audit/_ranges_java.py
 src/maintainability_audit/_ranges_js.py
+src/maintainability_audit/_ratchet.py
 src/maintainability_audit/_recurrence.py
 src/maintainability_audit/_runner.py
 src/maintainability_audit/_safe_write.py
@@ -121,6 +124,7 @@ tests/test_acquisition_trust.py
 tests/test_adapter_docs.py
 tests/test_adapter_recordings.py
 tests/test_adapters.py
+tests/test_added_lines.py
 tests/test_analysis_coverage.py
 tests/test_analysis_execution.py
 tests/test_analyzer_bridge.py
@@ -185,6 +189,7 @@ tests/test_declared_authorship.py
 tests/test_declared_imports.py
 tests/test_derivation_mix.py
 tests/test_determinism.py
+tests/test_dimension_ratchet.py
 tests/test_direct_runner_availability_class.py
 tests/test_discovery.py
 tests/test_doc_claims.py
@@ -225,6 +230,7 @@ tests/test_identity_docs.py
 tests/test_identity_resolution.py
 tests/test_idiom_divergence.py
 tests/test_installed_wheel_runtime.py
+tests/test_instruction_targets.py
 tests/test_java_range_guard.py
 tests/test_java_ranges.py
 tests/test_java_scored.py
@@ -270,6 +276,7 @@ tests/test_scan_history.py
 tests/test_scan_scope.py
 tests/test_scanning.py
 tests/test_schema_fidelity.py
+tests/test_scope_conformance.py
 tests/test_scoring_calibration.py
 tests/test_semantic_policy.py
 tests/test_setup_gate_completeness.py

{maintainability_agent-2.0.0 → maintainability_agent-2.2.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"

maintainability_agent-2.2.0/src/maintainability_audit/_conformance.py

@@ -0,0 +1,183 @@
+"""Did the diff stay inside the work order it was given?
+
+The product's central claim is a bounded work order: *fix exactly these
+findings and refactor nothing else*. Until now that bound was an
+**instruction**. The prompt said it, and nothing checked it — so an agent
+that rewrote half the tree while closing one finding produced a diff
+indistinguishable, to this tool, from one that did as it was told.
+
+This is the check that makes the bound verifiable. It reads the finished
+report and a revspec, and reports which changed files the work order
+actually named. It is the first of the three mechanisms behind the
+attestation artifact, and the one a code-generating agent cannot honestly
+perform about itself.
+
+**What it must not do is cry wolf.** A correct remediation almost always
+touches a file the work order does not name: the test that proves the fix.
+A check that flagged every good remediation would be turned off within a
+week, so a test file is in scope when it pairs to a named path by the same
+convention `_test_pairing` already uses for coverage — `test_foo.py` pairs
+to `foo.py`. A test paired to nothing named is still reported, because
+"while I was here I rewrote the suite" is exactly the drift being watched
+for.
+
+Three deliberate limits:
+
+- **It never scores.** Whether a diff was obedient is a fact about an
+  agent's behaviour, not evidence about the code's condition, so nothing
+  here reaches scoring or moves a grade.
+- **It reports, it does not gate**, unless a caller asks it to. A finding
+  can legitimately require touching a caller the work order did not name,
+  and a check that cannot be argued with becomes a check that is bypassed.
+- **It compares paths, not intent.** A file being in scope says the work
+  order named it, not that the change to it was the right one. Review is
+  still review.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ._metrics_types import is_test_path
+from ._test_pairing import subject_stem
+
+
+def _named_paths(work_order: list[dict[str, Any]]) -> set[str]:
+    """Every path the work order put in front of the agent."""
+    return {
+        str(item["path"]) for item in work_order
+        if isinstance(item, dict) and item.get("path")
+    }
+
+
+def _pairs_to_named(path: str, named: set[str]) -> bool:
+    """Whether a test file covers something the work order named.
+
+    Uses the pairing convention the coverage aspect already applies, so a
+    remediation's own test is in scope without the caller declaring it —
+    and a test that covers nothing in the work order is not.
+    """
+    if not is_test_path(path):
+        return False
+    subject = subject_stem(path)
+    if not subject:
+        return False
+    return any(subject_stem(candidate) == subject for candidate in named)
+
+
+#: Markers that switch a checker off rather than satisfy it. Per language,
+#: because the vocabulary differs and a single regex over all of them
+#: matches prose: "# type: ignore" in a docstring explaining the convention
+#: is not a suppression, and neither is this comment.
+#:
+#: Deliberately narrow. A marker here has to be a real directive that a
+#: real tool obeys; guessing wider would report ordinary comments as
+#: evasion, and a check that cries wolf is a check that gets switched off —
+#: the same reasoning as the test-pairing rule above.
+SUPPRESSION_MARKERS: tuple[tuple[str, str], ...] = (
+    (r"#\s*noqa\b", "noqa"),
+    (r"#\s*type:\s*ignore\b", "type: ignore"),
+    (r"#\s*pragma:\s*no\s*cover\b", "pragma: no cover"),
+    (r"#\s*nosec\b", "nosec"),
+    (r"//\s*eslint-disable", "eslint-disable"),
+    (r"/\*\s*eslint-disable", "eslint-disable"),
+    (r"//\s*@ts-(ignore|expect-error)\b", "ts-ignore"),
+    (r"@SuppressWarnings\b", "SuppressWarnings"),
+    (r"//\s*NOSONAR\b", "NOSONAR"),
+    (r"#\s*pylint:\s*disable\b", "pylint: disable"),
+    (r"@pytest\.mark\.(skip|xfail)\b", "skipped test"),
+    (r"@unittest\.skip\b", "skipped test"),
+    (r"\bit\.skip\(|\bdescribe\.skip\(", "skipped test"),
+    (r"@Disabled\b", "disabled test"),
+    (r"@Ignore\b", "ignored test"),
+)
+
+_SUPPRESSION = tuple(
+    (re.compile(pattern, re.IGNORECASE), label) for pattern, label in SUPPRESSION_MARKERS
+)
+
+
+def suppressions_added(
+    added: dict[str, list[tuple[int, str]]], named: set[str]
+) -> list[dict[str, Any]]:
+    """Suppressions this change introduced, and whether they land on a finding.
+
+    The failure being watched for: a finding is closed by making it
+    invisible rather than by fixing it. Add `# noqa` to the flagged line and
+    the next audit reports nothing — the scan goes green over code nobody
+    repaired, and scope conformance alone would call that diff obedient,
+    because the file it touched is exactly the file the work order named.
+
+    Only *added* lines are read. A suppression already in the tree is not
+    evidence about this change, and treating a decade of accumulated
+    directives as newly written would drown the signal that matters.
+
+    `on_named_path` is that signal: a suppression added to a file the work
+    order flagged is the shape of a finding being silenced, while one added
+    elsewhere is ordinary engineering that a reviewer may still want to see.
+    """
+    found: list[dict[str, Any]] = []
+    for path in sorted(added):
+        for line_number, text in added[path]:
+            for pattern, label in _SUPPRESSION:
+                if pattern.search(text):
+                    found.append({
+                        "path": path,
+                        "line": line_number,
+                        "marker": label,
+                        "on_named_path": path in named,
+                    })
+                    break
+    return found
+
+
+def scope_conformance(
+    report: dict[str, Any],
+    changed: set[str],
+    revspec: str,
+    added: dict[str, list[tuple[int, str]]] | None = None,
+) -> dict[str, Any]:
+    """How a diff relates to the work order the agent was handed.
+
+    Returns the record, never a verdict on the code. `in_scope`,
+    `paired_tests` and `out_of_scope` partition the changed files;
+    `unaddressed` names work-order paths the diff did not touch, which is
+    not a failure — a bounded change may take one item at a time.
+    """
+    work_order = report.get("work_order") or []
+    named = _named_paths(work_order)
+
+    in_scope = sorted(path for path in changed if path in named)
+    remaining = {path for path in changed if path not in named}
+    paired = sorted(path for path in remaining if _pairs_to_named(path, named))
+    out_of_scope = sorted(remaining - set(paired))
+    suppressions = suppressions_added(added or {}, named)
+    silenced = [item for item in suppressions if item["on_named_path"]]
+
+    return {
+        "revspec": revspec,
+        "work_order_items": len(work_order),
+        "named_paths": sorted(named),
+        "changed_paths": sorted(changed),
+        "in_scope": in_scope,
+        "paired_tests": paired,
+        "out_of_scope": out_of_scope,
+        "unaddressed": sorted(named - set(in_scope)),
+        "suppressions_added": suppressions,
+        "suppressions_on_named_paths": len(silenced),
+        # Two questions, kept apart. `conformant` answers "did it change
+        # only what it was asked to"; `clean` also answers "and without
+        # switching a checker off in a file that was flagged". Scope alone
+        # is satisfiable by adding `# noqa` to the named file and changing
+        # nothing else, which is the evasion this pairing exists to catch.
+        "conformant": not out_of_scope,
+        "clean": not out_of_scope and not silenced,
+        # Stated so a reader does not infer more than was checked. The
+        # record says which files the work order named, not whether the
+        # edits inside them were the right ones.
+        "note": (
+            "Paths and added lines. A file in scope means the work order "
+            "named it, not that the change to it was correct."
+        ),
+    }

maintainability_agent-2.2.0/src/maintainability_audit/_gates.py

@@ -0,0 +1,122 @@
+"""What happens after the audit and before the exit code.
+
+Split from `cli.py` when it crossed this project's 500-line file gate —
+the same reason `_mcp_setup`, `_adapters` and `test_architecture` were
+split before it.
+
+The split is not arbitrary. Everything here composes from the **finished
+report**: whether the diff obeyed its work order, whether a dimension
+slipped since the last comparable scan, and what those two facts mean for
+the process exit code. None of it measures a tree and none of it may reach
+scoring — a fact about an agent's behaviour, or about the difference
+between two scans, is not evidence about the code's condition.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .baseline import findings_not_in_baseline
+from .git_tools import added_lines, changed_paths
+
+
+def attach_conformance(args: argparse.Namespace, report: dict) -> None:
+    """Record how the diff relates to the work order, when asked.
+
+    Assembly, not scoring: the record is attached to the report and reaches
+    no dimension, because whether a diff was obedient is a fact about an
+    agent's behaviour and not evidence about the code's condition.
+    """
+    if not args.conformance:
+        return
+    from ._conformance import scope_conformance
+
+    root = Path(report["root"])
+    changed = changed_paths(root, args.conformance)
+    added = added_lines(root, args.conformance)
+    report["scope_conformance"] = scope_conformance(
+        report, changed, args.conformance, added
+    )
+
+
+def attach_ratchet(report: dict, history_path: Path) -> None:
+    """Record whether any category slipped since the last comparable scan."""
+    from ._ratchet import dimension_ratchet
+    from ._scan_history import read_history
+
+    if not history_path.exists():
+        return
+    report["dimension_ratchet"] = dimension_ratchet(read_history(history_path))
+
+
+def _attach_post_audit_records(
+    args: argparse.Namespace, report: dict, history_path: Path
+) -> None:
+    """Records composed from the finished report, before it is rendered.
+
+    Both read the report rather than the tree, and neither reaches scoring:
+    whether a diff obeyed its work order, and whether a dimension slipped
+    since the last comparable scan, are facts about a change and its
+    history — not evidence about the code's condition.
+    """
+    attach_conformance(args, report)
+    attach_ratchet(report, history_path)
+
+
+def _conformance_exit(args: argparse.Namespace, report: dict) -> int:
+    """0 to continue; otherwise the exit code the conformance gate demands."""
+    if not args.fail_on_out_of_scope:
+        return 0
+    record = report.get("scope_conformance")
+    if record is None:
+        print("--fail-on-out-of-scope needs --conformance REVSPEC", file=sys.stderr)
+        return 2
+    # `clean`, not `conformant`: staying in scope while silencing the finding
+    # is the evasion the pairing exists to catch, and a gate that accepted it
+    # would be satisfied by the thing it guards against.
+    return 0 if record["clean"] else 1
+
+
+def _regression_exit(args: argparse.Namespace, report: dict) -> int:
+    """0 to continue; otherwise the exit code the ratchet demands."""
+    if not args.fail_on_regression:
+        return 0
+    ratchet = report.get("dimension_ratchet")
+    if ratchet is None:
+        print("--fail-on-regression needs a recorded history (--record-history)",
+              file=sys.stderr)
+        return 2
+    # A run that could not compare does not pass quietly: exiting 0 where the
+    # question was never asked is the "absence read as a pass" shape.
+    #
+    # The reason is not interpolated — it derives from recorded scan history,
+    # and code scanning is right that history fields have no business in a log
+    # line. It stays in the report, which a caller reads deliberately.
+    # Suppressing that alert was refused: this release ships the check that
+    # treats a suppression as a finding rather than a fix.
+    if not ratchet["comparable"]:
+        print("no comparable scan for --fail-on-regression; see "
+              "dimension_ratchet.reason in the report", file=sys.stderr)
+        return 2
+    return 1 if ratchet["regressed"] else 0
+
+
+def audit_exit_code(args: argparse.Namespace, report: dict) -> int:
+    if args.fail_on_new:
+        # Structured matching, never a label-set difference: a label
+        # changes under `git mv` and same-name reorder, and failing a
+        # build over either is a false report about the change.
+        root = Path(report["root"])
+        if findings_not_in_baseline(report, args.baseline, root):
+            return 1
+    if args.fail_on_gate and report["hard_gate_failures"]:
+        return 1
+    conformance = _conformance_exit(args, report)
+    if conformance:
+        return conformance
+    regression = _regression_exit(args, report)
+    if regression:
+        return regression
+    return 0

maintainability_agent-2.2.0/src/maintainability_audit/_ratchet.py

@@ -0,0 +1,109 @@
+"""Did any dimension get worse than the last comparable scan?
+
+The third mechanism behind the attestation. `--fail-on-new` already catches
+a finding that clears and returns, using structured identity so a rename is
+not a new finding. What nothing caught is the slower failure: a change that
+improves one dimension while quietly regressing another. Both scans are
+green by every existing gate, the overall estimate can even rise, and the
+thing that got worse is never named.
+
+**The comparison is only honest inside one segment.** History is already
+split wherever the instrument changed — a different calibration constant, a
+different analyzer population — because two scans taken with different
+instruments cannot be subtracted. `_scan_history.segments` owns that rule,
+and this module refuses rather than reaching across a break. A ratchet that
+compared a 1.x score to a 2.0 score would have reported every repository on
+earth as catastrophically regressed on the day the corpus was extended, and
+it would have been the ratchet that was wrong.
+
+So there are three outcomes, not two: **held**, **regressed**, and **not
+comparable**. The third is not a pass. It says the question could not be
+asked, which is what a reader needs in order to know they are not being
+reassured by silence.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._scan_history import ScanRecord, segments
+
+#: Scores are reported to one decimal, so a difference below this is the
+#: rounding boundary rather than a movement. Named rather than inlined
+#: because it is a judgment: too tight and every scan trips on noise, too
+#: loose and a real slide hides under the threshold.
+TOLERANCE = 0.05
+
+
+def _series(record: ScanRecord, field: str) -> dict[str, float]:
+    values = getattr(record, field, None) or {}
+    return {
+        name: float(value) for name, value in values.items()
+        if isinstance(value, (int, float))
+    }
+
+
+def _regressions(
+    previous: ScanRecord, current: ScanRecord, field: str
+) -> list[dict[str, Any]]:
+    """Names that dropped, with the size of the drop."""
+    before, after = _series(previous, field), _series(current, field)
+    found = []
+    for name, was in sorted(before.items()):
+        # A name the current scan does not carry is not a regression: the
+        # aspect became unmeasurable, which the evidence model already
+        # reports as `Unknown` rather than as a zero. Scoring it as a drop
+        # to nothing would turn withheld evidence into a failure, which is
+        # the exact inversion P3 forbids.
+        if name not in after:
+            continue
+        now = after[name]
+        if was - now > TOLERANCE:
+            found.append({
+                "name": name, "was": round(was, 2),
+                "now": round(now, 2), "drop": round(was - now, 2),
+            })
+    return found
+
+
+def dimension_ratchet(records: list[ScanRecord]) -> dict[str, Any]:
+    """Compare the newest scan with the previous comparable one.
+
+    `comparable` is the load-bearing field. False means the two scans sit
+    either side of an instrument change, or there is no earlier scan at
+    all — in both cases the question was not asked, and a caller must not
+    read that as "nothing regressed".
+    """
+    if len(records) < 2:
+        return {
+            "comparable": False,
+            "reason": "no earlier scan to compare against",
+            "regressed": [],
+        }
+
+    latest = segments(records)[-1]
+    if len(latest.records) < 2:
+        return {
+            "comparable": False,
+            "reason": (
+                latest.break_reason
+                or "the previous scan was taken with a different instrument"
+            ),
+            "regressed": [],
+        }
+
+    previous, current = latest.records[-2], latest.records[-1]
+    categories = _regressions(previous, current, "categories")
+    aspects = _regressions(previous, current, "aspects")
+
+    return {
+        "comparable": True,
+        "against": getattr(previous, "commit", None),
+        "categories": categories,
+        "aspects": aspects,
+        # Categories only. An aspect can move while the category holding it
+        # holds, and failing on every aspect wobble makes the gate noise.
+        # Aspects are reported so a reader can see what moved underneath.
+        "regressed": categories,
+        "held": not categories,
+    }