declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.declapract.integration.test.ts

@@ -0,0 +1,103 @@
+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 simple-lambda-handlers migration, run through the REAL declapract
+ *   apply pipeline against a genTempDir clone of a consumer repo. per
+ *   rule.require.declapract-integration-tests, a fix that TRANSFORMS a file (regex rewrite + a
+ *   value-rewrite @declapract:review marker) owes a pipeline test — a unit test of the exported
+ *   `fix` never exercises the source-file glob -> file match, nor that the marker lands on disk.
+ * .why = the fix rewrites the `simple-lambda-handlers` import to `sdk-aws-lambda` and prepends a
+ *   loud @declapract:review marker, because the schema+invoke CONTRACT differs between the two
+ *   frameworks and a rename-only migration answers 400 to every request yet typechecks (#594). the
+ *   marker names the two manual edits rather than let a regex guess the contract.
+ * .note = the target file is snapshotted in full (before AND after), so a reviewer can eyeball the
+ *   exact end-state, per rule.require.declapract-integration-tests.
+ * .teeth = the input imports + CALLS `createApiGatewayHandler`. the after-state proves the import is
+ *   rewritten to `sdk-aws-lambda`, the call is rewritten to `genLambdaEndpoint.for.apiGateway`, and
+ *   the @declapract:review marker lands on disk — the glue a mocked-context unit test cannot show.
+ */
+describe('simple-lambda-handlers migration', () => {
+  given('[case1] a repo with a simple-lambda-handlers api-gateway handler', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-simple-lambda-handlers',
+      clone: './src/practices/node-service/bad-practices/simple-lambda-handlers/.test/assets/demo-repo-with-simple-lambda-handlers',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/node-service/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/contract/handlers/getWidget.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'node-service',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the src file imports + calls the simple-lambda-handlers factory + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain("from 'simple-lambda-handlers'");
+        expect(before).toContain('createApiGatewayHandler(');
+        expect(before).not.toContain('@declapract:review');
+        expect(before).toMatchSnapshot('getWidget.ts — before');
+      });
+    });
+
+    when('[t1] the simple-lambda-handlers fix is applied', () => {
+      useThen('migrate the handler import + call', async () => applyMigrate());
+
+      then(
+        'the import + call are rewritten to sdk-aws-lambda, the review marker lands, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the import is rewritten to the sdk
+          expect(after).toContain("from 'sdk-aws-lambda'");
+          expect(after).not.toContain("from 'simple-lambda-handlers'");
+
+          // the api-gateway factory call is rewritten to its sdk equivalent
+          expect(after).toContain('genLambdaEndpoint.for.apiGateway(');
+          expect(after).not.toContain('createApiGatewayHandler(');
+
+          // the value-rewrite marker lands on disk — the un-rewritable schema+invoke contract
+          // is loud, so a consumer cannot ship a handler that answers 400 to every request
+          expect(after).toContain('@declapract:review');
+          expect(after).toContain('rawEvent');
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('getWidget.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // post-rewrite the file imports from sdk-aws-lambda, so the check no longer detects the bad
+      // practice and the fix does not run — the second apply changes zero bytes, and the marker is
+      // never double-prepended (per 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/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.declapract.readme.md

@@ -0,0 +1,60 @@
+# simple-lambda-handlers
+
+## what
+
+detects and transforms simple-lambda-handlers usage to sdk-aws-lambda.
+
+## why
+
+sdk-aws-lambda provides modern lambda handler patterns:
+- better schema validation with zod (input + output)
+- log context passed to invoke function
+- trail.exid auto-propagation
+
+## transforms
+
+| old | new |
+|-----|-----|
+| `import { createStandardHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
+| `import { createApiGatewayHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
+| `createStandardHandler(...)` | `genLambdaEndpoint(...)` |
+| `createApiGatewayHandler(...)` | `genLambdaEndpoint.for.apiGateway(...)` |
+
+## limitations
+
+these patterns require manual migration:
+
+- `schema` (single joi) → `schema: { input, output }` (split zod)
+- `logic: (event) => O` → `invoke: ({ event }, { log }) => O`
+- `log` passed at creation → `log` also received in invoke context
+
+the contract differs in a way a regex cannot get right: the prior framework's schema described the
+WHOLE event, while sdk-aws-lambda's input schema describes the request BODY (the handler then reads
+headers off a separate `rawEvent`). a rename-only rewrite answers 400 to every request yet
+typechecks. so a handler CALL now carries a `@declapract:review` marker that names the two manual
+edits (unwrap the `body` key into the input schema; thread headers via `rawEvent.headers`). the
+codemod does NOT guess the contract — it flags it loud, and the consumer deletes the marker once the
+call is restructured (#594).
+
+## example
+
+before:
+```ts
+import { createStandardHandler } from 'simple-lambda-handlers';
+
+export const handler = createStandardHandler({
+  log,
+  schema,
+  logic: async (event) => doStuff(event),
+});
+```
+
+after (requires manual refinement):
+```ts
+import { genLambdaEndpoint } from 'sdk-aws-lambda';
+
+export const handler = genLambdaEndpoint({
+  schema: { input: inputSchema, output: outputSchema },
+  invoke: async ({ event }, { log }) => doStuff(event),
+}, { log });
+```

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.test/assets/demo-repo-with-simple-lambda-handlers/declapract.use.yml

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

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.test/assets/demo-repo-with-simple-lambda-handlers/package.json

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

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.test/assets/demo-repo-with-simple-lambda-handlers/src/contract/handlers/getWidget.ts

@@ -0,0 +1,13 @@
+import { createApiGatewayHandler } from 'simple-lambda-handlers';
+
+import { log } from '../../utils/logger';
+import { getWidgetSchema } from './getWidget.schema';
+
+// an api-gateway handler CALL — the schema+invoke contract differs between the two
+// frameworks, so the fix cannot rename-only; it must emit a loud review marker.
+export const handler = createApiGatewayHandler({
+  log,
+  schema: getWidgetSchema,
+  logic: async (event) => ({ widget: event.widgetId }),
+  cors: true,
+});

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,44 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`simple-lambda-handlers migration given: [case1] a repo with a simple-lambda-handlers api-gateway handler when: [t0] the migration input (before any fix) then: the src file imports + calls the simple-lambda-handlers factory + matches snapshot: getWidget.ts — before 1`] = `
+"import { createApiGatewayHandler } from 'simple-lambda-handlers';
+
+import { log } from '../../utils/logger';
+import { getWidgetSchema } from './getWidget.schema';
+
+// an api-gateway handler CALL — the schema+invoke contract differs between the two
+// frameworks, so the fix cannot rename-only; it must emit a loud review marker.
+export const handler = createApiGatewayHandler({
+  log,
+  schema: getWidgetSchema,
+  logic: async (event) => ({ widget: event.widgetId }),
+  cors: true,
+});
+"
+`;
+
+exports[`simple-lambda-handlers migration given: [case1] a repo with a simple-lambda-handlers api-gateway handler when: [t1] the simple-lambda-handlers fix is applied then: the import + call are rewritten to sdk-aws-lambda, the review marker lands, and it matches snapshot: getWidget.ts — after 1`] = `
+"/**
+ * @declapract:review — auto-migrated to sdk-aws-lambda; the api-gateway handler CONTRACT differs
+ * and MUST be restructured by hand (a rename-only migration answers 400 to every request):
+ *  - schema: the prior single schema described the WHOLE event; the sdk input schema describes the
+ *    request BODY only. split into \`schema: { input, output }\` and unwrap the \`body\` key.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event, rawEvent }) => O\`. \`event\` is
+ *    the parsed body; thread headers through \`rawEvent.headers\`.
+ * delete this marker once restructured.
+ */
+import { genLambdaEndpoint } from 'sdk-aws-lambda';
+
+import { log } from '../../utils/logger';
+import { getWidgetSchema } from './getWidget.schema';
+
+// an api-gateway handler CALL — the schema+invoke contract differs between the two
+// frameworks, so the fix cannot rename-only; it must emit a loud review marker.
+export const handler = genLambdaEndpoint.for.apiGateway({
+  log,
+  schema: getWidgetSchema,
+  logic: async (event) => ({ widget: event.widgetId }),
+  cors: true,
+});
+"
+`;

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "simple-lambda-handlers": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts

@@ -0,0 +1,27 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+/**
+ * .what = removes simple-lambda-handlers and adds sdk-aws-lambda
+ * .why = sdk-aws-lambda is the modern replacement with better patterns
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = JSON.parse(contents);
+
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: {
+      ...packageJSON.dependencies,
+      'simple-lambda-handlers': undefined,
+      'sdk-aws-lambda':
+        packageJSON.dependencies?.['sdk-aws-lambda'] ?? '^0.1.0',
+    },
+  };
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,130 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects simple-lambda-handlers imports in source files
+ * .why = simple-lambda-handlers should be replaced with sdk-aws-lambda
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match if file imports from simple-lambda-handlers
+  if (contents?.includes("from 'simple-lambda-handlers'")) return;
+  if (contents?.includes('from "simple-lambda-handlers"')) return;
+
+  // no match
+  throw new Error('does not import from simple-lambda-handlers');
+};
+
+/**
+ * .what = a loud marker for an api-gateway handler call, whose schema+invoke CONTRACT differs
+ *         between the two frameworks and cannot be mechanically rewritten.
+ * .why = the prior framework's schema described the WHOLE event and the handler received the whole
+ *        event; the sdk's input schema describes the request BODY and the handler receives the
+ *        parsed body plus a separate rawEvent. a rename-only rewrite leaves a handler that answers
+ *        400 to every request, yet typechecks (#594). the marker flags the two manual edits rather
+ *        than let a regex guess the contract.
+ */
+const apiGatewayReviewMarker = `/**
+ * @declapract:review — auto-migrated to sdk-aws-lambda; the api-gateway handler CONTRACT differs
+ * and MUST be restructured by hand (a rename-only migration answers 400 to every request):
+ *  - schema: the prior single schema described the WHOLE event; the sdk input schema describes the
+ *    request BODY only. split into \`schema: { input, output }\` and unwrap the \`body\` key.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event, rawEvent }) => O\`. \`event\` is
+ *    the parsed body; thread headers through \`rawEvent.headers\`.
+ * delete this marker once restructured.
+ */
+`;
+
+/**
+ * .what = a loud marker for a standard handler call, whose schema+invoke shape also differs.
+ * .why = the rename does not restructure the args; the sdk splits the schema and passes log in the
+ *        invoke context. the marker flags the manual edits (#594).
+ */
+const standardReviewMarker = `/**
+ * @declapract:review — auto-migrated to sdk-aws-lambda; the handler CONTRACT differs and MUST be
+ * restructured by hand:
+ *  - schema: the prior single schema splits into \`schema: { input, output }\`.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event }, { log }) => O\`; \`log\` is now
+ *    received in the invoke context, not only at creation.
+ * delete this marker once restructured.
+ */
+`;
+
+/**
+ * .what = parse a comma-separated import clause into its trimmed import names
+ * .why = names the split/trim parse, so the fix orchestrator reads as narrative rather than
+ *        an inline array-manipulation chain (rule.forbid.inline-decode-friction)
+ */
+const asImportNames = (input: { clause: string }): string[] =>
+  input.clause.split(',').map((name) => name.trim());
+
+/**
+ * .what = map one simple-lambda-handlers import name to its sdk-aws-lambda equivalent
+ * .why = both handler-factory names collapse onto `genLambdaEndpoint`; the named map keeps the
+ *        fix orchestrator narrative rather than an inline conditional (rule.forbid.inline-decode-friction)
+ */
+const asTransformedImportName = (input: { name: string }): string => {
+  if (input.name === 'createStandardHandler') return 'genLambdaEndpoint';
+  if (input.name === 'createApiGatewayHandler') return 'genLambdaEndpoint';
+  return input.name;
+};
+
+/**
+ * .what = dedupe import names, first-seen order retained
+ * .why = the two handler factories both map to `genLambdaEndpoint`, so a clause that imports both
+ *        would emit a duplicate; the named dedupe hides the Set semantics from the orchestrator
+ */
+const asDedupedImportNames = (input: { names: string[] }): string[] => [
+  ...new Set(input.names),
+];
+
+/**
+ * .what = transforms simple-lambda-handlers imports to sdk-aws-lambda, with a review marker
+ * .why = automated migration reduces manual toil, but the schema+invoke contract cannot be
+ *        mechanically rewritten — so a handler CALL gets a @declapract:review marker that names the
+ *        manual edits, rather than a silent rename that answers 400 to every request (#594).
+ *
+ * .note = basic transforms only; complex patterns require manual fix
+ *
+ * API map:
+ * - createStandardHandler → genLambdaEndpoint
+ * - createApiGatewayHandler → genLambdaEndpoint.for.apiGateway
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  // detect a handler CALL (name + paren) on the ORIGINAL contents, before the rename
+  const hasApiGatewayCall = /createApiGatewayHandler\s*\(/.test(contents);
+  const hasStandardCall = /createStandardHandler\s*\(/.test(contents);
+
+  const transformed = contents
+    // transform imports (dedupe to avoid duplicate genLambdaEndpoint)
+    .replace(
+      /import\s+\{([^}]*)\}\s+from\s+['"]simple-lambda-handlers['"]/g,
+      (match, imports) => {
+        // split, replace, dedupe, join
+        const importNames = asImportNames({ clause: imports });
+        const mapped = importNames.map((name) =>
+          asTransformedImportName({ name }),
+        );
+        const deduped = asDedupedImportNames({ names: mapped });
+        return `import { ${deduped.join(', ')} } from 'sdk-aws-lambda'`;
+      },
+    )
+    // transform function calls
+    .replace(/createStandardHandler/g, 'genLambdaEndpoint')
+    .replace(/createApiGatewayHandler/g, 'genLambdaEndpoint.for.apiGateway');
+
+  // prepend the review marker for a handler CALL (api-gateway takes precedence), so the
+  // un-rewritable schema+invoke contract is loud. idempotent: the check no longer fires
+  // post-rewrite, and a second pass would find the marker already present.
+  const marker = hasApiGatewayCall
+    ? apiGatewayReviewMarker
+    : hasStandardCall
+      ? standardReviewMarker
+      : '';
+  const updated =
+    marker && !transformed.includes('@declapract:review')
+      ? marker + transformed
+      : transformed;
+
+  return { contents: updated };
+};

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

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "dependencies": {
+    "sdk-aws-lambda": "@declapract{check.minVersion('0.4.0')}"
+  }
+}

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

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

package/dist/.test/assets/node-service/declarations/useCases.yml

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

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

@@ -1,4 +1,6 @@
 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';
@@ -7,6 +9,52 @@ 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
@@ -87,7 +135,7 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
 
       then('the packageManager pin survives (best-practice no-op)', () => {
         const pkg = JSON.parse(state.pkgAfter1);
-        expect(pkg.packageManager).toEqual('pnpm@10.31.7');
+        expect(pkg.packageManager).toEqual('pnpm@10.34.5');
       });
 
       then('before + after match snapshot', () => {
@@ -119,14 +167,14 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
     });
   });
 
-  given('[case2] a repo AHEAD of the blessed pnpm pin (10.32.1)', () => {
-    // the [case1] fixture seeds the pin already AT 10.31.7, so it proves only the no-op
-    // path. this case seeds the pin AHEAD of the blessed version to prove the DOWNGRADE
-    // rewrite (10.32.1 → 10.31.7) in pnpm's OWN suite — where an engineer looks first —
+  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.31.7`, so `declapract fix`
-    // merges the blessed pin over the ahead one. that convergence-to-one-version is the
-    // org-standardization intent, not a regression.
+    // 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',
@@ -140,7 +188,7 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
     const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
 
     const state = useBeforeAll(async () => {
-      // seed the pin AHEAD of the blessed version, then apply the practice
+      // 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();
@@ -161,15 +209,117 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
       return { pkgBefore, pkgAfter1, pkgAfter2 };
     }, 170_000);
 
-    when('[t0] the ahead-of-pin package.json is applied', () => {
-      then('the pin is rewritten DOWN to the blessed 10.31.7', () => {
+    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.31.7');
+        expect(JSON.parse(state.pkgAfter1).packageManager).toEqual('pnpm@10.34.5');
       });
 
-      then('a second apply is a fixed point (the downgrade converges)', () => {
+      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/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-npm-to-pnpm/package.json

@@ -1,7 +1,7 @@
 {
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",

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

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