audrey 0.21.0 → 1.0.0

package/scripts/verify-arxiv-compile.mjs

@@ -0,0 +1,440 @@
+import { createHash } from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join, relative, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+import { validateSchema } from '../benchmarks/validate-guardbench-artifacts.mjs';
+import { publicPath } from '../benchmarks/public-paths.mjs';
+import { verifyArxivSourcePackage } from './verify-arxiv-source.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_SOURCE_DIR = 'docs/paper/output/arxiv';
+const DEFAULT_OUT_DIR = 'docs/paper/output/arxiv-compile';
+const DEFAULT_REPORT = 'docs/paper/output/arxiv-compile-report.json';
+const DEFAULT_SCHEMA = 'docs/paper/arxiv-compile-report.schema.json';
+const MAIN_TEX = 'main.tex';
+const REFERENCES_BIB = 'references.bib';
+const TECTONIC_BUNDLE_URL = 'https://data1.fullyjustified.net/tlextras-2022.0r0.tar';
+
+function fromRoot(path) {
+  return resolve(ROOT, path);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(fromRoot(path), 'utf-8'));
+}
+
+function sha256File(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function pathForReport(path) {
+  const rel = relative(ROOT, path);
+  if (rel && !rel.startsWith('..')) return rel.replaceAll('\\', '/');
+  return publicPath(path);
+}
+
+function commandExists(command) {
+  const result = process.platform === 'win32'
+    ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', 'where', command], { encoding: 'utf-8' })
+    : spawnSync('sh', ['-lc', `command -v ${command}`], { encoding: 'utf-8' });
+  return result.status === 0;
+}
+
+function compilerPlan(exists = commandExists) {
+  if (exists('tectonic')) {
+    return {
+      name: 'tectonic',
+      stages: [
+        { command: 'tectonic', args: ['--keep-logs', '--keep-intermediates', MAIN_TEX] },
+      ],
+    };
+  }
+  if (exists('latexmk')) {
+    return {
+      name: 'latexmk',
+      stages: [
+        { command: 'latexmk', args: ['-pdf', '-interaction=nonstopmode', '-halt-on-error', MAIN_TEX] },
+      ],
+    };
+  }
+  if (exists('pdflatex') && exists('bibtex')) {
+    return {
+      name: 'pdflatex+bibtex',
+      stages: [
+        { command: 'pdflatex', args: ['-interaction=nonstopmode', '-halt-on-error', MAIN_TEX] },
+        { command: 'bibtex', args: ['main'] },
+        { command: 'pdflatex', args: ['-interaction=nonstopmode', '-halt-on-error', MAIN_TEX] },
+        { command: 'pdflatex', args: ['-interaction=nonstopmode', '-halt-on-error', MAIN_TEX] },
+      ],
+    };
+  }
+  if (exists('uvx')) {
+    return {
+      name: 'uvx-tecto',
+      bundleProxy: true,
+      stages: [
+        {
+          command: 'uvx',
+          args: ['tecto', '-X', 'compile', '--bundle', '__TECTONIC_BUNDLE_URL__', '--keep-logs', '--keep-intermediates', '--reruns', '2', MAIN_TEX],
+        },
+      ],
+    };
+  }
+  return null;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    dir: DEFAULT_SOURCE_DIR,
+    outDir: DEFAULT_OUT_DIR,
+    report: DEFAULT_REPORT,
+    schema: DEFAULT_SCHEMA,
+    allowMissing: false,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if ((token === '--dir' || token === '--source-dir') && argv[i + 1]) args.dir = argv[++i];
+    else if (token === '--out-dir' && argv[i + 1]) args.outDir = argv[++i];
+    else if (token === '--report' && argv[i + 1]) args.report = argv[++i];
+    else if (token === '--schema' && argv[i + 1]) args.schema = argv[++i];
+    else if (token === '--allow-missing') args.allowMissing = true;
+    else if (token === '--json') args.json = true;
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return args;
+}
+
+function usage() {
+  return `Usage: node scripts/verify-arxiv-compile.mjs [options]
+
+Options:
+  --dir <path>       arXiv source directory. Default: ${DEFAULT_SOURCE_DIR}.
+  --out-dir <path>   Compile output directory. Default: ${DEFAULT_OUT_DIR}.
+  --report <path>    Compile report JSON. Default: ${DEFAULT_REPORT}.
+  --schema <path>    Compile report schema. Default: ${DEFAULT_SCHEMA}.
+  --allow-missing    Exit 0 when no supported TeX toolchain is installed.
+  --json             Print the machine-readable compile report.
+`;
+}
+
+function sourceSnapshot(sourceDir) {
+  const manifestPath = join(sourceDir, 'arxiv-manifest.json');
+  const mainPath = join(sourceDir, MAIN_TEX);
+  const bibPath = join(sourceDir, REFERENCES_BIB);
+  return {
+    sourceDir: pathForReport(sourceDir),
+    manifest: pathForReport(manifestPath),
+    manifestSha256: sha256File(manifestPath),
+    mainTex: pathForReport(mainPath),
+    mainTexSha256: sha256File(mainPath),
+    referencesBib: pathForReport(bibPath),
+    referencesBibSha256: sha256File(bibPath),
+  };
+}
+
+function writeReport(path, report) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+}
+
+async function startTectonicBundleProxy(bundleUrl = TECTONIC_BUNDLE_URL) {
+  const bundle = new URL(bundleUrl);
+  const tarPath = bundle.pathname;
+  const indexPath = `${tarPath}.index.gz`;
+  const server = createServer(async (request, response) => {
+    try {
+      const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');
+      let remoteUrl = null;
+      if (requestUrl.pathname === tarPath) remoteUrl = bundleUrl;
+      else if (requestUrl.pathname === indexPath) remoteUrl = `${bundleUrl}.index.gz`;
+      if (!remoteUrl) {
+        response.writeHead(404);
+        response.end('not found');
+        return;
+      }
+
+      const headers = {};
+      if (request.headers.range) headers.range = request.headers.range;
+      const upstream = await fetch(remoteUrl, { headers });
+      response.statusCode = upstream.status;
+      for (const header of ['accept-ranges', 'content-length', 'content-range', 'content-type', 'etag', 'last-modified']) {
+        const value = upstream.headers.get(header);
+        if (value) response.setHeader(header, value);
+      }
+      if (!upstream.body) {
+        response.end();
+        return;
+      }
+      Readable.fromWeb(upstream.body).pipe(response);
+    } catch (error) {
+      response.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+      response.end(error?.message ?? 'bundle proxy error');
+    }
+  });
+
+  await new Promise((resolveListen, rejectListen) => {
+    server.once('error', rejectListen);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', rejectListen);
+      resolveListen();
+    });
+  });
+  const address = server.address();
+  return {
+    url: `http://127.0.0.1:${address.port}${tarPath}`,
+    close: () => new Promise(resolveClose => server.close(resolveClose)),
+  };
+}
+
+function stageWithBundle(stage, bundleUrl) {
+  return {
+    command: stage.command,
+    args: stage.args.map(arg => arg === '__TECTONIC_BUNDLE_URL__' ? bundleUrl : arg),
+  };
+}
+
+function runStage(stage, cwd) {
+  return new Promise(resolveRun => {
+    const child = spawn(stage.command, stage.args, { cwd, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      child.kill();
+      if (!settled) {
+        settled = true;
+        resolveRun({ status: 1, signal: 'TIMEOUT', stdout, stderr: `${stderr}\nTimed out after 120000ms`.trim() });
+      }
+    }, 120000);
+
+    child.stdout?.on('data', chunk => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on('data', chunk => {
+      stderr += chunk.toString();
+    });
+    child.once('error', error => {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        resolveRun({ status: 1, error, stdout, stderr: `${stderr}\n${error.message}`.trim() });
+      }
+    });
+    child.once('close', (status, signal) => {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        resolveRun({ status, signal, stdout, stderr });
+      }
+    });
+  });
+}
+
+export async function verifyArxivCompile(options = {}) {
+  const sourceDir = fromRoot(options.dir ?? DEFAULT_SOURCE_DIR);
+  const outDir = fromRoot(options.outDir ?? DEFAULT_OUT_DIR);
+  const reportPath = fromRoot(options.report ?? DEFAULT_REPORT);
+  const now = options.now ?? new Date().toISOString();
+  const failures = [];
+  const blockers = [];
+  const sourceReport = verifyArxivSourcePackage({ dir: pathForReport(sourceDir) });
+  const source = sourceReport.ok ? sourceSnapshot(sourceDir) : null;
+
+  if (!sourceReport.ok) {
+    failures.push(...sourceReport.failures.map(failure => `arXiv source: ${failure}`));
+    const report = {
+      schemaVersion: '1.0.0',
+      suite: 'Audrey arXiv compile check',
+      generatedAt: now,
+      source,
+      outputDir: pathForReport(outDir),
+      status: 'failed',
+      compiler: null,
+      outputPdf: null,
+      outputPdfSha256: null,
+      logFile: null,
+      blockers,
+      failures,
+    };
+    writeReport(reportPath, report);
+    return report;
+  }
+
+  const plan = compilerPlan(options.commandExists ?? commandExists);
+  if (!plan) {
+    blockers.push('Install tectonic, latexmk, or pdflatex+bibtex before final arXiv compile proof');
+    const report = {
+      schemaVersion: '1.0.0',
+      suite: 'Audrey arXiv compile check',
+      generatedAt: now,
+      source,
+      outputDir: pathForReport(outDir),
+      status: 'toolchain-missing',
+      compiler: null,
+      outputPdf: null,
+      outputPdfSha256: null,
+      logFile: null,
+      blockers,
+      failures,
+    };
+    writeReport(reportPath, report);
+    return report;
+  }
+
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  cpSync(join(sourceDir, MAIN_TEX), join(outDir, MAIN_TEX));
+  cpSync(join(sourceDir, REFERENCES_BIB), join(outDir, REFERENCES_BIB));
+
+  let proxy = null;
+  const logLines = [];
+  try {
+    proxy = plan.bundleProxy ? await startTectonicBundleProxy() : null;
+    const stages = proxy ? plan.stages.map(stage => stageWithBundle(stage, proxy.url)) : plan.stages;
+    for (const stage of stages) {
+      logLines.push(`$ ${stage.command} ${stage.args.join(' ')}`);
+      const result = await runStage(stage, outDir);
+      if (result.stdout) logLines.push(result.stdout.trim());
+      if (result.stderr) logLines.push(result.stderr.trim());
+      if (result.status !== 0) {
+        failures.push(`${stage.command} exited ${result.status ?? result.signal ?? 'unknown'}`);
+        break;
+      }
+    }
+  } finally {
+    await proxy?.close();
+  }
+  const logPath = join(outDir, 'arxiv-compile.log');
+  writeFileSync(logPath, `${logLines.filter(Boolean).join('\n\n')}\n`, 'utf-8');
+
+  const pdfPath = join(outDir, 'main.pdf');
+  if (!existsSync(pdfPath)) failures.push('main.pdf was not produced by the TeX compiler');
+  const status = failures.length ? 'failed' : 'passed';
+  const report = {
+    schemaVersion: '1.0.0',
+    suite: 'Audrey arXiv compile check',
+    generatedAt: now,
+    source,
+    outputDir: pathForReport(outDir),
+    status,
+    compiler: {
+      name: plan.name,
+      stages: plan.stages.map(stage => ({ command: stage.command, args: stage.args })),
+    },
+    outputPdf: existsSync(pdfPath) ? pathForReport(pdfPath) : null,
+    outputPdfSha256: existsSync(pdfPath) ? sha256File(pdfPath) : null,
+    logFile: pathForReport(logPath),
+    blockers,
+    failures,
+  };
+  writeReport(reportPath, report);
+  return report;
+}
+
+export function verifyArxivCompileReport(options = {}) {
+  const reportPath = fromRoot(options.report ?? DEFAULT_REPORT);
+  const schemaPath = fromRoot(options.schema ?? DEFAULT_SCHEMA);
+  const allowPending = options.allowPending !== false;
+  const failures = [];
+  const blockers = [];
+  let report = null;
+
+  try {
+    report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+  } catch (error) {
+    return {
+      ok: false,
+      report: pathForReport(reportPath),
+      status: 'missing',
+      blockers: [],
+      failures: [`arxiv-compile-report.json: ${error.message}`],
+    };
+  }
+
+  try {
+    failures.push(...validateSchema(report, readJson(pathForReport(schemaPath)), 'audrey-arxiv-compile-report'));
+  } catch (error) {
+    failures.push(`schema: ${error.message}`);
+  }
+
+  const source = report.source;
+  if (source) {
+    const sourceChecks = [
+      ['manifestSha256', source.manifest],
+      ['mainTexSha256', source.mainTex],
+      ['referencesBibSha256', source.referencesBib],
+    ];
+    for (const [hashKey, file] of sourceChecks) {
+      const absolute = fromRoot(file);
+      if (!existsSync(absolute)) {
+        failures.push(`arxiv-compile-report.json: source file missing: ${file}`);
+      } else if (report.source?.[hashKey] !== sha256File(absolute)) {
+        failures.push(`arxiv-compile-report.json: ${file} changed since compile report`);
+      }
+    }
+  }
+
+  if (report.status === 'toolchain-missing') {
+    blockers.push(...(report.blockers?.length ? report.blockers : ['TeX toolchain is missing']));
+  } else if (report.status === 'failed') {
+    failures.push(...(report.failures?.length ? report.failures : ['arXiv compile failed']));
+  } else if (report.status === 'passed') {
+    if (!report.outputPdf || !existsSync(fromRoot(report.outputPdf))) failures.push('arxiv-compile-report.json: outputPdf is missing');
+    if (report.outputPdf && report.outputPdfSha256 && sha256File(fromRoot(report.outputPdf)) !== report.outputPdfSha256) {
+      failures.push('arxiv-compile-report.json: outputPdfSha256 is stale');
+    }
+  }
+
+  return {
+    ok: failures.length === 0 && (allowPending || blockers.length === 0),
+    report: pathForReport(reportPath),
+    status: report.status,
+    compiler: report.compiler?.name ?? null,
+    blockers,
+    failures,
+  };
+}
+
+function exitCode(report, allowMissing) {
+  if (report.status === 'passed') return 0;
+  if (report.status === 'toolchain-missing' && allowMissing) return 0;
+  return 1;
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+
+  const report = await verifyArxivCompile(args);
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (report.status === 'passed') {
+    console.log(`arXiv compile check passed: ${report.outputPdf}`);
+  } else if (report.status === 'toolchain-missing') {
+    console.log(`arXiv compile check pending: ${report.blockers.join('; ')}`);
+  } else {
+    console.error('arXiv compile check failed:');
+    for (const failure of report.failures) console.error(`- ${failure}`);
+  }
+
+  process.exit(exitCode(report, args.allowMissing));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error.stack ?? error.message);
+    process.exit(1);
+  }
+}

