judgelint 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a90b0ee415a2b08188fd8141eef3ea4f725e3317a886b487d86ed4d1463c88a4
-  data.tar.gz: e0c57f2b25e7775a9dcedae5be947de53e8a1bc6ef363d4f07c3a601c8bcfb8d
+  metadata.gz: fe98d85a793082f8e0660331fd151d1d169ec16937f7a187f4f30c3e52058c54
+  data.tar.gz: 54aefdc8a09b29cf66ead37809cc5b2a78df0758a5753ab3cc2411a2d3d35f1d
 SHA512:
-  metadata.gz: 8849be7a19c2fe4e64304109120856ae8adbd02e3b6cca0894b6cecc2a56be27fa9af3f5e7c805d8c32f6df73e40f42a7b0b2e15e8628c93b938371d605651a8
-  data.tar.gz: 3df1f283287488314cbb5fb8c2ac21f8b79ead7ed94ce5eb4a2354fd93ca2979f3984a73a24898a4c9a8467c29c2fe698887c52aef7deae2b001e4a1d87d7913
+  metadata.gz: f9212995fc03c6f61589de5f8f0293d10ddde6003176037747d704789326fe95b4c16e0e61584b7c1bfdda868c2576c7381db8d38eeadfeb66aee96dc3b0af6c
+  data.tar.gz: 5ddefc93e017f7313eae0f4ea844cc7416ac58b0e1fc763c32c6800c7800e5a1baa0f74c025743076d89eadc1258bc6339b3045c996c553eb2dc86b72f3abe95

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.10 (2026-10-27)
+
+- `check` and `test` use far less memory and run faster. Against 0.1.9 on
+  a synthetic project, the native binary uses 84–89% less memory, and
+  Ruby 73–87% less. Both are 23–51% faster.
+  - Files of the same shape share their questions.
+  - A planned file is read again when its request is sent instead of being
+    kept. A file that changed in between stops the run with an error.
+  - The cache stays on disk and is looked up an entry at a time.
+  - Connections to the model are kept open between requests.
+  - Each glob pattern is walked once.
+- Output and cache files are unchanged.
+
 ## 0.1.9 (2026-10-27)
 
 - `check` uses much less memory on large projects. On 50,000 files its

data/lib/judgelint/cache.rb

@@ -4,12 +4,43 @@ module Judgelint
   # Stores each answer under a hash of everything that produced it: the state
   # the model saw (path and numbered contents), the question asked of it, and
   # the model. Changing any of them is a miss. Safe to share across threads.
+  #
+  # A cache file in the form #save writes stays on disk: loading it checks
+  # every entry and keeps its key and where it is, and a lookup finds the
+  # key by binary search and reads that entry back. Any other JSON object is
+  # read whole. New answers wait for #save in a scratch file beside the
+  # cache, already in the form it writes. A cache used again after it's saved
+  # reads its new file first.
   class Cache
+    # A line that starts an entry, without its line ending: its key, then
+    # its value or the value's first line.
+    ENTRY = /\A  "([0-9a-f]{64})": (.*)\z/
+    # Values in the plain form #save writes, which parse without being
+    # parsed: a number or literal, or a line of a hash of them with an ASCII
+    # name. Anything else is parsed to check it.
+    SCALAR = /\A(?:-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|null|true|false)\z/
+    # Spinel's JSON parser outruns its regexps, where CRuby's parser makes
+    # more garbage than its regexps do, so only CRuby checks by pattern.
+    BY_PATTERN = RUBY_ENGINE != "spinel"
+    MEMBER = %r{\A    "(?:[\x20\x21\x23-\x5b\x5d-\x7e]|\\["\\/bfnrt])*": (?:-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|null|true|false),?\r?\n\z}
+    KEY_SIZE = 64
+    # Where a value starts in its entry's first line.
+    VALUE_AT = 70
+    # A value's place in a file is kept as one Integer: its offset, shifted
+    # past its length.
+    SPAN_BITS = 32
+
     def initialize(path)
       @path = path
-      @entries = load_entries
+      @keys = +"" # the file's keys in order, end to end
+      @places = [] # the place of each key's value in the file
+      @entries = {} # every answer from a file read whole, or stored without a file
+      @stored_keys = +"" # the keys of answers stored this run, end to end, in the order stored
+      @stored_places = [] # the place of each in the scratch file
       @dirty = false
+      @saved = false
       @lock = Mutex.new
+      load_entries
     end
 
     def self.key(question_digest, state_digest, model_label)
@@ -17,37 +48,297 @@ module Judgelint
     end
 
     def fetch(key)
