declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/bestPracticeTemplateParse.declapract.integration.test.ts

@@ -0,0 +1,169 @@
+import { readFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import * as ts from 'typescript';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps that every `.ts`/`.tsx` TEMPLATE a practice ships parses as valid typescript,
+ *         and that no multi-line jsdoc inside one closes itself mid-line.
+ * .why  = a template is copied verbatim into a consumer repo, where it is real source that the
+ *         consumer's biome parses on every `pnpm fix`. a template that does not parse breaks
+ *         `pnpm fix` in EVERY adopter at once, and no adopter can repair it for itself —
+ *         `declapract apply` restores the shipped bytes (#613). this repo's own biome cannot
+ *         catch it: `biome.jsonc` excludes the practice provision tree because templates carry
+ *         `@declapract{}` syntax, so the templates are the one tree with no parse gate on it.
+ *         this clamp is that gate.
+ * .note = the hazard class is wider than any one line: ANY template may carry a glob or an arn
+ *         inside a block comment, and a `*` immediately before a `/` there terminates the comment
+ *         mid-prose. every character after it is read as code. that is how #613 shipped:
+ *         `persist-with-rds`'s `resources.parameters.ts` emitted 17 parse errors in every
+ *         adopter. so this clamps the CLASS (all templates), never the instance.
+ * .teeth = write an iam arn or a glob into any template's jsdoc with a literal `*` immediately
+ *          before a `/` — the shape #613 shipped in
+ *          `persist-with-rds/best-practice/provision/aws/resources.parameters.ts` — and BOTH
+ *          cases redden, with the offending path in the diff.
+ * .note = the two cases are separate nets over one defect class, deliberately. case1 (parse)
+ *         reads the property an adopter actually suffers. case2 (jsdoc shape) catches the
+ *         silent variant case1 cannot see: a comment that self-closes and whose prose tail
+ *         happens to parse as valid code, so the file is green and the note is corrupted.
+ * .note = scope excludes `*.declapract.*` basenames — those are declapract MACHINERY (check
+ *         declarations, unit clamps), never templates, and this repo's biome already parses
+ *         the `*.declapract.ts` declarations. `bad-practices/` is excluded by construction:
+ *         only `best-practice/` holds what ships.
+ * .note = this is an INTEGRATION test (`readdirSync` + `readFileSync` cross the filesystem
+ *         boundary, per `rule.forbid.unit.remote-boundaries`), and it lives at `src/` — not
+ *         under any practice — so declapract never walks it for emission (#583).
+ */
+
+// anchored on `__dirname` (this file sits at `src/`) rather than cwd, so a nested-scope jest run
+// cannot silently walk the wrong tree and assert on zero files (a vacuous green).
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+
+const isShippedTsTemplate = (path: string): boolean =>
+  /\.tsx?$/.test(path) &&
+  path.includes('/best-practice/') &&
+  !basename(path).includes('.declapract.');
+
+const asDiagnosticSite = (diagnostic: ts.Diagnostic): string => {
+  if (!diagnostic.file) return '';
+  if (diagnostic.start === undefined) return '';
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(
+    diagnostic.start,
+  );
+  return `:${line + 1}:${character + 1}`;
+};
+
+const asParseErrorLabel = (input: {
+  path: string;
+  diagnostic: ts.Diagnostic;
+}): string =>
+  [
+    relative(repoRoot, input.path),
+    asDiagnosticSite(input.diagnostic),
+    ' ',
+    ts.flattenDiagnosticMessageText(input.diagnostic.messageText, ' '),
+  ].join('');
+
+/**
+ * .what = every syntactic error typescript reports for one template's source.
+ * .why  = `transpileModule` runs the PARSER only — no type check, no module resolution — so a
+ *         template that references packages the consumer installs (but this repo does not) is
+ *         not a false red. the `@declapract{…}` placeholders sit inside string and template
+ *         literals in every ts template, so they parse as ordinary string content.
+ */
+const getAllParseErrors = (input: { path: string; source: string }): string[] =>
+  (
+    ts.transpileModule(input.source, {
+      fileName: input.path,
+      reportDiagnostics: true,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2020,
+        jsx: ts.JsxEmit.Preserve,
+      },
+    }).diagnostics ?? []
+  )
+    .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
+    .map((diagnostic) => asParseErrorLabel({ path: input.path, diagnostic }));
+
+const asLineNumber = (input: { source: string; at: number }): number =>
+  input.source.slice(0, input.at).split('\n').length;
+
+/**
+ * .what = every multi-line jsdoc in one template whose closing delimiter lands mid-line instead
+ *         of on a line of its own.
+ * .why  = the house jsdoc shape closes on its own line, always. a close anywhere else on a
+ *         multi-line block means the comment ended somewhere its author did not intend — which is
+ *         exactly what a glob or an arn in the prose does.
+ * .note = only a jsdoc that OPENS a line counts. the same opener sequence mid-line is almost
+ *         always a glob inside a string literal, and to read that as a comment would red on a
+ *         non-defect. a single-line jsdoc is left to the parse case, which sees its tail as code.
+ */
+const getAllJsdocSelfCloses = (input: {
+  path: string;
+  source: string;
+}): string[] =>
+  [...input.source.matchAll(/^[ \t]*\/\*\*/gm)].flatMap((opener) => {
+    const openAt = opener.index ?? 0;
+    // search from the final asterisk of the opener, so an empty block closes where it really does
+    const closeAt = input.source.indexOf('*/', openAt + opener[0].length - 1);
+    if (closeAt === -1) return []; // unterminated — the parse case owns that
+    const openLine = asLineNumber({ source: input.source, at: openAt });
+    const closeLine = asLineNumber({ source: input.source, at: closeAt });
+    if (openLine === closeLine) return []; // single-line jsdoc — the parse case owns it
+    const prefix = input.source.slice(
+      input.source.lastIndexOf('\n', closeAt) + 1,
+      closeAt,
+    );
+    if (/^[ \t]*$/.test(prefix)) return []; // the house shape: the delimiter alone on its line
+    return [
+      `${relative(repoRoot, input.path)}:${closeLine} jsdoc opened at line ${openLine} closes mid-line after «${prefix.trimStart()}»`,
+    ];
+  });
+
+describe('every shipped ts template parses as valid typescript (#613)', () => {
+  const templates = getAllPathsUnderDir({
+    dir: practicesDir,
+    skip: PRACTICE_TREE_SKIP_DIRS,
+  })
+    .filter(isShippedTsTemplate)
+    .sort();
+
+  const sources = templates.map((path) => ({
+    path,
+    source: readFileSync(path, 'utf8'),
+  }));
+
+  given('[case0] the src/practices best-practice tree', () => {
+    when('[t0] the ts templates are walked', () => {
+      // guards against a vacuous green: a walk that found zero files would pass both cases below
+      then('at least one shipped ts template is found', () => {
+        expect(templates.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  given('[case1] every shipped ts template', () => {
+    when('[t0] each is handed to the typescript parser', () => {
+      then('none reports a syntactic error', () => {
+        const offenders = sources.flatMap(getAllParseErrors);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] every multi-line jsdoc inside a shipped ts template', () => {
+    when('[t0] each block comment is located', () => {
+      then('none closes itself mid-line', () => {
+        const offenders = sources.flatMap(getAllJsdocSelfCloses);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+});

package/dist/parsePackageJSONAdoption.declapract.integration.test.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = a structural ratchet over every `package.json.declapract.ts` declaration: each one that
+ *         reads a consumer `package.json` off the `contents` arg must parse it through
+ *         `asPackageJSON`, not a raw `JSON.parse(contents)`. the ratchet holds the CURRENT
+ *         unconverted set to an allowlist, so the count only ever falls — a new declaration cannot
+ *         add a raw parse OF `contents` off the allowlist, and a converted one must drop from the
+ *         allowlist (D50 / #571).
+ * .bound = the ledger's teeth are keyed to the `contents` parameter name and to self-consistency
+ *          within ONE run. two gaps follow, both benign at today's instances and named here so the
+ *          claim above is not read wider than it holds: (1) a declaration that parses the consumer
+ *          `package.json` off a differently-named var is not matched — the ratchet reads the
+ *          `contents` arg, the canonical name for that arg in a `FileCheckFunction`/`FileFixFunction`
+ *          signature, so an off-name parse of the SAME input evades it (a `FileContentsFunction` that
+ *          parses config or its own template package.json, as `tests-service` does, is NOT this debt
+ *          — it never reads the consumer's package.json). (2) the compare is intra-run only: a diff
+ *          that adds a raw parse AND its allowlist row together passes, since there is no baseline
+ *          diff against `origin/main`. to widen either is a value-emitter change gated behind a
+ *          same-store/same-input discriminant (a differently-named parse of an unrelated input must
+ *          not false-positive) — a follow-on, not a claim this ledger makes today.
+ * .why  = a raw `JSON.parse(contents)` throws a context-free engine `SyntaxError` that names no
+ *         practice, no dependency, no file, and no remedy (see `asPackageJSON`). the verbal note
+ *         "route every parse through the util" decayed across three review rounds as a memory rather
+ *         than a test; a memory does not redden when a 27th declaration adds a raw parse. this turns
+ *         the note into a gate: the allowlist is the debt ledger, and it can only shrink.
+ * .note = this is an INTEGRATION test by the same rule its kin walks cite (`errors`, `domain`,
+ *         `actionPins`): it reads the filesystem — `readdirSync` over the practice tree,
+ *         `readFileSync` on every declaration — and `rule.forbid.unit.remote-boundaries` puts any
+ *         test that crosses that boundary in the integration suite. no credential, no network; the
+ *         boundary alone classifies it.
+ * .teeth = the "no NEW unconverted" case is the sharp one: it reddens the moment a fresh
+ *          `package.json.declapract.ts` raw-parses `contents` off the allowlist. the "no STALE
+ *          allowlist" case forces the ledger down — convert a declaration and its allowlist row must
+ *          go, or the test reddens.
+ */
+
+const PRACTICES_DIR = `${__dirname}/practices`;
+
+/**
+ * .what = the allowlist of `package.json.declapract.ts` declarations that still raw-parse `contents`
+ *         (paths relative to `src/practices`). this is the debt ledger; each row is a declaration
+ *         yet to route through `asPackageJSON`, and the ratchet forbids the ledger to grow.
+ */
+const ALLOWED_UNCONVERTED = [
+  'bottleneck/bad-practices/bottleneck/package.json.declapract.ts',
+  'config/bad-practices/old-config-with-paramstore-dep/package.json.declapract.ts',
+  'conventional-commits/bad-practices/commitlint/package.json.declapract.ts',
+  'dates-and-times/bad-practices/uni-time/package.json.declapract.ts',
+  'domain/bad-practices/simple-type-guards/package.json.declapract.ts',
+  'environments/bad-practices/old-dev-scripts/package.json.declapract.ts',
+  'errors/bad-practices/error-fns/package.json.declapract.ts',
+  'format/bad-practices/format-script/package.json.declapract.ts',
+  'format/bad-practices/prettier/package.json.declapract.ts',
+  'husky/bad-practices/postinstall/package.json.declapract.ts',
+  'lint/bad-practices/eslint/package.json.declapract.ts',
+  'lint/bad-practices/tslint/package.json.declapract.ts',
+  'logs/bad-practices/simple-log-methods/package.json.declapract.ts',
+  'node-service/bad-practices/license/package.json.declapract.ts',
+  'node-service/bad-practices/simple-lambda-client/package.json.declapract.ts',
+  'node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts',
+  'node/bad-practices/self-deps-not-link/package.json.declapract.ts',
+  'package-json-order/best-practice/package.json.declapract.ts',
+  'persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts',
+  'pnpm/bad-practices/npm-overrides/package.json.declapract.ts',
+  'runtime-schemas/bad-practices/joi/package.json.declapract.ts',
+  'serverless/bad-practices/old-sls-plugins/package.json.declapract.ts',
+  'tests-expo/bad-practices/inline-jest-config/package.json.declapract.ts',
+  'tests-node/bad-practices/deprecated-test-deps/package.json.declapract.ts',
+  'uuid/bad-practices/deps-file/package.json.declapract.ts',
+  'uuid/bad-practices/npm-uuidv4/package.json.declapract.ts',
+].sort();
+
+/**
+ * .what = whether a declaration's source text raw-parses `contents` WITHOUT a route through
+ *         `asPackageJSON` — i.e. it is unconverted debt on the ledger.
+ * .why  = a pure transformer leaf, named so the walk composer below reads intent rather than an
+ *         inline regex a reader must simulate to know what "unconverted" means. the `JSON.parse`
+ *         pattern matches `contents` ANYWHERE in the call args, not just as the exact first token —
+ *         so a trimmed or coalesced form (`JSON.parse(contents.trim())`, `JSON.parse(contents ??
+ *         '{}')`) cannot evade the ledger via a wrapped arg. the `asPackageJSON` guard is what
+ *         lets a converted declaration drop off the ledger.
+ */
+const isRawParseOfPackageJSON = (input: { source: string }): boolean =>
+  /JSON\.parse\([^)]*contents/.test(input.source) &&
+  !input.source.includes('asPackageJSON');
+
+/**
+ * .what = every `package.json.declapract.ts` declaration path under the practice tree, relative to
+ *         `src/practices`, that raw-parses `contents` without a route through `asPackageJSON`.
+ */
+const getUnconvertedRelPaths = (): string[] =>
+  getAllPathsUnderDir({ dir: PRACTICES_DIR, skip: PRACTICE_TREE_SKIP_DIRS })
+    .filter((path) => path.endsWith('package.json.declapract.ts'))
+    .filter((path) =>
+      isRawParseOfPackageJSON({ source: readFileSync(path, 'utf8') }),
+    )
+    .map((path) => relative(PRACTICES_DIR, path))
+    .sort();
+
+describe('asPackageJSON adoption — the raw-parse ratchet (D50 clamp)', () => {
+  given('[case1] the current unconverted declarations vs the allowlist', () => {
+    const scene = useBeforeAll(() => ({
+      unconverted: getUnconvertedRelPaths(),
+    }));
+
+    when('[t0] the unconverted set is compared to the ledger', () => {
+      then('no NEW declaration raw-parses off the allowlist', () => {
+        // teeth: add a 27th `package.json.declapract.ts` with a raw `JSON.parse(contents)` and its
+        // path lands here, off the allowlist, reddening this assertion.
+        const newUnconverted = scene.unconverted.filter(
+          (path) => !ALLOWED_UNCONVERTED.includes(path),
+        );
+        expect(newUnconverted).toEqual([]);
+      });
+
+      then('no allowlist row is stale — every entry still raw-parses', () => {
+        // teeth: route one allowlisted declaration through `asPackageJSON` and its allowlist row
+        // must go, or it surfaces here as a stale entry and reddens this assertion. the ledger can
+        // only shrink.
+        const staleAllowlist = ALLOWED_UNCONVERTED.filter(
+          (path) => !scene.unconverted.includes(path),
+        );
+        expect(staleAllowlist).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practiceTestFileLocation.declapract.integration.test.ts

@@ -0,0 +1,75 @@
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps that NO test artifact which declapract's compile would SHIP sits under a
+ *         `best-practice/` directory. compile strips `*.declapract.test.ts` (+ its `.snap`) before
+ *         it publishes a practice — so a UNIT clamp and its snapshot may collocate inside
+ *         `best-practice/`. it does NOT strip `*.declapract.integration.test.ts` (+ its `.snap`),
+ *         nor any other `__snapshots__/` file — those would ship, so they must live at the practice
+ *         ROOT (or another non-`best-practice/` home).
+ * .why  = declapract's emission classifier (getProjectCheckDeclaration) treats every file under
+ *         `best-practice/` that is not `.declapract.`-prefixed as a TEMPLATE to copy into the
+ *         consumer repo, and compile only removes the two `.declapract.test.ts` shapes. a shipped
+ *         `*.declapract.integration.test.ts` materializes at the consumer root as an EQUALS template
+ *         — it `import`s `declapract`/`test-fns` and reads fixtures that exist ONLY in this library,
+ *         so it fails jest load (ENOENT, or absent dev deps). found live on the app-protools-native
+ *         upgrade (#583). the compile-strip asymmetry is `ehmpathy/declapract#109`.
+ * .teeth = move a `*.declapract.integration.test.ts`, its `.snap`, or any other `__snapshots__/`
+ *          file under `best-practice/` and this clamp reddens, with the offender in the diff.
+ * .note = this lives at `src/` (not under any practice's `best-practice/`), so declapract never
+ *         walks it for emission — the same safe home as `src/actionPins.declapract.integration.test.ts`.
+ */
+
+// anchored on `__dirname` (this file sits at `src/`) rather than cwd, so the walk holds wherever
+// jest is invoked from — a nested-scope run or a CI checkout dir cannot silently scan the wrong
+// tree and assert on zero files (a vacuous green). same safe home as
+// `src/actionPins.declapract.integration.test.ts`.
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+
+const isTestArtifact = (path: string): boolean =>
+  path.endsWith('.declapract.test.ts') ||
+  path.endsWith('.declapract.integration.test.ts') ||
+  path.includes('/__snapshots__/');
+
+// compile strips ONLY these two shapes before it publishes a practice, so they never reach a
+// consumer even when they sit under `best-practice/` (a UNIT clamp + its snapshot).
+const isStrippedByCompile = (path: string): boolean =>
+  path.endsWith('.declapract.test.ts') ||
+  path.endsWith('.declapract.test.ts.snap');
+
+const isShippedTestArtifact = (path: string): boolean =>
+  isTestArtifact(path) && !isStrippedByCompile(path);
+
+const isUnderBestPractice = (path: string): boolean =>
+  path.includes('/best-practice/');
+
+describe('practice test files never sit under best-practice/ (#583)', () => {
+  const offenders = getAllPathsUnderDir({ dir: practicesDir, skip: null })
+    .filter(isUnderBestPractice)
+    .filter(isShippedTestArtifact)
+    .map((path) => relative(repoRoot, path))
+    .sort();
+
+  given('[case1] the src/practices tree', () => {
+    when('[t0] every path under a best-practice/ dir is scanned', () => {
+      then('no *.declapract.integration.test.ts ships into a template dir', () => {
+        const integrationTests = offenders.filter((path) =>
+          path.endsWith('.declapract.integration.test.ts'),
+        );
+        expect(integrationTests).toEqual([]);
+      });
+
+      then('no un-stripped __snapshots__/ file ships into a template dir', () => {
+        const snapshots = offenders.filter((path) =>
+          path.includes('/__snapshots__/'),
+        );
+        expect(snapshots).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practices/cache/.declapract.integration.test.ts

@@ -71,8 +71,8 @@ describe('cache practice with ifInstalled', () => {
         const packageJson = JSON.parse(
           await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
         );
-        // should have upgraded from 0.3.0 to 0.4.3
-        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+        // should have upgraded from 0.3.0 to the 0.5.1 floor
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.5.1');
       });
     });
   });
@@ -100,8 +100,8 @@ describe('cache practice with ifInstalled', () => {
         const packageJson = JSON.parse(
           await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
         );
-        // should still be 0.4.3 (unchanged, already valid)
-        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+        // should still be 0.5.1 (unchanged, already at the floor)
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.5.1');
       });
     });
   });

package/dist/practices/cache/.test/assets/repo-with-valid-cache-package/package.json

@@ -2,6 +2,6 @@
   "name": "test-project-valid-cache",
   "version": "1.0.0",
   "dependencies": {
-    "simple-in-memory-cache": "0.4.3"
+    "simple-in-memory-cache": "0.5.1"
   }
 }

package/dist/practices/cache/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
-    "simple-in-memory-cache": "@declapract{check.minVersion('0.4.3').ifInstalled()}",
-    "simple-on-disk-cache": "@declapract{check.minVersion('1.7.11').ifInstalled()}",
-    "with-simple-cache": "@declapract{check.minVersion('0.16.2').ifInstalled()}"
+    "simple-in-memory-cache": "@declapract{check.minVersion('0.5.1').ifInstalled()}",
+    "simple-on-disk-cache": "@declapract{check.minVersion('1.8.1').ifInstalled()}",
+    "with-simple-cache": "@declapract{check.minVersion('0.17.3').ifInstalled()}"
   }
 }

package/dist/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();