@pmelab/gtd 58.0.0 → 58.2.0

package/src/testkit/TestRepo.ts

@@ -2,10 +2,14 @@ import { Effect } from "effect"
 import { PassThrough } from "node:stream"
 import { runCli } from "../cli/index.js"
 import { EXIT_OK, type BeatDocument } from "../wire/index.js"
-import { makeCapturingCliIo, type CapturedCliResult } from "./cliIo.js"
-import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
-import { applyFlowScript } from "./FlowScripts.js"
-import { InMemRepo } from "./InMemRepo.js"
+import {
+  applyEmittedScript,
+  applyFlowScript,
+  InMemRepo,
+  makeCapturingCliIo,
+  type CapturedCliResult,
+  type CommandTable,
+} from "../twins/index.js"
 
 /**
  * The repository's `gtd.config.ts`: its source, or the module itself. A module
@@ -15,8 +19,23 @@ import { InMemRepo } from "./InMemRepo.js"
  */
 export type WorkflowModule = string | Readonly<Record<string, unknown>>
 
+/**
+ * What a command a step's script runs does in memory. `run` matches the command
+ * as the script spells it, exactly or by a pattern; the first match wins.
+ */
+export interface CannedCommand {
+  readonly run: string | RegExp
+  /** Defaults to 0. */
+  readonly exit?: number
+  readonly output?: string
+  /** What the command does to the tree, e.g. a formatter's rewrite. */
+  readonly effect?: (repo: TestRepo) => void
+}
+
 export interface TestRepoOptions {
   readonly workflow: WorkflowModule
+  /** The commands a step's script may run. A command none matches fails the script. */
+  readonly commands?: readonly CannedCommand[]
   /** Committed alongside the config, before any process starts. */
   readonly files?: Readonly<Record<string, string>>
   /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
@@ -39,6 +58,15 @@ export interface DriveOptions {
 }
 
 export interface TestRepo {
+  /** Adds a command a step's script may run, after those `testRepo` was given. */
+  command(command: CannedCommand): void
+  /** Creates branch `name` at `ref` (HEAD by default). Outside a process only. */
+  branch(name: string, ref?: string): void
+  /** Checks branch `name` out; refuses with uncommitted changes. Outside a process only. */
+  checkout(name: string): void
+  /** Points ref `name` (`refs/remotes/origin/main`, `refs/tags/v1`) at `ref` (HEAD by default). Outside a process only. */
+  ref(name: string, ref?: string): void
+  branchName(): string
   read(path: string): string | undefined
   write(path: string, content: string): void
   remove(path: string): void
@@ -155,19 +183,21 @@ const LINES: ReadonlyArray<readonly [RegExp, (repo: InMemRepo, words: string[])
 const knownLine = (line: string) => LINES.find(([pattern]) => pattern.test(line))
 
 const cannotRun = (error: string): Error =>
-  new Error(`testkit: cannot run script in memory — give the step an actor instead\n${error}`)
+  new Error(
+    `testkit: cannot run script in memory — add a canned command for it, or give the step an actor\n${error}`,
+  )
 
 // A script with a line `LINES` lacks goes to the contract-tested recognizers
 // whole, minus the git builders: they would apply a commit/reset/update-ref in
 // memory, so any git-mutating block is refused whatever its spelling.
-const runLines = (repo: InMemRepo, script: string): void => {
+const runLines = (repo: InMemRepo, commands: CommandTable, script: string): void => {
   const lines = script.split("\n").map((line) => line.trim())
   const known = lines.map(knownLine)
   if (known.every(Boolean)) {
     known.forEach((k, i) => k![1](repo, words(lines[i]!)))
     return
   }
-  const applied = applyEmittedScript(repo, new Map(), script, { git: false })
+  const applied = applyEmittedScript(repo, commands, script, { git: false })
   if (!applied.ok) throw cannotRun(applied.error ?? "")
 }
 
@@ -186,6 +216,18 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
   repo.seedCommit("chore: initial commit")
 
+  const canned = [...(options.commands ?? [])]
+  const commands: CommandTable = {
+    get: (command) => {
+      const hit = canned.find(({ run }) =>
+        typeof run === "string" ? run === command : run.test(command),
+      )
+      if (hit === undefined) return undefined
+      const { exit = 0, output = "", effect } = hit
+      return { kind: "exit", status: exit, output, effect: () => effect?.(self) }
+    },
+  }
+
   // The module is registered only while gtd runs, so nothing outlives the
   // call that loads it and no test can reach another's module.
   const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
@@ -214,7 +256,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
 
   const apply = (what: string, script: string): void => {
     if (script.length === 0) return
-    const applied = applyEmittedScript(repo, new Map(), script)
+    const applied = applyEmittedScript(repo, commands, script)
     if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`)
   }
 
@@ -257,14 +299,26 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   const self: TestRepo = {
+    command: (command) => {
+      canned.push(command)
+    },
+    branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
+    checkout: (name) => repo.checkoutBranch(name),
+    ref: (name, ref = "HEAD") => {
+      if (!name.startsWith("refs/")) throw new Error(`testkit: ref "${name}" must start with refs/`)
+      const hash = repo.resolveRef(ref)
+      if (hash === null) throw new Error(`testkit: ref "${ref}" resolves to no commit`)
+      repo.updateRef(name, hash)
+    },
+    branchName: () => repo.branchName(),
     read: (path) => repo.readFile(path),
     write: (path, content) => repo.writeFile(path, content),
     remove: (path) => repo.deleteFile(path),
     commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
-      const flow = applyFlowScript(repo, new Map(), script)
-      if (flow === undefined) runLines(repo, script)
+      const flow = applyFlowScript(repo, commands, script)
+      if (flow === undefined) runLines(repo, commands, script)
       else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,

package/src/testkit/index.ts

@@ -1,9 +1,16 @@
-export { runsItsScript, testRepo, type Actor, 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, type GitTier } from "./GitTiers.js"
-export { strictGitOperations } from "./StrictGitOperations.js"
-export { fakeGitOperations } from "./FakeGitOperations.js"
-export type { TestkitWorld } from "./steps.js"
+// The public testkit: runs any workflow against the real engine in an in-memory
+// repository. It imports no test runner, so any runner can use it; the
+// gherkin steps are the opt-in \`@pmelab/gtd/testkit/gherkin\`.
+export {
+  runsItsScript,
+  testRepo,
+  type Actor,
+  type Actors,
+  type CannedCommand,
+  type DriveOptions,
+  type TestRepo,
+  type TestRepoOptions,
+  type WorkflowModule,
+} from "./TestRepo.js"
+export { InMemRepo, type CapturedCliResult } from "../twins/index.js"
+export type { TestkitWorld } from "../gherkin/index.js"

package/src/{testkit → twins}/EmittedScriptRecognizer.ts

@@ -36,7 +36,7 @@ import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable } from "./Layers.js"
 
 export interface AppliedScriptResult {
   readonly ok: boolean
@@ -266,10 +266,7 @@ const recognizeFileExistsGuard = (repo: InMemRepo, block: string): BlockOutcome
 /** `binaryGuard`. The in-memory tier has no `$PATH`: a binary is present unless declared `missing`. */
 const BINARY_GUARD_MESSAGE_RE = /^gtd: mode "([^"]+)": "(format|validate)" command not found: (.+)$/
 
-const recognizeBinaryGuard = (
-  commands: ReadonlyMap<string, ScriptedCommand>,
-  block: string,
-): BlockOutcome | undefined => {
+const recognizeBinaryGuard = (commands: CommandTable, block: string): BlockOutcome | undefined => {
   const [binary, , message] = extractQuotedTokens(block)
   if (binary === undefined || message === undefined) return undefined
   const match = BINARY_GUARD_MESSAGE_RE.exec(message)
@@ -330,7 +327,7 @@ const expandFileVar = (text: string): string | undefined => {
  */
 const recognizeModeCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const command = expandFileVar(block) ?? block
@@ -356,7 +353,7 @@ const FAILURE_PROMPT_FOOTER = ' "$gtd_validate_out"\n  exit "$gtd_validate_statu
 
 const recognizeFailurePromptWrapper = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   if (!block.startsWith(FAILURE_PROMPT_HEADER) || !block.endsWith(FAILURE_PROMPT_FOOTER)) {
@@ -465,7 +462,7 @@ const parseModeContradictionCheck = (block: string): ParsedModeContradictionChec
  */
 const simulateModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   parsed: ParsedModeContradictionCheck,
 ): BlockOutcome => {
   const { mode, samplePath, sample, formatCommand, format } = parsed
@@ -502,7 +499,7 @@ const simulateModeContradictionCheck = (
  */
 const recognizeModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const parsed = parseModeContradictionCheck(block)
@@ -570,7 +567,7 @@ const PRESENTATION_SUBSHELL_SUFFIX = `\n) || ${PRESENTATION_FAILURE_WARNING}`
 
 const recognizePresentationSubshell = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
   git: boolean,
 ): BlockOutcome | undefined => {
@@ -595,7 +592,7 @@ const recognizePresentationSubshell = (
 /** Anything left over must be an EXACT hit in the scripted-command table — mirrors `ScriptedCommand`'s two `kind`s (`Layers.ts`). */
 const recognizeScriptedCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const scripted = commands.get(block)
@@ -607,6 +604,7 @@ const recognizeScriptedCommand = (
   if (scripted.kind === "missing") {
     return { kind: "failed", error: `sh: ${block.split(" ")[0]}: not found`, status: 127 }
   }
+  scripted.effect?.()
   if (scripted.status !== 0) {
     return { kind: "failed", error: scripted.output, status: scripted.status }
   }
@@ -693,7 +691,7 @@ const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | und
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   git: boolean,
 ): ReadonlyArray<(block: string) => BlockOutcome | undefined> => [
   (block) => recognizeSetFlags(block),
@@ -735,7 +733,7 @@ const recognizeBlock = (
  */
 export const applyEmittedScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   { git = true }: { readonly git?: boolean } = {},
 ): AppliedScriptResult => {
@@ -750,7 +748,7 @@ export const applyEmittedScript = (
 
 const applyBlocks = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   git: boolean,
 ): AppliedScriptResult => {

package/src/{testkit → twins}/FlowScripts.ts

@@ -15,7 +15,7 @@ import {
   writeScript,
 } from "../flows/index.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable, ScriptedCommand } from "./Layers.js"
 
 export interface FlowScriptResult {
   readonly ok: boolean
@@ -299,16 +299,17 @@ const parseCheck = (script: string): ParsedCheck | undefined => {
 
 const runCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   command: string,
 ): { readonly status: number; readonly output: string } => {
   const scripted = commands.get(command)
   if (scripted === undefined) {
-    throw new Error(
-      `testkit: cannot run \`${command}\` in memory — script it ("the shell command … exits …")`,
-    )
+    throw new Error(`testkit: no canned command matches \`${command}\` — add one to \`commands\``)
+  }
+  if (scripted.kind === "exit") {
+    scripted.effect?.()
+    return scripted
   }
-  if (scripted.kind === "exit") return scripted
   if (scripted.kind === "missing") return { status: 127, output: `sh: ${command}: not found\n` }
   repo.writeFile(scripted.file, rewritten(repo, scripted))
   return { status: 0, output: "" }
@@ -325,7 +326,7 @@ export const rewritten = (
 
 const recognizeCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   const parsed = parseCheck(script)
@@ -362,7 +363,7 @@ const recognizeCheck = (
  */
 export const applyFlowScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   if (!script.startsWith(`${SHEBANG}\n`)) return undefined

package/src/{testkit → twins}/InMemRepo.ts

@@ -134,7 +134,10 @@ export class InMemRepo {
     const refHash = this.refs.get(ref)
     if (refHash !== undefined) return refHash
 
-    return this.branches.get(ref) ?? null
+    // git's own short names: `origin/main` for refs/remotes/origin/main, …
+    const short = this.refs.get(`refs/tags/${ref}`) ?? this.refs.get(`refs/remotes/${ref}`)
+    if (short !== undefined) return short
+    return this.branches.get(ref.replace(/^refs\/heads\//, "")) ?? null
   }
 
   lastCommitSubject(ref = "HEAD"): string | null {
@@ -154,6 +157,28 @@ export class InMemRepo {
     return this.currentBranch
   }
 
+  /** `git branch <name> <ref>`. */
+  createBranch(name: string, ref: string): void {
+    if (this.branches.has(name)) throw new Error(`a branch named '${name}' already exists`)
+    const hash = this.resolveRef(ref)
+    if (hash === null) throw new Error(`not a valid object name: '${ref}'`)
+    this.branches.set(name, hash)
+  }
+
+  /** `git checkout <name>`, refusing any uncommitted change rather than carrying it over. */
+  checkoutBranch(name: string): void {
+    const hash = this.branches.get(name)
+    if (hash === undefined) throw new Error(`pathspec '${name}' did not match any branch`)
+    if (this.statusPorcelain().trim() !== "") {
+      throw new Error(`cannot check out '${name}': the working tree has uncommitted changes`)
+    }
+    const tree = this.getCommit(hash)?.files ?? new Map<string, string>()
+    this.head = hash
+    this.currentBranch = name
+    this.worktree = new Map(tree)
+    this.index = new Map(tree)
+  }
+
   /** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
   listRefs(prefix: string): Array<{ ref: string; hash: string; date: string }> {
     return [...this.refs.entries()]

package/src/{testkit → twins}/Layers.ts

@@ -4,7 +4,7 @@
 // gtd itself spawns no subprocess at all any more (`gtd renders; the driver
 // executes`) — a mode's `format:`/`validate:` command is emitted text, never
 // run in-process. `ScriptedCommand` below still exists for the world's own
-// fake-shell interpreter (`src/testkit/EmittedScriptRecognizer.ts`), which
+// fake-shell interpreter (`src/twins/EmittedScriptRecognizer.ts`), which
 // simulates a driver running gtd's emitted scripts against the in-memory
 // worktree — a wholly separate mechanism from any gtd-internal layer.
 
@@ -169,7 +169,13 @@ const makeInMemoryConfigDiscovery = (
 
 /** One scripted `bash` command's canned behavior, keyed by the RENDERED command string a scenario's `Given` step declares. */
 export type ScriptedCommand =
-  | { readonly kind: "exit"; readonly status: number; readonly output: string }
+  | {
+      readonly kind: "exit"
+      readonly status: number
+      readonly output: string
+      /** What the command does to the tree before it exits. */
+      readonly effect?: () => void
+    }
   | {
       readonly kind: "rewrite"
       readonly file: string
@@ -180,6 +186,11 @@ export type ScriptedCommand =
   /** Keyed by the binary's name: it is not on `$PATH`. */
   | { readonly kind: "missing" }
 
+/** The scripted commands, by the exact command a script runs; a `Map` is one. */
+export interface CommandTable {
+  get(command: string): ScriptedCommand | undefined
+}
+
 export interface TestWorldOptions {
   readonly env?: Readonly<Record<string, string | undefined>>
   readonly root?: string
@@ -193,7 +204,7 @@ export interface TestWorldOptions {
    * Effect test has no `--verbose` flag of its own to gate on.
    */
   readonly narrate?: (line: string) => void
-  /** Gates `narrate` above — defaults to `true` (fires whenever a sink is given) since these tests aren't exercising `Cli.ts`'s own `--verbose` gate. `src/testkit/cliIo.ts` overrides this with the real decoded flag. */
+  /** Gates `narrate` above — defaults to `true` (fires whenever a sink is given) since these tests aren't exercising `Cli.ts`'s own `--verbose` gate. `src/twins/cliIo.ts` overrides this with the real decoded flag. */
   readonly verbose?: boolean
   /** Real or fake driver and tool commands — each one left out fails when called. */
   readonly tools?: Partial<ToolCommands["Type"]>

package/src/twins/index.ts

@@ -0,0 +1,13 @@
+export { InMemRepo } from "./InMemRepo.js"
+export {
+  makeInMemoryWorkspaceOps,
+  testLayers,
+  type CommandTable,
+  type ScriptedCommand,
+} from "./Layers.js"
+export { makeCapturingCliIo, type CapturedCliResult } from "./cliIo.js"
+export { applyEmittedScript } from "./EmittedScriptRecognizer.js"
+export { applyFlowScript } from "./FlowScripts.js"
+export { gitTiers, runGitServiceContract, runGitScriptContract, type GitTier } from "./GitTiers.js"
+export { strictGitOperations } from "./StrictGitOperations.js"
+export { fakeGitOperations } from "./FakeGitOperations.js"

package/src/workflow/discovery.test.ts

@@ -6,7 +6,7 @@ import { NodeContext } from "@effect/platform-node"
 import { Effect, Layer } from "effect"
 import { afterEach, describe, expect, it } from "vitest"
 import { GitService, Host, Narrator, Workspace } from "../platform/index.js"
-import { InMemRepo, testLayers } from "../testkit/index.js"
+import { InMemRepo, testLayers } from "../twins/index.js"
 import { ConfigDiscovery, ConfigService } from "./index.js"
 
 // A config and the local modules it imports load the same from disk, where

package/src/workflow/discovery.ts

@@ -38,7 +38,7 @@ export const WORKFLOW_MODULE = "gtd.config.ts"
  * The file names gtd read repository settings from before `gtd.config.ts` took
  * them over. Still looked for, only to refuse them: a leftover one would
  * otherwise be silently ignored. Shared with the in-memory counterpart in
- * `src/testkit/Layers.ts`, so both tiers refuse the same names.
+ * `src/twins/Layers.ts`, so both tiers refuse the same names.
  */
 export const LEGACY_RC_FILES = [
   ".gtdrc",
@@ -71,7 +71,7 @@ const legacyRcFileAt = (path: string): LegacyRcFile | undefined => {
  * the user's home dir (inclusive, when it is an ancestor) or after reaching the
  * filesystem root — whichever comes first. Returned innermost→outermost.
  * Exported (via the barrel) for the same reason `SEARCH_PLACES` is — one
- * shared implementation, not a second copy in `src/testkit/Layers.ts` that
+ * shared implementation, not a second copy in `src/twins/Layers.ts` that
  * could silently diverge.
  */
 export const walkUp = (from: string, home: string): ReadonlyArray<string> => {
@@ -115,7 +115,7 @@ const workflowModule = (
  * reads; discovery is effectful and environment-dependent: `.Live` reads
  * REAL disk, so an `@inmem` scenario's fake
  * `Workspace` — a pure in-memory `Map`, no real files anywhere on disk —
- * cannot back it. `src/testkit/Layers.ts` provides the in-memory
+ * cannot back it. `src/twins/Layers.ts` provides the in-memory
  * counterpart instead, mirroring how `Workspace`/`Host`/`GitService` already
  * each have a production and a fake layer behind one Tag.
  */

package/src/workflow/load.ts

@@ -357,14 +357,14 @@ const shippedModules = (): Promise<ShippedModules> =>
     return { modules, missing }
   })())
 
-/** The file each subpath a config may import serves: all but `flows`, the engine's own, and `testkit`. */
+/** The file each subpath a config may import serves: all but `flows`, the engine's own, and the testkit's. */
 const subpathFiles = (condition: string): ReadonlyMap<string, string> => {
   const { root, pkg } = ownPackage()
   const files = new Map<string, string>()
   for (const [subpath, target] of Object.entries(pkg.exports)) {
     const file = typeof target === "string" ? target : target[condition]
-    // testkit imports the consumer's test runner, and no config runs one.
-    if (subpath === "./flows" || subpath === "./testkit" || file === undefined) continue
+    // A config runs no tests, and the gherkin steps import the consumer's test runner.
+    if (subpath === "./flows" || subpath.startsWith("./testkit") || file === undefined) continue
     files.set(`${PACKAGE}/${subpath.replace(/^\.\//, "")}`, join(root, file))
   }
   return files