An open source design system that's fully customizable and agent ready
TypeScript
docsite: the example-coverage report lists public hooks with no hook doc or no example block (#9494)
Cindy Zhang244d0b119ff4
diff --git a/apps/docsite/src/__tests__/example-coverage.test.ts b/apps/docsite/src/__tests__/example-coverage.test.tsindex 84d9fafe94..e98e4c46c8 100644--- a/apps/docsite/src/__tests__/example-coverage.test.ts+++ b/apps/docsite/src/__tests__/example-coverage.test.ts@@ -9,16 +9,19 @@* runnable demo) is visible in CI logs. This is a REPORT, not a gate: Core* does not require pairing and integration packages are intentionally no* stricter (owner decision, 2026-09-30); a repo-wide pairing gate remains an- * open decision.+ * open decision. It also prints each public hook with no hook doc or no+ * example block. That list is a report too and never fails the run.** @input Authored component docs and template descriptors across documented- * packages, plus the generated block registry- * @output CI-visible coverage inventory and regression coverage for- * authored-block admission into the registry+ * packages, committed API reports, plus the generated block and component+ * registries+ * @output CI-visible coverage inventory (components and public hooks) and+ * regression coverage for authored-block admission into the registry* @position Build-time docsite documentation-coverage reporting* Run: pnpm -F @astryxdesign/docsite test*/+import * as fs from 'node:fs';import * as path from 'node:path';import {describe, expect, it} from 'vitest';import docsiteConfig from '../../astryx.config.mjs';@@ -27,14 +30,19 @@ import {pairExampleCoverage,formatCoverageReport,resolveTemplatesRoot,+ readReportedHooks,+ pairHookExampleCoverage,+ formatHookCoverageReport,} from '../lib/exampleCoverage.mjs';import {blocks as registeredBlocks} from '../generated/blockRegistry';+import {components as registeredEntries} from '../generated/componentRegistry';import {packages} from '../generated/packageRegistry';const REPO_ROOT = path.resolve(__dirname, '../../../..');interface PackageInventory {packageName: string;+ packageDir: string;components: Awaited<ReturnType<typeof inventoryPackageExamples>>['components'];@@ -58,31 +66,38 @@ async function inventoryIntegration(});return {packageName,+ packageDir,components,blocks,coverage: pairExampleCoverage(components, blocks),};}+async function inventoryAllPackages(): Promise<PackageInventory[]> {+ const inventories: PackageInventory[] = [];+ for (const packageName of docsiteConfig.integrations) {+ inventories.push(await inventoryIntegration(packageName));+ }+ // Core authors its runnable blocks centrally in the CLI's assets tree.+ const coreDir = path.join(REPO_ROOT, 'packages/core');+ const {components, blocks} = await inventoryPackageExamples({+ repoRoot: REPO_ROOT,+ srcDir: path.join(coreDir, 'src'),+ blocksDir: path.join(REPO_ROOT, 'packages/cli/assets/templates/blocks'),+ });+ inventories.push({+ packageName: '@astryxdesign/core',+ packageDir: coreDir,+ components,+ blocks,+ coverage: pairExampleCoverage(components, blocks),+ });+ return inventories;+}+describe('example coverage (report-only)', () => {it('reports authored example-label ↔ runnable-block coverage per package', async () => {- const inventories: PackageInventory[] = [];- for (const packageName of docsiteConfig.integrations) {- inventories.push(await inventoryIntegration(packageName));- }- // Core authors its runnable blocks centrally in the CLI's assets tree.- const {components, blocks} = await inventoryPackageExamples({- repoRoot: REPO_ROOT,- srcDir: path.join(REPO_ROOT, 'packages/core/src'),- blocksDir: path.join(REPO_ROOT, 'packages/cli/assets/templates/blocks'),- });- inventories.push({- packageName: '@astryxdesign/core',- components,- blocks,- coverage: pairExampleCoverage(components, blocks),- });-+ const inventories = await inventoryAllPackages();for (const inventory of inventories) {// Write straight to stdout: vitest's console interceptor hides// console.* output for passing tests, and this report's whole job is@@ -99,6 +114,101 @@ describe('example coverage (report-only)', () => {}}, 120_000);+ it('reports public hooks with no hook doc or no example block', async () => {+ const inventories = await inventoryAllPackages();+ // A block in any package can be the example for a hook.+ const allBlocks = inventories.flatMap(inventory => inventory.blocks);+ for (const inventory of inventories) {+ const reportPath = path.join(inventory.packageDir, 'api-report.md');+ if (!fs.existsSync(reportPath)) {+ continue;+ }+ const hooks = readReportedHooks(fs.readFileSync(reportPath, 'utf8'));+ // The generator gives a hook page params; other pages get null.+ const hookDocNames = new Set(+ (registeredEntries[inventory.packageName] ?? [])+ .filter(entry => entry.params != null)+ .map(entry => entry.name),+ );+ if (hooks.length === 0) {+ continue;+ }+ process.stdout.write(+ formatHookCoverageReport(+ inventory.packageName,+ pairHookExampleCoverage(hooks, hookDocNames, allBlocks),+ ) + '\n',+ );+ }+ }, 120_000);++ it('reads hook names only from Hooks sections, once each', () => {+ const report = [+ '## `.`',+ '### Hooks',+ '```text',+ 'hook useAlpha: () => void',+ 'hook useBeta',+ ' (value: string): void',+ ' (value: number): void',+ '```',+ '### Functions',+ '```text',+ 'hook useNotAHook: () => void',+ '```',+ '## `./Beta`',+ '### Hooks',+ '```text',+ 'hook useBeta',+ '```',+ ].join('\n');+ expect(readReportedHooks(report)).toEqual(['useAlpha', 'useBeta']);+ });++ it('counts only loaded blocks that name the hook', () => {+ const block = {+ file: 'x.doc.mjs',+ type: 'block' as const,+ exampleFor: null,+ alsoExampleFor: [] as string[],+ isShowcase: false,+ hasSource: true,+ };+ const coverage = pairHookExampleCoverage(+ ['useAlpha', 'useBeta', 'useGamma'],+ new Set(['useAlpha']),+ [+ {...block, name: 'AlphaDemo', exampleFor: 'useAlpha'},+ {+ ...block,+ name: 'Shared',+ exampleFor: 'Card',+ alsoExampleFor: ['useBeta'],+ },+ {+ ...block,+ name: 'GammaPage',+ type: 'page' as const,+ exampleFor: 'useGamma',+ },+ {+ ...block,+ name: 'GammaBroken',+ exampleFor: 'useGamma',+ loadError: 'boom',+ },+ ],+ );+ expect(coverage).toEqual([+ {hook: 'useAlpha', hasDoc: true, exampleBlocks: ['AlphaDemo']},+ {hook: 'useBeta', hasDoc: false, exampleBlocks: ['Shared']},+ {hook: 'useGamma', hasDoc: false, exampleBlocks: []},+ ]);+ expect(formatHookCoverageReport('pkg', coverage)).toContain(+ 'no example block: useGamma',+ );+ });+it('admits every authored Lab block into the generated registry', async () => {// Authored → generated direction: a well-formed descriptor pair sitting in// packages/lab/blocks that never reaches blockRegistry would be a silentdiff --git a/apps/docsite/src/lib/exampleCoverage.mjs b/apps/docsite/src/lib/exampleCoverage.mjsindex 65349133f3..d9cfba472e 100644--- a/apps/docsite/src/lib/exampleCoverage.mjs+++ b/apps/docsite/src/lib/exampleCoverage.mjs@@ -14,22 +14,31 @@* unpaired label is a NAME mismatch, not proof the component has no demos —* blocks attach to a page via exampleFor regardless of name.*+ * It also lists each public hook (a hook in a committed API report) that has+ * no hook doc, or no block that names it in exampleFor/alsoExampleFor. The+ * caller supplies the hook-doc names from the generated component registry,+ * so the list matches the hook pages the docsite renders. It cannot tell+ * whether a block really demonstrates its hook; review checks that.+ ** REPORTS, NEVER GATES. Core does not require doc examples to have paired* blocks, and integration packages are intentionally no stricter (owner* decision, 2026-09-30). Whether example↔block pairing should gate CI is an* open repo-wide decision; until then tests print this inventory for CI-log* visibility only.*- * @input Authored component docs (src/X/X.doc.mjs) and template descriptors- * (the package's declared templates root, e.g. packages/lab/blocks)- * @output Per-component pairing of example labels to block names, plus- * structural findings (missing same-stem sources, descriptor load failures)+ * @input Authored component docs (src/X/X.doc.mjs), template descriptors+ * (the package's declared templates root, e.g. packages/lab/blocks), and+ * committed API reports (packages/X/api-report.md)+ * @output Per-component pairing of example labels to block names, structural+ * findings (missing same-stem sources, descriptor load failures), and+ * per-hook doc and example-block coverage* @position Shared by docsite reporting tests; no generator consumes this.*/import * as fs from 'node:fs';import * as path from 'node:path';import {pathToFileURL} from 'node:url';+import {parseReport} from '../../../../scripts/api-report/changes.mjs';/*** Basename prefix reserved for the automaticity test fixture@@ -204,6 +213,22 @@ export async function inventoryPackageExamples({repoRoot, srcDir, blocksDir}) {return {components, blocks, skippedTsDescriptors};}+/**+ * Loaded blocks that name `target` in `exampleFor` or `alsoExampleFor`.+ *+ * @param {AuthoredBlock[]} blocks+ * @param {string} target component or hook name+ * @returns {AuthoredBlock[]}+ */+function blocksAttributedTo(blocks, target) {+ return blocks.filter(+ block =>+ block.type === 'block' &&+ block.loadError == null &&+ (block.exampleFor === target || block.alsoExampleFor.includes(target)),+ );+}+/*** @typedef {object} ComponentCoverage* @property {string} component@@ -226,13 +251,7 @@ export async function inventoryPackageExamples({repoRoot, srcDir, blocksDir}) {*/export function pairExampleCoverage(components, blocks) {return components.map(component => {- const attributed = blocks.filter(- block =>- block.type === 'block' &&- block.loadError == null &&- (block.exampleFor === component.name ||- block.alsoExampleFor.includes(component.name)),- );+ const attributed = blocksAttributedTo(blocks, component.name);const pairedNames = attributed.map(block => block.name);const nameSet = new Set(pairedNames);return {@@ -294,3 +313,69 @@ export function formatCoverageReport(packageName, coverage, blocks) {}return lines.join('\n');}++/**+ * Hook names that an API report lists in its Hooks sections, sorted and+ * listed once each.+ *+ * @param {string} reportText content of a committed api-report.md+ * @returns {string[]}+ */+export function readReportedHooks(reportText) {+ const hookRows = [...parseReport(reportText).values()].filter(+ row => row.section === 'Hooks' && row.member == null,+ );+ return [+ ...new Set(hookRows.map(row => row.item.replace(/^hook /, ''))),+ ].sort();+}++/**+ * @typedef {object} HookCoverage+ * @property {string} hook+ * @property {boolean} hasDoc+ * @property {string[]} exampleBlocks names of blocks that name the hook+ */++/**+ * @param {string[]} hooks public hook names+ * @param {Set<string>} hookDocNames names of the hook pages the docsite renders+ * @param {AuthoredBlock[]} blocks+ * @returns {HookCoverage[]}+ */+export function pairHookExampleCoverage(hooks, hookDocNames, blocks) {+ return hooks.map(hook => ({+ hook,+ hasDoc: hookDocNames.has(hook),+ exampleBlocks: blocksAttributedTo(blocks, hook).map(block => block.name),+ }));+}++/**+ * Human-readable hook coverage for one package, for CI-log visibility.+ *+ * @param {string} packageName+ * @param {HookCoverage[]} coverage+ * @returns {string}+ */+export function formatHookCoverageReport(packageName, coverage) {+ const withoutDoc = coverage.filter(entry => !entry.hasDoc);+ const withoutExample = coverage.filter(+ entry => entry.exampleBlocks.length === 0,+ );+ const lines = [+ `hook example coverage — ${packageName}`,+ ` ${coverage.length} public hook(s); ${withoutDoc.length} without a hook doc; ${withoutExample.length} without a block naming them in exampleFor/alsoExampleFor`,+ ];+ if (withoutDoc.length > 0) {+ lines.push(+ ` - no hook doc: ${withoutDoc.map(entry => entry.hook).join(', ')}`,+ );+ }+ if (withoutExample.length > 0) {+ lines.push(+ ` - no example block: ${withoutExample.map(entry => entry.hook).join(', ')}`,+ );+ }+ return lines.join('\n');+}