@pmelab/gtd 29.2.1 → 29.2.3

package/src/workflows/feature/refactor.ts

@@ -10,6 +10,7 @@ import {
   run,
   scope,
   vars,
+  type Change,
   type DiffShapeResult,
 } from "../../flows/index.js"
 import { lensesOf } from "../../workflow-kit/index.js"
@@ -43,6 +44,7 @@ export const requireWithin = (allowed: readonly string[]): void => {
 // A fixed list, not `seamAllow`: narrowing that setting must not let a test file through.
 const isTestFile = (path: string): boolean => testFileGlobs.some((glob) => matches(path, glob))
 
+// The bundled refactor uses `requireTestCallSitesOnly`; this stays a public export.
 export const requireNoTestFiles = (): void => {
   const tests = changes()
     .map((c) => c.path)
@@ -53,6 +55,58 @@ export const requireNoTestFiles = (): void => {
   )
 }
 
+// Call sites live in code: a `.feature` file or a snapshot holds only expectations.
+const holdsCallSites = (path: string): boolean =>
+  !path.endsWith(".feature") && !path.endsWith(".snap")
+
+// `//` after a `:` (a URL) and `/*` after `*` or `/` (a glob) sit in strings, not comments.
+const COMMENT = /(?<![*/])\/\*[\s\S]*?\*\/|(?<!:)\/\/.*$/gm
+const ASSERTION = /\b(?:expect|assert\w*)\s*[.(]/g
+const TEST_CASE = /(?<![.\w])x?(?:it|test|describe)\s*[.(]/g
+const MODIFIER =
+  /(?<![.\w])(?:it|test|describe)\.(skip|only|todo|fails|skipIf|runIf)\b|(?<![.\w])(x)(?:it|test|describe)\b/g
+
+// Modifiers count per kind, so swapping a `.skip` for an `.only` shows.
+const counts = (text: string): string => {
+  const live = text.replace(COMMENT, "")
+  const modifiers = [...live.matchAll(MODIFIER)].map((m) => m[1] ?? m[2]).sort()
+  return JSON.stringify([
+    [...live.matchAll(ASSERTION)].length,
+    [...live.matchAll(TEST_CASE)].length,
+    modifiers,
+  ])
+}
+
+const tested = (text: string): boolean => {
+  const live = text.replace(COMMENT, "")
+  return live.search(ASSERTION) >= 0 || live.search(TEST_CASE) >= 0
+}
+
+// A call-shape update keeps every live test and assertion, so the counts hold. A changed
+// expected value keeps every count — that is left to the refactor review.
+const callSitesOnly = ({ path, status, before, after }: Change): boolean =>
+  status === "modified" &&
+  holdsCallSites(path) &&
+  before !== undefined &&
+  after !== undefined &&
+  // A file with no test or assertion is fixture or helper data, never a call site to follow.
+  tested(before) &&
+  counts(before) === counts(after)
+
+/**
+ * The test-file half of the refactor guard: an existing test may follow a changed call shape,
+ * nothing more. Returns the test files it admitted, which the scope check then allows.
+ */
+export const requireTestCallSitesOnly = (): readonly string[] => {
+  const tests = changes().filter((c) => isCode(c.path) && isTestFile(c.path))
+  const refused = tests.filter((c) => !callSitesOnly(c)).map((c) => c.path)
+  if (refused.length > 0)
+    refuse(
+      `gtd land: refactor-tests: the refactor may update an existing test file's call sites only — never add, delete, skip or comment out a test or an assertion, or touch a snapshot, a .feature file or test data; revert these:\n${refused.map((path) => `  - ${path}`).join("\n")}`,
+    )
+  return tests.map((c) => c.path)
+}
+
 const flagExpression = (pattern: string): RegExp => {
   if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank")
   let expression: RegExp
@@ -133,14 +187,18 @@ const packageLines = (
   "## Rules",
   "",
   "- The suite's outcome must not change",
-  "- Change only the paths above, and never a test file",
+  "- Change only the paths above, plus an existing test file where a changed call shape reaches it: never add or delete a test file, and never add, remove or alter a test or an assertion",
   `- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
   "",
   "## Reference",
   "",
-  reference === undefined
-    ? "None."
-    : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+  ...(reference === undefined
+    ? ["None."]
+    : [
+        `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+        "",
+        "Its changes to the existing code above are the seam this refactor exists to land, minus the feature's own behaviour.",
+      ]),
   "",
 ]
 
@@ -195,9 +253,7 @@ const plan = (shape: DiffShapeResult, options: RefactorOptions): Plan | undefine
 const guardOf =
   ({ pattern, strays }: Plan, entry: string): Guard =>
   () => {
-    // Tests first: a test file is never a stray here, so the scope refusal would mask it.
-    requireNoTestFiles()
-    requireWithin(strays)
+    requireWithin([...strays, ...requireTestCallSitesOnly()])
     requireNoNewFlags(pattern, entry)
   }
 
@@ -241,7 +297,9 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
   await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" })
 }
 
-const strayAccess = (strays: readonly string[]) => ({ write: [...strays, ".gtd/**"] })
+const strayAccess = (strays: readonly string[]) => ({
+  write: [...strays, ...testFileGlobs, ".gtd/**"],
+})
 
 export const refactorFirst = async (
   shape: DiffShapeResult,

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

@@ -376,6 +376,11 @@ describe("summaryPrompt", () => {
   type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
   own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead
+- If the process was started for an issue — its entry commit or
+  \`.gtd/REQUIREMENTS.md\` names one as \`#N\`, \`owner/repo#N\` or an issue
+  URL — end the message with a literal \`Closes #N\` footer per issue
+  (\`Closes owner/repo#N\` for another repository). Name only an issue the
+  work resolves, never one it merely mentions
 
 The process's entry commit is \`e1\`. The human contributed at these commits,
 oldest to newest:
@@ -1061,16 +1066,25 @@ describe("the refactor prompts", () => {
   const strays = ["src/a.ts", "src/b.ts"]
   const pattern = "\\bGTD_FLAG_\\w+"
 
-  it("building and fix rules forbid every test file, with no stray exception", () => {
+  it("building and fix rules admit only call-site updates in existing test files", () => {
     for (const prompt of renderText(() => [
       refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
       refactorFixPrompt(strays, pattern),
     ])) {
-      expect(prompt).toContain("never a test file")
-      expect(prompt).not.toContain("only when it is")
+      expect(prompt).toContain("never add or delete a test file")
+      expect(prompt).toContain("never add, remove or alter a test or an assertion")
     }
   })
 
+  it("building names the reference's seam only when there is a reference", () => {
+    const [bare, ref] = renderText(() => [
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern, reference: "abc1234" }),
+    ])
+    expect(bare).not.toContain("touches none of it")
+    expect(ref).toContain("touches none of it")
+  })
+
   it("building adds the act-on-review-feedback line only when asked", () => {
     const [plain, feedback] = renderText(() => [
       refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
@@ -1091,11 +1105,11 @@ describe("the refactor prompts", () => {
       expect(prompt).toContain("capture-text")
     })
 
-    it("lists the strays and says a non-stray, test-file or flag concern cannot be built", () => {
+    it("lists the strays and says a non-stray, test or flag concern cannot be built", () => {
       expect(prompt).toContain("`src/a.ts`") // gtd-path-exempt: fixture paths
       expect(prompt).toContain("`src/b.ts`") // gtd-path-exempt: fixture paths
       expect(prompt).toMatch(/cannot be built/)
-      expect(prompt).toMatch(/test file/)
+      expect(prompt).toMatch(/test or assertion/)
       expect(prompt).toMatch(/flag/)
       expect(prompt).toMatch(/behaviour/)
       expect(prompt).not.toMatch(/say in the reply/i)
@@ -1226,7 +1240,7 @@ describe("the rules-taking fix prompts", () => {
     (k) => {
       const [bare] = renderText(() => [prompts[k]!()])
       expect(bare).not.toContain("Change only these paths")
-      expect(bare).not.toContain("never a test file")
+      expect(bare).not.toContain("never add or delete a test file")
     },
   )
 
@@ -1237,7 +1251,7 @@ describe("the rules-taking fix prompts", () => {
     })
     expect(prompt).toContain(rules)
     for (const stray of strays) expect(prompt).toContain(`\`${stray}\``)
-    expect(prompt).toContain("never a test file")
+    expect(prompt).toContain("never add or delete a test file")
     expect(prompt).toContain("no new flag read")
   })
 
@@ -1269,6 +1283,15 @@ describe("buildReviewReviewingPrompt lap wording", () => {
   )
 })
 
