@pmelab/gtd 24.3.0 → 25.0.0

package/src/workflow/fingerprint.test.ts

@@ -1,9 +1,24 @@
-import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs"
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { describe, expect, it } from "vitest"
 import { changedConfigFiles, configFingerprint } from "./fingerprint.js"
 
+const read = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
 describe("the config fingerprint", () => {
   it("hashes each file under its root-relative path, skipping one that cannot be read", () => {
     const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
@@ -14,6 +29,7 @@ describe("the config fingerprint", () => {
     const fingerprint = configFingerprint(
       [join(root, "gtd.config.ts"), join(root, "lib", "flow.ts"), join(root, "gone.ts")],
       root,
+      read,
     )
 
     expect(Object.keys(fingerprint).sort()).toEqual(["gtd.config.ts", "lib/flow.ts"])
@@ -22,7 +38,7 @@ describe("the config fingerprint", () => {
     expect(
       changedConfigFiles(
         fingerprint,
-        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root),
+        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root, read),
       ),
     ).toEqual(["lib/flow.ts"])
   })
@@ -34,7 +50,7 @@ describe("the config fingerprint", () => {
     symlinkSync(real, link)
 
     expect(
-      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link)),
+      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link, read)),
     ).toEqual(["gtd.config.ts"])
   })
 
