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

package/authoring/discover/type.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for discover sources.
+ *
+ * A discover source tells `astryx discover` which integrations exist beyond the
+ * ones a project already has. A project sets one as `discover` in
+ * `astryx.config`; an integration exports one as a `discover` NAMED export from
+ * its manifest. Discover calls every source, checks each answer, keeps a saved
+ * copy of the last good one, and never installs, enables, or runs anything a
+ * catalog names.
+ */
+
+/** Kinds of item a package can add. */
+export type DiscoverKind =
+  'component' | 'template' | 'doc' | 'theme' | 'codemod' | 'agent-doc';
+
+/** One item a package version adds. */
+export interface DiscoverContribution {
+  kind: DiscoverKind;
+  /**
+   * The name the CLI uses for it: a component name, template id, doc topic,
+   * theme slug, or codemod id.
+   */
+  name: string;
+  title?: string;
+  summary?: string;
+  keywords?: string[];
+}
+
+/** One published version of a package. */
+export interface DiscoverVersion {
+  version: string;
+  /** ISO 8601 publish time, or null when the source does not know it. */
+  publishedAt: string | null;
+  prerelease: boolean;
+  /** `ok`, or why the source could not read this version. */
+  status: string;
+}
+
+/** One npm package a source knows about. */
+export interface DiscoverPackage {
+  package: string;
+  /** Shared by every npm name that publishes the same integration. */
+  integration: string;
+  /** The integration's other npm names. Discover never offers one the project has. */
+  aliases: string[];
+  description?: string;
+  /** The latest release, or null when the package has only prereleases. */
+  latest: string | null;
+  /** Every version, newest first. */
+  versions: DiscoverVersion[];
+  /** What the requested version adds, or the latest when none was requested. */
+  contributions: DiscoverContribution[];
+}
+
+/** What a discover source returns. */
+export interface DiscoverCatalog {
+  schemaVersion: 1;
+  source: {
+    /** Shown to people, for example "Acme catalog". */
+    name: string;
+    /** ISO 8601 time the source's data was produced. */
+    generatedAt: string;
+    /** False when the source knows its list is partial. */
+    complete: boolean;
+  };
+  packages: DiscoverPackage[];
+}
+
+/** One call to a discover source. */
+export interface DiscoverSourceContext {
+  /** Aborted when the source exceeds its 30-second budget. */
+  readonly signal: AbortSignal;
+  /** Asks for one package: every version, and `version`'s contributions. */
+  readonly package?: string;
+  /** With `package`: the version whose contributions to return. Defaults to the latest. */
+  readonly version?: string;
+}
+
+/**
+ * A discover source: an async function, like `debug`. Set it as `discover` in
+ * astryx.config, or export it as `discover` from an integration manifest.
+ */
+export type DiscoverSource = (
+  context: DiscoverSourceContext,
+) => Promise<DiscoverCatalog>;

package/authoring/doctypes/_schema.d.mts

@@ -25,7 +25,7 @@ export namespace AuthoredDocGraphFields {
         internal: "internal";
     }>>;
 }
-/** 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.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"prose">;
     text: z.ZodString;
@@ -55,6 +55,120 @@ export const ReferenceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"token-ref">;
     topic: z.ZodString;
     section: z.ZodString;
+}, z.core.$strict>], "type">;
+/** Runtime schema for graph-only blocks used by NamespaceDoc. */
+export const GraphContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"workflow">;
+    title: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        references: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"collection">;
+    title: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        slot: z.ZodString;
+    }, z.core.$strict>;
+    presentation: z.ZodOptional<z.ZodEnum<{
+        list: "list";
+        cards: "cards";
+        compact: "compact";
+    }>>;
+    whenEmpty: z.ZodOptional<z.ZodEnum<{
+        show: "show";
+        omit: "omit";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"reference">;
+    target: z.ZodString;
+    projection: z.ZodOptional<z.ZodObject<{
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    presentation: z.ZodOptional<z.ZodEnum<{
+        compact: "compact";
+        summary: "summary";
+        full: "full";
+    }>>;
+}, z.core.$strict>], "type">;
+/**
+ * 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.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"prose">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    level: z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    lang: z.ZodString;
+    code: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"table">;
+    headers: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    style: z.ZodEnum<{
+        ordered: "ordered";
+        unordered: "unordered";
+        do: "do";
+        dont: "dont";
+    }>;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"token-ref">;
+    topic: z.ZodString;
+    section: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"reference">;
+    target: z.ZodString;
+    projection: z.ZodOptional<z.ZodObject<{
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    presentation: z.ZodOptional<z.ZodEnum<{
+        compact: "compact";
+        summary: "summary";
+        full: "full";
+    }>>;
+}, z.core.$strict>], "type">;
+/** Namespace content accepts both stable reference blocks and graph-only blocks. */
+export const NamespaceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"prose">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    level: z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    lang: z.ZodString;
+    code: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"table">;
+    headers: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    style: z.ZodEnum<{
+        ordered: "ordered";
+        unordered: "unordered";
+        do: "do";
+        dont: "dont";
+    }>;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"token-ref">;
+    topic: z.ZodString;
+    section: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"workflow">;
     title: z.ZodOptional<z.ZodString>;
