@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/authoring/doctypes/_schema.mjs

@@ -11,10 +11,20 @@
 
 import {z} from 'zod';
 
-/** @typedef {import('./base/type').AuthoredDocGraphFields} AuthoredDocGraphFieldsType */
-/** @typedef {import('./base/type').AuthoredDocKind} AuthoredDocKind */
-/** @typedef {import('./namespace/type').NamespaceDoc} NamespaceDoc */
-/** @typedef {import('./reference/type').ReferenceContentBlock} ReferenceContentBlock */
+/** @typedef {import('./base/type.js').AuthoredDocGraphFields} AuthoredDocGraphFieldsType */
+/** @typedef {import('./base/type.js').AuthoredDocKind} AuthoredDocKind */
+/** @typedef {import('./namespace/type.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./reference/type.js').ReferenceContentBlock} ReferenceContentBlock */
+/** @typedef {import('./reference/type.js').GraphContentBlock} GraphContentBlock */
+/** @typedef {import('./reference/type.js').ReferenceSection} ReferenceSection */
+/** @typedef {import('./reference/type.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./component/type.js').SingleComponentDoc} SingleComponentDoc */
+/** @typedef {import('./base/type.js').ComponentPropDoc} ComponentPropDoc */
+/** @typedef {import('./hook/type.js').HookDoc} HookDoc */
+/** @typedef {import('./function/type.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./schema/type.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./command/type.js').CommandDoc} CommandDoc */
+/** @typedef {import('./enum/type.js').EnumDoc} EnumDoc */
 
 const nonEmptyString = z.string().min(1);
 
@@ -31,6 +41,12 @@ export const AuthoredDocKindSchema = z.enum([
   'namespace',
 ]);
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof AuthoredDocKindSchema>, AuthoredDocKind>
+ * >} _AuthoredDocKindDriftLock
+ */
+
 /** Shared optional graph fields for every authored doc kind. */
 export const AuthoredDocGraphFields = {
   placement: z
@@ -48,8 +64,8 @@ export const AuthoredDocGraphFields = {
 const _AuthoredDocGraphSchema = z.object(AuthoredDocGraphFields).strict();
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
  *     z.infer<typeof _AuthoredDocGraphSchema>,
  *     AuthoredDocGraphFieldsType
  *   >
@@ -147,7 +163,7 @@ const ReferenceBlockSchema = z
   })
   .strict();
 
-/** Runtime schema for every existing and V1 semantic content block. */
+/** Runtime schema for the stable content-block union published in 0.6.x. */
 export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
   ProseBlockSchema,
   HeadingBlockSchema,
@@ -155,26 +171,75 @@ export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
   TableBlockSchema,
   ListBlockSchema,
   TokenReferenceBlockSchema,
