@meri-imperiumi/signalk-passage-briefing 0.2.0

package/tests/statustilesexamples.test.js

@@ -0,0 +1,86 @@
+/**
+ * Tests for the Status Tiles example-set provider (work doc #13):
+ * the bundled JSON parses and has the expected shape, the provider
+ * lists while running and empties when stopped, and it is
+ * read-only.
+ *
+ * @file statustilesexamples.test.js
+ */
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const {
+  registerStatusTileExamples,
+  EXAMPLES,
+} = require("../plugin/statustilesexamples.js");
+
+test("bundled example set parses and references published paths", () => {
+  assert.equal(EXAMPLES.name, "Passage Briefing examples");
+  const set = EXAMPLES.sets[0];
+  assert.equal(set.id, "passage-comfort");
+  const tile = set.tiles[0];
+  assert.equal(tile.size, "1x1");
+  const types = tile.checks.map((c) => c.type);
+  assert.deepEqual(types, ["stateMatch", "boolean"]);
+  const paths = tile.checks.map((c) => c.path);
+  assert.ok(paths.includes("navigation.briefing.comfort"));
+  assert.ok(paths.includes("navigation.briefing.stale"));
+  const comfortCheck = tile.checks[0];
+  assert.deepEqual(
+    comfortCheck.map.map((m) => m.value),
+    ["champagne", "easy", "coffee", "rough", "sick"],
+  );
+  const footerPaths = tile.footer.map((f) => f.path);
+  assert.ok(footerPaths.includes("navigation.briefing.ageHours"));
+  assert.ok(footerPaths.includes("navigation.briefing.route"));
+});
+
+test("provider lists while running, empties when stopped, read-only", async () => {
+  const registered = [];
+  const errors = [];
+  const app = {
+    registerResourceProvider: (provider) => registered.push(provider),
+    error: (m) => errors.push(m),
+  };
+  const teardown = registerStatusTileExamples(app, {
+    id: "signalk-passage-briefing",
+  });
+  assert.equal(registered.length, 1);
+  const provider = registered[0];
+  assert.equal(provider.type, "statusTileExamples");
+
+  const listed = await provider.methods.listResources();
+  assert.ok(listed["signalk-passage-briefing"]);
+  const resource = await provider.methods.getResource(
+    "signalk-passage-briefing",
+  );
+  assert.equal(resource.sets[0].id, "passage-comfort");
+  await assert.rejects(() => provider.methods.getResource("some-other-plugin"));
+  await assert.rejects(() => provider.methods.setResource("x", {}));
+  await assert.rejects(() => provider.methods.deleteResource("x"));
+
+  teardown();
+  assert.deepEqual(await provider.methods.listResources(), {});
+  await assert.rejects(() =>
+    provider.methods.getResource("signalk-passage-briefing"),
+  );
+});
+
+test("re-start reuses the registration instead of stacking", async () => {
+  const registered = [];
+  const app = {
+    registerResourceProvider: (p) => registered.push(p),
+    error: () => {},
+  };
+  const teardown = registerStatusTileExamples(app, {
+    id: "signalk-passage-briefing",
+  });
+  const teardown2 = registerStatusTileExamples(app, {
+    id: "signalk-passage-briefing",
+  });
+  assert.equal(registered.length, 1); // Idempotent
+  teardown();
+  teardown2();
+  assert.deepEqual(await registered[0].methods.listResources(), {});
+});

package/tests/synoptic-source.test.js

