declapract-typescript-ehmpathy 0.39.18 → 0.41.0

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,8 +3,8 @@
     "@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-node": "@declapract{check.minVersion('10.9.2')}",
+    "ts-jest": "@declapract{check.minVersion('29.4.5')}",
+    "tsx": "@declapract{check.minVersion('4.20.6')}",
     "core-js": "@declapract{check.minVersion('3.26.1')}",
     "@babel/core": "@declapract{check.minVersion('7.28.5')}",
     "@babel/preset-env": "@declapract{check.minVersion('7.28.5')}",

package/dist/practices/typescript/best-practice/tsconfig.build.json

@@ -4,13 +4,14 @@
     "rootDir": "src"
   },
   "include": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "nontyped_modules/**/*.d.ts"
   ],
   "exclude": [
-    "**/*.test.(ts|js)", // all explicitly .test files are dev only assets too
-    "**/.test/**/*.(ts|js)",
-    "src/**/.scratch/**/*.(ts|js)",
-    "src/**/__test_utils__/**/*.(ts|js)",
-    "src/**/__test_assets__/**/*.(ts|js)"
+    "**/*.test.ts", // all explicitly .test files are dev only assets too
+    "**/*.test.js",
+    "**/.test/**/*",
+    "**/.scratch/**/*",
+    "**/__test*__/**/*" // todo: deprecate this pattern in favor of .test
   ]
 }

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.41.0",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -41,10 +41,10 @@
     "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",
+    "helpful-errors": "1.5.3",
     "simple-log-methods": "0.5.0"
   },
   "peerDependencies": {
@@ -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)