typespec_from_serializers 0.1.1 → 0.2.0

data/lib/typespec_from_serializers/io.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "open3"
+
+# Public: Builds on top of Ruby I/O open3 providing a friendlier experience.
+module TypeSpecFromSerializers::IO
+  class << self
+    # Internal: A modified version of capture3 that can continuously print stdout.
+    def capture(*cmd, with_output: nil, **opts)
+      return Open3.capture3(*cmd, **opts) unless with_output
+
+      Open3.popen3(*cmd, **opts) do |stdin, stdout, stderr, wait_threads|
+        stdin.close
+        out = Thread.new { read_lines(stdout, &with_output) }
+        err = Thread.new { read_lines(stderr, &with_output) }
+        [out.value, err.value, wait_threads.value]
+      end
+    end
+
+    # Internal: Reads and yield every line in the stream. Returns the full content.
+    def read_lines(io)
+      buffer = +""
+      while (line = io.gets)
+        buffer << line
+        yield line if block_given?
+      end
+      buffer
+    end
+  end
+end

data/lib/typespec_from_serializers/openapi_compiler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "runner"
+
+module TypeSpecFromSerializers
+  module OpenAPICompiler
+    class CompilationError < StandardError; end
+
+    class << self
+      # Public: Compiles TypeSpec to OpenAPI specification.
+      #
+      # Returns the Pathname to the generated OpenAPI file.
+      def compile
+        require "fileutils"
+
+        typespec_dir = config.output_dir
+        FileUtils.mkdir_p(config.openapi_path.dirname)
+
+        compile_typespec(typespec_dir)
+
+        config.openapi_path
+      end
+
+      private
+
+      def config
+        TypeSpecFromSerializers.config
+      end
+
+      def runner
+        @runner ||= TypeSpecFromSerializers::Runner.new(config)
+      end
+
+      # Internal: Executes TypeSpec compilation with OpenAPI emitter.
+      def compile_typespec(typespec_dir)
+        args = [
+          "compile", "routes.tsp",
+          "--emit", "@typespec/openapi3",
+          "--option", "@typespec/openapi3.emitter-output-dir=#{config.openapi_path.dirname}",
+          "--option", "@typespec/openapi3.output-file=#{config.openapi_path.basename}",
+        ]
+
+        output, error, status = runner.run(args, chdir: typespec_dir, with_output: ->(line) { print line })
+
+        unless status.success?
+          raise CompilationError, "TypeSpec compilation failed:\n#{output}#{error}"
+        end
+
+        unless config.openapi_path.exist?
+          raise CompilationError, "OpenAPI output not found at: #{config.openapi_path}"
+        end
+      rescue TypeSpecFromSerializers::Runner::MissingExecutableError => e
+        raise CompilationError, <<~ERROR
+          #{e.message}
+
+          Please install Node.js and a package manager:
+          https://nodejs.org/
+        ERROR
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/railtie.rb

@@ -33,15 +33,103 @@ class TypeSpecFromSerializers::Railtie < Rails::Railtie
   # Suitable when triggering code generation manually.
   rake_tasks do |app|
     namespace :typespec_from_serializers do
+      desc "Install TypeSpec dependencies"
+      task setup: :environment do
+        require_relative "generator"
+        require_relative "runner"
+        require "fileutils"
+
+        config = TypeSpecFromSerializers.config
+        root = config.root
+
+        puts "Setting up TypeSpec dependencies..."
+
+        # Create package.json in project root if it doesn't exist
+        package_json_path = root.join("package.json")
+        unless package_json_path.exist?
+          puts "Creating package.json in #{root}..."
+          File.write(package_json_path, <<~JSON)
+            {
+              "private": true,
+              "type": "module"
+            }
+          JSON
+        end
+
+        # Install TypeSpec packages
+        puts "Installing TypeSpec packages..."
+        deps = %w[@typespec/compiler @typespec/http @typespec/openapi3]
+
+        install_cmd = case config.package_manager
+        when "npm"
+          ["npm", "install", "--save-dev", *deps]
+        when "pnpm"
+          ["pnpm", "add", "-D", *deps]
+        when "bun"
+          ["bun", "add", "-d", *deps]
+        when "yarn"
+          ["yarn", "add", "-D", *deps]
+        end
+
+        output, error, status = TypeSpecFromSerializers::IO.capture(
+          *install_cmd,
+          chdir: root.to_s,
+          with_output: ->(line) { print line }
+        )
+
+        if status.success?
+          puts "\nTypeSpec dependencies installed successfully! 🎉"
+        else
+          puts "\nFailed to install dependencies:"
+          puts error
+          exit 1
+        end
+      end
+
       desc "Generates TypeSpec descriptions for each serializer in the app."
       task generate: :environment do
         require_relative "generator"
         start_time = Time.zone.now
         print "Generating TypeSpec descriptions..."
