Skip to content

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

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

/**
 * @file Matching a project to a host's package sets (architecture:cli-surface
 * INV30). A package set is a root whose `node_modules` holds a CLI, the Core
 * equal to it, and the integrations installed with them; a run resolves from at
 * most one root, and a hosted run installs nothing.
 *
 * Inside a project a root fills only the `@astryxdesign/*` packages the
 * project leaves uninstalled whose copy in the root ships no integration
 * manifest. For a run that a release other than the starting copy answers, the
 * first root in the host's order qualifies when its CLI and Core are that
 * release and it holds, for each package it may fill, the version the project
 * would install: the lockfile's, else a published version in the declared
 * range.
 *
 * @input A release, the project folder, and the host's roots.
 * @output The root that serves the run, or why none can.
 * @position foundation/runtime — read by the release choice (handoff.mjs) in a
 *   hosted run.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {findManifestPaths} from '../integrations/manifest-paths.mjs';
import {readJson} from '../release/project.mjs';
import {cliBinOf, isVersionRange} from '../release/cache.mjs';
import {isValidSemver, satisfiesRange} from '../env/semver.mjs';
import {projectAstryxPins} from './locked-versions.mjs';

const CLI = '@astryxdesign/cli';
const CORE = '@astryxdesign/core';

/**
 * A root's own copy of `name`, read from its `node_modules` only: a root never
 * reaches past itself.
 * @param {string} root
 * @param {string} name
 * @returns {{dir: string, version: string | null} | null}
 */
export function rootPackage(root, name) {
  const dir = path.join(root, 'node_modules', ...name.split('/'));
  const pkg = readJson(path.join(dir, 'package.json'));
  if (!pkg || typeof pkg !== 'object' || pkg.name !== name) return null;
  return {dir, version: typeof pkg.version === 'string' ? pkg.version : null};
}

/**
 * Whether `version` is one the project's install could bring in for `range`:
 * a plain version range only, and a prerelease only when the range names a
 * prerelease of the same version.
 * @param {string | null} version
 * @param {string} range
 * @returns {boolean}
 */
export function satisfiesInstall(version, range) {
  if (!version || !isValidSemver(version) || !isVersionRange(range)) {
    return false;
  }
  const dash = version.indexOf('-');
  if (dash !== -1 && !range.includes(`${version.slice(0, dash)}-`)) {
    return false;
  }
  return satisfiesRange(version, range);
}

/**
 * Whether `root` holds what the project would install for one pin it leaves
 * uninstalled. A package the root holds as an integration, or does not hold at
 * all, is one the root never fills, so it never keeps the root out.
 * @param {string} root
 * @param {import('./locked-versions.mjs').AstryxPin} pin
 * @returns {boolean}
 */
function holds(root, pin) {
  if (pin.name === CLI) return true;
  const copy = rootPackage(root, pin.name);
  if (!copy) return pin.name !== CORE;
  if (findManifestPaths(copy.dir).length > 0) return true;
  if (pin.locked) return copy.version === pin.locked;
  return satisfiesInstall(copy.version, pin.declared);
}

/**
 * @typedef {object} ServingRoot
 * @property {string} root
 * @property {string} cliDir the root's CLI package
 * @property {string | null} bin the root's `astryx` bin
 * @property {string | null} hostEntry the root's `host/index.mjs`, when its
 *   CLI ships one
 */

/**
 * The first of `roots` that may serve a run in `projectDir` that CLI
 * `release` answers.
 * @param {{release: string, projectDir: string | null, roots: readonly string[], needsHostEntry?: boolean}} input
 *   `needsHostEntry` keeps out a root whose CLI has no host entry
 * @returns {ServingRoot | {reason: string}}
 */
export function qualifyingRoot({
  release,
  projectDir,
  roots,
  needsHostEntry = false,
}) {
  const open = projectDir
    ? projectAstryxPins(projectDir).filter(pin => pin.installed === null)
    : [];
  for (const root of roots) {
    const cli = rootPackage(root, CLI);
    if (!cli || cli.version !== release) continue;
    const core = rootPackage(root, CORE);
    if (!core || core.version !== release) continue;
    const hostEntry = path.join(cli.dir, 'host', 'index.mjs');
    const hasHostEntry = fs.existsSync(hostEntry);
    if (needsHostEntry && !hasHostEntry) continue;
    const bin = cliBinOf(cli.dir);
    if (!bin && !hasHostEntry) continue;
    if (!open.every(pin => holds(root, pin))) continue;
    return {
      root,
      cliDir: cli.dir,
      bin,
      hostEntry: hasHostEntry ? hostEntry : null,
    };
  }
  return {
    reason: `no package set the host passed holds CLI ${release} with this project's packages`,
  };
}