corpus-core 0.1.0

package/dist/memory.js

@@ -0,0 +1,261 @@
+/**
+ * Corpus Immune Memory -- Backboard.io Integration
+ *
+ * Stores behavioral baselines and health snapshots persistently across sessions.
+ * The longer you use Corpus, the smarter it gets. Memory powers:
+ * - "This function was flagged 3 times before"
+ * - Cross-session pattern recognition
+ * - Behavioral drift detection over time
+ *
+ * Falls back to local .corpus/memory.json when Backboard is unavailable.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+// ── Backboard.io Client ──────────────────────────────────────────────────────
+const BACKBOARD_BASE_URL = 'https://app.backboard.io/api';
+class BackboardClient {
+    apiKey;
+    assistantId = null;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async request(method, endpoint, options) {
+        const url = new URL(`${BACKBOARD_BASE_URL}/${endpoint.replace(/^\//, '')}`);
+        if (options?.params) {
+            for (const [key, val] of Object.entries(options.params)) {
+                url.searchParams.set(key, String(val));
+            }
+        }
+        const headers = {
+            'X-API-Key': this.apiKey,
+            'User-Agent': 'corpus/1.0',
+        };
+        let body;
+        if (options?.json) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(options.json);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30000);
+        try {
+            const res = await fetch(url.toString(), {
+                method,
+                headers,
+                body,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '<no body>');
+                throw new Error(`Backboard API ${res.status}: ${text}`);
+            }
+            // DELETE responses may have no body
+            if (res.status === 204 || res.headers.get('content-length') === '0') {
+                return undefined;
+            }
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async ensureAssistant(name) {
+        if (this.assistantId)
+            return this.assistantId;
+        try {
+            // Try to find existing assistant
+            const list = await this.request('GET', '/assistants', { params: { skip: 0, limit: 100 } });
+            const existing = (Array.isArray(list) ? list : []).find((a) => a.name === name);
+            if (existing) {
+                this.assistantId = existing.assistant_id;
+                return existing.assistant_id;
+            }
+            // Create new
+            const created = await this.request('POST', '/assistants', {
+                json: {
+                    name,
+                    description: 'Corpus immune memory for codebase health tracking',
+                    system_prompt: 'You are the memory layer for Corpus, tracking codebase health patterns.',
+                },
+            });
+            this.assistantId = created.assistant_id;
+            return created.assistant_id;
+        }
+        catch (e) {
+            throw new Error(`Failed to initialize Backboard assistant: ${e}`);
+        }
+    }
+    async addMemory(assistantId, content, metadata) {
+        return this.request('POST', `/assistants/${assistantId}/memories`, {
+            json: { content, metadata },
+        });
+    }
+    async getMemories(assistantId) {
+        return this.request('GET', `/assistants/${assistantId}/memories`);
+    }
+    async deleteMemory(assistantId, memoryId) {
+        await this.request('DELETE', `/assistants/${assistantId}/memories/${memoryId}`);
+    }
+}
+// ── Local Memory Fallback ────────────────────────────────────────────────────
+function getLocalMemoryPath(projectRoot) {
+    return path.join(projectRoot, '.corpus', 'memory.json');
+}
+function loadLocalMemory(projectRoot) {
+    const memPath = getLocalMemoryPath(projectRoot);
+    if (existsSync(memPath)) {
+        try {
+            return JSON.parse(readFileSync(memPath, 'utf-8'));
+        }
+        catch {
+            // Corrupted, start fresh
+        }
+    }
+    return {
+        entries: [],
+        stats: {
+            totalEntries: 0,
+            totalViolations: 0,
+            totalFixes: 0,
+            sessionsTracked: 0,
+            lastUpdated: new Date().toISOString(),
+        },
+    };
+}
+function saveLocalMemory(projectRoot, memory) {
+    const corpusDir = path.join(projectRoot, '.corpus');
+    if (!existsSync(corpusDir))
+        mkdirSync(corpusDir, { recursive: true });
+    writeFileSync(getLocalMemoryPath(projectRoot), JSON.stringify(memory, null, 2));
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+let backboardClient = null;
+let backboardAssistantId = null;
+function getBackboardClient() {
+    if (backboardClient)
+        return backboardClient;
+    const apiKey = process.env.BACKBOARD_API_KEY;
+    if (!apiKey)
+        return null;
+    backboardClient = new BackboardClient(apiKey);
+    return backboardClient;
+}
+/**
+ * Record a memory entry (violation, fix, baseline, pattern).
+ * Stores in Backboard.io if available, always stores locally.
+ */
+export async function recordMemory(projectRoot, entry) {
+    const memory = loadLocalMemory(projectRoot);
+    const fullEntry = {
+        ...entry,
+        id: `mem_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        timestamp: new Date().toISOString(),
+    };
+    memory.entries.push(fullEntry);
+    if (entry.type === 'violation')
+        memory.stats.totalViolations++;
+    if (entry.type === 'fix')
+        memory.stats.totalFixes++;
+    memory.stats.totalEntries++;
+    memory.stats.lastUpdated = fullEntry.timestamp;
+    saveLocalMemory(projectRoot, memory);
+    // Also store in Backboard.io if available
+    const client = getBackboardClient();
+    if (client) {
+        try {
+            if (!backboardAssistantId) {
+                const projectName = path.basename(projectRoot);
+                backboardAssistantId = await client.ensureAssistant(`corpus-${projectName}`);
+            }
+            await client.addMemory(backboardAssistantId, fullEntry.content, {
+                type: fullEntry.type,
+                file: fullEntry.file,
+                functionName: fullEntry.functionName,
+                ...fullEntry.metadata,
+            });
+        }
+        catch {
+            // Backboard unavailable, local memory is the fallback
+        }
+    }
+}
+/**
+ * Get the flag count for a specific function across all sessions.
+ * "This function was flagged 3 times before."
+ */
+export function getFlagCount(projectRoot, file, functionName) {
+    const memory = loadLocalMemory(projectRoot);
+    return memory.entries.filter(e => e.type === 'violation' && e.file === file && e.functionName === functionName).length;
+}
+/**
+ * Get recent violations for the dashboard.
+ */
+export function getRecentViolations(projectRoot, limit = 20) {
+    const memory = loadLocalMemory(projectRoot);
+    return memory.entries
+        .filter(e => e.type === 'violation')
+        .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())
+        .slice(0, limit);
+}
+/**
+ * Get immune memory stats for display.
+ */
+export function getMemoryStats(projectRoot) {
+    const memory = loadLocalMemory(projectRoot);
+    return memory.stats;
+}
+/**
+ * Get all memories (for syncing to Backboard.io or display).
+ */
+export function getAllMemories(projectRoot) {
+    return loadLocalMemory(projectRoot);
+}
+/**
+ * Get memories stored in Backboard.io for this project.
+ */
+export async function getBackboardMemories(projectRoot) {
+    const client = getBackboardClient();
+    if (!client)
+        return null;
+    const projectName = path.basename(projectRoot);
+    try {
+        const assistantId = await client.ensureAssistant(`corpus-${projectName}`);
+        return await client.getMemories(assistantId);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sync local memory to Backboard.io (for initial setup or recovery).
+ */
+export async function syncToBackboard(projectRoot) {
+    const client = getBackboardClient();
+    if (!client)
+        return { synced: 0, errors: 0 };
+    const memory = loadLocalMemory(projectRoot);
+    const projectName = path.basename(projectRoot);
+    try {
+        const assistantId = await client.ensureAssistant(`corpus-${projectName}`);
+        let synced = 0;
+        let errors = 0;
+        for (const entry of memory.entries) {
+            try {
+                await client.addMemory(assistantId, entry.content, {
+                    type: entry.type,
+                    file: entry.file,
+                    functionName: entry.functionName,
+                    originalTimestamp: entry.timestamp,
+                    ...entry.metadata,
+                });
+                synced++;
+            }
+            catch {
+                errors++;
+            }
+        }
+        return { synced, errors };
+    }
+    catch {
+        return { synced: 0, errors: memory.entries.length };
+    }
+}

package/dist/pattern-learner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Corpus Pattern Learner
+ *
+ * Analyzes findings across multiple repos to learn which patterns
+ * are real issues vs false positives. Builds a statistical model
+ * that evolves as more repos are scanned.
+ *
+ * This is the "learning" part of the immune system.
+ */
+export interface PatternSignature {
+    type: string;
+    totalOccurrences: number;
+    inTestFiles: number;
+    inProductionFiles: number;
+    inBuildTools: number;
+    falsePositiveRate: number;
+    severity: 'CRITICAL' | 'WARNING' | 'INFO';
+    adjustedSeverity: 'CRITICAL' | 'WARNING' | 'INFO' | 'SUPPRESSED';
+    description: string;
+    examples: {
+        repo: string;
+        file: string;
+    }[];
+    repoCount: number;
+    repoPrevalence: number;
+    contextBreakdown: Record<string, number>;
+    coOccursWith: Array<{
+        pattern: string;
+        correlation: number;
+        combinedRisk: 'ELEVATED' | 'NORMAL';
+    }>;
+    linkedCVEs: string[];
+    categoryWeights: Record<string, number>;
+}
+export interface LearnedPatterns {
+    version: 1;
+    learnedFrom: number;
+    totalFindings: number;
+    patterns: PatternSignature[];
+    lastUpdated: string;
+    knownPackages: string[];
+    repoCategories: Record<string, string>;
+}
+/**
+ * Classify the semantic context of a file based on its path and content.
+ */
+export declare function classifyContext(filepath: string, content: string): string;
+/**
+ * Learn patterns from a set of findings across multiple repos.
+ * Updates the learned patterns file.
+ */
+export declare function learnFromFindings(projectRoot: string, findings: Array<{
+    repo: string;
+    type: string;
+    severity: string;
+    file: string;
+    message: string;
+}>): LearnedPatterns;
+/**
+ * Get learned patterns for display.
+ */
+export declare function getLearnedPatterns(projectRoot: string): LearnedPatterns | null;
+export declare function shouldSuppress(projectRoot: string, type: string, file: string, content?: string): {
+    suppress: boolean;
+    reason?: string;
+};
+/**
+ * Get intelligence verdict for a specific pattern type.
+ */
+export declare function getPatternIntelligence(projectRoot: string, type: string): {
+    verdict: 'CRITICAL' | 'WARNING' | 'INFO' | 'SUPPRESSED';
+    confidence: number;
+    reasoning: string;
+} | null;
+/**
+ * Register known legitimate npm packages to reduce false positives.
+ */
+export declare function addKnownPackages(projectRoot: string, packages: string[]): void;
+/**
+ * Categorize a repo for context-weighted pattern analysis.
+ */
+export declare function categorizeRepo(projectRoot: string, repo: string, category: string): void;