@shiyuphan/follow-me 0.7.1 → 0.9.0

package/dist/src/plan.js

@@ -10,6 +10,12 @@ export function isCommentId(s) {
 export function isConcernId(s) {
     return typeof s === "string" && /^k_[0-9a-f]{8}$/.test(s);
 }
+export function isOfferId(s) {
+    return typeof s === "string" && /^o_[0-9a-f]{8}$/.test(s);
+}
+/** At most this many offers in one commit and in the whole plan; most plans need none. */
+export const OFFERS_PER_COMMIT = 1;
+export const OFFERS_PER_PLAN = 3;
 export function isPlanVersion(n) {
     return typeof n === "number" && Number.isInteger(n) && n >= 1;
 }
@@ -29,6 +35,10 @@ export function isSeverity(s) {
 function isConcernKind(s) {
     return CONCERN_KINDS.some((x) => x === s);
 }
+const OFFER_KINDS = ["state-machine", "sequence", "diagram"];
+function isOfferKind(s) {
+    return OFFER_KINDS.some((x) => x === s);
+}
 /** Narrows to an object whose named fields are still unknown, which holds for any object. */
 export function isFields(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -123,7 +133,47 @@ function parseConcerns(v, onUnit) {
     }
     return out;
 }
-/** The optional narration, diagram and concerns of a commit or unit entry, or what is wrong. */
+/** An offer is { kind, label }; the label names the thing to draw. */
+function parseOffer(v) {
+    if (!isFields(v))
+        return "expected an object";
+    if (!isOfferKind(v.kind))
+        return `kind: expected one of ${OFFER_KINDS.join(", ")}`;
+    if (typeof v.label !== "string" || v.label.trim() === "") {
+        return 'label: expected what to draw, like "Draw UploadButton as a state machine"';
+    }
+    return { kind: v.kind, label: v.label };
+}
+/** A stored offer as validation placed it: with its id and its unit. */
+export function parsePlacedOffer(v) {
+    if (!isFields(v))
+        return "expected an object";
+    if (!isOfferId(v.id))
+        return "id: expected an offer id";
+    if (v.unit !== undefined && !(typeof v.unit === "string" && isUnitId(v.unit))) {
+        return "unit: expected a unit id";
+    }
+    const offer = parseOffer(v);
+    if (typeof offer === "string")
+        return offer;
+    return { ...offer, id: v.id, ...(v.unit === undefined ? {} : { unit: v.unit }) };
+}
+/** Absent, null and [] all mean no offers. */
+function parseOffers(v) {
+    if (v === undefined || v === null)
+        return [];
+    if (!isArray(v))
+        return "expected an array";
+    const out = [];
+    for (const [i, raw] of v.entries()) {
+        const offer = parseOffer(raw);
+        if (typeof offer === "string")
+            return `[${i}]: ${offer}`;
+        out.push(offer);
+    }
+    return out;
+}
+/** The optional narration, diagram, concerns and offers of a commit or unit entry, or what is wrong. */
 function parseExtras(v, onUnit) {
     const narration = parseText(v.narration);
     if (narration === INVALID)
@@ -137,7 +187,13 @@ function parseExtras(v, onUnit) {
     const concerns = parseConcerns(v.concerns, onUnit);
     if (typeof concerns === "string")
         return { field: "concerns", error: concerns };
-    return withExtras(narration, diagram, concerns);
+    const offers = parseOffers(v.offers);
+    if (typeof offers === "string")
+        return { field: "offers", error: offers };
+    return {
+        ...withExtras(narration, diagram, concerns),
+        ...(offers.length === 0 ? {} : { offers }),
+    };
 }
 function withText(narration, diagram) {
     return {
@@ -160,15 +216,21 @@ function serializeExtras(x) {
     return {
         ...withText(x.narration ?? null, x.diagram ?? null),
         ...(x.concerns === undefined ? {} : { concerns: x.concerns.map(serializeConcern) }),
+        ...(x.offers === undefined
+            ? {}
+            : { offers: x.offers.map((o) => ({ kind: o.kind, label: o.label })) }),
     };
 }
-/** A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration", "diagram", "concerns" }. */
+/**
+ * A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration", "diagram", "concerns", "offers" }.
+ */
 function parseUnitEntry(u) {
     if (typeof u === "string")
         return parseUnitRef(u);
-    if (!isFields(u) || typeof u.unit !== "string") {
+    if (!isFields(u) ||
+        typeof u.unit !== "string") {
         return {
-            error: 'expected a unit ref string or { "unit", "narration", "diagram", "concerns" }',
+            error: 'expected a unit ref string or { "unit", "narration", "diagram", "concerns", "offers" }',
         };
     }
     const ref = parseUnitRef(u.unit);
@@ -298,7 +360,10 @@ export function serializePlanFile(file) {
             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
+            units: c.units.map((ref) => ref.narration === undefined &&
+                ref.diagram === undefined &&
+                ref.concerns === undefined &&
+                ref.offers === undefined
                 ? formatUnitRef(ref)
                 : { unit: formatUnitRef(ref), ...serializeExtras(ref) }),
         })),
@@ -547,8 +612,51 @@ function placeConcerns(diff, file, claims, issues) {
     }
     return placedPerCommit;
 }
+/** "o_" + 8 hex over the unit and the label: stable while the offer stays at its place. */
+function deriveOfferId(unit, o) {
+    const hex = createHash("sha256")
+        .update(`offer\0${unit ?? ""}\0${o.label}`)
+        .digest("hex")
+        .slice(0, 8);
+    const id = `o_${hex}`;
+    if (!isOfferId(id))
+        throw new Error(`sha256 produced ${id}`);
+    return id;
+}
+/** Gives every offer its id: the commit's own first, then those of its unit refs in order. */
+function placeOffers(file, issues) {
+    const ids = new Set();
+    return file.commits.map((commit, k) => {
+        const placed = [];
+        const add = (o, unit) => {
+            const id = deriveOfferId(unit, o);
+            if (ids.has(id)) {
+                issues.push({ kind: "bad-offer", commit: k, reason: `${id} repeats another offer` });
+                return;
+            }
+            ids.add(id);
+            placed.push({ ...o, id, ...(unit === null ? {} : { unit }) });
+        };
+        for (const o of commit.offers ?? [])
+            add(o, null);
+        for (const ref of commit.units)
+            for (const o of ref.offers ?? [])
+                add(o, ref.unit);
+        return placed;
+    });
+}
+/** At most OFFERS_PER_COMMIT in a commit, its units' included, and OFFERS_PER_PLAN in all. */
+function offerLimits(file) {
+    const counts = file.commits.map((c) => (c.offers ?? []).length + c.units.reduce((n, r) => n + (r.offers ?? []).length, 0));
+    const issues = counts.flatMap((count, commit) => count > OFFERS_PER_COMMIT ? [{ kind: "too-many-offers", commit, count }] : []);
+    const total = counts.reduce((a, b) => a + b, 0);
+    if (total > OFFERS_PER_PLAN)
+        issues.push({ kind: "too-many-offers", commit: null, count: total });
+    return issues;
+}
 function project(diff, file, claims, issues) {
     const concerns = placeConcerns(diff, file, claims, issues);
+    const offers = placeOffers(file, issues);
     const { stateAt, tipOf } = projector(diff, claims.owners);
     const present = new Map();
     for (const f of diff.textFiles.values())
@@ -560,6 +668,7 @@ function project(diff, file, claims, issues) {
     const commits = file.commits.map((commit, k) => {
         const refs = claims.resolved[k] ?? [];
         const mine = concerns[k] ?? [];
+        const offered = offers[k] ?? [];
         const touched = [...new Set(refs.flatMap((r) => diff.units.get(r.unit)?.path ?? []))].sort();
         const changes = touched.map((path) => {
             const state = stateAt(path, k);
@@ -591,6 +700,7 @@ function project(diff, file, claims, issues) {
             ...(commit.section === undefined ? {} : { section: commit.section }),
             ...withText(commit.narration ?? null, commit.diagram ?? null),
             ...(mine.length === 0 ? {} : { concerns: mine }),
+            ...(offered.length === 0 ? {} : { offers: offered }),
             refs,
             changes,
         };
@@ -655,6 +765,7 @@ export function validatePlan(diff, draft, opts = {}) {
         if (c.units.length === 0)
             issues.push({ kind: "empty-commit", commit: k });
     });
+    issues.push(...offerLimits(file));
     const assignment = [];
     const claims = claim(diff, file, assignment);
     issues.push(...assignment);
@@ -677,6 +788,17 @@ export function validatePlan(diff, draft, opts = {}) {
         if (length > LONG_TITLE)
             warnings.push({ kind: "long-title", commit, length });
     });
+    // Sections read top-down: story, steps, details, wiring. A later section never comes back.
+    let reached = null;
+    file.commits.forEach((c, commit) => {
+        if (c.section === undefined)
+            return;
+        if (reached !== null && SECTIONS.indexOf(c.section) < SECTIONS.indexOf(reached)) {
+            warnings.push({ kind: "section-order", commit, section: c.section, after: reached });
+        }
+        else
+            reached = c.section;
+    });
     const asked = new Map(review?.comments.map((c) => [c.id, c.kind === "question"]));
     for (const r of file.responses) {
         const isQuestion = asked.get(r.comment);

package/dist/src/prompt.js

@@ -1018,6 +1018,28 @@ function indented(body) {
 function said(head, body) {
     return body.includes("\n") ? [`${head}:`, indented(body)] : [`${head}: ${body}`];
 }
+/**
+ * The one line that tells the agent a reviewer accepted an offer: where it sits, as the tip lines
+ * of its hunk or its commit, its label, and the command that answers it.
+ */
+export function acceptedOfferLine(c, offer, ctx) {
+    const found = (ctx?.commits ?? []).flatMap((commit, k) => (commit.offers ?? []).flatMap((o) => (o.id === offer ? [{ o, k }] : [])))[0];
+    let place = describeAnchor(c.anchor, ctx);
+    if (found !== undefined && found.o.unit === undefined)
+        place = `commit ${found.k + 1}`;
+    else if (found?.o.unit !== undefined) {
+        const unit = ctx?.units.get(found.o.unit);
+        let where = unit?.path ?? found.o.unit;
+        if (unit?.kind === "hunk" && ctx !== null) {
+            const from = tipStartOf(unit, ctx.units);
+            const kept = unit.body.filter((row) => row.op !== "-").length;
+            where = `${unit.path}:${from}-${from + Math.max(kept, 1) - 1}`;
+        }
+        place = `${where} (commit ${found.k + 1})`;
+    }
+    const label = (found?.o.label ?? c.body).trim().replace(/\.+$/, "");
+    return `Reviewer accepted offer ${offer} on ${place}: ${label}. Reply with follow-me reply ${c.id} --diagram <file> [--map <file>].`;
+}
 /**
  * A new comment carries its short quote, since the agent has not seen it; everything else is one
  * line naming its id, because the agent already has the comment it refers to.
@@ -1026,6 +1048,8 @@ function renderEvent(event, ctx) {
     switch (event.type) {
         case "comment": {
             const { comment: c } = event;
+            if (c.offer !== undefined)
+                return [acceptedOfferLine(c, c.offer, ctx)];
             const what = c.kind === "question" ? "question" : (c.severity ?? "comment");
             const lines = [`- ${c.id} ${what} on ${describeAnchor(c.anchor, ctx)}`];
             if (c.follows)
@@ -1047,6 +1071,8 @@ function renderEvent(event, ctx) {
         }
         case "resolved":
             return [`- ${event.commentId} ${event.resolved ? "resolved" : "reopened"}`];
+        case "offer-dismissed":
+            return [`- the reviewer dismissed offer ${event.offer}`];
         case "version":
             return [`- plan v${event.version} is open`];
         case "coverage":
@@ -1084,11 +1110,38 @@ export function renderShownComment(c, ctx, version) {
     lines.push(...quoted.map((r) => `    ${r}`));
     lines.push(...said(c.author === "agent" ? "agent" : "reviewer", c.body));
     for (const reply of c.replies ?? []) {
-        const diagram = reply.diagram === undefined ? "" : " (with a diagram)";
-        lines.push(...said(`${reply.author} replied${diagram}`, reply.body));
+        const extras = [
+            reply.diagram === undefined ? null : "a diagram",
+            reply.map === undefined ? null : "a state map",
+        ];
+        const parts = extras.filter((x) => x !== null);
+        const head = `${reply.author} replied${parts.length === 0 ? "" : ` (with ${parts.join(" and ")})`}`;
+        lines.push(...(reply.body.trim() === "" ? [head] : said(head, reply.body)));
+        if (reply.map !== undefined)
+            lines.push(...renderMap(reply.map).map((l) => `  ${l}`));
     }
     return `${lines.join("\n")}\n`;
 }
+/** "src/a.ts:12-20" or "src/a.ts:12", a following place in the same file as ":30-41". */
+function formatLocs(locs) {
+    return locs
+        .map((loc, i) => {
+        const lines = loc.start === loc.end ? `${loc.start}` : `${loc.start}-${loc.end}`;
+        return i > 0 && locs[i - 1]?.path === loc.path ? `:${lines}` : `${utf8(loc.path)}:${lines}`;
+    })
+        .join(", ");
+}
+/** A state map, one line per state and per transition. */
+function renderMap(map) {
+    return [
+        ...Object.entries(map.states).map(([name, locs]) => `state ${name}: ${formatLocs(locs)}`),
+        ...(map.transitions ?? []).map((t) => {
+            const event = t.event === undefined ? "" : ` on ${t.event}`;
+            const at = t.at.length === 0 ? "" : `: ${formatLocs(t.at)}`;
+            return `${t.from} -> ${t.to}${event}${at}`;
+        }),
+    ];
+}
 /** A concern of the plan with the lines it is pinned to, as its commit writes them. */
 export function renderShownConcern(concern, commit, ctx) {
     const where = whereConcern(ctx, { concern, commit, severity: concern.severity, note: null });

package/dist/src/refs.js

@@ -0,0 +1,239 @@
+/** Lines quoted per ref, as comments quote their rows. */
+export const QUOTE_LINES = 8;
+const GRAMMAR = /^(.+):(\d+)(?:-(\d+))?(?:@(\d+|base))?$/;
+/** `path:12`, `path:12-18`, `path:12@3`, `path:12-18@base`, or null when it is none of those. */
+export function parseRefText(text) {
+    const m = GRAMMAR.exec(text);
+    const [, path, startRaw, endRaw, atRaw] = m ?? [];
+    if (path === undefined || startRaw === undefined)
+        return null;
+    const start = Number(startRaw);
+    const end = endRaw === undefined ? start : Number(endRaw);
+    const at = atRaw === undefined ? null : atRaw === "base" ? "base" : Number(atRaw);
+    return { text, path, start, end, at };
+}
+/** One key per place, so `a.ts:5` and `a.ts:5-5` share a number. */
+export function refKey(spec) {
+    return `${spec.path}:${spec.start}-${spec.end}@${spec.at ?? "tip"}`;
+}
+/**
+ * A code span names a file when its path has a letter and a slash or a dot, so `10:30`,
+ * `localhost:3000` and `127.0.0.1:80` stay code.
+ */
+function looksLikeFile(path) {
+    return /[A-Za-z]/.test(path) && /[/.]/.test(path) && !/\s/.test(path);
+}
+/**
+ * The text of every inline code span outside fenced blocks, in order, read as CommonMark does: a
+ * run of backticks closes only on a run of the same length, and one space padding both ends is
+ * dropped.
+ */
+export function codeSpans(markdown) {
+    const spans = [];
+    let fence = null;
+    const prose = [];
+    for (const line of markdown.split("\n")) {
+        const opener = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (fence === null && opener !== undefined) {
+            fence = opener;
+            prose.push("");
+            continue;
+        }
+        if (fence !== null) {
+            const closer = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+            if (closer !== undefined && closer[0] === fence[0] && closer.length >= fence.length)
+                fence = null;
+            prose.push("");
+            continue;
+        }
+        prose.push(line);
+    }
+    // Spans never cross a blank line, which ends the paragraph.
+    for (const paragraph of prose.join("\n").split(/\n\s*\n/)) {
+        let i = 0;
+        while (i < paragraph.length) {
+            const c = paragraph[i];
+            if (c === "\\") {
+                i += 2;
+                continue;
+            }
+            if (c !== "`") {
+                i += 1;
+                continue;
+            }
+            let run = 0;
+            while (paragraph[i + run] === "`")
+                run += 1;
+            const open = i + run;
+            let close = -1;
+            for (let j = open; j < paragraph.length;) {
+                if (paragraph[j] !== "`") {
+                    j += 1;
+                    continue;
+                }
+                let k = 0;
+                while (paragraph[j + k] === "`")
+                    k += 1;
+                if (k === run) {
+                    close = j;
+                    break;
+                }
+                j += k;
+            }
+            if (close === -1) {
+                i = open;
+                continue;
+            }
+            let text = paragraph.slice(open, close).replace(/\n/g, " ");
+            if (text.length > 2 && text.startsWith(" ") && text.endsWith(" ") && text.trim() !== "") {
+                text = text.slice(1, -1);
+            }
+            spans.push(text);
+            i = close + run;
+        }
+    }
+    return spans;
+}
+/** The refs a reply's markdown writes, each place once, in order of first appearance. */
+export function refsIn(markdown) {
+    const seen = new Set();
+    const specs = [];
+    for (const span of codeSpans(markdown)) {
+        const spec = parseRefText(span);
+        if (spec === null || !looksLikeFile(spec.path))
+            continue;
+        const key = refKey(spec);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        specs.push(spec);
+    }
+    return specs;
+}
+/**
+ * Every line of a changed text file as it reads with the given change lines applied: none for
+ * the base, all for the tip, the plan's first n commits for commit n. Null when the file does
+ * not exist then.
+ */
+export function linesWith(file, applied) {
+    const changes = file.hunks.flatMap((h) => h.body.flatMap((l) => (l.op === " " ? [] : [applied(h, l)])));
+    const any = changes.some((c) => c);
+    const all = changes.every((c) => c);
+    if (file.base === null ? !any : file.tip === null && all)
+        return null;
+    const base = file.base?.lines ?? [];
+    const out = [];
+    let b = 0;
+    let t = 0;
+    const keep = (text) => {
+        b += 1;
+        t += 1;
+        out.push({ text, tip: t, base: b });
+    };
+    for (const hunk of file.hunks) {
+        while (b < hunk.oldStart)
+            keep(base[b] ?? "");
+        for (const line of hunk.body) {
+            if (line.op === " ")
+                keep(line.text);
+            else if (line.op === "-") {
+                b += 1;
+                if (!applied(hunk, line))
+                    out.push({ text: line.text, tip: null, base: b });
+            }
+            else {
+                t += 1;
+                if (applied(hunk, line))
+                    out.push({ text: line.text, tip: t, base: null });
+            }
+        }
+    }
+    while (b < base.length)
+        keep(base[b] ?? "");
+    return out;
+}
+/** Whether the plan's first n commits take this change line. */
+export function takenBy(commits) {
+    return (hunk, line) => commits.some((c) => c.refs.some((r) => r.unit === hunk.id &&
+        (r.select.kind === "rest" || r.select.changes.includes(line.change))));
+}
+/** The repo path a typed path names: its UTF-8 as the latin1 bytes git prints. */
+export function repoPathOfTyped(typed) {
+    return Buffer.from(typed, "utf8").toString("latin1");
+}
+function utf8(latin1) {
+    return Buffer.from(latin1, "latin1").toString("utf8");
+}
+function spanOf(ns) {
+    if (ns.length === 0)
+        return null;
+    return { start: Math.min(...ns), end: Math.max(...ns) };
+}
+function versionLabel(at) {
+    return at === null ? "at the tip" : at === "base" ? "in the base" : `in commit ${at}`;
+}
+/** A written ref resolved to its lines and quote, numbered n, or the reason it does not resolve. */
+export function resolveRef(spec, n, source) {
+    const { text, start, end, at } = spec;
+    if (start < 1)
+        return `${text}: lines count from 1`;
+    if (end < start)
+        return `${text} ends before it starts`;
+    if (typeof at === "number" && (at < 1 || at > source.commits.length)) {
+        const count = source.commits.length;
+        return `${text}: plan v${source.version} has ${count} commit${count === 1 ? "" : "s"}`;
+    }
+    const path = repoPathOfTyped(spec.path);
+    const where = versionLabel(at);
+    let lines;
+    let repoPath;
+    const file = [...source.textFiles.values()].find((f) => f.path === path);
+    const plain = [...source.unchanged].find(([p]) => p === path);
+    if (file !== undefined) {
+        const applied = at === null ? () => true : at === "base" ? () => false : takenBy(source.commits.slice(0, at));
+        const found = linesWith(file, applied);
+        if (found === null)
+            return `${text}: the file does not exist ${where}`;
+        lines = found;
+        repoPath = file.path;
+    }
+    else if (source.otherChanged.has(path)) {
+        return `${text}: not a text file`;
+    }
+    else if (plain !== undefined) {
+        lines = plain[1].map((t, i) => ({ text: t, tip: i + 1, base: i + 1 }));
+        repoPath = plain[0];
+    }
+    else
+        return `${text}: no such file at the tip`;
+    if (end > lines.length) {
+        return `${text} is past the end of the file ${where} (${lines.length} lines)`;
+    }
+    const picked = lines.slice(start - 1, end);
+    const kept = picked.flatMap((l) => (l.tip === null ? [] : [l.tip]));
+    const removed = picked.flatMap((l) => (l.tip === null && l.base !== null ? [l.base] : []));
+    return {
+        n,
+        path: repoPath,
+        start,
+        end,
+        at,
+        quote: picked.slice(0, QUOTE_LINES).map((l) => utf8(l.text).replace(/\r?\n$/, "")),
+        tip: source.tip,
+        lines: spanOf(kept),
+        old: spanOf(removed),
+    };
+}
+/** Every ref of a body resolved, or every reason one does not, so one fix round is enough. */
+export function resolveRefs(specs, source) {
+    const refs = [];
+    const problems = [];
+    specs.forEach((spec, i) => {
+        const ref = resolveRef(spec, i + 1, source);
+        if (typeof ref === "string")
+            problems.push(ref);
+        else
+            refs.push(ref);
+    });
+    return { refs, problems };
+}