feat(algorithms, top k elements): smallest range covering elements from k lists

[BrianLusina]

Describe your change:

Smallest range covering elements from k lists with 3 variations to the solution:

• Using Min Heap(priority queue)
• Using Two pointers
• Using Optimized Brute Force

All the approaches have documentation attached for following along including tests

• 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 algorithm for computing the smallest numeric range covering elements across multiple lists.

• Documentation

  • Added a comprehensive guide detailing the problem, multiple solution approaches, complexity analysis, examples, and visuals.

• Tests

  • Added unit tests covering multiple scenarios and edge cases to validate all implementations produce consistent results.

• Chores

  • Updated directory navigation to include the new algorithm entry.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new "Smallest Range Covering K Lists" problem under Top K Elements with a detailed README, three algorithm implementations (heap, two-pointer, brute-force), and unit tests verifying consistency across implementations.

Changes

Cohort / File(s)	Summary
Navigation DIRECTORY.md	Inserted a new sub-entry "Smallest Range Covering K Lists" under the Top K Elements section.
Documentation algorithms/top_k_elements/smallest_range_covering_k_lists/README.md	New README describing the problem, examples, three solution approaches (Optimal Brute Force, Heap, Two-Pointer), complexity analysis, and illustrative images.
Implementations algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py	Added three functions: smallest_range (min-heap), smallest_range_two_pointer (merge + sliding window), and smallest_range_brute_force (index-tracking brute force).
Tests algorithms/top_k_elements/smallest_range_covering_k_lists/test_smallest_range_covering_elements_from_k_lists.py	New unit tests that parametrize inputs and assert all three implementations produce the same expected range across edge cases and varied list shapes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰✨ I nibble through lists, one by one,
Hunting the smallest span under sun.
Heap, pointers, brute — I tally the scores,
Hopping through ranges and opening doors,
A tiny rabbit finding K-list cures.

🚥 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 specifically describes the main addition: implementing the smallest range covering elements from k lists algorithm within the top k elements category.
Description check	✅ Passed	The description documents the change, confirms three solution approaches with documentation and tests, and completes the required checklist items—only the issue-reference item remains unchecked, which is optional.

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

✨ 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-top-k-elements

---

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

🤖 Fix all issues with AI agents

In `@algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py`:
- Line 58: Typo in the inline comment: change the comment text "# sor the merged
list" to "# sort the merged list" so the comment correctly describes the
following operation (update the comment in __init__.py near the merged list
sorting code).

In `@algorithms/top_k_elements/smallest_range_covering_k_lists/README.md`:
- Line 196: Fix the typo in the README sentence that currently reads "So the
total tim complexity, in the worst case is `O(n log(k))` where n is the total
number of elements across all k lists" by changing "tim" to "time" so it reads
"So the total time complexity, in the worst case is `O(n log(k))` where n is the
total number of elements across all k lists".

🧹 Nitpick comments (2)

algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py (2)

8-9: Unnecessary heapify call on an empty list.

heapq.heapify([]) is a no-op. Since you immediately use heappush in the loop below, this line can be removed.

♻️ Suggested simplification

-    min_heap: List[Tuple[int, int, int]] = []
-    heapq.heapify(min_heap)
+    min_heap: List[Tuple[int, int, int]] = []

---

13-14: Return type List[int] but range_end is initialized to float("inf").

float("inf") is a float, not an int. While the problem constraints guarantee valid input (so the range will always be updated before return), the type annotation -> List[int] is technically violated by the initial value. The same pattern appears in smallest_range_two_pointer (Line 64) and smallest_range_brute_force (Line 93).

Consider using math.inf with an explicit cast or a large sentinel like 10**9 (given the constraint -10^3 <= nums[i][j] <= 10^3, a value like float("inf") works at runtime but misleads type checkers).

Also applies to: 46-47

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py`:
- Line 14: The sentinel float("inf") assigned to variables like range_end and
range_list[1] can leak a float into the declared List[int] return type for
degenerate inputs; add an early guard in the public functions that use these
sentinels (check the input variable nums and that no inner list is empty, e.g.,
in the functions that initialize range_end/range_list) and return an empty list
[] immediately when nums is empty or any inner list is empty; this preserves the
List[int] return type and prevents floats from being returned while leaving the
sentinel logic unchanged for normal cases.

🧹 Nitpick comments (2)

algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py (2)

8-9: Redundant heapify call on an empty list.

heapq.heapify([]) is a no-op. You can drop Line 9.

♻️ Suggested fix

     min_heap: List[Tuple[int, int, int]] = []
-    heapq.heapify(min_heap)

---

1-2: DefaultDict from typing is deprecated since Python 3.9.

You can annotate with collections.defaultdict directly (e.g., freq: defaultdict[int, int]) and drop the DefaultDict import from typing. Low priority.