declapract-typescript-ehmpathy 0.17.0

package/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: dist/examples
+  practices: dist/practices
+  use-cases: dist/useCases.yml

package/dist/examples/todo.md

@@ -0,0 +1 @@
+todo: create example of best practices followed when declapract supports cloning and validating the examples

package/dist/getVariables.ts

@@ -0,0 +1,27 @@
+import { createGetVariables } from 'declapract';
+
+export const getProjectVariables = createGetVariables({
+  organizationName: 'awesum',
+  projectName: 'svc-awesome-thing',
+});
+
+export const getServiceVariables = createGetVariables({
+  infrastructureNamespaceId: 'abcde12345',
+  slackWebhookUrl: 'https://...',
+  awsAccountId: {
+    dev: '123abc',
+    prod: '456def',
+  },
+});
+
+export const getRdsVariables = createGetVariables({
+  databaseName: 'awesomethingdb',
+  databaseClusterHost: {
+    dev: 'awesomesdb.cluster-abc123.us-east-1.rds.amazonaws.com',
+    prod: 'awesomesdb.cluster-def456.us-east-1.rds.amazonaws.com',
+  },
+  databaseUserName: {
+    serviceUser: 'svc_awesome_thing_user',
+    cicdUser: 'awesomethingdb_cicd',
+  },
+});

package/dist/practices/cicd-deploy-package/bad-practices/old-names/.github/workflows/publish_on_tag.yml.declapract.ts

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

package/dist/practices/cicd-deploy-package/best-practice/.declapract.readme.md

@@ -0,0 +1,2 @@
+flows:
+- publish package on every v* tagged commit on main

package/dist/practices/cicd-deploy-package/best-practice/.github/workflows/publish-on-tag.yml

@@ -0,0 +1,36 @@
+name: deploy_on_tag
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  test_and_deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: install
+        run: npm ci
+
+      - name: tests
+        run: npm run test
+
+      - name: publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/dist/practices/cicd-deploy-service/bad-practices/old-names/.github/workflows/deploy_dev_on_main.yml.declapract.ts

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

package/dist/practices/cicd-deploy-service/bad-practices/old-names/.github/workflows/deploy_dev_on_master.yml.declapract.ts

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

package/dist/practices/cicd-deploy-service/bad-practices/old-names/.github/workflows/deploy_on_tag.yml.declapract.ts

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

package/dist/practices/cicd-deploy-service/bad-practices/old-names/.github/workflows/deploy_prod_on_tag.yml.declapract.ts

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

package/dist/practices/cicd-deploy-service/best-practice/.declapract.readme.md

@@ -0,0 +1,4 @@
+flows:
+- test on every commit
+- deploy to dev every commit on master
+- deploy to prod every v* tagged commit on master

package/dist/practices/cicd-deploy-service/best-practice/.github/workflows/deploy-dev-on-main.yml

