@shiyuphan/follow-me 0.1.1 → 0.3.0

package/dist/src/plan.js

@@ -1,17 +1,30 @@
 import { createHash } from "node:crypto";
-import { formatUnitRef, isSha, parseUnitRef, projectFile } from "./diff.js";
+import { formatUnitRef, isSha, isUnitId, parseUnitRef, projectFile } from "./diff.js";
 export const PLAN_SCHEMA = "follow-me/plan@1";
+/** Titles past this many characters draw a warning; the prompt asks for 50 or fewer. */
+export const LONG_TITLE = 72;
 const validated = Symbol("follow-me/validated");
 export function isCommentId(s) {
     return s.length > 0;
 }
+export function isConcernId(s) {
+    return typeof s === "string" && /^k_[0-9a-f]{8}$/.test(s);
+}
 export function isPlanVersion(n) {
     return typeof n === "number" && Number.isInteger(n) && n >= 1;
 }
-const STATUSES = ["addressed", "declined", "deferred"];
+const STATUSES = ["addressed", "declined", "deferred", "answered"];
 function isResponseStatus(s) {
     return STATUSES.some((x) => x === s);
 }
+const SEVERITIES = ["blocker", "major", "minor"];
+const CONCERN_KINDS = ["bug", "missing-test", "naming", "risk"];
+export function isSeverity(s) {
+    return SEVERITIES.some((x) => x === s);
+}
+function isConcernKind(s) {
+    return CONCERN_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);
@@ -19,32 +32,150 @@ export function isFields(v) {
 export function isArray(v) {
     return Array.isArray(v);
 }
-const INVALID = Symbol("invalid narration");
-/** Absent, null and blank all mean no narration, so a planner may always write the field. */
-function parseNarration(v) {
+const INVALID = Symbol("invalid text");
+/** Absent, null and blank all mean none, so a planner may always write the field. */
+function parseText(v) {
     if (v === undefined || v === null)
         return null;
     if (typeof v !== "string")
         return INVALID;
     return v.trim() === "" ? null : v;
 }
-function withNarration(narration) {
-    return narration === null ? {} : { narration };
+const MERMAID_KEYWORDS = [
+    "graph",
+    "flowchart",
+    "sequenceDiagram",
+    "classDiagram",
+    "stateDiagram",
+    "stateDiagram-v2",
+    "erDiagram",
+    "journey",
+    "gantt",
+    "pie",
+    "gitGraph",
+    "mindmap",
+    "timeline",
+    "quadrantChart",
+    "block-beta",
+    "%%{init",
+];
+/** A diagram is Mermaid source, so its first line must name a diagram type. Else the reason. */
+export function diagramProblem(diagram) {
+    const first = (diagram.split("\n").find((line) => line.trim() !== "") ?? "").trim();
+    const named = MERMAID_KEYWORDS.some((k) => first.startsWith(k) && !/[\w-]/.test(first.charAt(k.length)));
+    if (named)
+        return null;
+    return `expected Mermaid source whose first line starts with a diagram type such as flowchart, sequenceDiagram or stateDiagram-v2, got "${first.slice(0, 40)}"`;
+}
+/** A concern is { severity, kind, text, lines? }; lines are change indices, on a unit ref only. */
+function parseConcern(v, onUnit) {
+    if (!isFields(v))
+        return "expected an object";
+    if (!isSeverity(v.severity))
+        return `severity: expected one of ${SEVERITIES.join(", ")}`;
+    if (!isConcernKind(v.kind))
+        return `kind: expected one of ${CONCERN_KINDS.join(", ")}`;
+    if (typeof v.text !== "string" || v.text.trim() === "")
+        return "text: expected a sentence";
+    const { severity, kind, text } = v;
+    if (v.lines === undefined || v.lines === null)
+        return { severity, kind, text };
+    if (!onUnit)
+        return "lines: only a concern on a unit ref has lines";
+    const lines = v.lines;
+    if (!isArray(lines) || lines.length === 0)
+        return "lines: expected a list of change indices";
+    const indices = lines.flatMap((n) => (Number.isInteger(n) && Number(n) >= 0 ? [Number(n)] : []));
+    if (indices.length !== lines.length)
+        return "lines: expected a list of change indices";
+    return { severity, kind, text, lines: [...new Set(indices)].sort((a, b) => a - b) };
+}
+/** Absent, null and [] all mean no concerns, so a planner may always write the field. */
+function parseConcerns(v, onUnit) {
+    if (v === undefined || v === null)
+        return [];
+    if (!isArray(v))
+        return "expected an array";
+    const out = [];
+    for (const [i, raw] of v.entries()) {
+        const concern = parseConcern(raw, onUnit);
+        if (typeof concern === "string")
+            return `[${i}]: ${concern}`;
+        out.push(concern);
+    }
+    return out;
+}
+/** The optional narration, diagram and concerns of a commit or unit entry, or what is wrong. */
+function parseExtras(v, onUnit) {
+    const narration = parseText(v.narration);
+    if (narration === INVALID)
+        return { field: "narration", error: "expected a string" };
+    const diagram = parseText(v.diagram);
+    if (diagram === INVALID)
+        return { field: "diagram", error: "expected a string" };
+    const problem = diagram === null ? null : diagramProblem(diagram);
+    if (problem !== null)
+        return { field: "diagram", error: problem };
+    const concerns = parseConcerns(v.concerns, onUnit);
+    if (typeof concerns === "string")
+        return { field: "concerns", error: concerns };
+    return withExtras(narration, diagram, concerns);
+}
+function withText(narration, diagram) {
+    return {
+        ...(narration === null ? {} : { narration }),
+        ...(diagram === null ? {} : { diagram }),
+    };
+}
+function withExtras(narration, diagram, concerns) {
+    return { ...withText(narration, diagram), ...(concerns.length === 0 ? {} : { concerns }) };
+}
+function serializeConcern(c) {
+    return {
+        severity: c.severity,
+        kind: c.kind,
+        text: c.text,
+        ...(c.lines === undefined ? {} : { lines: c.lines }),
+    };
 }
-/** A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration": "..." }. */
+function serializeExtras(x) {
+    return {
+        ...withText(x.narration ?? null, x.diagram ?? null),
+        ...(x.concerns === undefined ? {} : { concerns: x.concerns.map(serializeConcern) }),
+    };
+}
+/** A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration", "diagram", "concerns" }. */
 function parseUnitEntry(u) {
     if (typeof u === "string")
         return parseUnitRef(u);
     if (!isFields(u) || typeof u.unit !== "string") {
-        return { error: 'expected a unit ref string or { "unit", "narration" }' };
+        return {
+            error: 'expected a unit ref string or { "unit", "narration", "diagram", "concerns" }',
+        };
     }
     const ref = parseUnitRef(u.unit);
     if ("error" in ref)
         return ref;
-    const narration = parseNarration(u.narration);
-    if (narration === INVALID)
-        return { error: "narration must be a string" };
-    return { ...ref, ...withNarration(narration) };
+    const extras = parseExtras(u, true);
+    if ("error" in extras)
+        return { error: `${extras.field}: ${extras.error}` };
+    return { ...ref, ...extras };
+}
+/** { "commit": 3, "unit": "h_x" } with commit 1-based; absent and null mean not given. */
+function parseAnswerAt(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (!isFields(v))
+        return 'expected { "commit", "unit" }';
+    const { commit, unit } = v;
+    if (typeof commit !== "number" || !Number.isInteger(commit) || commit < 1) {
+        return "commit: expected a commit number counted from 1";
+    }
+    if (unit === undefined || unit === null)
+        return { commit };
+    if (typeof unit !== "string" || !isUnitId(unit))
+        return "unit: expected a unit id";
+    return { commit, unit };
 }
 /** Boundary parse of draft.json or plans/vN.json. Reports every malformed field. */
 export function parsePlanFile(draft) {
@@ -78,9 +209,9 @@ export function parsePlanFile(draft) {
             }
             if (typeof c.message !== "string")
                 bad(`${at}.message`, "expected a string");
-            const narration = parseNarration(c.narration);
-            if (narration === INVALID)
-                bad(`${at}.narration`, "expected a string");
+            const extras = parseExtras(c, false);
+            if ("error" in extras)
+                bad(`${at}.${extras.field}`, extras.error);
             const units = [];
             if (!isArray(c.units))
                 bad(`${at}.units`, "expected an array of unit refs");
@@ -93,8 +224,8 @@ export function parsePlanFile(draft) {
                         units.push(ref);
                 }
             }
-            if (typeof c.message === "string" && narration !== INVALID) {
-                commits.push({ message: c.message, ...withNarration(narration), units });
+            if (typeof c.message === "string" && !("error" in extras)) {
+                commits.push({ message: c.message, ...extras, units });
             }
         }
     }
@@ -115,8 +246,19 @@ export function parsePlanFile(draft) {
             }
             else if (typeof r.note !== "string")
                 bad(`${at}.note`, "expected a string");
-            else
-                responses.push({ comment: r.comment, status: r.status, note: r.note });
+            else {
+                const where = parseAnswerAt(r.at);
+                if (typeof where === "string")
+                    bad(`${at}.at`, where);
+                else {
+                    responses.push({
+                        comment: r.comment,
+                        status: r.status,
+                        note: r.note,
+                        ...(where === null ? {} : { at: where }),
+                    });
+                }
+            }
         }
     }
     if (issues.length > 0 || base === null || tip === null)
