declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/services-dir/.declapract.readme.md

@@ -0,0 +1,5 @@
+sometimes a "services" dir is used to describe the directory that business logic should reside in
+
+this is kind of confusing, because typically in those same cases you are working in a project called `service-something`. so, "service-something" also has a directory of "services" inside of it... which is a little confusing
+
+instead, we use the `logic` directory to store this code. its more clear, because this dir stores the business logic that this service was created to store (i.e., the whole point of the service is to give us the ability to run that logic).

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

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move any /services/* to /domain.operations/* (services = business logic)
+  const newPath = context.relativeFilePath.replace(
+    /\/services\//g,
+    '/domain.operations/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/best-practice/.declapract.readme.md

@@ -0,0 +1,73 @@
+layers in a project following directional-dependencies architecture:
+
+```
+src/
+  contract/            # topmost — public interfaces, local commands
+    api/               # public invocable api endpoints, deployed and exposed by the project
+    cmd/               # private internal use entrypoints, supported by the project
+    sdk/               # public software development kit exports, supported by the project
+    cli/               # public command line interface contracts, supported by the project
+
+  access/              # infrastructure layer (daos, sdks, svcs)
+    daos/              # private persistence logic — may reference domain objects
+    sdks/              # remote third party contracts, from any alt org
+    svcs/              # remote first party contracts, from our own org
+
+  domain.objects/      # canonical domain declarations
+  domain.operations/   # domain behavior + business rules
+
+  infra/               # infrastructure specific adapters
+```
+
+dependency rules:
+- each layer may depend **only on the layers below it**
+- `contract/` may depend on `domain.objects/` and `domain.operations/`
+- `access/` may depend on `domain.objects/` and `domain.operations/`
+- `domain.operations/` may depend on `domain.objects/` or `infra/`
+- `domain.objects/` must not depend on anything outside its own layer
+- `infra/` must not depend on anything outside its own layer
+
+layer responsibilities:
+
+- contract layer
+  - summary: responsible for strictly exposing the logic/domain defined in the service
+  - responsibilities:
+    - specifies the inputs and outputs
+    - normalizes inputs on behalf of user
+    - validates the inputs
+    - normalizes outputs on behalf of service
+  - purpose:
+    - separates how users interact with our business logic _from_ our business logic
+  - supporting-references:
+    - https://docs.aws.amazon.com/whitepapers/latest/serverless-architectures-lambda/business-logic-outside-the-handler.html
+
+- domain.objects layer
+  - summary: defines the domain which this service masters
+  - responsibilities:
+    - specify domain objects
+    - specify constants
+  - purpose:
+    - a canonical definition of the domain + ubiquitous language owned by the service
+
+- domain.operations layer
+  - summary: defines the business logic that this service manages
+  - responsibilities:
+    - define the business logic of the domain in an organized and maintainable way
+  - purpose:
+    - to explicitly define the business logic as close to human language as possible
+
+- access layer
+  - summary: defines how to persist data / leverage third party clients
+  - responsibilities:
+    - daos (data access objects)
+    - sdks (third party remote service contracts)
+    - svcs (first party remote service contracts)
+  - purpose:
+    - separates how to interact with data stores and remote services from our business logic
+
+- infra layer
+  - summary: defines infrastructure-specific adapters
+  - responsibilities:
+    - infrastructure adapters that bridge domain logic to specific infrastructure
+  - purpose:
+    - keeps infrastructure concerns isolated from domain logic

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/access/daos/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// daos are optional - not all services have persistence
+export const check = { type: FileCheckType.EXISTS, optional: true };

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/access/sdks/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// sdks (third party remote service contracts) are optional - not all services use external apis
+export const check = { type: FileCheckType.EXISTS, optional: true };

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/access/svcs/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// svcs (first party remote service contracts) are optional - not all services call other internal services
+export const check = { type: FileCheckType.EXISTS, optional: true };

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

@@ -0,0 +1,7 @@
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
+
+// contract layer is required - there should be some contract in this service (api, sdk, cli, cmd)
+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/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/domain.objects/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,7 @@
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
+
+// domain objects are required - what is the purpose of a service without domain objects?
+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/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/domain.operations/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,7 @@
+import { asPresenceCheck } from '../../../../../../utils/asPresenceCheck';
+
+// domain operations are required - there should be business logic in the service
+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/directory-structure-src/declarations/practices/directory-structure-src/best-practice/src/infra/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// infra layer is optional - not all services need infrastructure-specific adapters
+export const check = { type: FileCheckType.EXISTS, optional: true };

package/dist/.test/assets/directory-structure-src/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the directory-structure-src integration test
+use-cases:
+  lambda-service:
+    practices:
+      - directory-structure-src

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/package.json

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

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/src/domain/index.ts

@@ -0,0 +1,2 @@
+// export * from './constants';
+export * from './objects';

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/src/domain/objects/Quote.ts

@@ -0,0 +1,4 @@
+export interface Quote {
+  uuid: string;
+  priceWords: string;
+}

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/src/domain/objects/index.ts

@@ -0,0 +1 @@
+export * from './Quote';

package/dist/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels/src/domain.operations/getQuote.ts

@@ -0,0 +1,6 @@
+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;

package/dist/.test/assets/domain-contract/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the domain practice integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

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

@@ -0,0 +1,115 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `domain` best-practice to the go-forward `src/domain.objects/` layout, so it
+ *         can never again require a file that its kin `directory-structure-src`'s `domain-dir`
+ *         bad-practice forbids (D51 / #574).
+ * .why  = both practices sit in `typescript-project-core`, so every service repo carries both.
+ *         `domain-dir` forbids EVERY file under `src/**​/domain/**` and its fix RELOCATES them to
+ *         `src/domain.objects/`. while `domain` required `src/domain/objects/index.ts`, a repo that
+ *         satisfied `domain` VIOLATED `domain-dir`, and `domain-dir`'s fix moved the required file
+ *         AWAY — a terminal, unrepairable state. keyed on `domain.objects`, the two agree:
+ *         `domain-dir`'s fix produces exactly what `domain` requires.
+ * .note = this is an INTEGRATION test by the same rule the sibling `actionPins` walk cites — it
+ *         reads the filesystem (`readdirSync` over the `domain` best-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any filesystem-crossing test in the integration
+ *         suite. it needs no credential and no network; the boundary alone classifies it.
+ * .note = this is the FOCUSED clamp for the one collision D51 named. the wish's broader durable
+ *         guard — "no best-practice path is matched by a bad-practice glob in the SAME usecase,
+ *         across every practice" — is owed as a follow-on; it must land with a full collision audit,
+ *         since a repo-wide lint may surface other overlaps already present that each need a verdict.
+ */
+
+const BEST_PRACTICE_DIR = `${__dirname}/best-practice`;
+
+// the `schematic-joi-model` bad-practice DETECTS joi models by content and rewrites them to
+// domain-objects. its subject glob scopes WHERE it looks; keyed at the deprecated `src/domain/`
+// path it is inert on any migrated repo (D51 / #574, ask 2) — the go-forward path is
+// `src/domain.objects/`, exactly where `directory-structure-src`'s `domain-dir` relocates files.
+const JOI_DETECTOR_DIR = `${__dirname}/bad-practices/schematic-joi-model`;
+
+/**
+ * .what = the CONSUMER target path a declaration governs, relative to a practice-half base dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix; any other file is
+ *         a template that governs itself.
+ */
+const asConsumerTargetPath = (input: { absPath: string; baseDir: string }): string => {
+  const rel = relative(input.baseDir, input.absPath);
+  return rel.replace(/\.declapract\.ts$/, '');
+};
+
+/**
+ * .what = does a consumer target path sit under a bare `domain/` path segment?
+ * .why = that is precisely the set `domain-dir`'s `src/**​/domain/**` glob forbids. a
+ *        `domain.objects` segment is NOT a `domain` segment (the `.objects` makes it a distinct
+ *        directory name), so the go-forward layout reads false here.
+ */
+const isUnderBareDomainSegment = (input: { targetPath: string }): boolean =>
+  input.targetPath.split('/').includes('domain');
+
+/**
+ * .what = every declared CONSUMER target path under a practice-half dir — the walk minus the files
+ *         that are not governed consumer paths (readmes, todos, `.test.ts`, `__snapshots__`).
+ * .why  = both scenes below gather the same set from different base dirs; one named transformer
+ *         holds the exclusion list in one place rather than an inline `.filter` chain a reader
+ *         must simulate twice (rule.require.named-transformers).
+ */
+const getConsumerTargetPaths = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null })
+    .filter((path) => !/\.declapract\.readme\.md$/.test(path))
+    .filter((path) => !/\.declapract\.todo\.md$/.test(path))
+    // a test file is not a governed consumer path — exclude it so the walk holds
+    // only real declarations to the layout, not `.test.ts` / `__snapshots__`
+    .filter((path) => !/\.test\.ts$/.test(path))
+    .filter((path) => !/\/__snapshots__\//.test(path))
+    .map((absPath) => asConsumerTargetPath({ absPath, baseDir: input.dir }));
+
+describe('domain practice — go-forward layout (D51 clamp)', () => {
+  given('[case1] the `domain` best-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: BEST_PRACTICE_DIR }),
+    }));
+
+    when('[t0] its declared consumer target paths are gathered', () => {
+      then('none sits under a bare `domain/` segment that `domain-dir` forbids', () => {
+        // teeth: the pre-fix declaration at `src/domain/objects/index.ts.declapract.ts` targets
+        // `src/domain/objects/index.ts`, whose `domain` segment is exactly what `domain-dir`
+        // relocates — so a revert of the move to the deprecated path reddens this assertion.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the objects index is declared at the `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/index.ts');
+      });
+    });
+  });
+
+  given('[case2] the `schematic-joi-model` bad-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: JOI_DETECTOR_DIR }),
+    }));
+
+    when('[t0] its declared subject glob paths are gathered', () => {
+      then('none sits under a bare `domain/` segment (else the detector is inert post-migration)', () => {
+        // teeth: revert the glob to `src/domain/**/*.ts.declapract.ts` and its subject path
+        // `src/domain/**/*.ts` carries a bare `domain` segment — the deprecated location a
+        // migrated repo no longer holds — so this assertion reddens.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the joi detector targets the go-forward `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/**/*.ts');
+      });
+    });
+  });
+});

