@shapeshift-labs/frontier-lang-compiler 0.2.150 → 0.2.151

package/bench/real-repo-corpus-checkout-proof.mjs

@@ -0,0 +1,263 @@
+import { readdirSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectCheckoutIdentityMetadata } from './real-repo-corpus-checkout-identity.mjs';
+
+const defaultCheckoutRootEnv = 'FRONTIER_REAL_REPO_CORPUS_ROOT';
+const maxMatchedFilesPerEntry = 64;
+const maxScannedFilesPerGlob = 2_000;
+
+function collectExternalCheckoutProofs(manifest, entries) {
+  const root = checkoutProofRoot(manifest);
+  const rootPresent = root.path ? isDirectory(root.path) : false;
+  const packageManagerMatrix = manifest.localBehavior?.packageManagerMatrix ?? [];
+  const commandMatrix = summarizePackageManagerCommandMatrix(packageManagerMatrix);
+  const rows = entries.map((entry) => collectExternalCheckoutProof(entry, root.path, rootPresent, packageManagerMatrix, commandMatrix));
+  const statuses = new Set(rows.map((row) => row.status));
+  return {
+    rootMode: root.mode,
+    rootPath: root.path,
+    rootPresent,
+    rows,
+    statuses,
+    proofSkipped: rows.filter((row) => row.checkoutProofExecution === 'skipped').length,
+    proofExecuted: rows.filter((row) => row.checkoutProofExecution === 'executed').length,
+    skipped: rows.filter((row) => row.status === 'skipped-missing-checkout').length,
+    checkedOut: rows.filter((row) => row.status.startsWith('checked-out')).length,
+    noProofMatch: rows.filter((row) => row.status === 'checked-out-no-proof-match').length,
+    proofMatchedEntries: rows.filter((row) => row.status === 'checked-out').length,
+    matchedFiles: rows.reduce((sum, row) => sum + row.matchedFiles, 0),
+    maxBytesPerFile: rows.reduce((max, row) => Math.max(max, row.maxObservedBytesPerFile), 0),
+    identitySkipped: rows.filter((row) => row.checkoutIdentityExecution === 'skipped').length,
+    identityExecuted: rows.filter((row) => row.checkoutIdentityExecution === 'executed').length,
+    identityMetadataPresent: rows.filter((row) => row.gitMetadataPresent === true).length,
+    identityMatched: rows.filter((row) => row.checkoutIdentityStatus === 'git-identity-matched').length,
+    identityRemoteMatched: rows.filter((row) => row.gitRemoteOriginMatchesManifest === true).length,
+    identityRefMatched: rows.filter((row) => row.gitRefMatchesManifest === true).length
+  };
+}
+
+function checkoutProofRoot(manifest) {
+  const envName = manifest.localBehavior?.checkoutProof?.rootEnv ?? defaultCheckoutRootEnv;
+  const envRoot = process.env[envName];
+  if (envRoot) return { mode: 'env-override', path: resolve(envRoot) };
+  if (typeof manifest.fetchRoot !== 'string') return { mode: 'missing-fetch-root', path: null };
+  return { mode: 'manifest-fetch-root', path: fileURLToPath(new URL(`../${manifest.fetchRoot}`, import.meta.url)) };
+}
+
+function collectExternalCheckoutProof(entry, rootPath, rootPresent, packageManagerMatrix, commandMatrix) {
+  const missingPresence = missingCheckoutPresence(rootPath, rootPresent, entry);
+  const baseRow = {
+    entryId: entry.id,
+    checkoutDir: entry.checkoutDir ?? null,
+    checkoutRootPresent: rootPresent,
+    checkoutDirPresent: false,
+    checkoutPresenceStatus: missingPresence.status,
+    checkoutProofReason: missingPresence.reason,
+    plannedSampleFiles: entry.metrics?.sampleFiles ?? 0,
+    proofGlobs: entry.pathGlobs?.length ?? 0,
+    matchedFiles: 0,
+    maxObservedBytesPerFile: 0,
+    packageManagerLockFilesPresent: 0,
+    packageManagerLockFiles: [],
+    packageManagersPresent: [],
+    packageManagerCommandMatrixStatus: commandMatrix.status,
+    packageManagerCommandMatrixCommands: commandMatrix.commands,
+    packageManagerInstallCommands: commandMatrix.installCommands,
+    packageManagerBuildCommands: commandMatrix.buildCommands,
+    packageManagerTestCommands: commandMatrix.testCommands,
+    checkoutIdentityStatus: 'skipped-missing-checkout',
+    checkoutIdentityExecution: 'skipped',
+    gitMetadataPresent: false,
+    gitMetadataKind: 'not-scanned',
+    gitDirPointerPresent: false,
+    gitHeadPresent: false,
+    gitConfigPresent: false,
+    gitRemoteOriginUrlPresent: false,
+    gitRemoteOriginMatchesManifest: null,
+    gitRefMatchesManifest: null
+  };
+  if (!rootPath || !rootPresent || !entry.checkoutDir) return withCheckoutProofStatus(baseRow, 'skipped-missing-checkout');
+  const checkoutPath = resolveInside(rootPath, entry.checkoutDir);
+  if (!checkoutPath || !isDirectory(checkoutPath)) return withCheckoutProofStatus(baseRow, 'skipped-missing-checkout');
+
+  const matched = collectMatchingFileStats(checkoutPath, entry.pathGlobs ?? []);
+  const packageManagers = collectPackageManagerMetadata(checkoutPath, packageManagerMatrix);
+  const identity = collectCheckoutIdentityMetadata(checkoutPath, entry);
+  const hasProofMatch = matched.matchedFiles > 0;
+  return withCheckoutProofStatus({
+    ...baseRow,
+    checkoutDirPresent: true,
+    checkoutPresenceStatus: 'checkout-dir-present',
+    checkoutProofReason: hasProofMatch ? 'declared-proof-globs-matched' : 'declared-proof-globs-missing',
+    matchedFiles: matched.matchedFiles,
+    maxObservedBytesPerFile: matched.maxObservedBytesPerFile,
+    packageManagerLockFilesPresent: packageManagers.lockFiles.length,
+    packageManagerLockFiles: packageManagers.lockFiles,
+    packageManagersPresent: packageManagers.managers,
+    ...identity
+  }, hasProofMatch ? 'checked-out' : 'checked-out-no-proof-match');
+}
+
+function missingCheckoutPresence(rootPath, rootPresent, entry) {
+  if (!rootPath) return { status: 'checkout-root-unconfigured', reason: 'checkout-root-unconfigured' };
+  if (!rootPresent) return { status: 'checkout-root-missing', reason: 'checkout-root-missing' };
+  if (!entry.checkoutDir) return { status: 'checkout-dir-not-declared', reason: 'checkout-dir-not-declared' };
+  return { status: 'checkout-dir-missing', reason: 'checkout-dir-missing' };
+}
+
+function summarizePackageManagerCommandMatrix(matrix = []) {
+  const summary = {
+    status: matrix.length > 0 && matrix.every((row) => row.status === 'metadata-only') ? 'metadata-only' : 'unknown',
+    commands: 0,
+    installCommands: 0,
+    buildCommands: 0,
+    testCommands: 0
+  };
+  for (const row of matrix) {
+    for (const command of row.commands ?? []) {
+      summary.commands += 1;
+      if (/\b(ci|install)\b/.test(command)) summary.installCommands += 1;
+      if (/\bbuild\b/.test(command)) summary.buildCommands += 1;
+      if (/\btest\b/.test(command)) summary.testCommands += 1;
+    }
+  }
+  return summary;
+}
+
+function collectPackageManagerMetadata(checkoutPath, matrix = []) {
+  const lockFiles = [];
+  const managers = [];
+  for (const row of matrix) {
+    const present = (row.lockFiles ?? []).filter((lockFile) => {
+      const filePath = resolveInside(checkoutPath, lockFile);
+      if (!filePath) return false;
+      try { return statSync(filePath).isFile(); } catch { return false; }
+    });
+    if (!present.length) continue;
+    managers.push(row.manager);
+    for (const lockFile of present) lockFiles.push(lockFile);
+  }
+  return { lockFiles, managers };
+}
+
+function withCheckoutProofStatus(row, status) {
+  return {
+    ...row,
+    status,
+    checkoutProofExecution: status === 'skipped-missing-checkout' ? 'skipped' : 'executed'
+  };
+}
+
+function collectMatchingFileStats(checkoutPath, globs) {
+  const matches = new Map();
+  for (const glob of globs) {
+    if (!hasGlobMagic(glob)) {
+      const filePath = resolveInside(checkoutPath, glob);
+      addMatchedFile(matches, filePath, checkoutPath);
+      continue;
+    }
+    const prefix = staticPrefixForGlob(glob);
+    const scanRoot = resolveInside(checkoutPath, prefix);
+    if (!scanRoot || !isDirectory(scanRoot)) continue;
+    const regex = globToRegExp(toPosix(glob));
+    let scannedFiles = 0;
+    scanFiles(scanRoot, checkoutPath, (relativePath, filePath) => {
+      if (scannedFiles >= maxScannedFilesPerGlob || matches.size >= maxMatchedFilesPerEntry) return false;
+      scannedFiles += 1;
+      if (regex.test(relativePath)) addMatchedFile(matches, filePath, checkoutPath);
+      return true;
+    });
+  }
+  return {
+    matchedFiles: matches.size,
+    maxObservedBytesPerFile: [...matches.values()].reduce((max, size) => Math.max(max, size), 0)
+  };
+}
+
+function addMatchedFile(matches, filePath, rootPath) {
+  if (!filePath || matches.size >= maxMatchedFilesPerEntry) return;
+  try {
+    const stat = statSync(filePath);
+    if (stat.isFile()) matches.set(toPosix(relative(rootPath, filePath)), stat.size);
+  } catch {
+    // Local external checkouts are optional; races while scanning remain non-fatal.
+  }
+}
+
+function scanFiles(dirPath, rootPath, visit) {
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  } catch {
+    return true;
+  }
+  for (const entry of entries) {
+    const childPath = resolve(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      if (scanFiles(childPath, rootPath, visit) === false) return false;
+      continue;
+    }
+    if (entry.isFile() && visit(toPosix(relative(rootPath, childPath)), childPath) === false) return false;
+  }
+  return true;
+}
+
+function staticPrefixForGlob(glob) {
+  const prefix = [];
+  for (const part of toPosix(glob).split('/')) {
+    if (hasGlobMagic(part)) break;
+    prefix.push(part);
+  }
+  return prefix.join('/');
+}
+
+function globToRegExp(glob) {
+  let source = '^';
+  for (let index = 0; index < glob.length;) {
+    const char = glob[index];
+    if (char === '*' && glob[index + 1] === '*') {
+      source += glob[index + 2] === '/' ? '(?:[^/]+/)*' : '.*';
+      index += glob[index + 2] === '/' ? 3 : 2;
+    } else if (char === '*') {
+      source += '[^/]*';
+      index += 1;
+    } else if (char === '?') {
+      source += '[^/]';
+      index += 1;
+    } else {
+      source += escapeRegExp(char);
+      index += 1;
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+function hasGlobMagic(value) {
+  return /[*?]/.test(value);
+}
+
+function resolveInside(rootPath, requestedPath) {
+  const targetPath = resolve(rootPath, requestedPath);
+  const relativePath = relative(rootPath, targetPath);
+  if (relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath))) return targetPath;
+  return null;
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function toPosix(path) {
+  return path.replaceAll('\\', '/');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export { collectExternalCheckoutProofs };

package/bench/real-repo-corpus-command-execution.mjs

@@ -0,0 +1,314 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+const defaultPhases = ['dependency-install', 'build', 'test'];
+const defaultTimeoutMs = 15_000;
+const defaultMaxOutputBytes = 4_096;
+const safeEnvKeys = new Set(['PATH', 'HOME', 'USER', 'TMPDIR', 'TEMP', 'TMP']);
+const shellMetacharacters = /[;&|<>$`(){}[\]*?!~"'\\\n\r]/;
+
+function collectRealRepoCommandExecution(manifest, checkoutProof, options = {}) {
+  const phases = normalizePhases(options.phases);
+  const enabled = options.enabled === true;
+  const selectedEntryIds = Array.isArray(options.entryIds) ? new Set(options.entryIds) : null;
+  const matrixByManager = new Map((manifest.localBehavior?.packageManagerMatrix ?? []).map((row) => [row.manager, row]));
+  const rows = (checkoutProof.rows ?? []).map((row) => {
+    if (!enabled || (selectedEntryIds && !selectedEntryIds.has(row.entryId))) {
+      return createDefaultOffRow(row, phases, 'real-repo-command-opt-in-missing');
+    }
+    return collectCommandExecutionForRow(row, phases, matrixByManager, checkoutProof, options);
+  });
+  return {
+    enabled,
+    rows,
+    commandRunRows: rows.length,
+    commandRunEnabledRows: rows.filter((row) => row.commandRunEnabled).length,
+    commandRunDefaultOffRows: rows.filter((row) => row.commandRunExecutionStatus === 'not-run-default-network-free').length,
+    commandRunOptInRequiredRows: rows.filter((row) => row.commandRunStatus === 'blocked-opt-in-required').length,
+    commandRunSkippedRows: rows.filter((row) => row.commandRunStatus === 'skipped-missing-checkout').length,
+    commandRunBlockedRows: rows.filter((row) => row.commandRunStatus.startsWith('blocked-')).length,
+    commandRunExecutedPhases: countPhases(rows, 'executed'),
+    commandRunFailedPhases: countPhases(rows, 'failed'),
+    commandRunTimedOutPhases: countPhases(rows, 'timed-out'),
+    commandRunSkippedPhases: rows.reduce((sum, row) => sum + row.commandRunPhases.filter((phase) => phase.executionStatus.startsWith('skipped-')).length, 0),
+    commandRunDefaultOffPhases: rows.reduce((sum, row) => sum + row.commandRunPhases.filter((phase) => phase.defaultExecution === 'not-run-default-network-free').length, 0),
+    commandRunOutputTruncatedPhases: rows.reduce((sum, row) => sum + row.commandRunPhases.filter((phase) => phase.stdoutTruncated || phase.stderrTruncated).length, 0)
+  };
+}
+
+function collectCommandExecutionForRow(row, phases, matrixByManager, checkoutProof, options) {
+  const safety = commandExecutionSafety(row, checkoutProof);
+  if (safety.status !== 'ready') return createBlockedRow(row, phases, safety.status, safety.reason);
+
+  const packageManager = packageManagerForRow(row);
+  if (packageManager.status !== 'ready') return createBlockedRow(row, phases, packageManager.status, packageManager.reason);
+
+  const commandSpecs = commandSpecsForManager(matrixByManager.get(packageManager.manager));
+  if (!commandSpecs) return createBlockedRow(row, phases, 'blocked-command-not-allowed', 'real-repo-command-package-manager-unsupported');
+
+  const commandRunPhases = phases.map((phase) => {
+    const spec = commandSpecs.get(phase);
+    if (!spec) return createPhase(phase, 'blocked-command-not-allowed', 'real-repo-command-phase-not-allowed');
+    if (phase === 'dependency-install' && options.allowDependencyInstall !== true) {
+      return createPhase(phase, 'blocked-opt-in-required', 'real-repo-command-network-opt-in-missing', spec);
+    }
+    return runCommandPhase(phase, spec, safety.checkoutPath, options);
+  });
+  return createRunRow(row, commandRunPhases, true);
+}
+
+function commandExecutionSafety(row, checkoutProof) {
+  if (row.status === 'skipped-missing-checkout') {
+    return { status: 'skipped-missing-checkout', reason: 'real-repo-command-checkout-dir-missing' };
+  }
+  if (row.status !== 'checked-out') {
+    return { status: 'blocked-safety-invariant', reason: 'real-repo-command-proof-globs-missing' };
+  }
+  if (!checkoutProof.rootPath) {
+    return { status: 'blocked-safety-invariant', reason: 'real-repo-command-checkout-root-unconfigured' };
+  }
+  if (!existsSync(checkoutProof.rootPath)) {
+    return { status: 'blocked-safety-invariant', reason: 'real-repo-command-checkout-root-missing' };
+  }
+  if (!row.checkoutDir) {
+    return { status: 'blocked-safety-invariant', reason: 'real-repo-command-checkout-dir-not-declared' };
+  }
+  const contained = realContainedPath(checkoutProof.rootPath, row.checkoutDir);
+  if (contained.reason) return { status: 'blocked-safety-invariant', reason: contained.reason };
+  const identity = identitySafety(row);
+  if (identity.reason) return identity;
+  return { status: 'ready', reason: 'real-repo-command-ready-local-checkout', checkoutPath: contained.path };
+}
+
+function identitySafety(row) {
+  if (row.gitDirPointerPresent === true) {
+    return { status: 'blocked-safety-invariant', reason: 'real-repo-command-gitdir-pointer-unverified' };
+  }
+  if (row.checkoutIdentityStatus === 'git-identity-matched') return {};
+  if (!row.gitMetadataPresent) return { status: 'blocked-identity-mismatch', reason: 'real-repo-command-git-metadata-missing' };
+  if (row.gitRemoteOriginMatchesManifest === false) return { status: 'blocked-identity-mismatch', reason: 'real-repo-command-git-remote-mismatch' };
+  if (row.gitRefMatchesManifest === false) return { status: 'blocked-identity-mismatch', reason: 'real-repo-command-git-ref-mismatch' };
+  return { status: 'blocked-identity-mismatch', reason: 'real-repo-command-git-metadata-missing' };
+}
+
+function packageManagerForRow(row) {
+  const managers = row.packageManagersPresent ?? [];
+  if (!managers.length) return { status: 'blocked-command-not-allowed', reason: 'real-repo-command-lockfile-missing' };
+  if (managers.length > 1) return { status: 'blocked-command-not-allowed', reason: 'real-repo-command-package-manager-ambiguous' };
+  return { status: 'ready', manager: managers[0] };
+}
+
+function commandSpecsForManager(row) {
+  if (!row?.manager || !Array.isArray(row.commands)) return null;
+  const specs = new Map();
+  for (const command of row.commands) {
+    const parsed = parseAllowedCommand(command);
+    if (!parsed) return null;
+    const phase = phaseForCommand(command);
+    if (phase && !specs.has(phase)) specs.set(phase, { ...parsed, manager: row.manager });
+  }
+  return specs;
+}
+
+function runCommandPhase(phase, spec, checkoutPath, options) {
+  const startedAt = Date.now();
+  const result = spawnSync(spec.argv[0], spec.argv.slice(1), {
+    cwd: checkoutPath,
+    shell: false,
+    encoding: 'utf8',
+    env: commandEnv(options.env),
+    timeout: timeoutMs(options.timeoutMs),
+    maxBuffer: Math.max(maxOutputBytes(options.maxOutputBytes) * 16, 1_048_576)
+  });
+  const durationMs = Date.now() - startedAt;
+  const stdout = capOutput(result.stdout ?? '', options.maxOutputBytes);
+  const stderr = capOutput(result.stderr ?? '', options.maxOutputBytes);
+  const timedOut = result.error?.code === 'ETIMEDOUT';
+  const executionStatus = timedOut ? 'timed-out' : result.status === 0 ? 'executed' : 'failed';
+  return {
+    ...createPhase(phase, executionStatus, reasonForExecutionStatus(executionStatus), spec),
+    exitCode: typeof result.status === 'number' ? result.status : null,
+    signal: result.signal ?? null,
+    durationMs,
+    timedOut,
+    stdoutBytes: stdout.bytes,
+    stderrBytes: stderr.bytes,
+    stdoutHash: hashText(result.stdout ?? ''),
+    stderrHash: hashText(result.stderr ?? ''),
+    stdoutPreview: stdout.preview,
+    stderrPreview: stderr.preview,
+    stdoutTruncated: stdout.truncated,
+    stderrTruncated: stderr.truncated
+  };
+}
+
+function createDefaultOffRow(row, phases, reason) {
+  return createRunRow(row, phases.map((phase) => createPhase(phase, 'blocked-opt-in-required', reason)), false);
+}
+
+function createBlockedRow(row, phases, status, reason) {
+  return createRunRow(row, phases.map((phase) => createPhase(phase, status, reason)), true);
+}
+
+function createRunRow(row, commandRunPhases, enabled) {
+  const commandRunStatus = aggregateStatus(commandRunPhases);
+  const repositoryPhases = commandRunPhases.filter((phase) => phase.phase === 'build' || phase.phase === 'test');
+  const dependencyPhase = commandRunPhases.find((phase) => phase.phase === 'dependency-install');
+  return {
+    entryId: row.entryId,
+    commandRunEnabled: enabled,
+    commandRunStatus,
+    commandRunExecutionStatus: enabled ? commandRunStatus : 'not-run-default-network-free',
+    commandRunReason: aggregateReason(commandRunPhases),
+    commandRunPhaseCount: commandRunPhases.length,
+    commandRunPhases,
+    commandRunExecutedPhases: commandRunPhases.filter((phase) => phase.executionStatus === 'executed').length,
+    commandRunFailedPhases: commandRunPhases.filter((phase) => phase.executionStatus === 'failed').length,
+    commandRunTimedOutPhases: commandRunPhases.filter((phase) => phase.executionStatus === 'timed-out').length,
+    commandRunSkippedPhases: commandRunPhases.filter((phase) => phase.executionStatus.startsWith('skipped-')).length,
+    commandRunDefaultOffPhases: commandRunPhases.filter((phase) => phase.defaultExecution === 'not-run-default-network-free').length,
+    commandRunOutputTruncatedPhases: commandRunPhases.filter((phase) => phase.stdoutTruncated || phase.stderrTruncated).length,
+    dependencyInstallExecution: phaseExecutionForEvidence(dependencyPhase),
+    repositoryCommandExecution: repositoryExecutionForEvidence(repositoryPhases)
+  };
+}
+
+function createPhase(phase, executionStatus, reason, spec = null) {
+  return {
+    phase,
+    executionStatus,
+    reason,
+    defaultExecution: executionStatus === 'blocked-opt-in-required' ? 'not-run-default-network-free' : 'explicit-opt-in',
+    command: spec?.command ?? null,
+    argv: spec?.argv ?? [],
+    manager: spec?.manager ?? null,
+    commandHash: spec ? hashText(JSON.stringify(spec.argv)) : null,
+    stdoutBytes: 0,
+    stderrBytes: 0,
+    stdoutHash: null,
+    stderrHash: null,
+    stdoutPreview: '',
+    stderrPreview: '',
+    stdoutTruncated: false,
+    stderrTruncated: false
+  };
+}
+
+function aggregateStatus(phases) {
+  if (phases.some((phase) => phase.executionStatus === 'timed-out')) return 'timed-out';
+  if (phases.some((phase) => phase.executionStatus === 'failed')) return 'failed';
+  if (phases.some((phase) => phase.executionStatus === 'executed')) return 'executed';
+  if (phases.some((phase) => phase.executionStatus === 'skipped-missing-checkout')) return 'skipped-missing-checkout';
+  if (phases.some((phase) => phase.executionStatus === 'blocked-identity-mismatch')) return 'blocked-identity-mismatch';
+  if (phases.some((phase) => phase.executionStatus === 'blocked-command-not-allowed')) return 'blocked-command-not-allowed';
+  if (phases.some((phase) => phase.executionStatus === 'blocked-safety-invariant')) return 'blocked-safety-invariant';
+  return 'blocked-opt-in-required';
+}
+
+function aggregateReason(phases) {
+  return phases.find((phase) => phase.executionStatus !== 'executed')?.reason ?? 'real-repo-command-executed';
+}
+
+function repositoryExecutionForEvidence(phases) {
+  if (phases.some((phase) => phase.executionStatus === 'timed-out')) return 'timed-out';
+  if (phases.some((phase) => phase.executionStatus === 'failed')) return 'failed';
+  if (phases.some((phase) => phase.executionStatus === 'executed')) return 'executed';
+  return 'not-run-default-network-free';
+}
+
+function phaseExecutionForEvidence(phase) {
+  if (!phase) return 'not-run-default-network-free';
+  if (['executed', 'failed', 'timed-out'].includes(phase.executionStatus)) return phase.executionStatus;
+  return 'not-run-default-network-free';
+}
+
+function parseAllowedCommand(command) {
+  if (typeof command !== 'string' || shellMetacharacters.test(command)) return null;
+  const argv = command.trim().split(/\s+/).filter(Boolean);
+  if (!argv.length || !['npm', 'pnpm', 'yarn'].includes(argv[0])) return null;
+  return { command, argv };
+}
+
+function phaseForCommand(command) {
+  if (/\b(ci|install)\b/.test(command)) return 'dependency-install';
+  if (/\bbuild\b/.test(command)) return 'build';
+  if (/\btest\b/.test(command)) return 'test';
+  return null;
+}
+
+function realContainedPath(rootPath, checkoutDir) {
+  let rootRealPath;
+  try {
+    rootRealPath = realpathSync(rootPath);
+  } catch {
+    return { reason: 'real-repo-command-checkout-root-missing' };
+  }
+  const checkoutPath = resolve(rootRealPath, checkoutDir);
+  const lexicalRelative = relative(rootRealPath, checkoutPath);
+  if (lexicalRelative.startsWith('..') || isAbsolute(lexicalRelative)) return { reason: 'real-repo-command-checkout-dir-outside-root' };
+  try {
+    const stat = statSync(checkoutPath);
+    if (!stat.isDirectory()) return { reason: 'real-repo-command-checkout-dir-missing' };
+    const checkoutRealPath = realpathSync(checkoutPath);
+    const realRelative = relative(rootRealPath, checkoutRealPath);
+    if (realRelative.startsWith('..') || isAbsolute(realRelative)) return { reason: 'real-repo-command-checkout-realpath-escape' };
+    return { path: checkoutRealPath };
+  } catch {
+    return { reason: 'real-repo-command-checkout-dir-missing' };
+  }
+}
+
+function commandEnv(extra = {}) {
+  const env = {};
+  for (const key of safeEnvKeys) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    if (safeEnvKeys.has(key) || /^npm_config_[a-z0-9_]+$/i.test(key)) env[key] = String(value);
+  }
+  env.CI = 'true';
+  env.NO_COLOR = '1';
+  env.npm_config_audit = 'false';
+  env.npm_config_fund = 'false';
+  env.npm_config_update_notifier = 'false';
+  return env;
+}
+
+function capOutput(value, maxBytesOption) {
+  const text = String(value ?? '');
+  const bytes = Buffer.byteLength(text);
+  const maxBytes = maxOutputBytes(maxBytesOption);
+  if (bytes <= maxBytes) return { bytes, preview: text, truncated: false };
+  return { bytes, preview: Buffer.from(text).subarray(0, maxBytes).toString('utf8'), truncated: true };
+}
+
+function normalizePhases(phases) {
+  if (!Array.isArray(phases) || phases.length === 0) return defaultPhases;
+  return phases.filter((phase) => defaultPhases.includes(phase));
+}
+
+function timeoutMs(value) {
+  return Number.isInteger(value) && value > 0 ? value : defaultTimeoutMs;
+}
+
+function maxOutputBytes(value) {
+  return Number.isInteger(value) && value > 0 ? value : defaultMaxOutputBytes;
+}
+
+function countPhases(rows, status) {
+  return rows.reduce((sum, row) => sum + row.commandRunPhases.filter((phase) => phase.executionStatus === status).length, 0);
+}
+
+function reasonForExecutionStatus(status) {
+  if (status === 'failed') return 'real-repo-command-exit-nonzero';
+  if (status === 'timed-out') return 'real-repo-command-timeout';
+  return 'real-repo-command-executed';
+}
+
+function hashText(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+export { collectRealRepoCommandExecution };