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

CODE-006: Inconsistent API Response Shape

Files:

• src/app/api/users/route.ts:34 - Returns { data: users }
• src/app/api/products/route.ts:28 - Returns raw array [...]
• src/app/api/orders/route.ts:41 - Returns { items: orders } Fix: Standardize to consistent shape:

// Standard response shape
type ApiResponse = {
  data: T;
  meta?: { total: number; page: number };
  error?: string;
};

CODE-007: Magic Numbers

Files:

• src/lib/cache.ts:12 - setTimeout(() => {}, 300000)
• src/utils/pagination.ts:8 - const limit = 25
• src/hooks/useRetry.ts:15 - for (let i = 0; i < 3; i++) Fix: Extract to named constants

const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
const DEFAULT_PAGE_SIZE = 25;
const MAX_RETRY_ATTEMPTS = 3;

Low

CODE-008: TODO/FIXME Accumulation

Count: 34 items Oldest:

• src/lib/legacy.ts:12 - // TODO: migrate to new API (2023-01-15)
• src/utils/helpers.ts:89 - // FIXME: edge case (2023-03-22) Fix: Triage and address or convert to issues

CODE-009: Commented-Out Code

Files:

• src/components/Header.tsx:45-67 - 22 lines commented out
• src/lib/api.ts:112-125 - Old implementation Fix: Remove dead code (use git for history)

CODE-010: Inconsistent Naming

Examples:

• getUserData vs fetchUser vs loadUserInfo
• isLoading vs loading vs isProcessing
• handleClick vs onClick vs onButtonClick Fix: Establish naming conventions in CONTRIBUTING.md

Checklist

Must Fix

• Reduce any usage to < 5
• Remove all console.log statements
• Split files > 500 lines
• Simplify functions > 50 lines

Should Fix

• Extract duplicate logic
• Standardize API responses
• Replace magic numbers
• Address critical TODOs

Recommended

• Add lint rules for complexity
• Set up pre-commit hooks
• Document naming conventions
• Regular code review

## Execution Logging

After completing, append to `.claude/audits/EXECUTION_LOG.md`:

| [timestamp] | code-auditor | [status] | [duration] | [findings] | [errors] |

## Output Verification

Before completing:
1. Verify `.claude/audits/AUDIT_CODE.md` was created
2. Verify file has content beyond headers
3. If no issues found, write "No code quality issues detected" (not empty file)

Focus on maintainability and consistency. **Do NOT duplicate security or bug checks.**