@ttfw/envoi 1.0.0

package/dist/lib/risk.js

@@ -0,0 +1,192 @@
+/**
+ * Risk scoring and reviewer trigger logic.
+ *
+ * Determines when the reviewer should be invoked based on deterministic
+ * risk signals: high-risk file paths, diff fraction thresholds, repeated
+ * stops, verification failures, and budget warnings.
+ */
+import micromatch from 'micromatch';
+/**
+ * Checks if any paths match high-risk glob patterns.
+ *
+ * Uses micromatch to check paths against high_risk_globs patterns.
+ *
+ * @param paths - Array of file paths to check
+ * @param highRiskGlobs - Array of glob patterns for high-risk files
+ * @returns Array of paths that match high-risk patterns
+ *
+ * @example
+ * const riskyPaths = checkHighRiskGlobs(
+ *   ['src/auth.ts', 'src/utils.ts'],
+ *   ['src/auth*.ts', 'src/*secret*']
+ * );
+ */
+export function checkHighRiskGlobs(paths, highRiskGlobs) {
+    if (highRiskGlobs.length === 0) {
+        return [];
+    }
+    // Check if any paths match high-risk globs
+    return paths.filter((path) => micromatch.isMatch(path, highRiskGlobs));
+}
+/**
+ * Checks if diff fraction exceeds threshold.
+ *
+ * Calculates files_touched/max_files_touched or lines_changed/max_lines_changed
+ * and checks if either fraction >= threshold.
+ *
+ * @param analysis - Diff analysis result
+ * @param limits - Diff limits from task
+ * @param threshold - Fraction threshold (0.0 to 1.0)
+ * @returns True if diff fraction >= threshold
+ *
+ * @example
+ * const analysis = { files_touched: 8, lines_changed: 300, ... };
+ * const limits = { max_files_touched: 10, max_lines_changed: 400 };
+ * const nearCap = checkDiffFraction(analysis, limits, 0.8);
+ */
+export function checkDiffFraction(analysis, limits, threshold) {
+    if (threshold <= 0) {
+        return false;
+    }
+    const lines_changed = analysis.lines_added + analysis.lines_deleted;
+    // Calculate fractions
+    const filesFraction = limits.max_files_touched > 0
+        ? analysis.files_touched / limits.max_files_touched
+        : 0;
+    const linesFraction = limits.max_lines_changed > 0 ? lines_changed / limits.max_lines_changed : 0;
+    // Check if either fraction exceeds threshold
+    return filesFraction >= threshold || linesFraction >= threshold;
+}
+/**
+ * Checks if there are repeated stops within a time window.
+ *
+ * Counts STOP verdicts in stop_history within the specified window
+ * and checks if count >= maxStops.
+ *
+ * @param stopHistory - Array of stop history entries
+ * @param window - Time window in ticks
+ * @param maxStops - Maximum number of stops allowed in window
+ * @param currentTick - Current tick number
+ * @returns True if repeated stops detected
+ *
+ * @example
+ * const history = [
+ *   { tick: 5, verdict: 'stop' },
+ *   { tick: 8, verdict: 'stop' },
+ *   { tick: 12, verdict: 'stop' }
+ * ];
+ * const repeated = checkRepeatedStops(history, 10, 2, 12);
+ */
+export function checkRepeatedStops(stopHistory, window, maxStops, currentTick) {
+    if (window <= 0 || maxStops <= 0) {
+        return false;
+    }
+    // Filter stops within the window (from currentTick - window to currentTick)
+    const windowStart = Math.max(0, currentTick - window);
+    const stopsInWindow = stopHistory.filter((entry) => entry.verdict === 'stop' && entry.tick >= windowStart && entry.tick <= currentTick);
+    return stopsInWindow.length >= maxStops;
+}
+/**
+ * Computes risk flags based on various risk signals.
+ *
+ * Returns an array of risk flag strings indicating which risk conditions
+ * have been triggered.
+ *
+ * @param params - Parameters for risk computation
+ * @param params.analysis - Diff analysis result
+ * @param params.limits - Diff limits from task
+ * @param params.scope - Task scope configuration
+ * @param params.trigger - Reviewer trigger configuration
+ * @param params.stopHistory - Array of stop history entries
+ * @param params.currentTick - Current tick number
+ * @param params.verifyFailed - Whether verification failed
+ * @param params.budgetWarning - Whether budget warning threshold reached
+ * @returns Array of risk flag strings
+ *
+ * @example
+ * const flags = computeRiskFlags({
+ *   analysis,
+ *   limits,
+ *   scope,
+ *   trigger,
+ *   stopHistory: [],
+ *   currentTick: 10,
+ *   verifyFailed: false,
+ *   budgetWarning: false
+ * });
+ */
+export function computeRiskFlags(params) {
+    const { analysis, limits, scope, trigger, stopHistory, currentTick, verifyFailed, budgetWarning, } = params;
+    const flags = [];
+    // Check high-risk paths
+    if (trigger.on_high_risk_paths && trigger.high_risk_globs.length > 0) {
+        const riskyPaths = checkHighRiskGlobs(analysis.touched_paths, trigger.high_risk_globs);
+        if (riskyPaths.length > 0) {
+            flags.push('high_risk_path');
+        }
+        // Also check if allowed_globs overlap with high_risk_globs (pattern-level check)
+        // This is mentioned in the PRD as a risk trigger
+        const hasOverlap = scope.allowed_globs.some((allowedGlob) => trigger.high_risk_globs.some((riskGlob) => {
+            // Check if patterns overlap by testing if they could match similar paths
+            // Simple heuristic: check if one pattern could match the other
+            try {
+                return micromatch.isMatch(allowedGlob, [riskGlob]) ||
+                    micromatch.isMatch(riskGlob, [allowedGlob]);
+            }
+            catch {
+                // If pattern matching fails, skip this comparison
+                return false;
+            }
+        }));
+        if (hasOverlap && riskyPaths.length === 0) {
+            // Pattern overlap detected even if no paths match yet
+            flags.push('high_risk_path');
+        }
+    }
+    // Check diff fraction threshold
+    if (trigger.diff_fraction_threshold > 0) {
+        const nearCap = checkDiffFraction(analysis, limits, trigger.diff_fraction_threshold);
+        if (nearCap) {
+            flags.push('diff_near_cap');
+        }
+    }
+    // Check verification failure
+    if (trigger.on_verify_fail && verifyFailed) {
+        flags.push('verify_failed');
+    }
+    // Check repeated stops
+    if (trigger.on_repeated_stop &&
+        trigger.stop_window_ticks > 0 &&
+        trigger.max_stops_in_window > 0) {
+        const repeated = checkRepeatedStops(stopHistory, trigger.stop_window_ticks, trigger.max_stops_in_window, currentTick);
+        if (repeated) {
+            flags.push('repeated_stop');
+        }
+    }
+    // Check budget warning
+    if (budgetWarning) {
+        flags.push('budget_warning');
+    }
+    return flags;
+}
+/**
+ * Determines if reviewer should be triggered based on risk flags and config.
+ *
+ * Returns true if reviewer is enabled and any trigger condition is met.
+ *
+ * @param config - Reviewer configuration
+ * @param riskFlags - Array of risk flags from computeRiskFlags
+ * @returns True if reviewer should be triggered
+ *
+ * @example
+ * const shouldTrigger = shouldTriggerReviewer(config, ['high_risk_path', 'diff_near_cap']);
+ */
+export function shouldTriggerReviewer(config, riskFlags) {
+    // Reviewer must be enabled
+    if (!config.enabled) {
+        return false;
+    }
+    // At least one risk flag must be present
+    return riskFlags.length > 0;
+}
+//# sourceMappingURL=risk.js.map

