@rigour-labs/core 5.2.9 → 5.3.1

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

@@ -0,0 +1,75 @@
+/**
+ * 4-Layer Context Caching Engine for Rigour
+ *
+ * Implements:
+ * 1. Content-addressed static cache (AST, exports, imports, dependencies, patterns by content SHA)
+ * 2. Component context cache (Compact dossiers per component scope)
+ * 3. Semantic-query cache (Intent embeddings & edit/validation scopes)
+ * 4. Task checkpoint cache (Subagent handoff packets)
+ */
+export interface StaticCacheEntry {
+    astSummary?: any;
+    exports?: string[];
+    imports?: string[];
+    dependencies?: string[];
+    ownership?: string;
+    schemas?: any[];
+    endpoints?: string[];
+    eventRelationships?: any[];
+    styleFingerprint?: string;
+    rigourPatterns?: string[];
+}
+export interface ComponentDossier {
+    component: string;
+    responsibility: string;
+    canonicalFiles: string[];
+    contracts: string[];
+    directConsumers: string[];
+    validationCommands: string[];
+}
+export interface SemanticQueryEntry {
+    query: string;
+    intentEmbedding?: number[];
+    resolvedOwner: string;
+    editScope: string[];
+    validationScope: string[];
+    evidence: string[];
+    commitSha: string;
+    confidence: number;
+}
+export interface TaskCheckpointPacket {
+    taskId: string;
+    agentId: string;
+    phase: string;
+    component: string;
+    changedFiles: string[];
+    decisions: string[];
+    validation: string[];
+    remainingWork: string[];
+    risks: string[];
+}
+/**
+ * Generate SHA-256 content hash.
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Layer 1: Content-Addressed Static Cache
+ */
+export declare function getStaticCache(repo: string, branch: string, filePath: string, fileContent: string, cwd?: string): Promise<StaticCacheEntry | null>;
+export declare function setStaticCache(repo: string, branch: string, filePath: string, fileContent: string, entry: StaticCacheEntry, cwd?: string): Promise<void>;
+/**
+ * Layer 2: Component Context Cache
+ */
+export declare function getComponentCache(componentName: string, commitSha: string, profileVersion?: string, cwd?: string): Promise<ComponentDossier | null>;
+export declare function setComponentCache(componentName: string, commitSha: string, dossier: ComponentDossier, dependencyFingerprint: string, profileVersion?: string, cwd?: string): Promise<void>;
+/**
+ * Layer 3: Semantic-Query Cache
+ */
+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>;
+/**
+ * Layer 4: Task Checkpoint Cache
+ */
+export declare function setTaskCheckpointCache(packet: TaskCheckpointPacket, rawStateTokens: number, cwd?: string): Promise<void>;
+export declare function getTaskCheckpointCache(taskId: string, agentId: string, phase: string, cwd?: string): Promise<TaskCheckpointPacket | null>;

package/dist/context/cache-engine.js

