modwright 0.1.0

package/dist/surfaces/skyrimse/logs.js

@@ -0,0 +1,241 @@
+const PLUGIN_MANAGER = "https://github.com/ianpatt/skse64/blob/master/skse64/PluginManager.cpp";
+const PAPYRUS_SAMPLE = "a captured Papyrus.0.log";
+const SKSE_PLUGIN_PREFIX = String.raw `^\s*plugin (?<dll>\S.*?) \((?<dataVersion>[0-9A-Fa-f]{8}) (?<plugin>.+?) (?<pluginVersion>[0-9A-Fa-f]{8})\) `;
+const SKSE_HANDLE_SUFFIX = String.raw `(?: (?<errCode>-?\d+))? \(handle \d+\)\s*$`;
+function skse(reason) {
+    return new RegExp(SKSE_PLUGIN_PREFIX + reason + SKSE_HANDLE_SUFFIX);
+}
+const SKSE = [
+    {
+        id: "skyrimse.skse.plugin-loaded",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "info",
+        category: "success",
+        pattern: skse("loaded correctly"),
+        explain: "An SKSE plugin loaded; the roll-call of these lines is the authoritative list of SKSE plugins live this run.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin", "pluginVersion"],
+    },
+    {
+        id: "skyrimse.skse.plugin-incompatible-runtime",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "version",
+        pattern: skse("disabled, incompatible with current version of the game"),
+        explain: "The plugin's declared compatible runtime versions do not include the running game; the commonest failure after a game update.",
+        hint: "Update the plugin to a build for this runtime, or downgrade the game to the version the plugin declares.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin"],
+    },
+    {
+        id: "skyrimse.skse.address-library-missing",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "version",
+        pattern: skse("disabled, address library needs to be updated"),
+        explain: "The plugin is version-independent through the Address Library, but no versionlib-*.bin for this runtime is installed under Data/SKSE/Plugins.",
+        hint: "Install the Address Library for SKSE Plugins release matching the game runtime; the file is versionlib-<runtime>.bin.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin"],
+    },
+    {
+        id: "skyrimse.skse.address-library-recompile",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "version",
+        pattern: skse("must be recompiled for new address library"),
+        explain: "The plugin declares the post-AE Address Library but not the version-5 format flag and predates the 1.7.99 format change; only its author can rebuild it.",
+        hint: "Look for an updated build of the plugin; nothing on the install side fixes this.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin"],
+    },
+    {
+        id: "skyrimse.skse.plugin-load-failed",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "load",
+        pattern: skse("couldn't load plugin"),
+        explain: "Windows refused to load the DLL; the errCode is GetLastError, which separates a missing dependency (126/193 shapes) from a broken binary.",
+        hint: "Check the plugin's own requirements (a Visual C++ runtime, another DLL beside it) and that the file is not blocked or truncated.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin", "errCode"],
+    },
+    {
+        id: "skyrimse.skse.plugin-refused",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "load",
+        pattern: skse("reported as incompatible during (?<phase>load|query)"),
+        explain: "The plugin's own load function returned false; it refused this environment itself. The 'query' wording dates the install to SKSE 2.0.x.",
+        hint: "The plugin's own log or message box says why; read it next.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin", "phase"],
+    },
+    {
+        id: "skyrimse.skse.plugin-no-version-data",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "warn",
+        category: "load",
+        pattern: skse("no version data"),
+        explain: "The DLL exports no SKSEPlugin_Version; SKSE logs it without treating it as an error, but the plugin is not running.",
+        hint: "A DLL in Data/SKSE/Plugins that is not an SKSE plugin at all, or one built against the pre-AE API; check what it is.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin"],
+    },
+    {
+        id: "skyrimse.skse.plugin-disabled-other",
+        game: "skyrimse",
+        sources: ["skse"],
+        severity: "error",
+        category: "load",
+        pattern: skse("(?<reason>disabled, (?:bad version data|no name specified|unsupported version independence method|only compatible with versions earlier than 1\\.6\\.629|requires newer script extender|fatal error occurred while (?:checking plugin compatibility|loading plugin|querying plugin))|LE plugin cannot be used with SE|does not appear to be an SKSE plugin)"),
+        explain: "SKSE disabled the plugin for the reason quoted; each reason maps to one check in PluginManager.cpp.",
+        seenIn: [PLUGIN_MANAGER],
+        extract: ["dll", "plugin", "reason"],
+    },
+];
+const SKSE_LOADER = [
+    {
+        id: "skyrimse.skse-loader.runtime",
+        game: "skyrimse",
+        sources: ["skse-loader"],
+        severity: "info",
+        category: "version",
+        pattern: /^\s*(?:skse64 loader (?<skse>\d[\w.]*)(?: \((?:release|steam)\))?|runtime: initialize \(version = (?<runtime>\d+\.\d+\.\d+))/i,
+        explain: "The SKSE build and the game runtime actually in play; the anchor for every compatibility check.",
+        seenIn: ["ModWright research (unverified: tolerant pattern)"],
+        extract: ["skse", "runtime"],
+    },
+];
+const PAPYRUS_PREFIX = String.raw `^\[\d{2}/\d{2}/\d{4} - \d{2}:\d{2}:\d{2}(?:AM|PM)\] `;
+function papyrus(body) {
+    return new RegExp(PAPYRUS_PREFIX + body);
+}
+const PAPYRUS = [
+    {
+        id: "skyrimse.papyrus.log-opened",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "info",
+        category: "load",
+        pattern: papyrus(String.raw `Papyrus log opened \(PC\)`),
+        explain: "A new game session's script log begins here; the run boundary for scoping.",
+        seenIn: [PAPYRUS_SAMPLE],
+    },
+    {
+        id: "skyrimse.papyrus.cannot-open-store",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "error",
+        category: "resource",
+        pattern: papyrus(String.raw `Cannot open store for class "(?<script>[^"]+)", missing file\?`),
+        explain: "A script the save or a form references is no longer installed (its .pex is gone); the most diagnostic Papyrus line, written without a severity prefix.",
+        hint: "Reinstall the mod that shipped that script, or accept that the save carries a stale reference.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["script"],
+        systemImpact: false,
+    },
+    {
+        id: "skyrimse.papyrus.bind-base-type-mismatch",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "error",
+        category: "script",
+        pattern: papyrus(String.raw `Error: Unable to bind script (?<script>\S+) to (?<form>.+?) \((?<formId>[0-9A-Fa-f]{8})\) because their base types do not match`),
+        explain: "A script is attached to a form of the wrong base type; a mismatched attach in one mod's plugin.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["script", "form", "formId"],
+        systemImpact: false,
+    },
+    {
+        id: "skyrimse.papyrus.stale-property",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "warn",
+        category: "script",
+        pattern: papyrus(String.raw `Warning: Property (?<property>\S+) on script (?<script>\S+) attached to (?<form>.+?) \((?<formId>[0-9A-Fa-f]{8})\) cannot be initialized because the script no longer contains that property`),
+        explain: "The save was made against an older version of the script; the property it recorded no longer exists.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["property", "script", "formId"],
+        systemImpact: false,
+    },
+    {
+        id: "skyrimse.papyrus.none-object-call",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "error",
+        category: "script",
+        pattern: papyrus(String.raw `Error: Cannot call (?<function>[\w.]+)\(\) on a None object, aborting function call`),
+        explain: "The commonest Papyrus runtime fault: a script called a function on an unset object.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["function"],
+        systemImpact: false,
+    },
+    {
+        id: "skyrimse.papyrus.plugin-not-loaded",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "error",
+        category: "order",
+        pattern: papyrus(String.raw `Error: File "(?<plugin>[^"]+)" does not exist or is not currently loaded\.`),
+        explain: "A script reached for a plugin that is not in the load order; the runtime face of a missing master.",
+        hint: "Enable the named plugin in Plugins.txt or remove the mod whose script expects it.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["plugin"],
+        systemImpact: false,
+    },
+    {
+        id: "skyrimse.papyrus.save-script-drift",
+        game: "skyrimse",
+        sources: ["papyrus"],
+        severity: "warn",
+        category: "script",
+        pattern: papyrus(String.raw `Warning: Function (?<function>[\w.]+) in stack frame \d+ in stack \d+ (?:differs from|doesn't exist in) the in-game resource files - using version from save`),
+        explain: "The save carries a compiled function that no longer matches the installed script; save-baked script drift.",
+        seenIn: [PAPYRUS_SAMPLE],
+        extract: ["function"],
+        systemImpact: false,
+    },
+];
+const CRASH = [
+    {
+        id: "skyrimse.crash.unhandled-exception",
+        game: "skyrimse",
+        sources: ["crash"],
+        severity: "error",
+        category: "crash",
+        pattern: /^Unhandled exception "(?<exception>EXCEPTION_[A-Z_]+)" at 0x(?<address>[0-9A-Fa-f]+)\s+(?<module>\S+)\+(?<rva>[0-9A-Fa-f]+)/,
+        explain: "The crash itself: the exception and the module the faulting address falls in (CrashLoggerSSE format).",
+        hint: "The module after the address is the first suspect; the SKSE PLUGINS section below it lists what was loaded.",
+        seenIn: ["https://github.com/alandtse/CrashLoggerSSE/blob/main/src/main.cpp"],
+        extract: ["exception", "module", "rva"],
+    },
+    {
+        id: "skyrimse.crash.format-crashlogger",
+        game: "skyrimse",
+        sources: ["crash"],
+        severity: "info",
+        category: "crash",
+        pattern: /^SKSE PLUGINS:\s*$/,
+        explain: "A CrashLoggerSSE-format log (its plugin inventory section).",
+        seenIn: ["https://github.com/alandtse/CrashLoggerSSE/blob/main/src/main.cpp"],
+    },
+    {
+        id: "skyrimse.crash.format-trainwreck",
+        game: "skyrimse",
+        sources: ["crash"],
+        severity: "info",
+        category: "crash",
+        pattern: /^SCRIPT EXTENDER PLUGINS:\s*$/,
+        explain: "A Trainwreck-format log (its plugin inventory section).",
+        seenIn: ["https://github.com/Phostwood/crash-analyzer/blob/main/TestLogTrainwreck1.txt"],
+    },
+];
+export const SIGNATURES = [...SKSE_LOADER, ...SKSE, ...PAPYRUS, ...CRASH];

package/dist/surfaces/skyrimse/plugins.js

@@ -0,0 +1,149 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+export const TES4_FLAG_MASTER = 0x0000_0001;
+export const TES4_FLAG_LOCALIZED = 0x0000_0080;
+export const TES4_FLAG_LIGHT = 0x0000_0200;
+export const TES4_FLAG_IGNORED = 0x0000_1000;
+export const RECORD_FLAG_COMPRESSED = 0x0004_0000;
+export const FORM_VERSION_SSE = 44;
+export const FORM_VERSION_LE = 43;
+export const VALID_HEADER_VERSIONS_SSE = [0.94, 1.7, 1.71];
+export const HEADER_VERSION_EXPANDED_LIGHT_RANGE = 1.71;
+export const MASTER_LIMIT_SSE = 253;
+export const RECORD_HEADER_LENGTH = 24;
+export const SUBRECORD_HEADER_LENGTH = 6;
+export class PluginHeaderError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "PluginHeaderError";
+    }
+}
+const WINDOWS_1252 = new TextDecoder("windows-1252");
+export function decodeZString(bytes) {
+    const end = bytes.length > 0 && bytes[bytes.length - 1] === 0 ? bytes.length - 1 : bytes.length;
+    return WINDOWS_1252.decode(bytes.subarray(0, end));
+}
+function ascii4(view, offset) {
+    return String.fromCharCode(view.getUint8(offset), view.getUint8(offset + 1), view.getUint8(offset + 2), view.getUint8(offset + 3));
+}
+export function parsePluginHeader(buf) {
+    if (buf.length < RECORD_HEADER_LENGTH) {
+        throw new PluginHeaderError(`plugin is ${buf.length} bytes; a TES4 record header is ${RECORD_HEADER_LENGTH}`, "too-short");
+    }
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const signature = ascii4(view, 0);
+    if (signature !== "TES4") {
+        throw new PluginHeaderError(`first record is "${signature}", not TES4; this is not a Bethesda plugin`, "bad-signature");
+    }
+    const dataSize = view.getUint32(4, true);
+    const flags = view.getUint32(8, true);
+    const formId = view.getUint32(12, true);
+    const formVersion = view.getUint16(20, true);
+    const header = {
+        signature,
+        dataSize,
+        flags,
+        formId,
+        formVersion,
+        isMaster: (flags & TES4_FLAG_MASTER) !== 0,
+        isLight: (flags & TES4_FLAG_LIGHT) !== 0,
+        isLocalized: (flags & TES4_FLAG_LOCALIZED) !== 0,
+        isIgnored: (flags & TES4_FLAG_IGNORED) !== 0,
+        isCompressed: (flags & RECORD_FLAG_COMPRESSED) !== 0,
+        masters: [],
+        hasOnam: false,
+        subrecords: [],
+    };
+    if (header.isCompressed) {
+        throw new PluginHeaderError("the TES4 record is flagged compressed (0x00040000); this reader does not decompress", "compressed");
+    }
+    const end = RECORD_HEADER_LENGTH + dataSize;
+    if (buf.length < end) {
+        throw new PluginHeaderError(`TES4 dataSize is ${dataSize} but only ${buf.length - RECORD_HEADER_LENGTH} bytes follow the header`, "truncated");
+    }
+    let offset = RECORD_HEADER_LENGTH;
+    let sizeOverride;
+    while (offset + SUBRECORD_HEADER_LENGTH <= end) {
+        const type = ascii4(view, offset);
+        let size = view.getUint16(offset + 4, true);
+        const dataOffset = offset + SUBRECORD_HEADER_LENGTH;
+        if (sizeOverride !== undefined) {
+            size = sizeOverride;
+            sizeOverride = undefined;
+        }
+        if (dataOffset + size > end) {
+            throw new PluginHeaderError(`subrecord ${type} at ${offset} claims ${size} bytes past the TES4 record's end`, "malformed");
+        }
+        const data = buf.subarray(dataOffset, dataOffset + size);
+        header.subrecords.push({ type, size, offset });
+        switch (type) {
+            case "XXXX":
+                if (size === 4)
+                    sizeOverride = view.getUint32(dataOffset, true);
+                break;
+            case "HEDR":
+                if (size >= 12) {
+                    header.headerVersion = Math.round(view.getFloat32(dataOffset, true) * 100) / 100;
+                    header.recordCount = view.getUint32(dataOffset + 4, true);
+                    header.nextObjectId = view.getUint32(dataOffset + 8, true);
+                }
+                break;
+            case "CNAM":
+                header.author = decodeZString(data);
+                break;
+            case "SNAM":
+                header.description = decodeZString(data);
+                break;
+            case "MAST":
+                header.masters.push(decodeZString(data));
+                break;
+            case "DATA":
+                break;
+            case "ONAM":
+                header.hasOnam = true;
+                break;
+            default:
+                break;
+        }
+        offset = dataOffset + size;
+    }
+    return header;
+}
+export async function readPluginHeader(filePath) {
+    const handle = await fs.open(filePath, "r");
+    try {
+        const head = new Uint8Array(RECORD_HEADER_LENGTH);
+        const first = await handle.read(head, 0, RECORD_HEADER_LENGTH, 0);
+        if (first.bytesRead < RECORD_HEADER_LENGTH) {
+            throw new PluginHeaderError(`${path.basename(filePath)} is ${first.bytesRead} bytes; a TES4 record header is ${RECORD_HEADER_LENGTH}`, "too-short");
+        }
+        const view = new DataView(head.buffer, head.byteOffset, head.byteLength);
+        if (ascii4(view, 0) !== "TES4")
+            return parsePluginHeader(head);
+        const dataSize = view.getUint32(4, true);
+        const size = (await handle.stat()).size;
+        if (RECORD_HEADER_LENGTH + dataSize > size) {
+            throw new PluginHeaderError(`${path.basename(filePath)} declares a TES4 dataSize of ${dataSize} but the file is ${size} bytes`, "truncated");
+        }
+        const whole = new Uint8Array(RECORD_HEADER_LENGTH + dataSize);
+        whole.set(head, 0);
+        const rest = await handle.read(whole, RECORD_HEADER_LENGTH, dataSize, RECORD_HEADER_LENGTH);
+        return parsePluginHeader(whole.subarray(0, RECORD_HEADER_LENGTH + rest.bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function pluginExtension(fileName) {
+    const ext = path.extname(fileName).toLowerCase();
+    return ext === ".esp" || ext === ".esm" || ext === ".esl" ? ext : undefined;
+}
+export function pluginType(fileName, header) {
+    const ext = pluginExtension(fileName);
+    return {
+        master: ext === ".esm" || header.isMaster,
+        light: ext === ".esl" || header.isLight,
+    };
+}

package/dist/surfaces/skyrimse/records.js

@@ -0,0 +1,94 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { PluginHeaderError, RECORD_HEADER_LENGTH, parsePluginHeader } from "./plugins.js";
+export const MAX_WALK_BYTES = 256 * 1024 * 1024;
+export const MAX_WALK_RECORDS = 2_000_000;
+export const MAX_WALK_DEPTH = 64;
+export const MAX_WALK_PROBLEMS = 64;
+export class RecordWalkError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "RecordWalkError";
+    }
+}
+function ascii4(view, offset) {
+    return String.fromCharCode(view.getUint8(offset), view.getUint8(offset + 1), view.getUint8(offset + 2), view.getUint8(offset + 3));
+}
+export function walkPluginRecords(buf) {
+    const header = parsePluginHeader(buf);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const walk = { header, records: [], groupCount: 0, truncated: false, problems: [] };
+    const problem = (text) => {
+        if (walk.problems.length < MAX_WALK_PROBLEMS)
+            walk.problems.push(text);
+    };
+    const visit = (start, end, depth) => {
+        if (depth > MAX_WALK_DEPTH) {
+            problem(`GRUP nesting at ${start} is deeper than ${MAX_WALK_DEPTH}; that branch was not read`);
+            return;
+        }
+        let at = start;
+        while (at + RECORD_HEADER_LENGTH <= end) {
+            if (walk.records.length >= MAX_WALK_RECORDS) {
+                walk.truncated = true;
+                return;
+            }
+            const signature = ascii4(view, at);
+            const size = view.getUint32(at + 4, true);
+            if (signature === "GRUP") {
+                if (size < RECORD_HEADER_LENGTH) {
+                    problem(`GRUP at ${at} declares size ${size}, less than its own header`);
+                    return;
+                }
+                const groupEnd = at + size;
+                if (groupEnd > end) {
+                    problem(`GRUP at ${at} declares size ${size}, running ${groupEnd - end} bytes past its parent`);
+                    walk.groupCount++;
+                    visit(at + RECORD_HEADER_LENGTH, end, depth + 1);
+                    return;
+                }
+                walk.groupCount++;
+                visit(at + RECORD_HEADER_LENGTH, groupEnd, depth + 1);
+                at = groupEnd;
+                continue;
+            }
+            const recordEnd = at + RECORD_HEADER_LENGTH + size;
+            walk.records.push({ signature, formId: view.getUint32(at + 12, true), flags: view.getUint32(at + 8, true), offset: at });
+            if (recordEnd > end) {
+                problem(`${signature} record at ${at} declares dataSize ${size}, running ${recordEnd - end} bytes past its parent`);
+                return;
+            }
+            at = recordEnd;
+        }
+        if (at !== end && depth > 0)
+            problem(`${end - at} trailing bytes in a GRUP ending at ${end}`);
+    };
+    visit(RECORD_HEADER_LENGTH + header.dataSize, buf.length, 0);
+    return walk;
+}
+export async function readPluginRecords(filePath) {
+    const { size } = await fs.stat(filePath);
+    if (size > MAX_WALK_BYTES) {
+        throw new RecordWalkError("too-large", `${path.basename(filePath)} is ${size} bytes; the record walk holds at most ${MAX_WALK_BYTES}`);
+    }
+    const buf = new Uint8Array(await fs.readFile(filePath));
+    if (buf.length < RECORD_HEADER_LENGTH)
+        throw new PluginHeaderError(`${path.basename(filePath)} is ${buf.length} bytes; a TES4 record header is ${RECORD_HEADER_LENGTH}`, "too-short");
+    return walkPluginRecords(buf);
+}
+export function modIndexOf(formId) {
+    return formId >>> 24;
+}
+export function objectIndexOf(formId) {
+    return formId & 0x00ff_ffff;
+}
+export function classifyRecord(formId, masterCount) {
+    const index = modIndexOf(formId);
+    if (index === masterCount)
+        return "new";
+    if (index < masterCount)
+        return "override";
+    return "dangling";
+}