@zxyycom/vibe-check 0.0.1

package/src/project-run/completion.ts

@@ -0,0 +1,263 @@
+import { resolve } from "node:path";
+import { failedOutput } from "./output-status.ts";
+import { publishMachineOutput } from "./machine-publication.ts";
+import {
+  outputFailure,
+  type CheckDuration,
+  type CheckRunMessage,
+  type NonConfigurationRunResult,
+  type RunResultFacts
+} from "./result.ts";
+import type { CheckAggregate } from "./controls/contract.ts";
+import { diagnosticTags } from "./diagnostic-logging/logger.ts";
+import type { Invocation } from "./invocation.ts";
+import {
+  createPublicationModelV4,
+  type TrustedPublicationModelV4
+} from "../machine-output/v4/publication-model.ts";
+import type { CoreCheck, CoreSnapshot } from "../check-settlement/facts.ts";
+
+type OutcomeCounts = {
+  readonly failed: number;
+  readonly notApplicable: number;
+  readonly passed: number;
+  readonly unavailable: number;
+};
+
+/** Settled Check facts consumed by completion and output publication. */
+export type CoreExecution = Readonly<{
+  readonly aggregate: CheckAggregate | null;
+  readonly checkDurations: readonly CheckDuration[];
+  readonly checkMessages: readonly CheckRunMessage[];
+  readonly snapshot: CoreSnapshot;
+}>;
+
+export function completeInvocation(
+  invocation: Invocation,
+  core: CoreExecution
+): NonConfigurationRunResult {
+  const facts = runFacts(core);
+  if (invocation.outputConfiguration.machinePublication.enabled) {
+    const model = createModel(invocation, core.snapshot);
+    if (isExecutionResult(model)) return model;
+    const published = publishMachineOutput({
+      configuration: invocation.outputConfiguration.machinePublication,
+      statuses: invocation.outputs,
+      model,
+      directory: resolve(
+        invocation.projectRoot,
+        invocation.outputConfiguration.machinePublication.directory
+      )
+    });
+    if (!published) return failure(invocation, facts);
+  }
+  const output = failedOutput(invocation.outputs.value());
+  return output === undefined
+    ? Object.freeze({
+        kind: "completed",
+        declarativeFingerprint: invocation.declarativeFingerprint,
+        definitionWarnings: invocation.definitionWarnings,
+        outputs: invocation.outputs.value(),
+        ...facts
+      })
+    : failure(invocation, facts);
+}
+function failure(invocation: Invocation, facts: RunResultFacts): ReturnType<typeof outputFailure> {
+  const output = failedOutput(invocation.outputs.value());
+  if (output === undefined) throw new Error("Run output failed without a failed status");
+  return outputFailure(
+    invocation.declarativeFingerprint,
+    invocation.definitionWarnings,
+    invocation.outputs.value(),
+    output,
+    facts
+  );
+}
+function runFacts(core: CoreExecution): RunResultFacts {
+  return Object.freeze({
+    aggregate: core.aggregate,
+    checkDurations: core.checkDurations,
+    checkMessages: core.checkMessages,
+    snapshot: core.snapshot
+  });
+}
+function createModel(
+  invocation: Invocation,
+  snapshot: CoreExecution["snapshot"]
+): TrustedPublicationModelV4 | Extract<NonConfigurationRunResult, { readonly kind: "execution" }> {
+  try {
+    if (invocation.startedAtUtc === null)
+      throw new Error("Machine publication requires an invocation timestamp");
+    return createPublicationModelV4({
+      invocation: {
+        invocationId: invocation.invocationId,
+        projectRoot: ".",
+        timestamp: invocation.startedAtUtc
+      },
+      snapshot
+    });
+  } catch {
+    return Object.freeze({
+      kind: "execution",
+      declarativeFingerprint: invocation.declarativeFingerprint,
+      definitionWarnings: invocation.definitionWarnings,
+      diagnostic: Object.freeze({ code: "publication-model-failed" }),
+      outputs: invocation.outputs.value()
+    });
+  }
+}
+function isExecutionResult(
+  value:
+    | TrustedPublicationModelV4
+    | Extract<NonConfigurationRunResult, { readonly kind: "execution" }>
+): value is Extract<NonConfigurationRunResult, { readonly kind: "execution" }> {
+  return "kind" in value;
+}
+
+/** Closes diagnostic logging and applies final output priority to a non-configuration candidate. */
+export function finalizeInvocation(
+  invocation: Invocation,
+  candidate: NonConfigurationRunResult
+): NonConfigurationRunResult {
+  const preCloseOutputs = invocation.outputs.value();
+  invocation.diagnosticLogger.observe({
+    event: "run.terminal-before-log-close",
+    tags: diagnosticTags("RUN", "TERMINAL", terminalStatusTag(candidate)),
+    details: {
+      ...closingFacts(candidate),
+      diagnosticLogging: "close-not-yet-confirmed",
+      outputs: preCloseOutputDetails(preCloseOutputs)
+    }
+  });
+  const diagnosticLoggingStatus = invocation.diagnosticLogger.close();
+  if (diagnosticLoggingStatus === "failed") invocation.outputs.failed("diagnosticLogging");
+  if (diagnosticLoggingStatus === "succeeded") invocation.outputs.succeeded("diagnosticLogging");
+
+  const outputs = invocation.outputs.value();
+  switch (candidate.kind) {
+    case "completed": {
+      const output = failedOutput(outputs);
+      return output === undefined
+        ? Object.freeze({ ...candidate, outputs })
+        : outputFailure(
+            candidate.declarativeFingerprint,
+            candidate.definitionWarnings,
+            outputs,
+            output,
+            finalSnapshotFacts(candidate)
+          );
+    }
+    case "output": {
+      const output = failedOutput(outputs);
+      if (output === undefined) throw new Error("Run output failed without a failed status");
+      return outputFailure(
+        candidate.declarativeFingerprint,
+        candidate.definitionWarnings,
+        outputs,
+        output,
+        finalSnapshotFacts(candidate)
+      );
+    }
+    case "planning":
+    case "cancelled":
+    case "execution":
+      return Object.freeze({ ...candidate, outputs });
+  }
+}
+
+function terminalStatusTag(candidate: NonConfigurationRunResult): string {
+  if ("aggregate" in candidate && candidate.aggregate !== null)
+    return candidate.aggregate.toUpperCase();
+  if (candidate.kind === "cancelled") return "CANCELLED";
+  return candidate.kind.toUpperCase();
+}
+
+function preCloseOutputDetails(outputs: ReturnType<Invocation["outputs"]["value"]>): Readonly<{
+  readonly machinePublication: (typeof outputs)["machinePublication"];
+  readonly progressRendering: (typeof outputs)["progressRendering"];
+}> {
+  return Object.freeze({
+    machinePublication: outputs.machinePublication,
+    progressRendering: outputs.progressRendering
+  });
+}
+
+function closingFacts(candidate: NonConfigurationRunResult): Readonly<{
+  readonly aggregate: CheckAggregate | null;
+  readonly candidateKind: NonConfigurationRunResult["kind"];
+  readonly counts: Readonly<{
+    readonly failed: number;
+    readonly notApplicable: number;
+    readonly passed: number;
+    readonly unavailable: number;
+  }> | null;
+  readonly nonPassed: readonly Readonly<{
+    readonly checkId: string;
+    readonly reason: unknown;
+    readonly status: string;
+  }>[];
+}> {
+  if (!("snapshot" in candidate)) {
+    return Object.freeze({
+      aggregate: null,
+      candidateKind: candidate.kind,
+      counts: null,
+      nonPassed: []
+    });
+  }
+  const summary = summarizeSnapshot(candidate.snapshot);
+  return Object.freeze({
+    aggregate: "aggregate" in candidate ? candidate.aggregate : null,
+    candidateKind: candidate.kind,
+    ...summary
+  });
+}
+
+function summarizeSnapshot(snapshot: CoreSnapshot): Readonly<{
+  readonly counts: OutcomeCounts;
+  readonly nonPassed: readonly Readonly<{
+    readonly checkId: string;
+    readonly reason: unknown;
+    readonly status: string;
+  }>[];
+}> {
+  const counts = { failed: 0, notApplicable: 0, passed: 0, unavailable: 0 };
+  const nonPassed: Array<Readonly<{ checkId: string; reason: unknown; status: string }>> = [];
+  for (const check of snapshot.checks) {
+    counts[statusCountKey(check)] += 1;
+    const fact = nonPassedFact(check);
+    if (fact !== undefined) nonPassed.push(fact);
+  }
+  return Object.freeze({
+    counts: Object.freeze(counts),
+    nonPassed: Object.freeze(nonPassed)
+  });
+}
+
+function statusCountKey(check: CoreCheck): keyof OutcomeCounts {
+  return check.outcome.status === "not-applicable" ? "notApplicable" : check.outcome.status;
+}
+
+function nonPassedFact(
+  check: CoreCheck
+):
+  | Readonly<{ readonly checkId: string; readonly reason: unknown; readonly status: string }>
+  | undefined {
+  if (check.outcome.status === "passed") return undefined;
+  return Object.freeze({
+    checkId: check.checkId,
+    reason: check.outcome.status === "failed" ? null : (check.outcome.reason ?? null),
+    status: check.outcome.status
+  });
+}
+
+function finalSnapshotFacts(
+  candidate: Extract<NonConfigurationRunResult, RunResultFacts>
+): RunResultFacts {
+  return Object.freeze({
+    aggregate: candidate.aggregate,
+    checkDurations: candidate.checkDurations,
+    checkMessages: candidate.checkMessages,
+    snapshot: candidate.snapshot
+  });
+}

