{"id":14530981,"url":"https://github.com/mstksg/advent-of-code-dev","last_synced_at":"2025-03-21T00:30:30.160Z","repository":{"id":137482932,"uuid":"161102138","full_name":"mstksg/advent-of-code-dev","owner":"mstksg","description":"Interactive development environment and runner for Advent of Code challenges","archived":false,"fork":false,"pushed_at":"2023-11-30T20:20:10.000Z","size":730,"stargazers_count":26,"open_issues_count":1,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-01T01:02:05.378Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mstksg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-10T01:58:03.000Z","updated_at":"2024-07-03T17:55:24.000Z","dependencies_parsed_at":"2024-10-28T09:24:45.505Z","dependency_job_id":null,"html_url":"https://github.com/mstksg/advent-of-code-dev","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstksg%2Fadvent-of-code-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstksg%2Fadvent-of-code-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstksg%2Fadvent-of-code-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstksg%2Fadvent-of-code-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mstksg","download_url":"https://codeload.github.com/mstksg/advent-of-code-dev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717127,"owners_count":20498280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-05T00:01:11.185Z","updated_at":"2025-03-21T00:30:29.757Z","avatar_url":"https://github.com/mstksg.png","language":"Haskell","funding_links":[],"categories":["Projects"],"sub_categories":["Exercises"],"readme":"The Haskell Advent of Code Development Environment\n==================================================\n\nThis package contains the framework and executable for my [Advent of Code][aoc]\ninteractive development environment and runner/tester/benchmarker.  Networking\npowered by *[advent-of-code-api][]* library.\n\nYou write your solutions in the `AOC.Challenge.DayXX` modules, make sure to\nuncomment the exports, and everything should be good to go for interactive\nrunning, testing, viewing of prompts --- as well as integration into the\nexecutable.\n\n[aoc]: https://adventofcode.com\n[advent-of-code-api]: https://hackage.haskell.org/package/advent-of-code-api\n\nDesigned to only accommodate development for a single year.  If you want to\nwork on multiple years, you should re-fork into a new directory and\nre-configure (and change the executable name).\n\n### `:~\u003e` type\n\nThe solutions expected in terms of a `:~\u003e` record type:\n\n```haskell\ndata a :~\u003e b = MkSol\n    { sParse :: String -\u003e Maybe a    -- ^ parse input into an `a`\n    , sSolve :: a      -\u003e Maybe b    -- ^ solve an `a` input to a `b` solution\n    , sShow  :: b      -\u003e String     -- ^ print out the `b` solution for submission\n    }\n```\n\nAn `a :~\u003e b` is a solution to a challenge expecting input of type `a` and\nproducing answers of type `b`.  It also packs in functions to parse a `String`\ninto an `a`, and functions to show a `b` as a `String` to submit as an answer.\n\nThis is meant to help mentally separate out parsing, solving, and showing,\nallowing for some cleaner code and an easier time planning my solution.\n\nSuch a challenge can be \"run\" on string inputs by feeding the string into\n`sParse`, then `sSolve`, then `sShow`:\n\n```haskell\n-- | Run a ':~\u003e' on some input, retuning 'Maybe'\nrunSolution :: Challenge -\u003e String -\u003e Maybe String\nrunSolution MkSol{..} s = do\n    x \u003c- sParse s\n    y \u003c- sSolve x\n    pure $ sShow y\n```\n\nIn the actual library, I have `runSolution` return an `Either` so I can debug\nwhich stage the error happened in.\n\n`sSolve` also supports `dyno_ :: Typeable a =\u003e String -\u003e a -\u003e a`, which is how\n*special test parameters* are implemented.  For example, 2018 Day 6 involves\nfinding points that had a total distance of less than 10000, but for the test\ninput, we found the points that had a total distance of less than 32.  So,\n`dyno_` allows you to write `dyno_ \"limit\" 10000`.  This will be `10000` when\nrunning on test input, but will be replaced by the \"limit\" key that test data\nis allowed to manually supply. (See [this file][7btest] for reference.)\n\n[7btest]: https://github.com/mstksg/advent-of-code-dev/blob/master/test-data/2018/07b.txt\n\nIt is common to want to use certain common \"utility\" functions between\ndifferent tests.  For this, you can add them to the `AOC.Common` module, and\nthese will be loaded as a part of `AOC.Prelude`.\n\nConfiguration\n------------\n\nWhen you run the `aoc-dev` executable for the first time, it will generate a\ndefault configuration file at `./aoc-conf.yaml`.  At the moment, the\nconfiguration contains two fields:\n\n1.  `session`: the session key.  Allows you to download input data, part 2\n    prompts, and also submit challenges.\n\n    Can be found by logging in on a web client and checking the cookies.  You\n    can usually check these with in-browser developer tools.\n\n2.  `year`: The year you are working on.  Note that this project is designed to\n    only accommodate one \"year\" at a time.  If you want to work on a different\n    year, you should re-fork and start in a new project directory (and change\n    he executable name).  Note that you can re-use session keys between years,\n    provided that they have not expired.\n\nInteractive\n-----------\n\nThe *[AOC.Run.Interactive][interactive]* module has code (powered by\n*[advent-of-code-api][]*) for testing your solutions and submitting within\nGHCI, so you don't have to re-compile. If you edit your solution programs, they\nare automatically updated when you hit `:r` in ghci.\n\n[interactive]: https://mstksg.github.io/advent-of-code-dev/AOC-Run-Interactive.html\n\n```haskell\nghci\u003e execSolution_   $ solSpec 'day02a  -- get answer for challenge based on solution\nghci\u003e testSolution_   $ solSpec 'day02a  -- run solution against test suite\nghci\u003e viewPrompt_     $ solSpec 'day02a  -- view the prompt for a part\nghci\u003e waitForPrompt_  $ solSpec 'day02a  -- count down to the prompt for a part\nghci\u003e submitSolution_ $ solSpec 'day02a  -- submit a solution\n```\n\nThese are loaded with session key stored in the configuration file.\n\nThese identifiers (like `day02a`) need to be exported and in scope for this to\nwork.  If they aren't, you can manually specify the day and part, by using\n`mkCS 2 Part1`, etc.\n\nExecutable\n----------\n\nComes with test examples given in problems.  The executable is named `aoc-dev`\nby default, but it is recommended that you change the name (in `package.yaml`)\nbased on whatever year you are attempting.\n\n```\n$ aoc-dev --help\naoc-dev - Advent of Code 2020 challenge runner\n\nUsage: aoc-dev [-c|--config PATH] COMMAND\n   Run, test, bench, challenges from Advent of Code, and view prompts.\n   Available days: 1, 2, 3 (...)\n\nAvailable options:\n  -c,--config PATH         Path to configuration file (default: aoc-conf.yaml)\n  -h,--help                Show this help text\n\nAvailable commands:\n  run                      Run, test, and benchmark challenges\n  view                     View a prompt for a given challenge\n  submit                   Test and submit answers for challenges\n  test                     Alias for run --test\n  bench                    Alias for run --bench\n  countdown                Alias for view --countdown\n\n$ aoc-dev run 3 b\n\u003e\u003e Day 03b\n\u003e\u003e [✓] 243\n```\n\nYou can supply input via stdin with `--stdin`:\n\n```\n$ aoc-dev run 1 --stdin\n\u003e\u003e Day 01a\n+1\n+2\n+1\n-3\n\u003cCtrl+D\u003e\n[?] 1\n\u003e\u003e Day 01b\n[?] 1\n```\n\nBenchmarking is implemented using *criterion*\n\n```\n$ aoc-dev bench 2\n\u003e\u003e Day 02a\nbenchmarking...\ntime                 1.317 ms   (1.271 ms .. 1.392 ms)\n                     0.982 R²   (0.966 R² .. 0.999 R²)\nmean                 1.324 ms   (1.298 ms .. 1.373 ms)\nstd dev              115.5 μs   (77.34 μs .. 189.0 μs)\nvariance introduced by outliers: 65% (severely inflated)\n\n\u003e\u003e Day 02b\nbenchmarking...\ntime                 69.61 ms   (68.29 ms .. 72.09 ms)\n                     0.998 R²   (0.996 R² .. 1.000 R²)\nmean                 69.08 ms   (68.47 ms .. 69.99 ms)\nstd dev              1.327 ms   (840.8 μs .. 1.835 ms)\n```\n\nTest suites run the example problems given in the puzzle description, and\noutputs are colorized in ANSI terminals.\n\n```\n$ aoc-dev test 1\n\u003e\u003e Day 01a\n[✓] (3)\n[✓] (3)\n[✓] (0)\n[✓] (-6)\n[✓] Passed 4 out of 4 test(s)\n[✓] 416\n\u003e\u003e Day 01b\n[✓] (2)\n[✓] (0)\n[✓] (10)\n[✓] (5)\n[✓] (14)\n[✓] Passed 5 out of 5 test(s)\n[✓] 56752\n```\n\nThis should only work if you're running `aoc-dev` in the project directory.\n\n**To run on actual inputs**, the executable expects inputs to be found in the\nfolder `data/XX.txt` in the directory you are running in.  That is, the input\nfor Day 7 will be expected at `data/07.txt`.\n\nSession keys are required to download input data, \"Part 2\" prompts for each\nchallenge, and also to submit.\n\nYou can \"lock in\" your current answers (telling the executable that those are\nthe correct answers) by passing in `--lock`.  This will lock in any final\npuzzle solutions encountered as the verified official answers.  Later, if you\nedit or modify your solutions, they will be checked on the locked-in answers.\n\nThese are stored in `data/ans/XXpart.txt`.  That is, the target output for Day 7\n(Part 2, `b`) will be expected at `data/ans/07b.txt`.  You can also manually\nedit these files.\n\nYou can view prompts: (use `--countdown` to count down until a prompt is\nreleased, and display immediately)\n\n```\n$ aoc-dev view 3 b\n\u003e\u003e Day 03b\n--- Part Two ---\n----------------\n\nAmidst the chaos, you notice that exactly one claim doesn't overlap by\neven a single square inch of fabric with any other claim. If you can\nsomehow draw attention to it, maybe the Elves will be able to make\nSanta's suit after all!\n\nFor example, in the claims above, only claim `3` is intact after all\nclaims are made.\n\n*What is the ID of the only claim that doesn't overlap?*\n```\n\nYou can also submit answers:\n\n```\n$ aoc-dev submit 1 a\n```\n\nSubmissions will automatically run the test suite.  If any tests fail, you will\nbe asked to confirm submission or else abort.  The submit command will output\nthe result of your submission: The message from the AoC website, and whether or\nnot your answer was correct (or invalid or ignored).  Answers that are\nconfirmed correct will be locked in and saved for future testing against, in\ncase you change your solution.\n\nAll networking features are powered by *[advent-of-code-api][]*.\n\nNote also that `stack test`, `stack bench`, `cabal test`, `cabal bench`, etc.\nare all convenient aliases of `aoc-dev test all` and `aoc-dev bench all`.  This\ncan be useful continuous integration purposes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmstksg%2Fadvent-of-code-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmstksg%2Fadvent-of-code-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmstksg%2Fadvent-of-code-dev/lists"}