thurview 0.17.2 → 0.19.0

package/skills/thurview-explain/SKILL.md

@@ -62,10 +62,11 @@ Read the guidance files that exist, in this order; the second wins on conflict.
 `thurview explain` lists the ones it found under `guidance`.
 
 The `thurview` skill ships the references this one shares - document authoring,
-components, software map, theme, lifecycle. `thurview skill` prints the path of
+components, software map, searching the code, theme, lifecycle. `thurview skill` prints the path of
 every bundled SKILL.md; the references sit beside each one. Read **Document
 authoring** before you write `review.md`, **Components** before you edit
-`data.yaml`, **Software map** before you author `map.yaml`, **Theme** before you
+`data.yaml`, **Software map** before you author `map.yaml`, **Searching the
+code** before you look for callers, tests or importers, **Theme** before you
 write `theme.yaml`, and **Lifecycle** for statuses, storage and thread rules -
 they are identical for all three kinds.
 
@@ -86,8 +87,7 @@ thurview explain --commit v1.2.0 # a released commit rather than HEAD
 
 The positional argument is a path or a glob; a bare path means that directory
 and everything under it. It is the **scope**, and everything else obeys it:
-`graph architecture` reports the clusters inside it, and coverage accounts for
-every file inside it. A scope that matches no file at that commit is refused.
+your searches stay inside it, and coverage accounts for every file inside it. A scope that matches no file at that commit is refused.
 
 Record `explainer.id`, `explainer.dir`, `explainer.commit`, `explainer.scope`
 and `scale.filesInScope` from the output. Everywhere else the id is passed as
@@ -103,10 +103,12 @@ misleading about architecture, which is the one thing an explainer must not be.
 So work in three layers, and let each carry what it is good at.
 
 1. **System — the map carries breadth.** Author `map.yaml` first, seeded from
-   `thurview graph architecture --review <id>`: communities become nodes, their
-   files become the node's `files` globs, and the edges between communities
-   become edges. Every part of the scope should appear here, including the parts
-   the prose will not reach. See the `thurview` skill's Software map
+   the code: the directories in scope become candidate nodes and their files
+   the node's `files` globs, and what imports what between them becomes the
+   edges. `git ls-tree -d -r --name-only <commit> -- <scope>` lists the
+   directories; the `thurview` skill's Searching the code reference has the
+   import recipes. Every part of the scope should appear here, including the
+   parts the prose will not reach. See the `thurview` skill's Software map
    reference for the shape.
 2. **Subsystem — the prose carries depth.** Pick the parts that carry the most
    structure and the most traffic, and explain those. Three to six sections.
@@ -114,27 +116,37 @@ So work in three layers, and let each carry what it is good at.
 3. **File and symbol — anchors carry the proof.** Every claim gets an anchor.
    The reader opens code where they want it and nowhere else.
 
-**Select by structure, not by taste, and say what you selected on.** The graph
-gives you the basis: cluster size in files and symbols, the hub symbols of each
-cluster (most referenced), and the reference counts on the edges between
-clusters. Say in the document which parts you took and why they were the ones -
-"the two clusters with the most traffic between them" is a reason a reader can
-check. "The interesting bits" is not.
+**Select by structure, not by taste, and say what you selected on.** Your
+searches give you the basis: how many files a part holds, which of its names
+the rest of the scope references most, and how many places one part imports
+another. Say in the document which parts you took and why they were the ones -
+"the two parts that import each other most" is a reason a reader can check,
+with the searches that counted it in `searches`. "The interesting bits" is not.
 
 ## Coverage is derived, not claimed
 
 `thurview publish` accounts for every file in scope at the pinned commit and
-puts one of three states on it:
+puts one of four states on it, from what you did that it can check:
 
 - **explained** - an anchor in the document points into the file.
 - **placed** - a map node's `files` globs match it, and no anchor does. The
   reader is told where it sits, not what it does.
