@dotsetlabs/bellwether 0.10.0

package/dist/baseline/version.js

@@ -0,0 +1,206 @@
+/**
+ * Baseline versioning using CLI package version.
+ *
+ * Compatibility Rules:
+ * - Same CLI major version = COMPATIBLE (can compare baselines)
+ * - Different CLI major version = INCOMPATIBLE (requires migration)
+ *
+ * This aligns with semantic versioning: major version changes signal
+ * breaking changes, including baseline format changes.
+ */
+import { VERSION } from '../version.js';
+/**
+ * Get the current CLI version for baseline creation.
+ */
+export function getBaselineVersion() {
+    return VERSION;
+}
+/**
+ * Error thrown when baseline versions are incompatible.
+ */
+export class BaselineVersionError extends Error {
+    sourceVersion;
+    targetVersion;
+    constructor(message, sourceVersion, targetVersion) {
+        super(message);
+        this.sourceVersion = sourceVersion;
+        this.targetVersion = targetVersion;
+        this.name = 'BaselineVersionError';
+    }
+}
+/**
+ * Parse a version string into its semantic components.
+ *
+ * Handles:
+ * - Full semver: "1.0.0" -> { major: 1, minor: 0, patch: 0 }
+ * - Partial semver: "1.0" -> { major: 1, minor: 0, patch: 0 }
+ * - Legacy numeric: 1 -> { major: 1, minor: 0, patch: 0 }
+ *
+ * @param version - Version string or number to parse
+ * @returns Parsed version components
+ */
+export function parseVersion(version) {
+    // Handle undefined/null - treat as current version
+    if (version === undefined || version === null) {
+        return parseVersion(VERSION);
+    }
+    // Handle legacy numeric version (e.g., version: 1)
+    if (typeof version === 'number') {
+        return {
+            major: version,
+            minor: 0,
+            patch: 0,
+            raw: `${version}.0.0`,
+        };
+    }
+    // Parse semver string
+    const parts = version.split('.').map(Number);
+    // Validate parsed numbers
+    const major = Number.isNaN(parts[0]) ? 0 : parts[0];
+    const minor = Number.isNaN(parts[1]) ? 0 : (parts[1] ?? 0);
+    const patch = Number.isNaN(parts[2]) ? 0 : (parts[2] ?? 0);
+    return {
+        major,
+        minor,
+        patch,
+        raw: `${major}.${minor}.${patch}`,
+    };
+}
+/**
+ * Check if two versions are compatible for baseline comparison.
+ *
+ * Versions are compatible if they share the same major version.
+ *
+ * @param v1 - First version
+ * @param v2 - Second version
+ * @returns true if compatible, false otherwise
+ */
+export function areVersionsCompatible(v1, v2) {
+    return v1.major === v2.major;
+}
+/**
+ * Compare two versions and return -1, 0, or 1.
+ *
+ * @param v1 - First version
+ * @param v2 - Second version
+ * @returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+export function compareVersions(v1, v2) {
+    if (v1.major !== v2.major) {
+        return v1.major < v2.major ? -1 : 1;
+    }
+    if (v1.minor !== v2.minor) {
+        return v1.minor < v2.minor ? -1 : 1;
+    }
+    if (v1.patch !== v2.patch) {
+        return v1.patch < v2.patch ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Get a warning message for version differences, or null if versions are identical.
+ *
+ * @param v1 - First version (source/baseline)
+ * @param v2 - Second version (target/current)
+ * @returns Warning message or null
+ */
+export function getCompatibilityWarning(v1, v2) {
+    if (v1.major !== v2.major) {
+        return (`Baseline CLI versions are incompatible: v${v1.raw} vs v${v2.raw}. ` +
+            `Major version mismatch may cause incorrect comparison results. ` +
+            `Use \`bellwether baseline migrate\` to upgrade baselines to the current format.`);
+    }
+    if (v1.minor !== v2.minor || v1.patch !== v2.patch) {
+        return (`Baseline CLI versions differ: v${v1.raw} vs v${v2.raw}. ` +
+            `Comparison should work correctly, but some newer fields may not be present in the older baseline.`);
+    }
+    return null;
+}
+/**
+ * Check version compatibility and return detailed result.
+ *
+ * @param sourceVersion - Version of the source/baseline
+ * @param targetVersion - Version of the target/current
+ * @returns Compatibility result with details
+ */
+export function checkVersionCompatibility(sourceVersion, targetVersion) {
+    const v1 = parseVersion(sourceVersion);
+    const v2 = parseVersion(targetVersion);
+    return {
+        compatible: areVersionsCompatible(v1, v2),
+        warning: getCompatibilityWarning(v1, v2),
+        sourceVersion: v1.raw,
+        targetVersion: v2.raw,
+    };
+}
+/**
+ * Assert that two versions are compatible, throwing an error if not.
+ *
+ * @param sourceVersion - Version of the source/baseline
+ * @param targetVersion - Version of the target/current
+ * @throws BaselineVersionError if versions are incompatible
+ */
+export function assertVersionCompatibility(sourceVersion, targetVersion) {
+    const v1 = parseVersion(sourceVersion);
+    const v2 = parseVersion(targetVersion);
+    if (!areVersionsCompatible(v1, v2)) {
+        throw new BaselineVersionError(`Cannot compare baselines with incompatible CLI versions: v${v1.raw} vs v${v2.raw}. ` +
+            `Use \`bellwether baseline migrate\` to upgrade the older baseline, ` +
+            `or use --ignore-version-mismatch to force comparison (results may be incorrect).`, v1.raw, v2.raw);
+    }
+}
+/**
+ * Format a version for display.
+ *
+ * @param version - Version to format
+ * @returns Formatted version string like "v1.0.0"
+ */
+export function formatVersion(version) {
+    const parsed = parseVersion(version);
+    return `v${parsed.raw}`;
+}
+/**
+ * Check if a version is the current CLI version.
+ *
+ * @param version - Version to check
+ * @returns true if version matches current CLI version
+ */
+export function isCurrentVersion(version) {
+    const parsed = parseVersion(version);
+    const current = parseVersion(VERSION);
+    return compareVersions(parsed, current) === 0;
+}
+/**
+ * Check if a version is older than the current CLI version.
+ *
+ * @param version - Version to check
+ * @returns true if version is older than current
+ */
+export function isOlderVersion(version) {
+    const parsed = parseVersion(version);
+    const current = parseVersion(VERSION);
+    return compareVersions(parsed, current) < 0;
+}
+/**
+ * Check if a version is newer than the current CLI version.
+ *
+ * @param version - Version to check
+ * @returns true if version is newer than current
+ */
+export function isNewerVersion(version) {
+    const parsed = parseVersion(version);
+    const current = parseVersion(VERSION);
+    return compareVersions(parsed, current) > 0;
+}
+/**
+ * Check if a baseline version requires migration (different major version).
+ *
+ * @param version - Version to check
+ * @returns true if baseline needs migration to be compatible
+ */
+export function requiresMigration(version) {
+    const parsed = parseVersion(version);
+    const current = parseVersion(VERSION);
+    return parsed.major !== current.major;
+}
+//# sourceMappingURL=version.js.map

