Skip to content

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

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

/**
 * @file `theme build` in an app generates with the Core the app installed.
 *
 * A CLI run one-off (`npx @astryxdesign/cli`) has no Core beside it, and the
 * app's `<Theme>` runs on the app's Core either way, so the build loads the
 * project's installed `@astryxdesign/core` when it differs from the CLI's own.
 * When there is no Core to use, the error names the fix for where it ran:
 * install it in an app, build it in the Astryx repository. An installed Core
 * that does not load, or lacks the functions the build calls, fails the build,
 * naming it, rather than leave the build to the CLI's own Core.
 */

import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {
  coreUnavailableMessage,
  themeBuild,
  validateThemePrivateInputs,
} from './build.mjs';
import {fetchCarriedThemeCoreDir} from '../_adapter.mjs';

vi.mock('../_adapter.mjs', async importOriginal => {
  const actual = /** @type {Record<string, any>} */ (await importOriginal());
  return {
    ...actual,
    fetchCarriedThemeCoreDir: vi.fn(actual.fetchCarriedThemeCoreDir),
  };
});

const HERE = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(HERE, '../../../../..');
const CORE_DIST = path.join(REPO_ROOT, 'packages/core/dist');

/** @type {string[]} */
const tmpDirs = [];
const makeDir = () => {
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-project-core-'));
  tmpDirs.push(dir);
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    '{"name":"app","type":"module"}',
  );
  // A plain theme object: the file itself never imports Core, so only the
  // build's own Core loading can set the marker below.
  fs.writeFileSync(
    path.join(dir, 'ocean.mjs'),
    "export default {name: 'ocean', tokens: {'--color-bg': '#0a0a0a'}};\n",
  );
  return dir;
};

beforeEach(() => {
  delete globalThis.__astryxProjectCoreLoads;
});
afterEach(() => {
  delete globalThis.__astryxProjectCoreLoads;
  for (const dir of tmpDirs.splice(0))
    fs.rmSync(dir, {recursive: true, force: true});
});

/**
 * Install a Core in `dir` that is the built one, re-exported, and records each
 * entry as it is imported. Its `exports` map lists `source` first, as Core's
 * own does, so the build must skip that condition to find the runtime file.
 * @param {string} dir
 * @param {{broken?: boolean, themeModule?: string}} [options] `themeModule`
 *   replaces the theme entry's source
 */
function installCore(dir, {broken = false, themeModule} = {}) {
  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
  fs.mkdirSync(core, {recursive: true});
  fs.writeFileSync(
    path.join(core, 'package.json'),
    JSON.stringify({
      name: '@astryxdesign/core',
      version: '0.6.5',
      type: 'module',
      exports: {
        '.': {types: './root.d.ts', default: './root.mjs'},
        './theme': {
          source: './src/theme/index.ts',
          types: './theme.d.ts',
          default: './theme.mjs',
        },
      },
    }),
  );
  /** @param {string} entry @param {string} target */
  const module = (entry, target) =>
    broken
      ? "throw new Error('this Core is broken');\n"
      : `export * from ${JSON.stringify(pathToFileURL(path.join(CORE_DIST, target)).href)};\n` +
        `globalThis.__astryxProjectCoreLoads = [...(globalThis.__astryxProjectCoreLoads ?? []), '${entry}'];\n`;
  fs.writeFileSync(
    path.join(core, 'theme.mjs'),
    themeModule ?? module('theme', 'theme/index.js'),
  );
  fs.writeFileSync(path.join(core, 'root.mjs'), module('root', 'index.js'));
  return core;
}

describe('theme build outside a project, with the Core this CLI release carries', () => {
  it('fails naming a carried Core that does not load, rather than build with the CLI’s own', async () => {
    const carried = installCore(makeDir(), {broken: true});
    vi.mocked(fetchCarriedThemeCoreDir).mockReturnValueOnce(carried);
    const bare = makeDir();
    const build = themeBuild('ocean.mjs', {}, {cwd: bare});
    await expect(build).rejects.toMatchObject({
      code: 'ERR_CORE_NOT_FOUND',
      message: expect.stringContaining(
        `Could not load the @astryxdesign/core this CLI release carries, at ${carried}`,
      ),
    });
    await expect(build).rejects.toThrow(/Import error: this Core is broken/);
    expect(fs.existsSync(path.join(bare, 'ocean.css'))).toBe(false);
  });
});

