breadkit-lint 0.1.0 → 0.2.0

data/docs/rules/Intent/MeasurementUnavailable.md

@@ -0,0 +1,10 @@
+# Intent/MeasurementUnavailable
+
+An `expect_voltage` or `expect_current` declaration cannot be checked because
+the DC model has no value for that net or component. The warning includes the
+reason, such as an active GPIO output with an unknown drive state or a floating
+voltage reference.
+
+Connect a grounded source and supported passive parts, or check the circuit
+with a simulator that models the unsupported device. This warning does not
+mean the declared range passed.

data/docs/rules/Layout/AmbiguousSupplySource.md

@@ -0,0 +1,5 @@
+# Layout/AmbiguousSupplySource
+
+`supply from:` refers to a pin that matches more than one provided power output. Give each output a distinct positive pin in the part definition so the source has one matching return pin and voltage.
+
+This error prevents dependent electrical checks from running because the intended source cannot be determined.

data/docs/rules/Layout/BodyOverlap.md

@@ -0,0 +1,11 @@
+# Layout/BodyOverlap
+
+Two component bodies intersect even though their leads use different holes. This rule checks rectangular modules with `render.size_mm`, DIP bodies whose complete pin rows establish their position, and circular 5 mm LED bodies (`led_5mm` or `rgb_led_5mm`). Touching edges do not count as an overlap.
+
+```ruby
+board :half
+led :D1, anode: "a10", cathode: "a11"
+led :D2, anode: "b11", cathode: "b12"
+```
+
+Move one part until its body clears the other. The DIP rectangle follows the rendered body between its pin rows; incomplete or misaligned DIP placements are skipped. Other component shapes without reliable body dimensions are not checked. Module comparisons are skipped when the installed Breadkit version cannot provide body bounds.

data/docs/rules/Layout/HoleCovered.md

@@ -0,0 +1,11 @@
+# Layout/HoleCovered
+
+A module or DIP body covers a hole used by another component lead or an electrical wire endpoint. The check uses the module's `render.size_mm`, or a complete DIP pin arrangement, and physical hole positions. Move the lead or wire endpoint to a visible hole; a hole on the same conductive strip is fine if it is outside the body.
+
+```ruby
+board :half
+part :U1, :pico, at: "d1"
+resistor :R1, "330", pins: %w[e10 a25] # e10 is under U1
+```
+
+The owner's own pins, holes on the body boundary, and visual wires (`electrical: false`) are ignored. A standard DIP sits in the breadboard ravine, so it normally covers no holes. Module checks are skipped when an older Breadkit version cannot provide body geometry.

data/docs/rules/Layout/InvalidColor.md

@@ -0,0 +1,3 @@
+# Layout/InvalidColor
+
+A component or wire color is not a valid CSS color. Use a named color, hex, `rgb()`, or `hsl()`.

data/docs/rules/Layout/InvalidOption.md

@@ -0,0 +1,3 @@
+# Layout/InvalidOption
+
+A component attribute has a value outside its part definition. Use an allowed value.

data/docs/rules/Layout/InvalidRoute.md

@@ -0,0 +1,3 @@
+# Layout/InvalidRoute
+
+A wire route is not supported. Use a route accepted by the breadkit DSL.

data/docs/rules/Layout/InvalidValue.md

@@ -0,0 +1,3 @@
+# Layout/InvalidValue
+
+A component value cannot be parsed for its part category. Check digits and unit suffixes.

data/docs/rules/Layout/InvalidWireId.md

@@ -0,0 +1,3 @@
+# Layout/InvalidWireId
+
+A wire ID looks like a board hole and makes references ambiguous. Choose a distinct ID such as `W20`.

data/docs/rules/Layout/LeadSpan.md

@@ -0,0 +1,21 @@
+# Layout/LeadSpan
+
+A two-lead part is placed farther apart than its declared `max_lead_span_mm`. The rule measures the straight-line distance between the two board holes using the board's 2.54 mm pitch.
+
+```yaml
+id: limited_resistor
+category: passive
+placement: leads
+pins:
+  - {num: 1, name: "1"}
+  - {num: 2, name: "2"}
+max_lead_span_mm: 7.62
+```
+
+```ruby
+board :half
+use_parts "limited_resistor.yml"
+part :R1, :limited_resistor, pins: %w[a10 a14] # 10.16 mm exceeds 7.62 mm
+```
+
+Move the holes closer together or choose a part with a suitable lead span. Parts without declared `max_lead_span_mm` and incomplete placements are skipped; the rule does not assume a generic lead length.

