declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/prod-deps/.declapract.readme.md

@@ -0,0 +1,55 @@
+# rhachet prod-deps bad practice
+
+## what
+
+detects `rhachet` and `rhachet-roles-*` packages listed as production dependencies and moves them to devDependencies.
+
+## why
+
+rhachet packages are build-time / development tooling only. they should never be shipped as production dependencies because:
+
+1. **no runtime usage** — rhachet is used for agent role management, skill linking, and development workflows. none of this runs at runtime in production.
+
+2. **bloated bundles** — including rhachet in prod deps unnecessarily inflates `node_modules` for deployed applications.
+
+3. **dependency hygiene** — packages that are only used during development belong in `devDependencies`. at worst, if downstream packages need them, they should be declared as `peerDependencies`.
+
+## packages covered
+
+- `rhachet`
+- `rhachet-roles-*` (e.g., `rhachet-roles-ehmpathy`, `rhachet-roles-bhrain`, `rhachet-roles-bhuild`)
+
+## fix
+
+moves all matching packages from `dependencies` to `devDependencies`, preserving their versions.
+
+## correct placement
+
+```json
+{
+  "devDependencies": {
+    "rhachet": "^1.19.0",
+    "rhachet-roles-ehmpathy": "^1.15.0"
+  }
+}
+```
+
+or, if downstream packages need to use them:
+
+```json
+{
+  "peerDependencies": {
+    "rhachet": ">=1.0.0"
+  }
+}
+```
+
+never:
+
+```json
+{
+  "dependencies": {
+    "rhachet": "^1.19.0"
+  }
+}
+```

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/prod-deps/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "rhachet": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/prod-deps/package.json.declapract.ts

@@ -0,0 +1,47 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects rhachet and rhachet-roles-* packages in production dependencies
+ * .why = these packages should be devDependencies or peerDependencies, never direct prod deps
+ */
+
+const rhachetPackagePattern = /^rhachet(-roles-.*)?$/;
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('does not match bad practice');
+
+  const packageJSON = JSON.parse(contents);
+  const prodDeps = Object.keys(packageJSON.dependencies ?? {});
+
+  // check if any rhachet package is in prod dependencies
+  const rhachetInProdDeps = prodDeps.some((dep) =>
+    rhachetPackagePattern.test(dep),
+  );
+
+  if (rhachetInProdDeps) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = JSON.parse(contents);
+  const prodDeps = { ...packageJSON.dependencies };
+  const devDeps = { ...packageJSON.devDependencies };
+
+  // find all rhachet packages in prod deps and move them to dev deps
+  for (const dep of Object.keys(prodDeps)) {
+    if (rhachetPackagePattern.test(dep)) {
+      devDeps[dep] = prodDeps[dep];
+      delete prodDeps[dep];
+    }
+  }
+
+  const fixedPackageJSON = {
+    ...packageJSON,
+    dependencies: Object.keys(prodDeps).length > 0 ? prodDeps : undefined,
+    devDependencies: Object.keys(devDeps).length > 0 ? devDeps : undefined,
+  };
+
+  return { contents: JSON.stringify(fixedPackageJSON, null, 2) };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/<star><star>/<star>peer-review<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the old flat shape, where peer-review files sit directly in
+ *         .reviews with `peer-review` in the filename
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/peer/<star><star>/<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews/peer
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the new shape, where all peer-review files live under a
+ *         dedicated `peer` directory
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.declapract.readme.md

@@ -0,0 +1,12 @@
+peer review artifacts should not be committed to git
+
+these files live under `.behavior/**/.reviews/` and capture peer-review feedback
+from the behavior build lifecycle. they are noise for the most part — far less
+important than the root behavior files themselves.
+
+two path shapes are removed:
+
+- old (flat): `.behavior/**/.reviews/**/*peer-review*.md`
+- new (peer dir): `.behavior/**/.reviews/peer/**/*.md`
+
+self-reviews and other non-peer artifacts under `.reviews/` are intentionally left alone.

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.agent/keyrack.yml.declapract.ts

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

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.declapract.readme.md

