natsuzora 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c392b524dfcc75df005176d7e8dc65337be7d94f26575f9b0816c40a7e061d4c
+  data.tar.gz: f660922c286c77a2b2ac6e863ae4a8f2427eb50ba7a70c50838d0d56e524c898
+SHA512:
+  metadata.gz: 56c8ad664c64fb5f94992d1eadb163276c14494ab7c452b19d32d2a7fd81fcaedbf5eb89707cd0d9b0151b90ef7d20efce805a680b594bfd1be7be644e5d383d
+  data.tar.gz: 0f68bef0e391fc137904d96287d5daad54bbd29de293477b705138436bb5c6ff0efe80cbf94d584b2a69d459aa748418b7a5f43aeeacd501df6cef80ef0f6be9

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,55 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/ClassLength:
+  Max: 400
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+RSpec/DescribedClass:
+  EnforcedStyle: explicit
+
+RSpec/ExampleLength:
+  Max: 25
+
+RSpec/MultipleExpectations:
+  Max: 20
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: false
+
+

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 0.4.0
+
+### Added
+- `Natsuzora::Contract` namespace which absorbs the formerly separate `subaru` gem.
+  Provides parsing of `.ntzc` contract notation and validation of JSON data
+  against contracts. Two-generation diff markers (`+`, `-`, `*`) are supported.
+- Module-level helpers: `Natsuzora::Contract.parse(input)`,
+  `Natsuzora::Contract.parse_file(input)`,
+  `Natsuzora::Contract.parse_file_with_diff(input)`,
+  `Natsuzora::Contract.validate(contract, data)`,
+  `Natsuzora::Contract.validate_with_target(document, data, target:)`.
+- Contract AST nodes are grouped under `Natsuzora::Contract::AST::`
+  (`Any`, `Scalar`, `Record`, `List`, `Ref`, with `Node` as the abstract
+  base). `Natsuzora::Contract::AST.from_h(hash)` rebuilds an AST tree
+  from its hash representation.
+- `Natsuzora::Contract::TypeRefResolver` walks an AST tree replacing
+  `AST::Ref` nodes with concrete contracts; configurable via
+  `on_missing` / `on_unavailable` / `on_cyclic` callbacks. Cyclic type
+  references (e.g. `type A { ref: B }; type B { ref: A }`) raise via
+  `on_cyclic` instead of recursing forever.
+- Resource limits to bound pathological input:
+  - `Natsuzora::Renderer::MAX_RENDER_DEPTH` (1024) — caps recursion
+    through nested `{[#if]}` / `{[#each]}` / `{[!include]}` blocks.
+  - `Natsuzora::Renderer::MAX_OUTPUT_BYTES` (50 MiB) — caps the
+    rendered output size, checked per `{[#each]}` iteration.
+  - `Natsuzora::Contract::Validator::MAX_VALIDATE_DEPTH` (64) — caps
+    nesting depth of validated data trees.
+  Exceeding any limit raises `Natsuzora::RenderError` or
+  `Natsuzora::Contract::ValidationError` with a descriptive message.
+- Shared JSON tests under `tests/contract/` for cross-language parity with
+  the Rust `natsuzora-contract` crate.
+- `Natsuzora::Payload` class wrapping render input data. The class
+  encapsulates the boundary between untrusted host data and Natsuzora's
+  internal value space (Symbol→String key adaptation, whole-number
+  Float→Integer coercion, plus type/range validation).
+- `Natsuzora::DataNormalizable` mixin providing `normalize_data(data)` for
+  pure data adaptation (no exceptions raised).
+- `Natsuzora::Validator.validate_data!(data)` for asserting that a
+  prepared value conforms to the Natsuzora type system.
+
+### Changed
+- **Breaking** (pre-1.0): `Natsuzora::Template#render` now accepts a
+  `Natsuzora::Payload` instead of a raw `Hash`. The top-level facade
+  `Natsuzora.render(source, data, ...)` is unchanged and wraps `data` in a
+  Payload internally; only callers that construct a `Template` directly
+  via `Natsuzora.parse` need to update.
+
+  ```ruby
+  # Before
+  template = Natsuzora.parse(source)
+  template.render(hash)
+
+  # After
+  template = Natsuzora.parse(source)
+  template.render(Natsuzora::Payload.new(hash))
+  ```
+
+## 0.2.0
+
+Initial release of the natsuzora template language.