-      @lock.synchronize { @entries[key] }
+      @lock.synchronize do
+        reload if @saved
+        if (stored = stored(key))
+          read(@scratch, @stored_places[stored])
+        elsif (found = find(key))
+          read(@file, @places[found])
+        else
+          @entries[key]
+        end
+      end
+    end
+
+    # Makes room for about +count+ answers to be stored, so their keys don't
+    # grow a piece at a time.
+    def reserve(count)
+      @lock.synchronize do
+        return unless @path
+
+        reload if @saved
+        @stored_keys = String.new(capacity: count * KEY_SIZE) << @stored_keys if @stored_keys.bytesize < count * KEY_SIZE
+      end
     end
 
     def store(key, yes_probability)
       @lock.synchronize do
-        @entries[key] = yes_probability
+        reload if @saved
         @dirty = true
+        if @path
+          text = indented(yes_probability)
+          @scratch ||= scratch
+          @stored_keys << key
+          @stored_places << place(@scratch_size, text.bytesize)
+          @scratch.write(text)
+          @scratch.flush
+          @scratch_size += text.bytesize
+        else
+          @entries[key] = yes_probability
+        end
       end
     end
 
+    # Writes every entry in key order, as JSON.pretty_generate does, one at a
+    # time into a new file that then replaces the old one.
     def save
       @lock.synchronize do
         return unless @path && @dirty
 
         FileUtils.mkdir_p(File.dirname(@path))
-        File.write(@path, "#{JSON.pretty_generate(@entries.sort.to_h)}\n")
+        temp = "#{@path}.#{Process.pid}.tmp"
+        File.open(temp, "w") { |out| write(out) }
+        close
+        File.rename(temp, @path)
         @dirty = false
+        @saved = true
       end
     end
 
     private
 
+    # The index of +key+ among the file's keys, or nil.
+    def find(key)
+      low = 0
+      high = @places.size - 1
+      while low <= high
+        middle = (low + high) / 2
+        other = @keys.byteslice(middle * KEY_SIZE, KEY_SIZE)
+        return middle if other == key
+
+        other < key ? low = middle + 1 : high = middle - 1
+      end
+      nil
+    end
+
+    # The latest answer stored this run under +key+, or nil. A run looks its
+    # answers up before it stores any, so there are rarely any to look at.
+    def stored(key)
+      index = @stored_places.size - 1
+      while index >= 0
+        return index if @stored_keys.byteslice(index * KEY_SIZE, KEY_SIZE) == key
+
+        index -= 1
+      end
+      nil
+    end
+
+    def read(file, at)
+      JSON.parse(raw(file, at))
+    end
+
+    def raw(file, at)
+      file.pread(at & ((1 << SPAN_BITS) - 1), at >> SPAN_BITS)
+    end
+
+    def place(offset, length)
+      (offset << SPAN_BITS) | length
+    end
+
+    # Deleted as soon as it's open where the system allows that, so it goes
+    # away with the process; elsewhere, once the cache is saved.
+    def scratch
+      FileUtils.mkdir_p(File.dirname(@path))
+      path = "#{@path}.#{Process.pid}.answers"
+      file = File.open(path, "w+b")
+      begin
+        File.delete(path)
+      rescue SystemCallError
+        @scratch_path = path
+      end
+      @scratch_size = 0
+      file
+    end
+
+    def reload
+      @saved = false
+      @keys = +""
+      @places = []
+      @entries = {}
+      @stored_keys = +""
+      @stored_places = []
+      @scratch = nil
+      @scratch_path = nil
+      load_entries
+    end
+
+    # The file can't be replaced while it's open everywhere.
+    def close
+      @file&.close
+      @scratch&.close
+      File.delete(@scratch_path) if @scratch_path
+    end
+
+    # Merges the file's entries, or those read whole, with the answers stored
+    # this run, which replace any with the same key.
+    def write(out)
+      whole = @entries.keys.sort
+      kept = whole.empty? ? @places.size : whole.size
+      count = 0
+      i = 0
+      stored_buckets.each do |bucket|
+        keys = bucket.map { |index| @stored_keys.byteslice(index * KEY_SIZE, KEY_SIZE) }
+        latest(keys).each do |n|
+          key = keys[n]
+          while i < kept && (mine = kept_key(whole, i)) < key
+            count = entry(out, count, mine, kept_text(whole, i))
+            i += 1
+          end
+          i += 1 if i < kept && kept_key(whole, i) == key
+          count = entry(out, count, key, raw(@scratch, @stored_places[bucket[n]]))
+        end
+      end
+      while i < kept
+        count = entry(out, count, kept_key(whole, i), kept_text(whole, i))
+        i += 1
+      end
+      out.write(count.zero? ? "{}\n" : "\n}\n")
+    end
+
+    # +text+ is the value, indented to sit in the file's object.
+    def entry(out, count, key, text)
+      out.write(count.zero? ? "{\n  " : ",\n  ")
+      out.write(JSON.generate(key))
+      out.write(": ")
+      out.write(text)
+      count + 1
+    end
+
+    def indented(value)
+      JSON.pretty_generate(value).gsub("\n", "\n  ")
+    end
+
+    def kept_key(whole, index)
+      whole.empty? ? @keys.byteslice(index * KEY_SIZE, KEY_SIZE) : whole[index]
+    end
+
+    def kept_text(whole, index)
+      indented(whole.empty? ? read(@file, @places[index]) : @entries[whole[index]])
+    end
+
+    # The answers stored this run, by the first two hex digits of their keys:
+    # in key order a bucket at a time, so only one bucket's keys are out at
+    # once.
+    def stored_buckets
+      buckets = Array.new(256) { [] }
+      @stored_places.size.times do |index|
+        at = index * KEY_SIZE
+        buckets[(digit(@stored_keys.getbyte(at)) << 4) | digit(@stored_keys.getbyte(at + 1))] << index
+      end
+      buckets
+    end
+
+    def digit(byte)
+      byte < 97 ? byte - 48 : byte - 87
+    end
+
+    # The indexes of +keys+ in key order, keeping the latest of any stored twice.
+    def latest(keys)
+      found = []
+      (0...keys.size).sort_by { |index| keys[index] }.each do |index|
+        if !found.empty? && keys[found.last] == keys[index]
+          found[-1] = index if index > found.last
+        else
+          found << index
+        end
+      end
+      found
+    end
+
     def load_entries
