declapract-typescript-ehmpathy 0.49.13 → 0.49.14

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

@@ -22,3 +22,32 @@ save-exact=true
 message=%s 🎉
 "
 `;
+
+exports[`node practice .npmrc — expo hoisted linker given: [case3] an expo repo whose lockfile holds two versions of a package when: [t0] the first apply flips the linker to hoisted then: the notice and the .npmrc match snapshot: .npmrc — after the flip 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: [case3] an expo repo whose lockfile holds two versions of a package when: [t0] the first apply flips the linker to hoisted then: the notice and the .npmrc match snapshot: hoist flip notice 1`] = `
+"🟡 node-linker=hoisted added — one copy of each package now wins the root slot
+   ├─ packages with more than one version in your graph
+   │  ├─ @commitlint/cli  17.8.1, 19.5.0
+   │  └─ type-fns         0.8.1, 1.21.3
+   │
+   └─ remedy
+      ├─ any package above may now load a different copy at runtime
+      ├─ pin the copy you want via \`pnpm.overrides\` in package.json, then \`pnpm install\`
+      └─ see howto.pnpm-expo-hoisted-linker.md (declapract-typescript-ehmpathy)
+"
+`;

package/dist/practices/node/__snapshots__/readme.md.declapract.integration.test.ts.snap

@@ -0,0 +1,21 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`node readme.md title prepend (#607) given: [case1] a repo whose readme.md lacks the declared title when: [t0] the input (before any fix) then: the readme.md input matches snapshot: readme.md — before 1`] = `
+"surf lessons, booked.
+
+## usage
+
+book a lesson with \`npm run book\`.
+"
+`;
+
+exports[`node readme.md title prepend (#607) given: [case1] a repo whose readme.md lacks the declared title when: [t1] the readme.md fix is applied then: the readme.md matches snapshot: readme.md — after 1`] = `
+"# svc-example
+
+surf lessons, booked.
+
+## usage
+
+book a lesson with \`npm run book\`.
+"
+`;

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

@@ -33,7 +33,7 @@ describe('node/self-deps-not-link removal', () => {
     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' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const pkgPath = 'package.json';

package/dist/practices/node/bad-practices/self-deps-not-link/.test/assets/demo-repo-with-self-deps/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/node/bad-practices/self-deps-not-link/package.json.declapract.ts

@@ -1,5 +1,8 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
+import { isJsonObject } from '../../../../utils/asJsonMergedDeep';
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+
 const DEP_KEYS = [
   'dependencies',
   'devDependencies',
@@ -7,19 +10,31 @@ const DEP_KEYS = [
   'optionalDependencies',
 ] as const;
 
+const PRACTICE = 'node/self-deps-not-link';
+
+/**
+ * .what = the package's own name, or null where package.json names none
+ * .why  = a self-dep is keyed by this name; a non-string `name` names no package to match
+ */
+const getOnePackageName = (input: {
+  packageJson: Record<string, unknown>;
+}): string | null =>
+  typeof input.packageJson.name === 'string' ? input.packageJson.name : null;
+
 /**
  * .what = finds self-dependencies that are not `link:.`
+ * .why  = check and fix read one list, so the flag and the repair agree on which deps are bad
  */
 const findBadSelfDeps = (
   packageJson: Record<string, unknown>,
 ): { depKey: string; version: string }[] => {
-  const packageName = packageJson.name as string | undefined;
+  const packageName = getOnePackageName({ packageJson });
   if (!packageName) return [];
 
   return DEP_KEYS.flatMap((depKey) => {
-    const deps = packageJson[depKey] as Record<string, string> | undefined;
-    const selfDepVersion = deps?.[packageName];
-    if (selfDepVersion && selfDepVersion !== 'link:.')
+    const deps = packageJson[depKey];
+    const selfDepVersion = isJsonObject(deps) ? deps[packageName] : undefined;
+    if (typeof selfDepVersion === 'string' && selfDepVersion !== 'link:.')
       return [{ depKey, version: selfDepVersion }];
     return [];
   });
@@ -28,7 +43,7 @@ const findBadSelfDeps = (
 export const check: FileCheckFunction = (contents) => {
   if (!contents) throw new Error('no package.json found');
 
-  const packageJson = JSON.parse(contents);
+  const packageJson = asPackageJSON({ contents }, { practice: PRACTICE });
   const badSelfDeps = findBadSelfDeps(packageJson);
 
   // bad practice semantics: return = detected, throw = not detected
@@ -40,8 +55,8 @@ export const check: FileCheckFunction = (contents) => {
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return { contents };
 
-  const packageJson = JSON.parse(contents);
-  const packageName = packageJson.name as string | undefined;
+  const packageJson = asPackageJSON({ contents }, { practice: PRACTICE });
+  const packageName = getOnePackageName({ packageJson });
   if (!packageName) return { contents };
 
   const badSelfDeps = findBadSelfDeps(packageJson);
@@ -52,12 +67,9 @@ export const fix: FileFixFunction = (contents) => {
   // 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 (!badDepKeys.has(key) || !isJsonObject(value)) return [[key, value]];
 
-      const { [packageName]: _selfDep, ...rest } = value as Record<
-        string,
-        string
-      >;
+      const { [packageName]: _selfDep, ...rest } = value;
       if (Object.keys(rest).length === 0) return [];
       return [[key, rest]];
     }),

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

@@ -2,6 +2,8 @@ import type { FileCheckFunction, FileFixFunction } from 'declapract';
 import { ConstraintError } from 'helpful-errors';
 
 import { defineExpectedNpmrcContents } from '../../../utils/defineExpectedNpmrcContents';
+import { getFileTextOrNull } from '../../../utils/getFileTextOrNull';
+import { getOneContentionSetFromLockfile } from '../../../utils/getOneContentionSetFromLockfile';
 
 /**
  * .what = the `.npmrc` the node practice declares, usecase-aware for the expo runtime
@@ -58,7 +60,87 @@ export const check: FileCheckFunction = (contents, context) => {
  *         test's narrow-scope `[case2]`.
  */
 export const fix: FileFixFunction = (contents, context) => {
-  return {
-    contents: defineExpectedContents(contents, context.projectPractices),
-  };
+  // emit the declared contents
+  const contentsFixed = defineExpectedContents(
+    contents,
+    context.projectPractices,
+  );
+
+  // if this fix flips the linker to hoisted, name the version contention it makes decisive
+  if (isHoistFlip({ before: contents, after: contentsFixed }))
+    emitHoistFlipNoticeOnce({ root: context.getProjectRootDirectory() });
+
+  return { contents: contentsFixed };
+};
+
+/**
+ * .what = whether a fix adds `node-linker=hoisted` to a file that lacked it
+ */
+const isHoistFlip = (input: { before: string | null; after: string }) =>
+  !(input.before ?? '').split('\n').includes('node-linker=hoisted') &&
+  input.after.split('\n').includes('node-linker=hoisted');
+
+/**
+ * .what = the roots whose hoist flip notice was already printed in this process
+ * .why  = declapract may evaluate a fix more than once per apply; the notice prints once
+ * .note = deliberate module-scope state: a print-once guard, never read for a decision
+ */
+const rootsNoticed = new Set<string>();
+
+/**
+ * .what = prints the version contention set + the pnpm.overrides remedy to stderr, once per root
+ * .why  = the hoist flip makes one copy of each package win the root slot (#610). the runtime
+ *         symptoms (a crashed commit-msg hook, a blank page) name no package, so the set is
+ *         printed at the one moment the practice can enumerate it. no version pin is shipped:
+ *         the consumer chooses the pins
+ * .note = writes to stderr only, so the fix's output contents stay pure
+ */
+const emitHoistFlipNoticeOnce = (input: { root: string }): void => {
+  // print once per root
+  if (rootsNoticed.has(input.root)) return;
+  rootsNoticed.add(input.root); // .note = deliberate mutation: the print-once guard records this root
+
+  // read the lockfile, if one is present
+  const lockfile = getFileTextOrNull({
+    root: input.root,
+    relativePath: 'pnpm-lock.yaml',
+  });
+  const contention = lockfile
+    ? getOneContentionSetFromLockfile({ lockfile })
+    : null;
+
+  process.stderr.write(asHoistFlipNotice({ contention }));
+};
+
+/**
+ * .what = the treestruct notice for a hoist flip
+ */
+const asHoistFlipNotice = (input: {
+  contention: { name: string; versions: string[] }[] | null;
+}): string => {
+  const header =
+    '🟡 node-linker=hoisted added — one copy of each package now wins the root slot\n';
+  const remedy = [
+    '   └─ remedy',
+    '      ├─ any package above may now load a different copy at runtime',
+    '      ├─ pin the copy you want via `pnpm.overrides` in package.json, then `pnpm install`',
+    '      └─ see howto.pnpm-expo-hoisted-linker.md (declapract-typescript-ehmpathy)',
+  ].join('\n');
+
+  // no lockfile: say how to see the set
+  if (input.contention === null)
+    return `${header}   ├─ no pnpm-lock.yaml found; after \`pnpm install\`, run \`pnpm why <pkg>\` to see the versions\n${remedy}\n\n`;
+
+  // no contention: say so
+  if (input.contention.length === 0)
+    return `${header}   ├─ no package has more than one version in your graph\n${remedy}\n\n`;
+
+  // list the contention set
+  const contention = input.contention;
+  const width = Math.max(...contention.map((pkg) => pkg.name.length));
+  const rows = contention.map(
+    (pkg, index) =>
+      `   │  ${index === contention.length - 1 ? '└─' : '├─'} ${pkg.name.padEnd(width)}  ${pkg.versions.join(', ')}`,
+  );
+  return `${header}   ├─ packages with more than one version in your graph\n${rows.join('\n')}\n   │\n${remedy}\n\n`;
 };

package/dist/practices/node/best-practice/readme.md.declapract.ts

@@ -1,3 +1,21 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, type FileFixFunction } from 'declapract';
 
-export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)
+/**
+ * .what = the readme must contain the declared title line (default is equals)
+ */
+export const check = FileCheckType.CONTAINS;
+
+/**
+ * .what = writes the declared title where the readme is absent, and puts it atop a readme that
+ *         lacks it; the adopter's own text is kept below it
+ * .why  = declapract's own CONTAINS fix writes only an absent file, so a present readme without
+ *         the title had no fix, and core marked the file manual (#607). a readme that already
+ *         holds the title is returned unchanged, so a second fix is a no-op (#536)
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const declared = context.declaredFileContents ?? '';
+  if (!contents) return { contents: declared };
+  // the same includes test the CONTAINS check makes, so the fix agrees with the check
+  if (contents.includes(declared)) return { contents };
+  return { contents: `${declared}\n${contents}` };
+};

package/dist/practices/node/readme.md.declapract.integration.test.ts

@@ -0,0 +1,77 @@
+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 readme.md fix (#607), run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo whose readme.md lacks the declared title.
+ * .why  = declapract's own CONTAINS fix writes only an ABSENT file, so a present readme without the
+ *   title had no fix and core marked it manual. the custom fix prepends the title atop the
+ *   adopter's own text. a unit test of the fix is necessary but NOT sufficient
+ *   (`rule.require.declapract-integration-tests`): only the pipeline proves the
+ *   `@declapract{variable.projectName}` substitution feeds the right `declaredFileContents`, that
+ *   the CONTAINS check gates the custom fix, and that a second apply is a no-op on the real file.
+ */
+describe('node readme.md title prepend (#607)', () => {
+  given('[case1] a repo whose readme.md lacks the declared title', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-node-readme-without-title',
+      clone: './src/practices/node/.test/assets/repo-readme-without-title',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    const readmePath = 'readme.md';
+    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: readmePath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the readme.md input matches snapshot', async () => {
+        expect(await read(readmePath)).toMatchSnapshot('readme.md — before');
+      });
+    });
+
+    when('[t1] the readme.md fix is applied', () => {
+      const result = useThen('the apply succeeds', async () => {
+        await applyFix();
+        return { contents: await read(readmePath) };
+      });
+
+      then('the readme opens with the declared title, substituted from the projectName', () => {
+        expect(result.contents.startsWith('# svc-example\n')).toEqual(true);
+      });
+
+      then("the adopter's own text is kept below the title", () => {
+        expect(result.contents).toContain('surf lessons, booked.');
+        expect(result.contents).toContain('book a lesson with `npm run book`.');
+      });
+
+      then('no @declapract marker leaked into the output', () => {
+        expect(result.contents).not.toContain('@declapract{');
+      });
+
+      then('the readme.md matches snapshot', () => {
+        expect(result.contents).toMatchSnapshot('readme.md — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const result = useThen('a second apply over its own output', async () => {
+        const before = await read(readmePath);
+        await applyFix();
+        return { before, after: await read(readmePath) };
+      });
+
+      then('the second apply changes zero bytes — the title is not prepended twice', () => {
+        expect(result.after).toEqual(result.before);
+      });
+    });
+  });
+});

