dogfood 0.1.0

data/lib/dogfood/dsl/evaluator.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Dogfood
+  module DSL
+    # Evaluates minimal ${...} expressions. Safe: it is a tiny hand-rolled
+    # recursive-descent parser, NOT eval. See SPEC.md 4.4 for the grammar.
+    module Evaluator
+      TOKEN = /\$\{([^}]*)\}/
+
+      # Evaluates a value that may contain ${...} tokens.
+      # Returns the raw bound value if the entire input is a single ${...};
+      # otherwise interpolates tokens into the surrounding string.
+      def self.eval(value, bindings:, state:, rng:, self_object: nil)
+        if value.is_a?(String) && (m = TOKEN.match(value)) && m[0] == value
+          return evaluate_expression(m[1], bindings: bindings, state: state, rng: rng, self_object: self_object)
+        end
+
+        case value
+        when String
+          value.gsub(TOKEN) do
+            result = evaluate_expression(Regexp.last_match(1), bindings: bindings, state: state, rng: rng, self_object: self_object)
+            stringify(result)
+          end
+        when Hash
+          value.each_with_object({}) do |(k, v), acc|
+            acc[eval(k, bindings: bindings, state: state, rng: rng, self_object: self_object)] =
+              eval(v, bindings: bindings, state: state, rng: rng, self_object: self_object)
+          end
+        when Array
+          value.map { |v| eval(v, bindings: bindings, state: state, rng: rng, self_object: self_object) }
+        else
+          value
+        end
+      end
+
+      # Parses and evaluates a single expression (without ${...} delimiters).
+      def self.evaluate_expression(expr, bindings:, state:, rng:, self_object: nil)
+        Parser.new(expr, bindings: bindings, state: state, rng: rng, self_object: self_object).parse
+      end
+
+      def self.stringify(value)
+        case value
+        when nil then "null"
+        when true then "true"
+        when false then "false"
+        else value.to_s
+        end
+      end
+
+      # Recursive-descent parser for the expression grammar.
+      class Parser
+        def initialize(input, bindings:, state:, rng:, self_object: nil)
+          @input = input.strip
+          @pos = 0
+          @bindings = bindings
+          @state = state
+          @rng = rng
+          @self_object = self_object
+        end
+
+        def parse
+          result = parse_comparison
+          skip_ws
+          raise_error("unexpected trailing input") unless eof?
+          result
+        end
+
+        private
+
+        def parse_comparison
+          left = parse_primary
+          skip_ws
+          if peek("==") || peek("!=")
+            op = advance(2)
+            skip_ws
+            right = parse_primary
+            op == "==" ? left == right : left != right
+          else
+            left
+          end
+        end
+
+        def parse_primary
+          skip_ws
+          if peek("rand(")
+            parse_rand_call
+          elsif peek(":")
+            advance(1)
+            parse_identifier
+          elsif digit?(peek_char)
+            parse_number
+          else
+            parse_reference
+          end
+        end
+
+        def parse_rand_call
+          advance(5) # "rand("
+          skip_ws
+          low = parse_number
+          skip_ws
+          advance(2) # ".."
+          skip_ws
+          high = parse_number
+          skip_ws
+          advance(1) # ")"
+          @rng.rand(low..high)
+        end
+
+        def parse_reference
+          parts = [parse_identifier]
+          while peek(".")
+            advance(1)
+            parts << parse_identifier
+          end
+          resolve_reference(parts)
+        end
+
+        def resolve_reference(parts)
+          first = parts.first
+          value = resolve_root(first)
+          parts[1..].each do |part|
+            value = access(value, part)
+          end
+          value
+        end
+
+        def resolve_root(name)
+          if name == :state
+            @state
+          elsif name == :rng
+            @rng
+          elsif @bindings.key?(name)
+            @bindings[name]
+          elsif @self_object && @self_object.instance_variable_defined?("@#{name}")
+            @self_object.instance_variable_get("@#{name}")
+          else
+            raise_error("unknown variable #{name}")
+          end
+        end
+
+        def access(value, key)
+          if value.is_a?(Hash)
+            value[key.to_sym] || value[key]
+          else
+            value.public_send(key)
+          end
+        end
+
+        def parse_number
+          skip_ws
+          start = @pos
+          advance while digit?(peek_char)
+          skip_ws
+          if peek_char == "." && digit?(peek_char(1))
+            advance
+            advance while digit?(peek_char)
+          end
+          text = @input[start...@pos]
+          text.include?(".") ? text.to_f : text.to_i
+        end
+
+        def parse_identifier
+          skip_ws
+          start = @pos
+          raise_error("expected identifier") unless letter?(peek_char)
+          advance while identifier_char?(peek_char)
+          @input[start...@pos].to_sym
+        end
+
+        def letter?(c)
+          c && c.match?(/[a-zA-Z_]/)
+        end
+
+        def identifier_char?(c)
+          c && c.match?(/[a-zA-Z0-9_]/)
+        end
+
+        def digit?(c)
+          c && c.match?(/[0-9]/)
+        end
+
+        def skip_ws
+          advance while peek_char == " "
+        end
+
+        def peek(str)
+          @input[@pos, str.length] == str
+        end
+
+        def advance(len = 1)
+          chunk = @input[@pos, len]
+          @pos += len
+          chunk
+        end
+
+        def peek_char(offset = 0)
+          @input[@pos + offset]
+        end
+
+        def eof?
+          @pos >= @input.length
+        end
+
+        def raise_error(message)
+          raise ArgumentError, "Invalid expression #{@input.inspect}: #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/dogfood/dsl/explain_renderer.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Dogfood
+  module DSL
+    # Renders the compiled AST into a human-readable stage/decision tree.
+    # Does NOT resolve randomness or evaluate expressions. See SPEC.md 5.
+    class ExplainRenderer
+      def initialize(ast)
+        @ast = ast
+      end
+
+      def render
+        lines = []
+        lines << "Scenario: #{@ast[:name]}"
+        lines << "Title: #{@ast[:title]}"
+        lines << "Stages: #{@ast[:stages].map { |s| s[:stage] }.join(' → ')}"
+        lines << ""
+
+        @ast[:stages].each do |stage|
+          lines << "┌─ #{stage[:stage]}"
+          lines.concat(render_stage(stage))
+          lines << ""
+        end
+
+        lines << "Resumes: #{render_resume}"
+        lines << "Delays: #{(@ast[:delays] || []).join(', ')}"
+
+        lines.join("\n")
+      end
+
+      private
+
+      def render_stage(stage)
+        lines = []
+        branch_steps, merge_steps = partition_branch_steps(stage)
+        has_merge = merge_steps.any?
+
+        branch_steps.each_with_index do |step, idx|
+          last_branch = idx == branch_steps.length - 1
+          connector = (last_branch && !has_merge) ? "└─" : "├─"
+          lines.concat(render_step(step, "│  ", connector, stage))
+        end
+
+        if has_merge
+          lines << "│  ↓ (all branches merge)" if branch_steps.any?
+          merge_steps.each_with_index do |step, idx|
+            connector = idx == merge_steps.length - 1 ? "└─" : "├─"
+            lines.concat(render_step(step, "│  ", connector, stage))
+          end
+        end
+
+        lines
+      end
+
+      # Steps carrying `when_branch` form the branch fan-out; the remaining
+      # steps run for all branches and are drawn after the merge marker.
+      def partition_branch_steps(stage)
+        steps = stage[:steps]
+        branch = steps.select { |s| s[:type] == :call && s[:when_branch] }
+        merge = steps.reject { |s| s[:type] == :call && s[:when_branch] }
+        [branch, merge]
+      end
+
+      def render_step(step, prefix, connector, stage)
+        case step[:type]
+        when :call then render_call(step, prefix, connector, stage)
+        when :when then render_when(step, prefix, connector)
+        when :maybe then render_maybe(step, prefix, connector)
+        else []
+        end
+      end
+
+      def render_call(step, prefix, connector, stage)
+        lines = []
+        line = "#{prefix}#{connector} #{step[:name]}"
+        if step[:when_branch]
+          weight = weight_for(stage, step[:when_branch])
+          line += "  [branch: #{step[:when_branch]}#{weight ? ", #{weight}" : ''}]"
+        end
+        line += "  → out: #{format_out(step[:out])}" if step[:out]
+        lines << line
+
+        with = step[:with] || {}
+        arg_prefix = prefix + "│  " + "  "
+        if with.key?(:wrong_part)
+          lines[-1] += " (with wrong_part)"
+        end
+        with.each do |k, v|
+          lines << "#{arg_prefix}#{k}: #{format_value(v)}"
+        end
+        lines
+      end
+
+      def render_when(step, prefix, connector)
+        lines = ["#{prefix}#{connector} when #{step[:expr]}"]
+        child_prefix = prefix + "│  "
+
+        lines << "#{child_prefix}   then:"
+        lines.concat(render_block(step[:then], child_prefix + "     "))
+
+        unless step[:else].empty?
+          lines << "#{child_prefix}   else:"
+          lines.concat(render_block(step[:else], child_prefix + "     "))
+        end
+        lines
+      end
+
+      def render_maybe(step, prefix, connector)
+        lines = ["#{prefix}#{connector} maybe #{step[:prob]}"]
+        child_prefix = prefix + "│  "
+        block_lines = render_block(step[:then], child_prefix + "     ")
+        block_lines.each { |bl| lines << "#{child_prefix}     #{bl}" }
+        lines
+      end
+
+      # Renders a flat block (calls and maybes) at the given indent.
+      def render_block(steps, indent)
+        steps.each_with_index.flat_map do |item, idx|
+          connector = idx == steps.length - 1 ? "└─" : "├─"
+          rendered = case item[:type]
+                     when :maybe then render_maybe(item, indent, connector)
+                     else render_call(item, indent, connector, nil)
+                     end
+          rendered
+        end
+      end
+
+      def weight_for(stage, branch)
+        weights = stage[:branch_weights]
+        weights && weights[branch]
+      end
+
+      def render_resume
+        resume = @ast[:resume]
+        resume ? "after_await → #{resume[:after_await]}" : "-"
+      end
+
+      def format_out(out)
+        out.is_a?(Array) ? out.join(", ") : out.to_s
+      end
+
+      def format_value(value)
+        case value
+        when Hash then format_hash(value)
+        when Array then value.map { |v| format_value(v) }.join(", ")
+        when String then format_string(value)
+        when nil then "null"
+        else value.to_s
+        end
+      end
+
+      def format_hash(hash)
+        nested = hash.values.any? { |v| v.is_a?(Hash) || v.is_a?(Array) }
+        referenced = hash.values.any? { |v| v.is_a?(String) && v.match?(/\$\{/) }
+
+        if !nested && !referenced
+          "{ #{hash.values.map { |v| format_value(v) }.join(' ')} }"
+        else
+          "{ #{hash.map { |k, v| "#{k}: #{format_value(v)}" }.join(', ')} }"
+        end
+      end
+
+      def format_string(str)
+        if str.match?(/\A\$\{[^}]*\}\z/) || str.match?(/\A[a-zA-Z0-9_]+\z/)
+          str
+        else
+          str.inspect
+        end
+      end
+    end
+  end
+end

