declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.github/workflows/provision.yml.declapract.ts

@@ -78,11 +78,13 @@ export const check: FileCheckFunction = (contents, context) => {
 
 /**
  * .what = strip the 4 rds-coupled jobs, keeping every generic job intact.
- * .why  = reuse the best-practice truncation so the boundary is defined in one place; on an anchor
- *         miss `withoutRdsJobs` throws LOUD rather than truncating to the whole superset
- *         (`rule.forbid.failhide`).
+ * .why  = reuse the best-practice truncation so the boundary is defined in one place.
+ * .note = a consumer file with no anchor has no rds tail left — the same signal `check` reads as
+ *         "not detected" — so the fix returns it unchanged, and fix(fix(x)) === fix(x). the loud
+ *         anchor miss inside `withoutRdsJobs` stays where it guards: the best-practice template,
+ *         where a miss means the template drifted (`rule.forbid.failhide`).
  */
 export const fix: FileFixFunction = (contents) => {
-  if (!contents) return { contents };
+  if (!contents?.includes(RDS_JOBS_ANCHOR)) return { contents };
   return { contents: withoutRdsJobs({ contents }) };
 };

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/__snapshots__/.declapract.integration.test.ts.snap

@@ -140,8 +140,8 @@ jobs:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/test
-      github-environment-plan: test
-      github-environment-apply: test
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: \${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -150,8 +150,8 @@ jobs:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/prep
-      github-environment-plan: prep
-      github-environment-apply: prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: \${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -161,7 +161,7 @@ jobs:
     with:
       working-directory: provision/aws/environments/prod
       github-environment-plan: production-on-else-plan
-      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      github-environment-apply: \${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
       allow-apply: \${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: \${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
@@ -173,8 +173,8 @@ jobs:
       wish-path: provision/github.repo/resources.ts
       scope: github
       access: prod # github repo settings are inherently a prod resource
-      github-environment-plan: prod
-      github-environment-apply: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: \${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply
       creds-github-app-owner: \${{ github.repository_owner }}
       creds-github-app-id: \${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
     secrets:

package/dist/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml

@@ -9,7 +9,7 @@ on:
         required: true
       github-environment-apply:
         type: string
-        description: "github environment for the deploy jobs"
+        description: "the github environment for the deploy jobs; always declared, and one of the environments that provision/github.repo/resources.ts declares, e.g. preparation or production-on-main"
       creds-aws-region:
         description: "creds for aws, specifies the region"
         required: true
@@ -28,8 +28,8 @@ on:
         required: false
         description: enables sending pagerduty alarms on failure
 
+# .why = least privilege: only the jobs that assume the aws role grant id-token, at job scope
 permissions:
-  id-token: write # required for oidc
   contents: read
 
 jobs:
@@ -38,6 +38,9 @@ jobs:
 
   deploy:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
       # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on
@@ -72,6 +75,9 @@ jobs:
 
   assure:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
       # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on
@@ -110,12 +116,12 @@ jobs:
         if: inputs.needs-vpn-for-acceptance
         run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
 
-      # acceptance targets the contemp fleet — the service's own access-tier slug (-prep- at prep,
+      # acceptance targets the contemp fleet — the service's own access-keyed slug (-prep- at prep,
       # -prod- at prod). dual-publish ships the SAME artifact under the ancient (-dev-) slug too, so
       # a run against contemp proves the deployed code; the ancient slug is an alias for inbound
       # callers still on the old name, never a second target to test. contemp maps to the deployed
-      # access at both prep and prod, so one run covers every tier this job deploys — no
-      # per-fleet fan-out, no per-tier skip.
+      # access at both prep and prod, so one run covers every access this job deploys with — no
+      # per-fleet fan-out, no per-access skip.
       - name: test:acceptance
         run: ACCESS=${{ inputs.access }} npm run test:acceptance
 
@@ -130,6 +136,9 @@ jobs:
 
   prune:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
       # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on

package/dist/practices/cicd-service/best-practice/.github/workflows/.sql-schema-control.yml

@@ -30,8 +30,8 @@ on:
         description: "oidc role arn for the apply job"
         required: true
 
+# .why = least privilege: only the jobs that assume the aws role grant id-token, at job scope
 permissions:
-  id-token: write # required for oidc
   contents: read
 
 jobs:
@@ -40,6 +40,9 @@ jobs:
 
   plan:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
       # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
@@ -112,6 +115,9 @@ jobs:
 
   apply:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
       # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS

package/dist/practices/cicd-service/best-practice/.github/workflows/.terraform.yml

@@ -29,13 +29,16 @@ on:
         required: true
         type: string
 
+# .why = least privilege: only the jobs that assume the aws role grant id-token, at job scope
 permissions:
-  id-token: write # required for oidc
   contents: read
 
 jobs:
   plan:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
       # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
@@ -86,6 +89,9 @@ jobs:
 
   apply:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
       # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS

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');