feat(ruby): Ruby language bindings

[omarqureshi]

Objective

Introduces comprehensive Ruby language bindings for the jsii ecosystem, enabling AWS CDK (and other jsii-based libraries) to be packaged as gems and consumed idiomatically from Ruby. It adds the code-generation target (jsii-pacmak) and the core Ruby runtime (@jsii/ruby-runtime), with strict type-safety, careful object lifecycle management, and thread-safe IPC with the jsii Node kernel.

Implements RFC 0935: Ruby language bindings. The change is strictly additive — no breaking changes to existing languages and no assembly-format change beyond an additive targets.ruby schema extension.

Warning

CI is expected to be red on this branch, by design. Ruby code generation requires a jsii-compiler release with Ruby target support, which is not yet published. Until it is, the following failures are expected and are not indicative of broken work:

• jsii-pacmak target-ruby snapshot test — this branch builds with the stock compiler (no Ruby support), so the committed assemblies carry no targets.ruby and generated names won't match the snapshot.
• @jsii/ruby-runtime-test (generate.sh + rspec) — cannot generate the Ruby lib/ without the Ruby-capable compiler.
• "Assert clean working directory" — a build would rewrite the assemblies.

Once the Ruby-capable compiler is released, the committed fixtures (assemblies with targets.ruby + the Ruby snapshot) are regenerated against it and CI goes green. End-to-end regeneration + publish has already been validated against the fork compiler.

Key Components

1. Code Generation (jsii-pacmak)

• RubyTarget & RubyGenerator (packages/jsii-pacmak/lib/targets/ruby.ts): translate jsii types into idiomatic Ruby — class < Jsii::Object, behavioral interfaces as mixin modules, datatype structs as kwargs value-classes (< Jsii::Struct), enums as Jsii::Enum wrapper constants, async + sync methods, and property/method overrides.
• Generated RBS signatures: every class, module, method, and struct gets a .rbs; output validates clean under rbs validate across jsii-calc and its dependency closure.
• Idiomatic naming: snake_case members, PascalCase modules (configurable acronyms), UPPER_SNAKE constants, reserved-word mangling (next → _next). Root namespace AWSCDK with AWS-prefix de-duplication (aws-s3 → AWSCDK::S3::Bucket).
• Robust namespacing: pre-declares Ruby namespaces (module X; end) in dependency order to prevent NameError during nested type generation.
• Security & type checking: injects Jsii::Type.check_type for runtime enforcement, and embeds type metadata as Base64-encoded JSON literals so no jsii-supplied identifier or docstring can inject into generated source via string interpolation.
• Version management: shared version-utils.ts translates npm semver (incl. pre-release .alpha.1/.dev.1) to RubyGems ranges.

2. Ruby Runtime Core (@jsii/ruby-runtime)

• Thread-safe IPC kernel: a re-entrant Monitor makes the bidirectional JSON-RPC stdio pipe safe under concurrency and re-entrant callbacks; an isolated stderr-draining thread prevents pipe deadlocks.
• Callbacks & overrides: JS→Ruby callbacks (including super crossing back to the JS implementation), with user subclasses detected at construction time.
• Object registry & lifecycle: proxies created via .allocate, mapped by $jsii.byref; deliberately never issues a guest-initiated del (matching the Python/Go runtimes) — cleanup is wholesale on kernel shutdown, which suits short-lived synth workloads.
• Type-driven serialization: a dedicated Jsii::Serializer (rather than monkey-patching core types) handles by-value structs vs by-reference objects, avoiding leakage of host application state.

3. Compliance & Testing (@jsii/ruby-runtime-test)

• Full compliance suite covering all 123 canonical compliance cases (diamond inheritance, async/sync overrides, property overrides, hash coercion, unions, nullability, collections, naming).
• Ruby-specific unit specs: serializer round-trips, kernel concurrency, lazy autoload, and rbs validate. No skipped/pending tests.

4. CI / Build

• GitHub Actions: Ruby 3.3 set up on every matrix leg, plus dedicated Ruby 3.4 and 4.0 legs; buildspec.yaml CodeBuild runtime added.
• Wired into the compliance report (tools/jsii-compliance).

Compatibility & Known Limitations

• Ruby 3.3+ on MRI (CRuby) only — gemspecs enforce required_ruby_version >= 3.3.0 (3.1/3.2 are EOL). JRuby/TruffleRuby are out of scope for the initial release.
• Ambiguous unions: a Hash passed where a union admits more than one struct type is forwarded as-is; coercion only happens when exactly one struct arm makes it unambiguous.
• Hash keys must be snake_case when supplied for struct coercion.
• Async static methods go through the synchronous kernel path (the kernel's begin API only accepts object references — a limitation shared by all bindings).

Notes & Next Steps

• Rosetta: the jsii-rosetta translation backend for Ruby is not included here and will follow in a subsequent PR.
• Test fixtures: the committed test assemblies currently follow main and do not yet carry targets.ruby (it's compiler-generated). They — and the target-ruby snapshot — will be regenerated against the released Ruby-capable compiler before merge. See the warning above.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.