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

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

@@ -6,7 +6,22 @@
  */
 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;
@@ -22,6 +37,21 @@ export type DocsListEntry = {
      */
     replaces?: string | undefined;
 };
+/**
+ * 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
  */
@@ -34,7 +64,65 @@ export type DocsIndexResponse = {
  */
 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[];
+};
+/**
+ * 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
@@ -48,6 +136,10 @@ export type DocsIndex = {
     title: string;
     description: string;
     sections: DocsIndexSection[];
+    /**
+     * the moves from the index
+     */
+    links: DocsLinks;
 };
 export type DocsIndexSection = {
     /**
@@ -66,7 +158,94 @@ export type DocsIndexSection = {
  */
 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()`.

package/api/docs/docs.type.mjs

@@ -10,6 +10,8 @@
  *   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
  */
 
@@ -17,7 +19,11 @@
  * 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,6 +36,15 @@
  *   was contributed as a replacement
  */
 
+/**
+ * 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
@@ -41,7 +56,51 @@
  * 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
  */
 
 /**
@@ -52,6 +111,7 @@
  * @property {string} title
  * @property {string} description
  * @property {DocsIndexSection[]} sections
+ * @property {DocsLinks} links the moves from the index
  */
 
 /**
@@ -66,7 +126,61 @@
  * 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
  */
 
 /**

package/api/docs/index/index.mjs

@@ -15,7 +15,7 @@
  */
 
 import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
-import {resolveTopicDocs} from '../_adapter.mjs';
+import {resolveTopicDocs, topicLinks} from '../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -27,6 +27,14 @@ import {resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
  */
 export async function index(topic, options = {}) {
-  const {node} = await resolveTopicDocs(topic, options);
-  return {type: 'docs.index', data: indexView(node)};
+  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

@@ -49,7 +49,7 @@ describe('docs.index leaf', () => {
 });
 
 describe('docs() topic reads', () => {
-  it('returns the whole topic by default, as before', async () => {
+  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);