extwee 2.2.5 → 2.3.0

package/src/extwee.js

@@ -1,206 +1,31 @@
-#!/usr/bin/env node
+#! /usr/bin/env node
 
 /**
  * @file CLI for Extwee
  * @author Dan Cox
  */
 
-// Import functions we need.
-import {
-  parseTwine2HTML,
-  parseTwee,
-  parseStoryFormat,
-  parseTwine1HTML,
-  compileTwine2HTML,
-  compileTwine1HTML
-} from '../index.js';
+import { CommandLineProcessing } from "./CLI/CommandLineProcessing.js";
+import { ConfigFilePresent, ConfigFileProcessing } from "./CLI/ProcessConfig.js";
 
-// Import fs.
-import { readFileSync, writeFileSync, statSync } from 'node:fs';
-
-// Import Commander.
-import { Command, InvalidArgumentError } from 'commander';
-
-// Create a new Command.
-const program = new Command();
-
-/*
- * Check if a passed option is a valid file.
- * @function isFile
- * @description Check if a file exists.
- * @param {string} path - Path to file.
- * @returns {boolean} True if file exists, false if not.
- */
-const isFile = (path) => {
-  // set default.
-  let result = false;
-
-  try {
-    // Attempt tp get stats.
-    const stats = statSync(path);
-
-    // Return if path is a file.
-    result = stats.isFile();
-  } catch (e) {
-    // There was an error, so return false.
-    result = false;
-  }
-
-  // Return either the default (false) or the result (true).
-  return result;
-};
-
-program
-  .name('extwee')
-  .description('CLI for Extwee')
-  .option('-v, --version', '2.2.4')
-  .option('-c, --compile', 'Compile input into output')
-  .option('-d, --decompile', 'De-compile input into output')
-  .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.
-      throw new InvalidArgumentError(`Twine 1 code.js ${value} does not exist.`);
-    }
-
-    return 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.
-      throw new InvalidArgumentError(`Twine 1 engine.js ${value} does not exist.`);
-    }
-
-    return 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.
-      throw new InvalidArgumentError(`Twine 1 header.html ${value} does not exist.`);
-    }
-
-    return value;
-  })
-  .option('-s <storyformat>, --storyformat <storyformat>', 'Path to story format file for Twine 2', (value) => {
-    // Does the input file exist?
-    if (isFile(value) === false) {
-      // We cannot do anything without valid input.
-      throw new InvalidArgumentError(`Story format ${value} does not exist.`);
-    }
-
-    return value;
-  })
-  .option('-i <inputFile>, --input <inputFile>', 'Path to input file', (value) => {
-    // Does the input file exist?
-    if (isFile(value) === false) {
-      // We cannot do anything without valid input.
-      throw new InvalidArgumentError(`Input file ${value} does not exist.`);
-    }
-
-    return value;
-  })
-  .option('-o <outputFile>, --output <outputFile>', 'Path to output file');
-
-// Parse the passed arguments.
-program.parse(process.argv);
-
-// Create object of passed arguments parsed by Commander.
-const options = program.opts();
-
-/*
- * Prepare some (soon to be) global variables.
+/**
+ * As a command-line tool, Extwee can be invoked multiple ways.
+ * (1) Via NPX with command-line arguments. (process.argv.length > 2)
+ * (2) Via NPX in the presence of a `extwee.config.json` file.
  */
-// Check if Twine 1 is enabled.
-const isTwine1Mode = (options.twine1 === true);
-
-// Check if Twine 2 is enabled.
-const isTwine2Mode = (isTwine1Mode === false);
-
-// Check if de-compile mode is enabled.
-const isDecompileMode = (options.decompile === true);
-
-// Check if compile mode is enabled.
-const isCompileMode = (options.compile === true);
-
-// De-compile Twine 2 HTML into Twee 3 branch.
-// If -d is passed, -i and -o are required.
-if (isTwine2Mode === true && isDecompileMode === true) {
-  // Read the input HTML file.
-  const inputHTML = readFileSync(options.i, 'utf-8');
 
-  // Parse the input HTML file into Story object.
-  const storyObject = parseTwine2HTML(inputHTML);
-
-  // Write the output file from Story as Twee 3.
-  writeFileSync(options.o, storyObject.toTwee());
-
-  // Exit the process.
-  process.exit();
-}
-
-// Compile Twee 3 into Twine 2 HTML branch.
-// If -c is passed, -i, -o, and -s are required.
-if (isTwine2Mode === true && isCompileMode === true) {
-  // Read the input file.
-  const inputTwee = readFileSync(options.i, 'utf-8');
-
-  // Parse the input file.
-  const story = parseTwee(inputTwee);
-
-  // Read the story format file.
-  const inputStoryFormat = readFileSync(options.s, 'utf-8');
-
-  // Parse the story format file.
-  const parsedStoryFormat = parseStoryFormat(inputStoryFormat);
-
-  // Compile the story.
-  const Twine2HTML = compileTwine2HTML(story, parsedStoryFormat);
-
-  // Write the output file.
-  writeFileSync(options.o, Twine2HTML);
-
-  // Exit the process.
-  process.exit();
+// Check if the command line arguments are present.
+if(process.argv.length > 2) {
+    // Process the command line arguments.
+    CommandLineProcessing(process.argv);
+    // Exit the process.
+    process.exit(0);
 }
 
-// Compile Twee 3 into Twine 1 HTML branch.
-// Twine 1 compilation is complicated, so we have to check for all the required options.
-// * options.engine (from Twine 1 itself)
-// * options.header (from Twine 1 story format)
-// * options.name (from Twine 1 story format)
-// * options.codejs (from Twine 1 story format)
-if (isTwine1Mode === true && isCompileMode === true) {
-  // Read the input file.
-  const inputTwee = readFileSync(options.i, 'utf-8');
-
-  // Parse the input file.
-  const story = parseTwee(inputTwee);
-
-  // Does the engine file exist?
-  const Twine1HTML = compileTwine1HTML(story, options.engine, options.header, options.name, options.codejs);
-
-  // Write the output file.
-  writeFileSync(options.o, Twine1HTML);
-
-  // Exit the process.
-  process.exit();
-}
-
-// De-compile Twine 1 HTML into Twee 3 branch.
-if (isTwine1Mode === true && isDecompileMode === true) {
-  // Read the input HTML file.
-  const inputHTML = readFileSync(options.i, 'utf-8');
-
-  // Parse the input HTML file into Story object.
-  const storyObject = parseTwine1HTML(inputHTML);
-
-  // Write the output file from Story as Twee 3.
-  writeFileSync(options.o, storyObject.toTwee());
-
-  // Exit the process.
-  process.exit();
-}
+// Check if the config file exists.
+if(ConfigFilePresent()) {
+    // Process the config file.
+    ConfigFileProcessing();
+    // Exit the process.
+    process.exit(0);
+}

package/test/Config/Config.test.js

@@ -14,9 +14,10 @@ describe('src/Config/reader.js', () => {
         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"
+                "story-format": 'harlowe',
+                "mode": "decompile",
+                "input": "index.html",
+                "output": "index.twee"
             });
         });
     });
@@ -27,20 +28,49 @@ describe('src/Config/reader.js', () => {
             expect(() => ConfigParser('{')).toThrow();
         });
 
-        it('should extract the StoryFormat, StoryTitle, and StoryVersion from the JSON object', () => {
+        it('should extract the StoryFormat and StoryFormatVersion 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');
+            expect(contents.StoryFormat).toEqual('harlowe');
+            expect(contents.StoryFormatVersion).toEqual('latest');
+            expect(contents.Input).toEqual('index.html');
+            expect(contents.Output).toEqual('index.twee');
+            expect(contents.Mode).toEqual('decompile');
+            expect(contents.Twine1Project).toEqual(false);
         });
 
-        it('should not extract the StoryFormat, StoryTitle, and StoryVersion if they do not exist in the JSON object', () => {
+        it('should not extract options 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();
+            expect(contents.StoryFormatVersion).toBe('latest');
+            expect(contents.Input).toBeNull();
+            expect(contents.Output).toBeNull();
+            expect(contents.Mode).toBeNull();
+            expect(contents.Twine1Project).toBe(false);
+        });
+
+        it('should set StoryFormatVersion to "latest" if it is not present in the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/valid.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormatVersion).toEqual('latest');
+        });
+
+        it('should set Twine1Project to false if it is not present in the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/valid.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.Twine1Project).toEqual(false);
+        });
+
+        it('Should read story-format, story-format-version, and twine1-project if present', () => {
+            const jsonObject = ConfigReader('test/Config/files/full.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormat).toEqual('harlowe');
+            expect(contents.StoryFormatVersion).toEqual('3.2.0');
+            expect(contents.Input).toEqual('index.twee');
+            expect(contents.Output).toEqual('index.html');
+            expect(contents.Mode).toEqual('compile');
+            expect(contents.Twine1Project).toEqual(false);
         });
     });
 });

package/test/Config/files/full.json

@@ -0,0 +1,8 @@
+{
+    "story-format": "harlowe",
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format-version": "3.2.0",
+    "twine1-project": false
+}

package/test/Config/files/valid.json

@@ -1,5 +1,6 @@
 {
-    "story-format": "Harlowe",
-    "story-title": "My Story",
-    "story-version": "2.0.1"
+    "story-format": "harlowe",
+    "mode": "decompile",
+    "input": "index.html",
+    "output": "index.twee"
 }

package/test/Config/isDirectory.test.js

@@ -0,0 +1,44 @@
+import { isDirectory } from '../../src/CLI/isDirectory';
+import { statSync } from 'node:fs';
+
+jest.mock('node:fs');
+
+describe('isDirectory', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return true if the path is a directory', () => {
+        const mockStats = { isDirectory: jest.fn(() => true) };
+        statSync.mockReturnValue(mockStats);
+
+        const result = isDirectory('/valid/directory/path');
+        expect(statSync).toHaveBeenCalledWith('/valid/directory/path');
+        expect(mockStats.isDirectory).toHaveBeenCalled();
+        expect(result).toBe(true);
+    });
+
+    it('should return false if the path is not a directory', () => {
+        const mockStats = { isDirectory: jest.fn(() => false) };
+        statSync.mockReturnValue(mockStats);
+
+        const result = isDirectory('/valid/file/path');
+        expect(statSync).toHaveBeenCalledWith('/valid/file/path');
+        expect(mockStats.isDirectory).toHaveBeenCalled();
+        expect(result).toBe(false);
+    });
+
+    it('should return false and log an error if statSync throws an error', () => {
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        statSync.mockImplementation(() => {
+            throw new Error('Test error');
+        });
+
+        const result = isDirectory('/invalid/path');
+        expect(statSync).toHaveBeenCalledWith('/invalid/path');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Error: Test error'));
+        expect(result).toBe(false);
+
+        consoleErrorSpy.mockRestore();
+    });
+});

package/test/Config/isFile.test.js

@@ -0,0 +1,50 @@
+import { isFile } from '../../src/CLI/isFile.js';
+import { statSync } from 'node:fs';
+
+// Mock the statSync function from 'fs'.
+jest.mock('node:fs', () => ({
+    statSync: jest.fn(),
+}));
+
+describe('isFile', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return true if the path is a valid file', () => {
+        // Mock statSync to return an object with isFile() returning true.
+        statSync.mockReturnValue({
+            isFile: jest.fn(() => true),
+        });
+
+        const result = isFile('/path/to/file');
+        expect(result).toBe(true);
+        expect(statSync).toHaveBeenCalledWith('/path/to/file');
+    });
+
+    it('should return false if the path is not a valid file', () => {
+        // Mock statSync to return an object with isFile() returning false.
+        statSync.mockReturnValue({
+            isFile: jest.fn(() => false),
+        });
+
+        const result = isFile('/path/to/directory');
+        expect(result).toBe(false);
+        expect(statSync).toHaveBeenCalledWith('/path/to/directory');
+    });
+
+    it('should return false and log an error if statSync throws an error', () => {
+        // Mock statSync to throw an error.
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        statSync.mockImplementation(() => {
+            throw new Error('File not found');
+        });
+
+        const result = isFile('/invalid/path');
+        expect(result).toBe(false);
+        expect(statSync).toHaveBeenCalledWith('/invalid/path');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Error: Error: File not found'));
+
+        consoleErrorSpy.mockRestore();
+    });
+});

package/test/Config/loadStoryFormat.test.js

