declapract-typescript-ehmpathy 0.49.8 → 0.49.9

package/dist/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/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/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/practices/git/.test/assets/repo-without-cache-ignores/package.json

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

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

@@ -0,0 +1,51 @@
+// 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`] = `
+"*.bak.*
+*.local.json
+*.log
+*.tsbuildinfo
+.agent/.cache/
+.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`] = `
+".agent/.cache/
+.idea
+dist
+node_modules
+!.test*/**/node_modules
+!.test*/**/node_modules/**
+"
+`;

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

@@ -0,0 +1,23 @@
+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.
+
+## `.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/practices/git/best-practice/.gitignore.declapract.ts

@@ -1,14 +1,40 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
-import { dedupe } from 'domain-objects';
 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.
  */
-const ignoresSortable = [
+const ignoresSortable: readonly string[] = [
   '*.log',
   '*.tsbuildinfo',
-  '.agent/.cache/', // agent cache (trash dir, temp files)
+  '.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',
@@ -23,44 +49,44 @@ const ignoresSortable = [
   '*.bak.*', // backup files
   'coverage',
   'dist',
-].sort();
+];
 
 /**
- * ignores that must appear in a specific order (negations must follow their targets)
- *
- * note
- * - node_modules under .test* dirs are test fixtures (cloned repos via genTempDir)
- * - gitignore negation requires the negated pattern to come after the original
+ * .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 ignoresOrdered = [
-  'node_modules',
-  '!.test*/**/node_modules',
-  '!.test*/**/node_modules/**',
-];
-
-const defineExpectedContents = (contents: string | null): string => {
-  // parse ignores from file
-  const ignoresFromFile = contents ? contents.split('\n') : [];
-
-  // separate into sortable vs ordered
-  const orderedPatterns = new Set(ignoresOrdered);
-  const ignoresFromFileSortable = ignoresFromFile.filter(
-    (line) => !!line && !orderedPatterns.has(line),
-  );
-
-  // combine and sort the sortable ignores
-  const sortedIgnores = dedupe([...ignoresFromFileSortable, ...ignoresSortable])
-    .sort()
-    .filter((line) => !!line);
-
-  // append ordered ignores at the end (order preserved)
-  return [...sortedIgnores, ...ignoresOrdered, ''].join('\n');
-};
+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) };
 };

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

@@ -0,0 +1,32 @@
+rhachet boots roles, and role boots write scratch state into `.agent/.cache/`
+
+so this practice declares the gitignore line for that dir — the practice that creates the scratch
+declares its ignore, rather than a neighbor practice a repo may not have taken.
+
+📖 several practices declare this same `.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.
+
+## it declares only `.agent/.cache/`, not `.cache/`
+
+`.cache/` is generic tool scratch and belongs to the `git` practice. a practice declares the
+ignore for the dirs it creates.
+
+⚠️ **"rhachet owns it" does not mean "git should drop it".** the `git` practice declares
+`.agent/.cache/` too, and that line stays: `app-react-native-expo` (`src/useCases.yml`) takes
+`git` **without** `rhachet`, so for those repos git's line is the only explicit source of the
+ignore.
+
+## the end-to-end proof lives under the git practice
+
+`src/practices/git/.declapract.integration.test.ts` → `[case2] a repo whose use case has rhachet
+but NOT git`.
+
+that is the scenario which justifies this declaration at all. it clones a demo repo whose use case
+omits `git`, applies **this** practice alone, and asserts the agent cache path is ignored with no
+help from git, that `.cache/` is correctly absent, that the negation is honored by git itself, and
+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.

package/dist/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -0,0 +1,64 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGitignoreContents';
+
+/**
+ * ignores that this practice itself owns
+ *
+ * .why = rhachet boots roles which write scratch state into `.agent/.cache/`. the
+ *        practice that creates the dir declares the ignore for it, so a repo that
+ *        takes `rhachet` is never left with cruft it did not ask for:
+ *        - a worktree teardown is not snagged by untracked scratch
+ *        - a hurried `git add .` cannot sweep a debug file that holds a secret
+ *
+ * .note = `.cache/` is generic tool scratch and belongs to the `git` practice, not
+ *         here. a practice declares the ignore for the dirs IT creates, and no more.
+ *
+ * .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`).
+ */
+const ignoresSortable: readonly string[] = ['.agent/.cache/'];
+
+/**
+ * .what = emits the `.gitignore` this practice declares, given the repo's extant one
+ * .why  = the algorithm AND the ordered tail are imported, not declared here, because
+ *         `src/practices/git/best-practice/.gitignore.declapract.ts` declares this same
+ *         repo-root file. two declarers converge only while both emit an identical tail
+ *         by an identical algorithm -- so they share one, and the drift that would break
+ *         convergence cannot be written.
+ * .note = this file declares only `ignoresSortable`, which is the part the two
+ *         practices legitimately DIFFER on: rhachet owns `.agent/.cache/`, git owns
+ *         the generic scratch. the shared part is shared; the owned part is owned.
+ */
+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 this is what makes an upgrade actually deliver
+ *         `.agent/.cache/` to a repo 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) };
+};

package/dist/utils/defineExpectedGitignoreContents.ts

