Migrate Skuba Dive (#1497)

Co-authored-by: skuba <34733141+seek-oss-ci@users.noreply.github.com>
Co-authored-by: Ryan Ling <ryan@outlook.com.au>
Co-authored-by: Aaron Moat <2937187+AaronMoat@users.noreply.github.com>

.eslintignore

@@ -17,3 +17,4 @@ node_modules*/
 /integration/base/
 /integration/format/
 /template/
+/packages/**/*/lib*/

.github/workflows/validate.yml

@@ -76,6 +76,41 @@ jobs:
         name: Dry-run site packaging
         run: pnpm skuba node scripts/package.ts
 
+  package:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        template:
+          - eslint-config-skuba
+          - skuba-dive
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Set up pnpm
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Setup Skuba
+        run: pnpm build
+
+      - if: github.head_ref != 'changeset-release/main' && github.ref_name != 'changeset-release/main'
+        name: Lint package
+        run: pnpm --filter ${{ matrix.template }} lint
+
+      - if: github.head_ref != 'changeset-release/main' && github.ref_name != 'changeset-release/main'
+        name: Test package
+        run: pnpm --filter ${{ matrix.template }} test
+
   template:
     name: Integrate
     runs-on: ubuntu-latest

.gitignore

@@ -26,3 +26,4 @@ yarn-error.log
 /integration/lint/
 /template/**/pnpm-lock.yaml
 /template/**/yarn.lock
+/packages/**/*/lib*

.prettierignore

@@ -8,4 +8,3 @@ pnpm-lock.yaml
 # end managed by skuba
 
 /integration/base/
-

packages/eslint-config-skuba/package.json

@@ -20,6 +20,11 @@
     "index.d.ts",
     "index.js"
   ],
+  "scripts": {
+    "format": "pnpm --silent skuba format",
+    "lint": "pnpm --silent skuba lint",
+    "skuba": "node --env-file=../../.env ../../lib/skuba"
+  },
   "dependencies": {
     "@types/eslint": "^8.4.1",
     "@typescript-eslint/eslint-plugin": "^7.2.0",

packages/skuba-dive/.dockerignore

@@ -0,0 +1,23 @@
+# managed by skuba
+.gantry/
+.git/
+.idea/
+.serverless/
+.vscode/
+node_modules*/
+
+/coverage*/
+/dist*/
+/lib*/
+/tmp*/
+
+.DS_Store
+npm-debug.log
+yarn-error.log
+# end managed by skuba
+
+# Ignore .npmrc. This is no longer managed by skuba as pnpm projects use a managed .npmrc.
+# IMPORTANT: if migrating to pnpm, remove this line and add an .npmrc IN THE SAME COMMIT.
+# You can use `skuba format` to generate the file or otherwise commit an empty file.
+# Doing so will conflict with a local .npmrc and make it more difficult to unintentionally commit auth secrets.
+.npmrc

packages/skuba-dive/.eslintignore

@@ -0,0 +1,15 @@
+# managed by skuba
+.idea/*
+.vscode/*
+
+.cdk.staging/
+.pnpm-store/
+.serverless/
+cdk.out/
+node_modules*/
+
+/coverage*/
+/dist*/
+/lib*/
+/tmp*/
+# end managed by skuba

packages/skuba-dive/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['skuba'],
+};

packages/skuba-dive/.gitignore

@@ -0,0 +1,29 @@
+# managed by skuba
+.idea/*
+.vscode/*
+
+.cdk.staging/
+.serverless/
+cdk.out/
+node_modules*/
+
+/coverage*/
+/dist*/
+/lib*/
+/tmp*/
+
+.DS_Store
+.eslintcache
+.pnpm-debug.log
+*.tgz
+*.tsbuildinfo
+npm-debug.log
+package-lock.json
+yarn-error.log
+# end managed by skuba
+
+# Ignore .npmrc. This is no longer managed by skuba as pnpm projects use a managed .npmrc.
+# IMPORTANT: if migrating to pnpm, remove this line and add an .npmrc IN THE SAME COMMIT.
+# You can use `skuba format` to generate the file or otherwise commit an empty file.
+# Doing so will conflict with a local .npmrc and make it more difficult to unintentionally commit auth secrets.
+.npmrc

packages/skuba-dive/.prettierignore

@@ -0,0 +1,8 @@
+# managed by skuba
+# Gantry resource files support non-standard template syntax
+/.gantry/**/*.yaml
+/.gantry/**/*.yml
+gantry*.yaml
+gantry*.yml
+pnpm-lock.yaml
+# end managed by skuba

packages/skuba-dive/.prettierrc.js

@@ -0,0 +1 @@
+module.exports = require('../../config/prettier');

packages/skuba-dive/LICENSE

