@psnext/lscg 0.1.4 → 0.1.6

package/README.md

@@ -119,9 +119,12 @@ prefix and substring matches; an ambiguous match returns ranked candidates
 instead of merging unrelated symbols. Use `--kind` and repository-relative
 `--file` to disambiguate. Results are references by default; `--excerpts` opts
 into bounded source text with `--excerpt-lines` and `--excerpt-bytes` limits.
-The command compares a cheap path/size/mtime fingerprint with indexed files and
-reports whether the graph was reused or refreshed. This metadata check is not a
-content-verification guarantee for same-size edits with restored mtimes.
+Graph-reading commands never start a scan. Their Freshness Report reflects the
+stored graph state: `fresh` after a successful explicit scan, `stale` when no
+compatible graph exists or a known invalidation remains, and `degraded` when a
+retained failed-file or plugin contribution is being served. Run `scan` or keep
+`watch` active after source changes; a stored `fresh` result is not a live
+filesystem content-verification guarantee.
 
 Impact contains only syntax-grounded `calls` edges (with caller/callee
 direction), and dependencies contain `imports`/`exports`; parser confidence
@@ -130,14 +133,78 @@ Substring fallback is intentionally reported as a bounded capability warning.
 Use `rg` or `grep` for literal discovery when a term is not indexed—`context`
 does not replace arbitrary text search or claim complete semantic resolution.
 
+`lscg scan` performs an Explicit Scan. After the first scan, its default mode
+is incremental: it retains unchanged file graphs and reprocesses files whose
+path, size, or mtime metadata changed. Use `lscg scan --full` when you need a
+complete rebuild and content verification (including same-size edits with
+restored mtimes).
+
 `lscg watch` keeps the selected repository current in the foreground. It runs
 one scan immediately, then watches scanner-relevant files and prints compact
-status updates between rescans. Use `lscg scan` when you want the full one-shot
-scan output.
+status updates between rescans. `lscg scan --watch` provides the same Watch
+Session from the scan command. Use `lscg scan` when you want the one-shot scan
+output.
+
+Pass `--progress` to `scan`, `watch`, or `scan --watch` for line-oriented,
+human-readable lifecycle messages on stderr while the existing JSON summary or
+Watch Session events remain on stdout. For example:
+
+```bash
+npm start -- scan --progress >summary.json
+npm start -- watch --progress >watch-events.jsonl
+npm start -- scan --watch --progress >watch-events.jsonl
+```
 
-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.
+Progress labels discovery/planning, plugin work, file processing,
+reconciliation, and optional enrichment. A normal scan may report structural
+completion with enrichment deferred or degraded; a Full Scan reports retries
+and only reports stabilized completion after its enrichment loop succeeds.
+Progress is informational rather than a stable machine-readable protocol, and
+it does not provide cancellation or animated progress bars.
+
+## Scan/watch benchmark
+
+Run the non-blocking benchmark with:
+
+```bash
+npm run benchmark:scan-watch
+```
+
+The versioned JSON report separates two cold timings for this lscg checkout:
+
+- `coldNormalStructuralReady`: a normal scan's return after its structural
+  graph is persisted, before optional enrichment completes.
+- `coldFullEnrichmentComplete`: a cold `scan --full` completion, including its
+  required enrichment drain.
+
+Every cold sample uses an isolated copy with no pre-existing graph database;
+source and Git metadata are copied so the normal and full scans exercise the
+same source graph and optional attribution path without changing this checkout.
+The report records SHA-256 fingerprints plus structural node/edge counts before
+normal-scan enrichment and after that scan's pending enrichment work drains.
+`structuralEquivalence` must be `true`: user nodes, `attributed_to` edges, and
+per-node attribution are
+intentionally excluded because they are optional enrichment rather than source
+structure.
+
+`coldNormalStructuralReadyTarget` reports the 3.43-second baseline, the
+2.06-second median target (the required 40% reduction), the measured p50, and
+whether that run met the target. Timing values and target status are benchmark
+results for the documented machine/run, not unit-test thresholds. Use multiple
+cold samples for review (the default is 10); pass `-- --repetitions 5` to change
+the sample count.
+
+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.
+
+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
 
