declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/assets/nonpublished-modules/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/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.integration.test.ts

@@ -0,0 +1 @@
+import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';

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

@@ -0,0 +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: 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/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.ts

@@ -0,0 +1 @@
+import { createStandardHandler } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';

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

@@ -0,0 +1,13 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents.replace(
+      `import { createStandardHandler } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';`,
+      `import { createStandardHandler } from 'simple-lambda-handlers';`,
+    ),
+  };
+};

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/deep-omit/.declapract.readme.md

@@ -0,0 +1 @@
+was replaced with `domain-objects#omitAutogeneratedValues`

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/__nonpublished_modules__/deep-omit/<star><star>/<star>.ts.declapract.ts

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

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/data/dao/<star><star>/<star>.integration.test.ts

@@ -0,0 +1 @@
+import { deepOmit } from '../../../__nonpublished_modules__/deep-omit';

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/data/dao/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,18 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(
+        `import { deepOmit } from '../../../__nonpublished_modules__/deep-omit';`,
+        `import { omitAutogeneratedValues } from 'domain-objects';`,
+      )
+      .replace(
+        /deepOmit\(([\w|!|?|.]+), \[[\w'", ]+\]\)/g,
+        'omitAutogeneratedValues($1)',
+      ),
+  };
+};

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/simple-dynamodb-client/.declapract.readme.md

@@ -0,0 +1 @@
+was published under `simple-dynamodb-client` package

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/simple-dynamodb-client/src/__nonpublished_modules__/simple-dynamodb-client/<star><star>/<star>.ts.declapract.ts

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

package/dist/.test/assets/nonpublished-modules/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the nonpublished-modules practice integration test
+use-cases:
+  lambda-service:
+    practices:
+      - nonpublished-modules

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# declarations that isolate the with-connection-in-input bad-practice, so the test needs no persist-with-rds variables
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.declapract.readme.md

@@ -0,0 +1,10 @@
+withDatabaseConnection -> withDatabaseContext, per procedure-fns pattern
+
+`withDatabaseConnection` took `dbConnection` in the input. `withDatabaseContext`
+(`src/utils/database/withDatabaseContext.ts`, shipped by the best-practice) takes it in the context:
+each op becomes `(input, context) => …`, and each caller passes the context as the 2nd arg.
+
+the move changes each op and each caller, so the fix does not rewrite code. it stamps a
+`// @declapract:review:` line above each import or definition of `withDatabaseConnection` that names
+the move, and leaves the extant wrapper in place so the tree still builds. delete the marker, and
+then the wrapper, once its last caller moves.

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/package.json

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

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/domain.operations/findSurferById.ts

@@ -0,0 +1,9 @@
+import { DatabaseConnection } from '../utils/database/getDatabaseConnection';
+import {
+  withDatabaseConnection,
+} from '../utils/database/withDatabaseConnection';
+
+export const findSurferById = withDatabaseConnection(
+  async ({ id, dbConnection }: { id: string; dbConnection: DatabaseConnection }) =>
+    dbConnection.query({ sql: 'select * from surfer where id = :id', values: { id } }),
+);

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/utils/database/withDatabaseConnection.ts

@@ -0,0 +1,10 @@
+import { DatabaseConnection, getDatabaseConnection } from './getDatabaseConnection';
+
+export const withDatabaseConnection =
+  <I extends { dbConnection: DatabaseConnection }, O>(
+    logic: (input: I) => Promise<O>,
+  ) =>
+  async (input: Omit<I, 'dbConnection'>): Promise<O> => {
+    const dbConnection = await getDatabaseConnection();
+    return logic({ ...input, dbConnection } as I);
+  };

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,55 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asInputToContextReviewMarker } from '../../../../../../utils/asInputToContextReviewMarker';
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = a line that imports, re-exports, or defines the retired `withDatabaseConnection`.
+ * .why  = a multi-line import names the module only on its `from` line, so the module path is
+ *         matched too; one marker per import statement either way.
+ */
+const WITH_DATABASE_CONNECTION_LINE_PATTERN =
+  /(?:^\s*import\b[^\n]*\bwithDatabaseConnection\b|^\s*export\s+(?:const|function)\s+withDatabaseConnection\b|\bfrom\s+['"][^'"]*\/withDatabaseConnection['"])/;
+
+const REVIEW_MARKER = asInputToContextReviewMarker({
+  from: 'withDatabaseConnection (dbConnection in the input)',
+  into: 'withDatabaseContext (src/utils/database/withDatabaseContext.ts)',
+});
+
+/**
+ * .what = flags a src file that imports or defines `withDatabaseConnection`.
+ * .why  = the practice replaced it with `withDatabaseContext`; the prior declaration was an EXISTS
+ *         check with no fix, so an apply failed with no pointer to the replacement and each call
+ *         site broke the build (#626). this check names each file by path in `plan`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents
+      ?.split('\n')
+      .some((line) => WITH_DATABASE_CONNECTION_LINE_PATTERN.test(line))
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no import or definition of withDatabaseConnection',
+  );
+};
+
+/**
+ * .what = stamps the shared input→context review line above each such import or definition.
+ * .why  = each op moves `dbConnection` from its input into a context arg, and each caller passes
+ *         it as the 2nd arg — a shape change a regex cannot make safely — so the fix names the
+ *         move beside the line, and never deletes the extant wrapper (its callers still need it).
+ * .note = idempotent; the check stays red until a human moves the ops, so `plan` keeps it in view.
+ * .note = an absent file is left absent: every fix must settle on absent input, a contract the
+ *         repo-wide fix-coverage sweep holds (`practiceFixCoverage`, #607)
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: WITH_DATABASE_CONNECTION_LINE_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/.test/assets/persist-with-rds-connection-in-input/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the with-connection-in-input integration test
+use-cases:
+  lambda-service:
+    practices:
+      - persist-with-rds

package/dist/.test/assets/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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/pnpm/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

package/dist/.test/assets/pnpm/declarations/practices/pnpm/bad-practices/stale-patched-dependency/package.json.declapract.ts

@@ -0,0 +1,74 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+import { getAllStalePatchKeys } from '../../../../utils/getAllStalePatchKeys';
+import { getFileTextOrNull } from '../../../../utils/getFileTextOrNull';
+
+const PRACTICE = 'pnpm/stale-patched-dependency';
+
+/**
+ * .what = the repo's pnpm lockfile, or null when it has none
+ */
+const getLockfile = (input: { root: string }): string | null =>
+  getFileTextOrNull({ root: input.root, relativePath: 'pnpm-lock.yaml' });
+
+/**
+ * .what = detects a package.json whose `pnpm.patchedDependencies` pins a version the lockfile no
+ *         longer resolves (#680)
+ * .why  = such a patch applies to no install: pnpm warns on it (under `allowUnusedPatches`) or
+ *         refuses the install (without it). the patch is dead weight a human must retire by hand
+ * .note = bad-practice semantics: a RETURN means detected, a THROW means not detected
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('does not match bad practice');
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const keys = getAllStalePatchKeys({
+    patchedDependencies: packageJSON.pnpm?.patchedDependencies ?? {},
+    lockfile: getLockfile({ root: context.getProjectRootDirectory() }),
+  });
+  if (keys.length) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = drops each stale patch key, and an empty map or pnpm block left behind
+ * .why  = the patch file itself is deleted by the `patches/` declaration beside this one
+ * .note = a fixed point: once the stale keys are gone, the check no longer detects the pattern
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return {};
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const patchedDependencies: Record<string, string> =
+    packageJSON.pnpm?.patchedDependencies ?? {};
+  const keysStale = getAllStalePatchKeys({
+    patchedDependencies,
+    lockfile: getLockfile({ root: context.getProjectRootDirectory() }),
+  });
+  if (!keysStale.length) return { contents };
+
+  // the map without the stale keys
+  const patchedKept = Object.fromEntries(
+    Object.entries(patchedDependencies).filter(
+      ([key]) => !keysStale.includes(key),
+    ),
+  );
+
+  // an empty map is dropped, and so is an empty pnpm block
+  const pnpmKept = {
+    ...packageJSON.pnpm,
+    patchedDependencies: Object.keys(patchedKept).length
+      ? patchedKept
+      : undefined,
+  };
+  const pnpmHasKeys = Object.values(pnpmKept).some(
+    (value) => value !== undefined,
+  );
+
+  return {
+    contents: `${JSON.stringify(
+      { ...packageJSON, pnpm: pnpmHasKeys ? pnpmKept : undefined },
+      null,
+      2,
+    )}\n`,
+  };
+};

package/dist/.test/assets/pnpm/declarations/practices/pnpm/bad-practices/stale-patched-dependency/patches/<star>.patch.declapract.ts

@@ -0,0 +1,41 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import path from 'node:path';
+import { getAllStalePatchKeys } from '../../../../../utils/getAllStalePatchKeys';
+import { getFileTextOrNull } from '../../../../../utils/getFileTextOrNull';
+
+/**
+ * .what = the `pnpm.patchedDependencies` key a patch file stands for, from its path
+ * .why  = pnpm names a patch `<name>@<version>.patch`, with a scope slash encoded as `__`
+ */
+const asPatchKey = (input: { relativeFilePath: string }): string =>
+  path
+    .basename(input.relativeFilePath)
+    .replace(/\.patch$/, '')
+    .replace(/^(@[^_]+)__/, '$1/');
+
+/**
+ * .what = detects a patch file whose pinned version the lockfile no longer resolves (#680)
+ * .why  = the patch applies to no install; its key is retired by the package.json declaration
+ *         beside this one, and the file goes with it
+ * .note = bad-practice semantics: a RETURN means detected, a THROW means not detected
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (contents === null) throw new Error('does not match bad practice');
+  const lockfile = getFileTextOrNull({
+    root: context.getProjectRootDirectory(),
+    relativePath: 'pnpm-lock.yaml',
+  });
+  const key = asPatchKey({ relativeFilePath: context.relativeFilePath });
+  const keysStale = getAllStalePatchKeys({
+    patchedDependencies: { [key]: context.relativeFilePath },
+    lockfile,
+  });
+  if (keysStale.length) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = deletes the stale patch file
+ */
+export const fix: FileFixFunction = () => ({ contents: null });

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

@@ -1,3 +1,7 @@
 {
-  "packageManager": "pnpm@10.34.5"
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "allowUnusedPatches": true,
+    "ignorePatchFailures": true
+  }
 }

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

@@ -13,5 +13,12 @@ import { FileCheckType } from 'declapract';
  * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
  *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
  *         the org bumps the blessed version, this pin bumps and every consumer follows.
+ * .what = also declares `pnpm.allowUnusedPatches` + `pnpm.ignorePatchFailures` (#680).
+ * .why  = a patch pins one exact version; the next upgrade orphans it, and pnpm then refuses the
+ *         whole install (`ERR_PNPM_UNUSED_PATCH`, `ERR_PNPM_PATCH_FAILED`). both keys turn that
+ *         refusal into a warn, so patch-then-upgrade never halts an install. a repo with no patch
+ *         gets them too, so its first patch is already safe to upgrade past. the CONTAINS fix
+ *         deep-merges, so a repo's other `pnpm.*` keys (overrides, patchedDependencies, the build
+ *         allowlist) are kept.
  */
 export const check = FileCheckType.CONTAINS;