@johnmorrisdotca/kazu 1.2.0 → 1.3.0

package/dist/hitoriLogic.js

@@ -0,0 +1,189 @@
+import { hitoriNeighbors } from "./hitoriBoard.js";
+/**
+ * Hitori as variables: one per square, slot 0 for left white and slot 1 for shaded.
+ * `strength` is how much of the rules the pruning uses: 0 has the duplicates, the ban on touching shades, the
+ * pair and the sandwich; 1 adds that every white square must stay in reach of the others; 2 adds that a square
+ * whose shading would cut the whites in two must stay white. A finished answer must be one piece, which the
+ * search checks whatever the strength.
+ */
+export function hitoriModel(board, strength = 2) {
+    const size = board.size, total = size * size;
+    const neighbours = Array.from({ length: total }, (_, cell) => Int32Array.from(hitoriNeighbors(size, cell)));
+    const partners = Array.from({ length: total }, (_, cell) => {
+        const x = cell % size, y = Math.floor(cell / size), found = [];
+        for (let k = 0; k < size; k += 1) {
+            if (k !== x && board.numbers[y * size + k] === board.numbers[cell])
+                found.push(y * size + k);
+            if (k !== y && board.numbers[k * size + x] === board.numbers[cell])
+                found.push(k * size + x);
+        }
+        return Int32Array.from(found);
+    });
+    // A pair of equal numbers side by side shades every other equal number of that line; a number on both sides of a square keeps it white.
+    const pairs = [];
+    const sandwiches = [];
+    for (let y = 0; y < size; y += 1)
+        for (let x = 0; x < size; x += 1) {
+            const cell = y * size + x;
+            for (const [dx, dy] of [[1, 0], [0, 1]]) {
+                const nx = x + dx, ny = y + dy;
+                if (nx >= size || ny >= size)
+                    continue;
+                const next = ny * size + nx;
+                if (board.numbers[cell] === board.numbers[next]) {
+                    const others = partners[cell].filter(other => other !== next && (dx ? Math.floor(other / size) === y : other % size === x));
+                    if (others.length)
+                        pairs.push({ a: cell, b: next, others });
+                }
+                const fx = x + 2 * dx, fy = y + 2 * dy;
+                if (fx < size && fy < size && board.numbers[cell] === board.numbers[fy * size + fx])
+                    sandwiches.push(next);
+            }
+        }
+    const starts = Int32Array.from({ length: total + 1 }, (_, i) => i * 2);
+    const disc = new Int32Array(total), low = new Int32Array(total), whitesBelow = new Int32Array(total);
+    const propagate = (alive) => {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (let c = 0; c < total; c += 1) {
+                const white = alive[2 * c], shaded = alive[2 * c + 1];
+                if (!white && !shaded)
+                    return false;
+                if (shaded && !white) {
+                    const around = neighbours[c];
+                    for (let k = 0; k < around.length; k += 1) {
+                        const n = around[k];
+                        if (alive[2 * n + 1]) {
+                            alive[2 * n + 1] = 0;
+                            changed = true;
+                            if (!alive[2 * n])
+                                return false;
+                        }
+                    }
+                }
+                if (white && !shaded) {
+                    const same = partners[c];
+                    for (let k = 0; k < same.length; k += 1) {
+                        const p = same[k];
+                        if (alive[2 * p]) {
+                            alive[2 * p] = 0;
+                            changed = true;
+                            if (!alive[2 * p + 1])
+                                return false;
+                        }
+                    }
+                }
+                if (shaded) {
+                    // A square is shaded only to settle a duplicate, so some equal number in its row or column must stay white.
+                    const same = partners[c];
+                    let free = 0, last = -1;
+                    for (let k = 0; k < same.length; k += 1)
+                        if (alive[2 * same[k]]) {
+                            free += 1;
+                            last = same[k];
+                        }
+                    if (free === 0) {
+                        if (!white)
+                            return false;
+                        alive[2 * c + 1] = 0;
+                        changed = true;
+                    }
+                    else if (free === 1 && !white && alive[2 * last + 1]) {
+                        alive[2 * last + 1] = 0;
+                        changed = true;
+                    }
+                }
+            }
+            for (const { a, b, others } of pairs) {
+                if (!alive[2 * a] && !alive[2 * b])
+                    continue;
+                for (let k = 0; k < others.length; k += 1) {
+                    const o = others[k];
+                    if (alive[2 * o]) {
+                        alive[2 * o] = 0;
+                        changed = true;
+                        if (!alive[2 * o + 1])
+                            return false;
+                    }
+                }
+            }
+            for (let k = 0; k < sandwiches.length; k += 1) {
+                const m = sandwiches[k];
+                if (alive[2 * m + 1]) {
+                    alive[2 * m + 1] = 0;
+                    changed = true;
+                    if (!alive[2 * m])
+                        return false;
+                }
+            }
+            if (strength > 0) {
+                const verdict = reach(alive);
+                if (verdict < 0)
+                    return false;
+                if (verdict > 0)
+                    changed = true;
+            }
+        }
+        return true;
+    };
+    const cutList = new Int32Array(total);
+    let clock = 0, cutCount = 0, whiteTotal = 0, current = new Uint8Array(0), power = 0;
+    const visit = (u, parent) => {
+        disc[u] = low[u] = ++clock;
+        let below = current[2 * u + 1] ? 0 : 1, cutWhites = 0, cutParts = 0;
+        const around = neighbours[u];
+        for (let k = 0; k < around.length; k += 1) {
+            const n = around[k];
+            if (!current[2 * n] || n === parent)
+                continue;
+            if (disc[n]) {
+                if (disc[n] < low[u])
+                    low[u] = disc[n];
+                continue;
+            }
+            visit(n, u);
+            if (low[n] < low[u])
+                low[u] = low[n];
+            below += whitesBelow[n];
+            if (low[n] >= disc[u] && whitesBelow[n] > 0) {
+                cutParts += 1;
+                cutWhites += whitesBelow[n];
+            }
+        }
+        whitesBelow[u] = below;
+        if (power > 1 && current[2 * u] && current[2 * u + 1] && cutParts + (whiteTotal - cutWhites > 0 ? 1 : 0) >= 2)
+            cutList[cutCount++] = u;
+    };
+    /** -1 when the white squares cannot be one piece, 1 when a square was forced white, 0 when nothing moved. */
+    const reach = (alive) => {
+        let root = -1;
+        whiteTotal = 0;
+        for (let c = 0; c < total; c += 1)
+            if (!alive[2 * c + 1]) {
+                whiteTotal += 1;
+                if (root < 0)
+                    root = c;
+            }
+        if (root < 0)
+            return 0;
+        if (!alive[2 * root])
+            return -1;
+        disc.fill(0);
+        clock = 0;
+        cutCount = 0;
+        current = alive;
+        power = strength;
+        visit(root, -1);
+        let seenWhites = 0;
+        for (let c = 0; c < total; c += 1)
+            if (!alive[2 * c + 1] && disc[c])
+                seenWhites += 1;
+        if (seenWhites !== whiteTotal)
+            return -1;
+        for (let k = 0; k < cutCount; k += 1)
+            alive[2 * cutList[k] + 1] = 0;
+        return cutCount ? 1 : 0;
+    };
+    return { csp: { starts, propagate } };
+}

package/dist/hitoriRate.d.ts

@@ -0,0 +1,3 @@
+import type { HitoriBoard, HitoriRating } from "./hitori.types.ts";
+/** Rates a board with one answer by solving it: with the plain rules, with the whites-stay-together rule, then by supposing. */
+export declare function rateHitori(board: HitoriBoard): HitoriRating;

package/dist/hitoriRate.js

@@ -0,0 +1,32 @@
+import { checkHitori, isHitoriBoard } from "./hitoriBoard.js";
+import { hitoriModel } from "./hitoriLogic.js";
+import { logicCsp, openSlots, solveCsp } from "./csp.js";
+/** Rates a board with one answer by solving it: with the plain rules, with the whites-stay-together rule, then by supposing. */
+export function rateHitori(board) {
+    if (!isHitoriBoard(board))
+        throw new RangeError("Invalid Hitori board");
+    const strong = hitoriModel(board, 2).csp;
+    const proof = solveCsp(strong, openSlots(strong), 2, 300000);
+    if (proof.count !== 1 || proof.exhausted)
+        throw new RangeError("Hitori rating needs a board with one answer");
+    const shaded = Array.from({ length: board.size ** 2 }, (_, cell) => proof.solution[2 * cell + 1] === 1);
+    const solvedBy = (strength, depth) => {
+        const { csp } = hitoriModel(board, strength);
+        const run = logicCsp(csp, openSlots(csp), depth);
+        return { ...run, solved: run.solved && checkHitori(board, Array.from({ length: board.size ** 2 }, (_, cell) => run.alive[2 * cell + 1] === 1)).ok };
+    };
+    const plain = solvedBy(0, 0), reach = plain.solved ? plain : solvedBy(2, 0);
+    const probing = reach.solved ? reach : solvedBy(2, 1);
+    const repeats = board.numbers.filter((_, cell) => {
+        const x = cell % board.size, y = Math.floor(cell / board.size);
+        return board.numbers.some((other, at) => at !== cell && other === board.numbers[cell] && (at % board.size === x || Math.floor(at / board.size) === y));
+    }).length;
+    return {
+        depth: reach.solved ? 0 : probing.solved ? 1 : 2,
+        reach: !plain.solved && reach.solved,
+        probes: reach.solved ? 0 : probing.probes,
+        shaded: shaded.filter(Boolean).length,
+        shadedShare: shaded.filter(Boolean).length / shaded.length,
+        repeatShare: repeats / shaded.length,
+    };
+}

package/dist/hitoriSolve.d.ts

@@ -1,5 +1,8 @@
 import type { HitoriBoard, HitoriSolve } from "./hitori.types.ts";
-/** Counts distinct minimal shade patterns. A non-complete result never asserts uniqueness. */
+/**
+ * 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 declare function solveHitori(board: HitoriBoard, options?: {
     limit?: number;
     nodes?: number;

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;