@@ -42,7 +58,7 @@ describe("the config fingerprint", () => {
     const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
     writeFileSync(join(root, "a\x1b.ts"), "export const a = 1\n")
 
-    expect(configFingerprint([join(root, "a\x1b.ts")], root)).toEqual({})
+    expect(configFingerprint([join(root, "a\x1b.ts")], root, read)).toEqual({})
   })
 
   it("names a file only one side has as changed", () => {

package/src/workflow/fingerprint.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto"
-import { readFileSync, realpathSync } from "node:fs"
+import { realpathSync } from "node:fs"
 import { relative, sep } from "node:path"
 
 /** Path (relative to `root`) → content hash of every file a config load touched. */
@@ -27,19 +27,18 @@ const realOr = (path: string): string => {
 // feeds a warning, and the load that listed the file already read it.
 // Paths are real paths: a loader may report `/private/var/…` for a root
 // reached through the `/var` symlink, and the two must still relate.
-export const configFingerprint = (files: readonly string[], root: string): ConfigFingerprint => {
+export const configFingerprint = (
+  files: readonly string[],
+  root: string,
+  read: (path: string) => string | undefined,
+): ConfigFingerprint => {
   const fingerprint: Record<string, string> = {}
   const realRoot = realOr(root)
   for (const file of files) {
     const path = relative(realRoot, realOr(file)).split(sep).join("/")
     if (CONTROL_CHARACTER.test(path)) continue
-    let content: Buffer
-    try {
-      content = readFileSync(file)
-    } catch {
-      continue
-    }
-    fingerprint[path] = contentHash(content)
+    const content = read(file)
+    if (content !== undefined) fingerprint[path] = contentHash(content)
   }
   return fingerprint
 }

package/src/workflow/index.ts

@@ -25,9 +25,4 @@ export {
   type StateMode,
   type StateName,
 } from "./Workflow.js"
-export {
-  changedConfigFiles,
-  configFingerprint,
-  contentHash,
-  type ConfigFingerprint,
-} from "./fingerprint.js"
+export { changedConfigFiles, contentHash, type ConfigFingerprint } from "./fingerprint.js"

package/src/workflow/load.test.ts

@@ -1,13 +1,5 @@
 import { execSync } from "node:child_process"
-import {
-  existsSync,
-  readFileSync,
-  mkdtempSync,
-  realpathSync,
-  rmSync,
-  writeFileSync,
-  mkdirSync,
-} from "node:fs"
+import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs"
 import { join } from "node:path"
 import { tmpdir } from "node:os"
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
@@ -310,7 +302,7 @@ describe("ConfigService", () => {
     expect(cfg.workflow.steering).toEqual({ ".gtd/PLAN.md": "qa" })
   })
 
-  it("workflowFiles names gtd.config.ts AND a sibling module it imports from — a caller watching only gtd.config.ts's own path misses that module's edits", async () => {
+  it("the fingerprint covers gtd.config.ts AND a sibling module it imports from", async () => {
     writeFileSync(
       join(projectDir, "steps.ts"),
       [`export const steering = { ".gtd/PLAN.md": "qa" }`, ``].join("\n"),
@@ -323,19 +315,13 @@ describe("ConfigService", () => {
     const cfg = await getConfig()
 
     expect(cfg.workflow.steering[".gtd/PLAN.md"]).toBe("qa")
-    expect(cfg.workflowFiles.map((f) => realpathSync(f))).toEqual(
-      expect.arrayContaining([
-        realpathSync(join(projectDir, "gtd.config.ts")),
-        realpathSync(join(projectDir, "steps.ts")),
-      ]),
-    )
+    expect(Object.keys(cfg.fingerprint).sort()).toEqual(["gtd.config.ts", "steps.ts"])
   })
 
-  it("workflowFiles names gtd.config.ts but no shipped module it imports", async () => {
+  it("the fingerprint covers gtd.config.ts but no shipped module it imports", async () => {
     const cfg = await getConfig()
 
-    expect(cfg.workflowFiles).toHaveLength(1)
-    expect(cfg.workflowFiles[0]).toMatch(/\/gtd\.config\.ts$/)
+    expect(Object.keys(cfg.fingerprint)).toEqual(["gtd.config.ts"])
   })
 
   it.each([

package/src/workflow/load.ts

@@ -12,6 +12,7 @@ import { Host, Workspace, type WorkspaceOps } from "../platform/index.js"
 import { compileConfig, type CompiledConfig } from "./compile.js"
 import { SETTING_NAME_RULE, isSettingName } from "./vars.js"
 import { ConfigDiscovery, WORKFLOW_MODULE, type WorkflowModule } from "./discovery.js"
+import { configFingerprint, type ConfigFingerprint } from "./fingerprint.js"
 import {
   dedupeDiagnostics,
   formatDiagnostic,
@@ -41,8 +42,8 @@ export interface ConfigOperations {
   readonly ui?: flows.UiSettings
   /** Non-fatal findings, formatted through `formatDiagnostic` like an error. */
   readonly warnings: readonly Diagnostic[]
-  /** Every real file `gtd.config.ts`'s evaluation touched (itself plus any relative import). A caller that must know when `workflow` might have changed (the LSP's steering-map memo) watches all of them; watching `gtd.config.ts`'s own path alone misses an edit to a module it imports. */
-  readonly workflowFiles: readonly string[]
+  /** The content hash of every file `gtd.config.ts`'s evaluation touched — itself plus any relative import — by path relative to the root. */
+  readonly fingerprint: ConfigFingerprint
 }
 
 // Everything lives in `message` (not `GtdError.detail`) — `renderFailure`
@@ -175,10 +176,22 @@ export const load: Effect.Effect<
     },
     ...(compiled.ui !== undefined ? { ui: compiled.ui } : {}),
     warnings: diagnostics.filter((d) => d.severity === "warning"),
-    workflowFiles: loaded.file.dependencyFiles,
+    fingerprint: configFingerprint(
+      loaded.file.dependencyFiles,
+      host.root,
+      module.read ?? readFromDisk,
+    ),
   }
 })
 
+const readFromDisk = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
 interface Settings {
   readonly defaults: Readonly<Record<string, string>>
   readonly envDefaults: Readonly<Record<string, string>>
@@ -253,7 +266,14 @@ const memoized = (transform: Transform): Transform => {
 
 let jitiModule: JitiModule | undefined
 let transform: Transform | undefined
-const jiti = (shipped: ShippedModules): JitiInstance => {
+/** Relative specifiers a module imports, served from somewhere other than the disk. */
+interface LocalModules {
+  /** The path a specifier names, or nothing when it names no module. */
+  readonly resolve: (specifier: string) => string | undefined
+  readonly load: (path: string) => unknown
+}
+
+const jiti = (shipped: ShippedModules, local?: LocalModules): JitiInstance => {
   const require = createRequire(import.meta.url)
   jitiModule ??= require("jiti") as JitiModule
   // jiti's own Babel transform, which its package exports don't name.
@@ -261,7 +281,16 @@ const jiti = (shipped: ShippedModules): JitiInstance => {
     require(join(dirname(require.resolve("jiti/package.json")), "dist", "babel.cjs")) as Transform,
   )
   return jitiModule.createJiti(import.meta.url, {
-    virtualModules: shipped.modules,
+    // Consulted when a module is required, so a local module is evaluated
+    // only once an import actually runs.
+    virtualModules: new Proxy(shipped.modules, {
+      has: (modules, id) =>
+        id in modules || (typeof id === "string" && local?.resolve(id) !== undefined),
+      get: (modules, id) => {
+        const path = typeof id === "string" ? local?.resolve(id) : undefined
+        return path === undefined ? modules[id as string] : local!.load(path)
+      },
+    }),
     alias: shipped.missing,
     // No transpile cache on disk, and a fresh module every load — nothing a
     // later command could read back instead of the source.
@@ -572,11 +601,12 @@ const namespaceOf = (exported: unknown): Record<string, unknown> =>
  * pulled in, transitively.
  */
 const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded => {
-  const cache: Record<string, unknown> = {}
-  const exports = namespaceOf(
-    jiti(shipped).evalModule(module.source, { filename: module.filepath, cache }),
-  )
-  const file = fileFrom(exports, module.filepath, Object.keys(cache))
+  const { exports: evaluated, files } =
+    module.read === undefined
+      ? evaluateFromDisk(module, shipped)
+      : evaluateRead(module, module.read, shipped)
+  const exports = namespaceOf(evaluated)
+  const file = fileFrom(exports, module.filepath, files)
   const exported = Object.entries(exports).filter(
     ([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value),
   )
@@ -611,6 +641,60 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   }
 }
 
+const evaluateFromDisk = (
+  module: WorkflowModule,
+  shipped: ShippedModules,
+): { readonly exports: unknown; readonly files: readonly string[] } => {
+  const cache: Record<string, unknown> = {}
+  const exports = jiti(shipped).evalModule(module.source, { filename: module.filepath, cache })
+  return { exports, files: Object.keys(cache) }
+}
+
+// How jiti finds a TypeScript module behind a specifier: as written, its
+// `.js` spelling as `.ts`, with `.ts` appended, or as a directory index.
+const moduleCandidates = (path: string): readonly string[] => [
+  path,
+  path.replace(/\.js$/, ".ts"),
+  path.replace(/\.mjs$/, ".mts"),
+  `${path}.ts`,
+  join(path, "index.ts"),
+]
+
+/**
+ * Evaluates the config with every local module it imports taken from `read`
+ * instead of the disk. jiti matches a virtual module on the specifier as
+ * written, so each module gets its own instance resolving against its own
+ * directory. A specifier `read` cannot serve falls through to the disk, and
+ * fails the way a missing file does.
+ */
+const evaluateRead = (
+  module: WorkflowModule,
+  read: (path: string) => string | undefined,
+  shipped: ShippedModules,
+): { readonly exports: unknown; readonly files: readonly string[] } => {
+  const files = [module.filepath]
+  const evaluated = new Map<string, unknown>()
+  const evaluate = (filepath: string, source: string): unknown =>
+    jiti(shipped, {
+      resolve: (specifier) =>
+        /^\.\.?\//.test(specifier)
+          ? moduleCandidates(join(dirname(filepath), specifier)).find(
+              (candidate) => read(candidate) !== undefined,
+            )
+          : undefined,
+      load: (path) => {
+        if (!evaluated.has(path)) {
+          // A placeholder first, so an import cycle ends here.
+          evaluated.set(path, {})
+          files.push(path)
+          evaluated.set(path, evaluate(path, read(path)!))
+        }
+        return evaluated.get(path)
+      },
+    }).evalModule(source, { filename: filepath })
+  return { exports: evaluate(module.filepath, module.source), files }
+}
+
 const isWorkflow = (value: unknown): boolean =>
   typeof value === "function" || flows.isFactoryWorkflow(value)
 

package/src/workflow-kit/review.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+const state = vi.hoisted(() => ({ feedback: undefined as string | undefined, head: "h1" }))
+
+vi.mock("../flows/index.js", () => ({
+  changes: () => [],
+  changesSince: () => [],
+  hasThreadFor: () => false,
+  head: () => state.head,
+  read: () => state.feedback,
+  refuse: (m: string) => {
+    throw new Error(m)
+  },
+  requireReplies: () => {},
+  requireThreadsClosed: () => {},
+}))
+
+import { routeNotes, type ReviewPolicy, type Verdict } from "./review.js"
+import type { ReviewNote } from "../steering/index.js"
+
+const note = (id: string) => ({ id }) as unknown as ReviewNote
+
+const setup = (verdicts: Record<string, Verdict>) => {
+  const calls: string[] = []
+  const deferred: string[][] = []
+  const collected: ReviewNote[][] = []
+  const p = {
+    file: "r.md",
+    feedback: "f.md",
+    triage: async () => new Map(Object.entries(verdicts)),
+    answerQuestions: async () => void calls.push("answer"),
+    fixNits: async () => void calls.push("nits"),
+    keepGreen: async () => void calls.push("green"),
+    collecting: async () => {
+      calls.push("collect")
+      state.feedback = "x"
+    },
+    captures: {
+      editNotes: (_r: string, edits: readonly ReviewNote[]) => {
+        collected.push([...edits])
+        return "cap"
+      },
+    },
+    defer: async (ns: readonly ReviewNote[]) => {
+      calls.push("defer")
+      deferred.push(ns.map((n) => n.id))
+    },
+  } as unknown as ReviewPolicy
+  const r = {
+    round: "r1",
+    close: async () => void calls.push("close"),
+    outcome: (verdict: "signoff" | "feedback") => ({ verdict }) as never,
+    unfolded: async () => ({ verdict: "signoff" }) as never,
+  }
+  return { p, r, calls, deferred, collected }
+}
+
+beforeEach(() => {
+  state.feedback = undefined
+})
+
+describe("routeNotes defer", () => {
+  it("defer-only round awaits again, no collecting turn", async () => {
+    const t = setup({ a: "defer", b: "defer" })
+    const res = await routeNotes(t.p, [note("a"), note("b")], t.r)
+    expect(res).toEqual({ next: "await", reviewed: "r1" })
+    expect(t.deferred).toEqual([["a", "b"]])
+    expect(t.calls).toEqual(["defer"])
+  })
+
+  it("defer + edit collects only the edits and ends feedback", async () => {
+    const t = setup({ a: "defer", b: "edit" })
+    const res = await routeNotes(t.p, [note("a"), note("b")], t.r)
+    expect(res).toEqual({ verdict: "feedback" })
+    expect(t.calls).toEqual(["defer", "close", "collect"])
+    expect(t.collected[0]!.map((n) => n.id)).toEqual(["b"])
+  })
+
+  it("runs after nit fixes and before the collecting turn", async () => {
+    const t = setup({ a: "nit", b: "defer", c: "edit" })
+    await routeNotes(t.p, [note("a"), note("b"), note("c")], t.r)
+    expect(t.calls).toEqual(["nits", "green", "defer", "close", "collect"])
+  })
+})

package/src/workflow-kit/review.ts

@@ -24,7 +24,7 @@ export type ReviewOutcome =
       readonly edited: readonly Change[]
     }
 
-export type Verdict = "edit" | "question" | "nit" | "praise"
+export type Verdict = "edit" | "question" | "nit" | "praise" | "defer"
 
 export type ReviewRisk = ReturnType<typeof reviewRisks>[number]
 
@@ -49,6 +49,8 @@ export interface ReviewPolicy {
   readonly triage: (notes: readonly ReviewNote[]) => Promise<ReadonlyMap<string, Verdict>>
   readonly answerQuestions: (notes: readonly ReviewNote[]) => Promise<void>
   readonly fixNits: (notes: readonly ReviewNote[]) => Promise<void>
+  /** Leave `defer` notes out of the round. */
+  readonly defer: (notes: readonly ReviewNote[]) => Promise<void>
   /** Remove `file` at the end of a round at commit `round`. */
   readonly close: (round: string) => Promise<void>
   /** What a collecting turn reads. */
@@ -127,16 +129,16 @@ interface Round {
   readonly unfolded: () => Promise<Finish>
 }
 
-/** Judge every note, then run each verdict's route: answers, then nit fixes, then the edits' lap. */
-const routeNotes = async (
+/** Judge every note, then run each verdict's route: answers, then nit fixes, then deferrals, then the edits' lap. */
+export const routeNotes = async (
   p: ReviewPolicy,
   notes: readonly ReviewNote[],
   r: Round,
 ): Promise<Finish> => {
   const verdicts = await p.triage(notes)
   const of = (v: Verdict): ReviewNote[] => notes.filter((n) => (verdicts.get(n.id) ?? "edit") === v)
-  const [edits, questions, nits] = [of("edit"), of("question"), of("nit")]
-  if (edits.length + questions.length + nits.length === 0) return r.unfolded()
+  const [edits, questions, nits, deferred] = [of("edit"), of("question"), of("nit"), of("defer")]
+  if (edits.length + questions.length + nits.length + deferred.length === 0) return r.unfolded()
 
   let answeredAt: string | undefined
   if (questions.length > 0) {
@@ -147,6 +149,7 @@ const routeNotes = async (
     await p.fixNits(nits)
     await p.keepGreen()
   }
+  if (deferred.length > 0) await p.defer(deferred)
   if (edits.length > 0) {
     await r.close()
     return r.outcome(await collect(p, p.captures.editNotes(r.round, edits, answeredAt)))
@@ -155,7 +158,7 @@ const routeNotes = async (
     await r.close()
     return { next: "rereview", carry: answeredAt }
   }
-  return { next: "await", reviewed: answeredAt! }
+  return { next: "await", reviewed: answeredAt ?? r.round }
 }
 
 /** A code edit, not a thread-only change: lines that only add, answer or remove code threads don't count. */

package/src/workflow-kit/scenarios.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest"
+import type { Change } from "../flows/index.js"
+import { assertionLines, removedAssertions } from "./scenarios.js"
+
+const scenario = (name: string, ...steps: string[]): string[] => [
+  `  Scenario: ${name}`,
+  ...steps.map((s) => `    ${s}`),
+]
+
+const feature = (...steps: string[]): string =>
+  ["Feature: x", ...scenario("y", ...steps)].join("\n")
+
+const modified = (path: string, before: string, after: string | undefined): Change => ({
+  path,
+  status: after === undefined ? "deleted" : "modified",
+  before,
+  after,
+})
+
+const lost = (path: string, name: string, ...lines: string[]) => ({
+  path,
+  lines: lines.map((line) => ({ scenario: `Scenario: ${name}`, line })),
+})
+
+describe("assertionLines", () => {
+  it("keeps Then lines and their And/But continuations, not Given/When ones", () => {
+    expect(
+      assertionLines(
+        feature(
+          "Given a",
+          "And b",
+          "When c",
+          "Then d",
+          "And e",
+          "| row |",
+          "But f",
+          "When g",
+          "And h",
+        ),
+      ).map((a) => a.line),
+    ).toEqual(["Then d", "And e", "But f"])
+  })
+
+  it("skips doc string content", () => {
+    expect(
+      assertionLines(feature("Then a file with:", '  """', "  Then not a step", '  """')).map(
+        (a) => a.line,
+      ),
+    ).toEqual(["Then a file with:"])
+  })
+
+  it("names the scenario each assertion sits in, through an Examples table", () => {
+    const source = [
+      "Feature: x",
+      ...scenario("a", "Then one"),
+      "  Scenario Outline: b",
+      "    Then <two>",
+      "    Examples:",
+      "      | two |",
+    ].join("\n")
+    expect(assertionLines(source)).toEqual([
+      { scenario: "Scenario: a", line: "Then one" },
+      { scenario: "Scenario Outline: b", line: "Then <two>" },
+    ])
+  })
+})
+
+describe("removedAssertions", () => {
+  it("reports a reworded assertion of an existing scenario", () => {
+    expect(
+      removedAssertions([
+        modified(
+          "a.feature",
+          feature("Given a", "Then it is shown"),
+          feature("Given a", "Then it is displayed"),
+        ),
+      ]),
+    ).toEqual([lost("a.feature", "y", "Then it is shown")])
+  })
+
+  it("ignores reworded Given and When steps and added assertions", () => {
+    expect(
+      removedAssertions([
+        modified(
+          "a.feature",
+          feature("Given a", "Then b"),
+          feature("Given z", "When y", "Then b", "And c"),
+        ),
+      ]),
+    ).toEqual([])
+  })
+
+  it("counts duplicates, so dropping one of two identical lines shows", () => {
+    expect(
+      removedAssertions([modified("a.feature", feature("Then b", "Then b"), feature("Then b"))]),
+    ).toEqual([lost("a.feature", "y", "Then b")])
+  })
+
+  it("reports an assertion that moved to another scenario", () => {
+    const before = ["Feature: x", ...scenario("a", "Then ok"), ...scenario("b", "When c")]
+    const after = ["Feature: x", ...scenario("a", "When d"), ...scenario("b", "When c", "Then ok")]
+    expect(removedAssertions([modified("a.feature", before.join("\n"), after.join("\n"))])).toEqual(
+      [lost("a.feature", "a", "Then ok")],
+    )
+  })
+
+  it("reports every assertion of a deleted file, none of an added one or a non-feature", () => {
+    expect(
+      removedAssertions([
+        modified("gone.feature", feature("Then b"), undefined),
+        { path: "new.feature", status: "added", before: undefined, after: feature("Then c") },
+        modified("a.ts", "Then b", ""),
+      ]),
+    ).toEqual([lost("gone.feature", "y", "Then b")])
+  })
+})