declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-client/src/<star><star>/<star>.ts.declapract.ts

@@ -1,5 +1,8 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
+import { asObjectLiteralProps } from '../../../../../../utils/asObjectLiteralProps';
+import { withEachCallRewritten } from '../../../../../../utils/withEachCallRewritten';
+
 /**
  * .what = detects simple-lambda-client imports in source files
  * .why = simple-lambda-client should be replaced with sdk-aws-lambda
@@ -14,31 +17,82 @@ export const check: FileCheckFunction = (contents) => {
 };
 
 /**
- * .what = transforms simple-lambda-client imports to sdk-aws-lambda
+ * .what = `invokeLambdaFunction({ service, function, stage, event, cache? })` →
+ *         `sdkAwsLambdaAskAncient({ which: { service, function }, event }, { log, cache? })`
+ * .why  = a simple-lambda-client caller sends a flat event to the peer's `-dev-` name below prod —
+ *         the ancient address and the ancient payload together. `sdkAwsLambdaAskAncient` binds
+ *         both, so the move keeps the wire identical (#631). `stage` and `logDebug` have no slot:
+ *         the slug comes from the env helper, the logger from the context.
+ */
+const asAskAncientCall = (input: { argsText: string }): string => {
+  // a non-literal argument cannot be read field by field; rename the callee alone, so tsc names it
+  const objectText = input.argsText.trim();
+  if (!objectText.startsWith('{') || !objectText.endsWith('}'))
+    return `sdkAwsLambdaAskAncient(${input.argsText})`;
+
+  // the props, each read by key; a shorthand prop reads its own name
+  const props = asObjectLiteralProps({ body: objectText.slice(1, -1) });
+  const valueAt = (key: string): string | null => {
+    const prop = props.find((each) => each.key === key);
+    if (!prop) return null;
+    return prop.value ?? key;
+  };
+  const asShifted = (text: string) => text.replace(/\n/g, '\n  ');
+  const cache = valueAt('cache');
+
+  return [
+    'sdkAwsLambdaAskAncient(',
+    '  {',
+    `    which: { service: ${valueAt('service')}, function: ${valueAt('function')} },`,
+    `    event: ${asShifted(valueAt('event') ?? 'undefined')},`,
+    '  },',
+    cache ? `  { log, cache: { response: ${cache} } },` : '  { log },',
+    ')',
+  ].join('\n');
+};
+
+/**
+ * .what = transforms simple-lambda-client usage to sdk-aws-lambda
  * .why = automated migration reduces manual toil
  *
- * .note = basic transforms only; complex patterns require manual fix
- *
- * API map:
- * - invokeLambdaFunction → askLambdaEndpoint
+ * API map (#631):
+ * - invokeLambdaFunction(…) → sdkAwsLambdaAskAncient(…), from the node-service helper
+ * - every other imported name → the same name, from sdk-aws-lambda
  */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};
 
-  const updated = contents
-    // transform imports
-    .replace(
-      /import\s+\{([^}]*)\}\s+from\s+['"]simple-lambda-client['"]/g,
-      (match, imports) => {
-        const updatedImports = imports.replace(
-          /invokeLambdaFunction/g,
-          'askLambdaEndpoint',
-        );
-        return `import {${updatedImports}} from 'sdk-aws-lambda'`;
-      },
-    )
-    // transform function calls
-    .replace(/invokeLambdaFunction/g, 'askLambdaEndpoint');
+  // the import: invokeLambdaFunction moves to the helper; any other name to sdk-aws-lambda
+  const imported = contents.replace(
+    /import\s*\{([^}]*)\}\s*from\s*['"]simple-lambda-client['"];?/g,
+    (_match, clause: string) => {
+      const names = clause
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+      const rest = names.filter((name) => name !== 'invokeLambdaFunction');
+      const usesInvoke = names.length !== rest.length;
+      const hasLog = /import\s*\{[^}]*\blog\b[^}]*\}\s*from/.test(contents);
+      return [
+        ...(rest.length
+          ? [`import { ${rest.join(', ')} } from 'sdk-aws-lambda';`]
+          : []),
+        ...(usesInvoke
+          ? [
+              "import { sdkAwsLambdaAskAncient } from '@src/access/sdks/sdkAwsLambdaAskAncient';",
+              ...(hasLog ? [] : ["import { log } from '@src/utils/logger';"]),
+            ]
+          : []),
+      ].join('\n');
+    },
+  );
+
+  // each call, onto the ancient ask helper
+  const updated = withEachCallRewritten({
+    contents: imported,
+    callee: 'invokeLambdaFunction',
+    rewrite: asAskAncientCall,
+  });
 
   return { contents: updated };
 };

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.declapract.integration.test.ts