@@ -0,0 +1,84 @@
+import { dedupe } from 'domain-objects';
+
+/**
+ * .what = the ignores whose POSITION carries load, in the sequence git requires
+ * .why  = a `.gitignore` negation re-includes a path only when it appears AFTER the
+ *         pattern it negates. hoist a `!` line above its target and git silently drops
+ *         the negation -- the file still reads as correct while every test-fixture
+ *         `node_modules` it protects is re-ignored.
+ * .why  = it lives HERE, shared, rather than in each declaration, because every
+ *         practice that declares the repo-root `.gitignore` must emit an IDENTICAL
+ *         tail or the two converge no longer, and `declapract fix` rewrites the file on
+ *         every run. one constant makes that drift unrepresentable.
+ * .note = `.test*` dirs hold cloned repos (test fixtures via `genTempDir`), whose
+ *         `node_modules` must stay tracked.
+ * .note = `readonly` carries load here, it is not decoration. this array is
+ *         module-cached and shared by every declarer, so ONE in-place mutation anywhere
+ *         (`.push`, an in-place `.sort`, `.reverse`) would break convergence for ALL of
+ *         them at once -- at runtime, with no compiler signal. `readonly` makes that
+ *         unrepresentable rather than merely discouraged
+ *         (`rule.prefer.prevent-over-correct`).
+ * .note = typed `readonly string[]` rather than `as const`: `as const` narrows the
+ *         elements to literal types, which would make `orderedPatterns.has(line)` below
+ *         reject a plain `string`. this form keeps the element type while it forbids the
+ *         mutation.
+ */
+export const ignoresOrderedForGitignore: readonly string[] = [
+  'node_modules',
+  '!.test*/**/node_modules',
+  '!.test*/**/node_modules/**',
+];
+
+/**
+ * .what = emits the `.gitignore` a practice declares, given the repo's extant one
+ * .why  = a findsert by construction -- the file's own lines are unioned in before the
+ *         sort, so a repo's custom ignores survive and a line already present stays
+ *         present once. and it is a fixed point: `fix(fix(x)) === fix(x)`.
+ * .why  = SHARED across every practice that declares this file. convergence between
+ *         two declarers rests on the whole ALGORITHM, not merely the tail -- union,
+ *         then sort, then append. two copies could drift step-for-step; one cannot.
+ * .note = `sortable` vs `ordered` is the domain's split for a declared line: inert
+ *         position vs load-carrying position. see
+ *         `.agent/repo=.this/role=any/briefs/domain.terms/term=ordered._.choice._.md`.
+ *
+ * ⚠️ .note = **THIS FUNCTION IS THE CONTRACT, NOT A CONVENIENCE.** every practice that declares
+ *         the repo-root `.gitignore` converges only because all of them route through here. a
+ *         declaration that hand-rolls its own union/sort/tail instead of this import is OUTSIDE
+ *         that guarantee -- it may satisfy its own check and still oscillate against the rest,
+ *         forever, on every `declapract fix`.
+ *
+ *         that failure mode is measured, not hypothetical. every declaration of this file once
+ *         carried its own copy of the algorithm, and one of them fell behind: it sorted every
+ *         line and emitted no ordered tail, which hoists the `!` negations above their target and
+ *         turns them inert. re-derive any declaration by hand today and the clamps reproduce it
+ *         exactly -- that declaration's own idempotency assertions stay green while every
+ *         cross-declarer assertion goes red.
+ *
+ *         no build step stops the next author from a repeat. so: **if you declare the repo-root
+ *         `.gitignore` from a new practice, import this -- do not re-derive it.** a lint rule or a
+ *         single-owner registry would be the durable guard; today the cross-declarer clamps are.
+ */
+export const defineExpectedGitignoreContents = (input: {
+  contents: string | null;
+  ignoresSortable: readonly string[];
+}): string => {
+  // parse ignores from the repo's extant file
+  const ignoresFromFile = input.contents ? input.contents.split('\n') : [];
+
+  // separate the file's own lines into sortable vs ordered
+  const orderedPatterns = new Set(ignoresOrderedForGitignore);
+  const ignoresFromFileSortable = ignoresFromFile.filter(
+    (line) => !!line && !orderedPatterns.has(line),
+  );
+
+  // union the file's sortable lines with this practice's, then sort
+  const sortedIgnores = dedupe([
+    ...ignoresFromFileSortable,
+    ...input.ignoresSortable,
+  ])
+    .sort()
+    .filter((line) => !!line);
+
+  // append the ordered tail last, sequence preserved
+  return [...sortedIgnores, ...ignoresOrderedForGitignore, ''].join('\n');
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.49.8",
+  "version": "0.49.9",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,15 +76,15 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.43.1",
-    "rhachet-brains-anthropic": "0.4.1",
+    "rhachet": "1.44.4",
+    "rhachet-brains-anthropic": "0.4.3",
     "rhachet-brains-fireworksai": "0.1.3",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.30.2",
+    "rhachet-roles-bhrain": "0.31.3",
     "rhachet-roles-bhrowser": "0.1.0",
-    "rhachet-roles-bhuild": "0.21.26",
-    "rhachet-roles-ehmpathy": "1.38.1",
-    "rhachet-roles-ghlitch": "0.2.5",
+    "rhachet-roles-bhuild": "0.21.31",
+    "rhachet-roles-ehmpathy": "1.38.6",
+    "rhachet-roles-ghlitch": "0.2.10",
     "rhachet-roles-rhachet": "0.1.7",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",