@psnext/lscg 0.1.5 → 0.1.6

package/README.md

@@ -198,9 +198,13 @@ The report also retains deterministic work counters and informational p50/p95
 timings for the isolated representative fixture's initial full scan, no-change
 incremental scan, and one-file Watch Session update.
 
-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.
+Git user attribution is optional. Enable it with `--attribution` on `scan`,
+`watch`, or `scan --watch`; normal scans return structural data with attribution
+pending, while `--full` and active watch sessions drain the selected enrichment.
+Without the flag, scans report attribution as `disabled` and do not invoke Git
+or create user nodes. Existing attribution remains readable if a later scan omits
+the flag. When enabled, contributor user nodes are keyed by normalized email and
+the most recent contributor is tracked for each discovered node.
 
 ## Scanner plugins
 
@@ -210,10 +214,11 @@ 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.
+are never parsed as namespaces. Nodes and edges may also carry plugin-defined
+`type` values; edge `type` defaults to its structural `kind` when omitted.
 
 ```ts
-import { scanRepository, type ScannerPlugin } from '@psnext/lscg';
+import { AttributionPlugin, scanRepository, type ScannerPlugin } from '@psnext/lscg';
 
 const plugin: ScannerPlugin = {
   name: 'my-analyzer',
@@ -235,8 +240,26 @@ const plugin: ScannerPlugin = {
 };
 
 await scanRepository({ root: '/path/to/repo', plugins: [plugin] });
+
+// Or opt into the bundled Git user attribution enrichment:
+await scanRepository({ root: '/path/to/repo', plugins: [AttributionPlugin] });
+// The same bundled plugin can also be selected as a convenience option:
+await scanRepository({ root: '/path/to/repo', attribution: true });
+// The CLI equivalent is: lscg scan --attribution
+```
+
+A separately packaged plugin can be passed to a host application as an imported `ScannerPlugin`. The copyable [external scanner plugin example](examples/external-scanner-plugin/) demonstrates this with a TODO/FIXME analyzer and a host script.
+
+The CLI can load the default export of an external module with the repeatable `--plugin` option:
+
+```sh
+lscg scan --root /path/to/repo --plugin @acme/my-scanner-plugin
+lscg scan --root /path/to/repo --plugin ./my-scanner-plugin.mjs
+lscg watch --root /path/to/repo --plugin ./my-scanner-plugin.mjs
 ```
 
+Relative module specifiers are resolved from the current working directory. The module must default-export one `ScannerPlugin` (an array is also accepted). External plugins are trusted code and run in-process; only load modules you trust. The supplied plugins are used for one-shot scans, `watch`, and `scan --watch`.
+
 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
