mcp_authorization 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9042f13cf2b294336b81ade0d8f97c31179a6483dde8c73c2258a7459227c7c4
-  data.tar.gz: 8be4296941e757f985bdab130472aa3f7f1bda837eae5d3b8d924078e9f27bb9
+  metadata.gz: 7365a5b287722edcac66ce63fa3ef411f6a6761e17ebb12cdfaf982e1e71c03d
+  data.tar.gz: 01cbce16f56b0ca80523014d20caee64a90cd4b82e478c9ebbf85e0cb255397a
 SHA512:
-  metadata.gz: f167384e7a8b591bb76e05677ed8f99998bcb253144f509046cb4c46e57170ef8348350b3d926a04620011e4982d91de354e41be4c01e39f08acdcec06b893ff
-  data.tar.gz: c283b35338579177226136f6fb66d778e982e9748e5d946e8ec0232134149aeaa3571033133923b5caf7c497aba14d9b2798a3c5f784c2dc50a22cdcb7e907a4
+  metadata.gz: 374d094408606c87c9c7886d3e5bb22f05794076d001054d703431e604740fb914596d2c75dbb4bc7a07eb0461f3ac660ea121d134c850b0439d18f0fe7f9542
+  data.tar.gz: 793eca82f7a52d56e65134366ed300d07d07bb9331daa49f566294e9f14af46d40ada269ebd4efcfd0a8f65733ee8981a0cbc039d3520eec4f4c43c500e3421c

