@zxyycom/vibe-check 0.0.1

package/src/project-run/check-execution/preflight.ts

@@ -0,0 +1,321 @@
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { snapshotJsonObject } from "../../check/options-snapshot.ts";
+import {
+  diagnosticTags,
+  summarizeDiagnosticValue,
+  type DiagnosticLogger
+} from "../diagnostic-logging/logger.ts";
+import { parseCheckPreflightResult, type ParsedCheckPreflightResult } from "./preflight-result.ts";
+
+const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
+const INERT_SIGNAL = new AbortController().signal;
+
+export type PreparedCheck = Omit<NormalizedCheck, "options" | "preflight"> &
+  Readonly<{ readonly options: object; readonly preflightMessages: readonly CheckMessage[] }>;
+
+type BlockedCheck = Pick<NormalizedCheck, "definition" | "visibility"> &
+  Readonly<{ readonly preflightMessages: readonly CheckMessage[] }>;
+
+export type ReadyCheckPreflightResolution = Readonly<{
+  readonly kind: "ready";
+  readonly check: PreparedCheck;
+}>;
+
+export type BlockedCheckPreflightResolution = Readonly<{
+  readonly kind: "blocked";
+  readonly check: BlockedCheck;
+  readonly outcome: CheckOutcome;
+}>;
+
+export type CheckPreflightResolution =
+  | ReadyCheckPreflightResolution
+  | BlockedCheckPreflightResolution;
+
+type PreflightResolutionResult =
+  | "skipped"
+  | "prepared"
+  | "continued"
+  | "blocked"
+  | "cancelled-before-callback"
+  | "cancelled-after-callback"
+  | "cancelled-after-throw"
+  | "threw"
+  | "malformed";
+
+type PrepareCheckInput = Readonly<{
+  readonly check: NormalizedCheck;
+  readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly signal: AbortSignal | undefined;
+}>;
+
+type PreflightInvocation =
+  | Readonly<{ readonly kind: "returned"; readonly output: unknown }>
+  | Readonly<{ readonly kind: "threw"; readonly error: unknown }>;
+
+/** Completes the sequential invocation-wide barrier before any Check enters the Task graph. */
+export async function prepareChecks(
+  input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly signal: AbortSignal | undefined;
+  }>
+): Promise<readonly CheckPreflightResolution[]> {
+  const resolutions: CheckPreflightResolution[] = [];
+  for (const check of input.checks) {
+    resolutions.push(
+      await prepareCheck({
+        check,
+        diagnosticLogger: input.diagnosticLogger,
+        signal: input.signal
+      })
+    );
+  }
+  return Object.freeze(resolutions);
+}
+
+async function prepareCheck(input: PrepareCheckInput): Promise<CheckPreflightResolution> {
+  if (input.signal?.aborted) {
+    return observeBlockedPreflight({
+      check: input.check,
+      diagnosticLogger: input.diagnosticLogger,
+      details: {},
+      result: "cancelled-before-callback",
+      reasonCode: "execution-cancelled"
+    });
+  }
+  if (input.check.preflight === undefined) {
+    return resolveAuthoredOptions(input);
+  }
+  return resolvePreflightInvocation(input, await invokePreflight(input.check, input.signal));
+}
+
+function resolveAuthoredOptions(input: PrepareCheckInput): CheckPreflightResolution {
+  const resolution = readyResolution({
+    authoredCheck: input.check,
+    messages: EMPTY_MESSAGES,
+    preparedOptions: input.check.options
+  });
+  observeReadyOrMalformedResolution(
+    input.diagnosticLogger,
+    input.check.definition.checkId,
+    resolution,
+    "skipped",
+    { source: "authored" }
+  );
+  return resolution;
+}
+
+function resolvePreflightInvocation(
+  input: PrepareCheckInput,
+  invocation: PreflightInvocation
+): CheckPreflightResolution {
+  if (invocation.kind === "threw") {
+    return observeBlockedPreflight({
+      check: input.check,
+      diagnosticLogger: input.diagnosticLogger,
+      details: { error: invocation.error },
+      result: input.signal?.aborted ? "cancelled-after-throw" : "threw",
+      reasonCode: input.signal?.aborted ? "execution-cancelled" : "preflight-threw"
+    });
+  }
+  return resolveReturnedPreflight(input, invocation.output);
+}
+
+function resolveReturnedPreflight(
+  input: PrepareCheckInput,
+  preflightOutput: unknown
+): CheckPreflightResolution {
+  if (input.signal?.aborted) {
+    return observeBlockedPreflight({
+      check: input.check,
+      diagnosticLogger: input.diagnosticLogger,
+      details: { raw: preflightOutput },
+      result: "cancelled-after-callback",
+      reasonCode: "execution-cancelled"
+    });
+  }
+  const preflightResult = parseCheckPreflightResult(preflightOutput);
+  if (preflightResult === undefined) {
+    return observeBlockedPreflight({
+      check: input.check,
+      diagnosticLogger: input.diagnosticLogger,
+      details: { raw: preflightOutput },
+      result: "malformed",
+      reasonCode: "invalid-preflight-result"
+    });
+  }
+  if (preflightResult.status === "failure" && preflightResult.action === "block") {
+    return resolveBlockedPreflightResult(input, preflightResult);
+  }
+  return resolveReadyPreflightResult(input, preflightOutput, preflightResult);
+}
+
+function resolveBlockedPreflightResult(
+  input: PrepareCheckInput,
+  preflightResult: Extract<ParsedCheckPreflightResult, { readonly action: "block" }>
+): CheckPreflightResolution {
+  const resolution = blockedResolution({
+    check: input.check,
+    messages: preflightResult.messages,
+    reasonCode: preflightResult.reason.code
+  });
+  observePreflightResolution(
+    input.diagnosticLogger,
+    input.check.definition.checkId,
+    resolution,
+    "blocked",
+    {
+      ...(preflightResult.messages.length === 0 ? {} : { messages: preflightResult.messages }),
+      reason: preflightResult.reason
+    }
+  );
+  return resolution;
+}
+
+function resolveReadyPreflightResult(
+  input: PrepareCheckInput,
+  preflightOutput: unknown,
+  preflightResult: Exclude<ParsedCheckPreflightResult, { readonly action: "block" }>
+): CheckPreflightResolution {
+  const checkId = input.check.definition.checkId;
+  const result = preflightResult.status === "success" ? "prepared" : "continued";
+  const resolution = readyResolution({
+    authoredCheck: input.check,
+    messages: preflightResult.messages,
+    preparedOptions:
+      preflightResult.status === "success"
+        ? preflightResult.preparedOptions
+        : preflightResult.fallback
+  });
+  observeReadyOrMalformedResolution(input.diagnosticLogger, checkId, resolution, result, {
+    messages: preflightResult.messages,
+    ...(preflightResult.status === "success" ? {} : { reason: preflightResult.reason }),
+    raw: preflightOutput
+  });
+  return resolution;
+}
+
+async function invokePreflight(
+  check: NormalizedCheck,
+  signal: AbortSignal | undefined
+): Promise<PreflightInvocation> {
+  try {
+    return Object.freeze({
+      kind: "returned",
+      output: await check.preflight!(check.options, signal ?? INERT_SIGNAL)
+    });
+  } catch (error) {
+    return Object.freeze({ kind: "threw", error });
+  }
+}
+
+function observeBlockedPreflight(
+  input: Readonly<{
+    readonly check: NormalizedCheck;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly result: PreflightResolutionResult;
+    readonly reasonCode: string;
+  }>
+): BlockedCheckPreflightResolution {
+  const resolution = blockedResolution({
+    check: input.check,
+    messages: EMPTY_MESSAGES,
+    reasonCode: input.reasonCode
+  });
+  observePreflightResolution(
+    input.diagnosticLogger,
+    input.check.definition.checkId,
+    resolution,
+    input.result,
+    input.details
+  );
+  return resolution;
+}
+
+function observeReadyOrMalformedResolution(
+  diagnosticLogger: DiagnosticLogger | undefined,
+  checkId: string,
+  resolution: CheckPreflightResolution,
+  result: "skipped" | "prepared" | "continued",
+  details: Readonly<Record<string, unknown>>
+): void {
+  if (resolution.kind === "blocked") {
+    observePreflightResolution(diagnosticLogger, checkId, resolution, "malformed", {
+      raw: "raw" in details ? details.raw : summarizeDiagnosticValue(details)
+    });
+    return;
+  }
+  const messages = "messages" in details ? details.messages : EMPTY_MESSAGES;
+  observePreflightResolution(diagnosticLogger, checkId, resolution, result, {
+    ...(Array.isArray(messages) && messages.length > 0 ? { messages } : {}),
+    options: summarizeDiagnosticValue(resolution.check.options),
+    ...("reason" in details ? { reason: details.reason } : {}),
+    ...("source" in details ? { source: details.source } : {})
+  });
+}
+
+function observePreflightResolution(
+  diagnosticLogger: DiagnosticLogger | undefined,
+  checkId: string,
+  resolution: CheckPreflightResolution,
+  result: PreflightResolutionResult,
+  details: Readonly<Record<string, unknown>>
+): void {
+  diagnosticLogger?.observe({
+    event: "preflight.resolved",
+    tags: diagnosticTags(`CHECK:${checkId}`, "PREFLIGHT", result.toUpperCase()),
+    details: {
+      ...details,
+      ...(resolution.kind === "blocked" ? { outcome: resolution.outcome } : {})
+    }
+  });
+}
+
+function readyResolution(
+  input: Readonly<{
+    readonly authoredCheck: NormalizedCheck;
+    readonly messages: readonly CheckMessage[];
+    readonly preparedOptions: unknown;
+  }>
+): CheckPreflightResolution {
+  const preparedOptions = snapshotJsonObject(input.preparedOptions);
+  if (preparedOptions === undefined) {
+    return blockedResolution({
+      check: input.authoredCheck,
+      messages: EMPTY_MESSAGES,
+      reasonCode: "invalid-preflight-result"
+    });
+  }
+  const { preflight: _preflight, ...check } = input.authoredCheck;
+  return Object.freeze({
+    kind: "ready",
+    check: Object.freeze({
+      ...check,
+      options: preparedOptions,
+      preflightMessages: input.messages
+    })
+  });
+}
+
+function blockedResolution(
+  input: Readonly<{
+    readonly check: NormalizedCheck;
+    readonly messages: readonly CheckMessage[];
+    readonly reasonCode: string;
+  }>
+): BlockedCheckPreflightResolution {
+  return Object.freeze({
+    kind: "blocked",
+    check: Object.freeze({
+      definition: input.check.definition,
+      preflightMessages: input.messages,
+      visibility: input.check.visibility
+    }),
+    outcome: Object.freeze({
+      status: "unavailable",
+      reason: Object.freeze({ code: input.reasonCode })
+    })
+  });
+}

