modwright 0.1.0

package/dist/surfaces/cyberpunk2077/validators/red4ext.js

@@ -0,0 +1,318 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { PE_MACHINE_AMD64, PE_MACHINE_I386, readPeImageInfo } from "../../../core/compat/pe.js";
+import { walk } from "../../../core/fsutil.js";
+const GAME = "cyberpunk2077";
+const GROUPS = ["plugins"];
+const MOD_TYPES = ["red4ext-plugin"];
+const RED4EXT_ROOT = "red4ext";
+export const RED4EXT_DEPLOY_DEPTH_ID = "cp2077.plugins.red4ext-deploy-depth";
+const DEPLOY_DEPTH_EVIDENCE = [
+    "cp2077.red4ext.api.plugin-directory-depth-one",
+    "cp2077.red4ext.api.deploy-into-names-the-file",
+];
+function red4extTargets(project) {
+    return (project.project.deploy?.targets ?? []).filter((t) => t.rootId === RED4EXT_ROOT);
+}
+function segmentsOf(p) {
+    return p
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((s) => s !== "" && s !== ".");
+}
+async function locateFrom(target, project) {
+    const source = project.sources.find((s) => s.id === target.from);
+    const outDir = project.build?.absOutDir;
+    const candidates = source
+        ? [source.absPath]
+        : path.isAbsolute(target.from)
+            ? [target.from]
+            : [...(outDir ? [path.join(outDir, target.from)] : []), path.join(project.root, target.from)];
+    for (const candidate of candidates) {
+        try {
+            return { abs: candidate, dir: (await fs.stat(candidate)).isDirectory() };
+        }
+        catch {
+        }
+    }
+    return undefined;
+}
+function installedBase(target, sourceName) {
+    return target.into ? target.into : sourceName;
+}
+async function resolveFrom(target, project) {
+    const found = await locateFrom(target, project);
+    if (found)
+        return found.dir ? { kind: "dir", abs: found.abs } : { kind: "file", name: path.basename(found.abs) };
+    const name = segmentsOf(target.from).pop() ?? "";
+    return name.toLowerCase().endsWith(".dll") ? { kind: "file", name } : { kind: "unknown" };
+}
+function judge(p) {
+    const name = p.dest[p.dest.length - 1] ?? "";
+    const depth = p.dest.length - 1;
+    const stem = (p.sourceName ?? name).replace(/\.dll$/i, "");
+    if (!name.toLowerCase().endsWith(".dll")) {
+        return {
+            severity: "block",
+            problem: `the installed file has no ".dll" extension, so the loader never loads it (an "into" that names a folder puts a single-file target at that path: the folder name becomes the file)`,
+            fixInto: [...p.dest, `${stem}.dll`].join("/"),
+        };
+    }
+    if (!name.endsWith(".dll")) {
+        return {
+            severity: "block",
+            problem: `its extension is "${name.slice(-4)}", and the loader compares the extension to ".dll" exactly, so the file is never loaded`,
+            fixInto: [...p.dest.slice(0, -1), `${name.slice(0, -4)}.dll`].join("/"),
+        };
+    }
+    if (depth >= 2) {
+        return {
+            severity: "block",
+            problem: `it sits ${depth} folders deep under red4ext/plugins, and the loader stops descending past depth one, so it is never loaded`,
+            fixInto: `${p.dest[0]}/${name}`,
+        };
+    }
+    if (depth === 0) {
+        return {
+            severity: "warn",
+            problem: `it sits directly in red4ext/plugins; the loader loads it there, but without the altered DLL search path a depth-one plugin gets, so any library shipped beside it will not resolve`,
+            fixInto: `${stem}/${name}`,
+        };
+    }
+    return undefined;
+}
+async function lineOfFrom(ctx, from) {
+    try {
+        const text = await ctx.readText(ctx.project.file);
+        const needle = JSON.stringify(from);
+        const lines = text.split(/\r?\n/);
+        const i = lines.findIndex((l) => /"from"\s*:/.test(l) && l.includes(needle));
+        return i === -1 ? undefined : i + 1;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const red4extDeployDepthValidator = {
+    id: RED4EXT_DEPLOY_DEPTH_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A red4ext deploy target must land every plugin DLL at red4ext/plugins/<Folder>/<Name>.dll: the loader never loads a file without the exact \".dll\" extension or one deeper than one folder, and a DLL directly in plugins/ loads without its own folder on the DLL search path.",
+    appliesTo: (target, project) => target.kind === "project" && red4extTargets(project).length > 0,
+    appliesToDescription: "the whole project, when deploy.targets has a target on the \"red4ext\" root",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: DEPLOY_DEPTH_EVIDENCE,
+    async run(ctx) {
+        const findings = [];
+        for (const target of red4extTargets(ctx.project)) {
+            const from = await resolveFrom(target, ctx.project);
+            if (from.kind === "unknown")
+                continue;
+            const placements = [];
+            if (from.kind === "file") {
+                if (!from.name.toLowerCase().endsWith(".dll"))
+                    continue;
+                const dest = segmentsOf(installedBase(target, from.name));
+                if (dest.length === 0)
+                    continue;
+                placements.push({ dest, sourceName: from.name });
+            }
+            else {
+                const base = segmentsOf(installedBase(target, path.basename(from.abs)));
+                const listed = await walk(from.abs, { limit: 5000 });
+                for (const rel of listed.files) {
+                    if (!rel.toLowerCase().endsWith(".dll"))
+                        continue;
+                    placements.push({ dest: [...base, ...segmentsOf(rel)] });
+                }
+            }
+            for (const placement of placements) {
+                const verdict = judge(placement);
+                if (!verdict)
+                    continue;
+                const installed = `red4ext/plugins/${placement.dest.join("/")}`;
+                const line = await lineOfFrom(ctx, target.from);
+                findings.push({
+                    validatorId: RED4EXT_DEPLOY_DEPTH_ID,
+                    severity: verdict.severity,
+                    file: ctx.project.file,
+                    ...(line !== undefined ? { line } : {}),
+                    message: `deploy target "${target.from}" (root "red4ext"${target.into ? `, into "${target.into}"` : ""}) installs ${installed}: ${verdict.problem}.`,
+                    fix: from.kind === "file" && verdict.fixInto
+                        ? `Set "into": "${verdict.fixInto}" so the plugin lands at red4ext/plugins/${verdict.fixInto}.`
+                        : `Arrange the folder so each plugin DLL sits one folder below red4ext/plugins (plugins/<Folder>/<Name>.dll), or point "into" at that folder.`,
+                    evidence: DEPLOY_DEPTH_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const RED4EXT_ARCH_X64_ID = "cp2077.plugins.red4ext-arch-x64";
+export const RED4EXT_EXPORTS_PRESENT_ID = "cp2077.plugins.red4ext-exports-present";
+const ARCH_EVIDENCE = ["cp2077.red4ext.api.any-toolchain-x64-fastcall"];
+const EXPORTS_EVIDENCE = [
+    "cp2077.red4ext.api.plugin-exports-supports-query-required",
+    "cp2077.red4ext.api.plugin-exports-matched-by-exact-name",
+];
+async function builtDlls(project) {
+    const dlls = [];
+    const unbuilt = [];
+    for (const target of red4extTargets(project)) {
+        const found = await locateFrom(target, project);
+        if (!found) {
+            if (target.from.toLowerCase().endsWith(".dll"))
+                unbuilt.push(target);
+            continue;
+        }
+        if (!found.dir) {
+            if (found.abs.toLowerCase().endsWith(".dll"))
+                dlls.push({ target, abs: found.abs, single: true });
+            continue;
+        }
+        const listed = await walk(found.abs, { limit: 5000 });
+        for (const rel of listed.files) {
+            if (rel.toLowerCase().endsWith(".dll"))
+                dlls.push({ target, abs: path.join(found.abs, rel), single: false });
+        }
+    }
+    return { dlls, unbuilt };
+}
+function unbuiltFinding(id, ctx, target, evidence) {
+    return {
+        validatorId: id,
+        severity: "info",
+        file: ctx.project.file,
+        message: `deploy target "${target.from}" (root "red4ext") is not built yet, so its DLL was not checked.`,
+        fix: "Run build, then validate again.",
+        evidence,
+    };
+}
+function machineName(machine) {
+    if (machine === PE_MACHINE_AMD64)
+        return "x64 (AMD64)";
+    if (machine === PE_MACHINE_I386)
+        return "x86 (I386)";
+    return `machine 0x${machine.toString(16)}`;
+}
+export const red4extArchX64Validator = {
+    id: RED4EXT_ARCH_X64_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every DLL a red4ext target deploys must be an x64 image: the game is a 64-bit process, and LoadLibrary refuses anything else, so the loader never loads it.",
+    appliesTo: (target, project) => target.kind === "project" && red4extTargets(project).length > 0,
+    appliesToDescription: "the whole project, when deploy.targets has a target on the \"red4ext\" root (its built DLLs)",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: ARCH_EVIDENCE,
+    async run(ctx) {
+        const { dlls, unbuilt } = await builtDlls(ctx.project);
+        const findings = unbuilt.map((t) => unbuiltFinding(RED4EXT_ARCH_X64_ID, ctx, t, ARCH_EVIDENCE));
+        for (const dll of dlls) {
+            const info = await readPeImageInfo(dll.abs);
+            if (!info) {
+                findings.push({
+                    validatorId: RED4EXT_ARCH_X64_ID,
+                    severity: "warn",
+                    file: dll.abs,
+                    message: `${path.basename(dll.abs)} could not be read as a PE image, so its machine type was not checked (a non-PE file named .dll, or a layout ModWright's reader does not handle).`,
+                    evidence: ARCH_EVIDENCE,
+                });
+                continue;
+            }
+            if (info.machine === PE_MACHINE_AMD64 && info.pe32Plus)
+                continue;
+            findings.push({
+                validatorId: RED4EXT_ARCH_X64_ID,
+                severity: "block",
+                file: dll.abs,
+                message: `${path.basename(dll.abs)} is built for ${machineName(info.machine)}${info.pe32Plus ? "" : " (a PE32 image)"}; Cyberpunk 2077 is a 64-bit process, so LoadLibrary refuses it and RED4ext logs "Could not load plugin".`,
+                fix: "Build the plugin for x64 (cmake -A x64, or the x64 Native Tools prompt for cl.exe).",
+                evidence: ARCH_EVIDENCE,
+            });
+        }
+        return findings;
+    },
+};
+const REQUIRED_EXPORTS = ["Supports", "Query"];
+function decoratedAs(name, exports) {
+    return exports.find((e) => e !== name && (e.startsWith(`?${name}@`) || e.startsWith(`_Z${name.length}${name}`)));
+}
+function describeMissing(names, info) {
+    return names
+        .map((n) => {
+        const decorated = decoratedAs(n, info.exports);
+        return decorated ? `"${n}" (exported only as the C++-decorated "${decorated}")` : `"${n}"`;
+    })
+        .join(", ");
+}
+export const red4extExportsPresentValidator = {
+    id: RED4EXT_EXPORTS_PRESENT_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A RED4ext plugin DLL must export \"Supports\" and \"Query\" under those exact names (the loader looks them up with GetProcAddress and drops the plugin without them) and should export \"Main\", without which it loads but never initialises.",
+    appliesTo: (target, project) => target.kind === "project" && red4extTargets(project).length > 0,
+    appliesToDescription: "the whole project, when deploy.targets has a target on the \"red4ext\" root (its built DLLs)",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: EXPORTS_EVIDENCE,
+    async run(ctx) {
+        const { dlls, unbuilt } = await builtDlls(ctx.project);
+        const findings = unbuilt.map((t) => unbuiltFinding(RED4EXT_EXPORTS_PRESENT_ID, ctx, t, EXPORTS_EVIDENCE));
+        for (const dll of dlls) {
+            const info = await readPeImageInfo(dll.abs);
+            if (!info)
+                continue;
+            const name = path.basename(dll.abs);
+            const missing = REQUIRED_EXPORTS.filter((n) => !info.exports.includes(n));
+            const hasMain = info.exports.includes("Main");
+            const anyPluginExport = !(missing.length === REQUIRED_EXPORTS.length) || hasMain;
+            const decorationFix = 'Declare the plugin functions with RED4EXT_C_EXPORT (extern "C" __declspec(dllexport)) so they are exported undecorated.';
+            if (missing.length > 0) {
+                const decoratedAny = [...REQUIRED_EXPORTS, "Main"].some((n) => decoratedAs(n, info.exports));
+                if (!dll.single && !anyPluginExport && !decoratedAny) {
+                    findings.push({
+                        validatorId: RED4EXT_EXPORTS_PRESENT_ID,
+                        severity: "info",
+                        file: dll.abs,
+                        message: `${name} exports none of Supports, Query or Main, so it is taken for a library shipped beside a plugin. If it sits one folder below red4ext/plugins the loader still tries it as a plugin and logs "Could not retrieve 'Supports' function" for it; that line is expected.`,
+                        evidence: EXPORTS_EVIDENCE,
+                    });
+                    continue;
+                }
+                findings.push({
+                    validatorId: RED4EXT_EXPORTS_PRESENT_ID,
+                    severity: "block",
+                    file: dll.abs,
+                    message: `${name} does not export ${describeMissing(missing, info)}; RED4ext looks each up with GetProcAddress by that exact name, logs "Could not retrieve '${missing[0]}' function" and does not load the plugin.`,
+                    fix: decorationFix,
+                    evidence: EXPORTS_EVIDENCE,
+                });
+                continue;
+            }
+            if (!hasMain) {
+                findings.push({
+                    validatorId: RED4EXT_EXPORTS_PRESENT_ID,
+                    severity: "warn",
+                    file: dll.abs,
+                    message: `${name} does not export ${describeMissing(["Main"], info)}; RED4ext loads it but skips the call ("does not export a 'Main' function, skipping the call" at trace level), so nothing it registers in Main exists.`,
+                    fix: decorationFix,
+                    evidence: EXPORTS_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const RED4EXT_VALIDATORS = [
+    red4extDeployDepthValidator,
+    red4extArchX64Validator,
+    red4extExportsPresentValidator,
+];

package/dist/surfaces/cyberpunk2077/validators/redscript.js

@@ -0,0 +1,193 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+const ID = "cp2077.history.redscript-duplicate-global-func";
+const EVIDENCE = ["cp2077.redscript.modules.duplicate-global-func-crashes-the-script-load"];
+function stripCommentsAndStrings(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        const n = text[i + 1];
+        if (c === "/" && n === "/") {
+            while (i < text.length && text[i] !== "\n") {
+                out += " ";
+                i++;
+            }
+        }
+        else if (c === "/" && n === "*") {
+            out += "  ";
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
+                out += text[i] === "\n" ? "\n" : " ";
+                i++;
+            }
+            if (i < text.length) {
+                out += "  ";
+                i += 2;
+            }
+        }
+        else if (c === '"') {
+            out += " ";
+            i++;
+            while (i < text.length && text[i] !== '"' && text[i] !== "\n") {
+                if (text[i] === "\\") {
+                    out += " ";
+                    i++;
+                }
+                out += " ";
+                i++;
+            }
+            if (i < text.length && text[i] === '"') {
+                out += " ";
+                i++;
+            }
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}
+function splitParams(list) {
+    const parts = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of list) {
+        if (ch === "<")
+            depth++;
+        else if (ch === ">")
+            depth--;
+        if (ch === "," && depth === 0) {
+            parts.push(cur);
+            cur = "";
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur.trim().length > 0)
+        parts.push(cur);
+    return parts;
+}
+function paramType(param) {
+    const p = param.trim();
+    const colon = p.indexOf(":");
+    const opt = /^opt\s/.test(p) ? "opt " : "";
+    const type = colon >= 0 ? p.slice(colon + 1) : p;
+    return opt + type.replace(/\s+/g, "");
+}
+const FUNC_RE = /^\s*(?:(?:public|private|protected|static|final|native|exec|cb|quest)\s+)*func\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)/;
+const MODULE_RE = /^\s*module\s+[A-Za-z_]/m;
+export function moduleLessGlobals(text) {
+    const clean = stripCommentsAndStrings(text.replace(/\r\n/g, "\n"));
+    if (MODULE_RE.test(clean))
+        return undefined;
+    const rawLines = text.replace(/\r\n/g, "\n").split("\n");
+    const lines = clean.split("\n");
+    const out = [];
+    let depth = 0;
+    let annotated = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (depth === 0) {
+            if (trimmed.startsWith("@")) {
+                annotated = true;
+            }
+            else if (trimmed.length > 0) {
+                const m = FUNC_RE.exec(line);
+                if (m && !annotated) {
+                    out.push({
+                        name: m[1],
+                        paramTypes: splitParams(m[2]).map(paramType),
+                        decl: (rawLines[i] ?? "").trim(),
+                        line: i + 1,
+                    });
+                }
+                annotated = false;
+            }
+        }
+        for (const ch of line) {
+            if (ch === "{")
+                depth++;
+            else if (ch === "}")
+                depth = Math.max(0, depth - 1);
+        }
+    }
+    return out;
+}
+async function collectScriptFiles(project) {
+    const files = [];
+    for (const source of project.sources) {
+        if (source.kind !== "scripts" || !source.exists)
+            continue;
+        if (source.absPath.toLowerCase().endsWith(".reds")) {
+            files.push(source.absPath);
+            continue;
+        }
+        const walked = await walk(source.absPath, { limit: 20_000 });
+        for (const rel of walked.files) {
+            if (rel.toLowerCase().endsWith(".reds"))
+                files.push(path.join(source.absPath, rel));
+        }
+    }
+    files.sort();
+    return files;
+}
+const redscriptDuplicateGlobalFunc = {
+    id: ID,
+    game: "cyberpunk2077",
+    groups: ["history"],
+    modTypes: ["gameplay-tweak"],
+    summary: "No two module-less global redscript functions share a name and a parameter-type list: that compiles, then crashes the game at script load.",
+    appliesTo(target) {
+        return target.kind === "project";
+    },
+    appliesToDescription: 'every .reds file under a project source of kind "scripts", reasoned about together once per validation',
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const files = await collectScriptFiles(ctx.project);
+        const seen = new Map();
+        const findings = [];
+        for (const file of files) {
+            let text;
+            try {
+                text = await ctx.readText(file);
+            }
+            catch {
+                continue;
+            }
+            const globals = moduleLessGlobals(text);
+            if (!globals)
+                continue;
+            for (const fn of globals) {
+                const key = `${fn.name}(${fn.paramTypes.join(",")})`;
+                const first = seen.get(key);
+                if (!first) {
+                    seen.set(key, { file, fn });
+                    continue;
+                }
+                const where = first.file === file ? `line ${first.fn.line} of this file` : `${path.basename(first.file)}:${first.fn.line}`;
+                findings.push({
+                    validatorId: ID,
+                    severity: "block",
+                    file,
+                    line: fn.line,
+                    message: `"${fn.decl}" is a second module-less global ${fn.name} with the same parameter types as "${first.fn.decl}" (${where}). ` +
+                        "redscript compiles both, and the game then crashes at launch as it loads the script blob (the engine copies one definition onto the other and matches their parameters by name).",
+                    fix: `Rename one of them (for example the newer one to a name no other file uses), and update its callers, including any CET bridge code that calls Game.${fn.name}.`,
+                    evidence: EVIDENCE,
+                    related: [first.file],
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const REDSCRIPT_VALIDATORS = [redscriptDuplicateGlobalFunc];

package/dist/surfaces/cyberpunk2077/validators/templates.js

@@ -0,0 +1,7 @@
+import { vanillaExtractNeverShipValidator } from "../../../core/text/validate.js";
+export const vanillaExtractNeverShipsValidator = vanillaExtractNeverShipValidator({
+    id: "cp2077.history.vanilla-extract-never-ships",
+    game: "cyberpunk2077",
+    evidence: ["ModWright research"],
+});
+export const TEMPLATE_VALIDATORS = [vanillaExtractNeverShipsValidator];