@psnext/lscg 0.1.1 → 0.1.3

package/README.md

@@ -56,12 +56,13 @@ npm start -- nodes greet --kind symbol --limit 20
 npm start -- nodes greet --output text
 npm start -- edges --kind calls --limit 20
 npm start -- edges --kind attributed_to --limit 20
+npm start -- edges --output text
 npm start -- neighbors <node-id> --depth 2
 
 # Visualize the graph
 npm start -- view --scope repo
 npm start -- view --scope home --anchor greet --search util
-npm start -- view --output /tmp/lscg-view.svg
+npm start -- view --display icon --output /tmp/lscg-view.svg
 
 # Run a read-only SQL query
 npm start -- query "select kind, count(*) as n from nodes group by kind"
@@ -96,13 +97,16 @@ anchor-centered subgraph for the selected scope when no `--anchor` is provided.
 The browser view includes a toggle to switch between the subgraph and the full
 graph. Pass `--search` to filter within the active graph mode, or `--output
 <path>` to write a static SVG snapshot of the default subgraph instead of
-opening a browser.
+opening a browser. Use `--display simple`, `--display shape` (the default), or
+`--display icon` to choose how nodes are rendered. Simple mode uses colored
+circles, shape mode uses kind-specific shapes, and icon mode loads SVG icons
+from `src/view/templates/icons`.
 
 Examples:
 
 ```bash
 lscg view --anchor greet --search util
-lscg view --output graph.svg
+lscg view --display simple --output graph.svg
 ```
 
 `lscg context <symbol>` is the agent-oriented retrieval workflow. It returns a
@@ -135,6 +139,68 @@ When the repository has git history, `lscg scan` also records contributor user
 nodes keyed by email and tracks the most recent contributor for each discovered
 node.
 
+## Scanner plugins
+
+The library accepts trusted, versioned scanner plugins through the `plugins`
+option on `scanRepository`. A plugin receives a read-only repository context
+with the resolved `repoPath`, discovered files, file contents, and a `readFile`
+helper, then returns semantic node and edge facts. Edges refer to node `factKey` values within their emitting plugin namespace and
+may connect facts from different files. Use the additive `sourcePlugin` and
+`targetPlugin` fields when an endpoint belongs to another plugin; raw fact keys
+are never parsed as namespaces.
+
+```ts
+import { scanRepository, type ScannerPlugin } from '@psnext/lscg';
+
+const plugin: ScannerPlugin = {
+  name: 'my-analyzer',
+  apiVersion: 1,
+  capabilities: ['repository-analyzer'],
+  async scan({ repoPath, files }) {
+    return {
+      nodes: files.map((file) => ({
+        factKey: `artifact:${file.path}`,
+        filePath: file.path,
+        kind: 'symbol',
+        type: 'artifact',
+        name: file.path,
+        metadata: { repoPath }
+      })),
+      edges: []
+    };
+  }
+};
+
+await scanRepository({ root: '/path/to/repo', plugins: [plugin] });
+```
+
+Plugins may implement `initialize`, `scan`, `finalize`, and `dispose` hooks.
+The core assigns deterministic IDs, validates API compatibility, persists
+plugin facts, and reports plugin diagnostics in the scan summary. Plugins run
+in-process and must be treated as trusted code.
+
+Plugin output is bounded by conservative host-selected resource limits. The
+limits cover node and edge fact counts, diagnostics, metadata bytes, and total
+serialized output bytes. Callers can override them with `pluginLimits` on
+`scanRepository`; an oversized plugin contribution is rejected atomically and
+reported in the scan summary, while later plugins can still contribute normally.
+
+The host keeps semantic `factKey` values separate from graph identity. Node
+facts conflict by `(node, factKey)` and edge facts by `(edge, factKey)` across
+plugins. `merge` retains both under distinct plugin-qualified identities,
+`replace` uses priority (then plugin-name order for ties), and `reject` keeps
+the incumbent and reports a diagnostic. The host assigns deterministic IDs;
+plugins do not provide database IDs.
+
+Every scan also runs the bundled `PackagePlugin`. It reads the repository-root
+`package.json` dependency sections (`dependencies`, `devDependencies`,
+`peerDependencies`, and `optionalDependencies`) and creates repository-scoped
+`package` nodes only for package roots used by source imports. A `provides` edge
+connects each package node to its matching `import` node. Undeclared bare
+external imports create `implied` package nodes; relative, absolute, URL, and
+Node built-in imports are excluded. The plugin is de-duplicated if explicitly
+listed in `plugins`.
+
 ## Current parser support
 
 The starter scanner supports JavaScript, JSX, TypeScript, and TSX via

