typespec_from_serializers 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59daa7ce75b192fd0318e7360f7fa9f8f6a91a1b4c2af9de4c7e8f6ccb281cec
-  data.tar.gz: e4fc7a830df38e1b2a846acf3ad3f8b233e2d77e339479944c5228901942408c
+  metadata.gz: 58c9803235729fabc83ae742e83822906d3ed88746e2c40f7d04d7368409a5cb
+  data.tar.gz: de245ba8d20d6b695af332f886c8b0b83a491cd563364a2c06f000c90726739e
 SHA512:
-  metadata.gz: dbb851405183db2dd6f633f3ae24a64cf3e3ce164b70ebca97b4af60ba26c4383633c2ddbd46dc381eb0cee5cdb49f66657015857ea6cf90600ff2fe52ba3278
-  data.tar.gz: 27db65226501347667a097c87e944122072f6c95f3402990f8ebc078116bdf43252b84aaed61c642c85359a20d1a80e15230c6e7c5a58c44f81b424107a73d30
+  metadata.gz: efc632aa512a2fec97c35bde59de42c1516ec23d4231be04cbc3238ca5a1bc7756c495cb9b7efcbb5a0209aade99bd6096b04229b0b6bbc4b1afae58a5b4b62b
+  data.tar.gz: 2a2fb5ca8cf367d6a22649538af11e2ee690256522caca1b63de0639d8e5b64fb8d6d5af1453ac7604a2632c439b3132652a4b906d16b0cac76c0ac4c87150f3

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # TypeSpec From Serializers Changelog
 
+## [0.5.0] - 2025-12-22
+
+### Fixed
+- Route parameter typing with `type:` now works correctly without interfering with Rails routing
+
+## [0.4.0] - 2025-12-22
+
+### Added
+- Linting system with 5 configurable rules to catch common issues during generation
+
+### Fixed
+- Add `implicitOptionality: true` to PATCH decorators to suppress TypeSpec 1.0+ warnings
+
 ## [0.3.1] - 2025-12-22
 
 ### Fixed

data/lib/typespec_from_serializers/generator.rb

@@ -26,6 +26,92 @@ module TypeSpecFromSerializers
   MEMBER_ACTIONS = %w[show update destroy].freeze
   SPECIAL_ACTIONS = %w[new edit].freeze
 
+  # Internal: Linting methods for TypeSpec generation
+  module Linting
+    extend self
+
+    @warning_count = 0
+
+    def reset_count
+      @warning_count = 0
+    end
+
+    def warning_count
+      @warning_count
+    end
+
+    def print_summary
+      return if @warning_count == 0
+      puts "\nTypeSpec generation completed with #{@warning_count} lint warning#{'s' unless @warning_count == 1}"
+    end
+
+    # Internal: Lints for missing parameter types
+    def missing_param_types(controller, route, path_param_names, param_types, config)
+      return unless enabled?(config.linting, :missing_param_types)
+
+      missing_path_params = path_param_names.select { |name| !param_types.key?(name) }
+
+      unless missing_path_params.empty?
+        @warning_count += 1
+        location = "#{controller.camelize}#{config.controller_suffix}##{route[:action]}"
+        warn "TypeSpec Lint: Missing type for path parameter(s) #{missing_path_params.join(', ')} in #{location} (#{route[:method]} #{route[:path]}). Defaulting to 'string'."
+      end
+    end
+
+    # Internal: Lints for unknown response types
+    def unknown_response_type(controller, route, response_type, config)
+      return unless enabled?(config.linting, :unknown_response_types)
+
+      if response_type == "unknown"
+        @warning_count += 1
+        location = "#{controller.camelize}#{config.controller_suffix}##{route[:action]}"
+        warn "TypeSpec Lint: Unknown response type for #{location} (#{route[:method]} #{route[:path]}). Consider adding a serializer or explicit type annotation."
+      end
+    end
+
+    # Internal: Lints for missing documentation
+    def missing_documentation(controller, route, doc, config)
+      return unless enabled?(config.linting, :missing_documentation) && config.extract_docs
+
+      if doc.nil?
+        @warning_count += 1
+        location = "#{controller.camelize}#{config.controller_suffix}##{route[:action]}"
+        warn "TypeSpec Lint: Missing documentation for #{location} (#{route[:method]} #{route[:path]}). Consider adding an RDoc comment."
+      end
+    end
+
+    # Internal: Lints for duplicate action names
+    def ambiguous_operations(name_counts, operations, config)
+      return unless enabled?(config.linting, :ambiguous_operations)
+
+      duplicates = name_counts.select { |_, count| count > 1 }
+      duplicates.each do |action, count|
+        @warning_count += 1
+        ops = operations.select { |op| op.action == action }
+        methods = ops.map { |op| op.method }.join(', ')
+        warn "TypeSpec Lint: Action '#{action}' used for multiple routes (#{methods}). Using method suffix to differentiate."
+      end
+    end
+
+    # Internal: Lints for type inference failures
+    def type_inference_failure(property, explicit_type, serializer_name, config)
+      return unless enabled?(config.linting, :type_inference_failures)
+
+      if property.type.nil? && explicit_type.nil?
+        @warning_count += 1
+        warn "TypeSpec Lint: Could not infer type for '#{property.name}' in #{serializer_name}. Consider adding explicit type annotation."
+      end
+    end
+
+    private
+
+    # Internal: Checks if a linting rule is enabled
+    def enabled?(linting_config, rule)
+      return false if linting_config == false
+      linting_config.is_a?(Hash) && linting_config[rule]
+    end
+  end
+
   # Internal: Extensions that simplify the implementation of the generator.
   module SerializerRefinements
     refine String do
