declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/pnpm/.declapract.integration.test.ts

@@ -0,0 +1,325 @@
+import fs from 'fs/promises';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+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);
+
+/** extract the pinned version out of a `packageManager` field (`pnpm@10.34.5` → `10.34.5`). */
+const asPinnedVersionFromPackageManager = (packageManager: string): string =>
+  packageManager.split('@')[1] ?? '';
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((done) => setTimeout(done, ms));
+
+/**
+ * .what = query the npm registry for a package's published version, with bounded retry-with-backoff.
+ * .why  = a bare one-shot `npm view` makes a TRANSIENT registry blip (DNS hiccup, rate limit, brief
+ *         outage) redden the whole suite even when the pin is fine — the intermittent-failure class
+ *         rule.forbid.behavior-hazards targets. a phantom pin (never published) fails EVERY attempt
+ *         and still reddens after the budget, so the phantom-guard intent holds; a transient blip
+ *         recovers on a later attempt. fails loud with the last error once the budget is spent
+ *         (rule.forbid.failhide) — never a silent skip.
+ * .note = a committed/metadata source cannot substitute here: only the registry can confirm a pin
+ *         was actually PUBLISHED (a phantom pin parses fine locally). so the registry read stays,
+ *         hardened by retry rather than replaced.
+ */
+const getPublishedVersionFromRegistry = async (input: {
+  packageName: string;
+  version: string;
+  attemptsLeft: number;
+  backoffMs: number;
+}): Promise<string> => {
+  try {
+    return execFileSync(
+      'npm',
+      ['view', `${input.packageName}@${input.version}`, 'version'],
+      { timeout: 15_000 },
+    )
+      .toString('utf-8')
+      .trim();
+  } catch (error) {
+    // budget spent → fail loud with the last error (never swallow)
+    if (input.attemptsLeft <= 1) throw error;
+    // otherwise back off and retry — a transient blip recovers, a phantom pin fails again
+    await sleep(input.backoffMs);
+    return getPublishedVersionFromRegistry({
+      ...input,
+      attemptsLeft: input.attemptsLeft - 1,
+      backoffMs: input.backoffMs * 2,
+    });
+  }
+};
+
+/**
+ * .what = pipeline test for the pnpm npm→pnpm migration bad-practices
+ * .why  = the unit tests prove each fix in isolation; only the real executeApply pipeline
+ *         proves declapract WIRES them up — matches each declaration to its target file
+ *         (npm-overrides on package.json, husky-lockfile-check on the husky hook), and
+ *         reaches a fixed point on a re-run.
+ */
+describe('pnpm npm→pnpm migration — pipeline', () => {
+  given('[case1] a repo mid-migration from npm to pnpm', () => {
+    const tempDir = genTempDir({
+      slug: 'pnpm-npm-to-pnpm',
+      clone: './src/practices/pnpm/.test/assets/repo-npm-to-pnpm',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/pnpm/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const readPkg = () => fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+    const readHusky = () =>
+      fs.readFile(path.join(tempDir, '.husky/check.lockfile.sh'), 'utf-8');
+
+    // useBeforeAll RETURNS the captured state (no in-place mutation of a shared const)
+    const state = useBeforeAll(async () => {
+      const pkgBefore = await readPkg();
+      const huskyBefore = await readHusky();
+
+      // apply the package.json bad-practice (npm-overrides relocates the pins)
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      // apply the husky lockfile-hook bad-practice
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: '.husky/check.lockfile.sh',
+      });
+      const huskyAfter1 = await readHusky();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: '.husky/check.lockfile.sh',
+      });
+      const huskyAfter2 = await readHusky();
+
+      return {
+        pkgBefore,
+        pkgAfter1,
+        pkgAfter2,
+        huskyBefore,
+        huskyAfter1,
+        huskyAfter2,
+      };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied to package.json', () => {
+      then('overrides + resolutions relocate into pnpm.overrides', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.pnpm.overrides['react-refresh']).toEqual('~0.14.0');
+        expect(pkg.overrides).toBeUndefined();
+        expect(pkg.resolutions).toBeUndefined();
+      });
+
+      then('the `npm run` invocation convention is left intact (repo-wide idiom)', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.scripts.prepush).toEqual('npm run test && npm run build');
+      });
+
+      then('the packageManager pin survives (best-practice no-op)', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.packageManager).toEqual('pnpm@10.34.5');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.pkgBefore).toMatchSnapshot('package.json — before');
+        expect(state.pkgAfter1).toMatchSnapshot('package.json — after');
+      });
+
+      then('a second apply is a fixed point', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+
+    when('[t1] the pnpm practice is applied to the husky hook', () => {
+      then('the lockfile name + install command become pnpm', () => {
+        expect(state.huskyAfter1).toContain('pnpm-lock.yaml');
+        expect(state.huskyAfter1).toContain('pnpm install');
+        expect(state.huskyAfter1).not.toContain('package-lock.json');
+        expect(state.huskyAfter1).not.toMatch(/(?<!p)npm install/);
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.huskyBefore).toMatchSnapshot('check.lockfile.sh — before');
+        expect(state.huskyAfter1).toMatchSnapshot('check.lockfile.sh — after');
+      });
+
+      then('a second apply is a fixed point', () => {
+        expect(state.huskyAfter2).toEqual(state.huskyAfter1);
+      });
+    });
+  });
+
+  given('[case2] a repo OFF the blessed pnpm pin (10.32.1)', () => {
+    // the [case1] fixture seeds the pin already AT 10.34.5, so it proves only the no-op
+    // path. this case seeds the pin OFF the blessed version to prove the convergence
+    // rewrite (10.32.1 → 10.34.5) in pnpm's OWN suite — where an engineer looks first —
+    // not only inside the expo migration fixture. the best-practice CONTAINS check rejects
+    // a package.json that does not carry the exact `pnpm@10.34.5`, so `declapract fix`
+    // merges the blessed pin over the off one, in either direction. that
+    // convergence-to-one-version is the org-standardization intent, not a regression.
+    const tempDir = genTempDir({
+      slug: 'pnpm-ahead-of-pin',
+      clone: './src/practices/pnpm/.test/assets/repo-npm-to-pnpm',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/pnpm/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 pin OFF the blessed version, then apply the practice
+      const seeded = { ...JSON.parse(await readPkg()), packageManager: 'pnpm@10.32.1' };
+      await fs.writeFile(pkgPath(), `${JSON.stringify(seeded, null, 2)}\n`);
+      const pkgBefore = await readPkg();
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      return { pkgBefore, pkgAfter1, pkgAfter2 };
+    }, 170_000);
+
+    when('[t0] the off-pin package.json is applied', () => {
+      then('the pin is rewritten to the blessed 10.34.5', () => {
+        expect(JSON.parse(state.pkgBefore).packageManager).toEqual('pnpm@10.32.1');
+        expect(JSON.parse(state.pkgAfter1).packageManager).toEqual('pnpm@10.34.5');
+      });
+
+      then('a second apply is a fixed point (the convergence holds)', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+  });
+
+  given('[case3] the blessed packageManager pin is a real published version', () => {
+    // a phantom pin (e.g. pnpm@10.31.7, which was never published) 404s corepack on EVERY
+    // pm command in a consumer the moment `declapract fix` applies it — a repo-wide outage,
+    // not a lint nit (#576). so the blessed pin MUST exist on the npm registry. this guard
+    // reads the pin the best-practice ships and puts the question to the registry itself, so
+    // a future bump to an unpublished version reddens HERE rather than in a bricked consumer.
+    // anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different
+    // cwd. from this file (src/practices/pnpm/) the best-practice package.json is one segment down.
+    const bestPracticePkgPath = path.join(
+      __dirname,
+      'best-practice/package.json',
+    );
+
+    when('[t0] the best-practice package.json pin is read', () => {
+      const readPinnedVersion = (): string => {
+        const pkg = JSON.parse(readFileSync(bestPracticePkgPath, 'utf-8'));
+        return asPinnedVersionFromPackageManager(String(pkg.packageManager));
+      };
+
+      then('the pinned pnpm version has a valid semver shape (hermetic, every run)', () => {
+        expect(readPinnedVersion()).toMatch(/^\d+\.\d+\.\d+$/);
+      });
+
+      then('the pinned pnpm version is published on the npm registry (every build)', async () => {
+        // the phantom-pin guard (#576) needs the LIVE registry — only it confirms a pin was
+        // PUBLISHED (a phantom pin parses fine locally, then 404s corepack in every consumer). the
+        // read runs on EVERY build, CI included, per rule.require.external-contract-integration-tests:
+        // an external contract owes a real call, never a silent skip ("either run the real call, or
+        // fail the gate"). the transient-blip hazard rule.forbid.behavior-hazards names is absorbed by
+        // getPublishedVersionFromRegistry's bounded retry-with-backoff (3 attempts) — a brief blip
+        // recovers, a phantom pin fails all 3 and reddens the gate. the read needs no credential (a
+        // public `npm view`), and this repo's CI already reaches the registry to install deps, so a
+        // sustained outage would fail the install too. the shape check above stays hermetic.
+        const pinnedVersion = readPinnedVersion();
+        const published = await getPublishedVersionFromRegistry({
+          packageName: 'pnpm',
+          version: pinnedVersion,
+          attemptsLeft: 3,
+          backoffMs: 500,
+        });
+        expect(published).toContain(pinnedVersion);
+      });
+    });
+  });
+
+  given('[case4] a repo carrying an inert v11 allowBuilds block under the v10 pin', () => {
+    // the fixture's pnpm-workspace.yaml holds ONLY an `allowBuilds:` block — pnpm v11 syntax
+    // under a v10 pin, so it does ZERO work yet reads like a live allowlist (#575). the
+    // inert-build-allowlist bad-practice must DELETE the file (its whole content is the block),
+    // and a re-apply must be a no-op (the file is already gone → no key to detect).
+    const tempDir = genTempDir({
+      slug: 'pnpm-inert-allowbuilds',
+      clone: './src/practices/pnpm/.test/assets/repo-npm-to-pnpm',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/pnpm/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const wsPath = () => path.join(tempDir, 'pnpm-workspace.yaml');
+    const exists = async () =>
+      fs
+        .access(wsPath())
+        .then(() => true)
+        .catch(() => false);
+
+    const state = useBeforeAll(async () => {
+      const before = await fs.readFile(wsPath(), 'utf-8');
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'pnpm-workspace.yaml',
+      });
+      const existsAfter1 = await exists();
+
+      // a re-apply on the now-absent file must be a clean no-op
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'pnpm-workspace.yaml',
+      });
+      const existsAfter2 = await exists();
+
+      return { before, existsAfter1, existsAfter2 };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied to pnpm-workspace.yaml', () => {
+      then('the inert allowBuilds-only file is deleted', () => {
+        expect(state.existsAfter1).toEqual(false);
+      });
+
+      then('before matches snapshot (the inert block that was removed)', () => {
+        expect(state.before).toMatchSnapshot('pnpm-workspace.yaml — before');
+      });
+
+      then('a second apply is a fixed point (absent stays absent)', () => {
+        expect(state.existsAfter2).toEqual(false);
+      });
+    });
+  });
+});

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/.husky/check.lockfile.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'package-lock.json'; then
+  echo "📦 package-lock.json changed. Run 'npm install' to update your locally installed dependencies."
+fi

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/declapract.use.yml

