@shiyuphan/follow-me 0.5.1 → 0.6.0

package/README.md

@@ -69,8 +69,11 @@ If the hashes differ, `apply` exits with code 1. The commits are signed when you
 
 The red blob in the party hat is your branch tip. Nothing follow-me does moves it.
 
-![The review page: one scrolling document of commits with the stack dropdown in the sticky header, a picked line with its Ask box, and an inline thread where the agent answers in Markdown with a diagram](assets/screenshots/review.png)
-*The review page. Pick any line, changed or not, or a range; Ask or Flag opens right under it. The agent answers inline in Markdown.*
+![The review page: the index on the left groups commits by section in top-down order, and commit 2 shows a question on a line with the agent's answer inline](assets/screenshots/review.png)
+*The review page. The index groups the commits the way they read: the story first, then the steps it calls, then the details. Pick any line, changed or not, and Ask or Flag right under it; the agent answers inline.*
+
+![Cmd-clicking format in pow opens a peek of its definition, which lives outside this branch](assets/screenshots/definition.png)
+*Cmd-click a name to jump to where it is defined, even in a later commit, and Alt+Left to come back. A definition the branch does not change opens as a peek.*
 
 ![A diagram opened in the lightbox at full size](assets/screenshots/diagram.png)
 *Diagrams sit full width under the commit or reply they explain, and open full size on click.*
@@ -78,7 +81,7 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![The hand-off page: every kept item with its original-branch path and line, an include checkbox, and copy buttons](assets/screenshots/handoff.png)
 *Submit review. Each item carries the original branch's path and line, so your agent can post it to the merge request as is.*
 
-Keys: `j` and `k` move between commits, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
+Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
 
 ### Reviewing someone else's branch
 

package/dist/src/cli.js

@@ -3,13 +3,14 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { definitionIndex, isIdentifier } from "./definition.js";
 import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
 import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
 import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } from "./install.js";
 import { naiveDraft } from "./naive.js";
 import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
-import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownUnit, reportItems, } from "./prompt.js";
+import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownDefinitions, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
 import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
@@ -30,9 +31,10 @@ Other commands:
                                             Mermaid source
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked
-  show <h_…|c_…|k_…|path:line[@n|@base]>   print a unit, a comment's thread, a concern, or the
-                                            lines around path:line in commit n, instead of
-                                            reading files
+  show <h_…|c_…|k_…|path:line[@n|@base]|name>
+                                            print a unit, a comment's thread, a concern, the
+                                            lines around path:line in commit n, or where a name
+                                            is defined, instead of reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
 
@@ -85,11 +87,13 @@ Interactive loop (while the review page is open):
                                             --lines are change lines of the unit, commits count
                                             from 1; with no target it is about the whole plan.
                                             watch leaves these out like your replies
-  show <h_…|c_…|k_…|path:line[@n|@base]> [--branch <name>]
+  show <h_…|c_…|k_…|path:line[@n|@base]|name> [--branch <name>]
                                             print a unit with the commits that take it, a
                                             comment with its rows and thread, a concern with its
-                                            lines, or the lines around path:line at the tip, in
-                                            commit n of the plan, or in the base
+                                            lines, the lines around path:line at the tip, in
+                                            commit n of the plan, or in the base, or each place
+                                            a name is defined at the tip with the commit it
+                                            lands in
   report [--json] [--markdown] [--branch <name>]
                                             print the report of the open review, or of the last
                                             one that ended. Markdown lists issues by file and
@@ -1516,7 +1520,7 @@ async function explain(cwd, args) {
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
-const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]>";
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]|name>";
 /** Every comment the session has, with the plan version it was made on: live ones first. */
 async function knownComments(session) {
     const open = await openOnServer(session, null);
@@ -1629,6 +1633,12 @@ async function showRef(cwd, args) {
         }
         throw new UsageError(`no concern ${ref} in a plan that fits the branch`);
     }
+    if (isIdentifier(ref)) {
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        const index = definitionIndex(session.root, session.diff.tip, units, commits);
+        process.stdout.write(renderShownDefinitions(ref, await index.lookup(ref, null)));
+        return 0;
+    }
     process.stdout.write(showLines(session, ref));
     return 0;
 }

