natsuzora 0.4.0

data/lib/natsuzora/template_loader.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class TemplateLoader
+    class IncludePathResolver
+      def initialize(include_root)
+        @include_root = File.expand_path(include_root)
+        @include_root_realpath = nil
+      end
+
+      def resolve_template_path(name)
+        segments = name.split('/').reject(&:empty?)
+        segments[-1] = "_#{segments[-1]}"
+        "#{File.join(@include_root, *segments)}.ntzr"
+      end
+
+      def ensure_within_root!(path)
+        candidate = canonicalize_candidate(path)
+        root = canonical_root
+        return if within_root?(candidate, root)
+
+        raise IncludeError, "Path traversal detected: #{path}"
+      end
+
+      private
+
+      def canonical_root
+        return @include_root_realpath if @include_root_realpath
+
+        @include_root_realpath = File.realpath(@include_root)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise IncludeError, "Invalid include root: #{e.message}"
+      end
+
+      def canonicalize_candidate(path)
+        absolute = File.expand_path(path)
+        return File.realpath(absolute) if File.exist?(absolute)
+
+        existing_parent, missing_segments = split_existing_parent(absolute)
+        File.join(File.realpath(existing_parent), *missing_segments)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise IncludeError, "Failed to resolve include path: #{e.message}"
+      end
+
+      def split_existing_parent(path)
+        cursor = path
+        missing_segments = []
+
+        until File.exist?(cursor)
+          missing_segments.unshift(File.basename(cursor))
+          parent = File.dirname(cursor)
+          break if parent == cursor
+
+          cursor = parent
+        end
+
+        [cursor, missing_segments]
+      end
+
+      def within_root?(path, root)
+        return true if path == root
+
+        root_prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+        path.start_with?(root_prefix)
+      end
+    end
+
+    def initialize(include_root)
+      raise ArgumentError, 'include_root is required' if include_root.nil?
+
+      @path_resolver = IncludePathResolver.new(include_root)
+      @cache = {}
+      @include_stack = []
+    end
+
+    def load(name)
+      validate_name!(name)
+
+      raise IncludeError, "Circular include detected: #{name}" if @include_stack.include?(name)
+
+      @cache[name] ||= load_and_parse(name)
+    end
+
+    def with_include(name)
+      @include_stack.push(name)
+      yield
+    rescue StandardError => e
+      raise e.class, "#{e.message}\n  within include #{include_stack_trace}", e.backtrace
+    ensure
+      @include_stack.pop
+    end
+
+    private
+
+    def validate_name!(name)
+      Validator.validate_include_name_runtime!(name)
+    end
+
+    def load_and_parse(name)
+      path = @path_resolver.resolve_template_path(name)
+      @path_resolver.ensure_within_root!(path)
+
+      raise IncludeError, "Include file not found: #{name} (#{path})" unless File.file?(path)
+
+      source = File.read(path, encoding: 'UTF-8')
+      tokens = Lexer.new(source).tokenize
+      Parser.new(tokens).parse
+    end
+
+    def include_stack_trace
+      parts = @include_stack.map do |name|
+        path = @path_resolver.resolve_template_path(name)
+        "#{name} (#{path})"
+      end
+      (parts + ['current include']).join(' > ')
+    end
+  end
+end

data/lib/natsuzora/token.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  class Token
+    attr_reader :type, :value, :line, :column
+
+    RESERVED_WORDS = %w[if unless else each as in of unsecure true false null include].freeze
+
+    def initialize(type, value, line:, column:)
+      @type = type
+      @value = value
+      @line = line
+      @column = column
+    end
+
+    def inspect
+      "#<Token #{type}:#{value.inspect} at #{line}:#{column}>"
+    end
+  end
+end

