HealthLog/src/lib/medications/import/auto-export-instant.ts

/**
 * Reading an instant that carries its own UTC offset.
 *
 * The medication export writes `2023-02-16 08:38:00 +1030` — a space instead
 * of `T`, and a compact offset with no colon. Neither form is ISO 8601, so
 * `new Date(...)` on it is engine-dependent leniency rather than a contract:
 * V8 happens to accept it, another runtime need not, and a silent `Invalid
 * Date` or a reinterpretation in the server's zone would move every dose in
 * the file by hours. A file spanning an Australian summer carries `+1030` and
 * `+0930` on adjacent rows, so the offset is per-row data, not a file-level
 * setting to be guessed at once.
 *
 * So the offset is read explicitly and the epoch computed arithmetically:
 * `Date.UTC(wall clock) - offset`. Nothing here parses a date from a string
 * through the platform. A value without an offset is refused rather than
 * assumed — the server's zone is not evidence about where the dose was taken.
 *
 * `src/lib/tz/` is the project's timezone layer and it stays the authority for
 * the other direction (an instant plus a zone name to a local day key, which
 * is what the compliance rollups key on). It carries no parser, by design: it
 * converts an offset-less wall clock plus a zone NAME to UTC. An offset is not
 * a zone name, so this is the one thing it cannot do, and this module is
 * deliberately the narrowest possible complement to it.
 */

/** Widest real UTC offset in either direction (±14:00, Kiritimati). */
const MAX_OFFSET_MINUTES = 14 * 60;

/**
 * `YYYY-MM-DD` `HH:MM:SS` with an optional fractional second, then either `Z`
 * or a `±HHMM` / `±HH:MM` offset. Both the space and the `T` separator are
 * accepted: the CSV uses a space, and a hand-edited file may well use `T`.
 */
const OFFSET_INSTANT_RE =
  /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?\s*(?:(Z|z)|([+-])(\d{2}):?(\d{2}))$/;

export type AutoExportInstantFailure =
  /** The cell was blank. Distinct from unreadable: nothing was stated. */
  | "absent"
  /** Shaped like a timestamp but carries no offset, so the instant is unknown. */
  | "missing_offset"
  /** Does not match the documented `yyyy-MM-dd HH:mm:ss Z` shape at all. */
  | "unreadable"
  /** Matches the shape but names no real instant (month 13, offset ±99:00). */
  | "out_of_range";

export type AutoExportInstantResult =
  | { ok: true; instant: Date; offsetMinutes: number }
  | { ok: false; failure: AutoExportInstantFailure };

/**
 * True when the value looks like a date-time that simply lost its offset, so
 * the refusal can say "no offset" rather than the less useful "unreadable".
 */
const OFFSETLESS_INSTANT_RE =
  /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2})?(\.\d{1,9})?$/;

/**
 * Parse one `Date` / `Scheduled Date` cell.
 *
 * Returns the absolute instant and the offset that produced it. The offset is
 * handed back rather than discarded so a caller can prove, in a test, that the
 * value the file stated is the value that survived.
 */
export function parseAutoExportInstant(
  raw: string | null | undefined,
): AutoExportInstantResult {
  const value = (raw ?? "").trim();
  if (value.length === 0) return { ok: false, failure: "absent" };

  const match = OFFSET_INSTANT_RE.exec(value);
  if (!match) {
    return {
      ok: false,
      failure: OFFSETLESS_INSTANT_RE.test(value)
        ? "missing_offset"
        : "unreadable",
    };
  }

  const [, y, mo, d, h, mi, s, zulu, sign, offH, offM] = match;
  const year = Number(y);
  const month = Number(mo);
  const day = Number(d);
  const hour = Number(h);
  const minute = Number(mi);
  const second = Number(s);

  if (month < 1 || month > 12 || day < 1 || day > 31) {
    return { ok: false, failure: "out_of_range" };
  }
  if (hour > 23 || minute > 59 || second > 59) {
    return { ok: false, failure: "out_of_range" };
  }

  let offsetMinutes = 0;
  if (!zulu) {
    const offsetHours = Number(offH);
    const offsetRemainder = Number(offM);
    if (offsetRemainder > 59) return { ok: false, failure: "out_of_range" };
    offsetMinutes =
      (sign === "-" ? -1 : 1) * (offsetHours * 60 + offsetRemainder);
    if (Math.abs(offsetMinutes) > MAX_OFFSET_MINUTES) {
      return { ok: false, failure: "out_of_range" };
    }
  }

  // `Date.UTC` rolls a nonexistent calendar day over (Feb 30 becomes Mar 2),
  // so the components are read back and compared. A rolled-over value means
  // the file named a day that does not exist, which is a refusal, not a
  // silently shifted dose.
  const wallClockMs = Date.UTC(year, month - 1, day, hour, minute, second);
  const probe = new Date(wallClockMs);
  if (
    probe.getUTCFullYear() !== year ||
    probe.getUTCMonth() !== month - 1 ||
    probe.getUTCDate() !== day
  ) {
    return { ok: false, failure: "out_of_range" };
  }

  const instant = new Date(wallClockMs - offsetMinutes * 60_000);
  if (Number.isNaN(instant.getTime())) {
    return { ok: false, failure: "out_of_range" };
  }
  return { ok: true, instant, offsetMinutes };
}