feat(groq): Generates a whimsical ASCII map showing random placement of scavenged items for post‑apocalyptic adventures.

[polsala]

Implementation Summary

• Utility: nightly-scavenger-map
• Provider: groq
• Location: rust-utils/nightly-nightly-scavenger-map-3
• Files Created: 4
• Description: Generates a whimsical ASCII map showing random placement of scavenged items for post‑apocalyptic adventures.

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-map-3.
• 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-map-3/README.md
• Run tests located in rust-utils/nightly-nightly-scavenger-map-3/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 – the utility lives in its own crate (scavenger_map) under the nightly folder, so it won’t interfere with existing code.
• Deterministic output for testing – seeding StdRng with a constant (42) makes the map reproducible, which the integration test relies on.
• Simple, readable implementation – the generate_map and print_map functions are short, well‑named, and avoid unsafe code.
• README gives a quick‑start – the usage snippet (cargo run -- <items>) works out‑of‑the‑box for a new contributor.
• Basic test coverage – the integration test checks that the three supplied items appear on the map and that the dimensions are correct.

---

🧪 Tests

Observation	Recommendation
The test spawns a full cargo run process. This incurs a compile step on every test run and can be flaky if the working directory isn’t the crate root.	• Use the library functions directly (generate_map) instead of invoking the binary. • If you want to keep an end‑to‑end test, set current_dir to the crate folder and consider the assert_cmd crate for a more ergonomic API.
The test only verifies presence of the letters, not that they are placed uniquely or that the map respects the 100‑attempt limit.	Add a unit test for edge cases: ```rust\n#[test]\nfn map_fills_until_full() {\n let items = vec!["a".into(); 60]; // more than 510 cells\n let map = generate_map(&items, 1);\n // Count non‑dot cells – should be at most WIDTHHEIGHT\n let placed = map.iter().flatten().filter(
No test for empty input (no items) or duplicate first letters.	Add a test that calls generate_map(&[], seed) and asserts the map is all '.'. Also test that duplicate initials don’t overwrite each other (the algorithm already prevents overwriting, but a test makes the guarantee explicit).
The test description mentions “Mock rationale” even though no mock is used.	Remove or replace that comment – it adds noise and may confuse reviewers.

---

🔒 Security

• The crate only depends on rand = "0.8" and contains no unsafe code or external I/O beyond reading command‑line arguments, so the attack surface is minimal.
• Version pinning: rand = "0.8" uses a caret (^) by default, which will automatically pick newer patch releases. That’s fine, but consider adding a Cargo.lock in the crate (or a cargo vendor step in CI) to guarantee reproducible builds, especially for a utility that may be compiled on many machines.
• No secrets, environment variables, or file system writes are performed, so the utility is safe to run in CI or on user machines.

---

🧩 Docs / Developer Experience

Area	Suggested improvement
README	• Show a real example output with letters (e.g., W C M). • Explain that the map is deterministic because of a fixed seed, and how to change the seed for a “more random” experience (e.g., let seed = rand::random();).
Cargo.toml metadata	Add fields that improve discoverability and publishing: toml\n[package]\nname = \"scavenger_map\"\nversion = \"0.1.0\"\nedition = \"2021\"\nauthors = [\"Your Name <you@example.com>\"]\ndescription = \"Generate a whimsical ASCII scavenger‑item map\"\nlicense = \"MIT OR Apache-2.0\"\nrepository = \"https://github.com/yourorg/yourrepo\"\n
Installation tip	Mention that users can install the binary globally with cargo install --path . (or via cargo install scavenger_map once published).
CLI help	Consider adding a --help flag (e.g., using `std::env::args().any(
Testing instructions	In the README, point to the exact command to run the integration test (cargo test --test integration_test) and note that the test runs the binary, so it may take a few seconds.

---

🧱 Mocks / Fakes

• The PR correctly states that no new mocks were introduced.
• The only “mock‑like” comment appears in the integration test (// Mock rationale: …). Since the test does not actually mock anything, you can remove that comment to keep the test clean and focused.

---

Overall, the utility is a fun addition and the core implementation is solid. Tightening the test suite, enriching the README and Cargo.toml, and cleaning up the stray mock comment will make the crate more robust and easier for contributors to adopt.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Self-contained utility: The scavenger_map crate is isolated within its own directory, minimizing potential side effects on other parts of the codebase. This clear separation aids in maintainability and reduces integration risks.
• Deterministic testing: The use of a fixed seed (42u64) for the random number generator ensures that map generation is reproducible. This is a critical design choice that enables reliable and consistent integration testing.
• Clear and readable implementation: The generate_map and print_map functions are well-defined and easy to follow, contributing to the overall readability and maintainability of the code.
• Robust character handling: The logic item.chars().next().unwrap_or('?').to_ascii_uppercase() gracefully handles cases where an item name might be empty, preventing panics and ensuring a consistent single-character representation on the map.

🧪 Tests

• Enhanced integration test assertions: The current integration test verifies the presence of item characters and map dimensions. To make the test more robust against unintended layout changes, consider asserting the exact expected output string given the fixed seed. This would provide a stronger guarantee of deterministic behavior.

  // In tests/integration_test.rs
  #[test]
  fn test_map_output_fixed_seed_exact() {
      let output = std::process::Command::new("cargo")
          .args(&["run", "--quiet", "--", "water", "canned", "medkit"])
          .output()
          .expect("failed to execute cargo run");
      let stdout = std::str::from_utf8(&output.stdout).unwrap().trim();
  
      // This expected output needs to be generated by running the utility once
      // with the fixed seed and arguments, then copied here.
      let expected_output = "\
  

. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . W"; // Example, verify actual output
assert_eq!(stdout, expected_output, "Map output does not match expected for fixed seed.");
}
```

• Unit testing for generate_map: Extract the generate_map function into src/lib.rs and make it public. This would enable direct unit testing of the map generation logic without relying on std::process::Command, leading to faster and more granular tests.
• Edge case coverage: Add tests for scenarios where more items are provided than available map slots to ensure the !placed break condition is correctly handled and the output remains as expected (i.e., only a subset of items are placed).

🔒 Security

• Dependency review: While rand = "0.8" is a stable and widely used crate, it is good practice to periodically review all dependencies for known vulnerabilities, especially in utilities that might be integrated into larger systems.
• Input sanitization: The utility processes command-line arguments. Currently, these arguments are only used for character representation, posing minimal risk. However, if future features involve external command execution or file system interactions based on user input, ensure proper sanitization and validation are implemented to prevent potential injection vulnerabilities.

🧩 Docs/DX

• Update README example: The README.md currently shows an empty map in its example output. Update this to reflect an actual map with items placed, demonstrating the utility's core functionality more clearly to new users.
• Refine directory structure: The path rust-utils/nightly-nightly-scavenger-map-3/rust-utils/nightly-scavenger-map/ is redundant and verbose. Consider simplifying the directory structure to rust-utils/nightly-scavenger-map/ to improve navigability and reduce path complexity for developers.
• Enhance main.rs comments: Add comments to src/main.rs explaining the purpose of constants like WIDTH and HEIGHT, and clarify the item placement logic within generate_map, especially the for _ in 0..100 loop and the unwrap_or('?') fallback.
• Dynamic seeding for user experience: For a "whimsical" map generator, consider allowing the user to provide a seed via a command-line argument, or using a time-based seed by default (e.g., rand::thread_rng()) when not in a test environment. This would provide varied output for users while retaining deterministic testing capabilities.

🧱 Mocks/Fakes

• Explicit Rng passing: The current approach of seeding StdRng directly within generate_map is effective for deterministic testing. If generate_map were made public (e.g., in src/lib.rs), consider passing the Rng trait object as an argument (e.g., rng: &mut impl Rng). This pattern allows for easier injection of different random number generators (e.g., StdRng for tests, thread_rng for production) without modifying the function's internal logic, enhancing testability and flexibility.

  // In src/lib.rs (if generate_map is moved)
  use rand::Rng;
  
  pub fn generate_map<R: Rng>(items: &[String], rng: &mut R) -> Vec<Vec<char>> {
      let mut map = vec![vec!['.'; WIDTH]; HEIGHT];
      for item in items {
          let mut placed = false;
          for _ in 0..100 {
              let x = rng.gen_range(0..WIDTH);
              let y = rng.gen_range(0..HEIGHT);
              if map[y][x] == '.' {
                  map[y][x] = item.chars().next().unwrap_or('?').to_ascii_uppercase();
                  placed = true;
                  break;
              }
          }
          if !placed {
              break;
          }
      }
      map
  }