breadkit 0.1.0 → 0.2.0

data/lib/breadkit/board.rb

@@ -6,7 +6,20 @@ module Breadkit
 
     def initialize(data)
       @data = data
+      unknown = data.keys - %w[id name terminal rails rail_layout ground_labels]
+      raise ArgumentError, "unknown board keys: #{unknown.join(', ')}" unless unknown.empty?
       terminal = data["terminal"] || {}
+      unknown_terminal = terminal.keys - %w[columns rows groups ravine_between strip_direction wire_attachment]
+      raise ArgumentError, "unknown terminal keys: #{unknown_terminal.join(', ')}" unless unknown_terminal.empty?
+      unless %w[column row].include?(terminal.fetch("strip_direction", "column"))
+        raise ArgumentError, "terminal.strip_direction must be column or row"
+      end
+      unless %w[socket solder].include?(terminal.fetch("wire_attachment", "socket"))
+        raise ArgumentError, "terminal.wire_attachment must be socket or solder"
+      end
+      if data["ground_labels"] && (!data["ground_labels"].is_a?(Array) || !data["ground_labels"].all? { |label| label.is_a?(String) && !label.empty? })
+        raise ArgumentError, "ground_labels must be a list of names"
+      end
       unless data["id"] && terminal["columns"].to_i.positive? && terminal["rows"].is_a?(Array) && terminal["groups"].is_a?(Array)
         raise ArgumentError, "invalid board definition: #{data['id'] || '(missing id)'}"
       end
@@ -34,12 +47,26 @@ module Breadkit
       unless groups.all? { |group| group.is_a?(Array) && !group.empty? } && grouped_rows.sort == rows.sort
         raise ArgumentError, "terminal groups must partition rows exactly"
       end
+      if terminal.fetch("strip_direction", "column") == "row" && groups.any? { |group| group.length != 1 }
+        raise ArgumentError, "row strips require one terminal row per group"
+      end
       if terminal.key?("ravine_between")
         ravine = terminal["ravine_between"]
         unless ravine.is_a?(Array) && ravine.length == 2 && rows.each_cons(2).any? { |pair| pair == ravine.map(&:to_s) }
           raise ArgumentError, "ravine_between must name adjacent terminal rows"
         end
       end
+      Array(data["rails"]).each do |rail|
+        side, order = rail.values_at("side", "order")
+        unless %w[top bottom left right center].include?(side) && order.is_a?(Integer) && order >= 0
+          raise ArgumentError, "rail side or order is invalid"
+        end
+        if side == "center" && (!terminal.key?("ravine_between") || order > 1)
+          raise ArgumentError, "center rail needs a free row in the ravine"
+        end
+      end
+      rail_positions = Array(data["rails"]).map { |rail| rail.values_at("side", "order") }
+      raise ArgumentError, "rail positions overlap" unless rail_positions.uniq.length == rail_positions.length
     end
 
     def id
@@ -87,6 +114,11 @@ module Breadkit
       item && strips[item.strip_id]
     end
 
+    def solder_pad?(id)
+      item = hole(id)
+      item&.kind == :terminal && definition.data.dig("terminal", "wire_attachment") == "solder"
+    end
+
     def width
       definition.data.dig("terminal", "columns").to_i
     end
@@ -116,6 +148,18 @@ module Breadkit
       rail && (rail["polarity"] || rail.fetch("id").to_s[/[+-]\z/])
     end
 
+    def definition_for(_reference)
+      definition
+    end
+
+    def ravine_between_for(_reference)
+      ravine_between
+    end
+
+    def board_id_for(_reference)
+      nil
+    end
+
     private
 
     def add_hole(hole)
@@ -126,10 +170,11 @@ module Breadkit
     def build_terminal_holes
       terminal = definition.data.fetch("terminal")
       groups = terminal.fetch("groups")
+      row_strips = terminal.fetch("strip_direction", "column") == "row"
       terminal.fetch("columns").times do |col|
         groups.each_with_index do |rows, group_index|
-          strip_id = "terminal:#{col + 1}:#{group_index}"
           rows.each do |row|
+            strip_id = row_strips ? "terminal:row:#{row}" : "terminal:#{col + 1}:#{group_index}"
             add_hole(Hole.new(id: "#{row}#{col + 1}", kind: :terminal, row: row.to_s,
                               col: col + 1, x: col.to_f, y: @terminal_row_positions.fetch(row.to_s).to_f,
                               strip_id: strip_id))
@@ -148,10 +193,21 @@ module Breadkit
         segments = layout.fetch("split_segments", segments) if split_rails
         segments.each_with_index do |range, segment_index|
           (range[0]..range[1]).each do |index|
