feat(algorithms, stack): longest valid parentheses

[BrianLusina]

Describe your change:

Finds the longest valid parentheses using a stack data structure

• 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 Longest Valid Parentheses algorithm to the Stack collection.

• Documentation

  • Added comprehensive README with algorithm explanation, complexity analysis, and example cases.
  • Updated directory index to reflect new Stack entry.

• Tests

  • Added parameterised unit tests with multiple test cases.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new stack-based algorithm for finding the longest valid parentheses substring has been added to the algorithms collection, including implementation, comprehensive documentation, and unit tests across four files.

Changes

Cohort / File(s)	Summary
Documentation DIRECTORY.md, algorithms/stack/longest_valid_parentheses/README.md	Added directory entry and comprehensive README describing the longest valid parentheses problem, stack-based solution approach using index tracking, and O(n) time/O(n) space complexity analysis.
Implementation algorithms/stack/longest_valid_parentheses/__init__.py	New function implementing the longest valid parentheses algorithm using an index stack with sentinel value (−1), iterating through the string, managing stack operations on parentheses, and tracking maximum valid substring length.
Testing algorithms/stack/longest_valid_parentheses/test_longest_valid_parentheses.py	New parameterised unittest module with predefined test cases validating the longest_valid_parentheses() function against expected outputs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A stack so clever, indices we keep,
Matching brackets dance, nested deep,
One pass through strings, no repeat,
Longest valid parentheses—victory sweet! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a longest valid parentheses algorithm to the stack category.
Description check	✅ Passed	The pull request description is substantially complete, covering the change purpose and addressing all major checklist items, though the description itself is brief.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/algorithms-stack-longest-valid-parentheses

---

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

🧹 Nitpick comments (1)

algorithms/stack/longest_valid_parentheses/__init__.py (1)

1-1: Consider adding a function docstring with doctest examples.

This would improve discoverability and keep the new algorithm self-documented at source level.

🧩 Suggested enhancement

 def longest_valid_parentheses(s: str) -> int:
+    """
+    Return the length of the longest valid parentheses substring.
+
+    >>> longest_valid_parentheses("(()")
+    2
+    >>> longest_valid_parentheses(")()())")
+    4
+    >>> longest_valid_parentheses("")
+    0
+    """

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@algorithms/stack/longest_valid_parentheses/__init__.py` at line 1, Add a
concise docstring to the function longest_valid_parentheses describing its
purpose, parameters, and return value, and include several doctest-style
examples showing expected outputs (e.g., empty string -> 0, "()" -> 2, ")()())"
-> 4, "(()" -> 2) to serve as usage documentation and tests; place the docstring
immediately under the def longest_valid_parentheses(s: str) -> int: signature
and ensure examples use Python REPL format (>>> ...) so they can be run by
doctest.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@algorithms/stack/longest_valid_parentheses/README.md`:
- Line 73: Reword the final-step sentence to reflect that max_length is
maintained during the loop and is the final answer (rather than implying a
separate final max(maxLength, currentLength) call); mention that max_length is
updated on each iteration (e.g., via max_length = max(max_length,
current_length)) and the final result is simply max_length after the iteration
completes.

---

Nitpick comments:
In `@algorithms/stack/longest_valid_parentheses/__init__.py`:
- Line 1: Add a concise docstring to the function longest_valid_parentheses
describing its purpose, parameters, and return value, and include several
doctest-style examples showing expected outputs (e.g., empty string -> 0, "()"
-> 2, ")()())" -> 4, "(()" -> 2) to serve as usage documentation and tests;
place the docstring immediately under the def longest_valid_parentheses(s: str)
-> int: signature and ensure examples use Python REPL format (>>> ...) so they
can be run by doctest.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 26696d09-c053-4342-9d4a-807679d03054

📥 Commits

Reviewing files that changed from the base of the PR and between d11f015 and 58ec751.

📒 Files selected for processing (4)

• DIRECTORY.md
• algorithms/stack/longest_valid_parentheses/README.md
• algorithms/stack/longest_valid_parentheses/__init__.py
• algorithms/stack/longest_valid_parentheses/test_longest_valid_parentheses.py