@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/foundation/discovery/component-loader.mjs

@@ -1,245 +1,76 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Component doc loader — load and merge translations
- */
-
-import {pathToFileURL} from 'node:url';
-import {importUserModule} from '../fs/module-loader.mjs';
-import {parseDoc} from '../../authoring/doctypes/parse.mjs';
-
-/**
- * Load a component doc through the shared load/validation boundary.
- *
- * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
- * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates via
- * `parseDoc`, which accepts BOTH formats, so this loader reads whichever the
- * file uses:
- *   - NEW: a stamped default export (`export default {type: 'component', ...}`
- *     / `'function'` / `'generic'`) — the same single-export convention the
- *     other authoring parsers use for config/integration/template. These carry
- *     a stamped `type` and validate against the matching per-kind parser.
- *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
- *     against the permissive legacy union.
- * The default export wins when both are present. Throws a readable
- * `formatZodError`-style message on failure. Translations (`docsZh`/
- * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
- * identical output.
+ * @file Component and hook doc loader.
  *
- * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
- * @returns {Promise<object>} the validated (and optionally translated) doc
+ * @input A component or hook `.doc.{ts,mjs,js}` path and the reading language
+ *   (`lang`, or the legacy `zh`/`dense` flags).
+ * @output The module's own doc, with its translation laid over it for `lang`.
+ * @position The loaders every component and hook reader calls. Both read
+ *   through the doc compiler (foundation/doc-compiler/read.mjs), which lowers
+ *   the doc on every read. The two differ only in how strict they are:
+ *   {@link loadComponentDoc} reports a doc that fails its kind's parser, and
+ *   {@link loadDocs}, which has never checked docs, still reads one.
  */
-export async function loadComponentDoc(
-  docPath,
-  {zh = false, dense = false, lang} = {},
-) {
-  const mod = await importUserModule(docPath);
-  /** @type {any} */
-  const authored = mod?.default ?? mod?.docs;
-
-  parseDoc(authored, docPath);
-  const docs = authored;
 
-  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
-  if (!locale) return docs;
+import {readDocView} from '../doc-compiler/read.mjs';
 
-  const translationKey =
-    locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
-  if (!translationKey || !mod[translationKey]) return docs;
-
-  /** @type {any} */
-  const translation = mod[translationKey];
-  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
-    return overlayComponentDoc(docs, translation);
-  }
-  return mergeTranslation(docs, translation);
-}
+export {mergeTranslation} from '../doc-compiler/overlays.mjs';
 
 /**
- * @param {any} docs
- * @param {any} translation
- * @returns {any}
+ * @typedef {object} LoadDocOptions
+ * @property {boolean} [zh] legacy flag for `lang: 'zh'`
+ * @property {boolean} [dense] legacy flag for `lang: 'dense'`
+ * @property {string | null} [lang] wins over the legacy flags
+ * @property {'components' | 'hooks'} [root] which root reads the doc
+ *   (default: components)
  */
