declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -1,16 +1,193 @@
-import { FileCheckType } from 'declapract';
+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`.
- * .why  = an expo app's tests must transform react-native + expo ESM through
- *         babel-preset-expo (metro's transform), which jest-expo wires up. these deps
- *         track the installed expo SDK major (jest-expo 54 pairs with expo 54), so the
- *         floors are minima, not pins — a repo on a newer SDK bumps them.
- *
- * .caveat = these versions are SDK-coupled and un-validatable without a live expo repo;
- *           the emit is proven at the declapract-emit bar (the integration test), the
- *           live jest-expo run is proven against a real expo repo per the wisher's
- *           accepted validation bar for this fork.
+ * .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.
  */
-export const check = FileCheckType.CONTAINS;
+
+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/.test/assets/expo-fullusecase/declarations/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/.test/assets/expo-fullusecase/declarations/practices/typescript-expo/__snapshots__/package.json.declapract.integration.test.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`typescript-expo package.json the emitted build commands match snapshot: typescript-expo build commands 1`] = `
+{
+  "build": "npm run build:web",
+  "build:web": "npx expo export --platform web",
+}
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/typescript-expo/__snapshots__/tsconfig.json.declapract.integration.test.ts.snap

@@ -0,0 +1,19 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`typescript-expo tsconfig.json the emitted tsconfig template matches snapshot: typescript-expo tsconfig.json 1`] = `
+"{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"],
+      "@assets/*": ["assets/*"]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/typescript-expo/{best-practice/package.json.declapract.integration.test.ts → package.json.declapract.integration.test.ts}

@@ -2,7 +2,7 @@ import { FileCheckType } from 'declapract';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { check } from './package.json.declapract';
+import { check } from './best-practice/package.json.declapract';
 
 /**
  * .why integration = the build-command assertions read the shipped `package.json` template
@@ -19,7 +19,7 @@ describe('typescript-expo package.json', () => {
 
   it('the emitted build command uses metro/EAS (expo export), not tsc', () => {
     const template = JSON.parse(
-      readFileSync(path.join(__dirname, 'package.json'), 'utf-8'),
+      readFileSync(path.join(__dirname, 'best-practice/package.json'), 'utf-8'),
     );
     // `build` aliases build:web so the shared cicd `npm run build` works on expo
     expect(template.scripts.build).toEqual('npm run build:web');
@@ -27,4 +27,17 @@ describe('typescript-expo package.json', () => {
     expect(template.scripts['build:web']).toContain('expo export --platform web');
     expect(template.scripts.build).not.toContain('tsc');
   });
+
+  it('the emitted build commands match snapshot', () => {
+    // snapshot the governed build commands themselves, so a reshaped command that keeps the
+    // pinned tokens green (a reordered flag, a rephrased alias) reddens a vibecheck in review
+    // (rule.require.contract-snapshot-exhaustiveness)
+    const template = JSON.parse(
+      readFileSync(path.join(__dirname, 'best-practice/package.json'), 'utf-8'),
+    );
+    expect({
+      build: template.scripts.build,
+      'build:web': template.scripts['build:web'],
+    }).toMatchSnapshot('typescript-expo build commands');
+  });
 });

package/dist/.test/assets/{expo-toolchain/declarations/practices/typescript-expo/best-practice → expo-fullusecase/declarations/practices/typescript-expo}/tsconfig.json.declapract.integration.test.ts

@@ -2,7 +2,7 @@ import { FileCheckType } from 'declapract';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { check } from './tsconfig.json.declapract';
+import { check } from './best-practice/tsconfig.json.declapract';
 
 /**
  * .why integration = the template-content assertions read the shipped `tsconfig.json`
@@ -19,7 +19,7 @@ describe('typescript-expo tsconfig.json', () => {
 
   it('the emitted template is expo-shaped, not node', () => {
     const template = JSON.parse(
-      readFileSync(path.join(__dirname, 'tsconfig.json'), 'utf-8'),
+      readFileSync(path.join(__dirname, 'best-practice/tsconfig.json'), 'utf-8'),
     );
     // extends the expo base (jsx + react-native resolution), NOT @tsconfig/node20
     expect(template.extends).toEqual('expo/tsconfig.base');
@@ -29,4 +29,15 @@ describe('typescript-expo tsconfig.json', () => {
     // tsx is included (a react-native app has jsx), unlike the node tsconfig
     expect(template.include).toContain('**/*.tsx');
   });
+
+  it('the emitted tsconfig template matches snapshot', () => {
+    // snapshot the whole shipped template, so a reshape that keeps the pinned tokens green
+    // (a reordered path alias, a rephrased extends) reddens a vibecheck in review
+    // (rule.require.contract-snapshot-exhaustiveness)
+    const template = readFileSync(
+      path.join(__dirname, 'best-practice/tsconfig.json'),
+      'utf-8',
+    );
+    expect(template).toMatchSnapshot('typescript-expo tsconfig.json');
+  });
 });

package/dist/.test/assets/expo-migration/declarations/practices/cicd-app-react-native-expo/.declapract.integration.test.ts

@@ -171,16 +171,17 @@ describe('app-react-native-expo — graceful migration of an app-protools-shaped
       });
 
       then('the packageManager pin converges to the blessed exact version', () => {
-        // the fixture is AHEAD of the blessed pin (pnpm@10.32.1). the pnpm
-        // best-practice CONTAINS declares the ONE blessed version (pnpm@10.31.7),
-        // so a consumer ahead of it is pinned BACK on fix — that downgrade is the
-        // wisher-settled org-convergence REQUIREMENT (one blessed pnpm across CI,
-        // local, every repo), not a regression. this characterizes it.
+        // the fixture is OFF the blessed pin (pnpm@10.32.1). the pnpm
+        // best-practice CONTAINS declares the ONE blessed version (pnpm@10.34.5),
+        // so a consumer off it is converged onto the blessed pin on fix — in
+        // either direction. that convergence-to-one-version is the wisher-settled
+        // org-convergence REQUIREMENT (one blessed pnpm across CI, local, every
+        // repo), not a regression. this characterizes it.
         const pkgBefore = JSON.parse(state.before.pkg!);
         expect(pkgBefore.packageManager).toEqual('pnpm@10.32.1');
 
         const pkg = JSON.parse(state.after2.pkg!);
-        expect(pkg.packageManager).toEqual('pnpm@10.31.7');
+        expect(pkg.packageManager).toEqual('pnpm@10.34.5');
       });
 
       then('the inline jest dual-source block is dropped', () => {
@@ -389,6 +390,20 @@ describe('app-react-native-expo — migration-fixture drift guard', () => {
     return parsed['use-cases'][input.usecase].practices;
   };
 
+  // the practices in `of` absent from `reference` — the set-difference the drift asserts on.
+  const getPracticesAbsentFrom = (input: {
+    of: string[];
+    reference: string[];
+  }): string[] =>
+    input.of.filter((practice) => !input.reference.includes(practice));
+
+  // the practices in `of` also present in `reference` — the set-overlap the drift forbids.
+  const getPracticesPresentIn = (input: {
+    of: string[];
+    reference: string[];
+  }): string[] =>
+    input.of.filter((practice) => input.reference.includes(practice));
+
   const repoRoot = path.join(__dirname, '../../..');
 
   given('the real usecase and the fixture usecase', () => {
@@ -410,34 +425,34 @@ describe('app-react-native-expo — migration-fixture drift guard', () => {
 
     when('the fixture subset is measured against the real usecase', () => {
       then('the fixture invents no practice absent from the real usecase', () => {
-        const invented = fixturePractices.filter(
-          (practice) => !realPractices.includes(practice),
-        );
+        const invented = getPracticesAbsentFrom({
+          of: fixturePractices,
+          reference: realPractices,
+        });
         expect(invented).toEqual([]);
       });
 
       then('a fixture practice is never also on the config-only allowlist', () => {
-        const overlap = fixturePractices.filter((practice) =>
-          configOnlyAllowlist.includes(practice),
-        );
+        const overlap = getPracticesPresentIn({
+          of: fixturePractices,
+          reference: configOnlyAllowlist,
+        });
         expect(overlap).toEqual([]);
       });
 
       then('the allowlist names no practice absent from the real usecase', () => {
-        const dead = configOnlyAllowlist.filter(
-          (practice) => !realPractices.includes(practice),
-        );
+        const dead = getPracticesAbsentFrom({
+          of: configOnlyAllowlist,
+          reference: realPractices,
+        });
         expect(dead).toEqual([]);
       });
 
       then('every real usecase practice is classified — exercised or config-only', () => {
-        const classified = new Set([
-          ...fixturePractices,
-          ...configOnlyAllowlist,
-        ]);
-        const unclassified = realPractices.filter(
-          (practice) => !classified.has(practice),
-        );
+        const unclassified = getPracticesAbsentFrom({
+          of: realPractices,
+          reference: [...fixturePractices, ...configOnlyAllowlist],
+        });
         expect(unclassified).toEqual([]);
       });
     });
@@ -662,6 +677,91 @@ describe('useCases.yml — resolved-practice characterization', () => {
  * .note = a practice-set parity guard below pins this fixture's usecase === the real
  *         `src/useCases.yml` usecase, so the smoke can never silently test a stale set.
  */
+/**
+ * .what = a clamp on the expo `deploy.yml` prod job's `if:` test-gate precedence — the prod
+ *         job must bind the `needs.test` gate to EVERY trigger branch, so a `v*` tag push
+ *         cannot deploy to prod on a FAILED test.
+ * .why  = github-actions `&&` binds tighter than `||`, so an `if:` written
+ *         `(tag) || (access==prod) && always() && (test ok)` parses as `tag || (access &&
+ *         always && test)` — the test gate binds ONLY to the access branch, so a `v*` TAG
+ *         PUSH deploys to prod even when `test` FAILED. the correct shape wraps both trigger
+ *         branches in one OUTER group the gate applies to:
+ *         `((tag) || access==prod) && always() && (test ok)`. this is the silent-break class
+ *         the wish fights — an untested build reaches prod, every gate green. the clamp reads
+ *         the raw prod `if:` and reddens on the un-grouped (bug) shape. it mirrors the
+ *         cicd-service prod-gate clamp so both service and app deploy callers hold the guard.
+ * .note = a filesystem walk → integration suite per rule.forbid.unit.remote-boundaries; no
+ *         credential, no network — the boundary alone classifies it. the clamp lives at the
+ *         practice root, never under best-practice/, so it is a declaration and not a template.
+ */
+/**
+ * .what = whether the prod job's collapsed `if:` wraps BOTH trigger branches in ONE outer group
+ *         that the ` && always()` test-gate binds over — the correct precedence.
+ * .why  = a pure transformer leaf, named so the assertion below reads intent rather than a raw
+ *         precedence regex a reader must simulate. the buggy single-group shape opens one paren
+ *         `(startsWith`; the correct shape opens a second, OUTER paren `((startsWith` that the
+ *         ` && always()` gate closes over, so the gate binds to the tag-push branch too, not the
+ *         access branch alone.
+ */
+const isProdGateGroupedCorrectly = (input: { collapsedIf: string }): boolean =>
+  /\(\(startsWith\(github\.ref, 'refs\/tags\/'\).*\|\| github\.event\.inputs\.access == 'prod'\) &&\s*always\(\)/.test(
+    input.collapsedIf,
+  );
+
+describe('cicd-app-react-native-expo — prod test-gate precedence (silent-break clamp)', () => {
+  const readProdIf = (): string => {
+    const text = readFileSync(
+      `${__dirname}/best-practice/.github/workflows/deploy.yml`,
+      'utf-8',
+    );
+    // yaml.parse already returns `any`; annotate (not cast) to read the untyped workflow doc, as
+    // the peer cicd-service clamp does with its `parsed: any` annotation (no rule.forbid.as-cast cast)
+    const parsed: any = yaml.parse(text);
+    return (parsed.jobs?.prod?.if ?? '').replace(/\s+/g, ' ').trim();
+  };
+
+  given('[case1] the expo deploy.yml prod job', () => {
+    when('[t0] the prod job gates on the test result across every trigger branch', () => {
+      then('the two trigger branches sit in one outer group the test-gate binds to', () => {
+        const collapsed = readProdIf();
+        // guard the shape: an absent `if` leaves collapsed empty, a clean red not a crash
+        expect(collapsed.length).toBeGreaterThan(0);
+        // teeth: revert the outer paren and isProdGateGroupedCorrectly reddens.
+        expect(isProdGateGroupedCorrectly({ collapsedIf: collapsed })).toEqual(
+          true,
+        );
+      });
+
+      then('the buggy per-branch group (access alone in parens after `||`) is absent', () => {
+        // teeth: the precedence bug wraps the access branch in its OWN parens after the `||`
+        // (`|| (github.event.inputs.access == 'prod') &&`), which lets the tag branch stand alone.
+        // the correct shape leaves the access branch bare inside the outer group.
+        expect(readProdIf()).not.toContain(
+          "|| (github.event.inputs.access == 'prod') &&",
+        );
+      });
+
+      then('the test-result gate itself is present (guards the above from vacuity)', () => {
+        expect(readProdIf()).toContain(
+          "always() && (needs.test.result == 'success' || needs.test.result == 'skipped')",
+        );
+      });
+    });
+
+    when('[t1] the emitted prod-job gate is snapshotted for review', () => {
+      // the regex + toContain clamps above prove the SHAPE; this snapshots the emitted
+      // `if:` gate itself so a reviewer vibechecks the actual precedence group, and any
+      // drift (a reword, an operand reshuffle, a lost outer paren) shows as a diff. per
+      // rule.require.contract-snapshot-exhaustiveness, and mirrors the peer cicd-service clamp.
+      then('the prod job `if:` gate matches snapshot', () => {
+        expect(readProdIf()).toMatchSnapshot(
+          'deploy.yml prod job if: (test-gate precedence)',
+        );
+      });
+    });
+  });
+});
+
 describe('app-react-native-expo — full-usecase evaluation smoke', () => {
   const repoRoot = path.join(__dirname, '../../..');
   const sorted = (input: string[]): string[] => [...input].sort();