maintainability-agent 0.1.0__py3-none-any.whl

maintainability_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: maintainability-agent
+Version: 0.1.0
+Summary: Maintainability gate and AI remediation prompt generator for CI.
+Author: Marshall Guillory
+License: MIT
+Keywords: maintainability,ci,audit,quality,iso-25010,ai-code-review
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: jsonschema>=4; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Dynamic: license-file
+
+# Maintainability Agent
+
+A deterministic CI gate + bounded remediation prompt generator for repos that use AI coding agents (Claude, Codex, Cursor, Copilot, Windsurf, …).
+
+## Why this exists
+
+AI-written code fails in recognizable ways: speculative refactors, duplicated helpers, broad rewrites for narrow bugs, stale comments that sound confident, tests that assert implementation details instead of behavior, architecture drift across modules. SonarQube / CodeClimate / Qlty / ESLint / Ruff / Radon all catch some of this. None of them ship a **bounded prompt back to the agent** that says *"fix only these specific findings, do not refactor outside this scope."*
+
+That's the point of this tool:
+
+1. Run a deterministic local audit — file size, function size, approximate cyclomatic complexity, duplication, configurable risk patterns, ISO/IEC 25010-inspired 0–5 score.
+2. Emit Markdown, JSON, SARIF, a PR comment, and a baseline for incremental adoption.
+3. Generate an **AI remediation prompt scoped to the actual findings** — bounded, with explicit "don't rewrite the codebase" rules.
+4. Hand that prompt to your agent. Get a small, reviewable fix instead of a 600-line speculative cleanup PR.
+
+The remediation prompt is the differentiator. Every other tool in this space stops at "here's a list of findings."
+
+## Who it's for
+
+- Teams running AI agents in the dev loop who are tired of unbounded agent rewrites and want a CI gate that actively constrains follow-up scope.
+- Repos that want a maintainability gate without paying for SonarQube / CodeClimate / Qlty or sending code to a third party.
+- Solo devs who want a single-binary deterministic audit they can pin in a Makefile, a pre-commit, or a local CI script.
+
+## Design principles
+
+- **Deterministic first, AI optional.** The audit never calls an LLM by default. The remediation prompt is a generated artifact that you choose to hand to an agent.
+- **Bounded scope.** The remediation prompt explicitly tells the agent to fix the listed findings only — not to embark on architecture cleanup.
+- **No vendor lock-in.** All outputs (Markdown, JSON, SARIF, PR comment) are plain files. Pair this tool with mature analyzers (ESLint, Ruff, Radon, Semgrep, SonarQube, Qlty/Code Climate) — don't replace them.
+- **Pass-the-cost-of-disclosure.** A finding that's "just a warning" never blocks CI alone. Hard gates are configurable + opt-in.
+
+See [docs/philosophy.md](docs/philosophy.md) for the longer version.
+
+## Self-Audit
+
+This repo eats its own dogfood — the tool is run against this codebase as part of CI, and the latest report is checked in at [docs/self-audit.md](docs/self-audit.md):
+
+| Metric | Value |
+|---|---:|
+| Overall score | **5.0 / 5 (A+)** |
+| File warnings | 0 |
+| Function warnings | 0 |
+| Duplicate blocks | 0 |
+| Risk findings | 0 |
+| Hard gate failures | 0 |
+
+All five ISO/IEC 25010 categories (modularity, reusability, analyzability, modifiability, testability) score 5.0. Regenerate with `maintainability-agent --config maintainability-agent.json --output docs/self-audit.md` (see the file's preamble for the path-sanitization step).
+
+## Install
+
+Run directly from source:
+
+```bash
+python3 -m maintainability_audit \
+  --root . \
+  --config maintainability-agent.json \
+  --output maintainability-report.md
+```
+
+Or install editable during development:
+
+```bash
+python3 -m pip install -e .
+maintainability-audit --root . --config maintainability-agent.json
+maintainability-agent --root . --config maintainability-agent.json
+```
+
+## Quick Start
+
+Copy the example config to your repo root as `maintainability-agent.json`:
+
+```bash
+cp maintainability-audit.example.json maintainability-agent.json
+```
+
+Run:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --format markdown \
+  --output maintainability-report.md
+```
+
+Fail CI on hard gates:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --fail-on-gate \
+  --output maintainability-report.md \
+  --prompt-output maintainability-remediation-prompt.md \
+  --comment-output maintainability-pr-comment.md
+```
+
+## What It Analyzes
+
+The deterministic scanner reads code from your repo (no LLM calls) and produces signals on:
+
+- largest files (warn / fail thresholds configurable per-repo)
+- approximate function/class size
+- approximate cyclomatic complexity
+- duplicate blocks (≥ N consecutive non-trivial lines, configurable)
+- configurable risk patterns (regex matchers — TODO/FIXME, `eval(`, `exec(`, custom)
+- expected files present (README, LICENSE, etc. — opt-in hard gate)
+- expected test/lint commands declared in the config (opt-in hard gate)
+- worktree-clean state at audit time (opt-in hard gate)
+- ISO/IEC 25010-inspired 0–5 score per category + overall letter grade
+
+The analyzer is intentionally conservative and dependency-free. Mature repos should **pair** this with native tools (ESLint, Ruff, Radon, Semgrep, SonarQube, Qlty / Code Climate) — not replace them. SARIF input from those tools can be folded into this tool's report via `--sarif-input`.
+
+## What It Produces
+
+Each run can emit any combination of:
+
+- `maintainability-report.md` — the full Markdown report with summary, score, hotspots, duplicates, risk findings, external (SARIF) findings.
+- `maintainability-remediation-prompt.md` — bounded AI prompt scoped to the run's findings.
+- `maintainability-pr-comment.md` — short body suitable for a `gh pr comment` post.
+- `maintainability.sarif` — SARIF 2.1.0 output for GitHub Code Scanning ingestion.
+- `maintainability-baseline.json` — fingerprints of current findings, for `--fail-on-new` incremental adoption.
+- Per-tool agent instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/maintainability.mdc`, `.github/copilot-instructions.md`, `.windsurf/rules/maintainability.md`, `AI-MAINTAINABILITY.md`) via `--init-agent-standards`.
+
+## AI Remediation Prompt
+
+The runner can generate a bounded prompt for a human developer to give to Claude, Codex, or another coding assistant:
+
+```bash
+maintainability-agent \
+  --config maintainability-agent.json \
+  --output maintainability-report.md \
+  --prompt-output maintainability-remediation-prompt.md
+```
+
+The prompt is designed for AI-written or AI-assisted code reviews. It tells the assistant to:
+
+- fix only the highest-value maintainability issues
+- keep the patch small and reviewable
+- preserve existing architecture and behavior
+- add tests where behavior changes
+- report false positives instead of rewriting blindly
+
+This makes the CI artifact actionable without letting the audit turn into an unbounded refactor request.
+
+## PR and Baseline Workflows
+
+PR-only audits, baseline grandfathering, AI-agent instruction
+generation, and reusable agent-standard file generation are covered
+in [PR and Baseline Workflows](docs/pr-and-baseline-workflows.md).
+
+## Running Tests
+
+```bash
+# Sandbox-friendly invocation (works with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1):
+PYTHONPATH=src python3 -m pytest
+
+# With coverage gate (matches CI):
+PYTHONPATH=src python3 -m pytest \
+  --cov=maintainability_audit --cov-fail-under=92
+
+# With ruff lint + pip-audit (matches CI):
+python3 -m pip install -e ".[dev]"
+ruff check src tests
+pip-audit
+PYTHONPATH=src python3 -m pytest --cov=maintainability_audit --cov-fail-under=92
+```
+
+Coverage is intentionally NOT in `[tool.pytest.ini_options].addopts` so the
+sandbox-friendly invocation (`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`) doesn't choke
+on `--cov` flags it can't load. Pass coverage flags explicitly when you want
+the gate.
+
+## Scoring Standard
+
+The audit model is based on ISO/IEC 25010 maintainability:
+
+- modularity
+- reusability
+- analyzability
+- modifiability
+- testability
+
+See [docs/standard.md](docs/standard.md).
+
+## Documentation
+
+- [CLI reference](docs/cli.md)
+- [Config schema](docs/config-schema.md)
+- [Philosophy](docs/philosophy.md)
+- [Analyzer adapters](docs/adapters.md)
+- [External quality tools](docs/external-quality-tools.md)
+- [IDE and agent integration](docs/ide-agent-integration.md)
+- [PR and baseline workflows](docs/pr-and-baseline-workflows.md)
+- [Roadmap](docs/roadmap.md)
+
+## GitHub Action
+
+This repo includes `action.yml`, so it can be used as a composite action after publishing:
+
+```yaml
+- uses: marshallguillory86/maintainability-agent@v0.1.0
+  with:
+    config: maintainability-agent.json
+    changed-only: main...HEAD
+```
+
+## GitHub Actions
+
+After publishing, copy `.github/workflows/maintainability.yml` into the target repo or adapt it for your local CI.
+
+## IDE and Agent Integration
+
+See [docs/ide-agent-integration.md](docs/ide-agent-integration.md) for VS Code tasks and integration notes for Copilot, Cursor, Codex, Claude Code, Windsurf, generic agents, local CI, and GitHub Actions.
+
+## Local CI
+
+For repos that do not use GitHub Actions, use:
+
+```bash
+examples/local-ci.sh
+```
+
+The local CI script enforces test coverage at `>=92%` and writes `coverage.xml` for SonarQube Cloud, Qlty, Codacy, or any other tool that can ingest Python coverage.
+
+## Get in Touch
+
+- **Bug reports / feature requests / general questions** — open a [GitHub Issue](https://github.com/marshallguillory86/maintainability-agent/issues/new).
+- **Discussion / ideas** — use the [Discussions tab](https://github.com/marshallguillory86/maintainability-agent/discussions) (enable in repo settings if not visible yet).
+- **Security vulnerabilities** — see [`SECURITY.md`](SECURITY.md) and use the [private security advisory flow](https://github.com/marshallguillory86/maintainability-agent/security/advisories/new). Do **not** post vulnerabilities in public issues.
+
+## License
+
+MIT

maintainability_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+maintainability_agent-0.1.0.dist-info/licenses/LICENSE,sha256=SOAOD6SRucfO7P_MWSLyyjwgr7x0s1BDaIskdGU8idI,1074
+maintainability_audit/__init__.py,sha256=CAsYl-VynwMlhvu_kggVnBGhEYDe535sU9t1iztAizA,55
+maintainability_audit/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+maintainability_audit/_metrics_types.py,sha256=u4ghOpZo5kElxWJv1HHTKT83Typ6xQYj8d2ThRp1tKw,1135
+maintainability_audit/baseline.py,sha256=oL51yElOmR4YYPhLGEnQwNnoMmGDVD20msioAR1Ee6g,1445
+maintainability_audit/cli.py,sha256=Pp_CsaMTLal1fUBdQw3QohvBpwg8CRJ-Blcq2PPs4xQ,5056
+maintainability_audit/config.py,sha256=rAshORNP8iBekt4Ckz6eFg9Oay6LkT1jGLgAnY4UuSc,2285
+maintainability_audit/git_tools.py,sha256=K6Kke3pgZk_bcDKPDPC9mB0MqTUMd4G8wGGyJbVHwC0,553
+maintainability_audit/instructions.py,sha256=RNJEEEf7yBaIEjUvRStU3VH1c5tScw_kgxd3SXUzBJQ,3773
+maintainability_audit/metrics.py,sha256=R5U9ZxWpMa5uT5GZi8uVCjjuBcuHWD_HwHLTYSN4XYI,10102
+maintainability_audit/renderers.py,sha256=fAvwdSVp5TA9arddmFePz4AAUMN5RjHl_LGHkH-vGlE,10539
+maintainability_audit/sarif.py,sha256=CnD6kMHxOh1IlBcn5rdUwJxvznjSqe4wYNaarlbmEfI,5804
+maintainability_audit/scoring.py,sha256=NJdzjtUFbAIC-cwtaV3nyEQ66vzH7g1lJjkqr3OJsCM,1755
+maintainability_agent-0.1.0.dist-info/METADATA,sha256=sLuk3tzu-id-xHxFalTl3LJDlFTALqzDcD7mlcUbrnU,10715
+maintainability_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+maintainability_agent-0.1.0.dist-info/entry_points.txt,sha256=obtbqnuhuK9DCe-9307elxX5hrVR4k-KL8-0KaAnay4,128
+maintainability_agent-0.1.0.dist-info/top_level.txt,sha256=h62cy_cvetBemtpg5sL3nxbEOrdcHZmfOSXEVjP2_38,22
+maintainability_agent-0.1.0.dist-info/RECORD,,

maintainability_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maintainability_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+maintainability-agent = maintainability_audit.cli:main
+maintainability-audit = maintainability_audit.cli:main

maintainability_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marshall Guillory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maintainability_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maintainability_audit

maintainability_audit/__init__.py

@@ -0,0 +1,3 @@
+"""Maintainability Audit CI."""
+
+__version__ = "0.1.0"

maintainability_audit/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maintainability_audit/_metrics_types.py

@@ -0,0 +1,45 @@
+"""Internal value-types + regex constants used by ``metrics.py``.
+
+Extracted from ``metrics.py`` (2026-05-11) so the metrics module
+stays under the maintainability config's warn threshold for file
+length — eating our own dogfood on the A+ grade. Not a public API;
+import from ``metrics`` if you need any of these symbols externally.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+FUNC_PATTERNS = [
+    re.compile(r"^\s*def\s+([A-Za-z_][\w]*)\s*\("),
+    re.compile(r"^\s*(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\("),
+    re.compile(r"^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>"),
+    re.compile(r"^\s*(?:export\s+default\s+)?class\s+([A-Za-z_$][\w$]*)\b"),
+]
+
+COMPLEXITY_RE = re.compile(r"\b(if|elif|for|while|except|case|catch)\b|&&|\|\||\?")
+
+
+@dataclass
+class FileMetric:
+    path: str
+    lines: int
+    status: str
+
+
+@dataclass
+class FunctionMetric:
+    path: str
+    name: str
+    start_line: int
+    lines: int
+    complexity: int
+    status: str
+
+
+@dataclass
+class RiskFinding:
+    path: str
+    line: int
+    name: str
+    text: str

maintainability_audit/baseline.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def finding_fingerprints(report: dict[str, Any]) -> set[str]:
+    fingerprints: set[str] = set()
+    for item in report.get("largest_files", []):
+        if item["status"] == "fail":
+            fingerprints.add(f"file-lines:{item['path']}")
+    for item in report.get("function_hotspots", []):
+        if item["status"] == "fail":
+            fingerprints.add(f"function:{item['path']}:{item['name']}:{item['start_line']}")
+    for item in report.get("risk_findings", []):
+        fingerprints.add(f"risk:{item['path']}:{item['line']}:{item['name']}")
+    for item in report.get("duplicate_blocks", []):
+        locations = ",".join(item["locations"][:5])
+        fingerprints.add(f"duplicate:{locations}")
+    return fingerprints
+
+
+def load_baseline(path: str | None) -> set[str]:
+    if not path:
+        return set()
+    baseline_path = Path(path)
+    if not baseline_path.exists():
+        return set()
+    data = json.loads(baseline_path.read_text(encoding="utf-8"))
+    return set(data.get("findings", []))
+
+
+def write_baseline(path: str, report: dict[str, Any]) -> None:
+    data = {
+        "version": 1,
+        "root": report["root"],
+        "score": report.get("score", {}),
+        "findings": sorted(finding_fingerprints(report)),
+    }
+    Path(path).write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")

maintainability_audit/cli.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .baseline import finding_fingerprints, load_baseline, write_baseline
+from .config import DEFAULT_CONFIG, VERSION, load_config
+from .git_tools import changed_paths
+from .instructions import instruction_path_for_target, write_instruction_pack
+from .metrics import build_report
+from .renderers import (
+    render_agent_instructions,
+    render_ai_prompt,
+    render_markdown,
+    render_pr_comment,
+)
+from .sarif import read_sarif_inputs, report_to_sarif
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--version", action="version", version=f"maintainability-agent {VERSION}")
+    parser.add_argument("--root", default=".", help="Repository root to scan.")
+    parser.add_argument("--config", help="Path to JSON config.")
+    parser.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    parser.add_argument("--output", help="Output file. Defaults to stdout.")
+    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("--sarif-output", help="Optional SARIF output path for GitHub code scanning.")
+    parser.add_argument("--sarif-input", action="append", help="Optional external SARIF file to summarize in reports. Repeatable.")
+    parser.add_argument("--changed-only", help="Audit only files changed in a git revspec, for example main...HEAD.")
+    parser.add_argument("--baseline", help="Existing baseline JSON. With --fail-on-new, only new findings fail.")
+    parser.add_argument("--write-baseline", help="Write current findings to a baseline JSON file.")
+    parser.add_argument("--fail-on-new", action="store_true", help="Fail only when findings are not in --baseline.")
+    parser.add_argument("--fail-on-gate", action="store_true", help="Exit 1 when hard gates fail.")
+    parser.add_argument("--init-agent-standards", action="store_true", help="Write model/tool-specific instruction files and exit.")
+    parser.add_argument(
+        "--target",
+        action="append",
+        choices=["generic", "claude-code", "codex", "cursor", "copilot", "windsurf"],
+        help="Instruction target. Repeatable. Used with --init-agent-standards.",
+    )
+    parser.add_argument("--instructions-output-dir", default=".", help="Directory for generated instruction files.")
+
+
+def write_outputs(args: argparse.Namespace, report: dict, rendered: str) -> None:
+    if args.output:
+        Path(args.output).write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+    if args.prompt_output:
+        Path(args.prompt_output).write_text(render_ai_prompt(report) + "\n", encoding="utf-8")
+    if args.comment_output:
+        Path(args.comment_output).write_text(render_pr_comment(report) + "\n", encoding="utf-8")
+    if args.agent_instructions_output:
+        Path(args.agent_instructions_output).write_text(render_agent_instructions(report) + "\n", encoding="utf-8")
+    if args.write_baseline:
+        write_baseline(args.write_baseline, report)
+    if args.sarif_output:
+        Path(args.sarif_output).write_text(json.dumps(report_to_sarif(report), indent=2) + "\n", encoding="utf-8")
+
+
+def audit_exit_code(args: argparse.Namespace, report: dict) -> int:
+    if args.fail_on_new:
+        baseline = load_baseline(args.baseline)
+        if finding_fingerprints(report) - baseline:
+            return 1
+    if args.fail_on_gate and report["hard_gate_failures"]:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    add_arguments(parser)
+    args = parser.parse_args(argv)
+
+    root = Path(args.root).resolve()
+    config = load_config(args.config)
+    if args.init_agent_standards:
+        targets = args.target or ["generic", "claude-code", "codex", "cursor", "copilot", "windsurf"]
+        write_instruction_pack(targets, Path(args.instructions_output_dir).resolve(), config)
+        return 0
+
+    only_paths = changed_paths(root, args.changed_only) if args.changed_only else None
+    external_findings = read_sarif_inputs(args.sarif_input)
+    report = build_report(root, config, only_paths=only_paths, changed_revspec=args.changed_only, external_findings=external_findings)
+    rendered = json.dumps(report, indent=2, sort_keys=True) if args.format == "json" else render_markdown(report)
+    write_outputs(args, report, rendered)
+    return audit_exit_code(args, report)
+
+
+__all__ = [
+    "add_arguments",
+    "audit_exit_code",
+    "build_report",
+    "changed_paths",
+    "DEFAULT_CONFIG",
+    "finding_fingerprints",
+    "instruction_path_for_target",
+    "load_baseline",
+    "load_config",
+    "main",
+    "read_sarif_inputs",
+    "report_to_sarif",
+]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

maintainability_audit/config.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+VERSION = "0.1.0"
+
+PROJECT_URL = "https://github.com/marshallguillory86/maintainability-agent"
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "paths": {
+        "include_extensions": [".py", ".js", ".jsx", ".ts", ".tsx", ".html", ".css", ".md"],
+        "exclude_patterns": [
+            ".git/",
+            "node_modules/",
+            ".venv/",
+            "venv/",
+            "dist/",
+            "build/",
+            "coverage/",
+            "__pycache__/",
+            "maintainability-baseline.json",
+            "maintainability-report.md",
+            "maintainability-remediation-prompt.md",
+            "maintainability-pr-comment.md",
+            "maintainability.sarif",
+        ],
+    },
+    "thresholds": {
+        "max_file_lines": 800,
+        "warn_file_lines": 400,
+        "max_function_lines": 80,
+        "warn_function_lines": 50,
+        "max_complexity": 15,
+        "warn_complexity": 10,
+        "max_duplicate_blocks": 20,
+        "duplicate_block_lines": 8,
+    },
+    "hard_gates": {
+        "require_test_command": False,
+        "require_readme": True,
+        "require_clean_worktree": False,
+    },
+    "expected_files": ["README.md"],
+    "expected_commands": {"test": [], "lint": []},
+    "risk_patterns": [
+        {
+            "name": "debt-marker",
+            "pattern": r"\b(TODO|FIXME|HACK)\b",
+            "extensions": [".py", ".js", ".jsx", ".ts", ".tsx", ".html", ".css", ".md"],
+        }
+    ],
+    "instruction_pack": {
+        "project_name": "this repository",
+        "strictness": "high",
+        "test_policy": "tests for meaningful behavior changes",
+        "architecture_notes": [],
+    },
+}
+
+
+def deep_update(base: dict[str, Any], override: dict[str, Any]) -> None:
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(base.get(key), dict):
+            deep_update(base[key], value)
+        else:
+            base[key] = value
+
+
+def load_config(path: str | None) -> dict[str, Any]:
+    config = json.loads(json.dumps(DEFAULT_CONFIG))
+    if not path:
+        return config
+    user_config = json.loads(Path(path).read_text(encoding="utf-8"))
+    deep_update(config, user_config)
+    return config

maintainability_audit/git_tools.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def run_git(args: list[str], cwd: Path) -> str:
+    try:
+        return subprocess.check_output(["git", *args], cwd=cwd, text=True, stderr=subprocess.DEVNULL).strip()
+    except Exception:
+        return ""
+
+
+def changed_paths(root: Path, revspec: str) -> set[str]:
+    output = run_git(["diff", "--name-only", revspec], root)
+    if not output:
+        return set()
+    return {line.strip().replace(os.sep, "/") for line in output.splitlines() if line.strip()}