declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/best-practice/commitlint.config.js

@@ -7,6 +7,9 @@ module.exports = {
     // line. keep body lines aligned with the 140-char header cap so a long
     // header can never fail the release-branch commit lint.
     'body-max-line-length': [1, 'always', 140],
+    // the same allowance for the footer: a long `Co-Authored-By:` or `Refs:` trailer
+    // must never fail a commit lint the body rule would pass
+    'footer-max-line-length': [1, 'always', 140],
     'type-enum': [
       2,
       'always',

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "scripts": {
     "commit:with-cli": "npx cz",
-    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from \"${LAST_TAG:-}\" --to HEAD --verbose"
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && commitlint --from \"${LAST_TAG:-}\" --to HEAD --verbose"
   },
   "devDependencies": {
     "@commitlint/cli": "@declapract{check.minVersion('19.5.0')}",

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/commitlint-body-max-line.declapract.integration.test.ts

@@ -46,4 +46,23 @@ describe('conventional-commits commitlint body-max-line-length', () => {
       });
     });
   });
+
+  /**
+   * .what = clamps #516: the footer gets the same warn-level 140 as the body
+   * .why  = config-conventional's footer-max-line-length is error-level 100, so a long
+   *         `Co-Authored-By:` or `Refs:` trailer failed test:commits though the body rule allowed it
+   */
+  given('the shipped commitlint.config.js, loaded as commitlint loads it (#516)', () => {
+    // the template is a commonjs config, so require it as commitlint does
+    const config = require(join(__dirname, 'best-practice/commitlint.config.js')) as {
+      rules: Record<string, unknown>;
+    };
+
+    when('the footer-max-line-length rule is read', () => {
+      then('it is warn-level 140, beside the body rule', () => {
+        expect(config.rules['footer-max-line-length']).toEqual([1, 'always', 140]);
+        expect(config.rules['body-max-line-length']).toEqual([1, 'always', 140]);
+      });
+    });
+  });
 });

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/.declapract.integration.test.ts

