declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/expo-migration/declarations/practices/rhachet/best-practice/.agent/repo=.this/role=any/boot.yml.declapract.ts

@@ -0,0 +1,165 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+
+/**
+ * .what = the ref globs this practice declares — the deep glossary variants that stay on-demand.
+ * .why  = the boot.yml default is say-all (see the template); these two globs are the sole
+ *         demotions to ref, so a consumer's whole glossary rides in context while the reason-deep
+ *         and example variants stay a path-only fetch away. the findsert ensures a consumer's file
+ *         carries these two demotions, never the whole template — so its own boot entries survive.
+ */
+const declaredRefGlobs: readonly string[] = [
+  'briefs/domain.terms/term=*._.choice.reason.md',
+  'briefs/domain.terms/term=*._.choice.example=*.md',
+];
+
+/**
+ * .what = the token cap this practice findserts for the resident `say` payload at each boot.
+ * .why  = a boot whose say-content exceeds this halts, so the corpus cannot silently bloat context.
+ *         findserted so an extant consumer inherits the cap on upgrade, not only a fresh one — the
+ *         template block ships to a new consumer, this findsert reaches the ones already on disk.
+ *         findsert semantics: absent -> add; present -> leave the consumer's chosen value untouched,
+ *         so a consumer who deliberately raised or lowered the cap is never reverted.
+ */
+const declaredBudgetTokens = 5_000;
+
+/**
+ * .what = the comment the findsert attaches above the `budget:` key it injects.
+ * .why  = a bare `budget:\n  tokens: 5000` gives a consumer no clue why the value is plain, so a
+ *         later tidy-up could "improve" it to `5_000` and silently make the cap a yaml STRING. the
+ *         findserted block must carry the same NOTE the shipped template does, so the trap is warned
+ *         at the exact spot the value lands.
+ * .note = the yaml serializer prefixes each line with `# `, so a space at the front renders `# budget`.
+ */
+const declaredBudgetComment = [
+  ' budget — the token cap for the resident `say` payload at each boot.',
+  ' a boot whose say-content exceeds this halts, so the corpus cannot silently bloat',
+  ' context. remedies: demote a say glob to ref, adopt a .min brief variant, or raise',
+  ' this cap deliberately.',
+  ' NOTE: plain `5000`, not `5_000` — yaml 1.2 (the yaml v2 default) reads an underscore',
+  ' integer as a STRING, which would silently make the cap non-numeric.',
+].join('\n');
+
+/**
+ * .what = true when a consumer's boot.yml already declares `budget.tokens` (any value).
+ * .why  = the findsert gate: add the cap only when a consumer carries none, so a present value — even
+ *         a divergent one a consumer chose on purpose — is preserved (findsert, never upsert).
+ */
+const hasBudgetTokens = (doc: yaml.Document): boolean =>
+  doc.getIn(['budget', 'tokens']) !== undefined;
+
+/**
+ * .what = reads the ref globs a consumer's boot.yml currently carries, from whichever mode it uses.
+ * .why  = a consumer may curate in SIMPLE mode (top-level `briefs.ref`) or the legacy SUBJECT mode
+ *         (`always.briefs.ref`). read from whichever exists so the union is computed against the
+ *         consumer's real ref list, never a presumed one. no mutation here — this is the read half.
+ */
+const getCurrentRefGlobs = (doc: yaml.Document): string[] => {
+  // the yaml node api is an external boundary; a documented projection to json is the in-repo norm
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const node: any =
+    doc.getIn(['always', 'briefs', 'ref']) ?? doc.getIn(['briefs', 'ref']);
+  if (!node) return [];
+  return (node.toJSON() as string[] | null) ?? [];
+};
+
+/**
+ * .what = the mutable ref seq node to union into: the consumer's extant one, or a seeded simple-mode one.
+ * .why  = union into whichever ref list already exists (subject or simple), so a subject-mode consumer
+ *         is never corrupted into an invalid mixed `always:`+`briefs:` file. only when NEITHER exists
+ *         does the fix seed a simple-mode `briefs.ref` — the go-forward shape.
+ */
+const getOrSeedRefSeq = (doc: yaml.Document): unknown => {
+  const subject = doc.getIn(['always', 'briefs', 'ref']);
+  if (subject) return subject;
+  const simple = doc.getIn(['briefs', 'ref']);
+  if (simple) return simple;
+  // neither ref list exists — seed a real seq node (a plain [] becomes a js
+  // array without the `.add` the union relies on), then union into it.
+  const seq = new yaml.YAMLSeq();
+  doc.setIn(['briefs', 'ref'], seq);
+  return seq;
+};
+
+/**
+ * .what = the boot.yml a consumer should hold — its extant file with the declared ref globs unioned in
+ *         and the budget cap findserted, or the whole declared template when the consumer has none yet.
+ * .why  = a findsert by construction: a glob already present stays present once, a budget already set
+ *         is left as the consumer chose it, and every other line (a consumer's own say/ref entries,
+ *         comments, mode) is preserved because the file is mutated in place via the yaml document api,
+ *         never regenerated.
+ * .note = a fixed point — an already-conformant file is returned verbatim (no round-trip), so
+ *         `fix(fix(x)) === fix(x)` and `check` passes on its own output; without both, `declapract
+ *         fix` would rewrite this file forever.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  declaredContents: string,
+): string => {
+  // a fresh consumer (no boot.yml) gets the whole declared template verbatim.
+  if (!contents) return declaredContents;
+
+  const doc = yaml.parseDocument(contents);
+  const absentGlobs = declaredRefGlobs.filter(
+    (glob) => !getCurrentRefGlobs(doc).includes(glob),
+  );
+  const budgetAbsent = !hasBudgetTokens(doc);
+
+  // already conformant → return the consumer's file verbatim (no round-trip).
+  if (absentGlobs.length === 0 && !budgetAbsent) return contents;
+
+  // deliberate mutation — the yaml document api mutates the seq node in place to
+  // preserve the adjacent comments; there is no immutable seq-add.
+  if (absentGlobs.length > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const refSeq = getOrSeedRefSeq(doc) as any;
+    absentGlobs.forEach((glob) => refSeq.add(glob));
+  }
+
+  // findsert the budget cap — only when the consumer declares none, so a chosen value survives.
+  // attach the NOTE above the `budget:` key so the plain-5000 yaml trap is warned where it lands.
+  if (budgetAbsent) {
+    doc.setIn(['budget', 'tokens'], declaredBudgetTokens);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const budgetPair = (doc.contents as any)?.items?.find(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (item: any) => yaml.isScalar(item.key) && item.key.value === 'budget',
+    );
+    if (budgetPair?.key) budgetPair.key.commentBefore = declaredBudgetComment;
+  }
+
+  return doc.toString();
+};
+
+/**
+ * .what = throws when a consumer's boot.yml lacks a declared ref glob (or is absent entirely).
+ * .why  = `check` is the GATE: declapract runs `fix` only when `check` rejects. so this is what makes
+ *         an upgrade actually union the deep-variant ref demotions AND findsert the budget cap into a
+ *         consumer that lacks them.
+ * .note = best-practice semantics are inverted — a THROW means the practice is violated, a return
+ *         means it is followed. see `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ *         the equality is against the FINDSERT output (globs unioned, budget cap ensured), never the
+ *         whole template, so a consumer's own boot entries pass the check untouched.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  expect(contents).toEqual(
+    defineExpectedContents(contents, context.declaredFileContents ?? ''),
+  );
+};
+
+/**
+ * .what = unions the declared ref globs into a consumer's boot.yml and findserts the budget cap (or
+ *         writes the template if absent).
+ * .why  = fix forward once, for every consumer — never a whole-file overwrite that would drop a
+ *         consumer's own say/ref curation (#105 req 1).
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(
+      contents,
+      context.declaredFileContents ?? '',
+    ),
+  };
+};

package/dist/.test/assets/expo-migration/declarations/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -6,11 +6,21 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
 /**
  * ignores that this practice itself owns
  *
- * .why = rhachet boots roles which write scratch state into `.agent/.cache/`. the
- *        practice that creates the dir declares the ignore for it, so a repo that
- *        takes `rhachet` is never left with cruft it did not ask for:
+ * .why = rhachet boots roles which write scratch state into `.agent/.cache/`, and the
+ *        claude-code harness those roles run writes machine-local scheduler state into
+ *        `.claude/scheduled_tasks*` (a lock + queue). the practice that creates a dir
+ *        declares the ignore for it, so a repo that takes `rhachet` is never left with
+ *        cruft it did not ask for:
  *        - a worktree teardown is not snagged by untracked scratch
- *        - a hurried `git add .` cannot sweep a debug file that holds a secret
+ *        - a hurried `git add .` cannot sweep a machine-local lock or a debug file that
+ *          holds a secret
+ *
+ * .note = `.claude/scheduled_tasks*` is machine-local by nature -- a lock/queue for THIS
+ *         host's scheduler, never shared across a team -- so it is ignored, never tracked.
+ *         it belongs HERE, not in `git`: rhachet's role-boot harness is what creates it, and
+ *         a practice declares the ignore for the dirs IT creates. (`*.local.json`, the other
+ *         `.claude/` machine-local shape, stays in `git` -- it is a generic suffix, not a
+ *         rhachet-created path.)
  *
  * .note = `.cache/` is generic tool scratch and belongs to the `git` practice, not
  *         here. a practice declares the ignore for the dirs IT creates, and no more.
@@ -21,7 +31,10 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
  *         place. `readonly` forbids that mutation outright rather than merely discourages it
  *         (`rule.prefer.prevent-over-correct`).
  */