@@ -147,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',
@@ -172,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
@@ -190,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`,
@@ -203,7 +290,22 @@ listed in `plugins`.
 
 ## Current parser support
 
-The starter scanner supports JavaScript, JSX, TypeScript, and TSX via
-Tree-sitter. The extraction layer records syntax-grounded edges such as
-`defines`, `contains`, `imports`, `exports`, and `calls`. Cross-file symbol
-resolution should be added as language-specific semantic enrichers.
+The scanner supports JavaScript, JSX, TypeScript, TSX, Python, and Java via
+Tree-sitter. Python is handled by the bundled `PythonScannerPlugin`, and Java
+by `JavaScannerPlugin` using the pinned native `tree-sitter-java@0.21.0`
+grammar. Java records syntax-grounded classes, interfaces, enums, records,
+annotation types, methods, constructors, fields, imports, method invocations,
+containment, and explicit-public export approximations. Java calls/imports are
+occurrences (no type, overload, constructor, or cross-file resolution), and
+inherited/module APIs are not modeled. A Java parse error retains the prior
+file contribution and marks freshness degraded until the file recovers.
+
+Repositories with root or immediate-module `pom.xml`, `build.gradle`, or
+`build.gradle.kts` files also receive `java-dependency` `package` nodes from
+`JavaDependencyPlugin`. Manifest reading is bounded and non-executing; only
+literal Maven coordinates/properties and literal Gradle dependency calls are
+modeled. Dependencies remain independent from Java imports: no heuristic
+coordinate matching or dependency-to-import edges are emitted. Native
+Tree-sitter install scripts must remain allowlisted for clean installs.
+Cross-file symbol resolution remains a language-specific semantic-enricher
+concern.

package/dist/src/cli-progress.d.ts

@@ -0,0 +1,7 @@
+import type { ProgressReporter } from './types.js';
+export interface ProgressWriter {
+    (text: string): void;
+}
+/** Create a deterministic, line-oriented renderer for the stderr channel. */
+export declare function createProgressReporter(write?: ProgressWriter): ProgressReporter;
+//# sourceMappingURL=cli-progress.d.ts.map

package/dist/src/cli-progress.js

@@ -0,0 +1,59 @@
+/** Create a deterministic, line-oriented renderer for the stderr channel. */
+export function createProgressReporter(write = (text) => process.stderr.write(`${text}\n`)) {
+    const skippedByAttempt = new Map();
+    return (event) => {
+        const line = event.kind === 'scan'
+            ? renderScan(event, skippedByAttempt)
+            : renderWatch(event);
+        if (line)
+            write(line);
+    };
+}
+function renderScan(event, skippedByAttempt) {
+    const prefix = `[${event.operation} scan scope=${event.scope}]`;
+    if (event.phase === 'discovery' && event.status === 'started')
+        return `${prefix} discovery/planning: discovering files`;
+    if (event.phase === 'discovery' && event.status === 'completed') {
+        const c = event.counts ?? {};
+        return `${prefix} discovery/planning: discovered=${c.discovered ?? 0} selected=${c.selected ?? 0} unchanged=${c.unchanged ?? 0} deleted=${c.deleted ?? 0}`;
+    }
+    if (event.phase === 'plugins' && event.status === 'started')
+        return `${prefix} plugin work: starting plugins=${event.counts?.plugins ?? 0}`;
+    if (event.phase === 'plugins') {
+        const c = event.counts ?? {};
+        const suffix = event.detail ? ` (${event.detail})` : '';
+        return `${prefix} plugin work: plugins=${c.plugins ?? 0} failed=${c.failedPlugins ?? 0}${suffix}`;
+    }
+    if (event.phase === 'files' && event.status === 'started')
+        return `${prefix} file processing: selected=${event.counts?.selected ?? 0}`;
+    if (event.phase === 'files' && event.status === 'processed')
+        return `${prefix} file processing: processed=${event.counts?.processed ?? 0} skipped=${event.counts?.skipped ?? 0}`;
+    if (event.phase === 'files' && event.status === 'skipped') {
+        const key = `${event.operation}:${event.attempt ?? 1}`;
+        const count = (skippedByAttempt.get(key) ?? 0) + 1;
+        skippedByAttempt.set(key, count);
+        if (count <= 3)
+            return `${prefix} warning: skipped ${event.path ?? '<unknown>'}${event.detail ? ` (${event.detail})` : ''}`;
+        if (count === 4)
+            return `${prefix} warning: additional skipped files omitted (showing first 3)`;
+        return undefined;
+    }
+    if (event.phase === 'reconciliation' && event.status === 'started')
+        return `${prefix} reconciliation: starting deleted=${event.counts?.deleted ?? 0}`;
+    if (event.phase === 'reconciliation' && event.status === 'completed')
+        return `${prefix} reconciliation: complete processed=${event.counts?.processed ?? 0} skipped=${event.counts?.skipped ?? 0}`;
+    if (event.phase === 'enrichment' && event.status === 'started')
+        return `${prefix} enrichment: starting`;
+    if (event.phase === 'enrichment') {
+        const c = event.counts ?? {};
+        return `${prefix} enrichment: ${event.status} pending=${c.pending ?? 0} complete=${c.complete ?? 0} failed=${c.failed ?? 0}${event.detail ? ` (${event.detail})` : ''}`;
+    }
+    if (event.phase === 'terminal')
+        return `${prefix} ${event.status === 'failed' ? 'ERROR' : event.status === 'degraded' ? 'warning' : 'complete'}${event.detail ? `: ${event.detail}` : ''}`;
+    return undefined;
+}
+function renderWatch(event) {
+    const prefix = `[watch mode=${event.mode} scope=${event.scope}]`;
+    return `${prefix} ${event.event}${event.detail ? `: ${event.detail}` : ''}`;
+}
+//# sourceMappingURL=cli-progress.js.map

package/dist/src/cli.js

@@ -1,6 +1,9 @@
+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';
+import { createProgressReporter } from './cli-progress.js';
 import { graphStatus, initGraph, callGraph, contextGraph, listEdges, listNodes, listNodeText, neighbors, runReadOnlySql, scanRepository } from './graph/repository.js';
 const operationalCommands = new Set([
     'init', 'scan', 'watch', 'status', 'nodes', 'edges', 'neighbors',
@@ -13,20 +16,27 @@ export async function runCli(argv) {
         return;
     }
     const options = parseOptions(rest);
+    const progress = options.progress === true ? createProgressReporter() : undefined;
     switch (command) {
         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' });
+                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' }));
+            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' });
+        }
+        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;
@@ -58,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';
@@ -233,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 === 'attachHome' || key === 'excerpts' || key === 'help';
+        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;
@@ -286,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  --watch                     Watch and rescan after the initial scan.\n\nExamples:\n  lscg scan --scope both\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\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`,
@@ -303,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());
 }
@@ -479,10 +523,17 @@ Command options:
   scan:
     --root path                 Repository root (default: current directory).
     --scope repo|home|both      Storage scope to scan (default: repo).
+    --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).
@@ -496,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>:
@@ -570,6 +622,7 @@ Notes:
   - lscg view opens an interactive HTML page by default.
   - Pass --output to write a static SVG snapshot instead of opening the browser.
   - lscg watch supports repo scope only.
+  - --progress is opt-in human-readable diagnostics on stderr; stdout JSON is unchanged.
 
 Storage:
   repo: <root>/.sling/graph.sqlite

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/attribution.d.ts

@@ -1,8 +1,8 @@
-import type { GraphNode, FileAttribution } from '../types.js';
+import type { AttributionOutcome, GraphNode } from '../types.js';
 export declare function buildFileAttribution({ root, relativePath, source, nodes }: {
     root: string;
     relativePath: string;
     source: string;
     nodes: GraphNode[];
-}): FileAttribution | null;
+}): AttributionOutcome;
 //# sourceMappingURL=attribution.d.ts.map