extwee 2.2.4 → 2.2.5

package/README.md

@@ -145,17 +145,17 @@ De-compile Twine 2 HTML into Twee 3:
 
 ### Compiling Twee 3 into Twine 1 HTML
 
-Enabling Twine 1 mode requires using the `-t1` or `--twine1` flag.
+Enabling Twine 1 mode requires using the `--twine1` flag.
 
 Because Twine 1 story formats can be split across files, compilation requires the "engine" from Twine 1 named `engine.js`, the name of the story format, and then its `header.html` template code and the optional but often included `code.js` file.
 
-`extwee -t1 -c -i <tweeFile> -o <Twine1HTML> -engine <engineJS> -name <storyFormatName> -codejs <CodeJS> -header <header>`
+`extwee --twine1 -c -i <tweeFile> -o <Twine1HTML> --engine <engineJS> --name <storyFormatName> --codejs <CodeJS> --header <header>`
 
 ### De-compiling Twine 1 HTML into Twee 3
 
-Enabling Twine 1 mode requires using the `-t1` or `--twine1` flag.
+Enabling Twine 1 mode requires using the `--twine1` flag.
 
-`extwee -t1 -d -i <twine1HTML> -o <outputTwee>`
+`extwee --twine1 -d -i <twine1HTML> -o <outputTwee>`
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -163,7 +163,6 @@ Enabling Twine 1 mode requires using the `-t1` or `--twine1` flag.
 
 Each major version has its own GitHub project:
 
