@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/project-definition/check-tree/flag-conditions.ts

@@ -0,0 +1,99 @@
+import type { CheckFlagCondition } from "../../check/check.ts";
+import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+
+const FLAG_CONDITION_MAX_DEPTH = 16;
+const FLAG_CONDITION_MAX_NODES = 256;
+
+/** Parses and snapshots one bounded recursive flag condition while retaining child order and multiplicity. */
+export function parseFlagCondition(value: unknown): CheckFlagCondition | undefined {
+  return parseBoundedFlagCondition(value, 1, { nodes: 0 });
+}
+
+/** Checks that a closed record has no author-supplied keys outside this grammar fragment. */
+export function hasOnlyKeys(
+  value: Readonly<Record<string, unknown>>,
+  keys: readonly string[]
+): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function parseBoundedFlagCondition(
+  value: unknown,
+  depth: number,
+  state: { nodes: number }
+): CheckFlagCondition | undefined {
+  if (exceedsFlagConditionBounds(depth, state)) return undefined;
+  if (isNonEmptyIdentifier(value)) return value;
+  const condition = snapshotClosedRecord(value);
+  const kind = condition?.kind;
+  if (condition === undefined || typeof kind !== "string") return undefined;
+  return kind === "not"
+    ? parseFlagNegationCondition(condition, depth, state)
+    : parseFlagConditionSet(condition, kind, depth, state);
+}
+
+function exceedsFlagConditionBounds(depth: number, state: { nodes: number }): boolean {
+  state.nodes += 1;
+  return depth > FLAG_CONDITION_MAX_DEPTH || state.nodes > FLAG_CONDITION_MAX_NODES;
+}
+
+function parseFlagNegationCondition(
+  condition: Readonly<Record<string, unknown>>,
+  depth: number,
+  state: { nodes: number }
+): CheckFlagCondition | undefined {
+  if (!hasOnlyKeys(condition, ["condition", "kind"]) || !Object.hasOwn(condition, "condition")) {
+    return undefined;
+  }
+  const child = parseBoundedFlagCondition(condition.condition, depth + 1, state);
+  return child === undefined ? undefined : Object.freeze({ condition: child, kind: "not" });
+}
+
+function parseFlagConditionSet(
+  condition: Readonly<Record<string, unknown>>,
+  kind: string,
+  depth: number,
+  state: { nodes: number }
+): CheckFlagCondition | undefined {
+  if (!isFlagConditionSetKind(kind)) return undefined;
+  const conditions = parseFlagConditionChildren(condition, depth, state);
+  return conditions === undefined ? undefined : Object.freeze({ kind, conditions });
+}
+
+function parseFlagConditionChildren(
+  condition: Readonly<Record<string, unknown>>,
+  depth: number,
+  state: { nodes: number }
+): readonly [CheckFlagCondition, ...CheckFlagCondition[]] | undefined {
+  if (!hasOnlyKeys(condition, ["conditions", "kind"]) || !Object.hasOwn(condition, "conditions")) {
+    return undefined;
+  }
+  const children = snapshotClosedArray(condition.conditions);
+  if (children === undefined || children.length === 0) return undefined;
+  const normalized: CheckFlagCondition[] = [];
+  for (const child of children) {
+    const parsed = parseBoundedFlagCondition(child, depth + 1, state);
+    if (parsed === undefined) return undefined;
+    normalized.push(parsed);
+  }
+  const [firstCondition, ...remainingConditions] = normalized;
+  return firstCondition === undefined
+    ? undefined
+    : Object.freeze([firstCondition, ...remainingConditions]);
+}
+
+function isNonEmptyIdentifier(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function isFlagConditionSetKind(
+  value: string
+): value is "all" | "any" | "none" | "not-all" | "exactly-one" {
+  return (
+    value === "all" ||
+    value === "any" ||
+    value === "none" ||
+    value === "not-all" ||
+    value === "exactly-one"
+  );
+}

package/src/project-definition/check-tree/materialization.ts

@@ -1,4 +1,5 @@
 import { inherit, type Check, type InheritableCheckCollection } from "../../check/check.ts";
+import { bindHandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import type { ParsedCheck, ParsedCheckCollection, ParsedCheckTree } from "./authoring.ts";
 
 /** Rebuilds the validated public authoring shape without retaining untyped input. */
@@ -16,8 +17,8 @@ function materializeCheck(check: ParsedCheck): Check {
   const enabledByFlags = check.enabledByFlags;
   const mutex = materializeCollection(check.mutex);
   const observes = materializeCollection(check.observes);
-  const visibility = check.visibility;
-  const preflight = check.preflight;
+  const omitQuietPassedRow = check.omitQuietPassedRow;
+  const preparation = check.prepare;
   const scheduling = {
     ...(check.admissionPriority === undefined
       ? {}
@@ -30,9 +31,9 @@ function materializeCheck(check: ParsedCheck): Check {
   };
   if (
     check.definition === null ||
-    check.execution === null ||
+    check.execute === null ||
     check.options === null ||
-    visibility === null
+    omitQuietPassedRow === null
   ) {
     return Object.freeze({
       checkId: check.checkId,
@@ -41,18 +42,21 @@ function materializeCheck(check: ParsedCheck): Check {
       ...scheduling
     });
   }
-  return Object.freeze({
+  const materialized = Object.freeze({
     checkId: check.checkId,
     checks,
     displayName: check.displayName,
     ...(enabledByFlags === null ? {} : { enabledByFlags }),
-    execution: check.execution,
+    execute: check.execute,
+    ...(check.handoff === null ? {} : { handoff: true }),
     ...(check.parseData === null ? {} : { parseData: check.parseData }),
     options: check.options,
-    ...(preflight === null ? {} : { preflight }),
+    ...(preparation === null ? {} : { prepare: preparation }),
     ...scheduling,
-    visibility
+    ...(omitQuietPassedRow ? { omitQuietPassedRow: true as const } : {})
   });
+  if (check.handoff !== null) bindHandoffProviderIdentity(materialized, check.handoff);
+  return materialized;
 }
 
 function materializeCollection(

package/src/project-definition/check-tree/resolution.ts

@@ -1,10 +1,6 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
-import type {
-  CheckExecution,
-  CheckFlagEnablement,
-  CheckPreflight,
-  CheckVisibility
-} from "../../check/check.ts";
+import type { Check, CheckPreparation, CheckFlagEnablement } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import {
   parseCheckTreeAuthoring,
   type MeaninglessCheckWarning,
@@ -21,14 +17,15 @@ export interface ResolvedCheckTreeLeaf {
   readonly definition: CheckDescriptor;
   readonly dependsOn: readonly string[];
   readonly enabledByFlags?: CheckFlagEnablement;
-  readonly execution: CheckExecution;
+  readonly execute: NonNullable<Check["execute"]>;
+  readonly handoff?: HandoffProviderIdentity;
   readonly maxParallel: number;
   readonly mutex: readonly string[];
   readonly observes: readonly string[];
   readonly options: object;
-  readonly preflight?: CheckPreflight;
+  readonly prepare?: CheckPreparation;
   readonly resourceClaims: ResourceUnitMapping;
-  readonly visibility: CheckVisibility;
+  readonly omitQuietPassedRow: boolean;
 }
 
 export interface ResolvedCheckTree {
@@ -116,26 +113,27 @@ function resolvedLeafFor(
   check: ParsedCheck,
   scheduling: InheritedScheduling
 ): ResolvedCheckTreeLeaf | undefined {
-  const visibility = check.visibility;
+  const omitQuietPassedRow = check.omitQuietPassedRow;
   if (
-    check.execution !== null &&
+    check.execute !== null &&
     check.definition !== null &&
     check.options !== null &&
-    visibility !== null
+    omitQuietPassedRow !== null
   ) {
     return Object.freeze({
       admissionPriority: scheduling.admissionPriority,
       definition: check.definition,
       dependsOn: scheduling.dependsOn,
       ...(check.enabledByFlags === null ? {} : { enabledByFlags: check.enabledByFlags }),
-      execution: check.execution,
+      execute: check.execute,
+      ...(check.handoff === null ? {} : { handoff: check.handoff }),
       maxParallel: scheduling.maxParallel,
       mutex: scheduling.mutex,
       observes: scheduling.observes,
       options: check.options,
-      ...(check.preflight === null ? {} : { preflight: check.preflight }),
+      ...(check.prepare === null ? {} : { prepare: check.prepare }),
       resourceClaims: scheduling.resourceClaims,
-      visibility
+      omitQuietPassedRow
     });
   }
   return undefined;

package/src/project-definition/declarative-snapshot.ts

@@ -9,20 +9,27 @@ import type {
 } from "./project-definition.ts";
 import { resolveProgressRenderingOutput } from "./output-defaults.ts";
 import { isNonArrayRecord } from "../data-boundary/value-shapes.ts";
+import type { NormalizedProjectChangesConfiguration } from "./project-changes.ts";
 
 /**
  * Produces the immutable, callback-free Definition identity consumed by fingerprinting.
  */
 export function createDeclarativeProjectSnapshot(
-  definition: ProjectDefinition,
+  definition: Omit<ProjectDefinition, "changes"> & {
+    readonly changes?: NormalizedProjectChangesConfiguration;
+  },
   checks: readonly NormalizedCheck[]
 ): DeclarativeProjectSnapshot {
   const declarations = checks
-    .map(({ execution: _execution, preflight: _preflight, ...declaration }) => declaration)
+    .map(
+      ({ execute: _execution, handoff: _handoff, prepare: _preparation, ...declaration }) =>
+        declaration
+    )
     .sort((left, right) => compareText(left.definition.checkId, right.definition.checkId));
   return deepFreeze({
     apiVersion: definition.apiVersion,
     checks: declarations,
+    ...(definition.changes === undefined ? {} : { changes: definition.changes }),
     outputs: declarativeOutputs(definition),
     scheduler: Object.freeze({
       admissionPolicy: declarativeAdmissionPolicy(definition.scheduler.admissionPolicy),

package/src/project-definition/project-changes.ts

@@ -0,0 +1,112 @@
+import {
+  hasExactPlainRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedPolicyRecord,
+  snapshotClosedRecord
+} from "../data-boundary/closed-values.ts";
+
+/** Project 自有的 Git comparison，用于为一次 Run 推导 change flags。 */
+export interface ProjectChangeSource {
+  /** 作为 comparison base 的 Git revision。 */
+  readonly compareWith: string;
+}
+
+/** 一个 change flag 的 project-root-relative、exclude-first glob region。 */
+export interface ProjectChangeFlagRegion {
+  /** 可省略的排除 glob；省略等同空数组，显式 undefined 不是合法数组。 */
+  readonly exclude?: readonly string[];
+  readonly include: readonly string[];
+}
+
+/** 由 Project Definition 拥有的静态 change preparation 配置。 */
+export interface ProjectChangesConfiguration {
+  readonly source: ProjectChangeSource;
+  /** 至少一个非空 author ID 到其匹配 region 的映射。 */
+  readonly flags: Readonly<Record<string, ProjectChangeFlagRegion>>;
+}
+
+/** Definition 已验证、补齐并冻结的 region；Run 不再解释 authoring defaults。 */
+export interface NormalizedProjectChangeFlagRegion extends ProjectChangeFlagRegion {
+  readonly exclude: readonly string[];
+}
+
+/** 仅供 Definition snapshot 与 Run 消费的完整 change 配置。 */
+export interface NormalizedProjectChangesConfiguration extends ProjectChangesConfiguration {
+  readonly flags: Readonly<Record<string, NormalizedProjectChangeFlagRegion>>;
+}
+
+/**
+ * 解析并冻结 change preparation 的 closed Definition grammar。
+ * Runtime Git acquisition 与 region matching 有各自的 Run owner，不在此边界执行。
+ */
+export function parseProjectChangesConfiguration(
+  value: unknown
+): NormalizedProjectChangesConfiguration | undefined {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined || !hasExactPlainRecordKeys(data, ["flags", "source"])) return undefined;
+  const source = parseSource(data.source);
+  const flags = parseFlags(data.flags);
+  return source === undefined || flags === undefined ? undefined : Object.freeze({ flags, source });
+}
+
+function parseSource(value: unknown): ProjectChangeSource | undefined {
+  const source = snapshotClosedRecord(value);
+  if (
+    source === undefined ||
+    !hasExactPlainRecordKeys(source, ["compareWith"]) ||
+    !isGitComparisonRevision(source.compareWith)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ compareWith: source.compareWith });
+}
+
+function parseFlags(
+  value: unknown
+): Readonly<Record<string, NormalizedProjectChangeFlagRegion>> | undefined {
+  const flags = snapshotClosedRecord(value);
+  if (flags === undefined || Object.keys(flags).length === 0) return undefined;
+  const parsed: Record<string, NormalizedProjectChangeFlagRegion> = {};
+  for (const [flagId, region] of Object.entries(flags)) {
+    if (!isNonEmptyString(flagId)) return undefined;
+    const normalizedRegion = parseRegion(region);
+    if (normalizedRegion === undefined) return undefined;
+    Object.defineProperty(parsed, flagId, {
+      configurable: false,
+      enumerable: true,
+      value: normalizedRegion,
+      writable: false
+    });
+  }
+  return Object.freeze(parsed);
+}
+
+function parseRegion(value: unknown): NormalizedProjectChangeFlagRegion | undefined {
+  const region = snapshotClosedPolicyRecord(value, {
+    optional: ["exclude"],
+    required: ["include"]
+  });
+  if (region === undefined) return undefined;
+  const exclude = Object.hasOwn(region, "exclude")
+    ? parseStringArray(region.exclude)
+    : Object.freeze([]);
+  const include = parseStringArray(region.include);
+  return exclude === undefined || include === undefined
+    ? undefined
+    : Object.freeze({ exclude, include });
+}
+
+function parseStringArray(value: unknown): readonly string[] | undefined {
+  const values = snapshotClosedArray(value);
+  return values === undefined || !values.every(isNonEmptyString)
+    ? undefined
+    : Object.freeze([...values]);
+}
+
+function isGitComparisonRevision(value: unknown): value is string {
+  return isNonEmptyString(value) && !value.startsWith("-") && !value.includes("\0");
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}

package/src/project-definition/project-definition-validation.ts

@@ -7,7 +7,8 @@ import {
   type ProjectDefinitionValidationResult,
   type AdmissionPolicy,
   type CustomAdmissionStrategy,
-  type SchedulerMeasurementHook,
+  type NormalizedCheck,
+  type SchedulerTerminalEffect,
   type SchedulerPolicy
 } from "./project-definition.ts";
 import {
@@ -16,13 +17,20 @@ import {
   snapshotClosedRecord
 } from "../data-boundary/closed-values.ts";
 import { snapshotResourceUnitMapping } from "./resource-unit-mapping.ts";
+import { parseProjectChangesConfiguration } from "./project-changes.ts";
 
 type DefinitionValidationResult<T> = Readonly<
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: ProjectDefinitionDiagnostic }
 >;
 
-const PROJECT_DEFINITION_KEYS = ["apiVersion", "checks", "outputs", "scheduler"] as const;
+const PROJECT_DEFINITION_KEYS = [
+  "apiVersion",
+  "changes",
+  "checks",
+  "outputs",
+  "scheduler"
+] as const;
 
 /**
  * Validates one closed Definition before Run can invoke any project callback.
@@ -47,6 +55,12 @@ function parseProjectDefinitionFields(
 ): ProjectDefinitionValidationResult {
   const scheduler = parseScheduler(data.scheduler);
   if (scheduler === undefined) return invalidDefinition("definition.scheduler");
+  const changes = Object.hasOwn(data, "changes")
+    ? parseProjectChangesConfiguration(data.changes)
+    : undefined;
+  if (Object.hasOwn(data, "changes") && changes === undefined) {
+    return invalidDefinition("definition.changes");
+  }
   const checks = snapshotClosedArray(data.checks);
   if (checks === undefined) return invalidDefinition("definition.checks");
   const parsedChecks = parseCheckTreeAuthoring(checks);
@@ -57,6 +71,9 @@ function parseProjectDefinitionFields(
     scheduler.resourceCapacities
   );
   if (tree === undefined) return invalidDefinition("definition.checks");
+  if (!hasOnlyKnownChangeFlagReferences(tree.leaves, changes)) {
+    return invalidDefinition("definition.checks");
+  }
   const outputs = parseOutputs(data.outputs);
   if (outputs === undefined) return invalidDefinition("definition.outputs");
   return Object.freeze({
@@ -64,6 +81,7 @@ function parseProjectDefinitionFields(
     value: {
       apiVersion: "1" as const,
       checks: materializeCheckTreeAuthoring(parsedChecks),
+      ...(changes === undefined ? {} : { changes }),
       outputs,
       scheduler
     },
@@ -71,6 +89,36 @@ function parseProjectDefinitionFields(
   });
 }
 
+function hasOnlyKnownChangeFlagReferences(
+  checks: readonly NormalizedCheck[],
+  changes: ReturnType<typeof parseProjectChangesConfiguration>
+): boolean {
+  return checks.every(
+    (check) =>
+      check.enabledByFlags === undefined ||
+      hasOnlyKnownChangeFlagConditionReferences(check.enabledByFlags.when, changes)
+  );
+}
+
+function hasOnlyKnownChangeFlagConditionReferences(
+  condition: import("../check/check.ts").CheckFlagCondition,
+  changes: ReturnType<typeof parseProjectChangesConfiguration>
+): boolean {
+  if (typeof condition === "string") {
+    const prefix = "vibe-check:change:";
+    return (
+      !condition.startsWith(prefix) ||
+      (changes !== undefined && Object.hasOwn(changes.flags, condition.slice(prefix.length)))
+    );
+  }
+  if (condition.kind === "not") {
+    return hasOnlyKnownChangeFlagConditionReferences(condition.condition, changes);
+  }
+  return condition.conditions.every((child) =>
+    hasOnlyKnownChangeFlagConditionReferences(child, changes)
+  );
+}
+
 function exactProjectDefinition(
   value: unknown
 ): DefinitionValidationResult<Readonly<Record<string, unknown>>> {
@@ -101,7 +149,7 @@ function exactRecord(
 
 function parseScheduler(value: unknown): SchedulerPolicy | undefined {
   const data = snapshotClosedPolicyRecord(value, {
-    optional: ["admissionPolicy", "measurementHooks", "resourceCapacities"],
+    optional: ["admissionPolicy", "terminalEffects", "resourceCapacities"],
     required: ["maxParallel"]
   });
   if (data === undefined) return undefined;
@@ -109,33 +157,33 @@ function parseScheduler(value: unknown): SchedulerPolicy | undefined {
     ? parseAdmissionPolicy(data.admissionPolicy)
     : Object.freeze({ kind: "static" as const });
   if (admissionPolicy === undefined) return undefined;
-  const measurementHooks = parseMeasurementHooks(data.measurementHooks);
-  if (measurementHooks === undefined) return undefined;
+  const terminalEffects = parseTerminalEffects(data.terminalEffects);
+  if (terminalEffects === undefined) return undefined;
   const resourceCapacities = snapshotResourceUnitMapping(
     Object.hasOwn(data, "resourceCapacities") ? data.resourceCapacities : {}
   );
   if (resourceCapacities === undefined) return undefined;
   const maxParallel = positiveSafeInteger(data.maxParallel);
   if (maxParallel === undefined) return undefined;
-  return Object.freeze({ admissionPolicy, maxParallel, measurementHooks, resourceCapacities });
+  return Object.freeze({ admissionPolicy, maxParallel, terminalEffects, resourceCapacities });
 }
 
 function positiveSafeInteger(value: unknown): number | undefined {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
 }
 
-function parseMeasurementHooks(value: unknown): readonly SchedulerMeasurementHook[] | undefined {
+function parseTerminalEffects(value: unknown): readonly SchedulerTerminalEffect[] | undefined {
   if (value === undefined) return Object.freeze([]);
   if (!Array.isArray(value)) return undefined;
-  const hooks: SchedulerMeasurementHook[] = [];
+  const hooks: SchedulerTerminalEffect[] = [];
   for (const hook of value) {
-    if (!isMeasurementHook(hook)) return undefined;
+    if (!isTerminalEffect(hook)) return undefined;
     hooks.push(hook);
   }
   return Object.freeze(hooks);
 }
 
-function isMeasurementHook(value: unknown): value is SchedulerMeasurementHook {
+function isTerminalEffect(value: unknown): value is SchedulerTerminalEffect {
   return typeof value === "function";
 }