Skip to main content

tokencompact_core/
model.rs

1use serde::{Deserialize, Serialize};
2
3/// Severity assigned by a parser or structured-input adapter.
4#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
5#[serde(rename_all = "snake_case")]
6pub enum Severity {
7    Error,
8    Warning,
9    Note,
10}
11
12/// Provider-neutral diagnostic family used by presentation adapters.
13#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
14#[non_exhaustive]
15#[serde(rename_all = "snake_case")]
16pub enum DiagnosticClass {
17    Compiler,
18    Test,
19    Lint,
20    Tool,
21    Infrastructure,
22}
23
24/// How directly a finding is supported by the observed evidence.
25#[derive(Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
26#[serde(rename_all = "snake_case")]
27pub enum EvidenceQuality {
28    Located,
29    #[default]
30    Structured,
31    Summary,
32    Fallback,
33}
34
35/// Optional source coordinate extracted from diagnostic text.
36#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
37pub struct Location {
38    pub path: String,
39    pub line: Option<u32>,
40    pub column: Option<u32>,
41}
42
43/// Input channel within a scope.
44#[derive(Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
45#[serde(rename_all = "snake_case")]
46pub enum Stream {
47    Stdout,
48    Stderr,
49    #[default]
50    Combined,
51    Annotation,
52    Structured,
53}
54
55/// Provider-neutral unit that owns a related log stream.
56#[derive(Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
57#[serde(rename_all = "snake_case")]
58pub enum ScopeKind {
59    Invocation,
60    Job,
61    Step,
62    Command,
63    Test,
64    Attempt,
65    #[default]
66    Other,
67}
68
69/// Caller-owned identity for one independently bounded parser scope.
70#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
71pub struct Scope {
72    pub id: String,
73    pub kind: ScopeKind,
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub label: Option<String>,
76}
77
78impl Scope {
79    #[must_use]
80    pub fn new(id: impl Into<String>, kind: ScopeKind) -> Self {
81        Self {
82            id: id.into(),
83            kind,
84            label: None,
85        }
86    }
87
88    #[must_use]
89    pub fn with_label(mut self, label: impl Into<String>) -> Self {
90        self.label = Some(label.into());
91        self
92    }
93
94    #[must_use]
95    pub fn step(id: impl Into<String>) -> Self {
96        Self::new(id, ScopeKind::Step)
97    }
98}
99
100/// Why a parser scope ended.
101#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
102#[serde(rename_all = "snake_case")]
103pub enum EndReason {
104    Complete,
105    Truncated,
106    Cancelled,
107    Interrupted,
108}
109
110/// Caller and state-machine provenance for one returned finding.
111#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
112pub struct Provenance {
113    pub source: String,
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub label: Option<String>,
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub scope_id: Option<String>,
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub scope_kind: Option<ScopeKind>,
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub stream: Option<Stream>,
122    #[serde(skip_serializing_if = "Option::is_none")]
123    pub start_line: Option<u64>,
124    #[serde(skip_serializing_if = "Option::is_none")]
125    pub end_line: Option<u64>,
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub parser: Option<String>,
128}
129
130impl Provenance {
131    #[must_use]
132    pub fn new(source: impl Into<String>) -> Self {
133        Self {
134            source: source.into(),
135            label: None,
136            scope_id: None,
137            scope_kind: None,
138            stream: None,
139            start_line: None,
140            end_line: None,
141            parser: None,
142        }
143    }
144
145    #[must_use]
146    pub fn with_label(mut self, label: impl Into<String>) -> Self {
147        self.label = Some(label.into());
148        self
149    }
150
151    #[must_use]
152    pub fn with_scope(mut self, scope: &Scope) -> Self {
153        self.scope_id = Some(scope.id.clone());
154        self.scope_kind = Some(scope.kind);
155        if self.label.is_none() {
156            self.label = scope.label.clone();
157        }
158        self
159    }
160
161    #[must_use]
162    pub fn with_span(mut self, stream: Stream, start_line: u64, end_line: u64) -> Self {
163        self.stream = Some(stream);
164        self.start_line = Some(start_line);
165        self.end_line = Some(end_line.max(start_line));
166        self
167    }
168
169    #[must_use]
170    pub fn with_parser(mut self, parser: impl Into<String>) -> Self {
171        self.parser = Some(parser.into());
172        self
173    }
174}
175
176/// One normalized and redacted diagnostic.
177#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
178pub struct Diagnostic {
179    pub severity: Severity,
180    pub class: DiagnosticClass,
181    #[serde(skip_serializing_if = "Option::is_none")]
182    pub code: Option<String>,
183    pub message: String,
184    #[serde(skip_serializing_if = "Option::is_none")]
185    pub location: Option<Location>,
186    #[serde(skip_serializing_if = "Option::is_none")]
187    pub provenance: Option<Provenance>,
188    #[serde(default, skip_serializing_if = "is_structured_quality")]
189    pub quality: EvidenceQuality,
190    pub repetition_count: u32,
191}
192
193fn is_structured_quality(value: &EvidenceQuality) -> bool {
194    *value == EvidenceQuality::Structured
195}
196
197/// Structured failed-test evidence independent of a particular test provider.
198#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
199pub struct TestFailure {
200    pub name: String,
201    pub message: String,
202    #[serde(skip_serializing_if = "Option::is_none")]
203    pub framework: Option<String>,
204    #[serde(skip_serializing_if = "Option::is_none")]
205    pub location: Option<Location>,
206    #[serde(skip_serializing_if = "Option::is_none")]
207    pub provenance: Option<Provenance>,
208}
209
210/// Combined item and serialized-finding byte limits.
211#[derive(Clone, Copy, Debug, Eq, PartialEq)]
212pub struct Budget {
213    pub max_bytes: usize,
214    pub max_items: usize,
215}
216
217impl Budget {
218    #[must_use]
219    pub const fn unbounded() -> Self {
220        Self {
221            max_bytes: usize::MAX,
222            max_items: usize::MAX,
223        }
224    }
225}
226
227/// Controls whether unclaimed actionable lines may become tool diagnostics.
228#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
229pub enum FallbackPolicy {
230    Disabled,
231    #[default]
232    Generic,
233}
234
235/// Stable options for one synchronous batch reduction call.
236#[derive(Clone, Copy, Debug, Eq, PartialEq)]
237pub struct ReductionOptions {
238    pub budget: Budget,
239    pub fallback: FallbackPolicy,
240}
241
242impl Default for ReductionOptions {
243    fn default() -> Self {
244        Self {
245            budget: Budget {
246                max_bytes: 4 * 1024,
247                max_items: 20,
248            },
249            fallback: FallbackPolicy::Generic,
250        }
251    }
252}
253
254/// Hard bounds for incremental input and candidate retention.
255#[derive(Clone, Copy, Debug, Eq, PartialEq)]
256pub struct Limits {
257    pub max_scopes: usize,
258    pub max_scope_bytes: usize,
259    pub max_line_bytes: usize,
260    pub max_candidates: usize,
261}
262
263impl Default for Limits {
264    fn default() -> Self {
265        Self {
266            max_scopes: 128,
267            max_scope_bytes: 1024 * 1024,
268            max_line_bytes: 64 * 1024,
269            max_candidates: 10_000,
270        }
271    }
272}
273
274/// Options for an incremental reduction session.
275#[derive(Clone, Copy, Debug, Eq, PartialEq)]
276pub struct SessionOptions {
277    pub budget: Budget,
278    pub limits: Limits,
279}
280
281impl Default for SessionOptions {
282    fn default() -> Self {
283        Self {
284            budget: ReductionOptions::default().budget,
285            limits: Limits::default(),
286        }
287    }
288}
289
290/// Borrowed text plus optional owned output provenance.
291#[derive(Clone, Copy, Debug)]
292pub struct TextInput<'a> {
293    pub text: &'a [u8],
294    pub provenance: Option<&'a Provenance>,
295}
296
297impl<'a> TextInput<'a> {
298    #[must_use]
299    pub const fn new(text: &'a [u8]) -> Self {
300        Self {
301            text,
302            provenance: None,
303        }
304    }
305
306    #[must_use]
307    pub const fn with_provenance(mut self, provenance: &'a Provenance) -> Self {
308        self.provenance = Some(provenance);
309        self
310    }
311}
312
313/// One normalized input line delivered to an immutable parser plan.
314#[derive(Clone, Copy, Debug)]
315pub struct LogLine<'a> {
316    pub scope: &'a Scope,
317    pub stream: Stream,
318    pub ordinal: u64,
319    pub stream_line: u64,
320    pub text: &'a str,
321    pub truncated: bool,
322}
323
324/// Accounting that never contains raw input text.
325#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
326pub struct ReductionStats {
327    pub bytes_seen: u64,
328    pub bytes_retained: u64,
329    pub lines_seen: u64,
330    pub truncated_lines: u64,
331    pub scopes_started: u64,
332    pub scopes_completed: u64,
333    pub candidates_emitted: u64,
334    pub candidates_dropped: u64,
335    pub omitted_test_failures: usize,
336}
337
338/// Bounded result and explicit truncation accounting.
339#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
340pub struct Reduction {
341    pub diagnostics: Vec<Diagnostic>,
342    #[serde(default, skip_serializing_if = "Vec::is_empty")]
343    pub test_failures: Vec<TestFailure>,
344    pub truncated: bool,
345    pub omitted_diagnostics: usize,
346    pub used_bytes: usize,
347    #[serde(default, skip_serializing_if = "is_default_stats")]
348    pub stats: ReductionStats,
349}
350
351fn is_default_stats(value: &ReductionStats) -> bool {
352    value == &ReductionStats::default()
353}