@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/package-checks/code-quality-findings/finding-waiver-evidence.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+
+import type { CheckExecutionContext } from "../../check/check.ts";
+import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+import type {
+  FindingWaiverAudit,
+  FindingWaiverReconciliation
+} from "../../package-tools/finding-waivers/reconciliation.ts";
+
+interface CodeQualityFindingCandidate {
+  readonly data: Readonly<{ readonly blocking: boolean }>;
+  readonly id: string;
+}
+
+type FindingRecordContext = Pick<CheckExecutionContext<object>, "records">;
+
+const FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX = "/finding-waiver-audit/";
+
+export type FindingWaiverRecordAudit = Readonly<
+  Omit<FindingWaiverAudit, "status"> & {
+    readonly status: "overmatched" | "unused";
+  }
+>;
+
+export type FindingWaiverAuditRecordData<Identity> = Readonly<{
+  readonly identity: Identity;
+  readonly kind: "finding-waiver-audit";
+  readonly matchCount: number;
+  readonly reason: string;
+  readonly status: "overmatched" | "unused";
+}>;
+
+/** Builds the common immutable data shared by Check-owned waiver audit Records. */
+export function buildFindingWaiverAuditRecordData<Identity>(
+  identity: Identity,
+  audit: FindingWaiverRecordAudit
+): FindingWaiverAuditRecordData<Identity> {
+  return Object.freeze({
+    identity,
+    kind: "finding-waiver-audit",
+    matchCount: audit.matchCount,
+    reason: audit.waiver.reason,
+    status: audit.status
+  });
+}
+
+/** Builds the shared hash-addressed audit Record used by structured identities. */
+export function buildHashedFindingWaiverAuditRecord<Identity>(
+  identity: Identity,
+  audit: FindingWaiverRecordAudit
+): Readonly<{ readonly data: FindingWaiverAuditRecordData<Identity>; readonly id: string }> {
+  const digest = createHash("sha256").update(canonicalJsonBytes(identity)).digest("hex");
+  return Object.freeze({
+    data: buildFindingWaiverAuditRecordData(identity, audit),
+    id: `${FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX}sha256:${digest}`
+  });
+}
+
+/** Publishes every reconciled metric Finding while preserving applied waiver evidence. */
+export function reportReconciledCodeQualityFindingRecords<
+  Finding extends CodeQualityFindingCandidate
+>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>): void {
+  for (const finding of reconciliation.findings) {
+    const data =
+      finding.disposition === "waived"
+        ? Object.freeze({
+            ...finding.finding.data,
+            blocking: false,
+            waiver: Object.freeze({ reason: finding.waiver.reason })
+          })
+        : finding.finding.data;
+    context.records.report({ id: finding.finding.id }, data);
+  }
+}
+
+/** Publishes only unused/overmatched audit rows built by the identity-owning Check. */
+export function reportFindingWaiverAudits<Finding, AuditData extends object>(
+  context: FindingRecordContext,
+  reconciliation: FindingWaiverReconciliation<Finding>,
+  buildRecord: (
+    audit: FindingWaiverRecordAudit
+  ) => Readonly<{ readonly data: AuditData; readonly id: string }>
+): void {
+  for (const audit of reconciliation.waiverAudits) {
+    if (audit.status === "applied") continue;
+    const record = buildRecord(
+      Object.freeze({
+        matchCount: audit.matchCount,
+        status: audit.status,
+        waiver: audit.waiver
+      })
+    );
+    context.records.report({ id: record.id }, record.data);
+  }
+}

package/src/package-checks/code-quality-findings/policy.ts

@@ -1,4 +1,6 @@
 import type { CheckMessage, CheckResult } from "../../check/check.ts";
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString } from "../../data-boundary/value-shapes.ts";
 
 export const FINDING_POLICIES = Object.freeze(["blocking", "non-blocking"] as const);
 
