Skip to content

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

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

/**
 * @file Active release branch authority and receipt validation.
 *
 * A release branch releases the fixed-group version main declared at its cut
 * (spec:AST-017 FR47); main publishes canaries only and its versions never move
 * backward (FR46, FR50).
 *
 * @input  .release marker/plan files, authored Changesets, expected branch/head inputs
 * @output fail-closed receipts plus the cut-time release description frozen in the plan digest
 * @position single authority used by release CI, stable publishing, and branch cleanup
 *
 * CI copies this file, release-paths.mjs, and lib/workspace-globs.mjs as
 * trusted policy.
 */

import crypto from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {execFileSync} from 'node:child_process';
import {fileURLToPath} from 'node:url';
import {expandWorkspaceDirs} from '../lib/workspace-globs.mjs';
import {
  classifyReleaseDiff,
  diffEntryFiles,
  isReleaseOutputPath,
  isReleaseTestRepairPath,
} from './release-paths.mjs';

const ROOT = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)),
  '../..',
);
const RELEASE_DIR = '.release';
const MARKER_FILE = 'active.json';
const PLAN_FILE = 'plan.json';
const SHA_RE = /^[0-9a-f]{40}$/;
const VERSION_RE = /^\d+\.\d+\.\d+$/;
const BRANCH_RE = /^release\/v(\d+\.\d+\.\d+)$/;
const CHANGESET_CATEGORIES = new Set([
  'breaking',
  'experimental',
  'component',
  'feat',
  'fix',
  'perf',
  'docs',
  'chore',
]);
const CHANGESET_CATEGORY_ALIASES = {
  bug: 'fix',
  bugfix: 'fix',
  fixes: 'fix',
  feature: 'feat',
  features: 'feat',
  break: 'breaking',
  major: 'breaking',
  components: 'component',
  new: 'component',
  performance: 'perf',
  doc: 'docs',
  refactor: 'chore',
  internal: 'chore',
};

function normalizeChangesetCategory(raw) {
  const category = String(raw ?? '')
    .trim()
    .toLowerCase();
  if (CHANGESET_CATEGORIES.has(category)) return category;
  return CHANGESET_CATEGORY_ALIASES[category] ?? null;
}

function sha256(value) {
  return crypto.createHash('sha256').update(value).digest('hex');
}

function canonicalJson(value) {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  if (value && typeof value === 'object') {
    return `{${Object.keys(value)
      .sort()
      .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
      .join(',')}}`;
  }
  return JSON.stringify(value);
}

/** Order two X.Y.Z versions; null when either is not X.Y.Z. */
function compareVersions(a, b) {
  if (!VERSION_RE.test(a ?? '') || !VERSION_RE.test(b ?? '')) return null;
  const pa = a.split('.').map(Number);
  const pb = b.split('.').map(Number);
  for (let i = 0; i < 3; i += 1) if (pa[i] !== pb[i]) return pa[i] - pb[i];
  return 0;
}

function computePlanDigest(plan) {
  return sha256(canonicalJson(plan));
}

function readJson(file) {
  return JSON.parse(fs.readFileSync(file, 'utf8'));
}

function parseChangesetDescription(contents) {
  const text = contents.toString('utf8').replace(/\r\n/g, '\n');
  const parsed = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
  if (!parsed) {
    return {
      packages: [],
      category: null,
      headline: '',
      contributors: [],
      body: text.trim(),
    };
  }

  const packages = parsed[1]
    .split('\n')
    .map(line =>
      /^\s*['"]?([^'"]+)['"]?\s*:\s*(major|minor|patch|none)\s*$/.exec(line),
    )
    .filter(Boolean)
    .map(match => ({name: match[1], bump: match[2]}));

  const lines = parsed[2].split('\n');
  const first = lines.findIndex(line => line.trim() !== '');
  const headlineMatch =
    first === -1 ? null : /^\s*\[([^\]]+)\]\s*(.*)$/.exec(lines[first]);
  const contributors = [];
  const body = [];
  for (const line of lines.slice(first + 1)) {
    if (/^\s*@[-\w]+(?:\s+@[-\w]+)*\s*$/.test(line)) {
      for (const match of line.matchAll(/@([-\w]+)/g)) {
        if (!contributors.includes(match[1])) contributors.push(match[1]);
      }
    } else {
      body.push(line);
    }
  }
  while (body.length && body[0].trim() === '') body.shift();
  while (body.length && body.at(-1).trim() === '') body.pop();

  return {
    packages,
    category: normalizeChangesetCategory(headlineMatch?.[1]),
    headline: headlineMatch?.[2].trim() ?? '',
    contributors,
    body: body.join('\n'),
  };
}

function changesetEntries(root) {
  const dir = path.join(root, '.changeset');
  return fs
    .readdirSync(dir)
    .filter(name => name.endsWith('.md') && !['README.md'].includes(name))
    .sort()
    .map(name => {
      const relative = `.changeset/${name}`;
      const contents = fs.readFileSync(path.join(root, relative));
      return {
        path: relative,
        sha256: sha256(contents),
        ...parseChangesetDescription(contents),
      };
    });
}

function buildPlan({root, version, branch, cutSha}) {
  return {
    schemaVersion: 2,
    version,
    branch,
    cutSha,
    changesets: changesetEntries(root),
  };
}

function buildMarker(plan) {
  return {
    schemaVersion: 1,
    state: 'active',
    version: plan.version,
    branch: plan.branch,
    cutSha: plan.cutSha,
    planDigest: computePlanDigest(plan),
  };
}

function validateIdentity(marker, plan) {
  const errors = [];
  if (marker?.schemaVersion !== 1)
    errors.push('marker schemaVersion must be 1');
  if (marker?.state !== 'active') errors.push('marker state must be active');
  if (!VERSION_RE.test(marker?.version ?? ''))
    errors.push('marker version must be X.Y.Z');
  const branchMatch = BRANCH_RE.exec(marker?.branch ?? '');
  if (!branchMatch) errors.push('marker branch must be release/vX.Y.Z');
  if (branchMatch && branchMatch[1] !== marker.version)
    errors.push('marker branch version must match marker version');
  if (!SHA_RE.test(marker?.cutSha ?? ''))
    errors.push('marker cutSha must be a full SHA');
  if (!/^[0-9a-f]{64}$/.test(marker?.planDigest ?? ''))
    errors.push('marker planDigest must be a SHA-256 digest');
  if (plan?.schemaVersion !== 2) errors.push('plan schemaVersion must be 2');
  for (const key of ['version', 'branch', 'cutSha']) {
    if (plan?.[key] !== marker?.[key])
      errors.push(`plan ${key} must match marker`);
  }
  if (computePlanDigest(plan) !== marker?.planDigest)
    errors.push('plan digest does not match marker');
  const seen = new Set();
  for (const entry of plan?.changesets ?? []) {
    if (
      !entry ||
      !/^\.changeset\/[A-Za-z0-9._-]+\.md$/.test(entry.path ?? '')
    ) {
      errors.push('plan contains an invalid Changeset path');
      continue;
    }
    if (seen.has(entry.path)) errors.push(`plan repeats ${entry.path}`);
    seen.add(entry.path);
    if (!/^[0-9a-f]{64}$/.test(entry.sha256 ?? ''))
      errors.push(`plan has an invalid digest for ${entry.path}`);
    if (!Array.isArray(entry.packages) || entry.packages.length === 0) {
      errors.push(`plan has no packages for ${entry.path}`);
    } else {
      for (const release of entry.packages) {
        if (
          !release ||
          typeof release.name !== 'string' ||
          !['major', 'minor', 'patch', 'none'].includes(release.bump)
        ) {
          errors.push(`plan has an invalid package release for ${entry.path}`);
        }
      }
    }
    if (!CHANGESET_CATEGORIES.has(entry.category))
      errors.push(`plan has an invalid category for ${entry.path}`);
    if (typeof entry.headline !== 'string' || entry.headline.trim() === '')
      errors.push(`plan has no headline for ${entry.path}`);
    if (
      !Array.isArray(entry.contributors) ||
      entry.contributors.some(
        value => typeof value !== 'string' || value === '',
      )
    ) {
      errors.push(`plan has invalid contributors for ${entry.path}`);
    }
    if (typeof entry.body !== 'string')
      errors.push(`plan has an invalid body for ${entry.path}`);
  }
  return errors;
}