package/src/project-run/check-execution/resolved-checks.ts

@@ -0,0 +1,285 @@
+import type {
+  CheckMessage,
+  CheckOutcome,
+  CheckProjectContext,
+  CheckVisibility
+} from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { createCoreCheckSession, type CoreCheckSession } from "../../check-settlement/session.ts";
+import {
+  diagnosticTags,
+  summarizeDiagnosticValue,
+  type DiagnosticLogger
+} from "../diagnostic-logging/logger.ts";
+import { prepareTaskGraph } from "../task-scheduler/graph.ts";
+import { runTaskGraph } from "../task-scheduler/scheduler.ts";
+import { executeCheckCallback } from "./callback.ts";
+import { createCheckDependencies } from "./dependencies.ts";
+import {
+  CheckExecutionInvariantFailure,
+  recordSettledCheck,
+  settleCallback,
+  type CheckExecutionSettlementState,
+  type CheckIdentity,
+  type SettledCheckFacts
+} from "./execution-settlement.ts";
+import {
+  checkIdentity,
+  closeCancelledExecution,
+  closeResolvedChecks,
+  trustedFailure
+} from "./execution-finalization.ts";
+import { planStaticCheckGraph } from "./plan.ts";
+import {
+  prepareChecks,
+  type CheckPreflightResolution,
+  type PreparedCheck,
+  type ReadyCheckPreflightResolution
+} from "./preflight.ts";
+
+const INERT_SIGNAL = new AbortController().signal;
+const SYSTEM_MONOTONIC_CLOCK: CheckExecutionClock = Object.freeze({ now: () => performance.now() });
+
+/** Private Run handoff for Check lifecycle presentation and accounting. */
+export type CheckExecutionLifecycle = Readonly<{
+  readonly started: (fact: CheckStartedFact) => void;
+  readonly settled: (fact: CheckSettledFact) => void;
+}>;
+
+/** Package-private monotonic clock seam for execution accounting. */
+export type CheckExecutionClock = Readonly<{ now(): number }>;
+
+export type CheckStartedFact = Readonly<{ checkId: string; displayName: string }>;
+
+export type CheckSettledFact = CheckStartedFact &
+  Readonly<{
+    durationMs: number | null;
+    messages: readonly CheckMessage[];
+    outcome: CheckOutcome;
+    visibility: CheckVisibility;
+  }>;
+
+type ResolvedCheckExecutionFacts = Readonly<{
+  readonly checkDurations: readonly import("../result.ts").CheckDuration[];
+  readonly checkMessages: readonly import("../result.ts").CheckRunMessage[];
+  readonly snapshot: import("../../check-settlement/facts.ts").CoreSnapshot;
+}>;
+
+export type ResolvedCheckExecution =
+  | (Readonly<{ readonly kind: "completed" }> & ResolvedCheckExecutionFacts)
+  | (Readonly<{ readonly kind: "cancelled" }> & ResolvedCheckExecutionFacts);
+
+export interface CheckExecutionState extends CheckExecutionSettlementState {
+  readonly session: CoreCheckSession;
+}
+
+interface ExecuteCheckInput extends CheckExecutionState {
+  readonly preflight: ReadyCheckPreflightResolution;
+  readonly clock: CheckExecutionClock;
+  readonly project: CheckProjectContext;
+  readonly signal: AbortSignal;
+}
+
+type PreparedResolvedCheckExecution = Readonly<{
+  readonly blockedCheckIds: ReadonlySet<string>;
+  readonly readyChecks: readonly PreparedCheck[];
+  readonly readyPreflights: readonly ReadyCheckPreflightResolution[];
+  readonly state: CheckExecutionState;
+}>;
+
+/**
+ * Runs the already normalized executable Check collection through one generic
+ * Task per Check. Graph validation happens before Core scopes or callbacks.
+ */
+export async function executeResolvedChecks(
+  input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly maxParallel: number;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal | undefined;
+    readonly clock?: CheckExecutionClock;
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly lifecycle?: CheckExecutionLifecycle;
+  }>
+): Promise<ResolvedCheckExecution> {
+  const prepared = await prepareResolvedCheckExecution(input);
+  // The barrier is execution-phase work. A signal received while it runs must close this
+  // phase as cancelled even when every preflight already blocked and the scheduler graph is empty.
+  if (input.signal?.aborted) {
+    return closeCancelledExecution({
+      normalizedChecks: input.checks,
+      preparedChecks: prepared.readyChecks,
+      state: prepared.state
+    });
+  }
+  const readyPreflightByCheckId = new Map(
+    prepared.readyPreflights.map((preflight) => [preflight.check.definition.checkId, preflight])
+  );
+  const graph = planStaticCheckGraph(prepared.readyChecks, {
+    alreadySettledCheckIds: prepared.blockedCheckIds
+  });
+  let graphRun: Awaited<ReturnType<typeof runTaskGraph<void>>>;
+  try {
+    graphRun = await runTaskGraph({
+      graph,
+      maxParallel: input.maxParallel,
+      diagnosticLogger: input.diagnosticLogger,
+      signal: input.signal,
+      execute: (task, context) => {
+        const preflight = readyPreflightByCheckId.get(task.id);
+        if (preflight === undefined) {
+          throw new CheckExecutionInvariantFailure("Task graph has no prepared Check");
+        }
+        return executeCheck({
+          ...prepared.state,
+          preflight,
+          clock: input.clock ?? SYSTEM_MONOTONIC_CLOCK,
+          project: input.project,
+          signal: context.signal ?? INERT_SIGNAL
+        });
+      }
+    });
+  } catch (error) {
+    throw trustedFailure(error);
+  }
+
+  return closeResolvedChecks({
+    allChecks: input.checks,
+    graphRun,
+    readyChecks: prepared.readyChecks,
+    state: prepared.state
+  });
+}
+
+async function prepareResolvedCheckExecution(
+  input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly lifecycle?: CheckExecutionLifecycle;
+    readonly maxParallel: number;
+    readonly signal: AbortSignal | undefined;
+  }>
+): Promise<PreparedResolvedCheckExecution> {
+  prepareTaskGraph(planStaticCheckGraph(input.checks), input.maxParallel);
+  const preflights = await prepareChecks({
+    checks: input.checks,
+    diagnosticLogger: input.diagnosticLogger,
+    signal: input.signal
+  });
+  const state = createExecutionState({
+    checks: input.checks,
+    diagnosticLogger: input.diagnosticLogger,
+    lifecycle: input.lifecycle
+  });
+  const partition = settlePreflightResolutions(state, preflights);
+  return Object.freeze({ ...partition, state });
+}
+
+function createExecutionState(
+  input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly lifecycle: CheckExecutionLifecycle | undefined;
+  }>
+): CheckExecutionState {
+  return {
+    diagnosticLogger: input.diagnosticLogger,
+    settledFactsByCheckId: new Map<string, SettledCheckFacts>(),
+    lifecycle: input.lifecycle,
+    session: createCoreCheckSession(
+      input.checks.map(({ definition }) => Object.freeze({ definition }))
+    )
+  };
+}
+
+function settlePreflightResolutions(
+  state: CheckExecutionState,
+  resolutions: readonly CheckPreflightResolution[]
+): Omit<PreparedResolvedCheckExecution, "state"> {
+  const readyPreflights: ReadyCheckPreflightResolution[] = [];
+  const blockedCheckIds = new Set<string>();
+  for (const resolution of resolutions) {
+    if (resolution.kind === "ready") {
+      readyPreflights.push(resolution);
+      continue;
+    }
+    blockedCheckIds.add(resolution.check.definition.checkId);
+    settleBlockedPreflight(state, resolution);
+  }
+  return Object.freeze({
+    blockedCheckIds,
+    readyChecks: Object.freeze(readyPreflights.map((preflight) => preflight.check)),
+    readyPreflights: Object.freeze(readyPreflights)
+  });
+}
+
+function settleBlockedPreflight(
+  state: CheckExecutionState,
+  preflight: Extract<CheckPreflightResolution, { readonly kind: "blocked" }>
+): void {
+  const scope = state.session.openCheckScope(preflight.check.definition.checkId);
+  const outcome = scope.settleProduct(preflight.outcome);
+  recordSettledCheck({
+    check: checkIdentity(preflight.check),
+    durationMs: null,
+    messages: preflight.check.preflightMessages,
+    outcome,
+    phase: "preflight",
+    state
+  });
+}
+
+async function executeCheck(input: ExecuteCheckInput): Promise<void> {
+  const check = input.preflight.check;
+  const checkId = check.definition.checkId;
+  const scope = input.session.openCheckScope(checkId);
+  const identity = checkIdentity(check);
+  input.diagnosticLogger?.observe({
+    event: "check.started",
+    tags: diagnosticTags(`CHECK:${checkId}`, "EXECUTION", "STARTED"),
+    details: {
+      dependencies: check.dependsOn,
+      displayName: check.definition.displayName,
+      options: summarizeDiagnosticValue(check.options)
+    }
+  });
+  emitStarted(input.lifecycle, identity);
+  const startedAt = input.clock.now();
+  const callback = await executeCheckCallback({
+    check,
+    dependencies: createCheckDependencies({
+      checkId,
+      diagnosticLogger: input.diagnosticLogger,
+      directDependencyIds: check.dependsOn,
+      session: input.session
+    }),
+    diagnosticLogger: input.diagnosticLogger,
+    project: input.project,
+    scope,
+    signal: input.signal
+  });
+  const settled = settleCallback({
+    callback,
+    checkId,
+    diagnosticLogger: input.diagnosticLogger,
+    preflightMessages: check.preflightMessages,
+    scope
+  });
+  recordSettledCheck({
+    check: identity,
+    durationMs: durationSince(startedAt, input.clock),
+    messages: settled.messages,
+    outcome: settled.outcome,
+    phase: "execution",
+    state: input
+  });
+}
+
+function emitStarted(lifecycle: CheckExecutionLifecycle | undefined, check: CheckIdentity): void {
+  lifecycle?.started(Object.freeze({ checkId: check.checkId, displayName: check.displayName }));
+}
+
+function durationSince(startedAt: number, clock: CheckExecutionClock): number {
+  const elapsed = clock.now() - startedAt;
+  return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : 0;
+}

