breadkit 0.1.0 → 0.2.0

data/lib/breadkit/ir.rb

@@ -6,41 +6,59 @@ module Breadkit
   module IR
     class Writer
       def write(circuit)
+        @source_root = circuit.source_root || Dir.pwd
         library = PartLibrary.new
         part_definitions = circuit.components.values.map(&:part).uniq.filter_map do |part|
           standard = library.find(part.id, pin_count: part.pins.length)
           part.data unless standard&.data == part.data
         end
         result = {
-          schema_version: 1,
+          schema_version: circuit.multi_board? ? 2 : 1,
+          source_root: @source_root,
           title: circuit.title,
           board: { type: circuit.board.definition.id, options: { split_rails: circuit.board.split_rails } },
           board_definition: circuit.board.definition.data,
-          supplies: circuit.supplies.map { |item| { name: item.name, voltage: item.voltage, plus: item.plus, minus: item.minus, source: source(item.location) } },
-          labels: circuit.labels.map { |item| { net: item.name, at: item.at, source: source(item.location) } },
+          supplies: circuit.supplies.map { |item| { name: item.name, voltage: item.voltage, plus: item.plus, minus: item.minus,
+                                                   isolated: item.isolated == true, voltage_range: item.voltage_range,
+                                                   current_limit: item.current_limit,
+                                                   source: source(item.location) }.merge(step_field(item)) },
+          labels: circuit.labels.map { |item| { net: item.name, at: item.at, source: source(item.location) }.merge(step_field(item)) },
           components: circuit.components.values.map do |component|
             { ref: component.ref, part: component.part.id, value: component.value,
               attrs: stringify(component.attrs), pins: component.pins.transform_values(&:hole_id),
-              unused: component.unused, source: source(component.location) }
+              unused: component.unused, source: source(component.location) }.merge(step_field(component))
           end,
           wires: circuit.wires.map { |wire| { id: wire.id, from: wire.from, to: wire.to, color: wire.color, route: wire.route,
                                                layer: wire.layer, electrical: wire.electrical, dashed: wire.dashed,
-                                               source: source(wire.location) } },
+                                               source: source(wire.location) }.merge(step_field(wire)) },
           expectations: stringify(circuit.expectations),
           lint_disables: stringify(circuit.lint_disables),
           analysis: { nets: circuit.nets.map { |net| { name: net.name, members: net.members, holes: net.holes, potential: circuit.potentials.values[net.name] } } }
         }
+        if circuit.multi_board?
+          result.delete(:board)
+          result.delete(:board_definition)
+          result[:boards] = circuit.boards.map do |name, board|
+            { name: name, type: board.definition.id, options: { split_rails: board.split_rails },
+              definition: board.definition.data }
+          end
+        end
+        result[:steps] = circuit.steps.map { |item| { number: item[:number], title: item[:title], source: source(item[:source]) } } unless circuit.steps.empty?
         result[:part_definitions] = part_definitions unless part_definitions.empty?
         result
       end
 
       private
 
+      def step_field(item)
+        item.step ? { step: item.step } : {}
+      end
+
       def source(location)
         return nil unless location && location.path && location.line
 
         path = Pathname.new(location.path)
-        path = path.relative_path_from(Pathname.pwd) if path.absolute?
+        path = path.relative_path_from(Pathname.new(@source_root)) if path.absolute?
         { path: path.to_s, line: location.line }
       end
 
@@ -66,26 +84,41 @@ module Breadkit
       def read(data)
         data = stringify_keys(data)
         validate!(data)
+        @source_root = data["source_root"]
         doc = Document.new
+        doc.source_root = @source_root
         doc.title = data["title"]
-        doc.board = { type: data.dig("board", "type") || "full", options: (data.dig("board", "options") || {}).transform_keys(&:to_sym) }
-        doc.board_definitions = [data["board_definition"]] if data["board_definition"]
+        doc.steps = Array(data["steps"]).map do |item|
+          { number: item.fetch("number"), title: item["title"], source: location(item["source"]) }
+        end
+        if data["schema_version"] == 2
+          doc.boards = data.fetch("boards").map do |item|
+            { name: item.fetch("name"), type: item.fetch("type"), options: item.fetch("options").transform_keys(&:to_sym) }
+          end
+          doc.board_definitions = data.fetch("boards").map { |item| item.fetch("definition") }.uniq
+        else
+          doc.board = { type: data.dig("board", "type") || "full", options: (data.dig("board", "options") || {}).transform_keys(&:to_sym) }
+          doc.board_definitions = [data["board_definition"]] if data["board_definition"]
+        end
         doc.supplies = Array(data["supplies"]).map do |item|
