@sanity/ailf 0.1.0

package/dist/pipeline/plan-format.js

@@ -0,0 +1,202 @@
+/**
+ * pipeline/plan-format.ts
+ *
+ * Formatters for rendering an ExecutionPlan to console output or JSON.
+ *
+ * The console formatter produces a rich, human-readable preview with
+ * emoji markers, alignment, and color-coding (via unicode markers).
+ * The JSON formatter produces machine-readable output for CI/CD.
+ *
+ * @see docs/exec-plans/active/execution-preview.md
+ */
+import { formatCost } from "../agent-observer/pricing.js";
+// ---------------------------------------------------------------------------
+// Duration formatting
+// ---------------------------------------------------------------------------
+/**
+ * Format an execution plan as a rich console string.
+ *
+ * Produces a multi-section output with emoji markers showing:
+ * - Command summary (mode, source, flags)
+ * - Step plan (which steps will run, cached, or skipped)
+ * - Test/task summary
+ * - Model list
+ * - Cost estimate
+ * - File I/O
+ * - Comparison context
+ * - Warnings/errors
+ */
+export function formatPlanConsole(plan) {
+    const lines = [];
+    // Header
+    lines.push(`📋 Execution Plan: ailf ${plan.command}`);
+    lines.push("");
+    // Command summary
+    if (plan.mode) {
+        lines.push(`  Mode:         ${plan.mode}`);
+    }
+    if (plan.source) {
+        lines.push(`  Source:       ${plan.source}${plan.source === "production" ? " (sanity.io/docs)" : ""}`);
+    }
+    lines.push("");
+    // Step plan
+    if (plan.steps.length > 0) {
+        const willRunCount = plan.steps.filter((s) => s.willRun).length;
+        const totalSteps = plan.steps.length;
+        lines.push(`  📦 Steps (${willRunCount} of ${totalSteps} will execute):`);
+        for (const step of plan.steps) {
+            const icon = stepIcon(step);
+            const suffix = step.cacheStatus === "hit" && step.estimatedSavedMs
+                ? ` (saving ~${formatDuration(step.estimatedSavedMs)})`
+                : "";
+            lines.push(`    ${icon} ${step.name} — ${step.reason}${suffix}`);
+        }
+        lines.push("");
+    }
+    // Test/task summary
+    if (plan.totalTests !== undefined) {
+        if (plan.debug) {
+            lines.push(`  🧪 Tests: ${plan.debug.filteredCount} of ${plan.debug.totalCount} (${plan.debug.filterDescription})`);
+        }
+        else {
+            lines.push(`  🧪 Tests: ${plan.totalTests}`);
+        }
+        if (plan.repoTaskCount && plan.repoTaskCount > 0) {
+            lines.push(`  (includes ${plan.repoTaskCount} repo-based task definition${plan.repoTaskCount === 1 ? "" : "s"})`);
+        }
+        // Show task list (gold variants only, to avoid duplication noise)
+        if (plan.tasks && plan.tasks.length > 0) {
+            const goldTasks = plan.tasks.filter((t) => t.variant === "gold");
+            const maxShow = 15;
+            const showTasks = goldTasks.slice(0, maxShow);
+            for (const task of showTasks) {
+                lines.push(`    • ${task.description}`);
+            }
+            if (goldTasks.length > maxShow) {
+                lines.push(`    … and ${goldTasks.length - maxShow} more`);
+            }
+        }
+        lines.push("");
+    }
+    // Model list
+    if (plan.models && plan.models.length > 0) {
+        lines.push(`  🤖 Models (${plan.models.length}):`);
+        const maxLabelLen = Math.max(...plan.models.map((m) => m.label.length));
+        for (const model of plan.models) {
+            const padded = model.label.padEnd(maxLabelLen + 2);
+            lines.push(`    ${padded} ${model.id}`);
+        }
+        lines.push("");
+    }
+    // Cost estimate
+    if (plan.costEstimate) {
+        const ce = plan.costEstimate;
+        lines.push(`  📊 Estimated API calls: ${ce.totalApiCalls} (${plan.totalTests ?? 0} tests × ${plan.models?.length ?? 0} models)`);
+        const minCost = formatCost(ce.totalCost.min);
+        const maxCost = formatCost(ce.totalCost.max);
+        const gradingMin = formatCost(ce.grading.min);
+        const gradingMax = formatCost(ce.grading.max);
+        lines.push(`  💰 Estimated cost:      ${minCost}–${maxCost} (includes ${gradingMin}–${gradingMax} grading)`);
+        // Per-model breakdown
+        if (ce.perModel.length > 1) {
+            for (const pm of ce.perModel) {
+                if (pm.cost.min > 0) {
+                    lines.push(`     └ ${pm.label}: ${formatCost(pm.cost.min)}–${formatCost(pm.cost.max)}`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // Cache savings
+    if (plan.totalCacheSavingsMs > 0) {
+        lines.push(`  ⏱️  Cache savings:       ~${formatDuration(plan.totalCacheSavingsMs)} from cached steps`);
+        lines.push("");
+    }
+    // Comparison
+    if (plan.comparison) {
+        lines.push("  📊 Comparison:");
+        const ageStr = plan.comparison.baselineAge
+            ? ` (${plan.comparison.baselineAge} old)`
+            : "";
+        const existsStr = plan.comparison.exists ? "" : " ⚠️  NOT FOUND";
+        lines.push(`    Baseline:  ${plan.comparison.baselinePath}${ageStr}${existsStr}`);
+        lines.push(`    Threshold: ±${plan.comparison.threshold} points`);
+        lines.push("");
+    }
+    // Files read
+    if (plan.filesRead.length > 0) {
+        lines.push(`  📂 Files read (${plan.filesRead.length}):`);
+        const maxShow = 10;
+        const shown = plan.filesRead.slice(0, maxShow);
+        lines.push(`    ${shown.join(", ")}`);
+        if (plan.filesRead.length > maxShow) {
+            lines.push(`    … and ${plan.filesRead.length - maxShow} more`);
+        }
+        lines.push("");
+    }
+    // Files created
+    if (plan.filesCreated.length > 0) {
+        lines.push(`  📝 Files created:`);
+        for (const f of plan.filesCreated) {
+            lines.push(`    ${f}`);
+        }
+        lines.push("");
+    }
+    // Warnings
+    if (plan.warnings.length > 0) {
+        lines.push(`  ⚠️  Warnings (${plan.warnings.length}):`);
+        for (const w of plan.warnings) {
+            lines.push(`    ${w}`);
+        }
+        lines.push("");
+    }
+    // Errors
+    if (plan.errors.length > 0) {
+        lines.push(`  ❌ Errors (${plan.errors.length}):`);
+        for (const e of plan.errors) {
+            lines.push(`    ${e}`);
+        }
+        lines.push("");
+    }
+    // Footer
+    lines.push("  Run without --explain to execute, or add --yes to preview then confirm.");
+    lines.push("");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Console formatter
+// ---------------------------------------------------------------------------
+/**
+ * Format an execution plan as indented JSON.
+ *
+ * Useful for CI/CD integration, approval gates, and programmatic
+ * inspection of the plan.
+ */
+export function formatPlanJson(plan) {
+    return JSON.stringify(plan, null, 2);
+}
+// ---------------------------------------------------------------------------
+// JSON formatter
+// ---------------------------------------------------------------------------
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const min = Math.floor(ms / 60000);
+    const sec = Math.round((ms % 60000) / 1000);
+    return `${min}m ${sec}s`;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function stepIcon(step) {
+    if (!step.willRun) {
+        if (step.cacheStatus === "hit")
+            return "📦";
+        if (step.cacheStatus === "skipped")
+            return "⏭️";
+        return "⏭️";
+    }
+    return "✅";
+}

package/dist/pipeline/plan.d.ts

@@ -0,0 +1,169 @@
+/**
+ * pipeline/plan.ts
+ *
+ * Execution plan assembly for the `--explain` CLI flag.
+ *
+ * Computes a detailed preview of what a command will do without executing
+ * anything. Calls existing pure functions (task expansion, model loading,
+ * cache hashing, pricing) and composes them into an `ExecutionPlan`.
+ *
+ * @see docs/exec-plans/active/execution-preview.md
+ */
+import type { DebugOptions, EvalMode } from "./types.js";
+/** Comparison plan for --compare flag. */
+export interface ComparisonPlan {
+    /** Age of the baseline in human-readable form */
+    baselineAge?: string;
+    /** Path to the baseline file */
+    baselinePath: string;
+    /** Whether the baseline file exists */
+    exists: boolean;
+    /** Noise threshold for comparison */
+    threshold: number;
+}
+/** Cost estimate for the evaluation run. */
+export interface CostEstimate {
+    /** Grading cost estimate (min/max) */
+    grading: {
+        max: number;
+        min: number;
+    };
+    /** Number of grading calls (rubric evaluations) */
+    gradingCalls: number;
+    /** Per-model evaluation cost breakdown */
+    perModel: {
+        cost: {
+            max: number;
+            min: number;
+        };
+        label: string;
+        modelName: string;
+    }[];
+    /** Total API calls for evaluation (tests × models) */
+    totalApiCalls: number;
+    /** Total estimated cost (min/max) */
+    totalCost: {
+        max: number;
+        min: number;
+    };
+}
+/** Debug filtering plan. */
+export interface DebugPlan {
+    /** Description of the debug filter applied */
+    filterDescription: string;
+    /** How many tests survive debug filtering */
+    filteredCount: number;
+    /** Total tests before debug filtering */
+    totalCount: number;
+}
+/** The complete execution plan for any command. */
+export interface ExecutionPlan {
+    /** Cache prediction per step */
+    cacheStatus: Record<string, "hit" | "miss" | "skipped" | "unknown">;
+    /** Command name (e.g., "pipeline", "compare", "validate") */
+    command: string;
+    /** Comparison plan (when --compare is set) */
+    comparison?: ComparisonPlan;
+    /** Estimated cost */
+    costEstimate?: CostEstimate;
+    /** Debug filter plan */
+    debug?: DebugPlan;
+    /** Human-readable description of what the command does */
+    description: string;
+    /** Validation errors (would prevent execution) */
+    errors: string[];
+    /** Files that will be created or updated */
+    filesCreated: string[];
+    /** Files that will be read as input */
+    filesRead: string[];
+    /** Evaluation mode */
+    mode?: EvalMode;
+    /** Model plan */
+    models?: ModelPlan[];
+    /** Documentation source */
+    source?: string;
+    /** Step-by-step plan */
+    steps: StepPlan[];
+    /** Task plan */
+    tasks?: TaskPlan[];
+    /** Total estimated time savings from cache hits */
+    totalCacheSavingsMs: number;
+    /** Total number of tests to run */
+    totalTests?: number;
+    /** Number of tests from repo-based tasks (included in totalTests) */
+    repoTaskCount?: number;
+    /** Validation warnings */
+    warnings: string[];
+}
+/** A model that will be evaluated. */
+export interface ModelPlan {
+    /** Provider ID (e.g., "openai:chat:gpt-5.2") */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Raw model name for pricing lookup */
+    modelName: string;
+}
+/** Description of a single pipeline step in the execution plan. */
+export interface StepPlan {
+    /** Cache prediction: hit (will skip), miss (will execute), skipped (flag), or unknown */
+    cacheStatus: "hit" | "miss" | "skipped" | "unknown";
+    /** Estimated duration in ms from cached data (if cache hit predicted) */
+    estimatedSavedMs?: number;
+    /** Human-readable name */
+    name: string;
+    /** Short description of what happens */
+    reason: string;
+    /** Whether this step will execute */
+    willRun: boolean;
+}
+/** A task that will be included in the evaluation. */
+export interface TaskPlan {
+    /** Test description */
+    description: string;
+    /** Whether this is a gold (with docs) or baseline (without docs) variant */
+    variant: "baseline" | "gold";
+}
+/** Minimal options shape needed to build a pipeline execution plan. */
+export interface PlanOptions {
+    areaOption?: string;
+    beforeOption?: string;
+    compareBaseline?: string;
+    compareEnabled: boolean;
+    compareThreshold?: number;
+    concurrency?: number;
+    debug?: DebugOptions;
+    discoveryReportEnabled: boolean;
+    dryRun: boolean;
+    gapAnalysisEnabled: boolean;
+    graderReplications?: number;
+    mode: EvalMode;
+    noCache: boolean;
+    publishEnabled: boolean;
+    readinessEnabled: boolean;
+    repoTasksPath?: string;
+    skipEval: boolean;
+    skipFetch: boolean;
+    source?: string;
+    taskOption?: string;
+}
+/**
+ * Build a complete execution plan for the `pipeline` command.
+ *
+ * This is a read-only operation — it computes the plan by calling existing
+ * pure functions (task expansion, model loading, cache lookup, pricing)
+ * without executing any pipeline steps or writing to process.env.
+ */
+export declare function buildPipelinePlan(opts: PlanOptions, rootDir: string): Promise<ExecutionPlan>;
+/**
+ * Build a minimal plan for commands that don't have complex step graphs.
+ * Used by compare, validate, fetch-docs, baseline, etc.
+ */
+export declare function buildSimpleCommandPlan(opts: {
+    command: string;
+    description: string;
+    filesCreated?: string[];
+    filesRead?: string[];
+    rootDir: string;
+    steps?: StepPlan[];
+}): ExecutionPlan;