@fgv/ts-sudoku-lib 5.0.1-0 → 5.0.1-2

package/lib/packlets/hints/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './interfaces';
+export * from './baseHintProvider';
+export * from './hintRegistry';
+export * from './nakedSingles';
+export * from './hiddenSingles';
+export * from './explanations';
+export * from './hints';
+export * from './puzzleSessionHints';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/hints/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Core types and interfaces
+__exportStar(require("./types"), exports);
+__exportStar(require("./interfaces"), exports);
+// Base classes and utilities
+__exportStar(require("./baseHintProvider"), exports);
+__exportStar(require("./hintRegistry"), exports);
+// Technique implementations
+__exportStar(require("./nakedSingles"), exports);
+__exportStar(require("./hiddenSingles"), exports);
+// Educational framework
+__exportStar(require("./explanations"), exports);
+// Main hint system
+__exportStar(require("./hints"), exports);
+// PuzzleSession integration
+__exportStar(require("./puzzleSessionHints"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/hints/interfaces.d.ts

@@ -0,0 +1,121 @@
+import { Result } from '@fgv/ts-utils';
+import { ICellState, Puzzle, PuzzleState } from '../common';
+import { DifficultyLevel, IHint, IHintExplanation, IHintGenerationOptions, TechniqueId } from './types';
+/**
+ * Interface for classes that can provide hints using a specific solving technique.
+ * @public
+ */
+export interface IHintProvider {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly priority: number;
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * This should be a fast check to avoid expensive hint generation when not applicable.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if this provider might be able to generate hints
+     */
+    canProvideHints(puzzle: Puzzle, state: PuzzleState): boolean;
+    /**
+     * Generates all possible hints using this technique 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 hints, or failure if generation fails
+     */
+    generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+}
+/**
+ * Interface for managing and coordinating multiple hint providers.
+ * @public
+ */
+export interface IHintRegistry {
+    /**
+     * Registers a new hint provider.
+     * @param provider - The provider to register
+     * @returns Result indicating success or failure of registration
+     */
+    registerProvider(provider: IHintProvider): Result<void>;
+    /**
+     * Unregisters a hint provider.
+     * @param techniqueId - The ID of the technique to unregister
+     * @returns Result indicating success or failure of unregistration
+     */
+    unregisterProvider(techniqueId: TechniqueId): Result<void>;
+    /**
+     * Gets a specific provider by technique ID.
+     * @param techniqueId - The ID of the technique
+     * @returns Result containing the provider, or failure if not found
+     */
+    getProvider(techniqueId: TechniqueId): Result<IHintProvider>;
+    /**
+     * Gets all registered providers, optionally filtered by criteria.
+     * @param options - Optional filtering options
+     * @returns Array of providers matching the criteria
+     */
+    getProviders(options?: IHintGenerationOptions): readonly IHintProvider[];
+    /**
+     * Generates hints using all applicable providers.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints from all providers
+     */
+    generateAllHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets the best available hint based on difficulty and confidence.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing the best hint, or failure if no hints available
+     */
+    getBestHint(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Gets all registered technique IDs.
+     * @returns Array of technique IDs
+     */
+    getRegisteredTechniques(): readonly TechniqueId[];
+}
+/**
+ * Interface for hint explanation generation and formatting.
+ * @public
+ */
+export interface IHintExplanationProvider {
+    /**
+     * Gets the technique ID this explanation provider supports.
+     */
+    readonly techniqueId: TechniqueId;
+    /**
+     * Generates explanations for a specific hint.
+     * @param hint - The hint to explain
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The puzzle state context
+     * @returns Result containing array of explanations at different levels
+     */
+    generateExplanations(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly IHintExplanation[]>;
+}
+/**
+ * Interface for hint application and validation.
+ * @public
+ */
+export interface IHintApplicator {
+    /**
+     * Validates that a hint can be safely applied to the given state.
+     * @param hint - The hint to validate
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result indicating validation success or failure with details
+     */
+    canApplyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<void>;
+    /**
+     * Applies a hint to the puzzle state, generating the necessary cell updates.
+     * @param hint - The hint to apply
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing the cell state updates needed to apply the hint
+     */
+    applyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly ICellState[]>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/packlets/{file/model.js → hints/interfaces.js}

@@ -23,4 +23,4 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=model.js.map
+//# sourceMappingURL=interfaces.js.map

package/lib/packlets/hints/nakedSingles.d.ts

@@ -0,0 +1,57 @@
+import { Result } from '@fgv/ts-utils';
+import { Puzzle, PuzzleState } from '../common';
+import { BaseHintProvider } from './baseHintProvider';
+import { IHint, IHintGenerationOptions } 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 declare class NakedSinglesProvider extends BaseHintProvider {
+    /**
+     * Creates a new NakedSinglesProvider instance.
+     */
+    constructor();
+    /**
+     * 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: Puzzle, state: PuzzleState): boolean;
+    /**
+     * 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: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * 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
+     */
+    private _createNakedSingleHint;
+    /**
+     * 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
+     */
+    private _findRelatedCells;
+    /**
+     * Static factory method to create a new NakedSinglesProvider.
+     * @returns Result containing the new provider
+     */
+    static create(): Result<NakedSinglesProvider>;
+}
+//# sourceMappingURL=nakedSingles.d.ts.map

package/lib/packlets/hints/nakedSingles.js

@@ -0,0 +1,202 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NakedSinglesProvider = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const baseHintProvider_1 = require("./baseHintProvider");
+const types_1 = require("./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
+ */
+class NakedSinglesProvider extends baseHintProvider_1.BaseHintProvider {
+    /**
+     * Creates a new NakedSinglesProvider instance.
+     */
+    constructor() {
+        super({
+            techniqueId: types_1.TechniqueIds.NAKED_SINGLES,
+            techniqueName: 'Naked Singles',
+            difficulty: 'beginner',
+            priority: 1, // Highest priority - should be checked first
+            defaultConfidence: types_1.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 (0, ts_utils_1.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, types_1.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 = (0, common_1.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 = common_1.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 = common_1.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 = common_1.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 (0, ts_utils_1.succeed)(new NakedSinglesProvider());
+    }
+}
+exports.NakedSinglesProvider = NakedSinglesProvider;
+//# sourceMappingURL=nakedSingles.js.map