declapract-typescript-ehmpathy 0.49.13 → 0.49.14

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

@@ -2,7 +2,9 @@ import fs from 'fs/promises';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
-import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
 
 // executeApply is slow (full usecase evaluation)
 jest.setTimeout(180_000);
@@ -19,13 +21,11 @@ jest.setTimeout(180_000);
  */
 describe('expo test-toolchain triad — pipeline', () => {
   given('[case1] a fresh expo repo on the app-react-native-expo usecase', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'expo-toolchain',
       clone: './src/practices/tests-expo/.test/assets/repo-expo-greenfield',
-      symlink: [
-        { at: 'declarations', to: './src/.test/assets/expo-toolchain/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/expo-toolchain/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     const read = (rel: string) =>
@@ -47,11 +47,19 @@ describe('expo test-toolchain triad — pipeline', () => {
       const jestUnitAfter1 = await read('jest.unit.config.ts');
       const jestIntegrationAfter1 = await read('jest.integration.config.ts');
       const jestAcceptanceAfter1 = await read('jest.acceptance.config.ts');
+      const prepareIntegrationAfter1 = await read('jest.integration.prepare.ts');
+      const prepareAcceptanceAfter1 = await read('jest.acceptance.prepare.ts');
+      const wakeAfter1 = await read('src/.test/useWakeOfLivedb.ts');
+      const autopruneTypesAfter1 = await read(
+        'src/.test/assets/test-fns.autoprune.d.ts',
+      );
 
       await executeApply({ config });
       const pkgSettled = await read('package.json'); // resolved versions
       const tsconfigAfter2 = await read('tsconfig.json');
       const jestUnitAfter2 = await read('jest.unit.config.ts');
+      const prepareAcceptanceAfter2 = await read('jest.acceptance.prepare.ts');
+      const wakeAfter2 = await read('src/.test/useWakeOfLivedb.ts');
 
       await executeApply({ config });
       const pkgAfter3 = await read('package.json'); // must equal pkgSettled
@@ -65,6 +73,12 @@ describe('expo test-toolchain triad — pipeline', () => {
         jestAcceptanceAfter1,
         tsconfigAfter2,
         jestUnitAfter2,
+        prepareIntegrationAfter1,
+        prepareAcceptanceAfter1,
+        wakeAfter1,
+        autopruneTypesAfter1,
+        prepareAcceptanceAfter2,
+        wakeAfter2,
       };
     }, 170_000);
 
@@ -88,7 +102,10 @@ describe('expo test-toolchain triad — pipeline', () => {
         // `typescript-expo` is the SOLE declarer of `build:web` — `cicd-app-react-native-expo`
         // no longer re-declares it, so there is no second CONTAINS declarer to oscillate
         // with (the single-source shape this repo's convergence/oscillation lesson prefers).
-        expect(pkg.scripts['build:web']).toEqual('npx expo export --platform web');
+        // the export defaults ACCESS to prep, so an absent access never builds for prod (#619)
+        expect(pkg.scripts['build:web']).toEqual(
+          'ACCESS=${ACCESS:-prep} expo export --platform web',
+        );
         expect(pkg.scripts.build).toEqual('npm run build:web');
       });
 
@@ -119,6 +136,37 @@ describe('expo test-toolchain triad — pipeline', () => {
         expect(state.tsconfigAfter1).toMatchSnapshot('tsconfig.json — after fix');
         expect(state.jestUnitAfter1).toMatchSnapshot('jest.unit.config.ts — after fix');
       });
+
+      then('the integration + acceptance configs compose the livedb wake via-gateway (#621)', () => {
+        expect(state.jestIntegrationAfter1).toContain("globalSetup: './jest.integration.prepare.ts'");
+        expect(state.jestAcceptanceAfter1).toContain("globalSetup: './jest.acceptance.prepare.ts'");
+        expect(state.prepareIntegrationAfter1).toContain("reaches: 'via-gateway'");
+        expect(state.prepareAcceptanceAfter1).toContain("reaches: 'via-gateway'");
+        expect(state.wakeAfter1).toContain('export const getWakeDecision');
+      });
+
+      then('the autoprune subpath types are emitted, for expo sdk < 54 (moduleResolution node)', () => {
+        expect(state.autopruneTypesAfter1).toContain(
+          "declare module 'test-fns/autoprune.setup.jest'",
+        );
+        expect(state.prepareIntegrationAfter1).toContain(
+          '/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />',
+        );
+        expect(state.prepareAcceptanceAfter1).toContain(
+          '/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />',
+        );
+      });
+
+      then('the jest configs exclude .agent/.actors and match the `._.` kind seam (#647, #679)', () => {
+        expect(state.jestUnitAfter1).toContain("'!**/.agent/.actors/**'");
+        expect(state.jestIntegrationAfter1).toContain("'**/*._.intg.test.{ts,tsx}'");
+        expect(state.jestAcceptanceAfter1).toContain("'**/*._.acpt.test.{ts,tsx}'");
+      });
+
+      then('the emitted acceptance config + prepare match snapshot', () => {
+        expect(state.jestAcceptanceAfter1).toMatchSnapshot('jest.acceptance.config.ts — after fix');
+        expect(state.prepareAcceptanceAfter1).toMatchSnapshot('jest.acceptance.prepare.ts — after fix');
+      });
     });
 
     when('[t1] declapract fix is re-applied', () => {
@@ -133,6 +181,11 @@ describe('expo test-toolchain triad — pipeline', () => {
       then('jest.unit.config.ts is a fixed point', () => {
         expect(state.jestUnitAfter2).toEqual(state.jestUnitAfter1);
       });
+
+      then('the acceptance prepare and the wake util are fixed points', () => {
+        expect(state.prepareAcceptanceAfter2).toEqual(state.prepareAcceptanceAfter1);
+        expect(state.wakeAfter2).toEqual(state.wakeAfter1);
+      });
     });
   });
 });

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

@@ -1,5 +1,103 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted acceptance config + prepare match snapshot: jest.acceptance.config.ts — after fix 1`] = `
+"/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo/web = jsdom + react-native-web, so acceptance tests exercise the web build
+  // surface. (a repo that prefers a device/simulator acceptance harness, e.g. playwright
+  // against the exported web app, swaps this out — the cicd-common shard runner reads the
+  // jest config named here.)
+  preset: 'jest-expo/web',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/acceptance.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // pnpm-nested react-native/expo ESM must still transform (see jest.unit.config.ts).
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: [
+    '**/*.acceptance.test.{ts,tsx}',
+    '**/*._.acpt.test.{ts,tsx}', // the \`._.\` kind seam; both suffix forms match
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  // skip all of \`.agent/\`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
+  setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
+
+  // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
+  // one without the other stamps and never reclaims. the globalSetup COMPOSES the livedb wake
+  // (an expo app reaches the shared cluster via its gateway) with autoprune's setup.
+  globalSetup: './jest.acceptance.prepare.ts',
+  globalTeardown: 'test-fns/autoprune.teardown.jest',
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;
+"
+`;
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted acceptance config + prepare match snapshot: jest.acceptance.prepare.ts — after fix 1`] = `
+"/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />
+import autopruneSetup from 'test-fns/autoprune.setup.jest';
+
+import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
+
+/**
+ * .what = jest globalSetup for the expo acceptance suite — runs once, in the main process, before
+ *         jest forks its workers.
+ * .why =
+ *   - an expo app owns no database, but it reaches one THROUGH its gateway, whose peers query the
+ *     shared aurora-serverless cluster. at min-capacity 0 that cluster auto-pauses, so the first
+ *     query after a pause cold-starts past the timeout and flakes the suite.
+ *   - the wake is \`via-gateway\`: an expo app has no \`config/\` dir with a db tunnel to gate on, so
+ *     the test kind itself is the signal — an acceptance run reaches a deployment by construction.
+ *   - an expo acceptance run may declare ACCESS=prod; the wake refuses prod, so a test run never
+ *     writes capacity against production.
+ *   - COMPOSES the wake with test-fns autoprune in jest's ONE globalSetup: wake FIRST (best-effort),
+ *     THEN autoprune mints the run id. \`globalConfig\` is FORWARDED to autoprune unchanged, so its
+ *     half-wired-state check reads the real \`globalTeardown\` slot.
+ * .note = \`useWakeOfLivedb\` is imported by RELATIVE path, never the \`@src\` alias — a globalSetup is
+ *         loaded BEFORE jest's moduleNameMapper exists, so \`@src\` here fails at startup.
+ */
+// biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
+export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
+  // the wake refuses prod (prod never scales to 0); every other access wakes the prep cluster
+  await useWakeOfLivedb({
+    env: process.env.ACCESS === 'prod' ? 'prod' : null,
+    reaches: 'via-gateway',
+  });
+  await autopruneSetup(globalConfig);
+};
+"
+`;
+
 exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: jest.unit.config.ts — after fix 1`] = `
 "/**
  * @jest-config-loader esbuild-register
@@ -40,12 +138,21 @@ const config: Config = {
   ],
   testMatch: [
     // note: order matters
-    '**/*.test.{ts,tsx}',
+    '**/*.test.{ts,tsx}', // also matches the \`._.unit.test\` kind seam
     '!**/*.acceptance.test.{ts,tsx}',
     '!**/*.integration.test.{ts,tsx}',
+    '!**/*.evaluation.test.{ts,tsx}',
+    '!**/*._.acpt.test.{ts,tsx}',
+    '!**/*._.intg.test.{ts,tsx}',
+    '!**/*._.eval.test.{ts,tsx}',
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
     '!**/.agent/.cache/**',
     '!**/.yalc/**',
   ],
+  // skip all of \`.agent/\`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.unit.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
@@ -71,28 +178,29 @@ exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo
     "react": "^19.0.0"
   },
   "devDependencies": {
+    "@babel/core": "^7.24.0",
     "@jest/globals": "30.2.0",
     "@types/jest": "30.0.0",
-    "jest": "30.2.0",
+    "babel-preset-expo": "^12.0.0",
     "esbuild-register": "3.6.0",
-    "test-fns": "1.17.0",
-    "tsx": "4.20.6",
+    "isomorphic-fetch": "^3.0.0",
+    "jest": "30.2.0",
     "jest-expo": "^54.0.0",
     "react-test-renderer": "^19.0.0",
-    "@babel/core": "^7.24.0",
-    "babel-preset-expo": "^12.0.0",
-    "isomorphic-fetch": "^3.0.0",
+    "test-fns": "1.17.0",
+    "tsx": "4.20.6",
     "typescript": "5.4.5"
   },
   "scripts": {
+    "build:ifstale": "set -eu && if [ -f dist/.build.stamp ] && [ -z \\"$(find src assets package.json pnpm-lock.yaml tsconfig.json tsconfig.build.json app.json app.config.ts -newer dist/.build.stamp -type f ! -name '*.test.ts' ! -name '*.test.tsx' ! -name '*.snap' -print -quit 2>/dev/null)\\" ]; then echo '👌 dist is fresh, build skipped'; else npm run build && touch dist/.build.stamp; fi",
     "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:acceptance:locally": "set -eu && npm run build:ifstale && 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')",
     "test:types": "tsc -p ./tsconfig.json --noEmit",
     "build": "npm run build:web",
-    "build:web": "npx expo export --platform web"
+    "build:web": "ACCESS=\${ACCESS:-prep} expo export --platform web"
   }
 }
 "

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/__snapshots__/package.json.declapract.integration.test.ts.snap

