@pmelab/gtd 63.0.0 → 64.1.0

package/src/replay/Replay.test.ts

@@ -1226,7 +1226,7 @@ describe("pin commits", () => {
   const pinned = () =>
     new History()
       .land("human", "idle", 1, "build", { "NOTE.md": "n" })
-      .raw("gtd(check): pin → build\n\nGtd-Pin: add", { [PIN]: "gtdpin 1 gtd 1\n" })
+      .raw("gtd(check): gtd:pin → build\n\nGtd-Pin: add", { [PIN]: "gtdpin 1 gtd 1\n" })
 
   it("are never a turn: the next step answers from the commit after the pin", async () => {
     const flow = async () => {
@@ -1268,15 +1268,15 @@ describe("pin commits", () => {
       await agent("build", "b")
     }
     const h = pinned()
-      .land("agent", "build", 1, "unpin", { "a.ts": "a" })
-      .raw("gtd(check): unpin → idle\n\nGtd-Pin: remove", { [PIN]: null })
+      .land("agent", "build", 1, "gtd:unpin", { "a.ts": "a" })
+      .raw("gtd(check): gtd:unpin → idle\n\nGtd-Pin: remove", { [PIN]: null })
     expect((await replayOf(flow, h)).kind).toBe("ended")
   })
 })
 
 describe("replay: a repin's anchor", () => {
   const anchorTo = (to: string, at: number): string =>
-    formatCommitMessage({ actor: "check", from: "pin", to, pin: "add", anchor: hashOf(at) })
+    formatCommitMessage({ actor: "check", from: "gtd:pin", to, pin: "add", anchor: hashOf(at) })
 
   // The old flow went idle → build → old; this one goes idle → build → check.
   const anchoredHistory = (): History =>
@@ -1345,11 +1345,31 @@ describe("replay: a repin's anchor", () => {
     const h = new History()
       .land("human", "idle", 1, "build", { "a.txt": "a" })
       .land("agent", "build", 1, "old")
-      .raw(anchorTo("unpin", 1))
+      .raw(anchorTo("gtd:unpin", 1))
     const outcome = await replayOf(async () => void (await human("idle")), h)
     expect(outcome.kind).toBe("ended")
   })
 
+  it("closes the process when a format 3 anchor names the unpin by its old name", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old")
+      .raw(`gtd(check): pin → unpin\n\nGtd-Pin: add\nGtd-Anchor: ${hashOf(1)}\nGtd-Format: 3`)
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind).toBe("ended")
+  })
+
+  it("reads a format 4 anchor naming unpin as a step", async () => {
+    const outcome = await replayOf(
+      async () => void (await human("idle")),
+      new History()
+        .land("human", "idle", 1, "build", { "a.txt": "a" })
+        .land("agent", "build", 1, "old")
+        .raw(anchorTo("unpin", 1)),
+    )
+    expect(outcome).toMatchObject({ kind: "divergence", reached: undefined })
+  })
+
   it("fails when it names no commit replay reads", async () => {
     const h = anchoredHistory().raw(anchorTo("build", 2))
     const outcome = await replayOf(async () => void (await human("idle")), h)

package/src/replay/Replay.ts

@@ -29,10 +29,14 @@ import {
   type CommitMessage,
   type JudgeVerdict,
   type StepId,
-  PIN_STATES,
+  ENGINE_PREFIX,
+  pinStateIn,
 } from "./Trailers.js"
 
-const UNPIN_STATE = PIN_STATES.remove
+const namesUnpin = (commit: ParsedCommit): boolean => {
+  const unpin = pinStateIn(commit.parsed.format, "remove")
+  return unpin !== undefined && commit.parsed.parsed?.to === unpin
+}
 
 export interface EpisodeCommit {
   readonly hash: string
@@ -402,7 +406,7 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       position = commit
       const to = commit.parsed.parsed?.to
       expectedNext =
-        to === undefined || to === UNPIN_STATE ? undefined : { name: to, hash: commit.hash }
+        to === undefined || namesUnpin(commit) ? undefined : { name: to, hash: commit.hash }
       anchorPending = expectedNext !== undefined
     }
   }
@@ -672,7 +676,7 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   // A turn that ends a pinned process names the unpin, which is no step.
   const expectNextOf = (commit: ParsedCommit): void => {
     const to = commit.parsed.parsed?.to
-    if (to !== undefined && to !== UNPIN_STATE) expectedNext = { name: to, hash: commit.hash }
+    if (to !== undefined && !namesUnpin(commit)) expectedNext = { name: to, hash: commit.hash }
   }
 
   const noteKept = (step: ReachedStep, commit: ParsedCommit): void => {
@@ -719,8 +723,8 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
 
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
-    if (Object.values(PIN_STATES).includes(scoped(request.name))) {
-      return `gtd: step "${scoped(request.name)}": the name is reserved for the pin and unpin beats — rename the step`
+    if (scoped(request.name).startsWith(ENGINE_PREFIX)) {
+      return `gtd: step "${scoped(request.name)}": the "${ENGINE_PREFIX}" prefix is reserved for gtd's own beats — rename the step`
     }
     if (request.kind === "run" && typeof request.body !== "string") {
       return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`

package/src/replay/Trailers.test.ts

@@ -46,7 +46,7 @@ describe("the commit-message codec", () => {
       reviewBase: "abc",
     })
     expect(message).toBe(
-      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 3",
+      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 4",
     )
     expect(parseCommitMessage(message).workflow).toBe("fix")
     expect(parseCommitMessage("gtd(human): fix-precheck").workflow).toBeUndefined()
@@ -56,7 +56,7 @@ describe("the commit-message codec", () => {
     const one = formatCommitMessage({ actor: "human", to: "x", vars: { b: "2", a: "1", c: "" } })
     const two = formatCommitMessage({ actor: "human", to: "x", vars: { c: "", a: "1", b: "2" } })
     expect(one).toBe(two)
-    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 3")
+    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 4")
     expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
   })
 
@@ -81,8 +81,8 @@ describe("the commit-message codec", () => {
   it("reads a Gtd-Version carrying control bytes as unknown, and keeps spaces and parens", () => {
     const withVersion = (value: string) =>
       formatCommitMessage({ actor: "a", to: "b" }).replace(
-        "Gtd-Format: 3",
-        `Gtd-Version: ${value}\nGtd-Format: 3`,
+        "Gtd-Format: 4",
+        `Gtd-Version: ${value}\nGtd-Format: 4`,
       )
     expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
     expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
@@ -100,18 +100,18 @@ describe("the commit-message codec", () => {
 
   it("writes the current Gtd-Format when branch and version are written", () => {
     const message = formatCommitMessage({ actor: "a", to: "b", branch: "m", version: "1" })
-    expect(message.endsWith("Gtd-Format: 3")).toBe(true)
+    expect(message.endsWith("Gtd-Format: 4")).toBe(true)
   })
 
   it("writes Gtd-Format last on every message, even one with no other trailer", () => {
     const message = formatCommitMessage({ actor: "agent", to: "building" })
-    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 3")
-    expect(parseCommitMessage(message).format).toBe(3)
+    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 4")
+    expect(parseCommitMessage(message).format).toBe(4)
   })
 
   it("reads a message without Gtd-Format as format 1, and an explicit one as written", () => {
     expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Step: a#1").format).toBe(1)
-    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: 3").format).toBe(3)
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: 4").format).toBe(4)
     expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: two").format).toBe(1)
   })
 
@@ -149,7 +149,7 @@ describe("Gtd-Kept", () => {
   it("reads undefined when absent, and leaves Gtd-Format at the current format", () => {
     const parsed = parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" }))
     expect(parsed.kept).toBeUndefined()
-    expect(parsed.format).toBe(3)
+    expect(parsed.format).toBe(4)
   })
 })
 
@@ -289,7 +289,7 @@ describe("Gtd-Mark", () => {
     const at = lines.findIndex((l) => l.startsWith("Gtd-Mark:"))
     expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
     expect(lines[at + 1]).toMatch(/^Gtd-Approved:/)
-    expect(lines).toContain("Gtd-Format: 3")
+    expect(lines).toContain("Gtd-Format: 4")
   })
 
   it("writes nothing without marks", () => {

package/src/replay/Trailers.ts

@@ -70,8 +70,30 @@ export interface Approval {
 
 export type PinChange = PinMark
 
+/** Step names a workflow may not take: gtd's own beats live under it. */
+export const ENGINE_PREFIX = "gtd:"
+
 /** What a pin and an unpin beat rest at, and their commits name — neither is a step of the workflow. */
-export const PIN_STATES: Readonly<Record<PinChange, string>> = { add: "pin", remove: "unpin" }
+export const PIN_STATES: Readonly<Record<PinChange, string>> = {
+  add: `${ENGINE_PREFIX}pin`,
+  remove: `${ENGINE_PREFIX}unpin`,
+}
+
+/** The names formats 2 and 3 gave the pin beats, before `gtd:` reserved them. */
+export const LEGACY_PIN_STATES: Readonly<Record<PinChange, string>> = {
+  add: "pin",
+  remove: "unpin",
+}
+
+const SCOPED_PIN_FORMAT = 4
+
+/** The name a commit in `format` gives a pin beat; format 1 has none. */
+export const pinStateIn = (format: number, change: PinChange): string | undefined =>
+  format >= SCOPED_PIN_FORMAT
+    ? PIN_STATES[change]
+    : format >= 2
+      ? LEGACY_PIN_STATES[change]
+      : undefined
 
 export interface CommitMessage {
   readonly subject: string

package/src/replay/index.ts

@@ -17,6 +17,7 @@ export {
   type CommitSpec,
   type JudgeVerdict,
   type PinChange,
+  LEGACY_PIN_STATES,
   PIN_STATES,
 } from "./Trailers.js"
 export { accessShapeFault } from "./Access.js"

package/src/steering/Declared.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it } from "vitest"
+import { formatFinding, listFormat, sectionFormat } from "./index.js"
+import { formatFromSpec, steeringFormatFor } from "./internal.js"
+
+const criteria = listFormat({
+  name: "criteria",
+  section: { title: /^acceptance criteria$/i, example: "Acceptance criteria", level: 2 },
+  item: { id: /^AC-\d+$/, separator: ":", example: "AC-1" },
+  ids: { unique: true },
+})
+
+const doc = (...lines: string[]): string => `${lines.join("\n")}\n`
+
+const problems = (format: { validate: (c: string) => readonly unknown[] }, content: string) =>
+  format.validate(content).map((f) => formatFinding("F.md", f as never))
+
+describe("listFormat", () => {
+  it("parses ID'd items, joining indented continuation lines", () => {
+    const parsed = criteria.parse(
+      doc(
+        "# Plan",
+        "",
+        "## Acceptance criteria",
+        "",
+        "- AC-1: first",
+        "  wrapped",
+        "- AC-2: second",
+        "",
+        "## Next",
+        "",
+        "- not read",
+      ),
+    )
+    expect(parsed.problems).toEqual([])
+    expect(parsed.items).toEqual([
+      { line: 4, id: "AC-1", text: "first wrapped" },
+      { line: 6, id: "AC-2", text: "second" },
+    ])
+  })
+
+  it("validates its own sample, and describes itself", () => {
+    expect(criteria.validate(criteria.sample)).toEqual([])
+    expect(criteria.sample).toBe("## Acceptance criteria\n\n- AC-1: Describe the item.\n")
+    expect(criteria.instructions).toContain("`## Acceptance criteria`")
+    expect(criteria.instructions).toContain("`AC-1`")
+  })
+
+  it("reports a missing, repeated or misleveled section", () => {
+    expect(problems(criteria, doc("# Plan"))).toEqual([
+      "missing the `## Acceptance criteria` section",
+    ])
+    expect(problems(criteria, doc("### Acceptance criteria", "", "- AC-1: a"))).toEqual([
+      'F.md:1: "Acceptance criteria" is a level-3 heading — write it as `## Acceptance criteria`',
+    ])
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "", "## Acceptance criteria"),
+      ),
+    ).toEqual(['F.md:5: "Acceptance criteria" repeats the section on line 1 — keep one'])
+  })
+
+  it("reports markers it does not allow, and mixed markers", () => {
+    const numbered = listFormat({ name: "steps", markers: ["-", "1."] })
+    expect(problems(criteria, doc("## Acceptance criteria", "", "* AC-1: a"))).toEqual([
+      "F.md:3: `*` is not an allowed marker — use `-`",
+    ])
+    expect(problems(numbered, doc("- a", "1. b"))).toEqual([
+      "F.md:2: `1.` mixes markers in one list — the list started with `-`",
+    ])
+  })
+
+  it("reads a numbered list it allows rather than parsing it as empty", () => {
+    const numbered = listFormat({ name: "signals", markers: ["1."] })
+    expect(numbered.parse(doc("1. a", "2. b")).items.map((i) => i.text)).toEqual(["a", "b"])
+  })
+
+  it("reports an unindented continuation line", () => {
+    expect(problems(criteria, doc("## Acceptance criteria", "", "- AC-1: a", "b"))).toEqual([
+      "F.md:4: continuation line is not indented — indent it under its item, or separate it with a blank line",
+    ])
+  })
+
+  it("never reads a fenced item, and reports an unclosed fence", () => {
+    const parsed = criteria.parse(
+      doc("## Acceptance criteria", "", "- AC-1: a", "", "```", "- AC-2: b", "```"),
+    )
+    expect(parsed.items.map((i) => i.id)).toEqual(["AC-1"])
+    expect(parsed.problems.map((p) => p.message)).toContain(
+      "a list item inside a code fence is not read as an item",
+    )
+    expect(
+      problems(criteria, doc("## Acceptance criteria", "", "- AC-1: a", "", "```", "x")),
+    ).toEqual(["F.md:5: code fence is never closed"])
+  })
+
+  it("keeps a fence indented under its item as part of the item", () => {
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "", "  ```", "  - x", "  ```", "- AC-2: b"),
+      ),
+    ).toEqual([])
+  })
+
+  it("reports duplicate and missing IDs, and empty items", () => {
+    expect(
+      problems(
+        criteria,
+        doc("## Acceptance criteria", "", "- AC-1: a", "- AC-1: b", "- c", "- AC-3:"),
+      ),
+    ).toEqual([
+      "F.md:4: duplicate ID AC-1 — first on line 3",
+      "F.md:5: item has no ID — start it `AC-1: …`",
+      "F.md:6: empty item — AC-3 has no text",
+    ])
+    expect(problems(listFormat({ name: "plain" }), doc("- a", "-"))).toEqual(["F.md:2: empty item"])
+  })
+
+  it("reports text between items and nesting", () => {
+    expect(
+      problems(
+        criteria,
+        doc(
+          "## Acceptance criteria",
+          "",
+          "- AC-1: a",
+          "",
+          "Aside.",
+          "",
+          "- AC-2: b",
+          "  - AC-3: c",
+        ),
+      ),
+    ).toEqual([
+      "F.md:5: text between items — make it part of an item, or move it out of the list",
+      "F.md:8: nested list — this format is flat, one level of items",
+    ])
+  })
+
+  it("forbids, strips or requires checkboxes", () => {
+    expect(problems(criteria, doc("## Acceptance criteria", "", "- [ ] AC-1: a"))).toEqual([
+      "F.md:3: no checkboxes in this list — drop the `[ ]`",
+    ])
+    const todo = listFormat({ name: "todo", checkbox: "require" })
+    expect(todo.parse(doc("- [x] a")).items).toEqual([{ line: 0, text: "a", checked: true }])
+    expect(problems(todo, doc("- a"))).toEqual([
+      "F.md:1: every item starts with a checkbox — write `- [ ] …`",
+    ])
+    const stripped = listFormat({ name: "stripped", checkbox: "strip" })
+    expect(stripped.parse(doc("- [ ] a", "- b")).items.map((i) => i.checked)).toEqual([
+      false,
+      false,
+    ])
+  })
+
+  it("forbids wrapping when told to", () => {
+    const flat = listFormat({ name: "flat", wrap: "forbid" })
+    expect(problems(flat, doc("- a", "  b"))).toEqual([
+      "F.md:2: one line per item — this line continues the one above",
+    ])
+  })
+
+  it("refuses an inconsistent declaration", () => {
+    expect(() => listFormat({ name: "Bad Name" })).toThrow("format name")
+    expect(() =>
+      listFormat({ name: "x", item: { id: /^A\d$/, separator: ":", example: "B1" } }),
+    ).toThrow("does not match")
+    expect(() => listFormat({ name: "x", section: { title: /a/, level: 2 } })).toThrow("example")
+  })
+})
+
+describe("sectionFormat", () => {
+  const findings = sectionFormat({ name: "notes", level: 2, title: "unique" })
+
+  it("parses sections with their bodies", () => {
+    expect(
+      findings.parse(doc("# T", "", "## A", "", "one", "### deeper", "## B")).sections,
+    ).toEqual([
+      { line: 2, title: "A", body: "one\n### deeper" },
+      { line: 6, title: "B", body: "" },
+    ])
+    expect(findings.validate(findings.sample)).toEqual([])
+  })
+
+  it("reports repeated titles, a shallower heading, and a heading in an unclosed fence", () => {
+    expect(problems(findings, doc("## A", "## a", "# Up", "```", "## C"))).toEqual([
+      'F.md:2: "a" repeats the section on line 1 — titles are unique',
+      'F.md:3: "Up" is a level-1 heading — sections are `##`',
+      "F.md:4: code fence is never closed",
+    ])
+  })
+})
+
+describe("formatFromSpec", () => {
+  it("rebuilds the same format from its spec, RegExps included", () => {
+    const rebuilt = formatFromSpec(criteria.spec)
+    const content = doc("## Acceptance criteria", "", "- AC-1: a", "- AC-1: b", "* x")
+    expect(rebuilt.name).toBe("criteria")
+    expect(rebuilt.validate(content)).toEqual(criteria.validate(content))
+    const notes = sectionFormat({ name: "notes", level: 2, title: "unique" })
+    expect(formatFromSpec(notes.spec).validate("## A\n## A\n")).toEqual(
+      notes.validate("## A\n## A\n"),
+    )
+  })
+
+  it("throws on a spec no declaration produces", () => {
+    expect(() => formatFromSpec('{"kind":"nope"}')).toThrow("not a declared format spec")
+  })
+})
+
+describe("the built-in formats", () => {
+  it("are not declared formats — none of these rules apply to them", () => {
+    expect(
+      steeringFormatFor("findings")!.validate("## A\n\n- [ ] fix\n\n## A\n\n- [ ] fix\n"),
+    ).toEqual([])
+  })
+})