-- **not examined** - neither.
+- **searched** - a search you recorded under `searches` in `data.yaml` matched
+  it, and nothing above did. You saw lines of it; the document says nothing
+  about it.
+- **not examined** - none of the above.
+
+Record the searches you ran - for callers, tests, importers - under `searches`,
+each with its `pattern`, optional `paths` and a `why`. `publish` re-runs every
+one with `git grep -E` at the pinned commit, so what it counts is what the
+commit holds, not what you remember, and a search that matched nothing is shown
+as the zero it is. The shape is in the `thurview` skill's Components reference,
+the recipes in its Searching the code reference.
 
 The counts go above the document and onto the Coverage tab, and `publish`
 prints them with the files it did not examine. You cannot forget to state
 coverage, and you cannot overstate it: to move a file out of _not examined_ you
-have to actually anchor it or actually place it on the map.
+have to actually anchor it, place it on the map, or search it.
 
 Two consequences worth planning for:
 
@@ -145,12 +157,9 @@ Two consequences worth planning for:
   globs it owns and how many files they match, so `**/*` on one node inflates
   nothing quietly.
 
-Coverage also states what the code graph could not read: files in languages it
-does not parse (`thurview graph` covers TypeScript, JavaScript, Python, Go,
-Rust, Java and Elixir), and whether its file list was capped. Those files are absent
-from the structure, not empty. If a large part of the scope is outside the
-graph, say so in the document rather than letting the map imply the system is
-smaller than it is.
+Coverage is the same for every language: it counts files at the commit, so a
+config file, a stylesheet or a language nothing parses is accounted for like
+any other.
 
 ## Surface structure; do not grade it
 
@@ -160,7 +169,8 @@ the reader can **detect** design problems. That is only consistent with the
 thesis if you surface structure and leave the conclusion to them.
 
 The test: **every fact in an explainer is a count, or a list of named things,
-at the pinned commit, that the reader could re-derive with `thurview graph`.**
+at the pinned commit, that the reader could re-derive with `git grep` or
+`git ls-tree`.**
 
 Observation - write these:
 
@@ -169,7 +179,8 @@ Observation - write these:
 - "The API layer reaches the database layer in 14 places and the model layer in
   2; the model layer reaches the API layer in 6."
 - "Nothing in the scope references `legacy/` at this commit."
-- "No test file reaches this cluster." (a count of zero, stated as one)
+- "No test file names anything in `src/store`." (a count of zero, stated as
+  one, with the search that found it)
 
 Judgement - never write these:
 
@@ -188,11 +199,12 @@ the code" - not a finding.
 ## Workflow
 
 1. `thurview explain [<scope>]`. Note the id, the commit and the scope.
-2. `thurview graph architecture --review <id>`. This is the structure at the
-   pinned commit; do not re-derive it by reading directories.
-   `thurview graph callers <name>` and `tests-for <name>` answer the follow-ups.
-   `graph interfaces` and `graph impact` compare two commits and are refused.
-3. Author `map.yaml` from the architecture output, covering the whole scope.
+2. Survey the scope at the pinned commit: its directories and files
+   (`git ls-tree`), then what imports what between them and who calls the
+   names that recur, with the `git grep` recipes in the `thurview` skill's
+   Searching the code reference. Record each search that shapes what you write
+   under `searches` in `data.yaml`.
+3. Author `map.yaml` from that survey, covering the whole scope.
    Dispatch a sub-agent for it if you have one, exactly as the `thurview`
    skill's review does.
 4. Author `review.md` and `data.yaml` per **Document authoring**, minus the
@@ -202,10 +214,14 @@ the code" - not a finding.
    `graph: base` on an anchor - there is one commit.
 5. `theme.yaml` as usual - see **Theme**.
 6. `thurview publish --review <id>`. Read `coverage` and `notExamined`. If the
