@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/api/search/_gather-docs.mjs

@@ -0,0 +1,254 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's doc candidates: every topic, section, and docs-tree node,
+ * with its titles, prose, and code terms. Imported only by the adapter.
+ */
+
+import {
+  guideEntry,
+  loadDocsCatalog,
+  lowerTopic,
+  projectTree,
+  holdsOwnName,
+} from '../docs/_adapter.mjs';
+import {nodeView} from '../docs/node/node.mjs';
+import {
+  sectionKey,
+  sectionSummary,
+} from '../../foundation/discovery/docs-section-key.mjs';
+import {sectionProse, codeTerms, headings, plain} from './_doc-text.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * Build doc candidates at the grain a reader reads them: each section of a
+ * topic, whose command reads just that section; each topic as a whole, whose
+ * command lists its sections; and each docs-tree node by its route. The tree's
+ * guides split into sections like topics, and its typed docs also match by
+ * their own name, so `assertResponse` finds `cli/api/functions/assert-response`.
+ *
+ * Reads the project's catalog rather than the CLI's own docs directory, so a
+ * topic an integration contributed (or replaced) is searchable exactly like a
+ * built-in one — otherwise the replacement is served by `astryx docs` but
+ * invisible to the command whose job is finding it.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export async function gatherDocs(cwd) {
+  /** @type {Candidate[]} */
+  const candidates = [];
+  let catalog;
+  try {
+    catalog = await loadDocsCatalog(cwd);
+  } catch {
+    return candidates;
+  }
+  let tree = null;
+  try {
+    tree = await projectTree(catalog);
+  } catch {
+    // `astryx doctor` reports a tree that fails to build; search still
+    // indexes the topics.
+  }
+  for (const entry of catalog.entries()) {
+    // A topic whose name opens another doc (spec:AST-046 FR11) is not
+    // offered: every hit's command must open the hit.
+    if (tree && !holdsOwnName(tree, catalog, entry)) continue;
+    let lowered = null;
+    try {
+      lowered = await lowerTopic(catalog, entry);
+    } catch {
+      // A topic that cannot be loaded is reported by the commands that own
+      // integration issues; search just cannot index it.
+    }
+    const doc = lowered?.doc ?? null;
+    // A flat topic lives in the Unorganized level; its hits say so, and name
+    // the package each section came from.
+    const home = tree?.get(entry.name);
+    const placed = home?.ref?.flatTopic === entry.name ? home : null;
+    /** @type {Map<string, string>} */
+    const packages = new Map([
+      [entry.providerId ?? entry.package, entry.package],
+      ...entry.extensions.map(
+        ext =>
+          /** @type {[string, string]} */ ([
+            ext.providerId ?? ext.package,
+            ext.package,
+          ]),
+      ),
+    ]);
+    candidates.push(
+      ...topicCandidates(
+        entry.name,
+        doc,
+        entry.title,
+        '',
+        placed && tree
+          ? [
+              ...tree.ancestors(placed).map(a => a.title),
+              doc?.title || entry.title || entry.name,
+            ].join(' › ')
+          : undefined,
+        placed ? `astryx docs ${placed.parent}` : undefined,
+        entry.package,
+        key =>
+          packages.get(lowered?.sectionProviders?.[key] ?? '') ?? entry.package,
+      ),
+    );
+  }
+  if (tree == null) return candidates;
+  for (const node of tree.nodes.values()) {
+    // A flat topic is indexed above, as a topic.
+    if (node.ref?.flatTopic) continue;
+    // A tree hit names where it lives: its ancestors' titles, then its own.
+    const path = [...tree.ancestors(node).map(a => a.title), node.title];
+    if (node.kind === 'generic') {
+      let doc = null;
+      try {
+        doc = (await lowerTopic(catalog, guideEntry(node))).doc;
+      } catch {
+        // As above: the owning commands report it.
+      }
+      candidates.push(
+        ...topicCandidates(
+          node.route,
+          doc,
+          node.title,
+          node.summary,
+          path.join(' › '),
+          node.parent == null ? undefined : `astryx docs ${node.parent}`,
+          node.provider,
+        ),
+      );
+      continue;
+    }
+    const selfDoc = /** @type {any} */ (node.ref)?.selfDoc;
+    // A typed doc's content is what `astryx docs <route>` prints. The first
+    // column of its tables names what the doc defines (an error code, an
+    // option, a parameter), so each is a keyword the doc answers to.
+    /** @type {any[]} */
+    const content = (await nodeView(catalog, tree, node)).content ?? [];
+    /** @type {string[]} */
+    const defined = [];
+    for (const block of content) {
+      if (block.type !== 'table' || !Array.isArray(block.rows)) continue;
+      for (const row of block.rows)
+        if (row[0] != null) defined.push(plain(row[0]));
+    }
+    candidates.push({
+      domain: 'doc',
+      name: node.name,
+      keywords: [
+        node.route.slice(node.route.lastIndexOf('/') + 1),
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        // A namespace doc's own keywords, which it declares for search.
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+        ...defined,
+        ...codeTerms({content}),
+      ],
+      _declared: [
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+      ],
+      description: node.summary || '',
+      prose: sectionProse({title: node.title, content}),
+      titles: [node.title],
+      _topic: node.route,
+      _title: path.join(' › '),
+      _command: `astryx docs ${node.route}`,
+      _parent:
+        node.parent == null ? 'astryx docs' : `astryx docs ${node.parent}`,
+      _package: node.provider,
+    });
+  }
+  return candidates;
+}
+
+/**
+ * The candidates one topic yields: the topic itself, and one per section when
+ * it has more than one. A topic's command lists its sections, and a section's
+ * command reads only that section, so a hit never costs a whole-topic read.
+ * @param {string} name - the topic name, or a placed guide's route
+ * @param {any} doc - the lowered topic, or null when it did not load
+ * @param {string} [title]
+ * @param {string} [summary]
+ * @param {string} [path] - where the topic lives in the docs tree, as titles
+ *   joined by ` › `; a flat topic is its own title
+ * @param {string} [parent] - the command that opens the level above the
+ *   topic: its namespace, or the Unorganized level for a flat topic
+ * @param {string} [pkg] - the npm package that authored the topic
+ * @param {(key: string) => string} [sectionPackage] - the npm package a
+ *   section came from: an extension's section names the extension's package
+ * @returns {Candidate[]}
+ */
+function topicCandidates(
+  name,
+  doc,
+  title,
+  summary = '',
+  path,
+  parent,
+  pkg,
+  sectionPackage,
+) {
+  /** @type {any[]} */
+  const sections = doc?.sections ?? [];
+  const docTitle = path || doc?.title || title || name;
+  const split = sections.length > 1;
+  // A placed guide also answers to its last route segment's words:
+  // `quick start` is cli/integrations/quick-start.
+  const leaf = name.slice(name.lastIndexOf('/') + 1);
+  /** @type {Candidate[]} */
+  const out = [
+    {
+      domain: 'doc',
+      name,
+      keywords: [
+        ...(leaf !== name ? [leaf.replaceAll('-', ' ')] : []),
+        ...(doc?.title || title ? [doc?.title || title] : []),
+        ...(Array.isArray(doc?.keywords) ? doc.keywords : []),
+      ],
+      _declared: Array.isArray(doc?.keywords) ? doc.keywords : [],
+      description: doc?.description || summary,
+      prose: split
+        ? sections.map(section => section.title).filter(Boolean)
+        : sections.flatMap(sectionProse),
+      titles: [
+        doc?.title || title || name,
+        // A topic read whole answers for the headings inside it.
+        ...(split ? [] : sections.flatMap(s => [s.title, ...headings(s)])),
+      ].filter(Boolean),
+      _topic: name,
+      _title: docTitle,
+      _command: split ? `astryx docs ${name} --index` : `astryx docs ${name}`,
+      ...(parent ? {_parent: parent} : {}),
+      ...(pkg ? {_package: pkg} : {}),
+    },
+  ];
+  if (!split) return out;
+  for (const section of sections) {
+    const key = sectionKey(section);
+    out.push({
+      domain: 'doc',
+      name: key,
+      keywords: [
+        ...(section.title ? [section.title] : []),
+        ...headings(section),
+        ...codeTerms(section),
+      ],
+      description: sectionSummary(section),
+      prose: sectionProse(section),
+      titles: [section.title, ...headings(section)].filter(Boolean),
+      _topic: name,
+      _section: key,
+      _title: `${docTitle} › ${section.title}`,
+      _command: `astryx docs ${name} ${key}`,
+      _parent: `astryx docs ${name} --index`,
+      ...((sectionPackage?.(key) ?? pkg)
+        ? {_package: sectionPackage?.(key) ?? pkg}
+        : {}),
+    });
+  }
+  return out;
+}

