seer-mcp 0.1.0

package/docs/architecture.md

@@ -0,0 +1,105 @@
+# Architecture
+
+Seer turns a directory of source files into a small SQLite graph that an agent
+can query in milliseconds. This page is the high-level tour. For the lower-level
+decisions (caching, edge resolution, worker pooling), see
+[Implementation Notes](internals.md).
+
+---
+
+## The pipeline
+
+```mermaid
+flowchart TD
+    A[Workspace files] -->|.gitignore + .seerignore| B[Discovery]
+    B -->|worker thread pool| C[Tree-sitter parsing WASM]
+    C --> D[Language extractors]
+    D -->|symbols, calls, routes, config, hashes| E[(SQLite store, schema v10)]
+    E --> F[Post-pass resolution]
+    F --> G[Service-link resolver]
+    G --> H[Louvain clustering]
+    H --> I[CLI / MCP server]
+    I -->|JIT freshness check| J[AI agent]
+```
+
+1. **Discovery.** A fast directory walker respects layered `.gitignore` and
+   `.seerignore` rules and classifies each file as `project`, `test`,
+   `generated`, or `vendor`. Low-value files are dropped before they ever reach
+   a parser.
+2. **Parsing.** Files are parsed with Tree-sitter compiled to WASM, spread
+   across a pool of worker threads so a large repo is not bottlenecked on one V8
+   isolate.
+3. **Extraction.** Per-language extractors walk the AST and emit symbols
+   (with qualified names), call edges, routes, config reads, complexity metrics,
+   and structural shape hashes.
+4. **Storage.** Everything lands in one SQLite file, `<repo>/.seer/graph.db`,
+   under schema version 10. Writes are idempotent and incremental.
+5. **Resolution.** A post-pass links each call to the exact symbol it targets,
+   using a three-pass scope-aware strategy (same-file, then imported-file, then
+   global fallback).
+6. **Derived signals.** Service links, Louvain modules, shape hashes, and symbol
+   history are computed on top of the base graph (some during indexing, some
+   lazily on first query).
+
+---
+
+## What gets stored
+
+| Table | Holds |
+|---|---|
+| `files` | paths, hashes, language, role classification |
+| `symbols` | definitions with short + qualified names, roles, `is_rankable` |
+| `edges` | resolved caller/callee and import relationships |
+| `routes` | HTTP / tRPC / GraphQL / gRPC / message-queue handlers |
+| `service_calls` / `service_links` | outbound calls resolved to routes |
+| `modules` / `boundaries` | Louvain clusters and monorepo partitions |
+| `config_keys` | env/config reads mapped to their enclosing symbol |
+| `external_dependencies` | packages declared in manifests |
+| `external_bundles` | read-only layers imported from other repos |
+| `symbol_history_continuity` | resolved rename/move lineage |
+
+The full schema and table relationships are in [internals.md](internals.md).
+
+---
+
+## Three derived signals worth knowing
+
+These are where Seer goes beyond "structured grep".
+
+### Louvain modules
+Seer builds a weighted file graph (import edges weigh 2, call edges 1, test
+edges 3) and runs Louvain community detection. The result is a set of cohesive
+modules, so an agent can find the "auth" or "billing" subsystem before scanning
+directories.
+
+### Tests as behavioral specs
+Rather than a flat list of test files, `seer_behavior` ranks the tests that
+exercise a symbol by how directly they hit it: direct calls first, then naming
+conventions, then call-graph distance, then assertion density and recency.
+
+### Decomposed edit-risk
+`seer_risk` does not hand back a mystery number. It shows the components: caller
+fan-in, public route exposure, missing test coverage, monorepo boundary
+crossings, and complexity plus churn. The agent can see *why* a change is risky.
+
+---
+
+## Freshness
+
+Correctness is a product requirement. If an agent edits a file, the next query
+must reflect it.
+
+- A **Chokidar watcher** keeps the index warm in the background, debouncing
+  bursts of writes.
+- A **JIT freshness check** runs an instant hash comparison before any query
+  returns. Anything that changed is re-parsed serially right then, so results
+  are never stale, and concurrent reads are never blocked.
+
+---
+
+## Two product layers
+
+Seer-Core (this repository) is the deterministic, local, zero-AI engine
+described above. A separate Seer-Onboarding layer is designed to sit on top and
+translate these facts into human-facing visual walkthroughs. Everything in this
+repo is Core.

package/docs/benchmarks/methodology.md

@@ -0,0 +1,134 @@
+# Benchmark Methodology
+
+There are two very different kinds of claim in this project, and they need two
+very different kinds of evidence.
+
+- **Speed** is deterministic. It does not involve an LLM, so we can measure it
+  directly and reproducibly, and we do.
+- **Accuracy** and **token usage** are about how much Seer helps an *agent*.
+  That necessarily involves an LLM, so the numbers come from running real models
+  on a fixed task suite. Those measurements are in progress; this page describes
+  exactly how they are run so the results are honest and reproducible.
+
+Accuracy and token-usage measurements use: **GPT-5.5, Claude Opus 4.8, Gemini
+3.5 Flash (High), and Gemini 3.1 Pro.**
+
+---
+
+## Speed (deterministic)
+
+Speed comes straight from `npm run scale-test`, which indexes each repo twice
+(a cold fresh pass and a warm cached pass) and records:
+
+- **Fresh time** and **ms/file** for the cold index.
+- **Cached time** and the **cache speedup** for the warm re-index.
+- **Symbols**, **edges**, **resolution rate**, and **database size**.
+
+The same run also asserts determinism: the cached pass must reproduce the fresh
+pass's counts exactly, and a separate parity gate proves the parallel and serial
+indexers agree row-for-row. So the speed numbers are taken from runs that also
+prove correctness, not from a separate "fast but maybe wrong" path.
+
+To reproduce on your machine:
+
+```bash
+npm run scale-test                       # all repos under Large Codebases/
+npm run scale-test -- --only helix,react # a subset
+```
+
+Hardware and Node version are recorded in `tests/outputs/latest.md`. Numbers
+vary with disk and CPU; the shape (linear-ish ms/file, large cache speedup) is
+what to compare.
+
+---
+
+## Accuracy and token usage (model-in-the-loop)
+
+This is the part that proves the actual pitch: that an agent with Seer answers
+more correctly while spending fewer tokens and fewer round-trips than the same
+agent armed only with grep and file reads.
+
+### The design
+
+It is an A/B test where the only thing that changes is whether Seer is
+available.
+
+- **Condition A (baseline):** the agent has its normal file-read, grep/search,
+  and shell tools. No Seer.
+- **Condition B (Seer):** the same agent, same harness, same task, plus the Seer
+  MCP tools.
+
+Everything else (model, temperature, system prompt, repo, task wording) is held
+constant. Each task is run several times per model, because models are
+stochastic, and we report the mean and the spread rather than a single lucky
+run.
+
+### The task suite
+
+A fixed set of repo tasks with deterministic ground truth, for example:
+
+- "List every caller of function X." (ground truth: the resolved caller set)
+- "Which tests exercise Y?" (ground truth: the tests that actually call it)
+- "If I change the signature of Z, what breaks?" (ground truth: the transitive
+  dependents and the routes/contracts affected)
+- "Where is the handler for `POST /api/checkout`?" (ground truth: the route)
+- "How did this function change over the last N commits?" (ground truth: git)
+
+The tasks live alongside the repos so anyone can rerun them. Each task ships with
+its verified answer.
+
+### Establishing ground truth honestly
+
+This is the part people get wrong. **Do not let Seer grade its own homework.**
+Ground truth is established independently of Seer:
+
+- caller and dependent sets are verified by hand and cross-checked with a
+  compiler/LSP or a language-server where one exists,
+- "which tests cover this" is verified by actually running the tests and seeing
+  what executes the symbol,
+- route and history answers are checked against the framework config and git
+  directly.
+
+Only after the answer key exists independently do we score the agent runs
+against it.
+
+### What gets measured
+
+For each task, condition, and model:
+
+| Metric | Definition |
+|---|---|
+| **Correctness** | Did the final answer match ground truth? For set answers, precision and recall of the items found. |
+| **Tokens** | Total input + output tokens across every tool round-trip to reach the answer. |
+| **Round-trips** | Number of tool calls the agent made. |
+| **Wall time** | End-to-end time to a final answer. |
+
+The headline numbers are the **deltas**: accuracy gain, token reduction, and
+round-trip reduction of Condition B over Condition A, averaged across tasks and
+models.
+
+### Reporting rules (so it stays honest)
+
+- Report every task, not a cherry-picked subset. Include the cases where the
+  baseline ties or wins (small repos and trivial lookups, where grep is already
+  fine). Showing where Seer does *not* help is what makes the cases where it
+  does believable.
+- Report variance, not just means.
+- Keep the harness, prompts, and task suite public so the run is reproducible.
+- Separate "got it right" from "got it cheaply." A tool that is right but
+  expensive, or cheap but wrong, is not the claim.
+
+### Why this is favorable to Seer without fudging
+
+The pitch is structural: an agent without Seer reaches a caller set or a blast
+radius by issuing many searches and reading many files, which costs tokens and
+round-trips and still misses transitive and cross-file relationships. Seer
+returns those as one deterministic fact. So on the tasks that are about
+structure and impact, fewer round-trips and higher recall are the expected,
+honest outcome. On tasks that are not about structure, it should be a wash, and
+the report should say so.
+
+---
+
+See [raw-results.md](raw-results.md) for the measured speed numbers and the
+accuracy/token tables (filled in as the model runs complete).

