declapract-typescript-ehmpathy 0.39.18 → 0.40.0

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

@@ -0,0 +1,109 @@
+name: .declastruct
+
+on:
+  workflow_call:
+    inputs:
+      wish-path:
+        type: string
+        description: "the path to the wish declaration"
+      github-environment:
+        type: string
+        description: "the github environment that the apply step will be executed in"
+      allow-apply:
+        type: boolean
+        description: "whether the apply step is enabled. defaults to true on main"
+        default: ${{ github.ref == 'refs/heads/main' }}
+    secrets:
+      github-token:
+        required: false
+        description: optional credentials to support authenticating with github provider
+
+jobs:
+  # install the dependencies
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  plan:
+    runs-on: ubuntu-latest
+    needs: [install]
+    outputs:
+      has-changes-planned: ${{ steps.evaluate-plan.outputs.has-changes-planned }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: declastruct plan
+        id: plan
+        run: npx declastruct plan --wish ${{ inputs.wish-path }} --into ${{ inputs.wish-path }}.plan.json | tee ./plan.log
+        env:
+          GITHUB_TOKEN: ${{ secrets.github-token }} # allow specifying a github token to pass to the terraform command
+
+      - name: evaluate plan
+        id: evaluate-plan
+        run: |
+          # check whether it said there were required changes
+          if grep "Everything is in sync" ./plan.log
+          then
+            echo "has-changes-planned=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has-changes-planned=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: has changes planned?
+        run: echo "${{ steps.evaluate-plan.outputs.has-changes-planned }}"
+
+      - name: upload plan artifact
+        if: ${{ inputs.allow-apply == true && steps.evaluate-plan.outputs.has-changes-planned == 'true' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: declastruct-plan
+          path: |
+            ${{ inputs.wish-path }}.plan.json
+          retention-days: 1
+          include-hidden-files: false
+
+  apply:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.github-environment }}
+    needs: [install, plan]
+    if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: extract directory from wish-path
+        id: extract-dir
+        run: echo "wish-dir=$(dirname "${{ inputs.wish-path }}")" >> "$GITHUB_OUTPUT"
+
+      - name: download plan artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: declastruct-plan
+          path: ${{ steps.extract-dir.outputs.wish-dir }}
+
+      - name: declastruct apply
+        run: npx declastruct apply --plan ${{ inputs.wish-path }}.plan.json | tee ./apply.log
+        env:
+          GITHUB_TOKEN: ${{ secrets.github-token }} # allow specifying a github token to pass to the terraform command

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

@@ -0,0 +1,24 @@
+name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+jobs:
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github/declastruct.resources.ts
+      github-environment: prod
+    secrets:
+      github-token: ${{ secrets.PROVISION_GITHUB_GITHUB_TOKEN }}

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

@@ -5,8 +5,8 @@ on:
     tags:
       - v*
     branches:
-      - 'main'
-      - 'master'
+      - "main"
+      - "master"
   pull_request:
   workflow_dispatch:
 
@@ -21,7 +21,7 @@ jobs:
       working-directory: provision/aws/environments/test
       github-environment: dev
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.dev}'
+      aws-account-id: "@declapract{variable.awsAccountId.dev}"
     secrets:
       aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
@@ -32,7 +32,7 @@ jobs:
       working-directory: provision/aws/environments/dev
       github-environment: dev
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.dev}'
+      aws-account-id: "@declapract{variable.awsAccountId.dev}"
     secrets:
       aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
@@ -43,22 +43,18 @@ jobs:
       working-directory: provision/aws/environments/prod
       github-environment: prod
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.prod}'
+      aws-account-id: "@declapract{variable.awsAccountId.prod}"
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
     secrets:
       aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
 
   github:
-    uses: ./.github/workflows/.terraform.yml
+    uses: ./.github/workflows/.declastruct.yml
     with:
-      working-directory: provision/github/environment
+      wish-path: provision/github/declastruct.resources.ts
       github-environment: prod
-      aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.prod}'
     secrets:
-      aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
-      aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
       github-token: ${{ secrets.PROVISION_GITHUB_GITHUB_TOKEN }}
 
   sql-schema-dev:
@@ -67,7 +63,7 @@ jobs:
       stage: dev
       github-environment: dev
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.dev}'
+      aws-account-id: "@declapract{variable.awsAccountId.dev}"
     secrets:
       aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