-      return {} unless @path && File.exist?(@path)
+      return unless @path && File.exist?(@path)
 
+      @file = File.open(@path, "rb")
+      return if index
+
+      @keys = +""
+      @places = []
       data = JSON.parse(File.read(@path))
       raise ConfigError, "#{@path} isn't a judgelint cache; delete it to start over" unless data.is_a?(Hash)
 
-      data
+      @entries = data
     rescue JSON::ParserError
       raise ConfigError, "#{@path} isn't valid JSON; delete it to start over"
     end
+
+    # Indexes a file in the form #save writes, with its keys in order,
+    # checking that each value parses. Lines may end in CRLF, as #save writes
+    # them on Windows. False for anything else.
+    def index
+      offset = 0
+      last = nil # the latest key
+      open = false # inside a value that spans lines
+      start = 0
+      plain = false # the open value's lines are all plain so far
+      comma = true # the open value's last line ended in a comma
+      ended = false # read the entry without a comma
+      closed = false # read the final brace
+      @file.each_line do |line|
+        return false if closed
+
+        if open && line.start_with?("    ")
+          plain &&= BY_PATTERN && comma && line.match?(MEMBER)
+          comma = line.end_with?(",\n", ",\r\n")
+          offset += line.bytesize
+          next
+        end
+
+        bare = line.chomp
+        if offset.zero?
+          return false unless bare == "{" || bare == "{}"
+
+          closed = bare == "{}"
+        elsif open
+          return false unless bare == "  }" || bare == "  },"
+          return false unless indexed(last, start, offset + 3 - start, plain && !comma)
+
+          open = false
+          ended = bare == "  }"
+        elsif ended
+          return false unless bare == "}"
+
+          closed = true
+        else
+          match = ENTRY.match(bare)
+          return false unless match && (last.nil? || last < match[1])
+
+          last = match[1]
+          rest = match[2]
+          start = offset + VALUE_AT
+          if rest == "{"
+            open = true
+            plain = true
+            comma = true
+          else
+            ended = !rest.end_with?(",")
+            value = ended ? rest : rest.delete_suffix(",")
+            return false unless indexed(last, start, value.bytesize, BY_PATTERN && value.match?(SCALAR), value)
+          end
+        end
+        offset += line.bytesize
+      end
+      closed
+    end
+
+    # Keeps +key+'s place, once its value is known to parse. +text+ is the
+    # value when it's at hand.
+    def indexed(key, start, length, plain, text = nil)
+      JSON.parse(text || @file.pread(length, start)) unless plain
+      @keys << key
+      @places << place(start, length)
+      true
+    rescue JSON::ParserError
+      false
+    end
   end
 end

data/lib/judgelint/cli.rb

@@ -160,7 +160,8 @@ module Judgelint
       else
         paths = Glob.files(rules.flat_map(&:paths))
       end
-      paths.select { |path| rules.any? { |rule| !rule.directory? && rule.applies_to?(path) } }.reject { |path| Glob.binary?(path) }
+      buffer = String.new(capacity: 8000)
+      paths.select { |path| rules.any? { |rule| !rule.directory? && rule.applies_to?(path) } }.reject { |path| Glob.binary?(path, buffer) }
     end
 
     # The directories directory rules govern; with paths named, those the

