catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/domain/notice.ts

@@ -6,9 +6,12 @@
 /** Spec §3.6: `later` waits for the receiver's turn to end, `next` drains at its next tool round. Never `now`. */
 export type NoticePriority = "later" | "next";
 
-/** One role's news: it finished (`record`), or an event while it runs (`stall`). */
+/**
+ * One role's news: it finished (`record`), or an event while it runs (`stall`); of a 2.0 run, one of its
+ * reports (`report`: `name` is the unit, `status` the report's kind, `reply` its text).
+ */
 export interface Notice {
-  kind: "finished" | "stalled";
+  kind: "finished" | "stalled" | "report";
   eventId: string;
   runId: string;
   runTitle: string;
@@ -41,6 +44,7 @@ const threadWord = (n: Notice): string => `thread: ${n.thread ?? "none"}`;
 
 /** The first line of one role's block: it must stand alone, since the Desktop preview shows only it. */
 export function noticeHeader(n: Notice): string {
+  if (n.kind === "report") return `catherd · ${n.runTitle} · ${n.status} · ${n.name}`;
   const head = `catherd · ${n.runTitle} · ${n.name} ${n.role} · ${n.rung} · ${n.status}`;
   if (n.kind === "stalled") return `${head} · running ${n.secs}s · ${threadWord(n)}`;
   return [
@@ -68,6 +72,15 @@ export function capNoticeReply(reply: string, cap = REPLY_CAP): string {
 const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2 $3");
 
 function block(n: Notice): string {
+  if (n.kind === "report")
+    return [
+      noticeHeader(n),
+      ...(n.reply ? [n.reply] : []),
+      n.status === "parked"
+        ? `Answer: answer(run: "${n.runId}", unit: "${n.name}", answer: "<your answer>")`
+        : `Status: status(run: "${n.runId}")`,
+      `Event: ${n.eventId}`,
+    ].join("\n");
   const call = `run: "${n.runId}", name: "${n.name}"`;
   if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})\nEvent: ${n.eventId}`;
   const reply = capNoticeReply(n.reply);
@@ -80,12 +93,16 @@ function block(n: Notice): string {
 function previewOf(ns: Notice[]): string {
   const titles = [...new Set(ns.map((n) => n.runTitle))];
   const where = titles.length === 1 ? titles[0] : plural(titles.length, "run", "runs");
-  const what = ns.every((n) => n.kind === "finished")
-    ? `${ns.length} roles finished`
-    : `${plural(ns.length, "role", "roles")} to look at`;
-  const each = ns.map(
-    (n) =>
-      `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]} (${threadWord(n)})`,
+  const reports = ns.every((n) => n.kind === "report");
+  const what = reports
+    ? plural(ns.length, "report", "reports")
+    : ns.every((n) => n.kind === "finished")
+      ? `${ns.length} roles finished`
+      : `${plural(ns.length, "role", "roles")} to look at`;
+  const each = ns.map((n) =>
+    n.kind === "report"
+      ? `${n.name} ${n.status}`
+      : `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]} (${threadWord(n)})`,
   );
   return `catherd · ${where} · ${what}: ${each.join(", ")}`;
 }

package/src/domain/notify.ts

@@ -0,0 +1,32 @@
+import type { NotifyMoment } from "./profile.ts";
+
+export interface NotifyMessage {
+  title: string;
+  message: string;
+  tags: string[];
+}
+
+/**
+ * The phone message of a moment (spec 2.0): the run, the unit and the command that answers it, nothing else.
+ * Never the question's text, never code or secrets: the owner opens catherd to read it.
+ */
+export function notifyMessage(i: {
+  runId: string;
+  runTitle: string;
+  unit: string;
+  moment: NotifyMoment;
+}): NotifyMessage {
+  const title = `catherd · ${i.runTitle}`;
+  switch (i.moment) {
+    case "blocked":
+      return {
+        title,
+        message: `${i.unit} needs your answer. Answer: catherd answer ${i.runId} ${i.unit} "<your answer>"`,
+        tags: ["question"],
+      };
+    case "milestone":
+      return { title, message: `${i.unit} landed.`, tags: ["white_check_mark"] };
+    case "finish":
+      return { title, message: `The run finished: catherd status ${i.runId}`, tags: ["checkered_flag"] };
+  }
+}

package/src/domain/plan-doc.ts

@@ -0,0 +1,198 @@
+/** Plan files as a preamble and tasks (plan 32): what a lane's `Tasks:` line points at, and what an approval reads. */
+
+export interface PlanTask {
+  doc: string;
+  id: string;
+  title: string;
+  text: string;
+  signature: boolean;
+  test: boolean;
+}
+export interface PlanDoc {
+  name: string;
+  preamble: string;
+  tasks: PlanTask[];
+  /** the whole file, for the section checks (a section may follow the tasks) */
+  text: string;
+}
+
+export const TASK_HEADING = /^#{2,4}[ \t]+Task[ \t]+(\d+[a-z]?)\b[ \t]*[:.—–-]?[ \t]*(.*)$/gim;
+export const TASK_REF = /^(?:([^\s#,]+)#)?(\d+[a-z]?)$/;
+
+const SIGNATURE = [
+  /^[ \t]*(?:[-*][ \t]*)?\**(?:Interfaces|Produces|Signatures?)\**[ \t]*:/im,
+  /^[ \t]*```/m,
+  /`[^`\n]*\w\([^`\n]*\)[^`\n]*`/,
+];
+const TEST = [
+  /^[ \t]*(?:[-*][ \t]*)?\**Tests?\**[ \t]*:/im,
+  /[\w./-]*(?:\.test\.|_test\.|\.spec\.|\btest_)[\w.]*/,
+  /\b(?:it|test|describe)\(\s*["'`]|\bfunc Test\w+|\bdef test_\w+|#\[test\]/,
+  /^[ \t]*(?:[-*][ \t]*)?\**Expected\**[ \t]*:/im,
+];
+
+export function parsePlanDoc(name: string, text: string): PlanDoc {
+  const heads = [...text.matchAll(TASK_HEADING)];
+  const tasks: PlanTask[] = heads.map((m, i) => {
+    const next = heads[i + 1]?.index ?? text.length;
+    const body = text.slice(m.index, next);
+    const nl = body.indexOf("\n");
+    // a task ends at the next task heading, or at the next `## ` heading after its own line
+    const rest = nl < 0 ? -1 : body.slice(nl).search(/^##[ \t]+(?!#)/m);
+    const taskText = rest < 0 ? body : body.slice(0, nl + rest);
+    return {
+      doc: name,
+      id: m[1] as string,
+      title: (m[2] ?? "").trim(),
+      text: taskText,
+      signature: SIGNATURE.some((r) => r.test(taskText)),
+      test: TEST.some((r) => r.test(taskText)),
+    };
+  });
+  const milestone = /^##[ \t]+M\d+\b/m.exec(text)?.index ?? text.length;
+  return { name, preamble: text.slice(0, Math.min(milestone, heads[0]?.index ?? text.length)), tasks, text };
+}
+
+const and = (names: string[]) =>
+  names.length === 2 ? names.join(" and ") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+
+/** The task a lane's `Tasks:` ref names, or why it names none. */
+export function resolveTask(docs: PlanDoc[], ref: string): PlanTask | string {
+  const m = TASK_REF.exec(ref);
+  if (!m) return `${ref} is not a task number like 3 or plan.md#3`;
+  const file = m[1];
+  const id = m[2] as string;
+  if (file !== undefined) {
+    const doc = docs.find((d) => d.name === file);
+    if (!doc) return `no plan file ${file}`;
+    return pick(doc, id) ?? `no task ${id} in ${file}`;
+  }
+  const owners = docs.filter((d) => d.tasks.some((t) => t.id === id));
+  if (owners.length === 0) return `no task ${id} in ${docs.map((d) => d.name).join(", ")}`;
+  if (owners.length > 1) {
+    const names = owners.map((d) => d.name);
+    return `task ${id} is in ${and(names)}: write ${names[0]}#${id}`;
+  }
+  return pick(owners[0] as PlanDoc, id) as PlanTask | string;
+}
+
+/** The one task `id` names in `doc`, or why it names none: a file that holds a number twice cannot say which. */
+function pick(doc: PlanDoc, id: string): PlanTask | string | undefined {
+  const held = doc.tasks.filter((t) => t.id === id);
+  return held.length > 1 ? `${doc.name} holds Task ${id} twice: renumber one of them` : held[0];
+}
+
+/** What is wrong between a milestone's lanes and the plan: a lane with no task, a bad ref, a task with nothing to build or test. */
+export function coverageProblems(
+  docs: PlanDoc[],
+  lanes: { id: string; tasks: string[] }[],
+): { lane: string; note: string }[] {
+  const out: { lane: string; note: string }[] = [];
+  const named = new Set<PlanTask>();
+  for (const l of lanes) {
+    if (l.tasks.length === 0) {
+      out.push({
+        lane: l.id,
+        note: `lanes/${l.id}.md has no Tasks: line: name the plan tasks it implements`,
+      });
+      continue;
+    }
+    for (const ref of l.tasks) {
+      const r = resolveTask(docs, ref);
+      if (typeof r === "string") out.push({ lane: l.id, note: `lanes/${l.id}.md: Tasks: ${ref} — ${r}` });
+      else named.add(r);
+    }
+  }
+  // only a task a lane builds needs something to build or test: the rest of the plan is the owner's
+  for (const t of named)
+    if (!t.signature && !t.test)
+      out.push({
+        lane: "",
+        note: `${t.doc} Task ${t.id} has neither a signature nor a test: add its signatures (a code block or an Interfaces: line) or a Test: line`,
+      });
+  return out;
+}
+
+export const DEPTH_SECTIONS = ["What already exists", "Contracts", "Decisions"] as const;
+
+/** The text under a `## <name>` heading (case-insensitive prefix), up to the next `## ` heading; null when absent. */
+function section(text: string, name: string): string | null {
+  const lines = text.split("\n");
+  const at = lines.findIndex((l) => new RegExp(`^##[ \\t]+${name}`, "i").test(l));
+  if (at < 0) return null;
+  const end = lines.findIndex((l, i) => i > at && /^##[ \t]+(?!#)/.test(l));
+  return lines.slice(at + 1, end < 0 ? undefined : end).join("\n");
+}
+
+const DECISION = /^[ \t]*(?:[-*][ \t]*)?\**(D\d+)\b/;
+
+/** What a plan the architect wrote lacks, to the depth the owner reviews: one line per gap. */
+export function depthProblems(doc: PlanDoc): string[] {
+  const out: string[] = [];
+  const full = doc.text;
+  for (const s of DEPTH_SECTIONS) if (section(full, s) === null) out.push(`plan.md has no "## ${s}" section`);
+  if (doc.tasks.length === 0) out.push('plan.md has no "### Task <n>:" heading');
+  for (const t of doc.tasks)
+    if (!t.test) out.push(`plan.md Task ${t.id} has no test: add a Test: line naming its test file and case`);
+  for (const line of (section(full, "Decisions") ?? "").split("\n")) {
+    const id = DECISION.exec(line)?.[1];
+    if (id && !/rejected/i.test(line))
+      out.push(
+        `plan.md ${id} names no rejected alternative: write ${id} — <choice> — rejected: <alternative> — <why>`,
+      );
+  }
+  const exists = section(full, "What already exists");
+  if (exists !== null && !/`[^`\n]*(?:\/|\.\w+)[^`\n]*`/.test(exists))
+    out.push("plan.md's What already exists lists no path");
+  return out;
+}
+
+export const APPROVE_WORDS = ["approve", "approved", "yes", "ok", "lgtm"] as const;
+
+/** A bare approving word, case and a trailing `.`/`!` ignored; "ok but rename X" is a change request. */
+export function isApproval(answer: string): boolean {
+  const w = answer
+    .trim()
+    .toLowerCase()
+    .replace(/[.!]+$/, "");
+  return (APPROVE_WORDS as readonly string[]).includes(w);
+}
+
+export const approvalQuestion = (runId: string) =>
+  `The architect's plan is ready for your review: catherd run-file read ${runId} plan.md. Answer approve, or say what to change.`;
+
+export const reapprovalQuestion = (runId: string, ids: string[]) =>
+  `The architect changed approved decisions ${ids.join(", ")} of plan.md: catherd run-file read ${runId} plan.md. Answer approve, or say what to change.`;
+
+/** Each `D<n>` line of the Decisions section, keyed by its id, whitespace collapsed. */
+export function decisionLines(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const line of (section(text, "Decisions") ?? "").split("\n")) {
+    const id = DECISION.exec(line)?.[1];
+    if (id) out.set(id, line.trim().replace(/\s+/g, " "));
+  }
+  return out;
+}
+
+/** The `D<n>` ids added, removed or edited between two plan texts, in number order. */
+export function changedDecisions(approved: string, now: string): string[] {
+  const a = decisionLines(approved);
+  const b = decisionLines(now);
+  return [...new Set([...a.keys(), ...b.keys()])]
+    .filter((id) => a.get(id) !== b.get(id))
+    .sort((x, y) => Number(x.slice(1)) - Number(y.slice(1)));
+}
+
+/** The copies' file names: basenames, a repeat numbered `-2` before its extension. */
+export function planInputNames(paths: string[]): string[] {
+  const used = new Set<string>();
+  return paths.map((p) => {
+    const base = p.split("/").at(-1) as string;
+    const dot = base.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [base.slice(0, dot), base.slice(dot)] : [base, ""];
+    let name = base;
+    for (let n = 2; used.has(name); n++) name = `${stem}-${n}${ext}`;
+    used.add(name);
+    return name;
+  });
+}

package/src/domain/plan-lint.ts

@@ -0,0 +1,141 @@
+import { type LaneHeader, parseLaneHeader } from "./lane.ts";
+
+export interface PlanLint {
+  /** advice only: preflight reports it and goes on */
+  warnings: string[];
+  /** an `After:` that can never finish: the lane (or the cycle's first lane) never starts */
+  stuck: { lane: string; note: string }[];
+}
+
+const milestoneOf = (id: string): string => id.split(".")[0] as string;
+const isFolder = (p: string): boolean => p.endsWith("/");
+
+/**
+ * Lint of the lanes in scope. `known` is every lane id of the run (a bare milestone `Mx` is known when one of its lanes is), the landed milestones' too, so an `After:` on a
+ * lane that already landed is no error. `finished` is the milestones that landed (merged, in a base run): an `After:`
+ * on a lane of any other milestone can never finish, as that milestone does not start before this one is done. Never throws: a lane whose header cannot be read is left out.
+ */
+export function lintLanes(
+  lanes: { id: string; text: string }[],
+  known: string[],
+  finished: string[] = [],
+): PlanLint {
+  const warnings: string[] = [];
+  const stuck: PlanLint["stuck"] = [];
+  const headers = new Map<string, LaneHeader>();
+  for (const l of lanes) {
+    try {
+      headers.set(l.id, parseLaneHeader(l.text));
+    } catch {
+      // a header that cannot be read is preflight's refusal to make, not lint's
+    }
+  }
+  const inScope = lanes.filter((l) => headers.has(l.id));
+  const milestones = new Set(known.map(milestoneOf));
+
+  for (const { id } of inScope) {
+    const h = headers.get(id) as LaneHeader;
+    const folders = h.owns.filter(isFolder);
+    if (folders.length)
+      warnings.push(
+        `${id}: Owns names whole folders (${folders.join(", ")}): name the files, unless the lane creates the folder`,
+      );
+    for (const a of h.after) {
+      if (a === id) stuck.push({ lane: id, note: `${id}: After: names the lane itself` });
+      else if (!a.includes(".") && a === milestoneOf(id))
+        stuck.push({ lane: id, note: `${id}: After: ${a} is its own milestone: this lane never starts` });
+      else if (a.includes(".") ? !known.includes(a) : !milestones.has(a))
+        stuck.push({ lane: id, note: `${id}: After: ${a} has no lane file` });
+      else if (milestoneOf(a) !== milestoneOf(id) && !finished.includes(milestoneOf(a)))
+        stuck.push({
+          lane: id,
+          note: `${id}: After: ${a} is in milestone ${milestoneOf(a)}, which has not finished: this lane never starts`,
+        });
+      else {
+        const other = headers.get(a);
+        if (
+          other &&
+          h.kind !== "research" &&
+          other.kind !== "research" &&
+          h.owns.length &&
+          other.owns.length &&
+          !h.owns.some(isFolder) &&
+          !other.owns.some(isFolder) &&
+          !h.owns.some((p) => other.owns.includes(p))
+        )
+          warnings.push(
+            `${id}: After: ${a} shares no file with it: drop it unless ${id} needs ${a}'s output`,
+          );
+      }
+    }
+  }
+
+  const edges = (id: string): string[] =>
+    (headers.get(id)?.after ?? []).filter((a) => a !== id && headers.has(a));
+
+  const state = new Map<string, "visiting" | "done">();
+  const path: string[] = [];
+  const visit = (id: string): void => {
+    state.set(id, "visiting");
+    path.push(id);
+    for (const a of edges(id)) {
+      if (state.get(a) === "visiting") {
+        const loop = [...path.slice(path.indexOf(a)), a];
+        stuck.push({ lane: a, note: `After: cycle ${loop.join(" → ")}: these lanes never start` });
+      } else if (!state.has(a)) visit(a);
+    }
+    path.pop();
+    state.set(id, "done");
+  };
+  for (const { id } of inScope) if (!state.has(id)) visit(id);
+
+  const depth = new Map<string, number>();
+  const depthOf = (id: string): number => {
+    const seen = depth.get(id);
+    if (seen !== undefined) return seen;
+    depth.set(id, 1);
+    const d =
+      1 +
+      Math.max(
+        0,
+        ...edges(id)
+          .filter((a) => milestoneOf(a) === milestoneOf(id))
+          .map(depthOf),
+      );
+    depth.set(id, d);
+    return d;
+  };
+  const byMilestone = new Map<string, string[]>();
+  for (const { id } of inScope)
+    byMilestone.set(milestoneOf(id), [...(byMilestone.get(milestoneOf(id)) ?? []), id]);
+  for (const [m, ids] of byMilestone) {
+    if (ids.length < 2 || !ids.some((id) => edges(id).some((a) => milestoneOf(a) === m))) continue;
+    const k = Math.max(...ids.map(depthOf));
+    warnings.push(
+      `info: ${m} critical path ${k} of ${ids.length} lanes${k === ids.length ? ": fully serial" : ""}`,
+    );
+  }
+  return { warnings, stuck };
+}
+
+/** What keeps the milestones from ever starting: an `after` naming no milestone of the plan, or a wait cycle. */
+export function milestoneProblems(milestones: { id: string; after: string[] }[]): string[] {
+  const after = new Map(milestones.map((m) => [m.id, m.after]));
+  const out: string[] = [];
+  for (const m of milestones)
+    for (const a of m.after) if (!after.has(a)) out.push(`${m.id}: After: ${a} is no milestone of the plan`);
+  const done = new Set<string>();
+  const path: string[] = [];
+  const visit = (id: string): void => {
+    path.push(id);
+    for (const a of after.get(id) ?? []) {
+      if (path.includes(a))
+        out.push(`milestones wait on each other (cycle ${[...path.slice(path.indexOf(a)), a].join(" → ")})`);
+      else if (!done.has(a) && after.has(a)) visit(a);
+    }
+    path.pop();
+    done.add(id);
+  };
+  for (const m of milestones) if (!done.has(m.id)) visit(m.id);
+  return out;
+}