declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/practices/node/best-practice/.npmrc.declapract.ts

@@ -0,0 +1,60 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { defineExpectedNpmrcContents } from '../../../utils/defineExpectedNpmrcContents';
+
+/**
+ * .what = the `.npmrc` the node practice declares, usecase-aware for the expo runtime
+ * .why  = a flat node_modules (hoisted linker) is create-expo-app's own default for pnpm
+ *         and the documented fallback when isolated installs break metro/react-native
+ *         native-module lookup (SDK 54+ supports isolated, but hoisted is the trodden
+ *         default). so an expo repo layers the hoisted-linker block atop the base `.npmrc`
+ *         every node repo gets, rather than fork a separate practice
+ *         (rule.avoid.runtime-forks). the forced-vs-opt-in call is flagged for the wisher
+ *         in `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+ * .why  = a FINDSERT (check/fix union), NOT an EQUALS overwrite. the fix only APPENDS
+ *         absent declared lines and never removes a line, so a repo's own `.npmrc`
+ *         settings — and, crucially, a correctly-hoisted expo `.npmrc` under a narrow
+ *         `declapract fix --practice node` (where the expo signal goes dark) — are
+ *         preserved rather than clobbered. the algorithm lives in
+ *         `defineExpectedNpmrcContents`, shared by `check` and `fix` so the gate and the
+ *         repair can never disagree (mirrors the repo-root `.gitignore`).
+ * .note = best-practice check semantics are inverted — a THROW means the practice is
+ *         violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  projectPractices: string[],
+): string => defineExpectedNpmrcContents({ contents, projectPractices });
+
+/**
+ * .what = throws when the repo's `.npmrc` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. the expected value UNIONS the repo's extant lines in, so a repo
+ *         that already carries the declared lines (plus any of its own) passes — the
+ *         check mandates PRESENCE of the declared lines, never EQUALITY, so it can never
+ *         demand a custom line be removed.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  // a plain comparison + clear throw, NOT an `expect` assertion: declapract runs
+  // `check` outside any test runner, so a test-diff-shaped throw is a friction hazard
+  // (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');
+};
+
+/**
+ * .what = unions this practice's declared `.npmrc` lines into the repo's extant one
+ * .why  = a findsert by construction — a line already present stays present once, a
+ *         repo's own settings survive, and (the fix this closes) a hoisted expo
+ *         `.npmrc` is never stripped by a narrow-scope apply.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own output.
+ *         clamped by `.npmrc.declapract.test.ts` -> `idempotency` and by the pipeline
+ *         test's narrow-scope `[case2]`.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(contents, context.projectPractices),
+  };
+};

package/dist/practices/node/best-practice/__snapshots__/.npmrc.declapract.integration.test.ts.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`node practice .npmrc — expo hoisted linker given: [case1] an expo consumer repo with a base node .npmrc when: [t0] the node practice is applied then: the before + after contents match snapshot: .npmrc — after apply 1`] = `
+"engine-strict=true
+save-exact=true
+message=%s 🎉
+
+# hoisted linker flattens node_modules — create-expo-app default for pnpm,
+# the documented fallback when isolated installs break metro native lookup
+node-linker=hoisted
+public-hoist-pattern[]=*expo*
+public-hoist-pattern[]=*react-native*
+public-hoist-pattern[]=@react-native/*
+public-hoist-pattern[]=metro*
+public-hoist-pattern[]=*metro-*
+"
+`;
+
+exports[`node practice .npmrc — expo hoisted linker given: [case1] an expo consumer repo with a base node .npmrc when: [t0] the node practice is applied then: the before + after contents match snapshot: .npmrc — before 1`] = `
+"engine-strict=true
+save-exact=true
+message=%s 🎉
+"
+`;

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

@@ -0,0 +1,175 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .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
+ *         proves declapract WIRES them up — matches each declaration to its target file
+ *         (npm-overrides on package.json, husky-lockfile-check on the husky hook), and
+ *         reaches a fixed point on a re-run.
+ */
+describe('pnpm npm→pnpm migration — pipeline', () => {
+  given('[case1] a repo mid-migration from npm to pnpm', () => {
+    const tempDir = genTempDir({
+      slug: 'pnpm-npm-to-pnpm',
+      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 readPkg = () => fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+    const readHusky = () =>
+      fs.readFile(path.join(tempDir, '.husky/check.lockfile.sh'), 'utf-8');
+
+    // useBeforeAll RETURNS the captured state (no in-place mutation of a shared const)
+    const state = useBeforeAll(async () => {
+      const pkgBefore = await readPkg();
+      const huskyBefore = await readHusky();
+
+      // apply the package.json bad-practice (npm-overrides relocates the pins)
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      // apply the husky lockfile-hook bad-practice
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: '.husky/check.lockfile.sh',
+      });
+      const huskyAfter1 = await readHusky();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: '.husky/check.lockfile.sh',
+      });
+      const huskyAfter2 = await readHusky();
+
+      return {
+        pkgBefore,
+        pkgAfter1,
+        pkgAfter2,
+        huskyBefore,
+        huskyAfter1,
+        huskyAfter2,
+      };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied to package.json', () => {
+      then('overrides + resolutions relocate into pnpm.overrides', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.pnpm.overrides['react-refresh']).toEqual('~0.14.0');
+        expect(pkg.overrides).toBeUndefined();
+        expect(pkg.resolutions).toBeUndefined();
+      });
+
+      then('the `npm run` invocation convention is left intact (repo-wide idiom)', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.scripts.prepush).toEqual('npm run test && npm run build');
+      });
+
+      then('the packageManager pin survives (best-practice no-op)', () => {
+        const pkg = JSON.parse(state.pkgAfter1);
+        expect(pkg.packageManager).toEqual('pnpm@10.31.7');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.pkgBefore).toMatchSnapshot('package.json — before');
+        expect(state.pkgAfter1).toMatchSnapshot('package.json — after');
+      });
+
+      then('a second apply is a fixed point', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+
+    when('[t1] the pnpm practice is applied to the husky hook', () => {
+      then('the lockfile name + install command become pnpm', () => {
+        expect(state.huskyAfter1).toContain('pnpm-lock.yaml');
+        expect(state.huskyAfter1).toContain('pnpm install');
+        expect(state.huskyAfter1).not.toContain('package-lock.json');
+        expect(state.huskyAfter1).not.toMatch(/(?<!p)npm install/);
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.huskyBefore).toMatchSnapshot('check.lockfile.sh — before');
+        expect(state.huskyAfter1).toMatchSnapshot('check.lockfile.sh — after');
+      });
+
+      then('a second apply is a fixed point', () => {
+        expect(state.huskyAfter2).toEqual(state.huskyAfter1);
+      });
+    });
+  });
+
+  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 —
+    // 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.
+    const tempDir = genTempDir({
+      slug: 'pnpm-ahead-of-pin',
+      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 pkgPath = () => path.join(tempDir, 'package.json');
+    const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
+
+    const state = useBeforeAll(async () => {
+      // seed the pin AHEAD of 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();
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      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', () => {
+        expect(JSON.parse(state.pkgBefore).packageManager).toEqual('pnpm@10.32.1');
+        expect(JSON.parse(state.pkgAfter1).packageManager).toEqual('pnpm@10.31.7');
+      });
+
+      then('a second apply is a fixed point (the downgrade converges)', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+  });
+});

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/.husky/check.lockfile.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'package-lock.json'; then
+  echo "📦 package-lock.json changed. Run 'npm install' to update your locally installed dependencies."
+fi

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/declapract.use.yml

