test: add API, type and wire-protocol safety nets

.github/workflows/checks.yml

@@ -33,8 +33,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Build library
-        run: npm run build
+      - name: Build library and check the public API
+        run: npm run api:check
 
   test:
     name: Unit tests

.gitignore

@@ -37,3 +37,6 @@ testem.log
 # System files
 .DS_Store
 Thumbs.db
+
+# API snapshot output on a mismatch
+*.snapshot.json.actual

README.md

@@ -41,16 +41,34 @@ The package is built to `dist/ngx-ui-watchtower`.
 
 ## Scripts
 
-| Script                  | What it does                                         |
-| ----------------------- | ---------------------------------------------------- |
-| `npm run build`         | Builds the package (production, partial compilation) |
-| `npm run watch`         | Rebuilds on change (development)                     |
-| `npm run test`          | Runs the unit tests (Jest)                           |
-| `npm run test:coverage` | Runs the unit tests with coverage, as CI does        |
-| `npm run typecheck`     | Type-checks every library and spec tsconfig          |
-| `npm run lint`          | ESLint, no warnings allowed                          |
-| `npm run format`        | Formats with Prettier                                |
-| `npm run format:check`  | Checks formatting without writing                    |
+| Script                  | What it does                                                    |
+| ----------------------- | --------------------------------------------------------------- |
+| `npm run build`         | Builds the package (production, partial compilation)            |
+| `npm run watch`         | Rebuilds on change (development)                                |
+| `npm run test`          | Runs the unit tests (Jest)                                      |
+| `npm run test:coverage` | Runs the unit tests with coverage, as CI does                   |
+| `npm run typecheck`     | Type-checks every library and spec tsconfig, and the type tests |
+| `npm run api:check`     | Builds, then compares the public API with its snapshot          |
+| `npm run api:update`    | Builds, then rewrites the snapshot, for an intended change      |
+| `npm run lint`          | ESLint, no warnings allowed                                     |
+| `npm run format`        | Formats with Prettier                                           |
+| `npm run format:check`  | Checks formatting without writing                               |
+
+Three checks guard what consumers depend on:
+
+- **Type tests** (`projects/ngx-ui-watchtower/type-tests/`) compile, with the
+  Angular compiler, a consumer that uses every public export, and one that
+  augments the name registries: registered names accepted, others rejected,
+  `string` while nothing is registered.
+- **The API snapshot** (`projects/ngx-ui-watchtower/public-api.snapshot.json`)
+  records every export of the built package with its members and
+  signatures. After an intended change, run `npm run api:update` and review
+  the diff.
+- **The broadcast wire fixture**
+  (`projects/ngx-ui-watchtower/src/lib/sinks/uwt-broadcast/uwt-broadcast.wire.fixture.json`) records
+  every message a shell and a fragment exchange. Shells and fragments are
+  deployed separately, so it changes only with a deliberate protocol change:
+  `UPDATE_WIRE_FIXTURE=1 npm test` records it again.
 
 ## Before you push
 
@@ -62,6 +80,7 @@ npm run typecheck
 npm run lint
 npm run format:check
 npm run build
+npm run api:check
 ```
 
 CI runs the same checks on every pull request and every push to `main`.

package.json

@@ -8,9 +8,11 @@
     "test": "ng test --project=ngx-ui-watchtower",
     "test:coverage": "ng test --project=ngx-ui-watchtower --coverage --coverage-reporters text-summary --coverage-reporters lcov --json --output-file=./coverage/report.json",
     "lint": "eslint \"**/*.ts\" --max-warnings=0",
-    "format": "prettier --write \"**/*.{ts,html}\"",
-    "format:check": "prettier --check \"**/*.{ts,html}\"",
-    "typecheck": "tsc -p projects/ngx-ui-watchtower/tsconfig.lib.json --noEmit && tsc -p projects/ngx-ui-watchtower/tsconfig.spec.json --noEmit && tsc -p projects/ngx-ui-watchtower/rum/tsconfig.lib.json --noEmit && tsc -p projects/ngx-ui-watchtower/rum/tsconfig.spec.json --noEmit"
+    "format": "prettier --write \"**/*.{ts,mjs,html}\"",
+    "format:check": "prettier --check \"**/*.{ts,mjs,html}\"",
+    "typecheck": "tsc -p projects/ngx-ui-watchtower/tsconfig.lib.json --noEmit && tsc -p projects/ngx-ui-watchtower/tsconfig.spec.json --noEmit && tsc -p projects/ngx-ui-watchtower/rum/tsconfig.lib.json --noEmit && tsc -p projects/ngx-ui-watchtower/rum/tsconfig.spec.json --noEmit && ngc -p projects/ngx-ui-watchtower/type-tests/tsconfig.json && ngc -p projects/ngx-ui-watchtower/type-tests/tsconfig.augmented.json",
+    "api:check": "npm run build && node scripts/api-snapshot.mjs",
+    "api:update": "npm run build && node scripts/api-snapshot.mjs --update"
   },
   "private": true,
   "dependencies": {