logic-puzzle-generator 1.2.4 → 1.3.0

package/dist/src/engine/Clue.d.ts

@@ -82,5 +82,6 @@ export type Clue = BinaryClue | OrdinalClue | SuperlativeClue | UnaryClue | Cros
 export type ClueWithMetadata = Clue & {
     deductions?: number;
     updates?: number;
+    reasons?: import('../types').DeductionReason[];
     percentComplete?: number;
 };

package/dist/src/engine/GenerativeSession.js

@@ -128,6 +128,7 @@ class GenerativeSession {
         // Apply it
         const result = this.solver.applyClue(this.grid, clue);
         clue.deductions = result.deductions;
+        clue.reasons = result.reasons;
         // Calculate % Complete
         // Grid starts with 'totalPossible' and ends with 'solutionPossible'.
         // % = (Total - Current) / (Total - Solution)

package/dist/src/engine/Generator.js

@@ -459,6 +459,8 @@ class Generator {
             else {
                 step.clue.percentComplete = 100;
             }
+            // Capture Deduction Reasons (XAI)
+            step.clue.reasons = result.reasons;
         }
         return {
             solution: this.solution,

package/dist/src/engine/Solver.d.ts

@@ -20,6 +20,7 @@ export declare class Solver {
     applyClue(grid: LogicGrid, clue: Clue): {
         grid: LogicGrid;
         deductions: number;
+        reasons: import('../types').DeductionReason[];
     };
     private applyCrossOrdinalClue;
     private applyUnaryClue;

package/dist/src/engine/Solver.js

@@ -21,31 +21,32 @@ class Solver {
      */
     applyClue(grid, clue) {
         let deductions = 0;
+        const reasons = [];
         switch (clue.type) {
             case types_1.ClueType.BINARY:
-                deductions += this.applyBinaryClue(grid, clue);
+                deductions += this.applyBinaryClue(grid, clue, reasons);
                 break;
             case types_1.ClueType.SUPERLATIVE:
-                deductions += this.applySuperlativeClue(grid, clue);
+                deductions += this.applySuperlativeClue(grid, clue, reasons);
                 break;
             case types_1.ClueType.ORDINAL:
-                deductions += this.applyOrdinalClue(grid, clue);
+                deductions += this.applyOrdinalClue(grid, clue, reasons);
                 break;
             case types_1.ClueType.UNARY:
-                deductions += this.applyUnaryClue(grid, clue);
+                deductions += this.applyUnaryClue(grid, clue, reasons);
                 break;
             case types_1.ClueType.CROSS_ORDINAL:
-                deductions += this.applyCrossOrdinalClue(grid, clue); // Cast as any because import might lag or circular deps? no, just strict TS.
+                deductions += this.applyCrossOrdinalClue(grid, clue, reasons);
                 break;
         }
         let newDeductions;
         do {
-            newDeductions = this.runDeductionLoop(grid);
+            newDeductions = this.runDeductionLoop(grid, reasons);
             deductions += newDeductions;
         } while (newDeductions > 0);
-        return { grid, deductions };
+        return { grid, deductions, reasons };
     }
-    applyCrossOrdinalClue(grid, clue) {
+    applyCrossOrdinalClue(grid, clue, reasons) {
         let deductions = 0;
         const categories = grid.categories;
         const ord1Config = categories.find(c => c.id === clue.ordinal1);
@@ -71,6 +72,11 @@ class Solver {
                 if (targetVal1 === undefined) {
                     grid.setPossibility(clue.item1Cat, clue.item1Val, clue.ordinal1, cand1.val, false);
                     deductions++;
+                    reasons.push({
+                        type: 'cross_ordinal',
+                        description: `Cross-Ordinal: ${clue.item1Val} cannot be ${cand1.val} because offset ${clue.offset1} goes out of bounds.`,
+                        cells: [{ cat: clue.item1Cat, val: clue.item1Val }, { cat: clue.ordinal1, val: cand1.val }]
+                    });
                     continue;
                 }
                 // Compatibility check
@@ -90,6 +96,11 @@ class Solver {
                 if (!supported) {
                     grid.setPossibility(clue.item1Cat, clue.item1Val, clue.ordinal1, cand1.val, false);
                     deductions++;
+                    reasons.push({
+                        type: 'cross_ordinal',
+                        description: `Cross-Ordinal: ${clue.item1Val} as ${cand1.val} finds no compatible ${clue.item2Val} at offset pair.`,
+                        cells: [{ cat: clue.item1Cat, val: clue.item1Val }, { cat: clue.ordinal1, val: cand1.val }]
+                    });
                 }
             }
             // Filter 2 based on 1 (Symmetric)
@@ -99,6 +110,11 @@ class Solver {
                 if (targetVal2 === undefined) {
                     grid.setPossibility(clue.item2Cat, clue.item2Val, clue.ordinal2, cand2.val, false);
                     deductions++;
+                    reasons.push({
+                        type: 'cross_ordinal',
+                        description: `Cross-Ordinal: ${clue.item2Val} cannot be ${cand2.val} because offset ${clue.offset2} goes out of bounds.`,
+                        cells: [{ cat: clue.item2Cat, val: clue.item2Val }, { cat: clue.ordinal1, val: cand2.val }]
+                    });
                     continue;
                 }
                 let supported = false;
@@ -115,6 +131,11 @@ class Solver {
                 if (!supported) {
                     grid.setPossibility(clue.item2Cat, clue.item2Val, clue.ordinal2, cand2.val, false);
                     deductions++;
+                    reasons.push({
+                        type: 'cross_ordinal',
+                        description: `Cross-Ordinal: ${clue.item2Val} as ${cand2.val} finds no compatible ${clue.item1Val} at offset pair.`,
+                        cells: [{ cat: clue.item2Cat, val: clue.item2Val }, { cat: clue.ordinal2, val: cand2.val }]
+                    });
                 }
             }
             // Lock linkage if unique
@@ -130,6 +151,11 @@ class Solver {
                     if (grid.getPossibilitiesCount(clue.ordinal1, v1, clue.ordinal2) > 1) {
                         grid.setPossibility(clue.ordinal1, v1, clue.ordinal2, v2, true);
                         deductions++;
+                        reasons.push({
+                            type: 'cross_ordinal',
+                            description: `Cross-Ordinal Link: ${v1} must be ${v2} based on forced offsets.`,
+                            cells: [{ cat: clue.ordinal1, val: v1 }, { cat: clue.ordinal2, val: v2 }]
+                        });
                     }
                 }
             }
@@ -160,6 +186,11 @@ class Solver {
                     if (grid.isPossible(clue.ordinal1, v1, clue.ordinal2, v2)) {
                         grid.setPossibility(clue.ordinal1, v1, clue.ordinal2, v2, false);
                         deductions++;
+                        reasons.push({
+                            type: 'cross_ordinal',
+                            description: `Cross-Ordinal NOT: ${v1} cannot be ${v2} because positions are forbidden.`,
+                            cells: [{ cat: clue.ordinal1, val: v1 }, { cat: clue.ordinal2, val: v2 }]
+                        });
                     }
                 }
             }
@@ -328,6 +359,11 @@ class Solver {
                             if (grid.isPossible(clue.ordinal1, v1, clue.ordinal2, v2)) {
                                 grid.setPossibility(clue.item2Cat, clue.item2Val, clue.ordinal2, cand2.val, false);
                                 deductions++;
+                                reasons.push({
+                                    type: 'cross_ordinal',
+                                    description: `Cross-Ordinal NOT: ${clue.item2Val} cannot be ${cand2.val} because it implies forbidden link to ${v1}.`,
+                                    cells: [{ cat: clue.item2Cat, val: clue.item2Val }, { cat: clue.ordinal2, val: cand2.val }]
+                                });
                             }
                         }
                     }
@@ -345,6 +381,11 @@ class Solver {
                             if (grid.isPossible(clue.ordinal1, v1, clue.ordinal2, v2)) {
                                 grid.setPossibility(clue.item1Cat, clue.item1Val, clue.ordinal1, cand1.val, false);
                                 deductions++;
+                                reasons.push({
+                                    type: 'cross_ordinal',
+                                    description: `Cross-Ordinal NOT: ${clue.item1Val} cannot be ${cand1.val} because it implies forbidden link to ${v2}.`,
+                                    cells: [{ cat: clue.item1Cat, val: clue.item1Val }, { cat: clue.ordinal1, val: cand1.val }]
+                                });
                             }
                         }
                     }
@@ -353,7 +394,7 @@ class Solver {
         }
         return deductions;
     }
-    applyUnaryClue(grid, clue) {
+    applyUnaryClue(grid, clue, reasons) {
         let deductions = 0;
         const categories = grid.categories;
         const ordinalCatConfig = categories.find(c => c.id === clue.ordinalCat);
@@ -369,12 +410,17 @@ class Solver {
                 if (grid.isPossible(clue.targetCat, clue.targetVal, clue.ordinalCat, ordVal)) {
                     grid.setPossibility(clue.targetCat, clue.targetVal, clue.ordinalCat, ordVal, false);
                     deductions++;
+                    reasons.push({
+                        type: 'unary',
+                        description: `Unary Rule: ${ordVal} eliminated for ${clue.targetVal} because it is ${isEven ? 'not even' : 'not odd'}.`,
+                        cells: [{ cat: clue.targetCat, val: clue.targetVal }, { cat: clue.ordinalCat, val: String(ordVal) }]
+                    });
                 }
             }
         }
         return deductions;
     }
-    applyBinaryClue(grid, clue) {
+    applyBinaryClue(grid, clue, reasons) {
         let deductions = 0;
         const categories = grid.categories;
         const cat1Config = categories.find(c => c.id === clue.cat1);
@@ -385,6 +431,11 @@ class Solver {
             // Count the "Positive Confirmation" (Green Check) as a deduction if it wasn't already known
             if (grid.getPossibilitiesCount(clue.cat1, clue.val1, clue.cat2) > 1) {
                 deductions++;
+                reasons.push({
+                    type: 'confirmation',
+                    description: `Directly from clue: ${clue.val1} is ${clue.val2}.`,
+                    cells: [{ cat: clue.cat1, val: clue.val1 }, { cat: clue.cat2, val: clue.val2 }]
+                });
             }
             if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, clue.val2)) {
                 // This is not a deduction, but a fact application. Still, we need to eliminate other possibilities.
@@ -395,6 +446,11 @@ class Solver {
                     if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, val)) {
                         grid.setPossibility(clue.cat1, clue.val1, clue.cat2, val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'elimination',
+                            description: `Since ${clue.val1} is ${clue.val2}, it cannot be ${val}.`,
+                            cells: [{ cat: clue.cat1, val: clue.val1 }, { cat: clue.cat2, val: val }]
+                        });
                     }
                 }
             }
@@ -403,6 +459,11 @@ class Solver {
                     if (grid.isPossible(clue.cat1, val, clue.cat2, clue.val2)) {
                         grid.setPossibility(clue.cat1, val, clue.cat2, clue.val2, false);
                         deductions++;
+                        reasons.push({
+                            type: 'elimination',
+                            description: `Since ${clue.val2} is ${clue.val1}, it cannot be ${val}.`,
+                            cells: [{ cat: clue.cat1, val: val }, { cat: clue.cat2, val: clue.val2 }]
+                        });
                     }
                 }
             }
