hecks 2.8.0 → 3.0.0

data/rust/project/naming.rb

@@ -0,0 +1,205 @@
+require "hecks/vocabulary"
+require "hecks/bluebook/model_check"
+
+module RustProjection
+  # Domain-to-Rust codegen support: type mapping, reserved-name checks, and
+  # literal escaping shared by the Rust code generator.
+  module Projector
+    module_function
+
+    # Ruby has no single Boolean class, so a boolean attribute is declared
+    # TrueClass or FalseClass; both keys must map here.
+    SCALAR = { "String" => "String", "Integer" => "i64", "Float" => "f64",
+                   "TrueClass" => "bool", "FalseClass" => "bool" }.freeze
+    SCALAR_KIND = { "String" => :string, "Integer" => :int, "Float" => :float,
+                     "TrueClass" => :bool, "FalseClass" => :bool }.freeze
+
+    # A `Reference<X>` is represented as a plain `String` at the
+    # struct-field level — it's a bare id, not a nested object (see
+    # aggregates-and-value-objects.md's "Pointing at another aggregate").
+    def reference_type?(type_name) = type_name.to_s.start_with?("Reference<")
+
+    # Returns nil when `type_name` isn't a `Reference<...>` at all.
+    def reference_target(type_name)
+      match = type_name.to_s.match(/\AReference<(.+)>\z/)
+      match && match[1]
+    end
+
+    def effective_scalar_type(type_name)
+      return "String" if reference_type?(type_name)
+
+      type_name if SCALAR.key?(type_name)
+    end
+
+    def rust_type(type_name, list:)
+      scalar = effective_scalar_type(type_name)
+      inner = scalar ? SCALAR.fetch(scalar) : rust_ident(type_name)
+      list ? "Vec<#{inner}>" : inner
+    end
+
+    def rust_ident(name) = name.to_s.gsub(/[^A-Za-z0-9]/, "")
+    def dispatch_fn_name(cmd) = cmd.gsub(/(?<=.)([A-Z])/, '_\1').downcase
+
+    # A field name plays two different roles in generated code: a
+    # string-literal match-arm/payload key (plain text) and a struct-field
+    # identifier (must be raw-escaped when it collides with a Rust
+    # keyword) — kept as separate functions so escaping only ever applies
+    # to the identifier role.
+    #
+    # Declared once as the `RustReservedWord` vocabulary;
+    # `hecks project_reserved_names` projects the same table into
+    # hecks-codegen's `reserved_names.rs`.
+    RUST_KEYWORDS = Hecks::Vocabulary.fetch("RustReservedWord")
+
+    # A domain's own name doubles as a directory, a bare Rust module
+    # identifier (module names get no raw-identifier escape hatch), and a
+    # Cargo `[features]` key. This list rules out the third: every key
+    # already used elsewhere in `rust/Cargo.toml` outside `[features]`,
+    # plus `default`, which Cargo itself reserves for the auto-enabled
+    # feature set.
+    #
+    # Declared once as the `CargoReservedName` vocabulary.
+    CARGO_RESERVED_DOMAIN_NAMES = Hecks::Vocabulary.fetch("CargoReservedName")
+
+    # Checks identifier shape locally; delegates the reserved-word half to
+    # `ModelCheck.rust_reserved_name_findings`, the one shared check.
+    def valid_domain_mod_name?(name)
+      str = name.to_s
+      str.match?(/\A[a-z_][a-z0-9_]*\z/) &&
+        Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(domain_name: str).empty?
+    end
+
+    # Identifier-shape check only (a PascalCase name always passes); whether
+    # the downcased name is a Rust keyword is `reserved_name_refusal`'s job,
+    # below. An aggregate name never doubles as a Cargo feature key.
+    def legal_aggregate_mod_identifier?(name)
+      name.to_s.downcase.match?(/\A[a-z_][a-z0-9_]*\z/)
+    end
+
+    # Returns nil when every name is usable, else the message
+    # `DomainGenerator.call` raises. Must return the identical string as
+    # hecks-codegen's `naming::reserved_name_refusal`
+    # (rust/codegen/src/naming.rs) for the same input.
+    def reserved_name_refusal(source_label, mod_name, aggregate_names)
+      names = aggregate_names.map(&:to_s)
+      reserved = Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(aggregate_names: names, rust_target: true)
+                                            .map(&:subject)
+      refused = names.select { |name| reserved.include?(name) || !legal_aggregate_mod_identifier?(name) }
+      if refused.any?
+        return "#{source_label}: aggregate name(s) #{refused.map(&:inspect).join(', ')} can't be used as-is — " \
+               "downcased, each becomes a bare Rust module identifier (`pub mod #{refused.first.downcase};`) and a " \
+               "generated file name, and at least one is not a plain identifier or is a Rust keyword " \
+               "(RustReservedWord). Module names get no raw-identifier (r#name) escape hatch — rename the aggregate."
+      end
+      return nil if valid_domain_mod_name?(mod_name)
+
+      "#{source_label}: domain module name #{mod_name.to_s.inspect} can't be used as-is — it has to double as a Rust " \
+        "module identifier and a Cargo feature name, and this one is either not a plain lowercase identifier, is a " \
+        "Rust keyword (RustReservedWord), or is a reserved Cargo.toml key (CargoReservedName). Rename the domain."
+    end
+
+    # `r#crate`/`r#self`/`r#super`/`r#Self` are not valid raw-identifier
+    # syntax in Rust at all, so these four can't be escaped the way
+    # `rust_ident_field` escapes every other `RUST_KEYWORDS` entry.
+    RUST_UNESCAPABLE_KEYWORDS = %w[crate self super Self].freeze
+
+    def rust_field(name) = name.to_s
+
+    def rust_ident_field(name)
+      field = rust_field(name)
+      if RUST_UNESCAPABLE_KEYWORDS.include?(field)
+        raise "rust_ident_field(#{field.inspect}): #{field.inspect} is a Rust keyword that cannot be rescued by a raw " \
+              "identifier (r##{field} is not valid Rust syntax for crate/self/super/Self in any position) — rename " \
+              "the attribute/field in the bluebook."
+      end
+
+      RUST_KEYWORDS.include?(field) ? "r##{field}" : field
+    end
+
+    # Splits on any run of non-alphanumeric characters, since closed-set
+    # members can be glob patterns like `*.port`. `Self`, the one
+    # capitalized Rust keyword, is renamed by original casing (SelfType/
+    # SelfValue) so two different values can't collide into it.
+    def closed_set_variant(row)
+      _, value = row.first
+      variant = value.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map(&:capitalize).join
+      return variant unless variant == "Self"
+
+      value.to_s.start_with?("S") ? "SelfType" : "SelfValue"
+    end
+
+    def screaming_snake(name)
+      name.to_s.gsub(/([a-z0-9])([A-Z])/, '\1_\2').upcase
+    end
+
+    def scalar_to_value(type_name, rust_expr)
+      case type_name
+      when "String"  then "Value::Str(#{rust_expr}.clone())"
+      when "Integer" then "Value::Int(#{rust_expr})"
+      when "Float"   then "Value::Float(#{rust_expr})"
+      when "TrueClass", "FalseClass" then "Value::Bool(#{rust_expr})"
+      end
+    end
+
+    # True when `vo` can emit `Field::Nested(&self.x)`: any ordinary value
+    # object, or a single-field closed set (which has its own `Fielded`
+    # impl). False for a multi-field closed set, which has no `Fielded`
+    # impl to emit against.
+    def fielded_capable_nested?(vo)
+      !vo[:closed_set] || vo[:attributes].size == 1
+    end
+
+    # `Fielded` impl for a single-field closed set: answers "value" as its
+    # one field, matching the same arms the enum's own generated `to_json`
+    # already builds (reproduced here rather than shared, so it never
+    # touches the enum's existing to_json/from_json generation).
+    def emit_closed_set_fielded_impl(vo)
+      name = rust_ident(vo[:name])
+      arms = vo[:members].map do |row|
+        _, raw = row.first
+        "#{name}::#{closed_set_variant(row)} => #{rust_string_literal(raw.to_s)}.to_string(),"
+      end.join(" ")
+
+      "impl crate::kernel::Fielded for #{name} {\n    " \
+        "fn field(&self, name: &str) -> Option<crate::kernel::Field<'_>> {\n        " \
+        "use crate::kernel::{Field, Value};\n        " \
+        "match name {\n            " \
+        "\"value\" => Some(Field::Value(Value::Str(match self { #{arms} }))),\n            " \
+        "_ => None,\n        " \
+        "}\n    " \
+        "}\n    " \
+        "fn as_scalar(&self) -> Option<crate::kernel::Value> {\n        " \
+        "match self.field(\"value\") { Some(crate::kernel::Field::Value(v)) => Some(v), _ => None }\n    " \
+        "}\n" \
+        "}"
+    end
+
+    def literal_rhs(literal)
+      case literal
+      when String then "#{rust_string_literal(literal)}.to_string()"
+      when Integer, Float, true, false then literal.to_s
+      else raise "unsupported literal mutation source #{literal.inspect} — not one of String/Integer/Float/Boolean"
+      end
+    end
+
+    # Ruby's String#inspect escapes for Ruby's own read-back (e.g. a
+    # brace-less `\uXXXX`), which isn't valid Rust syntax. This escapes
+    # only what Rust's string-literal grammar needs: backslash,
+    # double-quote, and control characters.
+    def rust_string_literal(str)
+      escaped = str.to_s.each_char.map do |ch|
+        case ch
+        when "\\" then "\\\\"
+        when "\"" then "\\\""
+        when "\n" then "\\n"
+        when "\r" then "\\r"
+        when "\t" then "\\t"
+        else
+          cp = ch.ord
+          cp < 0x20 || cp == 0x7F ? format("\\u{%x}", cp) : ch
+        end
+      end.join
+      "\"#{escaped}\""
+    end
+  end
+end

