kumi 0.0.7 → 0.0.8

data/lib/kumi/core/analyzer/passes/dependency_resolver.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Build dependency graph and detect conditional dependencies in cascades
+        # DEPENDENCIES: :declarations from NameIndexer, :inputs from InputCollector
+        # PRODUCES: :dependencies, :dependents, :leaves - Dependency analysis results
+        # INTERFACE: new(schema, state).run(errors)
+        class DependencyResolver < PassBase
+          # Enhanced edge with conditional flag and cascade metadata
+          class DependencyEdge
+            attr_reader :to, :type, :via, :conditional, :cascade_owner
+
+            def initialize(to:, type:, via:, conditional: false, cascade_owner: nil)
+              @to = to
+              @type = type
+              @via = via
+              @conditional = conditional
+              @cascade_owner = cascade_owner
+            end
+          end
+
+          include Syntax
+
+          def run(errors)
+            definitions = get_state(:declarations)
+            input_meta = get_state(:inputs)
+
+            dependency_graph = Hash.new { |h, k| h[k] = [] }
+            reverse_dependencies = Hash.new { |h, k| h[k] = [] }
+            leaf_map = Hash.new { |h, k| h[k] = Set.new }
+
+            each_decl do |decl|
+              # Traverse the expression for each declaration, passing context down
+              visit_with_context(decl.expression, { decl_name: decl.name }) do |node, context|
+                process_node(node, decl, dependency_graph, reverse_dependencies, leaf_map, definitions, input_meta, errors, context)
+              end
+            end
+
+            # Compute transitive closure of reverse dependencies
+            transitive_dependents = compute_transitive_closure(reverse_dependencies)
+
+            state.with(:dependencies, dependency_graph.transform_values(&:freeze).freeze)
+                 .with(:dependents, transitive_dependents.freeze)
+                 .with(:leaves, leaf_map.transform_values(&:freeze).freeze)
+          end
+
+          private
+
+          def process_node(node, decl, graph, reverse_deps, leaves, definitions, _input_meta, errors, context)
+            case node
+            when DeclarationReference
+              report_error(errors, "undefined reference to `#{node.name}`", location: node.loc) unless definitions.key?(node.name)
+
+              # Determine if this is a conditional dependency
+              conditional = context[:in_cascade_branch] || context[:in_cascade_base] || false
+              cascade_owner = conditional ? (context[:cascade_owner] || context[:decl_name]) : nil
+
+              add_dependency_edge(graph, reverse_deps, decl.name, node.name, :ref, context[:via],
+                                  conditional: conditional,
+                                  cascade_owner: cascade_owner)
+            when InputReference
+              add_dependency_edge(graph, reverse_deps, decl.name, node.name, :key, context[:via])
+              leaves[decl.name] << node
+            when InputElementReference
+              # adds the root input declaration as a dependency
+              root_input_declr_name = node.path.first
+              add_dependency_edge(graph, reverse_deps, decl.name, root_input_declr_name, :key, context[:via])
+            when Literal
+              leaves[decl.name] << node
+            end
+          end
+
+          def add_dependency_edge(graph, reverse_deps, from, to, type, via, conditional: false, cascade_owner: nil)
+            edge = DependencyEdge.new(
+              to: to,
+              type: type,
+              via: via,
+              conditional: conditional,
+              cascade_owner: cascade_owner
+            )
+            graph[from] << edge
+            reverse_deps[to] << from
+          end
+
+          # Custom visitor that understands cascade structure
+          def visit_with_context(node, context = {}, &block)
+            return unless node
+
+            yield(node, context)
+
+            case node
+            when CascadeExpression
+              # Visit condition nodes and result expressions (non-base cases)
+              node.cases[0...-1].each do |when_case|
+                if when_case.condition
+                  # Visit condition normally
+                  visit_with_context(when_case.condition, context, &block)
+                end
+                # Visit result expressions as conditional dependencies
+                conditional_context = context.merge(in_cascade_branch: true, cascade_owner: context[:decl_name])
+                visit_with_context(when_case.result, conditional_context, &block)
+              end
+
+              # Visit base case with conditional flag
+              if node.cases.last
+                base_context = context.merge(in_cascade_base: true)
+                visit_with_context(node.cases.last.result, base_context, &block)
+              end
+            when CallExpression
+              new_context = context.merge(via: node.fn_name)
+              node.children.each { |child| visit_with_context(child, new_context, &block) }
+            else
+              node.children.each { |child| visit_with_context(child, context, &block) } if node.respond_to?(:children)
+            end
+          end
+
+          def compute_transitive_closure(reverse_dependencies)
+            transitive = {}
+            all_keys = reverse_dependencies.keys
+
+            all_keys.each do |key|
+              visited = Set.new
+              to_visit = [key]
+              dependents = Set.new
+
+              while to_visit.any?
+                current = to_visit.shift
+                next if visited.include?(current)
+
+                visited.add(current)
+
+                direct_dependents = reverse_dependencies[current] || []
+                direct_dependents.each do |dependent|
+                  next if visited.include?(dependent)
+
+                  dependents << dependent
+                  to_visit << dependent
+                end
+              end
+
+              transitive[key] = dependents.to_a
+            end
+
+            transitive
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/input_collector.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Collect field metadata from input declarations and validate consistency
+        # DEPENDENCIES: :definitions
+        # PRODUCES: :inputs - Hash mapping field names to {type:, domain:} metadata
+        # INTERFACE: new(schema, state).run(errors)
+        class InputCollector < PassBase
+          def run(errors)
+            input_meta = {}
+
+            schema.inputs.each do |field_decl|
+              unless field_decl.is_a?(Kumi::Syntax::InputDeclaration)
+                report_error(errors, "Expected InputDeclaration node, got #{field_decl.class}", location: field_decl.loc)
+                next
+              end
+
+              name = field_decl.name
+              existing = input_meta[name]
+
+              if existing
+                # Check for compatibility and merge
+                merged_meta = merge_field_metadata(existing, field_decl, errors)
+                input_meta[name] = merged_meta if merged_meta
+              else
+                # New field - collect its metadata
+                input_meta[name] = collect_field_metadata(field_decl, errors)
+              end
+            end
+
+            state.with(:inputs, freeze_nested_hash(input_meta))
+          end
+
+          private
+
+          def collect_field_metadata(field_decl, errors)
+            validate_domain_type(field_decl, errors) if field_decl.domain
+
+            metadata = {
+              type: field_decl.type,
+              domain: field_decl.domain
+            }
+
+            # Process children if present
+            if field_decl.children && !field_decl.children.empty?
+              children_meta = {}
+              field_decl.children.each do |child_decl|
+                unless child_decl.is_a?(Kumi::Syntax::InputDeclaration)
+                  report_error(errors, "Expected InputDeclaration node in children, got #{child_decl.class}", location: child_decl.loc)
+                  next
+                end
+                children_meta[child_decl.name] = collect_field_metadata(child_decl, errors)
+              end
+              metadata[:children] = children_meta
+            end
+
+            metadata
+          end
+
+          def merge_field_metadata(existing, field_decl, errors)
+            name = field_decl.name
+
+            # Check for type compatibility
+            if existing[:type] != field_decl.type && field_decl.type && existing[:type]
+              report_error(errors,
+                           "Field :#{name} declared with conflicting types: #{existing[:type]} vs #{field_decl.type}",
+                           location: field_decl.loc)
+            end
+
+            # Check for domain compatibility
+            if existing[:domain] != field_decl.domain && field_decl.domain && existing[:domain]
+              report_error(errors,
+                           "Field :#{name} declared with conflicting domains: #{existing[:domain].inspect} vs #{field_decl.domain.inspect}",
+                           location: field_decl.loc)
+            end
+
+            # Validate domain type if provided
+            validate_domain_type(field_decl, errors) if field_decl.domain
+
+            # Merge metadata (later declarations override nil values)
+            merged = {
+              type: field_decl.type || existing[:type],
+              domain: field_decl.domain || existing[:domain]
+            }
+
+            # Merge children if present
+            if field_decl.children && !field_decl.children.empty?
+              existing_children = existing[:children] || {}
+              new_children = {}
+
+              field_decl.children.each do |child_decl|
+                unless child_decl.is_a?(Kumi::Syntax::InputDeclaration)
+                  report_error(errors, "Expected InputDeclaration node in children, got #{child_decl.class}", location: child_decl.loc)
+                  next
+                end
+
+                child_name = child_decl.name
+                new_children[child_name] = if existing_children[child_name]
+                                             merge_field_metadata(existing_children[child_name], child_decl, errors)
+                                           else
+                                             collect_field_metadata(child_decl, errors)
+                                           end
+              end
+
+              merged[:children] = new_children
+            elsif existing[:children]
+              merged[:children] = existing[:children]
+            end
+
+            merged
+          end
+
+          def freeze_nested_hash(hash)
+            hash.each_value do |value|
+              freeze_nested_hash(value) if value.is_a?(Hash)
+            end
+            hash.freeze
+          end
+
+          def validate_domain_type(field_decl, errors)
+            domain = field_decl.domain
+            return if valid_domain_type?(domain)
+
+            report_error(errors,
+                         "Field :#{field_decl.name} has invalid domain constraint: #{domain.inspect}. Domain must be a Range, Array, or Proc",
+                         location: field_decl.loc)
+          end
+
+          def valid_domain_type?(domain)
+            domain.is_a?(Range) || domain.is_a?(Array) || domain.is_a?(Proc)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/name_indexer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Build definitions index and detect duplicate names
+        # DEPENDENCIES: None (first pass in pipeline)
+        # PRODUCES: :declarations - Hash mapping names to declaration nodes
+        # INTERFACE: new(schema, state).run(errors)
+        class NameIndexer < PassBase
+          def run(errors)
+            definitions = {}
+
+            each_decl do |decl|
+              report_error(errors, "duplicated definition `#{decl.name}`", location: decl.loc) if definitions.key?(decl.name)
+              definitions[decl.name] = decl
+            end
+
+            state.with(:declarations, definitions.freeze)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/pass_base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # Base class for analyzer passes with simple immutable state
+        class PassBase
+          include Kumi::Syntax
+          include Kumi::Core::ErrorReporting
+
+          # @param schema [Syntax::Root] The schema to analyze
+          # @param state [AnalysisState] Current analysis state
+          def initialize(schema, state)
+            @schema = schema
+            @state = state
+          end
+
+          # Main pass execution - subclasses implement this
+          # @param errors [Array] Error accumulator array
+          # @return [AnalysisState] New state after pass execution
+          def run(errors)
+            raise NotImplementedError, "#{self.class.name} must implement #run"
+          end
+
+          protected
+
+          attr_reader :schema, :state
+
+          # Iterate over all declarations (attributes and traits) in the schema
+          # @yield [Syntax::Attribute|Syntax::Trait] Each declaration
+          def each_decl(&block)
+            schema.attributes.each(&block)
+            schema.traits.each(&block)
+          end
+
+          # Get state value - compatible with old interface
+          def get_state(key, required: true)
+            raise StandardError, "Required state key '#{key}' not found" if required && !state.key?(key)
+
+            state[key]
+          end
+
+          # Add error to the error list
+          def add_error(errors, location, message)
+            errors << ErrorReporter.create_error(message, location: location, type: :semantic)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/semantic_constraint_validator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Validate DSL semantic constraints at the AST level
+        # DEPENDENCIES: :definitions
+        # PRODUCES: None (validation only)
+        # INTERFACE: new(schema, state).run(errors)
+        #
+        # This pass enforces semantic constraints that must hold regardless of which parser
+        # was used to construct the AST. It validates:
+        # 1. Cascade conditions are only trait references (DeclarationReference nodes)
+        # 2. Trait expressions evaluate to boolean values (CallExpression nodes)
+        # 3. Function names exist in the function registry
+        # 4. Expression types are valid for their context
+        class SemanticConstraintValidator < VisitorPass
+          def run(errors)
+            each_decl do |decl|
+              visit(decl) { |node| validate_semantic_constraints(node, decl, errors) }
+            end
+            state
+          end
+
+          private
+
+          def validate_semantic_constraints(node, _decl, errors)
+            case node
+            when Kumi::Syntax::TraitDeclaration
+              validate_trait_expression(node, errors)
+            when Kumi::Syntax::CaseExpression
+              validate_cascade_condition(node, errors)
+            when Kumi::Syntax::CallExpression
+              validate_function_call(node, errors)
+            end
+          end
+
+          def validate_trait_expression(trait, errors)
+            return if trait.expression.is_a?(Kumi::Syntax::CallExpression)
+
+            report_error(
+              errors,
+              "trait `#{trait.name}` must have a boolean expression",
+              location: trait.loc,
+              type: :semantic
+            )
+          end
+
+          def validate_cascade_condition(when_case, errors)
+            condition = when_case.condition
+
+            case condition
+            when Kumi::Syntax::DeclarationReference
+              # Valid: trait reference
+              nil
+            when Kumi::Syntax::CallExpression
+              # Valid if it's a boolean composition of traits (all?, any?, none?)
+              return if boolean_trait_composition?(condition)
+
+              # For now, allow other CallExpressions - they'll be validated by other passes
+              nil
+            when Kumi::Syntax::Literal
+              # Allow literal conditions (like true/false) - they might be valid
+              nil
+            else
+              # Only reject truly invalid conditions like InputReference or complex expressions
+              report_error(
+                errors,
+                "cascade condition must be trait reference",
+                location: when_case.loc,
+                type: :semantic
+              )
+            end
+          end
+
+          def validate_function_call(call_expr, errors)
+            fn_name = call_expr.fn_name
+
+            # Skip validation if Kumi::Registry.is being mocked for testing
+            return if function_registry_mocked?
+
+            return if Kumi::Registry.supported?(fn_name)
+
+            report_error(
+              errors,
+              "unknown function `#{fn_name}`",
+              location: call_expr.loc,
+              type: :semantic
+            )
+          end
+
+          def boolean_trait_composition?(call_expr)
+            # Allow boolean composition functions that operate on trait collections
+            %i[all? any? none?].include?(call_expr.fn_name)
+          end
+
+          def function_registry_mocked?
+            # Check if Kumi::Registry.is being mocked (for tests)
+
+            # Try to access a method that doesn't exist in the real registry
+            # If it's mocked, this won't raise an error
+            Kumi::Registry.respond_to?(:confirm_support!)
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/toposorter.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Compute topological ordering of declarations, allowing safe conditional cycles
+        # DEPENDENCIES: :dependencies from DependencyResolver, :declarations from NameIndexer, :cascades from UnsatDetector
+        # PRODUCES: :evaluation_order - Array of declaration names in evaluation order
+        # INTERFACE: new(schema, state).run(errors)
+        class Toposorter < PassBase
+          def run(errors)
+            dependency_graph = get_state(:dependencies, required: false) || {}
+            definitions = get_state(:declarations, required: false) || {}
+
+            order = compute_topological_order(dependency_graph, definitions, errors)
+            state.with(:evaluation_order, order)
+          end
+
+          private
+
+          def compute_topological_order(graph, definitions, errors)
+            temp_marks = Set.new
+            perm_marks = Set.new
+            order = []
+            cascades = get_state(:cascades) || {}
+
+            visit_node = lambda do |node, path = []|
+              return if perm_marks.include?(node)
+
+              if temp_marks.include?(node)
+                # Check if this is a safe conditional cycle
+                cycle_path = path + [node]
+                return if safe_conditional_cycle?(cycle_path, graph, cascades)
+
+                # Allow this cycle - it's safe due to cascade mutual exclusion
+
+                report_unexpected_cycle(temp_marks, node, errors)
+
+                return
+              end
+
+              temp_marks << node
+              current_path = path + [node]
+              Array(graph[node]).each { |edge| visit_node.call(edge.to, current_path) }
+              temp_marks.delete(node)
+              perm_marks << node
+
+              # Only include declaration nodes in the final order
+              order << node if definitions.key?(node)
+            end
+
+            # Visit all nodes in the graph
+            graph.each_key { |node| visit_node.call(node) }
+
+            # Also visit any definitions that aren't in the dependency graph
+            # (i.e., declarations with no dependencies)
+            definitions.each_key { |node| visit_node.call(node) }
+
+            order.freeze
+          end
+
+          def safe_conditional_cycle?(cycle_path, graph, cascades)
+            return false if cycle_path.nil? || cycle_path.size < 2
+
+            # Find where the cycle starts - look for the first occurrence of the repeated node
+            last_node = cycle_path.last
+            return false if last_node.nil?
+
+            cycle_start = cycle_path.index(last_node)
+            return false unless cycle_start && cycle_start < cycle_path.size - 1
+
+            cycle_nodes = cycle_path[cycle_start..]
+
+            # Check if all edges in the cycle are conditional
+            cycle_nodes.each_cons(2) do |from, to|
+              edges = graph[from] || []
+              edge = edges.find { |e| e.to == to }
+
+              return false unless edge&.conditional
+
+              # Check if the cascade has mutually exclusive conditions
+              cascade_meta = cascades[edge.cascade_owner]
+              return false unless cascade_meta&.dig(:all_mutually_exclusive)
+            end
+
+            true
+          end
+
+          def report_unexpected_cycle(temp_marks, current_node, errors)
+            cycle_path = temp_marks.to_a.join(" → ") + " → #{current_node}"
+
+            # Try to find the first declaration in the cycle for location info
+            first_decl = find_declaration_by_name(temp_marks.first || current_node)
+            location = first_decl&.loc
+
+            report_error(errors, "cycle detected: #{cycle_path}", location: location)
+          end
+
+          def find_declaration_by_name(name)
+            return nil unless schema
+
+            schema.attributes.find { |attr| attr.name == name } ||
+              schema.traits.find { |trait| trait.name == name }
+          end
+        end
+      end
+    end
+  end
+end