@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/project-definition/check-tree/check-fields-authoring.ts

@@ -0,0 +1,242 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import { type Check, type CheckFlagEnablement, type CheckPreparation } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
+import { validateCheckDescriptor } from "../../check/descriptor-validation.ts";
+import { snapshotJsonObject } from "../../check/options-snapshot.ts";
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { hasOnlyKeys, parseFlagCondition } from "./flag-conditions.ts";
+
+export type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
+
+export interface CheckAuthoringData extends Readonly<Record<string, unknown>> {
+  readonly checkId: string;
+  readonly displayName: string;
+}
+
+export interface ParsedCheckFields {
+  readonly definition: CheckDescriptor | null;
+  readonly enabledByFlags: CheckFlagEnablement | null;
+  readonly execute: NonNullable<Check["execute"]> | null;
+  readonly handoff: HandoffProviderIdentity | null;
+  readonly options: object | null;
+  readonly parseData: TrustedDataParser | null;
+  readonly prepare: CheckPreparation | null;
+  readonly omitQuietPassedRow: boolean | null;
+}
+
+export interface ParsedCheckFieldPrelude {
+  readonly enabledByFlags: CheckFlagEnablement | null;
+  readonly execute: NonNullable<Check["execute"]> | null;
+  readonly handoff: HandoffProviderIdentity | null;
+  readonly parseData: TrustedDataParser | null;
+  readonly prepare: CheckPreparation | null;
+}
+
+const CHECK_KEYS = [
+  "admissionPriority",
+  "checkId",
+  "checks",
+  "dependsOn",
+  "displayName",
+  "enabledByFlags",
+  "execute",
+  "handoff",
+  "maxParallel",
+  "mutex",
+  "options",
+  "observes",
+  "parseData",
+  "prepare",
+  "resourceClaims",
+  "omitQuietPassedRow"
+] as const;
+const FLAG_ENABLEMENT_EXPRESSION_KEYS = ["when", "propagateDependsOn"] as const;
+
+const CONTAINER_CHECK_FIELDS: ParsedCheckFields = Object.freeze({
+  definition: null,
+  enabledByFlags: null,
+  execute: null,
+  handoff: null,
+  options: null,
+  parseData: null,
+  prepare: null,
+  omitQuietPassedRow: null
+});
+
+export function parseCheckAuthoringData(value: unknown): CheckAuthoringData | undefined {
+  const data = snapshotClosedRecord(value);
+  return data !== undefined && hasValidCheckIdentity(data) ? data : undefined;
+}
+
+function hasValidCheckIdentity(
+  data: Readonly<Record<string, unknown>>
+): data is CheckAuthoringData {
+  return (
+    hasOnlyCheckKeys(data) &&
+    typeof data.checkId === "string" &&
+    data.checkId.length > 0 &&
+    typeof data.displayName === "string" &&
+    data.displayName.length > 0
+  );
+}
+
+export function parseCheckFieldPrelude(
+  data: CheckAuthoringData,
+  handoffProviderIdentity: HandoffProviderIdentity | undefined
+): ParsedCheckFieldPrelude | undefined {
+  const execution = parseExecution(data);
+  if (execution === undefined) return undefined;
+  const handoff = parseHandoff(data, handoffProviderIdentity);
+  if (handoff === undefined) return undefined;
+  const parseData = parseDataParser(data);
+  if (parseData === undefined) return undefined;
+  const preparation = parsePreparation(data);
+  if (preparation === undefined) return undefined;
+  const enabledByFlags = parseEnabledByFlags(data);
+  return enabledByFlags === undefined
+    ? undefined
+    : Object.freeze({
+        enabledByFlags,
+        execute: execution,
+        handoff,
+        parseData,
+        prepare: preparation
+      });
+}
+
+export function parseCheckFields(
+  data: CheckAuthoringData,
+  prelude: ParsedCheckFieldPrelude
+): ParsedCheckFields | undefined {
+  if (prelude.execute === null) {
+    return containerHasExecutableFields(data, prelude) ? undefined : CONTAINER_CHECK_FIELDS;
+  }
+  return parseExecutableCheckFields(data, prelude);
+}
+
+/** Container nodes cannot carry values that only an executable callback can consume. */
+function containerHasExecutableFields(
+  data: CheckAuthoringData,
+  prelude: ParsedCheckFieldPrelude
+): boolean {
+  return (
+    Object.hasOwn(data, "options") ||
+    Object.hasOwn(data, "enabledByFlags") ||
+    prelude.handoff !== null ||
+    Object.hasOwn(data, "omitQuietPassedRow") ||
+    prelude.parseData !== null ||
+    prelude.prepare !== null
+  );
+}
+
+/** Parses the callback-owned fields that form one executable Check definition. */
+function parseExecutableCheckFields(
+  data: CheckAuthoringData,
+  prelude: ParsedCheckFieldPrelude
+): ParsedCheckFields | undefined {
+  const definition = parseDefinition(data);
+  if (definition === undefined) return undefined;
+  const options = parseOptions(data);
+  if (options === undefined) return undefined;
+  const omitQuietPassedRow = parseOmitQuietPassedRow(data);
+  if (omitQuietPassedRow === undefined) return undefined;
+  return Object.freeze({
+    definition,
+    enabledByFlags: prelude.enabledByFlags,
+    execute: prelude.execute,
+    handoff: prelude.handoff,
+    options,
+    parseData: prelude.parseData,
+    prepare: prelude.prepare,
+    omitQuietPassedRow
+  });
+}
+
+function hasOnlyCheckKeys(data: Readonly<Record<string, unknown>>): boolean {
+  return Object.keys(data).every((key) => CHECK_KEYS.some((checkKey) => checkKey === key));
+}
+
+function parseExecution(
+  data: CheckAuthoringData
+): NonNullable<Check["execute"]> | null | undefined {
+  if (!Object.hasOwn(data, "execute")) return null;
+  return isTrustedFunction<NonNullable<Check["execute"]>>(data.execute) ? data.execute : undefined;
+}
+
+function parseHandoff(
+  data: CheckAuthoringData,
+  handoffProviderIdentity: HandoffProviderIdentity | undefined
+): HandoffProviderIdentity | null | undefined {
+  if (!Object.hasOwn(data, "handoff")) return null;
+  return data.handoff === true && handoffProviderIdentity !== undefined
+    ? handoffProviderIdentity
+    : undefined;
+}
+
+function parseDataParser(data: CheckAuthoringData): TrustedDataParser | null | undefined {
+  if (!Object.hasOwn(data, "parseData") || data.parseData === undefined) return null;
+  return isTrustedFunction<TrustedDataParser>(data.parseData) ? data.parseData : undefined;
+}
+
+function parsePreparation(data: CheckAuthoringData): CheckPreparation | null | undefined {
+  if (!Object.hasOwn(data, "prepare")) return null;
+  return isTrustedFunction<CheckPreparation>(data.prepare) ? data.prepare : undefined;
+}
+
+function isTrustedFunction<FunctionType extends (...parameters: never[]) => unknown>(
+  value: unknown
+): value is FunctionType {
+  return typeof value === "function";
+}
+
+function parseDefinition(data: CheckAuthoringData): CheckDescriptor | undefined {
+  const definition = validateCheckDescriptor({
+    checkId: data.checkId,
+    displayName: data.displayName
+  });
+  return definition.ok ? definition.value : undefined;
+}
+
+function parseOptions(data: CheckAuthoringData): object | undefined {
+  if (!Object.hasOwn(data, "options")) return Object.freeze({});
+  const options = snapshotClosedRecord(data.options);
+  if (options === undefined) return undefined;
+  return snapshotJsonObject(options);
+}
+
+function parseEnabledByFlags(data: CheckAuthoringData): CheckFlagEnablement | null | undefined {
+  if (!Object.hasOwn(data, "enabledByFlags")) return null;
+  return parseFlagEnablementControl(data.enabledByFlags);
+}
+
+/** Parses one closed flag-enablement field without validating its Project flag references. */
+export function parseFlagEnablementControl(value: unknown): CheckFlagEnablement | undefined {
+  const control = snapshotClosedRecord(value);
+  if (
+    control === undefined ||
+    !hasOnlyKeys(control, FLAG_ENABLEMENT_EXPRESSION_KEYS) ||
+    !Object.hasOwn(control, "when")
+  ) {
+    return undefined;
+  }
+  const when = parseFlagCondition(control.when);
+  const propagateDependsOn = parsePropagation(control);
+  return when === undefined || propagateDependsOn === undefined
+    ? undefined
+    : Object.freeze({
+        when,
+        ...(propagateDependsOn ? { propagateDependsOn: true as const } : {})
+      });
+}
+
+function parsePropagation(control: Readonly<Record<string, unknown>>): boolean | undefined {
+  if (!Object.hasOwn(control, "propagateDependsOn")) return false;
+  return control.propagateDependsOn === true ? true : undefined;
+}
+
+function parseOmitQuietPassedRow(data: CheckAuthoringData): boolean | undefined {
+  if (!Object.hasOwn(data, "omitQuietPassedRow")) return false;
+  return data.omitQuietPassedRow === undefined || data.omitQuietPassedRow === true
+    ? (data.omitQuietPassedRow ?? false)
+    : undefined;
+}