@@ -0,0 +1,7 @@
+# .note = declarations dir is symlinked by the test to test/assets/pnpm/declarations
+# .why  = a repo mid-migration from npm to pnpm, used to prove the pnpm bad-practices
+#         (npm-overrides, husky-lockfile-check) end to end.
+# .note = no variables — the pnpm-repo usecase carries only the pnpm practice, which
+#         references no @declapract{variable.*}.
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "overrides": {
+    "react-refresh": "~0.14.0"
+  },
+  "resolutions": {
+    "react-refresh": "~0.14.0"
+  }
+}

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  node-pty: true

package/dist/practices/pnpm/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,75 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t0] the pnpm practice is applied to package.json then: before + after match snapshot: package.json — after 1`] = `
+"{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "~0.14.0"
+    }
+  }
+}
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t0] the pnpm practice is applied to package.json then: before + after match snapshot: package.json — before 1`] = `
+"{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "overrides": {
+    "react-refresh": "~0.14.0"
+  },
+  "resolutions": {
+    "react-refresh": "~0.14.0"
+  }
+}
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t1] the pnpm practice is applied to the husky hook then: before + after match snapshot: check.lockfile.sh — after 1`] = `
+"#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'pnpm-lock.yaml'; then
+  echo "📦 pnpm-lock.yaml changed. Run 'pnpm install' to update your locally installed dependencies."
+fi
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t1] the pnpm practice is applied to the husky hook then: before + after match snapshot: check.lockfile.sh — before 1`] = `
+"#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'package-lock.json'; then
+  echo "📦 package-lock.json changed. Run 'npm install' to update your locally installed dependencies."
+fi
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case4] a repo carrying an inert v11 allowBuilds block under the v10 pin when: [t0] the pnpm practice is applied to pnpm-workspace.yaml then: before matches snapshot (the inert block that was removed): pnpm-workspace.yaml — before 1`] = `
+"allowBuilds:
+  esbuild: true
+  node-pty: true
+"
+`;

package/dist/practices/pnpm/bad-practices/husky-lockfile-check/.declapract.readme.md

@@ -0,0 +1,17 @@
+# bad-practice: husky-lockfile-check
+
+## .what
+
+a husky hook (`.husky/check.lockfile.sh`) that watches the npm `package-lock.json` for
+changes and points the human at `npm install`.
+
+## .why it is bad under pnpm
+
+a pnpm repo has no `package-lock.json` — its lockfile is `pnpm-lock.yaml`. a hook left on
+the npm name never fires on a real pnpm lockfile change, so the stale-dependencies
+reminder silently dies.
+
+## .the fix
+
+swap `package-lock.json` → `pnpm-lock.yaml` and `npm install` → `pnpm install`. idempotent
+— once swapped, the check no longer detects the npm name.

package/dist/practices/pnpm/bad-practices/husky-lockfile-check/.husky/check.lockfile.sh.declapract.ts

@@ -0,0 +1,28 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects a husky lockfile-change hook that watches the npm `package-lock.json`
+ * .why  = a pnpm repo has no `package-lock.json` — its lockfile is `pnpm-lock.yaml`. a hook
+ *         left on the npm name never fires, so a stale-lockfile reminder silently dies.
+ */
+export const check: FileCheckFunction = (contents) => {
+  // detected (bad practice) when the hook still references the npm lockfile name
+  if (contents?.includes('package-lock.json')) return;
+
+  // not detected — already on pnpm-lock.yaml (or absent)
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = swaps the npm lockfile name + install command for their pnpm equivalents
+ * .why  = the hook must watch `pnpm-lock.yaml` and point the human at `pnpm install`.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const fixed = contents
+    .replace(/package-lock\.json/g, 'pnpm-lock.yaml')
+    // `(?<!p)` guards the overlap: pnpm contains npm, so a naive swap of `npm install`
+    // would nest inside its own `pnpm install` output and loop on a re-run
+    .replace(/(?<!p)npm install/g, 'pnpm install');
+  return { contents: fixed };
+};

package/dist/practices/pnpm/bad-practices/inert-build-allowlist/pnpm-workspace.yaml.declapract.ts

@@ -0,0 +1,59 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects a `pnpm-workspace.yaml` that carries an `allowBuilds:` block and removes it.
+ *         when the block is the file's sole content, the whole file is deleted.
+ * .why  = `allowBuilds:` is pnpm v11 syntax; the pnpm practice pins v10 (`pnpm@10.34.5`), where
+ *         the build allowlist key is `pnpm.onlyBuiltDependencies` (an ARRAY, in package.json).
+ *         so an `allowBuilds:` block under the v10 pin does ZERO work — yet it READS like a live
+ *         allowlist, the exact trap #575 / ehmpathy/rhachet#475 burned an hour on.
+ * .note = the fix is DELETE, not a boolean-fill and not a fail-loud stub. (1) rhachet retired the
+ *         manual allowlist step ("by subtraction"); declapract emits no allowlist to converge to.
+ *         (2) a real allowlist is repo-specific (the v10 `pnpm.onlyBuiltDependencies` array the
+ *         repo adds itself). an inert block does no work, so its removal cannot regress a build.
+ * .note = idempotent — after fix the key is gone, check no longer detects it, re-run is a no-op.
+ */
+const ALLOW_BUILDS_KEY = /^allowBuilds:/;
+
+/** a yaml child line: whitespace-indented, then non-whitespace (the block's nested entries). */
+const isIndentedChild = (line: string): boolean => /^\s+\S/.test(line);
+
+/**
+ * strip the `allowBuilds:` key line + its contiguous indented child lines. a pure fold over the
+ * lines with an immutable `{ inBlock, kept }` accumulator (no `let`, no in-place push): the key
+ * line opens the block (and is dropped), each indented child is dropped while open, and the first
+ * non-indented (or blank) line closes the block and is kept. handles more than one block, since a
+ * later key line simply re-opens.
+ */
+const stripAllowBuildsBlock = (contents: string): string =>
+  contents
+    .split('\n')
+    .reduce<{ inBlock: boolean; kept: string[] }>(
+      (acc, line) => {
+        // the key line opens the block and is itself dropped
+        if (ALLOW_BUILDS_KEY.test(line))
+          return { inBlock: true, kept: acc.kept };
+        // an indented child of an open block is dropped
+        if (acc.inBlock && isIndentedChild(line)) return acc;
+        // any non-indented (or blank) line closes the block and is kept
+        return { inBlock: false, kept: [...acc.kept, line] };
+      },
+      { inBlock: false, kept: [] },
+    )
+    .kept.join('\n');
+
+const hasAllowBuilds = (contents: string): boolean =>
+  contents.split('\n').some((line) => ALLOW_BUILDS_KEY.test(line));
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents === null) throw new Error('does not match bad practice');
+  if (!hasAllowBuilds(contents)) throw new Error('does not match bad practice');
+  return;
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+  const stripped = stripAllowBuildsBlock(contents);
+  if (stripped.trim() === '') return { contents: null };
+  return { contents: stripped };
+};

package/dist/practices/pnpm/bad-practices/npm-overrides/.declapract.readme.md

@@ -0,0 +1,20 @@
+# bad-practice: npm-overrides
+
+## .what
+
+a package.json that keeps its dependency pins under a top-level `overrides` (npm) or
+`resolutions` (yarn) key.
+
+## .why it is bad under pnpm
+
+pnpm reads **neither** `overrides` nor `resolutions` — it reads `pnpm.overrides`. a repo
+migrated from npm/yarn that leaves its pins under the old keys silently loses them. under
+the hoisted linker (flat `node_modules`) that lets a mismatched transitive version hoist
+over the intended one — the skew hazard documented in
+`.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+
+## .the fix
+
+relocate both top-level keys into `pnpm.overrides` and drop them. on a key collision the
+precedence is: npm `overrides` beats yarn `resolutions` beats any pre-extant
+`pnpm.overrides`. idempotent — once relocated, the check no longer detects the pattern.

