declapract-typescript-ehmpathy 0.17.0

package/dist/practices/testing/bad-practices/old-acceptance-test-utils-3/acceptance/_utils/environment.ts.declapract.ts

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

package/dist/practices/testing/bad-practices/old-acceptance-test-utils-3/acceptance/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,18 @@
+import { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes(`import { locally } from '../_utils/environment';`))
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  return {
+    contents: contents.replace(
+      // replace the bad import
+      `import { locally } from '../_utils/environment';`,
+      `import { locally } from '../environment';`,
+    ),
+  };
+};

package/dist/practices/testing/bad-practices/old-extension-pattern/.declapract.readme.md

@@ -0,0 +1,3 @@
+a previous, now deprecated, best practice was to have the extension of `*.test.integration.ts` or `*.test.acceptance.ts` on test files
+
+we've since moved over to `*.integration.test.ts` and `*.acceptance.test.ts` (it having the `.test.ts` extension still makes tools that dont expect different test types work with these test files out of the box, which is a nice to have)

package/dist/practices/testing/bad-practices/old-extension-pattern/<star><star>/<star>.test.acceptance.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.acceptance\.ts$/,
+    '.acceptance.test.ts',
+  ),
+  contents,
+});

package/dist/practices/testing/bad-practices/old-extension-pattern/<star><star>/<star>.test.integration.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.integration\.ts$/,
+    '.integration.test.ts',
+  ),
+  contents,
+});

package/dist/practices/testing/best-practice/.declapract.readme.md

@@ -0,0 +1,45 @@
+# best practices for testing
+
+## purpose of testing:
+- think use cases, edge cases, and play with the business logic / model you've defined
+- define use cases, edge cases, and previous failure points explicitly for future reference
+- automate checking that:
+  - code complies with spec (i.e., all use cases and requirements are satisfied)
+  - regressions will not occur
+  - predicted error cases are covered
+
+## three test types:
+- unit tests
+  - test precisely scoped business logic, mocking out all dependencies
+  - purpose is to test that the unit/function of logic that you're defining does the logic in it correctly
+- integration tests
+  - test end to end logic OR test boundaries between calling a dependent service
+  - for example:
+    - test boundaries with a dependent api
+      - test that we are communicating w/ database correctly
+      - test that we are
+    - test end to end logic
+      - test that a handler acts correctly in different cases
+      - test that a highly composed business logic function produces the correct results in all cases
+- acceptance tests
+  - test that the deployed product works
+  - ideally: test an end to end pipeline of each use case it needs to support
+    - note: typically its sufficient to trust that integration tests have already tested the use cases and then all we need to test is that the lambda can be hit
+
+// todo: add examples to the above
+// todo: finesse the above definitions now that we're formally defining them
+
+## pattern
+
+- each test type gets its own file extension
+  - unit -> `.test.ts` (the default extension)
+  - integration -> `.integration.test.ts`
+  - acceptance -> `.acceptance.test.ts`
+- each test type gets its own config (e.g., specify what extension to use)
+  - `jest.unit.config`
+  - `jest.integration.config`
+  - `jest.acceptance.config`
+- each test type gets its own environment setup file (e.g., global mocks, or checks, etc)
+  - `jest.unit.env`
+  - `jest.integration.env`
+  - `jest.acceptance.env`

package/dist/practices/testing/best-practice/acceptance/<star><star>/<star>.acceptance.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should be atleast one acceptance test

package/dist/practices/testing/best-practice/acceptance/environment.ts

@@ -0,0 +1,5 @@
+import { Stage, stage } from '../src/utils/environment';
+
+export const locally = process.env.LOCALLY === 'true'; // whether we want to acceptance test locally or deployed lambda
+
+export const testInProdOnly = stage === Stage.PRODUCTION ? test : test.skip; // allow testing in prod env only (sometimes we don't deploy certain things in dev / test)

package/dist/practices/testing/best-practice/acceptance/lambdas/<star>.acceptance.test.ts.declapract.ts

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import { FileCheckFunction } from 'declapract';
+import expect from 'expect';
+
+import { defineFunctionNameFromTestFileName } from '../../../defineFunctionNameFromTestFileName';
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents)
+    throw new Error('expected at least one lambda acceptance test');
+
+  // check that each import was found
+  const expectedImports = [
+    "import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';",
+    "import { stage } from '../../src/utils/environment';",
+    "import { locally } from '../environment';",
+  ];
+  const missedImports = expectedImports.filter(
+    (expectedImport) => !contents.includes(expectedImport),
+  );
+  if (missedImports.length)
+    throw new Error(
+      `
+${chalk.green(`- Expected imports ${['', ...expectedImports].join('\n  - ')}`)}
+      `.trim(),
+    );
+
+  const expectedTestName = defineFunctionNameFromTestFileName({ context });
+  const expectedDescribe = `
+describe('${expectedTestName}', () => {
+  `.trim();
+  expect(contents).toContain(expectedDescribe);
+};

