declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/husky/check.timestamps.play.declapract.integration.test.ts

@@ -62,6 +62,20 @@ describe('check.timestamps guard', () => {
           '   └─ snapshot.json:1:{ "createdAt": "2026-06-25T14:30:00Z" }',
         );
       });
+      then('the verbatim halt output matches snapshot', () => {
+        // user-faced halt message — a reword must redden a vibecheck, not slip past the
+        // toContain asserts above (rule.require.snapshots). the fixture timestamp is a fixed
+        // input (not a live clock), so the output is deterministic.
+        // mask the instant to [timestamp] before the snapshot: the .snap is itself scanned by
+        // this very guard (only .ts/.sh are exempt), so a raw instant here would forbid its own
+        // commit. the raw detail-line toContain above already locks the exact instant in the
+        // output; the snapshot vibechecks the message shape, per the guard's own mask remedy (case8).
+        const masked = result.stdout.replace(
+          /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/g,
+          '[timestamp]',
+        );
+        expect(masked).toMatchSnapshot('check.timestamps halt output');
+      });
     });
   });
 
@@ -145,4 +159,55 @@ describe('check.timestamps guard', () => {
       });
     });
   });
+
+  // #566: an iso-8601 duration is a fixed span, not an instant, so it cannot permadrift —
+  // the matcher must not halt on it (a false positive that trains folks to bypass the hook)
+  given('[case9] a non-code file with a simple iso duration (PT12:30:00)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'fixture.json': '{ "window": "PT12:30:00" }\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case10] a non-code file with a day+time duration (P1DT02:15:30)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'fixture.json': '{ "elapsed": "P1DT02:15:30" }\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case11] a non-code file with a full-designator duration (P3Y6M4DT12:30:05)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'fixture.json': '{ "span": "P3Y6M4DT12:30:05" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case12] a non-code file with BOTH a duration and a real timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'fixture.json':
+          '{ "window": "PT12:30:00", "createdAt": "2026-06-25T14:30:00Z" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it halts with exit 2 (the real stamp wins, despite the duration)', () => {
+        expect(result.code).toEqual(2);
+      });
+    });
+  });
 });

package/dist/practices/lint/__snapshots__/dpdmrc-exclude-policy.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`lint .dpdmrc.yaml exclude policy given: the shipped .dpdmrc.yaml when: the exclude list is read then: the emitted exclude value matches snapshot: dpdmrc exclude value 1`] = `[]`;

package/dist/practices/lint/bad-practices/depcheck-denylisted-ignores/.depcheckrc.yml.declapract.ts

