maintainability-agent 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- maintainability_agent-0.1.0/LICENSE +21 -0
- maintainability_agent-0.1.0/PKG-INFO +260 -0
- maintainability_agent-0.1.0/README.md +231 -0
- maintainability_agent-0.1.0/pyproject.toml +67 -0
- maintainability_agent-0.1.0/setup.cfg +4 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/PKG-INFO +260 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/SOURCES.txt +25 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/dependency_links.txt +1 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/entry_points.txt +3 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/requires.txt +12 -0
- maintainability_agent-0.1.0/src/maintainability_agent.egg-info/top_level.txt +1 -0
- maintainability_agent-0.1.0/src/maintainability_audit/__init__.py +3 -0
- maintainability_agent-0.1.0/src/maintainability_audit/__main__.py +4 -0
- maintainability_agent-0.1.0/src/maintainability_audit/_metrics_types.py +45 -0
- maintainability_agent-0.1.0/src/maintainability_audit/baseline.py +41 -0
- maintainability_agent-0.1.0/src/maintainability_audit/cli.py +112 -0
- maintainability_agent-0.1.0/src/maintainability_audit/config.py +77 -0
- maintainability_agent-0.1.0/src/maintainability_audit/git_tools.py +19 -0
- maintainability_agent-0.1.0/src/maintainability_audit/instructions.py +88 -0
- maintainability_agent-0.1.0/src/maintainability_audit/metrics.py +249 -0
- maintainability_agent-0.1.0/src/maintainability_audit/renderers.py +246 -0
- maintainability_agent-0.1.0/src/maintainability_audit/sarif.py +150 -0
- maintainability_agent-0.1.0/src/maintainability_audit/scoring.py +47 -0
- maintainability_agent-0.1.0/tests/test_audit_components.py +177 -0
- maintainability_agent-0.1.0/tests/test_cli.py +216 -0
- maintainability_agent-0.1.0/tests/test_sarif.py +133 -0
- maintainability_agent-0.1.0/tests/test_schema_fidelity.py +47 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Marshall Guillory
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: maintainability-agent
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Maintainability gate and AI remediation prompt generator for CI.
|
|
5
|
+
Author: Marshall Guillory
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: maintainability,ci,audit,quality,iso-25010,ai-code-review
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Provides-Extra: test
|
|
19
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
20
|
+
Requires-Dist: pytest-cov>=5; extra == "test"
|
|
21
|
+
Requires-Dist: jsonschema>=4; extra == "test"
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
24
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
25
|
+
Requires-Dist: jsonschema>=4; extra == "dev"
|
|
26
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
27
|
+
Requires-Dist: pip-audit>=2.7; extra == "dev"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# Maintainability Agent
|
|
31
|
+
|
|
32
|
+
A deterministic CI gate + bounded remediation prompt generator for repos that use AI coding agents (Claude, Codex, Cursor, Copilot, Windsurf, …).
|
|
33
|
+
|
|
34
|
+
## Why this exists
|
|
35
|
+
|
|
36
|
+
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."*
|
|
37
|
+
|
|
38
|
+
That's the point of this tool:
|
|
39
|
+
|
|
40
|
+
1. Run a deterministic local audit — file size, function size, approximate cyclomatic complexity, duplication, configurable risk patterns, ISO/IEC 25010-inspired 0–5 score.
|
|
41
|
+
2. Emit Markdown, JSON, SARIF, a PR comment, and a baseline for incremental adoption.
|
|
42
|
+
3. Generate an **AI remediation prompt scoped to the actual findings** — bounded, with explicit "don't rewrite the codebase" rules.
|
|
43
|
+
4. Hand that prompt to your agent. Get a small, reviewable fix instead of a 600-line speculative cleanup PR.
|
|
44
|
+
|
|
45
|
+
The remediation prompt is the differentiator. Every other tool in this space stops at "here's a list of findings."
|
|
46
|
+
|
|
47
|
+
## Who it's for
|
|
48
|
+
|
|
49
|
+
- 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.
|
|
50
|
+
- Repos that want a maintainability gate without paying for SonarQube / CodeClimate / Qlty or sending code to a third party.
|
|
51
|
+
- Solo devs who want a single-binary deterministic audit they can pin in a Makefile, a pre-commit, or a local CI script.
|
|
52
|
+
|
|
53
|
+
## Design principles
|
|
54
|
+
|
|
55
|
+
- **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.
|
|
56
|
+
- **Bounded scope.** The remediation prompt explicitly tells the agent to fix the listed findings only — not to embark on architecture cleanup.
|
|
57
|
+
- **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.
|
|
58
|
+
- **Pass-the-cost-of-disclosure.** A finding that's "just a warning" never blocks CI alone. Hard gates are configurable + opt-in.
|
|
59
|
+
|
|
60
|
+
See [docs/philosophy.md](docs/philosophy.md) for the longer version.
|
|
61
|
+
|
|
62
|
+
## Self-Audit
|
|
63
|
+
|
|
64
|
+
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):
|
|
65
|
+
|
|
66
|
+
| Metric | Value |
|
|
67
|
+
|---|---:|
|
|
68
|
+
| Overall score | **5.0 / 5 (A+)** |
|
|
69
|
+
| File warnings | 0 |
|
|
70
|
+
| Function warnings | 0 |
|
|
71
|
+
| Duplicate blocks | 0 |
|
|
72
|
+
| Risk findings | 0 |
|
|
73
|
+
| Hard gate failures | 0 |
|
|
74
|
+
|
|
75
|
+
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).
|
|
76
|
+
|
|
77
|
+
## Install
|
|
78
|
+
|
|
79
|
+
Run directly from source:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
python3 -m maintainability_audit \
|
|
83
|
+
--root . \
|
|
84
|
+
--config maintainability-agent.json \
|
|
85
|
+
--output maintainability-report.md
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Or install editable during development:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
python3 -m pip install -e .
|
|
92
|
+
maintainability-audit --root . --config maintainability-agent.json
|
|
93
|
+
maintainability-agent --root . --config maintainability-agent.json
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Quick Start
|
|
97
|
+
|
|
98
|
+
Copy the example config to your repo root as `maintainability-agent.json`:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
cp maintainability-audit.example.json maintainability-agent.json
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Run:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
maintainability-agent \
|
|
108
|
+
--config maintainability-agent.json \
|
|
109
|
+
--format markdown \
|
|
110
|
+
--output maintainability-report.md
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Fail CI on hard gates:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
maintainability-agent \
|
|
117
|
+
--config maintainability-agent.json \
|
|
118
|
+
--fail-on-gate \
|
|
119
|
+
--output maintainability-report.md \
|
|
120
|
+
--prompt-output maintainability-remediation-prompt.md \
|
|
121
|
+
--comment-output maintainability-pr-comment.md
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## What It Analyzes
|
|
125
|
+
|
|
126
|
+
The deterministic scanner reads code from your repo (no LLM calls) and produces signals on:
|
|
127
|
+
|
|
128
|
+
- largest files (warn / fail thresholds configurable per-repo)
|
|
129
|
+
- approximate function/class size
|
|
130
|
+
- approximate cyclomatic complexity
|
|
131
|
+
- duplicate blocks (≥ N consecutive non-trivial lines, configurable)
|
|
132
|
+
- configurable risk patterns (regex matchers — TODO/FIXME, `eval(`, `exec(`, custom)
|
|
133
|
+
- expected files present (README, LICENSE, etc. — opt-in hard gate)
|
|
134
|
+
- expected test/lint commands declared in the config (opt-in hard gate)
|
|
135
|
+
- worktree-clean state at audit time (opt-in hard gate)
|
|
136
|
+
- ISO/IEC 25010-inspired 0–5 score per category + overall letter grade
|
|
137
|
+
|
|
138
|
+
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`.
|
|
139
|
+
|
|
140
|
+
## What It Produces
|
|
141
|
+
|
|
142
|
+
Each run can emit any combination of:
|
|
143
|
+
|
|
144
|
+
- `maintainability-report.md` — the full Markdown report with summary, score, hotspots, duplicates, risk findings, external (SARIF) findings.
|
|
145
|
+
- `maintainability-remediation-prompt.md` — bounded AI prompt scoped to the run's findings.
|
|
146
|
+
- `maintainability-pr-comment.md` — short body suitable for a `gh pr comment` post.
|
|
147
|
+
- `maintainability.sarif` — SARIF 2.1.0 output for GitHub Code Scanning ingestion.
|
|
148
|
+
- `maintainability-baseline.json` — fingerprints of current findings, for `--fail-on-new` incremental adoption.
|
|
149
|
+
- 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`.
|
|
150
|
+
|
|
151
|
+
## AI Remediation Prompt
|
|
152
|
+
|
|
153
|
+
The runner can generate a bounded prompt for a human developer to give to Claude, Codex, or another coding assistant:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
maintainability-agent \
|
|
157
|
+
--config maintainability-agent.json \
|
|
158
|
+
--output maintainability-report.md \
|
|
159
|
+
--prompt-output maintainability-remediation-prompt.md
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The prompt is designed for AI-written or AI-assisted code reviews. It tells the assistant to:
|
|
163
|
+
|
|
164
|
+
- fix only the highest-value maintainability issues
|
|
165
|
+
- keep the patch small and reviewable
|
|
166
|
+
- preserve existing architecture and behavior
|
|
167
|
+
- add tests where behavior changes
|
|
168
|
+
- report false positives instead of rewriting blindly
|
|
169
|
+
|
|
170
|
+
This makes the CI artifact actionable without letting the audit turn into an unbounded refactor request.
|
|
171
|
+
|
|
172
|
+
## PR and Baseline Workflows
|
|
173
|
+
|
|
174
|
+
PR-only audits, baseline grandfathering, AI-agent instruction
|
|
175
|
+
generation, and reusable agent-standard file generation are covered
|
|
176
|
+
in [PR and Baseline Workflows](docs/pr-and-baseline-workflows.md).
|
|
177
|
+
|
|
178
|
+
## Running Tests
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
# Sandbox-friendly invocation (works with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1):
|
|
182
|
+
PYTHONPATH=src python3 -m pytest
|
|
183
|
+
|
|
184
|
+
# With coverage gate (matches CI):
|
|
185
|
+
PYTHONPATH=src python3 -m pytest \
|
|
186
|
+
--cov=maintainability_audit --cov-fail-under=92
|
|
187
|
+
|
|
188
|
+
# With ruff lint + pip-audit (matches CI):
|
|
189
|
+
python3 -m pip install -e ".[dev]"
|
|
190
|
+
ruff check src tests
|
|
191
|
+
pip-audit
|
|
192
|
+
PYTHONPATH=src python3 -m pytest --cov=maintainability_audit --cov-fail-under=92
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Coverage is intentionally NOT in `[tool.pytest.ini_options].addopts` so the
|
|
196
|
+
sandbox-friendly invocation (`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`) doesn't choke
|
|
197
|
+
on `--cov` flags it can't load. Pass coverage flags explicitly when you want
|
|
198
|
+
the gate.
|
|
199
|
+
|
|
200
|
+
## Scoring Standard
|
|
201
|
+
|
|
202
|
+
The audit model is based on ISO/IEC 25010 maintainability:
|
|
203
|
+
|
|
204
|
+
- modularity
|
|
205
|
+
- reusability
|
|
206
|
+
- analyzability
|
|
207
|
+
- modifiability
|
|
208
|
+
- testability
|
|
209
|
+
|
|
210
|
+
See [docs/standard.md](docs/standard.md).
|
|
211
|
+
|
|
212
|
+
## Documentation
|
|
213
|
+
|
|
214
|
+
- [CLI reference](docs/cli.md)
|
|
215
|
+
- [Config schema](docs/config-schema.md)
|
|
216
|
+
- [Philosophy](docs/philosophy.md)
|
|
217
|
+
- [Analyzer adapters](docs/adapters.md)
|
|
218
|
+
- [External quality tools](docs/external-quality-tools.md)
|
|
219
|
+
- [IDE and agent integration](docs/ide-agent-integration.md)
|
|
220
|
+
- [PR and baseline workflows](docs/pr-and-baseline-workflows.md)
|
|
221
|
+
- [Roadmap](docs/roadmap.md)
|
|
222
|
+
|
|
223
|
+
## GitHub Action
|
|
224
|
+
|
|
225
|
+
This repo includes `action.yml`, so it can be used as a composite action after publishing:
|
|
226
|
+
|
|
227
|
+
```yaml
|
|
228
|
+
- uses: marshallguillory86/maintainability-agent@v0.1.0
|
|
229
|
+
with:
|
|
230
|
+
config: maintainability-agent.json
|
|
231
|
+
changed-only: main...HEAD
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## GitHub Actions
|
|
235
|
+
|
|
236
|
+
After publishing, copy `.github/workflows/maintainability.yml` into the target repo or adapt it for your local CI.
|
|
237
|
+
|
|
238
|
+
## IDE and Agent Integration
|
|
239
|
+
|
|
240
|
+
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.
|
|
241
|
+
|
|
242
|
+
## Local CI
|
|
243
|
+
|
|
244
|
+
For repos that do not use GitHub Actions, use:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
examples/local-ci.sh
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
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.
|
|
251
|
+
|
|
252
|
+
## Get in Touch
|
|
253
|
+
|
|
254
|
+
- **Bug reports / feature requests / general questions** — open a [GitHub Issue](https://github.com/marshallguillory86/maintainability-agent/issues/new).
|
|
255
|
+
- **Discussion / ideas** — use the [Discussions tab](https://github.com/marshallguillory86/maintainability-agent/discussions) (enable in repo settings if not visible yet).
|
|
256
|
+
- **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.
|
|
257
|
+
|
|
258
|
+
## License
|
|
259
|
+
|
|
260
|
+
MIT
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Maintainability Agent
|
|
2
|
+
|
|
3
|
+
A deterministic CI gate + bounded remediation prompt generator for repos that use AI coding agents (Claude, Codex, Cursor, Copilot, Windsurf, …).
|
|
4
|
+
|
|
5
|
+
## Why this exists
|
|
6
|
+
|
|
7
|
+
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."*
|
|
8
|
+
|
|
9
|
+
That's the point of this tool:
|
|
10
|
+
|
|
11
|
+
1. Run a deterministic local audit — file size, function size, approximate cyclomatic complexity, duplication, configurable risk patterns, ISO/IEC 25010-inspired 0–5 score.
|
|
12
|
+
2. Emit Markdown, JSON, SARIF, a PR comment, and a baseline for incremental adoption.
|
|
13
|
+
3. Generate an **AI remediation prompt scoped to the actual findings** — bounded, with explicit "don't rewrite the codebase" rules.
|
|
14
|
+
4. Hand that prompt to your agent. Get a small, reviewable fix instead of a 600-line speculative cleanup PR.
|
|
15
|
+
|
|
16
|
+
The remediation prompt is the differentiator. Every other tool in this space stops at "here's a list of findings."
|
|
17
|
+
|
|
18
|
+
## Who it's for
|
|
19
|
+
|
|
20
|
+
- 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.
|
|
21
|
+
- Repos that want a maintainability gate without paying for SonarQube / CodeClimate / Qlty or sending code to a third party.
|
|
22
|
+
- Solo devs who want a single-binary deterministic audit they can pin in a Makefile, a pre-commit, or a local CI script.
|
|
23
|
+
|
|
24
|
+
## Design principles
|
|
25
|
+
|
|
26
|
+
- **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.
|
|
27
|
+
- **Bounded scope.** The remediation prompt explicitly tells the agent to fix the listed findings only — not to embark on architecture cleanup.
|
|
28
|
+
- **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.
|
|
29
|
+
- **Pass-the-cost-of-disclosure.** A finding that's "just a warning" never blocks CI alone. Hard gates are configurable + opt-in.
|
|
30
|
+
|
|
31
|
+
See [docs/philosophy.md](docs/philosophy.md) for the longer version.
|
|
32
|
+
|
|
33
|
+
## Self-Audit
|
|
34
|
+
|
|
35
|
+
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):
|
|
36
|
+
|
|
37
|
+
| Metric | Value |
|
|
38
|
+
|---|---:|
|
|
39
|
+
| Overall score | **5.0 / 5 (A+)** |
|
|
40
|
+
| File warnings | 0 |
|
|
41
|
+
| Function warnings | 0 |
|
|
42
|
+
| Duplicate blocks | 0 |
|
|
43
|
+
| Risk findings | 0 |
|
|
44
|
+
| Hard gate failures | 0 |
|
|
45
|
+
|
|
46
|
+
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).
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
Run directly from source:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
python3 -m maintainability_audit \
|
|
54
|
+
--root . \
|
|
55
|
+
--config maintainability-agent.json \
|
|
56
|
+
--output maintainability-report.md
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or install editable during development:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
python3 -m pip install -e .
|
|
63
|
+
maintainability-audit --root . --config maintainability-agent.json
|
|
64
|
+
maintainability-agent --root . --config maintainability-agent.json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
Copy the example config to your repo root as `maintainability-agent.json`:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cp maintainability-audit.example.json maintainability-agent.json
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Run:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
maintainability-agent \
|
|
79
|
+
--config maintainability-agent.json \
|
|
80
|
+
--format markdown \
|
|
81
|
+
--output maintainability-report.md
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Fail CI on hard gates:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
maintainability-agent \
|
|
88
|
+
--config maintainability-agent.json \
|
|
89
|
+
--fail-on-gate \
|
|
90
|
+
--output maintainability-report.md \
|
|
91
|
+
--prompt-output maintainability-remediation-prompt.md \
|
|
92
|
+
--comment-output maintainability-pr-comment.md
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## What It Analyzes
|
|
96
|
+
|
|
97
|
+
The deterministic scanner reads code from your repo (no LLM calls) and produces signals on:
|
|
98
|
+
|
|
99
|
+
- largest files (warn / fail thresholds configurable per-repo)
|
|
100
|
+
- approximate function/class size
|
|
101
|
+
- approximate cyclomatic complexity
|
|
102
|
+
- duplicate blocks (≥ N consecutive non-trivial lines, configurable)
|
|
103
|
+
- configurable risk patterns (regex matchers — TODO/FIXME, `eval(`, `exec(`, custom)
|
|
104
|
+
- expected files present (README, LICENSE, etc. — opt-in hard gate)
|
|
105
|
+
- expected test/lint commands declared in the config (opt-in hard gate)
|
|
106
|
+
- worktree-clean state at audit time (opt-in hard gate)
|
|
107
|
+
- ISO/IEC 25010-inspired 0–5 score per category + overall letter grade
|
|
108
|
+
|
|
109
|
+
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`.
|
|
110
|
+
|
|
111
|
+
## What It Produces
|
|
112
|
+
|
|
113
|
+
Each run can emit any combination of:
|
|
114
|
+
|
|
115
|
+
- `maintainability-report.md` — the full Markdown report with summary, score, hotspots, duplicates, risk findings, external (SARIF) findings.
|
|
116
|
+
- `maintainability-remediation-prompt.md` — bounded AI prompt scoped to the run's findings.
|
|
117
|
+
- `maintainability-pr-comment.md` — short body suitable for a `gh pr comment` post.
|
|
118
|
+
- `maintainability.sarif` — SARIF 2.1.0 output for GitHub Code Scanning ingestion.
|
|
119
|
+
- `maintainability-baseline.json` — fingerprints of current findings, for `--fail-on-new` incremental adoption.
|
|
120
|
+
- 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`.
|
|
121
|
+
|
|
122
|
+
## AI Remediation Prompt
|
|
123
|
+
|
|
124
|
+
The runner can generate a bounded prompt for a human developer to give to Claude, Codex, or another coding assistant:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
maintainability-agent \
|
|
128
|
+
--config maintainability-agent.json \
|
|
129
|
+
--output maintainability-report.md \
|
|
130
|
+
--prompt-output maintainability-remediation-prompt.md
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The prompt is designed for AI-written or AI-assisted code reviews. It tells the assistant to:
|
|
134
|
+
|
|
135
|
+
- fix only the highest-value maintainability issues
|
|
136
|
+
- keep the patch small and reviewable
|
|
137
|
+
- preserve existing architecture and behavior
|
|
138
|
+
- add tests where behavior changes
|
|
139
|
+
- report false positives instead of rewriting blindly
|
|
140
|
+
|
|
141
|
+
This makes the CI artifact actionable without letting the audit turn into an unbounded refactor request.
|
|
142
|
+
|
|
143
|
+
## PR and Baseline Workflows
|
|
144
|
+
|
|
145
|
+
PR-only audits, baseline grandfathering, AI-agent instruction
|
|
146
|
+
generation, and reusable agent-standard file generation are covered
|
|
147
|
+
in [PR and Baseline Workflows](docs/pr-and-baseline-workflows.md).
|
|
148
|
+
|
|
149
|
+
## Running Tests
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
# Sandbox-friendly invocation (works with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1):
|
|
153
|
+
PYTHONPATH=src python3 -m pytest
|
|
154
|
+
|
|
155
|
+
# With coverage gate (matches CI):
|
|
156
|
+
PYTHONPATH=src python3 -m pytest \
|
|
157
|
+
--cov=maintainability_audit --cov-fail-under=92
|
|
158
|
+
|
|
159
|
+
# With ruff lint + pip-audit (matches CI):
|
|
160
|
+
python3 -m pip install -e ".[dev]"
|
|
161
|
+
ruff check src tests
|
|
162
|
+
pip-audit
|
|
163
|
+
PYTHONPATH=src python3 -m pytest --cov=maintainability_audit --cov-fail-under=92
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Coverage is intentionally NOT in `[tool.pytest.ini_options].addopts` so the
|
|
167
|
+
sandbox-friendly invocation (`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`) doesn't choke
|
|
168
|
+
on `--cov` flags it can't load. Pass coverage flags explicitly when you want
|
|
169
|
+
the gate.
|
|
170
|
+
|
|
171
|
+
## Scoring Standard
|
|
172
|
+
|
|
173
|
+
The audit model is based on ISO/IEC 25010 maintainability:
|
|
174
|
+
|
|
175
|
+
- modularity
|
|
176
|
+
- reusability
|
|
177
|
+
- analyzability
|
|
178
|
+
- modifiability
|
|
179
|
+
- testability
|
|
180
|
+
|
|
181
|
+
See [docs/standard.md](docs/standard.md).
|
|
182
|
+
|
|
183
|
+
## Documentation
|
|
184
|
+
|
|
185
|
+
- [CLI reference](docs/cli.md)
|
|
186
|
+
- [Config schema](docs/config-schema.md)
|
|
187
|
+
- [Philosophy](docs/philosophy.md)
|
|
188
|
+
- [Analyzer adapters](docs/adapters.md)
|
|
189
|
+
- [External quality tools](docs/external-quality-tools.md)
|
|
190
|
+
- [IDE and agent integration](docs/ide-agent-integration.md)
|
|
191
|
+
- [PR and baseline workflows](docs/pr-and-baseline-workflows.md)
|
|
192
|
+
- [Roadmap](docs/roadmap.md)
|
|
193
|
+
|
|
194
|
+
## GitHub Action
|
|
195
|
+
|
|
196
|
+
This repo includes `action.yml`, so it can be used as a composite action after publishing:
|
|
197
|
+
|
|
198
|
+
```yaml
|
|
199
|
+
- uses: marshallguillory86/maintainability-agent@v0.1.0
|
|
200
|
+
with:
|
|
201
|
+
config: maintainability-agent.json
|
|
202
|
+
changed-only: main...HEAD
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## GitHub Actions
|
|
206
|
+
|
|
207
|
+
After publishing, copy `.github/workflows/maintainability.yml` into the target repo or adapt it for your local CI.
|
|
208
|
+
|
|
209
|
+
## IDE and Agent Integration
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
|
|
213
|
+
## Local CI
|
|
214
|
+
|
|
215
|
+
For repos that do not use GitHub Actions, use:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
examples/local-ci.sh
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
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.
|
|
222
|
+
|
|
223
|
+
## Get in Touch
|
|
224
|
+
|
|
225
|
+
- **Bug reports / feature requests / general questions** — open a [GitHub Issue](https://github.com/marshallguillory86/maintainability-agent/issues/new).
|
|
226
|
+
- **Discussion / ideas** — use the [Discussions tab](https://github.com/marshallguillory86/maintainability-agent/discussions) (enable in repo settings if not visible yet).
|
|
227
|
+
- **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.
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
MIT
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "maintainability-agent"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Maintainability gate and AI remediation prompt generator for CI."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Marshall Guillory" }
|
|
14
|
+
]
|
|
15
|
+
keywords = ["maintainability", "ci", "audit", "quality", "iso-25010", "ai-code-review"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Environment :: Console",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"License :: OSI Approved :: MIT License",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
23
|
+
"Topic :: Software Development :: Quality Assurance"
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.scripts]
|
|
27
|
+
maintainability-audit = "maintainability_audit.cli:main"
|
|
28
|
+
maintainability-agent = "maintainability_audit.cli:main"
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
test = ["pytest>=8", "pytest-cov>=5", "jsonschema>=4"]
|
|
32
|
+
dev = ["pytest>=8", "pytest-cov>=5", "jsonschema>=4", "ruff>=0.5", "pip-audit>=2.7"]
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|
|
36
|
+
|
|
37
|
+
[tool.pytest.ini_options]
|
|
38
|
+
testpaths = ["tests"]
|
|
39
|
+
# addopts intentionally empty so the sandbox-friendly invocation
|
|
40
|
+
# (`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p no:cacheprovider`) does
|
|
41
|
+
# not choke on `--cov` flags whose plugin couldn't load. Coverage is
|
|
42
|
+
# opt-in: pass `--cov=maintainability_audit --cov-fail-under=92`
|
|
43
|
+
# explicitly (see CONTRIBUTING.md, docs/external-quality-tools.md,
|
|
44
|
+
# and the GH workflow).
|
|
45
|
+
|
|
46
|
+
[tool.coverage.run]
|
|
47
|
+
branch = true
|
|
48
|
+
source = ["maintainability_audit"]
|
|
49
|
+
|
|
50
|
+
[tool.coverage.report]
|
|
51
|
+
fail_under = 92
|
|
52
|
+
show_missing = true
|
|
53
|
+
skip_covered = false
|
|
54
|
+
exclude_also = [
|
|
55
|
+
"if __name__ == .__main__.:",
|
|
56
|
+
"raise SystemExit\\(main\\(\\)\\)"
|
|
57
|
+
]
|
|
58
|
+
|
|
59
|
+
[tool.coverage.xml]
|
|
60
|
+
output = "coverage.xml"
|
|
61
|
+
|
|
62
|
+
[tool.ruff]
|
|
63
|
+
line-length = 140
|
|
64
|
+
target-version = "py311"
|
|
65
|
+
|
|
66
|
+
[tool.ruff.lint]
|
|
67
|
+
select = ["E", "F", "I", "UP", "B", "SIM"]
|