@zxyycom/vibe-check 0.0.1

package/src/project-run/invocation.ts

@@ -0,0 +1,303 @@
+import type { CheckProjectContext } from "../check/check.ts";
+import type { CoreSnapshot } from "../check-settlement/facts.ts";
+import {
+  normalizeProjectDefinition,
+  type DefinitionWarning,
+  type NormalizedProjectDefinition,
+  type ProjectDefinition
+} from "../project-definition/project-definition.ts";
+import type { CheckAggregation, RunControls } from "./controls/contract.ts";
+import { prepareTaskGraph } from "./task-scheduler/graph.ts";
+import { aggregateCheckOutcomes, validateCheckAggregationSelection } from "./aggregation.ts";
+import {
+  executeResolvedChecks,
+  type CheckExecutionClock,
+  type ResolvedCheckExecution
+} from "./check-execution/resolved-checks.ts";
+import { planStaticCheckGraph } from "./check-execution/plan.ts";
+import {
+  type ProgressRefreshScheduler,
+  type ProgressRendering,
+  type ProgressWriterFactory
+} from "./progress-rendering/presentation.ts";
+import { completeInvocation, finalizeInvocation, type CoreExecution } from "./completion.ts";
+import { createProjectContext } from "./project-context.ts";
+import {
+  executionCancellation,
+  isCancelled,
+  planning,
+  preExecutionCancellation,
+  type NonConfigurationRunResult,
+  type RunDiagnostic,
+  type RunResult
+} from "./result.ts";
+import {
+  diagnosticTags,
+  type DiagnosticLogger,
+  type DiagnosticLoggerFactory
+} from "./diagnostic-logging/logger.ts";
+import { createInvocation } from "./invocation-creation.ts";
+import type { OutputStatuses } from "./output-status.ts";
+export type Invocation = Readonly<{
+  readonly clock: CheckExecutionClock;
+  readonly controls: RunControls;
+  readonly declarativeFingerprint: string;
+  readonly definition: ProjectDefinition;
+  readonly definitionWarnings: readonly DefinitionWarning[];
+  readonly diagnosticLogger: DiagnosticLogger;
+  readonly outputConfiguration: ProjectDefinition["outputs"];
+  readonly outputs: OutputStatuses;
+  readonly invocationId: string;
+  readonly normalized: NormalizedProjectDefinition;
+  readonly progressRendering: ProgressRendering;
+  readonly projectRoot: string;
+  /** Immutable UTC instant captured for enabled diagnostic or machine output, otherwise `null`. */
+  readonly startedAtUtc: string | null;
+}>;
+export interface RunInvocationDependencies {
+  readonly clock?: CheckExecutionClock;
+  readonly progressRefreshScheduler?: ProgressRefreshScheduler;
+  readonly progressWriterFactory?: ProgressWriterFactory;
+  readonly diagnosticLoggerFactory?: DiagnosticLoggerFactory;
+  /** Test seam for the invocation's machine-readable wall-clock timestamp. */
+  readonly wallClock?: Readonly<{ now(): Date }>;
+}
+export async function executeValidatedRun(
+  definition: ProjectDefinition,
+  controls: RunControls,
+  definitionWarnings: readonly DefinitionWarning[],
+  dependencies: RunInvocationDependencies = {}
+): Promise<RunResult> {
+  const normalized = normalizeProjectDefinition(definition);
+  const aggregation = validateCheckAggregationSelection(
+    controls.checkAggregation,
+    normalized.checks.map((check) => check.definition.checkId)
+  );
+  if (!aggregation.ok)
+    return Object.freeze({
+      kind: "configuration",
+      definitionWarnings: Object.freeze([...definitionWarnings]),
+      diagnostic: aggregation.error
+    });
+
+  const invocation = createInvocation({
+    controls,
+    definition,
+    definitionWarnings,
+    dependencies,
+    normalized
+  });
+  let candidate: NonConfigurationRunResult;
+  try {
+    observeInvocationStarted(invocation, aggregation.value);
+    if (isCancelled(controls)) {
+      candidate = cancelledBeforeExecution(invocation, "pre-work");
+    } else if (!validateTaskGraph(invocation)) {
+      candidate = planningResult(invocation, "task-graph-invalid");
+    } else {
+      candidate = await executePlannedInvocation(invocation, aggregation.value);
+    }
+  } catch {
+    candidate = executionResult(invocation, "task-engine-failed");
+  }
+  return finalizeInvocation(invocation, candidate);
+}
+
+function observeInvocationStarted(
+  invocation: Invocation,
+  aggregation: CheckAggregation | undefined
+): void {
+  invocation.diagnosticLogger.observe({
+    event: "run.started",
+    tags: diagnosticTags("RUN", "STARTED"),
+    details: {
+      aggregation: aggregation ?? null,
+      checkCount: invocation.normalized.checks.length,
+      flags: invocation.controls.flags ?? [],
+      invocationId: invocation.invocationId,
+      outputs: invocation.outputConfiguration,
+      scheduler: invocation.normalized.declarative.scheduler
+    }
+  });
+}
+
+function validateTaskGraph(invocation: Invocation): boolean {
+  try {
+    prepareTaskGraph(
+      planStaticCheckGraph(invocation.normalized.checks),
+      invocation.normalized.declarative.scheduler.maxParallel
+    );
+    invocation.diagnosticLogger.observe({
+      event: "run.planning.succeeded",
+      tags: diagnosticTags("RUN", "PLANNING", "SUCCEEDED"),
+      details: {
+        checkCount: invocation.normalized.checks.length,
+        maxParallel: invocation.normalized.declarative.scheduler.maxParallel
+      }
+    });
+    return true;
+  } catch {
+    invocation.diagnosticLogger.observe({
+      event: "run.planning.failed",
+      tags: diagnosticTags("RUN", "PLANNING", "FAILED"),
+      details: {
+        checkCount: invocation.normalized.checks.length,
+        maxParallel: invocation.normalized.declarative.scheduler.maxParallel
+      }
+    });
+    return false;
+  }
+}
+async function executePlannedInvocation(
+  invocation: Invocation,
+  aggregation: CheckAggregation | undefined
+): Promise<NonConfigurationRunResult> {
+  if (isCancelled(invocation.controls)) return cancelledBeforeExecution(invocation, "pre-work");
+  return executePreparedInvocation(
+    invocation,
+    aggregation,
+    createProjectContext({ controls: invocation.controls, root: invocation.projectRoot })
+  );
+}
+async function executePreparedInvocation(
+  invocation: Invocation,
+  aggregation: CheckAggregation | undefined,
+  project: CheckProjectContext
+): Promise<NonConfigurationRunResult> {
+  if (isCancelled(invocation.controls)) return cancelledBeforeExecution(invocation, "planning");
+  invocation.progressRendering.prepared(invocation.normalized.checks.length);
+  const executionStartedAt = invocation.clock.now();
+  const executed = await executeChecks(invocation, project, invocation.clock);
+  if (isExecutionRunResult(executed)) return executed;
+  invocation.progressRendering.final({
+    counts: outcomeCounts(executed.snapshot),
+    elapsedMs: elapsedSince(executionStartedAt, invocation.clock),
+    execution: executed.kind
+  });
+  if (executed.kind === "cancelled") {
+    invocation.diagnosticLogger.observe({
+      event: "run.execution.cancelled",
+      tags: diagnosticTags("RUN", "EXECUTION", "CANCELLED"),
+      details: { checkCount: executed.snapshot.checks.length }
+    });
+    return executionCancellation({
+      checkDurations: executed.checkDurations,
+      checkMessages: executed.checkMessages,
+      declarativeFingerprint: invocation.declarativeFingerprint,
+      definitionWarnings: invocation.definitionWarnings,
+      outputs: invocation.outputs.value(),
+      snapshot: executed.snapshot
+    });
+  }
+  const aggregate =
+    aggregation === undefined ? null : aggregateCheckOutcomes(executed.snapshot, aggregation);
+  invocation.diagnosticLogger.observe({
+    event: "run.aggregation.completed",
+    tags: diagnosticTags("RUN", "AGGREGATION", "COMPLETED"),
+    details: { aggregate, selection: aggregation ?? null }
+  });
+  const core: CoreExecution = Object.freeze({
+    aggregate,
+    checkDurations: executed.checkDurations,
+    checkMessages: executed.checkMessages,
+    snapshot: executed.snapshot
+  });
+  return completeInvocation(invocation, core);
+}
+
+function cancelledBeforeExecution(
+  invocation: Invocation,
+  phase: "pre-work" | "planning"
+): NonConfigurationRunResult {
+  invocation.diagnosticLogger.observe({
+    event: "run.cancelled",
+    tags: diagnosticTags("RUN", "CANCELLED"),
+    details: { phase }
+  });
+  return preExecutionCancellation(
+    invocation.declarativeFingerprint,
+    invocation.definitionWarnings,
+    invocation.outputs.value(),
+    phase
+  );
+}
+
+async function executeChecks(
+  invocation: Invocation,
+  project: CheckProjectContext,
+  clock: CheckExecutionClock
+): Promise<ResolvedCheckExecution | NonConfigurationRunResult> {
+  try {
+    return await executeResolvedChecks({
+      checks: invocation.normalized.checks,
+      clock,
+      diagnosticLogger: invocation.diagnosticLogger,
+      maxParallel: invocation.normalized.declarative.scheduler.maxParallel,
+      lifecycle: invocation.progressRendering.lifecycle,
+      project,
+      signal: invocation.controls.signal
+    });
+  } catch {
+    return executionResult(invocation, "task-engine-failed");
+  }
+}
+function outcomeCounts(snapshot: CoreSnapshot): Readonly<{
+  readonly failed: number;
+  readonly notApplicable: number;
+  readonly passed: number;
+  readonly unavailable: number;
+}> {
+  let failed = 0,
+    notApplicable = 0,
+    passed = 0,
+    unavailable = 0;
+  for (const check of snapshot.checks) {
+    switch (check.outcome.status) {
+      case "passed":
+        passed += 1;
+        break;
+      case "failed":
+        failed += 1;
+        break;
+      case "not-applicable":
+        notApplicable += 1;
+        break;
+      case "unavailable":
+        unavailable += 1;
+        break;
+    }
+  }
+  return Object.freeze({ failed, notApplicable, passed, unavailable });
+}
+function elapsedSince(startedAt: number, clock: CheckExecutionClock): number {
+  const elapsed = clock.now() - startedAt;
+  return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : 0;
+}
+function planningResult(
+  invocation: Invocation,
+  code: Extract<RunDiagnostic["code"], "task-graph-invalid">
+): NonConfigurationRunResult {
+  return planning(
+    invocation.declarativeFingerprint,
+    invocation.definitionWarnings,
+    invocation.outputs.value(),
+    code
+  );
+}
+function executionResult(
+  invocation: Invocation,
+  code: Extract<RunDiagnostic["code"], "publication-model-failed" | "task-engine-failed">
+): NonConfigurationRunResult {
+  return Object.freeze({
+    kind: "execution",
+    declarativeFingerprint: invocation.declarativeFingerprint,
+    definitionWarnings: invocation.definitionWarnings,
+    diagnostic: Object.freeze({ code }),
+    outputs: invocation.outputs.value()
+  });
+}
+function isExecutionRunResult(
+  value: ResolvedCheckExecution | NonConfigurationRunResult
+): value is NonConfigurationRunResult {
+  return "declarativeFingerprint" in value;
+}

