@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/project-run/check-execution/{preflight-result.ts → preparation-result.ts}

@@ -5,7 +5,7 @@ import {
 import type { CheckMessage } from "../../check/check.ts";
 import { parseCheckMessages } from "./messages.ts";
 
-export type ParsedCheckPreflightResult =
+export type ParsedCheckPreparationResult =
   | Readonly<{
       readonly status: "success";
       readonly preparedOptions: unknown;
@@ -25,30 +25,32 @@ export type ParsedCheckPreflightResult =
       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) {
+/** Parses the closed result vocabulary returned by one trusted Check preparation. */
+export function parseCheckPreparationResult(
+  value: unknown
+): ParsedCheckPreparationResult | undefined {
+  const preparationResult = snapshotClosedRecord(value);
+  if (preparationResult === undefined) {
     return undefined;
   }
-  const messages = parseCheckMessages(preflightResult.messages);
+  const messages = parseCheckMessages(preparationResult.messages);
   if (messages === undefined) return undefined;
-  switch (preflightResult.status) {
+  switch (preparationResult.status) {
     case "success":
-      return parseSuccessfulPreflight(preflightResult, messages);
+      return parseSuccessfulPreparation(preparationResult, messages);
     case "failure":
-      return parseFailedPreflight(preflightResult, messages);
+      return parseFailedPreparation(preparationResult, messages);
     default:
       return undefined;
   }
 }
 
-function parseSuccessfulPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseSuccessfulPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "preparedOptions"]
     })
@@ -57,35 +59,35 @@ function parseSuccessfulPreflight(
   }
   return Object.freeze({
     status: "success",
-    preparedOptions: preflightResult.preparedOptions,
+    preparedOptions: preparationResult.preparedOptions,
     messages
   });
 }
 
-function parseFailedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseFailedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
-  if (typeof preflightResult.action !== "string") return undefined;
-  const reason = parsePreflightReason(preflightResult.reason);
+): ParsedCheckPreparationResult | undefined {
+  if (typeof preparationResult.action !== "string") return undefined;
+  const reason = parsePreparationReason(preparationResult.reason);
   if (reason === undefined) return undefined;
-  switch (preflightResult.action) {
+  switch (preparationResult.action) {
     case "block":
-      return parseBlockedPreflight(preflightResult, reason, messages);
+      return parseBlockedPreparation(preparationResult, reason, messages);
     case "continue":
-      return parseContinuedPreflight(preflightResult, reason, messages);
+      return parseContinuedPreparation(preparationResult, reason, messages);
     default:
       return undefined;
   }
 }
 
-function parseBlockedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseBlockedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   reason: Readonly<{ readonly code: string }>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "action", "reason"]
     })
@@ -95,13 +97,13 @@ function parseBlockedPreflight(
   return Object.freeze({ status: "failure", action: "block", reason, messages });
 }
 
-function parseContinuedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseContinuedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   reason: Readonly<{ readonly code: string }>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "action", "fallback", "reason"]
     })
@@ -111,13 +113,13 @@ function parseContinuedPreflight(
   return Object.freeze({
     status: "failure",
     action: "continue" as const,
-    fallback: preflightResult.fallback,
+    fallback: preparationResult.fallback,
     reason,
     messages
   });
 }
 
