Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): close api.d.ts drift and make typecheck guard the API implementation (#2559)

Joeyb0e136d1bcc5
diff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjs
index a3b89de1ec..cc42b0aa88 100644
--- a/.github/scripts/api-cli-parity-test.mjs
+++ b/.github/scripts/api-cli-parity-test.mjs
@@ -135,6 +135,17 @@ if (sample) {
() => apiCall(api.component, sample, {props: true, cwd: ROOT}));
add(`component ${sample} --source`, ['component', sample, '--source'],
() => apiCall(api.component, sample, {source: true, cwd: ROOT}));
+ // --showcase (component.detail.showcase) and --blocks (component.detail.blocks)
+ // exercise the two single-component result shapes the parity suite previously
+ // never touched. Skip gracefully if the sample component has no showcase so
+ // the suite stays green on component sets that lack one.
+ const showcaseProbe = cliJson(['component', sample, '--showcase']);
+ if (showcaseProbe.type === 'component.detail.showcase') {
+ add(`component ${sample} --showcase`, ['component', sample, '--showcase'],
+ () => apiCall(api.component, sample, {showcase: true, cwd: ROOT}));
+ }
+ add(`component ${sample} --blocks`, ['component', sample, '--blocks'],
+ () => apiCall(api.component, sample, {blocks: true, cwd: ROOT}));
}
// Component — error
@@ -146,12 +157,40 @@ add('docs (list)', ['docs'], () => apiCall(api.docs));
for (const topic of allTopics) {
add(`docs ${topic}`, ['docs', topic], () => apiCall(api.docs, topic));
}
+// Docs — section detail (docs.detail.section). Pick the first topic's first
+// section so the case is data-driven and exercises the two-arg path.
+if (allTopics.length > 0) {
+ const firstTopic = allTopics[0];
+ const topicDetail = cliJson(['docs', firstTopic]);
+ const firstSection = topicDetail.data?.sections?.[0]?.title;
+ if (firstSection) {
+ add(`docs ${firstTopic} ${firstSection}`, ['docs', firstTopic, firstSection],
+ () => apiCall(api.docs, firstTopic, firstSection));
+ }
+}
add('docs nonexistent', ['docs', 'nonexistent_xyz'],
() => apiCall(api.docs, 'nonexistent_xyz'));
// Template — uses API
add('template --list', ['template', '--list'],
() => apiCall(api.template));
+// Template — type filters (template.list filtered by page/block).
+add('template --list --type page', ['template', '--list', '--type', 'page'],
+ () => apiCall(api.template, undefined, {list: true, type: 'page', cwd: ROOT}));
+add('template --list --type block', ['template', '--list', '--type', 'block'],
+ () => apiCall(api.template, undefined, {list: true, type: 'block', cwd: ROOT}));
+// Template — show + skeleton for the first available template. These cover
+// template.show and template.skeleton, neither previously exercised.
+const templateList = cliJson(['template', '--list']);
+const firstTemplate = templateList.data && !templateList.error
+ ? templateList.data[0]?.name
+ : undefined;
+if (firstTemplate) {
+ add(`template ${firstTemplate}`, ['template', firstTemplate],
+ () => apiCall(api.template, firstTemplate, {cwd: ROOT}));
+ add(`template ${firstTemplate} --skeleton`, ['template', firstTemplate, '--skeleton'],
+ () => apiCall(api.template, firstTemplate, {skeleton: true, cwd: ROOT}));
+}
add('template nonexistent', ['template', 'nonexistent99'],
() => apiCall(api.template, 'nonexistent99'));
@@ -193,6 +232,11 @@ add('search (no match)', ['search', 'zzqqxx_no_match'],
add('search (bad type)', ['search', 'x', '--type', 'bogus'],
() => apiCall(api.search, 'x', {type: 'bogus', cwd: ROOT}));
+// Discover — list (discover.list). Covers the discover API surface; the CLI
+// envelope's optional `meta` sidecar is stripped by cliJson, matching the API.
+add('discover (list)', ['discover'],
+ () => apiCall(api.discover, undefined, {cwd: ROOT}));
+
// Other commands — probe with safe read-only args (no API yet)
const otherCommands = [
['swizzle', '--list'],
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 9386655a43..42509cb750 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -49,7 +49,7 @@
"scripts": {
"xds": "node bin/xds.mjs",
"typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
- "typecheck:json-api": "tsc --project tsconfig.json-api.json"
+ "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"
},
"dependencies": {
"@clack/prompts": "^1.5.1",
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index 3b62c4e469..1d491c1e54 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -395,6 +395,7 @@ export async function getTemplateById(id, options = {}) {
* @param {boolean} [options.list]
* @param {boolean} [options.skeleton]
* @param {boolean} [options.show]
+ * @param {'page'|'block'} [options.type] - Filter list views by template kind.
* @param {string} [options.cwd]
* @returns {Promise<{type: string, data: unknown}>}
*/
diff --git a/packages/cli/src/types/api.contract.assert.ts b/packages/cli/src/types/api.contract.assert.ts
new file mode 100644
index 0000000000..b9e6131c89
--- /dev/null
+++ b/packages/cli/src/types/api.contract.assert.ts
@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Compile-time guard that the runtime @xds/cli/api implementation matches the
+ * declared programmatic API surface in api.d.ts.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `typecheck:json-api` historically only checked the `.d.ts` declarations plus a
+ * couple of `lib/*.mjs` helpers — it never looked at `src/api/*.mjs`. So the
+ * hand-written declarations in `api.d.ts` could (and did) silently drift from
+ * what the runtime functions actually accept: the runtime `component()` gained
+ * `package`/`blocks` options and a `component.detail.blocks` result, and
+ * `template()` gained a `type` filter, none of which were reflected in
+ * `api.d.ts`. CI never caught it.
+ *
+ * Turning on full `checkJs` over the api implementations surfaces ~140
+ * pre-existing implicit-any JSDoc errors in transitively-imported `lib/*` and
+ * `utils/*` files that have nothing to do with the public API contract — an
+ * unmanageable cleanup for one PR (see PR body). Instead, this file pins the
+ * *option surface and arity* of each runtime function against the declared
+ * types. The check runs under a dedicated tsconfig with `checkJs: false`, so
+ * the implementation bodies are not re-typechecked — only their JSDoc-derived
+ * export signatures are read and compared.
+ *
+ * The JSDoc `@param` annotations on each `src/api/*.mjs` export are the source
+ * TypeScript reads for the runtime side, so keeping them in sync with
+ * `api.d.ts` is exactly what this guard enforces. If a runtime function adds an
+ * option the `.d.ts` omits (or vice versa), the corresponding `MutuallyEqual`
+ * assertion below fails and `typecheck:json-api` goes red.
+ */
+
+import type * as Api from './api';
+import type {component} from '../api/component.mjs';
+import type {docs} from '../api/docs.mjs';
+import type {discover} from '../api/discover.mjs';
+import type {template} from '../api/template.mjs';
+
+/** Resolve to `true` only when `A` and `B` are mutually assignable. */
+type Equal<A, B> =
+ (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
+ ? true
+ : false;
+
+/** Compile error unless `T` is exactly `true`. */
+type Expect<T extends true> = T;
+
+/** Drop `undefined` from an optional options parameter for comparison. */
+type Opt<T> = NonNullable<T>;
+
+// ── Option-bag parity: the declared options and the runtime JSDoc options
+// must describe the same set of keys/types, in both directions. ──────────────
+
+type _ComponentOptions = Expect<
+ Equal<Opt<Parameters<typeof Api.component>[1]>, Opt<Parameters<typeof component>[1]>>
+>;
+type _DocsOptions = Expect<
+ Equal<Opt<Parameters<typeof Api.docs>[2]>, Opt<Parameters<typeof docs>[2]>>
+>;
+type _DiscoverOptions = Expect<
+ Equal<Opt<Parameters<typeof Api.discover>[1]>, Opt<Parameters<typeof discover>[1]>>
+>;
+type _TemplateOptions = Expect<
+ Equal<Opt<Parameters<typeof Api.template>[1]>, Opt<Parameters<typeof template>[1]>>
+>;
+
+// ── Positional-argument parity: arity and positional types must match. ───────
+
+type _ComponentName = Expect<
+ Equal<Parameters<typeof Api.component>[0], Parameters<typeof component>[0]>
+>;
+type _DocsTopic = Expect<
+ Equal<Parameters<typeof Api.docs>[0], Parameters<typeof docs>[0]>
+>;
+type _DocsSection = Expect<
+ Equal<Parameters<typeof Api.docs>[1], Parameters<typeof docs>[1]>
+>;
+type _DiscoverQuery = Expect<
+ Equal<Parameters<typeof Api.discover>[0], Parameters<typeof discover>[0]>
+>;
+type _TemplateName = Expect<
+ Equal<Parameters<typeof Api.template>[0], Parameters<typeof template>[0]>
+>;
+
+// Surface the assertion aliases so the file has a value/type export and the
+// checks above are not tree-shaken away by `noUnusedLocals`.
+export type _ApiContractGuard = [
+ _ComponentOptions,
+ _DocsOptions,
+ _DiscoverOptions,
+ _TemplateOptions,
+ _ComponentName,
+ _DocsTopic,
+ _DocsSection,
+ _DiscoverQuery,
+ _TemplateName,
+];
diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.ts
index f2e5b587fc..bb8f8dfe0c 100644
--- a/packages/cli/src/types/api.d.ts
+++ b/packages/cli/src/types/api.d.ts
@@ -15,6 +15,7 @@ import type {
ComponentDetailPropsResponse,
ComponentDetailSourceResponse,
ComponentDetailShowcaseResponse,
+ ComponentDetailBlocksResponse,
} from './component';
import type {
DocsListResponse,
@@ -62,9 +63,13 @@ export interface ComponentOptions {
cwd?: string;
list?: boolean;
category?: string;
+ /** Scope lookup to a specific external package (e.g. '@acme/xds-widgets'). */
+ package?: string;
props?: boolean;
source?: boolean;
showcase?: boolean;
+ /** List example blocks for the component: showcase, examples, and related. */
+ blocks?: boolean;
detail?: 'full' | 'compact' | 'brief';
lang?: string;
zh?: boolean;
@@ -78,7 +83,8 @@ type ComponentResult =
| ComponentDetailResponse
| ComponentDetailPropsResponse
| ComponentDetailSourceResponse
- | ComponentDetailShowcaseResponse;
+ | ComponentDetailShowcaseResponse
+ | ComponentDetailBlocksResponse;
export declare function component(
name?: string,
@@ -129,6 +135,8 @@ export interface TemplateOptions {
list?: boolean;
skeleton?: boolean;
show?: boolean;
+ /** Filter templates by kind: 'page' or 'block'. Only applies to list views. */
+ type?: 'page' | 'block';
targetPath?: string;
cwd?: string;
}
diff --git a/packages/cli/src/types/discover.d.ts b/packages/cli/src/types/discover.d.ts
index 05ef92c72c..d5eb188c05 100644
--- a/packages/cli/src/types/discover.d.ts
+++ b/packages/cli/src/types/discover.d.ts
@@ -19,6 +19,11 @@ import type {ComponentDoc} from '../../../core/src/docs-types';
export interface DiscoverListResponse {
type: 'discover.list';
data: DiscoverListEntry[];
+ /**
+ * Present when the list is empty so callers can distinguish "no packages
+ * configured" from "configured but nothing discovered".
+ */
+ meta?: {configured: boolean};
}
export interface DiscoverListEntry {
diff --git a/packages/cli/src/types/template.d.ts b/packages/cli/src/types/template.d.ts
index af3673a359..a8bcfd3ae2 100644
--- a/packages/cli/src/types/template.d.ts
+++ b/packages/cli/src/types/template.d.ts
@@ -22,9 +22,11 @@ export interface TemplateListResponse {
export interface TemplateListEntry {
name: string;
+ displayName: string;
description: string;
isReady: boolean;
scaffold?: boolean;
+ type: 'page' | 'block';
}
/** xds --json template <name> */
@@ -33,6 +35,7 @@ export interface TemplateShowResponse {
data: {
template: string;
description: string;
+ type: 'page' | 'block';
components: string[];
source: string;
};
@@ -52,7 +55,12 @@ export interface TemplateSkeletonResponse {
/** xds --json template <name> [path] */
export interface TemplateCopyResponse {
type: 'template.copy';
- data: {template: string; outputDir: string; filesCopied: number};
+ data: {
+ template: string;
+ outputDir: string;
+ fileName: string;
+ filesCopied: number;
+ };
}
/** xds --json template get --id <id> */
diff --git a/packages/cli/tsconfig.api-contract.json b/packages/cli/tsconfig.api-contract.json
new file mode 100644
index 0000000000..c9e7c1f32d
--- /dev/null
+++ b/packages/cli/tsconfig.api-contract.json
@@ -0,0 +1,15 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "../..",
+ "allowJs": true,
+ "checkJs": false,
+ "noEmit": true,
+ "types": ["node"]
+ },
+ "include": [
+ "src/types/**/*.d.ts",
+ "src/types/api.contract.assert.ts",
+ "../core/src/docs-types.ts"
+ ]
+}