@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,8 +1,12 @@
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
 import type {
   CheckExecutionLifecycle,
+  InvocationLifecycle,
   CheckSettledFact,
   CheckStartedFact
-} from "../check-execution/resolved-checks.ts";
+} from "../check-execution/lifecycle.ts";
 import {
   createProgressRenderer,
   type ProgressClock,
@@ -10,12 +14,15 @@ 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;
+  readonly checkLifecycle: CheckExecutionLifecycle;
+  readonly invocationLifecycle: InvocationLifecycle;
+  readonly prepared: (totalChecks: number, quietPassOmissionConfiguredCount: number) => void;
 }
 export interface ProgressFinalFeedback {
   readonly counts: ProgressOutcomeCounts;
@@ -34,6 +41,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;
 }
@@ -44,25 +53,31 @@ const defaultProgressRefreshScheduler: ProgressRefreshScheduler = Object.freeze(
   schedule: (refresh: () => void, intervalMs: number) => {
     const interval = setInterval(refresh, intervalMs);
     interval.unref();
-    return Object.freeze({ cancel: () => clearInterval(interval) });
+    return Object.freeze({
+      cancel: () => {
+        clearInterval(interval);
+      }
+    });
   }
 });
 
-/** 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 +94,45 @@ 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 +145,34 @@ 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({
-    prepared: (totalChecks: number) => render(Object.freeze({ kind: "prepared", totalChecks })),
-    lifecycle: Object.freeze({
+    close,
+    prepared: (totalChecks: number, quietPassOmissionConfiguredCount: number) => {
+      render(Object.freeze({ kind: "prepared", quietPassOmissionConfiguredCount, totalChecks }));
+    },
+    invocationLifecycle: Object.freeze({
+      selectionSettled: () => {
+        render(Object.freeze({ kind: "flag-control-completed" }));
+      }
+    }),
+    checkLifecycle: Object.freeze({
       settled: (fact: CheckSettledFact) => {
         render(
           Object.freeze({
@@ -139,7 +182,8 @@ export function createProgressRendering(
             durationMs: fact.durationMs,
             messages: fact.messages,
             outcome: fact.outcome,
-            visibility: fact.visibility
+            records: fact.records,
+            omitQuietPassedRow: fact.omitQuietPassedRow
           })
         );
         runningCheckIds.delete(fact.checkId);
@@ -148,7 +192,12 @@ export function createProgressRendering(
       started: (fact: CheckStartedFact) => {
         runningCheckIds.add(fact.checkId);
         render(
-          Object.freeze({ kind: "started", checkId: fact.checkId, displayName: fact.displayName })
+          Object.freeze({
+            kind: "started",
+            checkId: fact.checkId,
+            displayName: fact.displayName,
+            omitQuietPassedRow: fact.omitQuietPassedRow
+          })
         );
         startRefresh();
       }
@@ -157,23 +206,29 @@ 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({
+  const invocationLifecycle = Object.freeze({
+    selectionSettled: (): void => undefined
+  });
+  const checkLifecycle = Object.freeze({
     settled: (_fact: CheckSettledFact): void => undefined,
     started: (_fact: CheckStartedFact): void => undefined
   });
   return Object.freeze({
-    prepared: (_totalChecks: number): void => undefined,
-    lifecycle,
+    close: (): void => undefined,
+    prepared: (_totalChecks: number, _quietPassOmissionConfiguredCount: number): void => undefined,
+    checkLifecycle,
+    invocationLifecycle,
     final: (_input: ProgressFinalFeedback): void => undefined
   });
 }
@@ -187,3 +242,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;
+  }
+}

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

@@ -1,4 +1,10 @@
+import { types } from "node:util";
+
 import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
+import { canonicalJsonText } from "../../data-boundary/canonical-data.ts";
+import { FLAG_CONDITION_NOT_MATCHED_CODE } from "../check-execution/flag-controls.ts";
 import type { ProgressFeedback, ProgressOutcomeCounts } from "./renderer.ts";
 
 const COLOR = Object.freeze({
@@ -8,6 +14,8 @@ const COLOR = Object.freeze({
   warning: "\u001B[33m"
 });
 
+const TRUNCATION_MARKER = "… [truncated]";
+
 const NAMED_CONTROL_ESCAPES: Readonly<Partial<Record<string, string>>> = Object.freeze({
   "\n": "\\n",
   "\r": "\\r",
@@ -16,47 +24,86 @@ const NAMED_CONTROL_ESCAPES: Readonly<Partial<Record<string, string>>> = Object.
 
 export function formatRunningRow(
   input: Readonly<{
-    readonly displayIndex: number;
+    readonly displayIndex: number | undefined;
     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`;
+  const ordinal =
+    input.displayIndex === undefined ? "·" : `[${input.displayIndex}/${input.totalChecks}]`;
+  return `  ${ordinal} ${escapeTerminalText(input.displayName)} | running${elapsed}\n`;
 }
 
 export function shouldPresentSettledFeedback(
   feedback: Extract<ProgressFeedback, { readonly kind: "settled" }>
 ): boolean {
   return (
-    feedback.visibility !== "attention" ||
+    !feedback.omitQuietPassedRow ||
     feedback.outcome.status !== "passed" ||
-    feedback.messages.length > 0
+    feedback.messages.length > 0 ||
+    feedback.records.length > 0
+  );
+}
+
+export function isFlagConditionNotMatchedFeedback(
+  feedback: Extract<ProgressFeedback, { readonly kind: "settled" }>
+): boolean {
+  return (
+    feedback.durationMs === null &&
+    feedback.messages.length === 0 &&
+    feedback.records.length === 0 &&
+    feedback.outcome.status === "not-applicable" &&
+    feedback.outcome.reason?.code === FLAG_CONDITION_NOT_MATCHED_CODE
   );
 }
 
+export function formatFlagConditionNotMatchedBlock(
+  displayNames: readonly [string, ...string[]]
+): string {
+  const subject =
+    displayNames.length === 1
+      ? "The following check did not run because the run flags did not match its condition:"
+      : `The following ${displayNames.length} checks did not run because the run flags did not match their conditions:`;
+  return `  ${subject}\n${displayNames
+    .map((displayName) => `    - ${escapeTerminalText(displayName)}\n`)
+    .join("")}`;
+}
+
 export function formatSettledBlock(
   input: Readonly<{
-    readonly completionOrdinal: number;
+    readonly completionOrdinal: number | undefined;
     readonly displayName: string;
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
+    readonly records: readonly CoreRecord[];
     readonly totalChecks: number;
     readonly usesColor: boolean;
+    readonly progressRendering: ResolvedProgressRenderingOutput;
   }>
 ): 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("")}`;
+  const ordinal =
+    input.completionOrdinal === undefined
+      ? "·"
+      : `[${input.completionOrdinal}/${input.totalChecks}]`;
+  const row = `  ${ordinal} ${escapeTerminalText(input.displayName)} | ${status} | ${duration}${reasonSuffix}\n`;
+  const recordPreview = formatRecords(input.records, input.progressRendering);
+  const messagePreview = formatMessages(input.messages, input.usesColor, input.progressRendering);
+  return `${row}${recordPreview}${messagePreview}`;
 }
 
 export function formatFinalSummary(
-  input: Extract<ProgressFeedback, { readonly kind: "final" }>
+  input: Extract<ProgressFeedback, { readonly kind: "final" }> &
+    Readonly<{
+      readonly quietPassOmissionConfiguredCount: number;
+      readonly quietPassOmittedCount: number;
+    }>
 ): string {
   return [
     "",
@@ -67,36 +114,110 @@ export function formatFinalSummary(
     `  failed: ${input.counts.failed}`,
     `  not applicable: ${input.counts.notApplicable}`,
     `  unavailable: ${input.counts.unavailable}`,
+    ...(input.quietPassOmissionConfiguredCount === 0
+      ? []
+      : [`  quiet-pass rows omitted: ${input.quietPassOmittedCount}`]),
     `  elapsed: ${formatDuration(input.elapsedMs)}`,
     ""
   ].join("\n");
 }
 
-function formatMessage(message: CheckMessage, usesColor: boolean): string {
+function formatRecords(
+  records: readonly CoreRecord[],
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  return formatPreview(
+    records,
+    (record) => formatRecord(record, progressRendering),
+    "record",
+    progressRendering.recordPreviewLimit
+  );
+}
+
+function formatMessages(
+  messages: readonly CheckMessage[],
+  usesColor: boolean,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  return formatPreview(
+    messages,
+    (message) => formatMessage(message, usesColor, progressRendering),
+    "message",
+    progressRendering.messagePreviewLimit
+  );
+}
+
+function formatPreview<Item>(
+  items: readonly Item[],
+  formatItem: (item: Item) => string,
+  previewKind: "message" | "record",
+  limit: number
+): string {
+  const preview = items.slice(0, limit);
+  const omittedCount = items.length - preview.length;
+  let renderedPreview = "";
+  // Caller formatters run once in selection order; a throw stops the current block.
+  for (const item of preview) renderedPreview += formatItem(item);
+  if (omittedCount === 0) return renderedPreview;
+  return `${renderedPreview}    [${previewKind}s] ${omittedCount} additional ${previewKind}(s) were omitted from terminal preview.\n`;
+}
+
+function formatRecord(
+  record: CoreRecord,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  const defaultText = `${record.id} | ${canonicalJsonText(record.data)}`;
+  const formattedText = formattedPreviewText("record", defaultText, progressRendering);
+  const previewText = boundedTerminalText(
+    formattedText,
+    progressRendering.textPreviewCodePointLimit
+  );
+  return `    [record] ${previewText}\n`;
+}
+
+function formatMessage(
+  message: CheckMessage,
+  usesColor: boolean,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
   const label = colorMessageLevel(message.level, usesColor);
-  return `    [${label}] ${escapeTerminalText(message.message)}\n`;
+  const formattedText = formattedPreviewText("message", message.message, progressRendering);
+  const previewText = boundedTerminalText(
+    formattedText,
+    progressRendering.textPreviewCodePointLimit
+  );
+  return `    [${label}] ${previewText}\n`;
 }
 
-function totalChecks(counts: ProgressOutcomeCounts): number {
-  return counts.passed + counts.failed + counts.notApplicable + counts.unavailable;
+function formattedPreviewText(
+  kind: "record" | "message",
+  text: string,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  const formatter = progressRendering.formatter;
+  if (formatter === null) return text;
+  const formatted: unknown = formatter(
+    Object.freeze({ kind, maxCodePoints: progressRendering.textPreviewCodePointLimit, text })
+  );
+  if (typeof formatted === "string") return formatted;
+  observeRejectedPromise(formatted);
+  throw new TypeError("Progress preview formatter must synchronously return a string");
 }
 
-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 observeRejectedPromise(value: unknown): void {
+  if (types.isPromise(value)) {
+    // The intrinsic call observes a real Promise without reading a caller-controlled `.then`.
+    // oxlint-disable-next-line typescript/no-floating-promises -- rendering must not await formatter misuse.
+    void Promise.prototype.then.call(value, undefined, () => undefined);
   }
 }
 
-function reasonForOutcome(outcome: CheckOutcome): string | undefined {
-  return outcome.status === "passed" || outcome.status === "failed"
-    ? undefined
-    : outcome.reason?.code;
+function boundedTerminalText(value: string, maximumCodePoints: number): string {
+  const escaped = escapeTerminalText(value);
+  if (codePointLength(escaped) <= maximumCodePoints) return escaped;
+  const marker = prefixByCodePoints(TRUNCATION_MARKER, maximumCodePoints);
+  const textBudget = maximumCodePoints - codePointLength(marker);
+  return `${prefixByCodePoints(escaped, textBudget)}${marker}`;
 }
 
 /** Human-only fields must not control the terminal that presents them. */
@@ -116,6 +237,23 @@ function escapeTerminalText(value: string): string {
   return escaped;
 }
 
+function codePointLength(value: string): number {
+  let length = 0;
+  for (const _character of value) length += 1;
+  return length;
+}
+
+function prefixByCodePoints(value: string, limit: number): string {
+  let prefix = "";
+  let length = 0;
+  for (const character of value) {
+    if (length === limit) break;
+    prefix += character;
+    length += 1;
+  }
+  return prefix;
+}
+
 function isTerminalControl(codePoint: number): boolean {
   return (
     codePoint <= 0x1f ||
@@ -132,6 +270,28 @@ function colorMessageLevel(level: CheckMessage["level"], usesColor: boolean): st
 
 type ProgressStatus = CheckOutcome["status"];
 
+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;
+}
+
+function totalChecks(counts: ProgressOutcomeCounts): number {
+  return counts.passed + counts.failed + counts.notApplicable + counts.unavailable;
+}
+
 function formatDuration(durationMs: number): string {
   if (durationMs < 1_000) {
     return `${Number.isInteger(durationMs) ? durationMs : Number(durationMs.toFixed(1))}ms`;