An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): open a docs child named without its namespace (#10387)
Joeyc9c72973f69d
diff --git a/.changeset/docs-child-route.md b/.changeset/docs-child-route.mdnew file mode 100644index 0000000000..2291782d13--- /dev/null+++ b/.changeset/docs-child-route.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx docs` also opens a docs-tree node by its bare name, or by a route that drops the prefix its name repeats, when exactly one node matches: `astryx docs tokens-color` and `astryx docs tokens/color` both open `tokens/tokens-color`. Two or more nodes answering one name still fail with the suggestions they always listed, and an experimental doc still opens only by its marked route.++@josephfarinadiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 1515fa38ff..c34c78ed7c 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -1765,9 +1765,46 @@ export function nameOwner(tree, catalog, name) {return entry == null ? null : {kind: 'topic', entry};}const entry = catalog.resolve(name);- if (entry == null) return null;- const owner = routeOwner(tree, entry);- return owner == null ? {kind: 'topic', entry} : {kind: 'node', node: owner};+ if (entry != null) {+ const owner = routeOwner(tree, entry);+ return owner == null ? {kind: 'topic', entry} : {kind: 'node', node: owner};+ }+ return childOwner(tree, name);+}++/**+ * The child a reader names without its namespace, or with a route that leaves+ * out the prefix the child's own name repeats (spec:AST-046 FR5). A namespace+ * whose children repeat its name makes its own routes stutter: `tokens` holds+ * `tokens-color`, so the route is `tokens/tokens-color`, while the namespace+ * listing shows the bare `tokens-color`. Both spellings name one child, so+ * that child answers. Two or more children answering is ambiguous, and the+ * read falls through to the suggestion list, unchanged. An experimental doc+ * never answers to a bare name: its project reaches it only by a marked route+ * (spec:AST-017 FR27).+ * @param {DocsTree} tree+ * @param {string} name+ * @returns {{kind: 'node', node: TreeNode} | null}+ */+function childOwner(tree, name) {+ const wanted = name.toLowerCase();+ const slash = wanted.lastIndexOf('/');+ const parent = slash > 0 ? wanted.slice(0, slash) : null;+ const unstuttered =+ parent == null+ ? null+ : `${parent}/${parent.slice(parent.lastIndexOf('/') + 1)}-${wanted.slice(slash + 1)}`;+ const matches = [...tree.nodes.values()].filter(+ node =>+ node.ref?.flatTopic == null &&+ node.route.includes('/') &&+ // An experimental doc is reachable only by a route its project marked+ // as experimental (spec:AST-017 FR27): a bare name never opens one.+ !isExperimentalTreeNode(tree, node) &&+ (node.name?.toLowerCase() === wanted ||+ (unstuttered != null && node.route.toLowerCase() === unstuttered)),+ );+ return matches.length === 1 ? {kind: 'node', node: matches[0]} : null;}/**diff --git a/packages/cli/api/docs/docs.child-route.test.mjs b/packages/cli/api/docs/docs.child-route.test.mjsnew file mode 100644index 0000000000..db091cae68--- /dev/null+++ b/packages/cli/api/docs/docs.child-route.test.mjs@@ -0,0 +1,177 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A docs child named without its namespace (spec:AST-046 FR5). A+ * namespace whose children repeat its name makes its own routes stutter:+ * `tokens` holds `tokens-color`, so the route is `tokens/tokens-color`, while+ * the namespace listing shows the bare `tokens-color`. A reader who types what+ * the listing shows, or the route without the repeated prefix, names the one+ * child either way, so that child answers. Two children answering one name is+ * ambiguous, and the read still fails with its suggestions.+ */++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';++const SLOW = 60_000;++/** @type {string} */+let tmpDir;++/**+ * A project with two integrations, each a namespace holding a child named+ * `setup`, so one name has two owners.+ */+function scaffoldTwoOwners() {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: 'consumer'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/alpha', '@acme/beta']};\n",+ );+ for (const kit of ['alpha', 'beta']) {+ 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",+ );+ fs.writeFileSync(+ path.join(pkgDir, 'docs', `${kit}.doc.mjs`),+ `export const docs = ${JSON.stringify(+ {+ type: 'namespace',+ name: kit,+ title: kit,+ summary: `Everything about ${kit}.`,+ slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},+ },+ null,+ 2,+ )};\n`,+ );+ fs.writeFileSync(+ path.join(pkgDir, 'docs', 'setup.doc.mjs'),+ `export const docs = ${JSON.stringify(+ {+ type: 'generic',+ name: 'setup',+ title: `${kit} setup`,+ description: `How to set up ${kit}.`,+ placement: {parent: `namespace:${kit}`, slot: 'guides', order: 1},+ sections: [+ {title: 'Steps', content: [{type: 'prose', text: 'Steps.'}]},+ ],+ },+ null,+ 2,+ )};\n`,+ );+ }+}++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-child-route-test-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('a docs child named without its namespace', () => {+ it(+ 'opens the child a reader names by the name the listing shows',+ async () => {+ const canonical = await docs('tokens/tokens-color');+ expect(await docs('tokens-color')).toEqual(canonical);+ expect(canonical.data.name).toBe('tokens/tokens-color');+ },+ SLOW,+ );++ it(+ 'opens the child whose route leaves out the prefix its name repeats',+ async () => {+ expect(await docs('tokens/color')).toEqual(+ await docs('tokens/tokens-color'),+ );+ expect(await docs('tokens/usage')).toEqual(+ await docs('tokens/tokens-usage'),+ );+ },+ SLOW,+ );++ it(+ 'opens a child of a namespace that does not stutter',+ async () => {+ expect(await docs('headers-and-footers')).toEqual(+ await docs('layout/headers-and-footers'),+ );+ },+ SLOW,+ );++ it(+ 'leaves every name that already worked alone',+ async () => {+ expect((await docs('tokens')).data.route).toBe('tokens');+ expect((await docs('layout/side-panels')).data.name).toBe(+ 'layout/side-panels',+ );+ },+ SLOW,+ );++ it(+ 'never opens an experimental doc by a bare name',+ async () => {+ // `add`, `calendar` and `render` name experimental docs the project+ // reaches only by a marked route (spec:AST-017 FR27).+ for (const name of ['add', 'calendar', 'render']) {+ await expect(docs(name)).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_TOPIC',+ });+ }+ },+ SLOW,+ );++ it(+ 'still refuses a name no child holds',+ async () => {+ await expect(docs('Button')).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_TOPIC',+ });+ await expect(docs('tokens/nope')).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_TOPIC',+ });+ },+ SLOW,+ );++ it(+ 'still refuses a name two children hold, and names them both',+ async () => {+ scaffoldTwoOwners();+ const error = await docs('setup', undefined, {cwd: tmpDir}).catch(+ caught => caught,+ );+ expect(error).toMatchObject({code: 'ERR_UNKNOWN_TOPIC'});+ const suggested = (error.suggestions ?? []).map(+ (/** @type {{name: string}} */ one) => one.name,+ );+ expect(suggested).toContain('alpha/setup');+ expect(suggested).toContain('beta/setup');+ },+ SLOW,+ );+});diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjsindex 5e0a86f2c8..004da772cb 100644--- a/packages/cli/api/docs/docs.doc.mjs+++ b/packages/cli/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',@@ -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',diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjsindex 6a7f0470fe..2ee6160875 100644--- a/packages/cli/api/docs/docs.test.mjs+++ b/packages/cli/api/docs/docs.test.mjs@@ -255,10 +255,12 @@ describe('docs() dispatcher routing', () => {}, SLOW);it('an unknown route keeps every child of its namespace, closest first', async () => {- const error = await docs('tokens/usage').catch(e => e);+ // `tokens/usage` names the one child whose name repeats the namespace, so+ // it opens it now; a route no child answers to still lists them all.+ const error = await docs('tokens/colour').catch(e => e);expect(error.code).toBe('ERR_UNKNOWN_TOPIC');const names = error.suggestions.map(s => s.name);- expect(names[0]).toBe('tokens/tokens-usage');+ expect(names[0]).toBe('tokens/tokens-color');const none = await docs('tokens/zzzz-nope').catch(e => e);expect([...names].sort()).toEqual(none.suggestions.map(s => s.name).sort());}, SLOW);