[R45-T018] Cover failure and empty-result paths of HierholzerAlgorithm - #58

Description

Documents the failure and absent-result paths on hasEulerianCircuit() and findEulerianCircuit() in src/main/java/com/thealgorithms/graph/HierholzerAlgorithm.java, adds JUnit failure-path regression tests (HierholzerAlgorithmFailureTest.java), and adds a focused runner (work/R45-T018/check.py). Existing supported behavior, caller-owned graph preservation, and the public interface are preserved.

Related Issue

Fixes: #18

Type of Change

• Bug Fix
• New Feature
• UI/UX Improvement
• Performance Improvement
• Tests
• Documentation
• Refactoring / Maintenance
• CI/CD

Changes Made

• Added Javadoc on hasEulerianCircuit() (lines 41–48) and findEulerianCircuit() (lines 63–72) in src/main/java/com/thealgorithms/graph/HierholzerAlgorithm.java explaining the empty/absent-result paths (Collections.emptyList() on odd degree, disconnected non-zero-degree components, or empty/null graph, and single-element list for isolated degree-0 vertices). No executable code or public API was modified.
• Added src/test/java/com/thealgorithms/graph/HierholzerAlgorithmFailureTest.java with 3 test methods (7 logged cases):
  • null graph, empty {} graph ([]), and smallest isolated vertex {0=[]} ([0]).
  • Smallest odd-degree failure ({0=[1], 1=[0]} reaching line 56 false and line 75 Collections.emptyList()), verifying caller-owned graph stays unmutated and an ordinary valid triangle ([0, 1, 2, 0]) succeeds afterwards (including repeated calls).
  • Disconnected even-degree failure (two disjoint triangles reaching lines 141–142 false and line 75 Collections.emptyList()), verifying caller-owned graph stays unmutated and a subsequent ordinary valid call succeeds.
• Added work/R45-T018/check.py (with evidence files in work/R45-T018/), running mvn test for HierholzerAlgorithmFailureTest, enforcing a nonzero test count, saving comparisons.txt, result.txt, mvn_output.txt, and tool_versions.txt, and exiting non-zero on failure.

Screenshots / Recordings

Not applicable (no UI changes).

Testing

Command: python3 work/R45-T018/check.py
(runs mvn -B test -Dtest=HierholzerAlgorithmFailureTest -Dsurefire.failIfNoSpecifiedTests=false)

Result: tests=3 failures/errors=0 skipped=0 records=7 mvn_exit=0, status=PASS

Existing suite: mvn -B test -Dtest=HierholzerAlgorithmTest -Dsurefire.failIfNoSpecifiedTests=false → Tests run: 4, Failures: 0, Errors: 0, Skipped: 0 (BUILD SUCCESS).

Negative check: temporarily disabling the odd-degree check on line 55 (if (neighbors.size() % 2 != 0) → if (neighbors.size() < 0)) caused python3 work/R45-T018/check.py to print status=FAIL (tests=3 failures/errors=1 skipped=0 mvn_exit=1) and exit non-zero; reverted and re-verified.

Style: mvn -B checkstyle:check reports 0 Checkstyle violations (BUILD SUCCESS).

Tool versions and check records are saved in work/R45-T018/tool_versions.txt and work/R45-T018/comparisons.txt.

Checklist

• I have tested my changes locally.
• I have added or updated tests, if needed.
• I have updated documentation, if needed.
• I have followed the project's coding guidelines.
• I have run the relevant tests and checks.
• I have addressed previous review feedback, if applicable.

Additional Notes

• No error-handling repair was needed because HierholzerAlgorithm already returns Collections.emptyList() without mutating caller-owned adjacency lists (tempGraph copies them on lines 78–81).

• The work/R45-T018/ evidence folder is for coursework review only and should not go into any later upstream PR.

• I have read CONTRIBUTING.md.

• This pull request is all my own work -- I have not plagiarized it.

• All filenames are in PascalCase.

• All functions and variable names follow Java naming conventions.

• All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.

• All new algorithms include a corresponding test class that validates their functionality.

• All new code is formatted with clang-format -i --style=file path/to/your/file.java