modwright 0.1.0

package/dist/surfaces/eldenring/validators/params.js

@@ -0,0 +1,334 @@
+import * as path from "node:path";
+import { locateTool, TOOL_SPECS } from "../../../core/toolchain/index.js";
+import { checkFieldValue, findParamdef, findParamdexGameDir, loadParamdex } from "../paramdef.js";
+import { parseDsmsCsv, parseWitchyParamXml } from "../params.js";
+import { witchyBndParamdexDir } from "../tools.js";
+export const PARAMDEX_ENV = "MODWRIGHT_ELDENRING_PARAMDEX";
+export const PARAMDEX_SOURCE_KIND = "paramdex";
+export const PARAMS_SOURCE_KIND = "params";
+const EVIDENCE = ["eldenring.regulation.paramdefs-come-from-paramdex"];
+const SCHEMA_EVIDENCE = [...EVIDENCE, "eldenring.paramdef.def-files-are-named-after-the-param", "eldenring.params.dsmapstudio-csv-shape", "eldenring.params.witchybnd-xml-shape"];
+const VALUES_EVIDENCE = [...EVIDENCE, "eldenring.paramdef.def-grammar-is-a-c-declaration", "eldenring.paramdef.tdfs-cover-few-of-the-enums", "eldenring.paramdef.minimum-and-maximum-are-editor-hints"];
+const APPLIES = "every .csv and .xml (other than a _witchy-* sidecar) under a project source of kind \"params\"";
+const MAX_FINDINGS_PER_FILE = 40;
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isParamExport(target, project) {
+    if (target.kind !== "file")
+        return false;
+    const ext = path.extname(target.path).toLowerCase();
+    if (ext !== ".csv" && ext !== ".xml")
+        return false;
+    if (path.basename(target.path).toLowerCase().startsWith("_witchy-"))
+        return false;
+    return project.sources.some((s) => s.exists && s.kind === PARAMS_SOURCE_KIND && isWithin(s.absPath, target.path));
+}
+export async function resolveParamdexDir(project, options = {}) {
+    const env = options.env ?? process.env;
+    const tried = [];
+    for (const s of project.sources) {
+        if (s.kind !== PARAMDEX_SOURCE_KIND)
+            continue;
+        tried.push(`source "${s.id}" (${s.absPath})`);
+        const dir = await findParamdexGameDir(s.absPath);
+        if (dir)
+            return { dir, via: "source", tried };
+    }
+    const fromEnv = env[PARAMDEX_ENV];
+    if (fromEnv) {
+        tried.push(`${PARAMDEX_ENV}=${fromEnv}`);
+        const dir = await findParamdexGameDir(fromEnv);
+        if (dir)
+            return { dir, via: "env", tried };
+    }
+    let exe = options.witchyBndPath;
+    if (exe === undefined) {
+        const spec = TOOL_SPECS.find((t) => t.id === "witchybnd");
+        const overrides = project.project.toolchain;
+        const located = spec ? await locateTool(spec, { projectOverrides: overrides, probe: "none" }) : undefined;
+        exe = located?.found && located.path ? located.path : null;
+    }
+    if (exe) {
+        const candidate = witchyBndParamdexDir(exe);
+        tried.push(`WitchyBND's ${candidate}`);
+        const dir = await findParamdexGameDir(candidate);
+        if (dir)
+            return { dir, via: "witchybnd", tried };
+    }
+    else {
+        tried.push("WitchyBND (not located, so no bundled Paramdex)");
+    }
+    return { tried };
+}
+const CACHE_TTL_MS = 60_000;
+const cache = new Map();
+export function loadParamdexCached(dir) {
+    const hit = cache.get(dir);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS)
+        return hit.loaded;
+    const loaded = loadParamdex(dir);
+    cache.set(dir, { at: Date.now(), loaded });
+    loaded.catch(() => cache.delete(dir));
+    return loaded;
+}
+const lookupCache = new Map();
+function resolveParamdexDirCached(project) {
+    const key = project.file;
+    const hit = lookupCache.get(key);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS)
+        return hit.lookup;
+    const lookup = resolveParamdexDir(project);
+    lookupCache.set(key, { at: Date.now(), lookup });
+    lookup.catch(() => lookupCache.delete(key));
+    return lookup;
+}
+export function clearParamdexCache() {
+    cache.clear();
+    lookupCache.clear();
+}
+async function readExport(ctx, file) {
+    const ext = path.extname(file).toLowerCase();
+    let text;
+    try {
+        text = await ctx.readText(file);
+    }
+    catch (err) {
+        return { error: `could not be read: ${err.message}` };
+    }
+    if (ext === ".csv") {
+        const data = parseDsmsCsv(text);
+        if (data.rows.length === 0 && !data.fields)
+            return { error: "is empty: no header and no rows" };
+        const key = path.basename(file, path.extname(file)).replace(/\.param$/i, "");
+        return { data, key };
+    }
+    let data;
+    try {
+        data = parseWitchyParamXml(text);
+    }
+    catch (err) {
+        return { error: `is not well-formed XML: ${err.message}` };
+    }
+    if (!data)
+        return { skip: true };
+    const key = data.paramType ?? data.paramdefType;
+    if (!key)
+        return { error: "is a WitchyBND param XML with no <type> (the ParamType), so no paramdef can be chosen for it" };
+    return { data, key };
+}
+function paramdexInfo(id, evidence, file, lookup) {
+    return {
+        validatorId: id,
+        severity: "info",
+        file,
+        message: `${path.basename(file)} was not checked against a paramdef: no Paramdex was found (tried ${lookup.tried.join("; ")}).`,
+        fix: `Add a project source of kind "${PARAMDEX_SOURCE_KIND}" pointing at a soulsmods/Paramdex checkout, set ${PARAMDEX_ENV}, or install WitchyBND (it bundles Paramdex under Assets/Paramdex/ER).`,
+        evidence,
+    };
+}
+async function load(id, evidence, ctx, file) {
+    const exported = await readExport(ctx, file);
+    if ("skip" in exported)
+        return [];
+    const name = path.basename(file);
+    if ("error" in exported) {
+        return [{ validatorId: id, severity: "block", file, message: `${name} ${exported.error}; expected a DSMapStudio CSV export or a WitchyBND param XML.`, evidence }];
+    }
+    const lookup = await resolveParamdexDirCached(ctx.project);
+    if (!lookup.dir)
+        return [paramdexInfo(id, evidence, file, lookup)];
+    let paramdex;
+    try {
+        paramdex = await loadParamdexCached(lookup.dir);
+    }
+    catch (err) {
+        return [{ validatorId: id, severity: "block", file, message: `Paramdex at ${lookup.dir} could not be loaded: ${err.message}`, evidence }];
+    }
+    const def = findParamdef(paramdex, exported.key);
+    if (!def) {
+        return [
+            {
+                validatorId: id,
+                severity: "block",
+                file,
+                message: `${name} names param "${exported.key}", and ${lookup.dir} has no paramdef for it (by ParamType or by def file name).`,
+                fix: "Name a CSV after the param as DSMapStudio does (EquipParamWeapon.csv); a WitchyBND XML's <type> must be the def's ParamType (EQUIP_PARAM_WEAPON_ST). If the param is new to the game, update the Paramdex checkout.",
+                evidence,
+            },
+        ];
+    }
+    return { paramdex, def, data: exported.data };
+}
+const isFindings = (v) => Array.isArray(v);
+function capped(findings, id, evidence, file) {
+    if (findings.length <= MAX_FINDINGS_PER_FILE)
+        return findings;
+    const rest = findings.length - MAX_FINDINGS_PER_FILE;
+    return [
+        ...findings.slice(0, MAX_FINDINGS_PER_FILE),
+        { validatorId: id, severity: "info", file, message: `${rest} more finding${rest === 1 ? "" : "s"} of the same kind in ${path.basename(file)} not listed.`, evidence },
+    ];
+}
+function withoutTrailingBlank(values, expected) {
+    return values.length === expected + 1 && values[expected].trim() === "" ? values.slice(0, expected) : values;
+}
+const schema = {
+    id: "eldenring.params.schema",
+    game: "eldenring",
+    groups: ["params"],
+    modTypes: ["gameplay-tweak", "weapon", "armor", "item"],
+    summary: "A param export names a param Paramdex has a def for, and every field it names is in that def; a positional CSV row has one value per def field.",
+    appliesTo: isParamExport,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: SCHEMA_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const loaded = await load(this.id, SCHEMA_EVIDENCE, ctx, file);
+        if (isFindings(loaded))
+            return loaded;
+        const { def, data } = loaded;
+        const known = new Set(def.fields.map((f) => f.name));
+        const name = path.basename(file);
+        const findings = [];
+        const unknownField = (field, line) => ({
+            validatorId: this.id,
+            severity: "block",
+            file,
+            ...(line !== undefined ? { line } : {}),
+            message: `${name} names field "${field}", which ${def.paramType} (${def.fields.length} fields) does not have; DSMapStudio's import stops on an unknown column.`,
+            fix: "Check the spelling against the def's field names (Paramdex Defs, or the tool's own field list); an editor-renamed field keeps its internal name in the def.",
+            evidence: SCHEMA_EVIDENCE,
+        });
+        if (data.shape === "dsms-csv") {
+            if (data.fields) {
+                for (const f of data.fields)
+                    if (!known.has(f))
+                        findings.push(unknownField(f, 1));
+                const width = data.fields.length;
+                for (const row of data.rows) {
+                    const values = row.positional ? withoutTrailingBlank(row.positional, width) : undefined;
+                    if (values && values.length !== width) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file,
+                            ...(row.line !== undefined ? { line: row.line } : {}),
+                            message: `Row ${row.idText} in ${name} has ${values.length} value${values.length === 1 ? "" : "s"} for ${width} header field${width === 1 ? "" : "s"}.`,
+                            evidence: SCHEMA_EVIDENCE,
+                        });
+                    }
+                }
+            }
+            else {
+                for (const row of data.rows) {
+                    const count = withoutTrailingBlank(row.positional ?? [], def.fields.length).length;
+                    if (count !== def.fields.length) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file,
+                            ...(row.line !== undefined ? { line: row.line } : {}),
+                            message: `Row ${row.idText} in ${name} has ${count} value${count === 1 ? "" : "s"}; with no header the columns are positional and ${def.paramType} has ${def.fields.length} fields.`,
+                            fix: "Export with the header row (ID, Name, then every field), or supply every field in def order.",
+                            evidence: SCHEMA_EVIDENCE,
+                        });
+                    }
+                }
+            }
+        }
+        else {
+            for (const f of data.fields)
+                if (!known.has(f.name))
+                    findings.push(unknownField(f.name));
+            if (data.dataVersion !== undefined && data.dataVersion !== def.dataVersion) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file,
+                    message: `${name} was unpacked against paramdef data version ${data.dataVersion}; the Paramdex on hand has ${def.dataVersion} for ${def.paramType}, so its field list may not be the one the values were written for.`,
+                    fix: "Unpack again with a WitchyBND whose bundled Paramdex matches the checkout ModWright is reading, or point ModWright at that WitchyBND's copy.",
+                    evidence: SCHEMA_EVIDENCE,
+                });
+            }
+            if (data.unreadRows > 0) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "info",
+                    file,
+                    message: `${data.unreadRows} row${data.unreadRows === 1 ? "" : "s"} in ${name} store cells as one delimited string (WitchyBND's CSV cell style), which ModWright does not read; their values were not checked.`,
+                    fix: "Unpack with WitchyBND's cell style set to Element or Attribute to have values checked.",
+                    evidence: SCHEMA_EVIDENCE,
+                });
+            }
+        }
+        return capped(findings, this.id, SCHEMA_EVIDENCE, file);
+    },
+};
+function cellsOf(row, def, data) {
+    if (row.cells)
+        return [...row.cells.entries()];
+    if (data.shape === "dsms-csv" && !data.fields && row.positional) {
+        const values = withoutTrailingBlank(row.positional, def.fields.length);
+        if (values.length === def.fields.length)
+            return values.map((v, i) => [def.fields[i].name, v]);
+    }
+    return [];
+}
+const values = {
+    id: "eldenring.params.values",
+    game: "eldenring",
+    groups: ["params"],
+    modTypes: ["gameplay-tweak", "weapon", "armor", "item"],
+    summary: "Every cell in a param export fits its def field: integer ranges and bit widths, finite floats, byte arrays of the declared length, fixed strings within their length, and (where Paramdex has the tdf) an enumerated field's known values.",
+    appliesTo: isParamExport,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: VALUES_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const loaded = await load(this.id, VALUES_EVIDENCE, ctx, file);
+        if (isFindings(loaded))
+            return loaded;
+        const { paramdex, def, data } = loaded;
+        const byName = new Map(def.fields.map((f) => [f.name, f]));
+        const name = path.basename(file);
+        const findings = [];
+        for (const row of data.rows) {
+            const at = row.line !== undefined ? { line: row.line } : {};
+            if (row.id === undefined) {
+                findings.push({ validatorId: this.id, severity: "block", file, ...at, message: `Row id "${row.idText}" in ${name} is not an integer.`, evidence: VALUES_EVIDENCE });
+                continue;
+            }
+            for (const [fieldName, raw] of cellsOf(row, def, data)) {
+                const field = byName.get(fieldName);
+                if (!field)
+                    continue;
+                const problem = checkFieldValue(field, raw, paramdex.tdfs);
+                if (!problem)
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: problem.kind === "enum" ? "warn" : "block",
+                    file,
+                    ...at,
+                    message: `Row ${row.id}${row.name && row.name !== "null" ? ` (${row.name})` : ""} in ${name}: ${problem.message}.`,
+                    ...(problem.kind === "enum" ? { fix: "A value outside the tdf is not always wrong (Paramdex's tdfs lag the game), but it is worth a look." } : {}),
+                    evidence: VALUES_EVIDENCE,
+                });
+            }
+        }
+        return capped(findings, this.id, VALUES_EVIDENCE, file);
+    },
+};
+export const PARAM_VALIDATORS = [schema, values];

