@intentsolutionsio/code-cleanup 1.0.0

package/skills/cleanup-code/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: cleanup-code
+description: |
+  Comprehensive codebase cleanup across 11 quality dimensions: dead code, duplication,
+  weak types, circular deps, defensive cruft, legacy code, AI slop, type consolidation,
+  security, performance, and async patterns. Analyzes code with confidence scoring and
+  verifies changes with build/test gates. Use when codebase has accumulated tech debt,
+  after major feature work, before releases, or when code quality metrics are declining.
+  Trigger with "/cleanup-code-code", "clean up the codebase", "remove dead code", "fix code quality".
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(python3:*), Bash(tsc:*), Bash(wc:*), Bash(ls:*), AskUserQuestion
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [code-quality, cleanup, refactoring, dead-code, deduplication, type-safety, security]
+argument-hint: "[scope] [--dimensions d1,d2,...] [--changed]"
+---
+
+# Codebase Cleanup
+
+Systematic code cleanup across 11 quality dimensions, ordered by risk. Each finding includes
+confidence scoring (HIGH/MEDIUM/LOW) and all changes are verified through build/test gates.
+
+## Environment Detection
+
+!`git rev-parse --show-toplevel 2>/dev/null && echo "---" && git diff --stat HEAD~5 2>/dev/null | tail -5`
+!`ls package.json pyproject.toml Cargo.toml go.mod Makefile 2>/dev/null | head -5`
+!`cat package.json 2>/dev/null | head -3; echo "---"; ls tsconfig.json .eslintrc* 2>/dev/null`
+
+## Prerequisites
+
+- Git repository with clean working tree (no uncommitted changes)
+- Language toolchain installed (Node.js/Python/Go/Rust as applicable)
+- Optional: `knip`, `madge`, `jscpd`, `ruff`, `bandit` for tool-verified scanning
+
+## Overview
+
+This skill orchestrates cleanup across **11 dimensions**, each with a dedicated agent.
+Dimensions are ordered LOW → HIGH risk. See [dimensions reference](references/dimensions.md)
+for full detection criteria, verification steps, and risk profiles.
+
+**The 11 Dimensions** (by risk level):
+
+| # | Dimension | Key | Risk | Auto-apply? |
+|---|-----------|-----|------|-------------|
+| 1 | Dead code removal | `dead` | LOW | Yes (after build) |
+| 2 | AI slop removal | `slop` | LOW | Comments only |
+| 3 | Weak type elimination | `types` | MED | Yes (after typecheck) |
+| 4 | Security cleanup | `security` | MED | Flag only |
+| 5 | Legacy code removal | `legacy` | MED | With confirmation |
+| 6 | Type consolidation | `typecons` | MED | Yes (after typecheck) |
+| 7 | Defensive code cleanup | `defensive` | MED | Flag only |
+| 8 | Performance optimization | `perf` | MED | Flag only |
+| 9 | DRY deduplication | `dry` | HIGH | Flag only (>=10 lines) |
+| 10 | Async pattern fixes | `async` | HIGH | Flag only |
+| 11 | Circular dep untangling | `circular` | HIGH | Flag only |
+
+## Instructions
+
+### Step 1: Safety Checkpoint
+
+Before any changes:
+
+1. Verify clean git state: `git status --porcelain` must be empty (or stash changes)
+2. Record baseline: `git rev-parse HEAD` as rollback point
+3. Run existing tests to confirm green baseline
+4. See [safety protocol](references/safety.md) for revert procedures
+
+### Step 2: Determine Scope
+
+Parse user arguments to set scope:
+
+- **Full codebase** (default): scan all source files
+- **Specific path**: `cleanup src/api/` — limit to directory
+- **Changed files only**: `--changed` flag — `git diff --name-only HEAD~10`
+- **Specific dimensions**: `--dimensions dead,types,security`
+- **Single dimension**: `cleanup --dimensions dry`
+
+Exclude from all scans: `node_modules/`, `dist/`, `build/`, `.git/`, vendor dirs, generated files.
+
+### Step 3: Execute Dimensions
+
+For each selected dimension (in risk order):
+
+1. **Scan** using patterns from [patterns reference](references/patterns.md)
+2. **Score confidence** — HIGH (certain, safe to fix), MEDIUM (likely, needs review), LOW (possible, flag only)
+3. **Apply or flag** based on the dimension's auto-apply policy (see table above)
+4. **Verify** — run build/typecheck/tests after each dimension with auto-apply
+
+Use [tools reference](references/tools.md) for language-specific tool commands (knip, madge, ruff, jscpd, etc.).
+
+### Step 4: Build Verification Gate
+
+After each auto-applied dimension:
+
+```bash
+# TypeScript/JavaScript
+npx tsc --noEmit 2>&1 | tail -20
+npm test 2>&1 | tail -30
+
+# Python
+python3 -m py_compile <changed_files>
+python3 -m pytest --tb=short 2>&1 | tail -30
+
+# General
+git diff --stat  # Show what changed
+```
+
+If verification fails, revert that dimension: `git checkout -- .`
+
+### Step 5: Generate Report
+
+Produce a cleanup report in this format:
+
+```
+## Cleanup Report
+
+**Scope:** [path or "full codebase"]
+**Baseline:** [commit hash]
+**Dimensions:** [list of dimensions run]
+
+### Summary
+| Dimension | Findings | Applied | Flagged | Confidence |
+|-----------|----------|---------|---------|------------|
+| dead      | 12       | 10      | 2       | HIGH       |
+| types     | 8        | 8       | 0       | HIGH       |
+| security  | 3        | 0       | 3       | MEDIUM     |
+
+### Changes Applied
+- [file:line] description of change
+
+### Flagged for Review
+- [file:line] description + reasoning + suggested fix
+
+### Lines Removed: N | Lines Modified: N | Files Touched: N
+```
+
+## Output
+
+A structured cleanup report containing:
+- Summary table with findings per dimension (count, applied, flagged, confidence)
+- List of changes applied with file:line references
+- List of flagged items with reasoning and suggested fixes
+- Stats: lines removed, lines modified, files touched
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Dirty git state | Ask user to commit or stash first |
+| Build fails after cleanup | `git checkout -- .` to revert dimension |
+| No test command found | Skip verification, flag all as "unverified" |
+| Tool not installed | Fall back to grep patterns (see references/patterns.md) |
+| Confidence unclear | Default to flag-only, never auto-apply |
+
+## Examples
+
+**Full cleanup:**
+```
+/cleanup-code
+```
+
+**Security-focused:**
+```
+/cleanup-code --dimensions security,async
+```
+
+**Changed files only:**
+```
+/cleanup-code src/api/ --changed
+```
+
+**Single dimension deep-dive:**
+```
+/cleanup-code --dimensions dead
+```
+
+## Resources
+
+- [All 11 Dimensions](references/dimensions.md) — detection criteria, verification, risk profiles
+- [Tool Reference](references/tools.md) — language-specific cleanup tools
+- [Grep Patterns](references/patterns.md) — detection patterns by dimension
+- [Safety Protocol](references/safety.md) — revert procedures, confidence scoring

