How atesgoral/hrm-solutions works
1. This repository is primarily a curated archive of Human Resource Machine assembly solutions, plus a thin static-site and CI layer around that content. The core “application data” is the solutions/ tree, not a traditional source codebase.
2. solutions/ is organized by puzzle level. Each level has a folder named like <level>-<level name>-<size par>.<speed par>, and inside are multiple .asm files representing different submissions/variants. The filename encodes the achieved size and speed, optional strategy/type tags, and the author.
3. The .asm files are the main payload: they are Human Resource Machine programs in the game’s assembly-like syntax. Many levels contain multiple approaches for comparison, including “specific”, “unroll”, “exploit”, “obsolete”, and other strategy labels.
4. The repo also carries contributor metadata in contributors.json. Combined with the filenames, this supports attribution and presentation of who authored each solution in the site/README ecosystem.
5. The top-level index.html suggests a browser-facing static site. The README links to a GitHub Pages deployment for “Top Scores and more info,” so the site likely renders or indexes the solution set for browsing rather than serving dynamic application logic.
6. gulpfile.js is the build orchestration layer. It likely bundles, copies, or transforms the content into the static site published by GitHub Pages. This is the repo’s main build boundary: source content in solutions/ becomes a browsable site artifact.
7. CI/CD is handled through GitHub Actions. test.yml runs validation on pull requests, while build-and-deploy.yml publishes the site. That creates a clear separation between contributor-facing verification and release/deployment to GitHub Pages.
8. The testing pipeline is architecture-significant because it validates the solution corpus, not just code style. The README states tests perform static/runtime analysis and benchmarking, so correctness and performance are both first-class constraints.
9. The test stack depends on external HRM-specific tooling: hrm-parser for static analysis, hrm-cpu for execution/runtime analysis, hrm-level-data for puzzle constraints, and inbox/outbox generators for benchmark inputs and expected outputs. These tools are what turn the solution archive into an automatically checked dataset.
10. Data flow is roughly: puzzle metadata and generated inboxes feed the test harness; each .asm solution is parsed and executed against the level constraints; results determine pass/fail and performance; the validated content is then packaged for the static site and deployed.
11. The project boundaries are therefore: content repository at the center, validation tooling around it, and a static publication layer on top. There is no server-side runtime, database, or API in this repo; the only “live” external dependencies are GitHub Actions/GitHub Pages and the HRM analysis libraries.
12. Practical diagram takeaway: show a large content store of level folders and assembly files, a contributor metadata file, a Node/Yarn-based test/benchmark pipeline using HRM tooling, and a build/deploy path from that verified corpus to a GitHub Pages-hosted static index.
Main entry points: package.json Package config · test.yml Test CI · solutions ASM files · contributors.json Contributors
Components 18
Solution Archive
Curated Human Resource Machine level folders and assembly submissions.
- Solutions · Top-level archive of level folders and `.asm` submissions.
solutions - Level folders · Per-level directories grouping variants for each HRM puzzle.
solutions - ASM files · Human Resource Machine assembly solutions and strategy variants.
solutions - Strategy tags · Encoded labels such as specific, unroll, exploit, obsolete, and similar approaches.
solutions
Metadata
Contributor attribution and repository-facing presentation data.
- Contributors · Author metadata used to resolve names and present credits.
contributors.json - README · Repository overview and link hub for browsing, testing, and deployment.
README.md
Validation
Static analysis, runtime execution, and benchmarking of solutions.
- Test CI · Pull-request validation workflow.
.github/workflows/test.yml - Parser · Parses HRM assembly for structural checks.
- CPU runner · Executes solutions to validate behavior and performance.
- Level data · Puzzle-specific constraints and expectations used by tests.
- I/O generators · Inbox and outbox generation for automated test cases.
- Checks · Static validation of solution structure and legality.
- Benchmarks · Runtime and performance measurement across solution variants.
Build & Delivery
Static-site generation and GitHub Pages deployment.
- Index page · Browser-facing landing page for the solution archive.
index.html - Gulp build · Build pipeline for packaging the archive into a publishable static site.
gulpfile.js - Package config · Node/Yarn scripts and dependency boundary for build and test tooling.
package.json - Deploy CI · Build-and-deploy workflow for GitHub Pages publishing.
.github/workflows/build-and-deploy.yml - Pages site · Static browsable site generated from the verified archive.
Connections 20
- Solutions → Level folders: organizes · Archive is partitioned into per-level folders.
- Level folders → ASM files: contains · Each level directory stores multiple solution submissions.
- ASM files → Strategy tags: encoded by · Filenames capture size, speed, strategy, and author.
- Contributors → ASM files: attributes · Contributor metadata supports author presentation for solutions.
- README → Index page: points to · README directs users to the browsable site and scores.
- Package config → Gulp build: drives · Package scripts wire up build orchestration.
- Package config → Test CI: installs · CI uses the Node/Yarn dependency set.
- Package config → Deploy CI: installs · Deployment workflow relies on the same package boundary.
- Test CI → Checks: runs · PR validation invokes repository checks.
- Test CI → Benchmarks: runs · PR validation includes runtime and performance evaluation.
- Checks → Parser: uses · Structural validation is performed with the HRM parser.
- Checks → Level data: uses · Parsing checks are constrained by puzzle metadata.
- Benchmarks → CPU runner: uses · Solution execution is performed by the HRM CPU runner.
- Benchmarks → I/O generators: uses · Benchmarks consume generated inbox/outbox cases.
- Benchmarks → Level data: uses · Runtime checks are bounded by level-specific rules.
- Gulp build → Pages site: builds · Build step packages the archive into a browsable artifact.
- Index page → Pages site: served as · Landing page is part of the published site.
- Deploy CI → Pages site: deploys · GitHub Actions publishes the static site to Pages.
- Pages site → Solutions: indexes · Published site presents the validated solution corpus.
- Pages site → Contributors: displays · Published views can surface author attribution.