@webappwiz/arbor 0.0.30 → 0.0.32

package/plan.test.ts

@@ -1,318 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import {
-	checkPlan,
-	plannedFiles,
-	type Question,
-	questionNumber,
-	questions,
-	withQuestion,
-} from "./plan";
-
-const GOOD = `# alpha
-
-## Goal
-Teach show to check the plan.
-
-## Files
-- plan.ts
-
-## Done
-- [x] wrote the checker
-
-## Next
-- [ ] wire it up
-
-## Notes
-- lives in plan.ts
-`;
-
-describe("checkPlan", () => {
-	it("passes a plan in the prescribed shape", () => {
-		expect(checkPlan(GOOD, { task: "alpha" })).toEqual([]);
-	});
-
-	it("wants the title to name the task", () => {
-		expect(
-			checkPlan(GOOD.replace("# alpha", "# Alpha work"), { task: "alpha" }),
-		).toEqual(['title is "# Alpha work", should be "# alpha"']);
-	});
-
-	it("names the required sections that are missing", () => {
-		const problems = checkPlan("# alpha\n", { task: "alpha" });
-		expect(problems).toEqual([
-			"no ## Goal section",
-			"no ## Files section",
-			"no ## Next section",
-		]);
-	});
-
-	it("wants the files the task plans to touch", () => {
-		const problems = checkPlan(GOOD.replace("- plan.ts", ""), {
-			task: "alpha",
-		});
-		expect(problems).toEqual([
-			"## Files is empty: list the file paths you plan to touch",
-		]);
-	});
-
-	it("wants a next step, not just an empty heading", () => {
-		const problems = checkPlan(GOOD.replace("- [ ] wire it up", ""), {
-			task: "alpha",
-		});
-		expect(problems).toEqual([
-			"## Next has no `- [ ]` item: say what the next step is",
-		]);
-	});
-
-	it("catches work parked under Done that is not done", () => {
-		const problems = checkPlan(GOOD.replace("- [x] wrote", "- [ ] wrote"), {
-			task: "alpha",
-		});
-		expect(problems).toEqual([
-			"## Done has a `- [ ]` item: it belongs under ## Next",
-		]);
-	});
-
-	it("wants an escalation to leave numbered items behind", () => {
-		expect(checkPlan(GOOD, { task: "alpha", escalated: true })).toEqual([
-			"escalated with no ## Blocked section: add `- [ ] 1.` items for what the reviewer must do",
-		]);
-		const vague = `${GOOD}\n## Blocked\nIs the new banner the right green?\n`;
-		expect(checkPlan(vague, { task: "alpha", escalated: true })).toEqual([
-			"## Blocked lists nothing: add `- [ ] 1.` items for what the reviewer must do",
-		]);
-		const asked = `${GOOD}\n## Blocked\n- [ ] 1. Open /tmp/shot.png. Confirm the banner is green.\n`;
-		expect(checkPlan(asked, { task: "alpha", escalated: true })).toEqual([]);
-		const detailed = `${GOOD}\n## Blocked\n- [ ] 1. Does the banner fit?\n  ![banner](/tmp/shot.png)\n  - (a) Yes\n`;
-		expect(checkPlan(detailed, { task: "alpha", escalated: true })).toEqual([]);
-	});
-
-	it("flags open items once the task is no longer escalated", () => {
-		const items =
-			"- [x] 1. Run the tests. → pass\n- [ ] 2. Decide: keep or drop?\n- [ ] 3. Open /tmp/a.png.\n";
-		const blocked = `${GOOD}\n## Blocked\n${items}`;
-		expect(checkPlan(blocked, { task: "alpha" })).toEqual([
-			"## Blocked has open questions 2, 3: ask the reviewer before merging",
-		]);
-		const answered = `${GOOD}\n## Blocked\n${items.replaceAll("- [ ]", "- [x]")}`;
-		expect(checkPlan(answered, { task: "alpha" })).toEqual([]);
-		// Answered but unchecked is the agent's to act on, not the reviewer's.
-		const acting = `${GOOD}\n## Blocked\n- [ ] 1. Keep it? → yes\n  → and rename it\n`;
-		expect(checkPlan(acting, { task: "alpha" })).toEqual([]);
-	});
-
-	it("flags a section nobody will think to read", () => {
-		const problems = checkPlan(`${GOOD}\n## Ideas\n- someday\n`, {
-			task: "alpha",
-		});
-		expect(problems[0]).toContain('unexpected section "## Ideas"');
-	});
-
-	it("does not mistake a comment in a fenced block for a heading", () => {
-		const fenced = `${GOOD}\n\`\`\`bash\n# alpha notes\n## Goal\n\`\`\`\n`;
-		expect(checkPlan(fenced, { task: "alpha" })).toEqual([]);
-	});
-});
-
-describe("plannedFiles", () => {
-	it("takes each top-level bullet under ## Files, without backticks", () => {
-		const plan = [
-			"# alpha",
-			"",
-			"## Files",
-			"",
-			"Phase 1:",
-			"",
-			"- `a.ts`",
-			"- b/{c,d}.ts",
-			"  - nested note",
-			"",
-			"## Next",
-			"",
-			"- [ ] not a file",
-		].join("\n");
-
-		expect(plannedFiles(plan)).toEqual(["a.ts", "b/{c,d}.ts"]);
-	});
-
-	it("plans nothing without a ## Files section", () => {
-		expect(plannedFiles("# alpha\n")).toEqual([]);
-	});
-});
-
-const BLOCKED = `${GOOD}
-## Blocked
-
-- [x] 1. Run the tests. Does it fit? → pass
-- [ ] 2. Does the header fit? → no, too wide
-- [ ] 3. Decide: keep or drop?
-  - not a question of its own
-- [ ] 4. Confirm the copy.
-`;
-
-/** A question as `questions` reads it, with nothing under it. */
-function bare(overrides: Partial<Question>): Question {
-	return {
-		number: "1",
-		done: false,
-		text: "",
-		body: "",
-		reply: null,
-		followUps: [],
-		choices: [],
-		pick: null,
-		...overrides,
-	};
-}
-
-describe("questions", () => {
-	it("still reads a plan numbered the old way, Q1", () => {
-		const [asked] = questions("## Blocked\n\n- [ ] Q3. Keep it? → yes\n");
-
-		expect(asked).toMatchObject({
-			number: "3",
-			text: "Keep it?",
-			reply: "yes",
-		});
-	});
-
-	it("reads each numbered item with its reply and what is indented under it", () => {
-		expect(questions(BLOCKED)).toEqual([
-			bare({
-				number: "1",
-				done: true,
-				text: "Run the tests. Does it fit?",
-				reply: "pass",
-			}),
-			bare({
-				number: "2",
-				text: "Does the header fit?",
-				reply: "no, too wide",
-			}),
-			bare({
-				number: "3",
-				text: "Decide: keep or drop?",
-				body: "- not a question of its own",
-			}),
-			bare({ number: "4", text: "Confirm the copy." }),
-		]);
-	});
-
-	it("reads only ## Blocked", () => {
-		const elsewhere = GOOD.replace("- [ ] wire it up", "- [ ] 1. Not blocked.");
-		expect(questions(elsewhere)).toEqual([]);
-		const after = `${BLOCKED}\n## Notes\n- [ ] 9. Also not blocked.\n`;
-		expect(questions(after).map((found) => found.number)).toEqual([
-			"1",
-			"2",
-			"3",
-			"4",
-		]);
-	});
-
-	it("keeps the body's markdown, code and images included", () => {
-		const plan = `${GOOD}
-## Blocked
-
-- [ ] 1. Does this migration look right?
-  It runs before the deploy.
-
-  \`\`\`sql
-  alter table users
-    add column email text;
-  \`\`\`
-
-  ![before](/tmp/before.png) ![after](/tmp/after.png)
-  - (a) Ship it
-Prose back at the margin ends it.
-  - (b) not a choice of 1
-`;
-		expect(questions(plan)).toEqual([
-			bare({
-				text: "Does this migration look right?",
-				body: [
-					"It runs before the deploy.",
-					"",
-					"```sql",
-					"alter table users",
-					"  add column email text;",
-					"```",
-					"",
-					"![before](/tmp/before.png) ![after](/tmp/after.png)",
-				].join("\n"),
-				choices: [{ key: "a", text: "Ship it" }],
-				pick: "one",
-			}),
-		]);
-	});
-});
-
-const CHOICES = `${GOOD}
-## Blocked
-
-- [ ] 1. How do old sessions move over?
-  - (a) Force everyone to sign in again
-  - (b) Migrate on next login
-- [ ] 2. Which table? → b (users): and backfill
-  - (a) sessions
-  - (b) users
-- [ ] 3. Anything else? → a bit more logging
-- [ ] 4. Pick one → c
-  - (a) left
-- [ ] 5. Where should it notify? → c (Push), a: and log it
-  - [a] Email
-  - [b] Slack
-  - [c] Push
-`;
-
-describe("choices", () => {
-	it("reads the choices indented under each question", () => {
-		const [first, second, third, fourth, fifth] = questions(CHOICES);
-		expect(first).toMatchObject({
-			choices: [
-				{ key: "a", text: "Force everyone to sign in again" },
-				{ key: "b", text: "Migrate on next login" },
-			],
-			pick: "one",
-		});
-		expect(second?.choices.map((choice) => choice.key)).toEqual(["a", "b"]);
-		expect(third).toMatchObject({ choices: [], pick: null });
-		expect(fourth?.pick).toBe("one");
-		expect(fifth).toMatchObject({ pick: "any" });
-	});
-});
-
-describe("withQuestion", () => {
-	it("numbers a new question after the rest, its detail indented under it", () => {
-		const added = withQuestion(
-			BLOCKED,
-			"Ready to merge?",
-			"Look at\nthe header.",
-		);
-		expect(added.number).toBe("5");
-		expect(questions(added.plan).at(-1)).toMatchObject({
-			number: "5",
-			text: "Ready to merge?",
-			body: "Look at\nthe header.",
-		});
-		expect(questions(added.plan)).toHaveLength(questions(BLOCKED).length + 1);
-	});
-
-	it("makes ## Blocked when there is none", () => {
-		const added = withQuestion(GOOD, "Ready to merge?");
-		expect(added).toEqual({
-			plan: `${GOOD.trimEnd()}\n\n## Blocked\n\n- [ ] 1. Ready to merge?\n`,
-			number: "1",
-		});
-	});
-});
-
-describe("questionNumber", () => {
-	it("reads a number however it was typed", () => {
-		for (const raw of ["9", "q9", "Q9", "9.", " q9: "]) {
-			expect(questionNumber(raw)).toBe("9");
-		}
-		expect(questionNumber("nine")).toBeNull();
-		expect(questionNumber("D9")).toBeNull();
-	});
-});

