declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/report-slow-tests.play.declapract.integration.test.ts

@@ -0,0 +1,161 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+/**
+ * .what = integration test for the report-slow-tests shell the .test.yml workflow shells out to.
+ * .why  = the prior inline report filtered on `perfStats.runtime`, a key jest 30 dropped — so it
+ *         matched zero rows and went silent-green for its whole life (radio #602). this clamps the
+ *         go-forward: it reads endTime-startTime, ranks by wall-clock, and — the whole point of the
+ *         fix — fails LOUD if a future schema change zeroes the durations again, never silent-green.
+ * .how  = spawn the shipped best-practice/.github/workflows/report-slow-tests.sh against fixture
+ *         jest-results.json files, with GITHUB_STEP_SUMMARY pointed at a temp file, and assert the
+ *         exit code, the summary table, and the stdout annotations.
+ * .note = subject is the SHIPPED shell template. this file sits at the PRACTICE ROOT (not under
+ *         best-practice/), so declapract's loader — which walks only best-practice/ for templates —
+ *         never reads it as a declaration and never copies it to a consumer. it is the play-test
+ *         counterpart to husky/check.timestamps.play.declapract.integration.test.ts.
+ */
+
+// the shell under test (the distributed best-practice template)
+const scriptPath = path.join(
+  __dirname,
+  'best-practice/.github/workflows/report-slow-tests.sh',
+);
+
+// write a fixture jest-results.json + a fresh summary sink into a temp dir; return their paths
+const genFixture = (
+  jestResults: unknown,
+): { resultsPath: string; summaryPath: string } => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'report-slow-tests-'));
+  const resultsPath = path.join(dir, 'jest-results.json');
+  const summaryPath = path.join(dir, 'step-summary.md');
+  fs.writeFileSync(resultsPath, JSON.stringify(jestResults));
+  fs.writeFileSync(summaryPath, '');
+  return { resultsPath, summaryPath };
+};
+
+// spawn the report against a fixture; return exit code + stdout + the summary file contents
+const runReport = (
+  jestResults: unknown,
+): { code: number | null; stdout: string; summary: string } => {
+  const { resultsPath, summaryPath } = genFixture(jestResults);
+  const res = spawnSync('bash', [scriptPath, resultsPath], {
+    encoding: 'utf-8',
+    env: { ...process.env, GITHUB_STEP_SUMMARY: summaryPath },
+  });
+  // mask the random fixture dir, so a snapshot neither churns per run nor holds a host path
+  const asMaskedFixtureDir = (text: string): string =>
+    text.split(path.dirname(resultsPath)).join('[fixture]');
+  return {
+    code: res.status,
+    stdout: asMaskedFixtureDir(res.stdout),
+    summary: asMaskedFixtureDir(fs.readFileSync(summaryPath, 'utf-8')),
+  };
+};
+
+describe('report-slow-tests', () => {
+  given('[case1] a report with a slow (>30s), a medium (>10s), and a fast file', () => {
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() =>
+        runReport({
+          testResults: [
+            { name: '/repo/src/medium.test.ts', startTime: 1000, endTime: 16000 }, // 15s
+            { name: '/repo/src/fast.test.ts', startTime: 1000, endTime: 3000 }, // 2s
+            { name: '/repo/src/slow.test.ts', startTime: 1000, endTime: 41000 }, // 40s
+          ],
+        }),
+      );
+
+      then('it exits 0', () => {
+        expect(result.code).toEqual(0);
+      });
+
+      then('the summary carries the ranked table', () => {
+        expect(result.summary).toContain('### slowest test files');
+        expect(result.summary).toContain('| duration | file |');
+      });
+
+      then('the slowest file is ranked first in the table', () => {
+        const slowIdx = result.summary.indexOf('/repo/src/slow.test.ts');
+        const mediumIdx = result.summary.indexOf('/repo/src/medium.test.ts');
+        const fastIdx = result.summary.indexOf('/repo/src/fast.test.ts');
+        expect(slowIdx).toBeGreaterThan(-1);
+        expect(slowIdx).toBeLessThan(mediumIdx);
+        expect(mediumIdx).toBeLessThan(fastIdx);
+      });
+
+      then('it emits a warn annotation for the >30s file', () => {
+        expect(result.stdout).toContain(
+          '::warning file=/repo/src/slow.test.ts::slow test: 40s',
+        );
+      });
+
+      then('it emits a notice annotation for the >10s file', () => {
+        expect(result.stdout).toContain(
+          '::notice file=/repo/src/medium.test.ts::test duration: 15s',
+        );
+      });
+
+      then('it emits no annotation for the fast file', () => {
+        expect(result.stdout).not.toContain('/repo/src/fast.test.ts::');
+      });
+
+      then('the summary and annotations match snapshot', () => {
+        expect(result.summary).toMatchSnapshot('step summary — ranked');
+        expect(result.stdout).toMatchSnapshot('stdout annotations — ranked');
+      });
+    });
+  });
+
+  given('[case2] a non-empty report whose durations are all zero (schema drift)', () => {
+    // the exact silent-death #602 fixed: testResults present, but no real duration to be read.
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() =>
+        runReport({
+          testResults: [
+            { name: '/repo/src/a.test.ts', startTime: 1000, endTime: 1000 },
+            { name: '/repo/src/b.test.ts', startTime: 2000, endTime: 2000 },
+          ],
+        }),
+      );
+
+      then('it fails loud with exit 1 (never silent-green)', () => {
+        expect(result.code).toEqual(1);
+      });
+
+      then('it prints an error annotation that names the schema drift', () => {
+        expect(result.stdout).toContain('::error::');
+        expect(result.stdout).toContain('jest --json duration schema');
+        expect(result.stdout).toContain('read endTime/startTime'); // names the next move
+        expect(result.stdout).not.toMatch(/#\d+/); // a bare issue ref dangles in a consumer repo
+      });
+
+      then('the error output matches snapshot', () => {
+        expect(result.stdout).toMatchSnapshot('stdout — schema drift');
+      });
+    });
+  });
+
+  given('[case3] an empty shard (0 test files)', () => {
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() => runReport({ testResults: [] }));
+
+      then('it exits 0 (an empty shard is legitimate)', () => {
+        expect(result.code).toEqual(0);
+      });
+
+      then('the summary states the empty-shard state explicitly', () => {
+        expect(result.summary).toContain('0 test files');
+        expect(result.summary).toContain('empty shard');
+      });
+
+      then('the summary matches snapshot', () => {
+        expect(result.summary).toMatchSnapshot('step summary — empty shard');
+      });
+    });
+  });
+});

