maintainability-agent 2.4.0__tar.gz → 2.4.1__tar.gz

{maintainability_agent-2.4.0/src/maintainability_agent.egg-info → maintainability_agent-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.4.0
+Version: 2.4.1
 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.4.0**.
+Version **2.4.1**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -124,9 +124,12 @@ the independent check on their own work, so a platform that generates code and
 grades it is producing a self-assessment — a property of the arrangement, not a
 criticism of any one of them. This writes nothing and runs no model, which is
 what lets its verdict be evidence ([the principle](docs/philosophy.md#principles)).
-The limit, stated in the same breath: step 3 bounds the agent by **instruction**,
-and nothing yet verifies the returned diff stayed inside the work order
-([the three checks that would](docs/roadmap.md#the-remediation-hole-an-agent-can-satisfy-this-gate-without-doing-the-work)).
+Since 2.1.0 the work order is also **checked**: `--conformance` compares the
+returned diff against the paths the report named, `--fail-on-regression`
+ratchets the dimension scores, and `--attestation-output` composes them into one
+record ([how that hole was closed](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)).
+The limit, stated in the same breath: those checks read the diff's **shape**,
+never its correctness — whether the change works is not a claim this tool makes.
 
 One pre-registered experiment has tested the bounded prompt.
 Generic prompting made 2 of 6 repositories worse; bounded prompting made 1 of 6 worse and improved 5 of 6, under this tool's own finding count.
@@ -217,6 +220,41 @@ withheld estimate. For PR work, add `--changed-only main...HEAD` to audit the
 diff; on a change too small to support a rate, the estimate and grade are
 withheld and the scope is named as the reason.
 
+### Checking that the agent did the work
+
+The work order tells an agent to fix exactly these findings and refactor nothing
+else. These flags check that the diff that came back obeyed it — read the
+diff's _shape_, not its correctness:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --conformance main...HEAD \
+  --fail-on-out-of-scope \
+  --fail-on-regression \
+  --attestation-output maintainability-attestation.md
+```
+
+- **`--conformance <revspec>`** compares the diff against the paths the report
+  named, and answers two questions separately: did it **stay in scope**, and did
+  it **silence nothing**. They stay separate because a change can obey the work
+  order and still add a `# noqa` to a finding inside it. A test added for a fix
+  stays in scope even though the work order never named the test file.
+- **`--fail-on-out-of-scope`** turns that into a CI failure.
+- **`--fail-on-regression`** ratchets the _dimension_ scores against scan
+  history, catching a change that improves one dimension while silently
+  regressing another. It has three outcomes, not two — held, regressed, and
+  **not comparable**, because two scans taken under different calibration cannot
+  be differenced.
+- **`--attestation-output`** writes the three into one per-change record: what
+  was measured, what the agent was told to change, whether it stayed inside the
+  work order, and what moved. It is reproducible and **not signed** — nothing
+  here holds a key, and the document says so in its own text. A check nobody ran
+  renders as _not asked_, never as passed.
+
+The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
+has the history of why this was the hole under the product's central claim.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/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.4.0**.
+Version **2.4.1**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -85,9 +85,12 @@ the independent check on their own work, so a platform that generates code and
 grades it is producing a self-assessment — a property of the arrangement, not a
 criticism of any one of them. This writes nothing and runs no model, which is
 what lets its verdict be evidence ([the principle](docs/philosophy.md#principles)).
-The limit, stated in the same breath: step 3 bounds the agent by **instruction**,
-and nothing yet verifies the returned diff stayed inside the work order
-([the three checks that would](docs/roadmap.md#the-remediation-hole-an-agent-can-satisfy-this-gate-without-doing-the-work)).
+Since 2.1.0 the work order is also **checked**: `--conformance` compares the
+returned diff against the paths the report named, `--fail-on-regression`
+ratchets the dimension scores, and `--attestation-output` composes them into one
+record ([how that hole was closed](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)).
+The limit, stated in the same breath: those checks read the diff's **shape**,
+never its correctness — whether the change works is not a claim this tool makes.
 
 One pre-registered experiment has tested the bounded prompt.
 Generic prompting made 2 of 6 repositories worse; bounded prompting made 1 of 6 worse and improved 5 of 6, under this tool's own finding count.
@@ -178,6 +181,41 @@ withheld estimate. For PR work, add `--changed-only main...HEAD` to audit the
 diff; on a change too small to support a rate, the estimate and grade are
 withheld and the scope is named as the reason.
 
+### Checking that the agent did the work
+
+The work order tells an agent to fix exactly these findings and refactor nothing
+else. These flags check that the diff that came back obeyed it — read the
+diff's _shape_, not its correctness:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --conformance main...HEAD \
+  --fail-on-out-of-scope \
+  --fail-on-regression \
+  --attestation-output maintainability-attestation.md
+```
+
+- **`--conformance <revspec>`** compares the diff against the paths the report
+  named, and answers two questions separately: did it **stay in scope**, and did
+  it **silence nothing**. They stay separate because a change can obey the work
+  order and still add a `# noqa` to a finding inside it. A test added for a fix
+  stays in scope even though the work order never named the test file.
+- **`--fail-on-out-of-scope`** turns that into a CI failure.
+- **`--fail-on-regression`** ratchets the _dimension_ scores against scan
+  history, catching a change that improves one dimension while silently
+  regressing another. It has three outcomes, not two — held, regressed, and
+  **not comparable**, because two scans taken under different calibration cannot
+  be differenced.
+- **`--attestation-output`** writes the three into one per-change record: what
+  was measured, what the agent was told to change, whether it stayed inside the
+  work order, and what moved. It is reproducible and **not signed** — nothing
+  here holds a key, and the document says so in its own text. A check nobody ran
+  renders as _not asked_, never as passed.
+
+The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
+has the history of why this was the hole under the product's central claim.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.4.0
+Version: 2.4.1
 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.4.0**.
+Version **2.4.1**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -124,9 +124,12 @@ the independent check on their own work, so a platform that generates code and
 grades it is producing a self-assessment — a property of the arrangement, not a
 criticism of any one of them. This writes nothing and runs no model, which is
 what lets its verdict be evidence ([the principle](docs/philosophy.md#principles)).
-The limit, stated in the same breath: step 3 bounds the agent by **instruction**,
-and nothing yet verifies the returned diff stayed inside the work order
-([the three checks that would](docs/roadmap.md#the-remediation-hole-an-agent-can-satisfy-this-gate-without-doing-the-work)).
+Since 2.1.0 the work order is also **checked**: `--conformance` compares the
+returned diff against the paths the report named, `--fail-on-regression`
+ratchets the dimension scores, and `--attestation-output` composes them into one
+record ([how that hole was closed](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)).
+The limit, stated in the same breath: those checks read the diff's **shape**,
+never its correctness — whether the change works is not a claim this tool makes.
 
 One pre-registered experiment has tested the bounded prompt.
 Generic prompting made 2 of 6 repositories worse; bounded prompting made 1 of 6 worse and improved 5 of 6, under this tool's own finding count.
@@ -217,6 +220,41 @@ withheld estimate. For PR work, add `--changed-only main...HEAD` to audit the
 diff; on a change too small to support a rate, the estimate and grade are
 withheld and the scope is named as the reason.
 
+### Checking that the agent did the work
+
+The work order tells an agent to fix exactly these findings and refactor nothing
+else. These flags check that the diff that came back obeyed it — read the
+diff's _shape_, not its correctness:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --conformance main...HEAD \
+  --fail-on-out-of-scope \
+  --fail-on-regression \
+  --attestation-output maintainability-attestation.md
+```
+
+- **`--conformance <revspec>`** compares the diff against the paths the report
+  named, and answers two questions separately: did it **stay in scope**, and did
+  it **silence nothing**. They stay separate because a change can obey the work
+  order and still add a `# noqa` to a finding inside it. A test added for a fix
+  stays in scope even though the work order never named the test file.
+- **`--fail-on-out-of-scope`** turns that into a CI failure.
+- **`--fail-on-regression`** ratchets the _dimension_ scores against scan
+  history, catching a change that improves one dimension while silently
+  regressing another. It has three outcomes, not two — held, regressed, and
+  **not comparable**, because two scans taken under different calibration cannot
+  be differenced.
+- **`--attestation-output`** writes the three into one per-change record: what
+  was measured, what the agent was told to change, whether it stayed inside the
+  work order, and what moved. It is reproducible and **not signed** — nothing
+  here holds a key, and the document says so in its own text. A check nobody ran
+  renders as _not asked_, never as passed.
+
+The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
+has the history of why this was the hole under the product's central claim.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -290,6 +290,7 @@ tests/test_source_index.py
 tests/test_spotbugs_adapter.py
 tests/test_spotbugs_catalog.py
 tests/test_stage8_contract.py
+tests/test_suite_isolation.py
 tests/test_swift_declarations.py
 tests/test_tdd_structure.py
 tests/test_test_execution_class.py

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "2.4.0"
+__version__ = "2.4.1"

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/src/maintainability_audit/_config_defaults.py

@@ -45,6 +45,7 @@ DEFAULT_CONFIG: dict[str, Any] = {
             ".py", ".java", ".c", ".h",
             ".cpp", ".hpp", ".cc", ".cxx", ".hh",
             ".cs",
+            ".swift",
             ".f90", ".f95", ".f03", ".f08",
             ".F90", ".F95", ".F03", ".F08", ".pf",
             ".f", ".for", ".ftn", ".F", ".FOR", ".FTN",

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/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.4.0"
+VERSION = "2.4.1"
 
 PROJECT_URL = "https://github.com/marshallguillory86/maintainability-agent"
 

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/tests/test_claimed_languages.py

@@ -89,6 +89,24 @@ def test_every_scanned_source_suffix_can_be_read_by_something() -> None:
         "population would be a number nobody measured"
     )
 
+    # The other direction, which was missing and cost 2.4.0 its language.
+    # Swift shipped in `DECLARATION_SUFFIXES`, in `SCANNERS`, in the README
+    # table and in `language-support.md` — and not in the default
+    # `include_extensions`, so no `.swift` file was ever opened. The scanner
+    # was correct, tested, documented, and unreachable: an audit of a Swift
+    # repository found zero Swift files and withheld its rates, which is
+    # indistinguishable from not supporting the language at all.
+    #
+    # Caught by a corpus run reporting `vapor/vapor` as three files, not by
+    # any test, because every test that could have caught it exercised the
+    # scanner directly rather than through the configuration a user gets.
+    unopened = sorted(DECLARATION_SUFFIXES - included)
+    assert not unopened, (
+        f"{unopened} are parsed but absent from the default "
+        "include_extensions, so no such file is ever opened; the language "
+        "is claimed and unreachable"
+    )
+
 
 # One sample of real source per claimed language, by suffix. This was a
 # chain of nested conditionals until 1.4.0, when the fifth language took

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/tests/test_mcp_server.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import asyncio
 import json
-import os
 import subprocess
 import sys
 from pathlib import Path
@@ -159,12 +158,15 @@ def test_a_client_sees_the_two_tools_and_can_call_one(tmp_path: Path) -> None:
 def _child_import_path() -> str:
     """This process's own import path, for the child to inherit.
 
-    Derived from `sys.path` rather than assumed, so the subprocess
-    imports exactly what the test process is exercising: the package
-    under test (from `src/` in a checkout, site-packages when installed)
-    *and* the `mcp` SDK it needs to answer at all.
+    The MCP SDK spawns with a scrubbed environment rather than an
+    inherited one, so this seam needs the value passed explicitly even
+    though `conftest` now puts it in `os.environ` for every other child.
+    It is the same value, from the same place, for the same reason —
+    `conftest.child_import_path` carries the full account.
     """
-    return os.pathsep.join(entry for entry in sys.path if entry)
+    from conftest import child_import_path
+
+    return child_import_path()
 
 
 def test_real_stdio_process_initializes_and_reports_its_boundary(tmp_path: Path) -> None:

{maintainability_agent-2.4.0 → maintainability_agent-2.4.1}/tests/test_population_floors.py

@@ -44,6 +44,36 @@ pytestmark = pytest.mark.usefixtures("real_population_floors")
 CORPUS = Path(__file__).resolve().parent.parent / "tools" / "calibration" / "corpus.json"
 
 
+def test_the_shipped_floors_are_the_corpus_minima() -> None:
+    """The suite lifts the floors; this pins what it lifted.
+
+    Without it, a floor could be raised above a calibration member's
+    population and no test would notice, because every other test runs
+    with the floors disabled.
+
+    It lived in `conftest.py` and was therefore never collected — pytest
+    loads a conftest as a plugin, not as a test module — so for as long as
+    it existed it asserted nothing. It is compared against
+    `conftest.SHIPPED_FLOORS`, captured at import before any fixture
+    touches the table, rather than against the live module attribute this
+    file's own `real_population_floors` fixture restores.
+
+    Covers existing behaviour: the floors and the corpus it checks them
+    against are both older than this change, which only moves the
+    assertion somewhere pytest will run it. It cannot fail at the base
+    for the plainest possible reason — at the base it is not collected,
+    so there is nothing there to fail.
+    """
+    from conftest import SHIPPED_FLOORS
+
+    repos = json.loads(CORPUS.read_text(encoding="utf-8"))["repos"]
+    assert SHIPPED_FLOORS["files_scanned"] <= min(r["source_files"] for r in repos)
+    assert SHIPPED_FLOORS["declarations_scanned"] <= min(r["declarations"] for r in repos)
+    assert all(value > 0 for value in SHIPPED_FLOORS.values()), (
+        "a zero floor ships nothing; the hello-world A+ comes straight back"
+    )
+
+
 def _repo(tmp_path: Path, files: int, decls_per_file: int = 1) -> Path:
     root = tmp_path / "r"
     root.mkdir(parents=True)

maintainability_agent-2.4.1/tests/test_suite_isolation.py

@@ -0,0 +1,139 @@
+"""The suite's own isolation, tested where the tests actually run.
+
+Every assertion here is about the harness rather than the product: that a
+fixture repository cannot read the developer's git configuration, and that
+a spawned subprocess imports the same package this process did. Both are
+properties of `conftest.py`, and both were *written* in `conftest.py` —
+where pytest never collected them, because a conftest is a plugin module
+and not a test module. `python_files` defaults to `test_*.py` and
+`*_test.py`; `conftest.py` matches neither.
+
+So the guard for the git-isolation fixture, with its careful docstring
+about how the first attempt at that fix had been too narrow, had never
+run once. It is the failure mode this project keeps meeting in new
+costumes — a check narrower than the promise, a guard that reads one
+direction, an assertion nothing executes — and the cheapest of the three
+to miss, because a test that is never collected cannot go red.
+
+`test_the_isolation_guards_are_collected` below is the guard on the
+guards: it fails if these move back somewhere pytest will not look.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+DEVELOPER_HOME = Path(os.path.expanduser("~")).resolve()
+"""Captured at import, which is before the session fixture moves `HOME`.
+
+Reading it later would return the fixture's temporary home and the leak
+check below would compare against the wrong string — passing always, which
+is the same defect as not being collected.
+"""
+
+
+def test_no_git_in_this_suite_reads_developer_configuration(tmp_path: Path) -> None:
+    """The isolation holds, for any setting rather than a listed few.
+
+    Asserting on the *origin* of every setting is what makes this a guard
+    against the class. A test that only checked `commit.gpgsign` would pass
+    while `init.templateDir` was still installing hooks — which is precisely
+    how the first attempt at that fix was wrong.
+    """
+    repo = tmp_path / "probe"
+    repo.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+
+    origins = subprocess.run(
+        ["git", "config", "--list", "--show-origin"],
+        cwd=repo, text=True, capture_output=True, check=True,
+    ).stdout
+    leaked = [line for line in origins.splitlines() if str(DEVELOPER_HOME) in line]
+    assert not leaked, f"developer configuration reached a fixture git: {leaked}"
+
+    hooks = repo / ".git" / "hooks"
+    installed = [entry.name for entry in hooks.iterdir() if entry.suffix != ".sample"]
+    assert not installed, (
+        f"init.templateDir installed hooks into a fixture repository: {installed}"
+    )
+
+    # Not "unset": `_git_never_maintains_the_fixtures` sets these to false
+    # unconditionally. The requirement is that a fixture never *tries* to
+    # sign, whichever layer delivers that.
+    for setting in ("commit.gpgsign", "tag.gpgsign"):
+        value = subprocess.run(
+            ["git", "config", "--get", setting],
+            cwd=repo, text=True, capture_output=True, check=False,
+        ).stdout.strip()
+        assert value in ("", "false"), (
+            f"a fixture repository would attempt to sign: {setting}={value}"
+        )
+
+
+def test_a_spawned_child_imports_the_same_package_this_process_did() -> None:
+    """Parent and child agree on which copy is under test.
+
+    The suite makes assertions about CLI behaviour by spawning
+    `python -m maintainability_audit`. Those assertions are only about this
+    working tree if the child resolves the same package the test process
+    imported, and for a while nothing checked that:
+
+    - Where the package is installed with `pip install --user`, the `HOME`
+      move in `conftest` deleted the child's route to it entirely. Tests
+      failed with `No module named maintainability_audit` — a message that
+      names imports, in tests whose subject is not imports, on a laptop
+      while CI stayed green because a virtualenv's site-packages is not
+      `HOME`-derived.
+    - The quieter half is that a child could instead have found a
+      *different* copy — a stale wheel, an older `pip install` — and
+      passed. Every subprocess assertion would then have described a build
+      the rest of the suite never measured.
+
+    Comparing the resolved file rather than the version catches both: two
+    copies of the same version are still two copies.
+    """
+    child = subprocess.run(
+        [sys.executable, "-c",
+         "import maintainability_audit as m; print(m.__file__)"],
+        text=True, capture_output=True, check=False,
+    )
+
+    assert child.returncode == 0, (
+        "a spawned child could not import the package under test:\n"
+        f"{child.stderr}"
+    )
+
+    import maintainability_audit
+
+    assert Path(child.stdout.strip()) == Path(maintainability_audit.__file__), (
+        "a spawned subprocess imported a different copy of the package than "
+        f"this test process: child {child.stdout.strip()!r}, parent "
+        f"{maintainability_audit.__file__!r}"
+    )
+
+
+def test_the_isolation_guards_are_collected() -> None:
+    """No isolation guard may live where pytest does not collect it.
+
+    The guard on the guards, and the reason this file exists. Both tests
+    above sat in `conftest.py` and never ran; the suite was green for
+    months with its own harness unverified. Asserting that `conftest.py`
+    defines no `test_`-prefixed function encodes the rule rather than the
+    instance, so the next one written in the convenient place fails loudly
+    instead of silently never running.
+    """
+    conftest = Path(__file__).with_name("conftest.py").read_text()
+    stranded = [
+        line.split("(")[0].removeprefix("def ").strip()
+        for line in conftest.splitlines()
+        if line.startswith("def test_")
+    ]
+
+    assert not stranded, (
+        f"{stranded} are defined in conftest.py, which pytest loads as a "
+        "plugin and never collects as a test module, so they cannot fail. "
+        "Move them into a test_*.py file."
+    )