declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/provision/aws/product/parameter-store.tf

@@ -0,0 +1,32 @@
+data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_admin_password" {
+  name  = "${local.parameter_store_namespace}.database.admin.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}

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

@@ -0,0 +1,60 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t0] the migration input (before any fix) then: the terraform input matches snapshot: parameter-store.tf — before 1`] = `
+"data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "\${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_admin_password" {
+  name  = "\${local.parameter_store_namespace}.database.admin.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "\${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "\${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+"
+`;
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t1] the bad-practice forget fix is applied then: the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot: parameter-store.tf — after 1`] = `
+"# 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)
+removed {
+  from = aws_ssm_parameter.secret_database_admin_password
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+removed {
+  from = aws_ssm_parameter.secret_database_role_crud_password
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+removed {
+  from = aws_ssm_parameter.secret_twilio_authToken
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+"
+`;

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/provision/aws/product/parameter-store.tf.declapract.ts

@@ -0,0 +1,94 @@
+import { type FileCheckFunction, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = terraform must not manage ssm parameters — they belong to declastruct-aws
+ *   now (provision/aws/resources.parameters.ts).
+ * .why = terraform managed these via the `__IGNORED__` + `ignore_changes = [value]`
+ *   workaround, which hid drift and forced the secret through terraform state. the
+ *   real values live ONLY in aws (seeded once), so a plain resource-block delete
+ *   would issue DeleteParameter = permanent loss. the fix instead rewrites each
+ *   `resource "aws_ssm_parameter"` into a `removed{}` forget block (`destroy = false`)
+ *   — terraform drops it from state and preserves the live value. requires terraform
+ *   >= 1.7 for the `removed{}` block.
+ *
+ * .pair = this bad-practice removes terraform's ownership; the best-practice
+ *   provision/aws/resources.parameters.ts declares the declastruct owner (value-less
+ *   write-only KEEP — it adopts the live values terraform seeded). declare the wish
+ *   BEFORE this forget lands so declastruct owns every param first.
+ */
+
+// bad practice detected while terraform still declares an ssm parameter resource.
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('resource "aws_ssm_parameter"')) return; // detected
+  throw new Error(
+    'no terraform-managed ssm parameter resources; not the terraform-parameters bad practice',
+  );
+};
+
+/**
+ * .what = the derived ssm names a legacy role param's value seeds, or [] for any other param
+ * .why = the role rename (admin → cicd for-plan + for-apply, service → crud) moved the values to
+ *        new names; the forget erases the last terraform trace of the old one, so its comment
+ *        names where the value must be copied (#686). a fix holds no aws access, so the copy
+ *        itself is a human step (provision/aws/readme.md).
+ */
+const getAllCopyTargetsForLabel = (input: {
+  label: string;
+  namespace: string;
+}): string[] => {
+  if (/(^|_)admin(_|$)/.test(input.label))
+    return [
+      `${input.namespace}/database.role.cicd.for-plan.password`,
+      `${input.namespace}/database.role.cicd.for-apply.password`,
+    ];
+  if (/(^|_)service(_|$)/.test(input.label))
+    return [`${input.namespace}/database.role.crud.password`];
+  return [];
+};
+
+/**
+ * .what = cast copy targets into the comment line above a forget block ([] when none)
+ */
+const asCopyNoteLines = (input: { targets: string[] }): string[] =>
+  input.targets.length
+    ? [
+        `# copy this value before the first plan → ${input.targets.join(', ')} (see provision/aws/readme.md)`,
+      ]
+    : [];
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return {};
+
+  // the derived namespace each copy target sits under; the config segment differs per env, so it stays `{config}`
+  const org = context?.projectVariables?.organizationName ?? '{org}';
+  const project = context?.projectVariables?.projectName ?? '{project}';
+  const namespace = `/${org}/${project}/{config}`;
+
+  // drop the `data "aws_ssm_parameter"` reads — they existed only to seed values
+  // that declastruct-aws now owns.
+  const withoutDataReads = contents.replace(
+    /data\s+"aws_ssm_parameter"\s+"\w+"\s*\{[\s\S]*?\n\}\n?/g,
+    '',
+  );
+
+  // rewrite each `resource "aws_ssm_parameter" "<label>" { ... }` into a forget
+  // block. `[\s\S]*?\n\}` stops at the first column-0 `}` (the block close); the
+  // indented `  }` of a nested lifecycle block never matches, so the nest is safe.
+  const withForgetBlocks = withoutDataReads.replace(
+    /resource\s+"aws_ssm_parameter"\s+"(\w+)"\s*\{[\s\S]*?\n\}/g,
+    (_match, label: string) =>
+      [
+        ...asCopyNoteLines({
+          targets: getAllCopyTargetsForLabel({ label, namespace }),
+        }),
+        `removed {`,
+        `  from = aws_ssm_parameter.${label}`,
+        `  lifecycle {`,
+        `    destroy = false # forget from state; keep the live param`,
+        `  }`,
+        `}`,
+      ].join('\n'),
+  );
+
+  return { contents: withForgetBlocks };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.declapract.readme.md