package/scripts/verify-arxiv-source.mjs

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateSchema } from '../benchmarks/validate-guardbench-artifacts.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_DIR = 'docs/paper/output/arxiv';
+const DEFAULT_SCHEMA = 'docs/paper/arxiv-source.schema.json';
+const REQUIRED_FILES = ['main.tex', 'references.bib', 'README-arxiv.txt'];
+const SEEDED_SECRET = 'sk-guardbench-secret-0000000000000000000000000000';
+
+function fromRoot(path) {
+  return resolve(ROOT, path);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function sha256File(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function countBibEntries(text) {
+  return [...text.matchAll(/@\w+\s*\{/g)].length;
+}
+
+function walkFiles(dir, root = dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return walkFiles(path, root);
+    return relative(root, path).replaceAll('\\', '/');
+  });
+}
+
+function checkSourceHash(label, sourcePath, expectedHash, failures) {
+  if (!sourcePath || !expectedHash) return;
+  const absolute = fromRoot(sourcePath);
+  if (!existsSync(absolute)) {
+    failures.push(`arxiv-manifest.json: missing source file for ${label}: ${sourcePath}`);
+    return;
+  }
+  if (expectedHash !== sha256File(absolute)) failures.push(`arxiv-manifest.json: ${label} hash is stale`);
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    dir: DEFAULT_DIR,
+    schema: DEFAULT_SCHEMA,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if ((token === '--dir' || token === '--source-dir') && argv[i + 1]) args.dir = argv[++i];
+    else if (token === '--schema' && argv[i + 1]) args.schema = argv[++i];
+    else if (token === '--json') args.json = true;
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`Unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return `Usage: node scripts/verify-arxiv-source.mjs [options]
+
+Options:
+  --dir <path>     arXiv source directory. Default: ${DEFAULT_DIR}.
+  --schema <path>  arXiv source manifest schema. Default: ${DEFAULT_SCHEMA}.
+  --json           Print the machine-readable verification report.
+`;
+}
+
+export function verifyArxivSourcePackage(options = {}) {
+  const dir = fromRoot(options.dir ?? DEFAULT_DIR);
+  const schemaPath = fromRoot(options.schema ?? DEFAULT_SCHEMA);
+  const manifestPath = join(dir, 'arxiv-manifest.json');
+  const failures = [];
+  let manifest = null;
+
+  try {
+    manifest = readJson(manifestPath);
+  } catch (error) {
+    return {
+      ok: false,
+      dir,
+      files: [],
+      citationCount: 0,
+      bibEntries: 0,
+      failures: [`arxiv-manifest.json: ${error.message}`],
+    };
+  }
+
+  try {
+    failures.push(...validateSchema(manifest, readJson(schemaPath), 'audrey-arxiv-source'));
+  } catch (error) {
+    failures.push(`schema: ${error.message}`);
+  }
+
+  const listed = new Map((manifest.files ?? []).map(file => [file.path, file]));
+  for (const file of REQUIRED_FILES) {
+    if (!listed.has(file)) failures.push(`arxiv-manifest.json: missing required file record ${file}`);
+  }
+  if (listed.has('arxiv-manifest.json')) failures.push('arxiv-manifest.json: must not include a self-hash file record');
+  checkSourceHash('sourceMarkdown', manifest.sourceMarkdown, manifest.sourceHashes?.sourceMarkdown, failures);
+  checkSourceHash('publicationPack', manifest.publicationPack, manifest.sourceHashes?.publicationPack, failures);
+  checkSourceHash('referencesBib', 'docs/paper/references.bib', manifest.sourceHashes?.referencesBib, failures);
+
+  for (const [file, record] of listed) {
+    const path = join(dir, file);
+    if (!existsSync(path)) {
+      failures.push(`${file}: listed in manifest but missing from package`);
+      continue;
+    }
+    const bytes = readFileSync(path).byteLength;
+    if (record.bytes !== bytes) failures.push(`${file}: byte length mismatch`);
+    if (record.sha256 !== sha256File(path)) failures.push(`${file}: sha256 mismatch`);
+    if (record.source && record.source !== 'generated') {
+      const sourcePath = fromRoot(record.source);
+      if (existsSync(sourcePath)) {
+        const sourceSha = sha256File(sourcePath);
+        if (record.source === 'docs/paper/references.bib' && sourceSha !== record.sha256) {
+          failures.push(`${file}: source bibliography has changed since arXiv package creation`);
+        }
+      }
+    }
+  }
+
+  const actualFiles = walkFiles(dir).filter(file => file !== 'arxiv-manifest.json').sort();
+  const listedFiles = [...listed.keys()].sort();
+  const listedSet = new Set(listedFiles);
+  for (const file of actualFiles) {
+    if (!listedSet.has(file)) failures.push(`${file}: present in package but missing from manifest`);
+  }
+
+  const mainPath = join(dir, 'main.tex');
+  const bibPath = join(dir, 'references.bib');
+  const main = existsSync(mainPath) ? readFileSync(mainPath, 'utf-8') : '';
+  const bib = existsSync(bibPath) ? readFileSync(bibPath, 'utf-8') : '';
+  const citationCount = [...main.matchAll(/\\cite\{([^}]+)\}/g)].length;
+  const citedIds = new Set([...main.matchAll(/\\cite\{([^}]+)\}/g)].flatMap(match => match[1].split(',').map(id => id.trim())));
+  const bibIds = new Set([...bib.matchAll(/@\w+\s*\{\s*([^,\s]+)/g)].map(match => match[1].trim()));
+  const bibEntries = countBibEntries(bib);
+
+  if (!main.includes('\\documentclass')) failures.push('main.tex: missing documentclass');
+  if (!main.includes('\\begin{abstract}')) failures.push('main.tex: missing abstract');
+  if (!main.includes('\\bibliography{references}')) failures.push('main.tex: missing bibliography command');
+  if (main.includes('[@')) failures.push('main.tex: contains unconverted Markdown citation syntax');
+  if (/^#{1,6}\s/m.test(main)) failures.push('main.tex: contains unconverted Markdown heading syntax');
+  if (main.includes(SEEDED_SECRET)) failures.push('main.tex: contains seeded raw secret');
+  if (/([A-Z]:\\|file:\/\/|C:\\Users\\|B:\\Projects\\)/i.test(main)) failures.push('main.tex: contains a local absolute path');
+  if (citationCount < 1) failures.push('main.tex: expected at least one citation');
+  if (bibEntries !== 21) failures.push(`references.bib: expected 21 entries, found ${bibEntries}`);
+  for (const id of citedIds) {
+    if (!bibIds.has(id)) failures.push(`main.tex: cites missing bibliography id ${id}`);
+  }
+  if (manifest.tex?.citationCount !== citationCount) failures.push('arxiv-manifest.json: citation count is stale');
+  if (manifest.tex?.bibEntryCount !== bibEntries) failures.push('arxiv-manifest.json: bibliography count is stale');
+
+  return {
+    ok: failures.length === 0,
+    dir,
+    manifestPath,
+    files: listedFiles,
+    citationCount,
+    bibEntries,
+    failures,
+  };
+}
+
+function main() {
+  const args = parseArgs();
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+  const report = verifyArxivSourcePackage(args);
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else if (report.ok) console.log(`arXiv source package verification passed: ${report.dir}`);
+  else {
+    console.error('arXiv source package verification failed:');
+    for (const failure of report.failures) console.error(`- ${failure}`);
+  }
+  if (!report.ok) process.exit(1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.stack ?? error.message);
+    process.exit(1);
+  }
+}