scripts/correctness/test262-corpus.mjs

GitHub
#!/usr/bin/env node

import { spawnSync } from "node:child_process";
import {
  existsSync,
  mkdirSync,
  realpathSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));

export const defaultTest262ConfigPath = join(
  repoRoot,
  "scripts",
  "correctness",
  "test262-upstreams.json",
);
export const defaultManagedTest262Root = join(
  repoRoot,
  "target",
  "correctness-tools",
  "test262",
  "vendor",
);

export function loadTest262Upstream(configPath = defaultTest262ConfigPath) {
  const config = JSON.parse(readFileSync(configPath, "utf8"));
  if (config.schemaVersion !== 1) {
    throw new Error(`unsupported Test262 upstream schema ${config.schemaVersion}`);
  }
  const upstream = config.test262;
  if (!upstream || typeof upstream.url !== "string" || upstream.url.length === 0) {
    throw new Error("Test262 upstream URL must be a non-empty string");
  }
  validateRevision(upstream.revision);
  return { schemaVersion: config.schemaVersion, ...upstream };
}

export function inspectTest262Corpus({
  root = defaultManagedTest262Root,
  configPath = defaultTest262ConfigPath,
} = {}) {
  const upstream = loadTest262Upstream(configPath);
  const absoluteRoot = resolve(root);
  if (!existsSync(absoluteRoot)) {
    return corpusStatus(absoluteRoot, upstream, {
      exists: false,
      repository: false,
    });
  }
  if (!isGitRepository(absoluteRoot)) {
    return corpusStatus(absoluteRoot, upstream, {
      exists: true,
      repository: false,
    });
  }

  const head = gitText(absoluteRoot, ["rev-parse", "HEAD"], {
    allowFailure: true,
  });
  const dirty = gitText(absoluteRoot, ["status", "--porcelain"]).length > 0;
  const origin = gitText(absoluteRoot, ["remote", "get-url", "origin"], {
    allowFailure: true,
  });
  return corpusStatus(absoluteRoot, upstream, {
    exists: true,
    repository: true,
    head,
    dirty,
    origin: origin || null,
  });
}

export function setupTest262Corpus({
  root = defaultManagedTest262Root,
  configPath = defaultTest262ConfigPath,
  offline = false,
  force = false,
  upstream = loadTest262Upstream(configPath),
} = {}) {
  const absoluteRoot = resolve(root);
  prepareRepository(absoluteRoot, upstream, { force });

  let status = inspectTest262CorpusWithUpstream(absoluteRoot, upstream);
  if (status.origin !== upstream.url) {
    if (status.dirty) {
      throw new Error(
        `refusing to replace dirty Test262 checkout at ${absoluteRoot}: origin is ${status.origin ?? "missing"}, expected ${upstream.url}`,
      );
    }
    if (status.origin && !force) {
      throw new Error(
        `Test262 checkout origin is ${status.origin}, expected ${upstream.url}; rerun with --force to replace it`,
      );
    }
    if (status.origin) {
      git(absoluteRoot, ["remote", "set-url", "origin", upstream.url]);
    } else {
      git(absoluteRoot, ["remote", "add", "origin", upstream.url]);
    }
    status = inspectTest262CorpusWithUpstream(absoluteRoot, upstream);
  }
  if (status.dirty) {
    if (!force) {
      throw new Error(
        `refusing to modify dirty Test262 checkout at ${absoluteRoot}; clean it or rerun with --force`,
      );
    }
    rmSync(absoluteRoot, { recursive: true, force: true });
    prepareRepository(absoluteRoot, upstream, { force: false });
    status = inspectTest262CorpusWithUpstream(absoluteRoot, upstream);
  }

  if (status.head !== upstream.revision) {
    if (offline) {
      const available = git(absoluteRoot, ["cat-file", "-e", `${upstream.revision}^{commit}`], {
        allowFailure: true,
      }).status === 0;
      if (!available) {
        throw new Error(
          `pinned Test262 revision ${upstream.revision} is unavailable offline at ${absoluteRoot}`,
        );
      }
      git(absoluteRoot, ["checkout", "--detach", upstream.revision]);
    } else {
      git(absoluteRoot, ["fetch", "--depth=1", "origin", upstream.revision]);
      git(absoluteRoot, ["checkout", "--detach", "FETCH_HEAD"]);
    }
  }

  status = inspectTest262CorpusWithUpstream(absoluteRoot, upstream);
  if (!status.ready) {
    throw new Error(
      `Test262 setup ended at ${status.head ?? "no revision"}, expected ${upstream.revision}`,
    );
  }
  return status;
}

