feat(ruby): translate @example snippets to Ruby via Rosetta

The Ruby pacmak target emitted jsii @example docs verbatim, leaving
TypeScript snippets in generated Ruby docstrings. Wire in RosettaTabletReader
and translate each example to Ruby (TargetLanguage.RUBY), mirroring the Python
target. Examples degrade to the original source if translation fails.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: omarqureshi

packages/jsii-pacmak/lib/targets/ruby.ts

@@ -2,9 +2,16 @@ import * as spec from '@jsii/spec';
 import { toSnakeCase, toPascalCase } from 'codemaker';
 import * as fs from 'fs-extra';
 import * as reflect from 'jsii-reflect';
+import {
+  ApiLocation,
+  enforcesStrictMode,
+  RosettaTabletReader,
+  TargetLanguage,
+} from 'jsii-rosetta';
 import * as path from 'path';
 
 import { Generator, Legalese } from '../generator';
+import { assertSpecIsRosettaCompatible } from '../rosetta-assembly';
 import { Target, TargetOptions } from '../target';
 import { subprocess } from '../util';
 import { VERSION } from '../version';
@@ -17,7 +24,7 @@ export class RubyTarget extends Target {
 
   public constructor(options: TargetOptions) {
     super(options);
-    this.generator = new RubyGenerator(options);
+    this.generator = new RubyGenerator(options.rosetta, options);
   }
 
   public async build(sourceDir: string, outDir: string): Promise<void> {
@@ -211,12 +218,32 @@ const RUBY_RESERVED_NAMES = new Set([
 ]);
 
 export class RubyGenerator extends Generator {
-  public constructor(options: TargetOptions) {
+  public constructor(
+    private readonly rosetta: RosettaTabletReader,
+    options: TargetOptions,
+  ) {
     super({ runtimeTypeChecking: options.runtimeTypeChecking });
     // Ruby convention is 2-space indentation (CodeMaker defaults to 4).
     this.code.indentation = 2;
   }
 
+  /**
+   * Translate a jsii `@example` (authored in TypeScript) into idiomatic Ruby
+   * via Rosetta.  Falls back to the original text if translation fails, so a
+   * bad snippet degrades to a TypeScript example rather than breaking the
+   * build.
+   */
+  private convertExample(example: string, apiLocation: ApiLocation): string {
+    assertSpecIsRosettaCompatible(this.assembly);
+    const translated = this.rosetta.translateExample(
+      apiLocation,
+      example,
+      TargetLanguage.RUBY,
+      enforcesStrictMode(this.assembly),
+    );
+    return translated.source;
+  }
+
   /**
    * Normalize a type reference to its raw `spec.TypeReference` shape.
    * Call sites hold two shapes: jsii-reflect `TypeReference` instances
@@ -389,6 +416,12 @@ export class RubyGenerator extends Generator {
       /** Property getter: emit an @return of the property's type. */
       propertyType?: RubyTypeRef;
       propertyOptional?: boolean;
+      /**
+       * The API location the docs belong to. When present, `@example`
+       * snippets are translated to Ruby via Rosetta; without it they are
+       * emitted verbatim (i.e. as the original TypeScript).
+       */
+      apiLocation?: ApiLocation;
     } = {},
   ): void {
     const docs: spec.Docs = this.rawDocs(docsSource) ?? {};
@@ -430,12 +463,14 @@ export class RubyGenerator extends Generator {
       tags.push(`# @see ${this.inlineDoc(docs.see)}`);
     }
 
-    const exampleLines = docs.example
+    const exampleText =
+      docs.example && opts.apiLocation
+        ? this.convertExample(docs.example, opts.apiLocation)
+        : docs.example;
+    const exampleLines = exampleText
       ? [
           '# @example',
-          ...docs.example
-            .split('\n')
-            .map((l) => `#   ${l.trimEnd()}`.trimEnd()),
+          ...exampleText.split('\n').map((l) => `#   ${l.trimEnd()}`.trimEnd()),
         ]
       : [];
 
@@ -692,10 +727,14 @@ export class RubyGenerator extends Generator {
       (m) => this.rubyConstName(m.name),
       typeSpec.fqn,
     );
-    this.emitDocs(typeSpec);
+    this.emitDocs(typeSpec, {
+      apiLocation: { api: 'type', fqn: typeSpec.fqn },
+    });
     this.code.open(`module ${prefix}${this.rubyModuleName(typeSpec.name)}`);
     for (const member of resolvedMembers) {
-      this.emitDocs(member);
+      this.emitDocs(member, {
+        apiLocation: { api: 'member', fqn: typeSpec.fqn, memberName: member.name },
+      });
       this.code.line(
         `${this.rubyConstName(member.name)} = Jsii::Enum.new("${rubyDq(typeSpec.fqn)}", "${rubyDq(member.name)}")`,
       );
@@ -744,7 +783,9 @@ export class RubyGenerator extends Generator {
           ? ' < Jsii::Struct'
           : '';
 
-    this.emitDocs(typeSpec);
+    this.emitDocs(typeSpec, {
+      apiLocation: { api: 'type', fqn: typeSpec.fqn },
+    });
     this.code.open(`${kind} ${prefix}${rubyName}${baseString}`);
 
     if (!typeSpec.datatype) {
@@ -796,6 +837,11 @@ export class RubyGenerator extends Generator {
         this.emitDocs(prop, {
           propertyType: prop.type,
           propertyOptional: prop.optional,
+          apiLocation: {
+            api: 'member',
+            fqn: typeSpec.fqn,
+            memberName: prop.name,
+          },
         });
         this.code.line(`attr_reader :${this.rubyName(prop.name)}`);
       }
@@ -832,6 +878,11 @@ export class RubyGenerator extends Generator {
         this.emitDocs(prop, {
           propertyType: prop.type,
           propertyOptional: prop.optional,
+          apiLocation: {
+            api: 'member',
+            fqn: typeSpec.fqn,
+            memberName: prop.name,
+          },
         });
         this.code.open(`def ${propRubyName}()`);
         this.code.line(`jsii_get_property("${rubyDq(prop.name)}")`);
@@ -868,6 +919,11 @@ export class RubyGenerator extends Generator {
           params: method.parameters,
           returns: method.spec?.returns,
           isMethod: true,
+          apiLocation: {
+            api: 'member',
+            fqn: typeSpec.fqn,
+            memberName: method.name,
+          },
         });
         this.code.open(`def ${this.rubyName(method.name)}(${sigParams})`);
         for (const p of method.parameters) {
@@ -951,7 +1007,9 @@ export class RubyGenerator extends Generator {
       (i) => `::${this.rubyFullTypeName(i)}`,
     );
 
-    this.emitDocs(typeSpec);
+    this.emitDocs(typeSpec, {
+      apiLocation: { api: 'type', fqn: typeSpec.fqn },
+    });
     this.code.open(`class ${prefix}${rubyName} < ${baseClass}`);
 
     for (const mixin of interfaceMixins) {
@@ -977,7 +1035,10 @@ export class RubyGenerator extends Generator {
         })
         .join(', ');
 
-      this.emitDocs(initializer, { params: initializer.parameters });
+      this.emitDocs(initializer, {
+        params: initializer.parameters,
+        apiLocation: { api: 'initializer', fqn: typeSpec.fqn },
+      });
       this.code.open(`def initialize(${initParams})`);
       for (const p of initializer.parameters) {
         const rubyParam = this.rubyName(p.name);
@@ -1084,6 +1145,11 @@ export class RubyGenerator extends Generator {
         params: method.parameters,
         returns: method.spec?.returns,
         isMethod: true,
+        apiLocation: {
+          api: 'member',
+          fqn: typeSpec.fqn,
+          memberName: method.name,
+        },
       });
       this.code.open(`def self.${this.rubyMethodName(method)}(${sigParams})`);
       for (const p of method.parameters) {
@@ -1112,6 +1178,11 @@ export class RubyGenerator extends Generator {
         this.emitDocs(prop, {
           propertyType: prop.type,
           propertyOptional: prop.optional,
+          apiLocation: {
+            api: 'member',
+            fqn: typeSpec.fqn,
+            memberName: prop.name,
+          },
         });
         this.code.open(`def self.${rubyName}()`);
         this.code.line(
@@ -1136,6 +1207,11 @@ export class RubyGenerator extends Generator {
         this.emitDocs(prop, {
           propertyType: prop.type,
           propertyOptional: prop.optional,
+          apiLocation: {
+            api: 'member',
+            fqn: typeSpec.fqn,
+            memberName: prop.name,
+          },
         });
         this.code.open(`def ${rubyName}()`);
         this.code.line(`jsii_get_property("${rubyDq(prop.name)}")`);
@@ -1178,6 +1254,11 @@ export class RubyGenerator extends Generator {
         params: method.parameters,
         returns: method.spec?.returns,
         isMethod: true,
+        apiLocation: {
+          api: 'member',
+          fqn: typeSpec.fqn,
+          memberName: method.name,
+        },
       });
       this.code.open(`def ${this.rubyMethodName(method)}(${sigParams})`);
       for (const p of method.parameters) {

packages/jsii-pacmak/test/targets/ruby/ruby-names.test.ts

@@ -35,7 +35,7 @@ describe('Ruby naming behavior', () => {
       },
     };
 
-    rubyTarget = new RubyGenerator({
+    rubyTarget = new RubyGenerator({} as any, {
       targetName: 'ruby',
       packageDir: '.',
       assembly,