Skip to main content

drep/analysis/
result.rs

1//! What one analysis pass produced.
2//!
3//! A single pass over a file can produce findings AND fail to fully analyze
4//! the file (a truncated response gives a partial list, an unknown severity
5//! in one record fails the file, a transport error produces zero findings but
6//! still surfaces as a failure). Reporting the findings while forgetting the
7//! failure is the exact bug this type exists to prevent — the gate would
8//! green-light a commit whenever the LLM endpoint was unreachable, which is
9//! worse than having no gate at all.
10//!
11//! `failed_files` is a [`BTreeMap`] rather than a `Vec` because two passes
12//! over the same file set must UNION, never sum. Summing counts one
13//! unreachable endpoint twice, drifting the failure count up without any
14//! matching file to investigate. The map's value carries the reason so the
15//! caller can render something a user can act on, not just a path.
16//!
17//! `dropped_out_of_range` counts rather than silently drops out-of-range
18//! findings so that a model which consistently reports wrong lines is
19//! observable to the caller — not invisible.
20
21use std::collections::BTreeMap;
22use std::fmt;
23use std::path::PathBuf;
24
25use crate::analysis::findings::Finding;
26use crate::llm::error::BackendErrorKind;
27
28/// Why one file went unanalyzed.
29///
30/// A bare set of paths cannot tell a dead endpoint from a rate limit from a
31/// truncated response, and the caller needs that to print something a user can
32/// act on. `LlmError` already carries the detail; it used to be discarded at
33/// the analyzer boundary.
34#[derive(Debug, Clone, PartialEq, Eq)]
35pub enum FailureReason {
36    /// The endpoint was unreachable, or returned a retryable status too many
37    /// times. `status` is the HTTP code when there was one.
38    Transport {
39        status: Option<u16>,
40        message: String,
41    },
42    /// A non-HTTP backend failed with a structured routing class.
43    Backend {
44        kind: BackendErrorKind,
45        message: String,
46    },
47    /// A response arrived and no JSON could be extracted from it.
48    Unparseable(String),
49    /// Cache-only review found no response for this exact prompt and provider.
50    CacheMiss,
51    /// A fresh semantic review was required after the configured remediation
52    /// budget had already been consumed. This is fail-closed: cached reviews
53    /// remain usable, but uncached code is never waved through unseen.
54    ReviewLimit { completed: u32, limit: u32 },
55    /// The model stopped before producing JSON, and the server said why.
56    ///
57    /// Distinct from [`Self::Unparseable`] because the cause is known and
58    /// deterministic - an output-token cap or a content filter - so the answer
59    /// is not "ask again" but "this request cannot be served as sent". `finish`
60    /// is the server's own word for it, kept as a machine tag beside the human
61    /// message exactly as [`Self::Transport`] keeps its status.
62    ModelStopped { finish: String, message: String },
63    /// The response parsed only after closing unbalanced delimiters, so it is
64    /// a prefix of what the model meant to say.
65    Truncated,
66    /// A record in the response could not be understood - unknown severity,
67    /// missing field, unusable line number.
68    MalformedFinding(String),
69    /// A deterministic tool that should have run could not.
70    ToolUnavailable { tool: String, detail: String },
71    /// A linter did not run because it would have read working-tree content the commit does not hold. `paths` are the differing files, as the user names them.
72    ///
73    /// Distinct from [`Self::ToolUnavailable`]: the tool is installed and
74    /// configured, but in staged mode it reads the working tree, and linting a
75    /// staged file's uncommitted edit would judge content the commit does not
76    /// contain - a lint-failing staged blob would pass. Refusing the run keeps
77    /// "unanalyzed is not clean" true for the deterministic layer too.
78    UncommittedChanges { tool: String, paths: Vec<PathBuf> },
79    /// Machine site policy refuses to have this repository's source reviewed by
80    /// a model, because a marker file is present at its root.
81    ///
82    /// A `FailureReason` rather than a run-level field because this is the type
83    /// the whole exit-2 contract already rests on: putting the refusal in
84    /// `failed_files` makes `gate`, the text failure block, the JSON `unanalyzed`
85    /// array and the clean-cycle reset guard treat it correctly with no second
86    /// mechanism to keep in agreement. A consumer asking "did semantic review
87    /// happen" is then told no, rather than handed an empty `unanalyzed` beside
88    /// exit 2.
89    ///
90    /// Both paths are carried because a developer meeting this for the first time
91    /// reads it as a broken install unless it names the file that caused it and
92    /// the policy that asked for it.
93    SitePolicyRefused { marker: PathBuf, policy: PathBuf },
94    /// The file on disk exceeded the read guard, so drep never read it.
95    ///
96    /// Distinct from [`Self::PayloadTooLarge`] because the two measure
97    /// different things: this is the file's own size, checked before any I/O,
98    /// and that one is the size of the text the model would have been sent.
99    /// They were one variant sharing one limit, which meant `bytes` held the
100    /// file size on one code path and the rendered-payload size on another -
101    /// so "file is too large (330102 bytes)" could name a file that `ls`
102    /// reports as 261900 bytes.
103    FileTooLarge { bytes: u64, limit: u64 },
104    /// The rendered LLM payload exceeded the ceiling. See [`Self::FileTooLarge`].
105    PayloadTooLarge { bytes: u64, limit: u64 },
106    /// The file could not be read from disk.
107    Unreadable(String),
108    /// The user named a file that the running command has no analyzer for.
109    ///
110    /// Only ever produced for an **explicitly named** path. A walk that turns
111    /// up nothing analyzable is legitimately empty - `drep check .` in a
112    /// documentation repository has correctly found no code. A path the user
113    /// typed is different: reporting "No issues found." for a file drep
114    /// declined to look at is the single failure this codebase is built to
115    /// prevent, and it is the same distinction `resolve_paths` already draws
116    /// for an argument that does not exist at all.
117    ///
118    /// `hint` names the command that *does* handle the type, when there is
119    /// one. Markdown has `drep lint-docs`, so the error is a redirection
120    /// rather than a dead end.
121    Unsupported {
122        /// The extension as written, with its dot. `None` when the file has
123        /// none, which reads differently in the message.
124        extension: Option<String>,
125        /// What to run instead, phrased as an imperative.
126        hint: Option<String>,
127    },
128    /// A failover chain produced no answer, with what each provider
129    /// contributed.
130    ///
131    /// Only produced for a chain of **two or more** providers. A one-provider
132    /// config - what `drep init` writes, and what almost every run uses -
133    /// collapses to that provider's own reason, so it reports exactly what it
134    /// did before failover existed, JSON `kind` included. The trigger is the
135    /// chain's length, not the number of providers that failed: a two-provider
136    /// chain stopped dead at the head by a 401 has one failure and is exactly
137    /// the case where "which provider, and why did my fallback not run" is the
138    /// user's live question.
139    ///
140    /// Keeping only the last reason would hide a dead local endpoint behind
141    /// the cloud fallback's 401; keeping only the first would hide the broken
142    /// fallback. A user fixing the run needs both.
143    ///
144    /// The list can be shorter than the chain - a 401 at the head stops it, and
145    /// the providers below were never consulted.
146    ChainFailed(Vec<ProviderFailure>),
147}
148
149/// One provider's contribution to a file that no provider could analyze.
150///
151/// `reason` is always a non-chain LLM-layer variant. That is a property of the
152/// only thing that builds these: the conversion runs over one provider's
153/// `LlmError`, so a nested `ChainFailed` is not merely absent but unreachable.
154#[derive(Debug, Clone, PartialEq, Eq)]
155pub struct ProviderFailure {
156    /// Zero-based position in the chain. Rendered one-based, matching how
157    /// `doctor` numbers the same list.
158    pub provider: usize,
159    /// The model that provider asks for.
160    pub model: String,
161    /// Why it did not produce an answer.
162    pub reason: FailureReason,
163    /// True when the provider was already demoted and was not contacted for
164    /// this file. Worth reporting: a user needs to know the local endpoint has
165    /// been dead since the third file, not just that the fallback then failed.
166    pub skipped: bool,
167}
168
169impl FailureReason {
170    /// Build an [`Self::Unsupported`] for `path`.
171    ///
172    /// The extension convention (leading dot, `None` when there is none) is
173    /// stated here, beside the variant whose `one_line` renders it, rather than
174    /// at each command that raises one. It was written out twice, which is one
175    /// copy per command pointing at the other.
176    pub fn unsupported(path: &std::path::Path, hint: Option<String>) -> Self {
177        FailureReason::Unsupported {
178            extension: path
179                .extension()
180                .map(|ext| format!(".{}", ext.to_string_lossy())),
181            hint,
182        }
183    }
184
185    /// A single line suitable for a terminal, derived from the variant.
186    ///
187    /// The HTTP status is rendered next to the message so a 429 is visible
188    /// without the user having to match the message against a status code
189    /// list. This is the load-bearing reason the `Transport` variant carries
190    /// the status as a number rather than only inside the string.
191    pub fn one_line(&self) -> String {
192        match self {
193            FailureReason::Transport {
194                status: Some(code),
195                message,
196            } => {
197                format!("LLM transport failed (HTTP {code}): {message}")
198            }
199            FailureReason::Transport {
200                status: None,
201                message,
202            } => {
203                format!("LLM transport failed: {message}")
204            }
205            FailureReason::Unparseable(message) => {
206                format!("LLM response was unparseable: {message}")
207            }
208            FailureReason::CacheMiss => {
209                "LLM review is not cached; run a normal check to warm it".to_owned()
210            }
211            FailureReason::ReviewLimit { completed, limit } if completed < limit => format!(
212                "fresh LLM review capacity is currently reserved ({completed} completed of \
213                 {limit}); wait for the in-flight review, pass `--max-review-rounds N`, or pass \
214                 `--unlimited-reviews` to authorize another round"
215            ),
216            FailureReason::ReviewLimit { completed, limit } => format!(
217                "fresh LLM review limit reached ({completed} of {limit}); raise \
218                 `max_review_rounds`, pass `--max-review-rounds N`, or pass \
219                 `--unlimited-reviews` to authorize another round"
220            ),
221            FailureReason::Backend { kind, message } => {
222                format!("LLM backend {kind}: {message}")
223            }
224            // Deliberately says nothing about *which* command is running: both
225            // `check` and `lint-docs` produce this, pointing at each other.
226            FailureReason::Unsupported { extension, hint } => {
227                let what = match extension {
228                    Some(ext) => format!("`{ext}` files"),
229                    None => "files with no extension".to_owned(),
230                };
231                match hint {
232                    Some(hint) => format!("no analyzer for {what}: {hint}"),
233                    None => format!("no analyzer for {what}"),
234                }
235            }
236            // The message is already a sentence a user can act on; prefixing it
237            // with a category would bury the actionable half.
238            FailureReason::ModelStopped { message, .. } => message.clone(),
239            FailureReason::Truncated => "response was truncated".to_owned(),
240            FailureReason::MalformedFinding(detail) => format!("malformed finding: {detail}"),
241            FailureReason::ToolUnavailable { tool, detail } => {
242                format!("{tool} could not run: {detail}")
243            }
244            FailureReason::UncommittedChanges { tool, paths } => {
245                let paths = paths
246                    .iter()
247                    .map(|path| crate::text::path_label_of(path))
248                    .collect::<Vec<_>>()
249                    .join(", ");
250                format!(
251                    "{tool} did not run: the working tree differs from the commit at {paths}; stage those changes or run `git stash --keep-index --include-untracked` first"
252                )
253            }
254            FailureReason::SitePolicyRefused { marker, policy } => format!(
255                "semantic review is refused by site policy: {} is present (policy: {})",
256                crate::text::path_label_of(marker),
257                crate::text::path_label_of(policy)
258            ),
259            FailureReason::FileTooLarge { bytes, limit } => {
260                format!("file is too large to read ({bytes} bytes; limit is {limit})")
261            }
262            FailureReason::PayloadTooLarge { bytes, limit } => {
263                format!("the code sent for review is too large ({bytes} bytes; limit is {limit})")
264            }
265            FailureReason::Unreadable(detail) => format!("file could not be read: {detail}"),
266            FailureReason::ChainFailed(failures) => {
267                let each: Vec<String> = failures.iter().map(ProviderFailure::one_line).collect();
268                // Phrased by what happened, not by a count. "All N providers
269                // failed" is wrong for the case that matters most - a chain
270                // stopped at the head by a 401 has one entry and more
271                // providers behind it that were deliberately not asked.
272                if each.is_empty() {
273                    "no LLM provider analyzed this file".to_owned()
274                } else {
275                    format!("no LLM provider analyzed this file: {}", each.join("; "))
276                }
277            }
278        }
279    }
280
281    /// The HTTP status, when the failure had one.
282    ///
283    /// Only `Transport` ever carries one. Exposed as a number rather than
284    /// left inside the message because a caller has to distinguish a 429 from
285    /// a 401 - the message is prose and prose gets reworded.
286    pub fn status(&self) -> Option<u16> {
287        match self {
288            FailureReason::Transport { status, .. } => *status,
289            // Deliberately not "the first attempt's status". A chain failure
290            // has one status *per provider*, and flattening them to one number
291            // would tell a consumer a 401 was the whole story when a 500 came
292            // first. The JSON renderer exposes the per-provider list instead.
293            _ => None,
294        }
295    }
296}
297
298impl ProviderFailure {
299    /// One line naming the provider, its model, and what it said.
300    pub fn one_line(&self) -> String {
301        let skipped = if self.skipped {
302            " (already down earlier in this run)"
303        } else {
304            ""
305        };
306        format!(
307            "[{}] {}: {}{}",
308            self.provider + 1,
309            self.model,
310            self.reason.one_line(),
311            skipped
312        )
313    }
314}
315
316impl fmt::Display for FailureReason {
317    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
318        f.pad(&self.one_line())
319    }
320}
321
322/// What one analysis pass produced.
323///
324/// `findings` and `failed_files` are independent axes: a file can contribute
325/// findings AND be unanalyzed (a truncated response gives a partial list).
326/// Reporting the findings while forgetting the failure is the exact bug this
327/// type exists to prevent.
328#[derive(Debug, Default, Clone, PartialEq, Eq)]
329pub struct AnalysisResult {
330    /// Findings the analyzer could attribute to a real line of code.
331    pub findings: Vec<Finding>,
332    /// Files that could not be fully analyzed, with the reason. A `BTreeMap`
333    /// because two passes over the same file set must UNION, never sum —
334    /// summing counts one unreachable endpoint twice.
335    pub failed_files: BTreeMap<PathBuf, FailureReason>,
336    /// Findings discarded because their line was not in the payload's
337    /// `valid_lines`. Counted rather than silently dropped, so the drop is
338    /// observable.
339    pub dropped_out_of_range: usize,
340}
341
342/// Fold `src` into `dst`, keeping the reason already present on a collision.
343///
344/// The one statement of the failure-union rule. It was written out longhand as
345/// `entry().or_insert()` at four sites - `merge` here plus three in the CLI -
346/// each with its own comment re-explaining it. The two analysis layers cover
347/// the same files, so the sets union rather than sum: one unreachable endpoint
348/// is one failure, not two. First-wins because the reasons cannot be
349/// meaningfully combined and the earlier layer saw the file first.
350pub fn union_failures(
351    dst: &mut BTreeMap<PathBuf, FailureReason>,
352    src: BTreeMap<PathBuf, FailureReason>,
353) {
354    for (path, reason) in src {
355        dst.entry(path).or_insert(reason);
356    }
357}
358
359impl AnalysisResult {
360    /// One file, one failure, no findings.
361    ///
362    /// The shape was hand-assembled at four call sites - `default()`, insert,
363    /// return - each of which independently had to know that `findings` and
364    /// `dropped_out_of_range` stay at their defaults. Forgetting the insert at
365    /// any one of them reports an unanalyzed file as clean, which is the single
366    /// failure this whole type exists to prevent, so it gets a constructor.
367    pub fn failed(path: PathBuf, reason: FailureReason) -> Self {
368        let mut result = Self::default();
369        result.failed_files.insert(path, reason);
370        result
371    }
372
373    /// Fold `other` into `self`: findings concatenate, `failed_files`
374    /// unions, `dropped_out_of_range` sums.
375    ///
376    /// The merge semantics let a caller combine per-file and per-layer results
377    /// without losing the failure signal.
378    ///
379    /// On a key collision in `failed_files`, the **first** reason wins. A
380    /// file failing twice is still one failure, and the two reasons are not
381    /// meaningfully combinable - the first one is at least specific to the
382    /// file, while a hypothetical last-wins policy would let a later
383    /// analyzer overwrite a more informative first reason with a generic
384    /// one.
385    pub fn merge(&mut self, other: AnalysisResult) {
386        self.findings.extend(other.findings);
387        // `union_failures` rather than the loop written out again: the
388        // first-writer-wins rule is one decision, and two copies of it are two
389        // places for it to change independently.
390        union_failures(&mut self.failed_files, other.failed_files);
391        self.dropped_out_of_range = self
392            .dropped_out_of_range
393            .saturating_add(other.dropped_out_of_range);
394    }
395
396    /// True when any file went unanalyzed.
397    ///
398    /// The caller maps this to process exit 2: "could not analyze" is
399    /// distinct from both "clean" (exit 0) and "found issues" (exit 1),
400    /// because a gate that cannot distinguish them rubber-stamps the day
401    /// the LLM endpoint goes down.
402    pub fn has_failures(&self) -> bool {
403        !self.failed_files.is_empty()
404    }
405}
406
407#[cfg(test)]
408mod tests {
409    use super::*;
410
411    /// `merge` keeps the first reason on a key collision - the documented
412    /// first-writer-wins rule. A last-wins policy would silently overwrite
413    /// the more informative first reason with a generic later one.
414    #[test]
415    fn merge_keeps_first_reason_on_key_collision() {
416        let mut a = AnalysisResult::default();
417        a.failed_files.insert(
418            PathBuf::from("src/lib.rs"),
419            FailureReason::Transport {
420                status: Some(429),
421                message: "rate limited".to_owned(),
422            },
423        );
424
425        let mut b = AnalysisResult::default();
426        b.failed_files.insert(
427            PathBuf::from("src/lib.rs"),
428            FailureReason::Transport {
429                status: Some(500),
430                message: "internal".to_owned(),
431            },
432        );
433
434        a.merge(b);
435
436        assert_eq!(a.failed_files.len(), 1);
437        let reason = a.failed_files.get(&PathBuf::from("src/lib.rs")).unwrap();
438        assert_eq!(
439            reason,
440            &FailureReason::Transport {
441                status: Some(429),
442                message: "rate limited".to_owned(),
443            },
444            "first reason wins on collision"
445        );
446    }
447
448    /// A `Transport` failure with a status surfaces the code in the rendered
449    /// line. The whole point of keeping the status as a number is that it
450    /// reaches the user; this pins that the rendering preserves it.
451    #[test]
452    fn transport_render_includes_the_http_status() {
453        let reason = FailureReason::Transport {
454            status: Some(429),
455            message: "rate limited".to_owned(),
456        };
457        let rendered = reason.one_line();
458        assert!(
459            rendered.contains("429"),
460            "rendered line must contain 429, got {rendered:?}"
461        );
462    }
463
464    /// A refusal names both the marker and the policy that asked for it.
465    ///
466    /// Pinned at the type that owns the wording, beside the `Transport`-status
467    /// test, and for the same reason: the paths are carried as fields precisely so
468    /// they reach the user. A developer meeting this line for the first time reads
469    /// it as a broken install unless it says which file caused it and where the
470    /// decision came from.
471    #[test]
472    fn site_policy_refusal_names_the_marker_and_the_policy_file() {
473        let reason = FailureReason::SitePolicyRefused {
474            marker: PathBuf::from("/work/repo/.drep-no-llm"),
475            policy: PathBuf::from("/etc/drep/site.toml"),
476        };
477        let rendered = reason.one_line();
478        assert!(
479            rendered.contains("/work/repo/.drep-no-llm"),
480            "must name the marker, got {rendered:?}"
481        );
482        assert!(
483            rendered.contains("/etc/drep/site.toml"),
484            "must name the policy, got {rendered:?}"
485        );
486    }
487
488    #[test]
489    fn display_honours_formatter_width_and_alignment() {
490        let reason = FailureReason::Truncated;
491        assert_eq!(
492            format!("{reason:>30}"),
493            format!("{:>30}", reason.one_line())
494        );
495    }
496}