{"id":51115111,"url":"https://github.com/fullofcaffeine/reflaxe.ruby","last_synced_at":"2026-06-24T21:01:10.511Z","repository":{"id":365323269,"uuid":"1265437586","full_name":"fullofcaffeine/reflaxe.ruby","owner":"fullofcaffeine","description":"Experimental Haxe-\u003eRuby/Rails compiler","archived":false,"fork":false,"pushed_at":"2026-06-16T20:40:44.000Z","size":1665,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T22:23:26.892Z","etag":null,"topics":["compiler","haxe","rails","ruby"],"latest_commit_sha":null,"homepage":"https://fullofcaffeine.co","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullofcaffeine.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-10T19:19:58.000Z","updated_at":"2026-06-16T20:40:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fullofcaffeine/reflaxe.ruby","commit_stats":null,"previous_names":["fullofcaffeine/reflaxe.ruby"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fullofcaffeine/reflaxe.ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullofcaffeine","download_url":"https://codeload.github.com/fullofcaffeine/reflaxe.ruby/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34749211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["compiler","haxe","rails","ruby"],"created_at":"2026-06-24T21:01:09.567Z","updated_at":"2026-06-24T21:01:10.504Z","avatar_url":"https://github.com/fullofcaffeine.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reflaxe.ruby\n\n`reflaxe.ruby` is a Reflaxe-based Haxe target that emits readable,\nidiomatic Ruby from typed Haxe. It also includes RailsHx, a Rails-native typed\nauthoring layer for ActiveRecord, ActionController, ActionView/HHX, routing,\nTurbo, ActionCable, generators, migrations, tests, and installed-gem companion\ncontracts such as DeviseHx.\n\nThe current `0.1.0-beta.2` baseline supports executable Ruby smoke\nfixtures, shared `hxruby` runtime files and gem packaging, Ruby interop\nmetadata, typed extension/mixin contracts, and a RailsHx dogfood app with typed\nmodels, relations, migrations, controllers, params, HHX templates, Haxe-owned\nroutes, Devise-backed sessions, Turbo Streams, Haxe-authored browser code,\nRails tests, Playwright, and production smoke coverage.\n\nThe project intentionally uses `0.x` beta versioning until the compiler and RailsHx framework layer are production-ready.\n\nThere are two first-class layers:\n\n- **RubyHx / pure Ruby**: compile Haxe to normal Ruby, consume Ruby gems through typed externs/contracts, author Ruby modules/concerns from Haxe, and keep generated Ruby readable to Ruby developers.\n- **RailsHx**: a Rails-native typed authoring layer on top of the same Ruby compiler. Haxe/HHX is source of truth; Rails still owns runtime tasks such as `db:migrate`, `test`, Zeitwerk, and assets.\n\nRails is the flagship framework target because it is the dominant Ruby framework, but it is not the only intended use of `haxe.ruby`. Other framework layers can live in this monorepo or in separate repos that consume the published haxelib/gem and add their own typed std/macros/generators.\n\n## Quick Start\n\nInstall repository dependencies and run the default compiler/test suite:\n\n```bash\nnpm install\nnpm test\n```\n\n`npm test` is intentionally broad: it runs compiler snapshots, smoke tests,\nexample compilation, package checks, strict-boundary policy checks, and fast\nRailsHx materialization checks. Full Rails runtime/browser/production lanes are\ndocumented below.\n\nCompile a Haxe entrypoint by setting `ruby_output` and loading the compiler macros:\n\n```bash\nhaxe \\\n  -D ruby_output=out/ruby \\\n  -D reflaxe_runtime \\\n  -cp src \\\n  -cp examples/hello_world \\\n  -cp vendor/reflaxe/src \\\n  --macro \"reflaxe.ruby.CompilerBootstrap.Start()\" \\\n  --macro \"reflaxe.ruby.CompilerInit.Start()\" \\\n  -main Main\n\nruby out/ruby/run.rb\n```\n\nFor a guided public entrypoint, start with:\n\n- Pure Ruby: [examples/hello_world](examples/hello_world), [Ruby Extension Interop](docs/ruby-extension-interop.md), and [examples/ruby_extensions](examples/ruby_extensions).\n- RailsHx: [examples/todoapp_rails](examples/todoapp_rails) for a full app, [examples/rails_routes_dsl](examples/rails_routes_dsl) for focused Haxe-owned route snapshots, and [examples/rails_interop_app](examples/rails_interop_app) for gradual adoption from existing Ruby/ERB.\n- DeviseHx: [docs/railshx-devisehx-design.md](docs/railshx-devisehx-design.md) for the companion-layer design and [examples/todoapp_rails](examples/todoapp_rails) for the current app-local auth contract in a real Rails flow.\n- Documentation map: [docs/README.md](docs/README.md).\n\n## Target Defines\n\n- `ruby_output=\u003cdir\u003e`: output directory used by Reflaxe.\n- `reflaxe_runtime`: emits/copies shared `hxruby` runtime helpers.\n- `reflaxe_ruby_profile=ruby_first|portable`: declares the Ruby profile contract; default is `ruby_first`. The legacy `idiomatic` value remains accepted.\n- `reflaxe_ruby_rails`: writes app-owned code under `app/haxe_gen` and emits a Rails autoload initializer.\n- `reflaxe_ruby_rails_output_root=\u003cpath\u003e`: overrides the Rails output root; default is `app/haxe_gen`. Use safe relative paths such as `engines/blog/app/haxe_gen` for engine/plugin output; see [RailsHx Engines And Plugins Guide](docs/railshx-engines-plugins-guide.md).\n- `reflaxe_ruby_strict_examples`: rejects raw `__ruby__` injection in repo examples/snapshots.\n- `reflaxe_ruby_strict`: rejects raw `__ruby__` injection in user/project sources.\n- `reflaxe_ruby_strict_policy=auto|on|off`: policy hook for strict user boundaries.\n\nSee [Ruby Profiles](docs/profiles.md) for the profile contract: both profiles should emit idiomatic Ruby where safe, `portable` preserves Haxe semantics first, and `ruby_first` is the Ruby-first default. Profiles are semantic guardrails in one compiler pipeline, not separate backends.\n\n## Ruby Interop\n\nInterop is typed through metadata and small std surfaces:\n\n- `@:native(\"RubyName\")` maps Haxe symbols to Ruby constants or methods.\n- `@:rubyRequire(\"json\")` emits `require \"json\"`.\n- `@:rubyRequireRelative(\"./support/foo\")` emits `require_relative \"./support/foo\"`.\n- `@:rubyKwargs` lowers trailing object literals into Ruby keyword args.\n- `@:rubyBlockArg` lowers trailing function args into Ruby blocks.\n- `@:rubyMixin`, `@:rubyInclude`, `@:rubyPrepend`, and `@:rubyExtend` model Ruby module extension APIs as typed Haxe contracts while emitting normal Ruby `include`/`prepend`/`extend`.\n- `@:rubyPatch(ReceiverType)` plus Haxe `using` models monkey-patched receiver APIs, including ActiveSupport-style extensions, as typed Haxe calls that lower to direct Ruby receiver dispatch.\n- `@:rubyModule(\"Name\")` and `@:rubyConcern(\"Name\")` let Haxe author Ruby modules and ActiveSupport::Concern-style modules directly.\n- `ruby.Symbol.of(\"ready\")` lowers to `:ready`.\n\nRails/ActiveSupport facades are typed std contracts over real Rails APIs:\n\n```haxe\nusing rails.active_support.ObjectPresence;\nusing rails.active_support.StringFilters;\n\nvar normalized = \"  Ship   typed Rails  \".squish();\nvar maybeTitle = normalized.presence();\nif (maybeTitle.present()) trace(maybeTitle);\n```\n\nGenerated Ruby requires the matching ActiveSupport core extension files and calls the patched receivers directly.\n\nRaw `__ruby__` injection exists as an escape hatch, but examples and\nproduction-style code should prefer typed externs, generated contracts, or\nstd/runtime wrappers. The strict boundary defines enforce that policy.\n\nSee [Ruby Extension Interop](docs/ruby-extension-interop.md) for examples ranging from simple module include/extend through existing gem wrapping, gradual adoption, Haxe-owned libraries, and metaprogramming-heavy contract generation. For installed Rails gems such as Devise, see [RailsHx Gem Layers](docs/railshx-gem-layers.md): Ruby/Bundler owns the runtime gem, while RailsHx provides typed contracts, macros, generators, and reusable companion packages when a gem is common enough. The reusable DeviseHx layer starts from the [folded design review](docs/railshx-devisehx-design.md), which was produced from the [GPT 5.5 Pro design prompt](docs/railshx-devisehx-gpt55-prompt.md).\n\n## Rails Workflow\n\nRails mode is enabled with `-D reflaxe_ruby_rails`. It emits Haxe-owned app files under `app/haxe_gen`, plus:\n\n- `config/initializers/hxruby_autoload.rb`\n- Rails-friendly constant/file paths for Zeitwerk\n- typed `rails.active_record.Base\u003cT\u003e` model classes\n- generated ActiveRecord schema metadata via `Model.__hx_rails_schema`\n- generated Rails migrations from Haxe-authored `@:railsMigration(...)` classes\n- typed `rails.action_controller.Base` controller classes\n- `ParamsMacro.requirePermit(...)` for strong params\n- model metadata for `@:belongsTo`, `@:hasMany`, `@:hasOne`, `@:validates`, `@:railsEnum`, and typed callback metadata such as `@:beforeValidation`\n\nThe canonical RailsHx end-to-end example is `examples/todoapp_rails`. The mixed Rails adoption example is `examples/rails_interop_app`.\n\nRailsHx is not a Rails replacement. Rails still owns runtime execution:\n`bin/rails db:migrate`, `bin/rails test`, Zeitwerk, assets, ActionCable,\nDevise/Warden, and app boot remain ordinary Rails. RailsHx owns typed Haxe/HHX\nsource, compile-time validation, generated Rails-shaped artifacts, and a better\ndeveloper workflow around those artifacts.\n\nRun the generated Rails todo app locally:\n\n```bash\nrake todoapp:start\n```\n\nThen open `http://127.0.0.1:3000/`. The app now demonstrates a protected\nDevise-backed board, guest sign-in, user-scoped todos, admin-only user\nmanagement, typed ActiveRecord relations, Haxe-authored HHX views,\nTurbo Streams chat, Haxe-authored browser code, Rails request/model tests, and\nPlaywright UX checks.\n\nFor the RailsHx development loop, start the app with the integrated watcher:\n\n```bash\nrake todoapp:start:watch\n# or:\nWATCH=1 rake todoapp:start\n# or:\nrake 'todoapp:start[watch]'\n```\n\nThat prepares the app once, runs Rails and the RailsHx watcher together, and refreshes generated Rails files when Haxe/HHX or Haxe-authored JS changes.\n\nFor a real-browser RailsHx smoke, run the Playwright sentinel lane:\n\n```bash\nrake todoapp:playwright\n```\n\nThat prepares the generated Rails app, boots Rails on a dedicated port, runs `examples/todoapp_rails/e2e/*.spec.ts`, and tears the server down.\nThe browser lane also compiles the optional Haxe-authored Playwright spec from\n`examples/todoapp_rails/e2e_haxe/**` into disposable ES-module specs under\n`examples/todoapp_rails/e2e/generated/**`; vanilla TypeScript specs remain\nfirst-class. For the lightweight compile/output-shape check without booting\nRails, run `npm run test:haxe-playwright`.\n\nFor the tutorial-style walkthrough of the generated skeleton and todoapp\npatterns, see\n[RailsHx Skeleton And Todoapp Tutorial](docs/railshx-skeleton-and-todoapp-tutorial.md).\n\nFor gradual adoption of an existing Rails app or a quick Ruby/ERB PoC, use typed boundaries instead of an all-at-once rewrite:\n\n```bash\nnpm run test:rails-interop\n```\n\nThat lane proves Haxe can render existing ERB through `Template.external(\"path\") : Template\u003cTLocals\u003e`, call existing Ruby through typed externs, and let legacy ERB consume generated Haxe services/partials as normal Rails artifacts. See [docs/railshx-gradual-adoption.md](docs/railshx-gradual-adoption.md).\n\nTo force the generated Rails runtime apps to install their bundles and execute Rails tests, run:\n\n```bash\nrake test:rails:runtime\n```\n\nThis is the mandatory runtime lane for Rails coverage across the supported Ruby matrix (`3.2`, `3.3`, `4.0`). Plain `rake test`/`npm test` keeps the compiler loop fast and still syntax-checks generated Rails artifacts; the Rails runtime lanes skip only when Rails gems are unavailable in a local environment. CI runs the underlying npm script, so missing generated-app Rails gems become hard failures there.\n\nFor a Rails app adoption scaffold, generate the RailsHx source layout, compile config, rake hook, dev process files, and a small typed starter app:\n\n```bash\nrake rails:app ARGS=\"--output path/to/rails-app --name MyApp\"\n```\n\nThe generated starter includes a typed `HomeController`, HHX layout, HHX home\npage, Haxe-owned root route, route-helper extern placeholder, Haxe-authored\nclient JS, CSS/importmap wiring, app-local Rake tasks, `bin/railshx-*` helpers,\nand `docs/railshx/gem_layers.md` for deterministic-first installed-gem\nwrapping. Rails-facing generators are implemented in Ruby and exposed through\n`bin/rails generate hxruby:*`, repository Rake wrappers, and installed-app\n`hxruby` rake tasks, following the same host-framework-native generator lesson\nas PhoenixHx Mix tasks. npm remains repo infrastructure for Lix, Playwright,\nsemantic-release, and Node-based CI scripts; the RailsHx user-facing path is\nRake/Rails.\n\nIn an installed Rails app, prefer the Rails generator entrypoints:\n\n```bash\nbin/rails generate hxruby:install MyApp\nbin/rails generate hxruby:routes\nbin/rails generate hxruby:controller Todos index show --templates\nbin/rails generate hxruby:mailer UserMailer welcome\nbin/rails generate hxruby:scaffold Todo title:String isCompleted:Bool --controller\nbin/rails generate hxruby:scaffold Todo title:String --controller --skip-tests\nbin/rails generate hxruby:adopt --service LegacyPriceFormatter --template legacy/badge --locals label:String,tone:String\nbin/rails generate hxruby:adopt --service RbsPriceFormatter --rbs sig/rbs_price_formatter.rbs\nbin/rails generate hxruby:adopt --schema --discover\nbin/rails generate hxruby:adopt --schema --models Todo,User\nbin/rails generate hxruby:adopt --migrations --discover\nbin/rails generate hxruby:adopt --discover\n```\n\nInside a generated RailsHx app, the recommended development flow is one command:\n\n```bash\nbundle exec rake hxruby:start\n```\n\nFor the edit loop, run Rails and both Haxe watchers together:\n\n```bash\nbundle exec rake hxruby:start:watch\n# or:\nWATCH=1 bundle exec rake hxruby:start\n# or:\nbundle exec rake 'hxruby:start[watch]'\n```\n\nGenerated apps also include `bin/railshx-dev`, which starts Rails, the server Haxe watcher, and the client Haxe watcher through `foreman` or `overmind` when either tool is installed. Without those tools it falls back to `bundle exec rake hxruby:start:watch`. If you need the lower-level pieces for CI debugging, use `bundle exec rake hxruby:compile`, `bundle exec rake hxruby:compile:client`, `bundle exec rake hxruby:watch`, and `bundle exec rake hxruby:watch:client` directly.\n\nFor Rails tasks that consume generated artifacts, use the RailsHx-prefixed\ncompile-then-delegate tasks:\n\n```bash\nbundle exec rake hxruby:db:migrate   # compile Haxe migrations, then rails db:migrate\nbundle exec rake hxruby:db:prepare   # compile Haxe artifacts, then rails db:prepare\nbundle exec rake hxruby:test         # compile server/client artifacts, then rails test\nbundle exec rake hxruby:rails TASK=zeitwerk:check\nbundle exec rake hxruby:doctor       # non-mutating health report for Haxe/build files/manifests\nbundle exec rake hxruby:check        # compile and ruby -c generated Ruby\nbundle exec rake hxruby:clean        # remove manifest-owned generated artifacts\n```\n\nRaw `bin/rails db:migrate`, `bin/rails test`, and other Rails tasks still work\nwhen artifacts are already current. The `hxruby:*` variants are the safer daily\npath because they refresh generated Ruby, ERB, migrations, route files, and\nclient JS before Rails consumes them.\n\nUse `hxruby:doctor` when onboarding or debugging a generated app: it verifies\nHaxe availability, build files, JSON manifests, Rails command availability, and\nconfigured output roots without mutating the app. It also reports manifest output\ndrift/missing files, stale Haxe-owned route externs, duplicate Rails migration\ntimestamps/classes, and likely Haxe-authored client JS/importmap gaps. Use\n`hxruby:check` in CI for a fast generated-artifact gate; add `CLIENT=1`,\n`ROUTES=1`, or `ZEITWERK=1` when that CI lane should also compile Haxe-authored\nJavaScript, sync route externs, or delegate to Rails' `zeitwerk:check`.\n\nFor production builds, compile Haxe/HHX before the normal Rails build/release steps so generated `app/haxe_gen/**`, generated ActionView templates, generated `db/migrate/**` files, and `config/initializers/hxruby_autoload.rb` exist in the release artifact:\n\n```bash\nbin/railshx-prod\n# or, in CI/buildpacks:\nRAILS_ENV=production bundle exec rake hxruby:production\n```\n\n`hxruby:production` runs the server Haxe compile, client Haxe compile, `rails zeitwerk:check`, and `rails assets:precompile` with production defaults. It intentionally fails closed if required Haxe build files are missing, so releases do not accidentally ship stale generated Ruby, ERB, migrations, or JavaScript.\n\nThe canonical dogfood app has a production smoke that exercises the same shape end to end:\n\n```bash\nrake todoapp:production\n```\n\nThat command compiles Haxe/HHX, compiles Haxe-authored JS, materializes the generated Rails app, runs Rails migrations/tests, runs `zeitwerk:check`, precompiles production assets, creates `test/.generated/rails_integration_release.tgz`, and verifies the release artifact includes generated RailsHx files.\n\nRailsHx is still an experimental beta framework layer with a credible\nproduction path, not yet a production-ready contract. Production readiness is\ntracked by the `haxe.ruby-bjv` bead epic and documented in\n[docs/railshx-production-readiness.md](docs/railshx-production-readiness.md).\n\nThe RailsHx work is tracked in [docs/railshx-roadmap.md](docs/railshx-roadmap.md), covering typed ActiveRecord, migrations, controllers, routes, generators, and integration tests inspired by the Phoenix/Ecto implementation in `../haxe.elixir.codex`. Start with [docs/railshx-generator-workflows.md](docs/railshx-generator-workflows.md) for app-facing generator commands, generated artifacts, runtime handoff, diagnostics, and CI gates. See [docs/railshx-generators-and-tasks-design.md](docs/railshx-generators-and-tasks-design.md) for the generated app skeleton and Rake/Rails task contract, [docs/railshx-routing-design.md](docs/railshx-routing-design.md) for Haxe-owned and Rails-owned route source-of-truth modes, [docs/railshx-controller-guide.md](docs/railshx-controller-guide.md) for typed controllers/params, [docs/railshx-action-mailer-guide.md](docs/railshx-action-mailer-guide.md) for typed ActionMailer classes and HHX mail templates, [docs/railshx-active-job-guide.md](docs/railshx-active-job-guide.md) for typed ActiveJob classes and enqueue helpers, [docs/railshx-active-storage-guide.md](docs/railshx-active-storage-guide.md) for typed ActiveStorage refs, [docs/railshx-turbo-guide.md](docs/railshx-turbo-guide.md) for typed Turbo client and server-side stream helpers, [docs/railshx-action-cable-guide.md](docs/railshx-action-cable-guide.md) for typed ActionCable channels/subscriptions, [docs/railshx-instrumentation-guide.md](docs/railshx-instrumentation-guide.md) for typed ActiveSupport instrumentation, [docs/railshx-components-guide.md](docs/railshx-components-guide.md) for typed Rails-native components, [docs/railshx-engines-plugins-guide.md](docs/railshx-engines-plugins-guide.md) for engine/plugin output roots and host-app consumption, [docs/railshx-gradual-adoption.md](docs/railshx-gradual-adoption.md) for mixed Ruby/ERB and Haxe adoption patterns, and [docs/railshx-haxe-authored-testing-design.md](docs/railshx-haxe-authored-testing-design.md) for the optional Haxe-authored Ruby/JS test-layer design.\n\nUseful tooling:\n\n```bash\nrake rails:routes ARGS=\"--input routes.txt --output src_haxe/routes/Routes.hx\"\nrake rails:controller ARGS=\"Todos index show --templates --output tmp/todo\"\nrake rails:scaffold ARGS=\"--model Todo --fields title:String,isCompleted:Bool --validate title --controller --output tmp/todo\"\nrake rails:adopt ARGS=\"--service LegacyPriceFormatter --template legacy/badge --locals label:String,tone:String --output tmp/rails_app\"\nrake rails:app ARGS=\"--output tmp/rails_app --name TodoApp\"\n```\n\n`rake test:rails:integration` materializes a generated Rails app and always syntax-checks Ruby files. It runs `rails db:migrate` and `rails test` when Rails gems are installed. `rake test:rails:runtime` sets `REQUIRE_RAILS=1`, installs generated app bundles when needed, and makes both Rails integration and mixed-interop runtime execution mandatory.\n\nRailsHx routing supports both ownership directions. Existing Rails apps can keep Rails-owned `config/routes.rb` and generate typed Haxe externs from `rails routes`. Greenfield RailsHx apps can use Haxe-owned `@:railsRoutes` sources that emit normal `config/routes.rb`; Rails still remains the route-helper naming oracle by feeding `rails routes` back into `Routes.hx`. See [docs/railshx-routing-design.md](docs/railshx-routing-design.md) and the focused [examples/rails_routes_dsl](examples/rails_routes_dsl) snapshot fixture.\n\nDevise routes follow the same principle. A Haxe-owned route file can declare\n`DeviseRoutes.deviseFor(UserAuth.scope)` for the supported no-options MVP; the\ncompiler emits ordinary `devise_for :users`, validates the Devise mapping by\nbooting Rails, and still generates typed route helpers from actual\n`rails routes` output. More complex Devise route options remain Rails-owned\nuntil their typed DSL phases land.\n\n## Compatibility\n\nSee [docs/compatibility-matrix.md](docs/compatibility-matrix.md).\n\nThe CI contract targets:\n\n- Haxe `4.3.7`\n- Node `20`\n- Ruby `3.2`, `3.3`, and `4.0`\n\nLocal Ruby `2.6` can still run some non-Rails smoke tests, but it is not the supported runtime baseline for Rails-oriented work.\n\n### Local Ruby Setup\n\nUse `rbenv` for local Rails/compiler work. The repo pins Ruby with `.ruby-version`; install that version and initialize rbenv in your shell:\n\n```bash\nbrew install rbenv ruby-build\nrbenv install\neval \"$(rbenv init - zsh)\"\nruby -v\n```\n\nFor mandatory Rails runtime integration, use the pinned Ruby and let the generated apps install their own bundles:\n\n```bash\nrake test:rails:runtime\n```\n\n`rake test`/`npm test` will run Rails runtime checks when generated app bundles are already available. `rake test:rails:runtime` makes missing Rails gems a hard failure and installs the generated bundles first, matching the dedicated CI lane. Runtime logs are stage-labeled (`compiler`, `materialization`, `migration`, `request tests`, and browser stages) so CI failures point at the failing boundary.\n\n## Quality Gates\n\n```bash\nnpm test\nnpm run test:examples-compile\nrake format:haxe:check\nrake security:gitleaks\nrake test:snapshots\nrake test:strict_boundaries\nrake test:rails:runtime\nrake ci:version_sync\nrake ci:release_contracts\nrake package:gem:test\n```\n\nSnapshot tests compile with `reflaxe_ruby_strict_examples`, compare committed\nRuby output, reject CRLF/trailing-newline/path leaks, and compile each snapshot\ncase twice to catch non-deterministic output.\n\n`npm run test:examples-compile` compiles every `examples/*/Main.hx` entrypoint\nand known example client builds, then verifies each example has an explicit\nsnapshot/smoke/runtime/browser coverage contract. This keeps examples useful as\nliving documentation and as an additional compiler QA lane.\n\nSnapshots are the primary compiler/codegen contract: they show the exact Ruby,\nERB, JS, migration, initializer, and runtime-support artifacts that Rails/Ruby\nusers should be able to review as hand-written-looking output. Smoke tests are\nsupporting gates for focused invariants such as required files, syntax checks,\nnegative Haxe compile failures, package/generator flows, and thin Rails\nconsumption seams. Runtime Rails tests should prove that Rails can load/render/\nmigrate/deliver/subscribe to generated artifacts; they should not broadly\nretest Rails itself unless RailsHx adds custom runtime behavior. See\n[RailsHx Testing Strategy](docs/railshx-testing-strategy.md) for the\nsnapshot-vs-smoke decision rules.\n\n### Local Hooks\n\nInstall the repo-managed pre-commit hook:\n\n```bash\nhaxelib install formatter\nbrew install gitleaks # or use another gitleaks install method\nrake hooks:install\n```\n\nThe hook runs a staged `gitleaks` scan and formats staged `.hx` files with [haxe-formatter](https://github.com/HaxeCheckstyle/haxe-formatter). CI runs the full Haxe formatter check and a dedicated gitleaks workflow, so local hooks catch the same class of issues before review.\n\n## Haxelib Package\n\nBuild the release zip locally with:\n\n```bash\nrake package:haxelib:build\n```\n\nValidate the package contents, compile the extracted `examples/hello_world` fixture, and smoke-test an installed `-lib reflaxe.ruby` consumer with:\n\n```bash\nrake package:haxelib:test\n```\n\nSemantic-release runs the same package builder during release preparation and attaches `dist/reflaxe.ruby-*.zip` to the GitHub release.\n\n## Ruby Gem Package\n\nBuild the `hxruby` runtime gem locally with:\n\n```bash\nrake package:gem:build\n```\n\nValidate the gem contents, runtime require path, rake task registration, and local gem install behavior with:\n\n```bash\nrake package:gem:test\n```\n\nThe gem exposes `require \"hxruby\"` for runtime helpers and `require \"hxruby/tasks\"` for Rails-oriented rake tasks:\n\n```bash\nbin/rails generate hxruby:install MyApp\nbin/rails generate hxruby:routes\nbin/rails generate hxruby:scaffold Todo title:String isCompleted:Bool --controller\nbin/rails generate hxruby:adopt --service LegacyPriceFormatter --template legacy/badge --locals label:String,tone:String\nbin/rails generate hxruby:adopt --service RbsPriceFormatter --rbs sig/rbs_price_formatter.rbs\nbin/rails generate hxruby:adopt --schema --discover\nbin/rails generate hxruby:adopt --schema --models Todo,User\nbin/rails generate hxruby:adopt --migrations --discover\nrake hxruby:compile\nrake hxruby:compile:client\nrake hxruby:db:migrate\nrake hxruby:db:prepare\nrake hxruby:db:rollback\nrake hxruby:start\nrake hxruby:start:watch\nrake hxruby:routes\nrake hxruby:doctor\nrake hxruby:check\nrake hxruby:clean\nrake hxruby:test\nrake hxruby:rails TASK=zeitwerk:check\nrake hxruby:production\nrake hxruby:watch\nrake hxruby:watch:client\nrake hxruby:gen:app\nrake hxruby:gen:adopt SERVICE=LegacyPriceFormatter TEMPLATE=legacy/badge LOCALS=label:String,tone:String\nrake hxruby:gen:adopt SERVICE=RbsPriceFormatter RBS=sig/rbs_price_formatter.rbs\nrake hxruby:gen:routes\nrake hxruby:gen:model MODEL=Todo FIELDS=title:String CONTROLLER=1\nrake hxruby:gen:mailer MAILER=UserMailer ACTION=welcome\nrake hxruby:gen:template PATH=controllers/todos/_card LOCALS=title:String,count:Int\nrake hxruby:gen:test NAME=models/todo\n```\n\nGreenfield app/scaffold generators default to Haxe-owned routes. Pass\n`--routes=haxe|snippet|rails|none` to choose the route source-of-truth mode:\n`haxe` emits typed `@:railsRoutes`, `rails` keeps route helper extern generation\nfor an existing Rails-owned `config/routes.rb`, `snippet` writes reviewable\ninstructions, and `none` leaves route files untouched.\n\nScaffolds also generate a small Haxe-authored Rails model test by default under\n`test_haxe/**`. The Haxe test compiles through `@:railsTest` into normal\nMinitest output under `test/generated/**`, so the starter app exercises both\ntyped source and Rails-native test artifacts. Use `--skip-tests` only when an\nexisting test layout owns that boundary already.\n\nWhen `--controller` is enabled, the scaffold composes the controller generator's\ntyped HHX view path too: the index action renders `Template.of(IndexView)` with\ntyped locals, and the compiler emits ordinary Rails ERB under `app/views/**`.\n\nPlain `require \"hxruby\"` has no gem runtime dependencies. The task entrypoint requires `rake`, which is available in the supported CI Rubies and normal Rails applications.\n\nSemantic-release builds the gem during release preparation and attaches `dist/hxruby-*.gem` to the GitHub release.\n\n## Gap Report\n\nThe std/runtime gap report is generated from `docs/stdlib-inventory.json`.\n\n```bash\nnpm run test:gap-report\nUPDATE_GAP_REPORT=1 npm run test:gap-report\n```\n\nSee [docs/gap-report-guidance.md](docs/gap-report-guidance.md) for how to update inventory entries and interpret remaining gaps.\n\n## Repository Map\n\n- `src/reflaxe/ruby`: compiler, build context, naming, macros, and Ruby AST printer.\n- `std`: additive Ruby/Rails Haxe APIs and target std surfaces.\n- `std/_std`: upstream Haxe std overrides that must take classpath precedence.\n- `runtime/hxruby`: shared Ruby runtime helpers copied into generated output.\n- `examples`: executable compiler/Rails fixtures.\n- `scripts/ci`: smoke, snapshot, inventory, release, and hardening checks.\n- `scripts/rails`: Rails-oriented generators.\n- `scripts/hooks`, `scripts/lint`, `scripts/security`: local hook installer, Haxe formatter guard, and secret scanning wrapper.\n- `test/snapshots`: committed generated Ruby contracts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Freflaxe.ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullofcaffeine%2Freflaxe.ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Freflaxe.ruby/lists"}