@@ -9,7 +11,9 @@ export const DEFAULT_FINDING_POLICY: FindingPolicy = "non-blocking";
 
 /** 三个代码质量 Check 正常完成时返回的精确 finding 计数。 */
 export interface FindingSummary {
+  /** 仍可处置且采用 blocking policy 的 finding 数；waived finding 不计入。 */
   readonly blockingFindingCount: number;
+  /** Check 发现的全部 finding 数，包括已 waived 或 non-blocking 的 finding。 */
   readonly findingCount: number;
 }
 
@@ -32,6 +36,25 @@ export function validFindingPolicy(value: unknown): value is FindingPolicy {
   return FINDING_POLICIES.some((policy) => policy === value);
 }
 
+/** Resolves the closed, non-empty named area map shared by code-quality Checks. */
+export function resolveCodeAreaPolicyMap<Area>(
+  value: unknown,
+  defaultArea: () => Area,
+  resolveArea: (candidate: unknown) => Area | undefined
+): Readonly<Record<string, Area>> | undefined {
+  if (value === undefined) return Object.freeze({ project: defaultArea() });
+  const areas = snapshotClosedRecord(value);
+  if (areas === undefined || Object.keys(areas).length === 0) return undefined;
+  const resolvedEntries: Array<readonly [string, Area]> = [];
+  for (const [areaId, candidate] of Object.entries(areas)) {
+    if (!isNonEmptyString(areaId)) return undefined;
+    const area = resolveArea(candidate);
+    if (area === undefined) return undefined;
+    resolvedEntries.push([areaId, area]);
+  }
+  return Object.freeze(Object.fromEntries(resolvedEntries));
+}
+
 export function isBlockingFinding(policies: readonly FindingPolicy[]): boolean {
   return policies.some((policy) => policy === "blocking");
 }

package/src/package-checks/command-check/command-check.ts