package/skills/cleanup-code/references/dimensions.md

@@ -0,0 +1,241 @@
+# Cleanup Dimensions Reference
+
+Complete reference for all 11 cleanup dimensions, ordered by risk level.
+
+---
+
+## 1. Dead Code (Key: `dead` | Risk: LOW)
+
+**What:** Unreachable code, unused exports, unused variables, unused imports, unused functions, dead branches.
+
+**Detection:**
+- Unused exports: `knip` (JS/TS), `vulture` (Python), `deadcode` (Go)
+- Unused variables: compiler warnings, linter output
+- Unreachable code: code after `return`/`throw`/`break`/`continue`
+- Dead feature flags: flags that are always true/false
+
+**Verification:**
+1. Remove candidate
+2. Run `tsc --noEmit` (TS) or equivalent type check
+3. Run test suite
+4. If both pass → confirmed dead code
+
+**Auto-apply:** Yes, after build verification passes.
+
+**False positive signals:** Dynamic imports, reflection, test fixtures, plugin entry points, CLI entry points.
+
+---
+
+## 2. AI Slop (Key: `slop` | Risk: LOW)
+
+**What:** Low-value comments generated by AI assistants — restating obvious code, adding filler.
+
+**Detection patterns:**
+- Comments that restate the next line: `// Set the name` above `name = value`
+- Obvious JSDoc: `@param name - The name` or `@returns The result`
+- Section markers with no value: `// --- Helper Functions ---`
+- Filler phrases: "This function", "This method", "This class", "As mentioned above"
+- Over-documentation of trivial code
+
+**Verification:** Read the comment and the code it describes. If removing the comment loses zero information, it's slop.
+
+**Auto-apply:** Comments only — remove slop comments. Never modify actual code in this dimension.
+
+**False positive signals:** Comments explaining *why* (business logic, workarounds, TODOs with context), JSDoc on public APIs.
+
+---
+
+## 3. Weak Types (Key: `types` | Risk: MEDIUM)
+
+**What:** `any`, `unknown` used unnecessarily, missing return types, implicit any, overly broad generics.
+
+**Detection:**
+- TypeScript: `any` type annotations, missing return types on exported functions
+- Python: missing type hints on public functions, `Any` imports from typing
+- Untyped function parameters in public APIs
+
+**Verification:**
+1. Replace `any` with specific type
+2. Run `tsc --noEmit` — must compile without new errors
+3. Run tests
+
+**Auto-apply:** Yes, when the correct type is unambiguous (inferred from usage). Flag when ambiguous.
+
+**False positive signals:** Intentional `any` for serialization boundaries, third-party type gaps, `unknown` in catch blocks (correct usage).
+
+---
+
+## 4. Security (Key: `security` | Risk: MEDIUM)
+
+**What:** Hardcoded secrets, weak crypto, SQL injection vectors, command injection, path traversal, insecure defaults.
+
+**Detection categories:**
+
+| Category | Patterns |
+|----------|----------|
+| Hardcoded secrets | API keys, tokens, passwords in source code |
+| Weak crypto | MD5, SHA1 for security purposes, `Math.random()` for tokens |
+| SQL injection | String concatenation in SQL queries |
+| Command injection | Unsanitized input in `exec()`, `spawn()`, shell commands |
+| Path traversal | Unsanitized `../` in file paths |
+| Insecure defaults | HTTP instead of HTTPS, disabled TLS verification |
+
+**Verification:** Manual review required — security findings are NEVER auto-applied.
+
+**Auto-apply:** NEVER. Flag all findings with severity (CRITICAL/HIGH/MEDIUM/LOW) and suggested fix.
+
+**False positive signals:** Test fixtures, example code in docs, intentionally disabled security in dev mode.
+
+---
+
+## 5. Legacy Code (Key: `legacy` | Risk: MEDIUM)
+
+**What:** Deprecated API usage, old syntax patterns, compatibility shims for dropped platforms, polyfills for supported targets.
+
+**Detection:**
+- Deprecated Node.js APIs (`fs.exists`, `url.parse`, `new Buffer()`)
+- Old JS patterns (`var`, `arguments` object, `prototype` instead of class)
+- Unnecessary polyfills based on browserslist/engines config
+- Compatibility code for unsupported environments
+
+**Verification:**
+1. Replace with modern equivalent
+2. Check minimum platform target (engines, browserslist)
+3. Run tests
+
+**Auto-apply:** Yes, with confirmation prompt for each batch.
+
+**False positive signals:** Intentional backward compatibility, library code that must support older runtimes.
+
+---
+
+## 6. Type Consolidation (Key: `typecons` | Risk: MEDIUM)
+
+**What:** Duplicate type definitions, inconsistent interfaces, types that should be derived/shared.
+
+**Detection:**
+- Multiple interfaces with >80% field overlap
+- Same type defined in multiple files
+- Types that could use `Pick<>`, `Omit<>`, `Partial<>` instead of duplication
+- Enum values duplicated as string literals elsewhere
+
+**Verification:**
+1. Consolidate to single source
+2. Update all imports
+3. Run `tsc --noEmit` + tests
+
+**Auto-apply:** Yes, after typecheck passes.
+
+**False positive signals:** Types that are intentionally separate (different domains), API boundary types that mirror but shouldn't depend on internal types.
+
+---
+
+## 7. Defensive Code (Key: `defensive` | Risk: MEDIUM)
+
+**What:** Unnecessary null checks, impossible error handling, redundant validation, dead catch blocks.
+
+**Detection:**
+- Null checks on values that are never null (check upstream guarantees)
+- Try/catch around code that cannot throw
+- Validation of internal function parameters (not at system boundary)
+- Default values for required parameters
+- `typeof x !== 'undefined'` checks in module scope
+
+**Verification:** Trace data flow to confirm the defensive check is unnecessary. Read callers and type definitions.
+
+**Auto-apply:** Flag only. Show reasoning for why the check is unnecessary.
+
+**False positive signals:** Legitimate boundary validation, checks that guard against runtime data (API responses, user input), platform-specific guards.
+
+---
+
+## 8. Performance (Key: `perf` | Risk: MEDIUM)
+
+**What:** N+1 queries, blocking I/O in async contexts, bundle bloat, unnecessary re-renders, inefficient algorithms.
+
+**Detection categories:**
+
+| Category | Patterns |
+|----------|----------|
+| N+1 queries | Loop containing DB/API call |
+| Blocking I/O | `fs.readFileSync` in request handlers, synchronous HTTP |
+| Bundle bloat | Full library import when tree-shakeable (`import lodash` vs `import map from 'lodash/map'`) |
+| Re-renders | Missing `useMemo`/`useCallback` on expensive ops, object literals in JSX props |
+| Inefficient algorithms | Nested loops on large datasets, repeated array scans |
+
+**Verification:** Performance changes require benchmarking or profile evidence.
+
+**Auto-apply:** Flag only. Provide suggested fix and estimated impact.
+
+**False positive signals:** One-time startup code, build scripts, code paths that handle small datasets, intentional eager loading.
+
+---
+
+## 9. DRY Deduplication (Key: `dry` | Risk: HIGH)
+
+**What:** Copy-pasted code blocks, duplicated logic across files, repeated patterns that should be abstracted.
+
+**Detection:**
+- `jscpd` tool for exact/near-duplicate detection
+- Manual scan for functions with identical structure but different names
+- Threshold: **>=10 identical lines** before flagging
+
+**Verification:** Ensure the duplicated code truly serves the same purpose. Sometimes identical code has different *reasons* to change.
+
+**Auto-apply:** NEVER for code. Flag only, with suggested extraction.
+
+**Important:** Three similar lines is NOT duplication. Only flag when extraction genuinely reduces maintenance burden. Premature abstraction is worse than duplication.
+
+**False positive signals:** Test setup code (intentionally duplicated for isolation), similar but semantically different operations, code that will diverge.
+
+---
+
+## 10. Async Patterns (Key: `async` | Risk: HIGH)
+
+**What:** Floating promises, `async` in `forEach`, missing `await`, unhandled rejections, race conditions.
+
+**Detection:**
+
+| Pattern | Problem |
+|---------|---------|
+| `array.forEach(async ...)` | Promises float, no error handling |
+| Missing `await` | Promise returned but not awaited |
+| `async` function with no `await` | Unnecessary async wrapper |
+| `.then()` mixed with `await` | Inconsistent patterns, harder to debug |
+| Missing `.catch()` on fire-and-forget | Unhandled rejection |
+| `Promise.all` without error strategy | One failure kills all |
+
+**Verification:**
+1. Confirm the async pattern is actually incorrect (not intentional fire-and-forget)
+2. Apply fix
+3. Run tests — async bugs often only surface under load
+
+**Auto-apply:** NEVER. Flag with explanation of the specific risk.
+
+**False positive signals:** Intentional fire-and-forget with error logging, event emitters, streaming patterns where floating is expected.
+
+---
+
+## 11. Circular Dependencies (Key: `circular` | Risk: HIGH)
+
+**What:** Module A imports B which imports A, creating initialization order issues, bundle bloat, and test difficulty.
+
+**Detection:**
+- `madge --circular` (JS/TS)
+- `dependency-cruiser` (JS/TS, configurable)
+- Import graph analysis
+
+**Resolution strategies:**
+1. **Extract shared types** to a separate module
+2. **Dependency inversion** — depend on interfaces, not implementations
+3. **Lazy imports** — dynamic `import()` to break cycles
+4. **Barrel file restructuring** — split index.ts re-exports
+
+**Verification:**
+1. Run `madge --circular` — should show fewer cycles
+2. Run full test suite
+3. Check bundle size hasn't increased
+
+**Auto-apply:** NEVER. Flag with dependency graph and suggested resolution strategy.
+
+**False positive signals:** Circular type-only imports (no runtime impact in TS), monorepo cross-references that are resolved by bundler.