@@ -0,0 +1,21 @@
+### MIT License
+
+Copyright (c) 2020 SEEK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/skuba-dive/README.md

@@ -0,0 +1,101 @@
+# 🤿🌊
+
+[![Node.js version](https://img.shields.io/badge/node-%3E%3D%2014.18-brightgreen)](https://nodejs.org/en/)
+[![npm package](https://img.shields.io/npm/v/skuba-dive)](https://www.npmjs.com/package/skuba-dive)
+
+Minimal runtime for [`skuba`](https://github.com/seek-oss/skuba).
+
+## Table of contents
+
+- [API reference](#api-reference)
+  - [Assert](#assert)
+  - [Env](#env)
+  - [Register](#register)
+- [Design](#design)
+
+## API reference
+
+### Assert
+
+[TypeScript assertion functions] for narrowing down types in unit tests and the like.
+
+These may be used for input validation in your application code at a pinch,
+but consider a proper validation library with richer error handling and reporting.
+
+[typescript assertion functions]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+
+```typescript
+import { Assert } from 'skuba-dive';
+
+it('should think of a good test case name', () => {
+  const result = numberOrNull();
+  // result is number | null
+
+  Assert.notNullish(result);
+  // result is number
+});
+```
+
+### Env
+
+Functions for reading values out of environment variables.
+
+For example, in your `/src/config.ts`:
+
+```typescript
+import { Env } from 'skuba-dive';
+
+const ENVIRONMENTS = ['dev', 'prod'] as const;
+
+export type Environment = (typeof ENVIRONMENTS)[number];
+
+export const environment = Env.oneOf(ENVIRONMENTS)('ENVIRONMENT');
+// 'dev' | 'prod'
+
+export const port = Env.nonNegativeInteger('PORT', { default: undefined });
+// number | undefined
+
+export const version = Env.string('VERSION', { default: 'local' });
+// string | 'local'
+
+export const flag = Env.boolean('FLAG');
+// boolean
+```
+
+Each function will throw if its environment variable is not set and `opts.default` is not provided.
+
+### Register
+
+Runtime hook for import paths relative to `/src`.
+
+Make a side-effectful import at the top of your entry point(s):
+
+```typescript
+// /src/register.ts
+
+import 'skuba-dive/register';
+```
+
+```typescript
+// /src/app.ts
+
+import './register';
+
+import { config } from 'src/config';
+
+export = new Koa();
+```
+
+The hook must be imported from a module that sits directly under `/src` for module resolution to work correctly.
+
+## Design
+
+`skuba-dive` packages up:
+
+- General application boilerplate that doesn't justify a standalone module
+- Runtime functionality that complements `skuba`
+
+See `skuba`'s [goals] and [non-goals] for more information.
+
+[goals]: https://seek-oss.github.io/skuba/docs/about.html#goals
+[non-goals]: https://seek-oss.github.io/skuba/docs/about.html#non-goals

packages/skuba-dive/jest.config.ts

@@ -0,0 +1,12 @@
+import { Jest } from '../../src';
+
+export default Jest.mergePreset({
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+});

packages/skuba-dive/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "skuba-dive",
+  "version": "2.0.0",
+  "private": false,
+  "description": "Minimal runtime for skuba",
+  "homepage": "https://github.com/seek-oss/skuba/tree/main/packages/skuba-dive#readme",
+  "bugs": {
+    "url": "https://github.com/seek-oss/skuba/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seek-oss/skuba.git"
+  },
+  "license": "MIT",
+  "sideEffects": true,
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib/**/*.d.ts",
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "register.js"
+  ],
+  "scripts": {
+    "build": "pnpm skuba build",
+    "format": "pnpm skuba format",
+    "lint": "pnpm skuba lint",
+    "prepack": "pnpm skuba build",
+    "skuba": "node --env-file=../../.env ../../lib/skuba",
+    "test": "pnpm skuba test",
+    "test:ci": "pnpm skuba test --coverage"
+  },
+  "dependencies": {
+    "module-alias": "^2.2.2"
+  },
+  "devDependencies": {
+    "@types/module-alias": "2.0.4"
+  },
+  "engines": {
+    "node": ">=14.18"
+  },
+  "skuba": {
+    "entryPoint": "src/index.ts",
+    "template": "oss-npm-package",
+    "type": "package",
+    "version": "7.5.0"
+  }
+}

packages/skuba-dive/register.js

@@ -0,0 +1,12 @@
+/**
+ * @see {@link https://nodejs.org/api/deprecations.html#DEP0144}
+ */
+const [firstModuleParent] = Object.values(require.cache).filter((m) =>
+  m.children.includes(module),
+);
+
+if (typeof firstModuleParent !== 'undefined') {
+  const { addAlias } = require('module-alias');
+
+  addAlias('src', firstModuleParent.path);
+}