@@ -0,0 +1,7 @@
+# .note = declarations dir is symlinked by the test to test/assets/pnpm/declarations
+# .why  = a repo mid-migration from npm to pnpm, used to prove the pnpm bad-practices
+#         (npm-overrides, husky-lockfile-check) end to end.
+# .note = no variables — the pnpm-repo usecase carries only the pnpm practice, which
+#         references no @declapract{variable.*}.
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.31.7",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "overrides": {
+    "react-refresh": "~0.14.0"
+  },
+  "resolutions": {
+    "react-refresh": "~0.14.0"
+  }
+}

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

@@ -0,0 +1,68 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t0] the pnpm practice is applied to package.json then: before + after match snapshot: package.json — after 1`] = `
+"{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.31.7",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "~0.14.0"
+    }
+  }
+}
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t0] the pnpm practice is applied to package.json then: before + after match snapshot: package.json — before 1`] = `
+"{
+  "name": "app-example-native",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.31.7",
+  "scripts": {
+    "fix:format": "npm run fix:format:prettier",
+    "prepush": "npm run test && npm run build",
+    "fix:deps:expo": "npx expo install --fix"
+  },
+  "overrides": {
+    "react-refresh": "~0.14.0"
+  },
+  "resolutions": {
+    "react-refresh": "~0.14.0"
+  }
+}
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t1] the pnpm practice is applied to the husky hook then: before + after match snapshot: check.lockfile.sh — after 1`] = `
+"#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'pnpm-lock.yaml'; then
+  echo "📦 pnpm-lock.yaml changed. Run 'pnpm install' to update your locally installed dependencies."
+fi
+"
+`;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migration from npm to pnpm when: [t1] the pnpm practice is applied to the husky hook then: before + after match snapshot: check.lockfile.sh — before 1`] = `
+"#!/bin/bash
+
+# posix style fn definition; https://stackoverflow.com/a/12469057/3068233
+changed () {
+  git diff --name-only HEAD@{1} HEAD | grep "^$1"
+}
+
+if changed 'package-lock.json'; then
+  echo "📦 package-lock.json changed. Run 'npm install' to update your locally installed dependencies."
+fi
+"
+`;

