acts_as_calculator_editor 0.1.0

data/lib/acts_as_calculator_editor/cast_variable_rows.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # Form rows in, the `variables:` list `PublishFormulaVersion` takes out.
+  #
+  # Two things here are not cosmetic. First, an HTML form can post repeated fields either as
+  # an array (`version[variables][][name]`) or as an index-keyed hash
+  # (`version[variables][0][name]`); the second is what `fields_for` emits and the only one
+  # that survives a row whose checkbox is the sole differing field, so both are accepted.
+  #
+  # Second, `required`. `CastVariableAttributes` treats anything that is not literally
+  # `false` as true, and an unchecked Rails checkbox posts the *string* `"0"` — which would
+  # sail through as `required: true` and turn an optional variable into one that raises
+  # `MissingVariableError` at calculation time. The string has to become a real boolean
+  # before it gets anywhere near the core gem.
+  class CastVariableRows
+    FALSEY = ["0", "false", "off", ""].freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(rows)
+      @rows = rows
+    end
+
+    def call
+      normalized_rows.filter_map { |row| variable(row) }
+    end
+
+    private
+
+    attr_reader :rows
+
+    def normalized_rows
+      given = plain(rows)
+
+      case given
+      when Array then given.map { |row| plain(row) }
+      when Hash then given.sort_by { |index, _| index.to_s.rjust(9, "0") }.map { |(_, row)| plain(row) }
+      else []
+      end
+    end
+
+    def variable(row)
+      return nil unless row.is_a?(Hash)
+
+      name = row["name"].to_s.strip
+      return nil if name.empty?
+
+      { "name" => name,
+        "source_type" => row["source_type"].presence || "context",
+        "source_config" => source_config(row),
+        "required" => required?(row) }
+    end
+
+    # Absent means the core gem's default (true); present and falsey means the operator
+    # unchecked the box, which is the case a bare `!= false` comparison gets wrong.
+    def required?(row)
+      return true unless row.key?("required")
+
+      !FALSEY.include?(row["required"].to_s.strip.downcase)
+    end
+
+    # A `source_config` is arbitrary JSON, so the minimal form offers one textarea per row
+    # rather than a field per source type. Nested form fields that post a real hash work
+    # too — the Frontend Engineer's typed inputs will use those.
+    def source_config(row)
+      raw = row["source_config"]
+      return plain(raw) if raw.is_a?(Hash) || raw.respond_to?(:to_unsafe_h)
+      return {} if raw.to_s.strip.empty?
+
+      parsed = JSON.parse(raw.to_s)
+      raise ActsAsCalculator::Error, config_error(row, raw) unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError
+      raise ActsAsCalculator::Error, config_error(row, raw)
+    end
+
+    def config_error(row, raw)
+      "variable #{row["name"].to_s.inspect} has an invalid source_config — " \
+        "expected a JSON object, got #{raw.to_s.inspect}"
+    end
+
+    def plain(value)
+      value.respond_to?(:to_unsafe_h) ? value.to_unsafe_h.to_h : value
+    end
+  end
+end

data/lib/acts_as_calculator_editor/delete_lookup_table.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # Nothing in the schema stops a lookup table from being deleted out from under a formula
+  # that reads it: a variable names its table by key, not by foreign key, so there is no
+  # constraint to lean on and `MissingLookupTableError` would only surface at the next
+  # calculation.
+  #
+  # `ImportLookupTable` refuses to *rewrite* brackets an active or retired version resolved
+  # to, for the reason that rewriting them retroactively changes what an audited calculation
+  # was measured against. Deleting the table is the same act with a worse ending, so it gets
+  # the same guard and the same error class — reusing `FindLookupTableReferences` rather
+  # than approximating it, since which table a formula resolves to depends on owner
+  # shadowing and cannot be answered by matching keys.
+  class DeleteLookupTable
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(lookup_table:)
+      @lookup_table = lookup_table
+    end
+
+    def call
+      raise ActsAsCalculator::LookupTableInUseError, in_use_message unless references.empty?
+
+      lookup_table.destroy!
+      lookup_table
+    end
+
+    private
+
+    attr_reader :lookup_table
+
+    # Named here rather than in a constant: `FormulaVersion` is an autoloaded model, and
+    # this file is required while the engine is still booting.
+    def audited_statuses
+      [ActsAsCalculator::FormulaVersion::ACTIVE, ActsAsCalculator::FormulaVersion::RETIRED]
+    end
+
+    def references
+      @references ||= ActsAsCalculator::FindLookupTableReferences.(lookup_table:, statuses: audited_statuses)
+    end
+
+    def in_use_message
+      used_by = references.map { |version| "#{version.formula.key}##{version.version_number} (#{version.status})" }
+
+      "lookup table #{lookup_table.key.inspect} in scope #{lookup_table.scope.inspect} still backs " \
+        "#{used_by.join(", ")}; deleting it would leave those versions unable to calculate at all, " \
+        "and would remove the brackets their past runs were audited against. Retire the formula " \
+        "versions that read it first."
+    end
+  end
+end

