thurview 0.9.0 → 0.11.0

package/README.md

@@ -72,19 +72,33 @@ CLI. It works with Claude Code, Codex, Cursor, OpenCode and every agent that
 reads the Agent Skills format:
 
 ```sh
-npx skills add Thurbeen/thurview --skill thurview
-npx skills add Thurbeen/thurview --skill forge-review   # optional, see below
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill thurview --agent universal claude-code --global --yes
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill review-fix --agent universal claude-code --global --yes   # optional, see below
 ```
 
+`--global` installs for your user, so one install covers every repository.
+`universal` puts the one real copy in `~/.agents/skills/thurview`, the directory
+no single agent owns, and every other agent you name gets a symlink to it, such
+as `~/.claude/skills/thurview` → `../../.agents/skills/thurview`, so an update
+lands everywhere at once. Swap `claude-code` for any agent the skills CLI
+supports, but keep `universal` and at least one more: with `--yes` and a single
+target, the CLI copies instead of linking.
+
 That form tracks this repository's default branch: `skills update` takes
 whatever `main` holds, which can be ahead of the released command. To pin the
 skill to a release instead, install it from the tag, which the skill lock
 records and later updates keep:
 
 ```sh
-npx skills add https://github.com/Thurbeen/thurview/tree/v0.1.4/skills/thurview
+npx skills@latest add https://github.com/Thurbeen/thurview/tree/v0.10.0/skills/thurview \
+  --agent universal claude-code --global --yes
 ```
 
+Releases tag without committing, so nothing moves the tag above: swap in the
+[latest release](https://github.com/Thurbeen/thurview/releases/latest).
+
 The npm package ships the same skill, so `thurview setup skill` links the copy
 that matches the command you have installed. Use that when you want the two to
 move together.
@@ -102,7 +116,7 @@ The review reasons over a code graph thurview builds itself from the pinned
 commits with tree-sitter, so nothing else needs installing. `thurview graph`
 answers which interfaces the change moved, what it reaches, who calls a
 symbol, what tests cover it and how files cluster, for TypeScript,
-JavaScript, Python, Go, Rust and Java.
+JavaScript, Python, Go, Rust, Java and Elixir.
 
 To run from a checkout instead:
 
@@ -178,7 +192,7 @@ bar.
 | `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                   |
 | `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                            |
 | `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                           |
-| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at the pinned commits                          |
+| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`    |
 | `thurview forge status\|prior\|submit\|reply`                         | Read a change request through its forge, and post the review back |
 | `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one        |
 | `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                         |
@@ -194,11 +208,26 @@ arguments shows live state for the current directory instead of a manual.
 `thurview <command> --help` is the fallback. Progress and diagnostics go to
 stderr.
 
-## Posting the review to the forge
+## Review and fix
+
+The `review-fix` skill reviews a branch, a commit range or a pull or merge
+request, fixes what it is sure of and reports the rest, with no browser and no
+approval step. For each changed symbol it asks the code graph who calls it and
+which tests reach it, so a finding can name a caller the diff never shows.
+Fixes that pass the repository's own tests and lint land as one local commit;
+nothing is pushed unless you ask.
+
+```sh
+thurview graph impact --head HEAD                 # changed symbols, the callers they left alone, the tests
+thurview graph callers discount --head HEAD       # every call site of one symbol
+```
+
+`--base` and `--head` ask about two commits directly; `--head` alone diffs
+from where it forked from trunk. Each caller in `impact.reach` carries the line
+of its call and whether any test reaches it.
 
-A thurview review is read in the browser. When the change is a pull request on
-GitHub or a merge request on GitLab, the `forge-review` skill posts it there as
-well: inline comments anchored to lines, a summary, and a verdict.
+With `--post`, the skill posts the findings it did not fix as inline comments
+on the change request, through `thurview forge`:
 
 ```sh
 thurview forge status --change 123    # what CI actually did, and whether it is a gate at all
@@ -224,7 +253,7 @@ and gitlab.com are matched against what those CLIs are authenticated for, and
 an unmatched host is refused rather than guessed. The differences that survive
 the seam - GitLab has no changes-requested state, no atomic review and no
 multi-line comment anchor - are listed in
-[skills/forge-review/references/forges.md](skills/forge-review/references/forges.md).
+[skills/review-fix/references/forges.md](skills/review-fix/references/forges.md).
 
 ## Authoring format
 

package/dist/cli.js

@@ -215,22 +215,43 @@ async function ensureServer() {
 function reviewUrl(base, id, view) {
     return `${base}/review/${id}${view ? `#/${view}` : ""}`;
 }
+function pinnedOf(review) {
+    return { worktree: review.worktree, pins: review.pins, dir: reviewDir(review.id) };
+}
 /**
- * The interface delta at a review's pins. The graphs are cached per commit under
- * the review directory, so publish and `graph interfaces` build them once between
+ * Base and head as `--base` and `--head` name them. Head defaults to HEAD and
+ * base to where head forked from trunk, so a branch is diffed against what it
+ * branched from rather than against wherever trunk has moved since.
+ */
+async function pinRange(worktree, base, head, usage) {
+    try {
+        const h = await g.revParse(worktree, head ?? "HEAD");
+        const b = base
+            ? await g.revParse(worktree, base)
+            : await g.mergeBase(worktree, await g.trunkRef(worktree), h);
+        return { base: b, head: h };
+    }
+    catch (e) {
+        throw new AxiError(e.message, "VALIDATION_ERROR", [
+            `Pass resolvable refs: \`${usage}\``,
+        ]);
+    }
+}
+/**
+ * The interface delta at two pinned commits. The graphs are cached per commit
+ * under `at.dir`, so publish and `graph interfaces` build them once between
  * them; both modules load lazily to keep tree-sitter off every other command's path.
  */
