REFERENCE.md

breadkit-lint reference

Start with the README for installation and a first lint run. For individual checks, use the rule reference.

Inputs and results

bklint [options] [FILES...] accepts Ruby DSL (.bk.rb), declarative YAML and TOML (.bk.yml, .bk.yaml, .bk.toml), and Breadkit JSON IR. It scans directories recursively. With no file argument, it scans the current directory. Named multi-board circuits and IR v2 are supported; board holes use qualified IDs such as B1.a10.

The nearest .bklint.yml configures each file unless --config is given. Exit status is 0 when no finding reaches the failure level, 1 for findings, and 2 for invalid input or configuration. Ruby DSL circuits and configuration require entries execute code; inspect only trusted files. JSON IR is data-only.

Rules and configuration

Run bklint --list-rules to discover IDs and bklint --explain Electrical/ShortCircuit for a rule's guidance. The default configuration lists every rule and setting.

Create .bklint.yml beside a circuit to override only what you need:

Electrical/FloatingPin:
  Severity: error
  Include: ['circuits/**/*.bk.rb']
  Exclude: ['circuits/legacy/**/*.bk.rb']

Style/WireColor:
  Enabled: true

Include and Exclude match paths relative to the config file; Exclude wins. AllRules.Exclude skips entire files. Use inherit_from for shared settings and use_parts for custom definitions. Unknown rule IDs are errors. A circuit can use lint_disable with an optional target and reason; AllRules.RequireDisableReason makes reasons mandatory. In Ruby DSL files, # bklint:disable Electrical/FloatingPin -- deliberate open pin suppresses a finding on the same line. Use # bklint:disable-next-line RULE immediately before a declaration to suppress its next-line findings. Comments are scoped to one line; -- reason satisfies RequireDisableReason.

Connection expectations may name a switch state. expect_voltage and expect_current check supported DC ranges; unknown operating points produce Intent/MeasurementUnavailable. See the core DSL reference for declaration syntax. LED current, GPIO current, supply load, resistor power, supply voltage, signal voltage, and capacitor voltage checks evaluate declared source endpoints and resistor tolerance bounds when the DC model supports the circuit. Voltage checks use paired node differences so common voltage swings do not create false violations. Linear resistor circuits get complete bounds. Diode circuits get endpoint estimates; when those or other bounds are incomplete, Electrical/DcBoundsIncomplete says so.

To adopt lint with existing findings:

bklint --generate-baseline .bklint-baseline.json
bklint --baseline .bklint-baseline.json
bklint --diff origin/main --format github

Baseline entries omit line numbers, so moving known findings does not make them new. The lint JSON schema describes machine-readable output.

CLI options

Option	Use
--format FORMAT	text, json, github, sarif, markdown, junit, checkstyle, or rdjson.
--out PATH	Write the report to a file.
--only RULES, --except RULES	Select rule IDs.
--fail-level LEVEL	Fail on error, warning (default), or info.
--switch-states MODE	Check none, single (default), or all switch states.
--state-budget COUNT	Limit exhaustive states (default 256); report incomplete analysis when exceeded.
--fix-check, --fix	Preview or apply unambiguous Ruby DSL edits.
--watch	Rerun when circuit, part, or config files change.
--jobs COUNT	Inspect independent files with up to COUNT workers (maximum 32); report order stays stable.
--stdin PATH	Read a Ruby, YAML, or TOML circuit from standard input.
--teach, --locale LOCALE	Show short explanations or select en, ja, zh, or ko messages.

Use bklint --help for all flags. Fixing covers one-character wire-color typos, standalone unused suppressions, missing labels on a single known net, and literal wire endpoints with a free hole on the same strip. Ambiguous edits and declarative/JSON files are left unchanged. Fix modes cannot be combined with stdin, diff, baseline, or --out.

GitHub Action

The repository root is a composite Action. It installs this source and a pinned compatible Breadkit core revision. This push workflow uploads SARIF:

name: Circuit lint
on: push
permissions:
  contents: read
  security-events: write
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: breadkit/breadkit-lint@main
        with:
          path: circuits

Pin the Action to a commit SHA for reproducible runs. upload-sarif defaults to true; the report is uploaded even when findings fail the job. For untrusted pull requests, run on pull_request with contents: read, no secrets, and upload-sarif: "false" to emit check annotations. Set annotated-image: "true" for one circuit file to upload an annotated PNG artifact. Copy the read-only review workflow and comment workflow into your repository's .github/workflows directory to attach that image to its pull request. The comment workflow consumes only a validated PNG artifact; it never checks out or executes the proposed circuit. It skips runs without one pull request in GitHub's trusted workflow metadata, which can include some fork runs. Do not run proposed Ruby DSL files with a write token or pull_request_target.

Local integrations

A Rakefile can lint selected files:

require "breadkit/lint/rake_task"

Breadkit::RakeTask.new(:circuits) do |task|
  task.files = FileList["circuits/**/*.bk.rb"]
  task.options = ["--format", "github"]
end

The pre-commit hook reads staged circuit files from Git's index. An optional Guard plugin is available as require "guard/breadkit"; configure watched circuits in your Guardfile. Use bklint --format json with bkrender --annotations to draw findings on a diagram.