declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/useCases.yml

@@ -0,0 +1,29 @@
+# minimal use case for the gitignore integration test
+#
+# .why = BOTH practices declare the repo-root `.gitignore`. that contention is what
+#        this fixture exists to observe, so the use case must carry both -- exactly
+#        as `typescript-project` does in the real src/useCases.yml.
+use-cases:
+  typescript-project:
+    practices:
+      - git
+      - rhachet
+
+  # .why = the case that motivates the rhachet declaration at all: a repo which takes
+  #        `rhachet` WITHOUT `git` still writes `.agent/.cache/`, so it must still get
+  #        the ignore for it. no real use-case does this today -- which is exactly why
+  #        it needs a test. the gap is latent, so prod cannot reveal it.
+  rhachet-only:
+    practices:
+      - rhachet
+
+  # .why = five practices declare the repo-root `.gitattributes`, and git takes the LAST line
+  #        that matches, so their contention is order-sensitive. no real use-case carries all
+  #        five (rds and dynamodb sit apart), which is why this one does: it is the worst case
+  gitattributes-all-declarers:
+    practices:
+      - git
+      - tests-any
+      - rhachet
+      - persist-with-rds
+      - persist-with-dynamodb

package/dist/.test/assets/{expo-fullusecase/declarations/practices/git/best-practice → git/repo-with-all-gitattributes-declarers}/.gitattributes

