🔍 DeadScan — Dead Code Analyzer

DeadScan is a high-performance static-analysis CLI and programmatic library for JavaScript and TypeScript projects. It builds a full module dependency graph via the official TypeScript Compiler API, evaluates reachability from application entry points, and identifies potential dead files, unused exports, and unreferenced local declarations with confidence scoring.

⚡ Features

• 🎯 AST-Based Parsing: Powered by the TypeScript Compiler API. No fragile regexes.
• 🌳 Module Dependency Graph: Tracks imports, exports, default exports, re-exports (export *), side-effect imports, and path aliases.
• 🗑️ Dead File Detection: Finds files unreachable from application entry points.
• 📦 Unused Export Detection: Identifies exported symbols never consumed by reachable code.
• 🧹 Unused Declaration Detection: Pinpoints unused local variables, functions, and classes (with support for _ variable suppression).
• ⚡ Dynamic Import Warnings: Flags dynamic import(...) calls that cannot be statically resolved.
• 📊 Confidence Scoring: Assigns High/Medium/Low confidence metrics to minimize false positives.
• 💻 CLI & API Support: Use directly in terminal (npx deadscan) or programmatically in node scripts.
• 🎨 Visual & CI Ready: Colorized terminal output with color-suppression when piped, plus a --json output flag for CI pipelines.

📦 Installation

npm install deadscan --save-dev

Or run directly without installation using npx:

npx deadscan

🚀 Quick Start

1. CLI Usage

Run DeadScan in your project directory:

# Auto-detect entry points and scan project
npx deadscan

# Scan specific folder with explicit entry point
npx deadscan ./src --entry src/main.ts

# Detect only dead files
npx deadscan --dead-files

# Output CI-friendly JSON
npx deadscan --json

CLI Command Options

| Option | Shorthand | Description | | :--- | :--- | :--- | | [root] | | Project root directory (default: .) | | --entry <path...> | -e | Specify explicit entry point file(s) | | --config <path> | -c | Path to custom config file | | --dead-files | | Only scan for dead/unreachable files | | --unused-exports | | Only scan for unused exports | | --unused-declarations | | Only scan for unused local declarations | | --json | -j | Output structured JSON summary | | --verbose | -v | Display detailed reasons and confidence levels | | --strict | -s | Exit with status code 1 if dead code is found (for CI) | | --ignore <patterns...>| -i | Additional glob ignore patterns | | --extensions <exts...>| -x | Custom file extensions to scan (.ts .tsx .js .jsx) |

⚙️ Configuration File

DeadScan supports deadscan.config.ts, deadscan.config.js, or deadscan.config.json in your project root:

// deadscan.config.ts
export default {
  root: "./src",

  entryPoints: [
    "./src/main.ts",
    "./src/server.ts"
  ],

  ignore: [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/generated/**"
  ],

  extensions: [
    ".ts",
    ".tsx",
    ".js",
    ".jsx"
  ],

  ignoreUnderscoreVariables: true
};

💻 Programmatic Library API

DeadScan exposes a fully-typed programmatic API for custom Node.js scripts, build tasks, or linters:

import { analyze } from 'deadscan';

const result = await analyze({
  root: './src',
  entryPoints: ['./src/index.ts'],
  ignoreUnderscoreVariables: true
});

console.log(`Analyzed ${result.summary.filesAnalyzed} files.`);
console.log('Dead files:', result.deadFiles);
console.log('Unused exports:', result.unusedExports);
console.log('Unused local declarations:', result.unusedDeclarations);

TypeScript API Interfaces

export interface AnalyzeOptions {
  root?: string;
  entryPoints?: string[];
  config?: string;
  deadFiles?: boolean;
  unusedExports?: boolean;
  unusedDeclarations?: boolean;
  ignore?: string[];
  extensions?: string[];
  ignoreUnderscoreVariables?: boolean;
  strict?: boolean;
  verbose?: boolean;
  json?: boolean;
}

export interface AnalysisResult {
  summary: AnalysisSummary;
  deadFiles: DeadFile[];
  unusedExports: UnusedExport[];
  unusedDeclarations: UnusedDeclaration[];
  dynamicImportWarnings: DynamicImportWarning[];
}

🖥️ Example Terminal Output

🔍 DeadScan — Dead Code Analyzer

Scanning project...
✓ Parsed 248 files
✓ Built dependency graph
✓ Analyzed reachability & declarations

Potential dead code found:

⚠️  Dead files (2)

  src/legacy/payment.ts
  src/utils/old-helper.ts

⚠️  Unused exports (2)

  src/utils/date.ts
    └── formatLegacyDate (line 42)
  src/auth/auth.ts
    └── legacyAuth (line 15)

⚠️  Unused declarations (1)

  src/cart.ts:42
    └── discount (variable)

────────────────────────────────────
Files analyzed:        248
Potential dead files:    2
Unused exports:          2
Unused declarations:     1

Confidence:
  High:    5
  Medium:  0
  Low:     0
────────────────────────────────────

Structured JSON Output (--json)

{
  "summary": {
    "filesAnalyzed": 248,
    "deadFilesCount": 2,
    "unusedExportsCount": 2,
    "unusedDeclarationsCount": 1,
    "confidenceCounts": {
      "high": 5,
      "medium": 0,
      "low": 0
    }
  },
  "deadFiles": [
    {
      "file": "src/legacy/payment.ts",
      "confidence": 0.98,
      "confidenceLevel": "High",
      "reason": "No reachable import path from configured entry points."
    }
  ],
  "unusedExports": [
    {
      "file": "src/utils/date.ts",
      "name": "formatLegacyDate",
      "line": 42,
      "column": 1,
      "isDefault": false,
      "confidence": 0.92,
      "confidenceLevel": "High",
      "reason": "Export 'formatLegacyDate' is never imported or referenced by any reachable module."
    }
  ],
  "unusedDeclarations": [],
  "dynamicImportWarnings": []
}

🏗️ Architecture Overview

src/
├── cli/              # Command parsing & terminal output formatter
├── analyzer/         # AST Parsing (ts.createSourceFile), Symbol & Usage visitors
├── graph/            # Directed dependency graph & BFS reachability engine
├── resolver/         # TS Compiler API module resolution & tsconfig path mapping
├── detectors/        # Dead file, unused export, and unused declaration rules
├── config/           # Config loader & entry point auto-detector
├── types/            # TypeScript interfaces
└── index.ts          # Public programmatic entry point

⚠️ Limitations & False-Positive Disclaimer

[!WARNING] DeadScan performs static analysis. Dynamic imports (import("./plugins/" + name)), reflection, framework magic (e.g. Next.js page routing without static entry points), runtime component registration, generated code, and external npm consumers can cause false positives. DeadScan reports potential dead code with confidence scores and should be used as a guiding analysis tool.

📄 License

MIT © Pranessh