Codebase Health Auditor

Codebase Health Auditor

Comprehensive dead code detection and safe cleanup for Vue 3 + TypeScript projects.

Overview

A unified skill that merges the best of Legacy Tech Remover and Comprehensive Auditor while adding modern tooling:

• File Size/Token Limit: Detects oversized files that block AI editing (>25K tokens)
• Knip: Unused files, exports, dependencies
• depcheck: Unused npm packages
• TypeScript: noUnusedLocals, noUnusedParameters
• Vue-specific: Unused props, emits, computed, watchers
• Legacy patterns: Deprecated libraries, orphaned directories

Quick Start

# Full audit (dry-run by default)
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js audit

# Execute safe removals only
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js execute --safe-only

# Single detector
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js detect --detector vue

# CI mode
node .claude/skills/codebase-health-auditor/scripts/orchestrator.js audit --ci

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:

detection:
  knip:
    enabled: true
    ignore: ["**/*.test.ts", "**/*.stories.ts"]
  depcheck:
    enabled: true
    ignoreMatches: ["@types/*"]
  typescript:
    enabled: true
    noUnusedLocals: true
    noUnusedParameters: true
  vue:
    enabled: true
    detectUnusedProps: true
    detectUnusedEmits: true
    detectUnusedComputed: true
    detectUnusedWatchers: true
  legacy:
    enabled: true
    minYearsUntouched: 2

assessment:
  riskThresholds:
    safe: 20
    caution: 60
  protectedPaths:
    - "src/main.ts"
    - "src/App.vue"
    - "src/stores/**"
  protectedPackages:
    - "vue"
    - "pinia"
    - "vue-router"
    - "typescript"

actions:
  defaultMode: "dry-run"
  batchSize: 5
  validateAfterBatch: true
  gitIntegration:
    autoCommit: true
    commitPrefix: "[codebase-health]"
    createBackupBranch: true

reporting:
  formats: ["json", "markdown"]
  outputDir: "./audit-reports"
  includeBlindSpots: true

Output Examples

Console Summary

Codebase Health Audit Complete

Findings:
  SAFE (auto-remove OK):    23 items
  CAUTION (review needed):  18 items
  RISKY (migration needed):  6 items

By Category:
  Unused exports:     15
  Unused dependencies: 8
  Unused Vue props:   12
  Legacy patterns:     6
  Orphaned files:      6

Estimated Impact:
  Files to remove:    12
  Lines of code:   1,847
  Bundle savings: ~245KB

Run with --execute --safe-only to remove safe items.

JSON Report

{
  "metadata": {
    "timestamp": "2026-01-09T...",
    "version": "1.0.0",
    "executionTime": 45.2
  },
  "summary": {
    "totalFindings": 47,
    "byRisk": { "SAFE": 23, "CAUTION": 18, "RISKY": 6 },
    "byType": { "unused-export": 15, "unused-dependency": 8 }
  },
  "findings": [...]
}

Safety Features

1. Dry-run by default: No changes without explicit --execute
2. Backup branch: Creates backup/health-audit-YYYYMMDD before changes
3. Batch execution: Removes 5 items at a time, validates between
4. Build validation: Runs npm run build after each batch
5. Rollback commands: Provides git revert commands in report
6. Protected paths: Never suggests removing core files

False Positive Handling

In Code

// @codebase-health-ignore: Used dynamically
export const unusedButNeeded = ...;

In Config

detection:
  ignore:
    - "src/utils/polyfills.ts"  # Side-effect imports
    - "**/*.generated.ts"        # Generated code

Known Blind Spots

• Dynamic imports: import(variable) cannot be statically analyzed
• Reflection/metaprogramming
• Runtime code generation
• Framework magic (e.g., Vue's $attrs, $slots)
• Side-effect-only imports

Integration

This skill supersedes:

• 🧹 legacy-tech-remover (patterns ported)
• 📊 comprehensive-auditor (static analysis integrated)

Works alongside:

• dev-lint-cleanup - For ESLint-specific fixes
• document-sync - To update docs after removal

CLI Options

Available Detectors

More detectors coming: unused-exports, unused-deps, vue-dead-code, legacy-patterns

Version: 1.0.0 Author: Claude Code Category: Code Maintenance Created: January 9, 2026