@psnext/lscg 0.1.1

package/README.md

@@ -0,0 +1,143 @@
+# lscg
+
+Local source context graphs for repositories. `lscg` parses code with
+Tree-sitter, stores discovered nodes and edges in SQLite, and exposes the graph
+through both a CLI and an MCP server.
+
+## Requirements
+
+- Node.js 24+
+- npm install scripts allowed for Tree-sitter native packages
+
+## Install
+
+```bash
+npm install
+```
+
+## CLI
+
+Use global help to list commands, or ask any operational command for focused usage, supported options, and examples with `--help` or `-h`:
+
+```bash
+lscg --help
+lscg context --help
+lscg callgraph -h
+```
+
+The positional form `lscg <command> help` is not a command-help alias; `help` remains available as a normal command argument.
+
+Common option aliases are `-r`/`--root`, `-s`/`--scope`, `-k`/`--kind`, `-d`/`--depth`, `-l`/`--limit`, `-f`/`--file`, and `-o`/`--output` where the command supports the corresponding option. `callgraph` and `context` use text output by default; pass `--output json` when machine-readable JSON is needed.
+
+```bash
+# Create repo-local and home-level graph databases
+npm start -- init --scope both
+
+# Scan the current repository into both graph scopes
+npm start -- scan --scope both
+
+# Watch the current repository and rescan on scanner-relevant changes
+npm run watch
+npm run scan:watch
+npm start -- watch
+npm start -- scan --watch
+
+# Retrieve bounded context around a symbol (JSON envelope)
+npm start -- context greet --kind symbol
+npm start -- context greet --depth 2 --limit 25
+npm start -- context greet --file src/app.ts --excerpts --excerpt-lines 40 --excerpt-bytes 8000
+npm start -- context greet --output text
+npm start -- context greet --output svg > /tmp/context.svg
+
+# Inspect graph contents
+npm start -- status --scope repo
+npm start -- nodes --limit 20
+npm start -- nodes greet --kind symbol --limit 20
+npm start -- nodes greet --output text
+npm start -- edges --kind calls --limit 20
+npm start -- edges --kind attributed_to --limit 20
+npm start -- neighbors <node-id> --depth 2
+
+# Visualize the graph
+npm start -- view --scope repo
+npm start -- view --scope home --anchor greet --search util
+npm start -- view --output /tmp/lscg-view.svg
+
+# Run a read-only SQL query
+npm start -- query "select kind, count(*) as n from nodes group by kind"
+
+# Start the MCP server over stdio
+npm start -- mcp
+```
+
+When installed as a package, the binary names are `lscg` and `context-graph`.
+
+## MCP tools
+
+The MCP server exposes:
+
+- `context_graph_scan`
+- `context_graph_status`
+- `context_graph_nodes`
+- `context_graph_edges`
+- `context_graph_neighbors`
+- `context_graph_query`
+
+## Storage
+
+- Repo database: `.sling/graph.sqlite`
+- Home database: `~/.sling/graph.sqlite`
+
+Use `--scope repo`, `--scope home`, or `--scope both` on commands that read or
+write graph data.
+
+`lscg view` opens a temporary interactive HTML page by default and shows the
+anchor-centered subgraph for the selected scope when no `--anchor` is provided.
+The browser view includes a toggle to switch between the subgraph and the full
+graph. Pass `--search` to filter within the active graph mode, or `--output
+<path>` to write a static SVG snapshot of the default subgraph instead of
+opening a browser.
+
+Examples:
+
+```bash
+lscg view --anchor greet --search util
+lscg view --output graph.svg
+```
+
+`lscg context <symbol>` is the agent-oriented retrieval workflow. It returns a
+versioned JSON envelope with one result per selected scope by default. Use
+`--output text` for a concise human-readable summary or `--output svg` for a
+static graph of the returned context slice. Results distinguish
+`ok`, `ambiguous`, `not_found`, `refresh_failed`, and `stale` states from an
+empty context. Anchor matching prefers qualified/path and exact names before
+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.
+
+Impact contains only syntax-grounded `calls` edges (with caller/callee
+direction), and dependencies contain `imports`/`exports`; parser confidence
+and provenance are included so callers can verify relationships in source.
+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 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.
+
+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.
+
+## 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.

package/dist/bin/lscg.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=lscg.d.ts.map

package/dist/bin/lscg.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+try {
+    await runCli(process.argv.slice(2));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`lscg: ${message}`);
+    process.exitCode = 1;
+}
+//# sourceMappingURL=lscg.js.map

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(argv: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map