-async function deltaFor(review, base, head) {
+async function deltaFor(at, base, head) {
     const graph = await import("./graph.js");
     const { interfaceDelta } = await import("./interfaces.js");
-    const dir = reviewDir(review.id);
-    const b = base ?? (await graph.graphAt(review.worktree, review.pins.base, dir));
-    const h = head ?? (await graph.graphAt(review.worktree, review.pins.head, dir));
-    const changes = await g.lineChanges(review.worktree, review.pins.base, review.pins.head);
-    const changed = await g.changedFiles(review.worktree, review.pins.base, review.pins.head);
+    const b = base ?? (await graph.graphAt(at.worktree, at.pins.base, at.dir));
+    const h = head ?? (await graph.graphAt(at.worktree, at.pins.head, at.dir));
+    const changes = await g.lineChanges(at.worktree, at.pins.base, at.pins.head);
+    const changed = await g.changedFiles(at.worktree, at.pins.base, at.pins.head);
     return interfaceDelta({
-        cwd: review.worktree,
-        pins: review.pins,
+        cwd: at.worktree,
+        pins: at.pins,
         base: b,
         head: h,
         impact: graph.impact(b, h, changes, 1),
@@ -438,12 +459,18 @@ const SPECS = {
         args: "interfaces|impact|callers <name>|tests-for <name>|architecture",
         flags: {
             review: { kind: "string", help: "review id prefix" },
+            base: {
+                kind: "string",
+                help: "instead of --review: base revision (default: trunk fork point)",
+            },
+            head: { kind: "string", help: "instead of --review: head revision (default: HEAD)" },
             graph: { kind: "string", help: "callers, tests-for: head or base", default: "head" },
             depth: { kind: "string", help: "how many caller hops to follow", default: "2" },
         },
         examples: [
             "thurview graph interfaces",
             "thurview graph impact",
+            "thurview graph impact --base main --head HEAD",
             "thurview graph callers login",
             "thurview graph tests-for login --graph base",
             "thurview graph architecture",
@@ -590,17 +617,7 @@ const commands = {
             const [bb, hh] = b?.kind === "range" && !str(p, "base") && !str(p, "head")
                 ? b.name.split("..")
                 : [str(p, "base"), str(p, "head")];
-            try {
-                head = await g.revParse(worktree, hh ?? "HEAD");
-                base = bb
-                    ? await g.revParse(worktree, bb)
-                    : await g.mergeBase(worktree, await g.trunkRef(worktree), head);
-            }
-            catch (e) {
-                throw new AxiError(e.message, "VALIDATION_ERROR", [
-                    "Pass resolvable refs: `thurview scaffold --base <ref> --head <ref>`",
-                ]);
-            }
+            ({ base, head } = await pinRange(worktree, bb, hh, "thurview scaffold --base <ref> --head <ref>"));
             binding = { kind: "range", name: `${base.slice(0, 12)}..${head.slice(0, 12)}` };
         }
         else {
@@ -896,7 +913,7 @@ const commands = {
         let interfaces = null;
         if (kind === "review") {
             try {
-                interfaces = await deltaFor(review);
+                interfaces = await deltaFor(pinnedOf(review));
             }
             catch (e) {
                 diags.push({
@@ -1229,17 +1246,37 @@ const commands = {
         const side = str(p, "graph") ?? "head";
         if (side !== "head" && side !== "base")
             throw new AxiError("--graph must be head or base", "VALIDATION_ERROR", help);
+        const baseRef = str(p, "base");
+        const headRef = str(p, "head");
+        const commits = baseRef !== undefined || headRef !== undefined;
+        if (commits && str(p, "review"))
+            throw new AxiError("pass --review or --base/--head, not both", "VALIDATION_ERROR", help);
         const graph = await import("./graph.js");
-        const review = await resolveReview(str(p, "review"));
-        if (kindOf(review) === "explainer" && (sub === "interfaces" || sub === "impact"))
+        const review = commits ? null : await resolveReview(str(p, "review"));
+        let t;
+        if (review)
+            t = pinnedOf(review);
+        else {
+            const worktree = await worktreeOf(process.cwd());
+            if (!worktree)
+                throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
+                    "Run inside the source worktree, or pass --review <id>",
+                ]);
+            // No review directory owns these graphs, and a commit's graph is the same
+            // whoever asks, so they share one cache under the thurview home.
+            const pins = await pinRange(worktree, baseRef, headRef, "thurview graph impact --base <ref>");
+            t = { worktree, pins, dir: home() };
+        }
+        // A next step has to name the same commits, or it answers about another change.
+        const again = review ? "" : ` --base ${short(t.pins.base)} --head ${short(t.pins.head)}`;
+        if (review && kindOf(review) === "explainer" && (sub === "interfaces" || sub === "impact"))
             throw new AxiError(`graph ${sub} compares two commits; an explainer is pinned to one`, "VALIDATION_ERROR", [
                 `Run \`thurview graph architecture --review ${short(review.id)}\` for the structure at that commit`,
                 `Run \`thurview graph callers <name> --review ${short(review.id)}\` to follow one symbol`,
             ]);
-        const dir = reviewDir(review.id);
-        const at = (commit) => graph.graphAt(review.worktree, commit, dir);
+        const at = (commit) => graph.graphAt(t.worktree, commit, t.dir);
         if (sub === "callers" || sub === "tests-for") {
-            const g = await at(side === "base" ? review.pins.base : review.pins.head);
+            const g = await at(side === "base" ? t.pins.base : t.pins.head);
             const pins = {
                 graph: side,
                 commit: short(g.commit),
@@ -1251,25 +1288,25 @@ const commands = {
                     ...pins,
                     symbol: name,
                     callers: graph.callers(g, name),
-                    help: [`Run \`thurview graph tests-for ${name}\` to see what exercises it`],
+                    help: [`Run \`thurview graph tests-for ${name}${again}\` to see what exercises it`],
                 };
             return {
                 ...pins,
                 symbol: name,
                 depth,
                 tests: graph.testsFor(g, name, depth),
-                help: [`Run \`thurview graph callers ${name}\` for every reference`],
+                help: [`Run \`thurview graph callers ${name}${again}\` for every reference`],
             };
         }
-        const base = await at(review.pins.base);
-        const head = await at(review.pins.head);
+        const base = await at(t.pins.base);
+        const head = await at(t.pins.head);
         const pins = {
             base: short(base.commit),
             head: short(head.commit),
             languages: graph.LANGUAGES.join(","),
         };
         if (sub === "interfaces") {
-            const delta = await deltaFor(review, base, head);
+            const delta = await deltaFor(t, base, head);
             return {
                 ...pins,
                 verdict: delta.verdict,
@@ -1287,29 +1324,31 @@ const commands = {
                 unreadable: delta.unreadable,
                 truncated: delta.truncated,
                 help: [
-                    "Write one capability line per entry in data.yaml under `interfaces`, keyed by id",
-                    "Run `thurview graph callers <name>` to see who a removed or changed interface reached",
+                    ...(review
+                        ? ["Write one capability line per entry in data.yaml under `interfaces`, keyed by id"]
+                        : []),
+                    `Run \`thurview graph callers <name>${again}\` to see who a removed or changed interface reached`,
                 ],
             };
         }
         if (sub === "impact") {
-            const changes = await g.lineChanges(review.worktree, review.pins.base, review.pins.head);
+            const changes = await g.lineChanges(t.worktree, t.pins.base, t.pins.head);
             return {
                 ...pins,
                 depth,
                 ...graph.impact(base, head, changes, depth),
                 help: [
-                    "Run `thurview graph callers <name>` to follow one symbol",
-                    "Run `thurview graph architecture` for the module structure and its diff",
+                    `Run \`thurview graph callers <name>${again}\` to follow one symbol`,
+                    `Run \`thurview graph architecture${again}\` for the module structure and its diff`,
                 ],
             };
         }
         // An explainer is scoped to a path, so its structure is that path's, not the
         // repository's: the same bound the Coverage tab accounts for.
-        if (kindOf(review) === "explainer") {
+        if (review && kindOf(review) === "explainer") {
             const scope = review.binding.name;
             const g0 = scopeGraph(head, scope);
-            const allFiles = await g.listFiles(review.worktree, review.pins.head);
+            const allFiles = await g.listFiles(t.worktree, t.pins.head);
             const { diff: _diff, truncated: _truncated, ...rest } = graph.architecture(g0, g0);
             return {
                 commit: short(head.commit),
@@ -1787,7 +1826,7 @@ const commands = {
             return {
                 skill: installed,
                 help: [
-                    "Invoke them as /thurview and /forge-review in Claude Code, or by name in other agents",
+                    "Invoke them as /thurview and /review-fix in Claude Code, or by name in other agents",
                     "Run `thurview setup hooks` for ambient context at session start",
                 ],
             };