@psnext/lscg 0.1.4 → 0.1.5

package/dist/src/scanner/javaPlugin.js

@@ -0,0 +1,199 @@
+import { parseSource } from '../parser/treeSitter.js';
+import { runBatchedWorkers } from './parallelScan.js';
+export const JAVA_SCANNER_PLUGIN_NAME = 'java-scanner-plugin';
+const JAVA_EXTENSIONS = new Set(['.java']);
+const TYPE_DECLARATIONS = new Set(['class_declaration', 'interface_declaration', 'enum_declaration', 'record_declaration', 'annotation_type_declaration', 'annotation_type_declaration']);
+const MEMBER_DECLARATIONS = new Set(['method_declaration', 'constructor_declaration', 'field_declaration']);
+const IMPORT_DECLARATIONS = new Set(['import_declaration']);
+const CALL_DECLARATIONS = new Set(['method_invocation']);
+const MAX_SNIPPET_BYTES = 240;
+export function scanJavaFiles(files) {
+    const nodes = [];
+    const edges = [];
+    const failedPaths = [];
+    const diagnostics = [];
+    for (const file of files) {
+        if (!isJava(file.path))
+            continue;
+        const parsed = parseSource(file.absolutePath, file.source);
+        if (!parsed || parsed.language !== 'java') {
+            failedPaths.push(file.path);
+            diagnostics.push(`${file.path}: Java parser failed; retaining prior facts`);
+            continue;
+        }
+        if (containsError(parsed.tree.rootNode)) {
+            failedPaths.push(file.path);
+            diagnostics.push(`${file.path}: Java source contains a parse error; retaining prior facts`);
+            continue;
+        }
+        const sourceBuffer = Buffer.from(file.source, 'utf8');
+        const fileKey = factKey(file.path, 'file', 0, sourceBuffer.length);
+        nodes.push(makeNode(file, fileKey, parsed, 'file', 'file', file.path, parsed.tree.rootNode, sourceBuffer, { language: 'java' }));
+        walk(parsed.tree.rootNode, [], [], fileKey, file, parsed, sourceBuffer, nodes, edges);
+    }
+    return { nodes, edges, failedPaths, diagnostics };
+}
+async function scanJavaFilesInBatches(files) {
+    const javaFiles = files.filter((file) => isJava(file.path));
+    const results = await runBatchedWorkers(javaFiles, new URL('./javaScanWorker.js', import.meta.url), (batch) => batch);
+    return {
+        nodes: results.flatMap((result) => result.nodes),
+        edges: results.flatMap((result) => result.edges),
+        failedPaths: results.flatMap((result) => result.failedPaths ?? []),
+        diagnostics: results.flatMap((result) => result.diagnostics ?? [])
+    };
+}
+export const JavaScannerPlugin = {
+    name: JAVA_SCANNER_PLUGIN_NAME,
+    apiVersion: 1,
+    capabilities: ['file-scanner'],
+    scan: (context) => scanJavaFilesInBatches(context.files),
+    scanIncremental: (context, delta, previous) => scanJavaIncremental(context, delta, previous)
+};
+async function scanJavaIncremental(context, delta, previous) {
+    if (!previous)
+        return { ...(await scanJavaFilesInBatches(context.files)), retractions: { nodes: [], edges: [] } };
+    const changed = delta.full
+        ? new Set(previous.nodes.flatMap((node) => typeof node.metadata.filePath === 'string' ? [node.metadata.filePath] : []).concat(context.files.filter((file) => isJava(file.path)).map((file) => file.path)))
+        : new Set([...delta.changedPaths, ...delta.deletedPaths].filter(isJava));
+    if (changed.size === 0)
+        return { nodes: [], edges: [], retractions: { nodes: [], edges: [] } };
+    const result = await scanJavaFilesInBatches(context.files.filter((file) => changed.has(file.path)));
+    const failed = new Set(result.failedPaths ?? []);
+    const retractions = { nodes: [], edges: [] };
+    for (const node of previous.nodes) {
+        const filePath = typeof node.metadata.filePath === 'string' ? node.metadata.filePath : undefined;
+        if (filePath && changed.has(filePath) && !failed.has(filePath))
+            retractions.nodes.push(String(node.metadata.factKey ?? ''));
+    }
+    for (const edge of previous.edges) {
+        const filePath = typeof edge.metadata.filePath === 'string' ? edge.metadata.filePath : undefined;
+        if (filePath && changed.has(filePath) && !failed.has(filePath))
+            retractions.edges.push(String(edge.metadata.factKey ?? ''));
+    }
+    return { ...result, retractions };
+}
+function walk(node, symbols, graph, fileKey, file, parsed, sourceBuffer, nodes, edges) {
+    // Java permits several variable declarators in one field declaration (for
+    // example, `int first, second`). Each declarator is a distinct graph field;
+    // the parent field_declaration is only a syntax container and must not cause
+    // the later declarators to be dropped.
+    if (node.type === 'field_declaration') {
+        const declarators = node.namedChildren.filter((child) => child.type === 'variable_declarator');
+        if (declarators.length > 0) {
+            for (const declarator of declarators) {
+                walkFieldDeclarator(declarator, node, symbols, graph, fileKey, file, parsed, sourceBuffer, nodes, edges);
+            }
+            return;
+        }
+    }
+    const kind = kindFor(node);
+    let currentKey;
+    let nextSymbols = symbols;
+    let nextGraph = graph;
+    if (kind) {
+        const name = nameFor(node, sourceBuffer);
+        currentKey = factKey(file.path, kind, node.startIndex, node.endIndex);
+        const metadata = metadataFor(node, sourceBuffer, name);
+        nodes.push(makeNode(file, currentKey, parsed, kind, node.type, name, node, sourceBuffer, metadata));
+        const parent = graph.at(-1) ?? fileKey;
+        edges.push({ factKey: `contains:${file.path}:${node.startIndex}:${node.endIndex}`, sourceFactKey: parent, targetFactKey: currentKey, filePath: file.path, kind: kind === 'symbol' && symbols.length === 0 ? 'defines' : 'contains', metadata: { discoveredFrom: node.type } });
+        if (kind === 'import')
+            edges.push({ factKey: `imports:${file.path}:${node.startIndex}:${node.endIndex}`, sourceFactKey: fileKey, targetFactKey: currentKey, filePath: file.path, kind: 'imports', confidence: 0.9, metadata: { module: metadata.module, static: metadata.static, wildcard: metadata.wildcard } });
+        if (kind === 'call')
+            edges.push({ factKey: `calls:${file.path}:${node.startIndex}:${node.endIndex}`, sourceFactKey: symbols.at(-1) ?? fileKey, targetFactKey: currentKey, filePath: file.path, kind: 'calls', confidence: 0.65, metadata: { callee: name, syntaxOnly: true } });
+        if (kind === 'symbol') {
+            if (isPublic(node, sourceBuffer) && (symbols.length === 0 || containingTypesAccessible(node, sourceBuffer))) {
+                const exportKey = factKey(file.path, 'export', node.startIndex, node.endIndex);
+                nodes.push(makeNode(file, exportKey, parsed, 'export', 'java-public-export', name, node, sourceBuffer, { exportKind: 'java-public', symbol: name }));
+                edges.push({ factKey: `exports:${file.path}:${node.startIndex}:${node.endIndex}`, sourceFactKey: fileKey, targetFactKey: exportKey, filePath: file.path, kind: 'exports', metadata: { symbol: name, syntaxOnly: true } });
+            }
+            nextSymbols = [...symbols, currentKey];
+        }
+        nextGraph = [...graph, currentKey];
+    }
+    for (const child of node.namedChildren)
+        walk(child, nextSymbols, nextGraph, fileKey, file, parsed, sourceBuffer, nodes, edges);
+}
+function walkFieldDeclarator(declarator, declaration, symbols, graph, fileKey, file, parsed, sourceBuffer, nodes, edges) {
+    const currentKey = factKey(file.path, 'symbol', declarator.startIndex, declarator.endIndex);
+    const name = nameFor(declarator, sourceBuffer);
+    const metadata = metadataFor(declarator, sourceBuffer, name, declaration);
+    nodes.push(makeNode(file, currentKey, parsed, 'symbol', 'field_declaration', name, declarator, sourceBuffer, metadata));
+    const parent = graph.at(-1) ?? fileKey;
+    edges.push({ factKey: `contains:${file.path}:${declarator.startIndex}:${declarator.endIndex}`, sourceFactKey: parent, targetFactKey: currentKey, filePath: file.path, kind: symbols.length === 0 ? 'defines' : 'contains', metadata: { discoveredFrom: 'field_declaration' } });
+    if (isPublic(declaration, sourceBuffer) && (symbols.length === 0 || containingTypesAccessible(declaration, sourceBuffer))) {
+        const exportKey = factKey(file.path, 'export', declarator.startIndex, declarator.endIndex);
+        nodes.push(makeNode(file, exportKey, parsed, 'export', 'java-public-export', name, declarator, sourceBuffer, { exportKind: 'java-public', symbol: name }));
+        edges.push({ factKey: `exports:${file.path}:${declarator.startIndex}:${declarator.endIndex}`, sourceFactKey: fileKey, targetFactKey: exportKey, filePath: file.path, kind: 'exports', metadata: { symbol: name, syntaxOnly: true } });
+    }
+    for (const child of declarator.namedChildren)
+        walk(child, [...symbols, currentKey], [...graph, currentKey], fileKey, file, parsed, sourceBuffer, nodes, edges);
+}
+function kindFor(node) {
+    if (TYPE_DECLARATIONS.has(node.type) || MEMBER_DECLARATIONS.has(node.type))
+        return 'symbol';
+    if (IMPORT_DECLARATIONS.has(node.type))
+        return 'import';
+    if (CALL_DECLARATIONS.has(node.type))
+        return 'call';
+    return undefined;
+}
+function nameFor(node, source) {
+    const name = node.childForFieldName('name');
+    if (name)
+        return textFor(name, source).trim();
+    if (node.type === 'field_declaration') {
+        const declarator = node.childForFieldName('declarator') ?? node.namedChildren.find((child) => child.type === 'variable_declarator');
+        return declarator?.childForFieldName('name') ? textFor(declarator.childForFieldName('name'), source).trim() : null;
+    }
+    if (node.type === 'import_declaration')
+        return textFor(node, source).replace(/^import\s+(?:static\s+)?/u, '').replace(/;\s*$/u, '').trim();
+    if (node.type === 'method_invocation')
+        return textFor(name ?? node.childForFieldName('object') ?? node, source).trim().slice(0, 120);
+    return null;
+}
+function metadataFor(node, source, name, visibilityNode = node) {
+    const snippet = textFor(node, source).trim().slice(0, MAX_SNIPPET_BYTES);
+    if (node.type === 'import_declaration') {
+        const raw = textFor(node, source).trim().replace(/^import\s+/u, '').replace(/;\s*$/u, '');
+        const isStatic = raw.startsWith('static ');
+        const module = (isStatic ? raw.slice(7) : raw).replace(/\.\*$/u, '');
+        return { module, static: isStatic, wildcard: raw.endsWith('.*'), snippet };
+    }
+    if (node.type === 'method_invocation')
+        return { callee: name, snippet, syntaxOnly: true };
+    return { snippet, visibility: visibilityFor(visibilityNode, source) };
+}
+function isPublic(node, source) {
+    const modifiers = node.childForFieldName('modifiers') ?? node.namedChildren.find((child) => child.type === 'modifiers');
+    return Boolean(modifiers && /\bpublic\b/u.test(textFor(modifiers, source)));
+}
+function containingTypesAccessible(node, source) {
+    let parent = node.parent;
+    while (parent) {
+        if (TYPE_DECLARATIONS.has(parent.type) && !isPublic(parent, source))
+            return false;
+        parent = parent.parent;
+    }
+    return true;
+}
+function visibilityFor(node, source) {
+    const modifiers = node.childForFieldName('modifiers') ?? node.namedChildren.find((child) => child.type === 'modifiers');
+    const value = modifiers ? textFor(modifiers, source) : '';
+    if (/\bpublic\b/u.test(value))
+        return 'public';
+    if (/\bprotected\b/u.test(value))
+        return 'protected';
+    if (/\bprivate\b/u.test(value))
+        return 'private';
+    return 'package';
+}
+function makeNode(file, key, parsed, kind, type, name, treeNode, source, metadata) {
+    return { factKey: key, filePath: file.path, kind, type, name, startByte: treeNode.startIndex, endByte: treeNode.endIndex, startPoint: treeNode.startPosition, endPoint: treeNode.endPosition, sourceHash: file.hash, parser: parsed.parser, parserVersion: parsed.parserVersion, metadata: { ...metadata, filePath: file.path, factKey: key, sourceBytes: source.length } };
+}
+function factKey(filePath, kind, startByte, endByte) { return `${kind}:${filePath}:${startByte}:${endByte}`; }
+function textFor(node, source) { return source.subarray(node.startIndex, node.endIndex).toString('utf8'); }
+function containsError(node) { return Boolean(node.hasError) || node.type === 'ERROR' || node.namedChildren.some(containsError); }
+function isJava(filePath) { return JAVA_EXTENSIONS.has(filePath.slice(filePath.lastIndexOf('.')).toLowerCase()); }
+//# sourceMappingURL=javaPlugin.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=javaScanWorker.d.ts.map