package/dist/practices/node-service/.declapract.integration.test.ts

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, when } from 'test-fns';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
+
+/**
+ * .what = holds the `sdkAwsLambdaAskAncient` template to its runtime behavior (#631)
+ * .why  = an ancient peer differs on two axes at once — the `-dev-` address and the flat payload.
+ *         the helper exists to bind both, so this test runs the real template source and asserts
+ *         the ask it makes carries BOTH: `struct: { payload: 'ancient' }` and the ancient slug.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads the template file. the
+ *         template's imports look up in the consumer's tree, so it is transpiled and run with
+ *         stubs for `sdk-aws-lambda` and the env helper (the environments practice's exemplar).
+ */
+
+const ASK_ANCIENT_PATH = `${__dirname}/best-practice/src/access/sdks/sdkAwsLambdaAskAncient.ts`;
+
+/**
+ * .what = run the template once, with the ancient env helper stubbed to a given slug, and return
+ *         the args the template handed to `askLambdaEndpoint`
+ */
+const runAskAncient = async (input: {
+  slug: 'dev' | 'prod';
+}): Promise<{ input: any; context: any }> => {
+  const calls: { input: any; context: any }[] = [];
+  const requireStub = (id: string): unknown => {
+    if (id === 'sdk-aws-lambda')
+      return {
+        askLambdaEndpoint: async (askInput: any, askContext: any) => {
+          calls.push({ input: askInput, context: askContext });
+          return { ok: true };
+        },
+      };
+    if (id.includes('sdkAwsLambdaEnvAccessAncient'))
+      return { sdkAwsLambdaEnvAccessAncient: () => input.slug };
+    return {};
+  };
+  const { sdkAwsLambdaAskAncient } = getModuleExportsFromTsSource<{
+    sdkAwsLambdaAskAncient: (input: any, context: any) => Promise<unknown>;
+  }>({ source: readFileSync(ASK_ANCIENT_PATH, 'utf8'), requireStub });
+  await sdkAwsLambdaAskAncient!(
+    { which: { service: 'svc-widgets', function: 'getWidget' }, event: { uuid: 'w-1' } },
+    { log: console },
+  );
+  return calls[0]!;
+};
+
+describe('node-service — sdkAwsLambdaAskAncient (#631)', () => {
+  given('[case1] the template, run below prod', () => {
+    when('[t0] it asks an ancient peer', () => {
+      then('it sends the bare event in the ancient payload struct, to the dev slug', async () => {
+        const call = await runAskAncient({ slug: 'dev' });
+        expect(call.input).toEqual({
+          which: { service: 'svc-widgets', function: 'getWidget' },
+          event: { uuid: 'w-1' },
+          struct: { payload: 'ancient' },
+        });
+        expect(call.context.env.access).toEqual('dev');
+        expect(call.context.log).toBe(console);
+      });
+    });
+  });
+
+  given('[case2] the template, run at prod', () => {
+    then('it addresses the prod slug, still in the ancient struct', async () => {
+      const call = await runAskAncient({ slug: 'prod' });
+      expect(call.context.env.access).toEqual('prod');
+      expect(call.input.struct).toEqual({ payload: 'ancient' });
+    });
+  });
+
+  given('[case3] the template source', () => {
+    then('it holds exactly one documented cast, tied to sdk-aws-lambda#42', () => {
+      const source = readFileSync(ASK_ANCIENT_PATH, 'utf8');
+      expect(source.match(/\) as [A-Z]\w+/g)).toEqual([
+        ') as EnvironmentAccessTier',
+      ]);
+      expect(source).toContain('sdk-aws-lambda#42');
+      expect(source).toMatchSnapshot('sdkAwsLambdaAskAncient.ts source');
+    });
+
+    then('its context cache is typed by TResponse, not unknown (F88: TS2345 on every lambda usecase)', () => {
+      // `AskLambdaEndpointContext` is `Parameters<typeof askLambdaEndpoint>[1]`, which fixes the
+      // cache to `SimpleCache<unknown>`; hand that to `askLambdaEndpoint<TRequest, TResponse>` and
+      // tsc rejects it. the context must come from the generic instantiated on this call's types.
+      const source = readFileSync(ASK_ANCIENT_PATH, 'utf8');
+      expect(source).not.toContain('AskLambdaEndpointContext');
+      expect(source).toContain(
+        'Parameters<typeof askLambdaEndpoint<TRequest, TResponse>>[1]',
+      );
+    });
+  });
+});

