Skip to content

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

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

/**
 * @file Programmatic API for the discover command — dispatcher + barrel.
 *
 * `discover()` browses the integrations a project has and, through discover
 * sources and the official list the CLI carries, the ones it could add. It
 * only reads: the package manager installs.
 * Its job is to resolve the project and its sources (via ./_adapter) and route
 * to the leaf that owns each response shape:
 *
 *   discover                         -> ./list/list.mjs        discover.list
 *   discover <package>[@<version>]   -> ./detail/detail.mjs    discover.detail
 *   discover <package>/<Component>   -> ./detail/doc/doc.mjs   discover.detail.doc
 *   discover <package>/<item>        -> ./detail/item/item.mjs discover.item
 *   discover <words>                 -> ./search/search.mjs    discover.search (always a list)
 *
 * Source results are additive: they ride in `meta.available`/`meta.sources`,
 * in extra fields, or as extra search matches, so every existing field keeps
 * its meaning.
 *
 * @position api/discover — thin router over ./_adapter, ./_catalog-view, and
 *   the discover leaves.
 */

export {OFFICIAL_SOURCE_NAME} from './_adapter.mjs';
import {
  addCommand,
  callSources,
  computerAvailableEntries,
  declaredDependencies,
  describeInstalled,
  discoverPackages,
  findComponent,
  hasSources,
  loadReadKinds,
  officialDeclarations,
  STABLE_KINDS,
  officialFirst,
  officialList,
  withDeclaredOfficial,
} from './_adapter.mjs';
import {
  availableEntries,
  catalogState,
  searchItems,
  withLatest,
} from './_catalog-view.mjs';
import {list} from './list/list.mjs';
import {detail} from './detail/detail.mjs';
import {doc, docFromResult} from './detail/doc/doc.mjs';
import {item} from './detail/item/item.mjs';
import {search} from './search/search.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';

const DEFAULT_LIMIT = 20;

/**
 * Split a package-shaped query: `name`, `name@version`, or `name/item`, with an
 * optional `@scope/` prefix on the name.
 * @param {string} query
 * @returns {{scoped: boolean, name: string, version?: string, item?: string}}
 */
function splitTarget(query) {
  const scoped = query.startsWith('@');
  const firstSlash = query.indexOf('/');
  let head = query;
  /** @type {string | undefined} */
  let rest;
  const split = scoped
    ? firstSlash < 0
      ? -1
      : query.indexOf('/', firstSlash + 1)
    : firstSlash;
  if (split > 0) {
    head = query.slice(0, split);
    rest = query.slice(split + 1) || undefined;
  }
  const at = head.indexOf('@', 1);
  return {
    scoped,
    name: at > 0 ? head.slice(0, at) : head,
    ...(at > 0 && head.slice(at + 1) ? {version: head.slice(at + 1)} : {}),
    ...(rest ? {item: rest} : {}),
  };
}

/**
 * @param {{type?: unknown, installed?: boolean, available?: boolean, limit?: unknown}} options
 * @param {readonly string[]} kinds the item kinds this project reads
 */
function checkOptions({type, installed, available, limit}, kinds) {
  if (type != null && !kinds.includes(/** @type {string} */ (type))) {
    throw new AstryxError(
      `Unknown --type "${String(type)}"`,
      kinds.map(kind => ({name: kind, reason: 'item kind'})),
      ERROR_CODES.ERR_INVALID_OPTION,
    );
  }
  if (installed && available) {
    throw new AstryxError(
      '--installed and --available cannot be used together',
      undefined,
      ERROR_CODES.ERR_INVALID_OPTION,
    );
  }
  if (
    limit != null &&
    !(typeof limit === 'number' && Number.isInteger(limit) && limit > 0)
  ) {
    throw new AstryxError(
      `--limit must be a positive integer, not "${String(limit)}"`,
      undefined,
      ERROR_CODES.ERR_INVALID_OPTION,
    );
  }
}

/**
 * Items a source lists for a package that look like the one asked for: names
 * that contain it, else the closest few by spelling.
 * @param {import('../../authoring/discover/type.js').DiscoverPackage} entry
 * @param {string} wanted
 * @returns {Array<{name: string, reason: string}>}
 */