data/docs/rules/Layout/PartOverride.md

@@ -0,0 +1,3 @@
+# Layout/PartOverride
+
+A custom part replaces a built-in definition. Verify its pinout and attributes before using it.

data/docs/rules/Layout/UnknownSupplySource.md

@@ -0,0 +1,5 @@
+# Layout/UnknownSupplySource
+
+`supply from:` refers to a pin that is not a provided power output of an offboard component. Check the component reference and choose one of its declared power outputs, such as `UNO.5V`.
+
+This error prevents dependent electrical checks from running because the intended source cannot be connected.

data/docs/rules/Layout/UnmatchedParts.md

@@ -0,0 +1,3 @@
+# Layout/UnmatchedParts
+
+The `use_parts` path matches no files. Check its spelling and location relative to the circuit file.

data/docs/rules/Layout/WireOverIC.md

@@ -0,0 +1,11 @@
+# Layout/WireOverIC
+
+A straight electrical jumper crosses a DIP IC body in the layout. This informational finding helps when planning a build where the jumper should not pass above the chip. Route the wire around the chip if clearance matters.
+
+```ruby
+board :half
+ic :U1, :ne555, at: "e10"
+wire "a11", "j11" # Crosses U1
+```
+
+The rule estimates the standard DIP body from all placed pins: it requires two pin rows separated by three hole pitches. It checks only straight electrical wires whose endpoints are board holes. Curved and edge routes, visual alternatives, incomplete ICs, and non-DIP packages are outside this check.

data/docs/rules/Lint/RedundantDisable.md

@@ -0,0 +1,3 @@
+# Lint/RedundantDisable
+
+A `lint_disable` declaration suppresses no offense. Remove it or correct its rule and target.

data/docs/rules/Lint/UnknownRuleInDisable.md

@@ -0,0 +1,5 @@
+# Lint/UnknownRuleInDisable
+
+A `lint_disable` declaration names a rule that Breadkit Lint does not know.
+Check the rule name with `bklint --list-rules`; unknown names do not suppress
+any findings.

data/lib/breadkit/lint/baseline.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Breadkit
+  module Lint
+    class Baseline
+      def initialize(path)
+        @path = File.expand_path(path)
+      end
+
+      def write(files)
+        raise Error, "cannot baseline fatal errors" if files.any? { |file| file[:offenses].any? { |item| item.rule.start_with?("Fatal/") } }
+
+        entries = files.flat_map { |file| file[:offenses].map { |item| entry(file, item) } }.uniq
+        File.write(@path, JSON.pretty_generate(schema_version: 1, entries: entries) + "\n", encoding: "UTF-8")
+        entries.length
+      end
+
+      def filter(files)
+        data = JSON.parse(File.read(@path, encoding: "UTF-8"))
+        raise Error, "invalid baseline: expected schema_version 1 and entries" unless data.is_a?(Hash) && data["schema_version"] == 1 && data["entries"].is_a?(Array) && data["entries"].all? { |item| item.is_a?(Hash) }
+
+        known = data["entries"].to_set
+        files.map { |file| file.merge(offenses: file[:offenses].reject { |item| !item.rule.start_with?("Fatal/") && known.include?(entry(file, item)) }) }
+      end
+
+      private
+
+      def entry(file, item)
+        path = item.location&.path || file[:path]
+        relative = Pathname.new(File.expand_path(path)).relative_path_from(Pathname.new(File.dirname(@path))).to_s.tr("\\", "/")
+        targets = item.targets.to_h.sort_by { |key, _value| key.to_s }.to_h.transform_keys(&:to_s)
+                      .transform_values { |value| Array(value).map(&:to_s).sort }
+        { "path" => relative, "rule" => item.rule, "severity" => item.severity,
+          "message" => item.message, "state" => item.state, "targets" => targets }
+      end
+    end
+  end
+end

data/lib/breadkit/lint/rake_task.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rake/tasklib"
+require "breadkit/lint"
+
+module Breadkit
+  class RakeTask < Rake::TaskLib
+    attr_accessor :files, :options
+
+    def initialize(name = :breadkit)
+      super()
+      @files = []
+      @options = []
+      yield self if block_given?
+      desc "Lint Breadkit circuits"
+      task name do
+        status = Breadkit::Lint::CLI.new.run(Array(options) + Array(files))
+        raise Breadkit::Lint::Error, "bklint failed with status #{status}" unless status.zero?
+      end
+    end
+  end
+end