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

package/dist/packlets/common/puzzleState.js

@@ -0,0 +1,99 @@
+/*
+ * 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, succeed } from '@fgv/ts-utils';
+/**
+ * @public
+ */
+export class PuzzleState {
+    /**
+     * @internal
+     */
+    constructor(from, updates) {
+        const entries = [...Array.from(from.entries()), ...PuzzleState._toEntries(updates)];
+        this._cells = new Map(entries);
+    }
+    /**
+     * Constructs a new {@link PuzzleState | PuzzleState}.
+     * @param cells - An array of {@link ICellState | CellState} used to initialize the state.
+     * @returns The new {@link PuzzleState | PuzzleState}.
+     */
+    static create(cells) {
+        return succeed(new PuzzleState(new Map(), cells));
+    }
+    /**
+     * Convert {@link ICellContents | CellContents} to `[`{@link CellId | CellId}`,` {@link ICellContents | CellContents}`]`
+     * tuple for `Map` construction.
+     * @param states - An array of {@link ICellContents | CellContents} to be converted.
+     * @returns The corresponding array of `[`{@link CellId | CellId}`,` {@link ICellContents | CellContents}`]`
+     * @internal
+     */
+    static _toEntries(states) {
+        /* c8 ignore next 3 - defense in depth */
+        if (!states) {
+            return [];
+        }
+        return states.map((state) => {
+            const { id, value, notes } = state;
+            return [id, { value, notes }];
+        });
+    }
+    /**
+     * Gets the contents of a cell specified by {@link CellId | id}.
+     * @param id - The {@link CellId | id} of the cell to be retrieved.
+     * @returns A {@link ICellContents | CellContents} with the contents of
+     * the requested cell.
+     */
+    getCellContents(id) {
+        const cell = this._cells.get(id);
+        return cell ? succeed(cell) : fail(`cell ${id} not found`);
+    }
+    /**
+     * Determines if some cell has an assigned value.
+     * @param id - The {@link CellId | id} of the cell to be tested.
+     * @returns `true` if the cell has a value, `false` if the cell
+     * is empty or invalid.
+     */
+    hasValue(id) {
+        const cell = this._cells.get(id);
+        /* c8 ignore next 1 - defense in depth, tested but coverage fails */
+        return (cell === null || cell === void 0 ? void 0 : cell.value) !== undefined;
+    }
+    /**
+     * Creates a new {@link PuzzleState | PuzzleState} which corresponds
+     * to this state with updates applied.
+     * @param updates - An array of {@link ICellState | CellState} to be
+     * applied.
+     * @returns A new {@link PuzzleState} with updates applied.
+     */
+    update(updates) {
+        const updated = new PuzzleState(this._cells, updates);
+        /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+        if (updated._cells.size > this._cells.size) {
+            return fail(`update added cells`);
+        }
+        return succeed(updated);
+    }
+}
+/* c8 ignore next 7 - functional code tested but coverage intermittently missed */
+//# sourceMappingURL=puzzleState.js.map

package/dist/packlets/files/converters.js

@@ -0,0 +1,67 @@
+/*
+ * 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 { Converters, succeed } from '@fgv/ts-utils';
+import { Converters as CommonConverters } from '../common';
+/**
+ * Converts puzzle file dimensions from JSON format
+ * @public
+ */
+export const puzzleFileDimensions = Converters.strictObject({
+    cageWidthInCells: Converters.number,
+    cageHeightInCells: Converters.number,
+    boardWidthInCages: Converters.number,
+    boardHeightInCages: Converters.number
+});
+/**
+ * Converts puzzle file data from JSON format
+ * @public
+ */
+export const puzzleFileData = Converters.strictObject({
+    id: Converters.string,
+    description: Converters.string,
+    type: CommonConverters.puzzleType,
+    level: Converters.number,
+    cells: Converters.oneOf([Converters.string, Converters.stringArray.map((s) => succeed(s.join('')))]),
+    dimensions: puzzleFileDimensions
+}, {
+    optionalFields: ['id']
+});
+/**
+ * Converts an arbitrary object to a {@link Files.Model.IPuzzlesFile | IPuzzlesFile}.
+ * @public
+ */
+export const puzzlesFile = Converters.strictObject({
+    puzzles: Converters.arrayOf(puzzleFileData)
+});
+/**
+ * Loads a puzzles file from a `IFileTreeFileItem`.
+ * @param file - The `IFileTreeFileItem` to load.
+ * @returns `Success` with the resulting {@link Files.Model.IPuzzlesFile | IPuzzlesFile}, or `Failure` with
+ * details if an error occurs.
+ * @public
+ */
+export function loadPuzzlesFile(file) {
+    return file.getContents(puzzlesFile);
+}
+//# sourceMappingURL=converters.js.map

