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

package/api/docs/docs.mjs

@@ -3,24 +3,35 @@
 /**
  * @file Programmatic API for the docs command.
  *
- * Dispatcher + barrel. `docs()` routes by argument shape into one of three
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of five
  * leaves, each projecting into a single { type, data } envelope:
  *
- *   docs()                 -> list    -> docs.list
- *   docs(topic)            -> detail  -> docs.detail
- *   docs(topic, section)   -> section -> docs.detail.section
+ *   docs()                                -> list    -> docs.list
+ *   docs(topic)                           -> detail  -> docs.detail
+ *   docs(topic, undefined, {index: true}) -> index   -> docs.index
+ *   docs(topic, section)                  -> section -> docs.detail.section
+ *   docs(route)                           -> node    -> docs.node
  *
- * The leaves live in list/, detail/, and detail/section/; the discovery,
- * overlay loading, and topic resolution they share sit in _adapter.mjs. This
- * module keeps the same `docs` export (and re-exports the leaves) so
- * api/index.mjs and the CLI consumer import from here unchanged.
+ * A topic read returns the whole doc, as it always has; `index` returns its
+ * sections, so a reader can open one by its key (spec:AST-047). The CLI's text
+ * view lists the sections by default. A route names a node
+ * of the docs tree (spec:AST-046): a namespace lists its children, a guide the
+ * tree places reads like any topic, and a typed doc prints its content. The
+ * leaves
+ * live in list/, index/, detail/, detail/section/, and node/; the discovery,
+ * overlay loading, and resolution they share sit in _adapter.mjs.
  */
 
 import {list} from './list/list.mjs';
+import {index} from './index/index.mjs';
 import {detail} from './detail/detail.mjs';
 import {section as sectionLeaf} from './detail/section/section.mjs';
+import {node as nodeLeaf, nodeView} from './node/node.mjs';
+import {resolveDocsArgument} from './_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-export {list, detail, sectionLeaf as section};
+export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
 /**
  * @param {string} [topic]
@@ -29,15 +40,47 @@ export {list, detail, sectionLeaf as section};
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ *   the whole doc
  * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
+ *   import('./docs.type.mjs').DocsIndexResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
- *   import('./docs.type.mjs').DocsDetailSectionResponse
+ *   import('./docs.type.mjs').DocsDetailSectionResponse |
+ *   import('./docs.type.mjs').DocsNodeResponse
  * >}
  */
 export async function docs(topic, section, options = {}) {
   if (!topic) return list(options);
+  const found = await resolveDocsArgument(topic, options);
+  if (found.kind === 'node') {
+    // A namespace or a typed doc has no sections: it is one read. `--index`
+    // asks for what the node read already is.
+    if (section) {
+      throw new AstryxError(
+        `"${found.node.route}" has no sections. ${
+          found.node.kind === 'namespace'
+            ? 'Open one of its children instead.'
+            : `Read it whole: astryx docs ${found.node.route}.`
+        }`,
+        found.node.kind === 'namespace'
+          ? found.node.slots.flatMap(slot =>
+              slot.children.map(route => ({
+                name: route,
+                reason: found.tree.get(route)?.summary ?? '',
+              })),
+            )
+          : [{name: found.node.route, reason: found.node.summary}],
+        ERROR_CODES.ERR_UNKNOWN_SECTION,
+      );
+    }
+    return {
+      type: 'docs.node',
+      data: await nodeView(found.catalog, found.tree, found.node),
+    };
+  }
   if (section) return sectionLeaf(topic, section, options);
+  if (options.index) return index(topic, options);
   return detail(topic, options);
 }

package/api/docs/docs.type.d.mts

