composer_install/error.rs
1//! Typed install errors.
2//!
3//! Errors travel as [`eyre::Report`]s, but the ones a caller may want to
4//! treat specially have an [`InstallError`] at their root, so they can be
5//! recovered with `report.downcast_ref::<InstallError>()` (or by walking
6//! `report.chain()`) and mapped to an exit code or a tool-specific hint.
7
8use std::fmt;
9use std::path::PathBuf;
10
11/// An install failure a caller can match on.
12#[derive(Debug, Clone, PartialEq, Eq)]
13#[non_exhaustive]
14pub enum InstallError {
15 /// The project has no `composer.json`.
16 MissingManifest {
17 /// The path that was looked for.
18 path: PathBuf,
19 },
20 /// The project has a `composer.json` but no `composer.lock`.
21 MissingLock {
22 /// The path that was looked for.
23 path: PathBuf,
24 },
25 /// `composer.json` is not valid JSON.
26 InvalidManifest {
27 /// The manifest's path.
28 path: PathBuf,
29 /// The parser's message.
30 detail: String,
31 },
32 /// The lock needs features this installer does not handle (an
33 /// unsupported dist type, a non-git source, …). Every blocker is listed,
34 /// so the user can fix them in one pass.
35 Unsupported {
36 /// One human-readable reason per blocking package.
37 reasons: Vec<String>,
38 },
39 /// A `git` command failed while installing a source package.
40 Vcs {
41 /// What kind of failure, classified from git's stderr.
42 failure: VcsFailure,
43 /// The git step that failed (`clone`, `fetch`, `checkout`, …).
44 operation: String,
45 /// The repository URL, or empty when git itself could not run.
46 url: String,
47 /// git's stderr, trimmed.
48 detail: String,
49 },
50}
51
52/// Why a git command failed.
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54#[non_exhaustive]
55pub enum VcsFailure {
56 /// `git` is not installed or not on `PATH`.
57 GitMissing,
58 /// The repository is private or the credentials were refused.
59 Auth,
60 /// The locked commit is not on the remote.
61 MissingRef,
62 /// The repository could not be reached.
63 Unreachable,
64 /// Anything else; see the detail.
65 Other,
66}
67
68impl VcsFailure {
69 /// A tool-neutral suggestion for the user.
70 pub fn hint(self) -> &'static str {
71 match self {
72 Self::GitMissing => {
73 "install git and make sure it is on PATH; git sources are installed with the \
74 system git"
75 }
76 Self::Auth => {
77 "the repository is private or the credentials are wrong; configure a git \
78 credential helper or ssh key"
79 }
80 Self::MissingRef => {
81 "the locked commit is not on the remote; the lock may point at an unpushed or \
82 force-pushed commit, so update the lock to re-resolve it"
83 }
84 Self::Unreachable => {
85 "the repository could not be reached; check the URL and your network access"
86 }
87 Self::Other => "see git's output above",
88 }
89 }
90}
91
92impl fmt::Display for InstallError {
93 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
94 match self {
95 Self::MissingManifest { path } => {
96 write!(f, "{} not found — not a Composer project", path.display())
97 }
98 Self::MissingLock { path } => write!(
99 f,
100 "{} not found — run `composer update` first to generate it",
101 path.display()
102 ),
103 Self::InvalidManifest { path, detail } => {
104 write!(f, "parsing {}: {detail}", path.display())
105 }
106 Self::Unsupported { reasons } => {
107 write!(
108 f,
109 "this lockfile requires features this installer does not handle:"
110 )?;
111 for r in reasons {
112 write!(f, "\n - {r}")?;
113 }
114 Ok(())
115 }
116 Self::Vcs {
117 failure,
118 operation,
119 url,
120 detail,
121 } => {
122 write!(f, "git {operation} failed")?;
123 if !url.is_empty() {
124 write!(f, " for {url}")?;
125 }
126 if !detail.is_empty() {
127 write!(f, ": {detail}")?;
128 }
129 write!(f, "\nhint: {}", failure.hint())
130 }
131 }
132 }
133}
134
135impl std::error::Error for InstallError {}