@@ -46,6 +46,10 @@ export const fix: FileFixFunction = (contents) => {
   if (denylistedPresent.length === 0) return { contents };
 
   // Remove denylisted ignores from the document
+  // note = `as any` at an external boundary (the `yaml` library ships no node type for
+  //        `doc.get`, which returns `unknown`). correct type = the library's `YAMLSeq`
+  //        with an `items` array. removal path = when `yaml` exports a typed `get`, or a
+  //        local `isYamlSeq` type-guard narrows the node before the `.items` access.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const ignoresNode = doc.get('ignores') as any;
   if (ignoresNode?.items) {

package/dist/practices/lint/best-practice/.depcheckrc.yml.declapract.ts

@@ -25,17 +25,18 @@ export const fix: FileFixFunction = (contents, context) => {
 
   if (missingIgnores.length === 0) return { contents };
 
-  // Add missing ignores to the document (preserves comments)
+  // get the ignores seq node, seeding an empty seq onto the doc if absent
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let ignoresNode = currentDoc.get('ignores') as any;
-  if (!ignoresNode) {
+  const ignoresNode = ((): any => {
+    const node = currentDoc.get('ignores');
+    if (node) return node;
     currentDoc.set('ignores', []);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ignoresNode = currentDoc.get('ignores') as any;
-  }
-  for (const ignore of missingIgnores) {
-    ignoresNode.add(ignore);
-  }
+    return currentDoc.get('ignores');
+  })();
+
+  // .note = deliberate mutation — the yaml document api mutates the seq node in
+  // place to preserve the surrounding comments; there is no immutable seq-add
+  missingIgnores.forEach((ignore) => ignoresNode.add(ignore));
 
   return { contents: currentDoc.toString() };
 };

package/dist/practices/lint/best-practice/.dpdmrc.yaml

@@ -1,9 +1,13 @@
-# dpdm exclude patterns
-# each entry is joined with | to form a single regex for --exclude
+# dpdm exclude patterns — each entry is joined with | into a single --exclude regex.
 #
-# with --transform flag, type imports are erased before analysis
-# and test files are excluded via glob pattern '!(*.test).ts'
-# so excludes are rarely needed even for devDependencies
+# an empty `exclude: []` means dpdm checks every file for cycles, node_modules included. this is
+# the org policy `rule.forbid.dpdm-exclude-change`: we check dependencies too, because a prod-dep
+# cycle ships to consumers.
 #
-# never exclude prod dependencies — you'd ship cycles to consumers
+# with --transform, type imports are erased before analysis and test files drop via the
+# '!(*.test).ts' glob, so an exclude is rarely needed even for a devDep. a devDep may be added as
+# an escape hatch; a prod dep must not, since that ships cycles.
+#
+# the empty list is the policy — an entry of `node_modules` (or dpdm's own `/node_modules/`
+# default) disables the check across every consumer repo.
 exclude: []

package/dist/practices/lint/dpdmrc-exclude-policy.declapract.integration.test.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import { parse } from 'yaml';
+
+/**
+ * .what = clamps #581 + `rule.forbid.dpdm-exclude-change`: the shipped .dpdmrc.yaml keeps an empty
+ *         `exclude` and never adds node_modules, so dpdm checks ALL files for cycles (deps included).
+ * .why  = an empty `exclude: []` is the POLICY, not a no-op — it renders `--exclude ""` (dpdm's
+ *         include-all value), so a prod-dep cycle cannot ship to consumers unseen. the hazard is a
+ *         future tidy-up that adds `node_modules` / `^node_modules` or "fixes" the list toward
+ *         dpdm's own `/node_modules/` default — either silently disables the policy across every
+ *         consumer repo. the parse reads the `exclude` VALUE, so the ⚠️ node_modules mention in the
+ *         file's own comment does not false-match.
+ * .teeth = add `^node_modules` (or any node_modules entry) to `exclude` in best-practice/.dpdmrc.yaml
+ *          and the "no node_modules" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the practice
+ *         ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('lint .dpdmrc.yaml exclude policy', () => {
+  given('the shipped .dpdmrc.yaml', () => {
+    const parsed = parse(
+      readFileSync(join(__dirname, 'best-practice/.dpdmrc.yaml'), 'utf8'),
+    );
+    const exclude: unknown = parsed?.exclude;
+
+    when('the exclude list is read', () => {
+      then('it is an array', () => {
+        expect(Array.isArray(exclude)).toEqual(true);
+      });
+
+      then('it is empty (all files checked, deps included — the org policy)', () => {
+        expect(exclude).toEqual([]);
+      });
+
+      then('no entry excludes node_modules (that would disable the policy)', () => {
+        const entries = (exclude as unknown[]).map((e) => String(e));
+        const hasNodeModules = entries.some((e) => e.includes('node_modules'));
+        expect(hasNodeModules).toEqual(false);
+      });
+
+      // the emitted exclude value is the caller-faced contract: snapshot it so a reword toward
+      // dpdm's node_modules default reddens a vibecheck, not just the token assertion.
+      then('the emitted exclude value matches snapshot', () => {
+        expect(exclude).toMatchSnapshot('dpdmrc exclude value');
+      });
+    });
+  });
+});

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

@@ -0,0 +1,100 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the logs/leveled-term fix, run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo whose package.json lists the deprecated
+ *   `simple-leveled-log-methods` in BOTH `dependencies` and `devDependencies` (D50 / #571).
+ * .why  = the old declaration was a `CONTAINS` template pinned to `devDependencies`, so it was blind
+ *   to a `dependencies` placement — the bad practice silently never fired for a repo that had the
+ *   dep at runtime. the fix is now a `FileCheckFunction` + `withoutDeprecatedDep` transformer that
+ *   removes it from BOTH sections. a unit test of the transformer is necessary but not sufficient
+ *   (`rule.require.declapract-integration-tests`): only the pipeline proves the declaration's target
+ *   glob matches package.json and the fix lands on a real consumer file.
+ * .note = the package.json is snapshotted in full (before AND after) so a reviewer can eyeball the
+ *   exact end-state. the target file holds the dep in both sections, so the after-state proves the
+ *   both-section removal AND the section-presence preservation.
+ */
+describe('logs/leveled-term removal', () => {
+  given('[case1] a repo with simple-leveled-log-methods in both dep sections', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-logs-leveled-term',
+      clone: './src/practices/logs/bad-practices/leveled-term/.test/assets/demo-repo-with-leveled-term',
+      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: 'logs',
+        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 leveled-term fix is applied', () => {
+      useThen('remove the deprecated dep from both sections', async () =>
+        applyFix(),
+      );
+
+      then(
+        'the dep is gone from dependencies AND devDependencies, both sections preserved, and matches snapshot',
+        async () => {
+          const pkg = JSON.parse(await read(pkgPath));
+          // the deprecated dep is gone from both sections
+          expect(pkg.dependencies?.['simple-leveled-log-methods']).toBeUndefined();
+          expect(
+            pkg.devDependencies?.['simple-leveled-log-methods'],
+          ).toBeUndefined();
+          // each section's PRESENCE is preserved (the repo declared both, so both stay)
+          expect(pkg.dependencies).toBeDefined();
+          expect(pkg.devDependencies).toBeDefined();
+          // the peer deps in each section survive untouched
+          expect(pkg.dependencies.uuid).toEqual('9.0.0');
+          expect(pkg.devDependencies.jest).toEqual('29.3.1');
+          // 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 = the D50 invariant under re-apply is that the leveled-term fix is a
+      //   FIXED POINT for the deprecated dep: once removed, a second pass neither
+      //   re-introduces it nor drops a peer section. we do NOT assert full-file byte
+      //   equality here, because the logs best-practice package.json declaration (a
+      //   separate declarer, out of scope for D50) writes a raw
+      //   `@declapract{check.minVersion(...)}` marker on the first pass and resolves it
+      //   to a bare version on the second — a marker-resolution quirk of that declaration,
+      //   not of the leveled-term transformer 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 deprecated dep stays gone from both sections', () => {
+        expect(pkg.dependencies?.['simple-leveled-log-methods']).toBeUndefined();
+        expect(
+          pkg.devDependencies?.['simple-leveled-log-methods'],
+        ).toBeUndefined();
+      });
+
+      then('both sections and their peer deps survive the re-apply', () => {
+        expect(pkg.dependencies).toBeDefined();
+        expect(pkg.devDependencies).toBeDefined();
+        expect(pkg.dependencies.uuid).toEqual('9.0.0');
+        expect(pkg.devDependencies.jest).toEqual('29.3.1');
+      });
+    });
+  });
+});

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

