margin-ts 0.6.0 → 0.6.2

package/src/adapters/stream.ts

@@ -0,0 +1,227 @@
+/**
+ * Streaming health updates via Server-Sent Events (SSE).
+ *
+ * Push health/drift/anomaly updates to browser dashboards in real-time.
+ *
+ * Express:
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Next.js Pages Router:
+ *   export default marginSSEHandler(monitor);
+ *
+ * Browser client:
+ *   const source = new EventSource('/margin/stream');
+ *   source.onmessage = (e) => {
+ *     const health = JSON.parse(e.data);
+ *     updateDashboard(health);
+ *   };
+ *
+ * Zero dependencies. Works with any framework that supports
+ * writable response streams (Express, Fastify, Next.js, raw Node http).
+ */
+
+import {
+  Confidence,
+  Health,
+  Observation,
+  Expression,
+  Parser,
+  createExpression,
+  expressionToString,
+  expressionToDict,
+  classifyDrift,
+  DriftClassification,
+  DriftState,
+  DriftDirection,
+  classifyAnomaly,
+  AnomalyClassification,
+  AnomalyState,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// StreamingMonitor — the TS equivalent of Python's Monitor
+// -----------------------------------------------------------------------
+
+interface ComponentWindow {
+  values: number[];
+  observations: Observation[];
+  maxWindow: number;
+}
+
+export class StreamingMonitor {
+  private parser: Parser;
+  private windows: Map<string, ComponentWindow> = new Map();
+  private _expression: Expression | null = null;
+  private _step = 0;
+  private maxWindow: number;
+  private minAnomalyRef: number;
+
+  constructor(parser: Parser, options: { window?: number; minAnomalyRef?: number } = {}) {
+    this.parser = parser;
+    this.maxWindow = options.window ?? 100;
+    this.minAnomalyRef = options.minAnomalyRef ?? 10;
+  }
+
+  get expression(): Expression | null { return this._expression; }
+  get step(): number { return this._step; }
+
+  update(values: Record<string, number>, now?: Date): Expression {
+    now = now ?? new Date();
+    this._expression = this.parser.parse(values, { step: this._step });
+    this._step++;
+
+    // Update per-component windows
+    for (const obs of this._expression.observations) {
+      if (!this.windows.has(obs.name)) {
+        this.windows.set(obs.name, { values: [], observations: [], maxWindow: this.maxWindow });
+      }
+      const w = this.windows.get(obs.name)!;
+      w.values.push(obs.value);
+      // Stamp the observation with time for drift
+      const stamped = { ...obs, measuredAt: now };
+      w.observations.push(stamped);
+      if (w.values.length > this.maxWindow) {
+        w.values.shift();
+        w.observations.shift();
+      }
+    }
+
+    return this._expression;
+  }
+
+  drift(component: string): DriftClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.observations.length < 3) return null;
+    return classifyDrift(w.observations);
+  }
+
+  anomaly(component: string): AnomalyClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.values.length < this.minAnomalyRef + 1) return null;
+    const ref = w.values.slice(0, -1);
+    const current = w.values[w.values.length - 1];
+    return classifyAnomaly(current, ref, { component });
+  }
+
+  status(): Record<string, unknown> {
+    const drift: Record<string, unknown> = {};
+    const anomaly: Record<string, unknown> = {};
+
+    for (const [name] of this.windows) {
+      const dc = this.drift(name);
+      if (dc) drift[name] = { state: dc.state, direction: dc.direction, rate: dc.rate };
+      const ac = this.anomaly(name);
+      if (ac) anomaly[name] = { state: ac.state, zScore: ac.zScore };
+    }
+
+    return {
+      step: this._step,
+      expression: this._expression ? expressionToString(this._expression) : null,
+      health: this._expression ? expressionToDict(this._expression) : null,
+      drift,
+      anomaly,
+    };
+  }
+
+  reset(): void {
+    this.windows.clear();
+    this._expression = null;
+    this._step = 0;
+  }
+}
+
+// -----------------------------------------------------------------------
+// SSE helpers
+// -----------------------------------------------------------------------
+
+/** Connected SSE client. */
+interface SSEClient {
+  id: string;
+  res: any;
+}
+
+let _clients: SSEClient[] = [];
+let _clientIdCounter = 0;
+
+/**
+ * Broadcast a status update to all connected SSE clients.
+ * Call this after each monitor.update().
+ */
+export function broadcast(monitor: StreamingMonitor): void {
+  const data = JSON.stringify(monitor.status());
+  const message = `data: ${data}\n\n`;
+  _clients = _clients.filter(client => {
+    try {
+      client.res.write(message);
+      return true;
+    } catch {
+      return false; // client disconnected
+    }
+  });
+}
+
+/**
+ * Express/Fastify route handler for SSE streaming.
+ *
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Each connected browser receives real-time health updates.
+ * Call broadcast(monitor) after each monitor.update() to push.
+ */
+export function marginSSE(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (req: any, res: any) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    // Send current state immediately
+    const initial = JSON.stringify(monitor.status());
+    res.write(`data: ${initial}\n\n`);
+
+    const client: SSEClient = { id: String(++_clientIdCounter), res };
+    _clients.push(client);
+
+    req.on('close', () => {
+      _clients = _clients.filter(c => c.id !== client.id);
+    });
+  };
+}
+
+/**
+ * Next.js Pages Router SSE handler.
+ *
+ *   // pages/api/margin/stream.ts
+ *   export default marginSSEHandler(monitor);
+ */
+export function marginSSEHandler(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return marginSSE(monitor);
+}
+
+/**
+ * Create a polling endpoint (for environments that don't support SSE).
+ * Returns the current status as JSON on each request.
+ *
+ *   app.get('/margin/poll', marginPoll(monitor));
+ */
+export function marginPoll(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (_req: any, res: any) => {
+    res.json(monitor.status());
+  };
+}
+
+/** Number of connected SSE clients. */
+export function connectedClients(): number {
+  return _clients.length;
+}
+
+/** Disconnect all SSE clients (for testing). */
+export function resetClients(): void {
+  for (const client of _clients) {
+    try { client.res.end(); } catch {}
+  }
+  _clients = [];
+  _clientIdCounter = 0;
+}

