Skip to content

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

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

/**
 * @file The CLI release an integration's newer contributions need
 * (spec:AST-046 FR11).
 *
 * @input A package.json object.
 * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
 *   only CLIs that read what the package ships, and the package.json that
 *   declares that range.
 * @position foundation/integrations; read by `integration add doc --parent`
 *   and `integration add theme`, which declare the peer, and
 *   `integration verify`, which requires it.
 */

import {semverCompare} from '../env/semver.mjs';

export const CLI_PACKAGE = '@astryxdesign/cli';

/**
 * The first stable CLI release that reads an integration's docs tree:
 * namespace docs and placed guides. Published 0.6.3 rejects a namespace doc
 * and hides every doc topic the package ships, with no warning; published
 * 0.6.4 lists the namespace and reads its guides.
 */
export const NAMESPACE_DOCS_CLI = '0.6.4';

/**
 * The first stable CLI release that applies a template's `replaces`
 * (spec:AST-035 FR1). Published 0.6.3 and earlier reject the field, drop that
 * template, and hide every doc topic the package ships. Published 0.6.4 lists
 * the template, keeps the topics, answers the Core id with the replacement,
 * and still selects the Core original with `--package @astryxdesign/core`.
 */
export const TEMPLATE_REPLACES_CLI = '0.6.4';

/**
 * The first stable CLI release that reads a template's `keywords`. Published
 * 0.6.4 and 0.6.5 reject the field and drop that template but keep the
 * package's doc topics; 0.6.3 and earlier also hide them. Published 0.6.6
 * lists the template, and search matches its keywords.
 */
export const KEYWORDS_CLI = '0.6.6';

/**
 * The first stable CLI release that applies a component's `replaces`
 * (spec:AST-035 FR10). It is also the opt-in: a CLI applies a package's
 * component replacements only when the package's `@astryxdesign/cli` peer
 * range starts here, so a package published for an earlier CLI keeps the
 * behavior it shipped with. Earlier stable CLIs accept the field and keep the
 * component under its own name.
 *
 * Tied to the next patch slot: it must equal the first stable release that
 * ships component replacement. If that slot moves, change this constant and
 * its row in the floor table test together.
 */
export const COMPONENT_REPLACES_CLI = '0.6.7';

/**
 * The first stable CLI release that reads typed theme descriptors, the theme
 * folder `integration add theme` writes. Published 0.6.3 rejects a themes root
 * with no `manifest.json` catalog and withholds the package's themes and doc
 * topics; published 0.6.4 lists the themes.
 */
export const THEMES_CLI = '0.6.4';

/**
 * The first stable CLI release that reads a doc section's `id`. Published
 * 0.6.3 rejects the field and hides every doc topic the package ships;
 * published 0.6.4 reads the section by its id.
 */
export const SECTION_IDS_CLI = '0.6.4';

/**
 * The first stable CLI release that reads `stability` on a doc
 * (spec:AST-017 FR21, FR27). Published 0.7.3 refuses the field on a page or
 * block template, which it drops, and on a namespace doc, which hides every
 * doc topic the package ships; component docs and guides keep loading and
 * ignore it.
 *
 * Tied to the next patch slot: it must equal the first stable release that
 * reads the field.
 */
export const STABILITY_CLI = '0.7.4';

/**
 * The first stable CLI release that reads a template's `icons` declaration
 * (spec:AST-084 FR16). Published 0.7.3 refuses the field and drops that
 * template.
 *
 * Tied to the next patch slot, with {@link STABILITY_CLI}.
 */
export const TEMPLATE_ICONS_CLI = '0.7.4';

/**
 * The first CLI release that reads a doc section's `before` and `after`.
 * Earlier releases reject the fields and hide every doc topic the package
 * ships.
 */
export const SECTION_POSITION_CLI = '0.7.4';

/**
 * The first stable CLI release that renders doc tokens (`{@command …}`,
 * `{@pm …}`, `{@pm-only …}`) for the reader. Every earlier release prints
 * them as written, so readers see raw tokens.
 */
export const DOC_TOKENS_CLI = '0.7.4';

const VERSION_RE =
  /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;

/**
 * A version or partial version as MAJOR.MINOR.PATCH, a wildcard part as 0.
 * @param {string} text
 * @returns {string | null}
 */
function lowerVersion(text) {
  const m = VERSION_RE.exec(text.trim());
  if (!m) return null;
  return [m[1], m[2], m[3]]
    .map(part => (part == null || /^[xX*]$/.test(part) ? '0' : part))
    .join('.');
}

/**
 * The lowest version one space-joined comparator set admits, or null when it
 * has no lower bound this can read.
 * @param {string} set
 * @returns {string | null}
 */
