projscan 0.1.11 → 0.2.0

package/README.md

@@ -8,7 +8,9 @@
 
 **Instant codebase insights — doctor, x-ray, and architecture map for any repository.**
 
-[Install](#install) · [Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](docs/GUIDE.md)
+[Install](#install) · [Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](docs/GUIDE.md) · [Roadmap](docs/ROADMAP.md)
+
+<img src="docs/hero.png" alt="projscan banner" width="600">
 
 </div>
 
@@ -28,35 +30,19 @@ Answering these manually takes 10-30 minutes of poking through config files and
 **projscan answers all of this in one command, in under 2 seconds.**
 
 ```bash
-$ projscan doctor
-
-Project Health Report
-──────────────────────────────────────────
-
-  Health Score: C (67/100)
-  Found 3 warnings, 2 info
-
-Issues Detected
-──────────────────────────────────────────
-  ⚠ No ESLint configuration
-  ⚠ No Prettier configuration
-  ⚠ No test framework detected
-  ℹ Missing .editorconfig
-  ℹ README is nearly empty
-
-  Run projscan fix to auto-fix 4 issues.
+npx projscan
 ```
 
-And it doesn't just report problems — it **fixes them**:
+<img src="docs/npx%20projscan.png" alt="npx projscan" width="700">
+
+Run `projscan doctor` for a focused health check:
 
 ```bash
-$ projscan fix -y
-✔ Installed ESLint with TypeScript support
-✔ Installed Prettier with sensible defaults
-✔ Installed Vitest with sample test
-✔ Created .editorconfig
+npx projscan doctor
 ```
 
+<img src="docs/npx%20projscan%20doctor.png" alt="npx projscan doctor" width="700">
+
 ## Install
 
 ```bash
@@ -74,15 +60,20 @@ npx projscan
 Run inside any repository:
 
 ```bash
-projscan            # Full project analysis
-projscan doctor     # Health check
-projscan fix        # Auto-fix detected issues
-projscan ci         # CI health gate (exits 1 on low score)
-projscan diff       # Compare health against a baseline
-projscan diagram    # Architecture visualization
-projscan structure  # Directory tree
+projscan                # Full project analysis
+projscan doctor         # Health check
+projscan hotspots       # Rank files by risk (churn × complexity × issues × ownership)
+projscan file <path>    # Drill into a file — purpose, risk, ownership, issues
+projscan fix            # Auto-fix detected issues
+projscan ci             # CI health gate (exits 1 on low score)
+projscan diff           # Compare health + hotspot trends against a baseline
+projscan diagram        # Architecture visualization
+projscan structure      # Directory tree
+projscan mcp            # Run as an MCP server for AI coding agents
 ```
 
+<img src="docs/npx%20projscan%20--help.png" alt="npx projscan --help" width="700">
+
 For a comprehensive walkthrough, see the **[Full Guide](docs/GUIDE.md)**.
 
 ## Commands
@@ -91,14 +82,17 @@ For a comprehensive walkthrough, see the **[Full Guide](docs/GUIDE.md)**.
 |---------|-------------|
 | `projscan analyze` | Full analysis — languages, frameworks, dependencies, issues |
 | `projscan doctor` | Health check — missing tooling, architecture smells, security risks |
+| `projscan hotspots` | Rank files by risk — churn × complexity × issues × ownership |
+| `projscan file <path>` | Drill into a file — purpose, risk, ownership, related issues |
 | `projscan fix` | Auto-fix issues (ESLint, Prettier, Vitest, .editorconfig) |
 | `projscan ci` | CI pipeline health gate — exits 1 if score below threshold |
-| `projscan diff` | Compare current health against a saved baseline |
+| `projscan diff` | Compare current health **and hotspot trends** against a baseline |
 | `projscan explain <file>` | Explain a file's purpose, imports, exports, and issues |
 | `projscan diagram` | ASCII architecture diagram of your project |
 | `projscan structure` | Directory tree with file counts |
 | `projscan dependencies` | Dependency analysis — counts, risks, recommendations |
 | `projscan badge` | Generate a health score badge for your README |
+| `projscan mcp` | Run as an MCP server for AI coding agents (Claude Code, Cursor, …) |
 
 To see all commands and options, run:
 
@@ -106,6 +100,38 @@ To see all commands and options, run:
 projscan --help
 ```
 
+### Command Screenshots
+
+<details>
+<summary><strong>projscan structure</strong> — Directory tree with file counts</summary>
+
+<img src="docs/npx%20projscan%20structure.png" alt="npx projscan structure" width="700">
+</details>
+
+<details>
+<summary><strong>projscan diagram</strong> — Architecture visualization</summary>
+
+<img src="docs/npx%20projscan%20diagram.png" alt="npx projscan diagram" width="700">
+</details>
+
+<details>
+<summary><strong>projscan dependencies</strong> — Dependency analysis</summary>
+
+<img src="docs/npx%20projscan%20dependencies.png" alt="npx projscan dependencies" width="700">
+</details>
+
+<details>
+<summary><strong>projscan explain</strong> — File explanation</summary>
+
+<img src="docs/npx%20projscan%20explain.png" alt="npx projscan explain" width="700">
+</details>
+
+<details>
+<summary><strong>projscan badge</strong> — Health badge generation</summary>
+
+<img src="docs/npx%20projscan%20badge.png" alt="npx projscan badge" width="700">
+</details>
+
 ### Output Formats
 
 All commands support `--format` for different output targets:
@@ -147,6 +173,8 @@ projscan badge
 
 This outputs a [shields.io](https://shields.io) badge URL and markdown snippet you can paste into your README.
 
+**Sample badge:** [![projscan health](https://img.shields.io/badge/projscan-D-orange)](https://github.com/abhiyoheswaran1/projscan)
+
 ## What It Detects
 
 **Languages**: TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, C/C++, PHP, Swift, Kotlin, and 20+ more
@@ -180,6 +208,8 @@ projscan ci --min-score 70          # Exits 1 if score < 70
 projscan ci --min-score 80 --format json  # JSON output for parsing
 ```
 
+<img src="docs/npx%20projscan%20ci%20--min-score%2070.png" alt="npx projscan ci --min-score 70" width="700">
+
 ### GitHub Actions
 
 Copy the included workflow template to your project:
@@ -201,10 +231,89 @@ projscan diff                       # Compare against baseline
 projscan diff --format markdown     # Markdown diff for PRs
 ```
 
+<img src="docs/npx%20projscan%20diff%20--save-baseline.png" alt="npx projscan diff --save-baseline" width="700">
+
+## Hotspots — Where to Fix First
+
+A flat health score doesn't tell you what to do. **`projscan hotspots`** combines `git log` churn, file complexity, open issues, recency, and **ownership** into a single risk score per file — so you know where refactoring or review will actually pay off.
+
+```bash
+projscan hotspots                       # Top 10 hotspots
+projscan hotspots --limit 20
+projscan hotspots --since "6 months ago"
+projscan hotspots --format json         # Machine-readable for dashboards
+projscan hotspots --format markdown     # Drop into a PR or tech-debt ticket
+```
+
+Hotspot ranking follows the classic Feathers "churn × complexity" heuristic with boosts for files that fail `projscan doctor`, changed recently, or show **bus factor 1** (single-author + high churn). Falls back gracefully outside a git repo.
+
+### Drill Into a Hotspot
+
+```bash
+projscan file src/cli/index.ts
+```
+
+Combines the file's purpose, imports, exports, hotspot risk, ownership, and every open issue that references it — the natural follow-up to `projscan hotspots`.
+
+### Track Trends Over Time
+
+```bash
+projscan diff --save-baseline           # Snapshots health + hotspots
+# ...time passes, commits happen...
+projscan diff                           # Shows which hotspots rose / fell
+```
+
+The baseline file now captures top hotspots too, so `diff` surfaces files that are **getting worse** (not just new issues).
+
+## AI Agent Integration (MCP)
+
+**`projscan mcp`** starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query projscan during a session.
+
+**Tools** (7):
+- `projscan_analyze` — full project report
+- `projscan_doctor` — health score + issues
+- `projscan_hotspots` — risk-ranked files (with `limit`, `since` args)
+- `projscan_file` — per-file risk + ownership + related issues
+- `projscan_explain` — per-file purpose, imports, exports, smells
+- `projscan_structure` — directory tree
+- `projscan_dependencies` — package audit
+
+**Prompts** (2, parameterized with live project data):
+- `prioritize_refactoring` — ranked plan grounded in current hotspots
+- `investigate_file` — senior-engineer brief for a specific file
+
+**Resources** (3, readable on demand):
+- `projscan://health` · `projscan://hotspots` · `projscan://structure`
+
+### Claude Code
+
+```bash
+claude mcp add projscan -- npx projscan mcp
+```
+
+### Cursor / Windsurf / any MCP client
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "projscan": {
+      "command": "npx",
+      "args": ["projscan", "mcp"]
+    }
+  }
+}
+```
+
+Now your agent can ask *"what are the riskiest files in this repo?"* and get a grounded answer, or run `projscan_doctor` before proposing an edit.
+
 ## Use Cases
 
 - **Onboarding**: Understand any codebase in seconds, not hours
 - **Code reviews**: Run `projscan doctor --format markdown` and paste into PRs
+- **Tech-debt prioritization**: Use `projscan hotspots` to decide what deserves refactoring time
+- **AI-assisted development**: Mount `projscan mcp` in your agent of choice for grounded edits
 - **CI/CD**: Use `projscan ci` to enforce health standards in your pipeline
 - **Security**: Catch committed secrets and `.env` files before they reach production
 - **Consulting**: Quickly assess client projects before diving in

package/dist/cli/index.js

@@ -14,14 +14,17 @@ import { detectLanguages } from '../core/languageDetector.js';
 import { detectFrameworks } from '../core/frameworkDetector.js';
 import { analyzeDependencies } from '../core/dependencyAnalyzer.js';
 import { collectIssues } from '../core/issueEngine.js';
+import { analyzeHotspots } from '../core/hotspotAnalyzer.js';
+import { inspectFile, extractImports, extractExports, inferPurpose, detectFileIssues, } from '../core/fileInspector.js';
 import { getAllAvailableFixes } from '../fixes/fixRegistry.js';
 import { setLogLevel } from '../utils/logger.js';
 import { calculateScore, badgeUrl, badgeMarkdown } from '../utils/scoreCalculator.js';
 import { showBanner, showCompactBanner, showHelp } from '../utils/banner.js';
 import { saveBaseline, loadBaseline, computeDiff } from '../utils/baseline.js';
-import { reportAnalysis, reportHealth, reportCi, reportDiff, reportDetectedIssues, reportExplanation, reportDiagram, reportStructure, reportDependencies, } from '../reporters/consoleReporter.js';
-import { reportAnalysisJson, reportHealthJson, reportCiJson, reportDiffJson, reportExplanationJson, reportDiagramJson, reportStructureJson, reportDependenciesJson, } from '../reporters/jsonReporter.js';
-import { reportAnalysisMarkdown, reportHealthMarkdown, reportCiMarkdown, reportDiffMarkdown, reportExplanationMarkdown, reportDiagramMarkdown, reportStructureMarkdown, reportDependenciesMarkdown, } from '../reporters/markdownReporter.js';
+import { runMcpServer } from '../mcp/server.js';
+import { reportAnalysis, reportHealth, reportCi, reportDiff, reportDetectedIssues, reportExplanation, reportDiagram, reportStructure, reportDependencies, reportHotspots, reportFileInspection, } from '../reporters/consoleReporter.js';
+import { reportAnalysisJson, reportHealthJson, reportCiJson, reportDiffJson, reportExplanationJson, reportDiagramJson, reportStructureJson, reportDependenciesJson, reportHotspotsJson, reportFileJson, } from '../reporters/jsonReporter.js';
+import { reportAnalysisMarkdown, reportHealthMarkdown, reportCiMarkdown, reportDiffMarkdown, reportExplanationMarkdown, reportDiagramMarkdown, reportStructureMarkdown, reportDependenciesMarkdown, reportHotspotsMarkdown, reportFileMarkdown, } from '../reporters/markdownReporter.js';
 // ── CLI Setup ─────────────────────────────────────────────
 const program = new Command();
 program
@@ -205,12 +208,19 @@ program
     try {
         const scan = await scanRepository(rootPath);
         const issues = await collectIssues(rootPath, scan.files);
+        const hotspotReport = await analyzeHotspots(rootPath, scan.files, issues, { limit: 20 });
         if (cmdOpts.saveBaseline) {
-            const filePath = await saveBaseline(rootPath, issues);
+            const filePath = await saveBaseline(rootPath, issues, hotspotReport);
             const { score, grade } = calculateScore(issues);
             console.log(chalk.green(`\n  Baseline saved to ${filePath}`));
             console.log(`  Score: ${chalk.bold(`${grade} (${score}/100)`)}`);
-            console.log(`  Issues: ${issues.length}\n`);
+            console.log(`  Issues: ${issues.length}`);
+            if (hotspotReport.available) {
+                console.log(`  Hotspots snapshotted: ${hotspotReport.hotspots.length}\n`);
+            }
+            else {
+                console.log('');
+            }
             return;
         }
         let baseline;
@@ -222,7 +232,7 @@ program
             console.error(`  Run ${chalk.bold.cyan('projscan diff --save-baseline')} first to create one.\n`);
             process.exit(1);
         }
-        const diff = computeDiff(baseline, issues);
+        const diff = computeDiff(baseline, issues, hotspotReport);
         switch (format) {
             case 'json':
                 reportDiffJson(diff);
@@ -299,6 +309,42 @@ program
         process.exit(1);
     }
 });
+// ── Command: file ─────────────────────────────────────────
+program
+    .command('file <file>')
+    .description('Drill into a file — purpose, risk, ownership, related issues')
+    .action(async (filePath) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    const spinner = format === 'console' ? ora('Inspecting file...').start() : null;
+    try {
+        const inspection = await inspectFile(rootPath, filePath);
+        if (spinner)
+            spinner.stop();
+        if (!inspection.exists) {
+            console.error(chalk.red(`\n  ${inspection.reason ?? 'File unavailable'}: ${filePath}\n`));
+            process.exit(1);
+        }
+        switch (format) {
+            case 'json':
+                reportFileJson(inspection);
+                break;
+            case 'markdown':
+                reportFileMarkdown(inspection);
+                break;
+            default:
+                reportFileInspection(inspection);
+        }
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail('File inspection failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
 // ── Command: explain ──────────────────────────────────────
 program
     .command('explain <file>')
@@ -434,6 +480,61 @@ program
         process.exit(1);
     }
 });
+// ── Command: hotspots ─────────────────────────────────────
+program
+    .command('hotspots')
+    .description('Rank files by risk (git churn × complexity × open issues)')
+    .option('--limit <n>', 'number of hotspots to show', '10')
+    .option('--since <when>', 'git history window (e.g. "6 months ago", "2024-01-01")', '12 months ago')
+    .action(async (cmdOpts) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    const spinner = format === 'console' ? ora('Analyzing hotspots...').start() : null;
+    try {
+        const scan = await scanRepository(rootPath);
+        const issues = await collectIssues(rootPath, scan.files);
+        const limit = Math.max(1, Math.min(100, parseInt(cmdOpts.limit, 10) || 10));
+        const report = await analyzeHotspots(rootPath, scan.files, issues, {
+            since: cmdOpts.since,
+            limit,
+        });
+        if (spinner)
+            spinner.stop();
+        switch (format) {
+            case 'json':
+                reportHotspotsJson(report);
+                break;
+            case 'markdown':
+                reportHotspotsMarkdown(report);
+                break;
+            default:
+                reportHotspots(report);
+        }
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail('Hotspot analysis failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+// ── Command: mcp ──────────────────────────────────────────
+program
+    .command('mcp')
+    .description('Run projscan as an MCP server (stdio) for AI coding agents')
+    .action(async () => {
+    setLogLevel('quiet');
+    const rootPath = getRootPath();
+    try {
+        await runMcpServer(rootPath);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
 // ── Command: badge ────────────────────────────────────────
 program
     .command('badge')
@@ -473,7 +574,7 @@ function analyzeFile(filePath, content) {
     const lines = content.split('\n');
     const imports = extractImports(content);
     const exports = extractExports(content);
-    const purpose = inferPurpose(filePath, imports, exports);
+    const purpose = inferPurpose(filePath, exports);
     const potentialIssues = detectFileIssues(content, lines.length);
     return {
         filePath: path.relative(process.cwd(), filePath),
@@ -484,143 +585,6 @@ function analyzeFile(filePath, content) {
         lineCount: lines.length,
     };
 }
-function extractImports(content) {
-    const imports = [];
-    const seen = new Set();
-    // ES import
-    const esImportRegex = /import\s+(?:(?:\{[^}]*\}|[\w*]+(?:\s*,\s*\{[^}]*\})?|\*\s+as\s+\w+)\s+from\s+)?['"]([^'"]+)['"]/gm;
-    let match;
-    while ((match = esImportRegex.exec(content)) !== null) {
-        const source = match[1];
-        if (!seen.has(source)) {
-            seen.add(source);
-            imports.push({
-                source,
-                specifiers: [],
-                isRelative: source.startsWith('.') || source.startsWith('/'),
-            });
-        }
-    }
-    // CommonJS require
-    const requireRegex = /(?:const|let|var)\s+(?:\{[^}]*\}|\w+)\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/gm;
-    while ((match = requireRegex.exec(content)) !== null) {
-        const source = match[1];
-        if (!seen.has(source)) {
-            seen.add(source);
-            imports.push({
-                source,
-                specifiers: [],
-                isRelative: source.startsWith('.') || source.startsWith('/'),
-            });
-        }
-    }
-    return imports;
-}
-function extractExports(content) {
-    const exports = [];
-    // export function
-    const funcRegex = /^export\s+(?:async\s+)?function\s+(\w+)/gm;
-    let match;
-    while ((match = funcRegex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'function' });
-    }
-    // export class
-    const classRegex = /^export\s+class\s+(\w+)/gm;
-    while ((match = classRegex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'class' });
-    }
-    // export const/let/var
-    const varRegex = /^export\s+(?:const|let|var)\s+(\w+)/gm;
-    while ((match = varRegex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'variable' });
-    }
-    // export interface
-    const interfaceRegex = /^export\s+interface\s+(\w+)/gm;
-    while ((match = interfaceRegex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'interface' });
-    }
-    // export type
-    const typeRegex = /^export\s+type\s+(\w+)/gm;
-    while ((match = typeRegex.exec(content)) !== null) {
-        exports.push({ name: match[1], type: 'type' });
-    }
-    // export default
-    if (/^export\s+default/m.test(content)) {
-        exports.push({ name: 'default', type: 'default' });
-    }
-    return exports;
-}
-function inferPurpose(filePath, imports, exports) {
-    const name = path.basename(filePath, path.extname(filePath)).toLowerCase();
-    const dir = path.dirname(filePath).toLowerCase();
-    if (name.includes('test') || name.includes('spec'))
-        return 'Test file';
-    if (name.includes('config') || name.includes('rc'))
-        return 'Configuration file';
-    if (name === 'index')
-        return 'Module entry point / barrel file';
-    if (name === 'main' || name === 'app')
-        return 'Application entry point';
-    if (name.includes('route') || name.includes('router'))
-        return 'Route definitions';
-    if (name.includes('middleware'))
-        return 'Middleware handler';
-    if (name.includes('controller'))
-        return 'Request controller';
-    if (name.includes('service'))
-        return 'Service layer logic';
-    if (name.includes('model') || name.includes('schema'))
-        return 'Data model / schema definition';
-    if (name.includes('util') || name.includes('helper'))
-        return 'Utility functions';
-    if (name.includes('hook'))
-        return 'Custom hook';
-    if (name.includes('context') || name.includes('provider'))
-        return 'Context / state provider';
-    if (name.includes('type') || name.includes('interface'))
-        return 'Type definitions';
-    if (name.includes('constant') || name.includes('config'))
-        return 'Constants / configuration';
-    if (name.includes('migration'))
-        return 'Database migration';
-    if (name.includes('seed'))
-        return 'Database seed data';
-    if (name.includes('auth'))
-        return 'Authentication logic';
-    if (name.includes('api'))
-        return 'API endpoint handler';
-    if (dir.includes('component') || dir.includes('pages'))
-        return 'UI component';
-    if (dir.includes('service'))
-        return 'Service module';
-    if (dir.includes('model'))
-        return 'Data model';
-    if (dir.includes('util') || dir.includes('lib'))
-        return 'Library / utility module';
-    const exportTypes = exports.map((e) => e.type);
-    if (exportTypes.includes('class'))
-        return 'Class-based module';
-    if (exportTypes.filter((t) => t === 'function').length > 2)
-        return 'Function library';
-    return 'Source module';
-}
-function detectFileIssues(content, lineCount) {
-    const issues = [];
-    if (lineCount > 500)
-        issues.push(`Large file (${lineCount} lines) — consider splitting`);
-    if (lineCount > 1000)
-        issues.push('Very large file — strongly consider refactoring');
-    if (/console\.(log|warn|error|debug)\s*\(/.test(content)) {
-        issues.push('Contains console.log statements — consider using a proper logger');
-    }
-    if (/TODO|FIXME|HACK|XXX/i.test(content)) {
-        issues.push('Contains TODO/FIXME comments');
-    }
-    if (/any\b/.test(content) && /\.tsx?$/.test(content)) {
-        issues.push('Uses "any" type — consider using proper types');
-    }
-    return issues;
-}
 // ── Architecture Layer Detection ──────────────────────────
 function buildArchitectureLayers(files, frameworkNames) {
     const layers = [];