🎄 Advent of Code Team Monorepo

Welcome to our team's Advent of Code solutions! This repository is configured as a TypeScript + Bun monorepo, designed to let us code together, compare solutions, and race for the fastest execution times.

🚀 Getting Started

1. Install Bun

This repo uses Bun for lightning-fast installs and running.

# MacOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

2. Setup the Repository

Clone the repo and install dependencies:

git clone <repo-url>
cd aoc-team
bun install

3. Configure Your Environment (Crucial!)

You need to authenticate with Advent of Code to fetch your puzzle inputs automatically.

1. Copy the example env file:

   cp .env.example .env

2. Get your Session Cookie:

   • Log in to Advent of Code.
   • Right-click anywhere on the page and select Inspect.
   • Go to the Application tab (Chrome) or Storage tab (Firefox).
   • Expand Cookies in the sidebar and click on https://adventofcode.com.
   • Copy the value of the session cookie.

3. Edit .env:

   • Paste the cookie into AOC_SESSION.
   • Set AOC_USER to your preferred username (e.g., alice). This will be your folder name in src/.

🛠️ Daily Workflow

1. Scaffold a Day

Generate the boilerplate and download your puzzle input in one go:

bun run gen <day> [year]
# Example: bun run gen 1 2024

• Day folders are always zero-padded (day01, day02, ...).
• scripts/scaffold.ts refuses to overwrite an existing folder, creates index.ts, index.test.ts, and input.txt, then populates the input via your AOC_SESSION.
• The default year is the current calendar year; pass an explicit year to backfill older puzzles.

2. Code with the Watch Runner

Use the fast watch runner that wraps bun test --watch with smart filtering from scripts/dev.ts:

Scope	Command	Notes
Watch everything I have	bun run dev	Scans src/<AOC_USER> across all years.
Watch a single day	bun run dev 7	Accepts 7 or 07; discovers all matching years automatically.

If AOC_USER is missing the script exits early, so double-check your .env.

3. Run Targeted Suites on Demand

We now rely directly on the native Bun test runner (bun test). It understands globs and directories, so you can mix and match filters as needed:

Scenario	Command
Run my entire workspace	bun test src/$AOC_USER
Run my Day 05 once	bun test src/$AOC_USER/**/day05/**
Watch my Day 05	bun test --watch src/$AOC_USER/**/day05/**
Run Day 05 for everyone	bun test **/day05/**
Run everything for everyone	bun test

• Append --watch to keep bun test hot-reloading.
• Filters accept either padded (05) or non-padded (5) folder names; stick with the padded convention to match the scaffold.
• CI uses the same bun test command via the test npm script.

4. Get the Star

1. Paste the example input into index.test.ts (the template already contains the right hooks).

2. Iterate until the Example test passes in watch mode.

3. Check the Real Input test output to grab your answers.

4. Submit the numbers to Advent of Code, then persist them inside the real object so future runs assert against the truth:

   const real = {
     input: await readFile(new URL('./input.txt', import.meta.url), 'utf8'),
     solution1: '12345',
     solution2: '67890'
   }

   The scaffolded tests already compare part1/part2 against real.solution1/solution2, so once you update those strings the suite will fail anytime you regress.

5. Race the Leaderboard

bun run bench <day> [year]
# Example: bun run bench 5

scripts/bench.ts performs three phases:

1. Host verification – runs bun test src/<AOC_USER>/<year>/dayXX to make sure your solution is green before trusting it.
2. Validation – loads every other teammate’s implementation for that day/year and confirms their answers match yours.
3. Benchmarking – uses mitata to print p50/p75/p99 timings with your solution as the baseline.

Only solutions that match your answers enter the race, and disagreements are surfaced with a consensus warning.

📂 Repository Structure

src/
├── utils/           # Shared helpers (Graph algos, Grids, Math)
├── alice/           # Alice's solutions
├── bob/             # Bob's solutions
└── ...

Feel free to add shared utilities to src/utils/ if you write a helper that the team could use!

📜 Scripts Reference

Command	Description
bun run gen <day> [year]	Scaffold + download input for the day.
bun run dev [day]	Watch mode for your workspace (optional day filter).
bun test [path/glob]	Native Bun test runner (use globs for filtering + --watch).
bun run bench <day> [year]	Validate and benchmark every implementation.
bun run format	Format everything with Prettier.