package/dist/lib/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../../src/lib/risk.ts"],"names":[],"mappings":"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"}

package/dist/lib/rollback.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Rollback utilities to restore repository to base_commit state.
+ *
+ * Used when Judge detects violations (scope, diff limits, etc.) to reset
+ * tracked files and remove only the untracked files that were touched by the builder.
+ */
+/**
+ * Result of a rollback operation.
+ */
+export interface RollbackResult {
+    /**
+     * True if rollback completed successfully.
+     */
+    success: boolean;
+    /**
+     * Whether git reset succeeded.
+     */
+    tracked_reset: boolean;
+    /**
+     * Untracked paths that were removed.
+     */
+    paths_removed: string[];
+    /**
+     * Any errors encountered during rollback.
+     */
+    errors: string[];
+}
+/**
+ * Result of a rollback operation (new format for STOP code handling).
+ */
+export interface RollbackResultNew {
+    /**
+     * True if rollback completed successfully.
+     */
+    ok: boolean;
+    /**
+     * The commit SHA that was restored to.
+     */
+    restoredCommit: string;
+    /**
+     * Files that were removed during rollback.
+     */
+    removedFiles: string[];
+    /**
+     * Error message if rollback failed, null otherwise.
+     */
+    error: string | null;
+}
+/**
+ * Resets tracked files to a specific base commit using git reset --hard.
+ *
+ * @param baseCommit - The commit SHA to reset to
+ * @returns Object indicating success and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = rollbackTracked('abc123');
+ * if (!result.tracked_reset) {
+ *   console.error('Failed to reset tracked files');
+ * }
+ * ```
+ */
+export declare function rollbackTracked(baseCommit: string): {
+    tracked_reset: boolean;
+    errors: string[];
+};
+/**
+ * Removes specific untracked files and directories.
+ *
+ * Handles errors gracefully (file already removed, permission issues, etc.)
+ * and continues removing other paths even if some fail.
+ *
+ * @param paths - Array of file or directory paths to remove
+ * @returns Object with list of successfully removed paths and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await removeUntrackedPaths(['temp.txt', 'build/']);
+ * console.log(`Removed ${result.paths_removed.length} paths`);
+ * ```
+ */
+export declare function removeUntrackedPaths(paths: string[]): Promise<{
+    paths_removed: string[];
+    errors: string[];
+}>;
+/**
+ * Performs a full rollback operation: resets tracked files to base_commit
+ * and removes specified untracked paths.
+ *
+ * @param baseCommit - The commit SHA to reset tracked files to
+ * @param untrackedPaths - Array of untracked file/directory paths to remove
+ * @returns RollbackResult with complete status of the operation
+ *
+ * @example
+ * ```typescript
+ * const result = await rollback('abc123', ['temp.txt', 'build/']);
+ * if (result.success) {
+ *   console.log('Rollback completed successfully');
+ * }
+ * ```
+ */
+export declare function rollback(baseCommit: string, untrackedPaths: string[]): Promise<RollbackResult>;
+/**
+ * Resets to base commit and removes untracked files created by builder.
+ *
+ * This is the synchronous version used for STOP code handling.
+ * It resets tracked files to the base commit and removes specified untracked files.
+ *
+ * @param baseCommit - The commit SHA to reset to
+ * @param untrackedToRemove - Optional array of untracked file/directory paths to remove
+ * @returns RollbackResultNew with success status and details
+ *
+ * @example
+ * ```typescript
+ * const result = rollbackToCommit('abc123', ['temp.txt', 'build/']);
+ * if (result.ok) {
+ *   console.log(`Rolled back to ${result.restoredCommit}`);
+ *   console.log(`Removed ${result.removedFiles.length} files`);
+ * } else {
+ *   console.error(`Rollback failed: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function rollbackToCommit(baseCommit: string, untrackedToRemove?: string[]): RollbackResultNew;
+/**
+ * Verifies that the git worktree is clean.
+ *
+ * Uses `git diff --exit-code` to check for uncommitted tracked changes.
+ * Also checks that there are no untracked files (via git status --porcelain).
+ *
+ * @returns true if worktree is clean (no uncommitted changes and no untracked files), false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (verifyCleanWorktree()) {
+ *   console.log('Worktree is clean');
+ * } else {
+ *   console.log('Worktree has uncommitted changes');
+ * }
+ * ```
+ */
+export declare function verifyCleanWorktree(): boolean;
+//# sourceMappingURL=rollback.d.ts.map

