natsuzora 0.4.0

data/lib/natsuzora/contract/validator.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'type_ref_resolver'
+require_relative 'validation_target'
+require_relative 'ast/any'
+require_relative 'ast/scalar'
+require_relative 'ast/record'
+require_relative 'ast/list'
+require_relative 'ast/ref'
+
+module Natsuzora
+  module Contract
+    # Error that can occur during validation.
+    class ValidationError < StandardError
+      attr_reader :path, :error_message
+
+      def initialize(message, path = '$')
+        @path = path
+        @error_message = message
+        super("#{message} at #{path}")
+      end
+    end
+
+    # Validator for JSON data against contracts.
+    class Validator
+      MAX_VALIDATE_DEPTH = 64
+
+      # Validate JSON data against a contract.
+      def self.validate(contract, data)
+        new.validate_node(contract, data, [])
+      end
+
+      # Validate JSON data against a contract file with diff markers.
+      def self.validate_with_target(document, data, target: ValidationTarget::CURRENT)
+        contract = build_contract_for_target(document, target)
+        validate(contract, data)
+      end
+
+      def validate_node(contract, data, path)
+        raise ValidationError.new('validation depth exceeded', render_path(path)) if path.length > MAX_VALIDATE_DEPTH
+
+        case contract
+        when AST::Any
+          nil # any value is valid
+        when AST::Scalar
+          validate_scalar(contract, data, path)
+        when AST::Record
+          validate_object(contract, data, path)
+        when AST::List
+          validate_array(contract, data, path)
+        when AST::Ref
+          raise ValidationError.new("unresolved type reference '#{contract.name}'", render_path(path))
+        else
+          raise ArgumentError, "Unknown contract type: #{contract.class}"
+        end
+      end
+
+      private
+
+      def validate_scalar(contract, data, path)
+        return validate_null(contract, path) if data.nil?
+        return nil if scalar_value_valid?(contract, data, path)
+
+        raise ValidationError.new("expected #{contract.scalar_type}", render_path(path))
+      end
+
+      def validate_null(contract, path)
+        return nil if contract.nullable?
+
+        raise ValidationError.new('null is not allowed', render_path(path))
+      end
+
+      def scalar_value_valid?(contract, data, path)
+        return false unless contract.accepts?(data)
+
+        ensure_not_empty!(contract, data, path) if data.is_a?(String)
+        true
+      end
+
+      def ensure_not_empty!(contract, data, path)
+        return unless contract.required? && data.empty?
+
+        raise ValidationError.new('empty string is not allowed', render_path(path))
+      end
+
+      def validate_object(contract, data, path)
+        unless data.is_a?(Hash)
+          raise ValidationError.new('expected object', render_path(path))
+        end
+
+        # Check required fields
+        contract.required.each do |key|
+          unless data.key?(key) || data.key?(key.to_sym)
+            raise ValidationError.new('missing required property', render_path(path + [[:key, key]]))
+          end
+        end
+
+        # Validate properties
+        contract.properties.each do |key, child_contract|
+          value = if data.key?(key)
+                    data[key]
+                  elsif data.key?(key.to_sym)
+                    data[key.to_sym]
+                  end
+          next if value.nil? && !data.key?(key) && !data.key?(key.to_sym)
+
+          validate_node(child_contract, value, path + [[:key, key]])
+        end
+
+        nil
+      end
+
+      def validate_array(contract, data, path)
+        unless data.is_a?(Array)
+          raise ValidationError.new('expected array', render_path(path))
+        end
+
+        data.each_with_index do |item, idx|
+          validate_node(contract.items, item, path + [[:index, idx]])
+        end
+
+        nil
+      end
+
+      def render_path(path)
+        result = '$'
+        path.each do |(type, value)|
+          case type
+          when :key
+            result += ".#{value}"
+          when :index
+            result += "[#{value}]"
+          end
+        end
+        result
+      end
+
+      class << self
+        private
+
+        def build_contract_for_target(document, target)
+          resolver = TypeRefResolver.new(
+            document.types,
+            target: target,
+            on_missing: ->(name) { raise ValidationError, "undefined type '#{name}'" },
+            on_unavailable: ->(name) { raise ValidationError, "type '#{name}' is not available for #{target}" },
+            on_cyclic: ->(name) { raise ValidationError, "cyclic type reference '#{name}'" }
+          )
+
+          properties = {}
+          required = []
+
+          document.fields.each do |name, field|
+            contract = field.for_target(target)
+            next unless contract
+
+            properties[name] = resolver.resolve(contract)
+            required << name
+          end
+
+          AST::Record.new(properties, required)
+        end
+      end
+    end
+
+    # Validate JSON data against a contract.
+    def self.validate(contract, data) # rubocop:disable Naming/PredicateMethod
+      Validator.validate(contract, data)
+      true
+    end
+
+    # Validate JSON data against a contract file with diff markers.
+    def self.validate_with_target(document, data, target: ValidationTarget::CURRENT) # rubocop:disable Naming/PredicateMethod
+      Validator.validate_with_target(document, data, target: target)
+      true
+    end
+  end
+end

