@forgecharts/sdk 1.1.23

package/src/__tests__/candleInvariant.test.ts

@@ -0,0 +1,500 @@
+/**
+ * Candle Invariant Tests
+ *
+ * Verifies that the invariant guards in `candleInvariants.ts` fire correctly,
+ * and that `CandleEngine.applyLiveUpdate` maintains all invariants during
+ * normal operation (no warnings) and surfaces violations during abnormal
+ * conditions (mocked guard paths).
+ *
+ * Test categories:
+ *   1. assertOhlcRelationships — each OHLC violation is detected independently
+ *   2. assertBucketAlignment — misaligned timestamps are caught
+ *   3. assertNotFinalized — mutating a closed bar triggers the guard
+ *   4. assertOpenImmutability — open-price overwrite is detected
+ *   5. assertNoDuplicateAppend — same-bucket spurious append is detected
+ *   6. assertFinalizedUnchanged — new-bucket finalisation is verified
+ *   7. CandleEngine integration — no spurious warnings during correct operation
+ *   8. barDivergenceCheck — compareSources and formatReport
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  assertOhlcRelationships,
+  assertBucketAlignment,
+  assertNotFinalized,
+  assertOpenImmutability,
+  assertNoDuplicateAppend,
+  assertFinalizedUnchanged,
+  _setReporter,
+  _resetReporter,
+} from '../engine/candleInvariants';
+import type { CandleBar } from '../engine/CandleEngine';
+import { CandleEngine } from '../engine/CandleEngine';
+import type { RawOHLCV } from '../engine/CandleEngine';
+import {
+  compareSources,
+  checkAllSources,
+  formatReport,
+} from '../tools/barDivergenceCheck';
+import type { SourceBars } from '../tools/barDivergenceCheck';
+
+// ─── Reporter harness ─────────────────────────────────────────────────────────
+
+/**
+ * During tests we capture invariant violation messages instead of printing
+ * them to console.  This lets us assert on the exact message content.
+ */
+let violations: string[] = [];
+
+beforeEach(() => {
+  violations = [];
+  _setReporter((msg) => violations.push(msg));
+});
+
+afterEach(() => {
+  _resetReporter();
+});
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+/** Build a valid, closed CandleBar. */
+function validBar(overrides: Partial<CandleBar> = {}): CandleBar {
+  return {
+    timeMs:   60_000,
+    time:     60,
+    open:     100,
+    high:     110,
+    low:       90,
+    close:    105,
+    volume:     1,
+    isClosed: true,
+    ...overrides,
+  };
+}
+
+/** Unix seconds helper. */
+const sec = (iso: string): number => new Date(iso).getTime() / 1000;
+
+/** Build a minimal RawOHLCV tick for the engine. */
+function tick(
+  timeSec: number,
+  open = 100, high = 110, low = 90, close = 105, volume = 1,
+): RawOHLCV {
+  return { time: timeSec, open, high, low, close, volume };
+}
+
+// ─── 1. assertOhlcRelationships ───────────────────────────────────────────────
+
+describe('assertOhlcRelationships', () => {
+  it('passes for a valid OHLC bar with no violations', () => {
+    assertOhlcRelationships(validBar(), 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects high < open', () => {
+    assertOhlcRelationships(validBar({ open: 120, high: 110 }), 'ctx');
+    expect(violations.some(v => v.includes('high') && v.includes('open'))).toBe(true);
+  });
+
+  it('detects high < close', () => {
+    assertOhlcRelationships(validBar({ close: 120, high: 110 }), 'ctx');
+    expect(violations.some(v => v.includes('high') && v.includes('close'))).toBe(true);
+  });
+
+  it('detects high < low', () => {
+    assertOhlcRelationships(validBar({ high: 80, low: 90 }), 'ctx');
+    expect(violations.some(v => v.includes('high') && v.includes('low'))).toBe(true);
+  });
+
+  it('detects low > open', () => {
+    assertOhlcRelationships(validBar({ open: 80, low: 90 }), 'ctx');
+    expect(violations.some(v => v.includes('low') && v.includes('open'))).toBe(true);
+  });
+
+  it('detects low > close', () => {
+    assertOhlcRelationships(validBar({ close: 80, low: 90 }), 'ctx');
+    expect(violations.some(v => v.includes('low') && v.includes('close'))).toBe(true);
+  });
+
+  it('open === high === low === close is valid (doji candle)', () => {
+    assertOhlcRelationships(validBar({ open: 100, high: 100, low: 100, close: 100 }), 'ctx');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('includes context and timeMs in violation message', () => {
+    assertOhlcRelationships(validBar({ open: 120, high: 110, timeMs: 99_000 }), 'myCtx');
+    expect(violations[0]).toContain('[CANDLE_INVARIANT]');
+    expect(violations[0]).toContain('myCtx');
+    expect(violations[0]).toContain('99000');
+  });
+});
+
+// ─── 2. assertBucketAlignment ─────────────────────────────────────────────────
+
+describe('assertBucketAlignment', () => {
+  it('passes when timeMs is exactly on the 1m boundary', () => {
+    // 60_000 ms = exactly 1 minute from epoch — valid 1m bucket start
+    assertBucketAlignment(validBar({ timeMs: 60_000, time: 60 }), '1m', 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects timeMs not on a 1m boundary', () => {
+    // 62_500 ms is NOT on a 60_000-ms boundary
+    assertBucketAlignment(validBar({ timeMs: 62_500, time: 62 }), '1m', 'test');
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0]).toContain('timeMs');
+  });
+
+  it('passes for 1h boundary', () => {
+    const hourStart = new Date('2025-03-09T14:00:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: hourStart, time: hourStart / 1000 }), '1h', 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects misaligned 1h timestamp (30 min off)', () => {
+    const thirtyMin = new Date('2025-03-09T14:30:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: thirtyMin, time: thirtyMin / 1000 }), '1h', 'test');
+    expect(violations.length).toBeGreaterThan(0);
+  });
+
+  it('passes for a Monday 00:00 UTC timestamp with 1w', () => {
+    const monday = new Date('2025-03-03T00:00:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: monday, time: monday / 1000 }), '1w', 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects misaligned 1w timestamp (mid-week)', () => {
+    const wednesday = new Date('2025-03-05T12:00:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: wednesday, time: wednesday / 1000 }), '1w', 'test');
+    expect(violations.length).toBeGreaterThan(0);
+  });
+
+  it('passes for first-of-month timestamp with 1M', () => {
+    const monthStart = new Date('2025-03-01T00:00:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: monthStart, time: monthStart / 1000 }), '1M', 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects mid-month timestamp with 1M', () => {
+    const midMonth = new Date('2025-03-15T00:00:00Z').getTime();
+    assertBucketAlignment(validBar({ timeMs: midMonth, time: midMonth / 1000 }), '1M', 'test');
+    expect(violations.length).toBeGreaterThan(0);
+  });
+});
+
+// ─── 3. assertNotFinalized ────────────────────────────────────────────────────
+
+describe('assertNotFinalized', () => {
+  it('passes for an open (live) candle', () => {
+    assertNotFinalized(validBar({ isClosed: false }), 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('fires for a closed candle', () => {
+    assertNotFinalized(validBar({ isClosed: true }), 'test');
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0]).toContain('finalized');
+  });
+
+  it('violation message contains context and timeMs', () => {
+    assertNotFinalized(validBar({ isClosed: true, timeMs: 180_000 }), 'liveUpdate');
+    expect(violations[0]).toContain('liveUpdate');
+    expect(violations[0]).toContain('180000');
+  });
+});
+
+// ─── 4. assertOpenImmutability ────────────────────────────────────────────────
+
+describe('assertOpenImmutability', () => {
+  it('passes when open is unchanged', () => {
+    const bar = validBar({ open: 100 });
+    assertOpenImmutability(100, bar, 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('fires when open changed', () => {
+    const bar = validBar({ open: 200 });
+    assertOpenImmutability(100, bar, 'ctx');
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0]).toContain('open');
+  });
+
+  it('violation message shows previous and new open', () => {
+    const bar = validBar({ open: 200, timeMs: 120_000 });
+    assertOpenImmutability(100, bar, 'ctx');
+    expect(violations[0]).toContain('100');
+    expect(violations[0]).toContain('200');
+    expect(violations[0]).toContain('120000');
+  });
+});
+
+// ─── 5. assertNoDuplicateAppend ───────────────────────────────────────────────
+
+describe('assertNoDuplicateAppend', () => {
+  it('passes when count is unchanged', () => {
+    assertNoDuplicateAppend(5, 5, 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('fires when count increased (spurious append)', () => {
+    assertNoDuplicateAppend(5, 6, 'ctx');
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0]).toContain('same-bucket');
+  });
+});
+
+// ─── 6. assertFinalizedUnchanged ─────────────────────────────────────────────
+
+describe('assertFinalizedUnchanged', () => {
+  it('passes when the previous bar is now isClosed', () => {
+    const prev = validBar({ timeMs: 60_000, isClosed: false });
+    const current: CandleBar[] = [
+      { ...prev, isClosed: true },
+      validBar({ timeMs: 120_000, isClosed: false }),
+    ];
+    assertFinalizedUnchanged(prev, current, 'test');
+    expect(violations).toHaveLength(0);
+  });
+
+  it('fires when the previous bar is still open after a new-bucket append', () => {
+    const prev = validBar({ timeMs: 60_000, isClosed: false });
+    const current: CandleBar[] = [
+      { ...prev, isClosed: false }, // not closed — violation
+      validBar({ timeMs: 120_000, isClosed: false }),
+    ];
+    assertFinalizedUnchanged(prev, current, 'test');
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0]).toContain('isClosed');
+  });
+
+  it('passes when the bar was removed (e.g. after a merge)', () => {
+    const prev = validBar({ timeMs: 60_000 });
+    // prev is not in `current` at all — should not fire
+    assertFinalizedUnchanged(prev, [], 'test');
+    expect(violations).toHaveLength(0);
+  });
+});
+
+// ─── 7. CandleEngine integration — no spurious warnings ──────────────────────
+
+describe('CandleEngine integration — clean operation produces no violations', () => {
+  const TF = '1m';
+  const T0 = sec('2025-03-09T14:00:00Z');
+  const T1 = sec('2025-03-09T14:01:00Z');
+  const T2 = sec('2025-03-09T14:02:00Z');
+
+  it('single tick produces no invariant violations', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], TF as any);
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    expect(violations).toHaveLength(0);
+  });
+
+  it('same-bucket updates produce no violations', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], TF as any);
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 120, 85, 115));
+    engine.applyLiveUpdate(tick(T0 + 45, 100, 120, 85, 112));
+    expect(violations).toHaveLength(0);
+  });
+
+  it('new-bucket append produces no violations', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], TF as any);
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T1, 106, 120, 100, 115));
+    engine.applyLiveUpdate(tick(T2, 116, 125, 110, 120));
+    expect(violations).toHaveLength(0);
+  });
+
+  it('backfillGap produces no violations', () => {
+    const T4 = sec('2025-03-09T14:04:00Z');
+    const engine = new CandleEngine();
+    engine.initialize([tick(T0, 100, 110, 90, 105)], TF as any);
+    engine.applyLiveUpdate(tick(T4, 130, 140, 120, 135));
+    engine.backfillGap([
+      tick(T1, 106, 115, 100, 112),
+      tick(T2, 112, 118, 105, 116),
+    ]);
+    expect(violations).toHaveLength(0);
+  });
+
+  it('handleReconnect produces no violations', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      tick(T0, 100, 110, 90, 105),
+      tick(T1, 106, 112, 100, 110),
+    ], TF as any);
+    engine.handleReconnect([
+      tick(T0, 100, 115, 88, 112),
+      tick(T1, 106, 118, 96, 115),
+    ]);
+    expect(violations).toHaveLength(0);
+  });
+
+  it('weekly timeframe: calendar-aligned ticks produce no violations', () => {
+    const MONDAY = sec('2025-03-03T00:00:00Z');
+    const WEDNESDAY = sec('2025-03-05T12:00:00Z');
+    const FRIDAY = sec('2025-03-07T18:00:00Z');
+
+    const engine = new CandleEngine();
+    engine.initialize([], '1w' as any);
+
+    engine.applyLiveUpdate(tick(MONDAY, 40000, 42000, 39000, 41000));
+    // Wed and Fri are in the same 1w bucket — updates only
+    engine.applyLiveUpdate(tick(WEDNESDAY, 40000, 45000, 38000, 44000));
+    engine.applyLiveUpdate(tick(FRIDAY, 40000, 46000, 37500, 43000));
+
+    expect(violations).toHaveLength(0);
+    expect(engine.getBars().length).toBe(1); // still the same weekly candle
+  });
+
+  it('monthly timeframe: calendar-aligned ticks produce no violations', () => {
+    const MAR_01 = sec('2025-03-01T00:00:00Z');
+    const MAR_15 = sec('2025-03-15T12:00:00Z');
+    const APR_01 = sec('2025-04-01T00:00:00Z');
+
+    const engine = new CandleEngine();
+    engine.initialize([], '1M' as any);
+
+    engine.applyLiveUpdate(tick(MAR_01, 40000, 42000, 39000, 41000));
+    engine.applyLiveUpdate(tick(MAR_15, 40000, 45000, 38000, 44000)); // same month
+    engine.applyLiveUpdate(tick(APR_01, 44000, 46000, 43000, 45000));// new month
+
+    expect(violations).toHaveLength(0);
+    expect(engine.getBars().length).toBe(2); // March + April
+  });
+});
+
+// ─── 8. barDivergenceCheck ────────────────────────────────────────────────────
+
+describe('compareSources — identical sources', () => {
+  const BARS: SourceBars = {
+    source: 'provider',
+    bars: [
+      { time: 1_000_000, open: 100, high: 110, low: 90,  close: 105 },
+      { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+      { time: 1_000_120, open: 112, high: 120, low: 108, close: 118 },
+    ],
+  };
+  const DB_BARS: SourceBars = { source: 'database', bars: BARS.bars };
+
+  it('returns diverged=false when both sources are identical', () => {
+    const report = compareSources(BARS, DB_BARS, '1m', 'BTC', 1_000_000, 1_000_180);
+    expect(report.diverged).toBe(false);
+    expect(report.totalMismatches).toBe(0);
+    expect(report.firstMismatch).toBeNull();
+  });
+
+  it('correct source counts', () => {
+    const report = compareSources(BARS, DB_BARS, '1m', 'BTC', 1_000_000, 1_000_180);
+    expect(report.sourceACount).toBe(3);
+    expect(report.sourceBCount).toBe(3);
+  });
+});
+
+describe('compareSources — OHLC divergence', () => {
+  it('detects first high mismatch and reports field name', () => {
+    const provider: SourceBars = {
+      source: 'provider',
+      bars: [
+        { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+        { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+      ],
+    };
+    const db: SourceBars = {
+      source: 'database',
+      bars: [
+        { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+        { time: 1_000_060, open: 105, high: 999, low: 100, close: 112 }, // high differs
+      ],
+    };
+    const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+    expect(report.diverged).toBe(true);
+    expect(report.firstMismatch).not.toBeNull();
+    expect(report.firstMismatch!.time).toBe(1_000_060);
+    expect(report.firstMismatch!.differences.some(d => d.field === 'high')).toBe(true);
+  });
+
+  it('detects missing bar in one source', () => {
+    const provider: SourceBars = {
+      source: 'provider',
+      bars: [
+        { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+        { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+      ],
+    };
+    const db: SourceBars = {
+      source: 'database',
+      bars: [
+        { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+        // 1_000_060 is missing
+      ],
+    };
+    const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+    expect(report.diverged).toBe(true);
+    expect(report.firstMismatch!.time).toBe(1_000_060);
+    expect(report.firstMismatch!.notes.some(n => n.includes('missing'))).toBe(true);
+  });
+
+  it('reports first mismatch in time order even if later mismatches exist', () => {
+    const provider: SourceBars = {
+      source: 'provider',
+      bars: [
+        { time: 1_000_000, open: 100, high: 200, low: 90, close: 150 }, // high differs
+        { time: 1_000_060, open: 105, high: 300, low: 100, close: 200 }, // high also differs
+      ],
+    };
+    const db: SourceBars = {
+      source: 'database',
+      bars: [
+        { time: 1_000_000, open: 100, high: 110, low: 90, close: 150 },
+        { time: 1_000_060, open: 105, high: 115, low: 100, close: 200 },
+      ],
+    };
+    const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+    expect(report.firstMismatch!.time).toBe(1_000_000); // oldest first
+    expect(report.totalMismatches).toBe(2);
+  });
+});
+
+describe('checkAllSources', () => {
+  it('produces N*(N-1)/2 pairwise reports', () => {
+    const sources = [
+      { source: 'provider' as const, bars: [] },
+      { source: 'database' as const, bars: [] },
+      { source: 'sdk'      as const, bars: [] },
+    ];
+    const reports = checkAllSources(sources, 'BTC', '1h', 0, 100_000);
+    expect(reports.length).toBe(3); // C(3,2) = 3
+  });
+});
+
+describe('formatReport', () => {
+  it('includes IDENTICAL when no divergence', () => {
+    const bars: SourceBars = {
+      source: 'provider',
+      bars: [{ time: 1_000_000, open: 100, high: 110, low: 90, close: 105 }],
+    };
+    const report = compareSources(bars, { source: 'database', bars: bars.bars }, '1m', 'BTC', 1_000_000, 1_000_060);
+    const text = formatReport(report);
+    expect(text).toContain('IDENTICAL');
+  });
+
+  it('includes DIVERGED and mismatch details when sources differ', () => {
+    const provider: SourceBars = {
+      source: 'provider',
+      bars: [{ time: 1_000_000, open: 100, high: 999, low: 90, close: 105 }],
+    };
+    const db: SourceBars = {
+      source: 'database',
+      bars: [{ time: 1_000_000, open: 100, high: 110, low: 90, close: 105 }],
+    };
+    const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_060);
+    const text = formatReport(report);
+    expect(text).toContain('DIVERGED');
+    expect(text).toContain('1000000'); // time
+    expect(text).toContain('high');
+  });
+});

package/src/__tests__/public-api-surface.ts

@@ -0,0 +1,76 @@
+/**
+ * SDK Public API Surface — type-level integration test.
+ *
+ * Verifies that @forgecharts/sdk exports the required public symbols.
+ * Compiled by `tsc --noEmit` (no runtime execution needed).
+ *
+ * The three primary integration points are:
+ *   1. createChart()   — vanilla JS/TS DOM-based embed
+ *   2. ChartCanvas     — React component embed
+ *   3. ChartWorkspace  — full-workspace React embed
+ */
+
+import type {
+  // Primary chart config
+  ChartConfig,
+  ChartInterval,
+  ChartTheme,
+  ChartEventMap,
+  ChartLayout,
+  // Datafeed contract
+  IDatafeed,
+  HistoricalBarsResult,
+  SymbolInfo,
+  // Trading
+  ChartOrder,
+  ChartPosition,
+  ExecutionFill,
+  // Capabilities
+  ChartCapabilities,
+  // Indicator
+  IndicatorConfig,
+  IndicatorType,
+} from '@forgecharts/sdk';
+
+import {
+  createChart,
+  TChart,
+  DatafeedConnector,
+  TradingOverlayStore,
+  LicenseManager,
+  CandleEngine,
+  ReferenceAPI,
+  // Capability helpers
+  getCapabilities,
+  isManagedMode,
+  isUnmanagedMode,
+} from '@forgecharts/sdk';
+
+// ── Engine internals must NOT be importable from the root path ────────────
+// The following would correctly fail to compile if enabled:
+// import { Chart } from '@forgecharts/sdk'; // ❌ moved to ./internal
+// import { PixiChart } from '@forgecharts/sdk'; // ❌ moved to ./internal
+
+// ── Engine internals ARE importable from the internal path ────────────────
+import { Chart, PixiChart, InteractionManager } from '@forgecharts/sdk/internal';
+
+// ── Type assertions ───────────────────────────────────────────────────────
+
+// createChart must be callable and TChart must be exported
+void createChart;
+void TChart;
+
+// DatafeedConnector, TradingOverlayStore, and capability helpers must be exported
+void DatafeedConnector;
+void TradingOverlayStore;
+void getCapabilities;
+
+// Internal engine: Chart, PixiChart, InteractionManager must still be available
+void Chart;
+void PixiChart;
+void InteractionManager;
+void LicenseManager;
+void CandleEngine;
+void ReferenceAPI;
+void isManagedMode;
+void isUnmanagedMode;