breadkit 0.1.0 → 0.2.0

data/lib/breadkit/dc_analysis.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "matrix"
+
+module Breadkit
+  DCResult = Struct.new(:status, :voltages, :currents, :power, :floating, :reference_nodes,
+                        :assumptions, :errors, keyword_init: true) do
+    def success?
+      status == :ok
+    end
+  end
+
+  class Circuit
+    def dc_analysis(state = nil)
+      DCAnalysis.new(self).solve(state)
+    end
+  end
+
+  # DC model: ideal voltage sources and switches, ohmic resistors, and fixed-drop diodes.
+  # Capacitors are open at DC. Voltage in an ungrounded domain is relative to its
+  # reported reference node; it has no absolute meaning against another domain.
+  class DCAnalysis
+    DIODE_MODELS = { "led" => [2.0, 1.0], "diode" => [0.7, 1.0] }.freeze
+    MAX_ITERATIONS = 32
+
+    def initialize(circuit)
+      @circuit = circuit
+    end
+
+    def solve(state = nil)
+      return failure(:invalid, "circuit has errors") if circuit.diagnostics.any? { |item| item.severity == "error" }
+
+      @state = state
+      @sources, @resistors, @diodes, unsupported = [], [], [], []
+      ground_labels = Array(circuit.board.definition.data["ground_labels"] || %w[GND 0V VSS GROUND]).map(&:upcase)
+      @ground_names = circuit.nets(state).select do |net|
+        net.labels.any? { |label| ground_labels.include?(label.upcase) }
+      end.map(&:name)
+      collect_sources
+      circuit.components.each_value { |component| collect_component(component, unsupported) }
+      return failure(:unsupported, "no DC model for #{unsupported.join(', ')}") unless unsupported.empty?
+
+      active = Array.new(@diodes.length, true)
+      seen = {}
+      MAX_ITERATIONS.times do
+        key = active.join
+        return failure(:nonconvergent, "diode states did not converge") if seen[key]
+
+        seen[key] = true
+        solved = solve_linear(active)
+        return solved if solved.is_a?(DCResult)
+
+        voltages, source_currents, references, floating = solved
+        next_active = @diodes.map do |diode|
+          anode, cathode, drop, resistance = diode.values_at(:anode, :cathode, :drop, :resistance)
+          voltages.fetch(anode) - voltages.fetch(cathode) > drop - 1e-9 &&
+            (voltages.fetch(anode) - voltages.fetch(cathode) - drop) / resistance >= -1e-9
+        end
+        if active == next_active
+          if (bridge = unreturned_diode(active))
+            return failure(:indeterminate, "#{bridge} has no return path; its DC bias is undefined")
+          end
+
+          currents = source_currents.dup
+          power = {}
+          @resistors.each do |resistor|
+            current = resistor[:ohms].zero? ? source_currents.fetch(resistor[:name]) :
+                      (voltages.fetch(resistor[:a]) - voltages.fetch(resistor[:b])) / resistor[:ohms]
+            currents[resistor[:name]] = current
+            power[resistor[:name]] = current * current * resistor[:ohms]
+          end
+          @diodes.each_with_index do |diode, index|
+            current = active[index] ? (voltages.fetch(diode[:anode]) - voltages.fetch(diode[:cathode]) - diode[:drop]) / diode[:resistance] : 0.0
+            currents[diode[:name]] = current
+          end
+          return DCResult.new(status: :ok, voltages: voltages, currents: currents, power: power,
+                              floating: floating, reference_nodes: references, assumptions: assumptions, errors: [])
+        end
+        active = next_active
+      end
+      failure(:nonconvergent, "diode states did not converge")
+    rescue ArgumentError, TypeError, KeyError => error
+      failure(:invalid, error.message)
+    end
+
+    private
+
+    attr_reader :circuit
+
+    def failure(status, message)
+      DCResult.new(status: status, voltages: {}, currents: {}, power: {}, floating: [],
+                   reference_nodes: [], assumptions: assumptions, errors: [message])
+    end
+
+    def assumptions
+      @sources.to_a.filter_map do |source|
+        next unless source[:range]
+
+        "#{source[:name]}: nominal #{source[:volts]} V from #{source[:range].join('..')} V range"
+      end + @diodes.to_a.map do |diode|
+        "#{diode[:name]}: fixed #{diode[:drop]} V forward drop, #{diode[:resistance]} Ω on resistance"
+      end
+    end
+
+    def net_name(reference)
+      circuit.net_of(reference, @state)&.name || (raise ArgumentError, "unresolved terminal #{reference}")
+    end
+
+    def collect_sources
+      circuit.voltage_sources.each do |source|
+        voltage = source.voltage.to_f
+        raise ArgumentError, "invalid voltage source #{source.name}" unless voltage.finite? && voltage.positive?
+
+        @sources << { name: source.name, a: net_name(source.plus), b: net_name(source.minus), volts: voltage,
+                      range: source.voltage_range }
+      end
+    end
+
+    def collect_component(component, unsupported)
+      part = component.part
+      case part.id
+      when "resistor"
+        value = Value.parse(component.value)
+        raise ArgumentError, "invalid resistance #{component.ref}" unless value.finite? && value >= 0
+
+        @resistors << { name: component.ref, a: net_name("#{component.ref}.1"), b: net_name("#{component.ref}.2"), ohms: value }
+      when "led", "diode"
+        default_drop, default_resistance = DIODE_MODELS.fetch(part.id)
+        drop = part.data.fetch("forward_voltage", default_drop).to_f
+        resistance = part.data.fetch("on_resistance", default_resistance).to_f
+        polarity = part.data.fetch("polarity")
+        @diodes << { name: component.ref, anode: net_name("#{component.ref}.#{polarity.fetch('positive')}"),
+                     cathode: net_name("#{component.ref}.#{polarity.fetch('negative')}"),
+                     drop: drop, resistance: resistance }
+      when "capacitor", "electrolytic", "pin_header", "battery_box", "dc_jack_2wire"
+        nil
+      else
+        return if part.data["switch"]
+        if part.data["provides"]
+          provided_outputs = Array(part.data["provides"]).filter_map { |source| part.pin(source["positive"]) }
+          driven = component.pins.values.any? do |pin|
+            definition = part.pin(pin.number)
+            next unless %w[gpio output].include?(pin.role) || definition&.fetch("output_capable", false)
+            next if provided_outputs.include?(definition)
+
+            net = circuit.net_of("#{component.ref}.#{pin.name}", @state)
+            net&.members&.any? { |member| member != "#{component.ref}.#{pin.name}" }
+          end
+          unsupported << "#{component.ref} output state" if driven
+          return
+        end
+
+        unsupported << component.ref
+      end
+    end
+
+    def solve_linear(active)
+      nodes = (@sources.flat_map { |item| [item[:a], item[:b]] } +
+               @resistors.flat_map { |item| [item[:a], item[:b]] } +
+               @diodes.flat_map { |item| [item[:anode], item[:cathode]] }).uniq
+      links = @sources.map { |item| [item[:a], item[:b]] } +
+              @resistors.map { |item| [item[:a], item[:b]] } +
+              @diodes.each_with_index.filter_map { |item, index| [item[:anode], item[:cathode]] if active[index] }
+      groups = connected_groups(nodes, links)
+      group_of = groups.each_with_index.each_with_object({}) { |(group, index), result| group.each { |node| result[node] = index } }
+      @diodes.each_with_index do |diode, index|
+        next if active[index] || group_of[diode[:anode]] == group_of[diode[:cathode]]
+
+        return failure(:indeterminate, "#{diode[:name]} bridges independent DC domains while off")
+      end
+      references = groups.map { |group| reference_for(group) }
+      floating = groups.reject { |group| group.any? { |name| ground?(name) } }
+      variables = nodes - references
+      index = variables.each_with_index.to_h
+      ideal = @sources + @resistors.select { |item| item[:ohms].zero? }.map { |item| item.merge(volts: 0.0) }
+      size = variables.length + ideal.length
+      matrix = Array.new(size) { Array.new(size, 0.0) }
+      rhs = Array.new(size, 0.0)
+      @resistors.each { |item| stamp_conductance(matrix, index, item[:a], item[:b], 1.0 / item[:ohms]) unless item[:ohms].zero? }
+      @diodes.each_with_index do |item, position|
+        next unless active[position]
+
+        conductance = 1.0 / item[:resistance]
+        stamp_conductance(matrix, index, item[:anode], item[:cathode], conductance)
+        rhs[index.fetch(item[:anode])] += conductance * item[:drop] if index.key?(item[:anode])
+        rhs[index.fetch(item[:cathode])] -= conductance * item[:drop] if index.key?(item[:cathode])
+      end
+      ideal.each_with_index do |item, position|
+        row = variables.length + position
+        [[item[:a], 1.0], [item[:b], -1.0]].each do |node, sign|
+          next unless index.key?(node)
+
+          matrix[index.fetch(node)][row] += sign
+          matrix[row][index.fetch(node)] += sign
+        end
+        rhs[row] = item[:volts]
+      end
+      solution = size.zero? ? [] : Matrix.rows(matrix).lup.solve(Vector.elements(rhs)).to_a
+      return failure(:singular, "DC equations are inconsistent or underdetermined") unless valid_solution?(matrix, rhs, solution)
+
+      voltages = nodes.to_h { |node| [node, index.key?(node) ? solution.fetch(index.fetch(node)) : 0.0] }
+      currents = ideal.each_with_index.to_h { |item, position| [item[:name], solution.fetch(variables.length + position)] }
+      [voltages, currents, references, floating]
+    rescue ExceptionForMatrix::ErrNotRegular
+      failure(:singular, "DC equations are inconsistent or underdetermined")
+    end
+
+    def stamp_conductance(matrix, index, a, b, conductance)
+      return if a == b
+
+      if index.key?(a)
+        row = index.fetch(a)
+        matrix[row][row] += conductance
+        matrix[row][index.fetch(b)] -= conductance if index.key?(b)
+      end
+      if index.key?(b)
+        row = index.fetch(b)
+        matrix[row][row] += conductance
+        matrix[row][index.fetch(a)] -= conductance if index.key?(a)
+      end
+    end
+
+    def connected_groups(nodes, links)
+      union = UnionFind.new
+      nodes.each { |node| union.add(node) }
+      links.each { |a, b| union.union(a, b) }
+      nodes.group_by { |node| union.find(node) }.values
+    end
+
+    def unreturned_diode(active)
+      base = @sources.map { |item| [item[:a], item[:b]] } + @resistors.map { |item| [item[:a], item[:b]] }
+      @diodes.each_with_index do |diode, index|
+        next unless active[index]
+
+        union = UnionFind.new
+        (base + @diodes.each_with_index.filter_map do |other, other_index|
+          [other[:anode], other[:cathode]] if active[other_index] && other_index != index
+        end).each { |a, b| union.union(a, b) }
+        return diode[:name] unless union.find(diode[:anode]) == union.find(diode[:cathode])
+      end
+      nil
+    end
+
+    def reference_for(group)
+      group.find { |name| ground?(name) } || @sources.lazy.map { |source| source[:b] }.find { |name| group.include?(name) } || group.first
+    end
+
+    def ground?(name)
+      @ground_names.include?(name)
+    end
+
+    def valid_solution?(matrix, rhs, solution)
+      return false unless solution.all?(&:finite?)
+
+      matrix.each_with_index.all? do |row, index|
+        result = row.zip(solution).sum { |coefficient, value| coefficient * value }
+        (result - rhs.fetch(index)).abs <= 1e-7 * [rhs.fetch(index).abs, result.abs, 1.0].max
+      end
+    end
+  end
+end

