feat(groq): A whimsical CLI tool that estimates remaining device battery life based on capacity, draw, and efficiency.

[polsala]

Implementation Summary

• Utility: nightly-battery-life-estimator
• Provider: groq
• Location: rust-utils/nightly-nightly-battery-life-estimat
• Files Created: 5
• Description: A whimsical CLI tool that estimates remaining device battery life based on capacity, draw, and efficiency.

Rationale

• Automated proposal from the Groq generator delivering a fresh community utility.
• This utility was generated using the groq AI provider.

Why safe to merge

• Utility is isolated to rust-utils/nightly-nightly-battery-life-estimat.
• README + tests ship together (see folder contents).
• No secrets or credentials touched.
• All changes are additive and self-contained.

Test Plan

• Follow the instructions in the generated README at rust-utils/nightly-nightly-battery-life-estimat/README.md
• Run tests located in rust-utils/nightly-nightly-battery-life-estimat/tests/

Links

• Generated docs and examples committed alongside this change.

Mock Justification

• Not applicable; generator did not introduce new mocks.

[polsala]

🤖 Review by GROQ Agent

✅ What's solid

• Clear separation of concerns – the core estimation logic lives in src/lib.rs while the CLI lives in src/main.rs. This makes the library reusable from other crates or tests.
• Simple, well‑documented API – the estimate_hours function has a concise doc‑comment that explains each parameter and the special‑case return value (∞ when draw is zero).
• Zero‑draw handling – returning f64::INFINITY is a sensible way to signal “no consumption” without panicking.
• Minimal dependency footprint – the crate compiles with only the Rust standard library, which keeps the binary small and reduces attack surface.
• README provides quick start – the usage snippet, build, and test commands are all present, making it easy for a newcomer to try the tool.

---

🧪 Tests

• Coverage of core logic – the two unit tests in tests/test_main.rs verify the normal calculation and the zero‑draw edge case.
• Opportunities for improvement
  • Boundary validation – add tests for negative or out‑of‑range inputs (e.g., negative capacity, draw, or efficiency > 1.0) to ensure the library behaves predictably.
  • CLI integration test – consider an integration test that spawns the binary with various argument combinations and checks the stdout/stderr. Example using assert_cmd (add as a dev‑dependency):

    #[test]
    fn cli_basic() {
        use assert_cmd::Command;
        let mut cmd = Command::cargo_bin("battery-life-estimator").unwrap();
        cmd.arg("2500").arg("500")
            .assert()
            .success()
            .stdout(predicates::str::contains("4.50"));
    }

  • Floating‑point tolerance – the current test uses 1e-6; documenting the tolerance in a comment clarifies intent for future contributors.

---

🔒 Security

• Input parsing – the CLI uses parse().unwrap_or_else which exits with a generic error message. While this avoids a panic, it still accepts any string that can be parsed to f64. Consider:
  • Range checks for capacity, draw, and efficiency (e.g., capacity > 0, draw ≥ 0, efficiency ∈ (0, 1]). Rejecting nonsensical values early prevents downstream misuse.
  • Explicit error codes – returning distinct exit codes for “invalid argument count”, “invalid number format”, and “out‑of‑range value” can aid automation and security tooling.
• No external I/O – the crate does not read files, network resources, or environment variables beyond args, so the attack surface is minimal.
• Future‑proofing – if additional features (e.g., reading a config file) are added, remember to sanitize file paths and avoid directory traversal.

---

🧩 Docs / Developer Experience

• README enhancements
  • Add a “Parameters” table that explicitly lists the accepted ranges and default values.
  • Show an example with the optional efficiency argument to illustrate its effect.
  • Include a badge for CI status (once a CI pipeline is set up) to signal health.
• Cargo metadata
  • Populate Cargo.toml with description, license, repository, and keywords fields. This improves discoverability on crates.io and helps downstream users.
• Error messages
  • The usage helper prints to stderr, which is good. Consider making the messages a bit more user‑friendly, e.g.:

    eprintln!("Error: capacity must be a positive number (got `{}`)", args[1]);

• Clap / StructOpt
  • Switching to a command‑line argument parser (e.g., clap = { version = "4", features = ["derive"] }) would automatically generate help text, enforce required arguments, and provide built‑in validation. This reduces boilerplate and improves DX.

---

🧱 Mocks / Fakes

