breadkit 0.1.0 → 0.2.0

data/lib/breadkit/rake_task.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../breadkit"
+require "rake"
+
+module Breadkit
+  class RakeTask
+    attr_reader :task
+
+    def initialize(name = :breadkit, files:)
+      raise ArgumentError, "RakeTask needs a task name" if name.to_s.empty?
+      raise ArgumentError, "RakeTask files must be a nonempty list of paths" unless files.is_a?(Array) && !files.empty? && files.all? { |path| path.is_a?(String) && !path.empty? }
+
+      @task = Rake::Task.define_task(name) do
+        files.each do |path|
+          circuit = Breadkit.load(path)
+          errors = circuit.diagnostics.select { |item| item.severity == "error" }
+          raise "#{path}: #{errors.map { |item| "#{item.code}: #{item.message}" }.join('; ')}" unless errors.empty?
+
+          puts "Checked #{path}"
+        end
+      end
+    end
+  end
+end

data/lib/breadkit/resolver.rb

@@ -4,19 +4,23 @@ module Breadkit
   class Resolver
     def call(document)
       @document = document
-      @diagnostics = []
+      @diagnostics = document.diagnostics.dup
       @board = load_board
       @terminal_positions = @board.holes.values.select { |hole| hole.kind == :terminal }.to_h { |hole| [[hole.x, hole.y], hole] }
       @library = PartLibrary.new(extra_paths: document.part_paths, extra_definitions: document.part_definitions)
+      @library.warnings.each { |message| @diagnostics << diagnostic(:part_override, "warning", message, nil) }
       components = resolve_components
+      @wire_items = expand_source_supplies(components)
       wires = resolve_wires(components)
       supplies = resolve_supplies
       validate_names(components, wires, supplies)
-      labels = document.labels.map { |item| Label.new(name: item[:name], at: item[:at], location: item[:location]) }
+      labels = document.labels.map { |item| Label.new(name: item[:name], at: item[:at], location: item[:location], step: item[:step]) }
       validate_references(components, supplies, labels)
       circuit = Circuit.new(title: document.title, board: @board, components: components, wires: wires,
                             supplies: supplies, labels: labels, expectations: document.expectations,
-                            lint_disables: document.lint_disables, diagnostics: @diagnostics)
+                            lint_disables: document.lint_disables, diagnostics: @diagnostics,
+                            steps: document.steps,
+                            source_root: document.source_root)
       validate_split_labels(circuit) if labels.length > 1
       circuit
     end
@@ -24,12 +28,34 @@ module Breadkit
     private
 
     def load_board
-      Board.new(BoardDef.load(@document.board[:type], extra_paths: @document.board_paths,
-                             extra_definitions: @document.board_definitions),
-                split_rails: @document.board[:options][:split_rails] || false)
-    rescue StandardError => e
-      @diagnostics << diagnostic(:unknown_board, "error", e.message, nil)
-      Board.new(BoardDef.load("full"))
+      unless @document.boards.empty?
+        names = {}
+        @document.boards.each do |item|
+          name = item[:name].to_s
+          raise DSLError, "invalid board name #{name.inspect}" unless /\A[A-Za-z][A-Za-z0-9_]*\z/.match?(name)
+          raise DSLError, "duplicate board name #{name}" if names[name.downcase]
+
+          names[name.downcase] = true
+        end
+        boards = @document.boards.to_h do |item|
+          definition = BoardDef.load(item[:type], extra_paths: @document.board_paths,
+                                     extra_definitions: @document.board_definitions)
+          [item[:name], Board.new(definition, split_rails: item[:options][:split_rails] || false)]
+        rescue StandardError => e
+          @diagnostics << diagnostic(:unknown_board, "error", e.message, nil)
+          [item[:name], Board.new(BoardDef.load("full"))]
+        end
+        return BoardSet.new(boards)
+      end
+
+      begin
+        Board.new(BoardDef.load(@document.board[:type], extra_paths: @document.board_paths,
+                               extra_definitions: @document.board_definitions),
+                  split_rails: @document.board[:options][:split_rails] || false)
+      rescue StandardError => e
+        @diagnostics << diagnostic(:unknown_board, "error", e.message, nil)
+        Board.new(BoardDef.load("full"))
+      end
     end
 
     def resolve_components