@@ -0,0 +1,33 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`logs/leveled-term removal given: [case1] a repo with simple-leveled-log-methods in both dep sections when: [t0] the input (before any fix) then: the package.json input matches snapshot: package.json — before 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "simple-leveled-log-methods": "0.1.7",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "simple-leveled-log-methods": "0.1.7",
+    "jest": "29.3.1"
+  }
+}
+"
+`;
+
+exports[`logs/leveled-term removal given: [case1] a repo with simple-leveled-log-methods in both dep sections when: [t1] the leveled-term fix is applied then: the dep is gone from dependencies AND devDependencies, both sections preserved, and matches snapshot: package.json — after 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "uuid": "9.0.0",
+    "sdk-environment": "@declapract{check.minVersion('0.1.5')}",
+    "sdk-logs": "@declapract{check.minVersion('0.9.2')}"
+  },
+  "devDependencies": {
+    "jest": "29.3.1"
+  }
+}
+"
+`;

package/dist/practices/logs/bad-practices/leveled-term/.test/assets/demo-repo-with-leveled-term/declapract.declare.yml

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

package/dist/practices/logs/bad-practices/leveled-term/.test/assets/demo-repo-with-leveled-term/declapract.use.yml

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

package/dist/practices/logs/bad-practices/leveled-term/.test/assets/demo-repo-with-leveled-term/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "simple-leveled-log-methods": "0.1.7",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "simple-leveled-log-methods": "0.1.7",
+    "jest": "29.3.1"
+  }
+}

