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';