-          { name: item.fetch("name"), voltage: Value.parse(item.fetch("voltage")), plus: item.fetch("plus"), minus: item.fetch("minus"), location: location(item["source"]) }
+          { name: item.fetch("name"), voltage: Value.parse(item.fetch("voltage")), plus: item.fetch("plus"),
+            minus: item.fetch("minus"), isolated: item["isolated"] == true,
+            voltage_range: item["voltage_range"], current_limit: item["current_limit"],
+            location: location(item["source"]), step: item["step"] }
         end
         doc.labels = Array(data["labels"]).map do |item|
-          { name: item.fetch("net"), at: item.fetch("at"), location: location(item["source"]) }
+          { name: item.fetch("net"), at: item.fetch("at"), location: location(item["source"]), step: item["step"] }
         end
         doc.components = Array(data["components"]).map do |item|
           { ref: item.fetch("ref"), type: item.fetch("part"), value: item["value"],
             pins: item["pins"] || {}, at: nil, attrs: (item["attrs"] || {}).transform_keys(&:to_sym),
-            unused: item["unused"] || [], location: location(item["source"]) }
+            unused: item["unused"] || [], location: location(item["source"]), step: item["step"] }
         end
         doc.part_definitions = Array(data["part_definitions"])
         doc.wires = Array(data["wires"]).map do |item|
           { id: item["id"], from: item.fetch("from"), to: item.fetch("to"), color: item["color"],
             route: item["route"] || "straight", layer: item["layer"], electrical: item["electrical"] != false,
-            dashed: item["dashed"] == true, location: location(item["source"]) }
+            dashed: item["dashed"] == true, location: location(item["source"]), step: item["step"] }
         end
         doc.expectations = Array(data["expectations"])
         doc.lint_disables = Array(data["lint_disables"]).map do |item|
@@ -100,17 +133,40 @@ module Breadkit
 
       def validate!(data)
         require_hash(data, "root")
-        raise DSLError, "unsupported IR schema_version" unless data["schema_version"] == 1
+        raise DSLError, "unsupported IR schema_version" unless [1, 2].include?(data["schema_version"])
         raise DSLError, "invalid IR: title must be text or null" unless data["title"].nil? || data["title"].is_a?(String)
+        raise DSLError, "invalid IR: source_root must be text" if data.key?("source_root") && !data["source_root"].is_a?(String)
 
-        board = require_hash(data["board"], "board")
-        require_string(board["type"], "board.type")
-        options = require_hash(board["options"], "board.options")
-        unless !options.key?("split_rails") || [true, false].include?(options["split_rails"])
-          raise DSLError, "invalid IR: board.options.split_rails must be boolean"
+        if data["schema_version"] == 2
+          validate_named_boards(data)
+        else
+          board = require_hash(data["board"], "board")
+          require_string(board["type"], "board.type")
+          validate_board_options(board["options"], "board.options")
+          validate_board_definition(data["board_definition"]) if data.key?("board_definition")
         end
-        validate_board_definition(data["board_definition"]) if data.key?("board_definition")
+        validate_steps(data)
         validate_records(data, "supplies", %w[name plus minus], %w[voltage])
+        data.fetch("supplies").each_with_index do |item, index|
+          voltage = item["voltage"]
+          unless voltage.is_a?(Numeric) && voltage.finite? && voltage.positive?
+            raise DSLError, "invalid IR: supplies[#{index}].voltage must be positive"
+          end
+          unless !item.key?("isolated") || [true, false].include?(item["isolated"])
+            raise DSLError, "invalid IR: supplies[#{index}].isolated must be boolean"
+          end
+          range = item["voltage_range"]
+          unless range.nil? || (range.is_a?(Array) && range.length == 2 && range.all? { |value| value.is_a?(Numeric) && value.finite? && value.positive? } && range[0] <= range[1])
+            raise DSLError, "invalid IR: supplies[#{index}].voltage_range must be two ascending positive numbers"
+          end
+          if range && (voltage < range[0] || voltage > range[1])
+            raise DSLError, "invalid IR: supplies[#{index}].voltage must be within voltage_range"
+          end
+          limit = item["current_limit"]
+          unless limit.nil? || (limit.is_a?(Numeric) && limit.real? && limit.finite? && limit.positive?)
+            raise DSLError, "invalid IR: supplies[#{index}].current_limit must be positive"
+          end
+        end
         validate_records(data, "labels", %w[net at])
         validate_records(data, "components", %w[ref part])
         validate_records(data, "wires", %w[id from to])