data/lib/breadkit/dsl.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Breadkit
   module DSL
-    METHODS = %w[title board use_parts use_boards supply net part wire offboard expect lint_disable resistor capacitor electrolytic diode led transistor pot button ic connected isolated].freeze
+    METHODS = %w[title board use_parts use_boards include block use_block bus step supply net part wire connect offboard expect expect_voltage expect_current lint_disable resistor capacitor electrolytic diode led transistor pot button ic connected isolated].freeze
 
     class Builder
       attr_reader :document
@@ -11,35 +13,151 @@ module Breadkit
         @document = Document.new
         @expected = nil
         @base_dir = base_dir
+        @include_stack = []
+        @blocks = {}
+        @active_blocks = []
+        @current_step = nil
       end
 
       def title(value)
         document.title = value.to_s
       end
 
-      def board(type, **options)
-        raise DSLError, "board may only be declared once" if @board_declared
+      def board(type, as: nil, **options)
         unknown = options.keys - [:split_rails]
         raise DSLError, "unknown board option #{unknown.first}" unless unknown.empty?
         if options.key?(:split_rails) && ![true, false].include?(options[:split_rails])
           raise DSLError, "split_rails must be boolean"
         end
 
-        @board_declared = true
-        document.board = { type: type.to_s, options: options }
+        if as
+          raise DSLError, "named and unnamed boards cannot be mixed" if @board_declared
+          name = helper_name(as, "board")
+          if document.boards.any? { |item| item[:name].casecmp?(name) }
+            raise DSLError, "duplicate board name #{name}"
+          end
+          document.boards << { name: name, type: type.to_s, options: options }
+        else
+          raise DSLError, "named and unnamed boards cannot be mixed" unless document.boards.empty?
+          raise DSLError, "board may only be declared once" if @board_declared
+
+          @board_declared = true
+          document.board = { type: type.to_s, options: options }
+        end
       end
 
       def use_parts(path)