package/dist/practices/node-service/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,44 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`node-service — sdkAwsLambdaAskAncient (#631) given: [case3] the template source then: it holds exactly one documented cast, tied to sdk-aws-lambda#42: sdkAwsLambdaAskAncient.ts source 1`] = `
+"import { askLambdaEndpoint } from 'sdk-aws-lambda';
+import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { sdkAwsLambdaEnvAccessAncient } from '@src/access/sdks/sdkAwsLambdaEnvAccessAncient';
+
+/**
+ * .what = ask an ancient peer — one that publishes \`-dev-\` only, and reads a flat event.
+ * .why  = an ancient peer differs from a contemp one on two axes at once: its address (the legacy
+ *         \`dev\` slug below prod) and its payload (a bare event, never the \`{ event, trail }\`
+ *         envelope). a caller that sets one and forgets the other reaches a lambda that 404s, or
+ *         one that reads \`undefined\` for every field. this helper binds both, so neither can be
+ *         set alone.
+ * .note = the helper choice IS the migration ledger, with \`sdkAwsLambdaEnvAccessAncient\`: once
+ *         \`grep Ancient\` reaches zero, both retire, and each caller moves to \`askLambdaEndpoint\`.
+ */
+export const sdkAwsLambdaAskAncient = <TRequest, TResponse>(
+  input: { which: { service: string; function: string }; event: TRequest },
+  // the context of askLambdaEndpoint as instantiated on THIS call's types, so \`cache.response\`
+  // is a SimpleCache<TResponse>; the sdk's exported context type pins it to <unknown>
+  context: Omit<
+    Parameters<typeof askLambdaEndpoint<TRequest, TResponse>>[1],
+    'env'
+  > & {
+    env?: { region?: string };
+  },
+): Promise<TResponse> =>
+  askLambdaEndpoint<TRequest, TResponse>(
+    { which: input.which, event: input.event, struct: { payload: 'ancient' } },
+    {
+      ...context,
+      env: {
+        ...context.env,
+        // .cast = askLambdaEndpoint types \`env.access\` as the access set, which has no \`dev\`;
+        //   the ancient slug is the one value it must carry here. remove this cast once
+        //   sdk-aws-lambda#42 releases a \`dev\`-aware access type.
+        access: sdkAwsLambdaEnvAccessAncient() as EnvironmentAccessTier,
+      },
+    },
+  );
+"
+`;

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.declapract.integration.test.ts

