@zxyycom/vibe-check 0.0.1

package/types/project-run/progress-rendering/renderer.d.ts

@@ -0,0 +1,44 @@
+import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+export interface ProgressWriter {
+    readonly color: boolean;
+    readonly isTTY: boolean;
+    readonly term: string | undefined;
+    write(content: string): void;
+}
+export type ProgressFeedback = Readonly<{
+    readonly kind: "prepared";
+    readonly totalChecks: number;
+} | {
+    readonly kind: "started";
+    readonly checkId: string;
+    readonly displayName: string;
+} | {
+    readonly kind: "settled";
+    readonly checkId: string;
+    readonly displayName: string;
+    readonly outcome: CheckOutcome;
+    readonly durationMs: number | null;
+    readonly visibility: CheckVisibility;
+    readonly messages: readonly CheckMessage[];
+} | {
+    readonly kind: "final";
+    readonly execution: "cancelled" | "completed";
+    readonly counts: ProgressOutcomeCounts;
+    readonly elapsedMs: number;
+}>;
+export interface ProgressOutcomeCounts {
+    readonly failed: number;
+    readonly notApplicable: number;
+    readonly passed: number;
+    readonly unavailable: number;
+}
+export interface ProgressRenderer {
+    refresh(): void;
+    readonly refreshesRunningRegion: boolean;
+    render(feedback: ProgressFeedback): void;
+}
+export interface ProgressClock {
+    now(): number;
+}
+/** Product-private lifecycle presentation with one owner for feedback and its writer. */
+export declare function createProgressRenderer(writer: ProgressWriter, clock?: ProgressClock): ProgressRenderer;

package/types/project-run/project-context.d.ts

@@ -0,0 +1,7 @@
+import type { CheckProjectContext } from "../check/check.ts";
+import type { RunControls } from "./controls/contract.ts";
+/** Materializes only invocation-wide callback input; Check-local options own domain configuration. */
+export declare function createProjectContext(input: Readonly<{
+    readonly controls: RunControls;
+    readonly root: string;
+}>): CheckProjectContext;

package/types/project-run/result.d.ts

@@ -0,0 +1,99 @@
+import type { DefinitionWarning, ProjectDefinitionDiagnostic } from "../project-definition/project-definition.ts";
+import type { RunControlDiagnostic } from "./controls/validation-result.ts";
+import type { CheckAggregate, RunControls } from "./controls/contract.ts";
+import type { CheckMessageLevel } from "../check/check.ts";
+import type { CoreSnapshot } from "../check-settlement/facts.ts";
+import type { RunOutputStatuses } from "./output-status.ts";
+export type RunDiagnostic = Readonly<{
+    readonly code: "task-graph-invalid" | "task-engine-failed" | "publication-model-failed";
+}>;
+export type CheckDuration = Readonly<{
+    readonly checkId: string;
+    readonly durationMs: number | null;
+}>;
+export interface CheckRunMessage {
+    readonly checkId: string;
+    readonly level: CheckMessageLevel;
+    readonly code: string;
+    readonly message: string;
+}
+export interface RunResultFacts {
+    readonly aggregate: CheckAggregate | null;
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly snapshot: CoreSnapshot;
+}
+/** 一次 Project Run 的可判别结果；output failure 保留已结算 facts。 */
+export type RunResult = Readonly<{
+    readonly kind: "configuration";
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnostic: ProjectDefinitionDiagnostic | RunControlDiagnostic;
+} | {
+    readonly kind: "planning";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnostic: RunDiagnostic;
+    readonly outputs: RunOutputStatuses;
+} | {
+    readonly kind: "cancelled";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly outputs: RunOutputStatuses;
+    readonly phase: "pre-work" | "planning";
+} | {
+    readonly kind: "cancelled";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly outputs: RunOutputStatuses;
+    readonly phase: "execution";
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly snapshot: CoreSnapshot;
+} | ({
+    readonly kind: "completed";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly outputs: RunOutputStatuses;
+} & RunResultFacts) | {
+    readonly kind: "execution";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnostic: RunDiagnostic;
+    readonly outputs: RunOutputStatuses;
+} | ({
+    readonly kind: "output";
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnostic: Readonly<{
+        readonly code: "machine-publication-failed" | "progress-rendering-failed" | "diagnostic-logging-failed";
+    }>;
+    readonly outputs: RunOutputStatuses;
+} & RunResultFacts)>;
+/** Any Run result produced after controls and Definition validation have completed. */
+export type NonConfigurationRunResult = Exclude<RunResult, {
+    readonly kind: "configuration";
+}>;
+type OutputRunResult = Extract<RunResult, {
+    readonly kind: "output";
+}>;
+export declare function outputFailure(declarativeFingerprint: string, definitionWarnings: readonly DefinitionWarning[], outputs: RunOutputStatuses, output: keyof RunOutputStatuses, facts: RunResultFacts): OutputRunResult;
+export declare function isCancelled(controls: RunControls): boolean;
+export declare function planning(declarativeFingerprint: string, definitionWarnings: readonly DefinitionWarning[], outputs: RunOutputStatuses, code: Extract<RunDiagnostic["code"], "task-graph-invalid">): Extract<NonConfigurationRunResult, {
+    readonly kind: "planning";
+}>;
+export declare function preExecutionCancellation(declarativeFingerprint: string, definitionWarnings: readonly DefinitionWarning[], outputs: RunOutputStatuses, phase: "pre-work" | "planning"): Extract<NonConfigurationRunResult, {
+    readonly kind: "cancelled";
+    readonly phase: "pre-work" | "planning";
+}>;
+export declare function executionCancellation(input: Readonly<{
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly declarativeFingerprint: string;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly outputs: RunOutputStatuses;
+    readonly snapshot: CoreSnapshot;
+}>): Extract<NonConfigurationRunResult, {
+    readonly kind: "cancelled";
+    readonly phase: "execution";
+}>;
+export {};