@@ -0,0 +1,98 @@
+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 domain barrel move and the bare barrel import repoint (#655, #671).
+ * .why  = two barrels (`domain/index.ts` → `./objects`, and `domain/objects/index.ts`) both move onto
+ *   `domain.objects/index.ts`; the outer one, stripped, held no export and could win the path. and
+ *   a bare `'@src/domain'` / `'../domain'` import matched neither the check nor the fix. only the real
+ *   pipeline proves which file lands on the shared path.
+ * .note = the outer barrel is applied AFTER the inner one — the order in which it used to win.
+ */
+describe('directory-structure-src domain barrels and bare barrel imports', () => {
+  given('[case1] a repo with two domain barrels and bare barrel imports', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-dirs-two-barrels',
+      clone: './src/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/directory-structure-src/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const isPresent = (relativePath: string) =>
+      fs
+        .access(path.join(tempDir, relativePath))
+        .then(() => true)
+        .catch(() => false);
+    const applyOne = (input: { file: string }) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'directory-structure-src',
+        file: input.file,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the barrels and the importer match snapshot', async () => {
+        expect(await read('src/domain/index.ts')).toMatchSnapshot('outer barrel — before');
+        expect(await read('src/domain/objects/index.ts')).toMatchSnapshot('inner barrel — before');
+        expect(await read('src/domain.operations/getQuote.ts')).toMatchSnapshot('importer — before');
+      });
+    });
+
+    when('[t1] the moves and the import repoint are applied', () => {
+      const after = useThen('apply, outer barrel last', async () => {
+        await applyOne({ file: 'src/domain/objects/index.ts' });
+        await applyOne({ file: 'src/domain/objects/Quote.ts' });
+        await applyOne({ file: 'src/domain/index.ts' });
+        await applyOne({ file: 'src/domain.operations/getQuote.ts' });
+        return {
+          barrel: await read('src/domain.objects/index.ts'),
+          importer: await read('src/domain.operations/getQuote.ts'),
+          outerPresent: await isPresent('src/domain/index.ts'),
+          quotePresent: await isPresent('src/domain.objects/Quote.ts'),
+        };
+      });
+
+      then('domain.objects/index.ts holds the inner barrel list, never the stripped outer one (#655)', () => {
+        expect(after.barrel).toContain("export * from './Quote';");
+        expect(after.outerPresent).toBe(false);
+        expect(after.quotePresent).toBe(true);
+        expect(after.barrel).toMatchSnapshot('domain.objects/index.ts — after');
+      });
+
+      then('each bare barrel import is repointed, and a package subpath is left alone (#655, #671)', () => {
+        expect(after.importer).toContain("from '@src/domain.objects';");
+        expect(after.importer).toContain("from '../domain.objects';");
+        expect(after.importer).toContain("from 'some-pkg/domain';");
+        expect(after.importer).toMatchSnapshot('importer — after');
+      });
+    });
+
+    when('[t2] the importer and the barrel are applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const files = ['src/domain.objects/index.ts', 'src/domain.operations/getQuote.ts'];
+        const before = await Promise.all(files.map((file) => read(file)));
+        await applyOne({ file: files[0]! });
+        await applyOne({ file: files[1]! });
+        const after = await Promise.all(files.map((file) => read(file)));
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: importer — before 1`] = `
+"import type { Quote } from '@src/domain';
+import type { Quote as QuoteRelative } from '../domain';
+import type { Widget } from 'some-pkg/domain';
+
+export const getQuote = (input: { quote: Quote; peer: QuoteRelative; widget: Widget }) =>
+  input.quote;
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: inner barrel — before 1`] = `
+"export * from './Quote';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: outer barrel — before 1`] = `
+"// export * from './constants';
+export * from './objects';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t1] the moves and the import repoint are applied then: domain.objects/index.ts holds the inner barrel list, never the stripped outer one (#655): domain.objects/index.ts — after 1`] = `
+"export * from './Quote';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t1] the moves and the import repoint are applied then: each bare barrel import is repointed, and a package subpath is left alone (#655, #671): importer — after 1`] = `
+"import type { Quote } from '@src/domain.objects';
+import type { Quote as QuoteRelative } from '../domain.objects';
+import type { Widget } from 'some-pkg/domain';
+
+export const getQuote = (input: { quote: Quote; peer: QuoteRelative; widget: Widget }) =>
+  input.quote;
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/bad-practices/domain-dir/src/<star><star>/domain/<star><star>/<star>.declapract.ts

@@ -1,14 +1,62 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
 
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
 // if files exist in any /domain/, this is a bad practice
 export const check = FileCheckType.EXISTS;
 
+/**
+ * .what = whether a file is an outer `domain/index.ts` barrel that only forwards `./objects`,
+ *         beside an inner `domain/objects/index.ts` barrel.
+ * .why  = both barrels move onto one path, `domain.objects/index.ts`. the outer one, once its
+ *         `./objects` forward is stripped, holds no export — and if it wins the path, every domain
+ *         export vanishes from the barrel with no error (#655). the inner barrel holds the real
+ *         list, so the outer one must yield the path to it.
+ */
+const isOuterBarrelBesideInner = (input: {
+  contents: string | null;
+  relativeFilePath: string;
+  projectRoot: string | null;
+}): boolean => {
+  if (!input.contents || !input.projectRoot) return false;
+  if (!/(?:^|\/)domain\/index\.ts$/.test(input.relativeFilePath)) return false;
+  const codeOnly = input.contents
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '')
+    .trim();
+  if (!/^export\s+\*\s+from\s+['"]\.\/objects['"];?$/.test(codeOnly))
+    return false;
+  // the inner barrel, before its move or after it (apply order is not guaranteed)
+  const domainDir = path.join(
+    input.projectRoot,
+    path.dirname(input.relativeFilePath),
+  );
+  return (
+    existsSync(path.join(domainDir, 'objects', 'index.ts')) ||
+    existsSync(path.join(path.dirname(domainDir), 'domain.objects', 'index.ts'))
+  );
+};
+
 export const fix: FileFixFunction = (contents, context) => {
+  // an outer barrel that only forwards ./objects yields the path to the inner barrel (#655)
+  if (
+    isOuterBarrelBesideInner({
+      contents,
+      relativeFilePath: context.relativeFilePath,
+      projectRoot: context.getProjectRootDirectory?.() ?? null,
+    })
+  )
+    return { contents: null };
+
   // move any /domain/objects/* to /domain.objects/*
   // move any /domain/* to /domain.objects/*
+  // .note = the lookahead leaves the slash after each segment unconsumed, so adjacent segments
+  //         (`/domain/domain/`) each move. a consumed slash left the second `domain` segment in
+  //         place, which the `src/**/domain/**/*` glob then matched again on the next apply.
   const newPath = context.relativeFilePath
-    .replace(/\/domain\/objects\//g, '/domain.objects/')
-    .replace(/\/domain\//g, '/domain.objects/');
+    .replace(/\/domain\/objects(?=\/)/g, '/domain.objects')
+    .replace(/\/domain(?=\/)/g, '/domain.objects');
 
   let fixedContents = contents;
 

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/bad-practices/old-import-paths/src/<star><star>/<star>.ts.declapract.ts

@@ -1,5 +1,9 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
+import {
+  hasBareDeprecatedDirSpecifier,
+  withBareDeprecatedDirSpecifiersRepointed,
+} from '../../../../../../utils/asBareDeprecatedDirSpecifierReplacement';
 import { isDeferredToDeprecatedDirMove } from '../../../../../../utils/isDeferredToDeprecatedDirMove';
 
 // patterns to detect old import paths
@@ -16,6 +20,32 @@ const OLD_PATH_PATTERNS = [
   /from\s+['"][^'"]*\/__nonpublished_modules__\//,
 ];
 
+/**
+ * .what = each slash-suffixed old dir specifier, repointed at its new dir
+ * .note = ordered most specific first, so `/data/dao` is read before `/data/`
+ */
+const withOldDirSpecifiersRepointed = (input: { contents: string }): string =>
+  input.contents
+    // data layer fixes
+    .replace(/(['"])([^'"]*?)\/data\/dao\b/g, '$1$2/access/daos')
+    .replace(/(['"])([^'"]*?)\/data\/clients\b/g, '$1$2/access/sdks')
+    .replace(/(['"])([^'"]*?)\/data\//g, '$1$2/access/')
+    // domain layer fixes
+    .replace(/(['"])([^'"]*?)\/domain\/objects\b/g, '$1$2/domain.objects')
+    .replace(/(['"])([^'"]*?)\/domain\//g, '$1$2/domain.objects/')
+    // logic layer fixes
+    .replace(/(['"])([^'"]*?)\/logic\//g, '$1$2/domain.operations/')
+    // model layer fixes (old structure before domain.objects)
+    .replace(/(['"])([^'"]*?)\/model\/domainObjects\b/g, '$1$2/domain.objects')
+    .replace(/(['"])([^'"]*?)\/model\//g, '$1$2/domain.objects/')
+    // services layer fixes (services = business logic, not service clients)
+    .replace(/(['"])([^'"]*?)\/services\//g, '$1$2/domain.operations/')
+    // nonpublished modules dir fix
+    .replace(
+      /(['"])([^'"]*?)\/__nonpublished_modules__\//g,
+      '$1$2/_topublish/',
+    );
+
 export const check: FileCheckFunction = (contents, context) => {
   if (!contents) throw new Error('no contents');
 
@@ -33,35 +63,31 @@ export const check: FileCheckFunction = (contents, context) => {
   const hasOldImport = OLD_PATH_PATTERNS.some((pattern) =>
     pattern.test(contents),
   );
-
   if (hasOldImport) return; // matches bad practice
+
+  // a bare barrel import ('@src/domain', '../../domain') — the same specifier set the fix repoints (#671)
+  if (
+    hasBareDeprecatedDirSpecifier({
+      contents,
+      relativeFilePath: context?.relativeFilePath ?? null,
+    })
+  )
+    return; // matches bad practice
+
   throw new Error('does not match bad practice');
 };
 
-export const fix: FileFixFunction = (contents) => {
+export const fix: FileFixFunction = (contents, context) => {
   if (!contents) return { contents };
 
-  // fix imports in order of specificity (most specific first)
-  const fixed = contents
-    // data layer fixes
-    .replace(/(['"])([^'"]*?)\/data\/dao\b/g, '$1$2/access/daos')
-    .replace(/(['"])([^'"]*?)\/data\/clients\b/g, '$1$2/access/sdks')
-    .replace(/(['"])([^'"]*?)\/data\//g, '$1$2/access/')
-    // domain layer fixes
-    .replace(/(['"])([^'"]*?)\/domain\/objects\b/g, '$1$2/domain.objects')
-    .replace(/(['"])([^'"]*?)\/domain\//g, '$1$2/domain.objects/')
-    // logic layer fixes
-    .replace(/(['"])([^'"]*?)\/logic\//g, '$1$2/domain.operations/')
-    // model layer fixes (old structure before domain.objects)
-    .replace(/(['"])([^'"]*?)\/model\/domainObjects\b/g, '$1$2/domain.objects')
-    .replace(/(['"])([^'"]*?)\/model\//g, '$1$2/domain.objects/')
-    // services layer fixes (services = business logic, not service clients)
-    .replace(/(['"])([^'"]*?)\/services\//g, '$1$2/domain.operations/')
-    // nonpublished modules dir fix
-    .replace(
-      /(['"])([^'"]*?)\/__nonpublished_modules__\//g,
-      '$1$2/_topublish/',
-    );
+  // repoint each bare barrel import first, so the slash-suffixed rewrites below never see it (#655)
+  const barrelsRepointed = withBareDeprecatedDirSpecifiersRepointed({
+    contents,
+    relativeFilePath: context?.relativeFilePath ?? null,
+  });
 
-  return { contents: fixed };
+  // repoint each slash-suffixed old dir specifier
+  return {
+    contents: withOldDirSpecifiersRepointed({ contents: barrelsRepointed }),
+  };
 };

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/best-practice/src/contract/<star><star>/<star>.ts.declapract.ts

@@ -1,4 +1,7 @@
-import { FileCheckType } from 'declapract';
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
 
 // contract layer is required - there should be some contract in this service (api, sdk, cli, cmd)
-export const check = FileCheckType.EXISTS;
+export const check = asPresenceCheck({
+  expected: 'at least one contract under src/contract/',
+  hint: 'author the entrypoint this service exposes (an api, sdk, cli, or cmd)',
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/best-practice/src/domain.objects/<star><star>/<star>.ts.declapract.ts

@@ -1,4 +1,7 @@
-import { FileCheckType } from 'declapract';
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
 
 // domain objects are required - what is the purpose of a service without domain objects?
-export const check = FileCheckType.EXISTS;
+export const check = asPresenceCheck({
+  expected: 'at least one domain object under src/domain.objects/',
+  hint: 'declare the nouns this service operates on',
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/best-practice/src/domain.operations/<star><star>/<star>.ts.declapract.ts

@@ -1,4 +1,7 @@
-import { FileCheckType } from 'declapract';
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
 
 // domain operations are required - there should be business logic in the service
-export const check = FileCheckType.EXISTS;
+export const check = asPresenceCheck({
+  expected: 'at least one domain operation under src/domain.operations/',
+  hint: 'declare the operations this service performs',
+});

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

@@ -0,0 +1,47 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`domain X.contract() migration given: [case1] a repo whose handler refers to dobjs via .schema and a bare .contract when: [t0] the fix is applied, then applied again then: the handler refers to each dobj via X.contract(), and keeps internal .schema.safeParse: getChatThread.ts — after 1`] = `
+"import { z } from 'zod';
+
+import { ChatThread } from '@src/domain.objects/ChatThread';
+import { Transmission } from '@src/domain.objects/Transmission';
+
+const schemaInput = z.object({
+  thread: ChatThread.contract().ref('primary'),
+  transmission: Transmission.contract().ref('primary'),
+});
+
+const schemaOutput = z.object({
+  thread: ChatThread.contract().nullable(),
+  transmissions: z.array(Transmission.contract()),
+});
+
+export const isThreadShaped = (input: unknown) =>
+  ChatThread.schema.safeParse(input).success;
+
+export const schema = { input: schemaInput, output: schemaOutput };
+"
+`;
+
+exports[`domain X.contract() migration given: [case1] a repo whose handler refers to dobjs via .schema and a bare .contract when: [t0] the fix is applied, then applied again then: the handler refers to each dobj via X.contract(), and keeps internal .schema.safeParse: getChatThread.ts — before 1`] = `
+"import { z } from 'zod';
+
+import { ChatThread } from '@src/domain.objects/ChatThread';
+import { Transmission } from '@src/domain.objects/Transmission';
+
+const schemaInput = z.object({
+  thread: ChatThread.contract.ref('primary'),
+  transmission: Transmission.contract().ref('primary'),
+});
+
+const schemaOutput = z.object({
+  thread: ChatThread.schema.nullable(),
+  transmissions: z.array(Transmission.schema),
+});
+
+export const isThreadShaped = (input: unknown) =>
+  ChatThread.schema.safeParse(input).success;
+
+export const schema = { input: schemaInput, output: schemaOutput };
+"
+`;

package/dist/.test/assets/expo-fullusecase/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-fullusecase/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-fullusecase/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-fullusecase/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);
+      });
+    });
+  });
+});