@rigour-labs/core 6.2.3 → 6.2.5

package/dist/gates/deep-analysis.js

@@ -1,28 +1,40 @@
 /**
- * Deep Analysis Gate — LLM-powered code quality analysis.
+ * Deep Analysis Gate — LLM-powered code analysis.
  *
- * Three-step pipeline:
- * 1. AST extracts facts → "UserService has 8 public methods touching 4 domains"
- * 2. LLM interprets facts → "UserService violates Single Responsibility"
- * 3. AST verifies LLM → Does UserService actually have those methods? ✓
+ * Two modes:
+ * - Unscoped (`rigour check --deep`): repo-wide analysis from AST facts.
+ *   AST extracts facts, the LLM interprets them, AST verifies the findings.
+ * - Scoped (`rigour check <paths> --deep`, `rigour review --deep`): each
+ *   scoped file is reviewed with its numbered source; findings must cite a
+ *   line and identifiers that were actually sent.
  *
- * AST grounds LLM. LLM interprets AST. Neither works alone.
+ * The gate records an outcome. A run where setup failed or every chunk
+ * failed is an error, never a clean pass.
  */
 import { Gate } from './base.js';
 import { createProvider } from '../inference/index.js';
-import { extractFacts, factsToPromptString, chunkFacts, buildAnalysisPrompt, buildCrossFilePrompt, verifyFindings } from '../deep/index.js';
+import { SidecarProvider } from '../inference/sidecar-provider.js';
+import { extractFacts, verifyFindings } from '../deep/index.js';
+import { runFactsPass } from '../deep/facts-pass.js';
+import { runCodePass } from '../deep/code-pass.js';
+import { verifyCodeFindings } from '../deep/code-verifier.js';
 import { checkLocalPatterns } from '../storage/local-memory.js';
+import { isScoped } from '../utils/scope.js';
 import { Logger } from '../utils/logger.js';
 import path from 'path';
