@a13xu/lucid 1.0.0 → 1.4.0

package/build/guardian/validator.js

@@ -0,0 +1,332 @@
+import { readFileSync } from "fs";
+import { extname } from "path";
+const SEVERITY_ORDER = {
+    critical: 0, high: 1, medium: 2, low: 3, info: 4,
+};
+const SEVERITY_ICON = {
+    critical: "🔴", high: "🟠", medium: "🟡", low: "🔵", info: "ℹ️",
+};
+export function formatIssue(issue) {
+    const icon = SEVERITY_ICON[issue.severity];
+    let s = `${icon} [${issue.driftId}] ${issue.file}:${issue.line} — ${issue.message}`;
+    if (issue.suggestion)
+        s += `\n   💡 ${issue.suggestion}`;
+    if (issue.snippet)
+        s += `\n   📄 ${issue.snippet.trim().slice(0, 80)}`;
+    return s;
+}
+// ---------------------------------------------------------------------------
+// Language detection
+// ---------------------------------------------------------------------------
+const LANG_MAP = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".rs": "rust",
+    ".go": "go",
+};
+export function detectLanguage(filepath) {
+    return LANG_MAP[extname(filepath).toLowerCase()] ?? "generic";
+}
+// ---------------------------------------------------------------------------
+// Python analyzer (regex-based port of AST checks)
+// ---------------------------------------------------------------------------
+function analyzePython(filepath, lines) {
+    const issues = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        const trimmed = line.trim();
+        // Mutable default argument: def f(x=[], def f(x={})
+        if (/def\s+\w+\s*\(/.test(trimmed) && /=\s*[\[\{]/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "PY-MUT-DEFAULT",
+                message: "Mutable default argument in function definition",
+                suggestion: "Use None as default and create inside function body.",
+                snippet: trimmed,
+            });
+        }
+        // Bare except:
+        if (/^\s*except\s*:/.test(line)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "PY-BARE-EXCEPT",
+                message: "Bare `except:` catches everything including KeyboardInterrupt",
+                suggestion: "Use `except Exception:` or catch specific exceptions.",
+            });
+        }
+        // Silent except (except followed by pass on next line)
+        if (/^\s*except[\s:]/.test(line) && i + 1 < lines.length) {
+            const next = lines[i + 1].trim();
+            if (next === "pass") {
+                issues.push({
+                    file: filepath, line: num, severity: "critical",
+                    driftId: "DRIFT-002",
+                    message: "Exception silently swallowed with `pass`",
+                    suggestion: "Log the error, re-raise, or handle explicitly.",
+                });
+            }
+        }
+        // == None instead of is None
+        if (/==\s*None/.test(trimmed) && !trimmed.startsWith("#")) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "PY-IS-NONE",
+                message: "Using `== None` instead of `is None`",
+                suggestion: "Use `is None` for None checks (PEP 8).",
+                snippet: trimmed,
+            });
+        }
+        // != None instead of is not None
+        if (/!=\s*None/.test(trimmed) && !trimmed.startsWith("#")) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "PY-IS-NONE",
+                message: "Using `!= None` instead of `is not None`",
+                suggestion: "Use `is not None` for None checks (PEP 8).",
+                snippet: trimmed,
+            });
+        }
+        // f-string without interpolation
+        if (/f['"][^{'"]*['"]/.test(trimmed) && !trimmed.includes("{")) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "PY-FSTRING-EMPTY",
+                message: "f-string without any interpolation",
+                suggestion: "Remove the `f` prefix or add variables.",
+                snippet: trimmed,
+            });
+        }
+        // async def without await in body (heuristic: next non-empty line doesn't await)
+        if (/^\s*async\s+def\s+/.test(line)) {
+            // Collect the function body (next ~20 lines) and check for await
+            const body = lines.slice(i + 1, i + 20).join("\n");
+            if (!body.includes("await ") && !body.includes("async for") && !body.includes("async with")) {
+                issues.push({
+                    file: filepath, line: num, severity: "medium",
+                    driftId: "DRIFT-003",
+                    message: "async function may not use await — could be incorrectly async",
+                    suggestion: "Verify this function actually needs to be async.",
+                    snippet: trimmed,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// JavaScript / TypeScript analyzer
+// ---------------------------------------------------------------------------
+function analyzeJavaScript(filepath, lines) {
+    const issues = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        const trimmed = line.trim();
+        // Skip comments
+        if (trimmed.startsWith("//") || trimmed.startsWith("*"))
+            continue;
+        // == instead of === (but not !== or ===)
+        if (/[^!=><]={2}[^=]/.test(trimmed) && !/={3}/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "JS-STRICT-EQ",
+                message: "Using `==` instead of `===`",
+                suggestion: "Use strict equality `===` unless coercion is intentional.",
+                snippet: trimmed,
+            });
+        }
+        // console.log left in
+        if (/console\.log\s*\(/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "JS-CONSOLE",
+                message: "console.log() left in code",
+                suggestion: "Remove or replace with proper logging.",
+                snippet: trimmed,
+            });
+        }
+        // .then() without .catch() on same line
+        if (/\.then\s*\(/.test(trimmed) && !/\.catch\s*\(/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "JS-UNCAUGHT-PROMISE",
+                message: "`.then()` without `.catch()` — unhandled promise rejection",
+                suggestion: "Add `.catch()` or use try/catch with async/await.",
+                snippet: trimmed,
+            });
+        }
+        // .sort() without comparator
+        if (/\.sort\s*\(\s*\)/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "JS-SORT-DEFAULT",
+                message: "`.sort()` without comparator sorts as strings",
+                suggestion: "Use `.sort((a, b) => a - b)` for numeric sort.",
+                snippet: trimmed,
+            });
+        }
+        // any type in TypeScript
+        if (/:\s*any\b/.test(trimmed) || /as\s+any\b/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "TS-ANY",
+                message: "`any` type leaking through — disables type safety",
+                suggestion: "Use a specific type or `unknown` with type narrowing.",
+                snippet: trimmed,
+            });
+        }
+        // non-null assertion masking bugs
+        if (/\w!\.\w/.test(trimmed) || /\w!\[/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "TS-NON-NULL",
+                message: "Non-null assertion `!` — could crash if value is actually null",
+                suggestion: "Add explicit null check instead.",
+                snippet: trimmed,
+            });
+        }
+        // Early return with potential wrong value (heuristic)
+        if (/return\s+true\b/.test(trimmed) || /return\s+false\b/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "info",
+                driftId: "DRIFT-005",
+                message: "Boolean return — verify this is the correct value for this branch",
+                suggestion: "Logic inversions are the #1 LLM drift pattern. Double-check.",
+                snippet: trimmed,
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Generic analyzer (language-agnostic)
+// ---------------------------------------------------------------------------
+function analyzeGeneric(filepath, lines) {
+    const issues = [];
+    // TODO / FIXME / HACK markers
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        for (const marker of ["TODO", "FIXME", "HACK", "XXX", "BUG"]) {
+            if (line.toUpperCase().includes(marker) && /[/#*\-]/.test(line)) {
+                issues.push({
+                    file: filepath, line: num, severity: "info",
+                    driftId: "MARKER",
+                    message: `${marker} marker found`,
+                    snippet: line.trim(),
+                });
+            }
+        }
+    }
+    // Near-duplicate blocks (copy-paste drift detection)
+    const BLOCK_SIZE = 5;
+    const seen = new Map();
+    for (let i = 0; i <= lines.length - BLOCK_SIZE; i++) {
+        const block = lines.slice(i, i + BLOCK_SIZE).map((l) => l.trim()).filter(Boolean);
+        if (block.length < 3)
+            continue;
+        // Normalize: replace identifiers with placeholder
+        const sig = block.map((l) => l.replace(/\b[a-z_]\w*\b/g, "_")).join("|");
+        const prev = seen.get(sig);
+        if (prev !== undefined && i - prev > BLOCK_SIZE) {
+            issues.push({
+                file: filepath, line: i + 1, severity: "medium",
+                driftId: "DRIFT-007",
+                message: `Near-duplicate block (similar to line ${prev + 1})`,
+                suggestion: "Verify all variable names were updated correctly in the copy.",
+            });
+        }
+        else {
+            seen.set(sig, i);
+        }
+    }
+    // Magic numbers (2+ digit numbers not in common whitelist)
+    const MAGIC_WHITELIST = new Set([10, 16, 32, 64, 100, 128, 256, 512, 1000, 1024, 2048, 4096, 8080, 3000, 8000]);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (/^[/#*\-]/.test(trimmed))
+            continue;
+        for (const match of trimmed.matchAll(/(?<![.\w])(\d{2,})(?![.\w])/g)) {
+            const num = parseInt(match[1], 10);
+            if (!MAGIC_WHITELIST.has(num) && !/port|size|limit|max|min/i.test(trimmed)) {
+                issues.push({
+                    file: filepath, line: i + 1, severity: "low",
+                    driftId: "MAGIC-NUM",
+                    message: `Magic number \`${num}\` — consider a named constant`,
+                    snippet: trimmed,
+                });
+                break; // one per line is enough
+            }
+        }
+    }
+    return issues;
+}
+export function validateSource(filepath, source, lang) {
+    const language = lang ?? detectLanguage(filepath);
+    const lines = source.split("\n");
+    const issues = [];
+    if (language === "python") {
+        issues.push(...analyzePython(filepath, lines));
+    }
+    else if (language === "javascript" || language === "typescript") {
+        issues.push(...analyzeJavaScript(filepath, lines));
+    }
+    issues.push(...analyzeGeneric(filepath, lines));
+    issues.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    return issues;
+}
+export function validateFile(filepath) {
+    let source;
+    try {
+        source = readFileSync(filepath, { encoding: "utf-8" });
+    }
+    catch (err) {
+        return [{
+                file: filepath, line: 0, severity: "critical",
+                driftId: "IO-ERROR",
+                message: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+            }];
+    }
+    return validateSource(filepath, source);
+}
+export function formatReport(filepath, issues) {
+    const lines = [
+        "=".repeat(60),
+        "🛡️  LOGIC GUARDIAN — Validation Report",
+        "=".repeat(60),
+        `File: ${filepath}`,
+        `Issues: ${issues.length}`,
+        "",
+    ];
+    if (issues.length === 0) {
+        lines.push("✅ No issues detected. Proceed with confidence.");
+        lines.push("");
+        lines.push("⚠️  Automated checks catch ~40% of drift patterns.");
+        lines.push("   The manual checklist (Passes 1-5) catches the rest.");
+    }
+    else {
+        const bySeverity = (s) => issues.filter((i) => i.severity === s);
+        for (const sev of ["critical", "high", "medium", "low", "info"]) {
+            const group = bySeverity(sev);
+            if (group.length > 0) {
+                lines.push(`--- ${sev.toUpperCase()} (${group.length}) ---`);
+                for (const issue of group)
+                    lines.push(formatIssue(issue));
+                lines.push("");
+            }
+        }
+        const criticalCount = bySeverity("critical").length;
+        const highCount = bySeverity("high").length;
+        const passed = criticalCount === 0 && highCount === 0;
+        lines.push(passed
+            ? "✅ PASS — No critical or high severity issues."
+            : "❌ FAIL — Fix critical/high issues before proceeding.");
+    }
+    lines.push("=".repeat(60));
+    return lines.join("\n");
+}

package/build/index.js

@@ -10,6 +10,10 @@ import { recall, RecallSchema } from "./tools/recall.js";
 import { recallAll } from "./tools/recall-all.js";
 import { forget, ForgetSchema } from "./tools/forget.js";
 import { memoryStats } from "./tools/stats.js";
+import { handleValidateFile, ValidateFileSchema, handleCheckDrift, CheckDriftSchema, handleGetChecklist, } from "./tools/guardian.js";
+import { handleGrepCode, GrepCodeSchema } from "./tools/grep.js";
+import { handleInitProject, InitProjectSchema } from "./tools/init.js";
+import { handleSyncFile, SyncFileSchema, handleSyncProject, SyncProjectSchema, } from "./tools/sync.js";
 // ---------------------------------------------------------------------------
 // Init DB
 // ---------------------------------------------------------------------------
@@ -18,12 +22,13 @@ const stmts = prepareStatements(db);
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "lucid", version: "1.0.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "lucid", version: "1.1.0" }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
+        // ── Memory ──────────────────────────────────────────────────────────────
         {
             name: "remember",
             description: "Store a fact, decision, or observation about an entity in the knowledge graph.",
@@ -88,6 +93,104 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Get memory usage statistics.",
             inputSchema: { type: "object", properties: {} },
         },
+        // ── Init / Indexing ──────────────────────────────────────────────────────
+        {
+            name: "init_project",
+            description: "Scan and index a project directory into the knowledge graph. " +
+                "Reads CLAUDE.md (directives, conventions), package.json / pyproject.toml (dependencies, scripts), " +
+                "README.md (description), .mcp.json (MCP servers), logic-guardian.yaml (drift patterns), " +
+                "and source files (exported functions/classes). " +
+                "Call this once when starting work on a project to bootstrap memory with project context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    directory: {
+                        type: "string",
+                        description: "Absolute path to the project root. Defaults to current working directory.",
+                    },
+                },
+            },
+        },
+        {
+            name: "sync_file",
+            description: "Index or re-index a single source file after it was written or modified. " +
+                "Extracts exports, description, and open TODOs, then updates the knowledge graph. " +
+                "IMPORTANT: call this automatically after every Write or Edit tool call.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the modified file." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "sync_project",
+            description: "Re-index the entire project directory incrementally. " +
+                "Use this when multiple files have changed (e.g. after a refactor or git pull).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    directory: {
+                        type: "string",
+                        description: "Project root directory. Defaults to current working directory.",
+                    },
+                },
+            },
+        },
+        {
+            name: "grep_code",
+            description: "Search indexed source files using a regex pattern. " +
+                "Decompresses stored binary content and returns only matching lines with context. " +
+                "Token-efficient: returns ~20-50 tokens instead of full file contents. " +
+                "Useful for finding function calls, variable usages, import patterns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pattern: { type: "string", description: "Regex pattern to search for." },
+                    language: { type: "string", enum: ["python", "javascript", "typescript", "generic"], description: "Filter by language." },
+                    context: { type: "number", description: "Lines of context before/after each match (0-10, default 2)." },
+                },
+                required: ["pattern"],
+            },
+        },
+        // ── Logic Guardian ───────────────────────────────────────────────────────
+        {
+            name: "validate_file",
+            description: "Run Logic Guardian validation on a source file. Detects LLM drift patterns: " +
+                "logic inversions, null propagation, type confusion, copy-paste drift, silent exceptions, and more. " +
+                "Supports Python, JavaScript, TypeScript. Use after writing or modifying any code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the file to validate." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "check_drift",
+            description: "Analyze a code snippet for LLM drift patterns without saving to disk. " +
+                "Use this to validate code before writing it to a file.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "The code snippet to analyze." },
+                    language: {
+                        type: "string",
+                        enum: ["python", "javascript", "typescript", "generic"],
+                        description: "Programming language. Defaults to 'generic'.",
+                    },
+                },
+                required: ["code"],
+            },
+        },
+        {
+            name: "get_checklist",
+            description: "Get the full Logic Guardian validation checklist (5 passes). " +
+                "Call this before marking any implementation task as done.",
+            inputSchema: { type: "object", properties: {} },
+        },
     ],
 }));
 // ---------------------------------------------------------------------------
