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

package/lib/packlets/hints/hintRegistry.js

@@ -0,0 +1,226 @@
+"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.HintRegistry = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Implementation of the hint registry that manages and coordinates multiple hint providers.
+ * @public
+ */
+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 (0, ts_utils_1.fail)(`Failed to register provider ${provider.techniqueId}: ${result.message}`);
+                }
+            }
+        }
+        return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Provider for technique ${provider.techniqueId} is already registered`);
+        }
+        this._providers.set(provider.techniqueId, provider);
+        return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`No provider registered for technique ${techniqueId}`);
+        }
+        this._providers.delete(techniqueId);
+        return (0, ts_utils_1.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 ? (0, ts_utils_1.succeed)(provider) : (0, ts_utils_1.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 (0, ts_utils_1.succeed)([]);
+        }
+        // Generate hints from all applicable providers
+        const hintResults = applicableProviders.map((provider) => provider.generateHints(puzzle, state, options));
+        return (0, ts_utils_1.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 (0, ts_utils_1.fail)('No hints available for the current puzzle state');
+            }
+            // Return the first hint (already sorted by priority and confidence)
+            return (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.succeed)(filtered);
+    }
+}
+exports.HintRegistry = HintRegistry;
+//# sourceMappingURL=hintRegistry.js.map

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

@@ -0,0 +1,144 @@
+import { Result, Logging } from '@fgv/ts-utils';
+import { ICellState, Puzzle, PuzzleState } from '../common';
+import { IHintApplicator, IHintRegistry } from './interfaces';
+import { ExplanationLevel, IHint, IHintGenerationOptions } from './types';
+/**
+ * Configuration options for the hint system.
+ * @public
+ */
+export interface IHintSystemConfig {
+    readonly enableNakedSingles?: boolean;
+    readonly enableHiddenSingles?: boolean;
+    readonly defaultExplanationLevel?: ExplanationLevel;
+    readonly logger?: Logging.LogReporter<unknown>;
+}
+/**
+ * Default hint applicator that converts hints to cell state updates.
+ * @public
+ */
+export declare class DefaultHintApplicator implements IHintApplicator {
+    private readonly _log;
+    /**
+     * Creates a new {@link Hints.DefaultHintApplicator | DefaultHintApplicator}.
+     * @param logger - Optional logger for diagnostic output
+     */
+    constructor(logger?: Logging.LogReporter<unknown>);
+    /**
+     * 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[]>;
+}
+/**
+ * Main hint system that provides comprehensive hint generation and management.
+ * @public
+ */
+export declare class HintSystem {
+    private readonly _registry;
+    private readonly _applicator;
+    private readonly _config;
+    private readonly _log;
+    private readonly _logHints;
+    /**
+     * 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: IHintRegistry, applicator: IHintApplicator, config: IHintSystemConfig);
+    /**
+     * Creates a new HintSystem with default providers and configuration.
+     * @param config - Optional configuration options
+     * @returns Result containing the new hint system
+     */
+    static create(config?: IHintSystemConfig): Result<HintSystem>;
+    /**
+     * Gets the hint registry.
+     * @returns The hint registry
+     */
+    get registry(): IHintRegistry;
+    /**
+     * Gets the hint applicator.
+     * @returns The hint applicator
+     */
+    get applicator(): IHintApplicator;
+    /**
+     * Gets the system configuration.
+     * @returns The configuration
+     */
+    get config(): IHintSystemConfig;
+    /**
+     * 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: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * 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: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * 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: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly ICellState[]>;
+    /**
+     * 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: IHint, puzzle: Puzzle, state: PuzzleState): Result<void>;
+    /**
+     * 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: IHint, level?: ExplanationLevel): string;
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary(): string;
+    /**
+     * 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: Puzzle, state: PuzzleState): Result<boolean>;
+    /**
+     * 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: Puzzle, state: PuzzleState): Result<{
+        totalHints: number;
+        hintsByTechnique: Map<string, number>;
+        hintsByDifficulty: Map<string, number>;
+    }>;
+}
+//# sourceMappingURL=hints.d.ts.map

package/lib/packlets/hints/hints.js

@@ -0,0 +1,316 @@
+"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.HintSystem = exports.DefaultHintApplicator = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const explanations_1 = require("./explanations");
+const hintRegistry_1 = require("./hintRegistry");
+const hiddenSingles_1 = require("./hiddenSingles");
+const nakedSingles_1 = require("./nakedSingles");
+/**
+ * Default hint applicator that converts hints to cell state updates.
+ * @public
+ */
+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 : common_1.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 (0, ts_utils_1.fail)(`Unsupported action type: ${action.action}`);
+            }
+            // Validate the value to be set
+            if (action.value === undefined) {
+                return (0, ts_utils_1.fail)(`No value specified for set-value action on cell ${action.cellId}`);
+            }
+            if (action.value < 1 || action.value > maxValue) {
+                return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Cell ${action.cellId} already has value ${cellContents.value}`);
+                }
+                return (0, ts_utils_1.succeed)(undefined);
+            });
+        });
+        return (0, ts_utils_1.mapResults)(validations).onSuccess(() => (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.succeed)(updates);
+        });
+    }
+}
+exports.DefaultHintApplicator = DefaultHintApplicator;
+/**
+ * Main hint system that provides comprehensive hint generation and management.
+ * @public
+ */
+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 : common_1.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_1.HintRegistry.create()
+            .withErrorFormat((e) => `Failed to create hint registry: ${e}`)
+            .onSuccess((registry) => {
+            // Register naked singles provider if enabled
+            if (finalConfig.enableNakedSingles) {
+                const nakedResult = nakedSingles_1.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 (0, ts_utils_1.fail)(nakedResult.message);
+                }
+            }
+            // Register hidden singles provider if enabled
+            if (finalConfig.enableHiddenSingles) {
+                const hiddenResult = hiddenSingles_1.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 (0, ts_utils_1.fail)(hiddenResult.message);
+                }
+            }
+            // Create applicator and return complete system
+            const applicator = new DefaultHintApplicator(finalConfig.logger);
+            return (0, ts_utils_1.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 explanations_1.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 (0, ts_utils_1.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 (0, ts_utils_1.succeed)({
+                totalHints: hints.length,
+                hintsByTechnique,
+                hintsByDifficulty
+            });
+        });
+    }
+}
+exports.HintSystem = HintSystem;
+//# sourceMappingURL=hints.js.map