@@ -135,19 +191,93 @@ module Breadkit
         end
         data.fetch("expectations").each_with_index do |item, index|
           require_source(item["location"], "expectations[#{index}].location")
+          require_string(item["when"], "expectations[#{index}].when") if item.key?("when")
           require_array(item["entries"], "expectations[#{index}].entries")
           item["entries"].each_with_index do |entry, entry_index|
             require_hash(entry, "expectations[#{index}].entries[#{entry_index}]")
-            unless %w[connected isolated net].include?(entry["kind"])
+            unless %w[connected isolated net voltage current].include?(entry["kind"])
               raise DSLError, "invalid IR: expectations[#{index}].entries[#{entry_index}].kind is unknown"
             end
-            require_array(entry["refs"], "expectations[#{index}].entries[#{entry_index}].refs")
+            refs = require_array(entry["refs"], "expectations[#{index}].entries[#{entry_index}].refs")
+            if %w[voltage current].include?(entry["kind"])
+              range = entry["range"]
+              valid_refs = refs.length == 1 && refs.first.is_a?(String) && !refs.first.empty?
+              unless valid_refs && range.is_a?(Array) && range.length == 2 && range.all? { |value| value.is_a?(Numeric) && value.finite? } && range[0] <= range[1] && (entry["kind"] != "current" || range[0] >= 0)
+                raise DSLError, "invalid IR: expectations[#{index}].entries[#{entry_index}].range is invalid"
+              end
+            end
             require_source(entry["location"], "expectations[#{index}].entries[#{entry_index}].location")
           end
         end
         require_array(require_hash(data["analysis"], "analysis")["nets"], "analysis.nets") if data.key?("analysis")
       end
 
+      def validate_named_boards(data)
+        raise DSLError, "invalid IR: v2 must use boards instead of board" if data.key?("board") || data.key?("board_definition")
+
+        boards = require_array(data["boards"], "boards")
+        raise DSLError, "invalid IR: boards must not be empty" if boards.empty?
+
+        names = {}
+        definitions = {}
+        boards.each_with_index do |item, index|
+          item = require_hash(item, "boards[#{index}]")
+          name = item["name"]
+          unless name.is_a?(String) && /\A[A-Za-z][A-Za-z0-9_]*\z/.match?(name)
+            raise DSLError, "invalid IR: boards[#{index}].name is invalid"
+          end
+          raise DSLError, "invalid IR: duplicate board name #{name}" if names[name.downcase]
+          names[name.downcase] = true
+          require_string(item["type"], "boards[#{index}].type")
+          validate_board_options(item["options"], "boards[#{index}].options")
+          definition = item["definition"]
+          validate_board_definition(definition)
+          unless definition["id"] == item["type"]
+            raise DSLError, "invalid IR: boards[#{index}].definition.id must match type"
+          end
+          begin
+            board = Board.new(BoardDef.new(definition), split_rails: item.fetch("options").fetch("split_rails", false))
+            raise ArgumentError, "board has no holes" if board.holes.empty?
+          rescue StandardError => e
+            raise DSLError, "invalid IR: boards[#{index}].definition: #{e.message}"
+          end
+          if definitions.key?(item["type"]) && definitions[item["type"]] != definition
+            raise DSLError, "invalid IR: conflicting definitions for board type #{item['type']}"
+          end
+          definitions[item["type"]] = definition
+        end
+      end
+
+      def validate_board_options(value, path)
+        options = require_hash(value, path)
+        unless !options.key?("split_rails") || [true, false].include?(options["split_rails"])
+          raise DSLError, "invalid IR: #{path}.split_rails must be boolean"
+        end
+      end
+
+      def validate_steps(data)
+        steps = data.fetch("steps", [])
+        require_array(steps, "steps").each_with_index do |item, index|
+          require_hash(item, "steps[#{index}]")
+          raise DSLError, "invalid IR: steps[#{index}].number must be #{index + 1}" unless item["number"] == index + 1
+          unless item["title"].nil? || (item["title"].is_a?(String) && !item["title"].empty?)
+            raise DSLError, "invalid IR: steps[#{index}].title must be nonempty text or null"
+          end
+          require_source(item["source"], "steps[#{index}].source") if item.key?("source")
+        end
+        %w[supplies labels components wires].each do |key|
+          next unless data[key].is_a?(Array)
+
+          data[key].each_with_index do |item, index|
+            next unless item.is_a?(Hash) && item.key?("step")
+            number = item["step"]
+            unless number.is_a?(Integer) && number.positive? && number <= steps.length
+              raise DSLError, "invalid IR: #{key}[#{index}].step must reference a declared step"
+            end
+          end
+        end
+      end
+
       def validate_board_definition(value)
         board = require_hash(value, "board_definition")
         require_string(board["id"], "board_definition.id")