package/src/project-definition/check-tree/collection-authoring.ts

@@ -0,0 +1,13 @@
+import { snapshotClosedArray } from "../../data-boundary/closed-values.ts";
+
+/** Snapshots one closed array as unique, non-empty authored identifiers. */
+export function parseUniqueIdentifiers(value: unknown): readonly string[] | undefined {
+  const items = snapshotClosedArray(value);
+  if (items === undefined) return undefined;
+  const identifiers: string[] = [];
+  for (const item of items) {
+    if (typeof item !== "string" || item.length === 0) return undefined;
+    if (!identifiers.includes(item)) identifiers.push(item);
+  }
+  return Object.freeze(identifiers);
+}

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. */
@@ -13,19 +14,26 @@ function materializeChecks(checks: readonly ParsedCheck[]): readonly Check[] {
 function materializeCheck(check: ParsedCheck): Check {
   const checks = materializeChecks(check.checks);
   const dependsOn = materializeCollection(check.dependsOn);
+  const enabledByFlags = check.enabledByFlags;
   const mutex = materializeCollection(check.mutex);
-  const visibility = check.visibility;
-  const preflight = check.preflight;
+  const observes = materializeCollection(check.observes);
+  const omitQuietPassedRow = check.omitQuietPassedRow;
+  const preparation = check.prepare;
   const scheduling = {
+    ...(check.admissionPriority === undefined
+      ? {}
+      : { admissionPriority: check.admissionPriority }),
     ...(dependsOn === undefined ? {} : { dependsOn }),
     ...(check.maxParallel === undefined ? {} : { maxParallel: check.maxParallel }),
-    ...(mutex === undefined ? {} : { mutex })
+    ...(mutex === undefined ? {} : { mutex }),
+    ...(observes === undefined ? {} : { observes }),
+    ...(check.resourceClaims === undefined ? {} : { resourceClaims: check.resourceClaims })
   };
   if (
     check.definition === null ||
-    check.execution === null ||
+    check.execute === null ||
     check.options === null ||
-    visibility === null
+    omitQuietPassedRow === null
   ) {
     return Object.freeze({
       checkId: check.checkId,
@@ -34,17 +42,21 @@ function materializeCheck(check: ParsedCheck): Check {
       ...scheduling
     });
   }
-  return Object.freeze({
+  const materialized = Object.freeze({
     checkId: check.checkId,
     checks,
     displayName: check.displayName,
-    execution: check.execution,
+    ...(enabledByFlags === null ? {} : { enabledByFlags }),
+    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,5 +1,6 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
-import type { CheckExecution, 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,
@@ -7,18 +8,24 @@ import {
   type ParsedCheckCollection,
   type ParsedCheckTree
 } from "./authoring.ts";
+import { EMPTY_RESOURCE_UNIT_MAPPING, type ResourceUnitMapping } from "../resource-unit-mapping.ts";
 
 export type { Check, InheritableCheckCollection } from "../../check/check.ts";
 
 export interface ResolvedCheckTreeLeaf {
+  readonly admissionPriority: number;
   readonly definition: CheckDescriptor;
   readonly dependsOn: readonly string[];
-  readonly execution: CheckExecution;
+  readonly enabledByFlags?: CheckFlagEnablement;
+  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 visibility: CheckVisibility;
+  readonly prepare?: CheckPreparation;
+  readonly resourceClaims: ResourceUnitMapping;
+  readonly omitQuietPassedRow: boolean;
 }
 
 export interface ResolvedCheckTree {
@@ -27,9 +34,12 @@ export interface ResolvedCheckTree {
 }
 
 interface InheritedScheduling {
+  readonly admissionPriority: number;
   readonly dependsOn: readonly string[];
   readonly maxParallel: number;
   readonly mutex: readonly string[];
+  readonly observes: readonly string[];
+  readonly resourceClaims: ResourceUnitMapping;
 }
 
 /**
@@ -39,58 +49,104 @@ interface InheritedScheduling {
  */
 export function resolveCheckTree(
   value: unknown,
-  rootMaxParallel: number
+  rootMaxParallel: number,
+  resourceCapacities: ResourceUnitMapping = EMPTY_RESOURCE_UNIT_MAPPING
 ): ResolvedCheckTree | undefined {
   const parsed = parseCheckTreeAuthoring(value);
-  return parsed === undefined ? undefined : resolveParsedCheckTree(parsed, rootMaxParallel);
+  return parsed === undefined
+    ? undefined
+    : resolveParsedCheckTree(parsed, rootMaxParallel, resourceCapacities);
 }
 
 export function resolveParsedCheckTree(
   parsed: ParsedCheckTree,
-  rootMaxParallel: number
+  rootMaxParallel: number,
+  resourceCapacities: ResourceUnitMapping = EMPTY_RESOURCE_UNIT_MAPPING
 ): ResolvedCheckTree | undefined {
   if (!Number.isSafeInteger(rootMaxParallel) || rootMaxParallel <= 0) return undefined;
   const leaves: ResolvedCheckTreeLeaf[] = [];
   const root: InheritedScheduling = Object.freeze({
+    admissionPriority: 0,
     dependsOn: Object.freeze([]),
     maxParallel: rootMaxParallel,
-    mutex: Object.freeze([])
+    mutex: Object.freeze([]),
+    observes: Object.freeze([]),
+    resourceClaims: EMPTY_RESOURCE_UNIT_MAPPING
   });
-  for (const check of parsed.checks) flattenCheck(check, root, leaves);
+  for (const check of parsed.checks) {
+    if (!flattenCheck(check, root, resourceCapacities, leaves)) return undefined;
+  }
   return Object.freeze({ leaves: Object.freeze(leaves), warnings: parsed.warnings });
 }
 
 function flattenCheck(
   check: ParsedCheck,
   inherited: InheritedScheduling,
+  resourceCapacities: ResourceUnitMapping,
   leaves: ResolvedCheckTreeLeaf[]
-): void {
-  const scheduling: InheritedScheduling = Object.freeze({
+): boolean {
+  const scheduling = resolveScheduling(check, inherited);
+  if (!claimsFitCapacities(scheduling.resourceClaims, resourceCapacities)) return false;
+  const leaf = resolvedLeafFor(check, scheduling);
+  if (leaf !== undefined) leaves.push(leaf);
+  for (const child of check.checks) {
+    if (!flattenCheck(child, scheduling, resourceCapacities, leaves)) return false;
+  }
+  return true;
+}
+
+function resolveScheduling(
+  check: ParsedCheck,
+  inherited: InheritedScheduling
+): InheritedScheduling {
+  return Object.freeze({
+    admissionPriority: check.admissionPriority ?? inherited.admissionPriority,
     dependsOn: resolveCollection(inherited.dependsOn, check.dependsOn),
     maxParallel: check.maxParallel ?? inherited.maxParallel,
-    mutex: resolveCollection(inherited.mutex, check.mutex)
+    mutex: resolveCollection(inherited.mutex, check.mutex),
+    observes: resolveCollection(inherited.observes, check.observes),
+    resourceClaims: check.resourceClaims ?? inherited.resourceClaims
   });
-  const visibility = check.visibility;
+}
+
+function resolvedLeafFor(
+  check: ParsedCheck,
+  scheduling: InheritedScheduling
+): ResolvedCheckTreeLeaf | undefined {
+  const omitQuietPassedRow = check.omitQuietPassedRow;
   if (
-    check.execution !== null &&
+    check.execute !== null &&
     check.definition !== null &&
     check.options !== null &&
-    visibility !== null
+    omitQuietPassedRow !== null
   ) {
-    leaves.push(
-      Object.freeze({
-        definition: check.definition,
-        dependsOn: scheduling.dependsOn,
-        execution: check.execution,
-        maxParallel: scheduling.maxParallel,
-        mutex: scheduling.mutex,
-        options: check.options,
-        ...(check.preflight === null ? {} : { preflight: check.preflight }),
-        visibility
-      })
-    );
+    return Object.freeze({
+      admissionPriority: scheduling.admissionPriority,
+      definition: check.definition,
+      dependsOn: scheduling.dependsOn,
+      ...(check.enabledByFlags === null ? {} : { enabledByFlags: check.enabledByFlags }),
+      execute: check.execute,
+      ...(check.handoff === null ? {} : { handoff: check.handoff }),
+      maxParallel: scheduling.maxParallel,
+      mutex: scheduling.mutex,
+      observes: scheduling.observes,
+      options: check.options,
+      ...(check.prepare === null ? {} : { prepare: check.prepare }),
+      resourceClaims: scheduling.resourceClaims,
+      omitQuietPassedRow
+    });
   }
-  for (const child of check.checks) flattenCheck(child, scheduling, leaves);
+  return undefined;
+}
+
+function claimsFitCapacities(
+  claims: ResourceUnitMapping,
+  capacities: ResourceUnitMapping
+): boolean {
+  return Object.entries(claims).every(
+    ([resourceId, units]) =>
+      Object.hasOwn(capacities, resourceId) && units <= (capacities[resourceId] ?? 0)
+  );
 }
 
 function resolveCollection(