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

package/dist/packlets/hints/explanations.js

@@ -0,0 +1,270 @@
+/*
+ * 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 { TechniqueIds } from './types';
+/**
+ * Registry for managing hint explanation providers.
+ * @public
+ */
+export class ExplanationRegistry {
+    /**
+     * Creates a new ExplanationRegistry instance.
+     */
+    constructor() {
+        this._providers = new Map();
+    }
+    /**
+     * Registers a new explanation provider.
+     * @param provider - The provider to register
+     * @returns Result indicating success or failure of registration
+     */
+    registerProvider(provider) {
+        if (this._providers.has(provider.techniqueId)) {
+            return fail(`Explanation provider for technique ${provider.techniqueId} is already registered`);
+        }
+        this._providers.set(provider.techniqueId, provider);
+        return succeed(undefined);
+    }
+    /**
+     * Gets 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 the explanations
+     */
+    getExplanations(hint, puzzle, state) {
+        const provider = this._providers.get(hint.techniqueId);
+        if (!provider) {
+            return fail(`No explanation provider found for technique ${hint.techniqueId}`);
+        }
+        return provider.generateExplanations(hint, puzzle, state);
+    }
+    /**
+     * Gets a specific explanation at the requested level.
+     * @param hint - The hint to explain
+     * @param level - The desired explanation level
+     * @param state - The puzzle state context
+     * @returns Result containing the explanation at the specified level
+     */
+    getExplanationAtLevel(hint, level, puzzle, state) {
+        return this.getExplanations(hint, puzzle, state).onSuccess((explanations) => {
+            const explanation = explanations.find((exp) => exp.level === level);
+            return explanation
+                ? succeed(explanation)
+                : fail(`No explanation available at level ${level} for technique ${hint.techniqueId}`);
+        });
+    }
+}
+/**
+ * Utility class for formatting and displaying hint explanations.
+ * @public
+ */
+export class ExplanationFormatter {
+    /**
+     * Formats a hint explanation as a readable string.
+     * @param explanation - The explanation to format
+     * @param includeSteps - Whether to include step-by-step instructions
+     * @param includeTips - Whether to include tips
+     * @returns Formatted explanation string
+     */
+    static formatExplanation(explanation, includeSteps = true, includeTips = true) {
+        const sections = [];
+        // Title and description
+        sections.push(`${explanation.title}`);
+        sections.push(`${explanation.description}`);
+        // Steps
+        if (includeSteps && explanation.steps && explanation.steps.length > 0) {
+            sections.push('\nSteps:');
+            explanation.steps.forEach((step, index) => {
+                sections.push(`${index + 1}. ${step}`);
+            });
+        }
+        // Tips
+        if (includeTips && explanation.tips && explanation.tips.length > 0) {
+            sections.push('\nTips:');
+            explanation.tips.forEach((tip) => {
+                sections.push(`• ${tip}`);
+            });
+        }
+        return sections.join('\n');
+    }
+    /**
+     * Formats all explanations for a hint as a structured string.
+     * @param explanations - The explanations to format
+     * @returns Formatted explanations string
+     */
+    static formatAllExplanations(explanations) {
+        const sections = [];
+        for (const explanation of explanations) {
+            sections.push(`--- ${explanation.level.toUpperCase()} ---`);
+            sections.push(this.formatExplanation(explanation));
+            sections.push('');
+        }
+        return sections.join('\n');
+    }
+    /**
+     * Creates a summary of available explanation levels.
+     * @param explanations - The explanations to summarize
+     * @returns Summary string
+     */
+    static createLevelSummary(explanations) {
+        const levels = explanations.map((exp) => exp.level).join(', ');
+        return `Available explanation levels: ${levels}`;
+    }
+}
+/**
+ * Educational content manager for Sudoku solving techniques.
+ * @public
+ */
+export class EducationalContent {
+    /**
+     * Gets an introduction to a specific technique.
+     * @param techniqueId - The technique to introduce
+     * @returns Result containing the introduction text
+     */
+    static getTechniqueIntroduction(techniqueId) {
+        const introduction = this._techniqueIntroductions.get(techniqueId);
+        return introduction
+            ? succeed(introduction)
+            : fail(`No introduction available for technique ${techniqueId}`);
+    }
+    /**
+     * Gets relationship information for a technique.
+     * @param techniqueId - The technique to get relationships for
+     * @returns Result containing the relationship information
+     */
+    static getTechniqueRelationships(techniqueId) {
+        const relationships = this._techniqueRelationships.get(techniqueId);
+        return relationships
+            ? succeed(relationships)
+            : fail(`No relationship information available for technique ${techniqueId}`);
+    }
+    /**
+     * Gets a complete educational overview for a technique.
+     * @param techniqueId - The technique to describe
+     * @returns Result containing the complete overview
+     */
+    static getTechniqueOverview(techniqueId) {
+        const introduction = this.getTechniqueIntroduction(techniqueId);
+        const relationships = this.getTechniqueRelationships(techniqueId);
+        return introduction.onSuccess((intro) => {
+            return relationships.onSuccess((rels) => {
+                const sections = [intro, '', 'Technique Relationships:', ...rels.map((rel) => `• ${rel}`)];
+                return succeed(sections.join('\n'));
+            });
+        });
+    }
+    /**
+     * Gets general Sudoku solving advice.
+     * @returns Array of general solving tips
+     */
+    static getGeneralSolvingTips() {
+        return [
+            'Start with naked singles - they are always correct when found',
+            'After placing numbers, scan for new naked singles immediately',
+            'Check for hidden singles systematically in rows, columns, and boxes',
+            'Focus on units with many filled cells first',
+            'Keep track of candidates mentally or with pencil marks',
+            'Take breaks when stuck - fresh eyes often spot overlooked patterns',
+            'Practice pattern recognition to spot techniques more quickly'
+        ];
+    }
+    /**
+     * Gets difficulty progression advice.
+     * @returns Advice for progressing through difficulty levels
+     */
+    static getDifficultyProgression() {
+        return [
+            'Master naked singles and hidden singles completely before advancing',
+            'Beginner puzzles can often be solved with just these two techniques',
+            'Intermediate puzzles introduce pointing pairs and box/line interactions',
+            'Advanced puzzles require naked and hidden pairs/triples',
+            'Expert puzzles may need advanced techniques like X-wing and swordfish',
+            'Each technique builds on the foundation of simpler techniques'
+        ];
+    }
+    /**
+     * Creates a complete educational guide for beginners.
+     * @returns Comprehensive beginner guide
+     */
+    static createBeginnerGuide() {
+        const sections = [
+            'SUDOKU SOLVING GUIDE FOR BEGINNERS',
+            '='.repeat(35),
+            '',
+            'Sudoku is a logic puzzle where you fill a 9x9 grid with digits 1-9.',
+            'Each row, column, and 3x3 box must contain each digit exactly once.',
+            '',
+            'BASIC TECHNIQUES:',
+            '',
+            '1. Naked Singles',
+            this._techniqueIntroductions.get(TechniqueIds.NAKED_SINGLES),
+            '',
+            '2. Hidden Singles',
+            this._techniqueIntroductions.get(TechniqueIds.HIDDEN_SINGLES),
+            '',
+            'SOLVING STRATEGY:',
+            ...this.getGeneralSolvingTips().map((tip) => `• ${tip}`),
+            '',
+            'PROGRESSION:',
+            ...this.getDifficultyProgression().map((tip) => `• ${tip}`)
+        ];
+        return sections.join('\n');
+    }
+}
+EducationalContent._techniqueIntroductions = new Map([
+    [
+        TechniqueIds.NAKED_SINGLES,
+        'Naked Singles are the most fundamental Sudoku technique. When a cell has only one possible ' +
+            'value due to the numbers already placed in its row, column, and 3x3 box, that cell contains ' +
+            'a "naked single." This technique is always safe to apply and forms the foundation for more ' +
+            'advanced solving methods.'
+    ],
+    [
+        TechniqueIds.HIDDEN_SINGLES,
+        'Hidden Singles focus on finding where specific values must be placed within a unit (row, ' +
+            'column, or 3x3 box). When a particular number can only be placed in one cell within a unit, ' +
+            'that placement is a "hidden single." This technique complements naked singles and together ' +
+            'they can solve many easier puzzles completely.'
+    ]
+]);
+EducationalContent._techniqueRelationships = new Map([
+    [
+        TechniqueIds.NAKED_SINGLES,
+        [
+            'Apply naked singles first - they often reveal new naked singles',
+            'Naked singles may create hidden singles in related units',
+            'Use with hidden singles to solve beginner-level puzzles'
+        ]
+    ],
+    [
+        TechniqueIds.HIDDEN_SINGLES,
+        [
+            'Check for hidden singles after applying naked singles',
+            'Hidden singles can create new naked singles',
+            'Consider all three unit types: rows, columns, and boxes'
+        ]
+    ]
+]);
+//# sourceMappingURL=explanations.js.map