+]);
+
+/** Runtime schema for graph-only blocks used by NamespaceDoc. */
+export const GraphContentBlockSchema = z.discriminatedUnion('type', [
+  WorkflowBlockSchema,
+  CollectionBlockSchema,
+  ReferenceBlockSchema,
+]);
+
+/**
+ * A topic section's blocks: the stable union, plus a reference block, which a
+ * read inlines as the doc it includes.
+ */
+export const SectionContentBlockSchema = z.discriminatedUnion('type', [
+  ProseBlockSchema,
+  HeadingBlockSchema,
+  CodeBlockSchema,
+  TableBlockSchema,
+  ListBlockSchema,
+  TokenReferenceBlockSchema,
+  ReferenceBlockSchema,
+]);
+
+/** Namespace content accepts both stable reference blocks and graph-only blocks. */
+export const NamespaceContentBlockSchema = z.discriminatedUnion('type', [
+  ProseBlockSchema,
+  HeadingBlockSchema,
+  CodeBlockSchema,
+  TableBlockSchema,
+  ListBlockSchema,
+  TokenReferenceBlockSchema,
   WorkflowBlockSchema,
   CollectionBlockSchema,
   ReferenceBlockSchema,
 ]);
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof ReferenceContentBlockSchema>,
  *     ReferenceContentBlock
  *   >
  * >} _ReferenceContentBlockDriftLock
  */
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
+ *     z.infer<typeof GraphContentBlockSchema>,
+ *     GraphContentBlock
+ *   >
+ * >} _GraphContentBlockDriftLock
+ */
+
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
+ *     z.infer<typeof SectionContentBlockSchema>,
+ *     ReferenceSection['content'][number]
+ *   >
+ * >} _SectionContentBlockDriftLock
+ */
+
 const ReferenceSectionSchema = z
   .object({
     id: nonEmptyString.optional(),
     title: nonEmptyString,
     category: z.string().optional(),
-    content: z.array(ReferenceContentBlockSchema),
+    content: z.array(SectionContentBlockSchema),
     previewType: z
       .enum([
         'swatch',
@@ -245,11 +310,58 @@ const ComponentBaseSchema = z
   })
   .passthrough();
 
-/** New-format stamped component doc (`type: 'component'`). */
+/**
+ * One entry in a group doc's `components`: a full ComponentEntry or a
+ * name-only ComponentRef. Readers look every entry up by `name`, so that much
+ * is checked here; the rest passes through, as on an unstamped doc.
+ */
+const ComponentGroupEntrySchema = z
+  .object({name: z.string().min(1, 'component name is required')})
+  .passthrough();
+
+/**
+ * New-format stamped component doc (`type: 'component'`): one component's
+ * `props`, or the `components` a group doc documents together. These are the
+ * shapes the published ComponentDoc type allows, and the ones an unstamped doc
+ * may already take.
+ */
 export const ComponentDocKindSchema = ComponentBaseSchema.extend({
-  props: z.array(PropSchema),
+  props: z.array(PropSchema).optional(),
+  components: z.array(ComponentGroupEntrySchema).optional(),
+}).superRefine((doc, context) => {
+  if (doc.props == null && doc.components == null) {
+    context.addIssue({
+      code: 'custom',
+      path: ['props'],
+      message:
+        'expected the props array, or `components` for a doc that groups several components',
+    });
+  }
 });
 
+/**
+ * A stamped component doc as it loads. The loader accepts what the unstamped
+ * format always accepted, so stamping an existing doc never breaks it:
+ * `displayName` may be missing, `category` is any string, `usage`, `theming`,
+ * `playground` and `examples` pass through unchecked, and a doc has `props`,
+ * `components`, or both; each `components` entry needs only a `name`. Every
+ * other field matches the published type.
+ *
+ * @typedef {Omit<SingleComponentDoc,
+ *     'type' | 'displayName' | 'category' | 'usage' | 'theming' | 'examples' | 'playground' | 'props'>
+ *   & {type: 'component', displayName?: string, category?: string, usage?: unknown,
+ *     theming?: unknown, examples?: unknown[], playground?: unknown,
+ *     props?: ComponentPropDoc[], components?: Array<{name: string}>}} LoadedComponentDoc
+ */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof ComponentDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<LoadedComponentDoc>
+ *   >
+ * >} _ComponentDocDriftLock
+ */
+
 /** Return entry for generalized function docs. */
 const FunctionReturnSchema = z
   .object({
@@ -269,6 +381,28 @@ export const FunctionDocKindSchema = z
   })
   .passthrough();
 
+/**
+ * A stamped function doc as it loads: as with components, `displayName` may be
+ * missing and `usage` passes through unchecked.
+ *
+ * @typedef {Omit<FunctionDoc, 'type' | 'displayName' | 'usage'>
+ *   & {type: 'function', displayName?: string, usage?: unknown}} LoadedFunctionDoc
+ */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof FunctionDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<LoadedFunctionDoc>
+ *   >
+ * >} _FunctionDocDriftLock
+ */
+
+/**
+ * Every HookDoc is a FunctionDoc, so the one function schema covers both.
+ *
+ * @typedef {import('../_shared/contract.js').Expect<[HookDoc] extends [FunctionDoc] ? true : false>} _HookDocIsFunctionDocLock
+ */
+
 /**
  * Stamped generic reference/topic doc (`type: 'generic'`). `title` and
  * `sections` stay optional at this parser boundary for docs produced by the
@@ -308,9 +442,30 @@ export const GenericDocKindSchema = z
     });
   });
 
+/**
+ * A stamped generic doc as the load check accepts it. `title`, `description`
+ * and `sections` may be missing, as in docs the v0.3.0 factory-removal codemod
+ * produced; `parseReference` then fills them (title from `displayName` or
+ * `name`, an empty description, no sections), so its result is a full
+ * ReferenceDoc. Only a doc with a description and sections is a usable topic
+ * (see `problemsInTopic`).
+ *
+ * @typedef {Omit<ReferenceDoc, 'type' | 'title' | 'description' | 'sections'>
+ *   & {type: 'generic'}
+ *   & Partial<Pick<ReferenceDoc, 'title' | 'description' | 'sections'>>} LoadedReferenceDoc
+ */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof GenericDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<LoadedReferenceDoc>
+ *   >
+ * >} _ReferenceDocDriftLock
+ */
+
 /** Recursive field descriptor for a SchemaDoc. */
 const SchemaFieldSchema =
