thurview 0.20.0 → 0.21.0

package/dist/pr-review/format.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { AxiError } from "axi-sdk-js";
+import { CATEGORIES, CATEGORY_IDS, SEVERITIES, } from "./categories.js";
+/**
+ * What a change request review posts, and how it reads it back. Everything a
+ * follow loop needs to resume lives in two hidden markers on the forge - one
+ * on the summary, one on each finding's thread - so a restart reads the state
+ * back from the change request and never from this machine.
+ */
+/** The summary's word budget, the counts table and the marker excluded. */
+export const SUMMARY_WORDS = 120;
+/** A finding's visible lines, its suggestion block excluded and its sign-off included. */
+export const FINDING_LINES = 5;
+const SUMMARY_TAG = "thurview-pr-review";
+const FINDING_TAG = "thurview-finding";
+const Finding = z.object({
+    id: z
+        .string()
+        .regex(/^[a-z0-9-]+$/)
+        .optional(),
+    category: z.enum(CATEGORY_IDS),
+    severity: z.enum(SEVERITIES),
+    path: z.string().min(1),
+    line: z.number().int().positive(),
+    startLine: z.number().int().positive().optional(),
+    side: z.enum(["head", "base"]).optional(),
+    title: z.string().min(1),
+    body: z.string().default(""),
+    suggestion: z.string().optional(),
+});
+const PassSchema = z.object({
+    /** The head this pass reviewed; `sync` refuses it once the change request moved on. */
+    head: z.string().min(7),
+    confidence: z.number().int().min(1).max(5),
+    reason: z.string().min(1),
+    risk: z.array(z.string().min(1)).min(1).max(5),
+    change: z.string().min(1),
+    reviewUrl: z.string().url().optional(),
+    signoff: z.string().optional(),
+    findings: z.array(Finding).default([]),
+    fixed: z.array(z.string()).default([]),
+});
+export function parsePass(text, file) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new AxiError(`${file} is not valid JSON: ${e.message}`, "VALIDATION_ERROR", [
+            "Read `thurview pr-review --help` for the pass file's shape",
+        ]);
+    }
+    const parsed = PassSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new AxiError(`${file} is not a pass: ${parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"} ${i.message}`)
+            .join("; ")}`, "VALIDATION_ERROR", [
+            `category is one of ${CATEGORY_IDS.join(", ")}; severity is one of ${SEVERITIES.join(", ")}`,
+            "confidence is 1-5; risk holds 1 to 5 bullets",
+        ]);
+    checkPass(parsed.data);
+    return parsed.data;
+}
+/** The rules no schema says: one line per title, and the comment budget. */
+export function checkPass(p) {
+    // A newline would let a line pass as a table row or the marker, and so
+    // slip past the word budget; every one of these is one line by design.
+    const oneLine = [
+        ["reason", p.reason],
+        ["change", p.change],
+        ["signoff", p.signoff],
+        ...p.risk.map((r, i) => [`risk[${i}]`, r]),
+    ];
+    for (const [field, text] of oneLine)
+        if (text && /[\r\n]/.test(text.trim()))
+            throw new AxiError(`${field} is more than one line`, "VALIDATION_ERROR", [
+                "reason, each risk bullet, change and signoff are one line each",
+            ]);
+    for (const f of p.findings ?? []) {
+        const at = `${f.path}:${f.line}`;
+        if (f.title.includes("\n"))
+            throw new AxiError(`${at}: the title is more than one line`, "VALIDATION_ERROR", [
+                "The title is the claim, in one line; the fix goes in body",
+            ]);
+        if (f.startLine && f.startLine > f.line)
+            throw new AxiError(`${at}: startLine ${f.startLine} is after line`, "VALIDATION_ERROR", [
+                "line is the LAST line of the range and startLine the first",
+            ]);
+        const lines = visibleLines(f, p.signoff);
+        if (lines > FINDING_LINES)
+            throw new AxiError(`${at}: the comment is ${lines} lines, over the ${FINDING_LINES}-line budget`, "VALIDATION_ERROR", ["One point per comment: cut it to the claim and one fix, or split it in two"]);
+    }
+}
+function visibleLines(f, signoff) {
+    const body = f.body?.trim() ? f.body.trim().split("\n").length : 0;
+    return 1 + body + (signoff ? 1 : 0);
+}
+/** Stable across passes, so the same finding found twice is recognised as one. */
+export function findingId(f) {
+    if (f.id)
+        return f.id;
+    const h = createHash("sha1").update(`${f.category}\n${f.path}\n${f.title.trim()}`);
+    return h.digest("hex").slice(0, 10);
+}
+function marker(tag, data) {
+    return `<!-- ${tag} ${JSON.stringify(data)} -->`;
+}
+function readMarker(tag, body) {
+    const m = new RegExp(`^<!-- ${tag} (\\{.*?\\}) -->`).exec(body);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+export function readSummaryMarker(body) {
+    return readMarker(SUMMARY_TAG, body);
+}
+export function readFindingMarker(body) {
+    const m = readMarker(FINDING_TAG, body);
+    if (!m || !(m.category in CATEGORIES) || !SEVERITIES.includes(m.severity))
+        return null;
+    const heading = body.split("\n")[1] ?? "";
+    return { ...m, title: heading.replace(/^.*?:\*\* /, "") };
+}
+/**
+ * One finding as an inline comment: the claim, the fix, a suggestion the
+ * author can apply. GitHub anchors a range and replaces all of it; GitLab
+ * anchors the range's last line, so its suggestion reaches back over the rest.
+ */
+export function renderFinding(f, signoff, forge) {
+    const label = CATEGORIES[f.category].label;
+    const head = f.severity === "nit"
+        ? `nit: **${label}:** ${f.title.trim()}`
+        : `**${label} · ${f.severity}:** ${f.title.trim()}`;
+    const parts = [
+        marker(FINDING_TAG, { id: findingId(f), category: f.category, severity: f.severity }),
+        head,
+    ];
+    if (f.body?.trim())
+        parts.push(f.body.trim());
+    if (f.suggestion !== undefined) {
+        const above = f.startLine && f.startLine < f.line ? f.line - f.startLine : 0;
+        const fence = forge === "gitlab" ? `\`\`\`suggestion:-${above}+0` : "```suggestion";
+        parts.push(`${fence}\n${f.suggestion.replace(/\n$/, "")}\n\`\`\``);
+    }
+    if (signoff)
+        parts.push(signoff);
+    return parts.join("\n");
+}
+function table(open) {
+    if (!open.length)
+        return "No open findings.";
+    const rows = CATEGORY_IDS.filter((c) => open.some((f) => f.category === c)).map((c) => {
+        const n = (s) => open.filter((f) => f.category === c && f.severity === s).length;
+        return `| ${CATEGORIES[c].label} | ${SEVERITIES.map(n).join(" | ")} |`;
+    });
+    return [
+        `| Open findings | ${SEVERITIES.join(" | ")} |`,
+        `| --- | ${SEVERITIES.map(() => "---").join(" | ")} |`,
+        ...rows,
+    ].join("\n");
+}
+function headline(p, author, open) {
+    const blocking = open.filter((f) => f.severity === "blocking").length;
+    if (blocking)
+        return `Next: @${author} — fix the ${blocking} blocking finding${blocking === 1 ? "" : "s"}.`;
+    if (p.confidence >= 4)
+        return "Next: merge";
+    return `Next: @${author} — answer the risk below.`;
+}
+/** The line a stopped or finished review opens with instead of a next step. */
+export function statusLine(m) {
+    const at = m.head.slice(0, 7);
+    if (m.state === "stopped")
+        return `Review stopped at ${at}. Remove the \`thurview:stop\` label and run \`thurview pr-review start\` to resume.`;
+    if (m.state === "merged" || m.state === "closed")
+        return `Review ended: ${m.state} at ${at}.`;
+    return null;
+}
+/** Words a reader reads: the marker and the counts table are not prose. */
+export function summaryWords(body) {
+    return body
+        .split("\n")
+        .filter((l) => !l.startsWith("<!--") && !l.startsWith("|"))
+        .join(" ")
+        .split(/\s+/)
+        .filter((w) => /[\p{L}\p{N}]/u.test(w)).length;
+}
+/**
+ * The one summary a change request carries: the next step, the confidence
+ * with its reason, the risk, the change in short, the open findings by
+ * category and severity, and a link to the full review when there is one.
+ */
+export function renderSummary(p, m, author, open) {
+    const tail = [`Reviewed \`${m.head.slice(0, 7)}\``];
+    if (p.reviewUrl)
+        tail.push(`[Full review](${p.reviewUrl})`);
+    const parts = [
+        `${marker(SUMMARY_TAG, m)}\n${statusLine(m) ?? headline(p, author, open)}`,
+        `**Confidence ${p.confidence}/5:** ${p.reason.trim()}`,
+        `**Risk**\n${p.risk.map((r) => `- ${r.trim()}`).join("\n")}`,
+        `**Change:** ${p.change.trim()}`,
+        table(open),
+        tail.join(" · "),
+    ];
+    if (p.signoff)
+        parts.push(p.signoff);
+    const body = parts.join("\n\n");
+    const words = summaryWords(body);
+    if (words > SUMMARY_WORDS)
+        throw new AxiError(`the summary is ${words} words, over the ${SUMMARY_WORDS}-word budget`, "VALIDATION_ERROR", ["Cut reason, risk and change to what the author acts on; the full review holds the rest"]);
+    return body;
+}
+/** The same summary under a new marker and opening line; the rest is kept as written. */
+export function restate(body, m, opening) {
+    const lines = body.split("\n");
+    return [marker(SUMMARY_TAG, m), opening, ...lines.slice(2)].join("\n");
+}
+export function bareSummary(m, opening) {
+    return `${marker(SUMMARY_TAG, m)}\n${opening}`;
+}
+//# sourceMappingURL=format.js.map

