dogfood 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f3da6c7dfbeb9f09325d741ae81a835d65da453a17f5ca6deeb3cfde8826f73
-  data.tar.gz: 258a2ad0661d1aa5234e18305f75a39a0a696f8108fdef39988299db8e07d709
+  metadata.gz: 340e952c9eb89332501cff612428e4b2bf34a0a75af4f2d73efb0461cc8e8180
+  data.tar.gz: 0c7edf6a45de18e1827522185f418ec1058c29d03f9fcdf410b0bbf127d080b4
 SHA512:
-  metadata.gz: a6f7f694fbad5f13ff0d058eb819b005bc0cbd3464a3a692d022273759ec5f55bdc38e2206d99d2221fd458db732f948929d47949feccb44ddf2a210191fa624
-  data.tar.gz: 5a23dcbaf64043a23160180459ec1cf73fb39ac83adb630bd010affb36e42303c6f1edc7609c5193e7a30e31583ae8bd6fab845b4ed323385a9c31195de72d69
+  metadata.gz: e2dcfd39797bbb4c1951cf6aa5e046f104fa4da301c6e2ae96d72dd414a7374973fb3a01118eeb59418ee9381345e11e3d7853d9ec5e938e9084eea0a5076914
+  data.tar.gz: c7a8c24b61eac1aa38186411b6ff7a43ad2e2f7cdacf4223596fc158ce53ad6b5736dc1c46f0c7b3297990f90313c0ad8adf1a8d42ce69dc3d640577bce8681d

data/lib/dogfood/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "pathname"
 
 module Dogfood
   class CLI
@@ -13,7 +14,8 @@ module Dogfood
         days: 1,
         stories_per_day: (3..6),
         seed: nil,
-        scenario: nil
+        scenario: nil,
+        format: "text"
       }
     end
 
@@ -105,6 +107,9 @@ module Dogfood
         when /^--output(?:=(.+))?$/, "-o"
           @options[:output] = ($1 || @argv[i + 1])
           i += 1 unless $1
+        when "--format"
+          @options[:format] = @argv[i + 1]
+          i += 1
         when "--help", "-h"
           @options[:help] = true
         else
@@ -130,6 +135,7 @@ module Dogfood
           --explain [NAME|FILE]    Print the stage/decision tree for a scenario name
                                    or YAML file, no RNG
           --dry-run --scenario NAME  Same as --explain NAME
+          --format text|markdown|json  Output format for --explain (default: text)
           --help, -h               Show help
 
         Examples:
@@ -143,11 +149,27 @@ module Dogfood
     private
 
     def load_pack(path)
+      ensure_rails_root_shim
       Dogfood::Pack.current = nil
       load File.expand_path(path)
       raise "Pack file did not set Dogfood::Pack.current" unless Dogfood::Pack.current
     end
 
+    # A pack file may reference Rails.root to locate scenarios. When run as a
+    # bare `dogfood` executable from a Rails app root, Rails isn't booted. If we
+    # detect a Rails app (config/application.rb in the current directory) and
+    # Rails isn't already defined, provide a minimal shim exposing `Rails.root`
+    # pointing at the app root so the pack loads without a full app boot.
+    def ensure_rails_root_shim
+      return if defined?(Rails)
+      return unless File.exist?(File.expand_path("config/application.rb", Dir.pwd))
+
+      root = Pathname.new(Dir.pwd)
+      shim = Module.new
+      shim.define_singleton_method(:root) { root }
+      Object.const_set(:Rails, shim)
+    end
+
     def default_pack_path
       path = File.expand_path("config/dogfood.rb", Dir.pwd)
       File.exist?(path) ? path : nil
@@ -194,14 +216,16 @@ module Dogfood
       yaml = YAML.load_file(path)
       Dogfood::DSL::Schema.validate!(yaml)
       klass = Dogfood::DSL::Compiler.compile(yaml, pack: Dogfood::Pack.current)
-      puts Dogfood::DSL::AuditRenderer.new(klass.compiled_ast, pack: Dogfood::Pack.current).render
+      puts Dogfood::DSL::AuditRenderer.new(klass.compiled_ast, pack: Dogfood::Pack.current)
+        .render(format: @options[:format].to_sym)
     end
 
     def explain_scenario(name)
       klass = Dogfood::Pack.current.find_scenario(name)
 
       if klass.respond_to?(:compiled_ast)
-        puts Dogfood::DSL::AuditRenderer.new(klass.compiled_ast, pack: Dogfood::Pack.current).render
+        puts Dogfood::DSL::AuditRenderer.new(klass.compiled_ast, pack: Dogfood::Pack.current)
+          .render(format: @options[:format].to_sym)
       else
         puts render_ruby_story(name, klass)
       end

data/lib/dogfood/dsl/audit_renderer.rb

@@ -2,395 +2,23 @@
 
 module Dogfood
   module DSL
-    # Produces a five-section audit report for `--explain`:
-    #   A. Stage/decision tree (delegates to ExplainRenderer)
-    #   B. Branch weight table
-    #   C. Path enumeration (full step sequences per path)
-    #   D. Edge-case gap detection
-    #   E. Step resolution check
+    # Produces the `--explain` audit report. This is a thin facade over
+    # AuditReport, which owns the computation (IR) and the text/markdown/json
+    # formatters. The default `render` output is byte-identical to the
+    # pre-refactor five-section report; the regression target is
+    # EXAMPLES/explain_output.txt.
     class AuditRenderer
-      MAX_PATHS = 50
+      MAX_PATHS = AuditReport::MAX_PATHS
 
       def initialize(ast, pack: nil)
         @ast = ast
         @pack = pack
       end
 
-      def render
-        lines = []
-        lines.concat(section_a)
-        lines << ""
-        lines.concat(section_b)
-        lines << ""
-        lines.concat(section_c)
-        lines << ""
-        lines.concat(section_d)
-        lines << ""
-        lines.concat(section_e)
-        lines.join("\n") + "\n"
-      end
-
-      private
-
-      # ── Section A: Stage/decision tree ──
-
-      def section_a
-        ExplainRenderer.new(@ast).render.split("\n")
-      end
-
-      # ── Section B: Branch weight table ──
-
-      def section_b
-        lines = ["## Branch weights"]
-        any = false
-
-        @ast[:stages].each do |stage|
-          weights = stage[:branch_weights]
-          next unless weights
-
-          any = true
-          lines << ""
-          lines << "Stage: #{stage[:stage]}"
-          max_label = weights.keys.map(&:length).max
-          weights.each do |label, weight|
-            bar = bar_for(weight, weights.values.max)
-            lines << "  %-#{max_label}s  %.2f  %s" % [label, weight, bar]
-          end
-        end
-
-        # Surface when/maybe probabilities
-        when_probs = collect_conditional_probs
-        unless when_probs.empty?
-          any = true
-          lines << ""
-          lines << "Conditionals:"
-          when_probs.each do |desc|
-            lines << "  #{desc}"
-          end
-        end
-
-        lines << "" unless any
-        lines << "  (no branches or conditionals)" unless any
-        lines
-      end
-
-      def bar_for(weight, max_weight)
-        scale = (weight.to_f / max_weight * 20).round
-        "█" * scale
-      end
-
-      def collect_conditional_probs
-        probs = []
-        @ast[:stages].each do |stage|
-          stage[:steps].each do |step|
-            case step[:type]
-            when :maybe
-              probs << "maybe #{step[:prob]} in stage #{stage[:stage]}"
-            when :when
-              # Try to find a chance_decline or similar in the preceding call's with:
-              expr = step[:expr]
-              probs << "when #{expr} in stage #{stage[:stage]}"
-            end
-          end
-        end
-        probs
-      end
-
-      # ── Section C: Path enumeration ──
-
-      def section_c
-        lines = ["## Path enumeration"]
-        paths = enumerate_paths
-
-        if paths.length > MAX_PATHS
-          lines << ""
-          lines << "  ⚠ #{paths.length} paths total (showing first #{MAX_PATHS})"
-          paths = paths.first(MAX_PATHS)
-        end
-
-        paths.each_with_index do |path, idx|
-          lines << ""
-          label = path[:branches].empty? ? "(linear)" : path[:branches].join(" → ")
-          lines << "Path #{idx + 1}: #{label}"
-          path[:steps].each_with_index do |step, s_idx|
-            lines << "  #{s_idx + 1}. #{step}"
-          end
-          terminal = path[:terminal] || "unknown"
-          lines << "  Terminal: #{terminal}"
-        end
-
-        lines
-      end
-
-      def enumerate_paths
-        paths = []
-        walk_stages(@ast[:stages], 0, [], [], { status: :estimate, substatus: nil }, paths)
-        paths
-      end
-
-      # Walks stages recursively. state tracks known @state for when-condition pruning.
-      def walk_stages(stages, stage_idx, current_steps, branch_labels, state, paths)
-        if stage_idx >= stages.length
-          paths << { branches: branch_labels.dup, steps: current_steps.dup, terminal: "#{state[:status]} / #{state[:substatus] || '-'}" }
-          return
-        end
-
-        stage = stages[stage_idx]
-        weights = stage[:branch_weights]
-
-        if weights
-          weights.each_key do |branch_label|
-            filtered = filter_branch_steps(stage[:steps], branch_label)
-            new_branch_labels = branch_labels + [branch_label]
-            expand_steps(filtered, stage, stages, stage_idx, current_steps, new_branch_labels, state, paths)
-          end
-        else
-          expand_steps(stage[:steps], stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        end
-      end
-
-      def expand_steps(steps, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        fork_expansion(steps, 0, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-      end
-
-      def fork_expansion(steps, step_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        if step_idx >= steps.length
-          walk_stages(stages, stage_idx + 1, current_steps, branch_labels, state, paths)
-          return
-        end
-
-        step = steps[step_idx]
-        case step[:type]
-        when :call
-          new_steps = current_steps + [format_path_step(step)]
-          new_state = step[:name] == :update_state ? merge_state(state, step[:with]) : state
-          fork_expansion(steps, step_idx + 1, stage, stages, stage_idx, new_steps, branch_labels, new_state, paths)
-        when :when
-          result = eval_when_static(step[:expr], state)
-          if result == true
-            expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["then"], state, paths)
-          elsif result == false
-            expand_block(step[:else] || [], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["else"], state, paths)
-          else
-            expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["then"], state, paths)
-            expand_block(step[:else] || [], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["else"], state, paths)
-          end
-        when :maybe
-          expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
-          fork_expansion(steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        end
-      end
-
-      # Expands a block (then/else/maybe) which may contain :call and :maybe steps.
-      # After the block, continues with the remaining steps in the parent list.
-      def expand_block(block_steps, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        if block_steps.empty?
-          fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-          return
-        end
-
-        block_steps.each_with_index do |bstep, bidx|
-          case bstep[:type]
-          when :call
-            current_steps = current_steps + [format_path_step(bstep)]
-            new_state = bstep[:name] == :update_state ? merge_state(state, bstep[:with]) : state
-            if bidx == block_steps.length - 1
-              fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, new_state, paths)
-            else
-              state = new_state
-            end
-          when :maybe
-            # Fork: with maybe and without
-            if bidx == block_steps.length - 1
-              # Last item in block — fork then continue parent
-              expand_block(bstep[:then], parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
-              fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-            else
-              # Not last — need to fork and continue remaining block steps
-              # with maybe
-              expand_block_remainder(bstep[:then], block_steps, bidx + 1, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
-              # without maybe
-              expand_block_remainder([], block_steps, bidx + 1, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-            end
-            return
-          end
-        end
-      end
-
-      # Expands remainder of a block after a fork, then continues parent.
-      def expand_block_remainder(extra_steps, block_steps, start_idx, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-        remaining = extra_steps + block_steps[start_idx..]
-        expand_block(remaining, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
-      end
-
-      def merge_state(state, with_hash)
-        state.merge(
-          status: with_hash["status"]&.to_sym || state[:status],
-          substatus: with_hash.key?("substatus") ? with_hash["substatus"] : state[:substatus]
-        )
-      end
-
-      # Returns true/false if the when condition can be statically resolved, nil if unknown.
-      def eval_when_static(expr, state)
-        # Match ${state.status == :symbol} or ${state.status != :symbol}
-        return nil unless expr.is_a?(String)
-
-        if expr =~ /\$\{\s*state\.status\s*==\s*:(\w+)\s*\}/
-          return state[:status].to_s == $1
-        elsif expr =~ /\$\{\s*state\.status\s*!=\s*:(\w+)\s*\}/
-          return state[:status].to_s != $1
-        end
-        nil
-      end
-
-      def filter_branch_steps(steps, branch_label)
-        # Steps with when_branch matching the label, plus steps with no when_branch (merge steps)
-        steps.select do |s|
-          case s[:type]
-          when :call
-            s[:when_branch].nil? || s[:when_branch] == branch_label
-          else
-            true
-          end
-        end
-      end
-
-      def format_path_step(step)
-        args = step[:with] || {}
-        arg_str = args.empty? ? "" : " (#{args.map { |k, v| "#{k}: #{format_val(v)}" }.join(', ')})"
-        out_str = step[:out] ? " → out: #{step[:out]}" : ""
-        "#{step[:name]}#{arg_str}#{out_str}"
-      end
-
-      def format_val(v)
-        case v
-        when Hash then "{...}"
-        when Array then "[...]"
-        else v.to_s
-        end
-      end
-
-      # ── Section D: Edge-case gap detection ──
-
-      def section_d
-        lines = ["## Coverage gaps"]
-        gaps = detect_gaps
-
-        if gaps.empty?
-          lines << ""
-          lines << "  (no gaps detected)"
-        else
-          gaps.each { |g| lines << "  ⚠ #{g}" }
-        end
-
-        lines
-      end
-
-      def detect_gaps
-        gaps = []
-
-        @ast[:stages].each do |stage|
-          has_branches = !!stage[:branch_weights]
-          has_when = stage[:steps].any? { |s| s[:type] == :when }
-          has_maybe = stage[:steps].any? { |s| s[:type] == :maybe } ||
-                      stage[:steps].any? { |s| s[:type] == :when && s[:then].any? { |c| c[:type] == :maybe } }
-
-          unless has_branches || has_when || has_maybe
-            gaps << "stage \"#{stage[:stage]}\" has no branches or conditionals (linear)"
-          end
-
-          unless has_maybe
-            gaps << "stage \"#{stage[:stage]}\" has no maybe/error path"
-          end
-
-          # when blocks with no else
-          stage[:steps].each do |step|
-            if step[:type] == :when && (step[:else].nil? || step[:else].empty?)
-              gaps << "stage \"#{stage[:stage]}\" has a when block with no else"
-            end
-          end
-        end
-
-        # Check if all paths terminate in the same status
-        paths = enumerate_paths
-        terminals = paths.map { |p| p[:terminal] }.uniq
-        if terminals.length == 1 && terminals.first != "unknown"
-          gaps << "all paths terminate in \"#{terminals.first}\" — no alternative outcomes"
-        end
-
-        gaps
-      end
-
-      # ── Section E: Step resolution check ──
-
-      def section_e
-        lines = ["## Step resolution"]
-        names = collect_all_call_names.uniq
-
-        if names.empty?
-          lines << ""
-          lines << "  (no calls)"
-          return lines
-        end
-
-        builtins = Dogfood::DSL::Compiler::BUILTIN_NAMES
-        max_name = names.map(&:length).max
-
-        names.each do |name|
-          if builtins.include?(name)
-            lines << "  %-#{max_name}s  ✓ builtin" % name
-          elsif @pack && resolves_in_pack?(name)
-            mod = find_pack_module(name)
-            lines << "  %-#{max_name}s  ✓ pack (%s)" % [name, mod]
-          else
-            lines << "  %-#{max_name}s  ✗ missing" % name
-          end
-        end
-
-        if @pack && !@pack.pools.empty?
-          lines << ""
-          lines << "Pools:"
-          @pack.pools.sort_by { |name, _| name.to_s }.each do |name, pool|
-            lines << "  #{name} (#{pool.all.length} entries)"
-          end
-        end
-
-        lines
-      end
-
-      def resolves_in_pack?(name)
-        return false unless @pack
-        @pack.step_modules.any? { |m| m.instance_methods.include?(name) } ||
-          @pack.mixin_modules.any? { |m| m.instance_methods.include?(name) }
-      end
-
-      def find_pack_module(name)
-        return "unknown" unless @pack
-        mod = (@pack.step_modules + @pack.mixin_modules).find { |m| m.instance_methods.include?(name) }
-        mod&.name || "anonymous"
-      end
-
-      def collect_all_call_names
-        names = []
-        @ast[:stages].each do |stage|
-          stage[:steps].each do |step|
-            collect_step_names(step, names)
-          end
-        end
-        names
-      end
-
-      def collect_step_names(step, names)
-        case step[:type]
-        when :call
-          names << step[:name]
-        when :when
-          step[:then].each { |c| collect_step_names(c, names) }
-          (step[:else] || []).each { |c| collect_step_names(c, names) }
-        when :maybe
-          step[:then].each { |c| collect_step_names(c, names) }
-        end
+      def render(format: :text)
+        report = AuditReport.build(@ast, pack: @pack)
+        AuditReport.render(report, format: format)
       end
     end
   end
-end
+end

data/lib/dogfood/dsl/audit_report.rb

@@ -0,0 +1,777 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Dogfood
+  module DSL
+    # Builds a pure-data audit report from a compiled AST and renders it in one
+    # of three formats:
+    #   :text     -> the classic box-drawing tree + tables (default; regression
+    #                target is EXAMPLES/explain_output.txt)
+    #   :markdown -> GitHub-flavored Markdown (headings, bullets, tables)
+    #   :json     -> machine-readable; Ruby symbols tagged as {"__sym__": "..."}
+    #
+    # The computation (path enumeration, gap detection, branch-weight and step
+    # resolution collection) runs once in AuditReport.build; formatters only
+    # read the resulting Hash and emit strings.
+    class AuditReport
+      MAX_PATHS = 50
+
+      def self.build(ast, pack: nil, max_paths: MAX_PATHS)
+        new(ast, pack: pack, max_paths: max_paths).build
+      end
+
+      def self.render(report, format: :text)
+        case format.to_sym
+        when :text then TextFormatter.render(report)
+        when :markdown then MarkdownFormatter.render(report)
+        when :json then JsonFormatter.render(report)
+        else
+          raise ArgumentError, "unknown format: #{format.inspect}"
+        end
+      end
+
+      def initialize(ast, pack: nil, max_paths: MAX_PATHS)
+        @ast = ast
+        @pack = pack
+        @max_paths = max_paths
+      end
+
+      def build
+        paths = enumerate_paths
+        {
+          scenario: {
+            name: @ast[:name],
+            title: @ast[:title],
+            stages: @ast[:stages].map { |s| s[:stage] },
+            resume: @ast[:resume],
+            delays: @ast[:delays]
+          },
+          tree: build_tree,
+          tree_text: ExplainRenderer.new(@ast).render,
+          branches: build_branches,
+          conditionals: collect_conditional_probs,
+          paths: paths,
+          paths_truncated: paths.length > @max_paths,
+          paths_total: paths.length,
+          max_paths: @max_paths,
+          gaps: detect_gaps,
+          resolution: build_resolution
+        }
+      end
+
+      private
+
+      # ── Section A: stage/decision tree (as data nodes) ──
+
+      def build_tree
+        @ast[:stages].map do |stage|
+          { stage: stage[:stage], nodes: stage_nodes(stage) }
+        end
+      end
+
+      def stage_nodes(stage)
+        branch_steps, merge_steps = partition_branch_steps(stage)
+        nodes = branch_steps.map { |s| build_node(s, stage) }
+        if branch_steps.any? && merge_steps.any?
+          nodes << { type: :merge }
+        end
+        nodes.concat(merge_steps.map { |s| build_node(s, stage) })
+      end
+
+      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 build_node(step, stage)
+        case step[:type]
+        when :call
+          {
+            type: :call,
+            name: step[:name],
+            when_branch: step[:when_branch],
+            branch_weight: weight_for(stage, step[:when_branch]),
+            out: step[:out] ? format_out(step[:out]) : nil,
+            with_lines: build_with_lines(step[:with]),
+            with_wrong_part: !!(step[:with] && step[:with].key?(:wrong_part))
+          }
+        when :when
+          {
+            type: :when,
+            expr: step[:expr],
+            then_nodes: step[:then].map { |c| build_node(c, stage) },
+            else_nodes: (step[:else] || []).map { |c| build_node(c, stage) }
+          }
+        when :maybe
+          {
+            type: :maybe,
+            prob: step[:prob],
+            then_nodes: step[:then].map { |c| build_node(c, stage) }
+          }
+        else
+          { type: :unknown }
+        end
+      end
+
+      def build_with_lines(with)
+        (with || {}).map { |k, v| "#{k}: #{format_value(v)}" }
+      end
+
+      def weight_for(stage, branch)
+        weights = stage[:branch_weights]
+        weights && weights[branch]
+      end
+
+      # ── Section B: branch weights + conditional probabilities ──
+
+      def build_branches
+        @ast[:stages].each_with_object([]) do |stage, acc|
+          weights = stage[:branch_weights]
+          next unless weights
+
+          acc << {
+            stage: stage[:stage],
+            labels: weights.map { |label, weight| { label: label, weight: weight } }
+          }
+        end
+      end
+
+      def collect_conditional_probs
+        probs = []
+        @ast[:stages].each do |stage|
+          stage[:steps].each do |step|
+            case step[:type]
+            when :maybe
+              probs << "maybe #{step[:prob]} in stage #{stage[:stage]}"
+            when :when
+              probs << "when #{step[:expr]} in stage #{stage[:stage]}"
+            end
+          end
+        end
+        probs
+      end
+
+      # ── Section C: path enumeration ──
+
+      def enumerate_paths
+        paths = []
+        walk_stages(@ast[:stages], 0, [], [], { status: :estimate, substatus: nil }, paths)
+        paths
+      end
+
+      def walk_stages(stages, stage_idx, current_steps, branch_labels, state, paths)
+        if stage_idx >= stages.length
+          paths << { branches: branch_labels.dup, steps: current_steps.dup, terminal: "#{state[:status]} / #{state[:substatus] || '-'}" }
+          return
+        end
+
+        stage = stages[stage_idx]
+        weights = stage[:branch_weights]
+
+        if weights
+          weights.each_key do |branch_label|
+            filtered = filter_branch_steps(stage[:steps], branch_label)
+            new_branch_labels = branch_labels + [branch_label]
+            expand_steps(filtered, stage, stages, stage_idx, current_steps, new_branch_labels, state, paths)
+          end
+        else
+          expand_steps(stage[:steps], stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        end
+      end
+
+      def expand_steps(steps, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        fork_expansion(steps, 0, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+      end
+
+      def fork_expansion(steps, step_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        if step_idx >= steps.length
+          walk_stages(stages, stage_idx + 1, current_steps, branch_labels, state, paths)
+          return
+        end
+
+        step = steps[step_idx]
+        case step[:type]
+        when :call
+          new_steps = current_steps + [format_path_step(step)]
+          new_state = step[:name] == :update_state ? merge_state(state, step[:with]) : state
+          fork_expansion(steps, step_idx + 1, stage, stages, stage_idx, new_steps, branch_labels, new_state, paths)
+        when :when
+          result = eval_when_static(step[:expr], state)
+          if result == true
+            expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["then"], state, paths)
+          elsif result == false
+            expand_block(step[:else] || [], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["else"], state, paths)
+          else
+            expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["then"], state, paths)
+            expand_block(step[:else] || [], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["else"], state, paths)
+          end
+        when :maybe
+          expand_block(step[:then], steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
+          fork_expansion(steps, step_idx + 1, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        end
+      end
+
+      def expand_block(block_steps, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        if block_steps.empty?
+          fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+          return
+        end
+
+        block_steps.each_with_index do |bstep, bidx|
+          case bstep[:type]
+          when :call
+            current_steps = current_steps + [format_path_step(bstep)]
+            new_state = bstep[:name] == :update_state ? merge_state(state, bstep[:with]) : state
+            if bidx == block_steps.length - 1
+              fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, new_state, paths)
+            else
+              state = new_state
+            end
+          when :maybe
+            if bidx == block_steps.length - 1
+              expand_block(bstep[:then], parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
+              fork_expansion(parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+            else
+              expand_block_remainder(bstep[:then], block_steps, bidx + 1, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels + ["maybe"], state, paths)
+              expand_block_remainder([], block_steps, bidx + 1, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+            end
+            return
+          end
+        end
+      end
+
+      def expand_block_remainder(extra_steps, block_steps, start_idx, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+        remaining = extra_steps + block_steps[start_idx..]
+        expand_block(remaining, parent_steps, parent_idx, stage, stages, stage_idx, current_steps, branch_labels, state, paths)
+      end
+
+      def merge_state(state, with_hash)
+        state.merge(
+          status: with_hash["status"]&.to_sym || state[:status],
+          substatus: with_hash.key?("substatus") ? with_hash["substatus"] : state[:substatus]
+        )
+      end
+
+      def eval_when_static(expr, state)
+        return nil unless expr.is_a?(String)
+
+        if expr =~ /\$\{\s*state\.status\s*==\s*:(\w+)\s*\}/
+          return state[:status].to_s == $1
+        elsif expr =~ /\$\{\s*state\.status\s*!=\s*:(\w+)\s*\}/
+          return state[:status].to_s != $1
+        end
+        nil
+      end
+
+      def filter_branch_steps(steps, branch_label)
+        steps.select do |s|
+          case s[:type]
+          when :call
+            s[:when_branch].nil? || s[:when_branch] == branch_label
+          else
+            true
+          end
+        end
+      end
+
+      def format_path_step(step)
+        args = step[:with] || {}
+        arg_str = args.empty? ? "" : " (#{args.map { |k, v| "#{k}: #{format_val(v)}" }.join(', ')})"
+        out_str = step[:out] ? " → out: #{step[:out]}" : ""
+        "#{step[:name]}#{arg_str}#{out_str}"
+      end
+
+      def format_val(v)
+        case v
+        when Hash then "{...}"
+        when Array then "[...]"
+        else v.to_s
+        end
+      end
+
+      # ── Section D: edge-case gap detection ──
+
+      def detect_gaps
+        gaps = []
+
+        @ast[:stages].each do |stage|
+          has_branches = !!stage[:branch_weights]
+          has_when = stage[:steps].any? { |s| s[:type] == :when }
+          has_maybe = stage[:steps].any? { |s| s[:type] == :maybe } ||
+                      stage[:steps].any? { |s| s[:type] == :when && s[:then].any? { |c| c[:type] == :maybe } }
+
+          unless has_branches || has_when || has_maybe
+            gaps << "stage \"#{stage[:stage]}\" has no branches or conditionals (linear)"
+          end
+
+          unless has_maybe
+            gaps << "stage \"#{stage[:stage]}\" has no maybe/error path"
+          end
+
+          stage[:steps].each do |step|
+            if step[:type] == :when && (step[:else].nil? || step[:else].empty?)
+              gaps << "stage \"#{stage[:stage]}\" has a when block with no else"
+            end
+          end
+        end
+
+        terminals = enumerate_paths.map { |p| p[:terminal] }.uniq
+        if terminals.length == 1 && terminals.first != "unknown"
+          gaps << "all paths terminate in \"#{terminals.first}\" — no alternative outcomes"
+        end
+
+        gaps
+      end
+
+      # ── Section E: step resolution ──
+
+      def build_resolution
+        names = collect_all_call_names.uniq
+        calls = names.map do |name|
+          if Compiler::BUILTIN_NAMES.include?(name)
+            { name: name, status: :builtin, module: nil }
+          elsif @pack && resolves_in_pack?(name)
+            { name: name, status: :pack, module: find_pack_module(name) }
+          else
+            { name: name, status: :missing, module: nil }
+          end
+        end
+
+        pools = if @pack && !@pack.pools.empty?
+                  @pack.pools.sort_by { |name, _| name.to_s }.map { |name, pool| { name: name, count: pool.all.length } }
+                else
+                  []
+                end
+
+        { calls: calls, pools: pools }
+      end
+
+      def resolves_in_pack?(name)
+        return false unless @pack
+        @pack.step_modules.any? { |m| m.instance_methods.include?(name) } ||
+          @pack.mixin_modules.any? { |m| m.instance_methods.include?(name) }
+      end
+
+      def find_pack_module(name)
+        return "unknown" unless @pack
+        mod = (@pack.step_modules + @pack.mixin_modules).find { |m| m.instance_methods.include?(name) }
+        mod&.name || "anonymous"
+      end
+
+      def collect_all_call_names
+        names = []
+        @ast[:stages].each do |stage|
+          stage[:steps].each do |step|
+            collect_step_names(step, names)
+          end
+        end
+        names
+      end
+
+      def collect_step_names(step, names)
+        case step[:type]
+        when :call
+          names << step[:name]
+        when :when
+          step[:then].each { |c| collect_step_names(c, names) }
+          (step[:else] || []).each { |c| collect_step_names(c, names) }
+        when :maybe
+          step[:then].each { |c| collect_step_names(c, names) }
+        end
+      end
+
+      # ── Shared value formatting (ported from ExplainRenderer) ──
+
+      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
+
+      # ── Text formatter (byte-identical to the pre-refactor AuditRenderer) ──
+
+      class TextFormatter
+        def self.render(report)
+          new(report).render
+        end
+
+        def initialize(report)
+          @report = report
+        end
+
+        def render
+          lines = []
+          lines.concat(@report[:tree_text].split("\n"))
+          lines << ""
+          lines.concat(section_b)
+          lines << ""
+          lines.concat(section_c)
+          lines << ""
+          lines.concat(section_d)
+          lines << ""
+          lines.concat(section_e)
+          lines.join("\n") + "\n"
+        end
+
+        private
+
+        def section_b
+          lines = ["## Branch weights"]
+          any = false
+
+          @report[:branches].each do |b|
+            any = true
+            lines << ""
+            lines << "Stage: #{b[:stage]}"
+            max_label = b[:labels].map { |l| l[:label].to_s.length }.max
+            max_weight = b[:labels].map { |l| l[:weight] }.max
+            b[:labels].each do |l|
+              lines << "  %-#{max_label}s  %.2f  %s" % [l[:label], l[:weight], bar_for(l[:weight], max_weight)]
+            end
+          end
+
+          conditionals = @report[:conditionals]
+          unless conditionals.empty?
+            any = true
+            lines << ""
+            lines << "Conditionals:"
+            conditionals.each { |c| lines << "  #{c}" }
+          end
+
+          lines << "" unless any
+          lines << "  (no branches or conditionals)" unless any
+          lines
+        end
+
+        def bar_for(weight, max_weight)
+          scale = (weight.to_f / max_weight * 20).round
+          "█" * scale
+        end
+
+        def section_c
+          lines = ["## Path enumeration"]
+          paths = @report[:paths]
+
+          if @report[:paths_truncated]
+            lines << ""
+            lines << "  ⚠ #{@report[:paths_total]} paths total (showing first #{@report[:max_paths]})"
+            paths = paths.first(@report[:max_paths])
+          end
+
+          paths.each_with_index do |path, idx|
+            lines << ""
+            label = path[:branches].empty? ? "(linear)" : path[:branches].join(" → ")
+            lines << "Path #{idx + 1}: #{label}"
+            path[:steps].each_with_index do |step, s_idx|
+              lines << "  #{s_idx + 1}. #{step}"
+            end
+            lines << "  Terminal: #{path[:terminal]}"
+          end
+
+          lines
+        end
+
+        def section_d
+          lines = ["## Coverage gaps"]
+          gaps = @report[:gaps]
+
+          if gaps.empty?
+            lines << ""
+            lines << "  (no gaps detected)"
+          else
+            gaps.each { |g| lines << "  ⚠ #{g}" }
+          end
+
+          lines
+        end
+
+        def section_e
+          lines = ["## Step resolution"]
+          calls = @report[:resolution][:calls]
+
+          if calls.empty?
+            lines << ""
+            lines << "  (no calls)"
+            return lines
+          end
+
+          max_name = calls.map { |c| c[:name].to_s.length }.max
+          calls.each do |c|
+            case c[:status]
+            when :builtin
+              lines << "  %-#{max_name}s  ✓ builtin" % c[:name]
+            when :pack
+              lines << "  %-#{max_name}s  ✓ pack (%s)" % [c[:name], c[:module]]
+            else
+              lines << "  %-#{max_name}s  ✗ missing" % c[:name]
+            end
+          end
+
+          pools = @report[:resolution][:pools]
+          if pools.any?
+            lines << ""
+            lines << "Pools:"
+            pools.each { |p| lines << "  #{p[:name]} (#{p[:count]} entries)" }
+          end
+
+          lines
+        end
+      end
+
+      # ── Markdown formatter ──
+
+      class MarkdownFormatter
+        def self.render(report)
+          new(report).render
+        end
+
+        def initialize(report)
+          @report = report
+        end
+
+        def render
+          lines = []
+          s = @report[:scenario]
+
+          lines << "# Scenario: #{s[:name]}"
+          lines << ""
+          lines << "**Title:** #{s[:title]}"
+          lines << "**Stages:** #{s[:stages].join(' → ')}"
+          lines << "**Resumes:** #{render_resume(s[:resume])}"
+          lines << "**Delays:** #{s[:delays].join(', ')}"
+          lines << ""
+
+          @report[:tree].each do |stage|
+            lines << "## Stage: #{stage[:stage]}"
+            lines << ""
+            stage[:nodes].each do |node|
+              lines.concat(md_node(node, 0))
+            end
+            lines << ""
+          end
+
+          lines.concat(section_b)
+          lines << ""
+          lines.concat(section_c)
+          lines << ""
+          lines.concat(section_d)
+          lines << ""
+          lines.concat(section_e)
+
+          lines.join("\n") + "\n"
+        end
+
+        private
+
+        def render_resume(resume)
+          resume ? "after_await → #{resume[:after_await]}" : "-"
+        end
+
+        def md_node(node, indent)
+          pad = "  " * indent
+          case node[:type]
+          when :call
+            md_call(node, pad)
+          when :when
+            md_when(node, indent)
+          when :maybe
+            md_maybe(node, indent)
+          when :merge
+            ["#{pad}- *↓ all branches merge*"]
+          else
+            []
+          end
+        end
+
+        def md_call(node, pad)
+          parts = ["`#{node[:name]}`"]
+          if node[:when_branch]
+            parts << "· **branch:** #{node[:when_branch]}(#{node[:branch_weight]})"
+          end
+          parts << "· → out: `#{node[:out]}`" if node[:out]
+          parts << "(with wrong_part)" if node[:with_wrong_part]
+
+          lines = ["#{pad}- #{parts.join(' ')}"]
+          if node[:with_lines].any?
+            child_pad = pad + "  "
+            node[:with_lines].each { |wl| lines << "#{child_pad}- `#{wl}`" }
+          end
+          lines
+        end
+
+        def md_when(node, indent)
+          pad = "  " * indent
+          child = indent + 1
+          lines = ["#{pad}- **when** `#{node[:expr]}`"]
+          if node[:then_nodes].any?
+            lines << "#{pad}  - **then:**"
+            node[:then_nodes].each { |c| lines.concat(md_node(c, child + 1)) }
+          end
+          if node[:else_nodes].any?
+            lines << "#{pad}  - **else:**"
+            node[:else_nodes].each { |c| lines.concat(md_node(c, child + 1)) }
+          end
+          lines
+        end
+
+        def md_maybe(node, indent)
+          pad = "  " * indent
+          lines = ["#{pad}- **maybe** #{node[:prob]}"]
+          node[:then_nodes].each { |c| lines.concat(md_node(c, indent + 1)) }
+          lines
+        end
+
+        def section_b
+          lines = ["## Branch weights"]
+          branches = @report[:branches]
+          conditionals = @report[:conditionals]
+
+          if branches.empty? && conditionals.empty?
+            lines << ""
+            lines << "*No branches or conditionals.*"
+            return lines
+          end
+
+          if branches.any?
+            lines << ""
+            lines << "| Stage | Label | Weight | Bar |"
+            lines << "|-------|-------|--------|-----|"
+            branches.each do |b|
+              max_weight = b[:labels].map { |l| l[:weight] }.max
+              b[:labels].each do |l|
+                scale = (l[:weight].to_f / max_weight * 20).round
+                lines << "| #{b[:stage]} | #{l[:label]} | #{l[:weight]} | #{"█" * scale} |"
+              end
+            end
+          end
+
+          unless conditionals.empty?
+            lines << ""
+            lines << "**Conditionals:**"
+            conditionals.each { |c| lines << "- `#{c}`" }
+          end
+
+          lines
+        end
+
+        def section_c
+          lines = ["## Path enumeration"]
+          paths = @report[:paths]
+
+          if @report[:paths_truncated]
+            lines << ""
+            lines << "> ⚠ #{@report[:paths_total]} paths total (showing first #{@report[:max_paths]})"
+            paths = paths.first(@report[:max_paths])
+          end
+
+          paths.each_with_index do |path, idx|
+            lines << ""
+            label = path[:branches].empty? ? "(linear)" : path[:branches].join(" → ")
+            lines << "### Path #{idx + 1}: #{label}"
+            path[:steps].each_with_index do |step, s_idx|
+              lines << "#{s_idx + 1}. `#{step}`"
+            end
+            lines << ""
+            lines << "**Terminal:** #{path[:terminal]}"
+          end
+
+          lines
+        end
+
+        def section_d
+          lines = ["## Coverage gaps"]
+          gaps = @report[:gaps]
+
+          if gaps.empty?
+            lines << ""
+            lines << "**No gaps detected.**"
+          else
+            gaps.each { |g| lines << "- ⚠ #{g}" }
+          end
+
+          lines
+        end
+
+        def section_e
+          lines = ["## Step resolution"]
+          calls = @report[:resolution][:calls]
+
+          if calls.empty?
+            lines << ""
+            lines << "*No calls.*"
+            return lines
+          end
+
+          lines << ""
+          lines << "| Call | Status | Module |"
+          lines << "|------|--------|--------|"
+          calls.each do |c|
+            status = case c[:status]
+                     when :builtin then "✓ builtin"
+                     when :pack then "✓ pack"
+                     else "✗ missing"
+                     end
+            mod = c[:module] || ""
+            lines << "| `#{c[:name]}` | #{status} | #{mod} |"
+          end
+
+          pools = @report[:resolution][:pools]
+          if pools.any?
+            lines << ""
+            lines << "**Pools:**"
+            pools.each { |p| lines << "- `#{p[:name]}` (#{p[:count]} entries)" }
+          end
+
+          lines
+        end
+      end
+
+      # ── JSON formatter ──
+
+      class JsonFormatter
+        def self.render(report)
+          JSON.pretty_generate(serialize(report)) + "\n"
+        end
+
+        def self.serialize(obj)
+          case obj
+          when Symbol then { "__sym__" => obj.to_s }
+          when Hash then obj.transform_keys(&:to_s).transform_values { |v| serialize(v) }
+          when Array then obj.map { |v| serialize(v) }
+          else obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dogfood/dsl/compiler.rb

@@ -74,7 +74,11 @@ module Dogfood
             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]
+            if @rng.rand < step_spec[:prob]
+              step_spec[:then].each { |c| run_step(c, nil) }
+            else
+              step_spec[:else].each { |c| run_step(c, nil) }
+            end
           end
         end
 
@@ -166,7 +170,8 @@ module Dogfood
           {
             type: :maybe,
             prob: step["maybe"],
-            then: step["then"].map { |c| parse_call(c, stage) }
+            then: step["then"].map { |c| parse_call(c, stage) },
+            else: step["else"] ? step["else"].map { |c| parse_call(c, stage) } : []
           }
         else
           raise Dogfood::NestingTooDeep, "invalid step in stage #{stage}"
@@ -197,7 +202,8 @@ module Dogfood
           {
             type: :maybe,
             prob: step["maybe"],
-            then: step["then"].map { |c| parse_call(c, stage) }
+            then: step["then"].map { |c| parse_call(c, stage) },
+            else: step["else"] ? step["else"].map { |c| parse_call(c, stage) } : []
           }
         else
           parse_call(step, stage)
@@ -234,7 +240,7 @@ module Dogfood
           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] }
+          when :maybe then collect_block_names(step[:then]) + collect_block_names(step[:else])
           else []
           end
         end
@@ -243,7 +249,7 @@ module Dogfood
       def self.collect_block_names(steps)
         steps.flat_map do |step|
           if step[:type] == :maybe
-            step[:then].map { |c| c[:name] }
+            collect_block_names(step[:then]) + collect_block_names(step[:else])
           else
             [step[:name]]
           end

data/lib/dogfood/dsl/schema.rb

@@ -113,6 +113,9 @@ module Dogfood
           end
           require_then_block!(step, stage, idx, "maybe")
           validate_flat_block!(step["then"], stage, idx, "then")
+          if step.key?("else")
+            validate_flat_block!(step["else"], stage, idx, "else")
+          end
         end
 
         def require_then_block!(step, stage, idx, kind)

data/lib/dogfood/story_base.rb

@@ -29,6 +29,12 @@ module Dogfood
       raise NotImplementedError
     end
 
+    def money(cents)
+      return "$0" if cents.nil? || cents == 0
+      dollars = (cents / 100.0).round
+      "$#{dollars.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}"
+    end
+
     protected
 
     def step(actor:, event:, action:, notes: nil)

data/lib/dogfood/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dogfood
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/dogfood.rb

@@ -18,6 +18,7 @@ require_relative "dogfood/dsl/schema"
 require_relative "dogfood/dsl/pool_schema"
 require_relative "dogfood/dsl/compiler"
 require_relative "dogfood/dsl/explain_renderer"
+require_relative "dogfood/dsl/audit_report"
 require_relative "dogfood/dsl/audit_renderer"
 require_relative "dogfood/test/smoke"
 require_relative "dogfood/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dogfood
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Ben D'Angelo
@@ -80,6 +80,7 @@ files:
 - lib/dogfood/cli.rb
 - lib/dogfood/day_generator.rb
 - lib/dogfood/dsl/audit_renderer.rb
+- lib/dogfood/dsl/audit_report.rb
 - lib/dogfood/dsl/compiler.rb
 - lib/dogfood/dsl/evaluator.rb
 - lib/dogfood/dsl/explain_renderer.rb