function similarItems(entry, wanted) {
  const lower = wanted.toLowerCase();
  const names = [...new Set(entry.contributions.map(c => c.name))];
  const hits = names.filter(name => name.toLowerCase().includes(lower));
  const picked =
    hits.length > 0
      ? hits.slice(0, 5)
      : names
          .map(name => ({
            name,
            distance: levenshteinDistance(lower, name.toLowerCase()),
          }))
          .filter(m => m.distance <= 3)
          .sort((a, b) => a.distance - b.distance)
          .slice(0, 5)
          .map(m => m.name);
  return picked.map(name => ({
    name: `${entry.package}/${name}`,
    reason: 'similar name',
  }));
}

/**
 * Whether discover answers a query in this project, or answers every query
 * with the list (spec:AST-051 FR1): it answers once the project loads an
 * integration or has a discover source of its own. This is the rule
 * `discover()` applies to the project it loads; the command reads it to keep
 * the list's hints from suggesting queries that only return the list.
 * @param {import('../../foundation/config/project.mjs').Project | undefined} project
 * @returns {boolean}
 */
export function answersQueries(project) {
  return (
    project != null &&
    (project.loadedIntegrations.some(i => !i.__loadError) ||
      hasSources(project))
  );
}

/**
 * @param {string} [query]
 * @param {import('./discover.type.mjs').DiscoverOptions} [options]
 * @returns {Promise<
 *   import('./discover.type.mjs').DiscoverListResponse |
 *   import('./discover.type.mjs').DiscoverDetailResponse |
 *   import('./discover.type.mjs').DiscoverDetailDocResponse |
 *   import('./discover.type.mjs').DiscoverItemResponse |
 *   import('./discover.type.mjs').DiscoverSearchResponse
 * >}
 */
