@astryxdesign/cli 0.6.3-canary.ebaebc4 → 0.6.3-canary.ee13359

package/api/component/list/list.mjs

@@ -15,15 +15,16 @@ import {
   CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
   findComponentReadme,
+  findExternalComponentDoc,
   resolveImportPath,
   resolveIntegrationImportPath,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
-import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
+import {loadComponentDoc, loadIntegrationsSafely, withOwnership} from '../_adapter.mjs';
 
 /**
  * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
@@ -31,6 +32,29 @@ import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
  * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
  */
 
+/**
+ * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
+ * same way (`withOwnership`) so list and detail agree.
+ * @param {{name: string, docsDir: string}} ext
+ * @param {string} name
+ * @param {string} coreDir
+ * @param {{zh: boolean, lang: string|null}} docOpts
+ * @returns {Promise<string>}
+ */
+async function legacyImport(ext, name, coreDir, docOpts) {
+  const docPath = findExternalComponentDoc(ext.docsDir, name);
+  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
+  let docs = {};
+  if (docPath && docPath.endsWith('.doc.mjs')) {
+    try {
+      docs = await loadComponentDoc(docPath, docOpts);
+    } catch {
+      // Keep list resilient; validation owns malformed docs.
+    }
+  }
+  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
+}
+
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in
@@ -204,7 +228,8 @@ export async function componentList(
   const seenIntegration = new Set();
   for (const integration of loadedIntegrations) {
     seenIntegration.add(integration.name);
-    const owned = discoverIntegrationComponents(integration);
+    const {components: owned} =
+      await discoverValidIntegrationComponents(integration);
     // Group integration components by their doc `group`, falling back to the
     // package name. Keys are package-qualified so they never collide with
     // core groups or each other.
@@ -267,20 +292,24 @@ export async function componentList(
       k => grouped[k].length > 1 || grouped[k][0] !== k,
     );
 
-    if (hasGroups) {
-      for (const [group, members] of Object.entries(grouped)) {
-        listData[`${group} (${ext.name})`] = members.map(n => ({
+    /** @param {string[]} names */
+    const entriesFor = names =>
+      Promise.all(
+        names.map(async n => ({
           name: n,
           package: ext.name,
-        }));
+          import: await legacyImport(ext, n, coreDir, {zh, lang}),
+        })),
+      );
+
+    if (hasGroups) {
+      for (const [group, members] of Object.entries(grouped)) {
+        listData[`${group} (${ext.name})`] = await entriesFor(members);
       }
     } else {
       const allComps = Object.values(grouped).flat().sort();
       if (allComps.length > 0) {
-        listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-          name: n,
-          package: ext.name,
-        }));
+        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
       }
     }
   }

package/api/discover/discover.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'discover',
+  namespace: 'cli/api',
   displayName: 'discover()',
   summary: 'Browse and search components from configured external packages.',
   description:
@@ -41,7 +42,7 @@ export const doc = {
       name: 'options.components',
       type: 'boolean',
       description:
-        'List components only. A CLI display flag consumed by the renderer; the programmatic response shape is unchanged.',
+        'In the CLI package list, print every component of each package instead of the first 10. A display flag for the CLI renderer; the programmatic response is unchanged.',
     },
     {
       name: 'options.lang',

package/api/docs/_adapter.d.mts

@@ -16,22 +16,75 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * The overlay languages a topic ships for its own file or any extension.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
+ * The CLI's own topics alone, for a check that runs without a project.
+ * @returns {DocsCatalog}
  */
-export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
+export function builtinCatalog(): DocsCatalog;
 /**
- * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
- * Memoized per catalog, so a read that references a topic twice loads it once.
- * Every read of the catalog shares the memoized node, so it is frozen; the
- * lenses hand readers copies.
+ * 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` or `workflow` block carries the doc it
+ * names. Memoized per catalog and frozen, like the lowered node.
  * @param {DocsCatalog} catalog
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {DocsTopicEntry} entry
  * @param {string | null} [lang]
  * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function lowerTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): 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): a doc in the
+ * project's docs tree by its identity, or a flat topic by its provider and
+ * name. A target that matches neither is a problem, never a guess.
+ * @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}} [options] `owner`: only the docs this package owns
+ * @returns {Promise<string[]>}
+ */
+export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner }?: {
+    owner?: string;
+}): 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).
+ * @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 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<string[]>;
 /**
  * How a token reference finds its target: the topic it names in `catalog`,
  * lowered for the same language.
@@ -49,33 +102,156 @@ export function referenceTargets(catalog: DocsCatalog, lang: string | null): (to
  */
 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 lower it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the 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,
- *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
- *   lang: string | null,
- * }>}
- */
-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;
     node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
     lang: string | null;
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
-/** The localized overlays a docs read can apply. */
-export const OVERLAY_LANGUAGES: string[];
+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 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 };