@pmelab/gtd 27.7.0 → 27.8.0

package/src/replay/Replay.test.ts

@@ -15,6 +15,7 @@ import {
   restart,
   run,
   scope,
+  slice,
   threads,
   type Flow,
   type ScopeAccess,
@@ -1210,3 +1211,139 @@ describe("human({ approve })", () => {
     expect(outcome.kind).toBe("rest")
   })
 })
+
+describe("slice()", () => {
+  const spansOf = (o: ReplayOutcome) => (o as { slices: unknown }).slices
+
+  it("records enteredAt and leftAt as the commit replay stood on", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("refactor", async () => {
+        await human("b")
+      })
+      await human("c")
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "c")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "rest" })
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(1), leftAt: hashOf(2) },
+    ])
+  })
+
+  it("keeps leftAt undefined when the process rests inside the slice", async () => {
+    const wf = async () => {
+      await slice("refactor", async () => {
+        await human("a")
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(0), leftAt: undefined },
+    ])
+  })
+
+  it("records enteredAt === leftAt for a slice that landed no commit", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("empty", async () => undefined)
+      await human("b")
+    }
+    const h = new History().land("human", "a", 1, "b")
+    expect(spansOf(await replayOf(wf, h))).toEqual([
+      { name: "empty", enteredAt: hashOf(1), leftAt: hashOf(1) },
+    ])
+  })
+
+  it("prefixes no step name and ignores an enclosing scope", async () => {
+    const wf = async () => {
+      await scope("build", async () => {
+        await slice("refactor", async () => {
+          await human("gate")
+        })
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(outcome).toMatchObject({ kind: "rest", rest: { name: "build.gate" } })
+    expect((spansOf(outcome) as { name: string }[])[0]!.name).toBe("refactor")
+  })
+
+  const failed = async (wf: Flow) => {
+    const outcome = await replayOf(wf, new History())
+    expect(outcome.kind).toBe("failed")
+    return (outcome as { message: string }).message
+  }
+
+  it.each(["Refactor", "step_1", "v2.api", ""])("refuses the name %j", async (name) => {
+    expect(await failed(async () => slice(name, async () => human("a")))).toBe(
+      `gtd: slice "${name}": name must match /^[a-z][a-z0-9-]*$/`,
+    )
+  })
+
+  it("accepts refactor-2", async () => {
+    const outcome = await replayOf(
+      async () => slice("refactor-2", async () => human("a")),
+      new History(),
+    )
+    expect(outcome.kind).toBe("rest")
+  })
+
+  it("refuses the reserved name main", async () => {
+    expect(await failed(async () => slice("main", async () => human("a")))).toBe(
+      'gtd: slice "main" is reserved for the implicit slice',
+    )
+  })
+
+  it("refuses nesting, also through scope()", async () => {
+    const message = 'gtd: slice "inner" is entered inside slice "outer" — slices do not nest'
+    expect(
+      await failed(async () => slice("outer", async () => slice("inner", async () => human("a")))),
+    ).toBe(message)
+    expect(
+      await failed(async () =>
+        slice("outer", async () => scope("s", async () => slice("inner", async () => human("a")))),
+      ),
+    ).toBe(message)
+  })
+
+  it("checks the name rule before main and nesting", async () => {
+    expect(
+      await failed(async () => slice("outer", async () => slice("Main", async () => human("a")))),
+    ).toBe('gtd: slice "Main": name must match /^[a-z][a-z0-9-]*$/')
+  })
+
+  it("lets a flow that caught an error from a slice enter another", async () => {
+    const wf = async () => {
+      try {
+        await slice("a", async () => {
+          throw new Error("boom")
+        })
+      } catch {}
+      await slice("b", async () => human("x"))
+    }
+    expect(await replayOf(wf, new History())).toMatchObject({ kind: "rest" })
+  })
+
+  it("refuses a non-string name", async () => {
+    expect(
+      await failed(async () => slice(undefined as unknown as string, async () => human("a"))),
+    ).toContain("name must match")
+  })
+
+  it("refuses a name entered twice, sequentially and from a loop", async () => {
+    const message =
+      'gtd: slice "again" is entered twice in this episode — a loop must sit inside its slice'
+    expect(
+      await failed(async () => {
+        await slice("again", async () => undefined)
+        await slice("again", async () => human("a"))
+      }),
+    ).toBe(message)
+    expect(
+      await failed(async () => {
+        for (let i = 0; i < 2; i++) await slice("again", async () => undefined)
+        await human("a")
+      }),
+    ).toBe(message)
+  })
+})

package/src/replay/Replay.ts

@@ -23,6 +23,7 @@ import {
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
+import { IMPLICIT_SLICE, SLICE_NAME, type SliceSpan } from "./Slices.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
 import {
   formatStepId,
@@ -117,6 +118,7 @@ export type ReplayOutcome =
       readonly landed: ReachedStep | undefined
       /** Marks the flow made after the pending turn's step resolved; [] without a pending turn. */
       readonly marks: readonly Mark[]
+      readonly slices: readonly SliceSpan[]
     }
   | {
       readonly kind: "ended"
@@ -297,6 +299,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   >()
   let landed: ReachedStep | undefined
   const marks: Mark[] = []
+  const slices: { name: string; enteredAt: string; leftAt: string | undefined }[] = []
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
   const settled = new Promise<void>((resolve) => {
@@ -558,7 +561,14 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
-      return finish({ kind: "rest", rest: step, trace, landed, marks })
+      return finish({
+        kind: "rest",
+        rest: step,
+        trace,
+        landed,
+        marks,
+        slices: slices.map((s) => ({ ...s })),
+      })
     }
     return landPending(step, input.pending)
   }
@@ -630,6 +640,34 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
       scopes.pop()
       scopeCallIds.pop()
     },
+    enterSlice: (name) => {
+      if (outcome !== undefined) return
+      const fail = (message: string): never => {
+        void finish({ kind: "failed", message })
+        throw new Stop()
+      }
+      if (typeof name !== "string" || !SLICE_NAME.test(name)) {
+        fail(`gtd: slice "${name}": name must match ${SLICE_NAME}`)
+      }
+      if (name === IMPLICIT_SLICE) {
+        fail(`gtd: slice "${IMPLICIT_SLICE}" is reserved for the implicit slice`)
+      }
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) {
+        fail(`gtd: slice "${name}" is entered inside slice "${open.name}" — slices do not nest`)
+      }
+      if (slices.some((s) => s.name === name)) {
+        fail(
+          `gtd: slice "${name}" is entered twice in this episode — a loop must sit inside its slice`,
+        )
+      }
+      slices.push({ name, enteredAt: position.hash, leftAt: undefined })
+    },
+    leaveSlice: () => {
+      if (outcome !== undefined) return
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) open.leftAt = position.hash
+    },
     read: (path) => position.tree.read(path),
     glob: (pattern) => position.tree.paths().filter((path) => globMatches(path, pattern)),
     changes: () => changesBetween(previousPosition.tree, position.tree),