package/types/project-run/run.d.ts

@@ -0,0 +1,18 @@
+import type { ProjectDefinition } from "../project-definition/project-definition.ts";
+import type { RunControls } from "./controls/contract.ts";
+import type { RunResult } from "./result.ts";
+export type { RunOutputStatus, RunOutputStatuses } from "./output-status.ts";
+export type { RunDiagnostic, RunResult } from "./result.ts";
+/**
+ * 在调用方的 Bun runtime 中执行一个由项目拥有的 Project Definition。
+ *
+ * @param definition - Project Definition input；{@link defineConfig} 补齐 defaults，run 在 invocation 前验证。
+ * @param controls - 本次 invocation context 与 outputs 使用的闭合控制值。
+ * @returns ordinary configuration、planning、execution、cancellation 与 output failures 通过 `RunResult`
+ * 返回；调用方先按 `kind` narrow。
+ * @remarks Definition validation 关闭 authoring grammar；可选 Check preflight 组成 invocation execution barrier，
+ * 并在 execution callback、dependency resolver 或 scanner 前完成。`output` branch 同时提供完整 final
+ * snapshot 与 output failure diagnostic。
+ */
+export declare function run(definition: ProjectDefinition, controls?: RunControls): Promise<RunResult>;
+export declare function run(definition: unknown, controls?: unknown): Promise<RunResult>;

package/types/project-run/task-scheduler/execution-state.d.ts