@@ -96,7 +182,11 @@ module TypeSpecFromSerializers
                   column_name: options.fetch(:value_from),
                   doc: TypeSpecFromSerializers.config.extract_docs ? RDoc.method_doc(self, options.fetch(:value_from)) : nil,
                 ).tap do |property|
+                  explicit_type = property.type
                   property.infer_typespec_from(model_columns, model_enums, typespec_from, self, model_class)
+
+                  # Linting
+                  TypeSpecFromSerializers::Linting.type_inference_failure(property, explicit_type, self.name, TypeSpecFromSerializers.config)
                 end
               end
             }
@@ -138,6 +228,7 @@ module TypeSpecFromSerializers
     :openapi_path,
     :max_line_length,
     :extract_docs,
+    :linting,
     :root,
     keyword_init: true,
   ) do
@@ -416,14 +507,21 @@ module TypeSpecFromSerializers
     def build_single_line(tsp_method, operation_name)
       params = params_typespec
       params_str = params.empty? ? "()" : "(#{params})"
-      "@#{tsp_method} #{operation_name}#{params_str}: #{response_type.delete(":")};"
+      method_decorator = format_method_decorator(tsp_method)
+      "#{method_decorator} #{operation_name}#{params_str}: #{response_type.delete(":")};"
     end
 
     def multiline_format(route_line, tsp_method, operation_name)
       params_indented = all_params.map { |p| "\n    #{p}," }.join
       return_type = response_type.delete(":")
+      method_decorator = format_method_decorator(tsp_method)
+
+      "#{route_line}#{method_decorator} #{operation_name}(#{params_indented}\n  ): #{return_type};"
+    end
 
-      "#{route_line}@#{tsp_method} #{operation_name}(#{params_indented}\n  ): #{return_type};"
+    def format_method_decorator(tsp_method)
+      # PATCH operations need implicitOptionality flag in TypeSpec 1.0+
+      tsp_method == "patch" ? "@patch(\#{implicitOptionality: true})" : "@#{tsp_method}"
     end
 
     def operation_route_decorator(resource_path)
@@ -520,6 +618,8 @@ module TypeSpecFromSerializers
 
     # Public: Generates code for all serializers in the app.
     def generate(force: ENV["SERIALIZER_TYPESPEC_FORCE"])
+      Linting.reset_count
+
       @force_generation = force
       clean_output_dir if force && config.output_dir.exist?
 
@@ -536,6 +636,8 @@ module TypeSpecFromSerializers
         generate_model_for(serializer)
       end
 
+      Linting.print_summary
+
       {serializers: serializers, controllers: controllers}
     end
 
@@ -685,7 +787,7 @@ module TypeSpecFromSerializers
           path: path,
           response_type: response_type,
           route_name: route_name,
-          param_types: route.defaults[:type] || {},
+          param_types: route.defaults[:__typespec_types] || {},
         }
       end
 
@@ -723,14 +825,23 @@ module TypeSpecFromSerializers
       param_types = extract_all_param_types(controller, route)
       controller_class = "#{controller.camelize}#{config.controller_suffix}".safe_constantize
 
+      # Linting
+      Linting.missing_param_types(controller, route, path_param_names, param_types, config)
+
+      response_type = infer_operation_response_type(route)
+      doc = config.extract_docs && controller_class ? RDoc.method_doc(controller_class, route[:action]) : nil
+
+      Linting.unknown_response_type(controller, route, response_type, config)
+      Linting.missing_documentation(controller, route, doc, config)
+
       Operation.new(
         method: route[:method],
         action: simplify_operation_name(route),
         path: route[:path],
         path_params: build_path_params(path_param_names, param_types),
         body_params: build_body_params(route[:method], path_param_names, param_types),
-        response_type: infer_operation_response_type(route),
-        doc: config.extract_docs && controller_class ? RDoc.method_doc(controller_class, route[:action]) : nil,
+        response_type: response_type,
+        doc: doc,
       )
     end
 
@@ -786,6 +897,9 @@ module TypeSpecFromSerializers
       name_counts = operations.group_by(&:action).transform_values(&:count)
       name_usage = Hash.new(0)
 
