@ophan/core 0.0.1

package/dist/index.js

@@ -0,0 +1,715 @@
+"use strict";
+// @ophan/core — Analysis engine
+//
+// Architecture:
+//   Content-addressed storage: Analysis is keyed by SHA256 of function source code,
+//   not by file path or branch. This makes analysis branch-agnostic, merge-friendly,
+//   and enables insert-only sync (no conflict resolution).
+//
+//   Two-table split:
+//   - function_analysis: (content_hash, analysis_type) → analysis JSON. Persistent cache,
+//     synced to cloud. Each function produces two rows: 'documentation' and 'security'.
+//   - file_functions: file_path → content_hash mappings. Ephemeral index, rebuilt on
+//     every scan, never synced. Maps the current checkout's files to their analysis entries.
+//
+//   Analysis types:
+//   Analysis is split into independent types ('documentation', 'security') stored as
+//   separate rows. This enables independent versioning, selective re-analysis, and
+//   extensibility (add new types without re-running existing analysis). See schemas.ts
+//   for the Zod schemas and docs/architecture/analysis-types.md for design rationale.
+//
+//   Language & entity_type columns:
+//   Both tables carry `language` and `entity_type` fields to support multi-language
+//   analysis (Python, Go, Java) and multi-entity analysis (classes, methods, modules).
+//   These are set at parse time from file extension and AST node kind respectively.
+//
+//   Parser abstraction:
+//   Function extraction is handled by language-specific parsers (see ./parsers/).
+//   Each parser implements the LanguageParser interface and registers itself by file extension.
+//   TypeScript/JavaScript uses the TS compiler API. Python uses Python's own ast module via
+//   subprocess. New languages are added by creating a parser file — the analysis pipeline,
+//   hashing, DB storage, and sync all work unchanged.
+//
+//   No tree-sitter, no custom LSP:
+//   Each language uses its own native tooling rather than a universal parser framework.
+//   The CLI + SQLite DB is the cross-IDE abstraction — any IDE plugin just reads .ophan/index.db.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSupportedExtensions = exports.computeHash = void 0;
+exports.ensureGitignore = ensureGitignore;
+exports.discoverFiles = discoverFiles;
+exports.initDb = initDb;
+exports.migrateToAnalysisTypes = migrateToAnalysisTypes;
+exports.analyzeFunctions = analyzeFunctions;
+exports.analyzeFiles = analyzeFiles;
+exports.analyzeRepository = analyzeRepository;
+exports.mergeAnalysisRows = mergeAnalysisRows;
+exports.getAnalysisForFile = getAnalysisForFile;
+exports.getAnalysisByHash = getAnalysisByHash;
+exports.gcAnalysis = gcAnalysis;
+exports.refreshFileIndex = refreshFileIndex;
+exports.findMissingHashes = findMissingHashes;
+exports.importAnalysis = importAnalysis;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const glob_1 = require("glob");
+const p_retry_1 = __importDefault(require("p-retry"));
+const parsers_1 = require("./parsers");
+// Re-export from shared so downstream consumers (CLI, etc.) can still import from @ophan/core
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "computeHash", { enumerable: true, get: function () { return shared_1.computeHash; } });
+var parsers_2 = require("./parsers");
+Object.defineProperty(exports, "getSupportedExtensions", { enumerable: true, get: function () { return parsers_2.getSupportedExtensions; } });
+__exportStar(require("./schemas"), exports);
+const schemas_1 = require("./schemas");
+/** Skip files larger than this — catches minified bundles, generated code, etc. */
+const MAX_FILE_SIZE_BYTES = 50 * 1024; // 50 KB
+/**
+ * Ensure .ophan/ is in .gitignore. Only acts in git repos.
+ * Creates .gitignore if the repo has .git/ but no .gitignore.
+ */
+function ensureGitignore(rootPath) {
+    const gitignorePath = path.join(rootPath, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, "utf-8");
+        if (!content.includes(".ophan")) {
+            fs.appendFileSync(gitignorePath, "\n# Ophan analysis cache\n.ophan/\n");
+        }
+    }
+    else if (fs.existsSync(path.join(rootPath, ".git"))) {
+        fs.writeFileSync(gitignorePath, "# Ophan analysis cache\n.ophan/\n");
+    }
+}
+const HARDCODED_IGNORES = [
+    "**/node_modules/**", "**/.ophan/**", "**/dist/**",
+    "**/__pycache__/**", "**/.venv/**", "**/venv/**", "**/env/**",
+    "**/.tox/**", "**/.eggs/**", "**/build/**",
+];
+/**
+ * Discover source files using git (respects .gitignore) with glob fallback.
+ * Returns absolute paths filtered to supported extensions.
+ */
+async function discoverFiles(rootPath) {
+    const exts = (0, parsers_1.getSupportedExtensions)(); // [".ts", ".tsx", ...]
+    const extSet = new Set(exts.map((e) => e.toLowerCase()));
+    try {
+        // git ls-files: tracked + untracked-but-not-ignored. Respects all .gitignore files.
+        const output = (0, child_process_1.execSync)("git ls-files --cached --others --exclude-standard", { cwd: rootPath, encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 });
+        const files = output
+            .split("\n")
+            .filter((f) => f.length > 0)
+            .filter((f) => extSet.has(path.extname(f).toLowerCase()))
+            .map((f) => path.resolve(rootPath, f));
+        // Still apply hardcoded ignores as safety net (e.g. checked-in node_modules)
+        const ignoreSegments = ["node_modules", ".ophan", "__pycache__", ".venv", "venv", ".tox", ".eggs"];
+        return files.filter((f) => !ignoreSegments.some((seg) => f.includes(`/${seg}/`) || f.includes(`\\${seg}\\`)));
+    }
+    catch {
+        // Not a git repo or git not available — fall back to glob
+        const globExts = exts.map((e) => e.slice(1));
+        return (0, glob_1.glob)(`**/*.{${globExts.join(",")}}`, {
+            cwd: rootPath,
+            ignore: HARDCODED_IGNORES,
+            absolute: true,
+        });
+    }
+}
+// ============ DATABASE ============
+function initDb(dbPath) {
+    const db = new better_sqlite3_1.default(dbPath);
+    // Check if we need the analysis_type migration
+    const columns = db.prepare("PRAGMA table_info(function_analysis)").all();
+    const hasAnalysisType = columns.some((c) => c.name === "analysis_type");
+    if (columns.length > 0 && !hasAnalysisType) {
+        // Existing DB without analysis_type — run migration
+        migrateToAnalysisTypes(db);
+    }
+    else if (columns.length === 0) {
+        // Fresh DB — create with new schema directly
+        createFreshSchema(db);
+    }
+    // else: already migrated, no action needed
+    // Ensure supporting tables exist
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS file_functions (
+      file_path TEXT NOT NULL,
+      function_name TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      file_mtime INTEGER NOT NULL,
+      language TEXT NOT NULL DEFAULT 'typescript',
+      entity_type TEXT NOT NULL DEFAULT 'function'
+    )
+  `);
+    // Migration: add columns to file_functions for existing databases
+    const ffColumns = db.prepare("PRAGMA table_info(file_functions)").all();
+    if (!ffColumns.some((c) => c.name === "language")) {
+        try {
+            db.exec("ALTER TABLE file_functions ADD COLUMN language TEXT NOT NULL DEFAULT 'typescript'");
+        }
+        catch (_) { }
+        try {
+            db.exec("ALTER TABLE file_functions ADD COLUMN entity_type TEXT NOT NULL DEFAULT 'function'");
+        }
+        catch (_) { }
+    }
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS function_gc (
+      content_hash TEXT NOT NULL,
+      analysis_type TEXT,
+      gc_at INTEGER NOT NULL,
+      synced_at INTEGER,
+      PRIMARY KEY (content_hash, analysis_type)
+    )
+  `);
+    // Migration: add analysis_type to function_gc for existing databases
+    const gcColumns = db.prepare("PRAGMA table_info(function_gc)").all();
+    if (!gcColumns.some((c) => c.name === "analysis_type")) {
+        try {
+            db.exec("ALTER TABLE function_gc ADD COLUMN analysis_type TEXT");
+        }
+        catch (_) { }
+        // Rebuild PK by recreating table
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS function_gc_v2 (
+        content_hash TEXT NOT NULL,
+        analysis_type TEXT,
+        gc_at INTEGER NOT NULL,
+        synced_at INTEGER,
+        PRIMARY KEY (content_hash, analysis_type)
+      )
+    `);
+        db.exec("INSERT OR IGNORE INTO function_gc_v2 SELECT content_hash, NULL, gc_at, synced_at FROM function_gc");
+        db.exec("DROP TABLE function_gc");
+        db.exec("ALTER TABLE function_gc_v2 RENAME TO function_gc");
+    }
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sync_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+    db.exec("CREATE INDEX IF NOT EXISTS idx_file_functions_path ON file_functions(file_path)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_file_functions_hash ON file_functions(content_hash)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_fa_hash ON function_analysis(content_hash)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_fa_type ON function_analysis(analysis_type)");
+    return db;
+}
+function createFreshSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS function_analysis (
+      content_hash TEXT NOT NULL,
+      analysis_type TEXT NOT NULL,
+      analysis JSON NOT NULL,
+      model_version TEXT NOT NULL,
+      schema_version INTEGER NOT NULL DEFAULT 1,
+      created_at INTEGER NOT NULL,
+      last_seen_at INTEGER NOT NULL,
+      language TEXT NOT NULL DEFAULT 'typescript',
+      entity_type TEXT NOT NULL DEFAULT 'function',
+      synced_at INTEGER,
+      PRIMARY KEY (content_hash, analysis_type)
+    )
+  `);
+}
+/**
+ * Migrate from single-blob function_analysis to split analysis types.
+ * Creates v2 table, splits each existing row into 'documentation' + 'security' rows,
+ * drops old table, renames. Sets synced_at = NULL to force full re-sync.
+ */
+function migrateToAnalysisTypes(db) {
+    db.exec("BEGIN TRANSACTION");
+    try {
+        db.exec(`
+      CREATE TABLE function_analysis_v2 (
+        content_hash TEXT NOT NULL,
+        analysis_type TEXT NOT NULL,
+        analysis JSON NOT NULL,
+        model_version TEXT NOT NULL,
+        schema_version INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        language TEXT NOT NULL DEFAULT 'typescript',
+        entity_type TEXT NOT NULL DEFAULT 'function',
+        synced_at INTEGER,
+        PRIMARY KEY (content_hash, analysis_type)
+      )
+    `);
+        // Split documentation fields
+        db.exec(`
+      INSERT OR IGNORE INTO function_analysis_v2
+        (content_hash, analysis_type, analysis, model_version, schema_version, created_at, last_seen_at, language, entity_type, synced_at)
+      SELECT
+        content_hash,
+        'documentation',
+        json_object(
+          'description', json_extract(analysis, '$.description'),
+          'params', json_extract(analysis, '$.params'),
+          'returns', json_extract(analysis, '$.returns')
+        ),
+        model_version,
+        1,
+        created_at,
+        last_seen_at,
+        COALESCE(language, 'typescript'),
+        COALESCE(entity_type, 'function'),
+        NULL
+      FROM function_analysis
+    `);
+        // Split security fields
+        db.exec(`
+      INSERT OR IGNORE INTO function_analysis_v2
+        (content_hash, analysis_type, analysis, model_version, schema_version, created_at, last_seen_at, language, entity_type, synced_at)
+      SELECT
+        content_hash,
+        'security',
+        json_object(
+          'dataTags', json_extract(analysis, '$.dataTags'),
+          'securityFlags', json_extract(analysis, '$.securityFlags')
+        ),
+        model_version,
+        1,
+        created_at,
+        last_seen_at,
+        COALESCE(language, 'typescript'),
+        COALESCE(entity_type, 'function'),
+        NULL
+      FROM function_analysis
+    `);
+        db.exec("DROP TABLE function_analysis");
+        db.exec("ALTER TABLE function_analysis_v2 RENAME TO function_analysis");
+        db.exec("COMMIT");
+    }
+    catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+    }
+}
+// ============ LLM ANALYSIS ============
+const anthropic = new sdk_1.default();
+async function analyzeFunctions(functions) {
+    if (functions.length === 0)
+        return [];
+    // Use the language from the first function in the batch (batches are always same-file)
+    const lang = functions[0].language || "typescript";
+    const langLabel = lang.charAt(0).toUpperCase() + lang.slice(1); // "TypeScript", "Python"
+    // Language-specific security concerns for the prompt
+    const securityExamples = {
+        typescript: "sql_injection, xss, hardcoded_secret, unsanitized_input, path_traversal, prototype_pollution",
+        javascript: "sql_injection, xss, hardcoded_secret, unsanitized_input, path_traversal, prototype_pollution",
+        python: "sql_injection, command_injection, hardcoded_secret, unsanitized_input, path_traversal, pickle_deserialization, eval_exec, insecure_subprocess",
+    };
+    const securityHints = securityExamples[lang] || securityExamples.typescript;
+    const prompt = `Analyze these ${langLabel} functions. Return JSON array with one object per function.
+
+Each object must have:
+- name: string (function name, must match input)
+- description: string (one sentence)
+- params: array of { name, type, description }
+- returns: { type, description }
+- dataTags: array from [user_input, pii, credentials, database, external_api, file_system, config, internal]
+- securityFlags: array of concerns like [${securityHints}] or empty
+
+Functions:
+${functions
+        .map((fn) => `### ${fn.name}\n\`\`\`${lang}\n${fn.sourceCode}\n\`\`\``)
+        .join("\n\n")}
+
+CRITICAL: Return ONLY the raw JSON array. No markdown, no code fences, no \`\`\`json blocks, no explanation. Just the [ ... ] array directly.`;
+    const response = await (0, p_retry_1.default)(() => anthropic.messages.create({
+        model: "claude-sonnet-4-20250514",
+        max_tokens: 4096,
+        messages: [{ role: "user", content: prompt }],
+    }), {
+        retries: 4,
+        onFailedAttempt: (err) => {
+            if (err.status !== 429)
+                throw err;
+            console.log(`  Rate limited, retrying (${err.attemptNumber}/4)...`);
+        },
+    });
+    const text = response.content[0].type === "text" ? response.content[0].text : "";
+    try {
+        // Strip markdown code fences if model adds them
+        const cleaned = text.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+        const results = JSON.parse(cleaned);
+        return functions.map((fn) => {
+            const raw = results.find((r) => r.name === fn.name) || {};
+            // Validate with Zod, using .catch() defaults for graceful degradation
+            const validated = schemas_1.ClaudeAnalysisResponse.parse({ name: fn.name, ...raw });
+            return {
+                ...fn,
+                description: validated.description,
+                params: validated.params,
+                returns: validated.returns,
+                dataTags: validated.dataTags,
+                securityFlags: validated.securityFlags,
+            };
+        });
+    }
+    catch (e) {
+        console.error("Failed to parse LLM response:", text);
+        return functions.map((fn) => ({
+            ...fn,
+            description: "Analysis failed",
+            params: [],
+            returns: { type: "unknown", description: "" },
+            dataTags: [],
+            securityFlags: [],
+        }));
+    }
+}
+/**
+ * Analyze a specific set of files: parse → hash → pull → Claude → store.
+ * Used by `analyzeRepository()` for full scans and `ophan watch` for incremental.
+ * The caller is responsible for DB lifecycle (open/close).
+ */
+async function analyzeFiles(db, rootPath, files, options = {}) {
+    const { pullFn, onProgress } = options;
+    const now = Math.floor(Date.now() / 1000);
+    let totalAnalyzed = 0;
+    let totalSkippedSize = 0;
+    let totalSkipped = 0;
+    let totalPulled = 0;
+    // Prepared statements
+    const getFileMtime = db.prepare("SELECT file_mtime FROM file_functions WHERE file_path = ? LIMIT 1");
+    // Check for documentation type — if it exists, security exists too (always written together)
+    const checkAnalysis = db.prepare("SELECT 1 FROM function_analysis WHERE content_hash = ? AND analysis_type = 'documentation'");
+    const insertDocAnalysis = db.prepare(`
+    INSERT OR IGNORE INTO function_analysis
+    (content_hash, analysis_type, analysis, model_version, schema_version, created_at, last_seen_at, language, entity_type)
+    VALUES (?, 'documentation', ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const insertSecAnalysis = db.prepare(`
+    INSERT OR IGNORE INTO function_analysis
+    (content_hash, analysis_type, analysis, model_version, schema_version, created_at, last_seen_at, language, entity_type)
+    VALUES (?, 'security', ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const deleteFileEntries = db.prepare("DELETE FROM file_functions WHERE file_path = ?");
+    const insertFileFunction = db.prepare(`
+    INSERT INTO file_functions
+    (file_path, function_name, content_hash, file_mtime, language, entity_type)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+    const pendingFiles = [];
+    const allMissingHashes = new Set();
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        const relPath = path.relative(rootPath, file);
+        onProgress?.(i + 1, files.length, relPath);
+        const stat = fs.statSync(file);
+        if (stat.size > MAX_FILE_SIZE_BYTES) {
+            totalSkippedSize++;
+            continue;
+        }
+        const currentMtime = Math.floor(stat.mtimeMs);
+        const storedRow = getFileMtime.get(file);
+        if (storedRow && storedRow.file_mtime === currentMtime) {
+            continue;
+        }
+        const parser = (0, parsers_1.getParserForFile)(file);
+        if (!parser)
+            continue;
+        const functions = parser.extractFunctions(file);
+        if (functions.length === 0) {
+            deleteFileEntries.run(file);
+            continue;
+        }
+        const needsAnalysis = [];
+        for (const fn of functions) {
+            if (checkAnalysis.get(fn.contentHash)) {
+                totalSkipped++;
+            }
+            else {
+                needsAnalysis.push(fn);
+                allMissingHashes.add(fn.contentHash);
+            }
+        }
+        pendingFiles.push({ file, functions, needsAnalysis, mtime: currentMtime });
+    }
+    // Phase 2: Pull from cloud to avoid redundant Claude calls
+    if (pullFn && allMissingHashes.size > 0) {
+        await pullFn([...allMissingHashes]);
+    }
+    // Phase 3: Run Claude analysis on hashes still missing, update file_functions
+    const modelVersion = "claude-sonnet-4-20250514";
+    for (const pending of pendingFiles) {
+        // Re-check after pull — some hashes may now exist locally
+        const stillNeeds = pullFn
+            ? pending.needsAnalysis.filter((fn) => !checkAnalysis.get(fn.contentHash))
+            : pending.needsAnalysis;
+        const pulled = pending.needsAnalysis.length - stillNeeds.length;
+        totalPulled += pulled;
+        totalSkipped += pulled;
+        for (let j = 0; j < stillNeeds.length; j += 10) {
+            const batch = stillNeeds.slice(j, j + 10);
+            const analyzed = await analyzeFunctions(batch);
+            for (const fn of analyzed) {
+                insertDocAnalysis.run(fn.contentHash, JSON.stringify({
+                    description: fn.description,
+                    params: fn.params,
+                    returns: fn.returns,
+                }), modelVersion, schemas_1.SCHEMA_VERSIONS.documentation, now, now, fn.language, fn.entityType);
+                insertSecAnalysis.run(fn.contentHash, JSON.stringify({
+                    dataTags: fn.dataTags,
+                    securityFlags: fn.securityFlags,
+                }), modelVersion, schemas_1.SCHEMA_VERSIONS.security, now, now, fn.language, fn.entityType);
+            }
+            totalAnalyzed += analyzed.length;
+        }
+        // Rebuild file_functions for this file
+        deleteFileEntries.run(pending.file);
+        for (const fn of pending.functions) {
+            insertFileFunction.run(pending.file, fn.name, fn.contentHash, pending.mtime, fn.language, fn.entityType);
+        }
+    }
+    return { analyzed: totalAnalyzed, skipped: totalSkipped, skippedSize: totalSkippedSize, pulled: totalPulled };
+}
+async function analyzeRepository(rootPath, onProgress, pullFn) {
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    fs.mkdirSync(path.join(rootPath, ".ophan"), { recursive: true });
+    // Auto-add .ophan/ to .gitignore (only in git repos)
+    ensureGitignore(rootPath);
+    const db = initDb(dbPath);
+    const now = Math.floor(Date.now() / 1000);
+    const files = await discoverFiles(rootPath);
+    const result = await analyzeFiles(db, rootPath, files, { pullFn, onProgress });
+    // Clean up entries for deleted files
+    const fileSet = new Set(files);
+    const deleteFileEntries = db.prepare("DELETE FROM file_functions WHERE file_path = ?");
+    const storedPaths = db
+        .prepare("SELECT DISTINCT file_path FROM file_functions")
+        .all();
+    for (const { file_path } of storedPaths) {
+        if (!fileSet.has(file_path)) {
+            deleteFileEntries.run(file_path);
+        }
+    }
+    // Update last_seen_at for all hashes currently referenced
+    db.prepare(`UPDATE function_analysis SET last_seen_at = ?
+     WHERE content_hash IN (SELECT DISTINCT content_hash FROM file_functions)`).run(now);
+    db.close();
+    return { files: files.length, ...result };
+}
+// ============ QUERY ============
+/**
+ * Merge documentation + security analysis rows for a content_hash into
+ * the unified FunctionAnalysis shape that consumers expect.
+ */
+function mergeAnalysisRows(rows) {
+    let doc = {};
+    let sec = {};
+    for (const row of rows) {
+        const parsed = JSON.parse(row.analysis);
+        if (row.analysis_type === "documentation")
+            doc = parsed;
+        else if (row.analysis_type === "security")
+            sec = parsed;
+    }
+    return {
+        description: doc.description || "",
+        params: doc.params || [],
+        returns: doc.returns || { type: "unknown", description: "" },
+        dataTags: sec.dataTags || [],
+        securityFlags: sec.securityFlags || [],
+    };
+}
+function getAnalysisForFile(dbPath, filePath) {
+    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
+    const rows = db
+        .prepare(`SELECT ff.function_name, ff.content_hash, fa.analysis_type, fa.analysis, ff.language, ff.entity_type
+       FROM file_functions ff
+       JOIN function_analysis fa ON ff.content_hash = fa.content_hash
+       WHERE ff.file_path = ?`)
+        .all(filePath);
+    db.close();
+    // Group by content_hash, merge analysis types
+    const grouped = new Map();
+    for (const row of rows) {
+        const existing = grouped.get(row.content_hash);
+        if (existing) {
+            existing.analysisRows.push({ analysis_type: row.analysis_type, analysis: row.analysis });
+        }
+        else {
+            grouped.set(row.content_hash, {
+                functionName: row.function_name,
+                contentHash: row.content_hash,
+                language: row.language,
+                entityType: row.entity_type,
+                analysisRows: [{ analysis_type: row.analysis_type, analysis: row.analysis }],
+            });
+        }
+    }
+    return [...grouped.values()].map((entry) => ({
+        functionName: entry.functionName,
+        contentHash: entry.contentHash,
+        analysis: mergeAnalysisRows(entry.analysisRows),
+        language: entry.language,
+        entityType: entry.entityType,
+    }));
+}
+function getAnalysisByHash(dbPath, hash) {
+    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
+    const rows = db
+        .prepare("SELECT analysis_type, analysis FROM function_analysis WHERE content_hash = ?")
+        .all(hash);
+    db.close();
+    if (rows.length === 0)
+        return null;
+    return mergeAnalysisRows(rows);
+}
+// ============ GC ============
+function gcAnalysis(dbPath, maxAgeDays = 30) {
+    const db = new better_sqlite3_1.default(dbPath);
+    const cutoff = Math.floor(Date.now() / 1000) - maxAgeDays * 24 * 60 * 60;
+    const now = Math.floor(Date.now() / 1000);
+    // Insert tombstones for hashes about to be deleted (for sync to Supabase)
+    // One tombstone per (content_hash, analysis_type) pair
+    db.prepare(`INSERT OR IGNORE INTO function_gc (content_hash, analysis_type, gc_at)
+     SELECT content_hash, analysis_type, ?
+     FROM function_analysis
+     WHERE content_hash NOT IN (SELECT DISTINCT content_hash FROM file_functions)
+     AND last_seen_at < ?`).run(now, cutoff);
+    // Also clean up any previously-synced GC entries
+    db.prepare("DELETE FROM function_gc WHERE synced_at IS NOT NULL").run();
+    const result = db
+        .prepare(`DELETE FROM function_analysis
+       WHERE content_hash NOT IN (SELECT DISTINCT content_hash FROM file_functions)
+       AND last_seen_at < ?`)
+        .run(cutoff);
+    db.close();
+    return { deleted: result.changes };
+}
+// ============ REFRESH INDEX ============
+async function refreshFileIndex(rootPath, onProgress) {
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    if (!fs.existsSync(dbPath))
+        return;
+    const db = initDb(dbPath);
+    const now = Math.floor(Date.now() / 1000);
+    const files = await discoverFiles(rootPath);
+    const getFileMtime = db.prepare("SELECT file_mtime FROM file_functions WHERE file_path = ? LIMIT 1");
+    const deleteFileEntries = db.prepare("DELETE FROM file_functions WHERE file_path = ?");
+    const insertFileFunction = db.prepare(`
+    INSERT INTO file_functions
+    (file_path, function_name, content_hash, file_mtime, language, entity_type)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+    const fileSet = new Set(files);
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        const relPath = path.relative(rootPath, file);
+        onProgress?.(i + 1, files.length, relPath);
+        const stat = fs.statSync(file);
+        if (stat.size > MAX_FILE_SIZE_BYTES)
+            continue;
+        const currentMtime = Math.floor(stat.mtimeMs);
+        const storedRow = getFileMtime.get(file);
+        if (storedRow && storedRow.file_mtime === currentMtime) {
+            continue;
+        }
+        const parser = (0, parsers_1.getParserForFile)(file);
+        if (!parser)
+            continue;
+        const functions = parser.extractFunctions(file);
+        deleteFileEntries.run(file);
+        for (const fn of functions) {
+            insertFileFunction.run(file, fn.name, fn.contentHash, currentMtime, fn.language, fn.entityType);
+        }
+    }
+    // Remove entries for deleted files
+    const storedPaths = db
+        .prepare("SELECT DISTINCT file_path FROM file_functions")
+        .all();
+    for (const { file_path } of storedPaths) {
+        if (!fileSet.has(file_path)) {
+            deleteFileEntries.run(file_path);
+        }
+    }
+    // Update last_seen_at for current hashes
+    db.prepare(`UPDATE function_analysis SET last_seen_at = ?
+     WHERE content_hash IN (SELECT DISTINCT content_hash FROM file_functions)`).run(now);
+    db.close();
+}
+// ============ PULL SYNC HELPERS ============
+/**
+ * Find content hashes that are referenced in file_functions but have no
+ * analysis in function_analysis. Used by CLI to know what to pull from Supabase
+ * before running expensive Claude analysis.
+ */
+function findMissingHashes(dbPath) {
+    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
+    const rows = db.prepare(`SELECT DISTINCT ff.content_hash
+     FROM file_functions ff
+     LEFT JOIN function_analysis fa ON ff.content_hash = fa.content_hash AND fa.analysis_type = 'documentation'
+     WHERE fa.content_hash IS NULL`).all();
+    db.close();
+    return rows.map((r) => r.content_hash);
+}
+/**
+ * Import analysis rows pulled from Supabase into the local SQLite database.
+ * Used by CLI pull sync to cache remote analysis locally.
+ */
+function importAnalysis(dbPath, rows) {
+    if (rows.length === 0)
+        return 0;
+    const db = new better_sqlite3_1.default(dbPath);
+    const now = Math.floor(Date.now() / 1000);
+    const insert = db.prepare(`
+    INSERT OR IGNORE INTO function_analysis
+    (content_hash, analysis_type, analysis, model_version, schema_version, created_at, last_seen_at, language, entity_type, synced_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    let imported = 0;
+    const runInserts = db.transaction(() => {
+        for (const r of rows) {
+            const result = insert.run(r.content_hash, r.analysis_type, r.analysis, r.model_version, r.schema_version, now, now, r.language, r.entity_type, now // synced_at = now (came from Supabase)
+            );
+            if (result.changes > 0)
+                imported++;
+        }
+    });
+    runInserts();
+    db.close();
+    return imported;
+}