@zxyycom/vibe-check 0.0.1

package/src/project-run/progress-rendering/renderer-formatting.ts

@@ -0,0 +1,141 @@
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { ProgressFeedback, ProgressOutcomeCounts } from "./renderer.ts";
+
+const COLOR = Object.freeze({
+  error: "\u001B[31m",
+  info: "\u001B[36m",
+  reset: "\u001B[0m",
+  warning: "\u001B[33m"
+});
+
+const NAMED_CONTROL_ESCAPES: Readonly<Partial<Record<string, string>>> = Object.freeze({
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t"
+});
+
+export function formatRunningRow(
+  input: Readonly<{
+    readonly displayIndex: number;
+    readonly displayName: string;
+    readonly elapsedMs: number | null;
+    readonly totalChecks: number;
+  }>
+): string {
+  const elapsed = input.elapsedMs === null ? "" : ` | ${formatDuration(input.elapsedMs)}`;
+  return `  [${input.displayIndex}/${input.totalChecks}] ${escapeTerminalText(input.displayName)} | running${elapsed}\n`;
+}
+
+export function shouldPresentSettledFeedback(
+  feedback: Extract<ProgressFeedback, { readonly kind: "settled" }>
+): boolean {
+  return (
+    feedback.visibility !== "attention" ||
+    feedback.outcome.status !== "passed" ||
+    feedback.messages.length > 0
+  );
+}
+
+export function formatSettledBlock(
+  input: Readonly<{
+    readonly completionOrdinal: number;
+    readonly displayName: string;
+    readonly durationMs: number | null;
+    readonly messages: readonly CheckMessage[];
+    readonly outcome: CheckOutcome;
+    readonly totalChecks: number;
+    readonly usesColor: boolean;
+  }>
+): string {
+  const status = statusForOutcome(input.outcome);
+  const reason = reasonForOutcome(input.outcome);
+  const duration = input.durationMs === null ? "not run" : formatDuration(input.durationMs);
+  const reasonSuffix = reason === undefined ? "" : ` | ${escapeTerminalText(reason)}`;
+  const row = `  [${input.completionOrdinal}/${input.totalChecks}] ${escapeTerminalText(input.displayName)} | ${status} | ${duration}${reasonSuffix}\n`;
+  return `${row}${input.messages.map((message) => formatMessage(message, input.usesColor)).join("")}`;
+}
+
+export function formatFinalSummary(
+  input: Extract<ProgressFeedback, { readonly kind: "final" }>
+): string {
+  return [
+    "",
+    "Execution summary:",
+    `  execution: ${input.execution}`,
+    `  total checks: ${totalChecks(input.counts)}`,
+    `  passed: ${input.counts.passed}`,
+    `  failed: ${input.counts.failed}`,
+    `  not applicable: ${input.counts.notApplicable}`,
+    `  unavailable: ${input.counts.unavailable}`,
+    `  elapsed: ${formatDuration(input.elapsedMs)}`,
+    ""
+  ].join("\n");
+}
+
+function formatMessage(message: CheckMessage, usesColor: boolean): string {
+  const label = colorMessageLevel(message.level, usesColor);
+  return `    [${label}] ${escapeTerminalText(message.message)}\n`;
+}
+
+function totalChecks(counts: ProgressOutcomeCounts): number {
+  return counts.passed + counts.failed + counts.notApplicable + counts.unavailable;
+}
+
+function statusForOutcome(outcome: CheckOutcome): ProgressStatus {
+  switch (outcome.status) {
+    case "passed":
+    case "failed":
+      return outcome.status;
+    case "not-applicable":
+      return "not-applicable";
+    case "unavailable":
+      return "unavailable";
+  }
+}
+
+function reasonForOutcome(outcome: CheckOutcome): string | undefined {
+  return outcome.status === "passed" || outcome.status === "failed"
+    ? undefined
+    : outcome.reason?.code;
+}
+
+/** Human-only fields must not control the terminal that presents them. */
+function escapeTerminalText(value: string): string {
+  let escaped = "";
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    const namedEscape = NAMED_CONTROL_ESCAPES[character];
+    if (namedEscape !== undefined) {
+      escaped += namedEscape;
+      continue;
+    }
+    escaped += isTerminalControl(codePoint)
+      ? `\\u${codePoint.toString(16).padStart(4, "0").toUpperCase()}`
+      : character;
+  }
+  return escaped;
+}
+
+function isTerminalControl(codePoint: number): boolean {
+  return (
+    codePoint <= 0x1f ||
+    (codePoint >= 0x7f && codePoint <= 0x9f) ||
+    codePoint === 0x2028 ||
+    codePoint === 0x2029
+  );
+}
+
+function colorMessageLevel(level: CheckMessage["level"], usesColor: boolean): string {
+  if (!usesColor) return level;
+  return `${COLOR[level]}${level}${COLOR.reset}`;
+}
+
+type ProgressStatus = CheckOutcome["status"];
+
+function formatDuration(durationMs: number): string {
+  if (durationMs < 1_000) {
+    return `${Number.isInteger(durationMs) ? durationMs : Number(durationMs.toFixed(1))}ms`;
+  }
+  const seconds = durationMs / 1_000;
+  return `${Number.isInteger(seconds) ? seconds : Number(seconds.toFixed(1))}s`;
+}

