opencode-codeops 2.4.0 → 2.6.0

package/bin/lib/test-provenance.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Release provenance records and artifact verification.
+ *
+ * A provenance record is the evidence that lets production promote one artifact
+ * without repeating the full suite. It is deliberately strict: a missing full
+ * flag, a different commit, a different map, or a rebuilt artifact must fail the
+ * verifier rather than pass on a plausible-looking file.
+ *
+ * The record contains no test output, environment values, or secrets.
+ *
+ * @module lib/test-provenance
+ */
+
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync } from "node:fs"
+
+/** Gates whose evidence covers a release artifact. */
+const FULL_GATES = Object.freeze(["release", "acceptance"])
+
+/**
+ * Compute the SHA-256 digest of a file.
+ *
+ * @param {string} path File path.
+ * @returns {string} Digest in the form `sha256:<hex>`.
+ * @throws {Error} When the file cannot be read.
+ * @example
+ * sha256File("dist/app.tar.gz") // "sha256:..."
+ */
+export function sha256File(path) {
+  return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`
+}
+
+/**
+ * Check whether a value is a Git object hash.
+ *
+ * @param {unknown} value Candidate value.
+ * @returns {boolean} `true` for a 40- or 64-character hexadecimal string.
+ */
+function isCommit(value) {
+  return typeof value === "string" && /^[0-9a-f]{40}$|^[0-9a-f]{64}$/i.test(value)
+}
+
+/**
+ * Build one provenance record.
+ *
+ * @param {object} input Record input.
+ * @param {string} input.commit Tested commit.
+ * @param {string} [input.ref] Tested ref.
+ * @param {string} input.gate Gate name.
+ * @param {string|null} input.mapHash Map hash, or null for a no-map project.
+ * @param {string[]} [input.groups=[]] Groups covered by the full gate.
+ * @param {string|null} [input.fullRunId=null] CI full-run identifier.
+ * @param {string|null} [input.artifactPath=null] Artifact path.
+ * @param {string|null} [input.artifactDigest=null] Artifact digest override.
+ * @param {string|null} [input.sourceCommit=null] Commit the gate tested.
+ * @param {"source"|"artifact"} [input.artifactTested="source"] What the gate tested.
+ * @param {boolean} [input.reproducible=false] Whether a rebuild reproduced the digest.
+ * @param {object|null} [input.coverage=null] Coverage evidence.
+ * @param {object|null} [input.acceptance=null] Acceptance evidence.
+ * @param {string} [input.result="passed"] Gate result.
+ * @param {string} [input.startedAt] ISO start time.
+ * @param {string} [input.finishedAt] ISO finish time.
+ * @returns {object} Provenance record.
+ * @throws {Error} When the commit is not a Git hash or the gate is unknown.
+ * @example
+ * const record = createProvenanceRecord({ commit, gate: "release", mapHash, artifactPath: "dist/app.tgz" })
+ */
+export function createProvenanceRecord({
+  commit,
+  ref = null,
+  gate,
+  mapHash,
+  groups = [],
+  fullRunId = null,
+  artifactPath = null,
+  artifactDigest = null,
+  sourceCommit = null,
+  artifactTested = "source",
+  reproducible = false,
+  coverage = null,
+  acceptance = null,
+  result = "passed",
+  startedAt = new Date().toISOString(),
+  finishedAt = new Date().toISOString(),
+}) {
+  if (!isCommit(commit)) throw new Error("provenance commit must be a 40- or 64-character Git hash")
+  if (!FULL_GATES.includes(gate)) throw new Error(`provenance gate must be release or acceptance, got ${String(gate)}`)
+
+  let artifact = null
+  if (artifactPath || artifactDigest) {
+    if (!artifactPath && !artifactDigest) throw new Error("artifact verification needs a path or digest")
+    if (artifactPath && !existsSync(artifactPath) && !artifactDigest) {
+      throw new Error(`artifact not found: ${artifactPath}`)
+    }
+    artifact = {
+      path: artifactPath,
+      digest: artifactDigest ?? sha256File(artifactPath),
+      sourceCommit: sourceCommit ?? commit,
+      tested: artifactTested === "artifact" ? "artifact" : "source",
+      reproducible: reproducible === true,
+    }
+  }
+
+  return {
+    schema: 1,
+    commit,
+    ref,
+    gate,
+    mapHash: mapHash ?? null,
+    selection: mapHash ? "map" : "no-map",
+    full: true,
+    groups: [...groups].sort(),
+    fullRunId,
+    artifact,
+    coverage,
+    coverageStatus: coverage ? "provided" : "not-provided",
+    acceptance,
+    acceptanceStatus: acceptance ? "provided" : "not-provided",
+    startedAt,
+    finishedAt,
+    result,
+  }
+}
+
+/**
+ * Compare a record against expected release facts.
+ *
+ * @param {object} record Provenance record.
+ * @param {object} [expected] Expected facts.
+ * @param {string} [expected.commit] Expected tested commit.
+ * @param {string} [expected.mapHash] Expected map hash.
+ * @param {string} [expected.artifactPath] Artifact to re-hash.
+ * @param {string} [expected.artifactDigest] Expected artifact digest.
+ * @returns {{ok: boolean, errors: Array<{field: string, message: string}>}} Verification result.
+ * @example
+ * const result = verifyProvenance(record, { artifactPath: "dist/app.tar.gz" })
+ * if (!result.ok) process.exitCode = 1
+ */
+export function verifyProvenance(record, expected = {}) {
+  const errors = []
+  const fail = (field, message) => errors.push({ field, message })
+
+  if (!record || typeof record !== "object" || record.schema !== 1) {
+    fail("schema", "record must use schema 1")
+    return { ok: false, errors }
+  }
+  if (!isCommit(record.commit)) fail("commit", "record commit is not a Git hash")
+  if (expected.commit && record.commit !== expected.commit) {
+    fail("commit", `expected ${expected.commit}, got ${record.commit}`)
+  }
+
+  if (record.mapHash === null) {
+    if (record.selection !== "no-map") fail("selection", "a null map hash requires selection no-map")
+  } else {
+    if (record.selection !== "map") fail("selection", "a map hash requires selection map")
+    if (expected.mapHash && record.mapHash !== expected.mapHash) {
+      fail("mapHash", `expected ${expected.mapHash}, got ${record.mapHash}`)
+    }
+  }
+
+  if (FULL_GATES.includes(record.gate) && record.full !== true) {
+    fail("full", "release and acceptance records must have full: true")
+  }
+  if (record.result !== "passed") fail("result", `gate result is ${String(record.result)}, not passed`)
+
+  if (record.artifact) {
+    if (!record.artifact.digest) fail("artifact.digest", "artifact evidence needs a digest")
+    if (record.artifact.sourceCommit !== record.commit) {
+      fail("artifact.sourceCommit", "artifact source commit must match the tested commit")
+    }
+    if (record.artifact.tested !== "artifact" && record.artifact.reproducible !== true) {
+      fail("artifact.reproducible", "a source-tested artifact needs a reproducible rebuild")
+    }
+  }
+
+  const expectedDigest =
+    expected.artifactDigest ??
+    (expected.artifactPath && existsSync(expected.artifactPath) ? sha256File(expected.artifactPath) : null)
+  if (expectedDigest) {
+    if (!record.artifact?.digest) fail("artifact.digest", "record has no artifact digest")
+    else if (record.artifact.digest !== expectedDigest) {
+      fail("artifact.digest", `expected ${expectedDigest}, got ${record.artifact.digest}`)
+    }
+  }
+
+  return { ok: errors.length === 0, errors }
+}

package/bin/lib/test-runner.d.mts

@@ -0,0 +1,72 @@
+/**
+ * Type declarations for the argv-safe test runner.
+ */
+
+/** One command result. */
+export interface RunResult {
+  id: string
+  status: "passed" | "failed" | "timeout"
+  exitCode: number
+  durationMs: number
+  logPath: string | null
+  output: string
+  tail: string
+}
+
+/** Error raised when a command cannot run safely. */
+export declare class RunnerError extends Error {
+  code: string
+  constructor(code: string, message: string)
+}
+
+/** Default per-group timeout. */
+export declare const DEFAULT_GROUP_TIMEOUT_SECONDS: number
+
+/** Default full-suite timeout. */
+export declare const DEFAULT_FULL_TIMEOUT_SECONDS: number
+
+/** Resolve the captured-log directory. */
+export declare function resolveLogDir(env?: Record<string, string>): string
+
+/** Resolve and contain a command working directory. */
+export declare function resolveWorkingDirectory(root: string, cwd?: string): string
+
+/** Keep the last N lines of a log. */
+export declare function tailLines(text: string, count?: number): string
+
+/** Run one argv command. */
+export declare function runArgv(input: {
+  id: string
+  argv: string[]
+  cwd?: string
+  root: string
+  timeoutSeconds?: number
+  env?: Record<string, string>
+  gate?: string
+  keepLogs?: boolean
+  serial?: number
+}): Promise<RunResult>
+
+/** Read a retained log. */
+export declare function readRetainedLog(logPath: string | null): string
+
+/** Run commands sequentially or in a bounded pool. */
+export declare function runCommands(
+  commands: Array<{ id: string; argv: string[]; cwd?: string; parallelSafe?: boolean }>,
+  options: {
+    root: string
+    concurrency?: number
+    failFast?: boolean
+    timeoutSeconds?: number
+    env?: Record<string, string>
+    gate?: string
+    keepLogs?: boolean
+  }
+): Promise<RunResult[]>
+
+/** Run one requirement probe. */
+export declare function probeRequirement(input: {
+  argv: string[]
+  root: string
+  env?: Record<string, string>
+}): Promise<boolean>

package/bin/lib/test-runner.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+/**
+ * Argv-safe command execution for the test selector.
+ *
+ * The runner never builds a shell string. It spawns the program named by the
+ * first argv token with the remaining tokens as arguments, so a path containing
+ * spaces, semicolons, or `$()` stays one inert argument.
+ *
+ * Logs are temporary artifacts. A passing command deletes its log; a failing or
+ * timed-out command keeps the log, reports its path, and exposes the last lines
+ * so a developer can act without re-running the suite.
+ *
+ * @module lib/test-runner
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { isAbsolute, join, relative, resolve } from "node:path"
+
+/** Default per-group timeout in seconds. */
+export const DEFAULT_GROUP_TIMEOUT_SECONDS = 600
+
+/** Default full-suite timeout in seconds. */
+export const DEFAULT_FULL_TIMEOUT_SECONDS = 1800
+
+/** Maximum captured output retained in memory per stream. */
+const MAX_CAPTURE_BYTES = 2 * 1024 * 1024
+
+/** Number of trailing log lines reported on failure. */
+const FAILURE_TAIL_LINES = 50
+
+/**
+ * Error raised when a command cannot be run safely.
+ *
+ * `code` is stable (`cwd-escape`, `missing-command`) so the CLI can choose the
+ * documented exit code.
+ */
+export class RunnerError extends Error {
+  /**
+   * @param {string} code Stable error code.
+   * @param {string} message Human-readable explanation.
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = "RunnerError"
+    this.code = code
+  }
+}
+
+/**
+ * Resolve the directory that holds captured logs.
+ *
+ * @param {Record<string, string>} [env] Environment values.
+ * @returns {string} Existing temporary directory.
+ */
+export function resolveLogDir(env = process.env) {
+  const directory = env.CODEOPS_TMPDIR || tmpdir()
+  mkdirSync(directory, { recursive: true })
+  return directory
+}
+
+/**
+ * Resolve and contain a command working directory.
+ *
+ * Both the lexical path and the real path must stay under the repository root,
+ * which also blocks a symlinked subdirectory from escaping.
+ *
+ * @param {string} root Repository root.
+ * @param {string} [cwd="."] Requested working directory.
+ * @returns {string} Absolute, contained working directory.
+ * @throws {RunnerError} When the directory escapes the root or does not exist.
+ */
+export function resolveWorkingDirectory(root, cwd = ".") {
+  const absoluteRoot = realpathSync(resolve(root))
+  const candidate = isAbsolute(cwd) ? resolve(cwd) : resolve(absoluteRoot, cwd)
+  const relation = relative(absoluteRoot, candidate)
+  if (relation.startsWith("..") || isAbsolute(relation)) {
+    throw new RunnerError("cwd-escape", `cwd ${cwd} escapes the repository root`)
+  }
+  if (!existsSync(candidate)) throw new RunnerError("missing-cwd", `cwd ${cwd} does not exist`)
+  const real = realpathSync(candidate)
+  const realRelation = relative(absoluteRoot, real)
+  if (realRelation.startsWith("..") || isAbsolute(realRelation)) {
+    throw new RunnerError("cwd-escape", `cwd ${cwd} resolves outside the repository root`)
+  }
+  return real
+}
+
+/**
+ * Keep only the last N lines of a log.
+ *
+ * @param {string} text Log text.
+ * @param {number} [count=FAILURE_TAIL_LINES] Number of lines to keep.
+ * @returns {string} Trailing lines.
+ */
+export function tailLines(text, count = FAILURE_TAIL_LINES) {
+  return String(text ?? "")
+    .split(/\r?\n/)
+    .filter((line, index, lines) => !(index === lines.length - 1 && line === ""))
+    .slice(-count)
+    .join("\n")
+}
+
+/**
+ * Create a safe log file name from a group ID.
+ *
+ * @param {string} id Group or command ID.
+ * @param {number} serial Monotonic serial for uniqueness.
+ * @returns {string} File name with no path separators.
+ */
+function logFileName(id, serial) {
+  const safe = String(id).replace(/[^A-Za-z0-9_.-]+/g, "_").slice(0, 80)
+  return `codeops-test-${safe}-${process.pid}-${serial}.log`
+}
+
+/**
+ * Run one argv command asynchronously.
+ *
+ * @param {object} input Execution input.
+ * @param {string} input.id Group or command ID.
+ * @param {string[]} input.argv Program and arguments.
+ * @param {string} [input.cwd="."] Working directory inside the root.
+ * @param {string} input.root Repository root.
+ * @param {number} [input.timeoutSeconds] Timeout override.
+ * @param {Record<string, string>} [input.env] Extra environment values.
+ * @param {string} [input.gate] Gate name for diagnostics.
+ * @param {boolean} [input.keepLogs=false] Keep success logs.
+ * @param {number} [input.serial=0] Serial used in the log name.
+ * @returns {Promise<{id: string, status: "passed"|"failed"|"timeout", exitCode: number, durationMs: number, logPath: string|null, output: string, tail: string}>}
+ * @throws {RunnerError} When the command cannot start safely.
+ * @example
+ * const result = await runArgv({ id: "a.unit", argv: ["node", "--test", "a.test.js"], root: process.cwd() })
+ */
+export async function runArgv({
+  id,
+  argv,
+  cwd = ".",
+  root,
+  timeoutSeconds = DEFAULT_GROUP_TIMEOUT_SECONDS,
+  env = {},
+  gate,
+  keepLogs = false,
+  serial = 0,
+}) {
+  if (!Array.isArray(argv) || argv.length === 0 || typeof argv[0] !== "string") {
+    throw new RunnerError("missing-command", `group ${id} has no runnable command`)
+  }
+  const workingDirectory = resolveWorkingDirectory(root, cwd)
+  const logPath = join(resolveLogDir(env), logFileName(id, serial))
+  const started = Date.now()
+
+  return new Promise((resolvePromise) => {
+    let stdout = ""
+    let stderr = ""
+    let timedOut = false
+
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: workingDirectory,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        ...env,
+        CODEOPS_TEST_GROUP: id,
+        ...(gate ? { CODEOPS_TEST_GATE: gate } : {}),
+      },
+    })
+
+    const append = (current, chunk) => {
+      const next = current + chunk.toString("utf8")
+      return next.length > MAX_CAPTURE_BYTES ? next.slice(-MAX_CAPTURE_BYTES) : next
+    }
+    child.stdout.on("data", (chunk) => {
+      stdout = append(stdout, chunk)
+    })
+    child.stderr.on("data", (chunk) => {
+      stderr = append(stderr, chunk)
+    })
+
+    const timer =
+      timeoutSeconds > 0
+        ? setTimeout(() => {
+            timedOut = true
+            child.kill("SIGKILL")
+          }, timeoutSeconds * 1000)
+        : null
+
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer)
+      const output = `cannot start ${argv[0]}: ${error.message}\n`
+      writeFileSync(logPath, output)
+      resolvePromise({
+        id,
+        status: "failed",
+        exitCode: 127,
+        durationMs: Date.now() - started,
+        logPath,
+        output,
+        tail: output.trim(),
+      })
+    })
+
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer)
+      const output = `${stdout}${stderr}`
+      const status = timedOut ? "timeout" : code === 0 ? "passed" : "failed"
+      writeFileSync(logPath, output)
+
+      if (status === "passed" && !keepLogs) {
+        unlinkSync(logPath)
+        resolvePromise({
+          id,
+          status,
+          exitCode: 0,
+          durationMs: Date.now() - started,
+          logPath: null,
+          output,
+          tail: "",
+        })
+        return
+      }
+
+      const header = timedOut ? `timeout after ${timeoutSeconds}s\n` : ""
+      resolvePromise({
+        id,
+        status,
+        exitCode: timedOut ? 124 : code ?? 1,
+        durationMs: Date.now() - started,
+        logPath,
+        output: `${header}${output}`,
+        tail: tailLines(`${header}${output}`),
+      })
+    })
+  })
+}
+
+/**
+ * Read a retained log when a caller needs more than the tail.
+ *
+ * @param {string|null} logPath Retained log path.
+ * @returns {string} Log text, or an empty string when unavailable.
+ */
+export function readRetainedLog(logPath) {
+  if (!logPath || !existsSync(logPath)) return ""
+  return readFileSync(logPath, "utf8")
+}
+
+/**
+ * Run commands sequentially or in a bounded pool.
+ *
+ * Concurrency is allowed only when every command declares `parallelSafe`. A
+ * mixed set runs sequentially, because one shared resource would otherwise make
+ * results depend on scheduling.
+ *
+ * @param {Array<{id: string, argv: string[], cwd?: string, parallelSafe?: boolean}>} commands Commands to run.
+ * @param {object} options Execution options.
+ * @param {string} options.root Repository root.
+ * @param {number} [options.concurrency=1] Maximum concurrent commands.
+ * @param {boolean} [options.failFast=true] Stop after the first failure.
+ * @param {number} [options.timeoutSeconds] Per-command timeout.
+ * @param {Record<string, string>} [options.env] Extra environment values.
+ * @param {string} [options.gate] Gate name.
+ * @param {boolean} [options.keepLogs=false] Keep success logs.
+ * @returns {Promise<Array<object>>} Results in completion order.
+ * @example
+ * const results = await runCommands([{ id: "a", argv: ["node", "--test", "a.test.js"] }], { root: "." })
+ */
+export async function runCommands(
+  commands,
+  { root, concurrency = 1, failFast = true, timeoutSeconds, env = {}, gate, keepLogs = false } = {},
+) {
+  const results = []
+  const parallel = concurrency > 1 && commands.every((command) => command.parallelSafe === true)
+
+  if (!parallel) {
+    for (const [index, command] of commands.entries()) {
+      const result = await runArgv({
+        ...command,
+        root,
+        timeoutSeconds,
+        env,
+        gate,
+        keepLogs,
+        serial: index,
+      })
+      results.push(result)
+      if (failFast && result.status !== "passed") break
+    }
+    return results
+  }
+
+  let cursor = 0
+  let stopped = false
+  const worker = async () => {
+    while (!stopped && cursor < commands.length) {
+      const index = cursor
+      cursor += 1
+      const result = await runArgv({
+        ...commands[index],
+        root,
+        timeoutSeconds,
+        env,
+        gate,
+        keepLogs,
+        serial: index,
+      })
+      results.push(result)
+      if (failFast && result.status !== "passed") stopped = true
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, commands.length) }, () => worker()))
+  return results
+}
+
+/**
+ * Run one requirement probe.
+ *
+ * A failing probe is reported as `false`; the caller fails the dependent group
+ * instead of skipping it.
+ *
+ * @param {object} input Probe input.
+ * @param {string[]} input.argv Probe argv.
+ * @param {string} input.root Repository root.
+ * @param {Record<string, string>} [input.env] Extra environment values.
+ * @returns {Promise<boolean>} `true` when the probe exits zero.
+ */
+export async function probeRequirement({ argv, root, env = {} }) {
+  const workingDirectory = resolveWorkingDirectory(root, ".")
+  return new Promise((resolvePromise) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: workingDirectory,
+      shell: false,
+      stdio: "ignore",
+      env: { ...process.env, ...env },
+    })
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL")
+      resolvePromise(false)
+    }, 30_000)
+    child.on("error", () => {
+      clearTimeout(timer)
+      resolvePromise(false)
+    })
+    child.on("close", (code) => {
+      clearTimeout(timer)
+      resolvePromise(code === 0)
+    })
+  })
+}

package/bin/lib/test-selection-changes.d.mts

@@ -0,0 +1,76 @@
+/**
+ * Type declarations for change detection and baseline resolution.
+ */
+
+/** A resolved Git base. */
+export interface SelectionBase {
+  kind: "tree" | "ref"
+  value: string
+}
+
+/** A rename entry from `git diff --name-status`. */
+export interface SelectionRename {
+  from: string
+  to: string
+  score: string
+}
+
+/** Parsed Git name-status output. */
+export interface ParsedNameStatus {
+  changed: string[]
+  renames: SelectionRename[]
+  deleted: string[]
+}
+
+/** Git runner result. */
+export interface GitResult {
+  status: number
+  stdout: string
+  stderr?: string
+}
+
+/** Error raised when a base cannot be resolved. */
+export declare class SelectionError extends Error {
+  reason: string
+  constructor(reason: string, message: string)
+}
+
+/** Run a read-only Git command. */
+export declare function defaultRunGit(
+  args: string[],
+  options?: { cwd?: string }
+): GitResult
+
+/** Parse NUL-separated name-status output. */
+export declare function parseNameStatusZ(output: string): ParsedNameStatus
+
+/** Parse NUL-separated path lists. */
+export declare function parseNullList(output: string): string[]
+
+/** Resolve the selection base. */
+export declare function resolveBaseline(input?: {
+  baseline?: string
+  lastFullSha?: string
+  branch?: string
+  isTag?: boolean
+  env?: Record<string, string>
+  runGit?: (args: string[], options?: { cwd?: string }) => GitResult
+}): SelectionBase
+
+/** Collect every changed path for a selection run. */
+export declare function collectChanges(input: {
+  root: string
+  baseline?: string
+  lastFullSha?: string
+  branch?: string
+  isTag?: boolean
+  include?: string[]
+  env?: Record<string, string>
+  runGit?: (args: string[], options?: { cwd?: string }) => GitResult
+}): {
+  base: SelectionBase
+  changed: string[]
+  renames: SelectionRename[]
+  deleted: string[]
+  warnings: object[]
+}