@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

package/api/docs/docs.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
       name: 'topic',
       type: 'string',
       description:
-        "Doc topic to load (e.g. 'principles'), or a docs-tree route (e.g. 'cli/api/functions/search'). Omit to list all topics.",
+        "Doc topic to load (e.g. 'principles'), a docs-tree route (e.g. 'cli/api/functions/search'), or the name of one node of the docs tree: its own name (e.g. 'tokens-color'), or its route without the prefix its name repeats (e.g. 'tokens/color'), where exactly one node answers to it. Omit to list all topics.",
     },
     {
       name: 'section',
@@ -88,13 +88,13 @@ export const doc = {
       name: 'options.depth',
       type: "number | 'all'",
       description:
-        "How many levels below a docs-tree namespace to read: 0 for the namespace alone, 1 for its children (the default), 'all' for every level. Where a read stops, a child with docs below it carries childCount. A doc with nothing below it reads the same at any depth.",
+        "How many levels below a docs-tree namespace to read: 0 for the namespace alone, 1 for its children (the default), 'all' for every level. Where a read stops, a child with docs below it carries childCount. A doc with nothing below it reads the same at any depth. On the topic list, where each namespace otherwise lists alone, it names the docs below each one, as deep as asked; without it the list is unchanged.",
     },
     {
       name: 'options.detail',
       type: "'brief' | 'compact' | 'full'",
       description:
-        "How much of each doc below the named one a depth read returns: brief (the default) is its identity; compact and full add its text (a guide's sections, a namespace's or typed doc's content). Given alone, it reads one level down.",
+        "How much of each doc below the named one a depth read returns: brief (the default) is its identity; compact and full add its text (a guide's sections, a namespace's or typed doc's content). Given alone, it reads one level down. The topic list names each doc below a namespace by its identity whatever the detail.",
     },
     {
       name: 'options.cwd',
@@ -107,7 +107,7 @@ export const doc = {
     {
       type: 'docs.list',
       description:
-        "Every reference-doc topic in read order, as DocsListEntry[] ({topic, description, package, replaces?, replacedPackage?}), each readable with docs(topic). meta.namespaces lists the docs tree's top-level namespaces ({topic, description, package}), and meta.notLoaded each package whose docs did not load ({package, message}).",
+        "Every reference-doc topic in read order, as DocsListEntry[] ({topic, description, package, replaces?, replacedPackage?}), each readable with docs(topic). meta.namespaces lists the docs tree's top-level namespaces ({topic, description, package}); with depth, each also carries children, the docs below it as a namespace read names them ({topic, description, route, name, package, kind, title, summary, replaces?, replacedPackage?, stability?}), nested the same way to the depth asked for, and childCount where the depth stops on a doc with docs below it. meta.notLoaded names each package whose docs did not load ({package, message}).",
     },
     {
       type: 'docs.detail',
@@ -141,7 +141,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_TOPIC',
-      when: 'the topic is not a string, or matches no topic and no docs-tree route',
+      when: 'the topic is not a string, or matches no topic, no docs-tree route, and no one node of the docs tree by its own name or by its route without the prefix its name repeats; a name more than one node answers to opens none of them, and the suggestions list them',
     },
     {
       code: 'ERR_UNKNOWN_SECTION',

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

@@ -56,6 +56,27 @@ export type DocsListNamespace = {
      * the package that owns it
      */
     package: string;
+    /**
+     * the docs below it, present only for
+     * a read that passed `depth` and only where the namespace has children
+     */
+    children?: DocsListChild[] | undefined;
+    /**
+     * how many docs sit right below it, where a
+     * depth read stops here and it has docs below it
+     */
+    childCount?: number | undefined;
+};
+/**
+ * One doc below a namespace on the topic list, as `astryx docs --depth` names
+ * it: everything a namespace read gives a child, plus the two fields every
+ * list row carries, so one row reads the same way wherever it came from.
+ */
+export type DocsListChild = DocsNodeChild & {
+    topic: string;
+    description: string;
+    children?: DocsListChild[];
+    childCount?: number;
 };
 /**
  * astryx --json docs <topic> --index

package/api/docs/docs.type.mjs

@@ -45,6 +45,17 @@
  * @property {string} topic its route, the argument that opens it
  * @property {string} description
  * @property {string} package the package that owns it
+ * @property {DocsListChild[]} [children] the docs below it, present only for
+ *   a read that passed `depth` and only where the namespace has children
+ * @property {number} [childCount] how many docs sit right below it, where a
+ *   depth read stops here and it has docs below it
+ */
+
+/**
+ * One doc below a namespace on the topic list, as `astryx docs --depth` names
+ * it: everything a namespace read gives a child, plus the two fields every
+ * list row carries, so one row reads the same way wherever it came from.
+ * @typedef {DocsNodeChild & {topic: string, description: string, children?: DocsListChild[], childCount?: number}} DocsListChild
  */
 
 /**

package/api/docs/list/list.d.mts

@@ -4,8 +4,12 @@
 /**
  * @param {object} [options]
  * @param {string} [options.cwd]
+ * @param {number | 'all'} [options.depth] how many levels of the docs tree to
+ *   list below each namespace; without it the namespaces list alone, as they
+ *   always have
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export function list({ cwd }?: {
+export function list({ cwd, depth }?: {
     cwd?: string | undefined;
+    depth?: number | "all" | undefined;
 }): Promise<import("../docs.type.mjs").DocsListResponse>;

package/api/docs/list/list.mjs

@@ -16,6 +16,7 @@
 
 import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
 import {
+  childIdentity,
   holdsOwnName,
   linkDocText,
   loadDocsCatalog,
@@ -25,9 +26,12 @@ import {
 /**
  * @param {object} [options]
  * @param {string} [options.cwd]
+ * @param {number | 'all'} [options.depth] how many levels of the docs tree to
+ *   list below each namespace; without it the namespaces list alone, as they
+ *   always have
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export async function list({cwd} = {}) {
+export async function list({cwd, depth} = {}) {
   const catalog = await loadDocsCatalog(cwd);
   const tree = await projectTree(catalog);
   /** @type {Array<import('../docs.type.mjs').DocsListEntry>} */
@@ -64,11 +68,11 @@ export async function list({cwd} = {}) {
   // The docs tree's top-level namespaces, the CLI's and each integration's,
   // each the way into a whole branch (spec:AST-046 FR7). They go in `meta`,
   // so `data` stays the topic list 0.6 returned: every entry reads as a topic.
-  const namespaces = tree.roots().map(root => ({
-    topic: root.route,
-    description: root.summary,
-    package: root.provider,
-  }));
+  // With `depth`, each one also carries the branch below it, so one read
+  // learns every route: without it a reader knows only that the namespace is
+  // there, and the children it must name are invisible until it opens each one.
+  const levels = depthLevels(depth);
+  const namespaces = tree.roots().map(root => branch(tree, root, levels));
   /** @type {NonNullable<import('../docs.type.mjs').DocsListResponse['meta']>} */
   const meta = {};
   if (namespaces.length > 0) meta.namespaces = namespaces;
@@ -79,3 +83,65 @@ export async function list({cwd} = {}) {
     ? {type: 'docs.list', data: entries}
     : {type: 'docs.list', data: entries, meta};
 }
+
+/**
+ * How many levels below each namespace the list carries: none without
+ * `depth`, every level for `'all'`. `docs <namespace> --depth` reads the same
+ * way, so one flag means one thing everywhere.
+ * @param {number | 'all'} [depth]
+ * @returns {number | null} null for a list read with no depth, which carries
+ *   the namespaces alone
+ */
+function depthLevels(depth) {
+  if (depth == null) return null;
+  return depth === 'all' ? Infinity : depth;
+}
+
+/**
+ * One namespace of the list, with the branch below it to `levels`. A child
+ * reads exactly as a namespace read gives it (`childIdentity`): the route
+ * that opens it, and the package that owns it — the integration's, for a
+ * guide an integration replaced, with the package whose route it took beside
+ * it. Every line of the list is then an argument a reader can pass straight
+ * back to `astryx docs`, attributed the way the read attributes it. Where the
+ * depth stops on a doc with docs below it, the row says how many, as a
+ * namespace read's child does; `levels` of null is a read with no depth,
+ * which says nothing about what is below.
+ * @param {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} tree
+ * @param {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} node
+ * @param {number | null} levels
+ * @returns {import('../docs.type.mjs').DocsListNamespace}
+ */
+function branch(tree, node, levels) {
+  /** @type {import('../docs.type.mjs').DocsListNamespace} */
+  const listed = {
+    topic: node.route,
+    description: node.summary,
+    package: node.provider,
+  };
+  if (levels == null) return listed;
+  const below = node.slots.flatMap(slot => slot.children);
+  if (levels <= 0) {
+    if (below.length > 0) listed.childCount = below.length;
+    return listed;
+  }
+  const children = below
+    .map(route => tree.get(route))
+    .filter(child => child != null)
+    .map(child => {
+      const node = /** @type {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} */ (
+        child
+      );
+      const {topic: _route, ...rest} = branch(tree, node, levels - 1);
+      const identity = childIdentity(tree, node);
+      return /** @type {import('../docs.type.mjs').DocsListChild} */ ({
+        ...identity,
+        topic: identity.route,
+        description: identity.summary,
+        ...(rest.children ? {children: rest.children} : {}),
+        ...(rest.childCount ? {childCount: rest.childCount} : {}),
+      });
+    });
+  if (children.length > 0) listed.children = children;
+  return listed;
+}

package/api/docs/node/node.mjs

@@ -16,13 +16,14 @@
  */
 
 import {detailView} from '../../../foundation/doc-compiler/lenses.mjs';
-import {isExperimentalTreeNode} from '../../../foundation/doc-compiler/tree.mjs';
 import {
+  childIdentity,
   compileTopic,
   guideEntry,
   nodeContent,
   placeLinks,
   resolveDocsArgument,
+  stabilityOf,
   unknownTopicError,
 } from '../_adapter.mjs';
 
@@ -87,45 +88,6 @@ export async function nodeView(catalog, tree, node, read) {
   return view;
 }
 
-/**
- * `stability: 'experimental'` for a node whose doc is marked experimental, or
- * that sits under an experimental namespace (spec:AST-017 FR27), the way help
- * marks an experimental command; nothing for a stable one, so stable entries
- * read as they always have.
- * @param {DocsTree} tree
- * @param {TreeNode} node
- * @returns {{stability?: 'experimental'}}
- */
-function stabilityOf(tree, node) {
-  return isExperimentalTreeNode(tree, node) ? {stability: 'experimental'} : {};
-}
-
-/**
- * The fields every child carries: what it is, and the route that opens it.
- * @param {DocsTree} tree
- * @param {TreeNode} child
- * @returns {import('../docs.type.mjs').DocsNodeChild}
- */
-function childIdentity(tree, child) {
-  return {
-    route: child.route,
-    name: child.route.slice(child.route.lastIndexOf('/') + 1),
-    package: child.guideOverlay?.replacement?.package ?? child.provider,
-    // A guide an integration's doc took the place of names whose it was.
-    ...(child.guideOverlay?.replacement
-      ? {
-          replaces: child.route,
-          replacedPackage:
-            child.guideOverlay.replacedPackage ?? child.provider,
-        }
-      : {}),
-    kind: child.kind,
-    title: child.title,
-    summary: child.summary,
-    ...stabilityOf(tree, child),
-  };
-}
-
 /**
  * @param {TreeNode['slots']} slots
  * @returns {number}

package/api/doctor/doctor.d.mts

@@ -196,14 +196,14 @@ export function checkCliCommand(ctx: DoctorContext): DoctorCheck;
  * @property {{cli: string, core: string | null, copy: string}} answeredBy
  * @property {string | null} latest the newest release known, or null
  * @property {Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState}>} [agentText]
-  *   each file of the computer-level agent text against this release's rendering
+ *   each file of the computer-level agent text against this release's rendering
  * @property {import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings} [agentTextSettings]
  *   the person's choices about the computer-level agent text
  * @property {string | null} [agentTextCommand] the command the skill file
  *   tells agents to run, or null
  * @property {string | null} [agentTextInstall] the install step the skill
  *   file records for when that command is not found, or null
-  * @property {string} [cwd] the folder doctor runs in, for the printed fix
+ * @property {string} [cwd] the folder doctor runs in, for the printed fix
  * @property {import('../../foundation/release/notices.mjs').GlobalBehind | null} [globalBehind]
  *   the CLI installed for the computer, when it is older than the newest
  *   release (outside a project)
@@ -215,7 +215,7 @@ export function checkCliCommand(ctx: DoctorContext): DoctorCheck;
  *   the newest update notice that did not print, and why (diagnostic only)
  * @property {{pid: number | null, host: string | null, since: number} | null} [stateLock]
  *   who holds the state file's lock now (diagnostic only)
-  * @property {Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade?: string | null, runner?: boolean}>} [searchPathCommands]
+ * @property {Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade?: string | null, runner?: boolean}>} [searchPathCommands]
  *   every `astryx` on the search path, with the command that upgrades it
  *   the `astryx` commands on the search path, in order
  * @property {import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]} [computerIntegrations]
@@ -281,7 +281,7 @@ export function checkComputerIntegrations(ctx: ComputerContext): DoctorCheck;
  *   fix points at the project's folder
  * @returns {DoctorCheck}
  */
-export function checkComputerIntegrationsAvailable({ installed, candidates, install, elsewhere }: {
+export function checkComputerIntegrationsAvailable({ installed, candidates, install, elsewhere, }: {
     installed: Set<string>;
     candidates: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
     install: ((name: string) => string) | null;