modwright 0.1.0

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

@@ -0,0 +1,531 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+import { parseTweakXLYaml } from "../index/parsers/tweakxl-yaml.js";
+import { CR2W_VALIDATORS, cnameValue, collectKey, existsInVanillaIndex, existsStaged, isJsonObject, readCr2wJson, readStagedCr2wJson, resourcePathValue, walkObjects, } from "./cr2w.js";
+function fileTarget(t) {
+    return t.kind === "file" ? t.path : undefined;
+}
+function isEntJson(p) {
+    return p.toLowerCase().endsWith(".ent.json");
+}
+function isVehicleEntJson(p) {
+    return isEntJson(p) && /(^|[\\/])v_/i.test(p);
+}
+function isInkatlasJson(p) {
+    return /\.inkatlas\.json$/i.test(p);
+}
+function isYamlFile(p) {
+    return /\.ya?ml$/i.test(p);
+}
+function stagingRoot(project) {
+    return project.sources.find((s) => s.kind === "archive-staging")?.absPath;
+}
+function resolveDepotPath(root, depotPath) {
+    const stripped = depotPath.startsWith("*") ? depotPath.slice(1) : depotPath;
+    return path.join(root, ...stripped.split(/[\\/]/));
+}
+function isVanillaPath(depotPath) {
+    return /^base[\\/]/i.test(depotPath);
+}
+async function resolvesStagedOrVanilla(ctx, root, depotPath) {
+    if (isVanillaPath(depotPath)) {
+        if (!ctx.store)
+            return true;
+        return existsInVanillaIndex(ctx, depotPath);
+    }
+    return existsStaged(ctx, resolveDepotPath(root, depotPath));
+}
+async function allFilesUnder(project, predicate) {
+    const out = [];
+    for (const source of project.sources) {
+        if (!source.exists)
+            continue;
+        const walked = await walk(source.absPath, { limit: 20_000 });
+        for (const rel of walked.files) {
+            if (predicate(rel))
+                out.push(path.join(source.absPath, rel));
+        }
+    }
+    return out;
+}
+function entRootChunk(root) {
+    if (!isJsonObject(root))
+        return undefined;
+    const data = root.Data;
+    if (!isJsonObject(data))
+        return undefined;
+    const rc = data.RootChunk;
+    return isJsonObject(rc) ? rc : undefined;
+}
+function appDefinitionNames(root) {
+    const out = [];
+    walkObjects(root, (obj) => {
+        if (Array.isArray(obj.components) || obj.$type === "appearanceAppearanceDefinition") {
+            const n = cnameValue(obj.name);
+            if (n !== undefined)
+                out.push(n);
+        }
+    });
+    return out;
+}
+const ENT_APP_EVIDENCE = [
+    "cp2077.vehicles.entities.four-core-file-roles",
+    "cp2077.entities.entity-appearance-chain",
+    "cp2077.entities.appearance-submesh-references",
+];
+export const VEHICLE_ENT_APP_RESOLUTION = {
+    id: "cp2077.vehicles.ent-app-resolution",
+    game: "cyberpunk2077",
+    groups: ["vehicles"],
+    modTypes: ["vehicle"],
+    summary: "A vehicle .ent's appearance entries name appearances present in its .app; the .app's component depotPaths and the .ent's rig resolve.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over every v_*.ent.json in the project",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: ENT_APP_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        if (!root)
+            return [];
+        const findings = [];
+        const entFiles = await allFilesUnder(ctx.project, isVehicleEntJson);
+        for (const entFile of entFiles) {
+            const parsed = await readCr2wJson(ctx, entFile);
+            if (!parsed)
+                continue;
+            const rootChunk = entRootChunk(parsed.root);
+            if (!rootChunk)
+                continue;
+            const rig = resourcePathValue(rootChunk.rig ?? rootChunk.deformationRig);
+            if (rig && !(await resolvesStagedOrVanilla(ctx, root, rig))) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: entFile,
+                    message: isVanillaPath(rig)
+                        ? `This vehicle's rig "${rig}" does not resolve in the vanilla archive index.`
+                        : `This vehicle's rig "${rig}" is not staged.`,
+                    fix: `Stage the rig at "${rig}", or fix the path.`,
+                    evidence: ENT_APP_EVIDENCE,
+                });
+            }
+            const appearances = Array.isArray(rootChunk.appearances) ? rootChunk.appearances : [];
+            for (const entry of appearances) {
+                if (!isJsonObject(entry))
+                    continue;
+                const localName = cnameValue(entry.appearanceName);
+                const appPath = resourcePathValue(entry.appearanceResource);
+                if (!appPath)
+                    continue;
+                if (isVanillaPath(appPath)) {
+                    if (ctx.store && !(await existsInVanillaIndex(ctx, appPath))) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file: entFile,
+                            message: `Appearance entry "${localName ?? "?"}" points at .app "${appPath}", which does not resolve in the vanilla archive index.`,
+                            fix: `Fix the path, or build the resource index (build_index) if it has not been built yet.`,
+                            evidence: ENT_APP_EVIDENCE,
+                        });
+                    }
+                    continue;
+                }
+                const appJson = await readStagedCr2wJson(ctx, resolveDepotPath(root, appPath));
+                if (!appJson) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: entFile,
+                        message: `Appearance entry "${localName ?? "?"}" points at .app "${appPath}", which is not staged.`,
+                        fix: `Stage the .app at "${appPath}", or fix the path.`,
+                        evidence: ENT_APP_EVIDENCE,
+                    });
+                    continue;
+                }
+                if (localName !== undefined && !appDefinitionNames(appJson.root).includes(localName)) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: entFile,
+                        related: [appJson.absPath],
+                        message: `Appearance entry names "${localName}", but ${path.basename(appJson.absPath)} defines no appearance with that name.`,
+                        fix: `Add an appearance named "${localName}" to ${path.basename(appJson.absPath)}, or fix the .ent's appearanceName.`,
+                        evidence: ENT_APP_EVIDENCE,
+                    });
+                }
+                for (const hit of collectKey(appJson.root, "DepotPath")) {
+                    const p = resourcePathValue(hit.value);
+                    if (!p || /^\d*$/.test(p))
+                        continue;
+                    if (isVanillaPath(p) && !ctx.store)
+                        continue;
+                    if (!(await resolvesStagedOrVanilla(ctx, root, p))) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file: appJson.absPath,
+                            related: [entFile],
+                            message: isVanillaPath(p)
+                                ? `Component depot path "${p}" at ${hit.jsonPath} does not resolve in the vanilla archive index.`
+                                : `Component depot path "${p}" at ${hit.jsonPath} is not staged.`,
+                            fix: `Stage the file at "${p}", or fix the path.`,
+                            evidence: ENT_APP_EVIDENCE,
+                        });
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+const APPEARANCE_NAME_EVIDENCE = [
+    "cp2077.sectors.node-appearance-name-full",
+    "cp2077.entities.entity-appearance-factory-resolution",
+    "cp2077.tweakdb.weapon-visuals-via-appearanceresourcename",
+];
+function worldEntityNodes(root) {
+    const out = [];
+    walkObjects(root, (obj, jsonPath) => {
+        if (obj.$type !== "worldEntityNode")
+            return;
+        out.push({
+            appearanceName: cnameValue(obj.appearanceName),
+            entityTemplate: resourcePathValue(obj.entityTemplate),
+            jsonPath,
+        });
+    });
+    return out;
+}
+export const VEHICLE_APPEARANCE_NAME_RESOLUTION = {
+    id: "cp2077.vehicles.appearance-name-resolution",
+    game: "cyberpunk2077",
+    groups: ["vehicles"],
+    modTypes: ["vehicle", "world-sector"],
+    summary: "A sector node's appearanceName is the full internal appearance name present in the referenced .ent's appearances and its .app.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over every worldEntityNode in every staged sector json",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: APPEARANCE_NAME_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        if (!root)
+            return [];
+        const findings = [];
+        const jsonFiles = await allFilesUnder(ctx.project, (p) => p.toLowerCase().endsWith(".json"));
+        for (const file of jsonFiles) {
+            const parsed = await readCr2wJson(ctx, file);
+            if (!parsed)
+                continue;
+            for (const node of worldEntityNodes(parsed.root)) {
+                if (!node.appearanceName || !node.entityTemplate)
+                    continue;
+                if (isVanillaPath(node.entityTemplate)) {
+                    if (ctx.store && !(await existsInVanillaIndex(ctx, node.entityTemplate))) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file,
+                            message: `Sector node's entityTemplate "${node.entityTemplate}" does not resolve in the vanilla archive index.`,
+                            fix: `Fix the path, or build the resource index (build_index) if it has not been built yet.`,
+                            evidence: APPEARANCE_NAME_EVIDENCE,
+                        });
+                    }
+                    continue;
+                }
+                const entJson = await readStagedCr2wJson(ctx, resolveDepotPath(root, node.entityTemplate));
+                if (!entJson)
+                    continue;
+                const rootChunk = entRootChunk(entJson.root);
+                const appearances = rootChunk && Array.isArray(rootChunk.appearances) ? rootChunk.appearances : [];
+                const fullNames = appearances
+                    .filter((e) => isJsonObject(e))
+                    .map((e) => cnameValue(e.name))
+                    .filter((n) => n !== undefined);
+                if (fullNames.length === 0)
+                    continue;
+                if (!fullNames.includes(node.appearanceName)) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file,
+                        related: [entJson.absPath],
+                        message: `Sector node at ${node.jsonPath} sets appearanceName "${node.appearanceName}", which is not one of ` +
+                            `${path.basename(entJson.absPath)}'s declared appearance names (${fullNames.join(", ")}). A wrong appearanceName ` +
+                            "spawns an invisible entity with no log line.",
+                        fix: `Use one of ${fullNames.join(", ")}, or add an appearance named "${node.appearanceName}" to the entity template.`,
+                        evidence: APPEARANCE_NAME_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const TWEAK_NAME_EVIDENCE = ["cp2077.vehicles.entities.tweak-name-from-ent-filename"];
+function stripAppearanceSuffix(stem) {
+    const withWord = /^(.*)_{1,2}[a-z][a-z0-9]*_\d{2}$/i.exec(stem);
+    if (withWord)
+        return withWord[1].replace(/_+$/, "");
+    const bare = /^(.*)_{1,2}\d{2}$/.exec(stem);
+    return bare ? bare[1].replace(/_+$/, "") : stem;
+}
+export const VEHICLE_TWEAK_NAME_FROM_ENT = {
+    id: "cp2077.vehicles.tweak-name-from-ent",
+    game: "cyberpunk2077",
+    groups: ["vehicles"],
+    modTypes: ["vehicle"],
+    summary: "A vehicle's TweakDB record name matches the .ent filename with the appearance suffix stripped.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && isVehicleEntJson(f);
+    },
+    appliesToDescription: "every v_*.ent.json file, only when the project declares at least one Vehicle.* TweakDB record",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: TWEAK_NAME_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const stem = path.basename(file).replace(/\.ent\.json$/i, "");
+        const expected = `Vehicle.${stripAppearanceSuffix(stem)}`;
+        const yamlFiles = await allFilesUnder(ctx.project, isYamlFile);
+        const vehicleRecordNames = new Set();
+        for (const yamlFile of yamlFiles) {
+            let text;
+            try {
+                text = await ctx.readText(yamlFile);
+            }
+            catch {
+                continue;
+            }
+            let records;
+            try {
+                records = parseTweakXLYaml(text, yamlFile);
+            }
+            catch {
+                continue;
+            }
+            for (const rec of records) {
+                if (rec.name.startsWith("Vehicle."))
+                    vehicleRecordNames.add(rec.name);
+            }
+        }
+        if (vehicleRecordNames.size === 0)
+            return [];
+        if (vehicleRecordNames.has(expected))
+            return [];
+        return [
+            {
+                validatorId: this.id,
+                severity: "warn",
+                file,
+                message: `No TweakDB record named "${expected}" was found (derived from this .ent's filename with the appearance suffix stripped). ` +
+                    `Declared Vehicle.* records: ${[...vehicleRecordNames].join(", ")}.`,
+                fix: `Name the vehicle's TweakDB record "${expected}", or confirm the filename really matches an existing record.`,
+                evidence: TWEAK_NAME_EVIDENCE,
+            },
+        ];
+    },
+};
+const INKATLAS_RANGE_EVIDENCE = [
+    "cp2077.vehicles.dashboard-ui.inkatlas-uv-percentage-confirms-existing",
+    "cp2077.vehicles.dashboard-ui.inkatlas-three-resolution-slots",
+    "cp2077.ui.icon-atlas-texture-resolution",
+];
+export const VEHICLE_INKATLAS_UV_RANGE = {
+    id: "cp2077.vehicles.inkatlas-uv-range",
+    game: "cyberpunk2077",
+    groups: ["vehicles"],
+    modTypes: ["vehicle", "ui"],
+    summary: "Every inkTextureAtlasMapper slot's four rect coordinates are floats in [0,1] with top-left <= bottom-right; inkTextureSlot 0 is populated.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && isInkatlasJson(f);
+    },
+    appliesToDescription: "every *.inkatlas.json file",
+    needs: {},
+    cost: "edit",
+    severity: "block",
+    evidence: INKATLAS_RANGE_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const findings = [];
+        walkObjects(parsed.root, (obj, jsonPath) => {
+            if (!isJsonObject(obj.rect))
+                return;
+            const rect = obj.rect;
+            const top = rect.Top;
+            const left = rect.Left;
+            const bottom = rect.Bottom;
+            const right = rect.Right;
+            if (typeof top !== "number" || typeof left !== "number" || typeof bottom !== "number" || typeof right !== "number")
+                return;
+            const name = cnameValue(obj.name) ?? "(unnamed part)";
+            const outOfRange = [top, left, bottom, right].some((v) => v < 0 || v > 1);
+            if (outOfRange) {
+                findings.push({
+                    validatorId: "cp2077.vehicles.inkatlas-uv-range",
+                    severity: "block",
+                    file,
+                    message: `Part "${name}" at ${jsonPath} has a rect coordinate outside [0, 1] (Top=${top}, Left=${left}, Bottom=${bottom}, Right=${right}). Inkatlas coordinates are percentages, not pixels.`,
+                    fix: "Express the rect as a fraction of the atlas texture (0 to 1), not a pixel coordinate.",
+                    evidence: INKATLAS_RANGE_EVIDENCE,
+                });
+            }
+            else if (left > right || top > bottom) {
+                findings.push({
+                    validatorId: "cp2077.vehicles.inkatlas-uv-range",
+                    severity: "block",
+                    file,
+                    message: `Part "${name}" at ${jsonPath} has a reversed rect (Left=${left} > Right=${right}, or Top=${top} > Bottom=${bottom}). The top-left corner must be <= the bottom-right corner on both axes.`,
+                    fix: "Swap the coordinates so Left <= Right and Top <= Bottom.",
+                    evidence: INKATLAS_RANGE_EVIDENCE,
+                });
+            }
+        });
+        const slots = collectKey(parsed.root, "slots").find((h) => Array.isArray(h.value));
+        if (slots && Array.isArray(slots.value)) {
+            const slot0 = slots.value[0];
+            const texturePath = isJsonObject(slot0) ? resourcePathValue(slot0.texture) : undefined;
+            if (!texturePath || /^\d*$/.test(texturePath)) {
+                findings.push({
+                    validatorId: "cp2077.vehicles.inkatlas-uv-range",
+                    severity: "block",
+                    file,
+                    message: "inkTextureSlot 0 has no texture populated; slot 0 is the only one required for modding.",
+                    fix: "Populate slots[0].texture with the atlas's source texture depot path.",
+                    evidence: INKATLAS_RANGE_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const INKATLAS_PART_EVIDENCE = [
+    "cp2077.vehicles.dashboard-ui.atlaspartname-mismatch-is-silent",
+    "cp2077.vehicles.dashboard-ui.imagewidget-two-part-atlas-reference",
+    "cp2077.ui.icon-atlas-part-declaration",
+    "cp2077.ui.icon-path-record-name",
+];
+function partNames(atlasRoot) {
+    return collectKey(atlasRoot, "parts")
+        .flatMap((h) => (Array.isArray(h.value) ? h.value : []))
+        .map((p) => (isJsonObject(p) ? cnameValue(p.name) : undefined))
+        .filter((n) => n !== undefined);
+}
+function widgetAtlasRefs(root, file) {
+    const out = [];
+    walkObjects(root, (obj, jsonPath) => {
+        if (!("texturePart" in obj) || !("textureAtlas" in obj))
+            return;
+        const atlasPath = resourcePathValue(obj.textureAtlas);
+        const partName = cnameValue(obj.texturePart);
+        if (atlasPath && partName)
+            out.push({ file, atlasPath, partName, jsonPath });
+    });
+    return out;
+}
+export const VEHICLE_INKATLAS_PART_RESOLVES = {
+    id: "cp2077.vehicles.inkatlas-part-resolves",
+    game: "cyberpunk2077",
+    groups: ["vehicles"],
+    modTypes: ["vehicle", "ui", "icon"],
+    summary: "Every texturePart on an inkImageWidget, and every atlasPartName on a UIIcon record, matches a partName in the referenced .inkatlas.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over every inkImageWidget textureAtlas/texturePart pair and UIIcon atlasResourcePath/atlasPartName pair",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: INKATLAS_PART_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        if (!root)
+            return [];
+        const findings = [];
+        const refs = [];
+        for (const file of await allFilesUnder(ctx.project, (p) => p.toLowerCase().endsWith(".json"))) {
+            const parsed = await readCr2wJson(ctx, file);
+            if (!parsed)
+                continue;
+            refs.push(...widgetAtlasRefs(parsed.root, file));
+        }
+        for (const yamlFile of await allFilesUnder(ctx.project, isYamlFile)) {
+            let text;
+            try {
+                text = await ctx.readText(yamlFile);
+            }
+            catch {
+                continue;
+            }
+            let records;
+            try {
+                records = parseTweakXLYaml(text, yamlFile);
+            }
+            catch {
+                continue;
+            }
+            for (const rec of records) {
+                const atlasFlat = rec.flats.find((f) => f.name === "atlasResourcePath");
+                const partFlat = rec.flats.find((f) => f.name === "atlasPartName");
+                if (atlasFlat && partFlat && typeof atlasFlat.value === "string" && typeof partFlat.value === "string") {
+                    refs.push({ file: yamlFile, atlasPath: atlasFlat.value, partName: partFlat.value, jsonPath: rec.name });
+                }
+            }
+        }
+        const atlasCache = new Map();
+        for (const ref of refs) {
+            if (isVanillaPath(ref.atlasPath)) {
+                if (ctx.store && !(await existsInVanillaIndex(ctx, ref.atlasPath))) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: ref.file,
+                        message: `"${ref.atlasPath}" at ${ref.jsonPath} does not resolve in the vanilla archive index.`,
+                        fix: `Fix the path, or build the resource index (build_index) if it has not been built yet.`,
+                        evidence: INKATLAS_PART_EVIDENCE,
+                    });
+                }
+                continue;
+            }
+            let parts = atlasCache.get(ref.atlasPath);
+            if (parts === undefined && !atlasCache.has(ref.atlasPath)) {
+                const atlasJson = await readStagedCr2wJson(ctx, resolveDepotPath(root, ref.atlasPath));
+                parts = atlasJson ? partNames(atlasJson.root) : undefined;
+                atlasCache.set(ref.atlasPath, parts);
+            }
+            if (parts === undefined)
+                continue;
+            if (!parts.includes(ref.partName)) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: ref.file,
+                    message: `"${ref.partName}" at ${ref.jsonPath} has no matching part in "${ref.atlasPath}"'s inkTextureAtlasMapper (declared parts: ${parts.join(", ") || "(none)"}). An empty icon is displayed for a mismatch like this.`,
+                    fix: `Add a part named "${ref.partName}" to the atlas, or fix the name to match one already declared.`,
+                    evidence: INKATLAS_PART_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const VEHICLE_VALIDATORS = [
+    VEHICLE_ENT_APP_RESOLUTION,
+    VEHICLE_APPEARANCE_NAME_RESOLUTION,
+    VEHICLE_TWEAK_NAME_FROM_ENT,
+    VEHICLE_INKATLAS_UV_RANGE,
+    VEHICLE_INKATLAS_PART_RESOLVES,
+    ...CR2W_VALIDATORS,
+];
+export { CR2W_VALIDATORS } from "./cr2w.js";