package/src/project-run/progress-rendering/renderer-lifecycle.ts

@@ -0,0 +1,152 @@
+import type {
+  ProgressClock,
+  ProgressFeedback,
+  ProgressRenderer,
+  ProgressWriter
+} from "./renderer.ts";
+import {
+  formatFinalSummary,
+  formatRunningRow,
+  formatSettledBlock,
+  shouldPresentSettledFeedback
+} from "./renderer-formatting.ts";
+
+interface RunningCheck {
+  readonly checkId: string;
+  readonly displayName: string;
+  readonly startedAtMs: number;
+  elapsedMs: number | null;
+}
+
+/** Maintains the mutable lifecycle state and the TTY-only running terminal region. */
+export class ProgressRendererController implements ProgressRenderer {
+  readonly refreshesRunningRegion: boolean;
+
+  private readonly clock: ProgressClock;
+  private readonly writer: ProgressWriter;
+  private completedCount = 0;
+  private preparedTotal: number | undefined;
+  private renderedRunningRows = 0;
+  private readonly running: RunningCheck[] = [];
+  private readonly usesColor: boolean;
+
+  constructor(writer: ProgressWriter, clock: ProgressClock) {
+    this.writer = writer;
+    this.clock = clock;
+    this.refreshesRunningRegion = writer.isTTY && writer.term?.toLowerCase() !== "dumb";
+    this.usesColor = this.refreshesRunningRegion && writer.color;
+  }
+
+  refresh(): void {
+    if (!this.refreshesRunningRegion || this.running.length === 0) return;
+    this.requirePrepared();
+    this.eraseRunningRegion();
+    this.updateRunningDurations(this.clock.now());
+    this.redrawRunningRegion();
+  }
+
+  render(feedback: ProgressFeedback): void {
+    switch (feedback.kind) {
+      case "prepared":
+        this.prepare(feedback.totalChecks);
+        return;
+      case "started":
+        this.start(feedback);
+        return;
+      case "settled":
+        this.settle(feedback);
+        return;
+      case "final":
+        this.finish(feedback);
+    }
+  }
+
+  private prepare(totalChecks: number): void {
+    if (this.preparedTotal !== undefined) throw new Error("Progress feedback was prepared twice");
+    this.preparedTotal = totalChecks;
+    this.writer.write(`Vibe Check\ntotal ${totalChecks} checks\n\nChecks:\n`);
+  }
+
+  private start(feedback: Extract<ProgressFeedback, { readonly kind: "started" }>): void {
+    if (!this.refreshesRunningRegion) return;
+    this.requirePrepared();
+    this.eraseRunningRegion();
+    this.running.push({
+      checkId: feedback.checkId,
+      displayName: feedback.displayName,
+      elapsedMs: null,
+      startedAtMs: this.clock.now()
+    });
+    this.redrawRunningRegion();
+  }
+
+  private settle(feedback: Extract<ProgressFeedback, { readonly kind: "settled" }>): void {
+    const totalChecks = this.requirePrepared();
+    if (this.refreshesRunningRegion) this.eraseRunningRegion();
+    this.completedCount += 1;
+    this.removeRunningCheck(feedback.checkId);
+    if (shouldPresentSettledFeedback(feedback)) {
+      this.writer.write(
+        formatSettledBlock({
+          completionOrdinal: this.completedCount,
+          displayName: feedback.displayName,
+          durationMs: feedback.durationMs,
+          messages: feedback.messages,
+          outcome: feedback.outcome,
+          totalChecks,
+          usesColor: this.usesColor
+        })
+      );
+    }
+    if (this.refreshesRunningRegion) this.redrawRunningRegion();
+  }
+
+  private finish(feedback: Extract<ProgressFeedback, { readonly kind: "final" }>): void {
+    this.requirePrepared();
+    if (this.running.length > 0) {
+      throw new Error("Progress feedback finalized while Checks are still running");
+    }
+    this.writer.write(formatFinalSummary(feedback));
+  }
+
+  private eraseRunningRegion(): void {
+    for (let index = 0; index < this.renderedRunningRows; index += 1) {
+      this.writer.write("\u001B[1A\u001B[2K");
+    }
+    this.renderedRunningRows = 0;
+  }
+
+  private redrawRunningRegion(): void {
+    const totalChecks = this.requirePrepared();
+    for (const [index, check] of this.running.entries()) {
+      this.writer.write(
+        formatRunningRow({
+          displayIndex: this.completedCount + index + 1,
+          displayName: check.displayName,
+          elapsedMs: check.elapsedMs,
+          totalChecks
+        })
+      );
+    }
+    this.renderedRunningRows = this.running.length;
+  }
+
+  private removeRunningCheck(checkId: string): void {
+    const index = this.running.findIndex((check) => check.checkId === checkId);
+    if (index >= 0) this.running.splice(index, 1);
+  }
+
+  private updateRunningDurations(refreshedAtMs: number): void {
+    for (const check of this.running) {
+      const elapsedMs = refreshedAtMs - check.startedAtMs;
+      check.elapsedMs = Number.isFinite(elapsedMs) && elapsedMs >= 0 ? elapsedMs : 0;
+    }
+  }
+
+  private requirePrepared(): number {
+    if (this.preparedTotal === undefined) {
+      throw new Error("Progress feedback arrived before preparation");
+    }
+    return this.preparedTotal;
+  }
+}

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