package/dist/practices/logs/bad-practices/leveled-term/package.json.declapract.ts

@@ -1,18 +1,62 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
-export const check = FileCheckType.CONTAINS;
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
 
-export const fix: FileFixFunction = (contents) => {
-  if (!contents) return { contents }; // do nothing if no contents
-  const packageJSON = JSON.parse(contents);
-  const updatedPackageJSON = {
-    ...packageJSON,
-    devDependencies: {
-      ...packageJSON.devDependencies,
-      'simple-leveled-log-methods': undefined,
-    },
+// simple-leveled-log-methods is a RUNTIME log library, so a repo may list it under EITHER
+// `dependencies` or `devDependencies`. the old declaration was a `CONTAINS` template pinned to
+// `devDependencies` (and a fix that removed it only from there), so it was blind to the
+// `dependencies` placement — the bad practice silently never fired for a repo that had the dep at
+// runtime. `checkContainsJSON` is path-sensitive, so a CONTAINS template can only ever see one
+// section. this is a FileCheckFunction that inspects both, and the fix removes it from both.
+const DEPRECATED_DEP = 'simple-leveled-log-methods';
+const PRACTICE = 'logs/leveled-term';
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents)
+    throw new Error(
+      `does not match bad practice: [${PRACTICE}] package.json has no contents to scan for '${DEPRECATED_DEP}'`,
+    );
+
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const inProd = Boolean(packageJSON.dependencies?.[DEPRECATED_DEP]);
+  const inDev = Boolean(packageJSON.devDependencies?.[DEPRECATED_DEP]);
+
+  if (inProd || inDev) return; // detected — the deprecated dep is present in some section
+  // no violation — the deprecated dep is absent from both dependencies + devDependencies
+  throw new Error(
+    `does not match bad practice: '${DEPRECATED_DEP}' absent from dependencies|devDependencies`,
+  );
+};
+
+/**
+ * .what = return the package.json without `simple-leveled-log-methods` in either dep section,
+ *         each section's PRESENCE preserved byte-for-byte.
+ * .why  = names the removal as one pure intent, so `fix` reads what-not-how rather than an inline
+ *         spread-then-delete a reader must simulate (`rule.require.named-transformers`), to match
+ *         the peer rhachet/prod-deps `withRhachetDepsMovedToDevDeps` pure-op discipline. pure over a
+ *         fresh clone, so it is independently testable.
+ * .note = a section the consumer declared (even as an empty `{}`) stays; a section it never had is
+ *         not added. re-spread over `...packageJSON` keeps each key in its original position.
+ */
+const withoutDeprecatedDep = (input: {
+  packageJSON: Record<string, any>;
+}): Record<string, any> => {
+  const dependencies = { ...input.packageJSON.dependencies };
+  const devDependencies = { ...input.packageJSON.devDependencies };
+  delete dependencies[DEPRECATED_DEP];
+  delete devDependencies[DEPRECATED_DEP];
+  return {
+    ...input.packageJSON,
+    ...('dependencies' in input.packageJSON ? { dependencies } : {}),
+    ...('devDependencies' in input.packageJSON ? { devDependencies } : {}),
   };
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
   return {
-    contents: JSON.stringify(updatedPackageJSON, null, 2),
+    contents: JSON.stringify(withoutDeprecatedDep({ packageJSON }), null, 2),
   };
 };