data/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this gem are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.1] - 2026-05-27
+
+### Fixed
+- **Tag values containing balanced parens, commas, or pipes no longer break the parser.** ([#15](https://github.com/onboardiq/mcp_authorization/issues/15))
+
+  The historical regex parser used flat patterns (`[^)]*`, `[^,}]+`, bare `.split("|")`) to find delimiters. These patterns are not bracket-aware — a fundamental limitation of regular expressions (balanced delimiters are not a regular language). Symptom: silent miscompilation when any tag value contained the delimiter character.
+
+  Five call sites were affected, all with the same root cause:
+  - `extract_tags` — `@desc(foo (bar))` truncated at the inner `)`
+  - `compile_tagged_record` — comma inside `@desc(...)` fragmented fields
+  - `parse_record_type` — same, for nested/aliased records
+  - `parse_call_params` — flat `.split(",")` mistook commas inside `@desc(...)` AND commas inside generic types (`Hash[Symbol, untyped]`) for parameter separators
+  - union-splitting in `compile_tagged_union` and `rbs_type_to_json_schema` — pipe inside `@desc(...)` split the union mid-value
+
+  All four now go through bracket-aware primitives that track `()`, `[]`, `{}` depth while scanning.
+
+  **Concrete impact:** a field annotated `Integer @desc(The ID (NOT the question id)) @min(1)` previously compiled to `{type: "string", minLength: 1}` (wrong type AND wrong constraint keyword). Now compiles to `{type: "integer", description: "The ID (NOT the question id)", minimum: 1}`.
+
+### Changed
+- **Type-expression parsing now delegates to the official `rbs` gem.** `rbs_type_to_json_schema` previously dispatched via a regex case statement (`when "String"`, `when /\AArray\[(.+)\]\z/`, etc.). It now calls `RBS::Parser.parse_type` and walks the resulting AST through a small visitor (`visit_rbs_type`, `visit_rbs_class_instance`, `visit_rbs_union`, `visit_rbs_record`, `visit_rbs_literal`). This aligns the gem's runtime type interpretation with Steep's static interpretation — both now use the same parser, eliminating an entire class of silent divergence where the regex case statement misinterpreted types that Steep accepted.
+
+  Side benefit: types that previously fell through to the `{type: "string"}` fallback because the regex case statement didn't recognize them (e.g. `Hash[K, V]` becomes `{type: "object", additionalProperties: …}` instead of `{type: "string"}`) now have correct JSON Schema mappings. No external behavior change for the type expressions exercised by tools shipped before 0.5.1.
+
+### Added
+- Internal helpers: `find_at_depth_zero`, `split_at_depth_zero`, `peel_trailing_tag`, `find_matching_open_paren`, `each_field_in_record`. Bracket-aware primitives used by `extract_tags` and the record/union splitters.
+- **Runtime dependency on `rbs` (>= 3.0, < 4.0).** Previously transitive via Steep dev dependency; now explicit because the production code path uses it.
+
+## [0.5.0] - 2026-05-26
+
+### Changed (BREAKING)
+- **Prefix optional marker (`?key:`) is now honored consistently across all three RBS parsers.**
+
+  The three sibling parsers handled optional-field markers inconsistently:
+  - `parse_call_params` — accepted only prefix `?key:`
+  - `compile_tagged_record` — accepted only suffix `key?:`, silently treated prefix `?key:` as required
+  - `parse_record_type` — recognized neither form, silently treated all fields as required
+
+  The README documents prefix as canonical ("Prefix a param with `?` to mark it optional"), so handlers that followed the docs got unexpectedly-required fields in their compiled schemas.
+
+  **Effect on consumers:** any field declared with prefix `?key:` in a `# @rbs type input = { ... }` record, a nested/aliased record (`# @rbs type foo = { ?bar: ... }`), or an inline record inside a `#:` signature is now correctly marked optional in the JSON Schema (omitted from `required`). For a consuming monolith with ~616 such fields, the schema's `required` array shrinks accordingly and clients (e.g. LLMs producing tool calls) will no longer treat these fields as mandatory.
+
+  **If you relied on the buggy behavior** (prefix marker silently making the field required), declare the field with no marker (`key:`) to keep it required, or enforce presence inside `#call`.
+
+### Deprecated
+- **Suffix optional marker (`key?:`) is deprecated; will be removed in 0.6.0.** Suffix `key?:` continues to work in 0.5.0 (record types, call signatures, and nested aliased records) but now emits a single `Kernel#warn` per use with `category: :deprecated`. Silence with `Warning[:deprecated] = false` or `ruby -W:no-deprecated`. The warning embeds the handler's source-file path because the annotation is parsed as static text — the offending file is not on the Ruby call stack when the warning is emitted, so `uplevel:` cannot surface it.
+
+### Added
+- `RbsSchemaCompiler.parse_field_name(raw, source_file: nil)` — internal helper that turns a raw field-name token (everything before the `:`) into `[clean_name, optional?]`. Single source of truth for the three parsers. Raises `ArgumentError` on malformed input (empty, bare `"?"`, double-marked `"?key?"`, `"??key"`, `"key??"`). Tolerates whitespace around the marker (`" ? key"` → `["key", true]`).
+
+### Fixed
+- `parse_record_type` now recognizes optional markers at all. Previously, nested aliased record types like `# @rbs type foo = { ?bar: ... }` produced schemas where every field landed in `required` regardless of the marker. Caught only because the same bug existed in the sibling parsers under different shapes, hiding the test gap.
+
+### Migration notes
+- **No code changes required.** Suffix `key?:` annotations keep parsing; you'll see a deprecation warning per call site on first cache build of each handler. Migrate to prefix `?key:` at your own pace before 0.6.0.
+- If you've been relying on prefix `?key:` being silently treated as required (the buggy behavior), audit your schemas: declared-optional fields that the handler still requires must be enforced inside `#call`, not by the schema.
+- The README example in the records section was updated to use prefix `?count: Integer` to match the documented canonical form.
+
+### Notes
+- The `fountain/monolith` consumer (gem's primary downstream) has a separate migration PR tracking the suffix→prefix rewrite for ~616 affected fields, including `sig/shared/option_bank_result.rbs` and friends. That work is out of scope for this gem release and will land in the monolith repo once it bumps the `mcp_authorization` gem to 0.5.0+.
+
 ## [0.4.0] - 2026-05-21
 
 ### Added

data/README.md

@@ -380,9 +380,9 @@ The `@rbs type` comments compile to JSON Schema:
 # @rbs type result = {
 #   success: bool,
 #   message: String,
-#   count?: Integer
+#   ?count: Integer
 # }
-# (count? is optional -- excluded from "required")
+# (?count is optional -- excluded from "required")
 
 # Arrays
 # @rbs type items = Array[String]

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -1,3 +1,4 @@
+require "rbs"
 require_relative "diagnostics"
 
 module McpAuthorization
@@ -58,7 +59,7 @@ module McpAuthorization
         cached = cache_for(handler_class)
 
         schema = if cached[:raw_input]&.dig(:kind) == :record
-          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context)
+          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context, source_file: cached[:source_file])
         else
           build_input_schema(
             filter_call_signature(cached[:call_params], cached[:type_map], server_context)
@@ -206,7 +207,7 @@ module McpAuthorization
         cached = cache_for(handler_class)
 
         schema = if cached[:raw_input]&.dig(:kind) == :record
-          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context)
+          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context, source_file: cached[:source_file])
         else
           build_input_schema(
             filter_call_signature(cached[:call_params], cached[:type_map], server_context)
@@ -374,9 +375,11 @@ module McpAuthorization
       def extract_tags(type_str)
         tags = {}
 
-        # Extract all @tag(...) annotations from right to left
-        while type_str =~ /\A(.+?)\s+@(\w+)\(([^)]*)\)\s*\z/
-          type_str, tag_name, tag_value = $1.to_s.strip, $2.to_s, $3.to_s
+        # Extract all @tag(...) annotations from right to left, using a
+        # bracket-aware peeler so tag values can contain balanced parens,
+        # commas, and pipes (e.g. +@desc(foo (bar). Required.)+).
+        while (peeled = peel_trailing_tag(type_str))
+          type_str, tag_name, tag_value = peeled
 
           case tag_name
           when "requires"
