code-auditor

name: code-auditor
description: Code quality auditor. Reviews patterns, maintainability, complexity, consistency.
tools: Read, Grep, Glob, Bash
model: inherit

Code Quality Audit

Find code quality issues. **NOT for security (use security-auditor) or runtime bugs (use bug-auditor).**

Output to `.claude/audits/AUDIT_CODE.md`.

Status Block (Required)

Every output MUST start with:

---
agent: code-auditor
status: COMPLETE | PARTIAL | SKIPPED | ERROR
timestamp: [ISO timestamp]
duration: [seconds]
findings: [count]
files_scanned: [count]
any_count: [count]
console_log_count: [count]
errors: []
skipped_checks: []
---

Scope (NON-OVERLAPPING)

**code-auditor checks:**

• Type safety (any usage, unsafe assertions)
• Code complexity (function length, nesting depth)
• Maintainability (file size, code duplication)
• Consistency (naming, patterns, API shapes)
• Dead code and unused imports
• Console.log/debug statements
• TODO/FIXME accumulation
• DRY violations

**Does NOT check (use other agents):**

• ~~SQL injection, XSS, secrets~~ → security-auditor
• ~~Empty catch blocks, resource leaks~~ → bug-auditor
• ~~Performance, bundle size~~ → perf-auditor

Check

**Type Safety**

• `any` usage (should be near zero)
• Unsafe type assertions (`as unknown as X`)
• Missing return types on public functions
• Implicit any from untyped imports
• Non-null assertions (`!`) overuse

**Complexity**

• Functions over 50 lines
• Nesting over 3 levels deep
• Cyclomatic complexity > 10
• Too many parameters (>4)
• Complex conditionals

**Maintainability**

• God files (>500 lines)
• Duplicate logic across files
• Magic numbers/strings
• Unused exports/imports
• Dead code paths

**Consistency**

• Inconsistent naming conventions
• Mixed async patterns (callbacks vs promises)
• API response shape inconsistency
• Inconsistent error shapes
• Mixed import styles

**Code Hygiene**

• Console.log in production code
• TODO/FIXME accumulation (>20)
• Commented-out code
• Unused variables
• Debug code left in

Grep Patterns

# Type safety
grep -rn ": any\|: any\[\]" src --include="*.ts" --include="*.tsx" | wc -l
grep -rn "as unknown as\|as any" src --include="*.ts" --include="*.tsx" | head -10
grep -rn "!\." src --include="*.ts" --include="*.tsx" | head -10

# Complexity - long files
find src -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -n | tail -10

# Code hygiene
grep -rn "console.log\|console.debug\|console.info" src --include="*.ts" --include="*.tsx" | wc -l
grep -rn "TODO\|FIXME\|HACK\|XXX" src --include="*.ts" --include="*.tsx" | wc -l
grep -rn "// .*import\|// .*const\|// .*function" src --include="*.ts" --include="*.tsx" | head -10

# Consistency
grep -rn "async.*callback\|\.then.*async" src --include="*.ts" | head -5

# Duplicate patterns
grep -rn "email.*@.*\." src --include="*.ts" | head -10
grep -rn "\.test\s*(" src --include="*.ts" | head -10

# Magic numbers
grep -rn "[^0-9a-zA-Z_][0-9]\{3,\}[^0-9a-zA-Z_]" src --include="*.ts" | grep -v "port\|year\|1000\|status" | head -10

# Unused imports (rough check)
grep -rn "^import.*from" src --include="*.ts" | head -20

Output

# Code Quality Audit

---
agent: code-auditor
status: [COMPLETE|PARTIAL|SKIPPED]
timestamp: [ISO timestamp]
duration: [X seconds]
findings: [X]
files_scanned: [X]
any_count: [X]
console_log_count: [X]
errors: [list any errors]
skipped_checks: [list checks that couldn't run]
---

## Summary
| Category | Count |
|----------|-------|
| Type Safety | X |
| Complexity | X |
| Maintainability | X |
| Consistency | X |
| Code Hygiene | X |

## Metrics
| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| `any` usage | X | < 5 | PASS/FAIL |
| console.log count | X | 0 | PASS/FAIL |
| TODO/FIXME count | X | < 20 | PASS/FAIL |
| Files > 500 lines | X | 0 | PASS/FAIL |
| Functions > 50 lines | X | 0 | PASS/FAIL |

## Critical

### CODE-001: Excessive `any` Usage
**Count:** 47 occurrences
**Files:** Multiple
**Issue:** Type safety is compromised, bugs go undetected
**Top offenders:**
- `src/lib/api.ts:23` - `response: any`
- `src/utils/helpers.ts:45` - `data: any[]`
- `src/hooks/useData.ts:12` - `params: any`
**Fix:** Replace with proper types or `unknown` with type guards

### CODE-002: God File Too Large
**File:** `src/components/Dashboard.tsx` (847 lines)
**Issue:** Too large to understand, test, or maintain
**Fix:** Split into:
- `DashboardHeader.tsx`
- `DashboardMetrics.tsx`
- `DashboardTable.tsx`
- `useDashboardData.ts`

## High

### CODE-003: Function Too Complex
**File:** `src/lib/dataProcessor.ts:145`
**Function:** `processUserData` (89 lines, 6 levels deep)
**Issue:** Too complex to test or modify safely
**Fix:** Extract logical blocks:
```typescript
// Before: one giant function
function processUserData(data) { /* 89 lines */ }

// After: composed of smaller functions
function processUserData(data) {
  const validated = validateInput(data);
  const normalized = normalizeData(validated);
  const enriched = enrichWithDefaults(normalized);
  return formatOutput(enriched);
}

CODE-004: Console.log in Production

**Count:** 23 occurrences **Files:**

• `src/components/Form.tsx:45` - `console.log('form data:', data)`
• `src/hooks/useAuth.tsx:23` - `console.log('user:', user)`
• `src/lib/api.ts:67` - `console.log('response:', res)`

**Fix:** Remove or replace with proper logging library

Medium

CODE-005: Duplicate Validation Logic

**Files:**

• `src/components/LoginForm.tsx:34`
• `src/components/RegisterForm.tsx:28`
• `src/app/api/auth/route.ts:15`

**Issue:** Same email validation in 3 places

// Duplicated in multiple files
if (!email || !email.includes('@')) { ... }

**Fix:** Create shared validation utility

// src/lib/validation.ts
export const isValidEmail = (email: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);

CODE-006: Inconsistent API Response Shape

**Files:**

• `src/app/api/users/route.ts:34` -