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

package/dist/packlets/puzzles/killerCombinations.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 } from '@fgv/ts-utils';
+import { getCageTotalBounds } from '../common';
+import { CombinationCache } from './internal/combinationCache';
+import { CombinationGenerator } from './internal/combinationGenerator';
+import { PossibilityAnalyzer } from './internal/possibilityAnalyzer';
+/**
+ * Helper class providing UI assistance functions for killer sudoku puzzle solving.
+ * Generates possible totals, number combinations with constraints, and cell-specific
+ * possibilities based on current puzzle state.
+ * @public
+ */
+export class KillerCombinations {
+    /**
+     * Gets all mathematically possible totals for a given cage size.
+     *
+     * Uses the existing totalsByCageSize constant to determine the valid range
+     * of totals for the specified cage size and returns all integers in that range.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @returns Result containing array of possible totals in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get possible totals for a 3-cell cage
+     * const result = KillerCombinations.getPossibleTotals(3);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [6, 7, 8, 9, ..., 24]
+     * }
+     * ```
+     */
+    static getPossibleTotals(cageSize, maxValue = 9) {
+        // Validate cage size
+        if (!Number.isInteger(cageSize) || cageSize < 1 || cageSize > maxValue) {
+            return fail(`Cage size must be an integer between 1 and ${maxValue}, got ${cageSize}`);
+        }
+        const bounds = getCageTotalBounds(cageSize, maxValue);
+        // Generate all totals in the valid range
+        const totals = [];
+        for (let total = bounds.min; total <= bounds.max; total++) {
+            totals.push(total);
+        }
+        return succeed(totals);
+    }
+    /**
+     * Generates all possible number combinations that sum to the target total.
+     *
+     * Each combination contains unique numbers from 1-9 that sum exactly to the
+     * specified total. Combinations respect both excluded and required number
+     * constraints if provided.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @param total - The target sum (must be valid for the cage size)
+     * @param constraints - Optional constraints on included/excluded numbers
+     * @returns Result containing array of combinations, each sorted in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get all combinations for a 3-cell cage with total 15
+     * const result = KillerCombinations.getCombinations(3, 15);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [[1,5,9], [1,6,8], [2,4,9], ...]
+     * }
+     *
+     * // With constraints - exclude 1 and 2, require 9
+     * const constrained = KillerCombinations.getCombinations(3, 15, {
+     *   excludedNumbers: [1, 2],
+     *   requiredNumbers: [9]
+     * });
+     * ```
+     */
+    static getCombinations(cageSize, total, constraints, maxValue = 9) {
+        // Validate cage size
+        if (!Number.isInteger(cageSize) || cageSize < 1 || cageSize > maxValue) {
+            return fail(`Cage size must be an integer between 1 and ${maxValue}, got ${cageSize}`);
+        }
+        // Validate total against cage size bounds
+        const bounds = getCageTotalBounds(cageSize, maxValue);
+        if (!Number.isInteger(total) || total < bounds.min || total > bounds.max) {
+            return fail(`Total ${total} is invalid for cage size ${cageSize} - valid range: ${bounds.min}-${bounds.max}`);
+        }
+        // Validate constraints
+        const constraintValidation = this._validateConstraints(constraints, maxValue);
+        if (constraintValidation.isFailure()) {
+            return fail(constraintValidation.message);
+        }
+        // Check cache first
+        const cacheKey = CombinationCache.generateKey(cageSize, total, constraints);
+        const cached = CombinationCache.get(cacheKey);
+        if (cached) {
+            return succeed(cached);
+        }
+        // Generate combinations
+        const combinations = CombinationGenerator.generate(cageSize, total, constraints, maxValue);
+        // Cache the result
+        CombinationCache.set(cacheKey, combinations);
+        return succeed(combinations);
+    }
+    /**
+     * Determines possible values for each cell in a killer cage based on current puzzle state.
+     *
+     * Analyzes the current state of the puzzle and cage to determine which values
+     * are possible for each empty cell, considering both killer cage constraints
+     * and standard sudoku constraints (row, column, section uniqueness).
+     *
+     * @param puzzle - The puzzle instance
+     * @param state - Current puzzle state
+     * @param cage - The killer cage to analyze (must be of type 'killer')
+     * @returns Result containing map of CellId to possible number arrays
+     *
+     * @example
+     * ```typescript
+     * const cage = puzzle.getCage(cageId).orThrow();
+     * const possibilities = KillerCombinations.getCellPossibilities(puzzle, state, cage);
+     * if (possibilities.isSuccess()) {
+     *   for (const [cellId, values] of possibilities.value) {
+     *     console.log(`Cell ${cellId} can have values: ${values.join(', ')}`);
+     *   }
+     * }
+     * ```
+     */
+    static getCellPossibilities(puzzle, state, cage) {
+        // Validate cage type
+        if (cage.cageType !== 'killer') {
+            return fail(`Expected killer cage, got ${cage.cageType}`);
+        }
+        // Get current values in the cage to build constraints
+        // We need the concrete Cage class for containedValues method
+        const concreteCage = cage;
+        const currentValues = concreteCage.containedValues(state);
+        const constraints = {
+            excludedNumbers: Array.from(currentValues)
+        };
+        // Get valid combinations for this cage
+        const combinationsResult = this.getCombinations(cage.numCells, cage.total, constraints);
+        /* c8 ignore next 3 - error propagation from getCombinations already tested, integration error hard to trigger */
+        if (combinationsResult.isFailure()) {
+            return fail(`Failed to get combinations for cage ${cage.id}: ${combinationsResult.message}`);
+        }
+        // Analyze possibilities for each cell
+        return PossibilityAnalyzer.analyze(puzzle, state, cage, combinationsResult.value);
+    }
+    /**
+     * Validate constraint parameters.
+     * @param constraints - Constraints to validate
+     * @param maxValue - Maximum value allowed in cells
+     * @returns Result indicating success or failure with error message
+     */
+    static _validateConstraints(constraints, maxValue = 9) {
+        if (!constraints) {
+            return succeed(true);
+        }
+        // Validate excluded numbers
+        if (constraints.excludedNumbers) {
+            const excluded = constraints.excludedNumbers;
+            if (!Array.isArray(excluded)) {
+                return fail('excludedNumbers must be an array');
+            }
+            for (const num of excluded) {
+                if (!Number.isInteger(num) || num < 1 || num > maxValue) {
+                    return fail(`excludedNumbers must contain integers between 1-${maxValue}, got ${num}`);
+                }
+            }
+            // Check for duplicates
+            const uniqueExcluded = new Set(excluded);
+            if (uniqueExcluded.size !== excluded.length) {
+                return fail('excludedNumbers must not contain duplicates');
+            }
+        }
+        // Validate required numbers
+        if (constraints.requiredNumbers) {
+            const required = constraints.requiredNumbers;
+            if (!Array.isArray(required)) {
+                return fail('requiredNumbers must be an array');
+            }
+            for (const num of required) {
+                if (!Number.isInteger(num) || num < 1 || num > maxValue) {
+                    return fail(`requiredNumbers must contain integers between 1-${maxValue}, got ${num}`);
+                }
+            }
+            // Check for duplicates
+            const uniqueRequired = new Set(required);
+            if (uniqueRequired.size !== required.length) {
+                return fail('requiredNumbers must not contain duplicates');
+            }
+        }
+        // Check for overlap between excluded and required
+        if (constraints.excludedNumbers && constraints.requiredNumbers) {
+            const excludedSet = new Set(constraints.excludedNumbers);
+            const requiredSet = new Set(constraints.requiredNumbers);
+            for (const required of requiredSet) {
+                if (excludedSet.has(required)) {
+                    return fail(`Number ${required} cannot be both required and excluded`);
+                }
+            }
+        }
+        return succeed(true);
+    }
+}
+//# sourceMappingURL=killerCombinations.js.map

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