-        document.part_paths.concat(Dir.glob(resolve_path(path)))
+        matches = Dir.glob(resolve_path(path))
+        document.diagnostics << Diagnostic.new(code: "unmatched_parts", severity: "warning",
+                                               message: "no part definitions match #{path}", location: source_location,
+                                               targets: []) if matches.empty?
+        document.part_paths.concat(matches)
       end
 
       def use_boards(path)
         document.board_paths.concat(Dir.glob(resolve_path(path)))
       end
 
-      def supply(name, voltage:, plus:, minus:)
-        document.supplies << { name: name.to_s, voltage: Value.parse(voltage), plus: plus.to_s,
-                               minus: minus.to_s, location: source_location }
+      def include(path)
+        absolute = resolve_path(path)
+        raise DSLError.new("circular include: #{absolute}", location: source_location) if @include_stack.include?(absolute)
+
+        previous_dir = @base_dir
+        @include_stack << absolute
+        @base_dir = File.dirname(absolute)
+        instance_eval(File.read(absolute, encoding: "UTF-8"), absolute, 1)
+      rescue DSLError, ScriptError => e
+        frame = e.backtrace_locations&.find { |item| item.path == absolute }
+        location = e.respond_to?(:location) && e.location || SourceLocation.new(path: absolute, line: frame&.lineno)
+        raise DSLError.new(e.message, location: location)
+      ensure
+        if previous_dir
+          @base_dir = previous_dir
+          @include_stack.pop
+        end
+      end
+
+      def block(name, &body)
+        key = helper_name(name, "block")
+        raise DSLError, "block #{key} requires a body" unless body
+        raise DSLError, "block #{key} is already defined" if @blocks.key?(key)
+
+        @blocks[key] = body
+      end
+
+      def use_block(name, *args, **kwargs)
+        active = false
+        key = helper_name(name, "block")
+        body = @blocks[key]
+        raise DSLError, "unknown block #{key}" unless body
+        raise DSLError, "recursive block #{key}" if @active_blocks.include?(key)
+
+        @active_blocks << key
+        active = true
+        instance_exec(*args, **kwargs, &body)
+      ensure
+        @active_blocks.pop if active
+      end
+
+      def bus(name, **lines)
+        prefix = helper_name(name, "bus").upcase
+        raise DSLError, "bus #{prefix} must declare at least one line" if lines.empty?
+        raise DSLError, "bus cannot be declared inside expect" if @expected
+
+        labels = {}
+        lines.each do |line, reference|
+          key = helper_name(line, "bus line").upcase
+          raise DSLError, "duplicate bus line #{key}" if labels.key?(key)
+          raise DSLError, "bus line #{key} reference must be text" unless reference.is_a?(String) && !reference.empty?
+
+          labels[key] = reference
+        end
+        labels.each { |line, reference| net "#{prefix}_#{line}", at: reference }
+      end
+
+      def step(number, title: nil, &body)
+        active = false
+        raise DSLError, "nested step declarations are not allowed" if @current_step
+        expected = document.steps.length + 1
+        raise DSLError, "step number must be #{expected}" unless number.is_a?(Integer) && number == expected
+        raise DSLError, "step title must be nonempty text" unless title.nil? || (title.is_a?(String) && !title.empty?)
+        raise DSLError, "step #{number} requires a body" unless body
+
+        document.steps << { number: number, title: title, source: source_location }
+        @current_step = number
+        active = true
+        instance_eval(&body)
+      ensure
+        @current_step = nil if active
+      end
+
+      def supply(name = nil, voltage: nil, plus: nil, minus: nil, from: nil, isolated: false, current_limit: nil)
+        if from
+          raise DSLError, "supply from: cannot mix standalone supply options" if name || voltage || isolated != false || current_limit
+          raise DSLError, "supply from: requires plus and minus destinations" unless plus && minus
+          unless [from, plus, minus].all? { |value| value.is_a?(String) && !value.empty? }
+            raise DSLError, "supply from:, plus:, and minus: must be nonempty text"
+          end
+
+          document.wires << { supply_from: from, plus: plus, minus: minus,
+                              location: source_location, step: @current_step }
+          return
+        end
+
+        raise DSLError, "supply requires name, voltage, plus, and minus" unless name && voltage && plus && minus
+
+        range = voltage.is_a?(Range) ? [Value.parse(voltage.begin), Value.parse(voltage.end)] : nil
+        raise DSLError, "supply voltage range must be inclusive and ascending" if range && (voltage.exclude_end? || range[0] > range[1])
+        parsed = range ? (range[0] + range[1]) / 2.0 : Value.parse(voltage)
+        raise DSLError, "supply voltage must be positive" unless parsed.finite? && parsed.positive?
+        raise DSLError, "supply voltage range must be positive" if range && range.any? { |value| !value.finite? || !value.positive? }
+        raise DSLError, "isolated must be boolean" unless [true, false].include?(isolated)
+        if !current_limit.nil? && (!current_limit.is_a?(Numeric) || !current_limit.real? || !current_limit.finite? || !current_limit.positive?)
+          raise DSLError, "current_limit must be a positive current in amperes"
+        end
+        document.supplies << { name: name.to_s, voltage: parsed, plus: plus.to_s,
+                               minus: minus.to_s, isolated: isolated, voltage_range: range,
+                               current_limit: current_limit, location: source_location, step: @current_step }
       end
 
       def net(name, *refs, at: nil, **options)
