declapract-typescript-ehmpathy 0.49.13 → 0.49.15

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/pg-pool-patch.declapract.integration.test.ts.snap

@@ -0,0 +1,147 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.2.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.2.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.2.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.2.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.3.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.3.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.4.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.4.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.4.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.4.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.5.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.5.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.5.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.5.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.7.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.7.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.7.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.7.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.8.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.8.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.5, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.5 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.6, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.6 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.10.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.10.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.10.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.10.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.11.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.11.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.12.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.12.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.13.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.13.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.14.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.14.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case4] an rds repo that already holds its own "pg-pool@3.14.0" hand patch when: [t0] the persist-with-rds practice is applied then: the before + after contents match snapshot: package.json — after 1`] = `
+"{
+  "name": "repo-with-hand-patch",
+  "version": "1.0.0",
+  "dependencies": {
+    "pg": "8.3.0",
+    "pg-pool": "3.14.0",
+    "iso-time": "@declapract{check.minVersion('<floor>')}",
+    "yesql": "@declapract{check.minVersion('<floor>')}"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "pg-pool@3.14.0": "patches/pg-pool@3.14.0.patch",
+      "left-pad@1.3.0": "patches/left-pad@1.3.0.patch",
+      "pg-pool": "patches/pg-pool.patch"
+    }
+  },
+  "devDependencies": {
+    "sql-code-generator": "@declapract{check.minVersion('<floor>')}",
+    "sql-dao-generator": "@declapract{check.minVersion('<floor>')}",
+    "sql-schema-control": "@declapract{check.minVersion('<floor>')}",
+    "sql-schema-generator": "@declapract{check.minVersion('<floor>')}",
+    "@types/yesql": "@declapract{check.minVersion('<floor>')}",
+    "@types/pg": "@declapract{check.minVersion('<floor>')}"
+  },
+  "scripts": {
+    "generate:dao:postgres": "sql-dao-generator generate && npm run fix:format",
+    "generate:schema": "sql-schema-generator generate -c codegen.sql.schema.yml && npm run fix:format",
+    "generate:types-from-sql": "sql-code-generator generate -c codegen.sql.types.yml && npm run fix:format",
+    "provision:schema:plan": "sql-schema-control plan -c provision/schema/control.yml",
+    "provision:schema:apply": "sql-schema-control apply -c provision/schema/control.yml",
+    "provision:schema:sync": "sql-schema-control sync -c provision/schema/control.yml",
+    "provision:testdb:docker:clear": "for port in $(bash provision/docker/testdb/compose.sh config --format json | jq -r '.services[].ports[]?.published'); do docker rm -f $(docker ps -a -f \\"publish=$port\\" -q) 2>/dev/null || true; done && echo 'ensured ports are available 👍'",
+    "provision:testdb:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/testdb/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/testdb/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/testdb/init/user.cicd.sql",
+    "provision:testdb:docker:up": "bash provision/docker/testdb/compose.sh up -d --force-recreate --build --renew-anon-volumes",
+    "provision:testdb:docker:await": "bash provision/docker/testdb/compose.sh exec -T postgres /root/wait-for-postgres.sh",
+    "provision:testdb:docker:down": "bash provision/docker/testdb/compose.sh down",
+    "provision:testdb": "npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && ACCESS=test npm run provision:schema:plan && ACCESS=test npm run provision:schema:apply && ACCESS=test npm run provision:schema:plan",
+    "start:testdb": "npm run provision:testdb",
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
+  }
+}
+"
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case4] an rds repo that already holds its own "pg-pool@3.14.0" hand patch when: [t0] the persist-with-rds practice is applied then: the before + after contents match snapshot: package.json — before 1`] = `
+"{
+  "name": "repo-with-hand-patch",
+  "version": "1.0.0",
+  "dependencies": {
+    "pg": "8.3.0",
+    "pg-pool": "3.14.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "pg-pool@3.14.0": "patches/pg-pool@3.14.0.patch",
+      "left-pad@1.3.0": "patches/left-pad@1.3.0.patch"
+    }
+  }
+}
+"
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case5] a pg-pool release where the patched line moved, so the hunk fails when: [t0] pnpm install runs then: the warn an adopter reads matches snapshot: pnpm install — patch failure warn 1`] = `
+[
+  " WARN  Could not apply patch <tempdir>/patches/pg-pool.patch to <tempdir>/node_modules/.pnpm/pg-pool@3.14.0_patch_hash=<hash>_pg@8.3.0/node_modules/pg-pool",
+]
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case6] a bare rds adopter: pg, pg-pool, the shipped cycle check, and one src file that imports pg when: [t0] its cycle check runs, with the shipped patch then: the verdict an adopter reads matches snapshot: test:lint:cycles — with the shipped patch 1`] = `
+[
+  "> pg-pool-patch-demo@ test:lint:cycles <tempdir>",
+  "> EXCL=$(node -p "(require('yaml').parse(require('fs').readFileSync('.dpdmrc.yaml','utf8'))?.exclude ?? []).join('|')") && dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude "$EXCL" 'src/**/!(*.test).ts'",
+  "• Circular Dependencies",
+  "  ✅ Congratulations, no circular dependency was found in your project.",
+  "- Start analyzing dependencies...",
+  "✔ [37/37] Analyze done!",
+]
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case6] a bare rds adopter: pg, pg-pool, the shipped cycle check, and one src file that imports pg when: [t1] its cycle check runs, with no patch then: the verdict an adopter reads matches snapshot: test:lint:cycles — with no patch 1`] = `
+[
+  "> pg-pool-patch-demo@ test:lint:cycles <tempdir>",
+  "> EXCL=$(node -p "(require('yaml').parse(require('fs').readFileSync('.dpdmrc.yaml','utf8'))?.exclude ?? []).join('|')") && dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude "$EXCL" 'src/**/!(*.test).ts'",
+  "• Circular Dependencies",
+  "  1) node_modules/.pnpm/pg@<floor>/node_modules/pg/lib/index.js -> node_modules/.pnpm/pg-pool@3.14.0_pg@<floor>/node_modules/pg-pool/index.js",
+  " ELIFECYCLE  Command failed with exit code 1.",
+  "- Start analyzing dependencies...",
+  "✔ [37/37] Analyze done!",
+]
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/ssm-param-names.declapract.integration.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds ssm param names are the sdk-config derived names (#637) given: [case1] the wish run with ACCESS=prep CONFIG=prep when: [t0] getAllParameters is called with no choice override then: the declared names match snapshot 1`] = `
+[
+  "/@declapract{variable.organizationName}/@declapract{variable.projectName}/prep/database.role.crud.password",
+  "/@declapract{variable.organizationName}/@declapract{variable.projectName}/prep/database.role.cicd.for-plan.password",
+  "/@declapract{variable.organizationName}/@declapract{variable.projectName}/prep/database.role.cicd.for-apply.password",
+]
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/with-connection-in-input.declapract.integration.test.ts.snap

@@ -0,0 +1,57 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds with-connection-in-input given: [case1] a repo whose op imports withDatabaseConnection when: [t0] the input (before any fix) then: both src files match snapshot: op — before 1`] = `
+"import { DatabaseConnection } from '../utils/database/getDatabaseConnection';
+import {
+  withDatabaseConnection,
+} from '../utils/database/withDatabaseConnection';
+
+export const findSurferById = withDatabaseConnection(
+  async ({ id, dbConnection }: { id: string; dbConnection: DatabaseConnection }) =>
+    dbConnection.query({ sql: 'select * from surfer where id = :id', values: { id } }),
+);
+"
+`;
+
+exports[`persist-with-rds with-connection-in-input given: [case1] a repo whose op imports withDatabaseConnection when: [t0] the input (before any fix) then: both src files match snapshot: wrapper — before 1`] = `
+"import { DatabaseConnection, getDatabaseConnection } from './getDatabaseConnection';
+
+export const withDatabaseConnection =
+  <I extends { dbConnection: DatabaseConnection }, O>(
+    logic: (input: I) => Promise<O>,
+  ) =>
+  async (input: Omit<I, 'dbConnection'>): Promise<O> => {
+    const dbConnection = await getDatabaseConnection();
+    return logic({ ...input, dbConnection } as I);
+  };
+"
+`;
+
+exports[`persist-with-rds with-connection-in-input given: [case1] a repo whose op imports withDatabaseConnection when: [t1] the fix is applied then: the op gains one review line above its import, which names withDatabaseContext: op — after 1`] = `
+"import { DatabaseConnection } from '../utils/database/getDatabaseConnection';
+import {
+  withDatabaseConnection,
+// @declapract:review: withDatabaseConnection (dbConnection in the input) is retired — move to withDatabaseContext (src/utils/database/withDatabaseContext.ts), the (input, context) shape: each op becomes \`(input, context) => …\`, a dependency (dbConnection, log) moves out of the input into the context arg, and each caller passes it as the 2nd arg. then delete this marker
+} from '../utils/database/withDatabaseConnection';
+
+export const findSurferById = withDatabaseConnection(
+  async ({ id, dbConnection }: { id: string; dbConnection: DatabaseConnection }) =>
+    dbConnection.query({ sql: 'select * from surfer where id = :id', values: { id } }),
+);
+"
+`;
+
+exports[`persist-with-rds with-connection-in-input given: [case1] a repo whose op imports withDatabaseConnection when: [t1] the fix is applied then: the wrapper stays in place, marked, so the tree still builds: wrapper — after 1`] = `
+"import { DatabaseConnection, getDatabaseConnection } from './getDatabaseConnection';
+
+// @declapract:review: withDatabaseConnection (dbConnection in the input) is retired — move to withDatabaseContext (src/utils/database/withDatabaseContext.ts), the (input, context) shape: each op becomes \`(input, context) => …\`, a dependency (dbConnection, log) moves out of the input into the context arg, and each caller passes it as the 2nd arg. then delete this marker
+export const withDatabaseConnection =
+  <I extends { dbConnection: DatabaseConnection }, O>(
+    logic: (input: I) => Promise<O>,
+  ) =>
+  async (input: Omit<I, 'dbConnection'>): Promise<O> => {
+    const dbConnection = await getDatabaseConnection();
+    return logic({ ...input, dbConnection } as I);
+  };
+"
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.declapract.integration.test.ts

@@ -0,0 +1,71 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the legacy-change-id rename (#530), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = a unit test of `fix` never proves the `provision/schema/**\/*.yml` glob reaches a nested
+ *        definitions file, nor that one apply leaves the best-practice `init.yml` (CONTAINS, now on
+ *        `exid:`) satisfied. the repo's own change entry must move too, and keep its comment.
+ * .note = the init.yml is snapshotted in full, before AND after, per
+ *         rule.require.declapract-integration-tests.
+ */
+// each apply evaluates the whole practice, which runs long under a full suite
+jest.setTimeout(10 * 60 * 1000);
+
+describe('legacy-change-id (#530)', () => {
+  given('[case1] a repo whose schema definitions use the legacy `id:` key', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-persist-with-rds-legacy-change-id',
+      clone:
+        './src/practices/persist-with-rds/bad-practices/legacy-change-id/.test/assets/demo-repo-with-legacy-change-id',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    const initPath = 'provision/schema/sql/init.yml';
+    const read = () => fs.readFile(path.join(tempDir, initPath), 'utf-8');
+    const apply = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'persist-with-rds',
+        file: initPath,
+      });
+
+    when('[t0] the input, before any fix', () => {
+      then('init.yml holds `id:` on each change, and matches snapshot', async () => {
+        const before = await read();
+        expect(before).toContain('  id: init_service_user');
+        expect(before).toMatchSnapshot('init.yml — before');
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      useThen('apply the fix', async () => apply());
+
+      then('each change entry declares `exid:`, the repo extra kept, and matches snapshot', async () => {
+        const after = await read();
+        expect(after).toContain('  exid: init_default_txn_isolation');
+        expect(after).toContain('  exid: init_service_user');
+        expect(after).toContain('  exid: init_analyst_user');
+        expect(after).toContain('# a change the repo added on its own');
+        expect(after).not.toMatch(/^\s*id:/m);
+        expect(after).toMatchSnapshot('init.yml — after');
+      });
+    });
+
+    when('[t2] apply runs again (idempotency)', () => {
+      const passes = useThen('a second apply', async () => {
+        const before = await read();
+        await apply();
+        return { before, after: await read() };
+      });
+
+      then('the second apply changes zero bytes', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.declapract.readme.md

@@ -0,0 +1,6 @@
+sql-schema-control@1.8.0 renamed a change entry's natural key from `id:` to `exid:`. the tool still
+reads `id:`, with a deprecation nudge on every plan and apply.
+
+this fix renames `id:` to `exid:` on each `type: change` entry under `provision/schema/`. the value
+stays the same, so the change hashes still match. an `id` key outside a change entry is left alone,
+and an entry that already declares `exid` is left alone.

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.test/assets/demo-repo-with-legacy-change-id/declapract.declare.yml

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.test/assets/demo-repo-with-legacy-change-id/declapract.use.yml

@@ -0,0 +1,19 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: 'testdb'
+  databaseClusterName: 'testdb'
+  databaseUserName:
+    cicdUser: 'testdb_cicd'
+    serviceUser: 'testdb_service'
+  databaseTunnelHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  databaseClusterHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.test/assets/demo-repo-with-legacy-change-id/package.json

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/.test/assets/demo-repo-with-legacy-change-id/provision/schema/sql/init.yml

@@ -0,0 +1,15 @@
+- type: change
+  id: init_default_txn_isolation
+  author: declapract
+  path: ./init/default_transaction_isolation.sql
+
+- type: change
+  id: init_service_user
+  author: declapract
+  path: ./init/user.service.sql
+
+# a change the repo added on its own
+- type: change
+  id: init_analyst_user
+  author: surfschool
+  path: ./init/user.analyst.sql

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,39 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`legacy-change-id (#530) given: [case1] a repo whose schema definitions use the legacy \`id:\` key when: [t0] the input, before any fix then: init.yml holds \`id:\` on each change, and matches snapshot: init.yml — before 1`] = `
+"- type: change
+  id: init_default_txn_isolation
+  author: declapract
+  path: ./init/default_transaction_isolation.sql
+
+- type: change
+  id: init_service_user
+  author: declapract
+  path: ./init/user.service.sql
+
+# a change the repo added on its own
+- type: change
+  id: init_analyst_user
+  author: surfschool
+  path: ./init/user.analyst.sql
+"
+`;
+
+exports[`legacy-change-id (#530) given: [case1] a repo whose schema definitions use the legacy \`id:\` key when: [t1] apply runs then: each change entry declares \`exid:\`, the repo extra kept, and matches snapshot: init.yml — after 1`] = `
+"- type: change
+  exid: init_default_txn_isolation
+  author: declapract
+  path: ./init/default_transaction_isolation.sql
+
+- type: change
+  exid: init_service_user
+  author: declapract
+  path: ./init/user.service.sql
+
+# a change the repo added on its own
+- type: change
+  exid: init_analyst_user
+  author: surfschool
+  path: ./init/user.analyst.sql
+"
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/legacy-change-id/provision/schema/<star><star>/<star>.yml.declapract.ts

@@ -0,0 +1,68 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { isMap, isScalar, parseDocument, visit } from 'yaml';
+
+/**
+ * .what = the `id` key of each sql-schema-control change entry that still uses the legacy key
+ * .why = sql-schema-control@1.8.0 renamed a change's natural key from `id:` to `exid:`. the
+ *        tool still reads `id:`, but nudges on every plan and apply. only the key on a
+ *        `type: change` entry moves; an `id` key anywhere else in the yml is not the tool's.
+ * .note = an entry that already declares `exid` is never a target — whether it also holds an
+ *         `id` (the tool rejects that pair) or not. a rename there would leave two `exid` keys.
+ */
+const getLegacyChangeIdKeyRanges = (input: {
+  contents: string;
+}): { start: number; end: number }[] => {
+  const document = parseDocument(input.contents);
+  const ranges: { start: number; end: number }[] = [];
+  visit(document, {
+    Map: (_key, map) => {
+      if (!isMap(map)) return;
+      const isChange = map.get('type') === 'change';
+      if (!isChange) return;
+      if (map.has('exid')) return;
+      const pair = map.items.find(
+        (item) => isScalar(item.key) && item.key.value === 'id',
+      );
+      if (!pair || !isScalar(pair.key) || !pair.key.range) return;
+      ranges.push({ start: pair.key.range[0], end: pair.key.range[1] });
+    },
+  });
+  return ranges;
+};
+
+/**
+ * .what = the contents with `exid` spliced over each given key range
+ * .why = a splice keeps every other byte — comments, blank lines, quotes — exactly as the repo
+ *        wrote them
+ * .note = applied bottom-up, so the earlier offsets stay valid
+ */
+const withExidOverRanges = (input: {
+  contents: string;
+  ranges: { start: number; end: number }[];
+}): string =>
+  [...input.ranges]
+    .sort((a, b) => b.start - a.start)
+    .reduce(
+      (text, range) =>
+        `${text.slice(0, range.start)}exid${text.slice(range.end)}`,
+      input.contents,
+    );
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents && getLegacyChangeIdKeyRanges({ contents }).length > 0) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no sql-schema-control change entry uses the legacy `id:` key',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // splice `exid` over each legacy key
+  return {
+    contents: withExidOverRanges({
+      contents,
+      ranges: getLegacyChangeIdKeyRanges({ contents }),
+    }),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-dev-config-location/config/dev.json.declapract.ts

@@ -6,28 +6,18 @@ import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToP
 export const check = FileCheckType.EXISTS;
 
 /**
- * .what = rewrite the rds password placeholder `"__CHANG3_ME__"` to the aws-param reference.
- * .why  = the rds config twin adds this one transform the config twin lacks; a named op keeps the
- *         declarer's `fix` a what-not-how read (rule.require.named-transformers).
+ * .what = move config/dev.json → config/prep.json and migrate the access tokens (dev → prep)
+ * .why  = both halves are shared utils (one source for both declarers): migrateDevConfigToPrep
+ *         owns the content migration, asPrepConfigPath owns the relocate. the `__CHANG3_ME__`
+ *         passwords stay as they are — `deploy.database.sh` creates prep users with that
+ *         password, so a flip to `$.at(aws::param)` would point the app at params that hold no
+ *         value (#683).
  */
-const withAwsParamPlaceholder = (input: { contents: string }): string =>
-  input.contents.replace(/"__CHANG3_ME__"/g, '"$.at(aws::param)"');
-
-export const fix: FileFixFunction = (contents, context) => {
-  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
-  // both halves are shared utils (one source for both declarers): migrateDevConfigToPrep
-  // owns the content migration, asPrepConfigPath owns the relocate. this declarer adds the
-  // rds-only aws-param placeholder rewrite on top.
-  const updatedContents = contents
-    ? withAwsParamPlaceholder({
-        contents: migrateDevConfigToPrep({ contents }),
-      })
-    : contents;
-
-  return {
-    contents: updatedContents ?? null,
-    relativeFilePath: asPrepConfigPath({
-      relativeFilePath: context.relativeFilePath,
-    }),
-  };
-};
+export const fix: FileFixFunction = (contents, context) => ({
+  contents: contents
+    ? migrateDevConfigToPrep({ contents })
+    : (contents ?? null),
+  relativeFilePath: asPrepConfigPath({
+    relativeFilePath: context.relativeFilePath,
+  }),
+});