package/dist/packlets/puzzles/killerSudokuPuzzle.js

@@ -0,0 +1,136 @@
+/*
+ * 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 { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { Cage, Ids, Puzzle, getCageTotalBounds } from '../common';
+const cageDefFormat = /^[A-Za-z][0-9][0-9]$/;
+/**
+ * @public
+ */
+export class KillerSudokuPuzzle extends Puzzle {
+    constructor(puzzle, cages) {
+        super(puzzle, cages);
+    }
+    static create(desc) {
+        /* c8 ignore next 3 */
+        if (desc.type !== 'killer-sudoku') {
+            return fail(`Puzzle '${desc.description}' unsupported type ${desc.type}`);
+        }
+        return captureResult(() => {
+            const { cages, givens } = KillerSudokuPuzzle._getKillerCages(desc);
+            const cells = KillerSudokuPuzzle._getKillerCells(desc, givens);
+            return new KillerSudokuPuzzle(Object.assign(Object.assign({}, desc), { cells }), cages);
+        })
+            .onSuccess((puzzle) => {
+            return succeed(puzzle);
+        })
+            .onFailure((message) => {
+            return fail(`Failed to load killer puzzle "${desc.description}" - ${message}`);
+        });
+    }
+    static _getKillerCages(puzzle) {
+        const decl = puzzle.cells.split('|');
+        /* c8 ignore next 3 - tested but coverage has intermittent issues */
+        if (decl.length !== 2) {
+            throw new Error(`malformed cells|cages "${puzzle.cells}"`);
+        }
+        const cageCells = KillerSudokuPuzzle._getCageCells(puzzle, decl[0]);
+        const allCages = KillerSudokuPuzzle._getCages(puzzle, cageCells, decl[1]);
+        const cages = allCages.filter(([__id, cage]) => cage.numCells > 1);
+        const givens = allCages.filter(([__id, cage]) => cage.numCells === 1).map(([__id, cage]) => cage);
+        return { cages, givens };
+    }
+    static _getCageCells(puzzle, mappingDecl) {
+        var _a;
+        const cages = new Map();
+        const cageMapping = Array.from(mappingDecl);
+        /* c8 ignore next 5 - defensive coding: protected by validation in puzzleDefinitions.ts */
+        if (cageMapping.length !== puzzle.totalRows * puzzle.totalColumns) {
+            const expected = puzzle.totalRows * puzzle.totalColumns;
+            const got = cageMapping.length;
+            throw new Error(`expected ${expected} cell mappings, found ${got}`);
+        }
+        for (let row = 0; row < puzzle.totalRows; row++) {
+            for (let col = 0; col < puzzle.totalColumns; col++) {
+                const cage = cageMapping.shift();
+                const cell = Ids.cellId({ row, col }).orThrow();
+                const cells = (_a = cages.get(cage)) !== null && _a !== void 0 ? _a : [];
+                cells.push(cell);
+                cages.set(cage, cells);
+            }
+        }
+        return cages;
+    }
+    static _getCages(puzzle, cageCells, cagePart) {
+        const cages = new Map();
+        const cageDefs = cagePart.split(',');
+        if (cageDefs.length !== cageCells.size) {
+            throw new Error(`expected ${cageCells.size} cage sizes, found ${cageDefs.length}`);
+        }
+        for (const def of cageDefs) {
+            if (!cageDefFormat.test(def)) {
+                throw new Error(`malformed cage spec ${def}`);
+            }
+            const cage = def.slice(0, 1);
+            const cageId = Ids.cageId(`K${cage}`).orThrow();
+            const total = Number.parseInt(def.slice(1));
+            const cells = cageCells.get(cage);
+            /* c8 ignore next 3 - should never happen */
+            if (!cells) {
+                throw new Error(`cage ${cageId} has no cells`);
+            }
+            // Use the puzzle's maxValue for dynamic validation
+            const maxValue = puzzle.maxValue;
+            if (cells.length < 1 || cells.length > maxValue) {
+                throw new Error(`invalid cell count ${cells.length} for cage ${cageId} (max ${maxValue})`);
+            }
+            const { min, max } = getCageTotalBounds(cells.length, maxValue);
+            if (total < min || total > max) {
+                throw new Error(`invalid total ${total} for cage ${cageId} (expected ${min}..${max})`);
+            }
+            cages.set(cageId, Cage.create(cageId, 'killer', total, cells).orThrow());
+        }
+        return Array.from(cages.entries());
+    }
+    static _getKillerCells(puzzle, givens) {
+        const cells = [];
+        for (let row = 0; row < puzzle.totalRows; row++) {
+            for (let col = 0; col < puzzle.totalColumns; col++) {
+                const cellId = Ids.cellId({ row, col }).orThrow();
+                const cage = givens.find((g) => g.cellIds[0] === cellId);
+                if (cage) {
+                    /* c8 ignore next 3 - defense in depth should never happen */
+                    if (cage.total < 1 || cage.total > puzzle.maxValue) {
+                        throw new Error(`invalid total ${cage.total} for cell ${cellId}`);
+                    }
+                    cells.push(String(cage.total));
+                }
+                else {
+                    cells.push('.');
+                }
+            }
+        }
+        return cells.join('');
+    }
+}
+//# sourceMappingURL=killerSudokuPuzzle.js.map

