declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -0,0 +1,116 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the `old-dev-config-location` relocate + tier-migrate, run
+ *         through the REAL declapract apply pipeline against a genTempDir clone of a consumer
+ *         repo (the blocker.1 / row-4 clamp).
+ * .why  = the fix both RELOCATES `config/dev.json` → `config/prep.json` (a `relativeFilePath`
+ *         rewrite) AND TRANSFORMS the content via `migrateDevConfigToPrep`. per
+ *         `rule.require.declapract-integration-tests`, 'relocate a file' and 'transform blocks'
+ *         are each rows that REQUIRE a pipeline test — a unit test of the exported `fix` never
+ *         exercises the glob→file match or the `relativeFilePath` rewrite. this is that test.
+ * .note = the config file is snapshotted in full (before AND after) so a reviewer can eyeball
+ *         the exact end-state.
+ * .teeth = the input holds `"access": "dev"` — the ONE unambiguous tier token, migrated to
+ *          `prep` — plus four host values that must each survive byte-for-byte: a `://` URL
+ *          `https://auth.myapp.dev`, a mid-dotted bare host `bastion.dev.example.com`, a
+ *          terminal bare host `aws.ssmproxy.mydb.dev`, and a foreign public host
+ *          `api.dev.paypal.com`. a `.dev` label is axis-ambiguous WHEREVER it sits, so per
+ *          guard #3 (a rewrite that cannot verify its output must not guess) NO host is
+ *          rewritten. the after-state proves the tier migrate, all four hosts preserved, the
+ *          relocation, and that NO `@declapract:review` bytes ever enter the emitted config.
+ */
+describe('config — old-dev-config-location relocate + tier-migrate (row-4 clamp)', () => {
+  given('[case1] a repo with a config/dev.json to migrate', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-config-old-dev-config-location',
+      clone: './src/practices/config/.test/assets/demo-repo-with-dev-config',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const devPath = 'config/dev.json';
+    const prepPath = 'config/prep.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const exists = async (relativePath: string): Promise<boolean> =>
+      fs
+        .access(path.join(tempDir, relativePath))
+        .then(() => true)
+        .catch(() => false);
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'config',
+        file: devPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('config/dev.json holds the dev tier + matches snapshot', async () => {
+        const before = await read(devPath);
+        expect(before).toContain('"access": "dev"');
+        expect(before).toMatchSnapshot('config/dev.json — before');
+      });
+    });
+
+    when('[t1] the relocate + migrate fix is applied', () => {
+      useThen('migrate the dev config', async () => applyMigrate());
+
+      then(
+        'config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot',
+        async () => {
+          // the relocation landed: the new path exists, the old path is unlinked
+          expect(await exists(prepPath)).toBe(true);
+          expect(await exists(devPath)).toBe(false);
+
+          const after = await read(prepPath);
+          // the access itself is the one unambiguous token → migrated
+          expect(after).toContain('"access": "prep"');
+          expect(after).not.toContain('"access": "dev"');
+          // EVERY host survives byte-for-byte. the util runs on the CONSUMER's real config, whose
+          // host values are the consumer's own — a `.dev` label is axis-ambiguous WHEREVER it sits,
+          // so per guard #3 (a rewrite that cannot verify its output must not guess) NO host is
+          // rewritten.
+          expect(after).toContain('bastion.dev.example.com');
+          expect(after).toContain('aws.ssmproxy.mydb.dev');
+          expect(after).toContain('https://auth.myapp.dev');
+          // the FOREIGN public host is the decisive corruption case: a mid-dotted `dev` that is a
+          // foreign host's own label must survive byte-for-byte. teeth: the prior mid-dotted
+          // rewrite turned this into `api.prep.paypal.com`, a silent public-endpoint corruption
+          // (i013 r7.b1) surfaced only by a human read of the apply diff.
+          expect(after).toContain('api.dev.paypal.com');
+          expect(after).not.toContain('api.prep.paypal.com');
+          // no host was flipped to `.prep`, so no wrong-tier value ever enters the config
+          expect(after).not.toContain('bastion.prep.example.com');
+          expect(after).not.toContain('aws.ssmproxy.mydb.prep');
+          // the migration never emits a value it cannot verify — no marker bytes in config
+          expect(after).not.toContain('@declapract:review');
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('config/prep.json — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // config/dev.json is gone after the first relocate, so the EXISTS check no longer
+      // fires and no fix runs — config/prep.json must be untouched (per
+      // rule.require.idempotent-fixes).
+      const passes = useThen(
+        'a second apply over the already-migrated repo',
+        async () => {
+          const before = await read(prepPath);
+          await applyMigrate();
+          const after = await read(prepPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,17 @@
+{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}

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

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

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

@@ -0,0 +1,9 @@
+declarations: './'
+useCase: lambda-service
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  infrastructureNamespaceId: 'test'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

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

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

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

@@ -0,0 +1,43 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`config — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] a repo with a config/dev.json to migrate when: [t0] the migration input (before any fix) then: config/dev.json holds the dev tier + matches snapshot: config/dev.json — before 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;
+
+exports[`config — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] a repo with a config/dev.json to migrate when: [t1] the relocate + migrate fix is applied then: config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot: config/prep.json — after 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "prep"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prep.json.declapract.ts

@@ -7,9 +7,9 @@ export const check: FileCheckFunction = async (contents, context) => {
   if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
 
   // grab the desired keys
-  const testConfigJsonContents = await readFile(
-    `${context.getProjectRootDirectory()}/config/test.json`,
-  );
+  const testConfigJsonContents = await readFile({
+    filePath: `${context.getProjectRootDirectory()}/config/test.json`,
+  });
   if (!testConfigJsonContents)
     throw new Error('can only check if test file exists');
   const testConfigObject = JSON.parse(testConfigJsonContents);

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prod.json.declapract.ts

@@ -7,9 +7,9 @@ export const check: FileCheckFunction = async (contents, context) => {
   if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
 
   // grab the desired keys
-  const testConfigJsonContents = await readFile(
-    `${context.getProjectRootDirectory()}/config/test.json`,
-  );
+  const testConfigJsonContents = await readFile({
+    filePath: `${context.getProjectRootDirectory()}/config/test.json`,
+  });
   if (!testConfigJsonContents)
     throw new Error('can only check if test file exists');
   const testConfigObject = JSON.parse(testConfigJsonContents);

package/dist/practices/config/bad-practices/old-dev-config-location/config/dev.json.declapract.ts

@@ -1,21 +1,19 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
 
+import { asPrepConfigPath } from '../../../../../utils/asPrepConfigPath';
+import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToPrep';
+
 export const check = FileCheckType.EXISTS;
 
 export const fix: FileFixFunction = (contents, context) => {
-  // move config/dev.json → config/prep.json and update access: dev → prep
-  // also update .dev hostnames to .prep (e.g., bastion.dev.example.com → bastion.prep.example.com)
-  let fixed = contents;
-  if (fixed) {
-    fixed = fixed
-      .replace(/\.dev\b/g, '.prep')
-      .replace(/"access":\s*"dev"/, '"access": "prep"');
-  }
+  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
+  // both halves are shared utils, one source for both declarers: migrateDevConfigToPrep
+  // owns the content migration, asPrepConfigPath owns the relocate.
+  const fixed = contents ? migrateDevConfigToPrep({ contents }) : contents;
   return {
     contents: fixed ?? null,
-    relativeFilePath: context.relativeFilePath.replace(
-      /^config\/dev\.json$/,
-      'config/prep.json',
-    ),
+    relativeFilePath: asPrepConfigPath({
+      relativeFilePath: context.relativeFilePath,
+    }),
   };
 };

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

@@ -1,7 +1,7 @@
 {
   "dependencies": {
-    "sdk-aws-s3": "@declapract{check.minVersion('0.1.1')}",
-    "sdk-config": "@declapract{check.minVersion('0.1.1')}",
+    "sdk-aws-s3": "@declapract{check.minVersion('0.2.0')}",
+    "sdk-config": "@declapract{check.minVersion('0.2.3')}",
     "zod": "@declapract{check.minVersion('4.0.0')}"
   }
 }

package/dist/practices/config/best-practice/src/utils/config/getConfig.ts

@@ -39,12 +39,31 @@ const loaders = {
  *        { grant: 'plan' } or implicitly via the GRANT=plan env — the latter lets
  *        the ghlitch vpc tunnel (which calls getConfig() with no args) pick the
  *        plan scope at runtime without a code change.
+ * .name = `getConfig` is the org-canonical re-export of sdk-config's `genGetConfig`, called
+ *         `getConfig()` at every consumer site (the ghlitch vpc tunnel among them). it is an
+ *         external-package contract name, so it is exempt from the get-set-gen One/All cardinality
+ *         rule — a rename to `getOneConfig` breaks every consumer + diverges from sdk-config vocab.
  */
-export function getConfig<TGrant extends Grant = 'apply'>(input?: {
-  grant?: TGrant;
-}): Promise<Config<TGrant>> {
-  const grant = (input?.grant ??
+export const getConfig = <TGrant extends Grant = 'apply'>(
+  input: { grant: TGrant | null } = { grant: null },
+): Promise<Config<TGrant>> => {
+  // as-cast — why types miss: the runtime fallback yields the string literal
+  //   'plan' | 'apply', but the compiler cannot prove that value equals the
+  //   caller's free type parameter TGrant, so it stays `string`, not `TGrant`.
+  // correct type: the resolved value IS the caller's TGrant (a caller who omits
+  //   `grant` gets the default 'apply', which is TGrant's default).
+  // removal path: a `genGetConfig` overload keyed by the grant literal (or a
+  //   distributive conditional over TGrant) lets ts infer TGrant from the input
+  //   and drops this assertion.
+  const grant = (input.grant ??
     (process.env.GRANT === 'plan' ? 'plan' : 'apply')) as TGrant;
 
+  // as-cast — why types miss: `loaders` is a fixed { apply, plan } map keyed by
+  //   the literal grants; a lookup by the free TGrant loses the per-key return
+  //   type, so ts widens the result to the union of both loaders' returns.
+  // correct type: `Promise<Config<TGrant>>` — the loader at key TGrant returns
+  //   exactly the config for that grant.
+  // removal path: same as above — a per-grant overload or a distributive
+  //   conditional narrows the map lookup per-key and drops this assertion.
   return loaders[grant]() as Promise<Config<TGrant>>;
-}
+};

package/dist/practices/config/best-practice/src/utils/config/getOneCacheDirectory.ts

@@ -0,0 +1,33 @@
+import { sdkAwsS3 } from 'sdk-aws-s3';
+import type { DirectoryToPersistTo } from 'simple-on-disk-cache';
+import { isPresent } from 'type-fns';
+
+import { getOneProjectBucket } from './getOneProjectBucket';
+
+/**
+ * .what = casts a cache scope into its s3 uri prefix path
+ * .why = keeps the 'purpose=cache[/scope=<scope>]' pattern in one named place
+ */
+const asCachePrefix = (input: { scope: string | null }): string =>
+  ['purpose=cache', input.scope ? `scope=${input.scope}` : undefined]
+    .filter(isPresent)
+    .join('/');
+
+/**
+ * .what = gets the project's default cache directory, based on config
+ */
+export const getOneCacheDirectory = async (
+  input: { scope: string | null },
+): Promise<DirectoryToPersistTo> => {
+  // get the project bucket, then the scoped cache prefix
+  const bucket = await getOneProjectBucket();
+  const prefix = asCachePrefix({ scope: input.scope });
+
+  // persist to s3 via the sdk-aws-s3 cloud adapter
+  return {
+    cloud: {
+      path: `s3://${bucket}/${prefix}`,
+      via: sdkAwsS3,
+    },
+  };
+};

package/dist/practices/config/best-practice/src/utils/config/getOneProjectBucket.ts

@@ -0,0 +1,22 @@
+import { getConfig } from './getConfig';
+
+/**
+ * .what = casts config coordinates into the project's s3 bucket name
+ * .why = keeps the '<project>-<namespace>-<access>' pattern in one named place
+ */
+const asProjectBucketName = (input: {
+  config: Awaited<ReturnType<typeof getConfig>>;
+}): string =>
+  [
+    input.config.project,
+    input.config.aws.namespace,
+    input.config.environment.access,
+  ].join('-');
+
+/**
+ * .what = gets the project's default s3 bucket, based on config
+ */
+export const getOneProjectBucket = async (): Promise<string> => {
+  const config = await getConfig();
+  return asProjectBucketName({ config });
+};

package/dist/practices/config/best-practice/src/utils/environment.ts

@@ -1,3 +1,9 @@
-// this is a placeholder file, so that the declared acceptance test file passes typescript type checking. for this practice, we only check that the file exists
-export const stage = 'placeholder' as any;
-export const Stage = 'placeholder' as any;
+// note = a placeholder boundary. this practice only checks that the file EXISTS (it never
+//        checks its contents); the `environments` practice is the sole real declarer of
+//        `src/utils/environment.ts` and supplies the typed exports. this stub exists solely so
+//        the declared acceptance test file type-checks in a consumer that has `config` but not
+//        yet `environments`. removal path = when a consumer converges the `environments`
+//        practice, its real file overwrites this stub. the exports are typed `string` — no cast:
+//        the real `access` export is a tier string, so `string` is the honest widened type here
+//        and needs no `as`.
+export const access: string = 'placeholder';

package/dist/practices/config/best-practice/src/utils/environment.ts.declapract.ts

@@ -1,3 +1,11 @@
 import { FileCheckType } from 'declapract';
 
+/**
+ * .what = an EXISTS-only check on `src/utils/environment.ts`.
+ * .why = the `environments` practice, not `config`, authors the real `environment.ts`. this
+ *        practice only asserts the file is present. under BEST_PRACTICE purpose an EXISTS check
+ *        resolves `fix: null` (see declapract's getFileCheckDeclaration), so the peer template's
+ *        `as any` placeholder body is never written to a consumer — the contents are structurally
+ *        unreachable. safe to leave until the tracked CONTAINS-over-real-exports cleanup lands (D55).
+ */
 export const check = FileCheckType.EXISTS;

package/dist/practices/config/no-hand-written-config-type.declapract.integration.test.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that neither the `config` nor the `persist-with-rds` best-practice ships a
+ *         hand-written `Config.ts`, and that the schema-inferred `Config` is the sole source.
+ * .why  = the practice used to ship TWO `Config` exports in one dir: a hand-written `interface
+ *         Config` (Config.ts) and the grant-aware `z.infer` `Config` (config.schema.ts). the
+ *         hand-written twin has no reader (getConfig imports Config from ./config.schema), so it can
+ *         only drift from the live schema, never constrain it -- and it DID drift in a stamped repo
+ *         to `access: 'test' | 'dev' | 'prod'` (`dev` is a legacy deploy-slug value, never an access
+ *         tier; `prep` absent), read as a sanctioned contract and traced to a prod defect (#588). a dead type that
+ *         contradicts the live one is worse than absent -- it reads as authoritative. this clamp keeps
+ *         the twin gone.
+ * .teeth = re-create either best-practice `src/utils/config/Config.ts` and its case reddens; a drop
+ *          of the schema-inferred `Config` export reddens the sole-source case.
+ * .note = `.declapract.test.ts` = this repo's UNIT-test marker; at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different
+// cwd, and a repo-root-relative path under process.cwd() would then miss the tree (vacuous green) or
+// throw. from this file (src/practices/config/) the repo root is three segments up.
+const REPO_ROOT = join(__dirname, '../../..');
+
+const handWrittenConfigPaths = [
+  'src/practices/config/best-practice/src/utils/config/Config.ts',
+  'src/practices/persist-with-rds/best-practice/src/utils/config/Config.ts',
+];
+
+const configSchemaPath = join(
+  REPO_ROOT,
+  'src/practices/config/best-practice/src/utils/config/config.schema.ts',
+);
+
+describe('config practice ships no hand-written Config type', () => {
+  for (const relPath of handWrittenConfigPaths) {
+    given(`[case] ${relPath}`, () => {
+      when('[t0] the best-practice tree is inspected', () => {
+        then('the hand-written Config.ts is absent (schema is the source)', () => {
+          expect(existsSync(join(REPO_ROOT, relPath))).toEqual(false);
+        });
+
+        then('its declapract declaration is absent too', () => {
+          expect(existsSync(join(REPO_ROOT, `${relPath}.declapract.ts`))).toEqual(
+            false,
+          );
+        });
+      });
+    });
+  }
+
+  given('[case] the sole Config source', () => {
+    const schema = readFileSync(configSchemaPath, 'utf8');
+
+    when('[t0] config.schema.ts is read', () => {
+      then('it exports the grant-aware schema-inferred Config', () => {
+        expect(schema).toContain('export type Config<TGrant extends Grant');
+      });
+    });
+  });
+});

package/dist/practices/conventional-commits/__snapshots__/commitlint-body-max-line.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`conventional-commits commitlint body-max-line-length given: the shipped commitlint.config.js when: the body-max-line-length rule is read then: the emitted rule line matches snapshot: commitlint body-max-line-length rule line 1`] = `"'body-max-line-length': [1, 'always', 140],"`;

package/dist/practices/conventional-commits/best-practice/commitlint.config.js

@@ -2,6 +2,11 @@ module.exports = {
   extends: ['@commitlint/config-conventional'],
   rules: {
     'header-max-length': [1, 'always', 140],
+    // match the header allowance: a squash-merge turns each commit header
+    // into a `* ` body bullet, so a 140-char header becomes a ~142-char body
+    // line. keep body lines aligned with the 140-char header cap so a long
+    // header can never fail the release-branch commit lint.
+    'body-max-line-length': [1, 'always', 140],
     'type-enum': [
       2,
       'always',

package/dist/practices/conventional-commits/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "scripts": {
     "commit:with-cli": "npx cz",
-    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose"
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from \"${LAST_TAG:-}\" --to HEAD --verbose"
   },
   "devDependencies": {
     "@commitlint/cli": "@declapract{check.minVersion('19.5.0')}",

package/dist/practices/conventional-commits/commitlint-body-max-line.declapract.integration.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #554/#570: the shipped commitlint.config.js overrides body-max-line-length
+ *         to warn-level 140, aligned with the header-max-length cap, so a squash-merge release PR
+ *         cannot fail test:commits on a long header-turned-body-bullet.
+ * .why  = config-conventional's default body-max-line-length is error-level 100. a github
+ *         squash-merge collapses a PR's sub-commit headers into `* ` body bullets, so a header
+ *         near the 140-char header cap becomes a body line over 100 — which errors the
+ *         release-branch lint even though every source header was valid. the template MUST carry
+ *         the override (not just this repo's own root config, which #570 fixed) so every consumer
+ *         inherits it.
+ * .teeth = delete the body-max-line-length line from best-practice/commitlint.config.js and the
+ *          "declares body-max-line-length" assertion reddens (the config-conventional default,
+ *          error-level 100, reasserts).
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the practice
+ *         ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('conventional-commits commitlint body-max-line-length', () => {
+  given('the shipped commitlint.config.js', () => {
+    const source = readFileSync(
+      join(__dirname, 'best-practice/commitlint.config.js'),
+      'utf8',
+    );
+    const ruleLine = source
+      .split('\n')
+      .find((line) => line.includes('body-max-line-length'));
+
+    when('the body-max-line-length rule is read', () => {
+      then('it declares body-max-line-length (not the config-conventional default)', () => {
+        expect(ruleLine).toBeDefined();
+      });
+
+      then('it is warn-level 140, aligned with the header cap (a long header cannot block a release)', () => {
+        expect(ruleLine).toContain('[1, ');
+        expect(ruleLine).toContain('140]');
+      });
+
+      // the emitted rule line is the caller-faced contract: snapshot it so a reword that keeps
+      // the tokens green (a re-ordered tuple, a level change) reddens a vibecheck.
+      then('the emitted rule line matches snapshot', () => {
+        expect(ruleLine?.trim()).toMatchSnapshot('commitlint body-max-line-length rule line');
+      });
+    });
+  });
+});