@psnext/lscg 0.1.2 → 0.1.4

package/dist/src/scanner/plugins.js

@@ -0,0 +1,503 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { discoverSourceFiles } from './discover.js';
+export const SCANNER_PLUGIN_API_VERSION = 1;
+export const DEFAULT_PLUGIN_RESOURCE_LIMITS = {
+    maxNodes: 100_000,
+    maxEdges: 200_000,
+    maxDiagnostics: 1_000,
+    maxMetadataBytes: 1_048_576,
+    maxSerializedOutputBytes: 5_242_880,
+    maxDiagnosticMessageBytes: 4_096
+};
+const MIN_DIAGNOSTIC_MESSAGE_BYTES = 17;
+const GRAPH_NODE_KINDS = new Set(['file', 'symbol', 'import', 'export', 'call', 'user', 'package']);
+const GRAPH_EDGE_KINDS = new Set(['contains', 'defines', 'imports', 'exports', 'calls', 'attributed_to', 'provides']);
+/** Namespace used by plugins to target nodes produced by the built-in scanner. */
+export const BUILTIN_GRAPH_PLUGIN = '__lscg_builtin__';
+export function createRepositoryScanContext(repoPath) {
+    const discoveredPaths = discoverSourceFiles(repoPath);
+    const files = discoveredPaths.flatMap((relativePath) => {
+        try {
+            const absolutePath = path.join(repoPath, relativePath);
+            const source = readFileSync(absolutePath, 'utf8');
+            const stat = statSync(absolutePath);
+            return [{
+                    id: hashParts(['file', repoPath, relativePath]),
+                    path: relativePath,
+                    language: path.extname(relativePath).slice(1),
+                    hash: sha256(source),
+                    size: stat.size,
+                    mtimeMs: Math.round(stat.mtimeMs),
+                    absolutePath,
+                    source
+                }];
+        }
+        catch {
+            return [];
+        }
+    });
+    return { repoPath, files, discoveredPaths, readFile: (relativePath) => readFileSync(path.join(repoPath, relativePath), 'utf8') };
+}
+export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
+    const limits = normalizePluginResourceLimits(resourceLimits);
+    const nodes = [];
+    const edges = [];
+    const diagnostics = [];
+    const failedPlugins = [];
+    const successfulPlugins = [];
+    const owners = new Map();
+    for (const plugin of plugins) {
+        try {
+            validatePlugin(plugin);
+            await plugin.initialize?.(context);
+            const result = await plugin.scan(context);
+            const finalized = await plugin.finalize?.(context);
+            validatePluginResult(plugin.name, result, 'scan');
+            if (finalized !== undefined)
+                validatePluginResult(plugin.name, finalized, 'finalize');
+            enforceResourceLimits(plugin, result, finalized, limits);
+            collect(plugin, result, nodes, edges, owners, diagnostics, limits);
+            if (finalized)
+                collect(plugin, finalized, nodes, edges, owners, diagnostics, limits);
+            successfulPlugins.push(plugin.name);
+        }
+        catch (error) {
+            failedPlugins.push(plugin.name);
+            if (error instanceof PluginBudgetError) {
+                addBudgetDiagnostic(diagnostics, error.pluginName, error.budget, limits);
+            }
+            else {
+                addDiagnostic(diagnostics, `${plugin.name}: ${error instanceof Error ? error.message : String(error)}`, limits);
+            }
+        }
+        finally {
+            try {
+                await plugin.dispose?.(context);
+            }
+            catch (error) {
+                addDiagnostic(diagnostics, `${plugin.name}: dispose failed: ${error instanceof Error ? error.message : String(error)}`, limits);
+            }
+        }
+    }
+    const nodeByIdentity = new Map(nodes.map((node) => {
+        const materialized = materializeNode(node, context);
+        return [canonicalNodeIdentity(node.pluginName ?? '', node.factKey), materialized];
+    }));
+    const materializedNodes = [...nodeByIdentity.values()];
+    const materializedEdges = [];
+    for (const edge of edges) {
+        const sourceIdentity = canonicalNodeIdentity(edge.sourcePlugin ?? edge.pluginName ?? '', edge.sourceFactKey);
+        const targetPlugin = edge.targetPlugin ?? edge.pluginName ?? '';
+        const targetIdentity = canonicalNodeIdentity(targetPlugin, edge.targetFactKey);
+        const source = nodeByIdentity.get(sourceIdentity);
+        const target = targetPlugin === BUILTIN_GRAPH_PLUGIN
+            ? { id: edge.targetFactKey }
+            : nodeByIdentity.get(targetIdentity);
+        if (!source || !target) {
+            addDiagnostic(diagnostics, `unresolved edge ${edge.factKey}: ${edge.sourceFactKey} -> ${edge.targetFactKey}`, limits);
+            continue;
+        }
+        materializedEdges.push({
+            id: hashParts(['plugin-edge', edge.pluginName ?? '', edge.factKey, sourceIdentity, targetIdentity, edge.kind]),
+            sourceId: source.id,
+            targetId: target.id,
+            kind: edge.kind,
+            confidence: edge.confidence ?? 1,
+            metadata: {
+                ...(edge.metadata ?? {}),
+                ...(edge.filePath ? { filePath: edge.filePath } : { filePath: nodeFilePath(source, context) }),
+                factKey: edge.factKey,
+                plugin: edge.pluginName,
+                ...(edge.sourcePlugin ? { sourcePlugin: edge.sourcePlugin } : {}),
+                ...(edge.targetPlugin ? { targetPlugin: edge.targetPlugin } : {})
+            }
+        });
+    }
+    const pluginContributions = new Map();
+    for (const node of materializedNodes) {
+        const plugin = typeof node.metadata.plugin === 'string' ? node.metadata.plugin : undefined;
+        if (plugin)
+            contributionFor(plugin).nodes.push(node);
+    }
+    for (const edge of materializedEdges) {
+        const plugin = typeof edge.metadata.plugin === 'string' ? edge.metadata.plugin : undefined;
+        if (plugin)
+            contributionFor(plugin).edges.push(edge);
+    }
+    function contributionFor(plugin) {
+        const existing = pluginContributions.get(plugin);
+        if (existing)
+            return existing;
+        const created = { nodes: [], edges: [] };
+        pluginContributions.set(plugin, created);
+        return created;
+    }
+    return { nodes: materializedNodes, edges: materializedEdges, diagnostics, failedPlugins, successfulPlugins, pluginContributions };
+    function collect(plugin, result, nodeOutput, edgeOutput, ownerMap, messages, contributionLimits) {
+        for (const node of result.nodes ?? []) {
+            const identity = canonicalNodeIdentity(plugin.name, node.factKey);
+            const candidate = { ...node, factKey: node.factKey, pluginName: plugin.name };
+            applyFact('node', node.factKey, identity, plugin, node.conflict, nodeOutput, candidate, ownerMap, messages, contributionLimits);
+        }
+        for (const edge of result.edges ?? []) {
+            const identity = canonicalEdgeIdentity(plugin.name, edge.factKey);
+            const candidate = { ...edge, factKey: edge.factKey, sourceFactKey: edge.sourceFactKey, targetFactKey: edge.targetFactKey, pluginName: plugin.name };
+            applyFact('edge', edge.factKey, identity, plugin, edge.conflict, edgeOutput, candidate, ownerMap, messages, contributionLimits);
+        }
+        for (const message of result.diagnostics ?? [])
+            addDiagnostic(messages, `${plugin.name}: ${message}`, contributionLimits);
+    }
+}
+function canonicalNodeIdentity(pluginName, factKey) {
+    return `${pluginName}\u0000node\u0000${factKey}`;
+}
+function canonicalEdgeIdentity(pluginName, factKey) {
+    return `${pluginName}\u0000edge\u0000${factKey}`;
+}
+function applyFact(category, factKey, identity, plugin, policy, output, candidate, owners, diagnostics, limits) {
+    const conflictKey = `${category}\u0000${factKey}`;
+    const existing = owners.get(conflictKey) ?? [];
+    const incumbent = existing[0];
+    if (existing.some((owner) => owner.identity === identity)) {
+        addDiagnostic(diagnostics, `duplicate ${category} rejected for ${plugin.name}:${factKey}`, limits);
+        return;
+    }
+    if (!incumbent) {
+        owners.set(conflictKey, [{ priority: plugin.priority ?? 0, plugin: plugin.name, policy: policy ?? 'merge', identity }]);
+        output.push(candidate);
+        return;
+    }
+    const chosen = policy ?? incumbent.policy;
+    if (chosen === 'merge') {
+        existing.push({ priority: plugin.priority ?? 0, plugin: plugin.name, policy: policy ?? chosen, identity });
+        output.push(candidate);
+        return;
+    }
+    if (chosen === 'reject') {
+        addDiagnostic(diagnostics, `conflict rejected for ${category}:${factKey} (${incumbent.plugin}, ${plugin.name})`, limits);
+        return;
+    }
+    const candidatePriority = plugin.priority ?? 0;
+    const wins = candidatePriority > incumbent.priority || (candidatePriority === incumbent.priority && plugin.name > incumbent.plugin);
+    if (!wins) {
+        addDiagnostic(diagnostics, `conflict replaced by higher priority for ${category}:${factKey} (${incumbent.plugin}, ${plugin.name})`, limits);
+        return;
+    }
+    for (let index = output.length - 1; index >= 0; index -= 1) {
+        const outputIdentity = category === 'node'
+            ? canonicalNodeIdentity(output[index].pluginName ?? '', output[index].factKey)
+            : canonicalEdgeIdentity(output[index].pluginName ?? '', output[index].factKey);
+        if (existing.some((owner) => owner.identity === outputIdentity))
+            output.splice(index, 1);
+    }
+    owners.set(conflictKey, [{ priority: candidatePriority, plugin: plugin.name, policy: policy ?? chosen, identity }]);
+    output.push(candidate);
+}
+function acceptFact(key, plugin, policy, owners, diagnostics, limits) {
+    const priority = plugin.priority ?? 0;
+    const existing = owners.get(key);
+    if (!existing) {
+        owners.set(key, { priority, plugin: plugin.name, policy: policy ?? 'merge' });
+        return true;
+    }
+    const chosen = policy ?? existing.policy;
+    if (chosen === 'reject') {
+        addDiagnostic(diagnostics, `conflict rejected for ${key} (${existing.plugin}, ${plugin.name})`, limits);
+        return false;
+    }
+    if (chosen === 'replace' && priority >= existing.priority) {
+        owners.set(key, { priority, plugin: plugin.name, policy: chosen });
+        return true;
+    }
+    return chosen === 'merge' && priority >= existing.priority;
+}
+function normalizePluginResourceLimits(overrides) {
+    const limits = { ...DEFAULT_PLUGIN_RESOURCE_LIMITS, ...overrides };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error(`invalid plugin resource limit ${name}: ${value}`);
+    }
+    if (limits.maxDiagnostics < 1)
+        throw new Error('maxDiagnostics must be at least 1');
+    if (limits.maxDiagnosticMessageBytes < MIN_DIAGNOSTIC_MESSAGE_BYTES) {
+        throw new Error(`maxDiagnosticMessageBytes must be at least ${MIN_DIAGNOSTIC_MESSAGE_BYTES}`);
+    }
+    return limits;
+}
+function validatePluginResult(pluginName, value, phase) {
+    if (!isRecord(value))
+        throw new Error(`${pluginName}: invalid ${phase} result: expected an object`);
+    if (!Array.isArray(value.nodes))
+        throw new Error(`${pluginName}: invalid ${phase} result: nodes must be an array`);
+    if (!Array.isArray(value.edges))
+        throw new Error(`${pluginName}: invalid ${phase} result: edges must be an array`);
+    if (value.diagnostics !== undefined && (!Array.isArray(value.diagnostics) || value.diagnostics.some((message) => typeof message !== 'string'))) {
+        throw new Error(`${pluginName}: invalid ${phase} result: diagnostics must be an array of strings`);
+    }
+    value.nodes.forEach((node, index) => validateNodeFact(pluginName, node, `${phase}.nodes[${index}]`));
+    value.edges.forEach((edge, index) => validateEdgeFact(pluginName, edge, `${phase}.edges[${index}]`));
+}
+function validateNodeFact(pluginName, value, location) {
+    if (!isRecord(value))
+        throw new Error(`${pluginName}: invalid plugin fact ${location}: expected an object`);
+    requireNonEmptyString(pluginName, location, 'factKey', value.factKey);
+    requireNonEmptyString(pluginName, location, 'type', value.type);
+    if (!GRAPH_NODE_KINDS.has(value.kind)) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.kind: ${String(value.kind)}`);
+    }
+    if (value.filePath !== undefined)
+        requireNonEmptyString(pluginName, location, 'filePath', value.filePath);
+    if (value.name !== undefined && value.name !== null)
+        requireString(pluginName, location, 'name', value.name);
+    for (const field of ['sourceHash', 'parser', 'parserVersion']) {
+        if (value[field] !== undefined)
+            requireString(pluginName, location, field, value[field]);
+    }
+    for (const field of ['startByte', 'endByte']) {
+        if (value[field] !== undefined)
+            requireNonNegativeInteger(pluginName, location, field, value[field]);
+    }
+    for (const field of ['startPoint', 'endPoint']) {
+        if (value[field] !== undefined)
+            requirePoint(pluginName, location, field, value[field]);
+    }
+    if (value.conflict !== undefined && !['merge', 'replace', 'reject'].includes(String(value.conflict))) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.conflict: ${String(value.conflict)}`);
+    }
+    if (value.metadata !== undefined && !isRecord(value.metadata)) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.metadata: expected an object`);
+    }
+}
+function validateEdgeFact(pluginName, value, location) {
+    if (!isRecord(value))
+        throw new Error(`${pluginName}: invalid plugin fact ${location}: expected an object`);
+    requireNonEmptyString(pluginName, location, 'factKey', value.factKey);
+    requireNonEmptyString(pluginName, location, 'sourceFactKey', value.sourceFactKey);
+    requireNonEmptyString(pluginName, location, 'targetFactKey', value.targetFactKey);
+    for (const field of ['sourcePlugin', 'targetPlugin']) {
+        if (value[field] !== undefined)
+            requireNonEmptyString(pluginName, location, field, value[field]);
+    }
+    if (!GRAPH_EDGE_KINDS.has(value.kind)) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.kind: ${String(value.kind)}`);
+    }
+    if (value.filePath !== undefined)
+        requireNonEmptyString(pluginName, location, 'filePath', value.filePath);
+    if (value.confidence !== undefined && (typeof value.confidence !== 'number' || !Number.isFinite(value.confidence) || value.confidence < 0 || value.confidence > 1)) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.confidence: ${String(value.confidence)}`);
+    }
+    if (value.conflict !== undefined && !['merge', 'replace', 'reject'].includes(String(value.conflict))) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.conflict: ${String(value.conflict)}`);
+    }
+    if (value.metadata !== undefined && !isRecord(value.metadata)) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.metadata: expected an object`);
+    }
+}
+function requireNonEmptyString(pluginName, location, field, value) {
+    requireString(pluginName, location, field, value);
+    if (value.trim().length === 0) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.${field}: expected a non-empty string`);
+    }
+}
+function requireString(pluginName, location, field, value) {
+    if (typeof value !== 'string')
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.${field}: expected a string`);
+}
+function requireNonNegativeInteger(pluginName, location, field, value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.${field}: expected a non-negative integer`);
+    }
+}
+function requirePoint(pluginName, location, field, value) {
+    const point = isRecord(value) ? value : undefined;
+    if (!point || typeof point.row !== 'number' || !Number.isSafeInteger(point.row) || point.row < 0 ||
+        typeof point.column !== 'number' || !Number.isSafeInteger(point.column) || point.column < 0) {
+        throw new Error(`${pluginName}: invalid plugin fact ${location}.${field}: expected non-negative row and column`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function enforceResourceLimits(plugin, result, finalized, limits) {
+    let nodeCount = 0;
+    let edgeCount = 0;
+    let diagnosticCount = 0;
+    let metadataBytes = 0;
+    let serializedBytes = 0;
+    for (const contribution of [result, finalized]) {
+        if (!contribution)
+            continue;
+        nodeCount += contribution.nodes.length;
+        edgeCount += contribution.edges.length;
+        diagnosticCount += contribution.diagnostics?.length ?? 0;
+        if (nodeCount > limits.maxNodes)
+            throw new PluginBudgetError(plugin.name, 'maxNodes');
+        if (edgeCount > limits.maxEdges)
+            throw new PluginBudgetError(plugin.name, 'maxEdges');
+        if (diagnosticCount > limits.maxDiagnostics)
+            throw new PluginBudgetError(plugin.name, 'maxDiagnostics');
+        for (const node of contribution.nodes) {
+            if (node.metadata !== undefined)
+                metadataBytes += boundedJsonByteLength(node.metadata, limits.maxMetadataBytes - metadataBytes, plugin.name, 'maxMetadataBytes');
+            if (metadataBytes > limits.maxMetadataBytes)
+                throw new PluginBudgetError(plugin.name, 'maxMetadataBytes');
+        }
+        for (const edge of contribution.edges) {
+            if (edge.metadata !== undefined)
+                metadataBytes += boundedJsonByteLength(edge.metadata, limits.maxMetadataBytes - metadataBytes, plugin.name, 'maxMetadataBytes');
+            if (metadataBytes > limits.maxMetadataBytes)
+                throw new PluginBudgetError(plugin.name, 'maxMetadataBytes');
+        }
+        for (const message of contribution.diagnostics ?? []) {
+            if (Buffer.byteLength(message, 'utf8') > limits.maxDiagnosticMessageBytes)
+                throw new PluginBudgetError(plugin.name, 'maxDiagnosticMessageBytes');
+        }
+        serializedBytes += boundedJsonByteLength(contribution, limits.maxSerializedOutputBytes - serializedBytes, plugin.name, 'maxSerializedOutputBytes');
+        if (serializedBytes > limits.maxSerializedOutputBytes)
+            throw new PluginBudgetError(plugin.name, 'maxSerializedOutputBytes');
+    }
+}
+function boundedJsonByteLength(value, budget, pluginName, budgetName) {
+    const seen = new Set();
+    let total = 0;
+    function add(bytes) {
+        total += bytes;
+        if (total > budget)
+            throw new PluginBudgetError(pluginName, budgetName);
+    }
+    function visit(candidate) {
+        if (candidate === null) {
+            add(4);
+            return;
+        }
+        if (typeof candidate === 'string') {
+            add(Buffer.byteLength(JSON.stringify(candidate), 'utf8'));
+            return;
+        }
+        if (typeof candidate === 'number' || typeof candidate === 'boolean') {
+            add(Buffer.byteLength(String(candidate), 'utf8'));
+            return;
+        }
+        if (typeof candidate !== 'object')
+            return;
+        if (seen.has(candidate))
+            throw new Error('circular plugin output');
+        seen.add(candidate);
+        if (Array.isArray(candidate)) {
+            add(1);
+            candidate.forEach((item, index) => { if (index > 0)
+                add(1); visit(item); });
+            add(1);
+        }
+        else {
+            const entries = Object.entries(candidate);
+            add(1);
+            entries.forEach(([key, item], index) => {
+                if (index > 0)
+                    add(1);
+                add(Buffer.byteLength(JSON.stringify(key), 'utf8'));
+                add(1);
+                visit(item);
+            });
+            add(1);
+        }
+        seen.delete(candidate);
+    }
+    try {
+        visit(value);
+    }
+    catch (error) {
+        if (error instanceof PluginBudgetError)
+            throw error;
+        throw new Error(`invalid plugin output: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return total;
+}
+function addDiagnostic(diagnostics, message, limits) {
+    if (diagnostics.length >= limits.maxDiagnostics)
+        return;
+    diagnostics.push(truncateUtf8(message, limits.maxDiagnosticMessageBytes));
+}
+function addBudgetDiagnostic(diagnostics, pluginName, budget, limits) {
+    const budgetCode = budgetCodeFor(budget);
+    const compactMessage = `limit:${budgetCode}`;
+    const message = `${pluginName}: ${compactMessage}`;
+    const boundedMessage = Buffer.byteLength(message, 'utf8') <= limits.maxDiagnosticMessageBytes
+        ? message
+        : compactMessage;
+    if (diagnostics.length >= limits.maxDiagnostics)
+        diagnostics[limits.maxDiagnostics - 1] = boundedMessage;
+    else
+        diagnostics.push(boundedMessage);
+}
+function budgetCodeFor(budget) {
+    return {
+        maxNodes: 'nodes',
+        maxEdges: 'edges',
+        maxDiagnostics: 'diagnostics',
+        maxMetadataBytes: 'metadata',
+        maxSerializedOutputBytes: 'serialized',
+        maxDiagnosticMessageBytes: 'diagnostic'
+    }[budget] ?? 'output';
+}
+function truncateUtf8(value, maxBytes) {
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes)
+        return value;
+    let truncated = '';
+    for (const character of value) {
+        const next = truncated + character;
+        if (Buffer.byteLength(next, 'utf8') > maxBytes)
+            break;
+        truncated = next;
+    }
+    return truncated;
+}
+class PluginBudgetError extends Error {
+    pluginName;
+    budget;
+    constructor(pluginName, budget) {
+        super(`${pluginName}: plugin output exceeded ${budget}`);
+        this.pluginName = pluginName;
+        this.budget = budget;
+        this.name = 'PluginBudgetError';
+    }
+}
+function nodeFilePath(node, _context) {
+    return typeof node.metadata.filePath === 'string' ? node.metadata.filePath : undefined;
+}
+function materializeNode(node, context) {
+    const filePath = node.filePath;
+    const pluginName = node.pluginName ?? '';
+    const file = filePath ? context.files.find((candidate) => candidate.path === filePath) : undefined;
+    const sourceHash = node.sourceHash ?? file?.hash ?? '';
+    const startByte = node.startByte ?? 0;
+    const endByte = node.endByte ?? file?.size ?? 0;
+    return {
+        id: hashParts(['plugin-node', pluginName, node.factKey]),
+        kind: node.kind,
+        type: node.type,
+        name: node.name ?? null,
+        startByte,
+        endByte,
+        startPoint: node.startPoint ?? { row: 0, column: 0 },
+        endPoint: node.endPoint ?? { row: 0, column: 0 },
+        sourceHash,
+        parser: node.parser ?? `plugin:${pluginName}`,
+        parserVersion: node.parserVersion ?? `plugin-api-${SCANNER_PLUGIN_API_VERSION}`,
+        metadata: { ...(node.metadata ?? {}), ...(filePath ? { filePath } : {}), factKey: node.factKey, plugin: pluginName, identity: canonicalNodeIdentity(pluginName, node.factKey) },
+        lastModifiedUserId: null
+    };
+}
+function validatePlugin(plugin) {
+    if (!plugin?.name || !Number.isInteger(plugin.apiVersion) || plugin.apiVersion !== SCANNER_PLUGIN_API_VERSION)
+        throw new Error(`incompatible scanner plugin: ${plugin?.name ?? 'unknown'}`);
+    if (!Array.isArray(plugin.capabilities) || typeof plugin.scan !== 'function')
+        throw new Error(`invalid scanner plugin: ${plugin.name}`);
+}
+function hashParts(parts) {
+    return createHash('sha256').update(parts.map(String).join('\0')).digest('hex').slice(0, 32);
+}
+function sha256(value) { return createHash('sha256').update(value).digest('hex'); }
+//# sourceMappingURL=plugins.js.map

package/dist/src/storage/connection.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseSync } from 'node:sqlite';
+export declare function openGraphDatabase(databasePath: string): DatabaseSync;
+export declare function openReadOnlyGraphDatabase(databasePath: string): DatabaseSync;
+export declare function closeDatabase(db: DatabaseSync): void;
+export declare function attachDatabase(db: DatabaseSync, alias: string, databasePath: string): void;
+//# sourceMappingURL=connection.d.ts.map

package/dist/src/storage/connection.js

@@ -0,0 +1,133 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { CREATE_NODES_TABLE_SQL, CREATE_SCHEMA_SQL, SCHEMA_VERSION } from './schema.js';
+export function openGraphDatabase(databasePath) {
+    mkdirSync(path.dirname(databasePath), { recursive: true });
+    const db = new DatabaseSync(databasePath);
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec(CREATE_SCHEMA_SQL);
+    ensureSchemaVersion(db);
+    return db;
+}
+export function openReadOnlyGraphDatabase(databasePath) {
+    const db = new DatabaseSync(databasePath, { readOnly: true });
+    db.exec('PRAGMA foreign_keys = ON;');
+    return db;
+}
+export function closeDatabase(db) {
+    db.close();
+}
+export function attachDatabase(db, alias, databasePath) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(alias)) {
+        throw new Error(`Unsafe SQLite attachment alias: ${alias}`);
+    }
+    const escapedPath = databasePath.replaceAll("'", "''");
+    db.exec(`ATTACH DATABASE '${escapedPath}' AS ${alias}`);
+}
+function ensureSchemaVersion(db) {
+    const currentVersion = getCurrentSchemaVersion(db);
+    if (currentVersion === 0) {
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(SCHEMA_VERSION);
+        return;
+    }
+    if (currentVersion >= SCHEMA_VERSION)
+        return;
+    if (currentVersion === 1) {
+        migrateSchemaV1ToV2(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(2);
+    }
+    if (currentVersion <= 2) {
+        migrateSchemaV2ToV3(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(3);
+    }
+    if (currentVersion <= 3) {
+        migrateSchemaV3ToV4(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(SCHEMA_VERSION);
+        return;
+    }
+    throw new Error(`Unsupported schema version: ${currentVersion}`);
+}
+function migrateSchemaV3ToV4(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS plugin_contributions (
+      repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+      plugin_name TEXT NOT NULL,
+      generation INTEGER NOT NULL,
+      nodes_json TEXT NOT NULL,
+      edges_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY(repository_id, plugin_name)
+    );
+    CREATE INDEX IF NOT EXISTS idx_plugin_contributions_repo ON plugin_contributions(repository_id);
+  `);
+}
+function getCurrentSchemaVersion(db) {
+    const row = db.prepare('SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations').get();
+    return Number(row?.version ?? 0);
+}
+function migrateSchemaV1ToV2(db) {
+    db.exec('PRAGMA foreign_keys = OFF;');
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        db.exec(`DROP TABLE IF EXISTS nodes_new;`);
+        db.exec(CREATE_NODES_TABLE_SQL);
+        db.exec(`
+      INSERT INTO nodes_new(
+        id, repository_id, file_id, kind, type, name, start_byte, end_byte,
+        start_point, end_point, source_hash, parser, parser_version, metadata_json, last_modified_user_id
+      )
+      SELECT
+        id, repository_id, file_id, kind, type, name, start_byte, end_byte,
+        start_point, end_point, source_hash, parser, parser_version, metadata_json, NULL
+      FROM nodes;
+    `);
+        db.exec('DROP TABLE nodes;');
+        db.exec('ALTER TABLE nodes_new RENAME TO nodes;');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_repo_kind ON nodes(repository_id, kind);');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_repo_name ON nodes(repository_id, name);');
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+    finally {
+        db.exec('PRAGMA foreign_keys = ON;');
+    }
+}
+function migrateSchemaV2ToV3(db) {
+    db.exec('PRAGMA foreign_keys = OFF;');
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        db.exec(`
+      CREATE TABLE edges_new (
+        id TEXT PRIMARY KEY,
+        repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+        file_id TEXT REFERENCES files(id) ON DELETE CASCADE,
+        source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+        target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+        kind TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 1.0,
+        metadata_json TEXT NOT NULL DEFAULT '{}'
+      );
+      INSERT INTO edges_new(id, repository_id, file_id, source_id, target_id, kind, confidence, metadata_json)
+        SELECT id, repository_id, file_id, source_id, target_id, kind, confidence, metadata_json FROM edges;
+      DROP TABLE edges;
+      ALTER TABLE edges_new RENAME TO edges;
+      CREATE INDEX IF NOT EXISTS idx_edges_repo_kind ON edges(repository_id, kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+    `);
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+    finally {
+        db.exec('PRAGMA foreign_keys = ON;');
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/src/storage/context-queries.d.ts

@@ -0,0 +1,20 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { ContextCandidate, ContextSourceReference } from '../types.js';
+export interface ContextNodeRow extends ContextSourceReference {
+    fileId: string | null;
+}
+export declare function selectContextCandidates(db: DatabaseSync, repositoryId: string, term: string, { kind, file, limit }?: {
+    kind?: string | undefined;
+    file?: string | undefined;
+    limit?: number | undefined;
+}): ContextCandidate[];
+export declare function selectContextRelationships(db: DatabaseSync, repositoryId: string, anchorId: string, limit?: number, maxDepth?: number): Array<{
+    edgeId: string;
+    edgeKind: 'imports' | 'exports' | 'calls';
+    source: ContextNodeRow;
+    target: ContextNodeRow;
+    confidence: number;
+    metadata: Record<string, unknown>;
+    depth: number;
+}>;
+//# sourceMappingURL=context-queries.d.ts.map