Skip to content
This repository was archived by the owner on Apr 27, 2026. It is now read-only.

Commit 0cc312d

Browse files
aptratcnaptratcn
committed
v1.0.0: Interactive codebase health audit — 8 dimensions, zero dependencies
- 8-dimension scoring: Architecture, Security, Performance, Maintainability, Testing, Documentation, Dependencies, Code Quality - Interactive audit flow with contextual questions - ASCII scorecard with severity breakdown - Security scan: hardcoded secrets, SQL injection, XSS, auth gaps - Performance flags: N+1 queries, memory leaks, blocking calls - Tech debt detection: dead code, TODO density, god classes - CI integration: GitHub Actions workflow generation - Zero dependencies — runs as an AI agent skill
0 parents  commit 0cc312d

4 files changed

Lines changed: 638 additions & 0 deletions

File tree

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: aptratcn

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 aptratcn
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.

‎README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Skill Code Audit — Interactive codebase health audit. 8 dimensions. Zero dependencies.
2+
3+
```
4+
╔══════════════════════════════════════════════════════════════╗
5+
║ CODEBASE HEALTH REPORT ║
6+
╠══════════════════════════════════════════════════════════════╣
7+
║ Project: my-awesome-app Lines: 12,847 ║
8+
║ Language: TypeScript Files: 247 ║
9+
╠══════════════════════════════════════════════════════════════╣
10+
║ ║
11+
║ OVERALL HEALTH: 72/100 ████████████░░░░ GOOD ║
12+
║ ║
13+
║ Architecture 78/100 ████████████░░░ GOOD ║
14+
║ Security 45/100 ██████░░░░░░░░░░ NEEDS WORK ║
15+
║ Performance 82/100 █████████████░░░ GOOD ║
16+
║ Maintainability 65/100 █████████░░░░░░░ MODERATE ║
17+
║ Testing 55/100 ████████░░░░░░░░ MODERATE ║
18+
║ Documentation 90/100 ████████████████ EXCELLENT ║
19+
║ Dependencies 70/100 ███████████░░░░░ GOOD ║
20+
║ Code Quality 85/100 █████████████░░░ GOOD ║
21+
║ ║
22+
║ 🔴 Critical: 2 🟠 High: 5 🟡 Medium: 12 🟢 Low: 23 ║
23+
╚══════════════════════════════════════════════════════════════╝
24+
```
25+
26+
## Why This Exists
27+
28+
Linters find syntax errors. This skill finds **architectural rot, security holes, performance traps, and tech debt** — the stuff that kills projects slowly.
29+
30+
Code health isn't just "no lint errors." It's: *Can a new developer understand this code? Are we one dependency update from a security breach? Will this architecture survive the next feature request?*
31+
32+
## Before → After
33+
34+
### Before (what linters see)
35+
36+
```
37+
✓ No syntax errors
38+
✓ All imports resolved
39+
✓ Prettier formatted
40+
→ "Looks good!" 🤷
41+
```
42+
43+
### After (what Code Audit finds)
44+
45+
```
46+
🔴 CRITICAL: Hardcoded Stripe key in config.ts:47
47+
🔴 CRITICAL: SQL injection in users.ts:123
48+
🟠 HIGH: N+1 query in orders.ts:89 (10x slower under load)
49+
🟠 HIGH: 14 packages outdated, 3 with known CVEs
50+
🟡 MEDIUM: God class UserService.ts (847 lines, 23 methods)
51+
🟡 MEDIUM: No tests for payment module (handles money!)
52+
🟢 LOW: 47 TODOs across codebase, oldest from 2022
53+
```
54+
55+
## Quick Start
56+
57+
### 1. Install the skill
58+
59+
```bash
60+
# Via ClawHub
61+
clawhub install skill-code-audit
62+
63+
# Or clone directly
64+
git clone https://github.com/aptratcn/skill-code-audit.git
65+
```
66+
67+
### 2. Run an audit
68+
69+
Just tell your AI agent:
70+
71+
```
72+
"audit this codebase"
73+
"health check my project"
74+
"find tech debt in src/"
75+
```
76+
77+
### 3. Example output
78+
79+
```
80+
🔍 Scanning project...
81+
82+
📁 Detected: Node.js / TypeScript
83+
📊 247 source files, 45 test files, 12,847 LOC
84+
85+
Quick questions before I dive deep:
86+
1. Production app or internal tool?
87+
2. Any specific concerns?
88+
3. Timeline for fixes?
89+
90+
> Production app, security is top priority, sprint next week
91+
92+
Got it. Security-first with sprint-ready action items.
93+
94+
🚨 Found 2 critical security issues:
95+
• Hardcoded API key in config.ts:47
96+
• SQL injection in users.ts:123
97+
98+
⚡ Top performance bottleneck:
99+
• N+1 query in orders.ts — 10x overhead under load
100+
101+
📊 Full scorecard generated. Overall: 72/100
102+
Security needs immediate attention: 45/100
103+
104+
Sprint-ready fixes (estimated 5h total):
105+
1. Move secrets to env vars (2h) — blocks deployment
106+
2. Parameterize SQL queries (1h) — data breach risk
107+
3. Batch order queries (1.5h) — 10x perf improvement
108+
4. Update vulnerable packages (0.5h) — 3 CVEs patched
109+
110+
Create fix branch? → Yes → PR ready with all 4 fixes
111+
```
112+
113+
## The 8 Dimensions
114+
115+
| # | Dimension | Weight | What It Measures |
116+
|---|-----------|--------|-----------------|
117+
| 1 | **Architecture** | 15% | Pattern detection (MVC, microservices, monolith), coupling, cohesion, dependency direction |
118+
| 2 | **Security** | 20% | Hardcoded secrets, SQL injection, XSS, auth gaps, known CVEs |
119+
| 3 | **Performance** | 12% | N+1 queries, memory leaks, missing indexes, blocking calls |
120+
| 4 | **Maintainability** | 15% | Complexity metrics, dead code, TODO density, god classes |
121+
| 5 | **Testing** | 12% | Coverage gaps, test quality, missing critical tests |
122+
| 6 | **Documentation** | 8% | README quality, API docs, inline comments, ADRs |
123+
| 7 | **Dependencies** | 10% | Outdated packages, license conflicts, supply chain risks |
124+
| 8 | **Code Quality** | 8% | Naming, style consistency, error handling, code smells |
125+
126+
### Scoring Criteria
127+
128+
Each dimension scores 0-100:
129+
130+
| Score | Rating | Meaning |
131+
|-------|--------|---------|
132+
| 90-100 | 🟢 EXCELLENT | Production-ready, no concerns |
133+
| 70-89 | 🟢 GOOD | Minor issues, low risk |
134+
| 50-69 | 🟡 MODERATE | Noticeable debt, plan remediation |
135+
| 30-49 | 🟠 NEEDS WORK | Significant issues, prioritize fixes |
136+
| 0-29 | 🔴 CRITICAL | Urgent action required |
137+
138+
## Code Audit vs Linters
139+
140+
| Feature | Linters (ESLint, etc.) | Code Audit |
141+
|---------|----------------------|------------|
142+
| Syntax errors | ✅ | ✅ |
143+
| Style violations | ✅ | ✅ |
144+
| Security vulnerabilities | ⚠️ (some rules) | ✅ Deep scan |
145+
| Architecture analysis | ❌ | ✅ Pattern detection |
146+
| Performance issues | ❌ | ✅ N+1, memory, blocking |
147+
| Tech debt quantification | ❌ | ✅ Scored & prioritized |
148+
| Interactive Q&A | ❌ | ✅ Contextual follow-ups |
149+
| Prioritized fix plan | ❌ | ✅ Impact-based ordering |
150+
| CI integration | ⚠️ (fail/pass) | ✅ Detailed report |
151+
152+
**Think of it this way:** Linters are spell check. Code Audit is a full editorial review.
153+
154+
## Interactive Features
155+
156+
- **Ask questions** — The audit adapts to your project type and priorities
157+
- **Deep dive** — Focus on specific dimensions or modules
158+
- **Sprint-ready fixes** — Prioritized by impact, estimated by effort
159+
- **CI integration** — Generate GitHub Actions workflow for ongoing audits
160+
161+
## Tech Stack Support
162+
163+
Works with any codebase. Special detection for:
164+
165+
- **JavaScript/TypeScript** — Node.js, React, Next.js, Vue, Express
166+
- **Python** — Django, Flask, FastAPI
167+
- **Go** — Standard layout, microservices
168+
- **Rust** — Cargo projects
169+
- **Java** — Spring Boot, Maven/Gradle
170+
- **Ruby** — Rails, Sinatra
171+
- **PHP** — Laravel, Symfony
172+
173+
## License
174+
175+
MIT License — use it however you want.
176+
177+
---
178+
179+
**Made for AI agents. By AI agents.** 🤖

0 commit comments

Comments
 (0)