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

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

@@ -0,0 +1,288 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Build the tree. Pure: the same inputs give the same tree, whatever order
+ * they arrive in.
+ *
+ * A doc's home is decided once, in this order: its explicit `placement`, then
+ * the one adoption rule in its package that matches its group and kind. A
+ * placement that fails withdraws the doc; it never falls back to adoption. A
+ * doc with neither is a flat topic: it keeps its flat name as its route, and its
+ * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * integration's node that would take one is withdrawn with a diagnostic.
+ *
+ * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
+ * @returns {DocsTree}
+ */
+export function buildDocsTree({ namespaces, docs, topics }: {
+    namespaces: TreeNamespaceInput[];
+    docs: TreeDocInput[];
+    topics?: TreeTopicInput[];
+}): DocsTree;
+/**
+ * The files under {@link TREE_DOCS_DIR}, sorted.
+ * @param {string} [dir]
+ * @returns {string[]}
+ */
+export function treeDocFiles(dir?: string): string[];
+/**
+ * The CLI's own tree inputs: the namespace docs and guides under
+ * assets/docs/tree, and, unless left out, every typed self-doc with its
+ * `namespace` group. A file that fails to load or parse is a diagnostic, never
+ * a thrown error.
+ * @param {{selfDocs?: boolean, dir?: string}} [options]
+ * @returns {Promise<{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], diagnostics: CompilerDiagnostic[]}>}
+ */
+export function loadTreeInputs({ selfDocs, dir, }?: {
+    selfDocs?: boolean;
+    dir?: string;
+}): Promise<{
+    namespaces: TreeNamespaceInput[];
+    docs: TreeDocInput[];
+    diagnostics: CompilerDiagnostic[];
+}>;
+/**
+ * The CLI's own docs tree, built once per process. With `selfDocs: false` it
+ * holds only the namespaces and guides, which is all a topic list needs.
+ * @param {{selfDocs?: boolean, fresh?: boolean}} [options]
+ * @returns {Promise<DocsTree>}
+ */
+export function loadDocsTree({ selfDocs, fresh }?: {
+    selfDocs?: boolean;
+    fresh?: boolean;
+}): Promise<DocsTree>;
+export { routeSegment };
+/** Where the CLI keeps the docs that only the tree reads. */
+export const TREE_DOCS_DIR: string;
+/** One route segment: lowercase letters and digits joined by single hyphens. */
+export const ROUTE_SEGMENT_RE: RegExp;
+/**
+ * The generated level that `groupBy: 'kind'` makes for each kind: its route
+ * segment, title, and summary.
+ * @type {Readonly<Record<string, {segment: string, title: string, summary: string}>>}
+ */
+export const KIND_GROUPS: Readonly<Record<string, {
+    segment: string;
+    title: string;
+    summary: string;
+}>>;
+/**
+ * @typedef {import('../../authoring/doctypes/namespace/type').NamespaceDoc} NamespaceDoc
+ * @typedef {import('../../authoring/doctypes/base/type').DocPlacement} DocPlacement
+ * @typedef {import('./diagnostics.mjs').CompilerDiagnostic} CompilerDiagnostic
+ */
+/**
+ * @typedef {object} TreeNamespaceInput
+ * @property {string} provider the package that owns the namespace
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source `<package>/<path>` of its file
+ * @property {NamespaceDoc} doc
+ */
+/**
+ * @typedef {object} TreeDocInput
+ * @property {string} provider the package that authored the doc
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source
+ * @property {import('../../authoring/doctypes/base/type').AuthoredDocKind} kind
+ *   the authored kind: `generic`, `command`, `function`, `schema`, or `enum`
+ * @property {string} name the doc's stable name
+ * @property {string} title
+ * @property {string} summary
+ * @property {string | null} group the discovery group adoption reads, or null
+ * @property {DocPlacement | undefined} placement
+ * @property {any} [ref] what a reader needs to open the doc, carried as given
+ */
+/**
+ * @typedef {object} TreeSlot
+ * @property {string} name
+ * @property {string} title
+ * @property {string[]} children child routes, in reading order
+ */
+/**
+ * A flat topic: a reference topic that no namespace places. The tree gives it
+ * a home in the generated Unorganized level, under its own name.
+ * @typedef {object} TreeTopicInput
+ * @property {string} provider the package that owns the topic
+ * @property {string} providerId the provider's ProviderId
+ * @property {string} name the topic's name, which stays its route
+ * @property {string} title
+ * @property {string} summary
+ * @property {string} source where the topic comes from, for diagnostics
+ * @property {string[]} [aliases] every other name the topic answers to: the
+ *   topics it replaced, directly or through a chain
+ */
+/** The route of the generated level that holds every flat topic. */
+export const UNORGANIZED: "unorganized";
+export type NamespaceDoc = import("../../authoring/doctypes/namespace/type").NamespaceDoc;
+export type DocPlacement = import("../../authoring/doctypes/base/type").DocPlacement;
+export type CompilerDiagnostic = import("./diagnostics.mjs").CompilerDiagnostic;
+export type TreeNamespaceInput = {
+    /**
+     * the package that owns the namespace
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId (its manifest
+     * `providerId`, else its package name); node ids are built from it
+     */
+    providerId: string;
+    /**
+     * which provider wins a contested route: the CLI's
+     * own docs are 0, then each integration in configured order
+     */
+    rank?: number | undefined;
+    /**
+     * `<package>/<path>` of its file
+     */
+    source: string;
+    doc: NamespaceDoc;
+};
+export type TreeDocInput = {
+    /**
+     * the package that authored the doc
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId (its manifest
+     * `providerId`, else its package name); node ids are built from it
+     */
+    providerId: string;
+    /**
+     * which provider wins a contested route: the CLI's
+     * own docs are 0, then each integration in configured order
+     */
+    rank?: number | undefined;
+    source: string;
+    /**
+     *   the authored kind: `generic`, `command`, `function`, `schema`, or `enum`
+     */
+    kind: import("../../authoring/doctypes/base/type").AuthoredDocKind;
+    /**
+     * the doc's stable name
+     */
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * the discovery group adoption reads, or null
+     */
+    group: string | null;
+    placement: DocPlacement | undefined;
+    /**
+     * what a reader needs to open the doc, carried as given
+     */
+    ref?: any;
+};
+export type TreeSlot = {
+    name: string;
+    title: string;
+    /**
+     * child routes, in reading order
+     */
+    children: string[];
+};
+/**
+ * A flat topic: a reference topic that no namespace places. The tree gives it
+ * a home in the generated Unorganized level, under its own name.
+ */
+export type TreeTopicInput = {
+    /**
+     * the package that owns the topic
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId
+     */
+    providerId: string;
+    /**
+     * the topic's name, which stays its route
+     */
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * where the topic comes from, for diagnostics
+     */
+    source: string;
+    /**
+     * every other name the topic answers to: the
+     * topics it replaced, directly or through a chain
+     */
+    aliases?: string[] | undefined;
+};
+export type TreeNode = {
+    /**
+     * the doc's DocId, built from its provider's
+     * ProviderId, kind, and name: stable when the route moves; null on a
+     * generated level, which has no authored doc
+     */
+    id: string | null;
+    route: string;
+    /**
+     * `namespace` or the doc's authored kind
+     */
+    kind: string;
+    /**
+     * the package that owns it
+     */
+    provider: string;
+    /**
+     * its provider's ProviderId
+     */
+    providerId: string;
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * the parent's route; null at the top
+     */
+    parent: string | null;
+    /**
+     * the parent slot this node sits in
+     */
+    slot: string | null;
+    order: number | null;
+    /**
+     * made by the compiler (a `groupBy: 'kind'`
+     * level, or the Unorganized level), not authored
+     */
+    generated: boolean;
+    /**
+     * a namespace's slots; empty for a leaf
+     */
+    slots: TreeSlot[];
+    source: string;
+    ref?: any;
+};
+export type DocsTree = {
+    /**
+     * by route, in route order
+     */
+    nodes: Map<string, TreeNode>;
+    /**
+     * sorted
+     */
+    diagnostics: CompilerDiagnostic[];
+    get: (route: string) => TreeNode | undefined;
+    /**
+     * the node at a
+     * route compared without case, as topic names are
+     */
+    getFolded: (route: string) => TreeNode | undefined;
+    /**
+     * the namespaces with no parent
+     */
+    roots: () => TreeNode[];
+    /**
+     * top first, not the node
+     */
+    ancestors: (node: TreeNode) => TreeNode[];
+};
+import { routeSegment } from '../discovery/docs-section-key.mjs';