package/dist/lib/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/lib/rollback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IAEZ;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG;IACnD,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAgBA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACnE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAqCD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,cAAc,CAAC,CAqBzB;AA8CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,iBAAiB,GAAE,MAAM,EAAO,GAC/B,iBAAiB,CAkCnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAqB7C"}

package/dist/lib/rollback.js

@@ -0,0 +1,244 @@
+/**
+ * Rollback utilities to restore repository to base_commit state.
+ *
+ * Used when Judge detects violations (scope, diff limits, etc.) to reset
+ * tracked files and remove only the untracked files that were touched by the builder.
+ */
+import { execSync } from 'node:child_process';
+import { unlink, rm } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
+import { unlinkSync, rmSync, statSync } from 'node:fs';
+/**
+ * Resets tracked files to a specific base commit using git reset --hard.
+ *
+ * @param baseCommit - The commit SHA to reset to
+ * @returns Object indicating success and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = rollbackTracked('abc123');
+ * if (!result.tracked_reset) {
+ *   console.error('Failed to reset tracked files');
+ * }
+ * ```
+ */
+export function rollbackTracked(baseCommit) {
+    const errors = [];
+    try {
+        execSync(`git reset --hard ${baseCommit}`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { tracked_reset: true, errors: [] };
+    }
+    catch (error) {
+        const errorMsg = `Failed to reset tracked files to ${baseCommit}: ${error instanceof Error ? error.message : String(error)}`;
+        errors.push(errorMsg);
+        return { tracked_reset: false, errors };
+    }
+}
+/**
+ * Removes specific untracked files and directories.
+ *
+ * Handles errors gracefully (file already removed, permission issues, etc.)
+ * and continues removing other paths even if some fail.
+ *
+ * @param paths - Array of file or directory paths to remove
+ * @returns Object with list of successfully removed paths and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await removeUntrackedPaths(['temp.txt', 'build/']);
+ * console.log(`Removed ${result.paths_removed.length} paths`);
+ * ```
+ */
+export async function removeUntrackedPaths(paths) {
+    const paths_removed = [];
+    const errors = [];
+    for (const path of paths) {
+        try {
+            // Check if path exists and is a directory
+            const stats = await stat(path);
+            const isDirectory = stats.isDirectory();
+            if (isDirectory) {
+                // Use rm with recursive for directories
+                await rm(path, { recursive: true, force: true });
+            }
+            else {
+                // Use unlink for files
+                await unlink(path);
+            }
+            paths_removed.push(path);
+        }
+        catch (error) {
+            // Handle errors gracefully - file may already be removed, permission issues, etc.
+            const errorMsg = `Failed to remove ${path}: ${error instanceof Error ? error.message : String(error)}`;
+            // Check if it's a "file not found" error (ENOENT) - this is acceptable
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                // File/directory doesn't exist - consider it already removed, but don't add to paths_removed
+                // since we didn't actually remove it
+                continue;
+            }
+            errors.push(errorMsg);
+        }
+    }
+    return { paths_removed, errors };
+}
+/**
+ * Performs a full rollback operation: resets tracked files to base_commit
+ * and removes specified untracked paths.
+ *
+ * @param baseCommit - The commit SHA to reset tracked files to
+ * @param untrackedPaths - Array of untracked file/directory paths to remove
+ * @returns RollbackResult with complete status of the operation
+ *
+ * @example
+ * ```typescript
+ * const result = await rollback('abc123', ['temp.txt', 'build/']);
+ * if (result.success) {
+ *   console.log('Rollback completed successfully');
+ * }
+ * ```
+ */
+export async function rollback(baseCommit, untrackedPaths) {
+    const errors = [];
+    // Step 1: Reset tracked files
+    const trackedResult = rollbackTracked(baseCommit);
+    errors.push(...trackedResult.errors);
+    // Step 2: Remove untracked paths
+    const untrackedResult = await removeUntrackedPaths(untrackedPaths);
+    errors.push(...untrackedResult.errors);
+    // Rollback is considered successful if tracked files were reset
+    // (untracked removal errors are less critical)
+    const success = trackedResult.tracked_reset && errors.length === 0;
+    return {
+        success,
+        tracked_reset: trackedResult.tracked_reset,
+        paths_removed: untrackedResult.paths_removed,
+        errors,
+    };
+}
+/**
+ * Synchronous version of removeUntrackedPaths for use in rollbackToCommit.
+ */
+function removeUntrackedPathsSync(paths) {
+    const paths_removed = [];
+    const errors = [];
+    for (const path of paths) {
+        try {
+            // Check if path exists and is a directory
+            const stats = statSync(path);
+            const isDirectory = stats.isDirectory();
+            if (isDirectory) {
+                // Use rmSync with recursive for directories
+                rmSync(path, { recursive: true, force: true });
+            }
+            else {
+                // Use unlinkSync for files
+                unlinkSync(path);
+            }
+            paths_removed.push(path);
+        }
+        catch (error) {
+            // Handle errors gracefully - file may already be removed, permission issues, etc.
+            const errorMsg = `Failed to remove ${path}: ${error instanceof Error ? error.message : String(error)}`;
+            // Check if it's a "file not found" error (ENOENT) - this is acceptable
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                // File/directory doesn't exist - consider it already removed
+                continue;
+            }
+            errors.push(errorMsg);
+        }
+    }
+    return { paths_removed, errors };
+}
+/**
+ * Resets to base commit and removes untracked files created by builder.
+ *
+ * This is the synchronous version used for STOP code handling.
+ * It resets tracked files to the base commit and removes specified untracked files.
+ *
+ * @param baseCommit - The commit SHA to reset to
+ * @param untrackedToRemove - Optional array of untracked file/directory paths to remove
+ * @returns RollbackResultNew with success status and details
+ *
+ * @example
+ * ```typescript
+ * const result = rollbackToCommit('abc123', ['temp.txt', 'build/']);
+ * if (result.ok) {
+ *   console.log(`Rolled back to ${result.restoredCommit}`);
+ *   console.log(`Removed ${result.removedFiles.length} files`);
+ * } else {
+ *   console.error(`Rollback failed: ${result.error}`);
+ * }
+ * ```
+ */
+export function rollbackToCommit(baseCommit, untrackedToRemove = []) {
+    try {
+        // Step 1: Reset tracked files
+        execSync(`git reset --hard ${baseCommit}`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Step 2: Remove untracked files
+        const untrackedResult = removeUntrackedPathsSync(untrackedToRemove);
+        // If there were errors removing untracked files, still consider it successful
+        // as long as git reset succeeded (untracked removal errors are less critical)
+        const ok = untrackedResult.errors.length === 0;
+        const error = untrackedResult.errors.length > 0 ? untrackedResult.errors.join('; ') : null;
+        return {
+            ok,
+            restoredCommit: baseCommit,
+            removedFiles: untrackedResult.paths_removed,
+            error,
+        };
+    }
+    catch (error) {
+        const errorMsg = `Failed to rollback to ${baseCommit}: ${error instanceof Error ? error.message : String(error)}`;
+        return {
+            ok: false,
+            restoredCommit: baseCommit,
+            removedFiles: [],
+            error: errorMsg,
+        };
+    }
+}
+/**
+ * Verifies that the git worktree is clean.
+ *
+ * Uses `git diff --exit-code` to check for uncommitted tracked changes.
+ * Also checks that there are no untracked files (via git status --porcelain).
+ *
+ * @returns true if worktree is clean (no uncommitted changes and no untracked files), false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (verifyCleanWorktree()) {
+ *   console.log('Worktree is clean');
+ * } else {
+ *   console.log('Worktree has uncommitted changes');
+ * }
+ * ```
+ */
+export function verifyCleanWorktree() {
+    try {
+        // Check for uncommitted tracked changes
+        execSync('git diff --exit-code', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Check for untracked files
+        const status = execSync('git status --porcelain', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Worktree is clean if status is empty (no uncommitted changes and no untracked files)
+        return status.trim() === '';
+    }
+    catch {
+        // git diff --exit-code exits with non-zero if there are changes
+        // git status might fail in some edge cases
+        return false;
+    }
+}
+//# sourceMappingURL=rollback.js.map

package/dist/lib/rollback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.js","sourceRoot":"","sources":["../../src/lib/rollback.ts"],"names":[],"mappings":"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"}

package/dist/lib/schema.d.ts

@@ -0,0 +1,47 @@
+/**
+ * JSON Schema validation utilities using Ajv.
+ *
+ * Provides functions to load and validate data against JSON schemas.
+ */
+/**
+ * Raw AJV error object (subset of fields we care about).
+ */
+export interface RawAjvError {
+    instancePath: string;
+    schemaPath: string;
+    keyword: string;
+    params: Record<string, unknown>;
+    message?: string;
+}
+/**
+ * Result of schema validation.
+ */
+export interface ValidationResult<T> {
+    /** Whether the data is valid */
+    valid: boolean;
+    /** Typed data if valid, null otherwise */
+    data: T | null;
+    /** Validation error messages if invalid */
+    errors: string[];
+    /** Raw AJV error objects for diagnostics */
+    rawErrors?: RawAjvError[];
+}
+/**
+ * Loads and parses a JSON schema file.
+ *
+ * @param schemaPath - Path to the JSON schema file
+ * @returns Parsed schema object
+ * @throws Error if the schema file cannot be read or parsed
+ */
+export declare function loadSchema(schemaPath: string): Promise<object>;
+/**
+ * Validates data against a JSON schema using Ajv.
+ *
+ * Uses draft-2020-12 schema support and caches compiled schemas for performance.
+ *
+ * @param data - Data to validate
+ * @param schema - JSON schema object
+ * @returns ValidationResult with typed data or error messages
+ */
+export declare function validateWithSchema<T>(data: unknown, schema: object): ValidationResult<T>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/lib/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/lib/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,2CAA2C;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CAC3B;AAKD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CA6DxF"}