package/dist/.test/assets/domain-contract/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/domain-contract/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/domain-contract/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/domain-contract/declarations/practices/domain/bad-practices/schematic-joi-model/src/domain.objects/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,19 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('SchematicJoiModel')) return; // if it includes that, then this file matches a bad practice
+  if (contents?.includes('schematic-joi-model')) return; // if it includes that, then this file matches a bad practice
+  // otherwise, does not match the bad practice: no SchematicJoiModel import or schematic-joi-model reference found
+  throw new Error(
+    'does not match bad practice: no SchematicJoiModel or schematic-joi-model reference found',
+  );
+};
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {}; // shouldnt be called if file does not exist, but handle it in case anyway
+  return {
+    contents: contents
+      .replace('import SchematicJoiModel ', 'import { DomainObject } ')
+      .replace("from 'schematic-joi-model'", "from 'domain-objects'")
+      .replace(/SchematicJoiModel/g, 'DomainObject'), // default to a generic domain object, since we dont know if it should be a value object or domain entity
+  };
+};

package/dist/.test/assets/domain-contract/declarations/practices/domain/bad-practices/simple-type-guards/.declapract.readme.md

@@ -0,0 +1 @@
+`simple-type-guards` has been deprecated in favor of `type-fns`

package/dist/.test/assets/domain-contract/declarations/practices/domain/bad-practices/simple-type-guards/package.json.declapract.ts