package/docs/benchmarks/raw-results.md

@@ -0,0 +1,71 @@
+# Raw Results
+
+Full numbers behind the [benchmark summary](../benchmarks.md). Speed is measured
+and reproducible. Accuracy and token usage are model-in-the-loop and are filled
+in as those runs complete; see [methodology](methodology.md).
+
+---
+
+## Speed
+
+Generated by `npm run scale-test`. Each repo is indexed cold (fresh) and then
+warm (cached); the cached pass must reproduce the fresh pass's counts exactly,
+so these timings come from runs that also prove determinism.
+
+- Node: v26.1.0
+- Platform: win32
+- Codebase-Memory is excluded from the benchmark set on purpose (it is a
+  self-validation fixture, not a public comparison repo).
+
+<!-- speed-table-begin -->
+| Codebase | Language(s) | Files | Symbols | Edges | Resolved | Fresh index | ms/file | Cached re-index | Cache speedup | DB size |
+|---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| helix | Rust | (pending) | | | | | | | | |
+| client-go | Go | (pending) | | | | | | | | |
+| react | TS/JS | (pending) | | | | | | | | |
+| godot | C++/C#/Java | (pending) | | | | | | | | |
+| TypeScript | TS | (pending) | | | | | | | | |
+| linux | C/C++ | (pending) | | | | | | | | |
+| Unreal Engine | C++ | (pending) | | | | | | | | |
+<!-- speed-table-end -->
+
+Notes:
+
+- **Fresh** is a cold index from an empty database. **Cached** re-runs the same
+  index with every file unchanged, so almost all work is skipped.
+- **Resolved** is the share of call edges bound to a concrete definition. It is
+  naturally lower in repos that lean heavily on external libraries, whose targets
+  are not in the index. It is a health signal, not a quality grade.
+- DB size is the on-disk SQLite file.
+
+Reproduce:
+
+```bash
+npm run scale-test                 # all repos under Large Codebases/
+npm run scale-test -- --skip cbm   # the public benchmark set used here
+```
+
+---
+
+## Accuracy (model-in-the-loop)
+
+A/B over a fixed task suite, scored against deterministic ground truth. Models:
+GPT-5.5, Claude Opus 4.8, Gemini 3.5 Flash (High), Gemini 3.1 Pro. See
+[methodology](methodology.md) for the protocol and the honesty rules.
+
+<!-- accuracy-raw-begin -->
+_Runs in progress. Each cell will report mean correctness (and precision/recall
+for set answers) over N trials per model, baseline vs Seer._
+<!-- accuracy-raw-end -->
+
+---
+
+## Token usage (model-in-the-loop)
+
+Same suite and design; metric is total tokens and tool round-trips to a correct
+answer.
+
+<!-- token-raw-begin -->
+_Runs in progress. Each cell will report mean tokens and round-trips over N
+trials per model, baseline vs Seer, plus the reduction._
+<!-- token-raw-end -->

package/docs/benchmarks.md

