🔬 Copilot Autopsy: AI-Powered Repository Forensics

*This is a submission for the [GitHub Copilot CLI Challenge](https://dev.to/challenges/github-2026-01-21)* ## What I Built **Copilot Autopsy** is a terminal-first forensic analysis tool that performs deep "autopsies" of any GitHub repository using **GitHub Copilot CLI** as the AI reasoning engine. > 💡 Unlike traditional linters that just list problems, Copilot Autopsy explains **WHY** issues exist—powered entirely by GitHub Copilot CLI. ### ✨ The Problem It Solves Developers run linters and get a list like: ``` ❌ "Function too long" → But WHY? ❌ "Possible SQL injection" → But HOW do I fix it? ❌ "Missing tests" → But WHICH functions first? ``` **Copilot Autopsy** fixes this with AI-powered context: ``` ✅ Explains the ROOT CAUSE of each issue ✅ Provides CONTEXT-AWARE fixes with code examples ✅ Prioritizes findings by SEVERITY and IMPACT ✅ Generates a beautiful AUTOPSY.md report ``` --- ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ COPILOT AUTOPSY CLI │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Scanner │──▶│ Analyzer │──▶│Aggregator│──▶│ Reporter │ │ │ │ Module │ │ Module │ │ Module │ │ Module │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Detect │ │ GitHub │ │ AUTOPSY │ │ │ │ Language │ │ Copilot │ │ .md │ │ │ │Framework │ │ CLI ⭐ │ │ Report │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 📁 Project Structure ``` copilot-autopsy/ ├── 📄 bin/ │ └── copilot-autopsy.js # CLI entry point ├── 📁 src/ │ ├── cli.js # Commander.js setup │ ├── index.js # Main orchestrator │ ├── 📁 ui/ # Terminal UI components │ │ ├── banner.js # ASCII art banner │ │ └── progress.js # Progress bars & summary │ ├── 📁 scanner/ # Project detection │ │ ├── index.js # Scanner orchestrator │ │ ├── 📁 detectors/ │ │ │ ├── language.js # Language detection │ │ │ ├── framework.js # Framework detection │ │ │ └── tooling.js # Tooling detection │ │ └── 📁 collectors/ │ │ ├── files.js # Smart file prioritization │ │ └── dependencies.js # Dependency parser │ ├── 📁 analyzer/ # 🌟 AI analysis engine │ │ ├── index.js # Analyzer orchestrator │ │ ├── copilot.js # GitHub Copilot CLI wrapper │ │ ├── 📁 prompts/ │ │ │ └── templates.js # 6 specialized prompts │ │ └── 📁 analyzers/ │ │ ├── quality.js # Code quality analyzer │ │ ├── security.js # Security analyzer (CWE) │ │ ├── architecture.js # Architecture analyzer │ │ ├── testing.js # Test gap analyzer │ │ └── documentation.js# Documentation analyzer │ ├── 📁 aggregator/ │ │ └── index.js # Deduplication & scoring │ └── 📁 reporter/ │ └── index.js # AUTOPSY.md generator ├── 📄 package.json └── 📄 README.md ``` --- ## 🎯 Features | Feature | Description | |---------|-------------| | 🔍 **Auto-Detection** | Detects language, framework, tooling automatically | | 📝 **Code Quality** | Finds code smells, SOLID violations, complexity | | 🔒 **Security** | Vulnerabilities with CWE references | | 🏗️ **Architecture** | Circular dependencies, coupling issues | | 🧪 **Testing** | Missing tests, coverage gaps | | 📚 **Documentation** | README and JSDoc analysis | | 📊 **Health Score** | 0-100 score with visualization | | 📋 **Report** | Beautiful AUTOPSY.md with action items | | 🎨 **Beautiful UI** | ASCII art, progress bars, colors | --- ## 🎬 Demo ### Installation #### 1. Install GitHub CLI **macOS:** ```bash brew install gh ``` **Linux (Debian/Ubuntu):** ```bash sudo apt install gh ``` **Windows (choose one):** ```powershell # Option 1: winget winget install --id GitHub.cli # Option 2: Chocolatey choco install gh # Option 3: Scoop scoop install gh # Option 4: Download from https://cli.github.com/ ``` #### 2. Setup Copilot CLI > ⚠️ **IMPORTANT:** GitHub CLI and Copilot CLI are **separate**. You must install Copilot as an extension! ```bash # Login to GitHub gh auth login # Verify login gh auth status # Install Copilot CLI extension gh extension install github/gh-copilot ``` **Windows users:** When installing Copilot, you'll see: ``` ? Authenticate Git with your GitHub credentials? (Y/n) y ! First copy your one-time code: XXXX-XXXX Press Enter to open browser... ✓ Authentication complete. ``` ```bash # Verify Copilot works gh copilot -p "test" ``` #### 3. Install Copilot Autopsy ```bash # Clone the repository git clone https://github.com/xdarwin13/copilot-autopsy.git cd copilot-autopsy # Install dependencies npm install # Install globally npm install -g . # Run on any repo! autopsy ``` --- ### Terminal Output ``` ____ _ _ _ _ _ / ___|___ _ __ (_) | ___ | |_ / \ _ _| |_ ___ _ __ ___ _ _ | | / _ \| '_ \| | |/ _ \| __| / _ \| | | | __/ _ \| '_ \/ __| | | | | |__| (_) | |_) | | | (_) | |_ / ___ \ |_| | || (_) | |_) \__ \ |_| | \____\___/| .__/|_|_|\___/ \__/_/ \_\__,_|\__\___/| .__/|___/\__, | |_| |_| |___/ ╭───────────────────────────────────────────────────────────╮ │ 🔬 Repository Forensics • Powered by GitHub Copilot CLI │ ╰───────────────────────────────────────────────────────────╯ 📊 PROJECT DETECTION ──────────────────────────────────────── ✓ Language: TypeScript (78%), JavaScript (22%) ✓ Framework: Next.js + React ✓ Tooling: ESLint, Prettier, Jest, GitHub Actions ✓ Files: 142 total (47 source) 🤖 COPILOT ANALYSIS Powered by GitHub Copilot CLI ✓ 📝 Code Quality: 5 findings ✓ 🔒 Security: 2 findings ✓ 🏗️ Architecture: 3 findings ✓ 🧪 Testing: 4 findings ✓ 📚 Documentation: 2 findings ╭────────────────────────────────╮ │ │ │ 📋 AUTOPSY COMPLETE │ │ │ │ Health Score: 72/100 │ │ ██████████████░░░░░░ 72% │ │ │ │ 🔴 Critical: 1 🟠 High: 3 │ │ 🟡 Medium: 8 🟢 Low: 4 │ │ │ │ Duration: 45.2s │ │ Copilot CLI calls: 18 │ │ │ ╰────────────────────────────────╯ ``` --- ### Sample AUTOPSY.md Report ```markdown # 🔬 Repository Autopsy Report ## 📊 Executive Summary | Metric | Value | |--------|-------| | **Repository** | `my-project` | | **Primary Language** | TypeScript | | **Framework** | Next.js | | **Health Score** | 72/100 | ### Health Score: 72/100 ████████████████░░░░░░ 72% ## 🔍 Detailed Findings ### 🔒 Security Vulnerabilities #### SEC-001: SQL Injection Risk | Property | Value | |----------|-------| | **Severity** | 🔴 CRITICAL | | **Location** | `src/api/users.ts:45` | **Description:** User input is directly concatenated into SQL query. **Why This Matters:** Attackers can manipulate the query to access or delete data. **Suggested Fix:** Use parameterized queries or an ORM. ``` --- ## 🔧 CLI Options | Option | Description | Default | |--------|-------------|---------| | `--depth` | `quick`, `standard`, `deep` | `standard` | | `--focus` | `security`, `quality`, `architecture`, `testing`, `docs`, `all` | `all` | | `--path` | Target repository path | `.` | | `--output` | Output file name | `AUTOPSY.md` | | `--verbose` | Show Copilot CLI calls | `false` | | `--fix` | Include code fix examples | `false` | --- ## 💡 My Experience with GitHub Copilot CLI ### The Core Integration **GitHub Copilot CLI is the brain of this project.** Without it, Copilot Autopsy would have zero intelligence. ```javascript // src/analyzer/copilot.js - The heart of the tool class CopilotCLI { async query(prompt) { // Send prompt to GitHub Copilot CLI const result = execSync( `gh copilot -p ${JSON.stringify(prompt)}`, { encoding: 'utf-8', timeout: 120000 } ); return this.parseResponse(result); } } ``` ### Prompt Engineering I designed **6 specialized prompts** for different analysis types: ```javascript // Quality Analysis Prompt const QUALITY_PROMPT = ` You are a senior code reviewer performing forensic analysis. FILE: ${file.path} \`\`\`${language} ${content} \`\`\` Analyze for: 1. Code smells (long methods, deep nesting) 2. SOLID violations 3. DRY violations 4. Complexity issues For EACH issue, respond: [QUAL-NNN] SEVERITY | LINE | Description | Why | Fix `; ``` ### The "Why" Analysis - Unique Feature What makes Copilot Autopsy special is the **root cause analysis**: ```javascript // Root Cause Prompt const ROOT_CAUSE_PROMPT = ` Explain WHY this code issue exists, not just WHAT it is. FINDING: ${finding.description} CODE: ${codeContext} Explain in 2-3 sentences: 1. The likely reason this was introduced 2. The technical debt it creates 3. The fix priority `; ``` This gives developers **context** instead of just a list of problems. ### Orchestration Strategy I orchestrate **15-20 Copilot CLI calls** into one coherent report: ``` Phase 1 (Parallel): Phase 2: Phase 3: Phase 4: ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Quality │ │Architecture │ │ Root Cause │ │ Report │ │ Security │────────▶│ Analysis │──▶│ Analysis │──▶│ Generation │ │ Docs │ │ │ │ (critical) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ``` ### What I Learned 1. **Copilot CLI handles complex prompts well** - Even 2000+ character prompts work 2. **Rate limiting is important** - Added 1.5s delays between calls 3. **Response parsing requires creativity** - Structured prompts help 4. **The `-p` flag is powerful** - Use `gh copilot -p "prompt"` for non-interactive mode --- ## 🏆 Why This Project? 1. **Linters tell you WHAT, not WHY** - Copilot CLI adds context 2. **Code reviews are time-consuming** - Automate the first pass 3. **Security scanning is often shallow** - AI understands intent 4. **Onboarding is hard** - Health Score gives quick overview --- ## 📦 Tech Stack | Component | Technology | |-----------|------------| | Runtime | Node.js 18+ | | CLI Framework | Commander.js | | Terminal UI | Chalk, Ora, Boxen | | AI Engine | **GitHub Copilot CLI** ⭐ | | Templating | Handlebars | --- ## 🔗 Links - **GitHub:** [github.com/xdarwin13/copilot-autopsy](https://github.com/xdarwin13/copilot-autopsy) --- ## 🙏 Acknowledgments Built with ❤️ for the **GitHub Copilot CLI Challenge 2026** Special thanks to the GitHub Copilot team for creating such a powerful CLI tool! --- *⭐ If you found this useful, give it a star on GitHub! ⭐*