wordulator 1.0.0

package/src/lib/entropy.js

@@ -0,0 +1,123 @@
+const buckets = new Uint16Array(243).fill(0);
+/**
+ * @param {number} guess_index
+ * @param {Array<string>} word_list 
+ * @param {UInt8Array} feedback_matrix 
+ * @param {number[]} answer_indecies 
+ * @param {Float64Array} ent_table 
+ * @returns Number
+ */
+function calculateGuessEntropy(guess_index, word_list, feedback_matrix, answer_indecies, ent_table) {
+    buckets.fill(0);
+    const wl = word_list.length;
+    const base = guess_index*wl;
+
+    for (let ai=0; ai < wl; ai++) {
+        const pattern = feedback_matrix[base + answer_indecies[ai]];
+        buckets[pattern] += 1;
+    }
+
+    let entropy = 0;
+    if (ent_table !== undefined) {
+        for (let i = 0; i < 243; i++) {
+            const count = buckets[i];
+            entropy += ent_table[count];
+        }
+    } else {
+        for (let i = 0; i < 243; i++) {
+            const count = buckets[i];
+            if (count === 0) continue;
+            const p = count / wl;
+            entropy -= p * Math.log2(p);
+        }
+    }
+
+    return entropy;
+}
+
+/**
+ * @param {number} pattern 
+ * @returns 
+ */
+function encodePattern(pattern) {
+    let value = 0
+    for (let i = 0; i < 5; i++) {
+        value = value * 3 + (pattern.charCodeAt(i) - 48)
+    }
+    return value
+}
+
+/**
+ * @param {string} guess 
+ * @param {string} answer 
+ * @returns 
+ */
+function entropyFeedback(guess, answer) {
+    let used = 0
+    let result = 0
+
+    // greens
+    for (let i = 0; i < 5; i++) {
+        if (guess[i] === answer[i]) {
+            result += 2 * Math.pow(3, 4 - i)
+            used |= 1 << i
+        }
+    }
+
+    // yellows
+    for (let i = 0; i < 5; i++) {
+        if ((result / Math.pow(3, 4 - i) | 0) % 3 !== 0) continue
+
+        for (let j = 0; j < 5; j++) {
+            if (!(used & (1 << j)) && guess[i] === answer[j]) {
+                result += 1 * Math.pow(3, 4 - i)
+                used |= 1 << j
+                break
+            }
+        }
+    }
+
+    return result
+}
+
+/**
+ * 
+ * @param {number} length 
+ * @returns {Float64Array}
+ */
+function genEntropyTable(length) {
+    const table = new Float64Array(length + 1);
+
+    for (let c = 1; c <= length; c++) {
+        const p = c / length;
+        table[c] = -p * Math.log2(p);
+    }
+
+    return table;
+}
+
+
+const mmap = require('@luminati-io/mmap-io');
+const fs = require('fs');
+
+/**
+ * Lazily maps the feedback matrix file and returns a Uint8Array view
+ */
+function loadFeedbackMatrix(path) {
+    const fd = fs.openSync(path, 'r');
+    const stats = fs.fstatSync(fd);
+
+    const buffer = mmap.map(
+        stats.size,
+        mmap.PROT_READ,
+        mmap.MAP_SHARED,
+        fd,
+        0
+    );
+
+    // Uint8Array view over the memory-mapped file
+    const feedbackMatrix = new Uint8Array(buffer.buffer, buffer.byteOffset, stats.size / 2);
+    return feedbackMatrix;
+}
+
+module.exports = { calculateGuessEntropy, encodePattern, entropyFeedback, genEntropyTable, loadFeedbackMatrix };

package/src/lib/heuristic.js

