dogfood 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8f5e84e866312bd228f0fa94068f9a1553c52ef15221e541f933f3713c6ca84
+  data.tar.gz: 382acac5d2fddd967522af9f7c97a7a2dde1ab73a12dc67655a31ce3ee7108cc
+SHA512:
+  metadata.gz: e3876f850dcd5bcc59b58728ad4df5090400ae2fd6ad7391edd9a2f26db9a48104f416c7300810a252d4907ae9eadb1aa0bf5fc160c737eb95189739784e55c2
+  data.tar.gz: b1f219bb17809b21fbb1ddcaaf44941bb47c30497513c27341a24a366d453f5eec8c293702a9ea6ffaf39613b255e37dec6df22376a5b3128bd37f97c8087db2

data/bin/dogfood

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dogfood"
+Dogfood::CLI.new(ARGV).run

data/lib/dogfood/cli.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Dogfood
+  class CLI
+    def initialize(argv)
+      @argv = argv
+      @options = {
+        output: default_output_path,
+        days: 1,
+        wo_per_day: (3..6),
+        fleet_ratio: 0.25,
+        seed: nil,
+        scenario: nil
+      }
+    end
+
+    attr_reader :options
+
+    def run
+      parse!
+
+      if @options[:help]
+        print_help
+        return
+      end
+
+      unless @options[:pack]
+        warn "Error: --pack PATH is required"
+        print_help
+        exit 1
+      end
+
+      load_pack(@options[:pack])
+
+      if @options[:list]
+        list_scenarios
+        return
+      end
+
+      if @options[:explain]
+        explain_file(@options[:explain])
+        return
+      end
+
+      if @options[:dry_run] && @options[:scenario]
+        explain_scenario(@options[:scenario])
+        return
+      end
+
+      generator = Dogfood::DayGenerator.new(
+        pack: Dogfood::Pack.current,
+        days: @options[:days],
+        wo_per_day: @options[:wo_per_day],
+        fleet_ratio: @options[:fleet_ratio],
+        seed: @options[:seed],
+        scenario: @options[:scenario]
+      )
+      result = generator.generate
+
+      output = Dogfood::Renderer.new(result).render
+      FileUtils.mkdir_p(File.dirname(@options[:output]))
+      File.write(@options[:output], output)
+
+      puts "Generated simulation: #{@options[:output]}"
+      puts "Days: #{result[:days].length}"
+      puts "Seed: #{result[:seed]}"
+    end
+
+    def parse!
+      i = 0
+      while i < @argv.length
+        arg = @argv[i]
+        case arg
+        when "--pack"
+          @options[:pack] = @argv[i + 1]
+          i += 1
+        when "--scenario"
+          @options[:scenario] = @argv[i + 1]
+          i += 1
+        when "--list", "-l"
+          @options[:list] = true
+        when "--explain"
+          @options[:explain] = @argv[i + 1]
+          i += 1
+        when "--dry-run"
+          @options[:dry_run] = true
+        when "--random", "-r"
+          @options[:seed] = Random.new_seed
+        when /^--days(?:=(.+))?$/
+          @options[:days] = ($1 || @argv[i + 1]).to_i
+          i += 1 unless $1
+        when /^--wo-per-day(?:=(.+))?$/
+          @options[:wo_per_day] = parse_wo_per_day($1 || @argv[i + 1])
+          i += 1 unless $1
+        when /^--fleet-ratio(?:=(.+))?$/
+          @options[:fleet_ratio] = ($1 || @argv[i + 1]).to_f
+          i += 1 unless $1
+        when /^--seed(?:=(.+))?$/
+          @options[:seed] = ($1 || @argv[i + 1]).to_i
+          i += 1 unless $1
+        when /^--output(?:=(.+))?$/, "-o"
+          @options[:output] = ($1 || @argv[i + 1])
+          i += 1 unless $1
+        when "--help", "-h"
+          @options[:help] = true
+        end
+        i += 1
+      end
+    end
+
+    private
+
+    def load_pack(path)
+      Dogfood::Pack.current = nil
+      load File.expand_path(path)
+      raise "Pack file did not set Dogfood::Pack.current" unless Dogfood::Pack.current
+    end
+
+    def parse_wo_per_day(value)
+      if value.include?("-")
+        min, max = value.split("-").map(&:to_i)
+        (min..max)
+      else
+        value.to_i
+      end
+    end
+
+    def list_scenarios
+      puts "Available scenarios:"
+      Dogfood::Pack.current.scenario_keys.each do |key|
+        puts "  - #{key}"
+      end
+    end
+
+    def explain_file(path)
+      require "yaml"
+      yaml = YAML.load_file(path)
+      Dogfood::DSL::Schema.validate!(yaml)
+      klass = Dogfood::DSL::Compiler.compile(yaml, pack: Dogfood::Pack.current)
+      puts Dogfood::DSL::ExplainRenderer.new(klass.compiled_ast).render
+    end
+
+    def explain_scenario(name)
+      klass = Dogfood::Pack.current.find_scenario(name)
+      puts Dogfood::DSL::ExplainRenderer.new(klass.compiled_ast).render
+    end
+
+    def default_output_path
+      timestamp = Time.now.strftime("%Y-%m-%d-%H%M%S")
+      "tmp/simulations/#{timestamp}-simulation.md"
+    end
+
+    def print_help
+      puts <<~HELP
+        Usage: dogfood [options]
+
+          --pack PATH              Ruby file that registers a Dogfood::Pack (required)
+          --scenario NAME          Run a specific named scenario (otherwise: random mix)
+          --days N                 Number of simulated days (default: 1)
+          --wo-per-day N or M-N    Work orders per day (default: 3-6)
+          --fleet-ratio RATIO      Fraction of fleet stories (default: 0.25)
+          --seed N                 Set random seed for reproducibility
+          --random                 Use a random seed (prints it)
+          --output PATH, -o PATH   Output file path (default: tmp/simulations/<timestamp>.md)
+          --list, -l               List available scenarios
+          --explain FILE           Compile FILE and print the stage/decision tree, no RNG
+          --dry-run --scenario N   Same as --explain but takes a registered name
+          --help, -h               Show help
+      HELP
+    end
+  end
+end

