@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,70 @@
+import type { CheckDependencies, CheckOutcome, DependencyReadResult } from "../../check/check.ts";
+import type { CoreCheckSession } from "../../check-settlement/session.ts";
+import { diagnosticTags, type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+
+export function createCheckDependencies(
+  input: Readonly<{
+    readonly checkId: string;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly directDependencyIds: readonly string[];
+    readonly session: CoreCheckSession;
+  }>
+): CheckDependencies {
+  return Object.freeze({
+    get: (dependencyId: string): DependencyReadResult => {
+      const result = readDependency(input.session, input.directDependencyIds, dependencyId);
+      input.diagnosticLogger?.observe({
+        event: "dependency.read",
+        tags: diagnosticTags(`CHECK:${input.checkId}`, "EXECUTION", "DEPENDENCY-READ"),
+        details: dependencyReadDetails(dependencyId, result)
+      });
+      return result;
+    }
+  });
+}
+
+function dependencyReadDetails(
+  requestedCheckId: unknown,
+  result: DependencyReadResult
+): Readonly<Record<string, unknown>> {
+  if (!result.ok) {
+    return Object.freeze({ error: result.error, ok: false, requestedCheckId });
+  }
+  return Object.freeze({
+    hasData: true,
+    ok: true,
+    producer: result.checkId,
+    status: result.status
+  });
+}
+
+function readDependency(
+  session: CoreCheckSession,
+  directDependencyIds: readonly string[],
+  checkId: string
+): DependencyReadResult {
+  if (typeof checkId !== "string" || !directDependencyIds.includes(checkId)) {
+    return dependencyNotDeclared(checkId);
+  }
+  return dependencyReadResult(checkId, session.readSettledCheckOutcome(checkId));
+}
+
+function dependencyReadResult(checkId: string, outcome: CheckOutcome): DependencyReadResult {
+  if (outcome.status === "passed" || outcome.status === "failed") {
+    return Object.freeze({ ok: true, checkId, status: outcome.status, data: outcome.data });
+  }
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ code: "upstream-data-unavailable", checkId, status: outcome.status })
+  });
+}
+
+function dependencyNotDeclared(checkId: unknown): DependencyReadResult {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({
+      code: "dependency-not-declared",
+      checkId: typeof checkId === "string" ? checkId : ""
+    })
+  });
+}

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

