declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/practices/cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts

@@ -1,6 +1,12 @@
-import { FileCheckType, type FileContentsFunction } from 'declapract';
+import type {
+  FileCheckFunction,
+  FileContentsFunction,
+  FileFixFunction,
+} from 'declapract';
 import { MalfunctionError } from 'helpful-errors';
 
+import { asWorkflowMergedByJob } from '../../../../../utils/asWorkflowMergedByJob';
+import { getAllWorkflowJobDrifts } from '../../../../../utils/getAllWorkflowJobDrifts';
 import { readFile } from '../../../../../utils/readFile';
 
 /**
@@ -13,9 +19,9 @@ import { readFile } from '../../../../../utils/readFile';
  *         `lambda-service-with-dynamodb`) ships none of them, so those jobs fail its own
  *         provision workflow — D28/#573, live on 2 of 3 service usecases. a branch on
  *         `context.projectPractices` lets one practice serve all three usecases
- *         (`rule.avoid.runtime-forks`), and CONTAINS (not EQUALS) keeps a narrow
- *         `--practice cicd-service` apply from a strip of an rds repo's own jobs — the additive
- *         usecase-delta EQUALS hazard named in that rule's caveat table.
+ *         (`rule.avoid.runtime-forks`), and a merge-by-job check + fix (not EQUALS) keeps a
+ *         narrow `--practice cicd-service` apply from a strip of an rds repo's own jobs — the
+ *         additive usecase-delta EQUALS hazard named in that rule's caveat table.
  * .note = the 4 rds jobs are the contiguous tail after the generic `github` job, so a split on
  *         the first rds job header (`sql-schema-prep:`) truncates the whole rds block cleanly.
  */
@@ -71,4 +77,60 @@ export const contents: FileContentsFunction = async (context) => {
     : withoutRdsJobs({ contents: contentsSuperset });
 };
 
