code-cleanup-analyzer

name	code-cleanup-analyzer
description	Analyze codebase for dead code, duplicates, and consolidation opportunities. Use when user says "analyze code", "find dead code", "code cleanup", "find duplicates", "unused exports", "consolidation opportunities", or "static analysis".

Code Cleanup Analyzer

Runs three static analysis tools sequentially, then validates findings to filter out false positives.

Tools used:

• knip - Dead code, unused exports, unused dependencies
• jscpd - Duplicate code blocks
• madge - Circular dependencies

Important: Run Tools Directly

DO NOT use Task agents for this skill. Run all tools directly in the main context using Bash. This prevents infinite retry loops and token waste.

Workflow

Step 1: Ensure Dependencies

SKILL_DIR=~/.claude/skills/code-cleanup-analyzer
if [ ! -d "$SKILL_DIR/node_modules" ]; then
  cd "$SKILL_DIR" && bun install
fi

Step 2: Gather Project Context

Read package.json to understand the project:

cat package.json

Note these details for validation:

• Framework: next, react, vue, angular in dependencies
• Runtime: Look for bun.lockb or "bun" in scripts
• Scripts that use tools indirectly:
  • "lint": "next lint" → eslint is used
  • "test": "bun test --preload ./preload.ts" → preload.ts is used
• Config files: ls *.config.* tsconfig.json 2>/dev/null

Step 3: Run Analysis Tools (Sequentially)

Run each tool ONE TIME with the exact commands below. If a tool fails, report the error and move on.

Tool 1: knip (Dead Code)

~/.claude/skills/code-cleanup-analyzer/node_modules/.bin/knip --reporter json --no-progress 2>&1 | head -500

Flags explained:

• --reporter json - Machine-readable output
• --no-progress - Disable dynamic terminal updates (required for non-TTY)

Parse the JSON output for:

• files array - Unused files
• issues[].dependencies - Unused dependencies
• issues[].devDependencies - Unused devDependencies
• issues[].exports - Unused exports
• issues[].unlisted - Unlisted dependencies (false positives for framework-provided packages)

Tool 2: madge (Circular Dependencies)

~/.claude/skills/code-cleanup-analyzer/node_modules/.bin/madge --circular --json --extensions ts,tsx --ts-config tsconfig.json --no-spinner src 2>&1

Flags explained:

• --circular - Find circular dependencies
• --json - Machine-readable output
• --extensions ts,tsx - Only analyze TypeScript files
• --ts-config tsconfig.json - Use project's tsconfig for path resolution
• --no-spinner - Disable progress spinner
• src - Analyze the src directory

Output: Returns [] if no circular deps, or array of dependency chains.

Tool 3: jscpd (Duplicate Code)

~/.claude/skills/code-cleanup-analyzer/node_modules/.bin/jscpd src --min-lines 10 --min-tokens 100 --reporters json --silent --gitignore --max-size 500kb -o /tmp/jscpd-report 2>&1

Then read the report:

cat /tmp/jscpd-report/jscpd-report.json | head -200

Flags explained:

• --min-lines 10 - Minimum 10 lines to count as duplicate (default 5 is too noisy)
• --min-tokens 100 - Minimum 100 tokens (default 50 is too noisy)
• --reporters json - JSON output
• --silent - No progress output
• --gitignore - Respect .gitignore
• --max-size 500kb - Handle larger files (default 100kb skips many files)
• -o /tmp/jscpd-report - Write to temp dir, not project

Parse the report for:

• statistics.total.clones - Number of duplicate blocks
• statistics.total.duplicatedLines - Total duplicated lines
• duplicates array - Specific duplicate pairs with file paths and line ranges

Step 4: Validate Findings

After running all tools, validate each finding using Grep to filter false positives.

For Unused Dependencies:

# Check if package is imported anywhere
rg "from ['\"]package-name" src/
# Check if used in scripts
grep "package-name" package.json

Classify as:

• HIGH confidence: 0 imports in src/ AND not in scripts
• FALSE POSITIVE: Used in scripts (e.g., eslint via "next lint")
• FALSE POSITIVE: Framework-provided (e.g., "server-only" in Next.js)

For Unused Files:

# Check if file is imported anywhere
rg "from.*filename" src/
# Check if referenced in configs
grep -r "filename" *.config.* tsconfig.json package.json 2>/dev/null

Classify as:

• HIGH confidence: 0 imports AND not in config AND not in scripts
• FALSE POSITIVE: Used by scripts (e.g., preload.ts for bun test)

Step 5: Present Validated Results

## Code Cleanup Analysis (Validated)

### High Confidence - Safe to Remove

| Item | Type | Verification |
|------|------|--------------|
| react-icons | dependency | 0 imports in src/, not in scripts |
| src/components/OldComponent.tsx | file | 0 imports found |

### Circular Dependencies
[List any chains found by madge]

### Duplicate Code
[List significant duplicates from jscpd, skip test files and docs]

### Filtered Out (Not Issues)
- `eslint`: Used by `next lint` script
- `server-only`: Provided by Next.js
- `preload.ts`: Used by `bun test --preload` script

Step 6: Cleanup (If Requested)

If user wants to proceed:

1. Use AskUserQuestion to confirm which items to remove
2. Edit package.json to remove dependencies
3. Use trash command to delete unused files (not rm)
4. Run bun install to update lockfile
5. Run bun run typecheck to verify no breakage

Common False Positives

Next.js Projects

• eslint, eslint-config-next → used by next lint script
• server-only → provided by Next.js, shows as "unlisted" but is valid
• postcss, autoprefixer → used by Next.js CSS processing
• Files in app/ with special names (layout, page, loading, error) → framework conventions

Bun Projects

• preload.ts → used by bun test --preload
• Many @types/* packages → Bun provides built-in types

Testing

• @faker-js/faker, @testing-library/* → only in test files is OK
• Test file duplication → often intentional for test clarity

shadcn/ui Projects

• Unused @radix-ui/* packages → installed by CLI but component not yet used
• UI component files → installed but not yet used (suggest removal)

Documentation

• CLAUDE.md <-> GEMINI.md duplication → intentional
• README duplication in monorepos → intentional