@meri-imperiumi/signalk-passage-briefing 0.2.0

package/tests/brief-ext.test.js

@@ -0,0 +1,194 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const {
+  buildManifest,
+  registerPlotterExtension,
+  staticAssetHandler,
+} = require("../plugin/brief-ext.js");
+const { tileModel, briefAge } = require("../public/brief-ext-model.js");
+
+const PLUGIN_ID = "signalk-passage-briefing";
+const ASSET_BASE = `/plotterext/${PLUGIN_ID}`;
+const PUBLIC_DIR = path.join(__dirname, "..", "public");
+
+describe("plotter-extension manifest & provider (doc #8)", () => {
+  test("manifest targets plotter extension API v1", () => {
+    const m = buildManifest(ASSET_BASE, "1.2.3");
+    assert.equal(m.apiVersion, "1");
+    assert.equal(m.name, "Passage Briefing");
+    assert.equal(m.version, "1.2.3");
+    assert.ok(m.description.length > 0);
+  });
+
+  test("manifest requires the widget grid and the SK relay", () => {
+    const m = buildManifest(ASSET_BASE, "1.2.3");
+    assert.ok(m.requires.includes("widgets"));
+    assert.ok(m.requires.includes("signalk.stream"));
+    for (const cap of m.optional ?? []) {
+      assert.ok(!m.requires.includes(cap));
+    }
+  });
+
+  test("manifest contributes a valid 1x1 iframe widget", () => {
+    const m = buildManifest(ASSET_BASE, "1.2.3");
+    assert.equal(m.widgets.length, 1);
+    const [w] = m.widgets;
+    assert.equal(w.id, "passage-brief-tile");
+    assert.equal(w.type, "iframe");
+    assert.equal(w.size, "1x1");
+    assert.equal(w.lifecycle, "whileEnabled");
+    assert.ok(w.url.startsWith(`${ASSET_BASE}/`));
+  });
+
+  test("provider serves the manifest and empties on teardown", async () => {
+    const providers = [];
+    const mounts = [];
+    const app = {
+      registerResourceProvider: (p) => providers.push(p),
+      use: (prefix, handler) => mounts.push({ prefix, handler }),
+    };
+    const teardown = registerPlotterExtension(app, { id: PLUGIN_ID });
+    assert.equal(providers.length, 1);
+    assert.equal(providers[0].type, "plotterExtensions");
+    assert.equal(mounts[0].prefix, ASSET_BASE);
+
+    const manifest = await providers[0].methods.getResource(PLUGIN_ID);
+    assert.equal(manifest.name, "Passage Briefing");
+    const listing = await providers[0].methods.listResources();
+    assert.deepEqual(Object.keys(listing), [PLUGIN_ID]);
+
+    // Read-only
+    await assert.rejects(
+      () => providers[0].methods.setResource(PLUGIN_ID, {}),
+      /read-only/,
+    );
+
+    teardown();
+    assert.deepEqual(
+      await providers[0].methods.listResources(),
+      {},
+      "provider empty after teardown",
+    );
+    await assert.rejects(() => providers[0].methods.getResource(PLUGIN_ID));
+  });
+
+  test("static handler serves known assets with traversal guard", () => {
+    const handler = staticAssetHandler(PUBLIC_DIR, ASSET_BASE);
+    const next = () => {
+      throw new Error("should have been handled");
+    };
+
+    const serve = (urlPath) =>
+      new Promise((resolve) => {
+        const chunks = [];
+        const res = {
+          statusCode: 0,
+          headers: {},
+          setHeader(k, v) {
+            this.headers[k] = v;
+          },
+          end(data) {
+            chunks.push(data);
+            resolve({
+              status: this.statusCode,
+              type: this.headers["Content-Type"],
+              body: Buffer.concat(chunks),
+            });
+          },
+        };
+        handler({ path: urlPath }, res, next);
+      });
+
+    const fallthrough = (urlPath) =>
+      new Promise((resolve) => {
+        const res = {
+          statusCode: 0,
+          setHeader() {},
+          end() {},
+        };
+        handler({ path: urlPath }, res, () => resolve(true));
+        // If neither end nor next fired within a tick, resolve false
+        setTimeout(() => resolve(false), 50);
+      });
+
+    return (async () => {
+      const widget = await serve(`${ASSET_BASE}/brief-ext-widget.html`);
+      assert.equal(widget.status, 200);
+      assert.match(widget.type, /text\/html/);
+      assert.ok(widget.body.includes("brief-ext-widget"));
+
+      // Traversal attempt falls through, never escapes the root
+      assert.ok(
+        await fallthrough(`${ASSET_BASE}/../plugin/index.js`),
+        "traversal attempt falls through",
+      );
+
+      // Unknown file falls through
+      assert.ok(await fallthrough(`${ASSET_BASE}/nope.js`));
+    })();
+  });
+});
+
+describe("brief tile model (doc #8)", () => {
+  const NOW = new Date("2026-09-27T12:00:00Z");
+
+  test("no compiled brief renders muted with no badge", () => {
+    const model = tileModel(
+      { generatedAt: null, route: null, hasNew: null },
+      NOW,
+    );
+    assert.equal(model.severity, "muted");
+    assert.equal(model.badge, false);
+    assert.equal(model.title, "No brief");
+    assert.equal(briefAge(null, NOW), "");
+  });
+
+  test("available brief shows route name and age", () => {
+    const model = tileModel({
+      generatedAt: "2026-09-27T09:00:00Z",
+      route: "Tonga to Opua",
+      hasNew: false,
+      now: NOW,
+    });
+    assert.equal(model.severity, "ok");
+    assert.equal(model.badge, false);
+    assert.equal(model.title, "Tonga to Opua");
+    assert.equal(model.detail, "3 h old");
+  });
+
+  test("new brief flags the badge until acknowledged", () => {
+    const model = tileModel({
+      generatedAt: "2026-09-27T11:45:00Z",
+      route: "",
+      hasNew: true,
+      now: NOW,
+    });
+    assert.equal(model.severity, "new");
+    assert.equal(model.badge, true);
+    // Here mode: empty route falls back to the generic title
+    assert.equal(model.title, "Passage brief");
+    assert.equal(model.detail, "15 m old");
+  });
+
+  test("age buckets minutes, hours and days", () => {
+    assert.equal(briefAge("2026-09-27T11:48:00Z", NOW), "12 m old");
+    assert.equal(briefAge("2026-09-27T06:00:00Z", NOW), "6 h old");
+    assert.equal(briefAge("2026-09-25T12:00:00Z", NOW), "2 d old");
+  });
+});
+
+// The static-handler test asserts against a real file; make sure the
+// asset it needs actually shipped.
+assert.ok(
+  fs.existsSync(path.join(PUBLIC_DIR, "brief-ext-widget.html")),
+  "widget HTML exists in public/",
+);
+assert.ok(
+  fs.existsSync(
+    path.join(PUBLIC_DIR, "vendor", "plotterext-bus", "extension.js"),
+  ),
+  "vendored bus client exists",
+);

