ci(dx): guard that public dev-facing functions carry a JSDoc summary

Adds scripts/check-dx-coverage.mjs — a TypeDoc walk over the chat/ag-ui/
langgraph/render public surfaces that fails when an exported function lacks a
JSDoc summary (so the audited DX bar can't silently regress). Honors @internal
as an escape hatch for spec-only/implementation exports. Wired as a step in the
`library` CI job.

Documented the one straggler it found (extractErrorMessage). Guard reports:
"all 65 public functions across chat/ag-ui/langgraph/render have a JSDoc summary."

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: blove

.github/workflows/ci.yml

@@ -95,6 +95,8 @@ jobs:
       - run: npx nx run-many -t test --projects=$LIBS --coverage
       - run: npx nx run-many -t build --projects=$LIBS --configuration=production
       - run: node scripts/verify-release-versions.mjs
+      - name: DX-coverage — public dev-facing functions must have a JSDoc summary
+        run: node scripts/check-dx-coverage.mjs
 
   website:
     name: Website — lint / build

libs/chat/src/lib/primitives/chat-error/chat-error.component.ts

@@ -5,6 +5,19 @@ import type { Agent } from '../../agent';
 import { CHAT_HOST_TOKENS } from '../../styles/chat-tokens';
 import { CHAT_ERROR_STYLES } from '../../styles/chat-error.styles';
 
+/**
+ * Coerce an unknown error value into a human-readable message string — reads
+ * `.message` from `Error`s, returns strings as-is, and `String()`-casts the
+ * rest. Useful when rendering an agent's `error` outside the built-in
+ * `chat-error` component.
+ *
+ * @param error Any caught/agent error value.
+ * @returns The message text, or `null` when `error` is nullish.
+ * @example
+ * ```ts
+ * const msg = extractErrorMessage(agent.error());
+ * ```
+ */
 export function extractErrorMessage(error: unknown): string | null {
   if (!error) return null;
   if (error instanceof Error) return error.message;

scripts/check-dx-coverage.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * DX-coverage guard: every public exported FUNCTION in the dev-facing
+ * `@threadplane/*` libraries must carry a non-empty JSDoc summary so app
+ * developers get hover guidance on the surface they actually call.
+ *
+ * Symbols tagged `@internal` are exempt (spec-only / implementation exports).
+ * Run: `node scripts/check-dx-coverage.mjs` — exits non-zero on violations.
+ */
+import { Application, TSConfigReader, ReflectionKind } from 'typedoc';
+import fs from 'fs';
+import path from 'path';
+
+const LIBRARIES = [
+  { slug: 'chat', entryPoints: ['libs/chat/src/public-api.ts'] },
+  { slug: 'ag-ui', entryPoints: ['libs/ag-ui/src/public-api.ts'] },
+  { slug: 'langgraph', entryPoints: ['libs/langgraph/src/public-api.ts'] },
+  { slug: 'render', entryPoints: ['libs/render/src/public-api.ts'] },
+];
+
+function summaryText(comment) {
+  if (!comment?.summary) return '';
+  return comment.summary.map((p) => p.text ?? '').join('').trim();
+}
+
+function isInternal(reflection, signature) {
+  const tagged = (c) => !!c?.blockTags?.some((t) => t.tag === '@internal') || !!c?.modifierTags?.has?.('@internal');
+  return tagged(reflection.comment) || tagged(signature?.comment);
+}
+
+/** A function is documented if either the reflection or its call signature has a summary. */
+function functionHasSummary(reflection) {
+  const sig = reflection.signatures?.[0];
+  return summaryText(reflection.comment).length > 0 || summaryText(sig?.comment).length > 0;
+}
+
+function* walk(reflections) {
+  for (const ref of reflections ?? []) {
+    yield ref;
+    if (ref.children) yield* walk(ref.children);
+  }
+}
+
+async function main() {
+  const violations = [];
+  let checked = 0;
+
+  for (const lib of LIBRARIES) {
+    const missing = lib.entryPoints.filter((p) => !fs.existsSync(p));
+    if (missing.length) {
+      console.error(`✗ ${lib.slug}: entry point(s) not found: ${missing.join(', ')}`);
+      process.exitCode = 1;
+      continue;
+    }
+    const libDir = path.dirname(path.dirname(lib.entryPoints[0]));
+    const libTsconfig = fs.existsSync(path.join(libDir, 'tsconfig.lib.json'))
+      ? path.join(libDir, 'tsconfig.lib.json')
+      : undefined;
+
+    const app = await Application.bootstrapWithPlugins({
+      entryPoints: lib.entryPoints,
+      skipErrorChecking: true,
+      excludeInternal: true,
+      ...(libTsconfig ? { tsconfig: libTsconfig } : {}),
+    });
+    app.options.addReader(new TSConfigReader());
+    const project = await app.convert();
+    if (!project) throw new Error(`TypeDoc failed to convert ${lib.slug}`);
+
+    for (const ref of walk(project.children)) {
+      if (ref.kind !== ReflectionKind.Function) continue;
+      if (isInternal(ref, ref.signatures?.[0])) continue;
+      checked++;
+      if (!functionHasSummary(ref)) {
+        violations.push(`@threadplane/${lib.slug} :: ${ref.name}()`);
+      }
+    }
+  }
+
+  if (violations.length) {
+    console.error(`\n✗ DX-coverage: ${violations.length} public function(s) missing a JSDoc summary:\n`);
+    for (const v of violations.sort()) console.error(`   - ${v}`);
+    console.error(`\nAdd a one-line summary (and ideally an @example), or mark the symbol @internal if it is not public API.`);
+    process.exit(1);
+  }
+
+  console.log(`✓ DX-coverage: all ${checked} public functions across chat/ag-ui/langgraph/render have a JSDoc summary.`);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });