BREAKING: Generated Types and Schemas

.github/workflows/pr.yml

@@ -25,6 +25,18 @@ jobs:
           require-lockfile: true
       - name: Build Packages
         run: pnpm build
+      # Any changes after regenerating each package from the schema package mean the generated files weren't
+      # regenerated and committed alongside a schema change
+      - name: Generate Packages
+        run: pnpm generate
+      - name: Check for Uncommitted Changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::Generated files are out of date; run \`pnpm generate\` and commit the changes."
+            git status --short
+            git --no-pager diff
+            exit 1
+          fi
       - name: Lint Code
         run: pnpm lint
       - name: Run Unit Tests

package.json

@@ -10,13 +10,15 @@
     "check": "turbo run check",
     "format": "oxfmt --config oxfmt.config.ts --write .",
     "format:check": "oxfmt --config oxfmt.config.ts --check .",
+    "generate": "turbo run generate",
     "lint": "oxlint --config oxlint.config.ts .",
     "lint:fix": "oxlint --config oxlint.config.ts --fix .",
     "test": "vitest run"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
     "@bachman-dev/oxc-config": "0.3.0",
+    "@types/node": "24.19.2",
     "@vitest/coverage-v8": "5.0.3",
     "oxfmt": "0.72.0",
     "oxlint": "1.87.0",

packages/requests/vitest.config.ts

@@ -8,5 +8,6 @@ export default defineConfig({
       enabled: true,
     },
     pool: "threads",
+    isolate: false,
   },
 });

packages/schema/README.md

@@ -0,0 +1,25 @@
+# @bachman-dev/wanikani-api-schema
+
+The internal, single source of truth for the WaniKani API schema. The type definitions in `@bachman-dev/wanikani-api-types` and the runtime schema in `@bachman-dev/wanikani-api-valibot` and `@bachman-dev/wanikani-api-zod` are generated from it; their `src/` files (other than `lang/` folders) shouldn't be edited by hand.
+
+## Layout
+
+- `src/core/` (`@bachman-dev/wanikani-api-schema/core`): the building blocks for defining schema (`define`, `object`, `property`, `union`, ...), along with helpers for writing generators (docs rendering, import tracking, writing and formatting files).
+- `src/v20170710/` (`@bachman-dev/wanikani-api-schema/v20170710`): the definitions of the `20170710` API revision, one file per generated module, plus the revision's custom error `messages`.
+- `src/index.ts`: the latest revision, along with `revisions`, every revision a generator should generate.
+
+## Changing the Schema
+
+1. Edit the definitions in `src/<revision>/`. Docs given to a definition or property are printed above it in every generated package.
+2. Run `pnpm generate` from the repository root; this builds the schema package, then runs each package's `scripts/generate.ts`.
+3. Commit the regenerated files along with the schema change.
+
+CI runs `pnpm generate` and fails if it changes any files, so generated files can't fall out of date.
+
+## Adding a Schema Library
+
+1. Create the package, following the layout of the existing ones (`src/index.ts` exporting the latest revision from `src/v20170710/`).
+2. Add `@bachman-dev/wanikani-api-schema` as a dev dependency, and a `generate` script running `node scripts/generate.ts`.
+3. Write `scripts/generate.ts` (see `packages/valibot/scripts/generate.ts`), rendering every kind of `Schema` and passing the output to `generatePackageFiles()` and `writeGeneratedFiles()`.
+4. Implement the revision's `messages` in `src/<revision>/lang/`, exported under the same names.
+5. Write tests similar to those of the existing schema libraries.

packages/schema/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@bachman-dev/wanikani-api-schema",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The base WaniKani API schema used to generate types and runtime schema definitions",
+  "homepage": "https://wanikani-api-types.bachman.dev",
+  "license": "MIT",
+  "author": "Collin Bachman <collin.r68zdn9d@bachman.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bachman-dev/wanikani-api-types.git",
+    "directory": "packages/schema"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./core": "./dist/core/index.mjs",
+    "./v20170710": "./dist/v20170710/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "check": "tsc --noEmit"
+  }
+}