Skip to content

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

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

/**
 * The measurement build root, against a real pnpm virtual store.
 *
 * The measurer's build must not touch the sandbox it measures: that tree is the
 * attested artifact, and a build in place regenerates the app-owned theme,
 * writes `dist/`, appends to the CLI's invocation log, and caches into
 * `node_modules`, after which the cell no longer hashes to its own digest.
 *
 * A pnpm `node_modules` makes that harder than copying files, because it is
 * mostly links into a virtual store:
 *
 *   node_modules/is-odd          -> .pnpm/[email protected]/node_modules/is-odd
 *   node_modules/.pnpm/<id>/...  the real package trees
 *   node_modules/.modules.yaml   the store's own state
 *
 * Mirroring `.pnpm` with a symlink — which is what this did first — hands the
 * copy a door back into the original: an install or rebuild that rewrites the
 * store writes straight through it. These cases use a real `pnpm install` for
 * the fixture rather than a hand-drawn imitation, because the shape is the
 * thing being tested.
 *
 * The cases are the guarantee, not the construction: the sandbox is unchanged
 * after a build in the copy, the copy is a working tree, and the isolation
 * check catches both ways of getting it wrong. How the copier achieves that is
 * deliberately not asserted.
 */

import {execFileSync, spawnSync} from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {afterAll, afterEach, beforeAll, describe, expect, it} from 'vitest';
import {measurementPrivateValues, publicMeasurement} from './setup-measure.mjs';
import {
  createMeasurementWorkspace,
  manifestDifferences,
  retargetEscapingLinks,
  treeManifest,
  verifyWorkspaceIsolation,
} from './setup-workspace.mjs';

const temporaryDirectories = [];
/** One real install, reused: the shape is what matters, not the download. */
let installedFixture = null;

function temporary(prefix) {
  const directory = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
  temporaryDirectories.push(directory);
  return directory;
}

function write(root, relativePath, content, mode) {
  const file = path.join(root, relativePath);
  fs.mkdirSync(path.dirname(file), {recursive: true});
  fs.writeFileSync(file, content);
  if (mode !== undefined) fs.chmodSync(file, mode);
}

function pnpm(args, cwd) {
  return spawnSync('pnpm', args, {
    cwd,
    encoding: 'utf8',
    env: {...process.env, CI: 'true'},
    stdio: ['ignore', 'pipe', 'pipe'],
  });
}

/** Whether a real pnpm is reachable; without one these cases cannot run. */
function pnpmAvailable() {
  const result = pnpm(['--version'], os.tmpdir());
  return result.status === 0 && /^\d+\./.test((result.stdout ?? '').trim());
}

const HAS_PNPM = pnpmAvailable();
const describeWithPnpm = HAS_PNPM ? describe : describe.skip;

/**
 * A sandbox with a real pnpm `node_modules`, plus the files a measured arm
 * carries: a committed generated theme artifact, ignored build output, the
 * CLI's invocation log, an executable script, and a link out to a workspace
 * package.
 */
function installedSandbox() {
  if (!installedFixture) {
    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-workspace-src-'));
    temporaryDirectories.push(root);
    const app = path.join(root, 'app');
    fs.mkdirSync(app, {recursive: true});
    write(
      app,
      'package.json',
      `${JSON.stringify(
        {
          name: 'host',
          private: true,
          // `is-odd` pulls `is-number`, so the store has a package that depends
          // on another one and the relative link between them is exercised.
          dependencies: {'is-odd': '3.0.1'},
          scripts: {build: 'node build.mjs'},
        },
        null,
        2,
      )}\n`,
    );
    const install = pnpm(['install', '--ignore-scripts'], app);
    if (install.status !== 0) {
      throw new Error(`fixture install failed: ${install.stderr}`);
    }
    installedFixture = {root, app};
  }

  // Each case gets its own copy of that installed tree, so one case's install
  // cannot be seen by the next.
  const root = temporary('setup-workspace-test-');
  const app = path.join(root, 'app');
  execFileSync('cp', ['-a', '--reflink=auto', installedFixture.app, app]);

  write(app, '.gitignore', 'node_modules/\ndist/\n');
  write(app, 'index.html', '<!doctype html>\n<html lang="en"></html>\n');
  write(app, 'src/App.tsx', 'export const App = () => null;\n');
  write(app, 'src/index.css', "@import 'tailwindcss';\n");
  write(
    app,
    'src/apptheme.css',
    '/* @generated by `astryx theme build` */\n:root { color-scheme: light dark; }\n',
  );
  write(app, 'src/apptheme.d.ts', 'export declare const theme: unknown;\n');
  write(app, 'dist/index.html', '<!doctype html>\n');
  write(app, 'dist/assets/app.css', '@layer reset, theme;\n');
  write(app, '.astryx-invocations.log', 'theme build\n');
  write(app, 'scripts/run.sh', '#!/bin/sh\necho ok\n', 0o755);
  fs.symlinkSync('./index.css', path.join(app, 'src/alias.css'));

  // A workspace package linked in by absolute path, the way the canonical
  // harness links the design system's own source into an arm.
  const workspace = path.join(root, 'workspace-package');
  fs.mkdirSync(workspace, {recursive: true});
  write(workspace, 'package.json', '{"name": "@scope/workspace"}\n');
  fs.mkdirSync(path.join(app, 'node_modules/@scope'), {recursive: true});
  fs.symlinkSync(workspace, path.join(app, 'node_modules/@scope/workspace'));

  return {root, app, workspace};
}