@@ -429,6 +432,245 @@ module McpAuthorization
         [type_str, tags]
       end
 
+      # ---------------------------------------------------------------
+      # Bracket-aware parsing primitives
+      #
+      # The historical regex parser used flat patterns like +[^)]*+,
+      # +[^,}]++, and bare +.split("|")+ to find delimiters in RBS-flavored
+      # annotations. Those patterns can't track nested brackets — a classic
+      # limitation of regular expressions (regex are finite automata with
+      # no counter; balanced delimiters are not a regular language). The
+      # symptom was silent miscompilation when tag values contained the
+      # delimiter characters (e.g. +@desc(foo (bar). baz)+ would terminate
+      # the +)+ scan at the inner +)+, leaving the outer +@desc(...)+
+      # un-extracted and the field's type misparsed).
+      #
+      # These helpers walk the string character-by-character tracking
+      # +()+, +[]+, +{}+ depth so delimiters inside any balanced bracket
+      # pair are skipped. Used by:
+      # - +extract_tags+              — locate +@tag(...)+ with balanced value
+      # - +compile_tagged_record+     — split fields on +,+ at depth 0
+      # - +parse_record_type+         — same
+      # - +compile_tagged_union+      — split variants on +|+ at depth 0
+      # - +rbs_type_to_json_schema+   — same
+      #
+      # See the 0.5.1 CHANGELOG for the bug-class history. This is the
+      # foundation that Phase 2 of the parser migration will reuse.
+      # ---------------------------------------------------------------
+
+      # Find the position of the first character in +delims+ that occurs
+      # at bracket depth 0, scanning left-to-right from +start+. Returns
+      # +nil+ if no such position exists.
+      #
+      # Tracks +()+, +[]+, +{}+ as balanced pairs. A delimiter inside any
+      # of these pairs is skipped.
+      #
+      # @example
+      #   find_at_depth_zero("a, b, (c, d), e", [","])  #=> 1
+      #   find_at_depth_zero("a, b, (c, d), e", [","], start: 2)  #=> 4
+      #   find_at_depth_zero("(no delim here)", [","])  #=> nil
+      #
+      #: (String, Array[String], ?start: Integer) -> Integer?
+      def find_at_depth_zero(str, delims, start: 0)
+        depth = 0
+        pos = start
+        while pos < str.length
+          ch = str[pos].to_s
+          return pos if depth.zero? && delims.include?(ch)
+          if "([{".include?(ch)
+            depth += 1
+          elsif ")]}".include?(ch)
+            depth -= 1
+          end
+          pos += 1
+        end
+        nil
+      end
+
+      # Split +str+ on every occurrence of +delim+ at bracket depth 0.
+      # Returns an array of substrings (NOT stripped, NOT filtered).
+      # Callers strip / reject empties as needed to match prior semantics.
+      #
+      # @example
+      #   split_at_depth_zero("a, b, (c, d), e", ",")
+      #   #=> ["a", " b", " (c, d)", " e"]
+      #
+      #: (String, String) -> Array[String]
+      def split_at_depth_zero(str, delim)
+        parts = []
+        start = 0
+        while (pos = find_at_depth_zero(str, [delim], start: start))
+          parts << str[start...pos].to_s
+          start = pos + 1
+        end
+        parts << str[start..].to_s
+        parts
+      end
+
+      # Peel the rightmost +@tag(...)+ off +type_str+ if one exists,
+      # respecting balanced parentheses inside the tag value.
+      #
+      # Returns +[remaining_type_str, tag_name, tag_value]+ on success, or
+      # +nil+ if no trailing tag is found. The remainder is right-stripped.
+      # The tag value is not stripped (preserves intentional whitespace
+      # in +@desc(...)+ for example).
+      #
+      # The +@+ must be preceded by whitespace or be at position 0, so
+      # +"@foo"+ in the middle of a type expression isn't mistaken for a
+      # tag (this matches the prior regex semantics with +\s+@+).
+      #
+      # @example
+      #   peel_trailing_tag("Integer @desc(a (b) c) @min(1)")
+      #   #=> ["Integer @desc(a (b) c)", "min", "1"]
+      #
+      #   peel_trailing_tag("Integer @desc(a (b) c)")
+      #   #=> ["Integer", "desc", "a (b) c"]
+      #
+      #: (String) -> [String, String, String]?
+      def peel_trailing_tag(type_str)
+        trimmed = type_str.rstrip
+        return nil unless trimmed.end_with?(")")
+
+        close_pos = trimmed.length - 1
+        open_pos = find_matching_open_paren(trimmed, close_pos)
+        return nil unless open_pos
+        return nil if open_pos.zero?
+
+        # Walk backward from open_pos to capture the tag name (\w+).
+        name_end = open_pos
+        name_start = name_end
+        while name_start > 0 && trimmed[name_start - 1].to_s.match?(/\w/)
+          name_start -= 1
+        end
+        return nil if name_start == name_end
+
+        # The character immediately before the name must be '@'.
+        at_pos = name_start - 1
+        return nil unless at_pos >= 0 && trimmed[at_pos] == "@"
+
+        # The '@' must be preceded by whitespace or be at the start, so we
+        # don't accidentally peel an '@' embedded in an identifier.
+        return nil unless at_pos.zero? || trimmed[at_pos - 1].to_s.match?(/\s/)
+
+        tag_name = trimmed[name_start...name_end].to_s
+        tag_value = trimmed[(open_pos + 1)...close_pos].to_s
+        remainder = trimmed[0...at_pos].to_s.rstrip
+
+        [remainder, tag_name, tag_value]
+      end
+
+      # Find the position of the +(+ that matches the +)+ at +close_pos+
+      # in +str+. Walks backward, counting nested parens. Returns +nil+
+      # if no balanced match exists.
+      #
+      # Only tracks +()+ — other brackets inside the tag value are
+      # transparent (e.g. +@example([1, 2])+ works because +[+ and +]+
+      # don't affect paren depth).
+      #
+      #: (String, Integer) -> Integer?
+      def find_matching_open_paren(str, close_pos)
+        depth = 1
+        i = close_pos - 1
+        while i >= 0
+          case str[i]
+          when ")"
+            depth += 1
+          when "("
+            depth -= 1
+            return i if depth.zero?
+          end
+          i -= 1
+        end
+        nil
+      end
+
+      # Parse a field-name token (the part before +:+ in a record entry or
+      # call signature parameter) into its clean name and an optional flag.
+      #
+      # Recognizes both forms:
+      # - Prefix (RBS canonical, per README):     +?name:+ -> ["name", true]
+      # - Suffix (legacy, deprecated for 0.6.0):  +name?:+ -> ["name", true]
+      # - Unmarked:                                +name:+  -> ["name", false]
+      #
+      # The suffix form was historically accepted by parts of this gem
+      # but is not standard RBS. Recognizing it consistently across all
+      # three parsers (this method's callers) preserves backward
+      # compatibility while a single +Kernel#warn+ with
+      # +category: :deprecated+ steers consumers toward the prefix form.
+      # Users can silence via +Warning[:deprecated] = false+ or
+      # +-W:no-deprecated+ — the standard Ruby mechanisms.
+      #
+      # Raises +ArgumentError+ on malformed tokens. The helper produces
+      # three distinct error messages — categories grouped by which
+      # branch raises:
+      # - empty, whitespace-only, or nil input -> "empty field name"
+      # - double-marked optional after stripping (e.g. +"?key?"+) ->
+      #   "is double-marked optional"
+      # - any other shape that does not reduce to a bare +\w+
+      #   identifier (e.g. +"?"+, +"??key"+, +"key??"+, or tokens with
+      #   non-word characters) -> "invalid field name token"
+      #
+      # Whitespace adjacent to the marker is tolerated:
+      # +" ? key"+ -> ["key", true]. (Note: the three production call
+      # sites never produce such a token — their regexes don't permit
+      # internal whitespace — so this tolerance only matters if the
+      # helper is invoked directly.)
+      #
+      # @param raw [String] Token before the +:+ separator.
+      # @param source_file [String, nil] Path included in the deprecation
+      #   warning so consumers can locate the offending annotation. The
+      #   handler source file is read as text during parsing, so it is
+      #   not on the Ruby call stack — embedding the path in the message
+      #   is the only way to make the warning actionable.
+      # @return [Array(String, Boolean)] +[clean_name, optional?]+.
+      #: (String, ?source_file: String?) -> [String, bool]
+      def parse_field_name(raw, source_file: nil)
+        raise ArgumentError, "empty field name" if raw.nil? || raw.to_s.strip.empty?
+
+        trimmed = raw.to_s.strip
+        prefix = trimmed.start_with?("?")
+        suffix = trimmed.end_with?("?")
+
+        bare = trimmed
+        bare = bare.sub(/\A\?/, "").strip if prefix
+        bare = bare.sub(/\?\z/, "").strip if suffix
+
+        unless bare.match?(/\A\w+\z/)
+          raise ArgumentError, "invalid field name token: #{raw.inspect}"
+        end
+
+        if prefix && suffix
+          raise ArgumentError,
+            "field #{bare.inspect} is double-marked optional (both ?prefix and suffix?); pick one"
+        end
+
+        warn_deprecated_suffix_marker(bare, source_file) if suffix
+
+        [bare, prefix || suffix]
+      end
+
+      # Emit a deprecation warning for the legacy suffix optional marker
+      # (+key?:+). Uses +Kernel#warn+ with +category: :deprecated+ so
+      # silencing follows the standard Ruby mechanism
+      # (+Warning[:deprecated] = false+, +-W:no-deprecated+) and not a
+      # gem-specific env var.
+      #
+      # The source file path is embedded in the message because the
+      # handler annotation is parsed as static text — the offending file
+      # is not on the Ruby call stack at warn time, so +uplevel:+ cannot
+      # surface it. Embedding the path keeps the warning actionable for
+      # consumers grepping for the field name.
+      #: (String, String?) -> void
+      def warn_deprecated_suffix_marker(name, source_file)
+        location = source_file ? " (in #{source_file})" : ""
+        Kernel.warn(
+          "[mcp_authorization] Deprecated optional marker syntax: " \
+          "`#{name}?:`#{location}. Use prefix form `?#{name}:` instead. " \
+          "The suffix form will be removed in 0.6.0.",
+          category: :deprecated
+        )
+      end
+
       # Coerce a default value string from an annotation into its Ruby type.
       # Handles booleans, nil/null, integers, floats, and bare strings.
       #