data/Rakefile

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'fileutils'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+LEXER_ROOT = File.expand_path(__dir__)
+LEXERS = {
+  contract: {
+    source: File.join(LEXER_ROOT, 'lib', 'natsuzora', 'lexers', 'contract.rb'),
+    output: File.join(LEXER_ROOT, 'lib', 'natsuzora', 'data', 'lexers', 'contract.lkt1')
+  },
+  template: {
+    source: File.join(LEXER_ROOT, 'lib', 'natsuzora', 'lexers', 'template.rb'),
+    output: File.join(LEXER_ROOT, 'lib', 'natsuzora', 'data', 'lexers', 'template.lkt1')
+  }
+}.freeze
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+def build_program(source)
+  require 'lexer_kit'
+  LexerKit.load_builder(source).compile
+end
+
+def compile_lexers
+  require 'lexer_kit'
+
+  LEXERS.each do |name, config|
+    FileUtils.mkdir_p(File.dirname(config[:output]))
+    LexerKit::Format::LKT1.save(build_program(config[:source]), path: config[:output])
+    puts "Compiled #{name} lexer to #{config[:output]}"
+  end
+end
+
+def lexer_check_failures
+  require 'lexer_kit'
+
+  LEXERS.each_with_object([]) do |(name, config), failures|
+    unless File.file?(config[:output])
+      failures << "Missing #{name} lexer: #{config[:output]}"
+      next
+    end
+
+    expected_binary = build_program(config[:source]).to_binary
+    actual_binary = LexerKit.load_lexer(config[:output]).to_binary
+    failures << "Stale #{name} lexer: #{config[:output]}" unless actual_binary == expected_binary
+  rescue StandardError => e
+    failures << "Invalid #{name} lexer: #{e.class}: #{e.message}"
+  end
+end
+
+def abort_if_lexers_stale
+  failures = lexer_check_failures
+  return if failures.empty?
+
+  failures.each { |failure| warn failure }
+  abort 'Precompiled lexer files are not up to date. Run `rake lexers:compile`.'
+end
+
+namespace :lexers do
+  desc 'Compile LexerKit DSL files into precompiled .lkt1 programs'
+  task :compile do
+    compile_lexers
+  end
+
+  desc 'Verify precompiled LexerKit programs are present and up to date'
+  task :check do
+    abort_if_lexers_stale
+  end
+end
+
+task default: %i[lexers:check spec rubocop]

data/lib/natsuzora/ast.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  module AST
+    class Node
+      attr_reader :line, :column
+
+      def initialize(line: nil, column: nil)
+        @line = line
+        @column = column
+      end
+    end
+
+    class Template < Node
+      attr_reader :nodes
+
+      def initialize(nodes, **)
+        super(**)
+        @nodes = nodes
+      end
+    end
+
+    class Text < Node
+      attr_reader :content
+
+      def initialize(content, **)
+        super(**)
+        @content = content
+      end
+    end
+
+    class Variable < Node
+      attr_reader :path, :modifier
+
+      # modifier: nil (default), :nullable (?), :required (!)
+      def initialize(path, modifier: nil, **)
+        super(**)
+        @path = path
+        @modifier = modifier
+      end
+    end
+
+    class IfBlock < Node
+      attr_reader :condition, :then_nodes, :else_nodes
+
+      def initialize(condition:, then_nodes:, else_nodes: nil, **)
+        super(**)
+        @condition = condition
+        @then_nodes = then_nodes
+        @else_nodes = else_nodes
+      end
+    end
+
+    class UnlessBlock < Node
+      attr_reader :condition, :body_nodes
+
+      def initialize(condition:, body_nodes:, **)
+        super(**)
+        @condition = condition
+        @body_nodes = body_nodes
+      end
+    end
+
+    class EachBlock < Node
+      attr_reader :collection, :item_name, :body_nodes
+
+      def initialize(collection:, item_name:, body_nodes:, **)
+        super(**)
+        @collection = collection
+        @item_name = item_name
+        @body_nodes = body_nodes
+      end
+    end
+
+    class UnsecureOutput < Node
+      attr_reader :path
+
+      def initialize(path:, **)
+        super(**)
+        @path = path
+      end
+    end
+
+    class Include < Node
+      attr_reader :name, :args
+
+      def initialize(name:, args:, **)
+        super(**)
+        @name = name
+        @args = args
+      end
+    end
+  end
+end