package/dist/practices/testing/best-practice/jest.acceptance.config.js

@@ -0,0 +1,15 @@
+// https://jestjs.io/docs/en/configuration.html
+module.exports = {
+  preset: 'ts-jest',
+  globals: {
+    'ts-jest': {
+      tsconfig: 'tsconfig.json',
+    },
+  },
+  verbose: true,
+  testEnvironment: 'node',
+  moduleFileExtensions: ['js', 'ts'],
+  testMatch: ['**/*.acceptance.test.ts'],
+  setupFiles: ['core-js'],
+  setupFilesAfterEnv: ['./jest.acceptance.env.js'],
+};

package/dist/practices/testing/best-practice/jest.acceptance.env.js

@@ -0,0 +1,2 @@
+// eslint-disable-next-line no-undef
+jest.setTimeout(90000); // we're calling downstream apis

package/dist/practices/testing/best-practice/jest.config.js

@@ -0,0 +1 @@
+module.exports = require('./jest.unit.config'); // default to unit tests

package/dist/practices/testing/best-practice/jest.integration.config.js

@@ -0,0 +1,10 @@
+// https://jestjs.io/docs/en/configuration.html
+module.exports = {
+  preset: 'ts-jest',
+  verbose: true,
+  testEnvironment: 'node',
+  moduleFileExtensions: ['js', 'ts'],
+  testMatch: ['**/*.integration.test.ts'],
+  setupFiles: ['core-js'],
+  setupFilesAfterEnv: ['./jest.integration.env.js'],
+};

package/dist/practices/testing/best-practice/jest.integration.env.js

@@ -0,0 +1,13 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { stage, Stage } = require('./src/utils/environment');
+
+/**
+ * sanity check that integration tests are only run in 'test' environment
+ * - if they are run in prod environment, we could load a bunch of junk data into our prod databases, which would be no bueno
+ */
+if (stage !== Stage.TEST && process.env.I_KNOW_WHAT_IM_DOING !== 'true')
+  throw new Error(`integration-test is not targeting stage 'test'`);
+
+// set a longer timeout
+// eslint-disable-next-line no-undef
+jest.setTimeout(90000); // since we're calling downstream apis

package/dist/practices/testing/best-practice/jest.unit.config.js

@@ -0,0 +1,15 @@
+// https://jestjs.io/docs/en/configuration.html
+module.exports = {
+  preset: 'ts-jest',
+  verbose: true,
+  testEnvironment: 'node',
+  moduleFileExtensions: ['js', 'ts'],
+  testMatch: [
+    // note: order matters
+    '**/*.test.ts',
+    '!**/*.acceptance.test.ts',
+    '!**/*.integration.test.ts',
+  ],
+  setupFiles: ['core-js'],
+  setupFilesAfterEnv: ['./jest.unit.env.js'],
+};

package/dist/practices/testing/best-practice/jest.unit.env.js

@@ -0,0 +1,16 @@
+/* eslint-disable global-require */
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { stage, Stage } = require('./src/utils/environment');
+
+// eslint-disable-next-line no-undef
+jest.mock('./src/utils/config/getConfig', () => ({
+  // eslint-disable-next-line no-undef
+  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')), // mock that getConfig just returns plaintext test env config in unit tests
+}));
+
+/**
+ * sanity check that unit tests are only run in 'test' environment
+ * - if they are run in prod environment, we could load a bunch of junk data into our prod databases, which would be no bueno
+ */
+if (stage !== Stage.TEST && process.env.I_KNOW_WHAT_IM_DOING !== 'true')
+  throw new Error(`unit-test is not targeting stage 'test'`);

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

@@ -0,0 +1,16 @@
+{
+  "devDependencies": {
+    "@types/jest": "@declapract{check.minVersion('29.2.4')}",
+    "jest": "@declapract{check.minVersion('29.3.1')}",
+    "ts-jest": "@declapract{check.minVersion('29.0.3')}",
+    "core-js": "@declapract{check.minVersion('3.26.1')}",
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.2.1')}"
+  },
+  "scripts": {
+    "test:unit": "jest -c ./jest.unit.config.js --forceExit --coverage --verbose --passWithNoTests",
+    "test:integration": "jest -c ./jest.integration.config.js --forceExit --coverage --verbose --passWithNoTests",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.js --forceExit --verbose --runInBand",
+    "test": "npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.js --forceExit --verbose --runInBand"
+  }
+}

package/dist/practices/testing/best-practice/package.json.declapract.ts

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

package/dist/practices/testing/best-practice/src/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/practices/testing/best-practice/src/<star><star>/<star>.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/practices/testing/best-practice/src/utils/environment.ts

