feat(algorithms, graphs): min cost to supply water

[BrianLusina]

Describe your change:

Min Cost to supply water

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Documentation change?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms have a URL in its comments that points to Wikipedia or other similar explanation.
• If this pull request resolves one or more open issues then the commit message contains Fixes: #{$ISSUE_NO}.

Summary by CodeRabbit

Release Notes

• New Features

  • Added algorithm for optimizing water distribution using Union-Find approach.

• Documentation

  • Fixed image references in graph algorithm guides.
  • Reorganized graph algorithm content for improved accessibility.

• Tests

  • Added comprehensive test suite for water distribution algorithm.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR relocates graph algorithm entries from puzzles to algorithms, updates image path references by removing leading "./" from README files, and introduces the "Min Cost To Supply Water" algorithm with complete implementation, tests, and documentation using Union-Find and Kruskal's approach.

Changes

Cohort / File(s)	Summary
Directory Structure Update DIRECTORY.md	Moved block of graph-related entries from puzzles/graphs to algorithms/graphs, including Evaluate Division, Keys And Rooms, Knight On Chess Board, Maxareaofisland, Min Cost To Supply, Nearest Exit From Entrance In Maze, Number Of Islands, Number Of Provinces, Reorder Routes, Rotting Oranges, and Valid Path.
Image Path Normalization algorithms/graphs/knight_on_chess_board/README.md, algorithms/graphs/nearest_exit_from_entrance_in_maze/README.md, algorithms/graphs/reorder_routes/README.md, algorithms/graphs/rotting_oranges/README.md	Removed leading "./" from image file paths across multiple README files (e.g., ./knight_on_chess_board.jpg → knight_on_chess_board.jpg).
Min Cost To Supply Water Feature algorithms/graphs/min_cost_to_supply/README.md, algorithms/graphs/min_cost_to_supply/__init__.py, algorithms/graphs/min_cost_to_supply/test_min_cost_to_supply.py	Added new algorithm documentation, implementation with two variants using Kruskal's algorithm and Union-Find to compute minimum cost water supply distribution, and corresponding parameterized test suite.
Import Path Updates algorithms/graphs/number_of_islands/__init__.py, algorithms/graphs/number_of_islands/test_number_of_islands.py	Updated UnionFind import references from puzzles.graphs.number_of_islands to algorithms.graphs.number_of_islands, reflecting content relocation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 The graphs hop from puzzles to algorithms with glee,
Water flows through villages via UnionFind's tree,
Images shed their "./" like burrows in spring,
And imports find new homes—what joy this things bring!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly matches the main purpose of the PR: implementing the 'min cost to supply water' algorithm in the algorithms/graphs directory.
Description check	✅ Passed	The PR description follows the template structure with proper sections and all checklist items addressed; the author checked most boxes and appropriately left unchecked the issue reference checkbox (not applicable here).

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

DIRECTORY.md (1)

87-114: Graphs section entries and links look correct; MD007 warning is optional to address

The new Algorithms → Graphs bullets (Evaluate Division, Keys And Rooms, Knight On Chess Board, Maxareaofisland, Min Cost To Supply, Nearest Exit…, Number Of Islands (+ Union Find), Number Of Provinces, Reorder Routes, Rotting Oranges, Valid Path) correctly reference the algorithms/graphs/... test files, including the new Min Cost To Supply tests.

Indentation for this block matches the surrounding list structure; the MD007 (ul-indent) warnings from markdownlint are stylistic. If you want a perfectly clean lint run, you’d need to adjust indentation consistently across this whole file, not just this new block.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9c7f67d and 4c86ece.

⛔ Files ignored due to path filters (24)

