👻 Ghost

Ghost is a deterministic, local, and offline-capable static-analysis CLI tool designed to detect dead files, unused exports, circular dependencies, and unused dependencies in JavaScript and TypeScript codebases.

Note: The Ghost MVP is fully implemented and operational.

Features (Implemented)

• Dead File Detection: Finds files with no incoming import edges that aren't recognized entry points.
• Unused Export Detection: Identifies exported symbols that are never imported anywhere.
• Circular Dependency Detection: Detects import cycles using DFS.
• Unused Dependency Detection: Compares package.json dependencies against actual resolved imports.
• Confidence Engine: Dynamically scales confidence scores based on dynamic imports or heuristics.
• Interactive Terminal UI: Built with React and Ink for a modern CLI experience.
• Deterministic JSON Output: Predictable and sorted outputs via --json.

Project Vision & Architecture

Ghost is designed to be a highly precise, local-first static analyzer. Unlike tools that use loose heuristics or require cloud resources, Ghost uses a deterministic model constructed via the TypeScript Compiler API. It analyzes the project's dependency graph locally to identify dead files, unused exports, circular dependencies, and unused npm dependencies.

The core architecture is strictly decoupled from the presentation layer to ensure that the static-analysis engine can be directly reused by downstream projects such as CodeDNA.

Key Decoupling Principle

• Core Engine (src/core): Zero dependencies on terminal UI, CLI-specific flags, formatting, React, or Ink. Input is a clean configuration context, and output is a structured, pure JSON data structure representing findings.
• CLI presentation (src/cli): Consumes the Core Engine output and presents interactive, visual progress and rich logs using React and Ink.

Capabilities

• 🔍 Repository Scanning: Fast directory scanning ignoring files defined in .gitignore.
• 🧮 AST Parsing & Resolution: Complete module-level AST analysis utilizing TypeScript Compiler API.
• 🕸️ Dependency Graphing: Fully connected import/export resolution spanning relative paths, path aliases, and standard node modules.
• 🎯 Dead Code Detection: Detection of fully isolated files and unreferenced exported symbols.
• 🔁 Circular Dependency Checker: Direct, transitive cycle detection across files.
• 📦 Unused NPM Dependency Detection: Validation of declared vs. actually imported packages.
• ⚖️ Confidence Engine: Non-aggressive confidence scoring for dynamic code structures (such as dynamic import() or eval).

Quick Start

Installation

Install Ghost globally via npm:

npm install -g ghost-analyzer

Usage

Run Ghost from any project directory:

# Scan the current directory and output concise results
ghost .

# Output a detailed human-readable report
ghost report .

# Analyze cyclomatic complexity
ghost complexity .

# Analyze local git changes (diffs and status)
ghost git .

# Output results in JSON format
ghost . --json
ghost complexity . --json
ghost git . --json

# Suppress decorative output
ghost . --quiet

# Output detailed diagnostic information during analysis
ghost . --verbose

Requirements

• Node.js >= 18.0.0
• TypeScript project (or JavaScript) with a valid package.json

Examples

Analyze current directory:

ghost

Analyze specific directory and output JSON:

ghost ./src --json

Development

To test or modify Ghost locally:

1. Clone the repository and install dependencies:

   npm install

2. Build the project:

   npm run build

3. Run tests:

   npm test