@littlebearapps/platform-admin-sdk 1.5.0 → 2.1.0

package/templates/shared/tests/unit/components/usage-transformers.test.ts

@@ -0,0 +1,473 @@
+/**
+ * Unit Tests for Usage Transformers
+ *
+ * Tests the data transformation logic that powers the UnifiedResourceTable.
+ * These functions are the core logic for ResourceRow rendering and filtering.
+ *
+ * @module tests/unit/components/usage-transformers
+ * @created 2026-01-05
+ * @task task-17.27 - Component tests for ResourceRow/ExpandedDetails
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  transformToUnifiedResources,
+  applyComparisonData,
+  filterResources,
+  sortResources,
+} from '../../../dashboard/src/components/usage/transformers';
+import type { UnifiedResource } from '../../../dashboard/src/components/usage/types';
+
+describe('Usage Transformers', () => {
+  describe('transformToUnifiedResources', () => {
+    const baseCosts = {
+      workers: 5.0,
+      d1: 2.0,
+      kv: 1.0,
+      r2: 3.0,
+      vectorize: 0.5,
+      pages: 0.0,
+      queues: 0.0,
+      workflows: 0.0,
+      durableObjects: 0.0,
+      aiGateway: 1.5,
+      total: 13.0,
+    };
+
+    const projectMapping = (name: string) => {
+      if (name.includes('my-project')) return 'my-project';
+      if (name.includes('platform')) return 'platform';
+      return 'other';
+    };
+
+    it('transforms workers data correctly', () => {
+      const data = {
+        workers: [
+          {
+            scriptName: 'my-project-api',
+            requests: 100000,
+            cpuTime: 5000,
+            duration: 1000,
+            errors: 50,
+          },
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].type).toBe('worker');
+      expect(resources[0].name).toBe('my-project-api');
+      expect(resources[0].project).toBe('my-project');
+      expect(resources[0].usage.value).toBe(100000);
+      expect(resources[0].usage.unit).toBe('requests');
+    });
+
+    it('transforms D1 databases correctly', () => {
+      const data = {
+        d1: [
+          {
+            databaseId: 'db-123',
+            databaseName: 'my-project-db',
+            rowsRead: 50000,
+            rowsWritten: 1000,
+            queryCount: 5000,
+          },
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].type).toBe('d1');
+      expect(resources[0].name).toBe('my-project-db');
+      expect(resources[0].usage.value).toBe(50000);
+      expect(resources[0].usage.unit).toBe('rows read');
+    });
+
+    it('transforms KV namespaces with total operations', () => {
+      const data = {
+        kv: [
+          {
+            namespaceId: 'kv-123',
+            namespaceName: 'platform-cache',
+            reads: 10000,
+            writes: 500,
+            deletes: 50,
+            lists: 100,
+          },
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].type).toBe('kv');
+      expect(resources[0].usage.value).toBe(10650); // 10000 + 500 + 50 + 100
+      expect(resources[0].usage.unit).toBe('operations');
+    });
+
+    it('transforms R2 buckets with storage formatting (decimal GB)', () => {
+      const data = {
+        r2: [
+          {
+            bucketName: 'my-project-ai-logs',
+            storageBytes: 1000000000, // 1 GB (decimal, Cloudflare billing unit)
+            objectCount: 1000,
+            classAOperations: 500,
+            classBOperations: 2000,
+          },
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].type).toBe('r2');
+      expect(resources[0].usage.value).toBe(1000000000);
+      // Uses decimal GB (1 GB = 1,000,000,000 bytes) to match Cloudflare billing
+      expect(resources[0].usage.formatted).toBe('1.00 GB');
+    });
+
+    it('transforms AI Gateway as single entry', () => {
+      const data = {
+        aiGateway: {
+          totalRequests: 5000,
+          totalTokens: 1000000,
+          cachedRequests: 1000,
+          modelBreakdown: [{ model: 'gpt-4', requests: 5000, tokens: 1000000 }],
+        },
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].type).toBe('ai-gateway');
+      expect(resources[0].name).toBe('AI Gateway');
+      expect(resources[0].usage.value).toBe(1000000);
+    });
+
+    it('calculates costs based on actual usage (requests + CPU time)', () => {
+      const data = {
+        workers: [
+          { scriptName: 'worker-1', requests: 1000, cpuTime: 100, duration: 10, errors: 0 },
+          { scriptName: 'worker-2', requests: 2000, cpuTime: 200, duration: 20, errors: 0 },
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources).toHaveLength(2);
+      // Costs are calculated based on actual usage: $0.30/million requests + $0.02/million CPU ms
+      // worker-1: (1000/1M) * 0.30 + (100/1M) * 0.02 = 0.0003 + 0.000002 = 0.000302
+      // worker-2: (2000/1M) * 0.30 + (200/1M) * 0.02 = 0.0006 + 0.000004 = 0.000604
+      expect(resources[0].costCurrent).toBeCloseTo(0.000302, 6);
+      expect(resources[1].costCurrent).toBeCloseTo(0.000604, 6);
+    });
+
+    it('handles empty data gracefully', () => {
+      const resources = transformToUnifiedResources({}, baseCosts, projectMapping);
+      expect(resources).toHaveLength(0);
+    });
+
+    it('sets worker status based on error rate', () => {
+      const data = {
+        workers: [
+          { scriptName: 'healthy', requests: 1000, cpuTime: 100, duration: 10, errors: 5 }, // 0.5% = healthy
+          { scriptName: 'warning', requests: 1000, cpuTime: 100, duration: 10, errors: 15 }, // 1.5% = warning
+          { scriptName: 'high', requests: 1000, cpuTime: 100, duration: 10, errors: 60 }, // 6% = high
+          { scriptName: 'critical', requests: 1000, cpuTime: 100, duration: 10, errors: 150 }, // 15% = critical
+        ],
+      };
+
+      const resources = transformToUnifiedResources(data, baseCosts, projectMapping);
+
+      expect(resources.find((r) => r.name === 'healthy')?.status).toBe('healthy');
+      expect(resources.find((r) => r.name === 'warning')?.status).toBe('warning');
+      expect(resources.find((r) => r.name === 'high')?.status).toBe('high');
+      expect(resources.find((r) => r.name === 'critical')?.status).toBe('critical');
+    });
+  });
+
+  describe('applyComparisonData', () => {
+    const currentResources: UnifiedResource[] = [
+      {
+        id: 'worker-api',
+        name: 'api',
+        type: 'worker',
+        project: 'platform',
+        usage: { value: 1000, unit: 'requests', formatted: '1K' },
+        costCurrent: 5.0,
+        costPrior: 0,
+        costDelta: 0,
+        costDeltaPct: null,
+        status: 'healthy',
+      },
+      {
+        id: 'd1-main',
+        name: 'main-db',
+        type: 'd1',
+        project: 'my-project',
+        usage: { value: 5000, unit: 'rows read', formatted: '5K' },
+        costCurrent: 2.0,
+        costPrior: 0,
+        costDelta: 0,
+        costDeltaPct: null,
+        status: 'healthy',
+      },
+    ];
+
+    it('calculates cost delta percentage correctly', () => {
+      const priorResources: UnifiedResource[] = [
+        {
+          ...currentResources[0],
+          costCurrent: 4.0, // Was $4, now $5 = +25%
+        },
+        {
+          ...currentResources[1],
+          costCurrent: 2.5, // Was $2.5, now $2 = -20%
+        },
+      ];
+
+      const result = applyComparisonData(currentResources, priorResources);
+
+      expect(result[0].costDelta).toBeCloseTo(1.0);
+      expect(result[0].costDeltaPct).toBeCloseTo(25);
+
+      expect(result[1].costDelta).toBeCloseTo(-0.5);
+      expect(result[1].costDeltaPct).toBeCloseTo(-20);
+    });
+
+    it('marks new resources as NEW', () => {
+      const priorResources: UnifiedResource[] = [currentResources[0]];
+
+      const result = applyComparisonData(currentResources, priorResources);
+
+      expect(result[0].costDeltaPct).toBeCloseTo(0); // Matching resource
+      expect(result[1].costDeltaPct).toBe('NEW'); // New resource
+    });
+
+    it('handles zero prior cost correctly', () => {
+      const priorResources: UnifiedResource[] = [
+        {
+          ...currentResources[0],
+          costCurrent: 0, // Was $0, now $5
+        },
+      ];
+
+      const result = applyComparisonData([currentResources[0]], priorResources);
+
+      // When prior cost is below $0.01 threshold and current cost > 0, returns 'NEW'
+      // This avoids extreme/undefined percentages from near-zero baselines
+      expect(result[0].costDeltaPct).toBe('NEW');
+    });
+  });
+
+  describe('filterResources', () => {
+    const testResources: UnifiedResource[] = [
+      {
+        id: 'worker-api',
+        name: 'my-project-api',
+        type: 'worker',
+        project: 'my-project',
+        usage: { value: 1000, unit: 'requests', formatted: '1K' },
+        costCurrent: 5.0,
+        costPrior: 4.0,
+        costDelta: 1.0,
+        costDeltaPct: 25,
+        status: 'healthy',
+      },
+      {
+        id: 'd1-main',
+        name: 'platform-db',
+        type: 'd1',
+        project: 'platform',
+        usage: { value: 5000, unit: 'rows read', formatted: '5K' },
+        costCurrent: 0,
+        costPrior: 0,
+        costDelta: 0,
+        costDeltaPct: 0,
+        status: 'healthy',
+      },
+      {
+        id: 'kv-cache',
+        name: 'my-project-cache',
+        type: 'kv',
+        project: 'my-project',
+        usage: { value: 500, unit: 'operations', formatted: '500' },
+        costCurrent: 1.0,
+        costPrior: 0,
+        costDelta: 1.0,
+        costDeltaPct: 'NEW' as const,
+        status: 'healthy',
+      },
+    ];
+
+    it('filters by project', () => {
+      const result = filterResources(testResources, { project: 'my-project' });
+
+      expect(result).toHaveLength(2);
+      expect(result.every((r) => r.project === 'my-project')).toBe(true);
+    });
+
+    it('filters by service type', () => {
+      const result = filterResources(testResources, { serviceTypes: ['worker', 'd1'] });
+
+      expect(result).toHaveLength(2);
+      expect(result.some((r) => r.type === 'worker')).toBe(true);
+      expect(result.some((r) => r.type === 'd1')).toBe(true);
+      expect(result.some((r) => r.type === 'kv')).toBe(false);
+    });
+
+    it('filters by search query (case insensitive)', () => {
+      const result = filterResources(testResources, { searchQuery: 'COPILOT' });
+
+      expect(result).toHaveLength(2);
+      expect(result.every((r) => r.name.toLowerCase().includes('copilot'))).toBe(true);
+    });
+
+    it('filters by onlyChanged (>5% change or NEW)', () => {
+      const result = filterResources(testResources, { onlyChanged: true });
+
+      expect(result).toHaveLength(2);
+      // First has 25% change, third is NEW
+      expect(result.some((r) => r.costDeltaPct === 25)).toBe(true);
+      expect(result.some((r) => r.costDeltaPct === 'NEW')).toBe(true);
+    });
+
+    it('filters by nonZeroCost', () => {
+      const result = filterResources(testResources, { nonZeroCost: true });
+
+      expect(result).toHaveLength(2);
+      expect(result.every((r) => r.costCurrent > 0)).toBe(true);
+    });
+
+    it('combines multiple filters', () => {
+      const result = filterResources(testResources, {
+        project: 'my-project',
+        nonZeroCost: true,
+      });
+
+      expect(result).toHaveLength(2);
+      expect(result.every((r) => r.project === 'my-project' && r.costCurrent > 0)).toBe(true);
+    });
+
+    it('returns all resources when no filters applied', () => {
+      const result = filterResources(testResources, {});
+      expect(result).toHaveLength(3);
+    });
+  });
+
+  describe('sortResources', () => {
+    const testResources: UnifiedResource[] = [
+      {
+        id: '1',
+        name: 'bravo',
+        type: 'worker',
+        project: 'alpha',
+        usage: { value: 500, unit: 'requests', formatted: '500' },
+        costCurrent: 3.0,
+        costPrior: 2.0,
+        costDelta: 1.0,
+        costDeltaPct: 50,
+        status: 'warning',
+      },
+      {
+        id: '2',
+        name: 'alpha',
+        type: 'd1',
+        project: 'bravo',
+        usage: { value: 1000, unit: 'rows', formatted: '1K' },
+        costCurrent: 1.0,
+        costPrior: 1.0,
+        costDelta: 0,
+        costDeltaPct: 0,
+        status: 'healthy',
+      },
+      {
+        id: '3',
+        name: 'charlie',
+        type: 'kv',
+        project: 'charlie',
+        usage: { value: 200, unit: 'ops', formatted: '200' },
+        costCurrent: 5.0,
+        costPrior: 0,
+        costDelta: 5.0,
+        costDeltaPct: 'NEW' as const,
+        status: 'critical',
+      },
+    ];
+
+    it('sorts by name ascending', () => {
+      const result = sortResources(testResources, 'name', 'asc');
+
+      expect(result[0].name).toBe('alpha');
+      expect(result[1].name).toBe('bravo');
+      expect(result[2].name).toBe('charlie');
+    });
+
+    it('sorts by name descending', () => {
+      const result = sortResources(testResources, 'name', 'desc');
+
+      expect(result[0].name).toBe('charlie');
+      expect(result[1].name).toBe('bravo');
+      expect(result[2].name).toBe('alpha');
+    });
+
+    it('sorts by cost current', () => {
+      const result = sortResources(testResources, 'costCurrent', 'desc');
+
+      expect(result[0].costCurrent).toBe(5.0);
+      expect(result[1].costCurrent).toBe(3.0);
+      expect(result[2].costCurrent).toBe(1.0);
+    });
+
+    it('sorts by usage value', () => {
+      const result = sortResources(testResources, 'usage', 'desc');
+
+      expect(result[0].usage.value).toBe(1000);
+      expect(result[1].usage.value).toBe(500);
+      expect(result[2].usage.value).toBe(200);
+    });
+
+    it('sorts by costDeltaPct with NEW at end (ascending)', () => {
+      const result = sortResources(testResources, 'costDeltaPct', 'asc');
+
+      // 0, 50, NEW (infinity)
+      expect(result[0].costDeltaPct).toBe(0);
+      expect(result[1].costDeltaPct).toBe(50);
+      expect(result[2].costDeltaPct).toBe('NEW');
+    });
+
+    it('sorts by costDeltaPct with NEW at start (descending)', () => {
+      const result = sortResources(testResources, 'costDeltaPct', 'desc');
+
+      // NEW first when descending
+      expect(result[0].costDeltaPct).toBe('NEW');
+      expect(result[1].costDeltaPct).toBe(50);
+      expect(result[2].costDeltaPct).toBe(0);
+    });
+
+    it('sorts by status severity', () => {
+      const result = sortResources(testResources, 'status', 'desc');
+
+      expect(result[0].status).toBe('critical');
+      expect(result[1].status).toBe('warning');
+      expect(result[2].status).toBe('healthy');
+    });
+
+    it('sorts by type', () => {
+      const result = sortResources(testResources, 'type', 'asc');
+
+      expect(result[0].type).toBe('d1');
+      expect(result[1].type).toBe('kv');
+      expect(result[2].type).toBe('worker');
+    });
+
+    it('preserves order for unknown columns', () => {
+      const result = sortResources(testResources, 'unknown', 'asc');
+
+      expect(result).toHaveLength(3);
+    });
+  });
+});

package/templates/shared/tests/unit/control.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Unit Tests for PID Controller
+ *
+ * Tests the stateless PID controller for intelligent degradation throttling.
+ *
+ * @module tests/unit/control
+ * @created 2026-01-23
+ * @task Intelligent Degradation for Platform Usage
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  computePID,
+  createPIDState,
+  calculateUtilisation,
+  shouldUpdatePID,
+  formatThrottleRate,
+  DEFAULT_PID_CONFIG,
+  type PIDState,
+  type PIDConfig,
+} from '../../workers/lib/control';
+
+describe('PID Controller', () => {
+  describe('createPIDState', () => {
+    it('creates fresh state with zero values', () => {
+      const state = createPIDState();
+
+      expect(state.integral).toBe(0);
+      expect(state.prevError).toBe(0);
+      expect(state.throttleRate).toBe(0);
+      expect(state.lastUpdate).toBeGreaterThan(0);
+    });
+  });
+
+  describe('computePID', () => {
+    it('returns zero throttle when usage is below setpoint', () => {
+      const state = createPIDState();
+      const input = { currentUsage: 0.5, deltaTimeMs: 60000 }; // 50% usage, setpoint is 70%
+
+      const output = computePID(state, input);
+
+      // Error is negative (0.5 - 0.7 = -0.2), so throttle should be 0 (clamped)
+      expect(output.throttleRate).toBe(0);
+      expect(output.debug.error).toBeCloseTo(-0.2, 10);
+    });
+
+    it('increases throttle when usage exceeds setpoint', () => {
+      const state = createPIDState();
+      const input = { currentUsage: 0.9, deltaTimeMs: 60000 }; // 90% usage
+
+      const output = computePID(state, input);
+
+      // Error is positive (0.9 - 0.7 = 0.2), should have positive throttle
+      expect(output.throttleRate).toBeGreaterThan(0);
+      expect(output.debug.error).toBeCloseTo(0.2, 10);
+    });
+
+    it('clamps throttle rate to [0, 1] range', () => {
+      const state = createPIDState();
+      // Extreme over-budget scenario
+      const input = { currentUsage: 5.0, deltaTimeMs: 60000 }; // 500% usage
+
+      const output = computePID(state, input);
+
+      expect(output.throttleRate).toBeLessThanOrEqual(1);
+      expect(output.throttleRate).toBeGreaterThanOrEqual(0);
+    });
+
+    it('accumulates integral term over time', () => {
+      let state = createPIDState();
+
+      // Simulate sustained over-budget usage
+      for (let i = 0; i < 5; i++) {
+        const output = computePID(state, { currentUsage: 0.85, deltaTimeMs: 60000 });
+        state = output.newState;
+      }
+
+      // Integral should have accumulated
+      expect(state.integral).toBeGreaterThan(0);
+    });
+
+    it('clamps integral to prevent windup', () => {
+      let state = createPIDState();
+
+      // Extreme sustained over-budget
+      for (let i = 0; i < 100; i++) {
+        const output = computePID(state, { currentUsage: 2.0, deltaTimeMs: 60000 });
+        state = output.newState;
+      }
+
+      // Integral should be clamped at integralMax (2.0)
+      expect(state.integral).toBeLessThanOrEqual(DEFAULT_PID_CONFIG.integralMax);
+    });
+
+    it('calculates derivative term for rate of change', () => {
+      const state: PIDState = {
+        integral: 0,
+        prevError: 0.1, // Previous error was 0.1
+        lastUpdate: Date.now() - 60000,
+        throttleRate: 0,
+      };
+
+      // Current error is 0.2 (rate of change = 0.1 over 60s)
+      const output = computePID(state, { currentUsage: 0.9, deltaTimeMs: 60000 });
+
+      // dTerm = kd * (error - prevError) / dt
+      // = 0.05 * (0.2 - 0.1) / 60 = 0.05 * 0.1 / 60 ≈ 0.000083
+      expect(output.debug.dTerm).toBeGreaterThan(0);
+    });
+
+    it('uses custom config when provided', () => {
+      const state = createPIDState();
+      const customConfig: PIDConfig = {
+        kp: 1.0,
+        ki: 0,
+        kd: 0,
+        setpoint: 0.5,
+        outputMin: 0,
+        outputMax: 1,
+        integralMax: 2.0,
+      };
+
+      const input = { currentUsage: 0.8, deltaTimeMs: 60000 };
+      const output = computePID(state, input, customConfig);
+
+      // With kp=1, error=0.3, pTerm should be 0.3
+      expect(output.debug.pTerm).toBeCloseTo(0.3, 10);
+      expect(output.debug.error).toBeCloseTo(0.3, 10);
+    });
+
+    it('preserves state continuity across updates', () => {
+      let state = createPIDState();
+
+      // First update with short deltaTime to avoid integral saturation
+      const output1 = computePID(state, { currentUsage: 0.8, deltaTimeMs: 1000 });
+      state = output1.newState;
+
+      // Second update should use previous error
+      const output2 = computePID(state, { currentUsage: 0.85, deltaTimeMs: 1000 });
+
+      expect(output2.newState.prevError).toBeCloseTo(0.15, 10); // 0.85 - 0.70
+      // Integral should accumulate (both updates have positive error)
+      expect(output2.newState.integral).toBeGreaterThan(output1.newState.integral);
+    });
+  });
+
+  describe('calculateUtilisation', () => {
+    it('calculates correct utilisation ratio', () => {
+      expect(calculateUtilisation(70, 100)).toBe(0.7);
+      expect(calculateUtilisation(100, 100)).toBe(1.0);
+      expect(calculateUtilisation(150, 100)).toBe(1.5);
+    });
+
+    it('returns 0 when limit is 0 or negative', () => {
+      expect(calculateUtilisation(50, 0)).toBe(0);
+      expect(calculateUtilisation(50, -10)).toBe(0);
+    });
+
+    it('handles zero usage', () => {
+      expect(calculateUtilisation(0, 100)).toBe(0);
+    });
+  });
+
+  describe('shouldUpdatePID', () => {
+    it('returns true when interval has passed', () => {
+      const lastUpdate = Date.now() - 65000; // 65 seconds ago
+      expect(shouldUpdatePID(lastUpdate, 60000)).toBe(true);
+    });
+
+    it('returns false when interval has not passed', () => {
+      const lastUpdate = Date.now() - 30000; // 30 seconds ago
+      expect(shouldUpdatePID(lastUpdate, 60000)).toBe(false);
+    });
+
+    it('returns true exactly at interval boundary', () => {
+      const lastUpdate = Date.now() - 60000; // Exactly 60 seconds ago
+      expect(shouldUpdatePID(lastUpdate, 60000)).toBe(true);
+    });
+  });
+
+  describe('formatThrottleRate', () => {
+    it('formats rate as percentage with one decimal', () => {
+      expect(formatThrottleRate(0)).toBe('0.0%');
+      expect(formatThrottleRate(0.5)).toBe('50.0%');
+      expect(formatThrottleRate(1)).toBe('100.0%');
+      expect(formatThrottleRate(0.123)).toBe('12.3%');
+    });
+  });
+
+  describe('PID Convergence', () => {
+    it('converges to stable throttle under constant load', () => {
+      let state = createPIDState();
+      const throttleRates: number[] = [];
+
+      // Simulate 10 minutes of constant 85% usage
+      for (let i = 0; i < 10; i++) {
+        const output = computePID(state, { currentUsage: 0.85, deltaTimeMs: 60000 });
+        state = output.newState;
+        throttleRates.push(output.throttleRate);
+      }
+
+      // After convergence, throttle rate should stabilise
+      const last3 = throttleRates.slice(-3);
+      const variance = Math.max(...last3) - Math.min(...last3);
+      expect(variance).toBeLessThan(0.05); // Less than 5% variance
+    });
+
+    it('responds quickly to sudden usage spike', () => {
+      let state = createPIDState();
+
+      // Normal usage for a while
+      for (let i = 0; i < 5; i++) {
+        const output = computePID(state, { currentUsage: 0.5, deltaTimeMs: 60000 });
+        state = output.newState;
+      }
+
+      const throttleBefore = state.throttleRate;
+
+      // Sudden spike to 150% usage
+      const output = computePID(state, { currentUsage: 1.5, deltaTimeMs: 60000 });
+
+      // Throttle should increase significantly
+      expect(output.throttleRate).toBeGreaterThan(throttleBefore + 0.2);
+    });
+  });
+});