# 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.