-   split is not the one you meant, anchor or place more and publish again.
+   split is not the one you meant, anchor, place or search more and publish
+   again.
 7. `thurview open --review <id>`, then `thurview wait --review <id>`. The loop,
    the statuses and the thread rules are identical to a review; see
    **Lifecycle**.
+8. To share it beyond the browser, `thurview export --review <id> --out <path>`
+   writes a static, read-only copy - see the `thurview` skill's **Sharing a
+   copy that needs no server**.
 
 ## Hand over
 

package/skills/thurview-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thurview-fix
-description: Review a change and fix what the review finds - bugs, regressions for callers, missing or broken tests, security issues - with thurview's code graph showing the callers and tests a diff does not. Commits only the fixes that pass the repository's own tests and lint, and reports the rest. Use when the user asks to review and fix a branch, a commit range or a pull or merge request, to find and fix bugs in a change, or invokes /thurview-fix.
+description: Review a change and fix what the review finds - bugs, regressions for callers, missing or broken tests, security issues - with a search of the callers and tests a diff does not show. Commits only the fixes that pass the repository's own tests and lint, and reports the rest. Use when the user asks to review and fix a branch, a commit range or a pull or merge request, to find and fix bugs in a change, or invokes /thurview-fix.
 user-invocable: true
 argument-hint: "[<branch> | <base>..<head> | <PR or MR number or URL>] [--post]"
 ---
@@ -8,12 +8,12 @@ argument-hint: "[<branch> | <base>..<head> | <PR or MR number or URL>] [--post]"
 # thurview-fix
 
 Review a change, fix what you are sure of, report the rest. The diff shows what
-changed; thurview's code graph shows what depends on it, which is where a
-change breaks code the diff never shows.
+changed; a search of the code around it shows what depends on it, which is
+where a change breaks code the diff never shows.
 
 ```mermaid
 flowchart LR
-  A[Scope: pin base and head] --> B[Graph: who reaches the change]
+  A[Scope: pin base and head] --> B[Search: who reaches the change]
   B --> C[Findings]
   C --> D[Fix, then the repo's tests and lint]
   D -->|green| E[One fix commit]
@@ -42,49 +42,53 @@ $ARGUMENTS
 ## 1. Scope
 
 Start from a clean tree (`git status --porcelain` prints nothing), otherwise
-ask: the fixes get committed. Check out the head, then pin both commits with
-one graph call:
+ask: the fixes get committed. Check out the head, then pin both commits:
 
-| Request            | Check out                                      | Pin with                                                                          |
-| ------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------- |
-| empty              | the current branch                             | `thurview graph impact --head HEAD`                                               |
-| a branch           | `git switch <branch>`                          | `thurview graph impact --head HEAD`                                               |
-| `<base>..<head>`   | the branch at `<head>`                         | `thurview graph impact --base <base> --head HEAD`                                 |
-| a PR or MR ref/URL | `gh pr checkout <n>` or `glab mr checkout <n>` | `thurview graph impact --base $(git merge-base origin/<target> HEAD) --head HEAD` |
+| Request            | Check out                                      | Base                                  |
+| ------------------ | ---------------------------------------------- | ------------------------------------- |
+| empty              | the current branch                             | `git merge-base origin/HEAD HEAD`     |
+| a branch           | `git switch <branch>`                          | `git merge-base origin/HEAD HEAD`     |
+| `<base>..<head>`   | the branch at `<head>`                         | `git rev-parse <base>`                |
+| a PR or MR ref/URL | `gh pr checkout <n>` or `glab mr checkout <n>` | `git merge-base origin/<target> HEAD` |
 
-With `--head` alone the base is where head forked from trunk. For a change
-request, `thurview forge status --change <ref>` names `<target>` as
-`change.baseBranch`.
+Head is `git rev-parse HEAD`, taken now. For a change request,
+`thurview forge status --change <ref>` names `<target>` as
+`change.baseBranch`; when `origin/HEAD` is unset, use the trunk branch by name.
 
-The output's `base` and `head` are the pins. Pass `--base <base> --head <head>`
-to every later graph command, as its `help` lines do, so your fix commit does
-not move what you are reviewing.
+Write both full shas down and use them, not `HEAD`, in every later command, so
+your fix commit does not move what you are reviewing.
 
-## 2. Ask the graph
+## 2. Search what the change reaches
+
+List what changed, then find what the diff does not show, at the pins, with
+the recipes in the `thurview` skill's Searching the code reference
+(`thurview skill` prints its path):
 
 ```sh