@@ -79,7 +75,7 @@ jobs:
       stage: prod
       github-environment: prod
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.prod}'
+      aws-account-id: "@declapract{variable.awsAccountId.prod}"
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
     secrets:
       aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}

package/dist/practices/domain/best-practice/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "domain-objects": "@declapract{check.minVersion('0.25.7')}",
+    "domain-objects": "@declapract{check.minVersion('0.29.1')}",
     "joi": "@declapract{check.minVersion('17.4.0')}",
     "type-fns": "@declapract{check.minVersion('1.17.0')}"
   }

package/dist/practices/errors/best-practice/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "helpful-errors": "@declapract{check.minVersion('1.3.8')}"
+    "helpful-errors": "@declapract{check.minVersion('1.5.3')}"
   }
 }

package/dist/practices/lint/best-practice/.declapract.todo.md

@@ -0,0 +1,5 @@
+# todo
+
+replace with biome
+
+its faster and requires less deps

package/dist/practices/lint/best-practice/.eslintrc.js

@@ -6,6 +6,7 @@ module.exports = {
     'airbnb-typescript/base', // uses the airbnb recommended rules
     'plugin:prettier/recommended', // Enables eslint-plugin-prettier and displays prettier errors as ESLint errors. Make sure this is always the last configuration in the extends array.
   ],
+  plugins: ['unused-imports'],
   parserOptions: {
     project: './tsconfig.json',
     ecmaVersion: 2018, // Allows for the parsing of modern ECMAScript features
@@ -31,7 +32,26 @@ module.exports = {
       },
     ],
     '@typescript-eslint/no-explicit-any': 'error', // forbid any type for better type safety; you can use `never` or `unknown` instead when its truly unknown or never needed to be known
-    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/consistent-type-imports': [
+      'error',
+      {
+        prefer: 'type-imports', // enforce using `import type` for type-only imports
+        fixStyle: 'inline-type-imports', // use inline `import { type Foo }` style
+        disallowTypeAnnotations: true, // disallow using `import type` in type annotations
+      },
+    ],
+    'no-unused-vars': 'off', // turn off base rule as it can report incorrect errors
+    '@typescript-eslint/no-unused-vars': 'off', // turn off in favor of unused-imports/no-unused-vars
+    'unused-imports/no-unused-imports': 'error', // auto-fixable rule to remove unused imports
+    'unused-imports/no-unused-vars': [
+      'warn',
+      {
+        vars: 'all',
+        varsIgnorePattern: '^_',
+        args: 'after-used',
+        argsIgnorePattern: '^_',
+      },
+    ],
     'import/no-cycle': 'off',
     'max-classes-per-file': 'off',
     '@typescript-eslint/no-use-before-define': 'off',

package/dist/practices/lint/best-practice/package.json

@@ -7,6 +7,7 @@
     "eslint-config-prettier": "8.5.0",
     "eslint-plugin-import": "2.26.0",
     "eslint-plugin-prettier": "4.2.1",
