@astryxdesign/cli 0.7.12-canary.9a690d5 → 0.7.12-canary.c73b9e4

package/api/component/__fixtures__/resolutions/modules.txt

@@ -247,9 +247,9 @@ useAutoMediaMode useAutoMediaMode hooks/useAnimatedLayout.doc.mjs hooks/useAutoM
 useBackdropPress useBackdropPress Layer/Layer.doc.mjs Layer/useBackdropPress.ts
 useBaseTablePlugins useBaseTablePlugins Table/Table.doc.mjs Table/useBaseTablePlugins.ts
 useBusyAnnouncement useBusyAnnouncement hooks/useAnimatedLayout.doc.mjs hooks/useBusyAnnouncement.ts
-useCalendarConstraints useCalendarConstraints Calendar/Calendar.doc.mjs Calendar/hooks/useCalendarConstraints.ts
+useCalendarConstraints useCalendarConstraints Calendar/useCalendarConstraints.doc.mjs Calendar/hooks/useCalendarConstraints.ts
 useCalendarDays useCalendarDays Calendar/useCalendarDays.doc.mjs Calendar/hooks/useCalendarDays.ts
-useCalendarNavigation useCalendarNavigation Calendar/Calendar.doc.mjs Calendar/hooks/useCalendarNavigation.ts
+useCalendarNavigation useCalendarNavigation Calendar/useCalendarNavigation.doc.mjs Calendar/hooks/useCalendarNavigation.ts
 useChatComposerTokens useChatComposerTokens Chat/Chat.doc.mjs Chat/useChatComposerTokens.ts
 useChatDictation useChatDictation Chat/Chat.doc.mjs Chat/useChatDictation.ts
 useChatNewMessages useChatNewMessages Chat/Chat.doc.mjs Chat/useChatNewMessages.ts

package/api/docs/_adapter.d.mts

@@ -319,6 +319,28 @@ export function nameOwner(tree: DocsTree, catalog: DocsCatalog, name: string): {
     kind: "node";
     node: TreeNode;
 } | null;
