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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.2.0
+Version: 2.4.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,10 +44,10 @@ 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.4.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
+**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
 measured with that language's own reading of what a branch is.
 [What that means per language](#language-support).
 
@@ -252,9 +252,9 @@ SonarQube, Qlty) rather than replacing them — their SARIF folds in via
 and on an unrecognized language it will quietly under-report rather than fail.**
 Coverage comes from two layers.
 
-Eight languages are parsed as of **1.6.0**: Python (1.0), Java (1.0), C (1.1),
-C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), the JS/TS family,
-and HTML. Each has a scanner written for it and a documented list of what it
+Nine languages are parsed as of **2.4.0**: Python (1.0), Java (1.0), C (1.1),
+C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), Swift (2.4), the
+JS/TS family, and HTML. Each has a scanner written for it and a documented list of what it
 misses — a language is claimed here only when both exist.
 
 **Built-in scanner (always on, no dependencies)** — reads function/class
@@ -268,6 +268,7 @@ these:
 | C (`.c`, `.h`) | dedicated brace-bounded scanner — functions, `struct`/`enum`/`union` | Bounded; prototypes and macros are not declarations |
 | C++ (`.cpp`, `.hpp`, `.cc`, `.cxx`, `.hh`) | dedicated brace-bounded scanner — functions, class members, namespaces, templates | Bounded; bodyless declarations are not definitions |
 | C# (`.cs`) | dedicated brace-bounded scanner — methods, constructors, `class`/`interface`/`struct`/`record`/`enum` | Bounded; properties are not declarations |
+| Swift (`.swift`) | dedicated brace-bounded scanner — functions, initialisers, subscripts, `class`/`struct`/`enum`/`protocol`/`actor` | Bounded; extension members carry their type, protocol requirements and computed properties are not declarations |
 | Fortran, free-form (`.f90`, `.f95`, `.f03`, `.f08`, `.F90`, `.F95`, `.F03`, `.F08`, `.pf`) | dedicated **keyword**-bounded scanner — modules, subroutines, functions, derived types | Bounded by `end`; measured with Fortran's own branch and nesting reading |
 | Fortran, fixed-form (`.f`, `.for`, `.ftn`, `.F`, `.FOR`, `.FTN`) | the same scanner over card-column source; continuations joined, labelled `DO` loops understood | Bounded by `end` or by the loop's label |
 | JS / TS / JSX / TSX (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`) | brace/paren depth over a masked copy | Bounded by the declaration's own braces |

{maintainability_agent-2.2.0 → maintainability_agent-2.4.0}/README.md

@@ -5,10 +5,10 @@
 **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.4.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
+**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
 measured with that language's own reading of what a branch is.
 [What that means per language](#language-support).
 
@@ -213,9 +213,9 @@ SonarQube, Qlty) rather than replacing them — their SARIF folds in via
 and on an unrecognized language it will quietly under-report rather than fail.**
 Coverage comes from two layers.
 
-Eight languages are parsed as of **1.6.0**: Python (1.0), Java (1.0), C (1.1),
-C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), the JS/TS family,
-and HTML. Each has a scanner written for it and a documented list of what it
+Nine languages are parsed as of **2.4.0**: Python (1.0), Java (1.0), C (1.1),
+C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), Swift (2.4), the
+JS/TS family, and HTML. Each has a scanner written for it and a documented list of what it
 misses — a language is claimed here only when both exist.
 
 **Built-in scanner (always on, no dependencies)** — reads function/class
@@ -229,6 +229,7 @@ these:
 | C (`.c`, `.h`) | dedicated brace-bounded scanner — functions, `struct`/`enum`/`union` | Bounded; prototypes and macros are not declarations |
 | C++ (`.cpp`, `.hpp`, `.cc`, `.cxx`, `.hh`) | dedicated brace-bounded scanner — functions, class members, namespaces, templates | Bounded; bodyless declarations are not definitions |
 | C# (`.cs`) | dedicated brace-bounded scanner — methods, constructors, `class`/`interface`/`struct`/`record`/`enum` | Bounded; properties are not declarations |
+| Swift (`.swift`) | dedicated brace-bounded scanner — functions, initialisers, subscripts, `class`/`struct`/`enum`/`protocol`/`actor` | Bounded; extension members carry their type, protocol requirements and computed properties are not declarations |
 | Fortran, free-form (`.f90`, `.f95`, `.f03`, `.f08`, `.F90`, `.F95`, `.F03`, `.F08`, `.pf`) | dedicated **keyword**-bounded scanner — modules, subroutines, functions, derived types | Bounded by `end`; measured with Fortran's own branch and nesting reading |
 | Fortran, fixed-form (`.f`, `.for`, `.ftn`, `.F`, `.FOR`, `.FTN`) | the same scanner over card-column source; continuations joined, labelled `DO` loops understood | Bounded by `end` or by the loop's label |
 | JS / TS / JSX / TSX (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`) | brace/paren depth over a masked copy | Bounded by the declaration's own braces |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "2.2.0"
