feat(groq): CLI that prints the moon phase for a given date as a Unicode emoji.

[polsala]

Implementation Summary

• Utility: nightly-moon-phase-emoji
• Provider: groq
• Location: typescript-utils/nightly-nightly-moon-phase-emoji
• Files Created: 3
• Description: CLI that prints the moon phase for a given date as a Unicode emoji.

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 typescript-utils/nightly-nightly-moon-phase-emoji.
• 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 typescript-utils/nightly-nightly-moon-phase-emoji/README.md
• Run tests located in typescript-utils/nightly-nightly-moon-phase-emoji/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

• Self‑contained utility – All source, tests, and documentation live under a single folder, making the feature easy to locate and reason about.
• Clear algorithmic intent – The moonPhaseIndex function documents the reference new‑moon date and the synodic month length, which is helpful for future maintainers.
• CLI entry point – The require.main === module guard cleanly separates library usage from command‑line execution.
• Zero‑dependency design – The implementation only relies on Node’s built‑in process and Date, keeping the package lightweight.
• Readable mapping – The emojiMap array is ordered and commented, so the relationship between index and emoji is obvious at a glance.

🧪 Tests

• Positive coverage – The test suite checks four well‑known lunar phases, giving confidence that the core mapping works for typical dates.
• Actionable improvements
  • Add edge‑case tests – Verify dates that sit near the rounding boundaries (e.g., just before/after a phase change) to ensure Math.round behaves as expected.

    // Example edge test
    const justBefore = new Date("2023-01-20T23:59:59Z"); // should still be 🌔
    const justAfter  = new Date("2023-01-21T00:00:01Z"); // should be 🌕

  • Test pre‑reference dates – The algorithm should also work for dates before the 2000‑01‑06 reference; add a test such as 1999-12-31 to confirm correct handling of negative daysSince.
  • Validate CLI error path – Include a test that spawns the CLI with an invalid date string and asserts that the process exits with code 1 and prints the expected error message.
  • Make test runner explicit – The repository currently lacks a package.json with a "test" script. Adding one (e.g., "test": "mocha -r ts-node/register tests/**/*.ts") will make npm test functional out‑of‑the‑box.

🔒 Security

• Input validation – The CLI already checks isNaN(parsed.getTime()) and exits on failure, which is sufficient for this low‑risk utility.
• Potential improvement – When printing the emoji, consider using process.stdout.write instead of console.log to avoid an extra newline if downstream tooling expects a single character.
• No external secrets – The code does not read environment variables or network resources, so there are no obvious attack surfaces.

🧩 Docs/DX

• README typos & path consistency
  • The installation snippet references utils/typescript-utils/nightly-moon-phase-emoji, but the actual path is typescript-utils/nightly-nightly-moon-phase-emoji. Align the documentation with the real folder name.
  • The heading # nightly-moon-phase-emoji\n\nA tiny TypeScript… contains an escaped newline; clean it up for proper Markdown rendering.
• Add usage examples for compiled output – Show both ts-node and the compiled dist/main.js paths consistently (e.g., node ./dist/main.js).
• Provide a shebang – Adding #!/usr/bin/env node at the top of src/main.ts (and compiling it) enables direct execution after chmod +x.
• Package metadata – Even though this is a utility folder, a minimal package.json (name, version, bin field) would let users install it globally with npm i -g. Example:

  {
    "name": "nightly-moon-phase-emoji",
    "version": "0.1.0",
    "main": "dist/main.js",
    "bin": {
      "moon-phase": "dist/main.js"
    },
    "scripts": {
      "build": "tsc",
      "test": "mocha -r ts-node/register tests/**/*.ts"
    },
    "devDependencies": {
      "typescript": "^5.0.0",
      "ts-node": "^10.0.0",
      "mocha": "^10.0.0"
    }
  }

• Clarify date format expectations – Mention that the CLI accepts any string parsable by new Date(), but recommend ISO‑8601 (e.g., 2023-01-21) to avoid locale‑dependent ambiguities.

🧱 Mocks/Fakes

• Current approach – The test suite uses real dates and the actual implementation; no mocks are required for this pure‑function logic.
• Future extensibility – If the utility ever incorporates external data (e.g., an API for precise lunar ephemerides), introduce a thin abstraction layer (e.g., interface LunarCalculator) so that tests can inject deterministic fakes.

---

