poetry-agent 0.0.2

data/lib/poetry/agent/a2ui/checks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "functions"
+
+module Poetry
+  module Agent
+    module A2UI
+      # Evaluates a component's `checks`: each rule's condition (a binding
+      # or a function call) yields a ValidationResult - `{ "valid",
+      # "code", "message", "severity" }` - or a boolean; a failing rule
+      # of error severity is a failure, carrying the result's message or
+      # the rule's fallback.
+      module Checks
+        # The message when neither the result nor the rule carries one.
+        DEFAULT_MESSAGE = "Check failed"
+
+        module_function
+
+        # @param component [Hash]
+        # @param evaluator [Evaluator]
+        # @return [Array<Hash>] failures as `{ code:, message:, severity: }`
+        def failures(component, evaluator)
+          Array(component["checks"]).filter_map do |rule|
+            next unless rule.is_a?(Hash) && rule["condition"]
+
+            outcome = interpret(evaluator.resolve(rule["condition"]), rule)
+            outcome unless outcome[:valid] || outcome[:severity] != "error"
+          end
+        end
+
+        # @api private
+        def interpret(result, rule)
+          if result.is_a?(Hash)
+            { valid: result["valid"] == true, code: result["code"],
+              message: result["message"] || rule["message"] || DEFAULT_MESSAGE,
+              severity: result["severity"] || "error" }
+          else
+            { valid: Functions.truthy?(result), code: nil, message: rule["message"] || DEFAULT_MESSAGE,
+              severity: "error" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/a2ui/evaluator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "expression"
+require_relative "functions"
+
+module Poetry
+  module Agent
+    module A2UI
+      # Resolves dynamic values in a scope: a `{ "path" }` binding reads
+      # the data model, a `{ "call", "args" }` invokes a registered
+      # function with its arguments resolved first (a string argument with
+      # `${}` blocks interpolates, an array resolves item by item), and
+      # `@index` reads the collection index the scope carries. Problems
+      # (an unknown function, a bad argument, a malformed expression)
+      # resolve to nil and reach the `on_error` callback.
+      #
+      # @example
+      #   Evaluator.new(surface, "/items/2").resolve({ "call" => "@index", "args" => { "offset" => 1 } }) # => 3
+      class Evaluator
+        # @return [Surface]
+        attr_reader :surface
+        # @return [String, nil] the collection-item pointer in effect
+        attr_reader :scope
+
+        # @param surface [Surface]
+        # @param scope [String, nil]
+        # @param on_error [#call, nil] receives each problem's message
+        def initialize(surface, scope = nil, on_error: nil)
+          @surface = surface
+          @scope = scope
+          @on_error = on_error
+        end
+
+        # Resolves a component property: bindings and calls resolve,
+        # everything else is a literal.
+        #
+        # @param value [Object]
+        # @return [Object, nil]
+        def resolve(value)
+          return value unless value.is_a?(Hash)
+          return surface.read(value["path"], scope) if surface.binding?(value)
+          return call(value["call"], value["args"]) if surface.function_call?(value)
+
+          value
+        end
+
+        # Resolves a function argument: like {#resolve}, plus strings
+        # interpolate and arrays and plain objects resolve inside.
+        #
+        # @param value [Object]
+        # @return [Object, nil]
+        def argument(value)
+          case value
+          when String then Expression.dynamic?(value) ? interpolate(value) : value
+          when Array then value.map { |item| argument(item) }
+          when Hash
+            return resolve(value) if surface.binding?(value) || surface.function_call?(value)
+
+            value.transform_values { |item| argument(item) }
+          else value
+          end
+        end
+
+        # Calls a function by name.
+        #
+        # @param name [String]
+        # @param args [Hash, nil] raw arguments (resolved here unless `resolved:`)
+        # @param resolved [Boolean] whether the arguments are already resolved
+        # @return [Object, nil]
+        def call(name, args, resolved: false)
+          args = (args.is_a?(Hash) ? args : {}).to_h { |key, value| [key.to_s, resolved ? value : argument(value)] }
+          return index_of(args) if name == "@index"
+
+          surface.catalog.functions.call(name.to_s, args, self)
+        rescue Functions::Error, Expression::SyntaxError => e
+          fail!("function #{name.inspect}: #{e.message}")
+        end
+
+        # Interpolates a `formatString` template.
+        #
+        # @param text [String]
+        # @return [String]
+        def interpolate(text)
+          evaluate(Expression.parse(text))
+        rescue Expression::SyntaxError => e
+          fail!("formatString: #{e.message}")
+          ""
+        end
+
+        # Evaluates a parsed expression node.
+        #
+        # @param node [Array]
+        # @return [Object, nil]
+        def evaluate(node)
+          case node[0]
+          when :text, :literal then node[1]
+          when :path then surface.read(node[1], scope)
+          when :call then call(node[1], node[2].transform_values { |item| evaluate(item) }, resolved: true)
+          when :template then node[1].map { |item| stringify(evaluate(item)) }.join
+          end
+        end
+
+        # The string a value displays as (the spec's conversion rules: nil
+        # is empty, containers are JSON, whole floats drop their fraction).
+        #
+        # @param value [Object]
+        # @return [String]
+        def stringify(value)
+          case value
+          when nil then ""
+          when Float then value.finite? && value == value.floor && value.abs < 1e15 ? value.to_i.to_s : value.to_s
+          when Hash, Array then JSON.generate(value)
+          else value.to_s
+          end
+        end
+
+        # @return [Integer, nil] the collection index the scope carries
+        def index
+          token = scope.to_s.split("/").last
+          token&.match?(/\A\d+\z/) ? token.to_i : nil
+        end
+
+        private
+
+        def index_of(args)
+          position = index or raise Functions::Error, "@index is only available inside a template"
+
+          position + (Functions.number(args["offset"]) || 0)
+        end
+
+        def fail!(message)
+          @on_error&.call(message)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/a2ui/expression.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Agent
+    module A2UI
+      # The `formatString` grammar: literal text with `${...}` blocks, each
+      # block a data path, a literal, or a function call with named
+      # arguments whose values are expressions again (a bare argument is
+      # `value`); `\${` is a literal `${`. Parsing yields a plain tree the
+      # {Evaluator} walks:
+      #
+      #   [:template, nodes]           the whole string
+      #   [:text, "literal text"]
+      #   [:path, "/absolute"]         or a relative path
+      #   [:literal, 12] / [:literal, "quoted"] / [:literal, true]
+      #   [:call, "formatDate", { "value" => node, "format" => node }]
+      #
+      # @example
+      #   Expression.parse("Hi ${/user/name}, ${formatNumber(value: ${/n}, decimals: 1)}")
+      module Expression
+        # A malformed expression.
+        class SyntaxError < StandardError; end
+
+        # Identifier: function names, argument names, relative path heads.
+        IDENT = /[A-Za-z_@][A-Za-z0-9_]*/
+        # A number literal not followed by a path or identifier character.
+        NUMBER = %r{-?\d+(?:\.\d+)?(?![\w/])}
+        # Keyword literals.
+        KEYWORDS = { "true" => true, "false" => false, "null" => nil }.freeze
+        # Nesting depth beyond which an expression is refused.
+        MAX_DEPTH = 32
+
+        module_function
+
+        # @param text [String]
+        # @return [Array] the `[:template, nodes]` tree
+        # @raise [SyntaxError]
+        def parse(text)
+          Parser.new(text.to_s).template
+        end
+
+        # @param text [String]
+        # @return [Boolean] whether the text carries an interpolation block
+        def dynamic?(text)
+          text.is_a?(String) && text.include?("${")
+        end
+
+        # The recursive-descent parser.
+        class Parser
+          # @param source [String]
+          def initialize(source)
+            @source = source
+            @index = 0
+            @depth = 0
+          end
+
+          # @return [Array] the `[:template, nodes]` tree
+          def template
+            nodes = []
+            buffer = +""
+            until eos?
+              if peek(3) == "\\${"
+                buffer << "${"
+                @index += 3
+              elsif peek(2) == "${"
+                nodes << [:text, buffer] unless buffer.empty?
+                buffer = +""
+                nodes << block
+              else
+                buffer << @source[@index]
+                @index += 1
+              end
+            end
+            nodes << [:text, buffer] unless buffer.empty?
+            [:template, nodes]
+          end
+
+          private
+
+          # `${` expression `}`
+          def block
+            expect("${")
+            node = expression
+            skip_space
+            expect("}")
+            node
+          end
+
+          def expression
+            @depth += 1
+            raise SyntaxError, "expression nested deeper than #{MAX_DEPTH}" if @depth > MAX_DEPTH
+
+            skip_space
+            node = if peek(2) == "${" then block
+                   elsif (match = scan(/'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)"/))
+                     [:literal, unescape(match[1] || match[2])]
+                   elsif (match = scan(NUMBER)) then [:literal, number(match[0])]
+                   elsif (match = scan(%r{(true|false|null)(?![\w/])})) then [:literal, KEYWORDS[match[1]]]
+                   elsif peek(1) == "/" then [:path, scan(%r</[^\s,)}]*>)[0]]
+                   elsif (match = scan(IDENT)) then identifier(match[0])
+                   else raise SyntaxError, "unexpected #{peek(1).inspect} at #{@index}"
+                   end
+            @depth -= 1
+            node
+          end
+
+          # A name followed by `(` is a call; otherwise a relative path.
+          def identifier(name)
+            skip_space
+            return [:path, name + (scan(%r<(?:/[^\s,)}/]*)*>)&.[](0) || "")] unless peek(1) == "("
+
+            @index += 1
+            [:call, name, arguments]
+          end
+
+          def arguments
+            args = {}
+            skip_space
+            if peek(1) == ")"
+              @index += 1
+              return args
+            end
+            loop do
+              skip_space
+              named = scan(/(#{IDENT.source})\s*:/)
+              args[named ? named[1] : "value"] = expression
+              skip_space
+              case peek(1)
+              when "," then @index += 1
+              when ")"
+                @index += 1
+                return args
+              else raise SyntaxError, "expected , or ) at #{@index}"
+              end
+            end
+          end
+
+          def number(text)
+            text.include?(".") ? Float(text) : Integer(text, 10)
+          end
+
+          def unescape(text)
+            text.gsub(/\\(.)/) { Regexp.last_match(1) }
+          end
+
+          def scan(pattern)
+            match = pattern.match(@source, @index)
+            return unless match && match.begin(0) == @index
+
+            @index = match.end(0)
+            match
+          end
+
+          def expect(token)
+            raise SyntaxError, "expected #{token.inspect} at #{@index}" unless peek(token.length) == token
+
+            @index += token.length
+          end
+
+          def peek(length)
+            @source[@index, length]
+          end
+
+          def skip_space
+            @index += 1 while @source[@index]&.match?(/\s/)
+          end
+
+          def eos?
+            @index >= @source.length
+          end
+        end
+      end
+    end
+  end
+end