Add a zero-tolerance TypeDoc documentation gate

AGENTS.md

@@ -148,7 +148,7 @@ clarity, strictness, and reproducibility goals used elsewhere in this guide.
 
 - **ESM-first with a documented CLI exception**: Source modules and the
   published library surface are expected to be ESM. This repository retains a
-  CommonJS build artifact for the Node CLI because `bin/start.cjs` requires
+  CommonJS build artefact for the Node CLI because `bin/start.cjs` requires
   `../dist/index.cjs` so it can run under Node without transpilation. Treat
   that CommonJS output as a narrow operational exception, not as the default
   module model.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all check-fmt typecheck lint test build clean generate markdownlint \
+.PHONY: all check-fmt typecheck docs-check lint test build clean generate markdownlint \
 	nixie spelling spelling-helper-test
 
 MDLINT ?= markdownlint-cli2
@@ -8,14 +8,20 @@ TYPOS_VERSION ?= 1.48.0
 TYPOS = $(UV) tool run typos@$(TYPOS_VERSION)
 XARGS_R := $(shell if xargs --help 2>&1 | grep -q '\\-r'; then printf -- '-r'; fi)
 
-all: check-fmt typecheck lint test spelling
+all: check-fmt typecheck docs-check lint test spelling
 
 check-fmt:
 	bun node_modules/@biomejs/biome/bin/biome check --linter-enabled=false --assist-enabled=false .
 
 typecheck:
 	bun run check:types
 
+# Zero-tolerance documentation gate: TypeDoc's notDocumented validation over
+# the package entry point (typedoc.json). Runs after typecheck so the
+# generated GraphQL types already exist. Emits no documentation artefacts.
+docs-check:
+	bun run docs:check
+
 lint:
 	bun run lint
 

docs/developers-guide.md

@@ -87,6 +87,13 @@ BRANCH=$(git branch --show-current | tr '/ ' '__')
 make all 2>&1 | tee /tmp/all-digitalpuddle-${BRANCH}.out
 ```
 
+`make all` includes `docs-check` (`bun run docs:check`): TypeDoc's
+`notDocumented` validation over the package entry point (`typedoc.json`),
+requiring a JSDoc block on every declaration in the public surface, treating
+warnings as errors, and emitting no documentation artefacts. Zod schema
+constants are tagged `@internal` so their field definitions stay out of the
+documented surface.
+
 Run documentation gates when Markdown changes:
 
 ```bash

package.json

@@ -60,6 +60,7 @@
     "bench": "bun test --bench",
     "build": "tsdown",
     "check:types": "bun run generate && bunx tsc --noEmit",
+    "docs:check": "typedoc --options typedoc.json",
     "fmt": "bunx @biomejs/biome format --write .",
     "generate": "graphql-codegen",
     "lint": "bunx @biomejs/biome lint .",
@@ -96,6 +97,7 @@
     "fast-check": "^4.8.0",
     "publint": "^0.3.21",
     "tsdown": "^0.22.3",
+    "typedoc": "^0.28.20",
     "typescript": "^6.0.3"
   },
   "overrides": {
@@ -113,7 +115,7 @@
     "ws": "8.21.0"
   },
   "inlinedDependencies": {
-    "starfx": "0.15.0"
+    "starfx": "0.16.1"
   },
   "main": "./dist/index.cjs"
 }

src/index.ts

@@ -1,10 +1,12 @@
 /**
- * @file Public compatibility facade for the DigitalPuddle package entry.
+ * Public compatibility facade for the DigitalPuddle package entry.
  *
  * This module preserves the package-facing import surface while internal
  * assembly moves into target DigitalPuddle modules. It re-exports the
  * simulation factory and retained GitHub fixture schemas so existing consumers
  * and build configuration can keep importing from the package root.
+ *
+ * @module
  */
 export {simulation} from './simulation.ts';
 export type {GitHubSimulatorArgs, InitialState} from './simulation.ts';

src/simulation.ts

@@ -23,19 +23,28 @@ import {
 } from './store/index.ts';
 import type {SchemaFile} from './utils.ts';
 
