Ghost-Hunter

I built this because I got really irritated dealing with codebases that grew too large and accumulated tons of dead code. When you're working on a big project, it's hard to know which exports are actually being used and which ones are just sitting there taking up space.

Installation

npm install -g ghost-hunter

Or run it directly:

npx ghost-hunter

Usage

Run it in your project directory:

ghost-hunter

It automatically reads your tsconfig.json to understand your project structure.

Specify Custom tsconfig Path

ghost-hunter --project ./packages/core/tsconfig.json

JSON Output

For CI/CD integration or programmatic consumption:

ghost-hunter --format json

What It Detects

Ghost-Hunter finds unused:

• Named exports (export const, export function, export class)
• Default exports (export default)
• Type exports (export interface, export type)
• Enum exports (export enum)

Example Output

🔍 Found 5 unused exports in 2 files:

src/utils/helpers.ts
  ⚠️  formatDate (line 45)
  ⚠️  parseDate (line 67)

src/components/Button.tsx
  ⚠️  ButtonProps [default] (line 12)
  ⚠️  ButtonVariant (line 8)

Total files scanned: 47
Total unused exports: 5

How It Works

1. Loads your TypeScript project using ts-morph
2. Scans all .ts and .tsx files
3. Maps every export in your codebase
4. Maps every import in your codebase
5. Compares them to find exports that are never imported
6. Shows you the results grouped by file

Architecture

src/
├── core/
│   ├── errors.ts          # Custom error classes
│   └── ProjectLoader.ts   # tsconfig.json parser
├── analysis/
│   ├── ExportMapper.ts    # Extract all exports
│   ├── ImportMapper.ts    # Extract all imports
│   ├── GraphBuilder.ts    # Build usage graph
│   └── Analyzer.ts        # Orchestration layer
├── reporting/
│   └── Reporter.ts        # Format output
├── types.ts               # Type definitions
└── cli.ts                 # CLI entry point

Performance

Ghost-Hunter uses efficient data structures for O(1) lookup performance:

• Map<string, ExportSignature> for export tracking
• Set<string> for import existence checks

Exit Codes

• 0 - No unused exports found
• 1 - Unused exports detected
• 2 - Configuration error
• 3 - Analysis error
• 4 - Unexpected error

Limitations

• Only analyzes files included in your tsconfig.json
• Doesn't detect dynamic imports using string concatenation
• Doesn't know if external packages are using your exports
• Won't catch usage through reflection or runtime shenanigans

License

MIT