feat: update

Author: wislertt

.templates/leetcode/examples/README.md

@@ -1,77 +1,71 @@
-# LeetCode Problem Template Examples
+# LeetCode Template Examples
 
-These JSON5 files serve as reference templates for creating new LeetCode problems. Each template is designed to help LLMs parse raw problem text from leetcode.com into the correct JSON format.
+Reference templates for creating new LeetCode problems. **Copy from these examples** - don't create from scratch.
 
-## Template Types
+## Usage
 
-### 1. `basic.json5` - Array/Number Problems
+1. **Choose the right template** based on problem type
+2. **Copy the entire structure** to `.templates/leetcode/json/{question_name}.json`
+3. **Update all fields** with your problem's data
+4. **Generate**: `make q-gen QUESTION=your_question`
 
-- **Use for**: Array manipulation, hash table, basic algorithms
-- **Examples**: Two Sum, Contains Duplicate, Product of Array Except Self
-- **Key features**: Simple parameters, basic return types, no special imports
+## Templates
 
-### 2. `tree.json5` - Binary Tree Problems
+### `basic.json5`
 
-- **Use for**: Binary tree traversal, tree manipulation, tree construction
-- **Examples**: Invert Binary Tree, Maximum Depth, Validate BST
-- **Key features**: TreeNode import, array-to-tree conversion, tree-specific logging
+- **Use for**: Array, string, number, hash table problems
+- **Examples**: Two Sum, Valid Anagram, Contains Duplicate
+- **Features**: Simple parameters, direct assertions
 
-### 3. `linked_list.json5` - Linked List Problems
+### `tree.json5`
 
-- **Use for**: Singly linked list manipulation, list reversal, merging
-- **Examples**: Reverse Linked List, Merge Two Lists, Remove Nth Node
-- **Key features**: ListNode import, array-to-list conversion, multiple parameters
+- **Use for**: Binary tree problems
+- **Examples**: Invert Binary Tree, Maximum Depth, Same Tree
+- **Features**: TreeNode import, array-to-tree conversion, tree logging
 
-### 4. `string.json5` - String Problems
+### `linked_list.json5`
 
-- **Use for**: String manipulation, validation, parsing
-- **Examples**: Valid Parentheses, Longest Substring, Palindrome Check
-- **Key features**: String parameters, boolean returns, validation patterns
+- **Use for**: Linked list problems
+- **Examples**: Reverse Linked List, Merge Two Lists, Cycle Detection
+- **Features**: ListNode import, array-to-list conversion, list logging
 
-### 5. `matrix.json5` - 2D Array/Matrix Problems
+### `string.json5`
 
-- **Use for**: Matrix operations, 2D array manipulation, grid problems
-- **Examples**: Rotate Image, Spiral Matrix, Set Matrix Zeroes
-- **Key features**: 2D list types, in-place modifications, deep copy for testing
-
-## Usage Instructions
+- **Use for**: String manipulation problems
+- **Examples**: Valid Palindrome, Longest Substring, Anagrams
+- **Features**: String parameters, boolean/string returns
 
-1. **Choose the appropriate template** based on the problem's primary data structure
-2. **Copy the template structure** and fill in the specific problem details
-3. **Follow the comments** for guidance on each field
-4. **Use modern Python syntax** (e.g., `list[int]` instead of `List[int]`)
-5. **Test the generated JSON** with `make q-gen QUESTION=your_problem`
+### `matrix.json5`
 
-## Key Conventions
+- **Use for**: 2D array/matrix problems
+- **Examples**: Rotate Image, Spiral Matrix, Set Matrix Zeroes
+- **Features**: Matrix parameters, in-place operation testing
 
-- **Naming**: Use snake_case for `question_name` and `method_name`, PascalCase for `class_name`
-- **Types**: Use modern Python type hints (`list[int]`, `TreeNode | None`)
-- **Parameters**: Match the exact parameter names from the LeetCode method signature
-- **Test Cases**: Use the same data format as the examples (arrays for trees/lists)
-- **Imports**: Only include necessary imports (`TreeNode`, `ListNode`, etc.)
+## Key Fields
 
-## Common Patterns
+### Required Core Fields
 
-### Return Types & Dummy Returns
+- `question_name`, `class_name`, `method_name`
+- `problem_number`, `problem_title`, `difficulty`, `topics`
+- `problem_description`, `examples`, `constraints`
+- `parameters`, `return_type`, `dummy_return`
 
-- `bool` → `"False"`
-- `int` → `"0"`
-- `str` → `"\"\""`
-- `list[int]` → `"[]"`
-- `TreeNode | None` → `"None"`
-- `ListNode | None` → `"None"`
+### Test Configuration
 
