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

package/api/docs/docs.test.mjs

@@ -26,11 +26,15 @@ describe('docs() dispatcher routing', () => {
     expect((await docs('')).type).toBe('docs.list');
   }, SLOW);
 
-  it('topic only -> docs.detail', async () => {
+  it('topic only -> docs.detail, the whole doc', async () => {
     const {data} = await docs();
-    const topic = data[0].topic;
-    const r = await docs(topic);
-    expect(r.type).toBe('docs.detail');
+    expect((await docs(data[0].topic)).type).toBe('docs.detail');
+  }, SLOW);
+
+  it('topic + index -> docs.index', async () => {
+    const {data} = await docs();
+    const r = await docs(data[0].topic, undefined, {index: true});
+    expect(r.type).toBe('docs.index');
   }, SLOW);
 
   it('topic + section -> docs.detail.section', async () => {
@@ -63,6 +67,162 @@ describe('docs() dispatcher routing', () => {
     });
   }, SLOW);
 
+  it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
+    const res = await docs();
+    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'unorganized']);
+    for (const entry of res.data) {
+      expect((await docs(entry.topic)).type).toBe('docs.detail');
+    }
+  }, SLOW);
+
+  it('opens a route typed in another case', async () => {
+    const r = await docs('CLI/API');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({route: 'cli/api', links: {up: 'astryx docs cli'}});
+  }, SLOW);
+
+  it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {
+    const err = await docs('cli/api/functions/search', 'x').catch(e => e);
+    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.message).toContain('astryx docs cli/api/functions/search');
+    expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
+  }, SLOW);
+
+  it('a namespace route -> docs.node, one level of children', async () => {
+    const r = await docs('cli/api');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({
+      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/namespace/api',
+      route: 'cli/api',
+      kind: 'namespace',
+      package: '@astryxdesign/cli',
+      breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
+      content: [],
+    });
+    expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
+      'cli/api/functions',
+      'cli/api/schemas',
+      'cli/api/enums',
+    ]);
+  }, SLOW);
+
+  it('a typed doc route -> docs.node with its content', async () => {
+    const r = await docs('cli/api/functions/search');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({
+      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/function/search',
+      kind: 'function',
+      title: 'search()',
+      slots: [],
+    });
+    expect(r.data.breadcrumb.map(link => link.route)).toEqual([
+      'cli',
+      'cli/api',
+      'cli/api/functions',
+    ]);
+    expect(JSON.stringify(r.data.content)).toContain(
+      '`astryx search` runs it. Read it with `astryx docs cli/commands/search`.',
+    );
+  }, SLOW);
+
+  it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
+    expect((await docs('cli/integrations')).type).toBe('docs.detail');
+    const index = await docs('cli/integrations', undefined, {index: true});
+    expect(index).toMatchObject({type: 'docs.index', data: {name: 'cli/integrations'}});
+    expect(index.data.sections.length).toBeGreaterThan(1);
+    expect((await docs('cli/integrations', 'components')).type).toBe(
+      'docs.detail.section',
+    );
+  }, SLOW);
+
+  it('every read carries its moves (spec:AST-047)', async () => {
+    const root = (await docs('cli')).data;
+    expect(root.links).toEqual({up: 'astryx docs'});
+    const leaf = (await docs('cli/api/functions/search')).data;
+    expect(leaf.links.up).toBe('astryx docs cli/api/functions');
+    expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
+    expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
+    const index = await docs('cli/integrations', undefined, {index: true});
+    // A guide moves across its namespace's slot, as any tree node does.
+    expect(index.data.links).toEqual({
+      up: 'astryx docs cli',
+      next: 'astryx docs cli/writing-docs',
+    });
+    const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
+    expect(first.links).toEqual({
+      up: 'astryx docs cli/integrations --index',
+      next: `astryx docs cli/integrations ${index.data.sections[1].id}`,
+    });
+    const last = index.data.sections.at(-1).id;
+    const end = (await docs('cli/integrations', last)).data;
+    expect(end.links.next).toBeUndefined();
+    expect(end.links.previous).toBe(
+      `astryx docs cli/integrations ${index.data.sections.at(-2).id}`,
+    );
+    // A flat topic's home is the Unorganized level, and it moves across it.
+    const flat = (await docs('principles')).data.links;
+    expect(flat.up).toBe('astryx docs unorganized');
+    expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
+    expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
+    const home = (await docs('unorganized')).data;
+    expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    expect(home.slots[0].children.map(child => child.route)).toEqual(
+      (await docs()).data.map(entry => entry.topic),
+    );
+  }, SLOW);
+
+  it('names a node by its doc identity; a generated level has id null', async () => {
+    const level = (await docs('cli/api/functions')).data;
+    expect(level).toHaveProperty('id', null);
+    expect(level.route).toBe('cli/api/functions');
+  }, SLOW);
+
+  it("offers a typed doc's related docs as moves", async () => {
+    const fn = (await docs('cli/api/functions/search')).data;
+    expect(fn.links.related).toContain('astryx docs cli/commands/search');
+    const cmd = (await docs('cli/commands/search')).data;
+    expect(cmd.links.related).toContain('astryx docs cli/api/functions/search');
+  }, SLOW);
+
+  it('a topic read returns the whole doc; index returns its sections', async () => {
+    expect((await docs('principles')).type).toBe('docs.detail');
+    const index = await docs('principles', undefined, {index: true});
+    expect(index.type).toBe('docs.index');
+    expect(index.data.sections.length).toBeGreaterThan(1);
+    expect((await docs('principles', undefined, {dense: true})).type).toBe(
+      'docs.detail',
+    );
+  }, SLOW);
+
+  it("the guide's old flat name is gone, and its error names the new route", async () => {
+    await expect(docs('cli-integrations')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_TOPIC',
+      suggestions: [expect.objectContaining({name: 'cli/integrations'})],
+    });
+    expect((await docs()).data.map(entry => entry.topic)).not.toContain(
+      'cli-integrations',
+    );
+  }, SLOW);
+
+  it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {
+    const err = await docs('cli', 'commands').catch(e => e);
+    expect(err).toBeInstanceOf(AstryxError);
+    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.suggestions.map(s => s.name)).toEqual([
+      'cli/integrations',
+      'cli/writing-docs',
+      'cli/commands',
+      'cli/api',
+    ]);
+  }, SLOW);
+
+  it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
+    const err = await docs('cli/api/functions/serch').catch(e => e);
+    expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
+    expect(err.suggestions.map(s => s.name)).toContain('cli/api/functions/search');
+    expect(err.suggestions.every(s => s.name.startsWith('cli/api/functions/'))).toBe(true);
+  }, SLOW);
+
   it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {
     for (const bad of [123, {}, ['tokens'], true]) {
       const err = await docs(/** @type {any} */ (bad)).catch(e => e);

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,198 @@ 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: import("@astryxdesign/cli/authoring").ReferenceDoc & {
+        links: DocsLinks;
+    };
 };
 /**
- * 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
+ * carries `link` (null when the target names no doc), and each `workflow` step
+ * carries `links`, one per reference.
+ */
+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: import("@astryxdesign/cli/authoring").ReferenceSection & {
+        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 +238,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,134 @@
  */
 
 /**
- * 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 {import('@astryxdesign/cli/authoring').ReferenceDoc & {links: DocsLinks}} data
+ *   the whole doc, and the moves from it
+ */
+
+/**
+ * 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
+ * carries `link` (null when the target names no doc), and each `workflow` step
+ * carries `links`, one per reference.
+ * @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
+ */
+
+/**
+ * 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
  */
 
 /**
- * xds --json docs <topic> <section>
+ * @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 {import('@astryxdesign/cli/authoring').ReferenceSection & {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 +173,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};
+}