@@ -98,52 +201,59 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         let text;
         switch (name) {
-            case "remember": {
-                const input = RememberSchema.parse(args);
-                text = remember(stmts, input);
+            // Memory
+            case "remember":
+                text = remember(stmts, RememberSchema.parse(args));
                 break;
-            }
-            case "relate": {
-                const input = RelateSchema.parse(args);
-                text = relate(stmts, input);
+            case "relate":
+                text = relate(stmts, RelateSchema.parse(args));
                 break;
-            }
-            case "recall": {
-                const input = RecallSchema.parse(args);
-                text = recall(stmts, input);
+            case "recall":
+                text = recall(stmts, RecallSchema.parse(args));
                 break;
-            }
-            case "recall_all": {
+            case "recall_all":
                 text = recallAll(db, stmts);
                 break;
-            }
-            case "forget": {
-                const input = ForgetSchema.parse(args);
-                text = forget(stmts, input);
+            case "forget":
+                text = forget(stmts, ForgetSchema.parse(args));
                 break;
-            }
-            case "memory_stats": {
+            case "memory_stats":
                 text = memoryStats(db, stmts);
                 break;
-            }
+            // Init & Sync
+            case "init_project":
+                text = handleInitProject(stmts, InitProjectSchema.parse(args));
+                break;
+            case "sync_file":
+                text = handleSyncFile(stmts, SyncFileSchema.parse(args));
+                break;
+            case "sync_project":
+                text = handleSyncProject(stmts, SyncProjectSchema.parse(args));
+                break;
+            // Grep
+            case "grep_code":
+                text = handleGrepCode(stmts, GrepCodeSchema.parse(args));
+                break;
+            // Logic Guardian
+            case "validate_file":
+                text = handleValidateFile(ValidateFileSchema.parse(args));
+                break;
+            case "check_drift":
+                text = handleCheckDrift(CheckDriftSchema.parse(args));
+                break;
+            case "get_checklist":
+                text = handleGetChecklist();
+                break;
             default:
-                return {
-                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
-                    isError: true,
-                };
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
         return { content: [{ type: "text", text }] };
     }
     catch (err) {
         const message = err instanceof z.ZodError
             ? `Validation error: ${err.errors.map((e) => e.message).join(", ")}`
-            : err instanceof Error
-                ? err.message
-                : String(err);
-        return {
-            content: [{ type: "text", text: `Error: ${message}` }],
-            isError: true,
-        };
+            : err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
     }
 });
 // ---------------------------------------------------------------------------

