@pmelab/gtd 23.2.0 → 24.1.0

package/src/testkit/cliIo.ts

@@ -0,0 +1,36 @@
+import type { CliIo, ToolCommands } from "../cli/index.js"
+import type { InMemRepo } from "./InMemRepo.js"
+import { testLayers } from "./Layers.js"
+
+export interface CapturedCliResult {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+export const makeCapturingCliIo = (
+  repo: InMemRepo,
+  env: Readonly<Record<string, string | undefined>> = {},
+  tools: Partial<ToolCommands["Type"]> = {},
+): { readonly io: CliIo; readonly result: () => CapturedCliResult } => {
+  let stdout = ""
+  let stderr = ""
+  let exitCode = 0
+  const io: CliIo = {
+    stdout: (chunk) => {
+      stdout += chunk
+    },
+    stderr: (chunk) => {
+      stderr += chunk
+    },
+    exit: (code) => {
+      exitCode = code
+    },
+    // `narrate: io.stderr` is the SAME sink `stderr` above already captures
+    // errors into — narration lands in the exact same buffer, exactly like a
+    // real invocation's narration and remediation share one fd.
+    layers: (verbose) =>
+      testLayers(repo, { env, narrate: (line) => (stderr += line), verbose, tools }),
+  }
+  return { io, result: () => ({ stdout, stderr, exitCode }) }
+}

package/src/testkit/index.ts

@@ -0,0 +1,9 @@
+export { runsItsScript, testRepo, type TestRepo } from "./TestRepo.js"
+export { InMemRepo } from "./InMemRepo.js"
+export { makeInMemoryWorkspaceOps, testLayers, type ScriptedCommand } from "./Layers.js"
+export { makeCapturingCliIo } from "./cliIo.js"
+export { applyEmittedScript } from "./EmittedScriptRecognizer.js"
+export { gitTiers, runGitServiceContract, runGitScriptContract } from "./GitTiers.js"
+export { strictGitOperations } from "./StrictGitOperations.js"
+export { fakeGitOperations } from "./FakeGitOperations.js"
+export type { TestkitWorld } from "./steps.js"

package/src/testkit/steps.ts

@@ -0,0 +1,177 @@
+// 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 {
+  Given,
+  QuickPickleWorld,
+  Then,
+  When,
+  setWorldConstructor,
+  type InfoConstructor,
+  type QuickPickleWorldInterface,
+} from "quickpickle"
+import assert from "node:assert"
+import type { TestContext } from "vitest"
+import { runsItsScript, testRepo, type Actor, type TestRepo } from "./TestRepo.js"
+
+export class TestkitWorld extends QuickPickleWorld {
+  // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
+  declare info: QuickPickleWorldInterface["info"]
+
+  constructor(context: TestContext, info: InfoConstructor) {
+    super(context, info)
+  }
+
+  private gtdConfig: string | undefined = undefined
+  private env: Record<string, string> = {}
+  /** Per step, what its scripted actor does, in the order the scenario declared it. */
+  actions = new Map<string, Actor[]>()
+  verdicts = new Map<string, string>()
+  private created: TestRepo | undefined = undefined
+
+  // The repository is created on first use and keeps the config and
+  // environment it was created with, so a later change to either is refused
+  // rather than silently ignored.
+  configure(config: string): void {
+    this.assertNotCreated("a gtd config")
+    this.gtdConfig = config
+  }
+
+  setEnv(name: string, value: string): void {
+    this.assertNotCreated(`the environment variable ${name}`)
+    this.env[name] = value
+  }
+
+  private assertNotCreated(what: string): void {
+    if (this.created !== undefined) {
+      throw new Error(`${what} must be set before any step that touches the repository`)
+    }
+  }
+
+  repo(): TestRepo {
+    if (this.gtdConfig === undefined)
+      throw new Error("no gtd config: add a `gtd config` step first")
+    return (this.created ??= testRepo({ workflow: this.gtdConfig, env: this.env }))
+  }
+
+  act(step: string, action: Actor): void {
+    this.actions.set(step, [...(this.actions.get(step) ?? []), action])
+  }
+
+  async drive(): Promise<void> {
+    const actors: Record<string, Actor> = {}
+    for (const [step, actions] of this.actions) {
+      actors[step] = async (beat, repo) => {
+        for (const action of actions) await action(beat, repo)
+      }
+    }
+    for (const [step, verdict] of this.verdicts) actors[step] = () => verdict
+    await this.repo().drive(actors)
+  }
+}
+
+setWorldConstructor(TestkitWorld)
+
+const withNewline = (content: string): string => (content.endsWith("\n") ? content : `${content}\n`)
+
+const args = (list: string): string[] => list.split(" ").filter((arg) => arg !== "")
+
+Given("a gtd config with:", (world: TestkitWorld, source: string) => {
+  world.configure(withNewline(source))
+})
+
+Given(
+  "an environment variable {string} set to {string}",
+  (world: TestkitWorld, name: string, value: string) => {
+    world.setEnv(name, value)
+  },
+)
+
+Given("a file {string} with:", (world: TestkitWorld, path: string, content: string) => {
+  world.repo().write(path, withNewline(content))
+})
+
+Given("the working tree is committed as {string}", (world: TestkitWorld, message: string) => {
+  world.repo().commit(message)
+})
+
+Given("step {string} changes nothing", (world: TestkitWorld, step: string) => {
+  world.act(step, () => undefined)
+})
+
+Given(
+  "step {string} writes {string} with:",
+  (world: TestkitWorld, step: string, path: string, content: string) => {
+    world.act(step, (_, repo) => repo.write(path, withNewline(content)))
+  },
+)
+
+Given("step {string} runs its script", (world: TestkitWorld, step: string) => {
+  world.act(step, runsItsScript)
+})
+
+Given("judge step {string} answers:", (world: TestkitWorld, step: string, verdict: string) => {
+  world.verdicts.set(step, String(verdict))
+})
+
+When("gtd starts workflow {string}", async (world: TestkitWorld, workflow: string) => {
+  await world.repo().start(workflow)
+})
+
+When(
+  "gtd starts workflow {string} with {string}",
+  async (world: TestkitWorld, workflow: string, list: string) => {
+    await world.repo().start(workflow, ...args(list))
+  },
+)
+
+When("gtd opens door {string}", async (world: TestkitWorld, door: string) => {
+  await world.repo().door(door)
+})
+
+When(
+  "gtd opens door {string} with {string}",
+  async (world: TestkitWorld, door: string, list: string) => {
+    await world.repo().door(door, ...args(list))
+  },
+)
+
+When("gtd lands", async (world: TestkitWorld) => {
+  await world.repo().land()
+})
+
+When("the process is driven", async (world: TestkitWorld) => {
+  await world.drive()
+})
+
+Then(
+  "opening door {string} is refused with {string}",
+  async (world: TestkitWorld, door: string, message: string) => {
+    await assert.rejects(world.repo().door(door), (error: Error) => error.message.includes(message))
+  },
+)
+
+Then("the process rests at {string}", async (world: TestkitWorld, step: string) => {
+  assert.strictEqual((await world.repo().next()).state, step)
+})
+
+Then("the resting step's content contains {string}", async (world: TestkitWorld, text: string) => {
+  const { content } = await world.repo().next()
+  assert.ok(content.includes(text), content)
+})
+
+Then("the last commit subject is {string}", (world: TestkitWorld, subject: string) => {
+  assert.strictEqual(world.repo().subjects().at(-1), subject)
+})
+
+Then("the commit subjects end with:", (world: TestkitWorld, list: string) => {
+  const expected = list.split("\n").filter((line) => line.trim() !== "")
+  assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
+})
+
+Then("{string} contains {string}", (world: TestkitWorld, path: string, text: string) => {
+  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
+})
+
+Then("{string} does not exist", (world: TestkitWorld, path: string) => {
+  assert.strictEqual(world.repo().read(path), undefined)
+})

