feat(algorithms greedy) minimum moves to spread stones & minimum boats to rescue people

[BrianLusina]

Describe your change:

Adds algorithm challenges:

1. Minimum moves to spread stones along a 3X3 grid
2. Minimum number of boats to use to rescue people from a sinking ship

• 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 "Boats to Save People" algorithm solution with detailed problem documentation and examples
  • Added "Spread Stones" grid puzzle algorithm with comprehensive problem guide

• Documentation

  • Updated navigation directory to include new algorithm sections
  • Added problem statements, constraints, and complexity analysis for both algorithms

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

[coderabbitai]

Walkthrough

This PR adds two new greedy algorithm implementations to the algorithms library: a boats rescue problem using two-pointer technique and a stone spreading puzzle using permutation-based Manhattan distance minimization, along with documentation and unit tests for each.

Changes

Cohort / File(s)	Summary
Navigation DIRECTORY.md	Adds navigation entries for new Boats and Spread Stones subsections under Greedy algorithms
Boats to Save People algorithms/greedy/boats/README.md, algorithms/greedy/boats/__init__.py, algorithms/greedy/boats/test_boats_to_save_people.py	Implements rescue_boats() function using two-pointer greedy approach to pair lightest and heaviest people within boat weight limits; includes comprehensive problem documentation and parameterized unit tests
Spread Stones algorithms/greedy/spread_stones/README.md, algorithms/greedy/spread_stones/__init__.py, algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py	Implements minimum_moves() function computing minimal moves to distribute stones evenly across a 3×3 grid using permutation enumeration and Manhattan distance; includes problem documentation and parameterized unit tests

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• algorithms/greedy/boats/__init__.py: Verify correctness of two-pointer logic—ensure proper advancement of pointers and accurate boat counting across edge cases (single person, all people fit one boat, no one can pair)
• algorithms/greedy/spread_stones/__init__.py: Verify permutation-based algorithm logic—confirm Manhattan distance calculations are accurate and that minimum tracking correctly identifies the optimal assignment; assess computational complexity for larger problem instances
• Test coverage: Ensure both test suites adequately cover boundary conditions, typical cases, and edge cases relevant to each algorithm

Poem

🐰 Two algorithms hop into the fold,
Boats rescue sailors, brave and bold,
Stones spread evenly on the ground,
Greedy wisdom all around! 🚤💎

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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 accurately describes the main changes: adding two greedy algorithms for minimum moves to spread stones and minimum boats to rescue people.
Description check	✅ Passed	The description follows the template structure, clearly describes the changes, and includes all required checklist items with appropriate selections marked.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/algorithms-greedy-minimum-movees-to-spread-stones

---

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 (4)

DIRECTORY.md (1)

86-87: Fix markdown list indentation for consistency.

The indentation for the new subsections doesn't match the expected markdown list formatting used throughout the rest of the file.

🔎 Apply this diff to fix the indentation:

-    * Boats
-      * [Test Boats To Save People](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/greedy/boats/test_boats_to_save_people.py)
+  * Boats
+    * [Test Boats To Save People](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/greedy/boats/test_boats_to_save_people.py)

-    * Spread Stones
-      * [Test Minimum Moves To Spread Stones](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py)
+  * Spread Stones
+    * [Test Minimum Moves To Spread Stones](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py)

Based on static analysis hints.

Also applies to: 96-97

algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py (1)

16-20: Rename test method for better clarity.

The test method name test_something is not descriptive. Consider renaming it to better reflect what's being tested.

🔎 Apply this diff to improve the method name:

     @parameterized.expand(TEST_CASES)
-    def test_something(self, grid: List[List[int]], expected: int):
+    def test_minimum_moves(self, grid: List[List[int]], expected: int):
         actual = minimum_moves(grid)
         self.assertEqual(expected, actual)

algorithms/greedy/spread_stones/README.md (1)

1-13: Consider enhancing documentation to match the boats README standard.

The current documentation covers the problem statement and constraints, which is good. However, the boats README provides a more comprehensive guide including:

• Solution approach explanation (naive vs. optimized)
• Time and space complexity analysis
• Visual examples and walkthroughs

Adding these sections would make the documentation more helpful for contributors and users.

algorithms/greedy/spread_stones/__init__.py (1)

5-44: LGTM! Correct permutation-based solution.

The implementation correctly solves the problem by:

• Building surplus and empty cell lists
• Trying all permutations of surplus-to-empty assignments
• Calculating Manhattan distance for each assignment
• Returning the minimum

The brute-force permutation approach has O(k! × k) complexity, but this is acceptable for the 3×3 grid constraint where k ≤ 8.

Minor: Line 30 uses loop variable c only for counting. Consider using _ to indicate the value isn't used:

for _ in range(count - 1):

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 57c3839 and 887e853.

⛔ Files ignored due to path filters (15)

• algorithms/greedy/boats/images/examples/boats_to_save_people_example_1.png is excluded by !**/*.png
• algorithms/greedy/boats/images/examples/boats_to_save_people_example_2.png is excluded by !**/*.png
• algorithms/greedy/boats/images/examples/boats_to_save_people_example_3.png is excluded by !**/*.png
• algorithms/greedy/boats/images/examples/boats_to_save_people_example_4.png is excluded by !**/*.png
• algorithms/greedy/boats/images/examples/boats_to_save_people_example_5.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_1.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_10.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_2.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_3.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_4.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_5.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_6.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_7.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_8.png is excluded by !**/*.png
• algorithms/greedy/boats/images/solutions/boats_to_save_people_solution_9.png is excluded by !**/*.png

📒 Files selected for processing (7)

• DIRECTORY.md (2 hunks)
• algorithms/greedy/boats/README.md (1 hunks)
• algorithms/greedy/boats/__init__.py (1 hunks)
• algorithms/greedy/boats/test_boats_to_save_people.py (1 hunks)
• algorithms/greedy/spread_stones/README.md (1 hunks)
• algorithms/greedy/spread_stones/__init__.py (1 hunks)
• algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

algorithms/greedy/boats/test_boats_to_save_people.py (1)

algorithms/greedy/boats/__init__.py (1)

• rescue_boats (4-41)

algorithms/greedy/spread_stones/test_minimum_moves_to_spread_stones.py (1)

algorithms/greedy/spread_stones/__init__.py (1)

• minimum_moves (5-44)

🪛 markdownlint-cli2 (0.18.1)

DIRECTORY.md

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

(MD007, ul-indent)

---

87-87: 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)

🔇 Additional comments (3)

algorithms/greedy/boats/test_boats_to_save_people.py (1)

1-27: LGTM! Well-structured test suite.

The test file is well-organized with comprehensive test cases covering various scenarios including edge cases (single person, all same weight, etc.). The use of parameterized testing keeps the code DRY and maintainable.

algorithms/greedy/boats/README.md (1)

1-97: LGTM! Excellent documentation.

The documentation is comprehensive and well-structured, providing:

• Clear problem statement with real-world context
• Explicit constraints
• Visual examples and solution walkthroughs
• Comparison of naive vs. optimized approaches
• Detailed complexity analysis
• Step-by-step implementation guide

This sets a great standard for algorithm documentation in the repository.

algorithms/greedy/boats/__init__.py (1)

1-41: LGTM! Clean and correct implementation.

The greedy two-pointer approach is correctly implemented:

• Properly sorts weights and uses two pointers to pair lightest with heaviest
• Defensive programming: copies input to avoid mutation
• Clear variable names and helpful comments
• Matches the algorithm described in the README

The implementation correctly handles all edge cases and has the expected O(n log n) time complexity.