@kernlang/cli 3.1.9 → 3.3.4

package/dist/commands/review.js

@@ -1,14 +1,54 @@
 import { clearTemplates, registerTemplate, VALID_TARGETS } from '@kernlang/core';
-import { analyzeTaint, buildLLMPrompt, buildReviewInstructions, checkEnforcement, checkSpecFiles, clearReviewCache, dedup, exportKernIR, formatEnforcement, formatReport, formatSARIF, formatSummary, getRuleRegistry, isLLMAvailable, linkToNodes, resolveImportGraph, reviewFile, reviewGraph, runESLint, runLLMReview, runTSCDiagnosticsFromPaths, specViolationsToFindings, } from '@kernlang/review';
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { basename, relative, resolve } from 'path';
-import { collectTsFilesFlat, hasFlag, loadConfig, parseAndSurface, parseFlag } from '../shared.js';
+import { analyzeTaint, buildLLMPrompt, buildReviewInstructions, checkEnforcement, checkSpecFiles, clearReviewCache, dedup, exportKernIR, formatEnforcement, formatReport, formatSARIF, formatSARIFWithMetadata, formatSummary, getRuleRegistry, isLLMAvailable, linkToNodes, ReviewHealthBuilder, resolveImportGraph, reviewFile, reviewGraph, runESLint, runLLMReview, runTSCDiagnosticsFromPaths, specViolationsToFindings, } from '@kernlang/review';
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, relative, resolve } from 'path';
+import { withOptionalRemoteRepo } from '../remote-repo.js';
+import { compareReportsToBaseline, createReviewBaseline, filterReportsToNewFindings, getReviewBaselineKeyForFinding, parseReviewBaseline, } from '../review-baseline.js';
+import { collectTsFilesFlat, hasFlag, loadConfig, parseAndSurface, parseFlag, parseFlagOrNext } from '../shared.js';
+/**
+ * Pick a safe default diff base for bare `kern review` inside a git repo.
+ * Tries `origin/main`, then `origin/master`, then `HEAD~1`, returning the
+ * first ref that `git rev-parse --verify` accepts. Returns undefined when
+ * not in a git repo or no suitable ref exists (e.g. single-commit repo).
+ *
+ * Exported for testability.
+ */
+export function detectAutoDiffBase(cwd = process.cwd()) {
+    const verify = (ref) => {
+        try {
+            execFileSync('git', ['rev-parse', '--verify', '--quiet', ref], {
+                cwd,
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Require this to actually be a git repo before trying refs.
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd,
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+    }
+    catch {
+        return undefined;
+    }
+    for (const candidate of ['origin/main', 'origin/master', 'HEAD~1']) {
+        if (verify(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 // ── Review pipeline ──────────────────────────────────────────────────────
 async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
-    const { graphMode, batchMode, llmMode, cloudMode, securityMode, mcpMode, specMode, fixMode, autofixMode, lintMode, exportKern, enforce, jsonOutput, sarifOutput, maxDepth, batchSize, tsconfigPath, specFile, minCoverageArg, maxComplexityArg, maxErrorsArg, maxWarningsArg, } = modes;
+    const { graphMode, batchMode, llmMode, cloudMode, securityMode, mcpMode, specMode, fixMode, autofixMode, lintMode, skipGenerated, exportKern, enforce, jsonOutput, sarifOutput, maxDepth, batchSize, tsconfigPath, specFile, minCoverageArg, maxComplexityArg, maxErrorsArg, maxWarningsArg, baseline, writeBaselinePath, newOnly, } = modes;
     let reports = [];
     if (graphMode && entryFilePaths.length > 0) {
-        const graphOpts = { maxDepth, tsConfigFilePath: tsconfigPath ? resolve(tsconfigPath) : undefined };
+        const graphOpts = { maxDepth, tsConfigFilePath: tsconfigPath };
         const graph = resolveImportGraph(entryFilePaths, graphOpts);
         console.log(`  Graph: ${graph.totalFiles} files resolved (${graph.skipped} skipped, depth ${maxDepth})`);
         reports = reviewGraph(entryFilePaths, reviewConfig, graphOpts);
@@ -40,6 +80,14 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
             }
         }
     }
+    if (skipGenerated) {
+        const before = reports.length;
+        reports = reports.filter((r) => !r.generated);
+        const dropped = before - reports.length;
+        if (dropped > 0 && !jsonOutput && !sarifOutput) {
+            console.log(`  Skipped ${dropped} generated file(s). Use --include-generated to review them.`);
+        }
+    }
     if (reports.length === 0) {
         console.log('  No reviewable files found (.ts/.tsx/.py/.kern).');
         return { reports, exitCode: 0 };
@@ -306,7 +354,13 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
             }
         }
         else {
-            // No API key — AI CLI tool IS the reviewer
+            // No API key — emit machine-readable context for an upstream AI CLI
+            // (claude/codex/gemini) to consume as the reviewer. Without a banner
+            // this looks like "--llm did nothing" to someone running it standalone.
+            console.log('  LLM review: KERN_LLM_API_KEY not set — emitting LLM-prompt context.');
+            console.log('    Pipe to an AI CLI:   kern review --llm <file> | claude');
+            console.log('    Or set an API key:   export KERN_LLM_API_KEY=<key>');
+            console.log('');
             for (const report of reports) {
                 const rel = relative(process.cwd(), report.filePath);
                 if (report.findings.length > 0) {
@@ -518,7 +572,10 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
     // Lint mode
     if (lintMode) {
         const filePaths = reports.map((r) => r.filePath).filter((f) => existsSync(f));
-        const eslintFindings = await runESLint(filePaths, process.cwd());
+        // Collect lint-phase health across runESLint + runTSCDiagnosticsFromPaths; merge onto every
+        // report at the end so "ESLint not installed" shows up in the review header, not just console.
+        const lintHealth = new ReviewHealthBuilder();
+        const eslintFindings = await runESLint(filePaths, process.cwd(), lintHealth);
         if (eslintFindings.length > 0) {
             console.log(`  ESLint: ${eslintFindings.length} findings`);
             for (const report of reports) {
@@ -530,7 +587,7 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
         else {
             console.log('  ESLint: no findings (or not installed)');
         }
-        const tscFindings = runTSCDiagnosticsFromPaths(filePaths);
+        const tscFindings = runTSCDiagnosticsFromPaths(filePaths, lintHealth);
         if (tscFindings.length > 0) {
             console.log(`  tsc: ${tscFindings.length} findings`);
             for (const report of reports) {
@@ -542,10 +599,43 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
         else {
             console.log('  tsc: no findings');
         }
+        // Fold lint-phase health into each report's existing health (builder dedupes by key so merging
+        // a skipped-ESLint note on a report that already has an fs-project fallback keeps both).
+        const lintHealthBuilt = lintHealth.build();
+        if (lintHealthBuilt) {
+            for (const report of reports) {
+                const merged = new ReviewHealthBuilder();
+                for (const e of report.health?.entries ?? [])
+                    merged.note(e);
+                for (const e of lintHealthBuilt.entries)
+                    merged.note(e);
+                report.health = merged.build();
+            }
+        }
+    }
+    let baselineComparison;
+    let reportsForOutput = reports;
+    let reportsForEnforcement = reports;
+    if (baseline) {
+        baselineComparison = compareReportsToBaseline(reports, baseline);
+        reportsForEnforcement = filterReportsToNewFindings(reports, baselineComparison);
+        if (newOnly) {
+            reportsForOutput = reportsForEnforcement;
+        }
+    }
+    if (writeBaselinePath) {
+        const baselineDir = dirname(writeBaselinePath);
+        if (baselineDir && baselineDir !== '.') {
+            mkdirSync(baselineDir, { recursive: true });
+        }
+        writeFileSync(writeBaselinePath, `${JSON.stringify(createReviewBaseline(reports), null, 2)}\n`);
+        if (!jsonOutput && !sarifOutput) {
+            console.log(`  Baseline written: ${writeBaselinePath}`);
+        }
     }
     // Output
     if (jsonOutput) {
-        const enriched = reports.map((report) => {
+        const enriched = reportsForOutput.map((report) => {
             const llmPrompt = buildLLMPrompt(report.inferred, report.templateMatches);
             const kernIR = exportKernIR(report.inferred, report.templateMatches);
             return { ...report, kernIR, llmPrompt };
@@ -553,16 +643,40 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
         console.log(JSON.stringify(enriched.length === 1 ? enriched[0] : enriched, null, 2));
     }
     else if (sarifOutput) {
-        console.log(formatSARIF(reports));
+        if (baselineComparison) {
+            console.log(formatSARIFWithMetadata(reportsForOutput, {
+                getBaselineStatus: (report, finding) => {
+                    const key = getReviewBaselineKeyForFinding(report.filePath, finding);
+                    if (baselineComparison.knownKeys.has(key))
+                        return 'existing';
+                    if (baselineComparison.newKeys.has(key))
+                        return 'new';
+                    return undefined;
+                },
+            }));
+        }
+        else if (reportsForOutput.some((report) => (report.suppressedFindings?.length ?? 0) > 0)) {
+            console.log(formatSARIFWithMetadata(reportsForOutput));
+        }
+        else {
+            console.log(formatSARIF(reportsForOutput));
+        }
     }
     else {
-        for (const report of reports) {
+        for (const report of reportsForOutput) {
             console.log('');
             console.log(formatReport(report, reviewConfig));
         }
-        if (reports.length > 1) {
+        if (reportsForOutput.length > 1) {
+            console.log('');
+            console.log(formatSummary(reportsForOutput));
+        }
+        if (baselineComparison) {
             console.log('');
-            console.log(formatSummary(reports));
+            console.log(`  Baseline: ${baselineComparison.knownCount} existing, ${baselineComparison.newCount} new, ${baselineComparison.resolvedCount} resolved`);
+            if (newOnly) {
+                console.log('  Output: showing only new findings compared to baseline');
+            }
         }
         const hasThresholds = minCoverageArg !== undefined ||
             maxComplexityArg !== undefined ||
@@ -571,7 +685,7 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
         if (enforce || hasThresholds) {
             console.log('');
             let allPassed = true;
-            for (const report of reports) {
+            for (const report of reportsForEnforcement) {
                 const result = checkEnforcement(report, reviewConfig);
                 if (!result.passed) {
                     allPassed = false;
@@ -581,7 +695,8 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
                 }
             }
             if (allPassed) {
-                console.log(`  Enforcement: PASS (all files checked against thresholds)`);
+                const suffix = baselineComparison ? ' on new findings vs baseline' : '';
+                console.log(`  Enforcement: PASS (all files checked against thresholds${suffix})`);
             }
             else {
                 return { reports, exitCode: 1 };
@@ -591,7 +706,7 @@ async function runReviewPipeline(reviewConfig, entryFilePaths, modes) {
     return { reports, exitCode: 0 };
 }
 // ── Review command entry point ───────────────────────────────────────────
-export async function runReview(args) {
+async function runReviewLocal(args) {
     const jsonOutput = hasFlag(args, '--json');
     const sarifOutput = hasFlag(args, '--sarif', '--format=sarif');
     const recursive = hasFlag(args, '--recursive', '-r');
@@ -606,15 +721,46 @@ export async function runReview(args) {
     const fixMode = hasFlag(args, '--fix');
     const autofixMode = hasFlag(args, '--autofix');
     const lintMode = hasFlag(args, '--lint');
+    // Phase 6: generated files skipped by default — bugs in compiler output
+    // belong to the compiler, not the user, and inference re-fires every
+    // handler-size/handler-heavy rule on transpiled function bodies. Opt back
+    // in with --include-generated. --skip-generated stays accepted as a no-op
+    // so CI configs that pass it explicitly don't break.
+    const includeGenerated = hasFlag(args, '--include-generated');
+    const skipGenerated = !includeGenerated;
     const graphMode = hasFlag(args, '--graph') || recursive;
     const batchMode = hasFlag(args, '--batch');
     const maxDepth = Number(parseFlag(args, '--max-depth') ?? 3);
     const batchSize = Number(parseFlag(args, '--batch-size') ?? 20);
-    const tsconfigPath = parseFlag(args, '--tsconfig');
+    const explicitTsconfigPath = parseFlag(args, '--tsconfig');
+    // Only resolve when explicitly passed — per-file auto-discovery (via findTsConfig in the review engine)
+    // is usually right in monorepos, where the root tsconfig is a solution-only references file.
+    const tsconfigPath = explicitTsconfigPath ? resolve(explicitTsconfigPath) : undefined;
+    // Warn when the user explicitly points --tsconfig at a solution-only (references-only) file.
+    // ts-morph will load it but the resulting Project has no compilerOptions, which silently
+    // degrades review quality (no jsx, no paths, no strict). Tell the user before they waste a run.
+    if (tsconfigPath && existsSync(tsconfigPath)) {
+        try {
+            const raw = readFileSync(tsconfigPath, 'utf-8');
+            const stripped = raw.replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, '');
+            const parsed = JSON.parse(stripped);
+            const hasCompilerOptions = parsed.compilerOptions && Object.keys(parsed.compilerOptions).length > 0;
+            const hasReferences = Array.isArray(parsed.references) && parsed.references.length > 0;
+            if (!hasCompilerOptions && hasReferences) {
+                console.warn(`  Warning: --tsconfig ${tsconfigPath} is a solution-only file (references-only, no compilerOptions).`);
+                console.warn(`  Review quality will be degraded (no jsx/paths/strict). Point --tsconfig at a per-package tsconfig instead, or omit --tsconfig to let kern-review discover the nearest one per file.`);
+            }
+        }
+        catch {
+            // Bad JSON / unreadable — ts-morph will surface a clearer error during loading.
+        }
+    }
     const minCoverageArg = parseFlag(args, '--min-coverage');
     const minCoverage = minCoverageArg ? Number(minCoverageArg) : undefined;
     const maxComplexityArg = parseFlag(args, '--max-complexity');
     const maxComplexity = maxComplexityArg ? Number(maxComplexityArg) : 15;
+    const maxHandlerLinesArg = parseFlag(args, '--max-handler-lines');
+    const maxHandlerLines = maxHandlerLinesArg ? Number(maxHandlerLinesArg) : undefined;
     const maxErrorsArg = parseFlag(args, '--max-errors');
     const maxErrors = maxErrorsArg ? Number(maxErrorsArg) : 0;
     const maxWarningsArg = parseFlag(args, '--max-warnings');
@@ -623,6 +769,13 @@ export async function runReview(args) {
     const minConfidenceArg = parseFlag(args, '--min-confidence');
     const minConfidence = minConfidenceArg ? Number(minConfidenceArg) : undefined;
     const disableRuleArgs = args.filter((a) => a.startsWith('--disable-rule=')).map((a) => a.split('=')[1]);
+    const baselinePath = parseFlagOrNext(args, '--baseline');
+    const writeBaselinePath = parseFlagOrNext(args, '--write-baseline');
+    const newOnly = hasFlag(args, '--new-only');
+    if (newOnly && !baselinePath) {
+        console.error('--new-only requires --baseline=<file.json>');
+        process.exit(1);
+    }
     const rulesDirs = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === '--rules-dir' && args[i + 1] && !args[i + 1].startsWith('--')) {
@@ -637,9 +790,37 @@ export async function runReview(args) {
     const strict = strictArg === '--strict' ? 'inline' : strictArg === '--strict=all' ? 'all' : false;
     const strictParse = hasFlag(args, '--strict-parse');
     const listRules = hasFlag(args, '--list-rules');
-    const diffBase = args.find((a) => a.startsWith('--diff'))
-        ? parseFlag(args, '--diff') || args[args.indexOf('--diff') + 1] || 'origin/main'
+    let diffBase = args.some((a) => a === '--diff' || a.startsWith('--diff'))
+        ? parseFlagOrNext(args, '--diff') || 'origin/main'
         : undefined;
+    const fullMode = hasFlag(args, '--full');
+    if (fullMode && diffBase) {
+        console.error('  --full and --diff are mutually exclusive.');
+        process.exit(1);
+    }
+    let baseline;
+    if (baselinePath) {
+        const resolvedBaselinePath = resolve(baselinePath);
+        if (!existsSync(resolvedBaselinePath)) {
+            console.error(`Baseline not found: ${baselinePath}`);
+            process.exit(1);
+        }
+        let rawBaseline;
+        try {
+            rawBaseline = readFileSync(resolvedBaselinePath, 'utf-8');
+        }
+        catch (err) {
+            console.error(`Failed to read baseline ${baselinePath}: ${err.message}`);
+            process.exit(1);
+        }
+        try {
+            baseline = parseReviewBaseline(rawBaseline);
+        }
+        catch (err) {
+            console.error(`Failed to parse baseline ${baselinePath}: ${err.message}`);
+            process.exit(1);
+        }
+    }
     // --list-rules
     if (listRules) {
         const reviewCfg = loadConfig();
@@ -664,8 +845,60 @@ export async function runReview(args) {
         process.exit(0);
     }
     // Diff mode
-    const reviewInputs = args.filter((a) => !a.startsWith('--') && a !== 'review');
+    const flagsWithValues = new Set([
+        '--spec',
+        '--diff',
+        '--git',
+        '--ref',
+        '--rules-dir',
+        '--tsconfig',
+        '--target',
+        '--max-depth',
+        '--batch-size',
+        '--min-coverage',
+        '--max-complexity',
+        '--max-errors',
+        '--max-warnings',
+        '--min-confidence',
+        '--baseline',
+        '--write-baseline',
+    ]);
+    const reviewInputs = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === 'review')
+            continue;
+        if (flagsWithValues.has(arg)) {
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--'))
+            continue;
+        reviewInputs.push(arg);
+    }
     let reviewInput = reviewInputs[0];
+    const remoteUrl = parseFlagOrNext(args, '--git');
+    if (remoteUrl && !reviewInput && !diffBase) {
+        reviewInput = '.';
+    }
+    // Phase 5: diff-scoped by default.
+    // Bare `kern review` (no path, no --diff, no --full, no --git) inside a git
+    // repo defaults to reviewing changes vs the upstream branch. `--full` opts
+    // back into a cwd-wide scan. Explicit paths are unchanged — `kern review
+    // src/` still scans src/ in full. This keeps `kern review` quiet by default
+    // on large codebases without breaking CI invocations that pass a path.
+    if (!reviewInput && !diffBase && !remoteUrl && !fullMode) {
+        const autoBase = detectAutoDiffBase();
+        if (autoBase) {
+            diffBase = autoBase;
+            if (!hasFlag(args, '--json') && !hasFlag(args, '--sarif')) {
+                console.log(`  No path given — reviewing changes vs ${autoBase}. Use --full to scan the whole tree, or pass a path.\n`);
+            }
+        }
+    }
+    if (fullMode && !reviewInput) {
+        reviewInput = '.';
+    }
     if (diffBase && !reviewInput) {
         try {
             const { execFileSync } = await import('child_process');
@@ -675,13 +908,17 @@ export async function runReview(args) {
             })
                 .trim()
                 .split('\n')
-                .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx'))
+                .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.kern'))
                 .filter((f) => !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
+            const machineOutput = hasFlag(args, '--json') || hasFlag(args, '--sarif');
             if (diffFiles.length === 0) {
-                console.log(`  No changed .ts/.tsx files since ${diffBase}`);
+                if (!machineOutput)
+                    console.log(`  No changed .ts/.tsx/.kern files since ${diffBase}`);
                 process.exit(0);
             }
-            console.log(`  Reviewing ${diffFiles.length} changed files (diff from ${diffBase})\n`);
+            if (!machineOutput) {
+                console.log(`  Reviewing ${diffFiles.length} changed files (diff from ${diffBase})\n`);
+            }
             const diffRanges = new Map();
             try {
                 const unifiedDiff = execFileSync('git', ['diff', '--unified=0', '--diff-filter=ACMR', sanitizedBase], {
@@ -720,8 +957,11 @@ export async function runReview(args) {
         }
     }
     if (!reviewInput) {
-        console.error('Usage: kern review <file.ts|dir> [--security] [--mcp] [--llm] [--spec file.kern] [--cloud]');
-        console.error('       [--diff base] [--json] [--sarif] [--recursive] [--enforce] [--strict-parse] [--fix] [--autofix] [--rules-dir <dir>]');
+        console.error('Usage: kern review [file|dir] [--full] [--diff base] [--git=<url>] [--security] [--mcp] [--llm] [--spec file.kern] [--cloud] [--baseline=file.json] [--new-only]');
+        console.error('       [--write-baseline=file.json] [--json] [--sarif] [--recursive] [--enforce] [--strict-parse] [--fix] [--autofix] [--rules-dir <dir>] [--include-generated]');
+        console.error('');
+        console.error('  Default (inside git): reviews changes vs origin/main. Use --full to scan the whole tree.');
+        console.error('  Default skips generated files (src/generated/, files with @generated stamps). Use --include-generated to audit them.');
         process.exit(1);
     }
     if (reviewInput !== '__diff__') {
@@ -750,6 +990,7 @@ export async function runReview(args) {
         minCoverage: minCoverage ?? 0,
         enforceTemplates: enforce,
         maxComplexity: maxComplexity ?? reviewCfg.review.maxComplexity,
+        maxHandlerLines,
         maxErrors,
         maxWarnings,
         target: reviewCfg.target,
@@ -759,6 +1000,14 @@ export async function runReview(args) {
         rulesDirs: rulesDirs.length > 0 ? rulesDirs : undefined,
         strict,
         strictParse,
+        tsConfigFilePath: tsconfigPath,
+        publicApi: reviewCfg.review.publicApi.files.length > 0 || reviewCfg.review.publicApi.symbols.length > 0
+            ? {
+                files: reviewCfg.review.publicApi.files,
+                symbols: reviewCfg.review.publicApi.symbols,
+                projectRoot: process.cwd(),
+            }
+            : undefined,
     };
     // Load templates for review
     if (reviewCfg.templates && reviewCfg.templates.length > 0) {
@@ -831,6 +1080,7 @@ export async function runReview(args) {
         fixMode,
         autofixMode,
         lintMode,
+        skipGenerated,
         exportKern,
         enforce,
         jsonOutput,
@@ -845,6 +1095,9 @@ export async function runReview(args) {
         maxErrorsArg,
         maxWarningsArg,
         showConfidence,
+        baseline,
+        writeBaselinePath: writeBaselinePath ? resolve(writeBaselinePath) : undefined,
+        newOnly,
     };
     const noCache = hasFlag(args, '--no-cache');
     if (noCache) {
@@ -879,4 +1132,15 @@ export async function runReview(args) {
         process.exit(result.exitCode);
     }
 }
+export async function runReview(args) {
+    const diffBase = args.some((a) => a === '--diff' || a.startsWith('--diff'))
+        ? parseFlagOrNext(args, '--diff') || 'origin/main'
+        : undefined;
+    await withOptionalRemoteRepo(args, {
+        commandName: 'review',
+        fullClone: Boolean(diffBase),
+    }, async () => {
+        await runReviewLocal(args);
+    });
+}
 //# sourceMappingURL=review.js.map