Skip to main content

logcompact_core/
session.rs

1use std::collections::{BTreeMap, BTreeSet};
2use std::error::Error;
3use std::fmt::{Display, Formatter};
4
5use crate::{
6    Diagnostic, EndReason, LogLine, OutputPolicy, Provenance, Reduction, ReductionStats, Scope,
7    SessionOptions, Stream, TestFailure, finalize_findings, normalize_terminal_text,
8};
9
10/// Parser lifecycle notification for a caller-owned scope.
11#[derive(Clone, Debug)]
12pub enum ScopeBoundary<'a> {
13    Begin(&'a Scope),
14    End {
15        scope: &'a Scope,
16        reason: EndReason,
17        input_truncated: bool,
18    },
19}
20
21/// Deterministic, synchronous parser contract.
22pub trait Parser: Send {
23    fn id(&self) -> &'static str;
24
25    fn observe(&mut self, line: &LogLine<'_>, emitter: &mut Emitter<'_>);
26
27    fn boundary(&mut self, _boundary: ScopeBoundary<'_>, _emitter: &mut Emitter<'_>) {}
28
29    fn finish(&mut self, _emitter: &mut Emitter<'_>) {}
30}
31
32/// Immutable ordered set of trusted native parsers.
33#[derive(Default)]
34pub struct ParserPlan {
35    parsers: Vec<Box<dyn Parser>>,
36    ids: BTreeSet<&'static str>,
37}
38
39impl ParserPlan {
40    #[must_use]
41    pub fn new() -> Self {
42        Self::default()
43    }
44
45    pub fn push<P: Parser + 'static>(&mut self, parser: P) -> Result<(), ParserPlanError> {
46        let id = parser.id();
47        if id.is_empty() {
48            return Err(ParserPlanError::EmptyId);
49        }
50        if !self.ids.insert(id) {
51            return Err(ParserPlanError::DuplicateId(id));
52        }
53        self.parsers.push(Box::new(parser));
54        Ok(())
55    }
56
57    #[must_use]
58    pub fn len(&self) -> usize {
59        self.parsers.len()
60    }
61
62    #[must_use]
63    pub fn is_empty(&self) -> bool {
64        self.parsers.is_empty()
65    }
66}
67
68/// Invalid immutable parser-plan construction.
69#[derive(Clone, Copy, Debug, Eq, PartialEq)]
70pub enum ParserPlanError {
71    EmptyId,
72    DuplicateId(&'static str),
73}
74
75impl Display for ParserPlanError {
76    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
77        match self {
78            Self::EmptyId => formatter.write_str("parser identifiers must not be empty"),
79            Self::DuplicateId(id) => write!(formatter, "duplicate parser identifier {id:?}"),
80        }
81    }
82}
83
84impl Error for ParserPlanError {}
85
86#[derive(Default)]
87struct CandidateStore {
88    diagnostics: Vec<Diagnostic>,
89    test_failures: Vec<TestFailure>,
90    dropped: u64,
91}
92
93/// Bounded parser output sink. Contextual provenance is supplied by the engine.
94pub struct Emitter<'a> {
95    store: &'a mut CandidateStore,
96    maximum: usize,
97    provenance: Option<Provenance>,
98}
99
100impl Emitter<'_> {
101    /// Records a finding that a bounded parser could not retain or emit.
102    pub fn candidate_dropped(&mut self) {
103        self.store.dropped = self.store.dropped.saturating_add(1);
104    }
105
106    pub fn diagnostic(&mut self, mut diagnostic: Diagnostic) {
107        if self
108            .store
109            .diagnostics
110            .len()
111            .saturating_add(self.store.test_failures.len())
112            >= self.maximum
113        {
114            self.store.dropped = self.store.dropped.saturating_add(1);
115            return;
116        }
117        if diagnostic.provenance.is_none() {
118            diagnostic.provenance = self.provenance.clone();
119        }
120        self.store.diagnostics.push(diagnostic);
121    }
122
123    pub fn test_failure(&mut self, mut failure: TestFailure) {
124        if self
125            .store
126            .diagnostics
127            .len()
128            .saturating_add(self.store.test_failures.len())
129            >= self.maximum
130        {
131            self.store.dropped = self.store.dropped.saturating_add(1);
132            return;
133        }
134        if failure.provenance.is_none() {
135            failure.provenance = self.provenance.clone();
136        }
137        self.store.test_failures.push(failure);
138    }
139}
140
141#[derive(Clone, Debug)]
142struct ScopeState {
143    scope: Scope,
144    retained_bytes: usize,
145    truncated: bool,
146    stream_lines: BTreeMap<Stream, u64>,
147}
148
149#[derive(Clone, Debug, Default)]
150struct LineBuffer {
151    bytes: Vec<u8>,
152    truncated: bool,
153    previous_was_cr: bool,
154}
155
156/// Incremental, chunk-invariant reduction session.
157pub struct ReductionSession<'a> {
158    plan: ParserPlan,
159    options: SessionOptions,
160    policy: OutputPolicy<'a>,
161    scopes: BTreeMap<String, ScopeState>,
162    buffers: BTreeMap<(String, Stream), LineBuffer>,
163    candidates: CandidateStore,
164    stats: ReductionStats,
165    next_ordinal: u64,
166}
167
168impl<'a> ReductionSession<'a> {
169    #[must_use]
170    pub fn new(plan: ParserPlan, options: SessionOptions, policy: OutputPolicy<'a>) -> Self {
171        Self {
172            plan,
173            options,
174            policy,
175            scopes: BTreeMap::new(),
176            buffers: BTreeMap::new(),
177            candidates: CandidateStore::default(),
178            stats: ReductionStats::default(),
179            next_ordinal: 0,
180        }
181    }
182
183    pub fn begin_scope(&mut self, scope: Scope) -> bool {
184        if self.scopes.contains_key(&scope.id)
185            || self.scopes.len() >= self.options.limits.max_scopes
186        {
187            self.stats.candidates_dropped = self.stats.candidates_dropped.saturating_add(1);
188            return false;
189        }
190        let id = scope.id.clone();
191        self.scopes.insert(
192            id,
193            ScopeState {
194                scope: scope.clone(),
195                retained_bytes: 0,
196                truncated: false,
197                stream_lines: BTreeMap::new(),
198            },
199        );
200        self.stats.scopes_started = self.stats.scopes_started.saturating_add(1);
201        self.dispatch_boundary(ScopeBoundary::Begin(&scope));
202        true
203    }
204
205    pub fn push_chunk(&mut self, scope_id: &str, stream: Stream, chunk: &[u8]) -> bool {
206        let Some(state) = self.scopes.get_mut(scope_id) else {
207            return false;
208        };
209        self.stats.bytes_seen = self
210            .stats
211            .bytes_seen
212            .saturating_add(u64::try_from(chunk.len()).unwrap_or(u64::MAX));
213        let available = self
214            .options
215            .limits
216            .max_scope_bytes
217            .saturating_sub(state.retained_bytes);
218        let retained = chunk.len().min(available);
219        state.retained_bytes = state.retained_bytes.saturating_add(retained);
220        self.stats.bytes_retained = self
221            .stats
222            .bytes_retained
223            .saturating_add(u64::try_from(retained).unwrap_or(u64::MAX));
224        if retained < chunk.len() {
225            state.truncated = true;
226        }
227
228        let key = (scope_id.to_owned(), stream);
229        let buffer = self.buffers.entry(key).or_default();
230        let mut completed = Vec::<(Vec<u8>, bool)>::new();
231        for byte in &chunk[..retained] {
232            let boundary = *byte == b'\n' || *byte == b'\r';
233            if boundary {
234                if *byte == b'\n' && buffer.previous_was_cr {
235                    buffer.previous_was_cr = false;
236                    continue;
237                }
238                completed.push((std::mem::take(&mut buffer.bytes), buffer.truncated));
239                buffer.truncated = false;
240                buffer.previous_was_cr = *byte == b'\r';
241            } else {
242                buffer.previous_was_cr = false;
243                if buffer.bytes.len() < self.options.limits.max_line_bytes {
244                    buffer.bytes.push(*byte);
245                } else {
246                    buffer.truncated = true;
247                }
248            }
249        }
250        for (bytes, truncated) in completed {
251            self.dispatch_bytes(scope_id, stream, bytes, truncated);
252        }
253        true
254    }
255
256    /// Adds a trusted structured finding to the same redaction and budget path.
257    pub fn emit_structured(&mut self, scope_id: &str, mut diagnostic: Diagnostic) -> bool {
258        let Some(state) = self.scopes.get(scope_id) else {
259            return false;
260        };
261        if diagnostic.provenance.is_none() {
262            diagnostic.provenance = Some(
263                Provenance::new("structured")
264                    .with_scope(&state.scope)
265                    .with_parser("adapter"),
266            );
267        }
268        let mut emitter = Emitter {
269            store: &mut self.candidates,
270            maximum: self.options.limits.max_candidates,
271            provenance: None,
272        };
273        emitter.diagnostic(diagnostic);
274        true
275    }
276
277    pub fn end_scope(&mut self, scope_id: &str, reason: EndReason) -> bool {
278        let Some(mut state) = self.scopes.remove(scope_id) else {
279            return false;
280        };
281        let keys = self
282            .buffers
283            .keys()
284            .filter(|(id, _)| id == scope_id)
285            .cloned()
286            .collect::<Vec<_>>();
287        for key in keys {
288            if let Some(buffer) = self.buffers.remove(&key)
289                && (!buffer.bytes.is_empty() || buffer.truncated)
290            {
291                self.scopes.insert(scope_id.to_owned(), state.clone());
292                self.dispatch_bytes(scope_id, key.1, buffer.bytes, buffer.truncated);
293                state = self
294                    .scopes
295                    .remove(scope_id)
296                    .expect("temporary scope state must remain present");
297            }
298        }
299        let effective_reason = if state.truncated && reason == EndReason::Complete {
300            EndReason::Truncated
301        } else {
302            reason
303        };
304        self.dispatch_boundary(ScopeBoundary::End {
305            scope: &state.scope,
306            reason: effective_reason,
307            input_truncated: state.truncated,
308        });
309        self.stats.scopes_completed = self.stats.scopes_completed.saturating_add(1);
310        true
311    }
312
313    #[must_use]
314    pub fn finish(mut self) -> Reduction {
315        let scope_ids = self.scopes.keys().cloned().collect::<Vec<_>>();
316        for scope_id in scope_ids {
317            self.end_scope(&scope_id, EndReason::Interrupted);
318        }
319        for parser in &mut self.plan.parsers {
320            let provenance = Some(Provenance::new("parser").with_parser(parser.id()));
321            let mut emitter = Emitter {
322                store: &mut self.candidates,
323                maximum: self.options.limits.max_candidates,
324                provenance,
325            };
326            parser.finish(&mut emitter);
327        }
328        self.stats.candidates_emitted = u64::try_from(
329            self.candidates
330                .diagnostics
331                .len()
332                .saturating_add(self.candidates.test_failures.len()),
333        )
334        .unwrap_or(u64::MAX);
335        self.stats.candidates_dropped = self
336            .stats
337            .candidates_dropped
338            .saturating_add(self.candidates.dropped);
339        finalize_findings(
340            self.candidates.diagnostics,
341            self.candidates.test_failures,
342            self.options.budget,
343            self.policy,
344            self.stats,
345        )
346    }
347
348    fn dispatch_bytes(&mut self, scope_id: &str, stream: Stream, bytes: Vec<u8>, truncated: bool) {
349        let normalized = normalize_terminal_text(&bytes);
350        if normalized.is_empty() {
351            return;
352        }
353        for text in normalized.lines() {
354            let Some(state) = self.scopes.get_mut(scope_id) else {
355                return;
356            };
357            let stream_line = state.stream_lines.entry(stream).or_default();
358            *stream_line = stream_line.saturating_add(1);
359            let stream_line = *stream_line;
360            let scope = state.scope.clone();
361            let ordinal = self.next_ordinal;
362            self.next_ordinal = self.next_ordinal.saturating_add(1);
363            self.stats.lines_seen = self.stats.lines_seen.saturating_add(1);
364            if truncated {
365                self.stats.truncated_lines = self.stats.truncated_lines.saturating_add(1);
366                state.truncated = true;
367            }
368            let line = LogLine {
369                scope: &scope,
370                stream,
371                ordinal,
372                stream_line,
373                text,
374                truncated,
375            };
376            for parser in &mut self.plan.parsers {
377                let provenance = Some(
378                    Provenance::new(stream_name(stream))
379                        .with_scope(&scope)
380                        .with_span(stream, stream_line, stream_line)
381                        .with_parser(parser.id()),
382                );
383                let mut emitter = Emitter {
384                    store: &mut self.candidates,
385                    maximum: self.options.limits.max_candidates,
386                    provenance,
387                };
388                parser.observe(&line, &mut emitter);
389            }
390        }
391    }
392
393    fn dispatch_boundary(&mut self, boundary: ScopeBoundary<'_>) {
394        for parser in &mut self.plan.parsers {
395            let scope = match &boundary {
396                ScopeBoundary::Begin(scope) | ScopeBoundary::End { scope, .. } => scope,
397            };
398            let provenance = Some(
399                Provenance::new("boundary")
400                    .with_scope(scope)
401                    .with_parser(parser.id()),
402            );
403            let mut emitter = Emitter {
404                store: &mut self.candidates,
405                maximum: self.options.limits.max_candidates,
406                provenance,
407            };
408            parser.boundary(boundary.clone(), &mut emitter);
409        }
410    }
411}
412
413fn stream_name(stream: Stream) -> &'static str {
414    match stream {
415        Stream::Stdout => "stdout",
416        Stream::Stderr => "stderr",
417        Stream::Combined => "combined",
418        Stream::Annotation => "annotation",
419        Stream::Structured => "structured",
420    }
421}
422
423#[cfg(test)]
424mod tests {
425    use super::*;
426    use crate::{
427        Budget, DiagnosticClass, EvidenceQuality, GenericRanker, NoPathMapping, NoRedaction,
428        OutputPolicy, Severity,
429    };
430
431    #[derive(Default)]
432    struct ErrorParser;
433
434    impl Parser for ErrorParser {
435        fn id(&self) -> &'static str {
436            "test.error"
437        }
438
439        fn observe(&mut self, line: &LogLine<'_>, emitter: &mut Emitter<'_>) {
440            if line.text.contains("error:") {
441                emitter.diagnostic(Diagnostic {
442                    severity: Severity::Error,
443                    class: DiagnosticClass::Tool,
444                    code: Some("test.error".to_owned()),
445                    message: line.text.to_owned(),
446                    location: None,
447                    provenance: None,
448                    quality: EvidenceQuality::Structured,
449                    repetition_count: 1,
450                });
451            }
452        }
453    }
454
455    fn run(chunks: &[&[u8]]) -> Reduction {
456        let mut plan = ParserPlan::new();
457        plan.push(ErrorParser).unwrap();
458        let mut session = ReductionSession::new(
459            plan,
460            SessionOptions {
461                budget: Budget::unbounded(),
462                ..SessionOptions::default()
463            },
464            OutputPolicy::new(&NoRedaction, &NoPathMapping, &GenericRanker),
465        );
466        assert!(session.begin_scope(Scope::step("compile")));
467        for chunk in chunks {
468            assert!(session.push_chunk("compile", Stream::Stderr, chunk));
469        }
470        assert!(session.end_scope("compile", EndReason::Complete));
471        session.finish()
472    }
473
474    #[test]
475    fn arbitrary_chunking_produces_the_same_findings() {
476        let whole = run(&[b"note\nerror: broken\n"]);
477        let split = run(&[b"no", b"te\ner", b"ror: bro", b"ken\n"]);
478        assert_eq!(whole.diagnostics, split.diagnostics);
479        assert_eq!(whole.diagnostics.len(), 1);
480    }
481
482    #[test]
483    fn enforces_scope_and_line_bounds() {
484        let mut plan = ParserPlan::new();
485        plan.push(ErrorParser).unwrap();
486        let mut session = ReductionSession::new(
487            plan,
488            SessionOptions {
489                budget: Budget::unbounded(),
490                limits: crate::Limits {
491                    max_scope_bytes: 12,
492                    max_line_bytes: 8,
493                    ..crate::Limits::default()
494                },
495            },
496            OutputPolicy::new(&NoRedaction, &NoPathMapping, &GenericRanker),
497        );
498        session.begin_scope(Scope::step("compile"));
499        session.push_chunk("compile", Stream::Stderr, b"error: this line is too long\n");
500        session.end_scope("compile", EndReason::Complete);
501        let reduction = session.finish();
502        assert!(reduction.truncated);
503        assert!(reduction.stats.bytes_seen > reduction.stats.bytes_retained);
504    }
505
506    #[test]
507    fn rejects_duplicate_parser_ids() {
508        let mut plan = ParserPlan::new();
509        plan.push(ErrorParser).unwrap();
510        assert_eq!(
511            plan.push(ErrorParser).unwrap_err(),
512            ParserPlanError::DuplicateId("test.error")
513        );
514    }
515}