+/**
+ * `stability: 'experimental'` for a node whose doc is marked experimental, or
+ * that sits under an experimental namespace (spec:AST-017 FR27), the way help
+ * marks an experimental command; nothing for a stable one, so stable entries
+ * read as they always have.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {{stability?: 'experimental'}}
+ */
+export function stabilityOf(tree: DocsTree, node: TreeNode): {
+    stability?: "experimental";
+};
+/**
+ * The fields every child carries: what it is, and the route that opens it.
+ * Shared, so a child reads the same whether a namespace read or the topic
+ * list names it — including the package, which is the integration's for a
+ * guide an integration replaced, not the package whose route it took.
+ * @param {DocsTree} tree
+ * @param {TreeNode} child
+ * @returns {import('./docs.type.mjs').DocsNodeChild}
+ */
+export function childIdentity(tree: DocsTree, child: TreeNode): import("./docs.type.mjs").DocsNodeChild;
 /**
  * Whether a topic answers to its own name: what the topic list and search
  * offer must open that topic.

package/api/docs/_adapter.mjs

@@ -1765,9 +1765,87 @@ export function nameOwner(tree, catalog, name) {
     return entry == null ? null : {kind: 'topic', entry};
   }
   const entry = catalog.resolve(name);
-  if (entry == null) return null;
-  const owner = routeOwner(tree, entry);
-  return owner == null ? {kind: 'topic', entry} : {kind: 'node', node: owner};
+  if (entry != null) {
+    const owner = routeOwner(tree, entry);
+    return owner == null ? {kind: 'topic', entry} : {kind: 'node', node: owner};
+  }
+  return childOwner(tree, name);
+}
+
+/**
+ * The child a reader names without its namespace, or with a route that leaves
+ * out the prefix the child's own name repeats (spec:AST-046 FR5). A namespace
+ * whose children repeat its name makes its own routes stutter: `tokens` holds
+ * `tokens-color`, so the route is `tokens/tokens-color`, while the namespace
+ * listing shows the bare `tokens-color`. Both spellings name one child, so
+ * that child answers. Two or more children answering is ambiguous, and the
+ * read falls through to the suggestion list, unchanged. An experimental doc
+ * never answers to a bare name: its project reaches it only by a marked route
+ * (spec:AST-017 FR27).
+ * @param {DocsTree} tree
+ * @param {string} name
+ * @returns {{kind: 'node', node: TreeNode} | null}
+ */
+function childOwner(tree, name) {
+  const wanted = name.toLowerCase();
+  const slash = wanted.lastIndexOf('/');
+  const parent = slash > 0 ? wanted.slice(0, slash) : null;
+  const unstuttered =
+    parent == null
+      ? null
+      : `${parent}/${parent.slice(parent.lastIndexOf('/') + 1)}-${wanted.slice(slash + 1)}`;
+  const matches = [...tree.nodes.values()].filter(
+    node =>
+      node.ref?.flatTopic == null &&
+      node.route.includes('/') &&
+      // An experimental doc is reachable only by a route its project marked
+      // as experimental (spec:AST-017 FR27): a bare name never opens one.
+      !isExperimentalTreeNode(tree, node) &&
+      (node.name?.toLowerCase() === wanted ||
+        (unstuttered != null && node.route.toLowerCase() === unstuttered)),
+  );
+  return matches.length === 1 ? {kind: 'node', node: matches[0]} : null;
+}
+
+/**
+ * `stability: 'experimental'` for a node whose doc is marked experimental, or
+ * that sits under an experimental namespace (spec:AST-017 FR27), the way help
+ * marks an experimental command; nothing for a stable one, so stable entries
+ * read as they always have.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {{stability?: 'experimental'}}
+ */
+export function stabilityOf(tree, node) {
+  return isExperimentalTreeNode(tree, node) ? {stability: 'experimental'} : {};
+}
+
+/**
+ * The fields every child carries: what it is, and the route that opens it.
+ * Shared, so a child reads the same whether a namespace read or the topic
+ * list names it — including the package, which is the integration's for a
+ * guide an integration replaced, not the package whose route it took.
+ * @param {DocsTree} tree
+ * @param {TreeNode} child
+ * @returns {import('./docs.type.mjs').DocsNodeChild}
+ */
+export function childIdentity(tree, child) {
+  return {
+    route: child.route,
+    name: child.route.slice(child.route.lastIndexOf('/') + 1),
+    package: child.guideOverlay?.replacement?.package ?? child.provider,
+    // A guide an integration's doc took the place of names whose it was.
+    ...(child.guideOverlay?.replacement
+      ? {
+          replaces: child.route,
+          replacedPackage: child.guideOverlay.replacedPackage ?? child.provider,
+        }
+      : {}),
+    kind: child.kind,
+    title: child.title,
+    summary: child.summary,
+    ...stabilityOf(tree, child),
+  };
 }
 
 /**

package/api/docs/docs.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
       name: 'topic',
       type: 'string',
       description:
-        "Doc topic to load (e.g. 'principles'), or a docs-tree route (e.g. 'cli/api/functions/search'). Omit to list all topics.",
+        "Doc topic to load (e.g. 'principles'), a docs-tree route (e.g. 'cli/api/functions/search'), or the name of one node of the docs tree: its own name (e.g. 'tokens-color'), or its route without the prefix its name repeats (e.g. 'tokens/color'), where exactly one node answers to it. Omit to list all topics.",
     },
     {
       name: 'section',
@@ -88,13 +88,13 @@ export const doc = {
       name: 'options.depth',
       type: "number | 'all'",
       description:
-        "How many levels below a docs-tree namespace to read: 0 for the namespace alone, 1 for its children (the default), 'all' for every level. Where a read stops, a child with docs below it carries childCount. A doc with nothing below it reads the same at any depth.",
+        "How many levels below a docs-tree namespace to read: 0 for the namespace alone, 1 for its children (the default), 'all' for every level. Where a read stops, a child with docs below it carries childCount. A doc with nothing below it reads the same at any depth. On the topic list, where each namespace otherwise lists alone, it names the docs below each one, as deep as asked; without it the list is unchanged.",
     },
     {
       name: 'options.detail',
       type: "'brief' | 'compact' | 'full'",
       description:
-        "How much of each doc below the named one a depth read returns: brief (the default) is its identity; compact and full add its text (a guide's sections, a namespace's or typed doc's content). Given alone, it reads one level down.",
+        "How much of each doc below the named one a depth read returns: brief (the default) is its identity; compact and full add its text (a guide's sections, a namespace's or typed doc's content). Given alone, it reads one level down. The topic list names each doc below a namespace by its identity whatever the detail.",
     },
     {
       name: 'options.cwd',
@@ -107,7 +107,7 @@ export const doc = {
     {
       type: 'docs.list',
       description:
-        "Every reference-doc topic in read order, as DocsListEntry[] ({topic, description, package, replaces?, replacedPackage?}), each readable with docs(topic). meta.namespaces lists the docs tree's top-level namespaces ({topic, description, package}), and meta.notLoaded each package whose docs did not load ({package, message}).",
+        "Every reference-doc topic in read order, as DocsListEntry[] ({topic, description, package, replaces?, replacedPackage?}), each readable with docs(topic). meta.namespaces lists the docs tree's top-level namespaces ({topic, description, package}); with depth, each also carries children, the docs below it as a namespace read names them ({topic, description, route, name, package, kind, title, summary, replaces?, replacedPackage?, stability?}), nested the same way to the depth asked for, and childCount where the depth stops on a doc with docs below it. meta.notLoaded names each package whose docs did not load ({package, message}).",
     },
     {
       type: 'docs.detail',
@@ -141,7 +141,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_TOPIC',
-      when: 'the topic is not a string, or matches no topic and no docs-tree route',
+      when: 'the topic is not a string, or matches no topic, no docs-tree route, and no one node of the docs tree by its own name or by its route without the prefix its name repeats; a name more than one node answers to opens none of them, and the suggestions list them',
     },
     {
       code: 'ERR_UNKNOWN_SECTION',

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

@@ -56,6 +56,27 @@ export type DocsListNamespace = {
      * the package that owns it
      */
     package: string;