+/** Seed data accepted for the GitHub fixtures a simulation server starts with. */
 export type InitialState = GitHubInitialStore;
 
 type FoundationRouter = Parameters<
   NonNullable<Parameters<typeof createFoundationSimulationServer>[0]['extendRouter']>
 >[0];
 
+/** Options accepted by {@link simulation} to seed and extend a GitHub simulation server. */
 export type GitHubSimulatorArgs = {
+  /** Seed data for the GitHub fixture store. */
   initialState?: GitHubInitialStore;
+  /** Base URL the simulated GitHub API is served from. */
   apiUrl?: string;
+  /** OpenAPI document, or path to one, describing the simulated GitHub API. */
   apiSchema?: SchemaFile | string;
+  /** Store, REST, and router extensions layered onto the base simulation. */
   extend?: {
+    /** Additional store state and reducers merged into the GitHub fixture store. */
     extendStore?: GitHubExtendStoreInput;
+    /** Builds extra REST handlers from the extended simulation store. */
     openapiHandlers?: (simulationStore: ExtendedSimulationStore) => SimulationHandlers;
+    /** Registers additional routes on the extended simulation store's router. */
     extendRouter?: (router: FoundationRouter, simulationStore: ExtendedSimulationStore) => void;
   };
 };

src/store/entities.ts

@@ -39,6 +39,12 @@ const getNextInstallationId = (usedInstallationIds: Set<number>, nextInstallatio
   };
 };
 
+/**
+ * Validates and normalizes a seeded GitHub user fixture, deriving a display
+ * name and email address when they are omitted.
+ *
+ * @internal
+ */
 export const githubUserSchema = z
   .object({
     id: z

src/store/entities/blob.ts

@@ -2,6 +2,12 @@
 import {faker} from '@faker-js/faker';
 import {z} from 'zod';
 
+/**
+ * Validates a seeded git blob fixture, requiring a path or a sha so the
+ * fixture can be keyed within the store.
+ *
+ * @internal
+ */
 export const githubBlobSchema = z
   .object({
     content: z.string().optional().default(faker.lorem.paragraphs),

src/store/entities/branch.ts

@@ -4,6 +4,12 @@ import {z} from 'zod';
 
 const GITHUB_API_HOST = 'https://api.github.com';
 
+/**
+ * Validates and normalizes a seeded GitHub branch fixture, deriving a commit
+ * SHA and protection URL when they are omitted.
+ *
+ * @internal
+ */
 export const githubBranchSchema = z
   .object({
     owner: z.string(),

src/store/entities/organization.ts

@@ -25,6 +25,12 @@ const deriveOrganizationBaseUrl = (url?: string) => {
   }
 };
 
+/**
+ * Validates and normalizes a seeded GitHub organization fixture, filling in
+ * the profile URLs that GitHub derives from the login.
+ *
+ * @internal
+ */
 export const githubOrganizationSchema = z
   .object({
     id: z.number().default(() => faker.number.int({min: 4000, max: 9_999_999})),

src/store/entities/repository.ts

@@ -16,6 +16,12 @@ export const resetNextRepositoryId = (newValue = 3000) => {
   nextGeneratedRepositoryId = newValue;
 };
 
+/**
+ * Validates and normalizes a seeded GitHub repository fixture, deriving the
+ * full name and the GitHub-style API URLs for the repository.
+ *
+ * @internal
+ */
 export const githubRepositorySchema = z
   .object({
     id: z.number().optional(),

typedoc.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+
+  "entryPoints": ["src/index.ts"],
+  "entryPointStrategy": "resolve",
+
+  "emit": "none",
+  "commentStyle": "jsdoc",
+
+  "excludeExternals": true,
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+
+  "validation": {
+    "notDocumented": true,
+    "notExported": false,
+    "invalidLink": false,
+    "invalidPath": false,
+    "rewrittenLink": false,
+    "unusedMergeModuleWith": false
+  },
+
+  "requiredToBeDocumented": [
+    "Enum",
+    "EnumMember",
+    "Variable",
+    "Function",
+    "Class",
+    "Interface",
+    "Property",
+    "Method",
+    "Accessor",
+    "TypeAlias"
+  ],
+
+  "treatValidationWarningsAsErrors": true
+}