function lowestOfSet(set) {
  if (set === '' || set === '*' || /^[xX]$/.test(set)) return null;
  const hyphen = /^(\S+)\s+-\s+\S+$/.exec(set);
  if (hyphen) return lowerVersion(hyphen[1]);
  /** @type {string | null} */
  let lowest = null;
  for (const comparator of set.split(/\s+/)) {
    const m = /^(>=|<=|>|<|=|\^|~)?(.+)$/.exec(comparator);
    if (!m) return null;
    if (m[1] === '<' || m[1] === '<=') continue;
    const version = lowerVersion(m[2]);
    if (version == null) return null;
    if (lowest == null || semverCompare(version, lowest) > 0) lowest = version;
  }
  return lowest;
}

/**
 * The lowest version a semver range admits: the least of its `||`
 * alternatives. Null when an alternative has no lower bound, or the range is
 * not one this can read, so the caller treats it as admitting every version.
 * @param {unknown} range
 * @returns {string | null}
 */
export function lowestAdmitted(range) {
  if (typeof range !== 'string') return null;
  /** @type {string | null} */
  let lowest = null;
  for (const alternative of range.split('||')) {
    const low = lowestOfSet(alternative.trim());
    if (low == null) return null;
    if (lowest == null || semverCompare(low, lowest) < 0) lowest = low;
  }
  return lowest;
}

/**
 * Why a package that uses a feature an older CLI cannot read would lose it,
 * or null when its declared CLI range admits only CLIs that read it.
 * @param {any} pkg package.json
 * @param {string} feature what the package does, e.g. "ships a namespace doc"
 * @param {string} loss what an older CLI does with it
 * @param {string} floor the first stable CLI release that reads it
 * @returns {string | null}
 */
