@rigour-labs/core 6.2.5 → 6.3.0

package/dist/gates/side-effect-helpers/pattern-detection.js

@@ -71,7 +71,7 @@ export function pathsOverlap(watchPath, writePath) {
 // ═══════════════════════════════════════════════════════════════════
 // LOOP & RECURSION ANALYSIS — Context-aware body extraction
 // ═══════════════════════════════════════════════════════════════════
-import { findBlockEndBrace, findBlockEndIndent } from './scope-analysis.js';
+import { findBlockEndBrace, findBlockEndIndent, findExpressionEnd } from './scope-analysis.js';
 /**
  * Extract loop body with correct scope tracking.
  * Uses brace/indent matching (not just "next N lines").
@@ -122,13 +122,24 @@ export function extractFunctionDefs(lines, lang) {
                 ? findBlockEndIndent(lines, i)
                 : lang === 'rb'
                     ? findBlockEndRuby(lines, i)
-                    : findBlockEndBrace(lines, i);
+                    : isExpressionArrow(lines, i, stripped, m.index) ? findExpressionEnd(lines, i) : findBlockEndBrace(lines, i);
             defs.push({ name, start: i, end, params: lines[i] });
             break;
         }
     }
     return defs;
 }
+/** An arrow whose body is an expression, not a `{ ... }` block. */
+function isExpressionArrow(lines, line, stripped, matchAt) {
+    const arrow = stripped.indexOf('=>', matchAt);
+    if (arrow < 0)
+        return false;
+    const rest = stripped.slice(arrow + 2).trim();
+    if (rest !== '')
+        return !rest.startsWith('{');
+    const next = lines.slice(line + 1).find(l => l.trim() !== '');
+    return next !== undefined && !next.trim().startsWith('{');
+}
 function getFuncDefPatterns(lang) {
     switch (lang) {
         case 'py': return [/^\s*(?:async\s+)?def\s+(\w+)\s*\(/];
@@ -297,11 +308,24 @@ export function hasCatchWithContinue(body, lang) {
 // ═══════════════════════════════════════════════════════════════════
 // PROCESS & TIMER OPERATIONS
 // ═══════════════════════════════════════════════════════════════════
+/**
+ * Drop a trailing line comment (and whole comment lines) so prose such as
+ * "ported from the fork (verified …)" is not read as code. Strings are
+ * already blanked, so `//` inside a URL string is gone before this runs.
+ */
+function stripLineComment(line, lang) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('*') || trimmed.startsWith('/*'))
+        return '';
+    const marker = lang === 'py' || lang === 'rb' ? '#' : '//';
+    const at = line.indexOf(marker);
+    return at === -1 ? line : line.slice(0, at);
+}
 /**
  * Check if a line contains a process spawn call.
  */
 export function isProcessSpawn(line, lang) {
-    const stripped = stripStrings(line);
+    const stripped = stripLineComment(stripStrings(line), lang);
     const patterns = getSpawnPatterns(lang);
     for (const pat of patterns) {
         const m = pat.exec(stripped);
@@ -314,9 +338,13 @@ function getSpawnPatterns(lang) {
     switch (lang) {
         case 'js':
         case 'ts':
+            // A bare call (from a child_process import) or a call on a
+            // child_process namespace; `re.exec(src)` or `db.exec(sql)` is not a
+            // spawn. *Sync variants finish before returning, so they cannot orphan.
             return [
-                /\b(?:spawn|exec|execFile|fork|execa)\s*\(/,
-                /\bchild_process\.\w+\s*\(/,
+                /(?<![.\w$])(?:spawn|exec|execFile|fork)\s*\(/,
+                /(?<![.\w$])(?:execa|execaCommand)\s*\(/,
+                /\b(?:child_process|childProcess|cp)\.(?:spawn|exec|execFile|fork)\s*\(/,
             ];
         case 'py':
             return [
@@ -354,9 +382,9 @@ function getTimerCreatePatterns(lang) {
     switch (lang) {
         case 'js':
         case 'ts':
+            // setTimeout fires once and cannot run unbounded; only setInterval repeats.
             return [
                 [/\bsetInterval\s*\(/, 'setInterval'],
-                [/\bsetTimeout\s*\(/, 'setTimeout'],
             ];
         case 'py':
             return [
@@ -410,7 +438,7 @@ export function getProcessCleanupPatterns(lang) {
         case 'js':
         case 'ts':
             return [
-                /\.on\s*\(\s*['"](?:exit|close)['"]/,
+                /\.(?:on|once|addListener)\s*\(\s*['"](?:exit|close)['"]/,
                 /\.kill\s*\(/,
                 /\.disconnect\s*\(/,
             ];

package/dist/gates/side-effect-helpers/resource-tracking.js

@@ -39,8 +39,8 @@ export function extractVariableBinding(line, lang) {
     const jsMatch = stripped.match(/^(?:const|let|var|final|auto|val)\s+(\w+)\s*=\s*/);
     if (jsMatch)
         return jsMatch[1];
-    // Member assignment: `this.timer = ...`, `self.timer = ...`
-    const memberMatch = stripped.match(/^(?:this|self)\.([\w]+)\s*=\s*/);
+    // Member assignment: `this.timer = ...`, `self.timer = ...`, `this.#timer = ...`
+    const memberMatch = stripped.match(/^(?:this|self)\.(#?[\w]+)\s*=\s*/);
     if (memberMatch)
         return memberMatch[1];
     // Simple assignment: `timer = ...`
@@ -68,26 +68,33 @@ export function hasCleanupForVariable(lines, varName, scopeStart, scopeEnd, clea
     const scope = lines.slice(scopeStart, scopeEnd);
     for (let i = 0; i < scope.length; i++) {
         const stripped = stripStrings(scope[i]);
-        // Check cleanup patterns that reference the specific variable
+        // Check cleanup patterns that reference the specific variable. Some
+        // patterns need the quoted event name (`.once('exit', …)`), which
+        // stripStrings blanks, so they are also tried on the raw line.
         for (const pat of cleanupPatterns) {
-            if (!pat.test(stripped))
+            if (!pat.test(stripped) && !pat.test(scope[i]))
                 continue;
-            // The cleanup call should reference our variable
-            const escapedVar = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            const varRef = new RegExp(`\\b${escapedVar}\\b`);
-            if (varRef.test(stripped))
+            // The cleanup call should reference our variable. Lookarounds, not
+            // \b, so a private field such as `#timer` matches too.
+            if (variableReference(varName).test(stripped))
                 return true;
             // Also check method calls on the variable: timer.close(), timer.stop()
             // The pattern might match a generic .close() — check if it's on our var
         }
         // Direct method cleanup on the variable: varName.close(), varName.Stop()
-        const escapedVar = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const methodCleanup = new RegExp(`\\b${escapedVar}\\.(?:close|stop|destroy|kill|terminate|dispose|cancel|shutdown|unsubscribe|disconnect|end|release|Clear|Stop|Dispose|Close|Cancel)\\s*\\(`);
+        const escapedVar = escapeRegExp(varName);
+        const methodCleanup = new RegExp(`(?<![\\w$#])${escapedVar}\\.(?:close|stop|destroy|kill|terminate|dispose|cancel|shutdown|unsubscribe|disconnect|end|release|Clear|Stop|Dispose|Close|Cancel)\\s*\\(`);
         if (methodCleanup.test(stripped))
             return true;
     }
     return false;
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function variableReference(varName) {
+    return new RegExp(`(?<![\\w$#])${escapeRegExp(varName)}(?![\\w$])`);
+}
 /**
  * Check if a line is inside a cleanup/teardown context.
  *

package/dist/gates/side-effect-helpers/scope-analysis.d.ts

@@ -14,6 +14,12 @@ export declare function findEnclosingFunction(lines: string[], lineIdx: number,
  * Find the end of a brace-delimited block starting at `start`.
  */
 export declare function findBlockEndBrace(lines: string[], start: number): number;
+/**
+ * Find the end of an expression-bodied arrow (`const f = (x) => x + 1;`):
+ * the first line where brackets balance and the expression does not
+ * continue. Scanning for a `{` instead would run into the next block.
+ */
+export declare function findExpressionEnd(lines: string[], start: number): number;
 /**
  * Find the end of an indentation-delimited block (Python).
  */

package/dist/gates/side-effect-helpers/scope-analysis.js

@@ -95,6 +95,26 @@ export function findBlockEndBrace(lines, start) {
     }
     return maxScan;
 }
+/**
+ * Find the end of an expression-bodied arrow (`const f = (x) => x + 1;`):
+ * the first line where brackets balance and the expression does not
+ * continue. Scanning for a `{` instead would run into the next block.
+ */
+export function findExpressionEnd(lines, start) {
+    let depth = 0;
+    const maxScan = Math.min(lines.length, start + 300);
+    for (let j = start; j < maxScan; j++) {
+        const stripped = stripStrings(lines[j]);
+        depth += bracketDelta(stripped);
+        const continues = /(?:=>|[=+\-*/%&|?:,.(])\s*$/.test(stripped.trimEnd());
+        if (depth <= 0 && !continues)
+            return j + 1;
+    }
+    return maxScan;
+}
+function bracketDelta(text) {
+    return (text.match(/[([{]/g)?.length ?? 0) - (text.match(/[)\]}]/g)?.length ?? 0);
+}
 /**
  * Find the end of an indentation-delimited block (Python).
  */

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './stor
 export type { ProjectStats } from './storage/index.js';
 export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
 export type { ApplicableLessons, InteractionEvidence, LessonRecord, LessonState, LessonVisibility, LocalLessonImportOptions, LocalLessonImportResult } from './storage/index.js';
-export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 export type { TeamConfiguration, TeamSemanticConfiguration, TeamModeStatus, TeamDoctorResult, SemanticKnowledgeCandidate, SemanticKnowledgeResult, } from './storage/index.js';
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 export type { TemporalDriftReport, ProvenanceStream, MonthlyBucket, WeeklyBucket, DriftDirection } from './services/temporal-drift.js';
@@ -51,4 +51,8 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
+export { learnFromFix, type LearnReport, type Rejection } from './semantic/learn/learn.js';
+export { extractFixTrees, type FixTrees } from './semantic/learn/git-trees.js';
+export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
+export type { LearnedRule, LearnedPattern } from './semantic/learn/types.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';

package/dist/index.js

@@ -30,7 +30,7 @@ export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, rese
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
 export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
-export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 // Temporal Drift Engine (v5 — cross-session trend analysis + per-provenance EWMA)
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 // Adaptive Thresholds (v5 — Z-score + per-provenance trends)
@@ -50,6 +50,9 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
+export { learnFromFix } from './semantic/learn/learn.js';
+export { extractFixTrees } from './semantic/learn/git-trees.js';
+export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';
 // Pattern Index is intentionally NOT exported here to prevent
 // native dependency issues (sharp/transformers) from leaking into

package/dist/inference/sidecar-provider.js

@@ -9,6 +9,7 @@
  *
  * Code never leaves the machine: prompts go to a local child process.
  */
+import crypto from 'crypto';
 import path from 'path';
 import os from 'os';
 import fs from 'fs-extra';
@@ -88,7 +89,7 @@ export class SidecarProvider {
             maxTokens: options?.maxTokens || 1024,
             threads: this.threads,
             temperature: options?.temperature ?? 0.1,
-            schemaPath: options?.jsonMode ? this.schemaPath ?? undefined : undefined,
+            schemaPath: options?.jsonSchema ? await schemaFileFor(options.jsonSchema) : options?.jsonMode ? this.schemaPath ?? undefined : undefined,
         });
         let result;
         try {
@@ -159,6 +160,16 @@ async function findOnPath(name) {
         return null;
     }
 }
+/** A schema file per distinct schema, written once and reused across calls. */
+async function schemaFileFor(schema) {
+    const text = JSON.stringify(schema);
+    const schemaPath = path.join(managedEngineDir(), '..', 'schemas', `${crypto.createHash('sha256').update(text).digest('hex').slice(0, 16)}.json`);
+    if (!(await fs.pathExists(schemaPath))) {
+        await fs.ensureDir(path.dirname(schemaPath));
+        await fs.writeFile(schemaPath, text);
+    }
+    return schemaPath;
+}
 async function writeFindingsSchema() {
     const schemaPath = path.join(managedEngineDir(), '..', 'findings.schema.json');
     await fs.ensureDir(path.dirname(schemaPath));

package/dist/inference/types.d.ts

@@ -29,6 +29,8 @@ export interface InferenceOptions {
     temperature?: number;
     timeout?: number;
     jsonMode?: boolean;
+    /** Constrain local output to this JSON schema instead of the findings schema. */
+    jsonSchema?: Record<string, unknown>;
 }
 /**
  * A single finding from deep LLM analysis.

package/dist/semantic/ast.d.ts

@@ -0,0 +1,29 @@
+import ts from 'typescript';
+export type FunctionLike = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration;
+export declare function isFunctionLike(node: ts.Node): node is FunctionLike;
+/** Drop parentheses, type assertions, non-null and `await` around an expression. */
+export declare function unwrap(expr: ts.Expression): ts.Expression;
+/**
+ * Symbol for a node, following import aliases to the declaration. For the
+ * name in a shorthand property (`{ headers }`) this is the variable it reads,
+ * not the property it creates.
+ */
+export declare function symbolOf(checker: ts.TypeChecker, node: ts.Node): ts.Symbol | undefined;
+/** The function a call invokes, when it resolves to one declared in source. */
+export declare function calledFunction(checker: ts.TypeChecker, call: ts.CallExpression): FunctionLike | undefined;
+/** `fetch` in `fetch(...)`, `deps.fetch(...)`, `this.fetch(...)`. */
+export declare function calleeName(call: ts.CallExpression): string | undefined;
+export declare function enclosingFunction(node: ts.Node): FunctionLike | undefined;
+/** Visit every descendant of `root` that belongs to `root` itself, not to a nested function. */
+export declare function forEachOwnNode(root: ts.Node, visit: (node: ts.Node) => void): void;
+export declare function forEachNode(root: ts.Node, visit: (node: ts.Node) => void): void;
+/** Text of a property name (`a`, `'a'`, `"x-token"`), or undefined for computed names. */
+export declare function propertyNameText(name: ts.PropertyName | undefined): string | undefined;
+export declare function lineOf(node: ts.Node): number;
+/** "http.ts:51" style location for evidence, relative to cwd. */
+export declare function locationOf(cwd: string, node: ts.Node): string;
+export declare function relativeFile(cwd: string, sf: ts.SourceFile): string;
+/** Short, single-line source text for messages. */
+export declare function snippet(node: ts.Node, max?: number): string;
+/** True when any identifier inside `expr` resolves to `target`. */
+export declare function mentionsSymbol(checker: ts.TypeChecker, expr: ts.Node, target: ts.Symbol): boolean;

package/dist/semantic/ast.js

@@ -0,0 +1,122 @@
+/**
+ * Small, checker-aware AST helpers shared by the semantic rules.
+ */
+import path from 'path';
+import ts from 'typescript';
+export function isFunctionLike(node) {
+    return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)
+        || ts.isArrowFunction(node) || ts.isMethodDeclaration(node);
+}
+/** Drop parentheses, type assertions, non-null and `await` around an expression. */
+export function unwrap(expr) {
+    let current = expr;
+    for (;;) {
+        if (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current)
+            || ts.isTypeAssertionExpression(current) || ts.isSatisfiesExpression(current) || ts.isAwaitExpression(current)) {
+            current = current.expression;
+        }
+        else {
+            return current;
+        }
+    }
+}
+/**
+ * Symbol for a node, following import aliases to the declaration. For the
+ * name in a shorthand property (`{ headers }`) this is the variable it reads,
+ * not the property it creates.
+ */
+export function symbolOf(checker, node) {
+    const symbol = ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node
+        ? checker.getShorthandAssignmentValueSymbol(node.parent)
+        : checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        return checker.getAliasedSymbol(symbol);
+    return symbol;
+}
+/** The function a call invokes, when it resolves to one declared in source. */
+export function calledFunction(checker, call) {
+    const symbol = symbolOf(checker, call.expression);
+    for (const decl of symbol?.declarations ?? []) {
+        if (isFunctionLike(decl) && decl.body)
+            return decl;
+        if ((ts.isVariableDeclaration(decl) || ts.isPropertyAssignment(decl)) && decl.initializer) {
+            const init = unwrap(decl.initializer);
+            if (isFunctionLike(init) && init.body)
+                return init;
+        }
+    }
+    return undefined;
+}
+/** `fetch` in `fetch(...)`, `deps.fetch(...)`, `this.fetch(...)`. */
+export function calleeName(call) {
+    const callee = unwrap(call.expression);
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return undefined;
+}
+export function enclosingFunction(node) {
+    for (let current = node.parent; current; current = current.parent) {
+        if (isFunctionLike(current))
+            return current;
+    }
+    return undefined;
+}
+/** Visit every descendant of `root` that belongs to `root` itself, not to a nested function. */
+export function forEachOwnNode(root, visit) {
+    const walk = (node) => {
+        visit(node);
+        if (node !== root && isFunctionLike(node))
+            return;
+        ts.forEachChild(node, walk);
+    };
+    ts.forEachChild(root, walk);
+}
+export function forEachNode(root, visit) {
+    const walk = (node) => {
+        visit(node);
+        ts.forEachChild(node, walk);
+    };
+    ts.forEachChild(root, walk);
+}
+/** Text of a property name (`a`, `'a'`, `"x-token"`), or undefined for computed names. */
+export function propertyNameText(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    if (ts.isNoSubstitutionTemplateLiteral(name))
+        return name.text;
+    return undefined;
+}
+export function lineOf(node) {
+    const sf = node.getSourceFile();
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+/** "http.ts:51" style location for evidence, relative to cwd. */
+export function locationOf(cwd, node) {
+    return `${relativeFile(cwd, node.getSourceFile())}:${lineOf(node)}`;
+}
+export function relativeFile(cwd, sf) {
+    return path.relative(cwd, sf.fileName).replace(/\\/g, '/');
+}
+/** Short, single-line source text for messages. */
+export function snippet(node, max = 60) {
+    const text = node.getText(node.getSourceFile()).replace(/\s+/g, ' ');
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+/** True when any identifier inside `expr` resolves to `target`. */
+export function mentionsSymbol(checker, expr, target) {
+    let found = false;
+    const walk = (node) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(node) && symbolOf(checker, node) === target)
+            found = true;
+        else
+            ts.forEachChild(node, walk);
+    };
+    walk(expr);
+    return found;
+}

package/dist/semantic/benchmark.d.ts

@@ -0,0 +1,16 @@
+export interface BenchmarkCase {
+    name: string;
+    rule: string | null;
+    file: string | null;
+    line: number | null;
+    note: string;
+}
+export interface CaseResult {
+    case: BenchmarkCase;
+    /** Expected finding reported on `before/` (true for negatives). */
+    caught: boolean;
+    /** Findings on `after/` plus unexpected findings on `before/`. */
+    falsePositives: string[];
+}
+export declare function loadCases(root: string): BenchmarkCase[];
+export declare function runCase(root: string, bench: BenchmarkCase): CaseResult;

package/dist/semantic/benchmark.js

@@ -0,0 +1,31 @@
+/**
+ * Semantic benchmark: synthetic before/after cases per bug class.
+ *
+ * `before/` must produce the expected finding (recall); `after/` and cases
+ * with `rule: null` must produce none (false positives).
+ */
+import fs from 'fs';
+import path from 'path';
+import { analyzeFiles } from './engine.js';
+export function loadCases(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
+        .map(entry => ({ name: entry.name, ...JSON.parse(fs.readFileSync(path.join(root, entry.name, 'case.json'), 'utf8')) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function runCase(root, bench) {
+    const before = findingsIn(path.join(root, bench.name, 'before'));
+    const after = findingsIn(path.join(root, bench.name, 'after'));
+    const isExpected = (f) => bench.rule !== null && f === `${bench.rule} ${bench.file}:${bench.line}`;
+    return {
+        case: bench,
+        caught: bench.rule === null || before.some(isExpected),
+        falsePositives: [...before.filter(f => !isExpected(f)).map(f => `before: ${f}`), ...after.map(f => `after: ${f}`)],
+    };
+}
+function findingsIn(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const files = fs.readdirSync(dir).filter(f => /\.[cm]?[jt]sx?$/.test(f));
+    return analyzeFiles(dir, files).map(f => `${f.rule} ${f.file}:${f.line}`);
+}

package/dist/semantic/benchmark.test.d.ts

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

package/dist/semantic/benchmark.test.js

@@ -0,0 +1,18 @@
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { loadCases, runCase } from './benchmark.js';
+const ROOT = path.resolve(__dirname, '../../../../benchmarks/semantic');
+describe('semantic benchmark', () => {
+    const cases = loadCases(ROOT);
+    it('has cases for every built-in rule, including negatives', () => {
+        const rules = new Set(cases.map(c => c.rule));
+        expect(rules).toEqual(new Set(['in-memory-aggregation', 'credential-redirect', 'degraded-response-cached', null]));
+    });
+    for (const bench of cases) {
+        it(`${bench.name}: ${bench.note}`, () => {
+            const result = runCase(ROOT, bench);
+            expect(result.falsePositives).toEqual([]);
+            expect(result.caught).toBe(true);
+        });
+    }
+});

package/dist/semantic/engine.d.ts

@@ -0,0 +1,8 @@
+import type { SemanticFinding, SemanticRule } from './types.js';
+export declare const BUILT_IN_RULES: SemanticRule[];
+export interface EngineOptions {
+    rules?: SemanticRule[];
+    batchSize?: number;
+}
+/** Analyze `files` (cwd-relative or absolute). Declaration files are skipped. */
+export declare function analyzeFiles(cwd: string, files: string[], opts?: EngineOptions): SemanticFinding[];

package/dist/semantic/engine.js

@@ -0,0 +1,45 @@
+/**
+ * Runs semantic rules over a set of JS/TS files.
+ */
+import path from 'path';
+import { loadProjectConfig, programBatches } from './program.js';
+import { Summaries } from './summaries.js';
+import { inMemoryAggregation } from './rules/in-memory-aggregation.js';
+import { credentialRedirect } from './rules/credential-redirect.js';
+import { degradedResponseCached } from './rules/degraded-response-cached.js';
+export const BUILT_IN_RULES = [inMemoryAggregation, credentialRedirect, degradedResponseCached];
+/** Analyze `files` (cwd-relative or absolute). Declaration files are skipped. */
+export function analyzeFiles(cwd, files, opts = {}) {
+    const rules = opts.rules ?? BUILT_IN_RULES;
+    const roots = files
+        .filter(f => /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(f) && !/\.d\.[cm]?ts$/i.test(f))
+        .map(f => path.resolve(cwd, f));
+    if (roots.length === 0 || rules.length === 0)
+        return [];
+    const { options } = loadProjectConfig(cwd);
+    const rootSet = new Set(roots.map(r => path.normalize(r)));
+    const findings = [];
+    for (const program of programBatches(roots, options, opts.batchSize)) {
+        const checker = program.getTypeChecker();
+        const summaries = new Summaries(checker);
+        for (const sourceFile of program.getSourceFiles()) {
+            if (!rootSet.has(path.normalize(sourceFile.fileName)))
+                continue;
+            for (const rule of rules) {
+                findings.push(...rule.check({ cwd, checker, sourceFile, summaries }));
+            }
+            rootSet.delete(path.normalize(sourceFile.fileName));
+        }
+    }
+    return dedupe(findings);
+}
+function dedupe(findings) {
+    const seen = new Set();
+    return findings.filter(f => {
+        const key = `${f.rule}:${f.file}:${f.line}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/semantic/intent/benchmark.d.ts

@@ -0,0 +1,31 @@
+import { type ReadVerdict, type YesNoModel } from './intent-check.js';
+export interface IntentCase {
+    name: string;
+    note: string;
+    labels: Record<string, 'optional' | 'required'>;
+    expectFinding: boolean;
+    /** False when the finder must skip the site (no model call). */
+    expectSite?: boolean;
+}
+export interface IntentCaseResult {
+    case: IntentCase;
+    siteFound: boolean;
+    verdicts: ReadVerdict[];
+    findings: number;
+}
+export interface IntentScore {
+    /** Individual answers matching the label (question 1 expects yes for optional, question 2 no). */
+    rawCorrect: number;
+    rawTotal: number;
+    /** Reads whose flipped answers agreed, and how many of those were right. */
+    consistent: number;
+    consistentCorrect: number;
+    reads: number;
+    truePositives: number;
+    falseNegatives: number;
+    falsePositives: number;
+    finderErrors: string[];
+}
+export declare function loadIntentCases(root: string): IntentCase[];
+export declare function runIntentCase(root: string, bench: IntentCase, model: YesNoModel): Promise<IntentCaseResult>;
+export declare function scoreIntent(results: IntentCaseResult[]): IntentScore;