@@ -0,0 +1,195 @@
+/**
+ * Unit tests for the synoptic surface-analysis chart source (work
+ * doc #11): zone+hour URL selection with 12Z boundaries, static
+ * filenames, missing zones, TIFF→PNG conversion via the vendored
+ * UTIF, cache/skip behaviour, and offline reads.
+ *
+ * @file synoptic-source.test.js
+ */
+
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const { mkdtempSync, existsSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const UTIF = require("../public/vendor/utif/UTIF.js");
+const {
+  chartUrlForZone,
+  chartsForZones,
+  loadSynoptic,
+  loadSynopticMap,
+  refreshSynoptics,
+} = require("../plugin/synoptic-source.js");
+const { convertChart, detectFormat } = require("../plugin/raster-convert.js");
+
+function dataDir() {
+  return mkdtempSync(join(tmpdir(), "synoptic-"));
+}
+
+/** Builds a tiny uncompressed RGBA TIFF as agencies would ship. */
+function fixtureTif(width = 8, height = 4) {
+  const rgba = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    const value = i % 3 === 0 ? 0 : 255; // black/white line art
+    rgba[i * 4] = value;
+    rgba[i * 4 + 1] = value;
+    rgba[i * 4 + 2] = value;
+    rgba[i * 4 + 3] = 255;
+  }
+  return Buffer.from(UTIF.encodeImage(rgba, width, height));
+}
+
+describe("chart URL selection", () => {
+  const map = loadSynopticMap();
+
+  test("hour boundaries pick 00Z before noon, 12Z from noon", () => {
+    const map2 = {
+      14: {
+        name: "x",
+        source: "t",
+        hours: {
+          "00": "http://a/00.TIF",
+          12: "http://a/12.TIF",
+        },
+      },
+    };
+    const before = chartUrlForZone(map2, 14, new Date("2026-09-27T11:59:00Z"));
+    const at = chartUrlForZone(map2, 14, new Date("2026-09-27T12:00:00Z"));
+    assert.equal(before.url ?? before.urls[0], "http://a/00.TIF");
+    assert.equal(before.validHour, "00");
+    assert.equal(at.urls[0], "http://a/12.TIF");
+    assert.equal(at.validHour, "12");
+  });
+
+  test("zone 14 ladder: MetService first, NOAA then BoM fallbacks", () => {
+    const at = chartUrlForZone(map, 14, new Date("2026-09-27T12:00:00Z"));
+    assert.equal(at.validHour, "12");
+    assert.deepEqual(
+      at.urls.map((u) => new URL(u).host),
+      ["alerts.metservice.com", "tgftp.nws.noaa.gov", "tgftp.nws.noaa.gov"],
+    );
+    assert.match(at.urls[1], /PPBA89\.TIF$/);
+  });
+
+  test("static filenames skip the hour logic", () => {
+    const pick = chartUrlForZone(map, 11, new Date("2026-09-27T18:00:00Z"));
+    assert.match(pick.urls[0], /PJAA99\.TIF$/);
+    assert.equal(pick.validHour, "static");
+  });
+
+  test("missing hour variant falls back, missing zones resolve-and-skip", () => {
+    const map2 = {
+      3: { name: "x", source: "t", hours: { "00": "http://a/00.TIF" } },
+    };
+    // From 12Z with no 12Z variant: falls back to the 00Z chart
+    const pick = chartUrlForZone(map2, 3, new Date("2026-09-27T18:00:00Z"));
+    assert.deepEqual(pick.urls, ["http://a/00.TIF"]);
+    assert.equal(pick.validHour, "00");
+    assert.equal(chartUrlForZone(map2, 14), null); // not in this map
+    assert.deepEqual(chartsForZones(map2, [3, 14]), [
+      { zone: 3, urls: ["http://a/00.TIF"], validHour: "00" },
+    ]);
+  });
+});
+
+describe("conversion and cache", () => {
+  test("tiff converts to grayscale png; gif passes through as-is", () => {
+    const png = convertChart(fixtureTif());
+    assert.equal(detectFormat(png.bytes), "png");
+    assert.equal(png.converted, true);
+    assert.equal(png.width, 8);
+    assert.equal(png.height, 4);
+
+    // BoM difacs GIF: cached as-is, size read from the header
+    const gif = Buffer.concat([
+      Buffer.from("GIF89a"),
+      Buffer.from([12, 0, 6, 0]), // 12x6 logical screen
+      Buffer.from("trailer bytes would follow"),
+    ]);
+    const passthrough = convertChart(gif);
+    assert.equal(passthrough.format, "gif");
+    assert.equal(passthrough.converted, false);
+    assert.equal(passthrough.width, 12);
+    assert.equal(passthrough.height, 6);
+    assert.equal(passthrough.bytes, gif);
+
+    assert.equal(convertChart(Buffer.from("NOT AN IMAGE")), null);
+  });
+
+  test("refresh fetches, caches, then skips the same chart", async () => {
+    const dir = dataDir();
+    let fetches = 0;
+    const fetchImpl = async () => {
+      fetches++;
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => fixtureTif(16, 8),
+      };
+    };
+    const zones = [11]; // static URL entry
+    const first = await refreshSynoptics({
+      dataDir: dir,
+      zones,
+      fetchImpl,
+    });
+    assert.deepEqual(first.fetched, [11]);
+    assert.equal(fetches, 1);
+    assert.ok(existsSync(join(dir, "synoptic-11.png")));
+    const cached = await loadSynoptic(dir, 11);
+    assert.equal(cached.format, "png");
+    assert.equal(detectFormat(cached.bytes), "png");
+    assert.ok(cached.fetchedAt);
+
+    const second = await refreshSynoptics({
+      dataDir: dir,
+      zones,
+      fetchImpl,
+    });
+    assert.deepEqual(second.skipped, [11]);
+    assert.equal(fetches, 1);
+  });
+
+  test("failed charts are isolated and the cache survives", async () => {
+    const dir = dataDir();
+    const fetchImpl = async (url) => {
+      // Zone 1: both hour variants serve; zone 11: 404s
+      if (/PPV[AE]89/.test(String(url))) {
+        return { ok: true, status: 200, arrayBuffer: async () => fixtureTif() };
+      }
+      return { ok: false, status: 404, statusText: "Not Found" };
+    };
+    const result = await refreshSynoptics({
+      dataDir: dir,
+      zones: [1, 11], // 11 fails
+      fetchImpl,
+    });
+    assert.deepEqual(result.fetched, [1]);
+    assert.deepEqual(
+      result.failed.map((f) => f.zone),
+      [11],
+    );
+    assert.match(result.failed[0].error, /404/);
+    assert.ok(await loadSynoptic(dir, 1));
+    assert.equal(await loadSynoptic(dir, 11), null);
+  });
+});
+
+test("converted chart output is a well-formed grayscale PNG", () => {
+  const { bytes: png } = convertChart(fixtureTif(6, 3));
+  assert.deepEqual(
+    [...png.subarray(0, 8)],
+    [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+  );
+  assert.equal(png.readUInt32BE(16), 6); // width
+  assert.equal(png.readUInt32BE(20), 3); // height
+  assert.equal(png[25], 0); // bit depth 8
+  assert.equal(png[26], 0); // color type: grayscale
+  // IDAT chunk follows the IHDR: inflate it and check the filtered
+  // raw size (height * (filter byte + width))
+  const dataLen = png.readUInt32BE(33);
+  assert.equal(png.toString("ascii", 37, 41), "IDAT");
+  const raw = require("node:zlib").inflateSync(png.subarray(41, 41 + dataLen));
+  assert.equal(raw.length, 3 * (6 + 1));
+});

package/tests/tack-gybe.test.js

@@ -0,0 +1,211 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+
+const tgPromise = import("../public/tack-gybe.js");
+
+const approx = (actual, expected, epsilon = 1e-6) =>
+  assert.ok(
+    Math.abs(actual - expected) < epsilon,
+    `expected ${actual} ≈ ${expected} (±${epsilon})`,
+  );
+
+/**
+ * Builds one hourly simulation row for the detection tests.
+ *
+ * @param {object} overrides
+ * @returns {object}
+ */
+function row(overrides = {}) {
+  return {
+    hoursFromNow: 1,
+    timestamp: "2026-06-21T01:00:00.000Z",
+    lat: 0.5,
+    lon: 0,
+    distanceFromStartNm: 5,
+    headingDeg: 0,
+    twdDeg: 45,
+    twsKnots: 12,
+    sogKnots: 5,
+    sailState: "MAIN_FULL",
+    motoring: false,
+    night: false,
+    ...overrides,
+  };
+}
+
+describe("tack & gybe detection", () => {
+  test("wrap180 normalizes to (-180, 180]", async () => {
+    const { wrap180 } = await tgPromise;
+    assert.equal(wrap180(0), 0);
+    assert.equal(wrap180(180), 180);
+    assert.equal(wrap180(-180), 180);
+    assert.equal(wrap180(190), -170);
+    assert.equal(wrap180(-190), 170);
+    assert.equal(wrap180(540), 180);
+  });
+
+  test("tackSide: positive TWA is starboard", async () => {
+    const { tackSide } = await tgPromise;
+    assert.equal(tackSide(30), "starboard");
+    assert.equal(tackSide(-30), "port");
+    assert.equal(tackSide(170), "starboard");
+  });
+
+  test("upwind beat: single tack with interpolated crossing", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({
+        hoursFromNow: 1,
+        timestamp: "2026-06-21T01:00:00.000Z",
+        headingDeg: 30,
+        twdDeg: 60,
+        lat: 0.5,
+        distanceFromStartNm: 5,
+      }),
+      row({
+        hoursFromNow: 2,
+        timestamp: "2026-06-21T02:00:00.000Z",
+        headingDeg: 90,
+        twdDeg: 60,
+        lat: 0.4,
+        distanceFromStartNm: 10,
+      }),
+    ]);
+    assert.equal(events.length, 1);
+    const [e] = events;
+    assert.equal(e.maneuver, "tack");
+    assert.equal(e.fromTack, "starboard");
+    assert.equal(e.toTack, "port");
+    assert.equal(e.sailState, "MAIN_FULL@port");
+    // TWA +30 → −30: crossing at the segment midpoint
+    assert.equal(e.hoursFromNow, 1.5);
+    assert.equal(e.timestamp, "2026-06-21T01:30:00.000Z");
+    assert.equal(e.eta, e.timestamp);
+    approx(e.lat, 0.45);
+    assert.equal(e.distanceFromStartNm, 7.5);
+    assert.equal(e.twsAtManeuver, 12);
+  });
+
+  test("downwind run: gybe classified across ±180", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 0, twdDeg: 170 }),
+      row({ headingDeg: 0, twdDeg: -170 }),
+    ]);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].maneuver, "gybe");
+    assert.equal(events[0].fromTack, "starboard");
+    assert.equal(events[0].toTack, "port");
+  });
+
+  test("TWA wrap-around near ±180 still detects the gybe", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ hoursFromNow: 1, headingDeg: 0, twdDeg: 175 }),
+      row({ hoursFromNow: 2, headingDeg: 0, twdDeg: -176 }),
+    ]);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].maneuver, "gybe");
+    // The path from +175 to −176 wraps through +180: ΔTWA =
+    // wrap(−351) = +9°, crossing at f = (180 − 175)/9 = 5/9 ≈ 0.556,
+    // rounded to the sim row's 0.1 h precision
+    approx(events[0].hoursFromNow, 1.6, 0.001);
+  });
+
+  test("motoring legs are excluded", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 30, twdDeg: 60 }),
+      row({ headingDeg: 90, twdDeg: 60, motoring: true }),
+      row({ headingDeg: 150, twdDeg: 60 }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("drift-mode hours (SOG 0) are excluded", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 30, twdDeg: 60 }),
+      row({ headingDeg: 90, twdDeg: 60, sogKnots: 0 }),
+      row({ headingDeg: 150, twdDeg: 60 }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("wobble below the 25° margin is rejected", async () => {
+    const { detectManeuvers, MIN_TWA_MARGIN_DEG } = await tgPromise;
+    assert.equal(MIN_TWA_MARGIN_DEG, 25);
+    const events = detectManeuvers([
+      row({ headingDeg: 40, twdDeg: 60 }),
+      row({ headingDeg: 80, twdDeg: 60 }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("gradual veer through a low-wind-angle hour still lands the tack", async () => {
+    const { detectManeuvers } = await tgPromise;
+    // TWA +45 → +5 → −45: the mid hour dips below the margin while
+    // the wind swings through the eye, but the established side flips
+    const events = detectManeuvers([
+      row({ hoursFromNow: 1, headingDeg: 0, twdDeg: 45 }),
+      row({ hoursFromNow: 2, headingDeg: 0, twdDeg: 5 }),
+      row({ hoursFromNow: 3, headingDeg: 0, twdDeg: -45 }),
+    ]);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].maneuver, "tack");
+    assert.equal(events[0].fromTack, "starboard");
+    assert.equal(events[0].toTack, "port");
+  });
+
+  test("wobble that never flips the established side stays silent", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ hoursFromNow: 1, headingDeg: 0, twdDeg: 45 }),
+      row({ hoursFromNow: 2, headingDeg: 0, twdDeg: 10 }),
+      row({ hoursFromNow: 3, headingDeg: 0, twdDeg: 45 }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("mixed beam reach (one side < 90, one > 90) is not classified", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 30, twdDeg: 60 }),
+      row({ headingDeg: 170, twdDeg: 60 }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("multi-maneuver route: tack then gybe, time-sorted", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ hoursFromNow: 1, headingDeg: 30, twdDeg: 60 }),
+      row({ hoursFromNow: 2, headingDeg: 90, twdDeg: 60 }),
+      row({ hoursFromNow: 3, headingDeg: 90, twdDeg: -95 }),
+      row({ hoursFromNow: 4, headingDeg: 90, twdDeg: -60 }),
+    ]);
+    assert.equal(events.length, 2);
+    assert.equal(events[0].maneuver, "tack");
+    assert.equal(events[1].maneuver, "gybe");
+    assert.ok(events[0].hoursFromNow <= events[1].hoursFromNow);
+  });
+
+  test("no wind data yields no events", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 30, twdDeg: null }),
+      row({ headingDeg: 90, twdDeg: null }),
+    ]);
+    assert.equal(events.length, 0);
+  });
+
+  test("no sail state: event still carries the tack label", async () => {
+    const { detectManeuvers } = await tgPromise;
+    const events = detectManeuvers([
+      row({ headingDeg: 30, twdDeg: 60, sailState: null }),
+      row({ headingDeg: 90, twdDeg: 60, sailState: null }),
+    ]);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].sailState, "@port");
+  });
+});