refactor(report): summary

packages/utils/src/report-utils/reportUtils.ts

@@ -0,0 +1,236 @@
+import type {
+  EntryId,
+  GroupReport,
+  OntimeEventReport,
+  OntimeReport,
+  RundownEntries,
+  RunSummary,
+  ShowOffsets,
+  ShowReport,
+} from 'ontime-types';
+import { isOntimeEvent, isOntimeGroup } from 'ontime-types';
+
+import { dayInMs, MILLIS_PER_SECOND } from '../date-utils/conversionUtils.js';
+
+export type VarianceStatus = 'ontime' | 'over' | 'under' | 'not-run';
+
+export type EventVariance = {
+  /** how long the event actually took, null if it never completed */
+  actualDuration: number | null;
+  /** actualDuration - scheduledDuration, signed. 0 when the event did not complete */
+  delta: number;
+  status: VarianceStatus;
+};
+
+const notRun: EventVariance = { actualDuration: null, delta: 0, status: 'not-run' };
+
+/**
+ * Time between two points in the day.
+ *
+ * Report times are times of day, so a show running past midnight would
+ * otherwise measure as a large negative. A backwards result is read as
+ * having crossed into the next day.
+ */
+export function elapsedBetween(from: number, to: number): number {
+  return to >= from ? to - from : to + dayInMs - from;
+}
+
+/**
+ * Calculates how an event performed against its schedule.
+ * An event is considered on time if it is within a second of its scheduled duration.
+ */
+export function getEventVariance(entry: OntimeEventReport | undefined): EventVariance {
+  if (!entry) {
+    return notRun;
+  }
+
+  const { startedAt, endedAt, scheduledDuration } = entry;
+  if (startedAt === null || endedAt === null) {
+    return notRun;
+  }
+
+  const actualDuration = elapsedBetween(startedAt, endedAt);
+  const delta = actualDuration - scheduledDuration;
+
+  if (Math.abs(delta) < MILLIS_PER_SECOND) {
+    return { actualDuration, delta, status: 'ontime' };
+  }
+
+  return { actualDuration, delta, status: delta > 0 ? 'over' : 'under' };
+}
+
+/**
+ * How the show sat against its plan.
+ *
+ * A sum of event overruns cannot answer this: gaps absorb overrun, skipped
+ * events give time back, and a late start moves the whole show without any
+ * event running long.
+ */
+export function getShowOffsets(show: ShowReport): ShowOffsets {
+  const startOffset = offsetBetween(show.plannedStart, show.actualStart);
+  const endOffset = offsetBetween(show.plannedEnd, show.actualEnd);
+
+  return {
+    startOffset,
+    endOffset,
+    duringShow: startOffset === null || endOffset === null ? null : endOffset - startOffset,
+  };
+}
+
+/**
+ * Signed distance from a planned time to the time it happened.
+ * Positive means late, matching Ontime's offset convention.
+ * @private
+ */
+function offsetBetween(planned: number | null, actual: number | null): number | null {
+  if (planned === null || actual === null) {
+    return null;
+  }
+
+  const diff = actual - planned;
+  // a show is not half a day early: read a large negative as having crossed midnight
+  if (diff < -dayInMs / 2) {
+    return diff + dayInMs;
+  }
+  if (diff > dayInMs / 2) {
+    return diff - dayInMs;
+  }
+  return diff;
+}
+
+/**
+ * Derives the show's actual start and end from the events that ran.
+ * The first event to start opens the show, the last to finish closes it.
+ */
+export function getActualShowTimes(report: OntimeReport): Pick<ShowReport, 'actualStart' | 'actualEnd'> {
+  let actualStart: number | null = null;
+  let actualEnd: number | null = null;
+
+  for (const entry of Object.values(report)) {
+    if (entry.startedAt !== null && (actualStart === null || entry.startedAt < actualStart)) {
+      actualStart = entry.startedAt;
+    }
+    if (entry.endedAt !== null && (actualEnd === null || entry.endedAt > actualEnd)) {
+      actualEnd = entry.endedAt;
+    }
+  }
+
+  return { actualStart, actualEnd };
+}
+
+/**
+ * Rolls the report up to the blocks the show was planned in.
+ *
+ * A group carries a targetDuration the user committed to while planning, and
+ * Ontime already tells them whether the schedule fits it. This reports whether
+ * the show actually did.
+ */
+export function getGroupReports(report: OntimeReport, entries: RundownEntries, order: EntryId[]): GroupReport[] {
+  const groups: GroupReport[] = [];
+
+  for (const id of order) {
+    const group = entries[id];
+    if (!group || !isOntimeGroup(group)) continue;
+
+    let scheduledDuration = 0;
+    let eventsPlanned = 0;
+    let eventsRun = 0;
+    let ranDuration = 0;
+    let actualStart: number | null = null;
+    let actualEnd: number | null = null;
+
+    for (const childId of group.entries) {
+      const child = entries[childId];
+      // skipped events were never meant to run and would read as missed
+      if (!child || !isOntimeEvent(child) || child.skip) continue;
+
+      eventsPlanned += 1;
+      const reported = report[childId];
+      // measure against what was scheduled at the time where we know it
+      scheduledDuration += reported?.scheduledDuration ?? child.duration;
+
+      const variance = getEventVariance(reported);
+      if (variance.status === 'not-run') continue;
+
+      eventsRun += 1;
+      ranDuration += variance.actualDuration as number;
+
+      const started = reported.startedAt as number;
+      const ended = reported.endedAt as number;
+      if (actualStart === null || started < actualStart) actualStart = started;
+      if (actualEnd === null || ended > actualEnd) actualEnd = ended;
+    }
+
+    const elapsed = actualStart === null || actualEnd === null ? null : elapsedBetween(actualStart, actualEnd);
+    // the budget if the user set one, otherwise what they scheduled into it
+    const measuredAgainst = group.targetDuration ?? scheduledDuration;
+
+    groups.push({
+      id: group.id,
+      title: group.title,
+      colour: group.colour,
+      targetDuration: group.targetDuration,
+      scheduledDuration,
+      actualStart,
+      actualEnd,
+      elapsed,
+      // whatever the block spent not running an event
+      changeover: elapsed === null ? null : Math.max(0, elapsed - ranDuration),
+      variance: elapsed === null ? null : elapsed - measuredAgainst,
+      eventsRun,
+      eventsPlanned,
+    });
+  }
+
+  return groups;
+}
+
+/** Counts across the events in the report */
+export function getRunSummary(report: OntimeReport, eventsPlanned: number): RunSummary {
+  const summary: RunSummary = {
+    eventsRun: 0,
+    eventsPlanned,
+    eventsOver: 0,
+    eventsUnder: 0,
+    eventsOnTime: 0,
+    worstOverrun: null,
+  };
+
+  for (const [id, entry] of Object.entries(report)) {
+    const variance = getEventVariance(entry);
+    if (variance.status === 'not-run') {
+      continue;
+    }
+
+    summary.eventsRun += 1;
+
+    if (variance.status === 'over') {
+      summary.eventsOver += 1;
+      if (summary.worstOverrun === null || variance.delta > summary.worstOverrun.delta) {
+        summary.worstOverrun = { id, delta: variance.delta };
+      }
+    } else if (variance.status === 'under') {
+      summary.eventsUnder += 1;
+    } else {
+      summary.eventsOnTime += 1;
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Counts the events a run could have played.
+ * Skipped events are excluded: they were never meant to run and would
+ * make the completion figures read as if the show fell short.
+ */
+export function countPlannedEvents(entries: RundownEntries, order: EntryId[]): number {
+  let count = 0;
+  for (const id of order) {
+    const entry = entries[id];
+    if (entry && isOntimeEvent(entry) && !entry.skip) {
+      count += 1;
+    }
+  }
+  return count;
+}