package/dist/src/scanner/javaScanWorker.js

@@ -0,0 +1,8 @@
+import { parentPort } from 'node:worker_threads';
+import { scanJavaFiles } from './javaPlugin.js';
+if (!parentPort)
+    throw new Error('Java scan worker requires a parent port');
+parentPort.on('message', (files) => {
+    parentPort.postMessage(scanJavaFiles(files));
+});
+//# sourceMappingURL=javaScanWorker.js.map

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

@@ -0,0 +1,17 @@
+interface ParseFileTask {
+    path: string;
+    absolutePath: string;
+    source: string;
+    hash: string;
+}
+export interface PackageParseTask {
+    repositoryId: string;
+    files: ParseFileTask[];
+}
+export interface PackageImport {
+    path: string;
+    id: string;
+    module: string;
+}
+export {};
+//# sourceMappingURL=packageParseWorker.d.ts.map

package/dist/src/scanner/packageParseWorker.js

@@ -0,0 +1,30 @@
+import { parentPort } from 'node:worker_threads';
+import { extractGraph, hashParts } from '../graph/extract.js';
+import { parseSource } from '../parser/treeSitter.js';
+if (!parentPort)
+    throw new Error('package parse worker requires a parent port');
+parentPort.on('message', ({ repositoryId, files }) => {
+    const imports = [];
+    for (const file of files) {
+        const parsed = parseSource(file.absolutePath, file.source);
+        if (!parsed)
+            continue;
+        const extracted = extractGraph({
+            repositoryId,
+            fileId: hashParts([repositoryId, file.path]),
+            relativePath: file.path,
+            source: file.source,
+            sourceHash: file.hash,
+            parseResult: parsed
+        });
+        for (const node of extracted.nodes) {
+            if (node.kind !== 'import')
+                continue;
+            const module = typeof node.metadata.module === 'string' ? node.metadata.module : node.name;
+            if (module)
+                imports.push({ path: file.path, id: node.id, module });
+        }
+    }
+    parentPort.postMessage(imports);
+});
+//# sourceMappingURL=packageParseWorker.js.map

