@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/docs/_adapter.d.mts

@@ -16,53 +16,289 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * The CLI's own topics alone, for a check that runs without a project.
+ * @returns {DocsCatalog}
  */
-export function loadReferenceDocs(docPath: string, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function builtinCatalog(): DocsCatalog;
 /**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
+ * One topic, lowered for `lang` with every link between docs resolved
+ * (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that
+ * opens its doc, and a `reference` block carries the doc it names and the
+ * `content` it includes of it. Memoized per catalog and frozen, like the
+ * lowered node.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
+ */
+export function lowerTopic(catalog: DocsCatalog, entry: DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
+/**
+ * Each link in a topic that names no doc.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTopicEntry} entry
+ * @returns {Promise<LinkProblem[]>}
+ */
+export function topicLinkProblems(catalog: DocsCatalog, entry: DocsTopicEntry): Promise<LinkProblem[]>;
+/**
+ * The project's docs tree: the CLI's own docs plus the namespace docs and
+ * placed guides the configured integrations ship (spec:AST-046), built once
+ * per catalog. Without integration docs it is the CLI's tree, built once per
+ * process.
+ * @param {DocsCatalog} catalog
+ * @param {{fresh?: boolean}} [options] `fresh`: reread the CLI's tree files
+ * @returns {Promise<DocsTree>}
+ */
+export function projectTree(catalog: DocsCatalog, { fresh }?: {
+    fresh?: boolean;
+}): Promise<DocsTree>;
+/**
+ * How a doc's links find their targets (spec:AST-047 FR9), as
+ * {@link docFinder} finds them: each resolves to the link a read shows.
+ * @param {DocsCatalog} catalog
+ * @param {string} fromProvider the provider id of the doc the links sit in
+ * @returns {Promise<LinkResolver>}
+ */
+export function linkResolver(catalog: DocsCatalog, fromProvider: string): Promise<LinkResolver>;
+/**
+ * Every link in the project's docs that names no doc: in each topic, each
+ * guide the tree places, and each typed doc.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {{owner?: string, references?: boolean}} [options] `owner`: only the
+ *   docs this package owns. `references`: instead of the links, each reference
+ *   block that cannot include what it names; a reader loses that content,
+ *   where a link that names no doc still prints as written
+ * @returns {Promise<string[]>}
+ */
+export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner, references }?: {
+    owner?: string;
+    references?: boolean;
+}): Promise<string[]>;
+/**
+ * What \`astryx doctor integration docs\` checks in one integration's docs: the
+ * docs tree they build beside the CLI's (namespaces, placements, routes) and
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
+ * @param {{name: string}} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
+ */
+export function packageDocsProblems(integration: {
+    name: string;
+}, discovered: {
+    records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
+    namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
+}): Promise<Array<{
+    severity: "error" | "warning";
+    message: string;
+}>>;
+/**
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog: DocsCatalog, lang: string | null): (topic: string) => Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode | null>;
+/**
+ * Each reference block in one integration's docs that cannot include what it
+ * names (spec:AST-047 FR9): a target that names no doc, a field its schema
+ * does not have, or a projection its doc cannot take. A reader would lose
+ * that content, so `astryx doctor integration docs` fails on each.
+ * @param {{name: string}} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
+ * @returns {Promise<string[]>}
+ */
+export function packageReferenceProblems(integration: {
+    name: string;
+}, discovered: {
+    records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
+    namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
+}): Promise<string[]>;
+/**
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function compileTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
- * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
- *
- * @param {string} topic
- * @param {object} [options]
- * @param {string} [options.lang]
- * @param {boolean} [options.zh]
- * @param {boolean} [options.dense]
- * @param {string} [options.cwd]
- * @returns {Promise<{
- *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
- * }>}
- */
-export function resolveTopicDocs(topic: string, options?: {
-    lang?: string | undefined;
-    zh?: boolean | undefined;
-    dense?: boolean | undefined;
-    cwd?: string | undefined;
+ * A guide the docs tree places, as a topic entry the topic readers open by its
+ * route. It is never a flat topic: `astryx docs <route>` is its only name.
+ * @param {import('../../foundation/doc-compiler/tree.mjs').TreeNode} node
+ * @returns {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
+ */
+export function guideEntry(node: import("../../foundation/doc-compiler/tree.mjs").TreeNode): import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+/**
+ * What a typed doc in the docs tree prints: its content, with every link to
+ * another doc resolved (spec:AST-047 FR9). A namespace has no content. The
+ * CLI's doc modules are discovery, so this lives in the adapter
+ * (architecture:cli-surface INV21).
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {Promise<{content: any[], problems: LinkProblem[]}>}
+ */
+export function nodeContent(catalog: DocsCatalog, tree: DocsTree, node: TreeNode): Promise<{
+    content: any[];
+    problems: LinkProblem[];
+}>;
+/**
+ * The command that opens the level a topic sits in when the tree cannot say:
+ * a guide's parent namespace, or the topic list.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {import('./docs.type.mjs').DocsCommand}
+ */
+export function topicUp(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): import("./docs.type.mjs").DocsCommand;
+/**
+ * The moves from a node's place in the tree (spec:AST-047 FR2, FR4): up to its
+ * parent (the topic list, at the top), and across to the nodes before and
+ * after it in its parent's slot.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {import('./docs.type.mjs').DocsLinks}
+ */
+export function placeLinks(tree: DocsTree, node: TreeNode): import("./docs.type.mjs").DocsLinks;
+/**
+ * The moves a topic read offers: from its place in the tree, where a guide
+ * sits in its namespace and a flat topic in the Unorganized level.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {Promise<import('./docs.type.mjs').DocsLinks>}
+ */
+export function topicLinks(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): Promise<import("./docs.type.mjs").DocsLinks>;
+/**
+ * What a docs argument names: a topic (a flat one, or a guide the docs tree
+ * places), a namespace or typed doc in the tree, or nothing, as nameOwner
+ * decides.
+ * @param {unknown} topic
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<
+ *   | {kind: 'topic', catalog: DocsCatalog, entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
+ *   | {kind: 'node', catalog: DocsCatalog, tree: import('../../foundation/doc-compiler/tree.mjs').DocsTree, node: import('../../foundation/doc-compiler/tree.mjs').TreeNode}
+ *   | {kind: 'unknown', catalog: DocsCatalog}
+ * >}
+ */
+export function resolveDocsArgument(topic: unknown, { cwd }?: {
+    cwd?: string;
+}): Promise<{
+    kind: "topic";
+    catalog: DocsCatalog;
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+} | {
+    kind: "node";
+    catalog: DocsCatalog;
+    tree: import("../../foundation/doc-compiler/tree.mjs").DocsTree;
+    node: import("../../foundation/doc-compiler/tree.mjs").TreeNode;
+} | {
+    kind: "unknown";
+    catalog: DocsCatalog;
+}>;
+/**
+ * Who answers to a name a reader types (spec:AST-046 FR5, FR11). The tree
+ * decides first: the node at that route, compared without case, holds it. A
+ * name with no node of its own is a topic's other name (its `replaces`
+ * alias), and that topic answers, unless the tree gave the topic's own route
+ * to another doc. Reads, the topic list, and search all ask this, so they
+ * agree on every name.
+ * @param {DocsTree} tree
+ * @param {DocsCatalog} catalog
+ * @param {string} name
+ * @returns {{kind: 'topic', entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} | {kind: 'node', node: TreeNode} | null}
+ */
+export function nameOwner(tree: DocsTree, catalog: DocsCatalog, name: string): {
+    kind: "topic";
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+} | {
+    kind: "node";
+    node: TreeNode;
+} | null;
+/**
+ * Whether a topic answers to its own name: what the topic list and search
+ * offer must open that topic.
+ * @param {DocsTree} tree
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {boolean}
+ */
+export function holdsOwnName(tree: DocsTree, catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): boolean;
+/**
+ * The doc that took a flat topic's route in the docs tree, when it is not
+ * that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
+ * and `unorganized`, and a namespace keeps its route over a topic of the same
+ * name. Null when the topic owns its route, or the tree has no node there.
+ * @param {DocsTree} tree
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {TreeNode | null}
+ */
+export function routeOwner(tree: DocsTree, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): TreeNode | null;
+/**
+ * The error for a docs argument that names nothing. For a route, it suggests
+ * the children of the deepest namespace the route reaches; otherwise, every
+ * topic and every top-level namespace.
+ * @param {unknown} topic
+ * @param {DocsCatalog} catalog
+ * @returns {Promise<AstryxError>}
+ */
+export function unknownTopicError(topic: unknown, catalog: DocsCatalog): Promise<AstryxError>;
+/**
+ * A sentence naming the packages whose docs did not load, or nothing: a doc
+ * that fails to load withdraws its package's docs, so a reader who cannot
+ * find one learns where to look.
+ * @param {DocsCatalog} catalog
+ * @returns {string}
+ */
+export function notLoaded(catalog: DocsCatalog): string;
+/**
+ * Resolve a topic (a flat one, or a guide the docs tree places by its route)
+ * and lower it for the topic readers.
+ * @param {unknown} topic
+ * @param {{lang?: string | null, zh?: boolean, dense?: boolean, cwd?: string}} [options]
+ */
+export function resolveTopicDocs(topic: unknown, options?: {
+    lang?: string | null;
+    zh?: boolean;
+    dense?: boolean;
+    cwd?: string;
 }): Promise<{
     catalog: DocsCatalog;
-    docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
+    node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
+    lang: string | null;
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
+/**
+ * A doc a link found: what a read shows of the link, and the typed doc behind
+ * it when a reference block can include it.
+ */
+export type FoundDoc = {
+    link: import("../../foundation/doc-compiler/links.mjs").DocLink;
+    /**
+     * the doc's kind
+     */
+    kind: string;
+    /**
+     * a
+     * schema, command, function, or enum doc: a leaf of the docs tree (`tree`),
+     * or a section of `astryx docs authoring`; null for any other kind
+     */
+    typed: {
+        doc: any;
+        providerId: string;
+        tree: boolean;
+    } | null;
+};
+export type DocsTree = import("../../foundation/doc-compiler/tree.mjs").DocsTree;
+export type TreeNode = import("../../foundation/doc-compiler/tree.mjs").TreeNode;
+export type LinkProblem = import("../../foundation/doc-compiler/links.mjs").LinkProblem;
+export type LinkResolver = import("../../foundation/doc-compiler/links.mjs").LinkResolver;
+export type DocIncluder = import("../../foundation/doc-compiler/links.mjs").DocIncluder;
+export type DocsTopicEntry = import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
+import { AstryxError } from '../error.mjs';
+import { OVERLAY_LANGUAGES } from '../../foundation/doc-compiler/read.mjs';
+import { overlayLanguages } from '../../foundation/doc-compiler/read.mjs';
+export { OVERLAY_LANGUAGES, overlayLanguages };