wordl-solver 1.4.0 → 2.0.0

data/lib/data/opening_scores.json

@@ -0,0 +1,252 @@
+[
+  {
+    "word": "soare",
+    "score": 5.88596,
+    "is_possible_answer": false
+  },
+  {
+    "word": "roate",
+    "score": 5.882779,
+    "is_possible_answer": false
+  },
+  {
+    "word": "raise",
+    "score": 5.87791,
+    "is_possible_answer": true
+  },
+  {
+    "word": "raile",
+    "score": 5.86571,
+    "is_possible_answer": false
+  },
+  {
+    "word": "reast",
+    "score": 5.865457,
+    "is_possible_answer": false
+  },
+  {
+    "word": "slate",
+    "score": 5.855775,
+    "is_possible_answer": true
+  },
+  {
+    "word": "crate",
+    "score": 5.834874,
+    "is_possible_answer": true
+  },
+  {
+    "word": "salet",
+    "score": 5.834582,
+    "is_possible_answer": false
+  },
+  {
+    "word": "irate",
+    "score": 5.831397,
+    "is_possible_answer": true
+  },
+  {
+    "word": "trace",
+    "score": 5.830549,
+    "is_possible_answer": true
+  },
+  {
+    "word": "arise",
+    "score": 5.82094,
+    "is_possible_answer": true
+  },
+  {
+    "word": "orate",
+    "score": 5.817161,
+    "is_possible_answer": false
+  },
+  {
+    "word": "stare",
+    "score": 5.80728,
+    "is_possible_answer": true
+  },
+  {
+    "word": "carte",
+    "score": 5.794557,
+    "is_possible_answer": false
+  },
+  {
+    "word": "raine",
+    "score": 5.78671,
+    "is_possible_answer": false
+  },
+  {
+    "word": "caret",
+    "score": 5.776713,
+    "is_possible_answer": false
+  },
+  {
+    "word": "ariel",
+    "score": 5.775167,
+    "is_possible_answer": false
+  },
+  {
+    "word": "taler",
+    "score": 5.770612,
+    "is_possible_answer": false
+  },
+  {
+    "word": "carle",
+    "score": 5.770479,
+    "is_possible_answer": false
+  },
+  {
+    "word": "slane",
+    "score": 5.770181,
+    "is_possible_answer": false
+  },
+  {
+    "word": "snare",
+    "score": 5.770089,
+    "is_possible_answer": true
+  },
+  {
+    "word": "artel",
+    "score": 5.768295,
+    "is_possible_answer": false
+  },
+  {
+    "word": "arose",
+    "score": 5.767797,
+    "is_possible_answer": true
+  },
+  {
+    "word": "strae",
+    "score": 5.767281,
+    "is_possible_answer": false
+  },
+  {
+    "word": "carse",
+    "score": 5.765364,
+    "is_possible_answer": false
+  },
+  {
+    "word": "saine",
+    "score": 5.764078,
+    "is_possible_answer": false
+  },
+  {
+    "word": "earst",
+    "score": 5.757081,
+    "is_possible_answer": false
+  },
+  {
+    "word": "taser",
+    "score": 5.752976,
+    "is_possible_answer": false
+  },
+  {
+    "word": "least",
+    "score": 5.751646,
+    "is_possible_answer": true
+  },
+  {
+    "word": "alert",
+    "score": 5.745837,
+    "is_possible_answer": true
+  },
+  {
+    "word": "crane",
+    "score": 5.742782,
+    "is_possible_answer": true
+  },
+  {
+    "word": "tares",
+    "score": 5.742548,
+    "is_possible_answer": false
+  },
+  {
+    "word": "seral",
+    "score": 5.739455,
+    "is_possible_answer": false
+  },
+  {
+    "word": "stale",
+    "score": 5.738573,
+    "is_possible_answer": true
+  },
+  {
+    "word": "saner",
+    "score": 5.733713,
+    "is_possible_answer": true
+  },
+  {
+    "word": "ratel",
+    "score": 5.73087,
+    "is_possible_answer": false
+  },
+  {
+    "word": "torse",
+    "score": 5.72338,
+    "is_possible_answer": false
+  },
+  {
+    "word": "tears",
+    "score": 5.718023,
+    "is_possible_answer": false
+  },
+  {
+    "word": "resat",
+    "score": 5.716071,
+    "is_possible_answer": false
+  },
+  {
+    "word": "alter",
+    "score": 5.713171,
+    "is_possible_answer": true
+  },
+  {
+    "word": "later",
+    "score": 5.706089,
+    "is_possible_answer": true
+  },
+  {
+    "word": "prate",
+    "score": 5.700636,
+    "is_possible_answer": false
+  },
+  {
+    "word": "trine",
+    "score": 5.697082,
+    "is_possible_answer": false
+  },
+  {
+    "word": "react",
+    "score": 5.696354,
+    "is_possible_answer": true
+  },
+  {
+    "word": "saice",
+    "score": 5.691244,
+    "is_possible_answer": false
+  },
+  {
+    "word": "toile",
+    "score": 5.691014,
+    "is_possible_answer": false
+  },
+  {
+    "word": "earnt",
+    "score": 5.690444,
+    "is_possible_answer": false
+  },
+  {
+    "word": "trone",
+    "score": 5.684949,
+    "is_possible_answer": false
+  },
+  {
+    "word": "leant",
+    "score": 5.684574,
+    "is_possible_answer": true
+  },
+  {
+    "word": "liane",
+    "score": 5.68423,
+    "is_possible_answer": false
+  }
+]

