test: prevent duplicated aliases from idiots (#365)

* fix(usage_md): detect and reject visible aliases that duplicate their own flag name

A visible_alias matching the argument's own --long name (or a
visible_short_alias matching its -short flag) is a coding mistake that
produces redundant output in USAGE.md. The new validation runs at the
start of render_usage_md() and exits with code 1 if any such
redundancy is found.

https://claude.ai/code/session_01TSnvxN1HBwwzhxfFShWAQ5

* refactor(usage_md): return custom error type instead of calling process::exit

Define a non-exhaustive `RenderUsageMdError` enum with
`derive_more::{Display, Error}` and make `render_usage_md` return
`Result<String, RenderUsageMdError>`. The callsites in cli/usage_md.rs
and tests/sync_usage_md.rs now handle the error appropriately.

https://claude.ai/code/session_01TSnvxN1HBwwzhxfFShWAQ5

* refactor(usage_md): address review feedback on error type and callsites

- Split RedundantVisibleAlias into RedundantVisibleLongAlias(String)
  and RedundantVisibleShortAlias(char), moving message into #[display]
- Rename validate_no_redundant_visible_aliases to check_visible_aliases
- Use if-let-Err pattern in cli/usage_md.rs to match lib.rs style
- Simplify test to use .unwrap() instead of .expect()
- Fix doc comment to use plain English instead of backtick-wrapped flags

https://claude.ai/code/session_01TSnvxN1HBwwzhxfFShWAQ5

* refactor(usage_md): rename to reject_redundant_aliases, use pipe-trait, revert to match

- Rename check_visible_aliases to reject_redundant_aliases
- Use pipe-trait to flatten nested constructor and Err calls
- Revert cli/usage_md.rs back to match pattern

https://claude.ai/code/session_01TSnvxN1HBwwzhxfFShWAQ5

* refactor(usage_md): return ExitCode instead of calling process::exit

https://claude.ai/code/session_01TSnvxN1HBwwzhxfFShWAQ5

* docs: improve error message

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

cli/usage_md.rs

@@ -1,5 +1,15 @@
 use parallel_disk_usage::usage_md::render_usage_md;
+use std::process::ExitCode;
 
-fn main() {
-    println!("{}", render_usage_md().trim_end());
+fn main() -> ExitCode {
+    match render_usage_md() {
+        Ok(content) => {
+            println!("{}", content.trim_end());
+            ExitCode::SUCCESS
+        }
+        Err(error) => {
+            eprintln!("error: {error}");
+            ExitCode::FAILURE
+        }
+    }
 }

src/usage_md.rs

@@ -1,12 +1,27 @@
 use crate::args::Args;
 use clap::builder::PossibleValue;
 use clap::{Arg, ArgAction, Command, CommandFactory};
+use derive_more::{Display, Error};
 use itertools::Itertools;
+use pipe_trait::Pipe;
 use std::borrow::Cow;
 
+/// Error produced when generating the usage Markdown.
+#[derive(Debug, Display, Error)]
+#[non_exhaustive]
+pub enum RenderUsageMdError {
+    /// A `visible_alias` duplicates the argument's own long flag name.
+    #[display("--{_0} has a visible_alias that duplicates its own flag name")]
+    RedundantVisibleLongAlias(#[error(not(source))] String),
+    /// A `visible_short_alias` duplicates the argument's own short flag name.
+    #[display("-{_0} has a visible_short_alias that duplicates its own flag name")]
+    RedundantVisibleShortAlias(#[error(not(source))] char),
+}
+
 /// Renders a Markdown reference page for `pdu`'s CLI.
-pub fn render_usage_md() -> String {
+pub fn render_usage_md() -> Result<String, RenderUsageMdError> {
     let mut command: Command = Args::command();
+    reject_redundant_aliases(&command)?;
     let mut out = String::new();
 
     let usage = command.render_usage().to_string();
@@ -59,7 +74,7 @@ pub fn render_usage_md() -> String {
         }
     }
 
-    out
+    Ok(out)
 }
 
 fn render_argument(out: &mut String, arg: &Arg) {
@@ -232,3 +247,35 @@ fn ensure_ends_with_punctuation(line: &str) -> Cow<'_, str> {
         Cow::Owned(format!("{line}."))
     }
 }
+
+/// Rejects any argument whose visible alias duplicates its own primary flag name.
+///
+/// A visible alias matching the argument's own long name, or a visible short alias
+/// matching its own short flag, is a coding mistake that produces redundant output in
+/// USAGE.md.
+fn reject_redundant_aliases(command: &Command) -> Result<(), RenderUsageMdError> {
+    for arg in command.get_arguments() {
+        if let Some(primary_long) = arg.get_long() {
+            for alias in arg.get_visible_aliases().unwrap_or_default() {
+                if alias == primary_long {
+                    return primary_long
+                        .to_owned()
+                        .pipe(RenderUsageMdError::RedundantVisibleLongAlias)
+                        .pipe(Err);
+                }
+            }
+        }
+
+        if let Some(primary_short) = arg.get_short() {
+            for alias in arg.get_visible_short_aliases().unwrap_or_default() {
+                if alias == primary_short {
+                    return primary_short
+                        .pipe(RenderUsageMdError::RedundantVisibleShortAlias)
+                        .pipe(Err);
+                }
+            }
+        }
+    }
+
+    Ok(())
+}

tests/sync_usage_md.rs

@@ -11,7 +11,9 @@ use parallel_disk_usage::usage_md::render_usage_md;
 
 #[test]
 fn usage_md() {
-    let actual = render_usage_md();
+    let actual = render_usage_md().unwrap_or_else(|error| {
+        panic!("failed to render usage markdown: {error}");
+    });
     let expected = include_str!("../USAGE.md");
     assert!(
         actual.trim_end() == expected.trim_end(),