@@ -200,7 +330,9 @@ module Breadkit
 
       def location(source)
         return nil unless source
-        SourceLocation.new(path: source["path"], line: source["line"])
+        path = source["path"]
+        path = File.expand_path(path, @source_root) if @source_root && !Pathname.new(path).absolute?
+        SourceLocation.new(path: path, line: source["line"])
       end
 
       def stringify_keys(value)

data/lib/breadkit/jumper_kit.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Breadkit
+  class JumperKit
+    MAX_JUMPERS = 1000
+    VERIFIED_BOARDS = %w[mini half full double_full].freeze
+
+    def self.load(path)
+      source = File.read(path, encoding: "UTF-8")
+      data = case File.extname(path).downcase
+             when ".yml", ".yaml" then YAML.safe_load(source, aliases: false)
+             when ".json" then JSON.parse(source)
+             else raise ArgumentError, "jumper inventory must be YAML or JSON"
+             end
+      new(data)
+    rescue Psych::Exception, JSON::ParserError => error
+      raise ArgumentError, "invalid jumper inventory: #{error.message}"
+    end
+
+    def initialize(data)
+      unless data.is_a?(Hash) && (data.keys - %w[wires measured_routes]).empty? && data["wires"].is_a?(Array)
+        raise ArgumentError, "jumper inventory needs a wires list and optional measured_routes"
+      end
+
+      measured = data.fetch("measured_routes", {})
+      unless measured.is_a?(Hash) && measured.all? { |id, span| id.is_a?(String) && !id.empty? &&
+               span.is_a?(Numeric) && span.real? && span.finite? && span.positive? }
+        raise ArgumentError, "invalid measured_routes; use positive millimeter spans keyed by wire ID"
+      end
+      @measured_routes = measured.transform_values(&:to_f)
+
+      @slots = data.fetch("wires").flat_map do |item|
+        unless item.is_a?(Hash) && (item.keys - %w[color usable_span_mm count]).empty? &&
+               %w[color usable_span_mm count].all? { |key| item.key?(key) }
+          raise ArgumentError, "invalid jumper inventory entry"
+        end
+
+        color, span, count = item.values_at("color", "usable_span_mm", "count")
+        unless color.is_a?(String) && !color.strip.empty? && span.is_a?(Numeric) && span.real? &&
+               span.finite? && span.positive? && count.is_a?(Integer) && count.positive? && count <= MAX_JUMPERS
+          raise ArgumentError, "invalid jumper color, usable_span_mm, or count"
+        end
+
+        Array.new(count) { { color: color.downcase, usable_span_mm: span.to_f } }
+      end
+      raise ArgumentError, "jumper inventory exceeds #{MAX_JUMPERS} pieces" if @slots.length > MAX_JUMPERS
+    end
+
+    def allocate(circuit)
+      raise ArgumentError, "circuit has errors" if circuit.diagnostics.any? { |item| item.severity == "error" }
+      unknown = @measured_routes.keys - circuit.wires.map(&:id)
+      raise ArgumentError, "measured_routes names unknown wire #{unknown.first}" unless unknown.empty?
+
+      eligible, skipped = [], []
+      circuit.wires.each do |wire|
+        left, right = [wire.from, wire.to].map { |endpoint| circuit.board.hole(endpoint) }
+        reason = skip_reason(circuit, wire, left, right)
+        measured_span = @measured_routes[wire.id]
+        raise ArgumentError, "measured route #{wire.id} refers to a visual-only wire" if measured_span && wire.electrical == false
+
+        if reason && !measured_span
+          skipped << { wire: wire.id, reason: reason }
+        else
+          modeled_span = Math.hypot(left.x - right.x, left.y - right.y) * 2.54 unless reason
+          if modeled_span && measured_span && measured_span + 1e-9 < modeled_span
+            raise ArgumentError, "measured route #{wire.id} is shorter than its modeled endpoint span"
+          end
+          eligible << { wire: wire.id, color: wire.color&.downcase,
+                        minimum_span_mm: modeled_span, required_span_mm: measured_span || modeled_span,
+                        span_source: measured_span ? "measured" : "board_geometry" }
+        end
+      end
+
+      candidates = eligible.to_h do |wire|
+        compatible = @slots.each_index.select do |index|
+          slot = @slots.fetch(index)
+          (!wire[:color] || slot[:color] == wire[:color]) && slot[:usable_span_mm] + 1e-9 >= wire[:required_span_mm]
+        end.sort_by { |index| [@slots[index][:usable_span_mm], @slots[index][:color], index] }
+        [wire[:wire], compatible]
+      end
+      owners, assigned = {}, {}
+      eligible.sort_by { |wire| [candidates.fetch(wire[:wire]).length, -wire[:required_span_mm], wire[:wire]] }
+        .each { |wire| assign(wire[:wire], candidates, owners, assigned, {}) }
+
+      assignments = eligible.filter_map do |wire|
+        slot = @slots[assigned[wire[:wire]]] if assigned.key?(wire[:wire])
+        { wire: wire[:wire], color: slot[:color], usable_span_mm: slot[:usable_span_mm],
+          minimum_span_mm: wire[:minimum_span_mm]&.round(2),
+          required_span_mm: wire[:required_span_mm].round(2), span_source: wire[:span_source] } if slot
+      end
+      unassigned = eligible.reject { |wire| assigned.key?(wire[:wire]) }
+        .map { |wire| { wire: wire[:wire], reason: "no compatible jumper in inventory" } }
+      { assignments: assignments, unassigned: unassigned, skipped: skipped }
+    end
+
+    private
+
+    def skip_reason(circuit, wire, left, right)
+      return "visual-only wire" if wire.electrical == false
+      return "route length is not modeled" unless wire.route == "straight"
+      return "both endpoints must be board holes" unless left && right
+      return "cross-board distance is not modeled" if circuit.multi_board? && left.id.split(".", 2).first != right.id.split(".", 2).first
+      return "rail distance is not modeled" unless left.kind == :terminal && right.kind == :terminal
+      return "solder attachment is not a jumper socket" if circuit.board.solder_pad?(left.id) || circuit.board.solder_pad?(right.id)
+      board = circuit.multi_board? ? circuit.boards.fetch(left.id.split(".", 2).first) : circuit.board
+      return "board pitch is not verified" unless VERIFIED_BOARDS.include?(board.definition.id) &&
+                                                 board.definition.data == BoardDef.load(board.definition.id).data
+
+      nil
+    end
+
+    def assign(wire_id, candidates, owners, assigned, seen)
+      candidates.fetch(wire_id).each do |index|
+        next if seen[index]
+
+        seen[index] = true
+        previous = owners[index]
+        next if previous && !assign(previous, candidates, owners, assigned, seen)
+
+        owners[index] = wire_id
+        assigned[wire_id] = index
+        return true
+      end
+      false
+    end
+  end
+end