package/dist/cache/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache module exports.
+ */
+export { ResponseCache, ToolResponseCache, getGlobalCache, resetGlobalCache, type CacheEntry, type CacheStats, type CacheConfig, } from './response-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.js

@@ -0,0 +1,5 @@
+/**
+ * Cache module exports.
+ */
+export { ResponseCache, ToolResponseCache, getGlobalCache, resetGlobalCache, } from './response-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/response-cache.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Content-addressable cache for tool responses.
+ * Enables reuse of tool call results and LLM analysis across personas.
+ */
+/**
+ * Cache entry with metadata.
+ */
+export interface CacheEntry<T> {
+    /** The cached value */
+    value: T;
+    /** When the entry was created */
+    createdAt: Date;
+    /** When the entry expires */
+    expiresAt: Date;
+    /** Cache key (hash) */
+    key: string;
+    /** Human-readable description of what's cached */
+    description?: string;
+    /** Number of times this entry has been accessed */
+    hitCount: number;
+}
+/**
+ * Cache statistics.
+ */
+export interface CacheStats {
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Current number of entries */
+    entries: number;
+    /** Total bytes used (approximate) */
+    sizeBytes: number;
+    /** Hit rate as percentage */
+    hitRate: number;
+}
+/**
+ * Cache configuration.
+ */
+export interface CacheConfig {
+    /** Default TTL in milliseconds (default: 3600000 = 1 hour) */
+    defaultTTLMs?: number;
+    /** Maximum number of entries (default: 1000) */
+    maxEntries?: number;
+    /** Maximum total size in bytes (default: 50MB) */
+    maxSizeBytes?: number;
+    /** Whether to enable cache (default: true) */
+    enabled?: boolean;
+}
+/**
+ * In-memory content-addressable cache.
+ */
+export declare class ResponseCache {
+    private cache;
+    private config;
+    private stats;
+    private totalSizeBytes;
+    constructor(config?: CacheConfig);
+    /**
+     * Generate a cache key from input data.
+     */
+    generateKey(...parts: unknown[]): string;
+    /**
+     * Get an entry from cache.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set an entry in cache.
+     */
+    set<T>(key: string, value: T, options?: {
+        ttlMs?: number;
+        description?: string;
+    }): void;
+    /**
+     * Check if key exists and is not expired.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete an entry.
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Get or compute a value.
+     */
+    getOrCompute<T>(key: string, compute: () => Promise<T>, options?: {
+        ttlMs?: number;
+        description?: string;
+    }): Promise<T>;
+    /**
+     * Evict entries if needed to make room.
+     */
+    private evictIfNeeded;
+    /**
+     * Evict the oldest entry (LRU based on creation time).
+     */
+    private evictOldest;
+    /**
+     * Estimate the size of a value in bytes.
+     */
+    private estimateSize;
+}
+/**
+ * Specialized cache for tool responses.
+ */
+export declare class ToolResponseCache extends ResponseCache {
+    /**
+     * Generate key for a tool call.
+     */
+    toolCallKey(toolName: string, args: Record<string, unknown>): string;
+    /**
+     * Get cached tool response.
+     */
+    getToolResponse<T>(toolName: string, args: Record<string, unknown>): T | undefined;
+    /**
+     * Cache a tool response.
+     */
+    setToolResponse<T>(toolName: string, args: Record<string, unknown>, response: T, ttlMs?: number): void;
+    /**
+     * Generate key for LLM analysis.
+     */
+    analysisKey(toolName: string, args: Record<string, unknown>, responseHash: string): string;
+    /**
+     * Get cached analysis.
+     */
+    getAnalysis(toolName: string, args: Record<string, unknown>, responseHash: string): string | undefined;
+    /**
+     * Cache an analysis.
+     */
+    setAnalysis(toolName: string, args: Record<string, unknown>, responseHash: string, analysis: string, ttlMs?: number): void;
+    /**
+     * Hash a response for use in analysis key.
+     */
+    hashResponse(response: unknown): string;
+}
+/**
+ * Get or create the global cache instance.
+ */
+export declare function getGlobalCache(config?: CacheConfig): ToolResponseCache;
+/**
+ * Reset the global cache (for testing).
+ */
+export declare function resetGlobalCache(): void;
+//# sourceMappingURL=response-cache.d.ts.map

