fix: 2023 solutions

Author: mbrickerd

_2023/solutions/day01.py

@@ -1,6 +1,7 @@
 """Day 1: Trebuchet?!
 
 This module provides the solution for Advent of Code 2023 - Day 1.
+
 It handles extraction of calibration values from strings containing digits
 and written numbers.
 

_2023/solutions/day02.py

@@ -1,6 +1,7 @@
-"""Day 2: Cube Conundrum.
+"""Day 2: Cube Conundrum
 
 This module provides the solution for Advent of Code 2023 - Day 2.
+
 It handles analysis of cube games where colored cubes are drawn from a bag
 in multiple sets, with each game having several draws of red, green, and blue cubes.
 
@@ -59,7 +60,10 @@ def part1(self, data: list[str]) -> int:
         """
         total = 0
         for game in data:
-            game_id = int(re.search(self.id_regex, game).group(1))
+            match = re.search(self.id_regex, game)
+            if match is None:
+                continue
+            game_id = int(match.group(1))
             sets = game.split(":")[1].split(";")
             if all(self.is_possible(s) for s in sets):
                 total += game_id

_2023/solutions/day03.py

@@ -1,6 +1,7 @@
-"""Day 3: Gear Ratios.
+"""Day 3: Gear Ratios
 
 This module provides the solution for Advent of Code 2023 - Day 3.
+
 It handles analysis of engine schematics containing numbers and symbols,
 where valid part numbers are determined by their adjacency to symbols.
 

_2023/solutions/day04.py

@@ -1,4 +1,4 @@
-"""Day 4: Scratchcards.
+"""Day 4: Scratchcards
 
 This module provides the solution for Advent of Code 2023 - Day 4.
 It handles scoring scratchcards where each card has two sets of numbers:

_2023/solutions/day05.py

@@ -1,49 +1,54 @@
-from aoc.models.base import SolutionBase
+"""Day 5: If You Give A Seed A Fertilizer
 
+This module provides the solution for Advent of Code 2023 - Day 5.
 
-class Solution(SolutionBase):
-    """Solution for Advent of Code 2023 - Day 5: If You Give A Seed A Fertilizer.
+It handles mapping seeds through various conversion stages (soil, fertilizer,
+water, light, temperature, humidity, and location). Each stage has mapping
+rules that convert source numbers to destination numbers based on ranges.
+
+The module contains a Solution class that inherits from SolutionBase and implements
+methods to parse input data, convert numbers through mapping stages, and find the
+lowest final location number for both individual seeds and seed ranges.
+"""
+
+from aoc.models.base import SolutionBase
 
-    This class solves a puzzle involving mapping seeds through various conversion stages
-    (soil, fertilizer, water, light, temperature, humidity, and location). Each stage
-    has its own mapping rules that convert source numbers to destination numbers based
-    on ranges.
 
-    Input format:
-        Multiple sections separated by blank lines:
-        - First line: "seeds: " followed by seed numbers
-        - Multiple mapping sections, each starting with a header (e.g., "seed-to-soil map:")
-        - Each mapping section contains lines of three numbers:
-            [destination_start source_start range_length]
+class Solution(SolutionBase):
+    """Process seeds through mapping stages to find lowest location numbers.
 
-    Part 1 processes individual seed numbers through all mappings.
-    Part 2 treats seed numbers as pairs representing ranges (start and length).
+    This solution handles two types of seed processing:
+    Part 1 processes individual seed numbers through all mapping stages.
+    Part 2 treats seed numbers as pairs representing ranges (start and length)
+    and processes entire ranges to find the lowest location.
 
-    This class inherits from `SolutionBase` and provides methods to parse the input,
-    convert numbers through mapping ranges, and find the lowest final location number.
+    The solution uses range-based mappings to efficiently convert numbers through
+    multiple stages of transformations.
     """
 
     def parse_data(
         self, data: list[str], *, use_ranges: bool = False
-    ) -> tuple[list[int], dict[str, list[str]]]:
+    ) -> tuple[list[int] | list[tuple[int, int]], dict[str, list[list[int]]]]:
         """Parse input data into seeds and mapping sections.
 
+        Each line of input is processed to extract seed numbers and mapping rules.
+        The input format includes a seeds line followed by multiple mapping sections,
+        each with a header and range definitions.
+
         Args:
-            data: Raw input lines
-            use_ranges: If True, parse seed numbers as pairs representing ranges
+            data (list[str]): List of strings where each string is a line from the input
+            use_ranges (bool): If True, parse seed numbers as (start, length) pairs
 
         Returns
         -------
