Skip to content

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

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

/**
 * @file ensure-core-built.test.mjs
 * @input coreBuildIsStale over temporary trees; ensureBuiltOnce with a
 *   temporary lock directory; the repository's .gitignore
 * @output A core build counts as current only when it is newer than every
 *   source file. A missing entry, or a source or package.json changed after
 *   it, is stale. node_modules, dist and generated output are not sources, and
 *   Core's translations are. A caller waiting on another's build returns only
 *   once that build released the lock. A suite builds only a missing Core.
 *   Only the node global setup rebuilds a stale one, before the workers fork.
 *   It waits until every run that started before it has ended. Each checkout
 *   has its own lock and its own run leases. Every file Core's build scripts
 *   write output with, and every local file those load, is a source.
 * @position Unit test of packages/cli/clients/cli/commands/ensure-core-built.mjs
 */

import {spawn} from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {afterEach, describe, expect, it, vi} from 'vitest';
import {
  CORE_BUILD_MARKER,
  CORE_GENERATED,
  CORE_SOURCES,
  coreBuildIsStale,
  coreBuildLockDir,
  coreRunLeaseDir,
  earlierLiveRuns,
  ensureBuiltOnce,
  ensureCoreBuiltAt,
  ensureCoreBuiltForRunAt,
  registerTestRun,
} from '../packages/cli/clients/cli/commands/ensure-core-built.mjs';

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

let dir;
afterEach(() => {
  if (dir) fs.rmSync(dir, {recursive: true, force: true});
  dir = undefined;
});

/** A core-shaped tree: sources at t = 1000 s, the built entry at t = 2000 s. */
function tree() {
  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-build-stale-'));
  const write = (relative, content, seconds) => {
    const file = path.join(dir, relative);
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, content);
    fs.utimesSync(file, seconds, seconds);
    return file;
  };
  const source = write('src/theme/index.ts', 'export {};', 1000);
  const pkg = write('package.json', '{}', 1000);
  const entry = write('dist/theme/index.js', 'export {};', 2000);
  return {
    write,
    source,
    entry,
    roots: [path.join(dir, 'src'), pkg],
  };
}

describe('coreBuildIsStale', () => {
  it('throws on a built entry it cannot read, rather than read it as missing', () => {
    const {roots, source} = tree();
    expect(() =>
      coreBuildIsStale(path.join(source, 'index.js'), roots),
    ).toThrow(/ENOTDIR/);
  });

  it('throws on a source it cannot read, rather than skip it', () => {
    const {entry, source} = tree();
    expect(() =>
      coreBuildIsStale(entry, [path.join(source, 'nested.ts')]),
    ).toThrow(/ENOTDIR/);
  });

  it('is stale with no build', () => {
    const {entry, roots} = tree();
    fs.rmSync(entry);
    expect(coreBuildIsStale(entry, roots)).toBe(true);
  });

  it('is current when the build is newer than every source', () => {
    const {entry, roots} = tree();
    expect(coreBuildIsStale(entry, roots)).toBe(false);
  });

  it('is stale when a source changed after the build, as a checkout does', () => {
    const {entry, roots, source} = tree();
    fs.utimesSync(source, 3000, 3000);
    expect(coreBuildIsStale(entry, roots)).toBe(true);
  });

  it('is stale when a new source appeared after the build', () => {
    const {entry, roots, write} = tree();
    write('src/theme/adaptations.ts', 'export {};', 3000);
    expect(coreBuildIsStale(entry, roots)).toBe(true);
  });

  it('is stale when package.json changed after the build', () => {
    const {entry, roots} = tree();
    fs.utimesSync(roots[1], 3000, 3000);
    expect(coreBuildIsStale(entry, roots)).toBe(true);
  });

  it('skips node_modules and dist under a source root', () => {
    const {entry, roots, write} = tree();
    write('src/node_modules/x/index.js', 'x', 3000);
    write('src/dist/x.js', 'x', 3000);
    expect(coreBuildIsStale(entry, roots)).toBe(false);
  });

  it('skips generated output, which the test setup rewrites after a build', () => {
    const {entry, roots, write} = tree();
    write('src/i18n/generated-locales/en.generated.ts', 'x', 3000);
    write('locales/pseudo.json', '{}', 3000);
    write('locales/en.json', '{}', 1000);
    const generated = [
      path.join(dir, 'src/i18n/generated-locales'),
      path.join(dir, 'locales/pseudo.json'),
    ];
    const withLocales = [...roots, path.join(dir, 'locales')];
    expect(coreBuildIsStale(entry, withLocales, generated)).toBe(false);
    // The translations they come from are sources.
    fs.utimesSync(path.join(dir, 'locales/en.json'), 3000, 3000);
    expect(coreBuildIsStale(entry, withLocales, generated)).toBe(true);
  });
});