+      # Linting
+      Linting.ambiguous_operations(name_counts, operations, config)
+
       operations.map do |op|
         next op unless name_counts[op.action] > 1
 
@@ -1295,6 +1409,15 @@ module TypeSpecFromSerializers
         # Extract documentation from RDoc comments
         extract_docs: true,
 
+        # Linting configuration
+        linting: {
+          missing_param_types: true,
+          unknown_response_types: true,
+          missing_documentation: true,
+          ambiguous_operations: true,
+          type_inference_failures: true,
+        },
+
         # Project root directory
         root: root,
       )

data/lib/typespec_from_serializers/routing_patch.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "action_dispatch/routing/mapper"
+require "action_dispatch/journey/route"
+
+# Internal: Minimal surgical patches to ActionDispatch routing for TypeSpec metadata support.
+#
+# This module patches Rails routing to support the `type:` parameter for specifying
+# path parameter types without interfering with Rails' route matching or URL generation.
+#
+# The type metadata is stored in route defaults under the :__typespec_types key and
+# explicitly excluded from route requirements to prevent it from affecting routing behavior.
+#
+# Examples
+#
+#   # In routes.rb
+#   resources :users, type: { id: Integer }
+#   get '/posts/:id', to: 'posts#show', type: { id: Integer }
+#
+# The patches work at three interception points:
+# 1. Mapper::Base#match - for GET/POST/PATCH/etc methods
+# 2. Mapper::Resources#resources - for resources/resource methods
+# 3. Journey::Route#requirements - filters metadata from route requirements
+module TypeSpecFromSerializers
+  # Internal: Shared logic for moving type metadata from options to defaults.
+  module RoutingPatchHelpers
+    module_function
+
+    # Internal: Moves type: parameter from route options to defaults[:__typespec_types].
+    #
+    # This ensures type metadata is stored but doesn't interfere with routing.
+    #
+    # options - Hash of route options (will be modified in place)
+    #
+    # Returns the modified options Hash
+    def move_type_to_defaults!(options)
+      return options unless options.key?(:type)
+
+      types = options.delete(:type)
+      options[:defaults] = (options[:defaults] || {}).merge(__typespec_types: types)
+      options
+    end
+  end
+
+  # Internal: Patches ActionDispatch::Routing::Mapper::Base to intercept match method.
+  #
+  # Intercepts the low-level match method used by get, post, patch, delete, etc.
+  module MapperPatch
+    def match(path, *rest, &block)
+      options = rest.last.is_a?(Hash) ? rest.pop.dup : {}
+      RoutingPatchHelpers.move_type_to_defaults!(options)
+
+      rest.push(options) unless options.empty?
+      super(path, *rest, &block)
+    end
+  end
+
+  # Internal: Patches ActionDispatch::Routing::Mapper::Resources to intercept resources method.
+  #
+  # Intercepts the resources/resource DSL methods to support type: parameter.
+  module ResourcesPatch
+    def resources(*resources, &block)
+      options = resources.extract_options!
+      RoutingPatchHelpers.move_type_to_defaults!(options)
+
+      resources.push(options) unless options.empty?
+      super(*resources, &block)
+    end
+  end
+
+  # Internal: Patches ActionDispatch::Journey::Route to filter type metadata from requirements.
+  #
+  # The requirements method is used for route matching and URL generation.
+  # We exclude :__typespec_types to ensure it doesn't affect routing behavior.
+  module RoutePatch
+    def requirements
+      super.except(:__typespec_types)
+    end
+  end
+end
+
+# Apply patches to ActionDispatch
+ActionDispatch::Routing::Mapper::Base.prepend(TypeSpecFromSerializers::MapperPatch)
+ActionDispatch::Routing::Mapper::Resources.prepend(TypeSpecFromSerializers::ResourcesPatch)
+ActionDispatch::Journey::Route.prepend(TypeSpecFromSerializers::RoutePatch)

data/lib/typespec_from_serializers/version.rb

@@ -2,5 +2,5 @@
 
 module TypeSpecFromSerializers
   # Public: This library adheres to semantic versioning.
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
 end

data/lib/typespec_from_serializers.rb

@@ -5,3 +5,4 @@ require_relative "typespec_from_serializers/dsl"
 require_relative "typespec_from_serializers/sorbet"
 require_relative "typespec_from_serializers/rbi"
 require_relative "typespec_from_serializers/railtie"
+require_relative "typespec_from_serializers/routing_patch"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typespec_from_serializers
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Danila Poyarkov
@@ -320,6 +320,7 @@ files:
 - lib/typespec_from_serializers/railtie.rb
 - lib/typespec_from_serializers/rbi.rb
 - lib/typespec_from_serializers/rdoc.rb
+- lib/typespec_from_serializers/routing_patch.rb
 - lib/typespec_from_serializers/runner.rb
 - lib/typespec_from_serializers/sorbet.rb
 - lib/typespec_from_serializers/version.rb