declapract-typescript-ehmpathy 0.49.15 → 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/best-practice/.declapract.readme.md

@@ -105,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/expo-fullusecase/declarations/practices/cicd-common/.declapract.integration.test.ts

@@ -2,7 +2,9 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
-import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
+import { given, then, useBeforeAll, useThen, when } from 'test-fns';
+
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
 
 // executeApply is slow (full practice evaluation before the file filter narrows it)
 // .note = this suite scopes each apply with `file: '.github/workflows/review.yml'`, which
@@ -76,14 +78,12 @@ const getAllActionRefLines = (input: { contents: string }): string[] =>
  */
 describe('cicd-common workflow templates', () => {
   given('[case1] a consumer repo whose workflow still carries a tag ref', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cicd-common-action-pins',
       clone:
         './src/practices/cicd-common/.test/assets/repo-with-unpinned-workflow',
-      symlink: [
-        { at: 'declarations', to: './.test/assets/cicd-common/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cicd-common/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     when('[t0] before any apply', () => {
@@ -237,14 +237,12 @@ describe('cicd-common workflow templates', () => {
    *         case runs the real pipeline, so an empty delivery goes red on byte-equality
    */
   given('[case2] a consumer whose .test.yml is stale, on the custom-fix path', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cicd-common-action-pins-test-yml',
       clone:
         './src/practices/cicd-common/.test/assets/repo-with-unpinned-workflow',
-      symlink: [
-        { at: 'declarations', to: './.test/assets/cicd-common/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cicd-common/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     when('[t0] before any apply', () => {
@@ -419,14 +417,12 @@ describe('cicd-common workflow templates', () => {
    *         claim to mean what it says
    */
   given('[case3] a consumer repo that also has a workflow of its OWN', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cicd-common-consumer-owned',
       clone:
         './src/practices/cicd-common/.test/assets/repo-with-unpinned-workflow',
-      symlink: [
-        { at: 'declarations', to: './.test/assets/cicd-common/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cicd-common/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     when('[t0] the whole practice is applied, unscoped', () => {
@@ -532,14 +528,12 @@ describe('cicd-common workflow templates', () => {
    *         could drift from the first and quietly cease to be the same repo
    */
   given('[case4] a consumer repo where the declared workflow is ABSENT', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cicd-common-absent-workflow',
       clone:
         './src/practices/cicd-common/.test/assets/repo-with-unpinned-workflow',
-      symlink: [
-        { at: 'declarations', to: './.test/assets/cicd-common/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cicd-common/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     when('[t0] before any apply, with the workflow removed', () => {

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/.declapract.integration.test.ts

@@ -152,7 +152,7 @@ describe('gitignore practices', () => {
       slug: 'git-cache-dirs',
       clone: './src/practices/git/.test/assets/repo-without-cache-ignores',
       symlink: [
-        { at: 'declarations', to: './.test/assets/git/declarations' },
+        { at: 'declarations', to: './src/.test/assets/git/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -602,7 +602,7 @@ describe('gitignore practices', () => {
       slug: 'git-rhachet-only',
       clone: './src/practices/git/.test/assets/repo-with-rhachet-only',
       symlink: [
-        { at: 'declarations', to: './.test/assets/git/declarations' },
+        { at: 'declarations', to: './src/.test/assets/git/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/.gitattributes.declapract.integration.test.ts

@@ -4,9 +4,24 @@ import path from 'node:path';
 import { executeApply } from 'declapract';
 import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
 
-// executeApply evaluates the whole git practice before the `file` filter narrows it
+import { check as checkGit } from './best-practice/.gitattributes.declapract';
+
+// executeApply evaluates the whole practice before the `file` filter narrows it
 jest.setTimeout(5 * 60 * 1000);
 
+const context = {} as Parameters<typeof checkGit>[1]; // .note = the check reads no context
+
+// .note = a literal, independent of the declaration: the check is `x === fix(x)`, so it passes on
+//         any fixed point and cannot by itself prove the bytes are the ones the practice promises
+const MANAGED_SECTIONS = `# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
+pnpm-lock.yaml -diff
+package-lock.json -diff
+
+# [git] auto-resolve lock file conflicts by taking theirs; run install after merge
+pnpm-lock.yaml merge=theirs
+package-lock.json merge=theirs
+`;
+
 const MANAGED_ENTRIES = [
   'pnpm-lock.yaml -diff',
   'package-lock.json -diff',
@@ -15,15 +30,13 @@ const MANAGED_ENTRIES = [
 ];
 
 /**
- * .what = proves the .gitattributes fix through the real declapract pipeline
- * .why  = the unit suite proves the fix in isolation; only executeApply proves the declared path
- *         reaches the repo-root file, the CONTAINS check gates the fix, and the settled file
- *         satisfies that check — so a rerun is a no-op and the plan stops to flag it
+ * .what = proves the git `.gitattributes` declaration through the real declapract pipeline
+ * .why  = the unit suite proves the fix in isolation; only executeApply proves the declared
+ *         path reaches the repo-root file, the check gates the fix, and the settled file
+ *         satisfies the check — so a rerun is a no-op and the plan stops to flag it
  *         (rule.require.declapract-integration-tests, rule.require.idempotent-fixes)
- * .teeth = emit any section's entries out of declared order, and [t1] `contains the template`
- *          reddens while [t2] stays a byte-identical fixed point — the reflag loop a fixed-point
- *          test alone cannot see. the prior fix (sections re-assembled in place, a stray entry
- *          left outside its section) was in exactly that state
+ * .note = all five declarers together, and this repo's own file, are proven in
+ *         `src/gitattributesDeclarers.declapract.integration.test.ts`
  */
 describe('git .gitattributes', () => {
   given('[case1] a repo whose .gitattributes holds a legacy header, a legacy entry, and an out-of-section entry', () => {
@@ -31,7 +44,7 @@ describe('git .gitattributes', () => {
       slug: 'git-gitattributes-legacy',
       clone: './src/practices/git/.test/assets/repo-with-legacy-gitattributes',
       symlink: [
-        { at: 'declarations', to: './.test/assets/git/declarations' },
+        { at: 'declarations', to: './src/.test/assets/git/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -53,15 +66,15 @@ describe('git .gitattributes', () => {
     when('[t1] apply runs', () => {
       const scene = useThen('apply settles', async () => {
         await apply();
-        const template = await fs.readFile(
-          path.join(__dirname, 'best-practice/.gitattributes'),
-          'utf-8',
-        );
-        return { after: await read(), template };
+        return { after: await read() };
+      });
+
+      then('the git check passes on the file', () => {
+        expect(() => checkGit(scene.after, context)).not.toThrow();
       });
 
-      then('the file contains the template verbatim — the CONTAINS check passes', () => {
-        expect(scene.after).toContain(scene.template.trim());
+      then('the file holds the managed sections verbatim, then the repo-own line', () => {
+        expect(scene.after).toEqual(`${MANAGED_SECTIONS}\n*.png binary\n`);
       });
 
       then('the legacy header and the legacy entry are gone', () => {
@@ -77,8 +90,10 @@ describe('git .gitattributes', () => {
         );
       });
 
-      then('the repo-own line survives', () => {
-        expect(scene.after).toContain('*.png binary');
+      then('the repo-own line survives, after the managed sections', () => {
+        expect(scene.after.trim().split('\n').slice(-1)[0]).toEqual(
+          '*.png binary',
+        );
       });
 
       then('no declapract template syntax leaked', () => {

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/.test/assets/repo-with-legacy-gitattributes/declapract.use.yml

@@ -1,7 +1,7 @@
-# .note = declarations dir is symlinked by the test to .test/assets/git/declarations
+# .note = declarations dir is symlinked by the test to src/.test/assets/git/declarations
 # .why  = a repo whose .gitattributes predates the current template: a legacy header, a legacy
-#         entry, and a managed entry outside any section — so the CONTAINS check fails and the
-#         git practice's fix runs
+#         entry, and a managed entry outside any section — so the check fails and the git
+#         practice's fix runs
 # .note = NO `variables:` block — `git` and `rhachet` reference zero `@declapract{variable.*}`
 declarations: 'declarations/declapract.declare.yml'
 useCase: typescript-project

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/__snapshots__/.gitattributes.declapract.integration.test.ts.snap

@@ -11,14 +11,14 @@ pnpm-lock.yaml merge=theirs
 `;
 
 exports[`git .gitattributes given: [case1] a repo whose .gitattributes holds a legacy header, a legacy entry, and an out-of-section entry when: [t1] apply runs then: the output matches snapshot: .gitattributes — after 1`] = `
-"*.png binary
-
-# exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
+"# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
 pnpm-lock.yaml -diff
 package-lock.json -diff
 
-# auto-resolve lock file conflicts by taking theirs; run install after merge
+# [git] auto-resolve lock file conflicts by taking theirs; run install after merge
 pnpm-lock.yaml merge=theirs
 package-lock.json merge=theirs
+
+*.png binary
 "
 `;

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/best-practice/.declapract.readme.md

@@ -5,6 +5,43 @@ ordered tail, what a new declarer owes — is stated once at
 `.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitignore.md`. read that before you add
 a line here.
 
+📖 several practices declare the `.gitattributes` too, and there order carries load. their shared
+contract — the canonical layout, the declarer tag, what a new declarer owes — is stated once at
+`.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitattributes.md`.
+
+## what folds in a pr, and how to un-fold a path
+
+a repo that adopts these practices gets `linguist-generated` lines, so github renders robocode
+collapsed in a pr. each stays one click away.
+
+| folds | declared by |
+|-------|-------------|
+| `*.test.ts`, `*.test.tsx` | `tests-any` |
+| `src/access/daos/**/.generated/**`, `provision/schema/**/.generated/**` | `persist-with-rds` |
+| `src/access/daos/**/.generated/**` | `persist-with-dynamodb` |
+| `.route/**`, `.behavior/**`, except `*.yield.*` and `.radio/**` | `rhachet` |
+
+snapshots (`*.snap`) stay open: no line names them. the daos and the schemas stay open too: they
+are the internal contracts. only the `.generated/` dirs within them fold.
+
+to un-fold a path, add a line at the bottom of `.gitattributes`, below every `# [<declarer>]`
+section and apart from them by a blank line:
+
+```
+src/access/daos/.generated/** -linguist-generated
+```
+
+the repo's own lines always sit last, and git takes the last line that matches, so this line wins.
+
+- a dir-level line un-folds every file under it, test files included, since it outranks the
+  `tests-any` line too
+- one file un-folds with a line of its own:
+  `src/access/daos/.generated/queryFunctions.ts -linguist-generated`
+- leave your own lines untagged. a `# [<word>]` header marks a managed block: it floats above the
+  repo-own lines, and one that names a declarer is rewritten by that declarer's fix
+
+a folded file may also drop out of github code search, which skips generated files.
+
 ## `.agent/.cache/` is declared here and by the rhachet practice
 
 deliberate, and neither is redundant. rhachet owns the dir in the causal sense — it creates it —