package/dist/surfaces/eldenring/validators/profiles.js

@@ -0,0 +1,287 @@
+import * as path from "node:path";
+import { isDirectory } from "../../../core/fsutil.js";
+import { ME3_ELDENRING_IDS, ME3_GAME_IDS, ME3_PROFILE_VERSION, parseMe3ProfileDetailed } from "../loaders.js";
+const EVIDENCE = [
+    "eldenring.me3.profile-is-a-toml-file",
+    "eldenring.me3.package-paths-are-relative-to-the-profile",
+    "eldenring.me3.profile-schema-fixes-version-games-and-keys",
+];
+const APPLIES = "every .me3 file under a project source";
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isProfile(target, project) {
+    if (target.kind !== "file" || path.extname(target.path).toLowerCase() !== ".me3")
+        return false;
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, target.path));
+}
+async function parse(ctx, file) {
+    let text;
+    try {
+        text = await ctx.readText(file);
+    }
+    catch (err) {
+        return { error: `could not be read: ${err.message}` };
+    }
+    try {
+        return { detail: parseMe3ProfileDetailed(text) };
+    }
+    catch (err) {
+        const line = err.line;
+        return { error: `is not valid TOML: ${err.message.split("\n")[0]}`, ...(typeof line === "number" ? { line } : {}) };
+    }
+}
+const version = {
+    id: "eldenring.me3.profile-version",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: `A .me3 profile parses as TOML and carries profileVersion = "${ME3_PROFILE_VERSION}", the one version me3's schema accepts.`,
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed) {
+            return [{ validatorId: this.id, severity: "block", file, ...(parsed.line !== undefined ? { line: parsed.line } : {}), message: `${name} ${parsed.error}; me3 cannot load it.`, evidence: EVIDENCE }];
+        }
+        const v = parsed.detail.profile.profileVersion;
+        if (v === ME3_PROFILE_VERSION)
+            return [];
+        return [
+            {
+                validatorId: this.id,
+                severity: "block",
+                file,
+                message: v === undefined ? `${name} has no profileVersion; me3's schema requires profileVersion = "${ME3_PROFILE_VERSION}".` : `${name} has profileVersion = "${v}"; me3's schema accepts only "${ME3_PROFILE_VERSION}".`,
+                fix: `Add profileVersion = "${ME3_PROFILE_VERSION}" as the first line.`,
+                evidence: EVIDENCE,
+            },
+        ];
+    },
+};
+const supportedGame = {
+    id: "eldenring.me3.supported-game",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "Every [[supports]].game is an id me3 knows, and at least one of them is Elden Ring; a profile with no game needs -g at every launch.",
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed)
+            return [];
+        const { profile, supportsWithoutGame } = parsed.detail;
+        const findings = [];
+        for (const i of supportsWithoutGame) {
+            findings.push({ validatorId: this.id, severity: "warn", file, message: `[[supports]] block ${i + 1} in ${name} has no game key.`, fix: 'Give it game = "eldenring".', evidence: EVIDENCE });
+        }
+        for (const g of profile.supports) {
+            if (!ME3_GAME_IDS.includes(g)) {
+                findings.push({ validatorId: this.id, severity: "warn", file, message: `[[supports]] names game "${g}", which me3 does not know (its ids: ${ME3_GAME_IDS.join(", ")}).`, fix: 'Use game = "eldenring".', evidence: EVIDENCE });
+            }
+        }
+        const known = profile.supports.filter((g) => ME3_GAME_IDS.includes(g));
+        if (profile.supports.length === 0 && supportsWithoutGame.length === 0) {
+            findings.push({ validatorId: this.id, severity: "info", file, message: `${name} lists no [[supports]] game, so 'me3 launch' needs -g eldenring every time and double-clicking the profile cannot pick the game.`, fix: 'Add a [[supports]] block with game = "eldenring".', evidence: EVIDENCE });
+        }
+        else if (known.length > 0 && !known.some((g) => ME3_ELDENRING_IDS.includes(g))) {
+            findings.push({ validatorId: this.id, severity: "warn", file, message: `${name} supports ${known.join(", ")} but not Elden Ring, in an Elden Ring project.`, evidence: EVIDENCE });
+        }
+        return findings;
+    },
+};
+const pathsResolve = {
+    id: "eldenring.me3.paths-resolve",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "Every [[packages]].path is an existing directory and every [[natives]].path an existing .dll, resolved against the profile file (not the game).",
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed)
+            return [];
+        const { profile, entriesWithoutPath } = parsed.detail;
+        const base = path.dirname(file);
+        const findings = [];
+        for (const e of entriesWithoutPath) {
+            findings.push({ validatorId: this.id, severity: "block", file, message: `[[${e.block}]] block ${e.index + 1} in ${name} has no path.`, evidence: EVIDENCE });
+        }
+        for (const block of ["packages", "natives"]) {
+            for (const entry of profile[block]) {
+                if (entry.enabled === false)
+                    continue;
+                const abs = path.isAbsolute(entry.path) ? entry.path : path.resolve(base, entry.path);
+                const exists = await ctx.exists(abs);
+                const label = entry.id ? `${block} "${entry.id}"` : `${block} entry "${entry.path}"`;
+                if (!exists) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file,
+                        message: `${label} in ${name} resolves to ${abs}, which does not exist; me3 resolves paths against the profile file, not the game folder.`,
+                        fix: `Write the path relative to ${base}, or make it absolute (single-quoted so backslashes need no escaping).`,
+                        evidence: EVIDENCE,
+                        related: [abs],
+                    });
+                    continue;
+                }
+                const isDir = await isDirectory(abs);
+                if (block === "packages") {
+                    if (!isDir) {
+                        findings.push({ validatorId: this.id, severity: "warn", file, message: `${label} in ${name} resolves to a file, not a directory; a [[packages]] path is a folder laid out like the game's archives.`, evidence: EVIDENCE, related: [abs] });
+                    }
+                }
+                else if (isDir) {
+                    findings.push({ validatorId: this.id, severity: "warn", file, message: `${label} in ${name} is a folder, not a .dll; [[natives]] are DLL mods, and asset folders belong under [[packages]].`, evidence: EVIDENCE, related: [abs] });
+                }
+                else if (path.extname(entry.path).toLowerCase() !== ".dll") {
+                    findings.push({ validatorId: this.id, severity: "warn", file, message: `${label} in ${name} is not a .dll; [[natives]] are DLL mods, and asset folders belong under [[packages]].`, evidence: EVIDENCE });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const unknownKeys = {
+    id: "eldenring.me3.unknown-keys",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "Every key in the profile and its blocks is one me3's schema defines; a typo'd keyword (pakages, paths, idd) is silently ignored, which the docs name as a common failure.",
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed)
+            return [];
+        return parsed.detail.unknownKeys.map((u) => ({
+            validatorId: this.id,
+            severity: "warn",
+            file,
+            message: `${name}: "${u.key}" in ${u.where} is not a key me3's profile schema defines, so me3 ignores it.`,
+            fix: "Check the spelling against me3's profile schema (profileVersion, savefile, start_online, disable_arxan, mem_patch, mem_patch_heap_size, debug_properties; [[supports]] game/since; [[packages]] id/path/enabled/load_after/load_before; [[natives]] path/optional/enabled/load_after/load_before/initializer/finalizer/load_early; a load_after/load_before entry id/optional).",
+            evidence: EVIDENCE,
+        }));
+    },
+};
+const dependencyIds = {
+    id: "eldenring.me3.dependency-ids",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "Every load_after/load_before id names a package or native in the same profile, and no two entries share an id.",
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed)
+            return [];
+        const { profile } = parsed.detail;
+        const entries = [...profile.packages, ...profile.natives];
+        const ids = new Map();
+        for (const e of entries)
+            if (e.id)
+                ids.set(e.id, (ids.get(e.id) ?? 0) + 1);
+        const findings = [];
+        for (const [id, count] of ids) {
+            if (count > 1)
+                findings.push({ validatorId: this.id, severity: "warn", file, message: `${count} entries in ${name} share id "${id}"; load_after/load_before cannot tell them apart.`, evidence: EVIDENCE });
+        }
+        for (const e of entries) {
+            for (const [key, deps] of [["load_after", e.loadAfter], ["load_before", e.loadBefore]]) {
+                for (const d of deps ?? []) {
+                    if (ids.has(d.id))
+                        continue;
+                    findings.push({
+                        validatorId: this.id,
+                        severity: d.optional ? "info" : "warn",
+                        file,
+                        message: `${e.id ? `"${e.id}"` : `entry "${e.path}"`} in ${name} has ${key} = "${d.id}", which no package or native in this profile is named${d.optional ? " (optional, so me3 proceeds)" : ""}.`,
+                        fix: "Give the other entry that id, or fix the spelling.",
+                        evidence: EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const saveAndOnline = {
+    id: "eldenring.me3.save-and-online",
+    game: "eldenring",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "A profile that loads mods does not set start_online = true (me3's own help calls it a ban risk) and names a savefile (a modded save on the vanilla file is the documented corruption path).",
+    appliesTo: isProfile,
+    appliesToDescription: APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: [...EVIDENCE, "eldenring.me3.savefile-field-isolates-modded-saves", "eldenring.me3.blocks-matchmaking-by-default"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const parsed = await parse(ctx, file);
+        if ("error" in parsed)
+            return [];
+        const { profile } = parsed.detail;
+        const loadsMods = profile.packages.some((p) => p.enabled !== false) || profile.natives.some((n) => n.enabled !== false);
+        if (!loadsMods)
+            return [];
+        const findings = [];
+        if (profile.startOnline === true) {
+            findings.push({ validatorId: this.id, severity: "warn", file, message: `${name} sets start_online = true while loading mods; me3 blocks matchmaking by default because a modded online session risks a ban.`, fix: "Drop start_online, or keep it only for a private-server setup that needs it.", evidence: this.evidence });
+        }
+        if (profile.savefile === undefined) {
+            findings.push({ validatorId: this.id, severity: "info", file, message: `${name} loads mods with no savefile, so the modded game writes the vanilla save; me3's docs recommend a separate one to avoid corrupting it and to keep modded progress off the online character.`, fix: 'Add savefile = "Modded.sl2" (me3 copies the existing save the first time).', evidence: this.evidence });
+        }
+        return findings;
+    },
+};
+export const PROFILE_VALIDATORS = [version, supportedGame, pathsResolve, unknownKeys, dependencyIds, saveAndOnline];

package/dist/surfaces/index.js

@@ -0,0 +1,34 @@
+import { baldursgate3 } from "./baldursgate3/index.js";
+import { cyberpunk2077 } from "./cyberpunk2077/index.js";
+import { skyrimse } from "./skyrimse/index.js";
+import { eldenring } from "./eldenring/index.js";
+import { valheim } from "./valheim/index.js";
+import { subnautica2 } from "./subnautica2/index.js";
+import { stardewvalley } from "./stardewvalley/index.js";
+import { nivalisnights } from "./nivalisnights/index.js";
+export const SURFACES = [cyberpunk2077, baldursgate3, skyrimse, eldenring, valheim, subnautica2, stardewvalley, nivalisnights];
+export function getSurface(nameOrId) {
+    const needle = nameOrId.trim().toLowerCase();
+    return SURFACES.find((surface) => surface.id === needle ||
+        surface.name.toLowerCase() === needle ||
+        surface.aliases?.includes(needle));
+}
+export function surfaceIds() {
+    return SURFACES.map((surface) => surface.id);
+}
+export async function resolveInstall(surface, explicitPath) {
+    if (explicitPath) {
+        return { gameId: surface.id, root: explicitPath, source: "manual" };
+    }
+    const detected = await surface.detect();
+    return detected[0];
+}
+export async function installGameVersion(surface, install) {
+    if (install.version)
+        return install.version;
+    if (!surface.compat)
+        return undefined;
+    const components = await surface.compat.detectComponents(install).catch(() => undefined);
+    const game = components?.find((c) => c.kind === "game");
+    return game?.marketingVersion ?? game?.version ?? undefined;
+}