@psnext/lscg 0.1.2 → 0.1.4

package/dist/src/scanner/packagePlugin.js

@@ -0,0 +1,168 @@
+import { builtinModules } from 'node:module';
+import { extractGraph, hashParts } from '../graph/extract.js';
+import { parseSource } from '../parser/treeSitter.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
+// plugin creates package nodes and connects them to the existing import nodes.
+//
+// The important identity rule for edges is:
+// - package nodes use this plugin's fact-key namespace (`package:<name>`), and
+// - built-in nodes are referenced by their final graph ID with
+//   `targetPlugin: BUILTIN_GRAPH_PLUGIN`.
+//
+// Keep that distinction in mind when repointing an edge to another existing
+// node. Do not use the package node's eventual database ID as its fact key.
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const BUILTINS = new Set(builtinModules.flatMap((name) => [name, name.replace(/^node:/, ''), `node:${name.replace(/^node:/, '')}`]));
+/**
+ * Converts an import specifier into its package root.
+ *
+ * Examples:
+ *   react                  -> react
+ *   lodash/map             -> lodash
+ *   @scope/library/tool    -> @scope/library
+ *   ./local-file           -> undefined
+ *   node:fs                -> undefined
+ *
+ * Returning the root is what lets several imports share one package node.
+ */
+function packageRoot(specifier) {
+    if (!specifier || specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('#') || /^[a-z][a-z\d+.-]*:/i.test(specifier))
+        return undefined;
+    if (BUILTINS.has(specifier))
+        return undefined;
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined;
+    }
+    return specifier.split('/')[0];
+}
+function isManifest(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export const PackagePlugin = {
+    name: 'package-plugin',
+    apiVersion: 1,
+    capabilities: ['repository-analyzer'],
+    scan: (context) => {
+        let manifest;
+        try {
+            manifest = JSON.parse(context.readFile('package.json'));
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                return { nodes: [], edges: [] };
+            }
+            throw new Error(`invalid package.json: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!isManifest(manifest))
+            throw new Error('invalid package.json: expected an object');
+        const diagnostics = [];
+        const declarations = new Map();
+        for (const section of DEPENDENCY_SECTIONS) {
+            const entries = manifest[section];
+            if (entries === undefined)
+                continue;
+            if (!isManifest(entries)) {
+                diagnostics.push(`${section} must be an object`);
+                continue;
+            }
+            for (const [name, version] of Object.entries(entries)) {
+                if (typeof version !== 'string') {
+                    diagnostics.push(`${section}.${name} must be a string`);
+                    continue;
+                }
+                const list = declarations.get(name) ?? [];
+                list.push({ section, version });
+                declarations.set(name, list);
+            }
+        }
+        // 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 });
+            }
+        }
+        // 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.
+        const usedPackages = new Map();
+        for (const entry of imports) {
+            const root = packageRoot(entry.module);
+            if (!root)
+                continue;
+            if (!usedPackages.has(root))
+                usedPackages.set(root, { implied: !declarations.has(root) });
+        }
+        const packageNames = new Set(usedPackages.keys());
+        const nodes = [...packageNames].sort().map((name) => {
+            // This fact key is local to PackagePlugin. The scanner host later
+            // materializes it as hashParts(['plugin-node', 'package-plugin', factKey]).
+            const packageDeclarations = declarations.get(name) ?? [];
+            const implied = !declarations.has(name);
+            const versions = new Set(packageDeclarations.map((declaration) => declaration.version));
+            if (versions.size > 1)
+                diagnostics.push(`${name} has conflicting declared versions`);
+            return {
+                factKey: `package:${name}`,
+                kind: 'package',
+                type: 'package',
+                name,
+                metadata: {
+                    manifest: 'package.json',
+                    packageName: name,
+                    implied,
+                    declarations: packageDeclarations
+                }
+            };
+        });
+        const edges = imports.flatMap((entry) => {
+            const name = packageRoot(entry.module);
+            if (!name || !packageNames.has(name))
+                return [];
+            // The source is a node emitted by this plugin, so sourceFactKey uses
+            // PackagePlugin's namespace and can be resolved as `package:<name>`.
+            //
+            // The target is an existing node emitted by the built-in graph scanner.
+            // `entry.id` is that node's final graph ID, not a plugin fact key. The
+            // explicit built-in namespace tells the scanner host to use the ID
+            // directly instead of looking for a PackagePlugin node with that key.
+            //
+            // To repoint this edge to another existing built-in node, replace
+            // `targetFactKey` with that node's ID and keep
+            // `targetPlugin: BUILTIN_GRAPH_PLUGIN`. For a node from another plugin,
+            // use that plugin's name in targetPlugin and its factKey in targetFactKey.
+            return [{
+                    factKey: `provides:${name}:${entry.path}:${entry.id}`,
+                    sourceFactKey: `package:${name}`,
+                    targetFactKey: entry.id,
+                    targetPlugin: BUILTIN_GRAPH_PLUGIN,
+                    filePath: entry.path,
+                    kind: 'provides',
+                    metadata: { module: entry.module, package: name, implied: !declarations.has(name) }
+                }];
+        });
+        return { nodes, edges, diagnostics };
+    }
+};
+//# sourceMappingURL=packagePlugin.js.map

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