hecks 2.9.0 → 3.0.1

data/rust/project/exemplar.rb

@@ -0,0 +1,148 @@
+module RustProjection
+  # Loads the `// TMPL:<id> BEGIN/END` shapes in rust/src/exemplar/*.rs and renders them
+  # by substituting the fixed `Tmpl`/`tmpl_`/`TMPL_` placeholders with real domain names.
+  module Exemplar
+    # Matches any placeholder token. After substitution nothing may match, so an
+    # unfilled placeholder raises instead of leaking `TmplType` into generated output.
+    LEFTOVER_PLACEHOLDER = /\b(?:Tmpl\w*|tmpl_\w*|TMPL_\w*)\b/
+
+    DEFAULT_DIR = File.expand_path("../src/exemplar", __dir__)
+
+    class DriftError < StandardError; end
+
+    class << self
+      # Overridable so specs can point at a scratch fixture tree.
+      def dir
+        @dir ||= DEFAULT_DIR
+      end
+
+      # `id` -> raw shape text (dedented, marker lines excluded).
+      # A nested region leaves a `<<TMPL_SLOT:<id>:<sub>>>` sentinel; see `compose`.
+      def shapes
+        @shapes ||= parse_all
+      end
+
+      # Renders `shape_id`, replacing each `subs` key (a literal substring) with its value.
+      # Raises DriftError on a key absent from the shape or a placeholder left over.
+      #
+      # Uses the block form of gsub: the two-arg form interprets backslash sequences in
+      # the replacement, which corrupts escaped regex sources.
+      def render(shape_id, subs)
+        text = raw(shape_id)
+
+        subs.keys.sort_by { |k| -k.length }.each do |marker|
+          raise DriftError, "Exemplar.render(#{shape_id.inspect}): marker #{marker.inspect} not found in shape text — " \
+                             "exemplar and Ruby caller have drifted" unless text.include?(marker)
+
+          value = subs[marker]
+          text = text.gsub(marker) { value }
+        end
+
+        if (leftover = text.scan(LEFTOVER_PLACEHOLDER)).any?
+          raise DriftError, "Exemplar.render(#{shape_id.inspect}): unrendered placeholder(s) #{leftover.uniq.inspect} — " \
+                             "subs is missing a marker this shape actually contains"
+        end
+
+        text
+      end
+
+      # Renders `shape_id` once per entry in `subs_list`, joined by `join_with`.
+      def render_each(shape_id, subs_list, join_with: "\n")
+        subs_list.map { |subs| render(shape_id, subs) }.join(join_with)
+      end
+
+      # Fills every nested slot of `outer_id` (`slots` maps field_id => rendered content),
+      # reindenting each to its marker's depth, then applies `outer_subs` last so a marker
+      # cannot match text that came from a slot.
+      def assemble(outer_id, outer_subs, slots:)
+        outer_text = raw(outer_id)
+
+        slots.each do |field_id, content|
+          slot = "<<TMPL_SLOT:#{field_id}>>"
+          slot_line = outer_text.match(/^([ \t]*)#{Regexp.escape(slot)}$/)
+          raise DriftError, "Exemplar.assemble(#{outer_id.inspect}): no nested slot for #{field_id.inspect} — " \
+                             "expected a `// TMPL:#{field_id} BEGIN/END` region nested inside `// TMPL:#{outer_id} BEGIN/END`" unless slot_line
+
+          # The nested marker's indentation in the exemplar sets the depth, not the caller.
+          indent = slot_line[1]
+          reindented = content.lines.map { |l| l.strip.empty? ? l : "#{indent}#{l}" }.join
+          outer_text = outer_text.sub(slot_line[0]) { reindented } # block form: see render
+        end
+
+        outer_subs.keys.sort_by { |k| -k.length }.each do |marker|
+          raise DriftError, "Exemplar.assemble(#{outer_id.inspect}): marker #{marker.inspect} not found in outer shape text" unless outer_text.include?(marker)
+
+          value = outer_subs[marker]
+          outer_text = outer_text.gsub(marker) { value }
+        end
+
+        if (leftover = outer_text.scan(LEFTOVER_PLACEHOLDER)).any?
+          raise DriftError, "Exemplar.assemble(#{outer_id.inspect}): unrendered placeholder(s) #{leftover.uniq.inspect}"
+        end
+
+        outer_text
+      end
+
+      # `assemble` for the single-slot case: renders the inner shape `field_id` once per
+      # entry in `field_subs_list` and splices the joined result into `outer_id`.
+      def compose(outer_id, outer_subs, field_id:, field_subs_list:, join_with: "\n")
+        assemble(outer_id, outer_subs, slots: { field_id => render_each(field_id, field_subs_list, join_with: join_with) })
+      end
+
+      def raw(shape_id)
+        shapes.fetch(shape_id) do
+          raise DriftError, "Exemplar: no shape #{shape_id.inspect} — " \
+                             "checked rust/src/exemplar/*.rs for `// TMPL:#{shape_id} BEGIN`"
+        end
+      end
+
+      # Test-only: repoints `dir` and clears the memoized shapes.
+      def reset!(dir: DEFAULT_DIR)
+        @dir = dir
+        @shapes = nil
+      end
+
+      private
+
+      def parse_all
+        result = {}
+        Dir.glob(File.join(dir, "*.rs")).sort.each { |path| parse_file(path, result) }
+        result
+      end
+
+      def parse_file(path, result)
+        stack = [] # each frame: [id, lines, begin_indent]
+        File.readlines(path).each do |line|
+          if (id = begin_marker(line))
+            stack.push([id, [], line[/^[ \t]*/]])
+          elsif (id = end_marker(line))
+            raise "#{path}: TMPL:#{id} END with no matching BEGIN (stack: #{stack.map(&:first).inspect})" if stack.empty? || stack.last[0] != id
+
+            _, lines, begin_indent = stack.pop
+            result[id] = dedent(lines)
+            # Keep the nested marker's indentation; it sets the depth of the spliced lines.
+            stack.last[1] << "#{begin_indent}<<TMPL_SLOT:#{id}>>\n" if stack.any?
+          elsif stack.any?
+            stack.last[1] << line
+          end
+        end
+        raise "#{path}: unclosed TMPL region(s): #{stack.map(&:first).inspect}" if stack.any?
+      end
+
+      def begin_marker(line)
+        line[%r{//\s*TMPL:(\S+)\s+BEGIN\s*$}, 1]
+      end
+
+      def end_marker(line)
+        line[%r{//\s*TMPL:(\S+)\s+END\s*$}, 1]
+      end
+
+      # Drops the leading whitespace shared by all non-blank lines, like `<<~`.
+      def dedent(lines)
+        indents = lines.reject { |l| l.strip.empty? }.map { |l| l[/^[ \t]*/].length }
+        margin = indents.min || 0
+        lines.map { |l| l.empty? ? l : l[margin..] }.join.rstrip
+      end
+    end
+  end
+end

data/rust/project/expr_emitter.rb

@@ -0,0 +1,72 @@
+module RustProjection
+  # Emits Rust `Expr` data-literal source from the `ast` tree of an IR rule row.
+  # Mirrors rust/codegen/src/expr_emitter.rs node for node; see `AstJson::OPS`.
+  # `include` arm below only ever sees a real field/string haystack.
+  module ExprEmitter
+    module_function
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def emit_ast(node)
+      case at(node, :op)
+      when "or"  then "Expr::Or(Box::new(#{emit_ast(at(node, :left))}), Box::new(#{emit_ast(at(node, :right))}))"
+      when "and" then "Expr::And(Box::new(#{emit_ast(at(node, :left))}), Box::new(#{emit_ast(at(node, :right))}))"
+      when "not" then "Expr::Not(Box::new(#{emit_ast(at(node, :expr))}))"
+      when "compare"
+        "Expr::Compare { op: #{emit_comparison(at(node, :cmp))}, left: Box::new(#{emit_ast(at(node, :left))}), right: Box::new(#{emit_ast(at(node, :right))}) }"
+      when "include"
+        "Expr::Include { haystack: Box::new(#{emit_ast(at(node, :haystack))}), needle: Box::new(#{emit_ast(at(node, :needle))}) }"
+      when "int"    then "Expr::Int(#{at(node, :value)})"
+      when "float"  then "Expr::Float(#{at(node, :value)}f64)"
+      when "str"    then "Expr::Str(#{at(node, :value).inspect}.to_string())"
+      when "bool"   then "Expr::Bool(#{at(node, :value)})"
+      when "nil"    then "Expr::Nil"
+      when "lookup" then "Expr::Lookup(#{at(node, :path).join('.').inspect})"
+      when "add"    then "Expr::Add(Box::new(#{emit_ast(at(node, :left))}), Box::new(#{emit_ast(at(node, :right))}))"
+      when "sign_test"
+        "Expr::SignTest { op: #{emit_comparison(at(node, :cmp))}, receiver: Box::new(#{emit_ast(at(node, :receiver))}) }"
+      when "empty"  then "Expr::Empty(Box::new(#{emit_ast(at(node, :receiver))}))"
+      when "to_s"   then "Expr::ToS(Box::new(#{emit_ast(at(node, :receiver))}))"
+      when "modulo"
+        "Expr::Modulo { receiver: Box::new(#{emit_ast(at(node, :receiver))}), divisor: Box::new(#{emit_ast(at(node, :divisor))}) }"
+      when "size"   then "Expr::Size(Box::new(#{emit_ast(at(node, :receiver))}))"
+      when "block_predicate"
+        "Expr::BlockPredicate { mode: crate::kernel::BlockMode::#{at(node, :mode).capitalize}, receiver: Box::new(#{emit_ast(at(node, :receiver))}), " \
+          "param: #{at(node, :param).inspect}, predicate: Box::new(#{emit_ast(at(node, :predicate))}) }"
+      when "find"
+        "Expr::Find { receiver: Box::new(#{emit_ast(at(node, :receiver))}), param: #{at(node, :param).inspect}, " \
+          "predicate: Box::new(#{emit_ast(at(node, :predicate))}), path: &[#{at(node, :path).map(&:inspect).join(', ')}] }"
+      when "array"
+        "Expr::Array(vec![#{at(node, :elements).map { |element| emit_ast(element) }.join(', ')}])"
+      when "matches_regex"
+        "Expr::MatchesRegex { receiver: Box::new(#{emit_ast(at(node, :receiver))}), pattern: #{at(node, :pattern).inspect}.to_string(), flags: #{at(node, :flags).inspect}.to_string() }"
+      when "presence"
+        "Expr::Presence { receiver: Box::new(#{emit_ast(at(node, :receiver))}), negated: #{at(node, :negated)} }"
+      when "assignment"
+        "Expr::Assignment { receiver: Box::new(#{emit_ast(at(node, :receiver))}), negated: #{at(node, :negated)} }"
+      when "split"
+        "Expr::Split { receiver: Box::new(#{emit_ast(at(node, :receiver))}), separator: #{at(node, :separator).inspect}.to_string() }"
+      when "starts_with"
+        "Expr::StartsWith { receiver: Box::new(#{emit_ast(at(node, :receiver))}), substring: #{at(node, :substring).inspect}.to_string() }"
+      when "ends_with"
+        "Expr::EndsWith { receiver: Box::new(#{emit_ast(at(node, :receiver))}), substring: #{at(node, :substring).inspect}.to_string() }"
+      when "first" then "Expr::First(Box::new(#{emit_ast(at(node, :receiver))}))"
+      when "last"  then "Expr::Last(Box::new(#{emit_ast(at(node, :receiver))}))"
+      else
+        # An op with no arm above means `AstJson::OPS` grew and this file did not.
+        raise "unhandled ast op #{at(node, :op).inspect} — no Rust rendering exists for it in this generator (rust/project/expr_emitter.rb#emit_ast)"
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+    # Fully qualified: the grammar's own "Comparison" closed set would collide with the
+    # kernel struct of the same name in a file that needs both.
+    def emit_comparison(cmp)
+      "crate::kernel::Comparison { less_than: #{at(cmp, :less_than)}, equal: #{at(cmp, :equal)}, negated: #{at(cmp, :negated)} }"
+    end
+
+    # Reads a key from a symbol-keyed (round-tripped) or string-keyed (`AstJson`) node.
+    def at(node, key)
+      node.key?(key) ? node[key] : node.fetch(key.to_s)
+    end
+  end
+end

data/rust/project/fielded.rb

@@ -0,0 +1,141 @@
+module RustProjection
+  module Projector
+    module_function
+
+    # One `Fielded` match arm per attribute, shared by value objects, args structs and
+    # (via emit_fielded_record) aggregate records.
+    # `extra_arms:` are raw `"key" => ...,` lines appended verbatim, e.g. an entity's lifecycle
+    # field. Arms render from the leaf shapes in rust/src/exemplar/fielded.rs with a fixed
+    # 12-space prefix, using plain `render` because the leaves are shared across outer shapes.
+    def emit_fielded_flat(struct_name, attributes, value_objects_by_name, extra_arms: [], entity_names: [])
+      arms = attributes.filter_map do |attr|
+        key   = rust_field(attr[:name])
+        ident = rust_ident_field(attr[:name])
+        scalar = effective_scalar_type(attr[:type])
+        if attr[:list] && attr[:optional]
+          Exemplar.render("fielded_arm_list_optional", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        elsif attr[:list]
+          Exemplar.render("fielded_arm_list", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        elsif attr[:optional] && scalar
+          Exemplar.render(
+            "fielded_arm_optional_scalar",
+            '"tmpl_field"' => key.inspect,
+            "tmpl_ident" => ident,
+            "tmpl_value_expr_placeholder(v)" => scalar_to_value(scalar, "v")
+          )
+        elsif attr[:optional]
+          nested = value_objects_by_name[attr[:type]]
+          next nil unless nested && fielded_capable_nested?(nested)
+
+          Exemplar.render("fielded_arm_optional_nested", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        elsif scalar
+          Exemplar.render(
+            "fielded_arm_scalar",
+            '"tmpl_field"' => key.inspect,
+            "tmpl_value_expr_placeholder(&self.tmpl_ident)" => scalar_to_value(scalar, "self.#{ident}")
+          )
+        else
+          nested = value_objects_by_name[attr[:type]]
+          next nil unless nested && fielded_capable_nested?(nested)
+
+          Exemplar.render("fielded_arm_nested", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        end
+      end
+      arms = arms.map { |a| "            #{a}" }
+      arms += extra_arms
+
+      # The trailing "\n" keeps the blank-line count callers expect; render's dedent rstrips.
+      "#{Exemplar.render(
+        'fielded_flat',
+        'TmplFlatType' => struct_name,
+        '"tmpl_arms_placeholder" => tmpl_arms_block(),' => arms.join("\n"),
+        # `entity_names`: a list of entities is enumerated the same way the record does.
+        '"tmpl_items_placeholder" => tmpl_items_block(),' => items_arms(attributes, value_objects_by_name, entity_names, optional: ->(attr) { attr[:optional] }).join("\n"),
+        "tmpl_as_scalar_placeholder()" => as_scalar_expr(attributes),
+        # Import only what the arms use, so a struct with no arms leaves no unused `use`.
+        'use crate::kernel::Field;' => (arms.any? { |arm| arm.include?('Field') } ? 'use crate::kernel::Field;' : ''),
+        'use crate::kernel::Value;' => (arms.any? { |arm| arm.include?('Value') } ? 'use crate::kernel::Value;' : '')
+      )}\n"
+    end
+
+    # `Fielded::items`: one arm per list attribute whose element is a scalar or a fielded-capable
+    # nested type or entity. `optional` says whether the list is `Option`-wrapped.
+    def items_arms(attributes, value_objects_by_name, entity_names, optional:)
+      attributes.filter_map do |attr|
+        next nil unless attr[:list]
+
+        key    = rust_field(attr[:name])
+        ident  = rust_ident_field(attr[:name])
+        scalar = effective_scalar_type(attr[:type])
+        nested = value_objects_by_name[attr[:type]]
+        fielded_element = scalar || (nested && fielded_capable_nested?(nested)) || entity_names.include?(attr[:type])
+        next nil unless fielded_element
+
+        shape = "fielded_items_arm_list_#{optional.call(attr) ? 'optional_' : ''}#{scalar ? 'scalar' : 'nested'}"
+        subs = { '"tmpl_field"' => key.inspect, "tmpl_ident" => ident }
+        subs["tmpl_value_expr_placeholder(v)"] = scalar_to_value(scalar, "v") if scalar
+        "            #{Exemplar.render(shape, subs)}"
+      end
+    end
+
+    # Record variant of emit_fielded_flat: non-list attributes are `Option`-wrapped, so `None`
+    # reads as `Value::Nil`. Adds lifecycle and corrects-flag arms.
+    def emit_fielded_record(aggregate, value_objects_by_name)
+      name = rust_ident(aggregate[:name])
+      arms = aggregate[:attributes].filter_map do |attr|
+        key   = rust_field(attr[:name])
+        ident = rust_ident_field(attr[:name])
+        scalar = effective_scalar_type(attr[:type])
+        if attr[:list] && list_attr_creation_optional?(aggregate, attr[:name], value_objects_by_name)
+          Exemplar.render("fielded_arm_list_optional", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        elsif attr[:list]
+          Exemplar.render("fielded_arm_list", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        elsif scalar
+          Exemplar.render(
+            "fielded_arm_optional_scalar",
+            '"tmpl_field"' => key.inspect,
+            "tmpl_ident" => ident,
+            "tmpl_value_expr_placeholder(v)" => scalar_to_value(scalar, "v")
+          )
+        else
+          nested = value_objects_by_name[attr[:type]]
+          next nil unless nested && fielded_capable_nested?(nested)
+
+          Exemplar.render("fielded_arm_optional_nested", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+        end
+      end
+      if aggregate[:lifecycle]
+        key   = rust_field(aggregate[:lifecycle][:field])
+        ident = rust_ident_field(aggregate[:lifecycle][:field])
+        arms << Exemplar.render("fielded_lifecycle_arm", '"tmpl_field"' => key.inspect, "tmpl_ident" => ident)
+      end
+      correctable_event_names(aggregate).each do |ev|
+        ident = corrects_flag_field(ev)
+        arms << Exemplar.render("fielded_corrects_flag_arm", '"tmpl_field"' => ident.inspect, "tmpl_ident" => ident)
+      end
+      arms = arms.map { |a| "            #{a}" }
+
+      # Trailing "\n": see emit_fielded_flat.
+      entity_names = (aggregate[:entities] || []).map { |e| e[:name] }
+      "#{Exemplar.render(
+        'fielded_record',
+        'TmplRecordType' => name,
+        '"tmpl_arms_placeholder" => tmpl_arms_block(),' => arms.join("\n"),
+        '"tmpl_items_placeholder" => tmpl_items_block(),' => items_arms(
+          aggregate[:attributes], value_objects_by_name, entity_names,
+          optional: ->(attr) { list_attr_creation_optional?(aggregate, attr[:name], value_objects_by_name) }
+        ).join("\n"),
+        "tmpl_as_scalar_placeholder()" => as_scalar_expr(aggregate[:attributes])
+      )}\n"
+    end
+
+    # `Resolver#unwrap_scalar`: a struct with exactly one scalar attribute reads as that
+    # attribute's value whatever its name; anything else answers `None`.
+    def as_scalar_expr(attributes)
+      sole = attributes.size == 1 && !attributes.first[:list] ? attributes.first : nil
+      return "None" unless sole && effective_scalar_type(sole[:type])
+
+      "match self.field(#{rust_field(sole[:name]).inspect}) { Some(crate::kernel::Field::Value(v)) => Some(v), _ => None }"
+    end
+  end
+end