package/src/project-run/machine-publication.ts

@@ -0,0 +1,23 @@
+import type { ProjectOutputs } from "../project-definition/project-definition.ts";
+import type { TrustedPublicationModelV4 } from "../machine-output/v4/publication-model.ts";
+import { publishScanV4 } from "../machine-output/v4/publish.ts";
+import type { OutputStatuses } from "./output-status.ts";
+/** Publishes an already-trusted v4 model as the Run-owned machine output. */
+export function publishMachineOutput(
+  input: Readonly<{
+    readonly configuration: ProjectOutputs["machinePublication"];
+    readonly statuses: OutputStatuses;
+    readonly model: TrustedPublicationModelV4;
+    readonly directory: string;
+  }>
+): boolean {
+  if (!input.configuration.enabled) return true;
+  try {
+    publishScanV4({ artifactDir: input.directory, model: input.model });
+    input.statuses.succeeded("machinePublication");
+    return true;
+  } catch {
+    input.statuses.failed("machinePublication");
+    return false;
+  }
+}

package/src/project-run/output-configuration.ts

@@ -0,0 +1,24 @@
+import type {
+  ProjectDefinition,
+  ProjectOutputs
+} from "../project-definition/project-definition.ts";
+import type { RunControls } from "./controls/contract.ts";
+export function effectiveOutputs(
+  definition: ProjectDefinition,
+  controls: RunControls
+): ProjectOutputs {
+  return Object.freeze({
+    machinePublication: Object.freeze({
+      ...definition.outputs.machinePublication,
+      ...controls.outputs?.machinePublication
+    }),
+    progressRendering: Object.freeze({
+      ...definition.outputs.progressRendering,
+      ...controls.outputs?.progressRendering
+    }),
+    diagnosticLogging: Object.freeze({
+      ...definition.outputs.diagnosticLogging,
+      ...controls.outputs?.diagnosticLogging
+    })
+  });
+}