package/src/adapters/vitest.ts

@@ -0,0 +1,141 @@
+/**
+ * Vitest/Jest test health reporter for margin.
+ *
+ * Classifies test suite health after every run: pass rate, duration,
+ * flake rate. The JS equivalent of margin's pytest plugin.
+ *
+ * Usage with vitest:
+ *   // vitest.config.ts
+ *   import { marginReporter } from 'margin-ts/adapters/vitest';
+ *   export default { test: { reporters: ['default', marginReporter()] } };
+ *
+ * Or use standalone after collecting results:
+ *   import { classifySuite } from 'margin-ts/adapters/vitest';
+ *   const health = classifySuite({ passed: 95, failed: 3, skipped: 2, durationMs: 4500 });
+ */
+
+import {
+  Confidence,
+  Health,
+  Thresholds,
+  createThresholds,
+  classify,
+  Observation,
+  Expression,
+  createExpression,
+  expressionToString,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// Suite metrics thresholds
+// -----------------------------------------------------------------------
+
+export interface SuiteThresholds {
+  passRate: Thresholds;
+  skipRate: Thresholds;
+  meanDurationMs: Thresholds;
+  totalDurationMs: Thresholds;
+}
+
+export const DEFAULT_SUITE_THRESHOLDS: SuiteThresholds = {
+  passRate: createThresholds(0.95, 0.70, true),        // higher is better
+  skipRate: createThresholds(0.05, 0.20, false),        // lower is better
+  meanDurationMs: createThresholds(100, 1000, false),   // lower is better
+  totalDurationMs: createThresholds(30000, 120000, false), // lower is better
+};
+
+// -----------------------------------------------------------------------
+// Suite results → Expression
+// -----------------------------------------------------------------------
+
+export interface SuiteResults {
+  passed: number;
+  failed: number;
+  skipped: number;
+  durationMs: number;
+  testDurations?: number[];  // per-test durations in ms
+}
+
+export function classifySuite(
+  results: SuiteResults,
+  thresholds: SuiteThresholds = DEFAULT_SUITE_THRESHOLDS,
+  label = '',
+): Expression {
+  const total = results.passed + results.failed + results.skipped;
+  if (total === 0) return createExpression([], [], label);
+
+  const passRate = results.passed / total;
+  const skipRate = results.skipped / total;
+  const meanDuration = results.testDurations && results.testDurations.length > 0
+    ? results.testDurations.reduce((a, b) => a + b, 0) / results.testDurations.length
+    : results.durationMs / total;
+
+  const now = new Date();
+  const observations: Observation[] = [
+    {
+      name: 'pass_rate',
+      health: classify(passRate, Confidence.HIGH, thresholds.passRate),
+      value: passRate,
+      baseline: 1.0,
+      confidence: Confidence.HIGH,
+      higherIsBetter: true,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: 'skip_rate',
+      health: classify(skipRate, Confidence.HIGH, thresholds.skipRate),
+      value: skipRate,
+      baseline: 0.0,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: 'mean_duration',
+      health: classify(meanDuration, Confidence.HIGH, thresholds.meanDurationMs),
+      value: meanDuration,
+      baseline: 50,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: 'total_duration',
+      health: classify(results.durationMs, Confidence.MODERATE, thresholds.totalDurationMs),
+      value: results.durationMs,
+      baseline: 10000,
+      confidence: Confidence.MODERATE,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: 'failures',
+      health: classify(results.failed, Confidence.HIGH, createThresholds(0, 5, false)),
+      value: results.failed,
+      baseline: 0,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+  ];
+
+  return createExpression(observations, [], label || `suite (${total} tests)`);
+}
+
+/**
+ * Format suite health as a printable string.
+ */
+export function suiteHealthString(results: SuiteResults, thresholds?: SuiteThresholds): string {
+  const expr = classifySuite(results, thresholds);
+  const total = results.passed + results.failed + results.skipped;
+  const lines = [
+    `margin health: ${total} tests (${results.passed} passed, ${results.failed} failed, ${results.skipped} skipped)`,
+    `  ${expressionToString(expr)}`,
+  ];
+  return lines.join('\n');
+}

package/src/index.ts

@@ -31,3 +31,30 @@ export {
   AnomalyState, ANOMALY_SEVERITY, AnomalyClassification,
   classifyAnomaly,
 } from './anomaly.js';
+
+// Adapters
+export {
+  marginMiddleware, marginHealthRoute,
+  DEFAULT_THRESHOLDS as EXPRESS_THRESHOLDS,
+  type MarginMiddlewareOptions, type MarginState, type EndpointThresholds,
+} from './adapters/express.js';
+
+export {
+  classifySuite, suiteHealthString,
+  DEFAULT_SUITE_THRESHOLDS,
+  type SuiteResults, type SuiteThresholds,
+} from './adapters/vitest.js';
+
+export {
+  withMargin, withMarginApp,
+  marginHealthHandler, marginHealthAppHandler,
+  resetRoutes,
+  DEFAULT_NEXTJS_THRESHOLDS,
+  type WithMarginOptions, type NextjsThresholds,
+} from './adapters/nextjs.js';
+
+export {
+  StreamingMonitor,
+  broadcast, marginSSE, marginSSEHandler, marginPoll,
+  connectedClients, resetClients,
+} from './adapters/stream.js';