package/dist/packlets/hints/hiddenSingles.js

@@ -0,0 +1,233 @@
+/*
+ * 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 { BaseHintProvider } from './baseHintProvider';
+import { ConfidenceLevels, TechniqueIds } from './types';
+/**
+ * Hint provider for the Hidden Singles technique.
+ *
+ * A Hidden Single occurs when a value can only be placed in one cell within
+ * a row, column, or 3x3 box, even though that cell may have multiple candidates.
+ *
+ * @public
+ */
+export class HiddenSinglesProvider extends BaseHintProvider {
+    /**
+     * Creates a new HiddenSinglesProvider instance.
+     */
+    constructor() {
+        super({
+            techniqueId: TechniqueIds.HIDDEN_SINGLES,
+            techniqueName: 'Hidden Singles',
+            difficulty: 'beginner',
+            priority: 2, // Second priority after naked singles
+            defaultConfidence: ConfidenceLevels.HIGH
+        });
+    }
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if there are empty cells that might have hidden singles
+     */
+    canProvideHints(puzzle, state) {
+        const emptyCells = this.getEmptyCells(puzzle, state);
+        return emptyCells.length > 0;
+    }
+    /**
+     * Generates all hidden 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 hidden single hints
+     */
+    generateHints(puzzle, state, options) {
+        return this.validateOptions(options).onSuccess(() => {
+            const hints = [];
+            const hiddenSingles = this._findAllHiddenSingles(puzzle, state);
+            for (const hiddenSingle of hiddenSingles) {
+                const hint = this._createHiddenSingleHint(hiddenSingle, puzzle, state);
+                hints.push(hint);
+            }
+            return succeed(this.filterHints(hints, options));
+        });
+    }
+    /**
+     * Finds all hidden singles in the puzzle using cage-based analysis.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of hidden single information
+     */
+    _findAllHiddenSingles(puzzle, state) {
+        const hiddenSingles = [];
+        // Check all cages for hidden singles
+        for (const cage of puzzle.cages) {
+            hiddenSingles.push(...this._findHiddenSinglesInCage(cage, puzzle, state));
+        }
+        // Remove duplicates (a cell might be found as hidden single in multiple cages)
+        return this._removeDuplicateHiddenSingles(hiddenSingles);
+    }
+    /**
+     * Finds hidden singles in a specific cage using dynamic value analysis.
+     * @param cage - The cage to analyze
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of hidden singles in this cage
+     */
+    _findHiddenSinglesInCage(cage, puzzle, state) {
+        const hiddenSingles = [];
+        const maxValue = Math.sqrt(puzzle.numRows * puzzle.numColumns);
+        // For each possible value, check if it can only go in one cell in this cage
+        for (let value = 1; value <= maxValue; value++) {
+            const possibleCells = [];
+            for (const cellId of cage.cellIds) {
+                const candidates = this.getCandidates(cellId, puzzle, state);
+                if (candidates.includes(value)) {
+                    possibleCells.push(cellId);
+                }
+            }
+            // Hidden single: exactly one cell can contain this value
+            if (possibleCells.length === 1) {
+                const cellId = possibleCells[0];
+                const otherCandidateCells = cage.cellIds.filter((id) => id !== cellId && !state.hasValue(id));
+                hiddenSingles.push({
+                    cellId,
+                    value,
+                    unitType: cage.cageType,
+                    unitIndex: this._getCageDisplayIndex(cage),
+                    otherCandidateCells
+                });
+            }
+        }
+        return hiddenSingles;
+    }
+    /**
+     * Gets a display-friendly index for a cage.
+     * @param cage - The cage to get index for
+     * @returns Display index for the cage
+     */
+    _getCageDisplayIndex(cage) {
+        // Extract numeric part from cage ID if available
+        const match = cage.id.match(/\d+/);
+        return match ? parseInt(match[0], 10) : 0;
+    }
+    /**
+     * Removes duplicate hidden singles (same cell and value).
+     * @param hiddenSingles - Array of potentially duplicate hidden singles
+     * @returns Array with duplicates removed
+     */
+    _removeDuplicateHiddenSingles(hiddenSingles) {
+        const seen = new Set();
+        const unique = [];
+        for (const hiddenSingle of hiddenSingles) {
+            const key = `${hiddenSingle.cellId}-${hiddenSingle.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                unique.push(hiddenSingle);
+            }
+        }
+        return unique;
+    }
+    /**
+     * Creates a hint for a specific hidden single.
+     * @param hiddenSingle - The hidden single information
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns A complete hint for this hidden single
+     */
+    _createHiddenSingleHint(hiddenSingle, __puzzle, __state) {
+        const { cellId, value, unitType, unitIndex } = hiddenSingle;
+        // Create cell action to set the value
+        const cellAction = this.createCellAction(cellId, 'set-value', value, `Only cell in ${unitType} ${unitIndex} that can contain ${value}`);
+        // Create relevant cells grouping
+        const relevantCells = this.createRelevantCells([cellId], // Primary: the cell with the hidden single
+        hiddenSingle.otherCandidateCells, // Secondary: other empty cells in the unit
+        [] // Affected: none for hidden singles
+        );
+        // Create explanations at different levels
+        const unitName = this._getUnitName(unitType, unitIndex);
+        const explanations = [
+            this.createExplanation('brief', 'Hidden Single', `In ${unitName}, the value ${value} can only go in cell ${cellId}.`, [`Set ${cellId} = ${value}`], ['Look for values that can only go in one cell within a unit']),
+            this.createExplanation('detailed', 'Hidden Single Analysis', `In ${unitName}, the value ${value} can only be placed in cell ${cellId}. While this cell ` +
+                `may have other candidates, ${value} has no other valid positions in this ${unitType}.`, [
+                `Examine all empty cells in ${unitName}`,
+                `For each empty cell, determine which values are possible candidates`,
+                `Check where the value ${value} can be placed`,
+                `Identify that ${value} can only go in ${cellId}`,
+                `Set ${cellId} = ${value}`
+            ], [
+                'Hidden singles focus on where a value can go, not what can go in a cell',
+                'Check each value 1-9 systematically within each unit',
+                'A value with only one possible position must go there'
+            ]),
+            this.createExplanation('educational', 'Understanding Hidden Singles', `A hidden single occurs when a particular value can only be placed in one cell within a ` +
+                `row, column, or 3x3 box. In ${unitName}, we need to place the value ${value} somewhere, ` +
+                `but due to constraints from other filled cells, it can only go in ${cellId}. This technique ` +
+                `is called "hidden" because the single placement might not be obvious when looking at the ` +
+                `cell's candidates alone - you need to consider the entire unit.`, [
+                `Focus on ${unitName}`,
+                `Identify that this unit needs the value ${value} to be placed somewhere`,
+                `Examine each empty cell in this ${unitType} to see if ${value} could be placed there`,
+                `Consider the constraints from the cell's row, column, and box`,
+                `Eliminate cells where ${value} cannot go due to conflicts`,
+                `Confirm that ${cellId} is the only remaining option for ${value}`,
+                `Place ${value} in cell ${cellId}`
+            ], [
+                'Hidden singles complement naked singles - use both techniques together',
+                'Systematically check each value 1-9 in each row, column, and box',
+                'This technique often reveals itself after placing other numbers',
+                'Hidden singles can exist even when a cell has many candidates'
+            ])
+        ];
+        return this.createHint([cellAction], relevantCells, explanations, ConfidenceLevels.HIGH);
+    }
+    /**
+     * Gets a human-readable name for a unit.
+     * @param unitType - The type of unit
+     * @param unitIndex - The index of the unit
+     * @returns Human-readable unit name
+     */
+    _getUnitName(unitType, unitIndex) {
+        switch (unitType) {
+            case 'row':
+                return `row ${unitIndex + 1}`;
+            case 'column':
+                return `column ${unitIndex + 1}`;
+            /* c8 ignore next 4 - unreachable: puzzles use 'section' cage type, not 'box' */
+            case 'box':
+                const boxRow = Math.floor(unitIndex / 3);
+                const boxCol = unitIndex % 3;
+                return `box (${boxRow + 1},${boxCol + 1})`;
+        }
+        return `${unitType} ${unitIndex}`;
+    }
+    /**
+     * Static factory method to create a new HiddenSinglesProvider.
+     * @returns Result containing the new provider
+     */
+    static create() {
+        return succeed(new HiddenSinglesProvider());
+    }
+}
+//# sourceMappingURL=hiddenSingles.js.map