declapract-typescript-ehmpathy 0.49.13 → 0.49.14

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

@@ -1,33 +1,26 @@
 import type { FileCheckFunction } from 'declapract';
-import flatten from 'flat';
 
+import { isConfigShapeDivergent } from '../../../../../utils/isConfigShapeDivergent';
 import { readFile } from '../../../../../utils/readFile';
 
 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
+  // grab the desired shape
   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);
-  const flattenedTestConfigKeys = Object.keys(flatten(testConfigObject));
 
-  // grab the found keys
-  const prodConfigObject = JSON.parse(contents);
-  const flattenedProdConfigKeys = Object.keys(flatten(prodConfigObject));
-
-  // determine which keys are not matched
-  const keysInTestButNotInProd = flattenedTestConfigKeys.filter(
-    (key) => !flattenedProdConfigKeys.includes(key),
-  );
-  const keysInProdButNotInTest = flattenedProdConfigKeys.filter(
-    (key) => !flattenedTestConfigKeys.includes(key),
-  );
-  if (keysInTestButNotInProd.length) return; // matches bad practice
-  if (keysInProdButNotInTest.length) return; // matches bad practice
+  // matches bad practice when the prod shape diverges from the test shape
+  if (
+    isConfigShapeDivergent({
+      expected: JSON.parse(testConfigJsonContents),
+      found: JSON.parse(contents),
+    })
+  )
+    return;
 
   // otherwise, does not match a bad practice
   throw new Error('its fine');

package/dist/practices/config/bad-practices/hand-written-config-type/.declapract.readme.md

@@ -0,0 +1,3 @@
+a repo stamped before #588 holds a hand-written `src/utils/config/Config.ts`. `getConfig` now types off `config.schema.ts`, so the hand-written copy has no reader and can only drift from the live schema (it drifted to `access: 'test' | 'dev' | 'prod'` in one adopter).
+
+the fix deletes `src/utils/config/Config.ts` and repoints each import of it (`./Config` inside `src/utils/config/`, or any `…/utils/config/Config`) to `config.schema`, which exports the schema-inferred `Config`.

