Skip to content

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

TypeScript
5.7 KB
Raw Blame
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Check that every published package names the other `@astryxdesign`
 *   packages it needs at their release version.
 * @input Optional package directories; with none, every package npm receives
 *   from `packages/` and `packages/themes/` (public ones, and private ones
 *   marked canary-only, which the canary job publishes).
 * @output Prints each problem and exits 1 when there is one.
 * @position `pnpm check:published-manifests` runs it on every change,
 *   scripts/npm/publish-package.mjs runs `alignmentProblems` on each package
 *   just before it publishes, and the canary loops publish `publishedPackages`.
 *   A dependency, peer or optional dependency on an `@astryxdesign` package
 *   must name that package's exact version in the same release, the only
 *   spec the release's version sync moves. `*` and other ranges let a package
 *   manager keep an older release next to the new one: an app that upgraded
 *   Core could keep a theme from the release before, whose exact Core peer then
 *   no longer matches.
 */

import fs from 'node:fs';
import path from 'node:path';
import {pathToFileURL} from 'node:url';

const FIELDS = ['dependencies', 'peerDependencies', 'optionalDependencies'];
const PACKAGE_PARENTS = ['packages', 'packages/themes'];

// Entries that may keep another spec until a minor release. Narrowing a
// published range is a breaking change, so the CLI keeps its optional `*`
// peer on Core until the next minor release pins it to the release version.
export const PENDING_ALIGNMENT = [
  {
    name: '@astryxdesign/cli',
    field: 'peerDependencies',
    dependency: '@astryxdesign/core',
    spec: '*',
  },
];

function isPending(name, field, dependency, spec) {
  return PENDING_ALIGNMENT.some(
    entry =>
      entry.name === name &&
      entry.field === field &&
      entry.dependency === dependency &&
      entry.spec === spec,
  );
}

/** Each package under `root`, as its directory relative to `root` and its manifest. */
function workspacePackages(root) {
  return PACKAGE_PARENTS.flatMap(parent => {
    const parentDir = path.join(root, parent);
    if (!fs.existsSync(parentDir)) return [];
    return fs
      .readdirSync(parentDir, {withFileTypes: true})
      .filter(entry => entry.isDirectory())
      .map(entry => `${parent}/${entry.name}`)
      .sort();
  })
    .filter(dir => fs.existsSync(path.join(root, dir, 'package.json')))
    .map(dir => ({dir, manifest: readManifest(path.join(root, dir))}));
}

function readManifest(dir) {
  return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
}

/** Whether npm receives this package: public, or private and canary-only. */
export function isPublished(manifest) {
  return (
    Boolean(manifest.name?.startsWith('@astryxdesign/')) &&
    (!manifest.private || Boolean(manifest.astryx?.canaryOnly))
  );
}

/**
 * The packages npm receives from `root`: public `@astryxdesign` packages and
 * private canary-only ones. The canary loops publish exactly this list.
 */
export function publishedPackages(root) {
  return workspacePackages(root).filter(({manifest}) => isPublished(manifest));
}

/** Each package npm receives from `root`, by name, with its version. */
export function releaseVersions(root) {
  return new Map(
    publishedPackages(root).map(({manifest}) => [
      manifest.name,
      manifest.version,
    ]),
  );
}

/** The names of the packages only the canary channel publishes. */
export function canaryOnlyNames(root) {
  return new Set(
    publishedPackages(root)
      .filter(({manifest}) => manifest.astryx?.canaryOnly)
      .map(({manifest}) => manifest.name),
  );
}

/**
 * The problems in one manifest: each `@astryxdesign` entry in its
 * dependencies, peers or optional dependencies that does not name the
 * release version of that package (`versions`, by name). A package that the
 * stable channel publishes must not name one that only the canary channel
 * publishes (`canaryOnly`), because no stable version of it exists.
 */
export function alignmentProblems(manifest, versions, canaryOnly = new Set()) {
  const problems = [];
  const stable = !manifest.astryx?.canaryOnly;
  for (const field of FIELDS) {
    for (const [name, spec] of Object.entries(manifest[field] ?? {})) {
      if (!name.startsWith('@astryxdesign/')) continue;
      const version = versions.get(name);
      if (version == null) {
        problems.push(
          `${manifest.name}: ${field} names ${name}, which npm does not receive in this release`,
        );
      } else if (stable && canaryOnly.has(name)) {
        problems.push(
          `${manifest.name}: ${field} names ${name}, which only the canary channel publishes`,
        );
      } else if (
        spec !== version &&
        !isPending(manifest.name, field, name, spec)
      ) {
        problems.push(
          `${manifest.name}: ${field} ${name} is "${spec}"; name this release's version, "${version}"`,
        );
      }
    }
  }
  return problems;
}

function main() {
  const root = process.cwd();
  const versions = releaseVersions(root);
  const canaryOnly = canaryOnlyNames(root);
  const dirs = process.argv.slice(2);
  const manifests =
    dirs.length > 0
      ? dirs.map(readManifest).filter(isPublished)
      : publishedPackages(root).map(({manifest}) => manifest);
  const problems = manifests.flatMap(manifest =>
    alignmentProblems(manifest, versions, canaryOnly),
  );
  for (const problem of problems) console.error(problem);
  if (problems.length > 0) process.exit(1);
  console.log(
    `${manifests.length} published package manifests name their @astryxdesign packages at this release's version.`,
  );
}

if (
  process.argv[1] &&
  import.meta.url === pathToFileURL(process.argv[1]).href
) {
  main();
}