package/src/project-run/output-status.ts

@@ -0,0 +1,69 @@
+import type { ProjectOutputs } from "../project-definition/project-definition.ts";
+
+export interface RunOutputStatus {
+  readonly enabled: boolean;
+  readonly status: "disabled" | "failed" | "not-run" | "succeeded";
+}
+
+export interface RunDiagnosticLoggingOutputStatus extends RunOutputStatus {
+  /** Project-root-relative target when enabled, otherwise `null`. */
+  readonly file: string | null;
+}
+
+export interface RunOutputStatuses {
+  readonly machinePublication: RunOutputStatus;
+  readonly progressRendering: RunOutputStatus;
+  readonly diagnosticLogging: RunDiagnosticLoggingOutputStatus;
+}
+
+export interface OutputStatuses {
+  readonly failed: (output: keyof RunOutputStatuses) => void;
+  readonly succeeded: (output: keyof RunOutputStatuses) => void;
+  readonly value: () => RunOutputStatuses;
+}
+
+export function createOutputStatuses(
+  configuration: ProjectOutputs,
+  diagnosticLoggingFile: string | null
+): OutputStatuses {
+  const statuses: Record<keyof RunOutputStatuses, RunOutputStatus["status"]> = {
+    machinePublication: initialStatus(configuration.machinePublication.enabled),
+    progressRendering: initialStatus(configuration.progressRendering.enabled),
+    diagnosticLogging: initialStatus(configuration.diagnosticLogging.enabled)
+  };
+  const enabled = (output: keyof RunOutputStatuses): boolean => configuration[output].enabled;
+  return Object.freeze({
+    failed: (output: keyof RunOutputStatuses) => {
+      if (enabled(output)) statuses[output] = "failed";
+    },
+    succeeded: (output: keyof RunOutputStatuses) => {
+      if (enabled(output)) statuses[output] = "succeeded";
+    },
+    value: () =>
+      Object.freeze({
+        machinePublication: Object.freeze({
+          enabled: configuration.machinePublication.enabled,
+          status: statuses.machinePublication
+        }),
+        progressRendering: Object.freeze({
+          enabled: configuration.progressRendering.enabled,
+          status: statuses.progressRendering
+        }),
+        diagnosticLogging: Object.freeze({
+          enabled: configuration.diagnosticLogging.enabled,
+          file: diagnosticLoggingFile,
+          status: statuses.diagnosticLogging
+        })
+      })
+  });
+}
+
+export function failedOutput(statuses: RunOutputStatuses): keyof RunOutputStatuses | undefined {
+  for (const output of ["progressRendering", "machinePublication", "diagnosticLogging"] as const)
+    if (statuses[output].status === "failed") return output;
+  return undefined;
+}
+
+function initialStatus(enabled: boolean): RunOutputStatus["status"] {
+  return enabled ? "not-run" : "disabled";
+}