@@ -0,0 +1,152 @@
+import { executeCommandCheck } from "./execution.ts";
+import type { Check, CheckDataParser } from "../../check/check.ts";
+import { resolveCommandCheckInput } from "./options.ts";
+import type {
+  AfterCommand,
+  AfterCommandExecution,
+  CommandCheck,
+  CommandCheckInput,
+  CommandCheckWithAfterCommand,
+  ResolvedCommandCheckOptions,
+  TypedCommandCheck
+} from "./contract.ts";
+
+export type {
+  AfterCommand,
+  AfterCommandContext,
+  AfterCommandExecution,
+  CommandCheckWithAfterCommand,
+  CommandEnvironmentContext,
+  CommandEnvironmentResolver,
+  CompletedCommand,
+  CommandCheck,
+  CommandCheckEnvironment,
+  CommandCheckFinalData,
+  CommandCheckInput,
+  CommandCheckOutput,
+  CommandCheckUnavailableReasonCode,
+  TypedCommandCheck
+} from "./contract.ts";
+
+type CommandCheckImplementationInput = CommandCheckInput<string, AfterCommand | undefined>;
+
+/**
+ * 构造一个单一 no-shell executable 的 ordinary Check。
+ *
+ * @remarks constructor 会闭合并冻结 command-owned options；ordinary selection、relation 与 scheduling fields 仍按普通 Check lifecycle 传递。默认 exact-empty environment 与 discard output 不会把 ambient variables、child stdout/stderr 或 native error text 发布到 Check facts。`output: { mode: "transcript" }` 仅在 invocation 授予此 Check artifact directory 时，将 raw stdout/stderr 写入固定 `process.log`。
+ * @example 以 process.execPath 构造无 shell command Check
+ * ```ts
+ * import { commandCheck, defineConfig, run } from "@zxyycom/vibe-check";
+ *
+ * const nodeProbe = commandCheck({
+ *   checkId: "node-probe",
+ *   displayName: "Node probe",
+ *   executable: process.execPath,
+ *   arguments: ["--eval", "process.exit(0)"],
+ *   timeoutMs: 5_000,
+ *   outputByteLimit: 64 * 1024
+ * });
+ *
+ * const definition = defineConfig({
+ *   checks: [nodeProbe],
+ *   outputs: {
+ *     diagnosticLogging: { enabled: false },
+ *     machinePublication: { enabled: false },
+ *     progressRendering: { enabled: false }
+ *   }
+ * });
+ *
+ * const result = await run(definition);
+ * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+ * const outcome = result.snapshot.checks.find(
+ *   ({ checkId }) => checkId === nodeProbe.checkId
+ * )?.outcome;
+ * if (outcome?.status !== "passed" || outcome.data.exitCode !== 0) {
+ *   throw new Error("Node probe did not produce the expected passed outcome");
+ * }
+ * ```
+ */
+export function commandCheck<const Id extends string, const FinalData extends object>(
+  input: CommandCheckInput<
+    Id,
+    Readonly<{
+      readonly execute: AfterCommandExecution<FinalData>;
+      readonly parseData?: never;
+    }>
+  >
+): CommandCheckWithAfterCommand<Id, FinalData>;
+export function commandCheck<const Id extends string, const Parser extends CheckDataParser>(
+  input: CommandCheckInput<
+    Id,
+    Readonly<{
+      readonly execute: AfterCommandExecution<NoInfer<ReturnType<Parser>>>;
+      readonly parseData: Parser;
+    }>
+  >
+): TypedCommandCheck<Id, Parser>;
+export function commandCheck<const Id extends string>(
+  input: CommandCheckInput<Id>
+): CommandCheck<Id>;
+export function commandCheck(input: CommandCheckImplementationInput): Check {
+  const commandInput = input;
+  const resolved = resolveCommandCheckInput(input);
+  if (resolved === undefined) {
+    throw new TypeError(
+      "commandCheck input must match the documented closed command and ordinary Check authoring policy"
+    );
+  }
+  return {
+    ...(commandInput.admissionPriority === undefined
+      ? {}
+      : { admissionPriority: commandInput.admissionPriority }),
+    ...(commandInput.checks === undefined ? {} : { checks: commandInput.checks }),
+    ...(commandInput.dependsOn === undefined ? {} : { dependsOn: commandInput.dependsOn }),
+    ...(commandInput.enabledByFlags === undefined
+      ? {}
+      : { enabledByFlags: commandInput.enabledByFlags }),
+    ...(commandInput.maxParallel === undefined ? {} : { maxParallel: commandInput.maxParallel }),
+    ...(commandInput.mutex === undefined ? {} : { mutex: commandInput.mutex }),
+    ...(commandInput.observes === undefined ? {} : { observes: commandInput.observes }),
+    ...(commandInput.omitQuietPassedRow === undefined
+      ? {}
+      : { omitQuietPassedRow: commandInput.omitQuietPassedRow }),
+    ...(commandInput.resourceClaims === undefined
+      ? {}
+      : { resourceClaims: commandInput.resourceClaims }),
+    checkId: commandInput.checkId,
+    displayName: commandInput.displayName,
+    execute: (context: Parameters<CommandCheck["execute"]>[0]) =>
+      executeCommandCheck(context, {
+        afterCommand: resolved.afterCommand,
+        resolveEnvironment: resolved.resolveEnvironment
+      }),
+    options: resolved.options,
+    prepare: (options: ResolvedCommandCheckOptions) =>
+      isRevalidatedCommandOptions(options, commandInput.checkId, commandInput.displayName)
+        ? { status: "success", preparedOptions: options }
+        : { status: "failure", action: "block", reason: { code: "invalid-options" } },
+    ...(resolved.afterCommand?.parseData === undefined
+      ? {}
+      : { parseData: resolved.afterCommand.parseData })
+  };
+}
+
+function isRevalidatedCommandOptions<Id extends string>(
+  options: ResolvedCommandCheckOptions,
+  checkId: Id,
+  displayName: string
+): boolean {
+  return (
+    resolveCommandCheckInput({
+      checkId,
+      displayName,
+      executable: options.executable,
+      arguments: options.arguments,
+      environment: options.environment,
+      output: options.output,
+      outputByteLimit: options.outputByteLimit,
+      timeoutMs: options.timeoutMs,
+      ...(options.workingDirectory === null ? {} : { workingDirectory: options.workingDirectory })
+    }) !== undefined
+  );
+}