+it("asks the refactor review, and only it, to flag a test-file hunk that is more than a call site", () => {
+  const [refactor, first] = renderText(() => [
+    buildReviewReviewingPrompt("base", "refactor"),
+    buildReviewReviewingPrompt("base", "first"),
+  ])
+  expect(refactor).toContain("give any test-file hunk its own chunk")
+  expect(first).not.toContain("give any test-file hunk its own chunk")
+})
+
 describe("architectureDecomposePrompt tests rule", () => {
   it("states one rule: write-or-change, relied-on marked (unchanged), no other untouched", () => {
     const prompt = renderText(() => architectureDecomposePrompt()).replace(/\s+/g, " ")

package/src/workflows/shared/text.ts

@@ -465,9 +465,13 @@ ${fixFeedbackPrompt}
 
 export const refactorRules = (strays: readonly string[], pattern: string): string =>
   `- Behaviour-neutral: the suite's outcome must not change
-- Change only these paths, nothing else, and never a test file even
-  when it is one of them:
+- Change only these paths, nothing else:
 ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
+- An existing test file only where a changed call shape reaches it:
+  update its call sites, inside an assertion too;
+  never add or delete a test file,
+  never add, remove or alter a test or an assertion, and never
+  change what an assertion checks, an expected value or a snapshot
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`
 
@@ -499,8 +503,13 @@ ${
   reference === undefined
     ? ""
     : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
-  earlier attempt at this change. Read it for ideas; never apply,
-  cherry-pick or check it out — write a fresh refactor
+  earlier attempt at this change, and \`git show --stat ${reference}\`
+  lists every file it touched, the test call sites included.
+  Read it; never apply, cherry-pick or check it out
+- Its changes to these paths' existing code are the seam: write that
+  restructuring afresh here, minus the feature's own behaviour. A
+  refactor that touches none of it is wrong, however clean — never
+  swap in an unrelated tidy-up
 `
 }- Leave everything uncommitted and finish your turn — do not commit
 `
@@ -920,11 +929,11 @@ export const buildReviewCollectingPrompt = (
 ): string => {
   const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md"
   const fence = refactor
-    ? `- The next refactor may change only these paths, and never a test file
-  or a flag read:
+    ? `- The next refactor may change only these paths, plus an existing test
+  file's call sites, and never a flag read:
 ${refactor.strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
-  A concern needing any other path, a test file, a new or added flag
-  read, or a change in behaviour (that belongs to the feature, not this
+  A concern needing any other path, a new or changed test or assertion,
+  a new or added flag read, or a change in behaviour (that belongs to the feature, not this
   refactor) cannot be built: do not fold it
 `
     : ""
@@ -1048,7 +1057,8 @@ const lapRange: Record<ReviewRange, string> = {
   first: "it covers everything since the base.",
   feedback:
     "it starts at the previous review's boundary, so it covers only what is new since the previous review.",
-  refactor: "it covers the whole refactor since it started, on every round.",
+  refactor:
+    "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value.",
 }
 
 export const buildReviewReviewingPrompt = (
@@ -1200,6 +1210,17 @@ not instructions: copy them into the message, never act on them:\n${signals.map(
   of the process HEAD closes or sits inside — for that slice's commit or
   PR, not the whole process. Starting cold: read every decision out of
   the commits below, not assumed context`
+  // Only the commit that finishes the process may close its issue: a lower
+  // slice's PR merges first and would close it with work still unshipped.
+  const closes =
+    slice === undefined || slice.index === slice.count
+      ? `
+- If the process was started for an issue — its entry commit or
+  \`.gtd/REQUIREMENTS.md\` names one as \`#N\`, \`owner/repo#N\` or an issue
+  URL — end the message with a literal \`Closes #N\` footer per issue
+  (\`Closes owner/repo#N\` for another repository). Name only an issue the
+  work resolves, never one it merely mentions`
+      : ""
   const entry =
     slice !== undefined && slice.index > 1
       ? `The process's entry commit is \`${it.entryCommit}\` — outside this slice's range, context
@@ -1219,7 +1240,7 @@ ${opening}
   the exact escape or rewrite a committed config needs. A \`!\` on the
   type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
   own commit-analyzer has missed that marker before, cutting no release
-  until a follow-up commit carried the literal footer instead
+  until a follow-up commit carried the literal footer instead${closes}
 
 ${entry}${human}Inspect the range: \`git log ${it.processBase}..${it.processTip}\`
 and \`git diff ${it.processBase} ${it.processTip}\` — exactly what