extwee 2.2.2 → 2.2.4

package/eslint.config.js

@@ -0,0 +1,19 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import jest from "eslint-plugin-jest";
+
+export default [
+  {
+    languageOptions: { 
+        globals: {
+            ...globals.browser,
+            ...globals.node,
+            ...globals.jest
+        }
+    },
+    plugins: {
+        jest: jest
+    }
+  },
+  pluginJs.configs.recommended,
+];

package/jest.config.json

@@ -0,0 +1,5 @@
+{
+    "bail": 1,
+    "verbose": true,
+    "collectCoverage": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -8,12 +8,13 @@
     "extwee": "src/extwee.js"
   },
   "scripts": {
-    "test": "jest --runInBand --coverage --colors",
+    "test": "jest --runInBand",
     "lint": "eslint ./src/**/*.js --fix",
     "lint:test": "eslint ./test/**/*.test.js --fix",
     "build:web": "webpack",
-    "build:bin": "esbuild ./src/extwee.js --bundle --platform=node --target=node12 --outfile=out.js && pkg -t node18-macos-x64 out.js --output ./build/extwee && rm out.js",
-    "all": "npm run lint && npm run lint:test && npm run test"
+    "build:bin": "esbuild ./src/extwee.js --bundle --platform=node --target=node12 --outfile=out.js",
+    "gen-types": "npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types",
+    "all": "npm run lint && npm run lint:test && npm run test && npm run gen-types"
   },
   "keywords": [
     "twine",
@@ -23,37 +24,33 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^12.0.0",
+    "commander": "^12.1.0",
+    "graphemer": "^1.4.0",
     "html-entities": "^2.5.2",
-    "node-html-parser": "^6.1.12",
+    "node-html-parser": "^6.1.13",
     "pickleparser": "^0.2.1",
-    "semver": "^7.6.0",
-    "uuid": "^9.0.1"
+    "semver": "^7.6.2",
+    "uuid": "^10.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.23.4",
-    "@babel/core": "^7.24.0",
-    "@babel/eslint-parser": "^7.23.10",
-    "@babel/eslint-plugin": "^7.23.5",
-    "@babel/preset-env": "^7.24.0",
-    "@types/uuid": "^9.0.7",
+    "@babel/cli": "^7.25.6",
+    "@babel/core": "^7.24.6",
+    "@babel/preset-env": "^7.24.6",
+    "@eslint/js": "^9.10.0",
+    "@types/uuid": "^10.0.0",
     "babel-loader": "^9.1.3",
-    "clean-jsdoc-theme": "^4.2.17",
-    "core-js": "^3.36.0",
-    "esbuild": "^0.20.1",
-    "eslint": "^8.57.0",
-    "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jest": "^27.9.0",
-    "eslint-plugin-jsdoc": "^48.2.0",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^6.1.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",
     "jest": "^29.7.0",
-    "pkg": "^5.8.1",
     "regenerator-runtime": "^0.14.1",
     "shelljs": "^0.8.5",
-    "typescript": "^5.4.2",
-    "webpack": "^5.90.3",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.4.0",
+    "webpack": "^5.91.0",
     "webpack-cli": "^5.1.4"
   },
   "repository": {

package/src/JSON/parse.js

@@ -61,7 +61,7 @@ function parse (jsonString) {
   try {
     result = JSON.parse(jsonString);
   } catch (error) {
-    throw new Error('Invalid JSON!');
+    throw new Error(`Error: JSON could not be parsed! ${error.message}`);
   }
 
   // Name

package/src/Story.js

@@ -3,7 +3,9 @@ import { generate as generateIFID } from './IFID/generate.js';
 import { encode } from 'html-entities';
 
 const creatorName = 'extwee';
-const creatorVersion = '2.2.2';
+
+// Set the creator version.
+const creatorVersion = '2.2.4';
 
 /**
  * Story class.
@@ -396,6 +398,22 @@ class Story {
       return this.#_passages.length;
     }
 
+    // Parse Start
+    if (p.name === 'Start') {
+      // Have we already encountered StoryData?
+      if (this.start == '') {
+        // Set internal start based on Start.
+        /**
+         * Four possible scenarios:
+         * 1. StoryData has already been encountered, and we will never get here.
+         * 2. StoryData exists and will be encountered after Start.
+         * 3. StoryData does not exist.
+         * 4. Start is the first and only passage.
+         */
+        this.start = p.name;
+      }
+    }
+
     // This is not StoryData or StoryTitle.
     // Push the passage to the array.
     return this.#_passages.push(p);
