declapract-typescript-ehmpathy 0.49.14 → 0.50.0

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

@@ -0,0 +1,120 @@
+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 { 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',
+  'pnpm-lock.yaml merge=theirs',
+  'package-lock.json merge=theirs',
+];
+
+/**
+ * .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)
+ * .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', () => {
+    const tempDir = genTempDir({
+      slug: 'git-gitattributes-legacy',
+      clone: './src/practices/git/.test/assets/repo-with-legacy-gitattributes',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/git/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+    const read = () =>
+      fs.readFile(path.join(tempDir, '.gitattributes'), 'utf-8');
+    const apply = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'git',
+        file: '.gitattributes',
+      });
+
+    when('[t0] before any apply', () => {
+      then('the input file matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('.gitattributes — before');
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      const scene = useThen('apply settles', async () => {
+        await apply();
+        return { after: await read() };
+      });
+
+      then('the git check passes on the file', () => {
+        expect(() => checkGit(scene.after, context)).not.toThrow();
+      });
+
+      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', () => {
+        expect(scene.after).not.toContain('# exclude package-lock from git diff');
+        expect(scene.after).not.toContain('pnpm-lock.json -diff');
+      });
+
+      then('each managed entry appears exactly once', () => {
+        MANAGED_ENTRIES.forEach((entry) =>
+          expect(
+            scene.after.split('\n').filter((line) => line.trim() === entry),
+          ).toHaveLength(1),
+        );
+      });
+
+      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', () => {
+        expect(scene.after).not.toContain('@declapract{');
+      });
+
+      then('the output matches snapshot', () => {
+        expect(scene.after).toMatchSnapshot('.gitattributes — after');
+      });
+    });
+
+    when('[t2] apply runs a second time', () => {
+      const before = useBeforeAll(async () => ({ contents: await read() }));
+      const scene = useThen('apply again', async () => {
+        await apply();
+        return { after: await read() };
+      });
+
+      then('the file is byte-identical — the apply is a fixed point', () => {
+        expect(scene.after).toEqual(before.contents);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/git/.test/assets/repo-with-legacy-gitattributes/.gitattributes

@@ -0,0 +1,6 @@
+*.png binary
+
+# exclude package-lock from git diff; https://stackoverflow.com/a/72834452/3068233
+package-lock.json -diff
+pnpm-lock.json -diff
+pnpm-lock.yaml merge=theirs

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

@@ -0,0 +1,7 @@
+# .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 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/git/declarations/practices/git/.test/assets/repo-with-legacy-gitattributes/package.json

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

package/dist/.test/assets/git/declarations/practices/git/.test/assets/repo-with-rhachet-only/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test
+# .why  = `rhachet-only` deliberately omits the `git` practice, to prove rhachet
+#         declares the ignore for the dir rhachet writes without help from a
+#         neighbor practice
+declarations: 'declarations/declapract.declare.yml'
+useCase: rhachet-only

package/dist/.test/assets/git/declarations/practices/git/.test/assets/repo-with-rhachet-only/package.json

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

package/dist/.test/assets/git/declarations/practices/git/.test/assets/repo-without-cache-ignores/declapract.use.yml

@@ -0,0 +1,9 @@
+# .note = declarations dir is symlinked by the test
+# .note = NO `variables:` block. the rule's top gotcha is that apply evaluates the
+#         whole practice, so every `@declapract{variable.*}` it references must be
+#         defined here. both `git` and `rhachet` reference ZERO -- verified by grep,
+#         and by this fixture, which applies clean without any. a variables block
+#         copied from another fixture "to be safe" would be a claim the practices
+#         make demands they do not.
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project

package/dist/.test/assets/git/declarations/practices/git/.test/assets/repo-without-cache-ignores/package.json

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

package/dist/.test/assets/git/declarations/practices/git/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,55 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`gitignore practices given: [case1] a repo whose .gitignore lacks both cache dirs when: [t0] before any apply then: the input file matches snapshot: .gitignore -- before 1`] = `
+"dist
+coverage
+.idea
+node_modules
+"
+`;
+
+exports[`gitignore practices given: [case1] a repo whose .gitignore lacks both cache dirs when: [t3] both practices are applied a second time then: the settled file matches snapshot: .gitignore -- settled 1`] = `
+"**/.claude/scheduled_tasks*
+*.bak.*
+*.local.json
+*.log
+*.tsbuildinfo
+.agent/.cache/
+.agent/.notes/
+.artifact
+.cache/
+.env
+.idea
+.log/slowtest/
+.serverless
+.temp
+.terraform
+.terraform.lock
+.vscode
+.yalc
+coverage
+dist
+node_modules
+!.test*/**/node_modules
+!.test*/**/node_modules/**
+"
+`;
+
+exports[`gitignore practices given: [case2] a repo whose use case has rhachet but NOT git when: [t0] before any apply then: the input file matches snapshot: .gitignore -- rhachet only -- before 1`] = `
+"dist
+node_modules
+.idea
+"
+`;
+
+exports[`gitignore practices given: [case2] a repo whose use case has rhachet but NOT git when: [t1] the rhachet practice is applied then: the settled file matches snapshot: .gitignore -- rhachet only 1`] = `
+"**/.claude/scheduled_tasks*
+.agent/.cache/
+.agent/.notes/
+.idea
+dist
+node_modules
+!.test*/**/node_modules
+!.test*/**/node_modules/**
+"
+`;

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

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`git .gitattributes given: [case1] a repo whose .gitattributes holds a legacy header, a legacy entry, and an out-of-section entry when: [t0] before any apply then: the input file matches snapshot: .gitattributes — before 1`] = `
+"*.png binary
+
+# exclude package-lock from git diff; https://stackoverflow.com/a/72834452/3068233
+package-lock.json -diff
+pnpm-lock.json -diff
+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`] = `
+"# [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
+
+*.png binary
+"
+`;

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

@@ -0,0 +1,60 @@
+the repo-root `.gitignore` and `.gitattributes`
+
+📖 several practices declare the `.gitignore`. the contract they share — one shared algorithm, the
+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 —
+which is a different claim from which practices declare the ignore for it.
+
+this line stays because `app-react-native-expo` (`src/useCases.yml`) takes `git` **without**
+`rhachet`, so for those repos it is the only explicit source of the ignore. `.cache/` happens to
+cover `.agent/.cache/` at any depth, but that coverage is implicit — narrow `.cache/` and it is
+gone. the same caution sits in `.gitignore.declapract.ts`, at the point of edit.
+
+## this repo consumes this practice
+
+`declapract.use.yml` sets `useCase: npm-package`, which extends `typescript-project`, which
+carries `git`. so `[case3]` in `src/practices/git/.declapract.integration.test.ts` checks this
+repo's own `.gitignore` against the declaration — add a line to `ignoresSortable` and it goes red
+until the practice is applied here too.

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

@@ -0,0 +1,77 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
+
+/**
+ * .what = the `.gitattributes` sections this practice owns: lock-file diff and merge rules
+ * .why  = lock files churn on every install. `-diff` folds them out of `git diff`, and
+ *         `merge=theirs` takes the incoming lock on a conflict, so an install after the merge
+ *         rebuilds it
+ * .note = `retired` hold every form these sections once took — the untagged headers, the
+ *         `pnpm-lock.json` typo — so a fix lifts them out of an extant file
+ */
+const sections: readonly GitattributesSection[] = [
+  {
+    header: {
+      latest:
+        '# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233',
+      retired: [
+        '# exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233',
+        '# exclude package-lock from git diff; https://stackoverflow.com/a/72834452/3068233',
+      ],
+    },
+    entries: {
+      latest: ['pnpm-lock.yaml -diff', 'package-lock.json -diff'],
+      retired: ['pnpm-lock.json -diff'],
+    },
+  },
+  {
+    header: {
+      latest:
+        '# [git] auto-resolve lock file conflicts by taking theirs; run install after merge',
+      retired: [
+        '# auto-resolve lock file conflicts by taking theirs; run install after merge',
+      ],
+    },
+    entries: {
+      latest: ['pnpm-lock.yaml merge=theirs', 'package-lock.json merge=theirs'],
+      retired: ['pnpm-lock.json merge=theirs'],
+    },
+  },
+];
+
+/**
+ * .what = emits the `.gitattributes` this practice declares, given the repo's extant one
+ * .why  = tests-any, rhachet, and the persist practices declare this same file. they converge
+ *         only through one shared algorithm, so this file declares its sections and imports
+ *         the rest
+ */
+const defineExpectedContents = (input: { contents: string | null }): string =>
+  defineExpectedGitattributesContents({
+    contents: input.contents,
+    declarer: 'git',
+    sections,
+  });
+
+/**
+ * .what = throws when the repo's `.gitattributes` differs from what the shared layout emits
+ * .why  = `check` gates `fix`: a throw means violated (best-practice semantics). an exact
+ *         equality, not CONTAINS, since order carries load and `check(x) ⟺ x === fix(x)`
+ *         keeps `declapract apply` from a loop
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents({ contents }));
+};
+
+/**
+ * .what = sets this practice's sections into the repo's `.gitattributes`
+ * .why  = legacy headers and entries drop, duplicates collapse to one, repo-own lines move
+ *         last; a fixed point, so a second fix changes zero
+ */
+export const fix: FileFixFunction = (contents) => ({
+  contents: defineExpectedContents({ contents }),
+});

