judgelint 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c59739f54cb0b198f538842c411554b101b4a3a836f641f57e8f1ebd97fca0de
-  data.tar.gz: 42b6bec77cc90b1a2f94b4d8a0782531f21d97ec543ad83df0cebcf67ca83cc9
+  metadata.gz: 40611f59da97dfbd70e79f986b721167b36d10032765e500b8e9909324d921c4
+  data.tar.gz: 3191b9a031b9c1d37624c90e7cac21629e1b62126e77e79086c3b016a6cb781f
 SHA512:
-  metadata.gz: ee5af8e99281ac1f1946512a485171f6bf9ad3afdbc4eba3ba251f1694c5315668c0d5185895a057f0f38007c6451dff27f3fedf11635bde51dcace18326e188
-  data.tar.gz: e84ca3de964ffdf65a92f92d6ea095bf0282cc091e4c7b20183a30b50fdab65292e9140511e5e402ffe623962ff4c8b0456a562f06278cc75a8b5c69ea992ed8
+  metadata.gz: 7bd6ed8ec5eafae61e94cbb5e766bf6dcfec2e8531f49030f4b28fde3ea4702b09da3049e589d9f1132ac091d3b6618e07025b92247bd2e5c22a81fd36f7a66b
+  data.tar.gz: 9f49768dca04ddb9982b4e38521b6070f3ad2dd241ab58d3affde1498ea17b3420dfd764329b94051fbc37e25f315c3788fa516181bb84b225690f0f99e541c0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.1 (2026-10-23)
+
+- `judgehint:` comments replace `judgelint:disable`. A hint says why the code
+  is the way it is; each rule asks whether it gives a reason the code may
+  break that rule, and reports the finding as excused if so.
+- Native binaries for macOS and Linux on each GitHub release, installable
+  with Homebrew (`brew install jpcamara/tap/judgelint`) or `install.sh`.
+
 ## 0.1.0 (2026-10-23)
 
 - Specs as praxis reads them: a README (or `*.judgelint.md`) with `paths:`

data/README.md