package/src/project-run/controls/contract.ts

@@ -0,0 +1,24 @@
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+/** 单次 run 调用的闭合上下文与 output override；Project Definition 保持为 authored input。 */
+export interface RunControls {
+  readonly checkAggregation?: CheckAggregation;
+  /** 仅为本次调用覆盖 Run-owned outputs。 */
+  readonly outputs?: Partial<{
+    machinePublication: Partial<ProjectOutputs["machinePublication"]>;
+    progressRendering: Partial<ProjectOutputs["progressRendering"]>;
+    diagnosticLogging: Partial<ProjectOutputs["diagnosticLogging"]>;
+  }>;
+  readonly flags?: readonly string[];
+  readonly projectRoot?: string;
+  readonly signal?: AbortSignal;
+}
+/** 将选定 Check statuses 折叠为 invocation aggregate 的规则。 */
+export interface CheckAggregation {
+  readonly checks: "all" | readonly string[];
+  readonly mode: "all" | "any";
+  readonly unavailable: "propagate" | "fail" | "exclude";
+  readonly notApplicable: "exclude" | "pass" | "fail";
+  readonly empty: "passed" | "failed" | "not-applicable";
+}
+/** `CheckAggregation` 计算出的 invocation 级结果。 */
+export type CheckAggregate = "passed" | "failed" | "not-applicable" | "unavailable";