package/skills/cleanup-code/references/patterns.md

@@ -0,0 +1,195 @@
+# Grep Patterns by Dimension
+
+Fallback detection patterns when dedicated tools aren't installed. Use with `Grep` tool or `rg`.
+
+---
+
+## Dead Code
+
+```bash
+# Unused imports (JS/TS) — imported but never referenced
+rg "^import .+ from " --type ts -l  # Get all files with imports, then cross-reference
+
+# Unreachable code after return/throw
+rg "^\s*(return|throw)\b" -A 2 --type ts  # Look for code after return/throw
+
+# Commented-out code blocks (>3 lines)
+rg "^\s*//" --type ts -c | sort -t: -k2 -rn | head -20  # Files with most comments
+
+# TODO/FIXME/HACK markers (potential dead code indicators)
+rg "(TODO|FIXME|HACK|XXX|DEPRECATED)" --type-add 'src:*.{ts,js,py,go,rs}' --type src
+
+# Empty catch blocks
+rg "catch\s*\([^)]*\)\s*\{\s*\}" --type ts
+
+# Unused function parameters (starts with _)
+rg "function\s+\w+\([^)]*_\w+" --type ts
+```
+
+## AI Slop
+
+```bash
+# Restating comments: "// Set X" or "// Get X" or "// Return X"
+rg "//\s*(Set|Get|Return|Create|Initialize|Define|Check|Update|Delete|Remove)\s+(the\s+)?\w+" --type ts
+
+# Obvious JSDoc
+rg "@param\s+\w+\s*-?\s*(The|A|An)\s+\w+$" --type ts
+rg "@returns?\s*(The|A|An)\s+\w+$" --type ts
+
+# Filler section markers
+rg "//\s*-{3,}.*-{3,}" --type ts
+rg "//\s*(Helper|Utility|Private|Public)\s+(Functions|Methods|Variables)" --type ts
+
+# "This function/method/class" comments
+rg "//.*\b(This (function|method|class|variable|constant|module))" --type ts
+```
+
+## Weak Types
+
+```bash
+# Explicit any (TypeScript)
+rg ": any\b" --type ts
+rg "as any\b" --type ts
+rg "<any>" --type ts
+
+# Implicit any — missing return types on exported functions
+rg "export (async )?function \w+\([^)]*\)\s*\{" --type ts  # No return type annotation
+
+# Python Any import
+rg "from typing import.*\bAny\b" --type py
+rg ":\s*Any\b" --type py
+
+# Object type (too broad)
+rg ": object\b" --type ts
+rg ": Object\b" --type ts
+rg ": \{\}" --type ts  # Empty object type
+```
+
+## Security
+
+```bash
+# Hardcoded secrets
+rg "(api[_-]?key|secret|password|token|auth)\s*[:=]\s*['\"][^'\"]{8,}" -i
+rg "(AKIA[A-Z0-9]{16})" # AWS access keys
+rg "-----BEGIN (RSA |EC |DSA )?PRIVATE.KEY-----"
+rg "(ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9_]{36,}"  # GitHub tokens
+
+# Weak crypto
+rg "(md5|sha1)\s*\(" -i --type-add 'src:*.{ts,js,py,go,rs}' --type src
+rg "Math\.random\(\)" --type ts  # Insecure random for tokens
+rg "crypto\.createHash\(['\"]md5" --type ts
+
+# SQL injection vectors
+rg "(query|exec|execute)\s*\(\s*[`'\"].*\$\{" --type ts  # Template literal in SQL
+rg "f['\"].*SELECT.*\{" --type py  # Python f-string SQL
+
+# Command injection
+rg "(exec|execSync|spawn|spawnSync)\s*\(" --type ts
+rg "(subprocess\.call|os\.system|os\.popen)\s*\(" --type py
+
+# eval usage
+rg "\beval\s*\(" --type-add 'src:*.{ts,js,py}' --type src
+
+# Insecure defaults
+rg "rejectUnauthorized:\s*false" --type ts
+rg "verify\s*=\s*False" --type py  # Disabled SSL verify
+rg "http://" --type-add 'src:*.{ts,js,py,go}' --type src  # Plain HTTP
+```
+
+## Legacy Code
+
+```bash
+# Old Node.js APIs
+rg "\bnew Buffer\b" --type ts
+rg "\bfs\.exists\b" --type ts  # Use fs.access instead
+rg "\burl\.parse\b" --type ts  # Use new URL() instead
+rg "\bpath\.resolve\(__dirname" --type ts  # Use import.meta in ESM
+
+# Old JS patterns
+rg "\bvar\s+" --type ts  # Use let/const
+rg "\.prototype\." --type ts  # Use class syntax
+rg "\barguments\b" --type ts  # Use rest params
+rg "require\(" --type ts  # CJS in TS files
+
+# Unnecessary polyfills
+rg "core-js|regenerator-runtime|@babel/polyfill" --type json
+rg "Object\.assign" --type ts  # Spread is available everywhere now
+```
+
+## Type Consolidation
+
+```bash
+# Duplicate interface names across files
+rg "^(export )?(interface|type) (\w+)" --type ts -o | sort | uniq -d
+
+# Pick/Omit opportunities — interfaces with many shared fields
+rg "^\s+(id|name|email|createdAt|updatedAt|status):" --type ts -c | sort -t: -k2 -rn
+```
+
+## Defensive Code
+
+```bash
+# Unnecessary null checks (look for patterns after non-null assertions)
+rg "\?\.\w+\?\." --type ts  # Excessive optional chaining
+rg "!= null|!== null|!= undefined|!== undefined" --type ts
+rg "typeof \w+ !== ['\"]undefined['\"]" --type ts
+
+# Empty catch blocks (swallowed errors)
+rg "catch\s*\(\w*\)\s*\{\s*\}" --type ts
+
+# Redundant boolean comparisons
+rg "=== true|=== false|!== true|!== false" --type ts
+```
+
+## Performance
+
+```bash
+# N+1 query indicators (loop + await)
+rg "for.*\{" -A 5 --type ts | rg "await.*(find|query|fetch|get)"
+
+# Sync I/O in potentially async contexts
+rg "readFileSync|writeFileSync|execSync" --type ts
+rg "JSON\.parse\(fs\.readFileSync" --type ts
+
+# Bundle bloat — full library imports
+rg "import \w+ from ['\"]lodash['\"]" --type ts  # Should use lodash/map
+rg "import \* as" --type ts  # Namespace imports prevent tree shaking
+rg "require\(['\"]moment['\"]" --type ts  # moment.js is heavy, use date-fns/dayjs
+
+# React re-render triggers
+rg "\{\{" --type tsx  # Inline objects in JSX (new ref every render)
+rg "useEffect\(\s*\(\)\s*=>" -A 3 --type tsx  # Missing deps array
+```
+
+## Async Patterns
+
+```bash
+# forEach with async (floating promises)
+rg "\.forEach\(async" --type ts
+
+# Missing await
+rg "async.*=>" -A 3 --type ts | rg "return [^a]"  # Async arrow without await
+
+# Async function with no await
+rg "async function" --type ts  # Then check function body for await
+
+# Mixed .then() and await
+rg "await.*\.then\(" --type ts
+rg "\.then\(" --type ts -c | sort -t: -k2 -rn  # Files with most .then()
+
+# Unhandled promise rejection
+rg "\.catch\(\s*\)" --type ts  # Empty catch on promise
+rg "Promise\.(all|race|allSettled)\(" --type ts  # Check for error handling
+```
+
+## Circular Dependencies
+
+```bash
+# Barrel file re-exports (common source of circles)
+rg "export \* from" --type ts
+rg "export \{.*\} from ['\"]\.\./" --type ts  # Re-exporting from parent
+
+# Mutual imports — quick heuristic
+# Find files that import each other (requires cross-referencing)
+rg "from ['\"]\.\.?/" --type ts -l  # Files with relative imports
+```