declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/tests-service/best-practice/.declapract.readme.md

@@ -0,0 +1,68 @@
+# tests-service
+
+the acceptance-test layer for a lambda service — blackbox tests that invoke a deployed (or local)
+lambda fleet through its real contract.
+
+## acceptance targets the contemp fleet
+
+a service that dual-publishes (see the `serverless` + `environments` practices) ships its fleet
+under BOTH slugs through the ancient→contemp transition: `-dev-` (ancient) and `-prep-`/`-prod-`
+(contemp) — the SAME artifact under two names. so its own acceptance suite proves ONE fleet, the
+contemp one: a run against contemp proves the deployed code, and the ancient slug is an alias for
+inbound callers still on the old name, never a second target for the self-acceptance gate.
+
+contemp is the service's own access-tier slug — `-prep-` at prep, `-prod-` at prod — so a single
+access-keyed run covers every tier the deploy job ships. there is no per-fleet fan-out and no
+per-tier skip.
+
+the reusable primitive lives in the `environments` practice, one procedure per file:
+`src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts` — `sdkAwsLambdaEnvAccessContemp()` emits the
+access direct (`-prep-` at prep, `-prod-` at prod). its ancient sibling
+`sdkAwsLambdaEnvAccessAncient()` (emits the `-dev-` slug below prod) serves OUTBOUND calls to
+unmigrated peers, not the self-acceptance suite.
+
+the composition atop that primitive is per-service (a service wraps `invokeLambdaForTesting` once,
+at a local seam, so the contemp-slug target lands in one place rather than at every call site):
+
+```ts
+// blackbox/lambdaTestMethods.ts — a per-service seam onto simple-lambda-testing-methods
+import { invokeLambdaForTesting as invokeLambdaForTestingRaw } from 'simple-lambda-testing-methods';
+import { sdkAwsLambdaEnvAccessContemp } from '../src/access/sdks/sdkAwsLambdaEnvAccessContemp';
+
+export const invokeLambdaForTesting: typeof invokeLambdaForTestingRaw = (input) =>
+  invokeLambdaForTestingRaw({ ...input, stage: sdkAwsLambdaEnvAccessContemp() });
+```
+
+each blackbox test imports `invokeLambdaForTesting` from that seam, and one package command runs the
+suite against the contemp fleet:
+
+```jsonc
+"test:acceptance": "set -eu && npm run test:acceptance:jest"
+```
+
+## why the seam is per-service, not a shipped template
+
+the seam is composition, not a primitive: a given service re-exports its own extra test operations
+through it (an apigateway-event builder, a graphql event builder), and its blackbox tree shape
+varies. so the practice ships the reusable primitive (the `EnvAccess` helper) and documents this
+composition, rather than a one-shape-fits-all seam file. lift the seam to a shipped template only
+once two or more services share the identical composition (`rule.prefer.wet-over-dry`).
+
+## the PR acceptance gate runs in-process; the deployed-fleet run is post-deploy
+
+the shared `.test.yml` PR gate (cicd-common) runs its acceptance shards IN-PROCESS (`LOCALLY=true`),
+because a PR has no deployed lambda to invoke. a service that publishes only dev/prep (no `test`
+fleet) would otherwise target `svc-<name>-test-*` — a slug that does not exist — and 404 on every
+call, so the PR gate would regress to all-404 the moment the suite is non-empty. the in-process
+default lets a fleetless service inherit a green PR gate out of the box, with no hand-patch. the
+acceptance run against a DEPLOYED fleet is a separate post-deploy grain (`.deploy-sls.yml`'s
+`assure` job), which invokes the real deployed lambda.
+
+## the CI acceptance gate runs contemp only
+
+`.deploy-sls.yml`'s `assure` job runs `ACCESS=${{ inputs.access }} npm run test:acceptance` ONCE —
+against the contemp fleet the same job just deployed. contemp maps to the deployed access at
+both prep and prod, so one run covers every tier this job ships. the ancient slug is proven by
+identity: dual-publish deploys the SAME artifact under the `-dev-` name, so a green contemp run is
+a green ancient run. the self-acceptance gate never invokes the ancient fleet — that slug exists
+for inbound callers still on the old name, an alias, never a second target to test.

