@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/api/search/_gather-components.mjs

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's component candidates: Core's components and the ones
+ * integrations contribute, read from their docs. Imported only by the adapter.
+ */
+
+import {discoverExternalPackages} from '../../foundation/fs/paths.mjs';
+import {
+  discoverComponents,
+  discoverValidIntegrationComponents,
+  docStem,
+  familyMember,
+  findComponentReadme,
+  forEachIntegrationDoc,
+  integrationMemberEntry,
+  integrationRecordHold,
+  isIntegrationMember,
+  resolveImportPath,
+  resolveIntegrationImportPath,
+  CORE_PACKAGE,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  loadComponentReplacements,
+  loadIntegrationsSafely,
+  resolveLegacyExternalDoc,
+} from '../component/_adapter.mjs';
+import {loadModuleDoc, guidanceFrom} from './_module-doc.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
+ * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherCoreComponents(coreDir) {
+  const grouped = discoverComponents(coreDir);
+  const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
+  const candidates = [];
+  for (const comp of names) {
+    const readme = findComponentReadme(coreDir, comp);
+    /** @type {string[]} */
+    let keywords = [];
+    let description = '';
+    /** @type {string[]} */
+    let guidance = [];
+    if (readme && readme.endsWith('.doc.mjs')) {
+      const loaded = await loadModuleDoc(readme);
+      // A member documented in its family's doc (VStack in Stack's doc) is
+      // indexed from its own entry: the family's keywords and guidance
+      // describe the family, not the member.
+      const doc = familyMember(loaded, comp) ?? loaded;
+      if (doc) {
+        keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
+        description = doc.usage?.description || doc.description || '';
+        guidance = guidanceFrom(doc);
+      }
+    }
+    candidates.push({
+      domain: 'component',
+      name: comp,
+      keywords,
+      description,
+      guidance,
+      _package: CORE_PACKAGE,
+      _import: resolveImportPath(coreDir, comp),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Build component candidates contributed by the project's configured
+ * integrations (astryx.config's `integrations`): name + keywords +
+ * usage/description from each component's .doc.mjs, same as core. Without
+ * this, an integration component is invisible to `search`/`build` even
+ * though `component --list`/`component <Name>` already resolve it — the two
+ * discovery paths silently disagreed. Also returns, per name, the docs that
+ * hold it by their file name and the loadable docs that only record it.
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @returns {Promise<{candidates: Candidate[], fileNamed: Map<string, Set<string>>, documented: Map<string, Set<string>>}>}
+ */
+async function gatherIntegrationComponents(loadedIntegrations) {
+  /** @type {Candidate[]} */
+  const candidates = [];
+  // What the owner rule reads: the docs that hold a name by their file name,
+  // loadable or not and hidden ones too, and the loadable docs that only
+  // record it.
+  /** @type {Map<string, Set<string>>} */
+  const fileNamed = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const documented = new Map();
+  /** @param {Map<string, Set<string>>} map @param {string} name @param {string} docPath */
+  const hold = (map, name, docPath) =>
+    map.set(name, (map.get(name) ?? new Set()).add(docPath));
+  for (const integration of loadedIntegrations) {
+    const {components, discovered} =
+      await discoverValidIntegrationComponents(integration);
+    const renamed = new Set(
+      discovered
+        .filter(rec => integrationRecordHold(rec) === 'doc')
+        .filter(rec => !isIntegrationMember(rec))
+        .map(rec => rec.docPath),
+    );
+    forEachIntegrationDoc(integration.components, (docPath, stem) => {
+      if (!renamed.has(docPath)) hold(fileNamed, stem, docPath);
+    });
+    for (const rec of components) {
+      const loaded = await loadModuleDoc(rec.docPath);
+      // A family member is indexed from its own entry: the family's keywords
+      // and guidance describe the family.
+      const member = isIntegrationMember(rec);
+      const doc = member ? integrationMemberEntry(loaded, rec) : loaded;
+      // A doc that names another export of its file still answers to the
+      // file's name, as `component <file name>` does.
+      const fileName = docStem(rec.docPath);
+      if (integrationRecordHold(rec) === 'doc') {
+        hold(documented, rec.name, rec.docPath);
+      }
+      if (renamed.has(rec.docPath) && !member) {
+        hold(documented, fileName, rec.docPath);
+      }
+      candidates.push({
+        domain: 'component',
+        name: rec.name,
+        aliases: !member && fileName !== rec.name ? [fileName] : [],
+        _hold: integrationRecordHold(rec),
+        _docPath: rec.docPath,
+        keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
+        description: doc ? doc.usage?.description || doc.description || '' : '',
+        guidance: guidanceFrom(doc),
+        _package: rec.package ?? integration.name,
+        // Exactly what `component` reports: a doc may state its own specifier
+        // (one entry point exporting several components), and only when it
+        // does not do we resolve the subpath against the owning package's
+        // exports — read off the integration, which the loader already parsed.
+        // Reporting the bare package name here handed out a path that does not
+        // resolve, and disagreed with what `component <Name>` said about the
+        // very same component.
+        _import: resolveIntegrationImportPath(
+          {
+            exportsMap: integration.__packageExports,
+            packageDir: integration.__packageDir,
+            docPath: rec.docPath,
+            packageName: rec.package,
+          },
+          rec.name,
+          loaded?.import,
+        ),
+      });
+    }
+  }
+  return {candidates, fileNamed, documented};
+}
+
+/**
+ * Build component candidates: core's own tree plus every configured
+ * integration's components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+export async function gatherComponents(coreDir, cwd) {
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  const [core, gathered, replacements] = await Promise.all([
+    gatherCoreComponents(coreDir),
+    gatherIntegrationComponents(loadedIntegrations),
+    loadComponentReplacements(coreDir, loadedIntegrations),
+  ]);
+  const {candidates: integrations, fileNamed, documented} = gathered;
+  // An active replacement answers to the Core name it replaces, so a search
+  // for that name finds the replacement and not the Core original
+  // (spec:AST-035 FR11).
+  /** @type {Map<string, string>} */
+  const targetOf = new Map(
+    replacements.active.map(active => [
+      `${active.package}\0${active.name}`,
+      active.target,
+    ]),
+  );
+  // The owner rule, as component detail applies it: a candidate `component
+  // <name>` does not open names its package and follows the owner, and a
+  // file-name alias that opens another owner is dropped.
+  const coreNames = new Set(core.map(candidate => candidate.name));
+  /** @param {string} name @param {Candidate} candidate */
+  const opens = (name, candidate) =>
+    !coreNames.has(name) &&
+    findComponentReadme(coreDir, name) == null &&
+    [...(fileNamed.get(name) ?? [])].every(doc => doc === candidate._docPath) &&
+    [...(documented.get(name) ?? [])].every(doc => doc === candidate._docPath);
+  // A legacy docs package keeps an exact name over an export name a doc records.
+  /** @type {ReturnType<typeof discoverExternalPackages> | undefined} */
+  let externals;
+  /** @param {string} name */
+  const legacyDocuments = name =>
+    (externals ??= discoverExternalPackages(cwd)).some(
+      ext => resolveLegacyExternalDoc(ext, name) != null,
+    );
+  const ruled = integrations.map(candidate => {
+    const aliases = (candidate.aliases ?? []).filter(alias =>
+      opens(alias, candidate),
+    );
+    return candidate._hold === 'doc' &&
+      (!opens(candidate.name, candidate) || legacyDocuments(candidate.name))
+      ? {
+          ...candidate,
+          aliases,
+          _command: `astryx component ${candidate.name} --package ${candidate._package}`,
+        }
+      : {...candidate, aliases};
+  });
+  return [
+    ...core.filter(candidate => !replacements.forTarget(candidate.name)),
+    ...[
+      ...ruled.filter(candidate => !candidate._command),
+      ...ruled.filter(candidate => candidate._command),
+    ].map(candidate => {
+      const target = targetOf.get(`${candidate._package}\0${candidate.name}`);
+      if (target != null) {
+        return {...candidate, aliases: [...(candidate.aliases ?? []), target]};
+      }
+      // Another package's component named after a replaced Core component is
+      // shadowed for the bare name (FR14): its command names its package.
+      const shadowedBy = replacements.forTarget(candidate.name);
+      return shadowedBy && shadowedBy.package !== candidate._package
+        ? {
+            ...candidate,
+            _command: `astryx component ${candidate.name} --package ${candidate._package}`,
+          }
+        : candidate;
+    }),
+  ];
+}
+
+/**
+ * Every component the project can use, Core's and its integrations', with the
+ * keywords its own doc declares: the discovery and doc reads search's own
+ * candidates use, without the import paths and prose a result carries. `build`
+ * reads it to tell a part of a page from a page when its search was narrowed
+ * away from components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<{name: string, keywords: string[]}[]>}
+ */
+export async function componentKeywords(coreDir, cwd) {
+  /** @param {any} doc */
+  const keywordsOf = doc => (Array.isArray(doc?.keywords) ? doc.keywords : []);
+  const core = Object.values(discoverComponents(coreDir))
+    .flat()
+    .map(async name => {
+      const readme = findComponentReadme(coreDir, name);
+      const loaded =
+        readme && readme.endsWith('.doc.mjs')
+          ? await loadModuleDoc(readme)
+          : null;
+      return {name, keywords: keywordsOf(familyMember(loaded, name) ?? loaded)};
+    });
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  const replacements = await loadComponentReplacements(
+    coreDir,
+    loadedIntegrations,
+  );
+  const integrations = loadedIntegrations.map(async integration => {
+    const {components} = await discoverValidIntegrationComponents(integration);
+    return Promise.all(
+      components.map(async rec => {
+        const loaded = await loadModuleDoc(rec.docPath);
+        return {
+          name: rec.name,
+          keywords: keywordsOf(integrationMemberEntry(loaded, rec) ?? loaded),
+        };
+      }),
+    );
+  });
+  return [
+    ...(await Promise.all(core)).filter(
+      component => !replacements.forTarget(component.name),
+    ),
+    ...(await Promise.all(integrations)).flat(),
+  ];
+}

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

@@ -0,0 +1,20 @@
+// @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 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 function gatherDocs(cwd: string): Promise<Candidate[]>;
+export type Candidate = import("./_lexical.mjs").Candidate;

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 its topic 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 topic 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 authoring/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;