@johnmorrisdotca/kazu 1.2.0 → 1.4.0

package/dist/hitoriSolve.js

@@ -1,69 +1,18 @@
 import { HITORI_MAX_NODES } from "./hitori.constants.js";
-import { checkHitori, hitoriNeighbors, isHitoriBoard } from "./hitoriBoard.js";
-function firstUnshadedDuplicate(board, shaded) {
-    const size = board.size;
-    for (let y = 0; y < size; y += 1)
-        for (let x = 0; x < size; x += 1) {
-            const cell = y * size + x;
-            if (shaded[cell])
-                continue;
-            for (let otherX = x + 1; otherX < size; otherX += 1) {
-                const other = y * size + otherX;
-                if (!shaded[other] && board.numbers[cell] === board.numbers[other])
-                    return [cell, other];
-            }
-            for (let otherY = y + 1; otherY < size; otherY += 1) {
-                const other = otherY * size + x;
-                if (!shaded[other] && board.numbers[cell] === board.numbers[other])
-                    return [cell, other];
-            }
-        }
-    return null;
-}
-/** A valid answer cannot contain an unnecessary shade; this avoids treating extra black cells as separate puzzle solutions. */
-function isMinimalSolution(board, shaded) {
-    if (!checkHitori(board, shaded).ok)
-        return false;
-    for (let cell = 0; cell < shaded.length; cell += 1)
-        if (shaded[cell]) {
-            const smaller = [...shaded];
-            smaller[cell] = false;
-            if (checkHitori(board, smaller).ok)
-                return false;
-        }
-    return true;
-}
-/** Counts distinct minimal shade patterns. A non-complete result never asserts uniqueness. */
+import { isHitoriBoard } from "./hitoriBoard.js";
+import { hitoriModel } from "./hitoriLogic.js";
+import { openSlots, solveCsp } from "./csp.js";
+/**
+ * Counts distinct minimal shade patterns: an answer shades only squares that settle a duplicate, so extra shades
+ * are never a second answer. A non-complete result never asserts uniqueness.
+ */
 export function solveHitori(board, options = {}) {
     if (!isHitoriBoard(board))
         throw new RangeError("Invalid Hitori board");
     const limit = Math.max(1, Math.floor(options.limit ?? 2));
     const budget = Math.max(1, Math.floor(options.nodes ?? HITORI_MAX_NODES));
-    let nodes = 0, count = 0, solution = null, exhausted = false;
-    const search = (shaded) => {
-        if (count >= limit || exhausted)
-            return;
-        nodes += 1;
-        if (nodes > budget) {
-            exhausted = true;
-            return;
-        }
-        const duplicate = firstUnshadedDuplicate(board, shaded);
-        if (!duplicate) {
-            if (isMinimalSolution(board, shaded)) {
-                count += 1;
-                solution ?? (solution = [...shaded]);
-            }
-            return;
-        }
-        for (const cell of duplicate) {
-            if (hitoriNeighbors(board.size, cell).some(neighbor => shaded[neighbor]))
-                continue;
-            shaded[cell] = true;
-            search(shaded);
-            shaded[cell] = false;
-        }
-    };
-    search(Array(board.size * board.size).fill(false));
-    return { count, solution, complete: !exhausted && count < limit, nodes: Math.min(nodes, budget) };
+    const { csp } = hitoriModel(board);
+    const found = solveCsp(csp, openSlots(csp), limit, budget);
+    const solution = found.solution ? Array.from({ length: board.size ** 2 }, (_, cell) => found.solution[2 * cell + 1] === 1) : null;
+    return { count: found.count, solution, complete: !found.exhausted && !found.stopped, nodes: found.nodes };
 }

package/dist/kakuro-entry.d.ts

@@ -3,6 +3,7 @@ export * from "./kakuro.constants.ts";
 export * from "./kakuroBoard.ts";
 export * from "./kakuroSolve.ts";
 export * from "./kakuroGenerate.ts";
+export * from "./kakuroRate.ts";
 export * from "./kakuroGame.ts";
 export { drawKakuro } from "./kakuroDraw.ts";
 export type { KakuroDrawOptions } from "./kakuroDraw.ts";

