declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/persist-with-rds/testdb-per-worktree.declapract.integration.test.ts

@@ -0,0 +1,332 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, useBeforeAll } from 'test-fns';
+
+import { getTestdbIdentity } from './best-practice/src/.test/assets/database/getTestdbIdentity';
+import { getTestdbPort } from './best-practice/src/.test/assets/database/getTestdbPort';
+
+/**
+ * .what = proves each worktree of a repo gets a testdb of its own (#674): its own compose
+ *         project, container, and host port, while ci and a main checkout keep port 7821
+ * .why = two worktrees that share one testdb read and clobber each other's rows, and a
+ *        `start:testdb` in one stops the other's db mid-run
+ * .teeth = drop the worktree branch from getTestdbIdentity and case2 reddens; route a compose
+ *          command around compose.sh, or pin the compose port, and case5 reddens; read the port
+ *          straight off the config in a reader, or import a testdb test asset from a prod path,
+ *          and case5 reddens
+ * .note = getTestdbIdentity and getTestdbPort are test assets (`src/.test/assets/database/`): the
+ *         app never imports them, it reads the TESTDB_PORT the test harness declares
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it runs git and bash in temp repos
+ */
+
+jest.setTimeout(5 * 60 * 1000);
+
+const BEST_PRACTICE_DIR = join(__dirname, 'best-practice');
+const REPO_NODE_MODULES = join(__dirname, '../../../node_modules');
+const PORT_DECLARED = 7821;
+const ENV_LOCAL = { ...process.env, CI: '' };
+
+/**
+ * .what = run git in a dir, with an author so a commit needs no global config
+ */
+const runGit = (input: { cwd: string; args: string[] }): string =>
+  execFileSync(
+    'git',
+    [
+      '-c',
+      'user.name=surfer',
+      '-c',
+      'user.email=surfer@example.com',
+      ...input.args,
+    ],
+    { cwd: input.cwd, encoding: 'utf8' },
+  );
+
+/**
+ * .what = a temp repo with one commit, plus two linked worktrees of it
+ */
+const genRepoWithWorktrees = (input: {
+  slug: string;
+  files: Record<string, string>;
+}): { main: string; worktreeA: string; worktreeB: string } => {
+  const root = genTempDir({ slug: input.slug });
+  const main = join(root, 'main');
+  mkdirSync(main, { recursive: true });
+  Object.entries(input.files).forEach(([path, source]) => {
+    mkdirSync(join(main, path, '..'), { recursive: true });
+    writeFileSync(join(main, path), source);
+  });
+  runGit({ cwd: main, args: ['init', '-q', '-b', 'main'] });
+  runGit({ cwd: main, args: ['add', '-A'] });
+  runGit({ cwd: main, args: ['commit', '-q', '--allow-empty', '-m', 'init'] });
+  const worktreeA = join(root, 'worktree-a');
+  const worktreeB = join(root, 'worktree-b');
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'a', worktreeA] });
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'b', worktreeB] });
+  return { main, worktreeA, worktreeB };
+};
+
+describe('persist-with-rds testdb per worktree (#674)', () => {
+  given('[case1] a main checkout', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-main', files: {} }),
+    );
+
+    then('it keeps the declared port and no suffix, as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.main, env: ENV_LOCAL },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case2] two linked worktrees of one repo', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-linked',
+        files: {},
+      });
+      return {
+        a: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        aAgain: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        b: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeB, env: ENV_LOCAL },
+        ),
+      };
+    });
+
+    then('each derives a suffix of its own', () => {
+      expect(scene.a.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.b.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.a.suffix).not.toEqual(scene.b.suffix);
+    });
+
+    then('each binds a port of its own, never the declared one', () => {
+      [scene.a.port, scene.b.port].forEach((port) => {
+        expect(port).toBeGreaterThan(PORT_DECLARED);
+        expect(port).toBeLessThan(PORT_DECLARED + 1000);
+      });
+      expect(scene.a.port).not.toEqual(scene.b.port);
+    });
+
+    then('a worktree lands on the same identity every time', () => {
+      expect(scene.aAgain).toEqual(scene.a);
+    });
+  });
+
+  given('[case3] a linked worktree in ci', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-ci', files: {} }),
+    );
+
+    then('it keeps the declared port, so ci behaves as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: { ...process.env, CI: 'true' } },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case4] a reader asks for its port', () => {
+    then('an access other than test keeps its declared port', () => {
+      expect(getTestdbPort({ access: 'prep', portDeclared: 5432 })).toEqual(
+        5432,
+      );
+    });
+
+    then('test access dials the identity this checkout derives', () => {
+      expect(
+        getTestdbPort({ access: 'test', portDeclared: PORT_DECLARED }),
+      ).toEqual(getTestdbIdentity({ portDeclared: PORT_DECLARED }).port);
+    });
+  });
+
+  given('[case5] the shipped templates', () => {
+    const read = (path: string) =>
+      readFileSync(join(BEST_PRACTICE_DIR, path), 'utf8');
+
+    then('the compose project, container, and port take the derived values', () => {
+      const compose = read('provision/docker/testdb/docker-compose.yml');
+      expect(compose).toContain(
+        'name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain(
+        'container_name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain('- ${TESTDB_PORT:-7821}:5432');
+      expect(compose).not.toContain('- 7821:5432');
+    });
+
+    then('every compose command goes through compose.sh', () => {
+      const commands: string[] = Object.values(
+        JSON.parse(read('package.json')).scripts,
+      );
+      expect(
+        commands.filter((command) => command.includes('docker compose')),
+      ).toEqual([]);
+      expect(
+        commands.filter((command) =>
+          command.includes('bash provision/docker/testdb/compose.sh'),
+        ).length,
+      ).toBeGreaterThanOrEqual(4);
+    });
+
+    then('the app dials the TESTDB_PORT override, never the test asset', () => {
+      const factory = read('src/utils/database/getOneDatabaseConnection.ts');
+      expect(factory).toContain('getOneDatabasePort({');
+      expect(factory).not.toContain('getTestdbPort');
+      expect(factory).not.toContain('.test/');
+    });
+
+    then('the schema provisioner dials getTestdbPort, from the test assets', () => {
+      const config = read('provision/schema/connection.config.js');
+      expect(config).toContain('getTestdbPort({');
+      expect(config).toContain(
+        "require('../../src/.test/assets/database/getTestdbPort')",
+      );
+    });
+
+    then('no prod path under src/ imports a testdb test asset', () => {
+      const prodImporters = readdirSync(join(BEST_PRACTICE_DIR, 'src/utils'), {
+        recursive: true,
+      })
+        .map((entry) => entry.toString())
+        .filter((path) => path.endsWith('.ts') && !path.endsWith('.test.ts'))
+        .filter((path) =>
+          /getTestdb(Port|Identity)|\.test\/assets/.test(
+            read(join('src/utils', path)),
+          ),
+        );
+      expect(prodImporters).toEqual([]);
+    });
+  });
+
+  given('[case6] compose.sh, run in a linked worktree', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts': readFileSync(
+            join(BEST_PRACTICE_DIR, 'src/.test/assets/database/getTestdbIdentity.ts'),
+            'utf8',
+          ),
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports what compose would have received
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(
+        join(bin, 'docker'),
+        '#!/usr/bin/env bash\necho "suffix=$TESTDB_SUFFIX port=$TESTDB_PORT args=$*"\n',
+      );
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      const identity = getTestdbIdentity(
+        { portDeclared: PORT_DECLARED },
+        { cwd: repo.worktreeA, env: ENV_LOCAL },
+      );
+      return { result, identity, worktree: realpathSync(repo.worktreeA) };
+    });
+
+    then('it exits 0', () => {
+      expect(scene.result.stderr).toEqual('');
+      expect(scene.result.status).toEqual(0);
+    });
+
+    then('docker compose receives the worktree identity and the args', () => {
+      expect(scene.result.stdout.trim()).toEqual(
+        `suffix=${scene.identity.suffix} port=${scene.identity.port} args=compose -f ${scene.worktree}/provision/docker/testdb/docker-compose.yml up -d`,
+      );
+    });
+  });
+
+  given('[case7] compose.sh, where the identity util yields a malformed port', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose-malformed',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts':
+            "export const getTestdbIdentity = (_input: { portDeclared: number }) => ({ suffix: '-abc123', port: Number.NaN });\n",
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports any call it receives
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(join(bin, 'docker'), '#!/usr/bin/env bash\necho "docker called"\n');
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      return { result };
+    });
+
+    then('it halts with exit 1 and names the malformed identity', () => {
+      expect(scene.result.status).toEqual(1);
+      expect(scene.result.stderr).toContain(
+        "💥 MalfunctionError: getTestdbIdentity yielded '-abc123 NaN'",
+      );
+    });
+
+    then('docker compose is never called', () => {
+      expect(scene.result.stdout).not.toContain('docker called');
+    });
+  });
+});