describe("Core's sources", () => {
  it('include its translations, and skip exactly the git-ignored output under them', () => {
    const core = path.join(REPO_ROOT, 'packages/core');
    expect(CORE_SOURCES).toContain(path.join(core, 'locales'));
    // Every git-ignored path under a source root is generated output.
    const ignored = fs
      .readFileSync(path.join(REPO_ROOT, '.gitignore'), 'utf8')
      .split('\n')
      .map(line => line.trim())
      .filter(line => line.startsWith('packages/core/'))
      .map(line => path.join(REPO_ROOT, line.replace(/\/$/u, '')))
      .filter(p => CORE_SOURCES.some(root => p.startsWith(root + path.sep)));
    expect(ignored.length).toBeGreaterThan(0);
    expect([...CORE_GENERATED].sort()).toEqual([...ignored].sort());
  });
});

describe('ensureBuiltOnce', () => {
  /** A lock directory another process holds and releases after `ms`. */
  function heldFor(ms) {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-build-lock-'));
    const lockDir = path.join(dir, 'lock');
    fs.mkdirSync(lockDir);
    const child = spawn(
      process.execPath,
      [
        '-e',
        `setTimeout(() => require('node:fs').rmSync(${JSON.stringify(lockDir)}, {recursive: true, force: true}), ${ms})`,
      ],
      {stdio: 'ignore'},
    );
    return {lockDir, child};
  }

  it('waits for the lock to be released before reading a build another caller is writing', async () => {
    const {lockDir, child} = heldFor(400);
    const exited = new Promise(resolve => child.on('exit', resolve));
    let builds = 0;
    const start = Date.now();
    // The entry already reads as current while the holder still writes the
    // rest of the build.
    ensureBuiltOnce({
      isBuilt: () => true,
      build: () => {
        builds += 1;
      },
      lockDir,
      pollMs: 20,
    });
    const waited = Date.now() - start;
    await exited;
    expect(builds).toBe(0);
    expect(waited).toBeGreaterThanOrEqual(350);
  });

  it('returns at once when the build is current and nobody holds the lock', () => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-build-lock-'));
    let builds = 0;
    const start = Date.now();
    ensureBuiltOnce({
      isBuilt: () => true,
      build: () => {
        builds += 1;
      },
      lockDir: path.join(dir, 'lock'),
    });
    expect(builds).toBe(0);
    expect(Date.now() - start).toBeLessThan(200);
  });

  it('builds once under the lock when the build is stale, then releases it', () => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-build-lock-'));
    const lockDir = path.join(dir, 'lock');
    let built = false;
    let heldDuringBuild = false;
    ensureBuiltOnce({
      isBuilt: () => built,
      build: () => {
        heldDuringBuild = fs.existsSync(lockDir);
        built = true;
      },
      lockDir,
    });
    expect(built).toBe(true);
    expect(heldDuringBuild).toBe(true);
    expect(fs.existsSync(lockDir)).toBe(false);
  });
});

