code-hygiene

Code Hygiene — Scan, Report, Integrate

Persistent codebase health analysis. Runs static tools, interprets output, stores structured findings, suggests forge tasks for cleanup.

When to Use

• After shipping a feature (catch accumulated tech debt)
• Periodic hygiene (every 1-2 sprints)
• Before major refactoring (map current state first)
• Onboarding to unfamiliar codebase (architecture overview)
• User says "code hygiene", "tech debt", "почисти код", "найди мертвый код", "проверь тесты"

Pipeline: SCAN → REPORT → INTEGRATE → SAVE

---

Phase 1: SCAN

1a. Project Detection

• package.json → TypeScript/JavaScript (primary, full tool support)
• pyproject.toml/setup.py → Python (semgrep + scc only)
• go.mod → Go (semgrep + scc only)
• Cargo.toml → Rust (semgrep + scc only)
• Report honestly: "Full analysis available for TS/JS. Limited to semgrep+scc for [language]."

1b. Tool Detection

Check availability, report what's missing:

Global:   which tsc semgrep scc jq
Local:    grep devDependencies package.json for knip, jscpd, dependency-cruiser, stryker
Missing:  suggest `npm i -D knip jscpd dependency-cruiser` for full coverage

1c. Tool Execution

Run available tools. ALL output goes to files first — NEVER read raw output into context.

3-step pattern for every tool:

1. Redirect: <cmd> > .omc/hygiene/raw-<name>.json 2>&1
2. Summarize: jq '<path>[:50]' raw-<name>.json > <name>.json
   • If jq unavailable: Read raw-<name>.json with limit: 200
   • tsc is plain text: head -100 raw-types.txt > types.txt
3. Read: Read <name>.json — NEVER read raw-* files into context

Tools (run in parallel via background Bash):

Tool	Command	Output file	Summary jq path
tsc	tsc --noEmit 2>&1 > raw-types.txt	types.txt	head -100 (plain text)
scc	scc --by-file --format json src/ > raw-complexity.json	complexity.json	sort_by(.Complexity) | reverse | .[:50]
semgrep	semgrep scan --config auto --json . > raw-security.json	security.json	.results[:50]
knip	npx knip --reporter json > raw-dead-code.json	dead-code.json	.files[:50] + .exports[:50] (if in devDeps)
jscpd	npx jscpd src/ --reporters json -o /tmp/jscpd > raw-duplicates.json	duplicates.json	.duplicates[:50] (if installed)
dep-cruiser	npx dependency-cruiser src --include-only "^src" --output-type json > raw-dependencies.json	dependencies.json	.summary.violations[:50] (if installed)
stryker	npx stryker run --reporters json > raw-mutations.json	mutations.json	.files | to_entries[:20] (only with --deep)