natsuzora 0.4.0

data/lib/natsuzora/parser.rb

@@ -0,0 +1,419 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class Parser
+    def initialize(tokens)
+      @tokens = tokens
+      @pos = 0
+    end
+
+    def parse
+      nodes = parse_nodes
+      AST::Template.new(nodes, line: 1, column: 1)
+    end
+
+    private
+
+    def parse_nodes(stop_types: [:EOF])
+      nodes = []
+      nodes << parse_node until stop_types.include?(current_type)
+      nodes
+    end
+
+    def parse_node
+      case current_type
+      when :TEXT
+        node = parse_text
+        parse_tag_content_if_present
+        node
+      when :HASH, :SLASH, :BANG_UNSECURE, :BANG_INCLUDE, :IDENT, :KW_IF, :KW_UNLESS, :KW_ELSE, :KW_EACH, :KW_AS,
+           :WHITESPACE, :QUESTION, :EXCLAMATION, :DOT, :EQUAL, :COMMA
+        parse_tag_content
+      else
+        unexpected_token!
+      end
+    end
+
+    def parse_text
+      token = consume(:TEXT)
+      AST::Text.new(token.value, line: token.line, column: token.column)
+    end
+
+    def parse_tag_content_if_present
+      # No-op: comments are now handled by TokenProcessor
+    end
+
+    def parse_tag_content
+      first_token = current_token
+
+      check_no_whitespace_before_special(first_token) if current_type == :WHITESPACE
+
+      skip_whitespace
+
+      case current_type
+      when :HASH
+        parse_block_open
+      when :SLASH
+        unexpected_token!('Unexpected block close')
+      when :BANG_UNSECURE
+        parse_unsecure_output
+      when :BANG_INCLUDE
+        parse_include
+      else
+        parse_variable_node
+      end
+    end
+
+    def check_no_whitespace_before_special(ws_token)
+      saved_pos = @pos
+      skip_whitespace
+      if %i[HASH SLASH BANG_UNSECURE BANG_INCLUDE].include?(current_type)
+        raise ParseError.new(
+          "Whitespace not allowed before '#{current_token.value}' after tag open",
+          line: ws_token.line,
+          column: ws_token.column
+        )
+      end
+      @pos = saved_pos
+    end
+
+    def parse_block_open
+      consume(:HASH)
+      skip_whitespace
+
+      case current_type
+      when :KW_IF
+        parse_if_block
+      when :KW_UNLESS
+        parse_unless_block
+      when :KW_EACH
+        parse_each_block
+      when :KW_ELSE
+        unexpected_token!("Unexpected 'else' without 'if'")
+      else
+        unexpected_token!
+      end
+    end
+
+    def parse_if_block
+      token = consume(:KW_IF)
+      line = token.line
+      column = token.column
+
+      consume_required_whitespace
+      condition = parse_path
+      skip_whitespace
+      consume(:CLOSE)
+
+      then_nodes = parse_if_body
+      else_nodes = nil
+
+      if else_open?
+        consume_else
+        else_nodes = parse_if_body
+      end
+
+      consume_block_close(:KW_IF)
+
+      AST::IfBlock.new(
+        condition: condition,
+        then_nodes: then_nodes,
+        else_nodes: else_nodes,
+        line: line,
+        column: column
+      )
+    end
+
+    def parse_if_body
+      nodes = []
+      nodes << parse_node until block_close?(:KW_IF) || else_open?
+      nodes
+    end
+
+    def parse_unless_block
+      token = consume(:KW_UNLESS)
+      line = token.line
+      column = token.column
+
+      consume_required_whitespace
+      condition = parse_path
+      skip_whitespace
+      consume(:CLOSE)
+
+      body_nodes = parse_unless_body
+
+      consume_block_close(:KW_UNLESS)
+
+      AST::UnlessBlock.new(
+        condition: condition,
+        body_nodes: body_nodes,
+        line: line,
+        column: column
+      )
+    end
+
+    def parse_unless_body
+      nodes = []
+      nodes << parse_node until block_close?(:KW_UNLESS)
+      nodes
+    end
+
+    def else_open?
+      return false unless current_type == :HASH
+
+      saved_pos = @pos
+      advance_token # hash
+      skip_whitespace
+      result = current_type == :KW_ELSE
+      @pos = saved_pos
+      result
+    end
+
+    def consume_else
+      consume(:HASH)
+      skip_whitespace
+      consume(:KW_ELSE)
+      skip_whitespace
+      consume(:CLOSE)
+    end
+
+    def parse_each_block
+      token = consume(:KW_EACH)
+      line = token.line
+      column = token.column
+
+      consume_required_whitespace
+      collection = parse_path
+      consume_required_whitespace
+      consume(:KW_AS)
+      consume_required_whitespace
+      item_name = parse_identifier_with_validation
+
+      skip_whitespace
+      consume(:CLOSE)
+
+      body_nodes = parse_each_body
+
+      consume_block_close(:KW_EACH)
+
+      AST::EachBlock.new(
+        collection: collection,
+        item_name: item_name,
+        body_nodes: body_nodes,
+        line: line,
+        column: column
+      )
+    end
+
+    def parse_each_body
+      nodes = []
+      nodes << parse_node until block_close?(:KW_EACH)
+      nodes
+    end
+
+    def parse_unsecure_output
+      token = consume(:BANG_UNSECURE)
+      line = token.line
+      column = token.column
+
+      consume_required_whitespace
+      path = parse_path
+      skip_whitespace
+      consume(:CLOSE)
+
+      AST::UnsecureOutput.new(path: path, line: line, column: column)
+    end
+
+    def parse_include
+      token = consume(:BANG_INCLUDE)
+      line = token.line
+      column = token.column
+
+      consume_required_whitespace
+      name = parse_include_name
+      args = parse_include_args
+      skip_whitespace
+      consume(:CLOSE)
+
+      AST::Include.new(name: name, args: args, line: line, column: column)
+    end
+
+    def parse_include_name
+      first_token = current_token
+      unless current_type == :SLASH
+        raise ParseError.new("Include name must start with '/'", line: first_token.line, column: first_token.column)
+      end
+
+      segments = [parse_include_segment]
+      segments << parse_include_segment while current_type == :SLASH
+
+      path = segments.join
+      Validator.validate_include_name_syntax!(path, line: first_token.line, column: first_token.column)
+      path
+    end
+
+    def parse_include_segment
+      consume(:SLASH)
+
+      token = current_token
+      if current_type == :INVALID
+        raise LexerError.new("Invalid character in include path: '#{token.value}'",
+                             line: token.line, column: token.column)
+      end
+      unless current_type == :IDENT
+        raise ParseError.new('Expected identifier after /', line: token.line, column: token.column)
+      end
+
+      ident_token = consume(:IDENT)
+      if ident_token.value.start_with?('_')
+        raise LexerError.new("Include segment cannot start with underscore: #{ident_token.value}",
+                             line: ident_token.line, column: ident_token.column)
+      end
+
+      "/#{ident_token.value}"
+    end
+
+    def parse_include_args
+      args = {}
+
+      while current_type == :WHITESPACE
+        skip_whitespace
+        break unless current_type == :IDENT
+
+        key, value, key_token = parse_include_arg
+        if args.key?(key)
+          raise ParseError.new("Duplicate include argument: #{key}", line: key_token.line, column: key_token.column)
+        end
+
+        args[key] = value
+      end
+
+      args
+    end
+
+    def parse_include_arg
+      key_token = consume(:IDENT)
+      Validator.validate_identifier!(key_token.value, line: key_token.line, column: key_token.column)
+
+      skip_whitespace
+      consume(:EQUAL)
+      skip_whitespace
+      value = parse_path
+
+      [key_token.value, value, key_token]
+    end
+
+    def parse_variable_node
+      path = parse_path(allow_modifier: true)
+      skip_whitespace
+      consume(:CLOSE)
+      path
+    end
+
+    def parse_path(allow_modifier: false)
+      first_token = current_token
+      segments = [parse_identifier_with_validation]
+
+      while current_type == :DOT
+        consume(:DOT)
+        segments << parse_identifier_with_validation
+      end
+
+      modifier = nil
+      modifier = parse_modifier if allow_modifier
+
+      AST::Variable.new(segments, modifier: modifier, line: first_token.line, column: first_token.column)
+    end
+
+    def parse_modifier
+      case current_type
+      when :QUESTION
+        advance_token
+        :nullable
+      when :EXCLAMATION
+        advance_token
+        :required
+      end
+    end
+
+    def parse_identifier_with_validation
+      token = current_token
+
+      if keyword_token?(token)
+        advance_token
+        raise ReservedWordError.new("'#{token.value}' is a reserved word", line: token.line, column: token.column)
+      end
+
+      token = consume(:IDENT)
+
+      if Token::RESERVED_WORDS.include?(token.value)
+        raise ReservedWordError.new("'#{token.value}' is a reserved word", line: token.line, column: token.column)
+      end
+
+      Validator.validate_identifier!(token.value, line: token.line, column: token.column)
+      token.value
+    end
+
+    def keyword_token?(token)
+      return false if token.nil?
+
+      %i[KW_IF KW_UNLESS KW_ELSE KW_EACH KW_AS].include?(token.type)
+    end
+
+    def block_close?(keyword = nil)
+      return false unless current_type == :SLASH
+
+      return true unless keyword
+
+      saved_pos = @pos
+      advance_token # slash
+      skip_whitespace
+      result = current_type == keyword
+      @pos = saved_pos
+      result
+    end
+
+    def consume_block_close(keyword)
+      consume(:SLASH)
+      skip_whitespace
+      consume(keyword)
+      skip_whitespace
+      consume(:CLOSE)
+    end
+
+    def current_token
+      @tokens[@pos]
+    end
+
+    def current_type
+      current_token&.type
+    end
+
+    def advance_token
+      @pos += 1
+    end
+
+    def consume(type)
+      token = current_token
+      unexpected_token!("Expected #{type}") if token.nil? || token.type != type
+      advance_token
+      token
+    end
+
+    def consume_required_whitespace
+      unexpected_token!('Expected whitespace') unless current_type == :WHITESPACE
+      skip_whitespace
+    end
+
+    def skip_whitespace
+      advance_token while current_type == :WHITESPACE
+    end
+
+    def unexpected_token!(message = nil)
+      token = current_token
+      msg = message || 'Unexpected token'
+      msg = "#{msg}: #{token.type}" if token
+      raise ParseError.new(msg, line: token&.line, column: token&.column)
+    end
+  end
+end

data/lib/natsuzora/payload.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  # Wraps raw host data prepared for a single {Template#render} call.
+  #
+  # The class is the explicit boundary between untrusted host data
+  # (Symbol-keyed Hashes, host-side numeric types, etc.) and the value
+  # space that {Renderer} and {Context} consume.
+  #
+  # On construction:
+  #
+  # 1. Adapts host data via the {DataNormalizable} mixin
+  #    (Symbol→String keys, whole-number Float→Integer). Pure
+  #    transformation; never raises.
+  # 2. Asserts conformance to Natsuzora's value type system via
+  #    {Validator.validate_data!}. Raises {Natsuzora::TypeError} on any
+  #    residual violation (Float left over, Integer outside the safe
+  #    range, NaN/Infinity).
+  #
+  # If `new` returns, `#data` is guaranteed to conform; downstream
+  # components trust the result without further validation.
+  class Payload
+    include DataNormalizable
+
+    # @return [Hash] adapted and validated root data
+    attr_reader :data
+
+    def initialize(raw_data)
+      raise Natsuzora::TypeError, 'Root data must be an object' unless raw_data.is_a?(Hash)
+
+      @data = normalize_data(raw_data)
+      Validator.validate_data!(@data)
+    end
+  end
+end

data/lib/natsuzora/renderer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class Renderer
+    MAX_RENDER_DEPTH = 1024
+    MAX_OUTPUT_BYTES = 50 * 1024 * 1024 # 50 MB
+
+    def initialize(ast, template_loader: nil)
+      @ast = ast
+      @template_loader = template_loader
+    end
+
+    def render(data)
+      @context = Context.new(data)
+      @depth = 0
+      output = render_nodes(@ast.nodes)
+      raise RenderError, "output exceeded #{MAX_OUTPUT_BYTES} bytes" if output.bytesize > MAX_OUTPUT_BYTES
+
+      output
+    end
+
+    private
+
+    def render_nodes(nodes)
+      @depth += 1
+      raise RenderError, "render depth exceeded #{MAX_RENDER_DEPTH}" if @depth > MAX_RENDER_DEPTH
+
+      begin
+        nodes.map { |node| render_node(node) }.join
+      ensure
+        @depth -= 1
+      end
+    end
+
+    def render_node(node)
+      case node
+      when AST::Text
+        render_text(node)
+      when AST::Variable
+        render_variable(node)
+      when AST::IfBlock
+        render_if(node)
+      when AST::UnlessBlock
+        render_unless(node)
+      when AST::EachBlock
+        render_each(node)
+      when AST::UnsecureOutput
+        render_unsecure_output(node)
+      when AST::Include
+        render_include(node)
+      else
+        raise RenderError, "Unknown node type: #{node.class}"
+      end
+    end
+
+    def render_text(node)
+      node.content
+    end
+
+    def render_variable(node)
+      value = @context.resolve(node)
+      str = stringify_with_modifier(value, node.modifier)
+      HtmlEscape.escape(str)
+    end
+
+    def stringify_with_modifier(value, modifier)
+      case modifier
+      when :nullable
+        Value.stringify_nullable(value)
+      when :required
+        Value.stringify_required(value)
+      else
+        Value.stringify(value)
+      end
+    end
+
+    def render_if(node)
+      value = @context.resolve(node.condition)
+      if Value.truthy?(value)
+        render_nodes(node.then_nodes)
+      elsif node.else_nodes
+        render_nodes(node.else_nodes)
+      else
+        ''
+      end
+    end
+
+    def render_unless(node)
+      value = @context.resolve(node.condition)
+      if Value.truthy?(value)
+        ''
+      else
+        render_nodes(node.body_nodes)
+      end
+    end
+
+    def render_each(node)
+      collection = @context.resolve(node.collection)
+      Value.ensure_array!(collection)
+
+      buffer = +''
+      collection.each do |item|
+        bindings = { node.item_name => item }
+        buffer << @context.with_scope(bindings) { render_nodes(node.body_nodes) }
+        raise RenderError, "output exceeded #{MAX_OUTPUT_BYTES} bytes" if buffer.bytesize > MAX_OUTPUT_BYTES
+      end
+      buffer
+    end
+
+    def render_unsecure_output(node)
+      value = @context.resolve(node.path)
+      Value.stringify(value) # No escaping
+    end
+
+    def render_include(node)
+      raise IncludeError, 'Template loader not configured for include' unless @template_loader
+
+      partial_ast = @template_loader.load(node.name)
+
+      bindings = {}
+      node.args.each do |key, var|
+        bindings[key] = @context.resolve(var)
+      end
+
+      @template_loader.with_include(node.name) do
+        @context.with_scope(bindings, include_scope: true) do
+          render_nodes(partial_ast.nodes)
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/template.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  # Top-level entry that compiles a template source and renders against a
+  # {Payload}.
+  #
+  # `Template#render` accepts only a {Payload}, which is the explicit
+  # boundary between untrusted host data and the internal value space.
+  # Callers wishing to render from a raw Hash should either use the
+  # convenience facade {Natsuzora.render} or wrap the Hash in
+  # `Natsuzora::Payload.new(...)` themselves.
+  class Template
+    attr_reader :ast
+
+    def initialize(source, include_root: nil)
+      @source = source
+      @loader = include_root && TemplateLoader.new(include_root)
+      @ast = parse_ruby(source)
+    end
+
+    # @param payload [Natsuzora::Payload] prepared render input
+    # @return [String] rendered output
+    def render(payload)
+      Renderer.new(@ast, template_loader: @loader).render(payload.data)
+    end
+
+    private
+
+    def parse_ruby(source)
+      tokens = Lexer.new(source).tokenize
+      Parser.new(tokens).parse
+    end
+  end
+end