@@ -1,3 +1,6 @@
+*.png binary
+src/access/daos/custom/** -linguist-generated
+
 # exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
 pnpm-lock.yaml -diff
 package-lock.json -diff

package/dist/.test/assets/git/repo-with-all-gitattributes-declarers/declapract.use.yml

@@ -0,0 +1,26 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/git/declarations
+# .why  = a repo that adopts all five `.gitattributes` declarers, from a file that predates
+#         them: the untagged git template, a repo-own binary line, and a repo-own override
+#         that must outrank the dao collapse
+# .note = the persist practices reference `@declapract{variable.*}` in other files; the whole
+#         practice evaluates before the `file` filter narrows it, so each variable is supplied
+declarations: 'declarations/declapract.declare.yml'
+useCase: gitattributes-all-declarers
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  infrastructureNamespaceId: 'testns'
+  databaseName: 'testdb'
+  slackWebhookUrl: 'https://hooks.slack.test/webhook'
+  databaseUserName:
+    cicdUser: 'cicd_user'
+    serviceUser: 'service_user'
+  databaseTunnelHost:
+    prep: 'tunnel.prep.example.com'
+    prod: 'tunnel.prod.example.com'
+  databaseClusterHost:
+    prep: 'cluster.prep.example.com'
+    prod: 'cluster.prod.example.com'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/.test/assets/git/repo-with-all-gitattributes-declarers/package.json

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

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/pnpm/declarations
+# .why  = a repo with one patch the lockfile moved past and one it still resolves (#680)
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "repo-stale-patch-beside-bare",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy": "patches/rhachet-roles-ehmpathy.patch",
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/patches/rhachet-roles-ehmpathy.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/patches/rhachet-roles-ehmpathy@1.39.1.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/patches/type-fns@1.21.3.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/.test/assets/pnpm/declarations/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/pnpm-lock.yaml

@@ -0,0 +1,19 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+packages:
+
+  rhachet-roles-ehmpathy@1.40.0:
+    resolution: {integrity: sha512-a}
+
+  type-fns@1.21.3:
+    resolution: {integrity: sha512-b}
+
+snapshots:
+
+  rhachet-roles-ehmpathy@1.40.0: {}
+
+  type-fns@1.21.3: {}

package/dist/.test/assets/pnpm/declarations/practices/pnpm/__snapshots__/stale-patched-dependency.declapract.integration.test.ts.snap

@@ -36,3 +36,42 @@ exports[`pnpm — a stale patch never blocks an install given: [case1] a repo wi
 }
 "
 `;
+
+exports[`pnpm — a stale patch never blocks an install given: [case2] a repo with a bare-name patch key beside a stale exact key of the same package when: [t0] the pnpm practice is applied then: the before + after contents match snapshot: package.json — after 1`] = `
+"{
+  "name": "repo-stale-patch-beside-bare",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy": "patches/rhachet-roles-ehmpathy.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    },
+    "allowUnusedPatches": true,
+    "ignorePatchFailures": true
+  }
+}
+"
+`;
+
+exports[`pnpm — a stale patch never blocks an install given: [case2] a repo with a bare-name patch key beside a stale exact key of the same package when: [t0] the pnpm practice is applied then: the before + after contents match snapshot: package.json — before 1`] = `
+"{
+  "name": "repo-stale-patch-beside-bare",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy": "patches/rhachet-roles-ehmpathy.patch",
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}
+"
+`;

package/dist/.test/assets/pnpm/declarations/practices/pnpm/stale-patched-dependency.declapract.integration.test.ts

@@ -79,4 +79,57 @@ describe('pnpm — a stale patch never blocks an install', () => {
       });
     });
   });
+
+  given('[case2] a repo with a bare-name patch key beside a stale exact key of the same package', () => {
+    // the shape persist-with-rds ships for pg-pool: a bare key, which no lockfile can move past
+    const tempDir = genTempRepoWithDeclarationsOutside({
+      slug: 'pnpm-stale-patch-beside-bare',
+      clone: './src/practices/pnpm/.test/assets/repo-stale-patch-beside-bare',
+      declarations: './src/.test/assets/pnpm/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
+    });
+    const stalePatch = 'patches/rhachet-roles-ehmpathy@1.39.1.patch';
+    const barePatch = 'patches/rhachet-roles-ehmpathy.patch';
+
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+      const read = () =>
+        fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+      const before = await read();
+      await executeApply({ config });
+      const after1 = await read();
+      const exists1 = {
+        stale: existsSync(path.join(tempDir, stalePatch)),
+        bare: existsSync(path.join(tempDir, barePatch)),
+      };
+      await executeApply({ config });
+      const after2 = await read();
+      return { before, after1, after2, exists1 };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied', () => {
+      then('the stale exact key is retired; the bare-name key is kept', () => {
+        const patched = JSON.parse(state.after1).pnpm.patchedDependencies;
+        expect(patched).toEqual({
+          'rhachet-roles-ehmpathy': barePatch,
+          'type-fns@1.21.3': 'patches/type-fns@1.21.3.patch',
+        });
+      });
+
+      then('the stale patch file is deleted; the bare-name file is kept', () => {
+        expect(state.exists1).toEqual({ stale: false, bare: true });
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(state.before).toMatchSnapshot('package.json — before');
+        expect(state.after1).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t1] the practice is applied a second time', () => {
+      then('the second apply is a no-op', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
 });

package/dist/.test/assets/rhachet/declarations/practices/rhachet/best-practice/.declapract.readme.md

@@ -30,3 +30,11 @@ that a re-apply changes zero bytes.
 
 it sits there because one temp repo must hold both declarations to prove they agree. this pointer
 exists so a reader in `src/practices/rhachet/` can find it.
+
+## route robocode folds in a pr
+
+this practice declares a `# [rhachet]` section of the repo-root `.gitattributes`: each file under
+`.route/` and `.behavior/` is `linguist-generated`, so github renders it collapsed, except
+`*.yield.*` files and `.radio/` records, which stay open. its section sits last among the declarers,
+so those exceptions win over any earlier collapse line. to un-fold a path, see "what folds in a pr"
+in `src/practices/git/best-practice/.declapract.readme.md`.

package/dist/.test/assets/rhachet/declarations/practices/rhachet/best-practice/.gitattributes.declapract.ts

@@ -0,0 +1,65 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
+
+/**
+ * .what = the `.gitattributes` section this practice owns: route robocode folds in pr diffs
+ * .why  = rhachet installs the roles that drive routes (bhrain: `.route/`; bhuild:
+ *         `.behavior/`). a route carries stones, guards, reviews, caches: the trail. the
+ *         yields hold what the route concluded, and `.radio/` holds what it handed off. so a
+ *         pr folds the trail and opens on the yields and the radio
+ * .note = order carries load: git takes the last line that matches, so each
+ *         `-linguist-generated` exception follows the collapse line it carves out of.
+ *         attributes never recurse from a dir, so each pattern ends in `/**`
+ */
+const sections: readonly GitattributesSection[] = [
+  {
+    header: {
+      latest:
+        '# [rhachet] collapse route robocode in pr diffs; yields and radio stay open',
+      retired: [],
+    },
+    entries: {
+      latest: [
+        '.route/** linguist-generated',
+        '.route/**/*.yield.* -linguist-generated',
+        '.route/**/.radio/** -linguist-generated',
+        '.behavior/** linguist-generated',
+        '.behavior/**/*.yield.* -linguist-generated',
+        '.behavior/**/.radio/** -linguist-generated',
+      ],
+      retired: [],
+    },
+  },
+];
+
+/**
+ * .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: 'rhachet',
+    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/tests-any-only/declarations/practices/tests-any/best-practice/.declapract.readme.md

@@ -43,3 +43,10 @@
   - `jest.unit.env`
   - `jest.integration.env`
   - `jest.acceptance.env`
+
+## test source folds in a pr; snapshots stay open
+
+this practice declares a `# [tests-any]` section of the repo-root `.gitattributes`: `*.test.ts` and
+`*.test.tsx` are `linguist-generated`, so github renders them collapsed. `*.snap` files stay open, so
+a reviewer still reads each output change. to un-fold a path, see "what folds in a pr" in
+`src/practices/git/best-practice/.declapract.readme.md`.

package/dist/.test/assets/tests-any-only/declarations/practices/tests-any/best-practice/.gitattributes.declapract.ts

@@ -0,0 +1,60 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
+
+/**
+ * .what = the `.gitattributes` section this practice owns: test source folds in pr diffs
+ * .why  = a test file is the how; its snapshot is the proof. github folds a file marked
+ *         `linguist-generated`, one click away, so a pr opens on the snapshot diff and the
+ *         source, and the test source waits for the reviewer who asks for it
+ * .note = `*.snap` takes no line: linguist never marks a snapshot as generated, so it renders
+ *         open. `*.test.tsx` covers the expo cut, whose jest matches
+ *         `<star><star>/<star>.test.{ts,tsx}`
+ * .note = `<star>` stands in for the literal `*` wildcard, and must stay a stand-in. a literal
+ *         `*` immediately before a `/` closes this comment mid-prose
+ * .note = `linguist-generated` names a render hint here, not provenance; the header says so
+ */
+const sections: readonly GitattributesSection[] = [
+  {
+    header: {
+      latest:
+        '# [tests-any] collapse test source in pr diffs; snapshots stay open',
+      retired: [],
+    },
+    entries: {
+      latest: ['*.test.ts linguist-generated', '*.test.tsx linguist-generated'],
+      retired: [],
+    },
+  },
+];
+
+/**
+ * .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: 'tests-any',
+    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/__snapshots__/gitattributesDeclarers.declapract.integration.test.ts.snap

@@ -0,0 +1,79 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`gitattributes declarers given: [case1] a repo that adopts all five .gitattributes declarers, with a repo-own override when: [t0] before any apply then: the input holds the repo-own override and no declarer tag; it matches snapshot: .gitattributes — before 1`] = `
+"*.png binary
+src/access/daos/custom/** -linguist-generated
+
+# 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
+pnpm-lock.yaml merge=theirs
+package-lock.json merge=theirs
+"
+`;
+
+exports[`gitattributes declarers given: [case1] a repo that adopts all five .gitattributes declarers, with a repo-own override when: [t1] each practice applies, in turn then: the output holds every declarer section in order, then the repo-own lines; it matches snapshot: .gitattributes — all declarers 1`] = `
+"# [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
+
+# [tests-any] collapse test source in pr diffs; snapshots stay open
+*.test.ts linguist-generated
+*.test.tsx linguist-generated
+
+# [persist-with-rds] collapse dao-generator output in pr diffs
+src/access/daos/**/.generated/** linguist-generated
+provision/schema/**/.generated/** linguist-generated
+
+# [persist-with-dynamodb] collapse dao-generator output in pr diffs
+src/access/daos/**/.generated/** linguist-generated
+
+# [rhachet] collapse route robocode in pr diffs; yields and radio stay open
+.route/** linguist-generated
+.route/**/*.yield.* -linguist-generated
+.route/**/.radio/** -linguist-generated
+.behavior/** linguist-generated
+.behavior/**/*.yield.* -linguist-generated
+.behavior/**/.radio/** -linguist-generated
+
+*.png binary
+src/access/daos/custom/** -linguist-generated
+"
+`;
+
+exports[`gitattributes declarers given: [case3] a repo with no .gitattributes, that adopts git and persist-with-dynamodb when: [t0] the file is removed, then each practice applies then: it holds the git sections, then the dynamodb section, and no other: .gitattributes — born, git + dynamodb 1`] = `
+"# [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
+
+# [persist-with-dynamodb] collapse dao-generator output in pr diffs
+src/access/daos/**/.generated/** linguist-generated
+"
+`;
+
+exports[`gitattributes declarers given: [case4] a repo that dropped tests-any, and un-folds one test file when: [t0] git applies over the stale section then: the settled file matches snapshot: .gitattributes — a dropped declarer, after git 1`] = `
+"# [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
+
+# [tests-any] collapse test source in pr diffs; snapshots stay open
+*.test.ts linguist-generated
+*.test.tsx linguist-generated
+
+src/domain.operations/keep.test.ts -linguist-generated
+"
+`;