@@ -0,0 +1,67 @@
+import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope, TaskGraph } from "./graph.ts";
+import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+import type { SchedulerSnapshot } from "./scheduler-decision.ts";
+export type TaskSettlement<TResult> = Readonly<{
+    readonly kind: "completed";
+    readonly value: TResult;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+} | {
+    readonly kind: "blocked";
+    readonly dependencyIds: readonly string[];
+} | {
+    readonly kind: "cancelled-before-start";
+}>;
+export interface SettledTask<TResult> {
+    readonly task: PlannedTask;
+    readonly settlement: TaskSettlement<TResult>;
+}
+export interface TaskExecutionContext {
+    readonly signal: AbortSignal | undefined;
+}
+export interface TaskGraphRun<TResult> {
+    readonly cancelled: boolean;
+    /** One entry per static graph Task, in static graph order. */
+    readonly settlements: readonly SettledTask<TResult>[];
+}
+export interface RunTaskGraphOptions<TResult> {
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly graph: TaskGraph;
+    readonly maxParallel: number;
+    readonly signal?: AbortSignal;
+    readonly execute: (task: PlannedTask, context: TaskExecutionContext) => TResult | Promise<TResult>;
+}
+export type RunningTaskCompletion<TResult> = Readonly<{
+    readonly taskId: string;
+    readonly settlement: TaskSettlement<TResult>;
+}>;
+export interface RunningTask<TResult> {
+    readonly task: PlannedTask;
+    readonly completion: Promise<RunningTaskCompletion<TResult>>;
+}
+export interface RuntimeScope {
+    readonly scope: PlannedTaskScope;
+    readonly activationTaskIds: ReadonlySet<string>;
+    isActive: boolean;
+}
+export interface SchedulerState<TResult> {
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly graph: PlannedTaskGraph;
+    readonly maxParallel: number;
+    readonly signal: AbortSignal | undefined;
+    readonly execute: RunTaskGraphOptions<TResult>["execute"];
+    readonly pending: PlannedTask[];
+    readonly runningById: Map<string, RunningTask<TResult>>;
+    readonly runningMutexes: Set<string>;
+    readonly settlementsByTaskId: Map<string, TaskSettlement<TResult>>;
+    readonly scopesById: ReadonlyMap<string, RuntimeScope>;
+    reservationTaskId: string | undefined;
+    isCancelled: boolean;
+}
+export declare function createSchedulerState<TResult>(graph: PlannedTaskGraph, options: RunTaskGraphOptions<TResult>): SchedulerState<TResult>;
+/** Projects mutable execution state into the pure scheduler-decision input. */
+export declare function snapshotSchedulerState<TResult>(state: SchedulerState<TResult>): SchedulerSnapshot;
+export declare function scopeForTask<TResult>(task: PlannedTask, state: SchedulerState<TResult>): RuntimeScope | undefined;
+export declare function cancelPendingTasks<TResult>(state: SchedulerState<TResult>): void;
+export declare function recordSettlement<TResult>(state: SchedulerState<TResult>, task: PlannedTask, settlement: TaskSettlement<TResult>): void;

package/types/project-run/task-scheduler/graph-validation.d.ts

@@ -0,0 +1,11 @@
+import type { PlannedTask, PlannedTaskScope } from "./graph.ts";
+interface PreparedTaskGraphValidationInput {
+    readonly rootMaxParallel: number | undefined;
+    readonly scopeById: ReadonlyMap<string, PlannedTaskScope>;
+    readonly scopes: readonly PlannedTaskScope[];
+    readonly taskById: ReadonlyMap<string, PlannedTask>;
+    readonly tasks: readonly PlannedTask[];
+}
+/** Validates dependency and scope relations after graph-shaped input is normalized. */
+export declare function validatePreparedTaskGraph(input: PreparedTaskGraphValidationInput): void;
+export {};

package/types/project-run/task-scheduler/graph.d.ts

@@ -0,0 +1,40 @@
+export interface TaskNode {
+    readonly id: string;
+    readonly dependsOn?: readonly string[];
+    readonly mutex?: readonly string[];
+    readonly scopeId?: string;
+}
+/**
+ * A scheduling scope is intentionally product-agnostic. Product adapters may
+ * use its opaque id to bind local Check semantics, but the engine only uses
+ * membership, a cap, activation candidates, and the terminal relation.
+ */
+export interface TaskScope {
+    readonly id: string;
+    readonly maxParallel: number;
+    readonly activationTaskIds: readonly string[];
+    readonly terminalTaskId: string;
+}
+export interface TaskGraph {
+    readonly tasks: readonly TaskNode[];
+    readonly scopes?: readonly TaskScope[];
+}
+export interface PlannedTask {
+    readonly id: string;
+    readonly dependsOn: readonly string[];
+    readonly mutex: readonly string[];
+    readonly scopeId: string | undefined;
+}
+export interface PlannedTaskScope {
+    readonly id: string;
+    readonly maxParallel: number;
+    readonly activationTaskIds: readonly string[];
+    readonly terminalTaskId: string;
+}
+export interface PlannedTaskGraph {
+    readonly tasks: readonly PlannedTask[];
+    readonly scopes: readonly PlannedTaskScope[];
+}
+/** Validates untrusted graph-shaped input without admitting it to scheduler execution. */
+export declare function validateTaskGraph(graph: unknown): void;
+export declare function prepareTaskGraph(graph: unknown, rootMaxParallel?: number): PlannedTaskGraph;