data/lib/breadkit/lsp_server.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../breadkit"
+
+module Breadkit
+  # A small LSP 3.18 server. Only full document synchronization is advertised.
+  class LSPServer
+    MAX_MESSAGE_BYTES = 8 * 1024 * 1024
+    CIRCUIT_SUFFIXES = %w[.bk.yml .bk.yaml .bk.toml .bk.rb].freeze
+
+    def initialize(input: $stdin, output: $stdout, root: nil, trusted_ruby: false)
+      raise ArgumentError, "--trusted-ruby requires --root" if trusted_ruby && !root
+
+      @input, @output = input, output
+      @root = File.realpath(root) if root
+      raise ArgumentError, "LSP root must be a directory" if @root && !File.directory?(@root)
+      @trusted_ruby = trusted_ruby
+      @documents = {}
+      @running = true
+    end
+
+    def run
+      while @running && (message = read_message)
+        handle(message)
+      end
+    end
+
+    private
+
+    def read_message
+      headers = {}
+      while (line = @input.gets)
+        break if line == "\r\n" || line == "\n"
+        key, value = line.split(":", 2)
+        headers[key.downcase] = value&.strip if key
+      end
+      return unless line
+
+      size = Integer(headers.fetch("content-length"))
+      raise ArgumentError, "LSP message exceeds 8 MiB" unless size.between?(1, MAX_MESSAGE_BYTES)
+
+      body = @input.read(size)
+      raise EOFError, "truncated LSP message" unless body && body.bytesize == size
+      JSON.parse(body)
+    end
+
+    def send_message(message)
+      body = JSON.generate({ jsonrpc: "2.0" }.merge(message))
+      @output.write("Content-Length: #{body.bytesize}\r\n\r\n")
+      @output.write(body)
+      @output.flush
+    end
+
+    def reply(id, result)
+      send_message(id: id, result: result)
+    end
+
+    def handle(message)
+      method = message["method"]
+      params = message["params"] || {}
+      case method
+      when "initialize"
+        reply(message["id"], { capabilities: { textDocumentSync: 1, hoverProvider: true,
+                                               completionProvider: { triggerCharacters: [".", ":", "\"", "'"] } },
+                               serverInfo: { name: "breadkit", version: VERSION } })
+      when "shutdown" then reply(message["id"], nil)
+      when "exit" then @running = false
+      when "textDocument/didOpen" then open_document(params.fetch("textDocument"))
+      when "textDocument/didChange" then change_document(params)
+      when "textDocument/didClose" then close_document(params.fetch("textDocument").fetch("uri"))
+      when "textDocument/completion" then reply(message["id"], completion(params))
+      when "textDocument/hover" then reply(message["id"], hover(params))
+      else
+        send_message(id: message["id"], error: { code: -32_601, message: "Method not found" }) if message.key?("id")
+      end
+    rescue StandardError => e
+      send_message(id: message["id"], error: { code: -32_603, message: e.message }) if message.key?("id")
+    end
+
+    def open_document(document)
+      uri = document.fetch("uri")
+      path = file_path(uri)
+      return unless path && CIRCUIT_SUFFIXES.any? { |suffix| path.end_with?(suffix) }
+
+      @documents[uri] = { path: path, text: document.fetch("text"), version: document["version"] }
+      analyze(uri)
+    end
+
+    def change_document(params)
+      uri = params.fetch("textDocument").fetch("uri")
+      document = @documents[uri]
+      return unless document
+
+      # Incremental changes are not advertised. Clients must send the full text.
+      change = params.fetch("contentChanges").last
+      return if change.key?("range")
+
+      document[:text] = change.fetch("text")
+      document[:version] = params["textDocument"]["version"]
+      analyze(uri)
+    end
+
+    def close_document(uri)
+      return unless @documents.delete(uri)
+
+      send_message(method: "textDocument/publishDiagnostics", params: { uri: uri, diagnostics: [] })
+    end
+
+    def analyze(uri)
+      document = @documents.fetch(uri)
+      path, source = document.values_at(:path, :text)
+      circuit = if path.end_with?(".bk.rb")
+        Resolver.new.call(DSL.load_file(path, source: source, timeout: 2)) if @trusted_ruby && @root
+      else
+        parsed = StructuredInput.load_source(path, source)
+        (parsed.part_paths + parsed.board_paths).each { |dependency| ensure_inside_root(dependency) } if @root
+        PartLock.verify(parsed, path)
+        Resolver.new.call(parsed)
+      end
+      document[:circuit] = circuit
+      diagnostics = circuit ? circuit.diagnostics.map { |item| diagnostic(item, source) } : []
+      publish(uri, document, diagnostics)
+    rescue DSLError, ArgumentError, Psych::Exception => e
+      document[:circuit] = nil
+      location = e.respond_to?(:location) ? e.location : nil
+      line = location&.line || (e.respond_to?(:line) && e.line) || 1
+      publish(uri, document, [diagnostic_for("invalid_source", e.message, "error", line, source)])
+    end
+
+    def publish(uri, document, diagnostics)
+      send_message(method: "textDocument/publishDiagnostics",
+                   params: { uri: uri, version: document[:version], diagnostics: diagnostics })
+    end
+
+    def diagnostic(item, source)
+      diagnostic_for(item.code, item.message, item.severity, item.location&.line, source)
+    end
+
+    def diagnostic_for(code, message, severity, line, source)
+      index = [[line.to_i - 1, 0].max, source.lines.length - 1].min
+      index = 0 if index.negative?
+      end_character = source.lines[index].to_s.chomp.encode("UTF-16LE").bytesize / 2
+      { range: { start: { line: index, character: 0 }, end: { line: index, character: end_character } },
+        severity: { "error" => 1, "warning" => 2, "info" => 3 }.fetch(severity, 3),
+        code: code, source: "breadkit", message: message }
+    end
+
+    def completion(params)
+      document = @documents[params.dig("textDocument", "uri")]
+      return [] unless document
+
+      prefix = token_prefix(document[:text], params.fetch("position"))
+      return [] if prefix.empty?
+
+      circuit = document[:circuit]
+      board = circuit&.board || board_from_source(document)
+      candidates = board ? board.holes.keys + board.rail_ids : []
+      if circuit
+        circuit.components.each_value do |component|
+          component.part.pins.each do |pin|
+            ([pin["num"], pin["name"]] + Array(pin["aliases"])).compact.each do |name|
+              candidates << "#{component.ref}.#{name}"
+            end
+          end
+        end
+        candidates.concat(circuit.labels.map(&:name))
+      end
+      candidates.uniq.grep(/\A#{Regexp.escape(prefix)}/i).first(200).map do |name|
+        { label: name, kind: name.include?(".") ? 5 : 6 }
+      end
+    end
+
+    def hover(params)
+      document = @documents[params.dig("textDocument", "uri")]
+      circuit = document && document[:circuit]
+      return unless circuit && circuit.diagnostics.none? { |item| item.severity == "error" }
+
+      reference = token_at(document[:text], params.fetch("position"))
+      net = circuit.net_of(reference) if reference
+      return unless net
+
+      voltage = net.potential.nil? ? "unknown" : "#{net.potential} V"
+      { contents: { kind: "markdown", value: "**#{reference}** · net `#{net.name}`\n\nPotential: #{voltage}" } }
+    end
+
+    def token_prefix(source, position)
+      before = before_position(source, position)
+      before[/[A-Za-z0-9_.+\-]+\z/] || ""
+    end
+
+    def token_at(source, position)
+      line = source.lines[position.fetch("line")].to_s
+      before = before_position(source, position)
+      after = line[before.length..].to_s
+      left = before[/[A-Za-z0-9_.+\-]+\z/].to_s
+      right = after[/\A[A-Za-z0-9_.+\-]+/].to_s
+      value = left + right
+      value unless value.empty?
+    end
+
+    def before_position(source, position)
+      line = source.lines[position.fetch("line")].to_s
+      units = position.fetch("character")
+      count = 0
+      line.each_char.take_while do |char|
+        count += char.encode("UTF-16LE").bytesize / 2
+        count <= units
+      end.join
+    end
+
+    def board_from_source(document)
+      source = document[:text]
+      type = if document[:path].end_with?(".bk.rb")
+        source[/^\s*board\s+:(\w+)/, 1]
+      elsif document[:path].end_with?(".toml")
+        source[/^\s*board\s*=\s*["']([\w-]+)["']/, 1]
+      else
+        source[/^\s*board:\s*([\w-]+)/, 1]
+      end
+      Board.new(BoardDef.load(type)) if type
+    rescue ArgumentError
+      nil
+    end
+
+    def file_path(uri)
+      parsed = URI.parse(uri)
+      return unless parsed.scheme == "file"
+
+      path = URI::DEFAULT_PARSER.unescape(parsed.path)
+      path = path.delete_prefix("/") if Gem.win_platform? && path.match?(%r{\A/[A-Za-z]:/})
+      expanded = File.expand_path(path)
+      ensure_inside_root(expanded) if @root
+      expanded
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def ensure_inside_root(path)
+      expanded = File.expand_path(path)
+      ancestor = expanded
+      ancestor = File.dirname(ancestor) until File.exist?(ancestor)
+      expanded = File.realpath(ancestor) + expanded.delete_prefix(ancestor)
+      prefix = @root == File::SEPARATOR ? @root : "#{@root}#{File::SEPARATOR}"
+      raise ArgumentError, "path is outside the LSP root" unless expanded.start_with?(prefix)
+    end
+  end
+end