@@ -0,0 +1,3 @@
+// this is a placeholder file, so that the declared acceptance test file passes typescript type checking. for this practice, we only check that the file exists
+export const stage = 'placeholder' as any;
+export const Stage = 'placeholder' as any;

package/dist/practices/testing/best-practice/src/utils/environment.ts.declapract.ts

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

package/dist/practices/testing/defineFunctionNameFromTestFileName.ts

@@ -0,0 +1,11 @@
+import { FileCheckContext } from 'declapract';
+
+export const defineFunctionNameFromTestFileName = ({
+  context,
+}: {
+  context: FileCheckContext;
+}): string =>
+  context.relativeFilePath // same name as the file
+    .split('/')
+    .slice(-1)[0]!
+    .replace('.acceptance.test.ts', ''); // remove the extension from the file

package/dist/practices/typescript/best-practice/.declapract.readme.md

@@ -0,0 +1,10 @@
+this bundle defines best practices for tsconfig
+
+namely:
+- build vs test config
+- default name as test config, so that ide's automatically typecheck test files for you
+  - otherwise, they exclude them, and you only find ts errors _after_ you run tsc - not while looking at file
+- strict
+  - strict mode on tsc prevents a _ton_ of errors
+  - without it, `Type | null` -> `Type` -> so you have a bunch of bugs whenever a value could be null but you dont expect it to be / realize it could be
+    - it defeats the point of typechecking, really

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

@@ -0,0 +1,12 @@
+{
+  "devDependencies": {
+    "typescript": "@declapract{check.minVersion('4.9.4')}",
+    "@tsconfig/node-lts-strictest": "@declapract{check.minVersion('18.12.1')}"
+  },
+  "scripts": {
+    "build:clean": "rm dist/ -rf",
+    "build:compile": "tsc -p ./tsconfig.build.json",
+    "build": "npm run build:clean && npm run build:compile",
+    "test:types": "tsc -p ./tsconfig.build.json --noEmit"
+  }
+}

package/dist/practices/typescript/best-practice/package.json.declapract.ts

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

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

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "exclude": [
+    "dist",
+    "coverage",
+    "node_modules",
+    "acceptance",
+    "provision",
+    "jest.*",
+    "prettier.*",
+    "commitlint.*",
+    "src/**/*.test.(ts|js)"
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "extends": "@tsconfig/node-lts-strictest/tsconfig.json",
+  "compilerOptions": {
+    "importsNotUsedAsValues": "remove",
+    "noPropertyAccessFromIndexSignature": false,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "outDir": "dist",
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "dist",
+    "coverage",
+    "node_modules",
+  ]
+}

package/dist/practices/uuid/bad-practices/npm-uuidv4/.declapract.readme.md

@@ -0,0 +1 @@
+`uuidv4` has been deprecated in favor of `uuid` per maintainers

package/dist/practices/uuid/bad-practices/npm-uuidv4/package.json.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  const packageJSONObject = JSON.parse(contents!);
+  if (Object.keys(packageJSONObject.dependencies).includes('uuidv4')) 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, uuidv4: undefined },
+  };
+  return { contents: JSON.stringify(fixedPackageJSONObject, null, 2) };
+};

package/dist/practices/uuid/best-practice/.declapract.readme.md

@@ -0,0 +1 @@
+industry standard; the community has converged on it

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

@@ -0,0 +1,8 @@
+{
+  "dependencies": {
+    "uuid": "@declapract{check.minVersion('8.3.4')}"
+  },
+  "devDependencies": {
+    "@types/uuid": "@declapract{check.minVersion('8.3.4')}"
+  }
+}

package/dist/practices/uuid/best-practice/package.json.declapract.ts

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

package/dist/useCases.yml