package/dist/packlets/puzzles/sudokuPuzzle.js

@@ -0,0 +1,43 @@
+/*
+ * 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 { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { Puzzle } from '../common';
+/**
+ * @public
+ */
+export class SudokuPuzzle extends Puzzle {
+    constructor(puzzle) {
+        super(puzzle);
+    }
+    static create(puzzle) {
+        /* c8 ignore next 3 */
+        if (puzzle.type !== 'sudoku') {
+            return fail(`Puzzle '${puzzle.description}' unsupported type ${puzzle.type}`);
+        }
+        return captureResult(() => new SudokuPuzzle(puzzle)).onSuccess((puzzle) => {
+            return succeed(puzzle);
+        });
+    }
+}
+//# sourceMappingURL=sudokuPuzzle.js.map

package/dist/packlets/puzzles/sudokuXPuzzle.js

@@ -0,0 +1,65 @@
+/*
+ * 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 { captureResult, succeed, fail } from '@fgv/ts-utils';
+import { Cage, Ids, Puzzle } from '../common';
+/**
+ * @public
+ */
+export class SudokuXPuzzle extends Puzzle {
+    constructor(puzzle, extraCages) {
+        super(puzzle, extraCages);
+    }
+    static create(puzzle) {
+        /* c8 ignore next 3 */
+        if (puzzle.type !== 'sudoku-x') {
+            return fail(`Puzzle '${puzzle.description}' unsupported type ${puzzle.type}`);
+        }
+        // Sudoku X diagonals work for any square puzzle (totalRows === totalColumns)
+        if (puzzle.totalRows !== puzzle.totalColumns) {
+            return fail(`Sudoku X puzzle must be square, got ${puzzle.totalRows}x${puzzle.totalColumns}`);
+        }
+        return captureResult(() => {
+            return new SudokuXPuzzle(puzzle, SudokuXPuzzle._getXCages(puzzle));
+        }).onSuccess((puzzle) => {
+            return succeed(puzzle);
+        });
+    }
+    static _getXCages(puzzle) {
+        const x1Cells = [];
+        const x2Cells = [];
+        for (let row = 0, col1 = 0, col2 = puzzle.totalColumns - 1; row < puzzle.totalRows; row++, col1++, col2--) {
+            x1Cells.push(Ids.cellId({ row, col: col1 }).orThrow());
+            x2Cells.push(Ids.cellId({ row, col: col2 }).orThrow());
+        }
+        const x1Id = Ids.cageId('X1').orThrow();
+        const x2Id = Ids.cageId('X2').orThrow();
+        const x1 = Cage.create(x1Id, 'x', puzzle.basicCageTotal, x1Cells).orThrow();
+        const x2 = Cage.create(x2Id, 'x', puzzle.basicCageTotal, x2Cells).orThrow();
+        return [
+            [x1Id, x1],
+            [x2Id, x2]
+        ];
+    }
+}
+//# sourceMappingURL=sudokuXPuzzle.js.map