@@ -411,11 +472,16 @@ class Solver {
             if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, clue.val2)) {
                 grid.setPossibility(clue.cat1, clue.val1, clue.cat2, clue.val2, false);
                 deductions++;
+                reasons.push({
+                    type: 'elimination',
+                    description: `Directly from clue: ${clue.val1} is NOT ${clue.val2}.`,
+                    cells: [{ cat: clue.cat1, val: clue.val1 }, { cat: clue.cat2, val: clue.val2 }]
+                });
             }
         }
         return deductions;
     }
-    runDeductionLoop(grid) {
+    runDeductionLoop(grid, reasons) {
         let deductions = 0;
         const categories = grid.categories;
         for (const cat1 of categories) {
@@ -433,6 +499,11 @@ class Solver {
                                 if (grid.isPossible(cat1.id, otherVal1, cat2.id, val2)) {
                                     grid.setPossibility(cat1.id, otherVal1, cat2.id, val2, false);
                                     deductions++;
+                                    reasons.push({
+                                        type: 'uniqueness',
+                                        description: `Since ${val2} is uniquely ${val1} in ${cat1.id}, it cannot be ${otherVal1}.`,
+                                        cells: [{ cat: cat1.id, val: val1 }, { cat: cat2.id, val: val2 }, { cat: cat1.id, val: otherVal1 }]
+                                    });
                                 }
                             }
                         }
@@ -453,6 +524,11 @@ class Solver {
                                 else if (grid.getPossibilitiesCount(cat1.id, val1, cat3.id) > 1) {
                                     grid.setPossibility(cat1.id, val1, cat3.id, definiteVal3, true);
                                     deductions++;
+                                    reasons.push({
+                                        type: 'transitivity',
+                                        description: `Since ${cat1.id}:${val1} is ${cat2.id}:${definiteVal2}, and that is ${cat3.id}:${definiteVal3}, ${val1} must be ${definiteVal3}.`,
+                                        cells: [{ cat: cat1.id, val: val1 }, { cat: cat2.id, val: definiteVal2 }, { cat: cat3.id, val: definiteVal3 }]
+                                    });
                                 }
                             }
                         }
@@ -463,6 +539,11 @@ class Solver {
                                 if (!isPathPossible) {
                                     grid.setPossibility(cat1.id, val1, cat3.id, val3, false);
                                     deductions++;
+                                    reasons.push({
+                                        type: 'transitivity',
+                                        description: `Negative Transitivity: No path exists between ${val1} and ${val3} via ${cat2.id}.`,
+                                        cells: [{ cat: cat1.id, val: val1 }, { cat: cat3.id, val: val3 }]
+                                    });
                                 }
                             }
                         }