package/dist/src/scanner/packagePlugin.js

@@ -1,6 +1,7 @@
 import { builtinModules } from 'node:module';
-import { extractGraph, hashParts } from '../graph/extract.js';
-import { parseSource } from '../parser/treeSitter.js';
+import { availableParallelism } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import { hashParts } from '../graph/extract.js';
 import { BUILTIN_GRAPH_PLUGIN } from './plugins.js';
 // This plugin adds package-level relationships on top of the built-in source
 // graph. Built-in extraction already creates file/import/symbol nodes; this
@@ -41,11 +42,46 @@ function packageRoot(specifier) {
 function isManifest(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+const MAX_PARSE_WORKERS = 8;
+async function parseImportsInBatches(repositoryId, files) {
+    const sourceFiles = files.filter((file) => !file.path.toLowerCase().endsWith('.java'));
+    if (sourceFiles.length === 0)
+        return [];
+    const workerCount = Math.min(Math.max(1, availableParallelism() - 1), MAX_PARSE_WORKERS, sourceFiles.length);
+    const batchSize = Math.ceil(sourceFiles.length / workerCount);
+    const batches = Array.from({ length: workerCount }, (_, index) => sourceFiles.slice(index * batchSize, (index + 1) * batchSize));
+    const results = await Promise.all(batches.map((batch) => runParseWorker({ repositoryId, files: batch })));
+    return results.flat();
+}
+function runParseWorker(task) {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(new URL('./packageParseWorker.js', import.meta.url), {
+            // Test-runner and eval flags are not valid worker entry-point flags.
+            execArgv: [],
+            env: { ...process.env, NODE_OPTIONS: '' }
+        });
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            callback();
+            void worker.terminate();
+        };
+        worker.once('message', (imports) => finish(() => resolve(imports)));
+        worker.once('error', (error) => finish(() => reject(error)));
+        worker.once('exit', (code) => {
+            if (code !== 0)
+                finish(() => reject(new Error(`package parse worker exited with code ${code}`)));
+        });
+        worker.postMessage(task);
+    });
+}
 export const PackagePlugin = {
     name: 'package-plugin',
     apiVersion: 1,
     capabilities: ['repository-analyzer'],
-    scan: (context) => {
+    scan: async (context) => {
         let manifest;
         try {
             manifest = JSON.parse(context.readFile('package.json'));
@@ -81,28 +117,8 @@ export const PackagePlugin = {
         // Re-run the same extraction used by the built-in scanner. The resulting
         // import IDs are stable graph node IDs, so they can be used directly as
         // targets when targetPlugin is BUILTIN_GRAPH_PLUGIN.
-        const imports = [];
         const repositoryId = hashParts(['repository', context.repoPath]);
-        for (const file of context.files) {
-            const parsed = parseSource(file.absolutePath, file.source);
-            if (!parsed)
-                continue;
-            const extracted = extractGraph({
-                repositoryId,
-                fileId: hashParts([repositoryId, file.path]),
-                relativePath: file.path,
-                source: file.source,
-                sourceHash: file.hash,
-                parseResult: parsed
-            });
-            for (const node of extracted.nodes) {
-                if (node.kind !== 'import')
-                    continue;
-                const module = typeof node.metadata.module === 'string' ? node.metadata.module : node.name;
-                if (module)
-                    imports.push({ path: file.path, id: node.id, module });
-            }
-        }
+        const imports = await parseImportsInBatches(repositoryId, context.files);
         // A package is represented once even when it is imported by many files or
         // through many subpaths. `implied` records imports that are not declared in
         // any dependency section of package.json.
@@ -163,6 +179,49 @@ export const PackagePlugin = {
                 }];
         });
         return { nodes, edges, diagnostics };
+    },
+    scanIncremental: async (context, delta, previous) => {
+        if (delta.full || !previous)
+            return await PackagePlugin.scan(context);
+        const changed = new Set(delta.changedPaths);
+        const removed = new Set(delta.deletedPaths);
+        const changedResult = await PackagePlugin.scan({ ...context, files: context.files.filter((file) => changed.has(file.path)) });
+        const retainedEdges = previous.edges.flatMap((edge) => {
+            const filePath = typeof edge.metadata.filePath === 'string' ? edge.metadata.filePath : undefined;
+            const factKey = typeof edge.metadata.factKey === 'string' ? edge.metadata.factKey : undefined;
+            if (!filePath || !factKey || changed.has(filePath) || removed.has(filePath))
+                return [];
+            return [{
+                    factKey,
+                    sourceFactKey: typeof edge.metadata.package === 'string' ? `package:${edge.metadata.package}` : edge.sourceId,
+                    targetFactKey: edge.targetId,
+                    targetPlugin: BUILTIN_GRAPH_PLUGIN,
+                    filePath,
+                    kind: edge.kind,
+                    confidence: edge.confidence,
+                    metadata: Object.fromEntries(Object.entries(edge.metadata).filter(([key]) => key !== 'factKey' && key !== 'plugin'))
+                }];
+        });
+        const edges = [...retainedEdges, ...changedResult.edges];
+        const packageNames = new Set(edges.flatMap((edge) => typeof edge.metadata?.package === 'string' ? [edge.metadata.package] : []));
+        const changedNodes = new Map(changedResult.nodes.map((node) => [node.factKey, node]));
+        const nodes = [...packageNames].sort().flatMap((name) => {
+            const factKey = `package:${name}`;
+            const current = changedNodes.get(factKey);
+            if (current)
+                return [current];
+            const previousNode = previous.nodes.find((node) => node.metadata.factKey === factKey);
+            if (!previousNode)
+                return [];
+            return [{
+                    factKey,
+                    kind: previousNode.kind,
+                    type: previousNode.type,
+                    name: previousNode.name,
+                    metadata: Object.fromEntries(Object.entries(previousNode.metadata).filter(([key]) => key !== 'factKey' && key !== 'plugin'))
+                }];
+        });
+        return { nodes, edges, ...(changedResult.diagnostics ? { diagnostics: changedResult.diagnostics } : {}) };
     }
 };
 //# sourceMappingURL=packagePlugin.js.map

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