describe('ensureCoreBuiltAt', () => {
  it('builds a missing Core', () => {
    const {entry, roots} = tree();
    fs.rmSync(entry);
    let builds = 0;
    ensureCoreBuiltAt({
      entry,
      roots,
      build: () => {
        builds++;
      },
      lockDir: path.join(dir, 'lock'),
    });
    expect(builds).toBe(1);
  });

  it('leaves a present build alone in a suite, even when a source changed after it', () => {
    // A Core edit while the suites run must not rebuild under them: the
    // build deletes dist first, and suites still reading it fail.
    const {source, entry, roots} = tree();
    fs.utimesSync(source, 3000, 3000);
    expect(coreBuildIsStale(entry, roots)).toBe(true);
    let builds = 0;
    ensureCoreBuiltAt({
      entry,
      roots,
      build: () => {
        builds++;
      },
      lockDir: path.join(dir, 'lock'),
    });
    expect(builds).toBe(0);
  });

  it('rebuilds a build older than a source when asked, as the global setup does', () => {
    const {source, entry, roots} = tree();
    fs.utimesSync(source, 3000, 3000);
    let builds = 0;
    ensureCoreBuiltAt({
      entry,
      roots,
      build: () => {
        builds++;
      },
      lockDir: path.join(dir, 'lock'),
      rebuildStale: true,
    });
    expect(builds).toBe(1);
  });

  it('is asked to rebuild a stale Core only by the node global setup', () => {
    const setup = fs.readFileSync(
      path.join(REPO_ROOT, 'vitest.global-setup.node.mjs'),
      'utf8',
    );
    expect(setup).toContain('await ensureCoreBuiltForRun();');
    const suites = [];
    const walk = current => {
      for (const entry of fs.readdirSync(current, {withFileTypes: true})) {
        const full = path.join(current, entry.name);
        if (entry.isDirectory()) {
          if (entry.name !== 'node_modules') walk(full);
        } else if (
          entry.name.endsWith('.test.mjs') &&
          /ensureCoreBuiltForRun\(|ensureCoreBuilt\([^)]*rebuildStale/.test(
            fs.readFileSync(full, 'utf8'),
          )
        ) {
          suites.push(path.relative(REPO_ROOT, full));
        }
      }
    };
    walk(path.join(REPO_ROOT, 'packages/cli'));
    expect(suites).toEqual([]);
  });
});

describe('coreBuildLockDir', () => {
  it('gives each checkout its own lock', () => {
    expect(coreBuildLockDir('/work/a')).not.toBe(coreBuildLockDir('/work/b'));
    expect(coreBuildLockDir('/work/a')).toBe(coreBuildLockDir('/work/a/'));
    expect(path.dirname(coreBuildLockDir('/work/a'))).toBe(os.tmpdir());
  });

  it("does not keep a checkout with a current build waiting on another checkout's build", () => {
    const {entry, roots} = tree();
    const other = coreBuildLockDir(path.join(dir, 'other-checkout'));
    fs.mkdirSync(other);
    try {
      const started = Date.now();
      ensureCoreBuiltAt({
        entry,
        roots,
        build: () => {
          throw new Error('a current build is not rebuilt');
        },
        lockDir: coreBuildLockDir(dir),
        staleLockMs: 5000,
        pollMs: 50,
      });
      expect(Date.now() - started).toBeLessThan(1000);
    } finally {
      fs.rmSync(other, {recursive: true, force: true});
    }
  });
});

describe('the build marker', () => {
  it("is the output Core's build writes last, after the modules and their declarations", () => {
    const {scripts} = JSON.parse(
      fs.readFileSync(
        path.join(REPO_ROOT, 'packages/core/package.json'),
        'utf8',
      ),
    );
    const steps = scripts.build.split('&&').map(step => step.trim());
    const at = name => steps.findIndex(step => step.includes(name));
    expect(path.relative(REPO_ROOT, CORE_BUILD_MARKER)).toBe(
      'packages/core/dist/astryx.css',
    );
    expect(at('build:css')).toBeGreaterThan(at('build:esm'));
    expect(at('build:css')).toBeGreaterThan(at('tsc '));
    expect(at('build:css')).toBeGreaterThan(at('add-declaration-extensions'));
    expect(scripts['build:css']).toContain('build-css.mjs');
    expect(
      fs.readFileSync(path.join(REPO_ROOT, 'scripts/build-css.mjs'), 'utf8'),
    ).toContain("outFile: 'astryx.css'");
  });

  it('rebuilds a build that stopped before its marker, even when its modules are newer than every source', () => {
    // A rebuild interrupted after Babel wrote dist/theme/index.js, before the
    // declarations and the stylesheet: the marker is missing.
    const {write, roots} = tree();
    write('dist/theme/index.js', 'export {};', 3000);
    let builds = 0;
    ensureCoreBuiltAt({
      entry: path.join(dir, 'dist/astryx.css'),
      roots,
      build: () => {
        builds++;
      },
      lockDir: path.join(dir, 'lock'),
    });
    expect(builds).toBe(1);
  });
});

describe("Core's build inputs", () => {
  it("cover every script and config file Core's build scripts write output with, and every local file those load", () => {
    const coreDir = path.join(REPO_ROOT, 'packages/core');
    const {scripts} = JSON.parse(
      fs.readFileSync(path.join(coreDir, 'package.json'), 'utf8'),
    );
    const inputs = new Set();
    for (const [name, command] of Object.entries(scripts)) {
      if (!/^build(:|$)/.test(name)) continue;
      for (const [, file] of command.matchAll(/\bnode\s+(\S+\.m?js)/g)) {
        // Checks read the build; they write nothing it depends on.
        if (!/\/(check-|clean-dist)/.test(file)) inputs.add(file);
      }
      for (const [, file] of command.matchAll(
        /--(?:config-file|project)\s+(\S+)/g,
      )) {
        inputs.add(file);
      }
    }
    const covered = file =>
      CORE_SOURCES.some(root => {
        const relative = path.relative(root, file);
        return (
          relative === '' ||
          (!relative.startsWith('..') && !path.isAbsolute(relative))
        );
      });
    // Follow what those files load: a config's local plugins and presets, and
    // a script's relative imports, transitively.
    const resolveLocal = (from, specifier) => {
      const base = path.resolve(path.dirname(from), specifier);
      return ['', '.mjs', '.js', '.cjs', '.json']
        .map(ext => base + ext)
        .find(
          candidate =>
            fs.existsSync(candidate) && fs.statSync(candidate).isFile(),
        );
    };
    const queue = [...inputs].map(file => path.resolve(coreDir, file));
    const seen = new Set();
    while (queue.length > 0) {
      const file = queue.pop();
      if (seen.has(file) || !fs.existsSync(file)) continue;
      seen.add(file);
      const text = fs.readFileSync(file, 'utf8');
      const local = [];
      if (file.endsWith('.json')) {
        const config = JSON.parse(text);
        for (const entry of [
          ...(config.plugins ?? []),
          ...(config.presets ?? []),
        ]) {
          const name = Array.isArray(entry) ? entry[0] : entry;
          if (typeof name === 'string' && /^\.\.?\//.test(name))
            local.push(name);
        }
        if (
          typeof config.extends === 'string' &&
          /^\.\.?\//.test(config.extends)
        ) {
          local.push(config.extends);
        }
      } else {
        for (const [, specifier] of text.matchAll(
          /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)['"](\.\.?\/[^'"]+)['"]/g,
        )) {
          local.push(specifier);
        }
      }
      for (const specifier of local) {
        const target = resolveLocal(file, specifier);
        if (target) queue.push(target);
      }
    }
    const missing = [...seen]
      .filter(file => !covered(file))
      .map(file => path.relative(REPO_ROOT, file));
    expect(inputs.size).toBeGreaterThan(3);
    expect(seen.size).toBeGreaterThan(inputs.size);
    expect(missing).toEqual([]);
  });
});

describe('run leases', () => {
  /** A stale build (a source newer than it) and a lease directory. */
  function staleTree() {
    const built = tree();
    fs.utimesSync(built.source, 3000, 3000);
    return {...built, leaseDir: path.join(dir, 'runs')};
  }

  /** The node global setup's Core step over a made-up checkout. */
  function forRun(built, options) {
    const builds = [];
    const done = ensureCoreBuiltForRunAt({
      entry: built.entry,
      roots: built.roots,
      build: () => builds.push(Date.now()),
      lockDir: path.join(dir, 'lock'),
      leaseDir: built.leaseDir,
      pollMs: 20,
      ...options,
    });
    return {builds, done};
  }

  it('make a stale rebuild wait until a run that started before it has ended', async () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: 101, now: 1});
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 2});
    const ends = Date.now() + 300;
    const {builds, done} = forRun(built, {
      isAlive: pid => pid === 101 && Date.now() < ends,
    });
    await done;
    expect(builds).toHaveLength(1);
    expect(builds[0]).toBeGreaterThanOrEqual(ends);
  });

  it('wait on a timer, so the run stays stoppable: its timers and signal handlers run meanwhile', async () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: 101, now: 1});
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 2});
    const ends = Date.now() + 300;
    let timerAt = 0;
    setTimeout(() => {
      timerAt = Date.now();
    }, 50);
    const {builds, done} = forRun(built, {
      isAlive: pid => pid === 101 && Date.now() < ends,
    });
    await done;
    expect(timerAt).toBeGreaterThan(0);
    expect(timerAt).toBeLessThan(builds[0]);
  });

  it('give up after the limit: the run stops with an error naming the live run, and rebuilds nothing', async () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: 101, now: 1});
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 2});
    // The wait announces itself once; this test reads only the outcome.
    const announced = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      const startedAt = Date.now();
      const {builds, done} = forRun(built, {
        isAlive: pid => pid === 101,
        limitMs: 150,
      });
      const error = await done.catch(e => e);
      expect(error.message).toMatch(
        /test run 101 in this checkout still uses that build/,
      );
      // A leftover lease (a run killed by SIGHUP) can name another process
      // that took its pid: the message names the file to remove.
      expect(error.message).toContain(path.join(built.leaseDir, '101'));
      expect(Date.now() - startedAt).toBeLessThan(2000);
      expect(builds).toEqual([]);
      expect(coreBuildIsStale(built.entry, built.roots)).toBe(true);
      expect(announced.mock.calls[0]?.[0]).toMatch(/waiting up to 0 s/);
    } finally {
      announced.mockRestore();
    }
  });

  it('throw on a lease directory it cannot read, rather than read it as empty', () => {
    const built = staleTree();
    fs.writeFileSync(built.leaseDir, 'not a directory');
    expect(() => earlierLiveRuns(built.leaseDir)).toThrow(/ENOTDIR/);
  });

  it('throw on a lease it cannot read, rather than read it as no start time', () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 2});
    fs.mkdirSync(path.join(built.leaseDir, '101'));
    expect(() =>
      earlierLiveRuns(built.leaseDir, {isAlive: () => true}),
    ).toThrow(/EISDIR/);
  });

  it('throw on a lease whose process id the system refuses, rather than read the run as ended and remove its lease', () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 2});
    registerTestRun({leaseDir: built.leaseDir, pid: 2 ** 31, now: 1});
    expect(() => earlierLiveRuns(built.leaseDir)).toThrow(/pid/);
    expect(fs.existsSync(path.join(built.leaseDir, String(2 ** 31)))).toBe(
      true,
    );
  });

  it('let a run that started later wait instead, so two runs never wait for each other', async () => {
    const built = staleTree();
    registerTestRun({leaseDir: built.leaseDir, pid: process.pid, now: 1});
    registerTestRun({leaseDir: built.leaseDir, pid: 202, now: 2});
    expect(earlierLiveRuns(built.leaseDir, {isAlive: () => true})).toEqual([]);
    expect(
      earlierLiveRuns(built.leaseDir, {pid: 202, isAlive: () => true}),
    ).toEqual([process.pid]);
    const {builds, done} = forRun(built, {isAlive: () => true});
    await done;
    expect(builds).toHaveLength(1);
  });

  it('drop the lease of a run whose process is gone', () => {
    const {leaseDir} = staleTree();
    registerTestRun({leaseDir, pid: 303, now: 1});
    registerTestRun({leaseDir, pid: process.pid, now: 2});
    expect(earlierLiveRuns(leaseDir, {isAlive: () => false})).toEqual([]);
    expect(fs.readdirSync(leaseDir)).toEqual([String(process.pid)]);
  });

  it('end with the process too: a run stopped with Ctrl-C, which calls no teardown, leaves no lease', async () => {
    const {leaseDir} = staleTree();
    const helper = path.join(
      REPO_ROOT,
      'packages/cli/clients/cli/commands/ensure-core-built.mjs',
    );
    // The node global setup's pattern: a lease ended on exit, in a process
    // that exits on SIGINT as Vitest does.
    const child = spawn(
      process.execPath,
      [
        '--input-type=module',
        '-e',
        [
          `import {registerTestRun} from ${JSON.stringify(helper)};`,
          `const endRun = registerTestRun({leaseDir: ${JSON.stringify(leaseDir)}});`,
          "process.once('exit', endRun);",
          "process.on('SIGINT', () => process.exit(130));",
          "console.log('ready');",
          'setInterval(() => {}, 1000);',
        ].join('\n'),
      ],
      {stdio: ['ignore', 'pipe', 'inherit']},
    );
    await new Promise(resolve => child.stdout.once('data', resolve));
    expect(fs.readdirSync(leaseDir)).toEqual([String(child.pid)]);
    const exited = new Promise(resolve => child.once('exit', resolve));
    child.kill('SIGINT');
    expect(await exited).toBe(130);
    expect(fs.readdirSync(leaseDir)).toEqual([]);
  });

  it("end with the run: the teardown removes this run's lease", () => {
    const {leaseDir} = staleTree();
    const end = registerTestRun({leaseDir});
    expect(fs.readdirSync(leaseDir)).toEqual([String(process.pid)]);
    end();
    expect(fs.readdirSync(leaseDir)).toEqual([]);
  });

  it('are held by the node global setup for its whole run, beside its own lock', () => {
    const setup = fs.readFileSync(
      path.join(REPO_ROOT, 'vitest.global-setup.node.mjs'),
      'utf8',
    );
    expect(setup).toMatch(
      /export default async function setup\(project\) \{[\s\S]*const endRun = registerTestRun\(\);\s*process\.once\('exit', endRun\);\s*try \{[\s\S]*await ensureCoreBuiltForRun\(\);[\s\S]*return \(\) => \{[\s\S]*endRun\(\);\s*\};\s*\} catch \(error\) \{\s*endRun\(\);\s*throw error;\s*\}/,
    );
    expect(path.dirname(coreRunLeaseDir(REPO_ROOT))).toBe(
      path.dirname(coreBuildLockDir(REPO_ROOT)),
    );
    expect(coreRunLeaseDir(REPO_ROOT)).not.toBe(coreBuildLockDir(REPO_ROOT));
  });
});