@@ -0,0 +1,10 @@
+withDatabaseConnection -> withDatabaseContext, per procedure-fns pattern
+
+`withDatabaseConnection` took `dbConnection` in the input. `withDatabaseContext`
+(`src/utils/database/withDatabaseContext.ts`, shipped by the best-practice) takes it in the context:
+each op becomes `(input, context) => …`, and each caller passes the context as the 2nd arg.
+
+the move changes each op and each caller, so the fix does not rewrite code. it stamps a
+`// @declapract:review:` line above each import or definition of `withDatabaseConnection` that names
+the move, and leaves the extant wrapper in place so the tree still builds. delete the marker, and
+then the wrapper, once its last caller moves.

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/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/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/domain.operations/findSurferById.ts

@@ -0,0 +1,9 @@
+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 } }),
+);

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/utils/database/withDatabaseConnection.ts

@@ -0,0 +1,10 @@
+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);
+  };

package/dist/.test/assets/git/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,55 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asInputToContextReviewMarker } from '../../../../../../utils/asInputToContextReviewMarker';
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = a line that imports, re-exports, or defines the retired `withDatabaseConnection`.
+ * .why  = a multi-line import names the module only on its `from` line, so the module path is
+ *         matched too; one marker per import statement either way.
+ */
+const WITH_DATABASE_CONNECTION_LINE_PATTERN =
+  /(?:^\s*import\b[^\n]*\bwithDatabaseConnection\b|^\s*export\s+(?:const|function)\s+withDatabaseConnection\b|\bfrom\s+['"][^'"]*\/withDatabaseConnection['"])/;
+
+const REVIEW_MARKER = asInputToContextReviewMarker({
+  from: 'withDatabaseConnection (dbConnection in the input)',
+  into: 'withDatabaseContext (src/utils/database/withDatabaseContext.ts)',
+});
+
+/**
+ * .what = flags a src file that imports or defines `withDatabaseConnection`.
+ * .why  = the practice replaced it with `withDatabaseContext`; the prior declaration was an EXISTS
+ *         check with no fix, so an apply failed with no pointer to the replacement and each call
+ *         site broke the build (#626). this check names each file by path in `plan`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents
+      ?.split('\n')
+      .some((line) => WITH_DATABASE_CONNECTION_LINE_PATTERN.test(line))
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no import or definition of withDatabaseConnection',
+  );
+};
+
+/**
+ * .what = stamps the shared input→context review line above each such import or definition.
+ * .why  = each op moves `dbConnection` from its input into a context arg, and each caller passes
+ *         it as the 2nd arg — a shape change a regex cannot make safely — so the fix names the
+ *         move beside the line, and never deletes the extant wrapper (its callers still need it).
+ * .note = idempotent; the check stays red until a human moves the ops, so `plan` keeps it in view.
+ * .note = an absent file is left absent: every fix must settle on absent input, a contract the
+ *         repo-wide fix-coverage sweep holds (`practiceFixCoverage`, #607)
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: WITH_DATABASE_CONNECTION_LINE_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/.declapract.readme.md

@@ -0,0 +1,114 @@
+we use:
+- postgres database
+  - provisioned by aws rds aurora when in prep and prod env
+  - provisioned by docker when in test env
+- sql-schema-control to manage sql schema
+- sql-dao-generator to generate the sql-schemas + daos
+
+## required variables
+
+| variable | description | example |
+|----------|-------------|---------|
+| `databaseTunnelHost.{prep,prod}` | ssm proxy host for database tunnel | `aws.ssmproxy.ahbodedb.prep` |
+| `databaseClusterHost.{prep,prod}` | rds cluster endpoint | `ahbodedb.cluster-xxx.us-east-1.rds.amazonaws.com` |
+
+## optional variables
+
+| variable | description | default |
+|----------|-------------|---------|
+| `databaseClusterName` (or `databaseClusterName.{prep,prod}`) | the rds cluster the vpc tunnel targets (`database.tunnel.cluster.name`) | the first label of `databaseClusterHost.{env}` |
+
+set it only when the cluster endpoint is a custom dns alias whose first label is not the
+cluster identifier. a hand-set `database.tunnel.cluster.name` in a repo's own config is kept.
+
+## the pg-pool patch
+
+pg-pool's pool falls back to `require('pg').Client` when no `Client` is passed. dpdm reads that
+require statically, so every repo with pg + pg-pool fails `test:lint:cycles` on `pg <-> pg-pool`
+(the check reads node_modules too, by policy). this practice ships
+`patches/pg-pool.patch`, which drops the fallback, under the bare-name key
+`pnpm.patchedDependencies["pg-pool"]`:
+
+- the bare name never goes stale, so the stale-patch check never retires it; the hunk fits every
+  stable pg-pool release in `^3.2.1`, which `pg@8.3.0` asks for
+- a repo's own exact-version key (`pg-pool@<version>`) outranks it at install, and both survive the apply.
+  a hand patch of the same line may be deleted, key and file
+- after an apply, run `pnpm install` and commit the lockfile: it records the patch hash, so a ci
+  `--frozen-lockfile` install fails until it does
+- pg passes its own `Client` into every pool it builds, so code that goes through `pg` sees no change.
+  code that calls `new Pool()` from pg-pool directly must pass `{ Client: require('pg').Client }`
+- if pnpm warns that the patch failed to apply, pg-pool moved the line: upgrade
+  declapract-typescript-ehmpathy and re-apply. if no fix has shipped yet, pin your own
+  `pg-pool@<version>` patch; its exact key outranks the bare one
+- to recut the hunk, keep one context line on each side of the changed line. wider context misfits
+  older releases in `^3.2.1` (3.2.1–3.4.1), and pnpm then installs pg-pool unpatched
+
+## ssm parameters
+
+the provision wish (`provision/aws/resources.parameters.ts`) declares the db credentials at the
+names sdk-config derives for a bare `$.at(aws::param)`:
+
+| parameter name | description | environments |
+|----------------|-------------|--------------|
+| `/{org}/{project}/{config}/database.role.cicd.for-plan.password` | password for the cicd plan user | prep, prod |
+| `/{org}/{project}/{config}/database.role.cicd.for-apply.password` | password for the cicd apply user | prep, prod |
+| `/{org}/{project}/{config}/database.role.crud.password` | password for the crud user | prep, prod |
+
+a repo whose values sit at a prior name (or under `role.admin` / `role.service`) copies them to
+these names before its first provision apply — the map is in `provision/aws/readme.md`.
+
+prep users are created with the `__CHANG3_ME__` password by `provision/schema/deploy.database.sh`,
+so `config/prep.json` accepts either `__CHANG3_ME__` or `$.at(aws::param)` at each password.
+
+## config grants
+
+`src/utils/config/config.schema.ts` exports one schema per oidc grant:
+
+- `apply` (the default: the apply job, the cloud runtime, local dev, tests) requires every secret,
+  so `Config` carries no `| undefined` and consumers need no guards
+- `plan` marks `role.cicd.for-apply.password` and `role.crud.password` optional. the prod plan
+  job's oidc role may read only the for-plan credential, and sdk-config substitutes `undefined`
+  for each param a role is denied
+- `for-plan` and `for-apply` each carry a username, since a plan job may map to a readonly db user
+
+the grant is an argument, never read inside the schema; `getConfig` picks the schema at call time
+(see the `config` practice readme).
+
+## a stateful store gets an alias, never a copy, across the dual-publish transition
+
+the `serverless` + `environments` practices dual-publish each lambda fleet under both slugs
+(`-dev-` ancient, `-prep-` contemp) through the `-dev-`→`-prep-` slug transition. a stateless lambda
+is safe under two names. a stateful store is not.
+
+this RDS cluster (and its SSM credential params, its S3 buckets, its SQS queues) stays one store
+reached by two pointers — a Route53 CNAME, an SSM pointer, or an ARN — never two clusters.
+
+a second `-prep-` RDS cluster is never stood up to satisfy dual-publish. two independent clusters
+form a write-`-dev-`/read-`-prep-` split: the ancient fleet writes one, the contemp fleet reads the
+other, and the divergence stays silent until data is absent. the alias points at the one cluster.
+
+no data migration is needed: the runtime DB path resolves `config.database.tunnel.lambda.host` (see
+`src/utils/database/getOneDatabaseConnection.ts`), an access-keyed config value
+(`databaseClusterHost.{prep,prod}`) with no deploy-slug token, so a CNAME re-points the one live
+cluster with zero data moved. which alias mechanism to use is unsettled; the invariant "one store, two
+pointers" holds regardless.
+
+## the provision workflow's rds jobs are gated behind this practice (D28)
+
+`cicd-service`'s `provision.yml` carries 4 rds-coupled jobs — `sql-schema-{prep,prod}` (the
+`.sql-schema-control.yml` callee, driven by this practice's schema + daos) and
+`aws-{prep,prod}-declastruct` (the `provision/aws/resources.ts` wish this practice ships). the gate
+lives in `cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts`: a usecase-aware
+`contents` fn emits those 4 jobs **only** when `persist-with-rds` is in the resolved practice set, so
+a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) does not inherit a
+`provision` workflow that references files it lacks. it uses `CONTAINS`, not `EQUALS`, so a narrow
+`declapract apply --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
+EQUALS hazard). if you add a new rds-coupled provision job, add it to that gate the same way — a
+caller that names a callee this practice supplies must be reconciled against this practice's presence.
+
+## the dao-generator output folds in a pr
+
+this practice declares a `# [persist-with-rds]` section of the repo-root `.gitattributes`: it marks
+`src/access/daos/**/.generated/**` and `provision/schema/**/.generated/**` as
+`linguist-generated`, so github renders them collapsed. the daos and the schemas themselves stay
+open: they are the internal contracts, so a reviewer reads them. to un-fold a path, see "what folds in a pr" in `src/practices/git/best-practice/.declapract.readme.md`.

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/.gitattributes.declapract.ts

@@ -0,0 +1,64 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
+
+/**
+ * .what = the `.gitattributes` section this practice owns: `.generated/` dirs fold in pr diffs
+ * .why  = the daos and the schemas are the internal contracts, so a reviewer reads them open.
+ *         a `.generated/` dir holds derived code (casts, query types, query functions) that
+ *         every regen rewrites. github folds a file marked `linguist-generated`, one click away
+ * .note = `codegen.sql.types.yml` and the dao generator write `src/access/daos/.generated/`.
+ *         the `**` keeps a nested `.generated/` folded too, under the daos and the schemas
+ *         alike; every other dao and schema file stays open
+ */
+const sections: readonly GitattributesSection[] = [
+  {
+    header: {
+      latest: '# [persist-with-rds] collapse dao-generator output in pr diffs',
+      retired: [],
+    },
+    entries: {
+      latest: [
+        'src/access/daos/**/.generated/** linguist-generated',
+        'provision/schema/**/.generated/** linguist-generated',
+      ],
+      retired: [
+        'src/access/daos/** linguist-generated',
+        'provision/schema/sql/tables/** linguist-generated',
+        'provision/schema/sql/views/** linguist-generated',
+        'provision/schema/sql/functions/** linguist-generated',
+      ],
+    },
+  },
+];
+
+/**
+ * .what = emits the `.gitattributes` this practice declares, given the repo's extant one
+ * .why  = several practices declare this file; they converge only through the shared util
+ */
+const defineExpectedContents = (input: { contents: string | null }): string =>
+  defineExpectedGitattributesContents({
+    contents: input.contents,
+    declarer: 'persist-with-rds',
+    sections,
+  });
+
+/**
+ * .what = throws when the repo's `.gitattributes` differs from what the shared layout emits
+ * .why  = `check` gates `fix` (a throw means violated); exact equality, so `check(x) ⟺ x === fix(x)`
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents({ contents }));
+};
+
+/**
+ * .what = sets this practice's section into the repo's `.gitattributes`
+ * .why  = a fixed point: a second fix changes zero, and `check` passes on the output
+ */
+export const fix: FileFixFunction = (contents) => ({
+  contents: defineExpectedContents({ contents }),
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/codegen.sql.dao.yml

@@ -0,0 +1,18 @@
+language: postgres
+dialect: 17
+generates:
+  daos:
+    to: src/access/daos
+    using:
+      log: src/utils/logger#log
+      DatabaseConnection: src/utils/database/getOneDatabaseConnection#DatabaseConnection
+  schema:
+    config: codegen.sql.schema.yml
+  control:
+    config: provision/schema/control.yml
+  code:
+    config: codegen.sql.types.yml
+for:
+  objects:
+    search:
+      - 'src/domain.objects/*.ts'

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/codegen.sql.dao.yml.declapract.ts

@@ -0,0 +1,35 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // contains since the user may have exclusions in that "for" object
+
+const DIALECT_LINE = /^dialect: .*$/m;
+const LANGUAGE_LINE = /^language: .*$/m;
+
+/**
+ * .what = moves the found config onto the declared `dialect` line, and keeps every other line
+ * .why = a CONTAINS check has no default fix for a file that exists, so a repo on a stale dialect
+ *        (10.7, eight majors behind) could never converge on its own (#664)
+ * .note = a second pass finds the declared line already in place, so it changes naught
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // write the declared config where none exists
+  const declared = context.declaredFileContents!;
+  if (!contents) return { contents: declared };
+
+  // swap the found dialect line for the declared one
+  const dialectDeclared = declared.match(DIALECT_LINE)?.[0];
+  if (!dialectDeclared) return { contents };
+  if (DIALECT_LINE.test(contents))
+    return { contents: contents.replace(DIALECT_LINE, dialectDeclared) };
+
+  // or add it under the language line, where the template declares it
+  const languageFound = contents.match(LANGUAGE_LINE)?.[0];
+  if (languageFound)
+    return {
+      contents: contents.replace(
+        LANGUAGE_LINE,
+        `${languageFound}\n${dialectDeclared}`,
+      ),
+    };
+  return { contents: `${dialectDeclared}\n${contents}` };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/codegen.sql.schema.yml

@@ -0,0 +1,6 @@
+language: postgres
+dialect: 17
+declarations: provision/schema/domain/index.ts
+generates:
+  sql:
+    to: provision/schema/sql

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/codegen.sql.types.yml

@@ -0,0 +1,16 @@
+language: postgres
+dialect: 17
+resources: # where to find your tables, functions, views, procedures
+  - 'provision/schema/sql/tables/**/*.sql'
+  - 'provision/schema/sql/views/**/*.sql'
+  - 'provision/schema/sql/functions/**/*.sql'
+queries: # where to find your queries (each file must `export const query = `...`);
+  - 'src/access/daos/**/*.ts'
+  - '!src/access/daos/**/index.ts'
+  - '!src/access/daos/**/castFromDatabaseObject.ts'
+  - '!src/access/daos/**/findByRef.ts'
+  - '!src/**/*.test.ts'
+  - '!src/**/*.test.integration.ts'
+generates: # where to output the generated code
+  types: src/access/daos/.generated/types.ts
+  queryFunctions: src/access/daos/.generated/queryFunctions.ts

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/config/prep.json

@@ -0,0 +1,40 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "$.at(aws::param)"
+      }
+    },
+    "tunnel": {
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.prep}",
+        "port": 15432
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.prep}",
+        "port": 5432
+      }
+    }
+  }
+}

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/config/prep.json.declapract.ts