@@ -48,16 +166,18 @@ module Breadkit
         else
           raise DSLError, "net requires at: outside expect" if at.nil? || !refs.empty? || !options.empty?
 
-          document.labels << { name: name.to_s, at: at.to_s, location: source_location }
+          document.labels << { name: name.to_s, at: at.to_s, location: source_location, step: @current_step }
         end
       end
 
       def part(ref, type, value = nil, pins: nil, at: nil, **attrs)
-        unsupported = attrs.keys.find { |key| %i[rotate wire_layer].include?(key.to_sym) }
+        unsupported = attrs.keys.find { |key| key.to_sym == :wire_layer }
         raise DSLError, "unsupported component option #{unsupported}" if unsupported
+        raise DSLError, "rotate must be 0, 90, 180, or 270" if attrs.key?(:rotate) && ![0, 90, 180, 270].include?(attrs[:rotate])
+        raise DSLError, "mirror must be boolean" if attrs.key?(:mirror) && ![true, false].include?(attrs[:mirror])
 
         document.components << { ref: ref.to_s, type: type.to_s, value: value, pins: pins, at: at,
-                                 attrs: attrs, unused: Array(attrs.delete(:unused)), location: source_location }
+                                 attrs: attrs, unused: Array(attrs.delete(:unused)), location: source_location, step: @current_step }
       end
 
       def resistor(ref, value, **options)