@@ -542,14 +784,14 @@ module McpAuthorization
 
         # Build type map: shared imports first, then handler's own types override
         imported = load_imports(content)
-        local = parse_type_aliases(content)
+        local = parse_type_aliases(content, source_file: source_file)
         type_map = imported.merge(local)
 
         {
           type_map: type_map,
           raw_input: find_raw_type_body(content, "input"),
           raw_output: find_raw_type_body(content, "output"),
-          call_params: parse_call_params(content),
+          call_params: parse_call_params(content, source_file: source_file),
           source_file: source_file
         }
       end
@@ -622,24 +864,20 @@ module McpAuthorization
       # @param type_map [Hash] Resolved type definitions for +$ref+ lookups.
       # @param server_context [Object] Per-request context.
       # @return [Hash] JSON Schema object with +properties+, +required+, etc.
-      #: (String, Hash[String, Hash[Symbol, untyped]], untyped) -> Hash[Symbol, untyped]
-      def compile_tagged_record(raw_body, type_map, server_context)
+      #: (String, Hash[String, Hash[Symbol, untyped]], untyped, ?source_file: String?) -> Hash[Symbol, untyped]
+      def compile_tagged_record(raw_body, type_map, server_context, source_file: nil)
         properties = {}
         required = []
         dependent_required = {}
 