-function parsePreflightReason(value: unknown): Readonly<{ readonly code: string }> | undefined {
+function parsePreparationReason(value: unknown): Readonly<{ readonly code: string }> | undefined {
   const reason = snapshotClosedRecord(value);
   if (
     reason === undefined ||

package/src/project-run/check-execution/{preflight.ts → preparation.ts}

@@ -1,4 +1,4 @@
-import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CheckMessage, CheckOutcome, CheckProjectContext } from "../../check/check.ts";
 import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
 import { snapshotJsonObject } from "../../check/options-snapshot.ts";
 import {
@@ -6,35 +6,38 @@ import {
   summarizeDiagnosticValue,
   type DiagnosticLogger
 } from "../diagnostic-logging/logger.ts";
-import { parseCheckPreflightResult, type ParsedCheckPreflightResult } from "./preflight-result.ts";
+import {
+  parseCheckPreparationResult,
+  type ParsedCheckPreparationResult
+} from "./preparation-result.ts";
 import { invokeWithCapturedConsole } from "./console-capture.ts";
 import { combineCheckMessages } from "./messages.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[] }>;
+export type PreparedCheck = Omit<NormalizedCheck, "options" | "prepare"> &
+  Readonly<{ readonly options: object; readonly preparationMessages: readonly CheckMessage[] }>;
 
-type BlockedCheck = Pick<NormalizedCheck, "definition" | "visibility"> &
-  Readonly<{ readonly preflightMessages: readonly CheckMessage[] }>;
+type BlockedCheck = Pick<NormalizedCheck, "definition" | "omitQuietPassedRow"> &
+  Readonly<{ readonly preparationMessages: readonly CheckMessage[] }>;
 
-export type ReadyCheckPreflightResolution = Readonly<{
+export type ReadyCheckPreparationResolution = Readonly<{
   readonly kind: "ready";
   readonly check: PreparedCheck;
 }>;
 
-export type BlockedCheckPreflightResolution = Readonly<{
+export type BlockedCheckPreparationResolution = Readonly<{
   readonly kind: "blocked";
   readonly check: BlockedCheck;
   readonly outcome: CheckOutcome;
 }>;
 
-export type CheckPreflightResolution =
-  | ReadyCheckPreflightResolution
-  | BlockedCheckPreflightResolution;
+export type CheckPreparationResolution =
+  | ReadyCheckPreparationResolution
+  | BlockedCheckPreparationResolution;
 
-type PreflightResolutionResult =
+type PreparationResolutionResult =
   | "skipped"
   | "prepared"
   | "continued"
@@ -48,15 +51,16 @@ type PreflightResolutionResult =
 type PrepareCheckInput = Readonly<{
   readonly check: NormalizedCheck;
   readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly project: CheckProjectContext;
   readonly signal: AbortSignal | undefined;
 }>;
 
-type PreflightInvocation = Awaited<ReturnType<typeof invokeWithCapturedConsole<unknown>>>;
+type PreparationInvocation = Awaited<ReturnType<typeof invokeWithCapturedConsole<unknown>>>;
 
 /** Resolves one Check's task-local preparation after Scheduler admission. */
-export async function prepareCheck(input: PrepareCheckInput): Promise<CheckPreflightResolution> {
-  if (input.signal?.aborted) {
-    return observeBlockedPreflight({
+export async function prepareCheck(input: PrepareCheckInput): Promise<CheckPreparationResolution> {
+  if (input.signal?.aborted === true) {
+    return observeBlockedPreparation({
       check: input.check,
       diagnosticLogger: input.diagnosticLogger,
       details: {},
@@ -64,13 +68,13 @@ export async function prepareCheck(input: PrepareCheckInput): Promise<CheckPrefl
       reasonCode: "execution-cancelled"
     });
   }
-  if (input.check.preflight === undefined) {
+  if (input.check.prepare === undefined) {
     return resolveAuthoredOptions(input);
   }
-  return resolvePreflightInvocation(input, await invokePreflight(input.check, input.signal));
+  return resolvePreparationInvocation(input, await invokePreparation(input));
 }
 
-function resolveAuthoredOptions(input: PrepareCheckInput): CheckPreflightResolution {
+function resolveAuthoredOptions(input: PrepareCheckInput): CheckPreparationResolution {
   const resolution = readyResolution({
     authoredCheck: input.check,
     messages: EMPTY_MESSAGES,
@@ -86,125 +90,129 @@ function resolveAuthoredOptions(input: PrepareCheckInput): CheckPreflightResolut
   return resolution;
 }
 
-function resolvePreflightInvocation(
+function resolvePreparationInvocation(
   input: PrepareCheckInput,
-  invocation: PreflightInvocation
-): CheckPreflightResolution {
+  invocation: PreparationInvocation
+): CheckPreparationResolution {
   if (invocation.kind === "threw") {
-    return observeBlockedPreflight({
+    return observeBlockedPreparation({
       check: input.check,
       diagnosticLogger: input.diagnosticLogger,
       details: { error: invocation.error },
       messages: invocation.messages,
-      result: input.signal?.aborted ? "cancelled-after-throw" : "threw",
-      reasonCode: input.signal?.aborted ? "execution-cancelled" : "preflight-threw"
+      result: input.signal?.aborted === true ? "cancelled-after-throw" : "threw",
+      reasonCode: input.signal?.aborted === true ? "execution-cancelled" : "preparation-threw"
     });
   }
-  return resolveReturnedPreflight(input, invocation.output, invocation.messages);
+  return resolveReturnedPreparation(input, invocation.output, invocation.messages);
 }
 
-function resolveReturnedPreflight(
+function resolveReturnedPreparation(
   input: PrepareCheckInput,
-  preflightOutput: unknown,
+  preparationOutput: unknown,
   consoleMessages: readonly CheckMessage[]
-): CheckPreflightResolution {
-  if (input.signal?.aborted) {
-    return observeBlockedPreflight({
+): CheckPreparationResolution {
+  if (input.signal?.aborted === true) {
+    return observeBlockedPreparation({
       check: input.check,
       diagnosticLogger: input.diagnosticLogger,
-      details: { raw: preflightOutput },
+      details: { raw: preparationOutput },
       messages: consoleMessages,
       result: "cancelled-after-callback",
       reasonCode: "execution-cancelled"
     });
   }
-  const preflightResult = parseCheckPreflightResult(preflightOutput);
-  if (preflightResult === undefined) {
-    return observeBlockedPreflight({
+  const preparationResult = parseCheckPreparationResult(preparationOutput);
+  if (preparationResult === undefined) {
+    return observeBlockedPreparation({
       check: input.check,
       diagnosticLogger: input.diagnosticLogger,
-      details: { raw: preflightOutput },
+      details: { raw: preparationOutput },
       messages: consoleMessages,
       result: "malformed",
-      reasonCode: "invalid-preflight-result"
+      reasonCode: "invalid-preparation-result"
     });
   }
-  if (preflightResult.status === "failure" && preflightResult.action === "block") {
-    return resolveBlockedPreflightResult(input, preflightResult, consoleMessages);
+  if (preparationResult.status === "failure" && preparationResult.action === "block") {
+    return resolveBlockedPreparationResult(input, preparationResult, consoleMessages);
   }
-  return resolveReadyPreflightResult(input, preflightOutput, preflightResult, consoleMessages);
+  return resolveReadyPreparationResult(
+    input,
+    preparationOutput,
+    preparationResult,
+    consoleMessages
+  );
 }
 
-function resolveBlockedPreflightResult(
+function resolveBlockedPreparationResult(
   input: PrepareCheckInput,
-  preflightResult: Extract<ParsedCheckPreflightResult, { readonly action: "block" }>,
+  preparationResult: Extract<ParsedCheckPreparationResult, { readonly action: "block" }>,
   consoleMessages: readonly CheckMessage[]
-): CheckPreflightResolution {
+): CheckPreparationResolution {
   const resolution = blockedResolution({
     check: input.check,
-    messages: combineCheckMessages(consoleMessages, preflightResult.messages),
-    reasonCode: preflightResult.reason.code
+    messages: combineCheckMessages(consoleMessages, preparationResult.messages),
+    reasonCode: preparationResult.reason.code
   });
-  observePreflightResolution(
+  observePreparationResolution(
     input.diagnosticLogger,
     input.check.definition.checkId,
     resolution,
     "blocked",
     {
-      ...(preflightResult.messages.length === 0 ? {} : { messages: preflightResult.messages }),
-      reason: preflightResult.reason
+      ...(preparationResult.messages.length === 0 ? {} : { messages: preparationResult.messages }),
+      reason: preparationResult.reason
     }
   );
   return resolution;
 }
 
-function resolveReadyPreflightResult(
+function resolveReadyPreparationResult(
   input: PrepareCheckInput,
-  preflightOutput: unknown,
-  preflightResult: Exclude<ParsedCheckPreflightResult, { readonly action: "block" }>,
+  preparationOutput: unknown,
+  preparationResult: Exclude<ParsedCheckPreparationResult, { readonly action: "block" }>,
   consoleMessages: readonly CheckMessage[]
-): CheckPreflightResolution {
+): CheckPreparationResolution {
   const checkId = input.check.definition.checkId;
-  const result = preflightResult.status === "success" ? "prepared" : "continued";
+  const result = preparationResult.status === "success" ? "prepared" : "continued";
   const resolution = readyResolution({
     authoredCheck: input.check,
-    messages: combineCheckMessages(consoleMessages, preflightResult.messages),
+    messages: combineCheckMessages(consoleMessages, preparationResult.messages),
     preparedOptions:
-      preflightResult.status === "success"
-        ? preflightResult.preparedOptions
-        : preflightResult.fallback
+      preparationResult.status === "success"
+        ? preparationResult.preparedOptions
+        : preparationResult.fallback
   });
   observeReadyOrMalformedResolution(input.diagnosticLogger, checkId, resolution, result, {
-    messages: preflightResult.messages,
-    ...(preflightResult.status === "success" ? {} : { reason: preflightResult.reason }),
-    raw: preflightOutput
+    messages: preparationResult.messages,
+    ...(preparationResult.status === "success" ? {} : { reason: preparationResult.reason }),
+    raw: preparationOutput
   });
   return resolution;
 }
 
-async function invokePreflight(
-  check: NormalizedCheck,
-  signal: AbortSignal | undefined
-): Promise<PreflightInvocation> {
-  return invokeWithCapturedConsole(() => check.preflight!(check.options, signal ?? INERT_SIGNAL));
+async function invokePreparation(input: PrepareCheckInput): Promise<PreparationInvocation> {
+  return invokeWithCapturedConsole(() =>
+    input.check.prepare!(input.check.options, input.signal ?? INERT_SIGNAL, input.project)
+  );
 }
 
-function observeBlockedPreflight(
+function observeBlockedPreparation(
   input: Readonly<{
     readonly check: NormalizedCheck;
     readonly diagnosticLogger: DiagnosticLogger | undefined;
     readonly details: Readonly<Record<string, unknown>>;
     readonly messages?: readonly CheckMessage[];
-    readonly result: PreflightResolutionResult;
+    readonly result: PreparationResolutionResult;
     readonly reasonCode: string;
   }>
-): BlockedCheckPreflightResolution {
+): BlockedCheckPreparationResolution {
   const resolution = blockedResolution({
     check: input.check,
     messages: input.messages ?? EMPTY_MESSAGES,
     reasonCode: input.reasonCode
   });
-  observePreflightResolution(
+  observePreparationResolution(
     input.diagnosticLogger,
     input.check.definition.checkId,
     resolution,
@@ -217,18 +225,18 @@ function observeBlockedPreflight(
 function observeReadyOrMalformedResolution(
   diagnosticLogger: DiagnosticLogger | undefined,
   checkId: string,
-  resolution: CheckPreflightResolution,
+  resolution: CheckPreparationResolution,
   result: "skipped" | "prepared" | "continued",
   details: Readonly<Record<string, unknown>>
 ): void {
   if (resolution.kind === "blocked") {
-    observePreflightResolution(diagnosticLogger, checkId, resolution, "malformed", {
+    observePreparationResolution(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, {
+  observePreparationResolution(diagnosticLogger, checkId, resolution, result, {
     ...(Array.isArray(messages) && messages.length > 0 ? { messages } : {}),
     options: summarizeDiagnosticValue(resolution.check.options),
     ...("reason" in details ? { reason: details.reason } : {}),
@@ -236,16 +244,16 @@ function observeReadyOrMalformedResolution(
   });
 }
 
-function observePreflightResolution(
+function observePreparationResolution(
   diagnosticLogger: DiagnosticLogger | undefined,
   checkId: string,
-  resolution: CheckPreflightResolution,
-  result: PreflightResolutionResult,
+  resolution: CheckPreparationResolution,
+  result: PreparationResolutionResult,
   details: Readonly<Record<string, unknown>>
 ): void {
   diagnosticLogger?.observe({
-    event: "preflight.resolved",
-    tags: diagnosticTags(`CHECK:${checkId}`, "PREFLIGHT", result.toUpperCase()),
+    event: "preparation.resolved",
+    tags: diagnosticTags(`CHECK:${checkId}`, "PREPARATION", result.toUpperCase()),
     details: {
       ...details,
       ...(resolution.kind === "blocked" ? { outcome: resolution.outcome } : {})
@@ -259,22 +267,22 @@ function readyResolution(
     readonly messages: readonly CheckMessage[];
     readonly preparedOptions: unknown;
   }>
-): CheckPreflightResolution {
+): CheckPreparationResolution {
   const preparedOptions = snapshotJsonObject(input.preparedOptions);
   if (preparedOptions === undefined) {
     return blockedResolution({
       check: input.authoredCheck,
       messages: input.messages,
-      reasonCode: "invalid-preflight-result"
+      reasonCode: "invalid-preparation-result"
     });
   }
-  const { preflight: _preflight, ...check } = input.authoredCheck;
+  const { prepare: _preparation, ...check } = input.authoredCheck;
   return Object.freeze({
     kind: "ready",
     check: Object.freeze({
       ...check,
       options: preparedOptions,
-      preflightMessages: input.messages
+      preparationMessages: input.messages
     })
   });
 }
@@ -285,13 +293,13 @@ function blockedResolution(
     readonly messages: readonly CheckMessage[];
     readonly reasonCode: string;
   }>
-): BlockedCheckPreflightResolution {
+): BlockedCheckPreparationResolution {
   return Object.freeze({
     kind: "blocked",
     check: Object.freeze({
       definition: input.check.definition,
-      preflightMessages: input.messages,
-      visibility: input.check.visibility
+      preparationMessages: input.messages,
+      omitQuietPassedRow: input.check.omitQuietPassedRow
     }),
     outcome: Object.freeze({
       status: "unavailable",

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

@@ -0,0 +1,97 @@
+/** Executes and settles a Check after its task-local preparation has admitted it. */
+
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { artifactDirectoryForCheck, type ResolvedInvocationPaths } from "../invocation/paths.ts";
+import { diagnosticTags, summarizeDiagnosticValue } from "../diagnostic-logging/logger.ts";
+import { executeCheckCallback } from "./callback.ts";
+import { createCheckDependencies } from "./dependencies.ts";
+import { checkIdentity } from "./execution-finalization.ts";
+import {
+  recordSettledCheck,
+  settleCallback,
+  type CheckExecutionState
+} from "./execution-settlement.ts";
+import type { ReadyCheckPreparationResolution } from "./preparation.ts";
+
+export type ReadyCheckExecutionInput = CheckExecutionState &
+  Readonly<{
+    readonly check: NormalizedCheck;
+    readonly clock: Readonly<{ now(): number }>;
+    readonly invocationId: string;
+    readonly paths: ResolvedInvocationPaths | undefined;
+    readonly prepare: ReadyCheckPreparationResolution;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal;
+  }>;
+
+export async function executeReadyCheck(input: ReadyCheckExecutionInput): Promise<boolean> {
+  const check = input.prepare.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)
+    }
+  });
+  input.lifecycle?.started(
+    Object.freeze({
+      checkId: identity.checkId,
+      displayName: identity.displayName,
+      omitQuietPassedRow: identity.omitQuietPassedRow
+    })
+  );
+  const startedAt = input.clock.now();
+  const callback = await executeCheckCallback({
+    artifactDirectory:
+      input.paths === undefined ? null : artifactDirectoryForCheck(input.paths, checkId),
+    check,
+    dependencies: createCheckDependencies({
+      checkId,
+      directDependsOnCheckIds: check.dependsOn,
+      diagnosticLogger: input.diagnosticLogger,
+      directRelationCheckIds: directRelationCheckIds(check),
+      handoffsByCheckId: input.handoffsByCheckId,
+      session: input.session
+    }),
+    ...(input.diagnosticLogger === undefined ? {} : { diagnosticLogger: input.diagnosticLogger }),
+    invocationId: input.invocationId,
+    project: input.project,
+    scope,
+    signal: input.signal
+  });
+  const settled = settleCallback({
+    callback,
+    checkId,
+    diagnosticLogger: input.diagnosticLogger,
+    handoff: check.handoff,
+    preparationMessages: check.preparationMessages,
+    scope,
+    state: input
+  });
+  recordSettledCheck({
+    check: identity,
+    durationMs: durationSince(startedAt, input.clock),
+    messages: settled.messages,
+    outcome: settled.outcome,
+    phase: "execution",
+    state: input
+  });
+  return settled.outcome.status === "passed";
+}
+
+function directRelationCheckIds(
+  check: Pick<NormalizedCheck, "dependsOn" | "observes">
+): readonly string[] {
+  return Object.freeze([...new Set([...check.dependsOn, ...check.observes])].sort());
+}
+
+function durationSince(startedAt: number, clock: Readonly<{ now(): number }>): number {
+  const elapsed = clock.now() - startedAt;
+  return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : 0;
+}