chore: to production

README.md

@@ -13,7 +13,7 @@ From this repository's root (e.g., after cloning), try the included bookstore ex
 
 ```console
 $ oapi-codegen --config-file examples/bookstore/oapi-codegen-server.yaml examples/bookstore/openapi.yaml
-✓ wrote generated/restapi.rs
+✓ wrote generated/restapi.rs and 15 modules beside it
   note: add the crates the generated code references to Cargo.toml:
       serde = { version = "1.0.229", features = ["derive"] }
       serde_json = "1.0.151"

crates/oapi-codegen/Cargo.toml

@@ -53,4 +53,4 @@ reqwest = { version = "0.13.4", default-features = false, features = ["blocking"
 serde = { version = "1.0.229", features = ["derive"] }
 serde_urlencoded = "0.7.1"
 trycmd = "1.2.1"
-uuid = { version = "1.24.0", features = ["serde"] }
+uuid = { version = "1.24.1", features = ["serde"] }

crates/oapi-codegen/src/console.rs

@@ -127,34 +127,59 @@ pub fn report_empty_output(spec: &Path, stats: &SpecStats, generate: &Generate)
     }
 }
 
-/// Report a successful write to `path`.
-pub fn report_wrote(path: &Path) {
-    eprintln!("{} wrote {}", "✓".green().bold(), path.display());
+/// Report that generation wrote its output.
+///
+/// A run that splits its output names the root file and counts the rest: the
+/// root is the file a consumer mounts, and the count says the tree beside it is
+/// part of the same artifact.
+pub fn report_wrote(path: &Path, files: usize) {
+    let modules = files.saturating_sub(1);
+    if modules == 0 {
+        eprintln!("{} wrote {}", "✓".green().bold(), path.display());
+        return;
+    }
+    let plural = if modules == 1 { "module" } else { "modules" };
+    eprintln!(
+        "{} wrote {} and {modules} {plural} beside it",
+        "✓".green().bold(),
+        path.display()
+    );
 }
 
 /// Report that `--check` found `path` up to date.
 pub fn report_check_passed(path: &Path) {
     eprintln!("{} {} is up to date", "✓".green().bold(), path.display());
 }
 
+/// What `--check` found at the file it stopped on.
+#[derive(Debug, Clone, Copy)]
+pub enum DriftKind {
+    /// Generation writes the file, and it is not there.
+    Absent,
+    /// The file is there and holds different content.
+    Differs,
+    /// An earlier run wrote the file, and this run does not produce it.
+    Stale,
+}
+
 /// Report that `--check` found drift, and name the command that resolves it.
 ///
-/// The message states which of the two cases holds, because an absent file and a
-/// stale file need the reader to look at different things. Both have one remedy,
-/// which is a run with no `--check`.
-pub fn report_drift(path: &Path, absent: bool) {
-    if absent {
-        eprintln!(
-            "{} {} does not exist.",
-            "error:".red().bold(),
-            path.display().to_string().bold()
-        );
-    } else {
-        eprintln!(
-            "{} {} is out of date with the spec.",
-            "error:".red().bold(),
-            path.display().to_string().bold()
-        );
+/// The message states which of the three cases holds, because a missing file, a
+/// stale file, and a leftover file each need the reader to look at something
+/// different. All three have one remedy, which is a run with no `--check`.
+pub fn report_drift(path: &Path, kind: DriftKind) {
+    let path = path.display().to_string();
+    let name = path.bold();
+    match kind {
+        DriftKind::Absent => {
+            eprintln!("{} {name} does not exist.", "error:".red().bold());
+        }
+        DriftKind::Differs => {
+            eprintln!("{} {name} is out of date with the spec.", "error:".red().bold());
+        }
+        DriftKind::Stale => {
+            eprintln!("{} {name} is left over from an earlier run.", "error:".red().bold());
+        }
     }
     eprintln!(
         "  {} run the same command without `--check` to update it, and commit the result.",
@@ -242,6 +267,22 @@ fn hints_for(err: &Error) -> Vec<String> {
         Error::ReadOutput { path, .. } => {
             return vec![format!("Check that `{path}` is a readable file and not a directory.")];
         }
+        Error::UnownedOutput { path } => {
+            return vec![
+                format!("Move `{path}` out of the generated directory, or delete it."),
+                "The generator owns that directory and removes the files it no longer produces, so it never deletes a file it did not write.".to_owned(),
+            ];
+        }
+        Error::OutsideOutput { directory, .. } => {
+            return vec![format!(
+                "This is an internal bug in oapi-codegen. Every generated file belongs under `{directory}`."
+            )];
+        }
+        Error::UnsplittableOutput { path } => {
+            return vec![format!(
+                "Give the output path a `.rs` extension, for example `{path}.rs`."
+            )];
+        }
         Error::Unimplemented(_) => {
             return vec!["This generation mode is not supported yet.".to_owned()];
         }