package/dist/practices/persist-with-rds/with-connection-in-input.declapract.integration.test.ts

@@ -0,0 +1,97 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the with-connection-in-input fix on a real repo (#626).
+ * .why  = the prior declaration was an EXISTS check with no fix, so an apply could not repair it and
+ *   named no replacement. the src declaration now stamps the input→context review line above each
+ *   import and definition of withDatabaseConnection, and never deletes the wrapper its callers need.
+ * .note = the declarations isolate this one bad-practice (a persist-with-rds practice that holds only
+ *   it), so the test owes none of the practice's variables.
+ */
+describe('persist-with-rds with-connection-in-input', () => {
+  given('[case1] a repo whose op imports withDatabaseConnection', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rds-connection-in-input',
+      clone:
+        './src/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/persist-with-rds-connection-in-input/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const opPath = 'src/domain.operations/findSurferById.ts';
+    const wrapperPath = 'src/utils/database/withDatabaseConnection.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyOne = (input: { file: string }) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'persist-with-rds',
+        file: input.file,
+      });
+    const applyFix = async () => {
+      await applyOne({ file: opPath });
+      await applyOne({ file: wrapperPath });
+    };
+
+    when('[t0] the input (before any fix)', () => {
+      then('both src files match snapshot', async () => {
+        expect(await read(opPath)).toMatchSnapshot('op — before');
+        expect(await read(wrapperPath)).toMatchSnapshot('wrapper — before');
+      });
+    });
+
+    when('[t1] the fix is applied', () => {
+      const after = useThen('apply', async () => {
+        const before = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        await applyFix();
+        return { before, op: await read(opPath), wrapper: await read(wrapperPath) };
+      });
+
+      then('the op gains one review line above its import, which names withDatabaseContext', () => {
+        const markers = after.op
+          .split('\n')
+          .filter((line) => line.includes('@declapract:review:'));
+        expect(markers).toHaveLength(1);
+        expect(markers[0]).toContain('withDatabaseContext');
+        expect(markers[0]).toContain('(input, context)');
+        expect(after.op.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.op,
+        );
+        expect(after.op).toMatchSnapshot('op — after');
+      });
+
+      then('the wrapper stays in place, marked, so the tree still builds', () => {
+        expect(after.wrapper).toContain('export const withDatabaseConnection');
+        expect(after.wrapper.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.wrapper,
+        );
+        expect(after.wrapper).toMatchSnapshot('wrapper — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        await applyFix();
+        const after = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/pnpm/.test/assets/repo-stale-patch/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/pnpm/declarations
+# .why  = a repo with one patch the lockfile moved past and one it still resolves (#680)
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/practices/pnpm/.test/assets/repo-stale-patch/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "repo-stale-patch",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}

package/dist/practices/pnpm/.test/assets/repo-stale-patch/patches/rhachet-roles-ehmpathy@1.39.1.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/practices/pnpm/.test/assets/repo-stale-patch/patches/type-fns@1.21.3.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/practices/pnpm/.test/assets/repo-stale-patch/pnpm-lock.yaml

@@ -0,0 +1,19 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+packages:
+
+  rhachet-roles-ehmpathy@1.40.0:
+    resolution: {integrity: sha512-a}
+
+  type-fns@1.21.3:
+    resolution: {integrity: sha512-b}
+
+snapshots:
+
+  rhachet-roles-ehmpathy@1.40.0: {}
+
+  type-fns@1.21.3: {}

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

@@ -13,7 +13,9 @@ exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migrat
   "pnpm": {
     "overrides": {
       "react-refresh": "~0.14.0"
-    }
+    },
+    "allowUnusedPatches": true,
+    "ignorePatchFailures": true
   }
 }
 "

package/dist/practices/pnpm/__snapshots__/stale-patched-dependency.declapract.integration.test.ts.snap

@@ -0,0 +1,38 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`pnpm — a stale patch never blocks an install given: [case1] a repo with one patch the lockfile moved past and one it still resolves when: [t0] the pnpm practice is applied then: the before + after contents match snapshot: package.json — after 1`] = `
+"{
+  "name": "repo-stale-patch",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    },
+    "allowUnusedPatches": true,
+    "ignorePatchFailures": true
+  }
+}
+"
+`;
+
+exports[`pnpm — a stale patch never blocks an install given: [case1] a repo with one patch the lockfile moved past and one it still resolves when: [t0] the pnpm practice is applied then: the before + after contents match snapshot: package.json — before 1`] = `
+"{
+  "name": "repo-stale-patch",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}
+"
+`;

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

@@ -6,8 +6,15 @@ import type { FileCheckFunction, FileFixFunction } from 'declapract';
  *         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;
+  // detected (bad practice) when the hook watches the npm lockfile and not the pnpm one.
+  // the husky template watches both, so a hook that already watches pnpm-lock.yaml is the
+  // husky shape; a swap of its npm block would duplicate the pnpm block, and husky's check
+  // would restore it on the next apply, so the two practices would never converge
+  if (
+    contents?.includes('package-lock.json') &&
+    !contents.includes('pnpm-lock.yaml')
+  )
+    return;
 
   // not detected — already on pnpm-lock.yaml (or absent)
   throw new Error('does not match bad practice');

package/dist/practices/pnpm/bad-practices/override-undercuts-dependency/.declapract.readme.md

@@ -0,0 +1,5 @@
+a `pnpm.overrides` entry below the version the repo declares for that same package.
+
+pnpm installs the override, never the dependency it shadows. so a floor check that reads
+`dependencies` reads green while the tree runs the lower copy. the fix raises each such override to
+the declared version; every other override is kept.

package/dist/practices/pnpm/bad-practices/override-undercuts-dependency/package.json.declapract.ts

@@ -0,0 +1,67 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+import { isVersionBelowFloor } from '../../../../utils/isVersionBelowFloor';
+
+const PRACTICE = 'pnpm/override-undercuts-dependency';
+
+/**
+ * .what = each `pnpm.overrides` key whose version sits below the version the repo itself declares
+ *         for that package, paired with the declared version it must rise to.
+ * .why  = pnpm installs the override, never the dependency it shadows. a floor check reads the
+ *         dependency, so an override below it reads green while the tree runs the lower copy
+ *         (#624). an override is usually added to settle a contention by someone with no floor in
+ *         mind, so the louder its reason, the quieter the loss.
+ * .note = only a plain package-name key is judged; a selector key (`foo@1>bar`) or a non-numeric
+ *         value (`$foo`, `-`, `link:…`) cannot be compared, so it is never flagged.
+ */
+const getUndercutOverrides = (input: {
+  packageJSON: Record<string, any>;
+}): Array<{ name: string; declared: string }> => {
+  const overrides: Record<string, unknown> =
+    input.packageJSON.pnpm?.overrides ?? {};
+  const declaredOf = (name: string): string | undefined =>
+    input.packageJSON.dependencies?.[name] ??
+    input.packageJSON.devDependencies?.[name];
+  return Object.entries(overrides).flatMap(([name, override]) => {
+    const declared = declaredOf(name);
+    if (typeof override !== 'string' || !declared) return [];
+    return isVersionBelowFloor({ version: override, floor: declared })
+      ? [{ name, declared }]
+      : [];
+  });
+};
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents)
+    throw new Error('does not match bad practice: package.json absent');
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  if (getUndercutOverrides({ packageJSON }).length > 0) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no pnpm.overrides entry sits below its declared dependency',
+  );
+};
+
+/**
+ * .what = raise each undercut override to the version the repo declares for that package.
+ * .why  = so the version a floor check reads is the version pnpm installs. every other override
+ *         and key is kept as-is.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const raised = Object.fromEntries(
+    getUndercutOverrides({ packageJSON }).map(({ name, declared }) => [
+      name,
+      declared,
+    ]),
+  );
+  const updated = {
+    ...packageJSON,
+    pnpm: {
+      ...packageJSON.pnpm,
+      overrides: { ...packageJSON.pnpm?.overrides, ...raised },
+    },
+  };
+  return { contents: JSON.stringify(updated, null, 2) };
+};

package/dist/practices/pnpm/bad-practices/stale-patched-dependency/.declapract.readme.md

@@ -0,0 +1,22 @@
+# bad-practice: stale-patched-dependency
+
+## .what
+
+a `pnpm.patchedDependencies` entry (and its `patches/<name>@<version>.patch` file) whose pinned
+version the lockfile no longer resolves.
+
+## .why it is bad
+
+a patch pins one exact version. the next upgrade of that dependency orphans it: the patch
+applies to no install. without `pnpm.allowUnusedPatches` pnpm refuses the whole install
+(`ERR_PNPM_UNUSED_PATCH`); with it, pnpm warns on every install. either way the patch is dead
+weight that a human must notice and retire by hand.
+
+## .the fix
+
+drop each stale key from `pnpm.patchedDependencies` (and an empty map left behind), and delete
+the patch file. the verdict keys off the lockfile-resolved version, so:
+
+- no `pnpm-lock.yaml` → no verdict; no patch is judged stale
+- a range key (`name@^1.0.0`) or a bare name key (`name`) → never judged stale
+- the fix is a fixed point: once the stale keys are gone, the check no longer detects the pattern