@psnext/lscg 0.1.1

package/dist/src/cli.js

@@ -0,0 +1,524 @@
+import { startMcpServer } from './mcp/server.js';
+import { buildViewModel, loadViewSnapshot, renderSvgMarkup, viewGraph } from './view/index.js';
+import { watchRepository } from './watch.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',
+    'callgraph', 'context', 'query', 'view', 'mcp'
+]);
+export async function runCli(argv) {
+    const [command = 'help', ...rest] = argv;
+    if (operationalCommands.has(command) && rest.some((arg) => arg === '--help' || arg === '-h')) {
+        console.log(commandHelpText(command));
+        return;
+    }
+    const options = parseOptions(rest);
+    switch (command) {
+        case 'init':
+            printJson(initGraph({ root: options.root, scope: options.scope ?? 'repo' }));
+            return;
+        case 'scan':
+            if (options.watch) {
+                await watchRepository({ root: options.root, scope: options.scope ?? 'repo' }, { mode: 'scan --watch' });
+                return;
+            }
+            printJson(await scanRepository({ root: options.root, scope: options.scope ?? 'repo' }));
+            return;
+        case 'watch':
+            await watchRepository({ root: options.root, scope: options.scope ?? 'repo' }, { mode: 'watch' });
+            return;
+        case 'status':
+            printJson(graphStatus({ root: options.root, scope: options.scope ?? 'repo' }));
+            return;
+        case 'nodes': {
+            const output = options.output ?? 'json';
+            if (output === 'json') {
+                printJson(listNodes({
+                    root: options.root,
+                    scope: options.scope ?? 'repo',
+                    kind: options.kind,
+                    limit: options.limit
+                }));
+                return;
+            }
+            if (output === 'text') {
+                console.log(formatNodesText(listNodeText({
+                    root: options.root,
+                    scope: options.scope ?? 'repo',
+                    kind: options.kind,
+                    term: options._[0],
+                    limit: options.limit
+                })));
+                return;
+            }
+            throw new Error(`nodes output must be json or text, got: ${output}`);
+        }
+        case 'edges':
+            printJson(listEdges({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                kind: options.kind,
+                limit: options.limit
+            }));
+            return;
+        case 'neighbors': {
+            const nodeId = options._[0] ?? options.nodeId;
+            printJson(neighbors({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                nodeId,
+                depth: options.depth,
+                limit: options.limit
+            }));
+            return;
+        }
+        case 'context': {
+            validateContextOptions(options, rest);
+            const symbol = options._[0];
+            if (!symbol)
+                throw new Error('context requires a symbol');
+            const result = await contextGraph({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                symbol,
+                kind: options.kind,
+                file: options.file,
+                depth: options.depth,
+                limit: options.limit,
+                candidateLimit: options.candidateLimit,
+                excerptLines: options.excerptLines,
+                excerptBytes: options.excerptBytes,
+                excerpts: options.excerpts
+            });
+            const output = options.output ?? 'text';
+            if (output === 'json') {
+                printJson(result);
+                return;
+            }
+            if (output === 'text') {
+                console.log(formatContextText(result));
+                return;
+            }
+            if (output === 'svg') {
+                console.log(formatContextSvg(result, { root: options.root, scope: options.scope ?? 'repo' }));
+                return;
+            }
+            throw new Error(`context output must be json, text, or svg, got: ${output}`);
+        }
+        case 'callgraph': {
+            const results = callGraph({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                term: options._[0],
+                kind: options.kind,
+                depth: options.depth,
+                limit: options.limit
+            });
+            const output = options.output ?? 'text';
+            if (output === 'json') {
+                printJson(results);
+                return;
+            }
+            if (output === 'text') {
+                console.log(formatCallGraphText(results));
+                return;
+            }
+            if (output === 'svg') {
+                console.log(formatCallGraphSvg(results, { root: options.root, scope: options.scope ?? 'repo' }));
+                return;
+            }
+            throw new Error(`callgraph output must be json, text, or svg, got: ${output}`);
+        }
+        case 'query': {
+            const sql = options.sql ?? options._.join(' ');
+            printJson(runReadOnlySql({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                sql,
+                attachHome: Boolean(options.attachHome),
+                limit: options.limit
+            }));
+            return;
+        }
+        case 'view':
+            printJson(await viewGraph({
+                root: options.root,
+                scope: options.scope ?? 'repo',
+                anchor: options.anchor,
+                search: options.search,
+                output: options.output
+            }));
+            return;
+        case 'mcp':
+            await startMcpServer({ root: options.root });
+            return;
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(helpText());
+            return;
+        default:
+            throw new Error(`Unknown command: ${command}\n\n${helpText()}`);
+    }
+}
+function parseOptions(args) {
+    const options = { _: [] };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        const shortOption = /^-([rskdlf])(?:=(.*))?$/.exec(arg);
+        if (shortOption) {
+            const keyByAlias = {
+                r: 'root',
+                s: 'scope',
+                k: 'kind',
+                d: 'depth',
+                l: 'limit',
+                f: 'file'
+            };
+            const key = keyByAlias[shortOption[1]];
+            const inlineValue = shortOption[2];
+            if (inlineValue !== undefined) {
+                options[key] = coerce(inlineValue);
+                continue;
+            }
+            const next = args[index + 1];
+            if (next && !next.startsWith('-')) {
+                options[key] = coerce(next);
+                index += 1;
+            }
+            else {
+                options[key] = true;
+            }
+            continue;
+        }
+        if (arg === '-o' || arg.startsWith('-o=')) {
+            const inlineValue = arg.startsWith('-o=') ? arg.slice(3) : undefined;
+            if (inlineValue !== undefined) {
+                options.output = coerce(inlineValue);
+                continue;
+            }
+            const next = args[index + 1];
+            if (next && !next.startsWith('-')) {
+                options.output = coerce(next);
+                index += 1;
+            }
+            else {
+                options.output = true;
+            }
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            options._.push(arg);
+            continue;
+        }
+        const [rawKey, inlineValue] = arg.slice(2).split('=', 2);
+        if (!rawKey)
+            continue;
+        const key = toCamelCase(rawKey);
+        if (inlineValue !== undefined) {
+            options[key] = coerce(inlineValue);
+            continue;
+        }
+        const next = args[index + 1];
+        const booleanOption = key === 'watch' || key === 'attachHome' || key === 'excerpts' || key === 'help';
+        if (!booleanOption && next && !next.startsWith('--')) {
+            options[key] = coerce(next);
+            index += 1;
+        }
+        else {
+            options[key] = true;
+        }
+    }
+    return options;
+}
+function validateContextOptions(options, args) {
+    const allowed = new Set(['root', 'scope', 'kind', 'file', 'depth', 'limit', 'candidate-limit', 'excerpt-lines', 'excerpt-bytes', 'excerpts', 'output', 'help']);
+    const seen = new Set();
+    for (const arg of args) {
+        if (!arg.startsWith('--'))
+            continue;
+        const key = arg.slice(2).split('=', 1)[0] ?? '';
+        if (!allowed.has(key))
+            throw new Error(`unknown context option --${key}`);
+        if (seen.has(key) && key !== 'help')
+            throw new Error(`context option --${key} may only be provided once`);
+        seen.add(key);
+    }
+    if (options._.length !== 1)
+        throw new Error('context requires exactly one symbol');
+    const numeric = [
+        ['depth', options.depth, 0, 5],
+        ['limit', options.limit, 1, 500],
+        ['candidate-limit', options.candidateLimit, 1, 100],
+        ['excerpt-lines', options.excerptLines, 1, 500],
+        ['excerpt-bytes', options.excerptBytes, 1, 100_000]
+    ];
+    for (const [name, value, minimum, maximum] of numeric) {
+        if (value !== undefined && (!Number.isInteger(value) || value < minimum || value > maximum)) {
+            throw new Error(`context --${name} must be an integer between ${minimum} and ${maximum}`);
+        }
+    }
+    if (options.scope !== undefined && options.scope !== 'repo' && options.scope !== 'home' && options.scope !== 'both') {
+        throw new Error('context --scope must be repo, home, or both');
+    }
+    if (options.output !== undefined && options.output !== 'json' && options.output !== 'text' && options.output !== 'svg') {
+        throw new Error('context --output must be json, text, or svg');
+    }
+}
+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`,
+        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`,
+        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`,
+        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];
+    if (!commandHelp)
+        return helpText();
+    return `${commandHelp}\n\nShort aliases (where supported): -r --root, -s --scope, -k --kind, -d --depth, -l --limit, -f --file, -o --output.`;
+}
+function toCamelCase(value) {
+    return value.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+function coerce(value) {
+    if (/^\d+$/.test(value))
+        return Number(value);
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return value;
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function formatNodesText(nodes) {
+    if (nodes.length === 0)
+        return 'No matching nodes.';
+    return nodes.map((node) => [
+        `${node.scope}: ${node.root}`,
+        `node: ${node.name ?? '<unnamed>'} <${node.kind}/${node.type}> (${node.id})`,
+        `file: ${node.path ?? '<unknown>'}`,
+        `lines: ${node.startPoint.row + 1}-${node.endPoint.row + 1}`
+    ].join('\n')).join('\n\n');
+}
+function formatContextText(result) {
+    return result.scopes.map((scope) => {
+        const lines = [`scope: ${scope.scope}`, `state: ${scope.result.state}`, `freshness: ${scope.freshness.state}`];
+        const anchor = scope.result.anchor ?? scope.result.candidates?.[0];
+        if (anchor) {
+            lines.push(`anchor: ${anchor.name ?? '<unnamed>'} [${anchor.kind}/${anchor.type}] ${anchor.path ?? '<unknown>'}:${anchor.span.start.row + 1}`);
+            if (anchor.excerpt !== undefined) {
+                lines.push('snippet:');
+                lines.push(...anchor.excerpt.split(/\r?\n/).map((line) => `  ${line}`));
+            }
+        }
+        if (scope.result.candidates?.length) {
+            lines.push('candidates:');
+            lines.push(...scope.result.candidates.map((candidate) => `  - ${candidate.name ?? '<unnamed>'} [${candidate.kind}] ${candidate.path ?? '<unknown>'}:${candidate.span.start.row + 1}`));
+        }
+        lines.push('impact:');
+        lines.push(...formatContextRelations(scope.result.impact));
+        lines.push('dependencies:');
+        lines.push(...formatContextRelations(scope.result.dependencies));
+        if (scope.result.warnings.length)
+            lines.push(`warnings: ${scope.result.warnings.join(', ')}`);
+        return lines.join('\n');
+    }).join('\n\n');
+}
+function formatContextRelations(relations) {
+    if (relations.length === 0)
+        return ['  (none)'];
+    return relations.map((relation) => `  - ${relation.direction} ${relation.target.name ?? '<unnamed>'} [${relation.edgeKind}] depth=${relation.depth} ${relation.target.path ?? '<unknown>'}:${relation.target.span.start.row + 1}`);
+}
+function formatContextSvg(result, { root, scope }) {
+    if (scope === 'both')
+        throw new Error('context output svg does not support --scope both');
+    const scopeResult = result.scopes[0];
+    if (!scopeResult)
+        throw new Error('context output svg has no scope result');
+    const snapshot = loadViewSnapshot({ root, scope });
+    const ids = new Set();
+    const addReference = (reference) => { if (reference)
+        ids.add(reference.id); };
+    addReference(scopeResult.result.anchor);
+    for (const candidate of scopeResult.result.candidates ?? [])
+        addReference(candidate);
+    for (const relation of [...scopeResult.result.impact, ...scopeResult.result.dependencies]) {
+        addReference(relation.source);
+        addReference(relation.target);
+    }
+    const filteredSnapshot = {
+        ...snapshot,
+        nodes: snapshot.nodes.filter((node) => ids.has(node.id)),
+        edges: snapshot.edges.filter((edge) => ids.has(edge.sourceId) && ids.has(edge.targetId))
+    };
+    return renderSvgMarkup(buildViewModel(filteredSnapshot), { includeHiddenNodes: true, interactive: false });
+}
+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:');
+        lines.push(...formatCallGraphRelations(match.upstream));
+        lines.push('  downstream:');
+        lines.push(...formatCallGraphRelations(match.downstream));
+        return lines.join('\n');
+    }).join('\n\n');
+}
+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})`);
+}
+function formatCallGraphSvg(results, { root, scope }) {
+    if (scope === 'both')
+        throw new Error('callgraph svg output does not support --scope both');
+    const snapshot = loadViewSnapshot({ root, scope });
+    const visibleIds = new Set(results.flatMap((match) => [
+        match.id,
+        ...match.upstream.map((node) => node.id),
+        ...match.downstream.map((node) => node.id)
+    ]));
+    const filteredSnapshot = {
+        ...snapshot,
+        nodes: snapshot.nodes.filter((node) => visibleIds.has(node.id)),
+        edges: snapshot.edges.filter((edge) => visibleIds.has(edge.sourceId) && visibleIds.has(edge.targetId))
+    };
+    return renderSvgMarkup(buildViewModel(filteredSnapshot), { includeHiddenNodes: true, interactive: false });
+}
+function helpText() {
+    return `lscg - local source context graphs
+
+Usage:
+  lscg <command> [options]
+
+Commands:
+  init      Create graph storage for the selected scope.
+  scan      Parse repository files and write discovered graph data.
+  watch     Keep the repository current by rescanning on file changes.
+  status    Show graph counts and database paths.
+  nodes     List graph nodes.
+  edges     List graph edges.
+  neighbors Show nearby nodes around a graph node id.
+  callgraph Find nodes whose names contain a term and show upstream/downstream nodes.
+  context   Retrieve bounded definition, impact, and dependency context.
+  query     Run a read-only SQLite query against the graph database.
+  view      Open an interactive graph view or export a static SVG.
+  mcp       Start the MCP server over stdio.
+  help      Show this help text.
+
+Command options:
+  init:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to initialize (default: repo).
+  scan:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to scan (default: repo).
+    --watch                     Watch and rescan after the initial scan.
+  watch:
+    --root path                 Repository root (default: current directory).
+    --scope repo                Repository scope to watch (default: repo).
+  status:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to inspect (default: repo).
+  nodes [term]:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to inspect (default: repo).
+    --kind node-kind             Filter by node kind.
+    --limit n                   Maximum number of nodes (default: 50).
+    --output json|text           Output format (default: json).
+  edges:
+    --root path                 Repository root (default: current directory).
+    --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).
+  neighbors <node-id>:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to inspect (default: repo).
+    --depth n                   Traversal depth (default: 1).
+    --limit n                   Maximum number of neighbors (default: 100).
+    --node-id id                Node ID alternative to the positional argument.
+  context <symbol>:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to inspect (default: repo).
+    --kind node-kind            Constrain anchor candidates by node kind.
+    --file relative/path        Constrain anchor candidates by repository-relative path.
+    --depth n                   Relationship depth (default: 2, maximum: 5).
+    --limit n                   Relationships per section (default: 50, maximum: 500).
+    --candidate-limit n         Maximum ranked candidates (default: 20, maximum: 100).
+    --excerpt-lines n           Opt-in excerpt line budget (default: 80, maximum: 500).
+    --excerpt-bytes n           Opt-in excerpt byte budget (default: 12000, maximum: 100000).
+    --excerpts                  Include bounded source excerpts.
+    --output json|text|svg       Output format (default: text).
+  callgraph <term>:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to inspect (default: repo).
+    --kind node-kind             Filter matching nodes by kind.
+    --depth n                   Upstream/downstream traversal depth (default: 5).
+    --limit n                   Maximum matches and relations (default: 100).
+    --output json|text|svg      Output format (default: text).
+  query <sql>:
+    --root path                 Repository root (default: current directory).
+    --scope repo|home|both      Storage scope to query (default: repo).
+    --sql "select ..."          SQL alternative to the positional argument.
+    --attach-home               Attach the home database when querying repo scope.
+    --limit n                   Maximum rows (default: 200).
+  view:
+    --root path                 Repository root (default: current directory).
+    --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.
+    --output path               Write an SVG snapshot instead of opening a browser.
+  mcp:
+    --root path                 Repository root for the MCP server (default: current directory).
+
+Short aliases:
+  -r path                       Alias for --root.
+  -s value                      Alias for --scope.
+  -k value                      Alias for --kind.
+  -d n                          Alias for --depth.
+  -l n                          Alias for --limit.
+  -f path                       Alias for --file.
+  -o value                      Alias for --output.
+
+Examples:
+  lscg init --scope both
+  lscg scan --scope both
+  lscg watch
+  lscg nodes --kind user --limit 20
+  lscg edges --kind calls --limit 20
+  lscg neighbors <node-id> --depth 2
+  lscg context greet --depth 2 --kind symbol
+  lscg context greet --excerpts --excerpt-lines 40
+  lscg callgraph greet --depth 2
+  lscg callgraph greet --output text
+  lscg callgraph greet --output svg
+  lscg query "select kind, count(*) as n from nodes group by kind"
+  lscg view --anchor greet --search util
+  lscg view --output graph.svg
+
+Notes:
+  - lscg context is for indexed source context; use rg/grep for literal discovery.
+  - Context relationships are syntax-grounded and may require source verification.
+  - 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.
+
+Storage:
+  repo: <root>/.sling/graph.sqlite
+  home: ~/.sling/graph.sqlite
+`;
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/config/paths.d.ts

@@ -0,0 +1,12 @@
+import type { GraphScope, StorageScope } from '../types.js';
+export declare const GRAPH_DIR_NAME = ".sling";
+export declare const GRAPH_DATABASE_NAME = "graph.sqlite";
+export declare function resolveProjectRoot(input?: string): string;
+export declare function repoGraphDir(root?: string): string;
+export declare function homeGraphDir(): string;
+export declare function repoDatabasePath(root?: string): string;
+export declare function homeDatabasePath(): string;
+export declare function databasePathForScope(scope: StorageScope, root?: string): string;
+export declare function ensureGraphDirForScope(scope: StorageScope, root?: string): string;
+export declare function normalizeScope(scope?: GraphScope): StorageScope[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/config/paths.js

@@ -0,0 +1,54 @@
+import { mkdirSync, realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+export const GRAPH_DIR_NAME = '.sling';
+export const GRAPH_DATABASE_NAME = 'graph.sqlite';
+export function resolveProjectRoot(input = process.cwd()) {
+    const resolvedPath = realpathSync(path.resolve(input));
+    const gitRoot = detectGitRoot(resolvedPath);
+    return gitRoot ?? resolvedPath;
+}
+export function repoGraphDir(root = process.cwd()) {
+    return path.join(resolveProjectRoot(root), GRAPH_DIR_NAME);
+}
+export function homeGraphDir() {
+    return path.join(os.homedir(), GRAPH_DIR_NAME);
+}
+export function repoDatabasePath(root = process.cwd()) {
+    return path.join(repoGraphDir(root), GRAPH_DATABASE_NAME);
+}
+export function homeDatabasePath() {
+    return path.join(homeGraphDir(), GRAPH_DATABASE_NAME);
+}
+export function databasePathForScope(scope, root = process.cwd()) {
+    if (scope === 'repo')
+        return repoDatabasePath(root);
+    if (scope === 'home')
+        return homeDatabasePath();
+    throw new Error(`Unknown graph scope: ${scope}`);
+}
+export function ensureGraphDirForScope(scope, root = process.cwd()) {
+    const dir = scope === 'repo' ? repoGraphDir(root) : homeGraphDir();
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function normalizeScope(scope = 'repo') {
+    if (scope === 'both')
+        return ['repo', 'home'];
+    if (scope === 'repo' || scope === 'home')
+        return [scope];
+    throw new Error(`Expected --scope repo|home|both, got ${scope}`);
+}
+function detectGitRoot(startPath) {
+    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+        cwd: startPath,
+        encoding: 'utf8'
+    });
+    if (result.status !== 0 || result.error) {
+        return null;
+    }
+    const gitRoot = result.stdout.trim();
+    return gitRoot.length > 0 ? gitRoot : null;
+}
+//# sourceMappingURL=paths.js.map

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

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