How nitekat1124/advent-of-code-2024 works
Project Type and Purpose
• This is an open-source, command-line tool written in Python3 that automates solving Advent of Code puzzles, running tests, benchmarking, and submitting answers.
• Key features:
• A single entry point (app.py) that parses command-line args.
• A “solutions” directory of day-by-day puzzle implementations.
• A “utils” library for file I/O, puzzle input parsing, test harness, and submission logic.
File Structure
• Top-level files:
• .gitignore, LICENSE, README.md — project metadata.
• app.py — CLI interface and orchestration.
• “solutions” directory:
• solution modules: day01.py … day25.py. Each implements solve(part1/part2).
• “utils” directory:
• files.py — reading/writing files.
• puzzle_reader.py — downloads or loads puzzle input.
• solution_base.py — base classes or loading logic for solutions.
• submission.py — handles answer submission to Advent of Code.
README for Additional Insights
• It documents the usage of app.py, the available CLI flags, and the expected workflow:
1) A new day, 2) run tests, 3) benchmark, 4) submit answer.
Main Components
a. CLI Layer (app.py)
• Argparse-based parser that triggers commands: add, run, test, benchmark, submit.
b. Solution Loader (solution_base.py)
• Dynamically discovers and instantiates the correct day’s solution class.
c. Puzzle Input Manager (puzzle_reader.py + files.py)
• Retrieves raw or stored input for the current day.
d. Test Harness (utils/solution_base.py + built-in unittest or custom runner)
• Executes sample tests before real input.
e. Benchmark Engine (part of CLI logic)
• Times execution, optionally skips tests.
f. Submission Module (submission.py)
• Posts answers to the Advent of Code website via HTTP.
g. Solution Modules (solutions/dayXX.py)
• Pure puzzle logic, implements two parts.
Relationships and Data Flows
• User → app.py (CLI)
• app.py → solution_base loads Solution(day, part)
• Solution → puzzle_reader → files (local cache) or AoC Website
• Solution runs logic on input → returns answer
• CLI → test harness (optional) → validate solution output
• CLI → benchmark module (optional) → measure performance
• CLI → submission module → HTTP POST → AoC Website
Key Architectural Patterns & Principles
• Plugin/Module Discovery: dayXX.py files are auto-loaded based on day argument.
• Separation of Concerns:
• CLI orchestration vs. puzzle logic vs. I/O vs. submission.
• Extensibility:
• Adding a new day is “add” command + drop‐in solution file.
• Reusability:
• Utility modules abstract file handling, HTTP submission, timer.
Technologies & Frameworks to Call Out
• Python 3.x
• argparse (built-in) for CLI
• requests or http.client for web submission
• unittest or custom assertion logic for testing
• importlib for dynamic module loading
Detailed Checklist
• [ ] CLI Entry Point (app.py)
• [ ] Argument Parser & Command Dispatcher
• [ ] SolutionBase / Module Loader
• [ ] Solutions Directory (25 day modules)
• [ ] Puzzle Reader & File System Cache
• [ ] Test Harness & Benchmark Component
• [ ] Submission Component & HTTP Flow
• [ ] External Service: AoC Website
• [ ] Data flows: input request, answer output, submission request