Skip to main content

dima_core/
run_report.rs

1//! The run report (D103): how a run went, written to a separate JSON file
2//! (`schemas/run-report.schema.json`) so that the results stay byte-identical across runs.
3//!
4//! It records what an audit needs: version and build target, the command (rebuilt from the
5//! parameters, file names only), status, UTC times, threads and where their number came from,
6//! platform, phase times, CPU time, peak memory, and the size and SHA-256 of every input and
7//! output. It never records anything that identifies a person or machine: no host or user
8//! names, no directories, no environment values, no raw command line (data minimisation, GDPR
9//! art. 5 and 25). Field names follow the Workflow Run RO-Crate terms (Leo et al. 2024) so a
10//! Process Run Crate export can follow.
11//!
12//! Front ends fill it: the CLI (`--run-report`) and the desktop app ("Save run report…").
13
14use std::time::{Duration, SystemTime, UNIX_EPOCH};
15
16use serde::Serialize;
17
18use crate::control::Phase;
19
20/// Version of the run-report schema.
21pub const REPORT_SCHEMA_VERSION: &str = "1.1.0";
22
23/// The program that ran.
24#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
25pub struct Tool {
26    /// `dima` (the CLI) or `dima-gui` (the desktop app).
27    pub name: &'static str,
28    /// Its version.
29    pub version: &'static str,
30    /// The Rust target triple it was built for.
31    pub target: String,
32}
33
34/// Worker threads and where their number came from (D101).
35#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
36pub struct Threads {
37    /// Worker threads requested.
38    pub count: usize,
39    /// Worker threads started: `count`, or fewer when the system refused some (D110); `None`
40    /// when the run stopped before they were started.
41    pub started: Option<usize>,
42    /// `--threads`, `RAYON_NUM_THREADS`, `available_parallelism`, `settings` (desktop app) or
43    /// the name of the scheduler variable that limited the count. Never a value that could
44    /// name a host.
45    pub source: &'static str,
46}
47
48/// Operating system and processor.
49#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
50pub struct Platform {
51    /// `linux`, `macos`, `windows`, …
52    pub os: &'static str,
53    /// `x86_64`, `aarch64`, …
54    pub arch: &'static str,
55    /// Logical CPUs available to the process.
56    pub logical_cpus: usize,
57}
58
59impl Platform {
60    /// This process's platform.
61    #[must_use]
62    pub fn current() -> Self {
63        Self {
64            os: std::env::consts::OS,
65            arch: std::env::consts::ARCH,
66            logical_cpus: std::thread::available_parallelism()
67                .map_or(1, std::num::NonZeroUsize::get),
68        }
69    }
70}
71
72/// Time and memory used.
73#[derive(Clone, Debug, PartialEq, Serialize)]
74pub struct Resources {
75    /// Wall-clock time of the run.
76    pub wall_seconds: f64,
77    /// CPU time in user mode; `None` where it is not measured (the desktop app's process time
78    /// includes drawing the interface).
79    pub cpu_user_seconds: Option<f64>,
80    /// CPU time in kernel mode; `None` where it is not measured.
81    pub cpu_system_seconds: Option<f64>,
82    /// Peak resident memory; `None` where it is not measured.
83    pub peak_rss_bytes: Option<u64>,
84    /// Time the counting threads waited for input; `None` when the analysis did not finish (it
85    /// failed or was cancelled).
86    pub waited_for_input_seconds: Option<f64>,
87}
88
89/// Wall time of one phase.
90#[derive(Clone, Debug, PartialEq, Serialize)]
91pub struct PhaseTime {
92    /// [`Phase::as_str`].
93    pub name: &'static str,
94    /// Its wall-clock time.
95    pub wall_seconds: f64,
96}
97
98impl PhaseTime {
99    /// The time spent in `phase`.
100    #[must_use]
101    pub fn new(phase: Phase, time: Duration) -> Self {
102        Self {
103            name: phase.as_str(),
104            wall_seconds: time.as_secs_f64(),
105        }
106    }
107}
108
109/// Amount of work done.
110#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
111pub struct Work {
112    /// Records read.
113    pub records: u64,
114    /// Positions analysed; `None` if the run stopped before.
115    pub positions: Option<u64>,
116}
117
118/// An input or output file.
119#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
120pub struct FileRecord {
121    /// `alignment`, `results`, `results_jsonl`, `positions_table`, `variants_table`,
122    /// `metadata_table`, `hcs_table` or `hcs`.
123    pub role: &'static str,
124    /// File name without directories; `-` for a standard stream.
125    pub name: String,
126    /// Stored size in bytes.
127    pub size_bytes: u64,
128    /// SHA-256 of the stored bytes (lower-case hex).
129    pub sha256: String,
130}
131
132/// How the run ended.
133#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
134#[serde(rename_all = "snake_case")]
135pub enum Status {
136    /// Every output was written.
137    Completed,
138    /// An error stopped the run.
139    Failed,
140    /// The user cancelled the run.
141    Cancelled,
142}
143
144/// The run report. Serialised in field order.
145#[derive(Clone, Debug, PartialEq, Serialize)]
146pub struct RunReport {
147    /// [`REPORT_SCHEMA_VERSION`].
148    pub schema_version: &'static str,
149    /// The program.
150    pub tool: Tool,
151    /// The equivalent `dima` command (file names only).
152    pub command: Vec<String>,
153    /// How the run ended.
154    pub status: Status,
155    /// The process exit code (CLI) or the code the CLI would have returned.
156    pub exit_code: u8,
157    /// The error report with directories removed ([`redact_paths`]); `None` unless failed.
158    pub error: Option<String>,
159    /// Start, RFC 3339 UTC ([`rfc3339`]).
160    pub start_time: String,
161    /// End, RFC 3339 UTC.
162    pub end_time: String,
163    /// `None` when the run stopped before the thread count was resolved.
164    pub threads: Option<Threads>,
165    /// Operating system and processor.
166    pub platform: Platform,
167    /// Time and memory.
168    pub resources: Resources,
169    /// Wall time per phase, in order.
170    pub phases: Vec<PhaseTime>,
171    /// Records and positions.
172    pub work: Work,
173    /// The input alignment (when it was read to the end).
174    pub inputs: Vec<FileRecord>,
175    /// Every output written, in order.
176    pub outputs: Vec<FileRecord>,
177}
178
179/// `2026-10-05T08:12:01.123+00:00` (RFC 3339, UTC, milliseconds).
180#[must_use]
181pub fn rfc3339(t: SystemTime) -> String {
182    let d = t.duration_since(UNIX_EPOCH).unwrap_or(Duration::ZERO);
183    let secs = d.as_secs();
184    let (days, rem) = (secs / 86_400, secs % 86_400);
185    let (y, m, day) = civil_from_days(i64::try_from(days).unwrap_or(0));
186    format!(
187        "{y:04}-{m:02}-{day:02}T{:02}:{:02}:{:02}.{:03}+00:00",
188        rem / 3600,
189        (rem / 60) % 60,
190        rem % 60,
191        d.subsec_millis()
192    )
193}
194
195/// Days since 1970-01-01 to a proleptic Gregorian date (Hinnant's algorithm).
196fn civil_from_days(z: i64) -> (i64, u32, u32) {
197    let z = z + 719_468;
198    let era = z.div_euclid(146_097);
199    let doe = z.rem_euclid(146_097);
200    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
201    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
202    let mp = (5 * doy + 2) / 153;
203    let d = doy - (153 * mp + 2) / 5 + 1;
204    let m = if mp < 10 { mp + 3 } else { mp - 9 };
205    let y = yoe + era * 400 + i64::from(m <= 2);
206    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
207    (y, m as u32, d as u32)
208}
209
210/// A path reduced to its file name (no directories), `-` for standard streams and descriptor
211/// paths such as `/dev/fd/63` (process substitution).
212#[must_use]
213pub fn file_name(p: &std::path::Path) -> String {
214    if p.as_os_str() == "-" || crate::input::is_descriptor_alias(p) {
215        return "-".to_owned();
216    }
217    p.file_name()
218        .map_or_else(|| "-".to_owned(), |n| n.to_string_lossy().into_owned())
219}
220
221/// The error text a run report records: the first line of the message (later lines can list
222/// input data such as FASTA headers), every cause and the hint, with directories removed
223/// ([`redact_paths`]; `known` are the paths given to the program).
224#[must_use]
225pub fn error_text(error: &crate::DimaError, known: &[&std::path::Path]) -> String {
226    let message = error.to_string();
227    let mut text = message.lines().next().unwrap_or_default().to_owned();
228    let mut cause = std::error::Error::source(error);
229    while let Some(c) = cause {
230        text.push_str("\ncaused by: ");
231        text.push_str(&c.to_string());
232        cause = c.source();
233    }
234    if let Some(h) = error.hint() {
235        text.push_str("\nhint: ");
236        text.push_str(h);
237    }
238    redact_paths(&text, known)
239}
240
241/// `message` with every path reduced to its file name, so error texts in the run report hold
242/// no directories (D103): first the paths given on the command line (`known`, longest first),
243/// then any quoted path, then any bare absolute path (e.g. in an operating-system message).
244#[must_use]
245pub fn redact_paths(message: &str, known: &[&std::path::Path]) -> String {
246    let mut known: Vec<String> = known
247        .iter()
248        .map(|p| p.display().to_string())
249        .filter(|p| !p.is_empty() && p != "-")
250        .collect();
251    known.sort_by_key(|p| std::cmp::Reverse(p.len()));
252    let mut out = message.to_owned();
253    for p in &known {
254        out = out.replace(p.as_str(), last_component(p));
255    }
256    redact_bare(&redact_quoted(&out))
257}
258
259const SEPARATORS: [char; 2] = ['/', '\\'];
260
261/// The last non-empty component of a path (`/a/b/` → `b`).
262fn last_component(p: &str) -> &str {
263    p.rsplit(SEPARATORS).find(|c| !c.is_empty()).unwrap_or(p)
264}
265
266/// Reduces `'…'` and `"…"` segments that contain a directory separator.
267fn redact_quoted(s: &str) -> String {
268    let mut result = String::with_capacity(s.len());
269    let mut rest = s;
270    while let Some(i) = rest.find(['\'', '"']) {
271        let quote = &rest[i..=i];
272        result.push_str(&rest[..=i]);
273        let after = &rest[i + 1..];
274        let Some(end) = after.find(quote) else {
275            rest = after;
276            continue;
277        };
278        let content = &after[..end];
279        result.push_str(if content.contains(SEPARATORS) {
280            last_component(content)
281        } else {
282            content
283        });
284        result.push_str(quote);
285        rest = &after[end + 1..];
286    }
287    result.push_str(rest);
288    result
289}
290
291/// `true` for `/…`, `\\…`, `~/…` and `X:\…`/`X:/…`.
292fn is_absolute(t: &str) -> bool {
293    let b = t.as_bytes();
294    t.starts_with(SEPARATORS)
295        || t.starts_with("~/")
296        || (b.len() > 2
297            && b[0].is_ascii_alphabetic()
298            && b[1] == b':'
299            && (b[2] == b'/' || b[2] == b'\\'))
300}
301
302/// Reduces whitespace-separated absolute paths, keeping surrounding punctuation.
303fn redact_bare(s: &str) -> String {
304    let mut result = String::with_capacity(s.len());
305    for (i, token) in s.split(' ').enumerate() {
306        if i > 0 {
307            result.push(' ');
308        }
309        let core = token.trim_start_matches(['(', '\'', '"']);
310        let core = core.trim_end_matches([',', ';', ':', ')', '.', '\'', '"']);
311        if core.len() > 1 && is_absolute(core) {
312            let start = token.len() - token.trim_start_matches(['(', '\'', '"']).len();
313            result.push_str(&token[..start]);
314            result.push_str(last_component(core));
315            result.push_str(&token[start + core.len()..]);
316        } else {
317            result.push_str(token);
318        }
319    }
320    result
321}
322
323#[cfg(test)]
324mod tests {
325    use super::*;
326
327    #[test]
328    fn error_text_keeps_no_input_data() {
329        let e = crate::DimaError::input_data(
330            Some(crate::error::Location::new("/data/run1/in.fasta")),
331            "2 headers do not have the 3 fields\n  record 4 (line 7): 2 fields: patient-17|ward B",
332        )
333        .with_hint("fix the headers");
334        let text = error_text(&e, &[std::path::Path::new("/data/run1/in.fasta")]);
335        assert_eq!(
336            text,
337            "in.fasta: 2 headers do not have the 3 fields\nhint: fix the headers"
338        );
339    }
340
341    #[test]
342    fn dates() {
343        assert_eq!(rfc3339(UNIX_EPOCH), "1970-01-01T00:00:00.000+00:00");
344        let t = UNIX_EPOCH + Duration::from_millis(1_791_000_000_123);
345        assert_eq!(rfc3339(t), "2026-10-03T04:00:00.123+00:00");
346        // Leap day.
347        let t = UNIX_EPOCH + Duration::from_secs(951_782_400);
348        assert_eq!(rfc3339(t), "2000-02-29T00:00:00.000+00:00");
349        assert_eq!(file_name(std::path::Path::new("/a/b/c.fa")), "c.fa");
350        assert_eq!(file_name(std::path::Path::new("-")), "-");
351    }
352
353    #[test]
354    fn paths_are_redacted() {
355        let known = [std::path::Path::new("data dir/in.fasta")];
356        assert_eq!(
357            redact_paths(
358                "cannot open 'data dir/in.fasta'\ncaused by: No such file",
359                &known
360            ),
361            "cannot open 'in.fasta'\ncaused by: No such file"
362        );
363        assert_eq!(
364            redact_paths("failed at path \"/home/me/out/.tmpA1\" (x)", &[]),
365            "failed at path \".tmpA1\" (x)"
366        );
367        assert_eq!(
368            redact_paths("see /home/me/x.json, then C:\\Users\\me\\y.tsv.", &[]),
369            "see x.json, then y.tsv."
370        );
371        // Not paths: ratios, header formats, apostrophes.
372        let m = "entropy ~ 1/n; format 'A|B' can't match";
373        assert_eq!(redact_paths(m, &[]), m);
374    }
375}