package/types/project-run/task-scheduler/scheduler-admission-decision.d.ts

@@ -0,0 +1,8 @@
+import { type SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import { type SchedulerDecision, type SchedulerDecisionContext, type SchedulerTrigger } from "./scheduler-decision-model.ts";
+export interface SchedulerDecisionCycle {
+    readonly context: SchedulerDecisionContext;
+    readonly state: SchedulerInspection;
+    readonly trigger: SchedulerTrigger;
+}
+export declare function decideAdmission(cycle: SchedulerDecisionCycle): SchedulerDecision;

package/types/project-run/task-scheduler/scheduler-blocker-summary.d.ts

@@ -0,0 +1,4 @@
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import type { SchedulerBlockerSummary, SchedulerCapacity } from "./scheduler-decision-model.ts";
+/** Summarizes why pending Tasks cannot currently advance. */
+export declare function summarizeSchedulerBlockers(state: SchedulerInspection, capacity: SchedulerCapacity): SchedulerBlockerSummary;

package/types/project-run/task-scheduler/scheduler-decision-inspection.d.ts

@@ -0,0 +1,24 @@
+import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope } from "./graph.ts";
+import type { SchedulerAwaitReason, SchedulerDecisionContext, SchedulerSettlementKind, SchedulerSnapshot } from "./scheduler-decision-model.ts";
+export interface SchedulerInspection {
+    readonly activeScopeIds: ReadonlySet<string>;
+    readonly graph: PlannedTaskGraph;
+    readonly maxParallel: number;
+    readonly pendingTasks: readonly PlannedTask[];
+    readonly reservationTaskId: string | undefined;
+    readonly runningMutexes: ReadonlySet<string>;
+    readonly runningTaskIds: ReadonlySet<string>;
+    readonly settlementKindByTaskId: ReadonlyMap<string, SchedulerSettlementKind>;
+}
+export declare function inspectSnapshot(snapshot: SchedulerSnapshot): SchedulerInspection;
+export declare function decisionContext(state: SchedulerInspection): SchedulerDecisionContext;
+export declare function selectBlockedTask(state: SchedulerInspection): Readonly<{
+    readonly dependencyIds: readonly string[];
+    readonly task: PlannedTask;
+}> | undefined;
+export declare function isDependencyMutexEligible(task: PlannedTask, state: SchedulerInspection): boolean;
+export declare function capacityWaitReason(state: SchedulerInspection): SchedulerAwaitReason;
+export declare function canAdmit(state: SchedulerInspection, task: PlannedTask): boolean;
+export declare function activationScopeFor(state: SchedulerInspection, task: PlannedTask): PlannedTaskScope | undefined;
+export declare function selectTighteningTask(state: SchedulerInspection, eligibleTasks: readonly PlannedTask[], effectiveMaxParallel: number): PlannedTask | undefined;
+export declare function selectConstrainedContinuation(state: SchedulerInspection, eligibleTasks: readonly PlannedTask[], effectiveMaxParallel: number): PlannedTask | undefined;

package/types/project-run/task-scheduler/scheduler-decision-model.d.ts

