feat(cli): parse arguments with clap

The binary now derives command-line parsing from clap instead of maintaining a
custom parser. SEARCH_LIMIT remains an optional positional argument and keeps
its default of 1_000_000_000, while clap now owns usage errors, --help, and
--version output.

The parser stores the limit as NonZeroU64 so zero is rejected before the search
starts. The existing CLI parsing tests now exercise clap directly, and the
README documents the generated help/version flags plus the top-level program
structure.

Test Plan:
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo test
- cargo run -- --help

Trailer:
Refs: local request to replace custom argument parsing with clap
Dependencies: none

src/main.rs

@@ -1,8 +1,17 @@
-use std::{env, process, time::Instant};
+use std::{num::NonZeroU64, time::Instant};
+
+use clap::Parser;
 
 const DEFAULT_SEARCH_LIMIT: u64 = 1_000_000_000;
 const FIRST_PRIMES: &[u64] = &[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31];
 
+#[derive(Debug, Parser)]
+#[command(version, about = "Find highly composite numbers up to a search limit")]
+struct Cli {
+    #[arg(value_name = "SEARCH_LIMIT", default_value_t = NonZeroU64::new(DEFAULT_SEARCH_LIMIT).expect("default search limit is non-zero"))]
+    search_limit: NonZeroU64,
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 struct Candidate {
     nr: u64,
@@ -108,33 +117,8 @@ fn hcn_records(limit: u64) -> Vec<Candidate> {
     records
 }
 
-fn parse_search_limit(args: &[String]) -> Result<u64, String> {
-    let program = args.first().map_or("hcn", String::as_str);
-
-    match args.len() {
-        0 | 1 => Ok(DEFAULT_SEARCH_LIMIT),
-        2 => {
-            let raw_limit = &args[1];
-            let limit = raw_limit
-                .parse::<u64>()
-                .map_err(|err| format!("invalid search limit {raw_limit:?}: {err}"))?;
-
-            if limit == 0 {
-                return Err("search limit must be greater than zero".to_owned());
-            }
-
-            Ok(limit)
-        }
-        _ => Err(format!("usage: {program} [SEARCH_LIMIT]")),
-    }
-}
-
 fn main() {
-    let args = env::args().collect::<Vec<_>>();
-    let search_limit = parse_search_limit(&args).unwrap_or_else(|err| {
-        eprintln!("{err}");
-        process::exit(2);
-    });
+    let search_limit = Cli::parse().search_limit.get();
 
     let start = Instant::now();
     let records = hcn_records(search_limit);
@@ -146,7 +130,9 @@ fn main() {
 
 #[cfg(test)]
 mod tests {
-    use super::{Candidate, DEFAULT_SEARCH_LIMIT, hcn_records, max_exponent, parse_search_limit};
+    use clap::Parser;
+
+    use super::{Candidate, Cli, DEFAULT_SEARCH_LIMIT, hcn_records, max_exponent};
 
     fn count_divisors(mut nr: u64) -> u64 {
         let mut divisor_count = 1;
@@ -264,25 +250,29 @@ mod tests {
     #[test]
     fn parses_default_search_limit_without_arg() {
         assert_eq!(
-            parse_search_limit(&["hcn".to_owned()]),
-            Ok(DEFAULT_SEARCH_LIMIT)
+            Cli::try_parse_from(["hcn"])
+                .expect("CLI should parse without an explicit search limit")
+                .search_limit
+                .get(),
+            DEFAULT_SEARCH_LIMIT
         );
     }
 
     #[test]
     fn parses_search_limit_arg() {
         assert_eq!(
-            parse_search_limit(&["hcn".to_owned(), "42000".to_owned()]),
-            Ok(42_000)
+            Cli::try_parse_from(["hcn", "42000"])
+                .expect("CLI should parse an explicit search limit")
+                .search_limit
+                .get(),
+            42_000
         );
     }
 
     #[test]
     fn rejects_invalid_search_limit_arg() {
-        assert!(parse_search_limit(&["hcn".to_owned(), "nope".to_owned()]).is_err());
-        assert!(parse_search_limit(&["hcn".to_owned(), "0".to_owned()]).is_err());
-        assert!(
-            parse_search_limit(&["hcn".to_owned(), "100".to_owned(), "200".to_owned()]).is_err()
-        );
+        assert!(Cli::try_parse_from(["hcn", "nope"]).is_err());
+        assert!(Cli::try_parse_from(["hcn", "0"]).is_err());
+        assert!(Cli::try_parse_from(["hcn", "100", "200"]).is_err());
     }
 }