-export function mergeTranslation(docs, translation) {
-  if (!translation) return docs;
-
-  /** @type {any} */
-  const merged = {...docs};
-
-  // Merge prose into usage
-  if (merged.usage) {
-    merged.usage = {...merged.usage};
-    if (translation.usage?.description) merged.usage.description = translation.usage.description;
-    else if (translation.description) merged.usage.description = translation.description;
-    if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
-    if (translation.usage?.accessibility) merged.usage.accessibility = translation.usage.accessibility;
-  }
-
-  // Legacy top-level fields (for docsZh that are full ComponentDoc clones)
-  if (translation.description && !merged.usage) merged.description = translation.description;
-
-  // Merge prop descriptions for single-component docs
-  if (translation.propDescriptions && merged.props) {
-    merged.props = merged.props.map((/** @type {any} */ prop) => {
-      const desc = translation.propDescriptions[prop.name];
-      return desc != null ? {...prop, description: desc} : prop;
-    });
-  }
-
-  // Merge hook param descriptions (HookTranslationDoc). Params are an array of
-  // {name, type, description, required}; override description by name where the
-  // translation has an entry. Names may include dots (e.g. 'options.isActive');
-  // the lookup is keyed by the exact param name.
-  if (translation.paramDescriptions && merged.params) {
-    merged.params = merged.params.map((/** @type {any} */ param) => {
-      const desc = translation.paramDescriptions[param.name];
-      return desc != null ? {...param, description: desc} : param;
-    });
-  }
-
-  // Merge hook return descriptions (HookTranslationDoc). Returns are an array
-  // of {name, type, description}; override description by name where present.
-  if (translation.returnDescriptions && merged.returns) {
-    merged.returns = merged.returns.map((/** @type {any} */ ret) => {
-      const desc = translation.returnDescriptions[ret.name];
-      return desc != null ? {...ret, description: desc} : ret;
-    });
-  }
-
-  // Merge sub-component translations
-  if (translation.components && merged.components) {
-    merged.components = merged.components.map((/** @type {any} */ comp, /** @type {any} */ i) => {
-      const trans = translation.components.find((/** @type {any} */ t) => t.name === comp.name)
-        || translation.components[i];
-      if (!trans) return comp;
-
-      const mergedComp = {...comp};
-      if (trans.description) mergedComp.description = trans.description;
-      if (trans.propDescriptions && comp.props) {
-        mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
-          const desc = trans.propDescriptions[prop.name];
-          return desc != null ? {...prop, description: desc} : prop;
-        });
-      }
-      return mergedComp;
-    });
-  }
-
-  return merged;
-}
 
 /**
- * Load the typed docs object from a .doc.mjs file.
- * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
- * Also supports legacy --zh and --dense flags.
- * Translations are merged onto the base docs, keeping structure intact.
- * @param {string} readmePath
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
- * @returns {Promise<any>}
+ * The overlay a read applies: `lang`, else the legacy flags.
+ * @param {LoadDocOptions} opts
+ * @returns {string | null}
  */
-export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
-  const mod = await import(pathToFileURL(readmePath).href);
-  // Support both the new stamped default export (`export default {type: 'component', …}`)
-  // and the legacy named export (`export const docs = {…}`). Default wins when both
-  // are present, matching loadComponentDoc's precedence.
-  const docs = mod?.default ?? mod.docs;
-
-  // Resolve which translation to use (--lang takes priority over legacy flags)
-  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
-  if (!locale) return docs;
-
-  const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
-  if (!translationKey || !mod[translationKey]) return docs;
-
-  const translation = mod[translationKey];
-
-  // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
-  // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
-  // the translation had not caught up with simply ceased to exist —
-  // `component Button --zh` silently omitted `isInterruptible` and
-  // `isIconOnly`. A reader of the translated docs cannot discover a prop that
-  // is not there. Overlay it instead, so an untranslated prop falls back to
-  // its English entry. (Same principle as the reference-doc overlays, #2182.)
-  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
-    return overlayComponentDoc(docs, translation);
-  }
-
-  // Otherwise it's a ComponentTranslationDoc — merge it onto docs
-  return mergeTranslation(docs, translation);
+function localeOf({zh = false, dense = false, lang} = {}) {
+  return lang || (dense ? 'dense' : zh ? 'zh' : null);
 }
 
 /**
- * Overlay a full-ComponentDoc-shaped translation onto the English doc.
+ * Load a component or hook doc and check it against its kind's parser.
  *
- * Base order and completeness win; the translation supplies text for the
- * entries it covers. Props are matched by name, never by position, so a
- * translation that is missing entries (or lists them in another order) can no
- * longer drop or misattribute one.
+ * Reads `.doc.ts` through jiti and `.doc.mjs`/`.doc.js` natively. Both formats
+ * load: a stamped default export (`export default {type: 'component', ...}`)
+ * checked against its kind, and the legacy `export const docs = {...}` checked
+ * against the permissive legacy union. The default export wins when both are
+ * present. Throws the parser's readable message when the doc fails.
  *
- * @param {any} docs Base (English) component doc.
- * @param {any} translation Translated doc, possibly covering only some props.
- * @returns {any} Merged doc with every base prop present.
+ * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
+ * @param {LoadDocOptions} [opts]
+ * @returns {Promise<any>} the checked (and optionally translated) doc
  */