@@ -0,0 +1,104 @@
+const { normalise } = require('./lib.js')
+
+/**
+ * Calculates the positional frequencies of letters based on a list of words
+ * @param {Array<string>} words 
+ * @returns 
+ */
+function calculatePosFreq(words) {
+    const pf = Array.from({length: 5}, () => new Array(26).fill(0));
+
+    for (let i=0; i < words.length; i++) {
+        const word = words[i];
+        for (let j=0; j < 5; j++) {
+            const char_code = word.charCodeAt(j) - 97;
+            pf[j][char_code] += 1;
+        }
+    }
+
+    for (let i=0; i < 5; i++) {
+        pf[i] = normalise(pf[i]);
+    }
+
+    return pf;
+}
+
+/**
+ * Scores a word based on positional frequencies of letters
+ * @param {string} word 
+ * @param {Array<Array<number>>} pf 
+ * @returns {number}
+*/
+function pfHeuristicScore(word, pf) {
+    let score = 0;
+    const seen = new Array(26);
+    const wl = word.length;
+
+    for (let i=0; i < wl; i++) {
+        let char_code = word.charCodeAt(i) - 97;
+        if (seen[char_code] === 0) {
+            score += pf[i][char_code];
+            seen[char_code] = 1;
+        } else {
+            const s = pf[i][char_code];
+            score += s / 2;
+        }
+    }
+
+    return score;
+}
+
+/**
+ * Scores a word between 1-word.length based on how many unique letters it contains
+ * @param {string} word 
+ * @returns {number}
+*/
+function uniquenessHeuristicScore(word) {
+    let score = 0;
+    const seen = new Set();
+    for (let i=0; i<word.length; i++) {
+        let c = word[i];
+        if (!seen.has(c)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+
+/**
+ * 
+ * @param {string} guess 
+ * @param {Array<boolean>} usedLetters
+ * @return {number}
+ */
+function overlapScore(guess, usedLetters) {
+    let score = 0;
+    for (let l=0; l<guess.length; l++) {
+        const letter_idx = guess.charCodeAt(l) - 97;
+        if (usedLetters[letter_idx] === false) {
+            score++;
+        }
+    }
+
+    return score
+}
+
+/**
+ * 
+ * @param {string} guess 
+ * @param {Array<boolean>} [usedLetters]
+ * @return {string}
+ */
+function createOverlap(guess, usedLetters) {
+    let uL = usedLetters;
+    if (usedLetters === undefined) uL = Array.from({ length: 26 }).fill(false);
+
+    for (let l=0; l<guess.length; l++) {
+        const letter_idx = guess.charCodeAt(l) - 97;
+        uL[letter_idx] = true;
+    }
+
+    return uL
+}
+
+module.exports = { calculatePosFreq, pfHeuristicScore, uniquenessHeuristicScore, overlapScore, createOverlap }

package/src/lib/lib.js

@@ -0,0 +1,65 @@
+const readline = require('node:readline/promises');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+async function ask(q) {
+    let a = await rl.question(q);
+    return a.toLowerCase();
+}
+
+/**
+ * Counts the number of a given character in a word
+ * @param {*} word 
+ * @param {*} char 
+ * @returns 
+ */
+function count(word, character) {
+    let count = 0;
+    for (let letter of word) {
+        if (letter === character) { count++ }
+    }
+
+    return count
+}
+
+/**
+ * Normalises an array of data
+ * @param {number[]} arr 
+ * @returns {number[]}
+ */
+function normalise(arr) {
+    const max = Math.max(...arr);
+    const min = Math.min(...arr);
+    const range = Math.abs(max - min);
+
+    if (range === 0) return arr.map(() => 0);
+    return arr.map(v => { return (v - min) / range })
+}
+
+function patternToIndex(pattern) {
+    let index = 0;
+    let multiplier = 1;
+
+    for (let i = 0; i < 5; i++) {
+        const twoBits = (pattern >> (i * 2)) & 0b11; 
+        index += twoBits * multiplier;
+        multiplier *= 3; 
+    }
+
+    return index;
+}
+
+function randomInt(max) {
+  return Math.floor(Math.random() * max);
+}
+
+function randomUniform(min, max) {
+    return min + Math.random() * (max - min);
+}
+
+
+
+module.exports = { ask, count, normalise, patternToIndex, randomInt, randomUniform }

package/src/lib/wordle.js

@@ -0,0 +1,250 @@
+const GREEN = 2;
+const YELLOW = 1;
+const GREY = 0;
+
+const NOT_FIXED = -1;
+
+const BANNED = 1;
+
+class Wordle {
+    /** 
+     * @param {boolean} known 
+     * @param {string} answer 
+     */
+    constructor(known, answer) {
+        // Conditions
+        /** @type {Int8Array} */
+        this.min_counts = new Int8Array(26);
+        /** @type {Int8Array} */
+        this.max_counts = new Int8Array(26).fill(5);
+        /** 
+         * character codes of fixed positions if known | -1 stored if no letter yet fixed
+         * @type {Int8Array} 
+         */
+        this.fixed_positions = new Int8Array(5).fill(-1); 
+        /** 
+         * 
+         * @type {Int8Array} 
+         */
+        this.banned_positions = new Int8Array(26 * 5); // 0 not banned, 1 banned
+
+        this.known = known;
+
+        // Answer, used for automated feedback
+        if (known) {
+            this.answer = answer;
+            this.answer_letter_counts = new Int8Array(26);
+            for (let i = 0; i < 5; i++) {
+                const char_code = answer.charCodeAt(i) - 97;
+                this.answer_letter_counts[char_code] += 1;
+            }
+        }
+    }
+
+    /**
+     * Provides Feedback in the form a 16bit integer:
+     *          T  A  R  E  S
+     *          2  1  0  0  0
+     * 00_00_00_10_01_00_00_00
+     * @param {string} guess
+     * @param {string} answer
+     * @returns {number}
+     */
+    evaluateGuess(guess) {
+        if (!this.known) MELTDOWN("Can't evaluate guess with unkown answer");
+
+        const guess_counts = new Int8Array(26);
+        let pattern = 0;
+
+        // Greens
+        for (let i = 0; i < 5; i++) {
+            const guess_letter = guess.charCodeAt(i) - 97;
+            const answer_letter = this.answer.charCodeAt(i) - 97;
+            if (guess_letter === answer_letter) {
+                pattern = writePatternPosition(pattern, i, GREEN)
+                guess_counts[guess_letter] += 1;
+            }
+        }
+
+        // Yellows
+        for (let i = 0; i < 5; i++) {
+            const guess_letter = guess.charCodeAt(i) - 97;
+            const answer_letter = this.answer.charCodeAt(i) - 97;
+
+            if (guess_letter === answer_letter) continue;
+            else if (guess_counts[guess_letter] < this.answer_letter_counts[guess_letter]) {
+                pattern = writePatternPosition(pattern, i, YELLOW);
+                guess_counts[guess_letter] += 1;
+            }
+        }
+
+        // Greys are encoded by default. No need to reencode
+
+        return pattern;
+    }
+
+    /**
+     * @param {string} guess
+     * @param {number} pattern
+     */
+    updateConditions(guess, pattern) {
+        const min_counts = new Int8Array(26);
+        const max_counts = new Int8Array(26).fill(5);
+
+        // Set Min Using Green & Yellow Input
+        for (let word_pos = 0; word_pos < 5; word_pos++) {
+            const letter = guess.charCodeAt(word_pos) - 97;
+            const letter_colour = readPatternPosition(pattern, word_pos);
+
+            // Update min counts
+            if (letter_colour === YELLOW || letter_colour === GREEN) {
+                min_counts[letter] += 1;
+            }
+
+            // set fixed and banned positions
+            if (letter_colour === GREEN) {
+                if (this.hasFixedCharacter(word_pos)) {
+                    if (this.fixed_positions[word_pos] !== letter) MELTDOWN("Can't fix 2 letters in 1 position");
+                } else {
+                    this.fixPosition(letter, word_pos);
+                }
+            } else if (letter_colour === YELLOW) {
+                if (this.fixed_positions[word_pos] === letter) {
+                    MELTDOWN("Can't fix and ban a letter at same position");
+                }
+                this.banPosition(letter, word_pos);
+            }
+        }
+
+        // Set Max Using Grey Input
+        for (let word_pos = 0; word_pos < 5; word_pos++) {
+            const letter = guess.charCodeAt(word_pos) - 97;
+            const letter_colour = readPatternPosition(pattern, word_pos);
+            if (letter_colour === GREY) max_counts[letter] = min_counts[letter];
+        }
+
+        for (let letter = 0; letter < 26; letter++) {
+            if (min_counts[letter] > max_counts[letter]) MELTDOWN("Can't have min count greater than max count for letter");
+            this.min_counts[letter] = Math.max(this.min_counts[letter], min_counts[letter]);
+            this.max_counts[letter] = Math.min(this.max_counts[letter], max_counts[letter])
+            if (this.min_counts[letter] > this.max_counts[letter]) MELTDOWN("Can't have min count greater than max count for letter");
+        }
+    }
+
+    /**
+     * Checks if a word meets conditions with the min, max, fixed, and banned position of characters
+     * @param {string} word
+     * @returns {boolean}
+     */
+    meetsConditions(word) {
+        const letter_counts = new Int8Array(26);
+
+        for (let i = 0; i < 5; i++) {
+            const letter = word.charCodeAt(i) - 97;
+            if (this.isBanned(letter, i)) return false;
+            letter_counts[letter] += 1;
+        }
+
+        for (let i = 0; i < 26; i++) {
+            if (letter_counts[i] > this.max_counts[i]) return false;
+            if (letter_counts[i] < this.min_counts[i]) return false;
+        }
+
+        for (let i = 0; i < 5; i++) {
+            const letter = word.charCodeAt(i) - 97;
+            if (this.hasFixedCharacter(i) && this.fixed_positions[i] !== letter) return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Checks if a character code is banned from a position
+     * @param {Number} char_code 
+     * @param {Number} word_pos 
+     */
+    isBanned(char_code, word_pos) {
+        return this.banned_positions[char_code * 5 + word_pos] === BANNED;
+    }
+
+    /** 
+     * Bans a character code from appearing at a certain word position
+     * @param {Number} char_code 
+     * @param {Number} word_pos 
+     */
+    banPosition(char_code, word_pos) {
+        this.banned_positions[char_code * 5 + word_pos] = BANNED;
+    }
+
+    /**
+     * Checks if the word position has a fixed character code
+     * @param {Number} word_pos 
+     * @returns 
+     */
+    hasFixedCharacter(word_pos) {
+        return this.fixed_positions[word_pos] !== NOT_FIXED;
+    }
+
+    /** 
+     * Fixes a character code to a word position
+     * @param {Number} char_code 
+     * @param {Number} word_pos 
+     */
+    fixPosition(char_code, word_pos) {
+        this.fixed_positions[word_pos] = char_code;
+    }
+}
+
+/**
+ * Reads the two bits that each position i that encode green, yellow, or grey 
+ * @param {number} pattern 
+ * @param {number} word_pos 
+ */
+function readPatternPosition(pattern, word_pos) {
+    return (pattern >> (word_pos * 2)) & 0b11;
+}
+
+/**
+ * Writes the two bits that in position i that encode green, yellow, or grey 
+ * @param {number} pattern 
+ * @param {number} word_pos 
+ * @param {number} data 
+ * @return {number}
+ */
+function writePatternPosition(pattern, word_pos, data) {
+    return pattern |= data << (word_pos * 2);
+}
+
+
+/**
+ * Certainly one of the ways ever of debugging
+ * ! WARNING ! LITERRALY SHUTS THE PROGRAM DOWN AFTER SENDING ERROR MESSAGE
+ * @param {string} error 
+ */
+function MELTDOWN(error) {
+    console.error(error);
+    process.exit(1);
+}
+
+/**
+ * Returns an encoded pattern based on user input strings
+ * @param {string} green 
+ * @param {string} yellow 
+ * @return {number}
+ */
+function patternFromUserInput(green, yellow) {
+    if (green.length < 5) green = green.padEnd(5, '.')
+    if (yellow.length < 5) yellow = yellow.padEnd(5, '.')    
+
+    let pattern = 0;
+
+    for (let i = 0; i < 5; i++) {
+        if (green[i] !== '.') pattern = writePatternPosition(pattern, i, GREEN)
+        if (yellow[i] !== '.') pattern = writePatternPosition(pattern, i, YELLOW)
+        // Greys are encoded by default. No need to reencode
+    }
+
+    return pattern;
+}
+
+module.exports = { Wordle, patternFromUserInput }

package/src/pre/feedback_matrix.js

@@ -0,0 +1,35 @@
+/** Precomputes a frequency matrix for a given set of words */
+const fs = require('fs');
+
+const { entropyFeedback } = require('../lib/entropy.js');
+
+try {
+    const args = process.argv.slice(2);
+    const words_file = fs.existsSync(args[0]) ? args[0] : () => { throw "Words File Not Found" };
+    const write_file  = args[1];
+    
+    const words = JSON.parse(fs.readFileSync(words_file));
+    const matrix = new Uint8Array(words.length**2);
+    const wl = words.length;
+    
+    for (let gi=0; gi < wl; gi++) {
+        const guess = words[gi];
+
+        for (let ai = 0; ai < wl; ai++) {
+            const answer = words[ai];
+            const pattern = entropyFeedback(guess, answer);
+            matrix[gi * wl + ai] = pattern;
+        }
+
+        if (gi % 1000 === 0) {
+            console.log(`Computed ${gi}/${words.length}`);
+        }
+    }
+
+    fs.writeFileSync(`${write_file}`, matrix);
+    console.log(`Feedback matrix written to ${write_file}`);
+    process.exit(0);
+} catch (err) {
+    console.error(err);
+}
+

package/src/pre/filter_words.js

@@ -0,0 +1,36 @@
+/** Filters words down to a valid list based on a given length and preset character set */
+const fs = require('node:fs');
+
+try {
+    const args = process.argv.slice(2);
+    const read_file = fs.existsSync(args[0]) ? args[0] : () => { throw "Read File Not Found" };
+    const write_file = args[1];
+    const desired_word_length = typeof(args[2]) === Number ? args[2] : 5;
+
+    const data = fs.readFileSync(read_file, 'utf8');
+    const words = data.split('\n');
+
+    const valid_words = new Array(0);
+    const valid_chars = new Array(25);
+    for (let i = 97; i <= 122; i++) {
+        valid_chars.push(String.fromCharCode(i));
+    }
+
+    for (let word of words) {
+        word = word.toLowerCase();
+        let word_is_valid = (word.length === desired_word_length);
+
+        for (const letter of word) {
+            if (!word_is_valid) break;
+            word_is_valid = word_is_valid && valid_chars.includes(letter);
+        }
+
+        if (word_is_valid) valid_words.push(word);
+    }
+
+    fs.writeFileSync(`${write_file}`, JSON.stringify(valid_words, null, 4));
+    console.log(`Wrote ${valid_words.length} Valid Words to ${write_file}`);
+    process.exit(0);
+} catch (err) {
+    console.error(err);
+}

package/src/pre/test.js

@@ -0,0 +1,26 @@
+/** Precomuputes Frequencies of Letters in Words */
+const fs = require('node:fs');
+
+const { randomInt } = require('../lib/lib.js')
+
+
+try {
+    const args = process.argv.slice(2);
+    const words_file = fs.existsSync(args[0]) ? args[0] : () => { throw "Words File Not Found" };
+    const write_file  = args[1];
+    const test_num    = args[2] > 0 ? Number.parseInt(args[2])  : () => { throw "Number of Tests Not Found/Specified" };
+
+    const words = JSON.parse(fs.readFileSync(words_file));
+    const wl = words.length;
+    const test_words = new Array(test_num);
+
+    for (let i=0; i<test_num; i++) {
+        test_words[i] = words[randomInt(wl)]
+    }
+
+    fs.writeFileSync(`${write_file}`, JSON.stringify(test_words, null, 4));
+    console.log(`Tests Written to ${write_file}`);
+    process.exit(0);
+} catch (err) {
+    console.error(err);
+}