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.mjsindex 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 APIadd('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.jsonindex 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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.jsonnew file mode 100644index 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"+ ]+}