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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.2.0
+Version: 2.3.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.2.0**.
+Version **2.3.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.2.0 → maintainability_agent-2.3.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.2.0**.
+Version **2.3.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.2.0 → maintainability_agent-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "2.2.0"
+version = "2.3.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.2.0 → maintainability_agent-2.3.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.2.0
+Version: 2.3.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.2.0**.
+Version **2.3.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.2.0 → maintainability_agent-2.3.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/maintainability_audit/__main__.py
 src/maintainability_audit/_adapters.py
 src/maintainability_audit/_analysis.py
 src/maintainability_audit/_aspects.py
+src/maintainability_audit/_attestation.py
 src/maintainability_audit/_backfill.py
 src/maintainability_audit/_bands.py
 src/maintainability_audit/_built_ins.py
@@ -144,6 +145,7 @@ tests/test_artifact_write_route_class.py
 tests/test_aspect_coverage.py
 tests/test_asset_snapshot_class.py
 tests/test_ast_reading_resolves_spellings.py
+tests/test_attestation.py
 tests/test_audit_components.py
 tests/test_authorization_freshness.py
 tests/test_authorship_gates.py

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

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

maintainability_agent-2.3.0/src/maintainability_audit/_attestation.py

@@ -0,0 +1,166 @@
+"""The record a generator cannot produce about its own output.
+
+The three mechanisms — scope conformance, suppression detection, the
+dimension ratchet — each answer one question about a change. This composes
+them into the artifact they were built for: a per-change record of what was
+measured, what the agent was told to change, what it actually changed, and
+what moved.
+
+**Why an independent process has to emit it.** A platform that generates
+code and then reports on its quality is producing a self-assessment. That
+is a property of the arrangement, not a criticism of any particular one,
+and no amount of engineering removes it. The question a reviewer asks is
+*who checked this, and can they re-derive the check months from now* — and
+an author cannot be the answer. This tool writes nothing, runs no model,
+and returns the same verdict from the same inputs, which is the only reason
+its answer can be evidence rather than an opinion.
+
+**It is reproducible, not signed.** Every field is derived from the report
+and the pinned inputs, and the digest at the end is over the record's own
+content, so two runs on the same commit with the same analyzer versions
+produce the same digest. That makes it *verifiable* — anyone can re-run and
+compare. It is deliberately not called a signature: nothing here holds a
+key, and claiming a cryptographic guarantee this does not provide would be
+exactly the kind of overclaim the rest of the project spends its time
+removing. Signing the artifact, if a caller wants that, is a step they take
+with their own key on a file whose bytes are stable.
+
+**What it does not establish.** The record says which files the work order
+named and whether a checker was switched off — not whether the edits were
+correct. It never opens the diff to judge it, and it never touches a score.
+Review is still review.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+ARTIFACT_VERSION = 1
+
+
+def _verdicts(report: dict[str, Any]) -> list[str]:
+    """One line per question that was actually asked."""
+    lines: list[str] = []
+    conformance = report.get("scope_conformance")
+    if conformance:
+        out = len(conformance["out_of_scope"])
+        silenced = conformance["suppressions_on_named_paths"]
+        lines.append(
+            f"- **Stayed inside the work order:** "
+            f"{'yes' if conformance['conformant'] else f'no — {out} file(s) outside it'}"
+        )
+        lines.append(
+            f"- **Without silencing a finding:** "
+            f"{'yes' if not silenced else f'no — {silenced} suppression(s) on flagged files'}"
+        )
+    ratchet = report.get("dimension_ratchet")
+    if ratchet:
+        if not ratchet["comparable"]:
+            lines.append(
+                f"- **No dimension regressed:** not established — {ratchet['reason']}"
+            )
+        elif ratchet["regressed"]:
+            names = ", ".join(item["name"] for item in ratchet["regressed"])
+            lines.append(f"- **No dimension regressed:** no — {names}")
+        else:
+            lines.append("- **No dimension regressed:** yes")
+    return lines
+
+
+def _measured(report: dict[str, Any]) -> list[str]:
+    score = report.get("score") or {}
+    coverage = report.get("analyzer_coverage") or {}
+    status = score.get("evidence_status")
+    if isinstance(status, dict):
+        status = status.get("status")
+    ran = (coverage.get("by_outcome") or {}).get("ran") or []
+    return [
+        f"- Estimate: {score.get('maintainability_estimate', 'withheld')}",
+        f"- Verified grade: {score.get('verified_grade') or 'withheld'}",
+        f"- Evidence: {status or 'unstated'}",
+        f"- Analyzers that ran: {len(ran)}",
+        f"- Hard gate failures: {len(report.get('hard_gate_failures') or [])}",
+    ]
+
+
+def attestation_record(report: dict[str, Any]) -> dict[str, Any]:
+    """The structured record, before rendering."""
+    conformance = report.get("scope_conformance") or {}
+    ratchet = report.get("dimension_ratchet") or {}
+    score = report.get("score") or {}
+    record = {
+        "artifact_version": ARTIFACT_VERSION,
+        "tool_version": report.get("tool_version"),
+        "commit": report.get("git_commit"),
+        "branch": report.get("git_branch"),
+        # A finding reported against "the commit" that actually depends on
+        # uncommitted work is unreproducible, so the state of the tree is
+        # part of what is attested rather than a footnote.
+        "tree_dirty": bool(report.get("git_status_short")),
+        "revspec": conformance.get("revspec"),
+        "estimate": score.get("maintainability_estimate"),
+        "verified_grade": score.get("verified_grade"),
+        "stayed_in_scope": conformance.get("conformant"),
+        "no_finding_silenced": (
+            None if not conformance else conformance["suppressions_on_named_paths"] == 0
+        ),
+        "no_dimension_regressed": (
+            None if not ratchet or not ratchet.get("comparable")
+            else not ratchet["regressed"]
+        ),
+        "scope_conformance": conformance or None,
+        "dimension_ratchet": ratchet or None,
+    }
+    # The digest is over the record without it, so it is reproducible: the
+    # same commit measured with the same analyzer versions yields the same
+    # value, and anyone can recompute it rather than trust it.
+    record["digest"] = hashlib.sha256(
+        json.dumps(record, sort_keys=True, default=str).encode("utf-8")
+    ).hexdigest()[:16]
+    return record
+
+
+def render_attestation(report: dict[str, Any]) -> str:
+    """The record as text, for a reviewer or an audit trail."""
+    record = attestation_record(report)
+    dirty = " (uncommitted changes present)" if record["tree_dirty"] else ""
+    lines = [
+        "# Maintainability attestation",
+        "",
+        "An independent, deterministic check on a change. Produced by a "
+        "process that generated none of the code it examined.",
+        "",
+        f"- Commit: `{record['commit'] or 'unknown'}`{dirty}",
+        f"- Branch: `{record['branch'] or 'unknown'}`",
+        f"- Tool version: {record['tool_version'] or 'unknown'}",
+        f"- Compared: `{record['revspec'] or 'not asked'}`",
+        "",
+        "## What was measured",
+        "",
+        *_measured(report),
+        "",
+        "## What the change did",
+        "",
+    ]
+    verdicts = _verdicts(report)
+    lines += verdicts or ["- Nothing was asked: run with `--conformance` and "
+                          "`--fail-on-regression` to populate this section."]
+    lines += [
+        "",
+        "## What this does not establish",
+        "",
+        "- It compares paths and reads added lines. A file in scope means the "
+        "work order named it, **not** that the change to it was correct — this "
+        "never opens the diff to judge it.",
+        "- It touches no score. Whether a change obeyed its instructions is a "
+        "fact about behaviour, not evidence about the code's condition.",
+        "- It is reproducible, **not signed**. The digest is over this "
+        "record's own content, so the same inputs reproduce it and anyone can "
+        "recompute it. Nothing here holds a key.",
+        "",
+        f"Digest: `{record['digest']}`",
+        "",
+    ]
+    return "\n".join(lines)

{maintainability_agent-2.2.0 → maintainability_agent-2.3.0}/src/maintainability_audit/cli.py

@@ -97,6 +97,14 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--prompt-output", help="Optional Markdown prompt for AI-assisted remediation.")
     parser.add_argument("--comment-output", help="Optional Markdown body suitable for a PR comment.")
     parser.add_argument("--agent-instructions-output", help="Optional reusable instructions for AI coding agents.")
+    parser.add_argument(
+        "--attestation-output",
+        help="Write the attestation: an independent, reproducible record of "
+             "what was measured, what the change was told to do, what it did, "
+             "and what moved. Populated by --conformance and "
+             "--fail-on-regression; a generator cannot produce this about its "
+             "own output.",
+    )
     parser.add_argument("--hostile-prompt-output",
                         help="Optional adversarial audit brief seeded from this run (ADR 013). "
                              "Text only: it does not gate, score, or send anything.")
@@ -227,6 +235,10 @@ def write_outputs(args: argparse.Namespace, report: dict, rendered: str) -> None
         write_artifact(root, Path(args.comment_output), render_pr_comment(report) + "\n")
     if args.agent_instructions_output:
         write_artifact(root, Path(args.agent_instructions_output), render_agent_instructions(report) + "\n")
+    if args.attestation_output:
+        from ._attestation import render_attestation
+
+        write_artifact(root, Path(args.attestation_output), render_attestation(report))
     if args.hostile_prompt_output:
         write_artifact(root, Path(args.hostile_prompt_output),
                        render_hostile_audit_prompt(report) + "\n")

{maintainability_agent-2.2.0 → maintainability_agent-2.3.0}/src/maintainability_audit/config.py

@@ -11,7 +11,7 @@ from ._config_defaults import DEFAULT_CONFIG, DEFAULT_IDIOM_GROUPS
 # still the door every caller comes through.
 __all__ = ["DEFAULT_CONFIG", "DEFAULT_IDIOM_GROUPS", "PROJECT_URL", "VERSION"]
 
-VERSION = "2.2.0"
+VERSION = "2.3.0"
 
 PROJECT_URL = "https://github.com/marshallguillory86/maintainability-agent"
 

{maintainability_agent-2.2.0 → maintainability_agent-2.3.0}/src/maintainability_audit/prompts.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from typing import Any
 
 from . import _evidence_view as view
+from ._attestation import render_attestation  # noqa: F401
 from ._hostile_prompt import render_hostile_audit_prompt  # noqa: F401
 from ._hotspots import hotspot_measure, hotspot_name
 from ._tdd_view import tdd_sentences

maintainability_agent-2.3.0/tests/test_attestation.py

@@ -0,0 +1,151 @@
+"""The record an author cannot produce about their own work.
+
+The three mechanisms each answer one question about a change. This composes
+them into the artifact they were built for — and the value of that artifact
+is entirely in what it refuses to overstate, so that is what is tested here.
+
+Three properties, and all three are about honesty rather than plumbing:
+
+- **A mixed result reads as mixed.** A change that stayed in scope while
+  silencing a finding must not produce a document anyone could wave as a
+  pass.
+- **Not asked is not the same as passed.** A question nobody ran must not
+  render as a verdict.
+- **It claims reproducible, never signed.** Nothing here holds a key, and a
+  document that implied otherwise would be the exact overclaim the rest of
+  this project spends its time removing.
+"""
+
+from __future__ import annotations
+
+from maintainability_audit._attestation import attestation_record, render_attestation
+
+CLEAN = {
+    "tool_version": "2.3.0",
+    "git_commit": "a" * 40,
+    "git_branch": "main",
+    "git_status_short": "",
+    "score": {
+        "maintainability_estimate": 4.2,
+        "verified_grade": "B",
+        "evidence_status": {"status": "complete"},
+    },
+    "analyzer_coverage": {"by_outcome": {"ran": [{"tool": "lizard"}]}},
+    "hard_gate_failures": [],
+    "scope_conformance": {
+        "revspec": "main...HEAD", "conformant": True, "out_of_scope": [],
+        "suppressions_on_named_paths": 0, "clean": True,
+    },
+    "dimension_ratchet": {"comparable": True, "regressed": []},
+}
+
+
+def _with(**changes: object) -> dict:
+    report = {key: dict(value) if isinstance(value, dict) else value
+              for key, value in CLEAN.items()}
+    report.update(changes)
+    return report
+
+
+def test_a_clean_change_says_so_on_every_question() -> None:
+    text = render_attestation(CLEAN)
+
+    assert "**Stayed inside the work order:** yes" in text
+    assert "**Without silencing a finding:** yes" in text
+    assert "**No dimension regressed:** yes" in text
+
+
+def test_a_silenced_finding_is_not_hidden_by_staying_in_scope() -> None:
+    """The mixed verdict the artifact exists to make unmissable.
+
+    Scope and silence are separate questions, so a change that obeyed the
+    first and failed the second must not produce a document that reads as a
+    pass on either.
+    """
+    report = _with(scope_conformance={
+        "revspec": "main...HEAD", "conformant": True, "out_of_scope": [],
+        "suppressions_on_named_paths": 2, "clean": False,
+    })
+
+    text = render_attestation(report)
+
+    assert "**Stayed inside the work order:** yes" in text
+    assert "**Without silencing a finding:** no" in text
+    assert attestation_record(report)["no_finding_silenced"] is False
+
+
+def test_a_question_nobody_asked_is_not_reported_as_passed() -> None:
+    """`None`, not `True`. An unrun check is not a clean result."""
+    report = _with(scope_conformance=None, dimension_ratchet=None)
+
+    record = attestation_record(report)
+
+    assert record["stayed_in_scope"] is None
+    assert record["no_finding_silenced"] is None
+    assert record["no_dimension_regressed"] is None
+    assert "Nothing was asked" in render_attestation(report)
+
+
+def test_an_incomparable_ratchet_is_not_reported_as_no_regression() -> None:
+    """Two scans under different calibration cannot be differenced.
+
+    "Not established" is the honest rendering; "yes" would be a claim the
+    evidence cannot support.
+    """
+    report = _with(dimension_ratchet={
+        "comparable": False, "regressed": [],
+        "reason": "calibration changed, so scans cannot be joined",
+    })
+
+    text = render_attestation(report)
+
+    assert "not established" in text
+    assert attestation_record(report)["no_dimension_regressed"] is None
+
+
+def test_an_uncommitted_tree_is_disclosed() -> None:
+    """A verdict about "the commit" that depends on unstaged work is a lie."""
+    report = _with(git_status_short=" M src/thing.py")
+
+    assert attestation_record(report)["tree_dirty"] is True
+    assert "uncommitted changes present" in render_attestation(report)
+
+
+def test_the_document_claims_reproducible_and_refuses_to_claim_signed() -> None:
+    """Nothing here holds a key, and the artifact must not imply one.
+
+    "Signed" is the word a reader reaches for with an attestation, which is
+    exactly why the document has to say the opposite in its own text.
+    """
+    text = render_attestation(CLEAN)
+
+    assert "not signed" in text.lower()
+    assert "Digest:" in text
+
+
+def test_the_digest_is_reproducible_and_content_bound() -> None:
+    first = attestation_record(CLEAN)["digest"]
+    second = attestation_record(CLEAN)["digest"]
+    moved = attestation_record(_with(score={
+        "maintainability_estimate": 3.1, "verified_grade": "C",
+        "evidence_status": {"status": "complete"},
+    }))["digest"]
+
+    assert first == second, "the same inputs produced two different digests"
+    assert first != moved, "the digest did not follow the record's content"
+
+
+def test_the_record_carries_no_score_verdict_of_its_own() -> None:
+    """It reports the estimate the audit produced; it never computes one."""
+    record = attestation_record(CLEAN)
+
+    assert record["estimate"] == 4.2
+    assert "categories" not in record
+    assert "dimensions" not in record
+
+
+def test_the_document_states_that_it_never_opened_the_diff() -> None:
+    text = render_attestation(CLEAN)
+
+    assert "not** that the change to it was correct" in text
+    assert "touches no score" in text