@@ -16,13 +16,13 @@ exports[`tests-expo package.json — pipeline gate on the repo expo/react major
     "@commitlint/format": "19.9.9"
   },
   "devDependencies": {
-    "expo": "~51.0.0",
-    "react": "18.2.0",
-    "jest-expo": "^51.0.0",
-    "react-test-renderer": "^18.0.0",
+    "@babel/core": "^7.24.0",
     "babel-preset-expo": "^12.0.0",
+    "expo": "~51.0.0",
     "isomorphic-fetch": "^3.0.0",
-    "@babel/core": "^7.24.0"
+    "jest-expo": "^51.0.0",
+    "react": "18.2.0",
+    "react-test-renderer": "^18.0.0"
   }
 }
 "

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

@@ -0,0 +1,108 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = clamps that the expo `jest.*.prepare.ts` templates find the types of the
+ *         `test-fns/autoprune.setup.jest` subpath under BOTH module lookups an expo app compiles with
+ * .why  = expo sdk < 54 sets `moduleResolution: node`, which ignores `exports`; test-fns ships the
+ *         subpath only via `exports`, so the import is TS2307 there (F88). each prepare file reaches the
+ *         `src/.test/assets/test-fns.autoprune.d.ts` stand-in via a triple-slash reference, so the
+ *         adopter's tsconfig `include` (which skips dot dirs) never has to name it
+ * .teeth = drop the reference line from a prepare file, or the stand-in, and [case2] reddens
+ * .note = an integration test: the compile reads this repo's installed test-fns from disk
+ */
+const BEST_PRACTICE_DIR = path.join(__dirname, 'best-practice');
+const PREPARE_FILES = [
+  path.join(BEST_PRACTICE_DIR, 'jest.integration.prepare.ts'),
+  path.join(BEST_PRACTICE_DIR, 'jest.acceptance.prepare.ts'),
+];
+const SUBPATH = 'test-fns/autoprune.setup.jest';
+const REFERENCE_LINE =
+  '/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />\n';
+
+/**
+ * .what = compiles the given files and returns each diagnostic that concerns the autoprune subpath
+ * .why  = the prepare files also import peer-practice files absent from this dir; only the subpath
+ *         diagnostics are this clamp's concern
+ */
+const getSubpathDiagnostics = (input: {
+  rootNames: string[];
+  lookup: 'node' | 'bundler';
+}): { diagnostics: string[] } => {
+  const program = ts.createProgram({
+    rootNames: input.rootNames,
+    options: {
+      noEmit: true,
+      skipLibCheck: true,
+      strict: true,
+      esModuleInterop: true,
+      target: ts.ScriptTarget.ESNext,
+      types: [],
+      ...(input.lookup === 'node'
+        ? { moduleResolution: ts.ModuleResolutionKind.Node10 }
+        : {
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+          }),
+    },
+  });
+  const diagnostics = ts
+    .getPreEmitDiagnostics(program)
+    .map((diagnostic) =>
+      ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+    )
+    .filter((message) => message.includes(SUBPATH));
+  return { diagnostics };
+};
+
+describe('tests-expo autoprune subpath types', () => {
+  given('[case1] the prepare templates with the reference line stripped', () => {
+    when('[t0] compiled with moduleResolution node (expo sdk < 54)', () => {
+      const result = useThen('the compile completes', async () => {
+        // copy each prepare file into a temp dir that lacks the stand-in, minus the reference
+        const dir = genTempDir({ slug: 'tests-expo-autoprune-unreferenced' });
+        const rootNames = PREPARE_FILES.map((file) => {
+          const copy = path.join(dir, path.basename(file));
+          writeFileSync(copy, readFileSync(file, 'utf8').replace(REFERENCE_LINE, ''));
+          return copy;
+        });
+        return getSubpathDiagnostics({ rootNames, lookup: 'node' });
+      });
+
+      then('the subpath is TS2307 — the defect the stand-in exists for', () => {
+        expect(result.diagnostics.length).toEqual(PREPARE_FILES.length);
+        expect(result.diagnostics[0]).toContain(`Cannot find module '${SUBPATH}'`);
+      });
+    });
+  });
+
+  given('[case2] the shipped prepare templates, as an adopter compiles them', () => {
+    then('each prepare file carries the reference line', () => {
+      for (const file of PREPARE_FILES)
+        expect(readFileSync(file, 'utf8').startsWith(REFERENCE_LINE)).toEqual(true);
+    });
+
+    when('[t0] compiled with moduleResolution node (expo sdk < 54)', () => {
+      const result = useThen('the compile completes', async () =>
+        getSubpathDiagnostics({ rootNames: PREPARE_FILES, lookup: 'node' }),
+      );
+
+      then('the subpath types are found, with no diagnostic', () => {
+        expect(result.diagnostics).toEqual([]);
+      });
+    });
+
+    when('[t1] compiled with moduleResolution bundler (expo sdk 54+)', () => {
+      const result = useThen('the compile completes', async () =>
+        getSubpathDiagnostics({ rootNames: PREPARE_FILES, lookup: 'bundler' }),
+      );
+
+      then('the subpath types are found, with no diagnostic', () => {
+        expect(result.diagnostics).toEqual([]);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/jest.acceptance.config.ts

@@ -32,12 +32,23 @@ const config: Config = {
     'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
     'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
   ],
-  testMatch: ['**/*.acceptance.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  testMatch: [
+    '**/*.acceptance.test.{ts,tsx}',
+    '**/*._.acpt.test.{ts,tsx}', // the `._.` kind seam; both suffix forms match
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
-  // one without the other stamps and never reclaims.
-  globalSetup: 'test-fns/autoprune.setup.jest',
+  // one without the other stamps and never reclaims. the globalSetup COMPOSES the livedb wake
+  // (an expo app reaches the shared cluster via its gateway) with autoprune's setup.
+  globalSetup: './jest.acceptance.prepare.ts',
   globalTeardown: 'test-fns/autoprune.teardown.jest',
 
   // use 50% of threads to leave headroom for other processes

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/jest.acceptance.prepare.ts

@@ -0,0 +1,31 @@
+/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />
+import autopruneSetup from 'test-fns/autoprune.setup.jest';
+
+import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
+
+/**
+ * .what = jest globalSetup for the expo acceptance suite — runs once, in the main process, before
+ *         jest forks its workers.
+ * .why =
+ *   - an expo app owns no database, but it reaches one THROUGH its gateway, whose peers query the
+ *     shared aurora-serverless cluster. at min-capacity 0 that cluster auto-pauses, so the first
+ *     query after a pause cold-starts past the timeout and flakes the suite.
+ *   - the wake is `via-gateway`: an expo app has no `config/` dir with a db tunnel to gate on, so
+ *     the test kind itself is the signal — an acceptance run reaches a deployment by construction.
+ *   - an expo acceptance run may declare ACCESS=prod; the wake refuses prod, so a test run never
+ *     writes capacity against production.
+ *   - COMPOSES the wake with test-fns autoprune in jest's ONE globalSetup: wake FIRST (best-effort),
+ *     THEN autoprune mints the run id. `globalConfig` is FORWARDED to autoprune unchanged, so its
+ *     half-wired-state check reads the real `globalTeardown` slot.
+ * .note = `useWakeOfLivedb` is imported by RELATIVE path, never the `@src` alias — a globalSetup is
+ *         loaded BEFORE jest's moduleNameMapper exists, so `@src` here fails at startup.
+ */
+// biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
+export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
+  // the wake refuses prod (prod never scales to 0); every other access wakes the prep cluster
+  await useWakeOfLivedb({
+    env: process.env.ACCESS === 'prod' ? 'prod' : null,
+    reaches: 'via-gateway',
+  });
+  await autopruneSetup(globalConfig);
+};

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/jest.integration.config.ts

@@ -31,12 +31,23 @@ const config: Config = {
     'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
     'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
   ],
-  testMatch: ['**/*.integration.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  testMatch: [
+    '**/*.integration.test.{ts,tsx}',
+    '**/*._.intg.test.{ts,tsx}', // the `._.` kind seam; both suffix forms match
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.integration.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
-  // one without the other stamps and never reclaims.
-  globalSetup: 'test-fns/autoprune.setup.jest',
+  // one without the other stamps and never reclaims. the globalSetup COMPOSES the livedb wake
+  // (an expo app reaches the shared cluster via its gateway) with autoprune's setup.
+  globalSetup: './jest.integration.prepare.ts',
   globalTeardown: 'test-fns/autoprune.teardown.jest',
 
   // use 50% of threads to leave headroom for other processes

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/jest.integration.prepare.ts

@@ -0,0 +1,29 @@
+/// <reference path="./src/.test/assets/test-fns.autoprune.d.ts" />
+import autopruneSetup from 'test-fns/autoprune.setup.jest';
+
+import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
+
+/**
+ * .what = jest globalSetup for the expo integration suite — runs once, in the main process, before
+ *         jest forks its workers.
+ * .why =
+ *   - an expo app owns no database, but it reaches one THROUGH its gateway, whose peers query the
+ *     shared aurora-serverless cluster. at min-capacity 0 that cluster auto-pauses, so the first
+ *     query after a pause cold-starts past the timeout and flakes the suite.
+ *   - the wake is `via-gateway`: an expo app has no `config/` dir with a db tunnel to gate on, so
+ *     the test kind itself is the signal — an integration run reaches a deployment by construction.
+ *   - COMPOSES the wake with test-fns autoprune in jest's ONE globalSetup: wake FIRST (best-effort),
+ *     THEN autoprune mints the run id. `globalConfig` is FORWARDED to autoprune unchanged, so its
+ *     half-wired-state check reads the real `globalTeardown` slot.
+ * .note = `useWakeOfLivedb` is imported by RELATIVE path, never the `@src` alias — a globalSetup is
+ *         loaded BEFORE jest's moduleNameMapper exists, so `@src` here fails at startup.
+ */
+// biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
+export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
+  // the wake refuses prod (prod never scales to 0); every other access wakes the prep cluster
+  await useWakeOfLivedb({
+    env: process.env.ACCESS === 'prod' ? 'prod' : null,
+    reaches: 'via-gateway',
+  });
+  await autopruneSetup(globalConfig);
+};

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/jest.unit.config.ts

@@ -37,12 +37,21 @@ const config: Config = {
   ],
   testMatch: [
     // note: order matters
-    '**/*.test.{ts,tsx}',
+    '**/*.test.{ts,tsx}', // also matches the `._.unit.test` kind seam
     '!**/*.acceptance.test.{ts,tsx}',
     '!**/*.integration.test.{ts,tsx}',
+    '!**/*.evaluation.test.{ts,tsx}',
+    '!**/*._.acpt.test.{ts,tsx}',
+    '!**/*._.intg.test.{ts,tsx}',
+    '!**/*._.eval.test.{ts,tsx}',
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
     '!**/.agent/.cache/**',
     '!**/.yalc/**',
   ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.unit.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;

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

@@ -67,6 +67,17 @@ interface PackageJSON {
   [key: string]: unknown;
 }
 
+/**
+ * .what = a dep map with its keys in alphabetical order, as npm and pnpm write them
+ * .why  = the fix adds deps; appended in place, they land after the sorted keys, so
+ *         package-json-order re-sorts them on the next apply and this fix re-appends them, and
+ *         the two practices never converge
+ */
+const asSortedDeps = (deps: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(deps).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  );
+
 const getAllDeps = (packageJSON: PackageJSON): Record<string, string> => ({
   ...(packageJSON.dependencies ?? {}),
   ...(packageJSON.devDependencies ?? {}),
@@ -184,8 +195,12 @@ export const fix: FileFixFunction = (contents) => {
 
   // preserve each section's presence: rewrite `dependencies` ONLY when the manifest already declared
   // one (so a repo with no prod deps never gains an empty `dependencies: {}` it did not have).
-  const result: PackageJSON = { ...packageJSON, devDependencies };
-  if (packageJSON.dependencies) result.dependencies = dependencies;
+  const result: PackageJSON = {
+    ...packageJSON,
+    devDependencies: asSortedDeps(devDependencies),
+  };
+  if (packageJSON.dependencies)
+    result.dependencies = asSortedDeps(dependencies);
 
   return {
     contents: JSON.stringify(result, null, 2),

package/dist/.test/assets/expo-migration/declarations/practices/tests-expo/best-practice/src/.test/assets/test-fns.autoprune.d.ts

@@ -0,0 +1,14 @@
+/**
+ * .what = types for the `test-fns/autoprune.setup.jest` subpath, which the `jest.*.prepare.ts` files
+ *         import and reach via a triple-slash reference
+ * .why = expo sdk < 54 resolves with `moduleResolution: node`, which ignores `exports`; test-fns ships
+ *        the subpath only via `exports`, so the import is TS2307 there (jest loads it fine at runtime)
+ * .note = a stand-in. it retires once test-fns ships `typesVersions` for its subpaths
+ */
+declare module 'test-fns/autoprune.setup.jest' {
+  const autopruneSetup: (globalConfig: {
+    globalTeardown?: string | null;
+  }) => Promise<void>;
+  // biome-ignore lint/style/noDefaultExport: mirrors the jest globalSetup default export
+  export default autopruneSetup;
+}