Skip to main content

critpath_core/
error.rs

1//! Errors reported when a graph cannot be built.
2
3use core::fmt;
4
5use crate::graph::UnitId;
6use crate::millis::Millis;
7
8/// A graph that could not be constructed, and why.
9///
10/// Every variant names the units involved, because the caller building the graph is a program
11/// translating some build system's output and needs to know which piece of that output was wrong.
12#[derive(Clone, Debug, PartialEq, Eq)]
13#[non_exhaustive]
14pub enum GraphError {
15    /// More units were added than can be addressed.
16    UnitLimitExceeded {
17        /// The largest number of units supported.
18        limit: usize,
19    },
20    /// An edge named a unit that was never added.
21    UnknownUnit {
22        /// The identifier that does not belong to this graph.
23        id: UnitId,
24        /// How many units the graph does contain.
25        units: usize,
26    },
27    /// A unit was given itself as a dependency.
28    SelfDependency {
29        /// The unit that depends on itself.
30        unit: UnitId,
31    },
32    /// A metadata edge leaves a unit that never emits metadata.
33    MetadataEdgeFromOpaqueUnit {
34        /// The unit the edge leaves, which has no `metadata_at`.
35        producer: UnitId,
36        /// The unit the edge arrives at.
37        consumer: UnitId,
38    },
39    /// A unit claims to emit its metadata after it has already finished.
40    MetadataAfterCompletion {
41        /// The offending unit.
42        unit: UnitId,
43        /// When it claims to emit metadata.
44        metadata_at: Millis,
45        /// How long it runs in total.
46        total: Millis,
47    },
48    /// The dependencies contain a cycle, so no build order exists.
49    Cycle {
50        /// The units forming one cycle, in dependency order. There may be others.
51        units: Vec<UnitId>,
52    },
53}
54
55impl fmt::Display for GraphError {
56    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57        match self {
58            Self::UnitLimitExceeded { limit } => write!(
59                f,
60                "the graph cannot hold more than {limit} units; \
61                 analyse a subset of the workspace instead"
62            ),
63            Self::UnknownUnit { id, units } => write!(
64                f,
65                "unit {id} was named by an edge but this graph holds only {units} units; \
66                 an identifier is only meaningful for the graph that produced it, and one from \
67                 elsewhere is caught here only when it happens to point past the end"
68            ),
69            Self::SelfDependency { unit } => write!(
70                f,
71                "unit {unit} depends on itself, so it can never start; \
72                 drop the edge, since a unit is always available to itself"
73            ),
74            Self::MetadataEdgeFromOpaqueUnit { producer, consumer } => write!(
75                f,
76                "the edge from unit {producer} to unit {consumer} is a metadata edge, \
77                 but unit {producer} emits no metadata; \
78                 make it a full edge, or give unit {producer} a metadata_at time"
79            ),
80            Self::MetadataAfterCompletion {
81                unit,
82                metadata_at,
83                total,
84            } => write!(
85                f,
86                "unit {unit} emits metadata at {metadata_at} but finishes after {total}; \
87                 metadata cannot be emitted after the unit that emits it has ended, \
88                 so check the parser that produced these two numbers"
89            ),
90            Self::Cycle { units } => {
91                write!(
92                    f,
93                    "the dependencies contain a cycle, so no build order exists: "
94                )?;
95                for (i, unit) in units.iter().enumerate() {
96                    if i > 0 {
97                        write!(f, " -> ")?;
98                    }
99                    write!(f, "unit {unit}")?;
100                }
101                write!(
102                    f,
103                    "; a build graph is acyclic, so this is a defect in whatever produced it"
104                )
105            }
106        }
107    }
108}
109
110impl std::error::Error for GraphError {}