projscan 0.1.13 → 0.3.0

package/dist/cli/index.js

@@ -14,33 +14,74 @@ 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 { loadConfig, applyConfigToIssues } from '../utils/config.js';
+import { getChangedFiles } from '../utils/changedFiles.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';
+import { reportAnalysisSarif, reportHealthSarif, reportCiSarif, } from '../reporters/sarifReporter.js';
 // ── CLI Setup ─────────────────────────────────────────────
 const program = new Command();
 program
     .name('projscan')
     .description('Instant codebase insights — doctor, x-ray, and architecture map for any repository')
     .version(pkg.version)
-    .option('--format <type>', 'output format: console, json, markdown', 'console')
+    .option('--format <type>', 'output format: console, json, markdown, sarif', 'console')
+    .option('--config <path>', 'path to .projscanrc config file')
     .option('--verbose', 'enable verbose output')
     .option('--quiet', 'suppress non-essential output');
 function getFormat() {
     const opts = program.opts();
     const f = opts.format;
-    if (f === 'json' || f === 'markdown')
+    if (f === 'json' || f === 'markdown' || f === 'sarif')
         return f;
     return 'console';
 }
 function getRootPath() {
     return process.cwd();
 }
+async function loadProjectConfig() {
+    const opts = program.opts();
+    const explicit = typeof opts.config === 'string' ? opts.config : undefined;
+    try {
+        const { config, source } = await loadConfig(getRootPath(), explicit);
+        if (source && !opts.quiet && getFormat() === 'console') {
+            console.error(chalk.dim(`  [config: ${path.relative(getRootPath(), source) || source}]`));
+        }
+        return config;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`  Config error: ${msg}`));
+        process.exit(1);
+    }
+}
+async function filterIssuesByChangedFiles(issues, rootPath, baseRef) {
+    const result = await getChangedFiles(rootPath, baseRef);
+    if (!result.available) {
+        if (getFormat() === 'console' && !program.opts().quiet) {
+            console.error(chalk.yellow(`  [--changed-only: ${result.reason ?? 'unavailable'} — reporting all issues]`));
+        }
+        return issues;
+    }
+    if (getFormat() === 'console' && !program.opts().quiet) {
+        console.error(chalk.dim(`  [--changed-only: base=${result.baseRef}, ${result.files.length} file(s)]`));
+    }
+    const set = new Set(result.files);
+    return issues.filter((issue) => {
+        if (!issue.locations || issue.locations.length === 0)
+            return false;
+        return issue.locations.some((loc) => set.has(loc.file));
+    });
+}
 function setupLogLevel() {
     const opts = program.opts();
     if (opts.verbose)
@@ -74,14 +115,17 @@ function maybeCompactBanner() {
 program
     .command('analyze', { isDefault: true })
     .description('Analyze repository and show project report')
-    .action(async () => {
+    .option('--changed-only', 'only report issues on files changed vs base ref')
+    .option('--base-ref <ref>', 'git base ref for --changed-only (default: origin/main)')
+    .action(async (cmdOpts) => {
     setupLogLevel();
     maybeBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     const spinner = format === 'console' ? ora('Scanning repository...').start() : null;
     try {
-        const scan = await scanRepository(rootPath);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
         if (spinner)
             spinner.text = 'Detecting languages...';
         const languages = detectLanguages(scan.files);
@@ -93,7 +137,11 @@ program
         const dependencies = await analyzeDependencies(rootPath);
         if (spinner)
             spinner.text = 'Checking for issues...';
-        const issues = await collectIssues(rootPath, scan.files);
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
+        if (cmdOpts.changedOnly) {
+            issues = await filterIssuesByChangedFiles(issues, rootPath, cmdOpts.baseRef ?? config.baseRef);
+        }
         if (spinner)
             spinner.stop();
         const report = {
@@ -113,6 +161,9 @@ program
             case 'markdown':
                 reportAnalysisMarkdown(report);
                 break;
+            case 'sarif':
+                reportAnalysisSarif(issues, pkg.version);
+                break;
             default:
                 reportAnalysis(report);
         }
@@ -128,15 +179,22 @@ program
 program
     .command('doctor')
     .description('Evaluate project health and detect issues')
-    .action(async () => {
+    .option('--changed-only', 'only report issues on files changed vs base ref')
+    .option('--base-ref <ref>', 'git base ref for --changed-only (default: origin/main)')
+    .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     const spinner = format === 'console' ? ora('Running health checks...').start() : null;
     try {
-        const scan = await scanRepository(rootPath);
-        const issues = await collectIssues(rootPath, scan.files);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
+        if (cmdOpts.changedOnly) {
+            issues = await filterIssuesByChangedFiles(issues, rootPath, cmdOpts.baseRef ?? config.baseRef);
+        }
         if (spinner)
             spinner.stop();
         switch (format) {
@@ -146,6 +204,9 @@ program
             case 'markdown':
                 reportHealthMarkdown(issues);
                 break;
+            case 'sarif':
+                reportHealthSarif(issues, pkg.version);
+                break;
             default:
                 reportHealth(issues, scan.scanDurationMs);
         }
@@ -161,16 +222,24 @@ program
 program
     .command('ci')
     .description('Run health check for CI pipelines (exits 1 if score below threshold)')
-    .option('--min-score <score>', 'minimum passing score (0-100)', '70')
+    .option('--min-score <score>', 'minimum passing score (0-100)')
+    .option('--changed-only', 'gate only on issues in files changed vs base ref')
+    .option('--base-ref <ref>', 'git base ref for --changed-only (default: origin/main)')
     .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     try {
-        const scan = await scanRepository(rootPath);
-        const issues = await collectIssues(rootPath, scan.files);
-        const threshold = Math.max(0, Math.min(100, parseInt(cmdOpts.minScore, 10) || 70));
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
+        if (cmdOpts.changedOnly) {
+            issues = await filterIssuesByChangedFiles(issues, rootPath, cmdOpts.baseRef ?? config.baseRef);
+        }
+        const rawThreshold = cmdOpts.minScore ?? config.minScore ?? 70;
+        const threshold = Math.max(0, Math.min(100, typeof rawThreshold === 'string' ? parseInt(rawThreshold, 10) || 70 : rawThreshold));
         const { score } = calculateScore(issues);
         switch (format) {
             case 'json':
@@ -179,6 +248,9 @@ program
             case 'markdown':
                 reportCiMarkdown(issues, threshold);
                 break;
+            case 'sarif':
+                reportCiSarif(issues, pkg.version);
+                break;
             default:
                 reportCi(issues, threshold);
         }
@@ -202,15 +274,24 @@ program
     maybeCompactBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     try {
-        const scan = await scanRepository(rootPath);
-        const issues = await collectIssues(rootPath, scan.files);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
+        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 +303,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);
@@ -249,9 +330,11 @@ program
     maybeCompactBanner();
     const rootPath = getRootPath();
     const spinner = ora('Detecting issues...').start();
+    const config = await loadProjectConfig();
     try {
-        const scan = await scanRepository(rootPath);
-        const issues = await collectIssues(rootPath, scan.files);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
         const fixes = getAllAvailableFixes(issues);
         spinner.stop();
         if (fixes.length === 0) {
@@ -299,6 +382,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>')
@@ -341,9 +460,10 @@ program
     maybeCompactBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     const spinner = format === 'console' ? ora('Analyzing architecture...').start() : null;
     try {
-        const scan = await scanRepository(rootPath);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
         const frameworks = await detectFrameworks(rootPath, scan.files);
         const layers = buildArchitectureLayers(scan.files, frameworks.frameworks.map((f) => f.name));
         if (spinner)
@@ -375,9 +495,10 @@ program
     maybeCompactBanner();
     const rootPath = getRootPath();
     const format = getFormat();
+    const config = await loadProjectConfig();
     const spinner = format === 'console' ? ora('Scanning...').start() : null;
     try {
-        const scan = await scanRepository(rootPath);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
         if (spinner)
             spinner.stop();
         switch (format) {
@@ -434,6 +555,65 @@ 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')
+    .option('--since <when>', 'git history window (e.g. "6 months ago", "2024-01-01")')
+    .action(async (cmdOpts) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    const config = await loadProjectConfig();
+    const spinner = format === 'console' ? ora('Analyzing hotspots...').start() : null;
+    try {
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
+        const limitRaw = cmdOpts.limit ?? config.hotspots?.limit ?? 10;
+        const limit = Math.max(1, Math.min(100, typeof limitRaw === 'string' ? parseInt(limitRaw, 10) || 10 : limitRaw));
+        const since = cmdOpts.since ?? config.hotspots?.since ?? '12 months ago';
+        const report = await analyzeHotspots(rootPath, scan.files, issues, {
+            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')
@@ -444,9 +624,11 @@ program
     maybeCompactBanner();
     const rootPath = getRootPath();
     const spinner = ora('Calculating health score...').start();
+    const config = await loadProjectConfig();
     try {
-        const scan = await scanRepository(rootPath);
-        const issues = await collectIssues(rootPath, scan.files);
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let issues = await collectIssues(rootPath, scan.files);
+        issues = applyConfigToIssues(issues, config);
         const { score, grade } = calculateScore(issues);
         spinner.stop();
         const gradeColor = grade === 'A' || grade === 'B' ? chalk.green : grade === 'C' ? chalk.yellow : chalk.red;
@@ -473,7 +655,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 +666,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 = [];