declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-migration/declarations/practices/domain/bad-practices/schema-over-contract/.declapract.readme.md

@@ -0,0 +1,12 @@
+a published contract (`src/contract/**`) that refers to a domain object via `X.schema`, or via a
+bare `X.contract` with no call.
+
+- `X.schema` validates the data but emits no dobj identity into the json-schema a consumer reads.
+  `X.contract()` is the same schema stamped with the dobj's name and keys, and it composes the same
+  way: `z.array(X.contract())`, `X.contract().nullable()`
+- since domain-objects@0.34.0, `contract` is a getter that returns a function to CALL on the class,
+  so a bare `X.contract` is a type error. a detached receiver (`const c = X.contract; c()`) is a
+  compile error by design, too
+
+the fix rewrites each such member of a name imported from a `domain.objects` path to
+`X.contract()`. it leaves `X.schema.parse(…)` (internal validation) and `typeof X.schema` alone.

package/dist/.test/assets/expo-migration/declarations/practices/domain/bad-practices/schema-over-contract/src/contract/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,78 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = a value import from a `domain.objects` module: `import { A, B as C } from '…domain.objects…'`.
+ * .why  = only a dobj class carries `.contract()`, so the rewrite is scoped to names this file
+ *         imports from a domain.objects path; a zod schema or a sdk type that also has `.schema`
+ *         is left alone. an `import type { … }` is skipped — a type-only name cannot be a value.
+ */
+const DOBJ_IMPORT_PATTERN =
+  /import\s+(?!type\b)\{([^}]*)\}\s*from\s*['"][^'"]*domain\.objects[^'"]*['"]/g;
+
+/**
+ * .what = the local names a file imports as values from a `domain.objects` module.
+ */
+export const getDobjNamesImported = (input: { contents: string }): string[] =>
+  [...input.contents.matchAll(DOBJ_IMPORT_PATTERN)]
+    .flatMap((match) => (match[1] ?? '').split(','))
+    .map((specifier) => specifier.trim())
+    .filter((specifier) => specifier && !specifier.startsWith('type '))
+    .map(
+      (specifier) =>
+        specifier
+          .split(/\s+as\s+/)
+          .pop()
+          ?.trim() ?? '',
+    )
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+
+/**
+ * .what = the two shapes a published contract must not carry for a dobj `X`.
+ * .why  =
+ *   - `X.schema` validates, but emits no dobj identity into the json-schema a consumer reads (#565)
+ *   - `X.contract` with no call is a type error since domain-objects@0.34.0, where `contract`
+ *     became a getter that returns a function to CALL on the class (#634, defect 1)
+ * .note = `X.schema.parse(…)` (and its kin) is internal validation, never a published shape, so
+ *         it is left alone; so is `typeof X.schema`, since `typeof X.contract()` is not a type query.
+ */
+const asOutdatedMemberPattern = (input: { name: string }): RegExp =>
+  new RegExp(
+    `(?<!typeof\\s+)(?<![\\w$.])${input.name.replace(/\$/g, '\\$')}\\.(?:schema\\b(?!\\s*\\.\\s*(?:parse|safeParse|parseAsync|safeParseAsync)\\b)|contract\\b(?!\\s*\\())`,
+    'g',
+  );
+
+/**
+ * .what = flags a published contract file that refers to a dobj via `X.schema` or a bare `X.contract`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents &&
+    getDobjNamesImported({ contents }).some((name) =>
+      asOutdatedMemberPattern({ name }).test(contents),
+    )
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: each dobj in this contract is referred to via X.contract()',
+  );
+};
+
+/**
+ * .what = rewrites each `X.schema` / bare `X.contract` to `X.contract()`.
+ * .why  = `X.contract()` is the same zod schema stamped with the dobj's identity, so it composes
+ *         exactly as `X.schema` did (`z.array(X.contract())`, `X.contract().nullable()`).
+ * .note = idempotent: `X.contract()` matches neither shape, so a second pass changes no byte.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: getDobjNamesImported({ contents }).reduce(
+      (rewritten, name) =>
+        rewritten.replace(
+          asOutdatedMemberPattern({ name }),
+          `${name}.contract()`,
+        ),
+      contents,
+    ),
+  };
+};

package/dist/.test/assets/expo-migration/declarations/practices/domain/best-practice/src/domain.objects/index.ts.declapract.ts

@@ -1,4 +1,4 @@
-import { FileCheckType } from 'declapract';
+import { asPresenceCheck } from '../../../../../utils/asPresenceCheck';
 
 // a project should declare domain objects — otherwise, what does the service operate on?
 //
@@ -9,4 +9,7 @@ import { FileCheckType } from 'declapract';
 // its own kin — `domain-dir`'s fix moved the required file away, so a repo reached a terminal,
 // unrepairable state. keyed on the go-forward layout, the two practices agree: `domain-dir`'s fix
 // produces exactly this path.
-export const check = FileCheckType.EXISTS;
+export const check = asPresenceCheck({
+  expected: 'src/domain.objects/index.ts',
+  hint: 'create it as the entry for the domain objects this service declares',
+});

package/dist/.test/assets/expo-migration/declarations/practices/domain/contract.declapract.integration.test.ts

@@ -0,0 +1,61 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the `X.contract()` migration (#565, #634), through the REAL apply.
+ * .why  = `schema-over-contract` rewrites each published `X.schema` / bare `X.contract` to
+ *   `X.contract()`, and must leave internal `.schema.safeParse` alone. only the pipeline proves the
+ *   declared glob reaches the handler.
+ * .note = the handler is snapshotted before AND after.
+ */
+describe('domain X.contract() migration', () => {
+  given('[case1] a repo whose handler refers to dobjs via .schema and a bare .contract', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-domain-contract',
+      clone: './src/.test/assets/domain-contract/repo-with-contract',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/domain-contract/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const handlerPath = 'src/contract/handlers/getChatThread.ts';
+    const readHandler = () => fs.readFile(path.join(tempDir, handlerPath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'domain',
+        file: handlerPath,
+      });
+
+    when('[t0] the fix is applied, then applied again', () => {
+      const result = useThen('apply twice', async () => {
+        const before = await readHandler();
+        await applyFix();
+        const once = await readHandler();
+        await applyFix();
+        const twice = await readHandler();
+        return { before, once, twice };
+      });
+
+      then('the handler refers to each dobj via X.contract(), and keeps internal .schema.safeParse', () => {
+        expect(result.once).toContain("thread: ChatThread.contract().ref('primary'),");
+        expect(result.once).toContain('thread: ChatThread.contract().nullable(),');
+        expect(result.once).toContain('z.array(Transmission.contract())');
+        expect(result.once).toContain('ChatThread.schema.safeParse(input)');
+        expect(result.before).toMatchSnapshot('getChatThread.ts — before');
+        expect(result.once).toMatchSnapshot('getChatThread.ts — after');
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(result.twice).toEqual(result.once);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,105 @@
+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';
+
+// executeApply evaluates the whole git practice before the `file` filter narrows it
+jest.setTimeout(5 * 60 * 1000);
+
+const MANAGED_ENTRIES = [
+  'pnpm-lock.yaml -diff',
+  'package-lock.json -diff',
+  'pnpm-lock.yaml merge=theirs',
+  'package-lock.json merge=theirs',
+];
+
+/**
+ * .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
+ *         (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
+ */
+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: './.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();
+        const template = await fs.readFile(
+          path.join(__dirname, 'best-practice/.gitattributes'),
+          'utf-8',
+        );
+        return { after: await read(), template };
+      });
+
+      then('the file contains the template verbatim — the CONTAINS check passes', () => {
+        expect(scene.after).toContain(scene.template.trim());
+      });
+
+      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', () => {
+        expect(scene.after).toContain('*.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/expo-migration/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/expo-migration/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 .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
+# .note = NO `variables:` block — `git` and `rhachet` reference zero `@declapract{variable.*}`
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project

package/dist/.test/assets/expo-migration/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/expo-migration/declarations/practices/git/__snapshots__/.declapract.integration.test.ts.snap

@@ -9,14 +9,15 @@ 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.*
+"**/.claude/scheduled_tasks*
+*.bak.*
 *.local.json
 *.log
 *.tsbuildinfo
 .agent/.cache/
+.agent/.notes/
 .artifact
 .cache/
-.claude/scheduled_tasks*
 .env
 .idea
 .log/slowtest/
@@ -42,8 +43,9 @@ node_modules
 `;
 
 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/
-.claude/scheduled_tasks*
+"**/.claude/scheduled_tasks*
+.agent/.cache/
+.agent/.notes/
 .idea
 dist
 node_modules

package/dist/.test/assets/expo-migration/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`] = `
+"*.png binary
+
+# 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
+"
+`;

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

@@ -39,134 +39,60 @@ const SECTIONS: {
 ];
 
 /**
- * all latest entries managed by this practice (for deduplication)
+ * .what = every line this practice manages: each section's header and entries, latest and prior
+ * .why  = the fix lifts each of these out of wherever it sits, so none can linger out of place,
+ *         out of order, or twice
  */
-const ALL_LATEST_ENTRIES = SECTIONS.flatMap((s) => s.entries.latest);
+const ALL_MANAGED_LINES = SECTIONS.flatMap((s) => [
+  s.header.latest,
+  ...s.header.priors,
+  ...s.entries.latest,
+  ...s.entries.priors,
+]);
 
 /**
- * all prior entries that should be removed
+ * .what = the canonical block: each section's latest header + latest entries, in declared order
+ * .why  = the check is CONTAINS — the file must hold the whole template as one contiguous run of
+ *         text — so the fix must emit this block verbatim. a section re-assembled in place (an
+ *         entry inserted after its header, or a stray entry left outside its section) is a fixed
+ *         point that never CONTAINS the template, so the plan would flag the file on every run
  */
-const ALL_PRIOR_ENTRIES = SECTIONS.flatMap((s) => s.entries.priors);
+const CANONICAL_BLOCK = SECTIONS.map((s) =>
+  [s.header.latest, ...s.entries.latest].join('\n'),
+).join('\n\n');
 
 /**
- * all prior headers that should be removed
+ * .what = the repo-own lines of a .gitattributes: every managed line dropped, runs of blank
+ *         lines collapsed to one, and the edges trimmed
+ * .why  = the repo keeps every line this practice does not manage, in its own order
  */
-const ALL_PRIOR_HEADERS = SECTIONS.flatMap((s) => s.header.priors);
-
-/**
- * .what = drops prior headers + prior entries, and dedupes latest entries (keep first)
- * .why = the fix must not re-emit a legacy line, nor a second copy of a managed entry;
- *        a named transform keeps cleanContent a narrative of what happens, not how
- */
-const asLinesWithLegacyDroppedAndDeduped = (input: {
-  lines: string[];
-}): string[] => {
-  const { lines } = input.lines.reduce<{
-    lines: string[];
-    seen: Set<string>;
-  }>(
-    (acc, line) => {
-      const trimmed = line.trim();
-
-      // skip prior headers + prior entries
-      if (ALL_PRIOR_HEADERS.includes(trimmed)) return acc;
-      if (ALL_PRIOR_ENTRIES.includes(trimmed)) return acc;
-
-      // skip duplicate latest entries (keep first occurrence)
-      if (ALL_LATEST_ENTRIES.includes(trimmed)) {
-        if (acc.seen.has(trimmed)) return acc;
-        return {
-          lines: [...acc.lines, line],
-          seen: new Set([...acc.seen, trimmed]),
-        };
-      }
-
-      return { lines: [...acc.lines, line], seen: acc.seen };
-    },
-    { lines: [], seen: new Set<string>() },
+const asRepoOwnBlock = (input: { contents: string }): string => {
+  // drop every managed line, wherever it sits
+  const linesRepoOwn = input.contents
+    .split('\n')
+    .filter((line) => !ALL_MANAGED_LINES.includes(line.trim()));
+
+  // collapse runs of blank lines into one (drop a blank that follows a blank)
+  const linesCollapsed = linesRepoOwn.filter(
+    (line, index) =>
+      !(
+        line.trim() === '' &&
+        index > 0 &&
+        linesRepoOwn[index - 1]!.trim() === ''
+      ),
   );
-  return lines;
-};
-
-/**
- * removes legacy headers, duplicate entries, and cleans up empty lines
- */
-const cleanContent = (content: string): string => {
-  // drop legacy headers, legacy entries, and duplicate latest entries (keep first)
-  const cleanedLines = asLinesWithLegacyDroppedAndDeduped({
-    lines: content.split('\n'),
-  });
 
-  // collapse multiple consecutive empty lines into one (drop an empty that follows an empty)
-  const collapsedLines = cleanedLines.filter((line, index) => {
-    const isEmpty = line.trim() === '';
-    const prevWasEmpty = index > 0 && cleanedLines[index - 1]!.trim() === '';
-    return !(isEmpty && prevWasEmpty);
-  });
-
-  return collapsedLines.join('\n').trim();
+  return linesCollapsed.join('\n').trim();
 };
 
 /**
- * ensures a section with header and entries exists in the content
- */
-const ensureSection = (
-  content: string,
-  section: (typeof SECTIONS)[number],
-): string => {
-  const lines = content.split('\n');
-
-  // find which entries are absent from the content
-  const entriesAbsent = section.entries.latest.filter(
-    (entry) => !content.includes(entry),
-  );
-
-  // find the header line index
-  const headerIndex = lines.findIndex(
-    (line) => line.trim() === section.header.latest,
-  );
-
-  // if header not found, append header and only absent entries
-  if (headerIndex === -1) {
-    return (
-      content.trimEnd() +
-      '\n\n' +
-      [section.header.latest, ...entriesAbsent].join('\n') +
-      '\n'
-    );
-  }
-
-  // if all entries present, no fix required
-  if (entriesAbsent.length === 0) return content;
-
-  // insert absent entries right after the header
-  const newLines = [
-    ...lines.slice(0, headerIndex + 1),
-    ...entriesAbsent,
-    ...lines.slice(headerIndex + 1),
-  ];
-
-  return newLines.join('\n');
-};
-
-/**
- * fix by cleanup of legacy content and ensure all sections are present
+ * .what = the repo-own lines first, then the canonical block, with exactly one final newline
+ * .why  = legacy headers and entries drop, duplicates collapse to one, and the output CONTAINS the
+ *         template — so the check passes on the fixed output and a second fix changes zero
  */
 export const fix: FileFixFunction = (contents) => {
-  // if no contents, create the file with all sections
-  if (!contents) {
-    const allSections = SECTIONS.map((s) =>
-      [s.header.latest, ...s.entries.latest].join('\n'),
-    ).join('\n\n');
-    return { contents: allSections + '\n' };
-  }
-
-  // clean up legacy headers and duplicates, then ensure each section exists
-  const result = SECTIONS.reduce(
-    (acc, section) => ensureSection(acc, section),
-    cleanContent(contents),
-  );
-
-  // trim to exactly one final newline
-  return { contents: result.trimEnd() + '\n' };
+  const repoOwnBlock = asRepoOwnBlock({ contents: contents ?? '' });
+  return {
+    contents: `${[repoOwnBlock, CANONICAL_BLOCK].filter((block) => block).join('\n\n')}\n`,
+  };
 };