package/dist/pr-review/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/pr-review/format.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.20.0",
+  "version": "0.21.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",

package/skills/thurview-pr-review/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: thurview-pr-review
+description: Review a pull or merge request on the forge itself and follow it until it merges - one short summary with a confidence score that is edited in place, one resolvable inline thread per finding in a fixed set of categories, threads resolved as their findings are fixed, and only what each push changed re-reviewed. Use when the user asks to review a PR or MR and post the review on it, to watch or follow a PR until it lands, for a Greptile-style or bot-style review, or invokes /thurview-pr-review. Not for a review the reader opens in the browser, which is the thurview skill, nor for fixing what a review finds, which is thurview-fix.
+user-invocable: true
+argument-hint: "<PR or MR number or URL> [--once] [--stop]"
+---
+
+# thurview-pr-review
+
+Review a change request where its author already is, and keep the review true
+until the change request is merged or closed. The forge holds all the state:
+one summary note with a hidden marker, one thread per finding with a hidden
+marker. Nothing is kept on this machine, so the loop can die and resume
+anywhere.
+
+```mermaid
+flowchart LR
+  W[wait] -->|push| R[review only what moved]
+  R --> S[sync: new threads, resolve fixed, edit summary]
+  S --> W
+  W -->|merged, closed, stopped| E[summary says so; stop]
+  W -->|none| W
+```
+
+Run the CLI as `thurview`, or `npx -y thurview` when it is not on PATH. It
+prints TOON, and exit code 2 is a usage error. If it answers `unknown flag` or
+`unknown command` for something below, run `thurview update` and retry once.
+
+## Request
+
+$ARGUMENTS
+
+`--once` posts one pass and stops there. `--stop` runs
+`thurview pr-review stop --change <ref>` and nothing else.
+
+## Never
+
+- Never approve, merge, close or push to the change request. The verdict is
+  the summary's confidence. The command has no verb for any of those, and you
+  do not reach around it with `gh` or `glab`.
+- Never post a second summary. `sync` edits the one it finds.
+- Never post a finding you are not sure of. Leave it out and say in a risk
+  bullet that something was not confirmed.
+- Never post what you would not sign. Follow the user's own rules for text
+  posted in their name when they keep any - a sign-off line goes in `signoff`.
+
+## 1. Where the review stands
+
+```sh
+thurview pr-review status --change <ref>
+```
+
+It prints the change request's head and base, the head the last pass reviewed
+(`review.reviewedHead`), every open finding with its `id`, and the categories
+and confidence scale below. A stopped review stays stopped: do not sync it.
+
+## 2. Review only what moved
+
+- No summary yet: review `git diff <base> <head>`, the whole change.
+- A summary at an older head: review `git diff <reviewedHead> <head>`. When
+  `git merge-base --is-ancestor <reviewedHead> <head>` fails, the branch was
+  rewritten: review the whole change again.
+
+Fetch the head first (`gh pr checkout <n>` or `glab mr checkout <n>`, or
+`git fetch origin <fetchRef>`), and search at the pinned commits with the
+recipes in the `thurview` skill's Searching the code reference
+(`thurview skill` prints its path). The evidence rules are `thurview-fix`'s:
+a problem just as present at the base is not this change's finding, and a
+finding that rests on "no callers" says which search found none.
+
+Then decide each open finding against the new head: **fixed**, or **still
+valid** (do nothing - its thread stays open and is not posted again).
+
+## 3. Findings
+
+One point per finding, on a line the diff touches - the forge refuses any
+other line. Prefer one real defect over many nits.
+
+| Category          | Definition                                                                     |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `bug`             | The code does the wrong thing for an input it accepts.                         |
+| `security`        | An attacker gains access, data or execution they should not have.              |
+| `performance`     | Time, memory or calls grow worse than the change needs.                        |
+| `reliability`     | A failure, retry, timeout or race is handled wrongly or not at all.            |
+| `compatibility`   | A public API, schema, config, flag or data format breaks its callers.          |
+| `maintainability` | The next change here is harder: duplication, dead code, a misleading name.     |
+| `tests`           | A behaviour the change adds or alters is not tested, or a test proves nothing. |
+| `docs`            | A comment, README or doc now says something the code does not do.              |
+
+Severity is `blocking` (must be fixed before merge), `non-blocking` (worth
+fixing) or `nit` (taste, and the comment says `nit:`).
+
+Confidence that the change is safe to merge:
+
+| Score | Meaning                                                     |
+| ----- | ----------------------------------------------------------- |
+| 5     | Safe to merge; nothing open beyond nits.                    |
+| 4     | Safe to merge; non-blocking findings are worth a look.      |
+| 3     | Unsure: a risk is named that the review could not rule out. |
+| 2     | Not yet: a blocking finding is open.                        |
+| 1     | Do not merge: it breaks something that works today.         |
+
+An open blocking finding caps confidence at 2; `sync` refuses more.
+
+## 4. Sync
+
+Write `pass.json` for this head. `findings` holds only what is new; `fixed`
+holds the ids of open findings this push fixed:
+
+```json
+{
+  "head": "<the full sha you reviewed>",
+  "confidence": 2,
+  "reason": "Safe once the retry loop stops on a 4xx.",
+  "risk": ["Every upload goes through the changed retry path.", "No test covers a 4xx."],
+  "change": "Retries a failed upload three times with exponential backoff.",
+  "reviewUrl": "https://reviews.example.com/pr-7/",
+  "signoff": "<the user's sign-off line, when they keep one>",
+  "findings": [
+    {
+      "category": "bug",
+      "severity": "blocking",
+      "path": "src/upload.ts",
+      "line": 42,
+      "startLine": 40,
+      "title": "The retry loop never stops on a 4xx.",
+      "body": "Return the response on any status below 500.",
+      "suggestion": "if (res.status < 500) return res;"
+    }
+  ],
+  "fixed": ["3f2a9c1b07"]
+}
+```
+
+- `head` is the commit you reviewed. `sync` refuses the pass when the change
+  request moved on since: review what the new push added, then sync again.
+- `reason`, `change`, `signoff` and each `risk` bullet are one line each;
+  `sync` refuses a line break in any of them. `reason` is one sentence;
+  `risk` is one to five bullets naming what could break, the blast radius, and
+  anything touching security, data, infra or a public API; `change` is two or
+  three sentences.
+- The summary is capped at 120 words, the counts table aside. `sync` refuses
+  more: cut to what the author acts on.
+- A finding's `title` is the claim in one line, `body` the fix. Title, body
+  and sign-off together fit five lines. `suggestion` replaces the lines from
+  `startLine` to `line` and is optional.
+- `reviewUrl` links the full rendered review. When the user has a publish
+  target - `thurview export --out <folder>` into a Pages folder or a static
+  host they serve - publish there and pass its URL. With none, leave it out.
+
+```sh
+thurview pr-review sync --change <ref> --file pass.json --dry-run
+thurview pr-review sync --change <ref> --file pass.json
+```
+
+The dry run prints the summary as it will read. A finding already open is
+reported under `duplicates` and not posted twice.
+
+## 5. Follow
+
+```sh
+thurview pr-review wait --change <ref>      # --interval 120 --timeout 540 by default
+```
+
+It blocks until there is something to do and prints one `event`:
+
+| Event                         | Do                                           |
+| ----------------------------- | -------------------------------------------- |
+| `push`                        | back to step 2, with `since` as the old head |
+| `none`                        | run `wait` again                             |
+| `merged`, `closed`, `stopped` | stop: the summary already says so            |
+
+With `--once`, stop after the first sync.
+
+A reader stops the loop with the `thurview:stop` label or a comment that
+starts `/thurview stop`; you stop it with `thurview pr-review stop`. A stopped
+review resumes with `thurview pr-review start --change <ref>` once the label
+is gone. Report what you posted and the summary's link when the loop ends.
+
+How GitHub and GitLab differ, and what each supports, is in
+[Forges](references/forges.md).

