@psnext/lscg 0.1.4 → 0.1.6

package/dist/src/scanner/javaDependencyPlugin.js

@@ -0,0 +1,107 @@
+export const JAVA_DEPENDENCY_PLUGIN_NAME = 'java-dependency-plugin';
+const MAX_DECLARATIONS = 10_000;
+export const JavaDependencyPlugin = {
+    name: JAVA_DEPENDENCY_PLUGIN_NAME,
+    apiVersion: 1,
+    capabilities: ['repository-analyzer'],
+    scan: (context) => scanJavaDependencies(context),
+    scanIncremental: (context, _delta, previous) => scanJavaDependenciesIncremental(context, previous)
+};
+export function scanJavaDependencies(context) {
+    const nodes = [];
+    const diagnostics = [];
+    for (const manifest of context.manifests) {
+        if (manifest.status !== 'observed' || manifest.content === null) {
+            if (manifest.status !== 'confirmed_deleted')
+                diagnostics.push(`${manifest.path}: manifest read unavailable (${manifest.status})`);
+            continue;
+        }
+        const parsed = manifest.kind === 'maven-pom' ? parseMaven(manifest) : parseGradle(manifest);
+        nodes.push(...parsed.nodes);
+        diagnostics.push(...parsed.diagnostics);
+    }
+    return { nodes, edges: [], diagnostics };
+}
+function scanJavaDependenciesIncremental(context, previous) {
+    const result = scanJavaDependencies(context);
+    // Repository facts are cheap and bounded, so each incremental run replaces
+    // the complete analyzer contribution. This also handles manifest-only edits
+    // and the final manifest deletion after reopening the database.
+    if (!previous || result.diagnostics?.length) {
+        // A bounded/read/parse failure is not a confirmed deletion. Keep the
+        // previous repository contribution while exposing diagnostics.
+        return { ...result, retractions: { nodes: [], edges: [] } };
+    }
+    return { ...result, retractions: { nodes: previous.nodes.map((node) => String(node.metadata.factKey ?? '')).filter(Boolean), edges: previous.edges.map((edge) => String(edge.metadata.factKey ?? '')).filter(Boolean) } };
+}
+function parseMaven(manifest) {
+    const source = manifest.content ?? '';
+    const diagnostics = [];
+    if (/<!DOCTYPE|<!ENTITY/iu.test(source))
+        return { nodes: [], diagnostics: ['pom.xml rejected DTD/entity expansion'] };
+    if (!/<project\b/iu.test(source) || !/<\/project\s*>/iu.test(source))
+        return { nodes: [], diagnostics: [`${manifest.path}: malformed or unsupported Maven XML`] };
+    const properties = new Map();
+    const propertyBlock = /<properties\b[^>]*>([\s\S]*?)<\/properties>/iu.exec(source)?.[1] ?? '';
+    for (const match of propertyBlock.matchAll(/<([\w.-]+)\s*>([^<]{0,1000})<\/\1\s*>/gu))
+        properties.set(match[1], match[2].trim());
+    const nodes = [];
+    let occurrence = 0;
+    for (const match of source.matchAll(/<dependency\b[^>]*>([\s\S]*?)<\/dependency\s*>/giu)) {
+        if (occurrence >= MAX_DECLARATIONS) {
+            diagnostics.push(`${manifest.path}: dependency declaration limit exceeded`);
+            break;
+        }
+        const block = match[1];
+        const group = xmlTag(block, 'groupId');
+        const artifact = xmlTag(block, 'artifactId');
+        const version = resolveProperty(xmlTag(block, 'version'), properties);
+        const scope = xmlTag(block, 'scope') || 'compile';
+        if (!group || !artifact || !version) {
+            diagnostics.push(`${manifest.path}: unsupported or unresolved Maven dependency at declaration ${occurrence}`);
+            occurrence += 1;
+            continue;
+        }
+        const coordinate = `${group}:${artifact}:${version}`;
+        nodes.push(dependencyNode(manifest, `${manifest.path}\u0000${manifest.moduleIdentity}\u0000${coordinate}\u0000${scope}\u0000${occurrence}`, coordinate, group, artifact, version, scope, occurrence));
+        occurrence += 1;
+    }
+    return { nodes, diagnostics };
+}
+function parseGradle(manifest) {
+    const source = manifest.content ?? '';
+    const diagnostics = [];
+    const nodes = [];
+    let occurrence = 0;
+    // Literal Groovy/Kotlin dependency calls only. No Gradle expressions are evaluated.
+    const pattern = /\b(api|implementation|compileOnly|runtimeOnly|testImplementation|testRuntimeOnly|annotationProcessor|kapt|classpath)\b\s*(?:\(\s*)?['"]([^'"\n]+)['"]\s*\)?/gu;
+    for (const match of source.matchAll(pattern)) {
+        if (occurrence >= MAX_DECLARATIONS) {
+            diagnostics.push(`${manifest.path}: dependency declaration limit exceeded`);
+            break;
+        }
+        const raw = match[2].trim();
+        const parts = raw.split(':');
+        const configuration = match[1].trim();
+        if (parts.length < 3 || parts.slice(0, 3).some((part) => !/^[\w.${}-]+$/u.test(part))) {
+            diagnostics.push(`${manifest.path}: unsupported Gradle dependency declaration ${raw.slice(0, 120)}`);
+            occurrence += 1;
+            continue;
+        }
+        const [group, artifact, version] = parts;
+        const coordinate = `${group}:${artifact}:${version}`;
+        nodes.push(dependencyNode(manifest, `${manifest.path}\u0000${manifest.moduleIdentity}\u0000${coordinate}\u0000${configuration}\u0000${occurrence}`, coordinate, group, artifact, version, configuration, occurrence));
+        occurrence += 1;
+    }
+    if (/\b(?:project|platform|enforcedPlatform|libs\.|version\.catalog|\$\{)/u.test(source))
+        diagnostics.push(`${manifest.path}: dynamic or unsupported Gradle dependency expressions were ignored`);
+    return { nodes, diagnostics };
+}
+function dependencyNode(manifest, factKey, coordinate, group, artifact, version, scope, occurrence) {
+    return { factKey: `java-dependency:${factKey}`, kind: 'package', type: 'java-dependency', name: coordinate, metadata: { dependencyType: 'java-dependency', coordinate, group, artifact, version, scope, configuration: scope, declarationOccurrence: occurrence, manifestPath: manifest.path, manifestKind: manifest.kind, moduleIdentity: manifest.moduleIdentity, sourceHash: manifest.sourceHash } };
+}
+function xmlTag(source, tag) { return new RegExp(`<${tag}\\s*>([^<]{0,1000})<\\/${tag}\\s*>`, 'iu').exec(source)?.[1]?.trim(); }
+function resolveProperty(value, properties) { if (!value)
+    return undefined; const match = /^\$\{([^}]+)\}$/u.exec(value); return match ? properties.get(match[1]) : value; }
+function configurationAt(source, offset) { const line = source.slice(Math.max(0, source.lastIndexOf('\n', offset - 1) + 1), offset); return /\b(\w+)\s*$/u.exec(line)?.[1] ?? 'implementation'; }
+//# sourceMappingURL=javaDependencyPlugin.js.map

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

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

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,7 +1,8 @@
-import type { FileRecord, GraphEdge, GraphNode, GraphExtractionResult, Point } from '../types.js';
+import type { EnrichmentRunnerInput, AttributionOutcome, 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';
+export type ScannerCapability = 'file-scanner' | 'repository-analyzer' | 'enrichment';
 export interface RepositoryScanFile extends FileRecord {
     absolutePath: string;
     source: string;
@@ -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 {
@@ -42,6 +45,7 @@ export interface PluginEdgeFact {
     targetPlugin?: string;
     filePath?: string;
     kind: GraphEdge['kind'];
+    type?: string;
     confidence?: number;
     metadata?: Record<string, unknown>;
     conflict?: PluginConflictPolicy;
@@ -50,6 +54,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,16 +98,23 @@ 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>;
+    /** Optional deferred enrichment hook. The host supplies structural nodes after the file scan. */
+    enrich?(input: EnrichmentRunnerInput): AttributionOutcome | Promise<AttributionOutcome>;
 }
 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, {
         nodes: GraphNode[];
         edges: GraphEdge[];
     }>;
+    enrichmentPlugins?: Map<string, ScannerPlugin>;
 }
-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