@@ -54,12 +80,58 @@ module Breadkit
           @diagnostics << diagnostic(:unknown_part, "error", "unknown part #{item[:type]}", item[:location], [ref])
           next
         end
+        if %w[resistor capacitor electrolytic pot].include?(part.id) && item[:value]
+          begin
+            value = Value.parse(item[:value])
+            raise ArgumentError unless value.finite? && value >= 0
+          rescue ArgumentError, TypeError
+            @diagnostics << diagnostic(:invalid_value, "error", "invalid #{part.id} value #{item[:value].inspect}", item[:location], [ref])
+          end
+        end
         pins = resolve_pins(item, part)
         result[ref] = Component.new(ref: ref, part: part, value: item[:value], attrs: item[:attrs] || {},
-                                    pins: pins, unused: Array(item[:unused]).map(&:to_s), location: item[:location])
+                                    pins: pins, unused: Array(item[:unused]).map(&:to_s), location: item[:location], step: item[:step])
       end
     end
 
+    def expand_source_supplies(components)
+      @document.wires.flat_map do |item|
+        next item unless item[:supply_from]
+
+        reference = item[:supply_from]
+        parsed = HoleId.parse(reference, board: @board)
+        component = components[parsed.ref] if parsed.kind == :pin
+        source_pin = component&.part&.pin(parsed.pin)
+        matches = if component&.part&.placement == "offboard" && source_pin
+          component.provided_sources.select do |entry|
+            component.part.pin(entry.fetch("positive"))["num"].to_s == source_pin["num"].to_s
+          end
+        else
+          []
+        end
+        if matches.empty?
+          @diagnostics << diagnostic(:unknown_supply_source, "error", "#{reference} is not a provided offboard power output", item[:location], [reference])
+          next []
+        end
+        if matches.length > 1
+          @diagnostics << diagnostic(:ambiguous_supply_source, "error", "#{reference} matches multiple provided power outputs", item[:location], [reference])
+          next []
+        end
+
+        source = matches.first
+        [source_wire(item, "#{parsed.ref}.#{source.fetch('positive')}", item[:plus]),
+         source_wire(item, "#{parsed.ref}.#{source.fetch('negative')}", item[:minus])]
+      rescue ArgumentError
+        @diagnostics << diagnostic(:unknown_supply_source, "error", "#{reference} is not a provided offboard power output", item[:location], [reference])
+        []
+      end
+    end
+
+    def source_wire(item, from, to)
+      { id: nil, from: from, to: to, color: nil, route: "straight", layer: nil,
+        electrical: true, dashed: false, location: item[:location], step: item[:step] }
+    end
+
     def resolve_pins(item, part)
       requested = item[:pins]
       result = {}
@@ -69,9 +141,27 @@ module Breadkit
         end
       end
       attrs = item[:attrs] || {}
+      Array(part.data["required_attributes"]).each do |name|
+        next if attrs.key?(name) || attrs.key?(name.to_sym)
+
+        @diagnostics << diagnostic(:invalid_option, "error", "missing required component option #{item[:ref]}.#{name}", item[:location], [item[:ref]])
+      end
+      if attrs.key?(:rotate) || attrs.key?(:mirror)
+        placement_error(item, "#{item[:ref]} orientation requires a footprint") unless part.placement == "footprint"
+      end
       pin_names = part.pins.flat_map { |pin| [pin["num"], pin["name"], *Array(pin["aliases"])] }.compact.map(&:to_s)