data/lib/dogfood/dsl/schema.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Dogfood
+  module DSL
+    # Hand-rolled structural validation of scenario YAML. See SPEC.md 4.10
+    # and 4.7 (the depth-1 nesting limit is enforced here).
+    module Schema
+      ValidationError = Class.new(StandardError)
+
+      def self.validate!(yaml)
+        raise ValidationError, "must be a Hash" unless yaml.is_a?(Hash)
+
+        require_keys!(yaml, "name", "title", "stages", "stages_def")
+        validate_name(yaml["name"])
+        validate_title(yaml["title"])
+        stages = validate_stages(yaml["stages"])
+        validate_stages_def(yaml["stages_def"], stages)
+        validate_branches(yaml["branches"], stages) if yaml["branches"]
+        validate_delays(yaml["delays"]) if yaml["delays"]
+        validate_resume(yaml["resume"]) if yaml["resume"]
+        validate_fleet_ratio(yaml["fleet_ratio"]) if yaml["fleet_ratio"]
+
+        true
+      end
+
+      class << self
+        private
+
+        def require_keys!(yaml, *keys)
+          missing = keys.reject { |k| yaml.key?(k) }
+          unless missing.empty?
+            raise ValidationError, "missing required key(s): #{missing.join(', ')}"
+          end
+        end
+
+        def validate_name(name)
+          unless name.is_a?(String) && name.match?(/\A[a-z][a-z0-9_]*\z/)
+            raise ValidationError, "name must be a lowercase symbol-like string"
+          end
+        end
+
+        def validate_title(title)
+          raise ValidationError, "title must be a String" unless title.is_a?(String)
+        end
+
+        def validate_stages(stages)
+          unless stages.is_a?(Array) && !stages.empty? && stages.all? { |s| s.is_a?(String) }
+            raise ValidationError, "stages must be a non-empty array of strings"
+          end
+          stages
+        end
+
+        def validate_stages_def(stages_def, stages)
+          unless stages_def.is_a?(Hash)
+            raise ValidationError, "stages_def must be a map of stage -> step list"
+          end
+
+          stages.each do |stage|
+            steps = stages_def[stage]
+            raise ValidationError, "stages_def missing stage: #{stage}" if steps.nil?
+            validate_step_list(steps, stage)
+          end
+
+          unknown = stages_def.keys - stages
+          unless unknown.empty?
+            raise ValidationError, "stages_def has stage(s) not in stages: #{unknown.join(', ')}"
+          end
+        end
+
+        def validate_step_list(steps, stage)
+          raise ValidationError, "stages_def[#{stage}] must be an array" unless steps.is_a?(Array)
+
+          steps.each_with_index do |step, idx|
+            validate_step(step, stage, idx)
+          end
+        end
+
+        def validate_step(step, stage, idx)
+          unless step.is_a?(Hash)
+            raise ValidationError, "stage #{stage}, step #{idx}: must be a map"
+          end
+
+          keys = step.keys
+          if keys.include?("call")
+            validate_call(step, stage, idx)
+          elsif keys.include?("when")
+            validate_when(step, stage, idx)
+          elsif keys.include?("maybe")
+            validate_maybe(step, stage, idx)
+          else
+            raise ValidationError, "stage #{stage}, step #{idx}: must have call, when, or maybe"
+          end
+        end
+
+        def validate_call(step, stage, idx)
+          raise ValidationError, "stage #{stage}, step #{idx}: call name required" unless step["call"].is_a?(String)
+        end
+
+        def validate_when(step, stage, idx)
+          unless step["when"].is_a?(String)
+            raise ValidationError, "stage #{stage}, step #{idx}: when must be an expression string"
+          end
+          require_then_block!(step, stage, idx, "when")
+          validate_when_block!(step["then"], stage, idx, "then")
+          if step.key?("else")
+            validate_when_block!(step["else"], stage, idx, "else")
+          end
+        end
+
+        def validate_maybe(step, stage, idx)
+          maybe = step["maybe"]
+          unless maybe.is_a?(Numeric) && maybe >= 0 && maybe <= 1
+            raise ValidationError, "stage #{stage}, step #{idx}: maybe must be a float in 0..1"
+          end
+          require_then_block!(step, stage, idx, "maybe")
+          validate_flat_block!(step["then"], stage, idx, "then")
+        end
+
+        def require_then_block!(step, stage, idx, kind)
+          unless step["then"].is_a?(Array) && !step["then"].empty?
+            raise ValidationError, "stage #{stage}, step #{idx}: #{kind} requires a non-empty then list"
+          end
+        end
+
+        # A `when` branch may contain `call` steps and (one level down) a
+        # `maybe` probability step — but NEVER another `when`. This is the
+        # depth-1 limit, and it is what the reference example relies on.
+        def validate_when_block!(list, stage, idx, label)
+          list.each_with_index do |item, item_idx|
+            unless item.is_a?(Hash)
+              raise ValidationError, "stage #{stage}, step #{idx} (#{label} item #{item_idx}): must be a map"
+            end
+            if item.key?("when")
+              raise ValidationError,
+                    "nesting too deep at stage #{stage}, step #{idx} (#{label} item #{item_idx}): only call/maybe steps allowed"
+            end
+            if item.key?("maybe")
+              validate_maybe(item, stage, "#{idx}.#{item_idx}")
+            elsif !item.key?("call")
+              raise ValidationError, "stage #{stage}, step #{idx} (#{label} item #{item_idx}): must be call or maybe"
+            end
+          end
+        end
+
+        def validate_flat_block!(list, stage, idx, label)
+          list.each_with_index do |item, item_idx|
+            unless item.is_a?(Hash) && item.key?("call")
+              raise ValidationError,
+                    "nesting too deep at stage #{stage}, step #{idx} (#{label} item #{item_idx}): only call steps allowed"
+            end
+          end
+        end
+
+        def validate_branches(branches, stages)
+          unless branches.is_a?(Hash)
+            raise ValidationError, "branches must be a map of stage -> weight map"
+          end
+
+          branches.each do |stage, weights|
+            unless stages.include?(stage)
+              raise ValidationError, "branches references unknown stage: #{stage}"
+            end
+            validate_weights!(weights, "branches[#{stage}]")
+          end
+        end
+
+        def validate_delays(delays)
+          unless delays.is_a?(Hash)
+            raise ValidationError, "delays must be a map of event -> weight map"
+          end
+
+          delays.each do |event, weights|
+            validate_weights!(weights, "delays[#{event}]")
+          end
+        end
+
+        def validate_weights!(weights, label)
+          unless weights.is_a?(Hash)
+            raise ValidationError, "#{label} must be a weight map"
+          end
+          unless weights.values.all? { |v| v.is_a?(Numeric) }
+            raise ValidationError, "#{label} weights must be numeric"
+          end
+        end
+
+        def validate_resume(resume)
+          unless resume.is_a?(Hash)
+            raise ValidationError, "resume must be a map"
+          end
+        end
+
+        def validate_fleet_ratio(ratio)
+          unless ratio.is_a?(Numeric) && ratio >= 0 && ratio <= 1
+            raise ValidationError, "fleet_ratio must be a float in 0..1"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dogfood/ledger.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Dogfood
+  class Ledger
+    def initialize
+      @entries = {}
+    end
+
+    def register(story)
+      @entries[story[:id]] = story
+    end
+
+    def close(id)
+      @entries.delete(id)
+    end
+
+    def open_stories
+      @entries.values
+    end
+
+    def resumable_for(day_index)
+      @entries.values.select { |s| s[:resume_on] == day_index }
+    end
+
+    def find(id)
+      @entries[id]
+    end
+  end
+end

data/lib/dogfood/pack.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Dogfood
+  class Pack
+    UnknownScenario = Class.new(StandardError)
+
+    class << self
+      attr_accessor :current
+    end
+
+    attr_reader :name, :step_modules, :mixin_modules, :pools, :delay_distributions, :scenarios
+
+    def initialize(name)
+      @name = name
+      @step_modules = []
+      @mixin_modules = []
+      @pools = {}
+      @delay_distributions = {}
+      @scenarios = {}
+      yield self if block_given?
+    end
+
+    def include_steps(*mods)
+      @step_modules.concat(mods)
+    end
+
+    def include_mixins(*mods)
+      @mixin_modules.concat(mods)
+    end
+
+    def pools(*mods)
+      mods.each { |m| @pools[m.name.split("::").last.to_sym] = m }
+    end
+
+    def delays(hash)
+      @delay_distributions.merge!(hash)
+    end
+
+    def register(name, klass)
+      @scenarios[name.to_sym] = klass
+    end
+
+    def scenario_keys
+      @scenarios.keys
+    end
+
+    def find_scenario(name)
+      @scenarios[name.to_sym] or raise UnknownScenario, "Unknown scenario: #{name}"
+    end
+
+    def load_dir(glob)
+      Dir[glob].each { |path| load_file(path) }
+    end
+
+    def load_file(path)
+      require "yaml"
+      yaml = YAML.load_file(path)
+      require_relative "dsl/schema"
+      require_relative "dsl/compiler"
+      Dogfood::DSL::Schema.validate!(yaml)
+      klass = Dogfood::DSL::Compiler.compile(yaml, pack: self)
+      register(yaml["name"].to_sym, klass)
+    end
+  end
+end

data/lib/dogfood/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module Dogfood
+  class Engine < ::Rails::Engine
+    engine_name "dogfood"
+
+    initializer "dogfood.load_pack" do |app|
+      pack_file = app.root.join("config", "dogfood.rb")
+      next unless pack_file.exist?
+
+      Dogfood::Pack.current = nil
+      load pack_file.to_s
+      unless Dogfood::Pack.current
+        raise "config/dogfood.rb did not set Dogfood::Pack.current"
+      end
+    end
+  end
+end