package/dist/src/definition.js

@@ -0,0 +1,226 @@
+import { posix } from "node:path";
+import { splitLines, tipStartOf } from "./diff.js";
+import { blobsAt, grepTip } from "./git.js";
+export const MAX_CANDIDATES = 10;
+const PREVIEW_LINES = 8;
+/** An ASCII identifier as JS, Python, Go, Rust, JVM languages, Ruby and C spell one. */
+export function isIdentifier(s) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/.test(s);
+}
+const JS_MODS = "((static|async|public|private|protected|readonly|override|get|set)\\s+)*";
+const RUST_VIS = "(pub([(][^)]*[)])?\\s+)?";
+const JAVA_MODS = "((public|private|protected|static|final|abstract|synchronized|native|default|strictfp)\\s+)*";
+const JVM_CLASS_MODS = "((public|private|protected|static|final|abstract|sealed|data|open|internal|inner|enum|annotation)\\s+)*";
+const KOTLIN_MODS = "((public|private|protected|internal|override|open|abstract|suspend|inline|operator|infix|tailrec|external|actual|expect)\\s+)*";
+const STATEMENT = /^\s*(return|new|throw|else|case|yield|await|typedef|delete|goto)\b/;
+const LANGUAGES = [
+    {
+        extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"],
+        patterns: [
+            {
+                kind: "function",
+                source: "^\\s*(export\\s+)?(default\\s+)?(async\\s+)?function\\s*[*]?\\s*NAME\\s*[(<]",
+            },
+            {
+                kind: "const",
+                source: "^\\s*(export\\s+)?(declare\\s+)?(const|let|var)\\s+NAME\\s*(:[^=]*)?=",
+            },
+            {
+                kind: "class",
+                source: "^\\s*(export\\s+)?(default\\s+)?(declare\\s+)?(abstract\\s+)?class\\s+NAMEEND",
+            },
+            {
+                kind: "type",
+                source: "^\\s*(export\\s+)?(declare\\s+)?(interface|type|(const\\s+)?enum)\\s+NAMEEND",
+            },
+            {
+                kind: "method",
+                source: `^\\s+${JS_MODS}[*]?NAME\\s*(<[^>]*>)?[(].*[)]\\s*(:[^={;]+)?[{]\\s*$`,
+                reject: /^\s*(if|for|while|switch|catch|return)\b/,
+            },
+        ],
+    },
+    {
+        extensions: [".py", ".pyi"],
+        patterns: [
+            { kind: "function", source: "^(async\\s+)?def\\s+NAME\\s*[(]" },
+            { kind: "method", source: "^\\s+(async\\s+)?def\\s+NAME\\s*[(]" },
+            { kind: "class", source: "^\\s*class\\s+NAME\\s*[(:]" },
+        ],
+    },
+    {
+        extensions: [".go"],
+        patterns: [
+            { kind: "function", source: "^func\\s+NAME\\s*[[(]" },
+            { kind: "method", source: "^func\\s*[(][^)]*[)]\\s*NAME\\s*[[(]" },
+            { kind: "type", source: "^\\s*type\\s+NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".rs"],
+        patterns: [
+            {
+                kind: "function",
+                source: `^${RUST_VIS}((const|async|unsafe|extern)\\s+("[^"]*"\\s+)?)*fn\\s+NAME\\s*[<(]`,
+            },
+            {
+                kind: "method",
+                source: `^\\s+${RUST_VIS}((const|async|unsafe|extern)\\s+("[^"]*"\\s+)?)*fn\\s+NAME\\s*[<(]`,
+            },
+            { kind: "class", source: `^\\s*${RUST_VIS}struct\\s+NAMEEND` },
+            { kind: "type", source: `^\\s*${RUST_VIS}(enum|trait|type)\\s+NAMEEND` },
+            { kind: "other", source: "^\\s*impl(<[^>]*>)?\\s+([A-Za-z0-9_:<>, ]+\\s+for\\s+)?NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".java", ".kt", ".kts"],
+        patterns: [
+            { kind: "class", source: `^\\s*${JVM_CLASS_MODS}(class|object|record)\\s+NAMEEND` },
+            { kind: "type", source: `^\\s*${JVM_CLASS_MODS}(interface|enum|@interface)\\s+NAMEEND` },
+            {
+                kind: "function",
+                source: `^\\s*${KOTLIN_MODS}fun\\s+(<[^>]*>\\s*)?([A-Za-z0-9_.<>]+[.])?NAME\\s*[(]`,
+            },
+            {
+                kind: "method",
+                source: `^\\s*${JAVA_MODS}(<[^>]*>\\s+)?[A-Za-z_][A-Za-z0-9_<>,.?]*(\\[\\])*\\s+NAME\\s*[(][^;]*$`,
+                reject: STATEMENT,
+            },
+        ],
+    },
+    {
+        extensions: [".rb"],
+        patterns: [
+            { kind: "method", source: "^\\s*def\\s+(self[.])?NAMEEND" },
+            { kind: "class", source: "^\\s*class\\s+NAMEEND" },
+            { kind: "other", source: "^\\s*module\\s+NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".c", ".h", ".cc", ".cpp", ".cxx", ".hh", ".hpp", ".hxx"],
+        patterns: [
+            {
+                kind: "function",
+                source: "^[A-Za-z_][A-Za-z0-9_ *&<>,:~]*[ *&]([A-Za-z_][A-Za-z0-9_]*::)*NAME\\s*[(][^;]*$",
+                reject: STATEMENT,
+            },
+            { kind: "function", source: "^NAME\\s*[(][^;]*$" },
+            { kind: "class", source: "^\\s*(typedef\\s+)?(struct|class|union)\\s+NAME\\s*([{:]|$)" },
+            { kind: "type", source: "^\\s*(typedef\\s+)?enum\\s+(class\\s+)?NAME\\s*([{:]|$)" },
+        ],
+    },
+];
+const END = "([^A-Za-z0-9_$]|$)";
+function spell(source, name) {
+    return source
+        .replaceAll("NAMEEND", `${name.replaceAll("$", "[$]")}${END}`)
+        .replaceAll("NAME", name.replaceAll("$", "[$]"));
+}
+function toEre(source) {
+    return source.replaceAll("\\s", "[[:space:]]");
+}
+function languageOf(path) {
+    const ext = posix.extname(path).toLowerCase();
+    return LANGUAGES.find((l) => l.extensions.includes(ext)) ?? null;
+}
+/** What the match defines by the patterns of its file's language, or null when it is no definition. */
+function kindOf(match, name) {
+    const language = languageOf(match.path);
+    if (language === null)
+        return null;
+    const hit = language.patterns.find((p) => new RegExp(spell(p.source, name)).test(match.text) && !p.reject?.test(match.text));
+    return hit?.kind ?? null;
+}
+/** Same file as `from` first, then the same directory, then the rest, each in path and line order. */
+export function rank(found, from) {
+    const tier = (path) => {
+        if (from === null)
+            return 2;
+        if (path === from)
+            return 0;
+        return posix.dirname(path) === posix.dirname(from) ? 1 : 2;
+    };
+    return found
+        .map((f, i) => ({ f, i, t: tier(f.path) }))
+        .sort((a, b) => a.t - b.t || a.i - b.i)
+        .map(({ f }) => f);
+}
+const NOWHERE = { unit: null, row: null, commit: null };
+/**
+ * The hunk row that holds tip line `line` of `path`, and the commit that writes it: the owner of a
+ * change row, or the first commit taking the unit for a context row.
+ */
+export function place(units, commits, path, line) {
+    for (const unit of units.values()) {
+        if (unit.kind !== "hunk" || unit.path !== path)
+            continue;
+        const row = rowAt(unit, tipStartOf(unit, units), line);
+        if (row === null)
+            continue;
+        const body = unit.body[row];
+        const change = body !== undefined && body.op !== " " ? body.change : null;
+        const takes = (c) => c.refs.some((r) => r.unit === unit.id &&
+            (change === null || r.select.kind === "rest" || r.select.changes.includes(change)));
+        const k = commits.findIndex(takes);
+        return { unit: unit.id, row, commit: k === -1 ? null : k };
+    }
+    return NOWHERE;
+}
+function rowAt(hunk, tipStart, line) {
+    let tipLine = tipStart;
+    for (const [row, body] of hunk.body.entries()) {
+        if (body.op === "-")
+            continue;
+        if (tipLine === line)
+            return row;
+        tipLine += 1;
+    }
+    return null;
+}
+function stripEol(line) {
+    return line.replace(/\r?\n$/, "");
+}
+/**
+ * Where names are defined at one branch tip and where each lands in the plan. Built per hosted
+ * version, so a swap starts a fresh one; matches are cached per name and file lines per path.
+ */
+export function definitionIndex(repo, tip, units, commits) {
+    const foundByName = new Map();
+    const linesByPath = new Map();
+    const find = (name) => {
+        const cached = foundByName.get(name);
+        if (cached !== undefined)
+            return cached;
+        const patterns = [
+            ...new Set(LANGUAGES.flatMap((l) => l.patterns.map((p) => toEre(spell(p.source, name))))),
+        ];
+        const pathspecs = LANGUAGES.flatMap((l) => l.extensions.map((e) => `*${e}`));
+        const found = grepTip(repo, tip, patterns, pathspecs).then((matches) => matches.flatMap((m) => {
+            const kind = kindOf(m, name);
+            return kind === null ? [] : [{ path: m.path, newLine: m.line, kind }];
+        }));
+        foundByName.set(name, found);
+        // A failed grep is not an answer; the next request tries again.
+        found.catch(() => foundByName.delete(name));
+        return found;
+    };
+    const load = async (paths) => {
+        const missing = [...new Set(paths)].filter((p) => !linesByPath.has(p));
+        if (missing.length === 0)
+            return;
+        for (const [path, bytes] of await blobsAt(repo, tip, missing)) {
+            linesByPath.set(path, splitLines(bytes).map(stripEol));
+        }
+    };
+    return {
+        lookup: async (name, from) => {
+            const ranked = rank(await find(name), from).slice(0, MAX_CANDIDATES);
+            await load(ranked.map((f) => f.path));
+            return ranked.map((f) => ({
+                ...f,
+                ...place(units, commits, f.path, f.newLine),
+                preview: (linesByPath.get(f.path) ?? []).slice(f.newLine - 1, f.newLine - 1 + PREVIEW_LINES),
+            }));
+        },
+    };
+}

package/dist/src/git.js

@@ -1,13 +1,16 @@
 import { execFile } from "node:child_process";
 import { link, mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { isSha, neededBlobs, parseDiff } from "./diff.js";
+import { isRepoPath, isSha, neededBlobs, parseDiff } from "./diff.js";
 export class GitError extends Error {
     name = "GitError";
     args;
-    constructor(args, stderr) {
+    /** git's exit status, or null when it did not run or was killed. */
+    status;
+    constructor(args, stderr, status = null) {
         super(`git ${args.join(" ")}: ${stderr}`);
         this.args = args;
+        this.status = status;
     }
 }
 function git(repo, args, opts = {}) {
@@ -18,8 +21,10 @@ function git(repo, args, opts = {}) {
             maxBuffer: 1 << 30,
             env: { ...process.env, ...opts.env },
         }, (error, stdout, stderr) => {
-            if (error)
-                reject(new GitError(args, stderr.toString("utf8").trim() || error.message));
+            if (error) {
+                const status = typeof error.code === "number" ? error.code : null;
+                reject(new GitError(args, stderr.toString("utf8").trim() || error.message, status));
+            }
             else
                 resolve(stdout);
         });
@@ -97,25 +102,76 @@ export async function defaultBaseRef(repo) {
     }
     throw new Error("neither main nor master exists; pass --base <ref>");
 }
-async function catBlobs(repo, shas) {
-    const blobs = new Map();
-    if (shas.length === 0)
-        return blobs;
-    const out = await git(repo, ["cat-file", "--batch"], { input: `${shas.join("\n")}\n` });
+/** The blob named by each object spec, in order, as latin1; throws when one is not a blob. */
+async function catBatch(repo, specs) {
+    if (specs.length === 0)
+        return [];
+    const input = Buffer.from(`${specs.join("\n")}\n`, "latin1");
+    const out = await git(repo, ["cat-file", "--batch"], { input });
+    const blobs = [];
     let at = 0;
-    for (const sha of shas) {
+    for (const spec of specs) {
         const nl = out.indexOf(0x0a, at);
         const header = out.subarray(at, nl).toString("latin1");
         const m = /^([0-9a-f]+) blob (\d+)$/.exec(header);
-        if (nl === -1 || m === null || m[1] !== sha) {
-            throw new Error(`cat-file returned "${header}" for ${sha}`);
+        if (nl === -1 || m === null || (isSha(spec) && m[1] !== spec)) {
+            throw new Error(`cat-file returned "${header}" for ${spec}`);
         }
         const size = Number(m[2]);
-        blobs.set(sha, out.subarray(nl + 1, nl + 1 + size).toString("latin1"));
+        blobs.push(out.subarray(nl + 1, nl + 1 + size).toString("latin1"));
         at = nl + 1 + size + 1;
     }
     return blobs;
 }
+async function catBlobs(repo, shas) {
+    const blobs = await catBatch(repo, shas);
+    return new Map(shas.map((sha, i) => [sha, blobs[i] ?? ""]));
+}
+/** Each path's bytes at the commit, as latin1. */
+export async function blobsAt(repo, commit, paths) {
+    const blobs = await catBatch(repo, paths.map((p) => `${commit}:${p}`));
+    return new Map(paths.map((p, i) => [p, blobs[i] ?? ""]));
+}
+/**
+ * Lines of the commit's tree, not the working tree, that match any of the POSIX extended
+ * patterns, in files matching the pathspecs. Binary files are skipped.
+ */
+export async function grepTip(repo, commit, patterns, pathspecs) {
+    const args = [
+        "grep",
+        "-n",
+        "-E",
+        "-I",
+        "-z",
+        "--no-color",
+        "--no-column",
+        ...patterns.flatMap((p) => ["-e", p]),
+        commit,
+        "--",
+        ...pathspecs,
+    ];
+    let out;
+    try {
+        out = await git(repo, args);
+    }
+    catch (error) {
+        // grep exits 1 when nothing matched.
+        if (error instanceof GitError && error.status === 1)
+            return [];
+        throw error;
+    }
+    const prefix = `${commit}:`;
+    return out
+        .toString("latin1")
+        .split("\n")
+        .flatMap((record) => {
+        const [name = "", line = "", ...text] = record.split("\0");
+        const path = name.slice(prefix.length);
+        if (!name.startsWith(prefix) || !isRepoPath(path) || !/^\d+$/.test(line))
+            return [];
+        return [{ path, line: Number(line), text: text.join("\0") }];
+    });
+}
 const DIFF_FLAGS = ["--no-renames", "--full-index", "--no-color", "--no-ext-diff", "--no-textconv"];
 export async function loadDiff(repo, baseRef, tipRef) {
     const [tip, baseCommit] = await Promise.all([

package/dist/src/plan.js

@@ -17,6 +17,10 @@ const STATUSES = ["addressed", "declined", "deferred", "answered"];
 function isResponseStatus(s) {
     return STATUSES.some((x) => x === s);
 }
+const SECTIONS = ["story", "steps", "details", "wiring"];
+function isCommitSection(s) {
+    return SECTIONS.some((x) => x === s);
+}
 const SEVERITIES = ["blocker", "major", "minor"];
 const CONCERN_KINDS = ["bug", "missing-test", "naming", "risk"];
 export function isSeverity(s) {
@@ -223,6 +227,10 @@ export function parsePlanFile(draft) {
             }
             if (typeof c.message !== "string")
                 bad(`${at}.message`, "expected a string");
+            const section = c.section ?? null;
+            if (section !== null && !isCommitSection(section)) {
+                bad(`${at}.section`, `expected one of ${SECTIONS.join(", ")}`);
+            }
             const extras = parseExtras(c, false);
             if ("error" in extras)
                 bad(`${at}.${extras.field}`, extras.error);
@@ -239,7 +247,8 @@ export function parsePlanFile(draft) {
                 }
             }
             if (typeof c.message === "string" && !("error" in extras)) {
-                commits.push({ message: c.message, ...extras, units });
+                const placed = isCommitSection(section) ? { section } : {};
+                commits.push({ message: c.message, ...placed, ...extras, units });
             }
         }
     }
@@ -287,6 +296,7 @@ export function serializePlanFile(file) {
         tip: file.tip,
         commits: file.commits.map((c) => ({
             message: c.message,
+            ...(c.section === undefined ? {} : { section: c.section }),
             ...serializeExtras(c),
             units: c.units.map((ref) => ref.narration === undefined && ref.diagram === undefined && ref.concerns === undefined
                 ? formatUnitRef(ref)
@@ -578,6 +588,7 @@ function project(diff, file, claims, issues) {
         return {
             index: k,
             message: commit.message,
+            ...(commit.section === undefined ? {} : { section: commit.section }),
             ...withText(commit.narration ?? null, commit.diagram ?? null),
             ...(mine.length === 0 ? {} : { concerns: mine }),
             refs,

package/dist/src/prompt.js

@@ -1065,3 +1065,25 @@ export function renderShownConcern(concern, commit, ctx) {
         "",
     ].join("\n");
 }
+function utf8(latin1) {
+    return Buffer.from(latin1, "latin1").toString("utf8");
+}
+/** Where a name is defined, each with the commit it lands in and its first lines at the tip. */
+export function renderShownDefinitions(name, candidates) {
+    if (candidates.length === 0)
+        return `no definition of ${name} at the tip\n`;
+    return `${candidates
+        .flatMap((c) => {
+        const where = c.commit !== null
+            ? `in commit ${c.commit + 1}`
+            : c.unit !== null
+                ? `in ${c.unit}, which no commit of the plan takes`
+                : "unchanged by the branch";
+        const width = String(c.newLine + c.preview.length - 1).length;
+        return [
+            `${utf8(c.path)}:${c.newLine} ${c.kind}, ${where}`,
+            ...c.preview.map((l, i) => `    ${String(c.newLine + i).padStart(width)}  ${utf8(l)}`),
+        ];
+    })
+        .join("\n")}\n`;
+}

package/dist/src/server.js

@@ -5,6 +5,8 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isReplyId, parseComment, parseDraft, parseNewDecision, parseNewReply, } from "./comments.js";
+import { definitionIndex, isIdentifier } from "./definition.js";
+import { isRepoPath } from "./diff.js";
 import { carryConcerns, carrySession } from "./evolve.js";
 import { isConcernId, isPlanVersion } from "./plan.js";
 import { renderReport, reportItems } from "./prompt.js";
@@ -255,6 +257,7 @@ function viewOf(registration, loaded, draft, earlier = loaded.earlier) {
         unitIds: new Set(state.units.map((u) => u.id)),
         hunkRows: new Map(state.units.flatMap((u) => u.kind === "hunk" ? [[u.id, u.body.length]] : [])),
         concernIds: new Set(state.commits.flatMap((c) => (c.concerns ?? []).map((k) => k.id))),
+        definitions: definitionIndex(loaded.repo, state.anchor.tip, new Map(state.units.map((u) => [u.id, u])), state.commits),
         draftFile: draftPath(reviewsDir, state.version),
         reviewFile: join(reviewsDir, `v${state.version}.json`),
     };
@@ -544,6 +547,11 @@ function hostSession(id, registration, loaded, draft, load) {
             return waitForEvents(since, timeoutMs, signal);
         },
         report: () => report(review()),
+        /** The page reads a definition the plan shows from its hunk, so only others carry a preview. */
+        define: async (name, from) => {
+            const found = await view.definitions.lookup(name, from !== null && isRepoPath(from) ? from : null);
+            return found.map((c) => (c.unit === null ? c : { ...c, preview: [] }));
+        },
         reportItems: () => reportItems(review(), view.loaded.state.commits, unitsOf(), reportOptions()),
         add: async (raw) => {
             open();
@@ -943,6 +951,13 @@ export function startServer(opts) {
             const timeout = queryInt(url, "timeout", 0, MAX_POLL_MS, DEFAULT_POLL_MS);
             return sendJson(res, 200, await session.poll(since, timeout, abort.signal));
         }
+        if (method === "GET" && rest === "/api/definition") {
+            const name = url.searchParams.get("name") ?? "";
+            if (!isIdentifier(name))
+                throw new HttpError(400, "name must be an identifier");
+            const candidates = await session.define(name, url.searchParams.get("from"));
+            return sendJson(res, 200, { candidates });
+        }
         if (method === "GET" && rest === "/api/report" && url.searchParams.get("format") === "json") {
             return sendJson(res, 200, session.reportItems());
         }

package/dist/src/types.js

@@ -10,6 +10,8 @@
  *   session.ts  the .follow-me/<slug>/ layout: session anchor, plans, reviews, draft.
  *   comments.ts the wire formats of review state: comments, replies, concern decisions, the
  *               review file, the autosaved draft and the server's events. Pure parsers.
+ *   definition.ts where an identifier is defined at the branch tip, and where that lands in the
+ *               plan: per-language patterns, ranking, placement and a per-tip cache.
  *   prompt.ts   the planner prompt for an agent, the feedback and the consolidated report.
  *   server.ts   the review server: a registry of hosted sessions, their JSON API, and ui/.
  *   host.ts     the one server per user: its record in the state dir, attach, start, stop.

package/dist/ui/dist/assets/{abnfDiagram-WEYOIA3C-8UsLPznO.js → abnfDiagram-WEYOIA3C-fYSYLdMl.js}

@@ -1 +1 @@
-import{m as e,t}from"./mermaid-parser.core-DxvaorTa.js";import{n}from"./chunk-Y2CYZVJY-DsF7k-Jl.js";import{m as r}from"./src-BZ3kG7lO.js";import"./chunk-DSNLSHJZ-YiMuxsb-.js";import{n as i,r as a,t as o}from"./chunk-2E7WHVMD-BiHSeJMu.js";import{t as s}from"./chunk-JWPE2WC7-DVXcaiue.js";import"./mermaid.core-ujYTsRZz.js";var c=e().RailroadAbnf.parser.LangiumParser,l=n(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=n(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=n(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=n(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=n(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=n(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=n(e=>{s(e,o),e.title&&o.setTitle(e.title),e.rules.map(e=>o.addRule(m(e)))},`populateDb`),g={parser:{parse:n(e=>{o.clear(),r.debug(`[ABNF Parser] Starting Langium parse`);let n=c.parse(e);if(n.lexerErrors.length>0||n.parserErrors.length>0)throw new t(n);let i=n.value;r.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),r.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:o}},db:o,renderer:a,styles:i};export{g as diagram};
+import{m as e,t}from"./mermaid-parser.core-DGpOP8AM.js";import{n}from"./chunk-Y2CYZVJY-DsF7k-Jl.js";import{m as r}from"./src-XnrqevnL.js";import"./chunk-DSNLSHJZ-B2z7FX4h.js";import{n as i,r as a,t as o}from"./chunk-2E7WHVMD-CNMuK9zj.js";import{t as s}from"./chunk-JWPE2WC7-DVXcaiue.js";import"./mermaid.core-BJtBFbJx.js";var c=e().RailroadAbnf.parser.LangiumParser,l=n(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=n(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=n(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=n(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=n(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=n(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=n(e=>{s(e,o),e.title&&o.setTitle(e.title),e.rules.map(e=>o.addRule(m(e)))},`populateDb`),g={parser:{parse:n(e=>{o.clear(),r.debug(`[ABNF Parser] Starting Langium parse`);let n=c.parse(e);if(n.lexerErrors.length>0||n.parserErrors.length>0)throw new t(n);let i=n.value;r.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),r.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:o}},db:o,renderer:a,styles:i};export{g as diagram};

package/dist/ui/dist/assets/{arc-vovjGalz.js → arc-DGuGSnwa.js}

@@ -1 +1 @@
-import{n as e,t}from"./path-fybaL0A-.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-D3j-DODP.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i){if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};
+import{n as e,t}from"./path-fybaL0A-.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-BJd4jp9Y.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i){if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};

package/dist/ui/dist/assets/{architecture-WOLXFQ4H-BBMK-PUu.js → architecture-WOLXFQ4H-VFox_hV1.js}

@@ -1 +1 @@
-import"./chunk-NGNAAXSQ-C2Wy9Xmz.js";export{M as createArchitectureServices}from"./mermaid-parser.core-DxvaorTa.js";
+import"./chunk-NGNAAXSQ-C2Wy9Xmz.js";export{M as createArchitectureServices}from"./mermaid-parser.core-DGpOP8AM.js";