@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

package/clients/cli/commands/discover.text-projection.test.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` text output projects every field of its JSON entry.
+ *
+ * The text views of `discover.list` and `discover.detail` are renderings of the
+ * same entries `--json` returns, so each entry key must appear as a `key:` line
+ * carrying the same value.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+let tmpDir;
+let project;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-text-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'proj', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/kit']};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '3.1.4'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  for (const name of ['Dial', 'Gauge']) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.doc.mjs`),
+      `export const docs = {name: '${name}', usage: {description: 'A ${name}.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.tsx`),
+      `export function ${name}() { return null; }\n`,
+    );
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * @param {Record<string, unknown>} entry
+ * @param {string} text
+ */
+function expectEveryField(entry, text) {
+  const lines = text.split('\n');
+  for (const [key, value] of Object.entries(entry)) {
+    const rendered = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(lines).toContainEqual(
+      expect.stringMatching(new RegExp(`^${key}:\\s+${escape(rendered)}$`)),
+    );
+  }
+}
+
+/** @param {string} s */
+function escape(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+describe('astryx discover text output', () => {
+  it('lists every field of each discover.list entry', async () => {
+    const asJson = await runCli(['discover', '--json'], {cwd: project});
+    const [entry] = JSON.parse(asJson.stdout).data;
+    expect(Object.keys(entry)).toEqual(
+      expect.arrayContaining(['name', 'category', 'components', 'version']),
+    );
+
+    const {status, stdout} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expectEveryField(entry, stdout);
+  });
+
+  it('shows every field of the discover.detail entry', async () => {
+    const asJson = await runCli(['discover', '@test/kit', '--json'], {
+      cwd: project,
+    });
+    const {data} = JSON.parse(asJson.stdout);
+
+    const {status, stdout} = await runCli(['discover', '@test/kit'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expectEveryField(data, stdout);
+  });
+});

package/clients/cli/commands/docs.doc.mjs

@@ -12,26 +12,48 @@ export const doc = {
   type: 'command',
   name: 'docs',
   displayName: 'astryx docs',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print reference docs',
   description:
-    'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +
-    'full doc; a topic plus a section returns the first section whose title contains the ' +
-    '(case-insensitive) query.',
+    'Reads the reference docs one level at a time: with no topic it lists every topic; a ' +
+    'topic lists its sections, each with the key to read it by (a topic with one section ' +
+    'prints whole); a topic plus a section prints that section; `--full` prints the whole ' +
+    'topic, as does `--dense`. With `--json`, a topic returns its whole doc, as docs() ' +
+    '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.',
   fn: 'docs',
   args: [
     {name: 'topic', param: 'topic', required: false},
     {name: 'section', param: 'section', required: false},
   ],
+  options: [
+    {
+      flag: '--index',
+      param: 'options.index',
+      description: "List the topic's sections and their keys, even for a topic with one section",
+    },
+    {
+      flag: '--full',
+      description:
+        'Print the whole topic instead of its sections (text; `--json` returns the whole topic unless --index). Cannot be set with --index',
+    },
+  ],
   examples: [
     {label: 'List topics', cli: 'astryx docs'},
-    {label: 'One topic as JSON', cli: 'astryx docs spacing --json'},
+    {label: "A topic's sections", cli: 'astryx docs theme'},
+    {label: 'A whole topic as JSON', cli: 'astryx docs spacing --json'},
+    {label: 'One section', cli: 'astryx docs theme quick-start'},
+    {label: 'The CLI docs tree', cli: 'astryx docs cli'},
+    {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown topic, or a section that matches no title in the topic',
+      when: 'unknown topic or route, or a section that matches no section or more than one',
     },
   ],
   related: ['search', 'component', 'hook', 'template'],

package/clients/cli/commands/docs.mjs

@@ -3,19 +3,37 @@
 /**
  * @file docs command — Print Astryx reference docs
  *
- * Auto-discovers .doc.mjs files from the docs/ directory.
+ * In text, every read is one level: a topic lists its sections, so a reader can
+ * open one section by its key, and `--full` prints the whole topic. `--json`
+ * keeps the docs() contract: a topic returns its whole doc, and `--index` its
+ * sections.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
  *
  * Usage:
  *   astryx docs                          List available topics
- *   astryx docs <topic>                  Print full doc
+ *   astryx docs <topic>                  List the topic's sections (a topic
+ *                                        with one section prints whole)
  *   astryx docs <topic> <section>        Print one section
+ *   astryx docs <topic> --full           Print the whole topic
+ *   astryx docs <route>                  Open a node of the docs tree, such as
+ *                                        cli, cli/api, or cli/api/functions/search
  */
 
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text, code} from '../formatters/index.mjs';
+import {
+  emit,
+  section,
+  records,
+  text,
+  code,
+  wrapText,
+} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {resultSet} from '../../../foundation/debug/index.mjs';
 import {docs as docsApi} from '../../../api/docs/docs.mjs';
@@ -80,10 +98,14 @@ function formatBlock(block, detail) {
       return formatTable(block.headers, block.rows);
 
     case 'list': {
-      const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
-        : block.style === 'dont' ? () => 'x '
-        : block.style === 'do' ? () => '+ '
-        : () => '- ';
+      const prefix =
+        block.style === 'ordered'
+          ? (/** @type {number} */ i) => `${i + 1}. `
+          : block.style === 'dont'
+            ? () => 'x '
+            : block.style === 'do'
+              ? () => '+ '
+              : () => '- ';
       return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
     }
 
@@ -107,7 +129,8 @@ function formatSection(section, detail) {
     return `${section.title}: ${first.split('\n')[0]}`;
   }
 
-  const heading = detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
+  const heading =
+    detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
   return `${heading}\n\n${blocks.join('\n\n')}`;
 }
 
@@ -123,22 +146,129 @@ function formatReferenceFull(docs, detail) {
     return `${header}\n${sections.join('\n')}`;
   }
 
-  const header = detail === 'compact'
-    ? `# ${docs.title}\n${docs.description}`
-    : `# ${docs.title}\n\n${docs.description}`;
+  const header =
+    detail === 'compact'
+      ? `# ${docs.title}\n${docs.description}`
+      : `# ${docs.title}\n\n${docs.description}`;
   const sections = docs.sections.map(s => formatSection(s, detail));
   const sep = detail === 'compact' ? '\n\n' : '\n\n';
   return `${header}\n\n${sections.join(sep)}`;
 }
 
+/**
+ * The moves a read offers (spec:AST-047), one runnable command per line: up to
+ * the level it sits in, the item before and after it, and the docs it names.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsLinks | undefined} links
+ * @returns {string[]}
+ */
+function linkLines(links) {
+  if (!links) return [];
+  return [
+    `Up: ${formatCliCommand(links.up)}`,
+    ...(links.previous ? [`Previous: ${formatCliCommand(links.previous)}`] : []),
+    ...(links.next ? [`Next: ${formatCliCommand(links.next)}`] : []),
+    ...(links.related ?? []).map(
+      (command, i) => `${i === 0 ? 'Related: ' : '         '}${formatCliCommand(command)}`,
+    ),
+  ];
+}
+
+/**
+ * A topic's section index: what the topic is, one line per section with the
+ * key to read it by, and how to read further.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsIndex} index
+ * @param {string} run
+ */
+function emitIndex(index, run) {
+  emit(
+    section(
+      index.title,
+      index.description ? wrapText(index.description) : undefined,
+    ),
+    // Summaries wrap rather than being cut: the summary is how a reader picks
+    // the one section to open.
+    records(index.sections, {
+      fields: ['id', 'title', 'summary'],
+      layout: 'inline',
+    }),
+    text(
+      [
+        `Read one section: ${run} docs ${index.name} <section>`,
+        `Read everything:  ${run} docs ${index.name} --full`,
+        ...linkLines(index.links),
+      ].join('\n'),
+    ),
+  );
+}
+
+/**
+ * One child row of a namespace: its route name, then the doc's own title when
+ * it is not the route name (`assertResponse()`, `search()`), then its summary.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
+ * @returns {{name: string, summary: string}}
+ */
+function childRow(child) {
+  return {
+    name: child.name,
+    summary:
+      child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
+  };
+}
+
+/**
+ * One node of the docs tree. A namespace lists each slot's children, one level
+ * down, with the command to open one; a typed doc prints its content. Both end
+ * with the way back up.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsNode} node
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @param {string} run
+ */
+function emitNode(node, detail, run) {
+  if (node.kind === 'namespace') {
+    emit(
+      section(node.title, wrapText(node.summary)),
+      ...node.slots.flatMap(slot => [
+        // A namespace with one slot titled like itself needs no second heading.
+        ...(node.slots.length === 1 && slot.title === node.title
+          ? []
+          : [section(slot.title)]),
+        records(slot.children.map(childRow), {
+          fields: ['name', 'summary'],
+          layout: 'inline',
+          overflow: 'truncate',
+        }),
+      ]),
+      text(
+        [
+          // A child's route is its parent's route and its name, except a flat
+          // topic in the Unorganized level, which keeps its own name.
+          node.slots.every(slot =>
+            slot.children.every(child => child.route.startsWith(`${node.route}/`)),
+          )
+            ? `Open one: ${run} docs ${node.route}/<name>`
+            : `Open one: ${run} docs <name>`,
+          ...linkLines(node.links),
+        ].join('\n'),
+      ),
+    );
+    return;
+  }
+  emit(
+    code(formatSection({title: node.title, content: node.content}, detail)),
+    text(linkLines(node.links).join('\n')),
+  );
+}
+
 /**
  * What the run answered with. A named topic (or one of its sections) resolves
  * or throws, so it is always a direct match of one doc; the bare form lists
  * every topic there is.
  *
  * @param {import('../../../api/docs/docs.type.mjs').DocsListResponse
+ *   | import('../../../api/docs/docs.type.mjs').DocsIndexResponse
  *   | import('../../../api/docs/docs.type.mjs').DocsDetailResponse
- *   | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse} result
+ *   | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse
+ *   | import('../../../api/docs/docs.type.mjs').DocsNodeResponse} result
  * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
@@ -155,7 +285,11 @@ function summarize(result) {
 export function registerDocs(program) {
   defineCommand(program, docsCommand, {
     fn: docsFn,
-    action: async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ sectionName) => {
+    action: async (
+      /** @type {string | undefined} */ topic,
+      /** @type {string | undefined} */ sectionName,
+      /** @type {{index?: boolean, full?: boolean}} */ options = {},
+    ) => {
       const run = getCliInvocation();
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
@@ -163,13 +297,42 @@ export function registerDocs(program) {
       const detail = program.opts().detail || 'full';
       const json = program.opts().json || false;
 
+      if (options.index && options.full) {
+        return cliError(
+          'Ask for the section list or the whole topic, not both: --index and --full cannot both be set.',
+          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+        );
+      }
+      // Text reads one level: a topic lists its sections (one with a single
+      // section prints whole). JSON keeps docs(): the whole topic unless
+      // --index. The dense variant is written to be read whole.
+      const listSections =
+        Boolean(options.index) ||
+        (!json &&
+          !options.full &&
+          !dense &&
+          lang !== 'dense' &&
+          sectionName == null);
       let result;
       try {
-        result = await docsApi(topic, sectionName, {lang, zh, dense});
+        result = await docsApi(topic, sectionName, {
+          lang,
+          zh,
+          dense,
+          index: listSections,
+        });
+        if (
+          !options.index &&
+          result.type === 'docs.index' &&
+          result.data.sections.length <= 1
+        ) {
+          result = await docsApi(topic, sectionName, {lang, zh, dense});
+        }
       } catch (e) {
         // docs API throws structured errors with {name, reason} suggestions —
         // pass them through untouched so the CLI envelope matches the API.
-        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        const err =
+          /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {
           suggestions: err.suggestions || [],
           code: err.code,
@@ -184,28 +347,79 @@ export function registerDocs(program) {
 
       switch (result.type) {
         case 'docs.list': {
-          // The text view mirrors the JSON list: one record per topic (topic +
-          // description), then the usage footer as plain prose.
+          // 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 ?? [];
+          const topics = result.data;
           emit(
-            section('Available docs'),
-            records(result.data, {fields: ['topic', 'description']}),
+            ...(namespaces.length > 0
+              ? [
+                  section('Docs tree'),
+                  records(namespaces, {
+                    fields: ['topic', 'description', 'package'],
+                    layout: 'inline',
+                  }),
+                ]
+              : []),
+            section('Topics'),
+            records(topics, {
+              fields: ['topic', 'description', 'package'],
+              layout: 'inline',
+            }),
             text(
               [
-                `Usage: ${run} docs <topic>`,
-                `       ${run} docs <topic> <section>`,
+                `Usage: ${run} docs <topic>                  list a topic's sections`,
+                `       ${run} docs <topic> <section>        read one section`,
+                `       ${run} docs <topic> --full           read the whole topic`,
+                `       ${run} docs cli/api                  go down the docs tree one level at a time`,
+                `With --json, a topic returns its whole doc; add --index for its section list.`,
               ].join('\n'),
             ),
+            // A package whose doc files did not load has no topics here; say
+            // so, and where to look, instead of leaving them silently missing.
+            ...(result.meta?.notLoaded?.length
+              ? [
+                  section('Not loaded'),
+                  records(result.meta.notLoaded, {
+                    fields: ['package', 'message'],
+                    layout: 'inline',
+                  }),
+                  text(
+                    `Run \`${run} doctor integration docs\` in that package to see every problem.`,
+                  ),
+                ]
+              : []),
           );
           break;
         }
 
+        case 'docs.index': {
+          emitIndex(result.data, run);
+          break;
+        }
+
         case 'docs.detail': {
-          emit(code(formatReferenceFull(result.data, detail)));
+          emit(
+            code(formatReferenceFull(result.data, detail)),
+            text(linkLines(result.data.links).join('\n')),
+          );
           break;
         }
 
         case 'docs.detail.section': {
-          emit(code(formatSection(result.data, detail)));
+          // One section ends with its moves: up to its topic's index, and to
+          // the sections before and after it.
+          emit(
+            code(formatSection(result.data, detail)),
+            text(linkLines(result.data.links).join('\n')),
+          );
+          break;
+        }
+
+        case 'docs.node': {
+          emitNode(result.data, detail, run);
           break;
         }
       }