@@ -0,0 +1,2 @@
+export declare function runBatchedWorkers<T, R>(items: readonly T[], workerUrl: URL, createTask: (batch: T[]) => unknown): Promise<R[]>;
+//# sourceMappingURL=parallelScan.d.ts.map

package/dist/src/scanner/parallelScan.js

@@ -0,0 +1,32 @@
+import { availableParallelism } from 'node:os';
+import { Worker } from 'node:worker_threads';
+const MAX_SCAN_WORKERS = 8;
+export async function runBatchedWorkers(items, workerUrl, createTask) {
+    if (items.length === 0)
+        return [];
+    const workerCount = Math.min(Math.max(1, availableParallelism() - 1), MAX_SCAN_WORKERS, items.length);
+    const batchSize = Math.ceil(items.length / workerCount);
+    const batches = Array.from({ length: workerCount }, (_, index) => items.slice(index * batchSize, (index + 1) * batchSize));
+    return Promise.all(batches.map((batch) => runWorker(workerUrl, createTask(batch))));
+}
+function runWorker(workerUrl, task) {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(workerUrl, { execArgv: [], env: { ...process.env, NODE_OPTIONS: '' } });
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            callback();
+            void worker.terminate();
+        };
+        worker.once('message', (result) => finish(() => resolve(result)));
+        worker.once('error', (error) => finish(() => reject(error)));
+        worker.once('exit', (code) => {
+            if (code !== 0)
+                finish(() => reject(new Error(`scanner worker exited with code ${code}`)));
+        });
+        worker.postMessage(task);
+    });
+}
+//# sourceMappingURL=parallelScan.js.map

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

