breadkit-lint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ae47ac3ae7217a2a82b7515f278ad803d0784545f85d469cac5bb5256a5d56a
+  data.tar.gz: 123c596bd7f50e9da23e73d90e4fb6ad2c4ed8d9fe88274ba519497eec420a75
+SHA512:
+  metadata.gz: e7391a75a996a8068d8c9446c704d6ac6d13d3d44b3ce4adfc3a827ed4e7980868540baecb3c90a4839b06c287a05d3ac8d618e2af120ee784b88b9b02d31799
+  data.tar.gz: b87c6a614fdad6c4d9392fde335d48fe82db2f364e72237fe578aa571f72511335ec6ecde1c96a1ea10763640617a76809a18797cc00e6ad5ec6bebea903f7a1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-27
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# breadkit-lint
+
+Project site: https://breadkit.github.io/breadkit-lint/
+
+`bklint` checks Breadkit DSL and IR files for layout, electrical, and wiring-intent problems. DSL files execute as Ruby code; inspect only trusted files. Use IR JSON for data-only input. Configuration `require` entries also execute Ruby code, so load only trusted configuration files.
+
+Install `breadkit-lint` directly; RubyGems installs its compatible `breadkit` core dependency. Shared circuit examples are in the [breadkit repository](https://github.com/breadkit/breadkit/tree/main/examples).
+
+```sh
+bklint circuit.bk.rb
+bklint circuit.bk.rb --only Electrical/ShortCircuit
+bklint circuit.bk.rb --format json --out lint.json
+bklint circuit.bk.rb --format github
+bklint circuit.bk.rb --format sarif --out lint.sarif
+```
+
+## Options
+
+`bklint [options] [FILES...]` accepts `.bk.rb` and Breadkit IR `.json` inputs. Directory arguments are scanned recursively. With no files, it scans visible inputs under the current directory and skips `node_modules`. Each input uses the nearest ancestor `.bklint.yml` unless `--config` is specified.
+
+| Option | Description |
+| --- | --- |
+| `-f, --format FORMAT` | `text` (default), `json`, `github`, or `sarif`. |
+| `-o, --out PATH` | Write formatter output to a file. |
+| `-c, --config PATH` | Load a `.bklint.yml` configuration. |
+| `--fail-level LEVEL` | `error`, `warning` (default), or `info`. |
+| `--only RULES` / `--except RULES` | Select or skip comma-separated rule IDs. |
+| `--switch-states MODE` | Evaluate `none`, `single` (default), or `all` switch states. |
+| `--list-rules` | List registered rules. |
+| `--explain RULE` | Show rule guidance and an example. |
+| `--locale LOCALE` | `ja` or `en` for rule descriptions, messages, and text summary. |
+
+Exit status is `0` when no offense meets the fail level, `1` when one does, and `2` for invalid input, configuration, or command usage.
+
+## Configuration
+
+```yaml
+inherit_from:
+  - ./shared/bklint.yml
+use_parts:
+  - ./parts/*.yml
+
+Electrical/FloatingPin:
+  Severity: error
+
+Style/WireColor:
+  Enabled: true
+  PositiveColors: [red, orange]
+  GroundColors: [black, blue]
+```
+
+All built-in rules and defaults are in [`config/default.yml`](config/default.yml). `.bklint.yml` can also set `AllRules.SwitchStates`, `AllRules.FailLevel`, `AllRules.Exclude`, `AllRules.NewRules` (`pending`, `enable`, or `disable`), `AllRules.RequireDisableReason`, and `require` custom rule files. DSL `lint_disable` declarations suppress a rule globally or for one named component, pin, or wire. Unknown rule IDs are errors; set `reason:` when `RequireDisableReason` is enabled.
+
+Use `bklint --format json` with `bkrender --annotations` to display offense markers on a diagram. Rule guidance is in [`docs/rules`](docs/rules).

data/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+DSL files are executable Ruby. Do not process files from untrusted sources; use IR JSON for data-only input.
+
+Please report suspected vulnerabilities privately through GitHub's Security Advisories feature. Do not include exploit details in a public issue.

data/config/default.yml

@@ -0,0 +1,36 @@
+AllRules:
+  SwitchStates: single
+  FailLevel: warning
+  NewRules: pending
+
+Layout/InvalidHole: {Enabled: true, Severity: error}
+Layout/UnknownBoard: {Enabled: true, Severity: error}
+Layout/UnknownPart: {Enabled: true, Severity: error}
+Layout/UnknownTransistorModel: {Enabled: true, Severity: warning}
+Layout/UnknownPin: {Enabled: true, Severity: error}
+Layout/UnknownOption: {Enabled: true, Severity: error}
+Layout/UnplacedPin: {Enabled: true, Severity: error}
+Layout/DuplicateRef: {Enabled: true, Severity: error}
+Layout/InvalidPlacement: {Enabled: true, Severity: error}
+Layout/HoleConflict: {Enabled: true, Severity: error}
+Layout/NoFreeHole: {Enabled: true, Severity: error}
+Layout/SplitNetLabel: {Enabled: true, Severity: error}
+Layout/PinsInSameStrip: {Enabled: true, Severity: error}
+Electrical/ShortCircuit: {Enabled: true, Severity: error}
+Electrical/ShortedComponent: {Enabled: true, Severity: warning}
+Electrical/FloatingPin: {Enabled: true, Severity: warning}
+Electrical/DanglingWire: {Enabled: true, Severity: warning}
+Electrical/SplitRail: {Enabled: true, Severity: warning}
+Electrical/MissingSeriesResistor: {Enabled: true, Severity: error}
+Electrical/ReversePolarity: {Enabled: true, Severity: error}
+Electrical/PowerPinUnconnected: {Enabled: true, Severity: warning}
+Electrical/SupplyVoltageRange: {Enabled: true, Severity: error}
+Electrical/NoCommonGround: {Enabled: true, Severity: warning}
+Electrical/NetLabelConflict: {Enabled: true, Severity: error}
+Intent/ConnectionMismatch: {Enabled: true, Severity: error}
+Intent/UnknownNet: {Enabled: true, Severity: error}
+Style/WireColor:
+  Enabled: true
+  Severity: info
+  PositiveColors: [red, orange]
+  GroundColors: [black, blue, gray]

data/docs/rules/Electrical/DanglingWire.md

@@ -0,0 +1,9 @@
+# Electrical/DanglingWire
+
+At least one wire end is not connected to another component, supply, or wire on that strip.
+
+```ruby
+wire "a1", "a10"
+```
+
+Connect each end to its intended circuit node or remove the unused wire.

data/docs/rules/Electrical/FloatingPin.md

@@ -0,0 +1,9 @@
+# Electrical/FloatingPin
+
+A component pin has no external connection. A pin listed with `unused:` is intentionally ignored.
+
+```ruby
+led :D1, anode: "b10", cathode: "b12" # neither pin is wired elsewhere
+```
+
+Connect the pin to the intended net or mark a deliberately unused IC pin with `unused:`.

data/docs/rules/Electrical/MissingSeriesResistor.md

@@ -0,0 +1,11 @@
+# Electrical/MissingSeriesResistor
+
+An LED has a known unprotected path across a supply. This MVP check uses net reachability and is conservative about complex load branches.
+
+```ruby
+led :D1, anode: "b10", cathode: "g12"
+wire "a10", "B+"
+wire "h12", "B-"
+```
+
+Add a current-limiting resistor in series with the LED and verify its two pins land on distinct nets.

data/docs/rules/Electrical/NetLabelConflict.md

@@ -0,0 +1,10 @@
+# Electrical/NetLabelConflict
+
+One connected net has multiple distinct labels.
+
+```ruby
+net :VCC, at: "B+1"
+net :GND, at: "B+2"
+```
+
+Check whether the labels or the wiring are wrong, then give the connected net one consistent name.

data/docs/rules/Electrical/NoCommonGround.md

@@ -0,0 +1,10 @@
+# Electrical/NoCommonGround
+
+Multiple power supplies belong to disconnected supply-reference groups.
+
+```ruby
+supply :A, voltage: 5, plus: "B+1", minus: "B-1"
+supply :B, voltage: 3.3, plus: "T+1", minus: "T-1"
+```
+
+Connect the grounds when the powered circuits exchange signals or current.

data/docs/rules/Electrical/PowerPinUnconnected.md

@@ -0,0 +1,9 @@
+# Electrical/PowerPinUnconnected
+
+A part pin marked `role: power` or `role: ground` does not reach the matching supply.
+
+```ruby
+ic :U1, "NE555", at: "e20" # connect pins 8 and 1 to VCC and GND
+```
+
+Connect each required power pin to the corresponding supply rail.

data/docs/rules/Electrical/ReversePolarity.md

@@ -0,0 +1,10 @@
+# Electrical/ReversePolarity
+
+The positive pin of a polarized part is at a lower known potential than its negative pin.
+
+```ruby
+led :D1, anode: "b10", cathode: "g12"
+# Connect anode to GND and cathode to VCC.
+```
+
+Swap the connections so the positive pin faces the higher potential.

data/docs/rules/Electrical/ShortCircuit.md

@@ -0,0 +1,9 @@
+# Electrical/ShortCircuit
+
+Power constraints assign incompatible voltages to one connected net. The message includes a physical route when one is available.
+
+```ruby
+wire "B+", "B-"
+```
+
+Remove the shorting connection and review the reported holes and wires before powering the circuit.

data/docs/rules/Electrical/ShortedComponent.md

@@ -0,0 +1,9 @@
+# Electrical/ShortedComponent
+
+A two-pin component's pins resolve to the same net, so current can bypass the component.
+
+```ruby
+resistor :R1, "330", pins: %w[a4 e4]
+```
+
+Move the pins to separate strips and verify the resulting net list.

data/docs/rules/Electrical/SplitRail.md

@@ -0,0 +1,10 @@
+# Electrical/SplitRail
+
+A used segment of a split power rail has no known supply potential while another segment of that rail is powered.
+
+```ruby
+board :full, split_rails: true
+# Add a wire to B+30 while the supply is attached to B+1.
+```
+
+Bridge the rail sections with a wire or attach a supply to each required segment.

data/docs/rules/Electrical/SupplyVoltageRange.md

@@ -0,0 +1,10 @@
+# Electrical/SupplyVoltageRange
+
+The known voltage difference between a part's power and ground pins is outside its declared `supply_range`.
+
+```ruby
+supply :USB, voltage: 3.3, plus: "B+1", minus: "B-1"
+ic :U1, "NE555", at: "e20" # NE555 requires at least 4.5 V
+```
+
+Use a valid supply voltage or a part rated for the circuit voltage.

data/docs/rules/Intent/ConnectionMismatch.md

@@ -0,0 +1,9 @@
+# Intent/ConnectionMismatch
+
+Actual connectivity differs from a declared `connected`, `isolated`, or `net` expectation.
+
+```ruby
+expect { connected "R1.1", "D1.anode" }
+```
+
+Correct the wiring or update the expectation to match the intended circuit. `strict: true` also rejects extra pins on a declared net.

data/docs/rules/Intent/UnknownNet.md

@@ -0,0 +1,9 @@
+# Intent/UnknownNet
+
+An expectation or label refers to a hole, pin, supply terminal, or net name that cannot be resolved.
+
+```ruby
+expect { connected "U1.9", :VCC }
+```
+
+Check the reference spelling and part definition. Pin references must use a declared pin number or name.

data/docs/rules/Layout/DuplicateRef.md

@@ -0,0 +1,10 @@
+# Layout/DuplicateRef
+
+Component references and wire IDs must be unique within a circuit.
+
+```ruby
+resistor :R1, "330", pins: %w[a1 a3]
+resistor :R1, "1k", pins: %w[a5 a7]
+```
+
+Give each component and explicitly named wire a distinct identifier.

data/docs/rules/Layout/HoleConflict.md

@@ -0,0 +1,10 @@
+# Layout/HoleConflict
+
+Only one component lead or supply terminal can occupy a physical hole.
+
+```ruby
+resistor :R1, "330", pins: %w[a1 a3]
+led :D1, anode: "a1", cathode: "a5"
+```
+
+Move one lead to a different hole. Components may still share a conductive strip through separate holes.

data/docs/rules/Layout/InvalidHole.md

@@ -0,0 +1,9 @@
+# Layout/InvalidHole
+
+The reference does not identify a hole on the selected board.
+
+```ruby
+wire "k5", "a10" # k is not a breadboard row
+```
+
+Use an existing terminal or rail hole, for example `wire "j5", "a10"`.

data/docs/rules/Layout/InvalidPlacement.md

@@ -0,0 +1,9 @@
+# Layout/InvalidPlacement
+
+A DIP must straddle rows `e` and `f`; a fixed footprint must fit inside the board.
+
+```ruby
+ic :U1, "NE555", at: "c20"
+```
+
+Place pin 1 on row `e` or `f` and leave enough board space for the full footprint.

data/docs/rules/Layout/NoFreeHole.md

@@ -0,0 +1,7 @@
+# Layout/NoFreeHole
+
+Automatic rail or pin-strip selection found no unoccupied hole.
+
+This can happen when many wire endpoints request the same crowded rail or strip.
+
+Choose an explicit free hole, or move some connections to another strip.

data/docs/rules/Layout/PinsInSameStrip.md

@@ -0,0 +1,9 @@
+# Layout/PinsInSameStrip
+
+Two pins of the same component share a conductive strip, bypassing the component.
+
+```ruby
+resistor :R1, "330", pins: %w[a4 e4]
+```
+
+Place the leads in different strips, such as `a4` and `a5`.

data/docs/rules/Layout/SplitNetLabel.md

@@ -0,0 +1,3 @@
+# Layout/SplitNetLabel
+
+The same net label appears on disconnected parts of the board. Connect those locations or use distinct names.

data/docs/rules/Layout/UnknownBoard.md

@@ -0,0 +1,3 @@
+# Layout/UnknownBoard
+
+The selected board definition cannot be loaded. Check the board name or the path supplied to `use_boards`.

data/docs/rules/Layout/UnknownOption.md

@@ -0,0 +1,5 @@
+# Layout/UnknownOption
+
+Reports a component or offboard option that Breadkit does not recognize. The electrical and intent checks are skipped until the option is corrected.
+
+Check the option spelling or define the attribute in the part definition.

data/docs/rules/Layout/UnknownPart.md

@@ -0,0 +1,9 @@
+# Layout/UnknownPart
+
+The named part definition is not built in or loaded with `use_parts`.
+
+```ruby
+ic :U1, "NE556X", at: "e20"
+```
+
+Use a known part ID or add a YAML definition and load it before placing the part.

data/docs/rules/Layout/UnknownPin.md

@@ -0,0 +1,9 @@
+# Layout/UnknownPin
+
+A wire, label, or expectation refers to a pin that the component definition does not contain.
+
+```ruby
+wire "U1.9", "a10" # NE555 has only pins 1 through 8
+```
+
+Check the part pin list and use its pin number or name.

data/docs/rules/Layout/UnknownTransistorModel.md

@@ -0,0 +1,5 @@
+# Layout/UnknownTransistorModel
+
+Warns when a transistor model is not recognized. Breadkit uses a generic EBC pinout in this case, which may differ from the physical component.
+
+Specify a known model or define the part with its actual pin order.

data/docs/rules/Layout/UnplacedPin.md

@@ -0,0 +1,3 @@
+# Layout/UnplacedPin
+
+One or more component pins have no board hole. Supply every required pin location or use a supported footprint placement.

data/docs/rules/Style/WireColor.md

@@ -0,0 +1,9 @@
+# Style/WireColor
+
+A wire attached to a known positive or ground net uses a color outside the configured convention. Defaults are red or orange for positive voltage, and black, blue, or gray for ground.
+
+```ruby
+wire "a10", "B+", color: :blue
+```
+
+Choose a conventional color or set `PositiveColors` / `GroundColors` in `.bklint.yml`.

data/exe/bklint

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "breadkit/lint"
+exit Breadkit::Lint::CLI.new.run(ARGV)