declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/lint/lint-cycles-command.declapract.integration.test.ts

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the shipped `test:lint:cycles` command (#601, #616): it reads `.dpdmrc.yaml`
+ *         with node and the `yaml` devDependency, never with `yq`, and fails closed.
+ * .why  = `yq` is a host binary that no practice declares, so the lint gate only worked on a box
+ *         that happened to have it. the old `// "^$"` fallback was dead syntax on top. node is the
+ *         one binary every adopter has, and `yaml` ships as a declared devDependency.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. the exclude expression is
+ *         lifted out of the command and run for real in a temp dir, so the test proves what an
+ *         adopter's shell computes, not merely the text of the command.
+ * .teeth = put the `yq` form back in best-practice/package.json and case1 goes red; drop the
+ *          `&&` and case3 goes red (a malformed `.dpdmrc.yaml` no longer stops the gate).
+ */
+const repoRoot = join(__dirname, '../../..');
+const shipped = JSON.parse(
+  readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+);
+const command: string = shipped.scripts['test:lint:cycles'];
+
+/**
+ * .what = the shell assignment that computes the dpdm exclude regex, lifted from the command
+ */
+const asExcludeAssignment = (input: { command: string }): string => {
+  const match = input.command.match(/^(EXCL=\$\(.+?\)) && dpdm /);
+  if (!match?.[1])
+    throw new Error(`no EXCL=$(...) && dpdm prefix in: ${input.command}`);
+  return match[1];
+};
+
+/**
+ * .what = run the exclude assignment in a dir that holds the given `.dpdmrc.yaml`
+ */
+const runExcludeAssignment = (input: {
+  dpdmrc: string;
+}): { stdout: string; exitCode: number } => {
+  const dir = genTempDir({ slug: 'lint-cycles-exclude' });
+  writeFileSync(join(dir, '.dpdmrc.yaml'), input.dpdmrc);
+  try {
+    const stdout = execFileSync(
+      'bash',
+      ['-c', `${asExcludeAssignment({ command })} && printf '%s' "$EXCL"`],
+      {
+        cwd: dir,
+        env: { ...process.env, NODE_PATH: join(repoRoot, 'node_modules') },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    ).toString();
+    return { stdout, exitCode: 0 };
+  } catch (error) {
+    // allowlist only the child-process exit; jest's vm realm defeats an `instanceof Error` test
+    if (typeof error !== 'object' || error === null || !('status' in error))
+      throw error;
+    return { stdout: '', exitCode: Number(error.status) };
+  }
+};
+
+describe('lint test:lint:cycles reads .dpdmrc.yaml via node + yaml (#601, #616)', () => {
+  given('[case1] the shipped command', () => {
+    when('[t0] its text is read', () => {
+      then('it holds no yq', () => {
+        expect(command).not.toContain('yq');
+      });
+
+      then('it holds no dead // "^$" fallback', () => {
+        expect(command).not.toContain('// \\"^$\\"');
+        expect(command).not.toContain('"^$"');
+      });
+
+      then('it requires yaml through node', () => {
+        expect(command).toContain("require('yaml')");
+      });
+
+      then('the command matches snapshot', () => {
+        expect(command).toMatchSnapshot('test:lint:cycles');
+      });
+    });
+  });
+
+  given('[case2] the shipped devDependencies', () => {
+    then('yaml is declared, so the require resolves in every adopter', () => {
+      expect(shipped.devDependencies.yaml).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+  });
+
+  given('[case3] the exclude expression, run in a real shell', () => {
+    when('[t0] .dpdmrc.yaml has the shipped empty exclude', () => {
+      then('it emits an empty regex and exits 0', () => {
+        expect(runExcludeAssignment({ dpdmrc: 'exclude: []\n' })).toEqual({
+          stdout: '',
+          exitCode: 0,
+        });
+      });
+    });
+
+    when('[t1] .dpdmrc.yaml has no exclude key', () => {
+      then('it emits an empty regex and exits 0', () => {
+        expect(runExcludeAssignment({ dpdmrc: '# no keys\n' })).toEqual({
+          stdout: '',
+          exitCode: 0,
+        });
+      });
+    });
+
+    when('[t2] .dpdmrc.yaml holds two adopter entries', () => {
+      then('it joins them with |', () => {
+        expect(
+          runExcludeAssignment({ dpdmrc: 'exclude:\n  - jest\n  - ^foo\n' }),
+        ).toEqual({ stdout: 'jest|^foo', exitCode: 0 });
+      });
+    });
+
+    when('[t3] .dpdmrc.yaml is malformed', () => {
+      then('it exits non-zero, so the gate fails closed', () => {
+        const result = runExcludeAssignment({ dpdmrc: 'exclude: [\n' });
+        expect(result.exitCode).not.toEqual(0);
+      });
+    });
+  });
+});

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

@@ -4,6 +4,9 @@ import path from 'node:path';
 import { executeApply } from 'declapract';
 import { genTempDir, given, then, useThen, when } from 'test-fns';
 
+// each executeApply evaluates the whole usecase; under full-suite load one apply runs past 100s
+jest.setTimeout(240_000);
+
 /**
  * .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
@@ -23,7 +26,7 @@ describe('logs/leveled-term removal', () => {
     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' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const pkgPath = 'package.json';

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

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`logs src review markers given: [case1] a repo with a leveled-log import and a vendored withLogTrail fork when: [t0] the input (before any fix) then: both src files match snapshot: fork — before 1`] = `
+"import { log } from './logger';
+
+/**
+ * enables input output logs for a function
+ *
+ * todo: - hookup visual tracing w/ external lib (vi...lo...)
+ */
+export const withInputOutputTracing = <T extends (...args: any[]) => any>(
+  logic: T,
+  options: { name: string; durationReportingThresholdInSeconds: number },
+): T => {
+  return (async (...args: any[]) => {
+    log.debug(\`\${options.name}.input\`, { args });
+    const result = await logic(...args);
+    log.debug(\`\${options.name}.output\`, { result });
+    return result;
+  }) as T;
+};
+"
+`;
+
+exports[`logs src review markers given: [case1] a repo with a leveled-log import and a vendored withLogTrail fork when: [t0] the input (before any fix) then: both src files match snapshot: op — before 1`] = `
+"import { generateLogMethods } from 'simple-leveled-log-methods';
+
+export const log = generateLogMethods();
+"
+`;
+
+exports[`logs src review markers given: [case1] a repo with a leveled-log import and a vendored withLogTrail fork when: [t1] the logs fixes are applied then: the fork gains one review line above its export, which names withLogTrail and (input, context) (#635): fork — after 1`] = `
+"import { log } from './logger';
+
+/**
+ * enables input output logs for a function
+ *
+ * todo: - hookup visual tracing w/ external lib (vi...lo...)
+ */
+// @declapract:review: this vendored copy of withLogTrail (it logs no error on a throw) is retired — move to visualogic's withLogTrail, the (input, context) shape: each op becomes \`(input, context) => …\`, a dependency (dbConnection, log) moves out of the input into the context arg, and each caller passes it as the 2nd arg. then delete this marker
+export const withInputOutputTracing = <T extends (...args: any[]) => any>(
+  logic: T,
+  options: { name: string; durationReportingThresholdInSeconds: number },
+): T => {
+  return (async (...args: any[]) => {
+    log.debug(\`\${options.name}.input\`, { args });
+    const result = await logic(...args);
+    log.debug(\`\${options.name}.output\`, { result });
+    return result;
+  }) as T;
+};
+"
+`;
+
+exports[`logs src review markers given: [case1] a repo with a leveled-log import and a vendored withLogTrail fork when: [t1] the logs fixes are applied then: the op gains one review line above its leveled-log import, which names sdk-logs (#643): op — after 1`] = `
+"// @declapract:review: simple-leveled-log-methods is retired — import the logs practice's \`log\` (src/utils/logger.ts, built by sdk-logs \`genLogMethods\`) in its place, then delete this marker
+import { generateLogMethods } from 'simple-leveled-log-methods';
+
+export const log = generateLogMethods();
+"
+`;

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

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

package/dist/practices/logs/bad-practices/leveled-term/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,43 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = an import (or require) of the retired `simple-leveled-log-methods`.
+ */
+const LEVELED_IMPORT_PATTERN =
+  /(?:\bfrom\s+|\brequire\(\s*|\bimport\(\s*)['"]simple-leveled-log-methods(?:\/[^'"]*)?['"]/;
+
+const REVIEW_MARKER =
+  "// @declapract:review: simple-leveled-log-methods is retired — import the logs practice's `log` (src/utils/logger.ts, built by sdk-logs `genLogMethods`) in its place, then delete this marker";
+
+/**
+ * .what = flags a src file that still imports `simple-leveled-log-methods`.
+ * .why  = the package.json half of this practice removes the dep; a file that still imports it
+ *         then fails tsc with no pointer to the move (#643). this check makes `plan` name each such
+ *         file by path, beside the dep removal.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents && LEVELED_IMPORT_PATTERN.test(contents)) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no import of simple-leveled-log-methods',
+  );
+};
+
+/**
+ * .what = stamps a review line above each such import that names the replacement.
+ * .why  = the move to sdk-logs changes how a log is built and passed, which a regex cannot know,
+ *         so the fix names the move beside the line tsc will fail on, and rewrites no code.
+ * .note = idempotent: an import already marked is left alone. the check stays red until a human
+ *         moves the import, so `plan` keeps the file in view.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: LEVELED_IMPORT_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/practices/logs/bad-practices/vendored-log-trail/.declapract.readme.md

@@ -0,0 +1,6 @@
+a vendored copy of visualogic's `withLogTrail`.
+
+the copy drifted from the library: it logs no error on a throw, so each op it wraps is silent when
+it fails, and it takes a variadic arg list where `withLogTrail` takes `(input, context)`. the move
+is a shape change at each op and each caller, so the fix stamps a `// @declapract:review:` line
+above the fork that names the move, and rewrites no code.

package/dist/practices/logs/bad-practices/vendored-log-trail/.test/assets/demo-repo-with-log-forks/declapract.use.yml

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

package/dist/practices/logs/bad-practices/vendored-log-trail/.test/assets/demo-repo-with-log-forks/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "simple-leveled-log-methods": "0.5.0"
+  }
+}

package/dist/practices/logs/bad-practices/vendored-log-trail/.test/assets/demo-repo-with-log-forks/src/domain.operations/getWaveReport.ts

@@ -0,0 +1,3 @@
+import { generateLogMethods } from 'simple-leveled-log-methods';
+
+export const log = generateLogMethods();

package/dist/practices/logs/bad-practices/vendored-log-trail/.test/assets/demo-repo-with-log-forks/src/utils/withInputOutputTracing.ts

@@ -0,0 +1,18 @@
+import { log } from './logger';
+
+/**
+ * enables input output logs for a function
+ *
+ * todo: - hookup visual tracing w/ external lib (vi...lo...)
+ */
+export const withInputOutputTracing = <T extends (...args: any[]) => any>(
+  logic: T,
+  options: { name: string; durationReportingThresholdInSeconds: number },
+): T => {
+  return (async (...args: any[]) => {
+    log.debug(`${options.name}.input`, { args });
+    const result = await logic(...args);
+    log.debug(`${options.name}.output`, { result });
+    return result;
+  }) as T;
+};

package/dist/practices/logs/bad-practices/vendored-log-trail/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,69 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asInputToContextReviewMarker } from '../../../../../../utils/asInputToContextReviewMarker';
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = the fingerprints of a vendored copy of visualogic's `withLogTrail`.
+ * .why  = the fork carries visualogic's jsdoc byte-for-byte, todos and all, and the option name
+ *         visualogic retired; either one marks a local copy rather than a use of the library.
+ */
+const FORK_FINGERPRINTS = [
+  /hookup visual tracing w\/ external lib/,
+  /\bdurationReportingThresholdInSeconds\b/,
+];
+
+/**
+ * .what = the first exported declaration of a file.
+ */
+const FIRST_EXPORT_PATTERN = /^export\s+(?:const|function)\s+\w+/m;
+
+/**
+ * .what = whether a file defines (rather than imports) a withLogTrail-shaped wrapper.
+ */
+const isVendoredLogTrail = (input: { contents: string }): boolean =>
+  FIRST_EXPORT_PATTERN.test(input.contents) &&
+  FORK_FINGERPRINTS.some((fingerprint) => fingerprint.test(input.contents));
+
+/**
+ * .what = a matcher for the line that opens with a given export declaration, read literally
+ */
+const asLineMatcherForExport = (input: { declaration: string }): RegExp =>
+  new RegExp(`^${input.declaration.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+
+const REVIEW_MARKER = asInputToContextReviewMarker({
+  from: 'this vendored copy of withLogTrail (it logs no error on a throw)',
+  into: "visualogic's withLogTrail",
+});
+
+/**
+ * .what = flags a src file that holds a vendored fork of visualogic's `withLogTrail`.
+ * .why  = the fork drifted: it has no error branch, so each op it wraps is silent when it fails,
+ *         and it takes a variadic arg list where withLogTrail takes `(input, context)` (#635).
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents && isVendoredLogTrail({ contents })) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no vendored withLogTrail fork in this file',
+  );
+};
+
+/**
+ * .what = stamps the shared input→context review line above the fork's first export.
+ * .why  = each op the fork wraps, and each caller, changes shape — the same move #626 names for
+ *         withDatabaseConnection, often at the same call sites — so the fix names the move once
+ *         and rewrites no code.
+ * .note = idempotent; the check stays red until a human moves the ops, so `plan` keeps it in view.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const firstExport = contents.match(FIRST_EXPORT_PATTERN)?.[0];
+  if (!firstExport) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: asLineMatcherForExport({ declaration: firstExport }),
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/practices/logs/src-markers.declapract.integration.test.ts

@@ -0,0 +1,96 @@
+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 that the logs src declarations stamp their review lines on a real repo.
+ * .why  = two src files the logs practice cannot rewrite safely: an import of the retired
+ *   `simple-leveled-log-methods` (#643) and a vendored withLogTrail fork (#635). each fix names the
+ *   move above the line, rewrites no code, and must converge on a re-apply.
+ * .note = the declarations dir is symlinked, so the consumer's own src/ holds the target files.
+ */
+describe('logs src review markers', () => {
+  given('[case1] a repo with a leveled-log import and a vendored withLogTrail fork', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-logs-src-markers',
+      clone:
+        './src/practices/logs/bad-practices/vendored-log-trail/.test/assets/demo-repo-with-log-forks',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/logs/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const forkPath = 'src/utils/withInputOutputTracing.ts';
+    const opPath = 'src/domain.operations/getWaveReport.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyOne = (input: { file: string }) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'logs',
+        file: input.file,
+      });
+    const applyFix = async () => {
+      await applyOne({ file: forkPath });
+      await applyOne({ file: opPath });
+    };
+
+    when('[t0] the input (before any fix)', () => {
+      then('both src files match snapshot', async () => {
+        expect(await read(forkPath)).toMatchSnapshot('fork — before');
+        expect(await read(opPath)).toMatchSnapshot('op — before');
+      });
+    });
+
+    when('[t1] the logs fixes are applied', () => {
+      const after = useThen('apply', async () => {
+        const before = { fork: await read(forkPath), op: await read(opPath) };
+        await applyFix();
+        return { before, fork: await read(forkPath), op: await read(opPath) };
+      });
+
+      then('the fork gains one review line above its export, which names withLogTrail and (input, context) (#635)', () => {
+        const lines = after.fork.split('\n');
+        const exportIndex = lines.findIndex((line) =>
+          line.startsWith('export const withInputOutputTracing'),
+        );
+        expect(lines[exportIndex - 1]).toContain('// @declapract:review:');
+        expect(lines[exportIndex - 1]).toContain("visualogic's withLogTrail");
+        expect(lines[exportIndex - 1]).toContain('(input, context)');
+        expect(after.fork.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.fork,
+        );
+        expect(after.fork).toMatchSnapshot('fork — after');
+      });
+
+      then('the op gains one review line above its leveled-log import, which names sdk-logs (#643)', () => {
+        const lines = after.op.split('\n');
+        expect(lines[0]).toContain('// @declapract:review:');
+        expect(lines[0]).toContain('sdk-logs');
+        expect(after.op.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.op,
+        );
+        expect(after.op).toMatchSnapshot('op — after');
+      });
+    });
+
+    when('[t2] the fixes are applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = { fork: await read(forkPath), op: await read(opPath) };
+        await applyFix();
+        const after = { fork: await read(forkPath), op: await read(opPath) };
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

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

@@ -2,7 +2,9 @@ import fs from 'fs/promises';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
-import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
 
 // executeApply is slow (full practice evaluation), so widen the jest budget
 jest.setTimeout(180_000); // 3 minutes
@@ -21,13 +23,11 @@ jest.setTimeout(180_000); // 3 minutes
  */
 describe('node practice .npmrc — expo hoisted linker', () => {
   given('[case1] an expo consumer repo with a base node .npmrc', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       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' },
-      ],
+      declarations: './src/.test/assets/expo/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     const npmrcPath = () => path.join(tempDir, '.npmrc');
@@ -109,13 +109,11 @@ describe('node practice .npmrc — expo hoisted linker', () => {
    *         and rewrite the file to base).
    */
   given('[case2] a narrow --practice node apply on an expo repo keeps the hoist', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       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' },
-      ],
+      declarations: './src/.test/assets/expo/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     const npmrcPath = () => path.join(tempDir, '.npmrc');
@@ -162,4 +160,104 @@ describe('node practice .npmrc — expo hoisted linker', () => {
       });
     });
   });
+
+  /**
+   * .what = the hoist flip prints the version contention set + the pnpm.overrides remedy (#610)
+   * .why  = under the hoisted linker one copy of each package wins the root slot; the runtime
+   *         symptoms name no package, so the set is printed at the one moment the practice can
+   *         enumerate it. once per root, on stderr, and the written .npmrc is unchanged by it
+   */
+  given('[case3] an expo repo whose lockfile holds two versions of a package', () => {
+    const tempDir = genTempRepoWithDeclarationsOutside({
+      slug: 'node-npmrc-expo-contention',
+      clone: './src/practices/node/.test/assets/repo-expo-npmrc',
+      declarations: './src/.test/assets/expo/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
+    });
+
+    const readState = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+
+      // a lockfile with two contended packages and one sole package
+      await fs.writeFile(
+        path.join(tempDir, 'pnpm-lock.yaml'),
+        [
+          "lockfileVersion: '9.0'",
+          '',
+          'packages:',
+          '',
+          "  '@commitlint/cli@17.8.1':",
+          '    resolution: {integrity: sha512-a}',
+          '',
+          "  '@commitlint/cli@19.5.0':",
+          '    resolution: {integrity: sha512-b}',
+          '',
+          '  type-fns@0.8.1:',
+          '    resolution: {integrity: sha512-c}',
+          '',
+          '  type-fns@1.21.3:',
+          '    resolution: {integrity: sha512-d}',
+          '',
+          '  yaml@2.8.2:',
+          '    resolution: {integrity: sha512-e}',
+          '',
+        ].join('\n'),
+      );
+
+      // capture stderr across two applies
+      const writes: string[] = [];
+      const spy = jest
+        .spyOn(process.stderr, 'write')
+        .mockImplementation((chunk: string | Uint8Array) => {
+          writes.push(String(chunk));
+          return true;
+        });
+      try {
+        await executeApply({ config, file: '.npmrc' });
+        const afterFirst = writes.join('');
+        const npmrc = await fs.readFile(path.join(tempDir, '.npmrc'), 'utf-8');
+        await executeApply({ config, file: '.npmrc' });
+        const afterSecond = writes.join('');
+        return { afterFirst, afterSecond, npmrc };
+      } finally {
+        spy.mockRestore();
+      }
+    }, 170_000);
+
+    when('[t0] the first apply flips the linker to hoisted', () => {
+      then('stderr names each contended package with its versions', () => {
+        expect(readState.afterFirst).toContain(
+          '🟡 node-linker=hoisted added — one copy of each package now wins the root slot',
+        );
+        expect(readState.afterFirst).toContain('@commitlint/cli  17.8.1, 19.5.0');
+        expect(readState.afterFirst).toContain('type-fns         0.8.1, 1.21.3');
+        expect(readState.afterFirst).not.toContain('yaml');
+      });
+
+      then('stderr cites the pnpm.overrides remedy and the brief', () => {
+        expect(readState.afterFirst).toContain('pnpm.overrides');
+        expect(readState.afterFirst).toContain('howto.pnpm-expo-hoisted-linker.md');
+      });
+
+      then('the notice prints once', () => {
+        expect(readState.afterFirst.split('node-linker=hoisted added').length - 1).toEqual(1);
+      });
+
+      then('the notice and the .npmrc match snapshot', () => {
+        const notice = readState.afterFirst.slice(
+          readState.afterFirst.indexOf('🟡 node-linker=hoisted added'),
+        );
+        expect(notice.slice(0, notice.indexOf('\n\n') + 1)).toMatchSnapshot(
+          'hoist flip notice',
+        );
+        expect(readState.npmrc).toMatchSnapshot('.npmrc — after the flip');
+      });
+    });
+
+    when('[t1] a second apply runs on the hoisted repo', () => {
+      then('no second notice prints', () => {
+        expect(readState.afterSecond.split('node-linker=hoisted added').length - 1).toEqual(1);
+      });
+    });
+  });
 });

package/dist/practices/node/.test/assets/repo-readme-without-title/declapract.declare.yml

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

package/dist/practices/node/.test/assets/repo-readme-without-title/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/practices/node/.test/assets/repo-readme-without-title/package.json

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

package/dist/practices/node/.test/assets/repo-readme-without-title/readme.md

@@ -0,0 +1,5 @@
+surf lessons, booked.
+
+## usage
+
+book a lesson with `npm run book`.