-            x = layout.fetch("start_column", 1) - 1 + index - 1
             size = layout["group_size"].to_i
-            x += (index - 1) / size if size.positive?
-            y = rail.fetch("side") == "top" ? height + 1 + rail.fetch("order", 0) : -2 - rail.fetch("order", 0)
+            along = index - 1
+            along += (index - 1) / size if size.positive?
+            side, order = rail.values_at("side", "order")
+            if %w[left right].include?(side)
+              x = side == "left" ? -2 - order : width + 1 + order
+              y = layout.fetch("start_row", 1) - 1 + along
+            else
+              x = layout.fetch("start_column", 1) - 1 + along
+              y = case side
+                  when "top" then height + 1 + order
+                  when "center" then @terminal_row_positions.fetch(definition.data.dig("terminal", "ravine_between", 0).to_s) + 1 + order
+                  else -2 - order
+                  end
+            end
             strip_id = "rail:#{rail_id}:#{segment_index}"
             add_hole(Hole.new(id: "#{rail_id}#{index}", kind: :rail, rail: rail_id,
                               col: index, x: x.to_f, y: y.to_f, strip_id: strip_id))
@@ -160,4 +216,96 @@ module Breadkit
       end
     end
   end
+
+  class BoardSet
+    Definition = Data.define(:id, :data)
+
+    attr_reader :boards, :holes, :strips, :definition
+
+    def initialize(boards)
+      @boards = boards
+      @holes, @strips = {}, {}
+      @terminal_rows = []
+      @rail_ids = []
+      right_edge = nil
+      boards.each do |name, board|
+        @terminal_rows.concat(board.terminal_rows.map { |row| "#{name}.#{row}" })
+        @rail_ids.concat(board.rail_ids.map { |rail| "#{name}.#{rail}" })
+        left, right = board.holes.values.map(&:x).minmax
+        raise ArgumentError, "board #{name} has no holes" unless left
+        offset = right_edge ? right_edge + 8 - left : -left
+        board.holes.each_value do |hole|
+          id = "#{name}.#{hole.id}"
+          strip_id = "#{name}.#{hole.strip_id}"
+          @holes[id] = Hole.new(id: id, kind: hole.kind, row: hole.row, col: hole.col,
+                                rail: hole.rail && "#{name}.#{hole.rail}", x: hole.x + offset,
+                                y: hole.y, strip_id: strip_id)
+          (@strips[strip_id] ||= []) << id
+        end
+        right_edge = right + offset
+      end
+      ground_labels = boards.values.flat_map { |board| Array(board.definition.data["ground_labels"] || %w[GND 0V VSS GROUND]) }.uniq
+      @definition = Definition.new(id: "multi", data: { "ground_labels" => ground_labels })
+      @width = right_edge ? right_edge.ceil + 1 : 0
+    end
+
+    def hole(id)
+      holes[HoleId.parse(id, board: self).to_s]
+    rescue ArgumentError
+      nil
+    end
+
+    def strip(id)
+      item = hole(id)
+      item && strips[item.strip_id]
+    end
+
+    def solder_pad?(id)
+      board_for(id)&.solder_pad?(id.to_s.split(".", 2).last) || false
+    end
+
+    def terminal_rows
+      @terminal_rows
+    end
+
+    def rail_ids
+      @rail_ids
+    end
+
+    def width
+      @width
+    end
+
+    def height
+      boards.values.map(&:height).max || 0
+    end
+
+    def split_rails
+      false
+    end
+
+    def board_id_for(reference)
+      prefix = reference.to_s.split(".", 2).first
+      boards.keys.find { |name| name.casecmp?(prefix) }
+    end
+
+    def board_for(reference)
+      boards[board_id_for(reference)]
+    end
+
+    def definition_for(reference)
+      board_for(reference)&.definition
+    end
+
+    def ravine_between_for(reference)
+      name = board_id_for(reference)
+      board = boards[name]
+      board ? board.ravine_between.map { |row| "#{name}.#{row}" } : []
+    end
+
+    def rail_polarity(id)
+      name = board_id_for(id)
+      boards[name]&.rail_polarity(id.to_s.delete_prefix("#{name}."))
+    end
+  end
 end

data/lib/breadkit/cli.rb

@@ -4,7 +4,22 @@ require "optparse"
 
 module Breadkit
   class CLI