package/src/package-checks/command-check/contract.ts

@@ -0,0 +1,168 @@
+import type {
+  Check,
+  CheckDataParser,
+  CheckDependencies,
+  CheckExecutionContext,
+  CheckFlagEnablement,
+  CheckProjectContext,
+  CheckResourceClaims,
+  CheckResult,
+  CheckWithOptions,
+  DeepReadonly,
+  InheritableCheckCollection,
+  TypedCheckWithOptions
+} from "../../check/check.ts";
+
+/** command Check 的显式环境策略；默认 exact-empty，避免定义时读取 ambient environment。 */
+export type CommandCheckEnvironment =
+  | Readonly<{
+      readonly mode: "exact";
+      readonly variables?: Readonly<Record<string, string>>;
+    }>
+  | Readonly<{
+      readonly mode: "inherit";
+      readonly overrides?: Readonly<Record<string, string | null>>;
+    }>;
+
+/** child stdout/stderr 的处理边界；默认 discard。 */
+export type CommandCheckOutput = Readonly<{ readonly mode: "discard" | "transcript" }>;
+
+/** command 以 numeric exit status 结束时发布的唯一 final data。 */
+export interface CommandCheckFinalData {
+  /** child process 的 numeric exit status。 */
+  readonly exitCode: number;
+}
+
+/** 已完整结束且只在 invocation-local callback 中可见的 child material。 */
+export interface CompletedCommand {
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+
+/** spawn 前 environment resolver 可读取的最小 invocation context。 */
+export interface CommandEnvironmentContext {
+  readonly dependencies: CheckDependencies;
+  readonly options: DeepReadonly<ResolvedCommandCheckOptions>;
+  readonly project: CheckProjectContext;
+  readonly signal: AbortSignal;
+}
+
+/** 完整 command 后 caller-owned settlement 可读取的 context。 */
+export type AfterCommandContext = CheckExecutionContext<ResolvedCommandCheckOptions> &
+  Readonly<{ readonly command: CompletedCommand }>;
+
+/** 完整 command 的 caller-owned settlement callback。 */
+export type AfterCommandExecution<FinalData extends object = object> = (
+  this: void,
+  context: AfterCommandContext
+) => CheckResult<FinalData> | Promise<CheckResult<FinalData>>;
+
+/** command 完成后的可选 caller-owned settlement 与 typed-provider parser。 */
+export type AfterCommand<FinalData extends object = object> = Readonly<{
+  readonly execute: AfterCommandExecution<FinalData>;
+  readonly parseData?: CheckDataParser | undefined;
+}>;
+
+/** spawn 前解析此次 command closed environment policy 的 callback。 */
+export type CommandEnvironmentResolver = (
+  this: void,
+  context: CommandEnvironmentContext
+) => CommandCheckEnvironment | Promise<CommandCheckEnvironment>;
+
+/** command Check 自己产生的 stable unavailable reason code。 */
+export type CommandCheckUnavailableReasonCode =
+  | "command-environment-resolution-failed"
+  | "command-output-limit-exceeded"
+  | "command-start-failed"
+  | "command-terminated-by-signal"
+  | "command-timeout"
+  | "command-transcript-unavailable"
+  | "invalid-options";
+
+/** `commandCheck` 的 closed authoring input；ordinary Check composition fields 原样交由 Core 处理。 */
+interface CommandCheckBaseInput<Id extends string> {
+  readonly checkId: Id;
+  readonly displayName: string;
+  readonly executable: string;
+  readonly arguments?: readonly string[];
+  readonly workingDirectory?: string;
+  readonly timeoutMs: number;
+  readonly outputByteLimit: number;
+  readonly output?: CommandCheckOutput;
+  readonly enabledByFlags?: CheckFlagEnablement;
+  readonly checks?: readonly Check[];
+  readonly dependsOn?: InheritableCheckCollection<string>;
+  readonly observes?: InheritableCheckCollection<string>;
+  readonly maxParallel?: number;
+  readonly admissionPriority?: number;
+  readonly mutex?: InheritableCheckCollection<string>;
+  readonly resourceClaims?: CheckResourceClaims;
+  readonly omitQuietPassedRow?: true;
+}
+
+/** Static environment 与 invocation-time resolver 互斥；两者都省略时使用 exact-empty。 */
+export type CommandCheckInput<
+  Id extends string = string,
+  After extends AfterCommand | undefined = undefined
+> = CommandCheckBaseInput<Id> &
+  (
+    | Readonly<{
+        readonly environment?: CommandCheckEnvironment;
+        readonly resolveEnvironment?: never;
+      }>
+    | Readonly<{
+        readonly environment?: never;
+        readonly resolveEnvironment: CommandEnvironmentResolver;
+      }>
+  ) &
+  (After extends undefined
+    ? Readonly<{ readonly afterCommand?: undefined }>
+    : Readonly<{ readonly afterCommand: After }>);
+
+/** command constructor materializes、冻结并在 preparation 再次验证的内部完整 options。 */
+export interface ResolvedCommandCheckOptions {
+  readonly arguments: readonly string[];
+  readonly environment:
+    | Readonly<{ readonly mode: "exact"; readonly variables: Readonly<Record<string, string>> }>
+    | Readonly<{
+        readonly mode: "inherit";
+        readonly overrides: Readonly<Record<string, string | null>>;
+      }>;
+  readonly executable: string;
+  readonly output: Readonly<{ readonly mode: "discard" | "transcript" }>;
+  readonly outputByteLimit: number;
+  readonly timeoutMs: number;
+  /** `null` 表示 execution 时使用 invocation project root。 */
+  readonly workingDirectory: string | null;
+}
+
+/** 可放入普通 Project Definition 的 process-backed Check。 */
+export type CommandCheck<Id extends string = string> = CheckWithOptions<
+  Id,
+  ResolvedCommandCheckOptions
+> &
+  Readonly<{
+    execute(
+      this: void,
+      context: CheckExecutionContext<ResolvedCommandCheckOptions>
+    ): CheckResult<CommandCheckFinalData> | Promise<CheckResult<CommandCheckFinalData>>;
+  }>;
+
+/** 带 caller-owned completion callback 的 ordinary command Check。 */
+export type CommandCheckWithAfterCommand<Id extends string, FinalData extends object> = Omit<
+  CheckWithOptions<Id, ResolvedCommandCheckOptions>,
+  "execute"
+> &
+  Readonly<{
+    execute(
+      this: void,
+      context: CheckExecutionContext<ResolvedCommandCheckOptions>
+    ): CheckResult<FinalData> | Promise<CheckResult<FinalData>>;
+  }>;
+
+/** 带 caller-owned completion callback 与 parser 的 typed-provider command Check。 */
+export type TypedCommandCheck<
+  Id extends string,
+  Parser extends CheckDataParser
+> = TypedCheckWithOptions<Id, ResolvedCommandCheckOptions, Parser>;

package/src/package-checks/command-check/execution.ts

@@ -0,0 +1,211 @@
+import { isAbsolute, resolve } from "node:path";
+
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { runProcess } from "../host-environment/process.ts";
+import { isValidResolvedCommandCheckOptions, resolveCommandCheckEnvironment } from "./options.ts";
+import { closedTranscript, runningTranscript, writeCommandTranscript } from "./transcript.ts";
+import type {
+  AfterCommand,
+  CommandCheckFinalData,
+  CommandEnvironmentResolver,
+  CommandCheckUnavailableReasonCode,
+  ResolvedCommandCheckOptions
+} from "./contract.ts";
+
+type CommandProcessResult = Awaited<ReturnType<typeof runProcess>> &
+  Readonly<{ readonly isCanceled?: true; readonly isMaxBuffer?: true; readonly timedOut?: true }>;
+
+/** Executes one validated no-shell command and releases all child material after optional transcript persistence. */
+export async function executeCommandCheck(
+  context: CheckExecutionContext<ResolvedCommandCheckOptions>,
+  executionExtensions: Readonly<{
+    readonly afterCommand?: AfterCommand | undefined;
+    readonly resolveEnvironment?: CommandEnvironmentResolver | undefined;
+  }> = {}
+): Promise<CheckResult> {
+  if (!isValidResolvedCommandCheckOptions(context.options)) return unavailable("invalid-options");
+
+  const environment = await resolveExecutionEnvironment(
+    context,
+    executionExtensions.resolveEnvironment
+  );
+  if (environment === undefined) return unavailable("command-environment-resolution-failed");
+
+  return executeResolvedCommand(context, environment, executionExtensions.afterCommand);
+}
+
+/** Runs one resolved command, preserving requested transcripts before caller-owned settlement. */
+async function executeResolvedCommand(
+  context: CheckExecutionContext<ResolvedCommandCheckOptions>,
+  environment: ResolvedCommandCheckOptions["environment"],
+  afterCommand: AfterCommand | undefined
+): Promise<CheckResult> {
+  const { options } = context;
+  if (!(await writeRunningCommandTranscript(context.artifactDirectory, options.output.mode))) {
+    return unavailable("command-transcript-unavailable");
+  }
+
+  const result = await runProcess({
+    args: options.arguments,
+    cancelSignal: context.signal,
+    command: options.executable,
+    cwd: resolveWorkingDirectory(options.workingDirectory, context.project.root),
+    env: executionEnvironment(environment),
+    extendEnv: false,
+    label: "command Check",
+    maxBuffer: options.outputByteLimit,
+    timeout: options.timeoutMs
+  });
+  const terminal = terminalResult(result);
+  if (
+    !(await writeClosedCommandTranscript(
+      context.artifactDirectory,
+      options.output.mode,
+      terminal.status,
+      result
+    ))
+  ) {
+    return unavailable("command-transcript-unavailable");
+  }
+  return settleCommandResult(context, result, terminal.result, afterCommand);
+}
+
+/** Writes the running marker only where output policy and artifact capability both allow it. */
+async function writeRunningCommandTranscript(
+  artifactDirectory: string | null,
+  outputMode: ResolvedCommandCheckOptions["output"]["mode"]
+): Promise<boolean> {
+  if (outputMode === "discard") return true;
+  return (
+    artifactDirectory !== null && writeCommandTranscript(artifactDirectory, runningTranscript())
+  );
+}
+
+/** Replaces the running marker with final child material before any caller-owned callback observes it. */
+async function writeClosedCommandTranscript(
+  artifactDirectory: string | null,
+  outputMode: ResolvedCommandCheckOptions["output"]["mode"],
+  status: "passed" | "failed" | "unavailable",
+  result: CommandProcessResult
+): Promise<boolean> {
+  if (outputMode === "discard") return true;
+  return (
+    artifactDirectory !== null &&
+    writeCommandTranscript(
+      artifactDirectory,
+      closedTranscript({ status, stderr: result.stderr, stdout: result.stdout })
+    )
+  );
+}
+
+/** Lets the caller settle only complete numeric exits; all other terminal causes remain Product-owned. */
+function settleCommandResult(
+  context: CheckExecutionContext<ResolvedCommandCheckOptions>,
+  result: CommandProcessResult,
+  defaultResult: CheckResult<CommandCheckFinalData>,
+  afterCommand: AfterCommand | undefined
+): CheckResult | Promise<CheckResult> {
+  if (afterCommand === undefined || !isCompleteCommandResult(result)) return defaultResult;
+  return afterCommand.execute(
+    Object.freeze({
+      ...context,
+      command: Object.freeze({
+        exitCode: result.status,
+        stderr: result.stderr,
+        stdout: result.stdout
+      })
+    })
+  );
+}
+
+async function resolveExecutionEnvironment(
+  context: CheckExecutionContext<ResolvedCommandCheckOptions>,
+  resolver: CommandEnvironmentResolver | undefined
+): Promise<ResolvedCommandCheckOptions["environment"] | undefined> {
+  if (resolver === undefined) return context.options.environment;
+  try {
+    const environment = await resolver(
+      Object.freeze({
+        dependencies: context.dependencies,
+        options: context.options,
+        project: context.project,
+        signal: context.signal
+      })
+    );
+    return resolveCommandCheckEnvironment(environment);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveWorkingDirectory(workingDirectory: string | null, projectRoot: string): string {
+  if (workingDirectory === null) return projectRoot;
+  if (isAbsolute(workingDirectory)) return workingDirectory;
+  return resolve(projectRoot, workingDirectory);
+}
+
+function executionEnvironment(
+  environment: ResolvedCommandCheckOptions["environment"]
+): NodeJS.ProcessEnv {
+  if (environment.mode === "exact") return { ...environment.variables };
+  const inherited: NodeJS.ProcessEnv = { ...process.env };
+  for (const [name, value] of Object.entries(environment.overrides)) {
+    if (value === null) delete inherited[name];
+    else inherited[name] = value;
+  }
+  return inherited;
+}
+
+function isCompleteCommandResult(result: CommandProcessResult): result is CommandProcessResult & {
+  readonly status: number;
+} {
+  return (
+    typeof result.status === "number" &&
+    result.isCanceled !== true &&
+    result.isMaxBuffer !== true &&
+    result.timedOut !== true &&
+    result.signal === null
+  );
+}
+
+function terminalResult(result: CommandProcessResult): Readonly<{
+  readonly result: CheckResult<CommandCheckFinalData>;
+  readonly status: "passed" | "failed" | "unavailable";
+}> {
+  if (typeof result.status === "number" && result.status !== 0) {
+    return completedTerminal("failed", result.status);
+  }
+  if (result.isCanceled === true) return unavailableTerminal("command-terminated-by-signal");
+  if (result.timedOut === true) return unavailableTerminal("command-timeout");
+  if (result.isMaxBuffer === true) return unavailableTerminal("command-output-limit-exceeded");
+  if (result.signal !== null) return unavailableTerminal("command-terminated-by-signal");
+  if (result.status === 0) {
+    return completedTerminal("passed", 0);
+  }
+  return unavailableTerminal("command-start-failed");
+}
+
+function completedTerminal(
+  status: "passed" | "failed",
+  exitCode: number
+): Readonly<{
+  readonly result: CheckResult<CommandCheckFinalData>;
+  readonly status: "passed" | "failed";
+}> {
+  const result: CheckResult<CommandCheckFinalData> =
+    status === "passed"
+      ? Object.freeze({ status: "passed" as const, data: Object.freeze({ exitCode }) })
+      : Object.freeze({ status: "failed" as const, data: Object.freeze({ exitCode }) });
+  return Object.freeze({ result, status });
+}
+
+function unavailableTerminal(code: CommandCheckUnavailableReasonCode): Readonly<{
+  readonly result: CheckResult<CommandCheckFinalData>;
+  readonly status: "unavailable";
+}> {
+  return Object.freeze({ result: unavailable(code), status: "unavailable" });
+}
+
+function unavailable(code: CommandCheckUnavailableReasonCode): CheckResult<CommandCheckFinalData> {
+  return Object.freeze({ status: "unavailable", reason: Object.freeze({ code }) });
+}