declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/expo-migration/declarations/practices/git/best-practice/.gitattributes.declapract.ts

@@ -53,41 +53,56 @@ const ALL_PRIOR_ENTRIES = SECTIONS.flatMap((s) => s.entries.priors);
  */
 const ALL_PRIOR_HEADERS = SECTIONS.flatMap((s) => s.header.priors);
 
+/**
+ * .what = drops prior headers + prior entries, and dedupes latest entries (keep first)
+ * .why = the fix must not re-emit a legacy line, nor a second copy of a managed entry;
+ *        a named transform keeps cleanContent a narrative of what happens, not how
+ */
+const asLinesWithLegacyDroppedAndDeduped = (input: {
+  lines: string[];
+}): string[] => {
+  const { lines } = input.lines.reduce<{
+    lines: string[];
+    seen: Set<string>;
+  }>(
+    (acc, line) => {
+      const trimmed = line.trim();
+
+      // skip prior headers + prior entries
+      if (ALL_PRIOR_HEADERS.includes(trimmed)) return acc;
+      if (ALL_PRIOR_ENTRIES.includes(trimmed)) return acc;
+
+      // skip duplicate latest entries (keep first occurrence)
+      if (ALL_LATEST_ENTRIES.includes(trimmed)) {
+        if (acc.seen.has(trimmed)) return acc;
+        return {
+          lines: [...acc.lines, line],
+          seen: new Set([...acc.seen, trimmed]),
+        };
+      }
+
+      return { lines: [...acc.lines, line], seen: acc.seen };
+    },
+    { lines: [], seen: new Set<string>() },
+  );
+  return lines;
+};
+
 /**
  * removes legacy headers, duplicate entries, and cleans up empty lines
  */
 const cleanContent = (content: string): string => {
-  const lines = content.split('\n');
-  const seenEntries = new Set<string>();
-  const cleanedLines: string[] = [];
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // skip prior headers
-    if (ALL_PRIOR_HEADERS.includes(trimmed)) continue;
+  // drop legacy headers, legacy entries, and duplicate latest entries (keep first)
+  const cleanedLines = asLinesWithLegacyDroppedAndDeduped({
+    lines: content.split('\n'),
+  });
 
-    // skip prior entries
-    if (ALL_PRIOR_ENTRIES.includes(trimmed)) continue;
-
-    // skip duplicate latest entries (keep first occurrence)
-    if (ALL_LATEST_ENTRIES.includes(trimmed)) {
-      if (seenEntries.has(trimmed)) continue;
-      seenEntries.add(trimmed);
-    }
-
-    cleanedLines.push(line);
-  }
-
-  // collapse multiple consecutive empty lines into one
-  const collapsedLines: string[] = [];
-  let prevWasEmpty = false;
-  for (const line of cleanedLines) {
+  // collapse multiple consecutive empty lines into one (drop an empty that follows an empty)
+  const collapsedLines = cleanedLines.filter((line, index) => {
     const isEmpty = line.trim() === '';
-    if (isEmpty && prevWasEmpty) continue;
-    collapsedLines.push(line);
-    prevWasEmpty = isEmpty;
-  }
+    const prevWasEmpty = index > 0 && cleanedLines[index - 1]!.trim() === '';
+    return !(isEmpty && prevWasEmpty);
+  });
 
   return collapsedLines.join('\n').trim();
 };
@@ -146,14 +161,12 @@ export const fix: FileFixFunction = (contents) => {
     return { contents: allSections + '\n' };
   }
 
-  // clean up legacy headers and duplicates first
-  let result = cleanContent(contents);
-
-  // ensure each section exists
-  for (const section of SECTIONS) {
-    result = ensureSection(result, section);
-  }
+  // clean up legacy headers and duplicates, then ensure each section exists
+  const result = SECTIONS.reduce(
+    (acc, section) => ensureSection(acc, section),
+    cleanContent(contents),
+  );
 
-  // normalize to exactly one final newline
+  // trim to exactly one final newline
   return { contents: result.trimEnd() + '\n' };
 };

