refactor(report): improve report summary

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

@@ -1,8 +1,103 @@
 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, as the two separate questions it answers.
+ *
+ * Follows Ontime's offset convention: positive means behind schedule.
+ *
+ * `endOffset` asks whether the show came off air when it promised to, which is
+ * what an audience or a venue booking is measured against. `durationOffset`
+ * asks whether the show itself ran long, which is what the team controls and
+ * what carries over to the next run of the same rundown. They differ by
+ * exactly `startOffset`: a show can run over and still finish early if it
+ * started early, so reporting either one alone is misleading.
+ */
+export type ShowOffsets = {
+  /** actual start against planned start */
+  startOffset: MaybeNumber;
+  /** actual end against planned end */
+  endOffset: MaybeNumber;
+  /** how long the show was planned to take */
+  plannedDuration: MaybeNumber;
+  /** how long it actually took */
+  actualDuration: MaybeNumber;
+  /** actualDuration against plannedDuration, ie whether the show ran long */
+  durationOffset: 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 with no event running: elapsed minus the sum of the
+   * events' own durations. Deliberately named for what was measured rather
+   * than for a cause, since the same gap can be a changeover, a timer started
+   * late, or an event run without the timer at all.
+   */
+  untimed: MaybeNumber;
+  /**
+   * Measured against targetDuration where set, otherwise scheduledDuration.
+   * Null while the group is incomplete: the events still to run would make a
+   * partial group read as a large underrun.
+   */
+  variance: MaybeNumber;
+  eventsRun: number;
+  eventsPlanned: number;
+};
+
+/**
+ * Counts across the events in the report.
+ *
+ * Deliberately not a tally of events over, under and on time: events rarely
+ * land on the exact second, so those buckets describe rounding more than they
+ * describe the show. The single worst overrun is the fact that acts on.
+ */
+export type RunSummary = {
+  eventsRun: number;
+  eventsPlanned: 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';