data/lib/wordl_solver/cli.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../wordl_solver"
+require_relative "feedback"
+require_relative "game_state"
+require_relative "filter"
+require_relative "scorer"
+require_relative "word_lists"
+
+module WordlSolver
+  class CLI
+    DEFAULT_TOP = 10
+    OPENING_SCORES_PATH = File.expand_path("../data/opening_scores.json", __dir__)
+
+    def self.run(argv = ARGV, input: $stdin, output: $stdout, error: $stderr)
+      top = parse_top(argv) || DEFAULT_TOP
+      new(input: input, output: output, error: error, top: top).run
+    end
+
+    def self.parse_top(argv)
+      idx = argv.index("--top")
+      return nil unless idx
+
+      value = argv[idx + 1]
+      raise ArgumentError, "--top requires a positive integer argument" if value.nil?
+
+      parsed = Integer(value)
+      raise ArgumentError, "--top must be a positive integer, got #{value.inspect}" unless parsed.positive?
+
+      parsed
+    end
+
+    def initialize(input:, output:, error:, top: DEFAULT_TOP)
+      @in = input
+      @out = output
+      @err = error
+      @top = top
+      @state = GameState.new
+    end
+
+    def run
+      print_banner
+      loop do
+        candidates = current_candidates
+        print_turn_header(candidates)
+        print_suggestions(candidates)
+        return if @state.solved?
+
+        line = read_line
+        return if line.nil?
+
+        case line
+        when ":quit", ":q"
+          return
+        when ":help", ":h", ":?"
+          print_help
+        when ":undo", ":u"
+          handle_undo
+        when ":restart", ":r"
+          @state = GameState.new
+        else
+          handle_guess(line)
+        end
+      end
+    end
+
+    private
+
+    def print_banner
+      @out.puts "wordl-solver #{WordlSolver::VERSION}"
+      @out.puts "Type: <word> <pattern>  (pattern is 5 chars from g/y/s)"
+      @out.puts "Commands: :undo  :restart  :quit  :help"
+      @out.puts
+    end
+
+    def print_help
+      @out.puts
+      @out.puts "  <word> <pattern>   submit a guess, e.g.  crane sygss"
+      @out.puts "  pattern chars:     g=green, y=yellow, s=grey (b and . also accepted for grey)"
+      @out.puts "  :undo              remove the last turn"
+      @out.puts "  :restart           start over"
+      @out.puts "  :quit              exit"
+      @out.puts "  :help              this message"
+      @out.puts
+    end
+
+    def print_turn_header(candidates)
+      turn_num = @state.turns.size + 1
+      @out.puts "Turn #{turn_num} — #{candidates.size} possible answer#{'s' unless candidates.size == 1}."
+    end
+
+    def print_suggestions(candidates)
+      if @state.solved?
+        @out.puts "  Solved! 🎉"
+        return
+      end
+
+      if candidates.empty?
+        @out.puts "  No candidates remain. Did a guess get an incorrect pattern? Try :undo."
+        return
+      end
+
+      ranked = if @state.empty?
+                 opening_scores
+               else
+                 Scorer.rank(candidates: candidates, guess_pool: WordLists::ALLOWED_GUESSES)
+               end
+
+      shown = ranked.first(@top)
+      possible = shown.select(&:is_possible_answer)
+      others = shown - possible
+
+      show_bits = candidates.size > 2
+      formatter = ->(sw) { show_bits ? format("    %-6s %.2f bits", sw.word, sw.score) : "    #{sw.word}" }
+
+      if possible.any?
+        @out.puts "  Possible answers:"
+        possible.each { |sw| @out.puts formatter.call(sw) }
+      end
+      if others.any?
+        @out.puts "  High-info guesses:"
+        others.each { |sw| @out.puts "#{formatter.call(sw)}  (not a possible answer)" }
+      end
+      @out.puts
+    end
+
+    def current_candidates
+      Filter.candidates(WordLists::ANSWERS, @state)
+    end
+
+    def opening_scores
+      @opening_scores ||= JSON.parse(File.read(OPENING_SCORES_PATH)).map do |row|
+        Scorer::ScoredWord.new(row["word"], row["score"], row["is_possible_answer"])
+      end
+    end
+
+    def read_line
+      @out.print "> "
+      @out.flush
+      line = @in.gets
+      return nil if line.nil?
+
+      line.strip
+    end
+
+    def handle_undo
+      if @state.empty?
+        @out.puts "  Nothing to undo."
+      else
+        @state = @state.undo
+      end
+    end
+
+    def handle_guess(line)
+      parts = line.split(/\s+/, 2)
+      if parts.size != 2
+        @out.puts "  Expected: <word> <pattern>. Try again or :help."
+        return
+      end
+
+      word, pattern = parts
+      word = word.downcase
+
+      unless Filter.valid_guess?(word)
+        @out.puts "  #{word.inspect} is not a valid 5-letter word."
+        return
+      end
+
+      feedback = begin
+        Feedback.parse(pattern.downcase)
+      rescue ArgumentError => e
+        @out.puts "  Bad pattern: #{e.message}"
+        return
+      end
+
+      @state = @state.apply(guess: word, feedback: feedback)
+    end
+  end
+end