package/src/project-run/progress-rendering/presentation.ts

@@ -0,0 +1,189 @@
+import type {
+  CheckExecutionLifecycle,
+  CheckSettledFact,
+  CheckStartedFact
+} from "../check-execution/resolved-checks.ts";
+import {
+  createProgressRenderer,
+  type ProgressClock,
+  type ProgressFeedback,
+  type ProgressOutcomeCounts,
+  type ProgressWriter
+} from "./renderer.ts";
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { OutputStatuses } from "../output-status.ts";
+export interface ProgressRendering {
+  readonly final: (input: ProgressFinalFeedback) => void;
+  readonly lifecycle: CheckExecutionLifecycle;
+  readonly prepared: (totalChecks: number) => void;
+}
+export interface ProgressFinalFeedback {
+  readonly counts: ProgressOutcomeCounts;
+  readonly elapsedMs: number;
+  readonly execution: "cancelled" | "completed";
+}
+export type ProgressWriterFactory = () => ProgressWriter;
+
+export interface ProgressRefreshSchedule {
+  cancel(): void;
+}
+
+export interface ProgressRefreshScheduler {
+  schedule(refresh: () => void, intervalMs: number): ProgressRefreshSchedule;
+}
+
+export interface ProgressRenderingDependencies {
+  readonly clock?: ProgressClock;
+  readonly refreshScheduler?: ProgressRefreshScheduler;
+  readonly writerFactory?: ProgressWriterFactory;
+}
+
+const PROGRESS_REFRESH_INTERVAL_MS = 5_000;
+
+const defaultProgressRefreshScheduler: ProgressRefreshScheduler = Object.freeze({
+  schedule: (refresh: () => void, intervalMs: number) => {
+    const interval = setInterval(refresh, intervalMs);
+    interval.unref();
+    return Object.freeze({ cancel: () => clearInterval(interval) });
+  }
+});
+
+/** Owns progress writer lifecycle and rendering; failed writers are permanently muted. */
+export function createProgressRendering(
+  configuration: ProjectOutputs["progressRendering"],
+  statuses: OutputStatuses,
+  dependencies: ProgressRenderingDependencies = {}
+): ProgressRendering {
+  if (!configuration.enabled) return inertProgressRendering();
+  let failed = false;
+  const runningCheckIds = new Set<string>();
+  let renderer: ReturnType<typeof createProgressRenderer> | undefined;
+  let refreshSchedule: ProgressRefreshSchedule | undefined;
+
+  const failRendering = (): void => {
+    if (failed) return;
+    failed = true;
+    const activeSchedule = refreshSchedule;
+    refreshSchedule = undefined;
+    try {
+      activeSchedule?.cancel();
+    } catch {
+      // The output is already failed; a scheduler cleanup fault must not reach Check execution.
+    }
+    statuses.failed("progressRendering");
+  };
+
+  const stopRefresh = (): void => {
+    const activeSchedule = refreshSchedule;
+    refreshSchedule = undefined;
+    try {
+      activeSchedule?.cancel();
+    } catch {
+      failRendering();
+    }
+  };
+
+  const render = (feedback: ProgressFeedback): void => {
+    if (failed) return;
+    try {
+      renderer ??= createProgressRenderer(
+        (dependencies.writerFactory ?? defaultProgressWriter)(),
+        dependencies.clock
+      );
+      renderer.render(feedback);
+      if (feedback.kind === "final") {
+        statuses.succeeded("progressRendering");
+      }
+    } catch {
+      failRendering();
+    }
+  };
+
+  const refresh = (): void => {
+    if (failed) return;
+    try {
+      renderer?.refresh();
+    } catch {
+      failRendering();
+    }
+  };
+
+  const startRefresh = (): void => {
+    if (
+      failed ||
+      refreshSchedule !== undefined ||
+      runningCheckIds.size === 0 ||
+      renderer?.refreshesRunningRegion !== true
+    ) {
+      return;
+    }
+    try {
+      refreshSchedule = (dependencies.refreshScheduler ?? defaultProgressRefreshScheduler).schedule(
+        refresh,
+        PROGRESS_REFRESH_INTERVAL_MS
+      );
+    } catch {
+      failRendering();
+    }
+  };
+
+  return Object.freeze({
+    prepared: (totalChecks: number) => render(Object.freeze({ kind: "prepared", totalChecks })),
+    lifecycle: Object.freeze({
+      settled: (fact: CheckSettledFact) => {
+        render(
+          Object.freeze({
+            kind: "settled",
+            checkId: fact.checkId,
+            displayName: fact.displayName,
+            durationMs: fact.durationMs,
+            messages: fact.messages,
+            outcome: fact.outcome,
+            visibility: fact.visibility
+          })
+        );
+        runningCheckIds.delete(fact.checkId);
+        if (runningCheckIds.size === 0) stopRefresh();
+      },
+      started: (fact: CheckStartedFact) => {
+        runningCheckIds.add(fact.checkId);
+        render(
+          Object.freeze({ kind: "started", checkId: fact.checkId, displayName: fact.displayName })
+        );
+        startRefresh();
+      }
+    }),
+    final: (input: ProgressFinalFeedback) => {
+      stopRefresh();
+      render(
+        Object.freeze({
+          kind: "final",
+          counts: input.counts,
+          elapsedMs: input.elapsedMs,
+          execution: input.execution
+        })
+      );
+    }
+  });
+}
+function inertProgressRendering(): ProgressRendering {
+  const lifecycle = Object.freeze({
+    settled: (_fact: CheckSettledFact): void => undefined,
+    started: (_fact: CheckStartedFact): void => undefined
+  });
+  return Object.freeze({
+    prepared: (_totalChecks: number): void => undefined,
+    lifecycle,
+    final: (_input: ProgressFinalFeedback): void => undefined
+  });
+}
+function defaultProgressWriter(): ProgressWriter {
+  return Object.freeze({
+    color: process.stdout.isTTY === true && process.env.NO_COLOR === undefined,
+    isTTY: process.stdout.isTTY === true,
+    term: process.env.TERM,
+    write: (content: string) => {
+      process.stdout.write(content);
+    }
+  });
+}