breadkit-lint 0.1.0

data/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "breadkit-lint-site",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "build": "mkdir -p _site && cp -R site/. _site/ && tailwindcss -i site/styles.css -o _site/assets/site.css --minify"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.3.3",
+    "tailwindcss": "4.3.3"
+  }
+}

data/scripts/check_bad_examples.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+root = File.expand_path("..", __dir__)
+core = File.expand_path("../breadkit", root)
+files = Dir[File.join(core, "examples", "bad", "*.bk.rb")].sort
+abort "no bad examples found in #{core}/examples/bad" if files.empty?
+
+failed = false
+files.each do |path|
+  expected = File.foreach(path).filter_map { |line| line[/\A#\s*expect:\s*(\S+)/, 1] }.first
+  unless expected
+    warn "#{path}: missing '# expect: Rule/Id' header"
+    failed = true
+    next
+  end
+
+  stdout, stderr, status = Open3.capture3("bklint", "--format", "json", path, chdir: root)
+  report = JSON.parse(stdout)
+  rules = report.fetch("files").flat_map { |file| file.fetch("offenses").map { |offense| offense.fetch("rule") } }
+  unless status.exitstatus == 1 && rules.include?(expected)
+    warn "#{path}: expected #{expected}, got exit #{status.exitstatus} and #{rules.inspect}"
+    warn stderr unless stderr.empty?
+    failed = true
+    next
+  end
+
+  puts "#{File.basename(path)}: #{expected} detected"
+rescue JSON::ParserError, KeyError => e
+  warn "#{path}: invalid bklint JSON (#{e.message})"
+  failed = true
+end
+
+exit(failed ? 1 : 0)

data/sig/breadkit/lint.rbs

@@ -0,0 +1,68 @@
+module Breadkit
+  module Lint
+    VERSION: String
+
+    class Error < StandardError
+    end
+
+    class Offense
+      attr_reader rule: String
+      attr_reader severity: String
+      attr_reader message: String
+      attr_reader location: Breadkit::SourceLocation?
+      attr_reader targets: Hash[Symbol, untyped]
+      attr_reader state: String?
+    end
+
+    class Rule
+      attr_reader id: String
+      attr_reader severity: String
+      attr_reader description: String
+      attr_reader state_sensitive: bool
+      def check: (Context context) -> void
+    end
+
+    class Context
+      attr_reader circuit: Breadkit::Circuit
+      attr_reader state: Breadkit::State
+      attr_reader config: Config
+      attr_reader offenses: Array[Offense]
+    end
+
+    class Registry
+      def self.all: () -> Array[Rule | singleton(Rule)]
+      def self.register: (Rule | singleton(Rule) rule) -> void
+    end
+
+    class Config
+      attr_reader data: Hash[String, untyped]
+      def initialize: (?String? path) -> void
+      def severity: (Rule rule) -> String
+      def enabled?: (Rule rule) -> bool
+      def switch_states: () -> String
+      def fail_level: () -> String
+      def excludes: () -> Array[String]
+      def extra_parts: () -> Array[String]
+      def unknown_rules: () -> Array[String]
+      def excluded?: (String path) -> bool
+    end
+
+    class Engine
+      def initialize: (?config: Config) -> void
+      def run: (String | Array[String] paths, ?only: Array[String]?, ?except: Array[String]?) -> Array[Hash[Symbol, untyped]]
+      def fail?: (Array[Hash[Symbol, untyped]] files, ?String threshold) -> bool
+      def fatal?: (Array[Hash[Symbol, untyped]] files) -> bool
+    end
+
+    class Formatter
+      def text: (Array[Hash[Symbol, untyped]] files, ?locale: String) -> String
+      def json: (Array[Hash[Symbol, untyped]] files) -> String
+      def github: (Array[Hash[Symbol, untyped]] files) -> String
+      def sarif: (Array[Hash[Symbol, untyped]] files) -> String
+    end
+
+    class CLI
+      def run: (Array[String] argv) -> Integer
+    end
+  end
+end

data/site/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
+  <rect width="48" height="48" rx="12" fill="#1b2423" />
+  <path d="M10 15h28M10 33h28M15 10v28M33 10v28" fill="none" stroke="#3d4b47" stroke-width="2" />
+  <path d="M15 15h18v18H15z" fill="none" stroke="#d99755" stroke-linecap="round" stroke-linejoin="round" stroke-width="3" />
+  <circle cx="15" cy="15" r="2.5" fill="#e8eeeb" />
+  <circle cx="33" cy="33" r="2.5" fill="#e8eeeb" />
+</svg>

data/site/index.html

@@ -0,0 +1,95 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="theme-color" content="#101719">
+    <meta name="description" content="Check breadboard placement, shorts, floating pins, and mismatches with your intended connections.">
+    <title>breadkit-lint | Check wiring before building</title>
+    <link rel="canonical" href="https://breadkit.github.io/breadkit-lint/">
+    <link rel="icon" href="./favicon.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="./assets/site.css">
+  </head>
+  <body class="min-h-dvh bg-ink font-sans text-paper antialiased">
+    <a class="sr-only rounded-sm bg-copper px-4 py-3 font-semibold text-ink focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:outline-2 focus:outline-offset-4 focus:outline-paper" href="#main">Skip to content</a>
+    <header class="border-b border-line">
+      <div class="mx-auto flex max-w-7xl flex-wrap items-center justify-between gap-4 px-5 py-5 sm:px-8 lg:px-10">
+        <a class="flex items-center gap-3 rounded-sm text-xl font-semibold focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="./" aria-label="breadkit-lint home"><img class="size-8" src="./favicon.svg" alt="" width="32" height="32"><span>breadkit-lint</span></a>
+        <nav aria-label="Main navigation" class="flex flex-wrap items-center gap-x-5 gap-y-2 text-sm text-muted">
+          <a class="rounded-sm hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit/">Breadkit</a>
+          <a class="rounded-sm hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit/guide/">Guide</a>
+          <a class="rounded-sm hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit/guide/dsl/">Reference</a>
+          <a class="rounded-sm hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit-render/">Render</a>
+          <a class="rounded-sm hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://github.com/breadkit/breadkit-lint">GitHub</a>
+        </nav>
+      </div>
+    </header>
+
+    <main id="main">
+      <section class="mx-auto grid max-w-7xl items-center gap-12 px-5 py-16 sm:px-8 lg:grid-cols-2 lg:gap-16 lg:px-10 lg:py-24">
+        <div class="max-w-xl">
+          <p class="mb-5 text-sm font-medium text-copper">The Breadkit circuit checker</p>
+          <h1 class="text-balance text-4xl font-semibold leading-tight sm:text-5xl lg:text-6xl">Check wiring before you build.</h1>
+          <p class="mt-6 max-w-lg text-pretty text-lg leading-8 text-muted">Analyze breadboard holes and component connections to find placement errors, shorts, floating pins, and mismatches with your design intent.</p>
+          <div class="mt-8 flex flex-wrap gap-x-6 gap-y-4">
+            <a class="rounded-sm bg-copper px-5 py-3 font-semibold text-ink hover:bg-paper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="#example">See a finding</a>
+            <a class="rounded-sm py-3 font-medium text-paper underline decoration-line underline-offset-4 hover:decoration-copper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://github.com/breadkit/breadkit-lint/tree/main/docs/rules">Browse rules</a>
+          </div>
+          <div class="mt-10 rounded-lg border border-line bg-board p-5">
+            <p class="mb-3 text-sm text-muted">Install and run</p>
+            <pre class="overflow-x-auto font-mono text-sm leading-7"><code>gem install breadkit-lint
+bklint circuit.bk.rb</code></pre>
+          </div>
+        </div>
+        <figure id="example" class="m-0 overflow-hidden rounded-xl border border-line bg-board">
+          <div class="border-b border-line px-5 py-4 text-sm text-muted">Example: a short circuit</div>
+          <div class="p-5 sm:p-7">
+            <pre class="overflow-x-auto font-mono text-sm leading-7 text-paper"><code>board :half
+supply :USB, voltage: 5.0,
+       plus: "B+1", minus: "B-1"
+wire "a10", "B+"
+wire "b10", "B-"</code></pre>
+            <div class="my-6 border-t border-line"></div>
+            <p class="mb-3 text-sm text-muted">From the bklint report</p>
+            <pre class="overflow-x-auto font-mono text-sm leading-7 text-paper"><code>E: [Electrical/ShortCircuit]
+inconsistent voltage constraints near USB.+</code></pre>
+          </div>
+          <figcaption class="border-t border-line px-5 py-4 text-pretty text-sm leading-6 text-muted">a10 and b10 share a conductive strip, so the positive and negative rails are shorted.</figcaption>
+        </figure>
+      </section>
+
+      <section id="checks" class="border-t border-line bg-board/60">
+        <div class="mx-auto max-w-7xl px-5 py-16 sm:px-8 lg:px-10">
+          <h2 class="text-balance text-3xl font-semibold">What it checks</h2>
+          <div class="mt-8 border-y border-line">
+            <div class="grid gap-2 py-6 md:grid-cols-3"><h3 class="text-balance text-xl font-semibold">Placement</h3><p class="text-pretty leading-7 text-muted md:col-span-2">Invalid holes, part collisions, leads placed on the same strip, and ICs that miss the center gap.</p></div>
+            <div class="grid gap-2 border-t border-line py-6 md:grid-cols-3"><h3 class="text-balance text-xl font-semibold">Electrical connections</h3><p class="text-pretty leading-7 text-muted md:col-span-2">Shorts, unconnected pins, split rails, supply voltages, and LED series resistors.</p></div>
+            <div class="grid gap-2 border-t border-line py-6 md:grid-cols-3"><h3 class="text-balance text-xl font-semibold">Design intent</h3><p class="text-pretty leading-7 text-muted md:col-span-2">Differences between <code class="font-mono text-paper">expect</code> declarations and the resolved nets.</p></div>
+          </div>
+        </div>
+      </section>
+
+      <section id="workflow" class="mx-auto grid max-w-7xl gap-10 px-5 py-16 sm:px-8 lg:grid-cols-2 lg:px-10">
+        <div>
+          <h2 class="text-balance text-3xl font-semibold">Use it locally or in CI</h2>
+          <p class="mt-4 max-w-xl text-pretty leading-7 text-muted">Choose text, JSON, GitHub annotations, or SARIF output. Set the severity that fails the run with <code class="font-mono text-paper">--fail-level</code>.</p>
+          <pre class="mt-6 overflow-x-auto rounded-lg border border-line bg-board p-5 font-mono text-sm leading-7"><code>bklint circuit.bk.rb --format github
+bklint circuit.bk.rb --format sarif --out lint.sarif
+bklint circuit.bk.rb --only Electrical/ShortCircuit</code></pre>
+        </div>
+        <div class="rounded-lg border border-line bg-board p-6">
+          <h3 class="text-balance text-xl font-semibold">Review findings on the diagram</h3>
+          <p class="mt-4 text-pretty leading-7 text-muted">Pass JSON results to breadkit-render to mark the reported holes and wires on the diagram.</p>
+          <pre class="mt-5 overflow-x-auto font-mono text-sm leading-7"><code>bklint circuit.bk.rb --format json --out lint.json
+bkrender circuit.bk.rb --annotations lint.json \
+  -o review.svg</code></pre>
+          <a class="mt-6 inline-block rounded-sm text-paper underline decoration-copper underline-offset-4 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit-render/">Explore breadkit-render</a>
+        </div>
+      </section>
+
+      <section class="border-t border-line"><div class="mx-auto flex max-w-7xl flex-wrap items-center justify-between gap-4 px-5 py-10 sm:px-8 lg:px-10"><p class="max-w-2xl text-pretty text-sm leading-6 text-muted">DSL files and configuration <code class="font-mono text-paper">require</code> statements run as Ruby. Only process inputs you trust. Use IR JSON for data-only exchange.</p><a class="rounded-sm text-paper underline decoration-line underline-offset-4 hover:decoration-copper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://breadkit.github.io/breadkit/guide/">Learn to write a circuit</a></div></section>
+    </main>
+
+    <footer class="border-t border-line"><div class="mx-auto flex max-w-7xl flex-wrap items-center justify-between gap-3 px-5 py-7 text-sm text-muted sm:px-8 lg:px-10"><p>breadkit-lint is published independently from breadkit.</p><a class="rounded-sm text-paper underline decoration-line underline-offset-4 hover:decoration-copper focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-copper" href="https://github.com/breadkit/breadkit-lint">GitHub repository</a></div></footer>
+  </body>
+</html>

data/site/styles.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+
+@source "./**/*.html";
+
+@theme {
+  --color-ink: #101719;
+  --color-board: #1b2423;
+  --color-line: #3d4b47;
+  --color-paper: #e8eeeb;
+  --color-muted: #a1b0aa;
+  --color-copper: #d99755;
+  --font-sans: "Avenir Next", Avenir, ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+}

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: breadkit-lint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: breadkit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: bklint analyzes Breadkit circuits and reports layout, electrical, and
+  intent offenses.
+email:
+- t.yudai92@gmail.com
+executables:
+- bklint
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- SECURITY.md
+- config/default.yml
+- docs/rules/Electrical/DanglingWire.md
+- docs/rules/Electrical/FloatingPin.md
+- docs/rules/Electrical/MissingSeriesResistor.md
+- docs/rules/Electrical/NetLabelConflict.md
+- docs/rules/Electrical/NoCommonGround.md
+- docs/rules/Electrical/PowerPinUnconnected.md
+- docs/rules/Electrical/ReversePolarity.md
+- docs/rules/Electrical/ShortCircuit.md
+- docs/rules/Electrical/ShortedComponent.md
+- docs/rules/Electrical/SplitRail.md
+- docs/rules/Electrical/SupplyVoltageRange.md
+- docs/rules/Intent/ConnectionMismatch.md
+- docs/rules/Intent/UnknownNet.md
+- docs/rules/Layout/DuplicateRef.md
+- docs/rules/Layout/HoleConflict.md
+- docs/rules/Layout/InvalidHole.md
+- docs/rules/Layout/InvalidPlacement.md
+- docs/rules/Layout/NoFreeHole.md
+- docs/rules/Layout/PinsInSameStrip.md
+- docs/rules/Layout/SplitNetLabel.md
+- docs/rules/Layout/UnknownBoard.md
+- docs/rules/Layout/UnknownOption.md
+- docs/rules/Layout/UnknownPart.md
+- docs/rules/Layout/UnknownPin.md
+- docs/rules/Layout/UnknownTransistorModel.md
+- docs/rules/Layout/UnplacedPin.md
+- docs/rules/Style/WireColor.md
+- exe/bklint
+- lib/breadkit/lint.rb
+- lib/breadkit/lint/rules.rb
+- lib/breadkit/lint/rules/electrical.rb
+- lib/breadkit/lint/rules/intent.rb
+- lib/breadkit/lint/rules/layout.rb
+- lib/breadkit/lint/rules/style.rb
+- lib/breadkit/lint/rules/support.rb
+- lib/breadkit/lint/version.rb
+- locales/en.yml
+- locales/ja.yml
+- package-lock.json
+- package.json
+- scripts/check_bad_examples.rb
+- sig/breadkit/lint.rbs
+- site/favicon.svg
+- site/index.html
+- site/styles.css
+homepage: https://github.com/breadkit/breadkit-lint
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/breadkit/breadkit-lint
+  source_code_uri: https://github.com/breadkit/breadkit-lint/tree/main
+  bug_tracker_uri: https://github.com/breadkit/breadkit-lint/issues
+  documentation_uri: https://github.com/breadkit/breadkit-lint/tree/main/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Check breadboard wiring designs for common layout and circuit errors.
+test_files: []