package/tests/bulletin-engine.test.js

@@ -0,0 +1,361 @@
+/**
+ * Unit tests for the NAVAREA/NAVTEX filtering engine (work doc #4)
+ * and the internet bulletin source: boilerplate stripping, NAVTEX
+ * subject filtering, GMDSS segmentation, geographic extraction with
+ * antimeridian handling, the track discard rule, and cache/gating.
+ *
+ * @file bulletin-engine.test.js
+ */
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { mkdtempSync, writeFileSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const {
+  filterBulletin,
+  navtexSubject,
+  parseCardinalBounds,
+  parseCoordinateChain,
+  segmentBlocks,
+  shouldRetainSubject,
+  stripBoilerplate,
+  bboxIntersectsTrack,
+  ringContains,
+  ukhoBlocksFromWarnings,
+} = require("../plugin/bulletin-engine.js");
+const {
+  loadBulletinCache,
+  refreshBulletins,
+  saveBulletinCache,
+} = require("../plugin/bulletin-source.js");
+
+const approx = (actual, expected, epsilon = 1e-6) =>
+  assert.ok(
+    Math.abs(actual - expected) < epsilon,
+    `expected ${actual} ≈ ${expected} (±${epsilon})`,
+  );
+
+/** A realistic NAVAREA XIV gale warning, South Pacific (doc #4). */
+const NAVAREA_FIXTURE = `FQPS01 NFFN 011200Z AUG 26
+ZCZC GA14
+011200Z AUG 26
+NAVAREA XIV 114/26
+SOUTH PACIFIC FIJI WATERS
+GALE WARNING
+PART 1 WARNING
+DEVELOPING TROUGH T1 WITH SQUALLS AND GALES WITHIN 120NM
+EAST OF AXIS 16S 170E TO 20S 178W TO 25S 175W AT 011200Z.
+EXPECT WINDS 35 KNOTS. ROUGH SEAS WITH HEAVY SWELLS.
+PARTS 2 AND 3 SYNOPSIS AND FORECAST
+SITUATION IS MODERATE OVER REMAINDER WATERS.
+NNNN`;
+
+/** Ice report — NAVTEX subject C, must be discarded. */
+const ICE_FIXTURE = `ZCZC CC12
+030800Z AUG 26
+NAVAREA XIV 201/26
+ICE REPORTS SOUTHERN OCEAN. BERGS DRIFTING NORTH.
+NNNN`;
+
+/**
+ * Tonga → Opua track samples, GeoJSON [lon, lat] order — crosses
+ * the antimeridian.
+ */
+const TONGA_TRACK = [
+  [-175.2, -21.1],
+  [-179.0, -25.0],
+  [179.0, -30.0],
+  [174.3, -35.3],
+];
+
+// --- Tokenizer ------------------------------------------------------------
+
+test("stripBoilerplate removes ZCZC/NNNN and routing headers", () => {
+  const cleaned = stripBoilerplate(NAVAREA_FIXTURE);
+  assert.equal(cleaned.includes("FQPS01 NFFN"), false);
+  assert.equal(cleaned.includes("NNNN"), false);
+  // The NAVTEX id line stays (the subject filter reads it)
+  assert.match(cleaned, /ZCZC GA14/);
+  assert.match(cleaned, /GALE WARNING/);
+});
+
+test("NAVTEX B_2 subject filtering: C dropped, A and E retained", () => {
+  // ZCZC GA14: B_1 = G (Nadi station), B_2 = A (nav warnings)
+  assert.equal(navtexSubject(NAVAREA_FIXTURE), "A");
+  assert.equal(navtexSubject(ICE_FIXTURE), "C");
+  assert.equal(shouldRetainSubject("C"), false);
+  assert.equal(shouldRetainSubject("A"), true);
+  assert.equal(shouldRetainSubject("E"), true);
+  assert.equal(shouldRetainSubject(null), true); // Not NAVTEX: keep
+  assert.equal(filterBulletin({ rawText: ICE_FIXTURE, source: "api" }), null);
+});
+
+test("segmentBlocks anchors on PART headings and blank lines", () => {
+  const cleaned = stripBoilerplate(NAVAREA_FIXTURE);
+  const blocks = segmentBlocks(cleaned);
+  assert.ok(blocks.length >= 3, `blocks ${blocks.length}`);
+  const warning = blocks.find((b) => b.includes("PART 1 WARNING"));
+  assert.ok(warning, "warning section found");
+  assert.match(warning, /DEVELOPING TROUGH/);
+});
+
+// --- Geographic extraction ---------------------------------------------------
+
+test("coordinate chains parse with hemisphere letters and closing", () => {
+  const ring = parseCoordinateChain(
+    "EAST OF AXIS 16S 170E TO 20S 178W TO 25S 175W",
+  );
+  assert.equal(ring.length, 4); // Closed automatically
+  approx(ring[0][0], 170); // 170E
+  approx(ring[0][1], -16); // 16S
+  approx(ring[1][0], -178); // 178W — antimeridian west side
+  approx(ring[2][0], -175);
+  approx(ring[3][0], 170); // Ring closed back to start
+});
+
+test("two coordinate pairs form an open axis line", () => {
+  // NFFN trough style: lat-first pairs, no TO separators
+  const line = parseCoordinateChain("TROUGH T1 10S 160E 12S 166E SLOW MOVING");
+  assert.equal(line.length, 2);
+  approx(line[0][0], 160);
+  approx(line[0][1], -10);
+  approx(line[1][0], 166);
+  approx(line[1][1], -12);
+  assert.equal(parseCoordinateChain("10S 160E"), null); // single pair
+});
+
+test("cardinal bounds translate to a bbox", () => {
+  // SOUTH OF x means lat ≤ x: the box extends to the south pole
+  assert.deepEqual(
+    parseCardinalBounds("SOUTH OF 12S AND WEST OF 173W"),
+    [-180, -90, -173, -12],
+  );
+  // NORTH OF x means lat ≥ x: the box extends to the north pole
+  assert.deepEqual(
+    parseCardinalBounds("NORTH OF 25S AND EAST OF 179E"),
+    [179, -25, 180, 90],
+  );
+  assert.equal(parseCardinalBounds("no geography here"), null);
+});
+
+test("live NFFN bulletin: axis lines band-filtered, cardinal areas kept", () => {
+  // Real FQPS01 NFFN text as received on board 2026-09-27, vessel at
+  // anchor 18.7S 174W: T1/T2 axis bands lie well north (dropped), the
+  // "south of 10S and west of 169W" area contains the vessel (kept)
+  const text = [
+    "FQPS01 NFFN 270700",
+    "MARINE WEATHER BULLETIN FOR ISLANDS AREA",
+    "EQUATOR TO 25S BETWEEN 160E AND 120W.",
+    "ISSUED BY FIJI METEOROLOGICAL SERVICE SEP 270800 UTC.",
+    "",
+    "PART 1 : WARNINGNIL.",
+    "",
+    "PARTS 2 AND 3 : SYNOPSIS AND FORECAST VALID UNTIL SEP 280600 UTC.",
+    "",
+    " TROUGH T1 10S 160E 12S 166E SLOW MOVING. POOR VISIBILITY IN",
+    "OCCASIONAL SHOWERS AND FEW THUNDERSTORMS WITHIN 100 NAUTICAL MILES OF",
+    "T1.",
+    "",
+    "TROUGH T2 08S 172E 11S 179W 13S 173W SLOW MOVING. POOR VISIBILITY IN",
+    "OCCASIONAL SHOWERS AND FEW THUNDERSTORMS WITHIN 120 NAUTICAL MILES OF",
+    "T2.",
+    "",
+    "IN THE AREA SOUTH OF 10S AND WEST OF 169W, EXPECT SOUTHEAST WINDS 25",
+    "TO 30 KNOTS. ROUGH TO VERY ROUGH SEAS. MODERATE TO HEAVY SOUTH TO",
+    "SOUTHEAST SWELLS. ",
+  ].join("\n");
+  const bulletin = filterBulletin({
+    rawText: text,
+    source: "api",
+    track: [[-173.982, -18.658]],
+  });
+  const texts = bulletin.blocks.map((b) => b.text);
+  assert.ok(
+    texts.some((t) => t.includes("SOUTHEAST WINDS 25")),
+    "area containing the vessel kept",
+  );
+  assert.ok(!texts.some((t) => t.includes("TROUGH T1")), "T1 band dropped");
+  assert.ok(!texts.some((t) => t.includes("TROUGH T2")), "T2 band dropped");
+});
+
+// --- Antimeridian -------------------------------------------------------------
+
+/** Fiji-waters rectangle crossing the seam: 170E → 178W, 16S..25S. */
+const SEAM_BOX = parseCardinalBoundsWrapper();
+function parseCardinalBoundsWrapper() {
+  const { parseCoordinateChain } = require("../plugin/bulletin-engine.js");
+  return parseCoordinateChain("16S 170E TO 16S 178W TO 25S 178W TO 25S 170E");
+}
+
+test("ringContains handles polygons spanning 180", () => {
+  const ring = SEAM_BOX;
+  // Inside on the west side (179W is between 180 and the 178W edge)
+  assert.equal(ringContains(ring, -179, -20), true);
+  // Inside on the eastern (170E..180) side
+  assert.equal(ringContains(ring, 171, -20), true);
+  // Outside: 177W is east of the box's 178W edge
+  assert.equal(ringContains(ring, -177, -20), false);
+  // Outside: before 170E
+  assert.equal(ringContains(ring, 169, -20), false);
+  // Outside: well beyond the seam
+  assert.equal(ringContains(ring, -160, -20), false);
+});
+
+test("bbox intersection wraps around the antimeridian", () => {
+  // EAST OF 179E AND WEST OF 173W: wraps from +179 through 180 to −173
+  const bbox = parseCardinalBounds("EAST OF 179E AND WEST OF 173W");
+  assert.deepEqual(bbox, [179, -90, 187, 90]); // maxLon unwrapped
+  // Track point at 178E: west of the 179E bound → outside
+  assert.equal(bboxIntersectsTrack(bbox, [[178, -20]]), false);
+  // Track points through the seam: 180E and 179W (181 unwrapped)
+  assert.equal(bboxIntersectsTrack(bbox, [[180, -20]]), true);
+  assert.equal(bboxIntersectsTrack(bbox, [[-179, -20]]), true);
+  assert.equal(bboxIntersectsTrack(bbox, [[-175, -20]]), true);
+  // Track point at 150E: outside the box either way
+  assert.equal(bboxIntersectsTrack(bbox, [[150, -20]]), false);
+});
+
+// --- Track discard rule ---------------------------------------------------------
+
+test("filterBulletin retains the gale warning end-to-end", () => {
+  // Subject A (navigational warning) is retained by default
+  const result = filterBulletin({
+    rawText: NAVAREA_FIXTURE,
+    source: "spool",
+    track: TONGA_TRACK,
+    issuedAt: "2026-08-01T12:00:00.000Z",
+  });
+  assert.ok(result, "subject A retained");
+  assert.equal(result.source, "spool");
+  assert.equal(result.issuedAt, "2026-08-01T12:00:00.000Z");
+  assert.ok(result.blocks.length > 0);
+  const trough = result.blocks.find((b) => b.text.includes("TROUGH"));
+  assert.ok(trough, "trough block kept");
+  assert.equal(trough.geometryType, "polygon");
+  assert.equal(trough.subject, "A");
+});
+
+test("retained bulletin: blocks filtered against the Tonga track", () => {
+  const result = filterBulletin({
+    rawText: NAVAREA_FIXTURE,
+    source: "spool",
+    track: TONGA_TRACK,
+    issuedAt: "2026-08-01T12:00:00.000Z",
+    retainedSubjects: "ABEG",
+  });
+  assert.ok(result, "retained with G in the set");
+
+  // The far-away synopsis has no geography: kept conservatively
+  const synopsis = result.blocks.find((b) => b.text.includes("SITUATION"));
+  assert.ok(synopsis, "no-geometry block kept");
+  assert.equal(synopsis.geometryType, null);
+});
+test("ukhoBlocksFromWarnings: structured geometry vs track, point bbox", () => {
+  const warnings = [
+    {
+      text: "BUOY OFF STATION NEAR OPUA",
+      issuedAt: "2026-09-27T10:00:00Z",
+      coordinates: [
+        [174.0, -35.0],
+        [174.6, -35.4],
+        [174.2, -35.8],
+      ],
+    },
+    {
+      text: "FAR SHORE EVENT",
+      issuedAt: null,
+      coordinates: [
+        [0, 0],
+        [1, 0],
+        [1, 1],
+      ],
+    },
+    { text: "POINT HAZARD", issuedAt: null, coordinates: [[174.31, -35.31]] },
+  ];
+  const track = [
+    [174.3, -35.3],
+    [174.9, -35.6],
+  ];
+  const blocks = ukhoBlocksFromWarnings(warnings, track);
+  assert.deepEqual(
+    blocks.map((b) => b.text),
+    ["BUOY OFF STATION NEAR OPUA", "POINT HAZARD"],
+  );
+  assert.equal(blocks[0].source, "ukho");
+  assert.equal(blocks[0].geometryType, "polygon");
+  assert.equal(blocks[1].geometryType, "bbox");
+  assert.equal(blocks[1].subject, null);
+});
+
+test("discard rule drops geographically irrelevant warnings", () => {
+  // Same warning re-anchored to the Atlantic: nowhere near the track
+  const atlantic = NAVAREA_FIXTURE.replace(
+    "16S 170E TO 20S 178W TO 25S 175W",
+    "40N 020W TO 45N 030W TO 38N 035W",
+  );
+  const result = filterBulletin({
+    rawText: atlantic,
+    source: "api",
+    track: TONGA_TRACK,
+    retainedSubjects: "ABEG",
+  });
+  const trough = result.blocks.find((b) => b.text.includes("TROUGH"));
+  assert.equal(trough, undefined, "Atlantic trough dropped for Pacific track");
+  assert.ok(result.blocks.some((b) => b.text.includes("SITUATION")));
+});
+
+// --- Bulletin source ----------------------------------------------------------
+
+test("bulletin cache round-trips and prunes to the newest", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "bulletin-cache-"));
+  assert.deepEqual(await loadBulletinCache(dir), []);
+
+  const entries = [
+    { url: "https://x/a.txt", fetchedAt: "2026-08-01T00:00:00Z", text: "A" },
+    { url: "https://x/b.txt", fetchedAt: "2026-08-02T00:00:00Z", text: "B" },
+  ];
+  await saveBulletinCache(dir, entries);
+  const loaded = await loadBulletinCache(dir);
+  assert.equal(loaded.length, 2);
+  assert.equal(loaded[0].text, "B"); // Newest first
+
+  // Corrupt file → empty, not a crash
+  writeFileSync(join(dir, "weather", "bulletins.json"), "{oops");
+  assert.deepEqual(await loadBulletinCache(dir), []);
+});
+
+test("refreshBulletins fetches online sources, skips failures", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "bulletin-fetch-"));
+  const fetchImpl = async (url) => {
+    if (String(url).includes("broken")) {
+      throw new Error("connection refused");
+    }
+    return { ok: true, text: async () => NAVAREA_FIXTURE };
+  };
+  const { fetched, failed, entries } = await refreshBulletins({
+    dataDir: dir,
+    urls: ["https://met/a.txt", "https://met/broken.txt"],
+    fetchImpl,
+  });
+  assert.deepEqual(fetched, ["https://met/a.txt"]);
+  assert.deepEqual(failed, ["https://met/broken.txt"]);
+  assert.equal(entries.length, 1);
+
+  // Persisted and re-loadable
+  const loaded = await loadBulletinCache(dir);
+  assert.equal(loaded.length, 1);
+  assert.match(loaded[0].text, /GALE WARNING/);
+
+  // A second refresh failure keeps the cached copy
+  const second = await refreshBulletins({
+    dataDir: dir,
+    urls: ["https://met/a.txt"],
+    fetchImpl: async () => {
+      throw new Error("offline now");
+    },
+  });
+  assert.deepEqual(second.fetched, []);
+  assert.equal((await loadBulletinCache(dir)).length, 1);
+});