data/lib/acts_as_calculator_editor/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module ActsAsCalculatorEditor
+  class Engine < ::Rails::Engine
+    isolate_namespace ActsAsCalculatorEditor
+
+    # This engine adds no tables of its own. Every row it reads and writes belongs to
+    # `acts_as_calculator`, whose install generator the host runs (docs/core-gem-contract.md
+    # §2) — so there is no migration path to append here, deliberately.
+
+    config.generators do |generate|
+      generate.test_framework :rspec
+      generate.helper false
+      generate.assets false
+    end
+
+    # Merge this engine's pins into the host's importmap. Guarded twice over: a host is free
+    # to use esbuild/webpack instead of importmap-rails, in which case `config.importmap`
+    # does not exist and our Stimulus controllers are the host's problem to bundle.
+    #
+    # `before: "importmap"` matters — importmap-rails reads `config.importmap.paths` in its
+    # own initializer, so appending afterwards is a no-op that fails silently.
+    initializer "acts_as_calculator_editor.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+  end
+end

data/lib/acts_as_calculator_editor/export_formulas.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # The `formulas` section of an import document — which is *not* the shape
+  # `SerializeFormula` emits (docs/core-gem-contract.md §4.2). Four differences, each of
+  # which would silently produce a file that does not round-trip:
+  #
+  # - one flat entry per version, repeating `key`/`scope`/`owner`, rather than a formula
+  #   with a nested `versions` array;
+  # - `owner` as a `{type, id}` object, omitted entirely when nil;
+  # - no `id`, `formula_id`, `version_number`, `created_at` or `updated_at` — none of them
+  #   are import keys;
+  # - `required` written out as a real boolean, because the import default is "anything not
+  #   literally `false`" and omitting it is therefore not the same as round-tripping it.
+  #
+  # Version order is load-bearing, not cosmetic. `SupersedeFormulaVersions` applies entries
+  # in file order, so a version that takes over the tail of a range has to land after the
+  # one giving it up; an out-of-order export re-imports straight into
+  # `PartialSupersedeError`.
+  class ExportFormulas
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key: nil, scope: nil, full_history: false)
+      @key = key
+      @scope = scope
+      @full_history = full_history
+    end
+
+    def call
+      formulas.flat_map { |formula| versions(formula).map { |version| entry(formula, version) } }
+    end
+
+    private
+
+    attr_reader :key, :scope, :full_history
+
+    def formulas
+      relation = ActsAsCalculator::Formula.includes(versions: :variables).order(:scope, :key, :id)
+      relation = relation.where(key:) if key.present?
+      relation = relation.where(scope:) if scope.present?
+      relation
+    end
+
+    # A formula with no exportable version contributes nothing: the import format has no way
+    # to express an identity row with no maths attached, so there is nothing to write.
+    def versions(formula)
+      selected = formula.versions
+      selected = selected.select(&:active?) unless full_history
+
+      selected.sort_by { |version| [version.effective_from, version.version_number] }
+    end
+
+    def entry(formula, version)
+      { "key" => formula.key, "scope" => formula.scope }
+        .merge(owner(formula))
+        .merge("expression" => version.expression,
+               "effective_from" => version.effective_from.iso8601,
+               "effective_to" => version.effective_to&.iso8601,
+               "status" => version.status)
+        .merge(change_note(version))
+        .merge("variables" => variables(version))
+    end
+
+    def owner(formula)
+      reference = ExportOwnerReference.(record: formula)
+      reference ? { "owner" => reference } : {}
+    end
+
+    def change_note(version)
+      version.change_note.presence ? { "change_note" => version.change_note } : {}
+    end
+
+    # Sorted by name so two exports of the same data diff cleanly; the import compares
+    # variable sets order-independently, so the order carries no meaning of its own.
+    def variables(version)
+      version.variables.sort_by(&:name).map { |variable| declaration(variable) }
+    end
+
+    def declaration(variable)
+      config = ActsAsCalculator::CastJsonSafe.(variable.source_config || {})
+      declared = { "name" => variable.name, "source_type" => variable.source_type }
+      declared["source_config"] = config if config.present?
+
+      declared.merge("required" => variable.required?)
+    end
+  end
+end