package/src/project-run/check-execution/terminal-result.ts

@@ -0,0 +1,74 @@
+import type { CheckMessage } from "../../check/check.ts";
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { parseCheckMessages } from "./messages.ts";
+
+/**
+ * A terminal callback result split into the Core-owned four-state result and
+ * detached presentation-only messages. The caller must still pass `result` to
+ * Core; this adapter never validates outcome data or reasons.
+ */
+export interface ParsedCheckTerminalResult {
+  readonly messages: readonly CheckMessage[];
+  readonly result: StrippedTerminalResult;
+}
+
+type StrippedTerminalResult =
+  | Readonly<{ readonly status: "passed" | "failed"; readonly data: unknown }>
+  | Readonly<{ readonly status: "not-applicable"; readonly reason?: unknown }>
+  | Readonly<{ readonly status: "unavailable"; readonly reason: unknown }>;
+
+/**
+ * Safely removes an optional terminal-message attachment from an otherwise
+ * closed author result. Any malformed attachment rejects the whole value so a
+ * valid prefix can never escape into lifecycle or Run result state.
+ */
+export function parseCheckTerminalResult(value: unknown): ParsedCheckTerminalResult | undefined {
+  const terminal = snapshotClosedRecord(value);
+  if (terminal === undefined || typeof terminal.status !== "string") return undefined;
+
+  const result = strippedTerminalResult(terminal);
+  if (result === undefined) return undefined;
+  const messages = parseCheckMessages(terminal.messages);
+  return messages === undefined ? undefined : Object.freeze({ messages, result });
+}
+
+function strippedTerminalResult(
+  terminal: Readonly<Record<string, unknown>>
+): StrippedTerminalResult | undefined {
+  switch (terminal.status) {
+    case "passed":
+    case "failed":
+      return hasRequiredAndOptionalRecordKeys(terminal, {
+        required: ["status", "data"],
+        optional: ["messages"]
+      })
+        ? Object.freeze({ status: terminal.status, data: terminal.data })
+        : undefined;
+    case "not-applicable":
+      if (
+        !hasRequiredAndOptionalRecordKeys(terminal, {
+          required: ["status"],
+          optional: ["reason", "messages"]
+        })
+      ) {
+        return undefined;
+      }
+      return Object.freeze(
+        Object.hasOwn(terminal, "reason")
+          ? { status: "not-applicable", reason: terminal.reason }
+          : { status: "not-applicable" }
+      );
+    case "unavailable":
+      return hasRequiredAndOptionalRecordKeys(terminal, {
+        required: ["status", "reason"],
+        optional: ["messages"]
+      })
+        ? Object.freeze({ status: "unavailable", reason: terminal.reason })
+        : undefined;
+    default:
+      return undefined;
+  }
+}