data/lib/wordl_solver/feedback.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module WordlSolver
+  class Feedback
+    VALID_COLORS = %i[green yellow grey].freeze
+    CHAR_TO_COLOR = {
+      "g" => :green,
+      "y" => :yellow,
+      "s" => :grey,
+      "b" => :grey,
+      "." => :grey
+    }.freeze
+    COLOR_TO_CHAR = { green: "g", yellow: "y", grey: "s" }.freeze
+
+    attr_reader :colors
+
+    def self.parse(string)
+      raise ArgumentError, "feedback must be 5 chars, got #{string.inspect}" unless string.length == 5
+
+      colors = string.chars.map do |ch|
+        CHAR_TO_COLOR[ch] || raise(ArgumentError, "invalid feedback char #{ch.inspect}")
+      end
+      new(colors)
+    end
+
+    def initialize(colors)
+      raise ArgumentError, "feedback must be 5 colors" unless colors.length == 5
+
+      colors.each do |c|
+        raise ArgumentError, "invalid color #{c.inspect}" unless VALID_COLORS.include?(c)
+      end
+
+      @colors = colors.freeze
+      freeze
+    end
+
+    def [](index)
+      @colors[index]
+    end
+
+    def all_green?
+      @colors.all? { |c| c == :green }
+    end
+
+    def to_s
+      @colors.map { |c| COLOR_TO_CHAR.fetch(c) }.join
+    end
+
+    def ==(other)
+      other.is_a?(Feedback) && other.colors == @colors
+    end
+    alias eql? ==
+
+    def hash
+      @colors.hash
+    end
+  end
+end