package/plan.ts

@@ -1,302 +0,0 @@
-import { Markdown } from "webappwiz/md";
-
-/** The plan each task keeps at its worktree root, excluded from git. */
-export const PLAN_FILE = "ARBOR.md";
-
-/** The h2 sections an `ARBOR.md` may have, in the order they belong in. */
-const SECTIONS = ["Goal", "Files", "Done", "Next", "Notes", "Blocked"];
-const REQUIRED = ["Goal", "Files", "Next"];
-const UNCHECKED = /^[ \t]*- \[ \]/m;
-// A `Q` before the number is how plans were numbered once, and still reads.
-const QUESTION = /^[ \t]*- \[[ xX]\] [Qq]?\d+\./m;
-
-const BULLET = /^- +(.+)$/;
-
-/**
- * The paths an `ARBOR.md` says its task will touch: each top-level bullet
- * under `## Files`, taken as written. Prose around the list is left out, and a
- * plan with no such section plans nothing.
- */
-export function plannedFiles(text: string): string[] {
-	const md = Markdown.parse(text);
-	if (!md.has("Files")) {
-		return [];
-	}
-	return md
-		.section("Files")
-		.body.split("\n")
-		.flatMap((line) => {
-			const item = BULLET.exec(line)?.[1];
-			return item === undefined ? [] : [item.replaceAll("`", "").trim()];
-		});
-}
-
-/**
- * One `- [ ] 9.` item under `## Blocked`: something only a person can do.
- * The item's line is its subject; lines indented under it are its body, and
- * `- (a) ...` or `- [a] ...` lines among them are the answers it offers.
- */
-export interface Question {
-	/** As the plan numbers it, `9`: the name a reply goes by. */
-	number: string;
-	/** Checked off, which the agent does once it has acted on the reply. */
-	done: boolean;
-	/** The item's own line, without its checkbox, number or reply. */
-	text: string;
-	/**
-	 * The markdown indented under it, dedented, choices left out: detail,
-	 * code blocks, `![shot](/abs/path.png)` images. Empty when there is none.
-	 */
-	body: string;
-	/** Whatever follows ` → `, or null when nobody has answered yet. */
-	reply: string | null;
-	/**
-	 * What a person added once the reply was read, oldest first: each an
-	 * indented `→ ` line under the question.
-	 */
-	followUps: string[];
-	/**
-	 * The answers it offers, in order. Empty for a question answered in words
-	 * alone. A reply can always add words to its picks, or answer in words
-	 * instead.
-	 */
-	choices: Choice[];
-	/**
-	 * `one` for `- (a)` choices, at most one of which a reply picks; `any` for
-	 * `- [a]` choices, where it picks all that apply. Null without choices.
-	 */
-	pick: "one" | "any" | null;
-}
-
-/** One answer a question offers: `- (b) Migrate on next login`. */
-export interface Choice {
-	/** The letter it goes by: `b`. */
-	key: string;
-	text: string;
-}
-
-const ITEM = /^[ \t]*- \[([ xX])\] [Qq]?(\d+)\.[ \t]*(.*)$/;
-/** What separates an item from its reply, spaces included. */
-const ARROW = " → ";
-/** A follow-up: a line of its own under the question, led by the arrow. */
-const FOLLOW_UP = /^[ \t]+→[ \t]+(.*)$/;
-/** `- (a) text` picks one, `- [a] text` picks any. */
-const CHOICE = /^[ \t]+- (?:\(([a-z])\)|\[([a-z])\])[ \t]+(.+)$/;
-
-/**
- * Every numbered item under `## Blocked`, open or checked off, each with the
- * indented lines under it. The reply is read off the item's own line: an
- * answer is one line, written by `arbor reply` or by hand after the arrow.
- */
-export function questions(text: string): Question[] {
-	const found: { asked: Question; body: string[] }[] = [];
-	// The question the lines being read sit under, if they still do.
-	let last: { asked: Question; body: string[] } | undefined;
-	for (const { line } of blockedLines(text)) {
-		const asked = question(line);
-		if (asked !== null) {
-			last = { asked, body: [] };
-			found.push(last);
-			continue;
-		}
-		// A line back at the margin ends the question; blank ones do not.
-		if (line.trim() !== "" && !/^[ \t]/.test(line)) {
-			last = undefined;
-		}
-		if (last === undefined) {
-			continue;
-		}
-		const followUp = FOLLOW_UP.exec(line);
-		const choice = CHOICE.exec(line);
-		if (followUp !== null) {
-			last.asked.followUps.push((followUp[1] ?? "").trim());
-		} else if (choice !== null) {
-			last.asked.choices.push({
-				key: choice[1] ?? choice[2] ?? "",
-				text: (choice[3] ?? "").trim(),
-			});
-			last.asked.pick ??= choice[1] === undefined ? "any" : "one";
-		} else {
-			last.body.push(line);
-		}
-	}
-	return found.map(({ asked, body }) => {
-		asked.body = dedent(body);
-		return asked;
-	});
-}
-
-/** Lines with the indent they all share taken off, blank ends trimmed. */
-function dedent(lines: string[]): string {
-	const indents = lines
-		.filter((line) => line.trim() !== "")
-		.map((line) => /^[ \t]*/.exec(line)?.[0].length ?? 0);
-	const cut = indents.length === 0 ? 0 : Math.min(...indents);
-	return lines
-		.map((line) => line.slice(cut).trimEnd())
-		.join("\n")
-		.replace(/^\n+|\s+$/g, "");
-}
-
-/**
- * The plan with a new open question at the end of `## Blocked`, the section
- * made if missing, numbered after the highest there. Returns the plan and
- * the number it went by.
- */
-export function withQuestion(
-	text: string,
-	subject: string,
-	body = "",
-): { plan: string; number: string } {
-	const numbers = questions(text).map((asked) => Number(asked.number));
-	const number = String(Math.max(0, ...numbers) + 1);
-	const detail = body.trim() === "" ? [] : body.trim().split("\n");
-	const item = [
-		`- [ ] ${number}. ${subject.trim()}`,
-		...detail.map((line) => `  ${line}`.trimEnd()),
-	];
-	const blocked = blockedLines(text);
-	if (blocked.length === 0 && !/^## Blocked[ \t]*$/im.test(text)) {
-		return {
-			plan: `${text.trimEnd()}\n\n## Blocked\n\n${item.join("\n")}\n`,
-			number,
-		};
-	}
-	const lines = text.split("\n");
-	const last = blocked.findLast(({ line }) => line.trim() !== "");
-	const heading = lines.findIndex((line) => /^## Blocked[ \t]*$/i.test(line));
-	const at = last === undefined ? heading + 1 : last.index + 1;
-	lines.splice(at, 0, ...(last === undefined ? ["", ...item] : item));
-	return { plan: lines.join("\n"), number };
-}
-
-/**
- * A question's number however a person typed it: `9`, `9.`, `Q9` and `q9:`
- * all mean `9`. Null for anything that is not a number at all.
- */
-export function questionNumber(raw: string): string | null {
-	const digits = /^q?(\d+)[.:]?$/i.exec(raw.trim())?.[1];
-	return digits === undefined ? null : String(Number(digits));
-}
-
-function question(line: string): Question | null {
-	const item = ITEM.exec(line);
-	if (item === null) {
-		return null;
-	}
-	const [, check = " ", number = "", rest = ""] = item;
-	const arrow = rest.indexOf(ARROW);
-	return {
-		number,
-		done: check !== " ",
-		text: (arrow === -1 ? rest : rest.slice(0, arrow)).trim(),
-		body: "",
-		reply: arrow === -1 ? null : rest.slice(arrow + ARROW.length).trim(),
-		followUps: [],
-		choices: [],
-		pick: null,
-	};
-}
-
-/**
- * The lines under `## Blocked`, with where each sits in the whole file so a
- * reply can be written back in place.
- */
-function blockedLines(text: string): { index: number; line: string }[] {
-	const { sections } = Markdown.parse(text);
-	const at = sections.findIndex(
-		(section) => section.heading.toLowerCase() === "blocked",
-	);
-	const blocked = sections[at];
-	if (blocked === undefined) {
-		return [];
-	}
-	const lines = text.split("\n");
-	// `line` is 1-based, so it is also the index of the line after the heading.
-	const end =
-		sections.slice(at + 1).find((later) => later.level <= blocked.level)
-			?.line ?? lines.length + 1;
-	return lines
-		.slice(blocked.line, end - 1)
-		.map((line, offset) => ({ index: blocked.line + offset, line }));
-}
-
-export interface PlanOptions {
-	/** The task name the title is expected to match. */
-	task: string;
-	/** Whether the task has escalated, which makes `## Blocked` required. */
-	escalated?: boolean;
-}
-
-/**
- * Every way a task's `ARBOR.md` departs from the shape the agent skill
- * prescribes, phrased for the agent that wrote it. Advisory only: a resumable
- * plan is the point, and a malformed one still beats none, so nothing here
- * blocks a merge.
- */
-export function checkPlan(
-	text: string,
-	{ task, escalated = false }: PlanOptions,
-): string[] {
-	const md = Markdown.parse(text);
-	const problems: string[] = [];
-	const section = (name: string) =>
-		md.has(name) ? md.section(name).body : null;
-
-	if (md.title !== task) {
-		problems.push(
-			md.title === null
-				? `no title: the first line should be "# ${task}"`
-				: `title is "# ${md.title}", should be "# ${task}"`,
-		);
-	}
-	for (const name of REQUIRED) {
-		if (!md.has(name)) {
-			problems.push(`no ## ${name} section`);
-		}
-	}
-	if (section("Goal") === "") {
-		problems.push("## Goal is empty: say in a line or two what done means");
-	}
-	if (section("Files") === "") {
-		problems.push("## Files is empty: list the file paths you plan to touch");
-	}
-	const next = section("Next");
-	if (next !== null && !UNCHECKED.test(next)) {
-		problems.push("## Next has no `- [ ]` item: say what the next step is");
-	}
-	const done = section("Done");
-	if (done !== null && UNCHECKED.test(done)) {
-		problems.push("## Done has a `- [ ]` item: it belongs under ## Next");
-	}
-	const blocked = section("Blocked");
-	if (escalated && blocked === null) {
-		problems.push(
-			"escalated with no ## Blocked section: add `- [ ] 1.` items for what the reviewer must do",
-		);
-	}
-	if (blocked !== null && !QUESTION.test(blocked)) {
-		problems.push(
-			"## Blocked lists nothing: add `- [ ] 1.` items for what the reviewer must do",
-		);
-	}
-	// Answered and unchecked is a follow-up to act on; unanswered needs a person.
-	const open = questions(text).filter(
-		(asked) => !asked.done && asked.reply === null,
-	);
-	if (!escalated && open.length > 0) {
-		const numbers = open.map((asked) => asked.number).join(", ");
-		problems.push(
-			`## Blocked has open questions ${numbers}: ask the reviewer before merging`,
-		);
-	}
-	const known = SECTIONS.map((section) => section.toLowerCase());
-	for (const section of md.sections) {
-		if (section.level === 2 && !known.includes(section.heading.toLowerCase())) {
-			problems.push(
-				`unexpected section "## ${section.heading}" (line ${section.line}): keep to ${SECTIONS.join(", ")}`,
-			);
-		}
-	}
-	return problems;
-}

package/progress.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { progress } from "./progress";
-
-const plan = (...lines: string[]): string => `${lines.join("\n")}\n`;
-
-describe("progress", () => {
-	it("counts the ticked boxes against every box in Done and Next", () => {
-		expect(
-			progress(
-				plan(
-					"# alpha",
-					"",
-					"## Done",
-					"- [x] one",
-					"- [x] two",
-					"",
-					"## Next",
-					"- [ ] three",
-					"- [ ] four",
-				),
-			),
-		).toEqual({ done: 2, total: 4 });
-	});
-
-	it("ignores a checklist outside the sections that hold the work", () => {
-		expect(
-			progress(
-				plan(
-					"# alpha",
-					"",
-					"## Next",
-					"- [ ] the rest",
-					"",
-					"## Notes",
-					"- [ ] a stray box here must not count",
-				),
-			),
-		).toEqual({ done: 0, total: 1 });
-	});
-
-	it("reports nothing to count when the file has no checklist", () => {
-		expect(progress(plan("# alpha", "", "## Goal", "land it"))).toBeNull();
-	});
-
-	it("reports nothing to count when neither section is there at all", () => {
-		expect(progress(plan("- [x] a box under no heading"))).toBeNull();
-	});
-
-	it("counts an upper-case X as ticked, the way the CLI does", () => {
-		expect(
-			progress(plan("## Done", "- [X] one", "", "## Next", "- [ ] two")),
-		).toEqual({ done: 1, total: 2 });
-	});
-});

package/progress.ts

@@ -1,31 +0,0 @@
-import { Markdown } from "webappwiz/md";
-
-const BOX = /^[ \t]*- \[([ xX])\]/gm;
-
-/** The sections that hold the work, so a checklist under Notes cannot skew it. */
-const WORK = ["Done", "Next"];
-
-export interface Progress {
-	done: number;
-	total: number;
-}
-
-/**
- * How far along a task is, counted off its `ARBOR.md` checkboxes rather than
- * anything arbor records: the agent moving an item to `## Done` is the only
- * signal there is that a step finished. Null when there is nothing to count,
- * which is a task whose file has no checklist yet.
- */
-export function progress(plan: string): Progress | null {
-	const md = Markdown.parse(plan);
-	const boxes = WORK.flatMap((name) =>
-		md.has(name) ? [...md.section(name).body.matchAll(BOX)] : [],
-	);
-	if (boxes.length === 0) {
-		return null;
-	}
-	return {
-		done: boxes.filter((box) => box[1] !== " ").length,
-		total: boxes.length,
-	};
-}