declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-get-database-connection/src/utils/database/getDatabaseConnection.integration.test.ts.declapract.ts

@@ -0,0 +1,43 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asTemplateFingerprint } from '../../../../../../../utils/asTemplateFingerprint';
+import {
+  isGetDatabaseConnectionImporter,
+  withGetDatabaseConnectionRepointed,
+} from '../../../../../../../utils/withGetDatabaseConnectionRepointed';
+
+/**
+ * .what = the fingerprint of the one test body persist-with-rds shipped at this path
+ * .why = that test duplicates getOneDatabaseConnection.integration.test.ts, so the fix deletes it
+ *        when the repo still holds the shipped body; an edited copy is repointed instead
+ */
+export const OLD_TEST_TEMPLATE_FINGERPRINTS: string[] = [
+  '9f828d9d66611826e89a00ba28a28496d0648f13d2b937b8d599844256f63213', // 66284e3, unchanged through b8d4803
+];
+
+export const check: FileCheckFunction = (contents) => {
+  // detect the shipped duplicate, or any copy that still reaches the retired module
+  if (
+    contents !== null &&
+    (OLD_TEST_TEMPLATE_FINGERPRINTS.includes(
+      asTemplateFingerprint({ source: contents }),
+    ) ||
+      isGetDatabaseConnectionImporter({ source: contents }))
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no shipped getDatabaseConnection test, and no import of the retired module',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+
+  // delete the shipped duplicate
+  const fingerprint = asTemplateFingerprint({ source: contents });
+  if (OLD_TEST_TEMPLATE_FINGERPRINTS.includes(fingerprint))
+    return { contents: null };
+
+  // keep an edited copy, repointed onto the new factory
+  return { contents: withGetDatabaseConnectionRepointed({ source: contents }) };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-get-database-connection/src/utils/database/getDatabaseConnection.ts.declapract.ts

@@ -0,0 +1,51 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asTemplateFingerprint } from '../../../../../../../utils/asTemplateFingerprint';
+
+/**
+ * .what = the fingerprint of every body persist-with-rds ever shipped at this path
+ * .why = the fix deletes the file only when the repo still holds one of these bodies; an adopter's
+ *        edit must never be dropped silently. one per template revision, 2021-08 through 2026-05,
+ *        each proven by a fixture in this bad-practice's `.test/assets/old-templates/`
+ * .note = ten revisions, eight fingerprints: 66284e3 → d1e8cd7 → ef25ae0 were format-only changes
+ */
+export const OLD_TEMPLATE_FINGERPRINTS: string[] = [
+  '4652212f6406f8245aec5c8595975b1bb60a0f18b0191af5c5943fa40b372e7d', // 66284e3, d1e8cd7, ef25ae0
+  'c4382197566f98a406536c74c34637ddd93d894fa69e6608a6a665599fe46a9f', // 3a193e5
+  'a6b220f1ffffb81c1d793744be5c4324f401e45e1bc2c5b8d2f88525e04118e3', // 9e1bdc4
+  'ef6e06c5aaafbee194a5e209178b6b1e40a57f5870fd76f7ac33aa108d3a653e', // c6cef7e
+  'e38f23c3ef7b148ae1974001e65e05f1f92ebcb5eade23974ac6de40df68cbd7', // eab15c0
+  '8b1ffaa9a42d778b7a8ca07bda6cc7d405665aa44a02aec15379992d6e57970d', // c8eb35b
+  '0283efcee1fc208d125a24fe1c101599cecad67828a33108b2fa8c8a849b71d7', // 68cf8ba
+  '6871c674157bb59da937231cf8aac7e17e3c34a0c2e59c580fcf33e2709a64f2', // e0c53d8
+];
+
+/**
+ * .what = the review pointer stamped above an edited copy
+ * .why = an edited copy is kept, so `plan` stays red; the pointer names what a human must do
+ */
+const REVIEW_MARKER =
+  '// @declapract:review: getDatabaseConnection.ts is retired — its importers now read getOneDatabaseConnection. move any local edit into getOneDatabaseConnection.ts, then delete this file';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents !== null) return; // bad practice detected: the retired factory is still here
+  throw new Error(
+    'does not match bad practice: getDatabaseConnection.ts is absent',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+
+  // delete the file when it is still a template the practice shipped
+  const fingerprint = asTemplateFingerprint({ source: contents });
+  if (OLD_TEMPLATE_FINGERPRINTS.includes(fingerprint))
+    return { contents: null };
+
+  // otherwise keep the adopter's edit, and stamp the pointer once
+  if (
+    contents.includes('@declapract:review: getDatabaseConnection.ts is retired')
+  )
+    return { contents };
+  return { contents: `${REVIEW_MARKER}\n${contents}` };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-dir/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration_test_db` to `provision/docker/testdb`

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-dir/provision/docker/integration_test_db/<star><star>/<star>.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice
+
+export const fix: FileFixFunction = async (contents, { relativeFilePath }) => {
+  // Move from integration_test_db to testdb
+  const newPath = relativeFilePath.replace(
+    'provision/docker/integration_test_db',
+    'provision/docker/testdb',
+  );
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-hyphen-dir/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration-test-db` to `provision/docker/testdb`

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-hyphen-dir/provision/docker/integration-test-db/<star><star>/<star>.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice
+
+export const fix: FileFixFunction = async (contents, { relativeFilePath }) => {
+  // Move from integration-test-db to testdb
+  const newPath = relativeFilePath.replace(
+    'provision/docker/integration-test-db',
+    'provision/docker/testdb',
+  );
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration-test-db` to `provision/docker/testdb` - this detects old paths in package.json scripts

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/package.json

@@ -0,0 +1,8 @@
+{
+  "scripts": {
+    "provision:testdb:docker:prepare": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:up": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:await": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:down": "@declapract{check.contains('integration-test-db')}"
+  }
+}

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/package.json.declapract.ts

@@ -0,0 +1,10 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // do nothing if no contents
+  // Replace integration-test-db with testdb in all paths
+  const fixed = contents.replace(/integration-test-db/g, 'testdb');
+  return { contents: fixed };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-packagejson-script-names/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "provision:docker:clear": "docker rm -f $(docker ps -a -f 'publish=7821' -q) 2>/dev/null || true && echo 'ensured port is available 👍'",
+    "provision:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/integration-test-db/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/integration-test-db/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/integration-test-db/init/user.cicd.sql",
+    "provision:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:docker:await": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
+    "provision:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down"
+  }
+}

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts

@@ -0,0 +1,22 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // do nothing if no contents
+  const packageJSON = JSON.parse(contents);
+  const updatedPackageJSON = {
+    ...packageJSON,
+    scripts: {
+      ...packageJSON.scripts,
+      'provision:docker:clear': undefined,
+      'provision:docker:prepare': undefined,
+      'provision:docker:up': undefined,
+      'provision:docker:await': undefined,
+      'provision:docker:down': undefined,
+    },
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/old-param-placeholder/config/<star>.json.declapract.ts

@@ -0,0 +1,14 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('__PARAM__')) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  return {
+    contents: contents.replace(/"__PARAM__"/g, '"$.at(aws::param)"'),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.declapract.integration.test.ts

@@ -0,0 +1,86 @@
+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 pg-client-without-ssl fix (#652), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer repo
+ * .why = a unit test of `fix` never proves the `src/**\/*.ts` glob reaches a client the repo built
+ *        on its own, nor that one apply leaves it converged. a client that reads the app config is
+ *        given verified tls; a client that does not is flagged for a human, and never guessed at
+ * .note = each touched file 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('pg-client-without-ssl (#652)', () => {
+  given('[case1] a repo with two plaintext pg clients of its own', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-persist-with-rds-pg-client-without-ssl',
+      clone:
+        './src/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const files = [
+      'src/utils/database/getSurfReportConnection.ts',
+      'src/access/sdks/sdkWaveArchive.ts',
+    ];
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyAll = async () => {
+      for (const file of files)
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file,
+        });
+    };
+
+    when('[t0] the input, before any fix', () => {
+      then('each client file matches snapshot', async () => {
+        for (const file of files)
+          expect(await read(file)).toMatchSnapshot(`${file} — before`);
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      useThen('apply the fix', async () => applyAll());
+
+      then('the config-backed client declares verified tls, and matches snapshot', async () => {
+        const after = await read(files[0]!);
+        expect(after).toContain(
+          'ssl: asDatabaseClientSsl({ clusterEndpoint: config.database.tunnel.lambda?.host ?? null }),',
+        );
+        expect(after).toContain(
+          "import { asDatabaseClientSsl } from '@src/utils/database/asDatabaseClientSsl';",
+        );
+        expect(after).toMatchSnapshot(`${files[0]} — after`);
+      });
+
+      then('the client outside the config is flagged, not guessed at, and matches snapshot', async () => {
+        const after = await read(files[1]!);
+        expect(after.split('\n')[0]).toContain('@declapract:review: a pg Client here');
+        expect(after).toContain(
+          'new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });',
+        );
+        expect(after).toMatchSnapshot(`${files[1]} — after`);
+      });
+    });
+
+    when('[t2] apply runs again (idempotency)', () => {
+      const passes = useThen('a second apply', async () => {
+        const before = await Promise.all(files.map((file) => read(file)));
+        await applyAll();
+        const after = await Promise.all(files.map((file) => read(file)));
+        return { before, after };
+      });
+
+      then('the second apply changes zero bytes', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.declapract.readme.md

@@ -0,0 +1,9 @@
+a pg `Client` built with no `ssl` option connects in plaintext. a postgres 17 cluster forces ssl
+by default, so that client fails to connect at all once the cluster is upgraded.
+
+this fix gives each such client `ssl: asDatabaseClientSsl({ clusterEndpoint })`, which verifies the
+cluster certificate against the rds us-east-1 roots and connects plain to the local testdb.
+
+the fix names the endpoint as `config.database.tunnel.lambda?.host`, so it applies only where the
+file already reads `config.database.tunnel`. any other file gets a review pointer at its top, since
+a human must pick the endpoint there.

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/declapract.declare.yml

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

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/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/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/package.json

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

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/src/access/sdks/sdkWaveArchive.ts

@@ -0,0 +1,7 @@
+import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/src/utils/database/getSurfReportConnection.ts

@@ -0,0 +1,19 @@
+import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+  });
+  await client.connect();
+  return client;
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,72 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t0] the input, before any fix then: each client file matches snapshot: src/access/sdks/sdkWaveArchive.ts — before 1`] = `
+"import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t0] the input, before any fix then: each client file matches snapshot: src/utils/database/getSurfReportConnection.ts — before 1`] = `
+"import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+  });
+  await client.connect();
+  return client;
+};
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t1] apply runs then: the client outside the config is flagged, not guessed at, and matches snapshot: src/access/sdks/sdkWaveArchive.ts — after 1`] = `
+"// @declapract:review: a pg Client here connects with no tls. pass \`ssl: asDatabaseClientSsl({ clusterEndpoint })\` from @src/utils/database/asDatabaseClientSsl
+import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t1] apply runs then: the config-backed client declares verified tls, and matches snapshot: src/utils/database/getSurfReportConnection.ts — after 1`] = `
+"import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+import { asDatabaseClientSsl } from '@src/utils/database/asDatabaseClientSsl';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+    ssl: asDatabaseClientSsl({ clusterEndpoint: config.database.tunnel.lambda?.host ?? null }),
+  });
+  await client.connect();
+  return client;
+};
+"
+`;

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/pg-client-without-ssl/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,32 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import {
+  isPgClientWithoutSsl,
+  withPgClientSslDeclared,
+} from '../../../../../../utils/withPgClientSslDeclared';
+
+/**
+ * .what = the retired factory files that `old-get-database-connection` declares by their own path
+ * .why = that bad-practice deletes them on a template match; were this wildcard to flag them too,
+ *        two fixes would race on one file (a rewrite turns a template match into a kept edit, or
+ *        a second unlink hits a file already gone), so the retired files are left to their owner
+ */
+const RETIRED_FILE_PATHS = [
+  'src/utils/database/getDatabaseConnection.ts',
+  'src/utils/database/getDatabaseConnection.integration.test.ts',
+];
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (
+    contents !== null &&
+    !RETIRED_FILE_PATHS.includes(context.relativeFilePath) &&
+    isPgClientWithoutSsl({ source: contents })
+  )
+    return; // bad practice detected
+  throw new Error('does not match bad practice: every pg Client declares ssl');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+  return { contents: withPgClientSslDeclared({ source: contents }) };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/.declapract.readme.md

@@ -0,0 +1 @@
+provision/schema/entities -> provision/schema/domain

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/provision/schema/entities/<star>.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (_, context) => {
+  return {
+    relativeFilePath: context.relativeFilePath.replace(
+      /provision\/schema\/entities\//g,
+      'provision/schema/domain/',
+    ),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/provision/schema/sql/entities.yml.declapract.ts

@@ -0,0 +1,13 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (_, context) => {
+  return {
+    // rename file to "domain.yml"
+    relativeFilePath: context.relativeFilePath.replace(
+      /entities\.yml$/,
+      'domain.yml',
+    ),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.declapract.integration.test.ts

@@ -0,0 +1,95 @@
+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 terraform-parameters forget, run through the REAL
+ *   declapract apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = the bad-practice fix must rewrite every `resource "aws_ssm_parameter"` into
+ *   a `removed{}` forget block (never a destroy), and drop the `data` seed-reads —
+ *   so terraform lets go of the params without loss of the live value. the
+ *   go-forward declastruct wish declares its own names separately; the OLD names
+ *   here are simply orphaned (forgotten from terraform, not adopted by declastruct).
+ * .note = the terraform file is snapshotted in full (before AND after) so a reviewer
+ *   can eyeball the exact end-state, per rule.require.declapract-integration-tests.
+ */
+// the practice-scoped apply evaluates the whole persist-with-rds practice; under suite load it can outlast the default
+jest.setTimeout(600_000);
+
+describe('terraform-parameters forget', () => {
+  given(
+    '[case1] a repo with terraform-managed ssm params',
+    () => {
+      const tempDir = genTempDir({
+        slug: 'declapract-terraform-parameters',
+        clone: './src/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm',
+        symlink: [{ at: 'declarations', to: 'src' }],
+      });
+
+      const tfPath = 'provision/aws/product/parameter-store.tf';
+      const read = (relativePath: string) =>
+        fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+      const applyForget = () =>
+        executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file: tfPath,
+        });
+
+      when('[t0] the migration input (before any fix)', () => {
+        then('the terraform input matches snapshot', async () => {
+          expect(await read(tfPath)).toMatchSnapshot(
+            'parameter-store.tf — before',
+          );
+        });
+      });
+
+      when('[t1] the bad-practice forget fix is applied', () => {
+        useThen('forget the terraform params', async () => applyForget());
+
+        then(
+          'the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot',
+          async () => {
+            const tf = await read(tfPath);
+            expect(tf).not.toContain('resource "aws_ssm_parameter"');
+            expect(tf).not.toContain('data "aws_ssm_parameter"');
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_database_role_crud_password',
+            );
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_twilio_authToken',
+            );
+            expect(tf).toContain('destroy = false');
+            // the admin forget names its two copy targets under the derived names (#686)
+            expect(tf).toContain(
+              '# copy this value before the first plan → /test-org/test-project/{config}/database.role.cicd.for-plan.password, /test-org/test-project/{config}/database.role.cicd.for-apply.password (see provision/aws/readme.md)\nremoved {\n  from = aws_ssm_parameter.secret_database_admin_password',
+            );
+            // full content, for the reviewer's eye
+            expect(tf).toMatchSnapshot('parameter-store.tf — after');
+          },
+        );
+      });
+
+      when('[t2] the forget fix is applied a second time (idempotency)', () => {
+        // capture the post-first-forget state, apply again, capture again — assert
+        // zero change. the forget regex must not re-match its own removed{} output
+        // (per rule.require.idempotent-fixes).
+        const passes = useThen(
+          'a second forget over its own output',
+          async () => {
+            const before = await read(tfPath); // post-first-forget
+            await applyForget(); // second apply
+            const after = await read(tfPath);
+            return { before, after };
+          },
+        );
+
+        then('the second forget is a no-op', () => {
+          expect(passes.after).toEqual(passes.before);
+        });
+      });
+    },
+  );
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.declare.yml

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

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.use.yml

@@ -0,0 +1,18 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: '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/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/package.json

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