@astryxdesign/cli 0.6.3-canary.4fb81b0 → 0.6.3-canary.5937ac3

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,
@@ -179,7 +198,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).',
@@ -109,7 +110,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integrations; brief entries; or full ComponentDoc entries.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
     },
     {
       type: 'component.detail',

package/api/component/component.type.d.mts

@@ -31,9 +31,10 @@ export type ComponentListData = ({
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  */
 export type ComponentListEntry = {
     name: string;
@@ -42,7 +43,7 @@ export type ComponentListEntry = {
      */
     package: string;
     /**
-     * - Import specifier; present for integration components, absent for core.
+     * - Import specifier; present for integration and legacy package components, absent for core.
      */
     import?: string | undefined;
 };

package/api/component/component.type.mjs

@@ -52,13 +52,14 @@
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  * @typedef {object} ComponentListEntry
  * @property {string} name
  * @property {string} package - Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'.
- * @property {string} [import] - Import specifier; present for integration components, absent for core.
+ * @property {string} [import] - Import specifier; present for integration and legacy package components, absent for core.
  */
 
 /**

package/api/component/list/list.d.mts

@@ -1,11 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
- * @typedef {import('../component.type.mjs').ComponentListEntry} ComponentListEntry
- * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
- */
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in

package/api/component/list/list.mjs

@@ -17,13 +17,14 @@ import {
   discoverExternalComponentsGrouped,
   discoverIntegrationComponents,
   findComponentReadme,
+  findExternalComponentDoc,
   resolveImportPath,
   resolveIntegrationImportPath,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
-import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
+import {loadComponentDoc, loadIntegrationsSafely, withOwnership} from '../_adapter.mjs';
 
 /**
  * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
@@ -31,6 +32,29 @@ import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
  * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
  */
 
+/**
+ * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
+ * same way (`withOwnership`) so list and detail agree.
+ * @param {{name: string, docsDir: string}} ext
+ * @param {string} name
+ * @param {string} coreDir
+ * @param {{zh: boolean, lang: string|null}} docOpts
+ * @returns {Promise<string>}
+ */
+async function legacyImport(ext, name, coreDir, docOpts) {
+  const docPath = findExternalComponentDoc(ext.docsDir, name);
+  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
+  let docs = {};
+  if (docPath && docPath.endsWith('.doc.mjs')) {
+    try {
+      docs = await loadComponentDoc(docPath, docOpts);
+    } catch {
+      // Keep list resilient; validation owns malformed docs.
+    }
+  }
+  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
+}
+
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in
@@ -267,20 +291,24 @@ export async function componentList(
       k => grouped[k].length > 1 || grouped[k][0] !== k,
     );
 
-    if (hasGroups) {
-      for (const [group, members] of Object.entries(grouped)) {
-        listData[`${group} (${ext.name})`] = members.map(n => ({
+    /** @param {string[]} names */
+    const entriesFor = names =>
+      Promise.all(
+        names.map(async n => ({
           name: n,
           package: ext.name,
-        }));
+          import: await legacyImport(ext, n, coreDir, {zh, lang}),
+        })),
+      );
+
+    if (hasGroups) {
+      for (const [group, members] of Object.entries(grouped)) {
+        listData[`${group} (${ext.name})`] = await entriesFor(members);
       }
     } else {
       const allComps = Object.values(grouped).flat().sort();
       if (allComps.length > 0) {
-        listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-          name: n,
-          package: ext.name,
-        }));
+        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
       }
     }
   }

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/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: