@fgv/ts-sudoku-lib 5.0.1-9 → 5.0.1

package/dist/packlets/hints/types.js

@@ -0,0 +1,43 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Standard technique identifiers for built-in solving techniques.
+ * @public
+ */
+export const TechniqueIds = {
+    NAKED_SINGLES: 'naked-singles',
+    HIDDEN_SINGLES: 'hidden-singles'
+};
+/**
+ * Standard confidence levels as branded types.
+ * @public
+ */
+export const ConfidenceLevels = {
+    LOW: 1,
+    MEDIUM_LOW: 2,
+    MEDIUM: 3,
+    MEDIUM_HIGH: 4,
+    HIGH: 5
+};
+//# sourceMappingURL=types.js.map

package/dist/packlets/puzzles/anyPuzzle.js

@@ -0,0 +1,47 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { fail } from '@fgv/ts-utils';
+import { KillerSudokuPuzzle } from './killerSudokuPuzzle';
+import { SudokuPuzzle } from './sudokuPuzzle';
+import { SudokuXPuzzle } from './sudokuXPuzzle';
+/**
+ * Static class to instantiate any puzzle from a {@link IPuzzleDefinition | puzzle definition}.
+ * @internal
+ */
+export class AnyPuzzle {
+    static create(puzzle) {
+        switch (puzzle.type) {
+            case 'sudoku':
+                return SudokuPuzzle.create(puzzle);
+            case 'sudoku-x':
+                return SudokuXPuzzle.create(puzzle);
+            case 'killer-sudoku':
+                return KillerSudokuPuzzle.create(puzzle);
+            /* c8 ignore next 2 */
+            default:
+                return fail(`Puzzle '${puzzle.description}' unsupported type ${puzzle.type}`);
+        }
+    }
+}
+//# sourceMappingURL=anyPuzzle.js.map

package/dist/packlets/puzzles/index.js

@@ -0,0 +1,31 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { KillerSudokuPuzzle as Killer } from './killerSudokuPuzzle';
+import { SudokuPuzzle as Sudoku } from './sudokuPuzzle';
+import { SudokuXPuzzle as SudokuX } from './sudokuXPuzzle';
+import { KillerCombinations } from './killerCombinations';
+import { AnyPuzzle as Any } from './anyPuzzle';
+export * from './killerCombinationsTypes';
+export { Any, Killer, KillerCombinations, Sudoku, SudokuX };
+//# sourceMappingURL=index.js.map

package/dist/packlets/puzzles/internal/combinationCache.js

@@ -0,0 +1,75 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * @internal
+ */
+export class CombinationCache {
+    /**
+     * Generate cache key for combination parameters.
+     */
+    static generateKey(cageSize, total, constraints) {
+        var _a, _b, _c, _d;
+        const excluded = (_b = (_a = constraints === null || constraints === void 0 ? void 0 : constraints.excludedNumbers) === null || _a === void 0 ? void 0 : _a.slice().sort().join(',')) !== null && _b !== void 0 ? _b : '';
+        const required = (_d = (_c = constraints === null || constraints === void 0 ? void 0 : constraints.requiredNumbers) === null || _c === void 0 ? void 0 : _c.slice().sort().join(',')) !== null && _d !== void 0 ? _d : '';
+        return `${cageSize}:${total}:${excluded}:${required}`;
+    }
+    /**
+     * Get cached combination result.
+     */
+    static get(key) {
+        const result = this._cache.get(key);
+        if (result) {
+            // Deep clone to prevent mutation of cached data
+            return result.map((combination) => [...combination]);
+        }
+        return undefined;
+    }
+    /**
+     * Store combination result in cache.
+     */
+    static set(key, combinations) {
+        // Implement simple LRU by clearing cache when it gets too large
+        if (this._cache.size >= this._maxCacheSize) {
+            this.clear();
+        }
+        // Deep clone to prevent mutation of cached data
+        const clonedCombinations = combinations.map((combination) => [...combination]);
+        this._cache.set(key, clonedCombinations);
+    }
+    /**
+     * Clear the entire cache.
+     */
+    static clear() {
+        this._cache.clear();
+    }
+    /**
+     * Get current cache size (for testing/debugging).
+     */
+    static size() {
+        return this._cache.size;
+    }
+}
+CombinationCache._cache = new Map();
+CombinationCache._maxCacheSize = 1000;
+//# sourceMappingURL=combinationCache.js.map