package/dist/src/cli.js

@@ -53,14 +53,24 @@ export async function runCli(argv) {
             }
             throw new Error(`nodes output must be json or text, got: ${output}`);
         }
-        case 'edges':
-            printJson(listEdges({
+        case 'edges': {
+            const edges = listEdges({
                 root: options.root,
                 scope: options.scope ?? 'repo',
                 kind: options.kind,
                 limit: options.limit
-            }));
-            return;
+            });
+            const output = options.output ?? 'json';
+            if (output === 'json') {
+                printJson(edges);
+                return;
+            }
+            if (output === 'text') {
+                console.log(formatEdgesText(edges));
+                return;
+            }
+            throw new Error(`edges output must be json or text, got: ${output}`);
+        }
         case 'neighbors': {
             const nodeId = options._[0] ?? options.nodeId;
             printJson(neighbors({
@@ -140,15 +150,21 @@ export async function runCli(argv) {
             }));
             return;
         }
-        case 'view':
+        case 'view': {
+            const display = options.display ?? 'shape';
+            if (display !== 'simple' && display !== 'shape' && display !== 'icon') {
+                throw new Error(`view display must be simple, shape, or icon, got: ${display}`);
+            }
             printJson(await viewGraph({
                 root: options.root,
                 scope: options.scope ?? 'repo',
                 anchor: options.anchor,
                 search: options.search,
+                display,
                 output: options.output
             }));
             return;
+        }
         case 'mcp':
             await startMcpServer({ root: options.root });
             return;
@@ -274,12 +290,12 @@ function commandHelpText(command) {
         watch: `Usage: lscg watch [options]\n\nKeep the repository current by rescanning on file changes.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo                Repository scope to watch (default: repo).\n\nExamples:\n  lscg watch`,
         status: `Usage: lscg status [options]\n\nShow graph counts and database paths.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n\nExamples:\n  lscg status --scope repo`,
         nodes: `Usage: lscg nodes [term] [options]\n\nList graph nodes, optionally filtered by a case-insensitive name term.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --kind node-kind             Filter by node kind.\n  --limit n                   Maximum number of nodes (default: 50).\n  --output json|text           Output format (default: json).\n  -o value                    Alias for --output.\n\nExamples:\n  lscg nodes --kind user --limit 20\n  lscg nodes --output text`,
-        edges: `Usage: lscg edges [options]\n\nList graph edges.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --kind edge-kind             Filter by edge kind.\n  --limit n                   Maximum number of edges (default: 50).\n\nExamples:\n  lscg edges --kind calls --limit 20`,
+        edges: `Usage: lscg edges [options]\n\nList graph edges.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --kind edge-kind             Filter by edge kind.\n  --limit n                   Maximum number of edges (default: 50).\n  --output json|text           Output format (default: json).\n  -o value                    Alias for --output.\n\nExamples:\n  lscg edges --kind calls --limit 20\n  lscg edges --output text`,
         neighbors: `Usage: lscg neighbors <node-id> [options]\n\nShow nearby nodes around a graph node id.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --depth n                   Traversal depth (default: 1).\n  --limit n                   Maximum number of neighbors (default: 100).\n  --node-id id                Node ID alternative to the positional argument.\n\nExamples:\n  lscg neighbors <node-id> --depth 2`,
         callgraph: `Usage: lscg callgraph <term> [options]\n\nFind nodes whose names contain a term and show upstream/downstream nodes.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --kind node-kind             Filter matching nodes by kind.\n  --depth n                   Upstream/downstream traversal depth (default: 5).\n  --limit n                   Maximum matches and relations (default: 100).\n  --output json|text|svg      Output format (default: text; svg requires repo or home scope).\n  -o value                    Alias for --output.\n\nExamples:\n  lscg callgraph greet --depth 2\n  lscg callgraph greet --output text`,
         context: `Usage: lscg context <symbol> [options]\n\nRetrieve bounded definition, impact, and dependency context.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to inspect (default: repo).\n  --kind node-kind            Constrain anchor candidates by node kind.\n  --file relative/path        Constrain anchor candidates by repository-relative path.\n  --depth 0..5                Relationship depth (default: 2).\n  --limit 1..500              Relationships per section (default: 50).\n  --candidate-limit 1..100   Maximum ranked candidates (default: 20).\n  --excerpt-lines 1..500     Opt-in excerpt line budget (default: 80).\n  --excerpt-bytes 1..100000  Opt-in excerpt byte budget (default: 12000).\n  --excerpts                  Include bounded source excerpts.\n  --output json|text|svg      Output format (default: text; svg requires repo or home scope).\n  -o value                    Alias for --output.\n\nExamples:\n  lscg context greet --kind symbol\n  lscg context greet --output text`,
         query: `Usage: lscg query <sql> [options]\n\nRun a read-only SQLite query against the graph database.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to query (default: repo).\n  --sql \"select ...\"          SQL alternative to the positional argument.\n  --attach-home               Attach the home database when querying repo scope.\n  --limit n                   Maximum number of rows (default: 200).\n\nExamples:\n  lscg query \"select kind, count(*) as n from nodes group by kind\"`,
-        view: `Usage: lscg view [options]\n\nOpen an interactive graph view or export a static SVG.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home           Storage scope to view (default: repo).\n  --anchor name               Focus the view around a node name.\n  --search term               Filter visible nodes by name.\n  --output path               Write an SVG snapshot instead of opening a browser.\n  -o path                     Alias for --output.\n\nExamples:\n  lscg view --anchor greet --search util\n  lscg view --output graph.svg`,
+        view: `Usage: lscg view [options]\n\nOpen an interactive graph view or export a static SVG.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home           Storage scope to view (default: repo).\n  --anchor name               Focus the view around a node name.\n  --search term               Filter visible nodes by name.\n  --display simple|shape|icon Display style (default: shape).\n  --output path               Write an SVG snapshot instead of opening a browser.\n  -o path                     Alias for --output.\n\nExamples:\n  lscg view --anchor greet --search util\n  lscg view --output graph.svg`,
         mcp: `Usage: lscg mcp [options]\n\nStart the MCP server over stdio.\nOptions:\n  --root path                 Repository root for the MCP server (default: current directory).\n\nExamples:\n  lscg mcp`
     };
     const commandHelp = help[command];
@@ -302,6 +318,18 @@ function coerce(value) {
 function printJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
+function formatEdgesText(edges) {
+    if (edges.length === 0)
+        return 'No matching edges.';
+    return edges.map((edge) => [
+        `${edge.scope}: ${edge.kind} (${edge.id})`,
+        `from: ${edge.sourceId}`,
+        `to: ${edge.targetId}`,
+        `file: ${edge.fileId ?? '<repository>'}`,
+        `confidence: ${edge.confidence}`,
+        `metadata: ${edge.metadataJson}`
+    ].join('\n')).join('\n\n');
+}
 function formatNodesText(nodes) {
     if (nodes.length === 0)
         return 'No matching nodes.';
@@ -369,18 +397,43 @@ function formatCallGraphText(results) {
     if (results.length === 0)
         return 'No matching nodes.';
     return results.map((match) => {
-        const lines = [`${match.scope}: ${match.name ?? '<unnamed>'} [${match.kind}/${match.type}] (${match.id})`];
-        lines.push('  upstream:');
+        const lines = [`[${match.kind}/${match.type}]: ${match.name ?? '<unnamed>'}${formatCallGraphLocation(match)}`];
+        lines.push('  referenced from:');
         lines.push(...formatCallGraphRelations(match.upstream));
-        lines.push('  downstream:');
-        lines.push(...formatCallGraphRelations(match.downstream));
+        lines.push('  depends on:');
+        lines.push(...formatCallGraphRelationsHierarchical(match.id, match.downstream));
         return lines.join('\n');
-    }).join('\n\n');
+    }).join('\n\n----\n\n');
+}
+function formatCallGraphLocation(node) {
+    return node.path ? ` in file ${node.path}:${node.startPoint.row + 1}` : '';
+}
+function formatCallGraphRelationLine(relation, indent) {
+    return `${indent}- ${relation.name ?? '<unnamed>'} [${relation.kind}/${relation.type}]${formatCallGraphLocation(relation)}`;
 }
 function formatCallGraphRelations(relations) {
     if (relations.length === 0)
         return ['    (none)'];
-    return relations.map((relation) => `    - ${relation.name ?? '<unnamed>'} [${relation.kind}/${relation.type}] depth=${relation.depth} edge=${relation.edgeKind} (${relation.id})`);
+    return relations.map((relation) => formatCallGraphRelationLine(relation, '    '));
+}
+function formatCallGraphRelationsHierarchical(rootId, relations) {
+    if (relations.length === 0)
+        return ['    (none)'];
+    const children = new Map();
+    for (const relation of relations) {
+        const siblings = children.get(relation.parentId) ?? [];
+        siblings.push(relation);
+        children.set(relation.parentId, siblings);
+    }
+    const lines = [];
+    const append = (parentId, indent) => {
+        for (const relation of children.get(parentId) ?? []) {
+            lines.push(formatCallGraphRelationLine(relation, indent));
+            append(relation.id, `${indent}  `);
+        }
+    };
+    append(rootId, '    ');
+    return lines.length > 0 ? lines : ['    (none)'];
 }
 function formatCallGraphSvg(results, { root, scope }) {
     if (scope === 'both')
@@ -444,6 +497,7 @@ Command options:
     --scope repo|home|both      Storage scope to inspect (default: repo).
     --kind edge-kind             Filter by edge kind.
     --limit n                   Maximum number of edges (default: 50).
+    --output json|text           Output format (default: json).
   neighbors <node-id>:
     --root path                 Repository root (default: current directory).
     --scope repo|home|both      Storage scope to inspect (default: repo).
@@ -480,6 +534,7 @@ Command options:
     --scope repo|home           Storage scope to view (default: repo).
     --anchor name               Focus the view around a node name.
     --search term               Filter visible nodes by name.
+    --display simple|shape|icon Display style (default: shape).
     --output path               Write an SVG snapshot instead of opening a browser.
   mcp:
     --root path                 Repository root for the MCP server (default: current directory).

package/dist/src/graph/repository.d.ts

@@ -1,4 +1,5 @@
 import type { GraphEdgeRow, GraphNodeRow, GraphNodeTextRow, NeighborRow, CallGraphMatch, RepositoryRecord, ScanSummary, StatusResult, StorageScope, ContextGraphResult } from '../types.js';
+import { type PluginResourceLimits, type ScannerPlugin } from '../scanner/plugins.js';
 export declare function repositoryForRoot(root?: string | undefined): RepositoryRecord;
 export declare function initGraph({ root, scope }?: {
     root?: string | undefined;
@@ -10,9 +11,11 @@ export declare function initGraph({ root, scope }?: {
         databasePath: string;
     }>;
 };
-export declare function scanRepository({ root, scope }?: {
+export declare function scanRepository({ root, scope, plugins, pluginLimits }?: {
     root?: string | undefined;
     scope?: StorageScope | 'both' | undefined;
+    plugins?: readonly ScannerPlugin[] | undefined;
+    pluginLimits?: Partial<PluginResourceLimits> | undefined;
 }): Promise<ScanSummary>;
 export declare function graphStatus({ root, scope }?: {
     root?: string | undefined;

package/dist/src/graph/repository.js

@@ -1,13 +1,53 @@
 import { createHash } from 'node:crypto';
-import { readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { databasePathForScope, homeDatabasePath, normalizeScope, repoDatabasePath, resolveProjectRoot } from '../config/paths.js';
 import { parseSource } from '../parser/treeSitter.js';
 import { discoverSourceFiles } from '../scanner/discover.js';
 import { collectRepositoryFingerprint } from '../scanner/fingerprint.js';
-import { attachDatabase, closeDatabase, getStatus, openGraphDatabase, replaceFileGraph, runSelect, selectCallGraph, selectEdges, selectNeighbors, selectNodes, selectNodeTextRows, upsertRepository, reconcileDeletedFiles, selectFileInventory, selectContextCandidates, selectContextRelationships } from '../storage/database.js';
+import { attachDatabase, closeDatabase, getStatus, openGraphDatabase, replaceFileGraph, runSelect, selectCallGraph, selectEdges, selectNeighbors, selectNodes, selectNodeTextRows, upsertRepository, reconcileDeletedFiles, reconcilePluginEdges, reconcileRepositoryPluginNodes, insertRepositoryPluginNodes, loadPluginContributions, persistPluginContributions, nextPluginGeneration, selectFileInventory, selectContextCandidates, selectContextRelationships } from '../storage/database.js';
 import { extractGraph, hashParts } from './extract.js';
 import { buildFileAttribution } from './attribution.js';
+import { createRepositoryScanContext, runScannerPlugins, DEFAULT_PLUGIN_RESOURCE_LIMITS } from '../scanner/plugins.js';
+import { PackagePlugin } from '../scanner/packagePlugin.js';
+function normalizePluginFilePath(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return undefined;
+    const normalized = path.posix.normalize(value.replaceAll('\\', '/'));
+    if (path.posix.isAbsolute(normalized) || normalized === '..' || normalized.startsWith('../'))
+        return undefined;
+    return normalized.replace(/^\.\//, '');
+}
+function truncateDiagnostic(message, maxBytes) {
+    if (Buffer.byteLength(message, 'utf8') <= maxBytes)
+        return message;
+    let truncated = message;
+    while (Buffer.byteLength(truncated, 'utf8') > maxBytes)
+        truncated = truncated.slice(0, -1);
+    return truncated;
+}
+function diagnoseUnresolvedPluginOwnership(nodes, edges, persistedFileIds) {
+    const diagnostics = [];
+    for (const node of nodes) {
+        const filePath = node.metadata.filePath;
+        if (typeof filePath !== 'string')
+            continue;
+        const normalizedPath = normalizePluginFilePath(filePath);
+        if (!normalizedPath || !persistedFileIds.has(normalizedPath)) {
+            diagnostics.push(`unresolved plugin node ownership: ${filePath}`);
+        }
+    }
+    for (const edge of edges) {
+        const filePath = edge.metadata.filePath;
+        if (typeof filePath !== 'string')
+            continue;
+        const normalizedPath = normalizePluginFilePath(filePath);
+        if (!normalizedPath || !persistedFileIds.has(normalizedPath)) {
+            diagnostics.push(`unresolved plugin edge ownership: ${filePath}`);
+        }
+    }
+    return diagnostics;
+}
 export function repositoryForRoot(root = process.cwd()) {
     const resolvedRoot = resolveProjectRoot(root);
     return {
@@ -33,10 +73,15 @@ export function initGraph({ root = process.cwd(), scope = 'repo' } = {}) {
     }
     return { repository, initialized };
 }
-export async function scanRepository({ root = process.cwd(), scope = 'repo' } = {}) {
+export async function scanRepository({ root = process.cwd(), scope = 'repo', plugins = [], pluginLimits } = {}) {
     const repository = repositoryForRoot(root);
     const scopes = normalizeScope(scope);
     const files = discoverSourceFiles(repository.root);
+    const configuredPlugins = [
+        ...(existsSync(path.join(repository.root, 'package.json')) ? [PackagePlugin] : []),
+        ...plugins.filter((plugin) => plugin.name !== PackagePlugin.name)
+    ];
+    const pluginRun = await runScannerPlugins(createRepositoryScanContext(repository.root), configuredPlugins, pluginLimits);
     const opened = scopes.map((graphScope) => {
         const databasePath = databasePathForScope(graphScope, repository.root);
         return { scope: graphScope, databasePath, db: openGraphDatabase(databasePath) };
@@ -45,9 +90,42 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo' } =
     let nodesWritten = 0;
     let edgesWritten = 0;
     const skipped = [];
+    const stalePlugins = [];
     try {
-        for (const handle of opened)
+        const primary = opened[0];
+        const contributions = new Map(pluginRun.pluginContributions ?? new Map());
+        for (const pluginName of pluginRun.successfulPlugins ?? []) {
+            if (!contributions.has(pluginName))
+                contributions.set(pluginName, { nodes: [], edges: [] });
+        }
+        if (primary) {
+            upsertRepository(primary.db, repository);
+            const generation = nextPluginGeneration(primary.db, repository);
+            persistPluginContributions(primary.db, repository, contributions, generation);
+            const previous = loadPluginContributions(primary.db, repository, pluginRun.failedPlugins ?? []);
+            for (const pluginName of pluginRun.failedPlugins ?? []) {
+                const contribution = previous.get(pluginName);
+                if (!contribution)
+                    continue;
+                stalePlugins.push(pluginName);
+                pluginRun.nodes.push(...contribution.nodes);
+                pluginRun.edges.push(...contribution.edges);
+                const diagnosticLimit = pluginLimits?.maxDiagnostics ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnostics;
+                const messageLimit = pluginLimits?.maxDiagnosticMessageBytes ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnosticMessageBytes;
+                if (pluginRun.diagnostics.length < diagnosticLimit) {
+                    pluginRun.diagnostics.push(truncateDiagnostic(`${pluginName}: reused last successful contribution (stale)`, messageLimit));
+                }
+            }
+        }
+        for (const handle of opened.slice(1)) {
+            persistPluginContributions(handle.db, repository, contributions, nextPluginGeneration(handle.db, repository));
+        }
+        const activePlugins = [...(pluginRun.successfulPlugins ?? []), ...stalePlugins];
+        for (const handle of opened) {
             upsertRepository(handle.db, repository);
+            reconcileRepositoryPluginNodes(handle.db, repository, activePlugins);
+            insertRepositoryPluginNodes(handle.db, repository, pluginRun.nodes);
+        }
         for (const relativePath of files) {
             const absolutePath = path.join(repository.root, relativePath);
             const source = readFileSync(absolutePath, 'utf8');
@@ -67,7 +145,7 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo' } =
                 size: stat.size,
                 mtimeMs: Math.round(stat.mtimeMs)
             };
-            const graph = extractGraph({
+            const builtInGraph = extractGraph({
                 repositoryId: repository.id,
                 fileId,
                 relativePath,
@@ -75,6 +153,12 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo' } =
                 sourceHash,
                 parseResult
             });
+            const normalizedRelativePath = normalizePluginFilePath(relativePath);
+            const pluginNodes = pluginRun.nodes.filter((node) => normalizePluginFilePath(node.metadata.filePath) === normalizedRelativePath);
+            const graph = {
+                nodes: [...builtInGraph.nodes, ...pluginNodes],
+                edges: builtInGraph.edges
+            };
             const attribution = buildFileAttribution({
                 root: repository.root,
                 relativePath,
@@ -88,6 +172,19 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo' } =
             nodesWritten += graph.nodes.length + (attribution?.contributorEmails.length ?? 0);
             edgesWritten += graph.edges.length + (attribution?.nodeAttributions.reduce((sum, entry) => sum + entry.contributorEmails.length, 0) ?? 0);
         }
+        const persistedFileIds = new Map(files
+            .filter((relativePath) => !skipped.includes(relativePath))
+            .map((relativePath) => [normalizePluginFilePath(relativePath) ?? relativePath, hashParts([repository.id, relativePath])]));
+        const unresolvedOwnership = diagnoseUnresolvedPluginOwnership(pluginRun.nodes, pluginRun.edges, persistedFileIds);
+        const diagnosticLimit = pluginLimits?.maxDiagnostics ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnostics;
+        const messageLimit = pluginLimits?.maxDiagnosticMessageBytes ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnosticMessageBytes;
+        for (const diagnostic of unresolvedOwnership.slice(0, Math.max(0, diagnosticLimit - pluginRun.diagnostics.length))) {
+            pluginRun.diagnostics.push(truncateDiagnostic(diagnostic, messageLimit));
+        }
+        if (opened[0])
+            edgesWritten += reconcilePluginEdges(opened[0].db, repository, pluginRun.edges, persistedFileIds, activePlugins);
+        for (const handle of opened.slice(1))
+            reconcilePluginEdges(handle.db, repository, pluginRun.edges, persistedFileIds, activePlugins);
     }
     finally {
         for (const handle of opened)
@@ -100,7 +197,10 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo' } =
         filesScanned,
         nodesWritten,
         edgesWritten,
-        skipped
+        skipped,
+        pluginDiagnostics: pluginRun.diagnostics,
+        failedPlugins: pluginRun.failedPlugins,
+        stalePlugins
     };
 }
 export function graphStatus({ root = process.cwd(), scope = 'repo' } = {}) {

package/dist/src/index.d.ts

@@ -1,5 +1,8 @@
 export { initGraph, listEdges, listNodes, graphStatus, callGraph, neighbors, contextGraph, runReadOnlySql, scanRepository } from './graph/repository.js';
 export { watchRepository } from './watch.js';
+export { SCANNER_PLUGIN_API_VERSION, DEFAULT_PLUGIN_RESOURCE_LIMITS, createRepositoryScanContext, runScannerPlugins, BUILTIN_GRAPH_PLUGIN } from './scanner/plugins.js';
+export type { ScannerPlugin, ScannerCapability, PluginConflictPolicy, PluginNodeFact, PluginEdgeFact, PluginScanResult, PluginRunResult, PluginResourceLimits, RepositoryScanContext, RepositoryScanFile } from './scanner/plugins.js';
+export { PackagePlugin } from './scanner/packagePlugin.js';
 export { viewGraph, loadViewSnapshot, buildViewModel, renderInteractiveHtml, renderSvgMarkup, openInDefaultBrowser, openHtmlArtifactInBrowser, writeTemporaryHtmlArtifact } from './view/index.js';
 export { repoDatabasePath, homeDatabasePath, resolveProjectRoot } from './config/paths.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -1,5 +1,7 @@
 export { initGraph, listEdges, listNodes, graphStatus, callGraph, neighbors, contextGraph, runReadOnlySql, scanRepository } from './graph/repository.js';
 export { watchRepository } from './watch.js';
+export { SCANNER_PLUGIN_API_VERSION, DEFAULT_PLUGIN_RESOURCE_LIMITS, createRepositoryScanContext, runScannerPlugins, BUILTIN_GRAPH_PLUGIN } from './scanner/plugins.js';
+export { PackagePlugin } from './scanner/packagePlugin.js';
 export { viewGraph, loadViewSnapshot, buildViewModel, renderInteractiveHtml, renderSvgMarkup, openInDefaultBrowser, openHtmlArtifactInBrowser, writeTemporaryHtmlArtifact } from './view/index.js';
 export { repoDatabasePath, homeDatabasePath, resolveProjectRoot } from './config/paths.js';
 //# sourceMappingURL=index.js.map

package/dist/src/mcp/server.js

@@ -20,7 +20,7 @@ export async function startMcpServer({ root = process.cwd() } = {}) {
     tool('context_graph_nodes', 'List graph nodes discovered in the repository.', {
         root: z.string().optional(),
         scope: scopeSchema,
-        kind: z.enum(['file', 'symbol', 'import', 'export', 'call', 'user']).optional(),
+        kind: z.enum(['file', 'symbol', 'import', 'export', 'call', 'user', 'package']).optional(),
         limit: z.number().int().positive().max(500).default(50)
     }, async (input) => jsonResponse(listNodes({
         root: input.root ?? root,
@@ -31,7 +31,7 @@ export async function startMcpServer({ root = process.cwd() } = {}) {
     tool('context_graph_edges', 'List graph edges discovered in the repository.', {
         root: z.string().optional(),
         scope: scopeSchema,
-        kind: z.enum(['contains', 'defines', 'imports', 'exports', 'calls', 'attributed_to']).optional(),
+        kind: z.enum(['contains', 'defines', 'imports', 'exports', 'calls', 'attributed_to', 'provides']).optional(),
         limit: z.number().int().positive().max(500).default(50)
     }, async (input) => jsonResponse(listEdges({
         root: input.root ?? root,

package/dist/src/scanner/discover.js

@@ -4,8 +4,6 @@ import path from 'node:path';
 import { isSupportedSourceFile } from '../parser/treeSitter.js';
 const DEFAULT_IGNORES = new Set([
     '.git',
-    '.sling',
-    '.pi-subagents',
     'node_modules',
     'dist',
     'coverage',

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

@@ -0,0 +1,3 @@
+import type { ScannerPlugin } from './plugins.js';
+export declare const PackagePlugin: ScannerPlugin;
+//# sourceMappingURL=packagePlugin.d.ts.map

package/dist/src/scanner/packagePlugin.js

@@ -0,0 +1,125 @@
+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';
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const BUILTINS = new Set(builtinModules.flatMap((name) => [name, name.replace(/^node:/, ''), `node:${name.replace(/^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);
+            }
+        }
+        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 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) => {
+            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 [];
+            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