package/dist/.test/assets/cicd-common/declarations/useCases.yml

@@ -0,0 +1,11 @@
+# minimal use case for the action-pin integration test
+#
+# .why = only `cicd-common` is carried. the claim under test is that declapract's
+#        default EQUALS path delivers a pinned workflow template to a consumer
+#        verbatim, and one practice that declares one workflow is the whole of it.
+#        a broader use case would slow every apply with declarations that have no
+#        bearing on the pin.
+use-cases:
+  typescript-project:
+    practices:
+      - cicd-common

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/.test/assets/repo-with-hand-patch/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = the test writes declarations/ into the temp clone (genDeclarationsOfPackageJsonOnly)
+# .why  = an rds repo that already holds its own exact-version pg-pool hand patch (vision case=2)
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/.test/assets/repo-with-hand-patch/package.json

@@ -0,0 +1,17 @@
+{
+  "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"
+    }
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/.test/assets/repo-with-hand-patch/patches/left-pad@1.3.0.patch

@@ -0,0 +1,6 @@
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -1,1 +1,1 @@
+-/* This program is free software. It comes without any warranty, to
++/* This program is free software. It comes without any warranty, to (hand patch)

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/.test/assets/repo-with-hand-patch/patches/pg-pool@3.14.0.patch

@@ -0,0 +1,12 @@
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -92,7 +92,7 @@ class Pool extends EventEmitter {
+     this.options.allowExitOnIdle = this.options.allowExitOnIdle || false
+     this.options.maxLifetimeSeconds = this.options.maxLifetimeSeconds || 0
+     this.log = this.options.log || function () {}
+-    this.Client = this.options.Client || Client || require('pg').Client
++    this.Client = this.options.Client || Client // hand patch
+     this.Promise = this.options.Promise || global.Promise
+
+     if (typeof this.options.idleTimeoutMillis === 'undefined') {

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/best-practice/.declapract.readme.md

@@ -21,6 +21,28 @@ we use:
 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
@@ -83,3 +105,10 @@ a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) doe
 `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/cicd-service/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/cicd-service/declarations/practices/persist-with-rds/best-practice/package.json

@@ -12,6 +12,11 @@
     "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
     "@types/pg": "@declapract{check.minVersion('8.6.1')}"
   },
+  "pnpm": {
+    "patchedDependencies": {
+      "pg-pool": "patches/pg-pool.patch"
+    }
+  },
   "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",

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/patches/pg-pool.patch

@@ -0,0 +1,21 @@
+.what = drops pg-pool's lazy `require('pg')` fallback, so dpdm sees no pg <-> pg-pool require cycle
+.why  = pg passes its own Client into every pool it builds, so the fallback never runs under pg; but
+        dpdm reads it statically, and `test:lint:cycles` checks node_modules (exclude: []) by policy
+.note = shipped by declapract-typescript-ehmpathy, practice persist-with-rds. if pnpm warns that this
+        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: an exact key
+        outranks this bare one. code that calls `new Pool()` from pg-pool directly must pass
+        `{ Client: require('pg').Client }`. after an apply, run `pnpm install` and commit the
+        lockfile: it records this file's hash.
+.recut = keep one context line on each side of the changed line. wider context misfits older
+        pg-pool releases, and pnpm then warns and installs pg-pool unpatched. edit this file only
+        when the hunk must move: its hash sits in every adopter's lockfile, header included.
+
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -94,3 +94,3 @@ class Pool extends EventEmitter {
+     this.log = this.options.log || function () {}
+-    this.Client = this.options.Client || Client || require('pg').Client
++    this.Client = this.options.Client || Client
+     this.Promise = this.options.Promise || global.Promise