feat: add word ladder

.templates/leetcode/json/word_ladder.json

@@ -0,0 +1,47 @@
+{
+    "problem_name": "word_ladder",
+    "solution_class_name": "Solution",
+    "problem_number": "127",
+    "problem_title": "Word Ladder",
+    "difficulty": "Hard",
+    "topics": "Hash Table, String, Breadth-First Search",
+    "tags": ["grind-75"],
+    "readme_description": "A **transformation sequence** from word `beginWord` to word `endWord` using a dictionary `wordList` is a sequence of words `beginWord -> s1 -> s2 -> ... -> sk` such that:\n\n- Every adjacent pair of words differs by a single letter.\n- Every `si` for `1 <= i <= k` is in `wordList`. Note that `beginWord` does not need to be in `wordList`.\n- `sk == endWord`\n\nGiven two words, `beginWord` and `endWord`, and a dictionary `wordList`, return the **number of words** in the **shortest transformation sequence** from `beginWord` to `endWord`, or `0` if no such sequence exists.",
+    "readme_examples": [
+        {
+            "content": "```\nInput: beginWord = \"hit\", endWord = \"cog\", wordList = [\"hot\",\"dot\",\"dog\",\"lot\",\"log\",\"cog\"]\nOutput: 5\n```\n**Explanation:** One shortest transformation sequence is \"hit\" -> \"hot\" -> \"dot\" -> \"dog\" -> \"cog\", which is 5 words long."
+        },
+        {
+            "content": "```\nInput: beginWord = \"hit\", endWord = \"cog\", wordList = [\"hot\",\"dot\",\"dog\",\"lot\",\"log\"]\nOutput: 0\n```\n**Explanation:** The endWord \"cog\" is not in wordList, therefore there is no valid transformation sequence."
+        }
+    ],
+    "readme_constraints": "- 1 <= beginWord.length <= 10\n- endWord.length == beginWord.length\n- 1 <= wordList.length <= 5000\n- wordList[i].length == beginWord.length\n- beginWord, endWord, and wordList[i] consist of lowercase English letters.\n- beginWord != endWord\n- All the words in wordList are unique.",
+    "readme_additional": "",
+    "solution_imports": "",
+    "solution_methods": [
+        {
+            "name": "ladder_length",
+            "parameters": "begin_word: str, end_word: str, word_list: list[str]",
+            "return_type": "int",
+            "dummy_return": "0"
+        }
+    ],
+    "test_imports": "import pytest\nfrom leetcode_py.test_utils import logged_test\nfrom .solution import Solution",
+    "test_class_name": "WordLadder",
+    "test_helper_methods": [
+        { "name": "setup_method", "parameters": "", "body": "self.solution = Solution()" }
+    ],
+    "test_methods": [
+        {
+            "name": "test_ladder_length",
+            "parametrize": "begin_word, end_word, word_list, expected",
+            "parametrize_typed": "begin_word: str, end_word: str, word_list: list[str], expected: int",
+            "test_cases": "[('hit', 'cog', ['hot', 'dot', 'dog', 'lot', 'log', 'cog'], 5), ('hit', 'cog', ['hot', 'dot', 'dog', 'lot', 'log'], 0), ('a', 'c', ['a', 'b', 'c'], 2)]",
+            "body": "result = self.solution.ladder_length(begin_word, end_word, word_list)\nassert result == expected"
+        }
+    ],
+    "playground_imports": "from solution import Solution",
+    "playground_test_case": "# Example test case\nbegin_word = 'hit'\nend_word = 'cog'\nword_list = ['hot', 'dot', 'dog', 'lot', 'log', 'cog']\nexpected = 5",
+    "playground_execution": "result = Solution().ladder_length(begin_word, end_word, word_list)\nresult",
+    "playground_assertion": "assert result == expected"
+}

Makefile

@@ -1,5 +1,5 @@
 PYTHON_VERSION = 3.13
-PROBLEM ?= lowest_common_ancestor_of_a_binary_search_tree
+PROBLEM ?= word_ladder
 FORCE ?= 0
 COMMA := ,
 

leetcode/word_ladder/README.md