data/lib/acts_as_calculator_editor/export_lookup_tables.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # The `lookup_tables` section of an import document. The core gem has no
+  # `SerializeLookupTable` to borrow (docs/core-gem-contract.md §4.4), so the shape is built
+  # from the migration's own columns.
+  class ExportLookupTables
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key: nil, scope: nil)
+      @key = key
+      @scope = scope
+    end
+
+    def call
+      tables.map { |table| entry(table) }
+    end
+
+    private
+
+    attr_reader :key, :scope
+
+    def tables
+      relation = ActsAsCalculator::LookupTable.includes(:entries).order(:scope, :key, :id)
+      relation = relation.where(key:) if key.present?
+      relation = relation.where(scope:) if scope.present?
+      relation
+    end
+
+    def entry(table)
+      { "key" => table.key, "scope" => table.scope }
+        .merge(owner(table))
+        .merge("entries" => table.entries.sort_by { |row| [row.position, row.id] }.map { |row| bracket(row) })
+    end
+
+    def owner(table)
+      reference = ExportOwnerReference.(record: table)
+      reference ? { "owner" => reference } : {}
+    end
+
+    def bracket(row)
+      { "from" => CastExportDecimal.(row.from),
+        "to" => CastExportDecimal.(row.to),
+        "value" => CastExportDecimal.(row.value) }
+    end
+  end
+end

data/lib/acts_as_calculator_editor/export_owner_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # `{"type": "Company", "id": 7}`, or nothing at all.
+  #
+  # Nothing at all is load-bearing: `ResolveImportOwner` raises `ImportError` on `{}` and on
+  # `{"type": null}`, so an omitted key is the only way an import document can say "the
+  # global row" (docs/core-gem-contract.md §2.7). The columns are read directly rather than
+  # through the association so an export does not fail on a row whose owner has since been
+  # deleted.
+  class ExportOwnerReference
+    def self.call(record:)
+      return nil if record.owner_type.nil?
+
+      { "type" => record.owner_type, "id" => record.owner_id }
+    end
+  end
+end

data/lib/acts_as_calculator_editor/export_templates.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # The `templates` section — current versions only, and that is not a default anyone should
+  # switch off (docs/core-gem-contract.md §4.2, rule 2).
+  #
+  # `ImportTemplate` publishes a new version for every entry it sees, in file order. Export
+  # the whole history and a re-import replays it in version order, ending with the highest
+  # `version_number` live. After a `PromoteTemplate` rollback the current version is *not*
+  # the highest-numbered one, so that replay quietly puts the rolled-back body back in
+  # production. Exporting what is live is both correct and what the import format means.
+  #
+  # This is why `full_history` is a formula-versions switch and not a document-wide one:
+  # there is no version history to ask for here that could be re-imported truthfully.
+  class ExportTemplates
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key: nil, scope: nil)
+      @key = key
+      @scope = scope
+    end
+
+    def call
+      templates.map { |template| entry(template) }
+    end
+
+    private
+
+    attr_reader :key, :scope
+
+    def templates
+      relation = ActsAsCalculator::Template.current.order(:scope, :key, :id)
+      relation = relation.where(key:) if key.present?
+      relation = relation.where(scope:) if scope.present?
+      relation
+    end
+
+    def entry(template)
+      { "key" => template.key, "scope" => template.scope }
+        .merge(owner(template))
+        .merge("format" => template.format, "body" => template.body)
+    end
+
+    def owner(template)
+      reference = ExportOwnerReference.(record: template)
+      reference ? { "owner" => reference } : {}
+    end
+  end
+end

