1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
//! Stack-trace frame resolution contract for `fallow trace-error`.
//!
//! The verb answers one narrow question: for each frame of a runtime stack
//! trace, which definitions in the analysed project does that frame's
//! identifier name? It is deliberately easy to overclaim here, so the wire
//! shape is built so that it cannot:
//!
//! - a frame that matches several definitions reports `ambiguous` and lists
//! every candidate, instead of picking one and calling it the answer;
//! - a frame that matches nothing reports `not_found` instead of being dropped;
//! - a frame that matches one definition but whose own line sits at a
//! different declaration carries `line_mismatch`, because the look-up asks
//! about the identifier and not about the line;
//! - a frame the project graph was never asked about (a dependency frame, a
//! runtime-internal frame, a generated bundle, or a frame carrying no
//! identifier to look up) reports `not_attempted` rather than borrowing
//! `not_found`'s meaning;
//! - every frame read from the input appears in `frames`, in input order, and
//! [`ErrorTraceCounts`](crate::trace_error::ErrorTraceCounts) publishes the
//! per-outcome totals, so a caller can see exactly how much of its trace
//! went unanswered.
//!
//! No source-map resolution is performed. A frame pointing into a build
//! artifact is reported as such, because a stale map rebinds silently to the
//! wrong line and a wrong line is worse than an honest refusal.
use serde::Serialize;
/// Wire-version discriminator for [`ErrorTrace`]. Independent from the global
/// `SchemaVersion` and from the other trace payloads, like
/// [`crate::trace::ImportPathTraceSchemaVersion`]. Serializes as a string
/// `const` so JSON consumers can switch on it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum ErrorTraceSchemaVersion {
/// First release of the `fallow trace-error` shape.
#[serde(rename = "1")]
V1,
}
/// Where a frame's source location sits relative to the analysed project.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum FrameOrigin {
/// The frame's file resolved to at least one module in the project graph.
/// Only these frames are looked up against the graph's definitions.
InProject,
/// The frame's file lives under an installed dependency tree.
NodeModules,
/// Everything else: a runtime-internal frame, a generated bundle, a file
/// outside the analysed corpus, or a frame carrying no source location.
OutOfCorpus,
}
impl FrameOrigin {
/// Stable kebab-case token for human output and diagnostics.
#[must_use]
pub const fn label(self) -> &'static str {
match self {
Self::InProject => "in-project",
Self::NodeModules => "node-modules",
Self::OutOfCorpus => "out-of-corpus",
}
}
}
/// What the project graph could say about a frame's identifier.
///
/// `not_attempted` is not a softer `not_found`: it records that the graph was
/// never consulted, because the frame does not point at project source. Keeping
/// them apart is what lets `resolved + ambiguous + not_found + not_attempted`
/// equal the frame count without any of the four lying about what it measured.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum FrameResolution {
/// Exactly one definition matched. `candidates` holds that one entry.
Resolved,
/// More than one definition matched. Every match is listed and none is
/// preferred; the caller decides, or narrows the question.
Ambiguous,
/// The graph was asked and knows no definition under this identifier. A
/// module-local function is not in the graph's definition set, so this is
/// also the answer for a frame naming one.
NotFound,
/// The graph was not asked. Either the frame does not point at project
/// source, or it points at project source but carries nothing addressable
/// to ask about: no printed function name, or a placeholder such as
/// `Object.<anonymous>`. `reason` names which case applies, so this is
/// never a silent shrug.
NotAttempted,
}
impl FrameResolution {
/// Stable kebab-case token for human output and diagnostics.
#[must_use]
pub const fn label(self) -> &'static str {
match self {
Self::Resolved => "resolved",
Self::Ambiguous => "ambiguous",
Self::NotFound => "not-found",
Self::NotAttempted => "not-attempted",
}
}
}
/// One definition a frame's identifier could name.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ErrorTraceCandidate {
/// Root-relative file declaring the definition.
pub file: String,
/// The exported name. For a member match this is the owning export.
pub symbol: String,
/// The member name, when the frame's identifier named a member of
/// `symbol` rather than `symbol` itself. Absent for a direct export match.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub member: Option<String>,
/// What kind of definition this is: `export`, or the member kind
/// (`class-method`, `class-property`, `enum-member`, `store-member`,
/// `namespace-member`).
pub kind: String,
/// 1-based declaration line of the definition's identifier. Absent when the
/// source file could not be read; never guessed.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub line: Option<u32>,
}
/// One frame read from the input stack trace.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ErrorTraceFrame {
/// 0-based position in the input trace, so a caller can quote a frame back
/// even after filtering the array.
pub index: usize,
/// The input line this frame was read from, trimmed of surrounding
/// whitespace and otherwise verbatim.
pub raw: String,
/// The frame's function identifier as written by the runtime, with the
/// `async` and `new` markers stripped and recorded separately. Absent for a
/// frame the runtime emitted without one.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub function: Option<String>,
/// Whether the runtime marked this frame as a constructor call (`new X`).
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub is_constructor: bool,
/// Whether the runtime marked this frame as an async call.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub is_async: bool,
/// The frame's file as read from the trace, with any `file://` or
/// `http(s)://` wrapper removed and separators forward-slashed. Reported as
/// read: it is NOT rewritten to the module path it matched, so a caller can
/// see what its runtime actually said. Absent for a frame with no location.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub file: Option<String>,
/// 1-based line from the frame's location, when the runtime supplied one.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub line: Option<u32>,
/// 1-based column from the frame's location, when the runtime supplied one.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub column: Option<u32>,
/// Where the frame's file sits relative to the analysed project.
pub origin: FrameOrigin,
/// What the project graph could say about this frame's identifier.
pub resolution: FrameResolution,
/// Every definition the identifier could name, in deterministic order.
/// Exactly one entry when `resolution` is `resolved`, more than one when it
/// is `ambiguous`, and empty otherwise.
pub candidates: Vec<ErrorTraceCandidate>,
/// How many further candidates a presentation cap withheld.
/// `candidates.len() + candidates_omitted` is the true match count, so an
/// `ambiguous` frame never understates how ambiguous it is.
pub candidates_omitted: usize,
/// Set when this frame's own line disagrees with the definition its
/// identifier matched: some OTHER definition in the same file is declared
/// closer above the line the runtime reported.
///
/// The look-up matches on the identifier alone, so a `resolved` frame is
/// resolved however far its line sits from the match. That is honest about
/// the question asked and silent about a question a reader would ask next,
/// which is why the disagreement is published instead of left to be
/// noticed. The frame is NOT reclassified: the graph does know a
/// definition under this identifier, and only the caller can say whether
/// the runtime ran that one or a same-named definition elsewhere.
/// `reason` names the declaration that sits closer. Only set on a
/// `resolved` frame that carried a line and matched a definition whose own
/// line could be read.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub line_mismatch: bool,
/// Human-readable statement of what happened to this frame.
pub reason: String,
}
/// Per-outcome totals for an [`ErrorTrace`].
///
/// `resolved + ambiguous + not_found + not_attempted == frames`, and
/// `in_project + node_modules + out_of_corpus == frames`. Both identities hold
/// on every run, so a caller can verify that nothing was dropped.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ErrorTraceCounts {
/// Frames reported in `frames`.
pub frames: usize,
/// Frames a cap withheld from `frames`. Their outcomes are NOT counted in
/// the fields below, which describe the reported frames only.
pub frames_omitted: usize,
/// Frames whose file resolved to project source.
pub in_project: usize,
/// Frames whose file lives under an installed dependency tree.
pub node_modules: usize,
/// Frames outside the analysed corpus, including frames with no location.
pub out_of_corpus: usize,
/// Frames that matched exactly one definition.
pub resolved: usize,
/// Frames that matched more than one definition.
pub ambiguous: usize,
/// Frames the graph was asked about and could not name.
pub not_found: usize,
/// Frames the graph was never asked about.
pub not_attempted: usize,
/// Non-blank input lines that were neither recognised as a frame nor taken
/// as `header`. A trace that is entirely unrecognised reports zero frames
/// and a non-zero count here, rather than looking like an empty trace.
pub unparsed_lines: usize,
}
/// Result of resolving a runtime stack trace against the project graph.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schema", schemars(title = "fallow trace-error"))]
pub struct ErrorTrace {
/// Wire-shape version of this payload.
pub schema_version: ErrorTraceSchemaVersion,
/// Where the trace was read from: `stdin`, or the path as the caller wrote
/// it.
pub source: String,
/// The first non-blank input line that preceded any recognised frame,
/// verbatim. Conventionally the error type and message, but it is reported
/// as read and NOT parsed into parts. Absent when the input began with a
/// frame or was empty.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub header: Option<String>,
/// Every recognised frame, in input order. Nothing is filtered out: a
/// dependency or runtime-internal frame stays in the array with its origin
/// recorded, so hop numbering matches the trace the caller pasted.
pub frames: Vec<ErrorTraceFrame>,
/// Per-outcome totals.
pub counts: ErrorTraceCounts,
/// Human-readable summary of the outcome.
pub reason: String,
}