codebase-ai 0.1.1 → 0.1.3

package/commands/review.md

@@ -67,7 +67,7 @@ Follow the complete `/vb-review` workflow across all phases:
 
 - **Phase 0** — Scope (`--pr N` or full codebase)
 - **Phase 1** — Security Review (OWASP top 10, CVEs, secrets, auth/authz)
-- **Phase 2** — Quality Review (CLAUDE.md conventions, dead code, lint, complexity)
+- **Phase 2** — Quality Review (CLAUDE.md conventions, dead code, lint, complexity, defensive programming, minimal code)
 - **Phase 3** — Dependency Health (outdated, vulnerable, alternatives)
 - **Phase 4** — UI/Accessibility (contrast, ARIA, keyboard, responsive)
 - **Phase 5** — Consolidate & prioritize
@@ -147,4 +147,60 @@ Auto-fix:      [yes | no]
 ════════════════════════════════════════════════════════
 ```
 
-All other behavior (security agent prompts, quality rules, CVE research, accessibility checks, test generation) follows the `/vb-review` specification exactly.
+All other behavior (security agent prompts, CVE research, accessibility checks, test generation) follows the `/vb-review` specification exactly.
+
+---
+
+## Phase 2 — Quality Review (Extended Rules)
+
+The quality agent must check the following **in addition** to the base `/vb-review` quality rules.
+
+### Defensive Programming
+
+Check every function, method, and handler for:
+
+- **Missing guard clauses** — function body has deep nesting where an early return/throw would flatten it. Flag any function with 3+ levels of nesting that could use guard clauses.
+- **Missing input validation at boundaries** — functions that accept external input (API params, user input, env vars, CLI args, file reads) without validating type, range, or presence before use.
+- **Unchecked null/undefined** — property access on values that could be null/undefined without a prior check (e.g. `user.name` where `user` could be null).
+- **Silent failures** — empty `catch` blocks, `.catch(() => {})`, swallowed errors with no logging or rethrow. Every error boundary must either handle, log, or rethrow.
+- **Missing error handling at I/O boundaries** — file reads, network calls, subprocess exec, DB queries with no error handling.
+- **Optimistic assumptions** — code that assumes an array is non-empty before indexing, assumes a map key exists before accessing, or assumes an async call always resolves.
+- **No fail-fast** — configuration or required env vars read lazily (mid-request) instead of validated at startup, so failures surface late and with poor context.
+
+Severity guide:
+- `high` — missing validation on external input, unchecked null on a hot path, silent catch hiding errors
+- `medium` — deep nesting fixable with guard clauses, missing fail-fast for config
+- `low` — optimistic array/map access in low-risk paths
+
+### Minimal Code
+
+Check for over-engineering and unnecessary complexity:
+
+- **YAGNI violations** — abstractions, interfaces, config options, or generics added for hypothetical future use that have exactly one concrete caller/case today.
+- **Premature abstraction** — a helper/utility/class created for code used in only one place. Three similar lines of code is better than a one-use abstraction.
+- **Over-parameterization** — functions with options objects or boolean flags that only ever receive the same values. Flags that were never flipped from their default since they were added.
+- **Unnecessary indirection** — wrapper functions that do nothing but call another function with the same signature.
+- **Dead feature flags** — flags/toggles that are always `true` or always `false` in all environments; can just be removed.
+- **Backwards-compatibility shims for internal code** — deprecated aliases, re-exports, or `_unused` renames for code that has no external consumers.
+- **Excessive comments explaining obvious code** — comments that restate what the code already says clearly (e.g. `// increment counter` above `count++`). Flag only; do not auto-fix.
+- **Over-engineered error messages** — error classes with elaborate hierarchies for a project that throws 2-3 distinct error types.
+
+Severity guide:
+- `medium` — YAGNI abstractions, over-parameterization, unnecessary indirection
+- `low` — dead flags, excessive comments, minor shims
+
+### Code Simplicity Principles
+
+- **Flat over nested** — prefer early returns, guard clauses, and linear flow over pyramid/callback-hell structures.
+- **Explicit over clever** — flag code that uses obscure language tricks, complex one-liners, or metaprogramming where a simple loop/condition would be clearer.
+- **Consistent patterns** — same operation done differently in 2+ places (e.g. one place uses `?.` optional chaining, another uses explicit null check for the same pattern). Flag the inconsistency; suggest unifying to the simpler form.
+- **Functions do one thing** — flag functions that mix concerns (e.g. validate + transform + persist in one function body >30 lines with no clear single responsibility).
+
+Severity guide:
+- `medium` — mixed concerns in large functions, inconsistent patterns across the codebase
+- `low` — clever one-liners, minor style inconsistencies
+
+### Auto-fixable vs Architectural
+
+- **Auto-fixable (`--fix`)**: guard clause refactors (simple cases), removing empty catch blocks (replace with `// TODO: handle error`), removing dead flags set to constant values, removing unused re-exports.
+- **Architectural (create issue, no auto-fix)**: adding input validation that requires schema/type decisions, restructuring mixed-concern functions, replacing premature abstractions (requires understanding callers).