package/dist/test/unit/helpers/puzzleBuilders.js

@@ -0,0 +1,149 @@
+/*
+ * 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 '@fgv/ts-utils-jest';
+import { PuzzleSession, PuzzleDefinitionFactory, STANDARD_CONFIGS } from '../../../index';
+import { Puzzles } from '../../../index';
+/**
+ * Creates a standard test puzzle and state from row strings
+ * @param rows - 9 strings representing puzzle rows (use '.' for empty cells)
+ * @param puzzleId - Optional puzzle ID (defaults to 'test-puzzle')
+ * @returns Puzzle instance and initial state
+ */
+export function createPuzzleAndState(rows, puzzleId = 'test-puzzle') {
+    const puzzleDefinition = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle9x9, {
+        id: puzzleId,
+        description: 'Test puzzle',
+        type: 'sudoku',
+        level: 1,
+        cells: rows.join('')
+    }).orThrow();
+    const puzzle = Puzzles.Any.create(puzzleDefinition).orThrow();
+    const session = PuzzleSession.create(puzzle).orThrow();
+    return { puzzle, state: session.state };
+}
+/**
+ * Creates a test puzzle with specific dimensions
+ * @param dimensions - Puzzle dimensions configuration
+ * @param cells - Cell values string
+ * @param type - Puzzle type (defaults to 'sudoku')
+ * @returns Puzzle instance and initial state
+ */
+export function createPuzzleWithDimensions(dimensions, cells, type = 'sudoku') {
+    const puzzleDefinition = PuzzleDefinitionFactory.create(dimensions, {
+        id: 'test-puzzle',
+        description: 'Test puzzle',
+        type,
+        level: 1,
+        cells
+    }).orThrow();
+    const puzzle = Puzzles.Any.create(puzzleDefinition).orThrow();
+    const session = PuzzleSession.create(puzzle).orThrow();
+    return { puzzle, state: session.state };
+}
+/**
+ * Creates a killer sudoku puzzle for testing cage-based logic
+ * @param config - Configuration for the killer puzzle
+ * @returns Puzzle instance, session, and first cage
+ */
+export function createTestKillerPuzzle(config) {
+    var _a;
+    const cells = (_a = config.cells) !== null && _a !== void 0 ? _a : '.'.repeat(81);
+    // Build cage specifications
+    let cageSpecs = '';
+    if (config.cages) {
+        cageSpecs = config.cages
+            .map((cage) => {
+            var _a;
+            const id = (_a = cage.id) !== null && _a !== void 0 ? _a : `cage${cage.sum}`;
+            const cellList = cage.cells.join(',');
+            return `${id}:${cellList}:${cage.sum}`;
+        })
+            .join('|');
+    }
+    const puzzleDefinition = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle9x9, {
+        id: 'test-killer',
+        description: 'Test Killer Sudoku',
+        type: 'killer',
+        level: 1,
+        cells: cells + (cageSpecs ? `:${cageSpecs}` : '')
+    }).orThrow();
+    const puzzle = Puzzles.Killer.create(puzzleDefinition).orThrow();
+    const session = PuzzleSession.create(puzzle).orThrow();
+    // Return first cage if any were defined
+    const cage = config.cages && config.cages.length > 0
+        ? puzzle.cages.find((c) => { var _a; return c.id === ((_a = config.cages[0].id) !== null && _a !== void 0 ? _a : `cage${config.cages[0].sum}`); })
+        : undefined;
+    return { puzzle, session, cage };
+}
+/**
+ * Creates a simple killer sudoku cage for testing
+ * @param cageSize - Number of cells in the cage
+ * @param total - Sum total for the cage
+ * @param startCell - Starting cell ID (defaults to 'A1')
+ * @returns Cage specification object
+ */
+export function createSimpleKillerCage(cageSize, total, startCell = 'A1') {
+    const cells = [startCell];
+    // Add adjacent cells horizontally
+    const startRow = startCell.charCodeAt(0);
+    const startCol = parseInt(startCell.substring(1), 10);
+    for (let i = 1; i < cageSize && cells.length < cageSize; i++) {
+        const row = String.fromCharCode(startRow);
+        const col = startCol + i;
+        if (col <= 9) {
+            cells.push(`${row}${col}`);
+        }
+    }
+    // If we need more cells, add them vertically
+    for (let i = 1; cells.length < cageSize && i < 9; i++) {
+        const row = String.fromCharCode(startRow + i);
+        const col = startCol;
+        if (row <= 'I') {
+            cells.push(`${row}${col}`);
+        }
+    }
+    return {
+        id: `cage${total}`,
+        cells,
+        sum: total
+    };
+}
+/**
+ * Creates a sudoku X puzzle for testing diagonal constraints
+ * @param rows - 9 strings representing puzzle rows
+ * @returns Puzzle instance and initial state
+ */
+export function createSudokuXPuzzle(rows) {
+    const puzzleDefinition = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle9x9, {
+        id: 'test-sudoku-x',
+        description: 'Test Sudoku X',
+        type: 'sudoku-x',
+        level: 1,
+        cells: rows.join('')
+    }).orThrow();
+    const puzzle = Puzzles.SudokuX.create(puzzleDefinition).orThrow();
+    const session = PuzzleSession.create(puzzle).orThrow();
+    return { puzzle, state: session.state };
+}
+//# sourceMappingURL=puzzleBuilders.js.map