data/lib/natsuzora/context.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  # Manages variable scope and resolution during rendering.
+  class Context
+    def initialize(root_data)
+      raise Natsuzora::TypeError, 'Root data must be an object' unless root_data.is_a?(Hash)
+
+      @root = root_data
+      @local_stack = []
+    end
+
+    def resolve(variable)
+      path = variable.path
+      line = variable.line
+      column = variable.column
+
+      name = path.first
+      raise UndefinedVariableError.new('Undefined variable: <empty path>', line: line, column: column) unless name
+
+      value = resolve_name(name, line: line, column: column)
+
+      path[1..].each do |segment|
+        value = access_property(value, segment, line: line, column: column)
+      end
+
+      value
+    end
+
+    def push_scope(bindings = {})
+      validate_no_shadowing!(bindings)
+      @local_stack.push(bindings)
+    end
+
+    def push_include_scope(bindings)
+      @local_stack.push(bindings)
+    end
+
+    def pop_scope
+      @local_stack.pop
+    end
+
+    def with_scope(bindings, include_scope: false)
+      if include_scope
+        push_include_scope(bindings)
+      else
+        push_scope(bindings)
+      end
+      yield
+    ensure
+      pop_scope
+    end
+
+    private
+
+    def resolve_name(name, line: nil, column: nil)
+      @local_stack.reverse_each do |scope|
+        return scope[name] if scope.key?(name)
+      end
+
+      return @root[name] if @root.key?(name)
+
+      raise UndefinedVariableError.new("Undefined variable: #{name}", line: line, column: column)
+    end
+
+    def validate_no_shadowing!(bindings)
+      bindings.each_key do |name|
+        name_str = name.to_s
+        origin = binding_origin(name_str)
+        next unless origin
+
+        raise ShadowingError,
+              "Cannot shadow existing variable '#{name_str}' (already defined in #{origin})"
+      end
+    end
+
+    def binding_origin(name)
+      return 'root data' if @root.key?(name)
+
+      @local_stack.reverse_each do |scope|
+        return 'outer local scope' if scope.key?(name)
+      end
+      nil
+    end
+
+    def access_property(value, key, line: nil, column: nil)
+      raise TypeError, "Cannot access property '#{key}' on non-object" unless value.is_a?(Hash)
+
+      unless value.key?(key)
+        raise UndefinedVariableError.new("Undefined property: #{key}", line: line, column: column)
+      end
+
+      value[key]
+    end
+  end
+end