-    USAGE = "Usage: breadkit ir FILE | nets [--state SWITCH] FILE | parts [FILE] | --version".freeze
+    USAGE = <<~TEXT.freeze
+      Usage: breadkit COMMAND [OPTIONS]
+        ir [--force] [--timeout SECONDS] FILE
+        nets [--state SWITCH] [--timeout SECONDS] FILE
+        where HOLE FILE | explain PART FILE | bom FILE | diff OLD NEW
+        suggest FILE (show free-hole wire candidates for unmet connection intent)
+        kit --inventory KIT.yml FILE (allocate measured jumpers to straight board wires)
+        patterns FILE (recognize supported unloaded circuit patterns)
+        export --format kicad|spice|wokwi|pins|fritzing FILE
+        fmt FILE (declarative YAML or TOML; prints formatted source)
+        lock FILE (pin local part and board definitions in breadkit.lock)
+        parts [FILE] | parts show PART [FILE] | check-part YAML
+        new [FILE] --template led|555|arduino | doctor | console FILE
+        --version | --help
+    TEXT
+    TEMPLATES = %w[led 555 arduino].freeze
 
     def run(argv)
       args = argv.dup
@@ -12,34 +27,151 @@ module Breadkit
       case command
       when "ir", "nets"
         state_name = nil
+        force = false
+        timeout = 10.0
         if command == "nets"
-          OptionParser.new { |opts| opts.on("--state SWITCH") { |value| state_name = value } }.parse!(args)
+          OptionParser.new do |opts|
+            opts.on("--state SWITCH") { |value| state_name = value }
+            opts.on("--timeout SECONDS", Float) { |value| timeout = value }
+          end.parse!(args)
+        else
+          OptionParser.new do |opts|
+            opts.on("--force") { force = true }
+            opts.on("--timeout SECONDS", Float) { |value| timeout = value }
+          end.parse!(args)
         end
         path = args.shift
         raise ArgumentError, "usage: breadkit #{command} FILE" unless path
         raise ArgumentError, "unexpected arguments: #{args.join(' ')}" unless args.empty?
 
-        circuit = Breadkit.load(path)
+        circuit = Breadkit.load(path, timeout: timeout)
         if command == "ir"
-          errors = circuit.diagnostics.select { |item| item.severity == "error" }
-          errors.each { |item| warn "breadkit: #{item.code}: #{item.message}" }
-          return 1 unless errors.empty?
+          has_errors = report_errors(circuit)
+          return 1 if has_errors && !force
 
           puts JSON.pretty_generate(circuit.to_ir)
           0
         else
-          state = circuit.states.find { |item| item.name == state_name } if state_name
-          raise ArgumentError, "unknown switch state #{state_name}" if state_name && !state
+          return 1 if report_errors(circuit)
+
+          state = circuit.state(state_name)
           circuit.nets(state).each { |net| puts "#{net.name}: #{net.members.join(', ')}" }
-          circuit.diagnostics.any? { |item| item.severity == "error" } ? 1 : 0
+          0
         end
       when "parts"
+        show = args.shift if args.first == "show"
+        name = args.shift if show
+        raise ArgumentError, "usage: breadkit parts show PART [FILE]" if show && !name
         path = args.shift
-        raise ArgumentError, "unexpected arguments: #{args.join(' ')}" unless args.empty?
-
+        unexpected!(args)
         document = DSL.load_file(path) if path