-      attrs.each_key do |key|
-        next if part.pin(key) || %w[pin_count color layer address label side at].include?(key.to_s)
+      attrs.each do |key, value|
+        if key.to_s == "color" && !Color.valid?(value)
+          @diagnostics << diagnostic(:invalid_color, "error", "invalid #{item[:ref]} color #{value.inspect}", item[:location], [item[:ref]])
+          next
+        end
+        schema = (part.data["attributes"] || {})[key.to_s]
+        if schema
+          valid = schema == "css_color" ? Color.valid?(value) : Array(schema).any? { |allowed| allowed.to_s == value.to_s }
+          @diagnostics << diagnostic(:invalid_option, "error", "invalid #{item[:ref]}.#{key}: #{value.inspect}", item[:location], [item[:ref]]) unless valid
+          next
+        end
+        next if part.pin(key) || %w[pin_count color layer address label side at rotate mirror].include?(key.to_s)
 
         suggestion = DidYouMean::SpellChecker.new(dictionary: pin_names).correct(key.to_s).first
         if suggestion
@@ -99,6 +189,12 @@ module Breadkit
               @diagnostics << diagnostic(:invalid_hole, "error", "invalid hole #{anchor.inspect}", item[:location], [item[:ref], anchor])
             end
           end
+          if hole && definition["mount"] == "rail"
+            expected_polarity = { "power" => "+", "ground" => "-" }[definition["type"]]
+            if hole.kind != :rail || (expected_polarity && @board.rail_polarity(hole.rail) != expected_polarity)
+              placement_error(item, "#{item[:ref]}.#{name} needs a #{expected_polarity || 'matching'} rail hole")
+            end
+          end
           result[name.to_s] = Pin.new(name: name.to_s, number: number, hole_id: hole&.id,
                                       node_id: "pin:#{item[:ref]}.#{name}", role: definition["type"] || definition["role"])
         else
@@ -106,9 +202,14 @@ module Breadkit
                                       role: definition["type"] || definition["role"])
         end
       end
+      if @board.is_a?(BoardSet)
+        board_ids = result.values.filter_map { |pin| @board.board_id_for(pin.hole_id) if pin.hole_id }.uniq
+        placement_error(item, "#{item[:ref]} cannot span multiple boards") if board_ids.length > 1
+      end
       validate_footprint_geometry(item, part, result) if requested && part.placement == "footprint"
       if part.data["straddle"] && (item[:at] || requested)
-        groups = @board.definition.data.dig("terminal", "groups")
+        anchor = item[:at] || result.values.find(&:hole_id)&.hole_id
+        groups = @board.definition_for(anchor)&.data&.dig("terminal", "groups")
         occupied_groups = result.values.filter_map do |pin|
           row = @board.hole(pin.hole_id)&.row
           groups&.index { |rows| rows.include?(row) } if row
@@ -134,7 +235,7 @@ module Breadkit
     end
 
     def validate_footprint_geometry(item, part, result)
-      footprint = part.data["footprint"]
+      footprint = part.footprint
       return unless footprint
 
       first = part.pins.first
@@ -142,7 +243,7 @@ module Breadkit
       origin = @board.hole(item[:at] || result[first_key]&.hole_id)
       return unless origin
 
-      first_offset = footprint[first["num"].to_s] || [0, 0]
+      first_offset = transformed_offset(item, footprint[first["num"].to_s] || [0, 0])
       part.pins.each do |definition|
         pin = result[(definition["name"] || definition["num"]).to_s]
         next unless pin&.hole_id
@@ -150,8 +251,8 @@ module Breadkit
         offset = footprint[definition["num"].to_s]
         next unless offset
 
-        expected = @terminal_positions[[origin.x + offset[0].to_i - first_offset[0].to_i,
-                                         origin.y + offset[1].to_i - first_offset[1].to_i]]
+        x, y = transformed_offset(item, offset)
+        expected = @terminal_positions[[origin.x + x - first_offset[0], origin.y + y - first_offset[1]]]
         unless pin.hole_id == expected&.id
           placement_error(item, "#{item[:ref]} pins do not match its footprint")
           break
@@ -171,7 +272,7 @@ module Breadkit
         count = part.pins.length if count.zero?
         half = count / 2
         first_row = at.row
