🕵️ git-detective

Forensic Git Repository Inspector & Developer Habits Auditor — Investigate your commit history like a crime scene.

git-detective is an interactive CLI forensic audit suite designed for Git repositories. Rather than surfacing traditional, dry analytics, it treats your version control history like an active crime scene.

It audits local commit histories, inspects diffs, uncovers deceptive commit messages ("Git Perjury"), traces dangerous code churn in "High-Crime Neighborhoods," interrogates developers with interactive cross-examinations, and exports complete dark-mode case dossiers.

📸 Terminal Evidence Preview

   _____ _____ _____    ____  ______ _______ ______ _____ _______ _____ _    _ ______ 
  / ____|_   _|_   _|  |  _ \|  ____|__   __|  ____/ ____|__   __|_   _| |  | |  ____|
 | |  __  | |   | |    | | | | |__     | |  | |__ | |       | |    | | | |  | | |__   
 | | |_ | | |   | |    | | | |  __|    | |  |  __|| |       | |    | | | |  | |  __|  
 | |__| |_| |_ _| |_   | |_| | |____   | |  | |___| |____   | |   _| |_| |__| | |____ 
  \_____|_____|_____|  |____/|______|  |_|  |______\_____|  |_|  |_____|\____/|______|

 🚧 🚧 🚧  CRIME SCENE INVESTIGATION // CONFIDENTIAL DOSSIER  🚧 🚧 🚧 

╔══════════════════════════════════════════════════════════════════╗
║ CASE TYPE: FULL FORENSIC AUDIT                                   ║
║ ──────────────────────────────────────────────────────────────── ║
║   📦 Evidence Base:       184 analyzed commits                   ║
║   👥 Total Persons:       3 active contributor(s)                ║
║   👤 Prime Suspect:       alex-dev (112 commits)                 ║
║   🌙 Night Violations:    ⚠️  24 commits (12:00 AM – 5:00 AM)    ║
║   📅 Weekend Raids:       38 commits                             ║
║   🚨 Panic Signals:       14 flagged commits                     ║
║   🤥 Perjury / Lies:      2 fraudulent commit claims             ║
║ ──────────────────────────────────────────────────────────────── ║
║ ⚖️  LIE DETECTOR PERJURY CONVICTION:                             ║
║   Claim:    "quick typo fix"                                     ║
║   Reality:  +412 / -189 across 9 files                           ║
║   Suspect:  alex-dev (e7a9c12)                                   ║
║ ──────────────────────────────────────────────────────────────── ║
║ 📍 HIGH-CRIME NEIGHBORHOODS (Most Touched Files):                ║
║   • src/services/auth.js (42 modifications)                      ║
║   • src/index.js (29 modifications)                              ║
║ ──────────────────────────────────────────────────────────────── ║
║ 📂 MOST WANTED LIST (Contributor Activity):                      ║
║ ┌──────────────────────┬───────────┬───────────┬───────────┐     ║
║ │ Suspect              │ Commits   │ 🌙 Night  │ 🤥 Lies   │     ║
║ ├──────────────────────┼───────────┼───────────┼───────────┤     ║
║ │ alex-dev             │ 112       │ 18        │ 2         │     ║
║ │ sam-code             │ 48        │ 6         │ 0         │     ║
║ └──────────────────────┴───────────┴───────────┴───────────┘     ║
║ ──────────────────────────────────────────────────────────────── ║
║ Repo Integrity Index:  [████████████░░░░░░░░░░░░] 52%            ║
║                                                                  ║
║ DETECTIVE VERDICT:                                               ║
║ "The Deceptive Architect: Writes 'quick typo fix' while          ║
║  rewriting the entire backend."                                  ║
╚══════════════════════════════════════════════════════════════════╝

⚡ Quick Start

Run instantly without installation inside any local Git repository:

npx git-detective

Or install globally to use anywhere across your system:

# Using npm
npm install -g git-detective

# Using pnpm
pnpm add -g git-detective

# Using yarn
yarn global add git-detective

🔍 Core Features & Commands

1. Forensic Repository Audit (audit)

The default command inspects local commit logs, timestamps, message keywords, and diff stats.

# Standard investigation (last 300 commits)
git-detective

# Deep investigation into large histories
git-detective audit --limit 1000

# Target investigation to an individual developer
git-detective audit --suspect "john"

