@pmelab/gtd 27.9.0 → 28.1.0

package/src/workflows/rollout/rollout.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { CONFIG_SCAFFOLD } from "../../install/index.js"
-import { testRepo } from "../../testkit/index.js"
+import { runsItsScript, testRepo } from "../../testkit/index.js"
 
 const CONFIG = `${CONFIG_SCAFFOLD}export { rollout } from "@pmelab/gtd/workflows"\n`
 
@@ -30,9 +30,13 @@ describe("the rollout workflow", () => {
         r.write("src/flags/index.ts", FLIPPED)
       },
       "rollout.suite.check": () => undefined,
+      "rollout.mentions": runsItsScript,
     })
     expect(rest.state).toBe("idle")
-    expect(repo.subjects().at(-1)).toBe("gtd(check): rollout.suite.check → idle")
+    expect(repo.subjects().slice(-2)).toEqual([
+      "gtd(check): rollout.suite.check → rollout.mentions",
+      "gtd(check): rollout.mentions → idle",
+    ])
   })
 
   it("lands a flip when the tree was already dirty at the start", async () => {
@@ -42,6 +46,7 @@ describe("the rollout workflow", () => {
     const rest = await repo.drive({
       "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
       "rollout.suite.check": () => undefined,
+      "rollout.mentions": runsItsScript,
     })
     expect(rest.state).toBe("idle")
   })
@@ -160,8 +165,97 @@ describe("the rollout workflow", () => {
             ),
           ),
         "rollout.suite.check": () => undefined,
+        "rollout.mentions": runsItsScript,
       })
       expect(rest.state).toBe("idle")
     })
   })
 })
+
+describe("rollout.mentions", () => {
+  const flip = {
+    "rollout.flipping": (_: unknown, r: { write: (p: string, c: string) => void }) =>
+      r.write("src/flags/index.ts", FLIPPED),
+  }
+  const finish = async (
+    files: Record<string, string>,
+    mentions: typeof runsItsScript = runsItsScript,
+  ) => {
+    const repo = testRepo({
+      workflow: CONFIG,
+      files: { "src/flags/index.ts": REGISTRY, "src/a.ts": "a\n", ...files },
+    })
+    await repo.start("rollout", "--var", "flag=alpha")
+    const rest = await repo.drive({
+      ...flip,
+      "rollout.suite.check": () => undefined,
+      "rollout.mentions": mentions,
+    })
+    expect(rest.state).toBe("idle")
+    const marks = (repo.messages().at(-1) ?? "")
+      .split("\n")
+      .filter((l) => l.startsWith("Gtd-Mark: "))
+      .map((l) => l.slice("Gtd-Mark: ".length))
+    return { repo, marks }
+  }
+
+  it("lists mentions outside the registry and under no .gtd/ path", async () => {
+    const { marks } = await finish({
+      "README.md": "intro\non under GTD_FLAG_ALPHA=1\n",
+      "src/help.ts": 'export const h = "alpha help"\n',
+      ".gtd/NOTES.md": "alpha\n",
+    })
+    expect(marks).toEqual([
+      "flag-mentions=2",
+      "flag-mention=README.md:2",
+      "flag-mention=src/help.ts:1",
+    ])
+  })
+
+  it("the mentions script removes a feedback file present at the step; marks list the tree", async () => {
+    const { repo, marks } = await finish({ "README.md": "alpha\n" }, (beat, r) => {
+      r.write(".gtd/FEEDBACK.md", "alpha\n")
+      runsItsScript(beat, r)
+    })
+    expect(repo.read(".gtd/FEEDBACK.md")).toBeUndefined()
+    expect(marks).toEqual(["flag-mentions=1", "flag-mention=README.md:1"])
+  })
+
+  it("refuses a stray file written by the mentions script", async () => {
+    await expect(
+      finish({}, (beat, r) => {
+        runsItsScript(beat, r)
+        r.write("src/stray.ts", "x\n")
+      }),
+    ).rejects.toThrow("gtd land: rollout-only: src/stray.ts changed")
+  })
+
+  it("refuses a registry edit beyond the flip made by the mentions script", async () => {
+    await expect(
+      finish({}, (beat, r) => {
+        runsItsScript(beat, r)
+        r.write("src/flags/index.ts", FLIPPED.replace('owner: "b"', 'owner: "z"'))
+      }),
+    ).rejects.toThrow("rollout-only: other edits in src/flags/index.ts")
+  })
+
+  it("marks 0 when nothing names the flag", async () => {
+    const { marks } = await finish({})
+    expect(marks).toEqual(["flag-mentions=0"])
+  })
+
+  it("marks the total for 60 mentions but only the first 50 lines", async () => {
+    const text = Array.from({ length: 60 }, (_, i) => `alpha ${i}`).join("\n")
+    const { marks } = await finish({ "docs/many.md": `${text}\n` })
+    expect(marks[0]).toBe("flag-mentions=60")
+    expect(marks.filter((m) => m.startsWith("flag-mention="))).toHaveLength(50)
+  })
+
+  it("counts a path the mark grammar rejects without marking it, and never throws", async () => {
+    const { marks } = await finish({
+      "docs/bad\u0001name.md": "alpha\n",
+      "README.md": "alpha\n",
+    })
+    expect(marks).toEqual(["flag-mentions=2", "flag-mention=README.md:1"])
+  })
+})