package/dist/packlets/puzzles/internal/combinationGenerator.js

@@ -0,0 +1,142 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * @internal
+ */
+export class CombinationGenerator {
+    /**
+     * Generates all possible combinations of unique numbers that sum to the target total.
+     * @param cageSize - Number of cells in the cage
+     * @param total - Target sum
+     * @param constraints - Optional constraints on included/excluded numbers
+     * @param maxValue - Maximum value allowed in cells (defaults to 9)
+     * @returns Array of combinations, each sorted in ascending order
+     */
+    static generate(cageSize, total, constraints, maxValue = 9) {
+        var _a, _b;
+        const results = [];
+        const excludedSet = new Set((_a = constraints === null || constraints === void 0 ? void 0 : constraints.excludedNumbers) !== null && _a !== void 0 ? _a : []);
+        const requiredNumbers = (_b = constraints === null || constraints === void 0 ? void 0 : constraints.requiredNumbers) !== null && _b !== void 0 ? _b : [];
+        const requiredSet = new Set(requiredNumbers);
+        // Validate that we can satisfy required numbers constraint
+        if (requiredNumbers.length > cageSize) {
+            return [];
+        }
+        // Check if required numbers sum is already too high
+        const requiredSum = requiredNumbers.reduce((sum, num) => sum + num, 0);
+        if (requiredSum > total) {
+            return [];
+        }
+        // Calculate remaining constraints after accounting for required numbers
+        const remainingSize = cageSize - requiredNumbers.length;
+        const remainingTotal = total - requiredSum;
+        if (remainingSize === 0) {
+            // Only required numbers should be present
+            /* c8 ignore next 3 - edge case: required numbers fill cage but sum doesn't match (tested via KillerCombinations) */
+            if (remainingTotal === 0) {
+                return [Array.from(requiredNumbers).sort()];
+            }
+            return [];
+        }
+        // Generate combinations for the remaining slots
+        const availableNumbers = [];
+        for (let i = 1; i <= maxValue; i++) {
+            if (!excludedSet.has(i) && !requiredSet.has(i)) {
+                availableNumbers.push(i);
+            }
+        }
+        this._generateCombinations(availableNumbers, remainingSize, remainingTotal, 0, [], results);
+        // Add required numbers to each result and sort
+        return results.map((combination) => [...combination, ...requiredNumbers].sort((a, b) => a - b));
+    }
+    /**
+     * Recursive helper to generate combinations.
+     * @param availableNumbers - Numbers that can be used
+     * @param targetSize - Number of numbers needed
+     * @param targetSum - Target sum for the combination
+     * @param startIndex - Starting index in available numbers
+     * @param currentCombination - Current partial combination
+     * @param results - Array to collect results
+     */
+    static _generateCombinations(availableNumbers, targetSize, targetSum, startIndex, currentCombination, results) {
+        // Base case: we have the right number of elements
+        if (currentCombination.length === targetSize) {
+            const sum = currentCombination.reduce((total, num) => total + num, 0);
+            if (sum === targetSum) {
+                results.push([...currentCombination]);
+            }
+            return;
+        }
+        // Early termination: impossible to reach target
+        const remainingSlots = targetSize - currentCombination.length;
+        const currentSum = currentCombination.reduce((total, num) => total + num, 0);
+        const remainingSum = targetSum - currentSum;
+        // Check minimum possible sum with remaining slots
+        const minPossible = this._calculateMinSum(availableNumbers, startIndex, remainingSlots);
+        if (remainingSum < minPossible) {
+            return;
+        }
+        // Check maximum possible sum with remaining slots
+        const maxPossible = this._calculateMaxSum(availableNumbers, startIndex, remainingSlots);
+        if (remainingSum > maxPossible) {
+            return;
+        }
+        // Try each available number
+        for (let i = startIndex; i < availableNumbers.length; i++) {
+            const number = availableNumbers[i];
+            // Skip if adding this number would exceed our target
+            if (currentSum + number > targetSum) {
+                continue;
+            }
+            currentCombination.push(number);
+            this._generateCombinations(availableNumbers, targetSize, targetSum, i + 1, currentCombination, results);
+            currentCombination.pop();
+        }
+    }
+    /**
+     * Calculate minimum possible sum for remaining slots.
+     */
+    static _calculateMinSum(availableNumbers, startIndex, remainingSlots) {
+        let sum = 0;
+        let count = 0;
+        for (let i = startIndex; i < availableNumbers.length && count < remainingSlots; i++) {
+            sum += availableNumbers[i];
+            count++;
+        }
+        return sum;
+    }
+    /**
+     * Calculate maximum possible sum for remaining slots.
+     */
+    static _calculateMaxSum(availableNumbers, startIndex, remainingSlots) {
+        let sum = 0;
+        let count = 0;
+        for (let i = availableNumbers.length - 1; i >= startIndex && count < remainingSlots; i--) {
+            sum += availableNumbers[i];
+            count++;
+        }
+        return sum;
+    }
+}
+//# sourceMappingURL=combinationGenerator.js.map