package/dist/ts-sudoku-lib.d.ts

@@ -371,17 +371,12 @@ declare namespace Files {
     export {
         Converters_2 as Converters,
         Model,
-        FileSystem_2 as FileSystem
+        loadJsonPuzzlesFileSync,
+        loadJsonPuzzlesFromTree
     }
 }
 export { Files }
 
-declare namespace FileSystem_2 {
-    export {
-        loadJsonPuzzlesFileSync
-    }
-}
-
 /**
  * The minimum and maximum possible values for a {@link ICage | cage}, by cage size in
  * {@link ICell | cells}.
@@ -1263,6 +1258,16 @@ declare class KillerSudokuPuzzle extends Puzzle {
  */
 declare function loadJsonPuzzlesFileSync(path: string): Result<IPuzzlesFile>;
 
+/**
+ * Loads a puzzles file from a {@link FileTree.FileTree | FileTree}.
+ * @param fileTree - FileTree containing the file
+ * @param filePath - Path within the FileTree to the puzzles file
+ * @returns `Success` with the resulting file, or `Failure` with details if an
+ * error occurs.
+ * @public
+ */
+declare function loadJsonPuzzlesFromTree(fileTree: FileTree.FileTree, filePath: string): Result<IPuzzlesFile>;
+
 /**
  * Loads a puzzles file from a `IFileTreeFileItem`.
  * @param file - The `IFileTreeFileItem` to load.