/**
 * A build script that does to its own tree exactly what a real one does:
 * regenerate the theme, write dist, append to the log, cache in node_modules.
 */
function withBuildScript(app, {fails = false} = {}) {
  write(
    app,
    'build.mjs',
    [
      "import * as fs from 'node:fs';",
      // A build that finds no TTY must not ask anything or fall over.
      "if (process.stdout.isTTY) throw new Error('unexpected TTY');",
      "fs.writeFileSync('src/apptheme.css', '/* rebuilt */\\n');",
      "fs.mkdirSync('dist/assets', {recursive: true});",
      "fs.writeFileSync('dist/index.html', '<!doctype html>\\n');",
      "fs.writeFileSync('dist/assets/app.css', '@layer reset, theme;\\n');",
      "fs.appendFileSync('.astryx-invocations.log', 'build\\n');",
      "fs.mkdirSync('node_modules/.vite', {recursive: true});",
      "fs.writeFileSync('node_modules/.vite/cache.json', '{}\\n');",
      // Rewrite a file inside the virtual store, which is the write that used
      // to reach the original through the mirrored `.pnpm` link.
      "fs.writeFileSync('node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js', 'module.exports = 1;\\n');",
      ...(fails ? ['process.exit(1);'] : []),
    ].join('\n'),
  );
}

/** The whole tree, hashed — including every file in the virtual store. */
const manifest = root => treeManifest(root);

afterEach(() => {
  while (temporaryDirectories.length > 0) {
    const directory = temporaryDirectories.pop();
    if (installedFixture && directory === installedFixture.root) continue;
    fs.rmSync(directory, {recursive: true, force: true});
  }
});

afterAll(() => {
  if (installedFixture) {
    fs.rmSync(installedFixture.root, {recursive: true, force: true});
    installedFixture = null;
  }
});

describeWithPnpm('measurement build root over a pnpm virtual store', () => {
  beforeAll(() => {
    // Warm the shared install once so the first case is not timed with it.
    installedSandbox();
  }, 300_000);

  it.each([
    {name: 'a build that succeeds', fails: false},
    {name: 'a build that fails', fails: true},
  ])(
    'leaves the sandbox byte-identical after $name in the copy',
    ({fails}) => {
      const {app} = installedSandbox();
      withBuildScript(app, {fails});
      const before = manifest(app);
      const copy = createMeasurementWorkspace(app);

      const result = pnpm(['build'], copy.dir);
      expect(result.status).toBe(fails ? 1 : 0);
      // Non-interactive: nothing complained about a missing terminal.
      expect(`${result.stdout}${result.stderr}`).not.toMatch(/TTY|tty/);

      // The build really did write, in the copy — including into the virtual
      // store, which is the write that used to reach the original.
      expect(
        fs.readFileSync(path.join(copy.dir, 'src/apptheme.css'), 'utf8'),
      ).toBe('/* rebuilt */\n');
      expect(
        fs.readFileSync(
          path.join(
            copy.dir,
            'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js',
          ),
          'utf8',
        ),
      ).toBe('module.exports = 1;\n');

      // And none of it reached the sandbox, virtual store included.
      expect(manifestDifferences(before, manifest(app))).toEqual([]);

      copy.cleanup();
      expect(manifestDifferences(before, manifest(app))).toEqual([]);
    },
    300_000,
  );

  it('survives an install in the copy recreating the whole virtual store', () => {
    const {app} = installedSandbox();
    const before = manifest(app);
    const copy = createMeasurementWorkspace(app);

    // The strongest case: throw the copy's store away and have pnpm rebuild
    // it. Through a mirrored `.pnpm` link this would have deleted and rewritten
    // the sandbox's own store.
    fs.rmSync(path.join(copy.dir, 'node_modules/.pnpm'), {
      recursive: true,
      force: true,
    });
    const install = pnpm(['install', '--ignore-scripts'], copy.dir);
    expect(install.status, install.stderr).toBe(0);

    expect(manifestDifferences(before, manifest(app))).toEqual([]);
    copy.cleanup();
    expect(manifestDifferences(before, manifest(app))).toEqual([]);
  }, 300_000);

  it('hands back a working tree, resolving inside itself', () => {
    const {app, workspace: workspacePackage} = installedSandbox();
    const copy = createMeasurementWorkspace(app);

    // Module resolution works from the copy, and lands in the copy.
    const resolved = spawnSync(
      process.execPath,
      ['-e', "process.stdout.write(require.resolve('is-odd'))"],
      {cwd: copy.dir, encoding: 'utf8'},
    );
    expect(resolved.status, resolved.stderr).toBe(0);
    expect(resolved.stdout.startsWith(fs.realpathSync(copy.dir))).toBe(true);

    // A link out to a workspace package is left pointing where it pointed: it
    // is not the sandbox, and rewriting it would break resolution.
    expect(
      fs.realpathSync(path.join(copy.dir, 'node_modules/@scope/workspace')),
    ).toBe(fs.realpathSync(workspacePackage));

    // Nothing anywhere in the copy can reach the sandbox.
    expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);

    copy.cleanup();
  }, 120_000);

  it('copies the same way on a platform without a usable cp', () => {
    // The pure-Node copier is a second implementation of the same guarantee,
    // and no other case reaches it.
    const {app} = installedSandbox();
    const before = manifest(app);
    const copy = createMeasurementWorkspace(app, {strategy: 'node'});

    expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);
    fs.writeFileSync(
      path.join(
        copy.dir,
        'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js',
      ),
      'module.exports = 2;\n',
    );
    expect(manifestDifferences(before, manifest(app))).toEqual([]);

    copy.cleanup();
  }, 300_000);

  it('removes the build root even when the measurement throws', () => {
    const {app} = installedSandbox();
    const before = manifest(app);
    const copy = createMeasurementWorkspace(app);

    expect(() => {
      try {
        fs.writeFileSync(path.join(copy.dir, 'dist/index.html'), 'partial\n');
        throw new Error('measurement failed');
      } finally {
        copy.cleanup();
      }
    }).toThrow('measurement failed');

    expect(fs.existsSync(copy.dir)).toBe(false);
    expect(manifestDifferences(before, manifest(app))).toEqual([]);
  }, 120_000);
});

/**
 * The mutations: build the copy the two wrong ways and show each is caught.
 *
 * Without these the cases above could be passing for the wrong reason. There
 * are exactly two ways for a copy to stay reachable from the sandbox — a link
 * that resolves back into it, and a file that shares its inode — so there is
 * one mutation for each, and no more.
 */
