@7365admin1/module-hygiene 4.28.1-staging.7 → 4.28.1-staging.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/module-hygiene",
   "license": "MIT",
-  "version": "4.28.1-staging.7",
+  "version": "4.28.1-staging.8",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "release": "yarn run build && changeset publish",
-    "lint": "tsc"
+    "lint": "tsc",
+    "test": "tsup src/utils/hygiene-dashboard-metrics.util.ts --format esm --out-dir test/.build --no-dts --silent && node --test \"test/*.test.mjs\""
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.0",

package/test/hygiene-dashboard-metrics.util.test.mjs

@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DASHBOARD_TIMEZONE,
+  SUPPLY_ALERT_HAS_NO_PRIOR_PERIOD,
+  calculatePercentageChange,
+  getPeriodRange,
+  getPreviousPeriodRange,
+} from "./.build/hygiene-dashboard-metrics.util.mjs";
+
+/*
+  THE CLOCK IS PINNED, IN EVERY TEST THAT HAS ONE.
+
+  17:00 UTC on the 19th is 01:00 SGT on the 20th — a deliberately chosen instant
+  where the host's calendar day and Singapore's calendar day DISAGREE. A boundary
+  that quietly inherited the host's timezone would land on the 19th here and the
+  assertions below would fail. Nothing in this file reads the wall clock, so the
+  answers do not change with the hour the suite runs at, or with the machine's TZ.
+*/
+const LATE_EVENING_UTC = "2026-08-19T17:00:00.000Z";
+
+// ---------------------------------------------------------------------------
+// The day boundary is Singapore's, not the host's.
+// ---------------------------------------------------------------------------
+
+test("the day starts at Singapore midnight even when the host is a day behind", () => {
+  const range = getPeriodRange("today", LATE_EVENING_UTC);
+
+  // SGT is already on the 20th at this instant.
+  assert.equal(range.$gte.toISOString(), "2026-08-19T16:00:00.000Z");
+  assert.equal(range.$lte.toISOString(), "2026-08-20T15:59:59.999Z");
+});
+
+test("every boundary carries the UTC+8 signature, whatever timezone this test runs in", () => {
+  // 16:00 UTC IS midnight in Singapore. Asserting the offset rather than a local
+  // string keeps this true on a UTC container, an SGT container and a laptop.
+  for (const period of ["today", "thisWeek", "thisMonth"]) {
+    for (const range of [
+      getPeriodRange(period, LATE_EVENING_UTC),
+      getPreviousPeriodRange(period, LATE_EVENING_UTC),
+    ]) {
+      assert.equal(range.$gte.getUTCHours(), 16, `${period} start`);
+      assert.equal(range.$lte.getUTCHours(), 15, `${period} end`);
+    }
+  }
+});
+
+test("an unknown period falls back to a day, as it always did", () => {
+  assert.deepEqual(
+    getPeriodRange("whatever", LATE_EVENING_UTC),
+    getPeriodRange("today", LATE_EVENING_UTC),
+  );
+});
+
+test("the timezone is stated, not inherited", () => {
+  assert.equal(DASHBOARD_TIMEZONE, "Asia/Singapore");
+});
+
+// ---------------------------------------------------------------------------
+// The trend compares the period the user actually selected.
+// ---------------------------------------------------------------------------
+
+test("this week compares against the PREVIOUS ISO week, not yesterday", () => {
+  // 20 Aug 2026 SGT is a Thursday, so the ISO week runs Mon 17 -> Sun 23.
+  const current = getPeriodRange("thisWeek", LATE_EVENING_UTC);
+  const prior = getPreviousPeriodRange("thisWeek", LATE_EVENING_UTC);
+
+  assert.equal(current.$gte.toISOString(), "2026-08-16T16:00:00.000Z"); // Mon 17 SGT
+  assert.equal(prior.$gte.toISOString(), "2026-08-09T16:00:00.000Z"); // Mon 10 SGT
+  assert.equal(prior.$lte.toISOString(), "2026-08-16T15:59:59.999Z"); // Sun 16 SGT
+
+  // The two ranges are adjacent and do not overlap.
+  assert.equal(prior.$lte.getTime() + 1, current.$gte.getTime());
+});
+
+test("this month compares against the PREVIOUS month, not yesterday", () => {
+  const current = getPeriodRange("thisMonth", LATE_EVENING_UTC);
+  const prior = getPreviousPeriodRange("thisMonth", LATE_EVENING_UTC);
+
+  assert.equal(current.$gte.toISOString(), "2026-07-31T16:00:00.000Z"); // 1 Aug SGT
+  assert.equal(prior.$gte.toISOString(), "2026-06-30T16:00:00.000Z"); // 1 Jul SGT
+  assert.equal(prior.$lte.getTime() + 1, current.$gte.getTime());
+});
+
+test("today still compares against yesterday", () => {
+  const current = getPeriodRange("today", LATE_EVENING_UTC);
+  const prior = getPreviousPeriodRange("today", LATE_EVENING_UTC);
+
+  assert.equal(prior.$gte.toISOString(), "2026-08-18T16:00:00.000Z");
+  assert.equal(prior.$lte.getTime() + 1, current.$gte.getTime());
+});
+
+test("stepping a month back from the 31st does not skip a month", () => {
+  // 31 Aug SGT minus one month is 31 July in moment's arithmetic, which snaps
+  // to July — the trap the core suite caught, re-asserted here.
+  const prior = getPreviousPeriodRange("thisMonth", "2026-08-30T20:00:00.000Z");
+  assert.equal(prior.$gte.toISOString(), "2026-06-30T16:00:00.000Z");
+});
+
+// ---------------------------------------------------------------------------
+// A missing prior period yields NO percentage — never 0%, never 100%.
+// ---------------------------------------------------------------------------
+
+test("no prior period means no percentage, not 100%", () => {
+  assert.equal(calculatePercentageChange(7, 0), null);
+});
+
+test("two empty periods mean no percentage, not a measured 0%", () => {
+  assert.equal(calculatePercentageChange(0, 0), null);
+});
+
+test("a real comparison still returns a real number", () => {
+  assert.equal(calculatePercentageChange(3, 2), 50);
+  assert.equal(calculatePercentageChange(1, 3), -66.67);
+  assert.equal(calculatePercentageChange(2, 2), 0); // a genuine measured 0%
+});
+
+test("a non-number on either side is not silently treated as zero", () => {
+  for (const bad of [null, undefined, NaN, Infinity, "4"]) {
+    assert.equal(calculatePercentageChange(bad, 5), null, `current=${bad}`);
+    assert.equal(calculatePercentageChange(5, bad), null, `previous=${bad}`);
+  }
+});
+
+test("the percentage is never a constant — it moves with its inputs", () => {
+  const answers = new Set(
+    [
+      [10, 5],
+      [5, 10],
+      [3, 2],
+      [100, 25],
+    ].map(([a, b]) => calculatePercentageChange(a, b)),
+  );
+  assert.equal(answers.size, 4);
+  assert.ok(!answers.has(null));
+});
+
+// ---------------------------------------------------------------------------
+// Supply alert: an honest count, and an explicit not-available beside it.
+// ---------------------------------------------------------------------------
+
+test("the supply alert reason says why there is no percentage, in plain words", () => {
+  assert.match(SUPPLY_ALERT_HAS_NO_PRIOR_PERIOD, /out of stock right now/);
+  assert.match(SUPPLY_ALERT_HAS_NO_PRIOR_PERIOD, /no earlier period/);
+});