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