@@ -0,0 +1,101 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply evaluates the whole practice, so grant a generous limit
+jest.setTimeout(300_000);
+
+/**
+ * .what = end-to-end proof of the adhoc-lambda-clients marker, through the REAL declapract apply
+ *         pipeline against a genTempDir clone of a repo with hand-written and generated clients
+ * .why  = a unit test of the transformer never proves the `src/access/sdks/svc*` and
+ *         `src/data/clients/svc*` globs match, that `relativeFilePath` reaches the fix, or that a
+ *         generated client is left alone on disk (#532)
+ */
+describe('adhoc-lambda-clients (#532)', () => {
+  given('[case1] a repo with two hand-written clients and one generated client', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-adhoc-lambda-clients',
+      clone:
+        './src/practices/node-service/bad-practices/adhoc-lambda-clients/.test/assets/demo-repo-with-adhoc-lambda-clients',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/node-service/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const sdksJobs = 'src/access/sdks/svcJobs.ts';
+    const clientsQuotes = 'src/data/clients/svcQuotes.ts';
+    const sdksUsers = 'src/access/sdks/svcUsers.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const readAll = async () => ({
+      jobs: await read(sdksJobs),
+      quotes: await read(clientsQuotes),
+      users: await read(sdksUsers),
+    });
+    const applyAll = async () => {
+      for (const file of [sdksJobs, clientsQuotes, sdksUsers])
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'node-service',
+          file,
+        });
+    };
+
+    when('[t0] the input, before any fix', () => {
+      then('no client carries a review marker', async () => {
+        const before = await readAll();
+        expect(before.jobs).not.toContain('@declapract:review');
+        expect(before.quotes).not.toContain('@declapract:review');
+        expect(before.jobs).toMatchSnapshot('svcJobs.ts — before');
+        expect(before.quotes).toMatchSnapshot('svcQuotes.ts — before');
+      });
+    });
+
+    when('[t1] the node-service practice is applied', () => {
+      const afterFirst = useThen('apply each client file', async () => {
+        const before = await readAll();
+        await applyAll();
+        return { before, after: await readAll() };
+      });
+
+      then('each hand-written client names the codegen for its own peer', () => {
+        expect(afterFirst.after.jobs.split('\n')[0]).toContain(
+          'npx sdk-aws-lambda gen --for svc-jobs --into src/access/svcs/ --env prep',
+        );
+        expect(afterFirst.after.quotes.split('\n')[0]).toContain(
+          'npx sdk-aws-lambda gen --for svc-quotes --into src/access/svcs/ --env prep',
+        );
+        expect(afterFirst.after.jobs).toMatchSnapshot('svcJobs.ts — after');
+        expect(afterFirst.after.quotes).toMatchSnapshot('svcQuotes.ts — after');
+      });
+
+      then('the client bodies are left as found', () => {
+        expect(afterFirst.after.jobs.endsWith(afterFirst.before.jobs)).toBe(true);
+        expect(afterFirst.after.quotes.endsWith(afterFirst.before.quotes)).toBe(true);
+      });
+
+      then('the generated client is left alone', () => {
+        expect(afterFirst.after.users).toEqual(afterFirst.before.users);
+      });
+    });
+
+    when('[t2] the practice is applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = await readAll();
+        await applyAll();
+        return { before, after: await readAll() };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.declapract.readme.md

@@ -0,0 +1,26 @@
+# adhoc-lambda-clients
+
+## what
+
+flags a hand-written lambda client — a `svc*.ts` under `src/access/sdks/` or the legacy
+`src/data/clients/` that wraps `askLambdaEndpoint` — with a review marker on line one.
+
+## why
+
+a hand-transcribed client drifts from its peer's contract with no signal until a call fails at
+runtime. `sdk-aws-lambda gen` emits a typed client from the peer's live contract, so drift becomes
+a reviewable diff on the next re-run (#532).
+
+## the paved path
+
+```sh
+npx sdk-aws-lambda gen --for svc-jobs --into src/access/svcs/ --env prep
+```
+
+move callers onto the generated sdk, then delete the hand-written file.
+
+## scope
+
+- marks only; the generated sdk changes the import shape a caller uses, so no rewrite is attempted
+- a file that mentions `sdk-aws-lambda gen` anywhere (as the codegen banner does) is left alone
+- a file already marked is left alone, so a re-apply is a no-op

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.test/assets/demo-repo-with-adhoc-lambda-clients/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/node-service symlink to the real practice).
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.test/assets/demo-repo-with-adhoc-lambda-clients/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "sdk-aws-lambda": "0.7.1"
+  }
+}

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.test/assets/demo-repo-with-adhoc-lambda-clients/src/access/sdks/svcJobs.ts

@@ -0,0 +1,10 @@
+import { askLambdaEndpoint, type AskLambdaEndpointContext } from 'sdk-aws-lambda';
+
+export const getJob = (
+  event: { jobUuid: string },
+  context: AskLambdaEndpointContext,
+): Promise<{ job: { uuid: string } | null }> =>
+  askLambdaEndpoint(
+    { which: { service: 'svc-jobs', function: 'getJob' }, event },
+    context,
+  );

package/dist/practices/node-service/bad-practices/adhoc-lambda-clients/.test/assets/demo-repo-with-adhoc-lambda-clients/src/access/sdks/svcUsers.ts

@@ -0,0 +1,11 @@
+// generated by `sdk-aws-lambda gen` — do not edit; re-run to update
+import { askLambdaEndpoint, type AskLambdaEndpointContext } from 'sdk-aws-lambda';
+
+export const getUser = (
+  event: { userUuid: string },
+  context: AskLambdaEndpointContext,
+): Promise<{ user: { uuid: string } | null }> =>
+  askLambdaEndpoint(
+    { which: { service: 'svc-users', function: 'getUser' }, event },
+    context,
+  );