sorbet-typescript 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20b6b038eabc0014a293fcd994c56e1413d217613fa86c0df40157dc3e4399a2
+  data.tar.gz: 331239897ffb2f29a4b52dd09987d1fecdbbb298f9cfd8a42dc7898e0034889c
+SHA512:
+  metadata.gz: 28d320cb930debcab937be85c99d676743469c3a223a6d9b3e1ae50d89b14e123a7d81f698126cde66f978d0147fddaadf43422da9d5e941fe1c31e52d6b46be
+  data.tar.gz: b7656d8962f845ed7ff48afa5a507416dfd0accdac1f8a6ff641a2561b58056fb85db80471cf78244e62a3bbc2df7511246bd1adb5189ebc0137df512b990cbf

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [Unreleased]
+
+- Initial development release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nathan Broadbent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Sorbet::Typescript
+
+Sorbet::Typescript exports Sorbet `T::Enum` and `T::Struct` definitions into JSON metadata and TypeScript declarations so front-end clients can stay in sync with your Ruby types.
+
+## Background
+
+DocSpring built this gem for [LogStruct](https://github.com/DocSpring/logstruct) to keep its documented payload types in lockstep with the Ruby source. The generated metadata powers the live reference at [logstruct.com/docs/sorbet-types](https://logstruct.com/docs/sorbet-types/) and all sample logs published across [logstruct.com](https://logstruct.com/), ensuring every example stays current through code generation.
+
+See how LogStruct wires the exporter into its build pipeline in [`scripts/generate_structs.rb`](https://github.com/DocSpring/logstruct/blob/main/scripts/generate_structs.rb).
+
+## Installation
+
+Add the gem to your application:
+
+```bash
+bundle add sorbet-typescript
+```
+
+If you need the latest unreleased changes, point bundler at GitHub:
+
+```bash
+bundle add sorbet-typescript --git https://github.com/DocSpring/sorbet-typescript
+```
+
+## Usage
+
+### Command line
+
+The executable `sorbet-typescript` inspects the namespaces you specify and writes JSON and/or TypeScript files:
+
+```bash
+bundle exec sorbet-typescript export \
+  --struct-namespace MyApp::Types \
+  --enum-namespace MyApp::Enums \
+  --typescript-file app/frontend/types/generated.ts
+```
+
+You can also drive the export with a YAML config (default path `sorbet_typescript.yml`):
+
+```yaml
+requires:
+  - config/environment
+struct_namespaces:
+  - MyApp::Types
+enum_namespaces:
+  - MyApp::Enums
+outputs:
+  typescript_file: app/frontend/types/generated.ts
+  enums_json: tmp/sorbet/enums.json
+  structs_json: tmp/sorbet/structs.json
+```
+
+Run it with `bundle exec sorbet-typescript export --config sorbet_typescript.yml`. Any CLI options override the config file.
+
+### Ruby API
+
+If you want to script the export yourself, use the `Exporter` directly:
+
+```ruby
+exporter = Sorbet::Typescript::Exporter.new(
+  enum_namespaces: ["MyApp::Enums"],
+  struct_namespaces: ["MyApp::Types"]
+)
+
+exporter.export(
+  typescript_file: "app/frontend/types/generated.ts",
+  enums_json: "tmp/sorbet/enums.json",
+  structs_json: "tmp/sorbet/structs.json"
+)
+```
+
+The returned `ExportData` object contains `enums` and `structs` hashes that you can leverage for custom tooling.
+
+## Development
+
+After cloning the repo, install dependencies and run the task workflow:
+
+```bash
+task setup
+task all
+```
+
+Useful individual commands:
+
+- `task typecheck` – run Sorbet (`srb tc`) with the strict sigils enforced in the repo
+- `task lint` / `task lint:fix` – Standard/RuboCop lint checks and auto-corrections
+- `task test` – execute the Minitest suite via `scripts/test.rb`
+
+Make sure you have [Go Task](https://taskfile.dev/#/installation) installed to run the `task` command.
+
+## Releasing
+
+Bump the version in `lib/sorbet/typescript/version.rb`, then run:
+
+```bash
+bundle exec rake release
+```
+
+This creates a git tag, pushes the commit and tag, and publishes the gem.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Taskfile.yml

@@ -0,0 +1,41 @@
+version: '3'
+
+tasks:
+  setup:
+    desc: Install Ruby dependencies
+    cmds:
+      - bundle install
+
+  typecheck:
+    desc: Run Sorbet type checking
+    cmds:
+      - ./scripts/typecheck.sh
+
+  lint:
+    desc: Run RuboCop lint checks
+    cmds:
+      - bundle exec rubocop
+
+  lint:fix:
+    desc: Auto-fix RuboCop issues
+    cmds:
+      - bundle exec rubocop -A
+
+  test:
+    desc: Run the Ruby test suite
+    cmds:
+      - ./scripts/test.rb
+
+  all:
+    aliases: [ci]
+    desc: Run the full validation workflow
+    cmds:
+      - task: typecheck
+      - task: lint
+      - task: test
+
+  fix:
+    desc: Auto-fix lint, then rerun validation
+    cmds:
+      - task: lint:fix
+      - task: all

data/lib/sorbet/typescript/cli.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "yaml"
+require "thor"
+require "sorbet-runtime"
+
+class Sorbet; end unless defined?(Sorbet)
+
+module Sorbet::Typescript
+  class CLI < Thor
+    extend T::Sig
+
+    DEFAULT_CONFIG = "sorbet_typescript.yml"
+
+    class_option :config, type: :string, desc: "Path to configuration file"
+
+    desc "export", "Export Sorbet enums and structs to JSON and TypeScript files"
+    option :require, type: :array, desc: "Files to require before exporting"
+    option :struct_namespace, type: :array, desc: "Namespaces containing T::Struct subclasses"
+    option :enum_namespace, type: :array, desc: "Namespaces containing T::Enum subclasses"
+    option :enums_json, type: :string, desc: "Output path for enums JSON"
+    option :structs_json, type: :string, desc: "Output path for structs JSON"
+    option :typescript_file, type: :string, desc: "Output path for generated TypeScript definitions"
+    option :property_map_json, type: :string, desc: "Output path for property metadata JSON"
+    def export
+      opts = symbolize_keys(options.to_h)
+      configuration = load_configuration(opts[:config])
+
+      Array(configuration.fetch("requires", [])).concat(opts[:require] || []).each do |requirement|
+        require requirement
+      end
+
+      enum_namespaces = resolved_namespace_list(
+        configuration,
+        opts,
+        key: "enum_namespaces",
+        option_key: :enum_namespace
+      )
+      struct_namespaces = resolved_namespace_list(
+        configuration,
+        opts,
+        key: "struct_namespaces",
+        option_key: :struct_namespace
+      )
+
+      outputs = T.cast(configuration.fetch("outputs", {}), T::Hash[String, T.untyped])
+
+      exporter = Exporter.new(
+        enum_namespaces: enum_namespaces,
+        struct_namespaces: struct_namespaces
+      )
+
+      result = exporter.export(
+        enums_json: opts[:enums_json] || outputs["enums_json"],
+        structs_json: opts[:structs_json] || outputs["structs_json"],
+        typescript_file: opts[:typescript_file] || outputs["typescript_file"],
+        property_map_json: opts[:property_map_json] || outputs["property_map_json"]
+      )
+
+      say "Exported #{result.enums.keys.size} enums and #{result.structs.keys.size} structs"
+    rescue Error => e
+      raise Thor::Error, e.message
+    end
+
+    private
+
+    sig { params(config_path: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
+    def load_configuration(config_path)
+      path = config_path || (File.exist?(DEFAULT_CONFIG) ? DEFAULT_CONFIG : nil)
+      return {} unless path
+
+      YAML.load_file(path) || {}
+    rescue Errno::ENOENT
+      raise Error, "Configuration file not found: #{path}"
+    rescue Psych::SyntaxError => e
+      raise Error, "Unable to parse configuration file #{path}: #{e.message}"
+    end
+
+    sig do
+      params(configuration: T::Hash[String, T.untyped], options: T::Hash[Symbol, T.untyped], key: String, option_key: Symbol)
+        .returns(T::Array[T.any(String, Module)])
+    end
+    def resolved_namespace_list(configuration, options, key:, option_key:)
+      cli_value = options[option_key]
+      return Array(cli_value) if cli_value && !cli_value.empty?
+
+      Array(configuration.fetch(key, []))
+    end
+
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def symbolize_keys(hash)
+      hash.transform_keys { |key| key.to_sym }
+    end
+  end
+end

data/lib/sorbet/typescript/exporter.rb

@@ -0,0 +1,546 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require "date"
+require "fileutils"
+require "sorbet-runtime"
+
+class Sorbet; end unless defined?(Sorbet)
+
+module Sorbet::Typescript
+  class Exporter
+    extend T::Sig
+
+    class ExportData < T::Struct
+      const :enums, T::Hash[String, T::Hash[Symbol, T.untyped]]
+      const :structs, T::Hash[String, T::Hash[Symbol, T.untyped]]
+    end
+
+    sig do
+      params(
+        enum_namespaces: T::Array[T.any(String, Module)],
+        struct_namespaces: T::Array[T.any(String, Module)]
+      ).void
+    end
+    def initialize(enum_namespaces: [], struct_namespaces: [])
+      @enum_namespaces = normalize_namespaces(enum_namespaces)
+      @struct_namespaces = normalize_namespaces(struct_namespaces)
+    end
+
+    sig do
+      params(
+        enums_json: T.nilable(String),
+        structs_json: T.nilable(String),
+        typescript_file: T.nilable(String),
+        property_map_json: T.nilable(String)
+      ).returns(ExportData)
+    end
+    def export(enums_json: nil, structs_json: nil, typescript_file: nil, property_map_json: nil)
+      data = generate_data
+
+      write_json(enums_json, data.enums) if enums_json
+      write_json(structs_json, data.structs) if structs_json
+      write_property_map(property_map_json, data.structs) if property_map_json
+      write_typescript(typescript_file, data) if typescript_file
+
+      data
+    end
+
+    sig { returns(ExportData) }
+    def generate_data
+      enums = export_enums
+      structs = export_structs
+      ExportData.new(enums: enums, structs: structs)
+    end
+
+    private
+
+    sig { params(enum_namespaces: T::Array[T.any(String, Module)]).returns(T::Array[String]) }
+    def normalize_namespaces(enum_namespaces)
+      enum_namespaces.map do |namespace|
+        case namespace
+        when Module
+          namespace.name || ""
+        else
+          namespace.to_s
+        end
+      end.reject(&:empty?)
+    end
+
+    sig { returns(T::Array[T.class_of(T::Enum)]) }
+    def enum_classes
+      T::Enum.subclasses.to_a.compact.select do |klass|
+        klass_name = klass.name
+        klass_name && in_namespaces?(klass_name, @enum_namespaces)
+      end.sort_by { |klass| T.must(klass.name) }
+    end
+
+    sig { returns(T::Array[T.class_of(T::Struct)]) }
+    def struct_classes
+      T::Struct.subclasses.to_a.compact.select do |klass|
+        klass_name = klass.name
+        klass_name && in_namespaces?(klass_name, @struct_namespaces)
+      end.sort_by { |klass| T.must(klass.name) }
+    end
+
+    sig { params(name: String, namespaces: T::Array[String]).returns(T::Boolean) }
+    def in_namespaces?(name, namespaces)
+      return true if namespaces.empty?
+
+      namespaces.any? do |namespace|
+        name == namespace || name.start_with?("#{namespace}::")
+      end
+    end
+
+    sig { returns(T::Hash[String, T::Hash[Symbol, T.untyped]]) }
+    def export_enums
+      enum_classes.each_with_object({}) do |enum_class, memo|
+        class_name = T.must(enum_class.name)
+        values = enum_class.values.map do |value|
+          {
+            name: enum_constant_name(value),
+            serialized: value.serialize
+          }
+        end
+
+        memo[class_name] = {
+          name: class_name,
+          simple_name: class_name.split("::").last,
+          values: values
+        }
+      end
+    end
+
+    sig { returns(T::Hash[String, T::Hash[Symbol, T.untyped]]) }
+    def export_structs
+      struct_classes.each_with_object({}) do |struct_class, memo|
+        class_name = T.must(struct_class.name)
+        fields = struct_class.props.each_with_object({}) do |(field, prop_info), acc|
+          acc[field.to_s] = extract_type_info(prop_info)
+        end
+
+        memo[class_name] = {
+          name: class_name,
+          simple_name: class_name.split("::").last,
+          fields: fields
+        }
+      end
+    end
+
+    sig { params(path: String, data: T::Hash[String, T::Hash[Symbol, T.untyped]]).void }
+    def write_json(path, data)
+      ensure_dir(File.dirname(path))
+      File.write(path, JSON.pretty_generate(stringify_keys(data)))
+    end
+
+    sig { params(path: String, structs: T::Hash[String, T::Hash[Symbol, T.untyped]]).void }
+    def write_property_map(path, structs)
+      return unless path
+
+      mapping = structs.each_with_object({}) do |(struct_name, info), acc|
+        fields = T.cast(info[:fields], T::Hash[String, T::Hash[Symbol, T.untyped]])
+        fields.each do |field_name, field_info|
+          key = "#{struct_name}.#{field_name}"
+          acc[key] = field_info
+        end
+      end
+
+      write_json(path, mapping)
+    end
+
+    sig { params(path: String, data: ExportData).void }
+    def write_typescript(path, data)
+      return unless path
+
+      ensure_dir(File.dirname(path))
+
+      enums = data.enums
+      structs = data.structs
+
+      lines = []
+      lines << "// @generated by sorbet-typescript"
+      lines << "/* eslint-disable */"
+      lines << ""
+
+      enums.keys.sort.each do |enum_name|
+        enum_info = enums.fetch(enum_name)
+        ts_name = typescript_identifier(enum_name)
+        values = T.cast(enum_info[:values], T::Array[T::Hash[Symbol, T.untyped]])
+
+        union = values.map { |value| %("#{value[:serialized]}") }.join(" | ")
+        literal_values = values.map { |value| %("#{value[:serialized]}") }
+
+        lines << "export type #{ts_name} = #{union};"
+        lines << "export const #{ts_name}Values = [#{literal_values.join(", ")}] as const;"
+        lines << ""
+      end
+
+      structs.keys.sort.each do |struct_name|
+        struct_info = structs.fetch(struct_name)
+        ts_name = typescript_identifier(struct_name)
+        fields = T.cast(struct_info[:fields], T::Hash[String, T::Hash[Symbol, T.untyped]])
+
+        lines << "export interface #{ts_name} {"
+        fields.keys.sort.each do |field_name|
+          field_info = fields.fetch(field_name)
+          optional = field_info[:optional] ? "?" : ""
+          ts_type = typescript_type_for(field_info, enums)
+          lines << "  #{field_name}#{optional}: #{ts_type};"
+        end
+        lines << "}"
+        lines << ""
+      end
+
+      contents = lines.join("\n").rstrip + "\n"
+      File.write(path, contents)
+    end
+
+    sig { params(field_info: T::Hash[Symbol, T.untyped], enums: T::Hash[String, T::Hash[Symbol, T.untyped]]).returns(String) }
+    def typescript_type_for(field_info, enums)
+      case field_info[:type]
+      when "enum"
+        ts_name = field_info[:enum_name]
+        return "unknown" unless ts_name
+
+        enum_key = T.cast(ts_name, String)
+        if enums.key?(enum_key)
+          typescript_identifier(enum_key)
+        else
+          typescript_identifier(enum_key.split("::").last)
+        end
+      when "enum_single"
+        details = enum_value_details_for(field_info)
+        detail = details.first
+        literal = detail&.fetch(:serialized, nil) || detail&.fetch(:name, nil) || field_info[:enum_value_serialized] || field_info[:enum_value]
+        literal ? %("#{literal}") : "unknown"
+      when "enum_union"
+        details = enum_value_details_for(field_info)
+        return "unknown" if details.empty?
+
+        base_enum = field_info[:base_enum] || simple_enum_name(field_info[:enum_name])
+
+        details.map do |detail|
+          serialized = detail[:serialized]
+          constant_name = detail[:name]
+
+          if base_enum && serialized
+            "#{base_enum}.#{serialized.upcase}"
+          elsif base_enum && constant_name
+            "#{base_enum}.#{constant_name.upcase}"
+          else
+            %("#{serialized || constant_name}")
+          end
+        end.join(" | ")
+      when "array"
+        item = T.cast(field_info[:item], T::Hash[Symbol, T.untyped])
+        "#{typescript_type_for(item, enums)}[]"
+      when "struct"
+        ts_name = field_info[:struct_name]
+        ts_name ? typescript_identifier(ts_name) : "Record<string, unknown>"
+      when "object", "hash"
+        "Record<string, unknown>"
+      when "string"
+        "string"
+      when "integer", "number"
+        "number"
+      when "boolean"
+        "boolean"
+      when "symbol"
+        "string"
+      else
+        "unknown"
+      end
+    end
+
+    sig { params(name: String).returns(String) }
+    def typescript_identifier(name)
+      name.split("::").join
+    end
+
+    sig { params(prop_info: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def extract_type_info(prop_info)
+      type_object = prop_info[:type_object] || prop_info[:type]
+      info = analyse_type_object(type_object)
+      info = augment_enum_metadata(info)
+      info[:optional] = prop_info[:_tnilable] || prop_info[:fully_optional] || false
+      info
+    end
+
+    sig { params(obj: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+    def analyse_type_object(obj)
+      case obj
+      when T::Types::TypedArray
+        item_type = array_inner_type(obj)
+        item_meta = analyse_type_object(item_type)
+        {type: "array", item: item_meta}
+      when T::Types::TypedHash
+        {type: "object"}
+      when T::Private::Types::SimplePairUnion
+        inner_types = T.cast(obj.instance_variable_get(:@types), T::Array[T::Types::Base])
+        non_nil = inner_types.find do |inner|
+          !(inner.is_a?(T::Types::Simple) && inner.raw_type == NilClass)
+        end
+        non_nil ? analyse_type_object(resolve_type(inner: non_nil)) : {type: "any"}
+      when T::Types::Union
+        analyse_union(obj)
+      when T::Types::Simple
+        analyse_type_object(obj.raw_type)
+      when T::Types::TEnum
+        enum_value = obj.val
+        {
+          type: "enum_single",
+          enum_name: enum_value.class.name,
+          enum_values: [enum_value_metadata(enum_value)]
+        }
+      when T::Types::Untyped
+        {type: "any"}
+      when Class, Module
+        analyse_class(obj)
+      when Symbol
+        {type: "symbol"}
+      else
+        analyse_by_string(obj.to_s)
+      end
+    end
+
+    sig { params(inner: T::Types::Base).returns(T.untyped) }
+    def resolve_type(inner:)
+      if inner.is_a?(T::Types::Simple)
+        inner.raw_type
+      elsif inner.is_a?(T::Types::TEnum)
+        inner
+      elsif inner.respond_to?(:inner_type)
+        inner
+      else
+        inner
+      end
+    end
+
+    sig { params(array_type: T::Types::TypedArray).returns(T.untyped) }
+    def array_inner_type(array_type)
+      if array_type.respond_to?(:inner_type)
+        array_type.inner_type
+      else
+        array_type.instance_variable_get(:@inner_type)
+      end
+    end
+
+    sig { params(obj: T::Types::Union).returns(T::Hash[Symbol, T.untyped]) }
+    def analyse_union(obj)
+      inner_types = T.cast(obj.instance_variable_get(:@types), T::Array[T::Types::Base])
+
+      enum_values = []
+      enum_class = nil
+      other_types = []
+
+      inner_types.each do |inner|
+        case inner
+        when T::Types::TEnum
+          enum_value = inner.val
+          enum_class ||= enum_value.class
+
+          if enum_value.instance_of?(enum_class)
+            enum_values << enum_value_metadata(enum_value)
+          else
+            other_types << inner
+          end
+        when T::Types::Simple
+          raw = inner.raw_type
+          next if raw == NilClass
+
+          other_types << inner
+        else
+          other_types << inner
+        end
+      end
+
+      if enum_values.any? && other_types.empty?
+        unique_values = enum_values.uniq { |value| value[:serialized] }
+        enum_name = enum_class&.name
+
+        if unique_values.length == 1
+          return {
+            type: "enum_single",
+            enum_name: enum_name,
+            enum_values: unique_values
+          }
+        end
+
+        return {
+          type: "enum_union",
+          enum_name: enum_name,
+          enum_values: unique_values
+        }
+      end
+
+      resolved_non_nil = inner_types.map { |inner| resolve_type(inner: inner) }.reject { |type| type == NilClass }
+      return {type: "any"} if resolved_non_nil.empty?
+
+      if resolved_non_nil.length == 1
+        return analyse_type_object(resolved_non_nil.first)
+      end
+
+      {type: "any"}
+    end
+
+    sig { params(klass: Module).returns(T::Hash[Symbol, T.untyped]) }
+    def analyse_class(klass)
+      if klass <= T::Enum
+        {
+          type: "enum",
+          enum_name: klass.name
+        }
+      elsif klass <= T::Struct
+        {
+          type: "struct",
+          struct_name: klass.name
+        }
+      elsif klass <= String
+        {type: "string"}
+      elsif klass <= Symbol
+        {type: "symbol"}
+      elsif klass <= Integer
+        {type: "integer"}
+      elsif klass <= Float
+        {type: "number"}
+      elsif klass <= TrueClass || klass <= FalseClass
+        {type: "boolean"}
+      elsif klass <= Time || klass <= Date || klass <= DateTime
+        {type: "string", format: "date-time"}
+      elsif klass <= Hash
+        {type: "hash"}
+      elsif klass <= Array
+        {type: "array", item: {type: "any"}}
+      else
+        {type: "any", ruby_type: klass.name}
+      end
+    end
+
+    sig { params(type: String).returns(T::Hash[Symbol, T.untyped]) }
+    def analyse_by_string(type)
+      case type
+      when /String/
+        {type: "string"}
+      when /Integer/
+        {type: "integer"}
+      when /Float|Numeric/
+        {type: "number"}
+      when /Boolean|TrueClass|FalseClass/
+        {type: "boolean"}
+      when /Array/
+        {type: "array", item: {type: "any"}}
+      when /Hash/
+        {type: "hash"}
+      else
+        {type: "any"}
+      end
+    end
+
+    sig { params(enum_value: T.untyped).returns(T.nilable(String)) }
+    def enum_constant_name(enum_value)
+      const_name = enum_value.instance_variable_get(:@const_name)
+      return unless const_name
+
+      const_name.to_s.delete_prefix(":")
+    end
+
+    sig { params(enum_value: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+    def enum_value_metadata(enum_value)
+      {
+        name: enum_constant_name(enum_value),
+        serialized: enum_value.serialize
+      }
+    end
+
+    sig { params(info: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def augment_enum_metadata(info)
+      case info[:type]
+      when "enum"
+        enum_name = info[:enum_name]
+        info[:values] ||= simple_enum_name(enum_name)
+      when "enum_single"
+        details = enum_value_details_for(info)
+        info[:enum_value_details] = details if details.any?
+        info[:base_enum] ||= simple_enum_name(info[:enum_name])
+
+        first = details.first
+        if first
+          info[:enum_value] ||= first[:name]
+          info[:enum_value_serialized] ||= first[:serialized]
+        end
+      when "enum_union"
+        details = enum_value_details_for(info)
+        info[:enum_value_details] = details if details.any?
+        info[:base_enum] ||= simple_enum_name(info[:enum_name])
+
+        if details.any?
+          info[:enum_values] = details.map { |detail| detail[:name] }
+          info[:enum_values_serialized] = details.map { |detail| detail[:serialized] }
+        end
+      end
+
+      info
+    end
+
+    sig { params(info: T::Hash[Symbol, T.untyped]).returns(T::Array[T::Hash[Symbol, T.untyped]]) }
+    def enum_value_details_for(info)
+      details = info[:enum_value_details]
+      if details.is_a?(Array) && details.first.is_a?(Hash)
+        return T.cast(details, T::Array[T::Hash[Symbol, T.untyped]])
+      end
+
+      raw_values = info[:enum_values]
+      return [] unless raw_values.is_a?(Array)
+
+      if raw_values.first.is_a?(Hash)
+        return T.cast(raw_values, T::Array[T::Hash[Symbol, T.untyped]])
+      end
+
+      enum_class = enum_class_by_name(info[:enum_name])
+      return [] unless enum_class
+
+      raw_values.filter_map do |const_name|
+        next unless const_name.is_a?(String)
+
+        enum_class.values.find do |value|
+          enum_constant_name(value) == const_name
+        end&.then { |enum_value| enum_value_metadata(enum_value) }
+      end
+    end
+
+    sig { params(enum_name: T.untyped).returns(T.nilable(T.class_of(T::Enum))) }
+    def enum_class_by_name(enum_name)
+      return nil unless enum_name.is_a?(String)
+
+      enum_classes.find { |klass| klass.name == enum_name }
+    end
+
+    sig { params(enum_name: T.untyped).returns(T.nilable(String)) }
+    def simple_enum_name(enum_name)
+      return nil unless enum_name.is_a?(String)
+
+      enum_name.split("::").last
+    end
+
+    sig { params(path: String).void }
+    def ensure_dir(path)
+      FileUtils.mkdir_p(path) unless File.directory?(path)
+    end
+
+    sig { params(value: T.untyped).returns(T.untyped) }
+    def stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), hash|
+          key = k.is_a?(Symbol) ? k.to_s : k
+          hash[key] = stringify_keys(v)
+        end
+      when Array
+        value.map { |item| stringify_keys(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/sorbet/typescript/version.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+class Sorbet; end unless defined?(Sorbet)
+
+module Sorbet::Typescript
+  VERSION = "0.1.0"
+end

data/lib/sorbet/typescript.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "typescript/version"
+require_relative "typescript/exporter"
+require_relative "typescript/cli"
+
+class Sorbet; end unless defined?(Sorbet)
+
+module Sorbet::Typescript
+  class Error < StandardError; end
+end

data/sig/sorbet/typescript.rbs

@@ -0,0 +1,39 @@
+class Sorbet
+end
+
+module Sorbet::Typescript
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class Exporter
+    def initialize: (
+      enum_namespaces: Array[untyped] ?,
+      struct_namespaces: Array[untyped] ?
+    ) -> void
+
+    def export: (
+      enums_json: String?
+      structs_json: String?
+      typescript_file: String?
+      property_map_json: String?
+    ) -> ExportData
+
+    def generate_data: () -> ExportData
+
+    class ExportData
+      attr_reader enums: Hash[String, Hash[Symbol, untyped]]
+      attr_reader structs: Hash[String, Hash[Symbol, untyped]]
+
+      def initialize: (
+        enums: Hash[String, Hash[Symbol, untyped]],
+        structs: Hash[String, Hash[Symbol, untyped]]
+      ) -> void
+    end
+  end
+
+  class CLI < ::Thor
+    def export: (*untyped) -> void
+  end
+end

data/sorbet-typescript.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/sorbet/typescript/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "sorbet-typescript"
+  spec.version = Sorbet::Typescript::VERSION
+  spec.authors = ["DocSpring"]
+  spec.email = ["support@docspring.com"]
+
+  spec.summary = "Export Sorbet enums and structs into TypeScript-ready metadata."
+  spec.description = "Sorbet TypeScript bridges Sorbet RBI definitions to TypeScript by introspecting T::Enum and T::Struct classes and emitting JSON metadata and helper typings."
+  spec.homepage = "https://github.com/DocSpring/sorbet-typescript"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*",
+    "sig/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "Taskfile*",
+    "*.gemspec"
+  ]
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "sorbet-runtime", ">= 0.5"
+  spec.add_dependency "thor", ">= 1.3"
+
+  spec.add_development_dependency "minitest", ">= 5.20"
+  spec.add_development_dependency "rake", ">= 13.0"
+  spec.add_development_dependency "rubocop", ">= 1.59"
+  spec.add_development_dependency "rubocop-performance", ">= 1.20"
+  spec.add_development_dependency "rubocop-sorbet", ">= 0.8"
+  spec.add_development_dependency "sorbet", ">= 0.5"
+  spec.add_development_dependency "tapioca", ">= 0.13"
+end

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: sorbet-typescript
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DocSpring
+bindir: exe
+cert_chain: []
+date: 2025-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.59'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.59'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.20'
+- !ruby/object:Gem::Dependency
+  name: rubocop-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.13'
+description: Sorbet TypeScript bridges Sorbet RBI definitions to TypeScript by introspecting
+  T::Enum and T::Struct classes and emitting JSON metadata and helper typings.
+email:
+- support@docspring.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Taskfile.yml
+- lib/sorbet/typescript.rb
+- lib/sorbet/typescript/cli.rb
+- lib/sorbet/typescript/exporter.rb
+- lib/sorbet/typescript/version.rb
+- sig/sorbet/typescript.rbs
+- sorbet-typescript.gemspec
+homepage: https://github.com/DocSpring/sorbet-typescript
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DocSpring/sorbet-typescript
+  source_code_uri: https://github.com/DocSpring/sorbet-typescript
+  changelog_uri: https://github.com/DocSpring/sorbet-typescript/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Export Sorbet enums and structs into TypeScript-ready metadata.
+test_files: []