Skip to main content

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 {}