-        serializers = TypeSpecFromSerializers.generate(force: true)
+        result = TypeSpecFromSerializers.generate(force: true)
         puts "completed in #{(Time.zone.now - start_time).round(2)} seconds.\n"
-        puts "Found #{serializers.size} serializers:"
-        puts serializers.map { |s| "\t#{s.name}" }.join("\n")
+        puts "Found #{result[:serializers].size} serializers:"
+        puts result[:serializers].map { |s| "\t#{s.name}" }.join("\n")
+        if result[:controllers].any?
+          puts "\nFound #{result[:controllers].size} controllers:"
+          puts result[:controllers].map { |c| "\t#{c}" }.join("\n")
+        end
+      end
+
+      desc "Generates Sorbet RBI files for serializers"
+      task generate_rbi: :environment do
+        require_relative "generator"
+        require_relative "rbi"
+        start_time = Time.zone.now
+        print "Generating Sorbet RBI files for serializers..."
+        # Load serializers first
+        TypeSpecFromSerializers.generate(force: true)
+        files = TypeSpecFromSerializers::RBI.generate_for_all_serializers
+        puts "completed in #{(Time.zone.now - start_time).round(2)} seconds.\n"
+        puts "Generated #{files.size} RBI files:"
+        puts files.map { |f| "\t#{f}" }.join("\n")
+      end
+
+      desc "Compiles TypeSpec to OpenAPI specification"
+      task compile_openapi: :environment do
+        require_relative "generator"
+        require_relative "openapi_compiler"
+
+        start_time = Time.zone.now
+        print "Generating TypeSpec descriptions..."
+        TypeSpecFromSerializers.generate(force: true)
+        puts "done."
+
+        print "Compiling TypeSpec to OpenAPI..."
+        output_path = TypeSpecFromSerializers::OpenAPICompiler.compile
+        duration = (Time.zone.now - start_time).round(2)
+        puts "completed in #{duration} seconds.\n"
+        puts "OpenAPI spec generated at: #{output_path}"
       end
     end
   end

