@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -0,0 +1,114 @@
+import {
+  isInheritedCheckCollection,
+  snapshotInheritedCheckCollection,
+  type InheritedCheckCollection
+} from "../../check/check.ts";
+import { parseUniqueIdentifiers } from "./collection-authoring.ts";
+import { snapshotResourceUnitMapping, type ResourceUnitMapping } from "../resource-unit-mapping.ts";
+
+export type ParsedCheckCollection = Readonly<
+  | { readonly kind: "exact"; readonly values: readonly string[] }
+  | {
+      readonly kind: "inherit";
+      readonly add: readonly string[];
+      readonly remove: readonly string[];
+    }
+>;
+
+export type ParsedCheckScheduling = Readonly<{
+  readonly admissionPriority: number | undefined;
+  readonly dependsOn: ParsedCheckCollection | undefined;
+  readonly maxParallel: number | undefined;
+  readonly mutex: ParsedCheckCollection | undefined;
+  readonly observes: ParsedCheckCollection | undefined;
+  readonly resourceClaims: ResourceUnitMapping | undefined;
+}>;
+
+/** Parses the closed relation, priority, and capacity fields for one authored Check. */
+export function parseCheckScheduling(
+  data: Readonly<Record<string, unknown>>
+): ParsedCheckScheduling | undefined {
+  const dependsOn = parseCollection(data, "dependsOn");
+  const mutex = parseCollection(data, "mutex");
+  const observes = parseCollection(data, "observes");
+  const admissionPriority = parseAdmissionPriority(data.admissionPriority);
+  const maxParallel = parseMaxParallel(data.maxParallel);
+  const resourceClaims =
+    data.resourceClaims === undefined
+      ? undefined
+      : snapshotResourceUnitMapping(data.resourceClaims);
+  if (dependsOn === null || mutex === null || observes === null) return undefined;
+  if (
+    admissionPriority === null ||
+    maxParallel === null ||
+    (data.resourceClaims !== undefined && resourceClaims === undefined)
+  ) {
+    return undefined;
+  }
+  return resolvedScheduling({
+    admissionPriority,
+    dependsOn,
+    maxParallel,
+    mutex,
+    observes,
+    resourceClaims
+  });
+}
+
+function resolvedScheduling(
+  scheduling: Readonly<{
+    readonly admissionPriority: number | undefined;
+    readonly dependsOn: ParsedCheckCollection | undefined;
+    readonly maxParallel: number | undefined;
+    readonly mutex: ParsedCheckCollection | undefined;
+    readonly observes: ParsedCheckCollection | undefined;
+    readonly resourceClaims: ResourceUnitMapping | undefined;
+  }>
+): ParsedCheckScheduling {
+  return Object.freeze({
+    admissionPriority: scheduling.admissionPriority,
+    dependsOn: scheduling.dependsOn ?? undefined,
+    maxParallel: scheduling.maxParallel,
+    mutex: scheduling.mutex ?? undefined,
+    observes: scheduling.observes ?? undefined,
+    resourceClaims: scheduling.resourceClaims
+  });
+}
+
+function parseAdmissionPriority(value: unknown): number | null | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+
+function parseMaxParallel(value: unknown): number | null | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+
+function parseCollection(
+  data: Readonly<Record<string, unknown>>,
+  field: "dependsOn" | "mutex" | "observes"
+): ParsedCheckCollection | null | undefined {
+  if (!Object.hasOwn(data, field)) return undefined;
+  const value = data[field];
+  if (isInheritedCheckCollection(value)) return parseInheritedCollection(value);
+  const values = parseUniqueIdentifiers(value);
+  return values === undefined ? null : Object.freeze({ kind: "exact", values });
+}
+
+function parseInheritedCollection(
+  value: InheritedCheckCollection<unknown>
+): ParsedCheckCollection | null {
+  const data = snapshotInheritedCheckCollection(value);
+  if (data === undefined || !hasExactInheritedKeys(data)) return null;
+  const add = data.add === undefined ? Object.freeze([]) : parseUniqueIdentifiers(data.add);
+  const remove =
+    data.remove === undefined ? Object.freeze([]) : parseUniqueIdentifiers(data.remove);
+  if (add === undefined || remove === undefined) return null;
+  return Object.freeze({ kind: "inherit", add, remove });
+}
+
+function hasExactInheritedKeys(data: Readonly<Record<string, unknown>>): boolean {
+  const keys = Object.keys(data);
+  return keys.length > 0 && keys.every((key) => key === "add" || key === "remove");
+}

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

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+
+import type { AdmissionPolicy, DeclarativeSchedulerPolicy } from "./scheduler-policy.ts";
+import type {
+  DeclarativeProjectOutputs,
+  DeclarativeProjectSnapshot,
+  NormalizedCheck,
+  ProjectDefinition
+} 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: Omit<ProjectDefinition, "changes"> & {
+    readonly changes?: NormalizedProjectChangesConfiguration;
+  },
+  checks: readonly NormalizedCheck[]
+): DeclarativeProjectSnapshot {
+  const declarations = checks
+    .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),
+      maxParallel: definition.scheduler.maxParallel,
+      resourceCapacities: definition.scheduler.resourceCapacities
+    })
+  });
+}
+
+function declarativeOutputs(definition: ProjectDefinition): DeclarativeProjectOutputs {
+  const progressRendering = resolveProgressRenderingOutput(definition.outputs.progressRendering);
+  return Object.freeze({
+    diagnosticLogging: definition.outputs.diagnosticLogging,
+    machinePublication: definition.outputs.machinePublication,
+    progressRendering: Object.freeze({
+      enabled: progressRendering.enabled,
+      formatter: progressRendering.formatter === null ? "default" : "custom",
+      messagePreviewLimit: progressRendering.messagePreviewLimit,
+      recordPreviewLimit: progressRendering.recordPreviewLimit,
+      textPreviewCodePointLimit: progressRendering.textPreviewCodePointLimit
+    })
+  });
+}
+
+/** Generates the stable SHA-256 fingerprint for one declarative Definition snapshot. */
+export function createDeclarativeFingerprint(snapshot: DeclarativeProjectSnapshot): string {
+  return createHash("sha256").update(stableJson(snapshot)).digest("hex");
+}
+
+function declarativeAdmissionPolicy(
+  policy: AdmissionPolicy
+): DeclarativeSchedulerPolicy["admissionPolicy"] {
+  if (policy.kind === "custom") {
+    return Object.freeze({
+      kind: "custom" as const,
+      strategy: Object.freeze({ kind: policy.strategy.kind })
+    });
+  }
+  return Object.freeze({ kind: "static" as const });
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (isNonArrayRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  return JSON.stringify(value);
+}

package/src/project-definition/output-defaults.ts

@@ -1,6 +1,37 @@
+import type {
+  ProgressRenderingOutput,
+  ResolvedProgressRenderingOutput
+} from "./progress-rendering-output.ts";
+
 /** Default Run-owned output values applied when a Project Definition omits an override. */
 export const DEFAULT_PROJECT_OUTPUTS = Object.freeze({
   machinePublication: Object.freeze({ directory: "artifacts/vibe-check", enabled: true }),
-  progressRendering: Object.freeze({ enabled: true }),
+  progressRendering: Object.freeze({
+    enabled: true,
+    formatter: null,
+    messagePreviewLimit: 5,
+    recordPreviewLimit: 5,
+    textPreviewCodePointLimit: 240
+  }),
   diagnosticLogging: Object.freeze({ directory: ".log/vibe-check", enabled: false })
 } as const);
+
+/** Materializes compatible progress authoring into the single renderer-ready policy. */
+export function resolveProgressRenderingOutput(
+  output: Partial<ProgressRenderingOutput>
+): ResolvedProgressRenderingOutput {
+  const {
+    enabled = DEFAULT_PROJECT_OUTPUTS.progressRendering.enabled,
+    formatter = DEFAULT_PROJECT_OUTPUTS.progressRendering.formatter,
+    messagePreviewLimit = DEFAULT_PROJECT_OUTPUTS.progressRendering.messagePreviewLimit,
+    recordPreviewLimit = DEFAULT_PROJECT_OUTPUTS.progressRendering.recordPreviewLimit,
+    textPreviewCodePointLimit = DEFAULT_PROJECT_OUTPUTS.progressRendering.textPreviewCodePointLimit
+  } = output;
+  return Object.freeze({
+    enabled,
+    formatter,
+    messagePreviewLimit,
+    recordPreviewLimit,
+    textPreviewCodePointLimit
+  });
+}

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

@@ -1,44 +1,44 @@
-import { isAbsolute, relative, resolve, sep } from "node:path";
-
 import type { ProjectOutputs } from "./project-definition.ts";
+import type { ResolvedProgressRenderingOutput } from "./progress-rendering-output.ts";
+import { parseProgressRenderingFields } from "./progress-rendering-output.ts";
 import { snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+import { resolveProgressRenderingOutput } from "./output-defaults.ts";
 
 const OUTPUT_NAMES = ["machinePublication", "progressRendering", "diagnosticLogging"] as const;
-const DIRECTORY_VALIDATION_ROOT = "/vibe-check-validation-root";
 
 export function parseOutputs(value: unknown): ProjectOutputs | undefined {
   const data = exactKeys(value, OUTPUT_NAMES);
   if (data === undefined) return undefined;
   const machinePublication = parseDirectoryOutput(data.machinePublication);
-  const progressRendering = parseSwitchOutput(data.progressRendering);
+  const progressRendering = parseProgressRenderingOutput(data.progressRendering);
   const diagnosticLogging = parseDirectoryOutput(data.diagnosticLogging);
   return machinePublication === undefined ||
     progressRendering === undefined ||
-    diagnosticLogging === undefined ||
-    !isContainedRelativeDirectory(diagnosticLogging.directory)
+    diagnosticLogging === undefined
     ? undefined
     : Object.freeze({ machinePublication, progressRendering, diagnosticLogging });
 }
 
-export function isContainedRelativeDirectory(directory: string): boolean {
-  if (directory.length === 0 || isAbsolute(directory)) return false;
-  const root = resolve(DIRECTORY_VALIDATION_ROOT);
-  const relativeDirectory = relative(root, resolve(root, directory));
-  return relativeDirectory !== ".." && !relativeDirectory.startsWith(`..${sep}`);
+/** Accepts trusted output targets without claiming filesystem containment. */
+export function isOutputDirectory(directory: string): boolean {
+  return directory.length > 0 && !directory.includes("\0");
 }
 
 function parseDirectoryOutput(
   value: unknown
 ): Readonly<{ readonly directory: string; readonly enabled: boolean }> | undefined {
   const data = exactKeys(value, ["directory", "enabled"]);
-  return typeof data?.directory === "string" && typeof data.enabled === "boolean"
+  return typeof data?.directory === "string" &&
+    isOutputDirectory(data.directory) &&
+    typeof data.enabled === "boolean"
     ? Object.freeze({ directory: data.directory, enabled: data.enabled })
     : undefined;
 }
 
-function parseSwitchOutput(value: unknown): Readonly<{ readonly enabled: boolean }> | undefined {
-  const data = exactKeys(value, ["enabled"]);
-  return typeof data?.enabled === "boolean" ? Object.freeze({ enabled: data.enabled }) : undefined;
+function parseProgressRenderingOutput(value: unknown): ResolvedProgressRenderingOutput | undefined {
+  const fields = parseProgressRenderingFields(value);
+  if (!fields.ok || fields.value.enabled === undefined) return undefined;
+  return resolveProgressRenderingOutput(fields.value);
 }
 
 function exactKeys(

package/src/project-definition/progress-rendering-output.ts

@@ -0,0 +1,121 @@
+import { snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+
+/** Progress formatter 只接收当前 selected preview 的默认正文，不接收 Check 或事实对象。 */
+export type ProgressPreviewFormatter = (
+  this: void,
+  context: Readonly<{
+    readonly kind: "record" | "message";
+    readonly text: string;
+    readonly maxCodePoints: number;
+  }>
+) => string;
+
+/** 人读 progress rendering 的作者配置；省略 preview 字段时使用 Product 默认值。 */
+export interface ProgressRenderingOutput {
+  /** `false` 时不构造或写入 progress writer。 */
+  readonly enabled: boolean;
+  /** 每个 settled block 预览的 Record 数量；非负 safe integer，默认 `5`，`0` 只隐藏 detail。 */
+  readonly recordPreviewLimit?: number;
+  /** 每个 settled block 预览的 message 数量；非负 safe integer，默认 `5`，`0` 只隐藏 detail。 */
+  readonly messagePreviewLimit?: number;
+  /** 每条 preview 正文的 Unicode code point 上限；正 safe integer，默认 `240`。 */
+  readonly textPreviewCodePointLimit?: number;
+  /** `null` 或省略保持默认正文；函数返回文本仍由 Product escape 并限制长度。 */
+  readonly formatter?: ProgressPreviewFormatter | null;
+}
+
+/** 已补齐 defaults、可直接交给 progress renderer 的配置。 */
+export interface ResolvedProgressRenderingOutput {
+  readonly enabled: boolean;
+  readonly formatter: ProgressPreviewFormatter | null;
+  readonly messagePreviewLimit: number;
+  readonly recordPreviewLimit: number;
+  readonly textPreviewCodePointLimit: number;
+}
+
+type ProgressRenderingFieldSpec = Readonly<{
+  readonly key: keyof ProgressRenderingOutput;
+  readonly accepts: (value: unknown) => boolean;
+  readonly expected: ProgressRenderingFieldExpectation;
+}>;
+
+/** Closed expectations shared with invocation diagnostics; never contains authored values. */
+export type ProgressRenderingFieldExpectation =
+  | "plain-data-object"
+  | "boolean"
+  | "function-or-null"
+  | "non-negative-safe-integer"
+  | "positive-safe-integer";
+
+type ProgressRenderingFieldsResult = Readonly<
+  | { readonly ok: true; readonly value: Partial<ProgressRenderingOutput> }
+  | {
+      readonly ok: false;
+      readonly key: string | null;
+      readonly reason: "unknown-key" | "invalid-value";
+      readonly expected?: ProgressRenderingFieldExpectation;
+    }
+>;
+
+const PROGRESS_RENDERING_FIELD_SPECS = Object.freeze([
+  { key: "enabled", accepts: isBoolean, expected: "boolean" },
+  { key: "formatter", accepts: isProgressPreviewFormatterOrNull, expected: "function-or-null" },
+  {
+    key: "messagePreviewLimit",
+    accepts: isNonNegativeSafeInteger,
+    expected: "non-negative-safe-integer"
+  },
+  {
+    key: "recordPreviewLimit",
+    accepts: isNonNegativeSafeInteger,
+    expected: "non-negative-safe-integer"
+  },
+  {
+    key: "textPreviewCodePointLimit",
+    accepts: isPositiveSafeInteger,
+    expected: "positive-safe-integer"
+  }
+] satisfies readonly ProgressRenderingFieldSpec[]);
+
+/** Parses the fields shared by Definition output and RunControls override grammar. */
+export function parseProgressRenderingFields(value: unknown): ProgressRenderingFieldsResult {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) {
+    return { ok: false, key: null, reason: "invalid-value", expected: "plain-data-object" };
+  }
+  const unknownKey = Object.keys(data).find(
+    (key) => !PROGRESS_RENDERING_FIELD_SPECS.some((field) => field.key === key)
+  );
+  if (unknownKey !== undefined) return { ok: false, key: unknownKey, reason: "unknown-key" };
+  for (const { key, accepts, expected } of PROGRESS_RENDERING_FIELD_SPECS) {
+    if (data[key] !== undefined && !accepts(data[key])) {
+      return { ok: false, key, reason: "invalid-value", expected };
+    }
+  }
+  return {
+    ok: true,
+    value: Object.freeze(
+      Object.fromEntries(
+        PROGRESS_RENDERING_FIELD_SPECS.flatMap(({ key }) =>
+          data[key] === undefined ? [] : [[key, data[key]]]
+        )
+      ) as Partial<ProgressRenderingOutput>
+    )
+  };
+}
+
+function isBoolean(value: unknown): boolean {
+  return typeof value === "boolean";
+}
+
+function isNonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isPositiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function isProgressPreviewFormatterOrNull(value: unknown): boolean {
+  return value === null || typeof value === "function";
+}

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;
+}