typemap 0.1.0

data/lib/typemap/mapper/type_builder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # Turns a type syntax tree (see {TypeParser}) into the {Type} the mapper checks, resolving
+    # constant names from the declaring namespace. Both type strategies end here, so they accept
+    # exactly the same subset; anything outside it raises "unsupported type".
+    #
+    # @api private
+    module TypeBuilder
+      # @param node [Array] the syntax tree
+      # @param namespace [String, nil] the declaring class's full name, for relative names
+      # @return [Object] a {Type}
+      # @raise [DefinitionError] on an unsupported type or an unknown constant
+      def self.build(node, namespace)
+        case node.first
+        when :optional then optional(build(node[1], namespace))
+        when :union then union(node[1], namespace)
+        when :literal then literals([node[1]])
+        when :bool then Type::Bool.new
+        when :nil then unsupported("nil alone")
+        when :untyped then unsupported("untyped; for plain data passed through as the file holds it, write Object")
+        when :name then named(node[1], node[2], namespace)
+        else raise ArgumentError, "not a type node: #{node.inspect}"
+        end
+      end
+
+      # @param inner [Object] a {Type}
+      # @return [Type::Optional]
+      def self.optional(inner)
+        inner.is_a?(Type::Optional) ? inner : Type::Optional.new(inner: inner)
+      end
+
+      # `"a" | "b"`, optionally with `nil` among them; a union of anything but literals is
+      # outside the subset.
+      def self.union(members, namespace)
+        nilable = members.any? { |member| member.first == :nil }
+        rest = members.reject { |member| member.first == :nil }
+        unsupported("a union of #{rest.size} types besides nil") if rest.empty?
+        built = rest.size == 1 ? build(rest.first, namespace) : literals(rest.map { |member| literal_value(member) })
+        nilable ? optional(built) : built
+      end
+
+      def self.literal_value(node)
+        unsupported("a union of anything but literals: #{node.inspect}") unless node.first == :literal
+        node[1]
+      end
+
+      def self.literals(values)
+        values.each do |value|
+          supported = [String, Integer, TrueClass, FalseClass].any? { |klass| value.is_a?(klass) }
+          unsupported("the literal #{value.inspect}: a file cannot hold one") unless supported
+        end
+        Type::Literals.new(values: values)
+      end
+
+      def self.named(name, args, namespace)
+        constant = NameResolver.resolve(name, namespace)
+        if [Integer, Float, String, Object].include?(constant)
+          unsupported("#{name}[…]") unless args.empty?
+          constant == Object ? Type::Plain.new : Type::Scalar.new(klass: constant)
+        elsif constant == Array
+          unsupported("Array without exactly one element type") unless args.size == 1
+          Type::ArrayOf.new(element: build(args.first, namespace))
+        elsif constant == Hash
+          hash_of(args, namespace)
+        elsif constant.is_a?(Class) && args.empty?
+          Type::ClassRef.new(klass: constant)
+        else
+          unsupported(args.empty? ? name : "#{name}[…]")
+        end
+      end
+
+      def self.hash_of(args, namespace)
+        unsupported("Hash without a key and a value type") unless args.size == 2
+        key = build(args.first, namespace)
+        unsupported("Hash[#{key}, …]: a key is always a String") unless key == Type::Scalar.new(klass: String)
+        Type::HashOf.new(value: build(args.last, namespace))
+      end
+
+      private_class_method :union, :literal_value, :literals, :named, :hash_of
+
+      # @raise [DefinitionError] always
+      def self.unsupported(what)
+        raise DefinitionError, "unsupported type: #{what}"
+      end
+    end
+  end
+end