package/src/testkit/testkit.feature

@@ -0,0 +1,65 @@
+Feature: testkit drives any workflow against the real engine
+
+  A workflow the scenario writes itself, never a shipped one: scripted actors
+  stand in for the agent, the check and the judge.
+
+  Background:
+    Given a gtd config with:
+      """
+      import { agent, human, judge, read, run } from "@pmelab/gtd/flows"
+
+      export const tiny = async () => {
+        await agent("plan", "Write PLAN.md.")
+        await run("check", "npm test > .gtd/FEEDBACK.md 2>&1 && rm .gtd/FEEDBACK.md")
+        if (read(".gtd/FEEDBACK.md") !== undefined) await agent("repair", "Make the suite pass.")
+        const { answers } = await judge("ready", {
+          questions: [{ id: "ready", primitive: "noul", instructions: "Ready?", criteria: "" }],
+          evidence: { plan: read("PLAN.md") ?? "" },
+        })
+        await human(answers.ready?.answer === "yes" ? "ship" : "rework")
+      }
+
+      export default tiny
+      """
+
+  Scenario: a green check goes straight to the judge, whose verdict picks the gate
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "check" changes nothing
+    And judge step "ready" answers:
+      """
+      [{ "id": "ready", "answer": true, "p": 0.9 }]
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "ship"
+    And the commit subjects end with:
+      """
+      gtd(human): plan
+      gtd(agent): plan → check
+      gtd(check): check → ready
+      gtd(judge): ready → ship
+      """
+    And "PLAN.md" contains "add two numbers"
+
+  Scenario: a red check sends the process to repair, and an unscripted step is where it rests
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "check" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "repair"
+    And the resting step's content contains "Make the suite pass."
+    And the last commit subject is "gtd(check): check → repair"
+
+  # Fails if run: proves the `workflows` project honours @skip.
+  @skip
+  Scenario: a scenario tagged @skip never runs
+    Then the process rests at "a step this workflow does not have"