[R45-T014] Add traversal invariant checks for BipartiteGraphDFS - #55

Description

Documents the DFS coloring and cycle-termination invariant in src/main/java/com/thealgorithms/datastructures/graphs/BipartiteGraphDFS.java, adds JUnit invariant/property tests (BipartiteGraphDFSInvariantTest.java), and adds a focused runner (work/R45-T014/check.py) that executes the checks and records results and tool versions. All existing behavior and public interfaces are preserved.

Related Issue

Fixes: #14

Type of Change

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

Changes Made

• Documented the traversal invariant in the Javadoc of BipartiteGraphDFS.bipartite (lines 41–43) and BipartiteGraphDFS.isBipartite (lines 71–73) in src/main/java/com/thealgorithms/datastructures/graphs/BipartiteGraphDFS.java: every reachable vertex transitions from -1 to {0, 1} once before recursion, ensuring reachable nodes are expanded at most once and cycles terminate without infinite walks. No executable code or public API was modified.
• Added src/test/java/com/thealgorithms/datastructures/graphs/BipartiteGraphDFSInvariantTest.java with 3 test methods:
  • Required fixture (A→B, B→C, C→A and isolated D, both directed and undirected): verifies that starting at A expands [0, 1, 2] once each, terminates with false, and never visits D (D_visits=0).
  • Smallest failing example (v=1, self-loop 0→0 → false, visited [0]) and smallest bipartite even cycle with isolated node (0-1-2-3-0, isolated 4 → true, every node expanded once).
  • Seeded property test (FIXED_SEED = 20261111L, 120 bounded valid graphs with v in [1..12]): asserts at-most-once vertex expansion (expansionCounts[node] <= 1, and == 1 when bipartite), no input mutation, and 100% agreement with an independent BFS two-coloring oracle (59 bipartite, 61 non-bipartite).
• Added work/R45-T014/check.py (with evidence files in work/R45-T014/), running mvn test for BipartiteGraphDFSInvariantTest, 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-T014/check.py
(runs mvn -B test -Dtest=BipartiteGraphDFSInvariantTest -Dsurefire.failIfNoSpecifiedTests=false)

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

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

Negative check: temporarily breaking the unvisited guard on line 56 (if (color[it] == -1) → if (color[it] != color[node])) caused python3 work/R45-T014/check.py to print status=FAIL (tests=3 failures/errors=3 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-T014/tool_versions.txt and work/R45-T014/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

• Why the invariant holds: color[it] is assigned 1 - color[node] (in {0, 1}) before recursing on it, and color entries are never reset to -1. Therefore bipartite can recurse into any reachable vertex at most once, bounding total recursive calls to at most v even in the presence of arbitrary cycles.

• The work/R45-T014/ 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