declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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

@@ -0,0 +1,46 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+const defineModelImportFromRelativePathName = ({
+  relativeFilePath,
+}: {
+  relativeFilePath: string;
+}) => {
+  const directoriesDeepFromSrc = relativeFilePath.split('/').slice(1, -1); // all the directories between src/ and the /fileName
+  const badImportPath = `${directoriesDeepFromSrc
+    .map(() => '..')
+    .join('/')}/model`;
+  const badImportStatementIdentifierToReplace = `from '${badImportPath}`; // notice that we dont close the `'` so that we can match `.../model/some/other/stuff';`
+  return badImportStatementIdentifierToReplace;
+};
+
+/**
+ * check they dont import from the model dir
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  const badImportIdentifier = defineModelImportFromRelativePathName({
+    relativeFilePath: context.relativeFilePath,
+  });
+  if (contents?.includes(badImportIdentifier)) return; // relative import to model dir
+  if (contents?.includes(`@src/model`)) return; // absolute @src/model import
+  if (contents?.includes(`/domain/domainObjects`)) return; // matches bad practice if it has import to `.../domainObjects/...` as well
+  throw new Error('does not match bad practice'); // TODO: make this less weird... its weird that we throw an error when its not bad practice
+};
+
+/**
+ * replace `.../model` imports with `.../domain.objects` imports
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const badImportIdentifier = defineModelImportFromRelativePathName({
+    relativeFilePath: context.relativeFilePath,
+  });
+  if (!contents) return {}; // do nothing if no contents, fn shouldn't have been called in this case
+  return {
+    contents: contents
+      .replace(
+        badImportIdentifier,
+        badImportIdentifier.replace('/model', '/domain.objects'), // should be referencing the domain.objects dir instead
+      )
+      .replace(/@src\/model\b/g, '@src/domain.objects') // fix absolute @src/model imports
+      .replace(/\/domainObjects/g, ''), // remove the domainObjects subdir as domain.objects is flat now
+  };
+};

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

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if we see that files with this path exist, its bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents:
+      contents?.replace(
+        "export * from './domainObjects';", // if it has this, we want to replace it
+        "export * from './';",
+      ) ?? null,
+    relativeFilePath: context.relativeFilePath
+      .replace(/\/model\/domainObjects\//g, '/domain.objects/')
+      .replace(/\/model\//g, '/domain.objects/'),
+  };
+};

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

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in __nonpublished_modules__/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move any /__nonpublished_modules__/ to /_topublish/
+  const newPath = context.relativeFilePath.replace(
+    /__nonpublished_modules__\//g,
+    '_topublish/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/directory-structure-src/bad-practices/old-import-paths/.declapract.readme.md

@@ -0,0 +1,21 @@
+imports referencing old directory structure paths should be updated
+
+old → new:
+- `src/data/dao` → `src/access/daos`
+- `src/data/clients` → `src/access/sdks`
+- `src/data/` → `src/access/`
+- `src/domain/objects` → `src/domain.objects`
+- `src/domain/` → `src/domain.objects/`
+- `src/logic/` → `src/domain.operations/`
+
+this bad practice checks all source files for imports using the old paths and fixes them.
+
+## two-pass migration
+
+a file still under a deprecated src dir is **deferred** this pass — the import rewrite is held to
+the next `declapract fix` pass. that is because the peer `old-*-dir` bad-practices RELOCATE the file
+this pass; a relocate plus an in-place rewrite of one file in one apply throws ENOENT on the unlinked
+source. so a consumer who migrates a repo that still holds `logic/` / `data/` / etc. must **run
+`declapract fix` twice**: pass 1 relocates the files, pass 2 rewrites their imports at the new path.
+the guard is shared with `typescript-any/relative-imports` via
+`src/utils/isDeferredToDeprecatedDirMove.ts`, so the two rewriters defer the same files.

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

@@ -0,0 +1,67 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { isDeferredToDeprecatedDirMove } from '../../../../../../utils/isDeferredToDeprecatedDirMove';
+
+// patterns to detect old import paths
+const OLD_PATH_PATTERNS = [
+  /from\s+['"][^'"]*\/data\/dao/,
+  /from\s+['"][^'"]*\/data\/clients/,
+  /from\s+['"][^'"]*\/data\//,
+  /from\s+['"][^'"]*\/domain\/objects/,
+  /from\s+['"][^'"]*\/domain\//,
+  /from\s+['"][^'"]*\/logic\//,
+  /from\s+['"][^'"]*\/model\/domainObjects/,
+  /from\s+['"][^'"]*\/model\//,
+  /from\s+['"][^'"]*\/services\//,
+  /from\s+['"][^'"]*\/__nonpublished_modules__\//,
+];
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('no contents');
+
+  // defer a file still under a deprecated dir to its peer dir-move: the move
+  // relocates it this pass, then this rewrite fires at the new path next pass.
+  // the two never touch one file in one apply, so no relocate+rewrite ENOENT.
+  if (
+    isDeferredToDeprecatedDirMove({
+      relativeFilePath: context?.relativeFilePath,
+    })
+  )
+    throw new Error('deferred to peer dir-move this pass');
+
+  // check if any old import path pattern matches
+  const hasOldImport = OLD_PATH_PATTERNS.some((pattern) =>
+    pattern.test(contents),
+  );
+
+  if (hasOldImport) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  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/',
+    );
+
+  return { contents: fixed };
+};

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

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// contract layer is required - there should be some contract in this service (api, sdk, cli, cmd)
+export const check = FileCheckType.EXISTS;

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

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// domain objects are required - what is the purpose of a service without domain objects?
+export const check = FileCheckType.EXISTS;

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

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// domain operations are required - there should be business logic in the service
+export const check = FileCheckType.EXISTS;

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

@@ -3,7 +3,10 @@ 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
-  throw new Error('passes'); // otherwise, does not match the 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

package/dist/.test/assets/expo-fullusecase/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/expo-fullusecase/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/expo-fullusecase/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/expo-fullusecase/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/expo-fullusecase/declarations/practices/domain/best-practice/src/domain.objects/index.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType } from 'declapract';
+
+// 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 = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/errors/.declapract.integration.test.ts

@@ -0,0 +1,121 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `own-implementation` bad-practice to a catch-all `src` glob (matches at any
+ *         depth), so it catches a consumer's own `UnexpectedCodePathError.ts` no matter which
+ *         directory segment holds it (D48 / #571).
+ * .why  = a declapract declaration's FILENAME is its target glob. the declaration was pinned to the
+ *         literal `src/utils/errors/UnexpectedCodePathError.ts`, so a consumer that keeps its own
+ *         implementation one segment away — `src/domain/errors/…`, `src/errors/…` — was NEVER
+ *         matched, and the bad practice silently never fired. its two kin (`error-fns`,
+ *         `local-error-imports`) already glob every `.ts` at any depth; this holds
+ *         `own-implementation` to the same catch-all so the miss-by-one-segment case cannot recur.
+ * .note = this is an INTEGRATION test by the same rule the kin `domain` walk cites — it reads the
+ *         filesystem (`readdirSync` over the bad-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any test that reads the filesystem in the
+ *         integration suite. it needs no credential and no network; the boundary alone classifies it.
+ */
+
+const BAD_PRACTICES_DIR = `${__dirname}/bad-practices`;
+const CATCH_ALL_PREFIX = 'src/**/';
+
+/**
+ * .what = every declaration path (`*.declapract.ts`, minus tests) under a bad-practice dir, walked
+ *         with node's own readdir
+ */
+const getAllDeclarationPathsUnderDir = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null }).filter(
+    (path) =>
+      /\.declapract\.ts$/.test(path) && !/\.declapract\.test\.ts$/.test(path),
+  );
+
+/**
+ * .what = the CONSUMER target glob a declaration governs, relative to its bad-practice dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix — which, since the
+ *         filename may hold glob segments, IS the target glob declapract matches on.
+ */
+const asConsumerTargetGlob = (input: {
+  absPath: string;
+  badPracticeDir: string;
+}): string =>
+  relative(input.badPracticeDir, input.absPath).replace(/\.declapract\.ts$/, '');
+
+/**
+ * .what = the first path segment of a relative path (the head dir, before the first `/`).
+ * .why  = a pure transformer leaf, named so the composer below reads intent rather than an
+ *         inline positional `.split('/')[0]` a reader must simulate to know which segment lands.
+ */
+const asFirstPathSegment = (input: { relPath: string }): string =>
+  input.relPath.split('/')[0]!;
+
+/**
+ * .what = the bad-practice dir that governs a declaration = its first path segment under
+ *         BAD_PRACTICES_DIR. a declaration's consumer glob is computed relative to this, so the
+ *         `own-implementation/` (etc) segment is stripped before the `src/` check.
+ */
+const asBadPracticeDir = (input: { absPath: string }): string =>
+  `${BAD_PRACTICES_DIR}/${asFirstPathSegment({
+    relPath: relative(BAD_PRACTICES_DIR, input.absPath),
+  })}`;
+
+describe('errors practice — catch-all glob paths (D48 clamp)', () => {
+  given('[case1] the `own-implementation` bad-practice', () => {
+    const badPracticeDir = `${BAD_PRACTICES_DIR}/own-implementation`;
+    const scene = useBeforeAll(() => ({
+      targetGlobs: getAllDeclarationPathsUnderDir({ dir: badPracticeDir }).map(
+        (absPath) => asConsumerTargetGlob({ absPath, badPracticeDir }),
+      ),
+    }));
+
+    when('[t0] its declared consumer target globs are gathered', () => {
+      then('it governs UnexpectedCodePathError.ts under a catch-all src glob at any depth', () => {
+        // teeth: the pre-fix declaration at `src/utils/errors/UnexpectedCodePathError.ts.declapract.ts`
+        // governs the literal `src/utils/errors/UnexpectedCodePathError.ts` — no catch-all segment —
+        // so a revert to the pinned path reddens this assertion.
+        expect(scene.targetGlobs).toContain(
+          `${CATCH_ALL_PREFIX}UnexpectedCodePathError.ts`,
+        );
+      });
+
+      then('no declaration pins the file to a fixed intermediate segment', () => {
+        // every declaration under this bad-practice that governs a src-tree file must glob at any
+        // depth; a fixed intermediate dir (e.g. `src/utils/errors/…`) is the miss-by-one-segment
+        // defect D48 names.
+        const pinnedToFixedSegment = scene.targetGlobs.filter(
+          (glob) => glob.startsWith('src/') && !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(pinnedToFixedSegment).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] every error bad-practice that governs a src-tree file', () => {
+    const scene = useBeforeAll(() => ({
+      // gather the src-tree target globs across ALL error bad-practices, so the catch-all
+      // convention is held for the whole practice, not just `own-implementation`. each
+      // declaration's bad-practice dir is its first path segment under BAD_PRACTICES_DIR, so the
+      // consumer glob is computed relative to the practice that governs it.
+      srcTargetGlobs: getAllDeclarationPathsUnderDir({ dir: BAD_PRACTICES_DIR })
+        .map((absPath) =>
+          asConsumerTargetGlob({
+            absPath,
+            badPracticeDir: asBadPracticeDir({ absPath }),
+          }),
+        )
+        .filter((glob) => glob.startsWith('src/')),
+    }));
+
+    when('[t0] their consumer target globs are gathered', () => {
+      then('every src-tree declaration globs at any depth', () => {
+        const notCatchAll = scene.srcTargetGlobs.filter(
+          (glob) => !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(notCatchAll).toEqual([]);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/errors/bad-practices/error-fns/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@ehmpathy/error-fns": "@declapract{check.minVersion('0.0.0')}"
+  }
+}