-        near_row, far_row = @board.ravine_between
+        near_row, far_row = @board.ravine_between_for(at.to_s)
         return invalid_placement(item, at) unless [near_row, far_row].include?(first_row)
         row = first_row
         col = at.col
@@ -185,13 +286,15 @@ module Breadkit
         end
         return "#{row}#{col}"
       end
-      footprint = part.data["footprint"]
+      footprint = part.footprint
       return nil unless footprint
       offset = footprint[pin_num]
       return item[:at] if !offset && pin_num == part.pins.first["num"].to_s
       return nil unless offset
       anchor = @board.hole(at.to_s)
-      target = anchor && @terminal_positions[[anchor.x + offset[0].to_i, anchor.y + offset[1].to_i]]
+      x, y = transformed_offset(item, offset)
+      first_offset = transformed_offset(item, footprint[part.pins.first["num"].to_s] || [0, 0])
+      target = anchor && @terminal_positions[[anchor.x + x - first_offset[0], anchor.y + y - first_offset[1]]]
       unless target
         placement_error(item, "#{item[:ref]} footprint extends beyond the board or into the center gap")
         return nil
@@ -202,6 +305,10 @@ module Breadkit
       nil
     end
 
+    def transformed_offset(item, offset)
+      Geometry.transform(offset.map(&:to_i), rotate: item.dig(:attrs, :rotate) || 0, mirror: item.dig(:attrs, :mirror) == true)
+    end
+
     def placement_error(item, message)
       return if @diagnostics.any? { |entry| entry.code == "invalid_placement" && entry.targets.include?(item[:ref]) }
 
@@ -210,7 +317,7 @@ module Breadkit
 
     def invalid_placement(item, at)
       unless @diagnostics.any? { |entry| entry.code == "invalid_placement" && entry.targets.include?(item[:ref]) }
-        @diagnostics << diagnostic(:invalid_placement, "error", "DIP #{item[:ref]} must straddle the center gap (#{@board.ravine_between.join('/')} row)", item[:location], [item[:ref], at.to_s])
+        @diagnostics << diagnostic(:invalid_placement, "error", "DIP #{item[:ref]} must straddle the center gap (#{@board.ravine_between_for(at.to_s).join('/')} row)", item[:location], [item[:ref], at.to_s])
       end
       nil
     end
@@ -240,7 +347,7 @@ module Breadkit
         end
       end
       reserved = {}
-      @document.wires.each do |item|
+      @wire_items.each do |item|
         next if item[:electrical] == false
 
         [item[:from], item[:to]].each do |endpoint|
@@ -250,14 +357,23 @@ module Breadkit
         end
       end
       ids = {}
-      reserved_ids = components.keys + @document.supplies.map { |item| item[:name] } + @document.wires.filter_map { |item| item[:id] }
+      reserved_ids = components.keys + @document.supplies.map { |item| item[:name] } + @wire_items.filter_map { |item| item[:id] }
       next_id = 1
-      @document.wires.each do |item|
+      @wire_items.each do |item|
         unless item[:id]
           next_id += 1 while reserved_ids.include?("W#{next_id}") || ids["W#{next_id}"]
         end
         wire_id = item[:id] || "W#{next_id}"
         next_id += 1 unless item[:id]
+        if item[:id] && hole_like_id?(wire_id)
+          @diagnostics << diagnostic(:invalid_wire_id, "error", "wire ID #{wire_id} looks like a board hole", item[:location], [wire_id])
+        end
+        unless %w[straight arc edge].include?(item[:route].to_s)
+          @diagnostics << diagnostic(:invalid_route, "error", "invalid wire route #{item[:route].inspect}", item[:location], [wire_id])
+        end
+        if item[:color] && !Color.valid?(item[:color])
+          @diagnostics << diagnostic(:invalid_color, "error", "invalid wire color #{item[:color].inspect}", item[:location], [wire_id])
+        end
         if ids[wire_id]
           @diagnostics << diagnostic(:duplicate_ref, "error", "duplicate wire ID #{wire_id}", item[:location], [wire_id])
           next