@@ -0,0 +1,74 @@
+# Benchmarks
+
+## Summary
+
+Seer makes three claims. One is deterministic and measured here. Two depend on a
+model in the loop and are being measured now.
+
+- **Speed.** Indexing is fast and the cache is near-instant. Measured directly,
+  reproducibly, on eight real open-source repos up to the size of the Linux
+  kernel and Unreal Engine. Numbers below.
+- **Accuracy.** An agent with Seer answers structural and impact questions more
+  correctly than the same agent with only grep. In progress.
+- **Token usage.** That same agent gets there with fewer tokens and fewer tool
+  round-trips. In progress.
+
+Accuracy and token-usage numbers are measured with **GPT-5.5, Claude Opus 4.8,
+Gemini 3.5 Flash (High), and Gemini 3.1 Pro**. See
+[methodology](benchmarks/methodology.md) for exactly how, and
+[raw-results](benchmarks/raw-results.md) for the full tables.
+
+---
+
+## Speed (measured)
+
+Indexing throughput and cache speedup across the large-codebase suite. See
+[raw-results](benchmarks/raw-results.md) for the full table, hardware, and the
+determinism guarantees that ride along with these runs.
+
+<!-- speed-summary: populated from a single clean `npm run scale-test` -->
+
+The shape that matters: indexing scales roughly linearly in files, and a warm
+re-index is one to two orders of magnitude faster than a cold one because
+unchanged files are skipped entirely. Query latency against the finished index
+is SQLite-fast (low single-digit milliseconds for typical lookups), which is why
+an agent can afford to ask Seer many small questions.
+
+---
+
+## Accuracy (in progress)
+
+For a fixed suite of repo tasks with deterministic ground truth, we run each
+model twice: once with only its normal tools, once with Seer added, and score
+the final answer against the answer key.
+
+<!-- accuracy-table: filled in as model runs complete -->
+
+| Task family | Baseline (grep only) | With Seer | Models |
+|---|---|---|---|
+| Caller / dependent sets | (pending) | (pending) | GPT-5.5, Opus 4.8, Gemini 3.5 Flash (High), Gemini 3.1 Pro |
+| Test coverage of a symbol | (pending) | (pending) | " |
+| Change blast radius | (pending) | (pending) | " |
+| Route / handler lookup | (pending) | (pending) | " |
+| Symbol history | (pending) | (pending) | " |
+
+---
+
+## Token usage (in progress)
+
+Same task suite, same A/B design. The metric is total tokens and tool
+round-trips to reach a correct answer.
+
+<!-- token-table: filled in as model runs complete -->
+
+| Task family | Baseline tokens | With Seer | Reduction | Round-trips (base / Seer) |
+|---|---|---|---|---|
+| Caller / dependent sets | (pending) | (pending) | (pending) | (pending) |
+| Test coverage of a symbol | (pending) | (pending) | (pending) | (pending) |
+| Change blast radius | (pending) | (pending) | (pending) | (pending) |
+| Route / handler lookup | (pending) | (pending) | (pending) | (pending) |
+| Symbol history | (pending) | (pending) | (pending) | (pending) |
+
+---
+
+→ [Methodology](benchmarks/methodology.md) · [Raw results](benchmarks/raw-results.md)

package/docs/cli.md