@@ -91,7 +205,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 +238,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 +287,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
@@ -207,29 +349,6 @@ export const GenericDocKindSchema: z.ZodObject<{
             type: z.ZodLiteral<"token-ref">;
             topic: z.ZodString;
             section: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"workflow">;
-            title: z.ZodOptional<z.ZodString>;
-            steps: z.ZodArray<z.ZodObject<{
-                title: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"collection">;
-            title: z.ZodOptional<z.ZodString>;
-            source: z.ZodObject<{
-                slot: z.ZodString;
-            }, z.core.$strict>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                list: "list";
-                cards: "cards";
-                compact: "compact";
-            }>>;
-            whenEmpty: z.ZodOptional<z.ZodEnum<{
-                show: "show";
-                omit: "omit";
-            }>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"reference">;
             target: z.ZodString;
@@ -289,7 +408,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;
@@ -323,41 +442,6 @@ export const SchemaDocKindSchema: z.ZodObject<{
         type: z.ZodLiteral<"token-ref">;
         topic: z.ZodString;
         section: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"workflow">;
-        title: z.ZodOptional<z.ZodString>;
-        steps: z.ZodArray<z.ZodObject<{
-            title: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"collection">;
-        title: z.ZodOptional<z.ZodString>;
-        source: z.ZodObject<{
-            slot: z.ZodString;
-        }, z.core.$strict>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            list: "list";
-            cards: "cards";
-            compact: "compact";
-        }>>;
-        whenEmpty: z.ZodOptional<z.ZodEnum<{
-            show: "show";
-            omit: "omit";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"reference">;
-        target: z.ZodString;
-        projection: z.ZodOptional<z.ZodObject<{
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            summary: "summary";
-            full: "full";
-        }>>;
     }, z.core.$strict>], "type">>>;
     placement: z.ZodOptional<z.ZodObject<{
         parent: z.ZodString;
@@ -370,6 +454,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">;
@@ -434,41 +526,6 @@ export const CommandDocKindSchema: z.ZodObject<{
         type: z.ZodLiteral<"token-ref">;
         topic: z.ZodString;
         section: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"workflow">;
-        title: z.ZodOptional<z.ZodString>;
-        steps: z.ZodArray<z.ZodObject<{
-            title: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"collection">;
-        title: z.ZodOptional<z.ZodString>;
-        source: z.ZodObject<{
-            slot: z.ZodString;
-        }, z.core.$strict>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            list: "list";
-            cards: "cards";
-            compact: "compact";
-        }>>;
-        whenEmpty: z.ZodOptional<z.ZodEnum<{
-            show: "show";
-            omit: "omit";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"reference">;
-        target: z.ZodString;
-        projection: z.ZodOptional<z.ZodObject<{
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            summary: "summary";
-            full: "full";
-        }>>;
     }, z.core.$strict>], "type">>>;
     placement: z.ZodOptional<z.ZodObject<{
         parent: z.ZodString;
@@ -481,6 +538,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">;
@@ -833,29 +898,6 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"token-ref">;
             topic: z.ZodString;
             section: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"workflow">;
-            title: z.ZodOptional<z.ZodString>;
-            steps: z.ZodArray<z.ZodObject<{
-                title: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"collection">;
-            title: z.ZodOptional<z.ZodString>;
-            source: z.ZodObject<{
-                slot: z.ZodString;
-            }, z.core.$strict>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                list: "list";
-                cards: "cards";
-                compact: "compact";
-            }>>;
-            whenEmpty: z.ZodOptional<z.ZodEnum<{
-                show: "show";
-                omit: "omit";
-            }>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"reference">;
             target: z.ZodString;
@@ -885,13 +927,83 @@ 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 GraphContentBlock = import("./reference/type.js").GraphContentBlock;
+export type ReferenceSection = import("./reference/type.js").ReferenceSection;
+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>>;
+export type _GraphContentBlockDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof GraphContentBlockSchema>, GraphContentBlock>>;
+export type _SectionContentBlockDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof SectionContentBlockSchema>, ReferenceSection["content"][number]>>;
+/**
+ * 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<{