maintainability-agent 3.1.0__tar.gz → 3.2.0__tar.gz

{maintainability_agent-3.1.0/src/maintainability_agent.egg-info → maintainability_agent-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.1.0
+Version: 3.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,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 **3.1.0**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.1.0 → maintainability_agent-3.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 **3.1.0**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.1.0
+Version: 3.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,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 **3.1.0**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -29,18 +29,21 @@ src/maintainability_audit/_conformance.py
 src/maintainability_audit/_corroborate.py
 src/maintainability_audit/_coverage_notes.py
 src/maintainability_audit/_criteria_scope.py
+src/maintainability_audit/_delegated_pillar.py
 src/maintainability_audit/_derive.py
 src/maintainability_audit/_discovery.py
 src/maintainability_audit/_documents.py
 src/maintainability_audit/_economics.py
 src/maintainability_audit/_economics_view.py
 src/maintainability_audit/_environment.py
+src/maintainability_audit/_evidence_reader.py
 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/_grammar.py
 src/maintainability_audit/_grant_ledger.py
 src/maintainability_audit/_history_view.py
 src/maintainability_audit/_hostile_prompt.py
@@ -68,6 +71,7 @@ src/maintainability_audit/_precommit.py
 src/maintainability_audit/_precommit_install.py
 src/maintainability_audit/_precommit_view.py
 src/maintainability_audit/_pressures.py
+src/maintainability_audit/_prompt_sections.py
 src/maintainability_audit/_ranges_c.py
 src/maintainability_audit/_ranges_cobol.py
 src/maintainability_audit/_ranges_core.py
@@ -82,6 +86,7 @@ src/maintainability_audit/_ranges_ruby.py
 src/maintainability_audit/_ranges_rust.py
 src/maintainability_audit/_ranges_swift.py
 src/maintainability_audit/_ratchet.py
+src/maintainability_audit/_ratio_adapters.py
 src/maintainability_audit/_recurrence.py
 src/maintainability_audit/_run_comparison.py
 src/maintainability_audit/_runner.py
@@ -212,8 +217,10 @@ tests/test_declaration_edge_cases.py
 tests/test_declaration_grading.py
 tests/test_declaration_ranges.py
 tests/test_declaration_source.py
+tests/test_declarative_parsers.py
 tests/test_declared_authorship.py
 tests/test_declared_imports.py
+tests/test_delegated_security_pillar.py
 tests/test_derivation_mix.py
 tests/test_determinism.py
 tests/test_dimension_ratchet.py
@@ -280,6 +287,7 @@ tests/test_network_disclosure.py
 tests/test_one_setup_across_surfaces_class.py
 tests/test_operator_named_paths.py
 tests/test_operator_named_reads.py
+tests/test_pairing_reads_imports.py
 tests/test_pattern_budget.py
 tests/test_phase6_claims.py
 tests/test_php_declarations.py
@@ -303,6 +311,7 @@ tests/test_python_declarations.py
 tests/test_read_boundary.py
 tests/test_readme_claims.py
 tests/test_recurrence.py
+tests/test_release_needs_an_empty_ledger.py
 tests/test_release_plan.py
 tests/test_release_plan_status.py
 tests/test_report_remedy_copy.py
@@ -334,6 +343,7 @@ tests/test_stage8_contract.py
 tests/test_suite_isolation.py
 tests/test_swift_declarations.py
 tests/test_tdd_structure.py
+tests/test_terminal_asks_the_same_questions.py
 tests/test_test_commands.py
 tests/test_test_execution_class.py
 tests/test_three_presentations.py

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.1.0"
+__version__ = "3.2.0"

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_audit/_anchor.py

@@ -63,8 +63,11 @@ def unanchored_sentence() -> str:
     """One sentence naming what the anchor omits, for the corpus note."""
     if not UNANCHORED_LANGUAGES:
         return ""
+    from ._grammar import agreement
+
+    say = agreement(len(UNANCHORED_LANGUAGES))
     return (
-        f"{unanchored_names()} are parsed but absent from it, so their "
-        "findings are as good as their parser while their grade is "
-        "provisional."
+        f"{unanchored_names()} {say.verb} parsed but absent from it, so "
+        f"{say.possessive} findings are as good as {say.possessive} "
+        f"parser while {say.possessive} grade is provisional."
     )

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_audit/_catalog.py

@@ -190,7 +190,23 @@ def decide(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
     3. the depth, licence and concern tiers.
     """
     slug = tool["slug"]
+    return (
+        _denial(tool, settings)
+        or (Selection(slug, True, "explicitly allowed by name")
+            if slug in settings["allow_tools"] else None)
+        or _tier_decision(tool, settings)
+    )
+
+
+def _denial(tool: dict[str, Any], settings: dict[str, Any]) -> Selection | None:
+    """Step 1: every deny, which beats even an explicit allow.
 
+    `None` means nothing here refused the tool, not that it was admitted —
+    the caller has two more steps. Separate from the tiers because these
+    are the operator's own prohibitions and the tiers are policy: a deny
+    that could be overridden by an allow would not be a deny.
+    """
+    slug = tool["slug"]
     if slug in settings["deny_tools"]:
         return Selection(slug, False, "denied by name")
     if tool["license_class"] in settings["deny_license_classes"]:
@@ -198,10 +214,14 @@ def decide(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
     denied_concerns = set(tool["upstream_tags"]) & set(settings["deny_concerns"])
     if denied_concerns:
         return Selection(slug, False, f"concern {','.join(sorted(denied_concerns))} denied")
+    return None
 
-    if slug in settings["allow_tools"]:
-        return Selection(slug, True, "explicitly allowed by name")
 
+def _tier_decision(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
+    """Step 3: the depth, licence and concern tiers, for a tool no deny
+    caught and no allow admitted. The only step that can end in `True`
+    on the tool's own merits."""
+    slug = tool["slug"]
     if tool["deprecated"]:
         return Selection(slug, False, "deprecated upstream")
     if not tool["languages"]:

maintainability_agent-3.2.0/src/maintainability_audit/_delegated_pillar.py

@@ -0,0 +1,181 @@
+"""Reading a delegated pillar's own report of itself.
+
+[ADR 007](adr-007-pillars-and-practice.md) makes the five pillars of the
+source framework the top-level taxonomy and declares **Security
+delegated to `secure-code-agent`**, reported as `NotApplicable` so that
+silence is never read as safety. That entry was always a placeholder for
+an artifact that did not exist yet: the other tool measures the pillar,
+so the other tool has to be the one that reports it.
+
+`secure-code-agent` 0.5.0 ships the emitter — `--security-pillar <path>`
+writes `security-pillar.json`, schema `secure-code-agent/security-pillar`
+— and it was built against *this* vocabulary rather than its own. The
+scope words, the two-axis split and the posture matrix with its
+thresholds all come from `_pillars.py`, because two tools saying "level
+3" or "healthy" about one repository have to mean the same thing by it
+or the joined view is worse than either alone.
+
+This module reads the document and checks it is the one expected. The
+*shaping* of the pillar entry lives in `_pillars` beside the entries it
+sits among — scoring may not import a scanner, and reading a path the
+audited tree chooses is what makes this one. Neither half computes a
+number: a delegated pillar's numbers belong to the tool that measured
+them, and a consumer that recomputed anything would be a second opinion
+nobody asked for.
+
+**Absence is the normal case and stays the documented one.** No file
+means the pillar reports exactly what it reported before — delegated,
+`NotApplicable`, naming the other tool. That path is not a failure and
+does not warn: most repositories run one tool.
+
+**A file that cannot be trusted is refused rather than partly believed.**
+Wrong schema, unreadable JSON, a shape that is not an object — each
+returns `None`, and the pillar falls back to the honest placeholder. The
+alternative is a security posture assembled from a document this tool
+does not actually understand, which is worse than no posture at all.
+
+A trailing note on where this sits: it reads a path from the audited
+tree, so it is a scanner rather than part of the rubric.
+`test_scoring_never_imports_scanners_or_assembly` holds that boundary,
+and `report` is what joins the two.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ._operator_reads import PathNotAllowed, read_source_file
+
+#: Written beside the other artifacts a repository keeps about itself.
+#: The path is a convention rather than a search: a document this tool
+#: trusts for a whole pillar should be somewhere a reader can find, not
+#: wherever a glob happened to match.
+DEFAULT_PILLAR_PATH = ".maintainability/security-pillar.json"
+
+#: The contract this module understands. A document announcing anything
+#: else is refused rather than read hopefully — the schema string is the
+#: producer's promise about the shape, and guessing past it is how a
+#: consumer starts reporting fields that mean something different.
+SCHEMA = "secure-code-agent/security-pillar"
+SCHEMA_VERSION = 1
+
+#: What the pillar block takes from the document. Named rather than
+#: copied wholesale so a field added upstream cannot silently appear in
+#: this tool's report carrying meaning nobody here has checked.
+CARRIED = (
+    "practice",
+    "condition",
+    "condition_letter",
+    "posture",
+    "verified_grade",
+    "evidence_status",
+    "evidence_reasons",
+    "coverage",
+    "findings_by_severity",
+    "reported_not_scored",
+    "loc_scanned",
+)
+
+
+def read_delegated(root: Path, relative: str = DEFAULT_PILLAR_PATH) -> dict[str, Any] | None:
+    """The delegated pillar's own report, or `None` when there is none.
+
+    `None` for every reason a reader might not get a usable document:
+    the file is absent, it is not a regular file, it does not parse, it
+    is not an object, or it announces a schema this tool does not know.
+    All five collapse to one answer because the caller does the same
+    thing with each — keep the placeholder that names the other tool.
+
+    Read through the regular-file primitive like every other path the
+    audited tree chooses (D145): a FIFO here would hang the audit rather
+    than fail it.
+    """
+    path = Path(root) / relative
+    if not path.exists():
+        return None
+    try:
+        payload = json.loads("\n".join(read_source_file(path)))
+    except (OSError, ValueError) as error:
+        if isinstance(error, PathNotAllowed):
+            raise
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if payload.get("schema") != SCHEMA:
+        return None
+    if payload.get("schema_version") != SCHEMA_VERSION:
+        return None
+    return payload if _is_well_formed(payload) else None
+
+
+#: Fields whose *shape* the consumer depends on. A header check alone
+#: accepts any object announcing the right schema, and the pillar then
+#: reads these as if the producer had promised them.
+_SHAPES: tuple[tuple[str, type | tuple[type, ...]], ...] = (
+    ("producer", dict),
+    ("practice", dict),
+    ("condition", (int, float, type(None))),
+    ("posture", (str, type(None))),
+    ("evidence_status", (str, type(None))),
+    ("coverage", (dict, type(None))),
+    ("findings_by_severity", (dict, type(None))),
+    ("reported_not_scored", (dict, type(None))),
+)
+
+#: The postures this tool knows how to render. A document naming one it
+#: does not is refused rather than printed through: the word is the
+#: reader's whole summary of the pillar.
+_POSTURES = frozenset({"healthy", "managed debt", "unmanaged debt", "unverified"})
+
+
+def _is_well_formed(payload: dict[str, Any]) -> bool:
+    """Whether the document's fields are the shapes the pillar reads.
+
+    The header said what the document *claims to be*; this asks whether
+    it is. Checking only `schema` accepted
+    `{"producer": "not-an-object", ...}`, which the pillar then indexed
+    as a mapping and crashed on — a well-formed announcement with a
+    malformed body, which is the shape a header check cannot see.
+
+    Also refused: a `posture` this tool cannot render, and a `posture`
+    the document's own two axes do not support. The second is the one
+    worth stating. `healthy` requires practice at or above
+    `HIGH_PRACTICE` and a condition at or above `GOOD_CONDITION`; a
+    document claiming `healthy` at practice 1 is either a different
+    matrix or a mistake, and either way this tool must not print it.
+    Both tools are supposed to mean the same thing by the word — the
+    consumer is where that is checkable.
+    """
+    for name, kinds in _SHAPES:
+        if name in payload and not isinstance(payload[name], kinds):
+            return False
+    practice = payload.get("practice")
+    if isinstance(practice, dict) and not isinstance(practice.get("level"), int):
+        return False
+    posture = payload.get("posture")
+    if posture is not None and posture not in _POSTURES:
+        return False
+    return _posture_agrees(payload)
+
+
+def _posture_agrees(payload: dict[str, Any]) -> bool:
+    """Whether the stated posture follows from the two axes given.
+
+    Recomputed rather than trusted. The matrix and its thresholds are
+    `_pillars.py`'s, copied into the producer by value, and a copied
+    constant is a constant that can drift — so the one place the two
+    can be compared is here, against a document carrying both inputs
+    and the answer.
+    """
+    from ._pillars import posture as compute
+
+    stated = payload.get("posture")
+    practice = payload.get("practice")
+    if stated is None or not isinstance(practice, dict):
+        return True
+    level = practice.get("level")
+    condition = payload.get("condition")
+    if not isinstance(level, int):
+        return False
+    return compute(level, condition) == stated

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_audit/_derive.py

@@ -17,9 +17,10 @@ from statistics import median
 from typing import Any
 
 from ._aspects import evidence_aspect_scores, is_untested
+from ._evidence_reader import normalize_report_evidence
 from ._formula import CALIBRATED_ASPECTS, curve, overall_from_aspects
 from ._pressures import production_pressures
-from .evidence import REPORT_SCHEMA_VERSION, SCHEMA_VERSION_KEY, normalize_report_evidence
+from .evidence import REPORT_SCHEMA_VERSION, SCHEMA_VERSION_KEY
 
 # The stored column holding the analyzers' production reading. Named
 # once because both the refusal and the mix key on it.

{maintainability_agent-3.1.0 → maintainability_agent-3.2.0}/src/maintainability_audit/_discovery.py

@@ -35,6 +35,7 @@ from __future__ import annotations
 
 import json
 import re
+from collections.abc import Iterator
 from dataclasses import dataclass, field
 from enum import StrEnum
 from pathlib import Path
@@ -228,25 +229,8 @@ def _generated_directories(root: Path, excludes: tuple[str, ...]) -> dict[str, s
         relative = manifest.relative_to(root).as_posix()
         if is_excluded(relative, list(excludes)):
             continue
-        try:
-            scripts = json.loads(_text_of(manifest)).get("scripts", {})
-        except PathNotAllowed:
-            # `PathNotAllowed` is a `ValueError`, so it would otherwise be
-            # swallowed by the clause below and the manifest would read as
-            # a malformed one rather than a refused one (D145). A FIFO
-            # named `package.json` is not bad JSON; it is a path this tool
-            # will not read, and saying so is the whole point of routing
-            # the read through the primitive.
-            raise
-        except (OSError, ValueError, AttributeError):
-            continue
-        if not isinstance(scripts, dict):
-            continue
-        for name, command in scripts.items():
-            for target in DELETES_DIRECTORY.findall(str(command)):
-                cleaned = target.strip("./")
-                if not cleaned or cleaned.startswith(".."):
-                    continue
+        for name, command in _manifest_scripts(manifest).items():
+            for cleaned in _deleted_targets(str(command)):
                 directory = (manifest.parent / cleaned).relative_to(root).as_posix()
                 found.setdefault(
                     directory,
@@ -256,6 +240,40 @@ def _generated_directories(root: Path, excludes: tuple[str, ...]) -> dict[str, s
     return found
 
 
+def _manifest_scripts(manifest: Path) -> dict[str, Any]:
+    """One `package.json`'s scripts block, or empty if it has none to read.
+
+    Empty covers unreadable, malformed and shaped-wrong alike, because
+    none of the three is a statement about generated directories. A
+    refusal is the exception: `PathNotAllowed` is re-raised.
+    """
+    try:
+        scripts = json.loads(_text_of(manifest)).get("scripts", {})
+    except PathNotAllowed:
+        # `PathNotAllowed` is a `ValueError`, so it would otherwise be
+        # swallowed by the clause below and the manifest would read as
+        # a malformed one rather than a refused one (D145). A FIFO
+        # named `package.json` is not bad JSON; it is a path this tool
+        # will not read, and saying so is the whole point of routing
+        # the read through the primitive.
+        raise
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return scripts if isinstance(scripts, dict) else {}
+
+
+def _deleted_targets(command: str) -> Iterator[str]:
+    """The directory names one script command deletes, normalized.
+
+    A target that cleans to nothing, or that climbs out of the manifest's
+    own directory, is not a directory this repository generates.
+    """
+    for target in DELETES_DIRECTORY.findall(command):
+        cleaned = target.strip("./")
+        if cleaned and not cleaned.startswith(".."):
+            yield cleaned
+
+
 def _vendored_directories(root: Path) -> dict[str, str]:
     """Directories the repository says belong to someone else."""
     found: dict[str, str] = {}
@@ -315,18 +333,44 @@ def _asset_snapshot_directories(root: Path, excludes: tuple[str, ...]) -> dict[s
     }
 
 
+def _sorted_by_kind(
+    files: list[Path],
+) -> tuple[list[Path], list[Path], list[str]]:
+    """Markup pages, source files, and the other suffixes present.
+
+    One pass, three answers. It was three comprehensions re-testing the
+    same two memberships, which read as cyclomatic 15 in sixteen lines —
+    the joint-highest in the package and one branch from failing the
+    gate — for a function whose actual job is "sort these into three
+    piles".
+
+    The two tests deliberately stay independent rather than becoming an
+    `elif` chain: `.html` is both a markup suffix and a known source
+    suffix, so it belongs in *both* piles, and an `elif` would quietly
+    drop it from `code` and change what the ratio below compares.
+    """
+    markup: list[Path] = []
+    code: list[Path] = []
+    other: set[str] = set()
+    for found in files:
+        lowered = found.suffix.lower()
+        is_markup = lowered in _MARKUP_SUFFIXES
+        is_code = found.suffix in KNOWN_SOURCE_SUFFIXES
+        if is_markup:
+            markup.append(found)
+        if is_code:
+            code.append(found)
+        if found.suffix and not is_markup and not is_code:
+            other.add(lowered)
+    return markup, code, sorted(other)
+
+
 def _asset_evidence(files: list[Path]) -> str | None:
     """Why a directory is a saved page asset, or None."""
     versioned = sorted(f.name for f in files if _VERSIONED_SNAPSHOT.search(f.name))
     if versioned:
         return f"versioned page snapshot(s): {', '.join(versioned[:3])}"
-    markup = [f for f in files if f.suffix.lower() in _MARKUP_SUFFIXES]
-    code = [f for f in files if f.suffix in KNOWN_SOURCE_SUFFIXES]
-    siblings = sorted({
-        f.suffix.lower() for f in files
-        if f.suffix and f.suffix.lower() not in _MARKUP_SUFFIXES
-        and f.suffix not in KNOWN_SOURCE_SUFFIXES
-    })
+    markup, code, siblings = _sorted_by_kind(files)
     if len(markup) >= 2 and len(markup) > len(code) and siblings:
         return (f"{len(markup)} HTML/CSS pages outnumbering source, beside "
                 f"non-source assets ({', '.join(siblings[:4])})")