package/dist/.test/assets/git/declarations/practices/git/best-practice/.gitignore.declapract.ts

@@ -0,0 +1,100 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGitignoreContents';
+
+/**
+ * ignores that can be sorted alphabetically (no order dependencies)
+ *
+ * .note = `.agent/.cache/` is declared HERE and by
+ *         `src/practices/rhachet/best-practice/.gitignore.declapract.ts`. that is not drift, and
+ *         the line must not be "cleaned up" as a duplicate of rhachet's -- rhachet OWNS that dir
+ *         in the causal sense (it creates it), which is a different claim from which practices
+ *         declare the ignore for it.
+ *
+ *         two facts carry the load here:
+ *         - `app-react-native-expo` (`src/useCases.yml`) takes `git` WITHOUT `rhachet`, so for
+ *           every repo on that use case THIS line is the only explicit source of the ignore
+ *         - `.cache/` below happens to cover `.agent/.cache/` at any depth (a gitignore pattern
+ *           with no interior separator is unanchored -- measured with `git check-ignore -v`), so
+ *           a reader sees the overlap and reads it as redundant. that coverage is IMPLICIT --
+ *           narrow `.cache/` and it is gone
+ *
+ *         so removal here would un-ignore the agent cache for every git-without-rhachet repo, on
+ *         the day `.cache/` is next edited, with no line left to say why. if this ever moves, it
+ *         must land in a practice that still reaches every `git` consumer.
+ *
+ * .note = this list is NOT sorted here, and that is deliberate. `defineExpectedGitignoreContents`
+ *         sorts the union of these lines with the repo's own, so a `.sort()` at this site would
+ *         be a second sort that changes no output -- while it mutates a module-cached array in
+ *         place. `readonly` forbids that mutation outright rather than merely discourages it
+ *         (`rule.prefer.prevent-over-correct`), so the source may group lines by what they are
+ *         for, with their comments beside them, and the one sort that matters stays in one place.
+ *
+ * .note = every line here governs an UNTRACKED path only. git consults `.gitignore` for a path
+ *         not yet in the index; a path a consumer ALREADY tracks stays tracked, and this
+ *         declaration cannot reach the index to reconcile it (the `fix` is a pure contents
+ *         transform, so it has no seam to the index). so a consumer that committed a match
+ *         BEFORE this practice declared the pattern keeps it committed, silently, behind a line
+ *         that reads as enforcement. to reconcile an extant match, run `git rm --cached <path>`
+ *         by hand. a loud in-consumer report of that case is a proposed follow-on (#582).
+ */
+const ignoresSortable: readonly string[] = [
+  '*.log',
+  '*.tsbuildinfo',
+  '.agent/.cache/', // agent cache -- kept even though rhachet declares it too; see .note above
+  '.artifact', // deployment artifacts from `simple-artifact-builder` are produced here
+  '.cache/', // cache directories from various tools
+  '.env',
+  '.serverless',
+  '.log/slowtest/',
+  '.terraform',
+  '.terraform.lock',
+  '.yalc',
+  '.temp',
+  '.vscode',
+  '*.local.json', // e.g., .claude/permission.attempts.local.json
+  '*.bak.*', // backup files
+  'coverage',
+  'dist',
+];
+
+/**
+ * .what = emits the `.gitignore` this practice declares, given the repo's extant one
+ * .why  = one algorithm serves both `check` and `fix`, so the gate and the repair can
+ *         never disagree about what the file should hold.
+ * .why  = the algorithm AND the ordered tail are imported, not declared here, because this
+ *         practice is not the only declarer of the repo-root `.gitignore`. declarers converge
+ *         only while every one of them emits an identical tail by an identical algorithm --
+ *         so they share one, and the drift that would break convergence cannot be written.
+ *         which practices those are is a `grep`; a count here would go stale the first time
+ *         one is added, as it already has once.
+ */
+const defineExpectedContents = (contents: string | null): string =>
+  defineExpectedGitignoreContents({ contents, ignoresSortable });
+
+/**
+ * .what = throws when the repo's `.gitignore` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. so a line added to `ignoresSortable` above reaches a consumer
+ *         repo only because this throws on the file that lacks it.
+ * .note = best-practice semantics are inverted from what a reader expects -- a THROW
+ *         means the practice is violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents(contents));
+};
+
+/**
+ * .what = unions this practice's declared ignores into the repo's `.gitignore`
+ * .why  = a findsert by construction -- a line already present stays present once,
+ *         and a repo's own custom ignores survive, because the file's extant lines
+ *         are unioned in before the sort.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output -- without both, `declapract fix` would rewrite this file forever.
+ *         clamped by `.gitignore.declapract.test.ts` -> `idempotency`.
+ */
+export const fix: FileFixFunction = (contents) => {
+  return { contents: defineExpectedContents(contents) };
+};