@@ -1,4 +1,5 @@
 import type { FileRecord, GraphEdge, GraphNode, GraphExtractionResult, Point } from '../types.js';
+import { type RepositoryManifest } from './artifactInventory.js';
 export declare const SCANNER_PLUGIN_API_VERSION: 1;
 export type PluginConflictPolicy = 'merge' | 'replace' | 'reject';
 export type ScannerCapability = 'file-scanner' | 'repository-analyzer';
@@ -10,6 +11,8 @@ export interface RepositoryScanContext {
     repoPath: string;
     files: readonly RepositoryScanFile[];
     discoveredPaths: readonly string[];
+    /** Bounded root/immediate-module Maven and Gradle inventory. */
+    manifests: readonly RepositoryManifest[];
     readFile(relativePath: string): string;
 }
 export interface PluginNodeFact {
@@ -50,6 +53,29 @@ export interface PluginScanResult {
     nodes: PluginNodeFact[];
     edges: PluginEdgeFact[];
     diagnostics?: string[];
+    /** Paths whose previous contribution must be retained after a failed replacement. */
+    failedPaths?: string[];
+}
+/** Optional v1-compatible extension for plugins that can reconcile a repository delta. */
+export interface RepositoryScanDelta {
+    changedPaths: readonly string[];
+    deletedPaths: readonly string[];
+    /** Additive repository-artifact delta fields; source-only plugins may ignore them. */
+    changedManifests?: readonly string[];
+    deletedManifests?: readonly string[];
+    manifestsComplete?: boolean;
+    full: boolean;
+}
+export interface PreviousPluginContribution {
+    nodes: readonly GraphNode[];
+    edges: readonly GraphEdge[];
+}
+export interface IncrementalPluginScanResult extends PluginScanResult {
+    /** Fact keys replaced by this delta when a plugin elects not to return a complete contribution. */
+    retractions?: {
+        nodes?: string[];
+        edges?: string[];
+    };
 }
 export interface PluginResourceLimits {
     maxNodes: number;
@@ -71,9 +97,13 @@ export interface ScannerPlugin {
     scan(context: RepositoryScanContext): PluginScanResult | Promise<PluginScanResult>;
     finalize?(context: RepositoryScanContext): PluginScanResult | void | Promise<PluginScanResult | void>;
     dispose?(context: RepositoryScanContext): void | Promise<void>;
+    /** Opt-in delta hook. Plugins without it retain the complete-repository v1 scan contract. */
+    scanIncremental?(context: RepositoryScanContext, delta: RepositoryScanDelta, previous?: PreviousPluginContribution): IncrementalPluginScanResult | Promise<IncrementalPluginScanResult>;
 }
 export interface PluginRunResult extends GraphExtractionResult {
     diagnostics: string[];
+    /** Per-file failures are degraded but do not make the complete plugin stale. */
+    failedPaths?: string[];
     failedPlugins: string[];
     successfulPlugins?: string[];
     pluginContributions?: Map<string, {
@@ -81,6 +111,6 @@ export interface PluginRunResult extends GraphExtractionResult {
         edges: GraphEdge[];
     }>;
 }
-export declare function createRepositoryScanContext(repoPath: string): RepositoryScanContext;
-export declare function runScannerPlugins(context: RepositoryScanContext, plugins: readonly ScannerPlugin[], resourceLimits?: Partial<PluginResourceLimits>): Promise<PluginRunResult>;
+export declare function createRepositoryScanContext(repoPath: string, suppliedManifests?: readonly RepositoryManifest[]): RepositoryScanContext;
+export declare function runScannerPlugins(context: RepositoryScanContext, plugins: readonly ScannerPlugin[], resourceLimits?: Partial<PluginResourceLimits>, delta?: RepositoryScanDelta, previousContributions?: ReadonlyMap<string, PreviousPluginContribution>): Promise<PluginRunResult>;
 //# sourceMappingURL=plugins.d.ts.map

package/dist/src/scanner/plugins.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { discoverSourceFiles } from './discover.js';
+import { inventoryRepositoryManifests } from './artifactInventory.js';
 export const SCANNER_PLUGIN_API_VERSION = 1;
 export const DEFAULT_PLUGIN_RESOURCE_LIMITS = {
     maxNodes: 100_000,
@@ -16,8 +17,9 @@ const GRAPH_NODE_KINDS = new Set(['file', 'symbol', 'import', 'export', 'call',
 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) {
+export function createRepositoryScanContext(repoPath, suppliedManifests) {
     const discoveredPaths = discoverSourceFiles(repoPath);
+    const manifests = suppliedManifests ? [...suppliedManifests] : inventoryRepositoryManifests(repoPath);
     const files = discoveredPaths.flatMap((relativePath) => {
         try {
             const absolutePath = path.join(repoPath, relativePath);
@@ -38,23 +40,31 @@ export function createRepositoryScanContext(repoPath) {
             return [];
         }
     });
-    return { repoPath, files, discoveredPaths, readFile: (relativePath) => readFileSync(path.join(repoPath, relativePath), 'utf8') };
+    return { repoPath, files, discoveredPaths, manifests, readFile: (relativePath) => readFileSync(path.join(repoPath, relativePath), 'utf8') };
 }
-export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
+export async function runScannerPlugins(context, plugins, resourceLimits = {}, delta, previousContributions = new Map()) {
     const limits = normalizePluginResourceLimits(resourceLimits);
     const nodes = [];
     const edges = [];
     const diagnostics = [];
     const failedPlugins = [];
+    const failedPaths = new Set();
     const successfulPlugins = [];
+    const incrementalRetractions = new Map();
     const owners = new Map();
     for (const plugin of plugins) {
         try {
             validatePlugin(plugin);
             await plugin.initialize?.(context);
-            const result = await plugin.scan(context);
+            const result = plugin.scanIncremental && delta
+                ? await plugin.scanIncremental(context, delta, previousContributions.get(plugin.name))
+                : await plugin.scan(context);
             const finalized = await plugin.finalize?.(context);
+            if (plugin.scanIncremental && delta && 'retractions' in result && result.retractions)
+                incrementalRetractions.set(plugin.name, result.retractions);
             validatePluginResult(plugin.name, result, 'scan');
+            for (const failedPath of result.failedPaths ?? [])
+                failedPaths.add(failedPath);
             if (finalized !== undefined)
                 validatePluginResult(plugin.name, finalized, 'finalize');
             enforceResourceLimits(plugin, result, finalized, limits);
@@ -86,6 +96,15 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         return [canonicalNodeIdentity(node.pluginName ?? '', node.factKey), materialized];
     }));
     const materializedNodes = [...nodeByIdentity.values()];
+    for (const [plugin, retractions] of incrementalRetractions) {
+        const previous = previousContributions.get(plugin);
+        const retractedNodeKeys = new Set(retractions.nodes ?? []);
+        for (const node of previous?.nodes ?? []) {
+            const factKey = String(node.metadata.factKey ?? '');
+            if (factKey && !retractedNodeKeys.has(factKey))
+                nodeByIdentity.set(canonicalNodeIdentity(plugin, factKey), node);
+        }
+    }
     const materializedEdges = [];
     for (const edge of edges) {
         const sourceIdentity = canonicalNodeIdentity(edge.sourcePlugin ?? edge.pluginName ?? '', edge.sourceFactKey);
@@ -126,6 +145,33 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         if (plugin)
             contributionFor(plugin).edges.push(edge);
     }
+    for (const [plugin, retractions] of incrementalRetractions) {
+        const previous = previousContributions.get(plugin);
+        if (!previous)
+            continue;
+        const current = contributionFor(plugin);
+        const nodeKeys = new Set(retractions.nodes ?? []);
+        const edgeKeys = new Set(retractions.edges ?? []);
+        const currentNodeKeys = new Set(current.nodes.map((node) => String(node.metadata.factKey ?? '')));
+        const currentEdgeKeys = new Set(current.edges.map((edge) => String(edge.metadata.factKey ?? '')));
+        current.nodes = [
+            ...previous.nodes.filter((node) => !nodeKeys.has(String(node.metadata.factKey ?? '')) && !currentNodeKeys.has(String(node.metadata.factKey ?? ''))),
+            ...current.nodes
+        ];
+        current.edges = [
+            ...previous.edges.filter((edge) => !edgeKeys.has(String(edge.metadata.factKey ?? '')) && !currentEdgeKeys.has(String(edge.metadata.factKey ?? ''))),
+            ...current.edges
+        ];
+    }
+    const partiallyReconciledPlugins = new Set(incrementalRetractions.keys());
+    const mergedNodes = [
+        ...materializedNodes.filter((node) => !partiallyReconciledPlugins.has(String(node.metadata.plugin ?? ''))),
+        ...[...partiallyReconciledPlugins].flatMap((plugin) => pluginContributions.get(plugin)?.nodes ?? [])
+    ];
+    const mergedEdges = [
+        ...materializedEdges.filter((edge) => !partiallyReconciledPlugins.has(String(edge.metadata.plugin ?? ''))),
+        ...[...partiallyReconciledPlugins].flatMap((plugin) => pluginContributions.get(plugin)?.edges ?? [])
+    ];
     function contributionFor(plugin) {
         const existing = pluginContributions.get(plugin);
         if (existing)
@@ -134,7 +180,7 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         pluginContributions.set(plugin, created);
         return created;
     }
-    return { nodes: materializedNodes, edges: materializedEdges, diagnostics, failedPlugins, successfulPlugins, pluginContributions };
+    return { nodes: mergedNodes, edges: mergedEdges, diagnostics, failedPaths: [...failedPaths].sort(), 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);

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

@@ -0,0 +1,5 @@
+import type { PluginScanResult, RepositoryScanFile, ScannerPlugin } from './plugins.js';
+export declare const PYTHON_SCANNER_PLUGIN_NAME = "python-scanner-plugin";
+export declare function scanPythonFiles(files: readonly RepositoryScanFile[]): PluginScanResult;
+export declare const PythonScannerPlugin: ScannerPlugin;
+//# sourceMappingURL=pythonPlugin.d.ts.map