refactor(report): summary

packages/types/src/definitions/core/Report.type.ts

@@ -1,8 +1,85 @@
 import type { MaybeNumber } from '../../utils/utils.type.js';
+import type { EntryId } from './OntimeEntry.js';
 
 export type OntimeEventReport = {
   startedAt: MaybeNumber;
   endedAt: MaybeNumber;
+  /**
+   * Snapshot of the schedule taken when the event ran.
+   * Keeping a copy is what makes a report a record: editing the rundown
+   * afterwards no longer changes how a show that already happened is reported.
+   */
+  scheduledStart: number;
+  scheduledDuration: number;
 };
 
-export type OntimeReport = Record<string, OntimeEventReport>;
+export type OntimeReport = Record<EntryId, OntimeEventReport>;
+
+/**
+ * Show level times for the report.
+ *
+ * Planned times are snapshotted when the show starts, for the same reason the
+ * per event schedule is. Actual times are derived from the events that ran.
+ */
+export type ShowReport = {
+  plannedStart: MaybeNumber;
+  plannedEnd: MaybeNumber;
+  actualStart: MaybeNumber;
+  actualEnd: MaybeNumber;
+};
+
+/**
+ * How the show sat against its plan.
+ *
+ * Follows Ontime's offset convention: positive means behind schedule.
+ * `duringShow` separates a late start from a badly run show, which have
+ * different causes and different remedies.
+ */
+export type ShowOffsets = {
+  /** actual start against planned start */
+  startOffset: MaybeNumber;
+  /** actual end against planned end */
+  endOffset: MaybeNumber;
+  /** time lost (positive) or recovered (negative) between start and end */
+  duringShow: MaybeNumber;
+};
+
+/**
+ * How a group ran against the budget set for it.
+ *
+ * Ontime already compares a group's scheduled duration against its
+ * targetDuration while planning. This closes that loop after the show.
+ */
+export type GroupReport = {
+  id: EntryId;
+  title: string;
+  colour: string;
+  /** the budget the user set for the block, null when they set none */
+  targetDuration: MaybeNumber;
+  /** what was scheduled into the block */
+  scheduledDuration: number;
+  actualStart: MaybeNumber;
+  actualEnd: MaybeNumber;
+  /** wall time from the first event starting to the last one ending */
+  elapsed: MaybeNumber;
+  /**
+   * Time inside the block not covered by a running event, ie changeovers.
+   * elapsed minus the sum of the events' own durations.
+   */
+  changeover: MaybeNumber;
+  /** measured against targetDuration where set, otherwise scheduledDuration */
+  variance: MaybeNumber;
+  eventsRun: number;
+  eventsPlanned: number;
+};
+
+/** Counts across the events in the report */
+export type RunSummary = {
+  eventsRun: number;
+  eventsPlanned: number;
+  eventsOver: number;
+  eventsUnder: number;
+  eventsOnTime: number;
+  /** largest single overrun, answers "what blew the schedule" */
+  worstOverrun: { id: EntryId; delta: number } | null;
+};

packages/types/src/index.ts

@@ -24,7 +24,14 @@ export { TimerType } from './definitions/TimerType.type.js';
 export type { Day, Duration, Instant, TimeOfDay } from './definitions/core/Temporal.js';
 
 // ---> Report
-export type { OntimeReport, OntimeEventReport } from './definitions/core/Report.type.js';
+export type {
+  GroupReport,
+  OntimeReport,
+  OntimeEventReport,
+  RunSummary,
+  ShowOffsets,
+  ShowReport,
+} from './definitions/core/Report.type.js';
 
 // ---> Automations
 export { ontimeActionKeyValues } from './definitions/core/Automation.type.js';

packages/utils/index.ts

