@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/project-run/invocation/scheduler.ts

@@ -0,0 +1,75 @@
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { PreparedAdmissionStrategy } from "../admission-strategy-provider/prepared-admission-strategy.ts";
+import { executeResolvedChecks } from "../check-execution/resolved-checks.ts";
+import type { ResolvedCheckExecution } from "../check-execution/resolved-execution-result.ts";
+import type { Invocation } from "./run.ts";
+import type { NonConfigurationRunResult } from "../result.ts";
+
+export type SchedulerExecution =
+  | ResolvedCheckExecution
+  | Extract<NonConfigurationRunResult, { readonly kind: "execution" }>;
+
+type SchedulerAdapterInput = Readonly<{
+  readonly invocation: Invocation;
+  readonly preparedStrategy: PreparedAdmissionStrategy;
+  readonly project: CheckProjectContext;
+}>;
+
+/** Bridges one prepared invocation to resolved Check execution and contains task-engine faults. */
+export async function executeScheduler(input: SchedulerAdapterInput): Promise<SchedulerExecution> {
+  const { invocation, preparedStrategy } = input;
+  try {
+    const performanceDiagnostics = schedulerPerformanceDiagnostics(input);
+    return await executeResolvedChecks({
+      admissionPolicy: preparedStrategy.admissionPolicy,
+      checks: invocation.normalized.checks,
+      clock: invocation.clock,
+      diagnosticLogger: invocation.diagnosticLogging.core,
+      ...(invocation.diagnosticLoggingEnabled
+        ? { schedulerDiagnosticLogger: invocation.diagnosticLogging.scheduler }
+        : {}),
+      schedulerPerformanceDiagnostics: performanceDiagnostics,
+      schedulerMeasurementHooks: invocation.normalized.scheduler.measurementHooks,
+      onSchedulerMeasurementHookFailure: () => invocation.outputs.failed("measurementHooks"),
+      onSchedulerMeasurementHooksSettled: () => invocation.outputs.succeeded("measurementHooks"),
+      maxParallel: invocation.normalized.declarative.scheduler.maxParallel,
+      resourceCapacities: invocation.normalized.declarative.scheduler.resourceCapacities,
+      invocationId: invocation.invocationId,
+      lifecycle: invocation.progressRendering.lifecycle,
+      paths: invocation.paths,
+      project: input.project,
+      signal: invocation.controls.signal
+    });
+  } catch {
+    return taskEngineFailure(invocation);
+  }
+}
+
+function schedulerPerformanceDiagnostics(input: SchedulerAdapterInput) {
+  const { invocation, preparedStrategy } = input;
+  const shouldCollectSchedulerPerformanceDiagnostics =
+    invocation.diagnosticLoggingEnabled ||
+    invocation.normalized.scheduler.measurementHooks.length > 0 ||
+    preparedStrategy.admissionPolicy.requiresMeasurement === true ||
+    preparedStrategy.requiresTerminalMeasurement;
+  if (!shouldCollectSchedulerPerformanceDiagnostics) return undefined;
+  return Object.freeze({
+    clock: invocation.clock,
+    declarativeFingerprint: invocation.declarativeFingerprint,
+    ...(invocation.diagnosticLoggingEnabled
+      ? { logger: invocation.diagnosticLogging.scheduler }
+      : {})
+  });
+}
+
+function taskEngineFailure(
+  invocation: Invocation
+): Extract<NonConfigurationRunResult, { readonly kind: "execution" }> {
+  return Object.freeze({
+    kind: "execution",
+    declarativeFingerprint: invocation.declarativeFingerprint,
+    definitionWarnings: invocation.definitionWarnings,
+    diagnostic: Object.freeze({ code: "task-engine-failed" }),
+    outputs: invocation.outputs.value()
+  });
+}

package/src/project-run/{output-configuration.ts → outputs/configuration.ts}

