Codebase Health Auditor

Detection Capabilities

1. Unused Files & Exports (via Knip)

• Files never imported anywhere
• Exported functions/classes never used
• Types/interfaces never referenced

2. Unused Dependencies (via depcheck)

• npm packages in package.json but never imported
• Missing dependencies (imported but not in package.json)
• devDependencies in wrong section

3. TypeScript Dead Code

• Unused local variables
• Unused function parameters
• Detects what TypeScript would flag if noUnusedLocals/noUnusedParameters were enabled

4. Vue-Specific Dead Code

• Unused props (defineProps not used in template/script)
• Unused emits (defineEmits never called)
• Unused computed properties
• Unused watchers
• Unused refs/reactive
• Unused imported components

5. Legacy Detection (ported from legacy-tech-remover)

• Deprecated libraries (moment, request, jQuery, etc.)
• Legacy config files (Grunt, Gulp, Travis CI)
• Orphaned directories (old/, legacy/, v1/, bak/)
• Files untouched for 2+ years

6. File Size & Token Limit Detection ⭐ NEW

Detects files that exceed token limits for AI editing tools like Claude Code.

Why this matters: Files over ~25,000 tokens become difficult or impossible for AI tools to edit effectively, causing truncation, context loss, and failed edits.

Token Thresholds

Quick Usage

# Detect oversized files
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js detect --detector file-size

# Custom threshold (e.g., only 20K+ tokens)
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js detect --detector file-size --min-tokens 20000

# Save report to file
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js detect --detector file-size --output ./audit-reports/file-size.json

Sample Output

📊 File Size Detection Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Files scanned: 156
Files over threshold: 3

By Risk Level:
  🔴 CRITICAL: 1 files
  🟡 CAUTION:  2 files

──────────────────────────────────────────────────
Detailed Findings:

🔴 src/views/CanvasView.vue
   Tokens: 38,500 | Lines: 2,847 | Size: 154.2KB
   Suggestions:
     • 🔴 CRITICAL - High priority refactoring needed
     • Extract script logic into composables (src/composables/)
     • Split into smaller child components
     • URGENT: Major component decomposition needed
     • Consider: extract state to Pinia store

🟡 src/stores/canvas.ts
   Tokens: 28,200 | Lines: 1,245 | Size: 112.8KB
   Suggestions:
     • Split store into feature-specific modules
     • Extract actions/getters into separate files

Refactoring Suggestions

The detector provides context-aware suggestions based on file type:

Vue Components (.vue):

• Extract script logic into composables
• Split into smaller child components
• Consider state extraction to Pinia stores

TypeScript/JavaScript (.ts/.js):

• Split store into feature-specific modules
• Break into smaller, focused composables
• Apply single responsibility principle
• Extract utility functions to separate files

Risk Scoring

Each finding is categorized by risk level:

Risk Factors

4-Phase Workflow

┌─────────────────────────────────────────┐
│ PHASE 1: DETECTION                       │
│  - Run all detectors in parallel         │
│  - Deduplicate findings                  │
│  - Tag source (knip/depcheck/vue/etc)    │
└───────────────────┬─────────────────────┘
                    ▼
┌─────────────────────────────────────────┐
│ PHASE 2: ASSESSMENT                      │
│  - Calculate risk scores                 │
│  - Build dependency graph                │
│  - Categorize: SAFE / CAUTION / RISKY    │
└───────────────────┬─────────────────────┘
                    ▼
┌─────────────────────────────────────────┐
│ PHASE 3: ACTION (if --execute)           │
│  - Create backup branch                  │
│  - Remove SAFE items in batches          │
│  - Validate build after each batch       │
│  - Prompt for CAUTION items              │
└───────────────────┬─────────────────────┘
                    ▼
┌─────────────────────────────────────────┐
│ PHASE 4: REPORTING                       │
│  - Generate JSON report                  │
│  - Generate Markdown summary             │
│  - CI exit codes                         │
└─────────────────────────────────────────┘

Configuration

Create .claude/codebase-health-config.yml: