synthetic-factorio 0.0.1 → 0.2.4

package/README.md

@@ -1,45 +1,47 @@
-# Synthetic Factorio
-
-Synthetic Factorio nodeJS runtime for unit testing mods.
-
-This is **not** a Factorio emulator, it is not a game that can be played.
-
-```typescript
-import { ModManager, FactorioEngine } from 'synthetic-factorio';
-
-const manager = new ModManager();
-// install vanilla "mod" data from https://github.com/wube/factorio-data (requires git CLI)
-await manager.installVanillaMods();
-// install mod by name from mod portal (requires FACTORIO_USERNAME and FACTORIO_TOKEN env variables)
-await manager.installPortalMod('SimpleSeablock');
-// install a mod in development from local files
-manager.installDirectoryMod('my-mod', './my-mod-files', { clearCache: true });
-
-// initialize the synthetic factorio engine and specify the mods that should be active
-// vanilla "mods" need to be specified, including "base", however "core" does not need to be listed
-const engine = new FactorioEngine({
-    mods: ['base', 'space-age', 'quality', 'recycler', 'elevated-rails', 'my-mod']
-});
-// run all mods through their settings phase
-engine.runSettingsPhase();
-// customize settings for your specific test run
-engine.setSettings({ startup: { 'my-mod-setting': true } });
-// run all mods through their data phase
-engine.runDataPhase();
-
-// read the data.raw collection and run test assertions
-console.log(engine.getRawData()['item']['stone-furnace']);
-
-// run control phase - NOTE: control phase support is currently very limited
-engine.runControlPhase(['my-mod']);
-
-// run any registered on_init callbacks
-engine.triggerInit();
-
-// trigger an event with the payload of your choice
-// Partial on the generic and casts on the sub-properties are recommended to avoid the need to setup the entire event payload
-engine.triggerEvent<Partial<runtime.on_chunk_generated>>(defines.events.on_chunk_generated, {
-    position: { x: 0, y: 0 },
-    surface: { name: 'nauvis' } as runtime.LuaSurface,
-});
-```
+# Synthetic Factorio
+
+<!--Hidden version bump 4-->
+
+Synthetic Factorio nodeJS runtime for unit testing mods.
+
+This is **not** a Factorio emulator, it is not a game that can be played.
+
+```typescript
+import { ModManager, FactorioEngine } from 'synthetic-factorio';
+
+const manager = new ModManager();
+// install vanilla "mod" data from https://github.com/wube/factorio-data (requires git CLI)
+await manager.installVanillaMods();
+// install mod by name from mod portal (requires FACTORIO_USERNAME and FACTORIO_TOKEN env variables)
+await manager.installPortalMod('SimpleSeablock');
+// install a mod in development from local files
+manager.installDirectoryMod('my-mod', './my-mod-files', { clearCache: true });
+
+// initialize the synthetic factorio engine and specify the mods that should be active
+// vanilla "mods" need to be specified, including "base", however "core" does not need to be listed
+const engine = new FactorioEngine({
+    mods: ['base', 'space-age', 'quality', 'recycler', 'elevated-rails', 'my-mod']
+});
+// run all mods through their settings phase
+engine.runSettingsPhase();
+// customize settings for your specific test run
+engine.setSettings({ startup: { 'my-mod-setting': true } });
+// run all mods through their data phase
+engine.runDataPhase();
+
+// read the data.raw collection and run test assertions
+console.log(engine.getRawData()['item']['stone-furnace']);
+
+// run control phase - NOTE: control phase support is currently very limited
+engine.runControlPhase(['my-mod']);
+
+// run any registered on_init callbacks
+engine.triggerInit();
+
+// trigger an event with the payload of your choice
+// Partial on the generic and casts on the sub-properties are recommended to avoid the need to setup the entire event payload
+engine.triggerEvent<Partial<runtime.on_chunk_generated>>(defines.events.on_chunk_generated, {
+    position: { x: 0, y: 0 },
+    surface: { name: 'nauvis' } as runtime.LuaSurface,
+});
+```

package/dist/ModManager.d.ts

@@ -7,6 +7,11 @@ export interface ModManagerOptions {
      * Working directory for files like mod downloads
      */
     workingDir?: string;
+    /**
+     * Function to accept diagnostic logging, if not supplied then no diagnostics will be logged. Can be verbose, primarily intended for troubleshooting
+     * @param message Message to be logged
+     */
+    logger?: (message: string) => void;
 }
 export interface ModInstallOptions {
     /**
@@ -44,6 +49,7 @@ export interface ModPortalDownloadOptions extends ModDownloadOptions {
 export declare class ModManager {
     readonly modDir: string;
     readonly workingDir: string;
+    readonly log: (message: string) => void;
     constructor(options?: ModManagerOptions);
     /**
      * Download all vanilla "mod" data from https://github.com/wube/factorio-data

package/dist/ModManager.js

@@ -16,9 +16,11 @@ const vanillaMods = ['core', 'base', 'quality', 'recycler', 'elevated-rails', 's
 export class ModManager {
     modDir;
     workingDir;
+    log;
     constructor(options) {
         this.modDir = options?.modDir || modDir();
         this.workingDir = options?.workingDir || workingDir();
+        this.log = options?.logger || (() => { });
     }
     /**
      * Download all vanilla "mod" data from https://github.com/wube/factorio-data
@@ -28,13 +30,17 @@ export class ModManager {
     async installVanillaMods(options) {
         const run = promisify(exec);
         const gitDir = path.join(this.workingDir, 'factorio-data');
+        this.log(`Installing vanilla mods at ${gitDir}`);
         if (existsSync(gitDir) && options?.clearDownload) {
+            this.log(`gitDir ${gitDir} exists, deleting`);
             rmSync(gitDir, { recursive: true });
         }
         if (existsSync(gitDir) && options?.checkLatest) {
+            this.log(`Vanilla mod repo exists at ${gitDir}, pulling latest`);
             await run('git pull', { cwd: gitDir });
         }
         if (!existsSync(gitDir)) {
+            this.log(`Vanilla mod repo does not exist at ${gitDir}, cloning`);
             mkdirSync(this.workingDir, { recursive: true });
             await run('git clone --depth=1 https://github.com/wube/factorio-data.git', { cwd: this.workingDir });
         }
@@ -50,12 +56,18 @@ export class ModManager {
      */
     installDirectoryMod(modName, sourcePath, options) {
         const targetPath = this.getModPath(modName);
+        this.log(`Installing mod ${modName} to ${targetPath} from ${sourcePath}`);
         if (existsSync(targetPath) && options?.clearCache) {
+            this.log(`Removing existing mod ${modName} at ${targetPath}`);
             rmSync(targetPath, { recursive: true });
         }
         if (!existsSync(targetPath)) {
+            this.log(`Copying mod ${modName} from ${sourcePath} to ${targetPath}`);
             cpSync(sourcePath, targetPath, { recursive: true });
         }
+        else {
+            this.log(`Mod ${modName} already exists at ${targetPath}`);
+        }
     }
     /**
      * Downloads and installs a mod from Factorio's mod portal.
@@ -64,24 +76,29 @@ export class ModManager {
      * @param options Mod Installation Optiions
      */
     async installPortalMod(modName, options) {
+        this.log(`Installing ${modName} from portal`);
         let modInfo = undefined;
         let targetVersion = undefined;
         const downloadDir = path.join(this.workingDir, 'downloads');
         mkdirSync(downloadDir, { recursive: true });
         if (options?.version) {
             targetVersion = options?.version;
+            this.log(`Mod ${modName} installed at specific version ${targetVersion}`);
         }
         else if (options?.checkLatest) {
             modInfo = await this.getModInfo(modName);
             targetVersion = modInfo.releases.slice(-1)[0].version;
+            this.log(`Mod ${modName} latest version is ${targetVersion}`);
         }
         let zipPath = undefined;
         if (targetVersion) {
             zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+            this.log(`Installing mod ${modName} at target version ${targetVersion} to ${zipPath}`);
         }
         else {
             const modFiles = await glob(`${modName}_*.zip`, { cwd: downloadDir });
             if (modFiles.length) {
+                this.log(`Found ${modFiles.length} existing versions of mod ${modName}`);
                 let latest = '0.0.0';
                 for (const file of modFiles) {
                     const version = file.replace(/\.zip$/, '').split('_').slice(-1)[0];
@@ -89,10 +106,16 @@ export class ModManager {
                         latest = version;
                     }
                 }
+                this.log(`Latest downloaded version of ${modName} is ${latest}`);
                 zipPath = path.join(downloadDir, `${modName}_${latest}.zip`);
+                this.log(`Using zip path ${zipPath} for ${modName}`);
+            }
+            else {
+                this.log(`Did not find previously-installed version of ${modName}`);
             }
         }
         if (zipPath && options?.clearDownload) {
+            this.log(`Deleting existing zip at ${zipPath} for ${modName}`);
             rmSync(zipPath);
         }
         if (!zipPath) {
@@ -100,7 +123,9 @@ export class ModManager {
                 modInfo = await this.getModInfo(modName);
             }
             targetVersion = modInfo.releases.slice(-1)[0].version;
+            this.log(`Found ${targetVersion} version of ${modName} from mod info`);
             zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+            this.log(`Using zip path ${zipPath} for ${modName}`);
         }
         if (!existsSync(zipPath)) {
             if (!modInfo) {
@@ -111,6 +136,7 @@ export class ModManager {
                 let url = modInfo.releases.find(r => r.version === targetVersion)?.download_url;
                 if (url) {
                     modDownloadUrl = url;
+                    this.log(`Download url for ${modName} at target version ${targetVersion} is ${modDownloadUrl}`);
                 }
                 else {
                     throw new Error(`Cannot find version ${targetVersion} of mod ${modName}`);
@@ -118,6 +144,7 @@ export class ModManager {
             }
             else {
                 modDownloadUrl = modInfo.releases.slice(-1)[0].download_url;
+                this.log(`Download url for ${modName} is ${modDownloadUrl}`);
             }
             if (!process.env.FACTORIO_USERNAME) {
                 throw new Error('Cannot download mod, env variable FACTORIO_USERNAME is not set');
@@ -135,10 +162,12 @@ export class ModManager {
         }
         let isOutdated = false;
         const targetPath = this.getModPath(modName);
+        this.log(`Using path ${targetPath} for ${modName}`);
         if (existsSync(targetPath) && targetVersion) {
             const modInfo = getModInfo(targetPath);
             if (modInfo.version != targetVersion) {
                 isOutdated = true;
+                this.log(`Mod ${modName} is outdated`);
             }
         }
         await this.installZipMod(modName, zipPath, { ...options, clearCache: isOutdated ? true : options?.clearCache });
@@ -146,10 +175,17 @@ export class ModManager {
             const dependencies = getDependencies(this.getModPath(modName));
             for (let dependency of dependencies.required) {
                 if (!vanillaMods.includes(dependency) && !options?.omitDependencies?.includes(dependency)) {
+                    this.log(`Installing dependency ${dependency} for ${modName}`);
                     await this.installPortalMod(dependency, { ...options, version: undefined });
                 }
+                else {
+                    this.log(`Not necessary to install dependency ${dependency} for ${modName}`);
+                }
             }
         }
+        else {
+            this.log(`Skipping dependencies for ${modName}`);
+        }
     }
     async getModInfo(modName) {
         const response = await fetch(`https://mods.factorio.com/api/mods/${modName}`);
@@ -163,16 +199,24 @@ export class ModManager {
      */
     async installZipMod(modName, sourcePath, options) {
         const targetPath = this.getModPath(modName);
+        this.log(`Installing ${modName} as zip from ${sourcePath} to ${targetPath}`);
         if (existsSync(targetPath) && options?.clearCache) {
+            this.log(`Deleting existing mod ${modName} at ${targetPath}`);
             rmSync(targetPath, { recursive: true });
         }
         if (!existsSync(targetPath)) {
             const unzipDir = path.join(this.workingDir, 'unzip');
+            this.log(`Unzipping ${modName} from ${sourcePath} to ${unzipDir}`);
             mkdirSync(unzipDir, { recursive: true });
             await extractZip(sourcePath, { dir: unzipDir });
             // Mod contents are in a single dir inside the zip file, and the dir can have any name so we need to handle that
-            let dirs = readdirSync(unzipDir);
-            renameSync(path.join(unzipDir, dirs[0]), targetPath);
+            const dirs = readdirSync(unzipDir);
+            const sourceDir = path.join(unzipDir, dirs[0]);
+            this.log(`Renaming ${sourceDir} to ${targetPath} for ${modName}`);
+            renameSync(sourceDir, targetPath);
+        }
+        else {
+            this.log(`Mod zip ${modName} already exists at ${targetPath}, no action needed`);
         }
     }
     getModPath(modName) {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "synthetic-factorio",
-  "version": "0.0.1",
+  "version": "0.2.4",
   "description": "Synthetic Factorio runtime for unit testing",
   "license": "ISC",
   "author": "Spencer Guest",
   "type": "module",
+  "repository": "https://github.com/sguest/synthetic-factorio",
   "scripts": {
     "test": "vitest",
     "test:ci": "vitest run",

package/util_scripts/data_setup.lua

@@ -1,18 +1,18 @@
--- define data and its extend and raw methods in lua, JS will later read this global to extract it
--- and may inject into data.raw to pre-populate the table
--- this is handled in lua instead of a JS callback for performance reasons
--- thousands of data.extend calls doing interop into JS is unusably slow
-
-data = data or {}
-data.raw = data.raw or {}
-
-function data.extend(self, values)
-    for i, value in ipairs(values) do
-        -- space-age tries to extend on the string "./data/__space-age__/sound/ambient/space/interlude-6/interlude-6.lua" 
-        -- (i.e. not a valid prototype object, just that string) so we need to gracefully handle invalid objects
-        if(value.name ~= nil and value.type ~= nil) then
-            data.raw[value.type] = data.raw[value.type] or {}
-            data.raw[value.type][value.name] = value
-        end
-    end
+-- define data and its extend and raw methods in lua, JS will later read this global to extract it
+-- and may inject into data.raw to pre-populate the table
+-- this is handled in lua instead of a JS callback for performance reasons
+-- thousands of data.extend calls doing interop into JS is unusably slow
+
+data = data or {}
+data.raw = data.raw or {}
+
+function data.extend(self, values)
+    for i, value in ipairs(values) do
+        -- space-age tries to extend on the string "./data/__space-age__/sound/ambient/space/interlude-6/interlude-6.lua" 
+        -- (i.e. not a valid prototype object, just that string) so we need to gracefully handle invalid objects
+        if(value.name ~= nil and value.type ~= nil) then
+            data.raw[value.type] = data.raw[value.type] or {}
+            data.raw[value.type][value.name] = value
+        end
+    end
 end

package/util_scripts/require_handler.lua

@@ -1,63 +1,63 @@
-local old_require = require
-
--- Wrapper around lua's require() to handle several Factorio-isms that are used by either vanilla or other mods that break under regular lua import rules
-
--- Mods can require() the same filename across different mods, and each one will load its own version
--- for example both mods base and space-age import "prototypes.tile.tiles" but refer to different files
--- The lua spec says such an import re-uses the existing module, even if package.paths has changed, so this is a workaround
--- Each mod starts in its own "context" defined by the global current_mod_root_path
--- Imports are first attempted from this root path, and then allowed to fall back on error to find things like lualib
--- If a mod explicitly imports from another mod using the double-underscore syntax, i.e. require("__modname__.file")
--- then current_mod_root_path is set to that mod, and then restored after
-
--- This cannot be handled by running mods in different lua contexts because mods can re-use globals that were previously declared
--- for example "apply_heat_pipe_glow" is defined in base.prototypes.entity.entities, but then used in space-age.prototypes.entity.entities without being re-declared
--- Therefore both mods need to load in the same lua context to preserve globals
-
-function require(name, ...)
-    local mod_changed = false
-    local previous_mod = current_mod_root_path
-    local new_name = name
-    if(string.find(name, '__')) then
-        mod_changed = true
-        local end_index = string.find(name, '__', 3)
-        current_mod_root_path = string.sub(name, 3, end_index - 1)
-    else
-        new_name = '__' .. current_mod_root_path .. '__.' .. name
-    end
-
-    -- This is the first load attempt that tries within the context of current_mod_root_path
-    local status, lib = pcall(old_require, new_name, ...)
-    if(mod_changed) then
-        current_mod_root_path = previous_mod
-    end
-    if(status) then return lib end
-
-    if(not string.find(lib, string.format("module '%s' not found", new_name), 1, true)) then
-        error(lib)
-    end
-
-    -- First import has failed, fall back to the exact name that was provided. Most commonly this is loading lualib
-    -- though it also handles the case where mods require paths from vanilla mods without specifying the mod prefix
-    status, lib = pcall(old_require, name, ...)
-    if(status) then return lib end
-    if(not string.find(lib, string.format("module '%s' not found", name), 1, true)) then
-        error(lib)
-    end
-
-    -- The factorio-data repo (https://github.com/wube/factorio-data) is the source for the data for the vanilla "mods"
-    -- This repo doesn't have things like graphics, sounds or menu simulations, but these are still require()d in many places from the existing lua files
-    -- The global suppress_require_errors is set during vanilla mod loading to suppress these
-    -- They are also suppressed when loading from the vanilla mod namespaces to handle loads from other mods
-    -- By default non-vanilla mods do not suppress, set the global suppress_require_errors = true to change
-    if(suppress_require_errors or string.find(name, '__base__') or string.find(name, '__space-age__', 1, true) or string.find(name, '__quality__') or string.find(name, '__recycler__') or string.find(name, '__elevated-rails__', 1, true)) then
-        if(string.find(name, 'graphics')) then
-            return { width = 1, height = 1, shift = util.by_pixel(1.0, 1.0), line_length = 5 }
-        end
-        if(string.find(name, 'menu-simulations', 1, true) or string.find(name, 'sound')) then
-            return {}
-        end
-    end
-
-    error(lib)
+local old_require = require
+
+-- Wrapper around lua's require() to handle several Factorio-isms that are used by either vanilla or other mods that break under regular lua import rules
+
+-- Mods can require() the same filename across different mods, and each one will load its own version
+-- for example both mods base and space-age import "prototypes.tile.tiles" but refer to different files
+-- The lua spec says such an import re-uses the existing module, even if package.paths has changed, so this is a workaround
+-- Each mod starts in its own "context" defined by the global current_mod_root_path
+-- Imports are first attempted from this root path, and then allowed to fall back on error to find things like lualib
+-- If a mod explicitly imports from another mod using the double-underscore syntax, i.e. require("__modname__.file")
+-- then current_mod_root_path is set to that mod, and then restored after
+
+-- This cannot be handled by running mods in different lua contexts because mods can re-use globals that were previously declared
+-- for example "apply_heat_pipe_glow" is defined in base.prototypes.entity.entities, but then used in space-age.prototypes.entity.entities without being re-declared
+-- Therefore both mods need to load in the same lua context to preserve globals
+
+function require(name, ...)
+    local mod_changed = false
+    local previous_mod = current_mod_root_path
+    local new_name = name
+    if(string.find(name, '__')) then
+        mod_changed = true
+        local end_index = string.find(name, '__', 3)
+        current_mod_root_path = string.sub(name, 3, end_index - 1)
+    else
+        new_name = '__' .. current_mod_root_path .. '__.' .. name
+    end
+
+    -- This is the first load attempt that tries within the context of current_mod_root_path
+    local status, lib = pcall(old_require, new_name, ...)
+    if(mod_changed) then
+        current_mod_root_path = previous_mod
+    end
+    if(status) then return lib end
+
+    if(not string.find(lib, string.format("module '%s' not found", new_name), 1, true)) then
+        error(lib)
+    end
+
+    -- First import has failed, fall back to the exact name that was provided. Most commonly this is loading lualib
+    -- though it also handles the case where mods require paths from vanilla mods without specifying the mod prefix
+    status, lib = pcall(old_require, name, ...)
+    if(status) then return lib end
+    if(not string.find(lib, string.format("module '%s' not found", name), 1, true)) then
+        error(lib)
+    end
+
+    -- The factorio-data repo (https://github.com/wube/factorio-data) is the source for the data for the vanilla "mods"
+    -- This repo doesn't have things like graphics, sounds or menu simulations, but these are still require()d in many places from the existing lua files
+    -- The global suppress_require_errors is set during vanilla mod loading to suppress these
+    -- They are also suppressed when loading from the vanilla mod namespaces to handle loads from other mods
+    -- By default non-vanilla mods do not suppress, set the global suppress_require_errors = true to change
+    if(suppress_require_errors or string.find(name, '__base__') or string.find(name, '__space-age__', 1, true) or string.find(name, '__quality__') or string.find(name, '__recycler__') or string.find(name, '__elevated-rails__', 1, true)) then
+        if(string.find(name, 'graphics')) then
+            return { width = 1, height = 1, shift = util.by_pixel(1.0, 1.0), line_length = 5 }
+        end
+        if(string.find(name, 'menu-simulations', 1, true) or string.find(name, 'sound')) then
+            return {}
+        end
+    end
+
+    error(lib)
 end