package/api/search/_gather-hooks.d.mts

@@ -0,0 +1,12 @@
+// @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('./_lexical.mjs').Candidate} Candidate */
+/**
+ * Build hook candidates: name + keywords + usage/description from the hook's
+ * .doc.mjs.
+ * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
+ */
+export function gatherHooks(coreDir: string): Promise<Candidate[]>;
+export type Candidate = import("./_lexical.mjs").Candidate;

package/api/search/_gather-hooks.mjs

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's hook candidates, read from Core's hook docs. Imported only
+ * by the adapter.
+ */
+
+import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../foundation/discovery/hook-discovery.mjs';
+import {loadModuleDoc} from './_module-doc.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * Build hook candidates: name + keywords + usage/description from the hook's
+ * .doc.mjs.
+ * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
+ */
+export async function gatherHooks(coreDir) {
+  const grouped = discoverHooks(coreDir);
+  const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
+  const candidates = [];
+  for (const hookName of names) {
+    const docPath = findHookDoc(coreDir, hookName);
+    /** @type {string[]} */
+    let keywords = [];
+    let description = '';
+    let importPath = '@astryxdesign/core/hooks';
+    if (docPath) {
+      const doc = await loadModuleDoc(docPath, 'docs', 'hooks');
+      if (doc) {
+        keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
+        description = doc.usage?.description || doc.description || '';
+        importPath = doc.importPath || importPath;
+      }
+    }
+    candidates.push({
+      domain: 'hook',
+      name: hookName,
+      keywords,
+      description,
+      _package: CORE_PACKAGE,
+      _import: importPath,
+    });
+  }
+  return candidates;
+}

