@pmelab/gtd 24.3.0 → 25.0.0

package/src/workflow-kit/scenarios.ts

@@ -1,130 +1,70 @@
-import { head, read } from "../flows/index.js"
+import type { Change } from "../flows/index.js"
 
-/** Mutable: an accepted change moves the snapshot forward. */
-export interface FrozenScenarios {
-  at: string
-  texts: Record<string, string>
-}
-
-const DOC_STRING = /^(\s*)("""|```)/
-
-/**
- * Gherkin wording only: lines trimmed; blank, `#` comment and `@` tag lines
- * dropped — except inside a doc string, whose content is test input: kept
- * whole, indented relative to its opening delimiter (as Gherkin reads it).
- */
-export const scenarioText = (source: string): string => {
-  const out: string[] = []
-  let doc: { readonly indent: number; readonly fence: string } | undefined
-  for (const line of source.split("\n")) {
-    const delimiter = DOC_STRING.exec(line)
-    if (doc === undefined && delimiter !== null) {
-      doc = { indent: delimiter[1]!.length, fence: delimiter[2]! }
-      out.push(line.trim())
-    } else if (doc !== undefined && line.trim().startsWith(doc.fence)) {
-      doc = undefined
-      out.push(line.trim())
-    } else if (doc !== undefined) {
-      const lead = line.length - line.trimStart().length
-      out.push(line.slice(Math.min(lead, doc.indent)).trimEnd())
-    } else {
-      const trimmed = line.trim()
-      if (trimmed !== "" && !trimmed.startsWith("#") && !trimmed.startsWith("@")) out.push(trimmed)
-    }
-  }
-  return out.join("\n")
-}
+const DOC_STRING = /^("""|```)/
+const THEN = /^Then\s/
+const CONTINUATION = /^(And|But|\*)\s/
+const HEADING = /^(Feature|Rule|Background|Scenario|Scenario Outline|Scenario Template|Example):/
 
-const textOf = (path: string): string | undefined => {
-  const source = read(path)
-  return source === undefined ? undefined : scenarioText(source)
+export interface Assertion {
+  /** The trimmed heading line of the scenario (or background) it sits in. */
+  readonly scenario: string
+  readonly line: string
 }
 
-/** Snapshot `.feature` paths at `head()`, merged over `previous`; `undefined` when nothing is frozen. */
-export const freezeScenarios = (
-  paths: readonly string[],
-  previous?: FrozenScenarios,
-): FrozenScenarios | undefined => {
-  if (paths.length === 0) return previous
-  const texts: Record<string, string> = { ...previous?.texts }
-  for (const path of paths) {
-    const text = textOf(path)
-    if (text !== undefined) texts[path] = text
+/** Trimmed lines outside doc strings, whose content is test input, not steps. */
+const stepLines = (source: string): string[] => {
+  const out: string[] = []
+  let fence: string | undefined
+  for (const trimmed of source.split("\n").map((l) => l.trim())) {
+    const opening = fence === undefined ? DOC_STRING.exec(trimmed)?.[1] : undefined
+    if (opening !== undefined) fence = opening
+    else if (fence === undefined) out.push(trimmed)
+    else if (trimmed.startsWith(fence)) fence = undefined
   }
-  return Object.keys(texts).length === 0 ? previous : { at: head(), texts }
+  return out
 }
 
-/** Paths whose wording differs from the snapshot (a deleted file counts). */
-export const driftedScenarios = (frozen: FrozenScenarios): readonly string[] =>
-  Object.entries(frozen.texts)
-    .filter(([path, text]) => textOf(path) !== text)
-    .map(([path]) => path)
-
-// Blank lines survive only inside doc strings, where they are wording.
-const lines = (text: string | undefined): string[] =>
-  text === undefined || text === "" ? [] : text.split("\n")
-
-/** `table[i][j]`: the longest common subsequence of `a[i..]` and `b[j..]`. */
-const lcsTable = (a: readonly string[], b: readonly string[]): number[][] => {
-  const table = Array.from({ length: a.length + 1 }, () => Array<number>(b.length + 1).fill(0))
-  for (let i = a.length - 1; i >= 0; i--) {
-    for (let j = b.length - 1; j >= 0; j--) {
-      table[i]![j] =
-        a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!)
-    }
-  }
-  return table
-}
+const neutral = (line: string): boolean =>
+  line === "" || line.startsWith("#") || line.startsWith("|")
 
-/** Changed lines in file order, `- ` / `+ `-prefixed, so a moved or repeated step still shows. */
-const lineDiff = (a: readonly string[], b: readonly string[]): string[] => {
-  const table = lcsTable(a, b)
-  const out: string[] = []
-  let i = 0
-  let j = 0
-  while (i < a.length && j < b.length) {
-    if (a[i] === b[j]) {
-      i++
-      j++
-    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) out.push(`- ${a[i++]}`)
-    else out.push(`+ ${b[j++]}`)
+/** Trimmed `Then` step lines, an `And`/`But`/`*` continuing one included; doc strings skipped. */
+export const assertionLines = (source: string): readonly Assertion[] => {
+  const out: Assertion[] = []
+  let inThen = false
+  let scenario = ""
+  for (const line of stepLines(source)) {
+    if (HEADING.test(line)) scenario = line
+    if (THEN.test(line)) inThen = true
+    else if (!CONTINUATION.test(line) && !neutral(line)) inThen = false
+    if (inThen && !neutral(line)) out.push({ scenario, line })
   }
-  return [...out, ...a.slice(i).map((l) => `- ${l}`), ...b.slice(j).map((l) => `+ ${l}`)]
+  return out
 }
 
-export interface WordingDrift {
+export interface RemovedAssertions {
   readonly path: string
-  /** `- `/`+ `-prefixed, in file order. */
-  readonly lines: readonly string[]
+  readonly lines: readonly Assertion[]
 }
 
-export const wordingDrift = (frozen: FrozenScenarios, path: string): WordingDrift => ({
-  path,
-  lines: lineDiff(lines(frozen.texts[path]), lines(textOf(path))),
-})
+const key = (a: Assertion): string => `${a.scenario}\n${a.line}`
 
 /**
- * After a turn: rest at `stop` while wording drifted from `frozen`. Whatever
- * still differs after it is accepted and moves the snapshot; what was
- * restored stays frozen as it was.
+ * Assertions a `.feature` file that existed before `changes` lost — the one
+ * way rewording a scenario can weaken it. Matched within each scenario and
+ * counted, so a line moving to another scenario, or one of two identical
+ * `Then`s dropped, still shows. A renamed scenario reports all of its own.
  */
-export const holdWording = async (
-  frozen: FrozenScenarios | undefined,
-  stop: (at: string, drifted: readonly WordingDrift[]) => Promise<void>,
-): Promise<void> => {
-  if (frozen === undefined) return
-  const drifted = driftedScenarios(frozen)
-  if (drifted.length === 0) return
-  await stop(
-    frozen.at,
-    drifted.map((path) => wordingDrift(frozen, path)),
-  )
-  const accepted = driftedScenarios(frozen)
-  if (accepted.length === 0) return
-  for (const path of accepted) {
-    const text = textOf(path)
-    if (text === undefined) delete frozen.texts[path]
-    else frozen.texts[path] = text
-  }
-  frozen.at = head()
-}
+export const removedAssertions = (changes: readonly Change[]): readonly RemovedAssertions[] =>
+  changes
+    .filter((c) => c.path.endsWith(".feature") && c.before !== undefined)
+    .map((c) => {
+      const left = new Map<string, number>()
+      for (const a of assertionLines(c.after ?? "")) left.set(key(a), (left.get(key(a)) ?? 0) + 1)
+      const lines = assertionLines(c.before ?? "").filter((a) => {
+        const n = left.get(key(a)) ?? 0
+        left.set(key(a), n - 1)
+        return n <= 0
+      })
+      return { path: c.path, lines }
+    })
+    .filter((r) => r.lines.length > 0)

package/src/workflows/feature/feature.ts

@@ -10,7 +10,6 @@ import {
 } from "../../flows/index.js"
 import { gate } from "../shared/health.js"
 import { shipped } from "../shared/options.js"
-import type { FrozenScenarios } from "../shared/scenarios.js"
 import { FEEDBACK, REVIEW } from "../shared/steps.js"
 import { refusePendingHandOff } from "../shared/tail.js"
 import * as t from "../shared/text.js"
@@ -53,13 +52,11 @@ export const reUnwind = async (
 /** Plan, build and review until a review round signs off; feedback re-plans from scratch. */
 export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
-  let carried: FrozenScenarios | undefined
   for (;;) {
     await design(base)
     await architecture()
-    const built = await packages(carried)
-    carried = built.frozen
-    const outcome = await buildTail(false, base, built)
+    await packages()
+    const outcome = await buildTail(false, base, true)
     if (outcome.verdict === "signoff") return
     await reUnwind(outcome)
     base = outcome.base

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

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext, type Change, type StepRequest } from "../../flows/index.js"
-import { declaredTests, packages, SCENARIO_PACKAGE } from "./packages.js"
+import { declaredTests, packages } from "./packages.js"
 import { fixtureContext } from "../shared/text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -41,51 +41,34 @@ describe("declaredTests", () => {
   })
 })
 
-describe("packages scenarios", () => {
-  it("holds only package 0's own paths, not what later packages add", async () => {
-    const queue = [SCENARIO_PACKAGE, ".gtd/packages/01-impl.md"]
-    const touches: { at: number; change: Change }[] = []
-    let steps = 0
-    const touch = (path: string, status: Change["status"]): void => {
-      touches.push({ at: steps, change: { path, status, before: undefined, after: "x" } })
-    }
-    const effects: Record<string, () => void> = {
-      building: () => {
-        if (queue[0] === SCENARIO_PACKAGE) {
-          touch("tests/e2e/a.feature", "added")
-          touch(".gtd/packages/00-e2e-scenarios.md", "modified")
-        } else {
-          touch("src/impl.ts", "added")
-          touch("tests/e2e/b.feature", "added")
-          touch("tests/e2e/a.feature", "modified")
-        }
-      },
-      closing: () => void queue.shift(),
-    }
+describe("packages", () => {
+  it("closes every queued package in name order, the plan with the last", async () => {
+    const queue = [".gtd/packages/02-b.md", ".gtd/packages/01-a.md"]
+    const closings: string[] = []
     installContext(
       fixtureContext(
         {},
         {
           step: (request: StepRequest) => {
-            steps++
-            if (request.kind !== "restart") effects[request.name]?.()
+            if (request.kind === "run" && request.name === "closing") {
+              closings.push(request.body)
+              queue.splice(queue.indexOf([...queue].sort()[0]!), 1)
+            }
             return Promise.resolve()
           },
           pushScope: () => undefined,
           popScope: () => undefined,
-          refuse: (message: string): never => {
-            throw new Error(message)
-          },
           glob: () => [...queue],
-          changesSince: (hash: string): readonly Change[] =>
-            touches.filter((t) => t.at >= Number(hash.slice(1))).map((t) => t.change),
-          head: () => `c${steps}`,
+          changesSince: (): readonly Change[] => [],
+          head: () => "c",
         },
       ),
     )
-    const plan = await packages()
-    expect(plan.ranges.map((r) => r.pkg)).toEqual([SCENARIO_PACKAGE, ".gtd/packages/01-impl.md"])
-    expect(plan.scenarios.added).toEqual(["tests/e2e/a.feature"])
-    expect(plan.scenarios.changed).toEqual([])
+    await packages()
+    expect(closings).toHaveLength(2)
+    expect(closings[0]).toContain("01-a.md")
+    expect(closings[0]).not.toContain("ARCHITECTURE")
+    expect(closings[1]).toContain("02-b.md")
+    expect(closings[1]).toContain(".gtd/ARCHITECTURE.md")
   })
 })

package/src/workflows/feature/packages.ts

@@ -1,6 +1,5 @@
 import {
   changesSince,
-  type Change,
   glob,
   head,
   read,
@@ -10,12 +9,9 @@ import {
   scope,
 } from "../../flows/index.js"
 import { healthy } from "../shared/health.js"
-import { freezeScenarios, guarded, type FrozenScenarios } from "../shared/scenarios.js"
+import { ARCHITECTURE } from "../shared/steps.js"
 import { build, fixSuite } from "./steps.js"
 
-/** Package 0: the e2e scenarios, written red. */
-export const SCENARIO_PACKAGE = ".gtd/packages/00-e2e-scenarios.md"
-
 export interface DeclaredTest {
   readonly level: "unit" | "e2e"
   readonly path: string
@@ -62,68 +58,33 @@ export const requireDeclaredTests = (pkg: string, since: string): void => {
   )
 }
 
-export interface PackageRange {
-  readonly pkg: string
-  readonly from: string
-  readonly to: string
-}
-
-export interface BuiltPlan {
-  readonly ranges: readonly PackageRange[]
-  /** Paths package 0 added / modified outside `.gtd/`. */
-  readonly scenarios: { readonly added: readonly string[]; readonly changed: readonly string[] }
-  /** The wording snapshot after this run, to guard the tail and later laps. */
-  readonly frozen: FrozenScenarios | undefined
-}
-
-/** Build `pkg`, check its declared tests, keep the fast suite green, and close it out, which removes it. */
-export const packageItem = async (pkg: string, frozen?: FrozenScenarios): Promise<PackageRange> => {
+/**
+ * Build `pkg`, check its declared tests, keep the full suite green, and close
+ * it out, which removes it — and `.gtd/ARCHITECTURE.md` with the last one.
+ */
+export const packageItem = async (pkg: string): Promise<void> => {
   const from = head()
   // Rechecked after every fix too: a fix deleting a red declared test would
-  // otherwise green the suite. Before the wording gate, so it refuses the turn.
+  // otherwise green the suite.
   const declared = (turn: () => Promise<void>) => async () => {
     await turn()
     requireDeclaredTests(pkg, from)
   }
-  await guarded(
-    frozen,
-    declared(() => build(pkg)),
-  )()
-  await healthy(guarded(frozen, declared(fixSuite)), { suite: "fast" })
-  await run("closing", removeScript([pkg, ".gtd/SATISFIED.md"]), {
+  await declared(() => build(pkg))()
+  await healthy(declared(fixSuite))
+  const last = glob(".gtd/packages/*.md").length === 1
+  await run("closing", removeScript([pkg, ".gtd/SATISFIED.md", ...(last ? [ARCHITECTURE] : [])]), {
     label: "Closing out the package",
   })
-  return { pkg, from, to: head() }
 }
 
 /** The first queued package — the one a package step works on. */
 export const nextPackage = (): string | undefined => [...glob(".gtd/packages/*.md")].sort()[0]
 
-const outsideGtd = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
-
 /** Build every package file under `.gtd/packages/`, in name order. */
-export const packages = (carried?: FrozenScenarios): Promise<BuiltPlan> =>
+export const packages = (): Promise<void> =>
   scope("packages", async () => {
-    let frozen = carried
-    const ranges: PackageRange[] = []
-    // Captured right after package 0: a later diff to the tree would also hold what 01…N touch.
-    let touched: readonly Change[] = []
     for (let pkg = nextPackage(); pkg !== undefined; pkg = nextPackage()) {
-      const range = await scope("item", () =>
-        packageItem(pkg, pkg === SCENARIO_PACKAGE ? undefined : frozen),
-      )
-      ranges.push(range)
-      if (pkg === SCENARIO_PACKAGE) {
-        touched = changesSince(range.from).filter(
-          (c) => outsideGtd(c.path) && c.status !== "deleted",
-        )
-        frozen = freezeScenarios(
-          touched.filter((c) => c.path.endsWith(".feature")).map((c) => c.path),
-          frozen,
-        )
-      }
+      await scope("item", () => packageItem(pkg))
     }
-    const paths = (status: string): string[] =>
-      touched.filter((c) => c.status === status).map((c) => c.path)
-    return { ranges, scenarios: { added: paths("added"), changed: paths("modified") }, frozen }
   })

package/src/workflows/feature/planning.ts

@@ -54,7 +54,7 @@ export const architecture = (): Promise<void> =>
     }
     if (changes(ARCHITECTURE).some((c) => c.status === "deleted")) {
       refuse(
-        "gtd land: decompose: keep .gtd/ARCHITECTURE.md — the build tail's full run needs it; it is removed only once that run is green",
+        "gtd land: decompose: keep .gtd/ARCHITECTURE.md — the packages are built from it; it is removed with the last package",
       )
     }
   })