package/src/workflows/rollout/rollout.ts

@@ -1,7 +1,19 @@
-import { agent, changesSince, head, read, refuse, scope, vars } from "../../flows/index.js"
+import {
+  agent,
+  changesSince,
+  glob,
+  head,
+  mark,
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  vars,
+} from "../../flows/index.js"
 import { gate } from "../shared/health.js"
 import { flagShipped } from "../shared/options.js"
-import { flipProblems, requireFlag } from "../shared/registry.js"
+import { flagMentions, flipProblems, requireFlag } from "../shared/registry.js"
 import { coder, FEEDBACK } from "../shared/steps.js"
 
 const flippingPrompt = (name: string, registry: string): string =>
@@ -10,6 +22,31 @@ const flippingPrompt = (name: string, registry: string): string =>
 const suiteBlockedMessage = (): string =>
   "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land."
 
+// Marks past this many are dropped; the summary points at grep for the rest.
+const MARKED_MENTIONS = 50
+
+// Lists, never edits: the human fixes the now-stale prose, or cleanup does. The
+// list rides in marks only: a state file left at idle would be published by
+// ship and read as a failed unwind by the next process.
+const listMentions = async (registry: string, name: string, guard: () => void): Promise<void> => {
+  await run("mentions", removeScript([FEEDBACK]), { label: "Listing flag mentions" })
+  guard()
+  const files = glob("**")
+    .filter((path) => path !== registry && path !== ".gtd" && !path.startsWith(".gtd/"))
+    .sort()
+    .map((path) => ({ path, text: read(path) ?? "" }))
+  const mentions = flagMentions(files, name)
+  mark("flag-mentions", String(mentions.length))
+  for (const m of mentions.slice(0, MARKED_MENTIONS)) {
+    // A path the mark grammar rejects stays counted above, just unlisted here.
+    try {
+      mark("flag-mention", `${m.path}:${m.line}`)
+    } catch {
+      continue
+    }
+  }
+}
+
 // No review gate — a one-field change needs no review lap.
 export const rolloutFlow = async (): Promise<void> => {
   const registry = vars.flagRegistry ?? ""
@@ -38,7 +75,8 @@ export const rolloutFlow = async (): Promise<void> => {
     })
     guard()
     await gate("suite", suiteBlockedMessage(), guard)
+    await listMentions(registry, name, guard)
   })
 }
 
-export const rollout = flagShipped(rolloutFlow)
+export const rollout = flagShipped(rolloutFlow, "rollout")

package/src/workflows/shared/options.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { configure } from "../../flows/index.js"
+import { configure, type WorkflowDoors } from "../../flows/index.js"
 import * as workflows from "../index.js"
 import * as options from "./options.js"
 
