thurview 0.17.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Guided, evidence-anchored reviews of agent-written code. A coding agent authors the review; you read, ask, comment and decide in the browser.",
   "license": "MIT",
   "type": "module",
@@ -32,19 +32,9 @@
     "@toon-format/toon": "2.3.1",
     "axi-sdk-js": "0.1.11",
     "diff": "9.0.0",
-    "graphology": "0.26.0",
-    "graphology-communities-louvain": "2.0.2",
     "markdown-it": "15.0.1",
     "open": "11.0.2",
     "shiki": "4.4.3",
-    "tree-sitter-elixir": "0.3.5",
-    "tree-sitter-go": "0.25.0",
-    "tree-sitter-java": "0.23.5",
-    "tree-sitter-javascript": "0.25.0",
-    "tree-sitter-python": "0.25.0",
-    "tree-sitter-rust": "0.24.0",
-    "tree-sitter-typescript": "0.23.2",
-    "web-tree-sitter": "0.27.0",
     "yaml": "2.9.0",
     "zod": "4.5.4"
   },
@@ -52,7 +42,6 @@
     "@types/diff": "8.0.0",
     "@types/node": "26.4.1",
     "esbuild": "0.28.2",
-    "graphology-types": "0.24.8",
     "prettier": "3.9.6",
     "tsx": "4.23.13",
     "typescript": "7.0.2",

package/skills/thurview/SKILL.md

@@ -133,37 +133,32 @@ cold, and the walkthrough is what makes it so.
 ### 3. Study the change
 
 Read the whole diff once (`git diff <base> <head>`). The diff tells you what
-changed. The code graph tells you what it means, which is what the review is
-for. thurview builds it from the pinned commits with tree-sitter and the
-definitions-and-references query each grammar ships, so ask it rather than
-re-deriving structure from hunks:
+changed; what it means is in the code it does not show - who calls what the
+change moved, which tests reach it, what imports the module it touched. Find
+those yourself, at the pinned commits, with the recipes in
+[Searching the code](references/searching.md):
 
 ```sh
-thurview graph interfaces --review <id>         # what the change added to, changed in or removed from the visible surface
-thurview graph impact --review <id>             # symbols touched, edges added and removed, what reaches them, what tests cover them
-thurview graph callers <symbol> --review <id>   # used, or speculative? (--graph base for the old side)
-thurview graph tests-for <symbol> --review <id>
-thurview graph architecture --review <id>       # file clusters with their hubs, the edges between them, the file-level diff
+git grep -n -E -e '\bname *\(' <head> --       # who calls it now
+git grep -n -E -e '\bname *\(' <base> --       # who called it before: a removed symbol's callers are only here
+git grep -n -E -e '\bname\b' <head> -- '*test*'      # what tests name it
 ```
 