@@ -0,0 +1,177 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import type { SettledTask } from "../task-scheduler/scheduler.ts";
+import type { CheckDuration, CheckRunMessage } from "../result.ts";
+import {
+  CheckExecutionInvariantFailure,
+  recordSettledCheck,
+  type CheckIdentity,
+  type SettledCheckFacts
+} from "./execution-settlement.ts";
+import type { PreparedCheck } from "./preflight.ts";
+import type { CheckExecutionState, ResolvedCheckExecution } from "./resolved-checks.ts";
+
+const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
+
+/** Closes the task graph, lifecycle facts, and canonical Check summaries as one Run boundary. */
+export function closeResolvedChecks(
+  input: Readonly<{
+    readonly allChecks: readonly NormalizedCheck[];
+    readonly graphRun: Awaited<
+      ReturnType<typeof import("../task-scheduler/scheduler.ts").runTaskGraph<void>>
+    >;
+    readonly readyChecks: readonly PreparedCheck[];
+    readonly state: CheckExecutionState;
+  }>
+): ResolvedCheckExecution {
+  try {
+    assertNoTaskEngineFailures(input.graphRun.settlements);
+    if (input.graphRun.cancelled) {
+      return closeCancelledExecution({
+        normalizedChecks: input.allChecks,
+        preparedChecks: input.readyChecks,
+        state: input.state
+      });
+    }
+    assertEveryCheckClosed(input.readyChecks, input.graphRun.settlements);
+    return resolvedExecution("completed", input.state.session.freeze(), input.state);
+  } catch (error) {
+    throw trustedFailure(error);
+  }
+}
+
+export function closeCancelledExecution(
+  input: Readonly<{
+    readonly normalizedChecks: readonly NormalizedCheck[];
+    readonly preparedChecks: readonly PreparedCheck[];
+    readonly state: CheckExecutionState;
+  }>
+): ResolvedCheckExecution {
+  input.state.session.closeUnresolvedAsCancelled();
+  const snapshot = input.state.session.freeze();
+  settleUnstartedCancelledChecks({ ...input, snapshot });
+  return resolvedExecution("cancelled", snapshot, input.state);
+}
+
+export function checkIdentity(
+  check: Pick<NormalizedCheck, "definition" | "visibility">
+): CheckIdentity {
+  return Object.freeze({
+    checkId: check.definition.checkId,
+    displayName: check.definition.displayName,
+    visibility: check.visibility
+  });
+}
+
+export function trustedFailure(error: unknown): CheckExecutionInvariantFailure {
+  return error instanceof CheckExecutionInvariantFailure
+    ? error
+    : new CheckExecutionInvariantFailure(
+        "Check execution adapter escaped its contained failure boundary"
+      );
+}
+
+function resolvedExecution(
+  kind: ResolvedCheckExecution["kind"],
+  snapshot: CoreSnapshot,
+  state: CheckExecutionState
+): ResolvedCheckExecution {
+  return Object.freeze({
+    kind,
+    ...checkRunSummaries(snapshot, state.settledFactsByCheckId),
+    snapshot
+  });
+}
+
+function settleUnstartedCancelledChecks(
+  input: Readonly<{
+    readonly normalizedChecks: readonly NormalizedCheck[];
+    readonly preparedChecks: readonly PreparedCheck[];
+    readonly snapshot: CoreSnapshot;
+    readonly state: CheckExecutionState;
+  }>
+): void {
+  const normalizedByCheckId = new Map(
+    input.normalizedChecks.map((check) => [check.definition.checkId, check])
+  );
+  const preparedByCheckId = new Map(
+    input.preparedChecks.map((check) => [check.definition.checkId, check])
+  );
+  for (const check of input.snapshot.checks) {
+    if (input.state.settledFactsByCheckId.has(check.checkId)) continue;
+    const normalized = normalizedByCheckId.get(check.checkId);
+    if (normalized === undefined) {
+      throw new CheckExecutionInvariantFailure(
+        "Cancelled Check does not identify a normalized Check"
+      );
+    }
+    recordSettledCheck({
+      check: checkIdentity(normalized),
+      durationMs: null,
+      messages: preparedByCheckId.get(check.checkId)?.preflightMessages ?? EMPTY_MESSAGES,
+      outcome: check.outcome,
+      phase: "execution",
+      state: input.state
+    });
+  }
+}
+
+function checkRunSummaries(
+  snapshot: CoreSnapshot,
+  settledFactsByCheckId: ReadonlyMap<string, SettledCheckFacts>
+): Readonly<{
+  readonly checkDurations: readonly CheckDuration[];
+  readonly checkMessages: readonly CheckRunMessage[];
+}> {
+  if (snapshot.checks.length !== settledFactsByCheckId.size) {
+    throw new CheckExecutionInvariantFailure("Check settled facts do not close every Check");
+  }
+  const checkDurations: CheckDuration[] = [];
+  const messages: CheckRunMessage[] = [];
+  for (const check of snapshot.checks) {
+    const settledFacts = settledFactsByCheckId.get(check.checkId);
+    if (settledFacts === undefined) {
+      throw new CheckExecutionInvariantFailure("Check settled facts are missing a Check");
+    }
+    checkDurations.push(
+      Object.freeze({ checkId: check.checkId, durationMs: settledFacts.durationMs })
+    );
+    messages.push(
+      ...settledFacts.messages.map((message) =>
+        Object.freeze({ checkId: check.checkId, ...message })
+      )
+    );
+  }
+  return Object.freeze({
+    checkDurations: Object.freeze(checkDurations),
+    checkMessages: messages.length === 0 ? Object.freeze([]) : Object.freeze(messages)
+  });
+}
+
+function assertNoTaskEngineFailures(settlements: readonly SettledTask<void>[]): void {
+  for (const settled of settlements) {
+    if (settled.settlement.kind === "failed") {
+      throw new CheckExecutionInvariantFailure(
+        "Task engine received an unexpected execution failure"
+      );
+    }
+    if (settled.settlement.kind === "blocked") {
+      throw new CheckExecutionInvariantFailure("Task engine blocked a Product Check");
+    }
+  }
+}
+
+function assertEveryCheckClosed(
+  checks: readonly NormalizedCheck[],
+  settlements: readonly SettledTask<void>[]
+): void {
+  if (settlements.some((settled) => settled.settlement.kind === "cancelled-before-start")) {
+    throw new CheckExecutionInvariantFailure("Non-cancelled Task graph left a Check unstarted");
+  }
+  if (checks.length !== settlements.length) {
+    throw new CheckExecutionInvariantFailure(
+      "Task graph does not have one Task per executable Check"
+    );
+  }
+}

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

