@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/README.md

@@ -15,6 +15,25 @@ npx @astryxdesign/cli template --list
 
 Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
 
+## Reading the CLI's own docs
+
+The CLI documents itself, so these commands print what the installed version does:
+
+- `astryx <command> --help`: one command's arguments and options.
+- `astryx manifest --json`: every command, option, and response type, as JSON.
+- `astryx docs cli --index`: one section for each command (`commands-<name>`)
+  and each API function, plus the JSON output envelope, error codes, and
+  response types (`api-<name>`). Read one with `astryx docs cli <key>`, for
+  example `astryx docs cli api-search`.
+- `astryx docs authoring --index`: the authoring reference, with one section for
+  each file an author writes: the `astryx.config.*` file, the
+  `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
+  `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
+  `astryx docs authoring <section>`, for example `astryx docs authoring config`.
+- `astryx docs cli-integrations`: the guide to building an integration package.
+- `astryx docs`: every docs topic, including the design-system guides (for
+  example `tokens`, `theme`, and `layout`).
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -170,6 +189,8 @@ if (isError(result)) {
 | `ERR_UNKNOWN_FEATURE`             | An unrecognized `--features` value was passed to init.                                                                                                   |
 | `ERR_UNKNOWN_CODEMOD`             | A `--codemod` value did not match any registered codemod (upgrade).                                                                                      |
 | `ERR_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
+| `ERR_CODEMOD_PROTECTED`           | A required codemod change remains blocked by a protected consumer file.                                                                                  |
+| `ERR_CODEMOD_PROTECTION_SOURCE`   | A working-tree protection declaration could not be read or parsed.                                                                                       |
 | `ERR_NOT_FOUND`                   | A generic discover/lookup query matched nothing in any package.                                                                                          |
 | `ERR_NO_DOC`                      | A component exists but has no typed `.doc.mjs` file.                                                                                                     |
 | `ERR_NO_SHOWCASE`                 | No showcase exists for the requested component.                                                                                                          |
@@ -179,7 +200,7 @@ if (isError(result)) {
 | `ERR_FILE_EXISTS`                 | Refused to overwrite an existing file.                                                                                                                   |
 | `ERR_PATH_TRAVERSAL`              | A path escaped its allowed root, or a name contained traversal markers.                                                                                  |
 | `ERR_WRITE_FAILED`                | Writing output files failed (and was rolled back).                                                                                                       |
-| `ERR_THEME_INVALID`               | A theme definition or contributed theme catalog is invalid.                                                                                              |
+| `ERR_THEME_INVALID`               | A theme definition or contributed theme descriptor is invalid.                                                                                           |
 | `ERR_THEME_LOAD`                  | A theme file could not be loaded / parsed into a defineTheme result.                                                                                     |
 | `ERR_PALETTE_GENERATION`          | A palette generation request or one of its constraints was invalid.                                                                                      |
 | `ERR_VERSION_DETECT`              | The current `@astryxdesign/core` version could not be detected.                                                                                          |

package/api/blog/blog.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'blog',
+  namespace: 'cli/api',
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:

package/api/build/build.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'build',
+  namespace: 'cli/api',
   displayName: 'build()',
   summary:
     'Page-building assistant: the how-to-build playbook, or a composition kit for an idea.',

package/api/component/component.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'component',
+  namespace: 'cli/api',
   displayName: 'component()',
   summary:
     'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',

package/api/discover/discover.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'discover',
+  namespace: 'cli/api',
   displayName: 'discover()',
   summary: 'Browse and search components from configured external packages.',
   description:

package/api/docs/_adapter.d.mts

@@ -15,12 +15,6 @@
  * @returns {Promise<DocsCatalog>}
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
-/**
- * The overlay languages a topic ships for its own file or any extension.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
- */
-export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
 /**
  * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
  * Memoized per catalog, so a read that references a topic twice loads it once.
@@ -76,6 +70,7 @@ export function resolveTopicDocs(topic: string, options?: {
     node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
     lang: string | null;
 }>;
-/** The localized overlays a docs read can apply. */
-export const OVERLAY_LANGUAGES: string[];
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
+import { OVERLAY_LANGUAGES } from '../../foundation/doc-compiler/read.mjs';
+import { overlayLanguages } from '../../foundation/doc-compiler/read.mjs';
+export { OVERLAY_LANGUAGES, overlayLanguages };

package/api/docs/_adapter.mjs

@@ -10,24 +10,29 @@
  * @output Catalog access, the compiler input for a topic, and the compiled
  *   node for it: lowered (overlaid, extensions merged, keys stamped) or linked
  *   (token references resolved too), memoized per catalog.
- * @position Sits beside docs.mjs (api/docs/). Loads authored files and hands
- *   them to foundation/doc-compiler, so no leaf, doctor check or search loads,
- *   merges, or resolves docs on its own. Discovery itself lives in
+ * @position Sits beside docs.mjs (api/docs/). Hands topics to
+ *   foundation/doc-compiler (which loads their files) and memoizes the nodes
+ *   per catalog, so no leaf, doctor check or search loads, merges, or resolves
+ *   docs on its own. Discovery itself lives in
  *   foundation/discovery/docs-discovery, which the catalog comes from.
  */
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   linkReferenceTopic,
   lowerReferenceTopic,
 } from '../../foundation/doc-compiler/compile.mjs';
+import {
+  deepFreeze,
+  loadTopicInput,
+  OVERLAY_LANGUAGES,
+  overlayLanguages,
+} from '../../foundation/doc-compiler/read.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
-import {parseDoc} from '../../authoring/doctypes/parse.mjs';
+
+export {OVERLAY_LANGUAGES, overlayLanguages};
 
 /**
  * The project's topics: the built-in ones plus whatever the configured
@@ -51,34 +56,6 @@ export async function loadDocsCatalog(cwd = process.cwd()) {
   }
 }
 
-/** The localized overlays a docs read can apply. */
-export const OVERLAY_LANGUAGES = ['zh', 'dense'];
-
-/**
- * Where the `lang` overlay of a doc file lives: `{topic}.doc.{lang}.mjs`.
- * @param {string} docPath
- * @param {string} lang
- * @returns {string}
- */
-function overlayPath(docPath, lang) {
-  return path.join(
-    path.dirname(docPath),
-    `${path.basename(docPath, '.doc.mjs')}.doc.${lang}.mjs`,
-  );
-}
-
-/**
- * The overlay languages a topic ships for its own file or any extension.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
- */
-export function overlayLanguages(entry) {
-  const files = [entry.path, ...entry.extensions.map(ext => ext.path)];
-  return OVERLAY_LANGUAGES.filter(lang =>
-    files.some(file => fs.existsSync(overlayPath(file, lang))),
-  );
-}
-
 /**
  * The overlay a read applies: none for the authored language.
  * @param {string | null | undefined} lang
@@ -88,61 +65,6 @@ function overlayLanguage(lang) {
   return lang && lang !== 'en' ? lang : null;
 }
 
-/**
- * Load one authored file and the overlay for `lang`. A failure is recorded on
- * the result, not thrown, so the compiler reports it in reading order.
- * @param {string} docPath
- * @param {string | null} lang
- * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').AuthoredFile>}
- */
-async function loadAuthoredFile(docPath, lang) {
-  const file = path.basename(docPath);
-  let doc;
-  try {
-    const mod = await import(pathToFileURL(docPath).href);
-    doc = parseDoc(mod.docs ?? mod.default, file);
-  } catch (error) {
-    return {file, error};
-  }
-  if (!lang) return {file, doc};
-  const translationPath = overlayPath(docPath, lang);
-  if (!fs.existsSync(translationPath)) return {file, doc};
-  try {
-    const translationMod = await import(pathToFileURL(translationPath).href);
-    return {
-      file,
-      doc,
-      overlay: translationMod.docsZh || translationMod.docsDense || null,
-    };
-  } catch (overlayError) {
-    return {file, doc, overlayError};
-  }
-}
-
-/**
- * Everything the compiler needs for one topic, read from disk.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {string | null} lang
- * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').ReferenceTopicInput>}
- */
-async function loadCompilerInput(entry, lang) {
-  const extensions = [];
-  for (const extension of entry.extensions) {
-    extensions.push({
-      ...(await loadAuthoredFile(extension.path, lang)),
-      provider: extension.package,
-    });
-  }
-  return {
-    id: entry.name,
-    provider: entry.package,
-    replaces: entry.replaces ?? null,
-    lang,
-    base: await loadAuthoredFile(entry.path, lang),
-    extensions,
-  };
-}
-
 /** @type {WeakMap<DocsCatalog, Map<string, Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>>>} */
 const loweredByCatalog = new WeakMap();
 
@@ -166,7 +88,7 @@ export function lowerTopic(catalog, entry, lang = null) {
   const key = `${entry.name.toLowerCase()}\u0000${overlay ?? ''}`;
   let lowered = cache.get(key);
   if (!lowered) {
-    lowered = loadCompilerInput(entry, overlay).then(input =>
+    lowered = loadTopicInput(entry, overlay).then(input =>
       deepFreeze(lowerReferenceTopic(input)),
     );
     cache.set(key, lowered);
@@ -174,20 +96,6 @@ export function lowerTopic(catalog, entry, lang = null) {
   return lowered;
 }
 
-/**
- * Freeze a value and everything in it.
- * @template T
- * @param {T} value
- * @returns {T}
- */
-function deepFreeze(value) {
-  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
-    Object.freeze(value);
-    for (const child of Object.values(value)) deepFreeze(child);
-  }
-  return value;
-}
-
 /**
  * How a token reference finds its target: the topic it names in `catalog`,
  * lowered for the same language.

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

@@ -4,9 +4,9 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   the topic via the shared adapter, finds the section in its lowered compiled
- *   node by its stable key, then by exact title, then by a title that contains
- *   the query, and links only that section.
+ *   the topic via the shared adapter, keeps the 0.6.x first title-substring
+ *   match, then falls back to a stable key or normalized title key, and links
+ *   only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
@@ -17,10 +17,7 @@
 
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {
-  findDocSection,
-  sectionKey,
-} from '../../../../foundation/discovery/docs-section-key.mjs';
+import {findDocSection} from '../../../../foundation/discovery/docs-section-key.mjs';
 import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
 import {
   readerSections,
@@ -52,16 +49,13 @@ export async function section(topic, sectionName, options = {}) {
 
   const {catalog, node, lang} = await resolveTopicDocs(topic, options);
   const sections = readerSections(node);
-  const {section: match, candidates} = findDocSection(sections, sectionName);
+  const {section: match} = findDocSection(sections, sectionName);
   if (!match) {
-    const ambiguous = candidates.length > 1;
     throw new AstryxError(
-      ambiguous
-        ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
-        : `Section "${sectionName}" not found in "${topic}"`,
-      (ambiguous ? candidates : sections).map(s => ({
-        name: sectionKey(s),
-        reason: s.title,
+      `Section "${sectionName}" not found in "${topic}"`,
+      sections.map(s => ({
+        name: s.title,
+        reason: 'available section',
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );

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

@@ -30,6 +30,17 @@ describe('docs.detail.section leaf', () => {
     }
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.suggestions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: expect.any(String),
+          reason: 'available section',
+        }),
+      ]),
+    );
+    expect(err.suggestions.some(suggestion => /\s/u.test(suggestion.name))).toBe(
+      true,
+    );
   }, SLOW);
 
   it('does not return the first section for an empty section name', async () => {
@@ -50,12 +61,10 @@ describe('docs.detail.section leaf', () => {
     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);
+  it('keeps a previously accepted ambiguous query on its first match', async () => {
+    const res = await section('theme', 'e');
+    expect(res.type).toBe('docs.detail.section');
+    expect(res.data).toBeDefined();
   }, SLOW);
 
   it.each([null, 'zh', 'dense'])(

package/api/docs/docs.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'docs',
+  namespace: 'cli/api',
   displayName: 'docs()',
   summary:
     'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',

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 = {

package/api/doctor/doctor.d.mts

@@ -100,12 +100,34 @@ export function checkPackageManager(ctx: DoctorContext): 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.
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
  * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
  * @returns {Promise<DoctorCheck>}
  */
-export function checkAuthoringDocs(_ctx?: DoctorContext): Promise<DoctorCheck>;
+export function checkAuthoringDocs(_ctx?: DoctorContext, options?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<DoctorCheck>;
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkCliDocs(_ctx: DoctorContext | Partial<DoctorContext>, options?: {
+    root?: string;
+    sources?: string[];
+    authoringSources?: string[];
+}): 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

package/api/doctor/doctor.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'doctor',
+  namespace: 'cli/api',
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description: