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

package/authoring/doctypes/_schema.d.mts

@@ -91,7 +91,12 @@ export const ReferenceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         full: "full";
     }>>;
 }, z.core.$strict>], "type">;
-/** New-format stamped component doc (`type: 'component'`). */
+/**
+ * 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: z.ZodObject<{
     type: z.ZodLiteral<"component">;
     theming: z.ZodOptional<z.ZodUnknown>;
@@ -119,13 +124,16 @@ export const ComponentDocKindSchema: z.ZodObject<{
         public: "public";
         internal: "internal";
     }>>;
-    props: z.ZodArray<z.ZodObject<{
+    props: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         type: z.ZodString;
         description: z.ZodString;
         default: z.ZodOptional<z.ZodString>;
         required: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** New-format stamped function doc (`type: 'function'`). */
 export const FunctionDocKindSchema: z.ZodObject<{
@@ -165,6 +173,26 @@ export const FunctionDocKindSchema: z.ZodObject<{
         internal: "internal";
     }>>;
 }, z.core.$loose>;
+/**
+ * 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
@@ -289,7 +317,7 @@ export const SchemaDocKindSchema: z.ZodObject<{
     description: z.ZodString;
     namespace: z.ZodOptional<z.ZodString>;
     appliesTo: z.ZodOptional<z.ZodString>;
-    fields: z.ZodArray<z.ZodType<import("./schema/type").SchemaFieldDoc, any, z.core.$ZodTypeInternals<import("./schema/type").SchemaFieldDoc, any>>>;
+    fields: z.ZodArray<z.ZodType<import("./schema/type.js").SchemaFieldDoc, any, z.core.$ZodTypeInternals<import("./schema/type.js").SchemaFieldDoc, any>>>;
     examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         code: z.ZodString;
@@ -370,6 +398,14 @@ export const SchemaDocKindSchema: z.ZodObject<{
         internal: "internal";
     }>>;
 }, z.core.$loose>;
+/**
+ * @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.ZodObject<{
     type: z.ZodLiteral<"command">;
@@ -481,6 +517,14 @@ export const CommandDocKindSchema: z.ZodObject<{
         internal: "internal";
     }>>;
 }, z.core.$loose>;
+/**
+ * @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.ZodObject<{
     type: z.ZodLiteral<"enum">;
@@ -885,13 +929,79 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     extends: z.ZodOptional<z.ZodString>;
     tokenCategory: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>]>;
-export type AuthoredDocGraphFieldsType = import("./base/type").AuthoredDocGraphFields;
-export type AuthoredDocKind = import("./base/type").AuthoredDocKind;
-export type NamespaceDoc = import("./namespace/type").NamespaceDoc;
-export type ReferenceContentBlock = import("./reference/type").ReferenceContentBlock;
-export type _AuthoredDocGraphDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof _AuthoredDocGraphSchema>, AuthoredDocGraphFieldsType>>;
-export type _ReferenceContentBlockDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof ReferenceContentBlockSchema>, ReferenceContentBlock>>;
-export type _NamespaceDocDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof NamespaceDocKindSchema>, NamespaceDoc>>;
+export type AuthoredDocGraphFieldsType = import("./base/type.js").AuthoredDocGraphFields;
+export type AuthoredDocKind = import("./base/type.js").AuthoredDocKind;
+export type NamespaceDoc = import("./namespace/type.js").NamespaceDoc;
+export type ReferenceContentBlock = import("./reference/type.js").ReferenceContentBlock;
+export type ReferenceDoc = import("./reference/type.js").ReferenceDoc;
+export type SingleComponentDoc = import("./component/type.js").SingleComponentDoc;
+export type ComponentPropDoc = import("./base/type.js").ComponentPropDoc;
+export type HookDoc = import("./hook/type.js").HookDoc;
+export type FunctionDoc = import("./function/type.js").FunctionDoc;
+export type SchemaDoc = import("./schema/type.js").SchemaDoc;
+export type CommandDoc = import("./command/type.js").CommandDoc;
+export type EnumDoc = import("./enum/type.js").EnumDoc;
+export type _AuthoredDocKindDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof AuthoredDocKindSchema>, AuthoredDocKind>>;
+export type _AuthoredDocGraphDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof _AuthoredDocGraphSchema>, AuthoredDocGraphFieldsType>>;
+export type _ReferenceContentBlockDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof ReferenceContentBlockSchema>, ReferenceContentBlock>>;
+/**
+ * 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.
+ */
+export type LoadedComponentDoc = 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;
+    }>;
+};
+export type _ComponentDocDriftLock = 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>>>;
+/**
+ * A stamped function doc as it loads: as with components, `displayName` may be
+ * missing and `usage` passes through unchecked.
+ */
+export type LoadedFunctionDoc = Omit<FunctionDoc, "type" | "displayName" | "usage"> & {
+    type: "function";
+    displayName?: string;
+    usage?: unknown;
+};
+export type _FunctionDocDriftLock = 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>>>;
+/**
+ * Every HookDoc is a FunctionDoc, so the one function schema covers both.
+ */
+export type _HookDocIsFunctionDocLock = import("../_shared/contract.js").Expect<[HookDoc] extends [FunctionDoc] ? true : false>;
+/**
+ * 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`).
+ */
+export type LoadedReferenceDoc = Omit<ReferenceDoc, "type" | "title" | "description" | "sections"> & {
+    type: "generic";
+} & Partial<Pick<ReferenceDoc, "title" | "description" | "sections">>;
+export type _ReferenceDocDriftLock = 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>>>;
+export type _SchemaDocDriftLock = 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";
+}>>>;
+export type _CommandDocDriftLock = 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";
+}>>>;
+export type _EnumDocDriftLock = 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";
+}>>>;
+export type _NamespaceDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof NamespaceDocKindSchema>, NamespaceDoc>>;
 import { z } from 'zod';
 declare const _AuthoredDocGraphSchema: z.ZodObject<{
     placement: z.ZodOptional<z.ZodObject<{

package/authoring/doctypes/_schema.mjs

@@ -11,10 +11,18 @@
 
 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').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 +39,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 +62,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
  *   >
@@ -161,8 +175,8 @@ export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
 ]);
 
 /**
- * @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
  *   >
@@ -245,11 +259,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 +330,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 +391,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 +455,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 +524,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 +554,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,
@@ -514,8 +645,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,14 +12,14 @@ 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 graph. The docs graph is not built yet, so nothing reads them: a reference topic 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.',
+        'Requests one canonical parent in the docs graph. Not read yet: a topic that sets it fails to load.',
       fields: [
         {
           name: 'placement.parent',
@@ -43,13 +43,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 graph 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. Sections and content blocks refuse one in every doc.',
+    },
+  ],
 };

package/authoring/doctypes/base/type.ts

@@ -30,13 +30,17 @@ export interface DocPlacement {
   order?: number;
 }
 
-/** Graph metadata shared by every authored doc kind. */
+/**
+ * Graph metadata shared by every authored doc kind. Reserved for the docs
+ * graph, which is not built yet: nothing reads these fields, and a reference
+ * topic that sets one fails to load.
+ */
 export interface AuthoredDocGraphFields {
-  /** Requested canonical parent. Omit to use source adoption or Unorganized. */
+  /** Requested canonical parent in the docs graph. Not read yet. */
   placement?: DocPlacement;
-  /** Prior routes or names that must continue to resolve to this stable doc. */
+  /** Prior routes or names the docs graph 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

@@ -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 {

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.

package/authoring/doctypes/enum/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').EnumDoc} EnumDoc */
+/** @typedef {import('../types.js').EnumDoc} EnumDoc */
 /**
  * Validate an unknown value as a stamped enum doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {EnumDoc}
  */
 export function parseEnum(input: unknown, label?: string): EnumDoc;
-export type EnumDoc = import("../types").EnumDoc;
+export type EnumDoc = import("../types.js").EnumDoc;

package/authoring/doctypes/enum/parse.mjs

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

package/authoring/doctypes/enum/type.ts

@@ -5,7 +5,7 @@
  * discriminants). Colocated next to the source of truth it documents.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
 
 /** One member of an enumerated vocabulary. */
 export interface EnumMemberDoc {

package/authoring/doctypes/function/function.doc.mjs

@@ -250,6 +250,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",