-/** Default batch size for streaming analysis of large repos.
- *  Files are processed in batches to avoid OOM on huge repos.
- *  Optional soft limit via rigour.yml: deep.maxFiles */
-const DEFAULT_BATCH_SIZE = 200;
-/** Setup timeout: 120s for model download, 30s for API connection */
-const SETUP_TIMEOUT_MS = 120_000;
+/** Cloud setup (API connection) must not hang a check. Local setup is bounded by download stall timeouts instead. */
+const CLOUD_SETUP_TIMEOUT_MS = 120_000;
+/**
+ * Source budget per file in the code-review prompt. Local: ~36k chars is
+ * ~12k tokens; measured on Apple Silicon at ~19s per file for the 1.5B model
+ * (prompt eval ~670 tok/s), inside the 60s per-call timeout.
+ */
+const LOCAL_SOURCE_CHARS = 36_000;
+const CLOUD_SOURCE_CHARS = 60_000;
 export class DeepAnalysisGate extends Gate {
     config;
     provider = null;
+    outcome = emptyOutcome();
     constructor(config) {
         super('deep-analysis', 'Deep Code Quality Analysis');
         this.config = config;
@@ -30,321 +42,168 @@ export class DeepAnalysisGate extends Gate {
     get provenance() {
         return 'deep-analysis';
     }
-    /** Check if a file is a likely entry point (higher analysis priority) */
-    isEntryPoint(filePath) {
-        const basename = path.basename(filePath).toLowerCase();
-        const entryNames = [
-            'index.ts', 'index.js', 'index.tsx', 'index.jsx', 'index.mjs',
-            'main.ts', 'main.js', 'main.py', 'main.go', 'main.rs', 'main.java', 'main.kt',
-            'app.ts', 'app.js', 'app.py', 'app.go', 'app.rb',
-            'server.ts', 'server.js', 'server.py', 'server.go',
-            'mod.rs', 'lib.rs',
-        ];
-        return entryNames.includes(basename);
+    /** Outcome of the last run(). */
+    getOutcome() {
+        return this.outcome;
     }
     async run(context) {
-        const { onProgress } = this.config;
-        const failures = [];
         const startTime = Date.now();
+        const scoped = isScoped(context.patterns);
+        this.outcome = { ...emptyOutcome(), mode: scoped ? 'code' : 'facts' };
         try {
-            // Step 0: Initialize inference provider (with timeout)
-            onProgress?.('\n  Setting up Rigour Brain...\n');
-            this.provider = createProvider(this.config.options);
-            // Pre-check availability to fail fast instead of hanging on install
-            const isLocalProvider = !this.config.options.apiKey || this.config.options.provider === 'local';
-            if (isLocalProvider) {
-                const available = await this.provider.isAvailable();
-                if (!available) {
-                    onProgress?.('  ⚠ Local inference binary not found. Attempting auto-install...');
-                    onProgress?.('  (This may take a moment on first run)');
-                }
-            }
-            await Promise.race([
-                this.provider.setup(onProgress),
-                new Promise((_, reject) => setTimeout(() => reject(new Error('Deep analysis setup timed out.\n' +
-                    '  If local: run `rigour doctor` to check sidecar binary status.\n' +
-                    '  If cloud: check your API key with `rigour settings show`.')), SETUP_TIMEOUT_MS)),
-            ]);
-            const isLocal = !this.config.options.apiKey || this.config.options.provider === 'local';
-            if (isLocal) {
-                onProgress?.('\n  🔒 Local sidecar/model execution. Code remains on this machine.\n');
-            }
-            else {
-                onProgress?.(`\n  ☁️  Using ${this.config.options.provider} API. Code context may be sent to the provider.\n`);
-            }
-            // Step 1: AST extracts facts
-            onProgress?.('  Extracting code facts...');
-            let allFacts = await extractFacts(context.cwd, context.ignore);
-            if (allFacts.length === 0) {
-                onProgress?.('  No analyzable files found. Check ignore patterns and file extensions.');
+            await this.setupProvider();
+            this.config.onProgress?.('  Extracting code facts...');
+            const facts = prioritize(await extractFacts(context.cwd, context.ignore, scoped ? context.patterns : undefined));
+            this.outcome.filesAnalyzed = facts.length;
+            if (facts.length === 0) {
+                this.config.onProgress?.('  No analyzable files found. Check ignore patterns and file extensions.');
                 return [];
             }
-            // Smart prioritization: entry points first, then by complexity
-            allFacts.sort((a, b) => {
-                const aEntry = this.isEntryPoint(a.path) ? 1 : 0;
-                const bEntry = this.isEntryPoint(b.path) ? 1 : 0;
-                if (aEntry !== bEntry)
-                    return bEntry - aEntry;
-                return b.lineCount - a.lineCount;
-            });
-            // Optional soft limit — if user configures deep.maxFiles, respect it
-            // Otherwise process ALL files in batches (no hard cap)
-            if (this.config.options.maxFiles && allFacts.length > this.config.options.maxFiles) {
-                onProgress?.(`  Limiting to ${this.config.options.maxFiles} files (configured in rigour.yml).`);
-                allFacts = allFacts.slice(0, this.config.options.maxFiles);
-            }
-            const agentCount = this.config.options.agents || 1;
-            const isCloud = !!this.config.options.apiKey;
-            onProgress?.(`  Found ${allFacts.length} files to analyze${agentCount > 1 ? ` with ${agentCount} parallel agents` : ''}.`);
-            // Step 1.5: Check local project memory for known patterns (instant, no LLM)
-            // Wrapped in try/catch: sqlite3 may not be available in all environments
-            const fileList = allFacts.map(f => f.path).filter(Boolean);
-            let localFindings = [];
-            try {
-                localFindings = await checkLocalPatterns(context.cwd, fileList);
-                if (localFindings.length > 0) {
-                    onProgress?.(`  🧠 Local memory: ${localFindings.length} known pattern(s) matched instantly.`);
-                }
-            }
-            catch (error) {
-                Logger.debug(`Local memory check skipped (${error.message?.substring(0, 80)})`);
-                onProgress?.('  ℹ Local memory unavailable — continuing with LLM analysis only.');
-            }
-            // Step 2: LLM interprets facts (in chunks)
-            const chunks = chunkFacts(allFacts);
-            const allFindings = [...localFindings];
-            let failedChunks = 0;
-            if (agentCount > 1 && isCloud) {
-                // ── Multi-agent mode: partition chunks across N agents, analyze in parallel ──
-                // Each agent gets its own provider instance for true parallelism.
-                // Local mode stays sequential (single sidecar process).
-                onProgress?.(`  Spawning ${agentCount} parallel agents...`);
-                const agentBuckets = Array.from({ length: agentCount }, () => []);
-                chunks.forEach((chunk, i) => agentBuckets[i % agentCount].push(chunk));
-                // Create N independent provider instances
-                const agentProviders = [];
-                for (let a = 0; a < agentCount; a++) {
-                    if (agentBuckets[a].length === 0)
-                        continue;
-                    const p = createProvider(this.config.options);
-                    await p.setup(); // Already connected — cloud setup is instant after first
-                    agentProviders.push(p);
-                }
-                // Run all agents in parallel
-                const agentResults = await Promise.allSettled(agentProviders.map(async (provider, agentIdx) => {
-                    const bucket = agentBuckets[agentIdx];
-                    const findings = [];
-                    let failed = 0;
-                    for (let ci = 0; ci < bucket.length; ci++) {
-                        const globalIdx = agentIdx + ci * agentCount + 1;
-                        onProgress?.(`  Agent ${agentIdx + 1}: batch ${ci + 1}/${bucket.length} (global ${globalIdx}/${chunks.length})`);
-                        const factsStr = factsToPromptString(bucket[ci]);
-                        const prompt = buildAnalysisPrompt(factsStr, this.config.checks);
-                        try {
-                            const response = await provider.analyze(prompt, {
-                                maxTokens: this.config.maxTokens || 8192,
-                                temperature: this.config.temperature || 0.1,
-                                timeout: this.config.timeoutMs || 120000,
-                                jsonMode: true,
-                            });
-                            findings.push(...parseFindings(response));
-                        }
-                        catch (error) {
-                            failed++;
-                            Logger.warn(`Agent ${agentIdx + 1} chunk ${ci + 1} failed: ${error.message}`);
-                        }
-                    }
-                    return { findings, failed };
-                }));
-                // Merge results and dispose extra providers
-                for (let i = 0; i < agentResults.length; i++) {
-                    const result = agentResults[i];
-                    if (result.status === 'fulfilled') {
-                        allFindings.push(...result.value.findings);
-                        failedChunks += result.value.failed;
-                    }
-                    else {
-                        failedChunks += agentBuckets[i].length;
-                        Logger.warn(`Agent ${i + 1} failed entirely: ${result.reason?.message || 'unknown'}`);
-                    }
-                    agentProviders[i]?.dispose();
-                }
-                onProgress?.(`  All ${agentCount} agents completed.`);
-            }
-            else {
-                // ── Single-agent mode: sequential chunk processing ──
-                let chunkIndex = 0;
-                for (const chunk of chunks) {
-                    chunkIndex++;
-                    onProgress?.(`  Analyzing batch ${chunkIndex}/${chunks.length}...`);
-                    const factsStr = factsToPromptString(chunk);
-                    const prompt = buildAnalysisPrompt(factsStr, this.config.checks);
-                    try {
-                        const response = await this.provider.analyze(prompt, {
-                            maxTokens: this.config.maxTokens || (isCloud ? 4096 : 512),
-                            temperature: this.config.temperature || 0.1,
-                            timeout: this.config.timeoutMs || (isCloud ? 120000 : 60000),
-                            jsonMode: true,
-                        });
-                        const findings = parseFindings(response);
-                        allFindings.push(...findings);
-                    }
-                    catch (error) {
-                        failedChunks++;
-                        Logger.warn(`Chunk ${chunkIndex} inference failed: ${error.message}`);
-                        onProgress?.(`  ⚠ Batch ${chunkIndex} failed: ${error.message}`);
-                    }
-                }
-            }
-            // Cross-file analysis (if we have enough files and at least some chunks succeeded)
-            if (allFacts.length >= 3 && failedChunks < chunks.length) {
-                onProgress?.('  Running cross-file analysis...');
-                try {
-                    const crossPrompt = buildCrossFilePrompt(allFacts);
-                    const crossResponse = await this.provider.analyze(crossPrompt, {
-                        maxTokens: this.config.maxTokens || (isCloud ? 4096 : 512),
-                        temperature: this.config.temperature || 0.1,
-                        timeout: this.config.timeoutMs || (isCloud ? 120000 : 60000),
-                        jsonMode: true,
-                    });
-                    const crossFindings = parseFindings(crossResponse);
-                    allFindings.push(...crossFindings);
-                }
-                catch (error) {
-                    Logger.warn(`Cross-file analysis failed: ${error.message}`);
-                }
-            }
-            // Step 3: AST verifies LLM
-            onProgress?.('  Verifying findings...');
-            const verified = verifyFindings(allFindings, allFacts);
-            const durationMs = Date.now() - startTime;
-            onProgress?.(`  ✓ ${verified.length} verified findings (${allFindings.length - verified.length} dropped) in ${(durationMs / 1000).toFixed(1)}s`);
-            if (failedChunks > 0) {
-                onProgress?.(`  ⚠ ${failedChunks}/${chunks.length} batches failed — results may be incomplete.`);
-            }
-            // Convert to Failure format
-            for (const finding of verified) {
-                const failure = this.createFailure(finding.description, [finding.file], finding.suggestion, `[${finding.category}] ${finding.description.substring(0, 80)}`, finding.line, undefined, finding.severity);
-                // Tag with deep analysis metadata
-                failure.confidence = finding.confidence;
-                failure.source = 'llm';
-                failure.category = finding.category;
-                failure.verified = finding.verified;
-                failures.push(failure);
-            }
+            const verified = scoped
+                ? await this.reviewCode(context.cwd, facts)
+                : await this.analyzeFacts(context.cwd, limitFiles(facts, this.config));
+            this.config.onProgress?.(`  ✓ ${verified.length} verified findings in ${((Date.now() - startTime) / 1000).toFixed(1)}s`);
+            return verified.map(f => this.toFailure(f));
         }
         catch (error) {
-            Logger.error(`Deep analysis failed: ${error.message}`);
-            onProgress?.(`  ⚠ Deep analysis error: ${error.message}`);
-            // Don't fail the whole check — deep is advisory
+            this.outcome.status = 'error';
+            this.outcome.error = error?.message ?? String(error);
+            Logger.error(`Deep analysis failed: ${this.outcome.error}`);
+            this.config.onProgress?.(`  ⚠ Deep analysis error: ${this.outcome.error}`);
+            return [];
         }
         finally {
             this.provider?.dispose();
         }
-        return failures;
     }
-}
-/**
- * Parse LLM response into structured findings.
- * Handles various response formats (raw JSON, markdown-wrapped JSON, etc.)
- */
-function parseFindings(response) {
-    if (!response || response.trim().length === 0) {
-        Logger.warn('Empty LLM response received');
-        return [];
+    async setupProvider() {
+        const { options, onProgress } = this.config;
+        onProgress?.('\n  Setting up Rigour Brain...\n');
+        const provider = createProvider(options);
+        this.provider = provider;
+        if (isCloud(this.config.options)) {
+            await withTimeout(provider.setup(onProgress), CLOUD_SETUP_TIMEOUT_MS, 'Deep analysis setup timed out. Check your API key with `rigour settings show`.');
+            this.outcome.model = options.modelName || options.provider || 'cloud';
+            onProgress?.(`\n  ☁️  Using ${options.provider} API. Code context may be sent to the provider.\n`);
+            return;
+        }
+        await provider.setup(onProgress);
+        const active = provider instanceof SidecarProvider ? provider.getActiveModel() : null;
+        this.outcome.model = active?.name;
+        this.outcome.modelFallback = active?.fallback;
+        onProgress?.('\n  🔒 Local sidecar/model execution. Code remains on this machine.\n');
     }
-    try {
-        // Try direct JSON parse first
-        const parsed = JSON.parse(response);
-        if (Array.isArray(parsed.findings))
-            return validateFindings(parsed.findings);
-        if (Array.isArray(parsed))
-            return validateFindings(parsed);
-        return [];
+    async reviewCode(cwd, facts) {
+        this.config.onProgress?.(`  Reviewing ${facts.length} scoped file(s) with source...`);
+        const result = await runCodePass(this.provider, facts, {
+            cwd,
+            inference: inferenceOptions(this.config),
+            maxSourceChars: isCloud(this.config.options) ? CLOUD_SOURCE_CHARS : LOCAL_SOURCE_CHARS,
+            focusLines: this.config.options.focusLines,
+            onProgress: this.config.onProgress,
+        });
+        this.recordPass(result);
+        return verifyCodeFindings(result.findings, result.contexts);
     }
-    catch {
-        // Try extracting JSON from markdown code blocks
-        const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
-        if (jsonMatch) {
-            try {
-                const parsed = JSON.parse(jsonMatch[1]);
-                if (Array.isArray(parsed.findings))
-                    return validateFindings(parsed.findings);
-                if (Array.isArray(parsed))
-                    return validateFindings(parsed);
-            }
-            catch {
-                // Fall through
-            }
-        }
-        // Try finding JSON object in response
-        const objectMatch = response.match(/\{[\s\S]*"findings"[\s\S]*\}/);
-        if (objectMatch) {
-            try {
-                const parsed = JSON.parse(objectMatch[0]);
-                if (Array.isArray(parsed.findings))
-                    return validateFindings(parsed.findings);
-            }
-            catch {
-                // Give up
-            }
+    async analyzeFacts(cwd, facts) {
+        this.config.onProgress?.(`  Found ${facts.length} files to analyze.`);
+        const memory = await this.localMemoryFindings(cwd, facts);
+        const agentCount = this.config.options.agents || 1;
+        const result = await runFactsPass(this.provider, facts, {
+            inference: inferenceOptions(this.config),
+            checks: this.config.checks,
+            onProgress: this.config.onProgress,
+            agents: isCloud(this.config.options) && agentCount > 1
+                ? { count: agentCount, create: () => this.createCloudAgent() }
+                : undefined,
+        });
+        this.recordPass(result);
+        return verifyFindings([...memory, ...result.findings], facts);
+    }
+    recordPass(result) {
+        this.outcome.chunksTotal = result.chunksTotal;
+        this.outcome.chunksFailed = result.chunksFailed;
+        if (result.chunksTotal > 0 && result.chunksFailed === result.chunksTotal) {
+            this.outcome.status = 'error';
+            this.outcome.error = `All ${result.chunksTotal} inference call(s) failed. First error: ${result.firstError ?? 'unknown'}`;
         }
-        // Last resort: try to recover truncated JSON arrays
-        // LLMs sometimes exceed token limits, truncating the response mid-JSON
-        const recovered = recoverTruncatedFindings(response);
-        if (recovered.length > 0) {
-            Logger.info(`Recovered ${recovered.length} findings from truncated response`);
-            return recovered;
+        else if (result.chunksFailed > 0) {
+            this.outcome.status = 'partial';
+            this.config.onProgress?.(`  ⚠ ${result.chunksFailed}/${result.chunksTotal} batches failed — results are incomplete.`);
         }
-        Logger.warn(`Could not parse LLM response as findings JSON. First 200 chars: ${response.substring(0, 200)}`);
-        return [];
     }
-}
-/**
- * Attempt to recover individual finding objects from a truncated JSON response.
- * Extracts complete JSON objects from partial arrays.
- */
-function recoverTruncatedFindings(response) {
-    const findings = [];
-    // Match individual complete objects within the response
-    const objectRegex = /\{\s*"category"\s*:\s*"[^"]+"\s*,[\s\S]*?"description"\s*:\s*"[^"]*"[^}]*\}/g;
-    let match;
-    while ((match = objectRegex.exec(response)) !== null) {
+    async localMemoryFindings(cwd, facts) {
         try {
-            const obj = JSON.parse(match[0]);
-            if (obj.category && obj.file && obj.description) {
-                findings.push(obj);
-            }
+            const found = await checkLocalPatterns(cwd, facts.map(f => f.path).filter(Boolean));
+            if (found.length > 0)
+                this.config.onProgress?.(`  🧠 Local memory: ${found.length} known pattern(s) matched instantly.`);
+            return found;
         }
-        catch {
-            // Individual object was itself truncated — skip
+        catch (error) {
+            Logger.debug(`Local memory check skipped (${error.message?.substring(0, 80)})`);
+            return [];
         }
     }
-    return validateFindings(findings);
+    async createCloudAgent() {
+        const provider = createProvider(this.config.options);
+        await provider.setup();
+        return provider;
+    }
+    toFailure(finding) {
+        const failure = this.createFailure(finding.description, [finding.file], finding.suggestion, `[${finding.category}] ${finding.description.substring(0, 80)}`, finding.line, undefined, finding.severity);
+        return { ...failure, confidence: finding.confidence, source: 'llm', category: finding.category, verified: finding.verified };
+    }
 }
-/**
- * Validate and sanitize findings from LLM response.
- * Drops malformed entries that lack required fields.
- */
-function validateFindings(raw) {
-    return raw.filter(f => {
-        if (!f || typeof f !== 'object')
-            return false;
-        if (!f.category || typeof f.category !== 'string')
-            return false;
-        if (!f.file || typeof f.file !== 'string')
-            return false;
-        if (!f.description || typeof f.description !== 'string')
-            return false;
-        // Normalize confidence
-        if (typeof f.confidence !== 'number' || f.confidence < 0 || f.confidence > 1) {
-            f.confidence = 0.5;
-        }
-        // Normalize severity
-        const validSeverities = ['critical', 'high', 'medium', 'low', 'info'];
-        if (!validSeverities.includes(f.severity)) {
-            f.severity = 'medium';
-        }
-        return true;
+/** Cloud when an API key and a non-local provider are set (same rule as createProvider). */
+function isCloud(options) {
+    return !!options.apiKey && !!options.provider && options.provider !== 'local';
+}
+/** Per-call options; unset config falls back to per-provider defaults. */
+function inferenceOptions(config) {
+    const cloud = isCloud(config.options);
+    return {
+        maxTokens: config.maxTokens ?? (cloud ? 4096 : 1024),
+        temperature: config.temperature ?? 0.1,
+        timeout: config.timeoutMs ?? (cloud ? 120_000 : 60_000),
+        jsonMode: true,
+    };
+}
+function limitFiles(facts, config) {
+    const max = config.options.maxFiles;
+    if (!max || facts.length <= max)
+        return facts;
+    config.onProgress?.(`  Limiting to ${max} files (configured in rigour.yml).`);
+    return facts.slice(0, max);
+}
+function emptyOutcome() {
+    return { status: 'ok', mode: 'facts', filesAnalyzed: 0, chunksTotal: 0, chunksFailed: 0 };
+}
+/** Entry points first, then larger files. */
+function prioritize(facts) {
+    return [...facts].sort((a, b) => {
+        const entry = Number(isEntryPoint(b.path)) - Number(isEntryPoint(a.path));
+        return entry !== 0 ? entry : b.lineCount - a.lineCount;
     });
 }
+const ENTRY_POINTS = new Set([
+    'index.ts', 'index.js', 'index.tsx', 'index.jsx', 'index.mjs',
+    'main.ts', 'main.js', 'main.py', 'main.go', 'main.rs', 'main.java', 'main.kt',
+    'app.ts', 'app.js', 'app.py', 'app.go', 'app.rb',
+    'server.ts', 'server.js', 'server.py', 'server.go',
+    'mod.rs', 'lib.rs',
+]);
+function isEntryPoint(filePath) {
+    return ENTRY_POINTS.has(path.basename(filePath).toLowerCase());
+}
+async function withTimeout(promise, ms, message) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/gates/deep-analysis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gates/deep-analysis.test.js

@@ -0,0 +1,86 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const provider = vi.hoisted(() => ({
+    setup: vi.fn(async () => undefined),
+    analyze: vi.fn(async (_prompt) => '{"findings": []}'),
+}));
+vi.mock('../inference/index.js', () => ({
+    createProvider: () => ({
+        name: 'fake',
+        isAvailable: async () => true,
+        setup: provider.setup,
+        analyze: provider.analyze,
+        dispose: () => undefined,
+    }),
+}));
+vi.mock('../storage/local-memory.js', () => ({ checkLocalPatterns: async () => [] }));
+const { DeepAnalysisGate } = await import('./deep-analysis.js');
+const REPORT_TS = [
+    'export async function loadReport(days: number) {',
+    '  const rows = await fetchAll(days);',
+    '  return rows.length;',
+    '}',
+].join('\n');
+describe('DeepAnalysisGate', () => {
+    let cwd;
+    beforeEach(async () => {
+        cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-deep-gate-'));
+        await fs.outputFile(path.join(cwd, 'src/report.ts'), REPORT_TS);
+        await fs.outputFile(path.join(cwd, 'src/other.ts'), 'export const other = 1;\nexport const two = 2;\nexport const three = 3;\n');
+        provider.setup.mockReset().mockResolvedValue(undefined);
+        provider.analyze.mockReset().mockResolvedValue('{"findings": []}');
+    });
+    afterEach(async () => { await fs.remove(cwd); });
+    const gate = () => new DeepAnalysisGate({ options: { enabled: true, provider: 'local' } });
+    it('records an error outcome when setup fails', async () => {
+        provider.setup.mockRejectedValue(new Error('engine missing'));
+        const g = gate();
+        expect(await g.run({ cwd })).toEqual([]);
+        expect(g.getOutcome()).toMatchObject({ status: 'error', error: 'engine missing' });
+    });
+    it('records an error outcome when every inference call fails', async () => {
+        provider.analyze.mockRejectedValue(new Error('invalid argument: --json'));
+        const g = gate();
+        await g.run({ cwd, patterns: ['src/report.ts', 'src/other.ts'] });
+        expect(g.getOutcome()).toMatchObject({ status: 'error', chunksTotal: 2, chunksFailed: 2 });
+        expect(g.getOutcome().error).toContain('invalid argument: --json');
+    });
+    it('records a partial outcome when some calls fail', async () => {
+        provider.analyze.mockRejectedValueOnce(new Error('timed out')).mockResolvedValue('{"findings": []}');
+        const g = gate();
+        await g.run({ cwd, patterns: ['src/report.ts', 'src/other.ts'] });
+        expect(g.getOutcome()).toMatchObject({ status: 'partial', chunksTotal: 2, chunksFailed: 1 });
+    });
+    it('reviews only the scoped file, with its numbered source', async () => {
+        const g = gate();
+        await g.run({ cwd, patterns: ['src/report.ts'] });
+        expect(provider.analyze).toHaveBeenCalledTimes(1);
+        const prompt = provider.analyze.mock.calls[0][0];
+        expect(prompt).toContain('2|   const rows = await fetchAll(days);');
+        expect(prompt).not.toContain('src/other.ts');
+        expect(g.getOutcome()).toMatchObject({ status: 'ok', mode: 'code', filesAnalyzed: 1 });
+    });
+    it('keeps grounded findings and drops ones about code that was not sent', async () => {
+        provider.analyze.mockResolvedValue(JSON.stringify({ findings: [
+                { category: 'scalability', severity: 'high', file: 'src/report.ts', line: 2, description: '`fetchAll` loads every row.', suggestion: 'Aggregate in SQL.', confidence: 0.8 },
+                { category: 'security', severity: 'high', file: 'src/report.ts', line: 3, description: '`sendSecret` leaks a token.', suggestion: 'x', confidence: 0.9 },
+            ] }));
+        const failures = await gate().run({ cwd, patterns: ['src/report.ts'] });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ id: 'deep-analysis', files: ['src/report.ts'], line: 2, provenance: 'deep-analysis', verified: true });
+    });
+    it('uses the facts prompt for an unscoped run', async () => {
+        const g = gate();
+        await g.run({ cwd });
+        expect(provider.analyze.mock.calls[0][0]).toContain('AST-EXTRACTED FACTS');
+        expect(g.getOutcome()).toMatchObject({ status: 'ok', mode: 'facts', filesAnalyzed: 2 });
+    });
+    it('is ok with no analyzable files in scope', async () => {
+        const g = gate();
+        expect(await g.run({ cwd, patterns: ['README.md'] })).toEqual([]);
+        expect(g.getOutcome()).toMatchObject({ status: 'ok', filesAnalyzed: 0 });
+        expect(provider.analyze).not.toHaveBeenCalled();
+    });
+});

package/dist/gates/deep-runner.d.ts

@@ -0,0 +1,15 @@
+import type { GateContext } from './base.js';
+import type { Config, DeepOptions, Failure, Report, Status } from '../types/index.js';
+export interface DeepRunResult {
+    failures: Failure[];
+    summary: Status;
+    stats: NonNullable<Report['stats']['deep']>;
+}
+/**
+ * Run the deep gate and turn its outcome into summary, stats and failures.
+ * A deep run that could not analyze anything is ERROR with a visible
+ * failure, never a clean PASS.
+ */
+export declare function runDeepAnalysis(config: Config, context: Pick<GateContext, 'cwd' | 'ignore' | 'patterns'>, deepOptions: DeepOptions & {
+    onProgress?: (msg: string) => void;
+}): Promise<DeepRunResult>;