An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): read a section of a docs-tree namespace from the guide that has it (#7212)
Joey4ec0d0e9e68a
diff --git a/.changeset/layout-docs-namespace.md b/.changeset/layout-docs-namespace.mdindex 80fc18cc88..854680566d 100644--- a/.changeset/layout-docs-namespace.md+++ b/.changeset/layout-docs-namespace.md@@ -2,7 +2,7 @@'@astryxdesign/cli': patch----[docs] `astryx docs layout` still works and now lists the focused guides. Section reads move under them, for example `astryx docs layout/side-panels` or `astryx docs layout/scaffold shell`; the old `astryx docs layout <section>` form no longer resolves.+[docs] `astryx docs layout` still works and now lists the focused guides. Each section is also readable under its guide, for example `astryx docs layout/side-panels` or `astryx docs layout/scaffold shell`, and `astryx docs layout <section>` keeps working.(#7125)@josephfarinadiff --git a/.changeset/namespace-section-reads.md b/.changeset/namespace-section-reads.mdnew file mode 100644index 0000000000..d8a54055a9--- /dev/null+++ b/.changeset/namespace-section-reads.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] A section read on a docs-tree namespace answers from the guide that has the section again, so `astryx docs layout side-panels` and the other layout section reads released in 0.6.6 work after the layout split. `docs(route, section)` returns the same `docs.detail.section` the guide's own section read returns, found by key, then by title, in `--dense` and `--zh` too. When no guide or more than one has the section, the read fails with `ERR_UNKNOWN_SECTION` and names the guides to read it from.++@josephfarinadiff --git a/packages/cli/api/docs/detail/section/section.mjs b/packages/cli/api/docs/detail/section/section.mjsindex c4968525fe..acd7fad498 100644--- a/packages/cli/api/docs/detail/section/section.mjs+++ b/packages/cli/api/docs/detail/section/section.mjs@@ -11,6 +11,9 @@* token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.* Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches* more than one section (the candidates come back as suggestions).+ * A namespace's section read (spec:AST-046 FR6) finds the one guide below the+ * namespace that has the section and answers exactly as that guide's section+ * read does.* @position Leaf nested under api/docs/detail. Shares topic resolution with the* detail leaf via _adapter.mjs and reads through the compiler's lenses.*/@@ -20,6 +23,8 @@ import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';import {findDocSection,sectionKey,+ sectionTitleKey,+ sourceTitle,} from '../../../../foundation/discovery/docs-section-key.mjs';import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';import {@@ -43,19 +48,9 @@ import {* @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}*/export async function section(topic, sectionName, options = {}) {- // An empty section name must error, not resolve to the first section. The- // docs() dispatcher routes a falsy section to the topic, but the leaf must be- // safe on its own; a non-string would otherwise throw a raw TypeError.- if (typeof sectionName !== 'string' || !sectionName.trim()) {- throw new AstryxError(- 'A section name is required',- undefined,- ERROR_CODES.ERR_UNKNOWN_SECTION,- );- }-- const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);- const sections = readerSections(node);+ requireSectionName(sectionName);+ const resolved = await resolveTopicDocs(topic, options);+ const sections = readerSections(resolved.node);const {section: match} = findDocSection(sections, sectionName);if (!match) {throw new AstryxError(@@ -68,6 +63,33 @@ export async function section(topic, sectionName, options = {}) {);}+ return sectionResponse(resolved, sections, match);+}++/**+ * An empty section name must error, not resolve to the first section. The+ * docs() dispatcher routes a falsy section to the topic, but a leaf must be+ * safe on its own; a non-string would otherwise throw a raw TypeError.+ * @param {unknown} sectionName+ */+function requireSectionName(sectionName) {+ if (typeof sectionName !== 'string' || !sectionName.trim()) {+ throw new AstryxError(+ 'A section name is required',+ undefined,+ ERROR_CODES.ERR_UNKNOWN_SECTION,+ );+ }+}++/**+ * The docs.detail.section response for one section of a resolved topic.+ * @param {Awaited<ReturnType<typeof resolveTopicDocs>>} resolved+ * @param {any[]} sections the topic's reader sections+ * @param {any} match one of them+ * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}+ */+async function sectionResponse({catalog, node, lang, entry}, sections, match) {// A section read on its own inlines its token refs, as the whole topic does;// otherwise a section that is only a token-ref prints blank. Only this// section is linked, so a broken reference elsewhere cannot fail the read.@@ -93,3 +115,132 @@ export async function section(topic, sectionName, options = {}) {data: {...sectionView(node, linked), links},};}++/**+ * @typedef {object} GuideMatch+ * @property {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} guide+ * @property {Awaited<ReturnType<typeof resolveTopicDocs>>} resolved+ * @property {any[]} sections the guide's reader sections+ * @property {any} match the section it has+ */++/**+ * One section of a namespace (spec:AST-046 FR6): the section read of the one+ * guide below the namespace, at any depth, that has it. Each guide answers+ * with the section its own section read returns for the query; when that+ * section's key (its `id`, else the key its title derives) is the query in+ * some guides, those guides answer first. No guide, or several, fail with ERR_UNKNOWN_SECTION, naming+ * the guides to read instead.+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').DocsTree} tree+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} namespace+ * @param {string} sectionName+ * @param {object} [options] as {@link section}+ * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}+ */+export async function namespaceSection(+ tree,+ namespace,+ sectionName,+ options = {},+) {+ requireSectionName(sectionName);+ const guides = guidesBelow(tree, namespace);+ /** @type {Omit<GuideMatch, 'match'>[]} */+ const reads = [];+ for (const guide of guides) {+ const resolved = await resolveTopicDocs(guide.route, options);+ reads.push({guide, resolved, sections: readerSections(resolved.node)});+ }++ const wanted = sectionName.trim();+ const derived = sectionTitleKey(wanted);+ /** @type {GuideMatch[]} */+ const byKey = [];+ /** @type {GuideMatch[]} */+ const found = [];+ for (const read of reads) {+ // The section the guide's own section read returns for this query, so the+ // namespace read answers exactly what `astryx docs <guide> <section>` does.+ const {section: match} = findDocSection(read.sections, wanted);+ if (!match) continue;+ found.push({...read, match});+ if (+ sectionKey(match) === wanted ||+ (derived !== '' && sectionTitleKey(sourceTitle(match)) === derived)+ ) {+ byKey.push({...read, match});+ }+ }+ const matches = byKey.length > 0 ? byKey : found;+ const chosen = oneGuide(matches);+ if (chosen)+ return sectionResponse(chosen.resolved, chosen.sections, chosen.match);++ if (guides.length === 0) {+ // A namespace with no guide below it (a reference level such as cli/api)+ // has no sections to read: name its children, as before.+ throw new AstryxError(+ `"${namespace.route}" has no sections. Open one of its children instead.`,+ namespace.slots.flatMap(slot =>+ slot.children.map(route => ({+ name: route,+ reason: tree.get(route)?.summary ?? '',+ })),+ ),+ ERROR_CODES.ERR_UNKNOWN_SECTION,+ );+ }+ if (matches.length === 0) {+ throw new AstryxError(+ `Section "${sectionName}" is not in any guide under "${namespace.route}". Open one of its guides instead.`,+ guides.map(guide => ({name: guide.route, reason: guide.summary})),+ ERROR_CODES.ERR_UNKNOWN_SECTION,+ );+ }+ throw new AstryxError(+ `Section "${sectionName}" matches sections in more than one guide under "${namespace.route}". Read it from one of them.`,+ matches.map(({guide, match}) => ({+ name: guide.route,+ reason: `has "${match.title}"`,+ })),+ ERROR_CODES.ERR_UNKNOWN_SECTION,+ );+}++/**+ * The guide a namespace section read answers from, or null to ask. When the+ * query matches sections in several guides, the read asks the reader which+ * guide they mean (spec:AST-046 FR6), where a flat topic's section read+ * returned its first title match. To return the first match in tree order+ * instead, return `matches[0]` here.+ * @param {GuideMatch[]} matches in tree order+ * @returns {GuideMatch | null}+ */+export function oneGuide(matches) {+ return matches.length === 1 ? matches[0] : null;+}++/**+ * Every guide below a namespace, at any depth, in tree order.+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').DocsTree} tree+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} namespace+ * @returns {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode[]}+ */+function guidesBelow(tree, namespace) {+ /** @type {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode[]} */+ const guides = [];+ /** @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} parent */+ const walk = parent => {+ for (const slot of parent.slots) {+ for (const route of slot.children) {+ const child = tree.get(route);+ if (!child || child.parent !== parent.route) continue;+ if (child.kind === 'namespace') walk(child);+ else if (child.kind === 'generic' && child.ref?.topicFile)+ guides.push(child);+ }+ }+ };+ walk(namespace);+ return guides;+}diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjsindex 798e600baf..fb5d1dab02 100644--- a/packages/cli/api/docs/docs.doc.mjs+++ b/packages/cli/api/docs/docs.doc.mjs@@ -121,7 +121,7 @@ export const doc = {{type: 'docs.detail.section',description:- 'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined.',+ 'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined. Asked of a docs-tree namespace, it is the section read of the one guide below the namespace that has the section.',},{type: 'docs.node',@@ -144,7 +144,7 @@ export const doc = {},{code: 'ERR_UNKNOWN_SECTION',- when: 'a section is requested but is empty, matches no section, matches more than one, or is asked of a docs-tree namespace or typed doc, which have no sections',+ when: 'a section is requested but is empty, matches no section, or matches more than one; asked of a docs-tree namespace, when no guide below it or more than one has the section (suggestions name those guides); or asked of a typed doc, which has no sections',},],examples: [diff --git a/packages/cli/api/docs/docs.mjs b/packages/cli/api/docs/docs.mjsindex 4b8fe12dcd..d6d090a44d 100644--- a/packages/cli/api/docs/docs.mjs+++ b/packages/cli/api/docs/docs.mjs@@ -26,7 +26,10 @@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 {+ namespaceSection,+ 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';@@ -98,23 +101,15 @@ 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) {+ // A namespace answers a section read from the one guide below it that+ // has the section (spec:AST-046 FR6). A typed doc is one read.+ if (found.node.kind === 'namespace') {+ return namespaceSection(found.tree, found.node, section, options);+ }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}],+ `"${found.node.route}" has no sections. Read it whole: astryx docs ${found.node.route}.`,+ [{name: found.node.route, reason: found.node.summary}],ERROR_CODES.ERR_UNKNOWN_SECTION,);}diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjsindex a3f622a2cc..0f897d9771 100644--- a/packages/cli/api/docs/docs.test.mjs+++ b/packages/cli/api/docs/docs.test.mjs@@ -240,16 +240,15 @@ describe('docs() dispatcher routing', () => {);}, SLOW);- it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {- const err = await docs('cli', 'commands').catch(e => e);+ it('a section no guide of a namespace has -> ERR_UNKNOWN_SECTION, naming its guides', async () => {+ const err = await docs('cli', 'zzzz-nope').catch(e => e);expect(err).toBeInstanceOf(AstryxError);expect(err.code).toBe('ERR_UNKNOWN_SECTION');- // It names the namespace's children, in the order its slots list them.- const cli = (await docs('cli')).data;- expect(err.suggestions.map(s => s.name)).toEqual(- cli.slots.flatMap(slot => slot.children.map(child => child.route)),- );- expect(err.suggestions.map(s => s.name)).toContain('cli/commands');+ // It names every guide below the namespace, at any depth.+ const names = err.suggestions.map(s => s.name);+ expect(names).toContain('cli/component-lookups');+ expect(names).toContain('cli/integrations/quick-start');+ expect(names.every(name => name.startsWith('cli/'))).toBe(true);}, SLOW);it('an unknown route suggests the children of the deepest namespace it reaches', async () => {diff --git a/packages/cli/api/docs/namespace-section.test.mjs b/packages/cli/api/docs/namespace-section.test.mjsnew file mode 100644index 0000000000..3826e95292--- /dev/null+++ b/packages/cli/api/docs/namespace-section.test.mjs@@ -0,0 +1,260 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A section read on a namespace (spec:AST-046 FR6): `astryx docs+ * <namespace> <section>` answers from the one guide below the namespace that+ * has the section, exactly as that guide's own section read does, so a section+ * read that worked before a topic became a namespace still works.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {docs} from './docs.mjs';+import {oneGuide} from './detail/section/section.mjs';++const SLOW = 60_000;++/** @type {string} */+let tmpDir;++/** @param {Record<string, object>} files the integration's doc files */+function scaffold(files) {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: 'consumer'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit']};\n",+ );+ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'kit');+ fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});+ fs.writeFileSync(+ path.join(pkgDir, 'package.json'),+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(pkgDir, 'astryx.integration.mjs'),+ "export default {docs: './docs'};\n",+ );+ for (const [file, doc] of Object.entries(files)) {+ fs.writeFileSync(+ path.join(pkgDir, 'docs', file),+ `export const docs = ${JSON.stringify(doc, null, 2)};\n`,+ );+ }+}++/**+ * @param {string} name+ * @param {number} order+ * @param {Array<{title: string, id?: string}>} sections+ */+function guide(name, order, sections) {+ return {+ type: 'generic',+ name,+ title: `Acme ${name}`,+ description: `The ${name} guide.`,+ placement: {parent: 'namespace:acme', slot: 'guides', order},+ sections: sections.map(section => ({+ ...section,+ content: [{type: 'prose', text: `${section.title} text.`}],+ })),+ };+}++/** A namespace of two guides that both have a section titled "...setup". */+function kit() {+ return {+ 'acme.doc.mjs': {+ type: 'namespace',+ name: 'acme',+ title: 'Acme',+ summary: 'Everything about the Acme kit.',+ slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},+ },+ 'install.doc.mjs': guide('install', 1, [+ {title: 'Package setup', id: 'package-setup'},+ {title: 'Verify'},+ ]),+ 'theme.doc.mjs': guide('theme', 2, [+ {title: 'Theme setup'},+ {title: 'Dark mode'},+ ]),+ };+}++beforeEach(() => {+ tmpDir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-namespace-section-test-'),+ );+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('a section read on a namespace', () => {+ it(+ 'returns the one guide section, by key and by title, as the guide read does',+ async () => {+ for (const query of ['side-panels', 'Side panels', 'side panels']) {+ const read = await docs('layout', query);+ expect(read).toEqual(await docs('layout/side-panels', 'side-panels'));+ expect(read).toMatchObject({+ type: 'docs.detail.section',+ package: '@astryxdesign/cli',+ data: {id: 'side-panels', title: 'Side panels'},+ });+ }+ // A section in a guide of its own, and a section past a guide's first.+ expect((await docs('layout', 'shell')).data.id).toBe('shell');+ expect((await docs('layout', 'responsive-contract')).data.id).toBe(+ 'responsive-contract',+ );+ },+ SLOW,+ );++ it(+ 'reads dense and Chinese the way the guide read does',+ async () => {+ for (const options of [{dense: true}, {zh: true}, {lang: 'dense'}]) {+ expect(await docs('layout', 'side-panels', options)).toEqual(+ await docs('layout/side-panels', 'side-panels', options),+ );+ }+ },+ SLOW,+ );++ it(+ "prefers the guide whose section key is the query over another guide's title match",+ async () => {+ scaffold(kit());+ const read = await docs('acme', 'package-setup', {cwd: tmpDir});+ expect(read.data).toMatchObject({+ id: 'package-setup',+ title: 'Package setup',+ });+ expect(read.data.links.up).toBe('astryx docs acme/install --index');+ expect((await docs('acme', 'dark mode', {cwd: tmpDir})).data.title).toBe(+ 'Dark mode',+ );+ },+ SLOW,+ );++ it(+ 'fails on a miss, naming every guide below the namespace',+ async () => {+ const err = await docs('layout', 'zzzz-nope').catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ const names = err.suggestions.map(s => s.name);+ expect(names).toContain('layout/scaffold');+ expect(names).toContain('layout/side-panels');+ expect(names.every(name => name.startsWith('layout/'))).toBe(true);+ // At any depth: guides under nested namespaces are named, namespaces are not.+ const cli = await docs('cli', 'zzzz-nope').catch(e => e);+ expect(cli.code).toBe('ERR_UNKNOWN_SECTION');+ expect(cli.suggestions.map(s => s.name)).toContain(+ 'cli/integrations/quick-start',+ );+ expect(cli.suggestions.map(s => s.name)).not.toContain(+ 'cli/integrations',+ );+ },+ SLOW,+ );++ it(+ 'still fails a section on a typed doc, naming the doc',+ async () => {+ const err = await docs('cli/commands/docs', 'anything').catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ expect(err.suggestions.map(s => s.name)).toEqual(['cli/commands/docs']);+ },+ SLOW,+ );+});++describe('a namespace read answers what the guide read answers', () => {+ /** A guide with a title match before a key match, and a second guide. */+ function competing() {+ return {+ ...kit(),+ 'install.doc.mjs': guide('install', 1, [+ {title: 'Shell contract'},+ {title: 'Shell'},+ ]),+ 'theme.doc.mjs': guide('theme', 2, [{title: 'Setup', id: 'setup'}]),+ 'extra.doc.mjs': guide('extra', 3, [{title: 'Theme setup'}]),+ };+ }++ it(+ 'returns the section the guide read returns, even when a later section has the key',+ async () => {+ scaffold(competing());+ const own = await docs('acme/install', 'shell', {cwd: tmpDir});+ const read = await docs('acme', 'shell', {cwd: tmpDir});+ expect(read).toEqual(own);+ expect(read.data.title).toBe('Shell contract');+ },+ SLOW,+ );++ it(+ "prefers the guide whose own match is the query's key over another guide's title match",+ async () => {+ scaffold(competing());+ const read = await docs('acme', 'setup', {cwd: tmpDir});+ expect(read).toEqual(await docs('acme/theme', 'setup', {cwd: tmpDir}));+ expect(read.data).toMatchObject({id: 'setup', title: 'Setup'});+ },+ SLOW,+ );++ it(+ 'names the children of a namespace with no guide below it',+ async () => {+ const err = await docs('cli/api', 'anything').catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ const api = (await docs('cli/api')).data;+ expect(err.suggestions.map(s => s.name)).toEqual(+ api.slots.flatMap(slot => slot.children.map(child => child.route)),+ );+ expect(err.suggestions.length).toBeGreaterThan(0);+ expect(err.message).toContain('Open one of its children');+ },+ SLOW,+ );+});++describe('a section query that matches sections in several guides', () => {+ // It used to guess; now it asks. A flat topic's section read returns its+ // first title match; across guides, the read names each guide instead.+ it(+ 'asks which guide, naming each guide that matches',+ async () => {+ scaffold(kit());+ const err = await docs('acme', 'setup', {cwd: tmpDir}).catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ expect(err.suggestions).toEqual([+ {name: 'acme/install', reason: 'has "Package setup"'},+ {name: 'acme/theme', reason: 'has "Theme setup"'},+ ]);+ },+ SLOW,+ );++ it('decides in one place: oneGuide answers only a single match', () => {+ const a = /** @type {any} */ ({guide: {route: 'acme/install'}});+ const b = /** @type {any} */ ({guide: {route: 'acme/theme'}});+ expect(oneGuide([a])).toBe(a);+ expect(oneGuide([a, b])).toBeNull();+ expect(oneGuide([])).toBeNull();+ });+});diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjsindex 7ccced889f..cd16e1bf05 100644--- a/packages/cli/clients/cli/commands/docs.doc.mjs+++ b/packages/cli/clients/cli/commands/docs.doc.mjs@@ -22,7 +22,8 @@ export const doc = {'does, and `--index` its section index. A route ' +'opens a node of the docs tree: `cli` lists its guides and reference, ' +'`cli/api/functions` lists every API function, and `cli/api/functions/search` prints ' +- 'one. `--depth` reads as far down the tree as you ask, from the doc alone (0) to ' ++ 'one. A namespace plus a section prints that section from the one guide below it ' ++ 'that has it (`astryx docs layout side-panels`). `--depth` reads as far down the tree as you ask, from the doc alone (0) to ' +'everything below it (all), and with it `--detail` sets how much of each doc below ' +'shows: one line (brief, the default), its sections (compact), or all of it (full).',fn: 'docs',diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjsindex f4a5abfe8b..c848a51311 100644--- a/packages/cli/clients/cli/commands/docs.test.mjs+++ b/packages/cli/clients/cli/commands/docs.test.mjs@@ -330,22 +330,25 @@ describe('the docs tree, one level at a time', () => {expect(old.stderr).toContain('Unknown topic "cli-integrations"');}, SLOW);- it('returns docs.node as JSON, and fails a section of a namespace', async () => {+ it('returns docs.node as JSON, and reads a section of a namespace from its guide', async () => {const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);expect(node).toMatchObject({type: 'docs.node',data: {route: 'cli', kind: 'namespace', breadcrumb: []},});expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);- const section = await runCli(['docs', 'cli', 'commands', '--json']);- expect(section.status).toBe(1);- const error = JSON.parse(section.stdout);- expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});- // It names the namespace's children, in the order its slots list them.- expect(error.suggestions.map(s => s.name)).toEqual(- node.data.slots.flatMap(slot => slot.children.map(child => child.route)),+ const section = JSON.parse(+ (await runCli(['docs', 'layout', 'side-panels', '--json'])).stdout,);- expect(error.suggestions.map(s => s.name)).toContain('cli/commands');+ expect(section).toMatchObject({+ type: 'docs.detail.section',+ data: {id: 'side-panels', title: 'Side panels'},+ });+ const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);+ expect(missing.status).toBe(1);+ const error = JSON.parse(missing.stdout);+ expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});+ expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');}, SLOW);});