+version = "2.4.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.4.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.4.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,10 +44,10 @@ 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.4.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
+**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
 measured with that language's own reading of what a branch is.
 [What that means per language](#language-support).
 
@@ -252,9 +252,9 @@ SonarQube, Qlty) rather than replacing them — their SARIF folds in via
 and on an unrecognized language it will quietly under-report rather than fail.**
 Coverage comes from two layers.
 
-Eight languages are parsed as of **1.6.0**: Python (1.0), Java (1.0), C (1.1),
-C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), the JS/TS family,
-and HTML. Each has a scanner written for it and a documented list of what it
+Nine languages are parsed as of **2.4.0**: Python (1.0), Java (1.0), C (1.1),
+C++ (1.2), C# (1.3), Fortran (free-form 1.4, fixed-form 1.6), Swift (2.4), the
+JS/TS family, and HTML. Each has a scanner written for it and a documented list of what it
 misses — a language is claimed here only when both exist.
 
 **Built-in scanner (always on, no dependencies)** — reads function/class
@@ -268,6 +268,7 @@ these:
 | C (`.c`, `.h`) | dedicated brace-bounded scanner — functions, `struct`/`enum`/`union` | Bounded; prototypes and macros are not declarations |
 | C++ (`.cpp`, `.hpp`, `.cc`, `.cxx`, `.hh`) | dedicated brace-bounded scanner — functions, class members, namespaces, templates | Bounded; bodyless declarations are not definitions |
 | C# (`.cs`) | dedicated brace-bounded scanner — methods, constructors, `class`/`interface`/`struct`/`record`/`enum` | Bounded; properties are not declarations |
