@ak--47/dungeon-master 1.5.1 → 1.5.3

package/scripts/dungeon-to-json.mjs

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * Converts a JavaScript dungeon file to JSON that can be loaded into the UI
+ * Converts a JavaScript dungeon file to JSON that can be loaded into the UI.
+ * Thin CLI wrapper around the exported `dungeonToJSON` (lib/core/dungeon-to-json.js).
  * Usage: node scripts/dungeon-to-json.js <input.js> [output-name]
  */
 
 import { writeFileSync } from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { dungeonToJSON } from '../lib/core/dungeon-to-json.js';
 
 // Get command line arguments
 const args = process.argv.slice(2);
@@ -25,34 +24,10 @@ const inputPath = path.resolve(args[0]);
 const outputName = args[1] || path.basename(inputPath, '.js');
 
 try {
-    // Import the JavaScript module
     console.log(`📖 Loading ${inputPath}...`);
-    const module = await import(`file://${inputPath}`);
-    const config = module.default;
-
-    if (!config) {
-        throw new Error('No default export found in the module');
-    }
-
-    // Extract hooks if they exist
-    const hooksFunction = config.hook;
-    const hooksString = hooksFunction ? hooksFunction.toString() : null;
-
-    // Create a clean config without the hook function
-    const cleanConfig = { ...config };
-    delete cleanConfig.hook;
-
-    // Convert to JSON-serializable format
     console.log('🔄 Converting to JSON format...');
-    const schema = convertToJSON(cleanConfig);
-
-    // Create the dungeon state object (same format as UI saves)
-    const dungeonState = {
-        schema,
-        hooks: hooksString,
-        timestamp: new Date().toISOString(),
-        version: '4.0'
-    };
+    // includeCredentials: true preserves the legacy UI round-trip behavior (full config).
+    const dungeonState = await dungeonToJSON(inputPath, { includeCredentials: true });
 
     // Write to JSON file
     const outputPath = path.join(path.dirname(inputPath), `${outputName}.json`);
@@ -67,97 +42,3 @@ try {
     console.error(error.stack);
     process.exit(1);
 }
-
-/**
- * Convert JavaScript config to JSON-serializable format
- * Detects functions and converts them to object representation
- */
-function convertToJSON(value) {
-    // Null/undefined
-    if (value === null || value === undefined) {
-        return null;
-    }
-
-    // Primitives
-    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
-        return value;
-    }
-
-    // Functions - convert to object representation
-    if (typeof value === 'function') {
-        return convertFunctionToObject(value);
-    }
-
-    // Arrays
-    if (Array.isArray(value)) {
-        return value.map(item => convertToJSON(item));
-    }
-
-    // Objects
-    if (typeof value === 'object') {
-        const result = {};
-        for (const [key, val] of Object.entries(value)) {
-            result[key] = convertToJSON(val);
-        }
-        return result;
-    }
-
-    // Fallback
-    return null;
-}
-
-/**
- * Convert a function to its object representation
- * Tries to detect the function type and extract parameters
- */
-function convertFunctionToObject(func) {
-    const funcString = func.toString();
-
-    // Arrow function
-    if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
-        return {
-            functionName: 'arrow',
-            body: funcString
-        };
-    }
-
-    // Bound chance methods (e.g., chance.name.bind(chance))
-    if (funcString.includes('.bind(')) {
-        const match = funcString.match(/chance\.(\w+)\.bind/);
-        if (match) {
-            return {
-                functionName: `chance.${match[1]}`,
-                args: []
-            };
-        }
-    }
-
-    // Try to detect common utility functions
-    // This is a best-effort approach - some complex functions might not be detected
-    const commonFunctions = [
-        'weighNumRange',
-        'weighArray',
-        'weighChoices',
-        'pickAWinner',
-        'date',
-        'integer',
-        'uid',
-        'comma'
-    ];
-
-    for (const fnName of commonFunctions) {
-        if (funcString.includes(fnName)) {
-            // Extract args (this is simplified - real parsing would be more complex)
-            return {
-                functionName: fnName,
-                args: [] // Args would need to be extracted, but that's complex
-            };
-        }
-    }
-
-    // Generic function - just store as arrow function
-    return {
-        functionName: 'arrow',
-        body: funcString
-    };
-}

