declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/.test/assets/expo-fullusecase/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-fullusecase/declarations/practices/tests-any/bad-practices/javascript-config-files/jest.<star>.js.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = deletes a stale `.js` jest config file
+ * .why  = the go-forward jest config is `.ts` (see .declapract.readme.md). a leftover
+ *         `.js` jest config (e.g. a jsdom `jest.config.js` or a `jest.unit.config.js`)
+ *         is redundant and fights the shipped `.ts` config — the dual-source hazard the
+ *         app-protools-native migration must reconcile. drop the redundant `.js`; the
+ *         best-practice supplies the canonical `.ts` config in the same pass.
+ * .note  = `{ contents: null }` removes the file. idempotent: once gone, the EXISTS
+ *          check no longer detects it, so a re-run is a no-op.
+ */
+export const fix: FileFixFunction = () => {
+  return { contents: null };
+};

package/dist/{practices/tests → .test/assets/expo-fullusecase/declarations/practices/tests-any}/bad-practices/old-acceptance-dir-location/.declapract.integration.test.ts

@@ -12,7 +12,7 @@ describe('old-acceptance-dir-location', () => {
   given('[case1] accept.blackbox/ with various file types', () => {
     const tempDir = genTempDir({
       slug: 'declapract-old-acceptance-dir',
-      clone: './src/practices/tests/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir',
+      clone: './src/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir',
       symlink: [{ at: 'src', to: 'src' }],
     });
 
@@ -31,7 +31,7 @@ describe('old-acceptance-dir-location', () => {
       useThen('fix is applied', async () => {
         await executeApply({
           config: path.join(tempDir, 'declapract.use.yml'),
-          practice: 'tests',
+          practice: 'tests-any',
         });
       });
 

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/{practices/tests → .test/assets/expo-fullusecase/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-fullusecase/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/_utils/getDataFromLastOpenBracketAtStartOfLine.ts.declapract.ts

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

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/_utils/invokeLambda.ts.declapract.ts

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

package/dist/{practices/tests → .test/assets/expo-fullusecase/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-fullusecase/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils-3/blackbox/_utils/environment.ts.declapract.ts

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

package/dist/{practices/tests → .test/assets/expo-fullusecase/declarations/practices/tests-any}/best-practice/package.json

@@ -4,14 +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')}",
-    "tsx": "@declapract{check.minVersion('4.20.6')}",
-    "@swc/core": "@declapract{check.minVersion('1.15.3')}",
-    "@swc/jest": "@declapract{check.minVersion('0.2.39')}"
+    "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')"

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

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

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

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #531: the shipped `test:unit` + `test:integration` commands scope changed-file
+ *         detection against `origin/main`, NEVER bare `main`.
+ * .why  = a local `main` drifts behind the real trunk the moment a teammate merges without a local
+ *         pull, so `--changedSince=main` drags unrelated already-merged suites into scope — the
+ *         exact stale-ref defect #531 names. `origin/main` is the true fork point, so the scope
+ *         holds only this branch's own change.
+ * .teeth = revert either command to `--changedSince=main` in best-practice/package.json and the
+ *          "no bare main" assertion reddens (the emitted `echo '--changedSince=main'` carries the
+ *          `--changedSince=main'` token; the origin form carries `--changedSince=origin/main'`,
+ *          which does NOT contain it).
+ * .note = the subject is the shipped TEMPLATE, read once from __dirname (a single static-file read,
+ *         as the kin `dpdmrc-exclude-policy` / `commitlint-body-max-line` clamps do). this file
+ *         sits at the practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('tests-any changedSince=origin/main policy', () => {
+  given('the shipped best-practice/package.json', () => {
+    const parsed = JSON.parse(
+      readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+    );
+    const scripts: Record<string, string> = parsed?.scripts ?? {};
+
+    when('the changed-file test commands are read', () => {
+      then('test:unit scopes against origin/main', () => {
+        expect(scripts['test:unit']).toContain('--changedSince=origin/main');
+      });
+
+      then('test:integration scopes against origin/main', () => {
+        expect(scripts['test:integration']).toContain(
+          '--changedSince=origin/main',
+        );
+      });
+
+      then('neither command scopes against a bare local main', () => {
+        // the emitted flag is quoted: `echo '--changedSince=origin/main'`. a bare-main revert
+        // emits `echo '--changedSince=main'`, whose `--changedSince=main'` token the origin form
+        // never carries — so this token is the precise teeth for the drift #531 forbids.
+        const bareMainToken = "--changedSince=main'";
+        expect(scripts['test:unit']).not.toContain(bareMainToken);
+        expect(scripts['test:integration']).not.toContain(bareMainToken);
+      });
+
+      // the emitted commands are the caller-faced contract: snapshot both so a reword that keeps
+      // the origin token green (a re-ordered flag, a reshaped command) reddens a vibecheck.
+      then('the emitted changed-file commands match snapshot', () => {
+        expect({
+          'test:unit': scripts['test:unit'],
+          'test:integration': scripts['test:integration'],
+        }).toMatchSnapshot('tests-any changed-file commands');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/package.json.shell-flags.declapract.integration.test.ts

@@ -0,0 +1,139 @@
+import { execSync } from 'child_process';
+
+/**
+ * .what = read the whitespace-split arg list out of the stand-in jest echo output.
+ * .why  = a pure transformer that names the `JEST_ARGS: …` decode, so `getJestFlags` reads
+ *         what-not-how rather than an inline regex-match + positional `match[1]` a reader must
+ *         simulate. no output line = an empty arg list.
+ */
+const asArgsFromJestEchoOutput = (input: { output: string }): string[] => {
+  const found = input.output.match(/JEST_ARGS: (.*)/);
+  if (!found) return [];
+  return found[1].split(/\s+/).filter(Boolean);
+};
+
+/**
+ * Tests the shell flag expressions used in package.json test commands.
+ *
+ * These tests verify that env vars like RESNAP and THOROUGH produce
+ * the correct flags when passed to jest via the package.json commands.
+ *
+ * We use a stand-in jest function that echoes the arguments it receives,
+ * so we can verify what flags would actually be passed.
+ *
+ * .why integration = this drives a real `bash -c` via execSync — a child-process
+ *   boundary. per rule.forbid.unit.remote-boundaries a `.test.ts` (unit) may not
+ *   cross a process boundary, so the shell-flag behavior is proven at the
+ *   integration grain, where a real shell is the point of the test.
+ */
+describe('package.json shell flag expressions', () => {
+  /**
+   * Evaluates a shell command with given env vars and returns the arguments
+   * that would be passed to jest (everything after the config flag).
+   */
+  const getJestFlags = (
+    command: string,
+    env: Record<string, string | undefined>,
+  ): string[] => {
+    // .note = deliberate mutation — cleanEnv is built up across two scoped local loops (base env
+    //         minus the flag vars, then the test overlay); a single-threaded local zone
+    //         (rule.require.immutable-vars sanctions in-place mutation with this note).
+    const cleanEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (!['CI', 'THOROUGH', 'RESNAP'].includes(key) && value !== undefined) {
+        cleanEnv[key] = value;
+      }
+    }
+    // overlay the test env vars (undefined means unset)
+    for (const [key, value] of Object.entries(env)) {
+      if (value !== undefined) {
+        cleanEnv[key] = value;
+      }
+    }
+
+    // run the command with jest replaced by echo to capture args
+    const result = execSync(
+      `bash -c 'jest() { echo "JEST_ARGS: $*"; }; ${command}'`,
+      {
+        env: cleanEnv,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // bound the call so a stuck shell fails fast rather than hangs the suite;
+        // the command is a trivial echo, so 5s is generous
+        timeout: 5000,
+      },
+    );
+
+    // read the jest args out of the stand-in echo output (named, what-not-how)
+    return asArgsFromJestEchoOutput({ output: result });
+  };
+
+  // the test:unit command from package.json best-practice
+  const testUnitCommand = `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')`;
+
+  describe('RESNAP flag', () => {
+    it('should pass --updateSnapshot when RESNAP=true', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: 'true' });
+      expect(flags).toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP is unset', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP=false', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: 'false' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP is empty string', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: '' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP=0', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: '0' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+  });
+
+  describe('THOROUGH flag', () => {
+    it('should pass --changedSince=origin/main when THOROUGH is unset (run only changed)', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).toContain('--changedSince=origin/main');
+    });
+
+    it('should pass --changedSince=origin/main when THOROUGH=false', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'false' });
+      expect(flags).toContain('--changedSince=origin/main');
+    });
+
+    it('should pass --changedSince=origin/main when THOROUGH is empty string', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: '' });
+      expect(flags).toContain('--changedSince=origin/main');
+    });
+
+    it('should not pass --changedSince=origin/main when THOROUGH=true (run all tests)', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'true' });
+      expect(flags).not.toContain('--changedSince=origin/main');
+    });
+  });
+
+  describe('CI flag', () => {
+    it('should pass --ci when CI=true', () => {
+      const flags = getJestFlags(testUnitCommand, { CI: 'true' });
+      expect(flags).toContain('--ci');
+    });
+
+    it('should pass --ci when CI=1', () => {
+      const flags = getJestFlags(testUnitCommand, { CI: '1' });
+      expect(flags).toContain('--ci');
+    });
+
+    it('should not pass --ci when CI is unset', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).not.toContain('--ci');
+    });
+  });
+});

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

@@ -0,0 +1,138 @@
+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 usecase evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the expo test-toolchain triad (typescript-expo + tests-expo,
+ *         paired with typescript-any + tests-any).
+ * .why  = the shared cicd-common `.test.yml` runs `npm run build`, `test:types`,
+ *         `test:unit`, `test:integration`, `test:acceptance` unconditionally. before the
+ *         triad, the expo usecase carried none of those commands/configs, so a fresh expo
+ *         consumer's CI aborted at `npm run build`. this proves `declapract fix` on the
+ *         expo usecase EMITS the whole stack — the expo build (`expo export`), the
+ *         typecheck, and the jest-expo unit/integration/acceptance configs — so CI runs.
+ */
+describe('expo test-toolchain triad — pipeline', () => {
+  given('[case1] a fresh expo repo on the app-react-native-expo usecase', () => {
+    const tempDir = genTempDir({
+      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' },
+      ],
+    });
+
+    const read = (rel: string) =>
+      fs.readFile(path.join(tempDir, rel), 'utf-8').catch(() => null);
+
+    // useBeforeAll RETURNS the captured state (no in-place mutation of a shared const)
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+
+      // apply the whole expo usecase (all four triad practices), thrice.
+      // .why = declapract adds a new minVersion dep to an already-present package.json as
+      //        its raw `@declapract{check.minVersion(..)}` expression on the first pass,
+      //        then resolves it to the concrete version on the next pass (a net-new file
+      //        is resolved immediately). so package.json settles at apply-2, and apply-3
+      //        is the true fixed point. a net-new file (tsconfig, jest configs) is a fixed
+      //        point from apply-1.
+      await executeApply({ config });
+      const tsconfigAfter1 = await read('tsconfig.json');
+      const jestUnitAfter1 = await read('jest.unit.config.ts');
+      const jestIntegrationAfter1 = await read('jest.integration.config.ts');
+      const jestAcceptanceAfter1 = await read('jest.acceptance.config.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');
+
+      await executeApply({ config });
+      const pkgAfter3 = await read('package.json'); // must equal pkgSettled
+
+      return {
+        pkgSettled,
+        pkgAfter3,
+        tsconfigAfter1,
+        jestUnitAfter1,
+        jestIntegrationAfter1,
+        jestAcceptanceAfter1,
+        tsconfigAfter2,
+        jestUnitAfter2,
+      };
+    }, 170_000);
+
+    when('[t0] declapract fix emits the toolchain', () => {
+      then('package.json carries every command cicd-common runs', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        // the exact commands cicd-common/.test.yml invokes
+        expect(pkg.scripts.build).toBeDefined();
+        expect(pkg.scripts['test:types']).toEqual('tsc -p ./tsconfig.json --noEmit');
+        expect(pkg.scripts['test:unit']).toContain('jest -c ./jest.unit.config.ts');
+        expect(pkg.scripts['test:integration']).toContain(
+          'jest -c ./jest.integration.config.ts',
+        );
+        expect(pkg.scripts['test:acceptance']).toContain(
+          'jest -c ./jest.acceptance.config.ts',
+        );
+      });
+
+      then('the build command is the expo web export, not tsc', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        // `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');
+        expect(pkg.scripts.build).toEqual('npm run build:web');
+      });
+
+      then('package.json carries the typescript dep at a concrete version, and the SDK-coupled expo deps gated to the repo majors', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        // typescript is a plain minVersion floor (tests-any), resolved concrete on pass 2
+        expect(pkg.devDependencies.typescript).toEqual('5.4.5');
+        // jest-expo + react-test-renderer are GATED to the repo's own expo/react majors (#584):
+        // the fixture declares expo ^54 + react ^19, so the gate pins jest-expo to the expo major
+        // and react-test-renderer to the react major (caret, not a fixed pin — the major is the gate)
+        expect(pkg.devDependencies['jest-expo']).toEqual('^54.0.0');
+        expect(pkg.devDependencies['react-test-renderer']).toEqual('^19.0.0');
+      });
+
+      then('tsconfig.json extends the expo base, not the node base', () => {
+        const tsconfig = JSON.parse(state.tsconfigAfter1!);
+        expect(tsconfig.extends).toEqual('expo/tsconfig.base');
+      });
+
+      then('the jest configs use the jest-expo preset', () => {
+        expect(state.jestUnitAfter1).toContain("preset: 'jest-expo'");
+        expect(state.jestIntegrationAfter1).toContain("preset: 'jest-expo/web'");
+        expect(state.jestAcceptanceAfter1).toContain("preset: 'jest-expo/web'");
+      });
+
+      then('the emitted package.json + tsconfig + jest.unit match snapshot', () => {
+        expect(state.pkgSettled).toMatchSnapshot('package.json — after fix');
+        expect(state.tsconfigAfter1).toMatchSnapshot('tsconfig.json — after fix');
+        expect(state.jestUnitAfter1).toMatchSnapshot('jest.unit.config.ts — after fix');
+      });
+    });
+
+    when('[t1] declapract fix is re-applied', () => {
+      then('package.json is a fixed point once settled', () => {
+        expect(state.pkgAfter3).toEqual(state.pkgSettled);
+      });
+
+      then('tsconfig.json is a fixed point', () => {
+        expect(state.tsconfigAfter2).toEqual(state.tsconfigAfter1);
+      });
+
+      then('jest.unit.config.ts is a fixed point', () => {
+        expect(state.jestUnitAfter2).toEqual(state.jestUnitAfter1);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-expo/.test/assets/repo-expo-greenfield/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test to test/assets/expo-toolchain/declarations
+# .why  = a fresh expo repo, used to prove the typescript + tests triads emit the expo
+#         build/typecheck/jest stack that cicd-common's .test.yml runs.
+# .note = no variables — the four triad practices reference only @declapract{check.minVersion}.
+declarations: 'declarations/declapract.declare.yml'
+useCase: app-react-native-expo

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-expo/.test/assets/repo-expo-greenfield/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "test-expo-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "expo": "^54.0.0",
+    "react": "^19.0.0"
+  }
+}