@@ -2,11 +2,26 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json docs
+ * astryx --json docs
  */
 export type DocsListResponse = {
     type: "docs.list";
+    /**
+     * every topic, each readable as a topic
+     */
     data: DocsListEntry[];
+    /**
+     * `namespaces`: the docs tree's top-level namespaces, each opened by its
+     * `topic` as a docs.node; `notLoaded`: each package whose doc files did not
+     * load, and why (its docs are withdrawn)
+     */
+    meta?: {
+        namespaces?: DocsListNamespace[];
+        notLoaded?: Array<{
+            package: string;
+            message: string;
+        }>;
+    } | undefined;
 };
 export type DocsListEntry = {
     topic: string;
@@ -23,18 +38,214 @@ export type DocsListEntry = {
     replaces?: string | undefined;
 };
 /**
- * xds --json docs <topic>
+ * A top-level namespace of the docs tree, as `astryx docs --json` lists it in
+ * `meta.namespaces`.
+ */
+export type DocsListNamespace = {
+    /**
+     * its route, the argument that opens it
+     */
+    topic: string;
+    description: string;
+    /**
+     * the package that owns it
+     */
+    package: string;
+};
+/**
+ * astryx --json docs <topic> --index
+ */
+export type DocsIndexResponse = {
+    type: "docs.index";
+    data: DocsIndex;
+};
+/**
+ * astryx --json docs <topic>
  */
 export type DocsDetailResponse = {
     type: "docs.detail";
-    data: import("@astryxdesign/cli/authoring").ReferenceDoc;
+    /**
+     *   the whole doc, and the moves from it
+     */
+    data: DocsReadDoc & {
+        links: DocsLinks;
+    };
+};
+/**
+ * A topic section as a read returns it. A read inlines each token reference
+ * and each `reference` block the author wrote, so its content holds only the
+ * stable ReferenceContentBlock kinds.
+ */
+export type DocsReadSection = Omit<import("@astryxdesign/cli/authoring").ReferenceSection, "content"> & {
+    content: import("@astryxdesign/cli/authoring").ReferenceContentBlock[];
+};
+/**
+ * A topic as a read returns it: every section a {@link DocsReadSection}.
+ */
+export type DocsReadDoc = Omit<import("@astryxdesign/cli/authoring").ReferenceDoc, "sections"> & {
+    sections: DocsReadSection[];
 };
 /**
- * xds --json docs <topic> <section>
+ * The doc a link opens (spec:AST-047 FR9). A docs read resolves every link:
+ * an inline `{@link  <target>}` reads as `link.command`, a `reference` block in
+ * a namespace doc carries `link` (null when the target names no doc), and each
+ * `workflow` step carries `links`, one per reference. A topic read inlines a
+ * section's `reference` block as the doc it includes, then a line naming where
+ * that comes from and the command that opens it.
+ */
+export type DocLink = import("../../foundation/doc-compiler/links.mjs").DocLink;
+/**
+ * One move: a whole `astryx docs` command a reader can run as is.
+ */
+export type DocsCommand = "astryx docs" | `astryx docs ${string}`;
+/**
+ * The moves a docs read offers (spec:AST-047). Every read but the topic list
+ * carries them.
+ */
+export type DocsLinks = {
+    /**
+     * opens the level the read sits in: a section's
+     * topic index, a node's parent namespace, or the topic list
+     */
+    up: DocsCommand;
+    /**
+     * opens the item before it at its level: the
+     * previous section of its topic, or the previous node in its parent's slot
+     */
+    previous?: DocsCommand | undefined;
+    /**
+     * opens the item after it at its level
+     */
+    next?: DocsCommand | undefined;
+    /**
+     * opens each doc a typed doc names: a
+     * function's command, a command's function, and the docs it lists as
+     * related
+     */
+    related?: DocsCommand[] | undefined;
+};
+/**
+ * The section index of one topic: what the topic is, and the key each section
+ * is read by.
+ */
+export type DocsIndex = {
+    /**
+     * the topic
+     */
+    name: string;
+    title: string;
+    description: string;
+    sections: DocsIndexSection[];
+    /**
+     * the moves from the index
+     */
+    links: DocsLinks;
+};
+export type DocsIndexSection = {
+    /**
+     * stable key; pass it as the section argument
+     */
+    id: string;
+    title: string;
+    /**
+     * the section's first line of text, at most 240
+     * characters
+     */
+    summary: string;
+};
+/**
+ * astryx --json docs <topic> <section>
  */
 export type DocsDetailSectionResponse = {
     type: "docs.detail.section";
-    data: import("@astryxdesign/cli/authoring").ReferenceSection;
+    /**
+     *   the section, and the moves from it: up to its topic's index, and across to
+     *   the sections before and after it
+     */
+    data: DocsReadSection & {
+        links: DocsLinks;
+    };
+};
+/**
+ * astryx --json docs <route>, for a namespace or a typed doc in the docs tree
+ */
+export type DocsNodeResponse = {
+    type: "docs.node";
+    data: DocsNode;
+};
+/**
+ * One node of the docs tree.
+ */
+export type DocsNode = {
+    /**
+     * the doc's DocId, built from its provider's
+     * ProviderId, kind, and name (see the provider-identity authoring doc);
+     * unchanged when the node moves. Always present; null on a generated level,
+     * such as `cli/api/functions`, which has no authored doc
+     */
+    id: string | null;
+    /**
+     * pass it to `astryx docs`
+     */
+    route: string;
+    /**
+     * `namespace`, or the typed doc's kind: `command`,
+     * `function`, `schema`, or `enum`
+     */
+    kind: string;
+    /**
+     * the package that owns the node
+     */
+    package: string;
+    title: string;
+    summary: string;
+    /**
+     * the namespaces above it, top first
+     */
+    breadcrumb: DocsNodeLink[];
+    /**
+     * a namespace's slots that hold children, in
+     * order; empty for a typed doc
+     */
+    slots: DocsNodeSlot[];
+    /**
+     *   a typed doc's content; empty for a namespace
+     */
+    content: import("@astryxdesign/cli/authoring").ReferenceContentBlock[];
+    /**
+     * the moves from the node: up to its parent (the
+     * topic list, for a top-level namespace), and across to its neighbors in its
+     * parent's slot
+     */
+    links: DocsLinks;
+};
+export type DocsNodeLink = {
+    route: string;
+    title: string;
+};
+export type DocsNodeSlot = {
+    /**
+     * the slot's key in its namespace
+     */
+    name: string;
+    title: string;
+    /**
+     * in reading order
+     */
+    children: DocsNodeChild[];
+};
+export type DocsNodeChild = {
+    /**
+     * pass it to `astryx docs` to go one level down
+     */
+    route: string;
+    /**
+     * the last segment of its route
+     */
+    name: string;
+    kind: string;
+    title: string;
+    summary: string;
 };
 /**
  * Options for `docs()`.
@@ -43,6 +254,11 @@ export type DocsOptions = {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    /**
+     * return a topic's section index instead of its
+     * whole doc
+     */
+    index?: boolean | undefined;
     /**
      * project directory whose configured integrations
      * contribute topics; defaults to process.cwd()

package/api/docs/docs.type.mjs

@@ -4,19 +4,26 @@
  * @file Colocated types for the `docs` command — source of truth for the docs
  *   command JSON responses. `types/docs.d.ts` re-exports these.
  *
- *   Invocation                          -> type discriminator
+ *   Invocation                           -> type discriminator
  *   ------------------------------------------------------------
- *   xds --json docs                     -> docs.list
- *   xds --json docs <topic>             -> docs.detail
- *   xds --json docs <topic> <section>   -> docs.detail.section
- *   (unknown topic/section)             -> CLIError
+ *   astryx --json docs                   -> docs.list
+ *   astryx --json docs <topic>           -> docs.detail
+ *   astryx --json docs <topic> --index   -> docs.index
+ *   astryx --json docs <topic> <section> -> docs.detail.section
+ *   astryx --json docs <route>           -> docs.node (a namespace or a
+ *                                           typed doc in the docs tree)
+ *   (unknown topic/section)              -> CLIError
  */
 
 /**
- * xds --json docs
+ * astryx --json docs
  * @typedef {object} DocsListResponse
  * @property {'docs.list'} type
- * @property {DocsListEntry[]} data
+ * @property {DocsListEntry[]} data every topic, each readable as a topic
+ * @property {{namespaces?: DocsListNamespace[], notLoaded?: Array<{package: string, message: string}>}} [meta]
+ *   `namespaces`: the docs tree's top-level namespaces, each opened by its
+ *   `topic` as a docs.node; `notLoaded`: each package whose doc files did not
+ *   load, and why (its docs are withdrawn)
  */
 
 /**
@@ -30,17 +37,150 @@
  */
 
 /**
- * xds --json docs <topic>
+ * A top-level namespace of the docs tree, as `astryx docs --json` lists it in
+ * `meta.namespaces`.
+ * @typedef {object} DocsListNamespace
+ * @property {string} topic its route, the argument that opens it
+ * @property {string} description
+ * @property {string} package the package that owns it
+ */
+
+/**
+ * astryx --json docs <topic> --index
+ * @typedef {object} DocsIndexResponse
+ * @property {'docs.index'} type
+ * @property {DocsIndex} data
+ */
+
+/**
+ * astryx --json docs <topic>
  * @typedef {object} DocsDetailResponse
  * @property {'docs.detail'} type
- * @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
+ * @property {DocsReadDoc & {links: DocsLinks}} data
+ *   the whole doc, and the moves from it
+ */
+
+/**
+ * A topic section as a read returns it. A read inlines each token reference
+ * and each `reference` block the author wrote, so its content holds only the
+ * stable ReferenceContentBlock kinds.
+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceSection, 'content'>
+ *   & {content: import('@astryxdesign/cli/authoring').ReferenceContentBlock[]}} DocsReadSection
+ */
+
+/**
+ * A topic as a read returns it: every section a {@link DocsReadSection}.
+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceDoc, 'sections'>
+ *   & {sections: DocsReadSection[]}} DocsReadDoc
+ */
+
+/**
+ * The doc a link opens (spec:AST-047 FR9). A docs read resolves every link:
+ * an inline `{@link <target>}` reads as `link.command`, a `reference` block in
+ * a namespace doc carries `link` (null when the target names no doc), and each
+ * `workflow` step carries `links`, one per reference. A topic read inlines a
+ * section's `reference` block as the doc it includes, then a line naming where
+ * that comes from and the command that opens it.
+ * @typedef {import('../../foundation/doc-compiler/links.mjs').DocLink} DocLink
+ */
+
+/**
+ * One move: a whole `astryx docs` command a reader can run as is.
+ * @typedef {'astryx docs' | `astryx docs ${string}`} DocsCommand
+ */
+
+/**
+ * The moves a docs read offers (spec:AST-047). Every read but the topic list
+ * carries them.
+ * @typedef {object} DocsLinks
+ * @property {DocsCommand} up opens the level the read sits in: a section's
+ *   topic index, a node's parent namespace, or the topic list
+ * @property {DocsCommand} [previous] opens the item before it at its level: the
+ *   previous section of its topic, or the previous node in its parent's slot
+ * @property {DocsCommand} [next] opens the item after it at its level
+ * @property {DocsCommand[]} [related] opens each doc a typed doc names: a
+ *   function's command, a command's function, and the docs it lists as
+ *   related
  */
 
 /**
- * xds --json docs <topic> <section>
+ * The section index of one topic: what the topic is, and the key each section
+ * is read by.
+ * @typedef {object} DocsIndex
+ * @property {string} name the topic
+ * @property {string} title
+ * @property {string} description
+ * @property {DocsIndexSection[]} sections
+ * @property {DocsLinks} links the moves from the index
+ */
+
+/**
+ * @typedef {object} DocsIndexSection
+ * @property {string} id stable key; pass it as the section argument
+ * @property {string} title
+ * @property {string} summary the section's first line of text, at most 240
+ *   characters
+ */
+
+/**
+ * astryx --json docs <topic> <section>
  * @typedef {object} DocsDetailSectionResponse
  * @property {'docs.detail.section'} type
- * @property {import('@astryxdesign/cli/authoring').ReferenceSection} data
+ * @property {DocsReadSection & {links: DocsLinks}} data
+ *   the section, and the moves from it: up to its topic's index, and across to
+ *   the sections before and after it
+ */
+
+/**
+ * astryx --json docs <route>, for a namespace or a typed doc in the docs tree
+ * @typedef {object} DocsNodeResponse
+ * @property {'docs.node'} type
+ * @property {DocsNode} data
+ */
+
+/**
+ * One node of the docs tree.
+ * @typedef {object} DocsNode
+ * @property {string | null} id the doc's DocId, built from its provider's
+ *   ProviderId, kind, and name (see the provider-identity authoring doc);
+ *   unchanged when the node moves. Always present; null on a generated level,
+ *   such as `cli/api/functions`, which has no authored doc
+ * @property {string} route pass it to `astryx docs`
+ * @property {string} kind `namespace`, or the typed doc's kind: `command`,
+ *   `function`, `schema`, or `enum`
+ * @property {string} package the package that owns the node
+ * @property {string} title
+ * @property {string} summary
+ * @property {DocsNodeLink[]} breadcrumb the namespaces above it, top first
+ * @property {DocsNodeSlot[]} slots a namespace's slots that hold children, in
+ *   order; empty for a typed doc
+ * @property {import('@astryxdesign/cli/authoring').ReferenceContentBlock[]} content
+ *   a typed doc's content; empty for a namespace
+ * @property {DocsLinks} links the moves from the node: up to its parent (the
+ *   topic list, for a top-level namespace), and across to its neighbors in its
+ *   parent's slot
+ */
+
+/**
+ * @typedef {object} DocsNodeLink
+ * @property {string} route
+ * @property {string} title
+ */
+
+/**
+ * @typedef {object} DocsNodeSlot
+ * @property {string} name the slot's key in its namespace
+ * @property {string} title
+ * @property {DocsNodeChild[]} children in reading order
+ */
+
+/**
+ * @typedef {object} DocsNodeChild
+ * @property {string} route pass it to `astryx docs` to go one level down
+ * @property {string} name the last segment of its route
+ * @property {string} kind
+ * @property {string} title
+ * @property {string} summary
  */
 
 /**
@@ -49,6 +189,8 @@
  * @property {string} [lang]
  * @property {boolean} [zh]
  * @property {boolean} [dense]
+ * @property {boolean} [index] return a topic's section index instead of its
+ *   whole doc
  * @property {string} [cwd] project directory whose configured integrations
  *   contribute topics; defaults to process.cwd()
  */

package/api/docs/index/index.d.mts

@@ -0,0 +1,18 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
+ */
+export function index(topic: string, options?: {
+    lang?: string | undefined;
+    zh?: boolean | undefined;
+    dense?: boolean | undefined;
+    cwd?: string | undefined;
+}): Promise<import("../docs.type.mjs").DocsIndexResponse>;

package/api/docs/index/index.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.index leaf — the section index of one topic.
+ *
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and reads its lowered compiled node; nothing is
+ *   linked, since the index never inlines a token reference.
+ * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
+ *   description and, for each section, the key it is read by, its title, and a
+ *   one-line summary. Matches `astryx --json docs <topic> --index`.
+ * @position Leaf under api/docs: a topic's opt-in progressive read. One section
+ *   is the section leaf (`docs <topic> <key>`); the whole topic, a plain topic
+ *   read, is the detail leaf.
+ */
+
+import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
+import {resolveTopicDocs, topicLinks} from '../_adapter.mjs';
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
+ */
+export async function index(topic, options = {}) {
+  const {node, entry, catalog} = await resolveTopicDocs(topic, options);
+  const view = indexView(node);
+  /** @type {import('../docs.type.mjs').DocsIndex} */
+  const data = {
+    ...view,
+    // A guide the docs tree places is read by its route, not its doc name.
+    name: entry.tree ? entry.name : view.name,
+    links: await topicLinks(catalog, entry),
+  };
+  return {type: 'docs.index', data};
+}

package/api/docs/index/index.test.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {docs} from '../docs.mjs';
+import {index} from './index.mjs';
+import {loadDocsCatalog} from '../_adapter.mjs';
+
+const SLOW = 60_000;
+
+describe('docs.index leaf', () => {
+  it('lists each section by key, title, and summary', async () => {
+    const res = await index('theme');
+    expect(res.type).toBe('docs.index');
+    expect(res.data).toMatchObject({name: 'theme', title: expect.any(String)});
+    const keys = res.data.sections.map(s => s.id);
+    expect(new Set(keys).size).toBe(keys.length);
+    for (const entry of res.data.sections) {
+      expect(Object.keys(entry)).toEqual(['id', 'title', 'summary']);
+      expect(entry.summary.length).toBeLessThanOrEqual(240);
+    }
+  }, SLOW);
+
+  it('names the sections the full topic has, with the same keys', async () => {
+    const full = await docs('theme');
+    const {data} = await index('theme');
+    expect(data.sections.map(s => [s.id, s.title])).toEqual(
+      full.data.sections.map(s => [s.id, s.title]),
+    );
+  }, SLOW);
+
+  it('keeps every key the same in every language', async () => {
+    const english = (await index('theme')).data.sections.map(s => s.id);
+    for (const lang of ['zh', 'dense']) {
+      const localized = await index('theme', {lang});
+      expect(localized.data.sections.map(s => s.id)).toEqual(english);
+    }
+  }, SLOW);
+
+  it('lists keys every section can be read by', async () => {
+    const catalog = await loadDocsCatalog();
+    for (const entry of catalog.entries()) {
+      const {data} = await index(entry.name);
+      for (const {id, title} of data.sections) {
+        const read = await docs(entry.name, id);
+        expect(read.data.title).toBe(title);
+      }
+    }
+  }, SLOW);
+});
+
+describe('docs() topic reads', () => {
+  it('returns the whole topic by default', async () => {
+    const res = await docs('theme');
+    expect(res.type).toBe('docs.detail');
+    expect(res.data.sections[0].content.length).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('returns the section index on request', async () => {
+    const res = await docs('theme', undefined, {index: true});
+    expect(res.type).toBe('docs.index');
+  }, SLOW);
+});