diff --git a/README.md b/README.md index 8d92e632..511dcb17 100644 --- a/README.md +++ b/README.md @@ -42,21 +42,24 @@ That file sits in your quest log, a tree under `quest/`: quest/ README.md # The roadmap m0/ - README.md # First milestone, in priority order + README.md # The first milestone export.md # Ready download.md # Required: export.md ``` -Folders are **epics**. A README's `Required` lists its children in -priority order, beside any other dependencies. The README is the epic's +Folders are **epics**, and the quests in a folder are its children; its +README lists only what blocks it, never its children. The README is the epic's own quest, and it becomes ready once its children have merged. The top folders (`m0`, `m1`, ...) are **milestones** that give the work a delivery horizon. +Finishing a quest deletes its file and edits no README, so PRs that finish +sibling quests do not conflict. When a quest is complete, its PR removes the plan and the links that depended on it, so the quests that required it can become ready. A PR that leaves work rewrites the plan to what remains. Milestones are never -deleted, so a PR that finishes one (its README has no `Required` left) removes -the links to that milestone too; `quest check` flags any it misses. The +deleted, so a PR that finishes one (its folder holds no other quest and its +README has no `Required` left) removes the links to that milestone too; +`quest check` flags any it misses. The finished plan stays in Git history, beside the code that completed it. Work is taken through a live runner lock or an open change on the forge. @@ -119,7 +122,8 @@ nonzero exit means the command failed. ## Prioritize ready work `quest unblocked` ranks ready quests by milestone priority, descending number -of distinct transitive dependents, then existing tree order. Counts include +of distinct transitive dependents, then path order, which compares numbers by +value so `m10` follows `m9`. Counts include later milestones without moving their candidates ahead of earlier milestones. Structural root, milestone, and epic membership does not add to the count; real dependencies on an epic still reach its remaining work. Other prerequisites @@ -284,7 +288,8 @@ just finished, but keeps the root's listing of the milestone. Both stage the change, print one line per file (`R from -> to`, `D path`, or `M path`), and report on stderr any other mention of the path, such as prose or files outside `quest/`, without editing it. They run `quest check` on the -result and exit 1 if it fails, for example when a quest moved out of its epic. +result and exit 1 if it fails, for example when a quest moved into a folder +with no README. An epic is its directory or README; removing one that holds other quests needs `-r`. The root and milestones are never moved or removed. `mv` refuses a @@ -295,8 +300,8 @@ Neither command touches branches or PRs. ## Merge quest lists -Concurrent PRs edit the same link lists: the base branch deletes finished -quests' lines while a branch inserts a new quest beside them. `quest init` +Concurrent PRs can edit the same link list: the base branch deletes a finished +blocker's line while a branch adds another blocker beside it. `quest init` routes `quest/**` through a merge driver in `.gitattributes` and registers it in the clone's git config, so a local `git merge` resolves those conflicts. @@ -1649,7 +1654,7 @@ Automatic project history passes read updates since their prior issue/PR boundaries, including timestamp ties. Explicit Refresh starts or resumes a full history pass; successive refreshes repair cached issues deleted without a webhook. Open draft bodies are read only to classify `## Waiting`. -[The first milestone](quest/m0/README.md) lists the quests that remain. +[The first milestone](quest/m0/) holds the quests that remain. ## Contributing diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 30b096c7..ebdb5628 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -9,11 +9,11 @@ GitHub issues remain the untrusted public front door, while quests provide durab A **quest** is a Markdown file, completed in one PR. -An **epic** is a directory that consists of multiple quests. -The `README.md` file is the quest and the `Required` section lists the children. +An **epic** is a directory of quests. +Its children are the quest files in it and the epics one level down; its `README.md` is the epic's own work and lists none of them. It completes when its own work is done and every child has merged. -The root's entries are special epics called **milestones** (`m0`, `m1`, ...) that group work by priority horizon. +The directories under `quest/` are special epics called **milestones** (`m0`, `m1`, ...) that group work by priority horizon. Milestones are permanent. Quests are linked with root-absolute paths. @@ -45,9 +45,8 @@ Current decisions, open questions, or implementation guidance. ## Required -- [Child quest](/quest/foo/bar.md) - the outcome, so the list reads without opening it -- [Nested epic](/quest/foo/baz/README.md) - what the whole epic delivers -- [Blocker](/quest/bar.md) - work that must finish before this can start +- [Blocker](/quest/foo/bar.md) - what it delivers that this needs, so the list reads without opening it +- [Epic blocker](/quest/baz/README.md) - an epic finishes with all of its children ## Closes @@ -63,14 +62,15 @@ The `Goal` section is required; everything else is optional. Use these exact hea Size the title `[XS]` to `[XL]` by the agent's effort to implement, verify, and land it, judgment included. Much code that is mechanical stays small, such as applying one rename the same way across the tree, sized XS. Little code that is mostly judgment is larger, such as a 30-line rewording of a skill, sized M rather than XS. -An epic carries no size until its last child is removed; its README is then the epic's remaining work. +An epic carries no size until its last child is deleted; its README is then the epic's remaining work. `Waiting` lists what the work waits on outside the tree; each item opens with who acts, `Maintainer:` or the outside party, before a colon. A decision item gives its options and a recommendation. Remove an item once its condition clears, and the heading with its last item. -`Required` lists the quests that must finish before the work starts. -The list is ordered by priority, inserted at rank. +`Required` lists the quests that must finish before the work starts; an epic's never lists its own quests, which it already waits for. +A child that must precede a sibling is in that sibling's `Required`. +Nothing else orders work within a milestone: `quest unblocked` ranks it by downstream impact, then path. When the section is empty, delete it; the quest is now unblocked. `Required` must be acyclic. diff --git a/assets/skills/audit.md b/assets/skills/audit.md index 3567c40d..4e946d37 100644 --- a/assets/skills/audit.md +++ b/assets/skills/audit.md @@ -4,18 +4,18 @@ description: Audit and fix outstanding quests for disagreements, conflicts, misa Before you begin, run `quest guide` and `quest skill plan`, and read their output completely. -The goal is a quest tree that agrees with itself and the code, ordered by priority. +The goal is a quest tree that agrees with itself and the code, with each quest in the milestone its priority calls for. The scope is every outstanding quest; the argument (if provided) filters it to specific quests or epics. Look for: - Disagreements: quests whose goals or plans contradict each other, the code, or the repository's docs. - Conflicts: quests that would change the same code or interface incompatibly, or that must land in order without a `Required` link. -- Misaligned priorities: a quest ranked or placed in a milestone ahead of work it depends on, or behind work it blocks. +- Misaligned priorities: a quest placed in a milestone ahead of work it depends on, or behind work it blocks. - Stale plans: work already done, blockers that have cleared, or references to code that no longer exists. - Obsolete quests: a problem that is no longer real, or a plan a later change or decision has made the wrong solution. Split the reading across parallel sub-agents, each given a slice of the scope and returning its findings with evidence (a path, line, or commit). -Apply factual corrections and changes the user has already decided. Moving a quest between milestones or changing its rank is always the user's decision, never a factual correction. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. +Apply factual corrections and changes the user has already decided. Moving a quest between milestones is always the user's decision, never a factual correction. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. Move and delete quests with `quest mv` and `quest rm`, which update the links to them; edit any mentions they report, run `quest check`, and follow the repository's PR workflow within the user's authorized scope. Report the changes with their evidence and any decisions still open. An explicit read-only audit request leaves the tree unchanged. diff --git a/assets/skills/plan.md b/assets/skills/plan.md index 7b9c994b..43d36f26 100644 --- a/assets/skills/plan.md +++ b/assets/skills/plan.md @@ -28,7 +28,7 @@ Once complete, create, update, or delete the relevant quests and epics. Record each settled decision and its reason in the quest's Plan, so later sessions don't ask it again, and the decision prompts in the PR. A fix quest's Plan names the PR that caused the problem when it is known, so its implementer lists it under `## Caused by` without searching again. When the PR deletes the quest, record its decisions in the PR body's `## Decisions` section instead, since the deletion takes the Plan with it. -New work joins the milestone the user picked, at its rank; an epic groups related quests, and its README holds the work no child owns (the end-to-end test, the docs page). +New work joins the milestone the user picked, in its directory or an epic's there; an epic groups related quests, and its README holds the work no child owns (the end-to-end test, the docs page). When done, commit, open the PR as a draft, and run `/quest-review` on it, which reviews the branch, records the `## Review` section, and marks the PR ready. Quests planned as follow-ups of an open PR may be committed to that PR instead, whose next push is reviewed as `quest context`'s Reviews section describes. diff --git a/assets/skills/recurring.md b/assets/skills/recurring.md index 9552f5e9..00e99b0a 100644 --- a/assets/skills/recurring.md +++ b/assets/skills/recurring.md @@ -7,14 +7,14 @@ Before you begin, run `quest guide` and `quest skill plan`, and read their outpu Run the plan interview for a quest that recurs: the PR that finishes one run creates the next. The argument (if provided) is the work to repeat, or an existing quest to make recurring. -Agents working the quest never load this skill, so its Plan says, in its own words, where the next run goes, what gates it, and that it's linked from its parent's `Required`. +Agents working the quest never load this skill, so its Plan says, in its own words, where the next run goes and what gates it. The next run keeps the Goal and recurrence, and its Plan carries forward what this run learned (baselines, results, what to check first). Also settle in the interview: - Where the next run goes. If milestones only grow, it's the same path in the next milestone (`m1/perf/audit.md` to `m2/perf/audit.md`), created with any missing milestone or epic. If they shift up after a release, it's wherever the next run belongs after the shift. -- What gates it. Rank doesn't delay a quest: one with no `Required` is ready at once. Gate it on another recurring quest (such as a release cut) or a condition quest. A quest can't require its own milestone, so to run at the end of mN, the gate requires mN and the next run requires the gate. -- What each run delivers, where it ranks, and whether anything ends the recurrence. +- What gates it. Placement doesn't delay a quest: one with no `Required` is ready at once. Gate it on another recurring quest (such as a release cut) or a condition quest. A quest can't require its own milestone, so to run at the end of mN, the gate requires mN and the next run requires the gate. +- What each run delivers, and whether anything ends the recurrence. A recurring gate's Plan also says to remove its path from every `Required` before re-creating it, or its dependents never clear. Findings that need their own work are follow-ups for `/quest-plan`. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index 366da4bd..eefdc8dd 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -6,7 +6,7 @@ Before you begin, run `quest guide` and read its output completely. Your goal is to execute many quests in parallel. The scope consists of all ready quests that are not claimed. -Run `quest unblocked --unclaimed --json` for unclaimed ready candidates in milestone priority, descending downstream impact, then tree order. +Run `quest unblocked --unclaimed --json` for unclaimed ready candidates in milestone priority, descending downstream impact, then path order. The count is distinct transitive dependents; other prerequisites may still remain. Use that order when dispatching. As each agent reports, rerun `quest unblocked --unclaimed --json`, which reads the upstream tree afresh, and start the newly ready quests you would recommend, within the harness's agent limit: merges elsewhere and released claims make more work ready while the spawn runs. diff --git a/cloudflare/dev/seed.ts b/cloudflare/dev/seed.ts index a91c3a3c..a3fdf8de 100644 --- a/cloudflare/dev/seed.ts +++ b/cloudflare/dev/seed.ts @@ -34,21 +34,11 @@ export function world(): World { { path: "flake.nix", content: "{ outputs = _: { }; }\n" }, { path: "quest/README.md", - content: quest("Quests", "Plan the rocket app.", [ - "- [M0: Beta](/quest/m0/README.md) - the first public beta", - "- [M1: Later](/quest/m1/README.md) - after the beta", - ]), + content: quest("Quests", "Plan the rocket app."), }, { path: "quest/m0/README.md", - content: quest("Beta", "Ship the first public beta.", [ - "- [Landing page](/quest/m0/landing.md) - explain the app", - "- [Passkey sign-in](/quest/m0/sign-in.md) - sign in without a password", - "- [Getting started](/quest/m0/docs.md) - a first-run guide", - "- [Crash telemetry](/quest/m0/telemetry.md) - learn about crashes", - "- [ZIP export](/quest/m0/export.md) - take your data with you", - "- [ZIP import](/quest/m0/import.md) - bring your data back", - ]), + content: quest("Beta", "Ship the first public beta."), }, { path: "quest/m0/import.md", content: quest("[S] Import a project from a ZIP archive", "Restore it.") }, { path: "quest/m0/landing.md", content: quest("[S] Build the landing page", "Explain the app.") }, @@ -63,12 +53,7 @@ export function world(): World { { path: "quest/m0/export.md", content: quest("[S] Export a project as a ZIP archive", "Take your data.") }, { path: "quest/m1/README.md", - content: quest("Later", "Work after the beta.", [ - "- [Offline mode](/quest/m1/offline.md) - keep working without a network", - "- [Themes](/quest/m1/themes.md) - custom colors", - "- [Search](/quest/m1/search.md) - find anything", - "- [Fonts](/quest/m1/fonts.md) - choose the editor font", - ]), + content: quest("Later", "Work after the beta."), }, { path: "quest/m1/fonts.md", content: quest("[S] Choose the editor font", "Read comfortably.") }, { path: "quest/m1/search.md", content: quest("[S] Search across projects", "Find anything.") }, @@ -201,13 +186,11 @@ export function world(): World { files: [ { path: "quest/README.md", - content: quest("Quests", "Retire the old site.", ["- [M0: Retire](/quest/m0/README.md) - retire it"]), + content: quest("Quests", "Retire the old site."), }, { path: "quest/m0/README.md", - content: quest("Retire", "Retire the old site.", [ - "- [Clean up](/quest/m0/cleanup.md) - remove old pages", - ]), + content: quest("Retire", "Retire the old site."), }, { path: "quest/m0/cleanup.md", content: quest("[S] Remove the old pages", "Nothing links to them.") }, ], diff --git a/cloudflare/src/board/model.ts b/cloudflare/src/board/model.ts index fd0c2da2..d2b99765 100644 --- a/cloudflare/src/board/model.ts +++ b/cloudflare/src/board/model.ts @@ -9,7 +9,6 @@ import { branchQuest, children, comparePaths, - entries, isEpic, parse, permanent, @@ -45,7 +44,7 @@ export type Quest = { /** Finished work out of all work, by count and weighted by difficulty. */ export type Progress = { done: number; total: number; weight: number; totalWeight: number }; -/** A milestone or epic: a directory of quests, listed in priority order. */ +/** A milestone or epic: a directory of quests, listed in path order. */ export type Group = { path: string; href: string; @@ -171,7 +170,7 @@ export function readBoard(project: Project, jobs: ReadonlyMap = const progress = (path: string): Progress => { const under = (p: string) => p.startsWith(`${dir(path)}/`); - const remaining = parsed.filter((doc) => under(doc.path) && !isEpic(doc)); + const remaining = parsed.filter((doc) => under(doc.path) && !isEpic(parsed, doc)); const done = finishedUnder(path); const weigh = (titles: string[]) => titles.reduce((sum, text) => sum + WEIGHTS[title(text).size ?? "XS"], 0); const weight = weigh(done.map((c) => c.title)); @@ -183,21 +182,17 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; }; - // A group's items are its children in priority order, then anything under - // it that no README lists, so nothing in the tree goes unseen. + // A group's items are its children: the quests in its directory, in path order. const seen = new Set([ROOT]); const group = (doc: Doc): Group => { seen.add(doc.path); - const listed = children(doc).filter((path) => docs.has(path) && !seen.has(path)); - const base = dir(doc.path); - const loose = parsed - .map((d) => d.path) - .filter((path) => !listed.includes(path) && !seen.has(path) && direct(base, path)); - const items = [...listed, ...loose].flatMap((path): Item[] => { + const items = children(parsed, doc).flatMap((path): Item[] => { if (seen.has(path)) return []; seen.add(path); const child = docs.get(path)!; - return isEpic(child) ? [{ kind: "epic", epic: group(child) }] : [{ kind: "quest", quest: quest(child) }]; + return isEpic(parsed, child) + ? [{ kind: "epic", epic: group(child) }] + : [{ kind: "quest", quest: quest(child) }]; }); return { path: doc.path, @@ -208,28 +203,26 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; }; - const root = docs.get(ROOT); - const milestonePaths = [...(root ? children(root) : []), ...parsed.map((doc) => doc.path)].filter( - (path, i, all) => path !== ROOT && permanent(path) && docs.has(path) && all.indexOf(path) === i, - ); - const milestones = milestonePaths.map((path): Milestone => { - const segment = path.split("/")[1]; - return { - ...group(docs.get(path)!), - number: /^[a-z](\d+)$/.exec(segment)?.[1] ?? segment, - summary: lead(contents.get(path) ?? "", "Goal"), - }; - }); + const milestones = parsed + .filter((doc) => doc.path !== ROOT && permanent(doc.path)) + .map((doc): Milestone => { + const segment = doc.path.split("/")[1]; + return { + ...group(doc), + number: /^[a-z](\d+)$/.exec(segment)?.[1] ?? segment, + summary: lead(contents.get(doc.path) ?? "", "Goal"), + }; + }); // Quests outside every milestone still show, in a group of their own. - const rest = parsed.filter((doc) => !seen.has(doc.path) && !isEpic(doc)).map(quest); + const rest = parsed.filter((doc) => !seen.has(doc.path) && !isEpic(parsed, doc)).map(quest); if (rest.length > 0) { milestones.push({ path: "quest", href: questHref(project, ROOT), title: "Unsorted", number: "", - summary: "Quests that no milestone lists.", + summary: "Quests outside every milestone.", progress: { done: 0, total: rest.length, weight: 0, totalWeight: 0 }, items: rest.map((quest) => ({ kind: "quest", quest })), }); @@ -263,14 +256,6 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; } -/** Whether `path` sits directly in `dir`: a quest file, or an epic's README one level down. */ -function direct(dir: string, path: string): boolean { - const rest = path.slice(dir.length + 1); - if (!path.startsWith(`${dir}/`)) return false; - const parts = rest.split("/"); - return parts.length === 1 ? parts[0] !== "README.md" : parts.length === 2 && parts[1] === "README.md"; -} - /** Only the quests with this status, dropping epics left empty. */ export function only(items: Item[], kind: Status["kind"]): Item[] { return items.flatMap((item): Item[] => { diff --git a/cloudflare/src/board/pages.tsx b/cloudflare/src/board/pages.tsx index 283e21f5..4c526959 100644 --- a/cloudflare/src/board/pages.tsx +++ b/cloudflare/src/board/pages.tsx @@ -431,11 +431,6 @@ export function QuestPage(props: { board: Board; doc: Doc; content: string; user const heading = title(doc.title?.text ?? doc.path); const markdown = blobHref(project, doc.path); const required = entries(doc, "Required"); - const childPaths = new Set(group?.items.map((item) => (item.kind === "quest" ? item.quest.path : item.epic.path))); - const external = required.filter((entry) => { - const path = entry.target === null ? null : rooted(entry.target); - return path === null || !childPaths.has(path); - }); return (
@@ -457,11 +452,11 @@ export function QuestPage(props: { board: Board; doc: Doc; content: string; user if (section.heading === "Required") { return ( <> - {external.length > 0 && ( + {required.length > 0 && ( <>

Requires

    - {external.map((entry) => ( + {required.map((entry) => ( ))}
diff --git a/cloudflare/src/home.tsx b/cloudflare/src/home.tsx index eff3631e..f79226ef 100644 --- a/cloudflare/src/home.tsx +++ b/cloudflare/src/home.tsx @@ -37,7 +37,7 @@ people retry a failed download. const tree = `quest/ README.md # The roadmap m0/ - README.md # First milestone, in priority order + README.md # The first milestone export.md # Available download.md # Requires: export.md`; @@ -204,7 +204,7 @@ export function Home(props: { setup: string; board: Board }) {

Plan with your agent

/quest-plan asks the questions that turn an idea into scoped quests, with - dependencies, in priority order. + dependencies, in milestones by priority.

  • diff --git a/cloudflare/src/map.tsx b/cloudflare/src/map.tsx index 1bdeac48..afb8288d 100644 --- a/cloudflare/src/map.tsx +++ b/cloudflare/src/map.tsx @@ -1,4 +1,4 @@ -import { type Doc, entries, rooted } from "quest/core"; +import { type Doc, requires } from "quest/core"; import { type Milestone, type Board, @@ -30,15 +30,14 @@ export type Region = { milestone: Milestone; href: string; paths: Path[] }; * as everything it still holds. */ function steps(docs: Map): (path: string) => number { + const all = [...docs.values()]; const memo = new Map(); const step = (path: string): number => { const known = memo.get(path); if (known !== undefined) return known; // A cycle is a `quest check` failure; it must not hang the page. memo.set(path, 0); - const required = entries(docs.get(path)!, "Required") - .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((target): target is string => target !== null && docs.has(target)); + const required = requires(all, docs.get(path)!).filter((target) => docs.has(target)); const value = required.length === 0 ? 0 : 1 + Math.max(...required.map(step)); memo.set(path, value); return value; @@ -46,7 +45,7 @@ function steps(docs: Map): (path: string) => number { return step; } -/** The board's milestones as map regions, each path ordered by step, then priority. */ +/** The board's milestones as map regions, each path ordered by step, then path order. */ export function chart(board: Board): Region[] { const step = steps(board.docs); const ordered = (quests: Quest[]): Quest[] => @@ -56,8 +55,8 @@ export function chart(board: Board): Region[] { .map(({ quest }) => quest); return board.milestones.map((milestone) => { - // Paths keep the milestone's priority order. The quests it lists directly share - // one main path, placed where the first of them is listed. + // Paths keep the milestone's path order. The quests directly in it share one + // main path, placed where the first of them sorts. const loose = milestone.items.flatMap((item) => (item.kind === "quest" ? [item.quest] : [])); const main: Path = { title: "Main path", href: null, progress: null, waypoints: ordered(loose) }; const paths = milestone.items.flatMap((item): Path[] => { diff --git a/cloudflare/test/board.test.ts b/cloudflare/test/board.test.ts index b5e3f1d4..cc541f5d 100644 --- a/cloudflare/test/board.test.ts +++ b/cloudflare/test/board.test.ts @@ -5,11 +5,9 @@ import { type Board, blobHref, findDoc, findGroup, only, questHref, readBoard, t import type { Project } from "../src/board/project"; const docs: Record = { - "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [M0](/quest/m0/README.md) - first\n", - "quest/m0/README.md": - "# First release\n\n## Goal\n\nThe *first* release.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - grouped\n- [Solo](/quest/m0/solo.md) - alone\n", - "quest/m0/epic/README.md": - "# An epic\n\n## Goal\n\nGrouped work.\n\n## Required\n\n- [Ready](/quest/m0/epic/ready.md) - first\n- [Blocked](/quest/m0/epic/blocked.md) - second\n- [Taken](/quest/m0/epic/taken.md) - third\n- [Turned](/quest/m0/epic/turned.md) - fourth\n", + "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n", + "quest/m0/README.md": "# First release\n\n## Goal\n\nThe *first* release.\n", + "quest/m0/epic/README.md": "# An epic\n\n## Goal\n\nGrouped work.\n", "quest/m0/epic/ready.md": "# [S] Ready quest\n\n## Goal\n\nDo it.\n", "quest/m0/epic/blocked.md": "# [M] Blocked quest\n\n## Goal\n\nLater.\n\n## Required\n\n- [Ready](/quest/m0/epic/ready.md) - needs it\n", @@ -17,7 +15,7 @@ const docs: Record = { "# [XL] Taken quest\n\n## Goal\n\nMine.\n\n## Claim\n\n- Jane Doe (github:jdoe) on https://example.com/jdoe/repo since 2026-10-02\n", "quest/m0/epic/turned.md": "# [XS] Turned-in quest\n\n## Goal\n\nDone soon.\n", "quest/m0/solo.md": "# [L] Solo quest\n\n## Goal\n\nAlone.\n", - "quest/m0/loose.md": "# [S] Loose quest\n\n## Goal\n\nListed nowhere.\n", + "quest/m0/loose.md": "# [S] Loose quest\n\n## Goal\n\nNo blockers either.\n", }; function project(overrides: Partial = {}): Project { @@ -53,13 +51,13 @@ describe("board model", () => { expect(board.counts).toEqual({ available: 4, pending: 0, blocked: 1, "turn-in": 1, accepted: 0 }); }); - it("groups milestones and epics in priority order, then unlisted quests", () => { + it("groups milestones and epics by their directories, in path order", () => { const [milestone] = board.milestones; expect(milestone).toMatchObject({ number: "0", title: "First release", summary: "The first release." }); expect(milestone.items.map((item) => (item.kind === "quest" ? item.quest.path : item.epic.path))).toEqual([ "quest/m0/epic/README.md", - "quest/m0/solo.md", "quest/m0/loose.md", + "quest/m0/solo.md", ]); expect(trail(board, "quest/m0/epic/ready.md").map((group) => group.title)).toEqual([ "First release", diff --git a/cloudflare/test/core.test.ts b/cloudflare/test/core.test.ts index 2e384cd2..f5c1da72 100644 --- a/cloudflare/test/core.test.ts +++ b/cloudflare/test/core.test.ts @@ -6,7 +6,7 @@ import { describe, expect, it } from "vitest"; describe("quest/core", () => { it("checks a tree and finds ready work", () => { const docs = [ - parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](/quest/one.md)\n"), + parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n"), parse("quest/one.md", "# [S] One\n\n## Goal\n\nThe first quest.\n"), ]; const paths = new Set(docs.map((doc) => doc.path)); @@ -16,10 +16,7 @@ describe("quest/core", () => { it("reports a quest and an epic that share a path", () => { const docs = [ - parse( - "quest/README.md", - "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [Quest](/quest/one.md)\n- [Epic](/quest/one/README.md)\n", - ), + parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n"), parse("quest/one.md", "# [S] One\n\n## Goal\n\nA quest.\n"), parse("quest/one/README.md", "# [S] Epic\n\n## Goal\n\nAn epic's remaining work.\n"), ]; diff --git a/cloudflare/test/jobs.test.ts b/cloudflare/test/jobs.test.ts index 64b3c535..ed9aea6c 100644 --- a/cloudflare/test/jobs.test.ts +++ b/cloudflare/test/jobs.test.ts @@ -1113,18 +1113,11 @@ describe("job routes", () => { }); it("starts an epic on its README branch while a child's branch is claimed", async () => { - // The epic's last listed child merged, leaving its own work; another quest under it is claimed. + // The epic's last child merged, leaving its own work, and that child's branch still holds a claim. const documents = [ - { - path: "quest/README.md", - content: "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - }, - { - path: "quest/m0/README.md", - content: "# First\n\n## Goal\n\nShip.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, + { path: "quest/m0/README.md", content: "# First\n\n## Goal\n\nShip.\n" }, { path: "quest/m0/epic/README.md", content: "# [S] Epic\n\n## Goal\n\nThe epic's own work.\n" }, - { path: "quest/m0/epic/child.md", content: "# [S] Child\n\n## Goal\n\nClaimed.\n" }, ]; await db .prepare( @@ -1132,7 +1125,6 @@ describe("job routes", () => { ) .bind(JSON.stringify(documents), JSON.stringify(["quest/m0/epic/child"])) .run(); - expect((await post("", { workflow: "start", target: "quest/m0/epic/child.md" })).status).toBe(409); expect((await post("", { workflow: "start", target: "quest/m0/epic/README.md" })).status).toBe(201); const [job] = await store.listJobs(db, 10); expect(job).toMatchObject({ diff --git a/cloudflare/test/links.test.ts b/cloudflare/test/links.test.ts index d1621592..3491a90a 100644 --- a/cloudflare/test/links.test.ts +++ b/cloudflare/test/links.test.ts @@ -10,11 +10,7 @@ const project: Project = { commit: "a".repeat(40), date: "2026-10-07", documents: [ - { - path: "quest/README.md", - content: - "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](/quest/x%23y.md)\n- [Two](/quest/two.md)\n", - }, + { path: "quest/README.md", content: "# Quests\n\n## Goal\n\nShip it.\n" }, { path: "quest/x#y.md", content: "# [S] One\n\n## Goal\n\nFirst.\n" }, { path: "quest/two.md", diff --git a/cloudflare/test/map.test.ts b/cloudflare/test/map.test.ts index 7514c203..77d98486 100644 --- a/cloudflare/test/map.test.ts +++ b/cloudflare/test/map.test.ts @@ -4,15 +4,13 @@ import type { Project } from "../src/board/project"; import { QuestMap, chart } from "../src/map"; const docs: Record = { - "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [M0](/quest/m0/README.md) - first\n", - "quest/m0/README.md": - "# First release\n\n## Goal\n\nShip.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - grouped\n- [Finale](/quest/m0/finale.md) - last\n- [Solo](/quest/m0/solo.md) - alone\n", - // The epic lists its blocked quest first; the map still puts it after its blocker. - "quest/m0/epic/README.md": - "# An epic\n\n## Goal\n\nGrouped.\n\n## Required\n\n- [Later](/quest/m0/epic/later.md) - second\n- [First](/quest/m0/epic/first.md) - first\n- [Other](/quest/m0/epic/other.md) - third\n", + "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n", + "quest/m0/README.md": "# First release\n\n## Goal\n\nShip.\n", + "quest/m0/epic/README.md": "# An epic\n\n## Goal\n\nGrouped.\n", + // The blocked quest sorts first by path; the map still puts it after its blocker. "quest/m0/epic/later.md": - "# [M] Later\n\n## Goal\n\nLater.\n\n## Required\n\n- [First](/quest/m0/epic/first.md) - needs it\n", - "quest/m0/epic/first.md": "# [S] First\n\n## Goal\n\nFirst.\n", + "# [M] Later\n\n## Goal\n\nLater.\n\n## Required\n\n- [First](/quest/m0/epic/start.md) - needs it\n", + "quest/m0/epic/start.md": "# [S] First\n\n## Goal\n\nFirst.\n", "quest/m0/epic/other.md": "# [XS] Other\n\n## Goal\n\nOther.\n", "quest/m0/solo.md": "# [L] Solo\n\n## Goal\n\nAlone.\n", // Requiring an epic puts a quest after everything the epic still holds. @@ -39,15 +37,15 @@ describe("quest map", () => { expect(region.href).toBe("/repos/demo#m0"); }); - it("draws epics and the milestone's own quests as paths in priority order", () => { + it("draws epics and the milestone's own quests as paths in path order", () => { expect(region.paths.map((path) => path.title)).toEqual(["An epic", "Main path"]); expect(region.paths[0].href).toBe("/repos/demo/quest/m0/epic/README"); }); - it("orders each path by what it requires, then by priority", () => { + it("orders each path by what it requires, then by path", () => { const titles = region.paths.map((path) => path.waypoints.map((quest) => quest.title)); expect(titles).toEqual([ - ["First", "Other", "Later"], + ["Other", "First", "Later"], ["Solo", "Finale"], ]); }); @@ -89,9 +87,9 @@ describe("waypoint status", () => { it("survives a Required cycle", async () => { const html = await render({ documents: [ - ...project.documents.filter((doc) => doc.path !== "quest/m0/epic/first.md"), + ...project.documents.filter((doc) => doc.path !== "quest/m0/epic/start.md"), { - path: "quest/m0/epic/first.md", + path: "quest/m0/epic/start.md", content: "# [S] First\n\n## Goal\n\nFirst.\n\n## Required\n\n- [Later](/quest/m0/epic/later.md) - loop\n", }, diff --git a/cloudflare/test/project-fixtures.ts b/cloudflare/test/project-fixtures.ts index bdd0264c..e2334f92 100644 --- a/cloudflare/test/project-fixtures.ts +++ b/cloudflare/test/project-fixtures.ts @@ -13,10 +13,7 @@ const db = env.DB; export const commit = "a".repeat(40); export const head = "d".repeat(40); export const documents = [ - { - path: "quest/README.md", - content: "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [First](/quest/first.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, { path: "quest/first.md", content: "# [S] First\n\n## Goal\n\nBuild first.\n" }, ]; diff --git a/cloudflare/test/projects.test.ts b/cloudflare/test/projects.test.ts index 2487f9e5..1abc3de6 100644 --- a/cloudflare/test/projects.test.ts +++ b/cloudflare/test/projects.test.ts @@ -35,11 +35,7 @@ function blobOid(content: string) { return createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"); } const documents = [ - { - path: "quest/README.md", - content: - "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [First](/quest/first.md)\n- [Second](/quest/second.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, { path: "quest/first.md", content: "# [S] First\n\n## Goal\n\nBuild first.\n" }, { path: "quest/second.md", @@ -569,13 +565,7 @@ describe("project enrollment", () => { path: `quest/quest-${i}.md`, content: `# [S] Quest ${i}\n\n## Goal\n\nBuild it.\n`, })); - const snapshot = [ - { - path: "quest/README.md", - content: `# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n${quests.map((q, i) => `- [Quest ${i}](/${q.path})`).join("\n")}\n`, - }, - ...quests, - ]; + const snapshot = [{ path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, ...quests]; const { service, calls } = github({ documents: snapshot, subrequestLimit: 50 }); // Enrollment routes resolve the submitted repository before enabling it. await service.resolveRepository(repo.owner, repo.name); diff --git a/examples/export/quest/README.md b/examples/export/quest/README.md index fc34c27b..21cc5cb6 100644 --- a/examples/export/quest/README.md +++ b/examples/export/quest/README.md @@ -4,7 +4,3 @@ Illustrate a two-quest feature: build a CSV endpoint, then add a download button. These are sample plans for an imaginary application, not Quest's own backlog. - -## Required - -- [M0: Download your data](/quest/m0/README.md) - let users export their own records diff --git a/examples/export/quest/m0/README.md b/examples/export/quest/m0/README.md index 8d8a6de3..bd063c47 100644 --- a/examples/export/quest/m0/README.md +++ b/examples/export/quest/m0/README.md @@ -3,8 +3,3 @@ ## Goal Users can download their records as a CSV file from the settings page. - -## Required - -- [CSV endpoint](/quest/m0/export.md) - return the signed-in user's records as CSV -- [Download button](/quest/m0/download.md) - make the export available in settings diff --git a/quest/m0/README.md b/quest/m0/README.md index fa0cc7c9..ac8ce4b8 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -51,6 +51,10 @@ Decided 2026-10-30 (user, /quest-plan), replacing "First public release": The land work is what moq-dev's repositories use every day, and the maintainer ranked it first in the 2026-10-30 and 2026-11-01 sessions. + Superseded 2026-11-05 (user, /quest-plan, the + [token waste](/quest/m0/token-waste/README.md) audit): an epic's children + are its directory, so list order no longer ranks work within m0; + `quest unblocked` ranks by milestone, then downstream impact, then path. - How do moq-dev's repositories land? Decided 2026-11-01 (maintainer, /quest-plan), reversing the 2026-10-26 move to a batched gate: - ✅ Through GitHub's merge queue again, one PR at a time, with no batching diff --git a/quest/m0/model-routing/pins.md b/quest/m0/model-routing/pins.md index c60111e5..00440584 100644 --- a/quest/m0/model-routing/pins.md +++ b/quest/m0/model-routing/pins.md @@ -18,9 +18,11 @@ repository uses the same settings, so nothing in them changes but the pin. - Neither repository's `AGENTS.md` overrides the tables. - Each bump runs `quest check --fix` with the new `quest` and commits the result, since a `quest` past - [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518) rejects - epic READMEs that still list their children (coordinator, 2026-11-05, - follow-up of #518; [Pin sync](/quest/m0/pin-sync.md) does the same for + [Epics list no children](/quest/m0/token-waste/child-lists.md) rejects + epic READMEs that still list their children, and its `--fix` strips them + (coordinator, 2026-11-05, follow-up of + [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518), which + accepts both formats; [Pin sync](/quest/m0/pin-sync.md) does the same for its automated bumps). ## Required diff --git a/quest/m0/token-waste/child-lists.md b/quest/m0/token-waste/child-lists.md index 3c35b226..8f059249 100644 --- a/quest/m0/token-waste/child-lists.md +++ b/quest/m0/token-waste/child-lists.md @@ -1,17 +1,18 @@ -# [L] Epics list no children +# [S] Epics list no children ## Goal -An epic's children are the quests in its directory, and its `Required` -section lists only the work that blocks it. Finishing a quest deletes its -file and edits no epic or milestone README, so PRs that finish sibling -quests stop conflicting. `quest check --fix` strips the old child lists from -a repository's tree. +This repository's epic and milestone READMEs no longer list their children, +and `quest check` rejects a README `Required` entry naming a quest in its own +directory. Finishing a quest then deletes its file and edits no README, so +PRs that finish sibling quests stop conflicting there. ## Plan Decided 2026-11-05 (user, /quest-plan, the -[token waste](/quest/m0/token-waste/README.md) audit). +[token waste](/quest/m0/token-waste/README.md) audit): an epic's children are +the quests in its directory, its `Required` lists only what blocks it, and +path order replaces list order. Measured, moq-dev PRs created 2026-10-06 to 11-05: @@ -19,26 +20,25 @@ Measured, moq-dev PRs created 2026-10-06 to 11-05: milestone READMEs as a group by 45%; in moq-dev/rust2, `quest/m3/README.md` by 290 of 585. - GitHub's merge queue cannot run quest's merge driver and ejected 723 PRs - for conflicts. The [queue watcher](/quest/m0/queue-watcher/README.md) - re-merges such a PR with the driver since - [moq-dev/quest#389](https://github.com/moq-dev/quest/pull/389), but each - ejection still costs a requeue and a CI run, and the rate after 11-01 - stayed at 0.13 per merged PR. - -Decision prompts, chosen options marked ✅: - -- Ordering: ✅ drop the ordering. The maintainer proposed it. - `quest unblocked` already ranks by milestone, then downstream impact, and - only then by list order (`src/core/unblocked.ts`), so order is only a - tiebreak. Path order replaces it. -- Scope: ✅ every epic (rejected: milestones only; unordered lists). The - directory already is the tree and `Required` already holds blockers, so - epics stay the graph they are minus the copy of the directory. A child - that must precede a sibling becomes an explicit blocker in `Required`. - Parallel siblings spawned from one epic conflict on its README today, as - milestones do. - -The guide's Model, Format, and Creation sections, the skills that rank or -place work (`/quest-plan`, `/quest-audit`, `/quest-spawn`, -`/quest-recurring`, `/quest-import`), and `quest tree`'s output change with -it. The merge driver keeps resolving the blocker lists that remain. + for conflicts. + +Decided 2026-11-07 (user): ✅ stage it in two PRs (rejected: admin-bypass +merge once; skip; delete). The merge queue checks a PR with the CLI built +from its base, which rejected the migrated tree. +[moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518) shipped +directory membership with a validator that accepts both formats: an epic's +`Required` link to a quest it holds is allowed and counts once, as a child. +This quest is the second PR: + +- Make `remove()` (`src/core/edit.ts`) drop every epic's `Required` link to a + quest it holds, so `quest check --fix`, `quest rm`, and the land daemon's + base-merge prune strip old child lists, and let `quest check --fix` run with + no history to read. #518's commit caa32fc3 has both, with tests. +- Run `quest check --fix` on this tree and on prose that describes the lists. +- Turn `requires X, which this epic holds` into a `quest check` error. +- `assets/land-fix.md` stops adding the flaky quest's link to + `quest/m0/flaky/README.md`, and + [the flaky quest](/quest/m0/queue-watcher/flaky-quest.md) says so. +- The PR is breaking: other repositories migrate with `quest check --fix` on + their pin bump past it, as + [moq-dev pins](/quest/m0/model-routing/pins.md) describes. diff --git a/quest/m1/model-check.md b/quest/m1/model-check.md index 959dce50..7fdf5f55 100644 --- a/quest/m1/model-check.md +++ b/quest/m1/model-check.md @@ -93,9 +93,9 @@ work it was routed for: which passes `--ignore-user-config`) nor `quest agent` used Codex hooks, and `quest init` installs none. Recheck if either starts to. - The PR that finishes this run creates the next milestone's run the same - way: listed in that milestone's `Required`, requiring this milestone's - README, carrying forward the model ids and efforts it found, the routing - tallies as a baseline, and anything to check first. + way: in that milestone's directory, requiring this milestone's README, + carrying forward the model ids and efforts it found, the routing tallies + as a baseline, and anything to check first. ## Required diff --git a/scripts/lifecycle-check.mjs b/scripts/lifecycle-check.mjs index 44ff1f9f..04773be3 100644 --- a/scripts/lifecycle-check.mjs +++ b/scripts/lifecycle-check.mjs @@ -84,16 +84,8 @@ try { for (const skill of skills) assertFile(root, `${dir}/quest-${skill}/SKILL.md`, run(root, "skill", skill, "--stub")); } - write( - root, - "quest/README.md", - "# Lifecycle\r\n\r\n## Goal\r\n\r\nKeep plans.\r\n\r\n## Required\r\n\r\n- [First](/quest/m0/README.md)\r\n", - ); - write( - root, - "quest/m0/README.md", - "# First\r\n\r\n## Goal\r\n\r\nA milestone.\r\n\r\n## Required\r\n\r\n- [One](/quest/m0/one.md)\r\n- [Two](/quest/m0/two.md)\r\n", - ); + write(root, "quest/README.md", "# Lifecycle\r\n\r\n## Goal\r\n\r\nKeep plans.\r\n"); + write(root, "quest/m0/README.md", "# First\r\n\r\n## Goal\r\n\r\nA milestone.\r\n"); write(root, "quest/m0/one.md", "# [S] One\r\n\r\n## Goal\r\n\r\nFirst.\r\n"); write( root, diff --git a/src/cli/main.ts b/src/cli/main.ts index 23282c8e..3b722046 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -250,7 +250,7 @@ export function main(argv: string[], out: Output): number | Promise { .command("unblocked") .summary("Rank ready quests, or print what blocks one quest") .description( - "Rank ready quests by milestone priority, distinct transitive dependents, then tree order. " + + "Rank ready quests by milestone priority, distinct transitive dependents, then path order. " + "Given a path, print what blocks that quest instead.\n\n" + "Counts exclude structural epic membership. Other prerequisites may remain for dependents. " + "Invalid trees fail before printing a ranking. Prints a count and path per line; --json prints an " + @@ -337,7 +337,7 @@ export function main(argv: string[], out: Output): number | Promise { .description( "List every quest with a ## Waiting section and every open draft PR handed back with one (or the " + "older ## Decisions needed): those waiting on the maintainer first, then milestone priority, distinct " + - "transitive dependents as quest unblocked counts them, ready before blocked, then tree order, with " + + "transitive dependents as quest unblocked counts them, ready before blocked, then path order, with " + "drafts after quests by PR number. A draft ranks as the quest its branch carries, or last when it " + "carries none. Each item opens with who acts, Maintainer: or an outside party such as moq-dev/moq:, " + "followed by the condition and how to check or advance it. A draft's item without a party, and every " + @@ -1211,8 +1211,9 @@ export function main(argv: string[], out: Output): number | Promise { "root-absolute link to it under quest/. The change is staged.\n\n" + "Refuses the root epic and milestones, which are permanent. Refuses outside a git work tree, when " + "the destination exists, and while a moved quest has a claim branch or open PR on origin, or on " + - "the upstream that holds origin's claims (see quest start), since the old branch would no longer name it. Moving a " + - "quest into or out of an epic changes which epic lists it; the check afterwards reports what to fix.\n\n" + + "the upstream that holds origin's claims (see quest start), since the old branch would no longer name it. A " + + "quest belongs to the epic whose directory holds it, so moving it into another directory moves it " + + "into that epic.\n\n" + "Prints R for the move and M for each edited document. Mentions of the old path that are not links, " + "or are outside quest/, are reported on stderr and left alone. Runs quest check on the result and " + "exits 1 if it fails.", @@ -1235,8 +1236,8 @@ export function main(argv: string[], out: Output): number | Promise { .description( "Delete a quest, or an epic and the quests under it, with git rm, and drop every Required, Related, " + "or Closes entry that links to it, with any heading left empty. It also drops every Required link to a " + - "finished milestone, one whose README has no Required left, except the root's own listing. The change " + - "is staged.\n\n" + + "finished milestone, one whose directory holds no other quest and whose README has no Required left, " + + "except the root's own listing. The change is staged.\n\n" + "Refuses outside a git work tree. An epic is its directory or README; removing one that holds other " + "quests requires -r. The root epic and milestones are permanent.\n\n" + "Prints D for each deleted quest and M for each edited document. Mentions that are not list entries, " + diff --git a/src/core/doc.ts b/src/core/doc.ts index a179dcc9..bba071d5 100644 --- a/src/core/doc.ts +++ b/src/core/doc.ts @@ -16,7 +16,7 @@ import { gfmTableFromMarkdown } from "mdast-util-gfm-table"; import { gfmStrikethrough } from "micromark-extension-gfm-strikethrough"; import { gfmTable } from "micromark-extension-gfm-table"; -import { depth, escapes, fileName, join, normalize, parent } from "./path"; +import { comparePaths, depth, escapes, fileName, join, normalize, parent } from "./path"; /** * Where a link sits inside its `## Section`, which is what separates a @@ -47,7 +47,7 @@ export interface Link { span: [number, number]; } -/** One top-level list entry: the shape a `Required` child or blocker has. */ +/** One top-level list entry: the shape a `Required` blocker has. */ export interface Entry { /** 1-based source line, for findings. */ line: number; @@ -173,26 +173,48 @@ export function owner(path: string): string { } /** - * The `Required` entries that sit directly under a README's directory: the - * epic's children, in priority order. Every other entry is a blocker like any - * quest's, and a quest that is not a README has no children. + * Whether the epic README `readme` holds `path`: it sits anywhere under the + * epic's directory, so the epic already waits for it. */ -export function children(doc: Doc): string[] { +export function holds(readme: string, path: string): boolean { + return isReadme(readme) && path !== readme && path.startsWith(`${parent(readme)}/`); +} + +/** + * An epic's children: the quests directly in its directory and the READMEs of + * the epics one level down, in path order. A quest that is not a README has + * none. + */ +export function children(docs: readonly Doc[], doc: Doc): string[] { if (!isReadme(doc.path)) return []; const dir = parent(doc.path); - return entries(doc, "Required") - .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((child): child is string => child !== null && owner(child) === dir); + return docs + .map((d) => d.path) + .filter((path) => owner(path) === dir) + .sort(comparePaths); } /** - * An epic is a `README.md` that still requires a child. Any other README is - * what an epic becomes when its last child merges: the epic's own remaining - * work, executed like any other quest. The root and the milestones are the - * exception. + * An epic is a `README.md` whose directory still holds another quest. Any + * other README is what an epic becomes when its last child merges: the epic's + * own remaining work, executed like any other quest. The root and the + * milestones are the exception. */ -export function isEpic(doc: Doc): boolean { - return isReadme(doc.path) && (children(doc).length > 0 || permanent(doc.path)); +export function isEpic(docs: readonly Doc[], doc: Doc): boolean { + return permanent(doc.path) || docs.some((d) => holds(doc.path, d.path)); +} + +/** + * What must finish before `doc`: its `Required` quests, then, for an epic, its + * children. An epic's `Required` link to one of its children, left from a tree + * that listed them, counts once. + */ +export function requires(docs: readonly Doc[], doc: Doc): string[] { + const kids = children(docs, doc); + const required = entries(doc, "Required") + .map((entry) => (entry.target === null ? null : rooted(entry.target))) + .filter((target): target is string => target !== null && !kids.includes(target)); + return [...required, ...kids]; } /** @@ -223,7 +245,7 @@ export function resolve(docPath: string, target: string): string | null { /** * A root-absolute target as a repository-relative path, or `null` if it is not - * root-absolute or cannot resolve safely. The index and cycle walk use the same + * root-absolute or cannot resolve safely. The rules and cycle walk use the same * decoded, normalized path as link validation. */ export function rooted(target: string): string | null { diff --git a/src/core/index.ts b/src/core/index.ts index c3817b34..6ed68e31 100644 --- a/src/core/index.ts +++ b/src/core/index.ts @@ -22,6 +22,7 @@ export { parse, permanent, questBranch, + requires, resolve, rooted, SIZES, diff --git a/src/core/path.ts b/src/core/path.ts index 47949f66..e8b7a178 100644 --- a/src/core/path.ts +++ b/src/core/path.ts @@ -60,14 +60,25 @@ export function escapes(path: string): boolean { } /** - * Order paths component by component, so `a/b.md` sorts before `a-b.md` the - * way a directory listing walks them, rather than by raw characters. + * Path order, which is also the quest tree's order: component by component, so + * `a/b.md` sorts before `a-b.md` the way a directory listing walks them, with a + * directory's `README.md` first, since an epic precedes its children, and each + * run of digits compared by value, so the milestone `m10` follows `m9`. */ export function comparePaths(a: string, b: string): number { const left = a.split("/"); const right = b.split("/"); for (let i = 0; i < Math.min(left.length, right.length); i++) { - if (left[i] !== right[i]) return left[i] < right[i] ? -1 : 1; + if (left[i] === right[i]) continue; + if (left[i] === "README.md" || right[i] === "README.md") return left[i] === "README.md" ? -1 : 1; + const [x, y] = [numbered(left[i]), numbered(right[i])]; + if (x !== y) return x < y ? -1 : 1; + return left[i] < right[i] ? -1 : 1; } return left.length - right.length; } + +/** A name with each run of digits zero-padded, so comparing two compares their numbers by value. */ +function numbered(name: string): string { + return name.replace(/\d+/g, (digits) => digits.padStart(20, "0")); +} diff --git a/src/core/ready.ts b/src/core/ready.ts index f152b586..8d8e4d8c 100644 --- a/src/core/ready.ts +++ b/src/core/ready.ts @@ -1,5 +1,5 @@ -// Whether a quest can be started, read from the same `Required` section -// the rules validate. +// Whether a quest can be started, read from the same `Required` sections and +// epic directories the rules validate. // // Readiness is a property of the tree alone, which is what makes it cheap and // deterministic: a finished quest is deleted, so a blocker that still resolves @@ -7,9 +7,8 @@ // coherent, and already done by some other PR - and answering it means asking // the forge, so it belongs to the flow that is already talking to it. -import { type Doc, type Entry, children, entries, has, isEpic, rooted } from "./doc"; +import { type Doc, children, entries, has, isEpic, rooted } from "./doc"; import { comparePaths, normalize } from "./path"; -import { ROOT } from "./rules"; /** One thing standing between a quest and being started. */ export interface Blocker { @@ -38,9 +37,12 @@ export function renderBlocker(blocker: Blocker, depth = 0): string[] { return [`${" ".repeat(depth)}${label(blocker)}`, ...blocker.blockers.flatMap((b) => renderBlocker(b, depth + 1))]; } -/** What blocks `doc`, a required epic expanded into the quests it still holds. Empty means ready. */ +/** + * What blocks `doc`: its `Required` entries, then, for an epic, its children, + * each epic among them expanded into the quests it still holds. Empty means ready. + */ export function blockers(docs: Doc[], doc: Doc): Blocker[] { - return expand(new Map(docs.map((d) => [d.path, d])), doc, [doc.path]); + return expand(docs, new Map(docs.map((d) => [d.path, d])), doc, [doc.path]); } /** @@ -55,30 +57,15 @@ export function lookup(docs: Doc[], path: string): Doc | null { return null; } -/** - * Every document's path in tree order: the root's `Required` walked depth - * first, each epic before its children, then any document no epic lists, by - * path. - */ +/** Every document's path in tree order, which is path order: each epic before its children. */ export function treeOrder(docs: Doc[]): string[] { - const sorted = [...docs].sort((a, b) => comparePaths(a.path, b.path)); - const remaining = new Map(sorted.map((doc) => [doc.path, doc])); - const pending = [ROOT]; - const order: string[] = []; - for (let path = pending.pop(); path !== undefined; path = pending.pop()) { - const doc = remaining.get(path); - if (!doc) continue; - remaining.delete(path); - order.push(path); - if (isEpic(doc)) pending.push(...children(doc).reverse()); - } - return [...order, ...remaining.keys()]; + return docs.map((doc) => doc.path).sort(comparePaths); } /** * Every quest that can be started now, in tree order. * - * An epic is not listed while it still requires children; a README with + * An epic is not listed while its directory holds other quests; a README with * none left is the epic's own remaining work and lists like any other quest. * A quest is ready when it has no `## Required` heading. */ @@ -86,17 +73,18 @@ export function ready(docs: Doc[]): string[] { const byPath = new Map(docs.map((doc) => [doc.path, doc])); return treeOrder(docs).filter((path) => { const doc = byPath.get(path)!; - return !isEpic(doc) && !has(doc, "Required"); + return !isEpic(docs, doc) && !has(doc, "Required"); }); } -/** The blockers of one document: its `Required` entries, which for an epic include its children. */ -function expand(byPath: Map, doc: Doc, stack: string[]): Blocker[] { +/** The blockers of one document: its `Required` entries, then an epic's children. */ +function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[]): Blocker[] { const found: Blocker[] = []; // A heading left standing after its last blocker still reads as blocked to // everything that greps for it, including `quest check`, which reports it. // Calling it ready here would make this the one tool that disagrees. const required = entries(doc, "Required"); + const kids = children(docs, doc); if (has(doc, "Required") && required.length === 0) { found.push({ path: null, @@ -104,26 +92,29 @@ function expand(byPath: Map, doc: Doc, stack: string[]): Blocker[] blockers: [], }); } - for (const entry of required) found.push(blocker(byPath, entry, stack)); + for (const entry of required) { + // A bullet that does not open with a link into the tree is invalid, and + // nothing here can clear it, so it is a blocker with nothing under it. + const target = entry.target === null ? null : rooted(entry.target); + // An old child list's entry is listed below, with the children. + if (target !== null && kids.includes(target)) continue; + found.push(blocker(docs, byPath, target !== null && byPath.has(target) ? target : null, entry.text, stack)); + } + for (const child of kids) found.push(blocker(docs, byPath, child, child, stack)); return found; } -function blocker(byPath: Map, entry: Entry, stack: string[]): Blocker { - // A bullet that does not open with a link into the tree is invalid, and - // nothing here can clear it, so it is a blocker with nothing under it. - const target = entry.target === null ? null : rooted(entry.target); - const path = target !== null && byPath.has(target) ? target : null; - +function blocker(docs: Doc[], byPath: Map, path: string | null, text: string, stack: string[]): Blocker { // Only an epic expands. A required QUEST is the blocker itself, and its // own chain is the answer to running this on that quest instead; printing // it here buries the entries that were asked for under a repeated subtree. // The stack guard is for a tree nobody has run `quest check` on yet, where an - // epic listing an ancestor must print rather than recurse forever. + // epic requiring an ancestor must print rather than recurse forever. let nested: Blocker[] = []; - if (path !== null && isEpic(byPath.get(path)!) && !stack.includes(path)) { + if (path !== null && isEpic(docs, byPath.get(path)!) && !stack.includes(path)) { stack.push(path); - nested = expand(byPath, byPath.get(path)!, stack); + nested = expand(docs, byPath, byPath.get(path)!, stack); stack.pop(); } - return { path, text: entry.text, blockers: nested }; + return { path, text, blockers: nested }; } diff --git a/src/core/rules.ts b/src/core/rules.ts index 11783036..45d0dded 100644 --- a/src/core/rules.ts +++ b/src/core/rules.ts @@ -6,9 +6,9 @@ // tree. // // The whole tree is validated on every run, never just the changed files: the -// link graph and the epic index are global, so completing one quest breaks -// files the diff never mentions. That is not hypothetical - it is how the index -// entry for a completed quest survived a rebase that produced no conflict at +// link graph and the epic directories are global, so completing one quest +// breaks files the diff never mentions. That is not hypothetical - it is how a +// link to a completed quest survived a rebase that produced no conflict at // all. import { @@ -16,11 +16,12 @@ import { type Entry, entries, has, + holds, isEpic, - children, owner, permanent, questBranch, + requires, resolve, rooted, size, @@ -81,12 +82,12 @@ export function check(docs: Doc[], exists: (path: string) => boolean): Finding[] const known = new Set(docs.map((d) => d.path)); for (const doc of docs) { - headings(found, doc); + headings(found, docs, doc); links(found, exists, known, doc); } collisions(found, known, docs); - index(found, known, docs); + membership(found, known, docs); milestones(found, docs); cycles(found, docs); @@ -115,8 +116,8 @@ function collisions(found: Finding[], known: Set, docs: Doc[]) { } } -function headings(found: Finding[], doc: Doc) { - if (!isEpic(doc)) { +function headings(found: Finding[], docs: Doc[], doc: Doc) { + if (!isEpic(docs, doc)) { if (size(doc) === null) found.push({ path: doc.path, line: null, message: "quest title must be '# [XS|S|M|L|XL] Title'" }); } @@ -207,19 +208,27 @@ function links(found: Finding[], exists: (path: string) => boolean, known: Set, docs: Doc[]) { - const listed = new Set(); - +function membership(found: Finding[], known: Set, docs: Doc[]) { for (const doc of docs) { - for (const child of children(doc)) listed.add(child); + const epic = join(owner(doc.path), "README.md"); + // The root epic is permanent and has nothing above it. + if (doc.path !== ROOT && !known.has(epic)) { + found.push({ + path: doc.path, + line: null, + message: `sits in ${owner(doc.path)}, which has no README.md; every directory under quest/ is an epic, so add its README or move the quest`, + }); + } const seen = new Set(); for (const entry of entries(doc, "Required")) { @@ -238,23 +247,13 @@ function index(found: Finding[], known: Set, docs: Doc[]) { seen.add(target); } } - - for (const doc of docs) { - // The root epic is permanent and has nothing above it to list it. - if (doc.path === ROOT || listed.has(doc.path)) continue; - found.push({ - path: doc.path, - line: null, - message: `not listed in ${join(owner(doc.path), "README.md")}'s '## Required'; an unlisted quest is unreachable`, - }); - } } /** * A link to a finished milestone is removed. Milestones are permanent, so * unlike a finished quest, which is deleted, the link would keep resolving and - * block its quest forever. A milestone is finished once its README has no - * `## Required`, which counts blockers outside its own directory too. + * block its quest forever. A milestone is finished once its directory holds no + * other quest and its README has no `## Required`. * * Readiness stays a grep for the heading; this rule is what keeps that answer * true once the milestone empties. The root's own listing of its milestones is @@ -285,25 +284,18 @@ export function finishedMilestone(docs: Doc[]): (doc: Doc, entry: Entry) => bool const target = rooted(entry.target); if (target === null || target === ROOT || !permanent(target)) return false; const milestone = byPath.get(target); - return milestone !== undefined && !has(milestone, "Required"); + return milestone !== undefined && !has(milestone, "Required") && !docs.some((d) => holds(target, d.path)); }; } /** * `Required` must be acyclic. A cycle is a set of quests none of which can ever * start, and walking the links to rule one out is exactly the manual step an - * author would otherwise take before adding a blocker. An epic requires its + * author would otherwise take before adding a blocker. An epic waits for its * children, so a quest requiring the epic that holds it is a cycle too. */ function cycles(found: Finding[], docs: Doc[]) { - const blockers = new Map(); - for (const doc of docs) { - const edges = doc.links - .filter((l) => l.section === "Required" && l.position === "entry") - .map((l) => rooted(l.target)) - .filter((t): t is string => t !== null); - blockers.set(doc.path, [...(blockers.get(doc.path) ?? []), ...edges]); - } + const blockers = new Map(docs.map((doc) => [doc.path, requires(docs, doc)])); const state = new Map(); const walk = (node: string, stack: string[]) => { diff --git a/src/core/unblocked.ts b/src/core/unblocked.ts index d83d41e4..a45f18cd 100644 --- a/src/core/unblocked.ts +++ b/src/core/unblocked.ts @@ -1,4 +1,4 @@ -// Rank ready work without mistaking the epic index for downstream work. +// Rank ready work without mistaking epic membership for downstream work. import { handBackWaits } from "./claim"; import { type Doc, branchQuest, children, entries, permanent, rooted } from "./doc"; @@ -18,7 +18,7 @@ export interface RankedQuest { * structure; callers validate filesystem links. */ export interface Ranking { - /** The root's subtree rank of `path`, lowest first; unindexed paths sort last. */ + /** The rank of the root's child that holds `path`, lowest first; the root itself sorts last. */ priority(path: string): number; /** Distinct transitive dependents of `path`, excluding epic membership and milestones. */ impact(path: string): number; @@ -31,14 +31,19 @@ export function ranking(docs: Doc[]): Ranking { const byPath = new Map(docs.map((doc) => [doc.path, doc])); const reverse = new Map(); + const depend = (target: string, path: string, structural: boolean) => { + const dependents = reverse.get(target) ?? []; + dependents.push({ path, structural }); + reverse.set(target, dependents); + }; for (const doc of docs) { - const members = new Set(children(doc)); + const kids = children(docs, doc); for (const entry of entries(doc, "Required")) { const target = rooted(entry.target!)!; - const dependents = reverse.get(target) ?? []; - dependents.push({ path: doc.path, structural: members.has(target) }); - reverse.set(target, dependents); + // An old child list's entry is membership, which the children below record. + if (!kids.includes(target)) depend(target, doc.path, false); } + for (const child of kids) depend(child, doc.path, true); } // Assign the root's subtrees their priority before scoring. In particular, @@ -48,10 +53,10 @@ export function ranking(docs: Doc[]): Ranking { if (priority.has(path)) return; priority.set(path, rank); const doc = byPath.get(path); - if (doc) for (const child of children(doc)) assign(child, rank); + if (doc) for (const child of children(docs, doc)) assign(child, rank); }; const root = byPath.get(ROOT); - if (root) children(root).forEach(assign); + if (root) children(docs, root).forEach(assign); const impact = (path: string): number => { const visited = new Set([path]); diff --git a/test/fixture.ts b/test/fixture.ts index 364aa633..16f7c159 100644 --- a/test/fixture.ts +++ b/test/fixture.ts @@ -29,10 +29,6 @@ export const ROOT_README = `# Quests ## Goal The permanent root epic. - -## Required - -- [M0](/quest/m0/README.md) `; export const M0_README = `# M0 @@ -40,10 +36,6 @@ export const M0_README = `# M0 ## Goal A milestone. - -## Required - -- [Epic](/quest/m0/epic/README.md) `; export const EPIC_README = `# Epic @@ -51,11 +43,6 @@ export const EPIC_README = `# Epic ## Goal An epic. - -## Required - -- [One](/quest/m0/epic/one.md) -- [Two](/quest/m0/epic/two.md) `; export const ONE = `# [S] One diff --git a/test/land-watch.test.ts b/test/land-watch.test.ts index 1faac133..d7c4589f 100644 --- a/test/land-watch.test.ts +++ b/test/land-watch.test.ts @@ -857,8 +857,9 @@ const bin = fileURLToPath(new URL("../src/cli/bin.ts", import.meta.url)); const bunfig = fileURLToPath(new URL("../bunfig.toml", import.meta.url)); const PATH = process.env.PATH; -const EPIC = (entries: string[]) => - `# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; +/** The launch quest, which every quest the PRs plan or finish blocks: the list they all edit. */ +const LAUNCH = (entries: string[]) => + `# [S] Launch\n\n## Goal\n\nLaunch.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; /** github.com's `upstream/project` on disk: main, and each PR's branch `branch-`, also at `refs/pull//head`. */ function upstream() { @@ -878,8 +879,9 @@ function upstream() { commit( { ".gitattributes": "quest/** merge=quest\n", - "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - "quest/m0/README.md": EPIC(["a"]), + "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n", + "quest/m0/README.md": "# M0\n\n## Goal\n\nA milestone.\n", + "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/a.md": "# [S] A\n\n## Goal\n\nA.\n", "code.txt": "one\ntwo\nthree\n", }, @@ -1198,14 +1200,14 @@ describe.skipIf(process.platform === "win32")("the watcher's land fixer", () => test("a quest-file conflict is merged with the quest driver, and a code conflict goes to the fixer", async () => { const { repo, state, fix, context } = setup(1); const quests = repo.pull(3, { - "quest/m0/README.md": EPIC(["a", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": "# [S] C\n\n## Goal\n\nC.\n", }); const code = repo.pull(4, { "code.txt": "one\nII\nthree\n" }); const failing = repo.pull(6, { "feature.txt": "new\n" }); const built = repo.main(); const base = repo.advance({ - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": "# [S] B\n\n## Goal\n\nB.\n", "code.txt": "one\n2\nthree\n", }); @@ -1272,7 +1274,7 @@ printf '[{"number":%s,"action":"fixed","head":"%s","reason":"preserve both confl "fixing 4", `requeued 3 ${merged()}`, ]); - expect(git(repo.origin, "show", `${merged()}:quest/m0/README.md`)).toBe(EPIC(["a", "b", "c"]).trim()); + expect(git(repo.origin, "show", `${merged()}:quest/m0/launch.md`)).toBe(LAUNCH(["a", "b", "c"]).trim()); expect(git(repo.origin, "rev-parse", `${merged()}^1`, `${merged()}^2`).split("\n")).toEqual([quests, base]); expect(github.mutations).toEqual([`enablePullRequestAutoMerge 3 ${merged()}`]); expect(github.comments[3].at(-1)!.body).toContain( diff --git a/test/land.test.ts b/test/land.test.ts index 74e9b096..efa0383a 100644 --- a/test/land.test.ts +++ b/test/land.test.ts @@ -104,8 +104,9 @@ function git(cwd: string, ...args: string[]): string { const QUEST = (title: string) => `# [S] ${title}\n\n## Goal\n\n${title}.\n`; -const EPIC = (entries: string[]) => - `# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; +/** The launch quest, which every quest the PRs plan or finish blocks: the list they all edit. */ +const LAUNCH = (entries: string[]) => + `# [S] Launch\n\n## Goal\n\nLaunch.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; /** The tip of every forge's main, which the template sets. */ let forgeBase: string | undefined; @@ -119,8 +120,9 @@ const forge = template((dir) => { const work = initRepository(join(dir, "work")); const files: Record = { ".gitattributes": "quest/** merge=quest\n", - "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - "quest/m0/README.md": EPIC(["a"]), + "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n", + "quest/m0/README.md": "# M0\n\n## Goal\n\nA milestone.\n", + "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/a.md": "# [S] A\n\n## Goal\n\nA.\n", "code.txt": "one\ntwo\nthree\n", }; @@ -509,8 +511,8 @@ describe.skipIf(process.platform === "win32")("quest land", () => { test("lands a batch as merge commits that keep each head's ancestry and the tested tree", async () => { const forge = new Forge(); const base = forge.main(); - const one = forge.pull("Add b", { "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - const two = forge.pull("Add c", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/c.md": QUEST("C") }); + const one = forge.pull("Add b", { "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + const two = forge.pull("Add c", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": QUEST("C") }); const heads = [one.head!, two.head!]; const deps = await forge.deps(); const plan = await resolveQueue(REPOSITORY, MERGE, deps); @@ -535,15 +537,15 @@ describe.skipIf(process.platform === "win32")("quest land", () => { expect(git(forge.origin, "show", "-s", "--format=%P", "main")).toBe(`${one.squash} ${two.head}`); expect(git(forge.origin, "rev-parse", `${one.squash}^{tree}`)).toBe(chain.links[0].tree); expect(git(forge.origin, "rev-parse", "main^{tree}")).toBe(chain.links[1].tree); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe(EPIC(["a", "b", "c"]).trim()); + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe(LAUNCH(["a", "b", "c"]).trim()); }); test("prepares a behind-base PR with quest resolve and the exact tested tree", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - const pull = forge.pull("Remove a", { "quest/m0/README.md": EPIC(["b"]), "quest/m0/a.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + const pull = forge.pull("Remove a", { "quest/m0/launch.md": LAUNCH(["b"]), "quest/m0/a.md": null }); const pin = pull.head!; - forge.advance({ "quest/m0/README.md": EPIC(["a", "b", "c"]), "quest/m0/c.md": QUEST("C") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/c.md": QUEST("C") }); const base = forge.main(); const deps = await forge.deps(); const plan = await resolveQueue(REPOSITORY, SQUASH, deps); @@ -562,22 +564,22 @@ describe.skipIf(process.platform === "win32")("quest land", () => { const adding = mode === "adding"; if (!adding) forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": QUEST("C"), }); // Each PR adds or finishes its own quest, so each passes `quest check` alone on the base. const one = forge.pull("Change b", { - "quest/m0/README.md": EPIC(adding ? ["a", "b"] : ["a", "c"]), + "quest/m0/launch.md": LAUNCH(adding ? ["a", "b"] : ["a", "c"]), "quest/m0/b.md": adding ? QUEST("B") : null, }); const two = forge.pull("Change c", { - "quest/m0/README.md": EPIC(adding ? ["a", "c"] : ["a", "b"]), + "quest/m0/launch.md": LAUNCH(adding ? ["a", "c"] : ["a", "b"]), "quest/m0/c.md": adding ? QUEST("C") : null, }); expect((await forge.round()).landing).toEqual([`landed 1 ${one.squash}`, `landed 2 ${two.squash}`]); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe( - EPIC(adding ? ["a", "b", "c"] : ["a"]).trim(), + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe( + LAUNCH(adding ? ["a", "b", "c"] : ["a"]).trim(), ); }); @@ -987,11 +989,11 @@ describe.skipIf(process.platform === "win32")("quest land", () => { "bunfig.toml": 'preload = ["./evil.ts"]\n', ".env": "BUN_OPTIONS=--preload=./evil.ts\n", "evil.ts": "throw new Error('PR code ran');\n", - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": "# [S] B\n\n## Goal\n\nB.\n", }); forge.pull("Add c quest", { - "quest/m0/README.md": EPIC(["a", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": "# [S] C\n\n## Goal\n\nC.\n", }); const { landing } = await forge.round(); @@ -1374,7 +1376,7 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("ejects alone a PR that fails quest check on the current base, before batching", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); // A mistyped link never named a quest, so nothing the base did explains it. forge.pull("Link b", { "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/bb.md) - b\n`, @@ -1390,15 +1392,15 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("drops a queued PR's list links to a quest the base finished, in the chain and the landed head", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); const pull = forge.pull("Plan c", { - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/c.md": `${QUEST("C")}\n## Required\n\n- [B](/quest/m0/b.md) - b first\n`, "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n- [C](/quest/m0/c.md) - c\n`, }); const pin = pull.head!; // The base finishes b after the PR was queued, leaving both of its links to b dangling. - forge.advance({ "quest/m0/README.md": EPIC(["a"]), "quest/m0/b.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/b.md": null }); const base = forge.main(); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1]]); @@ -1417,28 +1419,28 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("two sibling PRs land together when one finishes a quest the other links", async () => { const forge = new Forge(); forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": QUEST("C"), }); // Each passes `quest check` alone on the base; chained, the first leaves the second's link dangling. - const one = forge.pull("Finish b", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/b.md": null }); + const one = forge.pull("Finish b", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/b.md": null }); const two = forge.pull("Finish c", { - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/c.md": null, "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n`, }); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1, 2]]); expect(landing).toEqual([`landed 1 ${one.squash}`, `landed 2 ${two.squash}`]); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe(EPIC(["a"]).trim()); + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe(LAUNCH(["a"]).trim()); expect(git(forge.origin, "show", "main:quest/m0/a.md")).toBe(QUEST("A").trim()); }); test("ejects a PR whose prose links a quest the base finished, and keeps links to a quest the base moved", async () => { const forge = new Forge(); forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": `${QUEST("C")}\nMore about c, so a move keeps enough of it to read as a rename.\n`, }); @@ -1448,7 +1450,7 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { }); // The base finishes b and moves c to d. forge.advance({ - "quest/m0/README.md": EPIC(["a", "d"]), + "quest/m0/launch.md": LAUNCH(["a", "d"]), "quest/m0/b.md": null, "quest/m0/c.md": null, "quest/m0/d.md": `${QUEST("C")}\nMore about c, so a move keeps enough of it to read as a rename.\n`, @@ -1461,11 +1463,11 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("screens only the PRs a batch reaches, leaving the rest of a long queue for later", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); for (let i = 0; i < 4; i++) forge.pull(`PR ${i}`, { [`${i}.txt`]: "ok" }); forge.pull("Link b", { "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n` }); // The base finishes b, so the last PR's link dangles, but an oldest-first batch of three never reaches it. - forge.advance({ "quest/m0/README.md": EPIC(["a"]), "quest/m0/b.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/b.md": null }); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1, 2, 3]]); expect(landing.map((line) => line.split(" ")[0])).toEqual(["landed", "landed", "landed"]); @@ -2090,8 +2092,8 @@ mv '${result}.new' '${result}' test("a prepared tree mismatch ejects only that PR, and the next round rebuilds the rest on the new base", async () => { const forge = new Forge(); // Both PRs edit the epic, so preparing PR 2 on PR 1's squash runs the quest merge driver. - forge.pull("Add b", { "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - forge.pull("Add c", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/c.md": QUEST("C") }); + forge.pull("Add b", { "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.pull("Add c", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": QUEST("C") }); forge.pull("Three", { "3.txt": "yes" }); forge.pull("Four", { "4.txt": "yes" }); const deps = await forge.deps(); diff --git a/test/landed.test.ts b/test/landed.test.ts index ddbeb4cc..759cc1df 100644 --- a/test/landed.test.ts +++ b/test/landed.test.ts @@ -29,12 +29,8 @@ function commit(tree: Tree, message: string) { test("a quest branch that deletes its quest passes", () => { const tree = repo("quest/m0/epic/one"); - tree.remove("quest/m0/epic/one.md") - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n", - ) - .write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nAnother quest.\n"); + // Finishing a quest edits only what it blocked, never its epic's README. + tree.remove("quest/m0/epic/one.md").write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nAnother quest.\n"); commit(tree, "finish one"); expect(tree.run("check", "--base", "main")).toEqual({ code: 0, stdout: "quest: 4 documents ok\n", stderr: "" }); }); @@ -88,7 +84,6 @@ test("a branch that is not a quest branch adds no finding", () => { test("a branch naming no quest at the merge base adds no finding", () => { const tree = repo("quest/m0/epic/three"); tree.write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nNew.\n"); - tree.append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n"); commit(tree, "plan three"); expect(tree.run("check", "--base", "main").code).toBe(0); }); diff --git a/test/links.test.ts b/test/links.test.ts index e90985a4..0cb024bb 100644 --- a/test/links.test.ts +++ b/test/links.test.ts @@ -5,10 +5,7 @@ import { ONE, Tree } from "./fixture"; function linked(name: string, target: string): Tree { return new Tree() - .write( - "quest/README.md", - `# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](${target})\n- [Two](/quest/two.md)\n`, - ) + .write("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n") .write(`quest/${name}`, ONE) .write("quest/two.md", `# [S] Two\n\n## Goal\n\nLater.\n\n## Required\n\n- [One](${target})\n`); } diff --git a/test/move.test.ts b/test/move.test.ts index 38c8b860..793e21be 100644 --- a/test/move.test.ts +++ b/test/move.test.ts @@ -10,7 +10,7 @@ import { move, remove } from "../src/core"; import { openPullRequests } from "../src/cli/claims"; import { GitHub, type GitHubDependencies } from "../src/cli/github"; import { main } from "../src/cli/main"; -import { EPIC_README, ROOT_README, Tree, initRepository, tempDir } from "./fixture"; +import { EPIC_README, Tree, initRepository, tempDir } from "./fixture"; // Each test spawns git up to a dozen times, which a busy Windows runner can stretch past 5 s. vi.setConfig({ testTimeout: 30_000 }); @@ -63,22 +63,23 @@ describe("move", () => { const moved = move( [ { - path: "quest/m0/README.md", - text: "# M0\n\n## Goal\n\nG.\n\n## Required\n\n- [E](/quest/m0/e/README.md)\n", + path: "quest/m0/next.md", + text: "# [S] Next\n\n## Goal\n\nG.\n\n## Required\n\n- [E](/quest/m0/e/README.md)\n", }, + { path: "quest/m0/e/README.md", text: "# E\n\n## Goal\n\nG.\n" }, + { path: "quest/m0/e/a.md", text: "# [S] A\n\n## Goal\n\nG.\n" }, { - path: "quest/m0/e/README.md", - text: "# E\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/e/a.md)\n", + path: "quest/m0/e/b.md", + text: "# [S] B\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/e/a.md)\n", }, - { path: "quest/m0/e/a.md", text: "# [S] A\n\n## Goal\n\nG.\n" }, { path: "quest/m0/elsewhere.md", text: "# [S] X\n\n## Related\n\n- [E2](/quest/m0/e2.md)\n" }, ], "quest/m0/e", "quest/m1/e", ); - expect([...moved.texts.keys()]).toEqual(["quest/m0/README.md", "quest/m1/e/README.md"]); - expect(moved.texts.get("quest/m0/README.md")).toContain("- [E](/quest/m1/e/README.md)\n"); - expect(moved.texts.get("quest/m1/e/README.md")).toContain("- [A](/quest/m1/e/a.md)\n"); + expect([...moved.texts.keys()]).toEqual(["quest/m0/next.md", "quest/m1/e/b.md"]); + expect(moved.texts.get("quest/m0/next.md")).toContain("- [E](/quest/m1/e/README.md)\n"); + expect(moved.texts.get("quest/m1/e/b.md")).toContain("- [A](/quest/m1/e/a.md)\n"); }); test("reports a link whose destination is not written as parsed", () => { @@ -132,7 +133,7 @@ describe("remove", () => { }, { path: "quest/b.md", text: "# [S] B\n\n## Goal\n\nG.\n" }, { - path: "quest/m1/a.md", + path: "quest/a.md", text: "# [S] A\n\n## Goal\n\nG.\n\n## Required\n\n- [M1](/quest/m1/README.md)\n- [M2](/quest/m2/README.md)\n\n" + "## Related\n\n- [M0](/quest/m0/README.md)\n", @@ -141,12 +142,10 @@ describe("remove", () => { { path: "quest/m2/README.md", text: "# M2\n\n## Goal\n\nG.\n" }, ]; const texts = remove(sources, gone); - expect([...texts.keys()].sort()).toEqual(["quest/m0/README.md", "quest/m1/README.md", "quest/m1/a.md"]); + expect([...texts.keys()].sort()).toEqual(["quest/a.md", "quest/m0/README.md", "quest/m1/README.md"]); expect(texts.get("quest/m0/README.md")).toBe("# M0\n\n## Goal\n\nG.\n"); expect(texts.get("quest/m1/README.md")).toBe("# M1\n\n## Goal\n\nG.\n"); - expect(texts.get("quest/m1/a.md")).toBe( - "# [S] A\n\n## Goal\n\nG.\n\n## Related\n\n- [M0](/quest/m0/README.md)\n", - ); + expect(texts.get("quest/a.md")).toBe("# [S] A\n\n## Goal\n\nG.\n\n## Related\n\n- [M0](/quest/m0/README.md)\n"); }); }); @@ -156,28 +155,22 @@ describe("quest mv", () => { const out = await quest(tree, "mv", "/quest/m0/epic/one.md", "quest/m0/epic/first.md"); expect(out).toEqual({ code: 0, - stdout: "R quest/m0/epic/one.md -> quest/m0/epic/first.md\nM quest/m0/epic/README.md\nM quest/m0/epic/two.md\n", + stdout: "R quest/m0/epic/one.md -> quest/m0/epic/first.md\nM quest/m0/epic/two.md\n", stderr: "quest: no origin remote, so claims were not checked\n", }); expect(tree.read("quest/m0/epic/two.md")).toContain("- [One](/quest/m0/epic/first.md) - must finish first"); - expect(staged(tree)).toEqual([ - "M quest/m0/epic/README.md", - "M quest/m0/epic/two.md", - "R quest/m0/epic/one.md -> quest/m0/epic/first.md", - ]); + expect(staged(tree)).toEqual(["M quest/m0/epic/two.md", "R quest/m0/epic/one.md -> quest/m0/epic/first.md"]); tree.accepts(); }); test("moves an epic into a new directory", async () => { const tree = Tree.committed(); const out = await quest(tree, "mv", "quest/m0/epic", "quest/m1/later/epic"); - expect(out.stdout).toBe( - "R quest/m0/epic -> quest/m1/later/epic\nM quest/m0/README.md\nM quest/m1/later/epic/README.md\nM quest/m1/later/epic/two.md\n", - ); - expect(tree.read("quest/m1/later/epic/README.md")).toContain("- [One](/quest/m1/later/epic/one.md)\n"); + expect(out.stdout).toBe("R quest/m0/epic -> quest/m1/later/epic\nM quest/m1/later/epic/two.md\n"); + expect(tree.read("quest/m1/later/epic/two.md")).toContain("- [One](/quest/m1/later/epic/one.md)"); // The epic left m0 for a directory with no README, which check reports rather than mv guessing. expect(out.code).toBe(1); - expect(out.stderr).toContain("quest/m1/later/epic/README.md: not listed in quest/m1/later/README.md"); + expect(out.stderr).toContain("quest/m1/later/epic/README.md: sits in quest/m1/later, which has no README.md"); }); test("reports mentions it does not edit", async () => { @@ -260,18 +253,16 @@ describe("quest mv", () => { describe("quest rm", () => { test("deletes a quest listed under several Required and Related sections", async () => { - const tree = Tree.baseline() - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") - .write( - "quest/m0/epic/three.md", - "# [S] Three\n\n## Goal\n\nMore.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [One](/quest/m0/epic/one.md)\n\n" + - "## Related\n\n- [One](/quest/m0/epic/one.md) - similar\n", - ); + const tree = Tree.baseline().write( + "quest/m0/epic/three.md", + "# [S] Three\n\n## Goal\n\nMore.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [One](/quest/m0/epic/one.md)\n\n" + + "## Related\n\n- [One](/quest/m0/epic/one.md) - similar\n", + ); committed(tree); const out = await quest(tree, "rm", "quest/m0/epic/one.md"); expect(out).toEqual({ code: 0, - stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/README.md\nM quest/m0/epic/three.md\nM quest/m0/epic/two.md\n", + stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/three.md\nM quest/m0/epic/two.md\n", stderr: "", }); expect(tree.read("quest/m0/epic/two.md")).toBe("# [S] Two\n\n## Goal\n\nAnother quest.\n"); @@ -282,10 +273,9 @@ describe("quest rm", () => { tree.accepts(); }); - test("drops links to the milestone it finishes while the root still lists it", async () => { + test("drops links to the milestone it finishes", async () => { const tree = Tree.baseline() - .write("quest/README.md", `${ROOT_README}- [M1](/quest/m1/README.md)\n`) - .write("quest/m1/README.md", "# M1\n\n## Goal\n\nNext.\n\n## Required\n\n- [Later](/quest/m1/later.md)\n") + .write("quest/m1/README.md", "# M1\n\n## Goal\n\nNext.\n") .write( "quest/m1/later.md", "# [S] Later\n\n## Goal\n\nAfter m0.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", @@ -294,11 +284,9 @@ describe("quest rm", () => { const out = await quest(tree, "rm", "-r", "quest/m0/epic"); expect(out.code).toBe(0); expect(out.stdout).toBe( - "D quest/m0/epic/README.md\nD quest/m0/epic/one.md\nD quest/m0/epic/two.md\nM quest/m0/README.md\nM quest/m1/later.md\n", + "D quest/m0/epic/README.md\nD quest/m0/epic/one.md\nD quest/m0/epic/two.md\nM quest/m1/later.md\n", ); - expect(tree.read("quest/m0/README.md")).toBe("# M0\n\n## Goal\n\nA milestone.\n"); expect(tree.read("quest/m1/later.md")).toBe("# [S] Later\n\n## Goal\n\nAfter m0.\n"); - expect(tree.read("quest/README.md")).toContain("- [M0](/quest/m0/README.md)\n"); tree.accepts(); }); @@ -357,10 +345,7 @@ describe("quest check --fix", () => { async function diverged(change: (tree: Tree) => Promise | void): Promise { const tree = Tree.committed(); git(tree.path, "checkout", "-q", "-b", "feature"); - tree.append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n").write( - "quest/m0/epic/three.md", - THREE, - ); + tree.write("quest/m0/epic/three.md", THREE); git(tree.path, "add", "-A"); git(tree.path, "commit", "-q", "-m", "three"); git(tree.path, "checkout", "-q", "main"); @@ -407,7 +392,7 @@ describe("quest check --fix", () => { const out = await quest(tree, "check", "--fix"); expect(out.code).toBe(1); - expect(out.stdout).toBe("M quest/m0/epic/README.md\nM quest/m0/epic/second.md\nM quest/m0/epic/three.md\n"); + expect(out.stdout).toBe("M quest/m0/epic/second.md\nM quest/m0/epic/three.md\n"); expect(tree.read("quest/m0/epic/three.md").replaceAll("\r\n", "\n")).toBe( "# [S] Three\n\n## Goal\n\nMore.\n\n## Related\n\n- [Two](/quest/m0/epic/two.md) - similar\n" + "- [Nope](/quest/m0/epic/nope.md)\n\n## Plan\n\nAfter [one](/quest/m0/epic/one.md).\n", @@ -426,24 +411,47 @@ describe("quest check --fix", () => { git(repo, "commit", "-q", "-m", "finish one"); expect(await quest(tree, "check", "--fix")).toEqual({ code: 0, - stdout: "M quest/m0/epic/README.md\nM quest/m0/epic/two.md\nquest: 4 documents ok\n", + stdout: "M quest/m0/epic/two.md\nquest: 4 documents ok\n", stderr: "", }); }); test("refuses while a quest file has unresolved conflicts", async () => { const tree = await diverged((tree) => { - tree.write("quest/m0/epic/README.md", `${EPIC_README}- [Four](/quest/m0/epic/four.md)\n`); + tree.write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nPlanned on main too.\n"); + git(tree.path, "add", "quest/m0/epic/three.md"); }); expect(spawnSync("git", ["-C", tree.path, "merge", "-q", "main"]).status).not.toBe(0); - const before = tree.read("quest/m0/epic/README.md"); + const before = tree.read("quest/m0/epic/three.md"); const out = await quest(tree, "check", "--fix"); expect(out).toEqual({ code: 1, stdout: "", - stderr: "quest: resolve the merge conflicts in quest/m0/epic/README.md before quest check --fix\n", + stderr: "quest: resolve the merge conflicts in quest/m0/epic/three.md before quest check --fix\n", }); - expect(tree.read("quest/m0/epic/README.md")).toBe(before); + expect(tree.read("quest/m0/epic/three.md")).toBe(before); + }); + + // Trees from before directory membership keep their child lists until migrated: + // finishing a quest drops only its own entry. + test("drops only the finished quest's entry from a child list", async () => { + const tree = Tree.baseline() + .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") + .append("quest/m0/README.md", "\n## Required\n\n- [Epic](/quest/m0/epic/README.md)\n") + .append( + "quest/m0/epic/README.md", + "\n## Required\n\n- [One](/quest/m0/epic/one.md)\n- [Two](/quest/m0/epic/two.md)\n", + ); + committed(tree); + expect(await quest(tree, "rm", "quest/m0/epic/one.md")).toEqual({ + code: 0, + stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/README.md\nM quest/m0/epic/two.md\n", + stderr: "", + }); + expect(tree.read("quest/m0/epic/README.md")).toBe( + `${EPIC_README}\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n`, + ); + expect(await quest(tree, "check", "--fix")).toEqual({ code: 0, stdout: "quest: 4 documents ok\n", stderr: "" }); }); test("fails outside a git work tree", async () => { diff --git a/test/theme.test.ts b/test/theme.test.ts index a5e27782..6ff8fc32 100644 --- a/test/theme.test.ts +++ b/test/theme.test.ts @@ -17,11 +17,7 @@ function sizes(): Tree { return new Tree() .write("quest/README.md", ROOT_README) .write("quest/m0/README.md", M0_README) - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n" + - ["xs", "s", "m", "l", "xl"].map((name) => `- [${name}](/quest/m0/epic/${name}.md)\n`).join(""), - ) + .write("quest/m0/epic/README.md", "# Epic\n\n## Goal\n\nAn epic.\n") .write("quest/m0/epic/xs.md", "# [XS] Tiny\n\n## Goal\n\nA quest.\n") .write("quest/m0/epic/s.md", "# [S] Small\n\n## Goal\n\nA quest.\n") .write("quest/m0/epic/m.md", "# [M] Medium\n\n## Goal\n\nA quest.\n") diff --git a/test/tree.test.ts b/test/tree.test.ts index 614cf8d1..a33ca185 100644 --- a/test/tree.test.ts +++ b/test/tree.test.ts @@ -12,7 +12,7 @@ import { basename } from "node:path"; import { describe, expect, test } from "vitest"; import { collect } from "../src/cli/tree"; -import { EPIC_README, ONE, TWO, Tree } from "./fixture"; +import { ONE, TWO, Tree } from "./fixture"; const tree = Tree.baseline; @@ -216,9 +216,9 @@ describe("headings", () => { }); }); -describe("index", () => { +describe("epics", () => { test("a quest and an epic cannot share a page and branch path", () => { - const t = tree().write("quest/m0/epic.md", ONE).append("quest/m0/README.md", "- [Quest](/quest/m0/epic.md)\n"); + const t = tree().write("quest/m0/epic.md", ONE); const finding = "quest/m0/epic.md: quest path collides with quest/m0/epic/README.md; rename one of these documents"; expect(t.findings()).toEqual([finding]); @@ -228,7 +228,6 @@ describe("index", () => { test("a collision persists after the epic's last child completes", () => { tree() .write("quest/m0/epic/one/README.md", ONE) - .append("quest/m0/epic/README.md", "- [Remaining epic](/quest/m0/epic/one/README.md)\n") .rejects("quest/m0/epic/one.md: quest path collides with quest/m0/epic/one/README.md"); }); @@ -238,7 +237,6 @@ describe("index", () => { test("a README-named directory collides with its parent README", () => { tree() .write("quest/m0/epic/README/README.md", ONE) - .append("quest/m0/epic/README.md", "- [Nested](/quest/m0/epic/README/README.md)\n") .rejects("quest/m0/epic/README.md: quest path collides with quest/m0/epic/README/README.md"); }); @@ -249,15 +247,21 @@ describe("index", () => { .rejects("quest/m0/epic/one/README.md: quest path collides with quest/m0/epic/one/README/two.md"); }); + // The directory is the epic's list of children: a new quest needs no link + // anywhere to be part of it. + test("a quest joins the epic whose directory holds it", () => { + const t = tree().write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nA new child.\n"); + t.accepts(); + expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/epic/three.md"]); + }); + // A README whose last child merged is the epic's own remaining work: a leaf // quest, sized and listed as ready like any other. - test("a README without an index is a quest", () => { - const t = tree() - .write( - "quest/m0/epic/sub/README.md", - "# Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", - ) - .append("quest/m0/epic/README.md", "- [Sub](/quest/m0/epic/sub/README.md)\n"); + test("a README whose directory holds no other quest is a quest", () => { + const t = tree().write( + "quest/m0/epic/sub/README.md", + "# Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", + ); t.rejects("quest title must be"); t.write( "quest/m0/epic/sub/README.md", @@ -267,90 +271,92 @@ describe("index", () => { expect(t.ready()).toContain("quest/m0/epic/sub/README.md"); }); - // Completing an epic's last quest removes its heading with the entry, or - // deletes the directory. A bare `## Required` would block the husk forever. - test("an empty epic index", () => { + // Completing a quest's last blocker removes its heading with the entry. A + // bare `## Required` would block it forever. + test("an empty Required section", () => { + tree().append("quest/m0/epic/one.md", "\n## Required\n").rejects("'## Required' is empty"); tree() - .write("quest/m0/husk/README.md", "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Required\n") - .append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n") + .write("quest/m0/husk/README.md", "# [S] Husk\n\n## Goal\n\nIts last blocker merged.\n\n## Required\n") .rejects("'## Required' is empty"); }); - // The absence of `## Required` means ready. A heading left behind by its last - // blocker reads as blocked to every readiness check, forever. - test("an empty Required section", () => { - tree().append("quest/m0/epic/one.md", "\n## Required\n").rejects("'## Required' is empty"); + // Nothing above such a quest reaches it, so nothing would ever rank or + // render it. + test("a quest in a directory without a README", () => { + tree() + .write("quest/m0/loose/three.md", ONE) + .rejects( + "quest/m0/loose/three.md: sits in quest/m0/loose, which has no README.md; every directory under quest/ is an epic, so add its README or move the quest", + ); + tree() + .write("quest/m0/loose/deeper/README.md", ONE) + .rejects("quest/m0/loose/deeper/README.md: sits in quest/m0/loose, which has no README.md"); }); - test("an unlisted quest", () => { - tree() - .write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nA quest nobody indexed.\n") - .rejects("not listed in quest/m0/epic/README.md's '## Required'"); + // Trees from before directory membership still list each epic's children. + // Such a link is membership, so it counts once. + test.each([ + ["quest/README.md", "/quest/m0/README.md"], + ["quest/m0/README.md", "/quest/m0/epic/README.md"], + ["quest/m0/epic/README.md", "/quest/m0/epic/one.md"], + ])("%s requiring its child %s", (readme, target) => { + const listed = tree().append(readme, `\n## Required\n\n- [Held](${target})\n`); + listed.accepts(); + expect(listed.ready()).toEqual(tree().ready()); + expect(listed.blockers(readme)).toEqual(tree().blockers(readme)); }); - // Children are the entries that sit directly under the epic, so a milestone - // requiring a grandchild only waits on it; the epic still owns it. - test("requiring a grandchild is a blocker", () => { - const t = tree().append("quest/m0/README.md", "- [One](/quest/m0/epic/one.md)\n"); - t.accepts(); - expect(t.ready()).toEqual(["quest/m0/epic/one.md"]); + // Only a child stands in for a link: a deeper quest, or a link to no quest, + // stays a blocker, as on a tree that listed children. + test.each([ + ["/quest/m0/epic/one.md", "quest/m0/epic/one.md"], + ["/quest/m0/gone.md", "Gone"], + ])("quest/m0/README.md requiring %s, which is not its child", (target, rendered) => { + const t = tree().append("quest/m0/README.md", `\n## Required\n\n- [Gone](${target})\n`); + expect(t.blockers("quest/m0/README.md")[0]).toBe(rendered); }); - test("a quest listed twice", () => { + test("a quest required twice", () => { tree() - .append("quest/m0/epic/README.md", "- [One again](/quest/m0/epic/one.md)\n") + .append("quest/m0/epic/two.md", "- [One again](/quest/m0/epic/one.md)\n") .rejects("requires /quest/m0/epic/one.md twice"); }); - test("a relative index entry", () => { + test("a relative Required entry", () => { tree() - .write("quest/m0/epic/README.md", EPIC_README.replace("(/quest/m0/epic/one.md)", "(one.md)")) + .write("quest/m0/epic/two.md", TWO.replace("(/quest/m0/epic/one.md)", "(one.md)")) .rejects("link to a quest must be root-absolute: one.md"); }); // A target that merely exists is not enough: quest/AGENTS.md is a file under // quest/ that nothing can finish. - test("an index entry that is not a quest", () => { + test("a Required entry that is not a quest", () => { tree() .write("quest/AGENTS.md", "# Contract\n") - .append("quest/README.md", "- [Contract](/quest/AGENTS.md)\n") + .append("quest/m0/epic/two.md", "- [Contract](/quest/AGENTS.md)\n") .rejects("requires /quest/AGENTS.md, which is not a quest document"); }); - // The index is a list of entries, not prose that happens to link. - test("prose under the index", () => { - tree().append("quest/m0/epic/README.md", "\nSee also [One](/quest/m0/epic/one.md).\n").rejects("mid-sentence"); + // `Required` is a list of entries, not prose that happens to link. + test("prose under Required", () => { + tree().append("quest/m0/epic/two.md", "\nSee also [One](/quest/m0/epic/one.md).\n").rejects("mid-sentence"); }); - // A blocker outside the epic's directory is not a child, so a README holding - // only one is a quest and needs a size like any other. - test("an epic listing no quest", () => { + // A blocker is not a child, so a README holding only blockers is a quest + // and needs a size like any other. + test("a README with only blockers is a quest", () => { tree() .write( "quest/m0/husk/README.md", "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n", ) - .append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n") .rejects("quest title must be"); }); - // A LOOSE list - blank lines between entries - wraps every item in a - // paragraph. Treating that paragraph as text would classify every entry in - // the list as mid-sentence prose, which is a false positive on ordinary - // Markdown and would fire on every blocker and every index entry at once. - test("a loose index list", () => { - tree() - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n\n- [Two](/quest/m0/epic/two.md)\n", - ) - .accepts(); - }); - // A milestone with nothing left is not its own work, so it needs no size and // never lists as ready. test("a milestone may be empty", () => { - const t = tree().write("quest/m0/README.md", "# m0\n\n## Goal\n\nEmpty for now.\n").remove("quest/m0/epic"); + const t = tree().remove("quest/m0/epic"); t.accepts(); expect(t.ready()).toEqual([]); }); @@ -359,18 +365,11 @@ describe("index", () => { // Milestones are permanent, so a link to one keeps resolving after it // finishes. Check forces its removal; readiness stays a grep for the heading. describe("finished milestones", () => { - const EMPTY_M0 = "# M0\n\n## Goal\n\nA milestone.\n"; const GATE = "# [S] Gate\n\n## Goal\n\nRuns once m0 finishes.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n"; /** The baseline plus m1, whose gate requires m0. */ const gated = () => - tree() - .append("quest/README.md", "- [M1](/quest/m1/README.md)\n") - .write( - "quest/m1/README.md", - "# M1\n\n## Goal\n\nThe next milestone.\n\n## Required\n\n- [Gate](/quest/m1/gate.md)\n", - ) - .write("quest/m1/gate.md", GATE); + tree().write("quest/m1/README.md", "# M1\n\n## Goal\n\nThe next milestone.\n").write("quest/m1/gate.md", GATE); test("a link to an open milestone blocks", () => { const t = gated(); @@ -379,7 +378,7 @@ describe("finished milestones", () => { }); test("a link to a finished milestone", () => { - const t = gated().write("quest/m0/README.md", EMPTY_M0).remove("quest/m0/epic"); + const t = gated().remove("quest/m0/epic"); expect(t.findings()).toEqual([ "quest/m1/gate.md:9: requires /quest/m0/README.md, a finished milestone; remove the link, and the '## Required' heading with its last entry", ]); @@ -387,22 +386,24 @@ describe("finished milestones", () => { }); // moq-dev/moq's m1 lists m0 quests: those blockers keep it open. - test("a milestone with only non-child blockers left is open", () => { + test("a milestone with only blockers left is open", () => { gated() - .write("quest/m0/README.md", `${EMPTY_M0}\n## Required\n\n- [Other](/quest/m1/other.md)\n`) + .append("quest/m0/README.md", "\n## Required\n\n- [Other](/quest/m1/other.md)\n") .remove("quest/m0/epic") .write("quest/m1/other.md", "# [S] Other\n\n## Goal\n\nOpen work m0 waits on.\n") - .append("quest/m1/README.md", "- [Other](/quest/m1/other.md)\n") .accepts(); }); - test("the root's listing of a finished milestone is membership", () => { - tree().write("quest/m0/README.md", EMPTY_M0).remove("quest/m0/epic").accepts(); + // The root's listing of its milestones is membership, not a blocker. + test("the root's link to a finished milestone is allowed", () => { + tree() + .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") + .remove("quest/m0/epic") + .accepts(); }); test("removing the link readies the quest", () => { const t = gated() - .write("quest/m0/README.md", EMPTY_M0) .remove("quest/m0/epic") .write("quest/m1/gate.md", "# [S] Gate\n\n## Goal\n\nRuns once m0 finishes.\n"); t.accepts(); @@ -424,12 +425,10 @@ describe("Required", () => { // only thing that can close it. test("a cycle through an epic", () => { tree() - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") .write( "quest/m0/outer.md", "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", ) - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") .write( "quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nInside the epic that blocks it.\n\n## Required\n\n- [Outer](/quest/m0/outer.md) - must finish first\n", @@ -582,12 +581,10 @@ describe("ready", () => { // useful answer is which of its quests are still open - all of them, since a // completed quest is deleted. test("blocked by an epic", () => { - const t = tree() - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") - .write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", - ); + const t = tree().write( + "quest/m0/outer.md", + "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", + ); expect(t.blockers("quest/m0/outer.md")).toEqual([ "quest/m0/epic/README.md", " quest/m0/epic/one.md", @@ -599,12 +596,10 @@ describe("ready", () => { // running this on it is how you ask. Expanding buried the entries that were // asked for under a subtree repeated once per path through it. test("a required quest is not expanded", () => { - const t = tree() - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") - .write( - "quest/m0/epic/three.md", - "# [S] Three\n\n## Goal\n\nLast in the chain.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md) - must finish first\n", - ); + const t = tree().write( + "quest/m0/epic/three.md", + "# [S] Three\n\n## Goal\n\nLast in the chain.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md) - must finish first\n", + ); expect(t.blockers("quest/m0/epic/three.md")).toEqual(["quest/m0/epic/two.md"]); }); @@ -619,15 +614,12 @@ describe("ready", () => { }); // The listing is the query the start flow reproduces by grepping. An - // epic is absent while it still indexes children, and `two.md` is + // epic is absent while its directory holds other quests, and `two.md` is // blocked. test("the listing", () => { const t = tree(); expect(t.ready()).toEqual(["quest/m0/epic/one.md"]); - t.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n").write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nReady too.\n", - ); + t.write("quest/m0/outer.md", "# [S] Outer\n\n## Goal\n\nReady too.\n"); expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/outer.md"]); }); @@ -636,38 +628,36 @@ describe("ready", () => { // cycle there has to print rather than recurse forever. test("a cycle terminates", () => { const t = tree() - .append("quest/m0/epic/README.md", "- [Itself](/quest/m0/epic/README.md)\n") - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") + .append("quest/m0/epic/README.md", "\n## Required\n\n- [Itself](/quest/m0/epic/README.md)\n") .write( "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on an epic that lists itself.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", + "# [S] Outer\n\n## Goal\n\nBlocked on an epic that requires itself.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", ); expect(t.blockers("quest/m0/outer.md")).toEqual([ "quest/m0/epic/README.md", + " quest/m0/epic/README.md", " quest/m0/epic/one.md", " quest/m0/epic/two.md", - " quest/m0/epic/README.md", ]); }); - test("the listing follows nested priority and terminates cycles", () => { + // Path order: an epic before its children, and milestone numbers by value. + test("the listing is in path order", () => { const t = tree() .write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nReady.\n") - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [Self](/quest/m0/epic/README.md)\n- [One](/quest/m0/epic/one.md)\n", - ); - expect(t.ready()).toEqual(["quest/m0/epic/two.md", "quest/m0/epic/one.md"]); - }); - - test("the listing appends unindexed quests", () => { - const t = tree() - .write("quest/m0/aaa.md", "# [S] Unindexed\n\n## Goal\n\nDiscover me.\n") - .write( - "quest/m0/blocked.md", - "# [S] Blocked\n\n## Goal\n\nWait.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n", - ); - expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/aaa.md"]); + .write("quest/m0/aaa.md", "# [S] First\n\n## Goal\n\nSorts before the epic.\n") + .write("quest/m10/README.md", "# M10\n\n## Goal\n\nLater.\n") + .write("quest/m10/one.md", ONE) + .write("quest/m2/README.md", "# M2\n\n## Goal\n\nSooner.\n") + .write("quest/m2/one.md", ONE); + t.accepts(); + expect(t.ready()).toEqual([ + "quest/m0/aaa.md", + "quest/m0/epic/one.md", + "quest/m0/epic/two.md", + "quest/m2/one.md", + "quest/m10/one.md", + ]); }); }); diff --git a/test/unblocked.test.ts b/test/unblocked.test.ts index 48bd144e..817b3b6b 100644 --- a/test/unblocked.test.ts +++ b/test/unblocked.test.ts @@ -2,32 +2,21 @@ import { expect, test } from "vitest"; import { type Doc, owner, parse, ready, unblocked } from "../src/core"; -/** A valid indexed tree, with insertion order defining each epic's priorities. */ +/** A valid tree: each spec quest with its blockers, and the READMEs its directories need as epics. */ function graph(spec: Record, milestones = ["m0"]): Doc[] { - const index = new Map([ - ["quest/README.md", milestones.map((name) => `quest/${name}/README.md`)], - ...milestones.map((name) => [`quest/${name}/README.md`, []] as [string, string[]]), - ]); - const add = (path: string) => { - if (path === "quest/README.md") return; - const parent = `${owner(path)}/README.md`; - if (!index.has(parent)) { - index.set(parent, []); - add(parent); + const epics = new Set(["quest/README.md", ...milestones.map((name) => `quest/${name}/README.md`)]); + for (const name of Object.keys(spec)) { + for (let path = `quest/${name}`; path !== "quest/README.md";) { + path = `${owner(path)}/README.md`; + epics.add(path); } - const children = index.get(parent)!; - if (!children.includes(path)) children.push(path); - }; - for (const name of Object.keys(spec)) add(`quest/${name}`); - const paths = new Set([...index.keys(), ...Object.keys(spec).map((name) => `quest/${name}`)]); + } + const paths = new Set([...epics, ...Object.keys(spec).map((name) => `quest/${name}`)]); return [...paths].map((path) => { - const dependencies = [ - ...(index.get(path) ?? []), - ...(spec[path.slice(6)] ?? []).map((name) => `quest/${name}`), - ]; + const dependencies = (spec[path.slice(6)] ?? []).map((name) => `quest/${name}`); return parse( path, - `# ${index.has(path) ? "Epic" : "[S] Work"}\n\n## Goal\n\nWork.\n` + + `# ${epics.has(path) ? "Epic" : "[S] Work"}\n\n## Goal\n\nWork.\n` + (dependencies.length ? `\n## Required\n\n${dependencies.map((dep) => `- [Work](/${dep})`).join("\n")}\n` : ""), @@ -37,7 +26,7 @@ function graph(spec: Record, milestones = ["m0"]): Doc[] { test("ranks chains ahead of zero-impact work without changing ready", () => { const docs = graph({ "m0/zero.md": [], "m0/a.md": [], "m0/b.md": ["m0/a.md"], "m0/c.md": ["m0/b.md"] }); - expect(ready(docs)).toEqual(["quest/m0/zero.md", "quest/m0/a.md"]); + expect(ready(docs)).toEqual(["quest/m0/a.md", "quest/m0/zero.md"]); expect(unblocked(docs)).toEqual([ { path: "quest/m0/a.md", dependents: 2 }, { path: "quest/m0/zero.md", dependents: 0 }, @@ -58,6 +47,12 @@ test("deduplicates diamonds and counts work that still has another prerequisite" ]); }); +test("an epic's list of its own children is membership, not dependents", () => { + const spec = { "m0/epic/a.md": [], "m0/epic/b.md": ["m0/epic/a.md"], "m0/zero.md": [] }; + const listed = graph({ ...spec, "m0/epic/README.md": ["m0/epic/a.md", "m0/epic/b.md"] }); + expect(unblocked(listed)).toEqual(unblocked(graph(spec))); +}); + test("does not score membership, but reaches real dependents of nested epics", () => { const docs = graph({ "m0/epic/nested/a.md": [], @@ -86,7 +81,7 @@ test("retains an epic's real prerequisites alongside its children", () => { ]); }); -test("root milestone order wins over impact, counting later-milestone dependents", () => { +test("milestone order wins over impact, counting later-milestone dependents", () => { const docs = graph( { "m0/early.md": [], @@ -102,17 +97,18 @@ test("root milestone order wins over impact, counting later-milestone dependents { path: "quest/m1/later.md", dependents: 2 }, ]); expect(unblocked(docs.slice().reverse())).toEqual(unblocked(docs)); - const reordered = graph({ "m0/a.md": [], "m1/b.md": [] }, ["m1", "m0"]); - expect(unblocked(reordered).map((quest) => quest.path)).toEqual(["quest/m1/b.md", "quest/m0/a.md"]); + // Milestones rank in path order, which compares their numbers by value. + const numbered = graph({ "m10/a.md": [], "m2/b.md": [] }, ["m10", "m2"]); + expect(unblocked(numbered).map((quest) => quest.path)).toEqual(["quest/m2/b.md", "quest/m10/a.md"]); }); -test("breaks ties in existing tree order and treats a completed epic as work", () => { +test("breaks ties in path order and treats a completed epic as work", () => { const docs = graph({ "m0/z.md": [], "m0/finished/README.md": [], "m0/a.md": [] }); expect(unblocked(docs)).toEqual(ready(docs).map((path) => ({ path, dependents: 0 }))); expect(unblocked(docs).map((quest) => quest.path)).toEqual([ - "quest/m0/z.md", - "quest/m0/finished/README.md", "quest/m0/a.md", + "quest/m0/finished/README.md", + "quest/m0/z.md", ]); }); diff --git a/test/waiting.test.ts b/test/waiting.test.ts index 647dd66e..8d75553a 100644 --- a/test/waiting.test.ts +++ b/test/waiting.test.ts @@ -12,25 +12,15 @@ import { withoutHandBack, } from "../src/core"; -const ROOT = "# Quests\n\n## Goal\n\nAll.\n\n## Required\n\n- [m0](/quest/m0/README.md)\n- [m1](/quest/m1/README.md)\n"; - -/** A tree of two milestones, each listing its quests. */ +/** A tree of two milestones and their quests. */ function tree(m0: Record, m1: Record = {}): Doc[] { const milestone = (name: string, quests: Record) => [ - parse( - `quest/${name}/README.md`, - `# ${name}\n\n## Goal\n\nWork.\n` + - (Object.keys(quests).length - ? `\n## Required\n\n${Object.keys(quests) - .map((q) => `- [${q}](/quest/${name}/${q})`) - .join("\n")}\n` - : ""), - ), + parse(`quest/${name}/README.md`, `# ${name}\n\n## Goal\n\nWork.\n`), ...Object.entries(quests).map(([q, body]) => parse(`quest/${name}/${q}`, `# [S] ${q}\n\n## Goal\n\nWork.\n${body}`), ), ]; - return [parse("quest/README.md", ROOT), ...milestone("m0", m0), ...milestone("m1", m1)]; + return [parse("quest/README.md", "# Quests\n\n## Goal\n\nAll.\n"), ...milestone("m0", m0), ...milestone("m1", m1)]; } test("a wait opens with its party", () => { @@ -83,14 +73,13 @@ test("lists the maintainer's waits first, then by milestone and impact", () => { ]); }); -test("ties keep the tree's priority order, as unblocked does", () => { - // The CLI loads documents by path, so a.md comes first. +test("ties keep path order, as unblocked does", () => { const docs = tree({ "z.md": "\n## Waiting\n\n- Maintainer: pick one.\n", "a.md": "\n## Waiting\n\n- Maintainer: pick another.\n", - }).sort((x, y) => x.path.localeCompare(y.path)); - expect(unblocked(docs).map((quest) => quest.path)).toEqual(["quest/m0/z.md", "quest/m0/a.md"]); - expect(waiting(docs).map((quest) => quest.path)).toEqual(["quest/m0/z.md", "quest/m0/a.md"]); + }); + expect(unblocked(docs).map((quest) => quest.path)).toEqual(["quest/m0/a.md", "quest/m0/z.md"]); + expect(waiting(docs).map((quest) => quest.path)).toEqual(["quest/m0/a.md", "quest/m0/z.md"]); }); test("a draft hands back with Waiting, or the Decisions needed heading it replaced", () => {