package/build/indexer/file.d.ts

@@ -0,0 +1,15 @@
+import type { Statements } from "../database.js";
+export interface FileIndex {
+    module: string;
+    exports: string[];
+    description: string;
+    todos: string[];
+    language: string;
+}
+export declare function indexFile(filepath: string): FileIndex | null;
+export interface UpsertResult {
+    observations: string[];
+    stored: boolean;
+    savedBytes: number;
+}
+export declare function upsertFileIndex(index: FileIndex, source: string, stmts: Statements): UpsertResult;

package/build/indexer/file.js

@@ -0,0 +1,100 @@
+import { readFileSync } from "fs";
+import { extname } from "path";
+import { compress, sha256 } from "../store/content.js";
+function extractTS(source) {
+    const exports = [];
+    const todos = [];
+    // Exported symbols
+    for (const m of source.matchAll(/export\s+(?:async\s+)?(?:function|class|const|type|interface|enum)\s+(\w+)/g)) {
+        exports.push(m[1]);
+    }
+    // First JSDoc / block comment as description
+    const docMatch = source.match(/^\/\*\*([\s\S]*?)\*\//m) ?? source.match(/^\/\/(.*)/m);
+    const description = docMatch
+        ? docMatch[1].replace(/\s*\*\s*/g, " ").trim().slice(0, 200)
+        : "";
+    // TODOs
+    for (const m of source.matchAll(/\/\/\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports, description, todos };
+}
+function extractPython(source) {
+    const exports = [];
+    const todos = [];
+    // Public functions and classes
+    for (const m of source.matchAll(/^(?:def|class|async def)\s+(\w+)/gm)) {
+        if (!m[1].startsWith("_"))
+            exports.push(m[1]);
+    }
+    // Module docstring
+    const docMatch = source.match(/^["']{3}([\s\S]*?)["']{3}/m);
+    const description = docMatch ? docMatch[1].trim().slice(0, 200) : "";
+    // TODOs
+    for (const m of source.matchAll(/#\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports, description, todos };
+}
+function extractGeneric(source) {
+    const todos = [];
+    for (const m of source.matchAll(/(?:\/\/|#)\s*(TODO|FIXME|HACK)[:\s]+(.+)/gi)) {
+        todos.push(`${m[1]}: ${m[2].trim()}`);
+    }
+    return { exports: [], description: "", todos };
+}
+export function indexFile(filepath) {
+    let source;
+    try {
+        source = readFileSync(filepath, { encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+    const ext = extname(filepath).toLowerCase();
+    const module = filepath.replace(/\\/g, "/");
+    let extracted;
+    let language;
+    if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+        extracted = extractTS(source);
+        language = ext.includes("ts") ? "typescript" : "javascript";
+    }
+    else if (ext === ".py") {
+        extracted = extractPython(source);
+        language = "python";
+    }
+    else {
+        extracted = extractGeneric(source);
+        language = "generic";
+    }
+    return { module, language, ...extracted };
+}
+export function upsertFileIndex(index, source, stmts) {
+    const fileHash = sha256(source);
+    // Change detection — skip everything se hash-ul e identic
+    const existing = stmts.getFileByPath.get(index.module);
+    if (existing?.content_hash === fileHash) {
+        return { observations: [], stored: false, savedBytes: 0 };
+    }
+    // Comprimă și stochează conținutul binar
+    const blob = compress(source);
+    stmts.upsertFile.run(index.module, blob, fileHash, Buffer.byteLength(source, "utf-8"), blob.byteLength, index.language);
+    // Index structural în entities (compact, pentru recall)
+    const observations = [];
+    if (index.description)
+        observations.push(`description: ${index.description}`);
+    if (index.exports.length > 0)
+        observations.push(`exports: ${index.exports.join(", ")}`);
+    if (index.todos.length > 0)
+        observations.push(`TODOs: ${index.todos.join(" | ")}`);
+    observations.push(`language: ${index.language}`);
+    const entityRow = stmts.getEntityByName.get(index.module);
+    if (entityRow) {
+        stmts.updateEntity.run(JSON.stringify(observations), entityRow.id);
+    }
+    else {
+        stmts.insertEntity.run(index.module, "pattern", JSON.stringify(observations));
+    }
+    const savedBytes = Buffer.byteLength(source, "utf-8") - blob.byteLength;
+    return { observations, stored: true, savedBytes };
+}

package/build/indexer/project.d.ts

@@ -0,0 +1,8 @@
+import type { Statements } from "../database.js";
+export interface IndexResult {
+    entity: string;
+    type: string;
+    observations: number;
+    source: string;
+}
+export declare function indexProject(directory: string, stmts: Statements): IndexResult[];