breadkit-lint 0.1.0 → 0.2.0

data/lib/breadkit/lint.rb

@@ -7,13 +7,18 @@ require "optparse"
 require "pathname"
 require "uri"
 require "find"
+require "open3"
+require "tmpdir"
+require "fileutils"
 require_relative "lint/version"
 
 module Breadkit
   module Lint
     class Error < StandardError; end
+    require_relative "lint/baseline"
 
-    Offense = Struct.new(:rule, :severity, :message, :location, :targets, :state, keyword_init: true)
+    Offense = Struct.new(:rule, :severity, :message, :location, :targets, :state, :column, :suggestion, keyword_init: true)
+    require_relative "lint/source_editor"
 
     class Rule
       attr_reader :id, :severity, :description, :state_sensitive, :checker
@@ -106,6 +111,37 @@ module Breadkit
         data.dig("AllRules", "SwitchStates") || "single"
       end
 
+      def state_budget
+        data.dig("AllRules", "StateBudget")
+      end
+
+      def states(circuit, mode = switch_states)
+        return circuit.states(mode) unless state_budget && mode.to_s == "all"
+        return circuit.states(mode, budget: state_budget) if circuit.method(:states).parameters.any? { |kind, name| kind == :key && name == :budget }
+
+        count = circuit.states("single").length - 1
+        required = 1 << count
+        raise Error, "#{required} switch states exceed budget #{state_budget}" if required > state_budget
+        raise Error, "exhaustive state analysis above 8 switches requires a newer breadkit gem" if count > 8
+        circuit.states(mode)
+      end
+
+      def intent_states(circuit, expectations)
+        singles = circuit.states("single")
+        ordered = singles.drop(1).map(&:name)
+        by_name = singles.drop(1).to_h { |state| [state.name, state] }
+        composite = expectations.filter_map do |expectation|
+          name = expectation["when"] || expectation[:when]
+          next unless name&.include?(",")
+
+          refs = name.split(",", -1)
+          next unless refs.uniq == refs && refs == ordered.select { |ref| refs.include?(ref) }
+
+          Breadkit::State.new(name: name, closed_switches: refs.flat_map { |ref| by_name.fetch(ref).closed_switches })
+        end
+        singles + composite.uniq(&:name)
+      end
+
       def fail_level
         data.dig("AllRules", "FailLevel") || "warning"
       end
@@ -124,16 +160,26 @@ module Breadkit
       end
 
       def excluded?(path)
+        matches_path?(excludes, path)
+      end
+
+      def rule_applies?(rule, path)
+        include_patterns = data.dig(rule.id, "Include")
+        (include_patterns.nil? || matches_path?(Array(include_patterns), path)) &&
+          !matches_path?(Array(data.dig(rule.id, "Exclude")), path)
+      end
+
+      private
+
+      def matches_path?(patterns, path)
         absolute = File.expand_path(path)
         relative = Pathname.new(absolute).relative_path_from(Pathname.new(@config_dir)).to_s
-        excludes.any? do |pattern|
+        patterns.any? do |pattern|
           File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
             File.fnmatch?(pattern, absolute, File::FNM_PATHNAME | File::FNM_EXTGLOB)
         end
       end
 
-      private
-
       def merge_file(path)
         @data = deep_merge(@data, load_config(path, []))
       rescue Psych::Exception => e
@@ -161,10 +207,17 @@ module Breadkit
         fail_level = data.dig("AllRules", "FailLevel")
         switch_states = data.dig("AllRules", "SwitchStates")
         new_rules = data.dig("AllRules", "NewRules")
+        budget = data.dig("AllRules", "StateBudget")
         raise Error, "invalid fail level: #{fail_level}" if fail_level && !%w[error warning info].include?(fail_level.to_s)
         raise Error, "invalid switch state mode: #{switch_states}" if switch_states && !%w[none single all].include?(switch_states.to_s)
         raise Error, "invalid new rules mode: #{new_rules}" if new_rules && !%w[pending enable disable].include?(new_rules.to_s)
+        raise Error, "StateBudget must be a positive integer" if budget && (!budget.is_a?(Integer) || !budget.positive?)
         Registry.all.each do |rule|
+          %w[Include Exclude].each do |key|
+            patterns = data.dig(rule.id, key)
+            next if patterns.nil? || patterns.is_a?(String) || (patterns.is_a?(Array) && patterns.all? { |pattern| pattern.is_a?(String) })
+            raise Error, "invalid #{rule.id} #{key} patterns"
+          end
           severity_value = data.dig(rule.id, "Severity")
           next unless severity_value && !%w[error warning info].include?(severity_value.to_s.downcase)
           raise Error, "invalid severity for #{rule.id}: #{severity_value}"
