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