Skip to content

README.md

Latest commit

 

History

History
145 lines (129 loc) · 10.4 KB

README.md

File metadata and controls

145 lines (129 loc) · 10.4 KB
Raw

haxe.ruby Docs

This repo has one compiler pipeline with multiple authoring layers:

  • RubyHx covers pure Ruby output, Ruby std/runtime support, gem interop, Ruby extension APIs, and framework-independent Haxe-to-Ruby authoring.
  • RailsHx is the Rails-first layer: typed ActiveRecord, ActionController, ActionView/HHX, generators, migrations, Turbo/importmap, tests, and Rails-native app workflows.

Both selective Ruby-first adoption and Haxe-first authoring are supported. Haxe-first projects can keep nearly all owned library or application source in Haxe/HHX while using generated Ruby with the normal runtime, gems, Rails, and deployment ecosystem.

RailsHx is a first-class citizen, not a separate backend. Rails remains the runtime owner for db:migrate, test, Zeitwerk, assets, and app boot. RailsHx owns typed Haxe source, compile-time validation, generated Rails artifacts, and the developer UX around those artifacts.

Future Ruby framework layers should reuse the same split: add typed std/macros/generators for the framework, emit framework-native Ruby artifacts, and keep framework runtime tasks owned by the framework. Those layers can live here if they share compiler/runtime code tightly, or in separate repos that consume reflaxe.ruby/hxruby.

Start Here

RailsHx Guides

  • RailsHx Roadmap: current Rails plan and sequencing.
  • Generator Workflows: app-facing generator commands, generated artifacts, runtime handoff, diagnostics, and CI gates.
  • Generators And Tasks: Rails-native generator/task ownership, generated starter skeleton, and hxruby:start workflows.
  • Development Loop: one-command Rails startup, checked HXML input discovery, change-aware server/client rebuilds, debounce, and watcher tuning.
  • Generated Artifact Ownership: manifest/header safety and overwrite policy.
  • Typed Views And HHX: TSX-like Haxe view authoring, compile-time checks, Rails-native ERB output, advantages, and honest limits.
  • Client JavaScript And Genes: the separate browser build, Genes versus the stock Haxe JavaScript emitter, Rails importmap integration, ownership, and tradeoffs.
  • Gradual Adoption: mixing existing Ruby/ERB with Haxe/HHX.
  • Gem Layers: wrapping installed Ruby gems through typed contracts and reusable companion packages such as future DeviseHx.
  • Gem-Layer Testing: testing pyramid for reusable RailsHx companion packages over Ruby gems.
  • DeviseHx GPT 5.5 Pro Prompt: required pre-implementation design review packet for the reusable Devise companion layer.
  • DeviseHx Design: folded GPT 5.5 Pro review, API shape, extraction strategy, escape hatches, tests, and rollout plan.
  • DeviseHx Release Lane: incubated package metadata, CI gates, security/release checklist, and standalone split criteria.
  • Testing Strategy: snapshots, smoke tests, Rails runtime tests, and Playwright.
  • Typed API Production Gap Audit: current typed API gaps.

RailsHx API Areas

Examples

  • examples/hello_world: smallest pure Ruby compile/run path.
  • examples/rubyhx_cli: maintained multi-file Haxe-first library/CLI with filesystem input, typed JSON, failure paths, a handwritten Ruby consumer, and an isolated installed-package compile/run contract.
  • examples/ruby_callable_abi: canonical pure RubyHx callable ABI example, including a handwritten Ruby consumer and runtime-free generated calls.
  • examples/ruby_interop and examples/ruby_extensions: consuming and authoring Ruby APIs from Haxe.
  • examples/active_support_facades: typed facades over Ruby/Rails extension-style APIs.
  • examples/rails_routes_dsl: focused Haxe-owned Rails route DSL fixture with committed config/routes.rb and route-manifest snapshots.
  • examples/rails_test_adapters: focused Haxe-authored Rails test fixture for default Minitest and explicit RSpec adapter output.
  • examples/rails_interop_app: gradual Rails adoption with existing Ruby/ERB seams.
  • examples/todoapp_rails: canonical RailsHx dogfood app with HHX, ActiveRecord, migrations, DeviseHx, Haxe-authored JS, Rails tests, production smoke, and Playwright.

Local Public-Readiness Checks

haxelib install formatter
brew install gitleaks
rake hooks:install
rake format:haxe:check
rake security:gitleaks
npm test

The pre-commit hook formats staged .hx files with haxe-formatter and runs staged gitleaks. CI runs a full formatter check, the compiler/Rails matrix, release-contract checks, and secret scanning.