@@ -0,0 +1,94 @@
+import type { PlannedTaskGraph } from "./graph.ts";
+export type SchedulerSettlementKind = "completed" | "failed" | "blocked" | "cancelled-before-start";
+export type SchedulerTrigger = Readonly<{
+    readonly kind: "execution-started";
+}> | Readonly<{
+    readonly kind: "admission-continued";
+}> | Readonly<{
+    readonly kind: "blocked-settled";
+    readonly taskId: string;
+}> | Readonly<{
+    readonly kind: "task-settled";
+    readonly settlementKind: SchedulerSettlementKind;
+    readonly taskId: string;
+}> | Readonly<{
+    readonly kind: "cancellation-observed";
+}> | Readonly<{
+    readonly kind: "cancellation-applied";
+}>;
+export interface SchedulerSnapshot {
+    readonly graph: PlannedTaskGraph;
+    readonly isAbortRequested: boolean;
+    readonly isCancelled: boolean;
+    readonly pendingTaskIds: readonly string[];
+    readonly reservationTaskId: string | undefined;
+    readonly runningMutexes: readonly string[];
+    readonly runningTaskIds: readonly string[];
+    readonly settledTasks: readonly Readonly<{
+        readonly kind: SchedulerSettlementKind;
+        readonly taskId: string;
+    }>[];
+    readonly activeScopeIds: readonly string[];
+    readonly maxParallel: number;
+}
+export interface SchedulerCapacity {
+    readonly effectiveMaxParallel: number;
+    readonly maxParallel: number;
+    readonly running: number;
+}
+export interface SchedulerBlockerSummary {
+    readonly dependency: number;
+    readonly mutex: number;
+    readonly rootCapacity: boolean;
+    readonly scopeCapacity: boolean;
+}
+export interface SchedulerReservationContext {
+    readonly taskId: string | null;
+}
+export interface SchedulerDecisionContext {
+    readonly blockers: SchedulerBlockerSummary;
+    readonly capacity: SchedulerCapacity;
+    readonly reservation: SchedulerReservationContext;
+}
+export type ReservationUpdate = Readonly<{
+    readonly kind: "unchanged";
+}> | Readonly<{
+    readonly kind: "set";
+    readonly taskId: string;
+}> | Readonly<{
+    readonly kind: "clear";
+}>;
+export type SchedulerAdmissionReason = "reservation" | "tightening-scope" | "constrained-continuation" | "canonical-order";
+export type SchedulerAwaitReason = "cancellation-drain" | "dependency-or-mutex" | "running-drain" | "root-capacity" | "active-scope-capacity" | "reserved-tightening-scope";
+export type SchedulerDecision = SchedulerDecisionContext & (Readonly<{
+    readonly eligibleCount: number;
+    readonly kind: "admit";
+    readonly reason: SchedulerAdmissionReason;
+    readonly reservationUpdate: ReservationUpdate;
+    readonly scopeToActivate: string | null;
+    readonly taskId: string;
+    readonly trigger: SchedulerTrigger;
+}> | Readonly<{
+    readonly dependencyIds: readonly string[];
+    readonly kind: "settle-blocked";
+    readonly taskId: string;
+    readonly trigger: SchedulerTrigger;
+}> | Readonly<{
+    readonly eligibleCount: number;
+    readonly kind: "await-running";
+    readonly reason: SchedulerAwaitReason;
+    readonly reservationUpdate: ReservationUpdate;
+    readonly trigger: SchedulerTrigger;
+}> | Readonly<{
+    readonly kind: "cancel-pending";
+    readonly taskIds: readonly string[];
+    readonly trigger: SchedulerTrigger;
+}> | Readonly<{
+    readonly cancelled: boolean;
+    readonly kind: "complete";
+    readonly trigger: SchedulerTrigger;
+}>);
+export declare function reservationUnchanged(): ReservationUpdate;
+export declare function reservationSet(taskId: string): ReservationUpdate;
+export declare function reservationClear(): ReservationUpdate;
+export declare function freezeDecision(decision: SchedulerDecision): SchedulerDecision;

package/types/project-run/task-scheduler/scheduler-decision.d.ts

@@ -0,0 +1,8 @@
+import type { SchedulerDecision, SchedulerSnapshot, SchedulerTrigger } from "./scheduler-decision-model.ts";
+export type { SchedulerDecision, SchedulerSettlementKind, SchedulerSnapshot, SchedulerTrigger } from "./scheduler-decision-model.ts";
+/**
+ * Computes the next generic task-engine action from an immutable state projection.
+ * Starting work, awaiting promises, cancellation, and diagnostic output remain in
+ * the imperative scheduler shell.
+ */
+export declare function decideScheduler(snapshot: SchedulerSnapshot, trigger: SchedulerTrigger): SchedulerDecision;

package/types/project-run/task-scheduler/scheduler.d.ts

@@ -0,0 +1,3 @@
+import { type RunTaskGraphOptions, type TaskGraphRun } from "./execution-state.ts";
+export type { RunTaskGraphOptions, SettledTask, TaskExecutionContext, TaskGraphRun, TaskSettlement } from "./execution-state.ts";
+export declare function runTaskGraph<TResult>(options: RunTaskGraphOptions<TResult>): Promise<TaskGraphRun<TResult>>;