@@ -85,7 +85,7 @@ describe("the shipped workflow factories", () => {
   })
 
   describe("flagShipped", () => {
-    const factory = flagShipped(async () => {})
+    const factory = flagShipped(async () => {}, "rollout")
 
     it("declare flag and flagRegistry as process settings, so --var flag= is accepted", () => {
       expect(configure(factory)).toMatchObject({
@@ -97,6 +97,29 @@ describe("the shipped workflow factories", () => {
       })
     })
 
+    it.each(["rollout", "cleanup"] as const)(
+      "%s declares one door named after it, with one required flag arg",
+      (name) => {
+        const result = configure(workflows[name]())
+        expect(result).toMatchObject({
+          ok: true,
+          build: { doors: { [name]: { args: [{ name: "flag" }] } } },
+        })
+        const build = (result as { build?: { doors?: WorkflowDoors } }).build
+        expect(Object.keys(build?.doors ?? {})).toEqual([name])
+        expect(build?.doors?.[name]?.vars?.({ flag: "x" })).toEqual({ flag: "x" })
+      },
+    )
+
+    it.each(["rollout", "cleanup"] as const)("%s builds one door of that name", (name) => {
+      const result = configure(flagShipped(async () => {}, name))
+      const doors = (result as { build?: { doors?: WorkflowDoors } }).build?.doors
+      expect(Object.keys(doors ?? {})).toEqual([name])
+      expect(doors?.[name]?.args).toEqual([{ name: "flag" }])
+      expect(doors?.[name]?.vars?.({ flag: "x" })).toEqual({ flag: "x" })
+      expect(doors?.[name]?.vars?.({})).toEqual({ flag: "" })
+    })
+
     it("fail the load on an unknown option", () => {
       // @ts-expect-error — `flag` is a --var, not an option
       const result = configure(factory({ flag: "x" }))

package/src/workflows/shared/options.ts

@@ -6,7 +6,7 @@ import {
   type WorkflowDoors,
   type WorkflowFactory,
 } from "../../flows/index.js"
-import { defaults, envDefaults } from "./vars.js"
+import { defaultFlagRegistry, defaults, envDefaults } from "./vars.js"
 
 const setting = Schema.optionalWith(Schema.String, { exact: true })
 
@@ -55,16 +55,19 @@ export const FlagOptions = Schema.Struct({ ...ShippedOptions.fields, flagRegistr
 
 export type FlagOptions = Schema.Schema.Encoded<typeof FlagOptions>
 
-export const flagShipped = (flow: Flow): WorkflowFactory<FlagOptions> =>
+export const flagShipped = (
+  flow: Flow,
+  name: "rollout" | "cleanup",
+): WorkflowFactory<FlagOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(FlagOptions, { onExcessProperty: "error", errors: "all" }),
     (options) => {
-      const flagDefaults = { ...defaults, flag: "", flagRegistry: "src/flags/index.ts" }
+      const flagDefaults = { ...defaults, flag: "", flagRegistry: defaultFlagRegistry }
       return {
         flow,
         defaults: over(flagDefaults, options),
         envDefaults: over(envDefaults, options),
-        doors: {},
+        doors: { [name]: { args: [{ name: "flag" }], vars: ({ flag }) => ({ flag: flag ?? "" }) } },
         base: undefined,
       }
     },

package/src/workflows/shared/registry.test.ts

@@ -1,6 +1,12 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext } from "../../flows/index.js"
-import { flagReferences, flipProblems, registryEntry, requireFlag } from "./registry.js"
+import {
+  flagMentions,
+  flagReferences,
+  flipProblems,
+  registryEntry,
+  requireFlag,
+} from "./registry.js"
 
 const ONE_LINE = `export const FLAGS = [
   { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
@@ -303,3 +309,37 @@ describe("flagReferences", () => {
     expect(flagReferences(files, "a(b")).toEqual([])
   })
 })
+
+describe("flagMentions", () => {
+  it("matches the env var, the flag_ form and the bare name, any case, 1-based", () => {
+    const files = [
+      {
+        path: "README.md",
+        text: "intro\non under GTD_FLAG_ALPHA=1\nflag_alpha helper\nThe Alpha flag\nnone\n",
+      },
+    ]
+    expect(flagMentions(files, "alpha")).toEqual([
+      { path: "README.md", line: 2 },
+      { path: "README.md", line: 3 },
+      { path: "README.md", line: 4 },
+    ])
+  })
+
+  it("never matches inside a longer identifier", () => {
+    const text = "alphabet\nalpha_two\nGTD_FLAG_ALPHA_TWO\nxalpha\nflag_alphabet\n"
+    expect(flagMentions([{ path: "a.md", text }], "alpha")).toEqual([])
+  })
+
+  it("keeps test files, and skips a file holding a NUL byte", () => {
+    const files = [
+      { path: "src/a.test.ts", text: "GTD_FLAG_ALPHA\n" },
+      { path: "bin.dat", text: "alpha\u0000alpha\n" },
+    ]
+    expect(flagMentions(files, "alpha").map((m) => m.path)).toEqual(["src/a.test.ts"])
+  })
+
+  it("matches regex metacharacters in the name literally", () => {
+    const files = [{ path: "a.md", text: "a.b\naxb\n" }]
+    expect(flagMentions(files, "a.b").map((m) => m.line)).toEqual([1])
+  })
+})

package/src/workflows/shared/registry.ts

@@ -47,7 +47,7 @@ const mask = (text: string): string => {
   return out
 }
 
-const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+export const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 // Entries are flat object literals, so the nearest braces around the name delimit one.
 const entrySpan = (text: string, name: string) => {
@@ -136,6 +136,31 @@ export const flagReferences = (
     )
 }
 
+export interface FlagMention {
+  readonly path: string
+  readonly line: number
+}
+
+/**
+ * Every line naming flag `name` as `GTD_FLAG_<NAME>`, `flag_<name>` or bare
+ * `<name>` — case-insensitive, never inside a longer identifier. Unlike
+ * `flagReferences`, test files count; a file holding a NUL byte is skipped.
+ */
+export const flagMentions = (
+  files: readonly { readonly path: string; readonly text: string }[],
+  name: string,
+): readonly FlagMention[] => {
+  const pattern = new RegExp(
+    `(?<![A-Za-z0-9_])(?:GTD_FLAG_|flag_)?${escapeRegExp(name)}(?![A-Za-z0-9_])`,
+    "i",
+  )
+  return files
+    .filter(({ text }) => !text.includes("\u0000"))
+    .flatMap(({ path, text }) =>
+      text.split("\n").flatMap((line, i) => (pattern.test(line) ? [{ path, line: i + 1 }] : [])),
+    )
+}
+
 export const requireFlag = (
   workflow: "rollout" | "cleanup",
   registryPath: string,