Overall, the core functionality is solid and the CLI works as described. Addressing the documentation inconsistencies, adding a few edge‑case tests, and providing a minimal package.json will make the utility more robust and developer‑friendly.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Self-contained utility: The utility is entirely self-contained within its directory, including source, tests, and documentation. This promotes modularity and ease of understanding, making it simple to integrate or remove.
• Clear algorithmic intent: The moonPhaseIndex function clearly documents its reference new moon date and the synodic month length. This explicit documentation is crucial for maintainability and for verifying the astronomical approximation used.
• Zero-dependency implementation: The core logic is implemented without external dependencies, making it lightweight, easy to audit, and highly portable across different environments.
• Robust date parsing: The parseDateArg function handles both default (today) and explicit ISO-8601 date arguments, including basic error handling for invalid inputs, which improves the user experience.

🧪 Tests

• Limited test coverage for phases: The current test suite covers only four specific dates representing the cardinal moon phases (New, First Quarter, Full, Last Quarter). This leaves significant gaps for intermediate phases (waxing/waning crescent/gibbous) and edge cases around the phase transitions.
  • Consider adding test cases for dates known to fall into the waxing/waning crescent and gibbous phases. For example:

    // ... existing test cases
    { date: "2023-01-09", expected: "🌒" }, // Waxing Crescent
    { date: "2023-01-17", expected: "🌔" }, // Waxing Gibbous
    { date: "2023-01-24", expected: "🌖" }, // Waning Gibbous
    { date: "2023-01-03", expected: "🌘" }  // Waning Crescent (from previous cycle)

• No negative test cases for CLI input: The parseDateArg function includes error handling for invalid dates, but there are no tests to verify this behavior.
  • Add a test case that attempts to parse an invalid date string and asserts that the program exits with an error (e.g., by mocking process.exit and console.error to capture their calls).
• Missing integration test for CLI: While the core logic is unit-tested, there isn't an end-to-end test that executes the CLI script directly (e.g., using child_process.execSync).
  • Consider adding an integration test that runs the compiled or ts-node version of main.ts with various arguments and asserts its standard output, ensuring the full CLI flow works as expected.

🔒 Security

• No external dependencies: The utility has zero external dependencies, which significantly reduces the supply chain attack surface and the risk of introducing vulnerabilities from third-party code.
• Input validation: The parseDateArg function performs basic validation on the date input using new Date(). While new Date() is generally robust, it can be lenient with various date formats.
  • For a CLI utility, consider adding more explicit input validation (e.g., using a regex for strict ISO-8601 format) to prevent unexpected parsing behavior with malformed but technically "valid" date strings that new Date() might interpret differently than intended. This enhances robustness, even if not a direct security vulnerability in this context.
• No sensitive operations: The utility does not interact with filesystems, networks, or sensitive user data, minimizing its security footprint and potential for misuse.

🧩 Docs/DX

• Clear and comprehensive README: The README.md is well-structured, providing clear instructions for features, installation, usage, and testing. This significantly improves the developer experience for anyone trying to use or understand the utility.
• Inline documentation: The moonPhaseIndex function includes helpful comments explaining the reference new moon and the synodic month length, which aids future maintainers in understanding the core logic.
• CLI output conciseness: The CLI prints only the emoji and a newline. While concise, for debugging or verbose modes, it might be useful to have an option to print the input date or the calculated phase index.
  • Consider adding a --verbose or --debug flag to the CLI that, when present, outputs additional information like the input date and the calculated phase index before the emoji.
• Missing package.json and tsconfig.json: The PR describes running with ts-node or tsc but doesn't include standard configuration files.
  • Add a package.json with scripts for build, test, and start (for ts-node and compiled node execution). This standardizes the development workflow and makes it easier for others to contribute or use.
  • Include a tsconfig.json to define the TypeScript compilation settings explicitly, ensuring consistent builds.

🧱 Mocks/Fakes

• No explicit mocks/fakes: The PR body states "Not applicable; generator did not introduce new mocks." This is accurate, as the tests use fixed, known dates for assertions rather than mocking the Date object or its methods.
• Potential for Date mocking in tests: While not strictly necessary for the current test cases, if more complex time-dependent logic were introduced (e.g., testing the default "today" behavior without relying on the actual current date), mocking the Date object would be beneficial.
  • For future enhancements, if the utility were to interact with system time in a more complex way, consider using a testing utility (e.g., jest.useFakeTimers() or manually patching Date) for precise control over time in tests. For this specific utility, the current approach of providing explicit dates is sufficient.
• CLI exit mocking for error tests: As mentioned in the "Tests" section, verifying the exit(1) behavior of parseDateArg would require mocking process.exit and console.error to prevent the test runner from terminating and to assert the error message.
  • To test the exit(1) path, you would typically need to mock process.exit and console.error to assert their calls without actually terminating the test runner. This allows for controlled testing of error conditions.