logic-puzzle-generator 1.0.0

package/dist/src/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./engine/Clue"), exports);
+__exportStar(require("./engine/LogicGrid"), exports);
+__exportStar(require("./engine/Solver"), exports);
+__exportStar(require("./engine/Generator"), exports);
+__exportStar(require("./engine/GenerativeSession"), exports);
+__exportStar(require("./defaults"), exports);
+__exportStar(require("./errors"), exports);

package/dist/src/scripts/GenerateBoundsDeprecated.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/GenerateBoundsDeprecated.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const BoundsCalculator_1 = require("../engine/BoundsCalculator");
+describe('Bounds Generation', () => {
+    // We increase timeout significantly for simulation
+    jest.setTimeout(120000);
+    test('Generate Table', () => {
+        const configs = [
+            { c: 2, i: 3 }, { c: 2, i: 4 }, { c: 2, i: 5 }, { c: 2, i: 6 },
+            { c: 3, i: 3 }, { c: 3, i: 4 }, { c: 3, i: 5 }, { c: 3, i: 6 },
+            { c: 4, i: 3 }, { c: 4, i: 4 }, { c: 4, i: 5 }, { c: 4, i: 6 }
+        ];
+        const results = {};
+        console.log("Generating Bounds Table (this may take a minute)...");
+        for (const conf of configs) {
+            const key = `${conf.c}x${conf.i}`;
+            // 20 iterations per config
+            process.stdout.write(`Computing ${key}... `);
+            const bounds = BoundsCalculator_1.BoundsCalculator.calculate(conf.c, conf.i, 20);
+            results[key] = bounds;
+            console.log(`[${bounds.min}, ${bounds.max}]`);
+        }
+        console.log("\n--- JSON OUTPUT ---");
+        console.log(JSON.stringify(results, null, 2));
+        console.log("--- END JSON ---\n");
+    });
+});

package/dist/src/scripts/StressTestBacktracking.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/StressTestBacktracking.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Generator_1 = require("../engine/Generator");
+const types_1 = require("../types");
+// CONFIGURATION
+const NUM_CATS = 5;
+const NUM_ITEMS = 10;
+const TARGET_CLUES = 45; // Minimum is 35, so 45 is still very hard (tight constraint)
+const TIMEOUT_MS = 60000; // Give it 60s for this extreme test
+// Setup Categories
+const categories = [];
+for (let i = 0; i < NUM_CATS; i++) {
+    const values = [];
+    for (let j = 0; j < NUM_ITEMS; j++) {
+        values.push(`Item ${j + 1}`);
+    }
+    categories.push({
+        id: `cat_${i + 1}`,
+        type: types_1.CategoryType.NOMINAL,
+        values: values
+    });
+}
+const generator = new Generator_1.Generator(Date.now()); // Seed with time
+console.log(`Starting Stress Test: ${NUM_CATS}x${NUM_ITEMS} Grid. Target: ${TARGET_CLUES}`);
+let lastLogTime = 0;
+try {
+    const puzzle = generator.generatePuzzle(categories, undefined, {
+        maxCandidates: Infinity,
+        targetClueCount: TARGET_CLUES,
+        timeoutMs: TIMEOUT_MS,
+        onTrace: (msg) => {
+            // Throttle logs to avoid flooding terminal
+            if (msg.includes("Depth") || msg.includes("SOLVED") || msg.includes("Pruning")) {
+                console.log(msg);
+            }
+            else if (Date.now() - lastLogTime > 1000) {
+                console.log(msg);
+                lastLogTime = Date.now();
+            }
+        }
+    });
+    console.log("SUCCESS! Puzzle generated.");
+    console.log(`Clues: ${puzzle.clues.length}`);
+    console.log("Proof Chain Length:", puzzle.proofChain.length);
+}
+catch (error) {
+    console.error("FAILED to generate puzzle.");
+    console.error(error);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A primitive value that acts as a label for an entity (e.g., "Alice", 42).
+ */
+export type ValueLabel = string | number;
+/**
+ * Defines the nature of a category's values.
+ */
+export declare enum CategoryType {
+    /** Order is irrelevant (e.g., Name, Genre). */
+    NOMINAL = 0,
+    /** Order is crucial for comparisons (e.g., Age, Price). Values must be numbers. */
+    ORDINAL = 1
+}
+/**
+ * Configuration for a single category in the puzzle.
+ */
+export interface CategoryConfig {
+    /** Unique internal identifier for the category (e.g., 'Name'). */
+    id: string;
+    /** The type of data this category holds. */
+    type: CategoryType;
+    /** The list of possible values. Must be unique. If ORDINAL, they must be sorted. */
+    values: ValueLabel[];
+}
+/**
+ * Represents the complete solution to the puzzle (the "answer key").
+ * Structure: { CategoryID -> { Value -> CorrectValueInOtherCategory } }
+ */
+export type Solution = Record<string, Record<string, ValueLabel>>;
+/**
+ * A specific correlation that the puzzle solver aims to deduce as the final answer.
+ */
+export interface TargetFact {
+    category1Id: string;
+    value1: ValueLabel;
+    category2Id: string;
+}
+/**
+ * Enumeration of all supported clue types.
+ */
+export declare enum ClueType {
+    /** Expresses a direct relationship (IS or IS NOT) between two values. */
+    BINARY = 0,
+    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
+    ORDINAL = 1,
+    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
+    SUPERLATIVE = 2,
+    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
+    UNARY = 3,
+    /** Expresses a relationship between relative positions in two different ordinal categories. */
+    CROSS_ORDINAL = 4
+}
+export declare enum CrossOrdinalOperator {
+    MATCH = 0,
+    NOT_MATCH = 1
+}
+export declare enum BinaryOperator {
+    IS = 0,
+    IS_NOT = 1
+}
+export declare enum OrdinalOperator {
+    GREATER_THAN = 0,
+    LESS_THAN = 1,
+    NOT_GREATER_THAN = 2,
+    NOT_LESS_THAN = 3
+}
+export declare enum SuperlativeOperator {
+    MIN = 0,
+    MAX = 1,
+    NOT_MIN = 2,
+    NOT_MAX = 3
+}
+export declare enum UnaryFilter {
+    IS_ODD = 0,
+    IS_EVEN = 1
+}
+/**
+ * Configuration for constraining the types of clues generated.
+ */
+export interface ClueGenerationConstraints {
+    /**
+     * If provided, only clues of these types will be generated.
+     * Use this to control difficulty or puzzle attributes.
+     */
+    allowedClueTypes?: ClueType[];
+}

package/dist/src/types.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnaryFilter = exports.SuperlativeOperator = exports.OrdinalOperator = exports.BinaryOperator = exports.CrossOrdinalOperator = exports.ClueType = exports.CategoryType = void 0;
+/**
+ * Defines the nature of a category's values.
+ */
+var CategoryType;
+(function (CategoryType) {
+    /** Order is irrelevant (e.g., Name, Genre). */
+    CategoryType[CategoryType["NOMINAL"] = 0] = "NOMINAL";
+    /** Order is crucial for comparisons (e.g., Age, Price). Values must be numbers. */
+    CategoryType[CategoryType["ORDINAL"] = 1] = "ORDINAL";
+})(CategoryType || (exports.CategoryType = CategoryType = {}));
+/**
+ * Enumeration of all supported clue types.
+ */
+var ClueType;
+(function (ClueType) {
+    /** Expresses a direct relationship (IS or IS NOT) between two values. */
+    ClueType[ClueType["BINARY"] = 0] = "BINARY";
+    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
+    ClueType[ClueType["ORDINAL"] = 1] = "ORDINAL";
+    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
+    ClueType[ClueType["SUPERLATIVE"] = 2] = "SUPERLATIVE";
+    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
+    ClueType[ClueType["UNARY"] = 3] = "UNARY";
+    /** Expresses a relationship between relative positions in two different ordinal categories. */
+    ClueType[ClueType["CROSS_ORDINAL"] = 4] = "CROSS_ORDINAL";
+})(ClueType || (exports.ClueType = ClueType = {}));
+var CrossOrdinalOperator;
+(function (CrossOrdinalOperator) {
+    CrossOrdinalOperator[CrossOrdinalOperator["MATCH"] = 0] = "MATCH";
+    CrossOrdinalOperator[CrossOrdinalOperator["NOT_MATCH"] = 1] = "NOT_MATCH";
+})(CrossOrdinalOperator || (exports.CrossOrdinalOperator = CrossOrdinalOperator = {}));
+var BinaryOperator;
+(function (BinaryOperator) {
+    BinaryOperator[BinaryOperator["IS"] = 0] = "IS";
+    BinaryOperator[BinaryOperator["IS_NOT"] = 1] = "IS_NOT";
+})(BinaryOperator || (exports.BinaryOperator = BinaryOperator = {}));
+var OrdinalOperator;
+(function (OrdinalOperator) {
+    OrdinalOperator[OrdinalOperator["GREATER_THAN"] = 0] = "GREATER_THAN";
+    OrdinalOperator[OrdinalOperator["LESS_THAN"] = 1] = "LESS_THAN";
+    OrdinalOperator[OrdinalOperator["NOT_GREATER_THAN"] = 2] = "NOT_GREATER_THAN";
+    OrdinalOperator[OrdinalOperator["NOT_LESS_THAN"] = 3] = "NOT_LESS_THAN";
+})(OrdinalOperator || (exports.OrdinalOperator = OrdinalOperator = {}));
+var SuperlativeOperator;
+(function (SuperlativeOperator) {
+    SuperlativeOperator[SuperlativeOperator["MIN"] = 0] = "MIN";
+    SuperlativeOperator[SuperlativeOperator["MAX"] = 1] = "MAX";
+    SuperlativeOperator[SuperlativeOperator["NOT_MIN"] = 2] = "NOT_MIN";
+    SuperlativeOperator[SuperlativeOperator["NOT_MAX"] = 3] = "NOT_MAX";
+})(SuperlativeOperator || (exports.SuperlativeOperator = SuperlativeOperator = {}));
+var UnaryFilter;
+(function (UnaryFilter) {
+    UnaryFilter[UnaryFilter["IS_ODD"] = 0] = "IS_ODD";
+    UnaryFilter[UnaryFilter["IS_EVEN"] = 1] = "IS_EVEN";
+})(UnaryFilter || (exports.UnaryFilter = UnaryFilter = {}));

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A primitive value that acts as a label for an entity (e.g., "Alice", 42).
+ */
+export type ValueLabel = string | number;
+/**
+ * Defines the nature of a category's values.
+ */
+export declare enum CategoryType {
+    /** Order is irrelevant (e.g., Name, Genre). */
+    NOMINAL = 0,
+    /** Order is crucial for comparisons (e.g., Age, Price). Values must be numbers. */
+    ORDINAL = 1
+}
+/**
+ * Configuration for a single category in the puzzle.
+ */
+export interface CategoryConfig {
+    /** Unique internal identifier for the category (e.g., 'Name'). */
+    id: string;
+    /** The type of data this category holds. */
+    type: CategoryType;
+    /** The list of possible values. Must be unique. If ORDINAL, they must be sorted. */
+    values: ValueLabel[];
+}
+/**
+ * Represents the complete solution to the puzzle (the "answer key").
+ * Structure: { CategoryID -> { Value -> CorrectValueInOtherCategory } }
+ */
+export type Solution = Record<string, Record<string, ValueLabel>>;
+/**
+ * A specific correlation that the puzzle solver aims to deduce as the final answer.
+ */
+export interface TargetFact {
+    category1Id: string;
+    value1: ValueLabel;
+    category2Id: string;
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CategoryType = void 0;
+/**
+ * Defines the nature of a category's values.
+ */
+var CategoryType;
+(function (CategoryType) {
+    /** Order is irrelevant (e.g., Name, Genre). */
+    CategoryType[CategoryType["NOMINAL"] = 0] = "NOMINAL";
+    /** Order is crucial for comparisons (e.g., Age, Price). Values must be numbers. */
+    CategoryType[CategoryType["ORDINAL"] = 1] = "ORDINAL";
+})(CategoryType || (exports.CategoryType = CategoryType = {}));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "logic-puzzle-generator",
+  "version": "1.0.0",
+  "description": "A headless, TypeScript-based Logic Grid Puzzle Engine.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "node dist/examples/cli.js",
+    "benchmark": "tsc && node dist/examples/benchmark.js",
+    "release": "standard-version",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "logic",
+    "puzzle",
+    "generator",
+    "zebra puzzle",
+    "grid",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.7",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "standard-version": "^9.5.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  }
+}