package/dist/cache/response-cache.js

@@ -0,0 +1,287 @@
+/**
+ * Content-addressable cache for tool responses.
+ * Enables reuse of tool call results and LLM analysis across personas.
+ */
+import { createHash } from 'crypto';
+import { getLogger } from '../logging/logger.js';
+import { TIME_CONSTANTS, CACHE } from '../constants.js';
+const logger = getLogger('response-cache');
+/**
+ * In-memory content-addressable cache.
+ */
+export class ResponseCache {
+    cache = new Map();
+    config;
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+    };
+    totalSizeBytes = 0;
+    constructor(config = {}) {
+        this.config = {
+            defaultTTLMs: config.defaultTTLMs ?? TIME_CONSTANTS.DEFAULT_CACHE_TTL,
+            maxEntries: config.maxEntries ?? CACHE.MAX_ENTRIES,
+            maxSizeBytes: config.maxSizeBytes ?? 50 * 1024 * 1024, // 50MB
+            enabled: config.enabled ?? true,
+        };
+    }
+    /**
+     * Generate a cache key from input data.
+     */
+    generateKey(...parts) {
+        const serialized = parts.map((p) => {
+            if (typeof p === 'string')
+                return p;
+            if (typeof p === 'undefined')
+                return 'undefined';
+            if (p === null)
+                return 'null';
+            try {
+                return JSON.stringify(p, Object.keys(p).sort());
+            }
+            catch {
+                return String(p);
+            }
+        }).join('|');
+        return createHash('sha256').update(serialized).digest('hex').slice(0, 16);
+    }
+    /**
+     * Get an entry from cache.
+     */
+    get(key) {
+        if (!this.config.enabled) {
+            return undefined;
+        }
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return undefined;
+        }
+        // Check expiration
+        if (new Date() > entry.expiresAt) {
+            this.delete(key);
+            this.stats.misses++;
+            logger.debug({ key }, 'Cache entry expired');
+            return undefined;
+        }
+        entry.hitCount++;
+        this.stats.hits++;
+        logger.debug({ key, hitCount: entry.hitCount }, 'Cache hit');
+        return entry.value;
+    }
+    /**
+     * Set an entry in cache.
+     */
+    set(key, value, options) {
+        if (!this.config.enabled) {
+            return;
+        }
+        const ttl = options?.ttlMs ?? this.config.defaultTTLMs;
+        const now = new Date();
+        // Calculate entry size
+        const entrySize = this.estimateSize(value);
+        // Evict if necessary
+        this.evictIfNeeded(entrySize);
+        const entry = {
+            value,
+            createdAt: now,
+            expiresAt: new Date(now.getTime() + ttl),
+            key,
+            description: options?.description,
+            hitCount: 0,
+        };
+        // Update size tracking
+        const existingEntry = this.cache.get(key);
+        if (existingEntry) {
+            this.totalSizeBytes -= this.estimateSize(existingEntry.value);
+        }
+        this.totalSizeBytes += entrySize;
+        this.cache.set(key, entry);
+        logger.debug({ key, ttlMs: ttl, description: options?.description }, 'Cache entry set');
+    }
+    /**
+     * Check if key exists and is not expired.
+     */
+    has(key) {
+        if (!this.config.enabled) {
+            return false;
+        }
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (new Date() > entry.expiresAt) {
+            this.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete an entry.
+     */
+    delete(key) {
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.totalSizeBytes -= this.estimateSize(entry.value);
+            this.cache.delete(key);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.cache.clear();
+        this.totalSizeBytes = 0;
+        logger.debug('Cache cleared');
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            entries: this.cache.size,
+            sizeBytes: this.totalSizeBytes,
+            hitRate: total > 0 ? (this.stats.hits / total) * 100 : 0,
+        };
+    }
+    /**
+     * Get or compute a value.
+     */
+    async getOrCompute(key, compute, options) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await compute();
+        this.set(key, value, options);
+        return value;
+    }
+    /**
+     * Evict entries if needed to make room.
+     */
+    evictIfNeeded(newEntrySize) {
+        // Check entry count
+        while (this.cache.size >= this.config.maxEntries) {
+            this.evictOldest();
+        }
+        // Check size
+        while (this.totalSizeBytes + newEntrySize > this.config.maxSizeBytes &&
+            this.cache.size > 0) {
+            this.evictOldest();
+        }
+    }
+    /**
+     * Evict the oldest entry (LRU based on creation time).
+     */
+    evictOldest() {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            const time = entry.createdAt.getTime();
+            if (time < oldestTime) {
+                oldestTime = time;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.delete(oldestKey);
+            this.stats.evictions++;
+            logger.debug({ key: oldestKey }, 'Evicted cache entry');
+        }
+    }
+    /**
+     * Estimate the size of a value in bytes.
+     */
+    estimateSize(value) {
+        try {
+            return JSON.stringify(value).length * 2; // Approximate UTF-16 size
+        }
+        catch {
+            return 1000; // Default estimate for non-serializable values
+        }
+    }
+}
+/**
+ * Specialized cache for tool responses.
+ */
+export class ToolResponseCache extends ResponseCache {
+    /**
+     * Generate key for a tool call.
+     */
+    toolCallKey(toolName, args) {
+        return this.generateKey('tool', toolName, args);
+    }
+    /**
+     * Get cached tool response.
+     */
+    getToolResponse(toolName, args) {
+        const key = this.toolCallKey(toolName, args);
+        return this.get(key);
+    }
+    /**
+     * Cache a tool response.
+     */
+    setToolResponse(toolName, args, response, ttlMs) {
+        const key = this.toolCallKey(toolName, args);
+        this.set(key, response, {
+            ttlMs,
+            description: `Tool: ${toolName}`,
+        });
+    }
+    /**
+     * Generate key for LLM analysis.
+     */
+    analysisKey(toolName, args, responseHash) {
+        return this.generateKey('analysis', toolName, args, responseHash);
+    }
+    /**
+     * Get cached analysis.
+     */
+    getAnalysis(toolName, args, responseHash) {
+        const key = this.analysisKey(toolName, args, responseHash);
+        return this.get(key);
+    }
+    /**
+     * Cache an analysis.
+     */
+    setAnalysis(toolName, args, responseHash, analysis, ttlMs) {
+        const key = this.analysisKey(toolName, args, responseHash);
+        this.set(key, analysis, {
+            ttlMs,
+            description: `Analysis: ${toolName}`,
+        });
+    }
+    /**
+     * Hash a response for use in analysis key.
+     */
+    hashResponse(response) {
+        return this.generateKey('response', response);
+    }
+}
+/**
+ * Global cache instance for sharing across modules.
+ */
+let globalCache;
+/**
+ * Get or create the global cache instance.
+ */
+export function getGlobalCache(config) {
+    if (!globalCache) {
+        globalCache = new ToolResponseCache(config);
+    }
+    return globalCache;
+}
+/**
+ * Reset the global cache (for testing).
+ */
+export function resetGlobalCache() {
+    globalCache?.clear();
+    globalCache = undefined;
+}
+//# sourceMappingURL=response-cache.js.map