package/skills/thurview-pr-review/references/forges.md

@@ -0,0 +1,47 @@
+# Forges
+
+`thurview pr-review` drives the same seam as `thurview forge`: `gh api` for
+GitHub and `glab api` for GitLab, a self-hosted host owned by whichever CLI is
+authenticated for it. The seam has no merge, close or push, so neither does
+this command.
+
+## What each forge does
+
+| Step              | GitHub                                     | GitLab                                              |
+| ----------------- | ------------------------------------------ | --------------------------------------------------- |
+| The summary       | one issue comment, `PATCH`ed in place      | one merge request note, `PUT` in place              |
+| A finding         | one review comment, a resolvable thread    | one diff discussion, a resolvable thread            |
+| A line range      | anchored as the range                      | anchored at its last line                           |
+| A suggestion      | ` ```suggestion ` over the range           | ` ```suggestion:-N+0 ` reaching back over the range |
+| Resolving a fixed | a reply, then `resolveReviewThread`        | a reply, then `PUT .../discussions/<id>` resolved   |
+| The stop label    | `thurview:stop` among the pull's labels    | `thurview:stop` among the merge request's labels    |
+| The stop command  | an issue comment starting `/thurview stop` | a top-level note starting `/thurview stop`          |
+| Merged or closed  | `merged`, or `state: closed`               | `state: merged` or `closed`                         |
+
+## Where the state lives
+
+The summary carries
+`<!-- thurview-pr-review {"head":"<sha>","state":"active","seen":"<note id>"} -->`
+and each finding's first comment
+`<!-- thurview-finding {"id":"<id>","category":"bug","severity":"blocking"} -->`.
+`state` is `active`, `stopped`, `merged` or `closed`. `seen` is the newest
+note already read, so a `/thurview stop` posted before a `start` stops nothing.
+Only a summary posted by the account the CLI is logged in as counts, so a
+pasted marker changes nothing. A finding's id is the `id` given in the pass, or a hash of its category, path
+and title, which is how the same finding found on the next push is recognised.
+
+## Gaps
+
+- No forge approve. A forge approve can arm an auto-merge, and the verdict
+  lives in the summary; `thurview forge submit` is the command for one.
+- GitHub reads the newest 100 review threads (`reviewThreads(last:100)`), the
+  same limit `thurview forge prior` has; GitLab reads every page.
+- Every call asks the forge who it is (`gh api user`, `glab api user`) to
+  tell its own markers from pasted ones, so it needs a token that can read its
+  own user; a GitHub App installation token cannot.
+- A finding must sit on a line the diff touches. A finding on an untouched
+  caller goes in a risk bullet.
+- GitLab reports no per-thread staleness, and its adapter is driven by stub
+  tests but has not been run against a live instance.
+- The full-review link is whatever URL the pass names; this command publishes
+  nothing itself.