export async function discover(query, options = {}) {
  const {lang = null, zh = false, type, limit} = options;
  // An experimental kind is read only in a project that opts in (spec:AST-017
  // FR27); only then does `--type` take it, or an error name it.
  const kinds =
    options.type != null &&
    !(/** @type {readonly unknown[]} */ (STABLE_KINDS).includes(options.type))
      ? await loadReadKinds()
      : STABLE_KINDS;
  checkOptions(options, kinds);
  const only = options.installed
    ? /** @type {const} */ ('installed')
    : options.available
      ? /** @type {const} */ ('available')
      : undefined;

  const {packages: scanned, configured, project} = await discoverPackages();
  const integrations = await describeInstalled(project, scanned);
  const declared = declaredDependencies(project);
  // The official list is always read, so discover always has a source.
  const official = officialList({project});
  const declarations = officialDeclarations(project, official.packages);
  const add = addCommand(project);
  const addOfficial = addCommand(project, {official: official.packages});
  /** @param {{package: string, official?: true}} pkg */
  const installFor = pkg => (pkg.official ? addOfficial : add)(pkg.package);

  /** @param {{package?: string, version?: string}} [request] */
  const catalogFor = request => callSources(project, request, {official});
  /**
   * What the project has, once a catalog says which official packages it
   * declares.
   * @param {import('./_adapter.mjs').CatalogResult} catalog
   */
  const installedFor = catalog =>
    withDeclaredOfficial(
      project,
      integrations,
      catalog,
      declarations,
      official.packages,
    );

  // No query, or any query in a project that loads no integration and has no
  // discover source of its own: the list (spec:AST-051 FR1).
  if (!query || (integrations.length === 0 && !hasSources(project))) {
    const catalog = await catalogFor();
    const packages = installedFor(catalog);
    // Inside a project, the integrations installed for the computer are
    // available, never loaded (spec AST-081 FR12).
    const computer = await computerAvailableEntries(
      project,
      packages,
      declared,
    );
    const fromSources = officialFirst(
      availableEntries(catalog, packages, declared, {
        officialDeclared: declarations.any,
        install: installFor,
      }),
      official.packages,
      entry => entry.name,
    );
    const named = new Set(fromSources.map(entry => entry.name));
    return list(withLatest(packages, catalog), {
      configured,
      type,
      only,
      available: [
        ...fromSources,
        ...computer.filter(entry => !named.has(entry.name)),
      ],
      sources: catalog.sources,
    });
  }

  // A non-string (truthy) query would crash the parsing below with a raw
  // TypeError (no ERR_* code → downgrades to ERR_UNKNOWN). The CLI only ever
  // passes a string, but the public API must fail with a code.
  if (typeof query !== 'string') {
    throw new AstryxError(
      `Invalid query "${String(query)}"`,
      undefined,
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }

  const target = splitTarget(query);

  /**
   * One package, one version, or one item, once `target.name` is known to be
   * a package the project or a source has.
   * @param {import('./_adapter.mjs').CatalogResult} catalog
   */
  const packageView = async catalog => {
    const packages = installedFor(catalog);
    const installedNames = new Set(packages.map(p => p.name));
    const entry = catalog.packages.find(p => p.package === target.name);
    const installedAs = entry
      ? catalogState(entry, installedNames, declared, declarations.any)
          .installedAs
      : undefined;
    const isIntegration = integrations.some(p => p.name === target.name);
    // An entry only the official list supplies answers for what it lists.
    // Any other version or item of that package keeps the answer discover
    // gave before the list existed: ERR_UNKNOWN_PACKAGE.
    const officialOnly = entry?.official === true && !isIntegration;
    if (officialOnly && target.version) {
      const local = packages.find(p => p.name === target.name)?.version;
      if (
        target.version !== local &&
        !entry.versions.some(v => v.version === target.version)
      ) {
        throw new AstryxError(
          `${target.name}@${target.version} is not a version discover knows here: ${
            entry.versions.length > 0
              ? `it knows ${entry.versions.map(v => v.version).join(', ')}`
              : 'it knows no version of it for this project'
          }. Other versions are on the package registry.`,
          [...new Set([...entry.versions.map(v => v.version), local])]
            .filter(v => v != null)
            .map(v => ({
              name: `${target.name}@${v}`,
              reason: 'version discover knows',
            })),
          ERROR_CODES.ERR_UNKNOWN_PACKAGE,
        );
      }
    }
    const context = {
      catalog: entry,
      version: target.version,
      // Only an entry the official list supplied gets a pinned version.
      add: entry?.official ? addOfficial : add,
      installedAs,
    };
    if (!target.item) return detail(packages, target.name, context);
    const found = item(packages, target.name, target.item, context);
    if (found) return found;
    // An installed icon set that was withdrawn answers nothing; say why
    // rather than that the package has no such item (spec:AST-084 FR17).
    const gone = packages
      .find(p => p.name === target.name)
      ?.withdrawnIconSets?.find(each => each.name === target.item);
    if (gone) {
      throw new AstryxError(
        `Icon set "${target.item}" in ${target.name} is installed but withdrawn: ${gone.reason}`,
        [],
        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
      );
    }
    if (officialOnly) {
      throw new AstryxError(
        `"${target.item}" not found in ${target.name}`,
        similarItems(entry, target.item),
        ERROR_CODES.ERR_UNKNOWN_PACKAGE,
      );
    }
    // Only an installed package has docs to fall back to. For one that is
    // only in a source, the item is what is unknown, not the package.
    if (entry && !isIntegration) {
      throw new AstryxError(
        `"${target.item}" not found in ${target.name}`,
        similarItems(entry, target.item),
        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
      );
    }
    return await doc(integrations, target.name, target.item, {lang, zh});
  };

  // An installed component keeps resolving to its full doc, before any source
  // is asked anything.
  const installedPkg = integrations.find(p => p.name === target.name);
  if (installedPkg && target.item && !target.version) {
    const resolved = findComponent([installedPkg], target.item);
    if (resolved) return await docFromResult(resolved, {lang, zh});
  }

  if (target.scoped) {
    return await packageView(
      await catalogFor({package: target.name, version: target.version}),
    );
  }

  const listing = await catalogFor();
  const isPackage =
    installedPkg != null ||
    listing.packages.some(p => p.package === target.name);
  if (isPackage && (target.version || target.item || target.name === query)) {
    return await packageView(
      await catalogFor({package: target.name, version: target.version}),
    );
  }

  const packages = installedFor(listing);
  return await search(packages, query, {
    items: searchItems(packages, listing, declared, declarations.any),
    type,
    only,
    limit: limit ?? DEFAULT_LIMIT,
  });
}