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

package/api/docs/detail/section/section.test.mjs

@@ -10,6 +10,7 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
+import {loadDocsCatalog, lowerTopic} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -39,4 +40,44 @@ describe('docs.detail.section leaf', () => {
       code: 'ERR_UNKNOWN_SECTION',
     });
   }, SLOW);
+
+  it('reads a section by its stable key', async () => {
+    const catalog = await loadDocsCatalog();
+    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
+    const target = doc.sections[doc.sections.length - 1];
+    const res = await section('theme', target.id);
+    expect(res.data.title).toBe(target.title);
+    expect(res.data.id).toBe(target.id);
+  }, SLOW);
+
+  it('refuses a query that matches more than one section', async () => {
+    const err = await section('theme', 'e').catch(e => e);
+    expect(err).toBeInstanceOf(AstryxError);
+    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.message).toMatch(/matches \d+ sections/);
+    expect(err.suggestions.length).toBeGreaterThan(1);
+  }, SLOW);
+
+  it.each([null, 'zh', 'dense'])(
+    'inlines token refs when a section is read on its own (lang %s)',
+    async lang => {
+      const catalog = await loadDocsCatalog();
+      let checked = 0;
+      for (const entry of catalog.entries()) {
+        const {doc} = await lowerTopic(catalog, entry);
+        for (const own of doc.sections) {
+          if (!own.content.some(block => block.type === 'token-ref')) continue;
+          const res = await section(entry.name, own.id, lang ? {lang} : {});
+          expect(res.data.content.length).toBeGreaterThan(0);
+          expect(res.data.content.some(block => block.type === 'token-ref')).toBe(
+            false,
+          );
+          expect(JSON.stringify(res.data.content)).not.toContain('[token-ref:');
+          checked += 1;
+        }
+      }
+      expect(checked).toBeGreaterThan(0);
+    },
+    SLOW,
+  );
 });

package/api/docs/docs.d.mts

@@ -8,9 +8,12 @@
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ *   the whole doc
  * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
+ *   import('./docs.type.mjs').DocsIndexResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
  *   import('./docs.type.mjs').DocsDetailSectionResponse
  * >}
@@ -19,9 +22,11 @@ export function docs(topic?: string, section?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    index?: boolean | undefined;
     cwd?: string | undefined;
-}): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
+}): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsIndexResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
 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';
-export { list, detail, sectionLeaf as section };
+export { list, index, detail, sectionLeaf as section };

package/api/docs/docs.doc.mjs

@@ -11,20 +11,23 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'docs',
+  namespace: 'cli/api',
   displayName: 'docs()',
   summary:
-    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
   description:
-    'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
-    'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
-    'plus a section returns the first section whose title contains the ' +
-    '(case-insensitive) query. The topic set is the CLI\'s own docs plus the ' +
+    'No topic lists every reference-doc topic; a topic returns that full ' +
+    'ReferenceDoc; `index: true` returns the topic\'s section index instead ' +
+    '(each section\'s key, title, and summary); a topic plus a section returns ' +
+    'that one section, found by its key, then its exact title, then a unique ' +
+    'part of its title (an ambiguous query is refused). Token-ref blocks are ' +
+    'inlined in every read. The topic set is the CLI\'s own docs plus the ' +
     'ones the project\'s configured integrations contribute, including any ' +
     'topic an integration replaces or extends, so it depends on the cwd. ' +
     'Overlay options select localized or dense variants.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse>',
