weaponsforge · weaponsforge · Dec 13, 2024 · Dec 13, 2024 · Dec 13, 2024 · Dec 13, 2024
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Weapons Forge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,14 +1,82 @@
-## adventofcode
+## ✨ adventofcode
 
-Solutions for [Advent of Code](https://adventofcode.com/) event puzzles.
+This repository contains solutions and a local development environment for the [Advent of Code](https://adventofcode.com/) event puzzles.
 
-### Requirements
+### 🎄 Advent of Code Quiz Information
+
+<details>
+<summary><b style="font-size: 24px;">2024</b></summary>
+
+- Day 1: Historian Hysteria [[link]](/src/2024/2024-12-01/README.md)
+
+</details>
+
+### Table of Contents
+
+<details>
+<summary>Click to expand the table of contents</summary>
+
+- [Advent of Code Quiz Information](#-advent-of-code-quiz-information)
+- [Project Folder Structure](#-project-folder-structure)
+- [Requirements](#-requirements)
+- [Installation](#%EF%B8%8F-installation)
+- [Usage](#-usage)
+- [Alternate Usage](#-alternate-usage)
+- [Available Scripts](#-available-scripts)
+
+</details>
+
+## 📚 Project Folder Structure
+
+It follows the directory structure:
+
+> [!NOTE]
+> 📂 dist<br>
+> 📂 src<br>
+> └─ 📂 lib<br>
+> └─ 📂 sample<br>
+> └─ 📂 2024<br>
+> └─── 📂 2024-12-01<br>
+> └───── 📂 lib<br>
+> └───── 📄 input.txt<br>
+> └───── 📄 quiz.ts<br>
+> └───── 📄 quiz.test.ts<br>
+> └───── 📄 sample.test.ts<br>
+> └───── 📄 README.md<br>
+> └─── 📂 2024-12-02<br>
+> └─── 📂 ...<br>
+> └─ 📂 2025<br>
+> └─ 📂 ...<br>
+> └─ 📄 index.ts<br>
+> └─ 📄 ...<br>
+> 📄 README.md
+
+#### Quiz Folders
+
+Each Advent of Code (AOC) event quiz has its folder under **`"/src/<YEAR>/<YYYY-MM-DD>"`** containing:
+- **/lib**: Folder containing main quiz solution logic
+- **input.txt**: Quiz input from AOC
+- **quiz.ts**: Quiz answer(s) validated with AOC
+- **quiz.test.ts**: Test of the correct quiz answers
+- **sample.test.ts**: Minimal sample input with expected correct answers
+- **README.md**: Static copy of the AOC quiz question
+
+#### Other Items
+
+- **/src/lib**: Folder containing generic utility helper functions
+- **/src/dist**: Folder containing the JavaScript files compiled from TypeScript (not committed to the repository)
+- **/src/sample**: Miscellaneous random examples
+- **/src/index.ts**: Exports all solutions to AOC quiz answer functions
+
+### 📋 Requirements
 
 - Node v20.15.0
    - node: 20.15.0
    - npm: 10.7.0
 
-## Installation
+- Docker (optional)
+
+## 🛠️ Installation
 
 1. Clone the repository.
    ```
@@ -20,12 +88,11 @@ Solutions for [Advent of Code](https://adventofcode.com/) event puzzles.
    npm install
    ```
 
-
-## Usage
+## 🚀 Usage
 
 Using Node
 
-1. Run a TypeScript file inside the **/src** directory. For example:
+1. Run a non-test TypeScript file inside the **/src** directory. For example:
 
    ```
    npx vite-node src/sample/sample.ts
@@ -37,7 +104,7 @@ Using Node
    ```
 3. See the [Available Scripts](#available-scripts) section for more information.
 
-## Alternate Usage
+## ⚡ Alternate Usage
 
 Using Docker
 
@@ -61,7 +128,10 @@ Using Docker
    docker run -it -v ${pwd}:/opt/app -v /opt/app/node_modules --rm weaponsforge/adventofcode:dev <AVAILABLE_SCRIPT>
    ```
 
-## Available Scripts
+## 📜 Available Scripts
+
+<details>
+<summary>Click to expand the list of available scripts</summary>
 
 ### `npm run dev`
 
@@ -95,5 +165,8 @@ Fixes TypeScript lint errors.
 
 Runs tests defined in `*.test.ts` files.
 
+</details>
+<br>
+
 @weaponsforge<br>
 20241213
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "adventofcode",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Solutions for Advent of Code https://adventofcode.com/ event puzzles",
   "main": "dist/index.js",
   "type": "module",

diff --git a/src/2024/2024-12-01/README.md b/src/2024/2024-12-01/README.md
@@ -0,0 +1,88 @@
+## Day 1: Historian Hysteria
+
+**Source:** https://adventofcode.com/2024/day/1<br>
+**Status:** Complete
+
+### 📘 Part 1
+
+The Chief Historian is always present for the big Christmas sleigh launch, but nobody has seen him in months! Last anyone heard, he was visiting locations that are historically significant to the North Pole; a group of Senior Historians has asked you to accompany them as they check the places they think he was most likely to visit.
+
+As each location is checked, they will mark it on their list with a star. They figure the Chief Historian must be in one of the first fifty places they'll look, so in order to save Christmas, you need to help them get fifty stars on their list before Santa takes off on December 25th.
+
+Collect stars by solving puzzles. Two puzzles will be made available on each day in the Advent calendar; the second puzzle is unlocked when you complete the first. Each puzzle grants one star. Good luck!
+
+You haven't even left yet and the group of Elvish Senior Historians has already hit a problem: their list of locations to check is currently empty. Eventually, someone decides that the best place to check first would be the Chief Historian's office.
+
+Upon pouring into the office, everyone confirms that the Chief Historian is indeed nowhere to be found. Instead, the Elves discover an assortment of notes and lists of historically significant locations! This seems to be the planning the Chief Historian was doing before he left. Perhaps these notes can be used to determine which locations to search?
+
+Throughout the Chief's office, the historically significant locations are listed not by name but by a unique number called the location ID. To make sure they don't miss anything, The Historians split into two groups, each searching the office and trying to create their own complete list of location IDs.
+
+There's just one problem: by holding the two lists up side by side (your puzzle input), it quickly becomes clear that the lists aren't very similar. Maybe you can help The Historians reconcile their lists?
+
+For example:
+
+```text
+3   4
+4   3
+2   5
+1   3
+3   9
+3   3
+```
+
+Maybe the lists are only off by a small amount! To find out, pair up the numbers and measure how far apart they are. Pair up the smallest number in the left list with the smallest number in the right list, then the second-smallest left number with the second-smallest right number, and so on.
+
+Within each pair, figure out how far apart the two numbers are; you'll need to add up all of those distances. For example, if you pair up a 3 from the left list with a 7 from the right list, the distance apart is 4; if you pair up a 9 with a 3, the distance apart is 6.
+
+In the example list above, the pairs and distances would be as follows:
+
+- The smallest number in the left list is 1, and the smallest number in the right list is 3. The distance between them is 2.
+- The second-smallest number in the left list is 2, and the second-smallest number in the right list is another 3. The distance between them is 1.
+- The third-smallest number in both lists is 3, so the distance between them is 0.
+- The next numbers to pair up are 3 and 4, a distance of 1.
+- The fifth-smallest numbers in each list are 3 and 5, a distance of 2.
+- Finally, the largest number in the left list is 4, while the largest number in the right list is 9; these are a distance 5 apart.
+
+To find the total distance between the left list and the right list, add up the distances between all of the pairs you found. In the example above, this is `2 + 1 + 0 + 1 + 2 + 5`, a total distance of `11`!
+
+Your actual left and right lists contain many location IDs. What is the total distance between your lists?
+
+> **Your puzzle answer was** 2086478.
+
+---
+
+### 📗 Part 2
+
+Your analysis only confirmed what everyone feared: the two lists of location IDs are indeed very different.
+
+Or are they?
+
+The Historians can't agree on which group made the mistakes or how to read most of the Chief's handwriting, but in the commotion you notice an interesting detail: a lot of location IDs appear in both lists! Maybe the other numbers aren't location IDs at all but rather misinterpreted handwriting.
+
+This time, you'll need to figure out exactly how often each number from the left list appears in the right list. Calculate a total similarity score by adding up each number in the left list after multiplying it by the number of times that number appears in the right list.
+
+Here are the same example lists again:
+
+```text
+3   4
+4   3
+2   5
+1   3
+3   9
+3   3
+```
+
+For these example lists, here is the process of finding the similarity score:
+
+- The first number in the left list is `3`. It appears in the right list three times, so the similarity score increases by `3 * 3 = 9`.
+- The second number in the left list is `4`. It appears in the right list once, so the similarity score increases by `4 * 1 = 4`.
+- The third number in the left list is `2`. It does not appear in the right list, so the similarity score does not increase `(2 * 0 = 0)`.
+- The fourth number, `1`, also does not appear in the right list.
+- The fifth number, `3`, appears in the right list three times; the similarity score increases by `9`.
+- The last number, `3`, appears in the right list three times; the similarity score again increases by `9`.
+
+So, for these example lists, the similarity score at the end of this process is `31 (9 + 4 + 0 + 0 + 9 + 9)`.
+
+Once again consider your left and right lists. What is their similarity score?
+
+> **Your puzzle answer was** 24941624.