-        inner = raw_body.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
-
-        inner.scan(/(\w+\??)\s*:\s*([^,}]+)/) do |match|
-          key, type_str = match[0].to_s, match[1].to_s
-          type_str, tags = extract_tags(type_str.strip)
+        each_field_in_record(raw_body) do |key, type_str|
+          type_str, tags = extract_tags(type_str)
 
           next if predicate_excluded?(tags, server_context)
 
-          optional = key.end_with?("?")
-          clean_key = key.delete_suffix("?")
+          clean_key, optional = parse_field_name(key, source_file: source_file)
 
-          schema = rbs_type_to_json_schema(type_str, type_map)
+          schema = rbs_type_to_json_schema(type_str, type_map, source_file: source_file)
           properties[clean_key.to_sym] = apply_tags(schema, tags, server_context: server_context)
           required << clean_key unless optional
 
@@ -669,7 +907,7 @@ module McpAuthorization
       # @return [Hash] JSON Schema — either a single schema or a +oneOf+ wrapper.
       #: (String, Hash[String, Hash[Symbol, untyped]], untyped) -> Hash[Symbol, untyped]
       def compile_tagged_union(raw_expr, type_map, server_context)
-        parts = raw_expr.split("|").map(&:strip).reject(&:empty?)
+        parts = split_at_depth_zero(raw_expr, "|").map(&:strip).reject(&:empty?)
 
         filtered = parts.filter_map do |part|
           part, tags = extract_tags(part)
