@holoscript/framework 6.0.3

package/src/ai/__tests__/Blackboard.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { Blackboard } from '../Blackboard';
+
+describe('Blackboard', () => {
+  let bb: Blackboard;
+
+  beforeEach(() => {
+    bb = new Blackboard();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Get / Set / Has / Delete
+  // ---------------------------------------------------------------------------
+
+  it('set and get round-trip', () => {
+    bb.set('hp', 100);
+    expect(bb.get('hp')).toBe(100);
+  });
+
+  it('get returns undefined for missing key', () => {
+    expect(bb.get('nope')).toBeUndefined();
+  });
+
+  it('has checks key existence', () => {
+    bb.set('hp', 100);
+    expect(bb.has('hp')).toBe(true);
+    expect(bb.has('mp')).toBe(false);
+  });
+
+  it('delete removes key', () => {
+    bb.set('hp', 100);
+    expect(bb.delete('hp')).toBe(true);
+    expect(bb.has('hp')).toBe(false);
+  });
+
+  it('delete returns false for missing key', () => {
+    expect(bb.delete('nope')).toBe(false);
+  });
+
+  it('overwrite existing key', () => {
+    bb.set('hp', 100);
+    bb.set('hp', 50);
+    expect(bb.get('hp')).toBe(50);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Scopes
+  // ---------------------------------------------------------------------------
+
+  it('set with scope groups keys', () => {
+    bb.set('agentHp', 100, 'agent');
+    bb.set('agentMp', 50, 'agent');
+    bb.set('envTemp', 25, 'env');
+    const agentData = bb.getByScope('agent');
+    expect(agentData.size).toBe(2);
+    expect(agentData.get('agentHp')).toBe(100);
+  });
+
+  it('getByScope returns empty for unknown scope', () => {
+    expect(bb.getByScope('nope').size).toBe(0);
+  });
+
+  it('clearScope removes all keys in scope', () => {
+    bb.set('a', 1, 'temp');
+    bb.set('b', 2, 'temp');
+    bb.set('c', 3, 'keep');
+    const removed = bb.clearScope('temp');
+    expect(removed).toBe(2);
+    expect(bb.has('a')).toBe(false);
+    expect(bb.has('c')).toBe(true);
+  });
+
+  it('getScopes lists all scopes', () => {
+    bb.set('a', 1, 'x');
+    bb.set('b', 2, 'y');
+    const scopes = bb.getScopes();
+    expect(scopes).toContain('x');
+    expect(scopes).toContain('y');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Observers
+  // ---------------------------------------------------------------------------
+
+  it('observe fires callback on set', () => {
+    const cb = vi.fn();
+    bb.observe('hp', cb);
+    bb.set('hp', 100);
+    expect(cb).toHaveBeenCalledWith('hp', 100, undefined);
+  });
+
+  it('observe callback receives old value on update', () => {
+    const cb = vi.fn();
+    bb.set('hp', 100);
+    bb.observe('hp', cb);
+    bb.set('hp', 50);
+    expect(cb).toHaveBeenCalledWith('hp', 50, 100);
+  });
+
+  it('observeAll fires for any key change', () => {
+    const cb = vi.fn();
+    bb.observeAll(cb);
+    bb.set('a', 1);
+    bb.set('b', 2);
+    expect(cb).toHaveBeenCalledTimes(2);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Version Tracking
+  // ---------------------------------------------------------------------------
+
+  it('getVersion increments on update', () => {
+    bb.set('hp', 100);
+    expect(bb.getVersion('hp')).toBe(0);
+    bb.set('hp', 50);
+    expect(bb.getVersion('hp')).toBe(1);
+  });
+
+  it('getVersion returns -1 for missing key', () => {
+    expect(bb.getVersion('nope')).toBe(-1);
+  });
+
+  // ---------------------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------------------
+
+  it('getHistory records changes', () => {
+    bb.set('hp', 100);
+    bb.set('hp', 50);
+    const history = bb.getHistory();
+    expect(history.length).toBe(2);
+    expect(history[0].key).toBe('hp');
+    expect(history[0].value).toBe(100);
+    expect(history[1].value).toBe(50);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  it('getEntryCount counts total entries', () => {
+    expect(bb.getEntryCount()).toBe(0);
+    bb.set('a', 1);
+    bb.set('b', 2);
+    expect(bb.getEntryCount()).toBe(2);
+  });
+
+  it('getKeys lists all keys', () => {
+    bb.set('x', 1);
+    bb.set('y', 2);
+    expect(bb.getKeys().sort()).toEqual(['x', 'y']);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Clear
+  // ---------------------------------------------------------------------------
+
+  it('clear removes all data', () => {
+    bb.set('a', 1);
+    bb.set('b', 2);
+    bb.clear();
+    expect(bb.getEntryCount()).toBe(0);
+    expect(bb.getHistory()).toHaveLength(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+
+  it('toJSON exports key-value pairs', () => {
+    bb.set('hp', 100);
+    bb.set('name', 'hero');
+    const json = bb.toJSON();
+    expect(json.hp).toBe(100);
+    expect(json.name).toBe('hero');
+  });
+
+  it('fromJSON imports key-value pairs', () => {
+    bb.fromJSON({ x: 10, y: 20 });
+    expect(bb.get('x')).toBe(10);
+    expect(bb.get('y')).toBe(20);
+  });
+});

package/src/ai/__tests__/GenerationAnalytics.prod.test.ts

@@ -0,0 +1,141 @@
+/**
+ * GenerationAnalytics — Production Test Suite
+ *
+ * Covers: metric recording, aggregate computation, adapter metrics,
+ * confidence/response-time/error distributions, recommendations,
+ * time series, export, report generation, clear.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  GenerationAnalytics,
+  createAnalytics,
+  type GenerationMetrics,
+} from '../GenerationAnalytics';
+
+function metric(overrides: Partial<GenerationMetrics> = {}): GenerationMetrics {
+  return {
+    promptLength: overrides.promptLength ?? 100,
+    codeLength: overrides.codeLength ?? 200,
+    confidence: overrides.confidence ?? 0.8,
+    parseSuccess: overrides.parseSuccess ?? true,
+    errorCount: overrides.errorCount ?? 0,
+    wasFixed: overrides.wasFixed ?? false,
+    responseTimeMs: overrides.responseTimeMs ?? 500,
+    attemptsNeeded: overrides.attemptsNeeded ?? 1,
+    adapterName: overrides.adapterName ?? 'openai',
+    timestamp: overrides.timestamp ?? new Date(),
+    platform: overrides.platform ?? 'web',
+  };
+}
+
+describe('GenerationAnalytics — Production', () => {
+  // ─── Factory ──────────────────────────────────────────────────────
+  it('createAnalytics returns instance', () => {
+    expect(createAnalytics()).toBeInstanceOf(GenerationAnalytics);
+  });
+
+  // ─── Record + Get ─────────────────────────────────────────────────
+  it('recordMetric stores metric', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric());
+    expect(a.getAllMetrics().length).toBe(1);
+  });
+
+  it('clearMetrics empties all', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric());
+    a.clearMetrics();
+    expect(a.getAllMetrics().length).toBe(0);
+  });
+
+  // ─── Aggregates ───────────────────────────────────────────────────
+  it('getAggregateMetrics computes totals', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ parseSuccess: true, confidence: 0.9, responseTimeMs: 100 }));
+    a.recordMetric(metric({ parseSuccess: false, confidence: 0.5, responseTimeMs: 300 }));
+    const agg = a.getAggregateMetrics();
+    expect(agg.totalGenerations).toBe(2);
+    expect(agg.successRate).toBe(0.5);
+    expect(agg.avgConfidence).toBeCloseTo(0.7, 1);
+    expect(agg.avgResponseTime).toBeCloseTo(200, 0);
+  });
+
+  // ─── Adapter Metrics ──────────────────────────────────────────────
+  it('getMetricsByAdapter returns per-adapter stats', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ adapterName: 'openai', parseSuccess: true }));
+    a.recordMetric(metric({ adapterName: 'openai', parseSuccess: true }));
+    a.recordMetric(metric({ adapterName: 'claude', parseSuccess: false }));
+    const oai = a.getMetricsByAdapter('openai');
+    expect(oai.generationCount).toBe(2);
+    expect(oai.successRate).toBe(1);
+  });
+
+  it('getAllAdapterMetrics covers all adapters', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ adapterName: 'openai' }));
+    a.recordMetric(metric({ adapterName: 'claude' }));
+    const all = a.getAllAdapterMetrics();
+    expect(all.length).toBe(2);
+  });
+
+  // ─── Distributions ────────────────────────────────────────────────
+  it('getConfidenceDistribution returns buckets', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ confidence: 0.15 }));
+    a.recordMetric(metric({ confidence: 0.55 }));
+    a.recordMetric(metric({ confidence: 0.95 }));
+    const dist = a.getConfidenceDistribution();
+    expect(dist.length).toBeGreaterThan(0);
+    expect(dist.reduce((s, d) => s + d.count, 0)).toBe(3);
+  });
+
+  it('getResponseTimeDistribution returns buckets', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ responseTimeMs: 50 }));
+    a.recordMetric(metric({ responseTimeMs: 500 }));
+    a.recordMetric(metric({ responseTimeMs: 5000 }));
+    const dist = a.getResponseTimeDistribution();
+    expect(dist.length).toBeGreaterThan(0);
+  });
+
+  it('getErrorPatterns categorizes errors', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric({ parseSuccess: false, errorCount: 2 }));
+    a.recordMetric(metric({ parseSuccess: true, errorCount: 0 }));
+    const patterns = a.getErrorPatterns();
+    expect(patterns.length).toBeGreaterThan(0);
+  });
+
+  // ─── Recommendations ─────────────────────────────────────────────
+  it('getRecommendations returns array of strings', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric());
+    const recs = a.getRecommendations();
+    expect(Array.isArray(recs)).toBe(true);
+  });
+
+  // ─── Export / Report ──────────────────────────────────────────────
+  it('exportMetrics returns valid JSON', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric());
+    const json = a.exportMetrics();
+    expect(() => JSON.parse(json)).not.toThrow();
+  });
+
+  it('generateReport returns non-empty string', () => {
+    const a = new GenerationAnalytics();
+    a.recordMetric(metric());
+    const report = a.generateReport();
+    expect(report.length).toBeGreaterThan(0);
+  });
+
+  // ─── Time Series ──────────────────────────────────────────────────
+  it('getTimeSeries returns metrics windows', () => {
+    const a = new GenerationAnalytics();
+    const now = new Date();
+    a.recordMetric(metric({ timestamp: now }));
+    const ts = a.getTimeSeries(3600000);
+    expect(ts.length).toBeGreaterThanOrEqual(0); // may or may not window
+  });
+});

package/src/ai/__tests__/GenerationAnalytics.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { GenerationAnalytics } from '../GenerationAnalytics';
+import type { GenerationMetrics } from '../GenerationAnalytics';
+
+function makeMetric(overrides: Partial<GenerationMetrics> = {}): GenerationMetrics {
+  return {
+    promptLength: 50,
+    codeLength: 200,
+    confidence: 0.9,
+    parseSuccess: true,
+    errorCount: 0,
+    wasFixed: false,
+    responseTimeMs: 500,
+    attemptsNeeded: 1,
+    adapterName: 'gpt-4',
+    timestamp: new Date(),
+    ...overrides,
+  };
+}
+
+describe('GenerationAnalytics', () => {
+  let ga: GenerationAnalytics;
+
+  beforeEach(() => {
+    ga = new GenerationAnalytics();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Record / Get
+  // ---------------------------------------------------------------------------
+
+  it('recordMetric stores a metric', () => {
+    ga.recordMetric(makeMetric());
+    expect(ga.getAllMetrics()).toHaveLength(1);
+  });
+
+  it('getAllMetrics returns all recorded metrics', () => {
+    ga.recordMetric(makeMetric());
+    ga.recordMetric(makeMetric({ confidence: 0.5 }));
+    expect(ga.getAllMetrics()).toHaveLength(2);
+  });
+
+  it('clearMetrics removes all metrics', () => {
+    ga.recordMetric(makeMetric());
+    ga.clearMetrics();
+    expect(ga.getAllMetrics()).toHaveLength(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Aggregate Metrics
+  // ---------------------------------------------------------------------------
+
+  it('getAggregateMetrics calculates totalGenerations', () => {
+    ga.recordMetric(makeMetric());
+    ga.recordMetric(makeMetric());
+    const agg = ga.getAggregateMetrics();
+    expect(agg.totalGenerations).toBe(2);
+  });
+
+  it('getAggregateMetrics computes success rate', () => {
+    ga.recordMetric(makeMetric({ parseSuccess: true }));
+    ga.recordMetric(makeMetric({ parseSuccess: false }));
+    const agg = ga.getAggregateMetrics();
+    expect(agg.successRate).toBeCloseTo(0.5);
+  });
+
+  it('getAggregateMetrics computes average confidence', () => {
+    ga.recordMetric(makeMetric({ confidence: 0.8 }));
+    ga.recordMetric(makeMetric({ confidence: 0.6 }));
+    const agg = ga.getAggregateMetrics();
+    expect(agg.avgConfidence).toBeCloseTo(0.7);
+  });
+
+  it('getAggregateMetrics computes average response time', () => {
+    ga.recordMetric(makeMetric({ responseTimeMs: 400 }));
+    ga.recordMetric(makeMetric({ responseTimeMs: 600 }));
+    const agg = ga.getAggregateMetrics();
+    expect(agg.avgResponseTime).toBeCloseTo(500);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Adapter Metrics
+  // ---------------------------------------------------------------------------
+
+  it('getMetricsByAdapter returns per-adapter stats', () => {
+    ga.recordMetric(makeMetric({ adapterName: 'gpt-4', confidence: 0.9 }));
+    ga.recordMetric(makeMetric({ adapterName: 'gpt-4', confidence: 0.8 }));
+    ga.recordMetric(makeMetric({ adapterName: 'claude', confidence: 0.7 }));
+    const gpt = ga.getMetricsByAdapter('gpt-4');
+    expect(gpt.generationCount).toBe(2);
+    expect(gpt.avgConfidence).toBeCloseTo(0.85);
+  });
+
+  it('getAllAdapterMetrics lists all adapters', () => {
+    ga.recordMetric(makeMetric({ adapterName: 'a' }));
+    ga.recordMetric(makeMetric({ adapterName: 'b' }));
+    const all = ga.getAllAdapterMetrics();
+    expect(all.length).toBe(2);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Confidence Distribution
+  // ---------------------------------------------------------------------------
+
+  it('getConfidenceDistribution returns buckets', () => {
+    ga.recordMetric(makeMetric({ confidence: 0.15 }));
+    ga.recordMetric(makeMetric({ confidence: 0.85 }));
+    const dist = ga.getConfidenceDistribution();
+    expect(dist.length).toBeGreaterThan(0);
+    // Should have at least entries in low and high buckets
+    const total = dist.reduce((sum, d) => sum + d.count, 0);
+    expect(total).toBe(2);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error Patterns
+  // ---------------------------------------------------------------------------
+
+  it('getErrorPatterns identifies error types', () => {
+    ga.recordMetric(makeMetric({ parseSuccess: false, errorCount: 2 }));
+    ga.recordMetric(makeMetric({ parseSuccess: true, errorCount: 0 }));
+    const patterns = ga.getErrorPatterns();
+    expect(patterns).toBeDefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Recommendations
+  // ---------------------------------------------------------------------------
+
+  it('getRecommendations returns suggestions array', () => {
+    ga.recordMetric(makeMetric({ confidence: 0.3, parseSuccess: false }));
+    ga.recordMetric(makeMetric({ confidence: 0.2, parseSuccess: false }));
+    const recs = ga.getRecommendations();
+    expect(Array.isArray(recs)).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Export / Report
+  // ---------------------------------------------------------------------------
+
+  it('exportMetrics returns JSON string', () => {
+    ga.recordMetric(makeMetric());
+    const json = ga.exportMetrics();
+    const parsed = JSON.parse(json);
+    expect(parsed).toBeDefined();
+  });
+
+  it('generateReport returns readable string', () => {
+    ga.recordMetric(makeMetric());
+    const report = ga.generateReport();
+    expect(typeof report).toBe('string');
+    expect(report.length).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Response Time Distribution
+  // ---------------------------------------------------------------------------
+
+  it('getResponseTimeDistribution returns buckets', () => {
+    ga.recordMetric(makeMetric({ responseTimeMs: 100 }));
+    ga.recordMetric(makeMetric({ responseTimeMs: 5000 }));
+    const dist = ga.getResponseTimeDistribution();
+    expect(dist.length).toBeGreaterThan(0);
+  });
+});

package/src/ai/__tests__/GenerationCache.prod.test.ts

@@ -0,0 +1,144 @@
+/**
+ * GenerationCache (LRU) — Production Test Suite
+ *
+ * Covers: set/get, key generation, TTL expiry, LRU eviction,
+ * statistics, serialization, entries, remove, getSize, clear.
+ *
+ * Note: GenerationCache uses node's crypto module for hashing,
+ * which Vitest supports natively.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GenerationCache } from '../GenerationCache';
+
+describe('GenerationCache — Production', () => {
+  // Helper function to mock Date.now with offset or counter
+  const mockDateNow = (offsetMs: number) => {
+    const originalNow = Date.now;
+    Date.now = vi.fn(() => originalNow() + offsetMs);
+    return () => {
+      Date.now = originalNow;
+    };
+  };
+
+  const mockDateNowIncrementing = (startOffset: number = 0) => {
+    const originalNow = Date.now;
+    let counter = startOffset;
+    Date.now = vi.fn(() => originalNow() + counter++);
+    return () => {
+      Date.now = originalNow;
+    };
+  };
+
+  // ─── Basic Get/Set ────────────────────────────────────────────────
+  it('set + get returns cached entry', () => {
+    const cache = new GenerationCache();
+    cache.set('prompt1', 'code1', 0.9, 'openai');
+    const entry = cache.get('prompt1', 'openai');
+    expect(entry).not.toBeNull();
+    expect(entry!.code).toBe('code1');
+    expect(entry!.confidence).toBe(0.9);
+  });
+
+  it('get returns null on miss', () => {
+    const cache = new GenerationCache();
+    expect(cache.get('unknown', 'openai')).toBeNull();
+  });
+
+  it('different adapters have different keys', () => {
+    const cache = new GenerationCache();
+    cache.set('prompt', 'code-oai', 0.9, 'openai');
+    cache.set('prompt', 'code-cl', 0.8, 'claude');
+    expect(cache.get('prompt', 'openai')!.code).toBe('code-oai');
+    expect(cache.get('prompt', 'claude')!.code).toBe('code-cl');
+  });
+
+  // ─── Hit Tracking ─────────────────────────────────────────────────
+  it('get increments hit count', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    cache.get('p', 'a');
+    cache.get('p', 'a');
+    const entry = cache.get('p', 'a');
+    expect(entry!.hits).toBe(3);
+  });
+
+  // ─── TTL Expiry ───────────────────────────────────────────────────
+  it('expired entries are not returned', () => {
+    const cache = new GenerationCache({ ttlMs: 100 });
+    cache.set('p', 'c', 0.9, 'a');
+
+    // Fast-forward time
+    const restoreDateNow = mockDateNow(200);
+    expect(cache.get('p', 'a')).toBeNull();
+    restoreDateNow();
+  });
+
+  // ─── LRU Eviction ─────────────────────────────────────────────────
+  it('evicts oldest when maxSize reached', () => {
+    const cache = new GenerationCache({ maxSize: 2 });
+    cache.set('first', 'c1', 0.9, 'a');
+
+    // Ensure "second" and "third" are newer with incrementing timestamps
+    const restoreDateNow = mockDateNowIncrementing(1);
+
+    cache.set('second', 'c2', 0.9, 'a');
+    cache.set('third', 'c3', 0.9, 'a'); // should evict 'first'
+
+    restoreDateNow();
+
+    expect(cache.get('first', 'a')).toBeNull();
+    expect(cache.get('third', 'a')).not.toBeNull();
+  });
+
+  // ─── Statistics ───────────────────────────────────────────────────
+  it('getStats tracks hits and misses', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    cache.get('p', 'a'); // hit
+    cache.get('x', 'a'); // miss
+    const stats = cache.getStats();
+    expect(stats.totalHits).toBe(1);
+    expect(stats.totalMisses).toBe(1);
+    expect(stats.hitRate).toBeCloseTo(0.5);
+    expect(stats.entriesCount).toBe(1);
+  });
+
+  // ─── Serialization ───────────────────────────────────────────────
+  it('serialize produces valid JSON', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    const json = cache.serialize();
+    expect(() => JSON.parse(json)).not.toThrow();
+  });
+
+  // ─── Entries / Remove / Size ──────────────────────────────────────
+  it('getEntries returns all cached entries', () => {
+    const cache = new GenerationCache();
+    cache.set('a', 'ca', 0.9, 'openai');
+    cache.set('b', 'cb', 0.8, 'openai');
+    expect(cache.getEntries().length).toBe(2);
+  });
+
+  it('remove deletes specific entry', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    expect(cache.remove('p', 'a')).toBe(true);
+    expect(cache.get('p', 'a')).toBeNull();
+  });
+
+  it('getSize returns approximate byte size', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    expect(cache.getSize()).toBeGreaterThan(0);
+  });
+
+  // ─── Clear ────────────────────────────────────────────────────────
+  it('clear empties cache and resets stats', () => {
+    const cache = new GenerationCache();
+    cache.set('p', 'c', 0.9, 'a');
+    cache.get('p', 'a');
+    cache.clear();
+    expect(cache.getEntries().length).toBe(0);
+    expect(cache.getStats().totalHits).toBe(0);
+  });
+});