@@ -131,12 +273,17 @@ export function serializePlanFile(file) {
         tip: file.tip,
         commits: file.commits.map((c) => ({
             message: c.message,
-            ...withNarration(c.narration ?? null),
-            units: c.units.map((ref) => ref.narration === undefined
+            ...serializeExtras(c),
+            units: c.units.map((ref) => ref.narration === undefined && ref.diagram === undefined && ref.concerns === undefined
                 ? formatUnitRef(ref)
-                : { unit: formatUnitRef(ref), narration: ref.narration }),
+                : { unit: formatUnitRef(ref), ...serializeExtras(ref) }),
+        })),
+        responses: file.responses.map((r) => ({
+            comment: r.comment,
+            status: r.status,
+            note: r.note,
+            ...(r.at === undefined ? {} : { at: r.at }),
         })),
-        responses: file.responses.map((r) => ({ comment: r.comment, status: r.status, note: r.note })),
     };
 }
 export function planHash(file) {
@@ -307,7 +454,77 @@ function matchesTip(change, tip) {
     }
     return false;
 }
+/** "k_" + 8 hex over the unit, the lines and the text: stable while the concern is unchanged. */
+function deriveConcernId(unit, c) {
+    const hex = createHash("sha256")
+        .update(`${unit ?? ""}\0${(c.lines ?? []).join(",")}\0${c.text}`)
+        .digest("hex")
+        .slice(0, 8);
+    const id = `k_${hex}`;
+    if (!isConcernId(id))
+        throw new Error(`sha256 produced ${id}`);
+    return id;
+}
+/**
+ * Gives every concern its id and checks where it sits: lines must be change lines the commit
+ * takes, and a unit carries at most one concern across the whole plan.
+ */
+function placeConcerns(diff, file, claims, issues) {
+    const ids = new Set();
+    const holders = new Map();
+    const placedPerCommit = file.commits.map((commit, k) => {
+        const placed = [];
+        const add = (c, unit) => {
+            const id = deriveConcernId(unit, c);
+            if (ids.has(id)) {
+                issues.push({ kind: "bad-concern", commit: k, reason: `${id} repeats another concern` });
+                return;
+            }
+            ids.add(id);
+            placed.push({ ...c, id, ...(unit === null ? {} : { unit }) });
+        };
+        for (const c of commit.concerns ?? [])
+            add(c, null);
+        commit.units.forEach((ref, j) => {
+            const concerns = ref.concerns ?? [];
+            if (concerns.length === 0)
+                return;
+            holders.set(ref.unit, [...(holders.get(ref.unit) ?? []), ...concerns.map(() => k)]);
+            const taken = claims.resolved[k]?.[j]?.select;
+            const unit = diff.units.get(ref.unit);
+            for (const c of concerns) {
+                const lines = c.lines ?? [];
+                if (lines.length > 0 && unit?.kind !== "hunk") {
+                    issues.push({
+                        kind: "bad-concern",
+                        commit: k,
+                        reason: `${ref.unit}: only a text hunk has change lines`,
+                    });
+                    continue;
+                }
+                const outside = taken?.kind === "lines" ? lines.filter((n) => !taken.changes.includes(n)) : [];
+                if (outside.length > 0) {
+                    issues.push({
+                        kind: "bad-concern",
+                        commit: k,
+                        reason: `${ref.unit}: concern lines ${outside.join(", ")} are not change lines this commit takes`,
+                    });
+                }
+                else
+                    add(c, ref.unit);
+            }
+        });
+        return placed;
+    });
+    for (const [unit, commits] of holders) {
+        if (commits.length > 1) {
+            issues.push({ kind: "too-many-concerns", unit, commits: [...new Set(commits)] });
+        }
+    }
+    return placedPerCommit;
+}
 function project(diff, file, claims, issues) {
+    const concerns = placeConcerns(diff, file, claims, issues);
     const { stateAt, tipOf } = projector(diff, claims.owners);
     const present = new Map();
     for (const f of diff.textFiles.values())
@@ -318,6 +535,7 @@ function project(diff, file, claims, issues) {
     }
     const commits = file.commits.map((commit, k) => {
         const refs = claims.resolved[k] ?? [];
+        const mine = concerns[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);
@@ -346,7 +564,8 @@ function project(diff, file, claims, issues) {
         return {
             index: k,
             message: commit.message,
-            ...withNarration(commit.narration ?? null),
+            ...withText(commit.narration ?? null, commit.diagram ?? null),
+            ...(mine.length === 0 ? {} : { concerns: mine }),
             refs,
             changes,
         };
@@ -366,6 +585,26 @@ function project(diff, file, claims, issues) {
     }
     return commits;
 }
+/**
+ * Why an "answered" response is not an answer, or null. It must answer a question and point at a
+ * commit, or a unit of it, that carries narration or a diagram to explain it.
+ */
+function answerProblem(file, r, isQuestion) {
+    if (!isQuestion)
+        return "answered is only for questions; use addressed, declined or deferred";
+    if (r.at === undefined)
+        return 'an answer needs "at" naming the commit that explains it';
+    const commit = file.commits[r.at.commit - 1];
+    if (commit === undefined)
+        return `at.commit ${r.at.commit} is not a commit of this plan`;
+    const target = r.at.unit;
+    const ref = target === undefined ? undefined : commit.units.find((u) => u.unit === target);
+    if (target !== undefined && ref === undefined) {
+        return `commit ${r.at.commit} does not take ${target}`;
+    }
+    const explains = [commit, ref].some((x) => x?.narration !== undefined || x?.diagram !== undefined);
+    return explains ? null : `commit ${r.at.commit} has no narration or diagram to point at`;
+}
 /**
  * Parses and checks a draft against the diff: every change line used exactly once, every
  * commit's tree valid, and the last commit equal to the tip. Collects all issues at once.
@@ -406,8 +645,25 @@ export function validatePlan(diff, draft, opts = {}) {
     const warnings = review === null
         ? []
         : review.comments
-            .filter((c) => !answered.has(c.id))
+            .filter((c) => c.author !== "agent" && !answered.has(c.id))
             .map((c) => ({ kind: "unanswered", comment: c.id, review: review.planVersion }));
+    file.commits.forEach((c, commit) => {
+        const length = (c.message.split("\n")[0] ?? "").length;
+        if (length > LONG_TITLE)
+            warnings.push({ kind: "long-title", commit, length });
+    });
+    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);
+        if (isQuestion === undefined)
+            continue;
+        if (r.status === "addressed" && isQuestion) {
+            warnings.push({ kind: "question-addressed", comment: r.comment });
+        }
+        const problem = r.status === "answered" ? answerProblem(file, r, isQuestion) : null;
+        if (problem !== null)
+            issues.push({ kind: "bad-answer", comment: r.comment, reason: problem });
+    }
     if (issues.length > 0)
         return { ok: false, issues };
     return {