• algorithms/graphs/knight_on_chess_board/knight_on_chess_board.jpg is excluded by !**/*.jpg
• algorithms/graphs/maxareaofisland/maxarea-grid.jpg is excluded by !**/*.jpg
• algorithms/graphs/min_cost_to_supply/images/examples/min_cost_to_supply_example_1.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/examples/min_cost_to_supply_example_2.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/examples/min_cost_to_supply_example_3.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/examples/min_cost_to_supply_example_4.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/examples/min_cost_to_supply_example_5.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_1.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_2.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_3.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_4.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_5.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_6.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_7.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_8.png is excluded by !**/*.png
• algorithms/graphs/min_cost_to_supply/images/solutions/min_cost_to_supply_solution_9.png is excluded by !**/*.png
• algorithms/graphs/nearest_exit_from_entrance_in_maze/nearest1-grid.jpg is excluded by !**/*.jpg
• algorithms/graphs/nearest_exit_from_entrance_in_maze/nearest2-grid.jpg is excluded by !**/*.jpg
• algorithms/graphs/nearest_exit_from_entrance_in_maze/nearest3-grid.jpg is excluded by !**/*.jpg
• algorithms/graphs/number_of_provinces/no_of_provinces_1.jpg is excluded by !**/*.jpg
• algorithms/graphs/number_of_provinces/no_of_provinces_2.jpg is excluded by !**/*.jpg
• algorithms/graphs/reorder_routes/reorder_routes_example_1.png is excluded by !**/*.png
• algorithms/graphs/reorder_routes/reorder_routes_example_2.png is excluded by !**/*.png
• algorithms/graphs/rotting_oranges/rotting_oranges.png is excluded by !**/*.png

📒 Files selected for processing (38)

• DIRECTORY.md
• algorithms/graphs/evaluate_division/README.md
• algorithms/graphs/evaluate_division/__init__.py
• algorithms/graphs/evaluate_division/test_evaluate_division.py
• algorithms/graphs/keys_and_rooms/README.md
• algorithms/graphs/keys_and_rooms/__init__.py
• algorithms/graphs/keys_and_rooms/test_can_visit_all_rooms.py
• algorithms/graphs/knight_on_chess_board/README.md
• algorithms/graphs/knight_on_chess_board/__init__.py
• algorithms/graphs/knight_on_chess_board/test_knight_on_chess_board.py
• algorithms/graphs/maxareaofisland/README.md
• algorithms/graphs/maxareaofisland/__init__.py
• algorithms/graphs/maxareaofisland/test_max_area_of_island.py
• algorithms/graphs/mesh_message/README.md
• algorithms/graphs/mesh_message/__init__.py
• algorithms/graphs/min_cost_to_supply/README.md
• algorithms/graphs/min_cost_to_supply/__init__.py
• algorithms/graphs/min_cost_to_supply/test_min_cost_to_supply.py
• algorithms/graphs/nearest_exit_from_entrance_in_maze/README.md
• algorithms/graphs/nearest_exit_from_entrance_in_maze/__init__.py
• algorithms/graphs/nearest_exit_from_entrance_in_maze/test_nearest_exit_from_entrance.py
• algorithms/graphs/number_of_islands/README.md
• algorithms/graphs/number_of_islands/__init__.py
• algorithms/graphs/number_of_islands/test_number_of_islands.py
• algorithms/graphs/number_of_islands/union_find.py
• algorithms/graphs/number_of_provinces/README.md
• algorithms/graphs/number_of_provinces/__init__.py
• algorithms/graphs/number_of_provinces/test_number_of_provinces.py
• algorithms/graphs/reorder_routes/README.md
• algorithms/graphs/reorder_routes/__init__.py
• algorithms/graphs/reorder_routes/test_reorder_routes.py
• algorithms/graphs/rotting_oranges/README.md
• algorithms/graphs/rotting_oranges/__init__.py
• algorithms/graphs/rotting_oranges/test_rotting_oranges.py
• algorithms/graphs/valid_path/README.md
• algorithms/graphs/valid_path/__init__.py
• algorithms/graphs/valid_path/test_valid_path.py
• puzzles/graphs/__init__.py

🧰 Additional context used

🧬 Code graph analysis (4)

algorithms/graphs/number_of_islands/test_number_of_islands.py (1)

algorithms/graphs/number_of_islands/__init__.py (2)

• num_of_islands (5-43)
• num_islands_union_find (46-65)

algorithms/graphs/min_cost_to_supply/__init__.py (2)

algorithms/graphs/number_of_islands/union_find.py (2)

• UnionFind (1-40)
• union (25-36)

algorithms/graphs/number_of_provinces/__init__.py (2)

• UnionFind (4-29)
• union (16-29)

algorithms/graphs/min_cost_to_supply/test_min_cost_to_supply.py (1)

algorithms/graphs/min_cost_to_supply/__init__.py (2)