data/lib/judgelint/client.rb

@@ -24,6 +24,9 @@ module Judgelint
       end
       @usage = usage
       @sleeper = sleeper
+      @question_tokens = {}
+      @connections = Queue.new # open, and not in use
+      @lock = Mutex.new
       check_settings
     end
 
@@ -44,9 +47,10 @@ module Judgelint
       JSON.generate(payload(state, questions)).bytesize / 3
     end
 
-    # What one more question adds to a request, without serializing the file again.
+    # What one more question adds to a request, without serializing the file
+    # again. Files share their questions, so each is measured once.
     def question_tokens(question)
-      (JSON.generate(@protocol.render(question)).bytesize + question.key.bytesize + 6) / 3
+      @question_tokens[question] ||= (JSON.generate(@protocol.render(question)).bytesize + question.key.bytesize + 6) / 3
     end
 
     def url
@@ -133,21 +137,30 @@ module Judgelint
       end
     end
 
-    # Answers nil after a connection error that's worth another try.
+    # Answers nil after a connection error that's worth another try. The
+    # HTTP stack loads with the first request, so a run the cache answers
+    # never loads it, and TLS only for an https endpoint. A connection is
+    # kept for the next request, from any thread, unless the request on it
+    # fails.
     def request(body, attempt)
-      uri = URI(url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      http.open_timeout = Endpoint::TIMEOUT
-      http.read_timeout = Endpoint::TIMEOUT
-
+      require "net/http"
+      uri = @lock.synchronize { @uri ||= URI(url) }
+      require "openssl" if uri.scheme == "https"
       request = Net::HTTP::Post.new(uri.request_uri)
       request["Content-Type"] = "application/json"
       request["Accept"] = "application/json"
       authorize(request)
       @endpoint.headers.each { |name, value| request[name.to_s] = Config.expand(value.to_s) }
       request.body = body
-      http.request(request)
+      http = connection(uri)
+      begin
+        response = http.request(request)
+      rescue StandardError
+        http.finish if http.started?
+        raise
+      end
+      @connections << http
+      response
     rescue Judgelint::Error
       raise
     rescue StandardError => e
@@ -160,6 +173,17 @@ module Judgelint
       nil
     end
 
+    # One kept from an earlier request, or a new one.
+    def connection(uri)
+      @connections.pop(true)
+    rescue ThreadError
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = Endpoint::TIMEOUT
+      http.read_timeout = Endpoint::TIMEOUT
+      http.start
+    end
+
     def authorize(request)
       key = @endpoint.api_key
       return if key.to_s.empty?

data/lib/judgelint/glob.rb

@@ -13,8 +13,9 @@ module Judgelint
       end
     end
 
+    # Rules from one spec share their patterns, so each is globbed once.
     def self.expand(patterns)
-      patterns.flat_map { |pattern| glob(pattern) }.select { |path| File.file?(path) }.uniq.sort
+      patterns.uniq.flat_map { |pattern| glob(pattern) }.select { |path| File.file?(path) }.uniq.sort
     end
 
     # Dir.glob, except that a symlink to itself is skipped. Dir.glob raises
@@ -44,6 +45,7 @@ module Judgelint
       listed = project_files
       return expand(patterns) if listed.nil?
 
+      patterns = patterns.uniq
       listed.select { |path| match_any?(patterns, path) && File.file?(path) }
     end
 
@@ -55,9 +57,10 @@ module Judgelint
       nil
     end
 
-    # A NUL byte in the first 8 KB, as git decides.
-    def self.binary?(path)
-      File.open(path, "rb") { |file| file.read(8000).to_s.include?("\0") }
+    # A NUL byte in the first 8 KB, as git decides. Every file is checked, so
+    # a caller can pass a +buffer+ to read into each time.
+    def self.binary?(path, buffer = +"")
+      File.open(path, "rb") { |file| file.read(8000, buffer).to_s.include?("\0") }
     end
 
     # Files named on the command line, with directories expanded.

data/lib/judgelint/pool.rb

@@ -3,9 +3,12 @@
 module Judgelint
   # Maps items over a few threads and returns results in the items' order, so
   # output doesn't depend on which request came back first. The first error
-  # is raised once every thread has finished.
+  # is raised once every thread has finished. A single item runs on the
+  # calling thread.
   module Pool
     def self.map(items, size)
+      return items.map { |item| yield(item) } if items.size <= 1
+
       results = Array.new(items.size)
       queue = Queue.new
       items.each_with_index { |item, index| queue << [item, index] }

data/lib/judgelint/question.rb

@@ -14,6 +14,9 @@ module Judgelint
   #
   # A rule written as a question is asked yes or no, as written. Code with a
   # judgehint comment is also asked, yes or no, whether the hint excuses it.
+  #
+  # Files share their questions, so a question works out its wording and
+  # options once, while the run is planned, and keeps them.
   class Question
     BREAKS = "The code clearly breaks the rule."
     FOLLOWS = "The code follows the rule."
@@ -37,7 +40,7 @@ module Judgelint
     end
 
     def places
-      @places || (first..last).map { |line| "L#{line}" }
+      @places ||= (first..last).map { |line| "L#{line}" }
     end
 
     def excuse?
@@ -54,18 +57,22 @@ module Judgelint
     end
 
     def key
-      base = "#{rule.question_key}.#{first}-#{last}"
-      return "#{base}.excused" if excuse?
-      return "#{base}.where" if where?
-
-      base
+      @key ||= begin
+        base = "#{rule.question_key}.#{first}-#{last}"
+        if excuse? then "#{base}.excused"
+        elsif where? then "#{base}.where"
+        else base
+        end
+      end
     end
 
     # A choice's options, as {name => description or nil}.
     def options
-      return places.to_h { |place| [place, nil] } if where?
-
-      { "breaks" => rule.yes_means || BREAKS, "follows" => rule.no_means || FOLLOWS, "not_applicable" => NOT_APPLICABLE }
+      @options ||= if where?
+                     places.to_h { |place| [place, nil] }
+                   else
+                     { "breaks" => rule.yes_means || BREAKS, "follows" => rule.no_means || FOLLOWS, "not_applicable" => NOT_APPLICABLE }
+                   end
     end
 
     # The probability the code breaks the rule, from a verdict's answer: a
@@ -79,16 +86,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 where_instructions if where?
-      return "How #{rule.scope == 'file' || lines&.size == 1 ? 'does' : 'do'} #{subject} relate to the following team rule? Rule: #{rule.convention}" if rule.convention
-
-      text = rule.window? ? "Look at #{span} of the file; the rest is context. #{rule.question}" : rule.question
-      return text unless rule.fail_when == "yes"
-
-      scope = { "window" => "those lines do it", "file" => "the code does it", "directory" => "the files do it" }
-              .fetch(rule.scope)
-      "#{text} Answer yes only when #{scope}, not when the question doesn't apply."
+      @instructions ||= instructions_text
     end
 
     def yes_means
@@ -112,6 +110,19 @@ module Judgelint
 
     private
 
+    def instructions_text
+      return excuse_instructions if excuse?
+      return where_instructions if where?
+      return "How #{rule.scope == 'file' || lines&.size == 1 ? 'does' : 'do'} #{subject} relate to the following team rule? Rule: #{rule.convention}" if rule.convention
+
+      text = rule.window? ? "Look at #{span} of the file; the rest is context. #{rule.question}" : rule.question
+      return text unless rule.fail_when == "yes"
+
+      scope = { "window" => "those lines do it", "file" => "the code does it", "directory" => "the files do it" }
+              .fetch(rule.scope)
+      "#{text} Answer yes only when #{scope}, not when the question doesn't apply."
+    end
+
     def subject
       { "window" => "#{span} of the file", "file" => "the file", "directory" => "the files" }.fetch(rule.scope)
     end

data/lib/judgelint/reporter.rb

@@ -19,7 +19,7 @@ module Judgelint
 
     def check(verdicts, config:, file_count:, usage:)
       case @format
-      when "json" then json(check_json(verdicts, config, file_count, usage))
+      when "json" then json_with(check_json(verdicts, config, file_count, usage), "results", verdicts, &:to_h)
       when "github" then verdicts.each { |verdict| annotate(verdict) }
       when "sarif" then json(sarif(verdicts))
       else text(verdicts, file_count)
@@ -27,7 +27,7 @@ module Judgelint
     end
 
     def fixtures(examples, usage:)
-      return json(fixtures_json(examples, usage)) if @format == "json"
+      return json_with(fixtures_json(examples, usage), "examples", examples, &:to_h) if @format == "json"
 
       examples.group_by(&:rule).each do |rule, group|
         correct = group.count(&:correct?)
@@ -51,6 +51,39 @@ module Judgelint
       @out.puts JSON.pretty_generate(data)
     end
 
+    # Prints +data+ with +key+ last, holding +items+ made into hashes, as
+    # JSON.pretty_generate does, but a value at a time: a run's results can
+    # be many. An item's values are scalars, or lists of them.
+    def json_with(data, key, items)
+      head = JSON.pretty_generate(data.merge(key => []))
+      return @out.puts(head) if items.empty?
+
+      @out.write("#{head.delete_suffix("[]\n}")}[")
+      items.each_with_index do |item, index|
+        @out.write(index.zero? ? "\n    {" : ",\n    {")
+        position = 0
+        yield(item).each do |name, value|
+          @out.write(position.zero? ? "\n      " : ",\n      ")
+          @out.write(JSON.generate(name))
+          @out.write(": ")
+          json_value(value)
+          position += 1
+        end
+        @out.write("\n    }")
+      end
+      @out.write("\n  ]\n}\n")
+    end
+
+    def json_value(value)
+      return @out.write(JSON.generate(value)) unless value.is_a?(Array) && !value.empty?
+
+      value.each_with_index do |element, position|
+        @out.write(position.zero? ? "[\n        " : ",\n        ")
+        @out.write(JSON.generate(element))
+      end
+      @out.write("\n      ]")
+    end
+
     def text(verdicts, file_count)
       shown = verdicts.reject { |verdict| verdict.status == :pass }
       width = shown.map { |verdict| verdict.rule.id.size }.max
