66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
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
|