-        PartLibrary.new(extra_paths: document&.part_paths || [], extra_definitions: document&.part_definitions || [])
-                   .all.each { |part| puts "#{part.id}\t#{part.data['category']}" }
+        library = PartLibrary.new(extra_paths: document&.part_paths || [], extra_definitions: document&.part_definitions || [])
+        if show
+          part = library.find(name)
+          raise ArgumentError, "unknown part #{name}" unless part
+          puts JSON.pretty_generate(part.data)
+        else
+          library.all.each { |part| puts "#{part.id}\t#{part.data['category']}" }
+        end
+        0
+      when "check-part"
+        path = required!(args, "check-part YAML")
+        data = YAML.safe_load(File.read(path, encoding: "UTF-8"), aliases: false)
+        raise ArgumentError, "part definition must be a YAML mapping" unless data.is_a?(Hash)
+        part = PartLibrary.new(extra_paths: [path]).find(data["id"])
+        raise ArgumentError, "part definition needs an id" unless part
+        puts "Valid part: #{part.id} (#{part.pins.length} pins)"
+        0
+      when "where", "explain", "bom"
+        state_name = nil
+        timeout = 10.0
+        OptionParser.new do |opts|
+          opts.on("--state SWITCH") { |value| state_name = value }
+          opts.on("--timeout SECONDS", Float) { |value| timeout = value }
+        end.parse!(args)
+        target = args.shift unless command == "bom"
+        path = required!(args, command == "bom" ? "bom FILE" : "#{command} TARGET FILE")
+        circuit = Breadkit.load(path, timeout: timeout)
+        return 1 if report_errors(circuit)
+
+        state = select_state(circuit, state_name)
+        case command
+        when "where" then show_where(circuit, target, state)
+        when "explain" then show_explain(circuit, target, state)
+        when "bom" then show_bom(circuit)
+        end
+        0
+      when "new"
+        template = nil
+        OptionParser.new { |opts| opts.on("--template NAME") { |value| template = value } }.parse!(args)
+        raise ArgumentError, "choose --template #{TEMPLATES.join('|')}" unless TEMPLATES.include?(template)
+        path = args.shift || "#{template}.bk.rb"
+        unexpected!(args)
+        source = File.expand_path("templates/#{template}.bk.rb", __dir__)
+        File.open(path, "wx:UTF-8") { |file| file.write(File.read(source, encoding: "UTF-8")) }
+        puts "Created #{path}"
+        0
+      when "doctor"
+        unexpected!(args)
+        supported = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
+        puts "Ruby #{RUBY_VERSION}: #{supported ? 'supported' : 'requires 3.3 or newer'}"
+        %w[bklint bkrender].each do |name|
+          found = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+          puts "#{name}: #{found ? 'available' : 'not installed'}"
+        end
+        supported ? 0 : 1
+      when "diff"
+        old_path = args.shift
+        new_path = required!(args, "diff OLD NEW")
+        raise ArgumentError, "usage: breadkit diff OLD NEW" unless old_path
+        show_diff(Breadkit.load(old_path), Breadkit.load(new_path))
+        0
+      when "export"
+        format = nil
+        OptionParser.new { |opts| opts.on("--format NAME") { |value| format = value } }.parse!(args)
+        raise ArgumentError, "choose --format #{Exporters::FORMATS.join('|')}" unless Exporters::FORMATS.include?(format)
+        path = required!(args, "export --format FORMAT FILE")
+        puts Exporters.call(Breadkit.load(path), format: format)
+        0
+      when "fmt"
+        path = required!(args, "fmt FILE")
+        print Formatter.call(path)
+        0
+      when "lock"
+        path = required!(args, "lock FILE")
+        puts "Wrote #{PartLock.write(path)}"
+        0
+      when "suggest"
+        path = required!(args, "suggest FILE")
+        circuit = Breadkit.load(path)
+        return 1 if report_errors(circuit)
+
+        puts JSON.pretty_generate(circuit.wire_suggestions)
+        0
+      when "kit"
+        inventory = nil
+        OptionParser.new { |opts| opts.on("--inventory FILE") { |value| inventory = value } }.parse!(args)
+        raise ArgumentError, "usage: breadkit kit --inventory KIT.yml FILE" unless inventory
+
+        path = required!(args, "kit --inventory KIT.yml FILE")
+        circuit = Breadkit.load(path)
+        return 1 if report_errors(circuit)
+
+        puts JSON.pretty_generate(JumperKit.load(inventory).allocate(circuit))
+        0
+      when "patterns"
+        path = required!(args, "patterns FILE")
+        circuit = Breadkit.load(path)
+        return 1 if report_errors(circuit)
+
+        puts JSON.pretty_generate(Patterns.call(circuit))
+        0
+      when "console"
+        path = required!(args, "console FILE")
+        circuit = Breadkit.load(path)
+        puts "Circuit loaded as `circuit`. Try circuit.nets or circuit.components."
+        require "irb"
+        binding.irb(show_code: false) # rubocop:disable Lint/Debugger -- This command intentionally opens a REPL.
         0
       when "--version", "-v"
         raise ArgumentError, "unexpected arguments: #{args.join(' ')}" unless args.empty?
@@ -57,5 +189,89 @@ module Breadkit
       warn "breadkit: #{e.message}"
       2
     end