@@ -0,0 +1,68 @@
+import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import { ProgressRendererController } from "./renderer-lifecycle.ts";
+
+export interface ProgressWriter {
+  readonly color: boolean;
+  readonly isTTY: boolean;
+  readonly term: string | undefined;
+  write(content: string): void;
+}
+
+export type ProgressFeedback = Readonly<
+  | {
+      readonly kind: "prepared";
+      readonly totalChecks: number;
+    }
+  | {
+      readonly kind: "started";
+      readonly checkId: string;
+      readonly displayName: string;
+    }
+  | {
+      readonly kind: "settled";
+      readonly checkId: string;
+      readonly displayName: string;
+      readonly outcome: CheckOutcome;
+      readonly durationMs: number | null;
+      readonly visibility: CheckVisibility;
+      readonly messages: readonly CheckMessage[];
+    }
+  | {
+      readonly kind: "final";
+      readonly execution: "cancelled" | "completed";
+      readonly counts: ProgressOutcomeCounts;
+      readonly elapsedMs: number;
+    }
+>;
+
+export interface ProgressOutcomeCounts {
+  readonly failed: number;
+  readonly notApplicable: number;
+  readonly passed: number;
+  readonly unavailable: number;
+}
+
+export interface ProgressRenderer {
+  refresh(): void;
+  readonly refreshesRunningRegion: boolean;
+  render(feedback: ProgressFeedback): void;
+}
+
+export interface ProgressClock {
+  now(): number;
+}
+
+const SYSTEM_PROGRESS_CLOCK: ProgressClock = Object.freeze({ now: () => performance.now() });
+
+/** Product-private lifecycle presentation with one owner for feedback and its writer. */
+export function createProgressRenderer(
+  writer: ProgressWriter,
+  clock: ProgressClock = SYSTEM_PROGRESS_CLOCK
+): ProgressRenderer {
+  const controller = new ProgressRendererController(writer, clock);
+  return Object.freeze({
+    refreshesRunningRegion: controller.refreshesRunningRegion,
+    refresh: (): void => controller.refresh(),
+    render: (feedback: ProgressFeedback): void => controller.render(feedback)
+  });
+}

package/src/project-run/project-context.ts

