Table of Contents

• Overview
• Key Features
• Architecture
• Installation
• CLI Usage & Options
• Interactive HTML Dashboard
• Automated Fix & Prune Modes
• LCOV Coverage & Orphan Author Analysis
• CI/CD Strict Enforcement & Templates
• Ghost Score Calculation Engine
• Author
• License

Overview

Ghost Code refers to code that is syntactically valid and non-throwing, yet structurally isolated, rarely modified, untested, and virtually unreferenced within a codebase.

Unlike superficial unused import linters, Ghostcode combines AST static analysis (functions, arrow functions, class methods), Git revision metrics, LCOV test execution coverage, and author ownership tracking to evaluate code viability through a multi-factor behavioral scoring engine.

Key Features

• Deep AST Reference Analysis: Uses ts-morph to traverse inter-file import graphs, exported function declarations, arrow functions (export const fn = () => {}), and class methods.
• Interactive HTML Dashboard: Generate a standalone, single-file HTML report dashboard with live search filtering, risk meters, and code location breakdowns.
• Git History & Author Metrics: Analyzes commit frequency, modification age, and flags Orphan Code written by contributors who left or haven't committed in > 365 days.
• LCOV Test Coverage Integration: Cross-references AST symbols with lcov.info execution coverage data.
• Automated Fix & Prune Engine: --fix appends @deprecated JSDoc tags to ghost functions; --prune safely strips unreferenced internal ghost code.
• CI Strict Mode: --fail-on-high returns exit code 1 if High Risk candidates exceed configured thresholds.
• Multi-CI Templates: Built-in GitHub Actions, GitLab CI, and Bitbucket Pipelines integration templates.

Architecture

ghostcode/
├── .github/workflows/
│   └── ghostcode.yml        # GitHub Action workflow
├── templates/
│   ├── .gitlab-ci.yml       # GitLab CI pipeline template
│   └── bitbucket-pipelines.yml # Bitbucket Pipelines template
├── src/
│   ├── index.ts             # CLI entry point powered by Commander
│   ├── scanner.ts           # Core scan pipeline orchestrator
│   ├── gitAnalyzer.ts       # Git history, revision timestamp & author orphan parser
│   ├── astAnalyzer.ts       # Deep AST dependency & symbol analyzer (ts-morph)
│   ├── ghostScorer.ts       # Dynamic 6-factor Ghost Score calculation engine
│   ├── htmlReporter.ts      # Interactive HTML dashboard generator
│   ├── configLoader.ts      # Configuration file loader (.ghostcoderc)
│   ├── coverageAnalyzer.ts  # LCOV test execution coverage parser
│   ├── fixer.ts             # Automated AST fixer (@deprecated tagging & function pruning)
│   ├── reporter.ts          # Chalk terminal and JSON reporting module
│   └── types.ts             # Domain models and interface definitions
├── assets/
│   └── logo.png             # Project logo
├── dist/                    # Compiled ESM production output
├── package.json
└── tsconfig.json

Installation

Global Installation

npm install -g @fa33az/ghostcode

Run via NPX

npx @fa33az/ghostcode --threshold 70

CLI Usage & Options

ghostcode [options]

Options Reference

| Flag | Type | Default | Description | | :--- | :--- | :--- | :--- | | -p, --path <dir> | string | . | Target project directory to analyze | | -t, --threshold <number> | number | 70 | Minimum Ghost Score threshold (0–100) for candidate flagging | | -c, --config <file> | string | - | Path to custom ghostcode config file | | -i, --ignore <globs...> | string[] | - | Glob patterns to ignore (e.g. --ignore "**/vendor/**" "**/dist/**") | | --coverage <file> | string | - | Path to LCOV coverage file (e.g. coverage/lcov.info) | | --html <file> | string | - | Generate an interactive standalone HTML report (e.g. report.html) | | --orphans | boolean | false | Analyze Git author history for orphan contributors (> 365 days inactive) | | --fix | boolean | false | Automatically append @deprecated JSDoc tags to ghost functions | | --prune | boolean | false | Safely remove unreferenced internal ghost functions | | --fail-on-high [max] | number | 0 | Fail CI process (exit code 1) if High Risk candidates exceed max allowed count | | --json | boolean | false | Output results in raw JSON format | | --debug | boolean | false | Enable verbose log output | | -v, --version | boolean | - | Display version information | | -h, --help | boolean | - | Display help documentation |

Interactive HTML Dashboard

Generate a self-contained interactive HTML report dashboard:

ghostcode --html ghostcode-report.html

CI/CD Strict Enforcement & Templates

• Fail Pipeline on High Risk Code:

  ghostcode --threshold 70 --fail-on-high 0

• Built-in Pipeline Templates:

  • GitHub Actions: .github/workflows/ghostcode.yml
  • GitLab CI: templates/.gitlab-ci.yml
  • Bitbucket Pipelines: templates/bitbucket-pipelines.yml

Automated Fix & Prune Modes

• Tagging Deprecated Ghost Code:

  ghostcode --fix --threshold 70

• Safe Pruning Internal Ghost Code:

  ghostcode --prune --threshold 80

Author

Fawwaz Fadhil Rasyad

• GitHub: @fa33az

License

This project is licensed under the MIT License - see the LICENSE file for details.