Skip to content

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

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

/**
 * @file Drift guard for the official package list the CLI carries for
 * `astryx discover` (spec:AST-051 FR11).
 *
 * `scripts/generate-cli-official-packages.mjs` builds the list from the
 * packages the release workflow publishes, with the CLI's own readers. This
 * test pins the committed file to what the generator builds now, and checks
 * the selection rule on a stand-in repository. When a package changes, run
 * `pnpm bundle:cli-official-packages` and commit the regenerated list.
 */

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {
  buildOfficialList,
  OFFICIAL_LIST_PATH,
  releaseChannel,
  serializeOfficialList,
} from './generate-cli-official-packages.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '..');

describe('the official package list is in sync with the repository', () => {
  it('matches what the generator builds (run `pnpm bundle:cli-official-packages`)', async () => {
    const committed = fs.readFileSync(
      path.join(REPO_ROOT, OFFICIAL_LIST_PATH),
      'utf-8',
    );
    expect(committed).toBe(serializeOfficialList(await buildOfficialList()));
  });

  it('releases every listed package with Core, unless it is canary-only', async () => {
    // A package outside Core's version group would show and pin a version it
    // was never released at: a renamed package must move with the group.
    const loose = (await buildOfficialList()).packages
      .filter(p => !p.canaryOnly && !p.releasedWithCore)
      .map(p => p.package);
    expect(loose).toEqual([]);
  });

  it('lists every public theme package and no base package', async () => {
    const names = (await buildOfficialList()).packages.map(p => p.package);
    const themes = fs
      .readdirSync(path.join(REPO_ROOT, 'packages', 'themes'))
      .map(slug =>
        path.join(REPO_ROOT, 'packages', 'themes', slug, 'package.json'),
      )
      .filter(file => fs.existsSync(file))
      .map(file => JSON.parse(fs.readFileSync(file, 'utf-8')))
      .filter(pkg => pkg.private !== true)
      .map(pkg => pkg.name);
    expect(themes.length).toBeGreaterThan(0);
    for (const theme of themes) expect(names).toContain(theme);
    for (const base of [
      '@astryxdesign/core',
      '@astryxdesign/cli',
      '@astryxdesign/build',
    ]) {
      expect(names).not.toContain(base);
    }
  });
});

describe('releaseChannel follows the release workflow publish rule', () => {
  it.each([
    [{name: '@astryxdesign/theme-x'}, 'latest'],
    [{name: '@astryxdesign/theme-x', private: false}, 'latest'],
    [{name: '@astryxdesign/x', private: true}, null],
    [
      {name: '@astryxdesign/x', private: true, astryx: {canaryOnly: true}},
      'canary',
    ],
    [{name: '@astryxdesign/x', astryx: {canaryOnly: true}}, 'canary'],
    [{name: '@acme/theme-x'}, null],
    [{}, null],
  ])('%o publishes to %s', (pkg, channel) => {
    expect(releaseChannel(pkg)).toBe(channel);
  });
});