data/lib/natsuzora/contract/ast/any.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Natsuzora
+  module Contract
+    module AST
+      # Any value (unconstrained).
+      class Any < Node
+        def to_h
+          { 'kind' => 'any' }
+        end
+
+        def ==(other)
+          other.is_a?(Any)
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Natsuzora
+  module Contract
+    module AST
+      # Ordered list of items of a single contract type.
+      # Serialized as 'kind' => 'array' for JSON compatibility.
+      class List < Node
+        attr_reader :items
+
+        def initialize(items)
+          super()
+          @items = items
+        end
+
+        def to_h
+          { 'kind' => 'array', 'items' => @items.to_h }
+        end
+
+        def ==(other)
+          other.is_a?(List) && other.items == @items
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast/node.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  module Contract
+    module AST
+      # Base class for contract AST nodes.
+      # Each subclass implements +to_h+ for JSON serialization.
+      # Use +Natsuzora::Contract::AST.from_h+ for deserialization.
+      class Node
+        def to_h
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast/record.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Natsuzora
+  module Contract
+    module AST
+      # Record-style object with named properties.
+      # Serialized as 'kind' => 'object' for JSON compatibility.
+      class Record < Node
+        attr_reader :properties, :required
+
+        def initialize(properties = {}, required = [])
+          super()
+          @properties = properties
+          @required = required
+        end
+
+        def to_h
+          h = { 'kind' => 'object', 'properties' => @properties.transform_values(&:to_h) }
+          h['required'] = @required unless @required.empty?
+          h
+        end
+
+        def ==(other)
+          other.is_a?(Record) &&
+            other.properties == @properties &&
+            other.required == @required
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast/ref.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Natsuzora
+  module Contract
+    module AST
+      # Type reference (used during parsing, resolved before use).
+      class Ref < Node
+        attr_reader :name
+
+        def initialize(name)
+          super()
+          @name = name
+        end
+
+        def to_h
+          { 'kind' => 'ref', 'name' => @name }
+        end
+
+        def ==(other)
+          other.is_a?(Ref) && other.name == @name
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast/scalar.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+require_relative '../scalar_type'
+
+module Natsuzora
+  module Contract
+    module AST
+      # Scalar value with type and modifier.
+      class Scalar < Node
+        # Modifier for null/empty handling on scalar values.
+        module Modifier
+          # Default: null not allowed, empty string allowed
+          NONE = :none
+          # `?` modifier: null allowed
+          NULLABLE = :nullable
+          # `!` modifier: null not allowed, empty string not allowed
+          REQUIRED = :required
+        end
+
+        attr_reader :scalar_type, :modifier
+
+        def initialize(scalar_type, modifier = Modifier::NONE)
+          super()
+          @scalar_type = scalar_type
+          @modifier = modifier
+        end
+
+        def nullable?
+          @modifier == Modifier::NULLABLE
+        end
+
+        def required?
+          @modifier == Modifier::REQUIRED
+        end
+
+        def accepts?(data)
+          case @scalar_type
+          when ScalarType::STRING then data.is_a?(String)
+          when ScalarType::INTEGER then data.is_a?(Integer)
+          when ScalarType::BOOL then data.is_a?(TrueClass) || data.is_a?(FalseClass)
+          when ScalarType::SCALAR then data.is_a?(String) || data.is_a?(Integer)
+          end
+        end
+
+        def to_h
+          h = { 'kind' => 'scalar', 'type' => @scalar_type.to_s }
+          h['modifier'] = @modifier.to_s unless @modifier == Modifier::NONE
+          h
+        end
+
+        def ==(other)
+          other.is_a?(Scalar) &&
+            other.scalar_type == @scalar_type &&
+            other.modifier == @modifier
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/ast.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'ast/node'
+require_relative 'ast/any'
+require_relative 'ast/scalar'
+require_relative 'ast/record'
+require_relative 'ast/list'
+require_relative 'ast/ref'
+
+module Natsuzora
+  module Contract
+    # Contract AST nodes and their serialization helpers.
+    module AST
+      # Build an AST::Node tree from its hash representation.
+      def self.from_h(hash)
+        case hash['kind']
+        when 'any'
+          Any.new
+        when 'scalar'
+          scalar_type = hash['type'].to_sym
+          modifier = (hash['modifier'] || 'none').to_sym
+          Scalar.new(scalar_type, modifier)
+        when 'object'
+          required = hash['required'] || []
+          properties = (hash['properties'] || {}).transform_values { |v| from_h(v) }
+          Record.new(properties, required)
+        when 'array'
+          items = from_h(hash['items'])
+          List.new(items)
+        when 'ref'
+          Ref.new(hash['name'])
+        else
+          raise ArgumentError, "Unknown contract kind: #{hash['kind']}"
+        end
+      end
+    end
+  end
+end

data/lib/natsuzora/contract/compiled_lexer.rb

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

data/lib/natsuzora/contract/diff_marker.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Natsuzora
+  module Contract
+    # Diff marker for 2-generation contracts.
+    module DiffMarker
+      # `+` - Field will be added in next generation
+      ADDED = :added
+      # `-` - Field will be removed in next generation
+      REMOVED = :removed
+      # `*` - Field type will change in next generation
+      CHANGED = :changed
+    end
+  end
+end