@@ -828,7 +1066,7 @@ module McpAuthorization
         resolved = {}
         aliases.each do |name, value|
           resolved[name] = if value.is_a?(String)
-            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)))
+            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)), source_file: path)
           else
             value
           end
@@ -912,8 +1150,8 @@ module McpAuthorization
       #
       # @param content [String] Full source file contents.
       # @return [Hash{String => Hash}] Type name → resolved JSON Schema.
-      #: (String) -> Hash[String, Hash[Symbol, untyped]]
-      def parse_type_aliases(content)
+      #: (String, ?source_file: String?) -> Hash[String, Hash[Symbol, untyped]]
+      def parse_type_aliases(content, source_file: nil)
         return {} if content.empty?
 
         aliases = {}
@@ -940,7 +1178,7 @@ module McpAuthorization
         resolved = {}
         aliases.each do |name, value|
           resolved[name] = if value.is_a?(String)
-            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)))
+            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)), source_file: source_file)
           else
             value
           end
@@ -961,8 +1199,8 @@ module McpAuthorization
       #
       # @param content [String] Full source file contents.
       # @return [Array<Hash>] Parameter descriptors.
-      #: (String) -> Array[Hash[Symbol, untyped]]
-      def parse_call_params(content)
+      #: (String, ?source_file: String?) -> Array[Hash[Symbol, untyped]]
+      def parse_call_params(content, source_file: nil)
         return [] if content.empty?
 
         lines = content.lines
@@ -978,10 +1216,24 @@ module McpAuthorization
 
         params = []
         if annotation =~ /\((.+)\)\s*->/m
-          $1.to_s.split(",").each do |param|
+          # Bracket-aware split — flat `.split(",")` was breaking on commas
+          # inside @desc(...) and on generic types like Hash[Symbol, untyped]
+          # where the comma is part of the type-arg list.
+          split_at_depth_zero($1.to_s, ",").each do |param|
             param = param.strip
-            next unless param =~ /\A(\?)?([\w]+):\s*(.+)\z/
-            opt, name, type = $1, $2.to_s, $3.to_s.strip
+            next if param.empty?
+
+            # Find the field-name/type separator at bracket depth 0 so
+            # `flag: Hash[Symbol, untyped]` doesn't get split on the `:`
+            # inside a nested record type.
+            colon = find_at_depth_zero(param, [":"])
+            next unless colon
+
+            raw_key = param[0...colon].to_s.strip
+            type = param[(colon + 1)..].to_s.strip
+            next if raw_key.empty? || type.empty?
+
+            name, optional = parse_field_name(raw_key, source_file: source_file)
             next if name == "server_context"
 
             type, tags = extract_tags(type)
@@ -989,7 +1241,7 @@ module McpAuthorization
             params << {
               name: name,
               type: type,
-              required: opt.nil? && !type.end_with?("?"),
+              required: !optional && !type.end_with?("?"),
               tags: tags
             }
           end
@@ -1021,20 +1273,16 @@ module McpAuthorization
       # @param body [String] Record body including surrounding braces.
       # @param type_map [Hash] Resolved types for reference lookups.
       # @return [Hash] JSON Schema object with +properties+ and +required+.
-      #: (String, ?Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
-      def parse_record_type(body, type_map = {})
+      #: (String, ?Hash[String, Hash[Symbol, untyped]], ?source_file: String?) -> Hash[Symbol, untyped]
+      def parse_record_type(body, type_map = {}, source_file: nil)
         properties = {}
         required = []
 
-        inner = body.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
+        each_field_in_record(body) do |key, type_str|
+          type_str, tags = extract_tags(type_str)
+          clean_key, optional = parse_field_name(key, source_file: source_file)
 
-        inner.scan(/(\w+):\s*([^,}]+)/) do |match|
-          key, type_str = match[0].to_s, match[1].to_s
-          type_str, tags = extract_tags(type_str.strip)
-          optional = key.end_with?("?")
-          clean_key = key.delete_suffix("?")
-
-          schema = rbs_type_to_json_schema(type_str, type_map)
+          schema = rbs_type_to_json_schema(type_str, type_map, source_file: source_file)
           properties[clean_key.to_sym] = apply_tags(schema, tags)
           required << clean_key unless optional
         end
@@ -1044,6 +1292,36 @@ module McpAuthorization
         schema
       end
 