describe('buildOfficialList on a stand-in repository', () => {
  /** @type {string} */
  let root;

  /** @param {string} file @param {unknown} value */
  const writeJSON = (file, value) => {
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, JSON.stringify(value));
  };

  /**
   * @param {string} slug
   * @param {object} pkg
   * @param {{descriptor?: boolean}} [options]
   */
  const theme = (slug, pkg, {descriptor = true} = {}) => {
    const dir = path.join(root, 'packages', 'themes', slug);
    writeJSON(path.join(dir, 'package.json'), pkg);
    fs.mkdirSync(path.join(dir, 'src'), {recursive: true});
    fs.writeFileSync(
      path.join(dir, 'src', `${slug}Theme.ts`),
      `export const ${slug}Theme = {};\n`,
    );
    if (descriptor) {
      fs.writeFileSync(
        path.join(dir, 'src', `${slug}Theme.doc.mjs`),
        `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: '${slug}', displayName: 'Ocean ${slug}', description: 'Blue ${slug}.', maintained: true};\n`,
      );
    }
  };

  beforeEach(() => {
    root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-official-list-'));
    writeJSON(path.join(root, '.changeset', 'config.json'), {
      fixed: [['@astryxdesign/core', '@astryxdesign/theme-ocean']],
    });
    writeJSON(path.join(root, 'packages', 'core', 'package.json'), {
      name: '@astryxdesign/core',
      description: 'The base.',
    });
  });

  afterEach(() => {
    fs.rmSync(root, {recursive: true, force: true});
  });

  it('keeps published packages that add something, and marks canary-only and Core-released ones', async () => {
    theme('ocean', {name: '@astryxdesign/theme-ocean', description: 'Sea.'});
    theme('lagoon', {
      name: '@astryxdesign/theme-lagoon',
      private: true,
      astryx: {canaryOnly: true},
    });
    theme('probe', {name: '@astryxdesign/theme-probe', private: true});
    theme('reef', {name: '@acme/theme-reef'});

    expect(await buildOfficialList(root)).toEqual({
      packages: [
        {
          package: '@astryxdesign/theme-lagoon',
          canaryOnly: true,
          contributions: [
            {
              kind: 'theme',
              name: 'lagoon',
              title: 'Ocean lagoon',
              summary: 'Blue lagoon.',
            },
          ],
        },
        {
          package: '@astryxdesign/theme-ocean',
          description: 'Sea.',
          releasedWithCore: true,
          contributions: [
            {
              kind: 'theme',
              name: 'ocean',
              title: 'Ocean ocean',
              summary: 'Blue ocean.',
            },
          ],
        },
      ],
    });
  });

  it('lists the same family members with or without a build of the package', async () => {
    // A canary-only package whose family member only its root entry exports,
    // as Lab's TourStep is: the list must not depend on a local build.
    const dir = path.join(root, 'packages', 'kit');
    writeJSON(path.join(dir, 'package.json'), {
      name: '@astryxdesign/kit',
      private: true,
      astryx: {canaryOnly: true},
      exports: {
        '.': {source: './src/index.ts', default: './dist/index.js'},
      },
    });
    const files = {
      'astryx.integration.mjs': "export default {components: './src'};\n",
      'src/index.ts':
        "export {Steps} from './Steps/Steps';\nexport {Step} from './Steps/Step';\n",
      'src/Steps/Steps.doc.mjs':
        "export default {type: 'component', name: 'Steps', usage: {description: 'x'}, components: [{name: 'Steps', description: 'x'}, {name: 'Step', description: 'x'}]};\n",
      'src/Steps/Steps.tsx': 'export function Steps() { return null; }\n',
      'src/Steps/Step.tsx': 'export function Step() { return null; }\n',
    };
    for (const [file, text] of Object.entries(files)) {
      fs.mkdirSync(path.dirname(path.join(dir, file)), {recursive: true});
      fs.writeFileSync(path.join(dir, file), text);
    }
    const unbuilt = serializeOfficialList(await buildOfficialList(root));
    expect(unbuilt).toContain('"name": "Step"');

    fs.mkdirSync(path.join(dir, 'dist'), {recursive: true});
    fs.writeFileSync(
      path.join(dir, 'dist', 'index.js'),
      'export function Steps() { return null; }\nexport function Step() { return null; }\n',
    );
    expect(serializeOfficialList(await buildOfficialList(root))).toBe(unbuilt);
  });

  it('refuses a published theme package with no descriptor', async () => {
    theme('bare', {name: '@astryxdesign/theme-bare'}, {descriptor: false});
    await expect(buildOfficialList(root)).rejects.toThrow(
      '@astryxdesign/theme-bare (packages/themes/bare) is published but has no src/bareTheme.ts with a same-stem src/bareTheme.doc.mjs descriptor',
    );
  });

  it('refuses a published theme package whose folder is not its file name', async () => {
    theme('ocean', {name: '@astryxdesign/theme-ocean'});
    fs.renameSync(
      path.join(root, 'packages', 'themes', 'ocean'),
      path.join(root, 'packages', 'themes', 'theme-ocean'),
    );
    await expect(buildOfficialList(root)).rejects.toThrow(
      'has no src/themeOceanTheme.ts with a same-stem src/themeOceanTheme.doc.mjs descriptor',
    );
  });

  it('refuses a published theme package whose descriptor does not read', async () => {
    theme('ocean', {name: '@astryxdesign/theme-ocean'});
    fs.writeFileSync(
      path.join(
        root,
        'packages',
        'themes',
        'ocean',
        'src',
        'oceanTheme.doc.mjs',
      ),
      'export default {};\n',
    );
    await expect(buildOfficialList(root)).rejects.toThrow(
      'must declare its public ThemeDoc type',
    );
  });
});