@@ -636,9 +654,6 @@ class Story {
       storyData += ` ifid="${ generateIFID() }"`;
     }
 
-    // 'Start' passage (if there is not a 'start' value set).
-    let startPassagePID = null;
-
     // Passage Identification (PID) counter.
     // (Twine 2 starts with 1, so we mirror that.)
     let PIDcounter = 1;
@@ -655,35 +670,25 @@ class Story {
         startPID = PIDcounter;
       }
 
-      // Have we found the 'Start' passage?
-      if (p.name === 'Start') {
-        // If so, set the PID based on index.
-        startPassagePID = PIDcounter;
-      }
-
       // Increase and keep looking.
       PIDcounter++;
     });
 
-    // startnode: (integer) Optional.
-    //
-    // Maps to <tw-storydata startnode>.
-    //
-    // Check if startnode exists.
-    if(this.start !== '') {
-      // Set starting passage PID.
-      storyData += ` startnode="${startPID}"`;
+    // Are there any passages?
+    if (passages.length === 0) {
+      // No passages, so we can't set a startnode.
+      startPID = 0;
     }
 
     /**
-     * If we came from Twee or another source, we might not have a start value.
-     * 
-     * We might, however, have a passage with the name "Start".
+     * Multiple possible scenarios:
+     * 1. No passages. (StartPID is 0.)
+     * 2. Start is the first or only passage. (StartPID is 1.)
+     * 3. Starting passage is not the first passage. (StartPID is > 1.)
      */
-    if(this.start === '' && startPassagePID !== null) {
-      // Set starting passage PID.
-      storyData += ` startnode="${startPassagePID}"`;
-    }
+
+    // startnode: (integer) Optional. The PID of the starting passage.
+    storyData += ` startnode="${startPID}"`;
     
     // creator: (string) Optional. The name of the program that created the story.
     // Maps to <tw-storydata creator>.

package/src/StoryFormat/parse.js

@@ -90,8 +90,8 @@ function parse (contents) {
   // Attempt to parse the JSON.
   try {
     jsonContent = JSON.parse(contents);
-  } catch (event) {
-    throw new Error('Error: Unable to parse Twine 2 JSON chunk!');
+  } catch (error) {
+    throw new Error(`Error: Unable to parse Twine 2 JSON chunk! ${error.message}`);
   }
 
   /**

package/src/TWS/parse.js

@@ -28,8 +28,9 @@ 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 Error('Buffer does not contain Python pickle data!');
+    throw new TypeError('Error: Buffer does not contain Python pickle data!');
   }
 
   // Create Story object.

package/src/Twee/parse.js

@@ -68,7 +68,9 @@ function parse (fileContents) {
       // Try to parse the metadata
       try {
         metadata = JSON.parse(metadata);
-      } catch (event) {
+      } catch (error) {
+        console.info(`Info: Metadata could not be parsed. Setting to empty object. Reported error: ${error.message}`);
+        metadata = {};
       }
     } else {
       // There wasn't any metadata, so set default

package/test/{Passage.test.js → Objects/Passage.test.js}

@@ -1,4 +1,4 @@
-import Passage from '../src/Passage.js';
+import Passage from '../../src/Passage.js';
 import { parse as HTMLParser } from 'node-html-parser';
 
 describe('Passage', () => {
@@ -218,8 +218,8 @@ describe('Passage', () => {
     });
 
     it('Should escape meta-characters safely in Twee header', function () {
-      const p = new Passage('Where do tags begin? [well',  '', ['hmm']);
-      expect(p.toTwee().includes('Where do tags begin? \[well [hmm]')).toBe(true);
+      const p = new Passage('Where do tags begin? [well', '', ['hmm']);
+      expect(p.toTwee().includes('Where do tags begin? [well [hmm]')).toBe(true);
     });
 
     it('Should produce valid HTML attributes', function () {
@@ -232,7 +232,7 @@ describe('Passage', () => {
       expect(d.querySelector('tw-passagedata').getAttribute('tags')).toBe('&tag "bad"');
       expect(d.querySelector('tw-passagedata').getAttribute('position')).toBe('100,100');
       // Use Twine 2 result.
-      const s = `<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>`;
+      const s = '<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>';
       // Parse HTML.
       const t = new HTMLParser(s);
       // Test Twine 2 attributes.

package/test/{Story.test.js → Objects/Story.test.js}

@@ -1,9 +1,9 @@
-import { Story, creatorName, creatorVersion } from '../src/Story.js';
-import Passage from '../src/Passage';
-import { parse as parseTwee } from '../src/Twee/parse.js';
+import { Story, creatorName, creatorVersion } from '../../src/Story.js';
+import Passage from '../../src/Passage.js';
+import { parse as parseTwee } from '../../src/Twee/parse.js';
 import { readFileSync } from 'node:fs';
 import { parse as HTMLParser } from 'node-html-parser';
-import { generate as generateIFID } from '../src/IFID/generate.js';
+import { generate as generateIFID } from '../../src/IFID/generate.js';
 
 // Pull the name and version of this project from package.json.
 // These are used as the 'creator' and 'creator-version'.
@@ -311,6 +311,27 @@ describe('Story', () => {
       // Test for format.
       expect(s.formatVersion).toBe('2.28.2');
     });
+
+    it('addPassage() - should override StoryData: zoom', function () {
+      // Generate object.
+      const o = {
+        zoom: 0.5
+      };
+
+      // Add the passage.
+      s.addPassage(new Passage('StoryData', JSON.stringify(o)));
+
+      // Test for zoom.
+      expect(s.zoom).toBe(0.5);
+    });
+
+    it('addPassage() - should set start if Start passage and StoryData is not present', function () {
+      // Add the passage.
+      s.addPassage(new Passage('Start'));
+
+      // Test for start.
+      expect(s.start).toBe('Start');
+    });
   });
 
   describe('removePassageByName()', () => {
@@ -444,7 +465,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for format in metadata, should not exist.
-      expect(t.includes(`"'format":`)).not.toBe(true);
+      expect(t.includes('"\'format":')).not.toBe(true);
     });
 
     it('Should not generate formatVersion if empty', function () {
@@ -461,7 +482,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for formatVersion in metadata, should not exist.
-      expect(t.includes(`"'format-version":`)).not.toBe(true);
+      expect(t.includes('"\'format-version":')).not.toBe(true);
     });
 
     it('Should not generate zoom if zero', function () {
@@ -478,7 +499,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for zoom in metadata, should not exist.
-      expect(t.includes(`"'zoom":`)).not.toBe(true);
+      expect(t.includes('"\'zoom":')).not.toBe(true);
     });
 
     it('Should not generate start if empty', function () {
@@ -495,7 +516,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for start in metadata, should not exist.
-      expect(t.includes(`"'start":`)).not.toBe(true);
+      expect(t.includes('"\'start":')).not.toBe(true);
     });
 
     it('Should detect StoryTitle text', function () {
@@ -726,17 +747,22 @@ describe('Story', () => {
       expect(result.includes('zoom="2"')).toBe(true);
     });
 
-    it('Should encode start', () => {
+    it('Should encode startnode as Start as single and only passage', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));
-      // Set start.
-      s.start = 'Start';
       // Create HTML.
       const result = s.toTwine2HTML();
       // Expect the start to be encoded.
       expect(result.includes('startnode="1"')).toBe(true);
     });
 
+    it('Should encode startnode as 0 if no passages', () => {
+        // Create HTML.
+        const result = s.toTwine2HTML();
+        // Expect the start to be encoded.
+        expect(result.includes('startnode="0"')).toBe(true);
+      });
+
     it('Should encode start if property is not set but Start passage is', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));
@@ -781,7 +807,7 @@ describe('Story', () => {
       expect(result.includes(`creator-version="${creatorVersion}"`)).not.toBe(true);
     });
 
-   it('Should not encode creator if not set', () => {
+    it('Should not encode creator if not set', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));
       // Set start.
@@ -793,7 +819,6 @@ describe('Story', () => {
       // Expect the creator to be encoded.
       expect(result.includes(`creator="${creatorName}"`)).not.toBe(true);
     });
-
   });
 
   describe('toTwine1HTML()', function () {
@@ -828,7 +853,7 @@ describe('Story', () => {
       // Expect correct name attribute for tw-passagedata.
       expect(root.querySelector('tw-passagedata').getAttribute('name')).toBe('"Test"');
       // Use Twine 2 result.
-      const s2 = `<tw-storydata name="&quot;Abuse&quot; &amp;test" startnode="1" creator="Twine" creator-version="2.8.1" format="Harlowe" format-version="3.3.8" ifid="452A9D80-C759-42C5-B001-5B861A2410C5" options="" tags="" zoom="1" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="300,100" size="100,100"></tw-passagedata></tw-storydata>`;
+      const s2 = '<tw-storydata name="&quot;Abuse&quot; &amp;test" startnode="1" creator="Twine" creator-version="2.8.1" format="Harlowe" format-version="3.3.8" ifid="452A9D80-C759-42C5-B001-5B861A2410C5" options="" tags="" zoom="1" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="300,100" size="100,100"></tw-passagedata></tw-storydata>';
       // Parse HTML.
       const root2 = HTMLParser(s2);
       // Expect correct name attribute for tw-storydata.

package/test/{StoryFormat.test.js → Objects/StoryFormat.test.js}

@@ -1,4 +1,4 @@
-import StoryFormat from '../src/StoryFormat.js';
+import StoryFormat from '../../src/StoryFormat.js';
 
 describe('StoryFormat', () => {
   describe('Default values', () => {
@@ -153,7 +153,7 @@ describe('StoryFormat', () => {
   describe('toString', () => {
     it('Should return string representation', () => {
       const sf = new StoryFormat();
-      expect(sf.toString()).toBe(JSON.stringify(sf, null, "\t"));
+      expect(sf.toString()).toBe(JSON.stringify(sf, null, '\t'));
     });
   });
 });

package/test/TWS/Parse.test.js

@@ -11,9 +11,9 @@ describe('TWSParser', () => {
       let r = null;
 
       beforeAll(() => {
-        const contents = fs.readFileSync('test/TWS/TWSParser/Example1.tws', 'binary');
-        const b = Buffer.from(contents, 'binary');
-        r = parseTWS(b);
+        const contents = fs.readFileSync('test/TWS/TWSParser/Example1.tws');
+        //const b = Buffer.from(contents, 'binary');
+        r = parseTWS(contents);
       });
 
       it('Should parse StoryTitle', function () {

package/test/Twee/Twee.Parse.test.js

@@ -15,6 +15,14 @@ describe('Twee', () => {
       expect(() => { parseTwee('()()'); }).toThrow();
     });
 
+    it('Should ignore malformed passage metadata and create empty object', () => {
+      const fr = readFileSync('test/Twee/TweeParser/malformed.twee', 'utf-8');
+      const story = parseTwee(fr);
+      const metadata = story.getPassageByName('Start').metadata;
+      const numberOfMetadataProperties = Object.keys(metadata).length;
+      expect(numberOfMetadataProperties).toBe(0);
+    });
+
     it('Should throw error if it detects malformed passage headers', () => {
       expect(() => { parseTwee('::{}[]\nNo name'); }).toThrow();
     });
@@ -72,5 +80,14 @@ describe('Twee', () => {
       const p = story.getPassageByName('StoryAuthor');
       expect(p).not.toBe(null);
     });
+
+    it('Should parse single and only passage Start', () => {
+      const fr = readFileSync('test/Twee/TweeParser/start.twee', 'utf-8');
+      const story = parseTwee(fr);
+      const p = story.getPassageByName('Start');
+      const startingPassage = story.start;
+      expect(p).not.toBe(null);
+      expect(startingPassage).toBe('Start');
+    });
   });
 });

package/test/Twee/TweeParser/cursed.twee

@@ -0,0 +1,16 @@
+:: StoryTitle
+Cursed
+
+
+:: StoryData
+{
+  "ifid": "22F25A58-7062-4927-95B6-F424DDB2EC65",
+  "format": "Harlowe",
+  "format-version": "3.3.8",
+  "start": "[Hello] {world} \\\\",
+  "zoom": 1
+}
+
+
+:: \[Hello\] \{world\} \\\\ {"position":"400,200","size":"100,100"}
+\:: Extra header

package/test/Twee/TweeParser/malformed.twee

@@ -0,0 +1,2 @@
+:: Start {"position":"353,60""size":"100,100"}
+Malformed metadata.

package/test/Twee/TweeParser/start.twee

@@ -0,0 +1,2 @@
+:: Start
+Technically, a valid story.

package/types/IFID/generate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generates an Interactive Fiction Identification (IFID) based the Treaty of Babel.
+ *
+ * For Twine works, the IFID is a UUID (v4) in uppercase.
+ * @see Treaty of Babel ({@link https://babel.ifarchive.org/babel_rev11.html#the-ifid-for-an-html-story-file})
+ * @function generate
+ * @description Generates a new IFID.
+ * @returns {string} IFID
+ * @example
+ * const ifid = generate();
+ * console.log(ifid);
+ * // => 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6'
+ */
+export function generate(): string;

package/types/JSON/parse.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parse JSON representation into Story.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md Twine 2 JSON Specification}
+ * @function parse
+ * @param {string} jsonString - JSON string to convert to Story.
+ * @throws {Error} - Invalid JSON!
+ * @returns {Story} Story object.
+ * @example
+ * const jsonString = `{
+ *  "name": "My Story",
+ *  "start": "First Passage",
+ *  "ifid": "A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6",
+ *  "format": "SugarCube",
+ *  "formatVersion": "2.31.0",
+ *  "creator": "Twine",
+ *  "creatorVersion": "2.3.9",
+ *  "zoom": 1,
+ *  "passages": [
+ *   {
+ *    "name": "First Passage",
+ *    "tags": "",
+ *    "metadata": "",
+ *    "text": "This is the first passage."
+ *   },
+ *  ]
+ * }`;
+ * const story = parse(jsonString);
+ * console.log(story);
+ * // => Story {
+ * //      name: 'My Story',
+ * //      start: 'First Passage',
+ * //      IFID: 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6',
+ * //      format: 'SugarCube',
+ * //      formatVersion: '2.31.0',
+ * //      creator: 'Twine',
+ * //      creatorVersion: '2.3.9',
+ * //      zoom: 1,
+ * //      tagColors: {},
+ * //      metadata: {},
+ * //      passages: [
+ * //        Passage {
+ * //          name: 'First Passage',
+ * //          tags: '',
+ * //          metadata: '',
+ * //          text: 'This is the first passage.'
+ * //        }
+ * //      ]
+ * //    }
+ */
+export function parse(jsonString: string): Story;
+import { Story } from '../Story.js';