declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/.test/assets/expo/declarations/practices/node/bad-practices/self-deps-not-link/package.json.declapract.ts

@@ -0,0 +1,76 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+const DEP_KEYS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+] as const;
+
+/**
+ * .what = finds self-dependencies that are not `link:.`
+ */
+const findBadSelfDeps = (
+  packageJson: Record<string, unknown>,
+): { depKey: string; version: string }[] => {
+  const packageName = packageJson.name as string | undefined;
+  if (!packageName) return [];
+
+  const badSelfDeps: { depKey: string; version: string }[] = [];
+
+  for (const depKey of DEP_KEYS) {
+    const deps = packageJson[depKey] as Record<string, string> | undefined;
+    if (!deps) continue;
+
+    const selfDepVersion = deps[packageName];
+    if (selfDepVersion && selfDepVersion !== 'link:.') {
+      badSelfDeps.push({ depKey, version: selfDepVersion });
+    }
+  }
+
+  return badSelfDeps;
+};
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('no package.json found');
+
+  const packageJson = JSON.parse(contents);
+  const badSelfDeps = findBadSelfDeps(packageJson);
+
+  // bad practice semantics: return = detected, throw = not detected
+  if (badSelfDeps.length > 0) return;
+
+  throw new Error('no bad self-dependencies found');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJson = JSON.parse(contents);
+  const packageName = packageJson.name as string | undefined;
+  if (!packageName) return { contents };
+
+  let modified = false;
+
+  for (const depKey of DEP_KEYS) {
+    const deps = packageJson[depKey] as Record<string, string> | undefined;
+    if (!deps) continue;
+
+    const selfDepVersion = deps[packageName];
+    if (selfDepVersion && selfDepVersion !== 'link:.') {
+      delete deps[packageName];
+      modified = true;
+
+      // if deps object is now empty, remove it
+      if (Object.keys(deps).length === 0) {
+        delete packageJson[depKey];
+      }
+    }
+  }
+
+  if (!modified) return { contents };
+
+  return {
+    contents: JSON.stringify(packageJson, null, 2),
+  };
+};

package/dist/.test/assets/expo/declarations/practices/node/best-practice/.npmrc.declapract.integration.test.ts

