declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/runtime-schemas/bad-practices/joi/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t0] the migration input (before any fix) then: the src file imports joi + declares a Joi schema + matches snapshot: widget.schema.ts — before 1`] = `
+"import Joi from 'joi';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = Joi.object({
+  name: Joi.string().required(),
+  count: Joi.number(),
+  createdAt: Joi.date(),
+});
+"
+`;
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t1] the joi fix is applied then: the import + schema are rewritten to zod, the review marker lands, and it matches snapshot: widget.schema.ts — after 1`] = `
+"/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+import { z } from 'zod';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  createdAt: z.date(),
+});
+"
+`;

package/dist/practices/runtime-schemas/bad-practices/joi/src/<star><star>/<star>.ts.declapract.ts

@@ -14,15 +14,38 @@ export const check: FileCheckFunction = (contents) => {
 };
 
 /**
- * .what = transforms joi imports and basic schema patterns to zod
- * .why = automated migration reduces manual toil
+ * .what = a loud marker prepended to every rewritten file, so the three SILENT semantic
+ *         changes this mechanical rewrite makes become visible to the consumer.
+ * .why = the rewrite is a regex, and a regex cannot know a field's intended optionality, its
+ *        unknown-key policy, or whether a date arrives as a string. it therefore GUESSES, and each
+ *        guess typechecks. per the value-rewrite guard, a rewrite that must guess emits a review
+ *        marker rather than a silent, possibly-wrong result (#594). the consumer deletes the marker
+ *        once each point is verified by hand.
+ */
+const reviewMarker = `/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+`;
+
+/**
+ * .what = transforms joi imports and basic schema patterns to zod, with a review marker
+ * .why = automated migration reduces manual toil, but the shape-for-shape rewrite makes three
+ *        silent semantic changes a regex cannot get right — so it prepends a @declapract:review
+ *        marker that flags them, rather than ship a silent guess (#594).
  *
  * .note = basic transforms only; complex patterns require manual fix
  */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};
 