@@ -120,8 +153,7 @@ module Judgelint
         "models" => config.models.map(&:label),
         "files" => file_count,
         "summary" => STATUSES.to_h { |status| [status, counts.fetch(status.to_sym, 0)] },
-        "usage" => usage.to_h,
-        "results" => verdicts.map(&:to_h)
+        "usage" => usage.to_h
       }
     end
 
@@ -130,8 +162,7 @@ module Judgelint
         "version" => VERSION,
         "correct" => examples.count(&:correct?),
         "total" => examples.size,
-        "usage" => usage.to_h,
-        "examples" => examples.map(&:to_h)
+        "usage" => usage.to_h
       }
     end
 

data/lib/judgelint/rule.rb

@@ -72,7 +72,7 @@ module Judgelint
     end
 
     def question_key
-      id.gsub(/[^A-Za-z0-9_]/, "_")
+      @question_key ||= id.gsub(/[^A-Za-z0-9_]/, "_")
     end
 
     def window?

data/lib/judgelint/runner.rb

@@ -12,29 +12,78 @@ module Judgelint
   # average. A rule's verdict is its worst window.
   class Runner
     # One file's work: the questions to ask, each model's answers (from the
-    # cache or the model), and the requests still to send.
+    # cache or the model), and the requests still to send. A job the cache
+    # answers in full is settled as soon as it's planned, and any other once
+    # it's sent.
     class Job
