Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file A stored search index: the candidates `search` gathers in a folder, as
 * plain JSON, and the ranking of stored candidates with search's own tree.
 *
 * Gathering reads every package's docs and loads its manifest, which runs the
 * package's code. A catalog that lists packages it must not load (a web page
 * that lists every published integration) stores each package's index once,
 * where loading is safe, and ranks the stored indexes per query.
 * @position api/search; search.mjs is the folder-reading search.
 */

import {
  docPackageManager,
  runWithDocPackageManager,
} from '../../foundation/env/package-manager.mjs';
import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
import {cliVersion} from '../../foundation/release/run-context.mjs';
import {runTree} from '../../foundation/route/route.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {linkSearchResponse} from '../component/_adapter.mjs';
import {AstryxError} from '../error.mjs';
import {
  gatherCandidates,
  loadSearchData,
  resolveSearchCore,
} from './_adapter.mjs';
import {checkSearchArgs} from './_result.mjs';
import {SEARCH_TREE} from './tree.mjs';

/**
 * Fields a gathered candidate holds that point into the folder it was read
 * from. They decide ownership while gathering and never rank, so an index
 * leaves them out and reads the same wherever it was made.
 */
const LOCAL_FIELDS = ['_docPath'];

/**
 * A component candidate's description as `search` prints it: its inline
 * `{@link}`, `{@pm}` and `{@command}` tokens resolved in the folder the index
 * is made in. The raw description stays the one that is scored.
 */
const DISPLAY_FIELD = '_displayDescription';

/** Stands for the Core the indexes were made with, which ranking never reads. */
const STORED_CORE = 'stored-index';

/**
 * @param {Record<string, unknown>} candidate
 * @returns {Record<string, unknown>}
 */
function portable(candidate) {
  /** @type {Record<string, unknown>} */
  const out = JSON.parse(JSON.stringify(candidate));
  for (const field of LOCAL_FIELDS) delete out[field];
  return out;
}

/**
 * The candidates `search` ranks in a folder, as plain JSON: store it, and rank
 * it later with {@link rankSearchIndex}.
 *
 * Experimental (spec:AST-017 FR27): may change or be removed in a patch
 * release.
 * @experimental
 * @param {object} [options]
 * @param {string} [options.cwd] - The folder to gather from, as `search` reads it.
 * @param {string} [options.package] - Keep only the candidates this npm package
 *   owns (its components, templates, themes, and doc parts).
 * @returns {Promise<import('./search.type.mjs').SearchIndex>}
 */