@@ -281,7 +397,7 @@ module Breadkit
           end
           wires << Wire.new(id: wire_id, from: endpoints[0], to: endpoints[1], color: item[:color],
                             route: item[:route], layer: item[:layer], electrical: false, dashed: item[:dashed],
-                            location: item[:location])
+                            location: item[:location], step: item[:step])
           next
         end
         parsed = endpoints.map { |endpoint| HoleId.parse(endpoint, board: @board) rescue nil }
@@ -299,6 +415,7 @@ module Breadkit
             picked = candidates && candidates.map { |id| @board.hole(id) }
                                       .compact.reject { |hole| occupied[hole.id] || reserved[hole.id] }
                                       .min_by { |hole| [(target_x ? (hole.x - target_x).abs : 0), hole_order(hole)] }
+            picked ||= @board.hole(pin_hole) if @board.solder_pad?(pin_hole)
             if picked
               endpoints[side], parsed[side] = picked.id, HoleId.parse(picked.id, board: @board)
               occupied[picked.id] = wire_id
@@ -326,14 +443,14 @@ module Breadkit
         endpoints.each do |endpoint|
           id = endpoint_hole(endpoint, components)
           next unless id && @board.hole(id)
-          if occupied[id] && occupied[id] != wire_id
+          if occupied[id] && occupied[id] != wire_id && !@board.solder_pad?(id)
             @diagnostics << diagnostic(:hole_conflict, "error", "hole #{id} is already occupied", item[:location], [wire_id, id])
           end
           occupied[id] = true
         end
         wires << Wire.new(id: wire_id, from: endpoints[0], to: endpoints[1], color: item[:color],
                           route: item[:route], layer: item[:layer], electrical: true, dashed: item[:dashed],
-                          location: item[:location])
+                          location: item[:location], step: item[:step])
       end
       wires
     end
@@ -343,6 +460,12 @@ module Breadkit
       @board.hole(id)&.x if id
     end
 
+    def hole_like_id?(value)
+      %i[terminal rail].include?(HoleId.parse(value, board: @board).kind)
+    rescue ArgumentError
+      false
+    end
+
     def endpoint_hole(endpoint, components)
       id = HoleId.parse(endpoint, board: @board)
       return id.to_s unless id.kind == :pin
@@ -380,7 +503,9 @@ module Breadkit
         end
       end
       @document.supplies.map do |item|
-        Supply.new(name: item[:name], voltage: item[:voltage], plus: item[:plus], minus: item[:minus], location: item[:location])
+        Supply.new(name: item[:name], voltage: item[:voltage], plus: item[:plus], minus: item[:minus],
+                   location: item[:location], isolated: item[:isolated] == true, voltage_range: item[:voltage_range],
+                   current_limit: item[:current_limit], step: item[:step])
       end
     end
 
@@ -389,6 +514,7 @@ module Breadkit
       entries = components.values.map { |item| [item.ref, item.location] } +
                 wires.map { |item| [item.id, item.location] } +
                 supplies.map { |item| [item.name, item.location] }
+      entries.concat(@board.boards.keys.map { |name| [name, nil] }) if @board.is_a?(BoardSet)
       entries.each do |name, location|
         if names[name]
           @diagnostics << diagnostic(:duplicate_ref, "error", "duplicate name #{name}", location, [name])
@@ -417,6 +543,12 @@ module Breadkit
         entries.each do |entry|
           refs = entry[:refs] || entry["refs"] || []
           location = entry[:location] || entry["location"]
+          if (entry[:kind] || entry["kind"]) == "current"
+            Array(refs).each do |reference|
+              @diagnostics << diagnostic(:unknown_part, "error", "unknown component #{reference}", location, [reference]) unless components.key?(reference.to_s)
+            end
+            next
+          end
           Array(refs).each { |reference| validate_reference(reference, location, components, supplies, labels) }
         end
       end