export function cliRangeProblem(pkg, feature, loss, floor) {
  // A floor that is missing or not a version means a caller passed the
  // arguments in another order, as after a merge with a caller written for
  // another signature. Fail loudly rather than compare a range against
  // feature text, or against nothing.
  if (typeof floor !== 'string' || lowerVersion(floor) == null) {
    throw new TypeError(`cliRangeProblem: floor "${floor}" is not a version`);
  }
  const range = pkg?.peerDependencies?.[CLI_PACKAGE];
  const fix = `"${CLI_PACKAGE}": ">=${floor}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
  if (typeof range !== 'string') {
    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${floor} ${loss}. Declare ${fix}.`;
  }
  const lowest = lowestAdmitted(range);
  if (lowest == null || semverCompare(lowest, floor) < 0) {
    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${floor}, which ${loss}. Declare ${fix}.`;
  }
  return null;
}

/**
 * Why a package that ships a namespace doc or a placed guide would lose its
 * docs on an older CLI, or null when its declared CLI range admits only CLIs
 * that read the docs tree. Published 0.6.3 hides every topic of a package
 * with a namespace doc; builds of main before the docs tree also do so for a
 * placed guide. Published 0.6.4 reads both.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function docsTreeCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'ships a namespace doc or a placed guide',
    'does not read the docs tree, and can hide every doc topic the package ships',
    NAMESPACE_DOCS_CLI,
  );
}

/**
 * Why a package with a template that sets `replaces` would lose that template
 * and its doc topics on an older CLI (spec:AST-035 FR1), or null when its
 * declared CLI range admits only CLIs that apply the field. Published 0.6.3
 * rejects the field; published 0.6.4 applies it.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function replacesCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a template that sets `replaces`',
    "rejects the field, drops that template, and hides the package's doc topics",
    TEMPLATE_REPLACES_CLI,
  );
}

/**
 * Why a package with a component that sets `replaces` would not get the
 * replacement (spec:AST-035 FR10), or null when its declared CLI range starts
 * at the release that applies it. That range is the package's opt-in: without
 * it the component keeps its own name and the Core component stays selected.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function componentReplacesCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a component that sets `replaces`',
    'ignores the field and keeps the component under its own name, and a later CLI applies the replacement only for a package whose range starts at that release',
    COMPONENT_REPLACES_CLI,
  );
}

/**
 * Why a package with a doc section that sets `id` would lose its doc topics on
 * an older CLI, or null when its declared CLI range admits only CLIs that read
 * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
 * the package ships; published 0.6.4 reads it.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function sectionIdsCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a doc section that sets `id`',
    'rejects the field, and can hide every doc topic the package ships',
    SECTION_IDS_CLI,
  );
}

/**
 * Why a package with a doc section that sets `before` or `after` would lose
 * its doc topics on an older CLI, or null when its declared CLI range admits
 * only CLIs that read the fields (spec:AST-046 FR11).
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function sectionPositionCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a doc section that sets `before` or `after`',
    'rejects the fields, and can hide every doc topic the package ships',
    SECTION_POSITION_CLI,
  );
}

/**
 * Why a package whose docs write doc tokens would show them raw on an older
 * CLI, or null when its declared CLI range admits only CLIs that render
 * them. Every release before the first that renders them prints a token as
 * written.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function docTokensCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'writes doc tokens (`{@command …}`, `{@pm …}` or `{@pm-only …}`) in its docs',
    'prints each token as written, so readers see raw tokens instead of commands',
    DOC_TOKENS_CLI,
  );
}

/**
 * Why a package that ships a theme would lose its themes and doc topics on an
 * older CLI, or null when its declared CLI range admits only CLIs that read
 * typed theme descriptors. Published 0.6.3 rejects a themes root with no
 * `manifest.json` catalog, which `integration add theme` no longer writes;
 * published 0.6.4 reads the descriptors.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function themesCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'ships a theme',
    "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
    THEMES_CLI,
  );
}

/**
 * Why a package with a template that sets `keywords` would lose that template
 * on an older CLI, or null when its declared CLI range admits only CLIs that
 * read the field. Published 0.6.4 and 0.6.5 reject the field and drop that
 * template; 0.6.3 and earlier also hide the package's doc topics. Published
 * 0.6.6 reads it.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function keywordsCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a template that sets `keywords`',
    "rejects the field and drops that template, and one before 0.6.4 also hides the package's doc topics",
    KEYWORDS_CLI,
  );
}

/**
 * The package.json with a CLI peer of `>=floor`: optional, unless the package
 * already says otherwise. Call it only when the package's range admits a CLI
 * before `floor`, so a stricter range is never lowered.
 * @param {any} pkg package.json
 * @param {string} floor the first stable CLI release the package needs
 * @returns {any}
 */
export function withCliPeer(pkg, floor) {
  const meta = pkg.peerDependenciesMeta ?? {};
  return {
    ...pkg,
    peerDependencies: {
      ...(pkg.peerDependencies ?? {}),
      [CLI_PACKAGE]: `>=${floor}`,
    },
    peerDependenciesMeta: meta[CLI_PACKAGE]
      ? meta
      : {...meta, [CLI_PACKAGE]: {optional: true}},
  };
}

/**
 * The package.json with a CLI peer that reads namespace docs.
 * @param {any} pkg package.json
 * @returns {any}
 */
export function withDocsTreeCli(pkg) {
  return withCliPeer(pkg, NAMESPACE_DOCS_CLI);
}

/**
 * Why a package whose template or namespace doc sets `stability` would lose
 * it on an older CLI, or null when its declared CLI range admits only CLIs
 * that read the field.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function stabilityCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a template or namespace doc that sets `stability`',
    "rejects the field and drops that descriptor, and for a namespace doc hides the package's doc topics",
    STABILITY_CLI,
  );
}

/**
 * Why a package with a template that declares `icons` would lose that
 * template on an older CLI, or null when its declared CLI range admits only
 * CLIs that read the field.
 * @param {any} pkg package.json
 * @returns {string | null}
 */
export function templateIconsCliProblem(pkg) {
  return cliRangeProblem(
    pkg,
    'has a template that declares `icons`',
    'rejects the field and drops that template',
    TEMPLATE_ICONS_CLI,
  );
}

/**
 * The first stable CLI release that reads `experimental.iconSet` in a
 * project's astryx.config (spec:AST-084 FR16). Published 0.7.3 refuses the
 * config ("Unrecognized key"), so commands that load the project
 * configuration, such as `doctor` and `discover`, fail in that project.
 *
 * Tied to the next patch slot, with {@link STABILITY_CLI}.
 */
export const CONFIG_ICON_SET_CLI = '0.7.4';

/**
 * Why an app project whose astryx.config sets `experimental.iconSet` would be
 * refused by a CLI it may run, or null when the `@astryxdesign/cli` range it
 * declares (in dependencies, devDependencies, optionalDependencies, or
 * peerDependencies) admits only CLIs that read the key. A project that
 * declares no range, or one that is not a version range (`workspace:`,
 * `file:`, `link:`), gets null: nothing says which CLI it runs.
 * @param {any} pkg the project's package.json
 * @returns {string | null}
 */
export function projectIconSetCliWarning(pkg) {
  const field = [
    'dependencies',
    'devDependencies',
    'optionalDependencies',
    'peerDependencies',
  ].find(name => typeof pkg?.[name]?.[CLI_PACKAGE] === 'string');
  if (!field) return null;
  const range = pkg[field][CLI_PACKAGE];
  if (range.includes(':')) return null;
  const lowest = lowestAdmitted(range);
  if (lowest != null && semverCompare(lowest, CONFIG_ICON_SET_CLI) >= 0) {
    return null;
  }
  return `The project's ${CLI_PACKAGE} range "${range}" (${field}) admits a release before ${CONFIG_ICON_SET_CLI}, which refuses an astryx.config that sets \`experimental.iconSet\` ("Unrecognized key"), so commands that load the project configuration, such as \`doctor\` and \`discover\`, fail there. Require "${CLI_PACKAGE}": ">=${CONFIG_ICON_SET_CLI}".`;
}