+    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse>',
   keywords: [
     'docs',
     'documentation',
@@ -46,7 +49,7 @@ export const doc = {
       name: 'section',
       type: 'string',
       description:
-        'Section within the topic to return; matches the first section title that contains this (case-insensitive).',
+        "Section to return: its key (from the topic's index), its title, or a unique part of its title (case-insensitive).",
     },
     {
       name: 'options.lang',
@@ -63,6 +66,12 @@ export const doc = {
       type: 'boolean',
       description: 'Return the token-efficient dense doc variant.',
     },
+    {
+      name: 'options.index',
+      type: 'boolean',
+      description:
+        "Return the topic's section index (each section's key, title, and summary) instead of the whole doc.",
+    },
     {
       name: 'options.cwd',
       type: 'string',
@@ -81,10 +90,15 @@ export const doc = {
       description:
         "One topic's full ReferenceDoc, with token-ref blocks inlined.",
     },
+    {
+      type: 'docs.index',
+      description:
+        "One topic's section index (index: true): {name, title, description, sections: [{id, title, summary}]}.",
+    },
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic: the first whose title contains the section query.',
+        'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',
     },
   ],
   throws: [
@@ -94,13 +108,17 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_SECTION',
-      when: 'a section is requested but is empty or matches no section title in the topic',
+      when: 'a section is requested but is empty, matches no section, or matches more than one',
     },
   ],
   examples: [
     {label: 'List topics', code: 'const r = await docs();'},
     {label: 'Load a topic', code: "await docs('principles');"},
-    {label: 'One section', code: "await docs('tokens', 'spacing');"},
+    {
+      label: "A topic's sections",
+      code: "await docs('principles', undefined, {index: true});",
+    },
+    {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
   ],
   command: 'docs',
   related: ['search', 'component', 'hook', 'template'],

package/api/docs/docs.mjs

@@ -3,24 +3,27 @@
 /**
  * @file Programmatic API for the docs command.
  *
- * Dispatcher + barrel. `docs()` routes by argument shape into one of three
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of four
  * leaves, each projecting into a single { type, data } envelope:
  *
- *   docs()                 -> list    -> docs.list
- *   docs(topic)            -> detail  -> docs.detail
- *   docs(topic, section)   -> section -> docs.detail.section
+ *   docs()                                -> list    -> docs.list
+ *   docs(topic)                           -> detail  -> docs.detail
+ *   docs(topic, undefined, {index: true}) -> index   -> docs.index
+ *   docs(topic, section)                  -> section -> docs.detail.section
  *
- * The leaves live in list/, detail/, and detail/section/; the discovery,
- * overlay loading, and topic resolution they share sit in _adapter.mjs. This
- * module keeps the same `docs` export (and re-exports the leaves) so
- * api/index.mjs and the CLI consumer import from here unchanged.
+ * A topic read returns the whole doc, as it always has. The index is how a
+ * reader works progressively instead: list the topic's sections, then read one
+ * by its key. The leaves live in list/, index/, detail/, and detail/section/;
+ * the discovery, overlay loading, and topic resolution they share sit in
+ * _adapter.mjs.
  */
 
 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';
 
-export {list, detail, sectionLeaf as section};
+export {list, index, detail, sectionLeaf as section};
 
 /**
  * @param {string} [topic]
@@ -29,9 +32,12 @@ export {list, detail, sectionLeaf as section};
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ *   the whole doc
  * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
+ *   import('./docs.type.mjs').DocsIndexResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
  *   import('./docs.type.mjs').DocsDetailSectionResponse
  * >}
@@ -39,5 +45,6 @@ export {list, detail, sectionLeaf as section};
 export async function docs(topic, section, options = {}) {
   if (!topic) return list(options);
   if (section) return sectionLeaf(topic, section, options);
+  if (options.index) return index(topic, options);
   return detail(topic, options);
 }

package/api/docs/docs.test.mjs

@@ -33,6 +33,12 @@ describe('docs() dispatcher routing', () => {
     expect(r.type).toBe('docs.detail');
   }, SLOW);
 
+  it('topic + index -> docs.index', async () => {
+    const {data} = await docs();
+    const r = await docs(data[0].topic, undefined, {index: true});
+    expect(r.type).toBe('docs.index');
+  }, SLOW);
+
   it('topic + section -> docs.detail.section', async () => {
     const {data} = await docs();
     let routed = null;

package/api/docs/docs.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json docs
+ * astryx --json docs
  */
 export type DocsListResponse = {
     type: "docs.list";
@@ -23,14 +23,46 @@ export type DocsListEntry = {
     replaces?: string | undefined;
 };
 /**
- * xds --json docs <topic>
+ * astryx --json docs <topic> --index
+ */
+export type DocsIndexResponse = {
+    type: "docs.index";
+    data: DocsIndex;
+};
+/**
+ * astryx --json docs <topic>
  */
 export type DocsDetailResponse = {
     type: "docs.detail";
     data: import("@astryxdesign/cli/authoring").ReferenceDoc;
 };
 /**
- * xds --json docs <topic> <section>
+ * The section index of one topic: what the topic is, and the key each section
+ * is read by.
+ */
+export type DocsIndex = {
+    /**
+     * the topic
+     */
+    name: string;
+    title: string;
+    description: string;
+    sections: DocsIndexSection[];
+};
+export type DocsIndexSection = {
+    /**
+     * stable key; pass it as the section argument
+     */
+    id: string;
+    title: string;
+    /**
+     * the section's first line of text, at most 240
+     * characters
+     */
+    summary: string;
+};
+/**
+ * astryx --json docs <topic> <section>
  */
 export type DocsDetailSectionResponse = {
     type: "docs.detail.section";
@@ -43,6 +75,11 @@ export type DocsOptions = {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    /**
+     * return a topic's section index instead of its
+     * whole doc
+     */
+    index?: boolean | undefined;
     /**
      * project directory whose configured integrations
      * contribute topics; defaults to process.cwd()

package/api/docs/docs.type.mjs

@@ -4,16 +4,17 @@
  * @file Colocated types for the `docs` command — source of truth for the docs
  *   command JSON responses. `types/docs.d.ts` re-exports these.
  *
- *   Invocation                          -> type discriminator
+ *   Invocation                           -> type discriminator
  *   ------------------------------------------------------------
- *   xds --json docs                     -> docs.list
- *   xds --json docs <topic>             -> docs.detail
- *   xds --json docs <topic> <section>   -> docs.detail.section
- *   (unknown topic/section)             -> CLIError
+ *   astryx --json docs                   -> docs.list
+ *   astryx --json docs <topic>           -> docs.detail
+ *   astryx --json docs <topic> --index   -> docs.index
+ *   astryx --json docs <topic> <section> -> docs.detail.section
+ *   (unknown topic/section)              -> CLIError
  */
 
 /**
- * xds --json docs
+ * astryx --json docs
  * @typedef {object} DocsListResponse
  * @property {'docs.list'} type
  * @property {DocsListEntry[]} data
@@ -30,14 +31,39 @@
  */
 
 /**
- * xds --json docs <topic>
+ * astryx --json docs <topic> --index
+ * @typedef {object} DocsIndexResponse
+ * @property {'docs.index'} type
+ * @property {DocsIndex} data
+ */
+
+/**
+ * astryx --json docs <topic>
  * @typedef {object} DocsDetailResponse
  * @property {'docs.detail'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
  */
 
 /**
- * xds --json docs <topic> <section>
+ * The section index of one topic: what the topic is, and the key each section
+ * is read by.
+ * @typedef {object} DocsIndex
+ * @property {string} name the topic
+ * @property {string} title
+ * @property {string} description
+ * @property {DocsIndexSection[]} sections
+ */
+
+/**
+ * @typedef {object} DocsIndexSection
+ * @property {string} id stable key; pass it as the section argument
+ * @property {string} title
+ * @property {string} summary the section's first line of text, at most 240
+ *   characters
+ */
+
+/**
+ * astryx --json docs <topic> <section>
  * @typedef {object} DocsDetailSectionResponse
  * @property {'docs.detail.section'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceSection} data
@@ -49,6 +75,8 @@
  * @property {string} [lang]
  * @property {boolean} [zh]
  * @property {boolean} [dense]
+ * @property {boolean} [index] return a topic's section index instead of its
+ *   whole doc
  * @property {string} [cwd] project directory whose configured integrations
  *   contribute topics; defaults to process.cwd()
  */

package/api/docs/index/index.d.mts

@@ -0,0 +1,18 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
+ */
+export function index(topic: string, options?: {
+    lang?: string | undefined;
+    zh?: boolean | undefined;
+    dense?: boolean | undefined;
+    cwd?: string | undefined;
+}): Promise<import("../docs.type.mjs").DocsIndexResponse>;

package/api/docs/index/index.mjs

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.index leaf — the section index of one topic.
+ *
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and reads its lowered compiled node; nothing is
+ *   linked, since the index never inlines a token reference.
+ * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
+ *   description and, for each section, the key it is read by, its title, and a
+ *   one-line summary. Matches `astryx --json docs <topic> --index`.
+ * @position Leaf under api/docs: a topic's opt-in progressive read. One section
+ *   is the section leaf (`docs <topic> <key>`); the whole topic, a plain topic
+ *   read, is the detail leaf.
+ */
+
+import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
+import {resolveTopicDocs} from '../_adapter.mjs';
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
+ */
+export async function index(topic, options = {}) {
+  const {node} = await resolveTopicDocs(topic, options);
+  return {type: 'docs.index', data: indexView(node)};
+}

package/api/docs/index/index.test.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {docs} from '../docs.mjs';
+import {index} from './index.mjs';
+import {loadDocsCatalog} from '../_adapter.mjs';
+
+const SLOW = 60_000;
+
+describe('docs.index leaf', () => {
+  it('lists each section by key, title, and summary', async () => {
+    const res = await index('theme');
+    expect(res.type).toBe('docs.index');
+    expect(res.data).toMatchObject({name: 'theme', title: expect.any(String)});
+    const keys = res.data.sections.map(s => s.id);
+    expect(new Set(keys).size).toBe(keys.length);
+    for (const entry of res.data.sections) {
+      expect(Object.keys(entry)).toEqual(['id', 'title', 'summary']);
+      expect(entry.summary.length).toBeLessThanOrEqual(240);
+    }
+  }, SLOW);
+
+  it('names the sections the full topic has, with the same keys', async () => {
+    const full = await docs('theme');
+    const {data} = await index('theme');
+    expect(data.sections.map(s => [s.id, s.title])).toEqual(
+      full.data.sections.map(s => [s.id, s.title]),
+    );
+  }, SLOW);
+
+  it('keeps every key the same in every language', async () => {
+    const english = (await index('theme')).data.sections.map(s => s.id);
+    for (const lang of ['zh', 'dense']) {
+      const localized = await index('theme', {lang});
+      expect(localized.data.sections.map(s => s.id)).toEqual(english);
+    }
+  }, SLOW);
+
+  it('lists keys every section can be read by', async () => {
+    const catalog = await loadDocsCatalog();
+    for (const entry of catalog.entries()) {
+      const {data} = await index(entry.name);
+      for (const {id, title} of data.sections) {
+        const read = await docs(entry.name, id);
+        expect(read.data.title).toBe(title);
+      }
+    }
+  }, SLOW);
+});
+
+describe('docs() topic reads', () => {
+  it('returns the whole topic by default, as before', async () => {
+    const res = await docs('theme');
+    expect(res.type).toBe('docs.detail');
+    expect(res.data.sections[0].content.length).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('returns the section index on request', async () => {
+    const res = await docs('theme', undefined, {index: true});
+    expect(res.type).toBe('docs.index');
+  }, SLOW);
+});

package/api/docs/integrationDocs.test.mjs

@@ -177,6 +177,112 @@ describe('integration-contributed topics', () => {
     expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
   }, SLOW);
 
+  it('migrates a real built-in section to a stable ID without duplicating it', async () => {
+    const builtin = await docs('theme');
+    // Readers see a key on every section; the migration case is one whose
+    // source authors no id.
+    const {docs: authored} = await import('../../assets/docs/theme.doc.mjs');
+    const target = authored.sections.find(section => section.id == null);
+    expect(target).toBeDefined();
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {
+            id: 'acme-theme-setup',
+            title: target.title,
+            content: [{type: 'prose', text: 'Use the Acme theme.'}],
+          },
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir});
+    expect(extended.data.sections).toHaveLength(builtin.data.sections.length);
+    const matches = extended.data.sections.filter(
+      section => section.title === target.title,
+    );
+    expect(matches).toEqual([
+      expect.objectContaining({
+        id: 'acme-theme-setup',
+        content: [{type: 'prose', text: 'Use the Acme theme.'}],
+      }),
+    ]);
+  }, SLOW);
+
+  it('replaces a real built-in section by the key its index shows', async () => {
+    const index = await docs('theme', undefined, {index: true});
+    const target = index.data.sections[0];
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {
+            id: target.id,
+            title: `${target.title} with Acme`,
+            content: [{type: 'prose', text: 'Acme first.'}],
+          },
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir});
+    expect(extended.data.sections).toHaveLength(index.data.sections.length);
+    expect(extended.data.sections.filter(s => s.id === target.id)).toEqual([
+      expect.objectContaining({content: [{type: 'prose', text: 'Acme first.'}]}),
+    ]);
+    const read = await docs('theme', target.id, {cwd: tmpDir});
+    expect(read.data.title).toBe(`${target.title} with Acme`);
+  }, SLOW);
+
+  it.each(['zh', 'dense'])(
+    'replaces translated real sections by their authored titles under --%s',
+    async lang => {
+      const english = await docs('theme');
+      const englishTitles = english.data.sections.map(section => section.title);
+      expect(englishTitles).toEqual(
+        expect.arrayContaining(['Quick Start', 'Theme Props']),
+      );
+      scaffold({
+        'theme-internal.doc.mjs': topic({
+          name: 'theme-internal',
+          extends: 'theme',
+          sections: [
+            {
+              id: 'acme-quick-start',
+              title: 'Quick Start',
+              content: [{type: 'prose', text: 'Acme quick start.'}],
+            },
+            {
+              title: 'Theme Props',
+              content: [{type: 'prose', text: 'Acme props.'}],
+            },
+          ],
+        }),
+      });
+
+      const base = await docs('theme', undefined, {lang});
+      expect(base.data.sections.map(section => section.title)).not.toEqual(
+        englishTitles,
+      );
+      const extended = await docs('theme', undefined, {cwd: tmpDir, lang});
+      expect(extended.data.sections).toHaveLength(base.data.sections.length);
+      expect(
+        extended.data.sections.filter(
+          section => section.id === 'acme-quick-start',
+        ),
+      ).toHaveLength(1);
+      expect(
+        extended.data.sections.filter(
+          section => section.content[0]?.text === 'Acme props.',
+        ),
+      ).toHaveLength(1);
+    },
+    SLOW,
+  );
+
   it('offers the contributed topics as suggestions on an unknown one', async () => {
     scaffold({'deploying.doc.mjs': topic()});
     await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir})).rejects.toBeInstanceOf(

package/api/docs/list/list.mjs

@@ -14,7 +14,7 @@
  * @position Leaf under api/docs. Sibling of detail; both share _adapter.mjs.
  */
 
-import {pathToFileURL} from 'node:url';
+import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
 import {loadDocsCatalog} from '../_adapter.mjs';
 
 /**
@@ -29,12 +29,8 @@ export async function list({cwd} = {}) {
   for (const entry of catalog.entries()) {
     let description = entry.description ?? '';
     if (entry.description == null) {
-      try {
-        const mod = await import(pathToFileURL(entry.path).href);
-        description = (mod.docs ?? mod.default)?.description ?? '';
-      } catch {
-        description = '';
-      }
+      const file = await loadTopicFile(entry.path, null);
+      description = file.doc?.description ?? '';
     }
     /** @type {import('../docs.type.mjs').DocsListEntry} */
     const listed = {