/**
 * Does this manifest belong to the stable cut? Private and canary-only
 * packages publish outside it (or not at all), so their changes never block or
 * enter a stable release.
 *
 * @param {{name?: string, private?: boolean, astryx?: {canaryOnly?: boolean}}} manifest
 * @returns {boolean}
 */
function isStableReleasePackage(manifest) {
  return (
    manifest?.name?.startsWith('@astryxdesign/') === true &&
    manifest.private !== true &&
    manifest.astryx?.canaryOnly !== true
  );
}

function publishablePackages(root) {
  return expandWorkspaceDirs(root)
    .map(dir => path.join(dir, 'package.json'))
    .filter(file => fs.existsSync(file))
    .map(file => ({file, manifest: readJson(file)}))
    .filter(({manifest}) => isStableReleasePackage(manifest));
}

function validateReleaseState({
  root,
  marker,
  plan,
  mode,
  releaseBranch,
  releaseVersion,
  releaseTag,
  expectedPlanDigest,
  refName,
  expectedHead,
  checkoutSha,
  remoteHead,
  activeBranches,
}) {
  const errors = validateIdentity(marker, plan);
  if (releaseBranch !== marker.branch)
    errors.push('release-branch input does not match marker');
  if (releaseVersion !== undefined && releaseVersion !== marker.version)
    errors.push('release-version input does not match marker');
  if (releaseTag !== undefined && releaseTag !== `v${marker.version}`)
    errors.push('release-tag input does not match marker version');
  if (
    expectedPlanDigest !== undefined &&
    expectedPlanDigest !== marker.planDigest
  )
    errors.push('plan-digest input does not match marker');
  if (activeBranches.length !== 1 || activeBranches[0] !== marker.branch)
    errors.push(
      `exactly one active release branch is required; found ${activeBranches.join(',') || 'none'}`,
    );
  if (!SHA_RE.test(expectedHead ?? ''))
    errors.push('expected-head must be a full SHA');
  if (!SHA_RE.test(checkoutSha ?? ''))
    errors.push('checkout SHA must be a full SHA');
  if (expectedHead !== checkoutSha)
    errors.push('checked-out commit does not match expected head');
  if (remoteHead && remoteHead !== expectedHead)
    errors.push('release branch moved after the expected head was recorded');

  if (mode === 'check') {
    if (releaseVersion === undefined)
      errors.push('release check requires release-version');
    if (expectedPlanDigest === undefined)
      errors.push('release check requires plan-digest');
  }

  if (mode === 'publish') {
    if (releaseVersion === undefined)
      errors.push('stable publish requires release-version');
    if (releaseTag === undefined)
      errors.push('stable publish requires release-tag');
    if (expectedPlanDigest === undefined)
      errors.push('stable publish requires plan-digest');
    if (refName !== `v${marker.version}`)
      errors.push('stable publish must run from the version tag');
    if (releaseTag !== undefined && refName !== releaseTag)
      errors.push('checked-out tag does not match release-tag input');
  } else if (refName !== marker.branch) {
    errors.push('release validation must run from the marked release branch');
  }

  const current = new Map(
    changesetEntries(root).map(entry => [entry.path, entry.sha256]),
  );
  if (mode === 'cut') {
    for (const entry of plan.changesets) {
      if (current.get(entry.path) !== entry.sha256)
        errors.push(`cut Changeset differs or is missing: ${entry.path}`);
    }
    if (current.size !== plan.changesets.length)
      errors.push('cut Changeset set differs from the recorded plan');
  } else if (current.size !== 0) {
    errors.push('versioned release must consume every branch Changeset');
  }
  // FR47: the branch releases the version main declared at the cut, before and
  // after its Changesets are consumed.
  for (const {manifest, file} of publishablePackages(root)) {
    if (manifest.version !== marker.version)
      errors.push(
        `${path.relative(root, file)} is ${manifest.version}, expected ${marker.version}`,
      );
  }
  return errors;
}

const GIT_MAX_BUFFER = 64 * 1024 * 1024;

function gitRaw(root, args) {
  return execFileSync('git', args, {
    cwd: root,
    encoding: 'utf8',
    maxBuffer: GIT_MAX_BUFFER,
  });
}

function git(root, args) {
  return gitRaw(root, args).trim();
}

/** The highest local stable vX.Y.Z tag, or null when none exists. */
function latestStableVersion(root) {
  const versions = git(root, ['tag', '--list', 'v*'])
    .split('\n')
    .filter(Boolean)
    .map(tag => tag.slice(1))
    .filter(version => VERSION_RE.test(version))
    .sort((a, b) => compareVersions(a, b));
  return versions.at(-1) ?? null;
}

// A found object's header line in `git cat-file --batch` output: its id,
// type and size in bytes.
const FOUND_OBJECT = /^[0-9a-f]{40,64} [a-z]+ (\d+)$/;

/**
 * Each file's bytes at `ref`, or null when the ref lacks it, read with one
 * `git cat-file --batch` instead of one `git show` per file. This module
 * imports nothing beyond its own lib (see the header), so it carries its own
 * reader.
 * @param {string} root
 * @param {string} ref
 * @param {string[]} files
 * @returns {Map<string, Buffer | null>}
 */
function filesAtRef(root, ref, files) {
  const contents = new Map();
  if (files.length === 0) return contents;
  const out = execFileSync('git', ['cat-file', '--batch'], {
    cwd: root,
    input: files.map(file => `${ref}:${file}\n`).join(''),
    maxBuffer: 1024 * 1024 * 1024,
  });
  let at = 0;
  for (const file of files) {
    const end = out.indexOf(0x0a, at);
    const found = FOUND_OBJECT.exec(out.toString('utf8', at, end));
    at = end + 1;
    if (found === null) {
      contents.set(file, null);
      continue;
    }
    const size = Number(found[1]);
    contents.set(file, out.subarray(at, at + size));
    at += size + 1;
  }
  return contents;
}

function fileDigestsAtRef(root, ref, files) {
  const contents = filesAtRef(root, ref, files);
  return new Map(
    files.map(file => {
      const content = contents.get(file);
      return [file, content ? sha256(content) : null];
    }),
  );
}

function parseJson(content) {
  try {
    return content ? JSON.parse(content.toString('utf8')) : null;
  } catch {
    return null;
  }
}

function changesetMapAtRef(root, ref) {
  const files = git(root, [
    'ls-tree',
    '-r',
    '--name-only',
    ref,
    '--',
    '.changeset',
  ]);
  return fileDigestsAtRef(
    root,
    ref,
    files
      .split('\n')
      .filter(
        file =>
          file.startsWith('.changeset/') &&
          file.endsWith('.md') &&
          file !== '.changeset/README.md',
      ),
  );
}

function isPackageManifestPath(file) {
  return /^packages\/(?:[^/]+|themes\/[^/]+)\/package\.json$/.test(file);
}

function releaseOutputPathsAtRef(root, plan, releaseRef) {
  return git(root, ['diff', '--name-only', plan.cutSha, releaseRef, '--'])
    .split('\n')
    .filter(Boolean);
}

function releaseOutputMapAtRef(root, plan, releaseRef) {
  return fileDigestsAtRef(
    root,
    releaseRef,
    releaseOutputPathsAtRef(root, plan, releaseRef)
      .filter(isReleaseOutputPath)
      .filter(file => !isPackageManifestPath(file)),
  );
}