-thurview graph impact     --base <base> --head <head>  # changed symbols, who reaches them, tests
-thurview graph interfaces --base <base> --head <head>  # exports and signatures that moved
-thurview graph callers <name> --base <base> --head <head>  # every call site; --graph base for before
-thurview graph tests-for <name> --base <base> --head <head>
+git diff --stat <base> <head>                              # the files
+git diff <base> <head>                                     # the change
+git grep -n -E -e '\bname *\(' <head> --                   # who calls a changed symbol now
+git grep -n -E -e '\bname *\(' <base> --                   # who called it before; a removed one's callers are only here
+git grep -n -E -e '\bname\b' <head> -- '*test*' '*spec*'       # which tests name it
 ```
 
-What to take from them:
+What to look for:
 
-- **`impact.reach`** lists code that calls a changed symbol and was not changed
-  itself - what the author may have forgotten. `at` is the line of the call,
-  `via` the changed symbol it reaches. Read each call site against the new
-  behaviour: this is the finding a diff cannot give you.
-- **`reach[].tested: false`**: no test reaches that caller, so nothing catches
-  a break there.
-- **`interfaces`** rows `changed` or `removed`: run `callers` on each, with
-  `--graph base` for a removed one, since head no longer has its callers.
-- **`impact.untested`**: changed symbols no test reaches.
-- **`unresolved`, `truncated`**: references the graph could not resolve and
-  files past its cap. "No callers" is only as true as those allow; say so when
-  a finding rests on it.
+- **Callers the change left alone.** For every function, method, type or
+  export whose signature or behaviour the diff changed, search its callers at
+  head and drop the ones the diff itself touched. What is left is what the
+  author may have forgotten: read each call site against the new behaviour.
+  This is the finding a diff cannot give you.
+- **Removed or renamed interfaces.** Search the old name at head: any hit is
+  a caller the change broke.
+- **Untested reach.** A changed symbol, or a caller of one, that no test names
+  has nothing to catch a break there.
+- **What a search misses.** A text search finds names, not meaning: a call
+  through a variable, a re-export or a string-built name escapes it. "No
+  callers" is only as true as the forms you searched; say which when a finding
+  rests on it.
 
-Then read the diff (`git diff <base> <head>`) and every call site the rows name.
+Then read every call site the searches name.
 
 ## 3. Findings
 
@@ -95,8 +99,9 @@ For each one, record:
   `medium` (a likely bug, or a risky path no test reaches), `low` (real but
   narrow)
 - why, in one line
-- the graph evidence when there is some, e.g.
-  `reach: checkout src/cart.js:5 via discount, tested false`
+- the search evidence when there is some: the search and the hit, e.g.
+  `git grep -n -E -e '\bdiscount *\(' <head>` → `src/cart.js:5`, no test names
+  it
 
 Security means input crossing a trust boundary: a shell command, query or path
 built from it, a secret reaching a log, an authorization check the change
@@ -133,9 +138,9 @@ git commit -m "fix: address review findings" -m "<one line per fix: file:line -
 
 ## 5. Report
 
-One table - severity, `file:line`, the finding, its graph evidence, and the fix
-commit or why it is unfixed - then the tests and lint after the commit, and
-what the graph could not see. Do not push; offer to.
+One table - severity, `file:line`, the finding, its search evidence, and the
+fix commit or why it is unfixed - then the tests and lint after the commit, and
+what the searches could not see. Do not push; offer to.
 
 ## 6. Post, with `--post` only