wordl-solver 1.4.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4a62f4eeebb61e2c99c23028737e472001a3f09380397d4b30e0d1564a2784f
-  data.tar.gz: 3d7ffec7b36cbd41937eae53a7a104a35e116357fae62726640549412cbcdf96
+  metadata.gz: 971e04860d52665cda7d60ed70620e482ab3e430257054d11bdc807308c12baa
+  data.tar.gz: 32a747b54c9765f467ee9577314baab53be899ffa1a0e395537ff933ed12d8b7
 SHA512:
-  metadata.gz: a02c49ebcaaefb0d97cb40ffec08f34d8875a70e624325570198024770a72b4ca0de8806ac1dfe26a4c3c19f3d4fb32e3177e46f281b1e59acbc8f1f19031388
-  data.tar.gz: 32c6b2fa2b25b50a25bc0f61c63d2b92c7dab9760d3334d65dd5cbc9a89fb940309260654338eaea9aad2e0562c55abdbb297915a744d7f222ffa2e247118ecc
+  metadata.gz: d79b870a00216e6e4ca66d2fefba913128e5374433e634c72e48265fcb011fd51aad985e3bfddee2691ff99cae1c078d5d8095667910f24c56350dd02784592a
+  data.tar.gz: 3d7c8713c93d569ae85dc378488a8b9594c5583e214ed08943f7218b9e7b7e9b4a4c66586c266ba5d8d76ceb12a6cc3e453f086f8b198ea709b5169bf1331e78

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 2.0.0 — 2026-05-12
+
+### Breaking changes
+
+- **CLI input format** changed from per-position prompts to a single line per turn (`<word> <pattern>`). The old `sa`/`yr`/`so`-style prompting is gone.
+- **Ruby API reshaped.** `WordlSolver.find_possible_words` is removed. The new API: `WordlSolver.score`, `WordlSolver::Filter.candidates`, `WordlSolver::Scorer.rank`, `WordlSolver::GameState`, `WordlSolver::Feedback`.
+- **Word lists replaced** with the real Wordle answer (~2,315) and allowed-guess (~12,972) lists. The old `5_words.csv` is gone.
+- **Ranking switched** from sum-of-letter-frequencies (and an ascending sort bug) to expected information gain (Shannon entropy).
+- **Minimum Ruby** is now 3.0.
+
+### Fixed
+
+- Duplicate-letter cases now scored correctly. In particular: yellow + grey of the same letter forces an exact count; two yellows of the same letter require ≥ 2 occurrences.
+- Filter no longer carries state between games.
+
+### Added
+
+- `:undo`, `:restart`, `:quit`, `:help` commands.
+- Precomputed top-50 opener entropy data (`lib/data/opening_scores.json`) so the first turn is instant.
+- Property-based filter tests (200 random secrets × random guesses).
+
+### Removed
+
+- `juwelier` and `shoulda` dev dependencies.
+- `README.rdoc` (superseded by `README.md`).
+- Checked-in build artifact (`wordl-solver-1.4.2.gem`).

data/README.md

@@ -0,0 +1,66 @@
+# wordl-solver
+
+A Ruby gem that solves Wordle puzzles by ranking each candidate guess by **expected information gain** — the same technique behind strong public Wordle solvers. Ships with the real Wordle answer and allowed-guess lists and a single-line CLI.
+
+## How it ranks guesses
+
+For each candidate guess, the solver simulates what feedback every still-possible answer would produce and computes the Shannon entropy of that distribution. A high-entropy guess splits the remaining answer set into many small buckets, telling you the most you can learn in one move. Higher score = better guess.
+
+## Install
+
+```bash
+gem install wordl-solver
+```
+
+## Use
+
+```bash
+wordl-solver
+```
+
+You enter one line per turn: the word you guessed and the color pattern you got. The pattern is 5 characters from `g` (green), `y` (yellow), `s` (grey). `b` and `.` are also accepted for grey.
+
+```
+> crane sygss
+Turn 2 — 41 possible answers.
+  Possible answers:
+    poilu  3.92 bits
+    plumb  3.71 bits
+  High-info guesses:
+    pluot  4.21 bits  (not a possible answer)
+```
+
+### Commands
+
+- `:undo` — remove the last turn.
+- `:restart` — start over.
+- `:quit` — exit.
+- `:help` — print help.
+
+### Flags
+
+- `--top N` — show the top N suggestions (default 10).
+
+## Going deeper
+
+Two long-form docs explain how the gem works and why it's built the way it is. They're written to be readable on their own, not just as developer notes:
+
+- [docs/ALGORITHM.md](docs/ALGORITHM.md) — the math. Walks through the Wordle scoring rule, the duplicate-letter filter algorithm, and the Shannon-entropy ranking from first principles, with worked examples. Useful if you want to understand *why* this approach works.
+- [docs/DESIGN.md](docs/DESIGN.md) — the software design. Covers value objects, immutability, pure functions, separation of concerns, dependency injection in the CLI, and the test design philosophy. Useful if you want to learn Ruby design patterns from a small worked example.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+To regenerate the precomputed opening scores (only needed if word lists change):
+
+```bash
+bundle exec rake compute_opening_scores
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/bin/wordl-solver

@@ -1,4 +1,12 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'wordl_solver_interface'
-WordlSolverInterface.run
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "wordl_solver/cli"
+
+begin
+  WordlSolver::CLI.run(ARGV)
+rescue ArgumentError => e
+  warn "wordl-solver: #{e.message}"
+  exit 2
+end