@pmelab/gtd 59.0.1 → 60.1.0

package/src/gherkin/index.ts

@@ -1,6 +1,8 @@
 // Generic quickpickle steps over `testRepo`: they name no workflow, so any
 // workflow's `.feature` can use them. A workflow's own steps live beside it.
 import {
+  After,
+  AfterAll,
   Given,
   QuickPickleWorld,
   Then,
@@ -16,19 +18,38 @@ import { pathToFileURL } from "node:url"
 import {
   runsItsScript,
   testRepo,
-  type Actor,
   type CannedCommand,
+  type DriveOptions,
+  type ScriptedActor,
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
-import { assertContains, assertLacks, refusal, refusedWith, restDescription } from "./messages.js"
-
-// Kept off the class so the exported world's type stays as it is.
-const usedActors = new WeakMap<TestkitWorld, Set<string>>()
+import {
+  assertContains,
+  assertLacks,
+  assertRestsAt,
+  refusal,
+  refusedWith,
+  restDescription,
+  unreachedList,
+  type Unreached,
+} from "./messages.js"
+
+// Kept on quickpickle's per-feature `common`: which steps a Background scripted,
+// and whether any scenario reached each.
+const BACKGROUND_ACTORS = "gtdBackgroundActors"
+
+interface BackgroundActors {
+  readonly reached: Map<string, boolean>
+  // The feature file's vitest task, to tell whether every scenario ran.
+  file: { readonly tasks?: readonly unknown[] } | undefined
+}
 
 export class TestkitWorld extends QuickPickleWorld {
   // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
   declare info: QuickPickleWorldInterface["info"]
+  declare common: QuickPickleWorldInterface["common"]
+  declare context: TestContext
 
   constructor(context: TestContext, info: InfoConstructor) {
     super(context, info)
@@ -37,11 +58,16 @@ export class TestkitWorld extends QuickPickleWorld {
   private gtdConfig: WorkflowModule | undefined = undefined
   private env: Record<string, string> = {}
   private commands: CannedCommand[] = []
-  /** Per step, what its scripted actor does, in the order the scenario declared it. */
-  actions = new Map<string, Actor[]>()
-  verdicts = new Map<string, string>()
-  /** Per judge step, a verdict for each text its questions may contain; the first match answers. */
-  conditionalVerdicts = new Map<string, [text: string, verdict: string][]>()
+  private modules: Record<string, Readonly<Record<string, unknown>>> = {}
+  private actions = new Map<string, ScriptedActor[]>()
+  private verdicts = new Map<string, string>()
+  private conditionalVerdicts = new Map<string, [text: string, verdict: string][]>()
+  private prompts = new Map<string, string[]>()
+  private used = new Set<string>()
+  // A step a scenario step scripts is the scenario's, even if a Background scripted it too.
+  private origins = new Map<string, Unreached["origin"]>()
+  private backgroundScripted = new Set<string>()
+  private excused = new Set<string>()
   private created: TestRepo | undefined = undefined
 
   // The repository is created on first use and keeps the config and
@@ -70,6 +96,21 @@ export class TestkitWorld extends QuickPickleWorld {
     this.env[name] = value
   }
 
+  /** Unlike `setEnv`, also once the repository exists: gtd sees it from its next call on. */
+  changeEnv(name: string, value: string): void {
+    if (this.created === undefined) this.env[name] = value
+    else this.created.setEnv(name, value)
+  }
+
+  /**
+   * Lets a config given as source import `module` as `specifier`. A support
+   * file may call it for every scenario, e.g. from a `Before` hook.
+   */
+  importable(specifier: string, module: Readonly<Record<string, unknown>>): void {
+    this.assertNotCreated(`the module ${specifier}`)
+    this.modules[specifier] = module
+  }
+
   private assertNotCreated(what: string): void {
     if (this.created !== undefined) {
       throw new Error(`${what} must be set before any step that touches the repository`)
@@ -83,17 +124,87 @@ export class TestkitWorld extends QuickPickleWorld {
       workflow: this.gtdConfig,
       env: this.env,
       commands: this.commands,
+      modules: this.modules,
     }))
   }
 
-  act(step: string, action: Actor): void {
+  // quickpickle numbers a (Rule) Background's steps negatively.
+  private scripting(step: string, replace = false): void {
+    const fromBackground = (this.info.stepIdx ?? 0) < 0
+    if (fromBackground) this.backgroundScripted.add(step)
+    if (!fromBackground || replace || !this.origins.has(step))
+      this.origins.set(step, fromBackground ? "Background" : "scenario")
+  }
+
+  /** Adds `action` to what `step`'s actor does at every visit. */
+  act(step: string, action: ScriptedActor): void {
+    this.scripting(step)
     this.actions.set(step, [...(this.actions.get(step) ?? []), action])
   }
 
-  async drive(): Promise<void> {
-    const actors: Record<string, Actor> = {}
-    const used = usedActors.get(this) ?? new Set<string>()
-    usedActors.set(this, used)
+  /** Drops every action and prompt queued for `step`, leaving `action` alone. */
+  rescript(step: string, action: ScriptedActor): void {
+    this.scripting(step, true)
+    this.actions.set(step, [action])
+    this.prompts.delete(step)
+  }
+
+  /** Drops every action and prompt queued for `step`, so a drive rests there. */
+  unscript(step: string): void {
+    this.actions.delete(step)
+    this.prompts.delete(step)
+  }
+
+  /**
+   * `step`'s beat content must contain `text`. A scripted step is checked at
+   * every visit, before its actor acts; a step with nothing else scripted is
+   * not scripted at all, so a drive rests there and checks it at the rest.
+   */
+  expectPrompt(step: string, text: string): void {
+    this.scripting(step)
+    this.prompts.set(step, [...(this.prompts.get(step) ?? []), text])
+  }
+
+  /** Judge step `step` answers `verdict`, a JSON array. */
+  answer(step: string, verdict: string): void {
+    this.scripting(step)
+    this.verdicts.set(step, verdict)
+  }
+
+  /** Judge step `step` answers `verdict` when its questions contain `text`; the first match answers. */
+  answerWhen(step: string, text: string, verdict: string): void {
+    this.scripting(step)
+    this.conditionalVerdicts.set(step, [
+      ...(this.conditionalVerdicts.get(step) ?? []),
+      [text, verdict],
+    ])
+  }
+
+  private scripted(): Set<string> {
+    return new Set([
+      ...this.actions.keys(),
+      ...this.verdicts.keys(),
+      ...this.conditionalVerdicts.keys(),
+      ...this.prompts.keys(),
+    ])
+  }
+
+  /** The steps the scenario scripted, or expects a prompt at, that no drive has reached. */
+  neverUsed(): Unreached[] {
+    return [...this.scripted()]
+      .filter((step) => !this.used.has(step))
+      .map((step) => ({ step, origin: this.origins.get(step) ?? "scenario" }))
+  }
+
+  private checkPrompts(step: string, content: string): void {
+    for (const text of this.prompts.get(step) ?? []) {
+      if (!content.includes(text))
+        throw new Error(`step "${step}" was not prompted with "${text}":\n${content}`)
+    }
+  }
+
+  private actors(): Record<string, ScriptedActor> {
+    const actors: Record<string, ScriptedActor> = {}
     for (const [step, actions] of this.actions) {
       actors[step] = async (beat, repo) => {
         for (const action of actions) await action(beat, repo)
@@ -121,32 +232,106 @@ export class TestkitWorld extends QuickPickleWorld {
         return hit[1]
       }
     }
-    const tracked: Record<string, Actor> = {}
-    for (const [step, actor] of Object.entries(actors)) {
-      tracked[step] = (beat, repo) => {
-        used.add(step)
-        return actor(beat, repo)
+    return actors
+  }
+
+  /**
+   * `strict: false` lets what a strict drive refuses pass. Every drive leaves
+   * scripted steps it never reached to `assertReached`: an earlier step may
+   * script one for a later drive.
+   */
+  async drive(options: DriveOptions = {}): Promise<void> {
+    try {
+      const actors = this.actors()
+      const tracked: Record<string, ScriptedActor> = {}
+      for (const [step, actor] of Object.entries(actors)) {
+        tracked[step] = (beat, repo) => {
+          this.used.add(step)
+          this.checkPrompts(step, beat.content)
+          return actor(beat, repo)
+        }
+      }
+      const rest = await this.repo().drive(tracked, { ...options, unreachedActors: "pass" })
+      if (rest.kind !== "stalled" && this.prompts.has(rest.state) && !(rest.state in actors)) {
+        this.used.add(rest.state)
+        this.checkPrompts(rest.state, rest.content)
       }
+    } catch (error) {
+      // Where a refused drive would have gone is unknown, so every step it was handed is excused.
+      for (const step of this.scripted()) this.excused.add(step)
+      throw error
+    }
+  }
+
+  /**
+   * Fails on a step a scenario step scripted, or expects a prompt at, that no
+   * drive reached. Run at scenario end. A Background's steps are left to the
+   * feature's end, and the steps a refused drive was handed are excused.
+   */
+  async assertReached(): Promise<void> {
+    const never = this.neverUsed()
+    const dead = never.filter(
+      ({ step, origin }) => origin === "scenario" && !this.excused.has(step),
+    )
+    if (dead.length === 0) return
+    throw new Error(
+      `at scenario end, no drive reached the steps scripted for ${unreachedList(dead)} — script a step only for a drive that reaches it, or in the Background when only some scenarios reach it\n\n${await restDescription(() => this.repo(), never)}`,
+    )
+  }
+
+  /** Records, for the feature's end, which Background-scripted steps this scenario reached. */
+  recordBackground(): void {
+    const record = (this.common[BACKGROUND_ACTORS] ??= {
+      reached: new Map(),
+      file: undefined,
+    }) as BackgroundActors
+    record.file ??= (this.context as Partial<TestContext> | undefined)?.task?.file
+    // A failed scenario stopped early, so it cannot tell a dead actor from one it did not get to.
+    const failed = this.info.errors.length > 0
+    for (const step of this.backgroundScripted) {
+      record.reached.set(step, record.reached.get(step) === true || failed || this.used.has(step))
     }
-    await this.repo().drive(tracked)
   }
 }
 
+After(async (world: QuickPickleWorldInterface) => {
+  if (!(world instanceof TestkitWorld)) return
+  world.recordBackground()
+  // Only for a scenario whose steps all passed: a failed one already reports.
+  if (world.info.errors.length === 0) await world.assertReached()
+})
+
+// vitest marks a test it filtered out, or skipped, as not run.
+const allRan = (tasks: readonly unknown[]): boolean =>
+  tasks.every((task) => {
+    const t = task as { mode?: string; result?: { state?: string }; tasks?: readonly unknown[] }
+    if (t.tasks !== undefined) return allRan(t.tasks)
+    return t.mode === "run" && t.result?.state !== "skip"
+  })
+
+// Per feature: a Background step no scenario reached scripts nothing. Left out
+// when a scenario did not run, since it may be the one that reaches it.
+AfterAll((common: QuickPickleWorldInterface["common"]) => {
+  const record = common[BACKGROUND_ACTORS] as BackgroundActors | undefined
+  if (record === undefined) return
+  if (record.file?.tasks !== undefined && !allRan(record.file.tasks)) return
+  const dead = [...record.reached].filter(([, reached]) => !reached)
+  if (dead.length === 0) return
+  throw new Error(
+    `${common.info.feature}: no scenario reached the steps scripted for ${unreachedList(dead.map(([step]) => ({ step, origin: "Background" })))} — script a step in the Background only when some scenario reaches it`,
+  )
+})
+
 setWorldConstructor(TestkitWorld)
 
 const withNewline = (content: string): string => (content.endsWith("\n") ? content : `${content}\n`)
 
-const args = (list: string): string[] => list.split(" ").filter((arg) => arg !== "")
-
-const neverUsed = (world: TestkitWorld): string[] => {
-  const used = usedActors.get(world) ?? new Set<string>()
-  const scripted = new Set([
-    ...world.actions.keys(),
-    ...world.verdicts.keys(),
-    ...world.conditionalVerdicts.keys(),
-  ])
-  return [...scripted].filter((step) => !used.has(step))
-}
+// Space-separated; a word that opens with a quote runs to its closing quote,
+// spaces included, so `--var 'title=a b'` is two arguments.
+const args = (list: string): string[] =>
+  [...list.matchAll(/(["'])(.*?)\1(?=\s|$)|\S+/g)].map(([word, quote, inner]) =>
+    quote === undefined ? word : inner!,
+  )
 
 /** An outcome step: a failure ends with where the process rests. */
 const outcome =
@@ -156,7 +341,7 @@ const outcome =
       await check(world, ...rest)
     } catch (error) {
       const failure = error instanceof Error ? error : new Error(String(error))
-      failure.message += `\n\n${await restDescription(() => world.repo(), neverUsed(world))}`
+      failure.message += `\n\n${await restDescription(() => world.repo(), world.neverUsed())}`
       throw failure
     }
   }
@@ -177,12 +362,27 @@ Given("the gtd config ends with:", (world: TestkitWorld, source: string) => {
 })
 
 Given(
-  "an environment variable {string} set to {string}",
+  "the environment variable {string} is {string}",
   (world: TestkitWorld, name: string, value: string) => {
     world.setEnv(name, value)
   },
 )
 
+Given(
+  "from now on the environment variable {string} is {string}",
+  (world: TestkitWorld, name: string, value: string) => {
+    world.changeEnv(name, value)
+  },
+)
+
+// Imported by the test runner, like `a gtd config from the module`.
+Given(
+  "the module {string} is importable as {string}",
+  async (world: TestkitWorld, path: string, specifier: string) => {
+    world.importable(specifier, { ...(await import(pathToFileURL(resolve(path)).href)) })
+  },
+)
+
 Given("the command {string} exits {int}", (world: TestkitWorld, run: string, exit: number) => {
   world.command({ run, exit })
 })
@@ -194,10 +394,28 @@ Given(
   },
 )
 
+Given(
+  "the command matching {string} exits {int}",
+  (world: TestkitWorld, pattern: string, exit: number) => {
+    world.command({ run: new RegExp(pattern), exit })
+  },
+)
+
+Given(
+  "the command matching {string} exits {int} with:",
+  (world: TestkitWorld, pattern: string, exit: number, output: string) => {
+    world.command({ run: new RegExp(pattern), exit, output: withNewline(output) })
+  },
+)
+
 Given("a branch {string}", (world: TestkitWorld, name: string) => {
   world.repo().branch(name)
 })
 
+Given("a branch {string} at {string}", (world: TestkitWorld, name: string, ref: string) => {
+  world.repo().branch(name, ref)
+})
+
 Given("{string} is checked out", (world: TestkitWorld, name: string) => {
   world.repo().checkout(name)
 })
@@ -227,7 +445,7 @@ Given(
   },
 )
 
-Given("{string} gets appended:", (world: TestkitWorld, path: string, text: string) => {
+Given("text is appended to {string}:", (world: TestkitWorld, path: string, text: string) => {
   const content = world.repo().read(path) ?? ""
   world.repo().write(path, `${content.trimEnd()}\n\n${text}\n`)
 })
@@ -246,12 +464,12 @@ Given("step {string} changes nothing", (world: TestkitWorld, step: string) => {
 
 // Unlike `changes nothing`, this drops every action already queued for the step.
 Given("step {string} from now on changes nothing", (world: TestkitWorld, step: string) => {
-  world.actions.set(step, [() => undefined])
+  world.rescript(step, () => undefined)
 })
 
 // Lets a later visit rest at a step an earlier one had scripted.
 Given("step {string} is no longer scripted", (world: TestkitWorld, step: string) => {
-  world.actions.delete(step)
+  world.unscript(step)
 })
 
 Given(
@@ -299,23 +517,19 @@ Given("step {string} deletes {string}", (world: TestkitWorld, step: string, path
   world.act(step, (_, repo) => repo.remove(path))
 })
 
-// A standing assertion like any queued action: it applies on every later visit
-// to the step until `from now on` clears the list.
+// A standing assertion: it applies on every later visit to the step until
+// `from now on` or `no longer scripted` clears it.
 Given(
   "step {string} is prompted with {string}",
   (world: TestkitWorld, step: string, text: string) => {
-    world.act(step, (beat) => {
-      if (!beat.content.includes(text)) {
-        throw new Error(`step "${step}" was not prompted with "${text}":\n${beat.content}`)
-      }
-    })
+    world.expectPrompt(step, text)
   },
 )
 
 // A closing step deletes the file before its collecting turn runs, so this edit
 // leaves a closed turn changing nothing while still answering an in-gate one.
 Given(
-  "step {string} rewrites {string} with:",
+  "step {string} overwrites {string}, if it exists, with:",
   (world: TestkitWorld, step: string, path: string, content: string) => {
     world.act(step, (_, repo) => {
       if (repo.read(path) !== undefined) repo.write(path, withNewline(content))
@@ -327,17 +541,31 @@ Given("step {string} runs its script", (world: TestkitWorld, step: string) => {
   world.act(step, runsItsScript)
 })
 
+/** A check step's script, every command it runs answering as `command` does. */
+const checkRuns = (world: TestkitWorld, step: string, command: Omit<CannedCommand, "run">) => {
+  world.act(step, (beat, repo) => {
+    if (beat.actor !== "check")
+      throw new Error(`step "${step}" is no check step; its actor is ${beat.actor}`)
+    repo.runScript(beat.content, { commands: [{ ...command, run: /[\s\S]*/ }] })
+  })
+}
+
+Given("check step {string} passes", (world: TestkitWorld, step: string) => {
+  checkRuns(world, step, {})
+})
+
+Given("check step {string} fails with:", (world: TestkitWorld, step: string, output: string) => {
+  checkRuns(world, step, { exit: 1, output: withNewline(output) })
+})
+
 Given("judge step {string} answers:", (world: TestkitWorld, step: string, verdict: string) => {
-  world.verdicts.set(step, String(verdict))
+  world.answer(step, String(verdict))
 })
 
 Given(
   "judge step {string}, when its questions contain {string}, answers:",
   (world: TestkitWorld, step: string, text: string, verdict: string) => {
-    world.conditionalVerdicts.set(step, [
-      ...(world.conditionalVerdicts.get(step) ?? []),
-      [text, String(verdict)],
-    ])
+    world.answerWhen(step, text, String(verdict))
   },
 )
 
@@ -371,6 +599,10 @@ When("the process is driven", async (world: TestkitWorld) => {
   await world.drive()
 })
 
+When("the process is driven leniently", async (world: TestkitWorld) => {
+  await world.drive({ strict: false })
+})
+
 Then(
   "opening door {string} is refused with {string}",
   outcome(async (world, door: string, message: string) => {
@@ -411,7 +643,56 @@ Then(
 Then(
   "the process rests at {string}",
   outcome(async (world, step: string) => {
-    assert.strictEqual((await world.repo().next()).state, step)
+    assertRestsAt(await world.repo().next(), step)
+  }),
+)
+
+Then(
+  "the process stalls at {string}",
+  outcome(async (world, step: string) => {
+    const beat = await world.repo().next()
+    if (beat.kind !== "stalled" || beat.state !== step)
+      assert.fail(
+        `expected a stall at "${step}", but the process rests at "${beat.state}" (${beat.kind})`,
+      )
+  }),
+)
+
+/** A beat field by its dotted path (`model`, `access.write`), as text: a string as is, anything else as JSON. */
+const beatField = async (world: TestkitWorld, path: string): Promise<unknown> => {
+  let value: unknown = await world.repo().next()
+  for (const key of path.split(".")) {
+    value =
+      typeof value === "object" && value !== null
+        ? (value as Record<string, unknown>)[key]
+        : undefined
+  }
+  return value
+}
+
+const asText = (value: unknown): string =>
+  typeof value === "string" ? value : (JSON.stringify(value) ?? "undefined")
+
+Then(
+  "the resting step's {word} is {string}",
+  outcome(async (world, path: string, expected: string) => {
+    const value = asText(await beatField(world, path))
+    if (value !== expected)
+      assert.fail(`the resting step's ${path} is not "${expected}"; it is:\n${value}`)
+  }),
+)
+
+Then(
+  "the resting step's {word} includes {string}",
+  outcome(async (world, path: string, expected: string) => {
+    const value = await beatField(world, path)
+    const found = Array.isArray(value)
+      ? value.some((item) => asText(item) === expected)
+      : typeof value === "string" && value.includes(expected)
+    if (!found)
+      assert.fail(
+        `the resting step's ${path} does not include "${expected}"; it is:\n${asText(value)}`,
+      )
   }),
 )
 
@@ -454,6 +735,37 @@ Then(
   }),
 )
 
+Then(
+  "the last commit body contains {string}",
+  outcome((world, text: string) => {
+    assertContains("the last commit's message", text, world.repo().messages().at(-1))
+  }),
+)
+
+// Every commit with the subject, so a repeated step is not judged by its first match.
+Then(
+  "the commit {string} has a body containing {string}",
+  outcome((world, subject: string, text: string) => {
+    const matching = world
+      .repo()
+      .commits()
+      .filter((commit) => commit.subject === subject)
+    assert.ok(matching.length > 0, `no commit "${subject}"`)
+    for (const { message } of matching) assertContains(`the commit "${subject}"`, text, message)
+  }),
+)
+
+Then(
+  "no commit body contains {string}",
+  outcome((world, text: string) => {
+    const hit = world
+      .repo()
+      .messages()
+      .find((message) => message.includes(text))
+    if (hit !== undefined) assert.fail(`a commit's message contains "${text}":\n${hit}`)
+  }),
+)
+
 const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
   const result = await world.repo().gtd(...args(list))
   assert.strictEqual(result.exitCode, 0, result.stderr)
@@ -509,6 +821,13 @@ Then(
   }),
 )
 
+Then(
+  "{string} as committed at {string} contains {string}",
+  outcome((world, path: string, ref: string, text: string) => {
+    assertContains(`"${path}" at ${ref}`, text, world.repo().show(ref, path))
+  }),
+)
+
 Then(
   "{string} contains {string} exactly once",
   outcome((world, path: string, text: string) => {

package/src/gherkin/messages.test.ts

@@ -1,7 +1,13 @@
 import { describe, expect, it } from "vitest"
-import { agent, human } from "../flows/index.js"
+import { agent, human, workflow } from "../flows/index.js"
 import { testRepo } from "../testkit/index.js"
-import { assertContains, assertLacks, refusedWith, restDescription } from "./messages.js"
+import {
+  assertContains,
+  assertLacks,
+  assertRestsAt,
+  refusedWith,
+  restDescription,
+} from "./messages.js"
 
 const flow = async (): Promise<void> => {
   await agent("plan", "Write PLAN.md.\nKeep it short.\n3\n4\n5\n6\n7")
@@ -22,7 +28,15 @@ describe("restDescription", () => {
     const repo = testRepo({ workflow: { default: flow } })
     repo.write("go", "\n")
     await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
-    expect(await restDescription(() => repo, ["repair", "ready"])).toBe(
+    expect(
+      await restDescription(
+        () => repo,
+        [
+          { step: "repair", origin: "scenario" },
+          { step: "ready", origin: "Background" },
+        ],
+      ),
+    ).toBe(
       [
         "where the process rests:",
         '  step "sign-off" (message, human)',
@@ -31,7 +45,7 @@ describe("restDescription", () => {
         "  last commits:",
         "    chore: initial commit",
         "    gtd(agent): plan → sign-off",
-        '  actors never used: "repair", "ready"',
+        '  actors never used: "repair" (scenario), "ready" (Background)',
       ].join("\n"),
     )
   })
@@ -88,3 +102,23 @@ describe("contains", () => {
     expect(await thrown(() => assertLacks('"a.md"', "x", undefined))).toBe('"a.md" does not exist')
   })
 })
+
+describe("assertRestsAt", () => {
+  it("fails on a stall at the step, pointing to the stall assertion", async () => {
+    const repo = testRepo({ workflow: { default: flow, flow: workflow(flow) } })
+    await repo.start("flow")
+    const stall = await repo.drive({ plan: () => undefined })
+    expect(stall.kind).toBe("stalled")
+    expect(await thrown(() => assertRestsAt(stall, "plan"))).toBe(
+      'expected a rest at "plan", but the process stalls at "plan" — assert a stall with: the process stalls at "plan"',
+    )
+  })
+
+  it("passes at a rest at the step, and fails at another", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    const rest = await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    assertRestsAt(rest, "sign-off")
+    expect(await thrown(() => assertRestsAt(rest, "plan"))).toContain("sign-off")
+  })
+})