data/lib/natsuzora/contract.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'contract/parse_error'
+require_relative 'contract/diff_marker'
+require_relative 'contract/validation_target'
+require_relative 'contract/scalar_type'
+require_relative 'contract/ast'
+require_relative 'contract/field'
+require_relative 'contract/type_def'
+require_relative 'contract/type_ref_resolver'
+require_relative 'contract/document'
+require_relative 'contract/compiled_lexer'
+require_relative 'contract/parser'
+require_relative 'contract/validator'
+
+module Natsuzora
+  # Contract notation (formerly the standalone `subaru` gem).
+  # Parses `.ntzc` files into a {Contract} tree, validates JSON data against
+  # contracts, and supports two-generation diff markers (`+`, `-`, `*`).
+  module Contract
+    class Error < StandardError; end
+  end
+end

data/lib/natsuzora/data/lexers/contract.lkt1

@@ -0,0 +1 @@
+{"format":"lkt1","codec":"deflate+base64","kind":"program","table_version":2,"uncompressed_len":2276,"sha256":"375d869fdc099409a5c07a3eb293c87d6a8a31c886cb9d545d77a297dc1c2ef1","data":"eJzlletrE0EUxc/sw7TbByolFAnSVkVoEayPCv1gs92d6pp9pLubpA/KUm3rq76tr1LIn5b/rJ7dxBiXRv0QpNgLP+7cOTPD3rMw41bieagABCYxniShjGRYl3ZyM0lQcPy66Tr2L8ItCr317Vx9J1ffzdULufoea90Mw6AB3QrcwIcRVKWfLIemJTFiuUEkO8VoV6jIGGM/pbQcWq3JKHa4f0SuWa7pmVmhVd1aBN1zfCYtis0QBSvwPOnHGI7XqzLxTU/CcGzOOCuOpO7Lhuv4Ekojoi+Fnd297YP9j73DdtRgYIE59U/JZsRxFpmfAsPMelcDtBupcD+bEYsQhxBHEJsQWxBLENMQcxCz6RZR4qEquiHQJ5R+wn8WStYpbWt3nPfn70J048epfSNb3rMhH4PrbDDRdmfQ/vy+f/EH/05T5P0p0p2ejzx1//NfRufqOtEZgRPNOSN+9d45bFlcAGZg8RZXF4Fzh8DQEWBsAqNbwPgScH4auDgHTMwCxSvApAlcWiYWsYkkK+QBeUgc8ohUiEs84pOAVMkqCUlEYlIjddIga2SdbJBtoPSYPCE7ZJfskafkGXlOXpCXZJ+8Iq/JG/KWvCPvyQfC5610QD6Rz+QL+Uq+EQO4zGdtaoxMkY5R168C19hjNsHvn7Fpma2VUUSZ4zQ3mZvMLeYWioJreEEVBXWVuqCuUhfUVeoKdY26Ql1rpn+AucXMWk//CtfrZWau16nzPHqGCeCYfvMt5aDDd/X9jB8="}

data/lib/natsuzora/data/lexers/template.lkt1

