@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

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

@@ -1,44 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * One authored file, as discovery loaded it.
- * @typedef {object} AuthoredFile
- * @property {string} file the file's name, for messages only
- * @property {any} [doc] the parsed doc, when it loaded
- * @property {unknown} [error] why it did not load or parse
- * @property {any} [overlay] the language overlay's export, when one applies
- * @property {unknown} [overlayError] why the overlay did not load
- */
-/**
- * @typedef {object} ReferenceTopicInput
- * @property {string} id the topic's name in the catalog
- * @property {string} provider the package that owns the topic
- * @property {string | null} replaces the topic it took the place of
- * @property {string | null} lang the overlay language, or null for authored text
- * @property {AuthoredFile} base
- * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
- */
-/**
- * A token reference after linking: the target section's content, or why it
- * has none.
- * @typedef {{status: 'resolved', topic: string, section: string, previewType?: string, content: any[]}
- *   | {status: 'unknown-topic'}
- *   | {status: 'unknown-section'}} TokenRefResolution
- */
-/**
- * @typedef {object} CompiledReferenceNode
- * @property {number} schemaVersion
- * @property {'reference'} kind
- * @property {'lowered' | 'linked'} stage `linked` once every token reference
- *   carries its resolution; a lowered node carries none
- * @property {string} id the topic's name in the catalog
- * @property {string | null} lang
- * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
- * @property {Record<string, string>} sourceTitles section key -> authored title
- * @property {any} doc the topic: authored fields in authored order, every
- *   section keyed; a linked node's token references carry `resolved`
- */
 /**
  * Lower one topic: overlay each file, merge the extensions in order, and stamp
  * every section with its key.
@@ -65,8 +27,208 @@ export function linkReferenceTopic(node: CompiledReferenceNode, lowerTarget: (to
 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.
  */
@@ -109,13 +271,25 @@ export type ReferenceTopicInput = {
      * 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
+     *   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
@@ -154,6 +328,13 @@ export type CompiledReferenceNode = {
      * 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`