@@ -0,0 +1,147 @@
+import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CoreCheckSession } from "../../check-settlement/session.ts";
+import {
+  diagnosticTags,
+  summarizeDiagnosticValue,
+  type DiagnosticLogger
+} from "../diagnostic-logging/logger.ts";
+import { parseCheckTerminalResult } from "./terminal-result.ts";
+import type { CheckExecutionLifecycle } from "./resolved-checks.ts";
+import type { executeCheckCallback } from "./callback.ts";
+
+export type CheckIdentity = Readonly<{
+  readonly checkId: string;
+  readonly displayName: string;
+  readonly visibility: CheckVisibility;
+}>;
+
+export interface SettledCheckFacts {
+  readonly durationMs: number | null;
+  readonly messages: readonly CheckMessage[];
+}
+
+export type CheckExecutionSettlementState = Readonly<{
+  readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly lifecycle: CheckExecutionLifecycle | undefined;
+  readonly settledFactsByCheckId: Map<string, SettledCheckFacts>;
+}>;
+
+export class CheckExecutionInvariantFailure extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "CheckExecutionInvariantFailure";
+  }
+}
+
+export function settleCallback(
+  input: Readonly<{
+    readonly callback: Awaited<ReturnType<typeof executeCheckCallback>>;
+    readonly checkId: string;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly preflightMessages: readonly CheckMessage[];
+    readonly scope: ReturnType<CoreCheckSession["openCheckScope"]>;
+  }>
+): Readonly<{ readonly messages: readonly CheckMessage[]; readonly outcome: CheckOutcome }> {
+  const executionTags = diagnosticTags(`CHECK:${input.checkId}`, "EXECUTION");
+  const { callback } = input;
+  if (callback.source === "product") {
+    const outcome = input.scope.settleProduct(callback.result);
+    return Object.freeze({ messages: input.preflightMessages, outcome });
+  }
+  const terminal = parseCheckTerminalResult(callback.result);
+  if (terminal === undefined) {
+    input.diagnosticLogger?.observe({
+      event: "callback.malformed",
+      tags: diagnosticTags(...executionTags, "MALFORMED"),
+      details: { result: callback.result }
+    });
+  }
+  const settlement = input.scope.settle(terminal?.result ?? callback.result);
+  if (terminal !== undefined && !settlement.authorResultAccepted) {
+    input.diagnosticLogger?.observe({
+      event: "check.contained",
+      tags: diagnosticTags(...executionTags, "CONTAINED"),
+      details: { outcome: diagnosticOutcome(settlement.outcome), raw: callback.result }
+    });
+  }
+  return Object.freeze({
+    messages:
+      terminal !== undefined && settlement.authorResultAccepted
+        ? Object.freeze([...input.preflightMessages, ...terminal.messages])
+        : input.preflightMessages,
+    outcome: settlement.outcome
+  });
+}
+
+/** Records one terminal Check lifecycle fact after its owning Core scope has closed. */
+export function recordSettledCheck(
+  input: Readonly<{
+    readonly check: CheckIdentity;
+    readonly durationMs: number | null;
+    readonly messages: readonly CheckMessage[];
+    readonly outcome: CheckOutcome;
+    readonly phase: "execution" | "preflight";
+    readonly state: CheckExecutionSettlementState;
+  }>
+): void {
+  if (input.state.settledFactsByCheckId.has(input.check.checkId)) {
+    throw new CheckExecutionInvariantFailure("Check lifecycle settled more than once");
+  }
+  input.state.settledFactsByCheckId.set(
+    input.check.checkId,
+    Object.freeze({ durationMs: input.durationMs, messages: input.messages })
+  );
+  input.state.diagnosticLogger?.observe({
+    event: "check.finished",
+    tags: diagnosticTags(
+      `CHECK:${input.check.checkId}`,
+      input.phase.toUpperCase(),
+      "FINISHED",
+      input.outcome.status.toUpperCase()
+    ),
+    details: {
+      durationMs: input.durationMs,
+      ...(input.messages.length === 0 ? {} : { messages: input.messages }),
+      ...diagnosticSettledOutcome(input.outcome)
+    }
+  });
+  input.state.lifecycle?.settled(
+    Object.freeze({
+      checkId: input.check.checkId,
+      displayName: input.check.displayName,
+      outcome: input.outcome,
+      durationMs: input.durationMs,
+      messages: input.messages,
+      visibility: input.check.visibility
+    })
+  );
+}
+
+function diagnosticSettledOutcome(outcome: CheckOutcome): Readonly<Record<string, unknown>> {
+  switch (outcome.status) {
+    case "passed":
+    case "failed":
+      return Object.freeze({ data: summarizeDiagnosticValue(outcome.data) });
+    case "not-applicable":
+      return outcome.reason === undefined
+        ? Object.freeze({})
+        : Object.freeze({ reason: outcome.reason });
+    case "unavailable":
+      return Object.freeze({ reason: outcome.reason });
+  }
+}
+
+function diagnosticOutcome(outcome: CheckOutcome): Readonly<Record<string, unknown>> {
+  switch (outcome.status) {
+    case "passed":
+    case "failed":
+      return Object.freeze({
+        data: summarizeDiagnosticValue(outcome.data),
+        status: outcome.status
+      });
+    case "not-applicable":
+      return Object.freeze({ reason: outcome.reason ?? null, status: outcome.status });
+    case "unavailable":
+      return Object.freeze({ reason: outcome.reason, status: outcome.status });
+  }
+}

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

