feat(groq): A whimsical CLI that shuffles a list of locations into a random scavenger route with distances between stops.

[polsala]

Implementation Summary

• Utility: nightly-scavenger-route-planner
• Provider: groq
• Location: rust-utils/nightly-nightly-scavenger-route-plan-2
• Files Created: 4
• Description: A whimsical CLI that shuffles a list of locations into a random scavenger route with distances between stops.

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-scavenger-route-plan-2.
• 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-scavenger-route-plan-2/README.md
• Run tests located in rust-utils/nightly-nightly-scavenger-route-plan-2/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

🧱 Mocks/Fakes

• (pending)

✅ What’s solid

• Clear separation of concerns – generate_route is pure and testable, while main only handles I/O.
• Deterministic behaviour – the route is reproducible via a seed (StdRng::seed_from_u64), which is great for testing and debugging.
• Adequate test coverage for core logic – test_repeatability verifies that the same seed yields the same route and that distances stay within 1–10 km.
• Self‑contained crate – Cargo.toml lists only the necessary dependencies (rand) and a dev‑dependency for the same crate, keeping the build lightweight.
• User‑friendly README – installation, usage, and testing instructions are present, making it easy for newcomers to try the tool.

🧪 Tests

• Edge‑case coverage – add tests for:
  • Empty input (generate_route(vec![], 42) → []).
  • Single location (["Only"] → distance 0).
  • Duplicate locations (ensure shuffling still works).
• CLI integration test – spawn the binary with a sample argument and assert that the output matches the expected format.
• Error‑handling test – run the binary with no arguments or too many arguments and confirm it exits with status 1 and prints the usage message.
• Property‑based test – use proptest or quickcheck to generate random location lists and verify that all distances are in [1,10] and that the first distance is 0.

🔒 Security

• No secrets or external credentials are touched; the crate is safe to merge from a security standpoint.
• All code is safe; no unsafe blocks or raw pointers.
• The random seed is derived from thread_rng, which is cryptographically secure for non‑security‑critical use.

🧩 Docs/DX

Area	Current state	Suggested improvement
License	Missing	Add a permissive license (e.g., MIT) in the root.
Output format	Described in prose	Show a concrete example of the printed route in the README.
CLI flags	Only positional argument	Add a --seed <u64> flag for reproducibility and a --help flag

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Clear Separation of Concerns: The core logic for generating a route is encapsulated in the generate_route function, which is a pure function taking locations and a seed. The main function handles I/O and argument parsing, maintaining a clean architecture.
• Deterministic Generation: The generate_route function's reliance on a seed for its random number generator is a strong design choice, enabling reproducible routes for testing and potential future features (e.g., sharing a specific route).
• Self-Contained Utility: The utility is entirely self-contained within its new directory, including its Cargo.toml, README.md, source code, and tests, simplifying integration and management.
• Robust Randomness: Appropriate use of the rand crate for shuffling and generating distances within specified ranges.

🧪 Tests

• The test_repeatability test effectively validates the core generate_route function, ensuring determinism with a fixed seed and correct distance ranges (0 for the first stop, 1-10 for subsequent stops).
• Actionable feedback:
  • The current test suite focuses solely on the generate_route function. Consider adding integration tests for the main function to cover argument parsing, error handling (e.g., no arguments provided), and the overall CLI output format. This could involve capturing stdout and stderr or checking exit codes.
  • For integration tests, it's common practice to add the crate as a [dev-dependency] in Cargo.toml to allow use scavenger_route_planner::generate_route; instead of use super::super::generate_route;. This improves clarity and standardizes test setup.

🔒 Security

• The utility is isolated and does not interact with external systems, network resources, or sensitive files, minimizing its attack surface.
• No secrets or credentials are handled, stored, or exposed by the application.
• Argument parsing via std::env::args() is used in a straightforward manner, without complex parsing logic that might introduce vulnerabilities.
• The rand crate is used appropriately for its intended purpose (non-cryptographic randomness for a scavenger hunt), posing no security risks in this context.

🧩 Docs/DX