+
+    private
+
+    def report_errors(circuit)
+      errors = circuit.diagnostics.select { |item| item.severity == "error" }
+      errors.each { |item| warn "breadkit: #{item.code}: #{item.message}" }
+      !errors.empty?
+    end
+
+    def required!(args, usage)
+      path = args.shift
+      raise ArgumentError, "usage: breadkit #{usage}" unless path
+      unexpected!(args)
+      path
+    end
+
+    def unexpected!(args)
+      raise ArgumentError, "unexpected arguments: #{args.join(' ')}" unless args.empty?
+    end
+
+    def select_state(circuit, name)
+      return unless name
+      circuit.state(name)
+    end
+
+    def show_where(circuit, reference, state)
+      hole = circuit.board.hole(reference)
+      raise ArgumentError, "unknown hole #{reference}" unless hole
+      strip = circuit.board.strip(hole.id)
+      pins = circuit.components.values.flat_map do |component|
+        component.pins.values.filter_map do |pin|
+          "#{component.ref}.#{pin.name}@#{pin.hole_id}" if strip.include?(pin.hole_id)
+        end
+      end
+      wires = circuit.wires.flat_map do |wire|
+        [wire.from, wire.to].filter_map { |end_at| "#{wire.id}@#{end_at}" if strip.include?(end_at) }
+      end
+      net = circuit.net_of(hole.id, state)
+      puts "Hole: #{hole.id}"
+      puts "Strip: #{strip.join(', ')}"
+      puts "Net: #{net&.name || 'unconnected'}"
+      puts "Pins: #{pins.empty? ? 'none' : pins.join(', ')}"
+      puts "Wires: #{wires.empty? ? 'none' : wires.join(', ')}"
+    end
+
+    def show_explain(circuit, reference, state)
+      component = circuit.components[reference]
+      raise ArgumentError, "unknown component #{reference}" unless component
+      puts "#{component.ref}: #{component.part.id}#{" #{component.value}" if component.value}"
+      dc = circuit.dc_analysis(state)
+      potentials = []
+      component.pins.each_value do |pin|
+        net = circuit.net_of("#{component.ref}.#{pin.name}", state)
+        potential = dc.success? && net && dc.voltages.key?(net.name) ? dc.voltages[net.name] : net&.potential
+        potentials << potential
+        voltage = potential.nil? ? "unknown" : "#{format('%.3g', potential)} V"
+        voltage += " (relative)" if dc.success? && net && dc.floating.any? { |group| group.include?(net.name) }
+        puts "  #{pin.name}: #{pin.hole_id || 'offboard'} | #{net&.name || 'unconnected'} | #{voltage}"
+      end
+      current = dc.currents[component.ref]&.abs if dc.success?
+      current ||= if component.part.id == "resistor" && potentials.length == 2 && potentials.none?(&:nil?)
+        resistance = Value.parse(component.value)
+        (potentials[0] - potentials[1]).abs / resistance if resistance.positive?
+      end
+      puts "Current: #{current ? "#{format('%.3g', current)} A" : 'unknown (DC operating point unavailable)'}"
+      puts "Power: #{format('%.3g', dc.power[component.ref])} W" if dc.success? && dc.power.key?(component.ref)
+      dc.assumptions.each { |assumption| puts "Assumption: #{assumption}" } if dc.success? && dc.currents.key?(component.ref)
+    end
+
+    def show_bom(circuit)
+      counts = circuit.components.values.map { |component| [component.part.id, component.value&.to_s] }.tally
+      puts "Count\tPart\tValue"
+      counts.sort_by { |(part, value), _count| [part, value.to_s] }.each do |(part, value), count|
+        puts "#{count}\t#{part}\t#{value}"
+      end
+      puts "#{circuit.wires.length}\tjumper_wire\t"
+    end
+
+    def show_diff(old_circuit, new_circuit)
+      old_circuit.diff(new_circuit).each do |key, (before, after)|
+        puts "- #{key}: #{before}" if before
+        puts "+ #{key}: #{after}" if after
+      end
+    end
   end
 end

data/lib/breadkit/color.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Breadkit
+  module Color
+    NAMES = %w[
+      aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown
+      burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan
+      darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred
+      darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue
+      dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray
+      green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen
+      lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink
+      lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen
+      linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue
+      mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy
+      oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip
+      peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown
+      seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle
+      tomato turquoise violet wheat white whitesmoke yellow yellowgreen
+    ].freeze
+
+    def self.valid?(value)
+      text = value.to_s.downcase
+      NAMES.include?(text) || /\A#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\z/.match?(text) ||
+        valid_function?(text)
+    end
+
+    def self.valid_function?(text)
+      if (match = /\Argb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)\z/.match(text))
+        return match.captures.all? { |channel| channel.to_i <= 255 }
+      end
+      if (match = /\Ahsl\(\s*(\d{1,3})\s*,\s*(\d{1,3})%\s*,\s*(\d{1,3})%\s*\)\z/.match(text))
+        return match[1].to_i <= 360 && match[2].to_i <= 100 && match[3].to_i <= 100
+      end
+      false
+    end
+  end
+end