function jsonAtRef(root, ref, file) {
  try {
    return JSON.parse(
      execFileSync('git', ['show', `${ref}:${file}`], {
        cwd: root,
        encoding: 'utf8',
        stdio: ['ignore', 'pipe', 'ignore'],
      }),
    );
  } catch {
    return null;
  }
}

function manifestMapAtRef(root, ref, files) {
  const contents = filesAtRef(root, ref, [...files]);
  return new Map([...files].map(file => [file, parseJson(contents.get(file))]));
}

function currentManifestMap(root, files) {
  return new Map(
    [...files].map(file => {
      const absolute = path.join(root, file);
      return [file, fs.existsSync(absolute) ? readJson(absolute) : null];
    }),
  );
}

function currentOutputMap(root, files) {
  return new Map(
    [...files].map(file => {
      const absolute = path.join(root, file);
      return [
        file,
        fs.existsSync(absolute) ? sha256(fs.readFileSync(absolute)) : null,
      ];
    }),
  );
}

/**
 * The merge-back's changes against `base`: `git diff --name-status` lines.
 * `base` must be the merge commit's first parent, the main commit the merge
 * was built on. A later main would show every file it gained as a deletion.
 */
function mergeBackEntries(root, base, head = 'HEAD') {
  const raw = git(root, [
    'diff',
    '--name-status',
    '--find-renames',
    base,
    head,
  ]);
  return raw ? raw.split('\n') : [];
}

/**
 * Validate one merge-back projection against its immutable release tag.
 *
 * The live PR path also binds the still-active release branch. A historical
 * coverage audit has no branch to bind after cleanup, so it replays the same
 * structural validation against the committed head and immutable tag.
 */
function validateMergeBackAtRef(
  root,
  {base, head = 'HEAD', releaseRef, activeBranches = null, workingTree = false},
) {
  const marker = markerAtRef(root, releaseRef);
  const plan = JSON.parse(
    git(root, ['show', `${releaseRef}:${RELEASE_DIR}/${PLAN_FILE}`]),
  );
  const errors = validateIdentity(marker, plan);
  if (releaseRef !== `v${marker.version}`)
    errors.push('release merge-back must use the immutable version tag');

  const releaseHead = git(root, ['rev-parse', releaseRef]);
  if (activeBranches !== null) {
    const branchHead = git(root, ['rev-parse', `origin/${marker.branch}`]);
    if (releaseHead !== branchHead)
      errors.push('version tag does not match the active release branch head');
    const sortedBranches = [...activeBranches].sort();
    if (sortedBranches.length !== 1 || sortedBranches[0] !== marker.branch)
      errors.push(
        'release merge-back requires exactly the marked active branch',
      );
  }

  const entries = mergeBackEntries(root, base, head);
  const releaseDiff = git(root, [
    'diff',
    '--name-status',
    '--find-renames',
    plan.cutSha,
    releaseRef,
  ]);
  const releaseRenames = new Set(
    releaseDiff
      .split('\n')
      .filter(Boolean)
      .map(entry => entry.split('\t'))
      .filter(
        ([status, ...files]) => status?.startsWith('R') && files.length === 2,
      )
      .map(([, ...files]) => files.join('\t')),
  );
  const releaseOutputs = releaseOutputMapAtRef(root, plan, releaseRef);
  const releaseManifestFiles = releaseOutputPathsAtRef(
    root,
    plan,
    releaseRef,
  ).filter(isPackageManifestPath);
  const cutManifests = manifestMapAtRef(
    root,
    plan.cutSha,
    releaseManifestFiles,
  );
  const releaseManifests = manifestMapAtRef(
    root,
    releaseRef,
    releaseManifestFiles,
  );
  const mainManifestFiles = git(root, [
    'ls-tree',
    '-r',
    '--name-only',
    base,
    '--',
    'packages',
  ])
    .split('\n')
    .filter(isPackageManifestPath);
  const baseManifests = manifestMapAtRef(root, base, mainManifestFiles);
  const baseConfig = jsonAtRef(root, base, '.changeset/config.json');
  const headChangesets = workingTree
    ? new Map(changesetEntries(root).map(entry => [entry.path, entry.sha256]))
    : changesetMapAtRef(root, head);
  const headOutputs = workingTree
    ? currentOutputMap(root, releaseOutputs.keys())
    : fileDigestsAtRef(root, head, [...releaseOutputs.keys()]);
  const headManifests = workingTree
    ? currentManifestMap(root, mainManifestFiles)
    : manifestMapAtRef(root, head, mainManifestFiles);

  errors.push(
    ...validateReleaseMergeBack({
      entries,
      plan,
      baseChangesets: changesetMapAtRef(root, base),
      headChangesets,
      releaseOutputs,
      headOutputs,
      releaseRenames,
      releaseVersion: marker.version,
      fixedNames: new Set((baseConfig?.fixed ?? []).flat()),
      cutManifests,
      releaseManifests,
      baseManifests,
      headManifests,
    }),
  );
  return {
    errors,
    receipt: {
      branch: marker.branch,
      head: releaseHead,
      version: marker.version,
      planDigest: marker.planDigest,
      base,
      releaseRef,
    },
  };
}

/** Replay the merge-back validator over a closed, one-parent merge commit. */
function validateHistoricalReleaseMergeBack(root, {head, releaseRef}) {
  const lineage = git(root, ['rev-list', '--parents', '-n', '1', head])
    .trim()
    .split(/\s+/);
  if (lineage.length !== 2)
    return ['historical release merge-back must be a one-parent squash commit'];
  return validateMergeBackAtRef(root, {
    base: lineage[1],
    head,
    releaseRef,
  }).errors;
}

function markerAtRef(root, ref) {
  return JSON.parse(
    git(root, ['show', `${ref}:${RELEASE_DIR}/${MARKER_FILE}`]),
  );
}

function validateRefMarker(marker, branch) {
  const match = BRANCH_RE.exec(branch);
  if (
    marker?.schemaVersion !== 1 ||
    !['active', 'closed'].includes(marker?.state) ||
    !match ||
    marker.branch !== branch ||
    marker.version !== match[1] ||
    !SHA_RE.test(marker.cutSha ?? '') ||
    !/^[0-9a-f]{64}$/.test(marker.planDigest ?? '')
  ) {
    throw new Error(
      `release branch ${branch} has an invalid or mismatched marker`,
    );
  }
}

