declapract-typescript-ehmpathy 0.49.13 → 0.49.15

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

@@ -1,8 +1,10 @@
 import fs from 'fs/promises';
-import { readFileSync } from 'node:fs';
+import { execSync, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
 import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
 
 jest.setTimeout(180_000);
@@ -67,6 +69,148 @@ describe('serverless practice — the dual-publish deploy split (north-star clam
       then('deploy:prune also prunes the contemp -prep- fleet (the B1 leak clamp)', () => {
         expect(scene.scripts['deploy:prune']).toContain('--stage prep');
       });
+
+      then('the ancient release refuses a dirty tree before it builds, so COMMIT names the shipped code (#668)', () => {
+        const ancient = scene.scripts['deploy:release:ancient']!;
+        expect(ancient).toContain('npm run deploy:assure:committed');
+        expect(ancient.indexOf('npm run deploy:assure:committed')).toBeLessThan(
+          ancient.indexOf('npm run build'),
+        );
+        expect(scene.scripts['deploy:assure:committed']).toContain(
+          'git status --porcelain',
+        );
+      });
+    });
+
+    when('[t1] the dirty-tree guard runs in a real git repo (#668)', () => {
+      const runGuard = (input: { dirty: boolean }) => {
+        const repo = genTempDir({ slug: `declapract-serverless-dirty-${input.dirty}` });
+        execSync('git init -q && git -c user.email=t@example.com -c user.name=t commit -q --allow-empty -m init', { cwd: repo });
+        if (input.dirty) writeFileSync(path.join(repo, 'edit.ts'), 'export {};\n');
+        const result = spawnSync('sh', ['-c', scene.scripts['deploy:assure:committed']!], {
+          cwd: repo,
+          encoding: 'utf-8',
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('a clean tree passes', () => {
+        expect(runGuard({ dirty: false }).status).toEqual(0);
+      });
+
+      then('a dirty tree exits 2 and says why', () => {
+        const result = runGuard({ dirty: true });
+        expect(result.status).toEqual(2);
+        expect(result.output).toContain('uncommitted');
+      });
+    });
+
+    when('[t2] the runtime gate is read (#553)', () => {
+      then('the ancient release loads the built artifact on the deploy runtime before it ships', () => {
+        const ancient = scene.scripts['deploy:release:ancient']!;
+        expect(ancient.indexOf('npm run build')).toBeLessThan(
+          ancient.indexOf('npm run test:runtime'),
+        );
+        expect(ancient.indexOf('npm run test:runtime')).toBeLessThan(
+          ancient.indexOf('sls deploy'),
+        );
+      });
+    });
+
+    when('[t3] the runtime gate runs against a fake docker (#553)', () => {
+      /**
+       * .what = run `test:runtime` in a temp repo with a fake `docker` first on PATH
+       * .why  = proves the preflight + the image the gate picks, with no daemon in this suite.
+       *         the fake prints its args on `run`, and answers `info` per `daemon`.
+       */
+      const runGate = (input: { daemon: boolean; runtime: string | null }) => {
+        const repo = genTempDir({
+          slug: `declapract-serverless-runtime-${input.daemon}-${input.runtime}`,
+        });
+        mkdirSync(path.join(repo, 'bin'));
+        writeFileSync(
+          path.join(repo, 'bin', 'docker'),
+          `#!/bin/sh\nif [ "$1" = info ]; then exit ${input.daemon ? 0 : 1}; fi\necho "docker $*"\n`,
+          { mode: 0o755 },
+        );
+        writeFileSync(
+          path.join(repo, 'serverless.yml'),
+          input.runtime ? `provider:\n  runtime: ${input.runtime}\n` : 'provider:\n',
+        );
+        const result = spawnSync('sh', ['-c', scene.scripts['test:runtime']!], {
+          cwd: repo,
+          encoding: 'utf-8',
+          env: { ...process.env, PATH: `${path.join(repo, 'bin')}:${process.env.PATH}` },
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('it runs the artifact in the lambda image of the serverless.yml major', () => {
+        const result = runGate({ daemon: true, runtime: 'nodejs20.x' });
+        expect(result.status).toEqual(0);
+        expect(result.output).toContain('public.ecr.aws/lambda/nodejs:20');
+        expect(result.output).toContain('/.artifact/contents:/var/task:ro');
+      });
+
+      then('no docker daemon exits 2 and names docker, never a fallback to the host node', () => {
+        const result = runGate({ daemon: false, runtime: 'nodejs20.x' });
+        expect(result.status).toEqual(2);
+        expect(result.output).toContain('docker');
+        expect(result.output).not.toContain('docker run');
+      });
+
+      then('a serverless.yml with no runtime fails before docker runs', () => {
+        const result = runGate({ daemon: true, runtime: null });
+        expect(result.status).not.toEqual(0);
+        expect(result.output).not.toContain('docker run');
+      });
+    });
+
+    when('[t4] the in-container load procedure runs over a built artifact (#553)', () => {
+      /**
+       * .what = run the in-container load procedure with the host node, over a temp artifact
+       * .why  = the image is a fake above; this proves the procedure itself loads every handler
+       *         and fails loud on one that cannot parse
+       */
+      const runLoad = (input: { handlers: Record<string, string> }) => {
+        const artifact = genTempDir({
+          slug: `declapract-serverless-load-${Object.keys(input.handlers).length}`,
+        });
+        mkdirSync(path.join(artifact, 'dist/contract/handlers/nested'), { recursive: true });
+        Object.entries(input.handlers).forEach(([name, source]) =>
+          writeFileSync(path.join(artifact, 'dist/contract/handlers', name), source),
+        );
+        // the load procedure is the single-quoted `node -e '<procedure>'` tail of `test:runtime`
+        const loadProcedure =
+          / -e '(?<procedure>.+)'$/.exec(scene.scripts['test:runtime'] ?? '')?.groups?.procedure ??
+          MalfunctionError.throw('test:runtime holds no `-e` load procedure', {
+            command: scene.scripts['test:runtime'] ?? null,
+          });
+        const result = spawnSync('node', ['-e', loadProcedure], {
+          cwd: artifact,
+          encoding: 'utf-8',
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('every handler, nested ones too, loads', () => {
+        const result = runLoad({
+          handlers: {
+            'getWidget.js': 'exports.handler = async () => ({});\n',
+            'nested/setWidget.js': 'exports.handler = async () => ({});\n',
+          },
+        });
+        expect(result.status).toEqual(0);
+        expect(result.output).toContain('2 handlers load on node');
+      });
+
+      then('a handler that cannot parse fails the gate', () => {
+        const result = runLoad({
+          handlers: { 'broken.js': 'exports.handler = ;\n' },
+        });
+        expect(result.status).not.toEqual(0);
+        expect(result.output).toContain('SyntaxError');
+      });
     });
   });
 
@@ -147,8 +291,9 @@ describe('serverless practice — the dual-publish deploy split (north-star clam
  *         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.
+ *         and mounts THIS repo's real `src` at `declarations` (never at `src`) so declapract resolves
+ *         the serverless practice from source while the demo repo's own `src` stays empty — a `src`
+ *         mount would make every `src/**` wildcard declaration scan the whole library.
  * .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`
@@ -161,7 +306,7 @@ describe('serverless practice — the real executeApply pipeline (r001.b1)', ()
     const tempDir = genTempDir({
       slug: 'declapract-serverless-fix',
       clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
-      symlink: [{ at: 'src', to: 'src' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const ymlPath = 'serverless.yml';
@@ -227,4 +372,72 @@ describe('serverless practice — the real executeApply pipeline (r001.b1)', ()
       });
     });
   });
+
+  given('[case2] a consumer whose .nvmrc pins node 20 (#552)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-nvmrc',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const read = () => fs.readFile(path.join(tempDir, 'serverless.yml'), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'serverless',
+        file: 'serverless.yml',
+      });
+
+    when('[t1] the serverless fix is applied', () => {
+      useThen('pin .nvmrc, then apply', async () => {
+        await fs.writeFile(path.join(tempDir, '.nvmrc'), 'v20.11.1\n');
+        await applyFix();
+      });
+
+      then('the runtime follows .nvmrc, not the template major', async () => {
+        const yml = await read();
+        expect(yml).toContain('runtime: nodejs20.x');
+        expect(yml).not.toContain('nodejs22.x');
+        expect(yml).not.toContain('nodejs14.x');
+      });
+
+      then('a second apply is a no-op (the CONTAINS check passes on the derived runtime)', async () => {
+        const before = await read();
+        await applyFix();
+        expect(await read()).toEqual(before);
+      });
+    });
+  });
+
+  given('[case3] a consumer whose .nvmrc names an alias, not a major (#552)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-nvmrc-alias',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    when('[t1] the serverless fix is applied', () => {
+      const result = useThen('pin .nvmrc to an alias, then apply', async () => {
+        await fs.writeFile(path.join(tempDir, '.nvmrc'), 'lts/*\n');
+        const error = await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'serverless',
+          file: 'serverless.yml',
+        }).then(
+          () => null,
+          (thrown: unknown) => thrown,
+        );
+        const yml = await fs.readFile(path.join(tempDir, 'serverless.yml'), 'utf-8');
+        return { error, yml };
+      });
+
+      then('the apply fails loud and names .nvmrc, rather than guess a major', () => {
+        expect(result.error).toBeInstanceOf(Error);
+        expect((result.error as Error).message).toContain('.nvmrc');
+      });
+
+      then('the runtime line is left as found', () => {
+        expect(result.yml).toContain('nodejs14.x');
+      });
+    });
+  });
 });

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/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/serverless/__snapshots__/divergentStageGuard.declapract.integration.test.ts.snap

@@ -3,13 +3,15 @@
 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:assure:committed": "if [ -n "$(git status --porcelain)" ]; then echo '🛑 uncommitted changes: deploy ships the committed tree only, so COMMIT names the code that runs; commit or stash, then retry' && git status --short && 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:prune": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && sls prune -n 7 --stage "\${SLS_STAGE:-}" && if [ "\${ACCESS:-}" = 'prep' ]; then 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:release:ancient": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && npm run deploy:assure:committed && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npm run build && npm run test:runtime && sls deploy --verbose --stage "\${SLS_STAGE:-}"",
+  "deploy:release:contemp": "export COMMIT=$(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}",
+  "test:runtime": "docker info > /dev/null 2>&1 || { echo '🛑 docker absent: test:runtime loads the built artifact on the deploy runtime, in the lambda image; start the docker daemon, then retry' && exit 2; } && LAMBDA_NODE_MAJOR=$(node -p "require('fs').readFileSync('serverless.yml', 'utf8').match(/runtime: nodejs([0-9]+)[.]x/)[1]") && docker run --rm -e ACCESS -e COMMIT -v "$PWD/.artifact/contents:/var/task:ro" -w /var/task --entrypoint node public.ecr.aws/lambda/nodejs:\${LAMBDA_NODE_MAJOR} -e 'const fs = require("fs"), p = require("path"); const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(p.join(d, e.name)) : e.name.endsWith(".js") ? [p.join(d, e.name)] : [])); const files = walk("dist/contract/handlers"); if (!files.length) throw new Error("no handlers in dist/contract/handlers"); files.forEach((f) => require(p.join(process.cwd(), f))); console.log("✔ " + files.length + " handlers load on node " + process.versions.node);'",
 }
 `;

package/dist/practices/serverless/best-practice/.declapract.readme.md

@@ -30,8 +30,8 @@ a contemp→prod 404 is therefore unreachable, because the `sdkAwsLambdaEnvAcces
 target helper resolves against the CALLER's OWN `access`, not a fixed `-prep-` string. a prod-access
 caller resolves BOTH `Ancient` and `Contemp` to `prod` (there is no dev/prep split at prod), so it
 always addresses the published `-prod-` fleet. the `-prep-` slug is only ever emitted by a
-`prep`-access caller, which addresses `prep`-tier peers — never a prod service. a `prep`-access
-caller that reaches a prod service is a cross-tier call, which is not a supported pattern and is not
+`prep`-access caller, which addresses the `-prep-` peers its `prep` access reaches — never a prod
+service. a `prep`-access caller that reaches a prod service is a cross-access call, which is not a supported pattern and is not
 what dual-publish covers. so prod's ancient-only publish leaves no cross-service call uncovered.
 
 the north-star of the fix-lambdas wish is to retire the `stage` axis entirely; this dual-publish is

package/dist/practices/serverless/best-practice/package.json

@@ -1,13 +1,14 @@
 {
   "devDependencies": {
     "serverless": "@declapract{check.minVersion('2.57.0')}",
-    "serverless-prune-plugin": "@declapract{check.minVersion('2.0.2')}",
-    "if-env": "@declapract{check.minVersion('1.0.4')}"
+    "serverless-prune-plugin": "@declapract{check.minVersion('2.0.2')}"
   },
   "scripts": {
-    "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: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:prune": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && sls prune -n 7 --stage \"${SLS_STAGE:-}\" && if [ \"${ACCESS:-}\" = 'prep' ]; then sls prune -n 7 --stage prep; fi",
+    "deploy:assure:committed": "if [ -n \"$(git status --porcelain)\" ]; then echo '🛑 uncommitted changes: deploy ships the committed tree only, so COMMIT names the code that runs; commit or stash, then retry' && git status --short && exit 2; fi",
+    "deploy:release:ancient": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && npm run deploy:assure:committed && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npm run build && npm run test:runtime && sls deploy --verbose --stage \"${SLS_STAGE:-}\"",
+    "test:runtime": "docker info > /dev/null 2>&1 || { echo '🛑 docker absent: test:runtime loads the built artifact on the deploy runtime, in the lambda image; start the docker daemon, then retry' && exit 2; } && LAMBDA_NODE_MAJOR=$(node -p \"require('fs').readFileSync('serverless.yml', 'utf8').match(/runtime: nodejs([0-9]+)[.]x/)[1]\") && docker run --rm -e ACCESS -e COMMIT -v \"$PWD/.artifact/contents:/var/task:ro\" -w /var/task --entrypoint node public.ecr.aws/lambda/nodejs:${LAMBDA_NODE_MAJOR} -e 'const fs = require(\"fs\"), p = require(\"path\"); const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(p.join(d, e.name)) : e.name.endsWith(\".js\") ? [p.join(d, e.name)] : [])); const files = walk(\"dist/contract/handlers\"); if (!files.length) throw new Error(\"no handlers in dist/contract/handlers\"); files.forEach((f) => require(p.join(process.cwd(), f))); console.log(\"✔ \" + files.length + \" handlers load on node \" + process.versions.node);'",
+    "deploy:release:contemp": "export COMMIT=$(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:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
     "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:\nhttps://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\\"}\" @declapract{variable.slackWebhookUrl}",
     "deploy:prep": "ACCESS=prep npm run deploy:release",

package/dist/practices/serverless/best-practice/serverless.yml

@@ -27,7 +27,7 @@ provider:
   stage: ${opt:stage}
   stackTags:
     app: @declapract{variable.organizationName}
-    environment: ${self:custom.access} # the ACCESS tier (test|prep|prod), NOT the deploy stage slug — a -dev-fleet stack is still access=prep, so a `stage`-valued tag would read as the two-word lie the access axis retired; matches the ACCESS env var below
+    environment: ${self:custom.access} # the access (test|prep|prod), NOT the deploy stage slug — a -dev-fleet stack is still access=prep, so a `stage`-valued tag would read as the two-word lie the access axis retired; matches the ACCESS env var below
     product: ${self:service}
   environment:
     TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success

package/dist/practices/serverless/best-practice/serverless.yml.declapract.ts

@@ -1,19 +1,16 @@
-import type { FileFixFunction } from 'declapract';
+import type { FileContentsFunction, FileFixFunction } from 'declapract';
 import { FileCheckType } from 'declapract';
 
+import { readFile } from '../../../utils/readFile';
+import { getOneLambdaNodeRuntime } from '../getOneLambdaNodeRuntime';
+
 export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)
 
-// .note = ON A MISS, EVERY TRANSFORM SOFT-SKIPS (returns the contents unchanged); none throws.
-//   a soft-skip is NOT a silent break: the overall check is CONTAINS, so any declared line a
-//   transform could not land is absent from the output, which leaves `declapract plan` RED — that
-//   red IS the signal. a throw was the wrong mechanism for a miss: `fix` folds 14 transforms, so
-//   one throw aborts the whole chain and a very common arrival shape (a var before NODE_ENV, a
-//   pre-extant custom: block, an underscore in the service name) then blocks every unrelated repair
-//   — the runtime bump, the plugin removal, the IAM grants — from landing at all. CONTAINS already
-//   supplies the visibility a throw reached for, without that abort. the one true silent break a
-//   throw once guarded — a SECOND top-level key of a section the file already holds, a yaml
-//   last-wins clobber that PASSES CONTAINS — is prevented by NOT inserting when the section already
-//   exists (a soft-skip that declines the duplicate), which needs no throw either.
+// .note = on a miss, each transform returns the contents unchanged; none throws. the check is
+//   CONTAINS, so a declared line a transform could not land stays absent and `declapract plan`
+//   stays red, which names the miss. a throw would abort the whole 14-transform fold, so one odd
+//   arrival shape would block every unrelated repair in it. a transform never inserts a section the
+//   file already holds, since a second top-level key would clobber the first and still pass CONTAINS.
 
 /**
  * .what = convert crlf newlines to unix lf, as the first transform in the fold.
@@ -53,11 +50,28 @@ const accessByStageCustom = `custom:
 `;
 
 /**
- * .what = bump the lambda runtime to the current node major.
- * .why  = an old runtime string silently deploys onto an unsupported node version.
+ * .what = set the lambda runtime to the node major the repo's `.nvmrc` pins.
+ * .why  = the major that builds the artifact and the major that serves it must match, or a
+ *         dependency ships syntax the lambda cannot parse while every gate stays green (#552).
  */
-const withNodeRuntime = (input: { contents: string }): string =>
-  input.contents.replace(/runtime: nodejs\d\d.x/, 'runtime: nodejs22.x');
+const withNodeRuntime = (input: {
+  contents: string;
+  runtime: string;
+}): string =>
+  input.contents.replace(/runtime: nodejs\d+\.x/, `runtime: ${input.runtime}`);
+
+/**
+ * .what = declare the template, with its runtime line derived from the project's `.nvmrc`.
+ * .why  = the check is CONTAINS, so a template that pinned one major would demand it of a repo on
+ *         another — the fix and the check must name the same runtime, from the same one source.
+ */
+export const contents: FileContentsFunction = async (context) =>
+  withNodeRuntime({
+    contents: await readFile({ filePath: `${__dirname}/serverless.yml` }),
+    runtime: getOneLambdaNodeRuntime({
+      projectRoot: context.getProjectRootDirectory(),
+    }),
+  });
 
 /**
  * .what = drop the plugins serverless no longer needs.
@@ -608,7 +622,6 @@ const withSsmGetParameter = (input: { contents: string }): string => {
 // withNodeEnvProduction runs after withConnectionReuse, which anchors on the legacy NODE_ENV form.
 const transforms: Array<(input: { contents: string }) => string> = [
   withUnixNewlines,
-  withNodeRuntime,
   withoutDeprecatedPlugins,
   withNativeVariables,
   withSingleHashCommentHeaders,
@@ -646,7 +659,20 @@ const withTransformsApplied = (input: {
     input.contents,
   );
 
-export const fix: FileFixFunction = (contents) => {
+export const fix: FileFixFunction = (contents, context) => {
   if (!contents) return { contents }; // skip an absent file
-  return { contents: withTransformsApplied({ contents, transforms }) };
+
+  // the runtime comes from the project's `.nvmrc` (#552); a bare unit call has no project root
+  const runtime = getOneLambdaNodeRuntime({
+    projectRoot: context?.getProjectRootDirectory?.() ?? null,
+  });
+  return {
+    contents: withTransformsApplied({
+      contents,
+      transforms: [
+        (step) => withNodeRuntime({ contents: step.contents, runtime }),
+        ...transforms,
+      ],
+    }),
+  };
 };

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

@@ -62,7 +62,7 @@ describe('serverless deployment bucket is account-scoped by stage (#596)', () =>
 
       then('the emitted deploymentBucketByStage map matches snapshot', () => {
         // snapshot the governed map block itself, so a reshaped map that keeps the pinned
-        // per-tier tokens green (a reordered key, a rephrased bucket name) reddens a vibecheck
+        // per-key tokens green (a reordered key, a rephrased bucket name) reddens a vibecheck
         // in review (rule.require.contract-snapshot-exhaustiveness). match the header line plus
         // its indented dev/prep/prod entry lines — robust to a comment on any entry and to the
         // entry order.

package/dist/practices/serverless/getOneLambdaNodeRuntime.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = the node major the node practice pins, as the lambda runtime it maps to
+ * .why  = the default when a repo declares no `.nvmrc` — the node practice ships `v22.*`
+ */
+const RUNTIME_DEFAULT = 'nodejs22.x';
+
+/**
+ * .what = cast the contents of a `.nvmrc` into the lambda runtime of the same node major
+ * .why  = the node major that BUILDS the artifact and the node major that SERVES it must match.
+ *         `build:artifact` copies third-party files verbatim, never down-levelled, so a skew lets a
+ *         dependency ship syntax the deploy runtime cannot parse — and every gate before prod stays
+ *         green (#552). one source (`.nvmrc`), so the two cannot drift.
+ * .note = an unreadable pin (`lts/*`, `node`, an empty file) fails loud: a guess here is the exact
+ *         silent skew this transformer exists to prevent.
+ */
+export const asLambdaNodeRuntime = (input: { nvmrc: string }): string => {
+  // read the major from `22`, `v22`, `22.21.0`, or `v22.21.0`
+  const major = input.nvmrc.trim().match(/^v?(\d+)(?:\.\d+){0,2}$/)?.[1];
+  if (!major)
+    throw new ConstraintError(
+      'serverless.yml runtime derives from .nvmrc, but .nvmrc names no node major',
+      {
+        nvmrc: input.nvmrc,
+        hint: "pin .nvmrc to a numeric version, e.g. 'v22.21.0' (an alias like 'lts/*' names no major)",
+      },
+    );
+  return `nodejs${major}.x`;
+};
+
+/**
+ * .what = the lambda runtime for the project, read from its `.nvmrc`
+ * .why  = serverless.yml's `provider.runtime` must follow the repo's node pin (#552)
+ * .note = no project root (a bare unit call) or no `.nvmrc` → the node practice's pinned major
+ */
+export const getOneLambdaNodeRuntime = (input: {
+  projectRoot: string | null;
+}): string => {
+  // locate the pin; absent → the node practice's default
+  if (!input.projectRoot) return RUNTIME_DEFAULT;
+  const nvmrcPath = path.join(input.projectRoot, '.nvmrc');
+  if (!existsSync(nvmrcPath)) return RUNTIME_DEFAULT;
+
+  // cast the pin into its runtime
+  return asLambdaNodeRuntime({ nvmrc: readFileSync(nvmrcPath, 'utf-8') });
+};

package/dist/practices/serverless/if-env-unfloored.declapract.integration.test.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #660: the serverless practice floors no `if-env`
+ * .why  = every serverless package command gates on `ACCESS` in plain shell
+ *         (`[ "${ACCESS:-}" = 'prep' ]`), so a floor on `if-env` forced every adopter to install a
+ *         package no command calls
+ * .teeth = re-add `"if-env": "@declapract{check.minVersion('1.0.4')}"` to the serverless
+ *          package.json and case1 goes red
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads the template on disk
+ */
+
+const template = readFileSync(
+  join(__dirname, 'best-practice/package.json'),
+  'utf-8',
+);
+const parsed = JSON.parse(template) as {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+};
+const commands = Object.entries(parsed.scripts ?? {});
+
+describe('serverless floors no if-env (#660)', () => {
+  given('[case1] the serverless best-practice package.json', () => {
+    when('[t0] its deps and commands are read', () => {
+      then('no dep section names if-env', () => {
+        expect(Object.keys(parsed.dependencies ?? {})).not.toContain('if-env');
+        expect(Object.keys(parsed.devDependencies ?? {})).not.toContain('if-env');
+      });
+
+      then('no package command calls if-env, so naught needs it', () => {
+        expect(commands.length).toBeGreaterThan(0);
+        expect(commands.filter(([, command]) => command.includes('if-env'))).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practices/terraform-aws/best-practice/provision/aws/environments/test/main.tf.declapract.ts

@@ -0,0 +1,73 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import {
+  defineExpectedContentsWithUsecaseInserts,
+  type UsecaseInsert,
+} from '../../../../../../../utils/defineExpectedContentsWithUsecaseInserts';
+
+/**
+ * .what = the test-environment `main.tf` terraform-aws declares, usecase-aware for persist-with-dynamodb
+ * .why  = terraform-aws is the one owner of this file (#630). a dynamodb service provisions the
+ *         tables of its test environment into the local dynamodb container, so its aws provider
+ *         gets an `endpoints` block — an insert on this owner, never a second declaration of the
+ *         same file (rule.avoid.runtime-forks).
+ * .why  = a FINDSERT, never EQUALS: the base must still equal the template, but the endpoints
+ *         block, once present, is kept under every scope — a narrow
+ *         `declapract apply --practice terraform-aws` never strips it.
+ */
+export const DYNAMODB_INSERTS: UsecaseInsert[] = [
+  {
+    after: 'provider "aws" {',
+    text: [
+      '',
+      '  endpoints {',
+      '    dynamodb = "http://localhost:7337/" # the test environment tables live in the local dynamodb',
+      '  }',
+      '',
+    ].join('\n'),
+  },
+];
+
+/**
+ * .what = the contents this declaration expects, for the repo's extant file and usecase
+ */
+const defineExpectedContents = (input: {
+  contents: string | null;
+  declared: string;
+  projectPractices: string[];
+}): string =>
+  defineExpectedContentsWithUsecaseInserts({
+    contents: input.contents,
+    declared: input.declared,
+    inserts: DYNAMODB_INSERTS,
+    usecaseInScope: input.projectPractices.includes('persist-with-dynamodb'),
+  });
+
+/**
+ * .what = throws when the repo's test main.tf differs from the declared base + its owed inserts
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  const expected = defineExpectedContents({
+    contents,
+    declared: context.declaredFileContents ?? '',
+    projectPractices: context.projectPractices,
+  });
+  if (contents !== expected)
+    throw new ConstraintError(
+      'provision/aws/environments/test/main.tf differs from the declared template (plus its usecase inserts)',
+      { relativeFilePath: context.relativeFilePath },
+    );
+};
+
+/**
+ * .what = writes the declared base, plus the dynamodb endpoints block when owed or already present
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its output.
+ */
+export const fix: FileFixFunction = (contents, context) => ({
+  contents: defineExpectedContents({
+    contents,
+    declared: context.declaredFileContents ?? '',
+    projectPractices: context.projectPractices,
+  }),
+});

package/dist/practices/terraform-common/best-practice/.terraform-version

@@ -1 +1 @@
-0.14.11
+1.9.8

package/dist/practices/tests-any/.test/assets/repo-old-acceptance-utils/blackbox/lambdas/consumeSESEmailEventFromSNS.acceptance.test.ts

@@ -0,0 +1,23 @@
+import { SNSEventRecord, SNSMessage, SNSEvent } from 'aws-lambda';
+
+import { exampleEmailClickEvent } from '../../src/.test/assets/exampleEmailClickEvent';
+import { invokeLambda } from '../_utils/invokeLambda';
+
+describe('consumeSESEmailEventFromSNS', () => {
+  it('should be possible to invoke the lambda', async () => {
+    const exampleSnsEvent: SNSEvent = {
+      Records: [
+        {
+          Sns: {
+            Message: JSON.stringify(exampleEmailClickEvent),
+          } as SNSMessage,
+        } as SNSEventRecord,
+      ],
+    };
+    const response = await invokeLambda({
+      name: 'consumeSESEmailEventFromSNS',
+      data: exampleSnsEvent,
+    });
+    expect(response).toBeDefined();
+  });
+});