feat(heaps): maximal score after k operations

[BrianLusina]

Describe your change:

Adds an algorithm to find the maximum score after applying k operations to a list of integers. This utilizes the max heap datastructure to ensure that the maximum value is readily available at the root of the max heap.

• 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 a new puzzle to the Heap collection: "Maximal Score After K Operations" with a working solution.

• Documentation

  • Added comprehensive problem documentation with algorithm explanation, step-by-step walkthroughs, example visualizations, and complexity notes.

• Tests

  • Added a test suite with nine cases covering varied inputs and edge conditions.

[coderabbitai]

Walkthrough

Added a new Heap puzzle "Maximal Score After K Operations": directory entry, README explaining the max-heap algorithm (pop max, add to score, push ceil(val/3) for k iterations), a Python implementation, and a nine-test unittest suite.

Changes

Cohort / File(s)	Summary
Directory index DIRECTORY.md	Inserted new Heap entry "Maximal Score After K Operations" with a test link.
Problem documentation puzzles/heap/maximal_score_after_k_operations/README.md	Added problem statement, constraints, solution outline using a max-heap (negation with heapq), step-by-step algorithm, complexity notes (O(k log n) time, O(n) space), and example illustrations.
Implementation puzzles/heap/maximal_score_after_k_operations/__init__.py	Added max_score(nums: List[int], k: int) -> int implementing: build max-heap, repeat k times pop max, add to score, push ceil(max/3); handles empty input.
Tests puzzles/heap/maximal_score_after_k_operations/test_maximal_score.py	Added unittest TestCase with nine test methods (test_1…test_9) asserting expected outputs for varied inputs and k values.

Sequence Diagram(s)

sequenceDiagram participant Caller participant max_score participant Heap Caller->>max_score: max_score(nums, k) max_score->>Heap: build max-heap (negate values) loop k iterations max_score->>Heap: pop max Heap-->>max_score: largest max_score->>max_score: score += largest max_score->>max_score: next = ceil(largest / 3) max_score->>Heap: push next end max_score-->>Caller: return score 

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10–15 minutes

• Focus review on: correct negation/use of heapq for max-heap, integer ceiling calculation and type handling, edge-case when nums is empty or contains zeros, and validity of expected values in the nine tests.

Poem

🐰 I hopped into the heap one day,
Popped the largest, sent it away,
Ceil'd and pushed, and counted K,
Nine tests cheered — hip, hop, hooray!

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 PR title clearly and concisely describes the main change: adding a maximal score algorithm using heaps after k operations, which matches the primary objective of the changeset.
Description check	✅ Passed	The PR description is comprehensive and addresses the template requirements, including clear problem description, all relevant checklist items checked, and adherence to repository guidelines for algorithm contributions.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/maximal-score-after-k-ops

---

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

🧹 Nitpick comments (2)

puzzles/heap/maximal_score_after_k_operations/__init__.py (1)

9-11: Consider more idiomatic empty check.

The current empty check works correctly, but Python idiom favors if not nums: over len(nums) == 0 for checking empty sequences.

Apply this diff for a more pythonic style:

 # if there are no elements, just return the score of 0 -if len(nums) == 0: +if not nums: return score

puzzles/heap/maximal_score_after_k_operations/test_maximal_score.py (1)

5-73: Comprehensive test coverage with good variety of scenarios.

The test suite includes excellent coverage:

• Various array sizes (3 to 100+ elements)
• Different k values relative to array size
• Uniform values (test_8)
• Large-scale stress test (test_9 with k=1000)

All tests respect the problem constraints and validate the heap-based algorithm thoroughly.

Optional: Consider adding a test case where k significantly exceeds len(nums) (e.g., nums=[5,10], k=10) to explicitly verify the algorithm handles repeated operations on reduced values correctly.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a92accd and 81c3837.

⛔ Files ignored due to path filters (18)

• puzzles/heap/maximal_score_after_k_operations/images/examples/maximal_score_after_k_operations_example_1.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/examples/maximal_score_after_k_operations_example_2.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/examples/maximal_score_after_k_operations_example_3.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_1.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_10.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_11.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_12.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_13.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_14.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_15.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_2.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_3.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_4.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_5.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_6.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_7.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_8.png is excluded by !**/*.png
• puzzles/heap/maximal_score_after_k_operations/images/solution/maximal_score_after_k_operations_solution_9.png is excluded by !**/*.png

📒 Files selected for processing (4)

• DIRECTORY.md (1 hunks)
• puzzles/heap/maximal_score_after_k_operations/README.md (1 hunks)
• puzzles/heap/maximal_score_after_k_operations/__init__.py (1 hunks)
• puzzles/heap/maximal_score_after_k_operations/test_maximal_score.py (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

puzzles/heap/maximal_score_after_k_operations/test_maximal_score.py (1)

puzzles/heap/maximal_score_after_k_operations/__init__.py (1)

• max_score (6-26)

🪛 LanguageTool

puzzles/heap/maximal_score_after_k_operations/README.md

[style] ~53-~53: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 3282 characters long)
Context: ...core_after_k_operations_solution_1.png) ![Solution 14](images/solution/maximal_sc...

(EN_EXCESSIVE_EXCLAMATION)

🪛 markdownlint-cli2 (0.18.1)

DIRECTORY.md

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

(MD007, ul-indent)

---

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

(MD007, ul-indent)

🔇 Additional comments (1)

puzzles/heap/maximal_score_after_k_operations/__init__.py (1)

6-26: LGTM! Clean and efficient heap-based solution.

The implementation correctly uses Python's heapq (min-heap) with negation to simulate a max-heap, efficiently extracting the maximum value in each iteration and reinserting the reduced value. The algorithm matches the documented approach and achieves the expected O(k log n) time complexity.

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (1)

puzzles/heap/maximal_score_after_k_operations/README.md (1)

20-21: Constraint line is now correct.

The duplicate ≤ symbol that was previously flagged has been resolved. Line 21 now correctly displays - 1 ≤ nums[i] ≤ 10^5.

🧹 Nitpick comments (1)

puzzles/heap/maximal_score_after_k_operations/README.md (1)

3-3: Consolidate the redundant problem statement.

Lines 3 and 5–6 both describe the problem setup with slightly different wording. The first sentence in line 3 introduces the operation but then shifts abruptly to the examples. Consolidate these into a single, cohesive problem description to improve clarity and avoid repetition.

Apply this diff to restructure:

- You are given an array of integers nums and an integer k. You want to perform the following operation exactly k times: -  - You are given a 0-indexed array of integer nums and an integer k. Your task is to maximize a score through a series of  - operations. Initially, your score is set to 0 + You are given a 0-indexed array of integers `nums` and an integer `k`. Your task is to maximize a score by performing exactly k operations. Initially, your score is set to 0.

Also applies to: 5-6

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 81c3837 and 221cb26.

📒 Files selected for processing (1)

• puzzles/heap/maximal_score_after_k_operations/README.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

puzzles/heap/maximal_score_after_k_operations/README.md

[style] ~53-~53: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 3281 characters long)
Context: ...core_after_k_operations_solution_1.png) ![Solution 14](images/solution/maximal_sc...

(EN_EXCESSIVE_EXCLAMATION)