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

package/dist/packlets/hints/nakedSingles.js

@@ -0,0 +1,198 @@
+/*
+ * 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';
+import { Ids, parseCellId } from '../common';
+import { BaseHintProvider } from './baseHintProvider';
+import { ConfidenceLevels, TechniqueIds } from './types';
+/**
+ * Hint provider for the Naked Singles technique.
+ *
+ * A Naked Single occurs when a cell has only one possible candidate value
+ * based on the constraints of its row, column, and 3x3 box.
+ *
+ * @public
+ */
+export class NakedSinglesProvider extends BaseHintProvider {
+    /**
+     * Creates a new NakedSinglesProvider instance.
+     */
+    constructor() {
+        super({
+            techniqueId: TechniqueIds.NAKED_SINGLES,
+            techniqueName: 'Naked Singles',
+            difficulty: 'beginner',
+            priority: 1, // Highest priority - should be checked first
+            defaultConfidence: ConfidenceLevels.HIGH
+        });
+    }
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * Always returns true since naked singles can potentially exist in any incomplete puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if there are empty cells that might have naked singles
+     */
+    canProvideHints(puzzle, state) {
+        // Quick check: if there are empty cells, there might be naked singles
+        const emptyCells = this.getEmptyCells(puzzle, state);
+        return emptyCells.length > 0;
+    }
+    /**
+     * Generates all naked single hints for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of naked single hints
+     */
+    generateHints(puzzle, state, options) {
+        return this.validateOptions(options).onSuccess(() => {
+            const hints = [];
+            const emptyCells = this.getEmptyCells(puzzle, state);
+            for (const cellId of emptyCells) {
+                const candidates = this.getCandidates(cellId, puzzle, state);
+                // A naked single has exactly one candidate
+                if (candidates.length === 1) {
+                    const value = candidates[0];
+                    const hint = this._createNakedSingleHint(cellId, value, state, puzzle);
+                    hints.push(hint);
+                }
+            }
+            return succeed(this.filterHints(hints, options));
+        });
+    }
+    /**
+     * Creates a hint for a specific naked single.
+     * @param cellId - The cell containing the naked single
+     * @param value - The single possible value for the cell
+     * @param state - The current puzzle state
+     * @returns A complete hint for this naked single
+     */
+    _createNakedSingleHint(cellId, value, state, puzzle) {
+        // Create cell action to set the value
+        const cellAction = this.createCellAction(cellId, 'set-value', value, `Only possible value for this cell`);
+        // Find related cells that eliminate other candidates
+        const relatedCells = this._findRelatedCells(cellId, value, state, puzzle);
+        // Create relevant cells grouping
+        const relevantCells = this.createRelevantCells([cellId], // Primary: the cell with the naked single
+        relatedCells, // Secondary: cells that constrain this cell
+        [] // Affected: none for naked singles
+        );
+        // Create explanations at different levels
+        const explanations = [
+            this.createExplanation('brief', 'Naked Single', `Cell ${cellId} can only contain the value ${value}.`, [`Set ${cellId} = ${value}`], ['Look for cells with only one possible value']),
+            this.createExplanation('detailed', 'Naked Single Analysis', `Cell ${cellId} has only one possible candidate: ${value}. All other values (1-9) are ` +
+                `eliminated by existing numbers in the same row, column, or 3x3 box.`, [
+                `Examine cell ${cellId}`,
+                `Check which values 1-9 are already used in the same row, column, and 3x3 box`,
+                `Identify that only ${value} is not eliminated`,
+                `Set ${cellId} = ${value}`
+            ], [
+                'Naked singles are the most basic solving technique',
+                'Always check for naked singles first',
+                'A cell with one candidate must contain that value'
+            ]),
+            this.createExplanation('educational', 'Understanding Naked Singles', `A naked single occurs when a cell has only one possible value due to Sudoku's fundamental rules. ` +
+                `In cell ${cellId}, the value ${value} is the only number from 1-${puzzle.dimensions.maxValue} that doesn't already appear in the ` +
+                `same row, column, or section. This makes it a "naked" single because the solution is immediately visible.`, [
+                `Locate cell ${cellId} in the grid`,
+                `Scan the row containing ${cellId} and note which numbers 1-${puzzle.dimensions.maxValue} are already placed`,
+                `Scan the column containing ${cellId} and note which numbers 1-${puzzle.dimensions.maxValue} are already placed`,
+                `Scan the section containing ${cellId} and note which numbers 1-${puzzle.dimensions.maxValue} are already placed`,
+                `Combine all the "used" numbers from row, column, and section`,
+                `The remaining unused number is ${value}, which must go in ${cellId}`,
+                `Place ${value} in cell ${cellId}`
+            ], [
+                'Naked singles are always correct - there is no risk in placing them',
+                'Start every solving session by finding all naked singles',
+                'Placing naked singles often reveals new naked singles in related cells',
+                'This technique forms the foundation for all other Sudoku solving methods'
+            ])
+        ];
+        return this.createHint([cellAction], relevantCells, explanations, ConfidenceLevels.HIGH);
+    }
+    /**
+     * Finds cells in the same row, column, and box that constrain the given cell.
+     * @param cellId - The cell to analyze
+     * @param value - The value that will be placed
+     * @param state - The current puzzle state
+     * @param puzzle - The puzzle for dimensions
+     * @returns Array of cell IDs that are related to this naked single
+     */
+    _findRelatedCells(cellId, value, state, puzzle) {
+        const relatedCells = [];
+        // Parse the cell ID to get row and column
+        const coords = parseCellId(cellId.toString());
+        /* c8 ignore next 3 - defensive coding: handles corrupted cell ID, impractical to test via public API */
+        if (!coords) {
+            return relatedCells;
+        }
+        const { row, col } = coords;
+        const totalRows = puzzle.dimensions.totalRows;
+        const totalColumns = puzzle.dimensions.totalColumns;
+        const cageHeight = puzzle.dimensions.cageHeightInCells;
+        const cageWidth = puzzle.dimensions.cageWidthInCells;
+        // Find cells in the same row, column, and section that contain any value
+        // These are the cells that constrain our naked single
+        // Same row
+        for (let c = 0; c < totalColumns; c++) {
+            if (c !== col) {
+                const checkIdResult = Ids.cellId({ row, col: c });
+                if (checkIdResult.isSuccess() && state.hasValue(checkIdResult.value)) {
+                    relatedCells.push(checkIdResult.value);
+                }
+            }
+        }
+        // Same column
+        for (let r = 0; r < totalRows; r++) {
+            if (r !== row) {
+                const checkIdResult = Ids.cellId({ row: r, col });
+                if (checkIdResult.isSuccess() && state.hasValue(checkIdResult.value)) {
+                    relatedCells.push(checkIdResult.value);
+                }
+            }
+        }
+        // Same section/cage
+        const boxStartRow = Math.floor(row / cageHeight) * cageHeight;
+        const boxStartCol = Math.floor(col / cageWidth) * cageWidth;
+        for (let r = boxStartRow; r < boxStartRow + cageHeight; r++) {
+            for (let c = boxStartCol; c < boxStartCol + cageWidth; c++) {
+                if (r !== row || c !== col) {
+                    const checkIdResult = Ids.cellId({ row: r, col: c });
+                    if (checkIdResult.isSuccess() && state.hasValue(checkIdResult.value)) {
+                        relatedCells.push(checkIdResult.value);
+                    }
+                }
+            }
+        }
+        return relatedCells;
+    }
+    /**
+     * Static factory method to create a new NakedSinglesProvider.
+     * @returns Result containing the new provider
+     */
+    static create() {
+        return succeed(new NakedSinglesProvider());
+    }
+}
+//# sourceMappingURL=nakedSingles.js.map