-- [Road to Extwee 2.2.0](https://github.com/users/videlais/projects/2)
 - [Road to Extwee 2.4.0](https://github.com/users/videlais/projects/4)
 
 ## Tree Shaking Support

package/eslint.config.js

@@ -1,8 +1,10 @@
 import globals from "globals";
 import pluginJs from "@eslint/js";
 import jest from "eslint-plugin-jest";
+import jsdoc from 'eslint-plugin-jsdoc';
 
 export default [
+  jsdoc.configs['flat/recommended'],
   {
     languageOptions: { 
         globals: {
@@ -12,7 +14,11 @@ export default [
         }
     },
     plugins: {
-        jest: jest
+        jest: jest,
+        jsdoc: jsdoc
+    },
+    rules: {
+      'jsdoc/require-description': 'warn'
     }
   },
   pluginJs.configs.recommended,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -24,34 +24,35 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^12.1.0",
+    "commander": "^13.1.0",
     "graphemer": "^1.4.0",
     "html-entities": "^2.5.2",
-    "node-html-parser": "^6.1.13",
+    "node-html-parser": "^7.0.1",
     "pickleparser": "^0.2.1",
-    "semver": "^7.6.2",
-    "uuid": "^10.0.0"
+    "semver": "^7.7.1",
+    "uuid": "^11.0.5"
   },
   "devDependencies": {
-    "@babel/cli": "^7.25.6",
-    "@babel/core": "^7.24.6",
-    "@babel/preset-env": "^7.24.6",
-    "@eslint/js": "^9.10.0",
+    "@babel/cli": "^7.26.4",
+    "@babel/core": "^7.26.8",
+    "@babel/preset-env": "^7.26.8",
+    "@eslint/js": "^9.20.0",
     "@types/uuid": "^10.0.0",
-    "babel-loader": "^9.1.3",
+    "babel-loader": "^9.2.1",
     "clean-jsdoc-theme": "^4.3.0",
-    "core-js": "^3.37.1",
-    "esbuild": "^0.23.0",
-    "eslint": "^9.10.0",
-    "eslint-plugin-jest": "^28.8.3",
-    "globals": "^15.9.0",
+    "core-js": "^3.40.0",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.20.0",
+    "eslint-plugin-jest": "^28.11.0",
+    "eslint-plugin-jsdoc": "^50.6.3",
+    "globals": "^15.14.0",
     "jest": "^29.7.0",
     "regenerator-runtime": "^0.14.1",
     "shelljs": "^0.8.5",
-    "typescript": "^5.4.5",
-    "typescript-eslint": "^8.4.0",
-    "webpack": "^5.91.0",
-    "webpack-cli": "^5.1.4"
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.23.0",
+    "webpack": "^5.97.1",
+    "webpack-cli": "^6.0.1"
   },
   "repository": {
     "type": "git",

package/src/Config/parser.js

@@ -0,0 +1,36 @@
+/**
+ * Parses a JSON object and extracts the StoryFormat, StoryTitle and StoryVersion.
+ * @param {object} obj Incoming JSON object.
+ * @returns {object} An object containing the extracted results.
+ */
+export function parser(obj) {
+    // Check if the object is a valid JSON object.
+    if (typeof obj !== 'object' || obj === null) {
+        throw new Error('Error: Invalid JSON object');
+    }
+
+    // Extracted results.
+    let results = {
+        StoryFormat: null,
+        StoryTitle: null,
+        StoryVersion: null
+    };
+    
+    // Does the object contain 'StoryFormat'?
+    if (Object.hasOwnProperty.call(obj, 'story-format')) {
+        results.StoryFormat = obj['story-format'];
+    }
+
+    // Does the object contain 'StoryTitle'?
+    if (Object.hasOwnProperty.call(obj, 'story-title')) {
+        results.StoryTitle = obj['story-title'];
+    }
+
+    // Does the object contain 'StoryVersion'?
+    if (Object.hasOwnProperty.call(obj, 'story-version')) {
+        results.StoryVersion = obj['story-version'];
+    }
+
+    // Return the extracted results.
+    return results;
+}

package/src/Config/reader.js

@@ -0,0 +1,34 @@
+import {readFileSync, existsSync} from 'node:fs';
+
+/**
+ * Read a JSON file and return its contents.
+ * @param {string} path Path to the JSON file.
+ * @returns {object} Parsed JSON object.
+ * @throws {Error} If the file does not exist.
+ * @throws {Error} If the file is not a valid JSON file.
+ * @example
+ * const contents = reader('test/Config/files/valid.json');
+ * console.log(contents); // {"story-format": 'Harlowe', "story-title": "My Story"}
+ */
+export function reader(path) {
+    // Does the file exist?
+    if (!existsSync(path)) {
+        throw new Error(`Error: File ${path} not found`);
+    }
+
+    // Read the file.
+    const contents = readFileSync(path, 'utf8');
+
+    // Parsed contents.
+    let parsedContents = null;
+
+    // Try to parse the contents into JSON object.
+    try {
+        parsedContents = JSON.parse(contents);
+    } catch (error) {
+        throw new Error(`Error: File ${path} is not a valid JSON file. ${error.message}`);
+    }
+
+    // Return the parsed contents.
+    return parsedContents;
+}

package/src/Story.js

@@ -5,7 +5,7 @@ import { encode } from 'html-entities';
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.2.4';
+const creatorVersion = '2.2.5';
 
 /**
  * Story class.

package/src/TWS/parse.js

@@ -28,9 +28,8 @@ function parse (binaryFileContents) {
     // Try to parse the pickle data, assuming it is pickle data.
     pythonObject = parser.parse(binaryFileContents);
   } catch (error) {
-    console.log(error);
     // This is a Buffer, but not pickle data.
-    throw new TypeError('Error: Buffer does not contain Python pickle data!');
+    throw new TypeError(`Error: Buffer does not contain Python pickle data! ${error}`);
   }
 
   // Create Story object.

package/src/extwee.js

@@ -53,12 +53,12 @@ const isFile = (path) => {
 program
   .name('extwee')
   .description('CLI for Extwee')
-  .version('2.2.0', '-v, -V, --version', 'Output the current version')
+  .option('-v, --version', '2.2.4')
   .option('-c, --compile', 'Compile input into output')
   .option('-d, --decompile', 'De-compile input into output')
-  .option('-t1, --twine1', 'Enable Twine 1 processing')
-  .option('-name <storyFormatName>', 'Name of the Twine 1 story format (needed for `code.js` inclusion)')
-  .option('-codejs <codeJSFile>', 'Twine 1 code.js file for use with Twine 1 HTML', (value) => {
+  .option('--twine1', 'Enable Twine 1 processing')
+  .option('--name <storyFormatName>', 'Name of the Twine 1 story format (needed for `code.js` inclusion)')
+  .option('--codejs <codeJSFile>', 'Twine 1 code.js file for use with Twine 1 HTML', (value) => {
     // Does the input file exist?
     if (isFile(value) === false) {
       // We cannot do anything without valid input.
@@ -67,7 +67,7 @@ program
 
     return value;
   })
-  .option('-engine <engineFile>', 'Twine 1 engine.js file for use with Twine 1 HTML', (value) => {
+  .option('--engine <engineFile>', 'Twine 1 engine.js file for use with Twine 1 HTML', (value) => {
     // Does the input file exist?
     if (isFile(value) === false) {
       // We cannot do anything without valid input.
@@ -76,7 +76,7 @@ program
 
     return value;
   })
-  .option('-header <headerFile>', 'Twine 1 header.html file for use with Twine 1 HTML', (value) => {
+  .option('--header <headerFile>', 'Twine 1 header.html file for use with Twine 1 HTML', (value) => {
     // Does the input file exist?
     if (isFile(value) === false) {
       // We cannot do anything without valid input.

package/test/CLI/CLI.test.js

@@ -27,12 +27,12 @@ describe('CLI', () => {
   });
 
   it('Twine 1 - compile: Twee 3 + Twine 1 engine.js + Twine 1 code.js + Twine 1 header.html', () => {
-    shell.exec(`node ${currentPath}/src/extwee.js -t1 -c -i ${testFilePath}/example6.twee -o ${testFilePath}/output/test3.html -codejs ${testFilePath}/twine1/code.js -engine ${testFilePath}/twine1/engine.js -header ${testFilePath}/twine1/header.html -name Test`);
+    shell.exec(`node ${currentPath}/src/extwee.js --twine1 -c -i ${testFilePath}/example6.twee -o ${testFilePath}/output/test3.html --codejs ${testFilePath}/twine1/code.js --engine ${testFilePath}/twine1/engine.js --header ${testFilePath}/twine1/header.html --name Test`);
     expect(shell.test('-e', `${testFilePath}/output/test3.html`)).toBe(true);
   });
 
   it('Twine 1 - de-compile: Twine 1 HTML into Twee 3', () => {
-    shell.exec(`node ${currentPath}/src/extwee.js -t1 -d -i ${testFilePath}/twine1Test.html -o ${testFilePath}/output/test.twee`);
+    shell.exec(`node ${currentPath}/src/extwee.js --twine1 -d -i ${testFilePath}/twine1Test.html -o ${testFilePath}/output/test.twee`);
     expect(shell.test('-e', `${testFilePath}/output/test.twee`)).toBe(true);
   });
 

package/test/Config/Config.test.js

@@ -0,0 +1,46 @@
+import {reader as ConfigReader} from '../../src/Config/reader.js';
+import {parser as ConfigParser} from '../../src/Config/parser.js';
+
+describe('src/Config/reader.js', () => {
+    describe('reader()', () => {
+        it('should throw an error if the file does not exist', () => {
+            expect(() => ConfigReader('non-existent-file.json')).toThrow('Error: File non-existent-file.json not found');
+        });
+
+        it('should throw an error if the file is not a valid JSON file', () => {
+            expect(() => ConfigReader('test/Config/files/invalid.json')).toThrow();
+        });
+
+        it('should return the parsed JSON contents of the file', () => {
+            const contents = ConfigReader('test/Config/files/valid.json');
+            expect(contents).toEqual({
+                "story-format": 'Harlowe',
+                "story-title": "My Story",
+                "story-version": "2.0.1"
+            });
+        });
+    });
+
+    describe('parser()', () => {
+
+        it('should throw an error if the object is not a valid JSON object', () => {
+            expect(() => ConfigParser('{')).toThrow();
+        });
+
+        it('should extract the StoryFormat, StoryTitle, and StoryVersion from the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/valid.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormat).toEqual('Harlowe');
+            expect(contents.StoryTitle).toEqual('My Story');
+            expect(contents.StoryVersion).toEqual('2.0.1');
+        });
+
+        it('should not extract the StoryFormat, StoryTitle, and StoryVersion if they do not exist in the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/empty.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormat).toBeNull();
+            expect(contents.StoryTitle).toBeNull();
+            expect(contents.StoryVersion).toBeNull();
+        });
+    });
+});

package/test/Config/files/empty.json

@@ -0,0 +1,3 @@
+{
+    "some": "value"
+}

package/test/Config/files/invalid.json

@@ -0,0 +1 @@
+invalid

package/test/Config/files/valid.json

@@ -0,0 +1,5 @@
+{
+    "story-format": "Harlowe",
+    "story-title": "My Story",
+    "story-version": "2.0.1"
+}

package/types/Config/parser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parses a JSON object and extracts the StoryFormat, StoryTitle and StoryVersion.
+ * @param {object} obj Incoming JSON object.
+ * @returns {object} An object containing the extracted results.
+ */
+export function parser(obj: object): object;

package/types/Config/reader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Read a JSON file and return its contents.
+ * @param {string} path Path to the JSON file.
+ * @returns {object} Parsed JSON object.
+ * @throws {Error} If the file does not exist.
+ * @throws {Error} If the file is not a valid JSON file.
+ * @example
+ * const contents = reader('test/Config/files/valid.json');
+ * console.log(contents); // {"story-format": 'Harlowe', "story-title": "My Story"}
+ */
+export function reader(path: string): object;

package/types/Passage.d.ts

@@ -68,12 +68,12 @@ export default class Passage {
      * @param {object} m - Replacement object
      * @throws {Error} Metadata must be an object literal!
      */
-    set metadata(m: any);
+    set metadata(m: object);
     /**
      * Metadata
      * @returns {object} Metadata
      */
-    get metadata(): any;
+    get metadata(): object;
     /**
      * @param {string} t - Replacement text
      * @throws {Error} Text should be a String!

package/types/Story.d.ts

@@ -50,12 +50,12 @@ export class Story {
     /**
      * @param {object} a - Replacement tag colors
      */
-    set tagColors(a: any);
+    set tagColors(a: object);
     /**
      * Tag Colors object (each property is a tag and its color)
      * @returns {object} tag colors array
      */
-    get tagColors(): any;
+    get tagColors(): object;
     /**
      * @param {string} i - Replacement IFID.
      */
@@ -86,12 +86,12 @@ export class Story {
     /**
      * @param {object} o - Replacement metadata
      */
-    set metadata(o: any);
+    set metadata(o: object);
     /**
      * Metadata of Story.
      * @returns {object} metadata of story
      */
-    get metadata(): any;
+    get metadata(): object;
     /**
      * @param {string} f - Replacement format
      */
@@ -226,5 +226,5 @@ export class Story {
     #private;
 }
 export const creatorName: "extwee";
-export const creatorVersion: "2.2.4";
+export const creatorVersion: "2.2.5";
 import Passage from './Passage.js';