@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/doc-compiler/compile.d.mts

@@ -0,0 +1,343 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Lower one topic: overlay each file, merge the extensions in order, and stamp
+ * every section with its key.
+ * @param {ReferenceTopicInput} input
+ * @returns {CompiledReferenceNode}
+ */
+export function lowerReferenceTopic(input: ReferenceTopicInput): CompiledReferenceNode;
+/**
+ * Link every section of a lowered node.
+ * @param {CompiledReferenceNode} node
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ *   the lowered node a reference names, or null when no topic has that name
+ * @returns {Promise<CompiledReferenceNode>}
+ */
+export function linkReferenceTopic(node: CompiledReferenceNode, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<CompiledReferenceNode>;
+/**
+ * Resolve the token references in one section. A section with none comes back
+ * as it went in.
+ * @template {{content: any[]}} S
+ * @param {S} section
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ * @returns {Promise<S>}
+ */
+export function linkReferenceSection<S extends {
+    content: any[];
+}>(section: S, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<S>;
+/**
+ * @typedef {import('./diagnostics.mjs').CompilerDiagnostic} CompilerDiagnostic
+ */
+/**
+ * One authored doc of any kind but a reference topic, as its root loaded it.
+ * @typedef {object} DocFileInput
+ * @property {string} id the input's id: provider, root, and name
+ * @property {keyof typeof ROOT_KINDS} root
+ * @property {string} provider the package that contributes it
+ * @property {string} source `<package>/<path>` of the file
+ * @property {string | null} lang the overlay language, or null
+ * @property {AuthoredFile} file `doc` is the authored export, not a parse
+ *   result; `overlay` is the translation the module exports for `lang`
+ * @property {string} [label] how a parse error names the file (default: its
+ *   file name)
+ * @property {boolean} [useParsed] carry the parser's result instead of the
+ *   authored export, for a reader that has always read the checked value
+ */
+/**
+ * The parser that checks a root's docs. Templates and themes have their own;
+ * every other root dispatches on the stamped type.
+ * @param {string} root
+ * @returns {(input: unknown, label?: string) => any}
+ */
+export function parserFor(root: string): (input: unknown, label?: string) => any;
+/**
+ * A compiled node for any kind but a reference topic.
+ * @typedef {object} CompiledDocNode
+ * @property {number} schemaVersion
+ * @property {Exclude<typeof COMPILED_DOC_KINDS[number], 'reference'>} kind
+ * @property {'lowered'} stage
+ * @property {string} id
+ * @property {string | null} lang
+ * @property {{provider: string, source: string}} provenance
+ * @property {any} doc the authored doc, overlaid for `lang`, as JSON carries
+ *   it: key order kept, `undefined` and functions dropped
+ */
+/**
+ * The result of lowering one doc.
+ *
+ * `view` is the doc as readers have always read it: the authored export (or,
+ * where a reader has always read it, the parser's result), with its
+ * translation laid over it, not copied and not converted. Readers print from
+ * the view, so nothing they print depends on JSON. `node` is the sealed,
+ * JSON-only form a whole-project compile collects.
+ *
+ * @typedef {object} LoweredDoc
+ * @property {any} [view] absent when the file could not be read
+ * @property {CompiledDocNode | null} node null when not asked for, or when a
+ *   problem is fatal to the node
+ * @property {CompilerDiagnostic[]} diagnostics
+ * @property {boolean} [loadFailed] importing the file threw
+ * @property {unknown} [loadFailure] what importing the file threw (any value,
+ *   `undefined` included)
+ * @property {boolean} [missing] the file exports no doc
+ * @property {null | undefined} [missingValue] the empty export, as the reader
+ *   picked it
+ * @property {boolean} [failed] the kind's parser threw
+ * @property {unknown} [failure] what the kind's parser threw
+ * @property {boolean} [overlayFailed] laying the translation over threw
+ * @property {unknown} [overlayFailure] what laying the translation over threw
+ */
+/**
+ * Lower one doc of any kind but a reference topic.
+ *
+ * With `check`, the doc is held to its kind's parser, and a failure is
+ * recorded, not fatal: readers that never checked docs keep reading it, and a
+ * checked reader turns it into the error it has always thrown. A doc stamped
+ * with a kind its root does not read keeps its root's kind and carries a
+ * `wrong_kind` diagnostic. With `node`, the view is also carried as JSON; a
+ * value JSON cannot hold withdraws the node, never the view.
+ *
+ * @param {DocFileInput} input
+ * @param {{check?: boolean, node?: boolean}} [options]
+ * @returns {LoweredDoc}
+ */
+export function lowerDoc(input: DocFileInput, { check, node: wantNode }?: {
+    check?: boolean;
+    node?: boolean;
+}): LoweredDoc;
+/** Bumped whenever the shape of a compiled node changes. */
+export const COMPILED_DOC_SCHEMA_VERSION: 1;
+/** Every kind a compiled node has: one per authored doc kind a root reads. */
+export const COMPILED_DOC_KINDS: readonly ["component", "function", "reference", "page", "block", "schema", "command", "enum", "theme", "namespace"];
+/**
+ * The roots that read docs, and the kinds each may hold. A doc without a
+ * stamped `type` (the legacy form) takes its root's first kind.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const ROOT_KINDS: Readonly<Record<string, readonly string[]>>;
+export type CompilerDiagnostic = import("./diagnostics.mjs").CompilerDiagnostic;
+/**
+ * One authored doc of any kind but a reference topic, as its root loaded it.
+ */
+export type DocFileInput = {
+    /**
+     * the input's id: provider, root, and name
+     */
+    id: string;
+    root: keyof typeof ROOT_KINDS;
+    /**
+     * the package that contributes it
+     */
+    provider: string;
+    /**
+     * `<package>/<path>` of the file
+     */
+    source: string;
+    /**
+     * the overlay language, or null
+     */
+    lang: string | null;
+    /**
+     * `doc` is the authored export, not a parse
+     * result; `overlay` is the translation the module exports for `lang`
+     */
+    file: AuthoredFile;
+    /**
+     * how a parse error names the file (default: its
+     * file name)
+     */
+    label?: string | undefined;
+    /**
+     * carry the parser's result instead of the
+     * authored export, for a reader that has always read the checked value
+     */
+    useParsed?: boolean | undefined;
+};
+/**
+ * A compiled node for any kind but a reference topic.
+ */
+export type CompiledDocNode = {
+    schemaVersion: number;
+    kind: Exclude<(typeof COMPILED_DOC_KINDS)[number], "reference">;
+    stage: "lowered";
+    id: string;
+    lang: string | null;
+    provenance: {
+        provider: string;
+        source: string;
+    };
+    /**
+     * the authored doc, overlaid for `lang`, as JSON carries
+     * it: key order kept, `undefined` and functions dropped
+     */
+    doc: any;
+};
+/**
+ * The result of lowering one doc.
+ *
+ * `view` is the doc as readers have always read it: the authored export (or,
+ * where a reader has always read it, the parser's result), with its
+ * translation laid over it, not copied and not converted. Readers print from
+ * the view, so nothing they print depends on JSON. `node` is the sealed,
+ * JSON-only form a whole-project compile collects.
+ */
+export type LoweredDoc = {
+    /**
+     * absent when the file could not be read
+     */
+    view?: any;
+    /**
+     * null when not asked for, or when a
+     * problem is fatal to the node
+     */
+    node: CompiledDocNode | null;
+    diagnostics: CompilerDiagnostic[];
+    /**
+     * importing the file threw
+     */
+    loadFailed?: boolean | undefined;
+    /**
+     * what importing the file threw (any value,
+     * `undefined` included)
+     */
+    loadFailure?: unknown;
+    /**
+     * the file exports no doc
+     */
+    missing?: boolean | undefined;
+    /**
+     * the empty export, as the reader
+     * picked it
+     */
+    missingValue?: null | undefined;
+    /**
+     * the kind's parser threw
+     */
+    failed?: boolean | undefined;
+    /**
+     * what the kind's parser threw
+     */
+    failure?: unknown;
+    /**
+     * laying the translation over threw
+     */
+    overlayFailed?: boolean | undefined;
+    /**
+     * what laying the translation over threw
+     */
+    overlayFailure?: unknown;
+};
+/**
+ * One authored file, as discovery loaded it.
+ */
+export type AuthoredFile = {
+    /**
+     * the file's name, for messages only
+     */
+    file: string;
+    /**
+     * the parsed doc, when it loaded
+     */
+    doc?: any;
+    /**
+     * why it did not load or parse
+     */
+    error?: unknown;
+    /**
+     * the language overlay's export, when one applies
+     */
+    overlay?: any;
+    /**
+     * why the overlay did not load
+     */
+    overlayError?: unknown;
+};
+export type ReferenceTopicInput = {
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    /**
+     * the package that owns the topic
+     */
+    provider: string;
+    /**
+     * the topic it took the place of
+     */
+    replaces: string | null;
+    /**
+     * the overlay language, or null for authored text
+     */
+    lang: string | null;
+    /**
+     * the owner's provider id; the package name
+     * when absent. The base file's sections resolve their links against it.
+     */
+    providerId?: string | undefined;
+    base: AuthoredFile;
+    /**
+     *   in merge order; each extension's sections resolve their links against its
+     *   own provider id
+     */
+    extensions: Array<AuthoredFile & {
+        provider: string;
+        providerId?: string;
+    }>;
+    /**
+     * a guide the docs tree places: its `placement` is
+     * read by the tree, so the topic reader accepts it
+     */
+    tree?: boolean | undefined;
+};
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ */
+export type TokenRefResolution = {
+    status: "resolved";
+    topic: string;
+    section: string;
+    previewType?: string;
+    content: any[];
+} | {
+    status: "unknown-topic";
+} | {
+    status: "unknown-section";
+};
+export type CompiledReferenceNode = {
+    schemaVersion: number;
+    kind: "reference";
+    /**
+     * `linked` once every token reference
+     * carries its resolution; a lowered node carries none
+     */
+    stage: "lowered" | "linked";
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    lang: string | null;
+    provenance: {
+        provider: string;
+        replaces: string | null;
+        extensions: string[];
+    };
+    /**
+     * section key -> authored title
+     */
+    sourceTitles: Record<string, string>;
+    /**
+     * section key -> the
+     * provider id that wrote the section: a topic merges sections from its base
+     * and its extensions, and each section's links resolve against its own
+     * provider (spec:AST-047 FR9)
+     */
+    sectionProviders: Record<string, string>;
+    /**
+     * the topic: authored fields in authored order, every
+     * section keyed; a linked node's token references carry `resolved`
+     */
+    doc: any;
+};