package/src/project-run/controls/outputs-override-validation.ts

@@ -0,0 +1,86 @@
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isContainedRelativeDirectory } from "../../project-definition/output-validation.ts";
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { RunControls } from "./contract.ts";
+
+type DirectoryOutputOverride = Readonly<{
+  readonly directory?: string;
+  readonly enabled?: boolean;
+}>;
+
+/** Parses invocation-local outputs without changing Definition defaults. */
+export function parseOutputsOverride(value: unknown): RunControls["outputs"] | undefined {
+  const data = snapshotClosedRecord(value);
+  if (
+    data === undefined ||
+    Object.keys(data).some(
+      (key) =>
+        key !== "machinePublication" && key !== "progressRendering" && key !== "diagnosticLogging"
+    )
+  )
+    return undefined;
+  const machinePublication = optionalOutput(
+    data,
+    "machinePublication",
+    parseDirectoryOutputOverride
+  );
+  const progressRendering = optionalOutput(data, "progressRendering", parseProgressOutputOverride);
+  const diagnosticLogging = optionalOutput(
+    data,
+    "diagnosticLogging",
+    parseDiagnosticLoggingOverride
+  );
+  if (!machinePublication.ok || !progressRendering.ok || !diagnosticLogging.ok) return undefined;
+  return Object.freeze({
+    ...(machinePublication.value === undefined
+      ? {}
+      : { machinePublication: machinePublication.value }),
+    ...(progressRendering.value === undefined
+      ? {}
+      : { progressRendering: progressRendering.value }),
+    ...(diagnosticLogging.value === undefined ? {} : { diagnosticLogging: diagnosticLogging.value })
+  });
+}
+function optionalOutput<T>(
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  parse: (candidate: unknown) => T | undefined
+): Readonly<{ readonly ok: boolean; readonly value?: T }> {
+  if (value[key] === undefined) return Object.freeze({ ok: true });
+  const parsed = parse(value[key]);
+  return parsed === undefined
+    ? Object.freeze({ ok: false })
+    : Object.freeze({ ok: true, value: parsed });
+}
+function parseDirectoryOutputOverride(value: unknown): DirectoryOutputOverride | undefined {
+  const data = snapshotClosedRecord(value);
+  if (
+    data === undefined ||
+    Object.keys(data).some((key) => key !== "directory" && key !== "enabled")
+  )
+    return undefined;
+  if (data.directory !== undefined && typeof data.directory !== "string") return undefined;
+  if (data.enabled !== undefined && typeof data.enabled !== "boolean") return undefined;
+  return Object.freeze({
+    ...(data.directory === undefined ? {} : { directory: data.directory }),
+    ...(data.enabled === undefined ? {} : { enabled: data.enabled })
+  });
+}
+function parseProgressOutputOverride(
+  value: unknown
+): Partial<ProjectOutputs["progressRendering"]> | undefined {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined || Object.keys(data).some((key) => key !== "enabled")) return undefined;
+  if (data.enabled !== undefined && typeof data.enabled !== "boolean") return undefined;
+  return Object.freeze(data.enabled === undefined ? {} : { enabled: data.enabled });
+}
+
+function parseDiagnosticLoggingOverride(
+  value: unknown
+): Partial<ProjectOutputs["diagnosticLogging"]> | undefined {
+  const parsed = parseDirectoryOutputOverride(value);
+  return parsed === undefined ||
+    (parsed.directory !== undefined && !isContainedRelativeDirectory(parsed.directory))
+    ? undefined
+    : parsed;
+}