@@ -176,7 +229,7 @@ module Breadkit
     Registry.const_set(:RULES, Registry.all.dup.freeze)
 
     class Engine
-      BLOCKING_DIAGNOSTICS = %w[invalid_hole unknown_board unknown_part unknown_pin unknown_option unplaced_pin invalid_placement no_free_hole].freeze
+      BLOCKING_DIAGNOSTICS = %w[invalid_hole unknown_board unknown_part unknown_pin unknown_supply_source ambiguous_supply_source unknown_option invalid_option invalid_value invalid_color invalid_route invalid_wire_id unplaced_pin invalid_placement no_free_hole].freeze
       LEVELS = { "info" => 0, "warning" => 1, "error" => 2 }.freeze
 
       def initialize(config: Config.new, locale: "en")
@@ -186,23 +239,35 @@ module Breadkit
         @checks = Checks.new(@config, messages)
       end
 
-      def run(paths, only: nil, except: nil)
+      def run(paths, only: nil, except: nil, timeout: 10, source: nil)
         Array(paths).filter_map do |path|
           next if excluded?(path)
           begin
             circuit = if path.end_with?(".json")
               Breadkit.load(path)
             else
-              document = Breadkit::DSL.load_file(path)
+              document = if path.end_with?(".bk.yml", ".bk.yaml", ".bk.toml")
+                raise Error, "declarative YAML/TOML input requires a newer breadkit gem" unless defined?(Breadkit::StructuredInput)
+
+                source ? Breadkit::StructuredInput.load_source(path, source) : Breadkit::StructuredInput.load_file(path)
+              else
+                Breadkit::DSL.load_file(path, timeout: timeout, source: source)
+              end
               document.part_paths.concat(@config.extra_parts)
               Breadkit::Resolver.new.call(document)
             end