@@ -0,0 +1,11 @@
+import type { CheckProjectContext } from "../check/check.ts";
+import type { RunControls } from "./controls/contract.ts";
+/** Materializes only invocation-wide callback input; Check-local options own domain configuration. */
+export function createProjectContext(
+  input: Readonly<{ readonly controls: RunControls; readonly root: string }>
+): CheckProjectContext {
+  return Object.freeze({
+    flags: Object.freeze([...(input.controls.flags ?? [])]),
+    root: input.root
+  });
+}

package/src/project-run/result.ts

@@ -0,0 +1,175 @@
+import type {
+  DefinitionWarning,
+  ProjectDefinitionDiagnostic
+} from "../project-definition/project-definition.ts";
+import type { RunControlDiagnostic } from "./controls/validation-result.ts";
+import type { CheckAggregate, RunControls } from "./controls/contract.ts";
+import type { CheckMessageLevel } from "../check/check.ts";
+import type { CoreSnapshot } from "../check-settlement/facts.ts";
+import type { RunOutputStatuses } from "./output-status.ts";
+export type RunDiagnostic = Readonly<{
+  readonly code: "task-graph-invalid" | "task-engine-failed" | "publication-model-failed";
+}>;
+export type CheckDuration = Readonly<{
+  readonly checkId: string;
+  readonly durationMs: number | null;
+}>;
+export interface CheckRunMessage {
+  readonly checkId: string;
+  readonly level: CheckMessageLevel;
+  readonly code: string;
+  readonly message: string;
+}
+export interface RunResultFacts {
+  readonly aggregate: CheckAggregate | null;
+  readonly checkDurations: readonly CheckDuration[];
+  readonly checkMessages: readonly CheckRunMessage[];
+  readonly snapshot: CoreSnapshot;
+}
+/** 一次 Project Run 的可判别结果；output failure 保留已结算 facts。 */
+export type RunResult = Readonly<
+  | {
+      readonly kind: "configuration";
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly diagnostic: ProjectDefinitionDiagnostic | RunControlDiagnostic;
+    }
+  | {
+      readonly kind: "planning";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly diagnostic: RunDiagnostic;
+      readonly outputs: RunOutputStatuses;
+    }
+  | {
+      readonly kind: "cancelled";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly outputs: RunOutputStatuses;
+      readonly phase: "pre-work" | "planning";
+    }
+  | {
+      readonly kind: "cancelled";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly outputs: RunOutputStatuses;
+      readonly phase: "execution";
+      readonly checkDurations: readonly CheckDuration[];
+      readonly checkMessages: readonly CheckRunMessage[];
+      readonly snapshot: CoreSnapshot;
+    }
+  | ({
+      readonly kind: "completed";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly outputs: RunOutputStatuses;
+    } & RunResultFacts)
+  | {
+      readonly kind: "execution";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly diagnostic: RunDiagnostic;
+      readonly outputs: RunOutputStatuses;
+    }
+  | ({
+      readonly kind: "output";
+      readonly declarativeFingerprint: string;
+      readonly definitionWarnings: readonly DefinitionWarning[];
+      readonly diagnostic: Readonly<{
+        readonly code:
+          | "machine-publication-failed"
+          | "progress-rendering-failed"
+          | "diagnostic-logging-failed";
+      }>;
+      readonly outputs: RunOutputStatuses;
+    } & RunResultFacts)
+>;
+
+/** Any Run result produced after controls and Definition validation have completed. */
+export type NonConfigurationRunResult = Exclude<RunResult, { readonly kind: "configuration" }>;
+
+type OutputRunResult = Extract<RunResult, { readonly kind: "output" }>;
+
+export function outputFailure(
+  declarativeFingerprint: string,
+  definitionWarnings: readonly DefinitionWarning[],
+  outputs: RunOutputStatuses,
+  output: keyof RunOutputStatuses,
+  facts: RunResultFacts
+): OutputRunResult {
+  return Object.freeze({
+    kind: "output",
+    declarativeFingerprint,
+    definitionWarnings,
+    diagnostic: Object.freeze({ code: outputDiagnosticCode(output) }),
+    outputs,
+    ...facts
+  });
+}
+function outputDiagnosticCode(
+  output: keyof RunOutputStatuses
+): Extract<RunResult, { readonly kind: "output" }>["diagnostic"]["code"] {
+  switch (output) {
+    case "machinePublication":
+      return "machine-publication-failed";
+    case "progressRendering":
+      return "progress-rendering-failed";
+    case "diagnosticLogging":
+      return "diagnostic-logging-failed";
+  }
+}
+
+export function isCancelled(controls: RunControls): boolean {
+  return controls.signal?.aborted === true;
+}
+export function planning(
+  declarativeFingerprint: string,
+  definitionWarnings: readonly DefinitionWarning[],
+  outputs: RunOutputStatuses,
+  code: Extract<RunDiagnostic["code"], "task-graph-invalid">
+): Extract<NonConfigurationRunResult, { readonly kind: "planning" }> {
+  return Object.freeze({
+    kind: "planning",
+    declarativeFingerprint,
+    definitionWarnings,
+    diagnostic: Object.freeze({ code }),
+    outputs
+  });
+}
+export function preExecutionCancellation(
+  declarativeFingerprint: string,
+  definitionWarnings: readonly DefinitionWarning[],
+  outputs: RunOutputStatuses,
+  phase: "pre-work" | "planning"
+): Extract<
+  NonConfigurationRunResult,
+  { readonly kind: "cancelled"; readonly phase: "pre-work" | "planning" }
+> {
+  return Object.freeze({
+    kind: "cancelled",
+    declarativeFingerprint,
+    definitionWarnings,
+    outputs,
+    phase
+  });
+}
+export function executionCancellation(
+  input: Readonly<{
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly outputs: RunOutputStatuses;
+    readonly snapshot: CoreSnapshot;
+  }>
+): Extract<NonConfigurationRunResult, { readonly kind: "cancelled"; readonly phase: "execution" }> {
+  return Object.freeze({
+    kind: "cancelled",
+    declarativeFingerprint: input.declarativeFingerprint,
+    definitionWarnings: input.definitionWarnings,
+    outputs: input.outputs,
+    phase: "execution",
+    checkDurations: input.checkDurations,
+    checkMessages: input.checkMessages,
+    snapshot: input.snapshot
+  });
+}