-function overlayComponentDoc(docs, translation) {
-  /** Merge one prop list: keep base entries and order, translate what's covered.
-   * @param {any[] | undefined} baseProps
-   * @param {any[] | undefined} tProps
-   */
-  const overlayProps = (baseProps, tProps) => {
-    if (!baseProps) return baseProps;
-    const byName = new Map((tProps ?? []).map((/** @type {any} */ p) => [p.name, p]));
-    return baseProps.map((/** @type {any} */ prop) => {
-      const t = byName.get(prop.name);
-      // Take the translated text, but never let it drop the prop's contract
-      // (type/default/required stay authoritative from the English doc).
-      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
-    });
-  };
-
-  /** Preserve canonical structured guidance added after legacy full-doc translations,
-   * without changing established translated prose behavior.
-   * @param {any} baseUsage
-   * @param {any} translatedUsage
-   */
-  const mergeUsage = (baseUsage, translatedUsage) => {
-    if (!translatedUsage) return baseUsage;
-    return {
-      ...translatedUsage,
-      ...(translatedUsage.accessibility === undefined &&
-      baseUsage?.accessibility !== undefined
-        ? {accessibility: baseUsage.accessibility}
-        : null),
-      ...(translatedUsage.accessibilityThemeCoverage === undefined &&
-      baseUsage?.accessibilityThemeCoverage !== undefined
-        ? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
-        : null),
-      ...(translatedUsage.anatomy === undefined && baseUsage?.anatomy !== undefined
-        ? {anatomy: baseUsage.anatomy}
-        : null),
-    };
-  };
-
-  const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};
-
-  merged.props = overlayProps(docs.props, translation.props);
-
-  if (docs.components) {
-    const tByName = new Map(
-      (translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
-    );
-    merged.components = docs.components.map((/** @type {any} */ base) => {
-      const t = tByName.get(base.name);
-      if (!t) return base;
-      return {...base, ...t, usage: mergeUsage(base.usage, t.usage), props: overlayProps(base.props, t.props)};
-    });
-  }
-
-  return merged;
+export async function loadComponentDoc(docPath, opts = {}) {
+  return readDocView(docPath, {
+    root: opts.root ?? 'components',
+    lang: localeOf(opts),
+    label: docPath,
+    strict: true,
+  });
 }
 
 /**
- * Find the doc file for a component, checking both top-level
- * and nested directories. Prefers {Name}.doc.mjs, then README.md
- * (for backward compatibility).
+ * Load a component or hook doc without checking it. Supports `lang` ('zh' for
+ * Chinese, 'dense' for compressed) and the legacy `zh`/`dense` flags; the
+ * translation is laid over the doc, keeping its structure. A file that exports
+ * no doc reads as `undefined`.
+ * @param {string} readmePath
+ * @param {LoadDocOptions} [opts]
+ * @returns {Promise<any>}
  */
+export async function loadDocs(readmePath, opts = {}) {
+  return readDocView(readmePath, {
+    root: opts.root ?? 'components',
+    lang: localeOf(opts),
+    label: readmePath,
+    loader: 'native',
+  });
+}

package/foundation/discovery/docs-discovery.d.mts

@@ -5,6 +5,8 @@
  * @typedef {object} DocsTopicRecord A doc file discovered under a docs root.
  * @property {string} name
  * @property {string} package owner package
+ * @property {string} [providerId] the owner's ProviderId, when it differs from
+ *   the package name
  * @property {string} path absolute path to the doc file
  * @property {string} [title]
  * @property {string} [description]
@@ -16,13 +18,21 @@
  * @typedef {object} DocsTopicEntry A resolved topic in the catalog.
  * @property {string} name
  * @property {string} package owner package
+ * @property {string} [providerId] the owner's ProviderId; the package name when
+ *   absent. Links in the topic resolve against it.
  * @property {string} path absolute path to the doc file
  * @property {string} [title]
  * @property {string} [description]
  * @property {string|null} [category]
  * @property {string} [replaces] the topic this one took the place of
- * @property {Array<{package: string, path: string}>} extensions overlays to
- *   merge onto the base doc, in the order their integrations were configured
+ * @property {Array<{package: string, path: string, providerId?: string}>} extensions
+ *   overlays to merge onto the base doc, in the order their integrations were
+ *   configured; each section an extension adds resolves its links against the
+ *   extension's provider id (its package name when absent)
+ * @property {string} [parent] the route of the namespace a tree guide sits in
+ * @property {string} [route] a tree guide's route
+ * @property {boolean} [tree] a guide that only the docs tree reads, by its
+ *   route; never a flat topic
  */
 /**
  * Discover the CLI's own topics.
@@ -48,9 +58,19 @@ export function loadTopicModule(file: string): Promise<unknown>;
  * where the file that needs fixing can be named.
  *
  * @param {any} doc a parsed doc
+ * @param {{placement?: boolean}} [options] `placement`: the doc is a guide the
+ *   docs tree places, so its `placement` field is read, not rejected
  * @returns {string[]} problems, each already pointed at a place in the doc
  */
-export function problemsInTopic(doc: any): string[];
+export function problemsInTopic(doc: any, { placement }?: {
+    placement?: boolean;
+}): string[];
+/**
+ * The fields the docs tree reads from a namespace doc an integration ships.
+ * @param {any} doc
+ * @returns {string[]}
+ */
+export function problemsInNamespace(doc: any): string[];
 /**
  * Discover the topics contributed by a single loaded integration. Mirrors
  * `discoverIntegrationComponents`: walk the resolved root, take every
@@ -58,23 +78,32 @@ export function problemsInTopic(doc: any): string[];
  * discovery this loads each doc, because a topic's name and its relationship
  * to an existing topic are fields inside the file.
  *
+ * A namespace doc and a guide with `placement` go to the docs tree instead of
+ * the topic list (spec:AST-046): they come back in `namespaces` and `guides`,
+ * named by the integration's provider id.
+ *
  * Errors are returned, not thrown: one unusable doc is reported as an issue
  * against its package while the rest of the CLI keeps working.
  *
- * @param {{name: string, docs?: string}} integration a loaded integration
- * @returns {Promise<{records: DocsTopicRecord[], errors: Error[]}>}
+ * @param {{name: string, docs?: string, providerId?: string}} integration a loaded integration
+ * @returns {Promise<{records: DocsTopicRecord[], errors: Error[], namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>}
  */
 export function discoverIntegrationDocs(integration: {
     name: string;
     docs?: string;
+    providerId?: string;
 }): Promise<{
     records: DocsTopicRecord[];
     errors: Error[];
+    namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
 }>;
 /**
- * Merge an extension onto a base topic: a section whose title matches one in
- * the base replaces it, a section the base does not have is appended, and the
- * title/description are taken from the extension when it states them.
+ * Merge an extension onto a base topic: a section with a stable `id` replaces
+ * the base section with the same `id`; legacy sections without IDs fall back to
+ * title matching. A section with no match is appended. The title and
+ * description stay the base topic's: an extension adds to a topic, it never
+ * renames it. A topic that `replaces` another is the one that renames.
  *
  * Keyed by section TITLE rather than by position, the way the localization
  * overlays are — position keying grafts an overlay onto whichever section
@@ -86,12 +115,23 @@ export function discoverIntegrationDocs(integration: {
  * @returns {any} a new doc; neither input is mutated
  */
 export function mergeTopic(base: any, overlay: any): any;
+export { withSourceTitle };
 /**
  * Owner package recorded for the built-in topics. They ship inside the CLI
  * (assets/docs), not in @astryxdesign/core, so this is the CLI's own name —
  * unlike component discovery, whose built-ins belong to core.
  */
-export const BUILTIN_DOCS_PACKAGE: "@astryxdesign/cli";
+export const BUILTIN_DOCS_PACKAGE: import("../../authoring/index.js").ProviderId;
+/**
+ * Blocks that are valid authoring but require the compiled graph renderer: a
+ * namespace doc's `blocks` hold them, a topic section does not.
+ */
+export const GRAPH_BLOCK_TYPES: Set<string>;
+/**
+ * Doc fields only the docs tree reads. A flat topic that sets one fails to
+ * load; a guide the tree places may set `placement` (spec:AST-046).
+ */
+export const GRAPH_ONLY_FIELDS: string[];
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -107,6 +147,40 @@ export class DocsCatalog {
      * @returns {DocsCatalog}
      */
     static fromBuiltins(builtins?: Record<string, string>): DocsCatalog;
+    /**
+     * Record a doc file a package ships that did not load. Its package's docs
+     * are withdrawn; readers name the package so an author knows where to look.
+     * @param {{package: string, message: string}} issue
+     */
+    addIssue(issue: {
+        package: string;
+        message: string;
+    }): void;
+    /**
+     * The doc files that did not load, by package.
+     * @returns {ReadonlyArray<{package: string, message: string}>}
+     */
+    get issues(): ReadonlyArray<{
+        package: string;
+        message: string;
+    }>;
+    /**
+     * Add the namespace docs and placed guides one integration ships to the
+     * docs tree (spec:AST-046).
+     * @param {{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}} inputs
+     */
+    addTreeInputs(inputs: {
+        namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
+        guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
+    }): void;
+    /**
+     * What the integrations add to the docs tree, in configured order.
+     * @returns {ReadonlyArray<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>}
+     */
+    get treeInputs(): ReadonlyArray<{
+        namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
+        guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
+    }>;
     /**
      * Add one integration-contributed doc, honoring what it declares. Returns
      * the issue it caused, or null when it applied cleanly — the caller owns
@@ -116,6 +190,14 @@ export class DocsCatalog {
      * @returns {import('../integrations/issue').AstryxIntegrationIssue | null}
      */
     add(record: DocsTopicRecord): import("../integrations/issue").AstryxIntegrationIssue | null;
+    /**
+     * Every other name a topic answers to, lowercased: the names of the topics
+     * it replaced, directly or through a chain of replacements. `resolve` finds
+     * the topic by each of them.
+     * @param {DocsTopicEntry} entry
+     * @returns {string[]}
+     */
+    aliasesOf(entry: DocsTopicEntry): string[];
     /**
      * Look a topic up by name, case-insensitively, following the alias a renamed
      * replacement left behind.
@@ -138,6 +220,11 @@ export type DocsTopicRecord = {
      * owner package
      */
     package: string;
+    /**
+     * the owner's ProviderId, when it differs from
+     * the package name
+     */
+    providerId?: string | undefined;
     /**
      * absolute path to the doc file
      */
@@ -163,6 +250,11 @@ export type DocsTopicEntry = {
      * owner package
      */
     package: string;
+    /**
+     * the owner's ProviderId; the package name when
+     * absent. Links in the topic resolve against it.
+     */
+    providerId?: string | undefined;
     /**
      * absolute path to the doc file
      */
@@ -175,11 +267,27 @@ export type DocsTopicEntry = {
      */
     replaces?: string | undefined;
     /**
-     * overlays to
-     * merge onto the base doc, in the order their integrations were configured
+     *   overlays to merge onto the base doc, in the order their integrations were
+     *   configured; each section an extension adds resolves its links against the
+     *   extension's provider id (its package name when absent)
      */
     extensions: Array<{
         package: string;
         path: string;
+        providerId?: string;
     }>;
+    /**
+     * the route of the namespace a tree guide sits in
+     */
+    parent?: string | undefined;
+    /**
+     * a tree guide's route
+     */
+    route?: string | undefined;
+    /**
+     * a guide that only the docs tree reads, by its
+     * route; never a flat topic
+     */
+    tree?: boolean | undefined;
 };
+import { withSourceTitle } from './docs-section-key.mjs';