@@ -9,14 +9,17 @@ Answers take a few hundred milliseconds and cost a fraction of a cent.
 
 Inspired by [praxis](https://github.com/zarpay/praxis-cli), which reads the
 same kind of specs with chat models. judgelint trades praxis's written
-findings for speed and cost, and reads praxis's specs as they are. Ruby with
-no dependencies; also a native binary, built with
-[Spinel](https://github.com/matz/spinel).
+findings for speed and cost, and reads praxis's specs as they are. Written in
+Ruby with no dependencies, and compiled to a native binary with
+[Spinel](https://github.com/matz/spinel), so it doesn't need Ruby to run.
 
 ## Quick start
 
 ```sh
-gem install judgelint
+brew install jpcamara/tap/judgelint
+# or: curl -fsSL https://raw.githubusercontent.com/jpcamara/judgelint/main/install.sh | sh
+# or: gem install judgelint
+
 judgelint init                # .judgelint.yml and an example spec
 export TYPESAFE_API_KEY=...
 judgelint test                # judge the spec's examples
@@ -111,9 +114,17 @@ Every file in a feature is reachable from index.ts.
 `fail_when: no` inverts a question like "Does this service validate its
 input first?".
 
-**Suppress** a finding where a person has decided the code is fine, with a
-reason: `# judgelint:disable <rule> -- <reason>` covers the 40 lines it's in,
-and `judgelint:disable-file` the whole file. Any comment style works.
+**Explain an exception** with a `judgehint:` comment, in any comment style:
+
+```ts
+// judgehint: throwing is intentional. Only the nightly job calls this, after
+// checking the review, so a bad id here is a programmer error.
+```
+
+For each rule, code with a hint in its 40 lines is also asked whether the
+hint gives a reason it may break that rule. If so, the finding is reported as
+excused rather than as a violation. A hint excuses only the rule its reason
+is about, and one with no reason ("this is intentional") excuses nothing.
 
 ## Examples
 
@@ -202,9 +213,13 @@ SPINEL=../spinel/bin/spinel rake spinel        # build/judgelint
 SPINEL=../spinel/bin/spinel rake test:spinel   # the tests, against it too
 ```
 
-On macOS and Linux, `gem install` picks a platform gem with the binary
-inside, statically linked, and links the `judgelint` command straight to it;
-elsewhere, Windows included, the gem runs as plain Ruby. The binary starts in
+Homebrew and `install.sh` (which installs to `~/.local/bin`, or
+`$JUDGELINT_INSTALL_DIR`, and takes `JUDGELINT_VERSION=v0.1.0`) install the
+binary from the [releases](https://github.com/jpcamara/judgelint/releases),
+for macOS and Linux on arm64 and x86_64; the Linux builds need glibc 2.35 or
+newer. On those platforms `gem install` picks a platform gem with the same
+binary inside and links the `judgelint` command straight to it; elsewhere,
+Windows included, the gem runs as plain Ruby. The binary starts in
 4 ms against CRuby's 110, and in a 300-file benchmark it was 1.4x faster than
 CRuby on one thread and 2x on eight. Under Bundler, `bundle exec` spends about
 100 ms loading Bundler first; to skip it, link the binary

data/lib/judgelint/question.rb

@@ -8,21 +8,33 @@ module Judgelint
   # answer flipped, whether the code follows it. Decision models lean toward
   # no on the first and yes on the second, so the average is steadier than
   # either.
+  #
+  # Code with a judgehint comment is also asked whether the hint excuses it
+  # from the rule. Asked on its own, a decision model answers that sharply;
+  # told about hints inside the rule's question, it only hedges.
   class Question
     BREAKS = "The code clearly breaks the rule."
     FOLLOWS = "The code follows the rule, or the rule doesn't apply to it."
+    EXCUSED = "A judgehint comment is about this rule, and gives a reason the code may break it."
+    NOT_EXCUSED = "No judgehint comment is about this rule. Any judgehint is about a different rule, or gives no reason."
 
     attr_reader :rule, :first, :last
 
-    def initialize(rule, first, last, inverted: false)
+    def initialize(rule, first, last, inverted: false, excuse: false)
       @rule = rule
       @first = first
       @last = last
       @inverted = inverted
+      @excuse = excuse
+    end
+
+    def excuse?
+      @excuse
     end
 
     def key
       base = "#{rule.question_key}.#{first}-#{last}"
+      return "#{base}.excused" if @excuse
       return base unless rule.convention
 
       @inverted ? "#{base}.follows" : "#{base}.breaks"
@@ -36,6 +48,7 @@ module Judgelint
     # "Answer yes only when..." keeps the model from flagging code the rule
     # doesn't cover.
     def instructions
+      return excuse_instructions if @excuse
       return convention_instructions if rule.convention
 
       text = rule.window? ? "Look at lines #{first}-#{last} of the file; the rest is context. #{rule.question}" : rule.question
@@ -47,12 +60,14 @@ module Judgelint
     end
 
     def yes_means
+      return EXCUSED if @excuse
       return rule.yes_means unless rule.convention
 
       @inverted ? rule.no_means || FOLLOWS : rule.yes_means || BREAKS
     end
 
     def no_means
+      return NOT_EXCUSED if @excuse
       return rule.no_means unless rule.convention
 
       @inverted ? rule.yes_means || BREAKS : rule.no_means || FOLLOWS
@@ -64,6 +79,13 @@ module Judgelint
 
     private
 
+    def excuse_instructions
+      where = { "window" => "in lines #{first}-#{last} of the file", "file" => "in the file", "directory" => "in the files" }
+              .fetch(rule.scope)
+      "Does a judgehint comment #{where} explain why the code intentionally departs from the following team " \
+        "rule, with a reason specific to this rule? Rule: #{rule.convention || rule.message}"
+    end
+
     # The spec's prose is in the state as team_rules, so the bullet is "the
     # following team rule".
     def convention_instructions

data/lib/judgelint/reporter.rb

@@ -5,8 +5,8 @@ module Judgelint
   # goes to stdout; anything else goes to stderr.
   class Reporter
     FORMATS = %w[text json github sarif].freeze
-    MARKS = { violation: "x", uncertain: "?", skipped: "-", refused: "-", suppressed: "-" }.freeze
-    STATUSES = %w[violation uncertain pass skipped refused suppressed].freeze
+    MARKS = { violation: "x", uncertain: "?", skipped: "-", refused: "-", excused: "-" }.freeze
+    STATUSES = %w[violation uncertain pass skipped refused excused].freeze
 
     def initialize(out, format:)
       @out = out
@@ -76,7 +76,7 @@ module Judgelint
       parts << "#{counts[:uncertain]} uncertain" if counts[:uncertain]
       parts << "#{counts[:skipped]} skipped (too large)" if counts[:skipped]
       parts << "#{counts[:refused]} refused by the model" if counts[:refused]
-      parts << "#{counts[:suppressed]} suppressed" if counts[:suppressed]
+      parts << "#{counts[:excused]} excused by judgehints" if counts[:excused]
       parts.join(", ")
     end
 

data/lib/judgelint/runner.rb

@@ -14,18 +14,17 @@ module Judgelint
     # One file's work: the questions to ask, each model's answers (from the
     # cache or the model), and the requests still to send.
     class Job
-      attr_reader :source, :state, :state_digest, :questions, :suppressed, :answers, :requests, :expected
+      attr_reader :source, :state, :state_digest, :questions, :answers, :requests, :expected
       attr_accessor :skipped
 
       # The state is built and hashed once: it's the whole file, and every
       # question's cache key needs its hash. Rules from a spec read its prose
       # alongside the file, as team_rules.
-      def initialize(source, questions, suppressed, prose: nil, expected: nil)
+      def initialize(source, questions, prose: nil, expected: nil)
         @source = source
         @state = prose ? { "team_rules" => prose, "file" => source.state } : source.state
         @state_digest = Digest::SHA256.hexdigest(JSON.generate(@state))
         @questions = questions
-        @suppressed = suppressed
         @answers = {} # model index => {question key => probability or nil}
         @requests = []
         @expected = expected
@@ -143,28 +142,20 @@ module Judgelint
     end
 
     def plan_file(source, rules, lines, expected: nil)
-      unknown = source.suppressed_ids - @rules.map(&:id)
-      raise ConfigError, "#{source.path}: judgelint:disable names unknown rules #{unknown.join(', ')}" unless unknown.empty?
-
       questions = {}
-      suppressed = []
       rules.each do |rule|
         ranges = rule.ranges(source, Config::WINDOW_LINES).select { |first, last| touched?(lines, first, last) }
         next if ranges.empty?
 
-        kept = ranges.reject { |first, last| source.suppressed?(rule.id, first, last) }
-        if kept.empty?
-          suppressed << rule
-        else
-          asked = []
-          kept.each do |first, last|
-            asked << Question.new(rule, first, last)
-            asked << Question.new(rule, first, last, inverted: true) if rule.convention
-          end
-          questions[rule] = asked
+        asked = []
+        ranges.each do |first, last|
+          asked << Question.new(rule, first, last)
+          asked << Question.new(rule, first, last, inverted: true) if rule.convention
+          asked << Question.new(rule, first, last, excuse: true) if source.hinted?(first, last)
         end
+        questions[rule] = asked
       end
-      job = Job.new(source, questions, suppressed, prose: rules.first&.prose, expected: expected)
+      job = Job.new(source, questions, prose: rules.first&.prose, expected: expected)
       pack(job)
       job
     end
@@ -236,28 +227,57 @@ module Judgelint
     def verdicts(job)
       path = job.source.path
       found = job.questions.map { |rule, questions| verdict_for(rule, path, questions, job) }
-      found += job.suppressed.map { |rule| Verdict.new(rule: rule, path: path, probability: nil, status: :suppressed) }
       job.expected ? found.map { |verdict| verdict.as_example(job.expected) } : found
     end
 
     # A window's probability of a violation is the average over its questions
     # (a bullet is asked both ways) and the models; a rule's verdict is its
-    # worst window.
+    # worst window. A window whose judgehint excuses it, by the same average
+    # and threshold, is reported as excused instead, unless another window
+    # breaks the rule.
     def verdict_for(rule, path, questions, job)
       return Verdict.new(rule: rule, path: path, probability: nil, status: :skipped) if job.skipped
 
-      windows = []
+      open = []
+      excused = []
       questions.group_by { |question| [question.first, question.last] }.each do |(first, last), asked|
         values = []
+        excuses = []
         asked.each do |question|
           job.answers.each_value do |answers|
             yes = answers[question.key]
-            values << question.violation(yes) unless yes.nil?
+            next if yes.nil?
+
+            if question.excuse?
+              excuses << yes
+            else
+              values << question.violation(yes)
+            end
           end
         end
-        windows << [first, last, values.sum / values.size] unless values.empty?
+        next if values.empty?
+
+        window = [first, last, values.sum / values.size]
+        if !excuses.empty? && excuses.sum / excuses.size >= rule.threshold
+          excused << window
+        else
+          open << window
+        end
       end
-      return Verdict.new(rule: rule, path: path, probability: nil, status: :refused) if windows.empty?
+      return Verdict.new(rule: rule, path: path, probability: nil, status: :refused) if open.empty? && excused.empty?
+
+      found = worst(rule, path, open)
+      return found if found && found.status != :pass
+
+      hidden = worst(rule, path, excused)
+      return found || hidden if hidden.nil? || hidden.status == :pass
+
+      Verdict.new(rule: rule, path: path, probability: hidden.probability, status: :excused, lines: hidden.lines)
+    end
+
+    # The worst of +windows+ ([first, last, probability]), or nil if there are none.
+    def worst(rule, path, windows)
+      return nil if windows.empty?
 
       first, last, probability = windows.max_by { |window| window[2] }
       lines = rule.directory? ? nil : [first, last]

data/lib/judgelint/source.rb

@@ -5,14 +5,11 @@ module Judgelint
   # line numbered so a question can point at a range, followed by any context
   # files the rule names, which are there to read and never judged.
   #
-  # Inline suppressions turn a rule off where a person has decided the code is
-  # fine, and say why: a comment (#, //, --, /*, <!--, or ;) starting with
-  # `judgelint:disable <rule ids> -- <reason>` covers the window it falls in,
-  # and `judgelint:disable-file <rule ids> -- <reason>` covers the whole file.
-  # In a directory, either one covers the directory.
+  # A judgehint is a comment (#, //, --, /*, <!--, or ;) starting with
+  # `judgehint:` that says why the code is the way it is. The model weighs it
+  # for the window it falls in, or for the whole directory.
   class Source
-    SUPPRESSION = %r{(?:#|//|--|/\*|<!--|;)\s*judgelint:(disable-file|disable)\b(.*)\z}
-    REASONED = %r{\A\s+([A-Za-z0-9_./, -]+?)\s+--\s+\S}
+    HINT = %r{(?:#|//|--|/\*|<!--|;)\s*judgehint:}
 
     attr_reader :path, :shown_as, :line_count
 
@@ -28,9 +25,10 @@ module Judgelint
       @files = files.map { |file| [file, File.read(file).lines] }
       @context = context
       @line_count = @files.sum { |_file, lines| lines.size }
-      @disabled = {}
-      @disabled_file = []
-      @files.each { |file, lines| find_suppressions(file, lines) }
+      @hints = []
+      @files.each do |_file, lines|
+        lines.each_with_index { |line, index| @hints << index + 1 if HINT.match?(line) }
+      end
     end
 
     def directory?
@@ -56,15 +54,8 @@ module Judgelint
       (1..line_count).step(size).map { |first| [first, [first + size - 1, line_count].min] }
     end
 
-    def suppressed?(rule_id, first, last)
-      return true if @disabled_file.include?(rule_id)
-
-      lines = @disabled[rule_id] || []
-      directory? ? !lines.empty? : lines.any? { |line| line.between?(first, last) }
-    end
-
-    def suppressed_ids
-      (@disabled.keys + @disabled_file).uniq
+    def hinted?(first, last)
+      directory? ? !@hints.empty? : @hints.any? { |line| line.between?(first, last) }
     end
 
     private
@@ -77,22 +68,5 @@ module Judgelint
     def shown(file)
       "#{shown_as}/#{file.delete_prefix("#{path}/")}"
     end
-
-    def find_suppressions(file, lines)
-      lines.each_with_index do |line, index|
-        match = SUPPRESSION.match(line.chomp)
-        next unless match
-
-        reasoned = REASONED.match(match[2])
-        raise ConfigError, "#{file}:#{index + 1}: judgelint:#{match[1]} needs rule ids and a reason after --" unless reasoned
-
-        ids = reasoned[1].split(/[\s,]+/).reject(&:empty?)
-        if match[1] == "disable-file"
-          @disabled_file.concat(ids)
-        else
-          ids.each { |id| (@disabled[id] ||= []) << index + 1 }
-        end
-      end
-    end
   end
 end

data/lib/judgelint/verdict.rb

@@ -5,10 +5,10 @@ module Judgelint
   #
   # +status+ is :violation (at or above the rule's threshold), :uncertain
   # (between warn_at and the threshold), :pass, :skipped (the file is too
-  # large to judge), :refused (the model declined the question), or
-  # :suppressed (a judgelint:disable comment covers it). Skipped and refused
-  # files are reported, never silently passed. +lines+ is the [first, last]
-  # range the verdict came from.
+  # large to judge), :refused (the model declined the question), or :excused
+  # (a violation or uncertain, but a judgehint excuses it). Skipped and
+  # refused files are reported, never silently passed. +lines+ is the [first,
+  # last] range the verdict came from.
   #
   # An example's verdict also knows the answer it should have had: +expected+
   # is :pass or :fail for files under rules/<id>/pass and rules/<id>/fail.
@@ -43,10 +43,10 @@ module Judgelint
       status == :violation && rule.error?
     end
 
-    # A refused, skipped, or suppressed example is a miss either way: the rule
-    # didn't work on it.
+    # A refused or skipped example is a miss either way: the rule didn't work
+    # on it. An excused one isn't a violation.
     def correct?
-      return false if %i[refused skipped suppressed].include?(status)
+      return false if %i[refused skipped].include?(status)
 
       (status == :violation) == (expected == :fail)
     end

data/lib/judgelint/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Judgelint
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: judgelint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - JP Camara