data/lib/dogfood/day_generator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Dogfood
+  class DayGenerator
+    DEFAULTS = { days: 1, wo_per_day: (3..6), fleet_ratio: 0.25, seed: nil }.freeze
+
+    def initialize(pack:, days: nil, wo_per_day: nil, fleet_ratio: nil, seed: nil, scenario: nil)
+      @pack = pack
+      @config = DEFAULTS.dup
+      @config[:days] = days if days
+      @config[:wo_per_day] = wo_per_day if wo_per_day
+      @config[:fleet_ratio] = fleet_ratio if fleet_ratio
+      @config[:seed] = seed if seed
+      @scenario = scenario&.to_sym
+      @rng = Dogfood::Randomness.new(seed: @config[:seed])
+      @ledger = Dogfood::Ledger.new
+      @builder = Dogfood::StoryBuilder.new(pack: @pack, rng: @rng)
+    end
+
+    def generate
+      days = @config[:days].times.map { |i| build_day(i) }
+      { days: days, seed: @rng.seed }
+    end
+
+    private
+
+    def build_day(day_index)
+      carry_overs = @ledger.resumable_for(day_index)
+      new_stories = build_new_stories(day_index, carry_overs.length)
+      active = carry_overs + new_stories
+
+      morning, afternoon, evening = [], [], []
+      active.shuffle(random: @rng).each_with_index do |entry, i|
+        story = entry.is_a?(Hash) ? entry[:story] : entry
+        slot = time_slot_for(i, active.length)
+        result = story.advance(day_index: day_index)
+        case slot
+        when :morning then morning << result
+        when :afternoon then afternoon << result
+        when :evening then evening << result
+        end
+        update_ledger(result)
+      end
+
+      {
+        index: day_index,
+        date: Date.today + day_index,
+        morning: morning, afternoon: afternoon, evening: evening,
+        carry_overs: carry_overs.map { |s| summarize(s) },
+        end_of_day_board: @ledger.open_stories.map { |s| summarize(s) }
+      }
+    end
+
+    def build_new_stories(day_index, carry_over_count)
+      target = wo_count_for_day
+      count = [target - carry_over_count, 0].max
+      count.times.map do
+        story = @builder.build(fleet_ratio: @config[:fleet_ratio], include: @scenario)
+        @ledger.register({ story: story, id: story.id, status: :estimate })
+        story
+      end
+    end
+
+    def update_ledger(result)
+      if result[:terminal]
+        @ledger.close(result[:id])
+      else
+        entry = @ledger.find(result[:id])
+        if entry
+          entry[:status] = result[:state][:status]
+          entry[:substatus] = result[:state][:substatus]
+          entry[:resume_on] = result[:resume_on]
+        end
+      end
+    end
+
+    def wo_count_for_day
+      range = @config[:wo_per_day]
+      range.is_a?(Range) ? @rng.rand(range) : range
+    end
+
+    def time_slot_for(index, total)
+      return :morning if index < (total * 0.5).ceil
+      return :afternoon if index < (total * 0.85).ceil
+      :evening
+    end
+
+    def summarize(story_or_hash)
+      story = story_or_hash.is_a?(Hash) ? story_or_hash[:story] : story_or_hash
+      { id: story.id, status: story.state[:status], substatus: story.state[:substatus] }
+    end
+  end
+end

data/lib/dogfood/dsl/compiler.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Dogfood
+  module DSL
+    # Compiles a validated scenario YAML hash into an anonymous
+    # Class(Dogfood::StoryBase). See SPEC.md 4.9 and 4.7.
+    module Compiler
+      TERMINAL_STATUSES = %i[paid declined voided].freeze
+
+      def self.compile(yaml, pack:)
+        ast = parse_ast(yaml)
+        validate_calls(ast, pack)
+
+        klass = Class.new(Dogfood::StoryBase) do
+          pack.step_modules.each { |m| include(m) }
+          pack.mixin_modules.each { |m| include(m) }
+          define_singleton_method(:compiled_ast) { ast }
+        end
+
+        klass.define_method(:title) { yaml["title"] }
+
+        klass.define_method(:advance) do |day_index:|
+          @current_day = day_index
+          @bindings ||= {}
+          @branch_for ||= {}
+          @next_stage ||= nil
+
+          stages.each do |stage_spec|
+            next unless @next_stage.nil? || @next_stage == stage_spec[:stage]
+            run_stage(stage_spec)
+            @next_stage = next_stage_after(stage_spec[:stage])
+          end
+
+          terminal = TERMINAL_STATUSES.include?(@state[:status])
+          {
+            id: id,
+            steps: @steps,
+            state: @state,
+            terminal: terminal,
+            resume_on: terminal ? nil : next_resume_day
+          }
+        end
+
+        klass.define_method(:stages) { self.class.compiled_ast[:stages] }
+
+        klass.define_method(:next_stage_after) do |stage|
+          idx = self.class.compiled_ast[:stages].index { |s| s[:stage] == stage }
+          nxt = self.class.compiled_ast[:stages][idx + 1]
+          nxt && nxt[:stage]
+        end
+
+        klass.define_method(:run_stage) do |stage_spec|
+          branch = resolve_branch(stage_spec)
+          stage_spec[:steps].each do |step_spec|
+            run_step(step_spec, branch)
+          end
+        end
+
+        klass.define_method(:resolve_branch) do |stage_spec|
+          weights = stage_spec[:branch_weights]
+          return nil unless weights
+          @branch_for[stage_spec[:stage]] ||= @rng.branch(weights)
+        end
+
+        klass.define_method(:run_step) do |step_spec, branch|
+          case step_spec[:type]
+          when :call
+            return if step_spec[:when_branch] && step_spec[:when_branch] != branch
+            call_step(step_spec)
+          when :when
+            list = eval_expr(step_spec[:expr]) ? step_spec[:then] : step_spec[:else]
+            (list || []).each { |c| run_step(c, nil) }
+          when :maybe
+            step_spec[:then].each { |c| run_step(c, nil) } if @rng.rand < step_spec[:prob]
+          end
+        end
+
+        klass.define_method(:call_step) do |call_spec|
+          if call_spec[:name] == :update_state
+            args = eval_with(call_spec[:with])
+            update_state(status: args[:status].to_sym, substatus: args[:substatus])
+            return
+          end
+
+          args = eval_with(call_spec[:with])
+          ret = send(call_spec[:name], **args)
+          bind_out(call_spec[:out], ret)
+        end
+
+        klass.define_method(:eval_with) do |with_hash|
+          (with_hash || {}).each_with_object({}) do |(k, v), acc|
+            acc[k.to_sym] = Dogfood::DSL::Evaluator.eval(v, bindings: @bindings, state: @state, rng: @rng, self_object: self)
+          end
+        end
+
+        klass.define_method(:eval_expr) do |expr|
+          Dogfood::DSL::Evaluator.eval(expr, bindings: @bindings, state: @state, rng: @rng, self_object: self)
+        end
+
+        klass.define_method(:bind_out) do |out, ret|
+          return unless out
+          if out.is_a?(Array)
+            if ret.is_a?(Hash)
+              out.each { |name| @bindings[name.to_sym] = ret[name.to_sym] }
+            else
+              out.each_with_index { |name, i| @bindings[name.to_sym] = ret[i] }
+            end
+          else
+            @bindings[out.to_sym] = ret
+          end
+        end
+
+        klass.define_method(:next_resume_day) do
+          resume = self.class.compiled_ast[:resume]
+          resume && resume[:after_await] == :same_day ? @current_day : @current_day + 1
+        end
+
+        klass
+      end
+
+      def self.parse_ast(yaml)
+        stages = yaml["stages"].map(&:to_sym)
+        branches = (yaml["branches"] || {}).each_with_object({}) do |(stage, weights), acc|
+          acc[stage.to_sym] = weights.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+        end
+
+        stage_list = stages.map do |stage|
+          steps = yaml["stages_def"][stage.to_s].map { |s| parse_step(s, stage.to_s) }
+          {
+            stage: stage,
+            branch_weights: branches[stage],
+            steps: steps
+          }
+        end
+
+        resume = if yaml["resume"] && yaml["resume"]["after_await"]
+                   { after_await: yaml["resume"]["after_await"].to_sym }
+                 end
+
+        {
+          name: yaml["name"].to_sym,
+          title: yaml["title"],
+          stages: stage_list,
+          delays: (yaml["delays"] || {}).keys.map(&:to_sym),
+          resume: resume
+        }
+      end
+
+      def self.parse_step(step, stage)
+        if step.key?("call")
+          out = step["out"]
+          {
+            type: :call,
+            name: step["call"].to_sym,
+            when_branch: step["when_branch"]&.to_sym,
+            with: step["with"] || {},
+            out: normalize_out(out)
+          }
+        elsif step.key?("when")
+          {
+            type: :when,
+            expr: step["when"],
+            then: step["then"].map { |c| parse_block_step(c, stage) },
+            else: step["else"] ? step["else"].map { |c| parse_block_step(c, stage) } : []
+          }
+        elsif step.key?("maybe")
+          {
+            type: :maybe,
+            prob: step["maybe"],
+            then: step["then"].map { |c| parse_call(c, stage) }
+          }
+        else
+          raise Dogfood::NestingTooDeep, "invalid step in stage #{stage}"
+        end
+      end
+
+      def self.parse_call(step, stage)
+        unless step.key?("call")
+          raise Dogfood::NestingTooDeep, "nesting too deep at stage #{stage}: only call steps allowed in blocks"
+        end
+        {
+          type: :call,
+          name: step["call"].to_sym,
+          when_branch: nil,
+          with: step["with"] || {},
+          out: normalize_out(step["out"])
+        }
+      end
+
+      # A step inside a `when`/`then`/`else` block may be a `call` or a
+      # `maybe` probability step, but never another `when`. This is the
+      # depth-1 limit (SPEC.md 4.7).
+      def self.parse_block_step(step, stage)
+        if step.key?("when")
+          raise Dogfood::NestingTooDeep, "nesting too deep at stage #{stage}: when blocks may not nest"
+        end
+        if step.key?("maybe")
+          {
+            type: :maybe,
+            prob: step["maybe"],
+            then: step["then"].map { |c| parse_call(c, stage) }
+          }
+        else
+          parse_call(step, stage)
+        end
+      end
+
+      def self.normalize_out(out)
+        case out
+        when Array then out.map(&:to_sym)
+        when String then out.to_sym
+        else nil
+        end
+      end
+
+      def self.validate_calls(ast, pack)
+        names = collect_call_names(ast).uniq
+        names.each do |name|
+          next if name == :update_state
+          found = pack.step_modules.any? { |m| m.instance_methods.include?(name) } ||
+                  pack.mixin_modules.any? { |m| m.instance_methods.include?(name) }
+          raise Dogfood::Pack::UnknownScenario, "call :#{name} does not resolve to a pack step module" unless found
+        end
+      end
+
+      def self.collect_call_names(ast)
+        ast[:stages].flat_map { |s| collect_stage_names(s[:steps]) }
+      end
+
+      def self.collect_stage_names(steps)
+        steps.flat_map do |step|
+          case step[:type]
+          when :call then [step[:name]]
+          when :when
+            collect_block_names(step[:then]) + collect_block_names(step[:else])
+          when :maybe then step[:then].map { |c| c[:name] }
+          else []
+          end
+        end
+      end
+
+      def self.collect_block_names(steps)
+        steps.flat_map do |step|
+          if step[:type] == :maybe
+            step[:then].map { |c| c[:name] }
+          else
+            [step[:name]]
+          end
+        end
+      end
+    end
+  end
+end