feat: ship TypeScript types for every package

.c8rc.json

@@ -1,6 +1,6 @@
 {
 	"all": true,
-	"exclude": ["coverage/**", "test/**"],
+	"exclude": ["coverage/**", "test/**", "**/*.d.ts"],
 	"check-coverage": true,
 	"branches": 100,
 	"functions": 100,

.github/workflows/ci.yml

@@ -100,6 +100,33 @@ jobs:
           done
           exit "$status"
 
+  # The published types are generated from the JSDoc, and committed since
+  # releases pack without installing anything, so check they're current
+  types:
+    if: github.repository == 'cutenode/nodevu'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: current
+      # the packages import each other, so link the workspaces
+      - name: Run npm install
+        run: npm install -ws --include-workspace-root
+      - name: Build the types
+        run: npm run types
+      - name: Check the committed types match the source
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git status --porcelain
+            echo "::error::the committed types are out of date, run npm run types and commit the result"
+            exit 1
+          fi
+
   test:
     needs: changes
     if: needs.changes.outputs.packages != '[]'
@@ -131,7 +158,7 @@ jobs:
   # required check that never reports blocks the merge
   ci-ok:
     if: always()
-    needs: [changes, lint, test]
+    needs: [changes, lint, types, test]
     runs-on: ubuntu-latest
     steps:
       - name: Fail if any job failed or was cancelled

.oxfmtrc.json

@@ -17,6 +17,7 @@
 		".pi/**",
 		".roo/**",
 		".windsurf/**",
-		"tools/oxlint/anti-slop/**"
+		"tools/oxlint/anti-slop/**",
+		"*/types/**"
 	]
 }

.oxlintrc.json

@@ -12,7 +12,8 @@
 		".pi/**",
 		".roo/**",
 		".windsurf/**",
-		"tools/oxlint/anti-slop/**"
+		"tools/oxlint/anti-slop/**",
+		"*/types/**"
 	],
 	"jsPlugins": [
 		{ "name": "anti-slop", "specifier": "./tools/oxlint/anti-slop/index.ts" }

README.md

@@ -22,6 +22,7 @@ nodevu is composed of a set of modules:
 
 - `npm test` and `npm run coverage` run every module's tests.
 - `npm run lint` checks the whole repo with oxlint and oxfmt.
+- `npm run types` type-checks the JSDoc and writes each module's TypeScript declarations to its `types/` folder. Commit them: CI fails when they're out of date.
 - `npm run docs:dev` builds the docs from `docs/pages/` with [doc-kit](https://doc-kit.nodejs.org/) and serves them locally. `npm run docs` only builds them, into `out/`.
 
 Merging to `main` publishes the docs to GitHub Pages.

aliases/index.js

@@ -1,3 +1,12 @@
+/**
+ * @typedef {'alpha' | 'current' | 'lts/latest' | 'lts/active' | 'lts/maintenance' | 'eol' | 'all'} Alias
+ */
+
+/**
+ * The names of the ranges of release lines `@nodevu/ranges` works out.
+ *
+ * @type {Alias[]}
+ */
 const aliases = [
 	'alpha',
 	'current',

aliases/package.json

@@ -23,5 +23,10 @@
 		"test": "",
 		"updates:check": "npx npm-check-updates",
 		"updates:update": "npx npm-check-updates -u"
-	}
+	},
+	"types": "types/index.d.ts",
+	"files": [
+		"index.js",
+		"/types"
+	]
 }

aliases/tsconfig.json

@@ -0,0 +1,5 @@
+{
+	"extends": "../tsconfig.base.json",
+	"include": ["index.js"],
+	"references": []
+}

aliases/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @typedef {'alpha' | 'current' | 'lts/latest' | 'lts/active' | 'lts/maintenance' | 'eol' | 'all'} Alias
+ */
+export = aliases;
+export type Alias = 'alpha' | 'current' | 'lts/latest' | 'lts/active' | 'lts/maintenance' | 'eol' | 'all';
+/**
+ * The names of the ranges of release lines `@nodevu/ranges` works out.
+ *
+ * @type {Alias[]}
+ */
+declare const aliases: Alias[];