data/rust/project/ports.rb

@@ -0,0 +1,65 @@
+require_relative "skip_reason"
+
+module RustProjection
+  module Projector
+    module_function
+
+    # A port operation has no givens or mutations, so the only ungenerable shape left is an
+    # attribute type with no resolved Rust type.
+    def port_operation_skip_reason(operation, _owner_name, value_objects_by_name)
+      unresolved = operation[:attributes].reject do |attr|
+        next true if attr[:list] # a list attribute's element type is checked below
+        next true if reference_type?(attr[:type])
+        next true if SCALAR.key?(attr[:type])
+
+        value_objects_by_name.key?(attr[:type])
+      end
+      return skip("port_attribute_type", "attribute type(s) #{unresolved.map { |a| a[:type] }.uniq.join(', ')} not generated yet " \
+                                         "(a value object this aggregate's own attributes never resolved a Rust type for)") if unresolved.any?
+
+      nil
+    end
+
+    # Emits the args struct and a pure dispatch function that builds the events the operation
+    # `emits`, addressed by `receiver_id`. Payloads are `Json::Null` placeholders; the registry's
+    # `stamp_payload` replaces them. A self-reference to the owner is left out of the args.
+    def emit_port_operation(operation, port_name, owner_name, domain_name, value_objects_by_name, aggregates_by_name)
+      args_struct = "#{rust_ident(port_name)}#{rust_ident(operation[:name])}Args"
+      qualified   = "#{domain_name}::#{owner_name}"
+      fact_attrs  = operation[:attributes].reject { |attr| reference_target(attr[:type]) == owner_name }
+
+      struct_lines = ["pub struct #{args_struct} {"]
+      fact_attrs.each do |attr|
+        type = rust_type(attr[:type], list: attr[:list])
+        type = "Option<#{type}>" if attr[:optional]
+        struct_lines << "    #{Exemplar.render('struct_field', 'TmplFieldType' => type, 'tmpl_field' => rust_ident_field(attr[:name]))}"
+      end
+      struct_lines << "}"
+
+      invariant_checks = invariant_checks_for(operation, aggregates_by_name, value_objects_by_name)
+      fn = "#{port_name.downcase}_#{dispatch_fn_name(rust_ident(operation[:name]))}"
+
+      events = operation[:emits].map do |event_name|
+        "        crate::kernel::Event { name: #{event_name.inspect}.to_string(), aggregate: #{qualified.inspect}.to_string(), " \
+          "id: receiver_id.to_string(), payload: crate::kernel::Json::Null, occurred_at: None, correlation: None },"
+      end
+
+      dispatch_fn = <<~RUST.rstrip
+        pub fn dispatch_operation_#{fn}(receiver_id: &str, args: #{args_struct}) -> Result<Vec<crate::kernel::Event>, crate::kernel::Refusal> {
+        #{invariant_checks.join("\n")}
+            Ok(vec![
+        #{events.join("\n")}
+            ])
+        }
+      RUST
+
+      [
+        "#[derive(Debug, Clone)]\n#{struct_lines.join("\n")}",
+        emit_to_json_flat(args_struct, fact_attrs, value_objects_by_name),
+        emit_from_json_flat(args_struct, fact_attrs, value_objects_by_name, command_name: "#{port_name}.#{operation[:name]}",
+                            interleave_checks: true, aggregates_by_name: aggregates_by_name),
+        dispatch_fn,
+      ].join("\n\n")
+    end
+  end
+end