-### Test Parameter Naming
+- `test_cases`: Array of `{args, expected}` objects
+- `param_names`: Parameter names for test methods
+- `test_setup`: Code to convert test data (e.g., arrays to TreeNode)
+- `assertion_code`: How to compare result with expected
 
-- **Basic problems**: `param1, param2, expected`
-- **Tree problems**: `root_list, expected_list` (converts arrays to TreeNode)
-- **Linked List problems**: `head_list, param2, expected_list` (converts arrays to ListNode)
+### Notebook Setup
 
-### Test Setup Patterns
+- `test_input_setup`: Code for notebook input cell
+- `expected_output_setup`: Code for notebook expected cell
+- `imports`: Required imports (TreeNode, ListNode, etc.)
 
-- **Basic**: No setup needed (`""`)
-- **Tree**: `"root = TreeNode.from_list(root_list)\\nexpected = TreeNode.from_list(expected_list)"`
-- **Linked List**: `"head = ListNode.from_list(head_list)\\nexpected = ListNode.from_list(expected_list)"`
-- **Matrix (in-place)**: `"import copy\\noriginal_matrix = copy.deepcopy(matrix)"`
+## Rules
 
-These templates ensure consistency and proper integration with the existing test framework and validation system.
+1. **Copy structure exactly** - all fields are required
+2. **Use modern Python syntax**: `list[int]`, `TreeNode | None`
+3. **Match existing patterns** - see current JSON files for reference
+4. **Test thoroughly** - run `make lint` and `make q-test` after generation

.templates/leetcode/examples/basic.json5

@@ -2,59 +2,57 @@
   // Basic problem template for array/string/number problems
   // Copy this structure when creating new basic problems
 
-  // REQUIRED: Core identifiers (snake_case for question_name, PascalCase for class_name)
-  "question_name": "two_sum",           // Snake case from problem title
-  "class_name": "TwoSum",               // PascalCase version
-  "method_name": "two_sum",             // Snake case method name
+  // REQUIRED: Core identifiers
+  "question_name": "two_sum",
+  "class_name": "TwoSum",
+  "method_name": "two_sum",
 
-  // REQUIRED: Problem metadata (copy directly from LeetCode)
-  "problem_number": "1",                // String number from URL
-  "problem_title": "Two Sum",           // Exact title from LeetCode
-  "difficulty": "Easy",                 // Easy|Medium|Hard
-  "topics": "Array, Hash Table",        // Comma-separated from LeetCode tags
+  // REQUIRED: Problem metadata
+  "problem_number": "1",
+  "problem_title": "Two Sum",
+  "difficulty": "Easy",
+  "topics": "Array, Hash Table",
 
-  // OPTIONAL: Problem categorization tags
-  "tags": ["grind-75"],                 // Popular lists: grind-75, blind-75, neetcode-150, top-interview
+  // OPTIONAL: Problem categorization
+  "tags": ["grind-75"],
 
-  // REQUIRED: Problem description (copy full description from LeetCode)
+  // REQUIRED: Problem description
   "problem_description": "Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.",
 
-  // REQUIRED: Examples (copy from LeetCode, keep input/output as strings)
+  // REQUIRED: Examples
   "examples": [
     { "input": "nums = [2,7,11,15], target = 9", "output": "[0,1]" },
     { "input": "nums = [3,2,4], target = 6", "output": "[1,2]" },
     { "input": "nums = [3,3], target = 6", "output": "[0,1]" }
   ],
 
-  // REQUIRED: Constraints (copy exactly from LeetCode with \n for line breaks)
+  // REQUIRED: Constraints
   "constraints": "- 2 <= nums.length <= 10^4\n- -10^9 <= nums[i] <= 10^9\n- -10^9 <= target <= 10^9\n- Only one valid answer exists.",
 
-  // REQUIRED: Method signature components
-  "parameters": "nums: list[int], target: int",    // Modern Python type hints
-  "return_type": "list[int]",                      // Return type with modern syntax
-  "dummy_return": "[]",                            // Default return for TODO implementation
+  // REQUIRED: Method signature
+  "parameters": "nums: list[int], target: int",
+  "return_type": "list[int]",
+  "dummy_return": "[]",
 
-  // REQUIRED: Import statements (empty for basic problems, specify for TreeNode/ListNode)
+  // REQUIRED: Imports (empty for basic problems)
   "imports": "",
 