+    /**
+     * the docs below it, present only for
+     * a read that passed `depth` and only where the namespace has children
+     */
+    children?: DocsListChild[] | undefined;
+    /**
+     * how many docs sit right below it, where a
+     * depth read stops here and it has docs below it
+     */
+    childCount?: number | undefined;
+};
+/**
+ * One doc below a namespace on the topic list, as `astryx docs --depth` names
+ * it: everything a namespace read gives a child, plus the two fields every
+ * list row carries, so one row reads the same way wherever it came from.
+ */
+export type DocsListChild = DocsNodeChild & {
+    topic: string;
+    description: string;
+    children?: DocsListChild[];
+    childCount?: number;
 };
 /**
  * astryx --json docs <topic> --index

package/api/docs/docs.type.mjs

@@ -45,6 +45,17 @@
  * @property {string} topic its route, the argument that opens it
  * @property {string} description
  * @property {string} package the package that owns it
+ * @property {DocsListChild[]} [children] the docs below it, present only for
+ *   a read that passed `depth` and only where the namespace has children
+ * @property {number} [childCount] how many docs sit right below it, where a
+ *   depth read stops here and it has docs below it
+ */
+
+/**
+ * One doc below a namespace on the topic list, as `astryx docs --depth` names
+ * it: everything a namespace read gives a child, plus the two fields every
+ * list row carries, so one row reads the same way wherever it came from.
+ * @typedef {DocsNodeChild & {topic: string, description: string, children?: DocsListChild[], childCount?: number}} DocsListChild
  */
 
 /**

package/api/docs/list/list.d.mts

@@ -4,8 +4,12 @@
 /**
  * @param {object} [options]
  * @param {string} [options.cwd]
+ * @param {number | 'all'} [options.depth] how many levels of the docs tree to
+ *   list below each namespace; without it the namespaces list alone, as they
+ *   always have
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export function list({ cwd }?: {
+export function list({ cwd, depth }?: {
     cwd?: string | undefined;
+    depth?: number | "all" | undefined;
 }): Promise<import("../docs.type.mjs").DocsListResponse>;

package/api/docs/list/list.mjs

@@ -16,6 +16,7 @@
 
 import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
 import {
+  childIdentity,
   holdsOwnName,
   linkDocText,
   loadDocsCatalog,
@@ -25,9 +26,12 @@ import {
 /**
  * @param {object} [options]
  * @param {string} [options.cwd]
+ * @param {number | 'all'} [options.depth] how many levels of the docs tree to
+ *   list below each namespace; without it the namespaces list alone, as they
+ *   always have
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export async function list({cwd} = {}) {
+export async function list({cwd, depth} = {}) {
   const catalog = await loadDocsCatalog(cwd);
   const tree = await projectTree(catalog);
   /** @type {Array<import('../docs.type.mjs').DocsListEntry>} */
