declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.declapract.integration.test.ts

@@ -0,0 +1,95 @@
+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 ahbode-standard-lambda-handler test-file migration, run through
+ *   the REAL declapract apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = the fix moves a handler test off the nonpublished `promiseLambdaInvocation` and onto
+ *   `runLambdaEndpoint.onReferenced(...).then(asLambdaEndpointOutput)` in one apply (#650) — a
+ *   transform, so per rule.require.declapract-integration-tests it owes a pipeline test. a unit
+ *   test of the exported `fix` never exercises the `src/contract/handlers/*.integration.test.ts`
+ *   glob -> file match, nor the CONTAINS check that gates the fix.
+ */
+describe('ahbode-standard-lambda-handler test-file migration', () => {
+  given('[case1] a repo whose handler test calls promiseLambdaInvocation', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-ahbode-standard-lambda-handler',
+      clone: './src/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/nonpublished-modules/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/contract/handlers/getWidget.integration.test.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'nonpublished-modules',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the handler test imports + calls promiseLambdaInvocation + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain('__nonpublished_modules__/ahbode-standard-lambda-handler');
+        expect(before).toContain('promiseLambdaInvocation(');
+        expect(before).not.toContain('runLambdaEndpoint');
+        expect(before).toMatchSnapshot('getWidget.integration.test.ts — before');
+      });
+    });
+
+    when('[t1] the ahbode-standard-lambda-handler fix is applied', () => {
+      useThen('migrate the handler test', async () => applyMigrate());
+
+      then(
+        'the test lands on runLambdaEndpoint.onReferenced in one apply, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the nonpublished module and the retired successor are both gone
+          expect(after).not.toContain('__nonpublished_modules__');
+          expect(after).not.toContain('promiseLambdaInvocation');
+          expect(after).not.toContain('simple-lambda-testing-methods');
+
+          // the sdk import + the onReferenced call land, output unwrapped by asLambdaEndpointOutput
+          expect(after).toContain(
+            "import { asLambdaEndpointOutput, runLambdaEndpoint } from 'sdk-aws-lambda';",
+          );
+          expect(after).toContain('runLambdaEndpoint.onReferenced(');
+          expect(after).toContain('.then(asLambdaEndpointOutput)');
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('getWidget.integration.test.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // post-rewrite the file no longer CONTAINS the nonpublished import line, so the check no
+      // longer detects the bad practice — the second apply changes zero bytes
+      // (rule.require.idempotent-fixes)
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = await read(targetPath); // post-first-migrate
+        await applyMigrate(); // second apply
+        const after = await read(targetPath);
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/declapract.use.yml

@@ -0,0 +1,5 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/nonpublished-modules symlink to the real practice), so the consumer's own src/
+#         tree stays free to hold the target handler test the glob matches.
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/src/contract/handlers/getWidget.integration.test.ts

@@ -0,0 +1,18 @@
+import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';
+import { given, then, when } from 'test-fns';
+
+import { handler } from './getWidget';
+
+describe('getWidget', () => {
+  given('[case1] a widget uuid', () => {
+    when('[t0] the handler is invoked', () => {
+      then('it responds', async () => {
+        const response = await promiseLambdaInvocation({
+          event: { widgetUuid: 'w-1' },
+          handler,
+        });
+        expect(response).toBeDefined();
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`ahbode-standard-lambda-handler test-file migration given: [case1] a repo whose handler test calls promiseLambdaInvocation when: [t0] the migration input (before any fix) then: the handler test imports + calls promiseLambdaInvocation + matches snapshot: getWidget.integration.test.ts — before 1`] = `
+"import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';
+import { given, then, when } from 'test-fns';
+
+import { handler } from './getWidget';
+
+describe('getWidget', () => {
+  given('[case1] a widget uuid', () => {
+    when('[t0] the handler is invoked', () => {
+      then('it responds', async () => {
+        const response = await promiseLambdaInvocation({
+          event: { widgetUuid: 'w-1' },
+          handler,
+        });
+        expect(response).toBeDefined();
+      });
+    });
+  });
+});
+"
+`;
+
+exports[`ahbode-standard-lambda-handler test-file migration given: [case1] a repo whose handler test calls promiseLambdaInvocation when: [t1] the ahbode-standard-lambda-handler fix is applied then: the test lands on runLambdaEndpoint.onReferenced in one apply, and it matches snapshot: getWidget.integration.test.ts — after 1`] = `
+"import { asLambdaEndpointOutput, runLambdaEndpoint } from 'sdk-aws-lambda';
+import { given, then, when } from 'test-fns';
+
+import { handler } from './getWidget';
+
+describe('getWidget', () => {
+  given('[case1] a widget uuid', () => {
+    when('[t0] the handler is invoked', () => {
+      then('it responds', async () => {
+        const response = await runLambdaEndpoint.onReferenced({
+          event: { widgetUuid: 'w-1' },
+          handler,
+        }).then(asLambdaEndpointOutput);
+        expect(response).toBeDefined();
+      });
+    });
+  });
+});
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.integration.test.ts.declapract.ts

@@ -1,15 +1,25 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
 
+import { asSourceOnRunLambdaEndpoint } from '../../../../../../../utils/asSourceOnRunLambdaEndpoint';
+
 export const check = FileCheckType.CONTAINS;
 
+/**
+ * .what = move `promiseLambdaInvocation` off the nonpublished module, onto
+ *         `runLambdaEndpoint.onReferenced(...).then(asLambdaEndpointOutput)`
+ * .why  = the old successor, simple-lambda-testing-methods, is retired (#650); the move lands on
+ *         sdk-aws-lambda in one apply, so an adopter never passes through the retired lib
+ */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};
   return {
-    contents: contents
-      .replace(
-        `import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';`,
-        `import { invokeHandlerForTesting } from 'simple-lambda-testing-methods';`,
-      )
-      .replace(/promiseLambdaInvocation/g, 'invokeHandlerForTesting'),
+    contents: asSourceOnRunLambdaEndpoint({
+      contents: contents
+        .replace(
+          `import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';`,
+          `import { invokeHandlerForTesting } from 'simple-lambda-testing-methods';`,
+        )
+        .replace(/promiseLambdaInvocation/g, 'invokeHandlerForTesting'),
+    }),
   };
 };

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

@@ -0,0 +1,100 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the package-json-order fix, run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo whose package.json holds its root keys,
+ *   its scripts, and its dependencies out of the declared order.
+ * .why  = the fix re-sorts keys of parsed json, and the declaration ships NO template — so the
+ *   global fix-coverage harness only feeds it `fix(null)`, which proves naught about the sort. a
+ *   unit test of the transformer is necessary but NOT sufficient
+ *   (`rule.require.declapract-integration-tests`): only the pipeline proves declapract matches the
+ *   declaration to the consumer's package.json, that a best-practice `check` that THROWS gates the
+ *   `fix`, and that a second apply is a no-op on the real file.
+ */
+describe('package-json-order sort', () => {
+  given('[case1] a repo whose package.json keys are out of order', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-package-json-order',
+      clone:
+        './src/practices/package-json-order/.test/assets/demo-repo-with-unordered-keys',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    const pkgPath = 'package.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'package-json-order',
+        file: pkgPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the package.json input matches snapshot', async () => {
+        expect(await read(pkgPath)).toMatchSnapshot('package.json — before');
+      });
+    });
+
+    when('[t1] the package-json-order fix is applied', () => {
+      const result = useThen('the apply succeeds', async () => {
+        await applyFix();
+        const contents = await read(pkgPath);
+        return { contents, pkg: JSON.parse(contents) };
+      });
+
+      then('the root keys follow the declared relative order', () => {
+        expect(Object.keys(result.pkg)).toEqual([
+          'name',
+          'author',
+          'version',
+          'scripts',
+          'dependencies',
+          'devDependencies',
+        ]);
+      });
+
+      then('the declared scripts follow the declared relative order', () => {
+        const declared = Object.keys(result.pkg.scripts).filter((key) =>
+          ['build', 'test:unit', 'test'].includes(key),
+        );
+        expect(declared).toEqual(['build', 'test:unit', 'test']);
+      });
+
+      then('the undeclared script is kept, with its value untouched', () => {
+        expect(result.pkg.scripts['custom:task']).toEqual('echo custom');
+      });
+
+      then('the dependencies and devDependencies are alphabetical', () => {
+        expect(Object.keys(result.pkg.dependencies)).toEqual([
+          'domain-objects',
+          'uuid',
+        ]);
+        expect(Object.keys(result.pkg.devDependencies)).toEqual([
+          'jest',
+          'typescript',
+        ]);
+      });
+
+      then('the package.json matches snapshot', () => {
+        expect(result.contents).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const result = useThen('a second apply over its own output', async () => {
+        const before = await read(pkgPath);
+        await applyFix();
+        return { before, after: await read(pkgPath) };
+      });
+
+      then('the second apply changes zero bytes', () => {
+        expect(result.after).toEqual(result.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/package-json-order/.test/assets/demo-repo-with-unordered-keys/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: declarations/examples
+  practices: declarations/practices
+  use-cases: declarations/useCases.yml

package/dist/.test/assets/expo-fullusecase/declarations/practices/package-json-order/.test/assets/demo-repo-with-unordered-keys/declapract.use.yml

@@ -0,0 +1,9 @@
+declarations: './'
+useCase: lambda-service
+# executeApply({ practice: 'package-json-order' }) evaluates the WHOLE practice before the `file`
+# filter narrows it (rule.require.declapract-integration-tests gotcha). no package-json-order file
+# references a @declapract{variable.*} today; the two below are the usecase's baseline, set so a
+# future template that adds one does not break this apply with `Variable … was not defined`.
+variables:
+  projectName: svc-example
+  organizationName: ehmpathy

package/dist/.test/assets/expo-fullusecase/declarations/practices/package-json-order/.test/assets/demo-repo-with-unordered-keys/package.json

@@ -0,0 +1,19 @@
+{
+  "version": "1.0.0",
+  "devDependencies": {
+    "typescript": "5.4.5",
+    "jest": "29.3.1"
+  },
+  "scripts": {
+    "test": "npm run test:unit",
+    "custom:task": "echo custom",
+    "build": "tsc",
+    "test:unit": "jest"
+  },
+  "name": "svc-example",
+  "dependencies": {
+    "uuid": "9.0.0",
+    "domain-objects": "0.31.0"
+  },
+  "author": "ehmpathy"
+}

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

@@ -0,0 +1,47 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`package-json-order sort given: [case1] a repo whose package.json keys are out of order when: [t0] the input (before any fix) then: the package.json input matches snapshot: package.json — before 1`] = `
+"{
+  "version": "1.0.0",
+  "devDependencies": {
+    "typescript": "5.4.5",
+    "jest": "29.3.1"
+  },
+  "scripts": {
+    "test": "npm run test:unit",
+    "custom:task": "echo custom",
+    "build": "tsc",
+    "test:unit": "jest"
+  },
+  "name": "svc-example",
+  "dependencies": {
+    "uuid": "9.0.0",
+    "domain-objects": "0.31.0"
+  },
+  "author": "ehmpathy"
+}
+"
+`;
+
+exports[`package-json-order sort given: [case1] a repo whose package.json keys are out of order when: [t1] the package-json-order fix is applied then: the package.json matches snapshot: package.json — after 1`] = `
+"{
+  "name": "svc-example",
+  "author": "ehmpathy",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc",
+    "test:unit": "jest",
+    "test": "npm run test:unit",
+    "custom:task": "echo custom"
+  },
+  "dependencies": {
+    "domain-objects": "0.31.0",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "jest": "29.3.1",
+    "typescript": "5.4.5"
+  }
+}
+"
+`;

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

@@ -26,7 +26,6 @@ export const desiredRelativeKeyOrder = {
     'commit:with-cli',
     'fix:format:biome',
     'fix:format:prettier',
-    'fix:format:terraform',
     'fix:format',
     'fix:deps',
     'fix:eslint',
@@ -44,6 +43,7 @@ export const desiredRelativeKeyOrder = {
     'build:compile:tsc',
     'build:compile',
     'build',
+    'build:ifstale',
     'provision:schema:plan',
     'provision:schema:apply',
     'provision:schema:sync',
@@ -59,7 +59,6 @@ export const desiredRelativeKeyOrder = {
     'test:commits',
     'test:types',
     'test:format:prettier',
-    'test:format:terraform',
     'test:format:biome',
     'test:format',
     'test:lint:deps',

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