diff --git a/docs/usage/recording-a-bug-repro.md b/docs/usage/recording-a-bug-repro.md index 474a8128..c5559f4c 100644 --- a/docs/usage/recording-a-bug-repro.md +++ b/docs/usage/recording-a-bug-repro.md @@ -219,6 +219,7 @@ anchors sampled every 5 seconds during the recording and at every sleep, so cloc - subscriber events are stamped when the recorder receives them. komorebi sends the notification _after_ it has handled the event, so the stamp is when the handler **finished**; the `processing event` line in `komorebi.log` is when it began. + `komorebi-recorder trace` ties the two together. `komorebi-recorder selftest` checks this on your machine: it records a rendered on-screen clock and compares the clock visible in the video with the time the session predicts. The result is stored in `session.json` under `calibration`. diff --git a/komorebi-recorder/src/analysis/answers.rs b/komorebi-recorder/src/analysis/answers.rs new file mode 100644 index 00000000..47c64673 --- /dev/null +++ b/komorebi-recorder/src/analysis/answers.rs @@ -0,0 +1,514 @@ +//! The answers to "what was the state", "what changed" and "what happened", as data. +//! +//! Built here, from an [`Analysis`], so that the commands print them and the viewer draws the +//! same thing. The data types are plain values that serialize: `komorebi-recorder` prints one as +//! text ([`crate::report`]) or, with `--json`, inside an envelope whose `schema` names the type. +//! +//! | Question | Asked with | Answered by | Data | Schema | Command | +//! |---|---|---|---|---|---| +//! | What was the state at a moment? | [`StateQuery`] | [`Analysis::state_answer`] | [`StateData`] | [`SCHEMA_STATE`] | `state` | +//! | What changed between two moments? | two times | [`Analysis::diff_answer`] | [`DiffData`] | [`SCHEMA_DIFF`] | `diff` | +//! | What happened? | [`EventQuery`] | [`Analysis::events_answer`] | [`EventsAnswer`], with [`EventsData`] | [`SCHEMA_EVENTS`] | `events` | +//! +//! The types at the end ([`AnnotationData`], [`AnnotationsData`], [`DeletedData`]) are what the +//! `annotate` and `annotations` commands print with `--json`. +//! +//! Times are nanoseconds on the host's master monotonic clock (`*_mach_ns`), which +//! [`Analysis::resolve`] gives for any time the user can type. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::analysis::Analysis; +//! use komorebi_recorder::analysis::answers::{EventQuery, StateQuery}; +//! use komorebi_recorder::testkit::{SessionBuilder, mach_ns, state_with_windows}; +//! use serde_json::json; +//! +//! let (session, _) = SessionBuilder::new("doc-answers") +//! .event(2.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal")]))) +//! .event(4.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal"), (8, "Browser")]))) +//! .build(); +//! let analysis = Analysis::open(&session.dir)?; +//! +//! // what was the state at 3 s: one window +//! let before = analysis.state_answer(mach_ns(3.0), &StateQuery::default())?; +//! assert_eq!(before.workspaces[0].windows, 1); +//! assert_eq!(before.origin.seq, Some(1)); +//! +//! // what changed by 5 s: the browser appeared and the terminal made room +//! let diff = analysis.diff_answer(mach_ns(3.0), mach_ns(5.0))?; +//! assert!(diff.changes.iter().any(|change| change.text.contains("Browser") && change.text.contains("appeared"))); +//! +//! // what happened: both events, or one at a time +//! let all = analysis.events_answer(&EventQuery::default()); +//! assert_eq!((all.data.matching, all.data.total), (2, 2)); +//! let first = analysis.events_answer(&EventQuery { limit: Some(1), ..EventQuery::default() }); +//! assert_eq!(first.next_cursor.as_deref(), Some("1")); +//! # Ok::<(), Box>(()) +//! ``` + +use super::Analysis; +use super::classify::Class; +use super::diff; +use super::diff::Change; +use super::envelope; +use super::facade::StateAt; +use super::facade::StateSource; +use super::invariants; +use super::invariants::Violation; +use super::state::Focus; +use super::state::Location; +use super::state::Monitor; +use super::state::Place; +use super::state::Rect; +use super::state::Snapshot; +use super::state::Window; +use super::views::EventView; +use super::views::Moment; +use super::views::StateOrigin; +use crate::annotations::AnnotationView; +use color_eyre::eyre; +use schemars::JsonSchema; +use serde::Serialize; + +/// The `schema` of the `state` command's output: the name that [`StateData`] has in an envelope. +pub const SCHEMA_STATE: &str = "state/1"; +/// The `schema` of the `diff` command's output: the name that [`DiffData`] has in an envelope. +pub const SCHEMA_DIFF: &str = "diff/1"; +/// The `schema` of the `events` command's output: the name that [`EventsData`] has in an envelope. +pub const SCHEMA_EVENTS: &str = "events/1"; + +/// A window asked about and everything known about where it is. +#[derive(Debug, Clone, Serialize, JsonSchema)] +pub struct WindowMatch { + /// The window, as the state records it. Its `rect` is where it really was when the state was + /// written, not where komorebi's layout put it. + pub window: Window, + /// Which monitor, workspace and place in the workspace it is in. + pub location: Location, + /// Where the layout says this container should be, when it is a tiled window. + /// + /// `None` for a window that is not in a container of the workspace's layout (monocle, maximized + /// or floating, or a workspace with a monocle container) or whose container has no recorded + /// layout rect. + pub layout_rect: Option, + /// Parked off screen the way komorebi hides windows. + /// + /// This is whether the window's real rect is where komorebi parks a window it has hidden on that + /// monitor, which depends on the komorebi that recorded the state: komorebi for Windows hides a + /// window by cloaking it in place, so its position never says. + pub hidden_position: bool, +} + +/// One workspace of one monitor, in a state answer. +#[derive(Debug, Clone, Serialize, JsonSchema)] +pub struct WorkspaceSummary { + /// The monitor (display id) the workspace is on. + pub monitor_id: u64, + /// The workspace's name. + pub name: String, + /// Whether it is the workspace showing on its monitor. + pub showing: bool, + /// How many windows it holds, of every kind: tiled, monocle, maximized and floating. + pub windows: usize, +} + +/// The answer to "what was komorebi's state at this moment", made by [`Analysis::state_answer`]. +#[derive(Debug, Serialize, JsonSchema)] +pub struct StateData { + /// The moment asked about, on every clock. + pub at: Moment, + /// Which notification the state is from, and how old it is at `at`. + pub origin: StateOrigin, + /// What has the keyboard focus. + pub focus: Option, + /// Whether komorebi was paused. + pub paused: bool, + /// The monitors, with only the workspaces asked for (the showing ones by default). + pub monitors: Vec, + /// Every workspace of every monitor, however the monitors and workspaces were filtered. + pub workspaces: Vec, + /// The windows that matched the window asked about (`--window`); empty if none was asked about. + pub matches: Vec, + /// What looks wrong in the state, narrowed to the monitor and windows asked about. + pub violations: Vec, +} + +/// One difference between two states: the sentence a person would say, and the change it says it +/// of. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct ChangeView { + /// The change in words. + pub text: String, + /// The change itself. Its fields are flattened into the same JSON object as `text`. + #[serde(flatten)] + pub change: Change, +} + +/// The answer to "what changed between these two moments", made by [`Analysis::diff_answer`]. +#[derive(Debug, Serialize, JsonSchema)] +pub struct DiffData { + /// The earlier moment, as given. + pub from: Moment, + /// Which notification the state at `from` is from. + pub from_origin: StateOrigin, + /// The later moment, as given. + pub to: Moment, + /// Which notification the state at `to` is from. + pub to_origin: StateOrigin, + /// What differs between the two states. Empty if nothing a person would notice does, which is + /// also the case when both moments fall in the same state. + pub changes: Vec, + /// Violations present at `to` and not at `from`. + pub violations_appeared: Vec, + /// Violations present at `from` and not at `to`. + pub violations_resolved: Vec, +} + +/// The answer to "what happened", made by [`Analysis::events_answer`]: the events that matched, in +/// order, with the counts to tell whether the list is whole. +#[derive(Debug, Serialize, JsonSchema)] +pub struct EventsData { + /// The events returned, in the order they were received. + pub events: Vec, + /// How many events matched the filters, including any not returned because of the limit + /// (`--limit`) or because they come before the cursor (`--cursor`). + pub matching: usize, + /// How many events the session has. + pub total: usize, + /// The name komorebi knew this recorder by. When komorebi logs at DEBUG it names it for each + /// notification pushed, which makes pairing events with handlers exact. + pub subscriber: Option, +} + +/// Which windows, monitors and workspaces a state answer is about. +/// +/// The default asks about nothing in particular: every monitor, the workspaces that are showing, +/// and no window. +#[derive(Debug, Clone, Default)] +pub struct StateQuery { + /// A window id, or text found in a window's application or title (compared without regard to + /// case). The workspaces holding a match are included in the answer even if they are not + /// showing. If nothing matches, [`Analysis::state_answer`] fails. + pub window: Option, + /// Only this monitor (display id) in [`StateData::monitors`] and [`StateData::violations`]. + pub monitor: Option, + /// Include workspaces that are not showing. + pub all: bool, +} + +/// Which events an events answer includes. +/// +/// The default includes every event. A filter is only applied if it is set, and an event must pass +/// all of the filters that are. +#[derive(Debug, Clone, Default)] +pub struct EventQuery { + /// Only events received at or after this time (nanoseconds on the master clock). + pub from_mach_ns: Option, + /// Only events received at or before this time. + pub to_mach_ns: Option, + /// Only events of these classes; empty means any class. + pub classes: Vec, + /// Leave out echoes of komorebi's own moves ([`Class::Echo`]). + pub hide_echo: bool, + /// Only events whose name contains this text, compared without regard to case. + pub name: Option, + /// Only events about this process id. + pub pid: Option, + /// Only events about this window id. + pub window: Option, + /// Most events to return; `None` for all. + pub limit: Option, + /// Only events after this sequence number. + pub after_seq: Option, +} + +/// An events answer and where to continue if it was cut short. +pub struct EventsAnswer { + /// The events and their counts. + pub data: EventsData, + /// Set if [`EventQuery::limit`] cut the answer short: the sequence number of the last event + /// returned, to pass back as [`EventQuery::after_seq`] (the `--cursor` of the `events` command) + /// for the rest. `None` if the answer is whole. + pub next_cursor: Option, +} + +fn matches_window(text: &str, window: &Window) -> bool { + if let Ok(id) = text.parse::() + && window.id == id + { + return true; + } + + let needle = text.to_lowercase(); + window.exe.to_lowercase().contains(&needle) || window.title.to_lowercase().contains(&needle) +} + +impl Analysis { + fn origin(&self, at: &StateAt, asked_mach_ns: u64) -> StateOrigin { + match at.source { + StateSource::Event { seq, recv_mach_ns } => StateOrigin { + source: "event".to_string(), + seq: Some(seq), + state_id: at.state_id, + age_ms: Some(asked_mach_ns.saturating_sub(recv_mach_ns) as f64 / 1e6), + }, + StateSource::Start => StateOrigin { + source: "start".to_string(), + seq: None, + state_id: None, + age_ms: Some( + asked_mach_ns.saturating_sub(self.manifest.start.mach_ns) as f64 / 1e6, + ), + }, + } + } + + /// Returns the state at `mach_ns`, filtered to what `query` asks about, with what looks wrong + /// in it. + /// + /// The state is the one [`Analysis::state_at`] finds, so it is as of the latest notification + /// before `mach_ns`; [`StateData::origin`] names which one and how old it is. + /// + /// # Errors + /// + /// Returns the errors of [`Analysis::state_at`] (no state was recorded before `mach_ns`), and a + /// not-found error if [`StateQuery::window`] is set and no window in the state matches it. + pub fn state_answer(&self, mach_ns: u64, query: &StateQuery) -> eyre::Result { + let found = self.state_at(mach_ns)?; + let snapshot: &Snapshot = &found.snapshot; + + let matches: Vec = match &query.window { + Some(text) => snapshot + .windows() + .into_iter() + .filter(|(_, window)| matches_window(text, window)) + .map(|(location, window)| { + let monitor = snapshot + .monitors + .iter() + .find(|monitor| monitor.id == location.monitor_id); + let layout_rect = monitor + .and_then(|monitor| { + monitor + .workspaces + .iter() + .find(|workspace| workspace.name == location.workspace) + }) + .and_then(|workspace| match location.place { + Place::Container { index, .. } if workspace.monocle.is_none() => { + workspace.layout_rects.get(index).copied() + } + _ => None, + }); + let hidden_position = window + .rect + .as_ref() + .zip(monitor) + .is_some_and(|(rect, monitor)| snapshot.is_hidden_position(rect, monitor)); + WindowMatch { + window: window.clone(), + location, + layout_rect, + hidden_position, + } + }) + .collect(), + None => Vec::new(), + }; + if query.window.is_some() && matches.is_empty() { + return Err(envelope::not_found(format!( + "no window matches '{}' in the state at {}", + query.window.as_deref().unwrap_or_default(), + self.moment(mach_ns).timecode + ))); + } + + let all_windows = snapshot.windows(); + let workspaces: Vec = snapshot + .monitors + .iter() + .flat_map(|monitor| { + let all_windows = &all_windows; + monitor + .workspaces + .iter() + .enumerate() + .map(move |(index, workspace)| WorkspaceSummary { + monitor_id: monitor.id, + name: workspace.name.clone(), + showing: index == monitor.focused, + windows: all_windows + .iter() + .filter(|(location, _)| { + location.monitor_id == monitor.id + && location.workspace == workspace.name + }) + .count(), + }) + }) + .collect(); + + let wanted = |monitor: &Monitor, index: usize, name: &str| { + query.all + || index == monitor.focused + || matches.iter().any(|found| { + found.location.monitor_id == monitor.id && found.location.workspace == name + }) + }; + let monitors: Vec = snapshot + .monitors + .iter() + .filter(|monitor| query.monitor.is_none_or(|id| id == monitor.id)) + .map(|monitor| { + let mut kept = monitor.clone(); + kept.workspaces = monitor + .workspaces + .iter() + .enumerate() + .filter(|(index, workspace)| wanted(monitor, *index, &workspace.name)) + .map(|(_, workspace)| workspace.clone()) + .collect(); + kept + }) + .collect(); + + let mut violations = invariants::check(snapshot); + if let Some(id) = query.monitor { + violations.retain(|violation| violation.monitor_id.is_none_or(|monitor| monitor == id)); + } + if !matches.is_empty() { + violations.retain(|violation| { + violation.window_ids.is_empty() + || violation + .window_ids + .iter() + .any(|id| matches.iter().any(|found| found.window.id == *id)) + }); + } + + Ok(StateData { + at: self.moment(mach_ns), + origin: self.origin(&found, mach_ns), + focus: snapshot.focus(), + paused: snapshot.paused, + monitors, + workspaces, + matches, + violations, + }) + } + + /// Returns what changed between the state at `from_mach_ns` and the state at `to_mach_ns`, in + /// terms a person would use, and which violations appeared or went away. + /// + /// Both states are found as [`Analysis::state_at`] does. The order of the two times is not + /// checked: with `to_mach_ns` before `from_mach_ns` the answer describes the change backwards. + /// The `diff` command refuses that. + /// + /// # Errors + /// + /// Returns the errors of [`Analysis::state_at`] for either moment. + pub fn diff_answer(&self, from_mach_ns: u64, to_mach_ns: u64) -> eyre::Result { + let before = self.state_at(from_mach_ns)?; + let after = self.state_at(to_mach_ns)?; + let changes = diff::diff(&before.snapshot, &after.snapshot); + + let (was, now) = ( + invariants::check(&before.snapshot), + invariants::check(&after.snapshot), + ); + Ok(DiffData { + from: self.moment(from_mach_ns), + from_origin: self.origin(&before, from_mach_ns), + to: self.moment(to_mach_ns), + to_origin: self.origin(&after, to_mach_ns), + changes: changes + .into_iter() + .map(|change| ChangeView { + text: change.describe(), + change, + }) + .collect(), + violations_appeared: now.iter().filter(|v| !was.contains(v)).cloned().collect(), + violations_resolved: was.iter().filter(|v| !now.contains(v)).cloned().collect(), + }) + } + + /// Returns the events matching `query`, in the order they were received. + /// + /// This does not fail: an empty answer means nothing matched. At most [`EventQuery::limit`] + /// events are returned, starting after [`EventQuery::after_seq`]; [`EventsData::matching`] + /// counts the matches before that, and [`EventsAnswer::next_cursor`] gives where to continue. + #[must_use] + pub fn events_answer(&self, query: &EventQuery) -> EventsAnswer { + let all = self.events(); + let needle = query.name.as_deref().map(str::to_lowercase); + let wanted: Vec = (0..all.len()) + .filter(|index| { + let event = &all[*index]; + let class = self.pairing().classes[*index].class; + query + .from_mach_ns + .is_none_or(|from| event.recv_mach_ns >= from) + && query.to_mach_ns.is_none_or(|to| event.recv_mach_ns <= to) + && (query.classes.is_empty() || query.classes.contains(&class)) + && !(query.hide_echo && class == Class::Echo) + && needle + .as_ref() + .is_none_or(|needle| event.info.name.to_lowercase().contains(needle)) + && query.pid.is_none_or(|pid| event.info.pid == Some(pid)) + && query + .window + .is_none_or(|window| event.info.window_id == Some(window)) + }) + .collect(); + + let remaining: Vec = wanted + .iter() + .copied() + .filter(|index| query.after_seq.is_none_or(|after| all[*index].seq > after)) + .collect(); + let count = query + .limit + .map_or(remaining.len(), |limit| limit.min(remaining.len())); + let events: Vec = remaining[..count] + .iter() + .filter_map(|index| self.event_view(*index)) + .collect(); + let next_cursor = (count < remaining.len()) + .then(|| events.last().map(|view| view.seq.to_string())) + .flatten(); + + EventsAnswer { + data: EventsData { + events, + matching: wanted.len(), + total: all.len(), + subscriber: self.pairing().subscriber.clone(), + }, + next_cursor, + } + } +} + +/// `annotate add` / `edit` answer with the annotation as it now reads. +#[derive(Serialize, JsonSchema)] +pub struct AnnotationData { + /// The annotation, read back from the file after the write. + pub annotation: AnnotationView, +} + +/// The answer of `annotate delete`. +#[derive(Serialize, JsonSchema)] +pub struct DeletedData { + /// The id of the annotation that was removed. + pub deleted: String, +} + +/// The answer of `annotations`: the session's annotations, optionally of one kind. +#[derive(Serialize, JsonSchema)] +pub struct AnnotationsData { + /// The annotations, ordered by start and then by id. + pub annotations: Vec, +} diff --git a/komorebi-recorder/src/analysis/invariants.rs b/komorebi-recorder/src/analysis/invariants.rs new file mode 100644 index 00000000..8c33ac0e --- /dev/null +++ b/komorebi-recorder/src/analysis/invariants.rs @@ -0,0 +1,715 @@ +//! Things that should never be true of komorebi's state, and what true state looks like. +//! +//! These are checks on one state taken on its own, so they can be run at any moment of a +//! recording. A violation is evidence, not a verdict: komorebi may be mid-way through a +//! transition, or an application may refuse a size komorebi asked for. Each says what it saw and +//! how sure it is by severity. +//! +//! There are two entry points, which look at different things: +//! +//! - [`check`] reads a [`Snapshot`] alone: the state komorebi reported, including where each +//! window really was when it was serialized. +//! - `check_probed` compares a snapshot with what Windows reported about one window just after +//! an event about it (`record --probe-windows`). +//! +//! `state`, `diff`, `trace` and `brief` call [`check`] on the states they show, and `overview` +//! calls both to find the states that were wrong and for how long. +//! +//! # The checks +//! +//! A violation's [`kind`](Violation::kind) is a stable name. Which flavor of komorebi a check +//! applies to is decided by how that komorebi hides a window: komorebi for Mac parks it in a corner +//! of its monitor, so a window's position shows whether it is hidden; komorebi for Windows cloaks +//! it where it is, so no position does (see [`Snapshot::hides_windows_by_position`]). +//! +//! | kind | severity | what it reports | komorebi for Mac | komorebi for Windows | +//! |---|---|---|---|---| +//! | `window-in-two-places` | error | one window id is in more than one place | [`check`] | [`check`] | +//! | `duplicate-monitor-id` | error | two monitors have the same id | [`check`] | [`check`] | +//! | `focus-out-of-range` | error | a monitor focuses a workspace, or a workspace a container, past the end of its list | [`check`] | [`check`] | +//! | `visible-window-hidden` | error | a window that should be on screen is hidden | [`check`]: parked in the hiding position | `check_probed`: Windows has it cloaked, minimized or not visible | +//! | `monitor-overlap` | warn | two monitors' areas overlap | [`check`] | [`check`] | +//! | `empty-container` | warn | a container holds no windows | [`check`] | [`check`] | +//! | `off-screen` | warn | a window on a showing workspace is where no monitor is | [`check`] | [`check`] | +//! | `layout-mismatch` | warn | a tiled window is not where the last layout put it | [`check`] | [`check`] | +//! | `hidden-window-visible` | warn | a window that should be hidden is on screen | [`check`]: not parked, on a workspace that is not showing | `check_probed`: Windows has it on screen | +//! | `unmanaged-window` | info | a window is on screen and komorebi does not have it | never | `check_probed` | +//! +//! So on a komorebi for Windows state [`check`] never reports `visible-window-hidden` or +//! `hidden-window-visible`, and on a komorebi for Mac state `check_probed` reports nothing: the +//! probe exists only on Windows. Without a probe, nothing can say whether a Windows window is +//! really hidden. + +use super::state::Location; +use super::state::Monitor; +use super::state::Place; +use super::state::Rect; +use super::state::Snapshot; +use super::state::Window; +use schemars::JsonSchema; +use serde::Serialize; +use std::collections::BTreeMap; + +/// How far a window's real rect may be from where the layout put it before it is reported. An +/// application with a minimum size (a terminal snapping to whole rows) is a few points off. +const LAYOUT_TOLERANCE: i64 = 4; + +/// A window on a workspace that is not showing, with more than this share of itself on a display, +/// is leaking through. +const LEAK_SHARE_PERCENT: i64 = 25; + +/// How serious a [`Violation`] is, and how sure it is that something is wrong. +/// +/// The variants are ordered from most to least serious (`Error < Warn < Info`), which is the order +/// [`check`] sorts its result in. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::invariants::Severity; +/// +/// assert!(Severity::Error < Severity::Warn); +/// assert!(Severity::Warn < Severity::Info); +/// ``` +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, JsonSchema)] +#[serde(rename_all = "kebab-case")] +pub enum Severity { + /// The state is wrong in a way that a person would see or that komorebi's bookkeeping should + /// not allow: a window in two places, a window that should be showing and is not. + Error, + /// The state is probably wrong, or is wrong in a way that may be an application's doing: a + /// tiled window off from its layout, a window where no monitor is. + Warn, + /// Worth knowing and not a fault in itself: a window komorebi does not manage. + Info, +} + +/// One thing wrong with a state, with the windows and place it is about. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)] +pub struct Violation { + /// Stable name of the check, e.g. `visible-window-hidden`. The kinds are listed in the + /// [module](self) documentation. + pub kind: String, + /// How serious it is. + pub severity: Severity, + /// A sentence saying what was seen, naming the windows and where they are. Two violations are + /// equal only if their messages are, so a problem whose numbers change reads as a different + /// violation. + pub message: String, + /// The ids of the windows it is about; empty for a problem with monitors or workspaces. + pub window_ids: Vec, + /// The display id of the monitor it is about, if it is about one. + pub monitor_id: Option, + /// The name of the workspace it is about, if it is about one. + pub workspace: Option, +} + +fn violation( + kind: &str, + severity: Severity, + message: String, + window_ids: Vec, + location: Option<&Location>, +) -> Violation { + Violation { + kind: kind.to_string(), + severity, + message, + window_ids, + monitor_id: location.map(|location| location.monitor_id), + workspace: location.map(|location| location.workspace.clone()), + } +} + +/// `found` with the monitor and workspace it is about filled in. +fn about(mut found: Violation, monitor_id: u64, workspace: Option<&str>) -> Violation { + found.monitor_id = Some(monitor_id); + found.workspace = workspace.map(str::to_string); + found +} + +fn name(window: &Window) -> String { + format!("{} \"{}\" (window {})", window.exe, window.title, window.id) +} + +/// Checks one state and returns every violation found, most serious first. +/// +/// The result is sorted by severity and then by kind, so errors come before warnings, and is empty +/// for a state with nothing wrong. Which checks apply to which flavor is in the [module](self) +/// documentation: on a komorebi for Windows state the position-based checks of hidden windows do +/// not run, because that state cannot show whether a window is hidden (use `check_probed` +/// for that). +/// +/// What is checked: +/// +/// - the same window in more than one place; +/// - two monitors with one id, or whose areas overlap; +/// - a focus index past the end of what it indexes, for monitors and for workspaces; +/// - a container with no windows; +/// - for every window that has a rect, on a workspace that is showing: parked in komorebi's hiding +/// position (`visible-window-hidden`, in any kind of place), else on no monitor +/// (`off-screen`); +/// - for every window on a workspace that is not showing, where windows are hidden by position: +/// not parked, and with at least 25% of its area on its monitor (`hidden-window-visible`); +/// - for the focused workspace of each monitor, if it is tiling and not monocle, maximized or on +/// the floating layer: a focused window more than 4 points from where the last layout put its +/// container, in any of left, top, width and height (`layout-mismatch`). The few points of slack +/// are for an application with a minimum size, such as a terminal snapping to whole rows. +/// +/// A window with no rect, or whose monitor is not in the state, is skipped by the position checks. +/// The function does not fail or panic. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::flavor::Flavor; +/// use komorebi_recorder::analysis::invariants::Severity; +/// use komorebi_recorder::analysis::invariants::check; +/// use komorebi_recorder::analysis::state::Snapshot; +/// use komorebi_recorder::testkit::container; +/// use komorebi_recorder::testkit::monitor; +/// use komorebi_recorder::testkit::state; +/// use komorebi_recorder::testkit::window; +/// use komorebi_recorder::testkit::workspace; +/// +/// // One window fills the only workspace of a 1000x800 monitor, but it is parked in the sliver at +/// // the bottom left, where komorebi for Mac puts a window it has hidden. +/// let layout = [[0, 0, 1000, 800]]; +/// let parked = window(1, "Ghostty", Some([-999, 790, 1000, 800])); +/// let screen = monitor( +/// 1, +/// [0, 0, 1000, 800], +/// vec![workspace("one", vec![container("a", vec![parked])], 0, &layout)], +/// 0, +/// ); +/// let snapshot = Snapshot::parse(Flavor::Macos, &state(vec![screen], 0)); +/// +/// let found = check(&snapshot); +/// assert_eq!(found.len(), 1); +/// assert_eq!(found[0].kind, "visible-window-hidden"); +/// assert_eq!(found[0].severity, Severity::Error); +/// assert_eq!(found[0].window_ids, [1]); +/// assert_eq!(found[0].monitor_id, Some(1)); +/// ``` +/// +/// Every kind that [`check`] reports has a unit test in this module, named after it +/// (`a_window_on_the_showing_workspace_parked_off_screen_is_an_error`, +/// `a_tiled_window_that_is_not_where_the_layout_put_it_is_a_mismatch`, ...). +#[must_use] +pub fn check(snapshot: &Snapshot) -> Vec { + let mut found = Vec::new(); + let windows = snapshot.windows(); + + // the same window in two places + let mut places: BTreeMap> = BTreeMap::new(); + for (location, window) in &windows { + places.entry(window.id).or_default().push(location); + } + for (id, locations) in &places { + if locations.len() > 1 { + let described: Vec = locations + .iter() + .map(|location| location.describe()) + .collect(); + found.push(violation( + "window-in-two-places", + Severity::Error, + format!( + "window {id} is in {} places: {}", + locations.len(), + described.join("; ") + ), + vec![*id], + locations.first().copied(), + )); + } + } + + // monitors that overlap or share an id + for (index, monitor) in snapshot.monitors.iter().enumerate() { + for other in &snapshot.monitors[index + 1..] { + if monitor.id == other.id { + found.push(violation( + "duplicate-monitor-id", + Severity::Error, + format!("two monitors have the id {}", monitor.id), + vec![], + None, + )); + } else if monitor.size.overlap_area(&other.size) > 0 { + found.push(violation( + "monitor-overlap", + Severity::Warn, + format!( + "monitor {} ({}) and monitor {} ({}) overlap", + monitor.id, + monitor.size.describe(), + other.id, + other.size.describe() + ), + vec![], + None, + )); + } + } + + // a focus that points past the end of what it focuses + if monitor.focused >= monitor.workspaces.len() && !monitor.workspaces.is_empty() { + found.push(about( + violation( + "focus-out-of-range", + Severity::Error, + format!( + "monitor {} focuses workspace {} of {}", + monitor.id, + monitor.focused, + monitor.workspaces.len() + ), + vec![], + None, + ), + monitor.id, + None, + )); + } + for workspace in &monitor.workspaces { + if workspace.focused >= workspace.containers.len() && !workspace.containers.is_empty() { + found.push(about( + violation( + "focus-out-of-range", + Severity::Error, + format!( + "monitor {} workspace {} focuses container {} of {}", + monitor.id, + workspace.name, + workspace.focused, + workspace.containers.len() + ), + vec![], + None, + ), + monitor.id, + Some(&workspace.name), + )); + } + for container in &workspace.containers { + if container.windows.is_empty() { + found.push(about( + violation( + "empty-container", + Severity::Warn, + format!( + "monitor {} workspace {} has an empty container {}", + monitor.id, workspace.name, container.id + ), + vec![], + None, + ), + monitor.id, + Some(&workspace.name), + )); + } + } + } + } + + let monitor_of = |id: u64| snapshot.monitors.iter().find(|monitor| monitor.id == id); + + for (location, window) in &windows { + let (Some(rect), Some(monitor)) = (&window.rect, monitor_of(location.monitor_id)) else { + continue; + }; + let hidden = snapshot.is_hidden_position(rect, monitor); + + if location.workspace_visible { + // on a workspace that is showing, so it should be on screen + if hidden { + found.push(violation( + "visible-window-hidden", + Severity::Error, + format!( + "{} is on {} which is showing, but it is parked off screen at {}", + name(window), + location.describe(), + rect.describe() + ), + vec![window.id], + Some(location), + )); + } else if snapshot + .monitors + .iter() + .all(|monitor| monitor.size.overlap_area(rect) == 0) + { + found.push(violation( + "off-screen", + Severity::Warn, + format!( + "{} is on {} but at {} which is on no display", + name(window), + location.describe(), + rect.describe() + ), + vec![window.id], + Some(location), + )); + } + } else if snapshot.hides_windows_by_position() + && !hidden + && rect.area() > 0 + && leaks(rect, monitor) + { + found.push(violation( + "hidden-window-visible", + Severity::Warn, + format!( + "{} is on {} which is not showing, but it is on screen at {}", + name(window), + location.describe(), + rect.describe() + ), + vec![window.id], + Some(location), + )); + } + } + + // tiled windows that are not where the layout put them + for monitor in &snapshot.monitors { + let Some(workspace) = monitor.focused_workspace() else { + continue; + }; + if !workspace.tiling + || workspace.layer == "Floating" + || workspace.monocle.is_some() + || workspace.maximized.is_some() + { + continue; + } + + for (index, container) in workspace.containers.iter().enumerate() { + let (Some(expected), Some(window)) = ( + workspace.layout_rects.get(index), + container.focused_window(), + ) else { + continue; + }; + let Some(actual) = &window.rect else { + continue; + }; + if snapshot.is_hidden_position(actual, monitor) { + // reported as visible-window-hidden + continue; + } + + let delta = expected.max_delta(actual); + if delta > LAYOUT_TOLERANCE { + let location = Location { + monitor_id: monitor.id, + workspace: workspace.name.clone(), + place: Place::Container { + index, + tab: container.focused, + }, + workspace_visible: true, + }; + found.push(violation( + "layout-mismatch", + Severity::Warn, + format!( + "{} is at {} but the layout put container {index} at {} ({delta} points off)", + name(window), + actual.describe(), + expected.describe() + ), + vec![window.id], + Some(&location), + )); + } + } + } + + found.sort_by(|a, b| (a.severity, &a.kind).cmp(&(b.severity, &b.kind))); + found +} + +/// Whether enough of `rect` is on `monitor` for the window to be seen. +fn leaks(rect: &Rect, monitor: &Monitor) -> bool { + let overlap = monitor.size.overlap_area(rect); + rect.area() > 0 && overlap * 100 / rect.area() >= LEAK_SHARE_PERCENT +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testkit::container; + use crate::testkit::monitor; + use crate::testkit::state; + use crate::testkit::window; + use crate::testkit::workspace; + + fn snapshot(monitors: Vec) -> Snapshot { + Snapshot::from_value(&state(monitors, 0)) + } + + fn kinds(violations: &[Violation]) -> Vec<&str> { + violations + .iter() + .map(|violation| violation.kind.as_str()) + .collect() + } + + const SCREEN: [i64; 4] = [0, 0, 1000, 800]; + + #[test] + fn a_tidy_state_has_no_violations() { + let layout = [[0, 0, 500, 800], [500, 0, 500, 800]]; + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![ + container("a", vec![window(1, "x", Some(layout[0]))]), + container("b", vec![window(2, "y", Some(layout[1]))]), + ], + 0, + &layout, + )], + 0, + )]); + + assert_eq!(check(&state), []); + } + + #[test] + fn a_window_on_the_showing_workspace_parked_off_screen_is_an_error() { + let layout = [[0, 0, 1000, 800]]; + // right edge one point inside the monitor: the bottom-left hiding sliver + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![container( + "a", + vec![window(1, "x", Some([-999, 790, 1000, 800]))], + )], + 0, + &layout, + )], + 0, + )]); + + let found = check(&state); + assert_eq!(kinds(&found), ["visible-window-hidden"]); + assert_eq!(found[0].severity, Severity::Error); + assert_eq!(found[0].window_ids, [1]); + assert_eq!(found[0].monitor_id, Some(1)); + } + + #[test] + fn a_window_on_a_workspace_that_is_not_showing_but_on_screen_is_leaking() { + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![ + workspace("one", vec![], 0, &[]), + workspace( + "two", + vec![container( + "a", + vec![window(1, "x", Some([100, 100, 500, 500]))], + )], + 0, + &[], + ), + ], + 0, + )]); + + let found = check(&state); + assert_eq!(kinds(&found), ["hidden-window-visible"]); + assert_eq!(found[0].workspace.as_deref(), Some("two")); + } + + #[test] + fn a_hidden_window_on_a_hidden_workspace_is_fine() { + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![ + workspace("one", vec![], 0, &[]), + workspace( + "two", + vec![container( + "a", + vec![window(1, "x", Some([-499, 790, 500, 800]))], + )], + 0, + &[], + ), + ], + 0, + )]); + + assert_eq!(check(&state), []); + } + + #[test] + fn a_tiled_window_that_is_not_where_the_layout_put_it_is_a_mismatch() { + let layout = [[0, 0, 500, 800], [500, 0, 500, 800]]; + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![ + container("a", vec![window(1, "x", Some(layout[0]))]), + // 120 points narrower than asked + container("b", vec![window(2, "y", Some([500, 0, 380, 800]))]), + ], + 0, + &layout, + )], + 0, + )]); + + let found = check(&state); + assert_eq!(kinds(&found), ["layout-mismatch"]); + assert_eq!(found[0].window_ids, [2]); + assert!( + found[0].message.contains("120 points off"), + "{}", + found[0].message + ); + + // a few points of slack is not a mismatch + let close = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![container( + "b", + vec![window(2, "y", Some([502, 0, 497, 800]))], + )], + 0, + &[[500, 0, 500, 800]], + )], + 0, + )]); + assert_eq!(check(&close), []); + } + + #[test] + fn a_visible_window_on_no_display_is_off_screen() { + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![container( + "a", + vec![window(1, "x", Some([5000, 5000, 500, 500]))], + )], + 0, + &[], + )], + 0, + )]); + + assert_eq!(kinds(&check(&state)), ["off-screen"]); + } + + #[test] + fn the_same_window_in_two_containers_is_an_error() { + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![ + container("a", vec![window(1, "x", None)]), + container("b", vec![window(1, "x", None)]), + ], + 0, + &[], + )], + 0, + )]); + + let found = check(&state); + assert_eq!(kinds(&found), ["window-in-two-places"]); + assert!(found[0].message.contains("2 places")); + } + + #[test] + fn overlapping_monitors_and_broken_focus_are_reported() { + let overlapping = snapshot(vec![ + monitor(1, [0, 0, 1000, 800], vec![], 0), + monitor(2, [500, 0, 1000, 800], vec![], 0), + ]); + assert_eq!(kinds(&check(&overlapping)), ["monitor-overlap"]); + + let duplicate = snapshot(vec![ + monitor(1, [0, 0, 100, 100], vec![], 0), + monitor(1, [100, 0, 100, 100], vec![], 0), + ]); + assert_eq!(kinds(&check(&duplicate)), ["duplicate-monitor-id"]); + + let broken = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![container("a", vec![window(1, "x", None)])], + 5, + &[], + )], + 3, + )]); + assert_eq!( + kinds(&check(&broken)), + ["focus-out-of-range", "focus-out-of-range"] + ); + } + + #[test] + fn errors_sort_before_warnings() { + let state = snapshot(vec![monitor( + 1, + SCREEN, + vec![workspace( + "one", + vec![ + container("a", vec![]), + container("b", vec![window(1, "x", Some([-999, 790, 1000, 800]))]), + ], + 0, + &[], + )], + 0, + )]); + + let found = check(&state); + assert_eq!(kinds(&found), ["visible-window-hidden", "empty-container"]); + } + + #[test] + fn a_real_state_is_checked_without_inventing_problems() { + let value: serde_json::Value = + serde_json::from_str(include_str!("../../tests/fixtures/state.json")).expect("fixture"); + let found = check(&Snapshot::from_value(&value)); + eprintln!("{found:#?}"); + + // every window on a workspace that is not showing is parked, and the showing ones sit + // where the layout put them + assert!( + found + .iter() + .all(|violation| violation.severity != Severity::Error), + "{found:#?}" + ); + } +} diff --git a/komorebi-recorder/src/analysis/mod.rs b/komorebi-recorder/src/analysis/mod.rs index 74b8483a..cff2aa93 100644 --- a/komorebi-recorder/src/analysis/mod.rs +++ b/komorebi-recorder/src/analysis/mod.rs @@ -6,6 +6,7 @@ //! ([`envelope`]), how a point in time is named ([`timespec`], [`ids`]) and the guard that keeps //! file access inside the session ([`guard`]). +pub mod answers; pub mod blocks; pub mod catalog; pub mod classify; @@ -18,10 +19,13 @@ pub mod flavor; pub mod guard; pub mod history; pub mod ids; +pub mod invariants; pub mod logparse; pub mod lookup; +pub mod overview; pub mod state; pub mod timespec; +pub mod trace; pub mod views; pub use facade::Analysis; diff --git a/komorebi-recorder/src/analysis/overview.rs b/komorebi-recorder/src/analysis/overview.rs new file mode 100644 index 00000000..398ec45c --- /dev/null +++ b/komorebi-recorder/src/analysis/overview.rs @@ -0,0 +1,1083 @@ +//! The things that stand out in a recording, ranked by how likely they are to matter. +//! +//! A session holds thousands of events and log lines, nearly all of them ordinary. This looks for +//! the things that are not: states that are wrong and for how long, windows that flap, bursts of +//! events, slow handlers, errors, and what happened to the machine (a display unplugged, a sleep). +//! Each is a [`Finding`] with the event or log line to look at next. Findings that overlap, or come +//! just before, a region the user marked as the bug rank first. +//! +//! [`Analysis::overview`] is what the `overview` command prints, and `brief` starts from the same +//! findings. [`Analysis::findings`] runs the detectors and [`Analysis::rank`] orders what they +//! found. +//! +//! # What is looked for +//! +//! Each detector has fixed thresholds, listed here so that an absent finding can be read as "none +//! of these happened", not "nothing was wrong": +//! +//! | `kind` | what it is | severity | +//! |---|---|---| +//! | `invariant:` | a violation found by [`invariants::check`] in the recorded states (`invariants::check_probed` for a recording made with `--probe-windows`), from the first state that has it to the first that does not, or to the end of the recording | the violation's own; one that was gone again within 0.5 s (for the probe's findings: seen at a single probe and gone at the window's next) is a transition in progress and is lowered one step (error to warn, anything else to info) | +//! | `window-flapping` | one window's hidden state flipping (parked in komorebi's hiding position, or brought back) at least 4 times within 10 s | warn | +//! | `focus-oscillation` | focus changing at least 4 times within 5 s between at most two windows | warn | +//! | `event-storm` | 20 or more events within 1 s | warn for 60 or more, else info | +//! | `slow-handler` | a handler that took at least 250 ms from its header to its notification: the 10 slowest | warn for 1 s or more, else info | +//! | `monitor-churn` | two or more display notifications, each within 5 s of the first | warn | +//! | `log-error`, `log-warning` | komorebi log lines at `ERROR` or `WARN`: one finding for each module and message, where messages that differ only in digits are the same | warn for `log-error`, info for `log-warning` | +//! | `incident:` | something the recorder noted about the machine: a display plugged or unplugged, a sleep, a capture that failed | warn for `capture-failed`, `log-stream-lost` and `komorebi-exited`, else info | +//! +//! The same violation across several consecutive states is one finding giving how long it lasted, +//! not one per event. A violation is told apart from another by its kind, the windows, +//! monitor and workspace it is about. +//! +//! # Flavor +//! +//! The state detectors read what the komorebi of the recorded flavor reported (see +//! [`super::invariants`]). komorebi for Windows hides a window without moving it, so for a Windows +//! session `window-flapping` never fires and the hidden-window violations come only from the probe: +//! without `--probe-windows` the overview reports nothing about whether a window is really hidden, +//! and that is not the same as nothing being wrong. The probe's findings are made by +//! `analysis::probed`. The other detectors do not depend on the flavor, except that the cause named +//! in a `slow-handler` finding is the flavor's own +//! ([`Rules::slow_handler_cause`](super::flavor::Rules::slow_handler_cause)). + +use super::Analysis; +use super::classify::Class; +use super::events::Family; +use super::invariants; +use super::invariants::Severity; +use super::logparse::Level; +use crate::annotations::Annotation; +use crate::annotations::Kind; +use crate::incidents::INCIDENTS_FILE; +use crate::incidents::Incident; +use crate::timecode; +use color_eyre::eyre; +use schemars::JsonSchema; +use serde::Serialize; +use std::collections::BTreeMap; +use std::collections::BTreeSet; +use std::collections::HashMap; + +/// The schema name that identifies an [`OverviewData`] in an envelope (`overview/1`); listed by +/// the `schema` command. +pub const SCHEMA_OVERVIEW: &str = "overview/1"; + +/// How long before a bug region starts a finding still counts as a possible cause, in +/// nanoseconds: 10 s. [`Analysis::rank`] gives such a finding a lower boost than one inside the +/// region. +pub const PRE_ROLL_NS: u64 = 10_000_000_000; + +/// Something in the recording that is worth looking at, with where to look. +/// +/// What is looked for, and with which thresholds, is in the [module](self) documentation. A +/// finding is evidence, not a conclusion: a violation can be a state komorebi was in the middle of +/// leaving, and a burst of events can be a burst of echoes. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Finding { + /// `invariant:` (including the ones read from Windows' own account of a window when the + /// recording was made with `--probe-windows`), `window-flapping`, `focus-oscillation`, + /// `event-storm`, `slow-handler`, `log-error`, `log-warning`, `monitor-churn` or + /// `incident:`. + pub kind: String, + /// How serious it is. For an `invariant:` finding it is the violation's, lowered one step if it + /// did not last. + pub severity: Severity, + /// Higher is more worth looking at. `0` until [`Analysis::rank`] has scored the finding. + pub score: i64, + /// A sentence saying what was seen and, where that applies, for how long. + pub summary: String, + /// When it began, in seconds of video time. + pub start_video_s: f64, + /// When it ended, in seconds of video time; the same as `start_video_s` for a single moment. + pub end_video_s: f64, + /// When it began, in nanoseconds on the host's master monotonic clock. + pub start_mach_ns: u64, + /// When it ended, in nanoseconds on the host's master monotonic clock. + pub end_mach_ns: u64, + /// References to look at: `event:12`, `log:345`, `incident:2`. For a state that was wrong, + /// the event whose state first showed it. + pub refs: Vec, + /// The ids of the windows it is about, if it is about any. + pub window_ids: Vec, + /// Still the case when the recording ended. + pub persisted_to_end: bool, + /// The ids of the bug regions it overlaps, or comes within the pre-roll ([`PRE_ROLL_NS`]) + /// before. + pub bugs: Vec, + /// A command that digs into it, ready to run. `None` for an incident. + pub next: Option, +} + +/// An incident the recorder noted about the machine, such as a display being unplugged. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct IncidentView { + /// `incident:`: the incident's position in the session's incidents (`recorder.jsonl`), + /// counting from 1. + pub number: u64, + /// When it happened, in seconds of video time. + pub video_s: f64, + /// The kind of incident, e.g. `display-disconnected`. + pub kind: String, + /// A sentence saying what the recorder saw. + pub detail: String, + /// The display it is about, if it is about one. + pub display: Option, +} + +/// One display that was recorded. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct DisplayInfo { + /// The display id, the same number as the `--display` of the recording. + pub id: u32, + /// The width of the display's video in pixels, in its first segment. + pub width_px: usize, + /// The height of the display's video in pixels, in its first segment. + pub height_px: usize, + /// How many video files the display has: a display that was unplugged or slept and came back + /// starts a new one. + pub segments: usize, +} + +/// The facts about a session an investigator wants before anything else. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct SessionInfo { + /// The session directory. + pub dir: String, + /// `recording`, `complete` or `recovered`. + pub status: String, + /// When the recording started, as an RFC 3339 UTC time. + pub started_utc: Option, + /// Seconds of video: the span findings and bug regions are placed in. + pub duration_s: f64, + /// The version of the recorder that made the session. + pub recorder_version: String, + /// The macOS version, when the session was recorded on a Mac. See `host` for any OS. + pub macos_version: Option, + /// The host the session was recorded on. + pub host: crate::platform::Host, + /// The displays that were recorded, by id. + pub displays: Vec, + /// The komorebi that was running, as its binary reported: `version branch commit`, with the + /// commit shortened to 10 characters. + pub komorebi: Vec, + /// The level komorebi was logging at, if the recorder saw it. + pub komorebi_log_level: Option, + /// How many komorebi notifications were recorded. + pub events: usize, + /// How many lines komorebi's log has. + pub log_lines: usize, + /// How many incidents were recorded. + pub incidents: usize, + /// `host-clock` if the video's frame timestamps were verified to be on the same clock as the + /// logs, `unverified` if not (then the alignment of video and logs is unreliable). + pub sync_quality: String, + /// Things the recorder said went wrong while recording. + pub warnings: Vec, +} + +/// A slice of the recording and how much happened in it, for drawing a picture of the whole. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Bucket { + /// Where the slice starts, in seconds of video time. + pub start_s: f64, + /// Where the slice ends, in seconds of video time. + pub end_s: f64, + /// How many komorebi events were received in it. + pub events: usize, + /// Events that are not echoes of komorebi's own moves. + pub real_events: usize, + /// How many `ERROR` lines komorebi logged in it. + pub log_errors: usize, + /// How many `WARN` lines komorebi logged in it. + pub log_warnings: usize, + /// How many incidents happened in it. + pub incidents: usize, +} + +/// The whole recording at a glance: the `data` of the `overview` command. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct OverviewData { + /// The facts about the session. + pub session: SessionInfo, + /// The regions the user marked, verbatim. + pub bugs: Vec, + /// Ranked, most worth looking at first. At most the limit asked for. + pub findings: Vec, + /// How many findings there were, including any left out by the limit. + pub findings_total: usize, + /// How much happened over the recording, in 60 buckets (fewer for a very short recording). + pub histogram: Vec, + /// Everything that happened to the machine: displays, sleep, lock, restarts. + pub incidents: Vec, +} + +impl Analysis { + /// Returns the whole recording at a glance: the session's facts, the findings ranked, a + /// histogram and the incidents. + /// + /// The findings are those of [`Analysis::findings`] ranked by [`Analysis::rank`] against the + /// bug regions the user marked ([`Analysis::bugs`]). `limit` cuts the list after that many; + /// [`OverviewData::findings_total`] still counts all of them. + /// + /// # Errors + /// + /// Returns an error if the annotations file cannot be read, or if a recorded state cannot be + /// read (see [`Analysis::findings`]). + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::analysis::Analysis; + /// use komorebi_recorder::testkit::SessionBuilder; + /// use komorebi_recorder::testkit::container; + /// use komorebi_recorder::testkit::monitor; + /// use komorebi_recorder::testkit::state; + /// use komorebi_recorder::testkit::window; + /// use komorebi_recorder::testkit::workspace; + /// use serde_json::json; + /// + /// // The only window of the only workspace is parked in komorebi's hiding position, so + /// // nothing is on screen although komorebi says it should be. + /// let layout = [[0, 0, 1000, 800]]; + /// let parked = window(1, "Ghostty", Some([-999, 790, 1000, 800])); + /// let screen = monitor( + /// 1, + /// [0, 0, 1000, 800], + /// vec![workspace("one", vec![container("a", vec![parked])], 0, &layout)], + /// 0, + /// ); + /// let (session, _) = SessionBuilder::new("doc-overview") + /// .event(2.0, json!({"type": "Retile"}), Some(state(vec![screen], 0))) + /// .build(); + /// let analysis = Analysis::open(&session.dir)?; + /// + /// let overview = analysis.overview(None)?; + /// assert_eq!(overview.session.events, 1); + /// assert_eq!(overview.findings_total, 1); + /// + /// let finding = &overview.findings[0]; + /// assert_eq!(finding.kind, "invariant:visible-window-hidden"); + /// assert_eq!(finding.refs, ["event:1"]); + /// // nothing changed it before the recording ended + /// assert!(finding.persisted_to_end); + /// # Ok::<(), Box>(()) + /// ``` + /// + /// Ranking against a bug region is covered by + /// `tests/brief.rs::findings_in_the_bug_region_rank_above_the_rest`, and the findings of a + /// Windows session by + /// `tests/windows_flavor.rs::a_window_komorebi_shows_that_windows_cloaked_is_a_finding_in_the_overview`. + pub fn overview(&self, limit: Option) -> eyre::Result { + let bugs = self.bugs()?; + let refs: Vec<&Annotation> = bugs.iter().collect(); + let ranked = self.rank(self.findings()?, &refs); + let total = ranked.len(); + + Ok(OverviewData { + session: self.session_info(), + bugs: bugs.iter().map(|bug| bug.view(&self.manifest)).collect(), + findings: ranked + .into_iter() + .take(limit.unwrap_or(usize::MAX)) + .collect(), + findings_total: total, + histogram: self.histogram(60), + incidents: self.incidents(), + }) + } + + /// Returns what happened to the recording environment: displays, sleep, lock, restarts, in + /// the order they were recorded. + /// + /// A session that recorded no incidents has none to return, which is not an error. Each is + /// numbered by its line in `recorder.jsonl` (so `incident:2` is the second line), and a line + /// that cannot be read is skipped, leaving a gap in the numbers. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::analysis::Analysis; + /// use komorebi_recorder::testkit::SessionBuilder; + /// + /// let (session, _) = SessionBuilder::new("doc-incidents") + /// .incident(3.0, "display-disconnected", "display 2 was unplugged") + /// .build(); + /// let analysis = Analysis::open(&session.dir)?; + /// + /// let incidents = analysis.incidents(); + /// assert_eq!(incidents.len(), 1); + /// assert_eq!(incidents[0].number, 1); + /// assert_eq!(incidents[0].kind, "display-disconnected"); + /// assert!((incidents[0].video_s - 3.0).abs() < 1e-6); + /// # Ok::<(), Box>(()) + /// ``` + #[must_use] + pub fn incidents(&self) -> Vec { + let Ok(text) = std::fs::read_to_string(self.session.path(INCIDENTS_FILE)) else { + return Vec::new(); + }; + + text.lines() + .enumerate() + .filter_map(|(index, line)| { + let incident: Incident = serde_json::from_str(line).ok()?; + Some(IncidentView { + number: index as u64 + 1, + video_s: self.video_s(incident.mach_ns), + kind: incident.kind, + detail: incident.detail, + display: incident.display, + }) + }) + .collect() + } + + /// Returns the facts about the session an investigator wants before anything else. + /// + /// This reads the manifest, and counts the events, the log lines and the incidents, so the + /// events and the log are parsed if nothing has asked for them yet. It cannot fail: what is + /// missing is empty or `None`. + #[must_use] + pub fn session_info(&self) -> SessionInfo { + let manifest = &self.manifest; + let mut displays: BTreeMap = BTreeMap::new(); + for entry in &manifest.displays { + let info = displays + .entry(entry.result.display.id) + .or_insert(DisplayInfo { + id: entry.result.display.id, + width_px: entry.result.width_px, + height_px: entry.result.height_px, + segments: 0, + }); + info.segments += 1; + } + + SessionInfo { + dir: self.session.dir.display().to_string(), + status: manifest.status.clone(), + started_utc: crate::timeline::format_wall_us(manifest.start.wall_us), + duration_s: manifest.video_span().1, + recorder_version: manifest.recorder_version.clone(), + macos_version: manifest.macos_version.clone(), + host: manifest.host(), + displays: displays.into_values().collect(), + komorebi: manifest + .komorebi + .versions + .iter() + .map(|version| { + format!( + "{} {} {}", + version.version, + version.branch.as_deref().unwrap_or(""), + version + .commit + .as_deref() + .map_or("", |commit| &commit[..commit.len().min(10)]) + ) + .trim() + .to_string() + }) + .collect(), + komorebi_log_level: manifest + .komorebi + .log_level + .as_ref() + .map(|level| level.level.clone()), + events: self.events().len(), + log_lines: self.log().lines.len(), + incidents: self.incidents().len(), + sync_quality: manifest.sync_quality.clone(), + warnings: manifest.warnings.clone(), + } + } + + /// Returns everything the detectors found, in time order and unranked. Use + /// [`Analysis::rank`] to order them by how much they matter. + /// + /// Findings are sorted by start time and then by kind. Each state is read from the session + /// once, however many events carried it. What is looked for is in the [module](self) + /// documentation. + /// + /// # Errors + /// + /// Returns an error if a recorded state cannot be read: its file is missing (not found) or is + /// not valid JSON. + pub fn findings(&self) -> eyre::Result> { + let mut found = Vec::new(); + self.find_state_problems(&mut found)?; + self.find_event_problems(&mut found); + self.find_log_problems(&mut found); + self.find_incidents(&mut found); + found.sort_by_key(|finding| (finding.start_mach_ns, finding.kind.clone())); + Ok(found) + } + + pub(super) fn finding( + &self, + kind: &str, + severity: Severity, + summary: String, + start_mach_ns: u64, + end_mach_ns: u64, + ) -> Finding { + Finding { + kind: kind.to_string(), + severity, + score: 0, + summary, + start_video_s: self.video_s(start_mach_ns), + end_video_s: self.video_s(end_mach_ns.max(start_mach_ns)), + start_mach_ns, + end_mach_ns: end_mach_ns.max(start_mach_ns), + refs: Vec::new(), + window_ids: Vec::new(), + persisted_to_end: false, + bugs: Vec::new(), + next: None, + } + } + + /// The end of the recording on the master clock. + fn session_end_ns(&self) -> u64 { + crate::analysis::timespec::session_end_ns(&self.manifest) + } + + fn find_state_problems(&self, found: &mut Vec) -> eyre::Result<()> { + let end = self.session_end_ns(); + let dir = self.session.dir.display().to_string(); + + // violations: when each appeared and when it went away + type Key = (String, Vec, Option, Option); + struct Open { + violation: invariants::Violation, + start_ns: u64, + seq: u64, + } + let mut open: HashMap = HashMap::new(); + let mut closed: Vec<(Open, u64)> = Vec::new(); + + // windows' hidden flags and focus, to find flapping and oscillation + let mut hidden_before: HashMap = HashMap::new(); + let mut flips: HashMap> = HashMap::new(); + let mut exes: HashMap = HashMap::new(); + let mut focus_series: Vec<(u64, u64, Option)> = Vec::new(); + + let mut last_state_id = None; + for event in self.events() { + let Some(state_id) = event.state_id else { + continue; + }; + if last_state_id == Some(state_id) { + continue; + } + last_state_id = Some(state_id); + let snapshot = self.snapshot(state_id)?; + + let violations = invariants::check(&snapshot); + let mut current: HashMap = HashMap::new(); + for violation in violations { + let mut ids = violation.window_ids.clone(); + ids.sort_unstable(); + let key = ( + violation.kind.clone(), + ids, + violation.monitor_id, + violation.workspace.clone(), + ); + current.entry(key).or_insert(violation); + } + + let gone: Vec = open + .keys() + .filter(|key| !current.contains_key(*key)) + .cloned() + .collect(); + for key in gone { + if let Some(opened) = open.remove(&key) { + closed.push((opened, event.recv_mach_ns)); + } + } + for (key, violation) in current { + open.entry(key).or_insert(Open { + violation, + start_ns: event.recv_mach_ns, + seq: event.seq, + }); + } + + for (location, window) in snapshot.windows() { + exes.entry(window.id).or_insert_with(|| window.exe.clone()); + let hidden = window.rect.as_ref().is_some_and(|rect| { + snapshot + .monitors + .iter() + .find(|monitor| monitor.id == location.monitor_id) + .is_some_and(|monitor| snapshot.is_hidden_position(rect, monitor)) + }); + if let Some(before) = hidden_before.insert(window.id, hidden) + && before != hidden + { + flips + .entry(window.id) + .or_default() + .push((event.recv_mach_ns, event.seq)); + } + } + focus_series.push(( + event.recv_mach_ns, + event.seq, + snapshot.focus().and_then(|focus| focus.window_id), + )); + } + + let mut push_violation = |opened: Open, ended: Option| { + let persisted = ended.is_none(); + let end_ns = ended.unwrap_or(end); + let lasted = end_ns.saturating_sub(opened.start_ns); + // a state that was only wrong for an instant is usually a transition in progress + let severity = if !persisted && lasted < 500_000_000 { + match opened.violation.severity { + Severity::Error => Severity::Warn, + _ => Severity::Info, + } + } else { + opened.violation.severity + }; + + let mut finding = self.finding( + &format!("invariant:{}", opened.violation.kind), + severity, + format!( + "{}{}", + opened.violation.message, + if persisted { + ", and it was still so when the recording ended".to_string() + } else { + format!(", for {:.1} s", lasted as f64 / 1e9) + } + ), + opened.start_ns, + end_ns, + ); + finding.refs = vec![format!("event:{}", opened.seq)]; + finding.window_ids = opened.violation.window_ids.clone(); + finding.persisted_to_end = persisted; + finding.next = Some(format!( + "komorebi-recorder trace {dir} event:{}", + opened.seq + )); + found.push(finding); + }; + for (opened, ended) in closed { + push_violation(opened, Some(ended)); + } + for (_, opened) in open { + push_violation(opened, None); + } + + // a window parked and un-parked over and over + for (window, times) in &flips { + let mut best: Option<(usize, usize)> = None; + for (start, (first, _)) in times.iter().enumerate() { + let within = times[start..] + .iter() + .take_while(|(time, _)| time.saturating_sub(*first) <= 10_000_000_000) + .count(); + if within >= 4 && best.is_none_or(|(_, count)| within > count) { + best = Some((start, within)); + } + } + if let Some((start, count)) = best { + let (first, seq) = times[start]; + let last = times[start + count - 1].0; + let name = exes + .get(window) + .map_or_else(String::new, |exe| format!("{exe} ")); + let mut finding = self.finding( + "window-flapping", + Severity::Warn, + format!( + "{name}window {window} was parked off screen and brought back {count} times in {:.1} s", + last.saturating_sub(first) as f64 / 1e9 + ), + first, + last, + ); + finding.refs = vec![format!("event:{seq}")]; + finding.window_ids = vec![*window]; + finding.next = Some(format!("komorebi-recorder window {dir} {window}")); + found.push(finding); + } + } + + // focus bouncing between two windows + let mut start = 0; + while start < focus_series.len() { + let origin = focus_series[start].0; + let mut changes = 0; + let mut windows = BTreeSet::new(); + let mut last = None; + let mut stop = start; + for (index, (time, _, window)) in focus_series.iter().enumerate().skip(start) { + if time.saturating_sub(origin) > 5_000_000_000 { + break; + } + if last.is_some() && *window != last { + changes += 1; + } + if let Some(window) = window { + windows.insert(*window); + } + last = *window; + stop = index; + } + + if changes >= 4 && windows.len() <= 2 { + let (first, seq, _) = focus_series[start]; + let (end_time, _, _) = focus_series[stop]; + let names: Vec = windows.iter().map(ToString::to_string).collect(); + let mut finding = self.finding( + "focus-oscillation", + Severity::Warn, + format!( + "focus bounced between window {} {changes} times in {:.1} s", + names.join(" and "), + end_time.saturating_sub(first) as f64 / 1e9 + ), + first, + end_time, + ); + finding.refs = vec![format!("event:{seq}")]; + finding.window_ids = windows.iter().copied().collect(); + finding.next = Some(format!("komorebi-recorder events {dir} --from event:{seq}")); + found.push(finding); + start = stop + 1; + } else { + start += 1; + } + } + + Ok(()) + } + + fn find_event_problems(&self, found: &mut Vec) { + let events = self.events(); + let pairing = self.pairing(); + let dir = self.session.dir.display().to_string(); + + // bursts: twenty or more events within a second + let mut start = 0; + while start < events.len() { + let mut stop = start; + while stop + 1 < events.len() + && events[stop + 1].recv_mach_ns - events[start].recv_mach_ns <= 1_000_000_000 + { + stop += 1; + } + + let count = stop - start + 1; + if count >= 20 { + let mut by_class: BTreeMap = BTreeMap::new(); + for index in start..=stop { + *by_class + .entry(format!("{:?}", pairing.classes[index].class).to_lowercase()) + .or_default() += 1; + } + let breakdown: Vec = by_class + .iter() + .map(|(class, count)| format!("{count} {class}")) + .collect(); + let mut finding = self.finding( + "event-storm", + if count >= 60 { + Severity::Warn + } else { + Severity::Info + }, + format!( + "{count} events in {:.1} s ({})", + (events[stop].recv_mach_ns - events[start].recv_mach_ns) as f64 / 1e9, + breakdown.join(", ") + ), + events[start].recv_mach_ns, + events[stop].recv_mach_ns, + ); + finding.refs = vec![ + format!("event:{}", events[start].seq), + format!("event:{}", events[stop].seq), + ]; + finding.next = Some(format!( + "komorebi-recorder events {dir} --from event:{} --to event:{} --hide-echo", + events[start].seq, events[stop].seq + )); + found.push(finding); + start = stop + 1; + } else { + start += 1; + } + } + + // handlers that took a long time from their header to their notification + let mut slow: Vec<(usize, f64)> = pairing + .pairs + .iter() + .enumerate() + .filter_map(|(index, pair)| pair.handler_ms.map(|ms| (index, ms))) + .filter(|(_, ms)| *ms >= 250.0) + .collect(); + slow.sort_by(|a, b| b.1.total_cmp(&a.1)); + for (index, ms) in slow.into_iter().take(10) { + let event = &events[index]; + let mut finding = self.finding( + "slow-handler", + if ms >= 1000.0 { + Severity::Warn + } else { + Severity::Info + }, + format!( + "{} took at least {ms:.0} ms to handle: {}", + event.info.summary(), + self.flavor().rules().slow_handler_cause() + ), + event.recv_mach_ns.saturating_sub((ms * 1e6) as u64), + event.recv_mach_ns, + ); + finding.refs = vec![format!("event:{}", event.seq)]; + finding.next = Some(format!("komorebi-recorder trace {dir} event:{}", event.seq)); + found.push(finding); + } + + // display changes arriving together + let monitor: Vec = (0..events.len()) + .filter(|index| events[*index].info.family == Family::Monitor) + .collect(); + let mut start = 0; + while start < monitor.len() { + let mut stop = start; + while stop + 1 < monitor.len() + && events[monitor[stop + 1]].recv_mach_ns - events[monitor[start]].recv_mach_ns + <= 5_000_000_000 + { + stop += 1; + } + if stop > start { + let (first, last) = (&events[monitor[start]], &events[monitor[stop]]); + let mut finding = self.finding( + "monitor-churn", + Severity::Warn, + format!( + "{} display notifications in {:.1} s ({})", + stop - start + 1, + (last.recv_mach_ns - first.recv_mach_ns) as f64 / 1e9, + first.info.summary() + ), + first.recv_mach_ns, + last.recv_mach_ns, + ); + finding.refs = vec![ + format!("event:{}", first.seq), + format!("event:{}", last.seq), + ]; + finding.next = Some(format!("komorebi-recorder trace {dir} event:{}", first.seq)); + found.push(finding); + start = stop + 1; + } else { + start += 1; + } + } + + let _ = Class::Echo; + } + + fn find_log_problems(&self, found: &mut Vec) { + #[derive(Default)] + struct Group { + count: usize, + first: u64, + last: u64, + first_line: u64, + sample: String, + } + + let mut groups: BTreeMap<(Level, String, String), Group> = BTreeMap::new(); + for line in &self.log().lines { + let (Some(level), Some(wall_us)) = (line.level, line.wall_us) else { + continue; + }; + if !matches!(level, Level::Error | Level::Warn) { + continue; + } + let Some(mach_ns) = self.clock().wall_to_mach(wall_us) else { + continue; + }; + + // the same problem with different numbers is one problem + let shape: String = line + .message + .chars() + .map(|character| { + if character.is_ascii_digit() { + '#' + } else { + character + } + }) + .collect(); + let group = groups + .entry((level, line.target.clone().unwrap_or_default(), shape)) + .or_default(); + if group.count == 0 { + group.first = mach_ns; + group.first_line = line.number; + group.sample = line.message.clone(); + } + group.count += 1; + group.last = mach_ns; + } + + let dir = self.session.dir.display().to_string(); + for ((level, target, _), group) in groups { + let mut finding = self.finding( + if level == Level::Error { + "log-error" + } else { + "log-warning" + }, + if level == Level::Error { + Severity::Warn + } else { + Severity::Info + }, + format!( + "{}x {} {target}: {}", + group.count, + format!("{level:?}").to_uppercase(), + group.sample + ), + group.first, + group.last, + ); + finding.refs = vec![format!("log:{}", group.first_line)]; + finding.next = Some(format!( + "komorebi-recorder code {dir} log:{}", + group.first_line + )); + found.push(finding); + } + } + + fn find_incidents(&self, found: &mut Vec) { + for incident in self.incidents() { + let mach_ns = self.manifest.mach_at_video_seconds(incident.video_s); + let severity = match incident.kind.as_str() { + "capture-failed" | "log-stream-lost" | "komorebi-exited" => Severity::Warn, + _ => Severity::Info, + }; + let mut finding = self.finding( + &format!("incident:{}", incident.kind), + severity, + format!( + "{}{}: {}", + incident.kind, + incident + .display + .map_or_else(String::new, |display| format!(" (display {display})")), + incident.detail + ), + mach_ns, + mach_ns, + ); + finding.refs = vec![format!("incident:{}", incident.number)]; + found.push(finding); + } + } + + /// Ranks findings: errors above warnings above notes, and anything in or just before a bug + /// region above everything outside one. + /// + /// Each finding is given a [`Finding::score`], and the result is ordered by it, highest first, + /// with earlier findings first among equal scores. The score is the sum of: + /// + /// | | points | + /// |---|---| + /// | severity: error, warn, info | 300, 100, 20 | + /// | for each bug region the finding overlaps | 1000 | + /// | for each bug region that starts within [`PRE_ROLL_NS`] after the finding ended | 400 | + /// | the finding was still so when the recording ended | 50 | + /// + /// The ids of the bug regions that raised the score are added to [`Finding::bugs`]. An open + /// region (one with no end) lasts to the end of the recording. With no bug regions only the + /// severity and persistence count. + /// + /// Covered by `tests/brief.rs::findings_in_the_bug_region_rank_above_the_rest`. + pub fn rank(&self, mut findings: Vec, bugs: &[&Annotation]) -> Vec { + for finding in &mut findings { + let base = match finding.severity { + Severity::Error => 300, + Severity::Warn => 100, + Severity::Info => 20, + }; + + for bug in bugs { + let (start, end) = (bug.start_mach_ns, bug.end_or_session_end(&self.manifest)); + if finding.start_mach_ns <= end && finding.end_mach_ns >= start { + finding.bugs.push(bug.id.clone()); + finding.score += 1000; + } else if finding.end_mach_ns < start && start - finding.end_mach_ns <= PRE_ROLL_NS + { + finding.bugs.push(bug.id.clone()); + finding.score += 400; + } + } + + finding.score += base; + if finding.persisted_to_end { + finding.score += 50; + } + } + + findings.sort_by(|a, b| { + b.score + .cmp(&a.score) + .then(a.start_mach_ns.cmp(&b.start_mach_ns)) + }); + findings + } + + /// Returns counts per time bucket: a picture of when things happened. + /// + /// `buckets` is the number of buckets wanted. The recording is divided into equal slices of at + /// least half a second, so a very short recording has fewer buckets than asked for. The span + /// is the video's, with a minimum of one second. + /// Events and log lines before the video starts are not counted; those after it ends are + /// counted in the last bucket. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::analysis::Analysis; + /// use komorebi_recorder::testkit::SessionBuilder; + /// use serde_json::json; + /// + /// let (session, _) = SessionBuilder::new("doc-histogram") + /// .length(10.0) + /// .event(1.2, json!({"type": "Retile"}), None) + /// .event(1.8, json!({"type": "Retile"}), None) + /// .event(8.0, json!({"type": "Retile"}), None) + /// .build(); + /// let analysis = Analysis::open(&session.dir)?; + /// + /// // ten seconds in ten buckets of one second + /// let histogram = analysis.histogram(10); + /// assert_eq!(histogram.len(), 10); + /// assert_eq!(histogram[1].events, 2); + /// assert_eq!(histogram[8].events, 1); + /// assert_eq!(histogram.iter().map(|bucket| bucket.events).sum::(), 3); + /// # Ok::<(), Box>(()) + /// ``` + #[must_use] + pub fn histogram(&self, buckets: usize) -> Vec { + let duration = self.manifest.video_span().1.max(1.0); + let width = (duration / buckets.max(1) as f64).max(0.5); + let count = (duration / width).ceil() as usize; + let mut out: Vec = (0..count) + .map(|index| Bucket { + start_s: index as f64 * width, + end_s: (index + 1) as f64 * width, + events: 0, + real_events: 0, + log_errors: 0, + log_warnings: 0, + incidents: 0, + }) + .collect(); + + let place = |seconds: f64| -> Option { + (seconds >= 0.0).then(|| ((seconds / width) as usize).min(count.saturating_sub(1))) + }; + + for (index, event) in self.events().iter().enumerate() { + if let Some(slot) = + place(self.video_s(event.recv_mach_ns)).and_then(|slot| out.get_mut(slot)) + { + slot.events += 1; + if self.pairing().classes[index].class != Class::Echo { + slot.real_events += 1; + } + } + } + for line in &self.log().lines { + let (Some(level), Some(mach_ns)) = ( + line.level, + line.wall_us + .and_then(|wall_us| self.clock().wall_to_mach(wall_us)), + ) else { + continue; + }; + if let Some(slot) = place(self.video_s(mach_ns)).and_then(|slot| out.get_mut(slot)) { + match level { + Level::Error => slot.log_errors += 1, + Level::Warn => slot.log_warnings += 1, + _ => {} + } + } + } + for incident in self.incidents() { + if let Some(slot) = place(incident.video_s).and_then(|slot| out.get_mut(slot)) { + slot.incidents += 1; + } + } + + out + } + + /// Returns the bug regions the user marked: the annotations of kind `bug`, in the order + /// [`crate::annotations::load`] gives them (by start time). + /// + /// # Errors + /// + /// Returns an error if the annotations file exists and cannot be read. A session with no + /// annotations has no such file, which is not an error. + pub fn bugs(&self) -> eyre::Result> { + Ok(crate::annotations::load(&self.session.dir)? + .annotations + .into_iter() + .filter(|annotation| annotation.kind == Kind::Bug) + .collect()) + } +} + +/// Returns the start of `finding` as a timecode, such as `00:12.345`. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::invariants::Severity; +/// use komorebi_recorder::analysis::overview::Finding; +/// use komorebi_recorder::analysis::overview::when; +/// +/// let finding = Finding { +/// kind: "slow-handler".to_string(), +/// severity: Severity::Info, +/// score: 0, +/// summary: "FocusChange took at least 300 ms to handle".to_string(), +/// start_video_s: 12.345, +/// end_video_s: 12.345, +/// start_mach_ns: 0, +/// end_mach_ns: 0, +/// refs: vec![], +/// window_ids: vec![], +/// persisted_to_end: false, +/// bugs: vec![], +/// next: None, +/// }; +/// assert_eq!(when(&finding), "00:12.345"); +/// ``` +#[must_use] +pub fn when(finding: &Finding) -> String { + timecode::format(finding.start_video_s) +} diff --git a/komorebi-recorder/src/analysis/trace.rs b/komorebi-recorder/src/analysis/trace.rs new file mode 100644 index 00000000..8e5ae849 --- /dev/null +++ b/komorebi-recorder/src/analysis/trace.rs @@ -0,0 +1,540 @@ +//! One event, end to end: what ran, what it logged, what it changed and who changed it. +//! +//! komorebi sends the state *after* each notification, so what an event changed is the difference +//! between its state and the previous event's. That difference is not all the handler's doing: +//! background threads (the reaper, the workspace reconciliator) change state with no notification +//! of their own, and their changes show up in whichever event comes next. So every change is given +//! an **attribution** with the evidence for it and how sure it is, and a change nothing explains is +//! said to be unexplained rather than blamed on the handler. +//! +//! [`Analysis::trace`] builds a [`TraceData`] for one event: what its handler logged (each line +//! tied to the statement of komorebi's source that wrote it), what other threads logged in the +//! interval, what changed with each change attributed, and which of the state's violations +//! (see [`super::invariants`]) the event introduced or cleared. It is what the `trace` command +//! prints, and what the viewer's inspector shows for an event. +//! +//! # How a change is attributed +//! +//! The rules are tried in this order for each change, and the first that applies decides: +//! +//! | the change | the evidence | `actor` | `confidence` | +//! |---|---|---|---| +//! | a window went away | `komorebi::reaper` logged `reaping window: ` in the interval | `reaper` | `high` | +//! | a window moved, a workspace came into focus, containers were reordered, or a rect really changed | `komorebi::workspace_reconciliator` logged a line containing `reconciliat` in the interval | `workspace-reconciliator` | `low` if the handler could also have made the change (below), else `medium` | +//! | one the event's handler is expected to make | none needed | `handler` | `high` if the handler's lines were found in the log, else `medium` | +//! | anything else | none: no log line accounts for it | `unexplained` | `low` | +//! +//! A handler is expected to make any change if the event is a command, a monitor change or could +//! not be read, and for a window-manager event it depends on the kind: a `FocusChange` is expected +//! to change focus, a workspace's focus, move a window, change a rect or reorder containers; a +//! `MoveStart`, `MoveEnd`, `ResizeStart` or `ResizeEnd` to change a rect, move a window, reorder +//! containers or change focus; every other window-manager event (windows shown, hidden or +//! closed reshuffle everything around them) to make any change. +//! +//! The attribution is a judgement from the log, and gives what it rests on in `evidence` and +//! `reason`. `unexplained` is a finding in itself: komorebi changed state with no notification +//! and nothing in the log accounts for it, or its log level does not show the cause. +//! +//! # Flavor +//! +//! The first two rules look for log lines of komorebi for Mac: its reaper logs `reaping window: +//! ` and it has a workspace reconciliator. komorebi for Windows does neither (its source has no +//! workspace reconciliator and no such reaper line), so for a Windows session a change is +//! attributed to the `handler` or is `unexplained`. Everything else here is the same for both: +//! the roles of the log lines ([`Rules::role`](super::flavor::Rules::role)), the explanation of a +//! slow handler ([`Rules::slow_handler_cause`](super::flavor::Rules::slow_handler_cause)) and +//! where a window is hidden are the rules of the flavor that recorded the session. + +use super::Analysis; +use super::answers::ChangeView; +use super::catalog; +use super::catalog::Confidence; +use super::diff; +use super::diff::Change; +use super::envelope; +use super::invariants; +use super::invariants::Violation; +use super::logparse::Line; +use super::timespec::Edge; +use super::timespec::Lookup; +use super::views::EventView; +use color_eyre::eyre; +use schemars::JsonSchema; +use serde::Serialize; + +/// The schema name that identifies a [`TraceData`] in an envelope (`trace/1`); listed by the +/// `schema` command. +pub const SCHEMA_TRACE: &str = "trace/1"; + +/// Where in komorebi's source a log line came from: the statement that wrote it, reduced to what a +/// reader of a trace needs (see `Source` in [`super::catalog`] for the whole match). +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct SourceRef { + /// `file:line` of the statement in komorebi's source, as an editor opens it. + pub location: String, + /// The function the statement is in, with its type if it is in an `impl`: + /// `WindowManager::process_event`. + pub function: String, + /// How much the text of the line pins the statement down. An `ambiguous` or `generic` match + /// is not a place to pin a cause on. + pub confidence: Confidence, + /// The file differs between the recorded komorebi and the indexed source, so the statement + /// may not be the one that ran. + pub file_changed: bool, +} + +/// A line of komorebi's log, with where it came from in the source. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct TraceLine { + /// The line of the session's `komorebi.log`, counting from 1. + pub line: u64, + /// When the line was logged, in seconds of video time; `None` if it has no time or it cannot + /// be placed on the session's clock. + pub video_s: Option, + /// The level in capitals (`INFO`); `None` for a line that is not a log record. + pub level: Option, + /// The span chain, e.g. `process_event:focus_window`. Empty for a line from a thread that + /// is not in a handler. + pub spans: String, + /// The module the line was logged from, such as `komorebi::reaper`. + pub target: Option, + /// The message, without ANSI escapes. + pub message: String, + /// The statement that wrote it, if one matched. + pub source: Option, + /// The part of komorebi that logged it changes state without sending a notification, so its + /// lines are candidates for a change with no event before it. + pub changes_state_silently: bool, +} + +/// Who made a change, and what that is based on. +/// +/// This is a judgement from the log, not a fact: see the [module](self) documentation for the +/// rules. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)] +pub struct Attribution { + /// `handler`, `reaper`, `workspace-reconciliator` or `unexplained`. + pub actor: String, + /// `high`, `medium` or `low`. + pub confidence: String, + /// The line numbers of `komorebi.log` that support it: the log lines of the reaper or the + /// reconciliator, or the handler's header. Empty for `unexplained`, and for a handler whose + /// lines were not found. + pub evidence: Vec, + /// The attribution in a sentence. + pub reason: String, +} + +/// A change an event made, with who made it. +/// +/// In JSON it is the fields of the change (a `ChangeView`: `text` and the change's fields, +/// including its `kind`) with an `attribution` beside them. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct TracedChange { + /// The change, with a line of text that describes it. + #[serde(flatten)] + pub change: ChangeView, + /// Who made it. + pub attribution: Attribution, +} + +/// One event end to end: the `data` of the `trace` command. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct TraceData { + /// The event, with its class and the handler that was paired with it. + pub event: EventView, + /// The lines the handler logged, in order; empty if the log has no block for this event. + pub handler: Vec, + /// Lines from other threads logged between the previous notification and this one: what else + /// was going on. For the first event that is everything logged before it. Lines that belong to + /// any handler, and continuation lines such as panic backtraces, are not included. + pub ambient: Vec, + /// The changes the event made, each with its attribution: the difference between the state when + /// its handler began (the state the previous event left) and the state it carried. Empty, with + /// a note, if the state before or after is unknown. + pub changes: Vec, + /// Violations (see [`super::invariants`]) that are in the state after the event and were not in + /// the state before it. A violation is the same one only if its message is the same. + pub violations_appeared: Vec, + /// Violations that were in the state before the event and are not in the state after it. + pub violations_resolved: Vec, + /// Things worth knowing that are not data: a slow handler, errors, a missing log. + pub notes: Vec, +} + +fn spans_of(line: &Line) -> String { + line.spans + .iter() + .map(|span| span.name.as_str()) + .collect::>() + .join(":") +} + +/// Whether a change is the kind of thing this event's handler is expected to do. +fn expected_of_handler(event: &EventView, change: &Change) -> bool { + use crate::analysis::events::Family; + match event.info.family { + // commands, monitor changes and anything unreadable can do anything + Family::Command | Family::Monitor | Family::Unknown => true, + Family::WindowManager => match event.info.name.as_str() { + "FocusChange" => matches!( + change, + Change::Focus { .. } + | Change::WorkspaceFocus { .. } + | Change::WindowMoved { .. } + | Change::WindowRect { .. } + | Change::ContainerOrder { .. } + ), + "MoveStart" | "MoveEnd" | "ResizeStart" | "ResizeEnd" => matches!( + change, + Change::WindowRect { .. } + | Change::WindowMoved { .. } + | Change::ContainerOrder { .. } + | Change::Focus { .. } + ), + // showing, hiding and closing windows reshuffles everything around them + _ => true, + }, + } +} + +impl Analysis { + fn trace_line(&self, line: &Line, skew: &catalog::Skew) -> TraceLine { + let source = match (&line.target, line.level) { + (Some(target), Some(level)) => self.catalog().find(target, level, &line.message), + _ => None, + }; + let role = line + .target + .as_deref() + .map(|target| self.flavor().rules().role(target)); + TraceLine { + line: line.number, + video_s: line + .wall_us + .and_then(|wall_us| self.clock().wall_to_mach(wall_us)) + .map(|mach_ns| self.video_s(mach_ns)), + level: line.level.map(|level| format!("{level:?}").to_uppercase()), + spans: spans_of(line), + target: line.target.clone(), + message: line.message.clone(), + source: source.map(|source| SourceRef { + location: source.statement.location(), + function: source.statement.qualified_function(), + confidence: source.confidence, + file_changed: skew.file_changed(&source.statement.file), + }), + changes_state_silently: role.is_some_and(|role| role.changes_state_silently), + } + } + + /// Traces event `seq`: what its handler logged, what else was logged, what it changed and who + /// made each change. + /// + /// The changes are the difference between the state at the moment the handler began and the + /// state the event carried, so anything background threads did since the previous + /// notification is in them too, attributed by [the rules](self#how-a-change-is-attributed). + /// The handler's lines are those komorebi's log has for the event, if any. The notes say + /// what is missing or worth knowing: no handler lines in the log, a handler that took 100 ms or + /// more from its header to the notification (with the flavor's likely cause), errors and + /// warnings the handler logged, and, for an event the analysis classified as an echo of + /// komorebi's own move, why. + /// + /// `TraceData::os_trace` is `None` in the result: ask `Analysis::os_trace` for it and set + /// it, as `trace --os` does. + /// + /// # Errors + /// + /// Returns an error if: + /// + /// - there is no event numbered `seq` (the not-found exit kind); + /// - the event carried a state, it is not the first event, and no state was recorded before it + /// (not found); + /// - a state file is missing (not found) or is not valid JSON. + /// + /// An event that carried no state, and the first event of a session that has no starting + /// state, are not errors: they have no `changes` and a note saying why. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::analysis::Analysis; + /// use komorebi_recorder::testkit::SessionBuilder; + /// use komorebi_recorder::testkit::state_with_windows; + /// use serde_json::json; + /// + /// let notification = |name: &str, what: &str| { + /// json!({"type": name, "content": [{"type": "Accessibility", "content": what}, 7, 1]}) + /// }; + /// + /// // Two windows; then Brave is closed (the reaper notices, and sends no notification of its + /// // own) and the next focus change reports the result. + /// let (session, _) = SessionBuilder::new("doc-trace") + /// .event( + /// 1.0, + /// notification("Show", "AXWindowCreated"), + /// Some(state_with_windows(&[(1, "Ghostty"), (2, "Brave")])), + /// ) + /// .event( + /// 4.0, + /// notification("FocusChange", "AXApplicationActivated"), + /// Some(state_with_windows(&[(1, "Ghostty")])), + /// ) + /// .log(3.5, "INFO", "komorebi::reaper: reaping window: 2") + /// .log( + /// 3.9, + /// "INFO", + /// "process_event: komorebi::process_event: processing event: FocusChange for process 7 with notification AXApplicationActivated", + /// ) + /// .build(); + /// let analysis = Analysis::open(&session.dir)?; + /// + /// let trace = analysis.trace(2)?; + /// assert_eq!(trace.handler.len(), 1); + /// // the reaper's line is from another thread, so it is ambient + /// assert_eq!(trace.ambient[0].message, "reaping window: 2"); + /// + /// // window 2 vanished with no notification of its own, and the reaper's line says why + /// let removed = trace + /// .changes + /// .iter() + /// .find(|traced| traced.change.change.kind() == "window-removed") + /// .expect("a window was removed"); + /// assert_eq!(removed.attribution.actor, "reaper"); + /// assert_eq!(removed.attribution.confidence, "high"); + /// assert_eq!(removed.attribution.evidence, [1]); + /// + /// // an event that does not exist is an error + /// assert!(analysis.trace(99).is_err()); + /// # Ok::<(), Box>(()) + /// ``` + /// + /// Also covered by + /// `tests/trace.rs::a_change_with_no_event_of_its_own_is_blamed_on_the_reaper_by_its_log_line` + /// and `tests/trace.rs::an_event_with_no_log_says_so_instead_of_inventing_a_handler`, and, for + /// a Windows session, by + /// `tests/windows_flavor.rs::the_state_is_read_by_window_handle_and_a_trace_says_what_moved`. + pub fn trace(&self, seq: u64) -> eyre::Result { + let index = self + .event_index(seq) + .ok_or_else(|| envelope::not_found(format!("there is no event #{seq}")))?; + let view = self + .event_view(index) + .ok_or_else(|| envelope::not_found(format!("there is no event #{seq}")))?; + let event = &self.events()[index]; + let log = self.log(); + let pair = &self.pairing().pairs[index]; + let block = pair.block.and_then(|id| log.blocks.get(id)); + + let skew = self.skew(); + let handler: Vec = block + .map(|block| { + block + .lines + .iter() + .filter_map(|number| log.lines.get(usize::try_from(number - 1).ok()?)) + .map(|line| self.trace_line(line, &skew)) + .collect() + }) + .unwrap_or_default(); + + // lines from other threads between the previous notification and this one + let previous_recv = index + .checked_sub(1) + .map_or(0, |before| self.events()[before].recv_mach_ns); + let handler_lines: std::collections::HashSet = log + .blocks + .iter() + .flat_map(|block| block.lines.iter().copied()) + .collect(); + let ambient_lines: Vec<&Line> = log + .lines + .iter() + .filter(|line| !line.continuation && !handler_lines.contains(&line.number)) + .filter(|line| { + line.wall_us + .and_then(|wall_us| self.clock().wall_to_mach(wall_us)) + .is_some_and(|mach_ns| mach_ns > previous_recv && mach_ns <= event.recv_mach_ns) + }) + .collect(); + + // what changed, and who did it + let start = self.event_mach_ns(seq, Edge::Start)?; + let (changes, appeared, resolved, mut notes) = + if index == 0 && self.state_at(start).is_err() { + ( + Vec::new(), + Vec::new(), + Vec::new(), + vec![ + "no state was recorded before this event, so what it changed is unknown" + .to_string(), + ], + ) + } else if event.state_id.is_none() { + ( + Vec::new(), + Vec::new(), + Vec::new(), + vec!["this notification carried no state".to_string()], + ) + } else { + let before = self.state_at(start)?; + let after = self.state_at(event.recv_mach_ns)?; + let raw = diff::diff(&before.snapshot, &after.snapshot); + let (was, now) = ( + invariants::check(&before.snapshot), + invariants::check(&after.snapshot), + ); + let traced = raw + .into_iter() + .map(|change| { + let attribution = self.attribute(&view, &change, &ambient_lines); + TracedChange { + change: ChangeView { + text: change.describe(), + change, + }, + attribution, + } + }) + .collect(); + ( + traced, + now.iter().filter(|v| !was.contains(v)).cloned().collect(), + was.iter().filter(|v| !now.contains(v)).cloned().collect(), + Vec::new(), + ) + }; + + if let Some(block) = block { + if let Some(ms) = pair.handler_ms + && ms >= 100.0 + { + notes.push(format!( + "the handler took at least {ms:.0} ms from its header to the notification: {}", + self.flavor().rules().slow_handler_cause() + )); + } + if block.errors + block.warnings > 0 { + notes.push(format!( + "the handler logged {} error(s) and {} warning(s)", + block.errors, block.warnings + )); + } + } else { + notes.push( + "no handler lines for this event were found in komorebi's log: it may not have \ + been recorded, or komorebi may log this kind of event only at a more verbose level" + .to_string(), + ); + } + if view.class == super::classify::Class::Echo { + notes.push(view.reason.clone()); + } + + Ok(TraceData { + event: view, + handler, + ambient: ambient_lines + .iter() + .map(|line| self.trace_line(line, &skew)) + .collect(), + changes, + violations_appeared: appeared, + violations_resolved: resolved, + notes, + }) + } + + /// Say who made `change`, from what the log shows happened around it. + fn attribute(&self, event: &EventView, change: &Change, ambient: &[&Line]) -> Attribution { + let lines_of = |target: &str, needle: &str| -> Vec { + ambient + .iter() + .filter(|line| { + line.target.as_deref() == Some(target) && line.message.contains(needle) + }) + .map(|line| line.number) + .collect() + }; + + // a window removed that the reaper logged reaping, by id + if let Change::WindowRemoved { window, .. } = change { + let evidence = lines_of( + "komorebi::reaper", + &format!("reaping window: {}", window.id), + ); + if !evidence.is_empty() { + return Attribution { + actor: "reaper".to_string(), + confidence: "high".to_string(), + evidence, + reason: format!( + "the reaper logged reaping window {}: it removes windows that no longer \ + exist, without sending a notification", + window.id + ), + }; + } + } + + let reconciling = lines_of("komorebi::workspace_reconciliator", "reconciliat"); + let moves = matches!( + change, + Change::WindowMoved { .. } + | Change::WorkspaceFocus { .. } + | Change::ContainerOrder { .. } + | Change::WindowRect { .. } + ); + let by_handler = expected_of_handler(event, change); + + if moves && !reconciling.is_empty() { + return Attribution { + actor: "workspace-reconciliator".to_string(), + confidence: if by_handler { "low" } else { "medium" }.to_string(), + evidence: reconciling, + reason: if by_handler { + "the workspace reconciliator ran in this interval and could have done this, \ + but so could the handler" + .to_string() + } else { + "the workspace reconciliator ran in this interval, and this is not what this \ + event's handler does" + .to_string() + }, + }; + } + + if by_handler { + let quality = event.handler.as_ref().map(|handler| handler.quality); + return Attribution { + actor: "handler".to_string(), + confidence: if quality.is_some() { "high" } else { "medium" }.to_string(), + evidence: event + .handler + .as_ref() + .map(|handler| vec![handler.header_line]) + .unwrap_or_default(), + reason: format!( + "{} is the kind of change {} makes", + change.kind(), + event.info.name + ), + }; + } + + Attribution { + actor: "unexplained".to_string(), + confidence: "low".to_string(), + evidence: Vec::new(), + reason: format!( + "{} is not something {} does, and no background activity in the log accounts for \ + it: komorebi changed state with no notification, or the log is at a level that \ + does not show it", + change.kind(), + event.info.name + ), + } + } +} diff --git a/komorebi-recorder/src/report.rs b/komorebi-recorder/src/report.rs index a6260fe2..49ddd15e 100644 --- a/komorebi-recorder/src/report.rs +++ b/komorebi-recorder/src/report.rs @@ -26,8 +26,19 @@ //! //! Times are written as timecodes (`00:12.500`, see [`crate::timecode::format`]) in video time. +use crate::analysis::answers::DiffData; +use crate::analysis::answers::EventsData; +use crate::analysis::answers::StateData; use crate::analysis::code::CodeData; use crate::analysis::history::HistoryData; +use crate::analysis::invariants::Severity; +use crate::analysis::invariants::Violation; +use crate::analysis::overview::Finding; +use crate::analysis::overview::OverviewData; +use crate::analysis::state::Container; +use crate::analysis::state::Window; +use crate::analysis::trace::TraceData; +use crate::analysis::trace::TraceLine; use crate::annotations::AnnotationView; use crate::annotations::Kind; use crate::timecode; @@ -460,6 +471,337 @@ fn rect_text(rect: &Option) -> String { .map_or_else(|| "rect unknown".to_string(), |rect| rect.describe()) } +fn window_line(window: &Window, marker: &str) -> String { + format!( + "{marker} window {} {} \"{}\" {}", + window.id, + window.exe, + window.title, + rect_text(&window.rect) + ) +} + +fn container_lines(out: &mut String, index: usize, container: &Container, focused: bool) { + for (tab, window) in container.windows.iter().enumerate() { + let marker = if tab == 0 { + format!("{index:>3}{}", if focused { "*" } else { " " }) + } else { + " ".to_string() + }; + let front = if container.windows.len() > 1 && tab == container.focused { + " (front tab)" + } else { + "" + }; + let _ = writeln!(out, " {}{front}", window_line(window, &marker)); + } +} + +fn violation_lines(out: &mut String, violations: &[Violation]) { + for violation in violations { + let severity = match violation.severity { + Severity::Error => "error", + Severity::Warn => "warn ", + Severity::Info => "info ", + }; + let _ = writeln!( + out, + " {severity} {}: {}", + violation.kind, violation.message + ); + } +} + +/// Renders the answer to `state`: the moment and which notification the state is from, the focus, +/// each monitor with its workspaces and the windows in them, the windows asked about, and what looks +/// wrong. +/// +/// The heading says how old the state is. If it is more than five seconds old a note says that +/// komorebi can change state without a notification, so it may be out of date. A workspace that is +/// showing is marked, and workspaces that are not showing and were left out of the answer are listed +/// with their window counts. A window that matched what was asked about says where it is, where it +/// really is and, for a tiled window, where the layout says it should be. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::Analysis; +/// use komorebi_recorder::analysis::answers::StateQuery; +/// use komorebi_recorder::report::state_text; +/// use komorebi_recorder::testkit::{SessionBuilder, mach_ns, state_with_windows}; +/// use serde_json::json; +/// +/// let (session, _) = SessionBuilder::new("doc-state-text") +/// .event(2.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal")]))) +/// .build(); +/// let analysis = Analysis::open(&session.dir)?; +/// let data = analysis.state_answer(mach_ns(2.5), &StateQuery::default())?; +/// +/// let text = state_text(&data); +/// assert!(text.starts_with("state at 00:02.500 (as of event #1, 500 ms before)\n")); +/// assert!(text.contains("workspace one [showing]")); +/// assert!(text.contains("window 7 Terminal")); +/// assert!(text.contains("nothing looks wrong in this state")); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn state_text(data: &StateData) -> String { + let mut out = String::new(); + let age = data.origin.age_ms.map_or_else(String::new, |age| { + if age < 1000.0 { + format!(", {age:.0} ms before") + } else { + format!(", {:.1} s before", age / 1000.0) + } + }); + let source = match (data.origin.source.as_str(), data.origin.seq) { + ("event", Some(seq)) => format!("as of event #{seq}{age}"), + _ => format!("the state when recording began{age}"), + }; + let _ = writeln!(out, "state at {} ({source})", data.at.timecode); + if data.origin.age_ms.is_some_and(|age| age > 5000.0) { + let _ = writeln!( + out, + "note: nothing was reported for a while, and komorebi can change state without a \ + notification, so this may be out of date" + ); + } + + if let Some(focus) = &data.focus { + let _ = writeln!( + out, + "focus: window {} on monitor {} workspace {}", + focus + .window_id + .map_or_else(|| "(none)".to_string(), |id| id.to_string()), + focus.monitor_id, + focus.workspace + ); + } + if data.paused { + let _ = writeln!(out, "komorebi is PAUSED"); + } + + for monitor in &data.monitors { + let _ = writeln!( + out, + "\nmonitor {} \"{}\" {}", + monitor.id, + monitor.device, + monitor.size.describe() + ); + + for (index, workspace) in monitor.workspaces.iter().enumerate() { + let showing = data.workspaces.iter().any(|summary| { + summary.monitor_id == monitor.id + && summary.name == workspace.name + && summary.showing + }); + let _ = writeln!( + out, + " workspace {}{} {}{}", + workspace.name, + if showing { " [showing]" } else { "" }, + workspace.layout, + if workspace.layer == "Floating" { + " [floating layer]" + } else { + "" + }, + ); + let _ = index; + + for (container_index, container) in workspace.containers.iter().enumerate() { + container_lines( + &mut out, + container_index, + container, + showing && container_index == workspace.focused, + ); + } + if let Some(monocle) = &workspace.monocle { + let _ = writeln!(out, " monocle:"); + container_lines(&mut out, 0, monocle, true); + } + if let Some(window) = &workspace.maximized { + let _ = writeln!(out, "{}", window_line(window, " maximized")); + } + for window in &workspace.floating { + let _ = writeln!(out, "{}", window_line(window, " floating")); + } + } + } + + let hidden: Vec = data + .workspaces + .iter() + .filter(|summary| { + !summary.showing + && !data.monitors.iter().any(|monitor| { + monitor.id == summary.monitor_id + && monitor + .workspaces + .iter() + .any(|workspace| workspace.name == summary.name) + }) + }) + .map(|summary| format!("{} ({})", summary.name, summary.windows)) + .collect(); + if !hidden.is_empty() { + let _ = writeln!( + out, + "\nnot showing (windows): {} (--all to list them)", + hidden.join(", ") + ); + } + + for found in &data.matches { + let _ = writeln!( + out, + "\nwindow {} {} \"{}\"\n where: {}\n really at: {}{}", + found.window.id, + found.window.exe, + found.window.title, + found.location.describe(), + rect_text(&found.window.rect), + if found.hidden_position { + " (parked off screen)" + } else { + "" + }, + ); + if let Some(layout) = &found.layout_rect { + let _ = writeln!(out, " layout says: {}", layout.describe()); + } + } + + if data.violations.is_empty() { + let _ = writeln!(out, "\nnothing looks wrong in this state"); + } else { + let _ = writeln!(out, "\nwrong in this state:"); + violation_lines(&mut out, &data.violations); + } + + out +} + +/// Renders the answer to `diff`: the two moments, a line for each change, and the violations that +/// appeared or were resolved between them. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::Analysis; +/// use komorebi_recorder::report::diff_text; +/// use komorebi_recorder::testkit::{SessionBuilder, mach_ns, state_with_windows}; +/// use serde_json::json; +/// +/// let (session, _) = SessionBuilder::new("doc-diff-text") +/// .event(2.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal")]))) +/// .event(4.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal"), (8, "Browser")]))) +/// .build(); +/// let analysis = Analysis::open(&session.dir)?; +/// +/// let text = diff_text(&analysis.diff_answer(mach_ns(3.0), mach_ns(5.0))?); +/// assert!(text.starts_with("from 00:03.000 to 00:05.000\n")); +/// assert!(text.contains("Browser \"window 8\" (window 8) appeared on monitor 1 workspace one")); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn diff_text(data: &DiffData) -> String { + let mut out = String::new(); + let _ = writeln!(out, "from {} to {}", data.from.timecode, data.to.timecode); + if data.changes.is_empty() { + let _ = writeln!(out, "no difference between the two states"); + } + for change in &data.changes { + let _ = writeln!(out, " {}", change.text); + } + if !data.violations_appeared.is_empty() { + let _ = writeln!(out, "\nwrong now, and not before:"); + violation_lines(&mut out, &data.violations_appeared); + } + if !data.violations_resolved.is_empty() { + let _ = writeln!(out, "\nwrong before, and not now:"); + violation_lines(&mut out, &data.violations_resolved); + } + out +} + +/// Renders the answer to `events`: how many of the session's events matched and a line for each one +/// returned. +/// +/// A line has the sequence number, the time, the class, what the event was, where the log has its +/// handler at least how long the handler ran and how many errors (`E`) and warnings (`W`) it logged, +/// and whether the state changed. With `verbose` a line follows each event saying why it was classified +/// as it was. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::Analysis; +/// use komorebi_recorder::analysis::answers::EventQuery; +/// use komorebi_recorder::report::events_text; +/// use komorebi_recorder::testkit::SessionBuilder; +/// use serde_json::json; +/// +/// let (session, _) = SessionBuilder::new("doc-events-text") +/// .event(2.0, json!({"type": "Retile"}), None) +/// .build(); +/// let analysis = Analysis::open(&session.dir)?; +/// +/// let text = events_text(&analysis.events_answer(&EventQuery::default()).data, false); +/// assert!(text.starts_with("1 of 1 events\n#1 00:02.000 command")); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn events_text(data: &EventsData, verbose: bool) -> String { + let mut out = String::new(); + let _ = writeln!( + out, + "{} of {} events{}", + data.matching, + data.total, + data.subscriber + .as_ref() + .map_or_else(String::new, |name| format!( + " (recorded as subscriber {name})" + )) + ); + + for event in &data.events { + let handler = event.handler.as_ref().map_or_else(String::new, |handler| { + let ms = handler + .handler_ms + .map_or_else(String::new, |ms| format!(" {ms:.0} ms")); + let problems = if handler.errors + handler.warnings > 0 { + format!(" {}E/{}W", handler.errors, handler.warnings) + } else { + String::new() + }; + format!(" handler{ms}{problems}") + }); + let state = match event.state_changed { + Some(true) => " state changed", + Some(false) => " state unchanged", + None => "", + }; + let _ = writeln!( + out, + "#{:<5} {} {:<9} {}{handler}{state}", + event.seq, + timecode::format(event.video_s), + format!("{:?}", event.class).to_lowercase(), + event.summary, + ); + if verbose { + let _ = writeln!(out, " {}", event.reason); + } + } + + out +} + /// Renders the answer to `code`: for each log line asked about, the statement in komorebi's source /// that wrote it, and for a search, the statements that matched. /// @@ -580,6 +922,153 @@ pub fn code_text(data: &CodeData) -> String { out } +fn trace_line_text(out: &mut String, line: &TraceLine) { + let time = line.video_s.map_or_else(String::new, |seconds| { + format!(" {}", timecode::format(seconds)) + }); + let _ = writeln!( + out, + " log:{:<6}{time} {:<5} {}{}", + line.line, + line.level.as_deref().unwrap_or(""), + if line.spans.is_empty() { + String::new() + } else { + format!("[{}] ", line.spans) + }, + line.message + ); + if let Some(source) = &line.source { + let _ = writeln!( + out, + " from {} in {}{}{}", + source.location, + source.function, + if source.file_changed { + " [file differs from the recorded komorebi]" + } else { + "" + }, + if line.changes_state_silently { + " [changes state without a notification]" + } else { + "" + } + ); + } +} + +/// Renders the answer to `trace`: the event, what its handler logged, and each change to the state +/// with who is held to have made it. +/// +/// The text also has what other threads logged meanwhile, the evidence for each attribution, and +/// what looks wrong after the event that did not before. When the data has them, it adds what +/// Windows said about the event's window (a recording made with `--probe-windows`), the OS trace +/// around the event (`trace --os`) grouped by where it came from, and notes such as a slow handler. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::Analysis; +/// use komorebi_recorder::report::trace_text; +/// use komorebi_recorder::testkit::{SessionBuilder, state_with_windows}; +/// use serde_json::json; +/// +/// let (session, _) = SessionBuilder::new("doc-trace-text") +/// .event(2.0, json!({"type": "Retile"}), Some(state_with_windows(&[(7, "Terminal")]))) +/// .build(); +/// let analysis = Analysis::open(&session.dir)?; +/// +/// let text = trace_text(&analysis.trace(1)?); +/// assert!(text.starts_with("event #1 received 00:02.000 Retile\n command (")); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn trace_text(data: &TraceData) -> String { + let mut out = String::new(); + let event = &data.event; + let _ = writeln!( + out, + "event #{} received {} {}\n {} ({})", + event.seq, + timecode::format(event.video_s), + event.summary, + format!("{:?}", event.class).to_lowercase(), + event.reason + ); + if let Some(handler) = &event.handler { + let _ = writeln!( + out, + " handler logged {} line(s) from {}, began {}{}", + handler.lines, + timecode::format(handler.started_video_s), + handler.handler_ms.map_or_else(String::new, |ms| format!( + "{ms:.0} ms before it was received" + )), + if handler.errors + handler.warnings > 0 { + format!( + ", {} error(s), {} warning(s)", + handler.errors, handler.warnings + ) + } else { + String::new() + } + ); + } + + if !data.handler.is_empty() { + let _ = writeln!(out, "\nwhat the handler logged:"); + for line in &data.handler { + trace_line_text(&mut out, line); + } + } + if !data.ambient.is_empty() { + let _ = writeln!(out, "\nlogged by other threads meanwhile:"); + for line in &data.ambient { + trace_line_text(&mut out, line); + } + } + + if data.changes.is_empty() { + let _ = writeln!(out, "\nthe state did not change"); + } else { + let _ = writeln!(out, "\nwhat changed, and who did it:"); + for traced in &data.changes { + let attribution = &traced.attribution; + let _ = writeln!( + out, + " {}\n -> {} ({}): {}", + traced.change.text, attribution.actor, attribution.confidence, attribution.reason + ); + if !attribution.evidence.is_empty() { + let lines: Vec = attribution + .evidence + .iter() + .map(|line| format!("log:{line}")) + .collect(); + let _ = writeln!(out, " evidence: {}", lines.join(", ")); + } + } + } + + if !data.violations_appeared.is_empty() { + let _ = writeln!(out, "\nwrong after this event, and not before:"); + violation_lines(&mut out, &data.violations_appeared); + } + if !data.violations_resolved.is_empty() { + let _ = writeln!(out, "\nwrong before this event, and not after:"); + violation_lines(&mut out, &data.violations_resolved); + } + if !data.notes.is_empty() { + let _ = writeln!(out, "\nnotes:"); + for note in &data.notes { + let _ = writeln!(out, " - {note}"); + } + } + + out +} + /// Renders the answer to `window`: the windows the query matched, then an entry for each event that /// came with a change to one of them. /// @@ -652,6 +1141,106 @@ pub fn history_text(data: &HistoryData) -> String { out } +fn finding_line(finding: &Finding) -> String { + let severity = match finding.severity { + Severity::Error => "error", + Severity::Warn => "warn ", + Severity::Info => "info ", + }; + let bugs = if finding.bugs.is_empty() { + String::new() + } else { + " [in or just before a bug region]".to_string() + }; + format!( + "{severity} {} {} {}{bugs}", + timecode::format(finding.start_video_s), + finding.kind, + finding.summary + ) +} + +/// Renders the answer to `overview`: the session's size, the bug regions the user marked, the +/// findings most worth looking at first, and a histogram of when things happened. +/// +/// Each finding has the command to dig into it. The histogram has a row for each bucket of time with something in it: a bar scaled to the +/// busiest bucket's number of events, then the counts of events, log errors and incidents. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::Analysis; +/// use komorebi_recorder::report::overview_text; +/// use komorebi_recorder::testkit::SessionBuilder; +/// use serde_json::json; +/// +/// let (session, _) = SessionBuilder::new("doc-overview-text") +/// .event(2.0, json!({"type": "Retile"}), None) +/// .build(); +/// let text = overview_text(&Analysis::open(&session.dir)?.overview(None)?); +/// assert!(text.contains(": 10 s of video, 1 events, 0 log lines, 0 incidents")); +/// assert!(text.contains("when things happened (events | errors | incidents):")); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn overview_text(data: &OverviewData) -> String { + let mut out = String::new(); + let session = &data.session; + let _ = writeln!( + out, + "session {}: {} s of video, {} events, {} log lines, {} incidents", + session.dir, + session.duration_s as i64, + session.events, + session.log_lines, + session.incidents + ); + + for bug in &data.bugs { + let _ = writeln!(out, "\nbug region:"); + out.push_str(&annotation_text(bug)); + } + + let _ = writeln!( + out, + "\nfindings, most worth looking at first ({} of {}):", + data.findings.len(), + data.findings_total + ); + for finding in &data.findings { + let _ = writeln!(out, " {}", finding_line(finding)); + if let Some(next) = &finding.next { + let _ = writeln!(out, " {next}"); + } + } + + let peak = data + .histogram + .iter() + .map(|bucket| bucket.events) + .max() + .unwrap_or(0) + .max(1); + let _ = writeln!(out, "\nwhen things happened (events | errors | incidents):"); + for bucket in &data.histogram { + if bucket.events + bucket.log_errors + bucket.incidents == 0 { + continue; + } + let bar = "#".repeat((bucket.events * 30).div_ceil(peak)); + let _ = writeln!( + out, + " {} {:<30} {:>4} {:>3} {:>2}", + timecode::format(bucket.start_s), + bar, + bucket.events, + bucket.log_errors, + bucket.incidents + ); + } + + out +} + #[cfg(test)] mod tests { use super::*;