data/lib/acts_as_calculator_editor/publish_lookup_table.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # The core gem ships no controller for lookup tables and no Decree for authoring one
+  # outside an import document (docs/core-gem-contract.md §4.4). This builds the single
+  # `lookup_tables` entry that document would have carried and hands it to
+  # `ActsAsCalculator::ImportLookupTable`.
+  #
+  # Going through that Decree rather than writing `table.entries.create!` here is the whole
+  # point: it carries `guard_against_rewriting_audited_brackets`, which refuses to change
+  # entries an active or retired formula version resolves to. That guard is what stops a
+  # bracket edit from retroactively changing what an audited calculation was measured
+  # against, and it exists in exactly one place.
+  #
+  # The transaction is ours because `ImportLookupTable` deletes the old entries before
+  # writing the new ones and leaves the savepoint to its caller — normally
+  # `ImportDefinitions`. Without one, an entry the model rejects would leave the table
+  # emptied.
+  class PublishLookupTable
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key:, scope: nil, owner: nil, entries: [])
+      @key = key.to_s.strip
+      @scope = (scope.presence || ActsAsCalculator::DEFAULT_SCOPE).to_s.strip
+      @owner = owner
+      @entries = entries
+    end
+
+    def call
+      ActsAsCalculator::Record.transaction(requires_new: true) do
+        ActsAsCalculator::ImportLookupTable.(attributes:)
+      end
+
+      ActsAsCalculator::LookupTable.owned_by(owner).find_by!(key:, scope:)
+    end
+
+    private
+
+    attr_reader :key, :scope, :owner, :entries
+
+    # `owner` is omitted entirely when nil: `ResolveImportOwner` raises on `{}` and on
+    # `{"type" => nil}`, so an absent key is the only way to say "the global row"
+    # (contract §2.7).
+    def attributes
+      document = { "key" => key, "scope" => scope, "entries" => entries }
+      document["owner"] = { "type" => owner.class.polymorphic_name, "id" => owner.id } if owner
+
+      document
+    end
+  end
+end

data/lib/acts_as_calculator_editor/render_template_preview.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # Preview a template body that has never been saved.
+  #
+  # The core gem's HTTP preview needs a persisted record because its controller does
+  # `Template.find(params[:id])` — but `RenderTemplate` itself does not: it reads only
+  # `#body` and short-circuits to whatever `template:` it was handed
+  # (docs/core-gem-contract.md §4.3). So an unsaved `Template.new` is enough, which beats
+  # "save an early version first" — no throwaway version rows, no partial state — while
+  # still exercising the real Liquid sandbox with all its resource limits rather than a
+  # second copy of it.
+  #
+  # Failures come back as `ActsAsCalculator::TemplateRenderError` (with a line number, since
+  # `RenderLiquid` parses in strict mode) or `UnsafeAssignError` for a context value Liquid
+  # will not accept. Both are 422s the preview pane shows; neither is a 500.
+  class RenderTemplatePreview
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(body:, format: ActsAsCalculator::Template::HTML, context: {}, result: nil)
+      @body = body.to_s
+      @format = format.presence || ActsAsCalculator::Template::HTML
+      @context = cast_context(context)
+      @result = result || BuildSampleResult.()
+    end
+
+    def call
+      ActsAsCalculator::RenderTemplate.(template:, result:, context:)
+    end
+
+    private
+
+    attr_reader :body, :format, :context, :result
+
+    def template
+      ActsAsCalculator::Template.new(body:, format:)
+    end
+
+    # The minimal preview form posts context as one JSON textarea. A Frontend Engineer's
+    # typed fields will post a real hash instead, so both are accepted.
+    def cast_context(given)
+      given = given.to_unsafe_h if given.respond_to?(:to_unsafe_h)
+      return given.to_h if given.is_a?(Hash)
+      return {} if given.to_s.strip.empty?
+
+      parsed = JSON.parse(given.to_s)
+      raise ActsAsCalculator::Error, context_error(given) unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError
+      raise ActsAsCalculator::Error, context_error(given)
+    end
+
+    def context_error(given)
+      "preview context must be a JSON object, got #{given.to_s.inspect}"
+    end
+  end
+end