package/src/project-run/controls/validation-result.ts

@@ -0,0 +1,12 @@
+/** Diagnostic emitted when one invocation control is not a closed supported value. */
+export interface RunControlDiagnostic {
+  readonly kind: "invalid-run-controls";
+  readonly path: string;
+  readonly reason: "invalid-value" | "unknown-key";
+}
+
+/** Closed validation result for a Run-owned invocation control. */
+export type RunControlValidationResult<T> = Readonly<
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: RunControlDiagnostic }
+>;

package/src/project-run/controls/validation.ts

@@ -0,0 +1,176 @@
+import { snapshotClosedArray } from "../../data-boundary/closed-values.ts";
+import { isNonArrayRecord, isUnknownArray } from "../../data-boundary/value-shapes.ts";
+import { parseOutputsOverride } from "./outputs-override-validation.ts";
+import type { RunControlDiagnostic, RunControlValidationResult } from "./validation-result.ts";
+import type { CheckAggregation, RunControls } from "./contract.ts";
+
+const RUN_CONTROL_KEYS = ["checkAggregation", "outputs", "flags", "projectRoot", "signal"] as const;
+const CHECK_AGGREGATION_MODES = ["all", "any"] as const;
+const UNAVAILABLE_HANDLING = ["propagate", "fail", "exclude"] as const;
+const NOT_APPLICABLE_HANDLING = ["exclude", "pass", "fail"] as const;
+const EMPTY_AGGREGATION_RESULTS = ["passed", "failed", "not-applicable"] as const;
+
+export function validateRunControls(value: unknown = {}): RunControlValidationResult<RunControls> {
+  try {
+    return validateRunControlsValue(value);
+  } catch {
+    return invalidControls("controls");
+  }
+}
+
+function validateRunControlsValue(value: unknown): RunControlValidationResult<RunControls> {
+  const data = exactControlRecord(value);
+  if (!data.ok) return data;
+  const flags = parseFlags(data.value.flags);
+  if (!flags.ok) return flags;
+  const checkAggregation = parseOptionalCheckAggregation(data.value.checkAggregation);
+  if (!checkAggregation.ok) return checkAggregation;
+  const outputs = optionalControl(data.value.outputs, parseOutputsOverride, "controls.outputs");
+  if (!outputs.ok) return outputs;
+  const projectRoot = optionalControl(data.value.projectRoot, parseString, "controls.projectRoot");
+  if (!projectRoot.ok) return projectRoot;
+  const signal = optionalControl(data.value.signal, parseAbortSignal, "controls.signal");
+  if (!signal.ok) return signal;
+  return Object.freeze({
+    ok: true,
+    value: Object.freeze({
+      ...(checkAggregation.value === undefined ? {} : { checkAggregation: checkAggregation.value }),
+      ...(outputs.value === undefined ? {} : { outputs: outputs.value }),
+      flags: flags.value,
+      ...(projectRoot.value === undefined ? {} : { projectRoot: projectRoot.value }),
+      ...(signal.value === undefined ? {} : { signal: signal.value })
+    })
+  });
+}
+
+function exactControlRecord(
+  value: unknown
+): RunControlValidationResult<Readonly<Record<string, unknown>>> {
+  if (!isNonArrayRecord(value)) return invalidControls("controls");
+  const unknownKey = Object.keys(value).find((key) => !isRunControlKey(key));
+  return unknownKey === undefined
+    ? Object.freeze({ ok: true, value })
+    : invalidRunControl(`controls.${unknownKey}`, "unknown-key");
+}
+
+function optionalControl<T>(
+  value: unknown,
+  parse: (candidate: unknown) => T | undefined,
+  path: string
+): RunControlValidationResult<T | undefined> {
+  if (value === undefined) return Object.freeze({ ok: true, value: undefined });
+  const parsed = parse(value);
+  return parsed === undefined ? invalidControls(path) : Object.freeze({ ok: true, value: parsed });
+}
+
+function parseFlags(value: unknown): RunControlValidationResult<readonly string[]> {
+  if (value === undefined) return Object.freeze({ ok: true, value: Object.freeze([]) });
+  if (!isUnknownArray(value)) return invalidControls("controls.flags");
+  const flags: string[] = [];
+  const length = value.length;
+  for (let index = 0; index < length; index += 1) {
+    if (!Object.hasOwn(value, index)) return invalidControls("controls.flags");
+    const flag = value[index];
+    if (typeof flag !== "string" || flag.length === 0) {
+      return invalidControls("controls.flags");
+    }
+    flags.push(flag);
+  }
+  return Object.freeze({
+    ok: true,
+    value: Object.freeze([...new Set(flags)].sort())
+  });
+}
+
+function parseOptionalCheckAggregation(
+  value: unknown
+): RunControlValidationResult<CheckAggregation | undefined> {
+  if (value === undefined) return Object.freeze({ ok: true, value: undefined });
+  const data = exactKeys(value, ["checks", "mode", "unavailable", "notApplicable", "empty"]);
+  if (data === undefined) return invalidControls("controls.checkAggregation");
+  const checks = data.checks === "all" ? "all" : parseClosedCheckIds(data.checks);
+  if (checks === undefined) return invalidControls("controls.checkAggregation.checks");
+  const mode = parseLiteral(data.mode, CHECK_AGGREGATION_MODES);
+  const unavailable = parseLiteral(data.unavailable, UNAVAILABLE_HANDLING);
+  const notApplicable = parseLiteral(data.notApplicable, NOT_APPLICABLE_HANDLING);
+  const empty = parseLiteral(data.empty, EMPTY_AGGREGATION_RESULTS);
+  if (
+    mode === undefined ||
+    unavailable === undefined ||
+    notApplicable === undefined ||
+    empty === undefined
+  )
+    return invalidControls("controls.checkAggregation");
+  return Object.freeze({
+    ok: true,
+    value: Object.freeze({
+      checks,
+      mode,
+      unavailable,
+      notApplicable,
+      empty
+    })
+  });
+}
+
+function parseClosedCheckIds(value: unknown): readonly string[] | undefined {
+  const values = snapshotClosedArray(value);
+  if (values === undefined) return undefined;
+  const checkIds: string[] = [];
+  for (const checkId of values) {
+    if (typeof checkId !== "string" || checkId.length === 0) return undefined;
+    checkIds.push(checkId);
+  }
+  return Object.freeze(checkIds);
+}
+
+function parseLiteral<Value extends string>(
+  value: unknown,
+  allowed: readonly Value[]
+): Value | undefined {
+  return typeof value === "string" ? allowed.find((option) => option === value) : undefined;
+}
+
+function isRunControlKey(value: string): boolean {
+  return RUN_CONTROL_KEYS.some((key) => key === value);
+}
+
+function exactKeys(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  if (!isNonArrayRecord(value)) return undefined;
+  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))
+    ? value
+    : undefined;
+}
+
+function isAbortSignal(value: unknown): value is AbortSignal {
+  return (
+    isNonArrayRecord(value) &&
+    typeof value.aborted === "boolean" &&
+    typeof value.addEventListener === "function"
+  );
+}
+
+function parseAbortSignal(value: unknown): AbortSignal | undefined {
+  return isAbortSignal(value) ? value : undefined;
+}
+
+function parseString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function invalidControls(path: string): RunControlValidationResult<never> {
+  return invalidRunControl(path, "invalid-value");
+}
+
+function invalidRunControl(
+  path: string,
+  reason: RunControlDiagnostic["reason"]
+): RunControlValidationResult<never> {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ kind: "invalid-run-controls", path, reason })
+  });
+}