@psnext/lscg 0.1.2 → 0.1.3

package/dist/src/scanner/plugins.d.ts

@@ -0,0 +1,86 @@
+import type { FileRecord, GraphEdge, GraphNode, GraphExtractionResult, Point } from '../types.js';
+export declare const SCANNER_PLUGIN_API_VERSION: 1;
+export type PluginConflictPolicy = 'merge' | 'replace' | 'reject';
+export type ScannerCapability = 'file-scanner' | 'repository-analyzer';
+export interface RepositoryScanFile extends FileRecord {
+    absolutePath: string;
+    source: string;
+}
+export interface RepositoryScanContext {
+    repoPath: string;
+    files: readonly RepositoryScanFile[];
+    discoveredPaths: readonly string[];
+    readFile(relativePath: string): string;
+}
+export interface PluginNodeFact {
+    factKey: string;
+    /** Internal owner assigned by the host; not part of plugin output. */
+    pluginName?: string;
+    filePath?: string;
+    kind: GraphNode['kind'];
+    type: string;
+    name?: string | null;
+    startByte?: number;
+    endByte?: number;
+    startPoint?: Point;
+    endPoint?: Point;
+    sourceHash?: string;
+    parser?: string;
+    parserVersion?: string;
+    metadata?: Record<string, unknown>;
+    conflict?: PluginConflictPolicy;
+}
+export interface PluginEdgeFact {
+    factKey: string;
+    /** Internal owner used to reconcile persisted edges per successful plugin. */
+    pluginName?: string;
+    sourceFactKey: string;
+    targetFactKey: string;
+    /** Optional cross-plugin namespace; omitted references use the edge's plugin. */
+    sourcePlugin?: string;
+    /** Optional cross-plugin namespace; omitted references use the edge's plugin. */
+    targetPlugin?: string;
+    filePath?: string;
+    kind: GraphEdge['kind'];
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+    conflict?: PluginConflictPolicy;
+}
+export interface PluginScanResult {
+    nodes: PluginNodeFact[];
+    edges: PluginEdgeFact[];
+    diagnostics?: string[];
+}
+export interface PluginResourceLimits {
+    maxNodes: number;
+    maxEdges: number;
+    maxDiagnostics: number;
+    maxMetadataBytes: number;
+    maxSerializedOutputBytes: number;
+    maxDiagnosticMessageBytes: number;
+}
+export declare const DEFAULT_PLUGIN_RESOURCE_LIMITS: PluginResourceLimits;
+/** Namespace used by plugins to target nodes produced by the built-in scanner. */
+export declare const BUILTIN_GRAPH_PLUGIN = "__lscg_builtin__";
+export interface ScannerPlugin {
+    name: string;
+    apiVersion: typeof SCANNER_PLUGIN_API_VERSION;
+    capabilities: readonly ScannerCapability[];
+    priority?: number;
+    initialize?(context: RepositoryScanContext): void | Promise<void>;
+    scan(context: RepositoryScanContext): PluginScanResult | Promise<PluginScanResult>;
+    finalize?(context: RepositoryScanContext): PluginScanResult | void | Promise<PluginScanResult | void>;
+    dispose?(context: RepositoryScanContext): void | Promise<void>;
+}
+export interface PluginRunResult extends GraphExtractionResult {
+    diagnostics: string[];
+    failedPlugins: string[];
+    successfulPlugins?: string[];
+    pluginContributions?: Map<string, {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    }>;
+}
+export declare function createRepositoryScanContext(repoPath: string): RepositoryScanContext;
+export declare function runScannerPlugins(context: RepositoryScanContext, plugins: readonly ScannerPlugin[], resourceLimits?: Partial<PluginResourceLimits>): Promise<PluginRunResult>;
+//# sourceMappingURL=plugins.d.ts.map

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