@@ -0,0 +1,48 @@
+# define the different types of combinations of the best practices that we support
+use-cases:
+  typescript-project:
+    practices:
+      - cicd-integrate
+      - conventional-commits
+      - directory-structure-src
+      - domain
+      - errors
+      - format
+      - git
+      - linting
+      - node
+      - nonpublished-modules
+      - package-json-order
+      - prettier
+      - testing
+      - typescript
+      - uuid
+  npm-package:
+    extends:
+      - typescript-project
+    practices:
+      - cicd-deploy-package
+  lambda-service:
+    extends:
+      - typescript-project
+    practices:
+      - cicd-deploy-service
+      - config
+      - dates-and-times
+      - environments
+      - lambda-clients
+      - lambda-handlers
+      - logging
+      - runtime-type-checking
+      - serverless
+      - terraform
+  lambda-service-with-rds:
+    extends:
+      - lambda-service
+    practices:
+      - persist-with-rds
+  lambda-service-with-dynamodb: # note that projects can still use both by specifying the `declapract.use-case: [lambda-service-with-dynamodb, lambda-service-with-rds]` since we allow use-cases to add together. `use-cases` just enable us to enforce a "minimum" set of practices
+    extends:
+      - lambda-service
+    practices:
+      - persist-with-dynamodb

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "declapract-typescript-ehmpathy",
+  "version": "0.17.0",
+  "description": "declapract best practices declarations for typescript",
+  "main": "src/index.js",
+  "repository": "ehmpathy/declapract-typescript-ehmpathy",
+  "homepage": "https://github.com/ehmpathy/declapract-typescript-ehmpathy",
+  "files": [
+    "/dist",
+    "/declapract.declare.yml"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && npx declapract compile",
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "fix:format:terraform": "terraform fmt -recursive",
+    "fix:format": "npm run fix:format:prettier && npm run fix:format:terraform",
+    "test:types": "tsc -p ./tsconfig.build.json --noEmit",
+    "test:format": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js",
+    "test:lint": "echo 'todo'",
+    "test:unit": "jest -c ./jest.unit.config.js --forceExit --coverage --verbose --passWithNoTests",
+    "test:integration": "echo 'no op'",
+    "test:validate": "npm run build && npx declapract validate",
+    "test": "npm run test:types && npm run test:format && npm run test:validate && npm run test:unit",
+    "prepush": "npm run build && npm run test",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js",
+    "commit:with-cli": "npx cz",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose"
+  },
+  "author": "uladkasach",
+  "license": "ISC",
+  "dependencies": {
+    "@middy/core": "1.0.0",
+    "@types/yesql": "3.2.2",
+    "aws-lambda": "1.0.5",
+    "aws-sdk": "2.658.0",
+    "axios": "0.21.1",
+    "change-case": "4.1.2",
+    "config-with-paramstore": "1.1.1",
+    "date-fns": "2.14.0",
+    "declapract": "0.10.0",
+    "domain-objects": "0.7.5",
+    "expect": "27.1.1",
+    "flat": "5.0.2",
+    "joi": "17.4.0",
+    "lodash.uniq": "4.5.0",
+    "middy": "0.33.2",
+    "pg": "8.2.1",
+    "simple-dynamodb-client": "^0.7.1",
+    "simple-lambda-client": "2.1.3",
+    "simple-lambda-handlers": "0.5.0",
+    "simple-leveled-log-methods": "0.2.1",
+    "simple-type-guards": "0.1.3",
+    "uuid": "3.4.0",
+    "yesql": "4.1.3"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "2.0.4",
+    "@tsconfig/node-lts-strictest": "18.12.1",
+    "@types/aws-lambda": "8.10.40",
+    "@types/flat": "5.0.2",
+    "@types/jest": "29.2.4",
+    "@types/joi": "14.3.4",
+    "@types/lodash.uniq": "4.5.6",
+    "@types/pg": "7.14.3",
+    "@types/shelljs": "0.8.6",
+    "@types/uuid": "3.4.7",
+    "@typescript-eslint/eslint-plugin": "5.46.1",
+    "@typescript-eslint/parser": "5.46.1",
+    "core-js": "3.26.1",
+    "eslint": "8.30.0",
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-config-airbnb-typescript": "17.0.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "jest": "29.3.1",
+    "prettier": "2.8.1",
+    "serverless": "1.66.0",
+    "serverless-offline": "5.12.1",
+    "serverless-pseudo-parameters": "2.5.0",
+    "shelljs": "0.8.3",
+    "simple-lambda-testing-methods": "0.1.1",
+    "sql-code-generator": "0.8.2",
+    "sql-dao-generator": "0.2.0",
+    "sql-schema-control": "0.7.3",
+    "sql-schema-generator": "0.21.1",
+    "ts-jest": "29.0.3",
+    "typescript": "4.9.4",
+    "@commitlint/cli": "13.1.0",
+    "@commitlint/config-conventional": "13.1.0",
+    "cz-conventional-changelog": "3.3.0",
+    "husky": "7.0.2"
+  }
+}

package/readme.md

@@ -0,0 +1,39 @@
+# declapract-typescript-ehmpathy
+
+declapract = declared best practices
+
+this repo contains the [ehmpathy org's](github.com/ehmpathy) declared best practices for typescript, for usage with [declapract](https://github.com/ehmpathy/declapract)
+
+# usage
+
+1. add `declapract` to your repo
+```sh
+npm install --save-dev declapract
+```
+
+2. add a declapract usage config to 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://...'
+```
+
+3. clone a declared best practices example, do bootstrap a new repo
+```sh
+declapract clone lambda-service-with-rds # bootstrap a new lambda-service-with-rds repo
+```
+
+4. check that your repo is conforming to best practices
+```
+declapract check
+```
+
+5. fix a specific practice that your repo is failing to conform to (if it has an automatic fix declared)
+```sh
+declapract fix --practice dates-and-times # e.g., apply a fix for the the dates-and-times practice
+```