-      attr_reader :source, :state_digest, :questions, :answers, :requests, :expected
+      attr_reader :source, :state_digest, :questions, :requests, :expected, :verdicts
       attr_accessor :skipped
 
       # The state is the whole file, and a run plans every file before it
-      # sends one, so it's built when needed rather than kept. Its hash, which
+      # sends one, so it's kept only while the job is planned. Its hash, which
       # every question's cache key needs, is kept.
       def initialize(source, questions, prose: nil, expected: nil)
         @source = source
         @prose = prose
-        @state_digest = Digest::SHA256.hexdigest(JSON.generate(state))
+        @planning = read_state
+        @state_digest = Digest::SHA256.hexdigest(JSON.generate(@planning))
         @questions = questions
-        @answers = {} # model index => {question key => probability or nil}
+        @answers = nil # model index => {question key => probability or nil}, once there are any
         @requests = []
         @expected = expected
         @skipped = false
+        @verdicts = nil
       end
 
-      # Rules from a spec read its prose alongside the file, as team_rules.
+      # The state to measure or send, which must be the one planned. While
+      # the job is planned it's the state that was hashed; after that the
+      # file is read again, and one that changed since would be cached under
+      # the wrong contents.
       def state
+        return @planning if @planning
+
+        state = read_state
+        return state if Digest::SHA256.hexdigest(JSON.generate(state)) == @state_digest
+
+        raise changed
+      rescue SystemCallError
+        raise changed
+      end
+
+      # Planning is done: the state is read again when it's sent.
+      def planned
+        @planning = nil
+      end
+
+      # A model's answers, or nil for none.
+      def answers(model)
+        @answers && @answers[model]
+      end
+
+      def answer(model, key, probability)
+        @answers ||= {}
+        (@answers[model] ||= {})[key] = probability
+      end
+
+      # Keeps the verdicts and lets go of what made them.
+      def settle(verdicts)
+        @verdicts = verdicts
+        @answers = nil
+        @source = nil
+        @state_digest = nil
+        verdicts
+      end
+
+      private
+
+      # Rules from a spec read its prose alongside the file, as team_rules.
+      def read_state
         @prose ? { "team_rules" => @prose, "file" => @source.state } : @source.state
       end