package/dist/practices/pnpm/bad-practices/husky-lockfile-check/.declapract.readme.md

@@ -0,0 +1,17 @@
+# bad-practice: husky-lockfile-check
+
+## .what
+
+a husky hook (`.husky/check.lockfile.sh`) that watches the npm `package-lock.json` for
+changes and points the human at `npm install`.
+
+## .why it is bad under pnpm
+
+a pnpm repo has no `package-lock.json` — its lockfile is `pnpm-lock.yaml`. a hook left on
+the npm name never fires on a real pnpm lockfile change, so the stale-dependencies
+reminder silently dies.
+
+## .the fix
+
+swap `package-lock.json` → `pnpm-lock.yaml` and `npm install` → `pnpm install`. idempotent
+— once swapped, the check no longer detects the npm name.

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

@@ -0,0 +1,28 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects a husky lockfile-change hook that watches the npm `package-lock.json`
+ * .why  = a pnpm repo has no `package-lock.json` — its lockfile is `pnpm-lock.yaml`. a hook
+ *         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;
+
+  // not detected — already on pnpm-lock.yaml (or absent)
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = swaps the npm lockfile name + install command for their pnpm equivalents
+ * .why  = the hook must watch `pnpm-lock.yaml` and point the human at `pnpm install`.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const fixed = contents
+    .replace(/package-lock\.json/g, 'pnpm-lock.yaml')
+    // `(?<!p)` guards the overlap: pnpm contains npm, so a naive swap of `npm install`
+    // would nest inside its own `pnpm install` output and loop on a re-run
+    .replace(/(?<!p)npm install/g, 'pnpm install');
+  return { contents: fixed };
+};

package/dist/practices/pnpm/bad-practices/npm-overrides/.declapract.readme.md