+| Swift (`.swift`) | dedicated brace-bounded scanner — functions, initialisers, subscripts, `class`/`struct`/`enum`/`protocol`/`actor` | Bounded; extension members carry their type, protocol requirements and computed properties are not declarations |
 | Fortran, free-form (`.f90`, `.f95`, `.f03`, `.f08`, `.F90`, `.F95`, `.F03`, `.F08`, `.pf`) | dedicated **keyword**-bounded scanner — modules, subroutines, functions, derived types | Bounded by `end`; measured with Fortran's own branch and nesting reading |
 | Fortran, fixed-form (`.f`, `.for`, `.ftn`, `.F`, `.FOR`, `.FTN`) | the same scanner over card-column source; continuations joined, labelled `DO` loops understood | Bounded by `end` or by the loop's label |
 | JS / TS / JSX / TSX (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`) | brace/paren depth over a masked copy | Bounded by the declaration's own braces |

{maintainability_agent-2.2.0 → maintainability_agent-2.4.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
@@ -63,6 +64,7 @@ src/maintainability_audit/_ranges_csharp.py
 src/maintainability_audit/_ranges_fortran.py
 src/maintainability_audit/_ranges_java.py
 src/maintainability_audit/_ranges_js.py
+src/maintainability_audit/_ranges_swift.py
 src/maintainability_audit/_ratchet.py
 src/maintainability_audit/_recurrence.py
 src/maintainability_audit/_runner.py
@@ -144,6 +146,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
@@ -287,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_swift_declarations.py
 tests/test_tdd_structure.py
 tests/test_test_execution_class.py
 tests/test_three_presentations.py

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

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

maintainability_agent-2.4.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.4.0}/src/maintainability_audit/_cognitive.py

@@ -45,6 +45,14 @@ _NESTING_NODES = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.ExceptHandler, a
 _NESTING_ONLY = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
 
 _CONTROL_RE = re.compile(r"\b(if|for|while|catch|switch|case|elif|except)\b")
+#: Swift adds `guard` — an early exit that is its primary branching idiom —
+#: and `repeat`, its do-while. Without them a function built from guards
+#: reads as having no branches at all, which is the Fortran `do` defect in
+#: another language: six nested loops once scored complexity 1 because the
+#: pattern did not know the keyword.
+_SWIFT_CONTROL_RE = re.compile(
+    r"\b(if|for|while|catch|switch|case|guard|repeat)\b"
+)
 _ELSE_RE = re.compile(r"\belse\b")
 _BOOLEAN_RE = re.compile(r"&&|\|\|")
 
@@ -167,7 +175,7 @@ def fortran_cognitive(lines: list[str]) -> int:
     return score
 
 
-def brace_cognitive(lines: list[str]) -> int:
+def brace_cognitive(lines: list[str], control: re.Pattern[str] | None = None) -> int:
     """Approximate cognitive complexity for a C-family declaration body.
 
     Nesting is read from brace depth relative to the declaration's own
@@ -191,16 +199,25 @@ def brace_cognitive(lines: list[str]) -> int:
         if base is None and opens:
             base = depth
         nesting = max(0, depth - (base if base is not None else 0))
-        score += _score_brace_line(line, nesting)
+        score += _score_brace_line(line, nesting, control or _CONTROL_RE)
         depth = max(0, depth + opens - closes)
     return score
 
 
-def _score_brace_line(line: str, nesting: int) -> int:
+def _score_brace_line(line: str, nesting: int, control: re.Pattern[str]) -> int:
     score = 0
-    for _ in _CONTROL_RE.finditer(line):
+    for _ in control.finditer(line):
         score += 1 + nesting
     if _ELSE_RE.search(line):
         score += 1
     score += len(_BOOLEAN_RE.findall(line))
     return score
+
+
+def swift_cognitive(lines: list[str]) -> int:
+    """`brace_cognitive` reading Swift's control keywords.
+
+    Swift is braced, so nesting is read the same way; only the vocabulary
+    differs, and `guard` is the difference that matters.
+    """
+    return brace_cognitive(lines, _SWIFT_CONTROL_RE)

{maintainability_agent-2.2.0 → maintainability_agent-2.4.0}/src/maintainability_audit/_metrics_types.py

@@ -53,6 +53,20 @@ COMPLEXITY_RE = re.compile(
 )
 
 
+#: Swift's `guard` is an early exit and its primary branching idiom, and
+#: `repeat` is its do-while. Neither is in the C-family pattern, so a
+#: guard-heavy function would read as branchless — the same defect Fortran
+#: had with `do`.
+SWIFT_COMPLEXITY_RE = re.compile(
+    r"\b(if|for|while|case|catch|guard|repeat)\b|&&|\|\||\?\?|\?(?![.?])"
+)
+
+
+def swift_branch_points(line: str) -> int:
+    """Decision points on one line of Swift."""
+    return len(SWIFT_COMPLEXITY_RE.findall(line))
+
+
 def branch_points(line: str) -> int:
     """Decision points on one line, for the C family and Python."""
     return len(COMPLEXITY_RE.findall(line))

maintainability_agent-2.4.0/src/maintainability_audit/_ranges_swift.py

@@ -0,0 +1,215 @@
+"""Declaration ranges for Swift.
+
+Braced, so it reuses `scan_bounded` with C, C++, C# and Java. What is
+different is worth stating, because two of the differences are the whole
+job and one of them is a trap this project has already fallen into once.
+
+**Every declaration is keyword-led.** `func`, `init`, `subscript`, `class`,
+`struct`, `enum`, `protocol`, `actor`, `extension`. That makes recognition
+*easier* than C++, where a bare `name(` is equally a call, a macro and a
+constructor, and where a wrong guess let a macro swallow the next
+declaration's braces. Nothing here has to guess.
+
+**An `extension` adds members to a type declared elsewhere**, often in
+another file. `extension Widget { func draw() }` must report `Widget.draw`
+rather than a second bare `draw` indistinguishable from every other type's,
+which is the same rule C++ applies to an out-of-line `void geo::Widget::draw()`.
+The extension itself is walked into and not graded: it is a container, and
+grading it would count its members twice.
+
+**Computed properties are not declarations**, and this is the C# properties
+problem in Swift spelling. `var area: Double { w * h }` has braces and would
+bound perfectly cleanly; an ordinary Swift type has many, each a line or
+two, none anybody's maintenance burden. Counting them would dilute the
+population every declaration rate divides by. They are excluded by
+construction rather than by a rule: every pattern here requires either a
+parameter list or a type keyword, and a property has neither.
+
+**A protocol requirement has no body** — `func draw()` with nothing after
+it — so it mints nothing, exactly as a C prototype and a pure virtual do.
+A protocol of forty requirements is not forty declarations.
+
+One claim was corrected while writing this. The roadmap said Swift's string
+interpolation "puts braces inside literals, so masking has to run before
+depth counting". It does not: Swift interpolates with `\\(expr)` —
+parentheses, not braces — and string contents are masked before any
+counting regardless. The real reason masking matters here is the ordinary
+one every language shares: a brace inside a string literal, `"{}"`, would
+desync depth.
+"""
+from __future__ import annotations
+
+import re
+
+from ._metrics_types import DeclRange
+from ._ranges_core import _mask_generics, scan_bounded
+
+# Stripped once per line so the patterns stay small: these lead a
+# declaration and say nothing about what it is.
+_SW_MODIFIER_RE = re.compile(
+    r"^\s*(?:(?:public|private|internal|fileprivate|open|static|final"
+    r"|override|mutating|nonmutating|convenience|required|lazy|weak|unowned"
+    r"|indirect|dynamic|optional|async|throws|rethrows|infix|prefix|postfix"
+    r"|package)\s+)*"
+)
+# `class` is both a declaration keyword and a modifier: `class Widget` is a
+# type, `class func make()` is a type-level method. Stripping it with the
+# other modifiers cost every `final class Store` its keyword — the type
+# vanished and only its members were reported. So it is removed only where
+# a declaration keyword follows it, and left alone otherwise.
+_SW_CLASS_MODIFIER_RE = re.compile(r"^class\s+(?=(?:func|var|let|subscript)\b)")
+# `@objc`, `@available(iOS 13, *)`, `@MainActor` — an attribute leads a
+# declaration and is not one. Stripped, so what follows is still read.
+_SW_ATTRIBUTE_RE = re.compile(r"^\s*(?:@[A-Za-z_]\w*(?:\([^)]*\))?\s*)+")
+# `extension Widget`, `extension Widget: Drawable`, `extension Array where …`
+_SW_EXTENSION_RE = re.compile(r"^extension\s+([A-Za-z_][\w.]*)")
+# The container keywords. `protocol` is here so its body is walked into —
+# its requirements are then skipped for having no body, which is what makes
+# a forty-requirement protocol mint nothing.
+_SW_TYPE_RE = re.compile(
+    r"^(?:class|struct|enum|protocol|actor)\s+([A-Za-z_]\w*)"
+)
+# `func name(`, and the three declarations that carry no `func` keyword.
+_SW_FUNC_RE = re.compile(r"^func\s+([A-Za-z_]\w*|[^\s(]+)\s*(?:<[^>]*>)?\s*\(")
+_SW_INIT_RE = re.compile(r"^(init\??|deinit|subscript)\b")
+
+
+def _swift_declaration(text: str) -> tuple[str, str | None] | None:
+    """``(name, kind)`` for a Swift declaration on one masked line.
+
+    ``kind`` is ``None`` for an `extension`: walk in, grade nothing.
+    """
+    line = _SW_ATTRIBUTE_RE.sub("", _mask_generics(text), count=1)
+    body = line[_SW_MODIFIER_RE.match(line).end():]
+    body = _SW_CLASS_MODIFIER_RE.sub("", body, count=1)
+    body = body[_SW_MODIFIER_RE.match(body).end():]
+
+    extension = _SW_EXTENSION_RE.match(body)
+    if extension is not None:
+        # The extended type's name, carried so its members can be reported
+        # as `Widget.draw` rather than as a second bare `draw`.
+        return extension.group(1), None
+
+    type_match = _SW_TYPE_RE.match(body)
+    if type_match is not None:
+        return type_match.group(1), "class"
+
+    func = _SW_FUNC_RE.match(body)
+    if func is not None:
+        return (func.group(1), "function") if _opens_a_body(body) else None
+
+    special = _SW_INIT_RE.match(body)
+    if special is not None:
+        return (special.group(1).rstrip("?"), "function") if _opens_a_body(body) else None
+
+    # Anything else — `var`, `let`, a computed property, a `case` — is not
+    # a declaration this tool measures. Falling through rather than listing
+    # exclusions keeps the rule "a declaration is keyword-led and named".
+    return None
+
+
+def _opens_a_body(body: str) -> bool:
+    """Whether this line starts a body, or is a requirement with none.
+
+    Swift has no statement terminator, so the shared `skip_bare` check
+    cannot work here: it looks for a signature that closes without opening
+    a brace, and in C or C# that is a `;`. A Swift protocol requirement
+    simply ends at the newline, so the end-finder walks on and adopts the
+    *next* declaration's brace — which is how `func describe() -> String`
+    inside a protocol came back measured as two lines of body.
+
+    The rule that replaces it: a signature whose parentheses balance on
+    this line and which then shows no `{` has no body. A wrapped signature
+    leaves its parentheses unbalanced, so it is still read as a
+    declaration and its body is found normally:
+
+        func draw(          <- unbalanced here, kept
+            into: Canvas
+        ) throws {
+
+    A body written Allman — `func f()` with `{` alone on the next line —
+    is missed and mints nothing. That is legal Swift and vanishingly rare
+    in it, and missing one declaration is the cheaper error than counting
+    every protocol requirement in the tree.
+    """
+    if "{" in body:
+        return True
+    return body.count("(") != body.count(")")
+
+
+def swift_declaration_ranges(lines: list[str]) -> tuple[list[DeclRange], list[str]]:
+    """Functions, initialisers and types, each bounded by its own body.
+
+    Types and extensions are descended into, because that is where members
+    live; a function body is stepped over, so nothing inside one is read as
+    a declaration.
+
+    Bodyless declarations mint nothing, as in C, C++ and C#: a protocol
+    requirement is a signature with nothing to measure, and grading it
+    would put one-line members into the population every rate divides by.
+
+    Everything it misses, it misses in the safe direction:
+
+    - **Computed properties** (`var area: Double { w * h }`) are not
+      declarations, the same call C# makes for the same reason.
+    - **A closure assigned to a property** is a body without a declaration
+      keyword and is not counted.
+    - **Declarations produced by a macro** (`@freestanding`, `#`-macros)
+      are not in the source and are not seen, as in C and C++.
+    - **Conditional compilation is not evaluated**, so a declaration in a
+      disabled `#if` arm still counts.
+    """
+    ranges, masked = scan_bounded(
+        lines, _swift_declaration, descend=("class",), skip_preprocessor=True
+    )
+    return _qualify_extension_members(ranges, masked), masked
+
+
+def _extension_spans(masked: list[str]) -> list[tuple[int, int, str]]:
+    """Every `extension X { … }` as (start, end, extended type)."""
+    def only_extensions(text: str) -> tuple[str, str | None] | None:
+        found = _swift_declaration(text)
+        if found is None:
+            return None
+        name, kind = found
+        return (name, "class") if kind is None else None
+
+    spans, _ = scan_bounded(
+        masked, only_extensions, descend=(), skip_preprocessor=True
+    )
+    return [(item.start, item.end, item.name) for item in spans]
+
+
+def _qualify_extension_members(
+    ranges: list[DeclRange], masked: list[str]
+) -> list[DeclRange]:
+    """Report an extension's members under the type they extend.
+
+    `extension Widget { func draw() }` becomes `Widget.draw`. Without it
+    the report carries a bare `draw` indistinguishable from every other
+    type's `draw`, and a reader given "shorten `draw`" cannot find which
+    one — the same reason C++ keeps the qualification on an out-of-line
+    `void geo::Widget::draw()`, except that in Swift the source does not
+    write it and the scanner has to carry it.
+
+    A member already qualified is left alone, and a nested type inside an
+    extension keeps its own name: the prefix answers "which type does this
+    belong to", which a named type already answers for itself.
+    """
+    spans = _extension_spans(masked)
+    if not spans:
+        return ranges
+    qualified = []
+    for item in ranges:
+        owner = next(
+            (name for start, end, name in spans
+             if start < item.start <= end and item.kind == "function"),
+            None,
+        )
+        if owner is None or "." in item.name:
+            qualified.append(item)
+            continue
+        qualified.append(
+            DeclRange(item.start, item.end, f"{owner}.{item.name}", item.kind)
+        )
+    return qualified

{maintainability_agent-2.2.0 → maintainability_agent-2.4.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")