feat(algorithms, two-pointers): next permutation

[BrianLusina]

Describe your change:

Next permutation of arrays

• 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

• New Features

  • Next Permutation algorithm added to Algorithms > Two Pointers collection.

• Documentation

  • Comprehensive documentation added for Next Permutation, including problem statement, constraints, examples, and detailed algorithm explanation with complexity analysis.

• Chores

  • Reorganized Next Permutation from Puzzles to Algorithms section.

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

[coderabbitai]

Caution

Review failed

The head commit changed during the review from 0449374 to 60afc43.

Walkthrough

The pull request reorganizes the Next Permutation problem from Puzzles to Algorithms > Two Pointers, updates the directory structure, adds comprehensive documentation, refactors the implementation with helper functions and detailed comments, and updates corresponding test imports.

Changes

Cohort / File(s)	Summary
Category reorganization DIRECTORY.md	Added Next Permutation entry under Algorithms > Two Pointers; removed from Puzzles section.
Documentation updates algorithms/two_pointers/next_permutation/README.md, puzzles/next_permutation/README.md	Added comprehensive README explaining the problem, constraints, examples, algorithm approach (pivot-successor-swap-reverse), edge cases, and complexity analysis to algorithms location; deleted equivalent documentation from puzzles location.
Implementation refactoring algorithms/two_pointers/next_permutation/__init__.py	Introduced helper functions reverse() and swap(); refactored next_permutation() with explicit three-step algorithm documentation (pivot location, swap, suffix reversal) and clarifying comments; maintained in-place semantics.
Test import migration algorithms/two_pointers/next_permutation/test_next_permutation.py	Updated import path from puzzles.next_permutation to algorithms.two_pointers.next_permutation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

• Primary attention: verify the refactored next_permutation() logic correctly implements the three-step algorithm (pivot scan, rightmost greater element swap, suffix reversal).
• Confirm helper functions reverse() and swap() have correct semantics for in-place list modification.
• Verify test import paths align with new module location and tests pass.

Suggested labels

enhancement, Documentation

Poem

🐰 A hop through the permutations we go,
From puzzles to algorithms, watch knowledge flow!
Two pointers dance in orderly grace,
Helper functions now lead the race—
Pivot, swap, reverse with care,
Next permutation blooms everywhere! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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 summarizes the main change: adding a next permutation algorithm to the algorithms/two-pointers section.
Description check	✅ Passed	The description follows the template structure with 'Describe your change' and a checklist. Most items are checked off, though the PR involves moving/refactoring an existing algorithm rather than purely adding new code.

---

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: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

algorithms/two_pointers/next_permutation/__init__.py (1)

40-44: Add missing type annotation for consistency.

The parameter j is missing its type annotation, which is inconsistent with the rest of the codebase where all function parameters have type hints.

🔎 Proposed fix

-def swap(nums: List[int], i: int, j) -> None:
+def swap(nums: List[int], i: int, j: int) -> None:

🧹 Nitpick comments (1)

algorithms/two_pointers/next_permutation/README.md (1)

16-42: Consider adding language specifiers to code blocks.

The example code blocks would benefit from language specifiers for better rendering and syntax highlighting in markdown viewers.

🔎 Proposed fix

-```
+```text
 Example 1:
 
 Input: nums = [1,2,3]
 Output: [1,3,2]

- +text
Example 2:

Input: nums = [3,2,1]
Output: [1,2,3]

-```
+```text
Example 3:

Input: nums = [1,1,5]
Output: [1,5,1]

- +text
Example 4:

Input: nums = [1]
Output: [1]

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dacbf8a and f339a02.

📒 Files selected for processing (5)

• DIRECTORY.md
• algorithms/two_pointers/next_permutation/README.md
• algorithms/two_pointers/next_permutation/__init__.py
• algorithms/two_pointers/next_permutation/test_next_permutation.py
• puzzles/next_permutation/README.md

💤 Files with no reviewable changes (1)

• puzzles/next_permutation/README.md

🧰 Additional context used

🧬 Code graph analysis (1)

algorithms/two_pointers/next_permutation/test_next_permutation.py (1)

algorithms/two_pointers/next_permutation/__init__.py (1)

• next_permutation (4-26)

🪛 LanguageTool

algorithms/two_pointers/next_permutation/README.md

[style] ~55-~55: Consider a more expressive alternative.
Context: ...e array (the right-hand side) first. To do this, we make the smallest possible in...

(DO_ACHIEVE)

🪛 markdownlint-cli2 (0.18.1)

DIRECTORY.md

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

algorithms/two_pointers/next_permutation/README.md

16-16: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

23-23: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

30-30: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

37-37: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (4)

algorithms/two_pointers/next_permutation/test_next_permutation.py (1)

3-3: LGTM! Import path correctly updated.

The import path has been properly updated to reflect the reorganization of the Next Permutation functionality from puzzles to algorithms.two_pointers. The test suite remains comprehensive and unchanged.

algorithms/two_pointers/next_permutation/__init__.py (2)

4-26: LGTM! Well-documented implementation.

The next_permutation function is correctly implemented with clear step-by-step comments that explain the algorithm. The three-phase approach (find pivot, swap with successor, reverse suffix) is standard and efficient.

---

29-37: LGTM! Clean helper function.

The reverse helper function is well-implemented and correctly reverses the array segment from the start index to the end.

algorithms/two_pointers/next_permutation/README.md (1)

44-97: LGTM! Excellent documentation.

The explanation is comprehensive and well-structured. The step-by-step breakdown clearly explains the algorithm logic, including edge cases and the two-pointer approach. The time and space complexity analysis is accurate.