data/lib/natsuzora/validator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  # Centralized validation functions for Natsuzora templates
+  module Validator
+    class << self
+      # Validate an identifier (variable name, each binding, include argument key)
+      #
+      # Rules:
+      # - Cannot be a reserved word (if, unless, each, as, unsecure, true, false, null, include)
+      # - Cannot start with '_' (reserved for internal use)
+      # - Cannot contain '@' (reserved for future use)
+      def validate_identifier!(name, line: nil, column: nil)
+        raise ReservedWordError.new("'#{name}' is a reserved word", line: line, column: column) if Token::RESERVED_WORDS.include?(name)
+
+        raise ParseError.new("Identifier cannot start with '_': #{name}", line: line, column: column) if name.start_with?('_')
+
+        return unless name.include?('@')
+
+        raise ParseError.new("Identifier cannot contain '@': #{name}", line: line, column: column)
+      end
+
+      # Validate an include name at parse time
+      #
+      # Lexer ensures each segment follows Identifier rules (starts with letter).
+      # This validates additional constraints:
+      # - Must start with '/'
+      # - Must have at least one segment after '/'
+      def validate_include_name_syntax!(name, line: nil, column: nil)
+        raise ParseError.new("Include name must start with '/'", line: line, column: column) unless name.start_with?('/')
+
+        return unless name == '/'
+
+        raise ParseError.new('Include name must have at least one segment', line: line, column: column)
+      end
+
+      # Validate an include name at load time
+      #
+      # Defense in depth: re-check basic rules even though lexer enforces them
+      def validate_include_name_runtime!(name)
+        raise IncludeError, "Include name must start with '/': #{name}" unless name.start_with?('/')
+
+        # These should be impossible with the new lexer, but check anyway
+        return unless name.include?('..') || name.include?('//') || name.include?('\\') || name.include?(':')
+
+        raise IncludeError, "Invalid include name: #{name}"
+      end
+
+      # Validate that runtime data conforms to Natsuzora's value type system.
+      #
+      # Error message:
+      # - Float NaN / Infinity     → "Invalid number: ..."
+      # - Other (non-whole) Float  → "Floating point numbers are not supported: ..."
+      # - Integer out of safe range → "Integer out of range: ..."
+      def validate_data!(data)
+        case data
+        when Hash
+          data.each_value { |v| validate_data!(v) }
+        when Array
+          data.each { |v| validate_data!(v) }
+        when Integer
+          return if data.between?(Value::INTEGER_MIN, Value::INTEGER_MAX)
+
+          raise Natsuzora::TypeError, "Integer out of range: #{data}"
+        when Float
+          raise Natsuzora::TypeError, "Invalid number: #{data}" unless data.finite?
+
+          raise Natsuzora::TypeError, "Floating point numbers are not supported: #{data}"
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/value.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  module Value
+    INTEGER_MIN = -9_007_199_254_740_991
+    INTEGER_MAX = 9_007_199_254_740_991
+
+    class << self
+      # Stringify value (v4.0: null is an error)
+      def stringify(value)
+        case value
+        when String
+          value
+        when Integer
+          validate_integer_range!(value)
+          value.to_s
+        when NilClass
+          raise TypeError, "Cannot stringify null value without '?' modifier"
+        when TrueClass, FalseClass
+          raise TypeError, 'Cannot stringify boolean value'
+        when Array
+          raise TypeError, 'Cannot stringify array'
+        when Hash
+          raise TypeError, 'Cannot stringify object'
+        else
+          raise TypeError, "Cannot stringify value of type #{value.class}"
+        end
+      end
+
+      # Stringify with nullable modifier (null -> empty string)
+      def stringify_nullable(value)
+        return '' if value.nil?
+
+        stringify(value)
+      end
+
+      # Stringify with required modifier (null and empty string are errors)
+      def stringify_required(value)
+        raise TypeError, "Cannot stringify null value with '!' modifier" if value.nil?
+        raise TypeError, "Cannot stringify empty string with '!' modifier" if value == ''
+
+        stringify(value)
+      end
+
+      def truthy?(value)
+        case value
+        when false, nil
+          false
+        when Integer
+          value != 0
+        when String, Array, Hash
+          !value.empty?
+        else
+          true
+        end
+      end
+
+      def ensure_array!(value)
+        raise TypeError, "Expected array, got #{value.class}" unless value.is_a?(Array)
+
+        value
+      end
+
+      private
+
+      def validate_integer_range!(value)
+        return if value.between?(INTEGER_MIN, INTEGER_MAX)
+
+        raise TypeError, "Integer out of range: #{value}"
+      end
+    end
+  end
+end

