feat(strings, heaps): longest happy string

[BrianLusina]

Describe your change:

Longest happy string implementation using max heaps

• 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

  • Added longest happy string generation feature for constructing diverse character strings.

• Documentation

  • Expanded and reorganized documentation structure with new problem references and solution guides.

• Tests

  • Added comprehensive test suite for the new algorithm.

• Refactor

  • Improved type safety with explicit type annotations and added performance optimization for string similarity checking.

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

[coderabbitai]

Walkthrough

The PR introduces a new longest diverse string module using a max-heap algorithm, adds type annotations and an early-exit optimization to similar_string_groups, provides supporting documentation and tests, and reorganizes DIRECTORY.md for intervals and data structure resources.

Changes

Cohort / File(s)	Summary
Longest Happy String Module pystrings/longest_happy_string/__init__.py, pystrings/longest_happy_string/README.md, pystrings/longest_happy_string/test_longest_happy_string.py	Introduces new function longest_diverse_string(a, b, c) using max-heap to construct longest string over {'a','b','c'} without three consecutive identical characters. Includes algorithm documentation with complexity analysis (O(a+b+c) time, O(k) space) and parameterized unit tests.
Similar String Groups Type Refinements pystrings/similar_string_groups/__init__.py	Adds Tuple type import, annotates are_similar(s1: str, s2: str) parameters with type hints, types diff variable as List[Tuple[str, str]], and introduces early-exit optimization for cases exceeding two differences.
Documentation & Directory Structure DIRECTORY.md	Reorganizes documentation entries: adds Intervals/Task Scheduler references, introduces Sets > Union Find category across multiple sections, augments Binary Search Tree listings, and reorganizes balanced parentheses entries with new test references.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• longest_happy_string/__init__.py: Verify max-heap algorithm correctness, boundary conditions (no valid character case), and heap requeue logic
• longest_happy_string/test_longest_happy_string.py: Assess test case coverage for edge cases (a=b=c=0, single character dominance, etc.)
• similar_string_groups/__init__.py: Confirm early-exit optimization preserves correctness and type annotations align with function logic

Possibly related PRs

• feat(strings): similar string groups #104: Directly modifies pystrings/similar_string_groups module including are_similar function and surrounding similarity/DSU logic.

Poem

🐰 Hop! A heap builds strings so bright,
No three in a row—oh, what a sight!
Types now guard our similar ways,
Directories bloom in structured maze. 🌱✨

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 'feat(strings, heaps): longest happy string' is directly related to the main change, clearly describing the addition of a longest happy string algorithm implementation using heaps.
Description check	✅ Passed	The pull request description follows the template structure, marks appropriate checklist items, and comprehensively documents the changes including algorithm addition and documentation updates.

✨ 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/longest-happy-string

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7cec5b1 and 68b4fd4.

⛔ Files ignored due to path filters (18)

• pystrings/longest_happy_string/images/examples/longest_happy_string_example_1.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/examples/longest_happy_string_example_2.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/examples/longest_happy_string_example_3.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_1.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_10.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_11.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_12.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_13.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_14.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_15.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_2.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_3.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_4.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_5.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_6.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_7.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_8.png is excluded by !**/*.png
• pystrings/longest_happy_string/images/solutions/longest_happy_string_solution_9.png is excluded by !**/*.png

📒 Files selected for processing (5)

• DIRECTORY.md (6 hunks)
• pystrings/longest_happy_string/README.md (1 hunks)
• pystrings/longest_happy_string/__init__.py (1 hunks)
• pystrings/longest_happy_string/test_longest_happy_string.py (1 hunks)
• pystrings/similar_string_groups/__init__.py (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

pystrings/longest_happy_string/test_longest_happy_string.py (1)

pystrings/longest_happy_string/__init__.py (1)

• longest_diverse_string (5-52)

🪛 LanguageTool

pystrings/longest_happy_string/README.md

[style] ~37-~37: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...uency and the corresponding character. We initialize an empty list result to cons...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~39-~39: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nstruct the happy string step by step. We iterate until the heap, pq, is empty an...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~43-~43: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...er with the highest frequency from pq. We handle repetition constraints by checki...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~58-~58: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 5399 characters long)
Context: ...ns/longest_happy_string_solution_1.png) ![Longest Happy String Solution 14](./ima...

(EN_EXCESSIVE_EXCLAMATION)

🪛 markdownlint-cli2 (0.18.1)

pystrings/longest_happy_string/README.md

18-18: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

DIRECTORY.md

91-91: Unordered list indentation
Expected: 0; Actual: 2

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

---

272-272: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

299-299: Unordered list indentation
Expected: 6; Actual: 8

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

746-746: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

748-748: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

750-750: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

752-752: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

776-776: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

🔇 Additional comments (4)

pystrings/similar_string_groups/__init__.py (1)

1-1: LGTM! Excellent type hints and optimization.

The addition of explicit type hints improves code clarity and enables better IDE support. The early-exit optimization on lines 62-63 is a smart performance improvement—bailing out as soon as we detect more than two differences avoids unnecessary iteration.

Also applies to: 57-63

pystrings/longest_happy_string/test_longest_happy_string.py (1)

1-25: Well-structured parameterized tests.

The test structure is clean and the use of parameterized.expand makes it easy to add new test cases. The coverage includes various scenarios: balanced counts, zero counts, and dominant single characters.

pystrings/longest_happy_string/__init__.py (1)

5-52: LGTM! Solid max-heap greedy algorithm.

The implementation correctly handles the constraint of avoiding three consecutive identical characters using a max-heap approach. The logic on lines 27-41 properly switches to the next most frequent character when needed, and the condition on line 37 (temp_cnt + 1) < 0 correctly checks if the temporary character still has remaining occurrences (since counts are stored as negative values for the max-heap simulation).

pystrings/longest_happy_string/README.md (1)

1-87: Excellent documentation with clear problem statement and solution.

The README provides a comprehensive explanation of the problem, constraints, and solution approach. The step-by-step solution description and complexity analysis are accurate and helpful. The time complexity O(k) where k=a+b+c and space complexity O(1) for the heap are correctly identified.

---

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.}