package/dist/practices/config/bad-practices/hand-written-config-type/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,68 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = whether a module specifier names the hand-written `src/utils/config/Config.ts`
+ * .why  = two shapes reach it: `…/utils/config/Config` from anywhere, and `./Config` from a file
+ *         inside `src/utils/config/`. a `Config` module anywhere else is the repo's own and is left
+ *         alone.
+ */
+const isHandWrittenConfigSpecifier = (input: {
+  specifier: string;
+  relativeFilePath: string;
+}): boolean => {
+  if (/(^|\/)utils\/config\/Config$/.test(input.specifier)) return true;
+  return (
+    input.specifier === './Config' &&
+    /^src\/utils\/config\/[^/]+$/.test(input.relativeFilePath)
+  );
+};
+
+// the static `from '<specifier>'` clause whose specifier the check reads for a config import
+const FROM_SPECIFIER_PATTERN = /(\bfrom\s+)(['"])([^'"]+)\2/g;
+
+/**
+ * .what = repoint each import of the hand-written Config.ts to config.schema
+ */
+const asContentsWithConfigSchemaImports = (input: {
+  contents: string;
+  relativeFilePath: string;
+}): string =>
+  input.contents.replace(
+    FROM_SPECIFIER_PATTERN,
+    (match, from: string, quote: string, specifier: string) =>
+      isHandWrittenConfigSpecifier({
+        specifier,
+        relativeFilePath: input.relativeFilePath,
+      })
+        ? `${from}${quote}${specifier.replace(/Config$/, 'config.schema')}${quote}`
+        : match,
+  );
+
+/**
+ * .what = flags a source file that imports the hand-written Config.ts (#661)
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (
+    contents &&
+    asContentsWithConfigSchemaImports({
+      contents,
+      relativeFilePath: context.relativeFilePath,
+    }) !== contents
+  )
+    return; // imports the hand-written Config.ts → bad practice
+  throw new Error('does not import the hand-written Config.ts');
+};
+
+/**
+ * .what = repoints each import of the hand-written Config.ts to config.schema, which exports the
+ *         schema-inferred Config
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return {};
+  return {
+    contents: asContentsWithConfigSchemaImports({
+      contents,
+      relativeFilePath: context.relativeFilePath,
+    }),
+  };
+};

package/dist/practices/config/bad-practices/hand-written-config-type/src/utils/config/Config.ts.declapract.ts

@@ -0,0 +1,10 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// a hand-written Config.ts is the bad practice; config.schema.ts infers Config (#661)
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = delete the hand-written Config.ts
+ * .why  = it has no reader once getConfig types off config.schema.ts, so it can only drift
+ */
+export const fix: FileFixFunction = () => ({ contents: null });

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

@@ -6,7 +6,7 @@ import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToP
 export const check = FileCheckType.EXISTS;
 
 export const fix: FileFixFunction = (contents, context) => {
-  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
+  // move config/dev.json → config/prep.json and migrate the access 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;

package/dist/practices/config/bad-practices/unmigrated-param-paths/.declapract.readme.md

@@ -0,0 +1,15 @@
+a config that names a param by an explicit path — `$.at(aws::param/org/repo/…)` — cannot be flipped
+to the bare `$.at(aws::param)` by a fix: the bare form makes sdk-config read
+`/{org}/{project}/{config}/{keyPath}`, a param that holds no value until someone copies it there.
+a flip before the copy breaks `getConfig()`.
+
+so the fix leaves every path as is and stamps a top-level `"@declapract:review"` key into each of
+`config/{test,prep,prod}.json` (all three, so their key sets stay equal) that names the copy step.
+zod's object schema strips the key on parse.
+
+to migrate:
+
+1. copy each explicit-path value to its derived name (see `provision/aws/readme.md` in the
+   `persist-with-rds` practice)
+2. swap each explicit path for the bare `$.at(aws::param)`
+3. delete the `"@declapract:review"` key; with no explicit path left, the check no longer flags it

package/dist/practices/config/bad-practices/unmigrated-param-paths/config/prep.json.declapract.ts

@@ -0,0 +1,3 @@
+import { genUnmigratedParamPathsDeclaration } from '../../../../../utils/genUnmigratedParamPathsDeclaration';
+
+export const { check, fix } = genUnmigratedParamPathsDeclaration();

package/dist/practices/config/bad-practices/unmigrated-param-paths/config/prod.json.declapract.ts

@@ -0,0 +1,3 @@
+import { genUnmigratedParamPathsDeclaration } from '../../../../../utils/genUnmigratedParamPathsDeclaration';
+
+export const { check, fix } = genUnmigratedParamPathsDeclaration();

package/dist/practices/config/bad-practices/unmigrated-param-paths/config/test.json.declapract.ts

@@ -0,0 +1,3 @@
+import { genUnmigratedParamPathsDeclaration } from '../../../../../utils/genUnmigratedParamPathsDeclaration';
+
+export const { check, fix } = genUnmigratedParamPathsDeclaration();

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

@@ -0,0 +1,18 @@
+## getConfig and oidc grants
+
+`src/utils/config/getConfig.ts` loads `config/*.json` plus the aws parameter-store supplier, under
+one of two grants:
+
+- `apply` (the default) parses with `schema.apply`, so every secret is required and `Config` holds
+  no `| undefined`
+- `plan` parses with `schema.plan`, which tolerates the secrets the plan role may not read. a caller
+  opts in with `getConfig({ grant: 'plan' })`, or with `GRANT=plan` in the env — the latter lets a
+  caller that passes no args (e.g. the ghlitch vpc tunnel) pick the plan scope with no code change
+
+each grant has its own loader and its own cache, so a plan miss never poisons the apply cache.
+
+`getConfig` keeps sdk-config's name: every consumer calls `getConfig()`, so a rename would break
+each call site.
+
+the two `as` casts in `getConfig` exist because ts cannot relate the runtime grant to the caller's
+type parameter `TGrant`; a per-grant overload of `genGetConfig` would let both go.

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

@@ -1,7 +1,10 @@
 {
   "dependencies": {
     "sdk-aws-s3": "@declapract{check.minVersion('0.2.0')}",
-    "sdk-config": "@declapract{check.minVersion('0.2.3')}",
+    "sdk-config": "@declapract{check.minVersion('0.3.0')}",
+    "simple-in-memory-cache": "@declapract{check.minVersion('0.5.1')}",
+    "simple-on-disk-cache": "@declapract{check.minVersion('1.8.1')}",
+    "type-fns": "@declapract{check.minVersion('1.21.4')}",
     "zod": "@declapract{check.minVersion('4.0.0')}"
   }
 }

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

@@ -0,0 +1,78 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = the names a config schema must hold to stay a superset of the base template
+ * .why  = every service extends the base with its own keys, and `persist-with-rds` ships a superset
+ *         of it; what each must keep is the base keys and the two exports getConfig reads
+ */
+const BASE_KEYS = [
+  'organization',
+  'project',
+  'environment',
+  'access',
+  'aws',
+  'account',
+  'namespace',
+] as const;
+const BASE_EXPORTS = [
+  { name: 'schema', pattern: /\bexport\s+const\s+schema\b/ },
+  { name: 'Config', pattern: /\bexport\s+type\s+Config\b/ },
+] as const;
+
+/**
+ * .what = the token that marks a schema a human must reconcile with the base by hand
+ */
+const REVIEW_MARKER_TOKEN = '@declapract:review: config.schema.ts lacks';
+
+/**
+ * .what = the base names a schema file lacks: each key absent as `key:`, each export absent
+ * .note = a regex over names, not a parse of the ts object literal: a key renamed or nested
+ *         elsewhere still reads as present, which only loosens the check (never a false red)
+ */
+export const getAllBaseNamesAbsent = (input: {
+  contents: string;
+}): string[] => [
+  ...BASE_KEYS.filter(
+    (key) => !new RegExp(`\\b${key}\\s*:`).test(input.contents),
+  ),
+  ...BASE_EXPORTS.filter(({ pattern }) => !pattern.test(input.contents)).map(
+    ({ name }) => name,
+  ),
+];
+
+/**
+ * .what = checks that `src/utils/config/config.schema.ts` holds a superset of the base schema (#630,
+ *         #658): every base key and both exports present, whatever keys it adds.
+ * .why  = an EQUALS check here would fail on every extended schema, rewrite it to the base on each
+ *         apply, and fight `persist-with-rds` in a 2-cycle that never converges. a superset check
+ *         lets the one owner (persist-with-rds, where in play) hold the file, and still catches a
+ *         schema that dropped a key getConfig reads.
+ * .note = a file that carries the review marker passes: the fix has handed the merge to a human,
+ *         and a check that still failed would make core mark the file manual.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents === null)
+    throw new Error('src/utils/config/config.schema.ts is absent');
+  if (contents.includes(REVIEW_MARKER_TOKEN)) return;
+  const absent = getAllBaseNamesAbsent({ contents });
+  if (absent.length)
+    throw new Error(
+      `src/utils/config/config.schema.ts lacks the base name(s): ${absent.join(', ')}`,
+    );
+};
+
+/**
+ * .what = writes the base schema where the file is absent; where a present file lacks base names,
+ *         stamps one review marker at the top that names them; else leaves the file unchanged.
+ * .why  = a ts schema cannot be merged by text without a risk to the service's own keys, so the
+ *         merge of a drifted file is a human's call; the marker names exactly what to add.
+ * .note = idempotent: the marker is stamped once, and a marked file passes the check.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (contents === null) return { contents: context.declaredFileContents };
+  if (contents.includes(REVIEW_MARKER_TOKEN)) return { contents };
+  const absent = getAllBaseNamesAbsent({ contents });
+  if (!absent.length) return { contents };
+  const marker = `// ${REVIEW_MARKER_TOKEN} the base name(s) ${absent.join(', ')} that getConfig and the config files expect — add them, as the config practice's base template declares them; then delete this marker`;
+  return { contents: `${marker}\n${contents}` };
+};

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

@@ -4,12 +4,11 @@ import {
 } from 'sdk-config';
 import { createCache } from 'simple-in-memory-cache';
 
-import { envStatic } from '../environment';
+import { envStatic } from '@src/utils/environment';
+
 import { type Config, type Grant, schema } from './config.schema';
 
-// one loader per grant. both read the same config/*.json + suppliers; they differ
-// only in which schema arbitrates the reader-denied secrets (see config.schema.ts).
-// caches are separate so a plan miss never poisons the apply cache.
+// one loader per grant, each with its own cache (see the config practice readme)
 const common = {
   statics: 'config/*.json' as const,
   suppliers: [genSdkConfigSupplierAwsParameterStore()],
@@ -32,38 +31,16 @@ const loaders = {
 } as const;
 
 /**
- * .what = load the config, scoped to an oidc grant (default apply).
- * .why = default 'apply' returns the fully-required Config, so ordinary consumers
- *        get no `| undefined` in their config type. the plan job opts into 'plan'
- *        (which tolerates the reader-denied secrets) either explicitly via
- *        { 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.
+ * .what = load the config for an oidc grant: `apply` (default) or `plan`, via input or GRANT=plan
+ * .why = `plan` tolerates the secrets its role may not read; `apply` keeps every secret required
  */
 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.
+  // as-cast: the fallback grant is the caller's TGrant. removal path: a per-grant overload
   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.
+  // as-cast: the loader at key TGrant returns Config<TGrant>. removal path: as above
   return loaders[grant]() as Promise<Config<TGrant>>;
 };

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

@@ -16,9 +16,9 @@ const asCachePrefix = (input: { scope: string | null }): string =>
 /**
  * .what = gets the project's default cache directory, based on config
  */
-export const getOneCacheDirectory = async (
-  input: { scope: string | null },
-): Promise<DirectoryToPersistTo> => {
+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 });

package/dist/practices/config/config-schema-superset.declapract.integration.test.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { FileCheckContext, FileFixContext } from 'declapract';
+import { getError, given, then, when } from 'test-fns';
+
+import {
+  check,
+  fix,
+} from './best-practice/src/utils/config/config.schema.ts.declapract';
+
+/**
+ * .what = clamps #658: config's `config.schema.ts` check passes on any superset of the base schema,
+ *         so the persist-with-rds template (its owner where in play) is never rewritten to the base,
+ *         and a schema that dropped a base name is caught.
+ * .teeth = revert the check to EQUALS and case2 goes red; revert it to a bare presence check and
+ *          case3 goes red.
+ */
+
+const templateBase = readFileSync(
+  join(__dirname, 'best-practice/src/utils/config/config.schema.ts'),
+  'utf-8',
+);
+const templateRds = readFileSync(
+  join(
+    __dirname,
+    '../persist-with-rds/best-practice/src/utils/config/config.schema.ts',
+  ),
+  'utf-8',
+);
+const context = {
+  declaredFileContents: templateBase,
+} as unknown as FileCheckContext & FileFixContext; // only declaredFileContents is read
+
+describe('config.schema.ts — a superset check (#658)', () => {
+  given('[case1] the file is absent', () => {
+    when('[t0] check, then fix, then check', () => {
+      then('check fails, fix writes the base, and check then passes', async () => {
+        expect(await getError(async () => check(null, context))).toBeInstanceOf(Error);
+        const fixed = await fix(null, context);
+        expect(fixed.contents).toEqual(templateBase);
+        expect(() => check(fixed.contents, context)).not.toThrow();
+      });
+    });
+  });
+
+  given('[case2] a schema that extends the base', () => {
+    when('[t0] the persist-with-rds template is checked', () => {
+      then('it passes, and fix leaves it byte-identical', async () => {
+        expect(() => check(templateRds, context)).not.toThrow();
+        expect((await fix(templateRds, context)).contents).toEqual(templateRds);
+      });
+    });
+
+    when('[t1] a service schema with its own keys is checked', () => {
+      const extended = templateBase.replace(
+        '  aws: z.object({',
+        '  openai: z.object({ apiKey: z.string() }),\n  aws: z.object({',
+      );
+      then('it passes', () => {
+        expect(extended).toContain('openai:');
+        expect(() => check(extended, context)).not.toThrow();
+      });
+    });
+  });
+
+  given('[case3] a schema that dropped a base name', () => {
+    const drifted = templateBase.replace('    namespace: z.string(),\n', '');
+
+    when('[t0] check runs', () => {
+      then('it fails and names the absent key', async () => {
+        const error = await getError(async () => check(drifted, context));
+        expect(error.message).toContain('namespace');
+        expect(error.message).not.toContain('organization');
+      });
+    });
+
+    when('[t1] fix runs, then check, then fix again', () => {
+      then('fix stamps one marker that names the key; check passes; a rerun is a no-op', async () => {
+        const once = (await fix(drifted, context)).contents as string;
+        expect(once.split('\n')[0]).toContain('@declapract:review');
+        expect(once.split('\n')[0]).toContain('namespace');
+        expect(once).toContain(drifted); // the service's own text is untouched
+        expect(() => check(once, context)).not.toThrow();
+        expect((await fix(once, context)).contents).toEqual(once);
+        expect(once.split('\n')[0]).toMatchSnapshot('config.schema.ts — marker line');
+      });
+    });
+  });
+});

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

@@ -0,0 +1,101 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof that the `hand-written-config-type` bad-practice deletes an adopter's
+ *         `src/utils/config/Config.ts` and repoints each import of it to `config.schema` (#661).
+ * .why  = #588 dropped the hand-written Config.ts from the practice tree, but a repo stamped before
+ *         #588 keeps its own copy; it has no reader and drifts (`access: 'test' | 'dev' | 'prod'`).
+ *         a unit test of the fix never proves the glob matches the importers or that EXISTS + a
+ *         null fix deletes the file.
+ * .teeth = drop the bad-practice dir and the Config.ts survives, its importers still name it.
+ */
+
+const CONFIG_PATH = 'src/utils/config/Config.ts';
+const IMPORTERS = [
+  'src/utils/config/getAccessLabel.ts',
+  'src/logic/getSurfReport.ts',
+];
+
+const exists = (filePath: string): Promise<boolean> =>
+  fs
+    .access(filePath)
+    .then(() => true)
+    .catch(() => false);
+
+// whole-usecase evaluation per file runs tens of seconds
+jest.setTimeout(600_000);
+
+describe('config — hand-written-config-type retires Config.ts (#661)', () => {
+  given('[case1] a repo with a hand-written Config.ts and two importers', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-config-hand-written-config-type',
+      clone:
+        './src/practices/config/.test/assets/demo-repo-with-hand-written-config-type',
+      symlink: [
+        { at: 'declarations/practices', to: 'src/practices' },
+        { at: 'declarations/useCases.yml', to: 'src/useCases.yml' },
+      ],
+    });
+
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyAll = async () => {
+      for (const file of [CONFIG_PATH, ...IMPORTERS])
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'config',
+          file,
+        });
+    };
+
+    when('[t0] the fix is applied, then applied again', () => {
+      const scene = useBeforeAll(async () => {
+        const before = {
+          config: await read(CONFIG_PATH),
+          importers: await Promise.all(IMPORTERS.map(read)),
+        };
+        await applyAll();
+        const once = {
+          configFound: await exists(path.join(tempDir, CONFIG_PATH)),
+          importers: await Promise.all(IMPORTERS.map(read)),
+        };
+        await applyAll();
+        const twice = {
+          configFound: await exists(path.join(tempDir, CONFIG_PATH)),
+          importers: await Promise.all(IMPORTERS.map(read)),
+        };
+        return { before, once, twice };
+      });
+
+      then('the hand-written Config.ts is deleted', () => {
+        expect(scene.before.config).toContain("'dev'");
+        expect(scene.once.configFound).toBe(false);
+      });
+
+      then('each importer now names config.schema', () => {
+        expect(scene.once.importers[0]).toContain("from './config.schema'");
+        expect(scene.once.importers[1]).toContain(
+          "from '../utils/config/config.schema'",
+        );
+        scene.once.importers.forEach((contents) =>
+          expect(contents).not.toMatch(/config\/Config'|'\.\/Config'/),
+        );
+      });
+
+      then('a second apply changes no byte', () => {
+        expect(scene.twice).toEqual(scene.once);
+      });
+
+      then('before and after match snapshot', () => {
+        IMPORTERS.forEach((file, index) => {
+          expect(scene.before.importers[index]).toMatchSnapshot(`${file} — before`);
+          expect(scene.once.importers[index]).toMatchSnapshot(`${file} — after`);
+        });
+      });
+    });
+  });
+});

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