package/dist/practices/pnpm/bad-practices/npm-overrides/package.json.declapract.ts

@@ -0,0 +1,75 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = detects a top-level `overrides` (npm) or `resolutions` (yarn) key in package.json
+ * .why  = pnpm reads NEITHER — it reads `pnpm.overrides`. a repo migrated to pnpm that keeps
+ *         its pins under the npm/yarn keys silently loses them, which lets a mismatched
+ *         transitive version hoist over the intended one (the flat-linker skew hazard). see
+ *         `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  const packageJSON = JSON.parse(contents ?? '{}');
+
+  // detected (bad practice) when either npm-`overrides` or yarn-`resolutions` sits at top level
+  if (
+    packageJSON.overrides !== undefined ||
+    packageJSON.resolutions !== undefined
+  )
+    return;
+
+  // not detected — already pnpm-shaped (or no pins at all)
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = relocates top-level `overrides` + `resolutions` into `pnpm.overrides`, then drops them
+ * .why  = pnpm reads only `pnpm.overrides`. precedence on a key conflict: npm `overrides` wins over
+ *         yarn `resolutions` over any pre-extant `pnpm.overrides`.
+ *
+ * .note = handles the FLAT override shape (`{ "pkg": "1.2.3" }`). npm ALSO supports a NESTED
+ *         per-dependency form (`{ "foo": { ".": "1.0.0", "bar": "2.0.0" } }`) that pnpm's flat-only
+ *         `pnpm.overrides` cannot express. this fix does NOT silently emit such a shape (a config
+ *         pnpm rejects — a failhide); it FAILS FAST with a `ConstraintError` that names the at-fault
+ *         key and the fix, per `rule.forbid.failhide` / `rule.require.failfast`. a consumer with
+ *         nested npm overrides must flatten them by hand.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = JSON.parse(contents);
+
+  // merge — npm `overrides` beats yarn `resolutions` beats any extant `pnpm.overrides`
+  const mergedOverrides = {
+    ...(packageJSON.pnpm?.overrides ?? {}),
+    ...(packageJSON.resolutions ?? {}),
+    ...(packageJSON.overrides ?? {}),
+  };
+
+  // fail fast on a nested per-dependency override — pnpm's flat `pnpm.overrides` cannot express it,
+  // so a pass-through would emit a config pnpm rejects (a silent failhide). name the fix.
+  const nestedKeys = Object.entries(mergedOverrides)
+    .filter(([, value]) => typeof value !== 'string')
+    .map(([key]) => key);
+  if (nestedKeys.length)
+    throw new ConstraintError(
+      'cannot migrate a NESTED npm override to pnpm — flatten it by hand first',
+      {
+        nestedKeys,
+        hint: `pnpm's \`pnpm.overrides\` is flat-only ({ "pkg": "1.2.3" }). the nested per-dependency form ({ ".": "...", "dep": "..." }) has no pnpm equivalent. flatten these keys to a single version string each, then re-run: ${nestedKeys.join(', ')}`,
+      },
+    );
+
+  // exclude the npm/yarn keys via destructure (no in-place delete), keep every other key
+  const {
+    overrides: _npmOverrides,
+    resolutions: _yarnResolutions,
+    ...packageJSONRest
+  } = packageJSON;
+
+  const updatedPackageJSON = {
+    ...packageJSONRest,
+    pnpm: { ...(packageJSON.pnpm ?? {}), overrides: mergedOverrides },
+  };
+
+  return { contents: `${JSON.stringify(updatedPackageJSON, null, 2)}\n` };
+};