package/src/project-run/run.ts

@@ -0,0 +1,50 @@
+import type { ProjectDefinition } from "../project-definition/project-definition.ts";
+import type { RunControls } from "./controls/contract.ts";
+import { validateProjectDefinition } from "../project-definition/project-definition-validation.ts";
+import { validateRunControls } from "./controls/validation.ts";
+import { executeValidatedRun } from "./invocation.ts";
+import type { RunResult } from "./result.ts";
+
+export type { RunOutputStatus, RunOutputStatuses } from "./output-status.ts";
+export type { RunDiagnostic, RunResult } from "./result.ts";
+
+/**
+ * 在调用方的 Bun runtime 中执行一个由项目拥有的 Project Definition。
+ *
+ * @param definition - Project Definition input；{@link defineConfig} 补齐 defaults，run 在 invocation 前验证。
+ * @param controls - 本次 invocation context 与 outputs 使用的闭合控制值。
+ * @returns ordinary configuration、planning、execution、cancellation 与 output failures 通过 `RunResult`
+ * 返回；调用方先按 `kind` narrow。
+ * @remarks Definition validation 关闭 authoring grammar；可选 Check preflight 组成 invocation execution barrier，
+ * 并在 execution callback、dependency resolver 或 scanner 前完成。`output` branch 同时提供完整 final
+ * snapshot 与 output failure diagnostic。
+ */
+export async function run(
+  definition: ProjectDefinition,
+  controls?: RunControls
+): Promise<RunResult>;
+export async function run(definition: unknown, controls?: unknown): Promise<RunResult>;
+export async function run(definition: unknown, controls: unknown = {}): Promise<RunResult> {
+  const validatedDefinition = validateProjectDefinition(definition);
+  if (!validatedDefinition.ok) {
+    return Object.freeze({
+      kind: "configuration",
+      definitionWarnings: Object.freeze([]),
+      diagnostic: validatedDefinition.error
+    });
+  }
+  const validatedControls = validateRunControls(controls);
+  if (!validatedControls.ok) {
+    return Object.freeze({
+      kind: "configuration",
+      definitionWarnings: Object.freeze([]),
+      diagnostic: validatedControls.error
+    });
+  }
+
+  return executeValidatedRun(
+    validatedDefinition.value,
+    validatedControls.value,
+    validatedDefinition.warnings
+  );
+}