modwright 0.1.0

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

@@ -0,0 +1,463 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { walk } from "../../../core/fsutil.js";
+import { globToRegExp } from "../../../core/validate/context.js";
+const GAME = "cyberpunk2077";
+const GROUPS = ["history"];
+const MOD_TYPES = ["packaging"];
+function isProjectTarget(target) {
+    return target.kind === "project";
+}
+function extensionOf(p) {
+    const idx = p.lastIndexOf(".");
+    return idx === -1 ? "" : p.slice(idx).toLowerCase();
+}
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, "/").toLowerCase();
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function buildExcludeMatchers(project) {
+    return (project.build?.exclude ?? []).map(globToRegExp);
+}
+function matchesAny(relPath, matchers) {
+    const norm = normalizeSlashes(relPath);
+    return matchers.some((re) => re.test(norm));
+}
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isWithinAnySource(absPath, project) {
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, absPath));
+}
+const DELETE_BEFORE_SHIP_RE = /delete\s+before\s+ship/i;
+const DEV_SCRIPT_SCAN_EXTENSIONS = new Set([".reds", ".lua", ".py", ".ps1"]);
+const DEV_SCRIPTS_ID = "cp2077.history.dev-scripts-never-ship";
+const DEV_SCRIPTS_EVIDENCE = [
+    "cp2077.packaging.variants.dev-scripts-that-log-every-attack-must-never-ship",
+    "cp2077.packaging.variants.build-script-gates-source-and-dev-script-leakage",
+];
+export const devScriptsNeverShipValidator = {
+    id: DEV_SCRIPTS_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Flags a dev-only file (headed \"DELETE BEFORE SHIP\") that build.exclude does not cover, and any build.exclude-matched file that has leaked into an already-built outDir/staging tree — the exact near-miss a pre-release audit caught live on a real mod.",
+    appliesTo: isProjectTarget,
+    appliesToDescription: "the whole project: every source tree (for the dev-marker check) and build.outDir/build.staging when they already exist on disk (for the leaked-into-output check)",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: DEV_SCRIPTS_EVIDENCE,
+    async run(ctx) {
+        const project = ctx.project;
+        const matchers = buildExcludeMatchers(project);
+        const findings = [];
+        for (const source of project.sources) {
+            if (!source.exists)
+                continue;
+            const { files, truncated } = await walk(source.absPath);
+            for (const rel of files) {
+                if (!DEV_SCRIPT_SCAN_EXTENSIONS.has(extensionOf(rel)))
+                    continue;
+                const abs = path.join(source.absPath, rel);
+                let text;
+                try {
+                    text = await ctx.readText(abs);
+                }
+                catch {
+                    continue;
+                }
+                if (DELETE_BEFORE_SHIP_RE.test(text) && !matchesAny(rel, matchers)) {
+                    findings.push({
+                        validatorId: DEV_SCRIPTS_ID,
+                        severity: "block",
+                        file: abs,
+                        message: `This file is headed "DELETE BEFORE SHIP" but is not covered by any build.exclude pattern, so nothing will stop it from shipping. A real audit found exactly this class of file (a mod's _Debug.reds and _Probe.reds) still deployed in the live game install.`,
+                        fix: `Add a build.exclude pattern that matches "${source.id}/${rel}" (e.g. "**/${path.basename(rel)}"), or delete the file if it is no longer needed.`,
+                        evidence: DEV_SCRIPTS_EVIDENCE,
+                    });
+                }
+            }
+            if (truncated) {
+                findings.push({
+                    validatorId: DEV_SCRIPTS_ID,
+                    severity: "info",
+                    file: source.absPath,
+                    message: `Source "${source.id}" has more files than this scan's limit; the dev-marker scan may be incomplete for it.`,
+                    evidence: DEV_SCRIPTS_EVIDENCE,
+                });
+            }
+        }
+        const roots = [];
+        if (project.build?.outDirExists && project.build.absOutDir) {
+            roots.push({ label: "build.outDir", abs: project.build.absOutDir });
+        }
+        if (project.build?.absStaging) {
+            roots.push({ label: "build.staging", abs: project.build.absStaging });
+        }
+        for (const root of roots) {
+            const { files, truncated } = await walk(root.abs);
+            for (const rel of files) {
+                const abs = path.join(root.abs, rel);
+                if (isWithinAnySource(abs, project))
+                    continue;
+                if (matchesAny(rel, matchers)) {
+                    findings.push({
+                        validatorId: DEV_SCRIPTS_ID,
+                        severity: "block",
+                        file: abs,
+                        message: `"${rel}" matches a build.exclude pattern but is present in ${root.label} (${root.abs}). Either the build step did not filter it out, or it was copied back in after packing — it must not reach the deployable output.`,
+                        fix: `Remove this file from ${root.label}, or re-run the build so its own exclude sweep drops it before packing.`,
+                        evidence: DEV_SCRIPTS_EVIDENCE,
+                    });
+                }
+            }
+            if (truncated) {
+                findings.push({
+                    validatorId: DEV_SCRIPTS_ID,
+                    severity: "info",
+                    file: root.abs,
+                    message: `${root.label} has more files than this scan's limit; the leaked-exclude scan may be incomplete for it.`,
+                    evidence: DEV_SCRIPTS_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const CLEAN_PACK_ID = "cp2077.history.clean-pack-json-sweep";
+const JSON_SIDECAR_EVIDENCE = "cp2077.packaging.variants.build-sources-pack-silently-as-json";
+const DEAD_EFFECT_EVIDENCE = "cp2077.packaging.variants.dead-referenced-fx-resource-must-be-pruned";
+const CLEAN_PACK_EVIDENCE = [
+    JSON_SIDECAR_EVIDENCE,
+    DEAD_EFFECT_EVIDENCE,
+    "cp2077.process.assetbuild.stale-serialized-sidecar-can-resurrect-old-geometry",
+];
+async function localizationBasenames(project, ctx) {
+    const xlSource = project.sources.find((s) => s.kind === "xl" && s.exists);
+    if (!xlSource)
+        return new Set();
+    let text;
+    try {
+        text = await ctx.readText(xlSource.absPath);
+    }
+    catch {
+        return new Set();
+    }
+    let doc;
+    try {
+        doc = parseYaml(text.replace(/^\uFEFF/, ""));
+    }
+    catch {
+        return new Set();
+    }
+    if (!isRecord(doc) || !isRecord(doc.localization) || !isRecord(doc.localization.onscreens))
+        return new Set();
+    const names = new Set();
+    for (const value of Object.values(doc.localization.onscreens)) {
+        if (typeof value === "string")
+            names.add(path.posix.basename(normalizeSlashes(value)));
+    }
+    return names;
+}
+export const cleanPackJsonSweepValidator = {
+    id: CLEAN_PACK_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Sweeps archive-staging for a leaked build-source .json (the *.mesh.json/*.app.json/*.effect.json class that packs silently, since .json is a real game resource type) not covered by build.exclude, and for a dead effect resource no .app in the tree references.",
+    appliesTo: isProjectTarget,
+    appliesToDescription: "every project source of kind \"archive-staging\"",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: CLEAN_PACK_EVIDENCE,
+    async run(ctx) {
+        const project = ctx.project;
+        const matchers = buildExcludeMatchers(project);
+        const findings = [];
+        const stagingSources = project.sources.filter((s) => s.kind === "archive-staging" && s.exists);
+        if (stagingSources.length === 0)
+            return findings;
+        const locNames = await localizationBasenames(project, ctx);
+        for (const source of stagingSources) {
+            const { files, truncated } = await walk(source.absPath);
+            for (const rel of files) {
+                if (extensionOf(rel) !== ".json")
+                    continue;
+                const base = path.posix.basename(normalizeSlashes(rel));
+                if (locNames.has(base))
+                    continue;
+                if (matchesAny(rel, matchers))
+                    continue;
+                findings.push({
+                    validatorId: CLEAN_PACK_ID,
+                    severity: "block",
+                    file: path.join(source.absPath, rel),
+                    message: `"${rel}" is a build-source .json left inside archive-staging ("${source.id}"). Unlike a skipped format such as .png, .json is a real game resource type and the packer includes it SILENTLY — this is exactly how a real release shipped 1.32 MB of *.mesh.json/*.app.json sources by accident.`,
+                    fix: `Delete this file from the staging tree before packing, or add a build.exclude pattern for it if it must remain in the working tree (e.g. "**/${path.basename(rel)}").`,
+                    evidence: [JSON_SIDECAR_EVIDENCE],
+                });
+            }
+            const effectFiles = files.filter((f) => extensionOf(f) === ".effect");
+            if (effectFiles.length > 0) {
+                const appFiles = files.filter((f) => extensionOf(f) === ".app");
+                const appTexts = await Promise.all(appFiles.map(async (f) => {
+                    try {
+                        return (await ctx.readText(path.join(source.absPath, f))).toLowerCase();
+                    }
+                    catch {
+                        return "";
+                    }
+                }));
+                for (const ef of effectFiles) {
+                    const stem = path.posix.basename(ef, ".effect").toLowerCase();
+                    const referenced = appTexts.some((t) => t.includes(stem));
+                    if (!referenced) {
+                        const excluded = matchesAny(ef, matchers);
+                        findings.push({
+                            validatorId: CLEAN_PACK_ID,
+                            severity: "warn",
+                            file: path.join(source.absPath, ef),
+                            message: `"${ef}" is staged in archive-staging ("${source.id}") but the string "${stem}" does not appear in any .app in this tree — it looks like a dead effect resource left over from a reverted design (the documented case: a weapon .app reverted to a vanilla effect, leaving its cloned effect unreferenced).${excluded
+                                ? " It is already covered by build.exclude, so it will not ship, but it remains dead clutter in the working tree — confirm and delete it."
+                                : " It is NOT covered by build.exclude, so it may still ship despite being unreferenced."}`,
+                            fix: `Verify no .app references "${stem}" (search the whole shipping tree, not just this source), then delete the effect resource — or, if it is a real work-in-progress asset, add a build.exclude entry for it.`,
+                            evidence: [DEAD_EFFECT_EVIDENCE],
+                        });
+                    }
+                }
+            }
+            if (truncated) {
+                findings.push({
+                    validatorId: CLEAN_PACK_ID,
+                    severity: "info",
+                    file: source.absPath,
+                    message: `Source "${source.id}" has more files than this scan's limit; the clean-pack sweep may be incomplete for it.`,
+                    evidence: CLEAN_PACK_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const ARCHIVE_SORT_ID = "cp2077.history.archive-name-sort-order";
+const ARCHIVE_SORT_EVIDENCE = [
+    "cp2077.loadorder.archive-conflicts-first-wins",
+    "cp2077.loadorder.reskin-ships-as-override-archive",
+    "cp2077.loadorder.archive-xl-does-not-reprioritise",
+];
+function archiveTargetForSource(targets, source) {
+    const lastSeg = path.basename(source.path).toLowerCase();
+    return targets.find((t) => {
+        if (!t.from.toLowerCase().endsWith(".archive"))
+            return false;
+        const stem = path.basename(t.from, path.extname(t.from)).toLowerCase();
+        return stem.includes(lastSeg) || lastSeg.includes(stem) || stem.includes(source.id.toLowerCase());
+    });
+}
+export const archiveNameSortOrderValidator = {
+    id: ARCHIVE_SORT_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "When two archive-staging sources demonstrably supply the same depot path, checks that the smaller (override/reskin) one is named to sort ASCII-before the larger (base) one — first-wins, not last-wins.",
+    appliesTo: isProjectTarget,
+    appliesToDescription: "the whole project, only when it declares two or more sources of kind \"archive-staging\" whose files overlap",
+    needs: { project: true, install: true },
+    cost: "build",
+    severity: "warn",
+    evidence: ARCHIVE_SORT_EVIDENCE,
+    async run(ctx) {
+        const project = ctx.project;
+        const findings = [];
+        const stagingSources = project.sources.filter((s) => s.kind === "archive-staging" && s.exists);
+        if (stagingSources.length < 2)
+            return findings;
+        const fileSets = new Map();
+        for (const s of stagingSources) {
+            const { files } = await walk(s.absPath);
+            fileSets.set(s.id, new Set(files.map((f) => normalizeSlashes(f))));
+        }
+        const targets = project.project.deploy?.targets ?? [];
+        for (let i = 0; i < stagingSources.length; i++) {
+            for (let j = i + 1; j < stagingSources.length; j++) {
+                const a = stagingSources[i];
+                const b = stagingSources[j];
+                if (!a || !b)
+                    continue;
+                const setA = fileSets.get(a.id);
+                const setB = fileSets.get(b.id);
+                const overlaps = [...setA].some((p) => setB.has(p));
+                if (!overlaps)
+                    continue;
+                const countA = setA.size;
+                const countB = setB.size;
+                if (countA === countB)
+                    continue;
+                const overrideSource = countA < countB ? a : b;
+                const baseSource = countA < countB ? b : a;
+                const overrideTarget = archiveTargetForSource(targets, overrideSource);
+                const baseTarget = archiveTargetForSource(targets, baseSource);
+                if (!overrideTarget || !baseTarget)
+                    continue;
+                const overrideName = path.basename(overrideTarget.from);
+                const baseName = path.basename(baseTarget.from);
+                if (!(overrideName.toLowerCase() < baseName.toLowerCase())) {
+                    findings.push({
+                        validatorId: ARCHIVE_SORT_ID,
+                        severity: "warn",
+                        file: project.file,
+                        message: `"${overrideSource.id}" (${overrideSource.absPath}, the smaller of the two, ${countA < countB ? countA : countB} files) shares at least one depot path with "${baseSource.id}" (${baseSource.absPath}, ${countA < countB ? countB : countA} files), so it looks like an override/reskin archive. Archive load order is ASCII-alphabetical and the FIRST-sorting archive wins — but its deploy target's filename "${overrideName}" does not sort before the base archive's "${baseName}". Vortex's "z-prefix"/last-wins advice is wrong for Cyberpunk 2077 archives, and a .archive.xl does not re-prioritise its .archive either.`,
+                        fix: `Rename the override archive's deploy target so it sorts ASCII-before "${baseName}" — a space right after the shared stem works cleanly (space 0x20 sorts before "." 0x2E), e.g. "${baseName.replace(/\.archive$/i, "")} - Override.archive".`,
+                        evidence: ARCHIVE_SORT_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const DEPLOY_SET_ID = "cp2077.history.deploy-set-completeness";
+const DEPLOY_SET_EVIDENCE = [
+    "cp2077.world.loot-container.three-artifacts-must-deploy-together",
+    "cp2077.archivexl.manifest-registers-at-init",
+];
+export const deploySetCompletenessValidator = {
+    id: DEPLOY_SET_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A project whose .xl registers streaming, factories or localization must declare deploy targets for the archive, the .xl and the tweaks together — redeploying only some of the three leaves ArchiveXL registering against a stale sibling.",
+    appliesTo: isProjectTarget,
+    appliesToDescription: "the whole project, only when its .xl source registers streaming, factories or localization",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: DEPLOY_SET_EVIDENCE,
+    async run(ctx) {
+        const project = ctx.project;
+        const xlSource = project.sources.find((s) => s.kind === "xl" && s.exists);
+        if (!xlSource)
+            return [];
+        let text;
+        try {
+            text = await ctx.readText(xlSource.absPath);
+        }
+        catch {
+            return [];
+        }
+        let doc;
+        try {
+            doc = parseYaml(text.replace(/^\uFEFF/, ""));
+        }
+        catch {
+            return [];
+        }
+        if (!isRecord(doc))
+            return [];
+        const registeredKeys = ["streaming", "factories", "localization"].filter((k) => doc[k] !== undefined);
+        if (registeredKeys.length === 0)
+            return [];
+        const targets = project.project.deploy?.targets ?? [];
+        const hasArchive = targets.some((t) => t.from.toLowerCase().endsWith(".archive"));
+        const hasXl = targets.some((t) => t.from.toLowerCase().endsWith(".xl"));
+        const tweaksSources = project.sources.filter((s) => s.kind === "tweaks");
+        const insideTweaks = (from) => {
+            const candidates = path.isAbsolute(from)
+                ? [from]
+                : [...(project.build ? [path.join(project.build.absOutDir, from)] : []), path.join(project.root, from)];
+            return candidates.some((abs) => tweaksSources.some((s) => {
+                const rel = path.relative(s.absPath, abs);
+                return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+            }));
+        };
+        const hasTweaks = targets.some((t) => tweaksSources.some((s) => s.id === t.from) || insideTweaks(t.from));
+        const missing = [];
+        if (!hasArchive)
+            missing.push("the packed .archive");
+        if (!hasXl)
+            missing.push("the .archive.xl manifest");
+        if (!hasTweaks)
+            missing.push("the tweaks (TweakXL yaml) source");
+        if (missing.length === 0)
+            return [];
+        return [
+            {
+                validatorId: DEPLOY_SET_ID,
+                severity: "block",
+                file: project.file,
+                message: `This project's .xl manifest ("${xlSource.id}") registers ${registeredKeys.map((k) => `"${k}:"`).join(", ")}, but deploy.targets has no target for: ${missing.join(", ")}. Redeploying the archive while leaving an older sibling behind (or vice versa) makes ArchiveXL's registration for it silently fail to appear — the archive, the .xl and the tweaks must deploy together.`,
+                fix: `Add a deploy target for ${missing.join(" and ")} alongside the existing ones in deploy.targets.`,
+                evidence: DEPLOY_SET_EVIDENCE,
+            },
+        ];
+    },
+};
+const FOLDER_PRUNE_ID = "cp2077.history.folder-target-prunes";
+const FOLDER_PRUNE_EVIDENCE = ["observed (2026-09-28): a folder deploy left a renamed .yaml behind in r6/tweaks, where TweakXL still read it", "cp2077.tweakxl.yaml-syntax.files-read-in-name-order"];
+async function isDirectory(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export const folderTargetPrunesValidator = {
+    id: FOLDER_PRUNE_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A deploy target copying a folder into its own subfolder declares a prune, so a renamed or deleted file does not stay deployed.",
+    appliesTo: isProjectTarget,
+    appliesToDescription: "the whole project's deploy.targets",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: FOLDER_PRUNE_EVIDENCE,
+    async run(ctx) {
+        const project = ctx.project;
+        const out = [];
+        for (const t of project.project.deploy?.targets ?? []) {
+            if (!t.into || (t.prune && t.prune.length > 0))
+                continue;
+            const source = project.sources.find((s) => s.id === t.from);
+            const candidates = source
+                ? [source.absPath]
+                : path.isAbsolute(t.from)
+                    ? [t.from]
+                    : [...(project.build ? [path.join(project.build.absOutDir, t.from)] : []), path.join(project.root, t.from)];
+            let folder = false;
+            for (const c of candidates) {
+                if (await isDirectory(c)) {
+                    folder = true;
+                    break;
+                }
+            }
+            if (!folder)
+                continue;
+            const into = t.into.replace(/\\/g, "/").replace(/\/+$/, "");
+            out.push({
+                validatorId: FOLDER_PRUNE_ID,
+                severity: "warn",
+                file: project.file,
+                message: `Deploy target "${t.from}" -> ${t.rootId}/${into} copies a folder and declares no prune, so a file renamed or removed in "${t.from}" stays deployed and keeps loading (observed: a renamed TweakXL file's old copy stayed in r6\\tweaks).`,
+                fix: `Add "prune": ["${into}/**"] to this target.`,
+                evidence: FOLDER_PRUNE_EVIDENCE,
+            });
+        }
+        return out;
+    },
+};
+export const PACKAGING_VALIDATORS = [
+    devScriptsNeverShipValidator,
+    cleanPackJsonSweepValidator,
+    archiveNameSortOrderValidator,
+    deploySetCompletenessValidator,
+    folderTargetPrunesValidator,
+];