cli: specialize error for missing workflows dir in remote input (#1324)

crates/zizmor/src/github.rs

@@ -711,7 +711,13 @@ impl Client {
             .await
             .map_err(ClientError::from)?
             .error_for_status()
-            .map_err(ClientError::from)?
+            .map_err(|err| match err {
+                // TODO: Disambiguate a 404 from missing repo vs missing workflows dir.
+                e if e.status() == Some(StatusCode::NOT_FOUND) => {
+                    CollectionError::RemoteWithoutWorkflows(ClientError::from(e), slug.to_string())
+                }
+                e => ClientError::from(e).into(),
+            })?
             .json()
             .await
             .map_err(ClientError::from)?;

crates/zizmor/src/main.rs

@@ -931,6 +931,24 @@ async fn main() -> ExitCode {
 
                         Some(report)
                     }
+                    CollectionError::RemoteWithoutWorkflows(_, slug) => {
+                        let group = Group::with_title(Level::ERROR.primary_title(err.to_string()))
+                            .elements([
+                                Level::HELP.message(
+                                    format!(
+                                        "ensure that {slug} contains one or more workflows under `.github/workflows/`"
+                                    )
+                                ),
+                                Level::HELP.message(
+                                    format!("ensure that {slug} exists and you have access to it")
+                                )
+                            ]);
+
+                        let renderer = Renderer::styled();
+                        let report = renderer.render(&[group]);
+
+                        Some(report)
+                    }
                     _ => None,
                 },
                 _ => None,

crates/zizmor/src/registry/input.rs

@@ -72,6 +72,12 @@ pub(crate) enum CollectionError {
     #[error("invalid input: must have .yml or .yaml extension")]
     InvalidExtension,
 
+    /// Workflow-specific collection was requested, but the remote
+    /// input doesn't contain any workflows. This typically means the remote
+    /// repository doesn't have a `.github` or `.github/workflows` directory.
+    #[error("input {1} doesn't contain any workflows")]
+    RemoteWithoutWorkflows(#[source] ClientError, String),
+
     /// A GitHub API error occurred while fetching a remote input.
     #[error("GitHub API error while fetching remote input")]
     Client(#[from] ClientError),

crates/zizmor/tests/integration/e2e.rs

@@ -396,3 +396,37 @@ fn issue_1286() -> Result<()> {
 
     Ok(())
 }
+
+/// Regression test for #1300.
+///
+/// Ensures that we produce a useful error when a user specifies
+/// `--collect=workflows` on a remote input that doesn't have a
+/// `.github/workflows/` directory.
+#[cfg_attr(not(feature = "gh-token-tests"), ignore)]
+#[test]
+fn issue_1300() -> Result<()> {
+    insta::assert_snapshot!(
+        zizmor()
+            .expects_failure(true)
+            .output(OutputMode::Both)
+            .offline(false)
+            .args(["--collect=workflows"])
+            .input("woodruffw-experiments/empty")
+            .run()?,
+        @r"
+    🌈 zizmor v@@VERSION@@
+    fatal: no audit was performed
+    error: input @@INPUT@@ doesn't contain any workflows
+      |
+      = help: ensure that @@INPUT@@ contains one or more workflows under `.github/workflows/`
+      = help: ensure that @@INPUT@@ exists and you have access to it
+
+    Caused by:
+        0: input @@INPUT@@ doesn't contain any workflows
+        1: request error while accessing GitHub API
+        2: HTTP status client error (404 Not Found) for url (https://api.github.com/repos/@@INPUT@@/contents/.github/workflows)
+    "
+    );
+
+    Ok(())
+}

docs/release-notes.md

@@ -9,6 +9,11 @@ of `zizmor`.
 
 ## Next (UNRELEASED)
 
+### Enhancements 🌱
+
+* `zizmor` now produces a more useful error message when asked to
+  collect only workflows from a remote input that contains no workflows (#1324)
+
 ### Performance Improvements 🚄
 
 * `zizmor`'s core has been refactored to be asynchronous, making online