declapract-typescript-ehmpathy 0.49.9 → 0.49.11

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

@@ -0,0 +1,59 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in any /domain/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move any /domain/objects/* to /domain.objects/*
+  // move any /domain/* to /domain.objects/*
+  const newPath = context.relativeFilePath
+    .replace(/\/domain\/objects\//g, '/domain.objects/')
+    .replace(/\/domain\//g, '/domain.objects/');
+
+  let fixedContents = contents;
+
+  // fix relative imports for files DIRECTLY in domain/objects/ that move to domain.objects/
+  // these files move UP one directory level, so reduce ../ by one
+  // note: nested files (domain/objects/nested/Deep.ts) stay at same depth, no transform
+  const isDirectChildOfDomainObjects = /\/domain\/objects\/[^/]+$/.test(
+    context.relativeFilePath,
+  );
+  if (fixedContents && isDirectChildOfDomainObjects) {
+    fixedContents = fixedContents.replace(
+      /((?:import|export)[^'"]*['"])((?:\.\.\/)+)/g,
+      (match, importPrefix, dotDots) => {
+        const count = dotDots.split('../').length - 1;
+        if (count === 1) {
+          // '../X' → './X'
+          return `${importPrefix}./`;
+        }
+        // '../../X' → '../X', '../../../X' → '../../X', etc.
+        return `${importPrefix}${'../'.repeat(count - 1)}`;
+      },
+    );
+  }
+
+  // fix internal export paths in index files
+  // when domain/index.ts moves to domain.objects/index.ts,
+  // exports like './objects/User' should become './User'
+  if (
+    fixedContents &&
+    context.relativeFilePath.includes('/domain/') &&
+    context.relativeFilePath.endsWith('/index.ts')
+  ) {
+    fixedContents = fixedContents
+      // export * from './objects' → remove (objects dir flattened to root)
+      .replace(/export\s+\*\s+from\s+['"]\.\/objects['"];?\n?/g, '')
+      // ./objects/Foo → ./Foo
+      .replace(/(['"])\.\/objects\//g, '$1./')
+      // ../domain/objects/Foo → ../domain.objects/Foo (for cross-references)
+      .replace(/(['"])([^'"]*?)\/domain\/objects\//g, '$1$2/domain.objects/')
+      // ../domain/Foo → ../domain.objects/Foo
+      .replace(/(['"])([^'"]*?)\/domain\//g, '$1$2/domain.objects/');
+  }
+
+  return {
+    contents: fixedContents ?? null,
+    relativeFilePath: newPath,
+  };
+};

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

@@ -0,0 +1,8 @@
+the `src/logic/` directory pattern is deprecated
+
+use `src/domain.operations/` instead for domain behavior and business rules
+
+this aligns with the directional-dependencies architecture where:
+- `domain.operations/` contains domain behavior and business rules
+- `domain.operations/` may depend on `domain.objects/` or `infra/`
+- `domain.operations/` must not reference infrastructure concerns directly

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

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = moves any file from any /logic/ to /domain.operations/
+ * .why = ensures all files are moved, not just .ts files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const newPath = context.relativeFilePath.replace(
+    /\/logic\//g,
+    '/domain.operations/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

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

@@ -0,0 +1,3 @@
+we use `domain.objects` directory instead of `model` directory
+- model directory was what we originally went with, but realized `domain.objects` was more explicit and better represented what we were going after
+- files are migrated directly from `src/model/` to `src/domain.objects/`

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

@@ -0,0 +1,16 @@
+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
+};
+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/expo-migration/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-migration/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-migration/declarations/practices/domain/best-practice/package.json

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

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

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// project should have domain objects... otherwise, what is the purpose of this thing? (how can we have a service that does not operate on a domain?)
+export const check = FileCheckType.EXISTS;