-  const updated = contents
+  const transformed = contents
     // transform imports: import Joi from 'joi' → import { z } from 'zod'
     .replace(/import\s+Joi\s+from\s+['"]joi['"]/g, "import { z } from 'zod'")
     // transform imports: import * as Joi from 'joi' → import { z } from 'zod'
@@ -46,5 +69,11 @@ export const fix: FileFixFunction = (contents) => {
     // transform .required() → remove (zod is required by default)
     .replace(/\.required\(\)/g, '');
 
+  // prepend the review marker once, so the silent semantic guesses are loud (idempotent: the
+  // check no longer fires post-rewrite, and a second pass would find the marker already present)
+  const updated = transformed.includes('@declapract:review')
+    ? transformed
+    : reviewMarker + transformed;
+
   return { contents: updated };
 };

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

@@ -0,0 +1,230 @@
+import fs from 'fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
+
+jest.setTimeout(180_000);
+
+/**
+ * .what = holds the serverless `package.json` deploy commands to the dual-publish split —
+ *         the council-gated fulcrum that a wrong guess would ship as a permanent 2×-deploy.
+ * .why  = the `package.json` is a CONTAINS template with no `fix`, so no unit test covers it.
+ *         per `rule.require.clamp-edge-cases`, the deploy-split (and the contemp prune it needs)
+ *         owes a clamp. this reads the template + pins the split shape.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the filesystem (the
+ *         template file). no credential, no network.
+ * .teeth = (a) `deploy:release` MUST invoke BOTH halves — a revert to a single-fleet release
+ *          reddens it; (b) `deploy:prune` MUST also prune the contemp `-prep-` fleet — a revert
+ *          to the ancient-only prune (the B1 leak) reddens it.
+ */
+
+const PACKAGE_JSON_PATH = `${__dirname}/best-practice/package.json`;
+const SERVERLESS_YML_PATH = `${__dirname}/best-practice/serverless.yml`;
+
+describe('serverless practice — the dual-publish deploy split (north-star clamp)', () => {
+  given('[case1] the shipped serverless package.json template', () => {
+    const scene = useBeforeAll(() => ({
+      scripts: JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')).scripts as Record<
+        string,
+        string
+      >,
+    }));
+
+    when('[t0] the deploy commands are read', () => {
+      then('the ancient release publishes the dev-below-prod slug', () => {
+        expect(scene.scripts['deploy:release:ancient']).toContain(
+          "[ \"${ACCESS:-}\" = 'prep' ] && echo 'dev'",
+        );
+        expect(scene.scripts['deploy:release:ancient']).toContain(
+          '--stage "${SLS_STAGE:-}"',
+        );
+      });
+
+      then('the contemp release publishes the prep slug', () => {
+        expect(scene.scripts['deploy:release:contemp']).toContain('--stage prep');
+      });
+
+      then('deploy:release runs BOTH fleets (the dual-publish teeth)', () => {
+        expect(scene.scripts['deploy:release']).toContain(
+          'npm run deploy:release:ancient',
+        );
+        expect(scene.scripts['deploy:release']).toContain(
+          'npm run deploy:release:contemp',
+        );
+      });
+
+      then('deploy:prod publishes the ancient fleet only (prod is prod on both axes)', () => {
+        expect(scene.scripts['deploy:prod']).toContain(
+          'npm run deploy:release:ancient',
+        );
+        expect(scene.scripts['deploy:prod']).not.toContain(
+          'npm run deploy:release:contemp',
+        );
+      });
+
+      then('deploy:prune also prunes the contemp -prep- fleet (the B1 leak clamp)', () => {
+        expect(scene.scripts['deploy:prune']).toContain('--stage prep');
+      });
+    });
+  });
+
+  given('[case2] the shipped serverless.yml template', () => {
+    const scene = useBeforeAll(() => ({
+      yml: readFileSync(SERVERLESS_YML_PATH, 'utf8'),
+    }));
+
+    when('[t0] the domain-driven-cache IAM grant is read', () => {
+      then('it grants the cache family with the stage segment globbed (#597)', () => {
+        // the shared cache is one table addressed by a single name (below prod that name is -dev-);
+        // a globbed grant covers -dev-, -prep-, -prod- in one line, so the contemp -prep- fleet's
+        // -dev- cache read is authorized. supersedes the earlier D27 two-line stage+access grant.
+        expect(scene.yml).toContain(
+          'table/infrastructure-*-table-domain-driven-cache',
+        );
+      });
+
+      then('no stage- or access-templated cache grant survives (the #597 teeth)', () => {
+        // a templated grant covers only the deployed fleet's own slug — the exact #597 break where
+        // the contemp -prep- fleet AccessDenied on the shared -dev- cache. the glob replaces both.
+        expect(scene.yml).not.toContain(
+          'table/infrastructure-${self:provider.stage}-table-domain-driven-cache',
+        );
+        expect(scene.yml).not.toContain(
+          'table/infrastructure-${self:custom.access}-table-domain-driven-cache',
+        );
+      });
+
+      then('the glue-db grants read the single hoisted custom.access var (D: no 4x dup)', () => {
+        // teeth: the accessByStage lookup is declared ONCE, as custom.access; a partial edit that
+        // re-inlined the lookup at one arn site (and missed another) is the D27-reopen hazard.
+        expect(scene.yml).toContain(
+          "access: ${self:custom.accessByStage.${opt:stage}, 'prep'}",
+        );
+        // exactly one occurrence of the raw accessByStage lookup — the hoisted var, nowhere else
+        expect(
+          (scene.yml.match(/accessByStage\.\$\{opt:stage\}/g) || []).length,
+        ).toBe(1);
+      });
+    });
+
+    when('[t1] the glue db + table IAM grants are read', () => {
+      // the vision names the cache AND the glue db as the SAME stage/access disease (D27). the
+      // cache dual-grant alone is a point-fix; the glue db + table owe the identical dual-grant, or
+      // the ancient stack's access-keyed glue lookup 403s exactly the way the cache did.
+      then('the glue db grants BOTH the stage-keyed and access-keyed name', () => {
+        expect(scene.yml).toContain(
+          'database/@declapract{variable.databaseName}_${self:provider.stage}',
+        );
+        // teeth: drop the access-keyed glue db grant and the glue instance of D27 reopens.
+        expect(scene.yml).toContain(
+          'database/@declapract{variable.databaseName}_${self:custom.access}',
+        );
+      });
+
+      then('the glue table grants BOTH the stage-keyed and access-keyed name', () => {
+        expect(scene.yml).toContain(
+          'table/@declapract{variable.databaseName}_${self:provider.stage}/*',
+        );
+        // teeth: drop the access-keyed glue table grant and the glue instance of D27 reopens.
+        expect(scene.yml).toContain(
+          'table/@declapract{variable.databaseName}_${self:custom.access}/*',
+        );
+      });
+    });
+  });
+});
+
+/**
+ * .what = end-to-end proof of the serverless.yml fix through the REAL declapract apply pipeline,
+ *         run against a genTempDir clone of a legacy consumer repo.
+ * .why  = serverless.yml.declapract.ts is a 17-transform fold of regex-over-structured-text
+ *         rewrites — per rule.require.declapract-integration-tests a transform-blocks fix REQUIRES
+ *         a test that runs the REAL executeApply, not a static template read. this proves what the
+ *         unit suite cannot: the `.declapract.ts` companion matched to `best-practice/serverless.yml`,
+ *         the file glob→match, the emitted file a consumer receives on disk, and a second-apply
+ *         fixed point.
+ * .note = INTEGRATION: reads the filesystem + runs executeApply against a temp clone. no credential,
+ *         no network. the fixture lives under a `.test` dot-dir (excluded from tsconfig/jest globs),
+ *         and mounts THIS repo's real `src` via the `src`→`src` symlink so declapract resolves the
+ *         serverless practice from source.
+ * .teeth = the env-block trio proves the CHAIN ORDER: withConnectionReuse anchors the legacy
+ *          NODE_ENV form and MUST run before withNodeEnvProduction rewrites that value to
+ *          `production`. so the presence of the connection-reuse flag beside a `NODE_ENV: production`
+ *          line proves the order held — a reorder that ran the production rewrite first would erase
+ *          the anchor and the flag would never land (the r007.b3 order-dependence clamp + the
+ *          r001.b1 pipeline clamp in one).
+ */
+describe('serverless practice — the real executeApply pipeline (r001.b1)', () => {
+  given('[case1] a legacy consumer serverless.yml (old runtime, legacy env block)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-fix',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const ymlPath = 'serverless.yml';
+    const read = () => fs.readFile(path.join(tempDir, ymlPath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'serverless',
+        file: ymlPath,
+      });
+
+    when('[t0] the legacy input (before any fix)', () => {
+      then('the serverless.yml input matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('serverless.yml — before');
+      });
+    });
+
+    when('[t1] the serverless fix is applied', () => {
+      useThen('apply the serverless fix', async () => applyFix());
+
+      then('the node runtime is bumped to the pinned major', async () => {
+        const yml = await read();
+        expect(yml).toContain('runtime: nodejs22.x');
+        expect(yml).not.toContain('nodejs14.x');
+      });
+
+      then('the legacy NODE_ENV value is rewritten to production', async () => {
+        const yml = await read();
+        expect(yml).toContain('NODE_ENV: production');
+        expect(yml).not.toContain('stageToNodeEnvMapping');
+      });
+
+      then('the connection-reuse flag lands beside the production NODE_ENV (chain-order teeth)', async () => {
+        const yml = await read();
+        // withConnectionReuse ran BEFORE withNodeEnvProduction: it anchored the legacy NODE_ENV form
+        // and inserted the flag on the next line, then the production rewrite hit the same line. the
+        // flag on the line after `NODE_ENV: production` proves the order held.
+        expect(yml).toContain(
+          'NODE_ENV: production # deploy with production optimizations of all resources, to make `prep` and `prod` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)\n    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true',
+        );
+      });
+
+      then('the utc timezone guard is inserted under the env block', async () => {
+        const yml = await read();
+        expect(yml).toContain('TZ: UTC # guarantee');
+      });
+
+      then('the emitted file matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('serverless.yml — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const passes = useThen('a second fix over its own output', async () => {
+        const before = await read(); // post-first-fix
+        await applyFix(); // second apply
+        const after = await read();
+        return { before, after };
+      });
+
+      then('the second fix is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/declapract.declare.yml

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

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/declapract.use.yml

@@ -0,0 +1,8 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  infrastructureNamespaceId: 'testns'
+  databaseName: 'testdb'
+  slackWebhookUrl: 'https://hooks.slack.test/webhook'

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/package.json

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

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/serverless.yml

@@ -0,0 +1,8 @@
+service: test-project
+
+provider:
+  name: aws
+  runtime: nodejs14.x
+  stage: ${opt:stage}
+  environment:
+    NODE_ENV: ${self:custom.stageToNodeEnvMapping.${self:provider.stage}}

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

@@ -0,0 +1,43 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless practice — the real executeApply pipeline (r001.b1) given: [case1] a legacy consumer serverless.yml (old runtime, legacy env block) when: [t0] the legacy input (before any fix) then: the serverless.yml input matches snapshot: serverless.yml — before 1`] = `
+"service: test-project
+
+provider:
+  name: aws
+  runtime: nodejs14.x
+  stage: \${opt:stage}
+  environment:
+    NODE_ENV: \${self:custom.stageToNodeEnvMapping.\${self:provider.stage}}
+"
+`;
+
+exports[`serverless practice — the real executeApply pipeline (r001.b1) given: [case1] a legacy consumer serverless.yml (old runtime, legacy env block) when: [t1] the serverless fix is applied then: the emitted file matches snapshot: serverless.yml — after 1`] = `
+"# @declapract:review — could not auto-insert \`ACCESS: \${self:custom.access}\` + \`COMMIT: \${env:COMMIT}\` under \`environment:\` because no \`STAGE: \${self:provider.stage}\` env var was present to convert; add both as children of your \`environment:\` block by hand — the failing \`declapract plan\` diff names them.
+service: test-project
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production # deploy with production optimizations of all resources, to make \`prep\` and \`prod\` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
+"
+`;

package/dist/practices/serverless/__snapshots__/cache-grant-stage-globbed.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless shared-cache IAM grant globs the stage segment (#597) given: [case1] the shared domain-driven cache grant when: [t0] serverless.yml is read then: the emitted cache grant line matches snapshot: serverless cache IAM grant 1`] = `"- arn:aws:dynamodb:\${aws:region}:\${aws:accountId}:table/infrastructure-*-table-domain-driven-cache # global cache: one SHARED table, name-globbed so every fleet's role can read it — see .declapract.readme.md"`;

package/dist/practices/serverless/__snapshots__/deployment-bucket-account-scoped.declapract.integration.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless deployment bucket is account-scoped by stage (#596) given: [case2] the provider.deploymentBucket reference when: [t0] serverless.yml is read then: the emitted deploymentBucketByStage map matches snapshot: serverless deploymentBucketByStage map 1`] = `
+"  deploymentBucketByStage: # the deployment bucket is ACCOUNT-scoped: it must live in the account the deploy role assumes, so it is keyed by stage like accessByStage above
+    dev: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-dev # prep-account bucket
+    prep: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-dev # prep-account bucket, shared with the -dev fleet, so no separate -prep bucket need exist
+    prod: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-prod # prod-account bucket — a prod deploy assumes the prod-account oidc role, which has no cross-account grant to the prep-account -dev bucket
+"
+`;

package/dist/practices/serverless/__snapshots__/divergentStageGuard.declapract.integration.test.ts.snap

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`divergent-stage guard — the shipped templates cannot re-split the stage/access axis given: [case4] the deploy-command ACCESS fall-through when: [t0] every deploy command that derives SLS_STAGE is read then: the shipped deploy commands match snapshot (a reworded message reddens): serverless deploy commands 1`] = `
+{
+  "deploy": "if [ "\${ACCESS:-}" = 'prod' ]; then npm run deploy:prod; elif [ "\${ACCESS:-}" = 'prep' ]; then npm run deploy:prep; else echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi",
+  "deploy:prep": "ACCESS=prep npm run deploy:release",
+  "deploy:prod": "ACCESS=prod npm run deploy:release:ancient && npm run deploy:send-notification",
+  "deploy:prune": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npx sls prune -n 7 --stage "\${SLS_STAGE:-}" && if [ "\${ACCESS:-}" = 'prep' ]; then npx sls prune -n 7 --stage prep; fi",
+  "deploy:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
+  "deploy:release:ancient": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npm run build && sls deploy --verbose --stage "\${SLS_STAGE:-}"",
+  "deploy:release:contemp": "export COMMIT=$(npx sdk-environment get commit) && if [ "\${ACCESS:-}" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
+  "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data "{\\"text\\":\\"$([ -z "\${DEPLOYER_NAME:-}" ] && git config user.name || echo "\${DEPLOYER_NAME:-}") has deployed $npm_package_name@v$npm_package_version:
+https://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\"}" @declapract{variable.slackWebhookUrl}",
+}
+`;

package/dist/practices/serverless/__snapshots__/serverless.yml.declapract.integration.test.ts.snap

@@ -0,0 +1,165 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless.yml given: a legacy serverless.yml — the full composed fix (snapshot + idempotency) then: the full composed fix matches snapshot (after): legacy serverless.yml — after 1`] = `
+"# @declapract:review — could not auto-insert \`ACCESS: \${self:custom.access}\` + \`COMMIT: \${env:COMMIT}\` under \`environment:\` because no \`STAGE: \${self:provider.stage}\` env var was present to convert; add both as children of your \`environment:\` block by hand — the failing \`declapract plan\` diff names them.
+service: svc-orders # orders domain service
+
+variablesResolutionMode: 20210326
+
+plugins:
+  - serverless-prune-plugin
+
+package:
+  artifact: .artifact/contents.zip
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+  deploymentBucketByStage: # the deployment bucket is ACCOUNT-scoped: it must live in the account the deploy role assumes, so it is keyed by stage like accessByStage above
+    dev: serverless-deployment-dev # prep-account bucket
+    prep: serverless-deployment-dev # prep-account bucket, shared with the -dev fleet, so no separate -prep bucket need exist
+    prod: serverless-deployment-prod # prod-account bucket — a prod deploy assumes the prod-account oidc role, which has no cross-account grant to the prep-account -dev bucket
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  memorySize: 1024
+  timeout: 60 # default timeout to 1min, for resilience against increased cold start times; individual functions can override this
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production # deploy with production optimizations of all resources, to make \`prep\` and \`prod\` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
+  deploymentBucket: \${self:custom.deploymentBucketByStage.\${opt:stage}, 'serverless-deployment-dev'} # account-scoped via deploymentBucketByStage above; provision the -prod bucket in the prod account before the first prod deploy, or a prod deploy trades a cross-account-deny for an absent-bucket error
+  iamRoleStatements:
+    # parameter store access
+    - Effect: Allow
+      Action:
+        - ssm:GetParameter
+        - ssm:GetParameters
+      Resource: arn:aws:ssm:\${aws:region}:\${aws:accountId}:parameter/*
+    # allow access inference from account name
+    - Effect: Allow
+      Action:
+        - account:GetAccountInformation
+      Resource: '*'
+    # allow invocation of other lambdas
+    - Effect: Allow
+      Action:
+        - lambda:InvokeFunction
+      Resource: '*'"
+`;
+
+exports[`serverless.yml given: a legacy serverless.yml — the full composed fix (snapshot + idempotency) then: the legacy input matches snapshot (before): legacy serverless.yml — before 1`] = `
+"service: svc-orders # orders domain service
+
+plugins:
+  - serverless-offline # local invoke for dev
+  - serverless-pseudo-parameters # obsolete once native vars land
+  - serverless-prune-plugin
+
+provider:
+  name: aws
+  runtime: nodejs18.x
+  memorySize: 1024
+  timeout: 10
+  stage: \${opt:stage}
+  environment:
+    NODE_ENV: \${self:custom.stageToNodeEnvMapping.\${self:provider.stage}}
+  deploymentBucket: serverless-deployment-\${self:provider.stage}
+  iamRoleStatements:
+    ## paramstore access
+    - Effect: Allow
+      Action: 'ssm:GetParameters'
+      Resource: arn:aws:ssm:#{AWS::Region}:#{AWS::AccountId}:parameter/*
+    # allow inferring access from account alias
+    - Effect: Allow
+      Action:
+        - iam:ListAccountAliases
+      Resource: '*'
+    ## allow invocation of other lambdas
+    - Effect: Allow
+      Action:
+        - lambda:InvokeFunction
+      Resource: '*'"
+`;
+
+exports[`serverless.yml given: a legacy sls.yaml that already holds a section under different content (r7 clobber-refusal) then: the section soft-skip injects an actionable @declapract:review marker, not a silent stall: section soft-skip custom clobber — review marker 1`] = `
+"service: svc-hascustom
+
+variablesResolutionMode: 20210326
+
+# @declapract:review — a \`custom:\` block is already present; merge the declared \`custom\` keys (from the failing \`declapract plan\` diff) into your extant \`custom:\` block by hand — auto-insert was declined to avoid a yaml last-wins clobber that would drop your block.
+custom:
+  domain: api.example.com
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+provider:
+  name: aws
+  stage: \${opt:stage}"
+`;
+
+exports[`serverless.yml given: a sls.yaml whose environment block exists but the anchors miss (r7 soft-skip) then: withUtcTimezone emits an actionable review marker when NODE_ENV sits below another env var: withUtcTimezone shuffled-env — review marker 1`] = `
+"# @declapract:review — could not auto-insert \`TZ: UTC\` under \`environment:\` because NODE_ENV is not the block's first key (the positional anchor missed); add \`TZ: UTC\` as a child of your \`environment:\` block by hand — the failing \`declapract plan\` diff names it.
+service: svc-shuffled
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  environment:
+    ACCESS: \${self:custom.access} # sdk-environment access, to target the correct config + resources (e.g., hit prep db -vs- prod db)
+    COMMIT: \${env:COMMIT} # sdk-environment commit slug, must be set by deploy command
+    NODE_ENV: production
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html"
+`;
+
+exports[`serverless.yml given: a sls.yaml with STAGE env var then: the composed fix over this example matches snapshot: STAGE example — after 1`] = `
+"service: svc-example
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production
+    ACCESS: \${self:custom.access} # sdk-environment access, to target the correct config + resources (e.g., hit prep db -vs- prod db)
+    COMMIT: \${env:COMMIT} # sdk-environment commit slug, must be set by deploy command
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true"
+`;