modwright 0.1.0

package/dist/surfaces/skyrimse/validators/plugins.js

@@ -0,0 +1,374 @@
+import * as path from "node:path";
+import { readPeFileVersion } from "../../../core/compat/pe.js";
+import { compareVersions, parseVersion } from "../../../core/compat/version.js";
+import { FORM_VERSION_LE, FORM_VERSION_SSE, HEADER_VERSION_EXPANDED_LIGHT_RANGE, MASTER_LIMIT_SSE, PluginHeaderError, VALID_HEADER_VERSIONS_SSE, pluginExtension, readPluginHeader, } from "../plugins.js";
+import { RUNTIME_EXPANDED_LIGHT_RANGE } from "../compat.js";
+const EVIDENCE = ["ModWright research"];
+function isPluginUnderSource(target, project) {
+    if (target.kind !== "file" || pluginExtension(target.path) === undefined)
+        return false;
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, target.path));
+}
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+const APPLIES = "every .esp, .esm or .esl file under a project source";
+async function headerOrFinding(id, file) {
+    try {
+        return await readPluginHeader(file);
+    }
+    catch (err) {
+        const reason = err instanceof PluginHeaderError ? err.reason : "unreadable";
+        return {
+            validatorId: id,
+            severity: "block",
+            file,
+            message: `${path.basename(file)} has no readable TES4 header (${reason}): ${err.message}`,
+            fix: "A plugin must begin with a TES4 record; re-save it from the Creation Kit or xEdit, or check the file is not truncated.",
+            evidence: EVIDENCE,
+        };
+    }
+}
+function isFinding(v) {
+    return v.validatorId !== undefined;
+}
+async function loadOrderOf(ctx) {
+    if (!ctx.install || !ctx.surface.loadOrder)
+        return undefined;
+    return ctx.surface.loadOrder(ctx.install);
+}
+function findEntry(order, name) {
+    const key = name.toLowerCase();
+    return order.find((e) => e.name.toLowerCase() === key);
+}
+const mastersPresent = {
+    id: "sse.plugins.masters-present",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "Every master a plugin's TES4 MAST entries name is present and active in the live load order.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true, install: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        const order = await loadOrderOf(ctx);
+        if (!order)
+            return [];
+        const findings = [];
+        for (const master of header.masters) {
+            const entry = findEntry(order, master);
+            if (entry?.enabled)
+                continue;
+            const onDisk = ctx.install ? await ctx.exists(path.join(ctx.install.root, "Data", master)) : false;
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file: ctx.target.path,
+                message: entry
+                    ? `Master "${master}" is listed in Plugins.txt but not active; ${path.basename(ctx.target.path)} depends on it and the game will refuse to load, or load with its records dropped.`
+                    : onDisk
+                        ? `Master "${master}" is under Data but not in the load order at all; ${path.basename(ctx.target.path)} depends on it.`
+                        : `Master "${master}" is neither in the load order nor under Data; ${path.basename(ctx.target.path)} cannot load without it.`,
+                fix: entry ? `Activate ${master} (a * line in Plugins.txt).` : `Install ${master} and activate it ahead of ${path.basename(ctx.target.path)}.`,
+                evidence: EVIDENCE,
+            });
+        }
+        return findings;
+    },
+};
+const masterOrder = {
+    id: "sse.plugins.master-order",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "Every master of a plugin loads before the plugin itself in the live load order.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true, install: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [...EVIDENCE],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        const order = await loadOrderOf(ctx);
+        if (!order)
+            return [];
+        const self = findEntry(order, path.basename(ctx.target.path));
+        if (!self) {
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "info",
+                    file: ctx.target.path,
+                    message: `${path.basename(ctx.target.path)} is not in the load order, so its masters' positions relative to it cannot be checked yet.`,
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        const findings = [];
+        for (const master of header.masters) {
+            const entry = findEntry(order, master);
+            if (!entry || entry.index < self.index)
+                continue;
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file: ctx.target.path,
+                message: `Master "${master}" loads at position ${entry.index}, after ${path.basename(ctx.target.path)} at ${self.index}; a plugin must load after every master it depends on.`,
+                fix: `Move ${master} above ${path.basename(ctx.target.path)} in Plugins.txt (LOOT does this).`,
+                evidence: [...EVIDENCE],
+            });
+        }
+        return findings;
+    },
+};
+const eslHeaderVersion = {
+    id: "sse.plugins.esl-header-version",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "A plugin's HEDR version is one Skyrim SE accepts (0.94, 1.70, 1.71), and a plugin whose masters are 1.71 is itself 1.71.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        const findings = [];
+        const version = header.headerVersion;
+        if (version === undefined) {
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file: ctx.target.path,
+                message: `${path.basename(ctx.target.path)} has no HEDR subrecord; every plugin's TES4 record carries one.`,
+                evidence: EVIDENCE,
+            });
+            return findings;
+        }
+        if (!VALID_HEADER_VERSIONS_SSE.includes(version)) {
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file: ctx.target.path,
+                message: `HEDR version ${version.toFixed(2)} is not one Skyrim SE accepts (${VALID_HEADER_VERSIONS_SSE.map((v) => v.toFixed(2)).join(", ")}).`,
+                fix: "Re-save the plugin with the Skyrim SE Creation Kit or xEdit in SSE mode.",
+                evidence: EVIDENCE,
+            });
+            return findings;
+        }
+        if (version >= HEADER_VERSION_EXPANDED_LIGHT_RANGE && ctx.install) {
+            const runtime = ctx.install.version ?? (await readPeFileVersion(path.join(ctx.install.root, "SkyrimSE.exe")));
+            if (runtime && parseVersion(runtime) && compareVersions(runtime, RUNTIME_EXPANDED_LIGHT_RANGE) < 0) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: ctx.target.path,
+                    message: `${path.basename(ctx.target.path)} has HEDR version ${version.toFixed(2)}, which needs game runtime ${RUNTIME_EXPANDED_LIGHT_RANGE} or later; this install is ${runtime}.`,
+                    fix: "Update the game, or re-save the plugin with a 1.70 header if it uses no FormID below 0x800.",
+                    evidence: EVIDENCE,
+                });
+            }
+        }
+        if (version < HEADER_VERSION_EXPANDED_LIGHT_RANGE) {
+            for (const master of header.masters) {
+                const candidates = [path.join(path.dirname(ctx.target.path), master), ...(ctx.install ? [path.join(ctx.install.root, "Data", master)] : [])];
+                for (const candidate of candidates) {
+                    if (!(await ctx.exists(candidate)))
+                        continue;
+                    try {
+                        const mh = await readPluginHeader(candidate);
+                        if (mh.headerVersion !== undefined && mh.headerVersion >= HEADER_VERSION_EXPANDED_LIGHT_RANGE) {
+                            findings.push({
+                                validatorId: this.id,
+                                severity: "warn",
+                                file: ctx.target.path,
+                                message: `Master "${master}" is a ${mh.headerVersion.toFixed(2)} plugin while ${path.basename(ctx.target.path)} is ${version.toFixed(2)}; referencing or overriding that master's records in the extended FormID range (001-7FF) will error.`,
+                                fix: "Re-save this plugin with a 1.71 header (xEdit 4.1.5b or later, or the current Creation Kit).",
+                                evidence: EVIDENCE,
+                            });
+                        }
+                    }
+                    catch {
+                    }
+                    break;
+                }
+            }
+        }
+        return findings;
+    },
+};
+const flagExtensionMismatch = {
+    id: "sse.plugins.flag-extension-mismatch",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "An .esm carries the master flag and an .esp does not; the flag, not the extension, decides how the game treats the file.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        const ext = pluginExtension(ctx.target.path);
+        const name = path.basename(ctx.target.path);
+        if (ext === ".esp" && header.isMaster) {
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: ctx.target.path,
+                    message: `${name} has the ESM flag set: the game treats it as a master regardless of the .esp extension, so it loads among the masters and every header-reading tool disagrees with its name.`,
+                    fix: "Clear the ESM flag in xEdit, or rename the file .esm so the extension says what the flag does.",
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        if (ext === ".esm" && !header.isMaster) {
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: ctx.target.path,
+                    message: `${name} has no ESM flag: the .esm extension makes the game load it as a master anyway, but tools reading the header will not.`,
+                    fix: "Set the ESM flag in xEdit so the header and the extension agree.",
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        return [];
+    },
+};
+const eslExtensionImpliesFlag = {
+    id: "sse.plugins.esl-extension-implies-flag",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "An .esl file carries the light flag in its header; the extension forces the flag at runtime, so a header without it misleads every tool.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        if (pluginExtension(ctx.target.path) !== ".esl" || header.isLight)
+            return [];
+        return [
+            {
+                validatorId: this.id,
+                severity: "warn",
+                file: ctx.target.path,
+                message: `${path.basename(ctx.target.path)} is an .esl without the light flag (0x200) in its header; the game treats it as light because of the extension, header-reading tools do not.`,
+                fix: "Set the ESL flag in xEdit (it checks the plugin's new records fit the light range first).",
+                evidence: EVIDENCE,
+            },
+        ];
+    },
+};
+const formVersion = {
+    id: "sse.plugins.form-version",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "The TES4 record's form version is 44, Skyrim SE's; 43 is a Skyrim LE plugin.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        if (header.formVersion === FORM_VERSION_SSE)
+            return [];
+        const le = header.formVersion === FORM_VERSION_LE;
+        return [
+            {
+                validatorId: this.id,
+                severity: le ? "block" : "warn",
+                file: ctx.target.path,
+                message: le
+                    ? `${path.basename(ctx.target.path)} has form version 43: a Skyrim Legendary Edition plugin, not converted for Special Edition.`
+                    : `${path.basename(ctx.target.path)} has form version ${header.formVersion}; Skyrim SE plugins carry 44.`,
+                fix: le ? "Open and re-save the plugin in the Skyrim SE Creation Kit to convert it (and re-pack any LE .bsa)." : "Re-save the plugin with the Skyrim SE Creation Kit or xEdit.",
+                evidence: EVIDENCE,
+            },
+        ];
+    },
+};
+const masterCount = {
+    id: "sse.plugins.master-count",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "A plugin names at most 253 masters; the FE slot is reserved for light plugins, in master lists too.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const header = await headerOrFinding(this.id, ctx.target.path);
+        if (isFinding(header))
+            return [header];
+        if (header.masters.length <= MASTER_LIMIT_SSE)
+            return [];
+        return [
+            {
+                validatorId: this.id,
+                severity: "block",
+                file: ctx.target.path,
+                message: `${path.basename(ctx.target.path)} names ${header.masters.length} masters; Skyrim SE allows ${MASTER_LIMIT_SSE}.`,
+                fix: "Clean unused masters in xEdit, or split the plugin.",
+                evidence: EVIDENCE,
+            },
+        ];
+    },
+};
+export const PLUGIN_VALIDATORS = [
+    mastersPresent,
+    masterOrder,
+    eslHeaderVersion,
+    flagExtensionMismatch,
+    eslExtensionImpliesFlag,
+    formVersion,
+    masterCount,
+];