+
+      def changed
+        Error.new("#{@source.path} changed while judgelint ran; run it again")
+      end
     end
 
     # Questions sent together to one model, and their estimated input tokens.
@@ -73,6 +122,8 @@ module Judgelint
       @rules = rules
       @clients = clients
       @cache = cache
+      @asked = {} # rule => {shape => questions}
+      @asked_together = {} # the rules' shapes => questions by rule
     end
 
     # +changes+ ({path => lines or :all}, from Changes.since) limits each file
@@ -161,12 +212,12 @@ module Judgelint
       requests.each_with_index.sum { |request, index| request.tokens * prices[index] / 1_000_000.0 }
     end
 
-    # Returns each job's verdicts, in the jobs' order.
+    # Returns each job's verdicts, in the jobs' order. Jobs the cache
+    # settled while planning have them already.
     def execute(jobs)
-      Pool.map(jobs, Config::THREADS) do |job|
-        ask(job)
-        verdicts(job)
-      end
+      @cache.reserve(jobs.sum { |job| job.requests.sum { |request| request.questions.size } })
+      Pool.map(jobs.reject(&:verdicts), Config::THREADS) { |job| judge(job) }
+      jobs.map(&:verdicts)
     ensure
       @cache.save
     end
@@ -183,23 +234,48 @@ module Judgelint
 
     def plan_file(source, rules, lines, expected: nil)
       questions = {}
+      shapes = []
+      shared = true
       rules.each do |rule|
         ranges = rule.ranges(source, Config::WINDOW_LINES).select { |first, last| touched?(lines, first, last) }
         next if ranges.empty?
 
-        asked = []
-        ranges.each do |first, last|
-          asked << Question.new(rule, first, last, lines: changed_lines(rule, lines, first, last))
-          asked << where(source, rule, first, last) if where?(source, rule, first, last)
-          asked << Question.new(rule, first, last, kind: :excuse) if source.hinted?(first, last)
+        if rule.directory?
+          questions[rule] = ask_about(source, rule, ranges, lines)
+          shared = false
+        else
+          shape = shape(source, rule, ranges, lines)
+          shapes << "#{@rules.index(rule)}:#{shape}"
+          questions[rule] = (@asked[rule] ||= {})[shape] ||= ask_about(source, rule, ranges, lines)
         end
-        questions[rule] = asked
       end
+      questions = @asked_together[shapes.join("|")] ||= questions if shared
       job = Job.new(source, questions, prose: rules.first&.prose, expected: expected)
       pack(job)
+      job.planned
+      job.settle(verdicts(job)) if job.requests.empty?
       job
     end
 
+    # What decides a rule's questions about a file: its ranges, changed lines
+    # and judgehints. Files that match share their questions, since a run
+    # holds every file it plans. A directory's are its own.
+    def shape(source, rule, ranges, lines)
+      ranges.map do |first, last|
+        "#{first}-#{last}:#{changed_lines(rule, lines, first, last)&.join(',')}:#{source.hinted?(first, last)}"
+      end.join(";")
+    end
+
+    def ask_about(source, rule, ranges, lines)
+      asked = []
+      ranges.each do |first, last|
+        asked << Question.new(rule, first, last, lines: changed_lines(rule, lines, first, last))
+        asked << where(source, rule, first, last) if where?(source, rule, first, last)
+        asked << Question.new(rule, first, last, kind: :excuse) if source.hinted?(first, last)
+      end
+      asked
+    end
+
     # Where a bullet is broken is asked over the range's lines or the
     # directory's files, but not for a rule written as a question, or past
     # what a choice can hold.
@@ -235,12 +311,11 @@ module Judgelint
     # over a model's limit is skipped: it's reported, never sent.
     def pack(job)
       @clients.each_with_index do |client, model|
-        answers = job.answers[model] = {}
         pending = []
         job.questions.each_value do |questions|
           questions.each do |question|
             cached = @cache.fetch(cache_key(question, job, client))
-            cached.nil? ? pending << question : answers[question.key] = cached
+            cached.nil? ? pending << question : job.answer(model, question.key, cached)
           end
         end
         next if pending.empty?
@@ -269,6 +344,11 @@ module Judgelint
       end
     end
 
+    def judge(job)
+      ask(job)
+      job.settle(verdicts(job))
+    end
+
     # Sends every request at once: a file's packed requests and every model's.
     def ask(job)
       return if job.requests.empty?
@@ -282,7 +362,7 @@ module Judgelint
         request.questions.each do |question|
           probability = results[index][question.key]
           @cache.store(cache_key(question, job, client), probability) unless probability.nil?
-          job.answers[request.model][question.key] = probability
+          job.answer(request.model, question.key, probability)
         end
       end
     end
