@ingissa/navcore-simulator 1.0.4 → 1.0.7

package/src/core/__tests__/SimulatorEngine.test.ts

@@ -0,0 +1,317 @@
+/**
+ * SimulatorEngine unit tests
+ * Uses vi.useFakeTimers() to control setInterval without real waiting.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { SimulatorEngine } from '../SimulatorEngine';
+import { NoiseEngine } from '../NoiseEngine';
+import { ScenarioInjector } from '../../scenarios/ScenarioInjector';
+import type { SimPosition, Coordinate } from '../types';
+
+// 10-point straight eastward route
+const ROUTE: Coordinate[] = Array.from({ length: 10 }, (_, i) => [i * 0.001, 0.0]);
+
+function makeEngine(overrides?: Partial<ConstructorParameters<typeof SimulatorEngine>[0]>) {
+  return new SimulatorEngine({
+    routeGeometry: ROUTE,
+    speedKmh: 50,
+    speedMultiplier: 1,
+    noiseProfile: NoiseEngine.NONE, // deterministic for tests
+    loop: false,
+    ...overrides,
+  });
+}
+
+describe('SimulatorEngine', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // ── Construction ────────────────────────────────────────────────────────────
+  describe('construction', () => {
+    it('throws with fewer than 2 geometry points', () => {
+      expect(() => makeEngine({ routeGeometry: [[0, 0]] })).toThrow();
+    });
+
+    it('starts in idle state', () => {
+      const engine = makeEngine();
+      expect(engine.state).toBe('idle');
+      expect(engine.position).toBeNull();
+      engine.destroy();
+    });
+
+    it('autoStart=true calls start automatically', () => {
+      const engine = makeEngine({ autoStart: true });
+      expect(engine.state).toBe('running');
+      engine.destroy();
+    });
+  });
+
+  // ── Start / Stop ────────────────────────────────────────────────────────────
+  describe('start / stop', () => {
+    it('transitions idle → running', () => {
+      const engine = makeEngine();
+      engine.start();
+      expect(engine.state).toBe('running');
+      engine.destroy();
+    });
+
+    it('stop transitions to idle and clears position', () => {
+      const engine = makeEngine();
+      engine.start();
+      vi.advanceTimersByTime(1000);
+      engine.stop();
+      expect(engine.state).toBe('idle');
+      expect(engine.position).toBeNull();
+      engine.destroy();
+    });
+
+    it('double start does not throw', () => {
+      const engine = makeEngine();
+      engine.start();
+      engine.start();
+      expect(engine.state).toBe('running');
+      engine.destroy();
+    });
+  });
+
+  // ── Callbacks ───────────────────────────────────────────────────────────────
+  describe('onPositionUpdate', () => {
+    it('fires on each tick and emits standard LocationObject coords', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({ onPositionUpdate: (p) => positions.push(p) });
+      engine.start();
+      vi.advanceTimersByTime(3000); // 3 ticks at 1× speed
+      expect(positions.length).toBe(3);
+      const p = positions[0]!;
+      expect(p.coords).toBeDefined();
+      expect(typeof p.coords.latitude).toBe('number');
+      expect(typeof p.coords.longitude).toBe('number');
+      expect(typeof p.coords.heading).toBe('number');
+      expect(typeof p.coords.speed).toBe('number');
+      expect(typeof p.coords.accuracy).toBe('number');
+      expect(p.location).toBeDefined();
+      expect(p.location?.coords.latitude).toBe(p.coords.latitude);
+      expect(p.location?.timestamp).toBe(p.timestamp);
+      engine.destroy();
+    });
+
+    it('receives correct bearing for eastward route', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({ onPositionUpdate: (p) => positions.push(p) });
+      engine.start();
+      vi.advanceTimersByTime(1000);
+      const bearing = positions[0]!.bearing;
+      expect(bearing).toBeGreaterThan(85);
+      expect(bearing).toBeLessThan(95);
+      engine.destroy();
+    });
+
+    it('never throws even if callback throws', () => {
+      const engine = makeEngine({
+        onPositionUpdate: () => { throw new Error('boom'); },
+      });
+      engine.start();
+      expect(() => vi.advanceTimersByTime(1000)).not.toThrow();
+      engine.destroy();
+    });
+  });
+
+  describe('onRouteComplete', () => {
+    it('fires when route is finished', () => {
+      const done = vi.fn();
+      const engine = makeEngine({ onRouteComplete: done });
+      engine.start();
+      // ROUTE has 10 points → 9 advances to complete
+      vi.advanceTimersByTime(10000);
+      expect(done).toHaveBeenCalledOnce();
+      expect(engine.state).toBe('complete');
+      engine.destroy();
+    });
+  });
+
+  // ── Pause / Resume ──────────────────────────────────────────────────────────
+  describe('pause / resume', () => {
+    it('pause freezes position, resume continues', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({ onPositionUpdate: (p) => positions.push(p) });
+      engine.start();
+      vi.advanceTimersByTime(2000);
+      const countBeforePause = positions.length;
+
+      engine.pause();
+      expect(engine.state).toBe('paused');
+
+      vi.advanceTimersByTime(3000); // nothing should fire
+      expect(positions.length).toBe(countBeforePause);
+
+      engine.resume();
+      vi.advanceTimersByTime(2000);
+      expect(positions.length).toBeGreaterThan(countBeforePause);
+      engine.destroy();
+    });
+  });
+
+  // ── Speed multiplier ────────────────────────────────────────────────────────
+  describe('setSpeed', () => {
+    it('4× speed fires 4 ticks per second', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({
+        speedMultiplier: 4,
+        onPositionUpdate: (p) => positions.push(p),
+      });
+      engine.start();
+      vi.advanceTimersByTime(1000); // 1000ms / (1000/4) = 4 ticks
+      expect(positions.length).toBe(4);
+      engine.destroy();
+    });
+
+    it('setSpeed changes tick rate mid-simulation', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({ onPositionUpdate: (p) => positions.push(p) });
+      engine.start();
+      vi.advanceTimersByTime(1000); // 1 tick at 1×
+
+      engine.setSpeed(4);
+      vi.advanceTimersByTime(1000); // 4 ticks at 4×
+      // Total should be 1 + 4 = 5 (approximately)
+      expect(positions.length).toBeGreaterThanOrEqual(5);
+      engine.destroy();
+    });
+  });
+
+  // ── Seek ────────────────────────────────────────────────────────────────────
+  describe('seek', () => {
+    it('jumps to specified index', () => {
+      const engine = makeEngine();
+      engine.seek(5);
+      expect(engine.progress).toBeCloseTo(5 / 9, 2);
+      engine.destroy();
+    });
+
+    it('recalculates bearing correctly after seek', () => {
+      const engine = makeEngine();
+      engine.seek(3);
+      const pos = engine.position;
+      expect(pos).not.toBeNull();
+      // Eastward route → bearing ~90°
+      expect(pos!.bearing).toBeGreaterThan(85);
+      expect(pos!.bearing).toBeLessThan(95);
+      engine.destroy();
+    });
+  });
+
+  // ── Progress ────────────────────────────────────────────────────────────────
+  describe('progress', () => {
+    it('is 0 at start', () => {
+      const engine = makeEngine();
+      expect(engine.progress).toBe(0);
+      engine.destroy();
+    });
+
+    it('is 1 when route completes', () => {
+      const engine = makeEngine();
+      engine.start();
+      vi.advanceTimersByTime(10000);
+      expect(engine.progress).toBe(1);
+      engine.destroy();
+    });
+  });
+
+  // ── Scenarios ───────────────────────────────────────────────────────────────
+  describe('scenarios', () => {
+    it('addScenario fires at correct index', () => {
+      const onScenarioStart = vi.fn();
+      const engine = makeEngine({ onScenarioStart });
+      engine.addScenario(ScenarioInjector.gpsBlackout(3, 1000));
+      engine.start();
+      vi.advanceTimersByTime(4000); // 4 ticks, scenario at index 3
+      expect(onScenarioStart).toHaveBeenCalledOnce();
+      expect(onScenarioStart.mock.calls[0]![0].type).toBe('GPS_BLACKOUT');
+      engine.destroy();
+    });
+
+    it('clearScenarios prevents firing', () => {
+      const onScenarioStart = vi.fn();
+      const engine = makeEngine({ onScenarioStart });
+      engine.addScenario(ScenarioInjector.gpsBlackout(2, 1000));
+      engine.clearScenarios();
+      engine.start();
+      vi.advanceTimersByTime(5000);
+      expect(onScenarioStart).not.toHaveBeenCalled();
+      engine.destroy();
+    });
+  });
+
+  // ── Loop ────────────────────────────────────────────────────────────────────
+  describe('loop', () => {
+    it('restarts from beginning when loop=true', () => {
+      const complete = vi.fn();
+      const engine = makeEngine({ loop: true, onRouteComplete: complete });
+      engine.start();
+      vi.advanceTimersByTime(10000); // completes once
+      expect(complete).toHaveBeenCalledOnce();
+      expect(engine.state).toBe('running'); // still running
+      engine.destroy();
+    });
+  });
+
+  // ── Recording ───────────────────────────────────────────────────────────────
+  describe('recording', () => {
+    it('startRecording / stopRecording captures positions', () => {
+      const engine = makeEngine();
+      engine.startRecording();
+      engine.start();
+      vi.advanceTimersByTime(4000);
+      const session = engine.stopRecording();
+
+      expect(session.positions.length).toBeGreaterThan(0);
+      expect(session.stats.scenariosFired).toBe(0);
+      expect(session.startedAt).toBeTruthy();
+      expect(session.endedAt).toBeTruthy();
+      engine.destroy();
+    });
+
+    it('records scenario fires', () => {
+      const engine = makeEngine();
+      engine.addScenario(ScenarioInjector.gpsBlackout(2, 1000));
+      engine.startRecording();
+      engine.start();
+      vi.advanceTimersByTime(5000);
+      const session = engine.stopRecording();
+
+      expect(session.scenarios.length).toBe(1);
+      expect(session.scenarios[0]!.scenario.type).toBe('GPS_BLACKOUT');
+      expect(session.stats.scenariosFired).toBe(1);
+      engine.destroy();
+    });
+
+    it('stats.distanceTravelledM is positive', () => {
+      const engine = makeEngine();
+      engine.startRecording();
+      engine.start();
+      vi.advanceTimersByTime(5000);
+      const session = engine.stopRecording();
+      expect(session.stats.distanceTravelledM).toBeGreaterThan(0);
+      engine.destroy();
+    });
+  });
+
+  // ── Destroy ─────────────────────────────────────────────────────────────────
+  describe('destroy', () => {
+    it('clears position and stops firing', () => {
+      const positions: SimPosition[] = [];
+      const engine = makeEngine({ onPositionUpdate: (p) => positions.push(p) });
+      engine.start();
+      vi.advanceTimersByTime(2000);
+      engine.destroy();
+      const countAtDestroy = positions.length;
+      vi.advanceTimersByTime(5000); // timer should be dead
+      expect(positions.length).toBe(countAtDestroy);
+    });
+  });
+});

package/src/core/types.ts

@@ -0,0 +1,191 @@
+/**
+ * @navcore/simulator — Core Types
+ *
+ * These types are the foundation of the entire simulator package.
+ * All other modules build on top of these definitions.
+ */
+
+/** [longitude, latitude] — Mapbox/GeoJSON order */
+export type Coordinate = [number, number];
+
+// ─── LocationObject Alignment ──────────────────────────────────────────────────
+
+/**
+ * Standard coords conforming to expo-location LocationObject['coords']
+ * and @react-native-community/geolocation.
+ */
+export interface SimLocationCoords {
+  latitude: number;
+  longitude: number;
+  altitude: number | null;
+  accuracy: number | null;
+  altitudeAccuracy: number | null;
+  heading: number | null;
+  speed: number | null;
+}
+
+/**
+ * Standard LocationObject conforming to expo-location.
+ */
+export interface SimLocationObject {
+  coords: SimLocationCoords;
+  timestamp: number;
+}
+
+// ─── SimPosition ──────────────────────────────────────────────────────────────
+
+/**
+ * A single simulated GPS position, emitted by SimulatorEngine on every tick.
+ * Shape includes standard LocationObject coords for drop-in Expo/React Native usage.
+ */
+export interface SimPosition {
+  /** [longitude, latitude] */
+  coord: Coordinate;
+  /** Heading in degrees 0–360 */
+  bearing: number;
+  /** Speed in metres per second */
+  speed: number;
+  /** Simulated GPS accuracy radius in metres */
+  accuracy: number;
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+  /**
+   * Standard LocationObject coords conforming to expo-location & React Native geolocation.
+   */
+  coords: SimLocationCoords;
+  /**
+   * Full standard LocationObject conforming to expo-location.
+   */
+  location?: SimLocationObject;
+  /** Optional debug metadata */
+  metadata?: {
+    /** Which geometry segment the vehicle is currently on */
+    segmentIndex: number;
+    /** Total metres travelled from route start */
+    distanceTravelled: number;
+    /** Whether noise was applied on this tick */
+    isNoisy: boolean;
+    /** Name of the active scenario, if any */
+    scenarioActive?: string;
+  };
+}
+
+// ─── NoiseProfile ─────────────────────────────────────────────────────────────
+
+/**
+ * Noise model applied to simulated GPS coordinates each tick.
+ */
+export interface NoiseProfile {
+  /** Noise type */
+  type: 'NONE' | 'GAUSSIAN' | 'URBAN' | 'TUNNEL' | 'CUSTOM';
+  /** Standard deviation of the Gaussian noise in metres (default: 12) */
+  stdDevM: number;
+  /**
+   * Optional seed for deterministic noise generation.
+   * Same seed + same route = identical output (critical for regression tests).
+   */
+  seed?: number;
+  /**
+   * For CUSTOM type: return [lngOffset, latOffset] for each tick.
+   * @param index - current geometry segment index
+   */
+  customFn?: (index: number) => [number, number];
+}
+
+// ─── Scenario ─────────────────────────────────────────────────────────────────
+
+/**
+ * A scenario that is injected at a specific geometry index during simulation.
+ */
+export interface Scenario {
+  /** Unique name for this scenario */
+  name: string;
+  /** Geometry index at which the scenario fires */
+  triggerIndex: number;
+  /** Scenario type */
+  type:
+    | 'GPS_BLACKOUT'      // dead reckoning stress test
+    | 'WRONG_SIDE_ROAD'   // parallel road resolver stress test
+    | 'UTURN'             // U-turn protection stress test
+    | 'SPEED_SPIKE'       // sudden speed change
+    | 'ACCURACY_DROP'     // GPS accuracy degrades
+    | 'CUSTOM';
+  /** How long the scenario lasts in milliseconds */
+  durationMs?: number;
+  /** Scenario-specific configuration */
+  params?: Record<string, unknown>;
+}
+
+// ─── SimulatorConfig ──────────────────────────────────────────────────────────
+
+/**
+ * Full configuration object passed to SimulatorEngine.
+ * All callback fields are optional — the engine is fully usable without them
+ * (useful for CI/headless tests).
+ */
+export interface SimulatorConfig {
+  // ── Route ────────────────────────────────────────────────────────────────
+  /** The route geometry to simulate along */
+  routeGeometry: Coordinate[];
+
+  // ── Speed ────────────────────────────────────────────────────────────────
+  /** Simulated vehicle speed in km/h (default: 50) */
+  speedKmh?: number;
+  /** Playback speed multiplier: 1×, 2×, 4×, 8× (default: 1) */
+  speedMultiplier?: 1 | 2 | 4 | 8;
+
+  // ── Noise ────────────────────────────────────────────────────────────────
+  /** Noise model applied to each position (default: NoiseEngine.STANDARD) */
+  noiseProfile?: NoiseProfile;
+
+  // ── Playback ─────────────────────────────────────────────────────────────
+  /** Whether to restart from the beginning when the route ends (default: false) */
+  loop?: boolean;
+  /** Start simulation from this geometry index (default: 0) */
+  startIndex?: number;
+  /** If true, start() is called automatically after construction (default: false) */
+  autoStart?: boolean;
+
+  // ── Callbacks ─────────────────────────────────────────────────────────────
+  /** Called on every tick with the new simulated position */
+  onPositionUpdate?: (pos: SimPosition) => void;
+  /** Called when the route end is reached (or loop restarts) */
+  onRouteComplete?: () => void;
+  /** Called when a scenario begins */
+  onScenarioStart?: (scenario: Scenario) => void;
+  /** Called when a scenario ends */
+  onScenarioEnd?: (scenario: Scenario) => void;
+}
+
+// ─── SimSession ───────────────────────────────────────────────────────────────
+
+/**
+ * A complete recorded simulation session.
+ * Produced by SimulatorEngine.stopRecording() / SessionRecorder.stop().
+ */
+export interface SimSession {
+  /** UUID v4 session identifier */
+  id: string;
+  /** ISO 8601 start timestamp */
+  startedAt: string;
+  /** ISO 8601 end timestamp */
+  endedAt: string;
+  /** The route geometry used */
+  route: Coordinate[];
+  /** All SimPositions emitted during the session */
+  positions: SimPosition[];
+  /** Scenarios that fired, with their tick timestamps */
+  scenarios: Array<{
+    scenario: Scenario;
+    /** Unix ms when the scenario fired */
+    firedAt: number;
+  }>;
+  /** Aggregate statistics for this session */
+  stats: {
+    durationMs: number;
+    distanceTravelledM: number;
+    avgSpeedKmh: number;
+    noiseSamplesAdded: number;
+    scenariosFired: number;
+  };
+}