package/types.d.ts

@@ -1508,6 +1508,79 @@ export declare function parseJSONDungeon(json: object): Dungeon;
 /** Validate that an object has the minimum shape of a dungeon config. Throws on shape violations. */
 export declare function validateDungeonShape(config: unknown): void;
 
+/**
+ * The serialized form of a function found in a dungeon schema. Produced by `dungeonToJSON`
+ * and revived by `parseJSONDungeon`.
+ *
+ * - `functionName: "arrow"` with a `body` — an inline/closure function, re-eval'd on revive.
+ * - `functionName: "chance.<method>"` — a bound chance method, e.g. `chance.name.bind(chance)`.
+ * - `functionName: "<utility>"` (weighNumRange, weighArray, …) — a detected utility; args are
+ *   not recoverable from the stringified source, so it revives to null (best effort).
+ *
+ * `dataType` records the function's sampled output type so the field's type is preserved even
+ * when the generator itself can't be revived.
+ */
+export interface SerializedFunction {
+	/** "arrow", "chance.<method>", or a known utility name. */
+	functionName: string;
+	/** Stringified function source (present for arrow/closure forms). */
+	body?: string;
+	/** Captured call arguments (best effort; usually empty for detected utilities). */
+	args?: unknown[];
+	/**
+	 * Inferred output type, sampled at serialization time:
+	 * "number" | "string" | "boolean" | "date" | "object" | "<elementType>[]" | "array".
+	 * Omitted when sampling failed (e.g. the function threw).
+	 */
+	dataType?: string;
+}
+
+/**
+ * The JSON/UI wrapper representation of a dungeon, as produced by `dungeonToJSON` and
+ * consumed by `parseJSONDungeon`. Functions in `schema` are serialized to
+ * {@link SerializedFunction} objects; everything else is plain JSON.
+ */
+export interface DungeonJSON {
+	/** The dungeon config with functions converted to {@link SerializedFunction} objects (hook excluded). */
+	schema: Record<string, unknown>;
+	/** The `hook` function stringified, or null if the dungeon has no hook. */
+	hooks: string | null;
+	/** ISO timestamp of when the JSON was produced. */
+	timestamp: string;
+	/** UI schema format version. */
+	version: string;
+}
+
+/** The doc blocks extracted from a dungeon's source by `extractComments`. */
+export interface DungeonComments {
+	/** Cleaned text of the `// ── OVERVIEW ──` block, or null if absent. */
+	overview: string | null;
+	/** Cleaned text of the `// ── HOOK STORIES ──` block, or null if absent. */
+	hookStories: string | null;
+	/** Every `// ── LABEL ──` header followed by a block comment, keyed by exact label. */
+	sections: Record<string, string>;
+}
+
+/**
+ * Convert a dungeon into its JSON representation (the inverse of `parseJSONDungeon`).
+ * Accepts a config object, a file path, raw JS source, or an array of file paths
+ * (returns an array). Credentials are stripped unless `includeCredentials` is set.
+ * Best effort: arrow functions and `chance.*` methods round-trip; detected utility
+ * calls lose their arguments. Always async.
+ */
+export declare function dungeonToJSON(input: Dungeon, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string[], options?: { includeCredentials?: boolean }): Promise<DungeonJSON[]>;
+
+/**
+ * Extract the human-readable doc blocks (OVERVIEW, HOOK STORIES, …) from a dungeon's
+ * SOURCE. Operates on a file path or raw source string — never imports the dungeon
+ * (importing discards comments). Best effort: relies on the canonical `// ── LABEL ──`
+ * header + block-comment convention.
+ */
+export declare function extractComments(input: string): DungeonComments;
+export declare function extractComments(input: string[]): DungeonComments[];
+
 // ============= Text Generator Types =============
 
 /**