Skip to content

development.md

Latest commit

 

History

History
181 lines (137 loc) · 6.91 KB

development.md

File metadata and controls

181 lines (137 loc) · 6.91 KB
Raw

Repository Development

This guide collects contributor and repository-maintenance details that do not belong on the product README. Application authors should start with Getting Started.

Install And Check The Checkout

npm install
npm test

npm test covers compiler/runtime smokes, exhaustive example compilation, negative diagnostics, deterministic snapshots, strict-boundary policies, generator behavior, release contracts, and package consumers. Rails runtime, browser, and production gates remain separate because they install/boot full applications:

rake test:rails:runtime
rake todoapp:playwright
rake todoapp:production

The complete release-readiness command set lives in RubyHx And RailsHx Production Readiness.

Queue The Full Local Suite

Several Haxe target repositories can otherwise start their largest local suites at the same time and make every run much slower. Use the opt-in queued entrypoint when other Haxe-family compiler work may be active:

npm run test:queued

This waits for at most 15 minutes on the user-scoped haxe-family.heavy-run-lease.v1 lease, runs the unchanged npm test command, and releases the lease on success, failure, or cancellation. It reports exit code 75 when the bounded wait expires, so retrying later is safe. The ordinary npm test command remains unqueued for focused/manual use, and CI never acquires a local lease.

Nested participating commands inherit the same owner PID and lease path, so a RubyHx suite that invokes an hxhx heavy gate does not deadlock itself. Override the shared path only for isolated diagnostics with HAXE_FAMILY_HEAVY_RUN_LEASE_FILE; a different schema is rejected rather than silently deleted. Protocol upgrades require a new schema name and coordinated adapter updates across repositories. The interoperability source is the hxhx native iteration latency contract.

Examples Are QA Contracts

Every examples/*/Main.hx entrypoint must be registered in npm run test:examples-compile. Each example also needs an explicit snapshot/smoke/runtime/browser contract; compile-only coverage is acceptable only when snapshots or diagnostics completely own the behavior.

The highest-value entrypoints are:

  • examples/hello_world: minimal compile/run.
  • examples/ruby_callable_abi: typed blocks, keywords, forwarding, and a handwritten Ruby consumer.
  • examples/rails_interop_app: mixed Ruby/ERB and Haxe ownership.
  • examples/todoapp_rails: canonical Rails runtime/browser/production app.

See RailsHx Testing Strategy for the evidence pyramid.

Snapshots, Smokes, And Runtime Tests

Snapshots own exact generated Ruby/Rails/ERB/JS shape and compile each case twice to detect nondeterminism. Smoke scripts add focused invariants, invalid compile cases, syntax checks, generators/packages, and thin consumption seams. Runtime tests prove behavior that output inspection cannot, such as Rails autoloading, rendering, migrations, jobs, mail, storage, ActionCable, browser flows, and production assets.

The packaged RailsHx development scheduler has a deterministic no-sleep gate:

npm run test:development-watcher

It owns HXML/classpath discovery, idle polls, target selection, debounce, failure recovery, and duplicate-initial-build suppression. See RailsHx Development Loop.

Do not broadly retest Ruby or Rails behavior unless RubyHx/RailsHx introduces a custom semantic boundary.

Local Hooks

Install formatter and secret-scanning prerequisites, then the shared project hooks:

haxelib install formatter
brew install gitleaks # or use another supported installation method
rake hooks:install

The hook formats staged .hx files and scans staged content with Gitleaks. CI runs the full formatter, locked-dependency, and full-history security gates.

Std And Runtime Inventory

The generated gap report is owned by docs/stdlib-inventory.json:

npm run test:gap-report
UPDATE_GAP_REPORT=1 npm run test:gap-report

Upstream behavioral parity is tracked independently by test/upstream_unitstd/manifest.json and npm run test:unitstd-ruby. See Gap Report Guidance, Std Ownership, and Ruby Stdlib Parity Audit.

Ruby AST Inventory

Compiler raw and print-reembed sites have a separate checked inventory:

npm run test:ruby-ast-inventory
UPDATE_RUBY_AST_INVENTORY=1 npm run test:ruby-ast-inventory

Review the generated diff rather than treating the count as a score. Every category must retain an owner, executable evidence, and a migration or retention reason. See Ruby AST And Semantic Lowering.

Issue And Git Workflow

Public bug reports, compatibility questions, and feature proposals enter through GitHub Issues. See Support And Maintenance for routing and response expectations.

This repository uses bd beads. Run bd prime for the current workflow and project memories, then use bd ready, bd show, bd update --claim, and bd close around a bounded slice. The tracked .beads/issues.jsonl export is committed with the work it describes.

Install the shared bead-aware hooks once after cloning:

bd hooks install --shared

The repository-level AGENTS.md is the authoritative design and workflow policy for agent-assisted changes.

Repository Map

  • src/reflaxe/ruby: compiler orchestration, typed Ruby AST/lowering, naming, build context, and focused Ruby/Rails compiler modules.
  • std/ruby: typed Ruby std/interop surfaces.
  • std/ruby/_std: upstream Haxe std overrides in source-checkout layout.
  • std/rails: typed Rails authoring APIs and compiler-erased markers.
  • runtime/hxruby: shared Ruby semantic helpers copied into generated output.
  • lib/hxruby: Ruby gem, Rails generators, and Rake workflows.
  • haxe_libraries: installed package definitions for Ruby server and RailsHx browser builds.
  • examples: executable product and compiler contracts.
  • scripts/ci: snapshot, smoke, policy, generator, package, and release checks.
  • scripts/rails: repository-facing Rails helpers and the todoapp lifecycle.
  • test/snapshots: committed generated output contracts.
  • vendor/reflaxe: the pinned compiler framework plus its patch ledger.

Focused Documentation