• 🤥 Git Lie Detector: Catches fraudulent commits claiming to be small (e.g., "just a tiny typo", "quick fix") when the diff actually altered hundreds of lines across multiple files.
• 🌙 Graveyard Shifts: Detects late-night commits pushed between 12:00 AM and 5:00 AM.
• 🚨 Panic Pattern Matching: Flags signs of technical debt and distress (fix, temp, wip, revert, oops, broken).
• 📍 High-Crime Neighborhoods: Ranks high-churn files that are modified repeatedly, highlighting fragile architecture hotspots.
• 📋 Most Wanted List: Summarizes team contributions into a clear comparative breakdown table.

2. Standalone HTML Dossier Export (--export-html)

Generate an offline, shareable dark-mode report you can view in your browser or attach to project documentation.

# Export to default git-detective-report.html
git-detective --export-html

# Export to a custom destination
git-detective --export-html my-team-audit.html

3. File Crime Scene Blame (blame <file>)

Run single-file line-by-line forensics using git blame to diagnose single points of failure and project code ownership.

git-detective blame src/services/auth.js
git-detective blame package.json

Outputs total line counts, percentage ownership per author, and single-point-of-failure risk warnings.

4. Interactive Interrogation Mode (interrogate)

Step into the detective's interrogation room. An interactive, terminal-driven questioning module that evaluates developer discipline and computes a final Guilt Index.

git-detective interrogate

🧩 Scoring & Diagnostics Engine

Repository Health is evaluated on a weighted penalty algorithm:

| Category | Impact | Trigger Criteria | | :--- | :--- | :--- | | Base Score | Starts at 100% | Baseline clean repository state | | Panic Penalty | Up to -40% | Proportion of commit messages matching distress keywords | | Graveyard Penalty| Up to -20% | Frequency of commits pushed between 12:00 AM and 5:00 AM | | Perjury Penalty | -10% per lie | Downplayed commit messages with large diff alterations | | Score Floor | Capped at 10% | Acknowledging that version control was used |

🏗️ Architecture & File Structure

git-detective/
├── bin/
│   └── index.js             # CLI binary entry point & subcommands registration
├── src/
│   ├── commands/
│   │   ├── audit.js         # Core repository audit runner
│   │   ├── blame.js         # Targeted git-blame file inspector
│   │   └── interrogate.js   # Interactive terminal questioning engine
│   ├── core/
│   │   ├── analyzer.js      # Lie detection, hotspot ranking, scoring rules
│   │   ├── git.js           # simple-git abstraction layer & validation
│   │   └── patterns.js      # Regex dictionary for panic signals & downplaying
│   ├── ui/
│   │   ├── ascii.js         # ASCII art banners and police tape dividers
│   │   ├── html-exporter.js # Self-contained HTML report generator
│   │   └── reporter.js      # Boxen and cli-table3 visual layout
│   └── utils/
│       └── formatters.js    # Progress bar and string clipping utilities
├── .gitignore
├── package.json
└── README.md

🛠️ CLI Options Reference

| Command / Option | Flag | Description | Default | | :--- | :--- | :--- | :--- | | audit | — | Run full repository forensic audit | Default command | | --limit <number> | -l | Number of commits to evaluate | 300 | | --suspect <name> | -s | Target investigation to a specific author | All authors | | --export-html [file] | — | Export evidence dossier to HTML | git-detective-report.html | | blame <file> | — | Investigate author line ownership on a file | — | | interrogate | — | Launch interactive terminal interrogation | — | | --version | -V | Output current CLI version | — | | --help | -h | Display available help and flags | — |

💻 Local Development Setup

To contribute to or extend the tool locally:

# 1. Clone the repository
git clone [https://github.com/](https://github.com/)<your-username>/git-detective.git
cd git-detective

# 2. Install dependencies
npm install

# 3. Create a local symlink for the binary
npm link

# 4. Test run locally
git-detective
git-detective interrogate
git-detective blame package.json

To unlink the local development binary:

npm unlink -g git-detective

🔒 Privacy & Local Execution

• 100% Local Execution: Analyzes local Git logs strictly via simple-git.
• Zero External Telemetry: No third-party APIs, external servers, or tokens are required.
• No Code Exposure: Your code never leaves your workstation.

📄 License

Distributed under the MIT License. See LICENSE for details.