package/dist/practices/node/.npmrc.declapract.integration.test.ts

@@ -0,0 +1,165 @@
+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), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = pipeline test for the usecase-aware .npmrc findsert (check/fix union)
+ * .why  = a unit test proves the check/fix in isolation; only the real
+ *         executeApply pipeline proves that declapract:
+ *         - matches the .npmrc declaration to the target file
+ *         - feeds context.projectPractices with the expo signal
+ *           (cicd-app-react-native-expo present in the usecase)
+ *         - findserts the declared lines into the consumer's .npmrc: the base
+ *           node lines PLUS the hoisted-linker block, unioned in so a repo's own
+ *           lines survive (a consumer merge, NOT an EQUALS overwrite)
+ *         - reaches a fixed point on a second apply (idempotent)
+ */
+describe('node practice .npmrc — expo hoisted linker', () => {
+  given('[case1] an expo consumer repo with a base node .npmrc', () => {
+    const tempDir = genTempDir({
+      slug: 'node-npmrc-expo',
+      clone: './src/practices/node/.test/assets/repo-expo-npmrc',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const npmrcPath = () => path.join(tempDir, '.npmrc');
+
+    // useBeforeAll RETURNS the captured reads (no in-place mutation of a shared const)
+    const readState = useBeforeAll(async () => {
+      // capture the consumer's own .npmrc before any apply
+      const before = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // first apply
+      // .note = filter by file ONLY, never by practice. the practice filter
+      //         narrows projectPractices too (getDesiredPractices), which would
+      //         strip cicd-app-react-native-expo and silence the expo branch.
+      //         file-only keeps every usecase practice in projectPractices while
+      //         it applies just the .npmrc plan.
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: '.npmrc',
+      });
+      const after1 = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // second apply — to prove a fixed point
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: '.npmrc',
+      });
+      const after2 = await fs.readFile(npmrcPath(), 'utf-8');
+
+      return { before, after1, after2 };
+    }, 170_000);
+
+    when('[t0] the node practice is applied', () => {
+      then('the base node lines are preserved', () => {
+        expect(readState.after1).toContain('engine-strict=true');
+        expect(readState.after1).toContain('save-exact=true');
+        expect(readState.after1).toContain('message=%s 🎉');
+      });
+
+      then('the hoisted-linker block is appended', () => {
+        expect(readState.after1).toContain('node-linker=hoisted');
+        expect(readState.after1).toContain('public-hoist-pattern[]=*expo*');
+        expect(readState.after1).toContain(
+          'public-hoist-pattern[]=*react-native*',
+        );
+        expect(readState.after1).toContain(
+          'public-hoist-pattern[]=@react-native/*',
+        );
+        expect(readState.after1).toContain('public-hoist-pattern[]=metro*');
+        expect(readState.after1).toContain('public-hoist-pattern[]=*metro-*');
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(readState.before).toMatchSnapshot('.npmrc — before');
+        expect(readState.after1).toMatchSnapshot('.npmrc — after apply');
+      });
+    });
+
+    when('[t1] the node practice is applied a second time', () => {
+      then('the fixed point holds — after2 equals after1', () => {
+        expect(readState.after2).toEqual(readState.after1);
+      });
+
+      then('a single hoist block exists, never a duplicate', () => {
+        const occurrences =
+          readState.after2.split('node-linker=hoisted').length - 1;
+        expect(occurrences).toEqual(1);
+      });
+    });
+  });
+
+  /**
+   * .what = a narrow-scope apply of the node practice on an expo repo leaves the hoist intact
+   * .why  = a narrow `declapract fix --practice node` on an expo repo makes
+   *         projectPractices === ['node'], so the expo branch does not fire. the `.npmrc`
+   *         declaration is a findsert (check/fix union) that appends only absent lines, so a
+   *         narrow-scope apply is a no-op on an already-hoisted `.npmrc`. this test reproduces
+   *         that narrow-scope invocation and asserts the hoist is preserved — it fails if the
+   *         declaration is ever changed to an EQUALS overwrite (which would append no union
+   *         and rewrite the file to base).
+   */
+  given('[case2] a narrow --practice node apply on an expo repo keeps the hoist', () => {
+    const tempDir = genTempDir({
+      slug: 'node-npmrc-expo-narrow',
+      clone: './src/practices/node/.test/assets/repo-expo-npmrc',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const npmrcPath = () => path.join(tempDir, '.npmrc');
+
+    const readState = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+
+      // first, reach the CORRECT expo state via the SUPPORTED path (file filter keeps
+      // every usecase practice in projectPractices, so the expo branch fires)
+      await executeApply({ config, file: '.npmrc' });
+      const withHoist = await fs.readFile(npmrcPath(), 'utf-8');
+
+      // now apply the narrow scope: `--practice node` makes projectPractices === ['node'],
+      // so the expo branch does not fire. the findsert appends only absent lines, so the
+      // hoist is preserved.
+      await executeApply({ config, practice: 'node' });
+      const afterNarrow = await fs.readFile(npmrcPath(), 'utf-8');
+
+      return { withHoist, afterNarrow };
+    }, 170_000);
+
+    when('[t0] the supported path first produced the hoist', () => {
+      then('the hoisted-linker block is present', () => {
+        expect(readState.withHoist).toContain('node-linker=hoisted');
+        expect(readState.withHoist).toContain('public-hoist-pattern[]=*expo*');
+      });
+    });
+
+    when('[t1] a narrow `--practice node` fix then runs on that repo', () => {
+      then('the hoist is preserved', () => {
+        expect(readState.afterNarrow).toContain('node-linker=hoisted');
+        expect(readState.afterNarrow).toContain(
+          'public-hoist-pattern[]=*expo*',
+        );
+      });
+
+      then('the base node lines survive too', () => {
+        expect(readState.afterNarrow).toContain('engine-strict=true');
+        expect(readState.afterNarrow).toContain('save-exact=true');
+      });
+
+      then('the narrow-scope apply is a no-op — afterNarrow equals withHoist', () => {
+        expect(readState.afterNarrow).toEqual(readState.withHoist);
+      });
+    });
+  });
+});

package/dist/practices/node/.test/assets/repo-expo-npmrc/declapract.use.yml

@@ -0,0 +1,23 @@
+# .note = declarations dir is symlinked by the test to test/assets/expo/declarations
+# .why  = an expo consumer repo, used to prove the node practice's .npmrc contents fn
+#         appends the hoisted-linker block when the expo usecase is in play.
+declarations: 'declarations/declapract.declare.yml'
+useCase: app-react-native-expo
+# .note = the apply evaluates the WHOLE usecase (node + cicd-app-react-native-expo)
+#         before the file-filter narrows to .npmrc, so EVERY variable any file in
+#         those practices references must be defined here, or evaluation throws.
+variables:
+  projectName: app-example-native
+  organizationName: ahbode
+  infrastructureNamespaceId: aaa000
+  awsAccountId:
+    prep: '111111111111'
+    prod: '222222222222'
+  app:
+    web:
+      domain:
+        prep: example.prep.ahbode.dev
+        prod: example.ahbode.dev
+      port:
+        hot: 3447
+        cold: 3449

package/dist/practices/node/.test/assets/repo-expo-npmrc/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "app-example-native",
+  "version": "1.0.0"
+}

package/dist/practices/node/__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 🎉
+"
+`;