@@ -0,0 +1,20 @@
+# bad-practice: npm-overrides
+
+## .what
+
+a package.json that keeps its dependency pins under a top-level `overrides` (npm) or
+`resolutions` (yarn) key.
+
+## .why it is bad under pnpm
+
+pnpm reads **neither** `overrides` nor `resolutions` — it reads `pnpm.overrides`. a repo
+migrated from npm/yarn that leaves its pins under the old keys silently loses them. under
+the hoisted linker (flat `node_modules`) that lets a mismatched transitive version hoist
+over the intended one — the skew hazard documented in
+`.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+
+## .the fix
+
+relocate both top-level keys into `pnpm.overrides` and drop them. on a key collision the
+precedence is: npm `overrides` beats yarn `resolutions` beats any pre-extant
+`pnpm.overrides`. idempotent — once relocated, the check no longer detects the pattern.

package/dist/practices/pnpm/bad-practices/npm-overrides/package.json.declapract.ts

@@ -0,0 +1,75 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = detects a top-level `overrides` (npm) or `resolutions` (yarn) key in package.json
+ * .why  = pnpm reads NEITHER — it reads `pnpm.overrides`. a repo migrated to pnpm that keeps
+ *         its pins under the npm/yarn keys silently loses them, which lets a mismatched
+ *         transitive version hoist over the intended one (the flat-linker skew hazard). see
+ *         `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  const packageJSON = JSON.parse(contents ?? '{}');
+
+  // detected (bad practice) when either npm-`overrides` or yarn-`resolutions` sits at top level
+  if (
+    packageJSON.overrides !== undefined ||
+    packageJSON.resolutions !== undefined
+  )
+    return;
+
+  // not detected — already pnpm-shaped (or no pins at all)
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = relocates top-level `overrides` + `resolutions` into `pnpm.overrides`, then drops them
+ * .why  = pnpm reads only `pnpm.overrides`. precedence on a key conflict: npm `overrides` wins over
+ *         yarn `resolutions` over any pre-extant `pnpm.overrides`.
+ *
+ * .note = handles the FLAT override shape (`{ "pkg": "1.2.3" }`). npm ALSO supports a NESTED
+ *         per-dependency form (`{ "foo": { ".": "1.0.0", "bar": "2.0.0" } }`) that pnpm's flat-only
+ *         `pnpm.overrides` cannot express. this fix does NOT silently emit such a shape (a config
+ *         pnpm rejects — a failhide); it FAILS FAST with a `ConstraintError` that names the at-fault
+ *         key and the fix, per `rule.forbid.failhide` / `rule.require.failfast`. a consumer with
+ *         nested npm overrides must flatten them by hand.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = JSON.parse(contents);
+
+  // merge — npm `overrides` beats yarn `resolutions` beats any extant `pnpm.overrides`
+  const mergedOverrides = {
+    ...(packageJSON.pnpm?.overrides ?? {}),
+    ...(packageJSON.resolutions ?? {}),
+    ...(packageJSON.overrides ?? {}),
+  };
+
+  // fail fast on a nested per-dependency override — pnpm's flat `pnpm.overrides` cannot express it,
+  // so a pass-through would emit a config pnpm rejects (a silent failhide). name the fix.
+  const nestedKeys = Object.entries(mergedOverrides)
+    .filter(([, value]) => typeof value !== 'string')
+    .map(([key]) => key);
+  if (nestedKeys.length)
+    throw new ConstraintError(
+      'cannot migrate a NESTED npm override to pnpm — flatten it by hand first',
+      {
+        nestedKeys,
+        hint: `pnpm's \`pnpm.overrides\` is flat-only ({ "pkg": "1.2.3" }). the nested per-dependency form ({ ".": "...", "dep": "..." }) has no pnpm equivalent. flatten these keys to a single version string each, then re-run: ${nestedKeys.join(', ')}`,
+      },
+    );
+
+  // exclude the npm/yarn keys via destructure (no in-place delete), keep every other key
+  const {
+    overrides: _npmOverrides,
+    resolutions: _yarnResolutions,
+    ...packageJSONRest
+  } = packageJSON;
+
+  const updatedPackageJSON = {
+    ...packageJSONRest,
+    pnpm: { ...(packageJSON.pnpm ?? {}), overrides: mergedOverrides },
+  };
+
+  return { contents: `${JSON.stringify(updatedPackageJSON, null, 2)}\n` };
+};

package/dist/practices/pnpm/bad-practices/package-lock-json/.declapract.readme.md

@@ -0,0 +1,30 @@
+# bad-practice: package-lock-json
+
+## .what
+
+a `package-lock.json` (the npm lockfile) in a repo that has migrated to pnpm.
+
+## .why it is bad
+
+pnpm reads `pnpm-lock.yaml`, not `package-lock.json`. a stale npm lockfile left beside the pnpm one
+is a dual source of truth for the dependency graph, and CI lockfile checks that grep the wrong file
+pass or fail for the wrong reason.
+
+## .the fix — forget-not-destroy
+
+the fix removes `package-lock.json`, but ONLY once a `pnpm-lock.yaml` sits beside it. the delete is
+gated on the pnpm lockfile's presence (read from the project root via
+`context.getProjectRootDirectory()`), so a fix that runs on a repo that has not yet run
+`pnpm install` is a no-op rather than a destructive strip that leaves the repo lockfile-less. this
+is the wish's stated safety bar: *"package-lock.json is removed ONLY after pnpm-lock.yaml exists, so
+a fix interrupted midway never leaves the repo lockfile-less."*
+
+a bare `FileCheckType.EXISTS` would delegate to declapract's default fix, which deletes the file
+UNCONDITIONALLY — so this practice declares its own gated `check`/`fix` instead.
+
+## .see also
+
+- `package-lock.json.declapract.integration.test.ts` — the forget-not-destroy clamp (delete-when-safe
+  + survive-when-unsafe)
+- `rule.require.clamp-edge-cases` — the regression clamp a destructive fix owes
+- `howto.craft-practice-migrations` — the forget-not-destroy migration shape