+      # Iterate the fields of a record body, splitting on +,+ at bracket
+      # depth 0 (so commas inside +@desc(...)+ or inside nested records
+      # don't fragment a field). Yields +key, type_str+ already trimmed
+      # for each non-empty field. Outer braces are stripped before
+      # iteration.
+      #
+      # Pre-bracket-aware behavior used +inner.scan(/(\??\w+\??)\s*:\s*([^,}]+)/)+,
+      # which silently dropped any field whose type string contained a
+      # comma — or worse, split that field at the comma.
+      #
+      #: (String) { (String, String) -> void } -> void
+      def each_field_in_record(body)
+        inner = body.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
+        return if inner.empty?
+
+        split_at_depth_zero(inner, ",").each do |field|
+          field = field.strip
+          next if field.empty?
+
+          colon = find_at_depth_zero(field, [":"])
+          next unless colon
+
+          key = field[0...colon].to_s.strip
+          type_str = field[(colon + 1)..].to_s.strip
+          next if key.empty? || type_str.empty?
+
+          yield key, type_str
+        end
+      end
+
       # Convert a single RBS type expression into its JSON Schema equivalent.
       #
       # Handles:
@@ -1057,38 +1335,172 @@ module McpAuthorization
       # @param rbs_type [String] RBS type expression.
       # @param type_map [Hash] Resolved type definitions for named type lookups.
       # @return [Hash] JSON Schema hash.
-      #: (String, ?Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
-      def rbs_type_to_json_schema(rbs_type, type_map = {})
+      #: (String, ?Hash[String, Hash[Symbol, untyped]], ?source_file: String?) -> Hash[Symbol, untyped]
+      def rbs_type_to_json_schema(rbs_type, type_map = {}, source_file: nil)
         stripped = rbs_type.strip
-        case stripped
+        return { type: "string" } if stripped.empty?
+
+        # Special case preserved for backward compat with the previous
+        # regex parser: "TrueClass | FalseClass" was recognized as a
+        # boolean shorthand. RBS would parse it as Union[ClassInstance,
+        # ClassInstance], which we'd otherwise turn into a oneOf.
+        return { type: "boolean" } if stripped == "TrueClass | FalseClass"
+
+        begin
+          ast = RBS::Parser.parse_type(stripped, require_eof: true)
+        rescue RBS::ParsingError
+          # Unparseable — fall back to type_map lookup or string.
+          return type_map[stripped] || { type: "string" }
+        end
+
+        visit_rbs_type(ast, type_map)
+      end
+
+      # AST visitor: convert an +RBS::Types::*+ node into JSON Schema.
+      #
+      # Replaces the prior regex case-statement parser with a delegation
+      # to the official rbs gem. Each node type maps onto a small JSON
+      # Schema fragment. Named types (+RBS::Types::Alias+, unknown
+      # +ClassInstance+) are looked up in +type_map+, preserving the
+      # gem's named-type indirection for shared and inline aliases.
+      #
+      # @param node [RBS::Types::t] AST node from +RBS::Parser.parse_type+.
+      # @param type_map [Hash] Resolved named-type definitions.
+      # @return [Hash] JSON Schema fragment.
+      #: (untyped, Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
+      def visit_rbs_type(node, type_map)
+        case node
+        when RBS::Types::Bases::Bool
+          { type: "boolean" }
+        when RBS::Types::Bases::Any, RBS::Types::Bases::Void, RBS::Types::Bases::Nil
+          # untyped / void / nil → no constraint (LLM can pass anything)
+          { type: "string" }
+        when RBS::Types::Literal
+          visit_rbs_literal(node)
+        when RBS::Types::Optional
+          # Optional wraps a type; nullability is handled at field
+          # level (required-set), not in the JSON Schema type itself.
+          visit_rbs_type(node.type, type_map)
+        when RBS::Types::Union
+          visit_rbs_union(node, type_map)
+        when RBS::Types::Record
+          visit_rbs_record(node, type_map)
+        when RBS::Types::Tuple
+          # RBS tuples have heterogeneous element types; JSON Schema's
+          # closest analog is array with prefixItems, but for simplicity
+          # we project to a plain array.
+          { type: "array" }
+        when RBS::Types::ClassInstance
+          visit_rbs_class_instance(node, type_map)
+        when RBS::Types::Alias
+          name = node.name.to_s.sub(/\A::/, "")
+          type_map[name] || { type: "string" }
+        else
+          # Interface, Proc, Variable, ClassSingleton, Bases::Self/Class/Instance/Top/Bottom etc.
+          { type: "string" }
+        end
+      end
+
+      # Map +RBS::Types::ClassInstance+ to JSON Schema. Recognizes the
+      # Ruby primitives we care about (+String+, +Integer+, +Float+),
+      # generic +Array[T]+ / +Hash[K, V]+, and falls back to the
+      # +type_map+ for user-defined names.
+      #: (untyped, Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
+      def visit_rbs_class_instance(node, type_map)
+        name = node.name.to_s.sub(/\A::/, "")
+        case name
         when "String"
           { type: "string" }
         when "Integer"
           { type: "integer" }