package/dist/surfaces/skyrimse/validators/records.js

@@ -0,0 +1,117 @@
+import * as path from "node:path";
+import { HEADER_VERSION_EXPANDED_LIGHT_RANGE, PluginHeaderError, pluginExtension } from "../plugins.js";
+import { RecordWalkError, classifyRecord, objectIndexOf, readPluginRecords } from "../records.js";
+const EVIDENCE = [
+    "sse.plugins.esl.validity-counts-new-records-only",
+    "sse.plugins.esl.hedr-1-71-unlocks-the-expanded-range",
+    "sse.plugins.esl.expanded-floor-is-disputed",
+    "sse.plugins.format.modindex-equal-to-master-count-is-the-plugins-own",
+];
+export const LIGHT_OBJECT_INDEX_MAX = 0xfff;
+export const LIGHT_OBJECT_INDEX_MIN_LEGACY = 0x800;
+export const LIGHT_OBJECT_INDEX_MIN_EXPANDED = 0x001;
+const NAMED_RECORDS = 5;
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isPluginUnderSource(target, project) {
+    if (target.kind !== "file" || pluginExtension(target.path) === undefined)
+        return false;
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, target.path));
+}
+const hex = (formId) => formId.toString(16).toUpperCase().padStart(8, "0");
+const eslRange = {
+    id: "sse.plugins.esl-range",
+    game: "skyrimse",
+    groups: ["plugins"],
+    modTypes: ["plugin"],
+    summary: "A light plugin's new records (every record that does not override a master) have object indices within the range its HEDR version allows: 0x800-0xFFF below 1.71, up to 0xFFF from 1.71 (with 0x000 reported as disputed); overrides are exempt.",
+    appliesTo: isPluginUnderSource,
+    appliesToDescription: "every .esp, .esm or .esl file under a project source",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        let walk;
+        try {
+            walk = await readPluginRecords(file);
+        }
+        catch (err) {
+            if (err instanceof RecordWalkError) {
+                return [{ validatorId: this.id, severity: "info", file, message: `${name} was not walked: ${err.message}; the light-plugin range was not checked.`, evidence: EVIDENCE }];
+            }
+            const reason = err instanceof PluginHeaderError ? err.reason : "unreadable";
+            return [{ validatorId: this.id, severity: "block", file, message: `${name} has no readable TES4 header (${reason}): ${err.message}`, fix: "A plugin must begin with a TES4 record; re-save it from the Creation Kit or xEdit, or check the file is not truncated.", evidence: EVIDENCE }];
+        }
+        const { header } = walk;
+        const light = header.isLight || pluginExtension(file) === ".esl";
+        const findings = [];
+        for (const p of walk.problems.slice(0, 3)) {
+            findings.push({ validatorId: this.id, severity: "warn", file, message: `${name}'s record structure is damaged: ${p}; records after that point were not read.`, fix: "Re-save the plugin from xEdit or the Creation Kit.", evidence: EVIDENCE });
+        }
+        if (walk.truncated) {
+            findings.push({ validatorId: this.id, severity: "info", file, message: `${name} has more records than this walk reads; only the first ${walk.records.length} were checked.`, evidence: EVIDENCE });
+        }
+        const masters = header.masters.length;
+        const dangling = walk.records.filter((r) => classifyRecord(r.formId, masters) === "dangling");
+        if (dangling.length > 0) {
+            const named = dangling.slice(0, NAMED_RECORDS).map((r) => `${r.signature} ${hex(r.formId)}`).join(", ");
+            findings.push({
+                validatorId: this.id,
+                severity: "warn",
+                file,
+                message: `${name} has ${dangling.length} record${dangling.length === 1 ? "" : "s"} whose mod index is above its ${masters} master${masters === 1 ? "" : "s"} (${named}${dangling.length > NAMED_RECORDS ? ", ..." : ""}); the index names a master the header does not list, so nothing can tell whether the record overrides a master's form or is the plugin's own. xEdit's error check calls this a HITME.`,
+                fix: "Usually a master was force-removed from the header. Re-saving in xEdit or the Creation Kit sometimes repairs it; often the plugin has to be rebuilt against the master it lost.",
+                evidence: EVIDENCE,
+            });
+        }
+        if (!light)
+            return findings;
+        const version = header.headerVersion;
+        const expanded = version !== undefined && version >= HEADER_VERSION_EXPANDED_LIGHT_RANGE;
+        const floor = expanded ? LIGHT_OBJECT_INDEX_MIN_EXPANDED : LIGHT_OBJECT_INDEX_MIN_LEGACY;
+        const own = walk.records.filter((r) => classifyRecord(r.formId, masters) !== "override");
+        const above = own.filter((r) => objectIndexOf(r.formId) > LIGHT_OBJECT_INDEX_MAX);
+        const below = own.filter((r) => objectIndexOf(r.formId) < floor && !(expanded && objectIndexOf(r.formId) === 0));
+        const zero = expanded ? own.filter((r) => objectIndexOf(r.formId) === 0) : [];
+        const describe = (records) => records.slice(0, NAMED_RECORDS).map((r) => `${r.signature} ${hex(r.formId)}`).join(", ") + (records.length > NAMED_RECORDS ? ", ..." : "");
+        if (above.length > 0) {
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file,
+                message: `${name} is a light plugin with ${above.length} new record${above.length === 1 ? "" : "s"} whose object index is above 0xFFF (${describe(above)}); a light plugin has 12 bits of object id, so the game cannot address them. xEdit refuses to save the ESL flag on such a file and Wrye Bash reports "This plugin contains records with FormIDs greater than 0xFFF".`,
+                fix: "Run xEdit's Compact FormIDs for ESL to renumber the plugin's own records into the light range, then rebuild anything that references them by FormID.",
+                evidence: EVIDENCE,
+            });
+        }
+        if (below.length > 0) {
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file,
+                message: `${name} is a light plugin with HEDR ${version === undefined ? "missing" : version.toFixed(2)} and ${below.length} new record${below.length === 1 ? "" : "s"} whose object index is below 0x${floor.toString(16).toUpperCase().padStart(3, "0")} (${describe(below)}); below header version 1.71 a light plugin's new records must start at 0x800.`,
+                fix: "Either raise the header to 1.71 (which then needs game runtime 1.6.1130 or later) or compact the FormIDs into 0x800-0xFFF with xEdit.",
+                evidence: EVIDENCE,
+            });
+        }
+        if (zero.length > 0) {
+            findings.push({
+                validatorId: this.id,
+                severity: "warn",
+                file,
+                message: `${name} is a 1.71 light plugin with ${zero.length} new record${zero.length === 1 ? "" : "s"} at object index 0x000 (${describe(zero)}); esplugin accepts 0x000, xEdit's notes say the expanded range starts at 001, and no real 1.71 plugin has been read here to settle it.`,
+                fix: "Renumber that record to 0x001 or above to be safe with every tool.",
+                evidence: EVIDENCE,
+            });
+        }
+        return findings;
+    },
+};
+export const RECORD_VALIDATORS = [eslRange];