@@ -0,0 +1,59 @@
+name: deploy-dev-on-main
+
+on:
+  push:
+    branches: # only on main branch
+      - 'main'
+      - 'master'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test-and-deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: install
+        run: npm ci
+
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: confirm aws credentials
+        run: |
+          [[ ${{steps.credentials.outputs.aws-account-id}} != '@declapract{variable.awsAccountId.dev}' ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db
+
+      - name: test
+        run: npm run test
+
+      - name: deploy
+        run: DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy:dev
+
+      - name: test:acceptance
+        run: DEPLOYMENT_STAGE=dev npm run test:acceptance

package/dist/practices/cicd-deploy-service/best-practice/.github/workflows/deploy-prod-on-tag.yml

@@ -0,0 +1,74 @@
+name: deploy-prod-on-tag
+
+on:
+  push:
+    tags:
+      - v*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test-and-deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: install
+        run: npm ci
+
+      # test in dev env
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials-dev
+        with:
+          aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: confirm aws credentials
+        run: |
+          [[ ${{steps.credentials-dev.outputs.aws-account-id}} != '@declapract{variable.awsAccountId.dev}' ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db
+
+      - name: test
+        run: npm run test
+
+      # deploy in prod env
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials-prod
+        with:
+          aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: confirm aws credentials
+        run: |
+          [[ ${{steps.credentials-prod.outputs.aws-account-id}} != '@declapract{variable.awsAccountId.prod}' ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: deploy
+        run: DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy:prod
+
+      - name: test:acceptance
+        run: DEPLOYMENT_STAGE=prod npm run test:acceptance

package/dist/practices/cicd-integrate/bad-practices/old-names/.github/workflows/ci-on-commit.yml.declapract.ts

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

package/dist/practices/cicd-integrate/bad-practices/old-names/.github/workflows/ci_on_commit.yml.declapract.ts

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

package/dist/practices/cicd-integrate/bad-practices/old-names/.github/workflows/test_on_commit.yml.declapract.ts

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

package/dist/practices/cicd-integrate/best-practice/.declapract.readme.md

@@ -0,0 +1,3 @@
+flows:
+- test on every commit
+- create please-release pull requests on every commit to main

package/dist/practices/cicd-integrate/best-practice/.github/workflows/pr-release-on-main.yml

@@ -0,0 +1,17 @@
+name: pr-release-on-main
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-please:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: google-github-actions/release-please-action@v3
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_GITHUB_TOKEN }}
+          release-type: node
+          pull-request-title-pattern: 'chore(release): v${version} 🎉'
+          changelog-path: changelog.md

package/dist/practices/cicd-integrate/best-practice/.github/workflows/test-on-commit.yml

@@ -0,0 +1,285 @@
+name: test-on-commit
+
+on:
+  push:
+    branches: # run for any branch
+      - '**'
+    tags-ignore: # but not for releases, as deploy_on_tag will trigger for it
+      - '**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  install:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: install
+        run: npm ci
+
+      - name: cache node modules
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+  # run tests in parallel
+  test-commits:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: test:commits
+        run: npm run test:commits
+
+  test-types:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: test:types
+        run: npm run test:types
+
+  test-format:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: test:format
+        run: npm run test:format
+
+  test-lint:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: test:lint
+        run: npm run test:lint
+
+  test-unit:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: test:unit
+        run: npm run test:unit
+
+  test-integration:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db
+
+      - name: test:integration
+        run: npm run test:integration
+
+  test-acceptance-locally:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: read nvmrc
+        id: nvmrc
+        run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+
+      - name: setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvmrc.outputs.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: grab node_modules from cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ github.sha }}
+
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db
+
+      - name: test:acceptance:locally
+        run: npm run test:acceptance:locally
+
+  check-provisions-github:
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        working-directory: ./provision/github/environment
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: setup terraform
+        uses: hashicorp/setup-terraform@v1
+
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: confirm aws credentials
+        run: |
+          [[ ${{steps.credentials.outputs.aws-account-id}} != '398838478359' ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: terraform init
+        id: init
+        run: terraform init
+
+      - name: terraform validate
+        id: validate
+        run: terraform validate -no-color
+
+      - name: terraform plan
+        id: plan
+        run: terraform plan -no-color -detailed-exitcode
+        env:
+          GITHUB_TOKEN: ${{ secrets.PROVISION_GITHUB_GITHUB_TOKEN }}

package/dist/practices/config/bad-practices/configs-contain-wrong-account-id/config/dev.json.declapract.ts

@@ -0,0 +1,9 @@
+import { FileCheckFunction } from 'declapract';
+
+import { getServiceVariables } from '../../../../../getVariables';
+
+export const check: FileCheckFunction = (contents, context) => {
+  const { awsAccountId } = getServiceVariables(context);
+  if (!contents?.includes(awsAccountId.prod))
+    throw new Error('does not contain aws prod account id');
+};

package/dist/practices/config/bad-practices/configs-contain-wrong-account-id/config/prod.json.declapract.ts

@@ -0,0 +1,9 @@
+import { FileCheckFunction } from 'declapract';
+
+import { getServiceVariables } from '../../../../../getVariables';
+
+export const check: FileCheckFunction = (contents, context) => {
+  const { awsAccountId } = getServiceVariables(context);
+  if (!contents?.includes(awsAccountId.dev))
+    throw new Error('does not contain aws dev account id');
+};

package/dist/practices/config/bad-practices/configs-contain-wrong-account-id/config/test.json.declapract.ts

@@ -0,0 +1,9 @@
+import { FileCheckFunction } from 'declapract';
+
+import { getServiceVariables } from '../../../../../getVariables';
+
+export const check: FileCheckFunction = (contents, context) => {
+  const { awsAccountId } = getServiceVariables(context);
+  if (!contents?.includes(awsAccountId.prod))
+    throw new Error('does not contain aws prod account id');
+};

package/dist/practices/config/bad-practices/divergent-config-shapes/.declapract.readme.md

@@ -0,0 +1,8 @@
+the following places should have the shape of the config defined identically:
+- `config/test.json`
+- `config/dev.json`
+- `config/prod.json`
+
+this check complains if one of them does not look like the others
+
+note: ideally we would have a separate util for this, but for now, we'll do this check here

package/dist/practices/config/bad-practices/divergent-config-shapes/config/dev.json.declapract.ts

@@ -0,0 +1,37 @@
+import { FileCheckFunction } from 'declapract';
+import flatten from 'flat';
+import fs from 'fs';
+import util from 'util';
+
+export const readFile = async (filePath: string) =>
+  util.promisify(fs.readFile)(filePath, 'utf-8');
+
+export const check: FileCheckFunction = async (contents, context) => {
+  if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
+
+  // grab the desired keys
+  const testConfigJsonContents = await readFile(
+    `${context.getProjectRootDirectory()}/config/test.json`,
+  );
+  if (!testConfigJsonContents)
+    throw new Error('can only check if test file exists');
+  const testConfigObject = JSON.parse(testConfigJsonContents);
+  const flattenedTestConfigKeys = Object.keys(flatten(testConfigObject));
+
+  // grab the found keys
+  const devConfigObject = JSON.parse(contents);
+  const flattenedDevConfigKeys = Object.keys(flatten(devConfigObject));
+
+  // determine which keys are not matched
+  const keysInTestButNotInDev = flattenedTestConfigKeys.filter(
+    (key) => !flattenedDevConfigKeys.includes(key),
+  );
+  const keysInDevButNotInTest = flattenedDevConfigKeys.filter(
+    (key) => !flattenedTestConfigKeys.includes(key),
+  );
+  if (keysInTestButNotInDev.length) return; // matches bad practice
+  if (keysInDevButNotInTest.length) return; // matches bad practice
+
+  // otherwise, does not match a bad practice
+  throw new Error('its fine');
+};

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prod.json.declapract.ts

@@ -0,0 +1,37 @@
+import { FileCheckFunction } from 'declapract';
+import flatten from 'flat';
+import fs from 'fs';
+import util from 'util';
+
+export const readFile = async (filePath: string) =>
+  util.promisify(fs.readFile)(filePath, 'utf-8');
+
+export const check: FileCheckFunction = async (contents, context) => {
+  if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
+
+  // grab the desired keys
+  const testConfigJsonContents = await readFile(
+    `${context.getProjectRootDirectory()}/config/test.json`,
+  );
+  if (!testConfigJsonContents)
+    throw new Error('can only check if test file exists');
+  const testConfigObject = JSON.parse(testConfigJsonContents);
+  const flattenedTestConfigKeys = Object.keys(flatten(testConfigObject));
+
+  // grab the found keys
+  const prodConfigObject = JSON.parse(contents);
+  const flattenedProdConfigKeys = Object.keys(flatten(prodConfigObject));
+
+  // determine which keys are not matched
+  const keysInTestButNotInProd = flattenedTestConfigKeys.filter(
+    (key) => !flattenedProdConfigKeys.includes(key),
+  );
+  const keysInProdButNotInTest = flattenedProdConfigKeys.filter(
+    (key) => !flattenedTestConfigKeys.includes(key),
+  );
+  if (keysInTestButNotInProd.length) return; // matches bad practice
+  if (keysInProdButNotInTest.length) return; // matches bad practice
+
+  // otherwise, does not match a bad practice
+  throw new Error('its fine');
+};