-            offenses = inspect_circuit(circuit, only, except)
-            { path: path, offenses: @checks.suppress(offenses, circuit.lint_disables, circuit),
-              skipped: circuit.diagnostics.any? { |item| BLOCKING_DIAGNOSTICS.include?(item.code) } }
-          rescue StandardError => e
+            offenses = inspect_circuit(circuit, path, only, except)
+            skipped = circuit.diagnostics.any? { |item| BLOCKING_DIAGNOSTICS.include?(item.code) }
+            { path: path, offenses: @checks.suppress(offenses, circuit.lint_disables, circuit, path: path, only: only, except: except, skipped: skipped),
+              skipped: skipped }
+          rescue StandardError, ScriptError, SystemStackError => e
+            location = e.respond_to?(:location) && e.location
+            location ||= begin
+              line = e.message[/\A(?:#{Regexp.escape(path)}|#{Regexp.escape(File.expand_path(path))}):(\d+):/, 1]
+              Breadkit::SourceLocation.new(path: path, line: line&.to_i)
+            end
             offense = Offense.new(rule: "Fatal/EvaluationError", severity: "error", message: e.message,
-                                  location: Breadkit::SourceLocation.new(path: path, line: nil), targets: {}, state: nil)
+                                  location: location, targets: {}, state: nil)
             { path: path, offenses: [offense] }
           end
         end
@@ -219,14 +284,20 @@ module Breadkit
 
       private
 
-      def inspect_circuit(circuit, only, except)
+      def inspect_circuit(circuit, path, only, except)
         offenses = []
         broken_layout = circuit.diagnostics.any? { |item| BLOCKING_DIAGNOSTICS.include?(item.code) }
-        states = circuit.states(@config.switch_states)
+        states = @config.states(circuit)
+        scoped_expectations = circuit.expectations.any? { |item| item["when"] || item[:when] }
+        intent_states = scoped_expectations ? @config.intent_states(circuit, circuit.expectations) : states
         Registry.all.each do |rule|
-          next unless @config.enabled?(rule) && selected?(rule.id, only, except)
+          next unless @config.enabled?(rule) && @config.rule_applies?(rule, path) && selected?(rule.id, only, except)
           next if broken_layout && rule.id.start_with?("Electrical/", "Intent/")
-          relevant_states = rule.state_sensitive ? states : [states.first]
+          relevant_states = if rule.id.start_with?("Intent/") && scoped_expectations
+            intent_states
+          else
+            rule.state_sensitive ? states : [states.first]
+          end
           relevant_states.each do |state|
             context = Context.new(circuit, state, @config, @checks)
             checked = begin
@@ -241,10 +312,12 @@ module Breadkit
             offenses.concat(checked)
           end
         end
+        pull_pins = offenses.select { |item| item.rule == "Electrical/MissingPullResistor" }.flat_map { |item| item.targets.fetch(:pins, []) }
+        offenses.reject! { |item| item.rule == "Electrical/FloatingInput" && item.state.nil? && (item.targets.fetch(:pins, []) & pull_pins).any? }
         baseline = offenses.select { |item| item.state.nil? }.map { |item| [item.rule, item.message, item.location&.line] }
         offenses.reject { |item| item.state && baseline.include?([item.rule, item.message, item.location&.line]) }
                 .uniq { |item| [item.rule, item.message, item.location&.line, item.state] }
-                .sort_by { |item| [item.location&.path.to_s, item.location&.line.to_i, item.rule] }
+                .sort_by { |item| [item.location&.path.to_s, item.location&.line.to_i, item.rule, item.message] }
       end
 
       def selected?(id, only, except)
@@ -259,21 +332,46 @@ module Breadkit
     end
 
     class Formatter
-      def text(files, locale: "en")
+      REPORT_LABELS = {
+        "zh" => { state: " (%{state} 状态)", why: "原因", skipped: "%{path}: 因布局错误而跳过电气与意图检查",
+                  summary: "检查了 %{files} 个文件，共 %{count} 条诊断（错误 %{errors}、警告 %{warnings}、信息 %{infos}）" },
+        "ko" => { state: " (%{state} 상태)", why: "이유", skipped: "%{path}: 배치 오류로 전기 및 의도 검사 생략",
+                  summary: "파일 %{files}개 검사, 진단 %{count}개 (오류 %{errors}, 경고 %{warnings}, 정보 %{infos})" }
+      }.freeze
+
+      def text(files, locale: "en", teach: false)
+        labels = REPORT_LABELS[locale]
         lines = files.flat_map do |file|
-          entries = file[:offenses].map do |item|
+          entries = file[:offenses].flat_map do |item|
             level = { "error" => "E", "warning" => "W", "info" => "I" }.fetch(item.severity, "E")
-            state = item.state ? (locale == "ja" ? " (#{item.state} の状態)" : " (#{item.state} state)") : ""
-            path = item.location&.path || file[:path]
-            line = item.location&.line ? ":#{item.location.line}" : ""
-            "#{path}#{line}: #{level}: [#{item.rule}] #{item.message}#{state}"
+            state = if item.state
+              labels ? format(labels[:state], state: item.state) : (locale == "ja" ? " (#{item.state} の状態)" : " (#{item.state} state)")
+            else
+              ""
+            end
+            path = display_path(item.location&.path || file[:path])
+            line = item.location&.line ? ":#{item.location.line}#{item.column ? ":#{item.column}" : ""}" : ""
+            heading = "#{path}#{line}: #{level}: [#{item.rule}] #{item.message}#{state}"
+            guidance = teach && [teach_guidance(item.rule, locale), item.suggestion].compact.join(" ")
+            guidance = nil if guidance == ""
+            guidance ? [heading, "  #{labels ? labels[:why] : (locale == 'ja' ? '説明' : 'Why')}: #{guidance}"] : [heading]
+          end
+          if file[:skipped]
+            entries << if labels
+              format(labels[:skipped], path: display_path(file[:path]))
+            elsif locale == "ja"
+              "#{display_path(file[:path])}: 配置エラーのため電気・意図の検査を省略しました"
+            else
+              "#{display_path(file[:path])}: electrical and intent checks skipped because of layout errors"
+            end
           end
-          entries << (locale == "ja" ? "#{file[:path]}: 配置エラーのため電気・意図の検査を省略しました" :
-                                           "#{file[:path]}: electrical and intent checks skipped because of layout errors") if file[:skipped]
           entries
         end
         errors, warnings, infos = files.flat_map { |file| file[:offenses] }.group_by(&:severity).values_at("error", "warning", "info").map { |items| items ? items.length : 0 }
-        summary = if locale == "ja"
+        summary = if labels
+          format(labels[:summary], files: files.length, count: errors + warnings + infos,
+                                   errors: errors, warnings: warnings, infos: infos)
+        elsif locale == "ja"
           "#{files.length} ファイルを検査、#{errors + warnings + infos} 件の指摘（エラー #{errors} 件、警告 #{warnings} 件、情報 #{infos} 件）"
         else
           count = errors + warnings + infos
@@ -282,15 +380,17 @@ module Breadkit
         (lines + [summary]).join("\n")
       end
 
-      def json(files)
+      def json(files, locale: "en")
         offenses = files.flat_map { |file| file[:offenses] }
         JSON.pretty_generate(
           schema_version: 1,
           tool: { name: "bklint", version: VERSION },
           files: files.map do |file|
-            { path: File.expand_path(file[:path]), analysis_skipped: !!file[:skipped], offenses: file[:offenses].map do |item|
-              { rule: item.rule, severity: item.severity, message: item.message,
-                location: { path: item.location&.path || file[:path], line: item.location&.line },
+            { path: display_path(file[:path]), analysis_skipped: !!file[:skipped], offenses: file[:offenses].map do |item|
+              { rule: item.rule, severity: item.severity, message: item.message, docs_url: rule_help_url(item.rule),
+                suggestion: item.suggestion || suggestion_for_rule(item.rule, locale),
+                location: { path: display_path(item.location&.path || file[:path]), line: item.location&.line }
+                  .merge(item.column ? { column: item.column } : {}),
                 state: item.state, targets: item.targets }
             end }
           end,
@@ -305,19 +405,68 @@ module Breadkit
             level = { "error" => "error", "warning" => "warning", "info" => "notice" }.fetch(item.severity, "error")
             line = item.location&.line
             message = escape_data(item.message)
-            location = "file=#{escape_property(item.location&.path || file[:path])}"
+            location = "file=#{escape_property(display_path(item.location&.path || file[:path]))}"
             location += ",line=#{line}" if line
+            location += ",col=#{item.column}" if line && item.column
             "::#{level} #{location},title=#{escape_property(item.rule)}::#{message}"
           end
         end.join("\n")
       end
 
-      def sarif(files)
+      def markdown(files)
+        rows = files.flat_map do |file|
+          file[:offenses].map do |item|
+            path = display_path(item.location&.path || file[:path])
+            [path, item.location&.line, item.severity, item.rule, item.message].map do |value|
+              xml_escape(value).gsub("|", "\\|").gsub(/\r?\n/, "<br>")
+            end.join(" | ").then { |row| "| #{row} |" }
+          end
+        end
+        (["| File | Line | Severity | Rule | Message |", "| --- | ---: | --- | --- | --- |"] + rows).join("\n")
+      end
+
+      def junit(files)
+        failures = files.count { |file| file[:offenses].any? { |item| item.severity == "error" } }
+        cases = files.map do |file|
+          name = xml_escape(display_path(file[:path]))
+          errors, notices = file[:offenses].partition { |item| item.severity == "error" }
+          details = errors.map do |item|
+            "<failure type=\"#{xml_escape(item.rule)}\" message=\"#{xml_escape(item.message)}\"/>"
+          end
+          details << "<system-out>#{xml_escape(notices.map { |item| "#{item.severity}: #{item.rule}: #{item.message}" }.join("\n"))}</system-out>" unless notices.empty?
+          "<testcase name=\"#{name}\">#{details.join}</testcase>"
+        end
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?><testsuites><testsuite name=\"bklint\" tests=\"#{files.length}\" failures=\"#{failures}\">#{cases.join}</testsuite></testsuites>"
+      end
+
+      def checkstyle(files)
+        entries = files.map do |file|
+          errors = file[:offenses].map do |item|
+            line = item.location&.line ? " line=\"#{item.location.line}\"" : ""
+            "<error#{line} severity=\"#{xml_escape(item.severity)}\" message=\"#{xml_escape(item.message)}\" source=\"#{xml_escape(item.rule)}\"/>"
+          end
+          "<file name=\"#{xml_escape(display_path(file[:path]))}\">#{errors.join}</file>"
+        end
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?><checkstyle version=\"10.0\">#{entries.join}</checkstyle>"
+      end
+
+      def rdjson(files)
+        diagnostics = files.flat_map do |file|
+          file[:offenses].map do |item|
+            location = { path: display_path(item.location&.path || file[:path]) }
+            location[:range] = { start: { line: item.location.line } } if item.location&.line.to_i.positive?
+            { message: item.message, location: location, severity: item.severity.upcase,
+              code: { value: item.rule } }
+          end
+        end
+        JSON.pretty_generate(source: { name: "bklint", url: "https://github.com/breadkit/breadkit-lint" }, diagnostics: diagnostics)
+      end
+
+      def sarif(files, locale: "en")
         rules = (Registry.all.map do |rule|
           level = { "error" => "error", "warning" => "warning", "info" => "note" }.fetch(rule.severity, "error")
           definition = { id: rule.id, shortDescription: { text: rule.description }, defaultConfiguration: { level: level } }
-          path = File.expand_path("../../docs/rules/#{rule.id}.md", __dir__)
-          definition[:helpUri] = "https://github.com/breadkit/breadkit-lint/blob/main/docs/rules/#{rule.id}.md" if File.file?(path)
+          definition[:helpUri] = rule_help_url(rule.id)
           definition
         end + %w[Fatal/EvaluationError Fatal/RuleError Config/InvalidDisable].map do |id|
           { id: id, shortDescription: { text: id.split("/").last }, defaultConfiguration: { level: "error" } }
@@ -325,18 +474,21 @@ module Breadkit
         results = files.flat_map do |file|
           file[:offenses].map do |item|
             result = { ruleId: item.rule, level: { "error" => "error", "warning" => "warning", "info" => "note" }.fetch(item.severity, "error"),
-                       message: { text: item.message }, properties: { targets: item.targets, state: item.state } }
+                       message: { text: item.message }, properties: { targets: item.targets, state: item.state,
+                                                                       suggestion: item.suggestion || suggestion_for_rule(item.rule, locale) } }
             path = item.location&.path || file[:path]
-            relative = Pathname.new(File.expand_path(path)).relative_path_from(Pathname.new(Dir.pwd)).to_s.tr("\\", "/")
+            relative = display_path(path)
             uri = URI::DEFAULT_PARSER.escape(relative, /[^A-Za-z0-9\-._~\/]/)
             physical = { artifactLocation: { uri: uri, uriBaseId: "%SRCROOT%" } }
-            physical[:region] = { startLine: item.location.line } if item.location&.line.to_i.positive?
+            if item.location&.line.to_i.positive?
+              physical[:region] = { startLine: item.location.line }
+              physical[:region][:startColumn] = item.column if item.column
+            end
             result[:locations] = [{ physicalLocation: physical }]
             result
           end
         end
-        root_path = URI::DEFAULT_PARSER.escape("#{File.expand_path(Dir.pwd)}/", /[^A-Za-z0-9\-._~\/]/)
-        root_uri = URI::File.build(path: root_path).to_s
+        root_uri = source_root_uri(Dir.pwd)
         JSON.pretty_generate(version: "2.1.0", "$schema" => "https://json.schemastore.org/sarif-2.1.0.json",
                              runs: [{ tool: { driver: { name: "bklint", version: VERSION, rules: rules } },
                                       originalUriBaseIds: { "%SRCROOT%" => { uri: root_uri } }, results: results }])
@@ -344,6 +496,49 @@ module Breadkit
 
       private
 
+      def rule_help_url(id)
+        path = File.expand_path("../../docs/rules/#{id}.md", __dir__)
+        "https://breadkit.github.io/breadkit-lint/rules/#{id}/" if File.file?(path)
+      end
+
+      def suggestion_for_rule(id, locale)
+        @guidance ||= {}
+        @guidance[locale] ||= begin
+          path = File.expand_path("../../locales/#{locale}.yml", __dir__)
+          YAML.safe_load(File.read(path, encoding: "UTF-8"), aliases: false).fetch("guidance", {})
+        end
+        @guidance[locale][id]
+      end
+
+      def source_root_uri(root)
+        path = root.tr("\\", "/")
+        path = File.expand_path(path) unless path.match?(/\A[A-Za-z]:\//)
+        path = "/#{path}" if path.match?(/\A[A-Za-z]:\//)
+        escaped = URI::DEFAULT_PARSER.escape("#{path}/", /[^A-Za-z0-9\-._~\/:]/)
+        URI::File.build(path: escaped).to_s
+      end
+
+      def teach_guidance(rule_id, locale)
+        @teach_guidance ||= {}
+        @teach_guidance[[rule_id, locale]] ||= if locale != "en"
+          suggestion_for_rule(rule_id, locale)
+        else
+          path = File.expand_path("../../docs/rules/#{rule_id}.md", __dir__)
+          File.read(path, encoding: "UTF-8").split(/\n\s*\n/)[1]&.gsub(/\s+/, " ")&.strip if File.file?(path)
+        end
+      end
+
+      def display_path(path)
+        return path.tr("\\", "/").delete_prefix("./") unless Pathname.new(path).absolute?
+        absolute = File.expand_path(path)
+        Pathname.new(absolute).relative_path_from(Pathname.new(Dir.pwd)).to_s.tr("\\", "/")
+      end
+
+      def xml_escape(value)
+        value.to_s.gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F]/, "\uFFFD")
+             .gsub(/[&<>"']/) { |char| { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&apos;" }.fetch(char) }
+      end
+
       def escape_data(value)
         value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
       end
@@ -355,51 +550,128 @@ module Breadkit
 
     class CLI
       def run(argv)
+        original_args = argv.dup
         options = { format: "text", fail_level: nil }
         parser = OptionParser.new do |opts|
           opts.banner = "Usage: bklint [options] [FILES...]"
-          opts.on("-f", "--format FORMAT", %w[text json github sarif]) { |value| options[:format] = value }
+          opts.on("-f", "--format FORMAT", %w[text json github sarif markdown junit checkstyle rdjson]) { |value| options[:format] = value }
           opts.on("-o", "--out PATH") { |value| options[:out] = value }
           opts.on("-c", "--config PATH") { |value| options[:config] = value }
           opts.on("--fail-level LEVEL", %w[error warning info]) { |value| options[:fail_level] = value }
           opts.on("--only RULES") { |value| options[:only] = value.split(",") }
           opts.on("--except RULES") { |value| options[:except] = value.split(",") }
           opts.on("--switch-states MODE", %w[none single all]) { |value| options[:switch_states] = value }
+          opts.on("--state-budget COUNT", Integer) { |value| options[:state_budget] = value }
+          opts.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+          opts.on("--stdin PATH") { |value| options[:stdin] = value }
+          opts.on("--baseline PATH") { |value| options[:baseline] = value }
+          opts.on("--generate-baseline PATH") { |value| options[:generate_baseline] = value }
+          opts.on("--diff REF") { |value| options[:diff] = value }
+          opts.on("--fix") { options[:fix] = true }
+          opts.on("--fix-check", "--fix-dry-run") { options[:fix_check] = true }
+          opts.on("--teach") { options[:teach] = true }
+          opts.on("--watch") { options[:watch] = true }
           opts.on("--list-rules") { options[:list_rules] = true }
           opts.on("--explain RULE") { |value| options[:explain] = value }
-          opts.on("--locale LOCALE", %w[ja en]) { |value| options[:locale] = value }
+          opts.on("--locale LOCALE", %w[en ja zh ko]) { |value| options[:locale] = value }
           opts.on("-v", "--version") { puts "bklint #{VERSION}"; return 0 }
           opts.on("-h", "--help") { puts opts; return 0 }
         end
         parser.parse!(argv)
+        raise Error, "timeout must be positive" if options[:timeout] && !options[:timeout].positive?
+        raise Error, "state budget must be a positive integer" if options[:state_budget] && !options[:state_budget].positive?
+        raise Error, "--teach requires --format text" if options[:teach] && options[:format] != "text"
         locale = options[:locale] || locale_from_environment
         return list_rules(locale) if options[:list_rules]
         return explain(options[:explain], locale) if options[:explain]
-        files = expand_inputs(argv)
+        raise Error, "--stdin accepts no additional file arguments" if options[:stdin] && !argv.empty?
+        if options[:stdin] && !options[:stdin].end_with?(".bk.rb", ".bk.yml", ".bk.yaml", ".bk.toml")
+          raise Error, "--stdin PATH requires a .bk.rb, .bk.yml, .bk.yaml, or .bk.toml path"
+        end
+        raise Error, "choose --baseline or --generate-baseline" if options[:baseline] && options[:generate_baseline]
+        raise Error, "--diff cannot be combined with a baseline" if options[:diff] && (options[:baseline] || options[:generate_baseline])
+        if options[:watch] && (options[:stdin] || options[:fix] || options[:fix_check] || options[:generate_baseline])
+          raise Error, "--watch cannot be combined with stdin, source fixes, or baseline generation"
+        end
+        if (options[:fix] || options[:fix_check]) && (options[:stdin] || options[:diff] || options[:baseline] || options[:generate_baseline] || options[:out])
+          raise Error, "source fixes cannot be combined with stdin, diff, baseline, or output options"
+        end
+        raise Error, "choose --fix or --fix-check" if options[:fix] && options[:fix_check]
+        files = options[:stdin] ? [options[:stdin]] : expand_inputs(argv)
+        if options[:watch]
+          original_args.delete_at(original_args.index("--watch"))
+          return watch(argv.empty? ? ["."] : argv, files, options, original_args)
+        end
+        source = $stdin.read if options[:stdin]
         configs = {}
-        results = files.flat_map do |path|
-          config_path = options[:config] || nearest_config(path)
-          unless configs.key?(config_path)
-            configs[config_path] = Config.new(config_path)
-            configs[config_path].unknown_rules.each do |rule|
-              suggestion = DidYouMean::SpellChecker.new(dictionary: Registry.all.map(&:id)).correct(rule).first
-              warn "bklint: unknown rule #{rule.inspect}#{suggestion ? "; did you mean #{suggestion.inspect}?" : ""}"
+        inspect_files = lambda do
+          files.flat_map do |path|
+            config_path = options[:config] || nearest_config(path)
+            unless configs.key?(config_path)
+              configs[config_path] = Config.new(config_path)
+              configs[config_path].unknown_rules.each do |rule|
+                suggestion = DidYouMean::SpellChecker.new(dictionary: Registry.all.map(&:id)).correct(rule).first
+                warn "bklint: unknown rule #{rule.inspect}#{suggestion ? "; did you mean #{suggestion.inspect}?" : ""}"
+              end
             end
+            config = configs[config_path]
+            config.data["AllRules"] ||= {}
+            config.data["AllRules"]["SwitchStates"] = options[:switch_states] if options[:switch_states]
+            config.data["AllRules"]["StateBudget"] = options[:state_budget] if options[:state_budget]
+            Engine.new(config: config, locale: locale).run([path], only: options[:only], except: options[:except],
+                                                           timeout: options[:timeout] || 10, source: source)
+          end
+        end
+        results = inspect_files.call
+        annotate = lambda do |items|
+          items.filter_map do |file|
+            path = file[:path]
+            next if file[:offenses].empty?
+            next unless path.end_with?(".bk.rb") && (source || File.file?(path))
+            editor = SourceEditor.new(path, source: source)
+            editor.annotate(file[:offenses])
+            [file, editor]
           end
-          config = configs[config_path]
-          config.data["AllRules"] ||= {}
-          config.data["AllRules"]["SwitchStates"] = options[:switch_states] if options[:switch_states]
-          Engine.new(config: config, locale: locale).run([path], only: options[:only], except: options[:except])
         end
+        editors = annotate.call(results)
+        planned = if options[:fix] || options[:fix_check]
+          editors.filter_map do |file, editor|
+            next if File.symlink?(file[:path])
+            edits = editor.plan(file[:offenses])
+            [file, editor, edits] unless edits.empty?
+          end
+        else
+          []
+        end
+        planned.each do |file, _editor, edits|
+          edits.each { |edit| warn "bklint: #{options[:fix_check] ? 'would' : 'will'} #{edit.description} at #{file[:path]}:#{edit.line}" }
+        end
+        if options[:fix] && !planned.empty?
+          planned.each { |_file, editor, edits| editor.apply(edits) }
+          results = inspect_files.call
+          annotate.call(results)
+        end
+        if options[:generate_baseline]
+          count = Baseline.new(options[:generate_baseline]).write(results)
+          puts "Wrote #{count} baseline offenses to #{options[:generate_baseline]}"
+          return 0
+        end
+        results = Baseline.new(options[:baseline]).filter(results) if options[:baseline]
+        results = filter_diff(results, files, options, locale: locale) if options[:diff]
         formatter = Formatter.new
         output = case options[:format]
-        when "json" then formatter.json(results)
+        when "json" then formatter.json(results, locale: locale)
         when "github" then formatter.github(results)
-        when "sarif" then formatter.sarif(results)
-        else formatter.text(results, locale: locale)
+        when "sarif" then formatter.sarif(results, locale: locale)
+        when "markdown" then formatter.markdown(results)
+        when "junit" then formatter.junit(results)
+        when "checkstyle" then formatter.checkstyle(results)
+        when "rdjson" then formatter.rdjson(results)
+        else formatter.text(results, locale: locale, teach: options[:teach])
         end
         options[:out] ? File.write(options[:out], output + "\n") : puts(output)
         return 2 if results.any? { |file| file[:offenses].any? { |item| item.rule.start_with?("Fatal/") } }
+        return 1 if options[:fix_check] && !planned.empty?
         results.any? do |file|
           config = configs[options[:config] || nearest_config(file[:path])]
           Engine.new(config: config).fail?([file], options[:fail_level] || config.fail_level)
@@ -411,9 +683,93 @@ module Breadkit
 
       private
 
+      def watch(roots, files, options, args)
+        watched = (files + [options[:config], options[:baseline]].compact + files.filter_map { |path| nearest_config(path) }).uniq
+        snapshot = watch_snapshot(roots, watched, options[:out])
+        warn "bklint: watching circuit and part files; press Ctrl-C to stop"
+        loop do
+          run(args.dup)
+          loop do
+            sleep 0.5
+            updated = watch_snapshot(roots, watched, options[:out])
+            next if updated == snapshot
+
+            snapshot = updated
+            break
+          end
+        end
+      rescue Interrupt
+        0
+      end
+
+      def watch_snapshot(roots, watched, output)
+        # ponytail: poll the project tree; use file events if large projects make scans slow.
+        files = watched.dup
+        roots.each do |entry|
+          root = File.directory?(entry) ? entry : File.dirname(entry)
+          Find.find(root) do |path|
+            if File.directory?(path)
+              Find.prune if path != root && (File.basename(path).start_with?(".") || File.basename(path) == "node_modules")
+            elsif path.end_with?(".bk.rb", ".yml", ".yaml", ".toml", ".json")
+              files << path
+            end
+          end
+        end
+        files.map { |path| File.expand_path(path) }.uniq.sort.reject { |path| output && path == File.expand_path(output) }.to_h do |path|
+          stat = File.stat(path)
+          [path, [stat.mtime.to_r, stat.size]]
+        rescue Errno::ENOENT
+          [path, nil]
+        end
+      end
+
+      def filter_diff(results, files, options, locale:)
+        root, error, status = Open3.capture3("git", "rev-parse", "--show-toplevel")
+        raise Error, "--diff requires a Git repository: #{error.strip}" unless status.success?
+
+        root = root.strip
+        Dir.mktmpdir("bklint-diff-") do |directory|
+          archive = File.join(directory, "base.tar")
+          base_root = File.join(directory, "base")
+          FileUtils.mkdir_p(base_root)
+          _out, error, status = Open3.capture3("git", "-C", root, "archive", "--format=tar", "-o", archive, options[:diff])
+          raise Error, "cannot read Git revision #{options[:diff]}: #{error.strip}" unless status.success?
+          _out, error, status = Open3.capture3("tar", "-xf", "base.tar", "-C", "base", chdir: directory)
+          raise Error, "cannot unpack Git revision #{options[:diff]}: #{error.strip}" unless status.success?
+
+          baseline_files = files.flat_map do |file|
+            relative = Pathname.new(File.expand_path(file)).relative_path_from(Pathname.new(root)).to_s
+            raise Error, "--diff input is outside the Git repository: #{file}" if relative == ".." || relative.start_with?("../")
+
+            base_path = File.join(base_root, relative)
+            next [] unless File.file?(base_path)
+
+            config = Config.new(options[:config] || nearest_config(base_path))
+            config.data["AllRules"] ||= {}
+            config.data["AllRules"]["SwitchStates"] = options[:switch_states] if options[:switch_states]
+            config.data["AllRules"]["StateBudget"] = options[:state_budget] if options[:state_budget]
+            Engine.new(config: config, locale: locale).run([base_path], only: options[:only], except: options[:except],
+                                                            timeout: options[:timeout] || 10).map do |result|
+              result[:path] = File.expand_path(file)
+              result[:offenses].each do |item|
+                if item.location&.path&.start_with?("#{base_root}/")
+                  item.location.path = File.join(root, item.location.path.delete_prefix("#{base_root}/"))
+                end
+                item.message = item.message.gsub(base_root, root)
+              end
+              result
+            end
+          end
+          baseline = Baseline.new(File.join(directory, "baseline.json"))
+          baseline.write(baseline_files)
+          baseline.filter(results)
+        end
+      end
+
       def locale_from_environment
         value = %w[LC_ALL LC_MESSAGES LANG].map { |key| ENV[key] }.find { |item| !item.to_s.empty? }
-        value.to_s.start_with?("ja") ? "ja" : "en"
+        language = value.to_s[0, 2].downcase
+        %w[ja zh ko].include?(language) ? language : "en"
       end
 
       def nearest_config(path)
@@ -435,7 +791,7 @@ module Breadkit
           Find.find(root) do |path|
             if File.directory?(path)
               Find.prune if path != root && (File.basename(path).start_with?(".") || File.basename(path) == "node_modules")
-            elsif path.end_with?(".bk.rb") || (path.end_with?(".json") && ir_json?(path))
+            elsif path.end_with?(".bk.rb", ".bk.yml", ".bk.yaml", ".bk.toml") || (path.end_with?(".json") && ir_json?(path))
               found << path
             end
           end
@@ -446,7 +802,7 @@ module Breadkit
       def ir_json?(path)
         return true if path.end_with?(".bk.json", ".breadkit.json")
         data = JSON.parse(File.read(path, encoding: "UTF-8"))
-        data.is_a?(Hash) && data["schema_version"] == 1
+        data.is_a?(Hash) && [1, 2].include?(data["schema_version"])
       rescue JSON::ParserError, Encoding::InvalidByteSequenceError
         false
       end
@@ -459,6 +815,13 @@ module Breadkit
       def explain(id, locale)
         rule = Registry.all.find { |item| item.id == id }
         raise Error, "unknown rule #{id}" unless rule
+        if locale != "en"
+          translations = YAML.safe_load(File.read(File.expand_path("../../locales/#{locale}.yml", __dir__), encoding: "UTF-8"), aliases: false) || {}
+          description = translations.dig("rules", rule.id) || rule.description
+          guidance = translations.dig("guidance", rule.id)
+          puts "# #{rule.id}\n\n#{description}#{guidance ? "\n\n#{guidance}" : ""}"
+          return 0
+        end
         path = File.expand_path("../../docs/rules/#{rule.id}.md", __dir__)
         puts File.file?(path) ? File.read(path, encoding: "UTF-8") : "#{rule.id} (#{rule.severity})\n#{localized_description(rule, locale)}"
         0