package/src/replay/Slices.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest"
+import { sliceRanges, type SliceSpan } from "./Slices.js"
+
+const span = (name: string, enteredAt: string, leftAt?: string): SliceSpan => ({
+  name,
+  enteredAt,
+  leftAt,
+})
+const running = { base: "B", tip: "T" }
+
+describe("sliceRanges", () => {
+  it("two adjacent spans: first from episode.base to its leftAt, second from there to episode.tip", () => {
+    expect(sliceRanges([span("a", "B", "c2"), span("b", "c2", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c2", open: false },
+      { name: "b", base: "c2", tip: "T", open: true },
+    ])
+  })
+
+  it("a leading gap folds into the first range via episode.base", () => {
+    expect(sliceRanges([span("a", "c1", "c2")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("an inner gap folds into the next range: its base is the previous leftAt", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c3", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+  })
+
+  it("a trailing gap folds back: the last range's tip is the episode tip, and it stays open", () => {
+    expect(sliceRanges([span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("drops a closed empty span, first, middle and last, its neighbours absorbing the gap", () => {
+    expect(sliceRanges([span("e", "B", "B"), span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+    expect(
+      sliceRanges([span("a", "B", "c1"), span("e", "c2", "c2"), span("b", "c2", "c4")], running),
+    ).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("a", "B", "c1"), span("e", "c1", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("no spans, and only empty closed spans, each yield one open main range over the whole episode", () => {
+    const main = [{ name: "main", base: "B", tip: "T", open: true }]
+    expect(sliceRanges([], running)).toEqual(main)
+    expect(sliceRanges([span("e", "c1", "c1")], running)).toEqual(main)
+  })
+
+  it("an unleft empty span is kept and open", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("b", "T")], running)).toEqual([
+      { name: "b", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("rejects a pending turn's empty hash", () => {
+    expect(() => sliceRanges([span("a", "", "c1")], running)).toThrow("not a commit")
+    expect(() => sliceRanges([span("a", "c1", "")], running)).toThrow("not a commit")
+  })
+})

package/src/replay/Slices.ts

@@ -0,0 +1,45 @@
+export const IMPLICIT_SLICE = "main"
+
+/** Same shape as mark()'s name rule; kept local so @pmelab/gtd/flows publishes no regex. */
+export const SLICE_NAME = /^[a-z][a-z0-9-]*$/
+
+/** One slice() call as replay saw it. Hashes are the commit replay stood on; "" is a pending turn. */
+export interface SliceSpan {
+  readonly name: string
+  readonly enteredAt: string
+  /** undefined: the flow never left it — the process rests inside, or restart() fired inside. */
+  readonly leftAt: string | undefined
+}
+
+export interface SliceRange {
+  readonly name: string
+  /** Exclusive: the range is base..tip in git's sense. */
+  readonly base: string
+  readonly tip: string
+  /** The tip can still move: only the last range, since a rest is never past the episode's end. */
+  readonly open: boolean
+}
+
+/**
+ * Folds boundaries into ranges: each kept span's base is the previous kept
+ * span's `leftAt`, so a gap before a span belongs to it, and the last span
+ * runs to the episode tip. A closed span that landed nothing is dropped.
+ */
+export const sliceRanges = (
+  spans: readonly SliceSpan[],
+  episode: { readonly base: string; readonly tip: string },
+): readonly SliceRange[] => {
+  if (spans.some((s) => s.enteredAt === "" || s.leftAt === "")) {
+    throw new Error('sliceRanges: a pending turn\'s "" hash is not a commit')
+  }
+  const kept = spans.filter((s) => s.leftAt === undefined || s.enteredAt !== s.leftAt)
+  if (kept.length === 0) {
+    return [{ name: IMPLICIT_SLICE, base: episode.base, tip: episode.tip, open: true }]
+  }
+  return kept.map((s, i) => ({
+    name: s.name,
+    base: i === 0 ? episode.base : (kept[i - 1]!.leftAt ?? episode.base),
+    tip: i === kept.length - 1 ? episode.tip : (s.leftAt ?? episode.tip),
+    open: i === kept.length - 1,
+  }))
+}

package/src/replay/index.ts

@@ -12,3 +12,4 @@ export {
 export { accessShapeFault, foldAccess } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"
+export { sliceRanges, type SliceRange } from "./Slices.js"

package/src/workflows/feature/review.test.ts

@@ -509,13 +509,19 @@ describe("severity routing", () => {
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
     })
-    expect(run.gates).toEqual([false, true])
+    expect(run.gates).toEqual([true, true])
     expect(run.gateMessages[1]).toContain("NOT acted on")
     expect(run.gateMessages[1]).toContain("note-1")
     expect(run.gateMessages[0]).not.toContain("NOT acted on")
   })
 
-  it("a later gate does not accept a clean land after a deferral round with a nit", async () => {
+  it("the first round's gate accepts a clean land", async () => {
+    const run = await drive({ notes: ["add", "sub", "mul"] })
+    expect(run.gates.length).toBeGreaterThan(0)
+    expect(run.gates.every((g) => g)).toBe(true)
+  })
+
+  it("a later gate still accepts a clean land after a deferral round with a nit", async () => {
     const run = await drive({
       notes: ["add — quote", "sub — typo", "mul"],
       answers: {
@@ -527,7 +533,7 @@ describe("severity routing", () => {
     })
     expect(run.log).toContain("review.defer")
     expect(run.log.at(-1)).toBe("review.await-review")
-    expect(run.gates).toEqual([false, false])
+    expect(run.gates).toEqual([true, true])
   })
 
   it("a question and a could note in one round: the gate's base is the answering commit", async () => {

package/src/workflows/feature/review.ts

@@ -167,8 +167,8 @@ export const review = (
   escalations: EscalationCount = { rounds: 0 },
 ): Promise<kit.ReviewOutcome> => {
   const severities = new Map<string, Severity>()
-  // Armed by a defer-only round and spent at the very next gate; a fresh
-  // review (`reviewing`) disarms it, so a later gate never accepts a clean land.
+  // Armed by a defer-only round to pick the next gate's message; a fresh
+  // review (`reviewing`) disarms it.
   let deferred: readonly t.NoteInput[] = []
   return kit.review(base, {
     file: REVIEW,
@@ -184,7 +184,7 @@ export const review = (
       const notes = deferred
       deferred = []
       return notes.length > 0
-        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes), true)
+        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes))
         : awaitReview(b)
     },
     reviewMissing,

package/src/workflows/shared/steps.ts

@@ -117,7 +117,6 @@ export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
 export const awaitReview = (
   base: string,
   message = t.buildReviewAwaitReviewMessage(base),
-  acceptClean = false,
 ): Promise<void> =>
   human("review.await-review", {
     message,
@@ -125,7 +124,7 @@ export const awaitReview = (
     file: REVIEW,
     mode: "review",
     base,
-    ...(acceptClean ? { acceptClean } : {}),
+    acceptClean: true,
   })
 
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */

package/src/workflows/shared/tail.test.ts

@@ -38,8 +38,18 @@ const handOff = async (
   } = {},
 ) => {
   const log: string[] = []
+  const gates: boolean[] = []
   const scripts = new Map<string, string>()
   const files = new Map<string, string>()
+  const onReviewing = () => {
+    if (log.filter((n) => n === "review.reviewing").length > 1) throw new Error("re-review")
+    if (after !== "unwritten") files.set(REVIEW, reviewDoc("new add function"))
+  }
+  const onGate = (request: StepRequest) => {
+    if (request.kind === "human") gates.push(request.options.acceptClean === true)
+    if (after === "deleted") files.delete(REVIEW)
+    else if (after !== "unwritten") files.set(REVIEW, after)
+  }
   installContext(
     fixtureContext(
       { codeThreads: extra.codeThreads ?? [] },
@@ -48,14 +58,8 @@ const handOff = async (
           if (request.kind === "restart") return Promise.resolve()
           log.push(request.name)
           if (request.kind === "run") scripts.set(request.name, request.body)
-          if (request.name === "review.reviewing") {
-            if (log.filter((n) => n === "review.reviewing").length > 1) throw new Error("re-review")
-            if (after !== "unwritten") files.set(REVIEW, reviewDoc("new add function"))
-          }
-          if (request.name === "review.await-review") {
-            if (after === "deleted") files.delete(REVIEW)
-            else if (after !== "unwritten") files.set(REVIEW, after)
-          }
+          if (request.name === "review.reviewing") onReviewing()
+          if (request.name === "review.await-review") onGate(request)
           return Promise.resolve()
         },
         refuse: (message: string): never => {
@@ -96,7 +100,7 @@ const handOff = async (
     () => undefined,
     (e: unknown) => (e as Error).message,
   )
-  return { log, scripts, refusal }
+  return { log, scripts, refusal, gates }
 }
 
 describe("the hand-off review", () => {
@@ -105,6 +109,11 @@ describe("the hand-off review", () => {
     expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.closing"])
   })
 
+  it("the review gate accepts a clean landing", async () => {
+    const run = await handOff(reviewDoc("new add function"))
+    expect(run.gates).toEqual([true])
+  })
+
   it("a note ends the round with the review kept and the reviewer's version copied beside it", async () => {
     const run = await handOff(reviewDoc("new add function — rename it to sum"))
     expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.handing-off"])