@zxyycom/vibe-check 0.0.2 → 0.0.3

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

@@ -1,8 +1,9 @@
 import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { CoreCheck } from "../../check-settlement/facts.ts";
 /**
  * `run(definition, controls?)` 的第二个参数，只指定这一次怎么运行。
  *
- * root、flags、signal、Check 产物与日志目标以及显式 aggregation 属于本次调用；`outputs` 只逐字段
+ * root、flags、signal、Check 产物与日志目标以及 aggregation 属于本次调用；`outputs` 只逐字段
  * 覆盖 Definition 的输出默认值，不修改原 Definition。Checks、Check options 与 scheduler 仍在
  * `defineConfig(...)` 中声明，不能从这里替换；这些 Controls 不进入 Definition fingerprint。
  */
@@ -13,7 +14,7 @@ export interface RunControls {
   readonly progressLogFile?: string;
   /** caller 选择的 Check-owned invocation artifact base；省略时不授予 artifact capability。 */
   readonly checkArtifactBaseDirectory?: string;
-  /** 为本次 Run 选择并折叠 Check statuses；省略时结果的 `aggregate` 为 `null`。 */
+  /** 为本次 Run 解释有效 Check facts；省略时使用严格的 all-passed 默认折叠。 */
   readonly checkAggregation?: CheckAggregation;
   /** 仅为本次调用覆盖 Run-owned outputs。 */
   readonly outputs?: Partial<{
@@ -25,23 +26,12 @@ export interface RunControls {
   readonly flags?: readonly string[];
   /** 项目相对输入与 output target 的解析根；省略时使用调用进程的当前工作目录。 */
   readonly projectRoot?: string;
-  /** 供 planning、preflight 与 execution 协作响应的 caller cancellation signal。 */
+  /** 供 planning、preparation 与 execution 协作响应的 caller cancellation signal。 */
   readonly signal?: AbortSignal;
 }
 /** Diagnostic 文件名选择；不改变目录、日志内容或 invocation identity。 */
 export type DiagnosticLogFileNaming = "unique" | "channel";
-/** 将选定 Check statuses 折叠为 invocation aggregate 的规则。 */
-export interface CheckAggregation {
-  /** `all` 选择全部 Check，ID 数组选择明确集合，`effective` 复用本 invocation 的 flag-and-dependency selection。 */
-  readonly checks: "all" | "effective" | readonly string[];
-  /** `all` 要求所有纳入状态通过；`any` 只要求至少一个纳入状态通过。 */
-  readonly mode: "all" | "any";
-  /** 将 `unavailable` 原样传播、按失败纳入，或从 `all`/`any` 计算中排除。 */
-  readonly unavailable: "propagate" | "fail" | "exclude";
-  /** 将 `not-applicable` 从计算中排除，或按通过/失败纳入。 */
-  readonly notApplicable: "exclude" | "pass" | "fail";
-  /** 选择为空或所有状态都被排除时返回的明确 aggregate。 */
-  readonly empty: "passed" | "failed" | "not-applicable";
-}
 /** `CheckAggregation` 计算出的 invocation 级结果。 */
 export type CheckAggregate = "passed" | "failed" | "not-applicable" | "unavailable";
+/** 同步解释本次有效 Check facts 的 caller-local aggregation。 */
+export type CheckAggregation = (checks: readonly CoreCheck[]) => CheckAggregate;

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

@@ -1,7 +1,7 @@
-import { snapshotClosedArray } from "../../data-boundary/closed-values.ts";
 import { isOutputDirectory } from "../../project-definition/output-validation.ts";
 import { isNonArrayRecord, isUnknownArray } from "../../data-boundary/value-shapes.ts";
 import { parseOutputsOverride } from "./outputs-override-validation.ts";
+import { CHANGE_FLAG_PREFIX } from "../changes/git.ts";
 import type { RunControlDiagnostic, RunControlValidationResult } from "./validation-result.ts";
 import type { CheckAggregation, DiagnosticLogFileNaming, RunControls } from "./contract.ts";
 
@@ -15,10 +15,6 @@ const RUN_CONTROL_KEYS = [
   "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;
 
 interface ParsedInvocationOutputTargets {
   readonly diagnosticLogFileNaming: DiagnosticLogFileNaming | undefined;
@@ -159,7 +155,7 @@ function parseFlags(value: unknown): RunControlValidationResult<readonly string[
   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) {
+    if (typeof flag !== "string" || flag.length === 0 || flag.startsWith(CHANGE_FLAG_PREFIX)) {
       return invalidControls("controls.flags");
     }
     flags.push(flag);
@@ -174,68 +170,19 @@ 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" || data.checks === "effective"
-      ? data.checks
-      : 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);
+  return isCheckAggregation(value)
+    ? Object.freeze({ ok: true, value })
+    : invalidControls("controls.checkAggregation");
 }
 
-function parseLiteral<Value extends string>(
-  value: unknown,
-  allowed: readonly Value[]
-): Value | undefined {
-  return typeof value === "string" ? allowed.find((option) => option === value) : undefined;
+function isCheckAggregation(value: unknown): value is CheckAggregation {
+  return typeof value === "function";
 }
 
 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) &&

package/src/project-run/diagnostic-logging/diagnostic-detail-rendering.ts

@@ -199,9 +199,8 @@ function renderDetailRecord(
 function isEnumerableDataDescriptor(
   descriptor: PropertyDescriptor | undefined
 ): descriptor is PropertyDescriptor & Readonly<{ readonly value: unknown }> {
+  if (descriptor?.enumerable !== true) return false;
   return (
-    descriptor !== undefined &&
-    descriptor.enumerable === true &&
     descriptor.get === undefined &&
     descriptor.set === undefined &&
     Object.hasOwn(descriptor, "value")

package/src/project-run/diagnostic-logging/observation-rendering.ts

@@ -131,7 +131,7 @@ function factKey(path: readonly string[]): string {
 
 function factValue(path: readonly string[], value: unknown): string {
   const key = path.at(-1);
-  if (typeof value === "number" && key?.endsWith("Ms")) {
+  if (typeof value === "number" && key?.endsWith("Ms") === true) {
     return String(Math.round(value * 1_000) / 1_000);
   }
   return JSON.stringify(value);

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

@@ -1,4 +1,4 @@
-import { aggregateCheckOutcomes } from "../aggregation.ts";
+import { aggregateEffectiveChecks } from "../aggregation.ts";
 import { completeInvocation, type CoreExecution } from "../completion/completion.ts";
 import type { CheckAggregation } from "../controls/contract.ts";
 import { diagnosticTags } from "../diagnostic-logging/logger.ts";
@@ -21,14 +21,20 @@ export function mapResolvedExecutionToRunCandidate(
   const { executed, invocation } = input;
   if (executed.kind === "admission-policy-failed") return admissionPolicyFailure(invocation);
 
-  invocation.progressRendering.final({
-    counts: outcomeCounts(executed.snapshot),
-    elapsedMs: elapsedSince(input.executionStartedAt, invocation.clock),
-    execution: executed.kind
-  });
-
-  if (executed.kind === "cancelled") return cancelledExecutionCandidate(invocation, executed);
-  return completedExecutionCandidate(invocation, input.aggregation, executed);
+  if (executed.kind === "cancelled") {
+    invocation.progressRendering.final({
+      counts: outcomeCounts(executed.snapshot),
+      elapsedMs: elapsedSince(input.executionStartedAt, invocation.clock),
+      execution: executed.kind
+    });
+    return cancelledExecutionCandidate(invocation, executed);
+  }
+  return completedExecutionCandidate(
+    invocation,
+    input.aggregation,
+    executed,
+    input.executionStartedAt
+  );
 }
 
 function admissionPolicyFailure(
@@ -65,16 +71,18 @@ function cancelledExecutionCandidate(
 function completedExecutionCandidate(
   invocation: Invocation,
   aggregation: CheckAggregation | undefined,
-  executed: Extract<ResolvedCheckExecution, { readonly kind: "completed" }>
+  executed: Extract<ResolvedCheckExecution, { readonly kind: "completed" }>,
+  executionStartedAt: number
 ): NonConfigurationRunResult {
-  const aggregate =
-    aggregation === undefined
-      ? null
-      : aggregateCheckOutcomes(executed.snapshot, aggregation, executed.effectiveCheckIds);
+  const aggregate = aggregateEffectiveChecks(
+    executed.snapshot,
+    executed.effectiveCheckIds,
+    aggregation
+  );
   invocation.diagnosticLogging.core.observe({
     event: "run.aggregation.completed",
     tags: diagnosticTags("RUN", "AGGREGATION", "COMPLETED"),
-    details: { aggregate, selection: aggregation ?? null }
+    details: { aggregate, aggregation: aggregation === undefined ? "default" : "custom" }
   });
   const core: CoreExecution = Object.freeze({
     aggregate,
@@ -82,5 +90,10 @@ function completedExecutionCandidate(
     checkMessages: executed.checkMessages,
     snapshot: executed.snapshot
   });
+  invocation.progressRendering.final({
+    counts: outcomeCounts(executed.snapshot),
+    elapsedMs: elapsedSince(executionStartedAt, invocation.clock),
+    execution: "completed"
+  });
   return completeInvocation(invocation, core);
 }

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

@@ -0,0 +1,56 @@
+import { diagnosticTags } from "../diagnostic-logging/logger.ts";
+import {
+  planning,
+  preExecutionCancellation,
+  type NonConfigurationRunResult,
+  type RunDiagnostic
+} from "../result.ts";
+import type { Invocation } from "./run.ts";
+
+/** Records a pre-execution cancellation as the Run-owned candidate result. */
+export function cancelledBeforeExecution(
+  invocation: Invocation,
+  phase: "pre-work" | "planning"
+): NonConfigurationRunResult {
+  invocation.diagnosticLogging.core.observe({
+    event: "run.cancelled",
+    tags: diagnosticTags("RUN", "CANCELLED"),
+    details: { phase }
+  });
+  return preExecutionCancellation(
+    invocation.declarativeFingerprint,
+    invocation.definitionWarnings,
+    invocation.outputs.value(),
+    phase
+  );
+}
+
+/** Constructs the planning failure candidate after the static graph has been rejected. */
+export function planningResult(
+  invocation: Invocation,
+  code: Extract<RunDiagnostic["code"], "task-graph-invalid">
+): NonConfigurationRunResult {
+  return planning(
+    invocation.declarativeFingerprint,
+    invocation.definitionWarnings,
+    invocation.outputs.value(),
+    code
+  );
+}
+
+/** Constructs a pre-settlement execution failure without revising existing output facts. */
+export function executionResult(
+  invocation: Invocation,
+  code: Extract<
+    RunDiagnostic["code"],
+    "admission-strategy-preparation-failed" | "task-engine-failed"
+  >
+): NonConfigurationRunResult {
+  return Object.freeze({
+    kind: "execution",
+    declarativeFingerprint: invocation.declarativeFingerprint,
+    definitionWarnings: invocation.definitionWarnings,
+    diagnostic: Object.freeze({ code }),
+    outputs: invocation.outputs.value()
+  });
+}

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

@@ -51,7 +51,7 @@ export function createInvocation(input: InvocationCreationInput): Invocation {
   const outputs = createOutputStatuses(
     outputConfiguration,
     paths.diagnosticLoggingReadbackFiles,
-    input.normalized.scheduler.measurementHooks.length > 0
+    input.normalized.scheduler.terminalEffects.length > 0
   );
   const diagnosticLogging = createDiagnosticLoggingRouter({
     clock,
@@ -77,8 +77,12 @@ export function createInvocation(input: InvocationCreationInput): Invocation {
     normalized: input.normalized,
     progressRendering: createProgressRendering(outputConfiguration.progressRendering, outputs, {
       clock,
-      refreshScheduler: input.dependencies.progressRefreshScheduler,
-      writerFactory: input.dependencies.progressWriterFactory,
+      ...(input.dependencies.progressRefreshScheduler === undefined
+        ? {}
+        : { refreshScheduler: input.dependencies.progressRefreshScheduler }),
+      ...(input.dependencies.progressWriterFactory === undefined
+        ? {}
+        : { writerFactory: input.dependencies.progressWriterFactory }),
       file: paths.progressLogFile
     }),
     startedAtUtc

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

@@ -0,0 +1,136 @@
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { CheckAggregation } from "../controls/contract.ts";
+import { createAdmissionStrategyProvider } from "../admission-strategy-provider/provider.ts";
+import { AdmissionStrategyPreparationFailure } from "../admission-strategy-provider/custom-strategy-preparation.ts";
+import type { PreparedAdmissionStrategy } from "../admission-strategy-provider/prepared-admission-strategy.ts";
+import { prepareTaskGraph } from "../task-scheduler/graph.ts";
+import type { ResolvedCheckExecution } from "../check-execution/resolved-execution-result.ts";
+import { planStaticCheckGraph } from "../check-execution/plan.ts";
+import { prepareProjectChanges } from "../changes/git.ts";
+import { createProjectContext } from "../project-context.ts";
+import type { OutputStatuses } from "../outputs/status.ts";
+import { isCancelled, type NonConfigurationRunResult } from "../result.ts";
+import { mapResolvedExecutionToRunCandidate } from "./candidate.ts";
+import { cancelledBeforeExecution, executionResult } from "./candidates.ts";
+import type { Invocation } from "./run.ts";
+import { executeScheduler, type SchedulerExecution } from "./scheduler.ts";
+
+const EMPTY_EFFECTIVE_FLAGS: readonly string[] = Object.freeze([]);
+
+/** Executes the post-validation invocation phases, from change preparation through Scheduler completion. */
+export async function executePlannedInvocation(
+  invocation: Invocation,
+  aggregation: CheckAggregation | undefined
+): Promise<NonConfigurationRunResult> {
+  if (isCancelled(invocation.controls)) return cancelledBeforeExecution(invocation, "pre-work");
+  const preparedChanges =
+    invocation.normalized.changes === undefined
+      ? undefined
+      : prepareProjectChanges({
+          callerFlags: invocation.controls.flags ?? [],
+          changes: invocation.normalized.changes,
+          projectRoot: invocation.paths.projectRoot
+        });
+  const effectiveFlags =
+    preparedChanges?.effectiveFlags ?? invocation.controls.flags ?? EMPTY_EFFECTIVE_FLAGS;
+  return executePreparedInvocation(
+    invocation,
+    aggregation,
+    createProjectContext({
+      ...(preparedChanges === undefined ? {} : { changes: preparedChanges.projectChanges }),
+      flags: effectiveFlags,
+      paths: invocation.paths
+    })
+  );
+}
+async function executePreparedInvocation(
+  invocation: Invocation,
+  aggregation: CheckAggregation | undefined,
+  project: CheckProjectContext
+): Promise<NonConfigurationRunResult> {
+  if (isCancelled(invocation.controls)) return cancelledBeforeExecution(invocation, "planning");
+  let preparedStrategy: PreparedAdmissionStrategy;
+  try {
+    preparedStrategy = await prepareAdmissionStrategy(invocation);
+  } catch (error) {
+    if (error instanceof AdmissionStrategyPreparationFailure) {
+      return executionResult(invocation, "admission-strategy-preparation-failed");
+    }
+    throw error;
+  }
+  if (preparedStrategy.completion.kind === "terminal-effect") {
+    invocation.outputs.enableTerminalEffects();
+  }
+  invocation.progressRendering.prepared(
+    invocation.normalized.checks.length,
+    invocation.normalized.checks.filter((check) => check.omitQuietPassedRow).length
+  );
+  const executionStartedAt = invocation.clock.now();
+  const executed = await executeScheduler({ invocation, preparedStrategy, project });
+  if (isExecutionRunResult(executed)) return executed;
+  await completeAdmissionStrategyAfterTerminalMeasurement(
+    preparedStrategy,
+    executed,
+    invocation.outputs
+  );
+  return mapResolvedExecutionToRunCandidate({
+    aggregation,
+    executed,
+    executionStartedAt,
+    invocation
+  });
+}
+
+/** Composes one invocation-local strategy only after the static Task graph is valid. */
+async function prepareAdmissionStrategy(
+  invocation: Invocation
+): Promise<PreparedAdmissionStrategy> {
+  const graph = prepareTaskGraph(
+    planStaticCheckGraph(
+      invocation.normalized.checks,
+      invocation.normalized.declarative.scheduler.resourceCapacities
+    ),
+    invocation.normalized.declarative.scheduler.maxParallel
+  );
+  const admissionStrategyProviderFactory =
+    invocation.admissionStrategyProviderFactory ?? createAdmissionStrategyProvider;
+  const provider = admissionStrategyProviderFactory({
+    admissionPolicy: invocation.normalized.scheduler.admissionPolicy,
+    graph: graph.schedulerGraphSnapshot
+  });
+  return provider.prepare();
+}
+
+/** The prepared provider closes only after Scheduler terminal measurement and Hooks have settled. */
+async function completeAdmissionStrategyAfterTerminalMeasurement(
+  preparedStrategy: PreparedAdmissionStrategy,
+  executed: ResolvedCheckExecution,
+  outputs: OutputStatuses
+): Promise<void> {
+  const terminalMeasurement = executed.terminalSchedulerMeasurement;
+  if (terminalMeasurement === undefined) return;
+  switch (preparedStrategy.completion.kind) {
+    case "none":
+      return;
+    case "internal":
+      try {
+        await preparedStrategy.completion.complete(Object.freeze({ terminalMeasurement }));
+      } catch {
+        // Private learned lifecycle cannot revise sealed execution or public output facts.
+      }
+      return;
+    case "terminal-effect":
+      try {
+        await preparedStrategy.completion.terminalEffect(terminalMeasurement);
+        outputs.succeeded("terminalEffects");
+      } catch {
+        outputs.failed("terminalEffects");
+      }
+  }
+}
+
+function isExecutionRunResult(
+  value: SchedulerExecution
+): value is Extract<NonConfigurationRunResult, { readonly kind: "execution" }> {
+  return "declarativeFingerprint" in value;
+}