@astryxdesign/cli 0.3.0-canary.c857354 → 0.3.0-canary.d52d2cb

package/authoring/codemod/parse.d.mts

@@ -1,4 +1,50 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {AstryxCodemod, AstryxConfigCodemod} from './type';
+/**
+ * Compile-time drift-lock: sealed envelope must infer exactly the public
+ * stamped-codemod union.
+ *
+ * @typedef {import('../_shared/contract').Expect<
+ *   import('../_shared/contract').Equal<
+ *     z.infer<typeof codemodEnvelopeSchema>,
+ *     AstryxCodemod | AstryxConfigCodemod
+ *   >
+ * >} _CodemodDriftLock
+ */
+/**
+ * Validate an unknown value as a stamped codemod default export, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {AstryxCodemod | AstryxConfigCodemod}
+ */
 export function parseCodemod(input: unknown, label?: string): AstryxCodemod | AstryxConfigCodemod;
+/**
+ * Compile-time drift-lock: sealed envelope must infer exactly the public
+ * stamped-codemod union.
+ */
+export type _CodemodDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof codemodEnvelopeSchema>, AstryxCodemod | AstryxConfigCodemod>>;
+export type AstryxCodemod = import("./type").AstryxCodemod;
+export type AstryxConfigCodemod = import("./type").AstryxConfigCodemod;
+export type AstryxCodemodTransform = import("./type").AstryxCodemodTransform;
+import { z } from 'zod';
+/**
+ * The load-boundary contract: a stamped codemod default export, discriminated
+ * by `type` (`'code'` may carry `fileExtensions`; `'config'` may not).
+ */
+declare const codemodEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    fileExtensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    type: z.ZodLiteral<"code">;
+}, z.core.$strict>, z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    type: z.ZodLiteral<"config">;
+}, z.core.$strict>], "type">;
+export {};

package/authoring/config/config.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `astryx.config.*` file (AstryxConfig). Colocated with
+ * the schema (`type.ts` + `parse.mjs`) it documents.
+ * @position packages/cli/authoring/config — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/config/parse.d.mts

@@ -1,4 +1,56 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {AstryxConfig} from './type';
+/**
+ * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
+ * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
+ * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
+ *
+ * @typedef {import('../_shared/contract').Expect<
+ *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
+ * >} _ConfigDriftLock
+ */
+/**
+ * Validate an unknown value as an Astryx config, or throw a readable error.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {AstryxConfig}
+ */
 export function parseConfig(input: unknown, label?: string): AstryxConfig;
