From 1f6e4cef051ff1fbde19d4b25195289ff0f0d07b Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Wed, 28 Oct 2026 15:45:03 -0700 Subject: [PATCH] feat(logq): query komorebi's log by field, with counts and group-by logq 'level=ERROR and hwnd=0x77179C' filters komorebi.log by level, target, message, line, the span chain, the handled command and event, or any span field, with and/or/parentheses, = != ~ !~, --count, --group-by, --from/--to and a paged logq/1 envelope whose hits carry log:N references. hwnd compares equal in decimal and hex. logparse keeps the span chain as written (Line::chain). --- docs/usage/investigating-a-recording.md | 1 + komorebi-recorder/src/analysis/logparse.rs | 53 +- komorebi-recorder/src/analysis/logq.rs | 1019 ++++++++++++++++++++ komorebi-recorder/src/analysis/mod.rs | 1 + komorebi-recorder/src/analysis/schemas.rs | 6 + komorebi-recorder/src/cli/logq.rs | 116 +++ komorebi-recorder/src/cli/mod.rs | 6 + komorebi-recorder/src/guide.md | 6 + komorebi-recorder/tests/logq.rs | 184 ++++ 9 files changed, 1385 insertions(+), 7 deletions(-) create mode 100644 komorebi-recorder/src/analysis/logq.rs create mode 100644 komorebi-recorder/src/cli/logq.rs create mode 100644 komorebi-recorder/tests/logq.rs diff --git a/docs/usage/investigating-a-recording.md b/docs/usage/investigating-a-recording.md index 9f4f0004..26905c02 100644 --- a/docs/usage/investigating-a-recording.md +++ b/docs/usage/investigating-a-recording.md @@ -115,6 +115,7 @@ and `event:12.end` when it finished. | `trace event:N` | One event end to end: what its handler logged, with the source statement for each line, what other threads logged meanwhile, and every change with who made it (see below). `--os` adds the OS trace around it: komorebi's own calls into the OS, the system and each application, split into while the handler ran and after | | `window ID\|TEXT` | One window's life: when it appeared, moved, was parked off screen, was really somewhere else, and which event did each | | `code event:N`, `code log:N` | The line of komorebi's source that wrote a log line, with the code around it | +| `logq QUERY` | Query komorebi's log by field, with no escape codes or span prefixes to strip: `level=ERROR and message~ghost`, `hwnd=0x77179C` (decimal and hex are the same window), `command=MoveWindow`; `--count`, `--group-by FIELD`, `--from`/`--to`, `--spans` | | `search TEXT` | Where a word appears: komorebi's log, events, incidents, annotations (and `--oslog` for the macOS trace) | | `changes` | When and where on each display the picture changed, and which events fall inside | | `sheet` | A contact sheet image of frames with times, events and the bug region marked | diff --git a/komorebi-recorder/src/analysis/logparse.rs b/komorebi-recorder/src/analysis/logparse.rs index c7de825e..6558be47 100644 --- a/komorebi-recorder/src/analysis/logparse.rs +++ b/komorebi-recorder/src/analysis/logparse.rs @@ -112,6 +112,13 @@ pub struct Line { /// The spans the code was inside, outermost first. Empty for a line logged outside any span, /// such as one from another thread. pub spans: Vec, + /// The span chain as the log wrote it, ANSI removed: `process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}`. + /// Unlike [`Line::spans`] it keeps a span's braces exactly, so a span that is not `key=value` + /// fields (the argument of `process_command`) is still there. Empty when `spans` is. Not part + /// of the serialized line. + #[serde(skip)] + #[schemars(skip)] + pub chain: String, /// The module that logged, e.g. `komorebi::container`. `None` for a continuation and for a line /// in which none was found. pub target: Option, @@ -216,6 +223,7 @@ pub fn parse_line( continuation, level: None, spans: Vec::new(), + chain: String::new(), target: None, message: text.to_string(), }; @@ -236,18 +244,20 @@ pub fn parse_line( continuation: false, level: None, spans: Vec::new(), + chain: String::new(), target: None, message: after_time.to_string(), }; }; - let (spans, target, message) = parse_body(body.trim_start()); + let (spans, chain, target, message) = parse_body(body.trim_start()); Line { number, wall_us: time.map(|time| time.timestamp_micros()), continuation: false, level: Some(level), spans, + chain, target, message, } @@ -330,8 +340,10 @@ fn parse_fields(text: &str) -> Vec<(String, String)> { } /// The span chain, target and message of the part of a line after its level. -fn parse_body(body: &str) -> (Vec, Option, String) { +fn parse_body(body: &str) -> (Vec, String, Option, String) { let mut spans = Vec::new(); + // each span as written, parallel to `spans` + let mut raws: Vec<&str> = Vec::new(); let mut cursor = body; // spans: `name`, `name{fields}`, joined by `:`; the chain ends at `: ` @@ -348,13 +360,17 @@ fn parse_body(body: &str) -> (Vec, Option, String) { break; } - let (fields, tail) = if after.starts_with('{') { + let (fields, tail, raw) = if after.starts_with('{') { match braced(after) { - Some((inside, tail)) => (parse_fields(inside), tail), + Some((inside, tail)) => ( + parse_fields(inside), + tail, + &cursor[..cursor.len() - tail.len()], + ), None => break, } } else { - (Vec::new(), after) + (Vec::new(), after, name) }; if let Some(rest) = tail.strip_prefix(": ") { @@ -362,6 +378,7 @@ fn parse_body(body: &str) -> (Vec, Option, String) { name: name.to_string(), fields, }); + raws.push(raw); cursor = rest; break; } @@ -371,6 +388,7 @@ fn parse_body(body: &str) -> (Vec, Option, String) { name: name.to_string(), fields, }); + raws.push(raw); cursor = rest; continue; } @@ -390,6 +408,7 @@ fn parse_body(body: &str) -> (Vec, Option, String) { { return ( spans, + raws.join(":"), Some(target.to_string()), cursor[target_len + 1..].to_string(), ); @@ -399,10 +418,11 @@ fn parse_body(body: &str) -> (Vec, Option, String) { if spans.last().is_some_and(|last| last.fields.is_empty()) && let Some(last) = spans.pop() { - return (spans, Some(last.name), cursor.to_string()); + raws.pop(); + return (spans, raws.join(":"), Some(last.name), cursor.to_string()); } - (spans, None, cursor.to_string()) + (spans, raws.join(":"), None, cursor.to_string()) } #[cfg(test)] @@ -416,6 +436,25 @@ mod tests { parse_line(1, &strip_ansi(text), time, time.is_none()) } + #[test] + fn the_chain_keeps_each_span_as_written() { + let parsed = line( + "2026-10-26T23:09:16.688494Z INFO process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}: komorebi::window_manager: moving", + ); + assert_eq!( + parsed.chain, + "process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}" + ); + + // a lone word before the message is a target, so it is not part of the chain + let lone = line("2026-10-26T23:09:16.688494Z INFO a{x=1}:komorebi: hello"); + assert_eq!(lone.chain, "a{x=1}"); + assert_eq!(lone.target.as_deref(), Some("komorebi")); + + let bare = line("2026-10-26T23:09:16.688494Z INFO komorebi::x: hello"); + assert_eq!(bare.chain, ""); + } + #[test] fn a_handler_header_has_one_span_a_target_and_a_message() { let parsed = line( diff --git a/komorebi-recorder/src/analysis/logq.rs b/komorebi-recorder/src/analysis/logq.rs new file mode 100644 index 00000000..7d2a2c1f --- /dev/null +++ b/komorebi-recorder/src/analysis/logq.rs @@ -0,0 +1,1019 @@ +//! Structured questions about komorebi's log: which lines, how many, and counted by what. +//! +//! The log is long, interleaves threads and wraps every line in a span prefix, so an investigation +//! that only has `grep` ends up stripping colour codes and counting by hand. `logq` reads each line +//! as [`super::logparse`] does and keeps the lines that satisfy a *query*. +//! +//! # The query language +//! +//! A query is predicates joined by `and` and `or` (`and` binds tighter; parentheses group): +//! +//! ```text +//! level=ERROR +//! message~"ghost|orphan" and hwnd=7804828 +//! command=MoveWindow and (level=WARN or level=ERROR) +//! ``` +//! +//! A predicate is `field op value`, where `op` is one of +//! +//! | op | holds when | +//! |---|---| +//! | `=` | the field equals the value (case-sensitive, except `level`) | +//! | `!=` | the field does not equal the value, or the line has no such field | +//! | `~` | the regular expression matches somewhere in the field (case-insensitive; start it with `(?-i)` for case-sensitive) | +//! | `!~` | the regular expression does not match, or the line has no such field | +//! +//! A value is a bare word (no spaces, no `)`), or `"quoted"` with `\"` and `\\` for a quote and a +//! backslash. Two numbers compare as numbers, so `hwnd=7804828` and `hwnd=0x77179C` are the same +//! window. A field with several values (the same field on two spans) matches `=` and `~` if any of +//! them does. +//! +//! | field | is | +//! |---|---| +//! | `level` | `ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE` (case does not matter) | +//! | `target` | the module that logged, `komorebi::window_manager` | +//! | `message` | the message, without the span chain | +//! | `line` | the line number in `komorebi.log` | +//! | `spans` | the span chain as written, `process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}` | +//! | `command` | the command a `process_command{X(..)}` span is handling: `MoveWindow` | +//! | `event` | the `event` field of a span, or else the event in a `processing event: X` message | +//! | anything else | the field of that name on any span: `hwnd`, `winevent`, `direction`, `idx`, ... | +//! +//! A continuation line (a panic message, a backtrace) belongs to the line before it and has only a +//! `message`, a `line` and the time of the line before it. +//! +//! [`Analysis::logq`] answers a [`LogqQuery`] with [`LogqData`]. Each hit has a `reference` +//! (`log:345`) that `at`, `trace`, `code` and `annotate --ref` accept. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::analysis::logparse::parse_line; +//! use komorebi_recorder::analysis::logq::Query; +//! +//! let query = Query::parse("command=MoveWindow and hwnd=0x10 and nothing!=x")?; +//! let line = parse_line( +//! 1, +//! "2026-10-28T15:46:20.088347Z INFO process_command{MoveWindow(Right)}:move_it{hwnd=16}: komorebi::w: moving", +//! None, +//! false, +//! ); +//! assert!(query.matches(&line)); +//! +//! // a bad query is a usage error whose hint names the fields +//! let error = Query::parse("level ERROR").unwrap_err(); +//! assert!(format!("{error:?}").contains("command")); +//! # Ok::<(), Box>(()) +//! ``` + +use super::Analysis; +use super::budget::Budget; +use super::envelope; +use super::logparse::Level; +use super::logparse::Line; +use crate::timecode; +use color_eyre::eyre; +use regex::Regex; +use regex::RegexBuilder; +use schemars::JsonSchema; +use serde::Serialize; +use std::collections::HashMap; +use std::collections::HashSet; +use std::fmt::Write; + +/// The schema name that identifies a [`LogqData`] in an envelope (`logq/1`); listed by the `schema` +/// command. +pub const SCHEMA_LOGQ: &str = "logq/1"; + +const FIELDS_HINT: &str = "write predicates joined by `and`/`or`, e.g. `level=ERROR and message~\"ghost\"`; \ +operators are =, !=, ~ and !~; fields are level, target, message, line, spans, command, event, or \ +any span field such as hwnd, winevent or direction"; + +#[derive(Debug, Clone, PartialEq, Eq)] +enum Field { + Level, + Target, + Message, + Line, + Spans, + Command, + Event, + Span(String), +} + +impl Field { + fn new(name: &str) -> Self { + match name { + "level" => Self::Level, + "target" => Self::Target, + "message" => Self::Message, + "line" => Self::Line, + "spans" => Self::Spans, + "command" => Self::Command, + "event" => Self::Event, + other => Self::Span(other.to_string()), + } + } + + fn name(&self) -> &str { + match self { + Self::Level => "level", + Self::Target => "target", + Self::Message => "message", + Self::Line => "line", + Self::Spans => "spans", + Self::Command => "command", + Self::Event => "event", + Self::Span(name) => name, + } + } + + /// Every value this field has on `line`: none, one, or several for a span field that occurs on + /// more than one span. + fn values(&self, line: &Line) -> Vec { + match self { + Self::Level => line + .level + .map(|level| level_text(level).to_string()) + .into_iter() + .collect(), + Self::Target => line.target.clone().into_iter().collect(), + Self::Message => vec![line.message.clone()], + Self::Line => vec![line.number.to_string()], + Self::Spans => { + if line.chain.is_empty() { + Vec::new() + } else { + vec![line.chain.clone()] + } + } + Self::Command => command_of(line).into_iter().collect(), + Self::Event => { + let mut values = span_values(line, "event"); + if values.is_empty() { + values.extend(after_marker(&line.message, "processing event: ")); + } + values + } + Self::Span(name) => { + let mut values = span_values(line, name); + if name == "hwnd" { + // a window is decimal in a span and hex in many messages + let hex: Vec = values + .iter() + .filter_map(|value| as_number(value)) + .map(|number| format!("0x{number:x}")) + .collect(); + values.extend(hex); + } + values + } + } + } +} + +fn level_text(level: Level) -> &'static str { + match level { + Level::Error => "ERROR", + Level::Warn => "WARN", + Level::Info => "INFO", + Level::Debug => "DEBUG", + Level::Trace => "TRACE", + } +} + +fn span_values(line: &Line, name: &str) -> Vec { + line.spans + .iter() + .flat_map(|span| span.fields.iter()) + .filter(|(key, _)| key == name) + .map(|(_, value)| value.clone()) + .collect() +} + +fn word(text: &str) -> Option { + let end = text + .find(|c: char| !(c.is_alphanumeric() || c == '_')) + .unwrap_or(text.len()); + (end > 0).then(|| text[..end].to_string()) +} + +fn after_marker(text: &str, marker: &str) -> Option { + text.split_once(marker).and_then(|(_, rest)| word(rest)) +} + +/// The command a `process_command{X(..)}` span handles: `MoveWindow` for +/// `process_command{MoveWindow(Right)}`. +fn command_of(line: &Line) -> Option { + const OPEN: &str = "process_command{"; + line.chain + .find(OPEN) + .and_then(|at| word(&line.chain[at + OPEN.len()..])) + .or_else(|| after_marker(&line.message, "processing command: ")) +} + +/// A decimal or `0x` hexadecimal number. +fn as_number(text: &str) -> Option { + let text = text.trim(); + match text.strip_prefix("0x").or_else(|| text.strip_prefix("0X")) { + Some(hex) => u64::from_str_radix(hex, 16).ok(), + None => text.parse().ok(), + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Op { + Eq, + Ne, + Match, + NotMatch, +} + +#[derive(Debug, Clone)] +struct Predicate { + field: Field, + op: Op, + value: String, + regex: Option, +} + +impl Predicate { + fn equals(&self, candidate: &str) -> bool { + if self.field == Field::Level { + return candidate.eq_ignore_ascii_case(&self.value); + } + candidate == self.value + || matches!((as_number(candidate), as_number(&self.value)), (Some(a), Some(b)) if a == b) + } + + fn holds(&self, line: &Line) -> bool { + let values = self.field.values(line); + let regex = self.regex.as_ref(); + match self.op { + Op::Eq => values.iter().any(|value| self.equals(value)), + Op::Ne => !values.iter().any(|value| self.equals(value)), + Op::Match => regex.is_some_and(|re| values.iter().any(|value| re.is_match(value))), + Op::NotMatch => regex.is_none_or(|re| !values.iter().any(|value| re.is_match(value))), + } + } +} + +#[derive(Debug, Clone)] +enum Expr { + Pred(Predicate), + And(Vec), + Or(Vec), +} + +impl Expr { + fn holds(&self, line: &Line) -> bool { + match self { + Self::Pred(predicate) => predicate.holds(line), + Self::And(all) => all.iter().all(|expr| expr.holds(line)), + Self::Or(any) => any.iter().any(|expr| expr.holds(line)), + } + } + + fn fields<'a>(&'a self, out: &mut Vec<&'a Field>) { + match self { + Self::Pred(predicate) => out.push(&predicate.field), + Self::And(items) | Self::Or(items) => items.iter().for_each(|item| item.fields(out)), + } + } +} + +/// A parsed query: [`Query::parse`] reads it once and [`Query::matches`] tests a line. +/// +/// See the [module](self) for the language. +#[derive(Debug, Clone)] +pub struct Query { + text: String, + expr: Expr, +} + +fn bad(message: impl Into) -> eyre::Report { + envelope::with_hint(envelope::usage(message), FIELDS_HINT) +} + +struct Reader<'a> { + text: &'a str, + at: usize, +} + +impl Reader<'_> { + fn rest(&self) -> &str { + &self.text[self.at..] + } + + fn next_char(&self) -> String { + self.rest() + .chars() + .next() + .map_or_else(String::new, String::from) + } + + fn skip_space(&mut self) { + let trimmed = self.rest().trim_start(); + self.at = self.text.len() - trimmed.len(); + } + + fn eat(&mut self, prefix: &str) -> bool { + if self.rest().starts_with(prefix) { + self.at += prefix.len(); + true + } else { + false + } + } + + /// Eats the keyword `and`/`or` when it is a whole word. + fn keyword(&mut self, word: &str) -> bool { + self.skip_space(); + let rest = self.rest(); + let Some(head) = rest.get(..word.len()) else { + return false; + }; + let after = rest[word.len()..].chars().next(); + if head.eq_ignore_ascii_case(word) && after.is_none_or(|c| c.is_whitespace() || c == '(') { + self.at += word.len(); + true + } else { + false + } + } + + fn or(&mut self) -> eyre::Result { + let mut items = vec![self.and()?]; + while self.keyword("or") { + items.push(self.and()?); + } + Ok(if items.len() == 1 { + items.remove(0) + } else { + Expr::Or(items) + }) + } + + fn and(&mut self) -> eyre::Result { + let mut items = vec![self.atom()?]; + while self.keyword("and") { + items.push(self.atom()?); + } + Ok(if items.len() == 1 { + items.remove(0) + } else { + Expr::And(items) + }) + } + + fn atom(&mut self) -> eyre::Result { + self.skip_space(); + if self.eat("(") { + let inner = self.or()?; + self.skip_space(); + if !self.eat(")") { + return Err(bad(format!( + "missing `)` at position {} of the query", + self.at + 1 + ))); + } + return Ok(inner); + } + + let name_len = self + .rest() + .find(|c: char| !(c.is_alphanumeric() || matches!(c, '_' | '.' | '-'))) + .unwrap_or(self.rest().len()); + if name_len == 0 { + return Err(bad(format!( + "expected a field name at position {} of the query, found `{}`", + self.at + 1, + self.next_char() + ))); + } + let name = self.rest()[..name_len].to_string(); + self.at += name_len; + self.skip_space(); + + let op = if self.eat("!=") { + Op::Ne + } else if self.eat("!~") { + Op::NotMatch + } else if self.eat("=") { + Op::Eq + } else if self.eat("~") { + Op::Match + } else { + return Err(bad(format!( + "expected one of = != ~ !~ after `{name}`; found `{}`", + self.next_char() + ))); + }; + self.skip_space(); + + let value = self.value()?; + let regex = if matches!(op, Op::Match | Op::NotMatch) { + Some( + RegexBuilder::new(&value) + .case_insensitive(true) + .build() + .map_err(|error| bad(format!("`{value}` is not a valid pattern: {error}")))?, + ) + } else { + None + }; + + Ok(Expr::Pred(Predicate { + field: Field::new(&name), + op, + value, + regex, + })) + } + + fn value(&mut self) -> eyre::Result { + if self.eat("\"") { + let mut value = String::new(); + let mut chars = self.rest().char_indices(); + while let Some((index, c)) = chars.next() { + match c { + '\\' => match chars.next() { + Some((_, escaped @ ('"' | '\\'))) => value.push(escaped), + Some((_, other)) => { + value.push('\\'); + value.push(other); + } + None => break, + }, + '"' => { + self.at += index + 1; + return Ok(value); + } + other => value.push(other), + } + } + return Err(bad("a quoted value is missing its closing `\"`")); + } + + let end = self + .rest() + .find(|c: char| c.is_whitespace() || c == ')') + .unwrap_or(self.rest().len()); + if end == 0 { + return Err(bad(format!( + "expected a value at position {} of the query", + self.at + 1 + ))); + } + let value = self.rest()[..end].to_string(); + self.at += end; + Ok(value) + } +} + +impl Query { + /// Reads a query. + /// + /// # Errors + /// + /// Returns a usage error, with a hint that names the valid fields, if the query is empty, is + /// not `field op value` predicates joined by `and`/`or`, or has an invalid regular expression. + pub fn parse(text: &str) -> eyre::Result { + if text.trim().is_empty() { + return Err(bad("the query is empty")); + } + + let mut reader = Reader { text, at: 0 }; + let expr = reader.or()?; + reader.skip_space(); + if !reader.rest().is_empty() { + return Err(bad(format!( + "unexpected `{}` at position {}: join predicates with `and` or `or`", + reader.rest(), + reader.at + 1 + ))); + } + + Ok(Self { + text: text.to_string(), + expr, + }) + } + + /// Returns whether `line` satisfies the query. + #[must_use] + pub fn matches(&self, line: &Line) -> bool { + self.expr.holds(line) + } + + /// The query as it was written. + #[must_use] + pub fn text(&self) -> &str { + &self.text + } + + /// The span fields the query names (not the built-in ones), without repeats. + fn span_fields(&self) -> Vec<&str> { + let mut fields = Vec::new(); + self.expr.fields(&mut fields); + let mut names: Vec<&str> = fields + .into_iter() + .filter_map(|field| match field { + Field::Span(name) => Some(name.as_str()), + _ => None, + }) + .collect(); + names.sort_unstable(); + names.dedup(); + names + } +} + +/// What to ask of the log. +#[derive(Debug, Clone, Default)] +pub struct LogqQuery { + /// The query (see the [module](self)). + pub query: String, + /// Ignore lines earlier than this, in nanoseconds on the host's master monotonic clock. + pub from_mach_ns: Option, + /// Ignore lines later than this, in nanoseconds on the host's master monotonic clock. + pub to_mach_ns: Option, + /// Count the lines by the distinct values of this field (any field of the language). + pub group_by: Option, + /// Hits (or groups) already returned: this many of the first are skipped. + pub skip: usize, + /// The most hits (or groups) to return; `None` for all of them. + pub limit: Option, + /// Return no hits and no groups, only [`LogqData::matching`]. + pub count_only: bool, +} + +/// One matching line of the log, with a reference other commands accept. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct LogHit { + /// Always `komorebi-log`, as for a log hit of `search`. + pub source: String, + /// When it was logged, in seconds of video time. + pub video_s: f64, + /// When it was logged, in nanoseconds on the host's master monotonic clock. + pub mach_ns: u64, + /// `log:`, for `at`, `trace`, `code` and `annotate --ref`. + pub reference: String, + /// The line's level; absent for a continuation or a line with no level. + pub level: Option, + /// The span chain as written; empty if the line was logged outside any span. + pub spans: String, + /// The module that logged. + pub target: Option, + /// The message. + pub text: String, +} + +/// How many matching lines had one value of the `group_by` field. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct Group { + /// The value as the log wrote it (the first, for a field that is on several spans). + pub value: String, + /// How many matching lines have it. + pub count: usize, +} + +/// The answer to a [`LogqQuery`]: the `data` of the `logq` command. +#[derive(Debug, Clone, PartialEq, Serialize, JsonSchema)] +pub struct LogqData { + /// The query as given. + pub query: String, + /// How many lines matched in all (the number `--count` prints), whatever the skip and limit. + pub matching: usize, + /// The matching lines of this page, in log order. Empty when only counting or grouping. + pub hits: Vec, + /// The field counted by, if grouping. + pub group_by: Option, + /// The values of the field of this page, the most common first, ties in value order. Empty + /// unless grouping. + pub groups: Vec, + /// How many distinct values there were, including any not returned. + pub distinct: usize, + /// When grouping, how many matching lines had no value for the field. + pub without_value: usize, + /// Things worth knowing about the answer, such as a field name that no line has. + pub notes: Vec, +} + +impl Analysis { + /// Runs a [`LogqQuery`] over the session's `komorebi.log`. + /// + /// Lines are tested in file order. A line that cannot be placed on the master clock never + /// matches, because it could not be given a time or put in a range. `budget` is charged the + /// size of every line read. + /// + /// # Errors + /// + /// Returns an error if the query is invalid (the usage exit kind), `group_by` is not a field + /// name, or `budget` runs out (the budget exit kind). + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::analysis::Analysis; + /// use komorebi_recorder::analysis::budget::Budget; + /// use komorebi_recorder::analysis::logq::LogqQuery; + /// use komorebi_recorder::testkit::SessionBuilder; + /// + /// let (session, _) = SessionBuilder::new("doc-logq") + /// .log(1.0, "INFO", "process_command{MoveWindow(Right)}:move_it{hwnd=16}: komorebi::w: moving") + /// .log(2.0, "WARN", "process_event{event=\"Show\" hwnd=16}: komorebi::e: ghost tile") + /// .log(3.0, "WARN", "komorebi::e: nothing to see") + /// .build(); + /// let analysis = Analysis::open(&session.dir)?; + /// + /// let found = analysis.logq( + /// &LogqQuery { query: "hwnd=0x10".to_string(), ..LogqQuery::default() }, + /// &Budget::unlimited(), + /// )?; + /// assert_eq!(found.matching, 2); + /// assert_eq!(found.hits[1].reference, "log:2"); + /// + /// let grouped = analysis.logq( + /// &LogqQuery { + /// query: "level=warn".to_string(), + /// group_by: Some("target".to_string()), + /// ..LogqQuery::default() + /// }, + /// &Budget::unlimited(), + /// )?; + /// assert_eq!(grouped.groups[0].value, "komorebi::e"); + /// assert_eq!(grouped.groups[0].count, 2); + /// # Ok::<(), Box>(()) + /// ``` + pub fn logq(&self, query: &LogqQuery, budget: &Budget) -> eyre::Result { + let parsed = Query::parse(&query.query)?; + let group_field = query + .group_by + .as_deref() + .map(|name| { + if name.is_empty() || name.contains(char::is_whitespace) { + Err(bad(format!("`{name}` is not a field to group by"))) + } else { + Ok(Field::new(name)) + } + }) + .transpose()?; + + let lines = &self.log().lines; + let limit = query.limit.unwrap_or(usize::MAX); + let mut hits: Vec = Vec::new(); + let mut matching = 0_usize; + let mut counts: HashMap = HashMap::new(); + let mut without_value = 0_usize; + let names = parsed.span_fields(); + let mut seen_names: HashSet<&str> = HashSet::new(); + + for line in lines { + budget + .charge((line.message.len() + line.chain.len() + 32) as u64) + .map_err(|exceeded| { + envelope::over_budget(format!( + "the query {exceeded}; narrow it with --from/--to" + )) + })?; + + for name in &names { + if !seen_names.contains(name) + && line + .spans + .iter() + .any(|span| span.fields.iter().any(|(key, _)| key == name)) + { + seen_names.insert(name); + } + } + + let Some(mach_ns) = line + .wall_us + .and_then(|wall_us| self.clock().wall_to_mach(wall_us)) + else { + continue; + }; + if query.from_mach_ns.is_some_and(|from| mach_ns < from) + || query.to_mach_ns.is_some_and(|to| mach_ns > to) + || !parsed.matches(line) + { + continue; + } + + matching += 1; + if let Some(field) = &group_field { + match field.values(line).into_iter().next() { + Some(value) => *counts.entry(value).or_default() += 1, + None => without_value += 1, + } + } else if !query.count_only && matching > query.skip && hits.len() < limit { + hits.push(LogHit { + source: "komorebi-log".to_string(), + video_s: self.video_s(mach_ns), + mach_ns, + reference: format!("log:{}", line.number), + level: line.level, + spans: line.chain.clone(), + target: line.target.clone(), + text: line.message.clone(), + }); + } + } + + let mut notes = Vec::new(); + if matching == 0 { + for name in &names { + if !seen_names.contains(name) { + notes.push(format!( + "no line of the log has a span field called `{name}`; check the spelling (`logq 'spans~{name}'` finds it in a span chain)" + )); + } + } + } + + let mut groups: Vec = counts + .into_iter() + .map(|(value, count)| Group { value, count }) + .collect(); + groups.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.value.cmp(&b.value))); + let distinct = groups.len(); + if query.count_only { + groups.clear(); + } else { + groups.drain(..query.skip.min(groups.len())); + groups.truncate(limit); + } + + Ok(LogqData { + query: query.query.clone(), + matching, + hits, + group_by: group_field.map(|field| field.name().to_string()), + groups, + distinct, + without_value, + notes, + }) + } +} + +/// Returns `text` cut to `max` characters, with `…` if it was cut. +fn trimmed(text: &str, max: usize) -> String { + if text.chars().count() <= max { + return text.to_string(); + } + let mut cut: String = text.chars().take(max.saturating_sub(1)).collect(); + cut.push('…'); + cut +} + +/// Renders a [`LogqData`] as the text `logq` prints. +/// +/// A hit is a line, `log:345 00:03.389 INFO message`; with `spans` the span chain, cut to 100 +/// characters, follows the level. A count is the bare number, and groups are `count value` lines. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::logparse::Level; +/// use komorebi_recorder::analysis::logq::{LogHit, LogqData, logq_text}; +/// +/// let data = LogqData { +/// query: "level=INFO".to_string(), +/// matching: 1, +/// hits: vec![LogHit { +/// source: "komorebi-log".to_string(), +/// video_s: 3.389, +/// mach_ns: 0, +/// reference: "log:7".to_string(), +/// level: Some(Level::Info), +/// spans: String::new(), +/// target: None, +/// text: "hello".to_string(), +/// }], +/// group_by: None, +/// groups: Vec::new(), +/// distinct: 0, +/// without_value: 0, +/// notes: Vec::new(), +/// }; +/// assert_eq!(logq_text(&data, false, false), "log:7 00:03.389 INFO hello\n"); +/// assert_eq!(logq_text(&data, true, false), "1\n"); +/// ``` +#[must_use] +pub fn logq_text(data: &LogqData, count_only: bool, spans: bool) -> String { + let mut out = String::new(); + if count_only { + let _ = writeln!(out, "{}", data.matching); + } else if let Some(field) = &data.group_by { + let width = data + .groups + .iter() + .map(|group| group.count.to_string().len()) + .max() + .unwrap_or(1); + for group in &data.groups { + let _ = writeln!(out, "{:>width$} {}", group.count, group.value); + } + if data.distinct > data.groups.len() { + let _ = writeln!( + out, + "... {} distinct `{field}` values in all", + data.distinct + ); + } + if data.without_value > 0 { + let _ = writeln!(out, "{:>width$} (no `{field}`)", data.without_value); + } + } else { + for hit in &data.hits { + let level = hit.level.map_or("", level_text); + let _ = write!( + out, + "{} {} {level:<5} ", + hit.reference, + timecode::format(hit.video_s) + ); + if spans && !hit.spans.is_empty() { + let _ = write!(out, "{} ", trimmed(&hit.spans, 100)); + } + let _ = writeln!(out, "{}", hit.text); + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::analysis::logparse::parse_line; + + fn line(text: &str) -> Line { + parse_line( + 1, + &format!("2026-10-28T15:46:20.088347Z {text}"), + None, + false, + ) + } + + fn moving() -> Line { + line( + " INFO process_command{MoveWindow(Right)}:move_it{direction=Right hwnd=7804828}: komorebi::window_manager: Moving the Ghost", + ) + } + + fn holds(query: &str, line: &Line) -> bool { + Query::parse(query).expect("a valid query").matches(line) + } + + #[test] + fn built_in_fields() { + let line = moving(); + assert!(holds("level=INFO", &line)); + assert!(holds("level=info", &line), "level ignores case"); + assert!(!holds("level=WARN", &line)); + assert!(holds("target=komorebi::window_manager", &line)); + assert!(holds("target~window_", &line)); + assert!(holds("message=\"Moving the Ghost\"", &line)); + assert!( + !holds("message=\"moving the ghost\"", &line), + "= is case-sensitive" + ); + assert!(holds("message~\"moving THE ghost\"", &line), "~ is not"); + assert!(!holds("message~\"(?-i)moving\"", &line)); + assert!(holds("line=1", &line)); + assert!(holds( + "spans~\"^process_command\\{MoveWindow\\(Right\\)\\}:move_it\"", + &line + )); + assert!(holds("command=MoveWindow", &line)); + assert!(!holds("command=Move", &line)); + assert!(holds("direction=Right", &line)); + assert!(holds("nothing!=1", &line), "no such field is not equal"); + assert!(!holds("nothing=1", &line)); + assert!(!holds("nothing~1", &line)); + assert!(holds("nothing!~1", &line)); + } + + #[test] + fn hwnd_is_the_same_in_decimal_and_hex() { + let line = moving(); + assert!(holds("hwnd=7804828", &line)); + assert!(holds("hwnd=0x77179C", &line)); + assert!(holds("hwnd=0x77179c", &line)); + assert!(holds("hwnd~0x77179c", &line)); + assert!(!holds("hwnd=0x77179D", &line)); + assert!(holds("hwnd!=0x77179D", &line)); + assert!(!holds("hwnd!=7804828", &line)); + } + + #[test] + fn event_and_command_come_from_a_span_or_the_message() { + let event = line( + " INFO process_event{event=\"FocusChange\" winevent=\"SystemForeground\" hwnd=330732}: komorebi::pe: handling", + ); + assert!(holds( + "event=FocusChange and winevent=SystemForeground", + &event + )); + + let derived = + line(" INFO komorebi::process_event: processing event: MoveEnd for process 11"); + assert!(holds("event=MoveEnd", &derived)); + + let command = line(" INFO komorebi::process_command: processing command: Retile"); + assert!(holds("command=Retile", &command)); + } + + #[test] + fn and_or_and_parentheses() { + let line = moving(); + assert!(holds("level=WARN or level=INFO", &line)); + assert!(holds( + "level=INFO and direction=Right and command=MoveWindow", + &line + )); + assert!(!holds("level=INFO and direction=Left", &line)); + // and binds tighter than or + assert!(holds( + "level=WARN and direction=Left or command=MoveWindow", + &line + )); + assert!(!holds( + "level=WARN and (direction=Left or command=MoveWindow)", + &line + )); + assert!(holds( + "(level=WARN or level=INFO) AND (command=X OR command=MoveWindow)", + &line + )); + // `android` is a value here, not a keyword + assert!(!holds("message=android", &line)); + } + + #[test] + fn values_may_be_quoted() { + let line = line(" WARN komorebi::x: said \"hi\" (twice)"); + assert!(holds(r#"message="said \"hi\" (twice)""#, &line)); + assert!(holds(r#"message~"\(twice\)""#, &line)); + assert!(holds("(message~twice)", &line)); + } + + #[test] + fn a_bad_query_is_a_usage_error_naming_the_fields() { + for bad_query in [ + "", + "level", + "level ERROR", + "level=", + "=x", + "level=INFO message=x", + "(level=INFO", + "level=INFO and", + "message~\"(\"", + "message=\"open", + ] { + let error = Query::parse(bad_query).unwrap_err(); + assert_eq!( + envelope::exit_kind(&error), + envelope::ExitKind::Usage, + "{bad_query:?}" + ); + assert!( + format!("{error:?}").contains("command"), + "{bad_query:?} hint" + ); + } + } + + #[test] + fn text_shows_groups_and_counts() { + let data = LogqData { + query: "x".to_string(), + matching: 5, + hits: Vec::new(), + group_by: Some("level".to_string()), + groups: vec![ + Group { + value: "INFO".to_string(), + count: 12, + }, + Group { + value: "WARN".to_string(), + count: 3, + }, + ], + distinct: 3, + without_value: 0, + notes: Vec::new(), + }; + assert_eq!( + logq_text(&data, false, false), + "12 INFO\n 3 WARN\n... 3 distinct `level` values in all\n" + ); + assert_eq!(logq_text(&data, true, false), "5\n"); + } +} diff --git a/komorebi-recorder/src/analysis/mod.rs b/komorebi-recorder/src/analysis/mod.rs index 33525d5d..8c6b94f9 100644 --- a/komorebi-recorder/src/analysis/mod.rs +++ b/komorebi-recorder/src/analysis/mod.rs @@ -26,6 +26,7 @@ pub mod history; pub mod ids; pub mod invariants; pub mod logparse; +pub mod logq; pub mod lookup; pub mod os_trace; pub mod overview; diff --git a/komorebi-recorder/src/analysis/schemas.rs b/komorebi-recorder/src/analysis/schemas.rs index 2eaa413b..83587309 100644 --- a/komorebi-recorder/src/analysis/schemas.rs +++ b/komorebi-recorder/src/analysis/schemas.rs @@ -20,6 +20,7 @@ use super::changes::ChangesData; use super::code::CodeData; use super::envelope::Envelope; use super::history::HistoryData; +use super::logq::LogqData; use super::overview::OverviewData; use super::search::SearchData; use super::sheet::SheetData; @@ -94,6 +95,11 @@ pub const ALL: &[Entry] = &[ about: "`search`: where a word appears in the recording", schema: of::, }, + Entry { + name: "logq/1", + about: "`logq`: lines of komorebi's log matching a field query, counted or grouped", + schema: of::, + }, Entry { name: "changes/1", about: "`changes`: when and where the picture changed on each display", diff --git a/komorebi-recorder/src/cli/logq.rs b/komorebi-recorder/src/cli/logq.rs new file mode 100644 index 00000000..dd3c0052 --- /dev/null +++ b/komorebi-recorder/src/cli/logq.rs @@ -0,0 +1,116 @@ +//! `logq`: structured queries over a session's `komorebi.log` (see [`crate::analysis::logq`]). +//! +//! With `--json` the answer is the `logq/1` envelope. A page cut short by `--limit` sets +//! `truncated` and a `next_cursor`, which `--cursor` takes back. `--count` prints only the number +//! of matching lines. +//! +//! Covered by `tests/logq.rs`, which runs the command through the real binary. + +use super::print_json; +use crate::analysis::Analysis; +use crate::analysis::budget::Budget; +use crate::analysis::envelope::Envelope; +use crate::analysis::logq::LogqQuery; +use crate::analysis::logq::SCHEMA_LOGQ; +use crate::analysis::logq::logq_text; +use clap::Args; +use color_eyre::eyre; +use std::path::PathBuf; +use std::time::Duration; + +/// The arguments of `logq`. +#[derive(Args, Debug)] +pub struct LogqArgs { + /// Session directory + pub session: PathBuf, + /// Predicates joined by `and`/`or`: `level=ERROR and message~"ghost"`, `hwnd=0x77179C`, + /// `command=MoveWindow`. Operators: = != ~ !~. Fields: level, target, message, line, spans, + /// command, event, or any span field (hwnd, winevent, direction, ...) + pub query: String, + /// Only after this moment (video time, `log:N`, `event:N`, ...) + #[arg(long, value_name = "TIME")] + pub from: Option, + /// Only before this moment + #[arg(long, value_name = "TIME")] + pub to: Option, + /// Most hits (or groups) to print (0 for all) + #[arg(long, default_value_t = 50)] + pub limit: usize, + /// Continue after this many hits (from a truncated answer's `next_cursor`) + #[arg(long, value_name = "N")] + pub cursor: Option, + /// Print only how many lines match + #[arg(long, conflicts_with = "group_by")] + pub count: bool, + /// Count the matching lines by each distinct value of this field, most common first + #[arg(long, value_name = "FIELD")] + pub group_by: Option, + /// Show each hit's span chain in text output (cut to 100 characters) + #[arg(long)] + pub spans: bool, + /// Give up after this many milliseconds + #[arg(long, value_name = "MS")] + pub budget_ms: Option, + /// Machine-readable JSON output + #[arg(long)] + pub json: bool, +} + +pub(super) fn logq(args: &LogqArgs) -> eyre::Result<()> { + let analysis = Analysis::open(&args.session)?; + let moment = |text: &Option| -> eyre::Result> { + text.as_deref() + .map(|text| analysis.resolve(text).map(|resolved| resolved.mach_ns)) + .transpose() + }; + + let mut budget = Budget::unlimited().reading_at_most(512 * 1024 * 1024); + if let Some(ms) = args.budget_ms { + budget = budget.within(Duration::from_millis(ms)); + } + + let limit = super::limit(args.limit); + let skip = args.cursor.unwrap_or(0); + let data = analysis.logq( + &LogqQuery { + query: args.query.clone(), + from_mach_ns: moment(&args.from)?, + to_mach_ns: moment(&args.to)?, + group_by: args.group_by.clone(), + skip, + limit, + count_only: args.count, + }, + &budget, + )?; + + let (returned, total) = if data.group_by.is_some() { + (data.groups.len(), data.distinct) + } else { + (data.hits.len(), data.matching) + }; + let truncated = !args.count && limit.is_some() && skip + returned < total; + let next_cursor = truncated.then(|| (skip + returned).to_string()); + + if args.json { + let mut warnings = analysis.warnings(); + warnings.extend(data.notes.clone()); + let mut envelope = Envelope::ok(SCHEMA_LOGQ, data).warnings(warnings); + if truncated { + envelope = envelope.truncated(next_cursor); + } + return print_json(&envelope); + } + + print!("{}", logq_text(&data, args.count, args.spans)); + for note in &data.notes { + eprintln!("note: {note}"); + } + if let Some(cursor) = next_cursor { + eprintln!( + "... {} of {total} shown; continue with --cursor {cursor}", + returned + ); + } + Ok(()) +} diff --git a/komorebi-recorder/src/cli/mod.rs b/komorebi-recorder/src/cli/mod.rs index c78b2e7e..e1c986bd 100644 --- a/komorebi-recorder/src/cli/mod.rs +++ b/komorebi-recorder/src/cli/mod.rs @@ -9,6 +9,7 @@ mod agent; mod annotate; mod doctor; mod investigate; +mod logq; mod query; mod record; mod video; @@ -38,6 +39,7 @@ pub use investigate::EventsArgs; pub use investigate::StateArgs; pub use investigate::TraceArgs; pub use investigate::WindowArgs; +pub use logq::LogqArgs; pub use query::AtArgs; pub use query::FilterArgs; pub use query::FramesArgs; @@ -96,6 +98,8 @@ pub enum Command { Overview(OverviewArgs), /// Where a word appears: komorebi's log, events, incidents, annotations, optionally the OS trace Search(SearchArgs), + /// Query komorebi's log by field: level, target, message, span fields (hwnd, event, ...), with counts and group-by + Logq(LogqArgs), /// How to investigate a recording, for an agent Guide(GuideArgs), /// The JSON Schema of a command's `--json` output @@ -175,6 +179,7 @@ impl Command { Self::Brief(args) => args.json, Self::Overview(args) => args.json, Self::Search(args) => args.json, + Self::Logq(args) => args.json, Self::Guide(args) => args.json, Self::State(args) => args.json, Self::Diff(args) => args.json, @@ -234,6 +239,7 @@ pub fn run(command: Command) -> eyre::Result<()> { Command::Brief(args) => agent::brief(&args), Command::Overview(args) => agent::overview(&args), Command::Search(args) => agent::search(&args), + Command::Logq(args) => logq::logq(&args), Command::Guide(args) => agent::guide(&args), Command::Schema(args) => agent::schema(&args), Command::State(args) => investigate::state(&args), diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index 7e48e4a2..d3396efb 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -57,6 +57,12 @@ locations as hints. with the code around it. `ambiguous` and `generic` matches say so: do not pin a cause on one. 7. **Anything else.** `search ` across the log, events, incidents and annotations (`--oslog` adds the OS trace, where the recording has one); `at`, `range` and `summary` read the raw timeline. + To query komorebi's log by field instead of grepping it, use `logq 'level=ERROR and hwnd=0x77179C'` + (`and`/`or`, `= != ~ !~`; `command`, `event` and any span field; `--count`, `--group-by `); + each hit's `log:N` goes to `at`, `trace` and `annotate --ref`. + To query komorebi's log by field instead of grepping it, use `logq 'level=ERROR and hwnd=0x77179C'` + (`and`/`or`, `= != ~ !~`; `command`, `event` and any span field; `--count`, `--group-by `); + each hit's `log:N` goes to `at`, `trace` and `annotate --ref`. ## 3. Facts about the data that change what it means diff --git a/komorebi-recorder/tests/logq.rs b/komorebi-recorder/tests/logq.rs new file mode 100644 index 00000000..764d0b5c --- /dev/null +++ b/komorebi-recorder/tests/logq.rs @@ -0,0 +1,184 @@ +//! `logq` through the real binary: field queries over komorebi's log, counts, group-by, the JSON +//! envelope and what a bad query says. + +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 text(args: &[&str]) -> String { + let output = recorder(args); + assert!( + output.status.success(), + "{args:?}: {}", + String::from_utf8_lossy(&output.stderr) + ); + String::from_utf8_lossy(&output.stdout).into_owned() +} + +fn json(args: &[&str]) -> Value { + serde_json::from_str(&text(args)).expect("JSON") +} + +fn session(name: &str) -> String { + let (session, _) = SessionBuilder::new(name) + .log(1.0, "INFO", "process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}: komorebi::window_manager: moving container") + .log(2.0, "WARN", "process_event{event=\"Show\" winevent=\"ObjectShow\" hwnd=7804828}: komorebi::process_event: ghost tile for 0x77179c") + .log(3.389, "ERROR", "process_event{event=\"Show\" winevent=\"ObjectShow\" hwnd=7804828}:update{follow=true}: komorebi::workspace: Ghost window dropped") + .log(4.0, "INFO", "process_event{event=\"Hide\" winevent=\"ObjectHide\" hwnd=99}: komorebi::process_event: hidden") + .log(5.0, "DEBUG", "komorebi::reaper: reaping") + .build(); + session.dir.display().to_string() +} + +#[test] +fn lines_are_found_by_field_and_listed_with_references() { + let dir = session("logq-fields"); + + let found = text(&["logq", &dir, "level=WARN or level=ERROR"]); + let lines: Vec<&str> = found.lines().collect(); + assert_eq!(lines.len(), 2, "{found}"); + assert!( + lines[0].starts_with("log:2 00:02.000 WARN ghost tile"), + "{found}" + ); + assert!( + lines[1].starts_with("log:3 00:03.389 ERROR Ghost window"), + "{found}" + ); + + // hwnd is the same window in decimal and hex + for query in ["hwnd=7804828", "hwnd=0x77179C"] { + assert_eq!( + text(&["logq", &dir, query, "--count"]).trim(), + "2", + "{query}" + ); + } + + assert_eq!( + text(&["logq", &dir, "command=MoveWindow", "--count"]).trim(), + "1" + ); + assert_eq!( + text(&["logq", &dir, "direction=Right and level=info", "--count"]).trim(), + "1" + ); + assert_eq!( + text(&["logq", &dir, "message~ghost", "--count"]).trim(), + "2" + ); + assert_eq!( + text(&["logq", &dir, "message~\"(?-i)^ghost\"", "--count"]).trim(), + "1" + ); + assert_eq!( + text(&["logq", &dir, "event=Show and not=x", "--count"]).trim(), + "0" + ); + + // the span chain can be shown, and is trimmed to a line + let with_spans = text(&["logq", &dir, "command=MoveWindow", "--spans"]); + assert!( + with_spans.contains("process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right} moving container"), + "{with_spans}" + ); +} + +#[test] +fn counting_grouping_and_ranges() { + let dir = session("logq-group"); + + let grouped = text(&["logq", &dir, "hwnd~.", "--group-by", "hwnd"]); + assert_eq!(grouped, "2 7804828\n1 99\n"); + + let levels = text(&["logq", &dir, "message~.", "--group-by", "level"]); + assert!(levels.starts_with("2 INFO\n"), "{levels}"); + + let ranged = text(&[ + "logq", + &dir, + "message~.", + "--from", + "2.5", + "--to", + "4", + "--count", + ]); + assert_eq!(ranged.trim(), "2"); +} + +#[test] +fn json_is_an_envelope_that_pages() { + let dir = session("logq-json"); + + let page = json(&["logq", &dir, "message~.", "--limit", "2", "--json"]); + assert_eq!(page["ok"], true); + assert_eq!(page["schema"], "logq/1"); + assert_eq!(page["truncated"], true); + assert_eq!(page["next_cursor"], "2"); + assert_eq!(page["data"]["matching"], 5); + assert_eq!(page["data"]["hits"].as_array().expect("hits").len(), 2); + assert_eq!(page["data"]["hits"][0]["reference"], "log:1"); + assert_eq!(page["data"]["hits"][0]["source"], "komorebi-log"); + assert_eq!(page["data"]["hits"][0]["level"], "INFO"); + assert_eq!( + page["data"]["hits"][0]["spans"], + "process_command{MoveWindow(Right)}:move_container_in_direction{direction=Right}" + ); + + let next = json(&[ + "logq", + &dir, + "message~.", + "--limit", + "2", + "--cursor", + "2", + "--json", + ]); + assert_eq!(next["data"]["hits"][0]["reference"], "log:3"); + + let grouped = json(&["logq", &dir, "hwnd~.", "--group-by", "hwnd", "--json"]); + assert_eq!(grouped["data"]["groups"][0]["value"], "7804828"); + assert_eq!(grouped["data"]["groups"][0]["count"], 2); + + // a field no line has is said, not silently empty + let typo = json(&["logq", &dir, "hwdn=1", "--json"]); + assert_eq!(typo["data"]["matching"], 0); + assert!(typo["warnings"].to_string().contains("hwdn"), "{typo}"); + + // the references are the ones `at` and `trace` take + let at = recorder(&["at", &dir, "3.389"]); + assert!(at.status.success()); + + let schema = text(&["schema", "logq/1"]); + assert!(schema.contains("matching")); +} + +#[test] +fn a_bad_query_is_a_usage_error_with_a_hint() { + let dir = session("logq-bad"); + + for query in ["level ERROR", "", "message~\"(\""] { + let output = recorder(&["logq", &dir, query, "--json"]); + assert_eq!(output.status.code(), Some(2), "{query:?}"); + let envelope: Value = serde_json::from_slice(&output.stdout).expect("envelope"); + assert_eq!(envelope["ok"], false); + assert_eq!(envelope["error"]["kind"], "usage"); + assert!( + envelope["error"]["hint"] + .as_str() + .unwrap_or_default() + .contains("hwnd"), + "{envelope}" + ); + } +}