@@ -99,24 +219,31 @@ module Breadkit
       def wire(from, to, color: nil, id: nil, route: :straight, layer: nil, electrical: true, dashed: false)
         document.wires << { id: id&.to_s, from: from.to_s, to: to.to_s, color: color&.to_s,
                             route: route.to_s, layer: layer_names(layer), electrical: electrical != false,
-                            dashed: !!dashed, location: source_location }
+                            dashed: !!dashed, location: source_location, step: @current_step }
       end
 
       def offboard(name, type, side: :left, at: nil, unused: [], **attrs)
-        unsupported = attrs.keys.find { |key| %i[rotate wire_layer].include?(key.to_sym) }
+        unsupported = attrs.keys.find { |key| %i[rotate mirror wire_layer].include?(key.to_sym) }
         raise DSLError, "unsupported component option #{unsupported}" if unsupported
 
         attrs[:at] = at if at
         document.components << { ref: name.to_s, type: type.to_s, attrs: attrs.merge(side: side.to_s),
-                                 pins: nil, unused: Array(unused), location: source_location, offboard: true }
+                                 pins: nil, unused: Array(unused), location: source_location, offboard: true,
+                                 step: @current_step }
       end
 
-      def expect(strict: false, &block)
+      def expect(strict: false, **options, &block)
+        unknown = options.keys - [:when]
+        raise DSLError, "unknown expect option #{unknown.first}" unless unknown.empty?
+        at_state = options[:when]&.to_s
+        raise DSLError, "expect when: must name a switch state" if options.key?(:when) && at_state.to_s.empty?
         entries = []
         previous = @expected
         @expected = entries
         instance_eval(&block)
-        document.expectations << { strict: strict, entries: entries, location: source_location }
+        expectation = { strict: strict, entries: entries, location: source_location }
+        expectation[:when] = at_state if at_state
+        document.expectations << expectation
       ensure
         @expected = previous
       end