@@ -0,0 +1 @@
+{"format":"lkt1","codec":"deflate+base64","kind":"program","table_version":2,"uncompressed_len":2226,"sha256":"f670fe5c25083a9642759f0aa0cd16670997d72b94f1323c676001b403fba8d3","data":"eJzdlW1PFEkQx/89s7M7sICIZj0vJqfx8YUCPmEuhuw2M427x+ws7OwCSsgGFZ/FB/SezCX7/r4Un+C+kvevnj3pAyX4ztjkx1R11VRXV0/1Jgudq/ABKJzCWK/XNplpL5u4N93rodRIl3XSiP9nuEaDq1/fo9/Yo9/co8/s0W9RL3TMagelRdOOTNpBIdZZHUGUtDKDQt0qWSKP0Tmd3ul108xE3bbBiFUbaZR0Y4OyWY0S3dSdRitFsLDSa8xjiI9umpgsQ4miSRjRCjqqWx+dwY9bHa7WajY1ArPU1QnCpa7JbJzhlXqjY7JFHRkEjVjS81B6uPlo4/2LdxiWxHtPt7Y237rTMlwTEALePxiH92ENZboGH9b4t/4X1HmoK/BEOgs1pc7R+SgZt0HURzvs+TA+nyeJ78wXHDlw5KIjlxw5dOQhRx627wMnrLw7X3bkEUcedeQxRz7iyOM2D+CHM7KBpxL5Pf95W7KHbUl+U1Z9IG5iKNlKydyQuJTFMPJCFhPr2EMJv2njztgqMNS+Ku3KXl52/CQLq0d25k9bjTyrL7+3Kx+u0lJJ4IIkqSRxT3L2JdOC7DLYtl5/D/Ip7T/ZQ6yXn9CVA09ZTguYlIXVhnhKHt72p2RsoZ9Y18MWcITclFhqOy/NJNRlqFmoqtjVKUbx8ZVDfRqDCe+LA3mBDrR/S8OzeLZdOVSF1dlNUjas9r/0manvceS1ySsjhRgFIsyd51fLz3p0nc19FpiYAo7zvqiwa39kR53hl3uJH+D0JHDrMvDzLHC7Csyy5apsiSqjVE8TDeg5EpGYGDJP7pA6aZBfyAJJSJOkpEUWyRJpk4x0SJcskxWySu6Se+Q+YSNp3kaal4p+TNhT+hl5Tthz+iXhRaBfkdfkDeHdptlDmr8O+lfyG/md/EF4LelBkerMH8dYnRpvC/4YlCaoT1OXO1S6knPz4sM9o4J+FHu1sIIdPvthRSHie+WrYlO1KPbBOfr4tTBV9PH7YezvhHEBIesB1ieUj69Z6J9mTaK4UAvj4s5/tqGB7WJu67u24YFtKrcxZgDXXh7YZ6w9yONWfJGZp8/cAtGZW5E5+sytWAs9cL7Y55N+9D/OLc/lew8/Dvb/L/ErdH4="}

data/lib/natsuzora/data_normalizable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  # Mixin that gives the including class a `normalize_data(data)` method.
+  module DataNormalizable
+    # performs only pure transformations:
+    # - Symbol Hash keys are converted to Strings (recursively).
+    # - Whole-number Float values are converted to Integers.
+    def normalize_data(data)
+      case data
+      when Hash
+        data.transform_keys(&:to_s).transform_values { |v| normalize_data(v) }
+      when Array
+        data.map { |v| normalize_data(v) }
+      when Float
+        normalize_float(data)
+      else
+        data
+      end
+    end
+
+    private
+
+    # Convert finite whole-number Float to Integer; pass through anything else.
+    def normalize_float(value)
+      return value.to_i if value.finite? && value == value.to_i
+
+      value
+    end
+  end
+end

data/lib/natsuzora/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class Error < StandardError
+    attr_reader :line, :column
+
+    def initialize(message, line: nil, column: nil)
+      @line = line
+      @column = column
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      return message unless line
+
+      column ? "#{message} at line #{line}, column #{column}" : "#{message} at line #{line}"
+    end
+  end
+
+  class LexerError < Error; end
+
+  class ParseError < Error; end
+
+  class ReservedWordError < ParseError; end
+
+  class RenderError < Error; end
+
+  class UndefinedVariableError < RenderError; end
+
+  class TypeError < RenderError; end
+
+  class IncludeError < RenderError; end
+
+  class ShadowingError < RenderError; end
+end

