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

package/dist/packlets/hints/hintRegistry.js

@@ -0,0 +1,222 @@
+/*
+ * 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, mapResults } from '@fgv/ts-utils';
+/**
+ * Implementation of the hint registry that manages and coordinates multiple hint providers.
+ * @public
+ */
+export class HintRegistry {
+    /**
+     * Creates a new HintRegistry instance.
+     */
+    constructor() {
+        this._providers = new Map();
+    }
+    /**
+     * Creates a new HintRegistry with the specified providers pre-registered.
+     * @param providers - The providers to register
+     * @returns Result containing the new registry or failure if registration fails
+     */
+    static create(providers) {
+        const registry = new HintRegistry();
+        if (providers && providers.length > 0) {
+            for (const provider of providers) {
+                const result = registry.registerProvider(provider);
+                if (result.isFailure()) {
+                    return fail(`Failed to register provider ${provider.techniqueId}: ${result.message}`);
+                }
+            }
+        }
+        return succeed(registry);
+    }
+    /**
+     * Registers a new hint 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(`Provider for technique ${provider.techniqueId} is already registered`);
+        }
+        this._providers.set(provider.techniqueId, provider);
+        return succeed(undefined);
+    }
+    /**
+     * Unregisters a hint provider.
+     * @param techniqueId - The ID of the technique to unregister
+     * @returns Result indicating success or failure of unregistration
+     */
+    unregisterProvider(techniqueId) {
+        if (!this._providers.has(techniqueId)) {
+            return fail(`No provider registered for technique ${techniqueId}`);
+        }
+        this._providers.delete(techniqueId);
+        return succeed(undefined);
+    }
+    /**
+     * 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) {
+        const provider = this._providers.get(techniqueId);
+        return provider ? succeed(provider) : fail(`No provider found for technique ${techniqueId}`);
+    }
+    /**
+     * Gets all registered providers, optionally filtered by criteria.
+     * @param options - Optional filtering options
+     * @returns Array of providers matching the criteria
+     */
+    getProviders(options) {
+        const providers = Array.from(this._providers.values());
+        if (!options) {
+            return providers;
+        }
+        let filtered = providers;
+        // Filter by enabled techniques
+        if (options.enabledTechniques && options.enabledTechniques.length > 0) {
+            filtered = filtered.filter((provider) => options.enabledTechniques.includes(provider.techniqueId));
+        }
+        // Filter by preferred difficulty (exact match for now)
+        if (options.preferredDifficulty) {
+            filtered = filtered.filter((provider) => provider.difficulty === options.preferredDifficulty);
+        }
+        return filtered;
+    }
+    /**
+     * 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, state, options) {
+        const applicableProviders = this.getProviders(options).filter((provider) => provider.canProvideHints(puzzle, state));
+        if (applicableProviders.length === 0) {
+            return succeed([]);
+        }
+        // Generate hints from all applicable providers
+        const hintResults = applicableProviders.map((provider) => provider.generateHints(puzzle, state, options));
+        return mapResults(hintResults).onSuccess((allHints) => {
+            // Flatten the array of hint arrays
+            const flatHints = allHints.flat();
+            // Sort by priority (ascending) then confidence (descending)
+            const sortedHints = flatHints.sort((a, b) => {
+                if (a.priority !== b.priority) {
+                    return a.priority - b.priority;
+                }
+                return b.confidence - a.confidence;
+            });
+            // Apply global filtering options
+            return this._applyGlobalFiltering(sortedHints, options);
+        });
+    }
+    /**
+     * 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, state, options) {
+        return this.generateAllHints(puzzle, state, options).onSuccess((hints) => {
+            if (hints.length === 0) {
+                return fail('No hints available for the current puzzle state');
+            }
+            // Return the first hint (already sorted by priority and confidence)
+            return succeed(hints[0]);
+        });
+    }
+    /**
+     * Gets the number of registered providers.
+     * @returns The number of registered providers
+     */
+    get providerCount() {
+        return this._providers.size;
+    }
+    /**
+     * Gets all registered technique IDs.
+     * @returns Array of technique IDs
+     */
+    getRegisteredTechniques() {
+        return Array.from(this._providers.keys());
+    }
+    /**
+     * Checks if a specific technique is registered.
+     * @param techniqueId - The technique ID to check
+     * @returns true if the technique is registered
+     */
+    hasProvider(techniqueId) {
+        return this._providers.has(techniqueId);
+    }
+    /**
+     * Clears all registered providers.
+     * @returns Result indicating success
+     */
+    clear() {
+        this._providers.clear();
+        return succeed(undefined);
+    }
+    /**
+     * Gets providers grouped by difficulty level.
+     * @returns Map of difficulty levels to providers
+     */
+    getProvidersByDifficulty() {
+        var _a;
+        const providersByDifficulty = new Map();
+        for (const provider of this._providers.values()) {
+            const existing = (_a = providersByDifficulty.get(provider.difficulty)) !== null && _a !== void 0 ? _a : [];
+            existing.push(provider);
+            providersByDifficulty.set(provider.difficulty, existing);
+        }
+        // Convert to readonly arrays
+        const result = new Map();
+        for (const [difficulty, providers] of providersByDifficulty.entries()) {
+            result.set(difficulty, providers);
+        }
+        return result;
+    }
+    /**
+     * Applies global filtering options to the collected hints.
+     * @param hints - The hints to filter
+     * @param options - The filtering options
+     * @returns Result containing the filtered hints
+     */
+    _applyGlobalFiltering(hints, options) {
+        if (!options) {
+            return succeed(hints);
+        }
+        let filtered = [...hints];
+        // Apply minimum confidence filter
+        if (options.minConfidence) {
+            filtered = filtered.filter((hint) => hint.confidence >= options.minConfidence);
+        }
+        // Apply maximum hints limit
+        if (options.maxHints && options.maxHints > 0 && filtered.length > options.maxHints) {
+            filtered = filtered.slice(0, options.maxHints);
+        }
+        return succeed(filtered);
+    }
+}
+//# sourceMappingURL=hintRegistry.js.map

package/dist/packlets/hints/hints.js

@@ -0,0 +1,311 @@
+/*
+ * 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, mapResults } from '@fgv/ts-utils';
+import { DefaultSudokuLogger } from '../common';
+import { ExplanationFormatter } from './explanations';
+import { HintRegistry } from './hintRegistry';
+import { HiddenSinglesProvider } from './hiddenSingles';
+import { NakedSinglesProvider } from './nakedSingles';
+/**
+ * Default hint applicator that converts hints to cell state updates.
+ * @public
+ */
+export class DefaultHintApplicator {
+    /**
+     * Creates a new {@link Hints.DefaultHintApplicator | DefaultHintApplicator}.
+     * @param logger - Optional logger for diagnostic output
+     */
+    constructor(logger) {
+        /* c8 ignore next 1 - defense in depth */
+        this._log = logger !== null && logger !== void 0 ? logger : DefaultSudokuLogger;
+    }
+    /**
+     * 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, puzzle, state) {
+        const maxValue = Math.sqrt(puzzle.numRows * puzzle.numColumns);
+        // Validate all cell actions
+        const validations = hint.cellActions.map((action) => {
+            // Only support set-value actions for now
+            if (action.action !== 'set-value') {
+                return fail(`Unsupported action type: ${action.action}`);
+            }
+            // Validate the value to be set
+            if (action.value === undefined) {
+                return fail(`No value specified for set-value action on cell ${action.cellId}`);
+            }
+            if (action.value < 1 || action.value > maxValue) {
+                return fail(`Invalid value ${action.value} for cell ${action.cellId} (must be 1-${maxValue})`);
+            }
+            // Check that the cell exists and is empty
+            return state
+                .getCellContents(action.cellId)
+                .withErrorFormat((e) => `Invalid cell ${action.cellId}: ${e}`)
+                .onSuccess((cellContents) => {
+                if (cellContents.value !== undefined) {
+                    return fail(`Cell ${action.cellId} already has value ${cellContents.value}`);
+                }
+                return succeed(undefined);
+            });
+        });
+        return mapResults(validations).onSuccess(() => succeed(undefined));
+    }
+    /**
+     * 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, puzzle, state) {
+        this._log.detail(`Applying hint: ${hint.techniqueName} affecting ${hint.cellActions.length} cell(s)`);
+        return this.canApplyHint(hint, puzzle, state).onSuccess(() => {
+            const updates = [];
+            for (const action of hint.cellActions) {
+                if (action.action === 'set-value' && action.value !== undefined) {
+                    // Get current cell contents to preserve notes
+                    const cellResult = state.getCellContents(action.cellId);
+                    /* c8 ignore next 3 - internal error should never happen in practice */
+                    if (cellResult.isFailure()) {
+                        return fail(`Failed to get cell contents: ${cellResult.message}`);
+                    }
+                    updates.push({
+                        id: action.cellId,
+                        value: action.value,
+                        notes: cellResult.value.notes // Preserve existing notes
+                    });
+                }
+            }
+            this._log.info(`Successfully applied hint: ${hint.techniqueName}, updated ${updates.length} cell(s)`);
+            return succeed(updates);
+        });
+    }
+}
+/**
+ * Main hint system that provides comprehensive hint generation and management.
+ * @public
+ */
+export class HintSystem {
+    /**
+     * Creates a new HintSystem instance.
+     * @param registry - The hint registry to use
+     * @param applicator - The hint applicator to use
+     * @param config - Configuration options
+     */
+    constructor(registry, applicator, config) {
+        var _a;
+        this._registry = registry;
+        this._applicator = applicator;
+        this._config = config;
+        this._log = (_a = config.logger) !== null && _a !== void 0 ? _a : DefaultSudokuLogger;
+        this._logHints = this._log.withValueFormatter((hints) => `Generated ${hints.length} hint(s) using ${new Set(hints.map((h) => h.techniqueId)).size} technique(s)`);
+    }
+    /**
+     * Creates a new HintSystem with default providers and configuration.
+     * @param config - Optional configuration options
+     * @returns Result containing the new hint system
+     */
+    static create(config) {
+        const finalConfig = Object.assign({ enableNakedSingles: true, enableHiddenSingles: true, defaultExplanationLevel: 'detailed' }, config);
+        return HintRegistry.create()
+            .withErrorFormat((e) => `Failed to create hint registry: ${e}`)
+            .onSuccess((registry) => {
+            // Register naked singles provider if enabled
+            if (finalConfig.enableNakedSingles) {
+                const nakedResult = NakedSinglesProvider.create()
+                    .withErrorFormat((e) => `Failed to create naked singles provider: ${e}`)
+                    .onSuccess((provider) => registry.registerProvider(provider))
+                    .withErrorFormat((e) => `Failed to register naked singles provider: ${e}`);
+                /* c8 ignore next 3 - defensive coding: provider creation/registration should not fail */
+                if (nakedResult.isFailure()) {
+                    return fail(nakedResult.message);
+                }
+            }
+            // Register hidden singles provider if enabled
+            if (finalConfig.enableHiddenSingles) {
+                const hiddenResult = HiddenSinglesProvider.create()
+                    .withErrorFormat((e) => `Failed to create hidden singles provider: ${e}`)
+                    .onSuccess((provider) => registry.registerProvider(provider))
+                    .withErrorFormat((e) => `Failed to register hidden singles provider: ${e}`);
+                /* c8 ignore next 3 - defensive coding: provider creation/registration should not fail */
+                if (hiddenResult.isFailure()) {
+                    return fail(hiddenResult.message);
+                }
+            }
+            // Create applicator and return complete system
+            const applicator = new DefaultHintApplicator(finalConfig.logger);
+            return succeed(new HintSystem(registry, applicator, finalConfig));
+        });
+    }
+    /**
+     * Gets the hint registry.
+     * @returns The hint registry
+     */
+    get registry() {
+        return this._registry;
+    }
+    /**
+     * Gets the hint applicator.
+     * @returns The hint applicator
+     */
+    get applicator() {
+        return this._applicator;
+    }
+    /**
+     * Gets the system configuration.
+     * @returns The configuration
+     */
+    get config() {
+        return this._config;
+    }
+    /**
+     * Generates all available hints for the current puzzle state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints
+     */
+    generateHints(puzzle, state, options) {
+        this._log.detail('Generating hints for puzzle state');
+        return this._registry.generateAllHints(puzzle, state, options).report(this._logHints, {
+            success: { level: 'info' },
+            failure: {
+                level: 'warning',
+                message: (msg) => `Failed to generate hints: ${msg}`
+            }
+        });
+    }
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing the best hint
+     */
+    getBestHint(puzzle, state, options) {
+        return this._registry.getBestHint(puzzle, state, options);
+    }
+    /**
+     * Applies a hint to generate cell state 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 updates
+     */
+    applyHint(hint, puzzle, state) {
+        return this._applicator.applyHint(hint, puzzle, state);
+    }
+    /**
+     * Validates that a hint can be applied to the current 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
+     */
+    validateHint(hint, puzzle, state) {
+        return this._applicator.canApplyHint(hint, puzzle, state);
+    }
+    /**
+     * Formats a hint explanation for display.
+     * @param hint - The hint to format
+     * @param level - The explanation level to use (defaults to config default)
+     * @returns Formatted explanation string
+     */
+    formatHintExplanation(hint, level) {
+        var _a;
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const explanationLevel = (_a = level !== null && level !== void 0 ? level : this._config.defaultExplanationLevel) !== null && _a !== void 0 ? _a : 'detailed';
+        const explanation = hint.explanations.find((exp) => exp.level === explanationLevel);
+        if (!explanation) {
+            return `No explanation available at level ${explanationLevel} for ${hint.techniqueName}`;
+        }
+        return ExplanationFormatter.formatExplanation(explanation);
+    }
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary() {
+        var _a;
+        const techniques = this._registry.getRegisteredTechniques();
+        const techniqueNames = techniques.map((id) => {
+            const provider = this._registry.getProvider(id);
+            /* c8 ignore next 1 - fallback to id should not happen in practice */
+            return provider.isSuccess() ? provider.value.techniqueName : id;
+        });
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const defaultExplanationLevel = (_a = this._config.defaultExplanationLevel) !== null && _a !== void 0 ? _a : 'detailed';
+        return [
+            'Sudoku Hint System',
+            '='.repeat(20),
+            `Registered Techniques: ${techniques.length}`,
+            ...techniqueNames.map((name) => `• ${name}`),
+            '',
+            `Default Explanation Level: ${defaultExplanationLevel}`
+        ].join('\n');
+    }
+    /**
+     * Checks if the puzzle state has any available hints.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing boolean indicating if hints are available
+     */
+    hasHints(puzzle, state) {
+        return this.generateHints(puzzle, state, { maxHints: 1 }).onSuccess((hints) => {
+            return succeed(hints.length > 0);
+        });
+    }
+    /**
+     * Gets statistics about available hints for the current state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(puzzle, state) {
+        return this.generateHints(puzzle, state).onSuccess((hints) => {
+            var _a, _b;
+            const hintsByTechnique = new Map();
+            const hintsByDifficulty = new Map();
+            for (const hint of hints) {
+                // Count by technique
+                /* c8 ignore next 1 - ?? is defense in depth */
+                const techniqueCount = (_a = hintsByTechnique.get(hint.techniqueName)) !== null && _a !== void 0 ? _a : 0;
+                hintsByTechnique.set(hint.techniqueName, techniqueCount + 1);
+                // Count by difficulty
+                const difficultyCount = (_b = hintsByDifficulty.get(hint.difficulty)) !== null && _b !== void 0 ? _b : 0;
+                hintsByDifficulty.set(hint.difficulty, difficultyCount + 1);
+            }
+            return succeed({
+                totalHints: hints.length,
+                hintsByTechnique,
+                hintsByDifficulty
+            });
+        });
+    }
+}
+//# sourceMappingURL=hints.js.map

package/dist/packlets/hints/index.js

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+// Core types and interfaces
+export * from './types';
+export * from './interfaces';
+// Base classes and utilities
+export * from './baseHintProvider';
+export * from './hintRegistry';
+// Technique implementations
+export * from './nakedSingles';
+export * from './hiddenSingles';
+// Educational framework
+export * from './explanations';
+// Main hint system
+export * from './hints';
+// PuzzleSession integration
+export * from './puzzleSessionHints';
+//# sourceMappingURL=index.js.map

package/dist/packlets/hints/interfaces.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=interfaces.js.map