declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/tests-expo/best-practice/jest.acceptance.config.ts

@@ -0,0 +1,48 @@
+/**
+ * @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}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  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',
+  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;

package/dist/practices/tests-expo/best-practice/jest.acceptance.env.ts

@@ -0,0 +1,15 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since the web build surface is exercised end-to-end
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;

package/dist/practices/tests-expo/best-practice/jest.config.ts

@@ -0,0 +1,7 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import config from './jest.unit.config';
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/practices/tests-expo/best-practice/jest.integration.config.ts

@@ -0,0 +1,47 @@
+/**
+ * @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 = a single jsdom project with react-native-web + expo module
+  // resolution, so integration tests that reach the expo/react-native boundary load
+  // under jsdom.
+  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/integration.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: ['**/*.integration.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  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',
+  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;

package/dist/practices/tests-expo/best-practice/jest.integration.env.ts

@@ -0,0 +1,26 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+import { ConstraintError } from 'helpful-errors';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since downstream apis are reached
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/**
+ * sanity check that integration tests only run in the 'test' environment
+ * .why = prevent prod state pollution + financial mutations from test data
+ */
+if (process.env.NODE_ENV !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new ConstraintError(
+    `integration.test config must be 'test' — set NODE_ENV=test (or I_KNOW_THE_RISKS=true to override)`,
+    { nodeEnv: process.env.NODE_ENV ?? null },
+  );

package/dist/practices/tests-expo/best-practice/jest.unit.config.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 wires up babel-preset-expo (metro's transform) + react-native module
+  // resolution (platform suffixes, haste). this is what lets tests that reach the
+  // expo/react-native boundary load, where a plain node preset cannot.
+  preset: 'jest-expo',
+
+  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/unit.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // the jest-expo preset's transformIgnorePatterns assume a hoisted (flat) node_modules.
+  // pnpm's `.pnpm/`-nested store ships react-native/expo as untranspiled ESM one layer
+  // deeper, so add a `.pnpm/` branch that still transforms those families. a repo that
+  // pulls other untranspiled-ESM packages (e.g. a native storage lib) appends its own
+  // package names to BOTH branches.
+  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: [
+    // note: order matters
+    '**/*.test.{ts,tsx}',
+    '!**/*.acceptance.test.{ts,tsx}',
+    '!**/*.integration.test.{ts,tsx}',
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  setupFilesAfterEnv: ['./jest.unit.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',
+  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;

package/dist/practices/tests-expo/best-practice/jest.unit.env.ts

@@ -0,0 +1,23 @@
+import util from 'node:util';
+
+import { ConstraintError } from 'helpful-errors';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/**
+ * sanity check that unit tests only run in the 'test' environment
+ * .why = prevent prod state pollution + financial mutations from test data
+ */
+if (process.env.NODE_ENV !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new ConstraintError(
+    `unit.test config must be 'test' — set NODE_ENV=test (or I_KNOW_THE_RISKS=true to override)`,
+    { nodeEnv: process.env.NODE_ENV ?? null },
+  );

package/dist/practices/tests-expo/best-practice/package.json.declapract.ts

@@ -0,0 +1,193 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { asPackageJSON } from '../../../utils/asPackageJSON';
+
+/**
+ * .what = the expo half of the tests triad: the jest-expo transform stack that replaces
+ *         node's `@swc/jest`. this check GATES the SDK-coupled majors on the repo's OWN
+ *         expo + react majors, rather than floor them at a fixed baseline.
+ * .why  = jest-expo's preset pokes react internals of the SDK it targets. a fixed
+ *         `minVersion('54.0.0')` floor forces jest-expo 54 (a react-19-era preset) onto an
+ *         expo-51 / react-18 repo, and every unit suite throws
+ *         `TypeError: Object.defineProperty called on non-object` at jest-expo's preset setup
+ *         (#584 / defect D1). the two crashing deps each track a major 1:1:
+ *           - jest-expo major  == expo major  (jest-expo 54 pairs with expo 54)
+ *           - react-test-renderer major == react major (rtr ships lockstep with react)
+ *         so the gate reads the repo's OWN expo + react majors and requires a match — which
+ *         holds jest-expo at 51 on an expo-51 repo and at 54 on an expo-54 repo, with no
+ *         version table to rot as new SDKs ship.
+ * .note = @babel/core + babel-preset-expo + isomorphic-fetch stay MINIMA (not the crash; each a
+ *         plain floor the pre-gate template already declared). babel-preset-expo also tracks the
+ *         SDK, but backward-compatibly; its floor is left as a residual — see .deliver/584.md.
+ * .note = a repo with no `expo` dep is not an expo repo in a gate-able state; the check passes
+ *         (returns) rather than flags, so a non-expo package.json is never falsely reddened.
+ */
+
+const BABEL_CORE_MIN = { major: 7, minor: 24, patch: 0 };
+const BABEL_PRESET_EXPO_MIN = { major: 12, minor: 0, patch: 0 };
+const ISOMORPHIC_FETCH_MIN = { major: 3, minor: 0, patch: 0 };
+
+interface SemverTriple {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** parse the leading `major.minor.patch` out of a semver range (`^54.0.0`, `~19.1.2`, `>=3.0.0`). */
+const parseVersionTriple = (range: string | undefined): SemverTriple | null => {
+  if (!range) return null;
+  const match = range.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+};
+
+const majorOf = (range: string | undefined): number | null =>
+  parseVersionTriple(range)?.major ?? null;
+
+const meetsMinimum = (
+  range: string | undefined,
+  min: SemverTriple,
+): boolean => {
+  const found = parseVersionTriple(range);
+  if (!found) return false;
+  if (found.major !== min.major) return found.major > min.major;
+  if (found.minor !== min.minor) return found.minor > min.minor;
+  return found.patch >= min.patch;
+};
+
+/** the subset of a package.json this declaration reads + rewrites (dep maps), typed rather than `any`. */
+interface PackageJSON {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+const getAllDeps = (packageJSON: PackageJSON): Record<string, string> => ({
+  ...(packageJSON.dependencies ?? {}),
+  ...(packageJSON.devDependencies ?? {}),
+});
+
+export const check: FileCheckFunction = (contents) => {
+  // no file → no gate to enforce; a best-practice check passes (returns) when clean
+  if (!contents) return;
+
+  const packageJSON: PackageJSON = asPackageJSON(
+    { contents },
+    {
+      practice: 'tests-expo',
+    },
+  );
+  const deps = getAllDeps(packageJSON);
+
+  // a repo with no `expo` dep is not an expo repo in a gate-able state — do not flag it
+  const expoMajor = majorOf(deps.expo);
+  if (expoMajor === null) return;
+
+  // jest-expo major must MATCH the repo's expo major (jest-expo tracks the SDK 1:1)
+  const jestExpoMajor = majorOf(deps['jest-expo']);
+  if (jestExpoMajor !== expoMajor)
+    throw new ConstraintError(
+      `jest-expo major (${jestExpoMajor}) must match the repo's expo major (${expoMajor}) — run \`declapract apply\` to pin jest-expo to ^${expoMajor}.0.0`,
+      { found: jestExpoMajor, required: expoMajor, dep: 'jest-expo' },
+    );
+
+  // react-test-renderer major must MATCH the repo's react major (rtr ships lockstep with react)
+  const reactMajor = majorOf(deps.react);
+  if (reactMajor !== null) {
+    const rtrMajor = majorOf(deps['react-test-renderer']);
+    if (rtrMajor !== reactMajor)
+      throw new ConstraintError(
+        `react-test-renderer major (${rtrMajor}) must match the repo's react major (${reactMajor}) — run \`declapract apply\` to pin react-test-renderer to ^${reactMajor}.0.0`,
+        { found: rtrMajor, required: reactMajor, dep: 'react-test-renderer' },
+      );
+  }
+
+  // @babel/core + babel-preset-expo + isomorphic-fetch stay MINIMA (not the crash; a plain
+  // floor, exactly as the pre-gate template declared each of the three)
+  if (!meetsMinimum(deps['@babel/core'], BABEL_CORE_MIN))
+    throw new ConstraintError(
+      '@babel/core must be >= 7.24.0 — run `declapract apply` to raise it',
+      {
+        found: deps['@babel/core'] ?? null,
+        required: '7.24.0',
+        dep: '@babel/core',
+      },
+    );
+  if (!meetsMinimum(deps['babel-preset-expo'], BABEL_PRESET_EXPO_MIN))
+    throw new ConstraintError(
+      'babel-preset-expo must be >= 12.0.0 — run `declapract apply` to raise it',
+      {
+        found: deps['babel-preset-expo'] ?? null,
+        required: '12.0.0',
+        dep: 'babel-preset-expo',
+      },
+    );
+  if (!meetsMinimum(deps['isomorphic-fetch'], ISOMORPHIC_FETCH_MIN))
+    throw new ConstraintError(
+      'isomorphic-fetch must be >= 3.0.0 — run `declapract apply` to raise it',
+      {
+        found: deps['isomorphic-fetch'] ?? null,
+        required: '3.0.0',
+        dep: 'isomorphic-fetch',
+      },
+    );
+
+  // all gates satisfied
+  return;
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON: PackageJSON = asPackageJSON(
+    { contents },
+    {
+      practice: 'tests-expo',
+    },
+  );
+  const deps = getAllDeps(packageJSON);
+  const expoMajor = majorOf(deps.expo);
+
+  // no expo dep → not a gate-able expo repo; leave untouched
+  if (expoMajor === null) return { contents };
+
+  const devDependencies = { ...(packageJSON.devDependencies ?? {}) };
+  const dependencies = { ...(packageJSON.dependencies ?? {}) };
+
+  // jest-expo + react-test-renderer are test-time deps that belong in devDependencies ALONE. pin
+  // them there AND delete any copy under `dependencies` — else the merged getAllDeps check (dev
+  // wins) reads green while npm installs ONE version and a stale `dependencies` copy at a conflicting
+  // major can win at install time (the two-section version conflict r006.b1 forbids). the sibling
+  // dep declarations (logs/leveled-term, rhachet/prod-deps) strip from both sections for the same reason.
+  devDependencies['jest-expo'] = `^${expoMajor}.0.0`;
+  delete dependencies['jest-expo'];
+
+  // pin react-test-renderer to the repo's react major, when a react dep is present
+  const reactMajor = majorOf(deps.react);
+  if (reactMajor !== null) {
+    devDependencies['react-test-renderer'] = `^${reactMajor}.0.0`;
+    delete dependencies['react-test-renderer'];
+  }
+
+  // raise @babel/core + babel-preset-expo + isomorphic-fetch to their minima when below
+  if (!meetsMinimum(deps['@babel/core'], BABEL_CORE_MIN))
+    devDependencies['@babel/core'] = '^7.24.0';
+  if (!meetsMinimum(deps['babel-preset-expo'], BABEL_PRESET_EXPO_MIN))
+    devDependencies['babel-preset-expo'] = '^12.0.0';
+  if (!meetsMinimum(deps['isomorphic-fetch'], ISOMORPHIC_FETCH_MIN))
+    devDependencies['isomorphic-fetch'] = '^3.0.0';
+
+  // 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;
+
+  return {
+    contents: JSON.stringify(result, null, 2),
+  };
+};

package/dist/practices/tests-expo/package.json.declapract.integration.test.ts

@@ -0,0 +1,94 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the tests-expo jest-expo/rtr SDK-major gate (#584 / defect D1).
+ * .why  = the unit test proves the check/fix in isolation; only the real executeApply pipeline
+ *         proves declapract WIRES the declaration to `package.json` and reaches a fixed point on
+ *         a re-run. the crash this gate prevents is a react-19-era jest-expo (54) held onto an
+ *         expo-51 / react-18 repo — every unit suite throws at jest-expo's preset setup — so the
+ *         gate must hold jest-expo at the repo's OWN expo major (51), never bump it to 54.
+ * .note = scoped `practice: 'tests-expo'` — the declaration reads only `contents`, never
+ *         `context.projectPractices`, so a practice scope is safe (no usecase-aware branch goes
+ *         dark) and isolates the apply to tests-expo's package.json declaration alone.
+ */
+describe('tests-expo package.json — pipeline gate on the repo expo/react major', () => {
+  given('[case1] an expo-51 / react-18 repo seeded with a react-19-era jest-expo 54 the gate aligns down to the expo major (51)', () => {
+    const tempDir = genTempDir({
+      slug: 'tests-expo-major-gate',
+      clone: './src/.test/assets/expo-migration/repo-app-protools-shaped',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo-migration/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const pkgPath = () => path.join(tempDir, 'package.json');
+    const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
+
+    const state = useBeforeAll(async () => {
+      // seed the crash shape: a react-19-era jest-expo/rtr on an expo-51 / react-18 repo
+      const seeded = {
+        ...JSON.parse(await readPkg()),
+        devDependencies: {
+          ...JSON.parse(await readPkg()).devDependencies,
+          expo: '~51.0.0',
+          react: '18.2.0',
+          'jest-expo': '^54.0.0',
+          'react-test-renderer': '^19.0.0',
+          'babel-preset-expo': '^12.0.0',
+          'isomorphic-fetch': '^3.0.0',
+        },
+      };
+      await fs.writeFile(pkgPath(), `${JSON.stringify(seeded, null, 2)}\n`);
+      const pkgBefore = await readPkg();
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      return { pkgBefore, pkgAfter1, pkgAfter2 };
+    }, 170_000);
+
+    when('[t0] the tests-expo gate is applied to the seeded package.json', () => {
+      then('jest-expo is held at the repo expo major (51), not bumped to 54', () => {
+        expect(JSON.parse(state.pkgBefore).devDependencies['jest-expo']).toEqual(
+          '^54.0.0',
+        );
+        expect(JSON.parse(state.pkgAfter1).devDependencies['jest-expo']).toEqual(
+          '^51.0.0',
+        );
+      });
+
+      then('react-test-renderer is held at the repo react major (18), not 19', () => {
+        expect(
+          JSON.parse(state.pkgAfter1).devDependencies['react-test-renderer'],
+        ).toEqual('^18.0.0');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.pkgBefore).toMatchSnapshot('package.json — before');
+        expect(state.pkgAfter1).toMatchSnapshot('package.json — after gate');
+      });
+
+      then('a second apply is a fixed point (the gate holds)', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+  });
+});

package/dist/practices/tests-node/__snapshots__/livedb-wake-branches.declapract.integration.test.ts.snap

@@ -0,0 +1,6 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`the useWakeOfLivedb decide-gate runs its real branches (executed, no live infra) given: the wake command fails when: it fails with a child-process shape (a non-zero exit) then: the wake-failure warn matches snapshot: useWakeOfLivedb wake-failure warn 1`] = `
+"useWakeOfLivedb: 'rhx use.rds.capacity --env prep' failed (non-fatal): {"status":1}
+"
+`;

package/dist/practices/tests-node/bad-practices/babel/babel.config.js.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/practices/tests-node/bad-practices/deprecated-test-deps/package.json.declapract.ts

@@ -0,0 +1,50 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+const deprecatedDeps = [
+  'babel-jest',
+  '@babel/core',
+  '@babel/preset-env',
+  'core-js',
+  'ts-jest',
+];
+
+/**
+ * .what = returns a deps map with every deprecated key removed, without any mutation
+ * .why  = the fix strips deprecated test deps; rule.require.immutable-vars forbids a
+ *         delete-in-place on the copied deps object, so it filters into a fresh map instead
+ */
+const withoutDeprecatedDeps = (
+  deps: Record<string, string> | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(deps ?? {}).filter(([dep]) => !deprecatedDeps.includes(dep)),
+  );
+
+/**
+ * .what = removes the deprecated node-jest test deps from a package.json's
+ *         dependencies + devDependencies
+ * .why  = deps like babel-jest, ts-jest, @babel/* belong to the retired node-jest
+ *         toolchain; a repo on the @swc/jest config no longer needs them, so this
+ *         bad-practice fix drops them
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // no-op when the file is absent
+  const packageJSON = JSON.parse(contents);
+
+  // remove deprecated deps from devDependencies + dependencies (non-mutating filter)
+  const updatedDevDeps = withoutDeprecatedDeps(packageJSON.devDependencies);
+  const updatedDeps = withoutDeprecatedDeps(packageJSON.dependencies);
+
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: Object.keys(updatedDeps).length > 0 ? updatedDeps : undefined,
+    devDependencies:
+      Object.keys(updatedDevDeps).length > 0 ? updatedDevDeps : undefined,
+  };
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/{tests → tests-node}/best-practice/jest.acceptance.config.ts

@@ -32,6 +32,14 @@ const config: Config = {
   testMatch: ['**/*.acceptance.test.ts', '!**/.agent/.cache/**', '!**/.yalc/**'],
   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
+  // (resume the shared aurora-serverless cluster before the first query) with autoprune's setup,
+  // and forwards globalConfig to it — a bare 'test-fns/autoprune.setup.jest' would leave the db
+  // un-woken.
+  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
 };

package/dist/practices/tests-node/best-practice/jest.acceptance.env.ts

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+import { ConstraintError } from 'helpful-errors';
+
+import { useKeyrack } from './src/.test/useKeyrack';
+
+jest.setTimeout(90000); // we're calling downstream apis
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+/**
+ * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
+ */
+if (!existsSync(join(process.cwd(), 'package.json')))
+  throw new ConstraintError(
+    'no package.json found in cwd — run the acceptance suite from the git root',
+    { cwd: process.cwd() },
+  );
+
+/**
+ * .what = source credentials from keyrack for the target tier and export them for the aws-sdk-v2
+ *         lambda caller, in one call.
+ * .why =
+ *   - a cloud acceptance run targets a deployed tier (e.g. prep), derived from ACCESS; default to the
+ *     lowest-privilege `test` when unset, so a PR / local in-process run stays on test creds.
+ *   - useKeyrack is the org convention: it sources keyrack (sets AWS_PROFILE), sets ACCESS, and — for
+ *     an aws consumer — exports the sso profile's static creds so aws-sdk-v2 auths against the target
+ *     (keyrack.source alone sets only AWS_PROFILE, which v2 cannot use). #586.
+ *   - `strict` fails fast with a helpful error if keyrack is locked or a key is absent.
+ */
+useKeyrack({ env: (process.env.ACCESS ?? 'test') as 'test' | 'prep' | 'prod', mode: 'strict' });