@@ -310,8 +390,9 @@ module Judgelint
         excuses = []
         spread = {}
         asked.each do |question|
-          job.answers.each_value do |answers|
-            answer = answers[question.key]
+          @clients.each_index do |model|
+            answers = job.answers(model)
+            answer = answers && answers[question.key]
             next if answer.nil?
 
             if question.excuse?

data/lib/judgelint/source.rb

@@ -18,35 +18,46 @@ module Judgelint
       new(dir, shown_as: shown_as, files: files, context: context, directory: true)
     end
 
-    # +text+ is the file's contents when it isn't on disk, like an example in a spec.
-    # Each file is kept as one string, since a run holds every file it plans.
+    # +text+ is the file's contents when it isn't on disk, like an example in a
+    # spec. A file on disk is read once to plan it, and its first state is
+    # built from that read, so the two agree. After that it's read again
+    # rather than kept, since a run holds every file it plans.
     def initialize(path, shown_as: path, files: [path], context: [], directory: false, text: nil)
       @path = path
       @shown_as = shown_as
       @directory = directory
-      @files = text ? [[path, text]] : files.map { |file| [file, File.read(file)] }
+      @files = directory ? files : nil
+      @text = text
       @context = context
       @line_count = 0
-      @hints = []
-      @files.each do |_file, contents|
+      @hints = nil
+      @read = self.files.map { |file| contents(file) }
+      @read.each do |contents|
         contents.each_line do |line|
           @line_count += 1
-          @hints << @line_count if HINT.match?(line)
+          (@hints ||= []) << @line_count if HINT.match?(line)
         end
       end
     end
 
+    # A file's source is the file alone.
+    def files
+      @files || [@path]
+    end
+
     def directory?
       @directory
     end
 
     def state
+      read = @read || files.map { |file| contents(file) }
+      @read = nil
       body =
         if directory?
-          sections = @files.map { |file, contents| "Path: #{shown(file)}\n\n#{numbered(contents)}" }
+          sections = files.each_with_index.map { |file, index| "Path: #{shown(file)}\n\n#{numbered(read[index])}" }
           "Directory: #{shown_as}\n\n#{sections.join("\n")}"
         else
-          "Path: #{shown_as}\n\n#{numbered(@files.first[1])}"
+          "Path: #{shown_as}\n\n#{numbered(read[0])}"
         end
       return body if @context.empty?
 
@@ -61,17 +72,29 @@ module Judgelint
 
     # The directory's files as [path, the path the model sees].
     def members
-      @files.map { |file, _contents| [file, shown(file)] }
+      files.map { |file| [file, shown(file)] }
     end
 
     def hinted?(first, last)
-      directory? ? !@hints.empty? : @hints.any? { |line| line.between?(first, last) }
+      return false if @hints.nil?
+
+      directory? || @hints.any? { |line| line.between?(first, last) }
     end
 
     private
 
+    def contents(file)
+      @text || File.read(file)
+    end
+
     def numbered(contents)
-      contents.lines.each_with_index.map { |line, index| "#{index + 1}: #{line.chomp}\n" }.join
+      text = +""
+      number = 0
+      contents.each_line do |line|
+        number += 1
+        text << number.to_s << ": " << line.chomp << "\n"
+      end
+      text
     end
 
     # A file's path inside the directory, as the model sees it.

data/lib/judgelint/verdict.rb

@@ -15,19 +15,25 @@ module Judgelint
   # is :pass or :fail for files under rules/<id>/pass and rules/<id>/fail.
   # Not Data.define: Spinel can't compile a Data or Struct in a program that also uses net/https and json.
   class Verdict
-    attr_reader :rule, :path, :probability, :status, :lines, :line, :file, :expected
+    attr_reader :rule, :path, :probability, :status, :line, :file, :expected
 
+    # A run holds a verdict for every rule and file, so the range is kept as
+    # one number: its first line, shifted past its last.
     def initialize(rule:, path:, probability:, status:, lines: nil, line: nil, file: nil, expected: nil)
       @rule = rule
       @path = path
       @probability = probability
       @status = status
-      @lines = lines
+      @range = lines && ((lines[0] << 32) | lines[1])
       @line = line
       @file = file
       @expected = expected
     end
 
+    def lines
+      @range && [@range >> 32, @range & 0xffffffff]
+    end
+
     def as_example(expected)
       Verdict.new(rule: rule, path: path, probability: probability, status: status, lines: lines, line: line, file: file,
                   expected: expected)

data/lib/judgelint/version.rb

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

data/lib/judgelint.rb

@@ -4,7 +4,6 @@ require "json"
 require "yaml"
 require "digest"
 require "fileutils"
-require "net/https"
 require "open3"
 
 require_relative "judgelint/version"

metadata

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