@@ -64,11 +68,11 @@ export async function list({cwd} = {}) {
   // The docs tree's top-level namespaces, the CLI's and each integration's,
   // each the way into a whole branch (spec:AST-046 FR7). They go in `meta`,
   // so `data` stays the topic list 0.6 returned: every entry reads as a topic.
-  const namespaces = tree.roots().map(root => ({
-    topic: root.route,
-    description: root.summary,
-    package: root.provider,
-  }));
+  // With `depth`, each one also carries the branch below it, so one read
+  // learns every route: without it a reader knows only that the namespace is
+  // there, and the children it must name are invisible until it opens each one.
+  const levels = depthLevels(depth);
+  const namespaces = tree.roots().map(root => branch(tree, root, levels));
   /** @type {NonNullable<import('../docs.type.mjs').DocsListResponse['meta']>} */
   const meta = {};
   if (namespaces.length > 0) meta.namespaces = namespaces;
@@ -79,3 +83,65 @@ export async function list({cwd} = {}) {
     ? {type: 'docs.list', data: entries}
     : {type: 'docs.list', data: entries, meta};
 }
+
+/**
+ * How many levels below each namespace the list carries: none without
+ * `depth`, every level for `'all'`. `docs <namespace> --depth` reads the same
+ * way, so one flag means one thing everywhere.
+ * @param {number | 'all'} [depth]
+ * @returns {number | null} null for a list read with no depth, which carries
+ *   the namespaces alone
+ */
+function depthLevels(depth) {
+  if (depth == null) return null;
+  return depth === 'all' ? Infinity : depth;
+}
+
+/**
+ * One namespace of the list, with the branch below it to `levels`. A child
+ * reads exactly as a namespace read gives it (`childIdentity`): the route
+ * that opens it, and the package that owns it — the integration's, for a
+ * guide an integration replaced, with the package whose route it took beside
+ * it. Every line of the list is then an argument a reader can pass straight
+ * back to `astryx docs`, attributed the way the read attributes it. Where the
+ * depth stops on a doc with docs below it, the row says how many, as a
+ * namespace read's child does; `levels` of null is a read with no depth,
+ * which says nothing about what is below.
+ * @param {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} tree
+ * @param {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} node
+ * @param {number | null} levels
+ * @returns {import('../docs.type.mjs').DocsListNamespace}
+ */
+function branch(tree, node, levels) {
+  /** @type {import('../docs.type.mjs').DocsListNamespace} */
+  const listed = {
+    topic: node.route,
+    description: node.summary,
+    package: node.provider,
+  };
+  if (levels == null) return listed;
+  const below = node.slots.flatMap(slot => slot.children);
+  if (levels <= 0) {
+    if (below.length > 0) listed.childCount = below.length;
+    return listed;
+  }
+  const children = below
+    .map(route => tree.get(route))
+    .filter(child => child != null)
+    .map(child => {
+      const node = /** @type {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} */ (
+        child
+      );
+      const {topic: _route, ...rest} = branch(tree, node, levels - 1);
+      const identity = childIdentity(tree, node);
+      return /** @type {import('../docs.type.mjs').DocsListChild} */ ({
+        ...identity,
+        topic: identity.route,
+        description: identity.summary,
+        ...(rest.children ? {children: rest.children} : {}),
+        ...(rest.childCount ? {childCount: rest.childCount} : {}),
+      });
+    });
+  if (children.length > 0) listed.children = children;
+  return listed;
+}

package/api/docs/node/node.mjs

@@ -16,13 +16,14 @@
  */
 
 import {detailView} from '../../../foundation/doc-compiler/lenses.mjs';
-import {isExperimentalTreeNode} from '../../../foundation/doc-compiler/tree.mjs';
 import {
+  childIdentity,
   compileTopic,
   guideEntry,
   nodeContent,
   placeLinks,
   resolveDocsArgument,
+  stabilityOf,
   unknownTopicError,
 } from '../_adapter.mjs';
 
@@ -87,45 +88,6 @@ export async function nodeView(catalog, tree, node, read) {
   return view;
 }
 
-/**
- * `stability: 'experimental'` for a node whose doc is marked experimental, or
- * that sits under an experimental namespace (spec:AST-017 FR27), the way help
- * marks an experimental command; nothing for a stable one, so stable entries
- * read as they always have.
- * @param {DocsTree} tree
- * @param {TreeNode} node
- * @returns {{stability?: 'experimental'}}
- */
-function stabilityOf(tree, node) {
-  return isExperimentalTreeNode(tree, node) ? {stability: 'experimental'} : {};
-}
-
-/**
- * The fields every child carries: what it is, and the route that opens it.
- * @param {DocsTree} tree
- * @param {TreeNode} child
- * @returns {import('../docs.type.mjs').DocsNodeChild}
- */
-function childIdentity(tree, child) {
-  return {
-    route: child.route,
-    name: child.route.slice(child.route.lastIndexOf('/') + 1),
-    package: child.guideOverlay?.replacement?.package ?? child.provider,
-    // A guide an integration's doc took the place of names whose it was.
-    ...(child.guideOverlay?.replacement
-      ? {
-          replaces: child.route,
-          replacedPackage:
-            child.guideOverlay.replacedPackage ?? child.provider,
-        }
-      : {}),
-    kind: child.kind,
-    title: child.title,
-    summary: child.summary,
-    ...stabilityOf(tree, child),
-  };
-}
-
 /**
  * @param {TreeNode['slots']} slots
  * @returns {number}

package/api/index.d.mts

@@ -47,6 +47,7 @@ export * from "./integration/authoring-checks.type.mjs";
 export * from "./integration/integration-check.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeRemove, themeUse, themeEject, themeTemplate, themeList, themeListAvailable, themeListCopySources, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { exportSearchIndex, rankSearchIndex } from "./search/search-index.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
 export { integrationTemplateConflicts, integrationComponentConflicts, integrationDocConflicts } from "./integration/authoring-checks.mjs";

package/api/index.mjs

@@ -48,6 +48,7 @@ export {
 } from './theme/theme.mjs';
 export {hook} from './hook/hook.mjs';
 export {search} from './search/search.mjs';
+export {exportSearchIndex, rankSearchIndex} from './search/search-index.mjs';
 export {build} from './build/build.mjs';
 export {swizzle} from './swizzle/swizzle.mjs';
 export {gapReport} from './gap-report/gap-report.mjs';

package/api/render/_adapter.mjs

@@ -548,6 +548,15 @@ export function reverseToFile({cwd, input, output, overwrite}) {
       ...(missing.length > 0 ? {missing} : {}),
     };
   }
+  // A file a render wrote, whose source block was taken out on the way
+  // (sanitizers and editors strip <script> elements), says so.
+  if (!isAstryxMarkup(html) && /<meta name="generator" content="Astryx[ "]/.test(html)) {
+    throw new AstryxError(
+      `${shown(cwd, input)} was rendered by Astryx, but its embedded source was removed (a sanitizer or an editor strips <script> blocks) and it has no Astryx components to rebuild from; nothing was written. Render the page again from its source and send the new file as is.`,
+      [],
+      ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
+    );
+  }
   if (!isAstryxMarkup(html)) {
     throw new AstryxError(
       `${shown(cwd, input)} is not an Astryx page: it has no embedded source and no Astryx components to rebuild from. To start an Astryx page like it, run astryx build "<what the page is>".`,

package/api/render/render.doc.mjs

@@ -99,9 +99,9 @@ export const doc = {
     {code: 'ERR_RENDER_FAILED', when: 'the page throws while rendering for any other reason'},
     {
       code: 'ERR_RENDER_NOT_ASTRYX',
-      when: 'reversing a file with no embedded source and no Astryx markup; the suggestion is `astryx build "<what the page is>"`',
+      when: 'reversing a file a render did not write, with no embedded source and no Astryx markup; the suggestion is `astryx build "<what the page is>"`',
     },
-    {code: 'ERR_RENDER_SOURCE_DAMAGED', when: 'reversing a file whose embedded source is damaged, lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds (a dotfile or dot-folder, `node_modules`, a package manifest, lockfile or tool configuration, or any kind but a page module, stylesheet, JSON or image)'},
+    {code: 'ERR_RENDER_SOURCE_DAMAGED', when: 'reversing a file a render wrote whose embedded source was removed (and that has no Astryx components to rebuild from), a file whose embedded source is damaged, lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds (a dotfile or dot-folder, `node_modules`, a package manifest, lockfile or tool configuration, or any kind but a page module, stylesheet, JSON or image)'},
     {code: 'ERR_PATH_TRAVERSAL', when: 'a file would be written outside the current folder (symlinks followed), or through a symbolic link: `out`, or with `reverse` the page or an embedded file; or, with `reverse`, a file other than the page would go into a folder that already exists'},
   ],
   examples: [

package/api/search/_adapter.d.mts

@@ -16,7 +16,7 @@ export function requireSearchCoreDir(cwd: string): string;
  * in the CLI's searches. A caller that runs its own operation shares it.
  *
  * @param {{cwd?: string, type?: string}} options
- * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}
  */
 export function gatherCandidates(options: {
     cwd?: string;
@@ -27,7 +27,28 @@ export function gatherCandidates(options: {
     searchedComponents: boolean;
     outside: boolean;
     coreSkipped: string | null;
+    coreSkippedCode: string | null;
 }>;
+/**
+ * The Core a search of `type` reads, and the domains it gathers. `astryx docs`
+ * reads docs without @astryxdesign/core, and `astryx theme list` reads themes
+ * without it, so a docs or themes search never looks for Core. Every other
+ * domain reads Core: the project's, else the answering release's own,
+ * installed into the per-user cache on first need (spec AST-081 FR3). A Core
+ * domain asked for by name throws the lookup's coded error. An open search
+ * without Core gathers the docs and themes alone and records why in
+ * `coreSkipped`; it never fails silently.
+ * @param {string | undefined} type
+ * @param {(cwd: string) => string} lookup finds the Core folder, or throws
+ * @param {string} cwd
+ * @returns {{coreDir: string | null, coreSkipped: string | null, coreSkippedCode: string | null, wants: (domain: string) => boolean}}
+ */
+export function resolveSearchCore(type: string | undefined, lookup: (cwd: string) => string, cwd: string): {
+    coreDir: string | null;
+    coreSkipped: string | null;
+    coreSkippedCode: string | null;
+    wants: (domain: string) => boolean;
+};
 /**
  * gatherCandidates, reused within one process: a later search in the same
  * folder, for the same `type`, ranks the candidates an earlier search

package/api/search/_adapter.mjs

@@ -43,46 +43,62 @@ export function requireSearchCoreDir(cwd) {
  * in the CLI's searches. A caller that runs its own operation shares it.
  *
  * @param {{cwd?: string, type?: string}} options
- * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}
  */
 export function gatherCandidates(options) {
   return withListingCache(() => gatherDomains(options));
 }
 
 /**
- * @param {{cwd?: string, type?: string}} options
+ * The Core a search of `type` reads, and the domains it gathers. `astryx docs`
+ * reads docs without @astryxdesign/core, and `astryx theme list` reads themes
+ * without it, so a docs or themes search never looks for Core. Every other
+ * domain reads Core: the project's, else the answering release's own,
+ * installed into the per-user cache on first need (spec AST-081 FR3). A Core
+ * domain asked for by name throws the lookup's coded error. An open search
+ * without Core gathers the docs and themes alone and records why in
+ * `coreSkipped`; it never fails silently.
+ * @param {string | undefined} type
+ * @param {(cwd: string) => string} lookup finds the Core folder, or throws
+ * @param {string} cwd
+ * @returns {{coreDir: string | null, coreSkipped: string | null, coreSkippedCode: string | null, wants: (domain: string) => boolean}}
  */
-async function gatherDomains(options) {
-  const {cwd = process.cwd(), type} = options;
-  // `astryx docs` reads docs without @astryxdesign/core, and `astryx theme
-  // list` reads themes without it (bundled themes need no project), so a
-  // search of either must too. Every other domain reads core: asked for by
-  // name, it is an error without core; an open search then covers the docs
-  // and themes alone.
+export function resolveSearchCore(type, lookup, cwd) {
   const needsCore = !type || !CORELESS_DOMAINS.includes(type);
-  // A domain that reads Core gets it as `component` does: the project's, else
-  // the answering release's own, installed into the per-user cache on first
-  // need (spec AST-081 FR3). Asked for by name, a Core that cannot be had is
-  // the error; an open search answers from the rest and says what it skipped
-  // and why, never silently.
   /** @type {string | null} */
   let coreDir = null;
   /** @type {string | null} */
   let coreSkipped = null;
+  /** @type {string | null} */
+  let coreSkippedCode = null;
   if (needsCore && type) {
-    coreDir = coreDirOrThrow(requireSearchCoreDir, cwd);
+    coreDir = coreDirOrThrow(lookup, cwd);
   } else if (needsCore) {
     try {
-      coreDir = requireSearchCoreDir(cwd);
+      coreDir = lookup(cwd);
     } catch (error) {
       coreSkipped = /** @type {Error} */ (error).message;
+      const code = /** @type {any} */ (error)?.code;
+      coreSkippedCode = typeof code === 'string' ? code : null;
     }
   }
+  /** @param {string} domain */
+  const wants = domain =>
+    (!type && (coreDir != null || CORELESS_DOMAINS.includes(domain))) ||
+    type === domain;
+  return {coreDir, coreSkipped, coreSkippedCode, wants};
+}
 
-  // Gather candidates from each requested domain in parallel.
-  /** @param {string} d */
-  const wants = d =>
-    (!type && (coreDir != null || CORELESS_DOMAINS.includes(d))) || type === d;
+/**
+ * @param {{cwd?: string, type?: string}} options
+ */
+async function gatherDomains(options) {
+  const {cwd = process.cwd(), type} = options;
+  const {coreDir, coreSkipped, coreSkippedCode, wants} = resolveSearchCore(
+    type,
+    requireSearchCoreDir,
+    cwd,
+  );
   const [components, hooks, docTopics, templates, themes] = await Promise.all([
     wants('component')
       ? gatherComponents(/** @type {string} */ (coreDir), cwd)
@@ -103,6 +119,7 @@ async function gatherDomains(options) {
     searchedComponents: wants('component'),
     outside,
     coreSkipped,
+    coreSkippedCode,
   };
 }
 

package/api/search/exportSearchIndex.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `exportSearchIndex()`. Colocated with the API function it
+ * documents; the shape source of truth stays in `search.type.mjs`.
+ * @position packages/cli/api/search — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/search/exportSearchIndex.doc.mjs

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `exportSearchIndex()`. Colocated with the API function it
+ * documents; the shape source of truth stays in `search.type.mjs`.
+ * @position packages/cli/api/search — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'exportSearchIndex',
+  namespace: 'cli/api',
+  stability: 'experimental',
+  displayName: 'exportSearchIndex()',
+  summary:
+    'The candidates search ranks in a folder, as plain JSON to store and rank later with rankSearchIndex().',
+  description:
+    "Gathers what `search()` would rank in `cwd` and returns it as `{version, candidates}`. Gathering reads each installed package's docs and loads its integration manifest, which runs that package's code, so a catalog that lists packages it must not load makes the index where loading is safe (a folder with those packages installed), stores it, and ranks it with {@link function:rankSearchIndex}. With `package`, the index keeps only that package's candidates, for a catalog that stores one index per package. A component description's inline doc tokens are resolved where the index is made, as `search` prints them; when Core could not be had there, the index says why in `coreSkipped`. Fields that point into the folder are left out, so an index reads the same wherever it was made. The candidates are the ranker's input, not a stable shape: an index is ranked only by the CLI version that made it. Experimental: it may change or be removed in a patch release.",
+  importPath: '@astryxdesign/cli/api',
+  signature: 'exportSearchIndex(options?: {cwd?: string, package?: string}): Promise<SearchIndex>',
+  keywords: ['search index', 'stored search index'],
+  params: [
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'The folder to gather from, read as `search()` reads it.',
+      default: 'process.cwd()',
+    },
+    {
+      name: 'options.package',
+      type: 'string',
+      description:
+        "Keep only the candidates this npm package owns: its components, templates, themes, and doc parts. Without it the index holds everything the folder's search ranks, Core's entries and the CLI's docs included.",
+    },
+  ],
+  returns: [
+    {
+      type: 'SearchIndex',
+      description:
+        '`version`, the CLI version that made it, and `candidates`, the gathered entries as plain JSON.',
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: '`package` is given and is not a non-empty string',
+    },
+  ],
+  examples: [
+    {
+      label: 'Index one installed integration',
+      code: "const index = await exportSearchIndex({cwd: '/tmp/harness', package: '@acme/ui'});",
+    },
+  ],
+  related: ['search', 'rankSearchIndex'],
+};