declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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

@@ -0,0 +1,94 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the tests-expo jest-expo/rtr SDK-major gate (#584 / defect D1).
+ * .why  = the unit test proves the check/fix in isolation; only the real executeApply pipeline
+ *         proves declapract WIRES the declaration to `package.json` and reaches a fixed point on
+ *         a re-run. the crash this gate prevents is a react-19-era jest-expo (54) held onto an
+ *         expo-51 / react-18 repo — every unit suite throws at jest-expo's preset setup — so the
+ *         gate must hold jest-expo at the repo's OWN expo major (51), never bump it to 54.
+ * .note = scoped `practice: 'tests-expo'` — the declaration reads only `contents`, never
+ *         `context.projectPractices`, so a practice scope is safe (no usecase-aware branch goes
+ *         dark) and isolates the apply to tests-expo's package.json declaration alone.
+ */
+describe('tests-expo package.json — pipeline gate on the repo expo/react major', () => {
+  given('[case1] an expo-51 / react-18 repo seeded with a react-19-era jest-expo 54 the gate aligns down to the expo major (51)', () => {
+    const tempDir = genTempDir({
+      slug: 'tests-expo-major-gate',
+      clone: './src/.test/assets/expo-migration/repo-app-protools-shaped',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo-migration/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const pkgPath = () => path.join(tempDir, 'package.json');
+    const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
+
+    const state = useBeforeAll(async () => {
+      // seed the crash shape: a react-19-era jest-expo/rtr on an expo-51 / react-18 repo
+      const seeded = {
+        ...JSON.parse(await readPkg()),
+        devDependencies: {
+          ...JSON.parse(await readPkg()).devDependencies,
+          expo: '~51.0.0',
+          react: '18.2.0',
+          'jest-expo': '^54.0.0',
+          'react-test-renderer': '^19.0.0',
+          'babel-preset-expo': '^12.0.0',
+          'isomorphic-fetch': '^3.0.0',
+        },
+      };
+      await fs.writeFile(pkgPath(), `${JSON.stringify(seeded, null, 2)}\n`);
+      const pkgBefore = await readPkg();
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      return { pkgBefore, pkgAfter1, pkgAfter2 };
+    }, 170_000);
+
+    when('[t0] the tests-expo gate is applied to the seeded package.json', () => {
+      then('jest-expo is held at the repo expo major (51), not bumped to 54', () => {
+        expect(JSON.parse(state.pkgBefore).devDependencies['jest-expo']).toEqual(
+          '^54.0.0',
+        );
+        expect(JSON.parse(state.pkgAfter1).devDependencies['jest-expo']).toEqual(
+          '^51.0.0',
+        );
+      });
+
+      then('react-test-renderer is held at the repo react major (18), not 19', () => {
+        expect(
+          JSON.parse(state.pkgAfter1).devDependencies['react-test-renderer'],
+        ).toEqual('^18.0.0');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.pkgBefore).toMatchSnapshot('package.json — before');
+        expect(state.pkgAfter1).toMatchSnapshot('package.json — after gate');
+      });
+
+      then('a second apply is a fixed point (the gate holds)', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/typescript-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/{practices/typescript → .test/assets/expo-fullusecase/declarations/practices/typescript-any}/bad-practices/relative-imports/src/<star><star>/<star>.ts.declapract.ts

@@ -1,5 +1,7 @@
 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
@@ -36,6 +38,12 @@ export const check: FileCheckFunction = (contents, { 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) {
@@ -50,6 +58,9 @@ export const fix: FileFixFunction = (contents, { relativeFilePath }) => {
   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');

package/dist/.test/assets/expo-fullusecase/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-fullusecase/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-fullusecase/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-fullusecase/declarations/practices/typescript-expo/__snapshots__/package.json.declapract.integration.test.ts.snap

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

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

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

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

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

package/dist/.test/assets/expo-fullusecase/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;

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

@@ -0,0 +1,14 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"],
+      "@assets/*": ["assets/*"]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}

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

@@ -0,0 +1,12 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = the expo tsconfig: extends `expo/tsconfig.base` (jsx, react-native module
+ *         resolution) instead of the node16 `@tsconfig/node20` base.
+ * .why  = CONTAINS, not EQUALS, so an app that has already customized its expo tsconfig
+ *         (extra paths, an app-specific include) is NOT clobbered — the check only asserts
+ *         the expo base + core `@src`/`@assets` paths are present. a greenfield expo repo
+ *         gets this emitted by `declapract fix`; a repo like app-protools-native (already
+ *         `extends: expo/tsconfig.base`) already satisfies it.
+ */
+export const check = FileCheckType.CONTAINS;

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

@@ -0,0 +1,43 @@
+import { FileCheckType } from 'declapract';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { check } from './best-practice/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, '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');
+    // 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');
+  });
+
+  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-fullusecase/declarations/practices/typescript-expo/tsconfig.json.declapract.integration.test.ts

@@ -0,0 +1,43 @@
+import { FileCheckType } from 'declapract';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { check } from './best-practice/tsconfig.json.declapract';
+
+/**
+ * .why integration = the template-content assertions read the shipped `tsconfig.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) 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 tsconfig.json', () => {
+  it('declares a CONTAINS check (a consumer may customize around the expo base)', () => {
+    expect(check).toEqual(FileCheckType.CONTAINS);
+  });
+
+  it('the emitted template is expo-shaped, not node', () => {
+    const template = JSON.parse(
+      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');
+    // the core path aliases a consumer relies on
+    expect(template.compilerOptions.paths['@src/*']).toEqual(['src/*']);
+    expect(template.compilerOptions.paths['@assets/*']).toEqual(['assets/*']);
+    // tsx is included (a react-native app has jsx), unlike the node tsconfig
+    expect(template.include).toContain('**/*.tsx');
+  });
+
+  it('the emitted tsconfig template matches snapshot', () => {
+    // snapshot the whole shipped template, so a reshape that keeps the pinned tokens green
+    // (a reordered path alias, a rephrased extends) reddens a vibecheck in review
+    // (rule.require.contract-snapshot-exhaustiveness)
+    const template = readFileSync(
+      path.join(__dirname, 'best-practice/tsconfig.json'),
+      'utf-8',
+    );
+    expect(template).toMatchSnapshot('typescript-expo tsconfig.json');
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/useCases.yml

@@ -0,0 +1,36 @@
+# the REAL app-react-native-expo usecase shape, mirrored for the full-usecase smoke.
+# .why  = a copy of src/useCases.yml's typescript-project-core + app-react-native-expo
+#         entries, so executeApply resolves the identical 23-practice set the live
+#         usecase does (extends is non-transitive — the consumer extends core directly).
+#         a drift guard in the smoke test pins this fixture's resolved set === the real
+#         src/useCases.yml resolved set, so this copy can never silently diverge.
+use-cases:
+  typescript-project-core:
+    practices:
+      - cache
+      - cicd-common
+      - conventional-commits
+      - husky
+      - directory-structure-src
+      - domain
+      - errors
+      - format
+      - git
+      - lint
+      - node
+      - nonpublished-modules
+      - package-json-order
+      - rhachet
+      - tests-any
+      - typescript-any
+      - pnpm
+  app-react-native-expo:
+    extends:
+      - typescript-project-core
+    practices:
+      - cicd-app-react-native-expo
+      - provision-github
+      - lint-react
+      - lint-react-native
+      - tests-expo
+      - typescript-expo

package/dist/.test/assets/expo-fullusecase/repo-greenfield/app.json

@@ -0,0 +1,6 @@
+{
+  "expo": {
+    "name": "greenfield-expo",
+    "slug": "greenfield-expo"
+  }
+}

package/dist/.test/assets/expo-fullusecase/repo-greenfield/declapract.use.yml

@@ -0,0 +1,24 @@
+# .note = a BARE create-expo-app-shaped tree — package.json + app.json only, NO src/ at all.
+# .why  = the r10 (l3) blocker-2 case: a brand-new expo app's FIRST `declapract fix`. proves the
+#         full usecase applies to a repo with no src/ — the domain / directory-structure EXISTS
+#         checks are unmet, and the apply must FLAG them without a halt or crash, not abort.
+# .note = declarations dir is symlinked by the test to src/.test/assets/expo-fullusecase/declarations,
+#         so the WHOLE resolved usecase (23 practices) is evaluated — every variable any of them
+#         references must be defined below.
+declarations: 'declarations/declapract.declare.yml'
+useCase: app-react-native-expo
+variables:
+  projectName: greenfield-expo
+  organizationName: ahbode
+  infrastructureNamespaceId: bbb111
+  awsAccountId:
+    prep: '111111111111'
+    prod: '222222222222'
+  app:
+    web:
+      domain:
+        prep: greenfield.prep.ahbode.dev
+        prod: greenfield.ahbode.dev
+      port:
+        hot: 3547
+        cold: 3549

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

@@ -0,0 +1,7 @@
+{
+  "name": "greenfield-expo",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {},
+  "devDependencies": {}
+}

package/dist/.test/assets/expo-migration/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# declarations for the app-protools-shaped graceful-migration integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml