declapract-typescript-ehmpathy 0.45.4 → 0.45.6

package/dist/practices/cicd-package/best-practice/.github/workflows/provision.yml

@@ -18,7 +18,7 @@ jobs:
   github:
     uses: ./.github/workflows/.declastruct.yml
     with:
-      wish-path: provision/github/declastruct.resources.ts
+      wish-path: provision/github.repo/resources.ts
       github-environment: prod
       creds-github-app-owner: ehmpathy
       creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}

package/dist/practices/cicd-service/best-practice/.github/workflows/provision.yml

@@ -43,7 +43,7 @@ jobs:
   github:
     uses: ./.github/workflows/.declastruct.yml
     with:
-      wish-path: provision/github/declastruct.resources.ts
+      wish-path: provision/github.repo/resources.ts
       github-environment: prod
       creds-github-app-owner: ehmpathy
       creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}

package/dist/practices/directory-structure-src/bad-practices/data-dir/.declapract.readme.md

@@ -0,0 +1,10 @@
+the `src/data/` directory pattern is deprecated
+
+use `src/access/` instead, which contains:
+- `daos/` - data access objects for persistence
+- `sdks/` - third party remote service contracts
+- `svcs/` - first party remote service contracts
+
+this aligns with the directional-dependencies architecture where:
+- `access/` may depend on `domain.objects/` and `domain.operations/`
+- `access/` must remain free of domain knowledge and business rules

package/dist/practices/directory-structure-src/bad-practices/data-dir/src/data/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in src/data/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move src/data/dao/* to src/access/daos/*
+  // move src/data/clients/* to src/access/sdks/*
+  // move other src/data/* to src/access/*
+  const newPath = context.relativeFilePath
+    .replace('src/data/dao/', 'src/access/daos/')
+    .replace('src/data/clients/', 'src/access/sdks/')
+    .replace('src/data/', 'src/access/');
+
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/directory-structure-src/bad-practices/domain-dir/.declapract.readme.md

@@ -0,0 +1,8 @@
+the `src/domain/` directory pattern is deprecated
+
+use `src/domain.objects/` instead for domain object declarations
+
+this aligns with the directional-dependencies architecture where:
+- `domain.objects/` contains canonical domain declarations
+- `domain.objects/` must not depend on anything outside its own layer
+- separates domain objects from domain operations for clearer boundaries

package/dist/practices/directory-structure-src/bad-practices/domain-dir/src/domain/<star><star>/<star>.ts.declapract.ts

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

package/dist/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/practices/directory-structure-src/bad-practices/logic-dir/src/logic/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in src/logic/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move src/logic/* to src/domain.operations/*
+  const newPath = context.relativeFilePath.replace(
+    'src/logic/',
+    'src/domain.operations/',
+  );
+
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/directory-structure-src/bad-practices/model-dir/.declapract.readme.md

@@ -1,2 +1,3 @@
-we use `domain` directory instead of `model` directory
-- model directory was what we originally went with, but realized `domain` was more explicit and better represented what we were going after
+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/practices/directory-structure-src/bad-practices/model-dir/src/<star><star>/<star>.ts.declapract.ts

@@ -20,13 +20,14 @@ export const check: FileCheckFunction = (contents, context) => {
   const badImportIdentifier = defineModelImportFromRelativePathName({
     relativeFilePath: context.relativeFilePath,
   });
-  if (contents?.includes(badImportIdentifier)) return; // dont fail since it matches bad practice
+  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` imporst
+ * replace `.../model` imports with `.../domain.objects` imports
  */
 export const fix: FileFixFunction = (contents, context) => {
   const badImportIdentifier = defineModelImportFromRelativePathName({
@@ -37,8 +38,9 @@ export const fix: FileFixFunction = (contents, context) => {
     contents: contents
       .replace(
         badImportIdentifier,
-        badImportIdentifier.replace('/model', '/domain'), // should be referencing the domain dir instead
+        badImportIdentifier.replace('/model', '/domain.objects'), // should be referencing the domain.objects dir instead
       )
-      .replace('/domainObjects', '/objects'), // and should still replace this type of import, too
+      .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/practices/directory-structure-src/bad-practices/model-dir/src/model/<star><star>/<star>.ts.declapract.ts

@@ -7,10 +7,10 @@ export const fix: FileFixFunction = (contents, context) => {
     contents:
       contents?.replace(
         "export * from './domainObjects';", // if it has this, we want to replace it
-        "export * from './objects';",
+        "export * from './';",
       ) ?? null,
     relativeFilePath: context.relativeFilePath
-      .replace('src/model/', 'src/domain/')
-      .replace('domainObjects/', 'objects/'),
+      .replace('src/model/domainObjects/', 'src/domain.objects/')
+      .replace('src/model/', 'src/domain.objects/'),
   };
 };

package/dist/practices/directory-structure-src/bad-practices/old-import-paths/.declapract.readme.md

@@ -0,0 +1,11 @@
+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.

package/dist/practices/directory-structure-src/bad-practices/old-import-paths/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,41 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+// 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\//,
+];
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('no contents');
+
+  // 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/');
+
+  return { contents: fixed };
+};

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

@@ -1,4 +1,34 @@
-layers to a project:
+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:
@@ -10,23 +40,34 @@ layers to a project:
     - 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 layer
+
+- 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
-- logic layer
+
+- 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
-- data layer:
+
+- access layer
   - summary: defines how to persist data / leverage third party clients
   - responsibilities:
-    - daos
-    - clients
+    - daos (data access objects)
+    - sdks (third party remote service contracts)
+    - svcs (first party remote service contracts)
   - purpose:
-    - separates how to interact with data stores (our own persistance stores + third party client + first party clients) from our business logic
+    - 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/practices/directory-structure-src/best-practice/src/{data/clients → access/daos}/<star><star>/<star>.ts.declapract.ts

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

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

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

package/dist/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/practices/directory-structure-src/best-practice/src/{domain/index.ts.declapract.ts → domain.operations/<star><star>/<star>.ts.declapract.ts}

@@ -1,3 +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/practices/directory-structure-src/best-practice/src/{data/dao → infra}/<star><star>/<star>.ts.declapract.ts

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

package/dist/practices/persist-with-dynamodb/best-practice/codegen.dynamodb.dao.ts

@@ -5,12 +5,12 @@ import {
 } from 'dynamodb-dao-generator';
 
 export const introspect: DeclaredDomainObjectIntrospectionPaths = [
-  './src/domain/index.ts',
+  './src/domain.objects/index.ts',
 ];
 
 export const directories: DeclaredOutputDirectories = {
   terraform: `provision/aws/product`,
-  dao: `src/data/dao`,
+  dao: `src/access/daos`,
 };
 
 export const specifications: DeclaredDaoSpecification[] = [];

package/dist/practices/persist-with-rds/best-practice/codegen.sql.dao.yml

@@ -2,7 +2,7 @@ language: postgres
 dialect: 10.7
 generates:
   daos:
-    to: src/data/dao
+    to: src/access/daos
     using:
       log: src/utils/logger#log
       DatabaseConnection: src/utils/database/getDatabaseConnection#DatabaseConnection
@@ -15,4 +15,4 @@ generates:
 for:
   objects:
     search:
-      - 'src/domain/objects/*.ts'
+      - 'src/domain.objects/*.ts'

package/dist/practices/persist-with-rds/best-practice/codegen.sql.types.yml

@@ -5,12 +5,12 @@ resources: # where to find your tables, functions, views, procedures
   - 'provision/schema/sql/views/**/*.sql'
   - 'provision/schema/sql/functions/**/*.sql'
 queries: # where to find your queries (each file must `export const query = `...`);
-  - 'src/data/dao/**/*.ts'
-  - '!src/data/dao/**/index.ts'
-  - '!src/data/dao/**/castFromDatabaseObject.ts'
-  - '!src/data/dao/**/findByRef.ts'
+  - 'src/access/daos/**/*.ts'
+  - '!src/access/daos/**/index.ts'
+  - '!src/access/daos/**/castFromDatabaseObject.ts'
+  - '!src/access/daos/**/findByRef.ts'
   - '!src/**/*.test.ts'
   - '!src/**/*.test.integration.ts'
 generates: # where to output the generated code
-  types: src/data/dao/.generated/types.ts
-  queryFunctions: src/data/dao/.generated/queryFunctions.ts
+  types: src/access/daos/.generated/types.ts
+  queryFunctions: src/access/daos/.generated/queryFunctions.ts

package/dist/practices/provision-github/bad-practices/old-declastruct-resources-path/provision/github/declastruct.resources.ts.declapract.ts

@@ -0,0 +1,7 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete old path, replaced by provision/github.repo/resources.ts
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.45.4",
+  "version": "0.45.6",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",

package/dist/practices/directory-structure-src/best-practice/src/domain/constants.ts.declapract.ts

@@ -1,15 +0,0 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
-
-export const check = FileCheckType.EXISTS;
-
-export const fix: FileFixFunction = (contents) => {
-  if (contents) return {}; // if contents exist, do nothing
-  return {
-    contents: `${`
-/**
- * constants shared across the whole service but not tied to a specific domain object go in this file
- */
-    `.trim()}
-`,
-  };
-};

package/dist/practices/directory-structure-src/best-practice/src/domain/objects/index.ts.declapract.ts

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

package/dist/practices/directory-structure-src/best-practice/src/logic/<star><star>/<star>.ts.declapract.ts

@@ -1,4 +0,0 @@
-import { FileCheckType } from 'declapract';
-
-// files matching this format should exist - there should be business logic in the service
-export const check = FileCheckType.EXISTS;