Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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);