@@ -253,7 +276,8 @@ 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.
+plugins do not provide database IDs. Use `lscg edges --type <edge-type>` to filter
+persisted edge types.
 
 Every scan also runs the bundled `PackagePlugin`. It reads the repository-root
 `package.json` dependency sections (`dependencies`, `devDependencies`,

package/dist/src/cli.js

@@ -1,3 +1,5 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { startMcpServer } from './mcp/server.js';
 import { buildViewModel, loadViewSnapshot, renderSvgMarkup, viewGraph } from './view/index.js';
 import { watchRepository } from './watch.js';
@@ -19,18 +21,22 @@ export async function runCli(argv) {
         case 'init':
             printJson(initGraph({ root: options.root, scope: options.scope ?? 'repo' }));
             return;
-        case 'scan':
+        case 'scan': {
             if (options.watch && options.full)
                 throw new Error('scan --full cannot be combined with --watch');
+            const plugins = await loadExternalPlugins(options.plugin ?? []);
             if (options.watch) {
-                await watchRepository({ root: options.root, scope: options.scope ?? 'repo' }, { mode: 'scan --watch', progress });
+                await watchRepository({ root: options.root, scope: options.scope ?? 'repo', attribution: options.attribution === true, plugins }, { mode: 'scan --watch', progress });
                 return;
             }
-            printJson(await scanRepository({ root: options.root, scope: options.scope ?? 'repo', full: options.full === true, progress }));
+            printJson(await scanRepository({ root: options.root, scope: options.scope ?? 'repo', plugins, attribution: options.attribution === true, full: options.full === true, progress }));
             return;
-        case 'watch':
-            await watchRepository({ root: options.root, scope: options.scope ?? 'repo' }, { mode: 'watch', progress });
+        }
+        case 'watch': {
+            const plugins = await loadExternalPlugins(options.plugin ?? []);
+            await watchRepository({ root: options.root, scope: options.scope ?? 'repo', attribution: options.attribution === true, plugins }, { mode: 'watch', progress });
             return;
+        }
         case 'status':
             printJson(graphStatus({ root: options.root, scope: options.scope ?? 'repo' }));
             return;
@@ -62,6 +68,7 @@ export async function runCli(argv) {
                 root: options.root,
                 scope: options.scope ?? 'repo',
                 kind: options.kind,
+                type: options.type,
                 limit: options.limit
             });
             const output = options.output ?? 'json';
@@ -237,12 +244,21 @@ function parseOptions(args) {
         if (!rawKey)
             continue;
         const key = toCamelCase(rawKey);
+        if (key === 'plugin') {
+            const value = inlineValue ?? args[index + 1];
+            if (!value || value.startsWith('-'))
+                throw new Error('--plugin requires a module specifier');
+            options.plugin = [...(options.plugin ?? []), value];
+            if (inlineValue === undefined)
+                index += 1;
+            continue;
+        }
         if (inlineValue !== undefined) {
             options[key] = coerce(inlineValue);
             continue;
         }
         const next = args[index + 1];
-        const booleanOption = key === 'watch' || key === 'full' || key === 'attachHome' || key === 'excerpts' || key === 'help' || key === 'progress';
+        const booleanOption = key === 'watch' || key === 'full' || key === 'attachHome' || key === 'excerpts' || key === 'help' || key === 'progress' || key === 'attribution';
         if (!booleanOption && next && !next.startsWith('--')) {
             options[key] = coerce(next);
             index += 1;
@@ -290,11 +306,11 @@ function validateContextOptions(options, args) {
 function commandHelpText(command) {
     const help = {
         init: `Usage: lscg init [options]\n\nCreate graph storage for the selected scope.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to initialize (default: repo).\n\nExamples:\n  lscg init --scope both`,
-        scan: `Usage: lscg scan [options]\n\nParse repository files and write discovered graph data.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to scan (default: repo).\n  --full                      Rebuild and verify every discovered source file.\n  --watch                     Watch and rescan after the initial scan.\n  --progress                  Write human-readable lifecycle progress to stderr.\n\nExamples:\n  lscg scan --scope both\n  lscg scan --full\n  lscg scan --watch`,
-        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  --progress                  Write human-readable lifecycle progress to stderr.\n\nExamples:\n  lscg watch`,
+        scan: `Usage: lscg scan [options]\n\nParse repository files and write discovered graph data.\nOptions:\n  --root path                 Repository root (default: current directory).\n  --scope repo|home|both      Storage scope to scan (default: repo).\n  --full                      Rebuild and verify every discovered source file.\n  --watch                     Watch and rescan after the initial scan.\n  --progress                  Write human-readable lifecycle progress to stderr.\n  --attribution               Enable optional Git user attribution enrichment.\n  --plugin module              Load an external ScannerPlugin module (repeatable).\n\nExamples:\n  lscg scan --scope both\n  lscg scan --full\n  lscg scan --watch`,
+        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  --progress                  Write human-readable lifecycle progress to stderr.\n  --attribution               Enable optional Git user attribution enrichment.\n  --plugin module              Load an external ScannerPlugin module (repeatable).\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  --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`,
+        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  --type edge-type             Filter by edge type.\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`,
@@ -307,6 +323,30 @@ function commandHelpText(command) {
         return helpText();
     return `${commandHelp}\n\nShort aliases (where supported): -r --root, -s --scope, -k --kind, -d --depth, -l --limit, -f --file, -o --output.`;
 }
+async function loadExternalPlugins(specifiers) {
+    const plugins = [];
+    for (const specifier of specifiers) {
+        const importTarget = specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:')
+            ? (specifier.startsWith('file:') ? specifier : pathToFileURL(path.resolve(process.cwd(), specifier)).href)
+            : specifier;
+        let loaded;
+        try {
+            loaded = await import(importTarget);
+        }
+        catch (error) {
+            throw new Error(`failed to load external plugin ${specifier}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const candidate = loaded.default ?? loaded;
+        const values = Array.isArray(candidate) ? candidate : [candidate];
+        for (const plugin of values) {
+            if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string' || typeof plugin.scan !== 'function') {
+                throw new Error(`external plugin ${specifier} must default-export a ScannerPlugin or ScannerPlugin[]`);
+            }
+            plugins.push(plugin);
+        }
+    }
+    return plugins;
+}
 function toCamelCase(value) {
     return value.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
 }
@@ -486,10 +526,14 @@ Command options:
     --full                      Rebuild and verify every discovered source file.
     --watch                     Watch and rescan after the initial scan.
     --progress                  Write human-readable lifecycle progress to stderr.
+    --attribution               Enable optional Git user attribution enrichment.
+    --plugin module              Load an external ScannerPlugin module (repeatable).
   watch:
     --root path                 Repository root (default: current directory).
     --scope repo                Repository scope to watch (default: repo).
     --progress                  Write human-readable lifecycle progress to stderr.
+    --attribution               Enable optional Git user attribution enrichment.
+    --plugin module              Load an external ScannerPlugin module (repeatable).
   status:
     --root path                 Repository root (default: current directory).
     --scope repo|home|both      Storage scope to inspect (default: repo).
@@ -503,6 +547,7 @@ Command options:
     --root path                 Repository root (default: current directory).
     --scope repo|home|both      Storage scope to inspect (default: repo).
     --kind edge-kind             Filter by edge kind.
+    --type edge-type             Filter by edge type.
     --limit n                   Maximum number of edges (default: 50).
     --output json|text           Output format (default: json).
   neighbors <node-id>:

package/dist/src/explore/sigma-provider.d.ts

@@ -0,0 +1,27 @@
+import type { ExploreGraphResult } from '../types.js';
+export interface SigmaGraph {
+    order: number;
+    size: number;
+    hasNode(nodeId: string): boolean;
+    hasEdge(edgeId: string): boolean;
+    addNode(nodeId: string, attributes: Record<string, unknown>): void;
+    addDirectedEdgeWithKey(edgeId: string, sourceId: string, targetId: string, attributes: Record<string, unknown>): void;
+    source(edgeId: string): string;
+    target(edgeId: string): string;
+}
+export interface SigmaGraphStats {
+    nodes: number;
+    edges: number;
+    aggregateNodes: number;
+    sourceNodes: number;
+    relationshipKinds: string[];
+}
+/**
+ * Convert the provider-neutral Explore result into Sigma's Graphology model.
+ * This adapter owns no layout or browser lifecycle; those remain provider work.
+ */
+export declare function toSigmaGraph(result: ExploreGraphResult): {
+    graph: SigmaGraph;
+    stats: SigmaGraphStats;
+};
+//# sourceMappingURL=sigma-provider.d.ts.map

package/dist/src/explore/sigma-provider.js

@@ -0,0 +1,87 @@
+import Graphology from 'graphology';
+/**
+ * Convert the provider-neutral Explore result into Sigma's Graphology model.
+ * This adapter owns no layout or browser lifecycle; those remain provider work.
+ */
+export function toSigmaGraph(result) {
+    const GraphConstructor = Graphology;
+    const graph = new GraphConstructor({ type: 'directed', multi: true, allowSelfLoops: true });
+    const aggregateNodes = result.scopes.flatMap((scope) => scope.nodes.filter((node) => node.category === 'aggregate'));
+    const sourceNodes = result.scopes.flatMap((scope) => scope.nodes.filter((node) => node.category === 'source'));
+    const edges = result.scopes.flatMap((scope) => scope.edges);
+    const allNodes = [...aggregateNodes, ...sourceNodes];
+    const columns = Math.max(1, Math.ceil(Math.sqrt(allNodes.length)));
+    allNodes.forEach((node, index) => {
+        if (graph.hasNode(node.id))
+            return;
+        graph.addNode(node.id, {
+            ...sigmaNodeAttributes(node),
+            x: (index % columns) * 2,
+            y: Math.floor(index / columns) * 2
+        });
+    });
+    for (const edge of edges) {
+        if (!graph.hasNode(edge.sourceId) || !graph.hasNode(edge.targetId))
+            continue;
+        if (graph.hasEdge(edge.id))
+            continue;
+        graph.addDirectedEdgeWithKey(edge.id, edge.sourceId, edge.targetId, {
+            label: edge.kind,
+            type: edge.kind,
+            size: edge.count ? Math.max(1, Math.log2(edge.count + 1)) : 1,
+            color: edgeColor(edge.kind),
+            confidence: edge.confidence,
+            metadata: edge.metadata
+        });
+    }
+    return {
+        graph,
+        stats: {
+            nodes: graph.order,
+            edges: graph.size,
+            aggregateNodes: aggregateNodes.length,
+            sourceNodes: sourceNodes.length,
+            relationshipKinds: [...new Set(edges.map((edge) => edge.kind))].sort()
+        }
+    };
+}
+function sigmaNodeAttributes(node) {
+    if (node.category === 'aggregate') {
+        return {
+            label: node.name,
+            x: 0,
+            y: 0,
+            size: Math.max(4, Math.min(18, 4 + Math.log2(node.childCount + 1))),
+            color: '#2563eb',
+            category: node.category,
+            kind: node.kind,
+            path: node.path,
+            expandable: node.expandable,
+            expansionKey: node.expansionKey
+        };
+    }
+    return {
+        label: node.name ?? node.id,
+        x: 0,
+        y: 0,
+        size: 5,
+        color: '#64748b',
+        category: node.category,
+        kind: node.kind,
+        type: node.type,
+        path: node.path,
+        metadata: node.metadata,
+        expansionKey: node.expansionKey
+    };
+}
+function edgeColor(kind) {
+    const colors = {
+        calls: '#dc2626',
+        imports: '#7c3aed',
+        exports: '#0891b2',
+        contains: '#64748b',
+        defines: '#16a34a'
+    };
+    return colors[kind] ?? '#94a3b8';
+}
+//# sourceMappingURL=sigma-provider.js.map

package/dist/src/explore/sigma-render.d.ts

@@ -0,0 +1,18 @@
+import { type BrowserOpenResult } from '../view/open.js';
+import type { ExploreGraphResult } from '../types.js';
+export interface SigmaExploreRunResult {
+    mode: 'interactive';
+    artifactPath: string;
+    opened: boolean;
+    command?: string;
+    error?: string;
+    nodeCount: number;
+    edgeCount: number;
+}
+export interface SigmaExploreDependencies {
+    opener?: (targetPath: string) => BrowserOpenResult;
+}
+/** Render the provider-neutral result into a standalone Sigma.js HTML page. */
+export declare function renderSigmaExploreHtml(result: ExploreGraphResult): string;
+export declare function openSigmaExplore(result: ExploreGraphResult, dependencies?: SigmaExploreDependencies): SigmaExploreRunResult;
+//# sourceMappingURL=sigma-render.d.ts.map

package/dist/src/explore/sigma-render.js

@@ -0,0 +1,67 @@
+import { openHtmlArtifactInBrowser } from '../view/open.js';
+/** Render the provider-neutral result into a standalone Sigma.js HTML page. */
+export function renderSigmaExploreHtml(result) {
+    const serialized = JSON.stringify(result).replaceAll('<', '\\u003c');
+    const title = `${result.repository.name} Explore`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+:root { color-scheme: dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+html, body, #app { width: 100%; height: 100%; margin: 0; background: #020617; color: #e2e8f0; }
+#graph { position: absolute; inset: 0; }
+#panel { position: absolute; top: 16px; left: 16px; width: min(360px, calc(100vw - 32px)); max-height: calc(100vh - 32px); overflow: auto; padding: 16px; border: 1px solid #334155; border-radius: 12px; background: rgba(15, 23, 42, .94); box-shadow: 0 12px 32px rgba(0,0,0,.35); }
+h1 { margin: 0 0 6px; font-size: 18px; } h2 { margin: 16px 0 8px; font-size: 13px; text-transform: uppercase; letter-spacing: .08em; color: #94a3b8; }
+#status { color: #94a3b8; font-size: 12px; white-space: pre-wrap; }
+input { width: 100%; box-sizing: border-box; margin-top: 12px; padding: 8px 10px; border: 1px solid #475569; border-radius: 7px; background: #0f172a; color: inherit; }
+label { display: block; margin: 6px 0; font-size: 12px; color: #cbd5e1; } label input { width: auto; margin: 0 6px 0 0; }
+#details { font-size: 12px; line-height: 1.5; color: #cbd5e1; }
+.warning { color: #fbbf24; } code { color: #93c5fd; }
+</style>
+</head>
+<body><div id="app"><div id="graph"></div><aside id="panel">
+<h1>${escapeHtml(title)}</h1><div id="status"></div>
+<input id="search" type="search" placeholder="Search nodes">
+<h2>Relationship filters</h2><div id="filters"></div>
+<h2>Selected node</h2><div id="details">Click a node to inspect it.</div>
+</aside></div>
+<script type="module">
+import Graph from 'https://cdn.jsdelivr.net/npm/graphology@0.26.0/+esm';
+import Sigma from 'https://cdn.jsdelivr.net/npm/sigma@3.0.3/+esm';
+const result = ${serialized};
+const scope = result.scopes[0] || { nodes: [], edges: [], warnings: [], filters: { relationshipKinds: [] }, freshness: { state: 'missing' } };
+const graph = new Graph({ type: 'directed', multi: true, allowSelfLoops: true });
+const nodes = scope.nodes || [], edges = scope.edges || [];
+const columns = Math.max(1, Math.ceil(Math.sqrt(nodes.length)));
+for (const [index, node] of nodes.entries()) {
+  graph.addNode(node.id, { label: node.name || node.id, x: (index % columns) * 2, y: Math.floor(index / columns) * 2, size: node.category === 'aggregate' ? Math.max(5, Math.min(18, 5 + Math.log2((node.childCount || 0) + 1))) : 5, color: node.category === 'aggregate' ? '#2563eb' : '#64748b', kind: node.kind, category: node.category, hidden: false });
+}
+for (const edge of edges) {
+  if (graph.hasNode(edge.sourceId) && graph.hasNode(edge.targetId) && !graph.hasEdge(edge.id)) graph.addDirectedEdgeWithKey(edge.id, edge.sourceId, edge.targetId, { type: 'arrow', label: edge.kind, color: edgeColor(edge.kind), size: edge.count ? Math.max(1, Math.log2(edge.count + 1)) : 1, relationshipKind: edge.kind });
+}
+const visibleKinds = new Set(scope.filters?.relationshipKinds || []);
+const search = document.getElementById('search');
+const details = document.getElementById('details');
+const status = document.getElementById('status');
+const filters = document.getElementById('filters');
+status.textContent = 'Mode: ' + scope.mode + '\\nScope: ' + scope.scope + '\\nNodes: ' + graph.order + ' · Edges: ' + graph.size + '\\nFreshness: ' + scope.freshness.state + (scope.truncation?.bounded ? '\\nResult bounded by visibility caps.' : '');
+if (scope.warnings?.length) status.textContent += '\\n' + scope.warnings.join('\\n');
+for (const kind of ['contains', 'defines', 'calls', 'imports', 'exports']) { const label = document.createElement('label'); const checkbox = document.createElement('input'); checkbox.type = 'checkbox'; checkbox.checked = visibleKinds.has(kind); checkbox.addEventListener('change', () => { checkbox.checked ? visibleKinds.add(kind) : visibleKinds.delete(kind); renderer.refresh(); }); label.append(checkbox, kind); filters.append(label); }
+const renderer = new Sigma(graph, document.getElementById('graph'), { renderEdgeLabels: false, labelColor: { color: '#e2e8f0' }, nodeReducer: (node, attrs) => { const next = { ...attrs }; const term = search.value.trim().toLocaleLowerCase(); if (term && !String(attrs.label || '').toLocaleLowerCase().includes(term)) next.hidden = true; return next; }, edgeReducer: (edge, attrs) => ({ ...attrs, hidden: !visibleKinds.has(String(attrs.relationshipKind)) }) });
+search.addEventListener('input', () => renderer.refresh());
+renderer.on('clickNode', ({ node }) => { const attrs = graph.getNodeAttributes(node); details.innerHTML = '<code>' + escapeHtml(node) + '</code><br>kind: ' + escapeHtml(String(attrs.kind || '')) + '<br>label: ' + escapeHtml(String(attrs.label || '')); });
+function edgeColor(kind) { return ({ calls: '#dc2626', imports: '#7c3aed', exports: '#0891b2', contains: '#64748b', defines: '#16a34a' })[kind] || '#94a3b8'; }
+function escapeHtml(value) { return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;'); }
+</script></body></html>`;
+}
+export function openSigmaExplore(result, dependencies = {}) {
+    const opened = openHtmlArtifactInBrowser(renderSigmaExploreHtml(result), dependencies.opener);
+    const scope = result.scopes.reduce((total, item) => total + item.nodes.length, 0);
+    const edges = result.scopes.reduce((total, item) => total + item.edges.length, 0);
+    return { mode: 'interactive', artifactPath: opened.htmlPath, opened: opened.opened, ...(opened.command ? { command: opened.command } : {}), ...(opened.error ? { error: opened.error } : {}), nodeCount: scope, edgeCount: edges };
+}
+function escapeHtml(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;'); }
+//# sourceMappingURL=sigma-render.js.map

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

@@ -0,0 +1,20 @@
+import type { ExploreDirection, ExploreEdgeKind, ExploreGraphResult, GraphScope } from '../types.js';
+export declare const EXPLORE_DEFAULT_DEPTH = 4;
+export declare const EXPLORE_MAX_NODES = 2000;
+export declare const EXPLORE_MAX_EDGES = 10000;
+export declare const EXPLORE_EDGE_KINDS: readonly ExploreEdgeKind[];
+export interface ExploreGraphOptions {
+    root?: string | undefined;
+    scope?: GraphScope;
+    anchor?: string | undefined;
+    file?: string | undefined;
+    search?: string | undefined;
+    direction?: ExploreDirection | undefined;
+    relationshipKinds?: readonly ExploreEdgeKind[] | undefined;
+    depth?: number | undefined;
+    nodeCap?: number | undefined;
+    edgeCap?: number | undefined;
+    candidateLimit?: number | undefined;
+}
+export declare function exploreGraph(options?: ExploreGraphOptions): ExploreGraphResult;
+//# sourceMappingURL=explore.d.ts.map

package/dist/src/graph/explore.js

@@ -0,0 +1,200 @@
+import { existsSync } from 'node:fs';
+import { databasePathForScope, normalizeScope } from '../config/paths.js';
+import { aggregateId, closeDatabase, openReadOnlyGraphDatabase, selectExploreAggregateEdges, selectExploreAggregates, selectExploreCandidates, selectExploreNode, selectExploreNodeRows, selectExploreSourcesForSearch, selectExploreTraversalEdges, selectFreshnessReport } from '../storage/database.js';
+import { repositoryForRoot } from './repository.js';
+export const EXPLORE_DEFAULT_DEPTH = 4;
+export const EXPLORE_MAX_NODES = 2_000;
+export const EXPLORE_MAX_EDGES = 10_000;
+export const EXPLORE_EDGE_KINDS = ['contains', 'defines', 'calls', 'imports', 'exports'];
+export function exploreGraph(options = {}) {
+    const repository = repositoryForRoot(options.root);
+    const scope = options.scope ?? 'repo';
+    const mode = options.anchor || options.file ? 'anchor' : 'full';
+    const request = {
+        root: repository.root,
+        scope,
+        mode,
+        ...(options.anchor ? { anchor: options.anchor.trim() } : {}),
+        ...(options.file ? { file: options.file.trim() } : {}),
+        ...(options.search ? { search: options.search.trim() } : {}),
+        direction: options.direction ?? 'both',
+        relationshipKinds: normalizeKinds(options.relationshipKinds),
+        depth: clamp(options.depth, 0, EXPLORE_DEFAULT_DEPTH, EXPLORE_DEFAULT_DEPTH),
+        nodeCap: clamp(options.nodeCap, 1, EXPLORE_MAX_NODES, EXPLORE_MAX_NODES),
+        edgeCap: clamp(options.edgeCap, 1, EXPLORE_MAX_EDGES, EXPLORE_MAX_EDGES),
+        candidateLimit: clamp(options.candidateLimit, 1, 100, 20)
+    };
+    const scopes = normalizeScope(scope);
+    return {
+        contract_version: 1,
+        repository,
+        request,
+        scopes: scopes.map((graphScope) => exploreScope(repository, graphScope, request))
+    };
+}
+function exploreScope(repository, graphScope, request) {
+    const databasePath = databasePathForScope(graphScope, repository.root);
+    if (!existsSync(databasePath))
+        return emptyScope(graphScope, databasePath, request, missingFreshness(databasePath));
+    let db;
+    try {
+        db = openReadOnlyGraphDatabase(databasePath);
+    }
+    catch (error) {
+        return emptyScope(graphScope, databasePath, request, {
+            state: 'unavailable', reason: 'unavailable_storage', message: `Explore storage is unavailable: ${diagnostic(error)}`,
+            recovery: 'Run lscg scan explicitly, then retry Explore.'
+        });
+    }
+    try {
+        const persistedFreshness = selectFreshnessReport(db, repository.id);
+        const freshness = freshnessFor(persistedFreshness);
+        if (request.mode === 'full')
+            return fullScope(db, repository, graphScope, databasePath, request, freshness);
+        return anchorScope(db, repository, graphScope, databasePath, request, freshness);
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function fullScope(db, repository, scope, databasePath, request, freshness) {
+    const allAggregates = selectExploreAggregates(db, repository.id);
+    let searchState = { term: request.search ?? null, matchedNodeIds: [], containingAggregateIds: [] };
+    let aggregates = allAggregates;
+    let matchingSources = [];
+    if (request.search?.trim()) {
+        const normalized = request.search.trim().toLocaleLowerCase();
+        matchingSources = selectExploreSourcesForSearch(db, repository.id, request.search, 200);
+        const matchedNodeIds = matchingSources.map((row) => row.id);
+        const containingAggregateIds = [...new Set(matchingSources.flatMap((row) => row.fileId ? [aggregateId(repository.id, row.fileId)] : []))];
+        const matchingFiles = new Set(containingAggregateIds);
+        aggregates = allAggregates.filter((row) => matchingFiles.has(row.id) || row.path.toLocaleLowerCase().includes(normalized));
+        searchState = { term: request.search.trim(), matchedNodeIds, containingAggregateIds };
+    }
+    const aggregateNodes = aggregates.map((row) => aggregateNode(row, repository.id, scope));
+    const nodes = [...aggregateNodes, ...matchingSources.map((row) => sourceNode(row, repository.id, scope))];
+    const aggregateIds = new Set(aggregateNodes.map((node) => node.id));
+    const edges = selectExploreAggregateEdges(db, repository.id, request.relationshipKinds)
+        .filter((edge) => aggregateIds.has(edge.sourceAggregateId) && aggregateIds.has(edge.targetAggregateId))
+        .map((edge) => ({ id: edge.id, sourceId: edge.sourceAggregateId, targetId: edge.targetAggregateId, kind: edge.kind, confidence: edge.confidence, direction: 'forward', metadata: edge.metadata, count: edge.count, expansionKey: `aggregate-expand:${edge.sourceAggregateId}:${edge.targetAggregateId}:${edge.kind}` }));
+    const state = nodes.length > 0 ? 'ok' : 'empty';
+    return {
+        scope, databasePath, freshness, state, mode: 'full', nodes, edges,
+        search: searchState, filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] },
+        truncation: noTruncation(request.nodeCap, request.edgeCap), expansionTargets: nodes.filter((node) => node.category === 'aggregate' && node.expandable).map((node) => node.expansionKey), warnings: freshnessWarnings(freshness)
+    };
+}
+function anchorScope(db, repository, scope, databasePath, request, freshness) {
+    const term = request.file ?? request.anchor ?? '';
+    const candidates = selectExploreCandidates(db, repository.id, term, { fileAnchor: Boolean(request.file), limit: request.candidateLimit });
+    const candidateContract = candidates.map(candidateContractFromRow);
+    const base = {
+        scope, databasePath, freshness, mode: 'anchor',
+        search: { term: null, matchedNodeIds: [], containingAggregateIds: [] },
+        filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] },
+        expansionTargets: [], warnings: freshnessWarnings(freshness)
+    };
+    if (candidates.length === 0)
+        return { ...base, state: 'not_found', nodes: [], edges: [], candidates: [], truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    if (candidates.length !== 1)
+        return { ...base, state: 'ambiguous', nodes: [], edges: [], candidates: candidateContract, truncation: noTruncation(request.nodeCap, request.edgeCap), warnings: [...base.warnings, 'Select one ranked candidate before traversal.'] };
+    const selected = candidates[0];
+    if (selected.kind === 'file' && selected.aggregateId) {
+        const aggregate = selectExploreAggregates(db, repository.id).find((row) => row.id === selected.aggregateId);
+        const node = aggregate ? aggregateNode(aggregate, repository.id, scope) : null;
+        return { ...base, state: node ? 'ok' : 'not_found', nodes: node ? [node] : [], edges: [], ...(node ? { anchor: node } : {}), candidates: candidateContract, expansionTargets: node ? [node.expansionKey] : [], truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    }
+    const anchor = selectExploreNode(db, repository.id, selected.id);
+    if (!anchor)
+        return { ...base, state: 'not_found', nodes: [], edges: [], candidates: candidateContract, truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    const traversal = traverse(db, repository.id, anchor, request);
+    const nodes = traversal.nodes.map((row) => sourceNode(row, repository.id, scope));
+    const anchorNode = nodes.find((node) => node.category === 'source' && node.id === anchor.id) ?? sourceNode(anchor, repository.id, scope);
+    return {
+        ...base, state: 'ok', nodes, edges: traversal.edges.map((edge) => edgeContract(edge, traversal.nodeIds)), anchor: anchorNode, candidates: candidateContract,
+        truncation: traversal.truncation, expansionTargets: [anchorNode.expansionKey ?? `node-expand:${anchorNode.id}`]
+    };
+}
+function traverse(db, repositoryId, anchor, request) {
+    const nodeIds = new Set([anchor.id]);
+    const allEdges = new Map();
+    let frontier = [anchor.id];
+    let omittedNodes = 0;
+    let omittedEdges = 0;
+    let deepestDepth = 0;
+    for (let depth = 1; depth <= request.depth && frontier.length > 0; depth += 1) {
+        const rows = selectExploreTraversalEdges(db, repositoryId, frontier, request.direction, request.relationshipKinds, request.edgeCap - allEdges.size + 1);
+        if (rows.length > request.edgeCap - allEdges.size)
+            omittedEdges += rows.length - Math.max(0, request.edgeCap - allEdges.size);
+        const uniqueRows = rows.filter((row) => !allEdges.has(row.id));
+        const adjacentIds = [...new Set(uniqueRows.flatMap((row) => adjacentFor(row, frontier, request.direction)))].filter((id) => !nodeIds.has(id));
+        const adjacentRows = selectExploreNodeRowsBounded(db, repositoryId, adjacentIds);
+        adjacentRows.sort(nodeOrder);
+        const available = Math.max(0, request.nodeCap - nodeIds.size);
+        const retained = adjacentRows.slice(0, available);
+        omittedNodes += Math.max(0, adjacentRows.length - retained.length);
+        for (const row of retained)
+            nodeIds.add(row.id);
+        const retainedIds = new Set(retained.map((row) => row.id));
+        for (const row of uniqueRows) {
+            if (allEdges.size >= request.edgeCap) {
+                omittedEdges += 1;
+                continue;
+            }
+            if (nodeIds.has(row.sourceId) && nodeIds.has(row.targetId))
+                allEdges.set(row.id, row);
+            else if (retainedIds.has(row.sourceId) || retainedIds.has(row.targetId))
+                omittedEdges += 1;
+        }
+        const next = retained.map((row) => row.id);
+        if (next.length === 0)
+            break;
+        frontier = next;
+        deepestDepth = depth;
+    }
+    const rows = selectExploreNodeRowsBounded(db, repositoryId, [...nodeIds]);
+    rows.sort(nodeOrder);
+    return { nodes: rows, nodeIds, edges: [...allEdges.values()], truncation: { bounded: omittedNodes > 0 || omittedEdges > 0, nodeCap: request.nodeCap, edgeCap: request.edgeCap, omittedNodes, omittedEdges, deepestDepth } };
+}
+function adjacentFor(row, frontier, direction) {
+    const hasSource = frontier.includes(row.sourceId);
+    const hasTarget = frontier.includes(row.targetId);
+    if (direction === 'incoming')
+        return hasTarget ? [row.sourceId] : [];
+    if (direction === 'outgoing')
+        return hasSource ? [row.targetId] : [];
+    return [...(hasSource ? [row.targetId] : []), ...(hasTarget ? [row.sourceId] : [])];
+}
+function edgeContract(edge, nodeIds) {
+    return { id: edge.id, sourceId: edge.sourceId, targetId: edge.targetId, kind: edge.kind, confidence: edge.confidence, direction: 'forward', metadata: edge.metadata };
+}
+function selectExploreNodeRowsBounded(db, repositoryId, ids) {
+    const rows = [];
+    for (let index = 0; index < ids.length; index += 500)
+        rows.push(...selectExploreNodeRows(db, repositoryId, ids.slice(index, index + 500)));
+    return rows;
+}
+function aggregateNode(row, repositoryId, scope) {
+    return { id: row.id, category: 'aggregate', kind: 'file', name: row.path, identity: { repositoryId, scope, path: row.path, qualifiedName: row.path }, path: row.path, language: row.language, expandable: row.childCount > 0, expansionKey: `aggregate-expand:${row.id}`, childCount: row.childCount };
+}
+function sourceNode(row, repositoryId, scope) {
+    return { id: row.id, category: 'source', kind: row.kind, type: row.type, name: row.name, identity: { repositoryId, scope, path: row.path, qualifiedName: row.name && row.path ? `${row.path}:${row.name}` : row.name }, path: row.path, span: { start: row.startPoint, end: row.endPoint }, metadata: row.metadata, ...(row.fileId ? { expansionKey: `aggregate-expand:${aggregateId(repositoryId, row.fileId)}` } : {}) };
+}
+function candidateContractFromRow(row) {
+    return { id: row.id, rank: row.rank, match: row.match, category: row.aggregateId && row.id === row.aggregateId ? 'aggregate' : 'source', kind: row.kind, name: row.name, qualifiedName: row.qualifiedName, path: row.path, ...(row.kind === 'file' ? {} : { span: { start: row.startPoint, end: row.endPoint } }) };
+}
+function freshnessFor(report) {
+    const message = report.state === 'fresh' ? 'Stored graph is fresh.' : report.state === 'degraded' ? 'Stored graph is degraded; some scan facts were retained.' : 'Stored graph is stale; Explore does not scan implicitly.';
+    return report.state === 'fresh'
+        ? { state: report.state, ...(report.reason ? { reason: report.reason } : {}), message }
+        : { state: report.state, ...(report.reason ? { reason: report.reason } : {}), message, recovery: 'Run lscg scan explicitly to refresh the stored graph.' };
+}
+function missingFreshness(databasePath) { return { state: 'missing', reason: 'missing_database', message: `No stored graph was found at ${databasePath}.`, recovery: 'Run lscg scan explicitly, then retry Explore.' }; }
+function freshnessWarnings(freshness) { return freshness.state === 'fresh' ? [] : [freshness.message, ...(freshness.recovery ? [freshness.recovery] : [])]; }
+function noTruncation(nodeCap, edgeCap) { return { bounded: false, nodeCap, edgeCap, omittedNodes: 0, omittedEdges: 0, deepestDepth: 0 }; }
+function emptyScope(scope, databasePath, request, freshness) { return { scope, databasePath, freshness, state: 'empty', mode: request.mode, nodes: [], edges: [], search: { term: request.search ?? null, matchedNodeIds: [], containingAggregateIds: [] }, filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] }, truncation: noTruncation(request.nodeCap, request.edgeCap), expansionTargets: [], warnings: freshnessWarnings(freshness) }; }
+function normalizeKinds(kinds) { return [...new Set((kinds ?? EXPLORE_EDGE_KINDS).filter((kind) => EXPLORE_EDGE_KINDS.includes(kind)))]; }
+function clamp(value, min, max, fallback) { return value === undefined || !Number.isFinite(value) ? fallback : Math.max(min, Math.min(max, Math.trunc(value))); }
+function nodeOrder(a, b) { return `${a.path ?? ''}:${a.name ?? ''}:${a.id}`.localeCompare(`${b.path ?? ''}:${b.name ?? ''}:${b.id}`); }
+function diagnostic(error) { return error instanceof Error ? error.message : String(error); }
+//# sourceMappingURL=explore.js.map