@@ -0,0 +1,32 @@
+rhachet boots roles, and role boots write scratch state into `.agent/.cache/`
+
+so this practice declares the gitignore line for that dir — the practice that creates the scratch
+declares its ignore, rather than a neighbor practice a repo may not have taken.
+
+📖 several practices declare this same `.gitignore`. the contract they share — one shared
+algorithm, the ordered tail, what a new declarer owes — is stated once at
+`.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitignore.md`. read that before you add
+a line here.
+
+## it declares only `.agent/.cache/`, not `.cache/`
+
+`.cache/` is generic tool scratch and belongs to the `git` practice. a practice declares the
+ignore for the dirs it creates.
+
+⚠️ **"rhachet owns it" does not mean "git should drop it".** the `git` practice declares
+`.agent/.cache/` too, and that line stays: `app-react-native-expo` (`src/useCases.yml`) takes
+`git` **without** `rhachet`, so for those repos git's line is the only explicit source of the
+ignore.
+
+## the end-to-end proof lives under the git practice
+
+`src/practices/git/.declapract.integration.test.ts` → `[case2] a repo whose use case has rhachet
+but NOT git`.
+
+that is the scenario which justifies this declaration at all. it clones a demo repo whose use case
+omits `git`, applies **this** practice alone, and asserts the agent cache path is ignored with no
+help from git, that `.cache/` is correctly absent, that the negation is honored by git itself, and
+that a re-apply changes zero bytes.
+
+it sits there because one temp repo must hold both declarations to prove they agree. this pointer
+exists so a reader in `src/practices/rhachet/` can find it.

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -0,0 +1,64 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGitignoreContents';
+
+/**
+ * ignores that this practice itself owns
+ *
+ * .why = rhachet boots roles which write scratch state into `.agent/.cache/`. the
+ *        practice that creates the dir declares the ignore for it, so a repo that
+ *        takes `rhachet` is never left with cruft it did not ask for:
+ *        - a worktree teardown is not snagged by untracked scratch
+ *        - a hurried `git add .` cannot sweep a debug file that holds a secret
+ *
+ * .note = `.cache/` is generic tool scratch and belongs to the `git` practice, not
+ *         here. a practice declares the ignore for the dirs IT creates, and no more.
+ *
+ * .note = this list is NOT sorted here, and that is deliberate. `defineExpectedGitignoreContents`
+ *         sorts the union of these lines with the repo's own, so a `.sort()` at this site would
+ *         be a second sort that changes no output -- while it mutates a module-cached array in
+ *         place. `readonly` forbids that mutation outright rather than merely discourages it
+ *         (`rule.prefer.prevent-over-correct`).
+ */
+const ignoresSortable: readonly string[] = ['.agent/.cache/'];
+
+/**
+ * .what = emits the `.gitignore` this practice declares, given the repo's extant one
+ * .why  = the algorithm AND the ordered tail are imported, not declared here, because
+ *         `src/practices/git/best-practice/.gitignore.declapract.ts` declares this same
+ *         repo-root file. two declarers converge only while both emit an identical tail
+ *         by an identical algorithm -- so they share one, and the drift that would break
+ *         convergence cannot be written.
+ * .note = this file declares only `ignoresSortable`, which is the part the two
+ *         practices legitimately DIFFER on: rhachet owns `.agent/.cache/`, git owns
+ *         the generic scratch. the shared part is shared; the owned part is owned.
+ */
+const defineExpectedContents = (contents: string | null): string =>
+  defineExpectedGitignoreContents({ contents, ignoresSortable });
+
+/**
+ * .what = throws when the repo's `.gitignore` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. so this is what makes an upgrade actually deliver
+ *         `.agent/.cache/` to a repo that lacks it.
+ * .note = best-practice semantics are inverted from what a reader expects -- a THROW
+ *         means the practice is violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents(contents));
+};
+
+/**
+ * .what = unions this practice's declared ignores into the repo's `.gitignore`
+ * .why  = a findsert by construction -- a line already present stays present once,
+ *         and a repo's own custom ignores survive, because the file's extant lines
+ *         are unioned in before the sort.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output -- without both, `declapract fix` would rewrite this file forever.
+ *         clamped by `.gitignore.declapract.test.ts` -> `idempotency`.
+ */
+export const fix: FileFixFunction = (contents) => {
+  return { contents: defineExpectedContents(contents) };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/package.json

@@ -0,0 +1,18 @@
+{
+  "devDependencies": {
+    "rhachet": "@declapract{check.minVersion('1.43.1')}",
+    "rhachet-brains-anthropic": "@declapract{check.minVersion('0.4.1')}",
+    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.3')}",
+    "rhachet-brains-xai": "@declapract{check.minVersion('0.3.3')}",
+    "rhachet-roles-bhrain": "@declapract{check.minVersion('0.29.24')}",
+    "rhachet-roles-bhrowser": "@declapract{check.minVersion('0.1.0')}",
+    "rhachet-roles-bhuild": "@declapract{check.minVersion('0.21.22')}",
+    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.1')}",
+    "rhachet-roles-ghlitch": "@declapract{check.minVersion('0.2.5')}",
+    "rhachet-roles-rhachet": "@declapract{check.minVersion('0.1.7')}"
+  },
+  "scripts": {
+    "prepare:rhachet": "rhachet init --keys --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect dispatcher learner operator observer deployer playwright enroller",
+    "upgrade:rhachet": "rhachet upgrade"
+  }
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -5,9 +5,7 @@
     "jest": "@declapract{check.minVersion('30.2.0')}",
     "esbuild-register": "@declapract{check.minVersion('3.6.0')}",
     "test-fns": "@declapract{check.minVersion('1.15.8')}",
-    "tsx": "@declapract{check.minVersion('4.20.6')}",
-    "@swc/core": "@declapract{check.minVersion('1.15.3')}",
-    "@swc/jest": "@declapract{check.minVersion('0.2.39')}"
+    "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')",

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

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

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/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-fullusecase/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-fullusecase/declarations/practices/tests-expo/.test/assets/repo-expo-greenfield/declapract.use.yml

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

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

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