thurview 0.6.0 → 0.8.0

package/README.md

@@ -9,6 +9,12 @@ and serves it in your browser: the walkthrough, live code peeks, the diff,
 commits, and a software map. You ask questions, leave anchored comments, and
 approve or request changes. The agent answers and republishes.
 
+It also explains a codebase. A **code explainer** is the same document over a
+different unit: one pinned commit instead of a range, so a reader can see the
+architecture well enough to spot design problems themselves. It has no diff and
+nothing to approve, it surfaces structure rather than grading it, and it states
+what it did not examine.
+
 It does not review the code for you. It helps you understand it fast enough
 to review it yourself.
 
@@ -32,10 +38,11 @@ The diff at the pinned commits, commenting on a selected line range:
 ![The Files tab, split diff, with a comment on lines 9 to 12 of
 src/auth.ts](./media/review-files.png)
 
-The software map, showing what the change added and what it touched:
+The software map: where the change landed in the system, and what sits next to
+it — the question the diff cannot answer:
 
-![The Map tab: Auth and Session store changed, Audit trail added, with its
-files and code](./media/review-map.png)
+![The Map tab: the parts the change touched, drawn first, the links between
+them, and the selected node's files, code and neighbours](./media/review-map.png)
 
 Threads: a question the agent already answered, and a comment held for the
 decision:
@@ -132,6 +139,12 @@ and open it.
   Click an identifier to see where it is defined at that commit; Ctrl-click
   jumps there.
 - **Commits**: the commits between base and head.
+- **Coverage** (explainers): every file in scope at the pinned commit, in one
+  of three states - anchored in the document, placed on the map only, or not
+  examined - with the parts of the system they belong to, the references that
+  cross between those parts, and the names defined in more than one of them.
+  Derived at publish, so what the explainer skipped is a stated fact rather
+  than something the reader has to infer.
 - **Map**: systems, containers, components and code, with what the change
   added, removed or touched, linked to files and code.
 - **Threads**: _Ask now_ sends a question to the agent immediately and the
@@ -152,18 +165,19 @@ bar.
 
 ## CLI
 
-| Command                                                               | Purpose                                                      |
-| --------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins) |
-| `thurview info [--all]`                                               | Reviews bound to this worktree                               |
-| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision               |
-| `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 serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one   |
-| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                    |
-| `thurview update`                                                     | Self-update from npm                                         |
+| Command                                                               | Purpose                                                          |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)     |
+| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit |
+| `thurview info [--all]`                                               | Reviews bound to this worktree                                   |
+| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                   |
+| `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 serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one       |
+| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                        |
+| `thurview update`                                                     | Self-update from npm                                             |
 
 thurview is an [AXI](https://axi.md): built for agents that drive it through a
 shell. Output is [TOON](https://toonformat.dev) on stdout, errors are
@@ -185,16 +199,22 @@ The agent writes three files in `~/.thurview/reviews/<id>/`:
 - `data.yaml`: typed inputs: `actors`, `anchors` (file, from, to, graph),
   `stores`, `interfaces` (a capability line per derived entry, plus the
   interfaces the graph cannot see).
-- `map.yaml`: the software map at head, optionally at base.
+- `map.yaml`: the software map at head, optionally at base. In an explainer it
+  carries the breadth the prose has no room for, and a node's `files` globs are
+  what let a file count as placed rather than not examined.
 - `theme.yaml`: the look, derived from the reviewed project's own design
   system (tokens, fonts, shape, code palette). Empty means the default skin.
 
+An explainer writes the same files, minus `interfaces`: there is no change to
+derive a delta from, and `graph: base` on an anchor is an error because there
+is one commit.
+
 `thurview publish` rejects an anchor whose file or lines do not exist at the
 pinned commit, a call stack frame that claims an added or removed call the
 diff does not show, a storage operation on an unknown field, a map edge
 to an unknown node, an interface annotation for a symbol the change did not
-move, and a declared interface whose anchor holds no added or deleted line.
-The full format is in
+move, a declared interface whose anchor holds no added or deleted line, and an
+explainer that anchors nothing at all. The full format is in
 [skills/thurview/references](skills/thurview/references).
 
 Optional guidance for the agent: `~/.thurview/THURVIEW.md` for you,

package/dist/cli.js

@@ -9,8 +9,9 @@ import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import open from "open";
 import * as g from "./git.js";
-import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, } from "./store.js";
-import { compileDocument, compileMap } from "./document/compile.js";
+import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, kindOf, } from "./store.js";
+import { compileDocument, compileMap, globToRegExp } from "./document/compile.js";
+import { computeCoverage, scopeGlob, scopeGraph, scopeTruncated, } from "./coverage.js";
 import { parseTheme, compileTheme } from "./theme.js";
 import { registerTheme } from "./highlight.js";
 import { replyThread, setThreadStatus, needsAgent } from "./threads.js";