describeWithPnpm('a copy that is not a copy is caught', () => {
  it('mirroring the virtual store writes through, and is reported', () => {
    const {app} = installedSandbox();
    const packageFile =
      'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js';
    const before = manifest(app);

    // The defective copier: real dirs, but `node_modules` entries symlinked
    // back at the original — which for pnpm means the whole virtual store.
    const mirrored = path.join(temporary('setup-workspace-mutation-'), 'app');
    fs.mkdirSync(mirrored, {recursive: true});
    for (const entry of fs.readdirSync(app, {withFileTypes: true})) {
      const from = path.join(app, entry.name);
      const to = path.join(mirrored, entry.name);
      if (entry.name === 'node_modules') {
        fs.mkdirSync(to, {recursive: true});
        for (const inner of fs.readdirSync(from, {withFileTypes: true})) {
          fs.symlinkSync(path.join(from, inner.name), path.join(to, inner.name));
        }
        continue;
      }
      if (entry.isSymbolicLink()) {
        fs.symlinkSync(fs.readlinkSync(from), to);
        continue;
      }
      if (entry.isDirectory()) {
        execFileSync('cp', ['-a', from, to]);
        continue;
      }
      fs.copyFileSync(from, to);
    }

    // `.pnpm` is a link to the original store, so this write lands there.
    fs.writeFileSync(
      path.join(mirrored, packageFile),
      'module.exports = "written through";\n',
    );
    expect(
      manifestDifferences(before, manifest(app)).join('\n'),
    ).toMatch(/changed: node_modules\/\.pnpm\//);

    // And the isolation check refuses that construction, so a change that
    // reintroduces mirroring cannot ship quietly.
    expect(verifyWorkspaceIsolation(mirrored, app).join('\n')).toMatch(
      /symlink escapes to the sandbox: node_modules\/\.pnpm/,
    );
  }, 120_000);

  it('hardlinking instead of copying is reported', () => {
    const {app} = installedSandbox();
    const dir = path.join(temporary('setup-workspace-hardlink-'), 'app');
    // The other way to get this wrong: the bytes look right and the inode is
    // shared, so a rewrite in the copy reaches the original.
    execFileSync('cp', ['-al', app, dir]);

    expect(
      verifyWorkspaceIsolation(dir, app, {full: true}).join('\n'),
    ).toMatch(/shares an inode with the sandbox/);
  }, 120_000);
});

/**
 * The manifest is the instrument every proof above depends on, so it has to be
 * able to fail. A build's own writes are covered end to end by those cases;
 * these are the two differences a content hash alone would miss.
 */
describe('tree manifest', () => {
  function plainSandbox() {
    const app = path.join(temporary('setup-manifest-test-'), 'app');
    write(app, 'src/App.tsx', 'export const App = () => null;\n');
    write(app, 'scripts/run.sh', '#!/bin/sh\n', 0o755);
    return app;
  }

  it.each([
    {
      name: 'a file touched without its bytes changing',
      mutate: app => {
        const when = new Date(Date.now() + 5_000);
        fs.utimesSync(path.join(app, 'src/App.tsx'), when, when);
      },
      expected: /changed: src\/App\.tsx/,
    },
    {
      name: 'a file whose mode changed and nothing else',
      mutate: app => fs.chmodSync(path.join(app, 'scripts/run.sh'), 0o644),
      expected: /changed: scripts\/run\.sh/,
    },
  ])('reports $name', ({mutate, expected}) => {
    const app = plainSandbox();
    const before = manifest(app);
    mutate(app);
    expect(manifestDifferences(before, manifest(app)).join('\n')).toMatch(
      expected,
    );
  });
});

describe('build root boundaries', () => {
  it('redacts the build root as well as the sandbox', () => {
    const root = temporary('setup-redaction-test-');
    const app = path.join(root, 'app');
    write(app, 'package.json', '{"name": "host"}\n');
    const workspace = createMeasurementWorkspace(app);
    const privateValues = measurementPrivateValues({
      appDir: app,
      outFile: path.join(root, 'measurement.json'),
      buildDir: workspace.dir,
    });
    expect(privateValues).toContain(workspace.dir);
    expect(privateValues).toContain(path.dirname(workspace.dir));

    const exported = publicMeasurement(
      {
        label: 'arm',
        app,
        build: {
          ok: false,
          status: 1,
          ms: 1,
          stdout: `building in ${workspace.dir}\n`,
          stderr: `failed in ${workspace.dir}/src\n`,
        },
        schemes: {},
      },
      {fixtureId: 'enterprise-scoped-synthetic', privateValues},
    );

    const serialized = JSON.stringify(exported);
    expect(serialized).not.toContain(workspace.dir);
    expect(serialized).not.toContain(path.dirname(workspace.dir));
    expect(serialized).not.toContain(app);
    expect(exported.app).toBe('enterprise-scoped-synthetic');

    workspace.cleanup();
  });

  it('moves only the links that would escape, and leaves the rest alone', () => {
    const root = temporary('setup-retarget-test-');
    const app = path.join(root, 'app');
    write(app, 'package.json', '{"name": "host"}\n');
    write(app, 'src/index.css', 'body {}\n');
    fs.symlinkSync('./index.css', path.join(app, 'src/relative.css'));
    fs.symlinkSync(
      path.join(app, 'src/index.css'),
      path.join(app, 'absolute.css'),
    );
    // An absolute link to somewhere that is not the sandbox stays as it is.
    write(root, 'outside.txt', 'shared\n');
    fs.symlinkSync(
      path.join(root, 'outside.txt'),
      path.join(app, 'outside.txt'),
    );

    const copy = path.join(root, 'copy');
    execFileSync('cp', ['-a', app, copy]);
    const rewritten = retargetEscapingLinks(copy, app);

    expect(fs.readlinkSync(path.join(copy, 'src/relative.css'))).toBe(
      './index.css',
    );
    expect(fs.readlinkSync(path.join(copy, 'absolute.css'))).toBe(
      path.join(copy, 'src/index.css'),
    );
    expect(fs.readlinkSync(path.join(copy, 'outside.txt'))).toBe(
      path.join(root, 'outside.txt'),
    );
    expect(rewritten.map(entry => path.relative(copy, entry.link))).toEqual([
      'absolute.css',
    ]);
  });

  it('refuses a sandbox that is not there, and cleans up idempotently', () => {
    expect(() =>
      createMeasurementWorkspace(path.join(os.tmpdir(), 'no-such-sandbox-xyz')),
    ).toThrow(/does not exist/);

    const app = path.join(temporary('setup-cleanup-test-'), 'app');
    write(app, 'package.json', '{"name": "host"}\n');
    const workspace = createMeasurementWorkspace(app);
    workspace.cleanup();
    expect(() => workspace.cleanup()).not.toThrow();
  });
});

/**
 * `--reflink` is GNU coreutils only. A BSD or busybox `cp` rejects it outright
 * — nonzero, nothing copied — and that is a platform, not a fault, so it has
 * to reach the pure-Node copier the same way a missing `cp` does. The
 * distinction that matters is the other one: a `cp` that took the flag and
 * then failed part way through has left debris, and must not be quietly
 * copied over.
 */
describe('a cp that does not support --reflink', () => {
  /**
   * Put a fake `cp` first on PATH. It writes `left-behind.txt` into the
   * destination before failing, so a fallback that did not clear the
   * destination first would be visible in the finished copy.
   */
  function shimCp(script) {
    const bin = temporary('setup-cp-shim-');
    const shim = path.join(bin, 'cp');
    fs.writeFileSync(
      shim,
      [
        '#!/bin/sh',
        'dest=""',
        'for arg in "$@"; do dest="$arg"; done',
        'mkdir -p "$dest"',
        'printf %s "debris" > "$dest/left-behind.txt"',
        script,
      ].join('\n'),
    );
    fs.chmodSync(shim, 0o755);
    const original = process.env.PATH;
    process.env.PATH = `${bin}${path.delimiter}${original}`;
    return () => {
      process.env.PATH = original;
    };
  }

  function plainSandbox() {
    const app = path.join(temporary('setup-reflink-test-'), 'app');
    write(app, 'package.json', '{"name": "host"}\n');
    write(app, 'src/index.css', 'body {}\n');
    write(app, 'scripts/run.sh', '#!/bin/sh\necho ok\n', 0o755);
    fs.symlinkSync('./index.css', path.join(app, 'src/alias.css'));
    return app;
  }

  it('falls back to a complete copy instead of failing the measurement', () => {
    const app = plainSandbox();
    const restore = shimCp(
      [
        // What busybox says; BSD `cp` says `illegal option` and a usage line.
        'echo "cp: unrecognized option \'--reflink=auto\'" >&2',
        'exit 1',
      ].join('\n'),
    );
    try {
      const copy = createMeasurementWorkspace(app);

      // A real copy: contents, modes and symlink text all came across.
      expect(fs.readFileSync(path.join(copy.dir, 'src/index.css'), 'utf8')).toBe(
        'body {}\n',
      );
      expect(
        fs.lstatSync(path.join(copy.dir, 'scripts/run.sh')).mode & 0o777,
      ).toBe(0o755);
      expect(fs.readlinkSync(path.join(copy.dir, 'src/alias.css'))).toBe(
        './index.css',
      );

      // The failed attempt's debris was cleared, not copied over.
      expect(fs.existsSync(path.join(copy.dir, 'left-behind.txt'))).toBe(false);
      expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);

      copy.cleanup();
    } finally {
      restore();
    }
  });

  it('still raises a copy that really failed', () => {
    const app = plainSandbox();
    const restore = shimCp(
      ['echo "cp: cannot stat \'src\': Input/output error" >&2', 'exit 1'].join(
        '\n',
      ),
    );
    try {
      expect(() => createMeasurementWorkspace(app)).toThrow(
        /could not copy the sandbox into a build root: cp: cannot stat/,
      );
    } finally {
      restore();
    }
  });
});