@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/api/docs/docs.doc.mjs

@@ -13,20 +13,18 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
   description:
-    '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 ' +
+    '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 ' +
     '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 | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse>',
+    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse>',
   keywords: [
     'docs',
     'documentation',
@@ -48,7 +46,7 @@ export const doc = {
       name: 'section',
       type: 'string',
       description:
-        "Section to return: its key (from the topic's index), its title, or a unique part of its title (case-insensitive).",
+        'Section within the topic to return; matches the first section title that contains this (case-insensitive).',
     },
     {
       name: 'options.lang',
@@ -65,12 +63,6 @@ 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',
@@ -89,15 +81,10 @@ 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:
-        'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [
@@ -107,17 +94,13 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_SECTION',
-      when: 'a section is requested but is empty, matches no section, or matches more than one',
+      when: 'a section is requested but is empty or matches no section title in the topic',
     },
   ],
   examples: [
     {label: 'List topics', code: 'const r = await docs();'},
     {label: 'Load a topic', code: "await docs('principles');"},
-    {
-      label: "A topic's sections",
-      code: "await docs('principles', undefined, {index: true});",
-    },
-    {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
+    {label: 'One section', code: "await docs('tokens', 'spacing');"},
   ],
   command: 'docs',
   related: ['search', 'component', 'hook', 'template'],

package/api/docs/docs.mjs

@@ -3,27 +3,24 @@
 /**
  * @file Programmatic API for the docs command.
  *
- * Dispatcher + barrel. `docs()` routes by argument shape into one of four
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of three
  * leaves, each projecting into a single { type, data } envelope:
  *
- *   docs()                                -> list    -> docs.list
- *   docs(topic)                           -> detail  -> docs.detail
- *   docs(topic, undefined, {index: true}) -> index   -> docs.index
- *   docs(topic, section)                  -> section -> docs.detail.section
+ *   docs()                 -> list    -> docs.list
+ *   docs(topic)            -> detail  -> docs.detail
+ *   docs(topic, section)   -> section -> docs.detail.section
  *
- * 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.
+ * 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.
  */
 
 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, index, detail, sectionLeaf as section};
+export {list, detail, sectionLeaf as section};
 
 /**
  * @param {string} [topic]
@@ -32,12 +29,9 @@ export {list, index, 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
  * >}
@@ -45,6 +39,5 @@ export {list, index, 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,12 +33,6 @@ 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.
 
 /**
- * astryx --json docs
+ * xds --json docs
  */
 export type DocsListResponse = {
     type: "docs.list";
@@ -23,46 +23,14 @@ export type DocsListEntry = {
     replaces?: string | undefined;
 };
 /**
- * astryx --json docs <topic> --index
- */
-export type DocsIndexResponse = {
-    type: "docs.index";
-    data: DocsIndex;
-};
-/**
- * astryx --json docs <topic>
+ * xds --json docs <topic>
  */
 export type DocsDetailResponse = {
     type: "docs.detail";
     data: import("@astryxdesign/cli/authoring").ReferenceDoc;
 };
 /**
- * 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>
+ * xds --json docs <topic> <section>
  */
 export type DocsDetailSectionResponse = {
     type: "docs.detail.section";
@@ -75,11 +43,6 @@ 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,17 +4,16 @@
  * @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
  *   ------------------------------------------------------------
- *   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                     -> docs.list
+ *   xds --json docs <topic>             -> docs.detail
+ *   xds --json docs <topic> <section>   -> docs.detail.section
+ *   (unknown topic/section)             -> CLIError
  */
 
 /**
- * astryx --json docs
+ * xds --json docs
  * @typedef {object} DocsListResponse
  * @property {'docs.list'} type
  * @property {DocsListEntry[]} data
@@ -31,39 +30,14 @@
  */
 
 /**
- * astryx --json docs <topic> --index
- * @typedef {object} DocsIndexResponse
- * @property {'docs.index'} type
- * @property {DocsIndex} data
- */
-
-/**
- * astryx --json docs <topic>
+ * xds --json docs <topic>
  * @typedef {object} DocsDetailResponse
  * @property {'docs.detail'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
  */
 
 /**
- * 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>
+ * xds --json docs <topic> <section>
  * @typedef {object} DocsDetailSectionResponse
  * @property {'docs.detail.section'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceSection} data
@@ -75,8 +49,6 @@
  * @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/integrationDocs.test.mjs

@@ -177,112 +177,6 @@ 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/doctor/doctor.d.mts

@@ -84,36 +84,6 @@ export function checkPeerDeps(ctx: DoctorContext): DoctorCheck;
  * @returns {DoctorCheck}
  */
 export function checkPackageManager(ctx: DoctorContext): DoctorCheck;
-/**
- * Check 6b — every contributing integration owns its provider identity.
- *
- * Artifact and document IDs are provider-scoped, so a package that claims a
- * provider ID an earlier-loaded package already holds is loaded inert: its
- * components, templates, themes, docs, and codemods are withdrawn while the
- * earlier package keeps contributing. That can be a deliberate transition
- * (a renamed package installed beside its predecessor), so it warns rather
- * than fails, but it is never allowed to happen quietly.
- *
- * @param {DoctorContext} ctx
- * @returns {DoctorCheck}
- */
-export function checkProviderIdentity(ctx: DoctorContext): DoctorCheck;
-/**
- * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
- * and fits in one read. The audit is imported here, inside the try, so a
- * malformed self-doc is reported rather than taking Doctor down.
- * @param {DoctorContext} [_ctx]
- * @returns {Promise<DoctorCheck>}
- */
-export function checkAuthoringDocs(_ctx?: DoctorContext): Promise<DoctorCheck>;
-/**
- * Every topic reads progressively, in every language it ships: it loads, its
- * section index and each of its sections fit in one read, and no contributed
- * doc is invalid.
- * @param {DoctorContext | Partial<DoctorContext>} ctx
- * @returns {Promise<DoctorCheck>}
- */
-export function checkDocsProgressiveDisclosure(ctx: DoctorContext | Partial<DoctorContext>): Promise<DoctorCheck>;
 /**
  * Run all diagnostic checks and return a structured report.
  *
@@ -199,27 +169,9 @@ export type DoctorContext = {
      * read at all.
      */
     integrations?: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[] | null | undefined;
-    /**
-     * - The topics a docs read sees.
-     */
-    docsCatalog?: DocsCatalog | null | undefined;
-    /**
-     * `invalid_doc` issues from the project's contributed docs.
-     */
-    docsCatalogIssues?: {
-        package?: string;
-        code: string;
-        message: string;
-    }[] | undefined;
-    /**
-     * - Why the project's docs catalog
-     * could not be built, when it could not.
-     */
-    docsCatalogError?: string | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
      */
     configError?: Error | null | undefined;
 };
-import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';