• Not applicable – the current implementation does not depend on external services or complex subsystems, so mocks are unnecessary.
• Potential future need – if the estimator later incorporates real‑time battery telemetry (e.g., via a system API), introduce a trait like BatteryReader and provide a mock implementation for unit tests. This will keep the core logic testable without hardware access.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Clear Separation of Concerns: The core estimation logic is well-encapsulated in src/lib.rs, making it reusable and independently testable. The CLI implementation in src/main.rs focuses solely on argument parsing and output.
• Robust Core Logic: The estimate_hours function correctly handles the edge case of zero or negative current draw by returning f64::INFINITY, which is then gracefully presented to the user in the CLI.
• Comprehensive README: The README.md provides clear instructions for usage, building, and testing, which is excellent for a new utility.
• User-Friendly Output: The CLI output for infinite battery life (∞ hours (no draw)) is intuitive and helpful.

🧪 Tests

• Core Logic Coverage: The test_main.rs file includes tests for the estimate_hours function, covering a basic calculation and the zero-draw edge case.

• Missing CLI Tests: The current test suite does not cover the main.rs functionality. This leaves argument parsing, error handling for invalid inputs, and output formatting untested.

  • Consider adding integration tests for the CLI using std::process::Command to verify argument parsing, error messages for invalid inputs (e.g., non-numeric values, incorrect number of arguments), and correct output formatting.

  #[test]
  fn test_cli_invalid_capacity() {
      let output = Command::new(env!("CARGO_BIN_EXE_battery-life-estimator"))
          .arg("invalid")
          .arg("500")
          .output()
          .expect("Failed to execute command");
      assert!(!output.status.success());
      assert!(String::from_utf8_lossy(&output.stderr).contains("Invalid capacity"));
  }
  
  #[test]
  fn test_cli_too_few_args() {
      let output = Command::new(env!("CARGO_BIN_EXE_battery-life-estimator"))
          .arg("2500")
          .output()
          .expect("Failed to execute command");
      assert!(!output.status.success());
      assert!(String::from_utf8_lossy(&output.stderr).contains("Usage:"));
  }

🔒 Security

• No External Dependencies: The utility relies only on the Rust standard library, minimizing the supply chain attack surface.
• Self-Contained and Isolated: The utility is isolated within its directory and does not interact with other parts of the codebase or external systems, reducing potential side effects.
• Input Handling: The use of parse().unwrap_or_else() for argument conversion ensures that the program exits gracefully on invalid numeric inputs rather than panicking, which is a good practice for CLI tools. No direct code injection vectors are apparent given the numeric input requirements.

🧩 Docs/DX

• Inconsistent Naming/Path: The directory path rust-utils/nightly-nightly-battery-life-estimat contains a redundant nightly-nightly segment, which is inconsistent with the Cargo.toml package name (battery-life-estimator) and the README.md title.

• Manual Argument Parsing: The main.rs uses manual std::env::args() parsing. For even slightly more complex CLIs, this approach can become verbose and error-prone.

  • Consider leveraging a dedicated CLI argument parsing crate like clap (or its derive features) for more robust, maintainable, and user-friendly argument handling, including automatic help generation, validation, and clearer error messages. This would significantly improve the developer experience for future enhancements.

  // Example with clap
  // Add `clap = { version = "4.0", features = ["derive"] }` to Cargo.toml
  use clap::Parser;
  
  #[derive(Parser, Debug)]
  #[command(author, version, about = "A whimsical CLI tool for post‑apocalyptic survivors to estimate how many hours their device will survive on the remaining battery.", long_about = None)]
  struct Args {
      /// Current battery capacity in milliamp-hours.
      capacity_mAh: f64,
      /// Average current draw in milliamps.
      draw_mA: f64,
      /// Efficiency factor (0.0-1.0), default 0.9.
      #[arg(default_value_t = 0.9)]
      efficiency: f64,
  }
  
  fn main() {
      let args = Args::parse();
      // ... use args.capacity_mAh, args.draw_mA, args.efficiency
  }

• Generic Error Messages: The error messages for invalid arguments (Invalid capacity, Invalid draw, Invalid efficiency) are somewhat generic.

  • Enhancing these messages to specify which argument was invalid and why (e.g., "Invalid capacity value provided: 'abc'. Expected a number.") could improve user experience. A crate like clap often provides this out-of-the-box.

🧱 Mocks/Fakes

• Not Applicable: As stated in the PR body, this utility does not introduce complex external dependencies or services that would necessitate mocks or fakes for testing. The estimate_hours function is a pure function, making it directly testable without such constructs.