package/api/search/_gather-templates.d.mts

@@ -0,0 +1,25 @@
+// @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('./_lexical.mjs').Candidate} Candidate */
+/**
+ * Build template candidates (page + block) from the template discovery API.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export function gatherTemplates(cwd: string): Promise<Candidate[]>;
+/**
+ * Build theme candidates from bundled and integration-provided themes. Without
+ * this, an integration's themes are invisible to `search` even though
+ * `theme list` and `discover` already resolve them.
+ *
+ * A theme's slug and display name are its names, and its description is prose
+ * (`spec:AST-050/FR14`). A theme declares no keywords, so a word it shares with
+ * the query only through its description is a description mention: read as a
+ * keyword, every word of the description would outrank the components and docs
+ * that declare that word.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export function gatherThemes(cwd: string): Promise<Candidate[]>;
+export type Candidate = import("./_lexical.mjs").Candidate;

package/api/search/_gather-templates.mjs

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's template and theme candidates. Imported only by the adapter.
+ */
+
+import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {discoverTemplates, extractComponents} from '../template/template.mjs';
+import {listAvailableThemes} from '../theme/_adapter.mjs';
+import {templateLookupIds} from '../../foundation/discovery/template-adapter.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * Build template candidates (page + block) from the template discovery API.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export async function gatherTemplates(cwd) {
+  let templates;
+  try {
+    templates = await discoverTemplates(cwd);
+  } catch {
+    return [];
+  }
+  return templates.map(t => {
+    // A replacement's target is its canonical unqualified lookup id. Keep the
+    // integration-owned id as a keyword and response label, but score and print
+    // commands against the id that `template()` resolves back to this entry.
+    // This matters for replacement chains: one replacement's own id can be the
+    // target of another, so using that shadowed id as the command would select
+    // the other template.
+    const commandName = t.replaces ?? t.dirName;
+    // Blocks ship an authored componentsUsed; page templates don't, so derive
+    // them from the source. Category words (e.g. "Dashboard - Analytics") are
+    // strong intent signal for pages, which otherwise only index on name +
+    // description.
+    //
+    // Authored signal and derived signal are kept apart: componentsUsed and
+    // category words are a deliberate statement of what the template is for,
+    // while scraped JSX tags only say what it happens to render. See the
+    // scoring table at the top of this file for why the derived set is capped.
+    const keywords = Array.isArray(t.componentsUsed)
+      ? [...t.componentsUsed]
+      : [];
+    keywords.push(...templateLookupIds(t).filter(id => id !== commandName));
+    /** @type {string[]} */
+    let weakKeywords = [];
+    if (t.type === 'page') {
+      if (t.filePath) {
+        try {
+          weakKeywords = extractComponents(t.filePath);
+        } catch {
+          // Best-effort: skip keyword enrichment if the source can't be read.
+        }
+      }
+      if (t.category)
+        keywords.push(...t.category.split(/[^A-Za-z0-9]+/).filter(Boolean));
+    }
+    return {
+      domain: 'template',
+      name: commandName,
+      keywords,
+      weakKeywords,
+      description: t.description || '',
+      // A template's own keywords name the many ideas it serves, so they score
+      // as its prose does, not as a name: one of them matching one word of a
+      // short idea is not a direct match.
+      prose: t.keywords ?? [],
+      _displayName: t.name,
+      _package: t.package ?? CORE_PACKAGE,
+      _kind: t.type, // 'page' | 'block'
+      _resultName: t.dirName,
+      _commandName: commandName,
+    };
+  });
+}
+
+/**
+ * Build theme candidates from bundled and integration-provided themes. Without
+ * this, an integration's themes are invisible to `search` even though
+ * `theme list` and `discover` already resolve them.
+ *
+ * A theme's slug and display name are its names, and its description is prose
+ * (`spec:AST-050/FR14`). A theme declares no keywords, so a word it shares with
+ * the query only through its description is a description mention: read as a
+ * keyword, every word of the description would outrank the components and docs
+ * that declare that word.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export async function gatherThemes(cwd) {
+  let themes;
+  try {
+    themes = await listAvailableThemes(cwd);
+  } catch {
+    return [];
+  }
+  return themes.map(t => ({
+    domain: 'theme',
+    name: t.slug,
+    aliases: t.displayName ? [t.displayName] : [],
+    description: t.description || '',
+    _displayName: t.displayName,
+    _package: t.package,
+  }));
+}

package/api/search/_lexical.d.mts

@@ -0,0 +1,135 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A search candidate gathered from one content domain. Extra underscore-
+ * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ * @typedef {object} Candidate
+ * @property {'component'|'hook'|'doc'|'template'|'theme'} domain
+ * @property {string} name
+ * @property {string[]} [aliases] - Other names the candidate answers to, scored
+ *   with the same name signals: a theme's display name.
+ * @property {string[]} [keywords]
+ * @property {string[]} [_declared] - A doc's own declared keywords: what its
+ *   author lists in `keywords`, without the code terms and table cells its
+ *   other keywords add.
+ * @property {string[]} [weakKeywords]
+ * @property {string} [description]
+ * @property {string[]} [prose]
+ * @property {string[]} [guidance]
+ * @property {string[]} [titles] - A doc's title and the headings inside it:
+ *   the lines a reader scans to pick it. The whole query standing in one of
+ *   them, or one of them standing whole in the query, is a top-tier match.
+ * @property {string} [_import]
+ * @property {string} [_title]
+ * @property {string} [_topic] - A doc result's topic or docs-tree route.
+ * @property {string} [_section] - A doc result's section key, when it is one section.
+ * @property {string} [_command] - The command that reads exactly this doc part.
+ * @property {string} [_parent] - The command that opens the level above a doc
+ *   part: its topic's section list, or the docs-tree namespace it sits in.
+ * @property {string} [_package] - The npm package that owns the candidate:
+ *   Core's package for its components, hooks, and templates, the integration's
+ *   for what it contributed, and for a doc part the package that wrote it.
+ * @property {string} [_displayName]
+ * @property {'page'|'block'} [_kind]
+ * @property {string} [_resultName]
+ * @property {string} [_commandName]
+ * @property {'file'|'doc'} [_hold] - How an integration component holds its
+ *   name, for the owner rule.
+ * @property {string} [_docPath] - An integration component's doc.
+ */
+/**
+ * True when the query is the candidate's whole name or another name of it,
+ * typed as is or, for anything but a doc, with its spaces removed. Such a
+ * query names that entry outright.
+ * @param {Candidate} candidate
+ * @param {string} term the query, trimmed and lowercased
+ * @returns {boolean}
+ */
+export function namesWhole(candidate: Candidate, term: string): boolean;
+/**
+ * Today's lexical ranking of a gathered catalog: the search response
+ * `searchCore` returns.
+ *
+ * @param {string} query
+ * @param {{limit?: number}} options
+ * @param {{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside?: boolean, coreSkipped?: string | null}} catalog
+ * @returns {import('./search.type.mjs').SearchResponse}
+ */
+export function rankLexical(query: string, options: {
+    limit?: number;
+}, catalog: {
+    all: Candidate[];
+    components: Candidate[];
+    searchedComponents: boolean;
+    outside?: boolean;
+    coreSkipped?: string | null;
+}): import("./search.type.mjs").SearchResponse;
+/**
+ * A search candidate gathered from one content domain. Extra underscore-
+ * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ */
+export type Candidate = {
+    domain: "component" | "hook" | "doc" | "template" | "theme";
+    name: string;
+    /**
+     * - Other names the candidate answers to, scored
+     * with the same name signals: a theme's display name.
+     */
+    aliases?: string[] | undefined;
+    keywords?: string[] | undefined;
+    /**
+     * - A doc's own declared keywords: what its
+     * author lists in `keywords`, without the code terms and table cells its
+     * other keywords add.
+     */
+    _declared?: string[] | undefined;
+    weakKeywords?: string[] | undefined;
+    description?: string | undefined;
+    prose?: string[] | undefined;
+    guidance?: string[] | undefined;
+    /**
+     * - A doc's title and the headings inside it:
+     * the lines a reader scans to pick it. The whole query standing in one of
+     * them, or one of them standing whole in the query, is a top-tier match.
+     */
+    titles?: string[] | undefined;
+    _import?: string | undefined;
+    _title?: string | undefined;
+    /**
+     * - A doc result's topic or docs-tree route.
+     */
+    _topic?: string | undefined;
+    /**
+     * - A doc result's section key, when it is one section.
+     */
+    _section?: string | undefined;
+    /**
+     * - The command that reads exactly this doc part.
+     */
+    _command?: string | undefined;
+    /**
+     * - The command that opens the level above a doc
+     * part: its topic's section list, or the docs-tree namespace it sits in.
+     */
+    _parent?: string | undefined;
+    /**
+     * - The npm package that owns the candidate:
+     * Core's package for its components, hooks, and templates, the integration's
+     * for what it contributed, and for a doc part the package that wrote it.
+     */
+    _package?: string | undefined;
+    _displayName?: string | undefined;
+    _kind?: "page" | "block" | undefined;
+    _resultName?: string | undefined;
+    _commandName?: string | undefined;
+    /**
+     * - How an integration component holds its
+     * name, for the owner rule.
+     */
+    _hold?: "file" | "doc" | undefined;
+    /**
+     * - An integration component's doc.
+     */
+    _docPath?: string | undefined;
+};