describe('theme build generates with the Core the project installed', () => {
  it('loads the app’s installed Core when it differs from the CLI’s own', async () => {
    const app = makeDir();
    installCore(app);
    await themeBuild('ocean.mjs', {}, {cwd: app});
    // The theme imports nothing from the root entry, so the root never loads.
    expect(globalThis.__astryxProjectCoreLoads).toEqual(['theme']);
    // The same Core, re-exported, emits the same CSS as the CLI's own. The
    // generated header differs only in the Core version it records.
    const bare = makeDir();
    await themeBuild('ocean.mjs', {}, {cwd: bare});
    /** @param {string} dir */
    const rules = dir =>
      fs
        .readFileSync(path.join(dir, 'ocean.css'), 'utf-8')
        .replace(/^\/\*[\s\S]*?\*\/\n/, '');
    expect(rules(app)).toBe(rules(bare));
    expect(rules(app)).toContain('#0a0a0a');
  });

  it('loads the app’s installed root only for a theme that imports it', async () => {
    const app = makeDir();
    installCore(app);
    fs.writeFileSync(
      path.join(app, 'harbor.mjs'),
      "import {defineTheme} from '@astryxdesign/core';\nexport default defineTheme({name: 'harbor', tokens: {'--color-bg': '#0b0b0b'}});\n",
    );
    await themeBuild('harbor.mjs', {}, {cwd: app});
    expect(globalThis.__astryxProjectCoreLoads).toEqual(['theme', 'root']);
    expect(fs.readFileSync(path.join(app, 'harbor.css'), 'utf-8')).toContain(
      '#0b0b0b',
    );
  });

  it('checks a theme’s private inputs without loading the app’s installed root when the theme does not import it', async () => {
    // The doctor's check: the CommonJS patch wraps the installed Core for a
    // `.cjs` dependency, and wraps its root only if something requires it.
    const app = makeDir();
    installCore(app);
    expect(await validateThemePrivateInputs('ocean.mjs', {cwd: app})).toEqual(
      [],
    );
    expect(globalThis.__astryxProjectCoreLoads).toEqual(['theme']);
  });

  it('checks the private inputs of every theme beside an installed Core whose theme entry fails to load', async () => {
    // Doctor runs this check for each added theme. A `.cjs` dependency could
    // not load that entry either, so the CommonJS patch skips it.
    const app = makeDir();
    installCore(app, {
      themeModule: "throw new Error('the theme entry failed to load');\n",
    });
    fs.writeFileSync(
      path.join(app, 'harbor.mjs'),
      "export default {name: 'harbor', tokens: {'--_card-radius': '4px'}};\n",
    );
    expect(await validateThemePrivateInputs('ocean.mjs', {cwd: app})).toEqual(
      [],
    );
    const errors = await validateThemePrivateInputs('harbor.mjs', {cwd: app});
    expect(errors).toHaveLength(1);
    expect(errors[0]).toContain('--_card-radius');
  });

  it('keeps the CLI’s own Core when the project has none', async () => {
    const bare = makeDir();
    await themeBuild('ocean.mjs', {}, {cwd: bare});
    expect(globalThis.__astryxProjectCoreLoads).toBeUndefined();
    expect(fs.existsSync(path.join(bare, 'ocean.css'))).toBe(true);
  });

  it('fails naming an installed Core that does not load, rather than build with the CLI’s own', async () => {
    const app = makeDir();
    installCore(app, {broken: true});
    await expect(themeBuild('ocean.mjs', {}, {cwd: app})).rejects.toMatchObject(
      {
        code: 'ERR_CORE_NOT_FOUND',
        message: expect.stringContaining(
          `Could not load the @astryxdesign/core installed at ${path.join('node_modules', '@astryxdesign', 'core')}`,
        ),
      },
    );
    await expect(themeBuild('ocean.mjs', {}, {cwd: app})).rejects.toThrow(
      /Import error: this Core is broken/,
    );
    expect(fs.existsSync(path.join(app, 'ocean.css'))).toBe(false);
  });

  it('fails naming an installed Core without the functions the build calls, rather than build with the CLI’s own', async () => {
    const app = makeDir();
    installCore(app, {
      themeModule: 'export const defineTheme = theme => theme;\n',
    });
    await expect(themeBuild('ocean.mjs', {}, {cwd: app})).rejects.toMatchObject(
      {
        code: 'ERR_CORE_INCOMPATIBLE',
        message: expect.stringContaining(
          'does not export generateThemeRulesSplit',
        ),
      },
    );
    expect(fs.existsSync(path.join(app, 'ocean.css'))).toBe(false);
  });
});

describe('the error when there is no Core to generate with', () => {
  it('tells an app to install Core, not to build it', () => {
    const app = makeDir();
    const message = coreUnavailableMessage(
      app,
      new Error("Cannot find package '@astryxdesign/core'"),
    );
    expect(message).toContain(
      'This project does not have @astryxdesign/core installed',
    );
    expect(message).toContain('`npm install @astryxdesign/core`');
    expect(message).not.toContain('pnpm -F');
    expect(message).toContain(
      "Import error: Cannot find package '@astryxdesign/core'",
    );
  });

  it('names an installed Core that does not load', () => {
    const app = makeDir();
    installCore(app, {broken: true});
    const message = coreUnavailableMessage(
      app,
      new Error('this Core is broken'),
    );
    expect(message).toContain(
      `Could not load the @astryxdesign/core installed at ${path.join('node_modules', '@astryxdesign', 'core')}`,
    );
    expect(message).toContain('Reinstall it.');
    expect(message).not.toContain('pnpm -F');
  });

  it('keeps the build instruction in the Astryx repository', () => {
    const message = coreUnavailableMessage(
      path.join(REPO_ROOT, 'packages', 'cli'),
      undefined,
    );
    expect(message).toContain('Build @astryxdesign/core first');
    expect(message).toContain('`pnpm -F @astryxdesign/core build`');
    expect(message).not.toContain('Import error');
  });
});