data/lib/typespec_from_serializers/rbi.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "rbi"
+
+module TypeSpecFromSerializers
+  # Public: Generates Sorbet RBI files for serializers.
+  #
+  # This generator creates type signatures for serializer class methods
+  # (.one, .many, .one_as_hash, .many_as_hash) that can be used by
+  # Sorbet for static type checking.
+  module RBI
+    # Internal: Reusable type builders for common Sorbet types.
+    module Types
+    module_function
+
+      # T::Hash[Symbol, T.untyped]
+      def hash
+        @hash ||= ::RBI::Type.generic("T::Hash", [
+          ::RBI::Type.simple("Symbol"),
+          ::RBI::Type.untyped,
+        ])
+      end
+
+      # T.nilable(T::Hash[Symbol, T.untyped])
+      def optional_hash
+        @optional_hash ||= ::RBI::Type.nilable(hash)
+      end
+
+      # T::Array[T::Hash[Symbol, T.untyped]]
+      def array_of_hashes
+        @array_of_hashes ||= ::RBI::Type.generic("T::Array", [hash])
+      end
+
+      # T.any(T::Array[ModelType], ActiveRecord::Relation)
+      def items_type(model_type)
+        ::RBI::Type.any(
+          ::RBI::Type.generic("T::Array", [::RBI::Type.simple(model_type)]),
+          ::RBI::Type.simple("ActiveRecord::Relation"),
+        )
+      end
+    end
+
+    class << self
+      # Public: Generate RBI content for a single serializer.
+      #
+      # serializer_class - The serializer class to generate RBI for
+      #
+      # Returns String with RBI content or nil
+      def generate_for_serializer(serializer_class)
+        model_class = infer_model_class(serializer_class)
+        return nil unless model_class
+
+        build_rbi_file(serializer_class, model_class).string
+      end
+
+      # Public: Generate RBI files for all serializers.
+      #
+      # output_dir - Optional output directory (defaults to sorbet/rbi/dsl)
+      #
+      # Returns Array of file paths that were written
+      def generate_for_all_serializers(output_dir: nil)
+        output_dir ||= default_output_dir
+        output_dir.mkpath unless output_dir.exist?
+
+        formatter = ::RBI::Formatter.new(sort_nodes: true, group_nodes: true)
+
+        TypeSpecFromSerializers.serializers.filter_map do |serializer_class|
+          model_class = infer_model_class(serializer_class)
+          next unless model_class
+
+          file_name = serializer_class.name.underscore.tr("/", "_")
+          file_path = output_dir.join("#{file_name}.rbi")
+
+          file = build_rbi_file(serializer_class, model_class)
+          File.write(file_path, formatter.print_file(file))
+          file_path
+        end
+      end
+
+    private
+
+      # Internal: Build RBI file for a serializer.
+      #
+      # serializer_class - The serializer class
+      # model_class - The inferred model class
+      #
+      # Returns RBI::File
+      def build_rbi_file(serializer_class, model_class)
+        ::RBI::File.new(strictness: "strong") do |file|
+          file << ::RBI::Class.new(serializer_class.name) do |klass|
+            build_serializer_methods(klass, model_class.name)
+          end
+        end
+      end
+
+      # Internal: Add all serializer methods to a class.
+      #
+      # klass - RBI::Class to add methods to
+      # model_type - Name of the model class (String)
+      #
+      # Returns nothing
+      def build_serializer_methods(klass, model_type)
+        [
+          ["one", false],
+          ["one_as_hash", false],
+          ["many", true],
+          ["many_as_hash", true],
+        ].each do |method_name, is_array|
+          klass << build_method(method_name, model_type, is_array: is_array)
+        end
+      end
+
+      # Internal: Build a serializer method with signature.
+      #
+      # method_name - Name of the method (String)
+      # model_type - Name of the model class (String)
+      # is_array - Boolean indicating if method returns array
+      #
+      # Returns RBI::Method
+      def build_method(method_name, model_type, is_array:)
+        # Build signature and method parameters
+        sig_params, method_params = if is_array
+          [
+            [
+              ::RBI::SigParam.new("items", Types.items_type(model_type).to_s),
+              ::RBI::SigParam.new("options", Types.optional_hash.to_s),
+            ],
+            [
+              ::RBI::ReqParam.new("items"),
+              ::RBI::OptParam.new("options", "nil"),
+            ],
+          ]
+        else
+          [
+            [
+              ::RBI::SigParam.new("item", model_type),
+              ::RBI::SigParam.new("options", Types.optional_hash.to_s),
+            ],
+            [
+              ::RBI::ReqParam.new("item"),
+              ::RBI::OptParam.new("options", "nil"),
+            ],
+          ]
+        end
+
+        # Determine return type
+        return_type = is_array ? Types.array_of_hashes.to_s : Types.hash.to_s
+
+        # Create method and add signature
+        ::RBI::Method.new(method_name, is_singleton: true, params: method_params).tap do |method|
+          method.add_sig(params: sig_params, return_type: return_type)
+        end
+      end
+
+      # Internal: Get the default output directory for RBI files.
+      #
+      # Returns Pathname
+      def default_output_dir
+        TypeSpecFromSerializers.rbi_dir.join("dsl")
+      end
+
+      # Internal: Infer the model class for a serializer.
+      #
+      # serializer_class - The serializer class
+      #
+      # Returns Class or nil
+      def infer_model_class(serializer_class)
+        # Try to get from object_as declaration
+        if serializer_class.respond_to?(:object_name) && serializer_class.object_name
+          model_name = serializer_class.object_name.to_s.camelize
+          model_class = model_name.safe_constantize
+          return model_class if model_class
+        end
+
+        # Try to get from explicit model declaration
+        if serializer_class.respond_to?(:model_name) && serializer_class.model_name
+          return serializer_class.model_name.safe_constantize
+        end
+
+        # Fall back to naming convention using configured name transformer
+        inferred_name = TypeSpecFromSerializers.config.name_from_serializer.call(serializer_class.name)
+        inferred_name.safe_constantize
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/runner.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "io"
+
+# Public: Executes TypeSpec commands, providing conveniences for debugging.
+class TypeSpecFromSerializers::Runner
+  class MissingExecutableError < StandardError; end
+
+  def initialize(config)
+    @config = config
+  end
+
+  # Public: Executes TypeSpec with the specified arguments.
+  def run(argv, chdir: nil, with_output: nil)
+    cmd = command_for(argv)
+    opts = {}
+    opts[:chdir] = chdir if chdir
+
+    TypeSpecFromSerializers::IO.capture(*cmd, with_output: with_output, **opts)
+  rescue Errno::ENOENT => error
+    raise MissingExecutableError, "TypeSpec executable not found: #{error.message}"
+  end
+
+  private
+
+  attr_reader :config
+
+  # Internal: Returns an Array with the command to run.
+  def command_for(args)
+    [].tap do |cmd|
+      cmd.push(*tsp_executable)
+      cmd.push(*args)
+    end
+  end
+
+  # Internal: Resolves to an executable for TypeSpec.
+  def tsp_executable
+    local_tsp = config.root.join("node_modules", ".bin", "tsp")
+    return [local_tsp.to_s] if local_tsp.exist?
+
+    case config.package_manager
+    when "npm"
+      %w[npx --yes --package=@typespec/compiler tsp]
+    when "pnpm"
+      %w[pnpm dlx --package=@typespec/compiler tsp]
+    when "bun"
+      %w[bunx --bun @typespec/compiler tsp]
+    when "yarn"
+      %w[yarn dlx --package=@typespec/compiler tsp]
+    else
+      raise ArgumentError, "Unknown package manager: #{config.package_manager.inspect}"
+    end
+  end
+end