@@ -19,7 +20,7 @@ import { parseFlags, helpFor, str, bool } from "./flags.js";
 import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
-const DESCRIPTION = "Guided, evidence-anchored reviews of agent-written code, read and answered in the browser";
+const DESCRIPTION = "Guided, evidence-anchored reviews of a change and explainers of a codebase, read and answered in the browser";
 function note(msg) {
     process.stderr.write(msg + "\n");
 }
@@ -86,6 +87,7 @@ async function reviewRow(r, fields) {
     const t = await readThreads(r.id);
     const row = {
         id: short(r.id),
+        kind: kindOf(r),
         title: r.title,
         status: r.status,
         rev: r.revision,
@@ -95,7 +97,10 @@ async function reviewRow(r, fields) {
     if (fields.has("all") || fields.has("binding"))
         row["binding"] = r.binding.kind === "pr" ? `PR #${r.binding.name}` : r.binding.name;
     if (fields.has("all") || fields.has("pins"))
-        row["pins"] = `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`;
+        row["pins"] =
+            kindOf(r) === "explainer"
+                ? r.pins.head.slice(0, 12)
+                : `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`;
     if (fields.has("all") || fields.has("worktree"))
         row["worktree"] = r.worktree;
     if (fields.has("all") || fields.has("inSync"))
@@ -216,7 +221,9 @@ anchors: {}
 stores: {}
 interfaces: {}
 `;
-const TEMPLATE_MAP = `# Software map: people, systems, containers, components, code. Empty nodes = no map.
+const TEMPLATE_MAP = `# Software map: where this change landed in the system, and what sits next to it.
+# People, systems, containers, components, code. Leave nodes empty when the change
+# lands in one place and the Files tab already answers that.
 nodes: []
 edges: []
 `;
@@ -232,6 +239,33 @@ const TEMPLATE_THEME = `# Look of this review, derived from the reviewed project
 # shape: { radius: 8px, bevel: false, glow: false, scanlines: false, headingTransform: none }
 # code: { keyword: "#7c3aed", string: "#15803d", function: "#b45309", variable: "#0369a1", comment: "#9ca3af" }
 `;
+const TEMPLATE_EXPLAIN_MD = (title) => `# ${title}
+
+**Summary**
+
+- The agent is still writing this explainer. The Coverage tab already states
+  what it has and has not examined at the pinned commit; this page offers the
+  new revision when the walkthrough lands.
+`;
+const TEMPLATE_EXPLAIN_DATA = `# Typed inputs for the explainer: actors, anchors and stores. An explainer has
+# one pinned commit, so every anchor reads that commit and \`graph: base\` is an
+# error. It has no interface delta: there is no change to take one from.
+#
+# anchors:
+#   dispatch:
+#     title: where a request picks its handler
+#     peek: { file: src/server/router.ts, from: 41, to: 58 }
+actors: {}
+anchors: {}
+stores: {}
+`;
+const TEMPLATE_EXPLAIN_MAP = `# The structure of the code at the pinned commit: systems, containers,
+# components, code. The map carries breadth so the prose can carry depth, and a
+# node's \`files\` globs are what tell the Coverage tab a file was at least placed.
+# Seed it from \`thurview graph architecture\`.
+nodes: []
+edges: []
+`;
 // ---- commands ----
 const SPECS = {
     scaffold: {
@@ -252,8 +286,25 @@ const SPECS = {
             "thurview scaffold --update --review <id>",
         ],
     },
+    explain: {
+        description: "Create a code explainer pinned to one commit: a whole codebase, or one subsystem of it",
+        args: "[<path scope>]",
+        flags: {
+            commit: { kind: "string", help: "commit to pin (default: HEAD)" },
+            title: { kind: "string", help: "initial title" },
+            new: { kind: "boolean", help: "create another explainer even if one matches the scope" },
+            update: { kind: "boolean", help: "re-pin an existing explainer to a new commit" },
+            review: { kind: "string", help: "explainer to update (id prefix)" },
+        },
+        examples: [
+            "thurview explain",
+            "thurview explain src/server",
+            "thurview explain --commit v1.2.0",
+            "thurview explain --update --review <id>",
+        ],
+    },
     info: {
-        description: "Reviews bound to this worktree (or every review with --all)",
+        description: "Reviews and explainers bound to this worktree (or all of them with --all)",
         flags: {
             all: { kind: "boolean", help: "every review, not only this worktree" },
             fields: {
@@ -393,6 +444,7 @@ async function homeView() {
             help: [
                 "Run `thurview scaffold` to create a review of the current branch",
                 "Run `thurview scaffold --pr <number>` for a pull request",
+                "Run `thurview explain [<path>]` to explain the codebase at HEAD instead",
             ],
         };
     const reviews = [];
@@ -573,6 +625,119 @@ const commands = {
             ],
         };
     },
+    async explain(args) {
+        const p = parseFlags("explain", args, spec("explain").flags, 1);
+        const cwd = process.cwd();
+        const worktree = await worktreeOf(cwd);
+        if (!worktree)
+            throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
+                "Run `thurview explain` inside the source worktree",
+            ]);
+        const existing = bool(p, "update") || str(p, "review") ? await resolveReview(str(p, "review")) : null;
+        if (existing && kindOf(existing) !== "explainer")
+            throw new AxiError(`${short(existing.id)} is a review, not an explainer`, "VALIDATION_ERROR", [
+                "Run `thurview scaffold --update --review <id>` to re-pin a review",
+                "Run `thurview explain` with no --review to start an explainer",
+            ]);
+        const scope = scopeGlob(p.positional[0] ?? existing?.binding.name);
+        let commit;
+        try {
+            commit = await g.revParse(worktree, str(p, "commit") ?? "HEAD");
+        }
+        catch (e) {
+            throw new AxiError(e.message, "VALIDATION_ERROR", [
+                "Pass a resolvable ref: `thurview explain --commit <ref>`",
+            ]);
+        }
+        // A scope that matches nothing is a typo, and an explainer of nothing would
+        // still publish and still state honest-looking coverage of zero files.
+        const files = await g.listFiles(worktree, commit);
+        const inScope = scope === "**" ? files : files.filter((f) => globToRegExp(scope).test(f));
+        if (!inScope.length)
+            throw new AxiError(`no file matches "${scope}" at ${commit.slice(0, 12)}`, "VALIDATION_ERROR", [
+                "Pass a path that exists at that commit: `thurview explain src/server`",
+                "Run `thurview explain` with no scope for the whole repository",
+            ]);
+        const binding = { kind: "codebase", name: scope };
+        const defaultTitle = scope === "**" ? worktree.split("/").pop() || "Codebase" : scope.replace(/\/\*\*$/, "");
+        let review;
+        let reused = false;
+        if (existing) {
+            review = existing;
+            review.pins = { base: commit, head: commit };
+            review.binding = binding;
+            if (str(p, "title"))
+                review.title = str(p, "title");
+            await writeReview(review);
+        }
+        else {
+            const match = bool(p, "new")
+                ? []
+                : (await reviewsFor(worktree)).filter((r) => kindOf(r) === "explainer" &&
+                    r.binding.name === scope &&
+                    r.status !== "accepted" &&
+                    r.status !== "closed");
+            if (match.length) {
+                review = match[0];
+                reused = true;
+                review.pins = { base: commit, head: commit };
+                await writeReview(review);
+            }
+            else {
+                const id = newId();
+                review = {
+                    schema: SCHEMA,
+                    id,
+                    kind: "explainer",
+                    title: str(p, "title") || defaultTitle,
+                    worktree,
+                    repoRoot: worktree,
+                    binding,
+                    pins: { base: commit, head: commit },
+                    status: "draft",
+                    revision: 0,
+                    dismissed: false,
+                    createdAt: now(),
+                    updatedAt: now(),
+                };
+                await mkdir(reviewDir(id), { recursive: true });
+                await writeText(join(reviewDir(id), "review.md"), TEMPLATE_EXPLAIN_MD(review.title));
+                await writeText(join(reviewDir(id), "data.yaml"), TEMPLATE_EXPLAIN_DATA);
+                await writeText(join(reviewDir(id), "map.yaml"), TEMPLATE_EXPLAIN_MAP);
+                await writeText(join(reviewDir(id), "theme.yaml"), TEMPLATE_THEME);
+                await writeReview(review);
+            }
+        }
+        const dir = reviewDir(review.id);
+        return {
+            explainer: {
+                id: short(review.id),
+                uuid: review.id,
+                kind: "explainer",
+                title: review.title,
+                status: review.status,
+                rev: review.revision,
+                scope,
+                commit,
+                worktree,
+                reused,
+                dir,
+            },
+            files: {
+                document: join(dir, "review.md"),
+                data: join(dir, "data.yaml"),
+                map: join(dir, "map.yaml"),
+                theme: join(dir, "theme.yaml"),
+            },
+            scale: { filesInScope: inScope.length },
+            guidance: await guidanceFiles(worktree),
+            help: [
+                `Run \`thurview graph architecture --review ${short(review.id)}\` for the clusters, their hubs and the links between them`,
+                `Author ${join(dir, "map.yaml")} first: it carries the breadth the prose cannot`,
+                `Edit ${join(dir, "review.md")} and data.yaml, then run \`thurview publish --review ${short(review.id)}\``,
+            ],
+        };
+    },
     async info(args) {
         const p = parseFlags("info", args, spec("info").flags);
         const fields = new Set((str(p, "fields") ?? "").split(",").filter(Boolean));
@@ -644,22 +809,28 @@ const commands = {
             }
         }
         const themeName = theme ? await registerTheme(theme.shiki) : undefined;
+        const kind = kindOf(review);
+        // An explainer has one pinned commit, so there is no delta to derive: the
+        // panel above its document states coverage instead.
         let interfaces = null;
-        try {
-            interfaces = await deltaFor(review);
-        }
-        catch (e) {
-            diags.push({
-                level: "warning",
-                file: "review.md",
-                message: `the interface delta is unavailable: ${e.message}`,
-            });
+        if (kind === "review") {
+            try {
+                interfaces = await deltaFor(review);
+            }
+            catch (e) {
+                diags.push({
+                    level: "warning",
+                    file: "review.md",
+                    message: `the interface delta is unavailable: ${e.message}`,
+                });
+            }
         }
         const doc = await compileDocument({
             cwd: review.worktree,
             pins: review.pins,
             reviewMd,
             dataYaml: dataYaml ?? "",
+            kind,
             ...(themeName ? { themeName } : {}),
             interfaces,
         });
@@ -671,6 +842,7 @@ const commands = {
                 pins: review.pins,
                 mapYaml,
                 anchors: doc.anchors,
+                kind,
             });
             diags.push(...m.diagnostics);
             map = m.map;
@@ -693,7 +865,54 @@ const commands = {
                 ],
             };
         }
+        // Coverage is derived, not claimed: every file in scope at the pinned commit
+        // is accounted for, so the reader is told what the prose never reached.
+        let coverage = null;
+        if (kind === "explainer") {
+            try {
+                const graph = await import("./graph.js");
+                const g0 = await graph.graphAt(review.worktree, review.pins.head, dir);
+                coverage = computeCoverage({
+                    commit: review.pins.head,
+                    scope: review.binding.name,
+                    allFiles: await g.listFiles(review.worktree, review.pins.head),
+                    graph: g0,
+                    anchored: Object.values(doc.document.anchors)
+                        .map((a) => a.peek?.file)
+                        .filter((f) => !!f),
+                    owners: (map?.head.nodes ?? [])
+                        .filter((n) => n.files?.length)
+                        .map((n) => ({ node: n.id, globs: n.files })),
+                });
+            }
+            catch (e) {
+                diags.push({
+                    level: "error",
+                    file: "review.md",
+                    message: `coverage is unavailable, so the explainer cannot state what it skipped: ${e.message}`,
+                });
+                process.exitCode = 1;
+                return {
+                    error: "publish failed: coverage could not be derived",
+                    code: "PUBLISH_FAILED",
+                    diagnostics: diags.map((d) => ({
+                        level: d.level,
+                        file: d.file,
+                        line: d.line ?? "",
+                        message: d.message,
+                    })),
+                    help: [`Run \`thurview publish --review ${short(review.id)}\` again`],
+                };
+            }
+        }
         const warnings = [];
+        if (kind === "explainer" && !map)
+            warnings.push("this explainer has no map, so every file it does not anchor counts as not examined; author map.yaml to place the rest");
+        if (review.binding.kind === "codebase") {
+            const tip = await g.revParse(review.worktree, "HEAD").catch(() => null);
+            if (tip && tip !== review.pins.head)
+                warnings.push(`HEAD has moved past the pinned commit; run \`thurview explain --update --review ${short(review.id)}\` to re-pin`);
+        }
         if (review.binding.kind === "branch") {
             const tip = await g.revParse(review.worktree, review.binding.name).catch(() => null);
             if (tip && tip !== review.pins.head)
@@ -711,6 +930,7 @@ const commands = {
         await writeJson(join(rdir, "document.json"), doc.document);
         await writeJson(join(rdir, "map.json"), map);
         await writeJson(join(rdir, "changes.json"), changes);
+        await writeJson(join(rdir, "coverage.json"), coverage);
         if (themeYaml !== null)
             await cp(join(dir, "theme.yaml"), join(rdir, "theme.yaml"));
         await writeJson(join(rdir, "theme.json"), theme);
@@ -719,6 +939,7 @@ const commands = {
             at: now(),
             title: doc.document.title,
             pins: review.pins,
+            kind,
             hasMap: !!map,
             theme: theme?.name ?? "default",
         });
@@ -738,15 +959,26 @@ const commands = {
         const out = {
             published: {
                 id: short(review.id),
+                kind,
                 rev: n,
                 title: review.title,
                 status: review.status,
                 map: !!map,
-                interfaces: doc.document.interfaces?.verdict ?? "(unavailable)",
+                ...(kind === "explainer"
+                    ? { coverage: coverage ? coverage.verdict : "(unavailable)" }
+                    : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
                 theme: theme?.name ?? "default",
                 url: url ?? "(server not running)",
             },
         };
+        if (coverage)
+            out["notExamined"] = {
+                files: coverage.states.uncovered,
+                first: coverage.uncovered.slice(0, 8),
+                byPart: coverage.clusters
+                    .filter((c) => c.uncovered.length)
+                    .map((c) => ({ part: c.label, files: c.uncovered.length })),
+            };
         if (rows.length)
             out["diagnostics"] = rows;
         if (warnings.length)
@@ -910,6 +1142,11 @@ const commands = {
             throw new AxiError("--graph must be head or base", "VALIDATION_ERROR", help);
         const graph = await import("./graph.js");
         const review = await resolveReview(str(p, "review"));
+        if (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);
         if (sub === "callers" || sub === "tests-for") {
@@ -978,6 +1215,25 @@ const commands = {
                 ],
             };
         }
+        // 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") {
+            const scope = review.binding.name;
+            const g0 = scopeGraph(head, scope);
+            const allFiles = await g.listFiles(review.worktree, review.pins.head);
+            const { diff: _diff, truncated: _truncated, ...rest } = graph.architecture(g0, g0);
+            return {
+                commit: short(head.commit),
+                scope,
+                languages: pins.languages,
+                truncated: scopeTruncated(allFiles, head, scope),
+                ...rest,
+                help: [
+                    "Seed map.yaml nodes from communities, their `files` from a community's files, and edges from edges",
+                    "A file in no community is outside the languages the graph reads; `thurview publish` counts those",
+                ],
+            };
+        }
         return {
             ...pins,
             ...graph.architecture(base, head),
@@ -1238,6 +1494,7 @@ function topLevelHelp() {
         examples: [
             "thurview",
             "thurview scaffold",
+            "thurview explain src/server",
             "thurview publish --view files --open",
             "thurview wait",
             'thurview threads reply <threadId> --body "<answer>"',