maintainability-agent 4.1.0__tar.gz → 4.2.0__tar.gz

{maintainability_agent-4.1.0/src/maintainability_agent.egg-info → maintainability_agent-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.1.0
+Version: 4.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -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.1.0**.
+Version **4.2.0**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -56,6 +56,11 @@ Version **4.1.0**.
 > taste, each pinned to the exact commit it was measured at, so anyone can
 > re-run the calibration and get the same numbers. The median of that corpus
 > scores a **B**. [How the corpus is chosen and measured](docs/standard.md#the-reference-corpus).
+>
+> So your grade places your code against those 201: a **B** means you are at
+> the median of mature, widely used open source. The corpus is re-measured
+> whenever the instrument changes — in 4.1.0 every file of even the largest
+> repositories was read, and the scale came back unchanged to four decimals.
 
 **Languages parsed:** Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Ruby,
 Swift, Shell, COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each
@@ -93,7 +98,10 @@ you what it could not measure.
 **Install secure-code-agent for the security pillar.** Every audit runs it; it is
 installed alongside rather than as a dependency, so the two tools release
 independently. Without it the report says the security pillar was not measured
-and gives this command. Its scanners decide what it can grade — see
+and gives this command. A full security run can take several minutes on a
+large repository; the audit waits up to 15 minutes for it, and
+`security.timeout_seconds` in `maintainability-agent.json` changes that. Its
+scanners decide what it can grade — see
 [machine setup](docs/machine-setup.md#3-toolchain) for which to install, and
 don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
 
@@ -356,6 +364,11 @@ signals on:
 - an ISO/IEC 25010-inspired 0–5 estimate per category, and a verified grade —
   or a disclosed withholding when the evidence is thin.
 
+**Large repositories are measured whole.** Every file is handed to the
+analyzers, split across as many runs as the command line needs, so a big
+codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
+1,543 that fitted on one command line before 4.1.0.
+
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
@@ -496,7 +509,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.1.0
+- uses: marshallguillory86/maintainability-agent@v4.2.0
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.1.0 → maintainability_agent-4.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 **4.1.0**.
+Version **4.2.0**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -14,6 +14,11 @@ Version **4.1.0**.
 > taste, each pinned to the exact commit it was measured at, so anyone can
 > re-run the calibration and get the same numbers. The median of that corpus
 > scores a **B**. [How the corpus is chosen and measured](docs/standard.md#the-reference-corpus).
+>
+> So your grade places your code against those 201: a **B** means you are at
+> the median of mature, widely used open source. The corpus is re-measured
+> whenever the instrument changes — in 4.1.0 every file of even the largest
+> repositories was read, and the scale came back unchanged to four decimals.
 
 **Languages parsed:** Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Ruby,
 Swift, Shell, COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each
@@ -51,7 +56,10 @@ you what it could not measure.
 **Install secure-code-agent for the security pillar.** Every audit runs it; it is
 installed alongside rather than as a dependency, so the two tools release
 independently. Without it the report says the security pillar was not measured
-and gives this command. Its scanners decide what it can grade — see
+and gives this command. A full security run can take several minutes on a
+large repository; the audit waits up to 15 minutes for it, and
+`security.timeout_seconds` in `maintainability-agent.json` changes that. Its
+scanners decide what it can grade — see
 [machine setup](docs/machine-setup.md#3-toolchain) for which to install, and
 don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
 
@@ -314,6 +322,11 @@ signals on:
 - an ISO/IEC 25010-inspired 0–5 estimate per category, and a verified grade —
   or a disclosed withholding when the evidence is thin.
 
+**Large repositories are measured whole.** Every file is handed to the
+analyzers, split across as many runs as the command line needs, so a big
+codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
+1,543 that fitted on one command line before 4.1.0.
+
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
@@ -454,7 +467,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.1.0
+- uses: marshallguillory86/maintainability-agent@v4.2.0
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.1.0
+Version: 4.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -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.1.0**.
+Version **4.2.0**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -56,6 +56,11 @@ Version **4.1.0**.
 > taste, each pinned to the exact commit it was measured at, so anyone can
 > re-run the calibration and get the same numbers. The median of that corpus
 > scores a **B**. [How the corpus is chosen and measured](docs/standard.md#the-reference-corpus).
+>
+> So your grade places your code against those 201: a **B** means you are at
+> the median of mature, widely used open source. The corpus is re-measured
+> whenever the instrument changes — in 4.1.0 every file of even the largest
+> repositories was read, and the scale came back unchanged to four decimals.
 
 **Languages parsed:** Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Ruby,
 Swift, Shell, COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each
@@ -93,7 +98,10 @@ you what it could not measure.
 **Install secure-code-agent for the security pillar.** Every audit runs it; it is
 installed alongside rather than as a dependency, so the two tools release
 independently. Without it the report says the security pillar was not measured
-and gives this command. Its scanners decide what it can grade — see
+and gives this command. A full security run can take several minutes on a
+large repository; the audit waits up to 15 minutes for it, and
+`security.timeout_seconds` in `maintainability-agent.json` changes that. Its
+scanners decide what it can grade — see
 [machine setup](docs/machine-setup.md#3-toolchain) for which to install, and
 don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
 
@@ -356,6 +364,11 @@ signals on:
 - an ISO/IEC 25010-inspired 0–5 estimate per category, and a verified grade —
   or a disclosed withholding when the evidence is thin.
 
+**Large repositories are measured whole.** Every file is handed to the
+analyzers, split across as many runs as the command line needs, so a big
+codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
+1,543 that fitted on one command line before 4.1.0.
+
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
@@ -496,7 +509,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.1.0
+- uses: marshallguillory86/maintainability-agent@v4.2.0
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -157,6 +157,7 @@ tests/test_a_dangling_source_link_is_named_not_fatal.py
 tests/test_a_format_override_is_disclosed.py
 tests/test_a_matching_format_stays_silent.py
 tests/test_a_published_question_offers_what_it_accepts.py
+tests/test_a_rendered_docs_site_is_not_scored_as_source.py
 tests/test_a_setup_question_keeps_its_contract.py
 tests/test_acquisition_trust.py
 tests/test_adapter_docs.py
@@ -276,6 +277,7 @@ tests/test_evidence_invariants.py
 tests/test_evidence_normalization.py
 tests/test_evidence_properties.py
 tests/test_example_config_opens_claimed_languages.py
+tests/test_exclude_additional_keeps_the_defaults.py
 tests/test_exclusion_dialects.py
 tests/test_exposure_never_outranks_band.py
 tests/test_falsifier_standard.py
@@ -367,6 +369,7 @@ tests/test_python_declarations.py
 tests/test_read_boundary.py
 tests/test_readme_claims.py
 tests/test_recurrence.py
+tests/test_regular_file_reads_work_without_o_nonblock.py
 tests/test_release_needs_an_empty_ledger.py
 tests/test_release_plan.py
 tests/test_release_plan_status.py

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "4.1.0"
+__version__ = "4.2.0"

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0}/src/maintainability_audit/_operator_reads.py

@@ -55,7 +55,9 @@ def open_regular_file(path: Path, why: str) -> int:
     """
     import stat as stat_module
 
-    handle = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+    # Windows has no `O_NONBLOCK` and no POSIX FIFO in the tree to guard
+    # against; using the flag unconditionally killed every read there.
+    handle = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
     if not stat_module.S_ISREG(os.fstat(handle).st_mode):
         os.close(handle)
         raise PathNotAllowed(f"{path} is not a regular file. {why}")

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0}/src/maintainability_audit/config.py

@@ -161,12 +161,29 @@ def load_config(path: str | None) -> dict[str, Any]:
         return config
     config["analyzers"]["run"] = True
     if user_tier is not None:
-        deep_update(config, user_tier)
+        _merge_tier(config, user_tier)
     if path:
-        deep_update(config, _host_authority_stripped(_configured(Path(path))))
+        _merge_tier(config, _host_authority_stripped(_configured(Path(path))))
     return config
 
 
+def _merge_tier(config: dict[str, Any], tier: dict[str, Any]) -> None:
+    """One tier over the ones before it, with `exclude_additional` appended.
+
+    `deep_update` replaces lists, so setting `paths.exclude_patterns` to add
+    one directory discarded every default exclusion and froze a copy that
+    drifts on the next release (#292). `exclude_additional` adds to whatever
+    the earlier tiers produced instead, so a repository can add without
+    restating.
+    """
+    added = list((tier.get("paths") or {}).get("exclude_additional") or [])
+    deep_update(config, tier)
+    paths = config["paths"]
+    paths.pop("exclude_additional", None)
+    paths["exclude_patterns"] = [*paths["exclude_patterns"],
+                                 *(p for p in added if p not in paths["exclude_patterns"])]
+
+
 #: The one key a repository may state and this tool will not act on,
 #: because acting on it runs a program of the tree's choosing on the host.
 #: The whole leaf is dropped, not merged.

maintainability_agent-4.2.0/tests/test_a_rendered_docs_site_is_not_scored_as_source.py

@@ -0,0 +1,61 @@
+"""A committed docs site rendered from Markdown is not scored as source (#292).
+
+Every repository now commits an HTML site rendered from its Markdown, and
+the audit scored it as source: each page duplicated its Markdown, so
+duplicate blocks doubled; a debt marker in `README.md` was reported again in
+`docs/html/readme.html`, where editing it is forbidden and re-rendering
+reproduces it; and a long page drew "split along a real boundary" advice
+with nobody to take it. secure-code-agent measured it: files 160 → 195,
+duplicate blocks 22 → 44, risk findings 5 → 8, from the site alone.
+
+Not a `docs/html/` exclusion: a directory-name rule is what ADR 010 rejected.
+The renderer declares what it wrote, with the `@generated` banner discovery
+already honours, and discovery does the rest for any repository whose
+renderer says so.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+from maintainability_audit.config import load_config
+from maintainability_audit.report import build_report
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _renderer():
+    spec = importlib.util.spec_from_file_location("render_docs_under_test", ROOT / "tools" / "render_docs.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_every_rendered_page_declares_itself_generated(tmp_path: Path) -> None:
+    out = tmp_path / "html"
+    _renderer().render(ROOT, out)
+    pages = sorted(out.glob("*.html"))
+
+    # `render` returns the Markdown sources, not the pages; reading the
+    # output directory is what makes this about what was written.
+    assert len(pages) > 10, "the renderer wrote too few pages; this test would pass vacuously"
+    unstamped = [p.name for p in pages
+                 if "@generated" not in p.read_text(encoding="utf-8").splitlines()[0]]
+    assert unstamped == []
+
+
+def test_a_stamped_page_is_not_scored_beside_its_markdown(tmp_path: Path) -> None:
+    banner = _renderer().GENERATED_BANNER
+    (tmp_path / "README.md").write_text("# Title\n\nTODO: settle this.\n", encoding="utf-8")
+    (tmp_path / "docs" / "html").mkdir(parents=True)
+    (tmp_path / "docs" / "html" / "readme.html").write_text(
+        f"{banner}\n<!doctype html><html><body><p>TODO: settle this.</p></body></html>\n",
+        encoding="utf-8")
+    (tmp_path / "app.py").write_text("def f():\n    return 1\n", encoding="utf-8")
+
+    report = build_report(tmp_path, load_config(None))
+
+    paths = {finding["path"] for finding in report["risk_findings"]}
+    assert "docs/html/readme.html" not in paths
+    assert "README.md" in paths

maintainability_agent-4.2.0/tests/test_exclude_additional_keeps_the_defaults.py

@@ -0,0 +1,53 @@
+"""`paths.exclude_additional` adds exclusions without discarding the defaults (#292).
+
+`deep_update` merges dicts and *replaces* lists, so a repository that set
+`paths.exclude_patterns` to skip one more directory silently discarded the
+whole default list — `.git/`, `node_modules/`, `vendor/`, `*.min.js` and
+whatever a later release adds — and froze a copy of it that drifts on the
+next release. secure-code-agent declined to do that rather than add one
+exclusion. `exclude_additional` appends to whatever the earlier tiers
+produced, at each tier, so a repository can add without restating.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import jsonschema
+
+from maintainability_audit.config import load_config
+from maintainability_audit.report import build_report
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _config_with(tmp_path: Path, paths: dict) -> str:
+    path = tmp_path / "maintainability-agent.json"
+    path.write_text(json.dumps({"version": 1, "paths": paths}), encoding="utf-8")
+    return str(path)
+
+
+def test_additions_keep_every_default(tmp_path: Path) -> None:
+    defaults = load_config(None)["paths"]["exclude_patterns"]
+
+    merged = load_config(_config_with(tmp_path, {"exclude_additional": ["scratch/"]}))
+
+    assert merged["paths"]["exclude_patterns"] == [*defaults, "scratch/"]
+
+
+def test_an_addition_is_honoured_by_the_scan(tmp_path: Path) -> None:
+    (tmp_path / "app.py").write_text("def f():\n    return 1\n", encoding="utf-8")
+    (tmp_path / "scratch").mkdir()
+    (tmp_path / "scratch" / "junk.py").write_text("def g():\n    return 2\n", encoding="utf-8")
+
+    config = load_config(_config_with(tmp_path, {"exclude_additional": ["scratch/"]}))
+    report = build_report(tmp_path, config)
+
+    assert report["summary"]["files_scanned"] == 1
+
+
+def test_the_published_schema_accepts_it() -> None:
+    schema = json.loads((ROOT / "maintainability-agent.schema.json").read_text(encoding="utf-8"))
+
+    jsonschema.validate({"version": 1, "paths": {"exclude_additional": ["scratch/"]}}, schema)

{maintainability_agent-4.1.0 → maintainability_agent-4.2.0}/tests/test_readme_claims.py

@@ -391,3 +391,19 @@ def test_the_readme_opens_with_the_corpus_size_in_bold() -> None:
 
     assert f"**Calibrated against {CORPUS_SIZE} mature open-source repositories" in opening
     assert f"in {words.get(len(CORPUS_LANGUAGES), len(CORPUS_LANGUAGES))} languages" in opening
+
+
+def test_the_readme_states_the_security_runs_actual_limit() -> None:
+    """The README tells a reader how long the security run may take.
+
+    That sentence names a number the code owns, so it is held to
+    `DEFAULT_TIMEOUT_SECONDS` the way the corpus headline is held to
+    `CORPUS_SIZE`: a default raised in code cannot leave the README promising
+    the old one.
+    """
+    from maintainability_audit._security_delegate import DEFAULT_TIMEOUT_SECONDS
+
+    readme = (ROOT / "README.md").read_text(encoding="utf-8")
+
+    assert f"up to {DEFAULT_TIMEOUT_SECONDS // 60} minutes" in readme
+    assert "security.timeout_seconds" in readme

maintainability_agent-4.2.0/tests/test_regular_file_reads_work_without_o_nonblock.py

@@ -0,0 +1,28 @@
+"""Reading a regular file works on a platform with no `os.O_NONBLOCK`.
+
+`open_regular_file` opens with `O_NONBLOCK` so a FIFO cannot hang the open
+before the regular-file check runs. Windows has no such flag, and the module
+used it unconditionally, so every read on the Windows probe died with
+`module 'os' has no attribute 'O_NONBLOCK'`. Windows has no POSIX FIFO in
+the tree to guard against, so where the flag does not exist the open goes
+without it; the check that follows is unchanged.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from maintainability_audit._operator_reads import open_regular_file
+
+
+def test_a_regular_file_opens_where_the_flag_does_not_exist(tmp_path: Path, monkeypatch) -> None:
+    target = tmp_path / "config.json"
+    target.write_text("{}", encoding="utf-8")
+    monkeypatch.delattr(os, "O_NONBLOCK")
+
+    handle = open_regular_file(target, "test")
+    try:
+        assert os.read(handle, 10) == b"{}"
+    finally:
+        os.close(handle)