@rigour-labs/core 6.5.2 → 6.5.3

package/README.md

@@ -46,7 +46,7 @@ Rigour's deep analysis is not a wrapper around a generic LLM. The model operates
 2. **Interpret** — the model receives structured facts (not raw source), focuses on SOLID, design patterns, language idioms, architecture. Constrained input prevents hallucination.
 3. **Verify** — every LLM finding is cross-referenced against all five signal streams. Wrong line numbers, phantom patterns, non-existent functions → discarded. Only verified findings with confidence scores reach the report.
 
-Both model tiers (lite sidecar + pro code-specialized) are fine-tuned via the [DriftBench RLAIF pipeline](https://github.com/rigour-labs/driftbench) where the five signal streams serve as the teacher signal.
+The lite and deep tiers are fine-tuned via the [DriftBench RLAIF pipeline](https://github.com/rigour-labs/driftbench), where the five signal streams serve as the teacher signal. The max tier (Qwen2.5-Coder-7B) runs the stock model until a fine-tune passes the evaluation gate.
 
 ### Temporal Drift Engine (v5.1)
 

package/dist/context/automatic-index.d.ts

@@ -8,6 +8,11 @@ export interface AutomaticIndexStatus {
     updatedAt: string;
 }
 export declare function mergeSemanticEmbeddings(latest: PatternIndex, enriched: PatternIndex): PatternIndex;
+/**
+ * What an explicit `rigour index` (CLI or MCP) chose, so automatic indexing and Studio's health
+ * agree with it: 'disabled' for --no-semantic, else ready or degraded by what was embedded.
+ */
+export declare function recordIndexChoice(cwd: string, index: PatternIndex, semantic: boolean): Promise<void>;
 export declare function getAutomaticIndexStatus(cwd: string): Promise<AutomaticIndexStatus>;
 export declare function ensureAutomaticIndex(cwd: string, options?: {
     backgroundSemantic?: boolean;

package/dist/context/automatic-index.js

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { PatternIndexer, getDefaultIndexPath, loadPatternIndex, savePatternIndex } from '../pattern-index/indexer.js';
+import { EMBEDDING_TEXT_VERSION } from '../pattern-index/embeddings.js';
 import { affectedDependents, buildDependencyGraph, updateDependencyGraph } from './dependency-graph.js';
 import { syncIndexToContextCache } from './index-bridge.js';
 const enrichmentJobs = new Map();
@@ -33,15 +34,35 @@ async function writeStatus(cwd, status) {
     await fs.ensureDir(path.join(cwd, '.rigour'));
     await fs.writeJson(statusPath(cwd), status, { spaces: 2 });
 }
+/** Embedded, and from the current embedding text (an older one is re-embedded on enrichment). */
+function hasCurrentEmbeddings(index) {
+    return index.embeddingTextVersion === EMBEDDING_TEXT_VERSION
+        && index.patterns.some(pattern => (pattern.embedding?.length ?? 0) > 0);
+}
+/**
+ * What an explicit `rigour index` (CLI or MCP) chose, so automatic indexing and Studio's health
+ * agree with it: 'disabled' for --no-semantic, else ready or degraded by what was embedded.
+ */
+export async function recordIndexChoice(cwd, index, semantic) {
+    const embedded = index.patterns.filter(pattern => (pattern.embedding?.length ?? 0) > 0).length;
+    await writeStatus(cwd, {
+        structural: 'ready',
+        graph: 'ready',
+        semantic: !semantic ? 'disabled' : embedded > 0 ? 'ready' : 'degraded',
+        ...(semantic && embedded === 0 ? { message: 'Local embedding model unavailable; text matching remains active.' } : {}),
+        updatedAt: new Date().toISOString(),
+    });
+}
 export async function getAutomaticIndexStatus(cwd) {
     try {
         return await fs.readJson(statusPath(cwd));
     }
     catch {
+        // No status yet is not an opt-out: only `rigour index --no-semantic` records 'disabled'.
         return {
             structural: 'missing',
             graph: 'missing',
-            semantic: 'disabled',
+            semantic: 'warming',
             updatedAt: new Date().toISOString(),
         };
     }
@@ -97,7 +118,7 @@ export async function ensureAutomaticIndex(cwd, options = {}) {
     if (!(await fs.pathExists(path.join(cwd, '.rigour', 'dependency-graph.json')))) {
         await buildDependencyGraph(cwd, index);
     }
-    const hasEmbeddings = index.patterns.some((pattern) => (pattern.embedding?.length ?? 0) > 0);
+    const hasEmbeddings = hasCurrentEmbeddings(index);
     await writeStatus(cwd, {
         structural: 'ready',
         graph: 'ready',
@@ -130,7 +151,7 @@ export async function updateAutomaticIndexForFiles(cwd, changedFiles) {
         await buildDependencyGraph(cwd, index);
     await writeStatus(cwd, {
         structural: 'ready', graph: 'ready',
-        semantic: index.patterns.some(pattern => (pattern.embedding?.length ?? 0) > 0)
+        semantic: hasCurrentEmbeddings(index)
             ? 'ready'
             : previousStatus.semantic === 'disabled' ? 'disabled' : 'warming',
         message: `${normalizedChangedFiles.length} changed file(s); ${affectedFiles.length} affected file(s) refreshed without a full scan.`,

package/dist/context/index-status.test.d.ts

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

package/dist/context/index-status.test.js

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { getAutomaticIndexStatus, recordIndexChoice } from './automatic-index.js';
+let cwd;
+beforeEach(() => { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'index-status-')); });
+afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));
+const index = (embedded) => ({
+    version: '1.0.0', lastUpdated: '', rootDir: cwd, files: [],
+    patterns: [{ id: 'a', type: 'function', name: 'a', file: 'a.ts', line: 1, endLine: 1, signature: '', description: '', keywords: [], hash: 'a', exported: true, usageCount: 0, indexedAt: '', ...(embedded ? { embedding: [0.1] } : {}) }],
+    stats: { totalPatterns: 1, totalFiles: 1, byType: {}, indexDurationMs: 0 },
+});
+describe('semantic index status', () => {
+    it('treats no status yet as warming, not as an opt-out', async () => {
+        expect((await getAutomaticIndexStatus(cwd)).semantic).toBe('warming');
+    });
+    it('records what an explicit index chose, so automatic indexing and Studio agree', async () => {
+        await recordIndexChoice(cwd, index(false), false);
+        expect((await getAutomaticIndexStatus(cwd)).semantic).toBe('disabled');
+        await recordIndexChoice(cwd, index(true), true);
+        expect((await getAutomaticIndexStatus(cwd)).semantic).toBe('ready');
+        await recordIndexChoice(cwd, index(false), true);
+        expect((await getAutomaticIndexStatus(cwd)).semantic).toBe('degraded');
+    });
+});

package/dist/gates/dedupe-failures.test.d.ts

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

package/dist/gates/dedupe-failures.test.js

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { dedupeFailures } from './runner.js';
+const finding = (title, line = 3) => ({ id: 'semantic-bugs', title, details: '', severity: 'high', provenance: 'traditional', files: ['src/a.ts'], line });
+describe('dedupeFailures', () => {
+    it('keeps a learned rule that fires on the same line as a built-in rule of the same gate', () => {
+        const kept = dedupeFailures([finding('credential-redirect'), finding('learned-rule: require-option-redirect')]);
+        expect(kept.map(f => f.title)).toEqual(['credential-redirect', 'learned-rule: require-option-redirect']);
+    });
+    it('still drops the same rule reported twice on one line', () => {
+        expect(dedupeFailures([finding('credential-redirect'), finding('credential-redirect'), finding('credential-redirect', 9)])).toHaveLength(2);
+    });
+});

package/dist/gates/deprecated-dependencies.d.ts

@@ -0,0 +1,27 @@
+import { Gate, type GateContext } from './base.js';
+import type { Failure } from '../types/index.js';
+export interface DeprecatedDependenciesConfig {
+    enabled?: boolean;
+    registry?: string;
+}
+type Fetch = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    json(): Promise<any>;
+}>;
+export declare class DeprecatedDependenciesGate extends Gate {
+    private config;
+    private fetchImpl;
+    constructor(config?: DeprecatedDependenciesConfig, fetchImpl?: Fetch);
+    run(context: GateContext): Promise<Failure[]>;
+    /** Deprecation messages for installed versions, from the day's cache and then the registry. */
+    private deprecations;
+    /** The version's deprecation message, null when it is not deprecated, undefined when the registry did not answer. */
+    private lookup;
+}
+/** Installed versions from package-lock.json, else node_modules; names with neither are left out. */
+export declare function installedVersions(cwd: string, names: string[]): Promise<Map<string, string>>;
+/** The package.json line declaring a dependency, so review can tell whether the change touched it. */
+export declare function lineOfDependency(manifestText: string, name: string): number | undefined;
+export {};

package/dist/gates/deprecated-dependencies.js

@@ -0,0 +1,104 @@
+/**
+ * Deprecated dependencies: a package.json dependency whose installed version
+ * npm marks deprecated.
+ *
+ * npm deprecates individual versions, so the check asks about the version
+ * actually installed (package-lock.json, else node_modules), never the latest;
+ * a dependency whose installed version cannot be known says nothing. The
+ * finding sits on the dependency's line in package.json, so review reports it
+ * when a change adds or moves a dependency onto a deprecated version.
+ *
+ * Opt-in and advisory: it sends package names and versions to the registry
+ * (as `npm install` does). Answers are cached for a day in .rigour/; a slow or
+ * unreachable registry means no findings, never a failed check.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { Gate } from './base.js';
+import { Logger } from '../utils/logger.js';
+const CACHE_FILE = path.join('.rigour', 'deprecated-dependencies.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const TIMEOUT_MS = 3000;
+const CONCURRENCY = 8;
+const MAX_PACKAGES = 300;
+export class DeprecatedDependenciesGate extends Gate {
+    config;
+    fetchImpl;
+    constructor(config = {}, fetchImpl = fetch) {
+        super('deprecated-dependencies', 'Deprecated dependency');
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async run(context) {
+        if (!this.config.enabled)
+            return [];
+        const manifestPath = path.join(context.cwd, 'package.json');
+        if (!(await fs.pathExists(manifestPath)))
+            return [];
+        const manifestText = await fs.readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(manifestText);
+        const names = Object.keys({ ...manifest.dependencies, ...manifest.devDependencies }).slice(0, MAX_PACKAGES);
+        const installed = await installedVersions(context.cwd, names);
+        const answers = await this.deprecations(context.cwd, installed);
+        return [...answers].flatMap(([name, message]) => [this.createFailure(`${name}@${installed.get(name)} is deprecated on npm: ${message}`, ['package.json'], `Move to the replacement the deprecation names, or a supported version of ${name}.`, undefined, lineOfDependency(manifestText, name), undefined, 'medium')]);
+    }
+    /** Deprecation messages for installed versions, from the day's cache and then the registry. */
+    async deprecations(cwd, installed) {
+        const cachePath = path.join(cwd, CACHE_FILE);
+        const cache = await fs.readJson(cachePath).catch(() => ({}));
+        const now = Date.now();
+        const stale = [...installed].filter(([name, version]) => !(cache[`${name}@${version}`]?.checkedAt > now - CACHE_TTL_MS));
+        let unreachable = 0;
+        for (let i = 0; i < stale.length; i += CONCURRENCY) {
+            await Promise.all(stale.slice(i, i + CONCURRENCY).map(async ([name, version]) => {
+                const deprecated = await this.lookup(name, version);
+                if (deprecated === undefined)
+                    unreachable++;
+                else
+                    cache[`${name}@${version}`] = { deprecated, checkedAt: now };
+            }));
+        }
+        if (unreachable)
+            Logger.info(`Deprecated dependencies: registry did not answer for ${unreachable} package(s); they are skipped this run.`);
+        await fs.outputJson(cachePath, cache, { spaces: 2 }).catch(() => undefined);
+        const found = new Map();
+        for (const [name, version] of installed) {
+            const message = cache[`${name}@${version}`]?.deprecated;
+            if (message)
+                found.set(name, message);
+        }
+        return found;
+    }
+    /** The version's deprecation message, null when it is not deprecated, undefined when the registry did not answer. */
+    async lookup(name, version) {
+        const registry = (this.config.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+        try {
+            const response = await this.fetchImpl(`${registry}/${name.replace('/', '%2F')}/${encodeURIComponent(version)}`, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+            if (!response.ok)
+                return undefined;
+            const body = await response.json();
+            return typeof body?.deprecated === 'string' && body.deprecated.trim() ? body.deprecated.trim() : null;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Installed versions from package-lock.json, else node_modules; names with neither are left out. */
+export async function installedVersions(cwd, names) {
+    const lock = await fs.readJson(path.join(cwd, 'package-lock.json')).catch(() => null);
+    const versions = new Map();
+    for (const name of names) {
+        const fromLock = lock?.packages?.[`node_modules/${name}`]?.version ?? lock?.dependencies?.[name]?.version;
+        const fromModules = fromLock ? undefined : (await fs.readJson(path.join(cwd, 'node_modules', name, 'package.json')).catch(() => null))?.version;
+        const version = fromLock ?? fromModules;
+        if (typeof version === 'string' && /^\d+\.\d+\.\d+/.test(version))
+            versions.set(name, version);
+    }
+    return versions;
+}
+/** The package.json line declaring a dependency, so review can tell whether the change touched it. */
+export function lineOfDependency(manifestText, name) {
+    const at = manifestText.split('\n').findIndex(line => line.trimStart().startsWith(`${JSON.stringify(name)}:`));
+    return at >= 0 ? at + 1 : undefined;
+}

package/dist/gates/deprecated-dependencies.test.d.ts

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

package/dist/gates/deprecated-dependencies.test.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DeprecatedDependenciesGate, installedVersions, lineOfDependency } from './deprecated-dependencies.js';
+let cwd;
+beforeEach(() => {
+    cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'deprecated-deps-'));
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { request: '^2.88.0', 'left-pad': '^1.3.0' }, devDependencies: { '@scope/tool': '1.0.0' } }, null, 2));
+    fs.writeFileSync(path.join(cwd, 'package-lock.json'), JSON.stringify({ packages: {
+            'node_modules/request': { version: '2.88.2' },
+            'node_modules/@scope/tool': { version: '1.0.0' },
+        } }));
+});
+afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));
+/** A registry answering per exact version, like registry.npmjs.org/<name>/<version>. */
+const registry = (deprecated) => vi.fn(async (url) => {
+    const [, name, version] = /registry\.test\/(.+)\/([^/]+)$/.exec(url);
+    return { ok: true, json: async () => ({ version, deprecated: deprecated[`${decodeURIComponent(name)}@${version}`] }) };
+});
+describe('DeprecatedDependenciesGate', () => {
+    it('reports the installed version npm deprecated, on its package.json line', async () => {
+        const fetch = registry({ 'request@2.88.2': 'request has been deprecated' });
+        const failures = await new DeprecatedDependenciesGate({ enabled: true, registry: 'https://registry.test' }, fetch).run({ cwd });
+        expect(failures).toEqual([expect.objectContaining({ id: 'deprecated-dependencies', files: ['package.json'], line: 3 })]);
+        expect(failures[0].details).toContain('request@2.88.2 is deprecated on npm: request has been deprecated');
+        expect(fetch.mock.calls.map(c => c[0])).toEqual(['https://registry.test/request/2.88.2', 'https://registry.test/@scope%2Ftool/1.0.0']);
+    });
+    it('asks once a day, and says nothing for a version it cannot determine or a registry that does not answer', async () => {
+        const fetch = registry({ 'request@2.88.2': 'deprecated' });
+        const gate = new DeprecatedDependenciesGate({ enabled: true, registry: 'https://registry.test' }, fetch);
+        await gate.run({ cwd });
+        await gate.run({ cwd });
+        expect(fetch).toHaveBeenCalledTimes(2); // left-pad has no installed version; the second run is cached
+        fs.rmSync(path.join(cwd, '.rigour'), { recursive: true });
+        const down = vi.fn(async () => { throw new Error('offline'); });
+        expect(await new DeprecatedDependenciesGate({ enabled: true }, down).run({ cwd })).toEqual([]);
+    });
+    it('is off unless enabled', async () => {
+        const fetch = registry({});
+        expect(await new DeprecatedDependenciesGate({}, fetch).run({ cwd })).toEqual([]);
+        expect(fetch).not.toHaveBeenCalled();
+    });
+});
+describe('helpers', () => {
+    it('reads installed versions from the lockfile, else node_modules', async () => {
+        fs.mkdirSync(path.join(cwd, 'node_modules', 'left-pad'), { recursive: true });
+        fs.writeFileSync(path.join(cwd, 'node_modules', 'left-pad', 'package.json'), JSON.stringify({ version: '1.3.0' }));
+        expect([...(await installedVersions(cwd, ['request', 'left-pad', 'missing']))]).toEqual([['request', '2.88.2'], ['left-pad', '1.3.0']]);
+    });
+    it('finds the line declaring a dependency', () => {
+        expect(lineOfDependency('{\n  "dependencies": {\n    "request": "^2"\n  }\n}', 'request')).toBe(3);
+        expect(lineOfDependency('{}', 'request')).toBeUndefined();
+    });
+});

package/dist/gates/runner.d.ts

@@ -1,5 +1,5 @@
 import { Gate } from './base.js';
-import { Config, Report, DeepOptions } from '../types/index.js';
+import { Failure, Config, Report, DeepOptions } from '../types/index.js';
 export declare class GateRunner {
     private config;
     private gates;
@@ -13,3 +13,9 @@ export declare class GateRunner {
         onProgress?: (msg: string) => void;
     }): Promise<Report>;
 }
+/**
+ * One finding per rule, file and line. The title names the rule: a learned rule shares its gate
+ * id with the built-in rules, and keying on the gate alone dropped it whenever a built-in rule
+ * fired on the same line.
+ */
+export declare function dedupeFailures(failures: Failure[]): Failure[];

package/dist/gates/runner.js

@@ -29,6 +29,8 @@ import { SideEffectAnalysisGate } from './side-effect-analysis/index.js';
 import { StyleDriftGate } from './style-drift.js';
 import { SemanticBugsGate } from './semantic-bugs.js';
 import { LogicDriftGate } from './logic-drift.js';
+import { UnindexedReadsGate } from './unindexed-reads/index.js';
+import { DeprecatedDependenciesGate } from './deprecated-dependencies.js';
 import { execa } from 'execa';
 import { Logger } from '../utils/logger.js';
 import { FileSystemCache } from '../services/filesystem-cache.js';
@@ -101,6 +103,12 @@ export class GateRunner {
         if (this.config.gates.phantom_apis?.enabled !== false) {
             this.gates.push(new PhantomApisGate(this.config.gates.phantom_apis));
         }
+        if (this.config.gates.deprecated_dependencies?.enabled) {
+            this.gates.push(new DeprecatedDependenciesGate(this.config.gates.deprecated_dependencies));
+        }
+        if (this.config.gates.unindexed_reads?.enabled) {
+            this.gates.push(new UnindexedReadsGate(this.config.gates.unindexed_reads));
+        }
         if (this.config.gates.deprecated_apis?.enabled !== false) {
             this.gates.push(new DeprecatedApisGate(this.config.gates.deprecated_apis));
         }
@@ -212,17 +220,8 @@ export class GateRunner {
         }
         const status = failures.length > 0 ? 'FAIL' : 'PASS';
         // Severity-weighted scoring with per-gate cap and deduplication
-        // Step 1: Deduplicate — same file + line + gate should not stack
-        const deduped = [];
-        const seen = new Set();
-        for (const f of failures) {
-            const key = `${f.id}:${(f.files || []).join(',')}:${f.line || 0}`;
-            if (!seen.has(key)) {
-                seen.add(key);
-                deduped.push(f);
-            }
-        }
-        // Replace failures array with deduplicated version
+        // Step 1: Deduplicate — the same rule on the same file and line should not stack
+        const deduped = dedupeFailures(failures);
         failures.length = 0;
         failures.push(...deduped);
         // Step 2: Calculate per-gate deductions with dynamic cap
@@ -340,3 +339,18 @@ export class GateRunner {
         return report;
     }
 }
+/**
+ * One finding per rule, file and line. The title names the rule: a learned rule shares its gate
+ * id with the built-in rules, and keying on the gate alone dropped it whenever a built-in rule
+ * fired on the same line.
+ */
+export function dedupeFailures(failures) {
+    const seen = new Set();
+    return failures.filter(f => {
+        const key = `${f.id}:${f.title}:${(f.files || []).join(',')}:${f.line || 0}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/gates/security-patterns-data.js

@@ -128,7 +128,8 @@ export const VULNERABILITY_PATTERNS = [
     // ReDoS — Denial of Service via regex (OWASP #7)
     {
         type: 'redos',
-        regex: /new RegExp\s*\([^)]*(?:req\.|params|query|body|input|user)/g,
+        // Request data, or a first argument that is exactly an input name; not any argument that merely contains "user" or "query".
+        regex: /new RegExp\s*\(\s*(?:[^)]*\b(?:req|request)\.(?:query|params|body)\b|(?:userInput|input|searchTerm|search|query|term|keyword|pattern)\s*[,)])/g,
         severity: 'high',
         description: 'Dynamic regex from user input — potential ReDoS',
         cwe: 'CWE-1333',

package/dist/gates/security-patterns-owasp.test.js

@@ -25,6 +25,21 @@ describe('SecurityPatternsGate — OWASP extended patterns', () => {
             const vulns = await checkSecurityPatterns(filePath);
             expect(vulns.some(v => v.type === 'redos')).toBe(true);
         });
+        it('detects request data and input-named arguments, not constants that contain those words', async () => {
+            const tainted = path.join(testDir, 'tainted.ts');
+            fs.writeFileSync(tainted, `
+                const a = new RegExp(\`^\${req.body.term}$\`);
+                const b = new RegExp(input, 'i');
+            `);
+            expect((await checkSecurityPatterns(tainted)).filter(v => v.type === 'redos')).toHaveLength(2);
+            const constant = path.join(testDir, 'constant.ts');
+            fs.writeFileSync(constant, `
+                const user = String.raw\`auth\\.uid\\(\\)\`;
+                const left = new RegExp(String.raw\`^\${user} ?= ?(\${NAME})$\`, 'i');
+                const byQuery = new RegExp(queryPrefix + '$');
+            `);
+            expect((await checkSecurityPatterns(constant)).filter(v => v.type === 'redos')).toEqual([]);
+        });
         it('should detect nested quantifiers', async () => {
             const filePath = path.join(testDir, 'regex.ts');
             fs.writeFileSync(filePath, `

package/dist/gates/semantic-bugs.js

@@ -42,7 +42,7 @@ export class SemanticBugsGate extends Gate {
         return wanted?.length ? [...ALL_RULES, ...learned].filter(rule => wanted.includes(rule.id)) : [...BUILT_IN_RULES, ...learned];
     }
     toFailure(finding) {
-        const failure = this.createFailure(`${finding.message}\n${finding.evidence.map(e => `  at ${e}`).join('\n')}`, [finding.file], finding.hint, `[${finding.rule}] ${finding.message.split('. ')[0]}`.slice(0, 120), finding.line, undefined, finding.severity);
+        const failure = this.createFailure(`${finding.message}\n${finding.evidence.map(e => `  at ${e}`).join('\n')}`, [finding.file], finding.hint, `[${finding.rule}] ${finding.message.split('. ')[0]}`.slice(0, 120), finding.line, finding.endLine, finding.severity);
         const category = finding.rule.startsWith(LEARNED_PREFIX) ? 'learned-rule' : finding.rule;
         return { ...failure, provenance: finding.provenance, source: 'ast', category, verified: true, confidence: 1 };
     }

package/dist/gates/unindexed-reads/coverage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether any index on a table can serve a read.
+ *
+ * The claim is deliberately narrow, so it can be proved from the schema
+ * alone: no index starts with a column the read compares to a value or sorts
+ * by first, or every index that does is partial with a WHERE the read's
+ * filters do not satisfy. `IS NOT NULL` alone is not a comparison: it narrows
+ * nothing on a mostly filled column. When a predicate cannot be read, the
+ * index counts as serving, so doubt keeps the gate silent.
+ */
+import type { IndexDef } from './schema.js';
+import type { Read } from './queries.js';
+/** Columns the read narrows by value or orders by first (lower case). */
+export declare function seekColumns(read: Read): Set<string>;
+export declare function servesRead(index: IndexDef, read: Read): boolean;

package/dist/gates/unindexed-reads/coverage.js

@@ -0,0 +1,24 @@
+/** Columns the read narrows by value or orders by first (lower case). */
+export function seekColumns(read) {
+    const columns = new Set(read.filters.filter(f => f.op !== 'notnull').map(f => f.column.toLowerCase()));
+    if (read.orderBy)
+        columns.add(read.orderBy.toLowerCase());
+    return columns;
+}
+export function servesRead(index, read) {
+    if (index.leading === null || !seekColumns(read).has(index.leading.toLowerCase()))
+        return false;
+    return index.predicate.every(term => satisfied(term, read.filters));
+}
+/** Whether the read's filters satisfy one partial-index term; an unreadable term is assumed satisfied. */
+function satisfied(term, filters) {
+    if (term.kind === 'unknown')
+        return true;
+    const own = filters.filter(f => f.column.toLowerCase() === term.column.toLowerCase());
+    if (term.kind === 'null')
+        return own.some(f => f.op === 'isnull');
+    // Every operator but IS NULL is strict: a row it matches has a value, so it implies IS NOT NULL.
+    if (term.kind === 'notnull')
+        return own.some(f => f.op !== 'isnull');
+    return own.some(f => f.op === 'eq' && (f.value === undefined || f.value === term.value)) || own.some(f => f.op === 'in' || f.op === 'match');
+}

package/dist/gates/unindexed-reads/index.d.ts

@@ -0,0 +1,20 @@
+import { Gate, type GateContext } from '../base.js';
+import type { Failure } from '../../types/index.js';
+import { type Schema } from './schema.js';
+import { type Read } from './queries.js';
+export interface UnindexedReadsConfig {
+    enabled?: boolean;
+    /** Globs for migration .sql files; each directory is replayed as its own database. */
+    migrations?: string[];
+}
+export declare class UnindexedReadsGate extends Gate {
+    private config;
+    constructor(config?: UnindexedReadsConfig);
+    run(context: GateContext): Promise<Failure[]>;
+    private finding;
+}
+/**
+ * The columns the read narrows by (its own and the table's policy filters) when
+ * no migration set can serve it; undefined when one can, or when that is not provable.
+ */
+export declare function unservedColumns(read: Read, schemas: Schema[]): string[] | undefined;

package/dist/gates/unindexed-reads/index.js

@@ -0,0 +1,98 @@
+/**
+ * Unindexed read: a supabase-js read whose table, as the repository's own
+ * migrations define it, has no index that can serve it (coverage.ts).
+ *
+ * Advisory and off by default. It speaks only when the claim is provable:
+ * the read is fully literal, its table is created in the migrations, and no
+ * DDL touching that table is beyond what schema.ts models. A small table
+ * read without an index is fine; dismiss the finding for it.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { Gate } from '../base.js';
+import { FileScanner } from '../../utils/scanner.js';
+import { Logger } from '../../utils/logger.js';
+import { policyFilters, replayMigrations } from './schema.js';
+import { findReads } from './queries.js';
+import { seekColumns, servesRead } from './coverage.js';
+const DEFAULT_MIGRATIONS = ['**/migrations/**/*.sql'];
+const SOURCE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const SKIP = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/*.test.*', '**/*.spec.*', '**/__tests__/**', '**/*.d.ts'];
+export class UnindexedReadsGate extends Gate {
+    config;
+    constructor(config = {}) {
+        super('unindexed-reads', 'Unindexed read');
+        this.config = config;
+    }
+    async run(context) {
+        if (!this.config.enabled)
+            return [];
+        const schemas = await loadSchemas(context.cwd, this.config.migrations?.length ? this.config.migrations : DEFAULT_MIGRATIONS, context.ignore ?? []);
+        if (schemas.length === 0)
+            return [];
+        const files = (await FileScanner.findFiles({ cwd: context.cwd, patterns: context.patterns, ignore: [...(context.ignore ?? []), ...SKIP] }))
+            .filter(file => SOURCE.test(file));
+        Logger.info(`Unindexed reads: ${files.length} files against ${schemas.length} migration set(s)`);
+        const failures = [];
+        for (const file of files) {
+            const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
+            if (!content.includes('.from('))
+                continue;
+            for (const read of findReads(file, content)) {
+                const columns = unservedColumns(read, schemas);
+                if (columns)
+                    failures.push(this.finding(file, read, columns));
+            }
+        }
+        return failures;
+    }
+    finding(file, read, columns) {
+        const list = columns.map(c => `\`${c}\``).join(', ');
+        return this.createFailure(`No index on \`${read.table}\` starts with a column this read compares to a value or sorts by first, including any its row-level policy adds (${list}), and none of its partial indexes match the read's filters, so Postgres cannot seek to these rows.`, [file], `Add an index in a new migration that leads with the most selective of ${list}, in the read's sort order. If the table stays small, dismiss this finding.`, undefined, read.line, undefined, 'medium');
+    }
+}
+/**
+ * The columns the read narrows by (its own and the table's policy filters) when
+ * no migration set can serve it; undefined when one can, or when that is not provable.
+ */
+export function unservedColumns(read, schemas) {
+    if (read.uncertain || seekColumns(read).size === 0)
+        return undefined;
+    const tables = schemas.map(schema => schema.get(read.table)).filter(table => table !== undefined);
+    if (tables.length === 0 || tables.some(table => table.uncertain || policyFilters(table).unknown))
+        return undefined;
+    const columns = new Set();
+    for (const table of tables) {
+        const filtered = withPolicyFilters(read, policyFilters(table).columns);
+        if (table.indexes.some(index => servesRead(index, filtered)))
+            return undefined;
+        for (const column of seekColumns(filtered))
+            columns.add(column);
+    }
+    return [...columns];
+}
+/** The read as Postgres runs it for a signed-in user: the policy's columns are compared too. */
+function withPolicyFilters(read, columns) {
+    return { ...read, filters: [...read.filters, ...columns.map(column => ({ column, op: 'eq', value: undefined }))] };
+}
+/** One schema per migrations directory, replayed in filename order. */
+async function loadSchemas(cwd, globs, ignore) {
+    const files = await FileScanner.findFiles({ cwd, patterns: globs, ignore });
+    const byDirectory = new Map();
+    for (const file of files) {
+        const directory = migrationsRoot(file);
+        byDirectory.set(directory, [...(byDirectory.get(directory) ?? []), file]);
+    }
+    const schemas = [];
+    for (const group of byDirectory.values()) {
+        const sql = await Promise.all(group.sort().map(file => fs.readFile(path.join(cwd, file), 'utf-8')));
+        schemas.push(replayMigrations(sql));
+    }
+    return schemas;
+}
+/** The directory a migration belongs to: up to and including its `migrations` segment, else its own folder. */
+function migrationsRoot(file) {
+    const parts = file.split('/');
+    const at = parts.lastIndexOf('migrations');
+    return at >= 0 ? parts.slice(0, at + 1).join('/') : path.posix.dirname(file);
+}

package/dist/gates/unindexed-reads/queries.d.ts

@@ -0,0 +1,17 @@
+export type Filter = {
+    column: string;
+    op: 'eq';
+    value: string | undefined;
+} | {
+    column: string;
+    op: 'in' | 'range' | 'isnull' | 'notnull' | 'match';
+};
+export interface Read {
+    table: string;
+    line: number;
+    filters: Filter[];
+    /** First `.order()` column: the only one an index can return rows in. */
+    orderBy?: string;
+    uncertain: boolean;
+}
+export declare function findReads(fileName: string, content: string): Read[];