package/dist/kakuro-entry.js

@@ -3,6 +3,7 @@ export * from "./kakuro.constants.js";
 export * from "./kakuroBoard.js";
 export * from "./kakuroSolve.js";
 export * from "./kakuroGenerate.js";
+export * from "./kakuroRate.js";
 export * from "./kakuroGame.js";
 export { drawKakuro } from "./kakuroDraw.js";
 export { mountKakuro } from "./kakuroMount.js";

package/dist/kakuro.constants.d.ts

@@ -1,6 +1,11 @@
 export declare const KAKURO_MIN_SIDE = 3;
-export declare const KAKURO_MAX_SIDE = 10;
+export declare const KAKURO_MAX_SIDE = 12;
 export declare const KAKURO_MAX_NODES = 250000;
 export declare const KAKURO_MAX_ATTEMPTS = 120;
 export declare const KAKURO_GENERATION_ATTEMPTS = 1200;
 export declare const KAKURO_GENERATION_NODES = 1000000;
+/** How hard a puzzle is made, by what a person must do to solve it; see `rateKakuro`. */
+export declare const KAKURO_LEVELS: readonly ["easy", "medium", "hard", "extra-hard"];
+/** The sides on offer, counting the row and column of totals; any side from 5 to `KAKURO_MAX_SIDE` can be made. */
+export declare const KAKURO_SIZES: readonly [6, 8, 10, 12];
+export declare const KAKURO_LEAST_GENERATED_SIDE = 5;

package/dist/kakuro.constants.js

@@ -1,6 +1,11 @@
 export const KAKURO_MIN_SIDE = 3;
-export const KAKURO_MAX_SIDE = 10;
+export const KAKURO_MAX_SIDE = 12;
 export const KAKURO_MAX_NODES = 250000;
 export const KAKURO_MAX_ATTEMPTS = 120;
 export const KAKURO_GENERATION_ATTEMPTS = 1200;
 export const KAKURO_GENERATION_NODES = 1000000;
+/** How hard a puzzle is made, by what a person must do to solve it; see `rateKakuro`. */
+export const KAKURO_LEVELS = ["easy", "medium", "hard", "extra-hard"];
+/** The sides on offer, counting the row and column of totals; any side from 5 to `KAKURO_MAX_SIDE` can be made. */
+export const KAKURO_SIZES = [6, 8, 10, 12];
+export const KAKURO_LEAST_GENERATED_SIDE = 5;

package/dist/kakuro.types.d.ts

@@ -16,10 +16,29 @@ export type KakuroRun = {
     cells: readonly number[];
     sum: number;
 };
+export type KakuroLevel = "easy" | "medium" | "hard" | "extra-hard";
 export type KakuroPuzzle = KakuroBoard & {
     seed: number;
+    level: KakuroLevel;
     solution: readonly number[];
 };