@@ -0,0 +1,148 @@
+# CLI Reference
+
+Every Seer capability is available from a plain shell, not just over MCP. This
+is useful for scripting, CI, and just looking around a repo yourself. All query
+commands auto-detect `.seer/graph.db` by walking up from the current directory;
+pass `--db <path>` to point at a saved index.
+
+Run `seer --help`, or `seer <command> --help`, for the full flag list of any
+command.
+
+---
+
+## Setup
+
+```bash
+seer init [workspace]          # wire Seer into your agents (see docs/mcp.md)
+seer index <repo-path>         # build or refresh the index
+seer mcp --workspace <path>    # run the MCP server over the index
+```
+
+### `seer index` options
+
+| Flag | Meaning |
+|---|---|
+| `--reset` | Delete the existing index first. |
+| `--mode full\|standard\|fast` | Discovery breadth. `standard` is the default. |
+| `--include-vendor` / `--include-generated` | Pull in normally-excluded files. |
+| `--max-file-kb <n>` | Skip files larger than `n` KiB (0 = no cap, the default). |
+| `--parallel` / `--no-parallel` | Force or disable worker-thread parsing. |
+| `--jobs <n>` | Worker thread count (default: cores minus one, capped at 8). |
+| `-v, --verbose` | Per-file progress. |
+
+`standard` excludes big dependency and generated trees. `fast` also drops docs,
+fixtures, and static assets. `full` indexes everything.
+
+---
+
+## Orientation
+
+```bash
+seer health           # schema version, role counts, watcher state (cheap)
+seer stats            # file / symbol / edge / route / config counts
+seer architecture     # one-page snapshot: top symbols, modules, frameworks
+seer boundaries       # detected monorepo package boundaries
+seer modules          # Louvain module clusters
+seer module <label>   # files and top symbols inside a module
+```
+
+---
+
+## Search and symbols
+
+```bash
+seer symbols [query]            # search by name, or list top symbols by PageRank
+seer symbols <q> --top 20
+seer symbols <q> --include-tests --include-declarations --include-type-refs
+```
+
+By default, vendor, generated, test-file symbols, forward declarations, and type
+references are hidden. Opt in with the `--include-*` flags.
+
+---
+
+## Call graph
+
+```bash
+seer callers <symbol> [--limit n]    # who calls this (name-based, broad)
+seer callees <symbol> [--limit n]    # what this calls
+```
+
+For precise, id-scoped call graphs, prefer `seer preflight` / `seer context`,
+which resolve to exact symbol IDs.
+
+---
+
+## Routes, dependencies, config
+
+```bash
+seer routes [--method POST] [--framework express] [--path checkout]
+seer deps   [--ecosystem npm] [--name react]
+seer config [--key DATABASE_URL]
+```
+
+---
+
+## Pre-edit intelligence
+
+```bash
+seer preflight --symbol <name> [--file <path>]      # full pre-edit packet
+seer preflight --from main --to HEAD                # blast radius of a diff
+seer preflight --from main --to HEAD --old-bundle a.seerbundle --new-bundle b.seerbundle
+
+seer context  <symbol>      # definition + callers + tests + history + risk
+seer risk     <symbol>      # decomposed edit-risk score
+seer behavior <symbol>      # ranked tests that exercise the symbol
+seer detect-changes --from main --to HEAD   # standalone diff blast radius
+```
+
+`preflight` is the one to reach for first. It folds definition, callers,
+transitive dependents, tests, recent history, and risk into a single packet.
+
+---
+
+## Git history and continuity
+
+```bash
+seer churn                       # file-level git stats
+seer symbol-history [--force]    # build the per-symbol history index (opt-in)
+seer history <symbol>            # commit blame chain for one symbol
+seer continuity <symbol>         # rename/move continuity evidence (advisory)
+```
+
+---
+
+## Portability and diffing
+
+```bash
+seer bundle export [--out file.seerbundle]
+seer bundle import <bundle> [--external --alias <name>]
+seer bundle info <bundle>
+seer bundle external                       # list imported external layers
+seer contract diff <old> <new> [--include-callers]
+seer ci bundle                             # fresh-index + emit a bundle (for CI)
+seer ci workflow                           # print a GitHub Actions YAML
+seer scip-import <scip.json>               # add a SCIP precision overlay
+seer duplicates [--max-distance 4] [--min-loc 5]
+```
+
+---
+
+## Service links
+
+```bash
+seer service-calls  [--protocol http] [--path /users]
+seer service-links  [--match-kind exact]
+seer trace-service <from> <to> [--depth n]
+```
+
+These resolve outbound network calls (fetch, axios, gRPC, tRPC, GraphQL, message
+queues) to the concrete route handlers that serve them.
+
+---
+
+## Common flags
+
+- `--db <path>` on any query command points at a specific index.
+- `--limit <n>` caps list output on most list commands.
+- `--json` is available on `preflight` and `contract diff` for machine output.

package/docs/examples/behavior-tests.md

