Skip to content

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.ts
index 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 silent
diff --git a/apps/docsite/src/lib/exampleCoverage.mjs b/apps/docsite/src/lib/exampleCoverage.mjs
index 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');
+}