data/lib/natsuzora/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  VERSION = '0.4.0'
+end

data/lib/natsuzora.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'natsuzora/version'
+require_relative 'natsuzora/errors'
+require_relative 'natsuzora/token'
+require_relative 'natsuzora/validator'
+require_relative 'natsuzora/html_escape'
+require_relative 'natsuzora/value'
+require_relative 'natsuzora/data_normalizable'
+require_relative 'natsuzora/ast'
+require_relative 'natsuzora/lexer'
+require_relative 'natsuzora/parser'
+require_relative 'natsuzora/context'
+require_relative 'natsuzora/template_loader'
+require_relative 'natsuzora/renderer'
+require_relative 'natsuzora/payload'
+require_relative 'natsuzora/template'
+require_relative 'natsuzora/contract'
+
+module Natsuzora
+  class << self
+    def render(source, data, include_root: nil)
+      Template.new(source, include_root: include_root).render(Payload.new(data))
+    end
+
+    def parse(source, include_root: nil)
+      Template.new(source, include_root: include_root)
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: natsuzora
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Aozora Bunko
+bindir: bin
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lexer_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+description: Natsuzora is a minimal, display-only template language designed for static
+  HTML generation and Rails preview templates.
+email:
+- info@aozora.gr.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Rakefile
+- lib/natsuzora.rb
+- lib/natsuzora/ast.rb
+- lib/natsuzora/context.rb
+- lib/natsuzora/contract.rb
+- lib/natsuzora/contract/ast.rb
+- lib/natsuzora/contract/ast/any.rb
+- lib/natsuzora/contract/ast/list.rb
+- lib/natsuzora/contract/ast/node.rb
+- lib/natsuzora/contract/ast/record.rb
+- lib/natsuzora/contract/ast/ref.rb
+- lib/natsuzora/contract/ast/scalar.rb
+- lib/natsuzora/contract/compiled_lexer.rb
+- lib/natsuzora/contract/diff_marker.rb
+- lib/natsuzora/contract/document.rb
+- lib/natsuzora/contract/field.rb
+- lib/natsuzora/contract/parse_error.rb
+- lib/natsuzora/contract/parser.rb
+- lib/natsuzora/contract/scalar_type.rb
+- lib/natsuzora/contract/type_def.rb
+- lib/natsuzora/contract/type_ref_resolver.rb
+- lib/natsuzora/contract/validation_target.rb
+- lib/natsuzora/contract/validator.rb
+- lib/natsuzora/data/lexers/contract.lkt1
+- lib/natsuzora/data/lexers/template.lkt1
+- lib/natsuzora/data_normalizable.rb
+- lib/natsuzora/errors.rb
+- lib/natsuzora/html_escape.rb
+- lib/natsuzora/lexer.rb
+- lib/natsuzora/lexer/compiled_lexer.rb
+- lib/natsuzora/lexer/token_processor.rb
+- lib/natsuzora/lexer_loader.rb
+- lib/natsuzora/lexers/contract.rb
+- lib/natsuzora/lexers/template.rb
+- lib/natsuzora/parser.rb
+- lib/natsuzora/payload.rb
+- lib/natsuzora/renderer.rb
+- lib/natsuzora/template.rb
+- lib/natsuzora/template_loader.rb
+- lib/natsuzora/token.rb
+- lib/natsuzora/validator.rb
+- lib/natsuzora/value.rb
+- lib/natsuzora/version.rb
+homepage: https://github.com/aozorabunko/natsuzora
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aozorabunko/natsuzora
+  source_code_uri: https://github.com/aozorabunko/natsuzora
+  changelog_uri: https://github.com/aozorabunko/natsuzora/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Minimal template language for safe HTML generation
+test_files: []