@@ -0,0 +1,101 @@
+import { loadStoryFormat } from "../../src/CLI/ProcessConfig/loadStoryFormat.js";
+import { isDirectory } from "../../src/CLI/isDirectory.js";
+import { isFile } from "../../src/CLI/isFile.js";
+import { readDirectories } from "../../src/CLI/ProcessConfig/readDirectories.js";
+import { readFileSync } from "node:fs";
+
+jest.mock("../../src/CLI/isDirectory.js");
+jest.mock("../../src/CLI/isFile.js");
+jest.mock("../../src/CLI/ProcessConfig/readDirectories.js");
+jest.mock("node:fs");
+
+describe("loadStoryFormat", () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it("should throw an error if the story-formats directory does not exist", () => {
+        isDirectory.mockReturnValueOnce(false);
+
+        expect(() => loadStoryFormat("Harlowe", "3.2.0")).toThrow(
+            "Error: story-formats directory does not exist. Consider running 'npx sfa-get' to download the latest story formats."
+        );
+    });
+
+    it("should throw an error if the named story format directory does not exist", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(false);
+
+        expect(() => loadStoryFormat("Harlowe", "3.2.0")).toThrow(
+            "Error: story format Harlowe does not exist in the story-formats directory."
+        );
+    });
+
+    it("should throw an error if the version directory does not exist", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true).mockReturnValueOnce(false);
+
+        expect(() => loadStoryFormat("Harlowe", "3.2.0")).toThrow(
+            "Error: story format Harlowe version 3.2.0 does not exist in the story-formats directory."
+        );
+    });
+
+    it("should throw an error if the format.js file does not exist in the version directory", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(false);
+
+        expect(() => loadStoryFormat("Harlowe", "3.2.0")).toThrow(
+            "Error: story format Harlowe version 3.2.0 does not have a format.js file."
+        );
+    });
+
+    it("should return the contents of the format.js file if all checks pass", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(true);
+        readFileSync.mockReturnValueOnce("format.js content");
+
+        const result = loadStoryFormat("Harlowe", "3.2.0");
+        expect(result).toBe("format.js content");
+    });
+
+    it("should handle 'latest' version and return the contents of the format.js file", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(false).mockReturnValueOnce(true);
+        readDirectories.mockReturnValueOnce(["3.2.0", "3.1.0"]);
+        readFileSync.mockReturnValueOnce("latest format.js content");
+
+        const result = loadStoryFormat("Harlowe", "latest");
+        expect(result).toBe("latest format.js content");
+        expect(readDirectories).toHaveBeenCalledWith("story-formats/Harlowe");
+    });
+
+    it("should throw an error if 'latest' version has no format.js file", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(false).mockReturnValueOnce(false);
+        readDirectories.mockReturnValueOnce(["3.2.0", "3.1.0"]);
+
+        expect(() => loadStoryFormat("Harlowe", "latest")).toThrow(
+            "Error: story format Harlowe version latest does not have a format.js file."
+        );
+    });
+
+    it("should read format.js file from the story format directory if it exists", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(true);
+        readDirectories.mockReturnValueOnce([]);
+        readFileSync.mockReturnValueOnce("latest format.js content");
+
+        const result = loadStoryFormat("Harlowe", "latest");
+        expect(result).toBe("latest format.js content");
+        expect(readFileSync).toHaveBeenCalledWith("story-formats/Harlowe/format.js", "utf-8");
+    });
+
+    it("should throw an error if the story format version is not 'latest' and version directories do not exist", () => {
+        isDirectory.mockReturnValueOnce(true).mockReturnValueOnce(true);
+        isFile.mockReturnValueOnce(false);
+        readDirectories.mockReturnValueOnce([]);
+
+        expect(() => loadStoryFormat("Harlowe", "latest")).toThrow(
+            `Error: story format Harlowe does not have any version directories.`
+        );
+    }
+    );
+});

package/test/Config/readDirectories.test.js

@@ -0,0 +1,68 @@
+import { readDirectories } from '../../src/CLI/ProcessConfig/readDirectories.js';
+import { readdirSync } from 'node:fs';
+import { isDirectory } from '../../src/CLI/isDirectory.js';
+
+jest.mock('node:fs');
+jest.mock('../../src/CLI/isDirectory.js');
+
+describe('readDirectories', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return an empty array and log an error if the directory does not exist', () => {
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        isDirectory.mockReturnValue(false);
+
+        const result = readDirectories('/nonexistent');
+
+        expect(result).toEqual([]);
+        expect(consoleErrorSpy).toHaveBeenCalledWith('Error: Directory /nonexistent does not exist.');
+        consoleErrorSpy.mockRestore();
+    });
+
+    it('should return an empty array and log an error if readdirSync throws an error', () => {
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        isDirectory.mockReturnValue(true);
+        readdirSync.mockImplementation(() => {
+            throw new Error('Permission denied');
+        });
+
+        const result = readDirectories('/restricted');
+
+        expect(result).toEqual([]);
+        expect(consoleErrorSpy).toHaveBeenCalledWith('Error reading directory /restricted:', expect.any(Error));
+        consoleErrorSpy.mockRestore();
+    });
+
+    it('should return an empty array if the directory is empty', () => {
+        isDirectory.mockReturnValue(true);
+        readdirSync.mockReturnValue([]);
+
+        const result = readDirectories('/empty');
+
+        expect(result).toEqual([]);
+    });
+
+    it('should return an array of directories', () => {
+        isDirectory.mockReturnValue(true);
+        readdirSync.mockReturnValue(['dir1', 'file1', 'dir2']);
+
+        isDirectory.mockImplementation((path) => {
+            return path === '/test/dir1' || path === '/test/dir2';
+        });
+
+        const result = readDirectories('/test');
+
+        expect(result).toEqual(['dir1', 'dir2']);
+    });
+    
+    it('should return an empty array if the result is not an array', () => {
+        isDirectory.mockReturnValue(true);
+        readdirSync.mockReturnValue('not an array');
+
+        const result = readDirectories('/test');
+
+        expect(result).toEqual([]);
+    });
+});

package/test/Objects/Passage.test.js

@@ -240,5 +240,10 @@ describe('Passage', () => {
       expect(t.querySelector('tw-passagedata').getAttribute('tags')).toBe('&tag "bad"');
       expect(t.querySelector('tw-passagedata').getAttribute('position')).toBe('100,100');
     });
+
+    it('Should escape double-colon at start of text when exporting to Twee', function () {
+      const p = new Passage('test', ':: nefarious');
+      expect(p.toTwee()).toBe(':: test\n\\:: nefarious\n\n');
+    });
   });
 });