@@ -0,0 +1,70 @@
+# Behavior and tests
+
+A flat "here are the test files that mention this symbol" list is noisy. Seer
+ranks tests by how directly they exercise the symbol, so the agent reads the
+specification that actually matters first.
+
+## The call
+
+```
+seer_behavior { "symbol": "chargeCard" }
+```
+
+Trimmed response:
+
+```json
+{
+  "symbol": "billing.PaymentService.chargeCard",
+  "tests": [
+    {
+      "name": "charges a valid card",
+      "file": "test/payment.spec.ts",
+      "line": 24,
+      "directness": "direct-call",
+      "assertions": 4,
+      "lastCommit": "2026-04-18"
+    },
+    {
+      "name": "rejects an expired card",
+      "file": "test/payment.spec.ts",
+      "line": 51,
+      "directness": "direct-call",
+      "assertions": 3
+    },
+    {
+      "name": "checkout completes end to end",
+      "file": "test/checkout.e2e.ts",
+      "line": 12,
+      "directness": "graph-distance-2",
+      "assertions": 7
+    }
+  ]
+}
+```
+
+## How the ranking works
+
+Tests are scored by, in order:
+
+1. **Direct call** the test invokes the symbol itself.
+2. **Naming convention** the test file mirrors the symbol's file.
+3. **Graph distance** how many call-graph steps from the test to the symbol.
+4. **Assertion count and recency** denser, more recently touched tests rank up.
+
+So in the example, the two unit tests that call `chargeCard` directly sit above
+the end-to-end test that only reaches it two hops away, even though the e2e test
+has more assertions.
+
+## Why an agent wants this
+
+Before changing behavior, the agent can read the existing contract: an expired
+card is rejected, a valid card charges. If the change should preserve that, the
+agent knows which tests must stay green. If the change alters it, the agent knows
+exactly which spec to update.
+
+## From the CLI
+
+```bash
+seer behavior chargeCard
+seer behavior chargeCard --depth 3 --limit 20
+```

package/docs/examples/change-history.md

@@ -0,0 +1,85 @@
+# Change history
+
+Generic MCP servers show file-level churn. Seer's differentiator is symbol-level
+history: the commit blame chain for the exact function, method, or class, and
+the blast radius of a diff mapped to symbols rather than line numbers.
+
+## History for one symbol
+
+```
+seer_history { "symbol": "chargeCard" }
+```
+
+Trimmed response:
+
+```json
+{
+  "symbol": "billing.PaymentService.chargeCard",
+  "commits": [
+    { "sha": "a1b2c3d", "date": "2026-04-18", "author": "Dana", "summary": "handle declined cards" },
+    { "sha": "9f8e7d6", "date": "2026-02-02", "author": "Sam",  "summary": "add retry on timeout" },
+    { "sha": "1122334", "date": "2025-11-20", "author": "Dana", "summary": "extract chargeCard from checkout" }
+  ]
+}
+```
+
+The last entry shows `chargeCard` was extracted out of `checkout` in November.
+That is lineage a per-file blame would blur, because the code used to live in a
+different function.
+
+## Diff blast radius
+
+When work is already underway, point Seer at the range:
+
+```
+seer_preflight { "fromRef": "main", "toRef": "HEAD" }
+```
+
+Trimmed response:
+
+```json
+{
+  "changedSymbols": [
+    {
+      "name": "chargeCard",
+      "file": "src/billing/payment.ts",
+      "changeKind": "modified",
+      "transitiveDependents": 9,
+      "routeExposure": [{ "method": "POST", "path": "/api/checkout" }],
+      "risk": { "verdict": "high" }
+    },
+    {
+      "name": "formatAmount",
+      "file": "src/billing/format.ts",
+      "changeKind": "modified",
+      "transitiveDependents": 31,
+      "risk": { "verdict": "medium" }
+    }
+  ]
+}
+```
+
+Seer translated the raw line diff into the two symbols you actually changed, then
+told you `formatAmount` has 31 dependents, which is the kind of thing easy to
+miss when a one-line format tweak looks harmless.
+
+## Continuity across renames
+
+If a symbol was recently renamed or moved and you want the evidence:
+
+```
+seer_continuity { "symbol": "chargeCard" }
+```
+
+This is advisory and confidence-labeled. It will not invent a link it cannot
+justify by shape and scope similarity. For the authoritative cross-commit lineage
+(across moves and renames), `seer_history` follows the file through git.
+
+## From the CLI
+
+```bash
+seer symbol-history            # build the per-symbol history index (opt-in, once)
+seer history chargeCard
+seer continuity chargeCard
+seer detect-changes --from main --to HEAD
+```