package/dist/packlets/files/fileTreeHelpers.js

@@ -0,0 +1,37 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 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 { puzzlesFile } from './converters';
+import { JsonFile } from '@fgv/ts-json-base';
+/**
+ * Loads a puzzles file from a {@link FileTree.FileTree | FileTree}.
+ * @param fileTree - FileTree containing the file
+ * @param filePath - Path within the FileTree to the puzzles file
+ * @returns `Success` with the resulting file, or `Failure` with details if an
+ * error occurs.
+ * @public
+ */
+export function loadJsonPuzzlesFromTree(fileTree, filePath) {
+    return JsonFile.DefaultJsonTreeHelper.convertJsonFromTree(fileTree, filePath, puzzlesFile);
+}
+//# sourceMappingURL=fileTreeHelpers.js.map

package/dist/packlets/files/filesystem.js

@@ -0,0 +1,37 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 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 { puzzlesFile } from './converters';
+import { JsonFile } from '@fgv/ts-json-base';
+/**
+ * Loads an arbitrary JSON file and parses it to return a validated
+ * {@link Files.Model.IPuzzlesFile | IPuzzlesFile}.
+ * @param path - String path to the file
+ * @returns `Success` with the resulting file, or `Failure` with details if an
+ * error occurs.
+ * @public
+ */
+export function loadJsonPuzzlesFileSync(path) {
+    return JsonFile.convertJsonFileSync(path, puzzlesFile);
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/packlets/files/index.browser.js

@@ -0,0 +1,32 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 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.
+ */
+// Browser-safe files exports - includes FileTree functions, excludes Node.js filesystem functions
+import * as Converters from './converters';
+import * as Model from './model';
+export { Converters, Model };
+// Re-export browser-compatible FileTree helpers
+export { loadJsonPuzzlesFromTree } from './fileTreeHelpers';
+// Excluded from browser:
+// - loadJsonPuzzlesFileSync (requires Node.js fs via JsonFile.convertJsonFileSync)
+//# sourceMappingURL=index.browser.js.map

package/dist/packlets/files/index.js

@@ -0,0 +1,30 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 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 * as Converters from './converters';
+import * as Model from './model';
+export { Converters, Model };
+// Export both filesystem and FileTree helpers
+export { loadJsonPuzzlesFileSync } from './filesystem';
+export { loadJsonPuzzlesFromTree } from './fileTreeHelpers';
+//# sourceMappingURL=index.js.map

package/dist/packlets/files/model.js

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/packlets/hints/baseHintProvider.js

@@ -0,0 +1,199 @@
+/*
+ * 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, succeed } from '@fgv/ts-utils';
+import { ConfidenceLevels } from './types';
+/**
+ * Abstract base class providing common functionality for hint providers.
+ * @public
+ */
+export class BaseHintProvider {
+    constructor(config) {
+        var _a;
+        this.techniqueId = config.techniqueId;
+        this.techniqueName = config.techniqueName;
+        this.difficulty = config.difficulty;
+        this.priority = config.priority;
+        this.defaultConfidence = (_a = config.defaultConfidence) !== null && _a !== void 0 ? _a : ConfidenceLevels.MEDIUM;
+    }
+    /**
+     * Utility method to create a hint with consistent structure.
+     * @param cellActions - The actions to be performed on cells
+     * @param relevantCells - The cells relevant to understanding the hint
+     * @param explanations - The explanations for the hint
+     * @param confidence - The confidence level for this hint
+     * @returns A complete hint object
+     */
+    createHint(cellActions, relevantCells, explanations, confidence) {
+        /* c8 ignore next 1 - defense in depth */
+        confidence = confidence !== null && confidence !== void 0 ? confidence : this.defaultConfidence;
+        return {
+            techniqueId: this.techniqueId,
+            techniqueName: this.techniqueName,
+            difficulty: this.difficulty,
+            confidence,
+            cellActions,
+            relevantCells,
+            explanations,
+            priority: this.priority
+        };
+    }
+    /**
+     * Utility method to create cell actions.
+     * @param cellId - The ID of the cell to act upon
+     * @param action - The type of action to perform
+     * @param value - Optional value for set-value actions
+     * @param reason - Optional reason for the action
+     * @returns A cell action object
+     */
+    createCellAction(cellId, action, value, reason) {
+        return {
+            cellId,
+            action,
+            value,
+            reason
+        };
+    }
+    /**
+     * Utility method to create relevant cells grouping.
+     * @param primary - Primary cells that are the focus of the hint
+     * @param secondary - Secondary cells that provide context
+     * @param affected - Cells that will be affected by applying the hint
+     * @returns A relevant cells object
+     */
+    createRelevantCells(primary, secondary = [], affected = []) {
+        return {
+            primary,
+            secondary,
+            affected
+        };
+    }
+    /**
+     * Utility method to create hint explanations.
+     * @param level - The level of detail for the explanation
+     * @param title - The title of the explanation
+     * @param description - The main description
+     * @param steps - Optional step-by-step instructions
+     * @param tips - Optional tips for understanding the technique
+     * @returns A hint explanation object
+     */
+    createExplanation(level, title, description, steps, tips) {
+        return {
+            level,
+            title,
+            description,
+            steps,
+            tips
+        };
+    }
+    /**
+     * Filters hints based on generation options.
+     * @param hints - The hints to filter
+     * @param options - The filtering options
+     * @returns Filtered array of hints
+     */
+    filterHints(hints, options) {
+        if (!options) {
+            return hints;
+        }
+        let filtered = [...hints];
+        // Filter by minimum confidence
+        if (options.minConfidence) {
+            filtered = filtered.filter((hint) => hint.confidence >= options.minConfidence);
+        }
+        // Filter by enabled techniques
+        if (options.enabledTechniques && options.enabledTechniques.length > 0) {
+            filtered = filtered.filter((hint) => options.enabledTechniques.includes(hint.techniqueId));
+        }
+        // Limit number of hints
+        if (options.maxHints && options.maxHints > 0) {
+            // Sort by confidence (descending) then priority (ascending)
+            filtered.sort((a, b) => {
+                if (a.confidence !== b.confidence) {
+                    return b.confidence - a.confidence;
+                }
+                return a.priority - b.priority;
+            });
+            filtered = filtered.slice(0, options.maxHints);
+        }
+        return filtered;
+    }
+    /**
+     * Validates generation options for consistency.
+     * @param options - The options to validate
+     * @returns Result indicating validation success or failure
+     */
+    validateOptions(options) {
+        if (!options) {
+            return succeed(undefined);
+        }
+        if (options.maxHints !== undefined && options.maxHints < 0) {
+            return fail('maxHints cannot be negative');
+        }
+        if (options.minConfidence !== undefined && (options.minConfidence < 1 || options.minConfidence > 5)) {
+            return fail('minConfidence must be between 1 and 5');
+        }
+        return succeed(undefined);
+    }
+    /**
+     * Gets all empty cells in the puzzle.
+     * @param puzzle - The puzzle structure
+     * @param state - The puzzle state to analyze
+     * @returns Array of cell IDs that are empty
+     */
+    getEmptyCells(puzzle, state) {
+        return puzzle.getEmptyCells(state).map((cell) => cell.id);
+    }
+    /**
+     * Gets the possible candidate values for a specific cell using cage-based constraints.
+     * This implementation works with any puzzle variant by checking all applicable cages.
+     * @param cellId - The cell to analyze
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of possible values for the cell
+     */
+    getCandidates(cellId, puzzle, state) {
+        if (state.hasValue(cellId)) {
+            return [];
+        }
+        // Get maximum value based on grid size (typically sqrt of total cells)
+        const maxValue = Math.sqrt(puzzle.numRows * puzzle.numColumns);
+        // Find all cages that contain this cell
+        const applicableCages = puzzle.cages.filter((cage) => cage.containsCell(cellId));
+        // Collect all values that are forbidden due to cage constraints
+        const usedValues = new Set();
+        for (const cage of applicableCages) {
+            const cageValues = cage.containedValues(state);
+            cageValues.forEach((value) => usedValues.add(value));
+        }
+        // Generate candidates (values not used in any applicable cage)
+        const candidates = [];
+        for (let value = 1; value <= maxValue; value++) {
+            if (!usedValues.has(value)) {
+                candidates.push(value);
+            }
+        }
+        return candidates;
+    }
+}
+//# sourceMappingURL=baseHintProvider.js.map