@rigour-labs/core 5.4.0 → 5.5.0

package/dist/context/cache-engine.d.ts

@@ -68,6 +68,31 @@ export declare function setComponentCache(componentName: string, commitSha: stri
 export declare function normalizeQuery(query: string): string;
 export declare function getSemanticQueryCache(query: string, commitSha: string, cwd?: string): Promise<SemanticQueryEntry | null>;
 export declare function setSemanticQueryCache(query: string, commitSha: string, entry: SemanticQueryEntry, cwd?: string): Promise<void>;
+/** Jaccard similarity of normalized query tokens — used for quality-safe partial reuse. */
+export declare function queryTokenOverlap(a: string, b: string): number;
+/**
+ * Distinctive tokens (len >= 5) must mostly agree — blocks "task service" ≈ "payment service".
+ */
+export declare function distinctiveTokenAgreement(a: string, b: string): number;
+export interface RelatedSemanticHit {
+    entry: SemanticQueryEntry;
+    overlap: number;
+    sourceQuery: string;
+}
+/**
+ * Quality-safe partial semantic reuse: same commit only.
+ * Requires high Jaccard (>= 0.75) AND distinctive-token agreement (>= 0.67).
+ * Never crosses commits — avoids stale scopes after code moves.
+ * File existence is re-validated by the caller before serving.
+ */
+export declare function findRelatedSemanticQueryCache(query: string, commitSha: string, cwd?: string, minOverlap?: number, minDistinctive?: number): Promise<RelatedSemanticHit | null>;
+/**
+ * Drop cached scopes that point at files no longer on disk (quality guard).
+ */
+export declare function filterExistingEditScope(editScope: string[], cwd: string): Promise<{
+    valid: string[];
+    missing: string[];
+}>;
 /**
  * Layer 4: Task Checkpoint Cache
  */

package/dist/context/cache-engine.js

@@ -8,7 +8,9 @@
  * 4. Task checkpoint cache (Subagent handoff packets)
  */
 import { createHash } from 'crypto';
-import { setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric } from '../storage/index.js';
+import fs from 'fs-extra';
+import path from 'path';
+import { setContextCacheRecord, getContextCacheRecord, listContextCacheRecords, recordCheckpointMetric } from '../storage/index.js';
 /**
  * Generate SHA-256 content hash.
  */
@@ -114,6 +116,82 @@ export async function setSemanticQueryCache(query, commitSha, entry, cwd) {
         payloadTokens,
     }, cwd);
 }
+function queryTokenSet(query) {
+    return new Set(normalizeQuery(query).split(' ').filter((t) => t.length > 1));
+}
+/** Jaccard similarity of normalized query tokens — used for quality-safe partial reuse. */
+export function queryTokenOverlap(a, b) {
+    const left = queryTokenSet(a);
+    const right = queryTokenSet(b);
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of left) {
+        if (right.has(t))
+            inter++;
+    }
+    const union = left.size + right.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Distinctive tokens (len >= 5) must mostly agree — blocks "task service" ≈ "payment service".
+ */
+export function distinctiveTokenAgreement(a, b) {
+    const left = [...queryTokenSet(a)].filter((t) => t.length >= 5);
+    const right = new Set([...queryTokenSet(b)].filter((t) => t.length >= 5));
+    if (left.length === 0 || right.size === 0)
+        return 0;
+    const hits = left.filter((t) => right.has(t)).length;
+    return hits / Math.max(left.length, right.size);
+}
+/**
+ * Quality-safe partial semantic reuse: same commit only.
+ * Requires high Jaccard (>= 0.75) AND distinctive-token agreement (>= 0.67).
+ * Never crosses commits — avoids stale scopes after code moves.
+ * File existence is re-validated by the caller before serving.
+ */
+export async function findRelatedSemanticQueryCache(query, commitSha, cwd, minOverlap = 0.75, minDistinctive = 0.67) {
+    const records = await listContextCacheRecords({ cacheType: 'semantic', commitSha, limit: 80 }, cwd);
+    let best = null;
+    for (const record of records) {
+        try {
+            const entry = JSON.parse(record.payloadJson);
+            const sourceQuery = entry.query || '';
+            const overlap = queryTokenOverlap(query, sourceQuery);
+            const distinctive = distinctiveTokenAgreement(query, sourceQuery);
+            if (overlap < minOverlap || distinctive < minDistinctive)
+                continue;
+            if (normalizeQuery(query) === normalizeQuery(sourceQuery))
+                continue; // exact path uses getSemanticQueryCache
+            if (!best || overlap > best.overlap) {
+                best = { entry, overlap, sourceQuery };
+            }
+        }
+        catch {
+            // skip bad payloads
+        }
+    }
+    return best;
+}
+/**
+ * Drop cached scopes that point at files no longer on disk (quality guard).
+ */
+export async function filterExistingEditScope(editScope, cwd) {
+    const valid = [];
+    const missing = [];
+    for (const file of editScope) {
+        try {
+            if (await fs.pathExists(path.join(cwd, file)))
+                valid.push(file);
+            else
+                missing.push(file);
+        }
+        catch {
+            missing.push(file);
+        }
+    }
+    return { valid, missing };
+}
 /**
  * Layer 4: Task Checkpoint Cache
  */