data/lib/breadkit/structured_input.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Breadkit
+  class StructuredInput
+    ROOT_KEYS = %w[title board boards use_parts use_boards supplies labels parts offboard wires connections expectations lint_disables].freeze
+
+    def self.load_file(path)
+      new(File.expand_path(path)).load_file
+    end
+
+    def self.load_source(path, source)
+      new(File.expand_path(path), source: source).load_file
+    end
+
+    def initialize(path, source: nil)
+      @path = path
+      @source = source
+      @location = SourceLocation.new(path: path, line: 1)
+      @builder = DSL::Builder.new(base_dir: File.dirname(path))
+    end
+
+    def load_file
+      source = @source || File.read(@path, encoding: "UTF-8")
+      raw = @path.end_with?(".toml") ? parse_toml(source) : YAML.safe_load(source, aliases: false)
+      data = mapping(raw, "root")
+      allowed!(data, ROOT_KEYS, "root")
+      @builder.document.source_root = File.dirname(@path)
+      @builder.title(string(data["title"], "title")) if data.key?("title")
+      raise DSLError, "board and boards cannot be used together" if data.key?("board") && data.key?("boards")
+      load_board(data["board"]) if data.key?("board")
+      if data.key?("boards")
+        named = records(data, "boards")
+        raise DSLError, "boards must contain at least one board" if named.empty?
+        named.each_with_index { |item, index| load_named_board(item, "boards[#{index}]") }
+      end
+      paths(data, "use_parts").each { |item| @builder.use_parts(item) }
+      paths(data, "use_boards").each { |item| @builder.use_boards(item) }
+      records(data, "supplies").each_with_index { |item, index| load_supply(item, "supplies[#{index}]") }
+      records(data, "labels").each_with_index { |item, index| load_label(item, "labels[#{index}]") }
+      records(data, "parts").each_with_index { |item, index| load_part(item, "parts[#{index}]", offboard: false) }
+      records(data, "offboard").each_with_index { |item, index| load_part(item, "offboard[#{index}]", offboard: true) }
+      records(data, "wires").each_with_index { |item, index| load_wire(item, "wires[#{index}]") }
+      records(data, "connections").each_with_index { |item, index| load_connection(item, "connections[#{index}]") }
+      records(data, "expectations").each_with_index { |item, index| load_expectation(item, "expectations[#{index}]") }
+      records(data, "lint_disables").each_with_index { |item, index| load_disable(item, "lint_disables[#{index}]") }
+      document = @builder.document
+      (document.supplies + document.labels + document.components + document.wires + document.lint_disables).each do |entry|
+        entry[:location] = @location
+      end
+      document.expectations.each do |group|
+        group[:location] = @location
+        group[:entries].each { |entry| entry[:location] = @location }
+      end
+      document.diagnostics.map! do |item|
+        Diagnostic.new(code: item.code, severity: item.severity, message: item.message,
+                       location: @location, targets: item.targets)
+      end
+      document
+    rescue Psych::Exception, DSLError, ArgumentError, TypeError => e
+      raise DSLError.new("#{@path}: #{e.message}", location: @location)
+    end
+
+    private
+
+    def parse_toml(source)
+      require "tomlrb"
+      Tomlrb.parse(source)
+    rescue Tomlrb::ParseError => e
+      raise DSLError, e.message
+    end
+
+    def load_board(value)
+      if value.is_a?(String)
+        @builder.board(string(value, "board"))
+      else
+        item = mapping(value, "board")
+        allowed!(item, %w[type split_rails], "board")
+        options = {}
+        options[:split_rails] = boolean(item["split_rails"], "board.split_rails") if item.key?("split_rails")
+        @builder.board(string(item["type"], "board.type"), **options)
+      end
+    end
+
+    def load_named_board(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[name type split_rails], context)
+      options = {}
+      options[:split_rails] = boolean(item["split_rails"], "#{context}.split_rails") if item.key?("split_rails")
+      @builder.board(string(item["type"], "#{context}.type"), as: string(item["name"], "#{context}.name"), **options)
+    end
+
+    def load_supply(value, context)
+      item = mapping(value, context)
+      if item.key?("from")
+        allowed!(item, %w[from plus minus], context)
+        @builder.supply(from: string(item["from"], "#{context}.from"),
+                        plus: string(item["plus"], "#{context}.plus"),
+                        minus: string(item["minus"], "#{context}.minus"))
+        return
+      end
+
+      allowed!(item, %w[name voltage plus minus isolated current_limit], context)
+      options = { voltage: number_or_range(item["voltage"], "#{context}.voltage"),
+                  plus: string(item["plus"], "#{context}.plus"),
+                  minus: string(item["minus"], "#{context}.minus") }
+      options[:isolated] = boolean(item["isolated"], "#{context}.isolated") if item.key?("isolated")
+      options[:current_limit] = item["current_limit"] if item.key?("current_limit")
+      @builder.supply(string(item["name"], "#{context}.name"), **options)
+    end
+
+    def load_label(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[name at], context)
+      @builder.net(string(item["name"], "#{context}.name"), at: string(item["at"], "#{context}.at"))
+    end
+
+    def load_part(value, context, offboard:)
+      item = mapping(value, context)
+      allowed!(item, %w[ref type value pins at attrs unused side offboard], context)
+      is_offboard = offboard || item["offboard"] == true
+      boolean(item["offboard"], "#{context}.offboard") if item.key?("offboard")
+      attrs = item.key?("attrs") ? mapping(item["attrs"], "#{context}.attrs").transform_keys(&:to_sym) : {}
+      ref = string(item["ref"], "#{context}.ref")
+      type = string(item["type"], "#{context}.type")
+      unused = item.key?("unused") ? strings(item["unused"], "#{context}.unused") : []
+      if is_offboard
+        raise DSLError, "#{context}.pins is unavailable for offboard parts" if item.key?("pins")
+        raise DSLError, "#{context}.value is unavailable for offboard parts" if item.key?("value")
+        side = item.key?("side") ? string(item["side"], "#{context}.side") : "left"
+        at = item.key?("at") ? string(item["at"], "#{context}.at") : nil
+        @builder.offboard(ref, type, side: side, at: at, unused: unused, **attrs)
+      else
+        raise DSLError, "#{context}.side requires offboard: true" if item.key?("side")
+        pins = pins(item["pins"], "#{context}.pins") if item.key?("pins")
+        at = item.key?("at") ? string(item["at"], "#{context}.at") : nil
+        value = item["value"]
+        unless value.nil? || value.is_a?(String) || value.is_a?(Numeric)
+          raise DSLError, "#{context}.value must be text or a number"
+        end
+        @builder.part(ref, type, value, pins: pins, at: at, **attrs.merge(unused: unused))
+      end
+    end
+
+    def load_wire(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[from to color id route layer electrical dashed], context)
+      options = {}
+      %w[color id route].each do |key|
+        options[key.to_sym] = string(item[key], "#{context}.#{key}") if item.key?(key)
+      end
+      if item.key?("layer")
+        layer = item["layer"]
+        options[:layer] = layer.is_a?(Array) ? strings(layer, "#{context}.layer") : string(layer, "#{context}.layer")
+      end
+      %w[electrical dashed].each do |key|
+        options[key.to_sym] = boolean(item[key], "#{context}.#{key}") if item.key?(key)
+      end
+      @builder.wire(string(item["from"], "#{context}.from"), string(item["to"], "#{context}.to"), **options)
+    end
+
+    def load_connection(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[from to when], context)
+      options = {}
+      options[:when] = string(item["when"], "#{context}.when") if item.key?("when")
+      @builder.connect(string(item["from"], "#{context}.from"), string(item["to"], "#{context}.to"), **options)
+    end
+
+    def load_expectation(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[strict when connected isolated nets voltage current], context)
+      strict = item.key?("strict") ? boolean(item["strict"], "#{context}.strict") : false
+      group = { strict: strict, entries: [], location: @location }
+      group[:when] = string(item["when"], "#{context}.when") if item.key?("when")
+      %w[connected isolated].each do |kind|
+        next unless item.key?(kind)
+        groups(item[kind], "#{context}.#{kind}").each do |refs|
+          group[:entries] << { kind: kind, refs: refs, location: @location }
+        end
+      end
+      records(item, "nets", context).each_with_index do |record, index|
+        entry = mapping(record, "#{context}.nets[#{index}]")
+        allowed!(entry, %w[name refs], "#{context}.nets[#{index}]")
+        group[:entries] << { kind: "net", name: string(entry["name"], "#{context}.nets[#{index}].name"),
+                             refs: strings(entry["refs"], "#{context}.nets[#{index}].refs"), location: @location }
+      end
+      %w[voltage current].each do |kind|
+        records(item, kind, context).each_with_index do |record, index|
+          entry = mapping(record, "#{context}.#{kind}[#{index}]")
+          allowed!(entry, %w[ref range], "#{context}.#{kind}[#{index}]")
+          range = number_or_range(entry["range"], "#{context}.#{kind}[#{index}].range")
+          raise DSLError, "#{context}.#{kind}[#{index}].range must be inclusive" unless range.is_a?(Range)
+          limits = [Value.parse(range.begin), Value.parse(range.end)]
+          unless limits.all?(&:finite?) && limits.first <= limits.last && (kind != "current" || !limits.first.negative?)
+            raise DSLError, "#{context}.#{kind}[#{index}].range is invalid"
+          end
+          group[:entries] << { kind: kind, refs: [string(entry["ref"], "#{context}.#{kind}[#{index}].ref")],
+                               range: limits, location: @location }
+        end
+      end
+      @builder.document.expectations << group
+    end
+
+    def load_disable(value, context)
+      item = mapping(value, context)
+      allowed!(item, %w[rule on reason], context)
+      options = {}
+      options[:on] = string(item["on"], "#{context}.on") if item.key?("on")
+      options[:reason] = string(item["reason"], "#{context}.reason") if item.key?("reason")
+      @builder.lint_disable(string(item["rule"], "#{context}.rule"), **options)
+    end
+
+    def number_or_range(value, context)
+      return value if value.is_a?(Numeric)
+      raise DSLError, "#{context} must be a number or numeric string" unless value.is_a?(String)
+
+      match = /\A(.+)\.\.(.+)\z/.match(value)
+      match ? (Value.parse(match[1])..Value.parse(match[2])) : value
+    end
+
+    def mapping(value, context)
+      unless value.is_a?(Hash) && value.keys.all? { |key| key.is_a?(String) }
+        raise DSLError, "#{context} must be a mapping with text keys"
+      end
+      value
+    end
+
+    def allowed!(item, keys, context)
+      unknown = item.keys - keys
+      raise DSLError, "#{context} has unknown keys: #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def records(item, key, context = "root")
+      value = item.fetch(key, [])
+      raise DSLError, "#{context}.#{key} must be a list" unless value.is_a?(Array)
+      value
+    end
+
+    def paths(item, key)
+      value = item.fetch(key, [])
+      value = [value] if value.is_a?(String)
+      strings(value, key)
+    end
+
+    def strings(value, context)
+      raise DSLError, "#{context} must be a list of text" unless value.is_a?(Array)
+      value.map.with_index { |item, index| string(item, "#{context}[#{index}]") }
+    end
+
+    def groups(value, context)
+      raise DSLError, "#{context} must be a list of reference lists" unless value.is_a?(Array)
+      value.map.with_index do |item, index|
+        refs = strings(item, "#{context}[#{index}]")
+        raise DSLError, "#{context}[#{index}] needs at least two references" if refs.length < 2
+        refs
+      end
+    end
+
+    def pins(value, context)
+      return strings(value, context) if value.is_a?(Array)
+      item = mapping(value, context)
+      item.transform_values { |hole| string(hole, "#{context} pin") }
+    end
+
+    def string(value, context)
+      raise DSLError, "#{context} must be nonempty text" unless value.is_a?(String) && !value.empty?
+      value
+    end
+
+    def boolean(value, context)
+      raise DSLError, "#{context} must be boolean" unless [true, false].include?(value)
+      value
+    end
+  end
+end