graph-indexer 3.0.1 → 3.1.1

package/CHANGELOG.md

@@ -4,6 +4,462 @@ All notable changes to graph-indexer are documented here. Dates are in YYYY-MM-D
 
 ---
 
+## [3.1.1] — 2026-11-13
+
+A security release. Upgrading is recommended for everyone; nothing else changes. Most of these need a
+repository that was copied together with its `.git` directory (an archive, a shared folder) or that
+commits symbolic links; one needs only a hostile tool call.
+
+### Security
+
+- **git runs nothing the indexed repository's config names, on every call.** Two git calls bypassed
+  the hardening added in 3.0.1, so a repository with `core.fsmonitor` set in its `.git/config` ran
+  that command: the post-tool hook's `git status` (after every shell command the agent ran) and the
+  `models` view's `git ls-files`. Every git call now goes through one hardened function.
+- **Filter and diff drivers named with `=` are switched off too.** git splits a `-c` argument at the
+  first `=`, so the override for a driver named `x=y` set another key and left its clean filter or
+  textconv command on, running it from `check_changes`, `change_impact` and the hook. The overrides
+  now go through git's environment (`GIT_CONFIG_COUNT`), which holds any name; a git older than 2.31
+  is not run at all on such a repository. git no longer descends into submodules, whose own config
+  the overrides do not cover.
+- **`.git/` is not served under another letter case.** On a case-insensitive file system (macOS,
+  Windows) `read_code ".GIT/config"` read `.git/config`, which can hold credentials in remote URLs.
+- **Nothing is written through links committed inside `.graph-indexer/`.** A repository that
+  shipped `.graph-indexer/index.db-wal` or `resident.started` as a link to `~/.zshrc` had that file
+  overwritten. Links inside the directory are now removed before anything is written, and an index
+  committed to the repository is not opened (the database also runs in SQLite's defensive mode with
+  `trusted_schema` off).
+- **Files under a linked directory stay out.** A tracked `link/secret.ts`, where `link` points
+  outside the repository, was indexed and served, because only the last component of a path was
+  checked. Every component is now resolved, and devices and FIFOs are skipped instead of read.
+- **`Cargo.toml`, `svelte.config.*`, `pom.xml`, `build.gradle`, `.gitignore`, Prisma schemas and
+  migrations are read only as small regular files inside the repository**, like `package.json` and
+  `tsconfig.json` already were: a `Cargo.toml` linked to `/dev/zero` grew the indexer past 5 GB, and a
+  `schema.prisma` linked to a file elsewhere was read and shown.
+- **`find_files` stops a glob that backtracks catastrophically** (`*a*a*a*a*a*a*a*a*b`: 97 s on one
+  file name) after 5 s, as `search_text` does for regular expressions.
+- **`.gitignore` patterns are matched without backtracking** (repositories without git), and
+  `search_text` annotates its matches in linear time and keeps at most 50,000 of them: 10,000 matches
+  in one file took 14 s, now about 1 s.
+- **Tool arguments are held to their schema's bounds** (`depth`, `limit`, list lengths) whatever
+  the MCP client sends.
+- **Windows: nothing named `git`, `npx` or `graph-indexer` is run from the repository.** A bare
+  command is looked up in the working directory first there, so a committed `git.exe` or `npx.cmd`
+  ran. git is looked up on PATH only; the Claude Code and OpenCode plugins start npx from the home
+  directory; `init` writes npx's absolute path; and `init` no longer takes a `graph-indexer` found
+  through a relative or `node_modules/.bin` PATH entry.
+- **Windows: another user cannot answer for the resident.** The named pipe's name now carries a
+  random id kept in `.graph-indexer/`, so it cannot be created first by someone who only knows the
+  repository's path.
+- `SECURITY.md` now states the one network access there is (the opt-in, hash-checked
+  `semantic install`) and lists every file read outside the index.
+
+---
+
+## [3.1.0] — 2026-11-08
+
+### Added
+
+- **Several queries in one call.**
+  - `search_code` and `explore` take `queries: [...]` (up to 6) besides `query`, and the CLI takes
+    `--or` once per extra query.
+  - The results of each query are fused by reciprocal rank (k = 60), so an agent that does not know
+    which of three names the code uses asks once instead of three times.
+- **Documentation is indexed.**
+  - Each Markdown heading (`.md`, `.mdx`, `.markdown`) is a `section` definition, named by its heading
+    path (`Guide › Install`) and spanning to the next heading of the same or a higher level.
+    `read_code` reads a section by its name.
+  - Sections are kept in an index of their own and are searched only when the query asks for docs,
+    design, the reason for something or a guide (or with `docs: true`). Code queries never see them:
+    symbol search MRR@10 0.761 against 0.763 before, localization unchanged (file Acc@1 0.550).
+  - `check_changes` and the hooks still report on code files only.
+- **Optional semantic search (opt-in).**
+  - `graph-indexer semantic install` downloads a static code embedding model
+    (minishlab/potion-code-16M-v2, MIT, 32 MB, pinned revision, SHA-256 checked) into
+    `~/.cache/graph-indexer/models`. With `GRAPH_INDEXER_SEMANTIC=1` search adds a fourth channel,
+    by meaning, to the name, concept and file channels.
+  - It runs in plain JavaScript, with no native code and no network after the install. Vectors are
+    stored in the index as int8 and computed lazily, file by file, so an edit re-embeds only that file.
+  - It is off by default because it does not help everywhere. Over the 377 search queries, top-5
+    success rises from 0.841 to 0.859, and from 0.674 to 0.728 on queries written in words. On
+    localizing 169 real commits it costs a little: file Acc@1 0.533–0.538 against 0.550 at the chosen
+    weights, 0.485 at twice and four times them. So the default stays lexical and graph-based.
+  - [docs/BENCHMARKS.md](docs/BENCHMARKS.md#3-symbol-search).
+- **`explore` reads issues.**
+  - When the query reads like an issue (a long text, code spans or blocks), definitions are ranked
+    by where the issue's names meet (`src/query/issue.mjs`).
+  - Names are matched by their words, so `DATE_DIFF`, `DateDiff` and `_date_diff_sql` are one
+    term, and title terms weigh more.
+  - A word in capitals that only names an entry of a table with 100 or more members (a token enum)
+    is no longer looked up as a definition.
+  - Offline, over 50 fresh issues ([`bench/agentic/localize.mjs`](bench/agentic/localize.mjs)):
+    explore shows the code the fix changes in 25 issues instead of 12, given either the issue or the
+    one-line keyword query agents write.
+  - In real sessions this did not make fixing issues cheaper: cost 1.12 (1.01–1.25) and 1.03
+    (0.96–1.12) of Claude Code alone in the pilots `issue1p` and `issue2`.
+  - `init`'s instructions now suggest the issue's names and terms as the query.
+  - [docs/AGENTIC-BENCHMARK.md](docs/AGENTIC-BENCHMARK.md#issues-as-written-explore-offline-and-in-real-sessions-issue1p-issue2-47-tasks-94-runs).
+- **`check_changes` with `by_name: true` lists, apart, the test files that name a changed module in
+  a string**, such as `transpile(sql, write="presto")` for `generators/presto.py`. They reach the
+  change through a dialect, plugin or backend lookup that no reference shows. It is off by default.
+  - Over 50 fresh issues, adding them takes the existing test files the gold fix affects from 11
+    of 15 detected to 14 of 15, and the developer's test files from 86 % to 94 %.
+  - The share of test files avoided falls from 88.5 % to 68.8 %.
+  - The gain came from sqlglot, where the rule was found. On SymPy, measured afterwards, it found
+    nothing more (1 of 2 affected files either way), so it stays opt-in. Neither setting reaches
+    the goal of 99 % of affected files.
+  - Measured with `localize.mjs select`, which runs the whole suite with and without the gold fix,
+    the way NameRTS measures test selection.
+- **B5, silent errors** (`bench/agentic/mine-b5.mjs`): tasks from real commits whose partial fix,
+  the changed definition without the updates its existing users needed, breaks tests elsewhere.
+  - The criterion was fixed before mining ([PLAN-IDE-AGENTE §4](docs/PLAN-IDE-AGENTE.md)).
+  - `validate-fresh` checks that RIPPLE passes with the real fix and fails with the partial one.
+  - 17 tasks with reviewed statements, from 8 repositories: sqlglot 6, haystack 3, sympy 2,
+    sqlalchemy 2, mypy 2, scrapy 1, xarray 1. The goal is 30.
+  - A test of RIPPLE that does not run with the partial fix (its module, a conftest or an import
+    no longer loads, or its file never finishes) now makes the task loud, as rule 3 says; the
+    miner used to count it as broken. `mine-b5.mjs --recheck` applied the rule again to every kept
+    task and withdrew 8, six of them already stated. A test missing while its file ran cleanly
+    does not exist without the rest of the fix and is dropped from RIPPLE instead.
+  - The miner stops when a repository has no virtualenv and `GI_PYTHON` is unset, and the test
+    runner takes pytest from `GI_PYTHON` when `GI_PYTEST` is unset. Without them every file
+    "crashed" under the system Python and read as loud.
+  - Test runs remove the result files that runs killed on their timeout left behind.
+  - A first pilot (Sonnet 5.5 against Haiku 5.5, 6 B5 tasks with 6 questions and 4 refactors,
+    128 runs; [AGENTIC-BENCHMARK](docs/AGENTIC-BENCHMARK.md)) found no silent error in either model
+    or arm: RIPPLE passed in all 48 B5 runs, so these tasks cannot show the B5 target. Haiku cost
+    about an eighth of Sonnet and solved the same; graph-indexer cost 1.22 (1.03–1.35) of no index
+    on B5 with Haiku and 1.00 with Sonnet.
+- **Bench: the repositories' code runs sandboxed.** Tests at mining, measuring and grading run
+  under `bench/agentic/sandbox.sb` (`sandboxed()` in `lib.mjs`):
+  - no network beyond localhost;
+  - no writes outside the checkout and temporary directories;
+  - no reads of credentials;
+  - it fails closed.
+- **Bench: test runs share the machine.** Parallel runs use only idle cores (`fairJobs`), and the
+  rule that drops slow tests uses CPU time instead of the wall clock.
+- **[docs/PLAN-IDE-AGENTE.md](docs/PLAN-IDE-AGENTE.md)**, the active plan: graph-indexer as the
+  agent's IDE and memory (exact references, the impact of an edit, verification), with B3 as a
+  no-regression check and a new bench of silent errors (B5).
+
+- **The arena's session axis** (`bench/agentic/competitors.mjs`, arms `cc+codegraph`, `cc+cbm`,
+  `cc+serena`, `cc+serena-prompt`): Claude Code sessions with CodeGraph 1.6.2,
+  codebase-memory-mcp 0.11.0 or Serena 1.7.0, each installed by its own installer or guide, next
+  to graph-indexer and to no tool. `session-round.mjs --in-repo` runs sessions in the repository
+  with the task as the prompt and the installed files committed first. `cleanup.mjs` frees a
+  graded round's worktrees and checkouts, and `session-round` runs it at the end. New
+  compiler-verified question set `qa-nestjs-r7`. Result (`arena1`, 170 runs, Sonnet 5.5): graph-indexer is the
+  only tool the agent called and the only arm that answered all 11 questions. Its cost against
+  CodeGraph was 0.65 / 0.74 / 0.87 (questions / refactors / issues), against codebase-memory-mcp
+  0.79 / 0.91 / 0.96, and against Serena 0.87 / 0.93 / 1.12. It loses to Serena on issues, where
+  Serena's system prompt, not its tools, carries the gain (control `arena1b`, 45 runs).
+  [docs/AGENTIC-BENCHMARK.md](docs/AGENTIC-BENCHMARK.md#against-other-tools-in-real-sessions-arena1-34-tasks-170-runs).
+
+- **`explore`**: one call that opens a task. For a question, bug or feature in words and/or named
+  symbols it returns the most relevant definitions with their code (line numbers kept for
+  editing), their direct callers, overrides and subclasses, one shared card of where the names
+  that code uses are defined, and the tests that reach it with the command to run them — inside
+  `max_tokens` (default 2,000), naming what it left out. It composes the existing engine (search,
+  references, method families, tests) and loads up front alongside `find_references`. CLI:
+  `graph-indexer explore <task in words> [--symbols a,b] [--path P] [--max-tokens N]`. Not yet
+  measured in agent sessions ([docs/PLAN-REFERENCIA.md](docs/PLAN-REFERENCIA.md) §1.1–1.2).
+- **`init` ends with an answer about your repository** (`graph-indexer demo`): it builds the index
+  and picks a method that shares its name with other definitions, then shows what `grep -w` returns
+  for that name next to the calls the index binds to that one definition — on nestjs,
+  `NestApplicationContext.get`: 4,238 grep lines in 300 files against 129 calls in 67 files.
+  `--no-demo` skips it.
+- **HTTP routes and their handlers** (`graph-indexer routes [path | METHOD /path]`), the edge no
+  compiler sees: FastAPI and Flask decorators (with `APIRouter(prefix=…)` / `Blueprint(url_prefix=…)`
+  prefixes), NestJS controllers, Spring mappings (with the class's `@RequestMapping`), Express /
+  Fastify / Koa / Hono and Gin / Echo / chi / net/http registrations, whose handler argument is
+  bound through the index. Route parameters match in any syntax (`{id}`, `:id`, `<int:id>`).
+  `explore` follows a route in its question — "what happens on POST /owners/42/edit" — to the handler
+  and says the framework calls it.
+- **`graph-indexer report`**: a summary to paste into an issue — versions, index size, the share of
+  calls bound and exact per language, warm latencies — with no paths, names or code. A "wrong
+  answer" issue template asks for it and for the command that reproduces the problem.
+
+- **The arena** (`bench/arena/`): any code-intelligence tool with an MCP server is scored against
+  the same compiler and type-checker oracles and samples as graph-indexer (`eval-graph.mjs` and
+  `eval-graph-python.mjs` take `--systems`), with its answer size, plus cold index time and size
+  (`arena.mjs speed`). Tools are declared in a JSON file written from what their servers expose;
+  graph-indexer's own server entered that way matches its native scores within 0.007.
+  First results with CodeGraph 1.6.2 and codebase-memory-mcp 0.11.0 (`bench/arena/systems.json`):
+  on nestjs (TypeScript oracle) precision / recall 0.993 / 0.886 against 0.743 / 0.755 and
+  0.559 / 0.263; on fastapi (pyright) 0.997 / 0.826 against 0.652 / 0.363 and 0.929 / 0.571; cold
+  index 1.9 s against 3.0 s and 11.8 s on nestjs. graph-indexer's answers are the largest (310
+  tokens median against 80 and 96). Answers that name declarations instead of lines are read
+  as an agent reads them (the declaration's lines that contain the name as code).
+
+- **Rust checked against rust-analyzer** (`bench/eval-graph-rust.mjs`) on serde_json, ripgrep and
+  tokio, and fixed where it disagreed: calls inside macro arguments and items inside item macros
+  (`tri!(…)`, `assert_eq!(…)`, `cfg_rt! { … }`), the crates of a workspace used by name, modules in
+  the 2018 layout, `use a::b::module`, and paths walked module by module (`crate::T::new()`,
+  `super::f()`, `Enum::Variant`, `de::Trait`). On the same samples precision / recall went from
+  0.895 / 0.523 to 0.955 / 0.841 (serde_json), 0.914 / 0.555 to 0.941 / 0.768 (ripgrep) and
+  0.887 / 0.389 to 0.930 / 0.582 (tokio). Rust moves to the verified level. Every other oracle
+  (TypeScript, six Python, three Go, three Java repositories) gives the same scores as before.
+
+- **Python: three fixes found on flask and click.** An absolute import resolves only from an
+  import root (`import json` inside `flask/json/` is the standard library, not that package);
+  `import a.b` also binds `a`; names inside the subscripts of qualified generics
+  (`t.Optional[Command]`, `t.Callable[[Ctx], "Group"]`) are type references. click's recall
+  against pyright goes from 0.888 to 0.980, flask's from 0.909 to 0.929; no repository loses.
+
+- **Dependency injection (NestJS)**: what an `@Inject(TOKEN)` receives — the `provide: TOKEN,
+  useClass | useExisting | useFactory | useValue` or `ClientsModule` registration — is shown by
+  `find_references` (on the provider: where it is injected; on the token: who provides it) and
+  `explore` ("receives by injection"), and `graph-indexer inject [name]` lists every token. Checked
+  by hand on Twenty and nestjs: 45 provider claims for 40 injection points, none wrong; one
+  provider computed at run time is not found.
+
+- **Dependency injection (Spring)**: the bean an `@Autowired` / `@Inject` / `@Resource` field,
+  a component's constructor, a `@Bean` method's parameter or a Lombok `@RequiredArgsConstructor`
+  field receives — chosen by `@Qualifier`, `@Primary` and name as Spring does, within the
+  application the class belongs to (read from `pom.xml` / `build.gradle`); Feign clients, Spring
+  Data repositories and MyBatis mappers are named as proxies generated at run time. Shown by
+  `find_references` (on a bean: where it is injected, or where another bean wins; on an interface:
+  which bean fills each point), `explore` ("receives by injection") and `graph-indexer inject`.
+  Checked by an independent reading on spring-petclinic, piggymetrics, jhipster-sample-app and
+  mall: 312 injection points; the first reading found 3 wrong claims and 1 missed point, all fixed
+  ([docs/BENCHMARKS.md](docs/BENCHMARKS.md#dependency-injection-spring)).
+
+- **Vue and Svelte components.** `.vue` and `.svelte` files are indexed: the `<script>` as
+  TypeScript, and each template tag of a component the script imports (`<UserCard>`,
+  `<user-card>`) as a use of that component, so `find_references` on a component lists where it is
+  rendered. SvelteKit's `$lib` / `kit.alias` and `package.json` `imports` (`#/*`) resolve. On
+  open-webui 3,602 of 3,604 such tags are bound, every one to the file imported; on vue-vben-admin
+  1,178 of 1,179, the 207 direct imports all to the file imported and 80 of 80 sampled through
+  barrels and workspace packages correct
+  ([docs/BENCHMARKS.md](docs/BENCHMARKS.md#components-in-vue-and-svelte-templates)).
+
+- **ORM models: tables, migrations, Prisma's client.** Prisma `model` blocks, Django models,
+  SQLAlchemy / SQLModel tables and TypeORM entities, each with the table its ORM gives it, the
+  migration statements that name that table (SQL, Alembic `op.*`, TypeORM `queryRunner`, Django
+  operations and data migrations) and, for Prisma, the client calls that use the model
+  (`prisma.envelope.findFirst(…)`, typed only by the generated client). `find_references` on a
+  model (or a Prisma model's name) and `explore` show them; `graph-indexer models [name]` lists
+  them. Checked by an independent reading on documenso, full-stack-fastapi-template,
+  django-oscar and twenty: of 2,671 migration statements and 1,073 client calls claimed, none
+  wrong; the models and statements it found missing were added
+  ([docs/BENCHMARKS.md](docs/BENCHMARKS.md#orm-models-their-migrations-and-prismas-client)).
+
+### Changed
+
+- **Kotlin grammar built from `fwcd/tree-sitter-kotlin` d6af96d** (2026-10-31; still no release
+  after 0.3.8), with the procedure of 3.0.2, whose build of 5b7b9b7 was first reproduced byte for
+  byte. It reads Kotlin 2.x syntax that left ERROR regions before: guard conditions in `when`
+  (`is X if cond ->`), `..<`, `$$` strings, context parameters, binary literals, `suspend {}`
+  lambdas. On 3,147 files of okhttp, kotlinx.coroutines, nowinandroid, Exposed and the android
+  fixture, files with an unreadable region go from 107 to 2 (both templates with
+  `{{packageName}}`), symbols from 43,306 to 43,629 and references from 306,426 to 307,084. 334
+  members that error recovery had cut out of their class are back in it; the only 2 symbols that
+  disappear were local `val`s taken for properties after a parse error.
+- **Full and large updates parse on several threads.** Extraction (tree-sitter parse and queries)
+  runs in a pool of worker threads while the main thread writes earlier batches to SQLite; a file
+  the pool fails on is parsed again inline. The index written is identical (checked on nestjs:
+  symbols, references and imports). A full nestjs index on 4 CPUs: 3.3–3.8 s instead of 4.5–4.7 s.
+  Updates of fewer than 48 files parse inline as before; `GRAPH_INDEXER_WORKERS` sets the number of
+  threads (0 turns the pool off).
+
+### Fixed
+
+*What #5 showed for Kotlin, made general: answers no longer present what the index could not see as seen.*
+
+- **A qualified name whose owner declares nothing of that name is reported, not replaced.**
+  `refs RefreshPort.execute` used to answer with the uses of another type's `execute` (#5's
+  `OtherPort.execute`) under a "matches 2 definitions" note, and could add "Complete". It now says
+  that nothing indexed as `RefreshPort` declares `execute`, lists the definitions of that name, and
+  names the lines where `RefreshPort` appears in code the parser could not read. A qualifier that
+  names the file or a directory (`utils.helper`, `pkg.mod.func`) still finds the top-level definition.
+- **A call on a receiver declared as a type the index lacks is no longer bound by name.** A
+  parameter typed with a library type (`p: Admin` from kafkajs) or with a type in a file the parser
+  could not read was bound to the only member of that name in the repository, as "likely". The call
+  now stays unbound and shows under "Possibly missed" when its file mentions the type. Checked
+  against the TypeScript compiler: of the 207 bindings this removes in nestjs and Twenty, none was
+  correct (26 bound DOM methods to repository code, such as `TextDecoder.decode` to
+  `JwtWrapperService.decode`; the other 181 were calls into libraries). Type parameters and wrappers (`T`, `InstanceType<typeof X>`) keep the old fallback. The
+  compiler oracles (nestjs, Twenty, gin, spring-petclinic) give the same precision and recall.
+- **"Complete" is limited to what the parser read.** `find_references` and `call_graph` say
+  "Complete in the files the parser read" and list the lines where the name occurs in code the
+  parser could not read (an ERROR region, give or take a line), where a use can be missing or
+  bound to another definition.
+- **The index records which lines the parser could not read**, not just whether a file had an
+  error, and no longer counts a token the parser inserted to keep the structure (a TSX
+  `` styled.div<Props>`…` ``, which flagged 370 files of Twenty, loses nothing). Indexes are rebuilt.
+- **Python 3.15 lazy imports** (`lazy import x`, `lazy from m import y`, PEP 810) are read as
+  imports; tree-sitter-python does not know the soft keyword yet.
+- **The `init --hooks` test** no longer depends on graph-indexer being installed globally on the
+  machine that runs it.
+- **Rust: methods belong to the impl of the type their file sees.** A workspace can have several
+  types of one name (ripgrep has four `RegexMatcher`s, one per crate); the methods of every
+  `impl RegexMatcher` were members of all four, so `RegexMatcher::new` in the printer crate bound
+  to the test helper's. An impl's owner is now the type its own file resolves under that name, or
+  one of the same Cargo package. ripgrep's `RegexMatcher::new` goes from 0 of 96 uses to all 96.
+- **Rust: `impl Trait for &'a mut T`** made the methods' owner the text `&'a mut T`, so `self`
+  inside them had no type (serde_json's whole `Deserializer`).
+- **Rust: a bare name is never a method.** A parameter or local `path` passed as an argument was
+  bound to a method `path` declared in an `impl` block of the same file; a macro (`suffix!`) to a
+  method through `use super::*`. Methods with a receiver are no longer items of their module (Rust
+  and Go).
+- **Rust: 2018 module paths.** `mod runtime; pub use runtime::Runtime;` names the child module,
+  not an external crate, so `use tokio::runtime::Runtime` resolved to nothing in tokio's own tests.
+- **Rust: types the index did not follow**:
+  - tuples: `let (tx, rx) = channel()` with `-> (Sender<T>, Receiver<T>)`, `for (i, x) in
+    xs.iter().enumerate()`, and the fields of a tuple struct (`self.0`);
+  - wrappers built in place: `Arc::new(x)`, `Box::pin(f)`, `Pin::new(&mut x)`, `Rc::clone(&x)`;
+  - a crate's own `Mutex`, `RwLock` or `Semaphore` is that type, not a transparent wrapper;
+  - type parameters stand for their bound: `fn f<R: Read>(r: &mut R)`, `R::decode(r)`, a field
+    `formatter: F` in `impl<W, F: Formatter>`, `where` clauses;
+  - patterns: `Value::Object(map) =>` and `if let Self::Number(n) = …` bind the variant's field,
+    `other =>` the matched value, `if let Some(x)` / `Ok(x)` the wrapped value;
+  - `Self::new()`, and sequential shadowing (`let x = a; let x = x.to_map();`) with block,
+    match-arm and `if let` scopes, so a name rebound elsewhere in the function no longer erases
+    both types;
+  - `clone()`, `unwrap()`, `get_mut()`, `upgrade()` and the like keep the value only when its own
+    type has no method of that name (tokio's `Weak::upgrade` returns a sender);
+  - longer path calls (`grep::regex::RegexMatcherBuilder::new()`) and associated types
+    (`type Value = …;` inside an impl is not the crate's `Value`).
+- **Rust: calls through traits.** tokio recall 0.799 → 0.838, serde_json 0.925 → 0.947, precision
+  up on both (docs/BENCHMARKS.md, third round):
+  - a type parameter with several bounds (`W: AsyncWrite + AsyncSeek`, `where` clauses, `impl A +
+    B`, `dyn A + B`) has the methods of each, not only the first trait's: tokio's
+    `AsyncSeek::poll_complete` goes from 0 of 19 uses to 17. Also through a field typed by the
+    parameter, a method returning it, and pin-project's `self.project()`;
+  - trait-path calls (`SerializeSeq::serialize_element(self, v)`, `Debug::fmt(n, f)`, `<T as
+    Trait>::m(x)`) reach the impl of that trait for the first argument's type. Methods record the
+    trait of their impl block (shown as "implements"), so `Debug::fmt` and `Display::fmt` of one
+    type are two methods;
+  - the uses of a trait's method include the calls of its implementations, as rust-analyzer counts
+    them;
+  - methods of one name in impls of different types (`Cursor<Vec<u8>>`, `Cursor<&mut [u8]>`) or
+    traits are no longer merged as redeclarations, `self.m()` reaches the `m` of its own impl block,
+    and a call on a value prefers the impl for the value over the one for `&T`;
+  - a blanket impl (`impl<M: Matcher> Matcher for &M`, `… for Box<M>`) belongs to the trait, and
+    `f32::to_bits(self)` inside `impl Float for f32` is the primitive's method, not recursion.
+- **Java: overloads of one arity bind by argument types.** Calls record the types their arguments
+  show (literals, typed locals and fields, `new`, casts, array elements, `"a" + x`), and among
+  overloads taking that many arguments the resolver keeps those the types fit, exact matches
+  before widening and boxing: `append('-')` is `append(char)`, not `append(String)`.
+- **Java: a single-type import from a library package** (`import java.io.UncheckedIOException;`)
+  is the library's type, not a same-name class elsewhere in the repository.
+- **Java: `Outer.this.m()`**, `new Node(…)` inside `Node` (the class, not its constructor), and
+  nested types named through their outer one (`Token.TokenType.EOF`, `Map.Kind.valueOf(…)`).
+- **Go: constants and variables declared with a type** (`ByCid SortOpt = "cid"`) carry it, so a
+  local assigned one (`s := ByCid; s.IsValid()`) is typed.
+- **Python: names inside tuples and sets** (`(InvalidSchema, "x")` in a parametrize list) are uses.
+- **Bench: `eval-graph-rust.mjs` reads inactive code from rust-analyzer 1.9x**, which reports it through
+  pull diagnostics and as `inactive_code`: with 1.99 the oracle saw no inactive line, so uses in
+  `#[cfg]`-disabled files and items counted against graph-indexer (tokio: 20,195 inactive lines).
+- **Indexing no longer overflows the stack on a field assigned an element of itself**
+  (`self.impl = self.impl[0]`, in SQLAlchemy's `test/perf`): each lookup added one element access
+  to the type, without end, and the whole index failed. A type now stacks at most 8 element
+  accesses. The four reference oracles give identical results.
+- **Names built into regular expressions are escaped in full** (`src/util/regex.mjs`), not only
+  their `$`; the location query `file.ext:name` no longer backtracks polynomially on long input.
+  Identifiers are matched as before: the four reference oracles give identical results.
+- **`check` no longer says "overridden, so not reached" of a subclass whose own version uses the
+  changed one.** Examples are `TRANSFORMS = {**MySQLGenerator.TRANSFORMS, …}` and `super().m()`.
+  - Such subclasses, and their subclasses, are now listed as running the changed code, with their
+    tests.
+  - `change_impact` and the symbol facts count them too.
+  - On sqlglot-1a782c55, `check` had missed `test_singlestore.py`, which the fix breaks.
+- **`check` no longer flags calls to a Python `@classmethod`** as not fitting ("takes 2 arguments"):
+  its `cls` was counted because a classmethod is marked static. On the 50 gold fixes of the fresh
+  issues it now reports no problems.
+- **Bench:** sqlglot's test hint gave `unittest discover tests`, which fails to import the suite;
+  it now gives `discover -s tests -t .`.
+
+- **Hooks follow work done in the shell.** On Sonnet 5.5 the B3 sessions read files with
+  chained `cd repo; sed -n a,bp f; sed -n …` commands and edited them with Python heredocs and
+  `sed -i`; the post-tool hook recognised only a single read after `cd DIR &&`, and checked edits
+  only after the edit tool. It now splits a shell line into its commands (outside quotes and
+  heredoc bodies, paths resolved against a `cd`) and resolves every read in it, and after any
+  other shell command runs the edit checker on the source files that command changed (working-tree
+  files whose modification time moved). Replaying the b3h3 pilot's `cc+gi+hooks` runs: context on
+  50 of 191 calls instead of 33. Measured in sessions (b3h4, 15 issues, Sonnet 5.5): the hooks
+  named 256 definitions and followed shell edits in 14 of 15 sessions, the agent still never
+  called graph-indexer, and the arm cost 1.07 (1.01–1.12) of working without it — a loss.
+
+- **TypeScript default exports.** `export { default as X } from './x'` now follows to x's default
+  export; an anonymous `export default function () {}` counts as exported; a default import binds
+  to the module's own definition or default export before anything the module itself imports
+  under the importer's name. Found on vue-vben-admin; the TypeScript, Python, Go and Java oracles
+  give the same scores as before.
+
+- **Claude Code 2.1.296 saw no graph-indexer tools.** It speaks MCP 2026-07-28, where every result
+  states `resultType: "complete"`; graph-indexer's results did not, so the server connected, its
+  instructions arrived, and `tools/list` was ignored — no tool, not even a deferred one. Results of
+  that protocol version now carry it (checked in a real session: the nine tools are listed and
+  `explore` answers). With it, the per-tool `anthropic/alwaysLoad` mark works again: `explore` and
+  `find_references` load up front (about 1,100 tokens with the instructions, against 3,000 for
+  marking the whole server).
+
+- **Python references, measured against pyright** on six repositories
+  ([docs/BENCHMARKS.md](docs/BENCHMARKS.md), `bench/eval-graph-python.mjs`): recall rises on all six
+  (httpx 0.832 → 0.946, rich 0.867 → 0.971, fastapi 0.986 → 0.998) and precision on five (httpx
+  0.910 → 0.998). `from pkg import submodule; submodule.X` no longer finds what `pkg/__init__.py`
+  re-exports as X; names re-exported from an uninstalled package are external instead of bound to a
+  same-name definition; untyped parameters and other locals shadow repository names; functions
+  nested in a function are no longer reached from outside it; `return name`, `A | B` unions,
+  `except` clauses, dictionary keys, generic arguments, `__all__`, `TypeVar(bound=…)`, `Class.attr`
+  and submodule chains are uses; `self.x` under a base class's property `x` is that property.
+  TypeScript (nestjs) and Java (spring-petclinic) are unchanged or better.
+- **References in JavaScript/TypeScript modules**: a value read the extractor left unscoped (a
+  lambda parameter, a block-scoped `const`) was bound by name, at 0.6 confidence, to a top-level
+  name of another module (`cases.filter(c => …)` → `export const c` elsewhere). An ES module sees
+  another module's names only through an import, so such reads no longer bind across modules.
+  Reference accuracy on nestjs against the TypeScript compiler is unchanged (dispatch oracle,
+  399 symbols: precision 0.998, recall 0.937).
+- **Agent benchmark, mined Python issues (B3).** Sessions ran tests with the system Python
+  (no pytest) while grading used a virtualenv: they now get the grading virtualenv first on their
+  `PATH`, and the preflight checks it inside a session. `unittest` outcomes are recorded by a result
+  object instead of read from verbose text, which missed tests whose subtests fail. Mining puts SQL
+  fixtures in the hidden tests (and runs the modules that read them), runs each state twice to drop
+  flaky tests, and `validate-fresh.mjs` checks every task through the grader (base fails, the real
+  fix solves it three times). The fourth round's 11 tasks pass it unchanged.
+- **"Defined elsewhere" card**: an unbound call no longer matches a constant or variable by name
+  (`Math.max(…)` listed a `const max` from another file).
+
+---
+
+## [3.0.2] — 2026-11-08
+
+Kotlin `fun interface` support, contributed by [@jhernandez-movicoders](https://github.com/jhernandez-movicoders)
+([#5](https://github.com/MaquinaTech/graph-indexer/issues/5), [#6](https://github.com/MaquinaTech/graph-indexer/pull/6)),
+and a Claude Code plugin that meets the plugin directory policy.
+
+### Fixed
+
+- **Kotlin `fun interface`** ([#5](https://github.com/MaquinaTech/graph-indexer/issues/5)). The vendored grammar
+  (`fwcd/tree-sitter-kotlin` 0.3.8) could not parse a SAM interface (`fun interface Port { fun execute() }`).
+  The interface was missing, and its method became a top-level function. Calls through it were then bound to
+  another method with the same name, while `refs` still reported the list as complete.
+- **The Kotlin grammar is now built from `fwcd/tree-sitter-kotlin` 5b7b9b7.** That commit adds `fun interface`
+  ([fwcd/tree-sitter-kotlin#169](https://github.com/fwcd/tree-sitter-kotlin/pull/169)) and is in no release yet.
+  It was built with `tree-sitter build --wasm` (tree-sitter-cli 0.25.10, the runtime's version).
+  - Measured on a 442-file Kotlin/Spring service: the 44 `fun interface` declarations and their methods are now
+    indexed.
+  - Resolved references go from 7,434 to 7,835, and exact ones from 5,325 to 5,545.
+  - No file loses a symbol. The one with one fewer had a local `val` taken for a property after a parse error
+    that the new grammar no longer makes.
+  - The grammar manifest is part of the index fingerprint, so existing indexes are rebuilt.
+
+### Changed
+
+- **The Claude Code plugin listed in the plugin directory is Markdown and JSON only.** The directory
+  accepts command hooks, local MCP servers and scripts only from verified organizations, so
+  `integrations/claude-code` now holds the `code-structure` sub-agent (with the `name` and `description`
+  frontmatter keys only), a `setup` skill that tells Claude how to connect the MCP server
+  (`claude mcp add graph-indexer -- npx -y --prefix / graph-indexer@3.0.2 serve`, with the user's
+  consent) and the manifest.
+- **The full plugin (MCP server, hooks, sub-agent) moved to `integrations/claude-code-local`** for manual
+  installs; `init --hooks` gives the same result without a plugin. Its launchers are pinned to the exact
+  release: the hook client ran `graph-indexer@3`, a range, and now runs `graph-indexer@3.0.2`. A test
+  keeps every pin equal to `package.json`.
+
+---
+
 ## [3.0.1] — 2026-10-23
 
 A security release. Upgrading is recommended for everyone; nothing else changes.

package/README.md

@@ -60,12 +60,18 @@ to `.gitignore`, and adds a short block to `CLAUDE.md` / `AGENTS.md` on how to l
 For Claude Code it also writes a structural helper, `.claude/agents/code-structure.md`: a
 read-only sub-agent on a small model that answers call-site, caller, subclass and impact
 questions from the index, so the main agent can hand them off and get back only the list (the
-Claude Code plugin ships it too). `--hooks` adds the Claude Code hooks to `.claude/settings.json`,
+Claude Code plugin ships it too (`integrations/claude-code`; the full plugin with hooks is `integrations/claude-code-local`)). `--hooks` adds the Claude Code hooks to `.claude/settings.json`,
 which Devin, Copilot CLI and Cursor also run, and the OpenCode / Kilo Code plugin that appends the
 same context to their tool output. Flags: `--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin`,
 `--all`, `--hooks`, `--local` (use this checkout instead of `npx`), `--dry-run`,
 `--no-instructions`, `--no-helper`.
 
+In Claude Code (2.1.275 or later), the plugin installs in one step:
+
+```text
+/plugin install graph-indexer --marketplace MaquinaTech/graph-indexer
+```
+
 <details>
 <summary>Manual configuration</summary>
 
@@ -94,11 +100,19 @@ Without `--repo` the server indexes the git repository containing its working di
 
 ## The tools
 
+`npx graph-indexer init` ends with an example from your own repository: a method that shares its
+name with other definitions, what grep returns for that name, and the calls the index binds to
+that one definition (`npx graph-indexer demo` shows it again).
+
 | Tool | Use it to | Typical reply |
 |---|---|---|
+| `explore` | start a task or bug in code you have not read, in one call | the most relevant definitions with their code, who calls them, overrides and subclasses, where the names they use are defined and the tests to run with the command — inside a token budget, naming what it left out |
+| `explore` + routes | ask about an endpoint ("what happens on POST /owners/42/edit") | the handler the framework registers for it — FastAPI, Flask, NestJS, Spring, Express/Fastify/Koa/Hono, Gin/Echo/chi; `npx graph-indexer routes` lists them all |
+| dependency injection | look up a NestJS or Spring class, interface or token (`find_references`, `explore`) | what an injection point receives — NestJS: the `provide: TOKEN, useClass/useFactory/…` or `ClientsModule` registration of an `@Inject(TOKEN)`; Spring: the bean of an `@Autowired`/constructor/`@Bean` parameter, chosen by `@Qualifier`, `@Primary` and name, Feign, Spring Data and MyBatis proxies named as such — and where a provider is injected, which neither the type checker nor grep for the type connects; `npx graph-indexer inject` lists them all |
+| ORM models | look up a model (`find_references`, `explore`; `npx graph-indexer models`) | its table, the migrations that touch it, and for Prisma the client calls (`prisma.user.findMany`) that only the generated client types — Prisma, Django, SQLAlchemy/SQLModel, TypeORM |
 | `read_code` | read symbols, line ranges or files — several per call — without searching for what they use | code with line numbers, then where each name it uses is defined (file:line and signature); who uses a symbol and which tests reference it; a long file's outline |
 | `search_text` | grep any text across the repository (code, config, docs) | grep lines with the enclosing definition and, for identifiers, the definition each match refers to; where the definition is when the search missed it |
-| `search_code` | find where a behaviour or identifier lives (natural language or names) | ranked symbols with location, signature, doc line and matching lines |
+| `search_code` | find where a behaviour or identifier lives (natural language or names); `queries: [...]` asks for several phrasings at once | ranked symbols with location, signature, doc line and matching lines; for a question about docs, design or the reason for something, the Markdown sections that answer it |
 | `find_references` | see every use before renaming or changing a signature | uses grouped by file, enclosing function, confidence, calls through base types marked |
 | `call_graph` | trace callers and callees across files | a tree with locations and confidence |
 | `change_impact` | get the blast radius of a change, or of your uncommitted diff | transitive dependents by distance, tests to run, co-changed files, risk |
@@ -136,6 +150,12 @@ often changed together (git): context.go (14/42), context_test.go (10/42), …
 risk: medium (9 dependents, 1 test files)
 ```
 
+**Search by meaning (optional).** `npx graph-indexer semantic install` downloads a 32 MB static code
+embedding model (potion-code-16M-v2, MIT, pinned and checksummed); with `GRAPH_INDEXER_SEMANTIC=1`
+search also ranks definitions by meaning, in plain JavaScript and without network access. It helps
+queries written in words (top-5 success 0.674 → 0.728) and not the localization of real commits,
+so it is off by default ([measurements](docs/BENCHMARKS.md#3-symbol-search)).
+
 Every reference carries a confidence: **exact/high** means it was bound through a scope,
 import or inferred receiver type; **likely/possible** means only the name matched. Footers
 report same-name call sites that could not be bound, so an agent knows when to double-check
@@ -161,8 +181,10 @@ own `findReferences` (import lines and declarations excluded):
 do not. Against the compiler's full rename set (sibling overrides included) recall is 0.925. The
 fixture has no `node_modules`, so library-typed values are invisible to the compiler: precision is
 a lower bound.* The same measurement against the Go type checker (gin, caddy, nats-server) gives
-precision 0.992–1.000 and recall 0.972–0.981, and against the Java compiler (spring-petclinic,
-jsoup, Commons Collections) 0.955–0.994 and 0.861–0.989; grep's precision there is 0.02–0.61.
+precision 0.992–1.000 and recall 0.972–0.981, against the Java compiler (spring-petclinic,
+jsoup, Commons Collections) 0.961–0.994 and 0.883–0.989, against pyright (six Python
+repositories) 0.895–0.998 and 0.927–0.998, and against rust-analyzer (serde_json, ripgrep, tokio)
+0.968–0.990 and 0.799–0.942; grep's precision there is 0.01–0.61.
 In the server of Twenty, an open-source CRM monorepo (28,512 files), precision is 0.999 and
 recall 0.924; grep's precision is 0.009 and 2.x's 0.052.
 
@@ -172,7 +194,7 @@ rolled back to the parent commit first.
 
 | | file Acc@1 | file Acc@5 | function Acc@5 | function MRR@10 |
 |---|---|---|---|---|
-| graph-indexer `search_code` | **0.544** | **0.805** | **0.528** | **0.432** |
+| graph-indexer `search_code` | **0.550** | **0.799** | **0.528** | **0.433** |
 | grep, files ranked by idf-weighted hits | 0.485 | 0.769 | 0.514 | 0.374 |
 | BM25 over the same index | 0.373 | 0.722 | 0.401 | 0.290 |
 
@@ -180,6 +202,14 @@ rolled back to the parent commit first.
 strictly at symbol level: rank-1 0.703 and MRR 0.760, against 0.552 and 0.646 for graph-indexer
 2.x on the same queries. On the 169 held-out queries (never used for tuning) MRR is 0.773 vs 0.632.
 
+**Against zvec-grep 0.3.0** (hybrid BM25 + vector search, with its default embedding model,
+Qwen3-Embedding-0.6B, run on the same Mac): on the same 377 queries its best setting, code only,
+reaches rank-1 0.581 and MRR 0.639 (graph-indexer 0.703 and 0.761); on the 169 commits it puts
+the changed file first in 0.420 of them (graph-indexer 0.550, ranked grep 0.485). It is ahead on
+two repositories, gin and fastapi. It has no references or callers. In a one-repetition pilot of
+agent sessions (Haiku 5.5, 24 tasks, 13 of them from zvec-grep's own benchmark) neither tool beat
+Claude Code alone. [Details](docs/BENCHMARKS.md#zvec-grep-030-2026-11-06).
+
 **Against 2.x.** In real Claude Code sessions on nestjs and Twenty (40 tasks, 120 runs), 3.0
 cost 0.43 of 2.x on code questions and 0.46 on refactors, with a quarter to a third of the
 tokens spent looking code up; 2.x cost about twice as much as no index, as its tools and prompt
@@ -240,9 +270,32 @@ files are re-parsed. Warm tool calls take 1–4 ms for the graph tools, about 30
 
 ## Languages
 
-JavaScript, TypeScript/TSX, Python, Go, Java, Kotlin, Scala, C#, Rust, C, C++, Ruby, PHP, Bash
-and CSS/SCSS/Less. Reference binding and type inference are deepest for TypeScript/JavaScript,
-Python, Go, Java, C# and Rust.
+Every language gets definitions, outlines, search and edit checks. How far references are bound
+differs, and is stated rather than implied:
+
+| Level | Languages | What it means |
+|---|---|---|
+| **Verified** | TypeScript/TSX, Go, Java, Python, Rust | references measured against the language's own compiler or type checker on three or more real repositories ([docs/BENCHMARKS.md](docs/BENCHMARKS.md)): TypeScript 0.997 precision / 0.962 recall (nestjs), Go ≥ 0.992 / ≥ 0.972 (gin, caddy, nats-server), Java 0.961–0.994 / 0.883–0.989 (spring-petclinic, jsoup, Commons Collections), Python 0.895–0.998 / 0.927–0.998 against pyright (fastapi, flask, requests, httpx, rich, click), Rust 0.974–0.990 / 0.838–0.947 against rust-analyzer (serde_json, ripgrep, tokio) |
+| **Resolved** | JavaScript, C#, Vue and Svelte components (`<script>` as TypeScript; template tags as uses of the components imported) | scopes, imports and receiver types inferred from declarations, annotations and constructors; no compiler oracle yet |
+| **Scoped** | Kotlin, Scala, C, C++, Ruby, PHP | scopes, imports/includes and packages; less type inference, so more calls stay unbound or by name |
+| **Symbols** | Bash, CSS/SCSS/Less | definitions, outlines and search; references by name |
+
+Each answer marks how a reference was bound (`exact`, `likely`, `possible`) and says when a list is
+complete, whatever the level.
+
+How much of the code the parser reads, measured on public repositories (68,000 files in 46
+repositories: the fixtures, the agent benchmark's repositories, okhttp, kotlinx.coroutines,
+nowinandroid, Exposed, spring-boot, cats, Play and Jellyfin):
+
+| | files with a region the parser cannot read |
+|---|---|
+| TypeScript, TSX, JavaScript, Python, Java, Kotlin, Scala, C#, Rust, Go, Ruby, PHP | 0–0.2% (test data with deliberate syntax errors, `typeof import()` in type arguments, Python 3.15 unpacking comprehensions) |
+| Bash | 4% (zsh completion scripts) |
+| C, C++ | 39% of files, 15% of lines: macros inside declarations (`void (CJSON_CDECL *fn)(…)`); the functions themselves are kept |
+| SCSS, Less | about half of the files: they are read with the CSS grammar, which does not know nesting, `#{…}` or mixins |
+
+Where a symbol's name occurs in code the parser could not read, `find_references` and
+`call_graph` say so and name the lines, instead of reporting the list as complete.
 
 ## Command line