An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): name the docs below each namespace on the topic list with --depth (#10393)
Joey13ef762c0cad
diff --git a/.changeset/docs-list-depth.md b/.changeset/docs-list-depth.mdnew file mode 100644index 0000000000..1d980c05e3--- /dev/null+++ b/.changeset/docs-list-depth.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx docs --depth <levels>` now names the docs below each namespace on the topic list, by the route that opens them, so one read learns every route instead of one read per namespace. Without `--depth` the list is unchanged, and the JSON keeps its shape: the new `children` sit inside each `meta.namespaces` entry.++@josephfarinadiff --git a/docs/specs/AST-046-docs-tree/spec.md b/docs/specs/AST-046-docs-tree/spec.mdindex 9298cf07f0..32308fe928 100644--- a/docs/specs/AST-046-docs-tree/spec.md+++ b/docs/specs/AST-046-docs-tree/spec.md@@ -140,7 +140,18 @@ and references from other packages are an open question (OQ2).every entry in it reads as a topic. The text view MUST show the namespaces first,under their own heading, because that is where the CLI's own docs start. Apackage whose docs did not load MUST be named, in `meta.notLoaded` and under- its own heading in text, so its author knows why its docs are missing.+ its own heading in text, so its author knows why its docs are missing. A list+ read with a depth (FR6) MUST carry the tree below each namespace: each entry+ in `meta.namespaces` gains a `children` array of the docs one level below it,+ each shaped as a child of a namespace read (its route, name, package, kind,+ title, summary, and its experimental mark), with the `topic` and+ `description` every list entry carries, and its own `children` while the+ depth goes deeper. Where the depth stops on a doc that has docs below it,+ that row MUST carry their count, as a namespace read's child does. The text+ view MUST list those docs under the same Docs tree heading, each by the route+ that opens it, and MUST mark an experimental one as every other listing marks+ it. A list read without a depth carries none of this, so the reader who asks+ for the topics still gets the topics.- **FR8 — Doctor proves the tree.** `astryx doctor` MUST warn when the tree hasan error diagnostic, when a CLI typed doc whose group the tree reads has noroute, and when a link between docs names no doc (`spec:AST-047` FR9). These@@ -317,18 +328,18 @@ Phase 1 changes these surfaces:## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |-| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |-| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route; a section on a namespace that one guide, no guide, and two guides hold | A namespace that inlines grandchildren, a lost section read, a section read that picks one of two guides, or a wrong error code |-| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |-| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |-| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |-| FR11 | Integration tree tests; guide route target tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route; a flat topic that replaces or extends a CLI guide by its route, with `before` and `after` | A node named by the package name, a broken link that passes either doctor, an integration that takes a CLI route, a replaced guide or added section that names the wrong package, or a section out of place |-| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |-| FR13 | Split tests over the topic before and after, the graph walk, and search tests | each old section key read through the namespace; a link and a token reference to the old topic; a `--dense` read; the topic list and a search for one section | A dropped, merged, or copied section; a changed title or `id`; a reference left on the old identity; a name listed twice; a section found twice |-| FR14 | Docsite page-generation and route-resolution tests | a split namespace; a nested namespace; a package-page namespace; a namespace with a `category`, and one whose guides are all foundations docs; a generated topic level | An old address that stops resolving or lands in another sidebar group, a permanent guide redirect, a guide page on a non-package namespace, or a slug that is both a page and a redirect |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |+| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |+| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route; a section on a namespace that one guide, no guide, and two guides hold; the topic list read with and without a depth, and a guide one integration replaces | A namespace that inlines grandchildren, a lost section read, a section read that picks one of two guides, a wrong error code, a listed doc attributed to the package whose route it took, or an experimental doc listed unmarked |+| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |+| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |+| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |+| FR11 | Integration tree tests; guide route target tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route; a flat topic that replaces or extends a CLI guide by its route, with `before` and `after` | A node named by the package name, a broken link that passes either doctor, an integration that takes a CLI route, a replaced guide or added section that names the wrong package, or a section out of place |+| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |+| FR13 | Split tests over the topic before and after, the graph walk, and search tests | each old section key read through the namespace; a link and a token reference to the old topic; a `--dense` read; the topic list and a search for one section | A dropped, merged, or copied section; a changed title or `id`; a reference left on the old identity; a name listed twice; a section found twice |+| FR14 | Docsite page-generation and route-resolution tests | a split namespace; a nested namespace; a package-page namespace; a namespace with a `category`, and one whose guides are all foundations docs; a generated topic level | An old address that stops resolving or lands in another sidebar group, a permanent guide redirect, a guide page on a non-package namespace, or a slug that is both a page and a redirect |## Decision logdiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex c34c78ed7c..531f5038b0 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -1807,6 +1807,47 @@ function childOwner(tree, name) {return matches.length === 1 ? {kind: 'node', node: matches[0]} : null;}+/**+ * `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'}}+ */+export function stabilityOf(tree, node) {+ return isExperimentalTreeNode(tree, node) ? {stability: 'experimental'} : {};+}++/**+ * The fields every child carries: what it is, and the route that opens it.+ * Shared, so a child reads the same whether a namespace read or the topic+ * list names it — including the package, which is the integration's for a+ * guide an integration replaced, not the package whose route it took.+ * @param {DocsTree} tree+ * @param {TreeNode} child+ * @returns {import('./docs.type.mjs').DocsNodeChild}+ */+export 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),+ };+}+/*** Whether a topic answers to its own name: what the topic list and search* offer must open that topic.diff --git a/packages/cli/api/docs/docs.depth.test.mjs b/packages/cli/api/docs/docs.depth.test.mjsindex d04c20ff1b..5433bba74f 100644--- a/packages/cli/api/docs/docs.depth.test.mjs+++ b/packages/cli/api/docs/docs.depth.test.mjs@@ -114,6 +114,95 @@ describe('docs() depth', () => {SLOW,);+ it(+ 'lists the docs below each namespace when the list is read with a depth',+ async () => {+ const plain = await docs();+ if (plain.type !== 'docs.list') return;+ // The list every reader has today: namespaces, and nothing below them.+ expect(plain.meta?.namespaces?.every(one => one.children == null)).toBe(+ true,+ );+ const one = await docs(undefined, undefined, {depth: 1});+ if (one.type !== 'docs.list') return;+ // `data` is the flat topic list it has always been.+ expect(one.data).toEqual(plain.data);+ const tokens = (one.meta?.namespaces ?? []).find(+ each => each.topic === 'tokens',+ );+ expect(tokens?.children?.map(child => child.topic)).toContain(+ 'tokens/tokens-color',+ );+ // One level only: a child of a child is not there yet.+ expect(+ (one.meta?.namespaces ?? [])+ .flatMap(each => each.children ?? [])+ .flatMap(child => child.children ?? []),+ ).toEqual([]);+ },+ SLOW,+ );++ it(+ 'says how many docs sit below a list row where the depth stops',+ async () => {+ const one = await docs(undefined, undefined, {depth: 1});+ if (one.type !== 'docs.list') return;+ const cli = (one.meta?.namespaces ?? []).find(+ each => each.topic === 'cli',+ );+ const api = (cli?.children ?? []).find(each => each.topic === 'cli/api');+ // The same count the namespace read gives the same row.+ const read = await docs('cli', undefined, {depth: 1});+ if (read.type !== 'docs.node') return;+ const fromRead = read.data.slots+ .flatMap((/** @type {any} */ slot) => slot.children)+ .find((/** @type {any} */ child) => child.route === 'cli/api');+ expect(api?.childCount).toBe(fromRead.childCount);+ expect(api?.childCount).toBeGreaterThan(0);+ // A row the depth did not stop on carries children instead of a count.+ const deeper = await docs(undefined, undefined, {depth: 2});+ if (deeper.type !== 'docs.list') return;+ const apiDeeper = (+ (deeper.meta?.namespaces ?? []).find(each => each.topic === 'cli')+ ?.children ?? []+ ).find(each => each.topic === 'cli/api');+ expect(apiDeeper?.children?.length).toBe(api?.childCount);+ expect(apiDeeper?.childCount).toBeUndefined();+ // A list with no depth says nothing about what is below.+ const plain = await docs();+ if (plain.type !== 'docs.list') return;+ expect(+ (plain.meta?.namespaces ?? []).every(each => each.childCount == null),+ ).toBe(true);+ },+ SLOW,+ );++ it(+ 'lists the whole tree for a depth of all, each doc by the route that opens it',+ async () => {+ const all = await docs(undefined, undefined, {depth: 'all'});+ if (all.type !== 'docs.list') return;+ /** @param {import('./docs.type.mjs').DocsListNamespace[]} nodes */+ const routes = nodes =>+ nodes.flatMap(node => [node.topic, ...routes(node.children ?? [])]);+ const listed = routes(all.meta?.namespaces ?? []);+ // A route the list names opens the doc it names.+ expect(listed).toContain('authoring/building-blocks/components');+ const deep = (await docs('authoring/building-blocks/components')).data;+ expect(deep.route ?? deep.name).toBe(+ 'authoring/building-blocks/components',+ );+ // Deeper than one level, and every route is unique.+ expect(listed.length).toBeGreaterThan(+ (await docs(undefined, undefined, {depth: 1})).meta?.namespaces?.length,+ );+ expect(new Set(listed).size).toBe(listed.length);+ },+ SLOW,+ );+it('refuses a depth that is not a number of levels, and an unknown detail',async () => {diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjsindex 004da772cb..5704c2a39d 100644--- a/packages/cli/api/docs/docs.doc.mjs+++ b/packages/cli/api/docs/docs.doc.mjs@@ -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',diff --git a/packages/cli/api/docs/docs.type.mjs b/packages/cli/api/docs/docs.type.mjsindex e710209d96..b4c4196b54 100644--- a/packages/cli/api/docs/docs.type.mjs+++ b/packages/cli/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*//**diff --git a/packages/cli/api/docs/guide-route-targets.test.mjs b/packages/cli/api/docs/guide-route-targets.test.mjsindex 47292341b2..3f0bbfeed3 100644--- a/packages/cli/api/docs/guide-route-targets.test.mjs+++ b/packages/cli/api/docs/guide-route-targets.test.mjs@@ -154,6 +154,34 @@ describe('a flat topic that replaces a placed guide by its route', () => {SLOW,);+ it(+ 'lists under its own package where the topic list names the guide',+ async () => {+ const list = await docs(undefined, undefined, {cwd: tmpDir, depth: 'all'});+ if (list.type !== 'docs.list') return;+ /** @param {any[]} rows */+ const flat = rows =>+ rows.flatMap((/** @type {any} */ row) => [+ row,+ ...flat(row.children ?? []),+ ]);+ const child = flat(list.meta?.namespaces ?? []).find(+ (/** @type {any} */ row) => row.topic === GUIDE,+ );+ // The same attribution the namespace read gives it, not the package+ // whose route it took.+ expect(child).toMatchObject({+ package: KIT,+ replaces: GUIDE,+ replacedPackage: CLI,+ title: 'Acme quick-start',+ });+ const text = await cliText(['docs', '--depth', 'all']);+ expect(text.stdout).toContain(GUIDE);+ },+ SLOW,+ );+it('lists under its own package where its namespace lists the guide',async () => {diff --git a/packages/cli/api/docs/list/list.mjs b/packages/cli/api/docs/list/list.mjsindex c1b6aa288c..edfb477599 100644--- a/packages/cli/api/docs/list/list.mjs+++ b/packages/cli/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;+}diff --git a/packages/cli/api/docs/node/node.mjs b/packages/cli/api/docs/node/node.mjsindex 396fd20f14..1ff7dc7d16 100644--- a/packages/cli/api/docs/node/node.mjs+++ b/packages/cli/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}diff --git a/packages/cli/clients/cli/commands/docs.depth.test.mjs b/packages/cli/clients/cli/commands/docs.depth.test.mjsindex 086d34d474..dfb7376f8d 100644--- a/packages/cli/clients/cli/commands/docs.depth.test.mjs+++ b/packages/cli/clients/cli/commands/docs.depth.test.mjs@@ -216,4 +216,52 @@ describe('astryx docs --depth', () => {},SLOW,);++ it(+ 'marks an experimental doc on the list as every other listing marks it',+ async () => {+ const list = await runCli(['docs', '--depth', 'all']);+ expect(list.status).toBe(0);+ const row = list.stdout+ .split('\n')+ .find(line => line.includes('cli/api/functions/render'));+ expect(row).toBeDefined();+ expect(row).toContain('[experimental]');+ // The namespace read marks the same doc the same way.+ const read = await runCli(['docs', 'cli/api/functions']);+ expect(read.stdout).toContain('[experimental]');+ // A stable neighbour is not marked.+ const stable = list.stdout+ .split('\n')+ .find(line => line.includes('cli/api/functions/search'));+ expect(stable).toBeDefined();+ expect(stable).not.toContain('[experimental]');+ },+ SLOW,+ );++ it(+ 'the topic list names the docs below each namespace with a depth',+ async () => {+ const plain = await runCli(['docs']);+ expect(plain.stdout).toContain('tokens');+ // Today's list names the namespace and stops there.+ expect(plain.stdout).not.toContain('tokens/tokens-color');+ const deep = await runCli(['docs', '--depth', '1']);+ expect(deep.status).toBe(0);+ expect(deep.stdout).toContain('tokens/tokens-color');+ // Each row is the route that opens it, whatever its depth.+ const json = await runCli(['--json', 'docs', '--depth', '1']);+ const listed = JSON.parse(json.stdout);+ const tokens = listed.meta.namespaces.find(+ (/** @type {{topic: string}} */ one) => one.topic === 'tokens',+ );+ expect(tokens.children.map((/** @type {{topic: string}} */ c) => c.topic)).toContain(+ 'tokens/tokens-color',+ );+ const read = await runCli(['docs', 'tokens/tokens-color']);+ expect(read.status).toBe(0);+ },+ SLOW,+ );});diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjsindex 804ce81f17..829b58ce40 100644--- a/packages/cli/clients/cli/commands/docs.doc.mjs+++ b/packages/cli/clients/cli/commands/docs.doc.mjs@@ -46,7 +46,7 @@ export const doc = {flag: '--depth <levels>',param: 'options.depth',description:- 'How many levels of the docs tree to read below a namespace: 0 for the namespace alone, 1 for its children (what a read without --depth shows), all for everything below it. With it, --detail sets how much of each doc below shows: brief (one line each, the default), compact (with its sections), or full',+ 'How many levels of the docs tree to read below a namespace: 0 for the namespace alone, 1 for its children (what a read without --depth shows), all for everything below it. On the topic list, where a namespace otherwise lists alone, it names the docs below each one by the route that opens them, one line each. With it on a namespace read, --detail sets how much of each doc below shows: brief (one line each, the default), compact (with its sections), or full; the topic list is one line per doc whatever the detail',},],examples: [@@ -56,6 +56,10 @@ export const doc = {{label: 'One section', cli: 'astryx docs theme quick-start'},{label: 'The CLI docs tree', cli: 'astryx docs cli'},{label: 'Every CLI doc, one line each', cli: 'astryx docs cli --depth all'},+ {+ label: 'Every route in the docs tree, one line each',+ cli: 'astryx docs --depth all',+ },{label: 'The integration guides as one read',cli: 'astryx docs authoring --depth all --detail full',diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjsindex 6669e014ce..6ea9fdc465 100644--- a/packages/cli/clients/cli/commands/docs.mjs+++ b/packages/cli/clients/cli/commands/docs.mjs@@ -615,6 +615,32 @@ function summarize(result) {// ─── Command ─────────────────────────────────────────────────────────────────+/**+ * Every namespace of the list and, where a `--depth` read carried them, the+ * docs below it, in reading order and in one flat list: each row's `topic` is+ * the route that opens it, so the depth of a row never changes how a reader+ * uses it, and each names the package that owns it.+ * @param {Array<import('../../../api/docs/docs.type.mjs').DocsListNamespace | import('../../../api/docs/docs.type.mjs').DocsListChild>} rows+ * @returns {Array<{topic: string, description: string, package: string}>}+ */+function flattenNamespaces(rows) {+ return rows.flatMap(row => [+ {+ topic: row.topic,+ // An experimental doc is marked here as it is wherever else it is+ // listed, so a reader cannot take a row of this list for a stable doc.+ description:+ 'stability' in row &&+ row.stability === 'experimental' &&+ !/^experimental\b/iu.test(row.description)+ ? `[experimental] ${row.description}`+ : row.description,+ package: row.package,+ },+ ...flattenNamespaces(row.children ?? []),+ ]);+}+/*** @param {import('commander').Command} program*/@@ -703,8 +729,10 @@ export function registerDocs(program) {// The text view mirrors the JSON list, with the docs tree's// namespaces (`meta.namespaces`) first under their own heading: that// is where the CLI's own docs start, and a namespace reads- // differently from a topic.- const namespaces = result.meta?.namespaces ?? [];+ // differently from a topic. With --depth each branch is flattened+ // into the same list, so every line is a route a reader can pass+ // straight back to `docs`.+ const namespaces = flattenNamespaces(result.meta?.namespaces ?? []);const topics = result.data;emit(...(namespaces.length > 0diff --git a/packages/cli/test/__golden__/no-icon-set/manifest.json b/packages/cli/test/__golden__/no-icon-set/manifest.jsonindex 0907332f90..25053b0512 100644--- a/packages/cli/test/__golden__/no-icon-set/manifest.json+++ b/packages/cli/test/__golden__/no-icon-set/manifest.json@@ -325,6 +325,7 @@"<text>","<text>","<text>",+ "<text>","<text>"],"exitCodes": [