data/lib/acts_as_calculator_editor/validate_expression.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # What a live expression field can be told about a formula before it is published, with
+  # no evaluation and nothing persisted (docs/core-gem-contract.md §4.1).
+  #
+  # `BuildCalculator.()` hands back a Dentaku calculator with the gem's function registry
+  # already installed, so `#ast` catches unbalanced parentheses, malformed operators *and*
+  # undefined function names — including whatever the host registered — while
+  # `#identifiers` lists every variable the expression could reach, syntactically, without
+  # evaluating a single branch.
+  #
+  # What this deliberately does not claim: whether the host's model actually responds to an
+  # `attribute` or `method` variable. That is only knowable when a real record is in hand,
+  # and saying otherwise would promise a guarantee the check does not make.
+  #
+  # This belongs upstream next to `EvaluateExpression`; it lives here because the core gem
+  # has no `ValidateExpression` Decree yet.
+  class ValidateExpression
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(expression:, variables: [], scope: nil, owner: nil)
+      @expression = expression.to_s
+      @variables = Array(variables).map { |variable| ActsAsCalculator::CastVariableAttributes.(variable) }
+      @scope = (scope.presence || ActsAsCalculator::DEFAULT_SCOPE).to_s
+      @owner = owner
+    end
+
+    def call
+      return blank if expression.strip.empty?
+      return unparsable if syntax_error
+
+      { valid: problems.empty?, errors: problems, warnings:, identifiers: }
+    end
+
+    private
+
+    attr_reader :expression, :variables, :scope, :owner
+
+    # `""` parses to `Dentaku::AST::Nil` rather than raising, so presence is a separate
+    # check — the same one `FormulaVersion` makes.
+    def blank
+      { valid: false, errors: [error(:blank, "expression can't be blank")], warnings: [], identifiers: [] }
+    end
+
+    def unparsable
+      { valid: false, errors: [error(:syntax, syntax_error)], warnings: [], identifiers: [] }
+    end
+
+    def calculator
+      @calculator ||= ActsAsCalculator::BuildCalculator.()
+    end
+
+    def syntax_error
+      return @syntax_error if defined?(@syntax_error)
+
+      calculator.ast(expression)
+      @syntax_error = nil
+    rescue Dentaku::Error => e
+      @syntax_error = e.message
+    end
+
+    # `BuildCalculator` defaults to `case_sensitive: false`, so Dentaku hands these back
+    # downcased. Comparing declared names any other way reports false "undeclared variable"
+    # errors on `Salary`.
+    def identifiers
+      @identifiers ||= calculator.identifiers(expression).map(&:to_s)
+    rescue Dentaku::Error
+      @identifiers = []
+    end
+
+    def declared
+      @declared ||= variables.to_h { |variable| [variable[:name].to_s.downcase, variable] }
+    end
+
+    def problems
+      @problems ||= undeclared + missing_lookup_tables
+    end
+
+    def undeclared
+      (identifiers.map(&:downcase) - declared.keys).uniq.map do |name|
+        error(:undeclared_variable,
+              "#{name.inspect} is used in the expression but not declared as a variable — " \
+              "it will raise MissingVariableError when the formula runs",
+              name:)
+      end
+    end
+
+    def missing_lookup_tables
+      lookup_variables.reject { |_, table_key| resolves?(table_key) }.map do |name, table_key|
+        error(:missing_lookup_table,
+              "variable #{name.inspect} reads lookup table #{table_key.inspect}, " \
+              "which does not exist in scope #{scope.inspect}",
+              name:)
+      end
+    end
+
+    def lookup_variables
+      declared.filter_map do |name, variable|
+        next unless variable[:source_type].to_s == "lookup"
+
+        [name, (variable[:source_config] || {}).transform_keys(&:to_s).fetch("table", name).to_s]
+      end
+    end
+
+    # The same owner-first, global-second resolution `BuildLookups` performs at calculation
+    # time, so this answers what an actual run would find rather than a near-miss of it.
+    def resolves?(table_key)
+      !ActsAsCalculator::FindOwnedRecord.(relation: ActsAsCalculator::LookupTable.all,
+                                          key: table_key, scope:, owner:).nil?
+    end
+
+    def warnings
+      (declared.keys - identifiers.map(&:downcase)).map do |name|
+        error(:unreferenced_variable,
+              "#{name.inspect} is declared but never used in the expression",
+              name:)
+      end
+    end
+
+    def error(type, message, name: nil)
+      { type:, message:, name: }.compact
+    end
+  end
+end

data/lib/acts_as_calculator_editor/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  VERSION = "0.1.0"
+end