declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-acceptance-dir-location/acceptance/<star><star>/<star>.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if any files exist in acceptance/, flag as bad practice
+
+/**
+ * .what = moves any file from acceptance/ to blackbox/
+ * .why = ensures all files are moved, not just .ts files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from acceptance/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^acceptance\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

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

@@ -0,0 +1,31 @@
+# old-acceptance-import-paths
+
+## .what
+
+detects import statements that reference the old `acceptance/` directory path.
+
+## .why
+
+the `acceptance/` directory has been renamed to `blackbox/` to make the testing philosophy explicit:
+- blackbox tests interact only through public contracts
+- no access to internal implementation details
+
+import paths must be updated to reference `blackbox/` instead of `acceptance/`.
+
+## .fix
+
+replaces all occurrences of `acceptance/` with `blackbox/` in import paths.
+
+## .examples
+
+before:
+```typescript
+import { locally } from '../acceptance/environment';
+import { stage } from '../../acceptance/utils/environment';
+```
+
+after:
+```typescript
+import { locally } from '../blackbox/environment';
+import { stage } from '../../blackbox/utils/environment';
+```

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-acceptance-import-paths/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,25 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects imports that reference acceptance/ directory
+ * .why = acceptance/ has been renamed to blackbox/
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match imports that reference acceptance/ directory
+  if (contents?.match(/from ['"]\.\.?\/.*acceptance\//)) return; // matches bad practice
+  if (contents?.match(/from ['"]acceptance\//)) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = replaces acceptance/ with blackbox/ in import paths
+ * .why = blackbox/ naming makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(/(['"])(.*)\/acceptance\//g, '$1$2/blackbox/')
+      .replace(/(['"])acceptance\//g, '$1blackbox/'),
+  };
+};

package/dist/.test/assets/expo-toolchain/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-toolchain/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/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,44 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { getProjectVariables } from '../../../../../../getVariables';
+
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents?.includes(`import { invokeLambda } from '../_utils/invokeLambda';`)
+  )
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents, context) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  const { projectName } = await getProjectVariables(context);
+  return {
+    contents: contents
+      .replace(
+        // replace the bad import
+        `import { invokeLambda } from '../_utils/invokeLambda';`,
+        [
+          `import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';`,
+          `import { stage } from '../../src/utils/environment';`,
+          `import { locally } from '../environment';`,
+        ].join('\n'),
+      )
+      .replace(
+        // replace calls to the fn
+        /invokeLambda\(\{/g,
+        'invokeLambdaForTesting({',
+      )
+      .replace(
+        // replace the inputs
+        /name: '(\w+)',/g,
+        [
+          `service: '${projectName}',`,
+          `function: '$1',`,
+          `stage,`,
+          `locally,`,
+        ].join('\n'),
+      )
+      .replace(/data: /g, 'event: '),
+  };
+};

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

@@ -0,0 +1,22 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents?.includes(
+      `import { locally } from '../__test_utils__/environment';`,
+    )
+  )
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  return {
+    contents: contents.replace(
+      // replace the bad import
+      `import { locally } from '../__test_utils__/environment';`,
+      `import { locally } from '../environment';`,
+    ),
+  };
+};

package/dist/.test/assets/expo-toolchain/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/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-acceptance-test-utils-3/blackbox/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,18 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes(`import { locally } from '../_utils/environment';`))
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  return {
+    contents: contents.replace(
+      // replace the bad import
+      `import { locally } from '../_utils/environment';`,
+      `import { locally } from '../environment';`,
+    ),
+  };
+};

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-extension-pattern/.declapract.readme.md

@@ -0,0 +1,3 @@
+a previous, now deprecated, best practice was to have the extension of `*.test.integration.ts` or `*.test.acceptance.ts` on test files
+
+we've since moved over to `*.integration.test.ts` and `*.acceptance.test.ts` (it having the `.test.ts` extension still makes tools that dont expect different test types work with these test files out of the box, which is a nice to have)

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-extension-pattern/<star><star>/<star>.test.acceptance.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.acceptance\.ts$/,
+    '.acceptance.test.ts',
+  ),
+  contents,
+});

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-extension-pattern/<star><star>/<star>.test.integration.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.integration\.ts$/,
+    '.integration.test.ts',
+  ),
+  contents,
+});

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-test-utils-and-assets-location/.declapract.readme.md

@@ -0,0 +1,8 @@
+test utilities and assets should be located in `.test.utils/` or `.test.assets/` instead of `__test_utils__` or `__test_assets__`
+
+the `.test.utils/` directory replaces `__test_utils__` and `.test.assets/` replaces `__test_assets__` in the same relative location.
+
+examples:
+- `src/domain/__test_utils__/exampleUser.ts` → `src/domain/.test.utils/exampleUser.ts`
+- `src/logic/__test_assets__/fixtures.json` → `src/logic/.test.assets/fixtures.json`
+- `blackbox/__test_utils__/environment.ts` → `blackbox/.test.utils/environment.ts`

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,27 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * check if file has imports from __test_utils__ or __test_assets__ directories
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('__test_utils__')) return; // matches bad practice
+  if (contents?.includes('__test_assets__')) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * replace __test_utils__ and __test_assets__ with .test.utils and .test.assets in import paths
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  // simple string replacement - the relative path stays the same, only the directory name changes
+  // e.g., from '../__test_utils__/foo' to '../.test.utils/foo'
+  const fixedContents = contents
+    .replace(/__test_utils__\//g, '.test.utils/')
+    .replace(/__test_assets__\//g, '.test.assets/');
+
+  return {
+    contents: fixedContents,
+  };
+};

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/__test_assets__/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import type { FileFixFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files exist in __test_assets__ directories, it's bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move from any/**/__test_assets__/**/* to .test.assets/**/*
+  const newPath = context.relativeFilePath.replace(
+    /__test_assets__\//g,
+    '.test.assets/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/__test_utils__/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import type { FileFixFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files exist in __test_utils__ directories, it's bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move from any/**/__test_utils__/**/* to .test.utils/**/*
+  const newPath = context.relativeFilePath.replace(
+    /__test_utils__\//g,
+    '.test.utils/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/best-practice/.declapract.readme.md

@@ -0,0 +1,45 @@
+# best practices for testing
+
+## purpose of testing:
+- think use cases, edge cases, and play with the business logic / model you've defined
+- define use cases, edge cases, and previous failure points explicitly for future reference
+- automate checking that:
+  - code complies with spec (i.e., all use cases and requirements are satisfied)
+  - regressions will not occur
+  - predicted error cases are covered
+
+## three test types:
+- unit tests
+  - test precisely scoped business logic, mocking out all dependencies
+  - purpose is to test that the unit/function of logic that you're defining does the logic in it correctly
+- integration tests
+  - test end to end logic OR test boundaries between calling a dependent service
+  - for example:
+    - test boundaries with a dependent api
+      - test that we are communicating w/ database correctly
+      - test that we are
+    - test end to end logic
+      - test that a handler acts correctly in different cases
+      - test that a highly composed business logic function produces the correct results in all cases
+- acceptance tests
+  - test that the deployed product works
+  - ideally: test an end to end pipeline of each use case it needs to support
+    - note: typically its sufficient to trust that integration tests have already tested the use cases and then all we need to test is that the lambda can be hit
+
+// todo: add examples to the above
+// todo: finesse the above definitions now that we're formally defining them
+
+## pattern
+
+- each test type gets its own file extension
+  - unit -> `.test.ts` (the default extension)
+  - integration -> `.integration.test.ts`
+  - acceptance -> `.acceptance.test.ts`
+- each test type gets its own config (e.g., specify what extension to use)
+  - `jest.unit.config`
+  - `jest.integration.config`
+  - `jest.acceptance.config`
+- each test type gets its own environment setup file (e.g., global mocks, or checks, etc)
+  - `jest.unit.env`
+  - `jest.integration.env`
+  - `jest.acceptance.env`

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/best-practice/.declapract.todo.md

@@ -0,0 +1,3 @@
+cutover to vitest
+
+its faster and has native esm + ts support

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

@@ -0,0 +1,17 @@
+{
+  "devDependencies": {
+    "@jest/globals": "@declapract{check.minVersion('30.2.0')}",
+    "@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')}"
+  },
+  "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: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-toolchain/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-toolchain/declarations/practices/tests-any/best-practice/package.json.shell-flags.declapract.integration.test.ts

@@ -0,0 +1,129 @@
+import { execSync } from 'child_process';
+
+/**
+ * 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,
+      },
+    );
+
+    // Extract the jest args from output
+    const match = result.match(/JEST_ARGS: (.*)/);
+    if (!match) return [];
+    return match[1].split(/\s+/).filter(Boolean);
+  };
+
+  // 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=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=main when THOROUGH is unset (run only changed)', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should pass --changedSince=main when THOROUGH=false', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'false' });
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should pass --changedSince=main when THOROUGH is empty string', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: '' });
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should not pass --changedSince=main when THOROUGH=true (run all tests)', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'true' });
+      expect(flags).not.toContain('--changedSince=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-toolchain/declarations/practices/tests-any/best-practice/src/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/best-practice/src/<star><star>/<star>.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

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

@@ -0,0 +1,134 @@
+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 + jest-expo deps at concrete versions', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        expect(pkg.devDependencies.typescript).toEqual('5.4.5');
+        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-toolchain/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-toolchain/declarations/practices/tests-expo/.test/assets/repo-expo-greenfield/package.json

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