data/lib/natsuzora/html_escape.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  module HtmlEscape
+    ESCAPE_MAP = {
+      '&' => '&',
+      '<' => '&lt;',
+      '>' => '&gt;',
+      '"' => '&quot;',
+      "'" => '&#39;'
+    }.freeze
+
+    ESCAPE_REGEXP = /[&<>"']/
+
+    class << self
+      def escape(string)
+        string.gsub(ESCAPE_REGEXP, ESCAPE_MAP)
+      end
+    end
+  end
+end

data/lib/natsuzora/lexer/compiled_lexer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../lexer_loader'
+
+module Natsuzora
+  class Lexer
+    module CompiledLexer
+      LEXER_PATH = File.expand_path('../data/lexers/template.lkt1', __dir__)
+
+      def self.instance
+        @instance ||= LexerLoader.load_compiled(LEXER_PATH)
+      end
+    end
+  end
+end

data/lib/natsuzora/lexer/token_processor.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class Lexer
+    # Processes tokens to handle whitespace control and comments.
+    #
+    # Responsibilities:
+    # - Consume DASH tokens and apply trim rules
+    # - Consume comment tags entirely
+    # - Detect unclosed comments
+    class TokenProcessor
+      def initialize(tokens)
+        @tokens = tokens
+        @result = []
+        @strip_next_text = false
+      end
+
+      def process
+        idx = 0
+
+        while idx < @tokens.length
+          token = @tokens[idx]
+
+          if token.type == :TEXT
+            append_text(token)
+            idx += 1
+          else
+            idx = process_tag(idx)
+          end
+        end
+
+        @result
+      end
+
+      private
+
+      def process_tag(start_idx)
+        close_idx = find_close_index(start_idx)
+        tag_tokens = close_idx ? @tokens[start_idx..close_idx] : @tokens[start_idx..]
+
+        apply_left_trim(tag_tokens)
+        apply_right_trim(tag_tokens)
+
+        if comment_tag?(tag_tokens)
+          raise_unclosed_comment!(tag_tokens) unless close_idx
+          return close_idx + 1
+        end
+
+        emit_tag_tokens(tag_tokens)
+        close_idx ? close_idx + 1 : @tokens.length
+      end
+
+      def append_text(token)
+        text_value = token.value
+
+        if @strip_next_text
+          @strip_next_text = false
+          text_value = strip_leading_whitespace_if_blank_line(text_value)
+        end
+
+        return if text_value.empty?
+
+        @result << Token.new(:TEXT, text_value, line: token.line, column: token.column)
+      end
+
+      def find_close_index(start_idx)
+        idx = start_idx
+        while idx < @tokens.length
+          return idx if @tokens[idx].type == :CLOSE
+
+          idx += 1
+        end
+        nil
+      end
+
+      def apply_left_trim(tag_tokens)
+        strip_trailing_from_last_text_if_blank_line if tag_tokens.first&.type == :DASH
+      end
+
+      def apply_right_trim(tag_tokens)
+        close_idx = tag_tokens.index { |token| token.type == :CLOSE }
+        @strip_next_text = true if close_idx&.positive? && tag_tokens[close_idx - 1].type == :DASH
+      end
+
+      def comment_tag?(tag_tokens)
+        first = tag_tokens.first
+        return false unless first
+
+        return true if first.type == :PERCENT
+
+        first.type == :DASH && tag_tokens[1]&.type == :PERCENT
+      end
+
+      def emit_tag_tokens(tag_tokens)
+        tag_tokens.each do |token|
+          next if token.type == :DASH
+
+          @result << token
+        end
+      end
+
+      def strip_trailing_from_last_text_if_blank_line
+        last_idx = @result.rindex { |token| token.type == :TEXT }
+        return unless last_idx
+
+        last_text = @result[last_idx]
+        value = last_text.value
+        line_start = same_line_start_offset(value)
+        trailing_segment = value[line_start..] || ''
+        return unless horizontal_whitespace_only?(trailing_segment)
+
+        stripped = value[0...line_start]
+        @result[last_idx] = Token.new(:TEXT, stripped, line: last_text.line, column: last_text.column)
+      end
+
+      def strip_leading_whitespace_if_blank_line(text)
+        bytes = text.bytes
+        idx = skip_leading_horizontal_whitespace(bytes)
+        return '' if idx >= bytes.length
+
+        newline_advance = leading_newline_advance(bytes, idx)
+        return text unless newline_advance
+
+        text[(idx + newline_advance)..] || ''
+      end
+
+      def same_line_start_offset(value)
+        line_break_idx = [value.rindex("\n"), value.rindex("\r")].compact.max
+        line_break_idx ? line_break_idx + 1 : 0
+      end
+
+      def horizontal_whitespace_only?(segment)
+        segment.match?(/\A[ \t]*\z/)
+      end
+
+      def skip_leading_horizontal_whitespace(bytes)
+        idx = 0
+        idx += 1 while idx < bytes.length && (bytes[idx] == 0x20 || bytes[idx] == 0x09)
+        idx
+      end
+
+      def leading_newline_advance(bytes, idx)
+        return 1 if bytes[idx] == 0x0A # \n
+
+        return nil unless bytes[idx] == 0x0D # \r
+
+        bytes[idx + 1] == 0x0A ? 2 : 1
+      end
+
+      def raise_unclosed_comment!(tag_tokens)
+        comment_token = tag_tokens.find { |token| token.type == :PERCENT } || tag_tokens.first
+        raise LexerError.new('Unclosed comment', line: comment_token.line, column: comment_token.column)
+      end
+    end
+  end
+end

data/lib/natsuzora/lexer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'lexer/compiled_lexer'
+require_relative 'lexer/token_processor'
+require_relative 'token'
+require_relative 'errors'
+
+module Natsuzora
+  # Lexer for Natsuzora template language using LexerKit
+  #
+  # Responsibilities:
+  # - Escape sequence processing ({[{]} -> {[)
+  # - Whitespace control via TokenProcessor ({[- and -]})
+  # - Error handling for invalid characters
+  # - EOF token addition
+  class Lexer
+    ESCAPE_SEQUENCE = '{[{]}'
+    ESCAPED_VALUE = '{['
+
+    def initialize(source)
+      @source = source
+    end
+
+    def tokenize
+      stream = CompiledLexer.instance.stream(@source)
+      mapped_tokens = map_tokens_from_stream(stream)
+      processed_tokens = TokenProcessor.new(mapped_tokens).process
+      add_eof(processed_tokens)
+      processed_tokens
+    end
+
+    private
+
+    def map_tokens_from_stream(stream)
+      result = []
+
+      until stream.eof?
+        name = stream.token_name
+        text = stream.text
+
+        case name
+        when :TEXT
+          text_value = process_text_value(text)
+          unless text_value.empty?
+            line, col = stream.line_col
+            result << Token.new(:TEXT, text_value, line: line, column: col)
+          end
+
+        when :INVALID
+          line, col = stream.line_col
+          raise LexerError.new("Unexpected character: '#{text}'", line: line, column: col)
+
+        else
+          line, col = stream.line_col
+          result << Token.new(name, text, line: line, column: col)
+        end
+
+        stream.advance
+      end
+
+      result
+    end
+
+    def process_text_value(text)
+      text.gsub(ESCAPE_SEQUENCE, ESCAPED_VALUE)
+    end
+
+    def add_eof(tokens)
+      if tokens.empty?
+        tokens << Token.new(:EOF, nil, line: 1, column: 1)
+      else
+        last = tokens.last
+        line, column = position_after_value(last)
+        tokens << Token.new(:EOF, nil, line: line, column: column)
+      end
+    end
+
+    def position_after_value(token)
+      line = token.line
+      column = token.column
+      value = token.value || ''
+
+      value.each_char do |char|
+        if char == "\n"
+          line += 1
+          column = 1
+        else
+          column += 1
+        end
+      end
+
+      [line, column]
+    end
+  end
+end

data/lib/natsuzora/lexer_loader.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'lexer_kit'
+
+module Natsuzora
+  module LexerLoader
+    def self.load_compiled(path)
+      unless File.file?(path)
+        raise LoadError, "Precompiled lexer is missing: #{path}. Run `rake lexers:compile`."
+      end
+
+      LexerKit.load_lexer(path)
+    end
+  end
+end

data/lib/natsuzora/lexers/contract.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'lexer_kit'
+
+LexerKit.build do
+  token :ARROW, '->'
+  token :COLON, ':'
+  token :OPEN_BRACE, '{'
+  token :CLOSE_BRACE, '}'
+  token :OPEN_BRACKET, '['
+  token :CLOSE_BRACKET, ']'
+  token :QUESTION, '?'
+  token :EXCLAMATION, '!'
+  token :PLUS, '+'
+  token :MINUS, '-'
+  token :STAR, '*'
+
+  token :COMMENT, /#[^\n]*/
+  token :TYPE_NAME, /[A-Z][a-zA-Z0-9_]*/
+  token :IDENTIFIER, /[a-z][a-zA-Z0-9_]*/
+  token :NEWLINE, /\n/
+
+  token :WS, /[ \t\r]+/, skip: true
+end

data/lib/natsuzora/lexers/template.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'lexer_kit'
+
+LexerKit.build do
+  delimited :TEXT, delimiter: '{[', escape: '{[{]}' do
+    token :PERCENT, '%'
+    token :DASH, '-'
+    token :CLOSE, ']}', pop: true
+    token :HASH, '#'
+    token :SLASH, '/'
+
+    token :BANG_UNSECURE, '!unsecure'
+    token :BANG_INCLUDE, '!include'
+    token :EXCLAMATION, '!'
+
+    token :KW_IF, 'if'
+    token :KW_UNLESS, 'unless'
+    token :KW_ELSE, 'else'
+    token :KW_EACH, 'each'
+    token :KW_AS, 'as'
+
+    token :DOT, '.'
+    token :COMMA, ','
+    token :EQUAL, '='
+    token :QUESTION, '?'
+
+    token :WHITESPACE, /[ \t\r\n]+/
+    token :IDENT, /[A-Za-z][A-Za-z0-9_]*/
+  end
+end