package/src/fleet/FleetSimulator.ts

@@ -0,0 +1,162 @@
+/**
+ * FleetSimulator — Phase 2 skeleton.
+ *
+ * Spawns N SimulatorEngine instances with optional per-vehicle profile
+ * overrides, runs them in parallel, and produces aggregate reports.
+ *
+ * @experimental — fully typed but not tested in Phase 1.
+ * Activate in a future iteration once SimulatorEngine is validated in CI.
+ */
+
+import { SimulatorEngine } from '../core/SimulatorEngine';
+import type { SimulatorConfig, SimSession } from '../core/types';
+
+export interface VehicleProfile extends Partial<SimulatorConfig> {
+  /** Human-readable label for this vehicle profile */
+  label?: string;
+}
+
+export interface FleetReport {
+  vehicles: Array<{
+    id: number;
+    label: string;
+    session: SimSession;
+    profile: VehicleProfile;
+  }>;
+  comparison: {
+    /** Average stats keyed by vehicle label */
+    avgScoreByProfile: Record<string, number>;
+    /** Per-segment noise deviation across all vehicles (heatmap data) */
+    deviationsBySegment: number[];
+  };
+}
+
+export class FleetSimulator {
+  private readonly engines: SimulatorEngine[];
+  private readonly profiles: VehicleProfile[];
+  private readonly baseConfig: Omit<SimulatorConfig, 'onPositionUpdate'>;
+
+  private constructor(
+    engines: SimulatorEngine[],
+    profiles: VehicleProfile[],
+    baseConfig: Omit<SimulatorConfig, 'onPositionUpdate'>,
+  ) {
+    this.engines = engines;
+    this.profiles = profiles;
+    this.baseConfig = baseConfig;
+  }
+
+  /**
+   * Spawn N SimulatorEngine instances.
+   *
+   * @param count - number of vehicles
+   * @param config - base config (onPositionUpdate is per-vehicle, excluded here)
+   */
+  static spawn(
+    count: number,
+    config: Omit<SimulatorConfig, 'onPositionUpdate'> & {
+      profiles?: VehicleProfile[];
+    },
+  ): FleetSimulator {
+    const { profiles = [], ...baseConfig } = config;
+
+    const engines: SimulatorEngine[] = [];
+    const resolvedProfiles: VehicleProfile[] = [];
+
+    for (let i = 0; i < count; i++) {
+      const profile = profiles[i] ?? {};
+      resolvedProfiles.push(profile);
+
+      const engine = new SimulatorEngine({
+        ...baseConfig,
+        ...profile,
+        onPositionUpdate: undefined,
+      });
+
+      engines.push(engine);
+    }
+
+    return new FleetSimulator(engines, resolvedProfiles, baseConfig);
+  }
+
+  /** Start all engines simultaneously */
+  start(): void {
+    for (const engine of this.engines) {
+      engine.startRecording();
+      engine.start();
+    }
+  }
+
+  /** Stop all engines */
+  stop(): void {
+    for (const engine of this.engines) {
+      engine.stop();
+    }
+  }
+
+  /**
+   * Get the engine at the given index.
+   * Use this for per-vehicle control (seek, setSpeed, addScenario, etc.)
+   */
+  vehicle(index: number): SimulatorEngine {
+    const engine = this.engines[index];
+    if (!engine) throw new Error(`FleetSimulator: no vehicle at index ${index}`);
+    return engine;
+  }
+
+  /**
+   * Stop all engines, collect sessions, and return an aggregate report.
+   */
+  report(): FleetReport {
+    const vehicleReports = this.engines.map((engine, i) => {
+      const session = engine.stopRecording();
+      const profile = this.profiles[i] ?? {};
+      return {
+        id: i,
+        label: profile.label ?? `vehicle-${i}`,
+        session,
+        profile,
+      };
+    });
+
+    // Compute average speed per profile label
+    const avgScoreByProfile: Record<string, number> = {};
+    for (const v of vehicleReports) {
+      const key = v.label;
+      const existing = avgScoreByProfile[key];
+      if (existing === undefined) {
+        avgScoreByProfile[key] = v.session.stats.avgSpeedKmh;
+      } else {
+        avgScoreByProfile[key] = (existing + v.session.stats.avgSpeedKmh) / 2;
+      }
+    }
+
+    // Per-segment noise deviation: average accuracy across all vehicles per segment
+    const segmentCount = this.baseConfig.routeGeometry.length;
+    const deviationsBySegment: number[] = new Array<number>(segmentCount).fill(0);
+    for (const v of vehicleReports) {
+      for (const pos of v.session.positions) {
+        const segIdx = pos.metadata?.segmentIndex ?? 0;
+        if (segIdx < segmentCount) {
+          deviationsBySegment[segIdx] = (deviationsBySegment[segIdx] ?? 0) + pos.accuracy;
+        }
+      }
+    }
+    // Average
+    for (let i = 0; i < deviationsBySegment.length; i++) {
+      deviationsBySegment[i] = (deviationsBySegment[i] ?? 0) / Math.max(1, vehicleReports.length);
+    }
+
+    return {
+      vehicles: vehicleReports,
+      comparison: { avgScoreByProfile, deviationsBySegment },
+    };
+  }
+
+  /** Destroy all engines and clean up */
+  destroy(): void {
+    for (const engine of this.engines) {
+      engine.destroy();
+    }
+  }
+}