package/dist/.test/assets/expo-migration/declarations/practices/git/best-practice/.gitignore.declapract.ts

@@ -30,6 +30,14 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
  *         place. `readonly` forbids that mutation outright rather than merely discourages it
  *         (`rule.prefer.prevent-over-correct`), so the source may group lines by what they are
  *         for, with their comments beside them, and the one sort that matters stays in one place.
+ *
+ * .note = every line here governs an UNTRACKED path only. git consults `.gitignore` for a path
+ *         not yet in the index; a path a consumer ALREADY tracks stays tracked, and this
+ *         declaration cannot reach the index to reconcile it (the `fix` is a pure contents
+ *         transform, so it has no seam to the index). so a consumer that committed a match
+ *         BEFORE this practice declared the pattern keeps it committed, silently, behind a line
+ *         that reads as enforcement. to reconcile an extant match, run `git rm --cached <path>`
+ *         by hand. a loud in-consumer report of that case is a proposed follow-on (#582).
  */
 const ignoresSortable: readonly string[] = [
   '*.log',

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/.declapract.integration.test.ts

@@ -0,0 +1,102 @@
+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 node/self-deps-not-link fix, run through the REAL declapract
+ *   apply pipeline against a genTempDir clone of a consumer repo whose package.json lists its OWN
+ *   name as a self-dependency at a real version (`1.2.3`, not `link:.`) across three dep sections
+ *   (#571, repo-rules r1). the fixture spans all three cases the fix must get right at once:
+ *     - `dependencies.svc-example: 1.2.3`      → a bad self-dep in a section with a peer → dropped, section kept
+ *     - `devDependencies.svc-example: link:.`  → the CORRECT self-link → preserved untouched
+ *     - `peerDependencies.svc-example: 1.2.3`  → a bad self-dep as the SOLE entry → dropped, empty section pruned
+ * .why  = the fix is a `FileFixFunction` that transforms structured json (drops each bad self-dep,
+ *   prunes any dep object it empties). a unit test of the transformer is necessary but NOT sufficient
+ *   (`rule.require.declapract-integration-tests`): only the pipeline proves declapract wires the
+ *   declaration up (glob→package.json match), that a bad-practice `check` that RETURNS gates the
+ *   `fix`, and that the consumer's `declapract apply` produces the claimed end-state on a real file.
+ * .teeth = revert the fix to a no-op (or drop the empty-section prune) and the after-state asserts
+ *   redden — the bad self-dep survives, or the emptied `peerDependencies` lingers. flip the fixture's
+ *   `devDependencies` entry off `link:.` and the preserve assert reddens.
+ * .note = the package.json is snapshotted in full (before AND after) so a reviewer eyeballs the exact
+ *   end-state (`rule.require.snapshots`). the scoped apply runs the WHOLE `node` practice (the `file`
+ *   filter narrows which file is written, not which declarers evaluate), so the after-state COMPOSES
+ *   two declarers: the self-deps-not-link transform (drops each bad self-dep) AND the node
+ *   best-practice package.json — a CONTAINS check whose merge-fix stamps the declared
+ *   author/repository/homepage/bugs/scripts fields. both are visible in the after-snapshot; the
+ *   assertions above target only the self-deps transform, which is what this bad-practice owns.
+ */
+describe('node/self-deps-not-link removal', () => {
+  given('[case1] a repo with its own name as a self-dep across three dep sections', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-node-self-deps-not-link',
+      clone: './src/practices/node/bad-practices/self-deps-not-link/.test/assets/demo-repo-with-self-deps',
+      symlink: [{ at: 'src', 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: 'node',
+        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 self-deps-not-link fix is applied', () => {
+      useThen('drop each bad self-dep, keep the link:. self-dep', async () =>
+        applyFix(),
+      );
+
+      then(
+        'the bad self-deps are gone, the link:. self-dep survives, the emptied section is pruned, and it matches snapshot',
+        async () => {
+          const pkg = JSON.parse(await read(pkgPath));
+          // the bad self-dep (a real version, not link:.) is dropped from dependencies
+          expect(pkg.dependencies?.['svc-example']).toBeUndefined();
+          // ...but the section survives because a peer dep remains in it
+          expect(pkg.dependencies?.uuid).toEqual('9.0.0');
+          // the CORRECT self-link (`link:.`) is preserved untouched — it is not a bad self-dep
+          expect(pkg.devDependencies?.['svc-example']).toEqual('link:.');
+          expect(pkg.devDependencies?.jest).toEqual('29.3.1');
+          // peerDependencies held ONLY the bad self-dep, so the drop empties + prunes the section
+          expect(pkg.peerDependencies).toBeUndefined();
+          // full content, for the reviewer's eye
+          expect(await read(pkgPath)).toMatchSnapshot('package.json — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // .note = once the bad self-deps are gone, the only self-dep left is the `link:.` in
+      //   devDependencies, which the bad-practice `check` does NOT detect — so the second apply
+      //   fires no fix and the file is a FIXED POINT. we assert the end-state holds rather than
+      //   full-file byte equality, because the node best-practice package.json is a separate
+      //   declarer (a CONTAINS check, out of scope here) whose behavior is not under test.
+      const pkg = useThen('a second apply over its own output', async () => {
+        await applyFix(); // second apply, over the post-first-fix output
+        return JSON.parse(await read(pkgPath));
+      });
+
+      then('the bad self-deps stay gone and the link:. self-dep stays', () => {
+        expect(pkg.dependencies?.['svc-example']).toBeUndefined();
+        expect(pkg.peerDependencies).toBeUndefined();
+        expect(pkg.devDependencies?.['svc-example']).toEqual('link:.');
+      });
+
+      then('the peer deps that remain are untouched by the re-apply', () => {
+        expect(pkg.dependencies?.uuid).toEqual('9.0.0');
+        expect(pkg.devDependencies?.jest).toEqual('29.3.1');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/.test/assets/demo-repo-with-self-deps/declapract.declare.yml

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

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/.test/assets/demo-repo-with-self-deps/declapract.use.yml

@@ -0,0 +1,8 @@
+declarations: './'
+useCase: lambda-service
+# executeApply({ practice: 'node' }) evaluates the WHOLE node practice before the `file` filter
+# narrows it, so every @declapract{variable.*} any node file references must be defined here
+# (rule.require.declapract-integration-tests gotcha). node/best-practice references these two.
+variables:
+  projectName: svc-example
+  organizationName: ehmpathy

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/.test/assets/demo-repo-with-self-deps/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "dependencies": {
+    "svc-example": "1.2.3",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "svc-example": "link:.",
+    "jest": "29.3.1"
+  },
+  "peerDependencies": {
+    "svc-example": "1.2.3"
+  }
+}

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,46 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`node/self-deps-not-link removal given: [case1] a repo with its own name as a self-dep across three dep sections when: [t0] the input (before any fix) then: the package.json input matches snapshot: package.json — before 1`] = `
+"{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "dependencies": {
+    "svc-example": "1.2.3",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "svc-example": "link:.",
+    "jest": "29.3.1"
+  },
+  "peerDependencies": {
+    "svc-example": "1.2.3"
+  }
+}
+"
+`;
+
+exports[`node/self-deps-not-link removal given: [case1] a repo with its own name as a self-dep across three dep sections when: [t1] the self-deps-not-link fix is applied then: the bad self-deps are gone, the link:. self-dep survives, the emptied section is pruned, and it matches snapshot: package.json — after 1`] = `
+"{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "dependencies": {
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "svc-example": "link:.",
+    "jest": "29.3.1"
+  },
+  "author": "ehmpathy",
+  "repository": "ehmpathy/svc-example",
+  "homepage": "https://github.com/ehmpathy/svc-example",
+  "bugs": "https://github.com/ehmpathy/svc-example/issues",
+  "scripts": {
+    "fix": "npm run fix:format && npm run fix:lint",
+    "prepare": "if [ -e .git ] && [ -z \\"\${CI:-}\\" ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
+    "prepush": "npm run test && npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify"
+  }
+}
+"
+`;

package/dist/.test/assets/expo-migration/declarations/practices/node/bad-practices/self-deps-not-link/package.json.declapract.ts

@@ -16,19 +16,13 @@ const findBadSelfDeps = (
   const packageName = packageJson.name as string | undefined;
   if (!packageName) return [];
 
-  const badSelfDeps: { depKey: string; version: string }[] = [];
-
-  for (const depKey of DEP_KEYS) {
+  return DEP_KEYS.flatMap((depKey) => {
     const deps = packageJson[depKey] as Record<string, string> | undefined;
-    if (!deps) continue;
-
-    const selfDepVersion = deps[packageName];
-    if (selfDepVersion && selfDepVersion !== 'link:.') {
-      badSelfDeps.push({ depKey, version: selfDepVersion });
-    }
-  }
-
-  return badSelfDeps;
+    const selfDepVersion = deps?.[packageName];
+    if (selfDepVersion && selfDepVersion !== 'link:.')
+      return [{ depKey, version: selfDepVersion }];
+    return [];
+  });
 };
 
 export const check: FileCheckFunction = (contents) => {
@@ -50,27 +44,26 @@ export const fix: FileFixFunction = (contents) => {
   const packageName = packageJson.name as string | undefined;
   if (!packageName) return { contents };
 
-  let modified = false;
-
-  for (const depKey of DEP_KEYS) {
-    const deps = packageJson[depKey] as Record<string, string> | undefined;
-    if (!deps) continue;
+  const badSelfDeps = findBadSelfDeps(packageJson);
+  if (badSelfDeps.length === 0) return { contents };
 
-    const selfDepVersion = deps[packageName];
-    if (selfDepVersion && selfDepVersion !== 'link:.') {
-      delete deps[packageName];
-      modified = true;
+  const badDepKeys = new Set(badSelfDeps.map((dep) => dep.depKey));
 
-      // if deps object is now empty, remove it
-      if (Object.keys(deps).length === 0) {
-        delete packageJson[depKey];
-      }
-    }
-  }
+  // rebuild the manifest without the self-deps; drop any dep object left empty
+  const cleaned = Object.fromEntries(
+    Object.entries(packageJson).flatMap(([key, value]) => {
+      if (!badDepKeys.has(key)) return [[key, value]];
 
-  if (!modified) return { contents };
+      const { [packageName]: _selfDep, ...rest } = value as Record<
+        string,
+        string
+      >;
+      if (Object.keys(rest).length === 0) return [];
+      return [[key, rest]];
+    }),
+  );
 
   return {
-    contents: JSON.stringify(packageJson, null, 2),
+    contents: JSON.stringify(cleaned, null, 2),
   };
 };

package/dist/.test/assets/expo-migration/declarations/practices/node/best-practice/.npmrc.declapract.ts

@@ -1,4 +1,5 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
 
 import { defineExpectedNpmrcContents } from '../../../utils/defineExpectedNpmrcContents';
 
@@ -41,7 +42,10 @@ export const check: FileCheckFunction = (contents, context) => {
   // (rule.forbid.friction-hazards) — the caller only needs a clean, stable signal.
   const expected = defineExpectedContents(contents, context.projectPractices);
   if (contents !== expected)
-    throw new Error('.npmrc does not carry the declared node/expo lines');
+    throw new ConstraintError(
+      '.npmrc does not carry the declared node/expo lines; run `declapract apply` to findsert them',
+      { relativeFilePath: context.relativeFilePath },
+    );
 };
 
 /**

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

@@ -7,7 +7,7 @@
   "bugs": "https://github.com/@declapract{variable.organizationName}/@declapract{variable.projectName}/issues",
   "scripts": {
     "fix": "npm run fix:format && npm run fix:lint",
-    "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
+    "prepare": "if [ -e .git ] && [ -z \"${CI:-}\" ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
     "prepush": "npm run test && npm run build",
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify"

package/dist/.test/assets/expo-migration/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/expo-migration/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/expo-migration/declarations/practices/pnpm/.test/assets/repo-npm-to-pnpm/pnpm-workspace.yaml

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