@@ -0,0 +1,11 @@
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
+
+/**
+ * .what = the contents, check, and fix that deep-merge the rds keys into config/prep.json.
+ * .why  = a deep merge adds the absent rds keys and keeps the leaves a repo holds on purpose, so an
+ *         apply never clobbers a value a service tuned (#638, #683); see genRdsConfigDeclaration.
+ */
+export const { contents, check, fix } = genRdsConfigDeclaration({
+  env: 'prep',
+  templatePath: `${__dirname}/prep.json`,
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/config/prod.json

@@ -0,0 +1,40 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "$.at(aws::param)"
+      }
+    },
+    "tunnel": {
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.prod}",
+        "port": 15433
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.prod}",
+        "port": 5432
+      }
+    }
+  }
+}

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/config/prod.json.declapract.ts

@@ -0,0 +1,11 @@
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
+
+/**
+ * .what = the contents, check, and fix that deep-merge the rds keys into config/prod.json.
+ * .why  = a deep merge adds the absent rds keys and keeps the leaves a repo holds on purpose, so an
+ *         apply never clobbers a value a service tuned (#638); see genRdsConfigDeclaration.
+ */
+export const { contents, check, fix } = genRdsConfigDeclaration({
+  env: 'prod',
+  templatePath: `${__dirname}/prod.json`,
+});