dsh-plugin-codegraph 0.1.7 → 0.2.0

package/README.md

@@ -40,6 +40,12 @@ Two tools, deliberately separate.
 | `explore` | Several related declarations with their source | `query` |
 | `context` | Everything relevant to a task | `task` |
 
+The tool also reports its own state into the system prompt. Every prompt assembly carries one line describing the workspace's index — how many files, declarations and relationships it holds, when it was built, and how many generated artifacts were left out — or, when there is none, that `codegraph_index` has to run first. That line is a section whose text is a function, re-evaluated per request by the host; nothing is spent on a `status` round-trip to learn it.
+
+**Re-indexing parses only what changed.** Every successful run leaves the extraction it produced for each file in `.codegraph/cache/`; the next run — a second `codegraph_index`, or a watch rebuild after one edit — confirms each file by its recorded modification time and size and reuses its extraction instead of reading and parsing it again. On a 337-file workspace measured here, a repeat run cost 45 ms against 991 ms for the first. Edges and call resolution are still rebuilt over the whole graph every time, deliberately: the rule that resolves a call by a workspace-unique name is global, so a symbol added in one file can invalidate edges pointing at another that never changed. `cacheVerify: 'hash'` trades that speed for correctness when a checkout can restore an older file without moving its mtime.
+
+**A large workspace indexes in the background.** `codegraph_index` estimates the job from the previous run's summary: at or past `backgroundIndexThreshold` files it hands the run to the host's job registry and returns a job id immediately, instead of holding a tool call open for minutes. `job_output <id>` reads the report; `job_kill <id>` stops it. Small workspaces keep the synchronous path, so the common case never pays for a job round-trip. Set `backgroundIndex: true` or `false` to override the estimate.
+
 ### `codegraph_index` — build or refresh the graph
 
 Separate from `codegraph` rather than an eleventh operation, because indexing a large workspace takes minutes while a query takes milliseconds, and a tool's timeout budget is fixed per registration. Folding them together would force one budget that is either too tight for a real build or too loose to catch a hung query.
@@ -133,7 +139,7 @@ The split is not ceremony. The seam carries no source text and performs no files
 
 ## Known limits
 
-- **Watching is on by default, and self-limiting where it wouldn't help.** A successful `codegraph_index` starts watching that root automatically — a single recursive `fs.watch` on macOS/Windows, one inotify watch per directory on Linux — refreshing the index after a debounced quiet period. Set `watch: false` to keep indexing purely explicit instead. It's overridden back off on a WSL2 kernel watching a path mounted in from the Windows host (`/mnt/<drive>/...`), since inotify doesn't reliably deliver events over that mount; `CODEGRAPH_FORCE_WATCH=1` and `CODEGRAPH_NO_WATCH=1` override that default either way. Whether or not watching is on, `status` still reports how many indexed files have gone stale — modified or removed since the last run — found by statting the filesystem directly, so a caller can always tell a trustworthy index from a drifted one instead of assuming the best.
+- **Watching is on by default, and it goes through the host's filesystem seam.** A successful `codegraph_index` starts watching that root automatically: one watch per in-scope directory, opened through `ctx.fs.watch` rather than `node:fs` directly, so a workspace a backend serves from another execution world is watched where it actually lives. The seam's change callback carries no filename, so a rebuild is triggered by re-listing the watched directories and diffing them against the previous snapshot; an empty diff schedules nothing, which is what keeps the indexer's own `.codegraph` writes from rebuilding forever. A backend that cannot watch degrades to explicit indexing with a logged reason instead of failing the plugin. Set `watch: false` to keep indexing purely explicit instead. It's overridden back off on a WSL2 kernel watching a path mounted in from the Windows host (`/mnt/<drive>/...`), since inotify doesn't reliably deliver events over that mount; `CODEGRAPH_FORCE_WATCH=1` and `CODEGRAPH_NO_WATCH=1` override that default either way. Whether or not watching is on, `status` still reports how many indexed files have gone stale — modified or removed since the last run — found by statting the filesystem directly, so a caller can always tell a trustworthy index from a drifted one instead of assuming the best.
 - **Git hooks and worktree detection ship as library functions only** — `installGitHooks`/`uninstallGitHooks` (a `post-checkout`/`post-merge`/`post-commit`/`post-rewrite` hook running a command of your choosing, for environments where live watching isn't available) and `detectWorktree` (whether a root is a linked `git worktree`, and where its main repository lives). Neither is wired into plugin load or exposed as a model-visible tool: `.git/hooks/*` is shared, ambient state this package doesn't own, so installing it is left to a caller's own init script, never automatic.
 - **Exclusion unions the built-in default directories with the project's own `.gitignore`.** Build output that lands outside `node_modules`/`dist`/`build`/`coverage` (a `lib` a TypeScript project compiles to, say) is almost always gitignored too, and indexing it alongside its own source would hand call resolution two same-named declarations of one symbol to pick between arbitrarily. Only a practical subset of gitignore syntax is understood — no `**`, character classes, or per-directory `.gitignore` files. Turn it off with `respectGitignore: false`.
 - **Committed build output is left out by shape, not by `.gitignore`.** Some deployments commit `dist/` so a server can serve it straight from the repository, which makes it neither gitignored nor named in `exclude`. Those files are still bundler output: a workspace sampled here had 25 such files that contributed 90% of the declarations, 86% of the edges, and 92% of the unresolved call sites in a graph that otherwise described 335 source files — and their mangled one-letter names collided with real symbols, making the unique-name rule refuse calls it could have settled. `skipMinified` (default on) skips a file whose path carries a `.min.` segment, or whose average line length is past 500 characters — roughly 7× the widest average found in hand-written source — and reports the count as `files_minified`. It is a heuristic, not a build-system integration: naming the artifact directory in `exclude` is still the exact fix, and `skipMinified: false` indexes such files anyway.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-codegraph",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Structural code intelligence for DeepSeek Harness — gives the agent codegraph and codegraph_index tools to find where a symbol is declared, what calls it, what a change reaches, and how one symbol reaches another, from a tree-sitter index it builds itself",
   "keywords": [
     "dsh",
@@ -42,9 +42,9 @@
     }
   },
   "dependencies": {
-    "dsh-plugin-codegraph-sqlite": "^0.1.7",
-    "dsh-plugin-codegraph-tree-sitter": "^0.1.7",
-    "dsh-plugin-codegraph-service": "^0.1.7",
-    "dsh-plugin-codegraph-tool": "^0.1.7"
+    "dsh-plugin-codegraph-sqlite": "^0.2.0",
+    "dsh-plugin-codegraph-service": "^0.2.0",
+    "dsh-plugin-codegraph-tree-sitter": "^0.2.0",
+    "dsh-plugin-codegraph-tool": "^0.2.0"
   }
 }