-const ignoresSortable: readonly string[] = ['.agent/.cache/'];
+const ignoresSortable: readonly string[] = [
+  '.agent/.cache/',
+  '.claude/scheduled_tasks*',
+];
 
 /**
  * .what = emits the `.gitignore` this practice declares, given the repo's extant one

package/dist/.test/assets/expo-migration/declarations/practices/rhachet/best-practice/package.json

@@ -1,18 +1,18 @@
 {
   "devDependencies": {
-    "rhachet": "@declapract{check.minVersion('1.43.1')}",
-    "rhachet-brains-anthropic": "@declapract{check.minVersion('0.4.1')}",
-    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.3')}",
+    "rhachet": "@declapract{check.minVersion('1.47.5')}",
+    "rhachet-brains-anthropic": "@declapract{check.minVersion('0.4.3')}",
+    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.6')}",
     "rhachet-brains-xai": "@declapract{check.minVersion('0.3.3')}",
-    "rhachet-roles-bhrain": "@declapract{check.minVersion('0.29.24')}",
+    "rhachet-roles-bhrain": "@declapract{check.minVersion('0.34.1')}",
     "rhachet-roles-bhrowser": "@declapract{check.minVersion('0.1.0')}",
-    "rhachet-roles-bhuild": "@declapract{check.minVersion('0.21.22')}",
-    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.1')}",
-    "rhachet-roles-ghlitch": "@declapract{check.minVersion('0.2.5')}",
+    "rhachet-roles-bhuild": "@declapract{check.minVersion('0.21.36')}",
+    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.12')}",
+    "rhachet-roles-ghlitch": "@declapract{check.minVersion('0.3.0')}",
     "rhachet-roles-rhachet": "@declapract{check.minVersion('0.1.7')}"
   },
   "scripts": {
-    "prepare:rhachet": "rhachet init --keys --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect dispatcher learner operator observer deployer playwright enroller",
+    "prepare:rhachet": "rhachet init --keys --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect dispatcher learner achiever telepath operator observer deployer playwright enroller",
     "upgrade:rhachet": "rhachet upgrade"
   }
 }

package/dist/.test/assets/expo-migration/declarations/practices/rhachet/boot-refs-glossary.declapract.integration.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the rhachet practice's shipped boot.yml defaults every brief to SAY level and
+ *         refs ONLY the deep glossary variants (`.reason`, `.example`), via GLOBs — never this repo's
+ *         enumerated term list, and never a `say:` enumeration.
+ * .why  = the boot.yml is a TEMPLATE copied to every consumer. under #105 the shape is SIMPLE mode
+ *         with `say` ABSENT + `ref` present, so the loader reads every discovered brief at say-level
+ *         EXCEPT the ref-matched deep variants. the ref entries must be globs (matched against the
+ *         consumer's tree by rhachet's fast-glob), never a hardcoded list of THIS repo's terms -- an
+ *         enumerated list would ref terms a consumer does not have and miss the ones it does. a glob
+ *         is also drift-proof: a new term's deep variants auto-demote, and no say entry is ever
+ *         enumerated.
+ * .teeth = swap a `term=*` deep-variant glob for an enumerated `term=convergence._.choice.reason.md`
+ *          and the "no hardcoded term name" case reddens; add a `say:` key and the "no say
+ *          enumeration" case reddens; add an `always:` key and the "simple mode" case reddens; ref
+ *          the `._.choice._.md` root (a say-level brief) and the "choice root stays say" case reddens.
+ * .note = the subject is the shipped TEMPLATE text. the `.integration.test.ts` suffix reads the
+ *         filesystem (a remote boundary); this file sits at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ * .note = this supersedes the #587 ref-all clamp: #587 refed the whole glossary (choice root +
+ *         readme) for a near-zero boot cost; #105 flips the default to say and refs only the
+ *         reason/example deep variants. the assertions below encode the #105 shape.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/rhachet/) the best-practice tree is one segment down.
+const bootYmlPath = join(
+  __dirname,
+  'best-practice/.agent/repo=.this/role=any/boot.yml',
+);
+
+const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+const CHOICE_ROOT_REF = 'briefs/domain.terms/term=*._.choice._.md';
+
+describe('rhachet boot.yml defaults to say, refs only deep glossary variants', () => {
+  given('[case1] the shipped boot.yml template', () => {
+    const contents = readFileSync(bootYmlPath, 'utf8');
+
+    when('[t0] the template is read', () => {
+      then('it is simple mode (top-level briefs:, no always:)', () => {
+        expect(contents).toMatch(/^briefs:/m);
+        expect(contents).not.toMatch(/^always:/m);
+      });
+
+      then('it enumerates no say entry (say defaults for every brief)', () => {
+        // the whole point of #105: `say` is absent, so the loader defaults every discovered brief to
+        // say. a `say:` key would enumerate — exactly what #105 forbids.
+        expect(contents).not.toMatch(/^\s*say:/m);
+      });
+
+      then('it refs the deep glossary variants via globs', () => {
+        expect(contents).toContain(REASON_REF);
+        expect(contents).toContain(EXAMPLE_REF);
+      });
+
+      then('it does not ref the choice root (it stays say-level)', () => {
+        // the `._.choice._.md` root is the say-lean brief a consumer wants in context; only the
+        // reason-deep + example variants demote to ref.
+        expect(contents).not.toContain(CHOICE_ROOT_REF);
+      });
+
+      then('it hardcodes no specific term name (stays per-consumer correct)', () => {
+        // a concrete `term=<slug>._.choice...` (slug != the `*` glob) would be this repo's own term,
+        // wrong for a consumer. the only legal `term=` token is the glob wildcard.
+        const concreteTermRefs = (
+          contents.match(/term=[a-z][a-z-]*\._\.choice/g) || []
+        ).filter((m) => !m.startsWith('term=*'));
+        expect(concreteTermRefs).toEqual([]);
+      });
+
+      then('the emitted glossary ref lines match snapshot', () => {
+        // snapshot the governed glossary ref lines themselves, so a reshaped ref that keeps the glob
+        // tokens green (a reordered entry, a rephrased comment) reddens a vibecheck in review
+        // (rule.require.contract-snapshot-exhaustiveness)
+        const refLines = contents
+          .split('\n')
+          .filter((line) => line.includes('domain.terms/'))
+          .map((line) => line.trim())
+          .join('\n');
+        expect(refLines).toMatchSnapshot('boot.yml glossary refs');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-migration/declarations/practices/rhachet/boot-yml-findsert.declapract.integration.test.ts

@@ -0,0 +1,145 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the boot.yml FINDSERT (#105 req 1), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer whose boot.yml already carries its
+ *         OWN say + ref entries.
+ * .why  = req 1 is that the boot.yml is only ever findserted into a consumer, never whole-file
+ *         overwritten — so a consumer's own boot entries survive. per
+ *         `rule.require.declapract-integration-tests`, a `fix` with logic (a yaml union that reads the
+ *         consumer's extant file) owes a pipeline test: a unit test of the exported `fix` never
+ *         exercises the glob→file match nor the apply against a real consumer file. this is that test.
+ * .note = the consumer boot is SIMPLE mode with a `say` pick and a `ref` pick of its own. the
+ *         after-state proves both declared deep-variant globs are unioned in AND both consumer picks
+ *         survive byte-for-value — the whole-file-overwrite failure this guards against would drop them.
+ * .note = the boot is snapshotted in full (before AND after) so a reviewer can eyeball the exact
+ *         end-state (`rule.require.snapshots`).
+ */
+describe('rhachet — boot.yml findsert (req 1: consumer entries survive)', () => {
+  given("[case1] a consumer whose boot.yml carries its own entries", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-findsert',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+    const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: bootPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the consumer boot.yml carries its own picks, no budget, + matches snapshot', async () => {
+        const before = await read(bootPath);
+        expect(before).toContain('briefs/my-own-brief.md');
+        expect(before).toContain('briefs/my-own-deep-variant.md');
+        // the consumer predates the budget cap — it carries none (the findsert-add path)
+        expect(yaml.parse(before).budget).toBeUndefined();
+        expect(before).toMatchSnapshot('boot.yml — before');
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('union the declared deep-variant globs into the consumer boot', async () =>
+        applyFix(),
+      );
+
+      then(
+        "both declared globs land AND the consumer's own say + ref picks survive, and it matches snapshot",
+        async () => {
+          const after = await read(bootPath);
+          const parsed = yaml.parse(after);
+
+          // the two declared deep-variant globs were unioned into the consumer's ref list
+          expect(parsed.briefs.ref).toContain(REASON_REF);
+          expect(parsed.briefs.ref).toContain(EXAMPLE_REF);
+          // the consumer's OWN ref pick survives (the whole-overwrite failure would drop it)
+          expect(parsed.briefs.ref).toContain('briefs/my-own-deep-variant.md');
+          // the consumer's OWN say pick survives untouched
+          expect(parsed.briefs.say).toContain('briefs/my-own-brief.md');
+          // it stayed simple mode — the fix created no top-level always: key
+          expect(parsed.always).toBeUndefined();
+          // the budget cap was findserted into a consumer that predated it
+          expect(parsed.budget.tokens).toEqual(5_000);
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('boot.yml — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // once both globs are present, the check passes and the fix is a no-op — the boot must be
+      // byte-identical across a re-apply (`rule.require.idempotent-fixes`).
+      const passes = useThen(
+        'a second apply over its own output',
+        async () => {
+          const before = await read(bootPath);
+          await applyFix();
+          const after = await read(bootPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+
+  given("[case2] a consumer whose boot.yml already declares a divergent budget", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-budget-preserved',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const bootAbs = path.join(tempDir, bootPath);
+
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: bootPath,
+      });
+
+    // seed the writable clone with a budget the consumer chose on purpose — a value the findsert
+    // must NOT revert (findsert, never upsert). this proves the present-value-preserved branch
+    // through the real pipeline, no extra fixture needed.
+    when('[t0] the consumer set its own budget of 9000', () => {
+      useThen('write a divergent budget into the cloned boot', async () => {
+        const before = await fs.readFile(bootAbs, 'utf-8');
+        await fs.writeFile(bootAbs, `${before}budget:\n  tokens: 9000\n`, 'utf-8');
+      });
+
+      then('the seed carries the consumer budget', async () => {
+        expect(yaml.parse(await fs.readFile(bootAbs, 'utf-8')).budget.tokens).toEqual(9000);
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('apply the fix over the consumer-chosen budget', async () => applyFix());
+
+      then("the consumer's budget survives untouched (findsert, never upsert)", async () => {
+        const parsed = yaml.parse(await fs.readFile(bootAbs, 'utf-8'));
+        expect(parsed.budget.tokens).toEqual(9000);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-migration/declarations/practices/tests-any/__snapshots__/changedsince-origin-main.declapract.integration.test.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`tests-any changedSince=origin/main policy given: the shipped best-practice/package.json when: the changed-file test commands are read then: the emitted changed-file commands match snapshot: tests-any changed-file commands 1`] = `
+{
+  "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n "\${CI:-}" ] && echo '--ci') $([ "\${THOROUGH:-}" != "true" ] && echo '--changedSince=origin/main') $([ "\${RESNAP:-}" = "true" ] && echo '--updateSnapshot')",
+  "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n "\${CI:-}" ] && echo '--ci') $([ "\${THOROUGH:-}" != "true" ] && echo '--changedSince=origin/main') $([ "\${RESNAP:-}" = "true" ] && echo '--updateSnapshot')",
+}
+`;

package/dist/.test/assets/expo-migration/declarations/practices/tests-any/autoprune-hooks.declapract.integration.test.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that every jest config template the tests-node / tests-expo practices ship
+ *         REACHES both autoprune hooks -- never one without the other -- whether it wires the
+ *         autoprune setup DIRECTLY or through a COMPOSITE globalSetup.
+ * .why  = test-fns >=1.16 reclaims the temp dirs genTempDir makes, but jest needs TWO keys:
+ *         globalSetup stamps the run, globalTeardown reclaims its dirs. a config with globalSetup
+ *         and NO globalTeardown stamps every dir and reclaims none -- the half-wired state #590
+ *         names, which test-fns itself detects + reports but the practice must never SHIP. the
+ *         floor bump (tests-any package.json, test-fns >=1.17.0) delivers the capability; this
+ *         clamp guards the wire-up so a future edit cannot drop one key and leave the other.
+ * .why-composite = #598 makes the two node suite configs (integration + acceptance) COMPOSE an
+ *         livedb wake with autoprune's setup, so their `globalSetup` points at a local
+ *         `jest.<suite>.prepare.ts` rather than the `test-fns/autoprune.setup.jest` subpath
+ *         directly. jest allows ONE globalSetup, so the composite is how both run. this clamp
+ *         follows the indirection: a composite config still REACHES autoprune iff its globalSetup
+ *         file imports the autoprune subpath. so a drop of the autoprune import from a composite
+ *         reddens here exactly as a drop of the direct key would.
+ * .teeth = remove `globalTeardown` from any config, OR remove the autoprune setup from a direct
+ *          config, OR drop the `test-fns/autoprune.setup.jest` import from a composite globalSetup
+ *          file, and the matched case reddens (the both-reached-together assertion).
+ * .note = the subject is the shipped TEMPLATE text, read as a string -- so this clamp is
+ *         independent of which test-fns version is installed here (the autoprune subpaths only
+ *         need to load in a CONSUMER, which the floor bump guarantees). the `.declapract.test.ts`
+ *         suffix is this repo's UNIT-test marker; declapract's loader excludes `.test.ts`, so this
+ *         file is neither loaded as a declaration nor copied to a consumer.
+ */
+
+// a DIRECT config wires the setup as `globalSetup: 'test-fns/autoprune.setup.jest'`; a COMPOSITE
+// file IMPORTS it as `... from 'test-fns/autoprune.setup.jest'`. the two forms are distinct on
+// purpose: a `.why` comment may quote the `globalSetup: '...'` form as prose, so the composite
+// reach-check matches the IMPORT form (`from '...'`), which a comment does not carry -- else a
+// mere mention of the subpath in a comment would satisfy the clamp (a teeth hole caught in dogfood).
+const SETUP_DIRECT_KEY = "globalSetup: 'test-fns/autoprune.setup.jest'";
+const SETUP_IMPORT = "from 'test-fns/autoprune.setup.jest'";
+const TEARDOWN_KEY = "globalTeardown: 'test-fns/autoprune.teardown.jest'";
+
+// anchor on __dirname, not process.cwd(): the repo-root-relative paths below must point at the same
+// file wherever jest is invoked from (a nested `jest src/practices/...` run has a different cwd).
+// from this file (src/practices/tests-any/) the repo root is three segments up.
+const REPO_ROOT = join(__dirname, '../../..');
+
+// each config either wires the autoprune setup DIRECTLY, or COMPOSES it via a local globalSetup
+// file that imports the autoprune subpath. `composite` names that file, relative to the practice.
+const configs: { relPath: string; composite: string | null }[] = [
+  { relPath: 'src/practices/tests-node/best-practice/jest.unit.config.ts', composite: null },
+  {
+    relPath: 'src/practices/tests-node/best-practice/jest.integration.config.ts',
+    composite: 'src/practices/tests-node/best-practice/jest.integration.prepare.ts',
+  },
+  {
+    relPath: 'src/practices/tests-node/best-practice/jest.acceptance.config.ts',
+    composite: 'src/practices/tests-node/best-practice/jest.acceptance.prepare.ts',
+  },
+  { relPath: 'src/practices/tests-expo/best-practice/jest.unit.config.ts', composite: null },
+  { relPath: 'src/practices/tests-expo/best-practice/jest.integration.config.ts', composite: null },
+  { relPath: 'src/practices/tests-expo/best-practice/jest.acceptance.config.ts', composite: null },
+];
+
+/**
+ * .what = whether a config REACHES the autoprune setup -- directly, or through its composite.
+ * .why  = the invariant #590 guards is "setup is reached", not "setup is inline". a composite
+ *         config reaches it iff its globalSetup file imports the autoprune subpath.
+ */
+const reachesAutopruneSetup = (input: {
+  configContents: string;
+  composite: string | null;
+}): boolean => {
+  // direct: the config itself wires `globalSetup: 'test-fns/autoprune.setup.jest'`
+  if (input.configContents.includes(SETUP_DIRECT_KEY)) return true;
+
+  // composite: the config points at a local globalSetup file that IMPORTS the autoprune subpath
+  if (!input.composite) return false;
+  const compositeContents = readFileSync(join(REPO_ROOT, input.composite), 'utf8');
+  return compositeContents.includes(SETUP_IMPORT);
+};
+
+describe('autoprune hook reach across the shipped jest configs', () => {
+  for (const { relPath, composite } of configs) {
+    given(`[case] ${relPath}${composite ? ' (composite)' : ' (direct)'}`, () => {
+      const configContents = readFileSync(join(REPO_ROOT, relPath), 'utf8');
+
+      when('[t0] the shipped config is read', () => {
+        then('it reaches the autoprune setup (stamps the run)', () => {
+          expect(reachesAutopruneSetup({ configContents, composite })).toEqual(true);
+        });
+
+        then('it wires globalTeardown (reclaims the dirs)', () => {
+          expect(configContents).toContain(TEARDOWN_KEY);
+        });
+
+        then('it never ships one hook without the other (half-wired = stamp, no reclaim)', () => {
+          const reachesSetup = reachesAutopruneSetup({ configContents, composite });
+          const hasTeardown = configContents.includes(TEARDOWN_KEY);
+          expect(reachesSetup).toEqual(hasTeardown);
+        });
+      });
+    });
+  }
+});

package/dist/.test/assets/expo-migration/declarations/practices/tests-any/bad-practices/old-acceptance-import-paths/.declapract.readme.md

@@ -21,11 +21,11 @@ replaces all occurrences of `acceptance/` with `blackbox/` in import paths.
 before:
 ```typescript
 import { locally } from '../acceptance/environment';
-import { stage } from '../../acceptance/utils/environment';
+import { access } from '../../acceptance/utils/environment';
 ```
 
 after:
 ```typescript
 import { locally } from '../blackbox/environment';
-import { stage } from '../../blackbox/utils/environment';
+import { access } from '../../blackbox/utils/environment';
 ```

package/dist/.test/assets/expo-migration/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/lambdas/<star>.ts.declapract.ts

@@ -20,7 +20,6 @@ export const fix: FileFixFunction = async (contents, context) => {
         `import { invokeLambda } from '../_utils/invokeLambda';`,
         [
           `import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';`,
-          `import { stage } from '../../src/utils/environment';`,
           `import { locally } from '../environment';`,
         ].join('\n'),
       )
@@ -30,14 +29,15 @@ export const fix: FileFixFunction = async (contents, context) => {
         'invokeLambdaForTesting({',
       )
       .replace(
-        // replace the inputs
-        /name: '(\w+)',/g,
-        [
-          `service: '${projectName}',`,
-          `function: '$1',`,
-          `stage,`,
-          `locally,`,
-        ].join('\n'),
+        // replace the inputs; capture the indent that precedes `name:` so the
+        // expanded 3-line option block stays aligned with its siblings
+        /^([ \t]*)name: '(\w+)',/gm,
+        (_match, indent, fnName) =>
+          [
+            `${indent}service: '${projectName}',`,
+            `${indent}function: '${fnName}',`,
+            `${indent}locally,`,
+          ].join('\n'),
       )
       .replace(/data: /g, 'event: '),
   };

package/dist/.test/assets/expo-migration/declarations/practices/tests-any/best-practice/package.json

@@ -4,12 +4,12 @@
     "@types/jest": "@declapract{check.minVersion('30.0.0')}",
     "jest": "@declapract{check.minVersion('30.2.0')}",
     "esbuild-register": "@declapract{check.minVersion('3.6.0')}",
-    "test-fns": "@declapract{check.minVersion('1.15.8')}",
+    "test-fns": "@declapract{check.minVersion('1.17.0')}",
     "tsx": "@declapract{check.minVersion('4.20.6')}"
   },
   "scripts": {
-    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
-    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=origin/main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=origin/main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
     "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
     "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
     "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')"