package/dist/packlets/puzzles/internal/possibilityAnalyzer.js

@@ -0,0 +1,121 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { succeed } from '@fgv/ts-utils';
+/**
+ * @internal
+ */
+export class PossibilityAnalyzer {
+    /**
+     * Analyze possible values for each cell in a killer cage based on current puzzle state.
+     * @param puzzle - The puzzle instance
+     * @param state - Current puzzle state
+     * @param cage - The killer cage to analyze
+     * @param validCombinations - Pre-computed valid combinations for the cage
+     * @returns Map of CellId to possible number arrays
+     */
+    static analyze(puzzle, state, cage, validCombinations) {
+        const possibilities = new Map();
+        // Get current values in the cage
+        // We need the concrete Cage class for containedValues method
+        const concreteCage = cage;
+        const currentValues = concreteCage.containedValues(state);
+        const emptyCells = [];
+        // Identify empty cells and initialize possibilities
+        for (const cellId of cage.cellIds) {
+            const cellContents = state.getCellContents(cellId).orDefault();
+            /* c8 ignore next 1 - ? is defense in depth */
+            if ((cellContents === null || cellContents === void 0 ? void 0 : cellContents.value) !== undefined) {
+                // Cell already has a value - set empty possibilities array
+                possibilities.set(cellId, []);
+            }
+            else {
+                // Empty cell
+                emptyCells.push(cellId);
+                possibilities.set(cellId, []);
+            }
+        }
+        // Filter combinations that are compatible with current state
+        const compatibleCombinations = validCombinations.filter((combination) => {
+            // Check if combination contains all current values
+            for (const currentValue of currentValues) {
+                if (!combination.includes(currentValue)) {
+                    return false;
+                }
+            }
+            // Check if combination has the right number of remaining values
+            const remainingValues = combination.filter((value) => !currentValues.has(value));
+            return remainingValues.length === emptyCells.length;
+        });
+        // If no compatible combinations exist, return empty possibilities for all cells
+        if (compatibleCombinations.length === 0) {
+            return succeed(possibilities);
+        }
+        // For each empty cell, find which values are possible
+        for (const cellId of emptyCells) {
+            const cellPossibilities = new Set();
+            // Get the cell to check sudoku constraints
+            const cellResult = puzzle.getCell(cellId);
+            /* c8 ignore next 3 - defensive coding: protects against internal cage/puzzle state corruption */
+            if (cellResult.isFailure()) {
+                continue;
+            }
+            const cell = cellResult.value;
+            // Check each compatible combination
+            for (const combination of compatibleCombinations) {
+                const remainingValues = combination.filter((value) => !currentValues.has(value));
+                // Check if each remaining value could go in this cell
+                for (const value of remainingValues) {
+                    if (this._canPlaceValueInCell(cell, value, state)) {
+                        cellPossibilities.add(value);
+                    }
+                }
+            }
+            possibilities.set(cellId, Array.from(cellPossibilities).sort());
+        }
+        return succeed(possibilities);
+    }
+    /**
+     * Check if a value can be placed in a cell considering sudoku constraints.
+     * @param cell - The cell to check
+     * @param value - The value to place
+     * @param state - Current puzzle state
+     * @returns True if the value can be placed
+     */
+    static _canPlaceValueInCell(cell, value, state) {
+        // Check all cages this cell belongs to for sudoku constraints
+        for (const cage of cell.cages) {
+            if (cage.cageType === 'killer') {
+                // Skip killer cage check - we're already analyzing within killer constraints
+                continue;
+            }
+            // Check if value already exists in this constraint cage (row, column, section, etc.)
+            const concreteCage = cage;
+            if (concreteCage.containsValue(value, state, [cell.id])) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=possibilityAnalyzer.js.map