data/lib/wordl_solver/filter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "word_lists"
+
+module WordlSolver
+  module Filter
+    # Pure function. Returns the subset of word_list consistent with every turn
+    # in game_state.
+    def self.candidates(word_list, game_state)
+      return word_list.dup if game_state.empty?
+
+      constraints = game_state.turns.map { |turn| compile_constraints(turn.guess, turn.feedback) }
+
+      word_list.select do |word|
+        constraints.all? { |c| satisfies?(word, c) }
+      end
+    end
+
+    def self.valid_guess?(word)
+      WordLists::ALLOWED_GUESSES_SET.include?(word)
+    end
+
+    # --- internals --------------------------------------------------------
+
+    # Compile one turn into a fast-checkable constraint bundle:
+    #   greens:  Hash{position => required_letter}
+    #   yellows: Hash{position => forbidden_letter_at_this_position}
+    #   counts:  Hash{letter => [min_count, has_grey]}
+    def self.compile_constraints(guess, feedback)
+      greens = {}
+      yellows = {}
+      per_letter = Hash.new { |h, k| h[k] = { min: 0, grey: false } }
+
+      5.times do |i|
+        letter = guess[i]
+        case feedback[i]
+        when :green
+          greens[i] = letter
+          per_letter[letter][:min] += 1
+        when :yellow
+          yellows[i] = letter
+          per_letter[letter][:min] += 1
+        when :grey
+          per_letter[letter][:grey] = true
+        end
+      end
+
+      counts = per_letter.transform_values { |v| [v[:min], v[:grey]] }
+      { greens: greens, yellows: yellows, counts: counts }
+    end
+
+    def self.satisfies?(word, c)
+      c[:greens].each { |i, ch| return false unless word[i] == ch }
+      c[:yellows].each { |i, ch| return false if word[i] == ch }
+      c[:counts].each do |letter, (min, has_grey)|
+        actual = word.count(letter)
+        if has_grey
+          return false unless actual == min
+        else
+          return false unless actual >= min
+        end
+      end
+      true
+    end
+  end
+end

data/lib/wordl_solver/game_state.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "feedback"
+
+module WordlSolver
+  Turn = Struct.new(:guess, :feedback) do
+    def initialize(guess, feedback)
+      super(guess.freeze, feedback)
+      freeze
+    end
+  end
+
+  class GameState
+    attr_reader :turns
+
+    def initialize(turns = [])
+      @turns = turns.freeze
+      freeze
+    end
+
+    def empty?
+      @turns.empty?
+    end
+
+    def solved?
+      !@turns.empty? && @turns.last.feedback.all_green?
+    end
+
+    def apply(guess:, feedback:)
+      GameState.new(@turns + [Turn.new(guess, feedback)])
+    end
+
+    def undo
+      raise ArgumentError, "cannot undo: state is empty" if @turns.empty?
+
+      GameState.new(@turns[0...-1])
+    end
+  end
+end

data/lib/wordl_solver/scorer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "../wordl_solver"
+
+module WordlSolver
+  module Scorer
+    ScoredWord = Struct.new(:word, :score, :is_possible_answer)
+
+    # Returns an Array<ScoredWord> sorted by score descending.
+    # For each guess in the guess pool, computes Shannon entropy of the
+    # distribution of feedback patterns it would produce against `candidates`.
+    def self.rank(candidates:, guess_pool:)
+      return [] if candidates.empty?
+
+      candidate_set = candidates.to_set
+      if candidates.size <= 2
+        return candidates.map { |w| ScoredWord.new(w, 0.0, true) }
+      end
+
+      effective_pool = candidates.size <= 50 ? candidates : guess_pool
+
+      n = candidates.size.to_f
+      effective_pool.map do |guess|
+        counts = Hash.new(0)
+        candidates.each do |secret|
+          counts[WordlSolver.score(guess, secret)] += 1
+        end
+        entropy = counts.each_value.sum(0.0) do |c|
+          p = c / n
+          -p * Math.log2(p)
+        end
+        ScoredWord.new(guess, entropy, candidate_set.include?(guess))
+      end.sort_by { |sw| -sw.score }
+    end
+  end
+end

data/lib/wordl_solver/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WordlSolver
+  VERSION = "2.0.0"
+end

data/lib/wordl_solver/word_lists.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "set"
+
+module WordlSolver
+  module WordLists
+    DATA_DIR = File.expand_path("../data", __dir__)
+
+    ANSWERS = File.readlines(File.join(DATA_DIR, "answers.txt"), chomp: true).each(&:freeze).freeze
+    ALLOWED_GUESSES = File.readlines(File.join(DATA_DIR, "allowed_guesses.txt"), chomp: true).each(&:freeze).freeze
+    ALLOWED_GUESSES_SET = Set.new(ALLOWED_GUESSES).freeze
+  end
+end