Skip to content

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

TypeScript

docs(cli): name every field of eight responses in the response-type docs (#6588)

Joey4fb81b07d85a
diff --git a/.changeset/cli-spec-response-type-fields.md b/.changeset/cli-spec-response-type-fields.md
new file mode 100644
index 0000000000..0ea2fad726
--- /dev/null
+++ b/.changeset/cli-spec-response-type-fields.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] The response-type docs, and the CLI README table generated from them, now name the fields of the `component.detail`, `docs.index`, `search`, `build.kit`, `gap-report.file`, `theme.build`, `theme.targets`, and `integration.pack-check` responses by their JSON keys, including `parentDoc`, `hint`, `notices`, `deprecatedFor`, each gap-report delivery's fields, and the pack-check contribution identities and issue fields. The `component.detail` response type declares `parentDoc`.
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 000550fe0b..adc09582e5 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -397,63 +397,63 @@ Every response has a `type` discriminant. The full set is below (generated from
<!-- BEGIN GENERATED: response-types -->
-| Type | What `data` carries |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
-| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set. |
-| `component.list` | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry. |
-| `component.detail` | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available). |
-| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). |
-| `component.detail.source` | One component's source file, as {component, source}. |
-| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. |
-| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry. |
-| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order. |
-| `docs.detail` | One topic's full ReferenceDoc, with token-ref blocks inlined. |
-| `docs.index` | One topic's section index (--index): each section's key, title, and one-line summary. |
-| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined. |
-| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
-| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
-| `discover.list` | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered". |
-| `discover.detail` | A single external package entry, for an @scope/name query. |
-| `discover.detail.doc` | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component. |
-| `discover.search` | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components. |
-| `search` | The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant). |
-| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
-| `build.kit` | The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays. |
-| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. |
-| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. |
-| `gap-report.categories` | The fixed gap category values and human-readable labels. |
-| `gap-report.file` | An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals. |
-| `template.list` | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. |
-| `template.show` | The resolved template's raw source plus its description, kind, and the component names it composes. |
-| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. |
-| `template.copy` | A scaffold receipt: template id, output directory, written file name, and file count. |
-| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
-| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. |
-| `hook.detail` | One hook's full authored HookDoc. |
-| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). |
-| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |
-| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |
-| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |
-| `theme.list` | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package. |
-| `theme.add` | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written. |
-| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
-| `theme.targets` | The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys. |
-| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
-| `upgrade.list` | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. |
-| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
-| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. |
-| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index. |
-| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status. |
-| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
-| `integration.pack-check` | The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues. |
-| `integration.validate` | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |
-| `integration.template-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command. |
-| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. |
-| `integration.doc-conflicts` | The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts. |
-| `layout.expand` | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
-| `layout.check` | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline). |
-| `layout.grammar` | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry. |
+| Type | What `data` carries |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
+| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set. |
+| `component.list` | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry. |
+| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). |
+| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). |
+| `component.detail.source` | One component's source file, as {component, source}. |
+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. |
+| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry. |
+| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order. |
+| `docs.detail` | One topic's full ReferenceDoc, with token-ref blocks inlined. |
+| `docs.index` | One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary). |
+| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined. |
+| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
+| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
+| `discover.list` | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered". |
+| `discover.detail` | A single external package entry, for an @scope/name query. |
+| `discover.detail.doc` | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component. |
+| `discover.search` | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components. |
+| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates). |
+| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
+| `build.kit` | The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin. |
+| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. |
+| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. |
+| `gap-report.categories` | The fixed gap category values and human-readable labels. |
+| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals. |
+| `template.list` | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. |
+| `template.show` | The resolved template's raw source plus its description, kind, and the component names it composes. |
+| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. |
+| `template.copy` | A scaffold receipt: template id, output directory, written file name, and file count. |
+| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
+| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. |
+| `hook.detail` | One hook's full authored HookDoc. |
+| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). |
+| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |
+| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |
+| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |
+| `theme.list` | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package. |
+| `theme.add` | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written. |
+| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
+| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key. |
+| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
+| `upgrade.list` | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. |
+| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
+| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. |
+| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index. |
+| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status. |
+| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
+| `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
+| `integration.validate` | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |
+| `integration.template-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command. |
+| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. |
+| `integration.doc-conflicts` | The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts. |
+| `layout.expand` | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
+| `layout.check` | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline). |
+| `layout.grammar` | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry. |
<!-- END GENERATED: response-types -->
<!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index f55d991db5..cb6d55a8b5 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -36,7 +36,7 @@ export const doc = {
{
value: 'component.detail',
description:
- "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).",
+ "One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).",
},
{
value: 'component.detail.props',
@@ -71,7 +71,7 @@ export const doc = {
{
value: 'docs.index',
description:
- "One topic's section index (--index): each section's key, title, and one-line summary.",
+ "One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).",
},
{
value: 'docs.detail.section',
@@ -116,7 +116,7 @@ export const doc = {
{
value: 'search',
description:
- 'The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+ 'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).',
},
// build
@@ -128,7 +128,7 @@ export const doc = {
{
value: 'build.kit',
description:
- 'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',
+ 'The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.',
},
// swizzle
@@ -151,7 +151,7 @@ export const doc = {
{
value: 'gap-report.file',
description:
- 'An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.',
+ 'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
},
// template
@@ -228,7 +228,7 @@ export const doc = {
{
value: 'theme.targets',
description:
- 'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
+ 'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',
},
{
value: 'theme.palette.generate',
@@ -276,7 +276,7 @@ export const doc = {
{
value: 'integration.pack-check',
description:
- 'The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.',
+ 'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
},
{
value: 'integration.validate',
diff --git a/packages/cli/foundation/response/response-types.doc.test.mjs b/packages/cli/foundation/response/response-types.doc.test.mjs
new file mode 100644
index 0000000000..c5cf1953fe
--- /dev/null
+++ b/packages/cli/foundation/response/response-types.doc.test.mjs
@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The response-types EnumDoc names every field of the responses below,
+ * nested entry fields included. Fields come from real responses where one is
+ * cheap to produce, else from the canonical typedef.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {describe, it, expect} from 'vitest';
+import {doc} from './response-types.doc.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+/** @param {string} type */
+const describedAs = (type) => doc.members.find((m) => m.value === type)?.description ?? '';
+
+/** @param {string} text @param {string} field */
+const names = (text, field) => new RegExp(`(^|\\W)${field}(\\W|$)`).test(text);
+
+/**
+ * Keys of an object, plus the keys of each nested object or array entry, `depth`
+ * levels down.
+ * @param {unknown} value @param {number} depth @returns {Set<string>}
+ */
+function fieldsOf(value, depth = 2) {
+ const out = new Set();
+ const visit = (/** @type {unknown} */ v, /** @type {number} */ d) => {
+ if (Array.isArray(v)) return v.forEach((item) => visit(item, d));
+ if (!v || typeof v !== 'object' || d < 0) return;
+ for (const [key, child] of Object.entries(v)) {
+ out.add(key);
+ visit(child, d - 1);
+ }
+ };
+ visit(value, depth);
+ return out;
+}
+
+/** @param {string[]} args @param {string} [cwd] */
+async function data(args, cwd) {
+ const {status, stdout} = await runCli(['--json', ...args], cwd ? {cwd} : undefined);
+ expect(status, stdout).toBe(0);
+ return JSON.parse(stdout);
+}
+
+/** @param {string} type @param {Iterable<string>} fields */
+function expectNamed(type, fields) {
+ const text = describedAs(type);
+ const missing = [...fields].filter((f) => !names(text, f));
+ expect(missing, `${type} omits`).toEqual([]);
+}
+
+describe('response-types EnumDoc names every field', () => {
+ it('component.detail: the ownership fields and parentDoc', async () => {
+ const res = await data(['component', 'HStack']);
+ expect(res.type).toBe('component.detail');
+ const ownership = ['package', 'import', 'sourceAvailable', 'parentDoc'];
+ for (const f of ownership) expect(Object.keys(res.data)).toContain(f);
+ expectNamed('component.detail', ownership);
+ // The canonical response type declares parentDoc too.
+ const types = fs.readFileSync(
+ new URL('../../api/component/component.type.mjs', import.meta.url),
+ 'utf8',
+ );
+ expect(types).toMatch(/@property \{string\} \[parentDoc\]/);
+ });
+
+ it('docs.index', async () => {
+ const res = await data(['docs', 'theme', '--index']);
+ expect(res.type).toBe('docs.index');
+ expectNamed('docs.index', fieldsOf(res.data));
+ });
+
+ it('search, across component, hook, template, and doc results', async () => {
+ const mixed = await data(['search', 'dashboard', '--limit', '50']);
+ const docsOnly = await data(['search', 'tokens', '--type', 'doc']);
+ expect(new Set(mixed.data.results.map((r) => r.domain))).toContain('template');
+ expectNamed('search', new Set([...fieldsOf(mixed.data), ...fieldsOf(docsOnly.data)]));
+ });
+
+ it('build.kit, including the hint a thin kit carries', async () => {
+ const res = await data(['build', 'zzqx-nothing-matches']);
+ expect(res.type).toBe('build.kit');
+ expect(res.data.hint).toBeDefined();
+ const fields = fieldsOf(res.data, 0);
+ for (const f of Object.keys(res.data.hint)) fields.add(f);
+ expectNamed('build.kit', fields);
+ });
+
+ it('theme.targets, including deprecatedFor', async () => {
+ const res = await data(['theme', 'targets']);
+ const fields = fieldsOf(res.data);
+ expect(fields).toContain('deprecatedFor');
+ expectNamed('theme.targets', fields);
+ });
+
+ it('gap-report.file, including each delivery', async () => {
+ const res = await data(['gap-report', 'Button', '--category', 'docs_gap', '--reason', 'probe']);
+ expect(res.type).toBe('gap-report.file');
+ expect(res.data.deliveries.length).toBeGreaterThan(0);
+ expectNamed('gap-report.file', fieldsOf(res.data));
+ });
+
+ it('theme.build, including notices', async () => {
+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-response-types-'));
+ fs.writeFileSync(path.join(cwd, 'package.json'), '{"name":"app","version":"1.0.0"}');
+ await data(['theme', 'template', 'starter.ts'], cwd);
+ const res = await data(['theme', 'build', 'starter.ts', '--out', 'starter.css'], cwd);
+ expect(res.type).toBe('theme.build');
+ expectNamed('theme.build', fieldsOf(res.data));
+ });
+
+ it('integration.pack-check (fields from api/integration/pack-check.type.mjs)', () => {
+ expectNamed('integration.pack-check', [
+ // PackCheckData
+ 'name',
+ 'version',
+ 'packable',
+ 'tarball',
+ 'inventory',
+ 'contributions',
+ 'issues',
+ // PackCheckTarball
+ 'filename',
+ 'fileCount',
+ 'size',
+ 'unpackedSize',
+ // PackCheckInventory and PackCheckInventoryRoot
+ 'manifest',
+ 'roots',
+ 'kind',
+ 'path',
+ 'expectedFiles',
+ 'missingFiles',
+ 'complete',
+ 'packedFiles',
+ // contributions, each ContributionIdentities
+ 'local',
+ 'packed',
+ 'themes',
+ 'slug',
+ 'exportName',
+ 'components',
+ 'templates',
+ 'id',
+ 'type',
+ 'codemods',
+ 'docs',
+ 'agentDocsAppend',
+ // issues, each AstryxIntegrationIssue
+ 'code',
+ 'severity',
+ 'message',
+ ]);
+ });
+});