@meri-imperiumi/signalk-passage-briefing 0.2.0

package/tests/celestial-source.test.js

@@ -0,0 +1,265 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+
+const cs = require("../plugin/celestial-source.js");
+
+/**
+ * SWPC planetary K-index forecast fixture (verified live shape:
+ * array of {time_tag, kp, observed} rows at 3-hour steps).
+ */
+function kpFixture() {
+  return [
+    { time_tag: "2026-09-27T00:00:00", kp: 2.33, observed: "observed" },
+    { time_tag: "2026-09-27T09:00:00", kp: 4.0, observed: "observed" },
+    { time_tag: "2026-09-27T12:00:00", kp: 6.33, observed: "predicted" },
+    { time_tag: "2026-09-27T15:00:00", kp: 5.67, observed: "predicted" },
+    { time_tag: "2026-09-27T18:00:00", kp: 3.0, observed: "predicted" },
+    { time_tag: "2026-09-30T00:00:00", kp: 8.0, observed: "predicted" },
+  ];
+}
+
+/** SBDB query fixture (documented {fields, rows} response shape). */
+function sbdbFixture() {
+  return {
+    fields: ["full_name", "M1", "K1", "r", "dist"],
+    rows: [
+      // m = 4.0 + 5·log10(0.5) + 10·log10(1.2) ≈ 5.12 → naked eye
+      ["C/2026 A1 (Fixture)", 4.0, 10, 1.2, 0.5],
+      // m ≈ 9.75 → too faint
+      ["C/2025 B2 (Faint)", 7.0, 10, 2.0, 1.5],
+      // Missing numbers → skipped
+      ["C/2024 C3 (Broken)", null, null, null, null],
+    ],
+  };
+}
+
+test("parseComets falls back to perihelion estimate without r/dist", () => {
+  // The live SBDB endpoint rejects r/dist for sb-kind=c: with q only,
+  // the parse screens on perihelion brightness and flags the estimate
+  const comets = cs.parseComets({
+    fields: ["full_name", "M1", "K1", "q", "tp_cal"],
+    rows: [
+      // mPeri = 4.0 + 15·log10(0.9) ≈ 3.31 → naked eye at perihelion
+      ["C/2026 D1 (Peri)", 4.0, 10, 0.9, "2026-Nov-03.1"],
+      // mPeri = 9 + 15·log10(3) ≈ 16.2 → never naked eye
+      ["C/2020 E4 (Faint)", 9.0, 10, 3.0, "2020-Aug-01.5"],
+    ],
+  });
+  assert.equal(comets.length, 1);
+  assert.equal(comets[0].name, "C/2026 D1 (Peri)");
+  assert.equal(comets[0].estimate, "perihelion");
+  assert.equal(comets[0].perihelion, "2026-Nov-03.1");
+});
+
+test("fetchComets negotiates invalid fields away and retries", async () => {
+  const attempted = [];
+  const responses = [
+    // 1st: full list rejected on r
+    {
+      ok: false,
+      status: 400,
+      text: async () =>
+        JSON.stringify({ message: "invalid field specified: 'r'" }),
+    },
+    // 2nd: dist rejected too
+    {
+      ok: false,
+      status: 400,
+      text: async () =>
+        JSON.stringify({ message: "invalid field specified: 'dist'" }),
+    },
+    // 3rd: accepted
+    {
+      ok: true,
+      status: 200,
+      json: async () => ({ fields: ["ok"], rows: [] }),
+    },
+  ];
+  const comets = await cs.fetchComets({
+    fetchImpl: async (url) => {
+      attempted.push(String(url));
+      return responses[attempted.length - 1];
+    },
+    timeoutMs: 500,
+  });
+  assert.deepEqual(comets, { fields: ["ok"], rows: [] });
+  assert.equal(attempted.length, 3);
+  assert.match(attempted[0], /fields=full_name,M1,K1,r,dist,q,tp_cal/);
+  assert.match(attempted[1], /fields=full_name,M1,K1,dist,q,tp_cal/);
+  assert.match(attempted[2], /fields=full_name,M1,K1,q,tp_cal/);
+});
+
+test("fetchComets returns null when the endpoint never answers", async () => {
+  const comets = await cs.fetchComets({
+    fetchImpl: async () => ({ ok: false, status: 503, text: async () => "" }),
+    timeoutMs: 500,
+  });
+  assert.equal(comets, null);
+});
+
+const NIGHT = (_date, _lat, _lon) => true;
+const DAY = (_date, _lat, _lon) => false;
+
+describe("celestial & space weather (doc #3 Phase 1)", () => {
+  test("aurora magnetic-latitude threshold tightens with Kp", () => {
+    assert.equal(cs.auroraMagLatThreshold(5), 65);
+    assert.equal(cs.auroraMagLatThreshold(8), 50);
+    assert.equal(cs.auroraMagLatThreshold(9), 45);
+    assert.equal(cs.auroraMagLatThreshold(12), 40); // Clamped
+  });
+
+  test("magnetic latitude: known hemisphere sanity", () => {
+    // Opua NZ: geographic -35.3 → dipole about -37 (coarse)
+    const opua = cs.magneticLatitudeDeg(-35.3, 174.3);
+    assert.ok(opua < -30 && opua > -45, `Opua mag lat ${opua}`);
+    // Tromsø, Norway: high northern magnetic latitude
+    const tromso = cs.magneticLatitudeDeg(69.6, 18.9);
+    assert.ok(tromso > 55, `Tromsø mag lat ${tromso}`);
+  });
+
+  test("parseKpForecast keeps the forward window only", () => {
+    const from = new Date("2026-09-27T06:00:00Z");
+    const entries = cs.parseKpForecast(kpFixture(), { from, hours: 24 });
+    assert.deepEqual(
+      entries.map((e) => e.timestamp),
+      [
+        "2026-09-27T09:00:00.000Z",
+        "2026-09-27T12:00:00.000Z",
+        "2026-09-27T15:00:00.000Z",
+        "2026-09-27T18:00:00.000Z",
+      ],
+    );
+    // The Kp 8 entry three days out is outside the window
+    assert.ok(entries.every((e) => e.kp < 8));
+    assert.equal(entries[1].predicted, true);
+    assert.deepEqual(cs.parseKpForecast(null), []);
+  });
+
+  test("comet apparent magnitude follows m = M1 + 5log Δ + K1 log r", () => {
+    const m = cs.cometApparentMagnitude({ M1: 4, K1: 10, r: 1.2, delta: 0.5 });
+    approx(m, 4 + 5 * Math.log10(0.5) + 10 * Math.log10(1.2));
+    assert.equal(cs.cometApparentMagnitude({ M1: 4 }), null);
+    assert.equal(
+      cs.cometApparentMagnitude({ M1: 4, K1: 10, r: 0, delta: 1 }),
+      null,
+    );
+  });
+
+  test("parseComets keeps only naked-eye comets, brightest first", () => {
+    const comets = cs.parseComets(sbdbFixture());
+    assert.equal(comets.length, 1);
+    assert.equal(comets[0].name, "C/2026 A1 (Fixture)");
+    assert.ok(comets[0].magnitude < 6);
+    // Broken row numbers are skipped, not fatal
+    assert.equal(cs.parseComets({ fields: [], rows: [] }).length, 0);
+    assert.equal(cs.parseComets(null).length, 0);
+  });
+
+  test("buildSpaceEvents gates aurora by Kp, magnetic latitude and night", async () => {
+    const kpEntries = cs.parseKpForecast(kpFixture(), {
+      from: new Date("2026-09-27T06:00:00Z"),
+      hours: 24,
+    });
+    const comets = cs.parseComets(sbdbFixture());
+
+    // Tonga (-21): far too equatorial for Kp 6
+    const tonga = await cs.buildSpaceEvents({
+      kpEntries,
+      comets,
+      lat: -21.1,
+      lon: -175.2,
+      isNightFn: NIGHT,
+    });
+    assert.ok(tonga.every((e) => e.kind !== "aurora"));
+    assert.equal(tonga.length, 1); // The comet
+    assert.equal(tonga[0].kind, "comet");
+    assert.equal(tonga[0].tactical, false);
+
+    // Subantarctic south (−54): inside the Kp 6.33 → 55°? No: 68 mag
+    // lat threshold at 6.33... use a Kp 9 window instead
+    const storm = [
+      { timestamp: "2026-09-27T12:00:00.000Z", kp: 9, predicted: true },
+    ];
+    const farSouth = await cs.buildSpaceEvents({
+      kpEntries: storm,
+      comets: [],
+      lat: -50,
+      lon: 170,
+      isNightFn: NIGHT,
+    });
+    assert.equal(farSouth.length, 1);
+    assert.equal(farSouth[0].kind, "aurora");
+    assert.equal(farSouth[0].tactical, true);
+    assert.match(farSouth[0].description, /Look south/);
+
+    // Daylight at the peak kills the aurora alert
+    const daytime = await cs.buildSpaceEvents({
+      kpEntries: storm,
+      comets: [],
+      lat: -50,
+      lon: 170,
+      isNightFn: DAY,
+    });
+    assert.equal(daytime.length, 0);
+
+    // Northern hemisphere looks north
+    const north = await cs.buildSpaceEvents({
+      kpEntries: storm,
+      comets: [],
+      lat: 55,
+      lon: 20,
+      isNightFn: NIGHT,
+    });
+    assert.match(north[0].description, /Look north/);
+
+    // Sub-storm Kp: nothing even at high latitude
+    const quiet = await cs.buildSpaceEvents({
+      kpEntries: [{ timestamp: "2026-09-27T12:00:00.000Z", kp: 4 }],
+      comets: [],
+      lat: -50,
+      lon: 170,
+      isNightFn: NIGHT,
+    });
+    assert.equal(quiet.length, 0);
+  });
+
+  test("fetchSpaceEvents degrades per source and on total failure", async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Only SWPC answers: aurora gating still runs (comets skipped)
+      globalThis.fetch = async (url) => {
+        if (String(url).includes("swpc.noaa.gov")) {
+          return { ok: true, json: async () => kpFixture() };
+        }
+        throw new Error("network down");
+      };
+      const events = await cs.fetchSpaceEvents({
+        lat: -50,
+        lon: 170,
+        now: new Date("2026-09-27T06:00:00Z"),
+        isNightFn: NIGHT,
+      });
+      assert.ok(events.every((e) => ["aurora", "comet"].includes(e.kind)));
+
+      // Everything fails: empty list, never throws
+      globalThis.fetch = async () => {
+        throw new Error("network down");
+      };
+      const none = await cs.fetchSpaceEvents({
+        lat: -50,
+        lon: 170,
+        now: new Date("2026-09-27T06:00:00Z"),
+      });
+      assert.deepEqual(none, []);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+function approx(actual, expected, epsilon = 1e-9) {
+  assert.ok(
+    Math.abs(actual - expected) < epsilon,
+    `expected ${actual} ≈ ${expected} (±${epsilon})`,
+  );
+}

package/tests/fetch-engine.test.js

@@ -0,0 +1,297 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const { mkdtempSync, existsSync, readdirSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const { forecastFixture, mockOpenMeteo } = require("./openmeteo-mock.js");
+
+const {
+  KEEP_SNAPSHOTS,
+  sampleRoutePoints,
+  routeDistanceNm,
+  dewpointC,
+  kIndex,
+  normalizeLocations,
+  fetchWeatherAlongTrack,
+  savePayload,
+  loadPayload,
+  listCachedRoutes,
+} = require("../plugin/fetch-engine.js");
+
+const approx = (actual, expected, epsilon = 1e-6) =>
+  assert.ok(
+    Math.abs(actual - expected) < epsilon,
+    `expected ${actual} ≈ ${expected} (±${epsilon})`,
+  );
+
+describe("route sampling", () => {
+  test("divides a 90 nm meridian leg into even ≤30 nm steps", () => {
+    const points = sampleRoutePoints(
+      [
+        [0, 0],
+        [0, 1.5],
+      ],
+      30,
+    );
+    // 90.06 nm total → 4 steps of 22.5 nm
+    assert.equal(points.length, 5);
+    approx(points[0].distanceFromStartNm, 0);
+    approx(points[1].distanceFromStartNm, 22.5, 0.1);
+    approx(points[2].distanceFromStartNm, 45, 0.1);
+    approx(
+      points[4].distanceFromStartNm,
+      routeDistanceNm([
+        [0, 0],
+        [0, 1.5],
+      ]),
+      0.1,
+    );
+    approx(points[2].lat, 0.75, 0.01);
+    assert.equal(points[0].lon, 0);
+  });
+
+  test("keeps spacing uniform across multi-leg routes", () => {
+    // 60 nm + 60 nm legs
+    const points = sampleRoutePoints(
+      [
+        [0, 0],
+        [0, 1],
+        [1, 1],
+      ],
+      30,
+    );
+    const distances = points.map((p) => p.distanceFromStartNm);
+    assert.equal(distances[0], 0);
+    for (let i = 1; i < distances.length; i++) {
+      approx(distances[i] - distances[i - 1], distances[1], 0.3);
+    }
+    approx(
+      distances[distances.length - 1],
+      routeDistanceNm([
+        [0, 0],
+        [0, 1],
+        [1, 1],
+      ]),
+      0.1,
+    );
+  });
+
+  test("single-point route and empty input", () => {
+    assert.equal(sampleRoutePoints([[5, 55]]).length, 1);
+    assert.deepEqual(sampleRoutePoints([]), []);
+  });
+
+  test("route distance", () => {
+    approx(
+      routeDistanceNm([
+        [0, 0],
+        [0, 1.5],
+      ]),
+      90,
+      0.1,
+    );
+  });
+});
+
+describe("k-index", () => {
+  test("dew point via Magnus", () => {
+    approx(dewpointC(15, 80), 11.57, 0.01);
+    approx(dewpointC(5, 60), -2.13, 0.01);
+  });
+
+  test("K = (T850−T500) + Td850 − (T700−Td700)", () => {
+    const k = kIndex({ t850: 15, t700: 5, t500: -10, rh850: 80, rh700: 60 });
+    approx(k, 29.44, 0.01);
+  });
+
+  test("null on missing inputs", () => {
+    assert.equal(
+      kIndex({ t850: 15, t700: 5, t500: null, rh850: 80, rh700: 60 }),
+      null,
+    );
+  });
+});
+
+describe("normalizeLocations", () => {
+  test("single object, array and null responses", () => {
+    assert.deepEqual(normalizeLocations({ a: 1 }, 2), [{ a: 1 }, null]);
+    assert.deepEqual(normalizeLocations([{ a: 1 }, { a: 2 }], 2), [
+      { a: 1 },
+      { a: 2 },
+    ]);
+    assert.deepEqual(normalizeLocations(null, 1), [null]);
+  });
+});
+
+const WAYPOINTS = sampleRoutePoints([
+  [0, 0],
+  [0, 1.5],
+]);
+
+describe("fetchWeatherAlongTrack", () => {
+  test("builds the SPEC §3.1 payload with unit conversions", async () => {
+    const payload = await fetchWeatherAlongTrack({
+      waypoints: WAYPOINTS,
+      fetchImpl: mockOpenMeteo(),
+    });
+    assert.equal(payload.metadata.source, "api");
+    assert.deepEqual(payload.metadata.models, [
+      "forecast:best_match",
+      "marine:ncep_gfswave025",
+      "marine:smoc_currents",
+    ]);
+    assert.equal(payload.waypoints.length, 5);
+    const [step] = payload.waypoints[0].forecasts;
+    // First step is the current hour (fixture times are relative)
+    const firstTimestamp = new Date(
+      Date.now() - (Date.now() % 3600000),
+    ).toISOString();
+    assert.equal(step.timestamp, firstTimestamp);
+    assert.deepEqual(step.surface, {
+      tws: 12,
+      twd: 45,
+      mslp: 1013,
+      gust: 18,
+    });
+    assert.deepEqual(step.marine, {
+      hsCombined: 1.2,
+      tpCombined: 7,
+      dirCombined: 160,
+      hsSwell: 0.9,
+      tpSwell: 9,
+      dirSwell: 150,
+      hsWindSea: 0.5,
+      tpWindSea: 4,
+      dirWindSea: 170,
+    });
+    assert.equal(step.upperAir.cape, 200);
+    assert.equal(step.upperAir.kIndex, 29.4);
+    assert.equal(step.upperAir.rh700, 60);
+    assert.equal(step.upperAir.wind850kts, 20);
+    // 1.852 km/h → 1 kn
+    assert.equal(step.current.drift, 1);
+    assert.equal(step.current.set, 45);
+    assert.equal(
+      payload.waypoints[4].distanceFromStartNm,
+      routeDistanceNm([
+        [0, 0],
+        [0, 1.5],
+      ]),
+    );
+  });
+
+  test("aligns multi-location responses in request order", async () => {
+    const waypoints = sampleRoutePoints([
+      [0, 0],
+      [0, 0.5],
+    ]); // 30 nm → 3 points
+    const multiForecast = [
+      forecastFixture(),
+      forecastFixture(),
+      forecastFixture(),
+    ];
+    const payload = await fetchWeatherAlongTrack({
+      waypoints,
+      fetchImpl: mockOpenMeteo({ forecast: multiForecast }),
+    });
+    assert.equal(payload.waypoints.length, 3);
+    assert.equal(payload.waypoints[0].forecasts[0].surface.tws, 12);
+    assert.equal(payload.waypoints[2].forecasts[0].surface.tws, 12);
+  });
+
+  test("marine failure degrades gracefully", async () => {
+    const payload = await fetchWeatherAlongTrack({
+      waypoints: WAYPOINTS,
+      fetchImpl: mockOpenMeteo({ throw: "ncep_gfswave025" }),
+    });
+    assert.deepEqual(payload.metadata.models, [
+      "forecast:best_match",
+      "marine:smoc_currents",
+    ]);
+    assert.equal(payload.waypoints[0].forecasts[0].marine.hsCombined, null);
+    assert.equal(payload.waypoints[0].forecasts[0].surface.tws, 12);
+  });
+
+  test("forecast failure fails the fetch", async () => {
+    await assert.rejects(
+      fetchWeatherAlongTrack({
+        waypoints: WAYPOINTS,
+        fetchImpl: mockOpenMeteo({ throw: "/v1/forecast" }),
+      }),
+      /returned 500|network down/,
+    );
+  });
+
+  test("retries a 500 before succeeding", async () => {
+    let attempts = 0;
+    const flaky = async (url) => {
+      const u = String(url);
+      if (u.includes("/v1/forecast") && attempts++ === 0) {
+        return { ok: false, status: 500, statusText: "boom" };
+      }
+      return mockOpenMeteo()(url);
+    };
+    const payload = await fetchWeatherAlongTrack({
+      waypoints: WAYPOINTS,
+      fetchImpl: flaky,
+    });
+    assert.equal(payload.metadata.source, "api");
+  });
+
+  test("empty waypoints rejected", async () => {
+    await assert.rejects(
+      fetchWeatherAlongTrack({ waypoints: [], fetchImpl: mockOpenMeteo() }),
+      /No waypoints/,
+    );
+  });
+});
+
+describe("payload cache", () => {
+  test("save, load round-trip and snapshot pruning", async () => {
+    const dataDir = mkdtempSync(join(tmpdir(), "passage-cache-"));
+    const makePayload = (fetchedAt) => ({
+      metadata: { fetchedAt, source: "api", models: ["forecast:best_match"] },
+      waypoints: [],
+    });
+
+    for (let i = 0; i < KEEP_SNAPSHOTS + 3; i++) {
+      await savePayload(
+        dataDir,
+        "route 1",
+        makePayload(`2026-09-27T${String(i).padStart(2, "0")}:00:00Z`),
+      );
+    }
+
+    const latest = await loadPayload(dataDir, "route 1");
+    assert.equal(
+      latest.payload.metadata.fetchedAt,
+      `2026-09-27T${String(KEEP_SNAPSHOTS + 2).padStart(2, "0")}:00:00Z`,
+    );
+    assert.equal(
+      latest.cachedAt,
+      `2026-09-27T${String(KEEP_SNAPSHOTS + 2).padStart(2, "0")}:00:00Z`,
+    );
+
+    const snapshots = readdirSync(join(dataDir, "weather")).filter(
+      (f) => f.startsWith("route%201-") && f.endsWith(".json"),
+    );
+    assert.equal(snapshots.length, KEEP_SNAPSHOTS);
+    // Newest snapshot carries the same content as latest
+    assert.ok(existsSync(join(dataDir, "weather", "latest-route%201.json")));
+
+    const cached = await listCachedRoutes(dataDir);
+    assert.deepEqual(cached, [
+      {
+        routeId: "route 1",
+        cachedAt: `2026-09-27T${String(KEEP_SNAPSHOTS + 2).padStart(2, "0")}:00:00Z`,
+      },
+    ]);
+  });
+
+  test("missing cache reads null", async () => {
+    const dataDir = mkdtempSync(join(tmpdir(), "passage-cache-"));
+    assert.equal(await loadPayload(dataDir, "nope"), null);
+    assert.deepEqual(await listCachedRoutes(dataDir), []);
+  });
+});