+    "eslint-plugin-unused-imports": "4.1.4",
     "depcheck": "1.4.3"
   },
   "scripts": {

package/dist/practices/{terraform-github/best-practice → provision-github/bad-practices/terraform-github}/provision/github/environment/main.tf

@@ -5,7 +5,7 @@ provider "github" {
 
 terraform {
   backend "s3" {
-    bucket  = "terraform-state-@declapract{variable.infrastructureNamespaceId}-prod" # tracked in the prod aws account's s3 bucket, so `use.@declapract{variable.organizationName}.prod`
+    bucket  = "terraform-state-xdeclapract{variable.infrastructureNamespaceId}-prod" # tracked in the prod aws account's s3 bucket, so `use.@declapract{variable.organizationName}.prod`
     key     = "@declapract{variable.projectName}-github"
     region  = "us-east-1"
     encrypt = true

package/dist/practices/provision-github/best-practice/package.json

@@ -0,0 +1,6 @@
+{
+  "devDependencies": {
+    "declastruct": "@declapract{check.minVersion('1.1.7')}",
+    "declastruct-github": "@declapract{check.minVersion('1.1.1')}"
+  }
+}

package/dist/practices/provision-github/best-practice/package.json.declapract.ts

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

package/dist/practices/provision-github/best-practice/provision/github/declastruct.resources.ts

@@ -0,0 +1,124 @@
+import { DeclastructProvider } from 'declastruct';
+import {
+  DeclaredGithubBranch,
+  DeclaredGithubBranchProtection,
+  DeclaredGithubRepo,
+  DeclaredGithubRepoConfig,
+  getDeclastructGithubProvider,
+} from 'declastruct-github';
+import { DomainEntity, RefByUnique } from 'domain-objects';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import pkg from '../../package.json';
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  getDeclastructGithubProvider(
+    {
+      credentials: {
+        token:
+          process.env.GITHUB_TOKEN ??
+          UnexpectedCodePathError.throw('github token not supplied'),
+      },
+    },
+    {
+      log: {
+        info: () => {},
+        debug: () => {},
+        warn: console.warn,
+        error: console.error,
+      },
+    },
+  ),
+];
+
+export const getResources = async (): Promise<DomainEntity<any>[]> => {
+  // declare the repo
+  const repo = DeclaredGithubRepo.as({
+    owner: '@declapract{variable.organizationName}',
+    name: '@declapract{variable.projectName}',
+    description: (pkg as any).description ?? null,
+    visibility: (pkg as any).private === true ? 'private' : 'public',
+    private: (pkg as any).private ?? false, // todo: why do we have to specify this twice?
+    homepage: (pkg as any).homepage ?? null,
+
+    // things we haven't changed from the defaults
+    archived: false,
+  });
+
+  // ref the main branch
+  const branchMain = RefByUnique.as<typeof DeclaredGithubBranch>({
+    name: 'main',
+    repo,
+  });
+
+  // declare config for the repo
+  const repoConfig = DeclaredGithubRepoConfig.as({
+    repo,
+
+    // explicitly set the main branch
+    defaultBranch: branchMain.name,
+
+    // we only use issues; the rest is noise today
+    hasIssues: true,
+    hasProjects: false,
+    hasWiki: false,
+    hasDownloads: false,
+    isTemplate: false,
+
+    // only squash merges are allowed
+    allowSquashMerge: true,
+    allowMergeCommit: false, // but especially not merge merges. never merge merges
+    allowRebaseMerge: false,
+
+    // allow nice to haves for pulls
+    allowAutoMerge: true,
+    allowUpdateBranch: true,
+
+    // always cleanup after yourself
+    deleteBranchOnMerge: true,
+
+    // configure messages
+    mergeCommitMessage: 'PR_TITLE',
+    mergeCommitTitle: 'MERGE_MESSAGE',
+    squashMergeCommitMessage: 'COMMIT_MESSAGES',
+    squashMergeCommitTitle: 'COMMIT_OR_PR_TITLE',
+    webCommitSignoffRequired: false,
+  });
+
+  // declare protection for that branch, too
+  const branchMainProtection = DeclaredGithubBranchProtection.as({
+    branch: branchMain,
+
+    enforceAdmins: true, // yes, even admins need to follow this (note: they can still take the time to go and change the settings temporarily for the exceptions)
+    allowsDeletions: false, // dont allow the `main` branch to be deleted
+    allowsForcePushes: false, // dont allow `main` branch to be force pushed to
+    requireLinearHistory: false, //  # no ugly merge commits, woo! 🎉
+
+    requiredStatusChecks: {
+      strict: true, // branch must be up to date. otherwise, we dont know if it will really pass once it is merged
+      contexts: [
+        'suite / install / npm',
+        'suite / test-commits',
+        'suite / test-types',
+        'suite / test-format',
+        'suite / test-lint',
+        'suite / test-unit',
+        'suite / test-integration',
+        'suite / test-acceptance-locally',
+        'pullreq-title', // "review / pullreq-title",
+      ],
+    },
+
+    // things we haven't changed from the defaults
+    allowForkSyncing: false,
+    blockCreations: false,
+    lockBranch: false,
+    requiredConversationResolution: false,
+    requiredPullRequestReviews: null,
+    requiredSignatures: false,
+    restrictions: null,
+  });
+
+  // and return the full set
+  return [repo, repoConfig, branchMainProtection];
+};

package/dist/practices/tests/best-practice/jest.acceptance.config.ts

@@ -22,6 +22,9 @@ const config: Config = {
   testMatch: ['**/*.acceptance.test.ts'],
   setupFiles: ['core-js'],
   setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
 };
 
 // eslint-disable-next-line import/no-default-export

package/dist/practices/tests/best-practice/jest.acceptance.env.ts

@@ -1,13 +1,34 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import util from 'util';
+
 // eslint-disable-next-line no-undef
 jest.setTimeout(90000); // we're calling downstream apis
 
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+/**
+ * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
+ */
+if (!existsSync(join(process.cwd(), 'package.json')))
+  throw new Error('no package.json found in cwd. are you @gitroot?');
+
 /**
- * .what = verify that the env has sufficient auth to run the tests; otherwise, fail fast
+ * .what = verify that the env has sufficient auth to run the tests if aws is used; otherwise, fail fast
  * .why =
  *   - prevent time wasted waiting on tests to fail due to lack of credentials
  *   - prevent time wasted debugging tests which are failing due to hard-to-read missed credential errors
  */
-if (!(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID))
+const declapractUsePath = join(process.cwd(), 'declapract.use.ts');
+const requiresAwsAuth =
+  existsSync(declapractUsePath) &&
+  readFileSync(declapractUsePath, 'utf8').includes('awsAccountId');
+if (
+  requiresAwsAuth &&
+  !(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID)
+)
   throw new Error(
     'no aws credentials present. please authenticate with aws to run acceptance tests',
   );

package/dist/practices/tests/best-practice/jest.integration.config.ts

@@ -22,6 +22,9 @@ const config: Config = {
   testMatch: ['**/*.integration.test.ts'],
   setupFiles: ['core-js'],
   setupFilesAfterEnv: ['./jest.integration.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
 };
 
 // eslint-disable-next-line import/no-default-export

package/dist/practices/tests/best-practice/jest.integration.env.ts

@@ -1,6 +1,20 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import util from 'util';
+
 // eslint-disable-next-line no-undef
 jest.setTimeout(90000); // since we're calling downstream apis
 
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+/**
+ * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
+ */
+if (!existsSync(join(process.cwd(), 'package.json')))
+  throw new Error('no package.json found in cwd. are you @gitroot?');
+
 /**
  * sanity check that unit tests are only run the 'test' environment
  *
@@ -15,12 +29,19 @@ if (
   throw new Error(`integration.test is not targeting stage 'test'`);
 
 /**
- * .what = verify that the env has sufficient auth to run the tests; otherwise, fail fast
+ * .what = verify that the env has sufficient auth to run the tests if aws is used; otherwise, fail fast
  * .why =
  *   - prevent time wasted waiting on tests to fail due to lack of credentials
  *   - prevent time wasted debugging tests which are failing due to hard-to-read missed credential errors
  */
-if (!(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID))
+const declapractUsePath = join(process.cwd(), 'declapract.use.ts');
+const requiresAwsAuth =
+  existsSync(declapractUsePath) &&
+  readFileSync(declapractUsePath, 'utf8').includes('awsAccountId');
+if (
+  requiresAwsAuth &&
+  !(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID)
+)
   throw new Error(
     'no aws credentials present. please authenticate with aws to run integration tests',
   );

package/dist/practices/tests/best-practice/jest.unit.config.ts

@@ -27,6 +27,9 @@ const config: Config = {
   ],
   setupFiles: ['core-js'],
   setupFilesAfterEnv: ['./jest.unit.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
 };
 
 // eslint-disable-next-line import/no-default-export

package/dist/practices/tests/best-practice/jest.unit.env.ts

@@ -1,7 +1,22 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import util from 'util';
+
+// mock that getConfig just returns plaintext test env config in unit tests
 jest.mock('./src/utils/config/getConfig', () => ({
-  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')), // mock that getConfig just returns plaintext test env config in unit tests
+  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')),
 }));
 
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+/**
+ * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
+ */
+if (!existsSync(join(process.cwd(), 'package.json')))
+  throw new Error('no package.json found in cwd. are you @gitroot?');
+
 /**
  * sanity check that unit tests are only run the 'test' environment
  *

package/dist/practices/tests/best-practice/jest.unit.env.ts.declapract.ts

@@ -15,8 +15,9 @@ export const contents: FileContentsFunction = async (context) => {
   let contents = contentsSuperset;
   if (!context.projectPractices.includes('config'))
     contents = contents.replace(
-      `jest.mock('./src/utils/config/getConfig', () => ({
-  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')), // mock that getConfig just returns plaintext test env config in unit tests
+      `// mock that getConfig just returns plaintext test env config in unit tests
+jest.mock('./src/utils/config/getConfig', () => ({
+  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')),
 }));
 
 `,

package/dist/practices/tests/best-practice/package.json

@@ -3,7 +3,7 @@
     "@types/jest": "@declapract{check.minVersion('29.2.4')}",
     "jest": "@declapract{check.minVersion('29.3.1')}",
     "test-fns": "@declapract{check.minVersion('1.4.2')}",
-    "ts-jest": "@declapract{check.minVersion('29.1.3')}",
+    "ts-jest": "@declapract{check.minVersion('29.4.5')}",
     "ts-node": "@declapract{check.minVersion('10.9.2')}",
     "core-js": "@declapract{check.minVersion('3.26.1')}",
     "@babel/core": "@declapract{check.minVersion('7.28.5')}",

package/dist/useCases.yml

@@ -23,6 +23,7 @@ use-cases:
     practices:
       - cicd-package
       - node-package
+      - provision-github
   lambda-service:
     extends:
       - typescript-project
@@ -40,8 +41,8 @@ use-cases:
       - node-service
       - runtime-type-checking
       - serverless
+      - provision-github
       - terraform-common
-      - terraform-github
       - terraform-aws
       - tests-service
       - uuid
@@ -70,7 +71,7 @@ use-cases:
       - package-json-order
       - prettier
       - terraform-common
-      - terraform-github
+      - provision-github
       - lint
       - lint-react
       - lint-react-native

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.39.18",
+  "version": "0.40.0",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -41,7 +41,7 @@
     "prepare:husky": "npx husky install && chmod ug+x .husky/*"
   },
   "dependencies": {
-    "domain-objects": "0.22.1",
+    "domain-objects": "0.29.2",
     "expect": "29.4.2",
     "flat": "5.0.2",
     "helpful-errors": "1.3.8",
@@ -68,12 +68,12 @@
     "eslint-config-prettier": "8.5.0",
     "eslint-plugin-import": "2.26.0",
     "eslint-plugin-prettier": "4.2.1",
+    "eslint-plugin-unused-imports": "4.3.0",
     "husky": "8.0.3",
     "jest": "29.3.1",
     "prettier": "2.8.1",
     "test-fns": "1.4.2",
     "ts-jest": "29.1.3",
-    "ts-node": "10.9.2",
     "type-fns": "0.8.1",
     "typescript": "5.4.5",
     "visualogic": "1.2.3"

package/readme.md

@@ -1,39 +1,150 @@
 # declapract-typescript-ehmpathy
 
-declapract = declared best practices
+Declared best practices for TypeScript projects.
 
-this repo contains the [ehmpathy org's](https://github.com/ehmpathy) declared best practices for typescript, for usage with [declapract](https://github.com/ehmpathy/declapract)
+Sync your projects with the latest and greatest best practices with codemods powered by [declapract](https://github.com/ehmpathy/declapract).
 
-# usage
+## What is this?
+
+This package contains battle-tested TypeScript best practices from the [ehmpathy org](https://github.com/ehmpathy), packaged for automated enforcement via codemods through [declapract](https://github.com/ehmpathy/declapract).
+
+Instead of adhoc configuration of linters, formatters, test frameworks, cicd pipelines, and infrastructure for every project, this package provides:
+
+- **40+ declared practices** covering TypeScript development, testing, CI/CD, AWS infrastructure, and more
+- **Automated checking** to verify your repo follows best practices - and avoids bad practices
+- **Automatic fixes** for most common issues
+- **Project templates** to bootstrap new projects with everything configured
+
+## How to use it?
+
+### 1. Install declapract
 
-1. add `declapract` to your repo
 ```sh
 npm install --save-dev declapract
 ```
 
-2. add a declapract usage config to your repo
+### 2. Configure your project
+
+Create `declapract.use.yml` in your repo:
+
 ```yml
-# declapract.use.yml
 declarations: npm:declapract-typescript-ehmpathy
-useCase: lambda-service # specify which use case your repo is following, see `declapract-typescript-ehmpathy:src/useCases.yml` for options
-variables: # specify the values of the variables to use against checks
-  organizationName: 'awesome-org'
-  projectName: 'svc-awesome-thing'
-  infrastructureNamespaceId: 'abcde12345'
-  slackReleaseWebHook: 'https://...'
+useCase: typescript-project # Choose from: typescript-project, npm-package, lambda-service, lambda-service-with-rds, lambda-service-with-dynamodb, app-react-native-expo
+variables:
+  organizationName: 'my-org'
+  projectName: 'my-project'
+  infrastructureNamespaceId: 'prod-abc123'
+  slackReleaseWebHook: 'https://hooks.slack.com/...'
 ```
 
-3. clone a declared best practices example, do bootstrap a new repo
+### 3. Plan changes
+
 ```sh
-declapract clone lambda-service-with-rds # bootstrap a new lambda-service-with-rds repo
-```
+# plan all practices
+declapract plan
 
-4. check that your repo is conforming to best practices
-```
-declapract check
+# or scope to one
+declapract plan --practice
 ```
 
-5. fix a specific practice that your repo is failing to conform to (if it has an automatic fix declared)
+### 4. Apply changes
+
 ```sh
-declapract fix --practice dates-and-times # e.g., apply a fix for the the dates-and-times practice
+# apply all practices
+declapract apply
+
+# or scope to one
+declapract apply --practice
 ```
+
+## Benefits
+
+### Consistency
+All projects follow the same patterns, making it easy to switch between codebases
+
+### Quality
+Enforced best practices catch issues before code review
+
+### Speed
+Bootstrap new projects in minutes instead of hours
+
+### Maintenance
+Update best practices across all repos by updating one dependency
+
+### Documentation
+Practices are explicitly declared and versioned, serving as living documentation
+
+## What use cases are supported?
+
+This package defines complete sets of practices for common project types:
+
+### `typescript-project`
+Base configuration for any TypeScript project (18 core practices)
+
+### `npm-package`
+TypeScript packages published to npm (adds CI/CD for publishing)
+
+### `lambda-service`
+AWS Lambda microservices (adds AWS infrastructure, handlers, config, logging)
+
+### `lambda-service-with-rds`
+Lambda services with PostgreSQL database (adds RDS provisioning and DAOs)
+
+### `lambda-service-with-dynamodb`
+Lambda services with DynamoDB (adds DynamoDB DAOs)
+
+### `app-react-native-expo`
+React Native mobile apps with Expo
+
+## What practices are included?
+
+### Core TypeScript Development
+- **typescript** - Strict TypeScript configuration
+- **lint** - ESLint with TypeScript rules (airbnb-typescript)
+- **format** - Prettier configuration
+- **domain** - Domain-driven design with `domain-objects`
+- **directory-structure-src** - Consistent project structures
+- **runtime-type-checking** - Type-safe validation with `domain-objects`
+- **errors** - Structured error handling with `helpful-errors`
+- etc
+
+### Tests & Quality
+- **tests** - Jest configuration for unit, integration, and acceptance tests
+- **conventional-commits** - Enforced commit message standards
+- **husky** - Git hooks for pre-commit validation
+- etc
+
+### CI/CD
+- **cicd-common** - GitHub Actions workflows for testing
+- **cicd-package** - Publishing workflows for npm packages
+- **cicd-service** - Deployment workflows for services
+
+### AWS Lambda Services
+- **lambda-handlers** - Standard Lambda function structure
+- **lambda-clients** - Type-safe Lambda client wrappers
+- **config** - Environment configuration with AWS Parameter Store
+- **logs** - Structured logging with `simple-log-methods`
+- **uuid** - UUID generation standards
+- etc
+
+### Infrastructure
+- **terraform-common** - Common Terraform patterns
+- **terraform-aws** - AWS-specific Terraform modules
+- **declastruct-github** - GitHub repository configuration
+- **environments-aws** - Multi-environment setup (dev/test/prod)
+- etc
+
+### Persistence
+- **persist-with-rds** - PostgreSQL with `sql-dao-generator`
+- **persist-with-dynamodb** - DynamoDB DAO patterns
+
+### React Native
+- **app-react-native-expo** - Expo app configuration
+- **lint-react** - React-specific linting
+- **lint-react-native** - React Native linting
+
+## Learn more
+
+- [declapract documentation](https://github.com/ehmpathy/declapract)
+- [full list of practices](./src/practices)
+- [full list of usecases](./src/useCases.yml)