@@ -0,0 +1,155 @@
+/**
+ * 4-Layer Context Caching Engine for Rigour
+ *
+ * Implements:
+ * 1. Content-addressed static cache (AST, exports, imports, dependencies, patterns by content SHA)
+ * 2. Component context cache (Compact dossiers per component scope)
+ * 3. Semantic-query cache (Intent embeddings & edit/validation scopes)
+ * 4. Task checkpoint cache (Subagent handoff packets)
+ */
+import { createHash } from 'crypto';
+import { setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric } from '../storage/index.js';
+/**
+ * Generate SHA-256 content hash.
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Layer 1: Content-Addressed Static Cache
+ */
+export async function getStaticCache(repo, branch, filePath, fileContent, cwd) {
+    const contentSha = hashContent(fileContent);
+    const cacheKey = `static:${repo}:${branch}:${filePath}:${contentSha}:v1`;
+    const record = await getContextCacheRecord(cacheKey, cwd);
+    if (!record)
+        return null;
+    try {
+        return JSON.parse(record.payloadJson);
+    }
+    catch {
+        return null;
+    }
+}
+export async function setStaticCache(repo, branch, filePath, fileContent, entry, cwd) {
+    const contentSha = hashContent(fileContent);
+    const cacheKey = `static:${repo}:${branch}:${filePath}:${contentSha}:v1`;
+    const payloadJson = JSON.stringify(entry);
+    const payloadTokens = Math.ceil(payloadJson.length / 4);
+    await setContextCacheRecord({
+        cacheKey,
+        cacheType: 'static',
+        repo,
+        branch,
+        commitSha: contentSha,
+        dependencyFingerprint: `sha-${contentSha}`,
+        payloadJson,
+        payloadTokens,
+    }, cwd);
+}
+/**
+ * Layer 2: Component Context Cache
+ */
+export async function getComponentCache(componentName, commitSha, profileVersion = '3', cwd) {
+    const cacheKey = `component:${componentName}:${commitSha}:v${profileVersion}`;
+    const record = await getContextCacheRecord(cacheKey, cwd);
+    if (!record)
+        return null;
+    try {
+        return JSON.parse(record.payloadJson);
+    }
+    catch {
+        return null;
+    }
+}
+export async function setComponentCache(componentName, commitSha, dossier, dependencyFingerprint, profileVersion = '3', cwd) {
+    const cacheKey = `component:${componentName}:${commitSha}:v${profileVersion}`;
+    const payloadJson = JSON.stringify(dossier);
+    const payloadTokens = Math.ceil(payloadJson.length / 4);
+    await setContextCacheRecord({
+        cacheKey,
+        cacheType: 'component',
+        repo: dossier.component,
+        branch: 'main',
+        commitSha,
+        dependencyFingerprint,
+        payloadJson,
+        payloadTokens,
+    }, cwd);
+}
+/**
+ * Layer 3: Semantic-Query Cache
+ */
+export function normalizeQuery(query) {
+    return query.toLowerCase().trim().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ');
+}
+export async function getSemanticQueryCache(query, commitSha, cwd) {
+    const normalized = normalizeQuery(query);
+    const queryHash = hashContent(normalized);
+    const cacheKey = `semantic:${queryHash}:${commitSha}`;
+    const record = await getContextCacheRecord(cacheKey, cwd);
+    if (!record)
+        return null;
+    try {
+        return JSON.parse(record.payloadJson);
+    }
+    catch {
+        return null;
+    }
+}
+export async function setSemanticQueryCache(query, commitSha, entry, cwd) {
+    const normalized = normalizeQuery(query);
+    const queryHash = hashContent(normalized);
+    const cacheKey = `semantic:${queryHash}:${commitSha}`;
+    const payloadJson = JSON.stringify(entry);
+    const payloadTokens = Math.ceil(payloadJson.length / 4);
+    await setContextCacheRecord({
+        cacheKey,
+        cacheType: 'semantic',
+        repo: 'workspace',
+        branch: 'main',
+        commitSha,
+        dependencyFingerprint: `query-${queryHash}`,
+        payloadJson,
+        payloadTokens,
+    }, cwd);
+}
+/**
+ * Layer 4: Task Checkpoint Cache
+ */
+export async function setTaskCheckpointCache(packet, rawStateTokens, cwd) {
+    const cacheKey = `checkpoint:${packet.taskId}:${packet.agentId}:${packet.phase}`;
+    const payloadJson = JSON.stringify(packet);
+    const checkpointTokens = Math.ceil(payloadJson.length / 4);
+    const replayTokensAvoided = Math.max(0, rawStateTokens - checkpointTokens);
+    await setContextCacheRecord({
+        cacheKey,
+        cacheType: 'checkpoint',
+        repo: packet.taskId,
+        branch: packet.phase,
+        commitSha: packet.agentId,
+        dependencyFingerprint: `cp-${packet.taskId}`,
+        payloadJson,
+        payloadTokens: checkpointTokens,
+    }, cwd);
+    await recordCheckpointMetric({
+        checkpointId: cacheKey,
+        taskId: packet.taskId,
+        agentId: packet.agentId,
+        rawStateTokens,
+        checkpointTokens,
+        replayTokensAvoided,
+    }, cwd);
+}
+export async function getTaskCheckpointCache(taskId, agentId, phase, cwd) {
+    const cacheKey = `checkpoint:${taskId}:${agentId}:${phase}`;
+    const record = await getContextCacheRecord(cacheKey, cwd);
+    if (!record)
+        return null;
+    try {
+        return JSON.parse(record.payloadJson);
+    }
+    catch {
+        return null;
+    }
+}

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

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

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

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+vi.mock('./db.js', () => ({
+    isSQLiteAvailable: () => false,
+    openDatabase: async () => null,
+    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';
+describe('4-Layer Context Cache Engine', () => {
+    const testCwd = path.join(os.tmpdir(), `rigour-cache-test-${Date.now()}`);
+    beforeEach(async () => {
+        await fs.ensureDir(testCwd);
+    });
+    it('should calculate consistent SHA-256 hashes', () => {
+        const hash1 = hashContent('const x = 1;');
+        const hash2 = hashContent('const x = 1;');
+        const hash3 = hashContent('const x = 2;');
+        expect(hash1).toBe(hash2);
+        expect(hash1).not.toBe(hash3);
+        expect(hash1.length).toBe(16);
+    });
+    it('should normalize intent queries correctly', () => {
+        expect(normalizeQuery('  Add priority to task!! ')).toBe('add priority to task');
+        expect(normalizeQuery('Task SHOULD Support Priority.')).toBe('task should support priority');
+    });
+    it('Layer 1: should store and retrieve content-addressed static cache', async () => {
+        const fileContent = 'export function processTask() { return true; }';
+        const entry = {
+            exports: ['processTask'],
+            imports: [],
+            ownership: 'platform-team',
+            endpoints: ['/api/task']
+        };
+        await setStaticCache('rigour-repo', 'main', 'services/task.ts', fileContent, entry, testCwd);
+        const cached = await getStaticCache('rigour-repo', 'main', 'services/task.ts', fileContent, testCwd);
+        expect(cached).not.toBeNull();
+        expect(cached?.exports).toEqual(['processTask']);
+        expect(cached?.ownership).toBe('platform-team');
+    });
+    it('Layer 2: should store and retrieve component context dossier', async () => {
+        const dossier = {
+            component: 'services/task',
+            responsibility: 'Task lifecycle and persistence',
+            canonicalFiles: ['services/task.ts'],
+            contracts: ['TaskContract'],
+            directConsumers: ['controllers/task'],
+            validationCommands: ['npm test']
+        };
+        await setComponentCache('services/task', 'abc123commit', dossier, 'dep-fingerprint-v1', '3', testCwd);
+        const retrieved = await getComponentCache('services/task', 'abc123commit', '3', testCwd);
+        expect(retrieved).not.toBeNull();
+        expect(retrieved?.responsibility).toBe('Task lifecycle and persistence');
+        expect(retrieved?.canonicalFiles).toContain('services/task.ts');
+    });
+    it('Layer 3: should store and retrieve semantic query scope', async () => {
+        const entry = {
+            query: 'task priority persistence',
+            resolvedOwner: 'task-team',
+            editScope: ['services/task.ts'],
+            validationScope: ['npm test'],
+            evidence: ['AST match'],
+            commitSha: 'commit-99',
+            confidence: 0.95
+        };
+        await setSemanticQueryCache('add priority to task', 'commit-99', entry, testCwd);
+        const retrieved = await getSemanticQueryCache('add priority to task', 'commit-99', testCwd);
+        expect(retrieved).not.toBeNull();
+        expect(retrieved?.resolvedOwner).toBe('task-team');
+        expect(retrieved?.editScope).toContain('services/task.ts');
+    });
+    it('Layer 4: should store and retrieve subagent task checkpoint packet', async () => {
+        const packet = {
+            taskId: 'CTP-142',
+            agentId: 'CTP-142-task',
+            phase: 'implementation',
+            component: 'services/task',
+            changedFiles: ['services/task.ts'],
+            decisions: ['Added priority field'],
+            validation: ['npm test passed'],
+            remainingWork: ['Add integration test'],
+            risks: ['Migration needed']
+        };
+        await setTaskCheckpointCache(packet, 126000, testCwd);
+        const retrieved = await getTaskCheckpointCache('CTP-142', 'CTP-142-task', 'implementation', testCwd);
+        expect(retrieved).not.toBeNull();
+        expect(retrieved?.taskId).toBe('CTP-142');
+        expect(retrieved?.decisions).toContain('Added priority field');
+    });
+    it('Layer 1: invalidates static cache when file content changes', async () => {
+        const originalContent = 'export function processTask() { return true; }';
+        const entry = {
+            exports: ['processTask'],
+            imports: [],
+            ownership: 'platform-team',
+            endpoints: ['/api/task'],
+        };
+        await setStaticCache('rigour-repo', 'main', 'services/task.ts', originalContent, entry, testCwd);
+        const cached = await getStaticCache('rigour-repo', 'main', 'services/task.ts', originalContent, testCwd);
+        expect(cached?.exports).toEqual(['processTask']);
+        const changedContent = 'export function processTask() { return false; }';
+        const stale = await getStaticCache('rigour-repo', 'main', 'services/task.ts', changedContent, testCwd);
+        expect(stale).toBeNull();
+    });
+});

package/dist/context/context-session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-project context session tracking.
+ * Persists file reads and token estimates to .rigour/context-session.json.
+ */
+export interface FileReadRecord {
+    path: string;
+    contentHash: string;
+    tokens: number;
+    readAt: number;
+}
+export interface ContextSession {
+    sessionId: string;
+    createdAt: number;
+    lastUpdatedAt: number;
+    fileReads: Record<string, FileReadRecord>;
+    totalTokens: number;
+}
+/**
+ * Load existing session or create a new one for the project.
+ */
+export declare function getOrCreateSession(cwd: string): Promise<ContextSession>;
+/**
+ * Record a file read in the current session, deduplicating by content hash.
+ */
+export declare function recordFileRead(cwd: string, filePath: string, content: string): Promise<FileReadRecord>;

package/dist/context/context-session.js

@@ -0,0 +1,78 @@
+/**
+ * Per-project context session tracking.
+ * Persists file reads and token estimates to .rigour/context-session.json.
+ */
+import { randomUUID } from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+import { hashContent } from './cache-engine.js';
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+function getSessionPath(cwd) {
+    return path.join(cwd, '.rigour', 'context-session.json');
+}
+async function loadSession(cwd) {
+    const sessionPath = getSessionPath(cwd);
+    if (!await fs.pathExists(sessionPath))
+        return null;
+    try {
+        return await fs.readJson(sessionPath);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveSession(cwd, session) {
+    const sessionPath = getSessionPath(cwd);
+    await fs.ensureDir(path.dirname(sessionPath));
+    await fs.writeJson(sessionPath, session, { spaces: 2 });
+}
+/**
+ * Load existing session or create a new one for the project.
+ */
+export async function getOrCreateSession(cwd) {
+    const resolved = path.resolve(cwd);
+    const existing = await loadSession(resolved);
+    if (existing)
+        return existing;
+    const session = {
+        sessionId: `sess-${randomUUID()}`,
+        createdAt: Date.now(),
+        lastUpdatedAt: Date.now(),
+        fileReads: {},
+        totalTokens: 0,
+    };
+    await saveSession(resolved, session);
+    return session;
+}
+/**
+ * Record a file read in the current session, deduplicating by content hash.
+ */
+export async function recordFileRead(cwd, filePath, content) {
+    const resolved = path.resolve(cwd);
+    const session = await getOrCreateSession(resolved);
+    const contentHash = hashContent(content);
+    const tokens = estimateTokens(content);
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const existing = session.fileReads[normalizedPath];
+    if (existing?.contentHash === contentHash) {
+        return existing;
+    }
+    const record = {
+        path: normalizedPath,
+        contentHash,
+        tokens,
+        readAt: Date.now(),
+    };
+    if (existing) {
+        session.totalTokens -= existing.tokens;
+    }
+    session.fileReads[normalizedPath] = record;
+    session.totalTokens += tokens;
+    session.lastUpdatedAt = Date.now();
+    await saveSession(resolved, session);
+    return record;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Bridge between Pattern Index and 4-Layer Context Cache.
+ * Syncs indexed patterns into static cache entries and component dossiers.
+ */
+import type { PatternIndex } from '../pattern-index/types.js';
+export interface IndexHealthReport {
+    indexPath: string;
+    exists: boolean;
+    lastUpdated?: string;
+    ageMs?: number;
+    isStale: boolean;
+    staleThresholdMs: number;
+    totalPatterns?: number;
+    totalFiles?: number;
+    message: string;
+}
+/**
+ * Sync pattern index entries into static cache and component dossier layers.
+ */
+export declare function syncIndexToContextCache(cwd: string, index: PatternIndex): Promise<number>;
+/**
+ * Check patterns.json freshness relative to the project directory.
+ */
+export declare function getIndexHealth(cwd: string, staleThresholdMs?: number): Promise<IndexHealthReport>;

package/dist/context/index-bridge.js

@@ -0,0 +1,114 @@
+/**
+ * Bridge between Pattern Index and 4-Layer Context Cache.
+ * Syncs indexed patterns into static cache entries and component dossiers.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { setStaticCache, setComponentCache, hashContent } from './cache-engine.js';
+function getIndexPath(cwd) {
+    return path.join(cwd, '.rigour', 'patterns.json');
+}
+const DEFAULT_STALE_MS = 24 * 60 * 60 * 1000;
+function groupByComponent(patterns) {
+    const groups = new Map();
+    for (const p of patterns) {
+        const key = p.type === 'component' ? p.name : p.category || 'uncategorized';
+        const list = groups.get(key) ?? [];
+        list.push(p);
+        groups.set(key, list);
+    }
+    return groups;
+}
+function buildDossier(component, patterns) {
+    const canonicalFiles = [...new Set(patterns.map(p => p.file))];
+    const contracts = patterns
+        .filter(p => p.signature)
+        .map(p => p.signature)
+        .slice(0, 20);
+    const descriptions = patterns.map(p => p.description).filter(Boolean);
+    const responsibility = descriptions[0] || `Indexed ${patterns.length} patterns for ${component}`;
+    return {
+        component,
+        responsibility,
+        canonicalFiles,
+        contracts,
+        directConsumers: [],
+        validationCommands: [],
+    };
+}
+/**
+ * Sync pattern index entries into static cache and component dossier layers.
+ */
+export async function syncIndexToContextCache(cwd, index) {
+    const resolved = path.resolve(cwd);
+    const repo = path.basename(index.rootDir || resolved);
+    const branch = 'main';
+    const commitSha = hashContent(index.lastUpdated);
+    let synced = 0;
+    for (const file of index.files) {
+        const filePatterns = index.patterns.filter(p => p.file === file.path);
+        if (filePatterns.length === 0)
+            continue;
+        const payload = {
+            rigourPatterns: filePatterns.map(p => `${p.type}:${p.name}`),
+            exports: filePatterns.filter(p => p.exported).map(p => p.name),
+        };
+        const fileContent = JSON.stringify(payload);
+        await setStaticCache(repo, branch, file.path, fileContent, payload, resolved);
+        synced++;
+    }
+    const componentGroups = groupByComponent(index.patterns);
+    for (const [component, patterns] of componentGroups) {
+        const dossier = buildDossier(component, patterns);
+        const fingerprint = hashContent(JSON.stringify(patterns.map(p => p.id)));
+        await setComponentCache(component, commitSha, dossier, fingerprint, '3', resolved);
+        synced++;
+    }
+    return synced;
+}
+/**
+ * Check patterns.json freshness relative to the project directory.
+ */
+export async function getIndexHealth(cwd, staleThresholdMs = DEFAULT_STALE_MS) {
+    const resolved = path.resolve(cwd);
+    const indexPath = getIndexPath(resolved);
+    if (!await fs.pathExists(indexPath)) {
+        return {
+            indexPath,
+            exists: false,
+            isStale: true,
+            staleThresholdMs,
+            message: 'patterns.json not found — run pattern index build',
+        };
+    }
+    const stat = await fs.stat(indexPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    let index = null;
+    try {
+        index = await fs.readJson(indexPath);
+    }
+    catch {
+        return {
+            indexPath,
+            exists: true,
+            ageMs,
+            isStale: true,
+            staleThresholdMs,
+            message: 'patterns.json is malformed',
+        };
+    }
+    const isStale = ageMs > staleThresholdMs;
+    return {
+        indexPath,
+        exists: true,
+        lastUpdated: index.lastUpdated,
+        ageMs,
+        isStale,
+        staleThresholdMs,
+        totalPatterns: index.stats?.totalPatterns,
+        totalFiles: index.stats?.totalFiles,
+        message: isStale
+            ? `Index is stale (${Math.round(ageMs / 3600000)}h old)`
+            : 'Index is fresh',
+    };
+}

package/dist/hooks/dlp-confidence.d.ts

@@ -0,0 +1,16 @@
+export type DLPDecision = 'block' | 'warn' | 'allow';
+interface DLPDetectionInput {
+    type: string;
+    match: string;
+    position?: {
+        start: number;
+        end: number;
+    };
+}
+interface DLPClassification {
+    confidence: number;
+    decision: DLPDecision;
+    reason_codes: string[];
+}
+export declare function classifyDLPDetection(detection: DLPDetectionInput, input: string): DLPClassification;
+export {};