• The README.md provides clear and concise instructions for installation and usage, making it easy for users to get started.
• The generate_route function includes a comprehensive doc comment, explaining its purpose, parameters, and return value.
• The CLI provides a helpful usage message when incorrect arguments are supplied.
• Actionable feedback:
  • The directory path rust-utils/nightly-nightly-scavenger-route-plan-2 contains a redundant nightly- prefix. Aligning the directory name with the utility's name (e.g., rust-utils/scavenger-route-planner) would improve consistency and clarity.
  • The generate_route function currently clones the input locations vector. For potentially large inputs, consider accepting &[String] or consuming the Vec<String> if the original vector is not needed elsewhere to avoid unnecessary allocations.
  • The main function uses rand::thread_rng().gen::<u64>() to generate a random seed for each run. While this ensures variety, providing an optional CLI argument for users to specify a seed would allow for reproducible routes directly from the command line, aligning with the deterministic nature of generate_route.

    // Example of adding a seed argument
    // In main function:
    // let seed = if args.len() == 3 {
    //     args[2].parse::<u64>().expect("Seed must be a valid u64")
    // } else {
    //     rand::thread_rng().gen::<u64>()
    // };
    // Update usage message accordingly.

🧱 Mocks/Fakes

• The utility's design, particularly the generate_route function accepting a seed, inherently supports testability without the need for mocking external dependencies or complex state.
• No external services or complex components are introduced that would typically necessitate mocking. The PR body's statement "Not applicable; generator did not introduce new mocks" is accurate.

[polsala]

🤖 Review by OPENROUTER Agent

✅ What's solid

• Clean separation of logic and I/O: The generate_route function is pure and deterministic, handling the core algorithmic logic, while main deals solely with command-line parsing and output. This makes the business logic easy to test and reuse.
• Deterministic behavior via seeded RNG: Using StdRng::seed_from_u64 ensures that routes can be reproduced for consistent testing and debugging, which is excellent for reliability.
• Sensible CLI interface: The CLI accepts a comma-separated list of locations as a single argument, which is straightforward and aligns well with typical Unix-style tools.
• Good test coverage for core functionality: The included test verifies repeatability and checks basic constraints like initial distance being zero and subsequent distances falling within expected bounds.

🧪 Tests

• ✅ Basic repeatability is covered well.
• 🔧 Actionable suggestion: Add edge case tests such as:
  • Empty input list (should return an empty route).
  • Single-item list (should return one item with 0 distance).
  • Duplicate locations (ensure shuffle still behaves correctly).

Example addition:

#[test]
fn test_single_location() {
    let locations = vec!["Only Place".to_string()];
    let seed = 0;
    let route = generate_route(locations, seed);
    assert_eq!(route.len(), 1);
    assert_eq!(route[0].1, 0);
}

🔒 Security

• ⚠️ Input sanitization: While this tool currently assumes trusted input, it would benefit from trimming whitespace and rejecting overly long strings or invalid characters to prevent potential misuse in broader contexts.
• 🛡️ Actionable suggestion: Consider adding length limits or validation for inputs:

const MAX_LOCATION_LEN: usize = 100;

let locations: Vec<String> = input
    .split(',')
    .map(|s| s.trim().to_string())
    .filter(|s| !s.is_empty() && s.len() <= MAX_LOCATION_LEN)
    .collect();

🧩 Docs/DX

• ✅ Clear installation and usage instructions in the README.
• 📌 Actionable suggestions:
  • Add example output to help users visualize what the tool produces.
  • Mention how seeding works or could be overridden for reproducibility.
  • Clarify error messages in code — consider extracting them into constants or helper functions for clarity and reusability.

Improved error message snippet:

const USAGE_MSG: &str = "Usage: scavenger-route-planner \"loc1,loc2,loc3,...\"";

if args.len() != 2 {
    eprintln!("{}", USAGE_MSG);
    std::process::exit(1);
}

🧱 Mocks/Fakes

• Not applicable per author justification; no external dependencies requiring mocking were introduced. Future enhancements involving real-world APIs (e.g., geolocation services) should include proper abstraction layers and associated mocks.