-  // REQUIRED: Test configuration
+  // REQUIRED: Test cases
   "test_cases": [
     { "args": [[2, 7, 11, 15], 9], "expected": [0, 1] },
     { "args": [[3, 2, 4], 6], "expected": [1, 2] },
     { "args": [[3, 3], 6], "expected": [0, 1] }
   ],
 
-  // REQUIRED: Test method parameters (use expected, not expected_list for basic problems)
+  // REQUIRED: Test configuration
   "param_names": "nums, target, expected",
   "param_names_with_types": "nums: list[int], target: int, expected: list[int]",
-
-  // REQUIRED: Test setup and logging
   "input_description": "nums={nums}, target={target}",
   "input_params": "nums, target",
   "expected_param": "expected",
   "method_args": "nums, target",
-  "test_setup": "",                                // Empty for basic problems
-  "test_logging": "",                              // Empty for default logging
+  "test_setup": "",
+  "test_logging": "",
   "assertion_code": "assert result == expected",
 
   // REQUIRED: Notebook setup

.templates/leetcode/examples/linked_list.json5

@@ -1,25 +1,25 @@
 {
-  // Linked List problem template for ListNode problems
-  // Use this for problems involving singly linked lists
+  // Linked list problem template
+  // Use this for problems involving ListNode structures
 
   // REQUIRED: Core identifiers
-  "question_name": "reverse_linked_list_ii",   // Snake case from problem title
-  "class_name": "ReverseLinkedListII",         // PascalCase version
-  "method_name": "reverse_between",            // Method name from problem (often different from title)
+  "question_name": "reverse_linked_list_ii",
+  "class_name": "ReverseLinkedListII",
+  "method_name": "reverse_between",
 
   // REQUIRED: Problem metadata
-  "problem_number": "92",                      // String number from LeetCode URL
-  "problem_title": "Reverse Linked List II",  // Exact title from LeetCode
-  "difficulty": "Medium",                      // Easy|Medium|Hard
-  "topics": "Linked List",                     // From LeetCode tags
+  "problem_number": "92",
+  "problem_title": "Reverse Linked List II",
+  "difficulty": "Medium",
+  "topics": "Linked List",
 
   // OPTIONAL: Problem categorization
-  "tags": [],                                  // Add if part of popular lists
+  "tags": [],
 
   // REQUIRED: Problem description
   "problem_description": "Given the head of a singly linked list and two integers left and right where left <= right, reverse the nodes of the list from position left to position right, and return the reversed list.",
 
-  // REQUIRED: Examples (linked list problems show array representation)
+  // REQUIRED: Examples
   "examples": [
     { "input": "head = [1,2,3,4,5], left = 2, right = 4", "output": "[1,4,3,2,5]" },
     { "input": "head = [5], left = 1, right = 1", "output": "[5]" }
@@ -28,15 +28,15 @@
   // REQUIRED: Constraints
   "constraints": "- The number of nodes in the list is n.\n- 1 <= n <= 500\n- -500 <= Node.val <= 500\n- 1 <= left <= right <= n",
 
-  // REQUIRED: Method signature (ListNode | None for nullable, multiple parameters common)
+  // REQUIRED: Method signature
   "parameters": "head: ListNode | None, left: int, right: int",
   "return_type": "ListNode | None",
   "dummy_return": "None",
 
   // REQUIRED: ListNode import for linked list problems
   "imports": "from leetcode_py.list_node import ListNode",
 
-  // REQUIRED: Test cases (use array representation, multiple args common)
+  // REQUIRED: Test cases
   "test_cases": [
     { "args": [[1, 2, 3, 4, 5], 2, 4], "expected": [1, 4, 3, 2, 5] },
     { "args": [[5], 1, 1], "expected": [5] },
@@ -46,14 +46,12 @@
   // REQUIRED: Test parameters (use expected_list for linked list problems)
   "param_names": "head_list, left, right, expected_list",
   "param_names_with_types": "head_list: list[int], left: int, right: int, expected_list: list[int]",
-
-  // REQUIRED: Test configuration for linked list problems
   "input_description": "head_list={head_list}, left={left}, right={right}",
-  "input_params": "head, left, right",      // Actual parameters passed to method
-  "expected_param": "expected",             // ListNode object for assertion
+  "input_params": "head, left, right",
+  "expected_param": "expected",
   "method_args": "head, left, right",
 
-  // REQUIRED: Linked list specific test setup (converts arrays to ListNode objects)
+  // REQUIRED: Linked list-specific test setup
   "test_setup": "head = ListNode.from_list(head_list)\nexpected = ListNode.from_list(expected_list)",
   "test_logging": "logger.success(f\"Got result: {result.to_list() if result else []}\")",
   "assertion_code": "assert result == expected",

.templates/leetcode/examples/matrix.json5

@@ -1,25 +1,25 @@
 {
-  // Matrix/2D Array problem template
-  // Use this for problems involving 2D arrays or matrices
+  // Matrix problem template
+  // Use this for 2D array/matrix problems
 
   // REQUIRED: Core identifiers
-  "question_name": "rotate_image",             // Snake case from problem title
-  "class_name": "RotateImage",                 // PascalCase version
-  "method_name": "rotate",                     // Method name from problem
+  "question_name": "rotate_image",
+  "class_name": "RotateImage",
+  "method_name": "rotate",
 
   // REQUIRED: Problem metadata
-  "problem_number": "48",                      // String number from LeetCode URL
-  "problem_title": "Rotate Image",            // Exact title from LeetCode
-  "difficulty": "Medium",                      // Easy|Medium|Hard
-  "topics": "Array, Math, Matrix",             // From LeetCode tags
+  "problem_number": "48",
+  "problem_title": "Rotate Image",
+  "difficulty": "Medium",
+  "topics": "Array, Math, Matrix",
 
   // OPTIONAL: Problem categorization
-  "tags": ["grind-75"],                        // Popular algorithm lists
+  "tags": ["grind-75"],
 
   // REQUIRED: Problem description
-  "problem_description": "You are given an n x n 2D matrix representing an image, rotate the image by 90 degrees (clockwise).",
+  "problem_description": "You are given an n x n 2D matrix representing an image, rotate the image by 90 degrees (clockwise).\n\nYou have to rotate the image in-place, which means you have to modify the input 2D matrix directly. DO NOT allocate another 2D matrix and do the rotation.",
 
-  // REQUIRED: Examples (matrix problems show 2D array representation)
+  // REQUIRED: Examples
   "examples": [
     { "input": "matrix = [[1,2,3],[4,5,6],[7,8,9]]", "output": "[[7,4,1],[8,5,2],[9,6,3]]" },
     { "input": "matrix = [[5,1,9,11],[2,4,8,10],[13,3,6,7],[15,14,12,16]]", "output": "[[15,13,2,5],[14,3,4,1],[12,6,8,9],[16,7,10,11]]" }
@@ -28,36 +28,32 @@
   // REQUIRED: Constraints
   "constraints": "- n == matrix.length == matrix[i].length\n- 1 <= n <= 20\n- -1000 <= matrix[i][j] <= 1000",
 
-  // REQUIRED: Method signature (2D list type hint)
+  // REQUIRED: Method signature
   "parameters": "matrix: list[list[int]]",
-  "return_type": "None",                       // Many matrix problems modify in-place
+  "return_type": "None",
   "dummy_return": "None",
 
-  // REQUIRED: Import statements (empty for basic matrix problems)
+  // REQUIRED: Imports (empty for matrix problems)
   "imports": "",
 
-  // REQUIRED: Test cases (2D arrays as input, None or modified matrix as expected)
+  // REQUIRED: Test cases (for in-place operations, test the modified matrix)
   "test_cases": [
     { "args": [[[1,2,3],[4,5,6],[7,8,9]]], "expected": [[7,4,1],[8,5,2],[9,6,3]] },
     { "args": [[[5,1,9,11],[2,4,8,10],[13,3,6,7],[15,14,12,16]]], "expected": [[15,13,2,5],[14,3,4,1],[12,6,8,9],[16,7,10,11]] }
   ],
 
-  // REQUIRED: Test parameters (matrix for input, expected for result)
+  // REQUIRED: Test configuration
   "param_names": "matrix, expected",
   "param_names_with_types": "matrix: list[list[int]], expected: list[list[int]]",
-
-  // REQUIRED: Test configuration for matrix problems
   "input_description": "matrix={matrix}",
   "input_params": "matrix",
   "expected_param": "expected",
   "method_args": "matrix",
+  "test_setup": "",
+  "test_logging": "",
+  "assertion_code": "assert matrix == expected",
 
-  // REQUIRED: Matrix-specific test setup (for in-place modification problems)
-  "test_setup": "import copy\noriginal_matrix = copy.deepcopy(matrix)",
-  "test_logging": "logger.success(f\"Got result: {matrix}\")",
-  "assertion_code": "assert matrix == expected",  // Compare modified matrix
-
-  // REQUIRED: Notebook setup for matrix problems
+  // REQUIRED: Notebook setup
   "test_input_setup": "# Example test case\nmatrix = [[1,2,3],[4,5,6],[7,8,9]]",
   "expected_output_setup": "expected = [[7,4,1],[8,5,2],[9,6,3]]"
 }