feat(cli): record until a command exits, findings and brief --compact, and --json everywhere

record --until-exit -- <command> runs the command while recording (with
KOMOREBI_RECORDER_SESSION set) and stops when it exits; its status is reported
apart from the recorder's. record, displays, reindex and selftest take --json
(record/1, displays/1, reindex/1, selftest/1). brief --compact is a 40-line
brief, and findings merges detector findings (with stable f-xxxxxx ids) with
an agent's. annotate --ref log:"text" / log:HH:MM:SS.mmm / log:<video time>
resolves to a log line and says which.
This commit is contained in:
LGUG2Z committed 2026-10-28 16:24:29 -07:00
1 parent 3c4f352846
commit cf15fc978c
18 files changed
+2364 -36

No files matched your search

+5 -1
View File
@@ -40,6 +40,7 @@ runs the latest commit without a checkout.
```sh
komorebi-recorder displays # which displays can be recorded
komorebi-recorder record --duration 30 --out ./repro
komorebi-recorder record --until-exit --out ./repro -- ./repro.sh # record while a script runs, stop when it exits
```
Run `komorebi-recorder` with no command for a small window with Record and Stop buttons instead.
@@ -55,6 +56,8 @@ the frames.
```sh
komorebi-recorder brief ./repro # what the user marked as the bug, and what the recording shows around it
komorebi-recorder brief ./repro --compact # the same in about 40 lines, for a small context window
komorebi-recorder findings ./repro # detector findings (with stable ids) and an agent's conclusions, in one list
komorebi-recorder overview ./repro # the whole recording at a glance
komorebi-recorder trace ./repro event:7 # one event, from the handler that ran to what changed and who changed it
```
@@ -74,7 +77,8 @@ when things happened (events | errors | incidents):
```
`komorebi-recorder view ./repro` opens the recording in the viewer, which is where you mark where the bug is.
Every command takes `--json`, and `komorebi-recorder guide` prints a playbook for an agent.
Every command takes `--json` (including `record`, `displays`, `reindex` and `selftest`), and `komorebi-recorder guide`
prints a playbook for an agent.
[Investigating a recording](docs/usage/investigating-a-recording.md) walks through both ways of working.
## How it fits together
+21 -1
View File
@@ -6,6 +6,8 @@ this is broken" to "this is the line of komorebi that causes it" using what was
```
komorebi-recorder brief <session> # start here
komorebi-recorder brief <session> --compact # the same, in about 40 lines
komorebi-recorder findings <session> # everything the detectors found and an agent concluded
komorebi-recorder guide # the playbook, for an agent
```
@@ -108,6 +110,8 @@ and `event:12.end` when it finished.
| Command | What it tells you |
| --- | --- |
| `brief` | The bug region(s) in the user's words, then what the recording shows around them: the events, what looked wrong, the state as it began and ended, what happened to the machine, and the events most worth tracing first, with why |
| `brief --compact` | The brief cut down to fit a small context window, about 40 lines: the user's words, one line on the state of the recording, the 3 highest-ranked findings (each with its id and the references to look at), and the exact commands to run next. `--json` gives `brief-compact/1` |
| `findings` | The detectors' findings and the findings an agent recorded, in one list (an agent's first, then the detectors' ranked as in `overview`). `--kind K` (`log-error`, or `invariant` for every `invariant:<kind>`), `--severity error\|warn\|info` (detector findings only), `--limit N`. `--json` gives `findings/1` |
| `overview` | The whole recording at a glance: what stands out, ranked (states that are wrong and for how long, windows that flap, event storms, slow handlers, errors, a display unplugged), anything near a bug region first |
| `state --at T` | What komorebi believed at a moment, and anything inconsistent in it: a window parked off screen on a workspace that is showing, a window in two places, a layout that was not applied |
| `diff A B` | What changed between two moments in terms a person would use: a window appeared, moved, was really somewhere else; focus moved; a monitor came or went |
@@ -159,6 +163,16 @@ the same.
the window really was, which is what makes comparing it with where komorebi's layout put it meaningful.
- An `AXError` in komorebi's log comes from the application or the OS, not from komorebi.
### Finding ids
Each detector finding has an id like `f-04dc11`: `f-` and six hex digits of a fixed hash (FNV-1a) of its kind, its first
reference (`event:17`, `log:345`) and the ids of the windows it is about; a finding with no reference uses the
five-second bucket of video time it began in. It does not depend on the score or on the bug regions, so the same finding
keeps its id between runs and as annotations are added, and `findings`, `brief --compact` and `overview` name it the
same way. Two different recordings share an id only where the same kind of finding is at the same reference, so use ids
to compare analyses of one session (before and after a change to the detectors), not to match a bug across recordings.
An agent's findings keep their annotation id (`a-3f9c1e02`).
## Recording what you conclude
```
@@ -168,5 +182,11 @@ komorebi-recorder annotate <session> add --kind finding --about <bug id> \
```
A finding with no evidence is refused, and every reference is checked to exist: the event, the log line, the video time,
the line of komorebi's source. Findings are stored in `annotations.jsonl` beside the bug region, so the person who
the line of komorebi's source. A log line can be named by what it says or when it was written instead of by number:
`--ref 'log:"could not place window"'` (the one line of `komorebi.log` that contains the text, ignoring case),
`--ref log:15:46:23.677700` (the line written at that UTC time, as precisely as you write it; `HH:MM:SS` alone matches the
whole second) or `--ref log:2.72` (the line nearest that time of the video). A text or time that matches several lines
is a usage error (exit 2) listing the first few as `log:N: text`; pick one with `log:N`. When a reference was resolved
this way the command prints the `log:N` it chose and the line's text (on standard error, and in `warnings` with
`--json`), so you can check it is the statement you meant. Findings are stored in `annotations.jsonl` beside the bug region, so the person who
recorded the bug can see what was concluded and why.
+21
View File
@@ -79,6 +79,27 @@ komorebi-recorder displays # list display ids
komorebi-recorder record --display 2 # record just one display
```
To record exactly while a script reproduces the bug, give the command after `--` with `--until-exit`:
```
komorebi-recorder record --until-exit --out ./repro -- ./repro.sh --slow
```
The recorder starts the command once the recording is under way, and stops the recording when the command exits. If
`--duration` or Ctrl-C comes first, that stops the recording and the command is terminated, so whichever comes first
wins. The command runs in the directory you are in, with this terminal's input and output, and has
`KOMOREBI_RECORDER_SESSION` in its environment: the session directory (an absolute path) that is being recorded, so
that anything the script runs can mark the moment with `komorebi-recorder mark` or annotate the session without being
told where it is. On Windows the command is terminated with `TerminateProcess`, which does not reach programs it
started.
The exit status of `komorebi-recorder record` is about the recording, never the command: it is 0 when the session was
finalised, whatever status the command exited with. The command's status is in the summary
(`command: ... exited with status 3`) and in `record --json` as `data.child` (`end`: `exited`, `stopped`,
`failed-to-start` or `not-started`; `exit_code`; `success`). `--json` on `record` prints the `record/1` envelope on
standard output (progress stays on standard error): the session directory, the duration, each display's frames, the
recorder's warnings and the command's status. `displays`, `reindex` and `selftest` take `--json` too.
Useful options:
| Option | Effect |
+281
View File
@@ -0,0 +1,281 @@
//! `brief --compact`: the brief cut down to what fits in a small context window.
//!
//! The full [`BriefData`] carries every event, change and state of each bug region, which is what an
//! investigation wants after it has started and more than an agent wants to read first. A
//! [`CompactBrief`] is what to read before that, in about 40 lines: the user's words, one line on the
//! state of the recording, the three highest-ranked findings (each with the references to look at),
//! and the exact commands to run next. [`BriefData::compact`] makes one from a brief that has already
//! been made, so it shows the same findings and the same commands the full brief does.
//!
//! Limits, so that the size is predictable: at most [`TOP_FINDINGS`] findings, at most
//! [`MAX_TEXT`] characters of each bug's description, [`MAX_SUMMARY`] of each finding's summary, at most
//! [`MAX_NEXT`] commands, and every bug region is listed (a recording rarely has more than one or
//! two). Anything cut off is counted, and the full `brief` has it.
use super::brief::BriefData;
use super::invariants::Severity;
use crate::timecode;
use schemars::JsonSchema;
use serde::Serialize;
use std::fmt::Write;
/// The `schema` of `brief --compact --json`: the name [`CompactBrief`] has in an envelope.
pub const SCHEMA_BRIEF_COMPACT: &str = "brief-compact/1";
/// How many findings a compact brief lists.
pub const TOP_FINDINGS: usize = 3;
/// How many characters of a description or a summary a compact brief keeps.
pub const MAX_TEXT: usize = 300;
/// How many characters of a finding's summary a compact brief keeps.
pub const MAX_SUMMARY: usize = 160;
/// How many commands a compact brief suggests.
pub const MAX_NEXT: usize = 6;
/// A bug region the user marked, in the user's words.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct CompactRegion {
/// The annotation id, e.g. `a-3f9c1e02`.
pub id: String,
/// What the user said is wrong, cut to [`MAX_TEXT`] characters.
pub text: String,
/// What should have happened instead, cut the same way.
pub expected: Option<String>,
/// Where the region starts, in seconds of video time.
pub start_video_s: f64,
/// Where it ends, in seconds of video time (the end of the recording if open-ended).
pub end_video_s: f64,
}
/// One of the highest-ranked findings.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct CompactFinding {
/// The stable id, `f-xxxxxx` (see [`super::findings`]).
pub id: String,
/// How serious it is.
pub severity: Severity,
/// The detector's kind.
pub kind: String,
/// What was seen, cut to [`MAX_SUMMARY`] characters.
pub summary: String,
/// When it began, in seconds of video time.
pub at_video_s: f64,
/// Where to look: `event:12`, `log:345`, ...
pub refs: Vec<String>,
}
/// The brief in a few lines: the `data` of `brief --compact --json`.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct CompactBrief {
/// The session directory.
pub session: String,
/// The state of the recording in one line: how long, what, and komorebi's state at the end.
pub state: String,
/// The bug regions the user marked; empty if none was.
pub regions: Vec<CompactRegion>,
/// How many findings there are in or near the regions (or in the whole recording if no region
/// was marked), of which the first [`TOP_FINDINGS`] are in `top_findings`.
pub findings_total: usize,
/// The highest-ranked findings.
pub top_findings: Vec<CompactFinding>,
/// How many findings an agent has already recorded (`findings` lists them).
pub recorded_findings: usize,
/// Commands to run next, exactly as they can be pasted.
pub next: Vec<String>,
}
fn cut(text: &str, most: usize) -> String {
let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
if flat.chars().count() <= most {
return flat;
}
let mut cut: String = flat.chars().take(most).collect();
cut.push_str("...");
cut
}
impl BriefData {
/// Returns the compact form of this brief; see the [module](super::compact) for its limits.
///
/// The findings are those of the bug regions' briefs (or of the whole recording when no region
/// was marked), each once, highest score first. The commands are those the first bug region's
/// brief suggests, then `findings` and the full `brief`.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::Analysis;
/// use komorebi_recorder::testkit::SessionBuilder;
///
/// let (session, _) = SessionBuilder::new("doc-compact")
/// .log(3.0, "ERROR", "komorebi::window: could not do the thing")
/// .build();
/// let compact = Analysis::open(&session.dir)?.brief()?.compact();
///
/// assert!(compact.regions.is_empty());
/// assert_eq!(compact.top_findings[0].kind, "log-error");
/// assert!(compact.top_findings[0].id.starts_with("f-"));
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn compact(&self) -> CompactBrief {
let dir = &self.session.dir;
let mut findings: Vec<&super::overview::Finding> = self
.bugs
.iter()
.map(|bug| &bug.region)
.chain(self.whole_session.as_ref())
.flat_map(|region| region.findings.iter())
.collect();
findings.sort_by(|a, b| {
b.score
.cmp(&a.score)
.then(a.start_mach_ns.cmp(&b.start_mach_ns))
});
let mut seen = std::collections::BTreeSet::new();
findings.retain(|finding| seen.insert(finding.stable_id()));
let region = self
.bugs
.first()
.map(|bug| &bug.region)
.or(self.whole_session.as_ref());
let at_end = region.and_then(|region| region.state_at_end.as_ref());
let session = &self.session;
let state = format!(
"{:.0} s of video, {} display(s), {} events, {} log lines, {} incidents; sync {}; {}",
session.duration_s,
session.displays.len(),
session.events,
session.log_lines,
session.incidents,
session.sync_quality,
at_end.map_or_else(
|| "no komorebi state recorded".to_string(),
|state| {
let wrong = state.violations.len();
if wrong == 0 {
format!("at the end: {}, nothing wrong", state.summary)
} else {
format!("at the end: {}, {wrong} thing(s) wrong", state.summary)
}
}
),
);
let mut next: Vec<String> = match self.bugs.first() {
Some(bug) => bug.commands.iter().take(MAX_NEXT - 2).cloned().collect(),
None => self
.next
.iter()
.filter(|command| command.starts_with("no bug region"))
.cloned()
.collect(),
};
next.push(format!("komorebi-recorder findings {dir}"));
next.push(format!("komorebi-recorder brief {dir}"));
CompactBrief {
session: dir.clone(),
state,
regions: self
.bugs
.iter()
.map(|bug| CompactRegion {
id: bug.bug.id.clone(),
text: cut(&bug.bug.text, MAX_TEXT),
expected: bug.bug.expected.as_deref().map(|text| cut(text, MAX_TEXT)),
start_video_s: bug.bug.start_video_s,
end_video_s: bug.bug.end_video_s,
})
.collect(),
findings_total: findings.len(),
top_findings: findings
.iter()
.take(TOP_FINDINGS)
.map(|finding| CompactFinding {
id: finding.stable_id(),
severity: finding.severity,
kind: finding.kind.clone(),
summary: cut(&finding.summary, MAX_SUMMARY),
at_video_s: finding.start_video_s,
refs: finding.refs.clone(),
})
.collect(),
recorded_findings: self.findings_recorded.len(),
next,
}
}
}
impl CompactBrief {
/// Returns the brief as plain text, in about 40 lines.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::Analysis;
/// use komorebi_recorder::testkit::SessionBuilder;
///
/// let (session, _) = SessionBuilder::new("doc-compact-text").build();
/// let text = Analysis::open(&session.dir)?.brief()?.compact().text();
/// assert!(text.lines().count() < 40);
/// assert!(text.contains("komorebi-recorder findings"));
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn text(&self) -> String {
let mut out = String::new();
if self.regions.is_empty() {
let _ = writeln!(out, "NO BUG REGION WAS MARKED");
}
for region in &self.regions {
let _ = writeln!(
out,
"BUG {} ({} -> {}), as the user said:\n {}",
region.id,
timecode::format(region.start_video_s),
timecode::format(region.end_video_s),
region.text
);
if let Some(expected) = &region.expected {
let _ = writeln!(out, " expected: {expected}");
}
}
let _ = writeln!(out, "\nrecording {}\n {}", self.session, self.state);
let _ = writeln!(
out,
"\nfindings ({} shown of {}; {} recorded by an agent):",
self.top_findings.len(),
self.findings_total,
self.recorded_findings
);
if self.top_findings.is_empty() {
let _ = writeln!(out, " none: no detector fired");
}
for finding in &self.top_findings {
let severity = serde_json::to_value(finding.severity)
.ok()
.and_then(|value| value.as_str().map(str::to_string))
.unwrap_or_default();
let _ = writeln!(
out,
" {} {severity} {} at {}: {} [{}]",
finding.id,
finding.kind,
timecode::format(finding.at_video_s),
finding.summary,
finding.refs.join(" ")
);
}
let _ = writeln!(out, "\nnext:");
for command in &self.next {
let _ = writeln!(out, " {command}");
}
out
}
}
+323
View File
@@ -0,0 +1,323 @@
//! Every finding in one list: what the detectors found and what an agent concluded.
//!
//! `overview` ranks what the detectors found, and `annotations --kind finding` lists what an
//! agent wrote down. [`Analysis::merged_findings`] is both together, which is what the `findings`
//! command prints: an agent coming back to a session sees its own conclusions next to what the
//! detectors say, and can filter by kind and severity.
//!
//! # Stable ids
//!
//! A detector finding has no id of its own, so [`Finding::stable_id`] makes one: `f-` and six hex
//! digits of an FNV-1a hash of the finding's `kind`, its first reference (`event:12`, `log:345`,
//! `incident:2`) and the ids of the windows it is about (so that two windows wrong at the same event
//! are two ids); a finding with no reference uses the five-second bucket of video time it began in
//! instead of the reference. The hash is fixed (it does not change between runs, machines
//! or versions of the recorder), and it does not depend on the score, the summary or the bug
//! regions, so the same finding keeps its id when a bug region is added and the ranking changes.
//! It is the same for the same session however many times it is analysed. Two *different*
//! sessions share an id only where the same kind of finding is at the same reference, which for
//! numbered references is by coincidence of numbering: ids compare findings across analyses of one
//! session (before and after a fix to the detectors, say), and are not a fingerprint of a bug across
//! recordings. Agent findings keep the annotation id (`a-3f9c1e02`) they were given.
use super::Analysis;
use super::invariants::Severity;
use super::overview::Finding;
use crate::annotations::Kind;
use color_eyre::eyre;
use schemars::JsonSchema;
use serde::Serialize;
/// The `schema` of the `findings` command's output: the name [`FindingsData`] has in an envelope.
pub const SCHEMA_FINDINGS: &str = "findings/1";
/// The `kind` of a finding an agent wrote down with `annotate add --kind finding`.
pub const AGENT_KIND: &str = "agent-finding";
/// Who a finding is from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum FindingSource {
/// Found by one of the detectors (see `overview`).
Detector,
/// Written down by an agent or a person with `annotate add --kind finding`.
Agent,
}
/// One finding, from either source.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct FindingItem {
/// `f-xxxxxx` for a detector finding (see [`Finding::stable_id`]), the annotation id for an
/// agent's.
pub id: String,
/// Where it came from.
pub source: FindingSource,
/// The detector's kind (`invariant:<kind>`, `log-error`, ...), or `agent-finding`.
pub kind: String,
/// How serious the detector thinks it is. `None` for an agent's finding, which is a conclusion
/// and has no severity.
pub severity: Option<Severity>,
/// The detector's ranking score (see `overview`); `None` for an agent's finding.
pub score: Option<i64>,
/// What was seen (a detector), or the conclusion (an agent).
pub summary: String,
/// When it began, in seconds of video time.
pub start_video_s: f64,
/// When it ended, in seconds of video time.
pub end_video_s: f64,
/// Where to look: `event:12`, `log:345`, `incident:2`, `code:<path>:<line>`, ...
pub refs: Vec<String>,
/// The bug regions it overlaps (a detector), or the one it explains (an agent).
pub bugs: Vec<String>,
/// Who wrote an agent's finding.
pub author: Option<String>,
/// A command that digs into it, if there is one.
pub next: Option<String>,
}
/// What [`Analysis::merged_findings`] is asked for.
#[derive(Debug, Clone, Default)]
pub struct FindingsQuery {
/// Only findings of this kind: the whole `kind`, or the part before the colon (`invariant`
/// matches every `invariant:<kind>`).
pub kind: Option<String>,
/// Only detector findings of this severity. Agent findings have none, so a severity leaves them
/// out.
pub severity: Option<Severity>,
/// The most findings to return; `None` for all of them.
pub limit: Option<usize>,
}
/// The `data` of the `findings` command.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct FindingsData {
/// Agent findings first (earliest first), then detector findings, ranked as in `overview`.
pub findings: Vec<FindingItem>,
/// How many findings matched the filters, including any cut off by the limit.
pub total: usize,
/// How many of those were written by an agent.
pub agent: usize,
/// How many of those were found by a detector.
pub detector: usize,
}
/// FNV-1a over `bytes`: fixed forever, unlike the standard library's hashers.
fn fnv1a(bytes: &[u8]) -> u64 {
bytes.iter().fold(0xcbf2_9ce4_8422_2325, |hash, byte| {
(hash ^ u64::from(*byte)).wrapping_mul(0x0000_0100_0000_01b3)
})
}
impl Finding {
/// Returns the finding's stable id, `f-` and six hex digits.
///
/// It is made from the kind, the first reference (or, for a finding with none, the five-second
/// bucket of video time it began in) and the windows it is about; see the [module](self) for what
/// that does and does not promise.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::Analysis;
/// use komorebi_recorder::testkit::SessionBuilder;
///
/// let (session, _) = SessionBuilder::new("doc-stable-id")
/// .log(3.0, "ERROR", "komorebi::window: could not do the thing")
/// .build();
/// let found = Analysis::open(&session.dir)?.findings()?;
///
/// let id = found[0].stable_id();
/// assert!(id.starts_with("f-") && id.len() == 8);
/// // the same finding, the same id
/// assert_eq!(id, found[0].clone().stable_id());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn stable_id(&self) -> String {
let place = self.refs.first().map_or_else(
|| format!("t{}", (self.start_video_s.max(0.0) / 5.0).floor() as u64),
Clone::clone,
);
let mut windows = self.window_ids.clone();
windows.sort_unstable();
let hash = fnv1a(format!("{}\0{place}\0{windows:?}", self.kind).as_bytes());
format!("f-{:06x}", hash & 0x00ff_ffff)
}
}
impl Analysis {
/// Returns the detectors' findings and the agent's, together, filtered by `query`.
///
/// The detector findings are those of [`Analysis::findings`], ranked against the bug regions by
/// [`Analysis::rank`]; the agent's are the `finding` annotations. Agent findings come first.
///
/// # Errors
///
/// Returns an error if the annotations cannot be read, or a recorded state cannot (see
/// [`Analysis::findings`]).
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::Analysis;
/// use komorebi_recorder::analysis::findings::FindingsQuery;
/// use komorebi_recorder::testkit::SessionBuilder;
///
/// let (session, _) = SessionBuilder::new("doc-merged-findings")
/// .log(3.0, "ERROR", "komorebi::window: could not do the thing")
/// .build();
/// let data = Analysis::open(&session.dir)?.merged_findings(&FindingsQuery::default())?;
/// assert_eq!(data.detector, 1);
/// assert_eq!(data.findings[0].kind, "log-error");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn merged_findings(&self, query: &FindingsQuery) -> eyre::Result<FindingsData> {
let bugs = self.bugs()?;
let bug_refs: Vec<&crate::annotations::Annotation> = bugs.iter().collect();
let ranked = self.rank(self.findings()?, &bug_refs);
let loaded = crate::annotations::load(&self.session.dir)?;
let mut items: Vec<FindingItem> = loaded
.annotations
.iter()
.filter(|annotation| annotation.kind == Kind::Finding)
.map(|annotation| {
let view = annotation.view(&self.manifest);
FindingItem {
id: view.id,
source: FindingSource::Agent,
kind: AGENT_KIND.to_string(),
severity: None,
score: None,
summary: view.text,
start_video_s: view.start_video_s,
end_video_s: view.end_video_s,
refs: view.refs.iter().map(ToString::to_string).collect(),
bugs: view.about.into_iter().collect(),
author: Some(view.author),
next: None,
}
})
.collect();
items.sort_by(|a, b| a.start_video_s.total_cmp(&b.start_video_s));
items.extend(ranked.into_iter().map(|finding| FindingItem {
id: finding.stable_id(),
source: FindingSource::Detector,
kind: finding.kind,
severity: Some(finding.severity),
score: Some(finding.score),
summary: finding.summary,
start_video_s: finding.start_video_s,
end_video_s: finding.end_video_s,
refs: finding.refs,
bugs: finding.bugs,
author: None,
next: finding.next,
}));
items.retain(|item| {
query.kind.as_deref().is_none_or(|kind| {
item.kind == kind
|| item
.kind
.strip_prefix(kind)
.is_some_and(|rest| rest.starts_with(':'))
}) && query
.severity
.is_none_or(|severity| item.severity == Some(severity))
});
let total = items.len();
let agent = items
.iter()
.filter(|item| item.source == FindingSource::Agent)
.count();
items.truncate(query.limit.unwrap_or(usize::MAX));
Ok(FindingsData {
findings: items,
total,
agent,
detector: total - agent,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::analysis::invariants::Severity;
fn finding(kind: &str, refs: &[&str], start_video_s: f64) -> Finding {
Finding {
kind: kind.to_string(),
severity: Severity::Warn,
score: 0,
summary: String::new(),
start_video_s,
end_video_s: start_video_s,
start_mach_ns: 0,
end_mach_ns: 0,
refs: refs.iter().map(ToString::to_string).collect(),
window_ids: Vec::new(),
persisted_to_end: false,
bugs: Vec::new(),
next: None,
}
}
#[test]
fn the_id_is_fixed_and_follows_the_kind_and_first_reference() {
let a = finding("log-error", &["log:12"], 3.0);
// pinned: the hash must not change between versions
assert_eq!(
a.stable_id(),
finding("log-error", &["log:12"], 9.0).stable_id()
);
assert_ne!(
a.stable_id(),
finding("log-error", &["log:13"], 3.0).stable_id()
);
assert_ne!(
a.stable_id(),
finding("log-warning", &["log:12"], 3.0).stable_id()
);
// the score and the summary do not matter
let mut ranked = a.clone();
ranked.score = 1300;
ranked.summary = "different".to_string();
assert_eq!(a.stable_id(), ranked.stable_id());
assert_eq!(a.stable_id().len(), 8);
assert_eq!(fnv1a(b"a"), 0xaf63_dc4c_8601_ec8c);
}
#[test]
fn two_windows_wrong_at_the_same_event_are_two_ids() {
let mut one = finding("invariant:layout-mismatch", &["event:4"], 3.0);
one.window_ids = vec![7];
let mut other = one.clone();
other.window_ids = vec![9];
assert_ne!(one.stable_id(), other.stable_id());
// the order the windows are listed in does not matter
let mut both = one.clone();
both.window_ids = vec![9, 7];
let mut reversed = one.clone();
reversed.window_ids = vec![7, 9];
assert_eq!(both.stable_id(), reversed.stable_id());
}
#[test]
fn a_finding_with_no_reference_uses_a_five_second_bucket() {
let early = finding("event-storm", &[], 1.0);
assert_eq!(
early.stable_id(),
finding("event-storm", &[], 4.9).stable_id()
);
assert_ne!(
early.stable_id(),
finding("event-storm", &[], 5.1).stable_id()
);
}
}
+2
View File
@@ -16,11 +16,13 @@ pub mod catalog;
pub mod changes;
pub mod classify;
pub mod code;
pub mod compact;
pub mod compare;
pub mod diff;
pub mod envelope;
pub mod events;
pub mod facade;
pub mod findings;
pub mod flavor;
pub mod framediff;
pub mod ghost;
+30
View File
@@ -159,6 +159,36 @@ pub const ALL: &[Entry] = &[
about: "`doctor --probe`: what one measurement found",
schema: of::<crate::doctor::ProbeReport>,
},
Entry {
name: "brief-compact/1",
about: "`brief --compact`: the brief cut down to the user's words, the top findings and what to run next",
schema: of::<super::compact::CompactBrief>,
},
Entry {
name: "findings/1",
about: "`findings`: detector findings (with stable ids) and an agent's findings, together",
schema: of::<super::findings::FindingsData>,
},
Entry {
name: "record/1",
about: "`record --json`: the finished session, its displays and frames, warnings and the --until-exit command's status",
schema: of::<crate::cli::outputs::RecordData>,
},
Entry {
name: "displays/1",
about: "`displays --json`: the displays that can be recorded",
schema: of::<crate::cli::outputs::DisplaysData>,
},
Entry {
name: "reindex/1",
about: "`reindex --json`: what was recovered and how many records the index has",
schema: of::<crate::cli::outputs::ReindexData>,
},
Entry {
name: "selftest/1",
about: "`selftest --json`: the video-to-clock readings of a passing self-test",
schema: of::<crate::cli::outputs::SelftestData>,
},
Entry {
name: "error/1",
about: "any failed command: the envelope with `ok: false` and an `error`",
+18
View File
@@ -41,6 +41,10 @@ pub const GUIDE: &str = include_str!("../guide.md");
pub struct BriefArgs {
/// Session directory
pub session: PathBuf,
/// A trimmed brief for a small context window (about 40 lines): the user's words, a line on the
/// state, the top 3 findings with their references, and the commands to run next
#[arg(long)]
pub compact: bool,
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
@@ -114,6 +118,20 @@ pub(super) fn brief(args: &BriefArgs) -> eyre::Result<()> {
let analysis = Analysis::open(&args.session)?;
let data = analysis.brief()?;
if args.compact {
let mut warnings = analysis.warnings();
warnings.extend(data.skew.warning.clone());
let compact = data.compact();
if args.json {
return print_json(
&Envelope::ok(crate::analysis::compact::SCHEMA_BRIEF_COMPACT, compact)
.warnings(warnings),
);
}
print!("{}", compact.text());
return Ok(());
}
if args.json {
let mut warnings = analysis.warnings();
warnings.extend(data.skew.warning.clone());
+38 -10
View File
@@ -128,7 +128,9 @@ pub struct AddArgs {
#[arg(long, value_name = "ID")]
pub about: Option<String>,
/// Evidence (repeatable; a finding needs at least one): event:<seq>, log:<line>,
/// log:<file>:<line>, code:<path>:<line>, frame:<time>
/// log:<file>:<line>, code:<path>:<line>, frame:<time>. A log line can also be named by its
/// text, log:"some text" (quote it for the shell: 'log:"some text"'), by its UTC time,
/// log:HH:MM:SS.mmm, or by a video time, log:12.5; the line it resolves to is printed to check
#[arg(long = "ref", value_name = "REF")]
pub refs: Vec<String>,
/// A checkout of the recorded komorebi, to check code: references [default: `$KOMOREBI_MAC_SRC`
@@ -219,8 +221,21 @@ pub const SCHEMA_ANNOTATIONS: &str = "annotations/1";
/// The `schema` of the output of `annotate delete` with `--json`: the id removed ([`DeletedData`]).
pub const SCHEMA_DELETED: &str = "annotation-deleted/1";
fn parse_refs(refs: &[String]) -> eyre::Result<Vec<Ref>> {
refs.iter().map(|text| text.parse()).collect()
/// Reads the references, finding the log line of one that names it by text or time
/// ([`super::refspec`]). The notes say what each of those was resolved to.
fn parse_refs(
session: &Session,
manifest: &Manifest,
refs: &[String],
) -> eyre::Result<(Vec<Ref>, Vec<String>)> {
let mut parsed = Vec::new();
let mut notes = Vec::new();
for text in refs {
let resolved = super::refspec::resolve(session, manifest, text)?;
parsed.push(resolved.reference.parse()?);
notes.extend(resolved.note);
}
Ok((parsed, notes))
}
fn resolve_ns(session: &Session, manifest: &Manifest, text: &str) -> eyre::Result<u64> {
@@ -278,7 +293,7 @@ pub(super) fn annotate(args: &AnnotateArgs) -> eyre::Result<()> {
fn add_annotation(session: &Session, manifest: &Manifest, args: &AddArgs) -> eyre::Result<()> {
let kind = Kind::from(args.kind);
let loaded = annotations::load(&session.dir)?;
let refs = parse_refs(&args.refs)?;
let (refs, resolved) = parse_refs(session, manifest, &args.refs)?;
let about = match &args.about {
Some(id) => Some(
loaded
@@ -345,7 +360,13 @@ fn add_annotation(session: &Session, manifest: &Manifest, args: &AddArgs) -> eyr
.code_root
.clone()
.or_else(|| annotations::default_code_root(manifest.komorebi.flavor));
let warnings = annotations::validate_refs(session, manifest, &refs, code_root.as_deref())?;
let mut warnings = resolved;
warnings.extend(annotations::validate_refs(
session,
manifest,
&refs,
code_root.as_deref(),
)?);
let author = args.author.clone().unwrap_or_else(|| {
if kind == Kind::Finding {
@@ -379,16 +400,23 @@ fn add_annotation(session: &Session, manifest: &Manifest, args: &AddArgs) -> eyr
}
fn edit_annotation(session: &Session, manifest: &Manifest, args: &EditArgs) -> eyre::Result<()> {
let refs = (!args.refs.is_empty())
.then(|| parse_refs(&args.refs))
.transpose()?;
let mut warnings = Vec::new();
let (refs, mut warnings) = if args.refs.is_empty() {
(None, Vec::new())
} else {
let (refs, notes) = parse_refs(session, manifest, &args.refs)?;
(Some(refs), notes)
};
if let Some(refs) = &refs {
let code_root = args
.code_root
.clone()
.or_else(|| annotations::default_code_root(manifest.komorebi.flavor));
warnings = annotations::validate_refs(session, manifest, refs, code_root.as_deref())?;
warnings.extend(annotations::validate_refs(
session,
manifest,
refs,
code_root.as_deref(),
)?);
}
let patch = Patch {
+139
View File
@@ -0,0 +1,139 @@
//! `findings`: what the detectors found and what an agent concluded, in one list.
//!
//! The answer is [`Analysis::merged_findings`] (`findings/1` with `--json`): the findings an agent
//! recorded with `annotate add --kind finding` first, then the detectors' findings ranked as
//! `overview` ranks them, each detector finding with the stable `f-xxxxxx` id
//! ([`crate::analysis::overview::Finding::stable_id`]). `--kind` and `--severity` narrow it and
//! `--limit` cuts it (20 by default; 0 for all); a cut list is marked `truncated`.
//!
//! Covered by `tests/findings.rs`, which runs the command through the real binary.
use super::print_json;
use crate::analysis::Analysis;
use crate::analysis::envelope::Envelope;
use crate::analysis::findings::FindingItem;
use crate::analysis::findings::FindingSource;
use crate::analysis::findings::FindingsData;
use crate::analysis::findings::FindingsQuery;
use crate::analysis::findings::SCHEMA_FINDINGS;
use crate::analysis::invariants::Severity;
use crate::timecode;
use clap::Args;
use clap::ValueEnum;
use color_eyre::eyre;
use std::fmt::Write;
use std::path::PathBuf;
/// A severity, as `--severity` spells it.
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum SeverityArg {
/// The state is wrong in a way a person would see
Error,
/// Probably wrong, or an application's doing
Warn,
/// Worth knowing, not a fault in itself
Info,
}
impl From<SeverityArg> for Severity {
fn from(severity: SeverityArg) -> Self {
match severity {
SeverityArg::Error => Self::Error,
SeverityArg::Warn => Self::Warn,
SeverityArg::Info => Self::Info,
}
}
}
/// The arguments of `findings`.
#[derive(Args, Debug)]
pub struct FindingsArgs {
/// Session directory
pub session: PathBuf,
/// Only this kind: `log-error`, `invariant` (every `invariant:<kind>`), `invariant:<kind>`,
/// `agent-finding`, ...
#[arg(long, value_name = "KIND")]
pub kind: Option<String>,
/// Only detector findings of this severity (an agent's findings have none, so they are left out)
#[arg(long, value_enum)]
pub severity: Option<SeverityArg>,
/// Most findings to list (0 for all)
#[arg(long, default_value_t = 20)]
pub limit: usize,
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
}
/// Renders the findings as text, one finding to a line and its next command under it.
#[must_use]
pub fn findings_text(data: &FindingsData) -> String {
let mut out = String::new();
let _ = writeln!(
out,
"{} finding(s): {} recorded by an agent, {} found by detectors",
data.total, data.agent, data.detector
);
for item in &data.findings {
out.push_str(&finding_line(item));
}
if data.findings.len() < data.total {
let _ = writeln!(
out,
"... {} more; --limit 0 lists them all",
data.total - data.findings.len()
);
}
out
}
fn finding_line(item: &FindingItem) -> String {
let mut out = String::new();
let who = match (item.source, item.severity) {
(FindingSource::Agent, _) => "agent".to_string(),
(FindingSource::Detector, Some(severity)) => serde_json::to_value(severity)
.ok()
.and_then(|value| value.as_str().map(str::to_string))
.unwrap_or_default(),
(FindingSource::Detector, None) => "detector".to_string(),
};
let _ = writeln!(
out,
" {} {who:<5} {} at {}: {}{}",
item.id,
item.kind,
timecode::format(item.start_video_s),
item.summary,
if item.refs.is_empty() {
String::new()
} else {
format!(" [{}]", item.refs.join(" "))
}
);
if let Some(next) = &item.next {
let _ = writeln!(out, " next: {next}");
}
out
}
pub(super) fn findings(args: &FindingsArgs) -> eyre::Result<()> {
let analysis = Analysis::open(&args.session)?;
let data = analysis.merged_findings(&FindingsQuery {
kind: args.kind.clone(),
severity: args.severity.map(Severity::from),
limit: super::limit(args.limit),
})?;
if args.json {
let cut = data.findings.len() < data.total;
let mut envelope = Envelope::ok(SCHEMA_FINDINGS, data).warnings(analysis.warnings());
if cut {
envelope = envelope.truncated(None);
}
return print_json(&envelope);
}
print!("{}", findings_text(&data));
Ok(())
}
+35 -2
View File
@@ -8,13 +8,18 @@
mod agent;
mod annotate;
mod doctor;
mod findings;
mod investigate;
pub mod outputs;
mod logq;
mod query;
mod record;
pub mod refspec;
pub mod until_exit;
mod video;
mod viewer_command;
use crate::analysis::envelope::Envelope;
use crate::analysis::envelope::unusable;
use crate::analysis::envelope::with_hint;
use crate::session::Session;
@@ -33,6 +38,7 @@ pub use agent::SearchArgs;
pub use annotate::AnnotateArgs;
pub use annotate::AnnotationsArgs;
pub use doctor::DoctorArgs;
pub use findings::FindingsArgs;
pub use investigate::CodeArgs;
pub use investigate::DiffArgs;
pub use investigate::EventsArgs;
@@ -46,6 +52,7 @@ pub use query::FramesArgs;
pub use query::LocateArgs;
pub use query::RangeArgs;
pub use query::SummaryArgs;
pub use record::DisplaysArgs;
pub use record::RecordArgs;
pub use video::BlankArgs;
pub use video::ChangesArgs;
@@ -82,7 +89,7 @@ pub enum Command {
/// Record without a window; Ctrl-C (or --duration) stops and finalizes the session
Record(RecordArgs),
/// List the displays that can be recorded
Displays,
Displays(DisplaysArgs),
/// What this machine can do for a recording, and probes that measure what one leans on
Doctor(DoctorArgs),
/// Everything recorded around a video timecode: komorebi log, events and OS trace
@@ -134,6 +141,8 @@ pub enum Command {
View(ViewArgs),
/// Which line of komorebi's source wrote a line of its log, with the code around it
Code(CodeArgs),
/// What the detectors found and what an agent concluded, in one list, with stable ids
Findings(FindingsArgs),
/// Add, edit or delete a session's bug regions, notes and an agent's findings
Annotate(AnnotateArgs),
/// List a session's bug regions, notes and findings
@@ -152,6 +161,9 @@ pub enum Command {
pub struct ReindexArgs {
/// Session directory
pub session: PathBuf,
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
}
/// The arguments of `selftest`.
@@ -166,6 +178,9 @@ pub struct SelftestArgs {
/// Session directory for the self-test recording
#[arg(long)]
pub out: Option<PathBuf>,
/// Machine-readable JSON output (a failed self-test is a failed envelope)
#[arg(long)]
pub json: bool,
}
/// Print `value` as pretty JSON.
@@ -208,6 +223,11 @@ impl Command {
Self::Annotate(args) => args.json(),
Self::Annotations(args) => args.json,
Self::Doctor(args) => args.json,
Self::Record(args) => args.json,
Self::Displays(args) => args.json,
Self::Reindex(args) => args.json,
Self::Selftest(args) => args.json,
Self::Findings(args) => args.json,
_ => false,
}
}
@@ -245,7 +265,7 @@ pub fn run(command: Command) -> eyre::Result<()> {
match command {
Command::Gui(args) => crate::app::run(args),
Command::Record(args) => record::record(&args),
Command::Displays => record::displays(),
Command::Displays(args) => record::displays(&args),
Command::Doctor(args) => doctor::doctor(&args),
Command::At(args) => query::at(&args),
Command::Range(args) => query::range(&args),
@@ -271,6 +291,7 @@ pub fn run(command: Command) -> eyre::Result<()> {
Command::Framediff(args) => video::framediff(&args),
Command::Blank(args) => video::blank(&args),
Command::Compare(args) => video::compare(&args),
Command::Findings(args) => findings::findings(&args),
Command::Annotate(args) => annotate::annotate(&args),
Command::Annotations(args) => annotate::list(&args),
Command::Reindex(args) => reindex(&args),
@@ -326,6 +347,18 @@ fn reindex(args: &ReindexArgs) -> eyre::Result<()> {
let session = Session::open(&args.session)?;
let reindexed = crate::recovery::reindex_session(&session)?;
if args.json {
return print_json(&Envelope::ok(
outputs::SCHEMA_REINDEX,
outputs::ReindexData {
session: session.dir.display().to_string(),
recovered: reindexed.recovered,
entries: reindexed.stats.entries,
by_source: reindexed.stats.by_source,
},
));
}
for note in &reindexed.recovered {
println!("recovered: {note}");
}
+147
View File
@@ -0,0 +1,147 @@
//! What `record`, `displays`, `reindex` and `selftest` print with `--json`.
//!
//! The investigation commands answer in the envelope of [`crate::analysis::envelope`] and so do
//! these, so that an agent driving the whole workflow (record, check what was recorded, investigate)
//! parses one shape. Each type here is the `data` of one envelope, named by its `SCHEMA_*` constant
//! and listed by `komorebi-recorder schema`. Without `--json` the commands print what they always
//! did.
use schemars::JsonSchema;
use serde::Serialize;
/// The `schema` of `record --json`: [`RecordData`].
pub const SCHEMA_RECORD: &str = "record/1";
/// The `schema` of `displays --json`: [`DisplaysData`].
pub const SCHEMA_DISPLAYS: &str = "displays/1";
/// The `schema` of `reindex --json`: [`ReindexData`].
pub const SCHEMA_REINDEX: &str = "reindex/1";
/// The `schema` of `selftest --json`: [`SelftestData`].
pub const SCHEMA_SELFTEST: &str = "selftest/1";
/// How the command of `record --until-exit` ended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum ChildEnd {
/// It ran to its end on its own, which stopped the recording; see `exit_code`.
Exited,
/// The recording ended first (Ctrl-C, `--duration`, or the recorder failing), and the command
/// was terminated; it has no exit code that means anything.
Stopped,
/// The command could not be started (see `error`); the recording was stopped.
FailedToStart,
/// The recording failed before the command was started, so it never ran.
NotStarted,
}
/// What became of the command of `record --until-exit`.
///
/// The recorder's own exit status is about the recording and never the command's: read
/// `exit_code` and `success` for that.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct ChildReport {
/// The command and its arguments, as given after `--`.
pub command: Vec<String>,
/// How it ended.
pub end: ChildEnd,
/// Its exit code, when it [`Exited`](ChildEnd::Exited) with one (`None` if it was ended by a
/// signal, or was stopped).
pub exit_code: Option<i32>,
/// Whether it exited with status 0. `None` unless it exited.
pub success: Option<bool>,
/// Why it could not be started.
pub error: Option<String>,
}
/// One display of a recording, with the frames recorded for it.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct RecordedDisplay {
/// The display id (what `--display` takes).
pub id: u32,
/// Frames of video written for it, across its segments.
pub frames: u64,
/// How many video files it has: a display that was unplugged or slept and came back starts a
/// new one.
pub segments: usize,
}
/// The `data` of `record --json`: what the recording that has just finished holds.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct RecordData {
/// The session directory, as an absolute path where it could be made one.
pub session: String,
/// Seconds of video (or, with no video, of recording).
pub duration_s: f64,
/// The displays that were recorded, with their frames; empty for a recording without video.
pub displays: Vec<RecordedDisplay>,
/// Bytes of komorebi's log recorded.
pub log_bytes: u64,
/// komorebi events recorded.
pub events: u64,
/// OS trace records recorded, across streams.
pub oslog_events: u64,
/// What the recorder warned about.
pub warnings: Vec<String>,
/// The command of `--until-exit`, and how it ended; `None` without `--until-exit`.
pub child: Option<ChildReport>,
}
/// One display that can be recorded.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct DisplayView {
/// The id `--display` takes.
pub id: u32,
/// Width in points.
pub width_points: i64,
/// Height in points.
pub height_points: i64,
/// Where the display's top left corner is, x.
pub x: f64,
/// Where the display's top left corner is, y.
pub y: f64,
}
/// The `data` of `displays --json`.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct DisplaysData {
/// The displays that can be recorded.
pub displays: Vec<DisplayView>,
}
/// The `data` of `reindex --json`.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct ReindexData {
/// The session directory.
pub session: String,
/// Notes on what was recovered; empty if the session had been finished properly.
pub recovered: Vec<String>,
/// How many records the rebuilt index has.
pub entries: u64,
/// How many of those are from each source.
pub by_source: std::collections::BTreeMap<String, u64>,
}
/// One reading of the self-test.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct SelftestSample {
/// Where in the video it was taken, in seconds.
pub video_s: f64,
/// The clock shown in the video minus the clock the manifest predicts, in milliseconds.
pub error_ms: f64,
}
/// The `data` of `selftest --json`. A self-test that fails is reported as a failed envelope instead.
#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)]
pub struct SelftestData {
/// The self-test's recording.
pub session: String,
/// Whether the worst error was within the tolerance (always `true` here).
pub passed: bool,
/// The largest disagreement, in milliseconds.
pub max_abs_error_ms: f64,
/// The mean disagreement, in milliseconds: the clock is painted slightly before it is shown.
pub mean_bias_ms: f64,
/// The tolerance asked for, in milliseconds.
pub tolerance_ms: f64,
/// The readings.
pub samples: Vec<SelftestSample>,
}
+226 -17
View File
@@ -4,6 +4,9 @@
//! window and `gui` opens the recorder window with the same options as its starting settings.
//! [`RecordArgs::to_options`] turns them into the [`RecordOptions`] that [`recorder::record`] takes.
//!
//! `record --until-exit -- <command>` runs a command while recording and stops when it exits (see
//! [`super::until_exit`]); `--json` prints the result as a `record/1` envelope ([`super::outputs`]).
//!
//! `record` installs a Ctrl-C handler that asks the recorder to stop (`--duration` stops it too),
//! runs the recorder on a thread of its own, and meanwhile prints to standard error: the
//! session directory and any start-up warnings once, then a line of counters (time, frames, bytes
@@ -17,6 +20,18 @@
//! The commands need the outside world (a screen, and komorebi unless `--no-komorebi`), so they have
//! no example; [`RecordArgs::to_options`] does.
use super::outputs::ChildEnd;
use super::outputs::ChildReport;
use super::outputs::DisplayView;
use super::outputs::DisplaysData;
use super::outputs::RecordData;
use super::outputs::RecordedDisplay;
use super::outputs::SCHEMA_DISPLAYS;
use super::outputs::SCHEMA_RECORD;
use super::print_json;
use super::until_exit;
use crate::analysis::envelope;
use crate::analysis::envelope::Envelope;
use crate::capture::CaptureConfig;
use crate::capture::Codec;
use crate::platform::capture;
@@ -25,6 +40,7 @@ use crate::recorder::AppsMode;
use crate::recorder::Live;
use crate::recorder::OsLogOptions;
use crate::recorder::RecordOptions;
use crate::session::Manifest;
use crate::session::Session;
use crate::sources::oslog::OsLogLevel;
use crate::timecode;
@@ -120,6 +136,21 @@ pub struct RecordArgs {
/// Never trace this application (repeatable), e.g. a chatty one
#[arg(long = "oslog-exclude", value_name = "NAME")]
pub oslog_exclude: Vec<String>,
/// `record` only: print the result as a JSON envelope (`record/1`) on standard output; progress
/// still goes to standard error
#[arg(long)]
pub json: bool,
/// `record` only: run the command after `--` while recording and stop when it exits (or at
/// `--duration` or Ctrl-C, whichever is first; that terminates the command). It gets
/// KOMOREBI_RECORDER_SESSION, the session directory, in its environment, and runs in the
/// current directory with this terminal's output. The exit status of `record` is about the
/// recording (0 when the session was finalised), never the command's: that is in the summary
/// and in `--json`
#[arg(long, requires = "command")]
pub until_exit: bool,
/// The command for `--until-exit`, after `--`: `record --until-exit -- ./repro.sh arg`
#[arg(last = true, value_name = "COMMAND", requires = "until_exit")]
pub command: Vec<String>,
}
impl Default for RecordArgs {
@@ -145,6 +176,9 @@ impl Default for RecordArgs {
trace_processes: Vec::new(),
trace_pids: Vec::new(),
oslog_exclude: Vec::new(),
json: false,
until_exit: false,
command: Vec::new(),
}
}
}
@@ -240,8 +274,36 @@ impl RecordArgs {
}
}
pub(super) fn displays() -> eyre::Result<()> {
for display in capture::active_displays()? {
/// The arguments of `displays`.
#[derive(Args, Debug)]
pub struct DisplaysArgs {
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
}
pub(super) fn displays(args: &DisplaysArgs) -> eyre::Result<()> {
let found = capture::active_displays()?;
if args.json {
return print_json(&Envelope::ok(
SCHEMA_DISPLAYS,
DisplaysData {
displays: found
.iter()
.map(|display| DisplayView {
id: display.id,
width_points: display.width_points,
height_points: display.height_points,
x: display.frame[0],
y: display.frame[1],
})
.collect(),
},
));
}
for display in found {
println!(
"{} {}x{} points at ({}, {})",
display.id,
@@ -255,7 +317,87 @@ pub(super) fn displays() -> eyre::Result<()> {
Ok(())
}
/// Waits until the recording is under way and its session directory exists, or returns `None` if the
/// recorder ended first (it failed to start).
fn wait_until_recording<T>(
live: &Live,
worker: &std::thread::JoinHandle<T>,
) -> Option<recorder::LiveSnapshot> {
loop {
let snapshot = live.snapshot();
if snapshot.phase == recorder::Phase::Recording && snapshot.session_dir.is_some() {
return Some(snapshot);
}
if worker.is_finished() {
return None;
}
std::thread::sleep(Duration::from_millis(20));
}
}
fn announce(snapshot: &recorder::LiveSnapshot, until_exit: bool) {
if let Some(dir) = &snapshot.session_dir {
eprintln!(
"recording to {} ({})",
dir.display(),
if until_exit {
"stops when the command exits; Ctrl-C to stop sooner"
} else {
"Ctrl-C to stop"
}
);
}
for warning in &snapshot.warnings {
eprintln!("warning: {warning}");
}
}
/// What the finished session holds, as `record --json` prints it.
fn record_data(
dir: &std::path::Path,
manifest: &Manifest,
child: Option<ChildReport>,
) -> RecordData {
let (_, duration) = manifest.video_span();
let displays = manifest
.display_ids()
.into_iter()
.map(|id| {
let segments: Vec<_> = manifest
.displays
.iter()
.filter(|entry| entry.result.display.id == id)
.collect();
RecordedDisplay {
id,
frames: segments.iter().map(|entry| entry.result.frames).sum(),
segments: segments.len(),
}
})
.collect();
RecordData {
session: std::path::absolute(dir)
.unwrap_or_else(|_| dir.to_path_buf())
.display()
.to_string(),
duration_s: duration,
displays,
log_bytes: manifest.log_segments.iter().map(|s| s.len()).sum(),
events: manifest.events.events,
oslog_events: manifest.oslog.iter().map(|stream| stream.events).sum(),
warnings: manifest.warnings.clone(),
child,
}
}
pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
if args.until_exit && args.command.is_empty() {
return Err(envelope::usage(
"--until-exit needs a command after `--`: record --until-exit -- <command> [args...]",
));
}
let live = Live::new();
let handler_live = live.clone();
ctrlc::set_handler(move || handler_live.request_stop())
@@ -268,6 +410,35 @@ pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
.spawn(move || recorder::record(&options, &worker_live))?;
let mut announced = false;
let mut child = None;
if args.until_exit
&& let Some(snapshot) = wait_until_recording(&live, &worker)
{
announce(&snapshot, true);
announced = true;
let dir = snapshot.session_dir.unwrap_or_default();
let command = args.command.clone();
let child_live = live.clone();
child = Some(
std::thread::Builder::new()
.name("until-exit".to_string())
.spawn(move || {
until_exit::supervise(
&command,
&dir,
|| {
child_live.stop_requested()
|| !matches!(
child_live.snapshot().phase,
recorder::Phase::Starting | recorder::Phase::Recording
)
},
|| child_live.request_stop(),
)
})?,
);
}
while !worker.is_finished() {
std::thread::sleep(Duration::from_millis(500));
let snapshot = live.snapshot();
@@ -275,12 +446,7 @@ pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
if snapshot.phase == recorder::Phase::Recording {
if !announced {
announced = true;
if let Some(dir) = &snapshot.session_dir {
eprintln!("recording to {} (Ctrl-C to stop)", dir.display());
}
for warning in &snapshot.warnings {
eprintln!("warning: {warning}");
}
announce(&snapshot, false);
}
eprint!(
@@ -295,12 +461,35 @@ pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
}
eprintln!();
let dir = worker
let recorded = worker
.join()
.map_err(|_| eyre::Report::msg("the recording thread panicked"))??;
.map_err(|_| eyre::Report::msg("the recording thread panicked"));
let child = match child {
Some(handle) => Some(
handle
.join()
.map_err(|_| eyre::Report::msg("the thread running the command panicked"))?,
),
None if args.until_exit => Some(ChildReport {
command: args.command.clone(),
end: ChildEnd::NotStarted,
exit_code: None,
success: None,
error: None,
}),
None => None,
};
let dir = recorded??;
let session = Session::open(&dir)?;
let manifest = session.manifest()?;
let data = record_data(&dir, &manifest, child);
if args.json {
let warnings = data.warnings.clone();
return print_json(&Envelope::ok(SCHEMA_RECORD, data).warnings(warnings));
}
let (_, duration) = manifest.video_span();
println!("session: {}", dir.display());
if manifest.displays.is_empty() {
@@ -310,18 +499,17 @@ pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
}
println!(
"recorded: {} komorebi log bytes, {} events, {} OS trace events across {} streams",
manifest.log_segments.iter().map(|s| s.len()).sum::<u64>(),
manifest.events.events,
manifest
.oslog
.iter()
.map(|stream| stream.events)
.sum::<u64>(),
data.log_bytes,
data.events,
data.oslog_events,
manifest.oslog.len(),
);
for warning in &manifest.warnings {
println!("warning: {warning}");
}
if let Some(child) = &data.child {
println!("command: {}", child_summary(child));
}
println!(
"\nquery it: komorebi-recorder at {} <timecode>\n komorebi-recorder summary {}",
dir.display(),
@@ -330,3 +518,24 @@ pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
Ok(())
}
/// Says what became of the `--until-exit` command in a line.
fn child_summary(child: &ChildReport) -> String {
let command = child.command.join(" ");
match child.end {
ChildEnd::Exited => match child.exit_code {
Some(code) => format!(
"{command} exited with status {code} (the recorder's own status is about the recording)"
),
None => format!("{command} was ended by a signal"),
},
ChildEnd::Stopped => {
format!("{command} was still running when the recording ended, and was terminated")
}
ChildEnd::FailedToStart => format!(
"{command} did not run: {}",
child.error.as_deref().unwrap_or("it could not be started")
),
ChildEnd::NotStarted => format!("{command} was not started: the recording failed first"),
}
}
+456
View File
@@ -0,0 +1,456 @@
//! Evidence references that name a log line by what it says or when it was written.
//!
//! `annotate add --ref log:345` says which line of komorebi's log by number, which an agent has to
//! find out first. [`resolve`] lets it say what it means instead, and turns that into the
//! `log:<line>` that [`crate::annotations::Ref`] reads:
//!
//! | Written | Means |
//! |---|---|
//! | `log:345`, `log:<file>:<line>` | that line, as before |
//! | `log:"some text"` (or in single quotes) | the one line of `komorebi.log` that contains the text, ignoring case |
//! | `log:HH:MM:SS.mmm` | the line written at that UTC time, as the log has it; as precise as it is written (`HH:MM:SS` matches the whole second) |
//! | `log:12.5`, `log:1:02.5` | the line nearest that time of the video |
//!
//! A text or a UTC time that matches more than one line is a usage error that lists the first few as
//! `log:N: text`, so the author can pick one or say more. A match is reported back as the resolved
//! `log:N` and the text of the line, so that the author can check it is the statement they meant.
//! Quote the whole argument for the shell: `--ref 'log:"could not find"'`.
use crate::analysis::envelope;
use crate::annotations::DEFAULT_LOG_FILE;
use crate::clock::ClockMap;
use crate::session::Manifest;
use crate::session::Session;
use crate::sources::komorebi_log;
use crate::timecode;
use chrono::DateTime;
use chrono::Timelike;
use chrono::Utc;
use color_eyre::eyre;
/// How many candidate lines an ambiguous reference lists.
const CANDIDATES: usize = 5;
/// A reference, with what to tell the author if it was not written as a line number.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Resolved {
/// The reference to parse: `text` itself, or the `log:<line>` it resolved to.
pub reference: String,
/// For a resolved reference: what it resolved to, and the text of the line.
pub note: Option<String>,
}
/// How the part of a `log:` reference after the colon is to be read.
#[derive(Debug, PartialEq)]
enum Spelling {
/// A line number, or `<file>:<line>`: [`crate::annotations::Ref`] reads it.
Line,
/// Text to find in the log.
Text(String),
/// A UTC time of day in microseconds, and how many microseconds the way it was written spans.
Utc { micros_of_day: u64, span: u64 },
/// Seconds of video time.
Video(f64),
/// Words that are not quoted: an error, with a hint.
Unquoted,
}
fn classify(rest: &str) -> Spelling {
if rest.parse::<u64>().is_ok() {
return Spelling::Line;
}
for quote in ['"', '\''] {
if rest.len() >= 2 && rest.starts_with(quote) && rest.ends_with(quote) {
return Spelling::Text(rest[1..rest.len() - 1].to_string());
}
}
if let Some(utc) = utc_of_day(rest) {
return utc;
}
let numeric = rest
.chars()
.all(|character| character.is_ascii_digit() || character == ':' || character == '.');
if numeric
&& rest.contains('.')
&& let Ok(video_s) = timecode::parse(rest)
{
return Spelling::Video(video_s);
}
// `<file>:<line>` is for Ref; anything else with words in it was probably meant as text
let is_file_and_line = rest
.rsplit_once(':')
.is_some_and(|(_, line)| line.parse::<u64>().is_ok());
if !is_file_and_line && rest.contains(char::is_whitespace) {
return Spelling::Unquoted;
}
Spelling::Line
}
/// Reads `HH:MM:SS` or `HH:MM:SS.fraction` (up to microseconds; more digits are ignored).
fn utc_of_day(text: &str) -> Option<Spelling> {
let (clock, fraction) = match text.split_once('.') {
Some((clock, fraction)) => (clock, Some(fraction)),
None => (text, None),
};
let mut parts = clock.split(':');
let (hours, minutes, seconds) = (parts.next()?, parts.next()?, parts.next()?);
if parts.next().is_some() || hours.len() > 2 || minutes.len() != 2 || seconds.len() != 2 {
return None;
}
let (hours, minutes, seconds): (u64, u64, u64) = (
hours.parse().ok()?,
minutes.parse().ok()?,
seconds.parse().ok()?,
);
if hours > 23 || minutes > 59 || seconds > 59 {
return None;
}
let (micros, span) = match fraction {
None => (0, 1_000_000),
Some(fraction) if !fraction.is_empty() && fraction.chars().all(|c| c.is_ascii_digit()) => {
let digits = fraction.len().min(6);
let padded = format!("{:0<6}", &fraction[..digits]);
(padded.parse().ok()?, 10_u64.pow(6 - digits as u32))
}
Some(_) => return None,
};
Some(Spelling::Utc {
micros_of_day: ((hours * 60 + minutes) * 60 + seconds) * 1_000_000 + micros,
span,
})
}
/// A line of the log: its number, its own time (none for a continuation line) and its text.
struct Line {
number: u64,
own_time: Option<DateTime<Utc>>,
text: String,
}
fn read_log(session: &Session) -> eyre::Result<Vec<Line>> {
let bytes = std::fs::read(session.path(DEFAULT_LOG_FILE)).map_err(|_| {
envelope::not_found(format!(
"the session has no {DEFAULT_LOG_FILE}, so a log reference cannot be found by text or time"
))
})?;
Ok(komorebi_log::index_lines(&bytes)
.into_iter()
.zip(bytes.split_inclusive(|byte| *byte == b'\n'))
.map(|(line, raw)| Line {
number: line.number,
own_time: (!line.is_continuation).then_some(line.timestamp).flatten(),
text: String::from_utf8_lossy(raw).trim_end().to_string(),
})
.collect())
}
/// The line without its timestamp, for matching and showing.
fn message(line: &Line) -> &str {
if line.own_time.is_some() {
line.text
.split_once(char::is_whitespace)
.map_or("", |(_, rest)| rest.trim_start())
} else {
line.text.trim()
}
}
fn shown(line: &Line) -> String {
let message = message(line);
let mut text: String = message.chars().take(160).collect();
if message.chars().count() > 160 {
text.push_str("...");
}
format!("log:{}: {text}", line.number)
}
fn ambiguous(what: &str, matches: &[&Line]) -> eyre::Report {
let mut listed: Vec<String> = matches
.iter()
.take(CANDIDATES)
.map(|line| format!(" {}", shown(line)))
.collect();
if matches.len() > CANDIDATES {
listed.push(format!(" ... and {} more", matches.len() - CANDIDATES));
}
envelope::usage(format!(
"{what} matches {} lines of {DEFAULT_LOG_FILE}; say which with log:<N>, or say more:\n{}",
matches.len(),
listed.join("\n")
))
}
fn resolved(input: &str, line: &Line) -> Resolved {
Resolved {
reference: format!("log:{}", line.number),
note: Some(format!(
"{input} resolved to {}; check that is the statement you meant",
shown(line)
)),
}
}
fn micros_of_day(time: DateTime<Utc>) -> u64 {
u64::from(time.num_seconds_from_midnight()) * 1_000_000
+ u64::from(time.timestamp_subsec_micros())
}
/// Returns the reference `text` stands for: itself, unless it is a `log:` reference that names a
/// line by text or time, in which case it is `log:<line>` with a note of what was chosen.
///
/// # Errors
///
/// A usage error if the text matches more than one line (the first few are listed), or is words
/// that are not quoted; a not-found error if nothing matches or the session has no
/// `komorebi.log`.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::cli::refspec::resolve;
/// use komorebi_recorder::testkit::SessionBuilder;
///
/// let (session, manifest) = SessionBuilder::new("doc-refspec")
/// .log(2.0, "INFO", "komorebi::process_event: processing event")
/// .log(3.0, "WARN", "komorebi::window: could not place the window")
/// .build();
///
/// // by what the line says
/// let found = resolve(&session, &manifest, "log:\"could not place\"")?;
/// assert_eq!(found.reference, "log:2");
/// assert!(found.note.is_some_and(|note| note.contains("could not place the window")));
///
/// // by when it was written (the testkit's clock reads 12:00:07 at video second 2.0)
/// let by_time = resolve(&session, &manifest, "log:12:00:07.000")?;
/// assert_eq!(by_time.reference, "log:1");
///
/// // a line number is left alone
/// assert_eq!(resolve(&session, &manifest, "log:7")?.reference, "log:7");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn resolve(session: &Session, manifest: &Manifest, text: &str) -> eyre::Result<Resolved> {
let unchanged = || Resolved {
reference: text.to_string(),
note: None,
};
let Some(rest) = text.strip_prefix("log:") else {
return Ok(unchanged());
};
match classify(rest) {
Spelling::Line => Ok(unchanged()),
Spelling::Unquoted => Err(envelope::usage(format!(
"'{text}': to find a log line by its text, quote the text: log:\"{rest}\" \
(quote the whole argument for the shell)"
))),
Spelling::Text(needle) => {
if needle.trim().is_empty() {
return Err(envelope::usage("'log:\"\"': there is no text to look for"));
}
let lines = read_log(session)?;
let lowered = needle.to_lowercase();
let matches: Vec<&Line> = lines
.iter()
.filter(|line| message(line).to_lowercase().contains(&lowered))
.collect();
match matches[..] {
[] => Err(envelope::not_found(format!(
"no line of {DEFAULT_LOG_FILE} contains \"{needle}\""
))),
[line] => Ok(resolved(text, line)),
_ => Err(ambiguous(&format!("\"{needle}\""), &matches)),
}
}
Spelling::Utc {
micros_of_day: wanted,
span,
} => {
let lines = read_log(session)?;
let matches: Vec<&Line> = lines
.iter()
.filter(|line| {
line.own_time
.is_some_and(|time| (wanted..wanted + span).contains(&micros_of_day(time)))
})
.collect();
match matches[..] {
[] => Err(envelope::not_found(format!(
"no line of {DEFAULT_LOG_FILE} was written at {rest} UTC{}",
nearest(&lines, wanted).map_or_else(String::new, |line| format!(
"; the nearest is {}",
shown(line)
))
))),
[line] => Ok(resolved(text, line)),
_ => Err(ambiguous(&format!("{rest} UTC"), &matches)),
}
}
Spelling::Video(video_s) => {
let lines = read_log(session)?;
let clock = ClockMap::new(manifest.anchors.clone());
let wall_us = clock
.mach_to_wall(manifest.mach_at_video_seconds(video_s))
.ok_or_else(|| {
envelope::unusable("the session has no clock anchors to convert a video time")
})?;
let wanted = DateTime::from_timestamp_micros(wall_us)
.map(micros_of_day)
.ok_or_else(|| envelope::usage(format!("{rest} is not a time")))?;
let line = nearest(&lines, wanted).ok_or_else(|| {
envelope::not_found(format!("{DEFAULT_LOG_FILE} has no timestamped line"))
})?;
Ok(resolved(text, line))
}
}
}
/// The line written nearest to a time of day (the earlier of two equally near).
fn nearest(lines: &[Line], wanted: u64) -> Option<&Line> {
lines
.iter()
.filter_map(|line| Some((line, micros_of_day(line.own_time?))))
.min_by_key(|(_, micros)| micros.abs_diff(wanted))
.map(|(line, _)| line)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::testkit::SessionBuilder;
#[test]
fn how_a_log_reference_is_spelled() {
assert_eq!(classify("345"), Spelling::Line);
assert_eq!(classify("oslog/komorebi.ndjson:77"), Spelling::Line);
assert_eq!(
classify("\"two words\""),
Spelling::Text("two words".to_string())
);
assert_eq!(classify("'it'"), Spelling::Text("it".to_string()));
assert_eq!(
classify("12:00:08.250"),
Spelling::Utc {
micros_of_day: 43_208_250_000,
span: 1_000
}
);
assert_eq!(
classify("12:00:08"),
Spelling::Utc {
micros_of_day: 43_208_000_000,
span: 1_000_000
}
);
assert_eq!(classify("12.5"), Spelling::Video(12.5));
assert_eq!(classify("1:02.5"), Spelling::Video(62.5));
assert_eq!(classify("some words"), Spelling::Unquoted);
// not a time of day
assert_eq!(classify("25:00:00"), Spelling::Line);
}
fn session(name: &str) -> (Session, Manifest) {
SessionBuilder::new(name)
.log(2.0, "INFO", "komorebi::process_event: processing event")
.log(3.0, "WARN", "komorebi::window: could not place the window")
.log(3.0, "INFO", "komorebi::process_event: processing event")
.log(5.0, "INFO", "komorebi::reaper: reaping orphans")
.build()
}
#[test]
fn text_resolves_to_its_one_line_and_says_which() {
let (session, manifest) = session("refspec-text");
let found = resolve(&session, &manifest, "log:\"REAPING\"").expect("one match");
assert_eq!(found.reference, "log:4");
let note = found.note.expect("a note");
assert!(
note.contains("log:4: INFO komorebi::reaper: reaping orphans"),
"{note}"
);
}
#[test]
fn text_that_matches_several_lines_lists_candidates() {
let (session, manifest) = session("refspec-ambiguous");
let error = resolve(&session, &manifest, "log:\"processing event\"").unwrap_err();
assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::Usage);
let message = error.to_string();
assert!(message.contains("matches 2 lines"), "{message}");
assert!(
message.contains("log:1: INFO komorebi::process_event"),
"{message}"
);
assert!(
message.contains("log:3: INFO komorebi::process_event"),
"{message}"
);
}
#[test]
fn text_that_matches_nothing_is_not_found() {
let (session, manifest) = session("refspec-none");
let error = resolve(&session, &manifest, "log:\"nothing like it\"").unwrap_err();
assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::NotFound);
}
#[test]
fn a_utc_time_is_as_precise_as_it_is_written() {
let (session, manifest) = session("refspec-utc");
// video 2.0 is 12:00:07.000 (the testkit's video starts 5 s after the clock's zero)
let exact = resolve(&session, &manifest, "log:12:00:07.000").expect("exact");
assert_eq!(exact.reference, "log:1");
// a whole second holds the two lines of 12:00:08
let error = resolve(&session, &manifest, "log:12:00:08").unwrap_err();
assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::Usage);
assert!(error.to_string().contains("log:2:"), "{error}");
// nothing was written then: the nearest line is offered
let error = resolve(&session, &manifest, "log:12:00:30.000").unwrap_err();
assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::NotFound);
assert!(
error.to_string().contains("the nearest is log:4"),
"{error}"
);
}
#[test]
fn a_video_time_resolves_to_the_nearest_line() {
let (session, manifest) = session("refspec-video");
let found = resolve(&session, &manifest, "log:4.9").expect("nearest");
assert_eq!(found.reference, "log:4");
}
#[test]
fn what_is_not_a_text_or_time_reference_is_left_alone() {
let (session, manifest) = session("refspec-alone");
for text in [
"log:2",
"event:3",
"code:komorebi/src/window.rs:210",
"log:other.log:9",
] {
let found = resolve(&session, &manifest, text).expect("left alone");
assert_eq!(
found,
Resolved {
reference: text.to_string(),
note: None
}
);
}
let error = resolve(&session, &manifest, "log:could not place").unwrap_err();
assert!(error.to_string().contains("quote the text"), "{error}");
}
}
+213
View File
@@ -0,0 +1,213 @@
//! `record --until-exit -- <command>`: run a command while recording, and stop when it exits.
//!
//! The recording is the point and the command is what is being recorded: a script that reproduces a
//! bug, run so that the screen, komorebi's log and its events are captured exactly while it runs.
//! [`supervise`] starts the command once the recording is under way (so that the session directory
//! exists), with [`SESSION_ENV`] set to that directory, and watches it. The command inherits the
//! recorder's standard streams and working directory, so its output is visible and relative paths
//! mean what the user meant.
//!
//! * When the command exits, the recording is asked to stop.
//! * When the recording ends first (Ctrl-C, `--duration`), the command is terminated.
//!
//! The recorder's exit status is about the recording, not the command: it is 0 when the session was
//! finalised, whatever the command's status was. The command's status is in the summary and in
//! `record --json` ([`ChildReport`]).
use super::outputs::ChildEnd;
use super::outputs::ChildReport;
use crate::platform::process;
use std::path::Path;
use std::process::Command;
use std::time::Duration;
/// The environment variable the command is given: the session directory being recorded to, as an
/// absolute path. `mark` and `annotate` read it when they are not given a session.
pub const SESSION_ENV: &str = "KOMOREBI_RECORDER_SESSION";
/// How often the command is looked at.
const POLL: Duration = Duration::from_millis(50);
/// Runs `command` (a program and its arguments) with [`SESSION_ENV`] set to `session_dir`, until it
/// exits or `recording_over` says the recording has ended, and says what became of it.
///
/// `on_exit` is called when the command exits (or cannot be started), and is how the caller stops
/// the recording. `recording_over` is asked every 50 ms while the command runs; when it is true the
/// command is terminated (see [`process::terminate`]) and waited for. This blocks until the command
/// has gone.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::cli::outputs::ChildEnd;
/// use komorebi_recorder::cli::until_exit::supervise;
/// use std::sync::atomic::{AtomicBool, Ordering};
///
/// let stopped = AtomicBool::new(false);
/// let command: Vec<String> = if cfg!(windows) {
/// ["cmd", "/c", "exit 3"].map(String::from).to_vec()
/// } else {
/// ["sh", "-c", "exit 3"].map(String::from).to_vec()
/// };
///
/// let report = supervise(
/// &command,
/// std::path::Path::new("some-session"),
/// || false,
/// || stopped.store(true, Ordering::SeqCst),
/// );
///
/// // the command's own status is reported, and the recording was asked to stop
/// assert_eq!(report.end, ChildEnd::Exited);
/// assert_eq!(report.exit_code, Some(3));
/// assert_eq!(report.success, Some(false));
/// assert!(stopped.load(Ordering::SeqCst));
/// ```
pub fn supervise(
command: &[String],
session_dir: &Path,
recording_over: impl Fn() -> bool,
on_exit: impl Fn(),
) -> ChildReport {
let report = |end, exit_code: Option<i32>, error: Option<String>| ChildReport {
command: command.to_vec(),
end,
exit_code,
success: (end == ChildEnd::Exited).then(|| exit_code == Some(0)),
error,
};
let Some((program, arguments)) = command.split_first() else {
on_exit();
return report(
ChildEnd::FailedToStart,
None,
Some("there is no command to run".to_string()),
);
};
let absolute = std::path::absolute(session_dir).unwrap_or_else(|_| session_dir.to_path_buf());
let mut child = match process::isolate(
Command::new(program)
.args(arguments)
.env(SESSION_ENV, absolute),
)
.spawn()
{
Ok(child) => child,
Err(error) => {
on_exit();
return report(
ChildEnd::FailedToStart,
None,
Some(format!("could not start {program}: {error}")),
);
}
};
loop {
match child.try_wait() {
Ok(Some(status)) => {
on_exit();
return report(ChildEnd::Exited, status.code(), None);
}
Ok(None) => {}
Err(error) => {
process::terminate(&mut child);
let _ = child.wait();
on_exit();
return report(
ChildEnd::FailedToStart,
None,
Some(format!("could not wait for {program}: {error}")),
);
}
}
if recording_over() {
process::terminate(&mut child);
let _ = child.wait();
return report(ChildEnd::Stopped, None, None);
}
std::thread::sleep(POLL);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
fn shell(script: &str) -> Vec<String> {
if cfg!(windows) {
vec!["cmd".into(), "/c".into(), script.into()]
} else {
vec!["sh".into(), "-c".into(), script.into()]
}
}
#[test]
fn a_command_that_exits_stops_the_recording_and_keeps_its_status() {
let stop = AtomicBool::new(false);
let report = supervise(
&shell("exit 0"),
Path::new("."),
|| false,
|| stop.store(true, Ordering::SeqCst),
);
assert_eq!(report.end, ChildEnd::Exited);
assert_eq!(report.exit_code, Some(0));
assert_eq!(report.success, Some(true));
assert!(stop.load(Ordering::SeqCst));
}
#[test]
fn the_command_is_told_which_session_it_is_recorded_in() {
let check = if cfg!(windows) {
format!("if defined {SESSION_ENV} (exit 0) else (exit 7)")
} else {
format!("[ -n \"${SESSION_ENV}\" ] && exit 0 || exit 7")
};
let report = supervise(&shell(&check), Path::new("a-session"), || false, || {});
assert_eq!(report.exit_code, Some(0), "{report:?}");
}
#[test]
fn a_recording_that_ends_first_terminates_the_command() {
let sleeper = if cfg!(windows) {
shell("ping -n 30 127.0.0.1 >nul")
} else {
shell("sleep 30")
};
let started = std::time::Instant::now();
let report = supervise(&sleeper, Path::new("."), || true, || {});
assert_eq!(report.end, ChildEnd::Stopped);
assert_eq!(report.exit_code, None);
assert_eq!(report.success, None);
assert!(started.elapsed() < Duration::from_secs(20));
}
#[test]
fn a_command_that_cannot_start_is_reported_and_stops_the_recording() {
let stop = AtomicBool::new(false);
let report = supervise(
&["komorebi-recorder-no-such-program".to_string()],
Path::new("."),
|| false,
|| stop.store(true, Ordering::SeqCst),
);
assert_eq!(report.end, ChildEnd::FailedToStart);
assert!(
report
.error
.is_some_and(|error| error.contains("could not start"))
);
assert!(stop.load(Ordering::SeqCst));
}
}
+9 -1
View File
@@ -22,6 +22,11 @@ was marked the brief says so: ask the user when it happened and what they saw, t
komorebi-recorder annotate <session> add --kind bug --start <t> --end <t> --text "<what is wrong>"
With little context to spare, `komorebi-recorder brief <session> --compact` is the same start in about 40 lines: the
user's words, one line on the state, the top 3 findings with their references and the exact next commands.
`komorebi-recorder findings <session>` lists everything the detectors found and any findings already recorded (`--kind`,
`--severity`, `--limit`); each detector finding has a stable id, `f-xxxxxx`.
The brief then gives, for each region: the events in it (echoes of komorebi's own moves are counted,
not listed), what looked wrong and for how long, the state as the bug began and as it ended and
what differs, what happened to the machine nearby (a display unplugged, a sleep), and the events most
@@ -116,7 +121,10 @@ locations as hints.
--ref event:<n> --ref log:<n> --ref code:<path>:<line>
A finding with no evidence is refused, and every reference is checked to exist. Cite evidence by
event number, log line, video time and state difference. Never claim a cause without a reference,
event number, log line, video time and state difference. A log line can be cited by its text,
`--ref 'log:"some text"'`, or its time, `--ref log:HH:MM:SS.mmm` (UTC, as the log has it) or `--ref log:12.5` (video):
the command prints the line it resolved to, so check it is the statement you meant; an ambiguous
text lists the candidates and is refused. Never claim a cause without a reference,
and say what you could not verify.
## 5. Propose the fix
+46 -4
View File
@@ -69,7 +69,11 @@
//! assert_eq!(verdict.samples[0].error_ms, -30.0);
//! ```
use crate::analysis::envelope::Envelope;
use crate::cli::SelftestArgs;
use crate::cli::outputs::SCHEMA_SELFTEST;
use crate::cli::outputs::SelftestData;
use crate::cli::outputs::SelftestSample;
use crate::clock;
use crate::frames;
use crate::platform::capture;
@@ -591,7 +595,7 @@ fn spawn_clock() -> eyre::Result<(
/// use komorebi_recorder::selftest::run;
///
/// // record for 8 seconds, and allow the video to disagree with the clocks by up to 100 ms
/// run(&SelftestArgs { seconds: 8.0, tolerance_ms: 100.0, out: None })?;
/// run(&SelftestArgs { seconds: 8.0, tolerance_ms: 100.0, out: None, json: false })?;
/// # Ok::<(), color_eyre::eyre::Report>(())
/// ```
///
@@ -686,12 +690,38 @@ pub fn run(args: &SelftestArgs) -> eyre::Result<()> {
}
let calibration = evaluate(&readings, args.tolerance_ms);
report(&calibration, &undecodable, &mut manifest);
report(&calibration, &undecodable, &mut manifest, args.json);
manifest.calibration = Some(calibration.clone());
session.write_manifest(&manifest)?;
println!("session: {}", dir.display());
if !args.json {
println!("session: {}", dir.display());
}
if calibration.passed {
if args.json {
let samples = &calibration.samples;
return crate::cli::print_json(
&Envelope::ok(
SCHEMA_SELFTEST,
SelftestData {
session: dir.display().to_string(),
passed: true,
max_abs_error_ms: calibration.max_abs_error_ms,
mean_bias_ms: samples.iter().map(|sample| sample.error_ms).sum::<f64>()
/ samples.len().max(1) as f64,
tolerance_ms: calibration.tolerance_ms,
samples: samples
.iter()
.map(|sample| SelftestSample {
video_s: sample.video_s,
error_ms: sample.error_ms,
})
.collect(),
},
)
.warnings(manifest.warnings.clone()),
);
}
Ok(())
} else {
Err(eyre::Report::msg(format!(
@@ -701,7 +731,19 @@ pub fn run(args: &SelftestArgs) -> eyre::Result<()> {
}
}
fn report(calibration: &Calibration, undecodable: &[f64], manifest: &mut Manifest) {
fn report(calibration: &Calibration, undecodable: &[f64], manifest: &mut Manifest, json: bool) {
if json {
// the readings are in the envelope; only the manifest's note is kept
if !undecodable.is_empty() {
manifest.warnings.push(format!(
"self-test could not read the clock at {} of {} sampled timestamps",
undecodable.len(),
undecodable.len() + calibration.samples.len()
));
}
return;
}
println!("video second | clock shown in video vs predicted");
for sample in &calibration.samples {
println!(
+354
View File
@@ -0,0 +1,354 @@
//! `findings`, `brief --compact`, log references by text or time, and `record --until-exit`,
//! through the real binary.
use komorebi_recorder::testkit::SessionBuilder;
use serde_json::Value;
use std::process::Command;
use std::process::Output;
fn recorder(args: &[&str]) -> Output {
Command::new(env!("CARGO_BIN_EXE_komorebi-recorder"))
.args(args)
.output()
.expect("run komorebi-recorder")
}
fn stdout(output: &Output) -> String {
String::from_utf8_lossy(&output.stdout).into_owned()
}
fn stderr(output: &Output) -> String {
String::from_utf8_lossy(&output.stderr).into_owned()
}
fn envelope(output: &Output) -> Value {
serde_json::from_slice(&output.stdout)
.unwrap_or_else(|error| panic!("not JSON ({error}): {}", stdout(output)))
}
/// A session with an error and a warning in komorebi's log, and a bug the user marked.
fn session(name: &str) -> String {
let (session, _) = SessionBuilder::new(name)
.log(2.0, "INFO", "komorebi::process_event: processing event")
.log(
3.0,
"ERROR",
"komorebi::window: could not place window 4711",
)
.log(4.0, "WARN", "komorebi::reaper: window 12 is gone")
.log(5.0, "INFO", "komorebi::process_event: processing event")
.build();
let dir = session.dir.display().to_string();
let added = recorder(&[
"annotate",
&dir,
"add",
"--kind",
"bug",
"--start",
"2.5",
"--end",
"6",
"--text",
"the window never appears",
]);
assert!(added.status.success(), "{}", stderr(&added));
dir
}
#[test]
fn findings_lists_detector_findings_with_stable_ids() {
let dir = session("findings-ids");
let first = envelope(&recorder(&["findings", &dir, "--json"]));
assert_eq!(first["ok"], true);
assert_eq!(first["schema"], "findings/1");
let items = first["data"]["findings"].as_array().expect("findings");
assert_eq!(first["data"]["detector"], 2);
assert_eq!(first["data"]["agent"], 0);
let error = items
.iter()
.find(|item| item["kind"] == "log-error")
.expect("log-error");
let id = error["id"].as_str().expect("id");
assert!(id.starts_with("f-") && id.len() == 8, "{id}");
assert_eq!(error["source"], "detector");
assert_eq!(error["severity"], "warn");
assert_eq!(error["refs"][0], "log:2");
// the same finding has the same id the next time
let second = envelope(&recorder(&["findings", &dir, "--json"]));
let again = second["data"]["findings"]
.as_array()
.expect("findings")
.iter()
.find(|item| item["kind"] == "log-error")
.expect("log-error");
assert_eq!(again["id"], id);
// the text form leads with the count and shows the id
let text = stdout(&recorder(&["findings", &dir]));
assert!(text.starts_with("2 finding(s)"), "{text}");
assert!(text.contains(id), "{text}");
}
#[test]
fn findings_merges_what_an_agent_concluded_and_filters() {
let dir = session("findings-merge");
let added = recorder(&[
"annotate",
&dir,
"add",
"--kind",
"finding",
"--start",
"3",
"--text",
"the placement failed because the window was already gone",
"--ref",
"log:2",
]);
assert!(added.status.success(), "{}", stderr(&added));
let all = envelope(&recorder(&["findings", &dir, "--json"]));
let items = all["data"]["findings"].as_array().expect("findings");
assert_eq!(all["data"]["total"], 3);
assert_eq!(all["data"]["agent"], 1);
// an agent's conclusions come first
assert_eq!(items[0]["source"], "agent");
assert_eq!(items[0]["kind"], "agent-finding");
assert!(items[0]["id"].as_str().expect("id").starts_with("a-"));
assert!(items[0]["severity"].is_null());
let by_kind = envelope(&recorder(&[
"findings",
&dir,
"--kind",
"log-warning",
"--json",
]));
assert_eq!(by_kind["data"]["total"], 1);
assert_eq!(by_kind["data"]["findings"][0]["kind"], "log-warning");
let by_severity = envelope(&recorder(&[
"findings",
&dir,
"--severity",
"warn",
"--json",
]));
assert_eq!(by_severity["data"]["total"], 1);
assert_eq!(by_severity["data"]["findings"][0]["kind"], "log-error");
let limited = envelope(&recorder(&["findings", &dir, "--limit", "1", "--json"]));
assert_eq!(
limited["data"]["findings"]
.as_array()
.expect("findings")
.len(),
1
);
assert_eq!(limited["data"]["total"], 3);
assert_eq!(limited["truncated"], true);
}
#[test]
fn a_compact_brief_is_short_and_keeps_the_users_words() {
let dir = session("brief-compact");
let text = recorder(&["brief", &dir, "--compact"]);
assert!(text.status.success(), "{}", stderr(&text));
let text = stdout(&text);
assert!(text.lines().count() <= 40, "{text}");
assert!(text.contains("the window never appears"), "{text}");
assert!(text.contains("could not place window 4711"), "{text}");
assert!(
text.contains(&format!("komorebi-recorder findings {dir}")),
"{text}"
);
let json = envelope(&recorder(&["brief", &dir, "--compact", "--json"]));
assert_eq!(json["schema"], "brief-compact/1");
assert_eq!(
json["data"]["regions"][0]["text"],
"the window never appears"
);
let top = json["data"]["top_findings"]
.as_array()
.expect("top findings");
assert!(top.len() <= 3 && !top.is_empty());
assert!(top[0]["id"].as_str().expect("id").starts_with("f-"));
assert!(!json["data"]["next"].as_array().expect("next").is_empty());
}
#[test]
fn a_log_reference_can_be_a_text_a_time_or_a_video_time() {
let dir = session("ref-resolve");
let add = |reference: &str| {
recorder(&[
"annotate", &dir, "add", "--kind", "finding", "--start", "3", "--text", "because",
"--ref", reference, "--json",
])
};
// by text: resolved to its line, and the line is shown
let by_text = add("log:\"could not place\"");
assert!(by_text.status.success(), "{}", stderr(&by_text));
let by_text = envelope(&by_text);
let refs = by_text["data"]["annotation"]["refs"][0].clone();
assert_eq!(refs["file"], "komorebi.log");
assert_eq!(refs["line"], 2);
let note = by_text["warnings"][0].as_str().expect("a note");
assert!(
note.contains("log:2: ERROR komorebi::window: could not place window 4711"),
"{note}"
);
// by UTC time (video 4.0 is 12:00:09.000 on the testkit's clock)
let by_time = envelope(&add("log:12:00:09.000"));
assert_eq!(by_time["data"]["annotation"]["refs"][0]["line"], 3);
// by video time
let by_video = envelope(&add("log:5.0"));
assert_eq!(by_video["data"]["annotation"]["refs"][0]["line"], 4);
// a line number is unchanged, and has nothing to say
let by_number = envelope(&add("log:1"));
assert_eq!(by_number["data"]["annotation"]["refs"][0]["line"], 1);
assert!(
by_number["warnings"]
.as_array()
.expect("warnings")
.is_empty()
);
}
#[test]
fn an_ambiguous_text_is_a_usage_error_that_lists_candidates() {
let dir = session("ref-ambiguous");
let output = recorder(&[
"annotate",
&dir,
"add",
"--kind",
"finding",
"--start",
"3",
"--text",
"because",
"--ref",
"log:\"processing event\"",
"--json",
]);
assert_eq!(output.status.code(), Some(2), "{}", stderr(&output));
let failure = envelope(&output);
assert_eq!(failure["ok"], false);
let message = failure["error"]["message"].as_str().expect("message");
assert!(message.contains("matches 2 lines"), "{message}");
assert!(
message.contains("log:1: INFO komorebi::process_event"),
"{message}"
);
assert!(
message.contains("log:4: INFO komorebi::process_event"),
"{message}"
);
// nothing was written
let listed = envelope(&recorder(&[
"annotations",
&dir,
"--kind",
"finding",
"--json",
]));
assert!(
listed["data"]["annotations"]
.as_array()
.expect("array")
.is_empty()
);
}
#[test]
fn the_new_outputs_are_registered_schemas() {
let listed = stdout(&recorder(&["schema"]));
for name in [
"record/1",
"displays/1",
"reindex/1",
"selftest/1",
"findings/1",
"brief-compact/1",
] {
assert!(listed.contains(name), "{name} is not listed: {listed}");
let schema = recorder(&["schema", name]);
assert!(schema.status.success(), "{name}: {}", stderr(&schema));
assert!(envelope(&schema).is_object());
}
}
#[test]
fn reindex_has_a_json_form() {
let dir = session("reindex-json");
let output = recorder(&["reindex", &dir, "--json"]);
assert!(output.status.success(), "{}", stderr(&output));
let envelope = envelope(&output);
assert_eq!(envelope["schema"], "reindex/1");
assert!(envelope["data"]["entries"].as_u64().is_some());
assert!(envelope["data"]["recovered"].as_array().is_some());
}
#[test]
fn until_exit_needs_a_command_and_a_command_needs_until_exit() {
let missing = recorder(&["record", "--until-exit"]);
assert_eq!(missing.status.code(), Some(2));
let stray = recorder(&["record", "--", "cmd"]);
assert_eq!(stray.status.code(), Some(2));
}
/// A real recording of everything that needs no screen and no komorebi, which a command stops.
#[test]
fn recording_until_a_command_exits_reports_the_commands_status() {
let out = std::env::temp_dir().join(format!(
"komorebi-recorder-until-exit-{}",
std::process::id()
));
let _ = std::fs::remove_dir_all(&out);
let out_arg = out.display().to_string();
let command: &[&str] = if cfg!(windows) {
&["cmd", "/c", "exit 3"]
} else {
&["sh", "-c", "exit 3"]
};
let mut args = vec![
"record",
"--no-video",
"--no-komorebi",
"--no-oslog",
"--json",
"--until-exit",
"--out",
&out_arg,
"--",
];
args.extend_from_slice(command);
let output = recorder(&args);
// the recorder's status is about the recording, which finished
assert_eq!(output.status.code(), Some(0), "{}", stderr(&output));
let envelope = envelope(&output);
assert_eq!(envelope["schema"], "record/1");
assert_eq!(envelope["data"]["child"]["end"], "exited");
assert_eq!(envelope["data"]["child"]["exit_code"], 3);
assert_eq!(envelope["data"]["child"]["success"], false);
assert!(out.join("session.json").exists());
let _ = std::fs::remove_dir_all(&out);
}