package/dist/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.integration.test.ts

@@ -0,0 +1,105 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import type { FileCheckContext } from 'declapract';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { check, fix } from './package-lock.json.declapract';
+
+/**
+ * .what = the forget-not-destroy clamp for the package-lock.json bad-practice.
+ * .why  = the fix DELETES the npm lockfile, so it is destructive — `rule.require.clamp-edge-cases`
+ *         demands a regression clamp that BITES. the gate reads the real filesystem for a
+ *         `pnpm-lock.yaml` beside the lockfile, so this is an integration test (a filesystem
+ *         boundary, per `rule.forbid.unit.remote-boundaries`), built on the `mkdtempSync`
+ *         throwaway-root pattern from `howto.craft-practice-migrations`. it proves BOTH paths:
+ *         delete-when-safe (pnpm-lock.yaml present) and skip-when-unsafe (absent) — the second
+ *         guards the forget-not-destroy contract: a bare EXISTS default-delete would fail it.
+ */
+/**
+ * .what = builds the minimal FileCheckContext the check and fix functions actually use
+ * .why  = declapract's FileCheckContext carries many fields the package-lock check/fix never
+ *         touch — they read only `getProjectRootDirectory()` (to look for a `pnpm-lock.yaml`
+ *         beside the lockfile). the single documented cast here is the sanctioned test-context
+ *         idiom (howto.craft-practice-migrations); it is confined to this helper so no call
+ *         site casts. removal path: drop the cast the day declapract exports a partial-context
+ *         builder.
+ */
+const genContextForRoot = (root: string): FileCheckContext =>
+  ({ getProjectRootDirectory: () => root }) as unknown as FileCheckContext;
+
+describe('pnpm package-lock-json — forget-not-destroy gate', () => {
+  // .note = deliberate mutation — `roots` accumulates every temp dir genRoot mints so the
+  //         afterAll below can remove them all; a scoped, single-threaded test-cleanup zone
+  //         (rule.require.immutable-vars sanctions in-place mutation with this note).
+  const roots: string[] = [];
+  const genRoot = (slug: string, files: Record<string, string>): string => {
+    const root = mkdtempSync(path.join(tmpdir(), `pnpm-lock-${slug}-`));
+    for (const [name, body] of Object.entries(files))
+      writeFileSync(path.join(root, name), body);
+    roots.push(root);
+    return root;
+  };
+
+  afterAll(() => {
+    for (const root of roots) rmSync(root, { recursive: true, force: true });
+  });
+
+  given('[case1] a package-lock.json WITH a pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('safe', {
+        'package-lock.json': '{}',
+        'pnpm-lock.yaml': 'lockfileVersion: 9\n',
+      });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check detects it — safe to remove', () => {
+        expect(() => check('{}', state.context)).not.toThrow();
+      });
+
+      then('fix removes it — contents become null', () => {
+        expect(state.fixed).toBeNull();
+      });
+    });
+  });
+
+  given('[case2] a package-lock.json with NO pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('unsafe', { 'package-lock.json': '{}' });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — forget-not-destroy, no pnpm-lock.yaml yet', () => {
+        expect(() => check('{}', state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+
+      then('fix is a no-op — the npm lockfile is preserved', () => {
+        // a bare EXISTS default-delete would make this null, which this test would catch
+        expect(state.fixed).toEqual('{}');
+      });
+    });
+  });
+
+  given('[case3] no package-lock.json at all', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('absent', { 'pnpm-lock.yaml': 'lockfileVersion: 9\n' });
+      return { context: genContextForRoot(root) };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — no npm lockfile to remove', () => {
+        expect(() => check(null, state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+    });
+  });
+});