-  /** @type {import('zod').ZodType<import('./schema/type').SchemaFieldDoc>} */ (
+  /** @type {import('zod').ZodType<import('./schema/type.js').SchemaFieldDoc>} */ (
     z.lazy(() =>
       z
         .object({
@@ -351,6 +506,15 @@ export const SchemaDocKindSchema = z
   })
   .passthrough();
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof SchemaDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<SchemaDoc & {type: 'schema'}>
+ *   >
+ * >} _SchemaDocDriftLock
+ */
+
 /** New stamped command doc (`type: 'command'`). */
 export const CommandDocKindSchema = z
   .object({
@@ -411,6 +575,15 @@ export const CommandDocKindSchema = z
   })
   .passthrough();
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof CommandDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<CommandDoc & {type: 'command'}>
+ *   >
+ * >} _CommandDocDriftLock
+ */
+
 /** New stamped enum doc (`type: 'enum'`). */
 export const EnumDocKindSchema = z
   .object({
@@ -432,6 +605,15 @@ export const EnumDocKindSchema = z
   })
   .passthrough();
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof EnumDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<EnumDoc & {type: 'enum'}>
+ *   >
+ * >} _EnumDocDriftLock
+ */
+
 const NamespaceSlotSchema = z
   .object({
     title: nonEmptyString,
@@ -474,7 +656,7 @@ export const NamespaceDocKindSchema = z
           .strict(),
       )
       .optional(),
-    blocks: z.array(ReferenceContentBlockSchema).optional(),
+    blocks: z.array(NamespaceContentBlockSchema).optional(),
   })
   .strict()
   .superRefine((doc, context) => {
@@ -514,8 +696,8 @@ export const NamespaceDocKindSchema = z
   });
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof NamespaceDocKindSchema>,
  *     NamespaceDoc
  *   >

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -12,25 +12,27 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    'Optional placement, compatibility aliases, and audience fields shared by every authored documentation kind.',
+    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
   appliesTo: 'Every supported .doc.mjs object',
   fields: [
     {
       name: 'placement',
       type: 'DocPlacement',
       description:
-        'Requests one canonical parent. The compiler fails invalid explicit placement instead of silently using Unorganized.',
+        "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also `replaces` or `extends` a topic. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
       fields: [
         {
           name: 'placement.parent',
           type: 'string',
-          description: 'Stable reference to the requested parent namespace.',
+          description:
+            'The parent namespace: `namespace:<name>` in the same package.',
           required: true,
         },
         {
           name: 'placement.slot',
           type: 'string',
-          description: 'Named slot owned by the parent namespace.',
+          description:
+            "A slot the parent namespace declares; it must accept this doc's kind. Optional when the parent has one slot.",
         },
         {
           name: 'placement.order',
@@ -43,13 +45,20 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes retained for compatibility. Aliases do not create another identity.',
+        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
     },
     {
       name: 'audience',
       type: "'public' | 'internal'",
-      description: 'Bundle audience. Omit for public documentation.',
+      description:
+        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
       default: "'public'",
     },
   ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'Unknown fields: `component`, `function`, `generic`, `schema`, `command` and `enum` docs accept a field they do not know, and nothing reads it, so a doc written for a newer CLI still loads here. `page`, `block` and `namespace` docs refuse one, as do `theme` descriptors. Sections and content blocks refuse one in every doc.',
+    },
+  ],
 };

package/authoring/doctypes/base/type.ts

@@ -30,13 +30,18 @@ export interface DocPlacement {
   order?: number;
 }
 
