feat(groq): Generates a random ASCII scavenger map for post‑apocalyptic tabletop sessions

[polsala]

Implementation Summary

• Utility: nightly-scavenger-map
• Provider: groq
• Location: rust-utils/nightly-nightly-scavenger-map-3
• Files Created: 4
• Description: Generates a random ASCII scavenger map for post‑apocalyptic tabletop sessions

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

• Isolation & Scope – The new utility lives in its own rust-utils/nightly‑nightly‑scavenger‑map‑3 folder, so it won’t interfere with existing crates.
• CLI ergonomics – clap::Parser with #[command(author, version, about = …)] gives a nice --help out‑of‑the‑box.
• Deterministic seeding – Accepting an optional --seed makes the map reproducible, which is great for testing and for game masters who want a fixed map.
• Randomness – Using StdRng (seedable, cryptographically‑secure) is a solid choice for a utility that isn’t performance‑critical.
• Integration test – The test launches the compiled binary and validates that the output respects the requested dimensions and only contains the allowed symbols.
• Cargo manifest – Minimal but complete: clap and rand are declared, and a dev-dependencies section is present for testing.

---

🧪 Tests

Observation	Recommendation
The integration test uses std::process::Command directly while assert_cmd is listed as a dev‑dependency.	Switch to assert_cmd for a more expressive API and to make the assert_cmd dependency actually useful. Example: rust\nuse assert_cmd::Command;\n\n#[test]\nfn map_dimensions_and_symbols() {\n Command::cargo_bin(\"scavenger_map\")\n .unwrap()\n .args(&[\"--width\", \"3\", \"--height\", \"2\", \"--seed\", \"123\"])\n .assert()\n .success()\n .stdout(predicates::str::is_match(r\"^[\\.FWM T]{3}\\n[\\.FWM T]{3}$\").unwrap());\n}\n
Only dimensions & symbol set are verified. No guarantee that a given seed always yields the same map.	Add a deterministic‑output test that compares the exact string for a known seed. Example: rust\n#[test]\nfn deterministic_output() {\n let expected = \"F.W\\n..M\"; // whatever the generator produces for seed 42, 3×2\n Command::cargo_bin(\"scavenger_map\")\n .unwrap()\n .args(&[\"--width\", \"3\", \"--height\", \"2\", \"--seed\", \"42\"])\n .assert()\n .success()\n .stdout(predicates::str::similar(expected));\n}\n
No unit tests for the core generate_map function.	Expose generate_map (e.g., pub(crate) fn generate_map…) and write a quick unit test that checks the 20 % resource density and that the symbols are drawn from the allowed set.
dev-dependencies include predicates but it isn’t used in the current test.	Either use predicates as shown above or remove it from Cargo.toml to keep the manifest tidy.

---

🔒 Security

• Input validation – width and height default to positive numbers, but a user could explicitly pass 0. This would allocate a zero‑sized vector and the program would silently output nothing. Add a simple validation step:
  rust\nif args.width == 0 || args.height == 0 {\n eprintln!(\"width and height must be > 0\");\n std::process::exit(1);\n}\n |
• Randomness source – StdRng::from_entropy() is appropriate; no need for additional entropy handling.
• No external secrets – The crate does not read files, environment variables, or network resources, so the attack surface is minimal.

---

🧩 Docs / Developer Experience

Area	Feedback
README formatting	The diff shows raw \n literals; ensure the file contains real line breaks. A clean Markdown file improves readability.
Example output	Include a concrete, deterministic example (e.g., the exact map produced with --seed 42). This helps users verify they’re running the right version.
CLI constraints	Document that width and height must be greater than zero, and explain the 20 % resource density rule.
Cargo metadata	Adding a short description field in Cargo.toml makes the crate discoverable on crates.io (even if it stays internal).
Help text	clap automatically generates help, but you can enrich it with #[arg(help = "…")] for each flag, making --help self‑explanatory.
Contribution guidelines	Since this is a generated utility, a brief note on how to regenerate or modify it (e.g., “run the Groq prompt again”) would be useful for future maintainers.

---

🧱 Mocks / Fakes

• The current test suite does not require any external services, so mocks aren’t needed.
• If you later add features that depend on external data (e.g., loading a resource‑distribution file), consider using a fake file system or in‑memory RNG to keep tests deterministic.

---

Overall impression: The utility is well‑scoped, functional, and comes with a basic integration test. Tightening the test suite, adding a small amount of input validation, and polishing the README will make the crate production‑ready and easier for other developers (or future you) to adopt and extend.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Isolation & Scope: The new utility is well-contained within its own directory (rust-utils/nightly-nightly-scavenger-map-3), preventing any unintended side effects on existing project components.
• CLI Ergonomics: The use of clap::Parser with #[command(author, version, about = …)] provides a user-friendly command-line interface with automatic --help output, which is excellent for discoverability.
• Deterministic Seeding: The inclusion of an optional --seed argument is a strong feature, enabling reproducible map generation for testing and consistent gameplay scenarios.

🧪 Tests

• Test Coverage: The existing integration test map_dimensions_and_symbols is a good start, verifying basic output dimensions and character set.
• Expand Test Cases: Consider adding more specific tests to cover edge cases and different configurations:
  • Zero Dimensions: Test how the utility handles width=0 or height=0.
  • Large Dimensions: Test with significantly larger width and height values to ensure performance and correctness.
  • Seed Variation: Test with a variety of seeds to ensure the randomness is distributed as expected.
  • Resource Distribution: While the current test checks for allowed characters, it doesn't verify the distribution of resources. A more advanced test could check if the approximate percentage of resources (20% as per the code) is maintained over several runs with different seeds.
  • Empty Map: Test a scenario where no resources are placed (e.g., very small dimensions or a seed that coincidentally results in no resource placement).

🔒 Security

• No Secrets Touched: The PR correctly identifies that no secrets or credentials are being accessed or modified, which is a fundamental security consideration.
• Dependency Analysis: While the dependencies (clap, rand) are standard and generally considered safe, it's always good practice to be aware of their security track records. For this utility, the risk is minimal.

🧩 Docs/DX

• Clear README: The README.md provides a concise explanation of the utility's purpose, usage instructions, and an example, which is great for immediate understanding.
• Usage Examples: The example in the README is helpful for users to quickly grasp how to run the command.
• Code Comments: The code includes a comment explaining the purpose of the count variable and the resource symbols, which aids readability.
• Consider Adding More Examples:
  • Include examples for different seed values to demonstrate determinism.
  • Show how to pipe the output to other commands if applicable.
• Doc Tests: While not strictly necessary for this simple utility, consider adding doc tests to the generate_map function if it were to become more complex, to ensure examples in documentation remain accurate.

🧱 Mocks/Fakes

• No New Mocks Introduced: The PR correctly states that no new mocks or fakes were introduced by this generator, which simplifies the review process.
• Test Mocking Strategy: The integration test uses std::process::Command to execute the binary. This is a valid approach for testing CLI tools, effectively treating the binary as an external dependency that is being "mocked" by its own execution. This is a common and effective pattern for testing command-line applications.