@@ -99,6 +99,19 @@ export {
 
 export { isPlaybackActive } from './src/playback-utils/playbackstate.js';
 
+// feature business logic - reports
+export {
+  countPlannedEvents,
+  elapsedBetween,
+  getActualShowTimes,
+  getEventVariance,
+  getGroupReports,
+  getRunSummary,
+  getShowOffsets,
+  type EventVariance,
+  type VarianceStatus,
+} from './src/report-utils/reportUtils.js';
+
 //Colour
 export {
   colourToHex,

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

@@ -0,0 +1,277 @@
+import type { OntimeEventReport, OntimeReport, RundownEntries } from 'ontime-types';
+import { SupportedEntry } from 'ontime-types';
+
+import { dayInMs } from '../date-utils/conversionUtils.js';
+import {
+  countPlannedEvents,
+  elapsedBetween,
+  getActualShowTimes,
+  getEventVariance,
+  getGroupReports,
+  getRunSummary,
+  getShowOffsets,
+} from './reportUtils.js';
+
+const MIN = 60000;
+
+function makeEntry(patch: Partial<OntimeEventReport> = {}): OntimeEventReport {
+  return { startedAt: 0, endedAt: 10000, scheduledStart: 0, scheduledDuration: 10000, ...patch };
+}
+
+function makeEvent(id: string, patch: Record<string, unknown> = {}) {
+  return { type: SupportedEntry.Event, id, duration: 10000, skip: false, parent: null, ...patch } as never;
+}
+
+function makeGroup(id: string, entries: string[], patch: Record<string, unknown> = {}) {
+  return {
+    type: SupportedEntry.Group,
+    id,
+    title: id,
+    colour: '',
+    targetDuration: null,
+    entries,
+    ...patch,
+  } as never;
+}
+
+describe('elapsedBetween()', () => {
+  it('measures forward within a day', () => {
+    expect(elapsedBetween(1000, 5000)).toBe(4000);
+  });
+
+  it('reads a backwards result as having crossed midnight', () => {
+    // 23:50 to 00:10 is twenty minutes, not minus twenty three hours
+    const tenToMidnight = dayInMs - 10 * MIN;
+    expect(elapsedBetween(tenToMidnight, 10 * MIN)).toBe(20 * MIN);
+  });
+});
+
+describe('getEventVariance()', () => {
+  it('reports an event which never ran', () => {
+    expect(getEventVariance(undefined)).toMatchObject({ status: 'not-run', actualDuration: null });
+  });
+
+  it('reports an event which started but never finished', () => {
+    expect(getEventVariance(makeEntry({ endedAt: null }))).toMatchObject({ status: 'not-run' });
+  });
+
+  it('treats sub-second differences as on time', () => {
+    expect(getEventVariance(makeEntry({ endedAt: 10500 }))).toMatchObject({ status: 'ontime', delta: 500 });
+  });
+
+  it('reports an overrun', () => {
+    expect(getEventVariance(makeEntry({ endedAt: 15000 }))).toMatchObject({ status: 'over', delta: 5000 });
+  });
+
+  it('reports an underrun', () => {
+    expect(getEventVariance(makeEntry({ endedAt: 6000 }))).toMatchObject({ status: 'under', delta: -4000 });
+  });
+
+  it('measures against the snapshot, not a later edit', () => {
+    expect(getEventVariance(makeEntry({ endedAt: 12000, scheduledDuration: 10000 })).delta).toBe(2000);
+  });
+
+  it('handles an event running past midnight', () => {
+    const entry = makeEntry({ startedAt: dayInMs - 5 * MIN, endedAt: 5 * MIN, scheduledDuration: 10 * MIN });
+    expect(getEventVariance(entry)).toMatchObject({ status: 'ontime', actualDuration: 10 * MIN });
+  });
+});
+
+describe('getShowOffsets()', () => {
+  it('reports a late start carried through to a late end', () => {
+    // started 8 late, ended 8 late: the show itself ran clean
+    const offsets = getShowOffsets({
+      plannedStart: 19 * 60 * MIN,
+      plannedEnd: 21 * 60 * MIN,
+      actualStart: 19 * 60 * MIN + 8 * MIN,
+      actualEnd: 21 * 60 * MIN + 8 * MIN,
+    });
+
+    expect(offsets).toEqual({ startOffset: 8 * MIN, endOffset: 8 * MIN, duringShow: 0 });
+  });
+
+  it('separates time lost during the show from a late start', () => {
+    const offsets = getShowOffsets({
+      plannedStart: 19 * 60 * MIN,
+      plannedEnd: 21 * 60 * MIN,
+      actualStart: 19 * 60 * MIN + 8 * MIN,
+      actualEnd: 21 * 60 * MIN + 12 * MIN,
+    });
+
+    expect(offsets).toMatchObject({ startOffset: 8 * MIN, endOffset: 12 * MIN, duringShow: 4 * MIN });
+  });
+
+  it('reports time recovered as a negative', () => {
+    const offsets = getShowOffsets({
+      plannedStart: 19 * 60 * MIN,
+      plannedEnd: 21 * 60 * MIN,
+      actualStart: 19 * 60 * MIN + 10 * MIN,
+      actualEnd: 21 * 60 * MIN + 2 * MIN,
+    });
+
+    expect(offsets.duringShow).toBe(-8 * MIN);
+  });
+
+  it('does not read a show ending after midnight as a day early', () => {
+    const offsets = getShowOffsets({
+      plannedStart: 23 * 60 * MIN,
+      plannedEnd: dayInMs - 10 * MIN,
+      actualStart: 23 * 60 * MIN,
+      actualEnd: 5 * MIN, // ran past midnight
+    });
+
+    expect(offsets.endOffset).toBe(15 * MIN);
+  });
+
+  it('has nothing to report without a plan', () => {
+    expect(getShowOffsets({ plannedStart: null, plannedEnd: null, actualStart: 1, actualEnd: 2 })).toEqual({
+      startOffset: null,
+      endOffset: null,
+      duringShow: null,
+    });
+  });
+});
+
+describe('getActualShowTimes()', () => {
+  it('opens on the first start and closes on the last end', () => {
+    const report: OntimeReport = {
+      b: makeEntry({ startedAt: 5000, endedAt: 9000 }),
+      a: makeEntry({ startedAt: 1000, endedAt: 4000 }),
+      c: makeEntry({ startedAt: 9000, endedAt: 20000 }),
+    };
+
+    expect(getActualShowTimes(report)).toEqual({ actualStart: 1000, actualEnd: 20000 });
+  });
+
+  it('is empty when nothing ran', () => {
+    expect(getActualShowTimes({})).toEqual({ actualStart: null, actualEnd: null });
+  });
+});
+
+describe('getGroupReports()', () => {
+  const entries: RundownEntries = {
+    act1: makeGroup('act1', ['a', 'b'], { targetDuration: 30 * MIN }),
+    a: makeEvent('a', { duration: 10 * MIN, parent: 'act1' }),
+    b: makeEvent('b', { duration: 10 * MIN, parent: 'act1' }),
+  };
+
+  it('measures the block against the target the user set', () => {
+    const report: OntimeReport = {
+      a: makeEntry({ startedAt: 0, endedAt: 12 * MIN, scheduledDuration: 10 * MIN }),
+      b: makeEntry({ startedAt: 12 * MIN, endedAt: 24 * MIN, scheduledDuration: 10 * MIN }),
+    };
+
+    const [group] = getGroupReports(report, entries, ['act1']);
+
+    expect(group).toMatchObject({
+      targetDuration: 30 * MIN,
+      elapsed: 24 * MIN,
+      variance: -6 * MIN, // came in under its 30 minute budget
+      eventsRun: 2,
+      eventsPlanned: 2,
+    });
+  });
+
+  it('reports the time a block spent not running an event', () => {
+    // 5 minute changeover between the two events
+    const report: OntimeReport = {
+      a: makeEntry({ startedAt: 0, endedAt: 10 * MIN, scheduledDuration: 10 * MIN }),
+      b: makeEntry({ startedAt: 15 * MIN, endedAt: 25 * MIN, scheduledDuration: 10 * MIN }),
+    };
+
+    const [group] = getGroupReports(report, entries, ['act1']);
+
+    expect(group.elapsed).toBe(25 * MIN);
+    expect(group.changeover).toBe(5 * MIN);
+  });
+
+  it('falls back to what was scheduled when no target was set', () => {
+    const noTarget: RundownEntries = { ...entries, act1: makeGroup('act1', ['a', 'b']) };
+    const report: OntimeReport = {
+      a: makeEntry({ startedAt: 0, endedAt: 12 * MIN, scheduledDuration: 10 * MIN }),
+      b: makeEntry({ startedAt: 12 * MIN, endedAt: 24 * MIN, scheduledDuration: 10 * MIN }),
+    };
+
+    const [group] = getGroupReports(report, noTarget, ['act1']);
+
+    // 24 elapsed against 20 scheduled
+    expect(group.targetDuration).toBeNull();
+    expect(group.scheduledDuration).toBe(20 * MIN);
+    expect(group.variance).toBe(4 * MIN);
+  });
+
+  it('reads a partly run block as incomplete rather than as an overrun', () => {
+    const report: OntimeReport = {
+      a: makeEntry({ startedAt: 0, endedAt: 10 * MIN, scheduledDuration: 10 * MIN }),
+    };
+
+    const [group] = getGroupReports(report, entries, ['act1']);
+
+    expect(group.eventsRun).toBe(1);
+    expect(group.eventsPlanned).toBe(2);
+  });
+
+  it('has no actuals for a block which never ran', () => {
+    const [group] = getGroupReports({}, entries, ['act1']);
+
+    expect(group).toMatchObject({ elapsed: null, changeover: null, variance: null, eventsRun: 0 });
+  });
+
+  it('leaves skipped events out of the block', () => {
+    const withSkip: RundownEntries = { ...entries, b: makeEvent('b', { duration: 10 * MIN, skip: true }) };
+
+    const [group] = getGroupReports({}, withSkip, ['act1']);
+
+    expect(group.eventsPlanned).toBe(1);
+    expect(group.scheduledDuration).toBe(10 * MIN);
+  });
+
+  it('ignores entries which are not groups', () => {
+    expect(getGroupReports({}, entries, ['a'])).toEqual([]);
+  });
+});
+
+describe('getRunSummary()', () => {
+  it('counts how events landed', () => {
+    const report: OntimeReport = {
+      a: makeEntry({ endedAt: 15000 }), // over
+      b: makeEntry({ endedAt: 6000 }), // under
+      c: makeEntry({ endedAt: 10000 }), // on time
+    };
+
+    expect(getRunSummary(report, 4)).toMatchObject({
+      eventsRun: 3,
+      eventsPlanned: 4,
+      eventsOver: 1,
+      eventsUnder: 1,
+      eventsOnTime: 1,
+    });
+  });
+
+  it('identifies the worst overrun', () => {
+    const report: OntimeReport = {
+      a: makeEntry({ endedAt: 15000 }),
+      b: makeEntry({ endedAt: 30000 }),
+      c: makeEntry({ endedAt: 12000 }),
+    };
+
+    expect(getRunSummary(report, 3).worstOverrun).toEqual({ id: 'b', delta: 20000 });
+  });
+
+  it('ignores events which did not complete', () => {
+    const report: OntimeReport = { a: makeEntry({ endedAt: 15000 }), b: makeEntry({ endedAt: null }) };
+    expect(getRunSummary(report, 2).eventsRun).toBe(1);
+  });
+});
+
+describe('countPlannedEvents()', () => {
+  it('counts playable events, excluding skipped ones', () => {
+    const entries: RundownEntries = {
+      a: makeEvent('a'),
+      b: makeEvent('b', { skip: true }),
+      g: makeGroup('g', []),
+    };
+
+    expect(countPlannedEvents(entries, ['a', 'b', 'g'])).toBe(1);
+  });
+});

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;
+}