-            Tuple of:
-                - seeds: List of individual numbers or list of (start, length)
-                    tuples if `use_ranges=True`
-                - mappings: Dict mapping section names to lists of
-                    [dest_start, source_start, range_len]
+            Tuple containing:
+            - seeds: List of individual numbers or list of (start, length) tuples
+            - mappings: Dict mapping section names to lists of [dest_start, source_start, range_len]
         """
         # Initialize data structures
-        seeds = []
-        mappings = {}
-        current_map = None
+        seeds: list[int] | list[tuple[int, int]] = []
+        mappings: dict[str, list[list[int]]] = {}
+        current_map: str | None = None
 
         for line in data:
             # Skip empty lines
@@ -55,14 +60,13 @@ def parse_data(
                 seed_numbers = [int(x) for x in line.split(":")[1].strip().split()]
                 if use_ranges:
                     # Convert pairs of numbers into (start, length) tuples
-                    seeds = []
-                    for i in range(0, len(seed_numbers), 2):
-                        if i + 1 < len(seed_numbers):  # Ensure we have a pair
-                            seeds.append((seed_numbers[i], seed_numbers[i + 1]))
-
+                    seeds = [
+                        (seed_numbers[i], seed_numbers[i + 1])
+                        for i in range(0, len(seed_numbers), 2)
+                        if i + 1 < len(seed_numbers)
+                    ]
                 else:
                     seeds = seed_numbers
-
                 continue
 
             # Check for new mapping section
@@ -84,36 +88,48 @@ def process_seed_range(
     ) -> int:
         """Process a range of seed numbers to find lowest location number.
 
+        Iterates through each seed in the specified range, mapping it through
+        all conversion stages to find the minimum final location value.
+
         Args:
-            start: Starting seed number
-            length: Length of range to process
-            mappings: Dictionary of mapping ranges for each stage
+            start (int): Starting seed number for the range
+            length (int): Number of seeds in the range
+            mappings (dict[str, list[list[int]]]): Dictionary of mapping ranges for each stage
 
         Returns
         -------
             Lowest location number found in the range
         """
-        lowest_location = float("inf")
+        lowest_location: int | float = float("inf")
 
         # Process each seed in the range
         for seed in range(start, start + length):
             location = self.map_seed(seed, mappings)
             lowest_location = min(lowest_location, location)
 
-        return lowest_location
+        return int(lowest_location)
 
-    def convert(self, num: int, ranges: list[int]) -> int:
+    def convert(self, num: int, ranges: list[list[int]]) -> int:
         """Convert a single number through one mapping section's ranges.
 
+        Checks each range to see if the number falls within its source range.
+        If a match is found, the number is converted to the destination range.
+        If no match is found, the number maps to itself.
+
         Args:
-            num: Number to convert
-            ranges: List of [dest_start, source_start, range_len] mappings
+            num (int): Number to convert
+            ranges (list[list[int]]): List of [dest_start, source_start, range_len] mappings
 
         Returns
         -------
             Converted number, or original number if no range matches
         """
-        for dst_start, src_start, length in ranges:
+        for range_item in ranges:
+            dst_start: int
+            src_start: int
+            length: int
+            dst_start, src_start, length = range_item
+
             if src_start <= num < src_start + length:
                 # Calculate offset from source_start and add to dest_start
                 offset = num - src_start
@@ -122,12 +138,15 @@ def convert(self, num: int, ranges: list[int]) -> int:
         # If no range matches, number maps to itself
         return num
 
-    def map_seed(self, seed: int, mappings: dict[str, list[list[int]]]):
+    def map_seed(self, seed: int, mappings: dict[str, list[list[int]]]) -> int:
         """Process a seed number through all mapping stages.
 
+        Takes an initial seed value and applies each mapping stage in sequence
+        to produce the final location number.
+
         Args:
-            seed: Initial seed number
-            mappings: Dictionary of mapping ranges for each stage
+            seed (int): Initial seed number
+            mappings (dict[str, list[list[int]]]): Dictionary of mapping ranges for each stage
 
         Returns
         -------
@@ -142,16 +161,20 @@ def map_seed(self, seed: int, mappings: dict[str, list[list[int]]]):
         return current_value
 
     def part1(self, data: list[str]) -> int:
-        """Solve part 1: Process individual seed numbers.
+        """Calculate lowest location number from individual seed numbers.
+
+        Processes each seed number through all mapping stages and finds
+        the minimum final location value.
 
         Args:
-            data: Raw input data
+            data (list[str]): List of strings representing the puzzle input
 
         Returns
         -------
             Lowest location number found across all seeds
         """
-        seeds, mappings = self.parse_data(data)
+        seeds_raw, mappings = self.parse_data(data)
+        seeds: list[int] = seeds_raw  # type: ignore[assignment]
 
         locations = set()
         for seed in seeds:
@@ -160,23 +183,26 @@ def part1(self, data: list[str]) -> int:
         return min(locations)
 
     def part2(self, data: list[str]) -> int:
-        """Solve part 2: Process seed numbers as ranges.
+        """Calculate lowest location number from seed ranges.
+
+        Treats seed numbers as pairs representing ranges (start and length).
+        Processes all seeds in each range to find the minimum location.
 
         Args:
-            data: Raw input data
+            data (list[str]): List of strings representing the puzzle input
 
         Returns
         -------
             Lowest location number found across all seed ranges
         """
         # Parse data with ranges enabled
-        seed_ranges, mappings = self.parse_data(data, use_ranges=True)
+        seed_ranges_raw, mappings = self.parse_data(data, use_ranges=True)
+        seed_ranges: list[tuple[int, int]] = seed_ranges_raw  # type: ignore[assignment]
 
         # Find lowest location across all ranges
-        lowest_location = float("inf")
-
+        lowest_location: int | float = float("inf")
         for start, length in seed_ranges:
             range_lowest = self.process_seed_range(start, length, mappings)
             lowest_location = min(lowest_location, range_lowest)
 
-        return lowest_location if lowest_location != float("inf") else None
+        return int(lowest_location) if lowest_location != float("inf") else 0