+/**
+ * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
+ * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
+ * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
+ */
+export type _ConfigDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>>;
+export type AstryxConfig = import("./type").AstryxConfig;
+export type PostCodemodHook = import("./type").PostCodemodHook;
+export type XleComponent = import("./type").XleComponent;
+import { z } from 'zod';
+declare const configSchema: z.ZodObject<{
+    integrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    issuesUrl: z.ZodOptional<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        postCodemod: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            buildCommand: z.ZodType<(ctx: {
+                packageDir: string;
+                files: string[];
+            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any, z.core.$ZodTypeInternals<(ctx: {
+                packageDir: string;
+                files: string[];
+            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    experimental: z.ZodOptional<z.ZodObject<{
+        xle: z.ZodOptional<z.ZodObject<{
+            components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                from: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                default: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/_schema.d.mts

@@ -0,0 +1,248 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** New-format stamped component doc (`type: 'component'`). */
+export const ComponentDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"component">;
+    props: 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>>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** New-format stamped function doc (`type: 'function'`) — hooks and CLI/API
+ *  functions alike (the discriminant and schema are shared). */
+export const FunctionDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    params: 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>>;
+    returns: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$loose>>;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** New-format stamped generic reference/topic doc (`type: 'generic'`). */
+export const GenericDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"generic">;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** New stamped schema doc (`type: 'schema'`) — documents an authored object. */
+export const SchemaDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"schema">;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    namespace: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<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>>>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        code: z.ZodString;
+    }, z.core.$loose>>>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$loose>;
+/** New stamped command doc (`type: 'command'`) — a function's terminal binding;
+ *  references a FunctionDoc via `fn`. */
+export const CommandDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    summary: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fn: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        param: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        variadic: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        param: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+        cliOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    subcommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        cli: z.ZodString;
+        output: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    exitCodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodNumber;
+        when: z.ZodString;
+    }, z.core.$loose>>>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$loose>;
+/** New stamped enum doc (`type: 'enum'`) — a closed vocabulary (error codes,
+ *  response-type discriminants). */
+export const EnumDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    namespace: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    members: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        description: z.ZodString;
+        deprecated: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** The permissive legacy union (sub-component first, then hook, multi, single). */
+export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    showcase: z.ZodOptional<z.ZodUnknown>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    subComponentOf: z.ZodString;
+    description: z.ZodString;
+    props: 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>, z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    showcase: z.ZodOptional<z.ZodUnknown>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    params: 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>>;
+    returns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    showcase: z.ZodOptional<z.ZodUnknown>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    components: z.ZodArray<z.ZodUnknown>;
+}, z.core.$loose>, z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    showcase: z.ZodOptional<z.ZodUnknown>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    props: 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>]>;
+import { z } from 'zod';

package/authoring/doctypes/base/type.ts

@@ -270,6 +270,12 @@ export interface ComponentThemingDerivedVar {
   /** Named expansion strategy instead of specific vars.
    *  `'container'` — expands padding to 7 container layout tokens. */
   expand?: 'container';
+  /** Emit only the internal `vars`, dropping the source property from the
+   *  generated rule. Use when the class-carrying element must not receive the
+   *  standard property itself — the value reaches a child through the var
+   *  (e.g. TextArea's flush wrapper drives the inner textarea's inline
+   *  padding). Without this, the property is emitted alongside the var. */
+  replaces?: boolean;
 }
 
 /**

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

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `CommandDoc` doc-type — how to author the TERMINAL
+ * binding of an operation. A command is a FunctionDoc exposed on the CLI, so it
+ * references the function via `fn` and only carries CLI-surface facts. Colocated
+ * with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/command — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

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

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

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `ComponentDoc` doc-type — how to author a component
+ * directory's `{Name}.doc.mjs`. A discriminated union (Single/Multi/Sub) that
+ * shares ComponentBaseDoc. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/component — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

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

package/authoring/doctypes/enum/enum.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `EnumDoc` doc-type — how to author a doc for a closed
+ * vocabulary (error codes, response-type discriminants). Colocated with the
+ * type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/enum — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

@@ -1,4 +1,13 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {EnumDoc} from '../types';
+/** @typedef {import('../types').EnumDoc} EnumDoc */
+/**
+ * Validate an unknown value as a stamped enum doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {EnumDoc}
+ */
 export function parseEnum(input: unknown, label?: string): EnumDoc;
+export type EnumDoc = import("../types").EnumDoc;

package/authoring/doctypes/function/function.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `FunctionDoc` doc-type — the generalized
+ * `type: 'function'` doc that covers BOTH React hooks and CLI/programmatic API
+ * functions. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/function — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

@@ -1,4 +1,13 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {FunctionDoc} from '../types';
+/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/**
+ * Validate an unknown value as a stamped function doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {FunctionDoc}
+ */
 export function parseFunction(input: unknown, label?: string): FunctionDoc;
+export type FunctionDoc = import("../types").FunctionDoc;

package/authoring/doctypes/function/parse.mjs

@@ -2,9 +2,29 @@
 
 /**
  * @file Function doc parser (stamped `type: 'function'`). Hooks and CLI/API
- * functions share the discriminant and the sealed schema, so this is the same
- * validator as `parseHook`, exported under the general name. Consumers call
- * `parseFunction` or use `parseDoc`.
+ * functions share the discriminant and the sealed schema, so this delegates to
+ * the same validator as `parseHook`. Consumers call `parseFunction` or use
+ * `parseDoc`.
+ *
+ * This is a wrapper rather than `export {parseHook as parseFunction}` on
+ * purpose: a bare re-export publishes `parseHook`'s narrower `HookDoc` return
+ * type under the general name. `label` is forwarded untouched so `parseHook`'s
+ * own default still supplies the message prefix.
  */
 
-export {parseHook as parseFunction} from '../hook/parse.mjs';
+import {parseHook} from '../hook/parse.mjs';
+
+/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+
+/**
+ * Validate an unknown value as a stamped function doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {FunctionDoc}
+ */
+export function parseFunction(input, label) {
+  return /** @type {FunctionDoc} */ (
+    /** @type {unknown} */ (parseHook(input, label))
+  );
+}

package/authoring/doctypes/hook/hook.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `HookDoc` doc-type — how to author a standalone
+ * React hook's `.doc.mjs`. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/hook — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

@@ -1,4 +1,13 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {HookDoc} from '../types';
+/** @typedef {import('../types').HookDoc} HookDoc */
+/**
+ * Validate an unknown value as a stamped function/hook doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {HookDoc}
+ */
 export function parseHook(input: unknown, label?: string): HookDoc;
+export type HookDoc = import("../types").HookDoc;

package/authoring/doctypes/legacy.d.mts

@@ -1,4 +1,15 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {ComponentDoc, HookDoc} from './types';
+/** @typedef {import('./types').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types').HookDoc} HookDoc */
+/**
+ * Validate an unknown value as a legacy (unstamped) doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ComponentDoc | HookDoc}
+ */
 export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc;
+export type ComponentDoc = import("./types").ComponentDoc;
+export type HookDoc = import("./types").HookDoc;

package/authoring/doctypes/parse.d.mts

@@ -1,21 +1,30 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-import type {
-  ComponentDoc,
-  HookDoc,
-  FunctionDoc,
-  ReferenceDoc,
-  TemplateDoc,
-  SchemaDoc,
-  CommandDoc,
-  EnumDoc,
-} from './types';
-
-// Must stay in step with the @returns of parseDoc in ./parse.mjs — one entry per
-// doc kind it dispatches to. This declaration shadows the implementation for
-// published consumers, so a missing member silently makes that kind unnarrowable.
-// check:cli-structure enforces the coverage.
-export function parseDoc(
-  input: unknown,
-  label?: string,
-): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc;
+/** @typedef {import('./types').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types').CommandDoc} CommandDoc */
+/** @typedef {import('./types').EnumDoc} EnumDoc */
+/**
+ * Validate an unknown loaded doc value into its typed shape, or throw.
+ * Dispatches on the stamped `type`; unstamped docs fall back to
+ * shape-sniffing. The reference/topic discriminant is `'generic'`; a hook and a
+ * CLI/API function share `'function'`.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc}
+ */
+export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc;
+export type ComponentDoc = import("./types").ComponentDoc;
+export type HookDoc = import("./types").HookDoc;
+export type FunctionDoc = import("./types").FunctionDoc;
+export type ReferenceDoc = import("./types").ReferenceDoc;
+export type TemplateDoc = import("./types").TemplateDoc;
+export type SchemaDoc = import("./types").SchemaDoc;
+export type CommandDoc = import("./types").CommandDoc;
+export type EnumDoc = import("./types").EnumDoc;