-The graph covers TypeScript, JavaScript, Python, Go, Rust, Java and Elixir; other
-files are absent from it, not empty. References resolve by name, so treat
-`unresolved` as the size of what it could not place, and `<module>` as code
-outside any definition. If `truncated` is true (`truncated.base` and
-`truncated.head` for impact and architecture, which look at both commits; a
-plain `truncated` for callers and tests-for, which look at one), the repo has
-more supported files than the graph could parse, and that answer is a partial
-view: say so rather than treating an empty result as "nothing there".
-
-Read `graph interfaces` first: it is the reader's own first question, and its
-`verdict` is what the browser shows above your document. A `removed` entry is
-the most review-worthy thing the change can contain; `No interface moved`
-means the change is internal, and the document should say why the refactor was
-worth making rather than dress it up as a feature. Do not repeat the entries
-in prose - the panel already lists them. Explain the ones that need it,
-in `data.yaml` (see below).
-
-Spend the rest of the review on what the other queries answer: what the change
+Start with the interfaces: what the change added to, changed in or removed
+from what other code, a user or another system reaches - an exported function,
+a CLI flag, an HTTP route, a config key, a file format. It is the reader's own
+first question, and the list you declare in `data.yaml` (step 5) is what the
+browser shows above your document. A removed or changed one is the most
+review-worthy thing a change can contain, so search for its callers at both
+pins. A change that moves none is internal, and the document should say why the
+refactor was worth making rather than dress it up as a feature. Do not repeat
+the entries in prose - the panel already lists them.
+
+A search finds names, not meaning, so open each hit before you count it, and
+state the search beside any claim that rests on one - "no other caller" is
+worth exactly the line that found none.
+
+Spend the rest of the review on what the searches answer: what the change
 reaches that the diff does not show, which boundaries it crosses, what now
 depends on what, what it left untested. Then compare the stated intent (commit
 messages, PR description, the user's own words) with what the code does. The
@@ -205,9 +200,11 @@ Source worktree: <worktree>
 Base commit: <base>
 Head commit: <head>
 
-Seed the structure from `thurview graph architecture --review <id>` rather
-than guessing it: communities and their hubs become nodes, its edges the
-edges, and its diff the difference between base and head.
+Seed the structure from the code rather than guessing it: the directories at
+each pin (`git ls-tree -d -r --name-only <commit>`) become candidate nodes, and
+the importers of each one (the recipes in the thurview skill's
+references/searching.md) the edges. What differs between base and head is the
+diff the map shows.
 
 Author <dir>/map.yaml: the head structure under nodes/edges and the base
 structure under base. Do not edit review.md or data.yaml. Do not publish.
@@ -225,10 +222,11 @@ Edit `review.md` and `data.yaml` in the review directory following
 Default to anchor links for evidence; use an inline peek only when the reader
 must see the code to follow the main claim.
 
-In `data.yaml`, add an `interfaces` entry for each interface change a
-consumer would not understand from its declaration alone, and for the ones
-the graph cannot see - a CLI flag, an HTTP route, a config key, a file
-format. See [Components](references/components.md) for the shape and
+In `data.yaml`, add an `interfaces` entry for each interface the change added,
+changed or removed - an exported function, a CLI flag, an HTTP route, a config
+key, a file format - anchored on the lines that moved it. Publish refuses an
+anchor that sits on no added or deleted line, so an entry cannot outlive the
+code. See [Components](references/components.md) for the shape and
 [Document authoring](references/document-authoring.md) for what earns an
 entry. Never write one for a capability the change did not deliver.
 

package/skills/thurview/references/components.md

@@ -79,10 +79,7 @@ stores:
           body: { type: text }
 
 interfaces:
-  spawnPty:                               # annotate a derived entry
-    symbol: src/pty.ts:spawnPty           # an id from `thurview graph interfaces`
-    capability: Callers get a sized PTY without knowing the fallback.
-  dryRun:                                 # declare one the graph cannot see
+  dryRun:                                 # one per interface the change moved
     name: thurview publish --dry-run      # what a consumer types or calls
     change: added                         # added | changed | removed
     capability: Validate a review without sealing a revision.
@@ -91,33 +88,38 @@ interfaces:
 security:                                 # a review only; omit until you have looked
   - boundary: The --shell flag reaches execFile's argv unquoted.
     anchor: spawn                         # a head anchor, with a peek
+
+searches:                                 # an explainer only
+  spawnCallers:
+    pattern: '\bspawnPty *\('            # git grep -E, re-run at the pinned commit
+    paths: ["src/"]                       # optional git pathspecs; the whole commit when left out
+    why: who opens a PTY                  # optional; the question it answered
 ```
 
 An anchor without `peek` can label a map node but cannot open code.
 
 ## interfaces
 
-The browser shows the interface delta above the document. thurview derives it
-at `publish` from the code graph at both pinned commits - every symbol the
-diff touched that is visible outside its own file, split into added, changed
-and removed - so the list itself is never authored and never goes stale.
+The browser shows the interface delta above the document: what the change
+added to, changed in or removed from the surfaces something outside it reaches.
+You declare each entry; thurview checks it.
 
-Each entry in `interfaces` does one of two things, and never both:
+Every entry has `name`, `change`, `capability` and `anchor`:
 
-- **`symbol`** annotates a derived entry with `capability`, one sentence in a
-  consumer's terms. `publish` fails when the change did not move that symbol,
-  so an annotation cannot outlive the entry it explains. Take the id verbatim
-  from `thurview graph interfaces`.
-- **`name`** declares an interface the graph cannot see: a CLI subcommand or
-  flag, an HTTP route, an event kind, a config key, a file format. It needs
-  `change` and an `anchor`. `publish` checks the anchor against the pinned
-  diff - a `removed` entry needs a `graph: base` anchor covering a deleted
-  line, `added` and `changed` need a head anchor covering an added line - so a
-  declared interface is evidence, not a claim.
+- **`name`** is what a consumer types or calls: an exported function, a CLI
+  subcommand or flag, an HTTP route, an event kind, a config key, a file
+  format.
+- **`change`** is `added`, `changed` or `removed`.
+- **`anchor`** proves it. `publish` checks it against the pinned diff - a
+  `removed` entry needs a `graph: base` anchor covering a deleted line, `added`
+  and `changed` need a head anchor covering an added line - so an entry is
+  evidence, not a claim, and cannot outlive the code that moved it.
+- **`capability`** is what a consumer can now do, or can no longer do. Write
+  "`thurview publish` gains `--dry-run`", not "added a boolean to
+  PublishOptions".
 
-`capability` is what a consumer can now do, or can no longer do. Write
-"`thurview publish` gains `--dry-run`", not "added a boolean to
-PublishOptions".
+An entry written with `symbol:` named a row thurview used to derive. It derives
+none now, and `publish` refuses the key with how to write the entry instead.
 
 ## security
 
@@ -153,6 +155,27 @@ severity that exists belongs to the findings in `thurview-fix`, not to this
 document. An explainer and a design are pinned to one commit and have no change,
 so `publish` refuses the key on either.
 
+## searches
+
+An explainer's record of what it searched: the callers, tests and importers
+it looked for while reading the code. `publish` re-runs each one with
+`git grep -I -E` at the pinned commit, so what it matched is the commit's and
+not the worktree's, and the Coverage tab counts every file in scope it matched
+and nothing anchored or placed as _matched by a search_. A search that matched
+nothing is listed too, since that zero is what a claim of absence rests on.
+
+- **`pattern`** is a POSIX extended regular expression, as `git grep -E` reads
+  it. One git refuses fails the publish with git's own message.
+- **`paths`** are git pathspecs to search under, read exactly as your own
+  `git grep` reads them, so `*test*` reaches into every directory; the whole
+  commit when left out.
+  Coverage counts only the files inside the explainer's scope either way.
+- **`why`** is the question the search answered, in a sentence.
+
+A review or a design has no Coverage tab, so `publish` refuses `searches` there:
+put the search beside the claim it supports, in the prose. The recipes are in
+[Searching the code](searching.md).
+
 ## Anchor link
 
 ```markdown

package/skills/thurview/references/document-authoring.md

@@ -66,33 +66,28 @@ Progressive disclosure: every `##` heading is a section the reader can fold.
 ## Interface delta
 
 The reader's first question is what the change lets them do that they could
-not before, and what it cost. thurview answers it from the code graph rather
-than from your prose: every symbol the diff touched that is visible outside
-its own file, as added, changed or removed, above your document. Read it with
-`thurview graph interfaces` before you write, and let it shape the document:
+not before, and what it cost. You answer it in `data.yaml` under `interfaces`
+(see [Components](components.md)), one entry per interface the change added,
+changed or removed - an exported function, a CLI subcommand or flag, an HTTP
+route, an event kind, a config key, a file format - and the browser lists them
+above your document. Each entry carries an anchor on the lines the diff moved;
+publish refuses one that sits on none, so the list cannot claim what the change
+did not do. Let it shape the document:
 
 - **A removed entry is the change's most review-worthy fact.** Say what
-  depended on it (`thurview graph callers <name> --graph base`) and what
-  replaces it. Never let a removal read as a rearrangement.
-- **`No interface moved` is a finding, not an empty result.** The change is
-  internal. Write about why it was worth making - the bug it fixes, the
-  duplication it folds - and do not dress it up as a capability.
-- **Do not restate the entries in prose.** The panel lists them, with the
-  declaration and a link into the file. Your sentences are for what it cannot
-  derive: why the surface has this shape, what a consumer does with it, what
-  a removal breaks.
-
-Add an `interfaces` entry in `data.yaml` (see [Components](components.md))
-only when one of these holds:
-
-1. A derived entry's declaration does not tell a consumer what it is for. The
-   `capability` line says what they can now do, in their words.
-2. The change moves an interface the graph cannot see - a CLI subcommand or
-   flag, an HTTP route, an event kind, a config key, a file format. Declare
-   it, with an anchor on the line the diff moved.
-
-Anything else is noise: the entry is already there, or there is nothing to
-add. An interface the change did not deliver is never an entry.
+  depended on it - search for its callers at the base pin, as
+  [Searching the code](searching.md) shows - and what replaces it. Never let a
+  removal read as a rearrangement.
+- **No entry is a finding, not an empty result.** The change is internal.
+  Write about why it was worth making - the bug it fixes, the duplication it
+  folds - and do not dress it up as a capability.
+- **Do not restate the entries in prose.** The panel lists them, with a link
+  into the file. Your sentences are for what it cannot hold: why the surface
+  has this shape, what a consumer does with it, what a removal breaks.
+
+What earns an entry is a surface something outside the change reaches. A
+private helper is not one, however much it moved, and an interface the change
+did not deliver is never an entry.
 
 ## Trust boundaries
 
@@ -101,7 +96,8 @@ Every review answers where the change lets input cross a trust boundary, in
 it under the interface delta, one line per place with the anchor the reader
 opens.
 
-Answer it after you have read the diff and the graph, and answer it either way.
+Answer it after you have read the diff and searched what it reaches, and answer
+it either way.
 `security: none` is the whole answer for a change that crosses none, and writing
 it is what makes the panel worth reading on the review where it is not none. A
 review that leaves the key out publishes as "not assessed", which is honest for

package/skills/thurview/references/searching.md

@@ -0,0 +1,74 @@
+# Searching the code
+
+thurview builds no index of the code. Who calls a symbol, which tests touch a
+file and what imports a module are answered by your own search, at the pinned
+commit, and every answer you state comes with the search behind it so the
+reader can run it again. Every skill that asks one of these questions uses the
+recipes here.
+
+## Search the pinned commit, not the worktree
+
+`git grep` reads a commit directly, so its answer is the one your anchors are
+pinned to however far the worktree has moved:
+
+```sh
+git grep -n -E -e '<pattern>' <commit> -- '<path glob>'
+```
+
+`<commit>` is `head` for what the change made, `base` for what it replaced.
+Each hit prints as `<commit>:<path>:<line>:<text>`; the `<path>:<line>` part is
+what an anchor's `peek` takes. `rg` gives the same answer, faster, only when
+`git rev-parse HEAD` in the worktree is the pinned commit and the tree is
+clean; when either is not true, use `git grep`.
+
+## Recipes
+
+Swap the name in; each one is a starting point, so read the hits before you
+trust the count.
+
+| Question                    | Search                                                                     |
+| --------------------------- | -------------------------------------------------------------------------- |
+| callers of a function       | `git grep -n -E -e '\bname *\(' <commit> --`                               |
+| every reference to a symbol | `git grep -n -E -e '\bname\b' <commit> --`                                 |
+| callers before the change   | the same at `<base>`: a removed symbol has no callers left at head         |
+| importers of a module       | `git grep -n -E -e "['\"][./]*path/to/module(\.[a-z]+)?['\"]" <commit> --` |
+| tests that touch a file     | `git grep -l -E -e '\bexportedName\b' <commit> -- '*test*' '*spec*'`       |
+| tests that name a symbol    | `git grep -n -E -e '\bname\b' <commit> -- '*test*' '*spec*'`               |
+| the directories in a scope  | `git ls-tree -d -r --name-only <commit> -- <scope>`                        |
+| the files in a scope        | `git ls-tree -r --name-only <commit> -- <scope>`                           |
+
+Every recipe is one `-E` pattern, with `\b` for a word boundary rather than
+`-w`, so an explainer can record it under `searches` exactly as you ran it -
+publish re-runs it with `-E` and nothing else. `\b` is a GNU extension: check
+it on the platform once (`git grep -c -E -e '\bname\b' <commit> --` must match
+what `-w -e name` matches) and use `[[:<:]]name[[:>:]]` where git's regex
+library reads that instead.
+
+The import recipe is written for JavaScript and TypeScript. Use the language's
+own form elsewhere: `^import .*module` in Python and Go, `use crate::module` in
+Rust, `alias|import|use Module` in Elixir. Test files are named per project;
+check one before you rely on `*test*`.
+
+## What a search can and cannot tell you
+
+A text search finds names, not meaning. It misses a call made through a
+variable, a re-export, a string-built name or reflection, and it matches a
+comment or a different symbol with the same name. So:
+
+- **A hit is a lead.** Open it before you call it a caller.
+- **No hit is a finding about the search, not the code.** "Nothing calls
+  `audit`" is true only of the forms you searched for; say which.
+- **Name the search with the claim.** A sentence like "no other caller" carries
+  the line that found none, so the reader can run it.
+
+## Record what you searched
+
+How it is recorded depends on the document:
+
+- **An explainer** lists its searches under `searches` in `data.yaml`. Publish
+  re-runs each one with `git grep -E` at the pinned commit and the Coverage tab
+  counts the files it matched; see [Components](components.md). Record the ones
+  that shaped what you wrote, a zero-hit one included.
+- **A review or a design** has no Coverage tab. Put the search in the prose
+  beside the claim it supports, as inline code.
+- **A fix pass** puts it in the evidence column of its report.

package/skills/thurview-design/SKILL.md

@@ -103,19 +103,19 @@ passed as `--review <id>`; that flag names a document, whichever kind it is.
 ### 2. Study what the design has to fit
 
 The design is an argument about a system, so read the system before proposing
-anything. The code graph is the fastest way in, and it is the same graph the
-reader can re-derive:
+anything. Search it yourself at the pinned commit, with the recipes in the
+`thurview` skill's Searching the code reference, so what you find is what the
+reader can re-run:
 
 ```sh
-thurview graph architecture --review <id>       # clusters in the scope, their hubs, the edges between them
-thurview graph callers <symbol> --review <id>   # who depends on what you plan to change
-thurview graph tests-for <symbol> --review <id> # what would have to move with it
+git ls-tree -d -r --name-only <commit> -- <scope>   # the parts the design has to fit
+git grep -n -E -e '\bname *\(' <commit> --          # who depends on what you plan to change
+git grep -n -E -e '\bname\b' <commit> -- '*test*'       # what tests would have to move with it
 ```
 
-`graph interfaces` and `graph impact` compare two commits and are refused here:
-there is one. The graph covers TypeScript, JavaScript, Python, Go, Rust, Java
-and Elixir; other files are absent from it, not empty, and `truncated` means
-the answer is partial.
+A search finds names, not meaning: open each hit before you count it, and put
+the search beside any claim that rests on it - a design has no Coverage tab to
+carry it, so `searches` in `data.yaml` is refused here.
 
 Read every range you intend to anchor from the pinned commit itself —
 `git show <commit>:<path>` — not from the working tree.
@@ -144,8 +144,7 @@ interfaces:
   a restatement of the signature.
 - `anchor` is the **site**: real code at the pinned commit that this proposal
   lands in, replaces or plugs into. It must resolve and it must have a `peek`.
-- A `symbol:` entry is refused. That shape annotates a row the code graph
-  derived from a diff, and a design has none.
+- A `symbol:` entry is refused: every entry names its own interface.
 - **A design with no entry here is refused.** A document that proposes nothing
   is an explainer; write one of those instead.
 
@@ -164,8 +163,9 @@ finishes is a design nobody decided on. A shape that works:
    fence. This is what makes a design arguable rather than assertible.
 3. **What to build** — the proposals in step 3, with the reasoning the panel
    cannot carry.
-4. **What it costs** — what has to move, what breaks, what is left out. Use
-   `thurview graph callers` for the blast radius rather than guessing it.
+4. **What it costs** — what has to move, what breaks, what is left out. Search
+   for the callers to count the blast radius rather than guessing it, and give
+   the search with the count.
 5. **What was considered and dropped**, with the reason. This is the section
    readers send a design back for missing.
 
@@ -205,7 +205,10 @@ The Map tab is where a design shows structure. Put the structure it
   part, and publish does not warn about it.
 - A node under `base` may not. It is a claim about today, and publish warns
   when its globs match nothing at the pinned commit.
-- Seed `base` from `thurview graph architecture --review <id>`.
+- Seed `base` from the code: the directories at the pinned commit
+  (`git ls-tree -d -r --name-only <commit>`) and what imports what between
+  them, found with the `git grep` recipes in the `thurview` skill's Searching
+  the code reference.
 
 A design that changes one part in place does not raise the question: leave
 `nodes: []` and say so in the handover.

package/skills/thurview-design/references/anchors-and-proposals.md

@@ -23,12 +23,12 @@ to nothing would put that question on every other anchor in the document.
 
 ## What this buys, concretely
 
-| The design says                                | How it is carried                                    | What the reader can do                        |
-| ---------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
-| "today the router picks a handler in a switch" | anchor with a `peek`                                 | open the switch                               |
-| "we would add `Router.register`"               | proposal, `change: added`, anchored at the switch    | open the code it replaces                     |
-| "it would look roughly like this"              | plain fenced code block in `review.md`               | read it as a sketch, because it is not a peek |
-| "these fourteen callers move"                  | anchor per caller, or the count from `graph callers` | check the count                               |
+| The design says                                | How it is carried                                            | What the reader can do                        |
+| ---------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
+| "today the router picks a handler in a switch" | anchor with a `peek`                                         | open the switch                               |
+| "we would add `Router.register`"               | proposal, `change: added`, anchored at the switch            | open the code it replaces                     |
+| "it would look roughly like this"              | plain fenced code block in `review.md`                       | read it as a sketch, because it is not a peek |
+| "these fourteen callers move"                  | anchor per caller, or the count and the `git grep` behind it | run the search and check the count            |
 
 ## The refusals, and why each one is there
 
@@ -37,9 +37,11 @@ why; these are the reasons behind them.
 
 - **`graph: base` on an anchor.** A design has one pinned commit. A base-graph
   anchor would resolve against a commit the document never named.
-- **A `symbol:` interface entry.** That shape annotates a row the code graph
-  derived from a diff. A design has no diff, so there is no derived row, and an
-  annotation with nothing under it is an assertion wearing a badge.
+- **A `symbol:` interface entry.** That shape annotated a row derived from a
+  diff. A design has no diff, and an annotation with nothing under it is an
+  assertion wearing a badge; a proposal names its own interface.
+- **`searches` in `data.yaml`.** Those feed an explainer's Coverage tab, which a
+  design has none of. Give the search in the prose, beside the count it backs.
 - **A design that proposes nothing.** A document with no `interfaces` entry is
   prose about the code as it stands. That is an explainer, and it should be one
   — the reader of a design is being asked to approve something.