declapract-typescript-ehmpathy 0.49.9 → 0.49.11

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

@@ -0,0 +1,112 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: jest.unit.config.ts — after fix 1`] = `
+"/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo wires up babel-preset-expo (metro's transform) + react-native module
+  // resolution (platform suffixes, haste). this is what lets tests that reach the
+  // expo/react-native boundary load, where a plain node preset cannot.
+  preset: 'jest-expo',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/unit.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // the jest-expo preset's transformIgnorePatterns assume a hoisted (flat) node_modules.
+  // pnpm's \`.pnpm/\`-nested store ships react-native/expo as untranspiled ESM one layer
+  // deeper, so add a \`.pnpm/\` branch that still transforms those families. a repo that
+  // pulls other untranspiled-ESM packages (e.g. a native storage lib) appends its own
+  // package names to BOTH branches.
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: [
+    // note: order matters
+    '**/*.test.{ts,tsx}',
+    '!**/*.acceptance.test.{ts,tsx}',
+    '!**/*.integration.test.{ts,tsx}',
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  setupFilesAfterEnv: ['./jest.unit.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;
+"
+`;
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: package.json — after fix 1`] = `
+"{
+  "name": "test-expo-app",
+  "version": "1.0.0",
+  "devDependencies": {
+    "@jest/globals": "30.2.0",
+    "@types/jest": "30.0.0",
+    "jest": "30.2.0",
+    "esbuild-register": "3.6.0",
+    "test-fns": "1.15.8",
+    "tsx": "4.20.6",
+    "jest-expo": "54.0.0",
+    "@babel/core": "7.24.0",
+    "babel-preset-expo": "12.0.0",
+    "react-test-renderer": "19.0.0",
+    "isomorphic-fetch": "3.0.0",
+    "typescript": "5.4.5"
+  },
+  "scripts": {
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${THOROUGH:-}\\" != \\"true\\" ] && echo '--changedSince=main') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${THOROUGH:-}\\" != \\"true\\" ] && echo '--changedSince=main') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:types": "tsc -p ./tsconfig.json --noEmit",
+    "build": "npm run build:web",
+    "build:web": "npx expo export --platform web"
+  }
+}
+"
+`;
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: tsconfig.json — after fix 1`] = `
+"{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": [
+        "src/*"
+      ],
+      "@assets/*": [
+        "assets/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}
+"
+`;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/bad-practices/inline-jest-config/.declapract.readme.md

@@ -0,0 +1,22 @@
+# bad-practice: inline-jest-config
+
+## .what
+
+a top-level `jest` key in a consumer's `package.json`.
+
+## .why it is bad
+
+an expo app that migrated to jest-expo by hand often carries the jest-expo preset INLINE in
+`package.json` AND a `jest.*.config.ts` file at the same time — a dual source of truth. `tests-expo`
+declares the jest config as its own `jest.*.config.ts` files (the go-forward home), so an inline
+block is redundant and the two configs can fight over the same run.
+
+## .the fix
+
+drop the inline `jest` key. the `jest.*.config.ts` files that `tests-expo` drops are the one home,
+so no jest settings are lost — they move to (or already live in) the config files.
+
+## .see also
+
+- `src/practices/tests-expo/best-practice/jest.*.config.ts` — the go-forward jest config home
+- `rule.require.idempotent-fixes` — the twice-applied clamp this fix owes

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/bad-practices/inline-jest-config/package.json.declapract.ts

@@ -0,0 +1,36 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = removes a top-level `jest` key from a consumer's package.json.
+ * .why  = an expo app that migrated by hand often carries a jest-expo preset INLINE in
+ *         package.json AND a jest.*.config.ts file at the same time — a dual source of
+ *         truth. tests-expo declares the jest config as its own jest.*.config.ts files
+ *         (the go-forward home), so the inline block is redundant and must be dropped, or
+ *         two configs fight over the same run. this is a bad-practice: `check` DETECTS the
+ *         inline key (returns) and `fix` drops it, so the jest.*.config.ts files stay the
+ *         one home.
+ */
+export const check: FileCheckFunction = (contents) => {
+  // no package.json → no key to detect, skip
+  if (!contents) throw new Error('does not match bad practice');
+
+  // an inline `jest` key is the dual-source hazard → detected
+  const packageJSON = JSON.parse(contents);
+  if (packageJSON.jest !== undefined) return;
+
+  // no inline `jest` key → not the bad practice, skip
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // drop the inline `jest` key; the jest.*.config.ts files are the one home.
+  // destructure to EXCLUDE the key rather than delete-in-place (rule.require.immutable-vars)
+  const packageJSON = JSON.parse(contents);
+  const { jest: _jest, ...updatedPackageJSON } = packageJSON;
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.acceptance.config.ts

@@ -0,0 +1,43 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo/web = jsdom + react-native-web, so acceptance tests exercise the web build
+  // surface. (a repo that prefers a device/simulator acceptance harness, e.g. playwright
+  // against the exported web app, swaps this out — the cicd-common shard runner reads the
+  // jest config named here.)
+  preset: 'jest-expo/web',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/acceptance.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // pnpm-nested react-native/expo ESM must still transform (see jest.unit.config.ts).
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: ['**/*.acceptance.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.acceptance.env.ts

@@ -0,0 +1,15 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since the web build surface is exercised end-to-end
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.config.ts

@@ -0,0 +1,7 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import config from './jest.unit.config';
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.integration.config.ts

@@ -0,0 +1,42 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo/web = a single jsdom project with react-native-web + expo module
+  // resolution, so integration tests that reach the expo/react-native boundary load
+  // under jsdom.
+  preset: 'jest-expo/web',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/integration.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // pnpm-nested react-native/expo ESM must still transform (see jest.unit.config.ts).
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: ['**/*.integration.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  setupFilesAfterEnv: ['./jest.integration.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.integration.env.ts

@@ -0,0 +1,22 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since downstream apis are reached
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/**
+ * sanity check that integration tests only run in the 'test' environment
+ * .why = prevent prod state pollution + financial mutations from test data
+ */
+if (process.env.NODE_ENV !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new Error(`integration-test does not target stage 'test'`);

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.unit.config.ts

@@ -0,0 +1,53 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo wires up babel-preset-expo (metro's transform) + react-native module
+  // resolution (platform suffixes, haste). this is what lets tests that reach the
+  // expo/react-native boundary load, where a plain node preset cannot.
+  preset: 'jest-expo',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/unit.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // the jest-expo preset's transformIgnorePatterns assume a hoisted (flat) node_modules.
+  // pnpm's `.pnpm/`-nested store ships react-native/expo as untranspiled ESM one layer
+  // deeper, so add a `.pnpm/` branch that still transforms those families. a repo that
+  // pulls other untranspiled-ESM packages (e.g. a native storage lib) appends its own
+  // package names to BOTH branches.
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: [
+    // note: order matters
+    '**/*.test.{ts,tsx}',
+    '!**/*.acceptance.test.{ts,tsx}',
+    '!**/*.integration.test.{ts,tsx}',
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  setupFilesAfterEnv: ['./jest.unit.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-expo/best-practice/jest.unit.env.ts

@@ -0,0 +1,18 @@
+import util from 'node:util';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/**
+ * sanity check that unit tests only run in the 'test' environment
+ * .why = prevent prod state pollution + financial mutations from test data
+ */
+if (process.env.NODE_ENV !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new Error(`unit-test does not target stage 'test'`);

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

@@ -0,0 +1,9 @@
+{
+  "devDependencies": {
+    "jest-expo": "@declapract{check.minVersion('54.0.0')}",
+    "@babel/core": "@declapract{check.minVersion('7.24.0')}",
+    "babel-preset-expo": "@declapract{check.minVersion('12.0.0')}",
+    "react-test-renderer": "@declapract{check.minVersion('19.0.0')}",
+    "isomorphic-fetch": "@declapract{check.minVersion('3.0.0')}"
+  }
+}

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

@@ -0,0 +1,16 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .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.
+ */
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/expo-toolchain/declarations/practices/typescript-any/bad-practices/relative-imports/.declapract.readme.md

@@ -0,0 +1,45 @@
+this bad practice detects relative imports that traverse up directories (`../`) and can be replaced with the `@src/` path alias.
+
+why this matters:
+- relative paths are fragile and break when files are moved or reorganized
+- `@src/` alias provides stable, absolute imports from the src root
+- enables easier refactoring and code navigation
+- imports remain correct regardless of file location
+
+what it catches:
+- imports using `../` (e.g., `from '../utils/helper'`)
+- deeply nested relative imports (e.g., `from '../../../domain/objects'`)
+
+what it ignores:
+- same-directory imports (`./`) which are appropriate for local modules
+- files outside `src/` directory
+- imports already using `@src/` alias
+
+the fix automatically rewrites:
+```typescript
+// before
+import { helper } from '../utils/helper';
+import { thing } from '../../shared/thing';
+
+// after
+import { helper } from '@src/utils/helper';
+import { thing } from '@src/shared/thing';
+```
+
+## two-pass migration + the `directory-structure-src` pair
+
+a file still under a deprecated src dir (`logic/`, `data/`, `domain/`, `model/`, `services/`,
+`__nonpublished_modules__/`) is **deferred** this pass — the rewrite is held to the next `declapract
+fix` pass, once the file sits at its new path. this is because `directory-structure-src`'s
+`old-*-dir` bad-practices RELOCATE that file in the same pass, and a relocate plus an in-place
+rewrite of one file in one apply throws ENOENT on the unlinked source. both practices share the
+guard via `src/utils/isDeferredToDeprecatedDirMove.ts`, so they cannot drift.
+
+two consequences a consumer should know:
+
+- **run `declapract fix` twice** on a repo that still holds deprecated-dir files: pass 1 relocates,
+  pass 2 rewrites the moved files' imports at their new path.
+- **this practice pairs with `directory-structure-src`.** the deferral only completes if
+  `directory-structure-src` is also in the usecase to perform the relocate. every usecase that
+  declares `typescript-any` today also declares `directory-structure-src`; keep them together, or a
+  deferred file is never moved and its rewrite never fires.

package/dist/.test/assets/expo-toolchain/declarations/practices/typescript-any/bad-practices/relative-imports/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,97 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { isDeferredToDeprecatedDirMove } from '../../../../../../utils/isDeferredToDeprecatedDirMove';
+
+/**
+ * .what = detects relative imports that should use @src alias
+ * .why = relative paths are fragile and break when files move
+ */
+
+// matches relative imports that go up directories (../)
+const RELATIVE_IMPORT_PATTERN = /from\s+['"](\.\.\/)+(.*?)['"]/g;
+
+const isInPracticesDir = (relativeFilePath: string | undefined): boolean =>
+  relativeFilePath?.includes('src/practices/') ?? false;
+
+const isDeclapractFile = (relativeFilePath: string | undefined): boolean =>
+  relativeFilePath?.endsWith('.declapract.ts') ?? false;
+
+/**
+ * skip files in src/practices/ because they are templates defining what target
+ * codebases should look like - not actual config files to be fixed. however,
+ * .declapract.ts files contain check/fix logic (not template content) so they
+ * should still be processed normally by other practices.
+ */
+const shouldSkip = (relativeFilePath: string | undefined): boolean =>
+  isInPracticesDir(relativeFilePath) && !isDeclapractFile(relativeFilePath);
+
+export const check: FileCheckFunction = (contents, { relativeFilePath }) => {
+  if (!contents) throw new Error('does not match bad practice');
+
+  // skip if file is not in src/
+  if (!relativeFilePath?.startsWith('src/')) {
+    throw new Error('does not match bad practice');
+  }
+
+  // skip practice template files
+  if (shouldSkip(relativeFilePath)) {
+    throw new Error('does not match bad practice');
+  }
+
+  // defer a file still under a deprecated dir to its peer dir-move: the move
+  // relocates it this pass, then this rewrite fires at the new path next pass.
+  // the two never touch one file in one apply, so no relocate+rewrite ENOENT.
+  if (isDeferredToDeprecatedDirMove({ relativeFilePath }))
+    throw new Error('deferred to peer dir-move this pass');
+
+  // check for relative imports that go up directories (../)
+  const matches = contents.match(RELATIVE_IMPORT_PATTERN);
+  if (matches && matches.length > 0) {
+    return; // matches bad practice
+  }
+
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents, { relativeFilePath }) => {
+  if (!contents) return {};
+  if (!relativeFilePath?.startsWith('src/')) return {};
+  if (shouldSkip(relativeFilePath)) return {};
+
+  // defer a file still under a deprecated dir to its peer dir-move (see check)
+  if (isDeferredToDeprecatedDirMove({ relativeFilePath })) return {};
+
+  // calculate the path parts of the current file
+  const pathParts = relativeFilePath.split('/');
+  const srcIndex = pathParts.indexOf('src');
+
+  // get the directories between src/ and the current file
+  const currentDirParts = pathParts.slice(srcIndex + 1, -1);
+
+  // replace relative imports with @src imports (only if they stay within src/)
+  const fixed = contents.replace(
+    /from\s+['"]((\.\.\/)+)(.*?)['"]/g,
+    (match, dots, _, importPath) => {
+      // count how many ../ we have
+      const upCount = (dots.match(/\.\.\//g) || []).length;
+
+      // if going up more levels than we have directories within src/, it goes OUTSIDE src
+      // leave these imports unchanged (e.g., ../../package.json from src/utils/index.ts)
+      if (upCount > currentDirParts.length) {
+        return match;
+      }
+
+      // if going up exactly as many levels as we have directories, target is at src root
+      if (upCount === currentDirParts.length) {
+        return `from '@src/${importPath}'`;
+      }
+
+      // otherwise, calculate the remaining path after going up
+      const remainingParts = currentDirParts.slice(0, -upCount);
+      const targetPath = [...remainingParts, importPath].join('/');
+      return `from '@src/${targetPath}'`;
+    },
+  );
+
+  return { contents: fixed };
+};

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

@@ -0,0 +1,17 @@
+this bundle defines the runtime-agnostic half of the typescript triad: the shared
+typecheck that every runtime runs, regardless of how it builds or bundles.
+
+namely:
+- the `test:types` command — `tsc -p ./tsconfig.json --noEmit`
+  - typechecks without a build, so it runs the same on node and expo
+  - the runtime halves (`typescript-node`, `typescript-expo`) ship the tsconfig it points at
+- the `typescript` dev dependency, pinned to a shared floor
+
+why a runtime-agnostic half:
+- the typecheck is identical across runtimes; only the build/bundle differs
+- so the shared command + dep live here, and each runtime half declares only its own
+  tsconfig + build (tsc-alias for node, metro/expo for expo)
+
+see the runtime halves for the build-specific config:
+- `typescript-node` — node16 tsconfig + `tsc` + `tsc-alias` post-compilation build
+- `typescript-expo` — `expo/tsconfig.base` + `expo export`, bundled by metro (no tsc build)

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

@@ -0,0 +1,8 @@
+{
+  "devDependencies": {
+    "typescript": "@declapract{check.minVersion('5.4.5')}"
+  },
+  "scripts": {
+    "test:types": "tsc -p ./tsconfig.json --noEmit"
+  }
+}

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

@@ -0,0 +1,11 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = the runtime-agnostic half of the typescript triad: the `typescript` dep
+ *         + the `tsc --noEmit` typecheck command
+ * .why  = the typecheck emits no output, so it is bound to no bundler and runs on any
+ *         runtime. the tsconfig.json it points at is supplied by the runtime half
+ *         (typescript-node or typescript-expo), so this practice pairs with exactly
+ *         one of them per usecase.
+ */
+export const check = FileCheckType.CONTAINS;

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

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "build": "npm run build:web",
+    "build:web": "npx expo export --platform web"
+  }
+}

package/dist/.test/assets/expo-toolchain/declarations/practices/typescript-expo/best-practice/package.json.declapract.integration.test.ts

@@ -0,0 +1,30 @@
+import { FileCheckType } from 'declapract';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { check } from './package.json.declapract';
+
+/**
+ * .why integration = the build-command assertions read the shipped `package.json` template
+ *   from disk via readFileSync — a filesystem boundary. per rule.forbid.unit.remote-boundaries
+ *   a `.test.ts` (unit) may not cross an fs boundary, so this guard (which exists to catch
+ *   DRIFT in the real template's build commands) lives at the integration grain, where a real
+ *   file read is permitted. an inline copy would test a hardcoded string, not the template,
+ *   so it could not catch the drift this guards.
+ */
+describe('typescript-expo package.json', () => {
+  it('declares a CONTAINS check (a repo may add its own build variants)', () => {
+    expect(check).toEqual(FileCheckType.CONTAINS);
+  });
+
+  it('the emitted build command uses metro/EAS (expo export), not tsc', () => {
+    const template = JSON.parse(
+      readFileSync(path.join(__dirname, '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');
+    // the web build is expo export, NOT a tsc build (an expo app never builds with tsc)
+    expect(template.scripts['build:web']).toContain('expo export --platform web');
+    expect(template.scripts.build).not.toContain('tsc');
+  });
+});

package/dist/.test/assets/expo-toolchain/declarations/practices/typescript-expo/best-practice/package.json.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = the expo half of the typescript triad: the `build` command that metro/EAS
+ *         use instead of tsc.
+ * .why  = an expo app never builds with tsc — metro bundles the native build and
+ *         `npx expo export --platform web` produces the web `dist/`. `build` aliases
+ *         `build:web` so the shared cicd-common `.test.yml` (which runs `npm run build`)
+ *         works on an expo repo, and `.deploy-expo.yml` (which runs `npm run build:web`)
+ *         works too. CONTAINS, so a repo may add its own build variants around these.
+ */
+export const check = FileCheckType.CONTAINS;