package/dist/practices/tests-service/best-practice/blackbox/lambdas/<star>.acceptance.test.ts.declapract.ts

@@ -1,31 +1,56 @@
 import type { FileCheckFunction } from 'declapract';
-import expect from 'expect';
+import { ConstraintError } from 'helpful-errors';
 
-import { defineFunctionNameFromTestFileName } from '../../../defineFunctionNameFromTestFileName';
+import { asFunctionNameFromTestFileName } from '../../../asFunctionNameFromTestFileName';
 
 export const check: FileCheckFunction = (contents, context) => {
   if (!contents)
-    throw new Error('expected at least one lambda acceptance test');
+    throw new ConstraintError(
+      'expected at least one lambda acceptance test; add a `describe` block that invokes the lambda',
+      { relativeFilePath: context.relativeFilePath },
+    );
 
-  // check that each import was found
+  // check that each import was found.
+  // D52: this check no longer MANDATES `import { stage } from '.../environment'`. that line was
+  // break-by-conformance: it forced 88 blackbox files onto the legacy `dev`-slug axis to build a
+  // target fleet name no peer publishes below prod. a consumer may still import what it needs, but
+  // the practice must not require the exact token the north-star exists to retire. the fleet-
+  // name rewrite (dev↔prep) is the collapse-coupled half (D52b) and is out of this check.
+  //
+  // .note = the match below is literal, not semantic. it holds by construction on the file the
+  // practice itself stamps, but a consumer's own import-sorter may later wrap a line, merge it with
+  // a co-specifier import, or swap the quote style — any of which trips a cryptic `Expected imports`
+  // throw against a functionally-equivalent file. the literal match is deliberate (both lines dodge
+  // a typical print-width wrap), and a lenient regex/ast match is a tracked follow-on; this comment
+  // is the durable disclosure, so the brittleness is legible in-code, not only in the route yield
+  // (i015 r10 §3).
   const expectedImports = [
     "import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';",
-    "import { stage } from '../../src/utils/environment';",
     "import { locally } from '../environment';",
   ];
   const missedImports = expectedImports.filter(
     (expectedImport) => !contents.includes(expectedImport),
   );
   if (missedImports.length)
-    throw new Error(
+    throw new ConstraintError(
       `
 ${`- Expected imports ${['', ...expectedImports].join('\n  - ')}`}
       `.trim(),
+      { relativeFilePath: context.relativeFilePath, missedImports },
     );
 
-  const expectedTestName = defineFunctionNameFromTestFileName({ context });
+  const expectedTestName = asFunctionNameFromTestFileName({
+    relativeFilePath: context.relativeFilePath,
+  });
   const expectedDescribe = `
 describe('${expectedTestName}', () => {
   `.trim();
-  expect(contents).toContain(expectedDescribe);
+  // route the describe-name mismatch through a ConstraintError, same as the paths above —
+  // a bare `expect(...).toContain(...)` throws jest's raw ANSI+middle-dot diff, which snapshots
+  // as terminal noise (rule.forbid.snapshot-visual-blemishes). name the derived describe plainly.
+  if (!contents.includes(expectedDescribe))
+    throw new ConstraintError(
+      `expected a \`describe\` block that names the derived function: ${expectedDescribe}`,
+      { relativeFilePath: context.relativeFilePath, expectedTestName },
+    );
 };

package/dist/practices/tests-service/best-practice/package.json

@@ -1,5 +1,8 @@
 {
   "devDependencies": {
-    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.4.2')}"
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  },
+  "scripts": {
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
   }
 }

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

@@ -1,3 +1,101 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { existsSync } from 'node:fs';
+import { readFile } from '../../../utils/readFile';
+
+/**
+ * .what = declare the tests-service package.json, with the `start:livedb:prep` wake command
+ *         included only when this service REACHES the shared aurora-serverless cluster —
+ *         signalled by a `database.tunnel` block in its own `config/prep.json`.
+ * .why  = the cicd-common test workflow already runs `npm run start:livedb:prep --if-present`
+ *         in both the integration + acceptance shards, but the command lived ONLY in
+ *         persist-with-rds — so a gateway/fan-out service (owns no db, but invokes peers that
+ *         query the shared cluster) never got it, the `--if-present` step no-op'd, and the
+ *         min-capacity-0 prep cluster was never woken in ci (#598). tests-service covers the
+ *         whole lambda-service set (gateways AND rds services), so it is the common-denominator
+ *         home for the wake. but a lambda-service that reaches NO cluster (no tunnel) must NOT
+ *         get it — else its `--if-present` step would fire `rhx use.rds.capacity` against a
+ *         cluster it does not use and could FAIL the job (the step has no swallow). so the emit
+ *         is self-gated on the tunnel: the same signal `useWakeOfLivedb` uses locally.
+ * .note = the discriminant is the CONSUMER's `config/prep.json`, not `context.projectPractices` —
+ *         a gateway declares its tunnel in config, not via a db-ownership practice. so this reads
+ *         the neighbor file via `getProjectRootDirectory()`, the check-context escape hatch.
+ * .note = persist-with-rds ALSO declares this command; both emit the IDENTICAL line, so an rds
+ *         service converges on one entry (the multi-declarer convergence pattern, as with the
+ *         repo-root .gitignore). additive by design — this does not touch persist-with-rds.
+ */
+
+/**
+ * .what = read whether the consumer declares a db tunnel in its config/<env>.json.
+ * .why  = the tunnel is the signal a service reaches the shared cluster (owns the db, or invokes
+ *         peers that query it). names the neighbor-read as one intent rather than an inline
+ *         positional decode (rule.forbid.inline-decode-friction).
+ * .note = an ABSENT config is benign — a service that declares no config/<env>.json reaches no
+ *         known cluster, so it returns false and gets no wake command (a false-negative just omits
+ *         a latency nicety, never breaks a suite; contrast the RUNTIME useWakeOfLivedb, likewise soft
+ *         on absence). but a PRESENT-yet-unparseable config is NOT benign: it means the consumer
+ *         authored a config the build cannot read, so a silent `return false` would conflate a
+ *         broken config with an absent tunnel (`rule.forbid.failhide`). so absence returns false
+ *         and a parse failure rethrows with context, naming the file to repair.
+ */
+const readReachesSharedCluster = async (input: {
+  projectRoot: string;
+  env: 'prep';
+}): Promise<boolean> => {
+  const configPath = `${input.projectRoot}/config/${input.env}.json`;
+  if (!existsSync(configPath)) return false; // no config = no known cluster (benign)
+  const raw = await readFile({ filePath: configPath });
+  try {
+    return !!JSON.parse(raw)?.database?.tunnel;
+  } catch (cause) {
+    // a non-Error throw is unexpected here; rethrow it verbatim rather than reclassify it
+    if (!(cause instanceof Error)) throw cause;
+    // a config the consumer authored but the build cannot parse is a real defect, not "no
+    // cluster" — a caller-must-fix condition, so throw a ConstraintError (exit 2) that NAMES the
+    // file, to match asPackageJSON's own class for the identical malformed-JSON case, so a
+    // consumer can machine-distinguish "my config is broken" from a server malfunction (never a
+    // silent false — `rule.forbid.failhide` / `rule.require.exit-code-semantics`)
+    throw new ConstraintError(
+      `tests-service: could not parse ${configPath} as JSON — fix the malformed config so the wake-command gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = return the package.json without the `start:livedb:prep` wake command; a `scripts` block
+ *         the strip leaves empty is removed too.
+ * .why  = names the tunnel-gated strip as one intent, so `contents` reads what-not-how rather than
+ *         an inline mutate-then-count-then-delete sequence a reader must simulate
+ *         (`rule.forbid.inline-decode-friction`). pure over a fresh clone of `pkg`, so the caller's
+ *         object is untouched and the leaf is independently testable.
+ */
+const withoutWakeCommand = (input: {
+  pkg: Record<string, any>;
+}): Record<string, any> => {
+  const pkg = { ...input.pkg, scripts: { ...input.pkg.scripts } };
+  delete pkg.scripts['start:livedb:prep'];
+  if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts;
+  return pkg;
+};
+
+export const contents: FileContentsFunction = async (context) => {
+  // the superset: the package.json with the wake command included
+  const superset = JSON.parse(
+    await readFile({ filePath: `${__dirname}/package.json` }),
+  );
+
+  // keep the wake command when this service reaches the shared cluster; strip it otherwise
+  const reachesSharedCluster = await readReachesSharedCluster({
+    projectRoot: context.getProjectRootDirectory(),
+    env: 'prep',
+  });
+  const emitted = reachesSharedCluster
+    ? superset
+    : withoutWakeCommand({ pkg: superset });
+
+  return `${JSON.stringify(emitted, null, 2)}\n`;
+};
 
 export const check = FileCheckType.CONTAINS;

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

@@ -0,0 +1,204 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, getError, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = end-to-end proof of the #598 wake-command gate, run through the REAL declapract apply
+ *   pipeline against a genTempDir consumer. per `rule.require.declapract-integration-tests`, a
+ *   `contents` fn that READS A NEIGHBOR FILE (here, the consumer's config/prep.json) is REQUIRED to
+ *   carry a pipeline test — a unit test of the exported `contents` never exercises the glob→file
+ *   match, the `getProjectRootDirectory()` resolution against the real consumer root, nor the
+ *   emitted package.json a consumer actually receives.
+ * .why = the declaration emits `start:livedb:prep` only when the consumer declares a db tunnel in
+ *   its own config/prep.json (the signal it REACHES the shared aurora-serverless cluster — owns the
+ *   db, or invokes peers that query it). only a real apply proves declapract (1) matches the
+ *   declaration to `package.json`, (2) reads the neighbor config via `getProjectRootDirectory()`,
+ *   (3) EMITS the wake command for a tunnel consumer, and (4) STRIPS it for a no-tunnel one — so a
+ *   pure-compute lambda's cicd `start:livedb:prep --if-present` step stays a no-op rather than fires
+ *   `rhx use.rds.capacity` against a cluster it does not use (which, with no swallow in the step,
+ *   could fail the job). that is the exact #598 end-state the gate delivers.
+ * .note = the apply is scoped by `file` ONLY, never by `practice` — a file-only apply keeps every
+ *   usecase practice in `projectPractices` while it applies just the package.json plan (per the
+ *   cicd-service provision.yml exemplar). the fixture symlinks a lean `declarations/` MIRROR that
+ *   carries only tests-service, so a file-only apply compiles 1 practice, not the real tree's ~40.
+ * .note = the CONSUMER config/prep.json is WRITTEN into the tempDir per case (not a fixture file),
+ *   so the same base fixture drives both branches — the test owns the discriminant the gate reads.
+ * .note = the emitted package.json is snapshotted in full (both branches), per the rule.
+ */
+
+const FIXTURE = './src/practices/tests-service/.test/assets/demo-repo-service';
+const DECLARATIONS_MIRROR = './src/.test/assets/tests-service/declarations';
+const WAKE_COMMAND = 'rhx use.rds.capacity --env prep';
+
+const TUNNEL_CONFIG = {
+  environment: { access: 'prep' },
+  database: {
+    tunnel: {
+      bastion: 'vpc-main-bastion',
+      lambda: { host: 'cluster.prep.example.com', port: 5432 },
+    },
+  },
+};
+const NO_TUNNEL_CONFIG = {
+  environment: { access: 'prep' },
+};
+
+describe('tests-service package.json — the #598 wake-command gate, end to end', () => {
+  given('[case1] a consumer that reaches the shared cluster (tunnel declared)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-tunnel',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer declares a db tunnel — the signal it reaches the shared cluster
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        `${JSON.stringify(TUNNEL_CONFIG, null, 2)}\n`,
+      );
+      await applyPackageJson();
+      const after1 = await read('package.json');
+      await applyPackageJson(); // second apply — prove a fixed point
+      const after2 = await read('package.json');
+      return { after1, after2 };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the emitted package.json holds the wake command', () => {
+        const pkg = JSON.parse(state.after1);
+        expect(pkg.scripts?.['start:livedb:prep']).toEqual(WAKE_COMMAND);
+      });
+
+      then('the emitted package.json matches snapshot', () => {
+        expect(state.after1).toMatchSnapshot(
+          'package.json — tunnel consumer (wake command emitted)',
+        );
+      });
+    });
+
+    when('[t1] the declaration is applied a second time', () => {
+      // idempotency is scoped to THIS fix's output — the scripts block. the devDependency's
+      // `@declapract{check.minVersion(...)}` token resolves to a concrete version across the two
+      // applies (a declapract minVersion-on-absent-dep behavior shared by every package.json
+      // practice, not introduced by #598), so a whole-file equality would assert a property
+      // declapract does not provide. the wake command this fix emits IS a fixed point.
+      then('the emitted scripts block is a fixed point (idempotent)', () => {
+        expect(JSON.parse(state.after2).scripts).toEqual(
+          JSON.parse(state.after1).scripts,
+        );
+      });
+    });
+  });
+
+  given('[case2] a consumer that reaches NO cluster (no tunnel declared)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-notunnel',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer declares NO db tunnel — a pure-compute lambda that reaches no cluster
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        `${JSON.stringify(NO_TUNNEL_CONFIG, null, 2)}\n`,
+      );
+      await applyPackageJson();
+      const after1 = await read('package.json');
+      await applyPackageJson(); // second apply — prove a fixed point
+      const after2 = await read('package.json');
+      return { after1, after2 };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the emitted package.json STRIPS the wake command', () => {
+        const pkg = JSON.parse(state.after1);
+        expect(pkg.scripts?.['start:livedb:prep']).toBeUndefined();
+      });
+
+      then('the emitted package.json matches snapshot (the stripped shape)', () => {
+        expect(state.after1).toMatchSnapshot(
+          'package.json — no-tunnel consumer (wake command stripped)',
+        );
+      });
+    });
+
+    when('[t1] the declaration is applied a second time', () => {
+      // scoped to this fix's output (see [case1] [t1] note); the strip is a fixed point — the
+      // wake command stays absent across applies.
+      then('the emitted scripts block stays absent (idempotent)', () => {
+        expect(JSON.parse(state.after2).scripts).toEqual(
+          JSON.parse(state.after1).scripts,
+        );
+      });
+    });
+  });
+
+  given('[case3] a consumer whose config/prep.json is present but unparseable', () => {
+    // the failhide clamp (r6 n2): a PRESENT-yet-broken config must FAIL LOUD, never be conflated
+    // with a no-tunnel consumer. teeth: with the old `catch { return false }`, this apply RESOLVED
+    // and stripped the wake command (a malformed config read as "no cluster"); with the rethrow,
+    // the apply REJECTS and names the file. revert the try/catch to a silent false and this reddens.
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-broken',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer wrote a config the build cannot parse (a real defect, not "no cluster")
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        '{ "database": { "tunnel": ', // truncated JSON — a real author defect
+      );
+      const error = await getError(applyPackageJson());
+      return { error };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the apply FAILS LOUD, and names the malformed config to fix', () => {
+        expect(state.error).toBeDefined();
+        expect(state.error.message).toContain('could not parse');
+        expect(state.error.message).toContain('config/prep.json');
+      });
+    });
+  });
+});

package/dist/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/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/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-migration/declarations/practices/typescript-expo/best-practice → 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/practices/typescript-node/best-practice/package.json.declapract.ts

@@ -11,7 +11,9 @@ import { readFile } from '../../../utils/readFile';
  */
 export const contents: FileContentsFunction = async (context) => {
   // grab the superset of best practices content
-  const contentsSuperset = await readFile(`${__dirname}/package.json`);
+  const contentsSuperset = await readFile({
+    filePath: `${__dirname}/package.json`,
+  });
 
   // remove the artifact-build clause when the artifact practice is absent — immutable const, no reassign
   const contents = context.projectPractices.includes('artifact')

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

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "uuid-fns": "@declapract{check.minVersion('1.0.2')}"
+    "uuid-fns": "@declapract{check.minVersion('1.1.3')}"
   }
 }