+/**
+ * How hard a board is, measured by solving it. `depth` 0 means the rules solve it, 1 that somebody has to suppose a
+ * digit and watch it break, 2 that more than that is needed; `plain` says the single-run rules were enough (no
+ * digit that must appear had to be traced). `probes` is how many suppositions depth 1 needed. The rest describes the runs.
+ */
+export type KakuroRating = {
+    depth: 0 | 1 | 2;
+    plain: boolean;
+    probes: number;
+    whites: number;
+    runs: number;
+    longest: number;
+    /** Mean number of squares in a run. */
+    meanRun: number;
+    /** Runs whose total can be made in only one way, as a share of the runs. */
+    fixedShare: number;
+};
 export type KakuroCheck = {
     ok: boolean;
     complete: boolean;

package/dist/kakuroBuild.d.ts

@@ -0,0 +1,30 @@
+import type { KakuroBoard, KakuroLevel } from "./kakuro.types.ts";
+import type { Random } from "./random.ts";
+/** How the black squares are scattered, and the longest run a level allows. */
+export declare const SHAPE: Record<KakuroLevel, {
+    black: number;
+    longest: number;
+}>;
+/** Which squares are white: no run shorter than two, none longer than the level allows, and all of them one connected piece. */
+export declare function kakuroPattern(side: number, level: KakuroLevel, random: Random): boolean[] | null;
+/** How many different sets of digits can make `sum` out of `length` squares. */
+export declare function kakuroWays(length: number, sum: number): number;
+/** A random digit for every white square with no digit repeated in a run, or null when the search gives up. */
+export declare function kakuroDigits(side: number, white: readonly boolean[], random: Random): number[] | null;
+/**
+ * Changes digits one square at a time, keeping every run free of repeats, to make runs whose totals can be made in
+ * few ways: a run that says a lot about its digits lets the solver start from the rules alone. A change is kept when
+ * it does not raise the count of ways, summed over runs, which is `weight` raised to the number of ways.
+ */
+export declare function kakuroTighten(side: number, white: readonly boolean[], digits: number[], random: Random, rounds: number): void;
+/** The totals of a pattern and its digits, as a board. */
+export declare function kakuroBoardOf(side: number, white: readonly boolean[], digits: readonly number[]): KakuroBoard;
+/**
+ * A board with exactly one answer, or null. While the board has other answers, each one is broken: a square the
+ * two answers disagree on is turned black (when every run stays two long and the squares stay one piece) or given
+ * another digit that still repeats nowhere in its runs, which changes two totals.
+ */
+export declare function candidateKakuro(side: number, level: KakuroLevel, random: Random): {
+    board: KakuroBoard;
+    digits: readonly number[];
+} | null;

package/dist/kakuroBuild.js

@@ -0,0 +1,337 @@
+import { isKakuroBoard } from "./kakuroBoard.js";
+import { kakuroModel } from "./kakuroLogic.js";
+import { countCsp, logicCsp, openSlots } from "./csp.js";
+import { shuffled } from "./random.js";
+/** How the black squares are scattered, and the longest run a level allows. */
+export const SHAPE = {
+    easy: { black: .34, longest: 4 },
+    medium: { black: .3, longest: 5 },
+    hard: { black: .26, longest: 7 },
+    "extra-hard": { black: .22, longest: 9 },
+};
+/** Which squares are white: no run shorter than two, none longer than the level allows, and all of them one connected piece. */
+export function kakuroPattern(side, level, random) {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+        const white = laidRows(side, level, random);
+        if (white && oneStrip(side, white))
+            return white;
+    }
+    return null;
+}
+/**
+ * Lays the squares out row by row, each row left to right, so that a run is never one square or longer than the
+ * level allows: a column whose run is one square long must go on, one at the limit must stop, and a row's own
+ * runs are kept the same way. A square is white with the level's chance, except where a rule forces it.
+ */
+function laidRows(side, level, random) {
+    const { black, longest } = SHAPE[level];
+    const white = Array(side * side).fill(false), above = Array(side).fill(0);
+    const chance = 1 - black * (.85 + random() * .3);
+    for (let row = 1; row < side; row += 1) {
+        const last = row === side - 1, chosen = Array(side).fill(false);
+        let steps = 0;
+        const place = (col, run) => {
+            if (++steps > 4000)
+                return false;
+            if (col === side)
+                return run !== 1;
+            const mustWhite = above[col] === 1;
+            const mustBlack = above[col] === longest || last && above[col] === 0;
+            const options = [];
+            if (mustWhite && mustBlack)
+                return false;
+            if (mustWhite)
+                options.push(true);
+            else if (mustBlack)
+                options.push(false);
+            else
+                options.push(...(random() < chance ? [true, false] : [false, true]));
+            for (const isWhite of options) {
+                if (isWhite && run + 1 > longest)
+                    continue;
+                if (!isWhite && run === 1)
+                    continue;
+                chosen[col] = isWhite;
+                if (place(col + 1, isWhite ? run + 1 : 0))
+                    return true;
+            }
+            return false;
+        };
+        if (!place(1, 0))
+            return null;
+        for (let col = 1; col < side; col += 1) {
+            white[row * side + col] = chosen[col];
+            above[col] = chosen[col] ? above[col] + 1 : 0;
+        }
+    }
+    return white;
+}
+/** How many different sets of digits can make `sum` out of `length` squares. */
+export function kakuroWays(length, sum) {
+    let ways = 0;
+    for (let mask = 1; mask < 512; mask += 1) {
+        let n = 0, total = 0;
+        for (let d = 1; d <= 9; d += 1)
+            if (mask & 1 << d - 1) {
+                n += 1;
+                total += d;
+            }
+        if (n === length && total === sum)
+            ways += 1;
+    }
+    return ways;
+}
+const WAYS = Array.from({ length: 10 }, (_, length) => Array.from({ length: 46 }, (_, sum) => length < 2 ? 0 : kakuroWays(length, sum)));
+/** A random digit for every white square with no digit repeated in a run, or null when the search gives up. */
+export function kakuroDigits(side, white, random) {
+    const digits = Array(white.length).fill(0);
+    let steps = 0;
+    const fill = (at) => {
+        while (at < white.length && !white[at])
+            at += 1;
+        if (at === white.length)
+            return true;
+        if (++steps > 40000)
+            return false;
+        const used = new Set();
+        for (let left = at - 1; left >= 0 && white[left] && (left + 1) % side !== 0; left -= 1)
+            used.add(digits[left]);
+        for (let up = at - side; up >= 0 && white[up]; up -= side)
+            used.add(digits[up]);
+        for (const digit of shuffled([1, 2, 3, 4, 5, 6, 7, 8, 9].filter(d => !used.has(d)), random)) {
+            digits[at] = digit;
+            if (fill(at + 1))
+                return true;
+        }
+        digits[at] = 0;
+        return false;
+    };
+    return fill(0) ? digits : null;
+}
+/**
+ * Changes digits one square at a time, keeping every run free of repeats, to make runs whose totals can be made in
+ * few ways: a run that says a lot about its digits lets the solver start from the rules alone. A change is kept when
+ * it does not raise the count of ways, summed over runs, which is `weight` raised to the number of ways.
+ */
+export function kakuroTighten(side, white, digits, random, rounds) {
+    const runsAt = (cell) => {
+        const across = [cell], down = [cell];
+        for (let at = cell - 1; at >= 0 && white[at] && (at + 1) % side !== 0; at -= 1)
+            across.push(at);
+        for (let at = cell + 1; at < white.length && white[at] && at % side !== 0; at += 1)
+            across.push(at);
+        for (let at = cell - side; at >= 0 && white[at]; at -= side)
+            down.push(at);
+        for (let at = cell + side; at < white.length && white[at]; at += side)
+            down.push(at);
+        return { across, down };
+    };
+    const ways = (run, swap) => {
+        let sum = 0;
+        for (const at of run)
+            sum += swap && at === swap.cell ? swap.digit : digits[at];
+        return WAYS[run.length][sum];
+    };
+    const cells = white.flatMap((w, i) => w ? [i] : []);
+    for (let round = 0; round < rounds; round += 1) {
+        const cell = cells[Math.floor(random() * cells.length)];
+        const { across, down } = runsAt(cell);
+        const used = new Set();
+        for (const at of [...across, ...down])
+            if (at !== cell)
+                used.add(digits[at]);
+        const options = [1, 2, 3, 4, 5, 6, 7, 8, 9].filter(d => !used.has(d) && d !== digits[cell]);
+        if (!options.length)
+            continue;
+        const digit = options[Math.floor(random() * options.length)];
+        const before = ways(across) + ways(down), after = ways(across, { cell, digit }) + ways(down, { cell, digit });
+        if (after <= before)
+            digits[cell] = digit;
+    }
+}
+/** The totals of a pattern and its digits, as a board. */
+export function kakuroBoardOf(side, white, digits) {
+    const cells = white.map(w => w ? { kind: "white" } : { kind: "black", across: null, down: null });
+    for (let cell = 0; cell < white.length; cell += 1) {
+        if (white[cell])
+            continue;
+        const black = cells[cell];
+        if (cell % side < side - 1 && white[cell + 1]) {
+            let sum = 0;
+            for (let at = cell + 1; white[at]; at += 1) {
+                sum += digits[at];
+                if ((at + 1) % side === 0)
+                    break;
+            }
+            black.across = sum;
+        }
+        if (cell + side < white.length && white[cell + side]) {
+            let sum = 0;
+            for (let at = cell + side; at < white.length && white[at]; at += side)
+                sum += digits[at];
+            black.down = sum;
+        }
+    }
+    return { width: side, height: side, cells };
+}
+/** Whether the white squares are one connected piece. */
+function oneStrip(side, white) {
+    const first = white.indexOf(true);
+    if (first < 0)
+        return false;
+    const seen = new Set([first]), stack = [first];
+    while (stack.length) {
+        const at = stack.pop();
+        for (const next of [at - 1, at + 1, at - side, at + side]) {
+            if (next < 0 || next >= white.length || !white[next] || seen.has(next) || (next === at + 1 && next % side === 0))
+                continue;
+            seen.add(next);
+            stack.push(next);
+        }
+    }
+    return seen.size === white.filter(Boolean).length;
+}
+/** The squares in the same row or column strip as `cell` that have the given digit, to see what digits it may take. */
+function digitsAround(side, white, digits, cell) {
+    const used = new Set();
+    for (let at = cell - 1; at >= 0 && white[at] && (at + 1) % side !== 0; at -= 1)
+        used.add(digits[at]);
+    for (let at = cell + 1; at < white.length && white[at] && at % side !== 0; at += 1)
+        used.add(digits[at]);
+    for (let at = cell - side; at >= 0 && white[at]; at -= side)
+        used.add(digits[at]);
+    for (let at = cell + side; at < white.length && white[at]; at += side)
+        used.add(digits[at]);
+    return used;
+}
+/**
+ * A board with exactly one answer, or null. While the board has other answers, each one is broken: a square the
+ * two answers disagree on is turned black (when every run stays two long and the squares stay one piece) or given
+ * another digit that still repeats nowhere in its runs, which changes two totals.
+ */
+export function candidateKakuro(side, level, random) {
+    // Easy and medium boards are also eased until the rules they promise are enough to solve them.
+    const eased = level === "easy" ? 0 : level === "medium" ? 1 : -1;
+    const white = kakuroPattern(side, level, random);
+    if (!white)
+        return null;
+    const digits = kakuroDigits(side, white, random);
+    if (!digits)
+        return null;
+    if (level === "easy" || level === "medium")
+        kakuroTighten(side, white, digits, random, side * side * (level === "easy" ? 60 : 25));
+    const valid = () => {
+        for (let cell = 0; cell < white.length; cell += 1) {
+            if (!white[cell])
+                continue;
+            let across = 1, down = 1;
+            for (let at = cell - 1; at >= 0 && white[at] && (at + 1) % side !== 0; at -= 1)
+                across += 1;
+            for (let at = cell + 1; at < white.length && white[at] && at % side !== 0; at += 1)
+                across += 1;
+            for (let at = cell - side; at >= 0 && white[at]; at -= side)
+                down += 1;
+            for (let at = cell + side; at < white.length && white[at]; at += side)
+                down += 1;
+            if (across < 2 || down < 2)
+                return false;
+        }
+        return oneStrip(side, white);
+    };
+    for (let repair = 0; repair < 150; repair += 1) {
+        const board = kakuroBoardOf(side, white, digits);
+        if (!isKakuroBoard(board))
+            return null;
+        const model = kakuroModel(board, 1, random);
+        let found = countCsp(model.csp, openSlots(model.csp), 8, 3000);
+        for (let restart = 0; restart < 5 && found.exhausted; restart += 1)
+            found = countCsp(model.csp, openSlots(model.csp), 8, 3000);
+        if (found.exhausted) {
+            // Too many answers to even count: darken any square that can be darkened and look again.
+            const any = shuffled(white.flatMap((w, cell) => w ? [cell] : []), random).find(cell => { white[cell] = false; if (valid())
+                return true; white[cell] = true; return false; });
+            if (any === undefined)
+                return null;
+            continue;
+        }
+        if (found.count === 1 && eased < 0)
+            return { board, digits };
+        if (found.count === 1) {
+            const rules = kakuroModel(board, eased);
+            const run = logicCsp(rules.csp, openSlots(rules.csp), 0);
+            if (run.solved)
+                return { board, digits };
+            if (white.filter(Boolean).length < (side - 1) * (side - 1) * .42)
+                return null;
+            const open = rules.whites.filter((_, i) => { let n = 0; for (let k = 0; k < 9; k += 1)
+                n += run.alive[9 * i + k]; return n > 1; });
+            // Squares still open, then the others that share a run with one.
+            const near = new Set(open);
+            for (const cell of open) {
+                for (let at = cell - 1; at >= 0 && white[at] && (at + 1) % side !== 0; at -= 1)
+                    near.add(at);
+                for (let at = cell + 1; at < white.length && white[at] && at % side !== 0; at += 1)
+                    near.add(at);
+                for (let at = cell - side; at >= 0 && white[at]; at -= side)
+                    near.add(at);
+                for (let at = cell + side; at < white.length && white[at]; at += side)
+                    near.add(at);
+            }
+            const stuck = [...shuffled(open, random), ...shuffled([...near].filter(cell => !open.includes(cell)), random)];
+            let eased_ = false;
+            for (const cell of stuck) {
+                white[cell] = false;
+                if (valid()) {
+                    eased_ = true;
+                    break;
+                }
+                white[cell] = true;
+            }
+            if (!eased_) {
+                const any = shuffled(white.flatMap((w, cell) => w ? [cell] : []), random).find(cell => { white[cell] = false; if (valid())
+                    return true; white[cell] = true; return false; });
+                if (any === undefined)
+                    return null;
+            }
+            continue;
+        }
+        const digitOf = (answer, cell) => { const index = model.index[cell]; let d = 0; for (let k = 0; k < 9; k += 1)
+            if (answer[9 * index + k])
+                d = k + 1; return d; };
+        let moved = false;
+        for (const answer of found.solutions) {
+            const differing = shuffled(white.flatMap((w, cell) => w && digitOf(answer, cell) !== digits[cell] ? [cell] : []), random);
+            if (!differing.length)
+                continue;
+            const blacken = () => {
+                for (const cell of differing) {
+                    if (!white[cell])
+                        continue;
+                    white[cell] = false;
+                    if (valid())
+                        return true;
+                    white[cell] = true;
+                }
+                return false;
+            };
+            const change = () => {
+                for (const cell of differing) {
+                    if (!white[cell])
+                        continue;
+                    const used = digitsAround(side, white, digits, cell);
+                    const options = [1, 2, 3, 4, 5, 6, 7, 8, 9].filter(d => !used.has(d));
+                    if (!options.length)
+                        continue;
+                    digits[cell] = options[Math.floor(random() * options.length)];
+                    return true;
+                }
+                return false;
+            };
+            if (random() < .5 ? blacken() || change() : change() || blacken())
+                moved = true;
+        }
+        if (!moved)
+            return null;
+    }
+    return null;
+}

package/dist/kakuroGenerate.d.ts

@@ -1,3 +1,10 @@
-import type { KakuroPuzzle } from "./kakuro.types.ts";
-/** Makes a seeded 10×10 family of crossing runs and returns only a uniquely proved puzzle. */
-export declare function generateKakuro(seed?: number): KakuroPuzzle;
+import type { KakuroLevel, KakuroPuzzle } from "./kakuro.types.ts";
+/**
+ * Makes a seeded board of `size` squares a side (counting the row and column of totals) and proves it has one
+ * answer. A random pattern of black squares sets the runs, random digits fill them, and digits are changed until
+ * the answer is single. The board is then rated by solving it: easy by the single-run rules, medium once a digit
+ * that must appear has to be traced, hard by supposing, and extra-hard the most-supposing of several boards.
+ * If no board of the level is found within the attempts the next level down is tried, and the first generator
+ * (a 10×10 only) is the last resort, so a seed never throws.
+ */
+export declare function generateKakuro(seed?: number, level?: KakuroLevel, size?: number): KakuroPuzzle;