-        when "Float"
+        when "Float", "Numeric"
           { type: "number" }
-        when "bool", "TrueClass | FalseClass"
-          { type: "boolean" }
-        when "true"
+        when "TrueClass"
           { type: "boolean", const: true }
-        when "false"
+        when "FalseClass"
           { type: "boolean", const: false }
-        when /\AArray\[(.+)\]\z/
-          { type: "array", items: rbs_type_to_json_schema($1.to_s, type_map) }
-        when /\A(\w+)\?\z/
-          rbs_type_to_json_schema($1.to_s, type_map)
-        when /\A\{/
-          parse_record_type(stripped, type_map)
-        when /\|/
-          parts = stripped.split("|").map(&:strip)
-          if parts.all? { |p| p.start_with?('"') && p.end_with?('"') }
-            { type: "string", enum: parts.map { |p| p.delete('"') } }
-          else
-            { oneOf: parts.map { |p| rbs_type_to_json_schema(p, type_map) } }
-          end
+        when "Array"
+          inner = node.args.first
+          inner ? { type: "array", items: visit_rbs_type(inner, type_map) } : { type: "array" }
+        when "Hash"
+          # Hash[K, V] — JSON Schema can express V as additionalProperties.
+          val = node.args[1]
+          val ? { type: "object", additionalProperties: visit_rbs_type(val, type_map) } : { type: "object" }
+        when "Symbol"
+          { type: "string" }
+        when "NilClass"
+          { type: "string" }
         else
-          type_map[stripped] || { type: "string" }
+          type_map[name] || { type: "string" }
+        end
+      end
+
+      # Map a +RBS::Types::Literal+ to a JSON Schema +const+ fragment.
+      # In a union of literals this becomes part of an +enum+; see
+      # +visit_rbs_union+ for that aggregation.
+      #: (untyped) -> Hash[Symbol, untyped]
+      def visit_rbs_literal(node)
+        case node.literal
+        when true  then { type: "boolean", const: true }
+        when false then { type: "boolean", const: false }
+        when String then { type: "string", const: node.literal }
+        when Symbol then { type: "string", const: node.literal.to_s }
+        when Integer then { type: "integer", const: node.literal }
+        else { type: "string", const: node.literal.to_s }
+        end
+      end
+
+      # Map +RBS::Types::Union+ to JSON Schema. A union of string
+      # literals becomes a +{type: "string", enum: [...]}+; any other
+      # mix becomes +{oneOf: [...]}+. This mirrors the prior regex
+      # parser's behavior so existing schemas don't drift.
+      #: (untyped, Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
+      def visit_rbs_union(node, type_map)
+        types = node.types
+
+        # All string literals → enum.
+        if types.all? { |t| t.is_a?(RBS::Types::Literal) && t.literal.is_a?(String) }
+          return { type: "string", enum: types.map { |t| t.literal.to_s } }
+        end
+
+        # TrueClass | FalseClass → boolean. RBS doesn't have a single
+        # "boolean" base class, so this pattern is what users write.
+        if types.size == 2 &&
+           types.all? { |t| t.is_a?(RBS::Types::ClassInstance) } &&
+           types.map { |t| t.name.to_s.sub(/\A::/, "") }.sort == %w[FalseClass TrueClass]
+          return { type: "boolean" }
         end
+
+        { oneOf: types.map { |t| visit_rbs_type(t, type_map) } }
+      end
+
+      # Map +RBS::Types::Record+ to a JSON Schema object. RBS handles
+      # +?key:+ optional markers natively — they land in
+      # +node.optional_fields+ rather than +node.fields+. No need for
+      # us to parse the marker manually.
+      #
+      # NOTE: this path is used when a record appears nested inside
+      # another type expression (e.g. +Array[{name: String}]+). Top-level
+      # records reached via +# @rbs type input = { ... }+ go through
+      # +compile_tagged_record+ instead so per-field tag extraction can
+      # happen before the type is parsed.
+      #: (untyped, Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
+      def visit_rbs_record(node, type_map)
+        properties = {}
+        required = []
+
+        node.fields.each do |name, type|
+          key = name.to_s
+          properties[key.to_sym] = visit_rbs_type(type, type_map)
+          required << key
+        end
+        node.optional_fields.each do |name, type|
+          properties[name.to_s.to_sym] = visit_rbs_type(type, type_map)
+        end
+
+        schema = { type: "object", properties: properties } #: Hash[Symbol, untyped]
+        schema[:required] = required if required.any?
+        schema
       end
 
       # Look up a named type in the type map. Returns a bare +{type: "object"}+

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,6 +38,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement