feat(groq): Suggests a whimsical ramen recipe based on current system load, turning performance monitoring into a culinary adventure.

[polsala]

Implementation Summary

• Utility: nightly-ramen-recipe-suggester
• Provider: groq
• Location: bash-utils/nightly-nightly-ramen-recipe-suggest
• Files Created: 3
• Description: Suggests a whimsical ramen recipe based on current system load, turning performance monitoring into a culinary adventure.

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 bash-utils/nightly-nightly-ramen-recipe-suggest.
• 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 bash-utils/nightly-nightly-ramen-recipe-suggest/README.md
• Run tests located in bash-utils/nightly-nightly-ramen-recipe-suggest/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 purpose & fun UX – The script turns a mundane metric (load average) into a whimsical ramen suggestion, which is a delightful addition to the bash-utils collection.
• Self‑contained implementation – All logic lives in a single script with no external dependencies beyond bc and Bash 4+, making it easy to drop into any Linux box.
• Graceful fallback – When /proc/loadavg is missing the script prints a helpful error and exits with a non‑zero status.
• Readable code – Functions are short, variables are well‑named, and associative arrays make the mapping between spice level and recipe explicit.
• Documentation – The README explains the utility, usage, requirements, and how to run the test suite, which is exactly what a new contributor needs.

🧪 Tests

• Positive coverage – The test suite verifies that the three load‑range thresholds (<0.5, <1.5, ≥1.5) map to the expected spice levels.
• Actionable improvements
  • Add edge‑case tests – Verify behavior at the exact threshold values (0.5 and 1.5) to ensure the comparison logic matches the intended categorisation.

    output=$(run "0.5")
    [[ "$output" == *"Medium"* ]] || { echo "FAIL: 0.5 should be Medium"; exit 1; }

  • Invalid input handling – Test that non‑numeric or negative values cause a clean error message and a non‑zero exit code.

    set +e   # allow script to exit with error
    output=$(run "foo" 2>&1)
    rc=$?
    [[ $rc -ne 0 && "$output" == *"Invalid load value"* ]] || { echo "FAIL: bad input not rejected"; exit 1; }

  • Missing bc – Simulate an environment without bc (e.g., by temporarily renaming it) and assert that the script fails with a clear message. This protects against a hidden runtime dependency.
  • Test output format – Instead of only checking for the level keyword, assert that the three expected lines (Current load, Suggested ramen level, Recipe) appear in order. This guards against accidental output changes that could break downstream tooling.

🔒 Security

• Input validation – The script already checks that the supplied argument matches a simple decimal regex. Consider tightening it:
  • Disallow negative numbers (- sign) and leading dots (.5) if those aren’t meaningful for load averages.
  • Use Bash’s built‑in arithmetic comparison for integer parts to avoid relying on external bc for validation.

    if (( $(printf "%.0f" "$raw_load") < 0 )); then
      echo "Invalid load value: $raw_load" >&2
      exit 1
    fi

• Dependency safety – bc is a standard utility, but it’s still an external binary. Add a runtime check with a helpful fallback:

  command -v bc >/dev/null || { echo "bc is required but not installed" >&2; exit 127; }

• Shebang & permissions – The script uses #!/usr/bin/env bash, which is portable. Ensure the file is marked executable (chmod +x) in the repository’s .gitattributes or CI step, so users can run it without extra steps.

🧩 Docs/DX

• Threshold documentation – Explicitly list the numeric boundaries in the README (e.g., “Load < 0.5 → Mild, 0.5 ≤ Load < 1.5 → Medium, Load ≥ 1.5 → Spicy”). This helps users understand the mapping without reading the code.
• Exit‑code table – Document the script’s exit codes (e.g., 0 = success, 1 = invalid input, 127 = missing dependency). This is useful for automation.
• Cross‑platform note – Mention that the script only works on Linux systems exposing /proc/loadavg. For macOS or BSD, suggest using sysctl -n vm.loadavg or similar.
• Example output – Include a full sample run (all three lines) in the README to set expectations for formatting.
• Contribution guide – Add a short “How to add a new spice level” section, showing how to extend the associative array and adjust thresholds. This lowers the barrier for future enhancements.

🧱 Mocks/Fakes

• No mocks required – The utility is pure Bash and reads either a supplied argument or /proc/loadavg. The current test strategy of passing explicit values sidesteps the need for filesystem mocks.
• Potential future mock – If you ever decide to test the default (no‑argument) path, consider injecting a temporary /proc/loadavg via a bind‑mount in a container or using a wrapper function that can be overridden in tests. This would keep the test suite deterministic on CI runners with varying system loads.

---