data/lib/typemap/mapper/type_parser.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # Parses a type string in the subset of RBS the mapper supports into a syntax tree for
+    # {TypeBuilder}; `BasicTypes` uses it so the `rbs` gem stays optional. The grammar:
+    #
+    #     type    := postfix ('|' postfix)*
+    #     postfix := primary '?'*
+    #     primary := '(' type ')' | literal | 'bool' | 'nil' | 'untyped' | name ('[' type (',' type)* ']')?
+    #     name    := '::'? Constant ('::' Constant)*
+    #     literal := "string" | 'string' | integer | true | false
+    #
+    # A tree node is an Array: `[:name, "Tuile::Size", [args]]`, `[:optional, node]`,
+    # `[:union, [nodes]]`, `[:literal, value]`, `[:bool]`, `[:nil]`, `[:untyped]` — the same nodes
+    # `RBSTypes` builds from the `rbs` gem's AST, so both strategies share one builder.
+    #
+    # @api private
+    class TypeParser
+      TOKEN = /\s*(?:(::)|([A-Za-z_]\w*)|("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')|(-?\d+(?:\.\d+)?)|([\[\],|?()]))/
+      private_constant :TOKEN
+
+      # @param source [String] the type as written, `"Array[String]?"`
+      # @return [Array] the syntax tree
+      # @raise [DefinitionError] on a syntax error
+      def self.parse(source)
+        new(source).parse
+      end
+
+      # @param source [String]
+      def initialize(source)
+        @source = source
+        @tokens = tokenize(source)
+        @pos = 0
+      end
+
+      # @return [Array] the syntax tree
+      # @raise [DefinitionError] on a syntax error
+      def parse
+        node = union
+        fail_at("unexpected #{peek.inspect}") if peek
+        node
+      end
+
+      private
+
+      def tokenize(source)
+        tokens = []
+        rest = source
+        until rest.strip.empty?
+          match = TOKEN.match(rest)
+          unless match&.begin(0)&.zero?
+            raise DefinitionError,
+                  "type #{source.inspect}: cannot read #{rest.strip.inspect}"
+          end
+
+          tokens << match.captures.compact.first
+          rest = match.post_match
+        end
+        tokens
+      end
+
+      def peek = @tokens[@pos]
+
+      def take
+        @tokens[@pos].tap { @pos += 1 }
+      end
+
+      def expect(token)
+        fail_at("expected #{token.inspect}, got #{peek.inspect}") unless peek == token
+        take
+      end
+
+      def fail_at(detail)
+        raise DefinitionError, "type #{@source.inspect}: #{detail}"
+      end
+
+      def union
+        members = [postfix]
+        while peek == "|"
+          take
+          members << postfix
+        end
+        members.size == 1 ? members.first : [:union, members]
+      end
+
+      def postfix
+        node = primary
+        while peek == "?"
+          take
+          node = [:optional, node] unless node.first == :optional
+        end
+        node
+      end
+
+      def primary
+        token = peek
+        fail_at("unexpected end") if token.nil?
+        return parenthesized if token == "("
+        return [:literal, literal(take)] if token.match?(/\A(?:["'-]|\d)/)
+
+        case token
+        when "bool" then take && [:bool]
+        when "nil" then take && [:nil]
+        when "untyped" then take && [:untyped]
+        when "true" then take && [:literal, true]
+        when "false" then take && [:literal, false]
+        else name
+        end
+      end
+
+      def parenthesized
+        expect("(")
+        node = union
+        expect(")")
+        node
+      end
+
+      def literal(token)
+        case token
+        when /\A"/ then token[1..-2].gsub(/\\(.)/, '\1')
+        when /\A'/ then token[1..-2].gsub(/\\(.)/, '\1')
+        when /\./ then fail_at("a Float literal is not a type in RBS: #{token}")
+        else Integer(token)
+        end
+      end
+
+      def name
+        parts = []
+        absolute = peek == "::"
+        take if absolute
+        loop do
+          part = take
+          fail_at("expected a constant, got #{part.inspect}") unless part&.match?(/\A[A-Z]/)
+          parts << part
+          break unless peek == "::"
+
+          take
+        end
+        [:name, "#{"::" if absolute}#{parts.join("::")}", arguments]
+      end
+
+      def arguments
+        return [] unless peek == "["
+
+        take
+        args = [union]
+        while peek == ","
+          take
+          args << union
+        end
+        expect("]")
+        args
+      end
+    end
+  end
+end

data/lib/typemap/mapper/wording.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # How a load error words the found value and the fix, for the source the app names in
+    # `load(..., source:)`. The types detect the mistake in the Hash; a wording only spells it:
+    #
+    #   :ruby  server: expected Array[Server], got a single Server; wrap it in an array
+    #   :toml  server: expected Array[Server], got a single Server; write [[server]], not [server], or server = [{…}]
+    #
+    # Each source is a module answering the same six calls: `found(value)`, `wrap(path, entry)`,
+    # `unwrap(path)`, `quote(value)`, `unquote` and `misplaced(key, path, owner)`. A hint returns
+    # `nil` for none. A dump error is worded for {Ruby}: its reader is the programmer.
+    #
+    # @api private
+    module Wording
+      # @param source [Symbol] `:ruby`, `:toml`, `:json` or `:yaml`
+      # @return [Module] the wording for it
+      # @raise [ArgumentError] on any other source
+      def self.for(source)
+        case source
+        when :ruby then Ruby
+        when :toml then TOML
+        when :json then JSON
+        when :yaml then YAML
+        else raise ArgumentError, "source: must be :ruby, :toml, :json or :yaml, got #{source.inspect}"
+        end
+      end
+
+      # @param value [Object]
+      # @return [String] its `inspect`, cut at 60 characters
+      def self.inspected(value)
+        text = value.inspect
+        text.length > 61 ? "#{text[0, 60]}…" : text
+      end
+
+      # @param key [String]
+      # @param owner [String] the enclosing object's path, `""` for the top level
+      # @return [String] `sandbox belongs to the top level`
+      def self.belongs(key, owner) = "#{key} belongs to #{owner.empty? ? "the top level" : owner}"
+
+      QUOTE = "quote it to make it a string"
+      UNQUOTE = "remove the quotes"
+
+      # A Hash built in Ruby: the found value's class names the mistake, and there are no quotes
+      # to add or remove.
+      #
+      #   value: expected String, got Integer 70
+      module Ruby
+        # @param value [Object]
+        # @return [String] `Integer 70`; bare for `nil`, `true`, `false` and an inspect that names
+        #   its class already, `#<data Server …>`
+        def self.found(value)
+          text = Wording.inspected(value)
+          [nil, true, false].include?(value) || text.start_with?("#<") ? text : "#{value.class} #{text}"
+        end
+
+        # @param _path [String]
+        # @param _entry [Boolean]
+        # @return [String]
+        def self.wrap(_path, _entry) = "wrap it in an array"
+
+        # @param _path [String]
+        # @return [String]
+        def self.unwrap(_path) = "unwrap it"
+
+        # @param _value [Object]
+        # @return [nil]
+        def self.quote(_value) = nil
+
+        # @return [nil]
+        def self.unquote = nil
+
+        # @param key [String]
+        # @param _path [String]
+        # @param owner [String]
+        # @return [String]
+        def self.misplaced(key, _path, owner) = Wording.belongs(key, owner)
+      end
+
+      # TOML: headers spelled from the path, `llm[0].servers` → `[[llm.servers]]`, since a header
+      # names no index.
+      #
+      # == Implementation details
+      #
+      # An array hint names the inline spelling too, `server = [{…}]`: Typemap can't tell which
+      # one the file used.
+      module TOML
+        # @param value [Object]
+        # @return [String]
+        def self.found(value) = Wording.inspected(value)
+
+        # @param path [String]
+        # @param entry [Boolean] whether the lone value is an object
+        # @return [String]
+        def self.wrap(path, entry)
+          return "wrap it in [ ]" unless entry && keyed?(path)
+
+          "write #{header(path, array: true)}, not #{header(path)}, or #{key(path)} = [{…}]"
+        end
+
+        # @param path [String]
+        # @return [String]
+        def self.unwrap(path)
+          return "remove the [ ]" unless keyed?(path)
+
+          "write #{header(path)}, not #{header(path, array: true)}, or #{key(path)} = {…}"
+        end
+
+        # @param _value [Object]
+        # @return [String]
+        def self.quote(_value) = QUOTE
+
+        # @return [String]
+        def self.unquote = UNQUOTE
+
+        # @param key [String]
+        # @param path [String] the object the key sits in
+        # @param owner [String] the enclosing object that has the key, `""` for the top level
+        # @return [String] `sandbox belongs to code, under [code] before [code.panel]`
+        def self.misplaced(key, path, owner)
+          where = owner.empty? ? "before any [header]" : "under #{header(owner)} before #{header(path)}"
+          "#{Wording.belongs(key, owner)}, #{where}"
+        end
+
+        # @param path [String] `llm[0].params`
+        # @param array [Boolean] whether to spell it as an array entry's header
+        # @return [String] `[llm.params]`; `[[llm]]` for `llm[0]`
+        def self.header(path, array: path.end_with?("]"))
+          name = path.split(".").map { |key| bare(key.sub(/\[\d+\]\z/, "")) }.join(".")
+          array ? "[[#{name}]]" : "[#{name}]"
+        end
+
+        # @param path [String]
+        # @return [Boolean] whether the value sits under a key, which a header can name — not at the
+        #   root, nor directly in an array
+        def self.keyed?(path) = !path.empty? && !path.end_with?("]")
+
+        # @param path [String] `llm[0].servers`
+        # @return [String] `servers`, as TOML writes it
+        def self.key(path) = bare(path.split(".").last)
+
+        # @param key [String]
+        # @return [String] the key as TOML writes it, quoted unless bare
+        def self.bare(key) = key.match?(/\A[A-Za-z0-9_-]+\z/) ? key : key.inspect
+        private_class_method :header, :keyed?, :key, :bare
+      end
+
+      # JSON: brackets and braces.
+      module JSON
+        # @param value [Object]
+        # @return [String]
+        def self.found(value) = Wording.inspected(value)
+
+        # @param _path [String]
+        # @param _entry [Boolean]
+        # @return [String]
+        def self.wrap(_path, _entry) = "wrap it in [ ]"
+
+        # @param _path [String]
+        # @return [String]
+        def self.unwrap(_path) = "remove the [ ]"
+
+        # @param _value [Object]
+        # @return [String]
+        def self.quote(_value) = QUOTE
+
+        # @return [String]
+        def self.unquote = UNQUOTE
+
+        # @param key [String]
+        # @param path [String] the object the key sits in
+        # @param owner [String] the enclosing object that has the key, `""` for the top level
+        # @return [String] `sandbox belongs to the top level; move it out of pane's { }`
+        def self.misplaced(key, path, owner) = "#{Wording.belongs(key, owner)}; move it out of #{path}'s { }"
+      end
+
+      # YAML in block style: `- ` and indentation.
+      module YAML
+        # @param value [Object]
+        # @return [String]
+        def self.found(value) = Wording.inspected(value)
+
+        # @param _path [String]
+        # @param _entry [Boolean]
+        # @return [String]
+        def self.wrap(_path, _entry) = 'put "- " before it'
+
+        # @param _path [String]
+        # @return [String]
+        def self.unwrap(_path) = 'remove the "- "'
+
+        # Psych reads YAML 1.1, so `no` loads as `false`: the Norway problem.
+        #
+        # @param value [Object]
+        # @return [String]
+        def self.quote(value)
+          [true, false].include?(value) ? "#{QUOTE}; YAML reads yes, no, on and off as booleans" : QUOTE
+        end
+
+        # @return [String]
+        def self.unquote = UNQUOTE
+
+        # @param key [String]
+        # @param _path [String]
+        # @param owner [String]
+        # @return [String] `sandbox belongs to the top level; dedent it`
+        def self.misplaced(key, _path, owner) = "#{Wording.belongs(key, owner)}; dedent it"
+      end
+    end
+  end
+end