@@ -472,7 +553,7 @@ class Solver {
         }
         return deductions;
     }
-    applyOrdinalClue(grid, constraint) {
+    applyOrdinalClue(grid, constraint, reasons) {
         let deductions = 0;
         const categories = grid.categories;
         const ordCatConfig = categories.find(c => c.id === constraint.ordinalCat);
@@ -494,6 +575,11 @@ class Solver {
                     if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
                         grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item1Val} cannot be ${pval1.val} (idx ${pval1.idx}) because it must be > ${constraint.item2Val}.`,
+                            cells: [{ cat: constraint.item1Cat, val: constraint.item1Val }, { cat: constraint.ordinalCat, val: pval1.val }]
+                        });
                     }
                 }
             }
@@ -505,6 +591,11 @@ class Solver {
                     if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
                         grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item1Val} cannot be ${pval1.val} (idx ${pval1.idx}) because it must be < ${constraint.item2Val}.`,
+                            cells: [{ cat: constraint.item1Cat, val: constraint.item1Val }, { cat: constraint.ordinalCat, val: pval1.val }]
+                        });
                     }
                 }
             }
@@ -516,6 +607,11 @@ class Solver {
                     if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
                         grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item1Val} cannot be ${pval1.val} (idx ${pval1.idx}) because it must be <= ${constraint.item2Val}.`,
+                            cells: [{ cat: constraint.item1Cat, val: constraint.item1Val }, { cat: constraint.ordinalCat, val: pval1.val }]
+                        });
                     }
                 }
             }
@@ -527,6 +623,11 @@ class Solver {
                     if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
                         grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item1Val} cannot be ${pval1.val} (idx ${pval1.idx}) because it must be >= ${constraint.item2Val}.`,
+                            cells: [{ cat: constraint.item1Cat, val: constraint.item1Val }, { cat: constraint.ordinalCat, val: pval1.val }]
+                        });
                     }
                 }
             }
@@ -539,6 +640,11 @@ class Solver {
                     if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
                         grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item2Val} cannot be ${pval2.val} (idx ${pval2.idx}) because it must be < ${constraint.item1Val}.`,
+                            cells: [{ cat: constraint.item2Cat, val: constraint.item2Val }, { cat: constraint.ordinalCat, val: pval2.val }]
+                        });
                     }
                 }
             }
@@ -550,6 +656,11 @@ class Solver {
                     if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
                         grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item2Val} cannot be ${pval2.val} (idx ${pval2.idx}) because it must be > ${constraint.item1Val}.`,
+                            cells: [{ cat: constraint.item2Cat, val: constraint.item2Val }, { cat: constraint.ordinalCat, val: pval2.val }]
+                        });
                     }
                 }
             }
@@ -561,6 +672,11 @@ class Solver {
                     if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
                         grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item2Val} cannot be ${pval2.val} (idx ${pval2.idx}) because it must be >= ${constraint.item1Val}.`,
+                            cells: [{ cat: constraint.item2Cat, val: constraint.item2Val }, { cat: constraint.ordinalCat, val: pval2.val }]
+                        });
                     }
                 }
             }
@@ -572,13 +688,18 @@ class Solver {
                     if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
                         grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
                         deductions++;
+                        reasons.push({
+                            type: 'ordinal',
+                            description: `${constraint.item2Val} cannot be ${pval2.val} (idx ${pval2.idx}) because it must be <= ${constraint.item1Val}.`,
+                            cells: [{ cat: constraint.item2Cat, val: constraint.item2Val }, { cat: constraint.ordinalCat, val: pval2.val }]
+                        });
                     }
                 }
             }
         }
         return deductions;
     }
-    applySuperlativeClue(grid, clue) {
+    applySuperlativeClue(grid, clue, reasons) {
         const categories = grid.categories;
         const ordinalCatConfig = categories.find(c => c.id === clue.ordinalCat);
         if (!ordinalCatConfig || ordinalCatConfig.type !== types_1.CategoryType.ORDINAL)
@@ -611,7 +732,7 @@ class Solver {
             val2: extremeValue,
             operator: isNot ? types_1.BinaryOperator.IS_NOT : types_1.BinaryOperator.IS,
         };
-        return this.applyBinaryClue(grid, binaryClue);
+        return this.applyBinaryClue(grid, binaryClue, reasons);
     }
 }
 exports.Solver = Solver;

package/dist/src/types.d.ts

@@ -103,3 +103,11 @@ export interface ClueGenerationConstraints {
      */
     maxDeductions?: number;
 }
+export interface DeductionReason {
+    type: 'elimination' | 'confirmation' | 'uniqueness' | 'transitivity' | 'clue' | 'unary' | 'ordinal' | 'cross_ordinal';
+    description: string;
+    cells?: {
+        cat: string;
+        val: ValueLabel;
+    }[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logic-puzzle-generator",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -45,4 +45,4 @@
     "ts-jest": "^29.1.2",
     "typescript": "^5.4.5"
   }
-}
+}