Overall, the implementation is clean, the documentation is solid, and the test suite provides a good baseline. Adding the edge‑case and error‑handling tests, tightening input validation, and expanding the README with thresholds and exit‑code information will make the utility more robust and easier for contributors to extend. Great work!

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Clear and Engaging Concept: The script's premise of linking system load to ramen spiciness is creative and provides a unique, fun way to monitor system health. It aligns well with the "whimsical" description in the PR title.
• Self-Contained and Minimal Dependencies: The implementation is a single Bash script with only bc and Bash 4+ as external requirements, making it highly portable and easy to integrate into various environments.
• Robust Load Average Handling: The get_load function correctly prioritizes a provided argument for testing and gracefully falls back to reading /proc/loadavg, with an appropriate error message if the file is missing.
• Clear Documentation: The README.md is comprehensive, detailing the script's purpose, usage, requirements, and testing instructions, which significantly improves the developer experience.

🧪 Tests

• Boundary Condition Testing: The current tests cover low, medium, and high load values. Consider adding test cases for the exact boundary conditions (0.5 and 1.5) to ensure the transitions between "Mild", "Medium", and "Spicy" are precise.

  # Test load at lower boundary of Medium
  output=$(run "0.5")
  if [[ "$output" != *"Medium"* ]]; then
    echo "FAIL: Expected Medium for load 0.5 (boundary)"
    exit 1
  fi
  
  # Test load at lower boundary of Spicy
  output=$(run "1.5")
  if [[ "$output" != *"Spicy"* ]]; then
    echo "FAIL: Expected Spicy for load 1.5 (boundary)"
    exit 1
  fi

• Invalid Input Handling: Add a test case to verify the script's behavior when an invalid (non-numeric) load value is provided as an argument. The script currently handles this with an exit 1, which is good, but a test would confirm this behavior.

  # Test invalid input
  if ! output=$(run "invalid_load" 2>&1); then
    if [[ "$output" != *"Invalid load value"* ]]; then
      echo "FAIL: Expected error for invalid load 'invalid_load'"
      exit 1
    fi
  else
    echo "FAIL: Script did not exit with error for invalid load 'invalid_load'"
    exit 1
  fi

• Dependency Check: While bc is a common utility, the script relies on it for floating-point comparisons. A test could simulate bc being unavailable (e.g., by temporarily removing it from PATH) to ensure the script fails gracefully with an informative error, rather than a cryptic command not found from bc.

🔒 Security

• Input Sanitization: The script uses awk '{print $1}' /proc/loadavg which is generally safe for reading system files. The explicit numeric validation if ! [[ "$raw_load" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then is a strong safeguard against injection if the load value were to come from an untrusted source. This is well-handled.
• External Command Execution: The script executes bc. While bc itself is not typically a vector for command injection, ensuring that the input passed to bc is strictly numeric (as is done here) prevents any potential for unexpected behavior if bc were to interpret malicious input.
• Path Handling: The script uses #!/usr/bin/env bash and relies on bc being in the system's PATH. This is standard practice, but in highly sensitive environments, specifying full paths to executables (/usr/bin/bc) can sometimes be preferred to mitigate PATH-related vulnerabilities.

🧩 Docs/DX

• Consistent Naming: The directory is named nightly-nightly-ramen-recipe-suggest, which has a redundant "nightly". Consider renaming the directory to nightly-ramen-recipe-suggester for consistency with the utility name and to avoid repetition.
• Shebang in Tests: The test script test_ramensuggester.sh also uses #!/usr/bin/env bash. While correct, it's good practice to explicitly mention bash in the README.md's testing section if the test runner itself has specific shell requirements, similar to how bash tests/test_ramensuggester.sh is already shown.
• Error Message Clarity: The error message "Cannot determine load average (no /proc/loadavg)." is clear. For the "Invalid load value" error, it might be slightly more helpful to suggest the expected format, e.g., "Invalid load value: $raw_load. Expected a numeric value (e.g., 0.73)."

🧱 Mocks/Fakes

• Simulating /proc/loadavg Absence: The get_load function handles the absence of /proc/loadavg. While the current test suite doesn't explicitly test this path, a mock could be introduced to simulate this scenario. This would involve creating a temporary environment where /proc/loadavg does not exist or is inaccessible, then verifying the script's exit code and error output.

  # Example of how a mock might be used in a test setup:
  # # Temporarily move /proc/loadavg or use a fake /proc
  # # (requires elevated permissions or a controlled test environment)
  # if [[ -f /proc/loadavg ]]; then
  #   sudo mv /proc/loadavg /tmp/loadavg_backup
  # fi
  # output=$(./src/ramen_suggester.sh 2>&1 || true)
  # if [[ "$output" != *"Cannot determine load average"* ]]; then
  #   echo "FAIL: Expected error for missing /proc/loadavg"
  #   exit 1
  # fi
  # # Restore /proc/loadavg
  # if [[ -f /tmp/loadavg_backup ]]; then
  #   sudo mv /tmp/loadavg_backup /proc/loadavg
  # fi

  This would confirm the robustness of the get_load function's error handling for its default behavior.
• Mocking bc: As mentioned in the "Tests" section, mocking bc could be useful to test the script's behavior when this dependency is missing. This could be achieved by manipulating the PATH variable within a test function to point to a directory containing a dummy bc script that either fails or prints an error, allowing for controlled testing of dependency failures.