@@ -0,0 +1,46 @@
+import type { CheckMessage } from "../../check/check.ts";
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+
+const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
+
+/** Parses the shared closed Check-message attachment without retaining author input. */
+export function parseCheckMessages(value: unknown): readonly CheckMessage[] | undefined {
+  if (value === undefined) return EMPTY_MESSAGES;
+  const authoredMessages = snapshotClosedArray(value);
+  if (authoredMessages === undefined) return undefined;
+
+  const messages: CheckMessage[] = [];
+  for (const authoredMessage of authoredMessages) {
+    const message = detachedMessage(authoredMessage);
+    if (message === undefined) return undefined;
+    messages.push(message);
+  }
+  return messages.length === 0 ? EMPTY_MESSAGES : Object.freeze(messages);
+}
+
+function detachedMessage(value: unknown): CheckMessage | undefined {
+  const message = snapshotClosedRecord(value);
+  if (
+    message === undefined ||
+    !hasRequiredAndOptionalRecordKeys(message, {
+      required: ["level", "code", "message"],
+      optional: []
+    }) ||
+    !isCheckMessageLevel(message.level) ||
+    typeof message.code !== "string" ||
+    message.code.length === 0 ||
+    typeof message.message !== "string" ||
+    message.message.length === 0
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ code: message.code, level: message.level, message: message.message });
+}
+
+function isCheckMessageLevel(value: unknown): value is CheckMessage["level"] {
+  return value === "info" || value === "warning" || value === "error";
+}

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

@@ -0,0 +1,46 @@
+import type { TaskGraph, TaskNode, TaskScope } from "../task-scheduler/graph.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+
+/**
+ * Pure executable-Check projection. Check ids are the only scheduler Task
+ * identities: containment has already been resolved by Definition and has no
+ * runtime alias or completion semantics here.
+ */
+export function planStaticCheckGraph(
+  checks: readonly NormalizedCheck[],
+  options: Readonly<{ readonly alreadySettledCheckIds?: ReadonlySet<string> }> = {}
+): TaskGraph {
+  const alreadySettledCheckIds = options.alreadySettledCheckIds ?? new Set<string>();
+  const tasks = checks.map((check) => taskForCheck(check, alreadySettledCheckIds));
+  const scopes = checks.map(scopeForCheck);
+  return Object.freeze({
+    tasks: Object.freeze(tasks),
+    scopes: Object.freeze(scopes)
+  });
+}
+
+function taskForCheck(
+  check: NormalizedCheck,
+  alreadySettledCheckIds: ReadonlySet<string>
+): TaskNode {
+  return Object.freeze({
+    dependsOn: check.dependsOn.filter((checkId) => !alreadySettledCheckIds.has(checkId)),
+    id: check.definition.checkId,
+    mutex: check.mutex,
+    scopeId: scopeIdFor(check)
+  });
+}
+
+function scopeForCheck(check: NormalizedCheck): TaskScope {
+  const taskId = check.definition.checkId;
+  return Object.freeze({
+    activationTaskIds: Object.freeze([taskId]),
+    id: scopeIdFor(check),
+    maxParallel: check.maxParallel,
+    terminalTaskId: taskId
+  });
+}
+
+function scopeIdFor(check: NormalizedCheck): string {
+  return `check/${check.definition.checkId}`;
+}

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