@@ -0,0 +1,47 @@
+# Word Ladder
+
+**Difficulty:** Hard
+**Topics:** Hash Table, String, Breadth-First Search
+**Tags:** grind-75
+
+**LeetCode:** [Problem 127](https://leetcode.com/problems/word-ladder/description/)
+
+## Problem Description
+
+A **transformation sequence** from word `beginWord` to word `endWord` using a dictionary `wordList` is a sequence of words `beginWord -> s1 -> s2 -> ... -> sk` such that:
+
+- Every adjacent pair of words differs by a single letter.
+- Every `si` for `1 <= i <= k` is in `wordList`. Note that `beginWord` does not need to be in `wordList`.
+- `sk == endWord`
+
+Given two words, `beginWord` and `endWord`, and a dictionary `wordList`, return the **number of words** in the **shortest transformation sequence** from `beginWord` to `endWord`, or `0` if no such sequence exists.
+
+## Examples
+
+### Example 1:
+
+```
+Input: beginWord = "hit", endWord = "cog", wordList = ["hot","dot","dog","lot","log","cog"]
+Output: 5
+```
+
+**Explanation:** One shortest transformation sequence is "hit" -> "hot" -> "dot" -> "dog" -> "cog", which is 5 words long.
+
+### Example 2:
+
+```
+Input: beginWord = "hit", endWord = "cog", wordList = ["hot","dot","dog","lot","log"]
+Output: 0
+```
+
+**Explanation:** The endWord "cog" is not in wordList, therefore there is no valid transformation sequence.
+
+## Constraints
+
+- 1 <= beginWord.length <= 10
+- endWord.length == beginWord.length
+- 1 <= wordList.length <= 5000
+- wordList[i].length == beginWord.length
+- beginWord, endWord, and wordList[i] consist of lowercase English letters.
+- beginWord != endWord
+- All the words in wordList are unique.

leetcode/word_ladder/playground.ipynb

@@ -0,0 +1,81 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from solution import Solution"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "setup",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example test case\n",
+    "begin_word = \"hit\"\n",
+    "end_word = \"cog\"\n",
+    "word_list = [\"hot\", \"dot\", \"dog\", \"lot\", \"log\", \"cog\"]\n",
+    "expected = 5"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "execute",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "5"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "result = Solution().ladder_length(begin_word, end_word, word_list)\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "test",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "assert result == expected"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "leetcode-py-py3.13",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

leetcode/word_ladder/solution.py

@@ -0,0 +1,33 @@
+class Solution:
+    # Time: O(M^2 * N) where M is length of each word, N is total number of words
+    # Space: O(M * N) for the visited sets
+    def ladder_length(self, begin_word: str, end_word: str, word_list: list[str]) -> int:
+        if end_word not in word_list:
+            return 0
+
+        word_set = set(word_list)
+        begin_set = {begin_word}
+        end_set = {end_word}
+        length = 1
+
+        while begin_set and end_set:
+            if len(begin_set) > len(end_set):
+                begin_set, end_set = end_set, begin_set
+
+            next_set = set()
+            for word in begin_set:
+                for i in range(len(word)):
+                    for c in "abcdefghijklmnopqrstuvwxyz":
+                        new_word = word[:i] + c + word[i + 1 :]
+
+                        if new_word in end_set:
+                            return length + 1
+
+                        if new_word in word_set:
+                            next_set.add(new_word)
+                            word_set.remove(new_word)
+
+            begin_set = next_set
+            length += 1
+
+        return 0

leetcode/word_ladder/tests.py

@@ -0,0 +1,42 @@
+import pytest
+
+from leetcode_py.test_utils import logged_test
+
+from .solution import Solution
+
+
+class TestWordLadder:
+    def setup_method(self):
+        self.solution = Solution()
+
+    @pytest.mark.parametrize(
+        "begin_word, end_word, word_list, expected",
+        [
+            # Basic cases
+            ("hit", "cog", ["hot", "dot", "dog", "lot", "log", "cog"], 5),
+            ("hit", "cog", ["hot", "dot", "dog", "lot", "log"], 0),
+            ("a", "c", ["a", "b", "c"], 2),
+            # Edge cases
+            ("hot", "dog", ["hot", "dog"], 0),  # No intermediate words
+            ("hot", "hot", ["hot"], 1),  # Same word
+            ("cat", "dog", [], 0),  # Empty word list
+            ("cat", "dog", ["cat"], 0),  # End word not in list
+            # Single character changes
+            ("a", "b", ["a", "b"], 2),
+            ("ab", "cd", ["ab", "ad", "cd"], 3),
+            # Longer paths
+            ("red", "tax", ["ted", "tex", "red", "tax", "tad", "den", "rex", "pee"], 4),
+            # Multiple possible paths (should return shortest)
+            ("cat", "dog", ["cat", "bat", "bag", "dag", "dog", "cag", "cog"], 4),
+            # No path exists
+            ("abc", "def", ["abc", "def", "ghi"], 0),
+            # Direct transformation
+            ("cat", "bat", ["cat", "bat"], 2),
+            # Longer word length
+            ("word", "form", ["word", "worm", "form", "foam", "flam", "flab"], 3),
+        ],
+    )
+    @logged_test
+    def test_ladder_length(self, begin_word: str, end_word: str, word_list: list[str], expected: int):
+        result = self.solution.ladder_length(begin_word, end_word, word_list)
+        assert result == expected