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.
Files changed (27) hide show
  1. maintainability_agent-0.1.0/LICENSE +21 -0
  2. maintainability_agent-0.1.0/PKG-INFO +260 -0
  3. maintainability_agent-0.1.0/README.md +231 -0
  4. maintainability_agent-0.1.0/pyproject.toml +67 -0
  5. maintainability_agent-0.1.0/setup.cfg +4 -0
  6. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/PKG-INFO +260 -0
  7. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/SOURCES.txt +25 -0
  8. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/dependency_links.txt +1 -0
  9. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/entry_points.txt +3 -0
  10. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/requires.txt +12 -0
  11. maintainability_agent-0.1.0/src/maintainability_agent.egg-info/top_level.txt +1 -0
  12. maintainability_agent-0.1.0/src/maintainability_audit/__init__.py +3 -0
  13. maintainability_agent-0.1.0/src/maintainability_audit/__main__.py +4 -0
  14. maintainability_agent-0.1.0/src/maintainability_audit/_metrics_types.py +45 -0
  15. maintainability_agent-0.1.0/src/maintainability_audit/baseline.py +41 -0
  16. maintainability_agent-0.1.0/src/maintainability_audit/cli.py +112 -0
  17. maintainability_agent-0.1.0/src/maintainability_audit/config.py +77 -0
  18. maintainability_agent-0.1.0/src/maintainability_audit/git_tools.py +19 -0
  19. maintainability_agent-0.1.0/src/maintainability_audit/instructions.py +88 -0
  20. maintainability_agent-0.1.0/src/maintainability_audit/metrics.py +249 -0
  21. maintainability_agent-0.1.0/src/maintainability_audit/renderers.py +246 -0
  22. maintainability_agent-0.1.0/src/maintainability_audit/sarif.py +150 -0
  23. maintainability_agent-0.1.0/src/maintainability_audit/scoring.py +47 -0
  24. maintainability_agent-0.1.0/tests/test_audit_components.py +177 -0
  25. maintainability_agent-0.1.0/tests/test_cli.py +216 -0
  26. maintainability_agent-0.1.0/tests/test_sarif.py +133 -0
  27. 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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+