@@ -0,0 +1,131 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import type { CheckMessage } from "../../check/check.ts";
+import { parseCheckMessages } from "./messages.ts";
+
+export type ParsedCheckPreflightResult =
+  | Readonly<{
+      readonly status: "success";
+      readonly preparedOptions: unknown;
+      readonly messages: readonly CheckMessage[];
+    }>
+  | Readonly<{
+      readonly status: "failure";
+      readonly action: "block";
+      readonly reason: { readonly code: string };
+      readonly messages: readonly CheckMessage[];
+    }>
+  | Readonly<{
+      readonly status: "failure";
+      readonly action: "continue";
+      readonly fallback: unknown;
+      readonly reason: { readonly code: string };
+      readonly messages: readonly CheckMessage[];
+    }>;
+
+/** Parses the closed result vocabulary returned by one trusted Check preflight. */
+export function parseCheckPreflightResult(value: unknown): ParsedCheckPreflightResult | undefined {
+  const preflightResult = snapshotClosedRecord(value);
+  if (preflightResult === undefined) {
+    return undefined;
+  }
+  const messages = parseCheckMessages(preflightResult.messages);
+  if (messages === undefined) return undefined;
+  switch (preflightResult.status) {
+    case "success":
+      return parseSuccessfulPreflight(preflightResult, messages);
+    case "failure":
+      return parseFailedPreflight(preflightResult, messages);
+    default:
+      return undefined;
+  }
+}
+
+function parseSuccessfulPreflight(
+  preflightResult: Readonly<Record<string, unknown>>,
+  messages: readonly CheckMessage[]
+): ParsedCheckPreflightResult | undefined {
+  if (
+    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+      optional: ["messages"],
+      required: ["status", "preparedOptions"]
+    })
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    status: "success",
+    preparedOptions: preflightResult.preparedOptions,
+    messages
+  });
+}
+
+function parseFailedPreflight(
+  preflightResult: Readonly<Record<string, unknown>>,
+  messages: readonly CheckMessage[]
+): ParsedCheckPreflightResult | undefined {
+  if (typeof preflightResult.action !== "string") return undefined;
+  const reason = parsePreflightReason(preflightResult.reason);
+  if (reason === undefined) return undefined;
+  switch (preflightResult.action) {
+    case "block":
+      return parseBlockedPreflight(preflightResult, reason, messages);
+    case "continue":
+      return parseContinuedPreflight(preflightResult, reason, messages);
+    default:
+      return undefined;
+  }
+}
+
+function parseBlockedPreflight(
+  preflightResult: Readonly<Record<string, unknown>>,
+  reason: Readonly<{ readonly code: string }>,
+  messages: readonly CheckMessage[]
+): ParsedCheckPreflightResult | undefined {
+  if (
+    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+      optional: ["messages"],
+      required: ["status", "action", "reason"]
+    })
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ status: "failure", action: "block", reason, messages });
+}
+
+function parseContinuedPreflight(
+  preflightResult: Readonly<Record<string, unknown>>,
+  reason: Readonly<{ readonly code: string }>,
+  messages: readonly CheckMessage[]
+): ParsedCheckPreflightResult | undefined {
+  if (
+    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+      optional: ["messages"],
+      required: ["status", "action", "fallback", "reason"]
+    })
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    status: "failure",
+    action: "continue" as const,
+    fallback: preflightResult.fallback,
+    reason,
+    messages
+  });
+}
+
+function parsePreflightReason(value: unknown): Readonly<{ readonly code: string }> | undefined {
+  const reason = snapshotClosedRecord(value);
+  if (
+    reason === undefined ||
+    Object.keys(reason).length !== 1 ||
+    typeof reason.code !== "string" ||
+    reason.code.length === 0
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ code: reason.code });
+}