@@ -10,8 +10,8 @@ import { given, then, when } from 'test-fns';
  *         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
+ *         to `access: 'test' | 'dev' | 'prod'` (`dev` is a legacy deploy-slug value, never an access;
+ *         `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

package/dist/practices/config/template-prose-condensed.declapract.integration.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the `src/utils/config/*` templates carry short comments: no run of comment
+ *         lines longer than four, and no `.name` defense (#690).
+ * .why  = every adopter inherits these files, and every reader pays for their prose. the long
+ *         rationale lives in each practice's `.declapract.readme.md`, with a pointer left behind.
+ * .teeth = restore an 8-line as-cast note into getConfig.ts and its case reddens with the run.
+ */
+
+const REPO_ROOT = join(__dirname, '../../..');
+const TEMPLATES = [
+  'src/practices/config/best-practice/src/utils/config/getConfig.ts',
+  'src/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts',
+];
+const MAX_COMMENT_RUN = 4;
+
+/**
+ * .what = the longest run of consecutive comment lines in a source, with the line it starts at
+ */
+const getOneLongestCommentRun = (input: {
+  source: string;
+}): { length: number; startLine: number } =>
+  input.source.split('\n').reduce(
+    (acc, line, index) => {
+      const isComment = /^\s*(\/\/|\/\*\*|\*)/.test(line);
+      const current = isComment ? acc.current + 1 : 0;
+      const start = isComment && acc.current === 0 ? index + 1 : acc.start;
+      return current > acc.longest.length
+        ? { current, start, longest: { length: current, startLine: start } }
+        : { current, start, longest: acc.longest };
+    },
+    { current: 0, start: 0, longest: { length: 0, startLine: 0 } },
+  ).longest;
+
+describe('config templates carry condensed prose (#690)', () => {
+  TEMPLATES.forEach((relPath) =>
+    given(`[case] ${relPath}`, () => {
+      const source = readFileSync(join(REPO_ROOT, relPath), 'utf8');
+
+      when('[t0] its comments are read', () => {
+        then(`no run of comment lines exceeds ${MAX_COMMENT_RUN}`, () => {
+          const run = getOneLongestCommentRun({ source });
+          expect({ relPath, ...run, overMax: run.length > MAX_COMMENT_RUN }).toEqual({
+            relPath,
+            ...run,
+            overMax: false,
+          });
+        });
+
+        then('no `.name` defense block', () => {
+          expect(source).not.toContain('.name =');
+        });
+      });
+    }),
+  );
+});

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

@@ -7,6 +7,9 @@ module.exports = {
     // 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],
+    // the same allowance for the footer: a long `Co-Authored-By:` or `Refs:` trailer
+    // must never fail a commit lint the body rule would pass
+    'footer-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) && commitlint --from \"${LAST_TAG:-}\" --to HEAD --verbose"
   },
   "devDependencies": {
     "@commitlint/cli": "@declapract{check.minVersion('19.5.0')}",