@@ -20,7 +20,7 @@ jest.setTimeout(180_000);
  * .note = the target file is snapshotted in full (before AND after), so a reviewer can eyeball the
  *   exact end-state, per rule.require.declapract-integration-tests.
  * .teeth = the input imports + CALLS `createApiGatewayHandler`. the after-state proves the import is
- *   rewritten to `sdk-aws-lambda`, the call is rewritten to `genLambdaEndpoint.for.apiGateway`, and
+ *   rewritten to `sdk-aws-lambda`, the call is rewritten to `genLambdaEndpoint.forApiGateway`, and
  *   the @declapract:review marker lands on disk — the glue a mocked-context unit test cannot show.
  */
 describe('simple-lambda-handlers migration', () => {
@@ -69,14 +69,17 @@ describe('simple-lambda-handlers migration', () => {
           expect(after).toContain("from 'sdk-aws-lambda'");
           expect(after).not.toContain("from 'simple-lambda-handlers'");
 
-          // the api-gateway factory call is rewritten to its sdk equivalent
-          expect(after).toContain('genLambdaEndpoint.for.apiGateway(');
+          // the api-gateway factory call is rewritten to its sdk@0.7.1 equivalent (#646)
+          expect(after).toContain('genLambdaEndpoint.forApiGateway(');
+          expect(after).not.toContain('.for.apiGateway(');
           expect(after).not.toContain('createApiGatewayHandler(');
 
           // the value-rewrite marker lands on disk — the un-rewritable schema+invoke contract
-          // is loud, so a consumer cannot ship a handler that answers 400 to every request
+          // is loud, so a consumer cannot ship a handler that answers 400 to every request.
+          // it teaches the 0.7.1 shape, never the retired `rawEvent` (#640)
           expect(after).toContain('@declapract:review');
-          expect(after).toContain('rawEvent');
+          expect(after).toContain('{ headers, payload, event }');
+          expect(after).not.toContain('rawEvent');
 
           // full content, for the reviewer's eye
           expect(after).toMatchSnapshot('getWidget.ts — after');

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/.declapract.readme.md

@@ -2,7 +2,8 @@
 
 ## what
 
-detects and transforms simple-lambda-handlers usage to sdk-aws-lambda.
+detects and transforms simple-lambda-handlers usage to sdk-aws-lambda, at the `sdk-aws-lambda@0.7.1`
+floor the node-service practice declares.
 
 ## why
 
@@ -17,24 +18,47 @@ sdk-aws-lambda provides modern lambda handler patterns:
 |-----|-----|
 | `import { createStandardHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
 | `import { createApiGatewayHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
-| `createStandardHandler(...)` | `genLambdaEndpoint(...)` |
-| `createApiGatewayHandler(...)` | `genLambdaEndpoint.for.apiGateway(...)` |
+| `createStandardHandler(...)` | `genLambdaEndpoint.forAsk(...)` |
+| `createApiGatewayHandler(...)` | `genLambdaEndpoint.forApiGateway(...)` |
+
+## the invoke input — `{ headers, payload, event }`
+
+in `sdk-aws-lambda@0.7.1`, `invoke` receives one input with three keys:
+
+| key | holds |
+|-----|-------|
+| `payload` | the validated body — what the input schema describes |
+| `headers` | the request headers, keys lowercased (api gateway only) |
+| `event` | the reconciled wire event — method, params, codec (api gateway only) |
+
+two renames apply to a guide written against an earlier release, and they fail differently:
+
+| earlier guide | 0.7.1 | how a migrator meets it |
+|---|---|---|
+| `rawEvent.headers[k]` | `headers[k]` | loud — `rawEvent` is absent at the destructure |
+| `event` for the body | `payload` | quiet — `event` still exists, so the error lands at the use site |
 
 ## limitations
 
 these patterns require manual migration:
 
 - `schema` (single joi) → `schema: { input, output }` (split zod)
-- `logic: (event) => O` → `invoke: ({ event }, { log }) => O`
+- `logic: (event) => O` → `invoke: async ({ payload }, { log }) => O`
 - `log` passed at creation → `log` also received in invoke context
 
 the contract differs in a way a regex cannot get right: the prior framework's schema described the
-WHOLE event, while sdk-aws-lambda's input schema describes the request BODY (the handler then reads
-headers off a separate `rawEvent`). a rename-only rewrite answers 400 to every request yet
-typechecks. so a handler CALL now carries a `@declapract:review` marker that names the two manual
-edits (unwrap the `body` key into the input schema; thread headers via `rawEvent.headers`). the
-codemod does NOT guess the contract — it flags it loud, and the consumer deletes the marker once the
-call is restructured (#594).
+WHOLE event, while sdk-aws-lambda's input schema describes the request BODY. a rename-only rewrite
+answers 400 to every request yet typechecks. so a handler CALL carries a `@declapract:review` marker
+that names the manual edits (unwrap the `body` key into the input schema; read the body as
+`payload` and the headers as `headers`). the codemod does NOT guess the contract — it flags it loud,
+and the consumer deletes the marker once the call is restructured (#594).
+
+## the payload is frozen — readonly sinks
+
+`invoke`'s input is deep-frozen (`FrozenDeep<T>`). a domain input typed with a mutable array no
+longer accepts it. the repair is a readonly sink: `z.array(…).readonly()` in the zod schema plus a
+`readonly T[]` field on the domain input. `FrozenDeep<…>` on a handler signature is the wrong repair:
+it spreads the sdk type through consumer code.
 
 ## example
 
@@ -53,8 +77,29 @@ after (requires manual refinement):
 ```ts
 import { genLambdaEndpoint } from 'sdk-aws-lambda';
 
-export const handler = genLambdaEndpoint({
-  schema: { input: inputSchema, output: outputSchema },
-  invoke: async ({ event }, { log }) => doStuff(event),
-}, { log });
+export const handler = genLambdaEndpoint.forAsk(
+  {
+    schema: { input: inputSchema, output: outputSchema },
+    invoke: async ({ payload }, { log }) => doStuff(payload, { log }),
+  },
+  { log },
+);
 ```
+
+an api-gateway handler, after:
+```ts
+export const handler = genLambdaEndpoint.forApiGateway({
+  schema: {
+    input: z.object({ headers: headersSchema, payload: bodySchema }),
+    output: asApiGatewayResponseSchema({ body: outputSchema }),
+  },
+  invoke: async ({ headers, payload }, context) => ({
+    body: await doStuff({ payload, authorization: headers.authorization }, context),
+  }),
+});
+```
+
+## a repo already on sdk-aws-lambda below 0.7
+
+the `sdk-aws-lambda-pre-v07` bad-practice owns that move: `genLambdaEndpoint(` → `.forAsk(`,
+`.for.apiGateway(` → `.forApiGateway(`, `({ event })` → `({ payload })`.

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/__snapshots__/.declapract.integration.test.ts.snap

@@ -19,12 +19,13 @@ export const handler = createApiGatewayHandler({
 
 exports[`simple-lambda-handlers migration given: [case1] a repo with a simple-lambda-handlers api-gateway handler when: [t1] the simple-lambda-handlers fix is applied then: the import + call are rewritten to sdk-aws-lambda, the review marker lands, and it matches snapshot: getWidget.ts — after 1`] = `
 "/**
- * @declapract:review — auto-migrated to sdk-aws-lambda; the api-gateway handler CONTRACT differs
- * and MUST be restructured by hand (a rename-only migration answers 400 to every request):
+ * @declapract:review — auto-migrated to sdk-aws-lambda@0.7.1; the api-gateway handler CONTRACT
+ * differs and MUST be restructured by hand (a rename-only migration answers 400 to every request):
  *  - schema: the prior single schema described the WHOLE event; the sdk input schema describes the
  *    request BODY only. split into \`schema: { input, output }\` and unwrap the \`body\` key.
- *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event, rawEvent }) => O\`. \`event\` is
- *    the parsed body; thread headers through \`rawEvent.headers\`.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ headers, payload, event }) => O\`.
+ *    \`payload\` is the parsed body; \`headers\` holds the lowercased request headers; \`event\` is
+ *    the reconciled wire event (method, params, codec).
  * delete this marker once restructured.
  */
 import { genLambdaEndpoint } from 'sdk-aws-lambda';
@@ -34,7 +35,7 @@ import { getWidgetSchema } from './getWidget.schema';
 
 // an api-gateway handler CALL — the schema+invoke contract differs between the two
 // frameworks, so the fix cannot rename-only; it must emit a loud review marker.
-export const handler = genLambdaEndpoint.for.apiGateway({
+export const handler = genLambdaEndpoint.forApiGateway({
   log,
   schema: getWidgetSchema,
   logic: async (event) => ({ widget: event.widgetId }),

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts

@@ -16,8 +16,7 @@ export const fix: FileFixFunction = (contents) => {
     dependencies: {
       ...packageJSON.dependencies,
       'simple-lambda-handlers': undefined,
-      'sdk-aws-lambda':
-        packageJSON.dependencies?.['sdk-aws-lambda'] ?? '^0.1.0',
+      'sdk-aws-lambda': packageJSON.dependencies?.['sdk-aws-lambda'] ?? '0.7.2', // the node-service floor (#646), pinned
     },
   };
 

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/simple-lambda-handlers/src/<star><star>/<star>.ts.declapract.ts

@@ -18,32 +18,36 @@ export const check: FileCheckFunction = (contents) => {
  *         between the two frameworks and cannot be mechanically rewritten.
  * .why = the prior framework's schema described the WHOLE event and the handler received the whole
  *        event; the sdk's input schema describes the request BODY and the handler receives the
- *        parsed body plus a separate rawEvent. a rename-only rewrite leaves a handler that answers
- *        400 to every request, yet typechecks (#594). the marker flags the two manual edits rather
- *        than let a regex guess the contract.
+ *        parsed body as `payload`, the lowercased `headers`, and the reconciled wire `event`. a
+ *        rename-only rewrite leaves a handler that answers 400 to every request, yet typechecks
+ *        (#594). the marker flags the manual edits rather than let a regex guess the contract.
+ * .note = the shape named here is the one sdk-aws-lambda@0.7.1 publishes (#640); `rawEvent` and
+ *         a body read off `event` are gone from that release.
  */
 const apiGatewayReviewMarker = `/**
- * @declapract:review — auto-migrated to sdk-aws-lambda; the api-gateway handler CONTRACT differs
- * and MUST be restructured by hand (a rename-only migration answers 400 to every request):
+ * @declapract:review — auto-migrated to sdk-aws-lambda@0.7.1; the api-gateway handler CONTRACT
+ * differs and MUST be restructured by hand (a rename-only migration answers 400 to every request):
  *  - schema: the prior single schema described the WHOLE event; the sdk input schema describes the
  *    request BODY only. split into \`schema: { input, output }\` and unwrap the \`body\` key.
- *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event, rawEvent }) => O\`. \`event\` is
- *    the parsed body; thread headers through \`rawEvent.headers\`.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ headers, payload, event }) => O\`.
+ *    \`payload\` is the parsed body; \`headers\` holds the lowercased request headers; \`event\` is
+ *    the reconciled wire event (method, params, codec).
  * delete this marker once restructured.
  */
 `;
 
 /**
  * .what = a loud marker for a standard handler call, whose schema+invoke shape also differs.
- * .why = the rename does not restructure the args; the sdk splits the schema and passes log in the
- *        invoke context. the marker flags the manual edits (#594).
+ * .why = the rename does not restructure the args; the sdk splits the schema, hands the validated
+ *        input as `payload`, and passes log in the invoke context. the marker flags the manual
+ *        edits (#594, #646).
  */
 const standardReviewMarker = `/**
- * @declapract:review — auto-migrated to sdk-aws-lambda; the handler CONTRACT differs and MUST be
- * restructured by hand:
+ * @declapract:review — auto-migrated to sdk-aws-lambda@0.7.1; the handler CONTRACT differs and
+ * MUST be restructured by hand:
  *  - schema: the prior single schema splits into \`schema: { input, output }\`.
- *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ event }, { log }) => O\`; \`log\` is now
- *    received in the invoke context, not only at creation.
+ *  - invoke: \`logic: (event) => O\` becomes \`invoke: async ({ payload }, { log }) => O\`; the
+ *    validated input is \`payload\`, and \`log\` is now received in the invoke context.
  * delete this marker once restructured.
  */
 `;
@@ -84,9 +88,9 @@ const asDedupedImportNames = (input: { names: string[] }): string[] => [
  *
  * .note = basic transforms only; complex patterns require manual fix
  *
- * API map:
- * - createStandardHandler → genLambdaEndpoint
- * - createApiGatewayHandler → genLambdaEndpoint.for.apiGateway
+ * API map (sdk-aws-lambda@0.7.1, #646):
+ * - createStandardHandler → genLambdaEndpoint.forAsk
+ * - createApiGatewayHandler → genLambdaEndpoint.forApiGateway
  */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};
@@ -110,8 +114,8 @@ export const fix: FileFixFunction = (contents) => {
       },
     )
     // transform function calls
-    .replace(/createStandardHandler/g, 'genLambdaEndpoint')
-    .replace(/createApiGatewayHandler/g, 'genLambdaEndpoint.for.apiGateway');
+    .replace(/createStandardHandler/g, 'genLambdaEndpoint.forAsk')
+    .replace(/createApiGatewayHandler/g, 'genLambdaEndpoint.forApiGateway');
 
   // prepend the review marker for a handler CALL (api-gateway takes precedence), so the
   // un-rewritable schema+invoke contract is loud. idempotent: the check no longer fires

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

@@ -1,6 +1,6 @@
 {
   "private": true,
   "dependencies": {
-    "sdk-aws-lambda": "@declapract{check.minVersion('0.4.0')}"
+    "sdk-aws-lambda": "@declapract{check.minVersion('0.7.2')}"
   }
 }

package/dist/.test/assets/node-service/declarations/practices/node-service/best-practice/src/access/sdks/sdkAwsLambdaAskAncient.ts

@@ -0,0 +1,39 @@
+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/.test/assets/node-service/declarations/practices/node-service/withLambdaClientGenMarker.ts

@@ -0,0 +1,55 @@
+/**
+ * .what = the text that marks a client file as the codegen's, or as already pointed at it
+ * .why  = one text, two skips: a generated client and a client already marked both hold it.
+ * .note = the codegen banner reads `generated by \`sdk-aws-lambda gen\``; the marker this module
+ *         stamps names `npx sdk-aws-lambda gen`.
+ */
+const CODEGEN_MENTION = 'sdk-aws-lambda gen';
+
+/**
+ * .what = the stable token every marker this module stamps carries
+ * .why  = the skip keys on this token too, so a reword of the marker's prose can never re-stamp a
+ *         marked file — the fixed point does not rest on the codegen command's exact words alone
+ */
+const MARKER_TOKEN = 'declapract-typescript-ehmpathy#532';
+
+/**
+ * .what = is this file a hand-written client that wraps `askLambdaEndpoint`?
+ * .why  = a hand-transcribed client drifts from its peer's contract in silence; the codegen emits
+ *         one that matches the peer's live contract, so drift turns into a reviewable diff (#532)
+ */
+export const isAdhocLambdaClient = (input: { contents: string }): boolean =>
+  /\baskLambdaEndpoint\b/.test(input.contents) &&
+  !input.contents.includes(CODEGEN_MENTION) &&
+  !input.contents.includes(MARKER_TOKEN);
+
+/**
+ * .what = the peer service slug a client file name spells, e.g. `svcJobs.ts` → `svc-jobs`
+ * .why  = the marker names the exact codegen command for this peer, so the reader can paste it
+ * .note = a name that spells no `svc*` peer yields a placeholder, never a guess
+ */
+const asPeerServiceSlug = (input: { relativeFilePath: string }): string => {
+  const basename = input.relativeFilePath.split('/').pop() ?? '';
+  const stem = basename.replace(/\.ts$/, '');
+  if (!/^svc[A-Z]\w*$/.test(stem)) return '<svc-name>';
+  return stem.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+};
+
+/**
+ * .what = stamp a review marker on line one that names the codegen for this peer
+ * .why  = the move to a generated sdk changes the contract a caller imports (namespaced resources,
+ *         `(event, context)` mechanisms), so it cannot be rewritten in place. the marker points the
+ *         tree at the paved command rather than leave a hand-written client unflagged (#532).
+ */
+export const withLambdaClientGenMarker = (input: {
+  contents: string;
+  relativeFilePath: string;
+}): string => {
+  // skip a generated client, or one already marked
+  if (!isAdhocLambdaClient({ contents: input.contents })) return input.contents;
+
+  // name the paved command, for this peer
+  const peer = asPeerServiceSlug({ relativeFilePath: input.relativeFilePath });
+  const marker = `// @declapract:review — a hand-written lambda client drifts from its peer's contract; generate it via \`npx ${CODEGEN_MENTION} --for ${peer} --into src/access/svcs/ --env prep\`, move callers onto the generated sdk, then delete this file (${MARKER_TOKEN})`;
+  return `${marker}\n${input.contents}`;
+};

package/dist/.test/assets/nonpublished-modules/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the nonpublished-modules practice integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/.declapract.readme.md

@@ -0,0 +1,5 @@
+nonpublished modules are used when we are testing out some new functionality and have not yet generalized it sufficiently to warrant creating a npm module of its own yet (e.g., follow W.E.T and have not written it twice already)
+
+however, when modules do graduate and get published, we want to make sure we start using them and stop using the "nonpublished" one
+
+this practice consists of bad-practice checks that make sure whenever we publish one (or deprecate one) we dont keep using the old one

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.declapract.integration.test.ts

@@ -0,0 +1,95 @@
+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 of the ahbode-standard-lambda-handler test-file migration, run through
+ *   the REAL declapract apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = the fix moves a handler test off the nonpublished `promiseLambdaInvocation` and onto
+ *   `runLambdaEndpoint.onReferenced(...).then(asLambdaEndpointOutput)` in one apply (#650) — a
+ *   transform, so per rule.require.declapract-integration-tests it owes a pipeline test. a unit
+ *   test of the exported `fix` never exercises the `src/contract/handlers/*.integration.test.ts`
+ *   glob -> file match, nor the CONTAINS check that gates the fix.
+ */
+describe('ahbode-standard-lambda-handler test-file migration', () => {
+  given('[case1] a repo whose handler test calls promiseLambdaInvocation', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-ahbode-standard-lambda-handler',
+      clone: './src/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/nonpublished-modules/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/contract/handlers/getWidget.integration.test.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'nonpublished-modules',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the handler test imports + calls promiseLambdaInvocation + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain('__nonpublished_modules__/ahbode-standard-lambda-handler');
+        expect(before).toContain('promiseLambdaInvocation(');
+        expect(before).not.toContain('runLambdaEndpoint');
+        expect(before).toMatchSnapshot('getWidget.integration.test.ts — before');
+      });
+    });
+
+    when('[t1] the ahbode-standard-lambda-handler fix is applied', () => {
+      useThen('migrate the handler test', async () => applyMigrate());
+
+      then(
+        'the test lands on runLambdaEndpoint.onReferenced in one apply, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the nonpublished module and the retired successor are both gone
+          expect(after).not.toContain('__nonpublished_modules__');
+          expect(after).not.toContain('promiseLambdaInvocation');
+          expect(after).not.toContain('simple-lambda-testing-methods');
+
+          // the sdk import + the onReferenced call land, output unwrapped by asLambdaEndpointOutput
+          expect(after).toContain(
+            "import { asLambdaEndpointOutput, runLambdaEndpoint } from 'sdk-aws-lambda';",
+          );
+          expect(after).toContain('runLambdaEndpoint.onReferenced(');
+          expect(after).toContain('.then(asLambdaEndpointOutput)');
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('getWidget.integration.test.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // post-rewrite the file no longer CONTAINS the nonpublished import line, so the check no
+      // longer detects the bad practice — the second apply changes zero bytes
+      // (rule.require.idempotent-fixes)
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = await read(targetPath); // post-first-migrate
+        await applyMigrate(); // second apply
+        const after = await read(targetPath);
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.declapract.readme.md

@@ -0,0 +1 @@
+was published under `standard-lambda-handlers` package

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/declapract.use.yml

@@ -0,0 +1,5 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/nonpublished-modules symlink to the real practice), so the consumer's own src/
+#         tree stays free to hold the target handler test the glob matches.
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/.test/assets/nonpublished-modules/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.test/assets/demo-repo-with-ahbode-handler-test/src/contract/handlers/getWidget.integration.test.ts

@@ -0,0 +1,18 @@
+import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';
+import { given, then, when } from 'test-fns';
+
+import { handler } from './getWidget';
+
+describe('getWidget', () => {
+  given('[case1] a widget uuid', () => {
+    when('[t0] the handler is invoked', () => {
+      then('it responds', async () => {
+        const response = await promiseLambdaInvocation({
+          event: { widgetUuid: 'w-1' },
+          handler,
+        });
+        expect(response).toBeDefined();
+      });
+    });
+  });
+});