typespec_from_serializers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e14e0d2601ec8ee7b5efa388163e3997830d825b6f98f9df7e40ecd0248a8f6
+  data.tar.gz: d15e88b3aa25f587697c2614b867ccaa31b3438c08d11ca12bd17ddf752313b8
+SHA512:
+  metadata.gz: a2a246f2e90ce1fb583ce3bd1abc4c621c36f69fca705c853360e371beb22f668aa51ba043e4b7c3fdec9e2055577dd5df9b92c645984a4af81543aec546826b
+  data.tar.gz: 47249bf5f3c9f9af0c801790f65d0d8aa829071770f7590c15897c73fe286af61922bf92d9985bea9acb201c7d43b8c9fb5d84f2a5e71bb9720dd2a2c1d90fce

data/CHANGELOG.md

@@ -0,0 +1,102 @@
+# [2.3.0](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@2.2.0...types_from_serializers@2.3.0) (2024-08-23)
+
+
+### Features
+
+* generate types for inline serializers, exclude them from the index ([1c3657c](https://github.com/ElMassimo/types_from_serializers/commit/1c3657c61a1bc891f3219f6eaf8557cd3cd6344a)), closes [#19](https://github.com/ElMassimo/types_from_serializers/issues/19)
+
+
+
+# [2.2.0](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@2.1.0...types_from_serializers@2.2.0) (2024-08-23)
+
+
+### Bug Fixes
+
+* be more accurate regarding decimal serialization ([cd63653](https://github.com/ElMassimo/types_from_serializers/commit/cd636530a5710112a14746cc7d0e3f15016cd5e1))
+
+
+### Features
+
+* infer type from enums ([#20](https://github.com/ElMassimo/types_from_serializers/issues/20)) ([49dc61d](https://github.com/ElMassimo/types_from_serializers/commit/49dc61da2718256e9b5f5743b5a65c4746d64c2f))
+
+
+
+# [2.1.0](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@2.0.2...types_from_serializers@2.1.0) (2023-07-19)
+
+
+### Features
+
+* add `namespace` option to generate `.d.ts` files ([#9](https://github.com/ElMassimo/types_from_serializers/issues/9)) ([6f67b1a](https://github.com/ElMassimo/types_from_serializers/commit/6f67b1ad9283868e8e3325042645bceccc85b047))
+
+
+
+## [2.0.2](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@2.0.1...types_from_serializers@2.0.2) (2023-04-05)
+
+
+### Features
+
+* map citext from PostgreSQL to string ([#7](https://github.com/ElMassimo/types_from_serializers/issues/7)) ([d8c6848](https://github.com/ElMassimo/types_from_serializers/commit/d8c6848b99b0f4ba3770871f491755c229a2c4b0))
+
+
+
+## [2.0.1](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@2.0.0...types_from_serializers@2.0.1) (2023-04-03)
+
+
+### Bug Fixes
+
+* `add_attribute` now expects keyword arguments ([154b49e](https://github.com/ElMassimo/types_from_serializers/commit/154b49e463e3e6533b21520b7f0d699e6f0f47ba))
+
+
+
+## [2.0.0](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@0.1.2...types_from_serializers@2.0.0) (2023-04-02)
+
+This version adds support for `oj_serializers-2.0.2`, supporting all changes in:
+
+- https://github.com/ElMassimo/oj_serializers/pull/9
+
+### Features ✨
+
+- Now keys will match the [`transform_keys`](https://github.com/ElMassimo/oj_serializers#transforming-attribute-keys-) configuration instead of always being camelized
+- Support for [`flat_one`](https://github.com/ElMassimo/oj_serializers#composing-serializers-)
+- Use relative paths for imports to make the output configuration more flexible
+- Define the order of properties in the interface with `sort_properties_by`
+
+## [0.1.3](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@0.1.2...types_from_serializers@0.1.3) (2022-07-12)
+
+
+### Features
+
+* apply the sql mapping fallback as the default ([64898c4](https://github.com/ElMassimo/types_from_serializers/commit/64898c4e3a3f83ea67294f2200f253cd2a64aea9))
+
+
+
+## [0.1.2](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@0.1.1...types_from_serializers@0.1.2) (2022-07-12)
+
+
+### Bug Fixes
+
+* avoid having the full file path in the cache key ([556f8f6](https://github.com/ElMassimo/types_from_serializers/commit/556f8f667608fa950a3ad0647540055b1b5f1dc8))
+
+
+
+## [0.1.1](https://github.com/ElMassimo/types_from_serializers/compare/types_from_serializers@0.1.0...types_from_serializers@0.1.1) (2022-07-12)
+
+
+
+# 0.1.0 (2022-07-12)
+
+
+### Features
+
+- Start simple, no additional syntax required
+- Infers types from a related `ActiveRecord` model, using the SQL schema
+- Understands JS native types and how to map SQL columns: `string`, `boolean`, etc
+- Automatically types [associations](https://github.com/ElMassimo/oj_serializers#associations-dsl-), importing the generated types for the referenced serializers
+- Detects [conditional attributes](https://github.com/ElMassimo/oj_serializers#rendering-an-attribute-conditionally) and marks them as optional: `name?: string`
+- Fallback to a custom interface using `type_from`
+- Supports custom types and automatically adds the necessary imports
+- handle non-ActiveRecord models and extract types from unions ([ea9b2a7](https://github.com/ElMassimo/types_from_serializers/commit/ea9b2a71cb85503ff691e5ef115ab73f89b005af))
+- support specifying base serializers and additional dirs to scan ([164cfe1](https://github.com/ElMassimo/types_from_serializers/commit/164cfe17bb0527c59cf95441381aef7bf797a568))
+
+
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2021 Máximo Mussini
+
+MIT License
+
+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,35 @@
+<h1 align="center">
+TypeSpec From Serializers
+<p align="center">
+<a href="https://travis-ci.org/dannote/typespec_from_serializers"><img alt="Build Status" src="https://travis-ci.org/dannote/typespec_from_serializers.svg"/></a>
+<a href="http://inch-ci.org/github/dannote/typespec_from_serializers"><img alt="Inline docs" src="http://inch-ci.org/github/dannote/typespec_from_serializers.svg"/></a>
+<a href="https://codeclimate.com/github/dannote/typespec_from_serializers"><img alt="Maintainability" src="https://codeclimate.com/github/dannote/typespec_from_serializers/badges/gpa.svg"/></a>
+<a href="https://codeclimate.com/github/dannote/typespec_from_serializers"><img alt="Test Coverage" src="https://codeclimate.com/github/dannote/typespec_from_serializers/badges/coverage.svg"/></a>
+<a href="https://rubygems.org/gems/typespec_from_serializers"><img alt="Gem Version" src="https://img.shields.io/gem/v/typespec_from_serializers.svg?colorB=e9573f"/></a>
+<a href="https://github.com/dannote/typespec_from_serializers/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/></a>
+</p>
+</h1>
+
+[aliases]: https://vite-ruby.netlify.app/guide/development.html#import-aliases-%F0%9F%91%89
+[config options]: https://github.com/dannote/typespec_from_serializers/blob/main/lib/typespec_from_serializers/generator.rb#L82-L85
+[readme]: https://github.com/dannote/typespec_from_serializers
+
+**TypeSpec From Serializers** is a Ruby gem that automatically generates [TypeSpec](https://typespec.io) definitions from Ruby serializers and Rails routes. It is a derivative work of [`types_from_serializers`][types_from_serializers] by ElMassimo, originally designed to generate TypeScript definitions. This fork adapts the core functionality to produce TypeSpec descriptions, enabling Rails developers to define APIs compatible with TypeSpec’s ecosystem, including OpenAPI generation and client/server code scaffolding.
+
+For more information, check the main [README].
+
+### Installation 💿
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'typespec_from_serializers'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install typespec_from_serializers

data/lib/typespec_from_serializers/dsl.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+# Internal: A DSL to specify types for serializer attributes.
+module TypeSpecFromSerializers
+  module DSL
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Override: Capture the name of the model related to the serializer.
+      #
+      # name - An alias for the internal object in the serializer.
+      # model - The name of an ActiveRecord model to infer types from the schema.
+      # typespec_from - The name of a TypeScript model to infer types from.
+      def object_as(name, model: nil, typespec_from: nil)
+        # NOTE: Avoid taking memory for type information that won't be used.
+        if Rails.env.development?
+          model ||= name.is_a?(Symbol) ? name : try(:_serializer_model_name) || name
+          define_singleton_method(:_serializer_model_name) { model }
+          define_singleton_method(:_serializer_typespec_from) { typespec_from } if typespec_from
+        end
+
+        super(name)
+      end
+
+      # Public: Shortcut for typing a serializer attribute.
+      #
+      # It specifies the type for a serializer method that will be defined
+      # immediately after calling this method.
+      def type(type, **options)
+        attribute type: type, **options
+      end
+
+    private
+
+      # Override: Remove unnecessary options in production, types are only
+      # used when generating code in development.
+      unless Rails.env.development?
+        def add_attribute(name, type: nil, optional: nil, **options)
+          super(name, **options)
+        end
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/generator.rb

@@ -0,0 +1,622 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "pathname"
+
+# Public: Automatically generates TypeSpec descriptions for Ruby serializers and Rails routes.
+module TypeSpecFromSerializers
+  DEFAULT_TRANSFORM_KEYS = ->(key) { key.camelize(:lower).chomp("?") }
+
+  # Internal: Extensions that simplify the implementation of the generator.
+  module SerializerRefinements
+    refine String do
+      # Internal: Converts a name such as :user to the User constant.
+      def to_model
+        classify.safe_constantize
+      end
+    end
+
+    refine Symbol do
+      def safe_constantize
+        to_s.classify.safe_constantize
+      end
+
+      def to_model
+        to_s.to_model
+      end
+    end
+
+    refine Class do
+      # Internal: Name of the TypeSpec model.
+      def tsp_name
+        TypeSpecFromSerializers.config.name_from_serializer.call(name).tr_s(":", "")
+      end
+
+      # Internal: The base name of the TypeSpec file to be written.
+      def tsp_filename
+        TypeSpecFromSerializers.config.name_from_serializer.call(name).gsub("::", "/")
+      end
+
+      # Internal: If the serializer was defined inside a file.
+      def inline_serializer?
+        name.include?("Serializer::")
+      end
+
+      # Internal: The TypeSpec properties of the serialzeir model.
+      def tsp_properties
+        @tsp_properties ||= begin
+          model_class = _serializer_model_name&.to_model
+          model_columns = model_class.try(:columns_hash) || {}
+          model_enums = model_class.try(:defined_enums) || {}
+          typespec_from = try(:_serializer_typespec_from)
+
+          prepare_attributes(
+            sort_by: TypeSpecFromSerializers.config.sort_properties_by,
+            transform_keys: TypeSpecFromSerializers.config.transform_keys || try(:_transform_keys) || DEFAULT_TRANSFORM_KEYS,
+          )
+            .flat_map { |key, options|
+              if options[:association] == :flat
+                options.fetch(:serializer).tsp_properties
+              else
+                Property.new(
+                  name: key,
+                  type: options[:serializer] || options[:type],
+                  optional: options[:optional] || options.key?(:if),
+                  multi: options[:association] == :many,
+                  column_name: options.fetch(:value_from),
+                ).tap do |property|
+                  property.infer_typespec_from(model_columns, model_enums, typespec_from)
+                end
+              end
+            }
+        end
+      end
+
+      # Internal: A first pass of gathering types for the serializer attributes.
+      def tsp_model
+        @tsp_model ||= Interface.new(
+          name: tsp_name,
+          filename: tsp_filename,
+          properties: tsp_properties,
+        )
+      end
+    end
+  end
+
+  # Internal: The configuration for TypeSpec generation.
+  Config = Struct.new(
+    :base_serializers,
+    :serializers_dirs,
+    :output_dir,
+    :custom_typespec_dir,
+    :name_from_serializer,
+    :global_types,
+    :sort_properties_by,
+    :sql_to_typespec_type_mapping,
+    :action_to_operation_mapping,
+    :skip_serializer_if,
+    :transform_keys,
+    :namespace,
+    keyword_init: true,
+  ) do
+    def relative_custom_typespec_dir
+      @relative_custom_typespec_dir ||= (custom_typespec_dir || output_dir.parent).relative_path_from(output_dir.join("models"))
+    end
+
+    def unknown_type
+      :unknown
+    end
+  end
+
+  # Internal: Information to generate a TypeSpec model for a serializer.
+  Interface = Struct.new(
+    :name,
+    :filename,
+    :properties,
+    keyword_init: true,
+  ) do
+    using SerializerRefinements
+
+    def inspect
+      to_h.inspect
+    end
+
+    # Internal: Returns a list of imports for types used in this model.
+    def used_imports
+      association_serializers, attribute_types = properties.map(&:type).compact.uniq
+        .partition { |type| type.respond_to?(:tsp_model) }
+
+      serializer_type_imports = association_serializers.map(&:tsp_model)
+        .map { |type| [type.name, relative_path(type.pathname, pathname)] }
+
+      custom_type_imports = attribute_types
+        .flat_map { |type| extract_typespec_types(type.to_s) }
+        .uniq
+        .reject { |type| global_type?(type) }
+        .map { |type|
+          type_path = TypeSpecFromSerializers.config.relative_custom_typespec_dir.join(type)
+          [type, relative_path(type_path, pathname)]
+        }
+
+      (custom_type_imports + serializer_type_imports)
+        .map { |model, filename| %(import "#{filename}.tsp";\n) }
+    end
+
+    def as_typespec
+      indent = TypeSpecFromSerializers.config.namespace ? 2 : 1
+      <<~TSP.gsub(/\n$/, "")
+        model #{name} {
+        #{"  " * indent}#{properties.index_by(&:name).values.map(&:as_typespec).join("\n#{"  " * indent}")}
+        #{"  " * (indent - 1)}}
+      TSP
+    end
+
+  protected
+
+    def pathname
+      @pathname ||= Pathname.new(filename)
+    end
+
+    # Internal: Calculates a relative path that can be used in an import.
+    def relative_path(target_path, importer_path)
+      path = target_path.relative_path_from(importer_path.parent).to_s
+      path.start_with?(".") ? path : "./#{path}"
+    end
+
+    # Internal: Extracts any types inside generics or array types.
+    def extract_typespec_types(type)
+      type.split(".").first
+    end
+
+    # NOTE: Treat uppercase names as custom types.
+    # Lowercase names would be native types, such as :string and :boolean.
+    def global_type?(type)
+      type[0] == type[0].downcase || TypeSpecFromSerializers.config.global_types.include?(type)
+    end
+  end
+
+  # Internal: The type metadata for a serializer attribute.
+  Property = Struct.new(
+    :name,
+    :type,
+    :optional,
+    :multi,
+    :column_name,
+    keyword_init: true,
+  ) do
+    using SerializerRefinements
+
+    def inspect
+      to_h.inspect
+    end
+
+    # Internal: Infers the property's type by checking a corresponding SQL
+    # column, or falling back to a TypeSpec model if provided.
+    def infer_typespec_from(columns_hash, defined_enums, tsp_model)
+      if type
+        type
+      elsif (enum = defined_enums[column_name.to_s])
+        self.type = enum.keys.map(&:inspect).join(" | ")
+      elsif (column = columns_hash[column_name.to_s])
+        self.multi = true if column.try(:array)
+        self.optional = true if column.null && !column.default
+        self.type = TypeSpecFromSerializers.config.sql_to_typespec_type_mapping[column.type]
+      elsif tsp_model
+        self.type = "#{tsp_model}.#{name}::type"
+      end
+    end
+
+    def as_typespec
+      type_str = if type.respond_to?(:tsp_name)
+        type.tsp_name
+      else
+        type || TypeSpecFromSerializers.config.unknown_type
+      end
+
+      "#{name}#{"?" if optional}: #{type_str}#{"[]" if multi};"
+    end
+  end
+
+  # Internal: Represents a TypeSpec resource interface
+  Resource = Struct.new(:name, :path, :operations, keyword_init: true) do
+    def as_typespec
+      <<~TSP
+        #{"  " * 1}@route("#{path}")
+        #{"  " * 1}interface #{name} {
+        #{"  " * 1}#{operations.map(&:as_typespec).join("\n  ")}
+        #{"  " * 1}}
+      TSP
+    end
+  end
+
+  # Internal: Represents a TypeSpec operation within a resource
+  Operation = Struct.new(:method, :action, :path_params, :response_type, keyword_init: true) do
+    def as_typespec
+      method_map = {
+        "GET" => "get",
+        "POST" => "post",
+        "PUT" => "put",
+        "PATCH" => "patch",
+        "DELETE" => "delete",
+      }
+      tsp_method = method_map[method] || method.downcase
+      operation_name = TypeSpecFromSerializers.config.action_to_operation_mapping[action] || action
+      params = params_typespec
+      params_str = params.empty? ? "()" : "(#{params})"
+
+      "#{"  " * 1}@#{tsp_method} #{operation_name}#{params_str}: #{response_type.gsub("::", "")};"
+    end
+
+    def params_typespec
+      params = []
+      params += path_params.map { |param| "@path #{param}: string" } if path_params.any?
+      params << "@body body: #{response_type.gsub("::", "")}" if %w[POST PUT PATCH].include?(method)
+      params.join(", ")
+    end
+  end
+
+  # Internal: Structure to keep track of changed files.
+  class Changes
+    def initialize(dirs)
+      @added = Set.new
+      @removed = Set.new
+      @modified = Set.new
+      track_changes(dirs)
+    end
+
+    def updated?
+      @modified.any? || @added.any? || @removed.any?
+    end
+
+    def any_removed?
+      @removed.any?
+    end
+
+    def modified_files
+      @modified
+    end
+
+    def only_modified?
+      @added.empty? && @removed.empty?
+    end
+
+    def clear
+      @added.clear
+      @removed.clear
+      @modified.clear
+    end
+
+  private
+
+    def track_changes(dirs)
+      Listen.to(*dirs, only: %r{.rb$}) do |modified, added, removed|
+        modified.each { |file| @modified.add(file) }
+        added.each { |file| @added.add(file) }
+        removed.each { |file| @removed.add(file) }
+      end.start
+    end
+  end
+
+  class << self
+    using SerializerRefinements
+
+    attr_reader :force_generation
+
+    # Public: Configuration of the code generator.
+    def config
+      (@config ||= default_config(root)).tap do |config|
+        yield(config) if block_given?
+      end
+    end
+
+    # Public: Generates code for all serializers in the app.
+    def generate(force: ENV["SERIALIZER_TYPESPEC_FORCE"])
+      @force_generation = force
+      config.output_dir.rmtree if force && config.output_dir.exist?
+
+      if config.namespace
+        load_serializers(all_serializer_files) if force
+      else
+        generate_index_file
+      end
+
+      generate_routes
+
+      loaded_serializers.each do |serializer|
+        generate_model_for(serializer)
+      end
+    end
+
+    def generate_changed
+      if changes.updated?
+        config.output_dir.rmtree if changes.any_removed?
+        load_serializers(changes.modified_files)
+        generate
+        changes.clear
+      end
+    end
+
+    # Internal: Defines a TypeSpec model for the serializer.
+    def generate_model_for(serializer)
+      model = serializer.tsp_model
+
+      write_if_changed(filename: "models/#{model.filename}", cache_key: model.inspect, extension: "tsp") {
+        serializer_model_content(model)
+      }
+    end
+
+    # Internal: Allows to import all serializer types from a single file.
+    def generate_index_file
+      cache_key = all_serializer_files.map { |file| file.delete_prefix(root.to_s) }.join
+      write_if_changed(filename: "index", cache_key: cache_key) {
+        load_serializers(all_serializer_files)
+        serializers_index_content(loaded_serializers)
+      }
+    end
+
+    # Internal: Generates TypeSpec routes from Rails routes
+    def generate_routes
+      return unless defined?(Rails) && Rails.application
+
+      routes = collect_rails_routes
+      cache_key = routes.map { |r| r.operations.map { |op| "#{op.method}#{r.path}#{op.action}" }.join }.join
+      write_if_changed(filename: "routes", cache_key: cache_key) {
+        routes_content(routes)
+      }
+    end
+
+    # Internal: Checks if it should avoid generating an model.
+    def skip_serializer?(serializer)
+      serializer.name.in?(config.base_serializers) ||
+        config.skip_serializer_if.call(serializer)
+    end
+
+    # Internal: Returns an object compatible with FileUpdateChecker.
+    def track_changes
+      changes
+    end
+
+  private
+
+    def root
+      defined?(Rails) ? Rails.root : Pathname.new(Dir.pwd)
+    end
+
+    def changes
+      @changes ||= Changes.new(config.serializers_dirs)
+    end
+
+    def all_serializer_files
+      config.serializers_dirs.flat_map { |dir| Dir["#{dir}/**/*.rb"] }.sort
+    end
+
+    def load_serializers(files)
+      files.each { |file| require file }
+    end
+
+    def loaded_serializers
+      config.base_serializers.map(&:constantize)
+        .flat_map(&:descendants)
+        .uniq
+        .sort_by(&:name)
+        .reject { |s| skip_serializer?(s) }
+    rescue NameError
+      raise ArgumentError, "Please ensure all your serializers extend BaseSerializer, or configure `config.base_serializers`."
+    end
+
+    # Internal: Collects routes from Rails and groups them into resources
+    def collect_rails_routes
+      return [] unless defined?(Rails) && Rails.application
+
+      routes_by_controller = Rails.application.routes.routes.each_with_object(Hash.new { |h, k| h[k] = [] }) do |route, hash|
+        next unless route.defaults[:controller] && route.verb.present?
+
+        controller = route.defaults[:controller]
+        action = route.defaults[:action]
+        method = route.verb.split("|").first
+        path = route.path.spec.to_s.sub("(.:format)", "")
+        response_type = infer_response_type(controller, action) || "unknown"
+
+        unless hash[controller].any? { |r| r[:method] == method && r[:action] == action }
+          hash[controller] << {
+            method: method,
+            action: action,
+            path: path,
+            response_type: response_type,
+          }
+        end
+      end
+
+      routes_by_controller.map do |controller, routes|
+        path_segments = routes.map { |r| r[:path].split("/")[1..-1] || [] }.uniq.sort_by(&:length)
+        base_path = path_segments.any? ? path_segments.first.join("/")&.split("/{")&.first || controller : controller
+
+        operations = routes.map do |route|
+          path_params = route[:path].scan(/{([^}]+)}/).flatten
+          response_type = if route[:response_type] == route[:action]
+            "unknown"
+          else
+            (route[:action] == "index") ? "#{route[:response_type]}[]" : route[:response_type]
+          end
+          Operation.new(
+            method: route[:method],
+            action: route[:action],
+            path_params: (route[:action] == "show") ? ["id"] : path_params,
+            response_type: response_type,
+          )
+        end
+        Resource.new(
+          name: controller.tr("/", "_").camelize,
+          path: "/#{base_path}",
+          operations: operations,
+        )
+      end
+    end
+
+    # Internal: Infers the response type based on controller and action
+    def infer_response_type(controller, action)
+      controller_class = "#{controller.camelize}Controller".safe_constantize
+      return nil unless controller_class
+
+      model_name = controller.singularize.camelize
+      serializer_class = "#{model_name}Serializer".safe_constantize
+      serializer_class&.tsp_name
+    end
+
+    # Internal: Generates the routes.tsp content with resources
+    def routes_content(routes)
+      imports = routes.flat_map { |r| r.operations.map(&:response_type) }.compact.uniq.map do |type|
+        base_type = (type || "unknown").split("[]").first.gsub("::", "")
+        next if base_type == "unknown"
+        relative_path = "./#{base_type}.tsp"
+        %(import "#{relative_path}";\n)
+      end.compact.uniq.join
+
+      resources = routes.map(&:as_typespec).join("\n").strip
+      <<~TSP
+        //
+        // DO NOT MODIFY: This file was automatically generated by TypeSpecFromSerializers.
+        import "@typespec/http";
+        
+        #{imports}
+        using TypeSpec.Http;
+
+        namespace Routes {
+          #{resources}
+        }
+      TSP
+    end
+
+    def default_config(root)
+      Config.new(
+        # The base serializers that all other serializers extend.
+        base_serializers: ["BaseSerializer"],
+
+        # The dirs where the serializer files are located.
+        serializers_dirs: [root.join("app/serializers").to_s],
+
+        # The dir where model files are placed.
+        output_dir: root.join(defined?(ViteRuby) ? ViteRuby.config.source_code_dir : "app/frontend").join("typespec/generated"),
+
+        # Remove the serializer suffix from the class name.
+        name_from_serializer: ->(name) {
+          name.split("::").map { |n| n.delete_suffix("Serializer") }.join("::")
+        },
+
+        # Types that don't need to be imported in TypeSpec.
+        global_types: [
+          "Array",
+          "Record",
+          "Date",
+        ].to_set,
+
+        # Allows to choose a different sort order, alphabetical by default.
+        sort_properties_by: :name,
+
+        # Allows to avoid generating a serializer.
+        skip_serializer_if: ->(serializer) { false },
+
+        # Maps SQL column types to TypeSpec native and custom types.
+        sql_to_typespec_type_mapping: {
+          boolean: :boolean,
+          date: :plainDate,
+          datetime: :utcDateTime,
+          timestamp: :utcDateTime,
+          timestamptz: :offsetDateTime,
+          time: :plainTime,
+          decimal: :decimal128,
+          numeric: :decimal128,
+          integer: :int32,
+          bigint: :int64,
+          smallint: :int16,
+          tinyint: :int8,
+          float: :float32,
+          double: :float64,
+          real: :float32,
+          string: :string,
+          text: :string,
+          citext: :string,
+          binary: :bytes,
+          blob: :bytes,
+          json: "Record<string, unknown>",
+          jsonb: "Record<string, unknown>",
+          uuid: :string,
+        },
+
+        # Map Rails actions to TypeSpec operations
+        action_to_operation_mapping: {
+          "index" => "list",
+          "show" => "read",
+          "create" => "create",
+          "update" => "update",
+          "destroy" => "delete",
+        },
+
+        # Allows to transform keys, useful when converting objects client-side.
+        transform_keys: nil,
+
+        # Allows scoping typespec definitions to a namespace
+        namespace: nil,
+      )
+    end
+
+    # Internal: Writes if the file does not exist or the cache key has changed.
+    # The cache strategy consists of a comment on the first line of the file.
+    #
+    # Yields to receive the rendered file content when it needs to.
+    def write_if_changed(filename:, cache_key:, extension: "tsp")
+      filename = config.output_dir.join("#{filename}.#{extension}")
+      FileUtils.mkdir_p(filename.dirname)
+      cache_key_comment = "// TypeSpecFromSerializers CacheKey #{Digest::MD5.hexdigest(cache_key)}\n"
+      File.open(filename, "a+") { |file|
+        if stale?(file, cache_key_comment)
+          file.truncate(0)
+          file.write(cache_key_comment)
+          file.write(yield)
+        end
+      }
+    end
+
+    def serializers_index_content(serializers)
+      <<~TSP
+        //
+        // DO NOT MODIFY: This file was automatically generated by TypeSpecFromSerializers.
+
+        import "./routes.tsp";
+        #{serializers.reject(&:inline_serializer?).map { |s|
+          %(import "./models/#{s.tsp_filename}.tsp";)
+        }.join("\n")}
+      TSP
+    end
+
+    def serializer_model_content(model)
+      config.namespace ? declaration_model_definition(model) : standard_model_definition(model)
+    end
+
+    def standard_model_definition(model)
+      <<~TSP
+        //
+        // DO NOT MODIFY: This file was automatically generated by TypeSpecFromSerializers.
+        #{model.used_imports.join}
+        #{model.as_typespec}
+      TSP
+    end
+
+    def declaration_model_definition(model)
+      <<~TSP
+        //
+        // DO NOT MODIFY: This file was automatically generated by TypeSpecFromSerializers.
+        #{model.used_imports.empty? ? "export {}\n" : model.used_imports.join}
+        namespace #{config.namespace} {
+          #{model.as_typespec}
+        }
+      TSP
+    end
+
+    # Internal: Returns true if the cache key has changed since the last codegen.
+    def stale?(file, cache_key_comment)
+      @force_generation || file.gets != cache_key_comment
+    end
+  end
+end

data/lib/typespec_from_serializers/railtie.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+class TypeSpecFromSerializers::Railtie < Rails::Railtie
+  railtie_name :typespec_from_serializers
+
+  # Automatically generates code whenever a serializer is loaded.
+  if defined?(Rails.env) && Rails.env.development?
+    require_relative "generator"
+
+    initializer "typespec_from_serializers.reloader" do |app|
+      if Gem.loaded_specs["listen"]
+        require "listen"
+
+        app.config.after_initialize do
+          app.reloaders << TypeSpecFromSerializers.track_changes
+        end
+
+        app.config.to_prepare do
+          TypeSpecFromSerializers.generate_changed
+        end
+      else
+        app.config.to_prepare do
+          TypeSpecFromSerializers.generate
+        end
+
+        Rails.logger.warn "Add 'listen' to your Gemfile to automatically generate code on serializer changes."
+      end
+    end
+  end
+
+  # Suitable when triggering code generation manually.
+  rake_tasks do |app|
+    namespace :typespec_from_serializers do
+      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)
+        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")
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TypeSpecFromSerializers
+  # Public: This library adheres to semantic versioning.
+  VERSION = "0.1.0"
+end

data/lib/typespec_from_serializers.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "typespec_from_serializers/version"
+require_relative "typespec_from_serializers/dsl"
+require_relative "typespec_from_serializers/railtie"

metadata

@@ -0,0 +1,285 @@
+--- !ruby/object:Gem::Specification
+name: typespec_from_serializers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Danila Poyarkov
+- Máximo Mussini
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: oj_serializers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rspec-snapshot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: js_from_routes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: typespec_from_serializers helps you by automatically generating TypeSpec
+  descriptions for your JSON serializers, allowing you typecheck your frontend code
+  to ship fast and with confidence.
+email:
+- maximomussini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/typespec_from_serializers.rb
+- lib/typespec_from_serializers/dsl.rb
+- lib/typespec_from_serializers/generator.rb
+- lib/typespec_from_serializers/railtie.rb
+- lib/typespec_from_serializers/version.rb
+homepage: https://github.com/dannote/typespec_from_serializers
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Generate TypeSpec descriptions from your JSON serializers.
+test_files: []