maintainability-agent 4.4.0__tar.gz → 4.4.1__tar.gz

{maintainability_agent-4.4.0/src/maintainability_agent.egg-info → maintainability_agent-4.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.4.0
+Version: 4.4.1
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: mcp<3,>=2; extra == "dev"
 Requires-Dist: PyYAML>=6; extra == "dev"
 Requires-Dist: setuptools>=70; extra == "dev"
 Requires-Dist: lizard>=1.17; extra == "dev"
-Requires-Dist: markdown>=3.5; extra == "dev"
+Requires-Dist: markdown==3.11.1; extra == "dev"
 Dynamic: license-file
 
 # Maintainability Agent
@@ -47,7 +47,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 **4.4.0**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -512,7 +512,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.0
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.0 → maintainability_agent-4.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 **4.4.0**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -470,7 +470,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.0
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/pyproject.toml

@@ -63,7 +63,10 @@ mcp = ["mcp>=2,<3"]
 # ships imports it, and the oracle exists so a measurement can be
 # checked against something other than its author. `markdown` renders the
 # docs/html reading copy (`tools/render_docs.py`); the product never does.
-dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3.6", "jsonschema>=4", "ruff>=0.5", "pip-audit>=2.7", "mcp>=2,<3", "PyYAML>=6", "setuptools>=70", "lizard>=1.17", "markdown>=3.5"]
+# It is pinned exactly: the committed copy is checked against a fresh render,
+# and markdown 3.11 rendered two pages differently from 3.10, so an unpinned
+# release failed CI on files nobody had touched (2026-10-14).
+dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3.6", "jsonschema>=4", "ruff>=0.5", "pip-audit>=2.7", "mcp>=2,<3", "PyYAML>=6", "setuptools>=70", "lizard>=1.17", "markdown==3.11.1"]
 
 [tool.pydocstyle]
 # D401 ("First line should be in imperative mood") is switched off, and the

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.4.0
+Version: 4.4.1
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: mcp<3,>=2; extra == "dev"
 Requires-Dist: PyYAML>=6; extra == "dev"
 Requires-Dist: setuptools>=70; extra == "dev"
 Requires-Dist: lizard>=1.17; extra == "dev"
-Requires-Dist: markdown>=3.5; extra == "dev"
+Requires-Dist: markdown==3.11.1; extra == "dev"
 Dynamic: license-file
 
 # Maintainability Agent
@@ -47,7 +47,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 **4.4.0**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -512,7 +512,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.0
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -182,6 +182,7 @@ tests/test_analyzer_scoring_path.py
 tests/test_analyzer_spread_range.py
 tests/test_analyzer_xml_bounds.py
 tests/test_analyzers_against_the_real_tools.py
+tests/test_analyzers_never_write.py
 tests/test_analyzers_report_what_actually_failed.py
 tests/test_anchor_and_mode.py
 tests/test_anchor_caveat_and_counts_follow_the_run.py

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_agent.egg-info/requires.txt

@@ -10,7 +10,7 @@ mcp<3,>=2
 PyYAML>=6
 setuptools>=70
 lizard>=1.17
-markdown>=3.5
+markdown==3.11.1
 
 [mcp]
 mcp<3,>=2

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "4.4.0"
+__version__ = "4.4.1"

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_audit/_analysis.py

@@ -19,6 +19,7 @@ clean result.
 
 from __future__ import annotations
 
+import hashlib
 from collections.abc import Sequence
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -40,6 +41,7 @@ from ._metrics_types import KNOWN_SOURCE_SUFFIXES, Finding, Measurement
 from ._runner import Outcome, Probe, ToolResult, run
 from ._selection import Selected, select_runnable
 from .config import acquisition_permitted
+from .git_tools import GitCommandFailed, probe_git, run_git
 
 #: Sources outside this package: an analyzer it ran, or a file the
 #: developer's own pipeline wrote (Decision 17). Built-ins are not here.
@@ -356,6 +358,43 @@ def analyze(root: Path, config: dict[str, Any], probe: Probe | None = None) -> A
     return analysis
 
 
+class RepositoryModifiedError(Exception):
+    """An analyzer changed the repository it was auditing.
+
+    The audit never edits source. A tool that writes to the audited tree
+    (ruff honouring a repository's `fix = true` rewrote 102 files of
+    an audited repository on 2026-10-14) fails the audit loudly rather than handing back
+    a grade for code that is no longer what was audited.
+    """
+
+
+def _tracked_state(root: Path) -> dict[str, str] | None:
+    """Each tracked file that differs from HEAD, by a hash of its diff.
+
+    None when `root` is not a git work tree: there is nothing to compare
+    against, so nothing is claimed.
+    """
+    if not probe_git(["rev-parse", "--is-inside-work-tree"], root):
+        return None
+    try:
+        diff = run_git(["diff", "HEAD", "--no-ext-diff", "--binary"], root, strip=False)
+    except GitCommandFailed:
+        return None
+    state: dict[str, str] = {}
+    for block in diff.split("\ndiff --git "):
+        if not block.strip():
+            continue
+        header = block.split("\n", 1)[0].removeprefix("diff --git ")
+        name = header.split(" b/", 1)[-1]
+        state[name] = hashlib.sha256(block.encode("utf-8", "replace")).hexdigest()
+    return state
+
+
+def _changed_paths(before: dict[str, str], after: dict[str, str]) -> list[str]:
+    return sorted(path for path in set(before) | set(after)
+                  if before.get(path) != after.get(path))
+
+
 def _run_one(root: Path, adapter: Any, probe: Probe, timeout: int,
              analysis: Analysis, excludes: Sequence[str] = (),
              inventory: Any = None) -> ToolCoverage:
@@ -371,6 +410,9 @@ def _run_one(root: Path, adapter: Any, probe: Probe, timeout: int,
     """
     try:
         return _attempt(root, adapter, probe, timeout, analysis, excludes, inventory)
+    except RepositoryModifiedError:
+        # Not an adapter defect to record quietly: the audited tree changed.
+        raise
     except Exception as error:  # noqa: BLE001 - the backstop is the point
         return ToolCoverage(
             slug=adapter.slug, outcome="failed", concepts=tuple(adapter.concepts),
@@ -494,12 +536,19 @@ def _run_batches(adapter: Any, root: Path, excludes: Sequence[str],
     invocations = planned(root, excludes) if planned else [adapter.invocation(root, excludes=excludes)]
     results: list[ToolResult] = []
     parsed: list[Extraction] = []
+    before = _tracked_state(root)
     for invocation in invocations:
         result = run(adapter.slug, invocation, timeout_seconds=timeout)
         results.append(result)
         parsed.append(adapter.parse(result))
         if not result.usable:
             break
+    after = _tracked_state(root) if before is not None else None
+    if before is not None and after is not None and after != before:
+        changed = _changed_paths(before, after)
+        raise RepositoryModifiedError(
+            f"{adapter.slug} modified the audited repository: {', '.join(changed)}. "
+            "The audit never edits source; restore these files and report the adapter.")
     if len(results) == 1:
         return results[0], parsed[0]
     return _merged_result(results, len(invocations)), _merged_extraction(parsed)

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_audit/_mcp_refusals.py

@@ -18,6 +18,7 @@ D48.
 
 from __future__ import annotations
 
+from ._analysis import RepositoryModifiedError
 from ._catalog import PolicyError
 from ._mcp_audit import InvalidAuditArgument, PathNotAllowed
 from ._mcp_setup import SetupRequired
@@ -37,6 +38,11 @@ ANTICIPATED_REFUSALS = (
     # type and `PathNotAllowed` both derive from it alongside the
     # internal ones that must stay crashes.
     ConfigUnreadable,
+    # An analyzer changed the audited repository. The message names the
+    # changed files and says to report the adapter: actionable, and a
+    # grade must never be returned for code that is no longer what was
+    # audited.
+    RepositoryModifiedError,
 )
 
 __all__ = ["ANTICIPATED_REFUSALS"]

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/src/maintainability_audit/_verdict_adapters.py

@@ -117,7 +117,9 @@ class RuffAdapter(BaseAdapter):
             concepts=("style", "complexity", "dead-code"),
             findings_exit_codes=(0, 1), exclude_flag="--exclude",
             exclude_dialect="gitignore",
-            extra_args=("check", "--output-format", "json", "--no-cache"),
+            # --no-fix: a repository's `fix = true` must never turn an audit
+            # into a rewrite (it rewrote 102 files of an audited repository, 2026-10-14).
+            extra_args=("check", "--no-fix", "--output-format", "json", "--no-cache"),
         )
 
     def _read(self, result: ToolResult) -> Extraction:
@@ -169,7 +171,7 @@ class FortitudeAdapter(BaseAdapter):
             concepts=("style", "dead-code"),
             findings_exit_codes=(0, 1), exclude_flag="--exclude",
             exclude_dialect="fnmatch",
-            extra_args=("check", "--output-format", "json"),
+            extra_args=("check", "--no-fix", "--output-format", "json"),
         )
 
     def _read(self, result: ToolResult) -> Extraction:

{maintainability_agent-4.4.0 → maintainability_agent-4.4.1}/tests/test_adapters.py

@@ -17,10 +17,12 @@ A+ one more time.
 from __future__ import annotations
 
 import json
+import subprocess
 from pathlib import Path
 
 import pytest
 
+from maintainability_audit import _analysis
 from maintainability_audit._adapters import BaseAdapter, Extraction, measurements_only
 from maintainability_audit._metrics_types import Measurement
 from maintainability_audit._runner import Outcome, ToolResult
@@ -489,3 +491,55 @@ def test_jscpd_paths_drop_the_embedded_format_tag() -> None:
 
     paths = [f.path for f in adapter.parse(result).findings]
     assert paths == ["docs/api/formik.md", "src/a.ts", "pkgs/v1.2/b.js"]
+
+
+# --- Guards for D229 (an analyzer can never rewrite the audited repository) --
+# Regression guards, not falsifiers: they pass on the code before the fix too,
+# so they live here rather than in the falsifier file D229 cites.
+
+_WRITE_TOKENS = ("--fix", "--write", "--in-place", "-i", "--apply", "--fix-only", "--unsafe-fixes")
+
+
+def _write_guard_argvs(slug, root):
+    names = ("mod.py", "Main.java", "main.f90", "app.js", "lib.c", "x.go", "y.rs", "z.ts")
+    for name in names:
+        (root / name).write_text("x\n", encoding="utf-8")
+    adapter = ADAPTERS[slug]()
+    runs = list(adapter.invocations(root, ()))
+    runs.append(adapter.invocation(root, [str(root / name) for name in names]))
+    return [tuple(run.argv) for run in runs]
+
+
+@pytest.mark.parametrize("slug", sorted(ADAPTERS))
+def test_no_adapter_is_built_to_write(slug, tmp_path):
+    """Covers existing behaviour: no adapter has ever passed a write-enabling flag; D229's
+    rewrite came from repository config, and this keeps a future adapter from adding one."""
+    adapter = ADAPTERS[slug]()
+    for argv in _write_guard_argvs(slug, tmp_path):
+        found = [token for token in argv if token in _WRITE_TOKENS]
+        assert not found, f"{slug} argv carries write-enabling {found}: {argv}"
+    assert not adapter.extra_args or adapter.extra_args[0] != "format", (
+        f"{slug} runs a formatter, which rewrites files")
+
+
+class _QuietProbe(BaseAdapter):
+    def __init__(self):
+        super().__init__(slug="fake", emits="verdict", executable="fake", concepts=("style",))
+
+    def _read(self, result):  # pragma: no cover - parse is not the subject
+        return Extraction()
+
+
+def test_an_analyzer_that_changes_nothing_reports_no_integrity_failure(tmp_path, monkeypatch):
+    """Covers existing behaviour: a clean run raised nothing before D229 either; this holds
+    that the integrity check never turns an unchanged tree into a failure."""
+    for args in (("init", "-q"), ("config", "user.email", "t@example.com"), ("config", "user.name", "t")):
+        subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True)
+    (tmp_path / "mod.py").write_text("import os\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True, capture_output=True)
+    subprocess.run(["git", "commit", "-q", "-m", "init"], cwd=tmp_path, check=True, capture_output=True)
+    monkeypatch.setattr(_analysis, "run",
+                        lambda slug, invocation, **kw: ToolResult(slug=slug, outcome=Outcome.RAN,
+                                                                   stdout="[]", exit_code=0))
+    result, _parsed = _analysis._run_batches(_QuietProbe(), tmp_path, (), 60)
+    assert result.outcome == Outcome.RAN

maintainability_agent-4.4.1/tests/test_analyzers_never_write.py

@@ -0,0 +1,128 @@
+"""Written by the Claude Sonnet test seat (Codex at its usage limit); Codex reviews.
+
+Defect: an analyzer rewrote the audited repository (2026-10-14).
+
+MA's contract is that it never edits source. The ruff adapter ran
+`ruff check` in the audited repository, ruff honoured that repository's own
+`fix = true`, and 102 files were rewritten. Three layers are specified:
+
+1. the ruff and fortitude argv carry `--no-fix`;
+2. no registered adapter's argv carries a write-enabling token (the bug
+   class, swept over the registry so a new adapter is covered);
+3. the structural block: if a tracked file of the audited git repository
+   changes while an analyzer runs, the audit raises `RepositoryModifiedError`
+   from `_analysis._run_batches` (the function that runs an adapter's
+   invocations) naming the changed path, instead of succeeding quietly;
+4. end to end with the real ruff.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from maintainability_audit import _analysis, _runner
+from maintainability_audit._adapters import BaseAdapter
+from maintainability_audit._runner import Outcome, ToolResult
+from maintainability_audit._tool_adapters import ADAPTERS
+
+WRITE_TOKENS = ("--fix", "--write", "--in-place", "-i", "--apply", "--fix-only", "--unsafe-fixes")
+
+
+def _tree(root: Path) -> list[str]:
+    """A few files of several kinds, so file-list adapters have targets."""
+    names = ("mod.py", "Main.java", "main.f90", "app.js", "lib.c", "x.go", "y.rs", "z.ts")
+    for name in names:
+        (root / name).write_text("x\n", encoding="utf-8")
+    return [str(root / name) for name in names]
+
+
+def _argvs(slug: str, root: Path) -> list[tuple[str, ...]]:
+    adapter = ADAPTERS[slug]()
+    files = _tree(root)
+    runs = list(adapter.invocations(root, ()))
+    runs.append(adapter.invocation(root, files))
+    return [tuple(run.argv) for run in runs]
+
+
+@pytest.mark.parametrize("slug", ["ruff", "fortitude"])
+def test_the_linters_that_can_fix_are_told_not_to(slug: str, tmp_path: Path) -> None:
+    for argv in _argvs(slug, tmp_path):
+        assert "--no-fix" in argv, f"{slug} may rewrite the audited repository: {argv}"
+
+
+# --- the structural block -------------------------------------------------
+
+
+def _git(root: Path, *args: str) -> None:
+    subprocess.run(["git", *args], cwd=root, check=True, capture_output=True)
+
+
+def _repo(root: Path) -> Path:
+    _git(root, "init", "-q")
+    _git(root, "config", "user.email", "t@example.com")
+    _git(root, "config", "user.name", "t")
+    (root / "mod.py").write_text("import os\n", encoding="utf-8")
+    (root / "other.py").write_text("y = 1\n", encoding="utf-8")
+    _git(root, "add", ".")
+    _git(root, "commit", "-q", "-m", "init")
+    return root
+
+
+class _Probe(BaseAdapter):
+    def __init__(self) -> None:
+        super().__init__(slug="fake", emits="verdict", executable="fake", concepts=("style",))
+
+    def _read(self, result: ToolResult):  # pragma: no cover - parse is not the subject
+        from maintainability_audit._adapters import Extraction
+        return Extraction()
+
+
+def _fake_run(monkeypatch: pytest.MonkeyPatch, effect) -> None:
+    def fake(slug, invocation, **kwargs):
+        effect()
+        return ToolResult(slug=slug, outcome=Outcome.RAN, stdout="[]", exit_code=0)
+
+    monkeypatch.setattr(_analysis, "run", fake)
+
+
+def test_an_analyzer_that_edits_a_tracked_file_is_an_integrity_failure(
+        tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    root = _repo(tmp_path)
+    _fake_run(monkeypatch, lambda: (root / "mod.py").write_text("", encoding="utf-8"))
+
+    with pytest.raises(_analysis.RepositoryModifiedError) as raised:
+        _analysis._run_batches(_Probe(), root, (), 60)
+
+    assert "mod.py" in str(raised.value)
+    assert "other.py" not in str(raised.value)
+
+
+# --- end to end with the real tool ----------------------------------------
+
+
+@pytest.mark.skipif(_runner.locate("ruff") is None, reason="ruff is not installed here")
+def test_real_ruff_with_fix_true_leaves_the_audited_repository_untouched(
+        tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    root = tmp_path
+    # ruff reads `fix` from the config found from its working directory, not
+    # from the audited file's directory, so the defect only shows when the
+    # audit runs from inside the repository (the CLI's case, and the incident's).
+    monkeypatch.chdir(root)
+    (root / "ruff.toml").write_text('fix = true\n[lint]\nselect = ["F"]\n', encoding="utf-8")
+    (root / "mod.py").write_text("import os\n", encoding="utf-8")
+    _git(root, "init", "-q")
+    _git(root, "config", "user.email", "t@example.com")
+    _git(root, "config", "user.name", "t")
+    _git(root, "add", ".")
+    _git(root, "commit", "-q", "-m", "init")
+    before = (root / "mod.py").read_bytes()
+
+    _analysis._run_batches(ADAPTERS["ruff"](), root, (), 60)
+
+    assert (root / "mod.py").read_bytes() == before
+    status = subprocess.run(["git", "status", "--porcelain"], cwd=root, check=True,
+                            capture_output=True, text=True).stdout
+    assert status == ""