export async function exportSearchIndex(options = {}) {
  const {cwd = process.cwd(), package: owner} = options;
  if (owner != null && (typeof owner !== 'string' || owner.trim() === '')) {
    throw new AstryxError(
      `Invalid package "${owner}". Pass an npm package name.`,
      undefined,
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
  return runWithDocPackageManager(docPackageManager(cwd), () =>
    withListingCache(async () => {
      const gathered = await gatherCandidates({cwd});
      const kept =
        owner == null
          ? gathered.all
          : gathered.all.filter(candidate => candidate._package === owner);
      const candidates = kept.map(candidate =>
        portable(/** @type {Record<string, unknown>} */ (candidate)),
      );
      await addDisplayDescriptions(candidates, cwd);
      return {
        version: cliVersion(),
        candidates,
        ...(gathered.coreSkipped == null
          ? {}
          : {
              coreSkipped: gathered.coreSkipped,
              ...(gathered.coreSkippedCode == null
                ? {}
                : {coreSkippedCode: gathered.coreSkippedCode}),
            }),
      };
    }),
  );
}

/**
 * Resolves each component description's inline tokens as `search` does for
 * the results it prints, and keeps the printed text beside the scored one.
 * @param {Record<string, unknown>[]} candidates
 * @param {string} cwd
 */
async function addDisplayDescriptions(candidates, cwd) {
  const linkable = candidates.filter(
    candidate =>
      candidate.domain === 'component' &&
      typeof candidate.description === 'string' &&
      candidate.description.includes('{@'),
  );
  if (linkable.length === 0) return;
  const response = await linkSearchResponse(
    /** @type {any} */ ({
      type: 'search',
      data: {
        results: linkable.map(candidate => ({
          domain: 'component',
          package: candidate._package,
          description: candidate.description,
        })),
      },
    }),
    cwd,
  );
  response.data.results.forEach(
    (/** @type {any} */ result, /** @type {number} */ i) => {
      if (result.description !== linkable[i].description)
        linkable[i][DISPLAY_FIELD] = result.description;
    },
  );
}

/**
 * Ranks stored indexes with search's tree. An index made in one folder answers
 * as `search(query)` does there (a theme result's command is the in-project
 * `theme add`). Indexes made in separate folders, such as one per package
 * (made with `package`) and one for Core, are ranked together as one list; a
 * doc that one package replaces or extends in another is not merged across
 * them. Every index must come from this CLI's version, since the tree reads
 * the candidates' shape. When every index was made where Core could not be
 * had, the answer carries `meta.partial`, as `search` does.
 *
 * Experimental (spec:AST-017 FR27): may change or be removed in a patch
 * release.
 * @experimental
 * @param {string} query - Free-text search term.
 * @param {import('./search.type.mjs').SearchIndex | import('./search.type.mjs').SearchIndex[]} indexes
 * @param {object} [options]
 * @param {import('./search.type.mjs').SearchDomain} [options.type] - Restrict to one domain.
 * @param {number} [options.limit] - Max results (default 20).
 * @returns {Promise<import('./search.type.mjs').SearchResponse>}
 */
export async function rankSearchIndex(query, indexes, options = {}) {
  checkSearchArgs(query, options);
  const list = Array.isArray(indexes) ? indexes : [indexes];
  const version = cliVersion();
  /** @type {any[]} */
  const all = [];
  for (const index of list) {
    if (index == null || !Array.isArray(index.candidates)) {
      throw new AstryxError(
        'A search index is {version, candidates}, as exportSearchIndex() returns it.',
        undefined,
        ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
    if (index.version !== version) {
      throw new AstryxError(
        `This search index was made by CLI ${index.version}; this is CLI ${version}. Make it again with this version's exportSearchIndex().`,
        undefined,
        ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
    all.push(...index.candidates);
  }
  const {type} = options;
  const wanted =
    type == null ? all : all.filter(candidate => candidate.domain === type);
  const {searchedComponents, coreSkipped} = coreFlags(list, type);
  const response = /** @type {import('./search.type.mjs').SearchResponse} */ (
    await runTree(
      SEARCH_TREE,
      {query, options: {type, limit: options.limit}},
      {
        all: wanted,
        components: wanted.filter(
          candidate => candidate.domain === 'component',
        ),
        searchedComponents,
        outside: false,
        coreSkipped,
        coreSkippedCode: null,
        data: loadSearchData(),
      },
    )
  );
  return withDisplayDescriptions(response, wanted);
}

/**
 * The catalog flags `search` derives from Core for a request of `type`, by
 * search's own rule (`resolveSearchCore`). Core is missing only when no index
 * had it. An open search then names what it skipped. A docs or themes search
 * never reads Core. A Core domain asked for by name throws the error that
 * `search` throws.
 * @param {import('./search.type.mjs').SearchIndex[]} list
 * @param {import('./search.type.mjs').SearchDomain | undefined} type
 * @returns {{searchedComponents: boolean, coreSkipped: string | null}}
 */
function coreFlags(list, type) {
  const missing =
    list.length > 0 &&
    list.every(index => typeof index.coreSkipped === 'string');
  const lookup = () => {
    if (!missing) return STORED_CORE;
    throw Object.assign(
      new Error(/** @type {string} */ (list[0].coreSkipped)),
      {
        code: list[0].coreSkippedCode ?? ERROR_CODES.ERR_CORE_NOT_FOUND,
      },
    );
  };
  const {coreSkipped, wants} = resolveSearchCore(type, lookup, STORED_CORE);
  return {searchedComponents: wants('component'), coreSkipped};
}

/**
 * The response with each component result's description as `search` prints
 * it, from the text the index stored when it was made.
 * @param {import('./search.type.mjs').SearchResponse} response
 * @param {any[]} candidates
 * @returns {import('./search.type.mjs').SearchResponse}
 */
function withDisplayDescriptions(response, candidates) {
  /** @type {Map<string, string>} */
  const display = new Map();
  for (const candidate of candidates) {
    if (
      candidate.domain === 'component' &&
      typeof candidate[DISPLAY_FIELD] === 'string'
    )
      display.set(
        `${candidate._package}\u0000${candidate._resultName ?? candidate.name}`,
        candidate[DISPLAY_FIELD],
      );
  }
  if (display.size === 0) return response;
  return {
    ...response,
    data: {
      ...response.data,
      results: response.data.results.map(result => {
        if (result.domain !== 'component') return result;
        const text = display.get(`${result.package}\u0000${result.name}`);
        return text == null ? result : {...result, description: text};
      }),
    },
  };
}