-/** Graph metadata shared by every authored doc kind. */
+/**
+ * Tree metadata shared by every authored doc kind. The docs tree reads
+ * `placement` for every guide, the CLI's and each integration's
+ * (spec:AST-046); nothing reads `aliases` or `audience` yet. A reference topic
+ * outside the docs tree that sets one fails to load.
+ */
 export interface AuthoredDocGraphFields {
-  /** Requested canonical parent. Omit to use source adoption or Unorganized. */
+  /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Prior routes or names that must continue to resolve to this stable doc. */
+  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
   aliases?: string[];
-  /** Bundle audience. Omit for public docs. */
+  /** Docs bundle audience; omit for public docs. Not read yet. */
   audience?: DocAudience;
 }
 

package/authoring/doctypes/command/command.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path. Defaults to 'cli' when applied by the docs index.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -135,8 +135,9 @@ export const doc = {
         },
         {
           name: 'options[].default',
-          type: 'string',
-          description: 'Default value as a string.',
+          type: 'string | boolean | string[]',
+          description:
+            'Default value: a string, a boolean, or a list of strings.',
         },
         {
           name: 'options[].cliOnly',

package/authoring/doctypes/command/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').CommandDoc} CommandDoc */
+/** @typedef {import('../types.js').CommandDoc} CommandDoc */
 /**
  * Validate an unknown value as a stamped command doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {CommandDoc}
  */
 export function parseCommand(input: unknown, label?: string): CommandDoc;
-export type CommandDoc = import("../types").CommandDoc;
+export type CommandDoc = import("../types.js").CommandDoc;

package/authoring/doctypes/command/parse.mjs

@@ -8,7 +8,7 @@
 import {CommandDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').CommandDoc} CommandDoc */
+/** @typedef {import('../types.js').CommandDoc} CommandDoc */
 
 /**
  * Validate an unknown value as a stamped command doc, or throw.

package/authoring/doctypes/command/type.ts

@@ -9,8 +9,8 @@
  * `--help`. Colocated at `clients/cli/commands/<name>.doc.mjs`.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /** A positional argument. `param` links it to a FunctionDoc param for its description. */
 export interface CommandArgDoc {
@@ -65,7 +65,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   summary: string;
   /** Longer help body / when-to-use. */
   description?: string;
-  /** Docs namespace path. Defaults to 'cli' when applied by the docs index. */
+  /** The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];
@@ -81,7 +81,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   examples?: CommandExampleDoc[];
   /** Documented exit codes. */
   exitCodes?: {code: number; when: string}[];
-  /** Related command names. */
+  /** Related command names; the CLI links each to its doc. */
   related?: string[];
   /** Freeform prose/notes. */
   notes?: ReferenceContentBlock[];

package/authoring/doctypes/component/component.doc.mjs

@@ -124,8 +124,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. (Optional on SubComponentDoc, where the sub-component description is used instead.)',
-      required: true,
+        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. Required on a component doc; optional on a sub-component doc (`subComponentOf`), which uses its description instead.',
       fields: [
         {
           name: 'usage.description',
@@ -242,6 +241,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "When it loads, a stamped component doc is checked as loosely as an unstamped one, so adding `type: 'component'` to an existing doc never breaks it: `displayName` may be missing, `category` may be any string, and `usage`, `theming`, `playground` and `examples` are not checked. Each entry in a group doc's `components` must have a `name`. Write to the type anyway; it is the contract.",
+    },
     {
       type: 'prose',
       text: 'ComponentDoc is a discriminated union of three shapes that all extend ComponentBaseDoc. Pick the variant by which key you set: `props` (single), `components` (multi), or `subComponentOf` (sub).',

package/authoring/doctypes/component/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').ComponentDoc} ComponentDoc */
+/** @typedef {import('../types.js').ComponentDoc} ComponentDoc */
 /**
  * Validate an unknown value as a stamped component doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ComponentDoc}
  */
 export function parseComponent(input: unknown, label?: string): ComponentDoc;
-export type ComponentDoc = import("../types").ComponentDoc;
+export type ComponentDoc = import("../types.js").ComponentDoc;

package/authoring/doctypes/component/parse.mjs

@@ -8,7 +8,7 @@
 import {ComponentDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ComponentDoc} ComponentDoc */
+/** @typedef {import('../types.js').ComponentDoc} ComponentDoc */
 
 /**
  * Validate an unknown value as a stamped component doc, or throw.

package/authoring/doctypes/component/type.ts

@@ -19,7 +19,7 @@ import type {
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Shared fields between single-component and multi-component docs.
@@ -146,10 +146,10 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
 /**
  * The documentation type for a component directory's {Name}.doc.mjs file.
  *
- * Every .doc.mjs must export a single `docs` constant of this type:
+ * Every new .doc.mjs default-exports a stamped object of this type:
  *
  *   /\*\* \@type \{import('@astryxdesign/cli/authoring').ComponentDoc\} *\/
- *   export const docs = \{ ... \};
+ *   export default \{ type: 'component', ... \};
  *
  * Use SingleComponentDoc (with `props`) for single-component directories.
  * Use MultiComponentDoc (with `components`) for multi-component directories.

package/authoring/doctypes/doctypes-new.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Tests for the new authoring doc-types (schema/command/enum) and the
+ * @file Tests for the new authoring doc-types (schema/command/enum/theme) and the
  * generalized `function` doc (hooks + CLI/API functions sharing the schema).
  */
 
@@ -12,6 +12,7 @@ import {
   parseCommand,
   parseEnum,
   parseFunction,
+  parseTheme,
 } from '../index.mjs';
 
 describe('SchemaDoc', () => {
@@ -22,13 +23,21 @@ describe('SchemaDoc', () => {
     description: 'Project config.',
     appliesTo: 'astryx.config.{ts,mjs,js}',
     fields: [
-      {name: 'integrations', type: 'string[]', description: 'Packages to load.'},
+      {
+        name: 'integrations',
+        type: 'string[]',
+        description: 'Packages to load.',
+      },
       {
         name: 'hooks',
         type: 'object',
         description: 'Lifecycle hooks.',
         fields: [
-          {name: 'hooks.postCodemod', type: 'PostCodemodHook[]', description: 'Runs after codemods.'},
+          {
+            name: 'hooks.postCodemod',
+            type: 'PostCodemodHook[]',
+            description: 'Runs after codemods.',
+          },
         ],
       },
     ],
@@ -63,8 +72,16 @@ describe('CommandDoc', () => {
     fn: 'search',
     args: [{name: 'query', param: 'query', required: true}],
     options: [
-      {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook']},
-      {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
+      {
+        flag: '--type <domain>',
+        param: 'options.type',
+        choices: ['component', 'hook'],
+      },
+      {
+        flag: '--json',
+        cliOnly: true,
+        description: 'Emit the typed JSON envelope.',
+      },
     ],
     examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
     exitCodes: [{code: 1, when: 'invalid --type'}],
@@ -90,6 +107,29 @@ describe('EnumDoc', () => {
   });
 });
 
+describe('ThemeDoc', () => {
+  const doc = {
+    type: 'theme',
+    name: 'ocean',
+    displayName: 'Ocean',
+    description: 'Cool blue surfaces with crisp contrast.',
+    maintained: true,
+  };
+
+  it('accepts a complete theme descriptor and dispatches through parseDoc', () => {
+    expect(parseTheme(doc)).toEqual(doc);
+    expect(parseDoc(doc)).toEqual(doc);
+  });
+
+  it('rejects non-kebab identity and missing required metadata', () => {
+    expect(() => parseTheme({...doc, name: 'OceanTheme'})).toThrow(
+      /lowercase kebab-case/,
+    );
+    const {maintained: _maintained, ...missingMaintained} = doc;
+    expect(() => parseTheme(missingMaintained)).toThrow(/maintained/);
+  });
+});
+
 describe('generalized FunctionDoc', () => {
   it('accepts an API function whose returns are envelope entries (no field name)', () => {
     const apiFn = {
@@ -98,7 +138,9 @@ describe('generalized FunctionDoc', () => {
       name: 'search',
       displayName: 'search()',
       importPath: '@astryxdesign/cli/api',
-      params: [{name: 'query', type: 'string', description: 'Term.', required: true}],
+      params: [
+        {name: 'query', type: 'string', description: 'Term.', required: true},
+      ],
       returns: [{type: 'search', description: 'query + ranked results[]'}],
       throws: [{code: 'ERR_INVALID_ARGUMENT', when: 'empty query'}],
     };

package/authoring/doctypes/enum/enum.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path. Defaults to 'cli' when applied by the docs index.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's enums use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/enums/<name>`. Every enum doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',