mcp_authorization 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9042f13cf2b294336b81ade0d8f97c31179a6483dde8c73c2258a7459227c7c4
-  data.tar.gz: 8be4296941e757f985bdab130472aa3f7f1bda837eae5d3b8d924078e9f27bb9
+  metadata.gz: dbd953dcd628ffaf2d42d3bfa024ed6e6ab5a0b8a1089be84f8505a7158aaf20
+  data.tar.gz: e510d9b492abbdbc4acb091a0a802dea803b97434923673b16711215de918d38
 SHA512:
-  metadata.gz: f167384e7a8b591bb76e05677ed8f99998bcb253144f509046cb4c46e57170ef8348350b3d926a04620011e4982d91de354e41be4c01e39f08acdcec06b893ff
-  data.tar.gz: c283b35338579177226136f6fb66d778e982e9748e5d946e8ec0232134149aeaa3571033133923b5caf7c497aba14d9b2798a3c5f784c2dc50a22cdcb7e907a4
+  metadata.gz: 71272e773f2cba13d99a1b44fb94ad53e1de079627a5546432d39bb0de0c166a047edd95ab60e43072f91c008121b16ad7bdb3548b01ebde5ffee80305323ada
+  data.tar.gz: 9e06ca547f65de3b44de14e2538b54ff24d53db6b686faf63195dd1490a88d6d20ba831f28cc69eb0ea14fd266150fe9121380a073df39279ffbdceeb443c0e0

data/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.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

@@ -58,7 +58,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 +206,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)
@@ -429,6 +429,93 @@ module McpAuthorization
         [type_str, tags]
       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 +629,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 +709,23 @@ 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|
+        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)
 
           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
 
@@ -828,7 +914,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 +998,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 +1026,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 +1047,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
@@ -980,8 +1066,10 @@ module McpAuthorization
         if annotation =~ /\((.+)\)\s*->/m
           $1.to_s.split(",").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 unless param =~ /\A(\??\w+\??):\s*(.+)\z/
+            raw_key, type = $1.to_s, $2.to_s.strip
+
+            name, optional = parse_field_name(raw_key, source_file: source_file)
             next if name == "server_context"
 
             type, tags = extract_tags(type)
@@ -989,7 +1077,7 @@ module McpAuthorization
             params << {
               name: name,
               type: type,
-              required: opt.nil? && !type.end_with?("?"),
+              required: !optional && !type.end_with?("?"),
               tags: tags
             }
           end
@@ -1021,20 +1109,19 @@ 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
 
-        inner.scan(/(\w+):\s*([^,}]+)/) do |match|
+        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)
-          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)
           required << clean_key unless optional
         end
@@ -1057,8 +1144,8 @@ 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
         when "String"
@@ -1074,17 +1161,17 @@ module McpAuthorization
         when "false"
           { type: "boolean", const: false }
         when /\AArray\[(.+)\]\z/
-          { type: "array", items: rbs_type_to_json_schema($1.to_s, type_map) }
+          { type: "array", items: rbs_type_to_json_schema($1.to_s, type_map, source_file: source_file) }
         when /\A(\w+)\?\z/
-          rbs_type_to_json_schema($1.to_s, type_map)
+          rbs_type_to_json_schema($1.to_s, type_map, source_file: source_file)
         when /\A\{/
-          parse_record_type(stripped, type_map)
+          parse_record_type(stripped, type_map, source_file: source_file)
         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) } }
+            { oneOf: parts.map { |p| rbs_type_to_json_schema(p, type_map, source_file: source_file) } }
           end
         else
           type_map[stripped] || { type: "string" }

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 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.0
 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