@@ -127,12 +254,36 @@ module Breadkit
         @expected << { kind: "connected", refs: refs.map(&:to_s), location: source_location }
       end
 
+      def connect(*refs, **options)
+        raise DSLError, "connect is an intent assertion; use connected inside expect" if @expected
+        raise DSLError, "connect requires exactly two references and does not place a wire" unless refs.length == 2
+        raise DSLError, "connect references must be nonempty text" unless refs.all? { |ref| (ref.is_a?(String) || ref.is_a?(Symbol)) && !ref.to_s.empty? }
+        unknown = options.keys - [:when]
+        raise DSLError, "unknown connect option #{unknown.first}" unless unknown.empty?
+
+        at_state = options[:when]&.to_s
+        raise DSLError, "connect when: must name a switch state" if options.key?(:when) && at_state.to_s.empty?
+
+        location = source_location
+        expectation = { strict: false, entries: [{ kind: "connected", refs: refs.map(&:to_s), location: location }], location: location }
+        expectation[:when] = at_state if at_state
+        document.expectations << expectation
+      end
+
       def isolated(*refs)
         raise DSLError, "isolated must be inside expect" unless @expected
 
         @expected << { kind: "isolated", refs: refs.map(&:to_s), location: source_location }
       end
 
+      def expect_voltage(reference, range)
+        measurement_expectation("voltage", reference, range)
+      end
+
+      def expect_current(reference, range)
+        measurement_expectation("current", reference, range)
+      end
+
       def lint_disable(rule_id, on: nil, reason: nil)
         document.lint_disables << { rule: rule_id.to_s, on: on&.to_s, reason: reason, location: source_location }
       end
@@ -149,6 +300,29 @@ module Breadkit
 
       private
 
+      def helper_name(value, kind)
+        name = value.to_s
+        raise DSLError, "invalid #{kind} name #{name.inspect}" unless value.is_a?(String) || value.is_a?(Symbol)
+        raise DSLError, "invalid #{kind} name #{name.inspect}" unless /\A[A-Za-z][A-Za-z0-9_]*\z/.match?(name)
+
+        name
+      end
+
+      def measurement_expectation(kind, reference, range)
+        raise DSLError, "#{kind} expectation requires an inclusive range" unless range.is_a?(Range) && !range.exclude_end?
+
+        limits = [Value.parse(range.begin), Value.parse(range.end)]
+        raise DSLError, "#{kind} expectation range must be inclusive and ascending" unless limits.all?(&:finite?) && limits.first <= limits.last
+        raise DSLError, "current expectation cannot be negative" if kind == "current" && limits.first.negative?
+
+        entry = { kind: kind, refs: [reference.to_s], range: limits, location: source_location }
+        if @expected
+          @expected << entry
+        else
+          document.expectations << { strict: false, entries: [entry], location: source_location }
+        end
+      end
+
       def source_location
         loc = caller_locations(2, 12).find { |item| item.path && File.expand_path(item.path) != __FILE__ }
         SourceLocation.new(path: loc&.path, line: loc&.lineno)
@@ -166,17 +340,24 @@ module Breadkit
       end
     end
 
-    def self.load_file(path)
+    def self.load_file(path, timeout: 10, source: nil)
+      raise ArgumentError, "timeout must be positive" unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
       absolute = File.expand_path(path)
       builder = Builder.new(base_dir: File.dirname(absolute))
-      builder.instance_eval(File.read(absolute, encoding: "UTF-8"), absolute, 1)
+      builder.document.source_root = File.dirname(absolute)
+      Timeout.timeout(timeout) { builder.instance_eval(source || File.read(absolute, encoding: "UTF-8"), absolute, 1) }
       builder.document
-    rescue DSLError
-      raise
-    rescue ScriptError, StandardError => e
+    rescue DSLError, ScriptError, StandardError, SystemExit, SystemStackError => e
       line = e.backtrace_locations&.find { |frame| frame.path == absolute }&.lineno
-      location = line ? "#{path}:#{line}" : path
-      raise DSLError, "#{location}: #{e.message}"
+      location = e.is_a?(DSLError) && e.location || SourceLocation.new(path: path, line: line)
+      detail = if e.is_a?(SystemExit)
+        "exit is not allowed in a circuit file"
+      elsif e.is_a?(Timeout::Error)
+        "circuit evaluation timed out after #{timeout} seconds"
+      else
+        e.message
+      end
+      raise DSLError.new("#{location.path}#{":#{location.line}" if location.line}: #{detail}", location: location)
     end
   end
 end