@@ -0,0 +1,165 @@
+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), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = pipeline test for the usecase-aware .npmrc findsert (check/fix union)
+ * .why  = a unit test proves the check/fix in isolation; only the real
+ *         executeApply pipeline proves that declapract:
+ *         - matches the .npmrc declaration to the target file
+ *         - feeds context.projectPractices with the expo signal
+ *           (cicd-app-react-native-expo present in the usecase)
+ *         - findserts the declared lines into the consumer's .npmrc: the base
+ *           node lines PLUS the hoisted-linker block, unioned in so a repo's own
+ *           lines survive (a consumer merge, NOT an EQUALS overwrite)
+ *         - reaches a fixed point on a second apply (idempotent)
+ */
+describe('node practice .npmrc — expo hoisted linker', () => {
+  given('[case1] an expo consumer repo with a base node .npmrc', () => {
+    const tempDir = genTempDir({
+      slug: 'node-npmrc-expo',
+      clone: './src/practices/node/.test/assets/repo-expo-npmrc',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const npmrcPath = () => path.join(tempDir, '.npmrc');
+
+    // useBeforeAll RETURNS the captured reads (no in-place mutation of a shared const)
+    const readState = useBeforeAll(async () => {
+      // capture the consumer's own .npmrc before any apply
+      const before = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // first apply
+      // .note = filter by file ONLY, never by practice. the practice filter
+      //         narrows projectPractices too (getDesiredPractices), which would
+      //         strip cicd-app-react-native-expo and silence the expo branch.
+      //         file-only keeps every usecase practice in projectPractices while
+      //         it applies just the .npmrc plan.
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: '.npmrc',
+      });
+      const after1 = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // second apply — to prove a fixed point
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: '.npmrc',
+      });
+      const after2 = await fs.readFile(npmrcPath(), 'utf-8');
+
+      return { before, after1, after2 };
+    }, 170_000);
+
+    when('[t0] the node practice is applied', () => {
+      then('the base node lines are preserved', () => {
+        expect(readState.after1).toContain('engine-strict=true');
+        expect(readState.after1).toContain('save-exact=true');
+        expect(readState.after1).toContain('message=%s 🎉');
+      });
+
+      then('the hoisted-linker block is appended', () => {
+        expect(readState.after1).toContain('node-linker=hoisted');
+        expect(readState.after1).toContain('public-hoist-pattern[]=*expo*');
+        expect(readState.after1).toContain(
+          'public-hoist-pattern[]=*react-native*',
+        );
+        expect(readState.after1).toContain(
+          'public-hoist-pattern[]=@react-native/*',
+        );
+        expect(readState.after1).toContain('public-hoist-pattern[]=metro*');
+        expect(readState.after1).toContain('public-hoist-pattern[]=*metro-*');
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(readState.before).toMatchSnapshot('.npmrc — before');
+        expect(readState.after1).toMatchSnapshot('.npmrc — after apply');
+      });
+    });
+
+    when('[t1] the node practice is applied a second time', () => {
+      then('the fixed point holds — after2 equals after1', () => {
+        expect(readState.after2).toEqual(readState.after1);
+      });
+
+      then('a single hoist block exists, never a duplicate', () => {
+        const occurrences =
+          readState.after2.split('node-linker=hoisted').length - 1;
+        expect(occurrences).toEqual(1);
+      });
+    });
+  });
+
+  /**
+   * .what = a narrow-scope apply of the node practice on an expo repo leaves the hoist intact
+   * .why  = a narrow `declapract fix --practice node` on an expo repo makes
+   *         projectPractices === ['node'], so the expo branch does not fire. the `.npmrc`
+   *         declaration is a findsert (check/fix union) that appends only absent lines, so a
+   *         narrow-scope apply is a no-op on an already-hoisted `.npmrc`. this test reproduces
+   *         that narrow-scope invocation and asserts the hoist is preserved — it fails if the
+   *         declaration is ever changed to an EQUALS overwrite (which would append no union
+   *         and rewrite the file to base).
+   */
+  given('[case2] a narrow --practice node apply on an expo repo keeps the hoist', () => {
+    const tempDir = genTempDir({
+      slug: 'node-npmrc-expo-narrow',
+      clone: './src/practices/node/.test/assets/repo-expo-npmrc',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const npmrcPath = () => path.join(tempDir, '.npmrc');
+
+    const readState = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+
+      // first, reach the CORRECT expo state via the SUPPORTED path (file filter keeps
+      // every usecase practice in projectPractices, so the expo branch fires)
+      await executeApply({ config, file: '.npmrc' });
+      const withHoist = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // now apply the narrow scope: `--practice node` makes projectPractices === ['node'],
+      // so the expo branch does not fire. the findsert appends only absent lines, so the
+      // hoist is preserved.
+      await executeApply({ config, practice: 'node' });
+      const afterNarrow = await fs.readFile(npmrcPath(), 'utf-8');
+
+      return { withHoist, afterNarrow };
+    }, 170_000);
+
+    when('[t0] the supported path first produced the hoist', () => {
+      then('the hoisted-linker block is present', () => {
+        expect(readState.withHoist).toContain('node-linker=hoisted');
+        expect(readState.withHoist).toContain('public-hoist-pattern[]=*expo*');
+      });
+    });
+
+    when('[t1] a narrow `--practice node` fix then runs on that repo', () => {
+      then('the hoist is preserved', () => {
+        expect(readState.afterNarrow).toContain('node-linker=hoisted');
+        expect(readState.afterNarrow).toContain(
+          'public-hoist-pattern[]=*expo*',
+        );
+      });
+
+      then('the base node lines survive too', () => {
+        expect(readState.afterNarrow).toContain('engine-strict=true');
+        expect(readState.afterNarrow).toContain('save-exact=true');
+      });
+
+      then('the narrow-scope apply is a no-op — afterNarrow equals withHoist', () => {
+        expect(readState.afterNarrow).toEqual(readState.withHoist);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo/declarations/practices/node/best-practice/.npmrc.declapract.ts

@@ -0,0 +1,60 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { defineExpectedNpmrcContents } from '../../../utils/defineExpectedNpmrcContents';
+
+/**
+ * .what = the `.npmrc` the node practice declares, usecase-aware for the expo runtime
+ * .why  = a flat node_modules (hoisted linker) is create-expo-app's own default for pnpm
+ *         and the documented fallback when isolated installs break metro/react-native
+ *         native-module lookup (SDK 54+ supports isolated, but hoisted is the trodden
+ *         default). so an expo repo layers the hoisted-linker block atop the base `.npmrc`
+ *         every node repo gets, rather than fork a separate practice
+ *         (rule.avoid.runtime-forks). the forced-vs-opt-in call is flagged for the wisher
+ *         in `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+ * .why  = a FINDSERT (check/fix union), NOT an EQUALS overwrite. the fix only APPENDS
+ *         absent declared lines and never removes a line, so a repo's own `.npmrc`
+ *         settings — and, crucially, a correctly-hoisted expo `.npmrc` under a narrow
+ *         `declapract fix --practice node` (where the expo signal goes dark) — are
+ *         preserved rather than clobbered. the algorithm lives in
+ *         `defineExpectedNpmrcContents`, shared by `check` and `fix` so the gate and the
+ *         repair can never disagree (mirrors the repo-root `.gitignore`).
+ * .note = best-practice check semantics are inverted — a THROW means the practice is
+ *         violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  projectPractices: string[],
+): string => defineExpectedNpmrcContents({ contents, projectPractices });
+
+/**
+ * .what = throws when the repo's `.npmrc` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. the expected value UNIONS the repo's extant lines in, so a repo
+ *         that already carries the declared lines (plus any of its own) passes — the
+ *         check mandates PRESENCE of the declared lines, never EQUALITY, so it can never
+ *         demand a custom line be removed.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  // a plain comparison + clear throw, NOT an `expect` assertion: declapract runs
+  // `check` outside any test runner, so a test-diff-shaped throw is a friction hazard
+  // (rule.forbid.friction-hazards) — the caller only needs a clean, stable signal.
+  const expected = defineExpectedContents(contents, context.projectPractices);
+  if (contents !== expected)
+    throw new Error('.npmrc does not carry the declared node/expo lines');
+};
+
+/**
+ * .what = unions this practice's declared `.npmrc` lines into the repo's extant one
+ * .why  = a findsert by construction — a line already present stays present once, a
+ *         repo's own settings survive, and (the fix this closes) a hoisted expo
+ *         `.npmrc` is never stripped by a narrow-scope apply.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own output.
+ *         clamped by `.npmrc.declapract.test.ts` -> `idempotency` and by the pipeline
+ *         test's narrow-scope `[case2]`.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(contents, context.projectPractices),
+  };
+};

package/dist/.test/assets/expo/declarations/practices/node/best-practice/.nvmrc

@@ -0,0 +1 @@
+v22.21.0

package/dist/.test/assets/expo/declarations/practices/node/best-practice/__snapshots__/.npmrc.declapract.integration.test.ts.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`node practice .npmrc — expo hoisted linker given: [case1] an expo consumer repo with a base node .npmrc when: [t0] the node practice is applied then: the before + after contents match snapshot: .npmrc — after apply 1`] = `
+"engine-strict=true
+save-exact=true
+message=%s 🎉
+
+# hoisted linker flattens node_modules — create-expo-app default for pnpm,
+# the documented fallback when isolated installs break metro native lookup
+node-linker=hoisted
+public-hoist-pattern[]=*expo*
+public-hoist-pattern[]=*react-native*
+public-hoist-pattern[]=@react-native/*
+public-hoist-pattern[]=metro*
+public-hoist-pattern[]=*metro-*
+"
+`;
+
+exports[`node practice .npmrc — expo hoisted linker given: [case1] an expo consumer repo with a base node .npmrc when: [t0] the node practice is applied then: the before + after contents match snapshot: .npmrc — before 1`] = `
+"engine-strict=true
+save-exact=true
+message=%s 🎉
+"
+`;

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

@@ -0,0 +1,15 @@
+{
+  "name": "@declapract{variable.projectName}",
+  "author": "@declapract{variable.organizationName}",
+  "version": "@declapract{check.minVersion('0.0.0')}",
+  "repository": "@declapract{variable.organizationName}/@declapract{variable.projectName}",
+  "homepage": "https://github.com/@declapract{variable.organizationName}/@declapract{variable.projectName}",
+  "bugs": "https://github.com/@declapract{variable.organizationName}/@declapract{variable.projectName}/issues",
+  "scripts": {
+    "fix": "npm run fix:format && npm run fix:lint",
+    "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
+    "prepush": "npm run test && npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify"
+  }
+}

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

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

package/dist/.test/assets/expo/declarations/practices/node/best-practice/readme.md

@@ -0,0 +1 @@
+# @declapract{variable.projectName}

package/dist/.test/assets/expo/declarations/practices/node/best-practice/readme.md.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)

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

@@ -0,0 +1,8 @@
+# minimal expo use case for integration tests
+# .why = the .npmrc branch fires on context.projectPractices.includes('cicd-app-react-native-expo'),
+#        so both practices must be listed for the usecase to carry that signal.
+use-cases:
+  app-react-native-expo:
+    practices:
+      - node
+      - cicd-app-react-native-expo

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

@@ -0,0 +1,10 @@
+# declarations for the full-usecase evaluation smoke test
+# .why  = the migration fixture curates 11 practices to keep the graceful-migration
+#         assertions legible; this fixture carries the FULL resolved set for
+#         app-react-native-expo (23 practices, extends typescript-project-core), so
+#         executeApply evaluates the REAL usecase shape end-to-end. the point is to
+#         prove the complete usecase resolves + applies without a variable gap or
+#         crash, not just the migration-risk slice.
+declare:
+  practices: practices
+  use-cases: useCases.yml

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

@@ -0,0 +1,108 @@
+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 (90+ seconds per invocation due to full practice evaluation)
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = acceptance test for cache practice with .ifInstalled() modifier
+ * .why = verifies that minVersion().ifInstalled() correctly:
+ *        - skips check when package is not installed
+ *        - flags outdated versions when package IS installed
+ *        - passes when package is at or above minimum version
+ */
+describe('cache practice with ifInstalled', () => {
+  given('[case1] repo WITHOUT cache package installed', () => {
+    const tempDir = genTempDir({
+      slug: 'cache-not-installed',
+      clone: './src/practices/cache/.test/assets/repo-without-cache-package',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    // run executeApply before assertions
+    useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'cache',
+      });
+    }, 120_000); // 2 min timeout
+
+    when('[t0] after declapract apply', () => {
+      then('package.json is unchanged (ifInstalled skips absent packages)', async () => {
+        const packageJson = JSON.parse(
+          await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
+        );
+        // should NOT have added cache packages since they were absent
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBeUndefined();
+        expect(packageJson.dependencies['simple-on-disk-cache']).toBeUndefined();
+        expect(packageJson.dependencies['with-simple-cache']).toBeUndefined();
+        // original dependency should still be there
+        expect(packageJson.dependencies.lodash).toBe('4.17.21');
+      });
+    });
+  });
+
+  given('[case2] repo WITH outdated cache package', () => {
+    const tempDir = genTempDir({
+      slug: 'cache-outdated',
+      clone: './src/practices/cache/.test/assets/repo-with-old-cache-package',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    // run executeApply before assertions
+    useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'cache',
+      });
+    }, 120_000); // 2 min timeout
+
+    when('[t0] after declapract apply', () => {
+      then('package.json has version upgraded to minimum', async () => {
+        const packageJson = JSON.parse(
+          await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
+        );
+        // should have upgraded from 0.3.0 to 0.4.3
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+      });
+    });
+  });
+
+  given('[case3] repo WITH valid cache package version', () => {
+    const tempDir = genTempDir({
+      slug: 'cache-valid',
+      clone: './src/practices/cache/.test/assets/repo-with-valid-cache-package',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    // run executeApply before assertions
+    useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'cache',
+      });
+    }, 120_000); // 2 min timeout
+
+    when('[t0] after declapract apply', () => {
+      then('package.json version is unchanged (already at minimum)', async () => {
+        const packageJson = JSON.parse(
+          await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
+        );
+        // should still be 0.4.3 (unchanged, already valid)
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-old-cache-package/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test (contains declapract.declare.yml + dist/)
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project-old-cache'

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-old-cache-package/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-project-old-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "simple-in-memory-cache": "0.3.0"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-valid-cache-package/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test (contains declapract.declare.yml + dist/)
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project-valid-cache'

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

@@ -0,0 +1,7 @@
+{
+  "name": "test-project-valid-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "simple-in-memory-cache": "0.4.3"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-without-cache-package/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test (contains declapract.declare.yml + dist/)
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project-no-cache'

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-without-cache-package/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-project-no-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "lodash": "4.17.21"
+  }
+}

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

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