function listActiveBranches(root) {
  const refs = git(root, [
    'for-each-ref',
    '--format=%(refname:short)',
    'refs/remotes/origin/release/v*',
  ]);
  if (!refs) return [];
  const active = [];
  for (const ref of refs.split('\n').filter(Boolean)) {
    let marker;
    try {
      marker = markerAtRef(root, ref);
    } catch {
      throw new Error(`release branch ${ref} has no readable marker`);
    }
    const branch = ref.replace(/^origin\//, '');
    validateRefMarker(marker, branch);
    if (marker.state === 'active') active.push(branch);
  }
  return active.sort();
}

const RELEASE_TEST_REPAIR_FORBIDDEN_STATEMENT =
  /(?:unbounded changed statement|\b(?:expect|assert)\s*[.(]|\b(?:expect|assert)[A-Z]\w*\s*\(|\.(?:not\.)?to[A-Z]\w*\s*\(|\b(?:skip|fixme|fail|slow)\s*\(|\b(?:test|it|describe)(?:\.[A-Za-z]+)*\.(?:skip|fixme|fail|slow|skipIf|runIf)\b|\b(?:skip|fixme)\s*:\s*true\b|\breturn\b|timeout|retr(?:y|ies)|\b(?:disableRules|disabledRules|excludeRules)\b|\btoMatch(?:Inline)?Snapshot\b)/i;

function changedStatementsFromDiff(diff) {
  const statements = [];
  let oldLines = [];
  let newLines = [];

  const statementData = text => {
    const masked = [...text];
    const stack = [];
    const pairs = [];
    let quote = null;
    let escaped = false;
    let lineComment = false;
    let blockComment = false;
    for (let index = 0; index < text.length; index += 1) {
      const character = text[index];
      const next = text[index + 1];
      if (lineComment) {
        masked[index] = ' ';
        if (character === '\n') lineComment = false;
        continue;
      }
      if (blockComment) {
        masked[index] = ' ';
        if (character === '*' && next === '/') {
          masked[index + 1] = ' ';
          blockComment = false;
          index += 1;
        }
        continue;
      }
      if (quote) {
        masked[index] = ' ';
        if (escaped) escaped = false;
        else if (character === '\\') escaped = true;
        else if (character === quote) quote = null;
        continue;
      }
      if (character === '/' && next === '/') {
        masked[index] = ' ';
        masked[index + 1] = ' ';
        lineComment = true;
        index += 1;
        continue;
      }
      if (character === '/' && next === '*') {
        masked[index] = ' ';
        masked[index + 1] = ' ';
        blockComment = true;
        index += 1;
        continue;
      }
      if (character === "'" || character === '"' || character === '`') {
        masked[index] = ' ';
        quote = character;
        continue;
      }
      if ('([{'.includes(character)) {
        stack.push({character, index});
        continue;
      }
      if (')]}'.includes(character)) {
        const expected = {')': '(', ']': '[', '}': '{'}[character];
        const opening = stack.at(-1);
        if (opening?.character === expected) {
          stack.pop();
          pairs.push({
            close: index,
            open: opening.index,
            type: opening.character,
          });
        }
      }
    }
    return {masked: masked.join(''), pairs};
  };

  const addChangedStatements = lines => {
    const text = lines.map(line => line.text).join('\n');
    const ranges = [];
    let offset = 0;
    for (const line of lines) {
      ranges.push({end: offset + line.text.length, start: offset});
      offset += line.text.length + 1;
    }
    const {masked, pairs} = statementData(text);
    for (let index = 0; index < lines.length; index += 1) {
      if (!lines[index].changed) continue;
      const range = ranges[index];
      const enclosingCall = pairs
        .filter(
          pair =>
            pair.type === '(' &&
            pair.open <= range.start &&
            pair.close >= range.end,
        )
        .sort((a, b) => a.close - a.open - (b.close - b.open))[0];
      const changedCode = masked.slice(range.start, range.end).trim();
      if (!changedCode) {
        if (
          /@(?:vitest-environment|jest-environment|ts-check|ts-nocheck)|(?:eslint|prettier)-(?:disable|enable)/i.test(
            lines[index].text,
          )
        ) {
          statements.push('<unbounded changed statement>');
        }
        continue;
      }
      if (!enclosingCall) {
        if (!changedCode.includes(';')) {
          statements.push('<unbounded changed statement>');
          continue;
        }
        for (const statement of changedCode.split(';')) {
          if (statement.trim()) statements.push(`${statement.trim()};`);
        }
        continue;
      }
      const previousSemicolon = masked.lastIndexOf(';', enclosingCall.open - 1);
      if (previousSemicolon === -1) {
        statements.push('<unbounded changed statement>');
        continue;
      }
      const start = previousSemicolon + 1;
      const semicolon = masked.indexOf(';', enclosingCall.close);
      if (semicolon === -1) {
        statements.push('<unbounded changed statement>');
        continue;
      }
      statements.push(text.slice(start, semicolon + 1).trim());
    }
  };
  const flush = () => {
    addChangedStatements(oldLines);
    addChangedStatements(newLines);
    oldLines = [];
    newLines = [];
  };

  for (const line of diff.split('\n')) {
    if (line.startsWith('@@')) {
      flush();
      continue;
    }
    if (/^(?:diff --git |index |--- |\+\+\+ )/.test(line)) continue;
    const marker = line[0];
    const text = line.slice(1);
    if (marker === ' ') {
      oldLines.push({changed: false, text});
      newLines.push({changed: false, text});
    } else if (marker === '-') {
      oldLines.push({changed: true, text});
    } else if (marker === '+') {
      newLines.push({changed: true, text});
    }
  }
  flush();
  return [...new Set(statements)];
}

function validateReleaseTestRepair({
  entries,
  changedLines,
  changedStatements,
  commitCount,
  mergeCommitCount,
  patchId,
  changeDigest,
  mainPatches,
  baseChangesets,
}) {
  const errors = [];
  if (entries.length === 0)
    errors.push('release test repair has no changed files');
  if (commitCount !== 1 || mergeCommitCount !== 0)
    errors.push(
      'release test repair must contain exactly one non-merge commit',
    );
  if (baseChangesets.size !== 0)
    errors.push(
      'release test repair requires the generated version bump to be merged first',
    );

  for (const entry of entries) {
    const status = entry.split('\t', 1)[0];
    if (status !== 'M')
      errors.push(`release test repair may only modify an existing test: ${entry}`);
    const files = diffEntryFiles(entry);
    if (files === null) {
      errors.push(`invalid diff entry: ${entry}`);
      continue;
    }
    for (const file of files) {
      if (!isReleaseTestRepairPath(file))
        errors.push(`release test repair contains a non-test path: ${file}`);
    }
  }
  for (const statement of changedStatements ?? changedLines ?? []) {
    if (RELEASE_TEST_REPAIR_FORBIDDEN_STATEMENT.test(statement))
      errors.push(
        `release test repair changes an assertion, test control, timeout, retry, or snapshot: ${statement}`,
      );
  }

  const source = patchId
    ? (mainPatches.get(patchId) ?? []).find(
        candidate =>
          candidate.changeDigest === changeDigest && candidate.presentAtMain,
      )
    : null;
  if (!patchId || !changeDigest || !source)
    errors.push(
      'release test repair does not exactly match a non-merge commit still present on main',
    );
  return {errors, sourceCommit: source?.commit ?? null};
}

function stablePatchId(root, diff) {
  if (!diff.trim()) return null;
  const output = execFileSync('git', ['patch-id', '--stable'], {
    cwd: root,
    encoding: 'utf8',
    input: diff,
  }).trim();
  return output.split(/\s+/)[0] || null;
}

function exactChangeDigest(diff) {
  const change = diff
    .split('\n')
    .filter(
      line =>
        /^(?:diff --git |new file mode |deleted file mode |rename (?:from|to) |copy (?:from|to) )/.test(
          line,
        ) ||
        (/^[+-]/.test(line) && !/^(?:\+\+\+|---)/.test(line)),
    )
    .join('\n');
  return change ? sha256(change) : null;
}

function patchIsPresentAtRef(root, ref, diff) {
  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-release-index-'));
  const index = path.join(temp, 'index');
  const env = {...process.env, GIT_INDEX_FILE: index};
  try {
    execFileSync('git', ['read-tree', ref], {
      cwd: root,
      env,
      stdio: 'ignore',
    });
    execFileSync(
      'git',
      ['apply', '--cached', '--reverse', '--check', '--whitespace=nowarn'],
      {
        cwd: root,
        env,
        input: diff.endsWith('\n') ? diff : `${diff}\n`,
        stdio: ['pipe', 'ignore', 'ignore'],
      },
    );
    return true;
  } catch {
    return false;
  } finally {
    fs.rmSync(temp, {recursive: true, force: true});
  }
}

function validateReleaseTestRepairAtRef(
  root,
  {base, head, mainRef, entries, baseChangesets},
) {
  const mergeBase = git(root, ['merge-base', base, head]);
  const commits = git(root, ['rev-list', `${mergeBase}..${head}`])
    .split('\n')
    .filter(Boolean);
  const mergeCommits = git(root, [
    'rev-list',
    '--min-parents=2',
    `${mergeBase}..${head}`,
  ])
    .split('\n')
    .filter(Boolean);
  const diff = gitRaw(root, [
    'diff',
    '--binary',
    `${mergeBase}..${head}`,
  ]);
  const changedStatements = changedStatementsFromDiff(
    git(root, ['diff', '--unified=20', `${mergeBase}..${head}`]),
  );
  const patchId = stablePatchId(root, diff);
  const changeDigest = exactChangeDigest(diff);
  const files = [
    ...new Set(entries.flatMap(entry => diffEntryFiles(entry) ?? [])),
  ];
  const mainPatches = new Map();
  if (mainRef) {
    const candidates = git(root, [
      'log',
      '--format=%H',
      '--no-merges',
      mainRef,
      '--',
      ...files,
    ])
      .split('\n')
      .filter(Boolean);
    for (const commit of candidates) {
      const candidateDiff = gitRaw(root, [
        'show',
        '--format=',
        '--binary',
        commit,
      ]);
      const candidatePatchId = stablePatchId(root, candidateDiff);
      if (!candidatePatchId || candidatePatchId !== patchId) continue;
      const candidateChangeDigest = exactChangeDigest(candidateDiff);
      const matches = mainPatches.get(candidatePatchId) ?? [];
      matches.push({
        commit,
        changeDigest: candidateChangeDigest,
        presentAtMain:
          candidateChangeDigest === changeDigest &&
          patchIsPresentAtRef(root, mainRef, candidateDiff),
      });
      mainPatches.set(candidatePatchId, matches);
    }
  }
  return {
    ...validateReleaseTestRepair({
      entries,
      changedStatements,
      commitCount: commits.length,
      mergeCommitCount: mergeCommits.length,
      patchId,
      changeDigest,
      mainPatches,
      baseChangesets,
    }),
    patchId,
  };
}

const RELEASE_POLICY_CARRY_PATTERNS = [
  /^scripts\/release\/active-release(?:\.test)?\.mjs$/,
  /^scripts\/release\/release-paths\.mjs$/,
  /^\.github\/actions\/test-scope\/action\.yml$/,
  /^\.github\/scripts\/(?:test-scope-action|touched-components)\.test\.mjs$/,
  /^\.github\/workflows\/ci\.yml$/,
  /^docs\/release\.md$/,
  /^docs\/specs\/AST-(?:017|030)\/spec\.md$/,
];

function isAncestor(root, ancestor, descendant) {
  try {
    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
      cwd: root,
      stdio: 'ignore',
    });
    return true;
  } catch {
    return false;
  }
}

function patchBuildsHead(root, base, head, patch) {
  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-policy-carry-'));
  const index = path.join(temp, 'index');
  const env = {...process.env, GIT_INDEX_FILE: index};
  try {
    execFileSync('git', ['read-tree', base], {cwd: root, env, stdio: 'ignore'});
    execFileSync(
      'git',
      ['apply', '--cached', '--unidiff-zero', '--whitespace=nowarn'], {
      cwd: root,
      env,
      input: patch.endsWith('\n') ? patch : `${patch}\n`,
      stdio: ['pipe', 'ignore', 'ignore'],
    });
    const tree = execFileSync('git', ['write-tree'], {
      cwd: root,
      env,
      encoding: 'utf8',
    }).trim();
    return tree === git(root, ['rev-parse', `${head}^{tree}`]);
  } catch {
    return false;
  } finally {
    fs.rmSync(temp, {recursive: true, force: true});
  }
}

function validateReleasePolicyCarryAtRef(
  root,
  {base, head, source, mainRef, manifestPath, releaseBranch},
) {
  const errors = [];
  const baseCommit = git(root, ['rev-parse', base]);
  const commits = git(root, ['rev-list', `${baseCommit}..${head}`])
    .split('\n')
    .filter(Boolean);
  const mergeCommits = git(root, [
    'rev-list',
    '--min-parents=2',
    `${baseCommit}..${head}`,
  ])
    .split('\n')
    .filter(Boolean);
  if (commits.length !== 1 || mergeCommits.length !== 0)
    errors.push(
      'release policy carry must contain exactly one non-merge commit',
    );
  if (git(root, ['rev-parse', `${head}^`]) !== baseCommit)
    errors.push('release policy carry commit must directly follow the release head');
  if (!isAncestor(root, source, mainRef))
    errors.push('release policy carry source is not merged on current main');
  if (
    !/^scripts\/release\/policy-carry\/v\d+\.\d+\.\d+\.json$/.test(manifestPath)
  )
    errors.push('release policy carry manifest path is invalid');

  const manifest = jsonAtRef(root, source, manifestPath);
  if (
    manifest?.schemaVersion !== 1 ||
    manifest.releaseBranch !== releaseBranch ||
    manifest.base !== baseCommit ||
    !/^scripts\/release\/policy-carry\/v\d+\.\d+\.\d+\.diff$/.test(
      manifest?.patch ?? '',
    ) ||
    !/^[0-9a-f]{64}$/.test(manifest?.patchSha256 ?? '') ||
    !manifest?.targets ||
    Array.isArray(manifest.targets) ||
    typeof manifest.targets !== 'object'
  ) {
    errors.push(
      'release policy carry manifest does not match this branch and base',
    );
  }

  const targets =
    manifest?.targets &&
    !Array.isArray(manifest.targets) &&
    typeof manifest.targets === 'object'
      ? Object.entries(manifest.targets).sort(([a], [b]) => a.localeCompare(b))
      : [];
  for (const [file, digest] of targets) {
    if (
      !RELEASE_POLICY_CARRY_PATTERNS.some(pattern => pattern.test(file)) ||
      !/^[0-9a-f]{64}$/.test(digest)
    ) {
      errors.push(
        `release policy carry manifest has an invalid target: ${file}`,
      );
    }
  }

  const candidateEntries = git(root, [
    'diff',
    '--name-status',
    baseCommit,
    head,
  ])
    .split('\n')
    .filter(Boolean);
  const candidateFiles = [
    ...new Set(
      candidateEntries.flatMap(entry => {
        const files = diffEntryFiles(entry);
        if (files === null) {
          errors.push(`invalid release policy carry diff entry: ${entry}`);
          return [];
        }
        return files;
      }),
    ),
  ].sort();
  const targetFiles = targets.map(([file]) => file);
  for (const file of candidateFiles) {
    if (!RELEASE_POLICY_CARRY_PATTERNS.some(pattern => pattern.test(file)))
      errors.push(
        `release policy carry contains an unauthorized path: ${file}`,
      );
  }
  if (canonicalJson(candidateFiles) !== canonicalJson(targetFiles))
    errors.push(
      'release policy carry file set does not match its reviewed bundle',
    );

  const candidateDigests = fileDigestsAtRef(root, head, candidateFiles);
  for (const [file, digest] of targets) {
    if (candidateDigests.get(file) !== digest)
      errors.push(
        `release policy carry file does not match its reviewed bundle: ${file}`,
      );
  }

  const patchContent = manifest?.patch
    ? filesAtRef(root, source, [manifest.patch]).get(manifest.patch)
    : null;
  const patch = patchContent?.toString('utf8') ?? '';
  if (!patch || sha256(patchContent) !== manifest?.patchSha256)
    errors.push(
      'release policy carry patch does not match its manifest digest',
    );
  else if (!patchBuildsHead(root, baseCommit, head, patch))
    errors.push('release policy carry patch does not build the candidate head');

  return {
    errors,
    files: candidateEntries.length,
    bundleDigest: manifest ? sha256(canonicalJson(manifest)) : null,
  };
}

function validateReleaseDiff(entries, {plan, baseChangesets} = {}) {
  const errors = [];
  const planned = plan
    ? new Map(plan.changesets.map(entry => [entry.path, entry.sha256]))
    : null;
  const deletedChangesets = new Set();
  for (const entry of entries) {
    const [status] = entry.split('\t');
    const files = diffEntryFiles(entry);
    if (files === null) {
      errors.push(`invalid diff entry: ${entry}`);
      continue;
    }
    for (const file of files) {
      if (!file.startsWith('.changeset/') && !isReleaseOutputPath(file))
        errors.push(`release bump contains a non-generated path: ${file}`);
      if (file.startsWith('.changeset/')) {
        if (status !== 'D')
          errors.push(
            `release bump may only delete planned Changesets: ${file}`,
          );
        else {
          deletedChangesets.add(file);
          if (planned && !planned.has(file))
            errors.push(`release bump deletes an unplanned Changeset: ${file}`);
        }
      }
    }
  }
  if (planned && baseChangesets) {
    for (const [file, digest] of planned) {
      if (baseChangesets.get(file) !== digest)
        errors.push(
          `frozen Changeset differs or is missing at branch base: ${file}`,
        );
      if (!deletedChangesets.has(file))
        errors.push(`release bump did not delete frozen Changeset: ${file}`);
    }
    for (const file of baseChangesets.keys()) {
      if (!planned.has(file))
        errors.push(`release branch contains an unplanned Changeset: ${file}`);
    }
  }
  return errors;
}

const VERSION_DEPENDENCY_FIELDS = [
  'dependencies',
  'devDependencies',
  'optionalDependencies',
  'peerDependencies',
];
const EXACT_SPEC_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
function patchSuccessor(version) {
  if (!VERSION_RE.test(version ?? '')) return null;
  const [major, minor, patch] = version.split('.').map(Number);
  return `${major}.${minor}.${patch + 1}`;
}

function minorSuccessor(version) {
  if (!VERSION_RE.test(version ?? '')) return null;
  const [major, minor] = version.split('.').map(Number);
  return `${major}.${minor + 1}.0`;
}

/**
 * FR51 — choose the next declaration after merge-back. Patch is the operational
 * default. An owner-named value may select only the patch or minor successor;
 * pending Changesets never choose or skip the plan.
 */
function nextPlannedVersion(releaseVersion, ownerVersion = null) {
  const patch = patchSuccessor(releaseVersion);
  const minor = minorSuccessor(releaseVersion);
  if (patch === null || minor === null) return null;
  if (ownerVersion === null) return patch;
  return ownerVersion === patch || ownerVersion === minor ? ownerVersion : null;
}

/**
 * Apply only the generated manifest delta from the published branch to current
 * main. This preserves post-cut main fields while carrying an allowed release
 * version or exact-internal-pin change byte-for-byte.
 */
function mergedReleaseManifest(base, cut, release, {mainVersion, fixedNames}) {
  if (!base || !cut || !release) return null;
  const expected = structuredClone(base);
  if (cut.version !== release.version) expected.version = release.version;
  for (const field of VERSION_DEPENDENCY_FIELDS) {
    const cutValues = cut[field] ?? {};
    const releaseValues = release[field] ?? {};
    for (const name of new Set([
      ...Object.keys(cutValues),
      ...Object.keys(releaseValues),
    ])) {
      if (canonicalJson(cutValues[name]) === canonicalJson(releaseValues[name]))
        continue;
      expected[field] ??= {};
      if (releaseValues[name] === undefined) delete expected[field][name];
      else expected[field][name] = releaseValues[name];
    }
  }
  if (mainVersion) {
    if (fixedNames.has(expected.name)) expected.version = mainVersion;
    for (const field of VERSION_DEPENDENCY_FIELDS) {
      for (const [name, spec] of Object.entries(expected[field] ?? {})) {
        if (fixedNames.has(name) && EXACT_SPEC_RE.test(spec))
          expected[field][name] = mainVersion;
      }
    }
  }
  return expected;
}

/**
 * The release bump may change a published manifest's version and internal
 * pins only.
 */
function releaseManifestChangeError({file, cut, release}) {
  if (!cut || !release)
    return `release merge-back cannot read manifest history: ${file}`;
  const releaseFromCut = structuredClone(cut);
  releaseFromCut.version = release.version;
  for (const field of VERSION_DEPENDENCY_FIELDS) {
    const cutValues = cut[field] ?? {};
    const releaseValues = release[field] ?? {};
    for (const name of new Set([
      ...Object.keys(cutValues),
      ...Object.keys(releaseValues),
    ])) {
      if (canonicalJson(cutValues[name]) === canonicalJson(releaseValues[name]))
        continue;
      if (!name.startsWith('@astryxdesign/'))
        return `published manifest contains a non-version release change: ${file} ${field}.${name}`;
      releaseFromCut[field] ??= {};
      if (releaseValues[name] === undefined) delete releaseFromCut[field][name];
      else releaseFromCut[field][name] = releaseValues[name];
    }
  }
  return canonicalJson(releaseFromCut) === canonicalJson(release)
    ? null
    : `published manifest contains a non-version release change: ${file}`;
}

function validateReleaseMergeBack({
  entries,
  plan,
  baseChangesets,
  headChangesets,
  releaseOutputs,
  headOutputs,
  releaseRenames = new Set(),
  releaseVersion,
  fixedNames = new Set(),
  cutManifests = new Map(),
  releaseManifests = new Map(),
  baseManifests = new Map(),
  headManifests = new Map(),
}) {
  const errors = [];
  const planned = new Map(
    plan.changesets.map(entry => [entry.path, entry.sha256]),
  );
  const releaseManifestPaths = new Set(releaseManifests.keys());
  const releaseOutputPaths = new Set(releaseOutputs.keys());
  const releaseRenamePaths = new Set(
    [...releaseRenames].flatMap(rename => rename.split('\t')),
  );

  for (const entry of entries) {
    const [status, ...files] = entry.split('\t');
    const isRename = status?.startsWith('R');
    const expectedPaths = isRename ? 2 : 1;
    if (
      !status ||
      files.length !== expectedPaths ||
      files.some(file => !file)
    ) {
      errors.push(`invalid merge-back diff entry: ${entry}`);
      continue;
    }
    if (isRename && !releaseRenames.has(files.join('\t'))) {
      errors.push(
        `release merge-back rename does not match published branch: ${files.join(' -> ')}`,
      );
      continue;
    }
    for (const file of files) {
      if (file.startsWith('.changeset/')) {
        if (status !== 'D' || !planned.has(file))
          errors.push(
            `release merge-back may only delete frozen Changesets: ${file}`,
          );
      } else if (isPackageManifestPath(file)) {
        if (!releaseManifestPaths.has(file))
          errors.push(
            `release merge-back changed a manifest not changed on the published branch: ${file}`,
          );
      } else if (isReleaseOutputPath(file)) {
        if (!releaseOutputPaths.has(file) && !releaseRenamePaths.has(file))
          errors.push(
            `release merge-back changed an output not changed on the published branch: ${file}`,
          );
      } else {
        errors.push(`release merge-back contains a non-release path: ${file}`);
      }
    }
  }

  for (const [file, digest] of planned) {
    const baseDigest = baseChangesets.get(file);
    const headDigest = headChangesets.get(file);
    if (baseDigest === digest) {
      if (headDigest !== undefined)
        errors.push(
          `release merge-back did not delete frozen Changeset: ${file}`,
        );
    } else if (headDigest !== baseDigest) {
      errors.push(`release merge-back changed post-cut Changeset: ${file}`);
    }
  }
  for (const [file, digest] of baseChangesets) {
    if (planned.has(file)) continue;
    if (headChangesets.get(file) !== digest)
      errors.push(`release merge-back changed post-cut Changeset: ${file}`);
  }
  for (const file of headChangesets.keys()) {
    if (!baseChangesets.has(file))
      errors.push(
        `release merge-back added a Changeset instead of preserving main: ${file}`,
      );
  }
  for (const [file, digest] of releaseOutputs) {
    if (headOutputs.get(file) !== digest)
      errors.push(
        `release merge-back output differs from published branch: ${file}`,
      );
  }

  const baseVersions = new Set(
    [...baseManifests.values()]
      .filter(manifest => manifest && fixedNames.has(manifest.name))
      .map(manifest => manifest.version),
  );
  const mainVersion = baseVersions.size === 1 ? [...baseVersions][0] : null;
  if (
    mainVersion === null ||
    compareVersions(mainVersion, releaseVersion) === null ||
    compareVersions(mainVersion, releaseVersion) < 0
  )
    errors.push(
      `release merge-back requires current main at or above published v${releaseVersion}; found ${[...baseVersions].sort().join(', ') || 'none'}`,
    );

  for (const [file, release] of releaseManifests) {
    const cut = cutManifests.get(file);
    const error = releaseManifestChangeError({file, cut, release});
    if (error) {
      errors.push(error);
      continue;
    }
    const expected = mergedReleaseManifest(
      baseManifests.get(file),
      cut,
      release,
      {mainVersion, fixedNames},
    );
    const head = headManifests.get(file);
    if (!expected || !head) {
      errors.push(`release merge-back cannot read manifest history: ${file}`);
    } else if (canonicalJson(head) !== canonicalJson(expected)) {
      errors.push(
        `release merge-back manifest differs from the published branch delta: ${file}`,
      );
    }
  }
  for (const [file, base] of baseManifests) {
    if (releaseManifestPaths.has(file)) continue;
    const head = headManifests.get(file);
    if (!head)
      errors.push(`release merge-back removed a package manifest: ${file}`);
    else if (canonicalJson(head) !== canonicalJson(base))
      errors.push(
        `release merge-back changed a current-main manifest outside the published branch: ${file}`,
      );
  }

  const headVersions = new Set(
    [...headManifests.values()]
      .filter(manifest => manifest && fixedNames.has(manifest.name))
      .map(manifest => manifest.version),
  );
  if (
    mainVersion === null ||
    headVersions.size !== 1 ||
    [...headVersions][0] !== mainVersion
  )
    errors.push(
      `release merge-back must preserve main's declaration ${mainVersion ?? 'unknown'}; found ${[...headVersions].sort().join(', ') || 'none'}`,
    );
  if (mainVersion) {
    for (const manifest of headManifests.values()) {
      if (!manifest) continue;
      for (const field of VERSION_DEPENDENCY_FIELDS) {
        for (const [name, spec] of Object.entries(manifest[field] ?? {})) {
          if (
            fixedNames.has(name) &&
            EXACT_SPEC_RE.test(spec) &&
            spec !== mainVersion
          )
            errors.push(
              `release merge-back changed ${manifest.name} ${field}.${name} to ${spec}; expected preserved main declaration ${mainVersion}`,
            );
        }
      }
    }
  }
  return errors;
}

function canaryEligibility({fixed, releasedVersion, manifests}) {
  const versions = new Set(
    [...manifests.values()]
      .filter(
        manifest =>
          fixed.has(manifest.name) && isStableReleasePackage(manifest),
      )
      .map(manifest => manifest.version),
  );
  if (versions.size !== 1 || !VERSION_RE.test([...versions][0] ?? ''))
    return {
      errors: [
        `canary needs one plain fixed-group version; found ${[...versions].sort().join(', ') || 'none'}`,
      ],
      publish: false,
      declaredVersion: null,
      releasedVersion,
    };
  const [declaredVersion] = versions;
  const order = compareVersions(declaredVersion, releasedVersion);
  if (order === null || order < 0)
    return {
      errors: [
        `canary declaration ${declaredVersion} is below newest stable v${releasedVersion}`,
      ],
      publish: false,
      declaredVersion,
      releasedVersion,
    };
  return {
    errors: [],
    publish: order > 0,
    declaredVersion,
    releasedVersion,
  };
}

function packageManifestsByName(read, root) {
  const manifests = new Map();
  for (const dir of expandWorkspaceDirs(root)) {
    const manifest = read(path.relative(root, path.join(dir, 'package.json')));
    if (manifest?.name) manifests.set(manifest.name, manifest);
  }
  return manifests;
}

function parseArgs(argv) {
  const [command, ...rest] = argv;
  const values = {};
  for (let index = 0; index < rest.length; index += 1) {
    const key = rest[index];
    if (!key.startsWith('--')) throw new Error(`unexpected argument ${key}`);
    const value = rest[index + 1];
    if (value == null || value.startsWith('--'))
      throw new Error(`${key} needs a value`);
    values[key.slice(2)] = value;
    index += 1;
  }
  return {command, values};
}

function required(values, key) {
  if (!values[key]) throw new Error(`--${key} is required`);
  return values[key];
}

function versionTagExists(root, version) {
  try {
    execFileSync(
      'git',
      ['rev-parse', '--verify', '--quiet', `refs/tags/v${version}`],
      {cwd: root, stdio: 'ignore'},
    );
    return true;
  } catch {
    return false;
  }
}

/**
 * FR47/FR49 — the fixed-group version main declared at `ref`.
 *
 * @param {string} root
 * @param {string} ref
 * @returns {{version: string|null, errors: string[]}}
 */
function declaredVersionAtRef(root, ref) {
  const configFile = '.changeset/config.json';
  const files = expandWorkspaceDirs(root).map(dir =>
    path.relative(root, path.join(dir, 'package.json')),
  );
  const contents = filesAtRef(root, ref, [configFile, ...files]);
  const config = parseJson(contents.get(configFile));
  if (!config)
    return {
      version: null,
      errors: [`${ref} has no readable .changeset/config.json`],
    };
  const fixed = new Set((config.fixed ?? []).flat());
  const versions = new Map();
  for (const file of files) {
    const manifest = parseJson(contents.get(file));
    if (!manifest || !fixed.has(manifest.name)) continue;
    if (!isStableReleasePackage(manifest)) continue;
    if (!versions.has(manifest.version)) versions.set(manifest.version, []);
    versions.get(manifest.version).push(manifest.name);
  }
  if (versions.size !== 1)
    return {
      version: null,
      errors: [
        `the fixed group at ${ref} must declare one version; found ${
          [...versions.entries()]
            .map(([v, names]) => `${v} (${names.join(', ')})`)
            .join('; ') || 'none'
        }`,
      ],
    };
  const [version] = versions.keys();
  if (!VERSION_RE.test(version))
    return {
      version: null,
      errors: [
        `the fixed group at ${ref} declares ${version}, which is not X.Y.Z`,
      ],
    };
  return {version, errors: []};
}

function writeAuthority(root, values, refresh) {
  const version = required(values, 'version');
  const branch = required(values, 'branch');
  const cutSha = required(values, 'cut-sha');
  if (
    !VERSION_RE.test(version) ||
    branch !== `release/v${version}` ||
    !SHA_RE.test(cutSha)
  )
    throw new Error(
      'version, branch, and cut SHA do not form a valid release identity',
    );
  const declared = declaredVersionAtRef(root, cutSha);
  if (declared.errors.length) throw new Error(declared.errors.join('\n'));
  if (declared.version !== version)
    throw new Error(
      `main declares ${declared.version} at the cut, so the release is ${declared.version}, not ${version}`,
    );
  const dir = path.join(root, RELEASE_DIR);
  const markerPath = path.join(dir, MARKER_FILE);
  const planPath = path.join(dir, PLAN_FILE);
  const markerExists = fs.existsSync(markerPath);
  const planExists = fs.existsSync(planPath);

  if (refresh) {
    if (!markerExists || !planExists)
      throw new Error(
        'release refresh requires an existing active marker and plan',
      );
    const existingMarker = readJson(markerPath);
    const existingPlan = readJson(planPath);
    const identityErrors = validateIdentity(existingMarker, existingPlan);
    if (identityErrors.length) throw new Error(identityErrors.join('\n'));
    for (const [key, value] of [
      ['version', version],
      ['branch', branch],
      ['cutSha', cutSha],
    ]) {
      if (existingMarker[key] !== value)
        throw new Error(`release refresh cannot change ${key}`);
    }
  } else {
    if (markerExists || planExists)
      throw new Error(
        'release authority already exists; a release branch cannot be reused',
      );
    if (versionTagExists(root, version))
      throw new Error(
        `version v${version} already has an immutable tag; use a new release branch and version`,
      );
  }

  fs.mkdirSync(dir, {recursive: true});
  const plan = buildPlan({root, version, branch, cutSha});
  const marker = buildMarker(plan);
  fs.writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
  fs.writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`);
  console.log(
    JSON.stringify({branch, version, cutSha, planDigest: marker.planDigest}),
  );
}

async function main() {
  const {command, values} = parseArgs(process.argv.slice(2));
  const root = path.resolve(values.root ?? ROOT);
  if (command === 'create' || command === 'refresh') {
    // FR48/FR49: admission runs where the plan is made. Loaded here so the
    // trusted CI copy of this file needs no other module.
    const {admitRelease} = await import('./release-inputs.mjs');
    const admission = admitRelease(root, {
      version: required(values, 'version'),
    });
    if (admission.problems.length)
      throw new Error(
        `release admission refused ${values.version}:\n${admission.problems.join('\n')}`,
      );
    writeAuthority(root, values, command === 'refresh');
    return;
  }
  if (command === 'list-active') {
    console.log(listActiveBranches(root).join(','));
    return;
  }
  if (command === 'inspect-ref') {
    const ref = required(values, 'ref');
    const marker = markerAtRef(root, ref);
    const branch = ref.replace(/^origin\//, '');
    validateRefMarker(marker, branch);
    console.log(JSON.stringify(marker));
    return;
  }
  if (command === 'validate-policy-carry') {
    const base = required(values, 'base');
    const head = required(values, 'head');
    const source = required(values, 'source');
    const mainRef = required(values, 'main-ref');
    const manifestPath = required(values, 'manifest');
    const releaseBranch = required(values, 'release-branch');
    const result = validateReleasePolicyCarryAtRef(root, {
      base,
      head,
      source,
      mainRef,
      manifestPath,
      releaseBranch,
    });
    if (result.errors.length) throw new Error(result.errors.join('\n'));
    console.log(
      JSON.stringify({
        kind: 'policy-carry',
        base,
        head,
        source,
        manifest: manifestPath,
        files: result.files,
        bundleDigest: result.bundleDigest,
      }),
    );
    return;
  }
  if (command === 'validate-diff') {
    const base = required(values, 'base');
    const head = required(values, 'head');
    const marker = markerAtRef(root, base);
    const plan = JSON.parse(
      git(root, ['show', `${base}:${RELEASE_DIR}/${PLAN_FILE}`]),
    );
    const raw = git(root, ['diff', '--name-status', `${base}...${head}`]);
    const entries = raw ? raw.split('\n') : [];
    const baseChangesets = changesetMapAtRef(root, base);
    const kind = classifyReleaseDiff(entries);
    let sourceCommit = null;
    let patchId = null;
    let diffErrors;
    if (kind === 'test-repair') {
      const repair = validateReleaseTestRepairAtRef(root, {
        base,
        head,
        mainRef: required(values, 'main-ref'),
        entries,
        baseChangesets,
      });
      sourceCommit = repair.sourceCommit;
      patchId = repair.patchId;
      diffErrors = repair.errors;
    } else if (kind === 'version-bump') {
      diffErrors = validateReleaseDiff(entries, {plan, baseChangesets});
    } else {
      diffErrors = [
        'release candidate contains paths outside the generated version bump or test-repair classes',
      ];
    }
    const errors = [...validateIdentity(marker, plan), ...diffErrors];
    if (errors.length) throw new Error(errors.join('\n'));
    console.log(
      JSON.stringify({
        base,
        head,
        kind,
        planDigest: marker.planDigest,
        files: entries.length,
        ...(sourceCommit ? {sourceCommit, patchId} : {}),
      }),
    );
    return;
  }
  if (command === 'next-plan-version') {
    const releaseVersion = required(values, 'released-version');
    const ownerVersion = values['owner-version'] ?? null;
    const version = nextPlannedVersion(releaseVersion, ownerVersion);
    if (version === null)
      throw new Error(
        `next plan after v${releaseVersion} must be patch successor ${patchSuccessor(releaseVersion)} or owner-named minor ${minorSuccessor(releaseVersion)}`,
      );
    console.log(version);
    return;
  }
  if (command === 'canary-eligibility') {
    const config = readJson(path.join(root, '.changeset/config.json'));
    const fixed = new Set((config.fixed ?? []).flat());
    const manifests = packageManifestsByName(file => {
      const absolute = path.join(root, file);
      return fs.existsSync(absolute) ? readJson(absolute) : null;
    }, root);
    const releasedVersion = latestStableVersion(root);
    const receipt = canaryEligibility({fixed, releasedVersion, manifests});
    if (receipt.errors.length) throw new Error(receipt.errors.join('\n'));
    if (process.env.GITHUB_OUTPUT)
      fs.appendFileSync(
        process.env.GITHUB_OUTPUT,
        `publish=${receipt.publish}\ndeclared-version=${receipt.declaredVersion}\nreleased-version=${releasedVersion}\n`,
      );
    console.log(
      JSON.stringify({
        declaredVersion: receipt.declaredVersion,
        releasedVersion,
        publish: receipt.publish,
      }),
    );
    return;
  }
  if (command === 'validate-merge-back') {
    const base = required(values, 'base');
    const releaseRef = required(values, 'release-ref');
    const activeBranches = required(values, 'active-branches')
      .split(',')
      .filter(Boolean);
    const {errors, receipt} = validateMergeBackAtRef(root, {
      base,
      releaseRef,
      activeBranches,
      workingTree: true,
    });
    if (errors.length) throw new Error(errors.join('\n'));
    console.log(JSON.stringify(receipt));
    return;
  }
  if (command !== 'validate')
    throw new Error(
      'command must be create, refresh, list-active, inspect-ref, validate-diff, next-plan-version, canary-eligibility, validate-merge-back, or validate',
    );

  const marker = readJson(path.join(root, RELEASE_DIR, MARKER_FILE));
  const plan = readJson(path.join(root, RELEASE_DIR, PLAN_FILE));
  const activeBranches = required(values, 'active-branches')
    .split(',')
    .filter(Boolean)
    .sort();
  const errors = validateReleaseState({
    root,
    marker,
    plan,
    mode: required(values, 'mode'),
    releaseBranch: required(values, 'release-branch'),
    releaseVersion: values['release-version'],
    releaseTag: values['release-tag'],
    expectedPlanDigest: values['plan-digest'],
    refName: required(values, 'ref-name'),
    expectedHead: required(values, 'expected-head'),
    checkoutSha: required(values, 'checkout-sha'),
    remoteHead: values['remote-head'],
    activeBranches,
  });
  if (errors.length) throw new Error(errors.join('\n'));
  const receipt = {
    branch: marker.branch,
    head: values['expected-head'],
    version: marker.version,
    planDigest: marker.planDigest,
    mode: values.mode,
  };
  if (process.env.GITHUB_OUTPUT) {
    fs.appendFileSync(
      process.env.GITHUB_OUTPUT,
      Object.entries(receipt)
        .map(([key, value]) => `${key}=${value}\n`)
        .join(''),
    );
  }
  console.log(JSON.stringify(receipt));
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
  main().catch(error => {
    console.error(`release authority validation failed: ${error.message}`);
    process.exit(1);
  });
}

export {
  buildMarker,
  buildPlan,
  canaryEligibility,
  canonicalJson,
  changedStatementsFromDiff,
  compareVersions,
  computePlanDigest,
  declaredVersionAtRef,
  filesAtRef,
  nextPlannedVersion,
  isReleaseTestRepairPath,
  isStableReleasePackage,
  latestStableVersion,
  listActiveBranches,
  mergeBackEntries,
  validateIdentity,
  validateRefMarker,
  validateReleaseDiff,
  validateReleaseTestRepair,
  validateReleaseState,
  validateReleaseMergeBack,
  validateHistoricalReleaseMergeBack,
  versionTagExists,
  writeAuthority,
};