@@ -0,0 +1,23 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  const packageJSONObject = JSON.parse(contents!);
+  if (
+    Object.keys(packageJSONObject.dependencies).includes('simple-type-guards')
+  )
+    return; // matches
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {}; // should not occur
+  const packageJSONObject = JSON.parse(contents);
+  const fixedPackageJSONObject = {
+    ...packageJSONObject,
+    dependencies: {
+      ...packageJSONObject.dependencies,
+      'simple-type-guards': undefined,
+    },
+  };
+  return { contents: JSON.stringify(fixedPackageJSONObject, null, 2) };
+};

package/dist/.test/assets/domain-contract/declarations/practices/domain/best-practice/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "domain-objects": "@declapract{check.minVersion('0.34.0')}",
+    "type-fns": "@declapract{check.minVersion('1.21.4')}"
+  }
+}

package/dist/.test/assets/domain-contract/declarations/practices/domain/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

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

@@ -0,0 +1,15 @@
+import { asPresenceCheck } from '../../../../../utils/asPresenceCheck';
+
+// a project should declare domain objects — otherwise, what does the service operate on?
+//
+// this requires the `src/domain.objects/` layout that `directory-structure-src`'s `domain-dir`
+// bad-practice enforces. it deliberately does NOT require the deprecated `src/domain/objects/`
+// path: `domain-dir` forbids every file under `src/**/domain/**` and its fix relocates them to
+// `src/domain.objects/`, so a check that required `src/domain/objects/index.ts` (D51) contradicted
+// 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 = asPresenceCheck({
+  expected: 'src/domain.objects/index.ts',
+  hint: 'create it as the entry for the domain objects this service declares',
+});

package/dist/.test/assets/domain-contract/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/domain-contract/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the domain practice integration test
+use-cases:
+  lambda-service:
+    practices:
+      - domain

package/dist/.test/assets/domain-contract/repo-with-contract/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/domain-contract/repo-with-contract/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "domain-objects": "0.34.0",
+    "type-fns": "1.21.4"
+  }
+}

package/dist/.test/assets/domain-contract/repo-with-contract/src/contract/handlers/getChatThread.ts

@@ -0,0 +1,19 @@
+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/domain-contract/repo-with-contract/src/domain.objects/ChatThread.ts

@@ -0,0 +1,10 @@
+import { DomainEntity } from 'domain-objects';
+
+export interface ChatThread {
+  id?: number;
+  uuid?: string;
+  externalId: string;
+}
+export class ChatThread extends DomainEntity<ChatThread> implements ChatThread {
+  public static unique = ['externalId'] as const;
+}