• min_cost_to_supply_water (5-38)
• min_cost_to_supply_water_2 (41-51)

algorithms/graphs/number_of_islands/__init__.py (1)

algorithms/graphs/number_of_islands/union_find.py (1)

• UnionFind (1-40)

🪛 LanguageTool

algorithms/graphs/min_cost_to_supply/README.md

[style] ~3-~3: Consider a more expressive alternative.
Context: ...want to supply water to every house. To do this, we have two options: 1. Build a w...

(DO_ACHIEVE)

🪛 markdownlint-cli2 (0.18.1)

DIRECTORY.md

90-90: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

91-91: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

92-92: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

93-93: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

94-94: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

95-95: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

96-96: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

97-97: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

98-98: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

99-99: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

100-100: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

101-101: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

102-102: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

103-103: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

104-104: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

105-105: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

106-106: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

107-107: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

108-108: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

109-109: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

110-110: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

111-111: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

112-112: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

---

113-113: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

114-114: Unordered list indentation
Expected: 4; Actual: 6

(MD007, ul-indent)

🔇 Additional comments (13)

algorithms/graphs/number_of_islands/test_number_of_islands.py (1)

4-4: Import path alignment with algorithms package looks correct

The updated import to algorithms.graphs.number_of_islands matches the relocated implementation and exposed symbols; tests remain otherwise unchanged.

algorithms/graphs/rotting_oranges/README.md (1)

15-15: Image path tweak is consistent and safe

Switching from ./rotting_oranges.png to rotting_oranges.png keeps the relative reference valid and aligns with other graph README updates.

algorithms/graphs/knight_on_chess_board/README.md (1)

6-6: Image reference normalization looks good

Removing the leading "./" from the knight image path is harmless and consistent with the rest of the graph READMEs.

algorithms/graphs/reorder_routes/README.md (1)

18-27: Reorder Routes image paths updated consistently

Both example images now use reorder_routes_example_X.png without "./", matching the pattern adopted elsewhere in this PR.

algorithms/graphs/nearest_exit_from_entrance_in_maze/README.md (1)

15-43: Nearest-exit maze image references look fine

All three image paths are normalized (no "./") and still correctly target files in the same directory.

algorithms/graphs/number_of_islands/__init__.py (1)

2-2: UnionFind import path update aligns with new module layout

Importing UnionFind from algorithms.graphs.number_of_islands.union_find matches the reorganized location of that helper and keeps num_islands_union_find behavior intact.

algorithms/graphs/min_cost_to_supply/__init__.py (1)

1-51: No changes needed; the UnionFind.union method correctly returns a boolean

The imported UnionFind from datastructures.sets.union_find explicitly returns bool—True when a merge occurs and False when elements are already in the same set. The pattern if uf.union(house1, house2): is correct, and total_cost will properly accumulate. Both functions implement the MST/Kruskal approach correctly.

algorithms/graphs/min_cost_to_supply/test_min_cost_to_supply.py (3)

1-18: LGTM! Well-structured test setup.

The imports are correct, and the test cases provide good coverage across various scenarios including edge cases with different graph sizes, well costs, and pipe configurations.

---

21-27: LGTM! Test method is correctly implemented.

The parameterized test is properly structured with accurate type hints and assertion logic.

---

29-38: LGTM! Second test method and CLI entry point are correct.

The test for the alternative implementation shares the same test cases appropriately, and the CLI entry point follows Python conventions.

algorithms/graphs/min_cost_to_supply/README.md (3)

1-26: LGTM! Clear and comprehensive problem description.

The problem statement effectively explains the water distribution challenge with wells and pipes, and the constraints are properly documented. The static analysis style hint about "To do this" can be safely ignored—the phrasing is clear and appropriate for technical documentation.

---

80-91: LGTM! Accurate complexity analysis.

The time and space complexity analysis is correct and well-explained. The identification of the sorting step as the dominant factor and the mention of the inverse Ackermann function α(n) for Union-Find operations demonstrates thorough understanding.

---

29-67: LGTM! Excellent solution explanation with clear algorithm steps.

The solution effectively describes the virtual node approach combined with Union-Find/Kruskal's algorithm. The step-by-step breakdown is clear and actionable. All referenced example images are present and properly linked.