KaizenGuidance

*Codebase improvement programs*

A curated, language-agnostic library of Code Quality Guides where each guide is:

- Readable for humans,
- Checkable by linters/static analyzers,
- Refactorable by codemods/agents,
- Measurable with before/after quality metrics.

Think “Clean Code + MISRA precision + Sonar/ESLint automation + AI codemods.”

See also: https://chatgpt.com/share/68d6b45b-17f8-8009-8d15-c174f53d2591

## Guide anatomy (single source of truth)
- Each guide lives as a versioned folder containing:
- A manifest (machine-readable spec)
- A narrative (rationale, trade-offs, examples)
- Checks (lint/static analysis mappings)
- Refactors (codemods, recipes, prompts)
- Tests (fixtures + expected diffs)
- Metrics (what ‘better’ means)

## Rule expression & execution pipeline
a) Parse → Check → Plan → Refactor → Test → Measure → Report
- Parse: build AST/index (libcst for Py, ts-morph/jscodeshift for TS/JS, OpenRewrite for Java, Clang-Tidy/LibTooling for C/C++).
- Check: run native linters + Semgrep queries from guide.yaml (unified output schema).
- Plan: produce a Change Plan (JSON) listing targets & suggested transforms.
- Refactor: deterministic codemods first; ambiguous edits delegated to an Agent with a strict prompt & test harness.
- Test: run unit tests + mutation tests (where available).
- Measure: compute deltas for maintainability index (MI), cyclomatic complexity, duplication, lint issues, “hotspot*rule” intersections (code churn × smells).
- Report: markdown/HTML summary + SARIF for code scanning.

## Example guides (initial catalog)

1. API Design
- Avoid boolean “success” returns (above)
- Prefer narrow, explicit exceptions
- Make side effects explicit (naming & module boundaries)

2. Readability & Structure
- Function length & parameter count thresholds (with exceptions mechanism)
- Cohesion over convenience: one reason to change (SRP pragmatically)
- Replace “god module/class” with feature modules

3. Testing & Contracts
- Fast tests default; slow/flaky quarantined
- Golden tests for parsers/formatters
- Pre/postconditions via lightweight asserts or type contracts

4. Performance-safe Patterns
- Avoid N+1 queries (framework-specific codemods)
- Replace quadratic hot-loops with map/join or indexed lookups
- Lazy vs eager boundaries (measurable)

5. Security & Robustness
- Input validation at boundaries (web/cli)
- No raw SQL without parameterization
- Secrets/config separation; env-based wiring

Each guide ships checks + codemods + agent prompts + metrics.


xxx