export function updateTest262Pin({
  revision,
  root = defaultManagedTest262Root,
  configPath = defaultTest262ConfigPath,
  offline = false,
  force = false,
} = {}) {
  validateRevision(revision);
  const current = loadTest262Upstream(configPath);
  const upstream = { ...current, revision };
  const status = setupTest262Corpus({
    root,
    configPath,
    offline,
    force,
    upstream,
  });
  const config = {
    schemaVersion: current.schemaVersion,
    test262: {
      url: upstream.url,
      revision: upstream.revision,
    },
  };
  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
  return status;
}

export function assertPinnedTest262Corpus({
  root = defaultManagedTest262Root,
  configPath = defaultTest262ConfigPath,
} = {}) {
  const status = inspectTest262Corpus({ root, configPath });
  if (!status.ready || status.dirty) {
    const reason = !status.exists
      ? "is missing"
      : !status.repository
        ? "is not a git checkout"
        : status.dirty
          ? "is dirty"
          : `is at ${status.head}, expected ${status.configuredRevision}`;
    throw new Error(
      `managed Test262 checkout ${reason}; run \`node scripts/correctness/test262-corpus.mjs setup\``,
    );
  }
  return status;
}

export function readTest262Revision(root) {
  const absoluteRoot = resolve(root);
  if (!isGitRepository(absoluteRoot)) {
    return null;
  }
  return gitText(absoluteRoot, ["rev-parse", "HEAD"], { allowFailure: true }) || null;
}

function corpusStatus(root, upstream, actual) {
  return {
    root,
    configuredUrl: upstream.url,
    configuredRevision: upstream.revision,
    exists: actual.exists,
    repository: actual.repository,
    head: actual.head ?? null,
    dirty: actual.dirty ?? false,
    origin: actual.origin ?? null,
    ready:
      actual.repository === true &&
      actual.head === upstream.revision &&
      actual.dirty !== true &&
      actual.origin === upstream.url,
  };
}

function inspectTest262CorpusWithUpstream(root, upstream) {
  if (!existsSync(root) || !isGitRepository(root)) {
    return corpusStatus(root, upstream, {
      exists: existsSync(root),
      repository: false,
    });
  }
  const origin = gitText(root, ["remote", "get-url", "origin"], {
    allowFailure: true,
  });
  return corpusStatus(root, upstream, {
    exists: true,
    repository: true,
    head: gitText(root, ["rev-parse", "HEAD"], { allowFailure: true }) || null,
    dirty: gitText(root, ["status", "--porcelain"]).length > 0,
    origin: origin || null,
  });
}

function prepareRepository(root, upstream, { force }) {
  if (existsSync(root) && !isGitRepository(root)) {
    const nonEmpty = readdirSync(root).length > 0;
    if (nonEmpty && !force) {
      throw new Error(
        `refusing to replace non-git Test262 directory at ${root}; rerun with --force`,
      );
    }
    if (force) {
      rmSync(root, { recursive: true, force: true });
    }
  }
  if (!existsSync(root)) {
    mkdirSync(dirname(root), { recursive: true });
    mkdirSync(root, { recursive: true });
  }
  if (!isGitRepository(root)) {
    git(root, ["init"]);
    git(root, ["remote", "add", "origin", upstream.url]);
  }
}

function isGitRepository(root) {
  if (!existsSync(root)) {
    return false;
  }
  const result = spawnSync("git", ["-C", root, "rev-parse", "--show-toplevel"], {
    encoding: "utf8",
  });
  return (
    result.status === 0 &&
    realpathSync(result.stdout.trim()) === realpathSync(root)
  );
}

function gitText(root, args, options = {}) {
  const result = git(root, args, options);
  if (result.status !== 0) {
    return "";
  }
  return result.stdout.trim();
}

function git(root, args, { allowFailure = false } = {}) {
  const result = spawnSync("git", ["-C", root, ...args], {
    encoding: "utf8",
    maxBuffer: 10 * 1024 * 1024,
    env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
  });
  if (result.error) {
    throw new Error(`git ${args.join(" ")} failed: ${result.error.message}`);
  }
  if (result.status !== 0 && !allowFailure) {
    throw new Error(
      `git ${args.join(" ")} failed with exit ${result.status}\n${result.stderr || result.stdout}`,
    );
  }
  return result;
}

function validateRevision(revision) {
  if (typeof revision !== "string" || !/^[0-9a-f]{40}$/i.test(revision)) {
    throw new Error("Test262 revision must be a full 40-character commit SHA");
  }
}

function parseArgs(argv) {
  const command = argv[0];
  if (!command || !["setup", "status", "update"].includes(command)) {
    throw new Error(usage());
  }
  const options = {
    command,
    root: defaultManagedTest262Root,
    configPath: defaultTest262ConfigPath,
    offline: false,
    force: false,
    json: false,
    revision: null,
  };
  for (let index = 1; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === "--root") {
      options.root = resolve(readValue(argv, ++index, arg));
    } else if (arg === "--config") {
      options.configPath = resolve(readValue(argv, ++index, arg));
    } else if (arg === "--revision") {
      options.revision = readValue(argv, ++index, arg);
    } else if (arg === "--offline") {
      options.offline = true;
    } else if (arg === "--force") {
      options.force = true;
    } else if (arg === "--json") {
      options.json = true;
    } else {
      throw new Error(`unknown option: ${arg}`);
    }
  }
  return options;
}

function readValue(argv, index, option) {
  const value = argv[index];
  if (!value || value.startsWith("-")) {
    throw new Error(`${option} requires a value`);
  }
  return value;
}

function usage() {
  return `Usage:
  node scripts/correctness/test262-corpus.mjs setup [--offline] [--force]
  node scripts/correctness/test262-corpus.mjs status [--json]
  node scripts/correctness/test262-corpus.mjs update --revision <full-sha> [--force]

Options:
  --root <dir>       Override the managed checkout directory
  --config <file>    Override the tracked upstream manifest
  --offline          Require the pinned commit to exist locally
  --force            Explicitly replace dirty or mismatched fixture state
  --json             Print machine-readable status
`;
}

function printStatus(status, json) {
  if (json) {
    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
    return;
  }
  console.log(`root: ${status.root}`);
  console.log(`configured revision: ${status.configuredRevision}`);
  console.log(`checkout revision: ${status.head ?? "missing"}`);
  console.log(`dirty: ${status.dirty}`);
  console.log(`ready: ${status.ready}`);
}

function isMain() {
  return process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
}

if (isMain()) {
  try {
    const options = parseArgs(process.argv.slice(2));
    let status;
    if (options.command === "setup") {
      status = setupTest262Corpus(options);
    } else if (options.command === "update") {
      if (!options.revision) {
        throw new Error("update requires --revision <full-sha>");
      }
      status = updateTest262Pin(options);
    } else {
      status = inspectTest262Corpus(options);
    }
    printStatus(status, options.json);
    if (options.command === "status" && !status.ready) {
      process.exitCode = 1;
    }
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    process.exitCode = 1;
  }
}