package/dist/packlets/hints/puzzleSessionHints.js

@@ -0,0 +1,495 @@
+/*
+ * 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';
+import { Ids } from '../common';
+import { HintSystem } from './hints';
+/**
+ * Wrapper class that integrates hint functionality with PuzzleSession.
+ * Provides hint generation, application, and explanation capabilities while
+ * maintaining integration with existing state management and undo/redo functionality.
+ * @public
+ */
+export class PuzzleSessionHints {
+    /**
+     * @internal
+     */
+    constructor(session, hintSystem, config) {
+        this._session = session;
+        this._hintSystem = hintSystem;
+        this._config = config;
+        this._hintCache = undefined;
+    }
+    /**
+     * Creates a new PuzzleSessionHints wrapper for an existing PuzzleSession.
+     * @param session - The PuzzleSession to wrap
+     * @param config - Optional configuration for the hint system
+     * @returns Result containing the new PuzzleSessionHints wrapper
+     */
+    static create(session, config) {
+        const finalConfig = Object.assign({ enableNakedSingles: true, enableHiddenSingles: true, defaultExplanationLevel: 'detailed', cacheTimeoutMs: 5000, maxCacheEntries: 1 }, config);
+        return HintSystem.create(finalConfig).onSuccess((hintSystem) => {
+            return succeed(new PuzzleSessionHints(session, hintSystem, finalConfig));
+        });
+    }
+    /**
+     * Gets the wrapped PuzzleSession instance.
+     * @returns The underlying PuzzleSession
+     */
+    get session() {
+        return this._session;
+    }
+    /**
+     * Gets the HintSystem instance.
+     * @returns The hint system
+     */
+    get hintSystem() {
+        return this._hintSystem;
+    }
+    /**
+     * Gets the configuration.
+     * @returns The configuration
+     */
+    get config() {
+        return this._config;
+    }
+    // Delegate all PuzzleSession methods for transparent access
+    /**
+     * Gets the puzzle ID.
+     * @returns The puzzle ID
+     */
+    get id() {
+        return this._session.id;
+    }
+    /**
+     * Gets the puzzle description.
+     * @returns The puzzle description
+     */
+    get description() {
+        return this._session.description;
+    }
+    /**
+     * Gets the number of rows in the puzzle.
+     * @returns The number of rows
+     */
+    get numRows() {
+        return this._session.numRows;
+    }
+    /**
+     * Gets the number of columns in the puzzle.
+     * @returns The number of columns
+     */
+    get numColumns() {
+        return this._session.numColumns;
+    }
+    /**
+     * Gets the current puzzle state.
+     * @returns The current state
+     */
+    get state() {
+        return this._session.state;
+    }
+    /**
+     * Gets whether undo is possible.
+     * @returns true if undo is possible
+     */
+    get canUndo() {
+        return this._session.canUndo;
+    }
+    /**
+     * Gets whether redo is possible.
+     * @returns true if redo is possible
+     */
+    get canRedo() {
+        return this._session.canRedo;
+    }
+    /**
+     * Checks if the puzzle is solved.
+     * @returns true if the puzzle is solved
+     */
+    checkIsSolved() {
+        return this._session.checkIsSolved();
+    }
+    /**
+     * Checks if the puzzle is valid.
+     * @returns true if the puzzle is valid
+     */
+    checkIsValid() {
+        return this._session.checkIsValid();
+    }
+    /**
+     * Updates a cell value.
+     * @param spec - Cell specification
+     * @param value - New value
+     * @returns Result with this instance
+     */
+    updateCellValue(spec, value) {
+        return this._session.updateCellValue(spec, value).onSuccess(() => {
+            this._invalidateCache();
+            return succeed(this);
+        });
+    }
+    /**
+     * Updates cell notes.
+     * @param spec - Cell specification
+     * @param notes - New notes
+     * @returns Result with this instance
+     */
+    updateCellNotes(spec, notes) {
+        return this._session.updateCellNotes(spec, notes).onSuccess(() => {
+            this._invalidateCache();
+            return succeed(this);
+        });
+    }
+    /**
+     * Updates multiple cells.
+     * @param updates - Array of cell updates
+     * @returns Result with this instance
+     */
+    updateCells(updates) {
+        return this._session.updateCells(updates).onSuccess(() => {
+            this._invalidateCache();
+            return succeed(this);
+        });
+    }
+    /**
+     * Performs an undo operation.
+     * @returns Result with this instance
+     */
+    undo() {
+        return this._session.undo().onSuccess(() => {
+            this._invalidateCache();
+            return succeed(this);
+        });
+    }
+    /**
+     * Performs a redo operation.
+     * @returns Result with this instance
+     */
+    redo() {
+        return this._session.redo().onSuccess(() => {
+            this._invalidateCache();
+            return succeed(this);
+        });
+    }
+    // Hint-specific functionality
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing the best hint
+     */
+    getHint(options) {
+        return this._hintSystem.getBestHint(this._session.puzzle, this._session.state, options);
+    }
+    /**
+     * Gets all available hints for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing array of hints
+     */
+    getAllHints(options) {
+        // Check cache first
+        const cachedHints = this._getCachedHints(options);
+        if (cachedHints) {
+            return succeed(cachedHints);
+        }
+        // Generate new hints
+        return this._hintSystem
+            .generateHints(this._session.puzzle, this._session.state, options)
+            .onSuccess((hints) => {
+            this._updateCache(hints, options);
+            return succeed(hints);
+        });
+    }
+    /**
+     * Applies a hint to the puzzle, updating the state and adding to undo history.
+     * @param hint - The hint to apply
+     * @returns Result with this instance if successful
+     */
+    applyHint(hint) {
+        return this._hintSystem
+            .applyHint(hint, this._session.puzzle, this._session.state)
+            .onSuccess((updates) => {
+            // Convert readonly array to mutable array for PuzzleSession.updateCells
+            const mutableUpdates = [...updates];
+            return this._session.updateCells(mutableUpdates).onSuccess(() => {
+                this._invalidateCache();
+                return succeed(this);
+            });
+        });
+    }
+    /**
+     * Gets hints that specifically affect a given cell.
+     * @param spec - Cell specification (ID, row/column, or cell object)
+     * @param options - Optional hint generation options
+     * @returns Result containing hints affecting the specified cell
+     */
+    getHintsForCell(spec, options) {
+        const cellIdResult = Ids.cellId(spec);
+        return cellIdResult.onSuccess((cellId) => {
+            return this.getAllHints(options).onSuccess((allHints) => {
+                const relevantHints = allHints.filter((hint) => {
+                    // Check if the hint affects this specific cell
+                    return (hint.cellActions.some((action) => action.cellId === cellId) ||
+                        hint.relevantCells.primary.includes(cellId) ||
+                        hint.relevantCells.secondary.includes(cellId) ||
+                        hint.relevantCells.affected.includes(cellId));
+                });
+                return succeed(relevantHints);
+            });
+        });
+    }
+    /**
+     * Gets a formatted explanation for a hint.
+     * @param hint - The hint to explain
+     * @param level - The explanation level (defaults to configured default)
+     * @returns Formatted explanation string
+     */
+    getExplanation(hint, level) {
+        return this._hintSystem.formatHintExplanation(hint, level);
+    }
+    /**
+     * Validates that a hint can be applied to the current state.
+     * @param hint - The hint to validate
+     * @returns Result indicating validation success or failure
+     */
+    validateHint(hint) {
+        return this._hintSystem.validateHint(hint, this._session.puzzle, this._session.state);
+    }
+    /**
+     * Checks if hints are available for the current state.
+     * @param options - Optional hint generation options
+     * @returns Result containing boolean indicating availability
+     */
+    hasHints(options) {
+        return this._hintSystem.hasHints(this._session.puzzle, this._session.state);
+    }
+    /**
+     * Gets statistics about available hints.
+     * @param options - Optional hint generation options
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(options) {
+        return this._hintSystem.getHintStatistics(this._session.puzzle, this._session.state);
+    }
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary() {
+        return this._hintSystem.getSystemSummary();
+    }
+    // Delegate remaining PuzzleSession methods for complete transparency
+    /**
+     * Gets the rows.
+     * @returns Array of row cages
+     */
+    get rows() {
+        return this._session.rows;
+    }
+    /**
+     * Gets the columns.
+     * @returns Array of column cages
+     */
+    get cols() {
+        return this._session.cols;
+    }
+    /**
+     * Gets the sections.
+     * @returns Array of section cages
+     */
+    get sections() {
+        return this._session.sections;
+    }
+    /**
+     * Gets all cages.
+     * @returns Array of all cages
+     */
+    get cages() {
+        return this._session.cages;
+    }
+    /**
+     * Gets all cells.
+     * @returns Array of all cells
+     */
+    get cells() {
+        return this._session.cells;
+    }
+    /**
+     * Gets the next step index.
+     * @returns Next step index
+     */
+    get nextStep() {
+        return this._session.nextStep;
+    }
+    /**
+     * Gets the number of steps.
+     * @returns Number of steps
+     */
+    get numSteps() {
+        return this._session.numSteps;
+    }
+    /**
+     * Gets empty cells.
+     * @returns Array of empty cells
+     */
+    getEmptyCells() {
+        return this._session.getEmptyCells();
+    }
+    /**
+     * Gets invalid cells.
+     * @returns Array of invalid cells
+     */
+    getInvalidCells() {
+        return this._session.getInvalidCells();
+    }
+    /**
+     * Checks if a cell is valid.
+     * @param spec - Cell specification
+     * @returns true if valid
+     */
+    cellIsValid(spec) {
+        return this._session.cellIsValid(spec);
+    }
+    /**
+     * Checks if a cell has a value.
+     * @param spec - Cell specification
+     * @returns true if cell has value
+     */
+    cellHasValue(spec) {
+        return this._session.cellHasValue(spec);
+    }
+    /**
+     * Checks if a value is valid for a cell.
+     * @param spec - Cell specification
+     * @param value - Value to check
+     * @returns true if valid
+     */
+    isValidForCell(spec, value) {
+        return this._session.isValidForCell(spec, value);
+    }
+    /**
+     * Gets a cell neighbor.
+     * @param spec - Cell specification
+     * @param direction - Navigation direction
+     * @param wrap - Wrap behavior
+     * @returns Result containing neighbor cell
+     */
+    getCellNeighbor(spec, direction, wrap) {
+        return this._session.getCellNeighbor(spec, direction, wrap);
+    }
+    /**
+     * Gets cell contents.
+     * @param spec - Cell specification
+     * @returns Result containing cell and contents
+     */
+    getCellContents(spec) {
+        return this._session.getCellContents(spec);
+    }
+    /**
+     * Checks if a cage contains a value.
+     * @param spec - Cage specification
+     * @param value - Value to check
+     * @returns true if cage contains value
+     */
+    cageContainsValue(spec, value) {
+        return this._session.cageContainsValue(spec, value);
+    }
+    /**
+     * Gets contained values in a cage.
+     * @param spec - Cage specification
+     * @returns Set of contained values
+     */
+    cageContainedValues(spec) {
+        return this._session.cageContainedValues(spec);
+    }
+    /**
+     * Gets string representation of the puzzle.
+     * @returns Array of strings representing puzzle rows
+     */
+    toStrings() {
+        return this._session.toStrings();
+    }
+    // Private cache management methods
+    /**
+     * Generates a cache key for the current state and options.
+     * @param options - Hint generation options
+     * @returns Cache key
+     */
+    _generateCacheKey(options) {
+        // Simple state hash based on cell values and notes
+        const stateString = this._session.toStrings().join('|');
+        const notesString = this._session.cells
+            .map((cell) => {
+            const contents = this._session
+                .getCellContents(cell.id)
+                .orDefault({ cell, contents: { value: undefined, notes: [] } });
+            return `${cell.id}:${contents.contents.notes.join(',')}`;
+        })
+            .join('|');
+        const stateHash = `${stateString}#${notesString}`;
+        const optionsString = options ? JSON.stringify(options) : '';
+        return { stateHash, options: optionsString };
+    }
+    /**
+     * Gets cached hints if valid.
+     * @param options - Hint generation options
+     * @returns Cached hints or undefined
+     */
+    _getCachedHints(options) {
+        var _a;
+        if (!this._hintCache) {
+            return undefined;
+        }
+        const cacheKey = this._generateCacheKey(options);
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const timeoutMs = (_a = this._config.cacheTimeoutMs) !== null && _a !== void 0 ? _a : 5000;
+        const now = Date.now();
+        // Check if cache is still valid
+        if (this._hintCache.cacheKey.stateHash === cacheKey.stateHash &&
+            this._hintCache.cacheKey.options === cacheKey.options &&
+            now - this._hintCache.generatedAt < timeoutMs) {
+            return this._hintCache.hints;
+        }
+        return undefined;
+    }
+    /**
+     * Updates the cache with new hints.
+     * @param hints - Generated hints
+     * @param options - Generation options
+     */
+    _updateCache(hints, options) {
+        const cacheKey = this._generateCacheKey(options);
+        this._hintCache = {
+            hints,
+            generatedAt: Date.now(),
+            cacheKey
+        };
+    }
+    /**
+     * Invalidates the current hint cache.
+     */
+    _invalidateCache() {
+        this._hintCache = undefined;
+    }
+}
+//# sourceMappingURL=puzzleSessionHints.js.map