@@ -1,18 +1,19 @@
 import type {
   ProjectDefinition,
-  ProjectOutputs
-} from "../project-definition/project-definition.ts";
-import type { RunControls } from "./controls/contract.ts";
+  ResolvedProjectOutputs
+} from "../../project-definition/project-definition.ts";
+import { resolveProgressRenderingOutput } from "../../project-definition/output-defaults.ts";
+import type { RunControls } from "../controls/contract.ts";
 export function effectiveOutputs(
   definition: ProjectDefinition,
   controls: RunControls
-): ProjectOutputs {
+): ResolvedProjectOutputs {
   return Object.freeze({
     machinePublication: Object.freeze({
       ...definition.outputs.machinePublication,
       ...controls.outputs?.machinePublication
     }),
-    progressRendering: Object.freeze({
+    progressRendering: resolveProgressRenderingOutput({
       ...definition.outputs.progressRendering,
       ...controls.outputs?.progressRendering
     }),

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

@@ -0,0 +1,161 @@
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import { DIAGNOSTIC_CHANNELS, type DiagnosticChannel } from "../diagnostic-logging/logger.ts";
+
+/** 一项 Run-owned terminal output 或 measurement participant 的最终状态 readback。 */
+export interface RunOutputStatus {
+  /** effective configuration 是否启用该 participant；`false` 时 status 必为 `disabled`。 */
+  readonly enabled: boolean;
+  /** `disabled` 为未启用；`not-run` 为启用但未到达完成；`succeeded` 为完成，`failed` 为其 own I/O 或 hook failure。 */
+  readonly status: "disabled" | "failed" | "not-run" | "succeeded";
+}
+
+/** Product-owned 人读 diagnostic channel；即使 setup 失败也保留其 file readback。 */
+export interface RunDiagnosticLoggingChannelStatus extends RunOutputStatus {
+  /**
+   * 相对 effective project root 的 target readback；跨卷时可为 absolute path。disabled channel 为 `null`，
+   * enabled channel 即使 setup 失败也保留预先计算的 path。
+   */
+  readonly file: string | null;
+}
+
+/** diagnostic logging aggregate 及其各 owner channel 的最终状态 readback。 */
+export interface RunDiagnosticLoggingOutputStatus extends RunOutputStatus {
+  /** aggregate status 及每个 owner channel 的独立 readback；partial failure 可由此定位。 */
+  readonly channels: Readonly<Record<DiagnosticChannel, RunDiagnosticLoggingChannelStatus>>;
+}
+
+/** 配置有效后四个 terminal output participant 的独立最终状态。 */
+export interface RunOutputStatuses {
+  /** `run.json` 与 `records.ndjson` canonical publication 的状态。 */
+  readonly machinePublication: RunOutputStatus;
+  /** terminal progress 与可选 progress log tee 的状态。 */
+  readonly progressRendering: RunOutputStatus;
+  /** core 与 scheduler diagnostic channels 的 aggregate 状态。 */
+  readonly diagnosticLogging: RunDiagnosticLoggingOutputStatus;
+  /**
+   * Definition generic Hooks 与 prepared custom strategy 的 optional `complete` 所形成的 terminal participant
+   * 状态；它不能由 RunControls 注入或覆盖。
+   */
+  readonly measurementHooks: RunOutputStatus;
+}
+
+export interface OutputStatuses {
+  /** Enables a runtime-only terminal participant after successful preparation. */
+  readonly enableMeasurementHooks: () => void;
+  /** A diagnostic channel failure is isolated but updates the aggregate diagnostic output. */
+  readonly failedDiagnosticChannel: (channel: DiagnosticChannel) => void;
+  readonly failed: (output: keyof RunOutputStatuses) => void;
+  readonly succeededDiagnosticChannel: (channel: DiagnosticChannel) => void;
+  readonly succeeded: (output: keyof RunOutputStatuses) => void;
+  readonly value: () => RunOutputStatuses;
+}
+
+export function createOutputStatuses(
+  configuration: ProjectOutputs,
+  diagnosticLoggingFiles: Readonly<Record<DiagnosticChannel, string | null>>,
+  initialMeasurementHooksEnabled: boolean
+): OutputStatuses {
+  let measurementHooksEnabled = initialMeasurementHooksEnabled;
+  const diagnosticChannelEnabled: Readonly<Record<DiagnosticChannel, boolean>> = Object.freeze({
+    core: configuration.diagnosticLogging.enabled,
+    scheduler: configuration.diagnosticLogging.enabled
+  });
+  const statuses: Record<keyof RunOutputStatuses, RunOutputStatus["status"]> = {
+    machinePublication: initialStatus(configuration.machinePublication.enabled),
+    progressRendering: initialStatus(configuration.progressRendering.enabled),
+    diagnosticLogging: initialStatus(configuration.diagnosticLogging.enabled),
+    measurementHooks: initialStatus(measurementHooksEnabled)
+  };
+  const diagnosticChannelStatuses: Record<DiagnosticChannel, RunOutputStatus["status"]> = {
+    core: initialStatus(diagnosticChannelEnabled.core),
+    scheduler: initialStatus(diagnosticChannelEnabled.scheduler)
+  };
+  const enabled = (output: keyof RunOutputStatuses): boolean =>
+    output === "measurementHooks" ? measurementHooksEnabled : configuration[output].enabled;
+  const refreshDiagnosticAggregate = (): void => {
+    const enabledStatuses = DIAGNOSTIC_CHANNELS.filter(
+      (channel) => diagnosticChannelEnabled[channel]
+    ).map((channel) => diagnosticChannelStatuses[channel]);
+    if (enabledStatuses.includes("failed")) {
+      statuses.diagnosticLogging = "failed";
+      return;
+    }
+    if (enabledStatuses.every((status) => status === "succeeded")) {
+      statuses.diagnosticLogging = "succeeded";
+      return;
+    }
+    statuses.diagnosticLogging = enabledStatuses.every((status) => status === "disabled")
+      ? "disabled"
+      : "not-run";
+  };
+  return Object.freeze({
+    enableMeasurementHooks: () => {
+      if (measurementHooksEnabled) return;
+      measurementHooksEnabled = true;
+      statuses.measurementHooks = "not-run";
+    },
+    failedDiagnosticChannel: (channel: DiagnosticChannel) => {
+      if (!diagnosticChannelEnabled[channel]) return;
+      diagnosticChannelStatuses[channel] = "failed";
+      refreshDiagnosticAggregate();
+    },
+    failed: (output: keyof RunOutputStatuses) => {
+      if (enabled(output)) statuses[output] = "failed";
+    },
+    succeededDiagnosticChannel: (channel: DiagnosticChannel) => {
+      if (!diagnosticChannelEnabled[channel] || diagnosticChannelStatuses[channel] === "failed")
+        return;
+      diagnosticChannelStatuses[channel] = "succeeded";
+      refreshDiagnosticAggregate();
+    },
+    succeeded: (output: keyof RunOutputStatuses) => {
+      if (enabled(output) && statuses[output] !== "failed") 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({
+          channels: Object.freeze({
+            core: diagnosticChannelValue("core"),
+            scheduler: diagnosticChannelValue("scheduler")
+          }),
+          enabled: configuration.diagnosticLogging.enabled,
+          status: statuses.diagnosticLogging
+        }),
+        measurementHooks: Object.freeze({
+          enabled: measurementHooksEnabled,
+          status: statuses.measurementHooks
+        })
+      })
+  });
+
+  function diagnosticChannelValue(channel: DiagnosticChannel): RunDiagnosticLoggingChannelStatus {
+    return Object.freeze({
+      enabled: diagnosticChannelEnabled[channel],
+      file: diagnosticLoggingFiles[channel],
+      status: diagnosticChannelStatuses[channel]
+    });
+  }
+}
+
+export function failedOutput(statuses: RunOutputStatuses): keyof RunOutputStatuses | undefined {
+  for (const output of [
+    "progressRendering",
+    "machinePublication",
+    "diagnosticLogging",
+    "measurementHooks"
+  ] 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

@@ -1,8 +1,11 @@
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
 import type {
   CheckExecutionLifecycle,
   CheckSettledFact,
   CheckStartedFact
-} from "../check-execution/resolved-checks.ts";
+} from "../check-execution/lifecycle.ts";
 import {
   createProgressRenderer,
   type ProgressClock,
@@ -10,9 +13,11 @@ import {
   type ProgressOutcomeCounts,
   type ProgressWriter
 } from "./renderer.ts";
-import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
-import type { OutputStatuses } from "../output-status.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
+import type { OutputStatuses } from "../outputs/status.ts";
 export interface ProgressRendering {
+  /** Closes only an already-created file tee; it never creates a writer after pre-work termination. */
+  readonly close: () => void;
   readonly final: (input: ProgressFinalFeedback) => void;
   readonly lifecycle: CheckExecutionLifecycle;
   readonly prepared: (totalChecks: number) => void;
@@ -34,6 +39,8 @@ export interface ProgressRefreshScheduler {
 
 export interface ProgressRenderingDependencies {
   readonly clock?: ProgressClock;
+  /** Caller-owned exact progress transcript target for this invocation; `null` keeps terminal-only output. */
+  readonly file?: string | null;
   readonly refreshScheduler?: ProgressRefreshScheduler;
   readonly writerFactory?: ProgressWriterFactory;
 }
@@ -48,21 +55,23 @@ const defaultProgressRefreshScheduler: ProgressRefreshScheduler = Object.freeze(
   }
 });
 
-/** Owns progress writer lifecycle and rendering; failed writers are permanently muted. */
+/** Owns terminal progress and its optional file tee; terminal output survives a file-only failure. */
 export function createProgressRendering(
-  configuration: ProjectOutputs["progressRendering"],
+  configuration: ResolvedProgressRenderingOutput,
   statuses: OutputStatuses,
   dependencies: ProgressRenderingDependencies = {}
 ): ProgressRendering {
   if (!configuration.enabled) return inertProgressRendering();
-  let failed = false;
+  let terminalFailed = false;
+  let closed = false;
   const runningCheckIds = new Set<string>();
   let renderer: ReturnType<typeof createProgressRenderer> | undefined;
+  let writer: ProgressWriter | undefined;
   let refreshSchedule: ProgressRefreshSchedule | undefined;
 
-  const failRendering = (): void => {
-    if (failed) return;
-    failed = true;
+  const failTerminalRendering = (): void => {
+    if (terminalFailed) return;
+    terminalFailed = true;
     const activeSchedule = refreshSchedule;
     refreshSchedule = undefined;
     try {
@@ -79,38 +88,43 @@ export function createProgressRendering(
     try {
       activeSchedule?.cancel();
     } catch {
-      failRendering();
+      failTerminalRendering();
     }
   };
 
+  const createRenderer = (): ReturnType<typeof createProgressRenderer> => {
+    if (renderer !== undefined) return renderer;
+    writer = createProgressTee({
+      file: dependencies.file ?? null,
+      onFileFailure: () => statuses.failed("progressRendering"),
+      terminal: (dependencies.writerFactory ?? defaultProgressWriter)()
+    });
+    renderer = createProgressRenderer(writer, dependencies.clock, configuration);
+    return renderer;
+  };
+
   const render = (feedback: ProgressFeedback): void => {
-    if (failed) return;
+    if (terminalFailed) return;
     try {
-      renderer ??= createProgressRenderer(
-        (dependencies.writerFactory ?? defaultProgressWriter)(),
-        dependencies.clock
-      );
-      renderer.render(feedback);
-      if (feedback.kind === "final") {
-        statuses.succeeded("progressRendering");
-      }
+      createRenderer().render(feedback);
+      if (feedback.kind === "final") statuses.succeeded("progressRendering");
     } catch {
-      failRendering();
+      failTerminalRendering();
     }
   };
 
   const refresh = (): void => {
-    if (failed) return;
+    if (terminalFailed) return;
     try {
       renderer?.refresh();
     } catch {
-      failRendering();
+      failTerminalRendering();
     }
   };
 
   const startRefresh = (): void => {
     if (
-      failed ||
+      terminalFailed ||
       refreshSchedule !== undefined ||
       runningCheckIds.size === 0 ||
       renderer?.refreshesRunningRegion !== true
@@ -123,13 +137,28 @@ export function createProgressRendering(
         PROGRESS_REFRESH_INTERVAL_MS
       );
     } catch {
-      failRendering();
+      failTerminalRendering();
+    }
+  };
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    stopRefresh();
+    if (writer === undefined) return;
+    try {
+      writer.close?.();
+    } catch {
+      // A terminal writer close is an output failure; a tee contains file-only failures itself.
+      statuses.failed("progressRendering");
     }
   };
 
   return Object.freeze({
+    close,
     prepared: (totalChecks: number) => render(Object.freeze({ kind: "prepared", totalChecks })),
     lifecycle: Object.freeze({
+      flagControlCompleted: () => render(Object.freeze({ kind: "flag-control-completed" })),
       settled: (fact: CheckSettledFact) => {
         render(
           Object.freeze({
@@ -139,6 +168,7 @@ export function createProgressRendering(
             durationMs: fact.durationMs,
             messages: fact.messages,
             outcome: fact.outcome,
+            records: fact.records,
             visibility: fact.visibility
           })
         );
@@ -157,21 +187,24 @@ export function createProgressRendering(
       stopRefresh();
       render(
         Object.freeze({
-          kind: "final",
           counts: input.counts,
           elapsedMs: input.elapsedMs,
-          execution: input.execution
+          execution: input.execution,
+          kind: "final"
         })
       );
+      close();
     }
   });
 }
 function inertProgressRendering(): ProgressRendering {
   const lifecycle = Object.freeze({
+    flagControlCompleted: (): void => undefined,
     settled: (_fact: CheckSettledFact): void => undefined,
     started: (_fact: CheckStartedFact): void => undefined
   });
   return Object.freeze({
+    close: (): void => undefined,
     prepared: (_totalChecks: number): void => undefined,
     lifecycle,
     final: (_input: ProgressFinalFeedback): void => undefined
@@ -187,3 +220,62 @@ function defaultProgressWriter(): ProgressWriter {
     }
   });
 }
+
+function createProgressTee(
+  input: Readonly<{
+    readonly file: string | null;
+    readonly onFileFailure: () => void;
+    readonly terminal: ProgressWriter;
+  }>
+): ProgressWriter {
+  if (input.file === null) return input.terminal;
+  let descriptor: number | undefined;
+  let fileFailed = false;
+  let closed = false;
+  const failFile = (): void => {
+    if (fileFailed) return;
+    fileFailed = true;
+    input.onFileFailure();
+  };
+  try {
+    mkdirSync(dirname(input.file), { recursive: true });
+    descriptor = openSync(input.file, "wx");
+  } catch {
+    failFile();
+  }
+  return Object.freeze({
+    close: (): void => {
+      if (closed) return;
+      closed = true;
+      if (descriptor === undefined) return;
+      try {
+        closeSync(descriptor);
+      } catch {
+        failFile();
+      }
+      descriptor = undefined;
+    },
+    color: input.terminal.color,
+    isTTY: input.terminal.isTTY,
+    term: input.terminal.term,
+    write: (content: string): void => {
+      input.terminal.write(content);
+      if (fileFailed || descriptor === undefined) return;
+      try {
+        writeFileBuffer(descriptor, content);
+      } catch {
+        failFile();
+      }
+    }
+  });
+}
+
+function writeFileBuffer(descriptor: number, content: string): void {
+  const bytes = Buffer.from(content, "utf8");
+  let offset = 0;
+  while (offset < bytes.length) {
+    const written = writeSync(descriptor, bytes, offset, bytes.length - offset, null);
+    if (written <= 0) throw new Error("Progress log append made no progress");
+    offset += written;
+  }
+}