package/dist/context/cache-engine.test.js

@@ -8,7 +8,7 @@ vi.mock('./db.js', () => ({
     DB_PATH: '/tmp/rigour-test.db',
     RIGOUR_DIR: '/tmp/.rigour',
 }));
-import { getStaticCache, setStaticCache, getComponentCache, setComponentCache, getSemanticQueryCache, setSemanticQueryCache, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
+import { getStaticCache, setStaticCache, getComponentCache, setComponentCache, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, queryTokenOverlap, distinctiveTokenAgreement, filterExistingEditScope, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
 describe('4-Layer Context Cache Engine', () => {
     const testCwd = path.join(os.tmpdir(), `rigour-cache-test-${Date.now()}`);
     beforeEach(async () => {
@@ -89,6 +89,42 @@ describe('4-Layer Context Cache Engine', () => {
         expect(retrieved?.taskId).toBe('CTP-142');
         expect(retrieved?.decisions).toContain('Added priority field');
     });
+    it('Layer 3: finds related semantic queries at same commit for partial reuse', async () => {
+        expect(queryTokenOverlap('task priority persistence service', 'task priority persistence service layer')).toBeGreaterThan(0.7);
+        expect(distinctiveTokenAgreement('task service', 'payment service')).toBeLessThan(0.67);
+        await setSemanticQueryCache('task priority persistence service', 'commit-rel', {
+            query: 'task priority persistence service',
+            resolvedOwner: 'task-team',
+            editScope: ['services/task.ts'],
+            validationScope: ['npm test'],
+            evidence: ['related'],
+            commitSha: 'commit-rel',
+            confidence: 0.9,
+        }, testCwd);
+        const related = await findRelatedSemanticQueryCache('task priority persistence service layer', 'commit-rel', testCwd);
+        expect(related).not.toBeNull();
+        expect(related?.entry.editScope).toContain('services/task.ts');
+        // Same generic stem, different distinctive noun → reject
+        await setSemanticQueryCache('payment service billing', 'commit-rel', {
+            query: 'payment service billing',
+            resolvedOwner: 'pay',
+            editScope: ['services/pay.ts'],
+            validationScope: [],
+            evidence: [],
+            commitSha: 'commit-rel',
+            confidence: 0.9,
+        }, testCwd);
+        const crossDomain = await findRelatedSemanticQueryCache('task service billing', 'commit-rel', testCwd);
+        expect(crossDomain).toBeNull();
+        const otherCommit = await findRelatedSemanticQueryCache('task priority persistence service layer', 'commit-other', testCwd);
+        expect(otherCommit).toBeNull();
+    });
+    it('filters missing edit-scope files for quality', async () => {
+        await fs.writeFile(path.join(testCwd, 'alive.ts'), 'export const ok = 1;\n');
+        const result = await filterExistingEditScope(['alive.ts', 'gone.ts'], testCwd);
+        expect(result.valid).toEqual(['alive.ts']);
+        expect(result.missing).toEqual(['gone.ts']);
+    });
     it('Layer 1: invalidates static cache when file content changes', async () => {
         const originalContent = 'export function processTask() { return true; }';
         const entry = {

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export * from './utils/logger.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
-export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, updateCursorApiKey } from './settings.js';
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, isCursorApiKeyConfigured, getCursorApiKeyHint, updateCursorApiKey, removeCursorApiKey, } from './settings.js';
 export type { RigourSettings, ResolvedDeepOptions, CLIDeepOptions } from './settings.js';
 export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
 // Settings Module (Global user config at ~/.rigour/settings.json)
-export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, updateCursorApiKey } from './settings.js';
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, isCursorApiKeyConfigured, getCursorApiKeyHint, updateCursorApiKey, removeCursorApiKey, } from './settings.js';
 // Deep Analysis Pipeline (v4.0+)
 export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';

package/dist/settings.d.ts

@@ -106,10 +106,23 @@ export declare function updateProviderKey(provider: string, apiKey: string): voi
  */
 export declare function removeProviderKey(provider: string): void;
 /**
- * Get Cursor Admin API key from settings
+ * Get Cursor Admin API key — prefer env over file-stored secret.
+ * Env: RIGOUR_CURSOR_API_KEY or CURSOR_ADMIN_API_KEY
  */
 export declare function getCursorApiKey(): string | undefined;
 /**
- * Update Cursor Admin API key in settings
+ * Whether a Cursor vendor adapter key is available (env or file).
+ */
+export declare function isCursorApiKeyConfigured(): boolean;
+/**
+ * Last-4 hint for UI status — never return the full key.
+ */
+export declare function getCursorApiKeyHint(): string | undefined;
+/**
+ * Persist Cursor Admin API key to settings (optional; prefer env in production).
  */
 export declare function updateCursorApiKey(apiKey: string): void;
+/**
+ * Remove file-stored Cursor Admin API key (env vars are untouched).
+ */
+export declare function removeCursorApiKey(): void;

package/dist/settings.js

@@ -45,10 +45,22 @@ export function saveSettings(settings) {
     const settingsPath = getSettingsPath();
     const settingsDir = path.dirname(settingsPath);
     try {
-        // Ensure directory exists
+        // Ensure directory exists with owner-only access
         fs.ensureDirSync(settingsDir);
+        try {
+            fs.chmodSync(settingsDir, 0o700);
+        }
+        catch {
+            // ignore chmod failures on platforms that do not support it
+        }
         // Write with pretty formatting (2-space indent)
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        try {
+            fs.chmodSync(settingsPath, 0o600);
+        }
+        catch {
+            // ignore chmod failures on platforms that do not support it
+        }
         Logger.debug(`Settings saved to ${settingsPath}`);
     }
     catch (error) {
@@ -185,20 +197,58 @@ export function removeProviderKey(provider) {
     }
 }
 /**
- * Get Cursor Admin API key from settings
+ * Get Cursor Admin API key — prefer env over file-stored secret.
+ * Env: RIGOUR_CURSOR_API_KEY or CURSOR_ADMIN_API_KEY
  */
 export function getCursorApiKey() {
+    const fromEnv = process.env.RIGOUR_CURSOR_API_KEY?.trim() ||
+        process.env.CURSOR_ADMIN_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
     const settings = loadSettings();
-    return settings.cursor?.apiKey;
+    const fromFile = settings.cursor?.apiKey?.trim();
+    return fromFile || undefined;
+}
+/**
+ * Whether a Cursor vendor adapter key is available (env or file).
+ */
+export function isCursorApiKeyConfigured() {
+    return Boolean(getCursorApiKey());
 }
 /**
- * Update Cursor Admin API key in settings
+ * Last-4 hint for UI status — never return the full key.
+ */
+export function getCursorApiKeyHint() {
+    const key = getCursorApiKey();
+    if (!key || key.length < 4)
+        return undefined;
+    return `••••${key.slice(-4)}`;
+}
+/**
+ * Persist Cursor Admin API key to settings (optional; prefer env in production).
  */
 export function updateCursorApiKey(apiKey) {
+    const trimmed = apiKey.trim();
+    if (!trimmed || trimmed.length > 512) {
+        throw new Error('Invalid Cursor Admin API key');
+    }
     const settings = loadSettings();
     if (!settings.cursor) {
         settings.cursor = {};
     }
-    settings.cursor.apiKey = apiKey;
+    settings.cursor.apiKey = trimmed;
     saveSettings(settings);
 }
+/**
+ * Remove file-stored Cursor Admin API key (env vars are untouched).
+ */
+export function removeCursorApiKey() {
+    const settings = loadSettings();
+    if (settings.cursor?.apiKey) {
+        delete settings.cursor.apiKey;
+        if (Object.keys(settings.cursor).length === 0) {
+            delete settings.cursor;
+        }
+        saveSettings(settings);
+    }
+}

package/dist/storage/context-telemetry.d.ts

@@ -62,6 +62,14 @@ export declare function recordModelUsage(usage: ModelUsage, cwd?: string): Promi
  * Insert or update cache entry.
  */
 export declare function setContextCacheRecord(record: ContextCacheRecord, cwd?: string): Promise<void>;
+/**
+ * List cache records by type (and optional commit). Does not increment hit counts.
+ */
+export declare function listContextCacheRecords(opts: {
+    cacheType?: ContextCacheRecord['cacheType'];
+    commitSha?: string;
+    limit?: number;
+}, cwd?: string): Promise<ContextCacheRecord[]>;
 /**
  * Fetch cached context record by cache key. Increments hit count.
  */

package/dist/storage/context-telemetry.js

@@ -112,6 +112,67 @@ export async function setContextCacheRecord(record, cwd) {
     cacheData[record.cacheKey] = { ...record, createdAt: timestamp };
     await fs.writeJson(fallbackPath, cacheData, { spaces: 2 });
 }
+/**
+ * List cache records by type (and optional commit). Does not increment hit counts.
+ */
+export async function listContextCacheRecords(opts, cwd) {
+    const limit = opts.limit ?? 50;
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                const clauses = [];
+                const params = [];
+                if (opts.cacheType) {
+                    clauses.push('cache_type = ?');
+                    params.push(opts.cacheType);
+                }
+                if (opts.commitSha) {
+                    clauses.push('commit_sha = ?');
+                    params.push(opts.commitSha);
+                }
+                const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+                const rows = await db.all(`SELECT * FROM context_cache ${where} ORDER BY COALESCE(last_hit_at, created_at) DESC LIMIT ?`, ...params, limit);
+                await db.close();
+                return (rows || []).map((row) => ({
+                    cacheKey: row.cache_key,
+                    cacheType: row.cache_type,
+                    repo: row.repo,
+                    branch: row.branch,
+                    commitSha: row.commit_sha,
+                    dependencyFingerprint: row.dependency_fingerprint,
+                    payloadJson: row.payload_json,
+                    payloadTokens: row.payload_tokens,
+                    hitCount: row.hit_count || 0,
+                    createdAt: row.created_at,
+                    lastHitAt: row.last_hit_at,
+                }));
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackPath = path.join(getFallbackDir(cwd), 'context-cache.json');
+    if (!(await fs.pathExists(fallbackPath)))
+        return [];
+    try {
+        const cacheData = await fs.readJson(fallbackPath);
+        return Object.values(cacheData)
+            .filter((entry) => {
+            if (opts.cacheType && entry.cacheType !== opts.cacheType)
+                return false;
+            if (opts.commitSha && entry.commitSha !== opts.commitSha)
+                return false;
+            return true;
+        })
+            .sort((a, b) => (b.lastHitAt || b.createdAt || 0) - (a.lastHitAt || a.createdAt || 0))
+            .slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Fetch cached context record by cache key. Increments hit count.
  */

package/dist/storage/index.d.ts

@@ -9,5 +9,5 @@ export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.
 export { reinforcePattern, decayPatterns, getStrongPatterns, getPatterns, getHardRules } from './patterns.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './local-memory.js';
 export type { ProjectStats } from './local-memory.js';
-export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';
+export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, listContextCacheRecords, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';
 export type { ContextEvent, ModelUsage, ContextCacheRecord, CheckpointMetric } from './context-telemetry.js';

package/dist/storage/index.js

@@ -7,4 +7,4 @@ export { insertScan, getRecentScans, getScoreTrendFromDB, getTopIssues } from '.
 export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.js';
 export { reinforcePattern, decayPatterns, getStrongPatterns, getPatterns, getHardRules } from './patterns.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './local-memory.js';
-export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';
+export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, listContextCacheRecords, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -66,11 +66,11 @@
     "@xenova/transformers": "^2.17.2",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "5.4.0",
-    "@rigour-labs/brain-darwin-x64": "5.4.0",
-    "@rigour-labs/brain-linux-arm64": "5.4.0",
-    "@rigour-labs/brain-linux-x64": "5.4.0",
-    "@rigour-labs/brain-win-x64": "5.4.0"
+    "@rigour-labs/brain-darwin-arm64": "5.5.0",
+    "@rigour-labs/brain-darwin-x64": "5.5.0",
+    "@rigour-labs/brain-linux-x64": "5.5.0",
+    "@rigour-labs/brain-win-x64": "5.5.0",
+    "@rigour-labs/brain-linux-arm64": "5.5.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",