-export const check = FileCheckType.CONTAINS;
+/**
+ * .what = the declared contents this check and fix read, or a loud failure where none arrived
+ * .why  = the `contents` fn above always emits a body, so an absent one is a malfunction of the
+ *         pipeline, never a consumer input
+ */
+const asDeclaredContents = (input: {
+  declaredFileContents: string | null;
+  relativeFilePath: string;
+}): string => {
+  if (input.declaredFileContents === null)
+    throw new MalfunctionError(
+      'the cicd-service practice emitted no declared provision.yml',
+      { practice: 'cicd-service', relativeFilePath: input.relativeFilePath },
+    );
+  return input.declaredFileContents;
+};
+
+/**
+ * .what = pass when every declared top-level key and every declared job holds its declared shape;
+ *         the repo's own jobs never count as drift
+ * .why  = a text-contains check with no fix left a pre-oidc caller in place after its callees went
+ *         oidc-only, and github then rejected the workflow with `startup_failure` (#685). a
+ *         merge-by-job check reads each declared job, so a stale one is flagged and repaired,
+ *         while a repo may still add jobs of its own (the reason this was never EQUALS).
+ * .note = scope-safe: under a narrow `--practice cicd-service` the `contents` fn emits the
+ *         non-rds body, so the rds jobs go undeclared — and an undeclared job is kept, never
+ *         stripped. `rds-jobs-in-non-rds-service` alone owns that strip, behind its callee guard.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('provision.yml is absent');
+  const drift = getAllWorkflowJobDrifts({
+    found: contents,
+    declared: asDeclaredContents(context),
+    dropJobWhen: null,
+  });
+  if (drift.length > 0)
+    throw new Error(
+      `provision.yml drifts from its declaration:\n- ${drift.join('\n- ')}`,
+    );
+};
+
+/**
+ * .what = create the file where absent; else merge each declared job and top-level key into it
+ * .why  = see `check`. the merge keeps the repo's own jobs and comments, and returns the found
+ *         text untouched where no drift remains, so a second apply changes zero bytes.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const declared = asDeclaredContents(context);
+  if (!contents) return { contents: declared };
+  return {
+    contents: asWorkflowMergedByJob({
+      found: contents,
+      declared,
+      dropJobWhen: null,
+    }),
+  };
+};

package/dist/practices/cicd-service/provision.yml.merge.declapract.integration.test.ts

@@ -0,0 +1,144 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+import { parse } from 'yaml';
+
+import { getAllWorkflowJobDrifts } from '../../utils/getAllWorkflowJobDrifts';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(240_000);
+
+/**
+ * .what = end-to-end proof of the provision.yml merge-by-job fix (#685), run through the REAL
+ *         declapract apply against a pre-oidc caller
+ * .why  = the callee workflows went oidc-only; a caller still on the retired access-key inputs
+ *         fails at github with `startup_failure` before any job starts. the old declaration was a
+ *         text-contains check with no fix, so `apply` reported the drift and changed no byte. only a
+ *         real apply proves declapract wires the custom check + fix to this file, that each declared
+ *         job lands in its oidc shape, and that the repo's own job survives.
+ * .note = the apply is scoped by `file`, so `projectPractices` keeps `persist-with-rds` and the
+ *         declaration emits its rds superset. [t2] then runs a NARROW `--practice cicd-service`
+ *         apply, where `projectPractices` shrinks and the emitted body drops the rds jobs — the
+ *         merge must keep them, since an undeclared job is never stripped.
+ */
+
+const FIXTURE = './src/practices/cicd-service/.test/assets/demo-repo-pre-oidc';
+const DECLARATIONS_MIRROR = './src/.test/assets/cicd-service/declarations';
+const PROVISION_PATH = '.github/workflows/provision.yml';
+const SOURCE_SUPERSET =
+  'src/practices/cicd-service/best-practice/.github/workflows/provision.yml';
+
+const DECLARED_JOBS = [
+  'aws-test-terraform',
+  'aws-prep-terraform',
+  'aws-prod-terraform',
+  'github',
+  'sql-schema-prep',
+  'sql-schema-prod',
+  'aws-prep-declastruct',
+  'aws-prod-declastruct',
+];
+
+describe('provision.yml — merge-by-job fix, end to end (#685)', () => {
+  given('[case1] an rds service whose provision.yml is a pre-oidc caller with a repo-own job', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-cicd-service-provision-pre-oidc',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const config = () => path.join(tempDir, 'declapract.use.rds.yml');
+
+    const state = useBeforeAll(async () => {
+      const superset = await fs.readFile(SOURCE_SUPERSET, 'utf-8');
+      const before = await read(PROVISION_PATH);
+      await executeApply({ config: config(), file: PROVISION_PATH });
+      const after1 = await read(PROVISION_PATH);
+      await executeApply({ config: config(), file: PROVISION_PATH });
+      const after2 = await read(PROVISION_PATH);
+      await executeApply({ config: config(), practice: 'cicd-service' });
+      const afterNarrow = await read(PROVISION_PATH);
+      return { superset, before, after1, after2, afterNarrow };
+    }, 230_000);
+
+    when('[t0] declapract apply', () => {
+      then('each declared job matches the oidc template shape', () => {
+        const jobsAfter = parse(state.after1).jobs;
+        const jobsDeclared = parse(state.superset).jobs;
+        for (const name of DECLARED_JOBS)
+          expect(jobsAfter[name]).toEqual(jobsDeclared[name]);
+      });
+
+      then('no retired access-key input survives in a declared job', () => {
+        expect(state.before).toContain('aws-access-key-id');
+        expect(state.after1).not.toContain('aws-access-key-id');
+        expect(state.after1).not.toContain('aws-account-id');
+      });
+
+      then('the repo-own job survives, unchanged', () => {
+        expect(parse(state.after1).jobs['seed-prep-fixtures']).toEqual(
+          parse(state.before).jobs['seed-prep-fixtures'],
+        );
+        expect(state.after1).toContain(
+          "# the repo's own job, which the practice never declares",
+        );
+      });
+
+      then('the pull_request trigger stays bare, with no paths gate', () => {
+        expect(parse(state.after1).on.pull_request).toBeNull();
+      });
+
+      then("the repo's own schedule trigger survives, comment and all", () => {
+        expect(parse(state.after1).on.schedule).toEqual(
+          parse(state.before).on.schedule,
+        );
+        expect(parse(state.after1).on.schedule).toEqual([
+          { cron: '0 6 * * *' },
+        ]);
+        expect(state.after1).toContain(
+          "# the repo's own nightly drift plan, which the practice never declares",
+        );
+      });
+
+      then('the oidc permissions block lands', () => {
+        expect(parse(state.after1).permissions).toEqual({
+          'id-token': 'write',
+          contents: 'read',
+        });
+      });
+
+      then('the check passes on the fixed file', () => {
+        expect(
+          getAllWorkflowJobDrifts({
+            found: state.after1,
+            declared: state.superset,
+            dropJobWhen: null,
+          }),
+        ).toEqual([]);
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.before).toMatchSnapshot('provision.yml — before (pre-oidc)');
+        expect(state.after1).toMatchSnapshot('provision.yml — after merge');
+      });
+    });
+
+    when('[t1] declapract apply again', () => {
+      then('zero bytes change', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+
+    when('[t2] a narrow --practice cicd-service apply, where the rds jobs go undeclared', () => {
+      then('the rds jobs and the repo-own job survive; zero bytes change', () => {
+        expect(state.afterNarrow).toEqual(state.after1);
+      });
+    });
+  });
+});

package/dist/practices/commands/best-practice/src/contract/commands/sayHello.ts

@@ -1,8 +1,9 @@
 import { asCommand } from '@ehmpathy/as-command';
 import { getResourceNameFromFileName } from 'visualogic';
 
-import { access } from '../../utils/environment';
-import { log } from '../../utils/logger';
+import { access } from '@src/utils/environment';
+import { log } from '@src/utils/logger';
+
 import { COMMANDS_OUTPUT_DIRECTORY } from './__tmp__/directory';
 
 const command = asCommand(

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

@@ -4,8 +4,11 @@ import path from 'node:path';
 import { executeApply } from 'declapract';
 import { genTempDir, given, then, useThen, when } from 'test-fns';
 
+// each executeApply evaluates the whole usecase; under full-suite load one apply runs past 90s
+jest.setTimeout(240_000);
+
 /**
- * .what = end-to-end proof of the `old-dev-config-location` relocate + tier-migrate, run
+ * .what = end-to-end proof of the `old-dev-config-location` relocate + access-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`
@@ -15,21 +18,21 @@ import { genTempDir, given, then, useThen, when } from 'test-fns';
  *         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
+ * .teeth = the input holds `"access": "dev"` — the ONE unambiguous access 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
+ *          rewritten. the after-state proves the access 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)', () => {
+describe('config — old-dev-config-location relocate + access-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' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const devPath = 'config/dev.json';
@@ -49,7 +52,7 @@ describe('config — old-dev-config-location relocate + tier-migrate (row-4 clam
       });
 
     when('[t0] the migration input (before any fix)', () => {
-      then('config/dev.json holds the dev tier + matches snapshot', async () => {
+      then('config/dev.json holds the dev access + matches snapshot', async () => {
         const before = await read(devPath);
         expect(before).toContain('"access": "dev"');
         expect(before).toMatchSnapshot('config/dev.json — before');
@@ -83,7 +86,7 @@ describe('config — old-dev-config-location relocate + tier-migrate (row-4 clam
           // (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
+          // no host was flipped to `.prep`, so no wrong-access 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

package/dist/practices/config/.test/assets/demo-repo-with-dev-config/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/config/.test/assets/demo-repo-with-hand-written-config-type/declapract.use.yml

@@ -0,0 +1,9 @@
+declarations: 'declarations/declapract.declare.yml'
+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-hand-written-config-type/declarations/declapract.declare.yml

@@ -0,0 +1,6 @@
+# the test symlinks `declarations/practices` -> src/practices and `declarations/useCases.yml` ->
+# src/useCases.yml at genTempDir time, so the temp repo's own `src/` (the hand-written Config.ts and
+# its importers) stays its own.
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/practices/config/.test/assets/demo-repo-with-hand-written-config-type/package.json

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

package/dist/practices/config/.test/assets/demo-repo-with-hand-written-config-type/src/logic/getSurfReport.ts

@@ -0,0 +1,4 @@
+import type { Config } from '../utils/config/Config';
+
+export const getSurfReport = (input: { config: Config }) =>
+  input.config.environment.access;

package/dist/practices/config/.test/assets/demo-repo-with-hand-written-config-type/src/utils/config/Config.ts

@@ -0,0 +1,3 @@
+export interface Config {
+  environment: { access: 'test' | 'dev' | 'prod' };
+}

package/dist/practices/config/.test/assets/demo-repo-with-hand-written-config-type/src/utils/config/getAccessLabel.ts

@@ -0,0 +1,4 @@
+import type { Config } from './Config';
+
+export const getAccessLabel = (input: { config: Config }) =>
+  `access=${input.config.environment.access}`;

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

@@ -1,6 +1,6 @@
 // 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`] = `
+exports[`config — old-dev-config-location relocate + access-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 access + matches snapshot: config/dev.json — before 1`] = `
 "{
   "organization": "test-org",
   "project": "test-project",
@@ -21,7 +21,7 @@ exports[`config — old-dev-config-location relocate + tier-migrate (row-4 clamp
 "
 `;
 
-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`] = `
+exports[`config — old-dev-config-location relocate + access-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",

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

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`config.schema.ts — a superset check (#658) given: [case3] a schema that dropped a base name 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: config.schema.ts — marker line 1`] = `"// @declapract:review: config.schema.ts lacks the base name(s) namespace that getConfig and the config files expect — add them, as the config practice's base template declares them; then delete this marker"`;

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

@@ -0,0 +1,33 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`config — hand-written-config-type retires Config.ts (#661) given: [case1] a repo with a hand-written Config.ts and two importers when: [t0] the fix is applied, then applied again then: before and after match snapshot: src/logic/getSurfReport.ts — after 1`] = `
+"import type { Config } from '../utils/config/config.schema';
+
+export const getSurfReport = (input: { config: Config }) =>
+  input.config.environment.access;
+"
+`;
+
+exports[`config — hand-written-config-type retires Config.ts (#661) given: [case1] a repo with a hand-written Config.ts and two importers when: [t0] the fix is applied, then applied again then: before and after match snapshot: src/logic/getSurfReport.ts — before 1`] = `
+"import type { Config } from '../utils/config/Config';
+
+export const getSurfReport = (input: { config: Config }) =>
+  input.config.environment.access;
+"
+`;
+
+exports[`config — hand-written-config-type retires Config.ts (#661) given: [case1] a repo with a hand-written Config.ts and two importers when: [t0] the fix is applied, then applied again then: before and after match snapshot: src/utils/config/getAccessLabel.ts — after 1`] = `
+"import type { Config } from './config.schema';
+
+export const getAccessLabel = (input: { config: Config }) =>
+  \`access=\${input.config.environment.access}\`;
+"
+`;
+
+exports[`config — hand-written-config-type retires Config.ts (#661) given: [case1] a repo with a hand-written Config.ts and two importers when: [t0] the fix is applied, then applied again then: before and after match snapshot: src/utils/config/getAccessLabel.ts — before 1`] = `
+"import type { Config } from './Config';
+
+export const getAccessLabel = (input: { config: Config }) =>
+  \`access=\${input.config.environment.access}\`;
+"
+`;

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prep.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 prepConfigObject = JSON.parse(contents);
-  const flattenedPrepConfigKeys = Object.keys(flatten(prepConfigObject));
-
-  // determine which keys are not matched
-  const keysInTestButNotInPrep = flattenedTestConfigKeys.filter(
-    (key) => !flattenedPrepConfigKeys.includes(key),
-  );
-  const keysInPrepButNotInTest = flattenedPrepConfigKeys.filter(
-    (key) => !flattenedTestConfigKeys.includes(key),
-  );
-  if (keysInTestButNotInPrep.length) return; // matches bad practice
-  if (keysInPrepButNotInTest.length) return; // matches bad practice
+  // matches bad practice when the prep 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/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();