modwright 0.1.0

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

@@ -0,0 +1,1181 @@
+import * as path from "node:path";
+import { promises as fs } from "node:fs";
+import { walk } from "../../../core/fsutil.js";
+import { parseTweakXLYaml } from "../index/parsers/tweakxl-yaml.js";
+import { locateTool, runTool } from "../../../core/toolchain/index.js";
+import { TOOL_SPECS } from "../../../core/toolchain/specs.js";
+import { cnameValue, collectDollarValueStrings, collectKey, collectResourcePaths, existsInVanillaIndex, existsStaged, isJsonObject, readCr2wJson, readStagedCr2wJson, resourcePathValue, walkObjects, } from "./cr2w.js";
+async function existsStagedOrVanilla(ctx, absPath, depotPath) {
+    if (await existsStaged(ctx, absPath))
+        return true;
+    return existsInVanillaIndex(ctx, depotPath);
+}
+const KNOWN_PLACEHOLDERS = new Set([
+    "camera",
+    "gender",
+    "body",
+    "arms",
+    "feet",
+    "sleeves",
+    "skin_color",
+    "hair_color",
+]);
+function isKnownPlaceholder(token) {
+    if (KNOWN_PLACEHOLDERS.has(token))
+        return true;
+    return /^variant(\.\d+)?$/.test(token);
+}
+const ENUMERABLE_VALUES = {
+    camera: ["fpp", "tpp"],
+    gender: ["m", "w"],
+    arms: ["base_arms", "mantis_blades", "monowire", "projectile_launcher"],
+    feet: ["flat", "lifted", "high_heels", "flat_shoes"],
+    sleeves: ["full", "part"],
+};
+const PLACEHOLDER_RE = /\{([a-zA-Z_][a-zA-Z0-9_.]*)\}/g;
+function placeholdersIn(text) {
+    const out = [];
+    let m;
+    PLACEHOLDER_RE.lastIndex = 0;
+    while ((m = PLACEHOLDER_RE.exec(text)))
+        out.push(m[1]);
+    return out;
+}
+const KNOWN_VISUAL_TAGS = new Set([
+    "hide_H1",
+    "hide_F1",
+    "hide_T1",
+    "hide_T2",
+    "hide_L1",
+    "hide_S1",
+    "hide_Hair",
+    "hide_Genitals",
+    "hide_T1part",
+    "hide_Head",
+    "hide_Torso",
+    "hide_LowerAbdomen",
+    "hide_UpperAbdomen",
+    "hide_CollarBone",
+    "hide_Arms",
+    "hide_Thighs",
+    "hide_Calves",
+    "hide_Ankles",
+    "hide_Feet",
+    "hide_Legs",
+    "AppearanceParts",
+    "HighHeels",
+    "FlatShoes",
+    "force_FlatFeet",
+    "force_Hair",
+    "DynamicAppearance",
+]);
+const KNOWN_OUTFIT_SLOTS = new Set([
+    "TorsoUnder",
+    "TorsoInner",
+    "TorsoMiddle",
+    "TorsoOuter",
+    "TorsoAux",
+    "LegsInner",
+    "LegsMiddle",
+    "LegsOuter",
+    "BodyUnder",
+    "BodyInner",
+    "BodyMiddle",
+    "BodyOuter",
+    "EarLeft",
+    "EarRight",
+    "EyeLeft",
+    "EyeRight",
+    "Eyes",
+    "ShoulderLeft",
+    "ShoulderRight",
+    "ElbowLeft",
+    "ElbowRight",
+    "WristLeft",
+    "WristRight",
+    "HandLeft",
+    "HandRight",
+    "Hands",
+    "FingersLeft",
+    "FingersRight",
+    "FingernailsLeft",
+    "FingernailsRight",
+    "ThighLeft",
+    "ThighRight",
+    "KneeLeft",
+    "KneeRight",
+    "AnkleLeft",
+    "AnkleRight",
+    "ToesLeft",
+    "ToesRight",
+    "ToenailsLeft",
+    "ToenailsRight",
+    "HandPropLeft",
+    "HandPropRight",
+    "Head",
+    "Glasses",
+    "Mask",
+    "Feet",
+    "NecklaceShort",
+]);
+function isEntJson(p) {
+    return p.toLowerCase().endsWith(".ent.json");
+}
+function isAppJson(p) {
+    return p.toLowerCase().endsWith(".app.json");
+}
+function isXlManifest(p) {
+    return p.toLowerCase().endsWith(".archive.xl");
+}
+function isYamlFile(p) {
+    return /\.ya?ml$/i.test(p);
+}
+function fileTarget(t) {
+    return t.kind === "file" ? t.path : undefined;
+}
+function toSnakeCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}
+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(/[\\/]/));
+}
+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;
+}
+async function readYaml(ctx, absPath) {
+    try {
+        const text = await ctx.readText(absPath);
+        const YAML = await import("yaml");
+        return YAML.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function xlManifests(ctx) {
+    const files = await allFilesUnder(ctx.project, isXlManifest);
+    const out = [];
+    for (const file of files) {
+        const parsed = await readYaml(ctx, file);
+        if (isJsonObject(parsed))
+            out.push({ file, manifest: parsed });
+    }
+    return out;
+}
+function bodyValueSet(manifests) {
+    const values = new Set(["base_body"]);
+    for (const { manifest } of manifests) {
+        const player = manifest.player;
+        if (!isJsonObject(player))
+            continue;
+        const bodyTypes = player.bodyTypes;
+        if (!Array.isArray(bodyTypes))
+            continue;
+        for (const bt of bodyTypes) {
+            if (typeof bt === "string")
+                values.add(toSnakeCase(bt));
+        }
+    }
+    return [...values];
+}
+function customTagNames(manifests) {
+    const out = new Set();
+    for (const { manifest } of manifests) {
+        const overrides = manifest.overrides;
+        if (!isJsonObject(overrides))
+            continue;
+        const tags = overrides.tags;
+        if (!isJsonObject(tags))
+            continue;
+        for (const key of Object.keys(tags))
+            out.add(key);
+    }
+    return out;
+}
+const STAR_PREFIX_EVIDENCE = ["cp2077.clothing.garments.substitution-path-requires-star-prefix"];
+export const GARMENT_STAR_PREFIX = {
+    id: "cp2077.garments.substitution-star-prefix",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "A mesh-entity component depotPath containing {…} must start with *.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && (isEntJson(f) || isAppJson(f));
+    },
+    appliesToDescription: "every .ent.json/.app.json file",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: STAR_PREFIX_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const findings = [];
+        for (const { path: p, jsonPath } of collectResourcePaths(parsed.root)) {
+            if (p.includes("{") && !p.startsWith("*")) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `Depot path "${p}" at ${jsonPath} contains a {…} substitution placeholder but does not start with "*". ` +
+                        "ArchiveXL only substitutes {placeholder} in a mesh-entity component's depot path when the path starts with *; " +
+                        "without it, the literal, unsubstituted path is looked up and the game crashes loading a mesh that does not exist.",
+                    fix: `Prefix the path with "*": "*${p}".`,
+                    evidence: STAR_PREFIX_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const PLACEHOLDER_KNOWN_EVIDENCE = [
+    "cp2077.clothing.garments.dynamic-appearance-placeholders",
+    "cp2077.clothing.garments.dynamic-variant-name-syntax",
+];
+export const GARMENT_PLACEHOLDER_KNOWN = {
+    id: "cp2077.garments.placeholder-known",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "Every {…} placeholder used is one of ArchiveXL's documented substitutions.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && (isEntJson(f) || isAppJson(f));
+    },
+    appliesToDescription: "every .ent.json/.app.json file",
+    needs: {},
+    cost: "edit",
+    severity: "block",
+    evidence: PLACEHOLDER_KNOWN_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const findings = [];
+        const seen = new Set();
+        for (const { value, jsonPath } of collectDollarValueStrings(parsed.root)) {
+            for (const token of placeholdersIn(value)) {
+                if (isKnownPlaceholder(token))
+                    continue;
+                const key = `${token}@${jsonPath}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `"{${token}}" at ${jsonPath} (in "${value}") is not a placeholder ModWright's knowledge base attests as of ` +
+                        "the wiki's 2026-09-07 reading (camera, gender, body, arms, feet, sleeves, skin_color, hair_color, variant/variant.N). " +
+                        "It may be a real, newer ArchiveXL substitution unknown to this check, or a typo — check the spelling first.",
+                    fix: "Use one of camera, gender, body, arms, feet, sleeves, skin_color, hair_color, variant, variant.1, variant.2.",
+                    evidence: PLACEHOLDER_KNOWN_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const COMBINATION_EVIDENCE = [
+    "cp2077.clothing.garments.unvalidated-variant-crashes",
+    "cp2077.clothing.refits.default-body-tag-is-base-body",
+];
+const COMBINATION_CAP = 64;
+export const GARMENT_COMBINATION_RESOLVES = {
+    id: "cp2077.garments.substitution-combination-resolves",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "Every combination of the placeholders actually present in a substituted path resolves to a staged file or the vanilla archive index.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over every *-prefixed substituted depotPath in the project's .ent.json files",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: COMBINATION_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        if (!root)
+            return [];
+        const manifests = await xlManifests(ctx);
+        const values = { ...ENUMERABLE_VALUES, body: bodyValueSet(manifests) };
+        const entFiles = await allFilesUnder(ctx.project, isEntJson);
+        const findings = [];
+        let capped = false;
+        for (const file of entFiles) {
+            const parsed = await readCr2wJson(ctx, file);
+            if (!parsed)
+                continue;
+            for (const { path: p, jsonPath } of collectResourcePaths(parsed.root)) {
+                if (!p.startsWith("*") || !p.includes("{"))
+                    continue;
+                const tokens = [...new Set(placeholdersIn(p))];
+                if (tokens.length === 0)
+                    continue;
+                if (tokens.some((t) => !isKnownPlaceholder(t) || !(t in values)))
+                    continue;
+                const domains = tokens.map((t) => values[t]);
+                const total = domains.reduce((n, d) => n * d.length, 1);
+                if (total > COMBINATION_CAP) {
+                    if (!capped) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "info",
+                            file,
+                            message: `${jsonPath} enumerates ${total} combinations of {${tokens.join("}{")}}, over the ${COMBINATION_CAP}-combination cap; skipped rather than reporting a partial answer as clean.`,
+                            evidence: COMBINATION_EVIDENCE,
+                        });
+                        capped = true;
+                    }
+                    continue;
+                }
+                let combos = [[]];
+                for (const domain of domains) {
+                    combos = combos.flatMap((prefix) => domain.map((v) => [...prefix, v]));
+                }
+                for (const combo of combos) {
+                    let resolved = p;
+                    tokens.forEach((t, i) => {
+                        resolved = resolved.split(`{${t}}`).join(combo[i]);
+                    });
+                    const abs = resolveDepotPath(root, resolved);
+                    if (!(await existsStagedOrVanilla(ctx, abs, resolved))) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file,
+                            message: `The combination {${tokens.map((t, i) => `${t}=${combo[i]}`).join(", ")}} of ${jsonPath} resolves to ` +
+                                `"${resolved}", which is not staged (expected at ${abs}) and does not resolve in the vanilla archive index. ` +
+                                "ArchiveXL crashes the game loading a mesh that does not exist for whichever combination the player's install produces.",
+                            fix: `Stage a mesh at "${resolved}", or narrow the {${tokens.join("}/{")}} this component actually supports.`,
+                            evidence: COMBINATION_EVIDENCE,
+                        });
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+const BODY_TAG_EVIDENCE = [
+    "cp2077.clothing.refits.bodytypes-key-snake-cases-name",
+    "cp2077.clothing.refits.body-tag-patches-player-ent",
+    "cp2077.clothing.refits.body-patch-lists-gendered-player-ents",
+    "cp2077.clothing.refits.default-body-tag-is-base-body",
+];
+export const GARMENT_BODY_TAG_REGISTRATION = {
+    id: "cp2077.garments.body-tag-registration",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "A .xl declaring player.bodyTypes ships a patch .ent with a matching Body:<Name> component.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, when a project's .xl declares player.bodyTypes",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: BODY_TAG_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        const manifests = await xlManifests(ctx);
+        const findings = [];
+        for (const { file: xlFile, manifest } of manifests) {
+            const player = manifest.player;
+            if (!isJsonObject(player) || !Array.isArray(player.bodyTypes))
+                continue;
+            const patch = isJsonObject(manifest.resource) ? manifest.resource.patch : undefined;
+            const patchEntKeys = isJsonObject(patch) ? Object.keys(patch) : [];
+            for (const bodyType of player.bodyTypes) {
+                if (typeof bodyType !== "string")
+                    continue;
+                const wantedName = `Body:${bodyType}`;
+                let found = false;
+                for (const depotKey of patchEntKeys) {
+                    if (!root)
+                        break;
+                    const abs = resolveDepotPath(root, depotKey);
+                    const parsed = await readStagedCr2wJson(ctx, abs);
+                    if (!parsed)
+                        continue;
+                    const names = collectKey(parsed.root, "name").map((h) => cnameValue(h.value));
+                    if (names.includes(wantedName)) {
+                        found = true;
+                        break;
+                    }
+                }
+                if (!found) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: xlFile,
+                        message: `player.bodyTypes declares "${bodyType}", but no patch .ent registered under resource.patch has an ` +
+                            `entMeshComponent named "${wantedName}". PuppetStateSystem's body-type lookup (and every {body} substitution ` +
+                            `resolving to "${toSnakeCase(bodyType)}") depends on that component existing on the patched player entity.`,
+                        fix: `Add an entMeshComponent named "${wantedName}" to the patch .ent listed under resource.patch in ${path.basename(xlFile)}.`,
+                        evidence: BODY_TAG_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const VISUAL_TAGS_EVIDENCE = [
+    "cp2077.clothing.garments.vanilla-hide-tags-by-slot",
+    "cp2077.clothing.garments.archivexl-fine-grained-hide-tags",
+    "cp2077.clothing.garments.visual-tags-are-case-sensitive",
+    "cp2077.clothing.garments.custom-tag-declared-in-xl-not-yaml",
+    "cp2077.clothing.garments.force-hair-tag",
+    "cp2077.clothing.garments.heel-state-tags-need-foot-base",
+];
+function collectAppearanceComponentGroups(root) {
+    const groups = [];
+    walkObjects(root, (obj) => {
+        if (!Array.isArray(obj.components))
+            return;
+        const names = obj.components
+            .map((c) => (isJsonObject(c) ? cnameValue(c.name) : undefined))
+            .filter((n) => n !== undefined);
+        if (names.length > 0)
+            groups.push(names);
+    });
+    return groups;
+}
+export const GARMENT_VISUAL_TAGS_RESOLVE = {
+    id: "cp2077.garments.visual-tags-resolve",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit", "recolor"],
+    summary: "Every hide_*/force_*/HighHeels/FlatShoes tag is documented, or declared in this project's own .xl overrides.tags; component names are unique within an appearance.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && (isEntJson(f) || isAppJson(f));
+    },
+    appliesToDescription: "every .ent.json/.app.json file",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: VISUAL_TAGS_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const findings = [];
+        const custom = customTagNames((await xlManifests(ctx)));
+        for (const hit of collectKey(parsed.root, "tags")) {
+            if (!Array.isArray(hit.value))
+                continue;
+            for (const t of hit.value) {
+                const tag = cnameValue(t);
+                if (!tag || !tag.startsWith("hide_") && !["HighHeels", "FlatShoes", "force_FlatFeet", "force_Hair", "DynamicAppearance", "AppearanceParts"].includes(tag))
+                    continue;
+                if (custom.has(tag) || KNOWN_VISUAL_TAGS.has(tag))
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file,
+                    message: `Visual tag "${tag}" at ${hit.jsonPath} is not in ModWright's documented vanilla/ArchiveXL tag vocabulary ` +
+                        "(as of this knowledge base's last check) and is not declared in this project's own .xl overrides.tags block. " +
+                        "Tags are case-sensitive, so this may be a casing or spelling slip on a real tag.",
+                    fix: "Check spelling and case against the documented tag list, or declare it as a custom tag in this project's .xl overrides.tags block.",
+                    evidence: VISUAL_TAGS_EVIDENCE,
+                });
+            }
+        }
+        for (const group of collectAppearanceComponentGroups(parsed.root)) {
+            const seen = new Map();
+            for (const name of group)
+                seen.set(name, (seen.get(name) ?? 0) + 1);
+            for (const [name, count] of seen) {
+                if (count > 1) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file,
+                        message: `Component name "${name}" appears ${count} times within one appearance. A custom-tag override in .xl ` +
+                            "overrides.tags matches on component name alone, so a duplicate silently applies to the wrong component.",
+                        fix: "Give each component a unique name within the appearance.",
+                        evidence: VISUAL_TAGS_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const ROOT_BLANK_EVIDENCE = ["cp2077.clothing.garments.root-entity-single-blank-appearance"];
+const DYNAMIC_TAG_EVIDENCE = [
+    "cp2077.clothing.garments.dynamicappearance-tag-required",
+    "cp2077.clothing.garments.dynamic-appearance-placeholders",
+];
+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 visualTags(rootChunk) {
+    const schema = rootChunk.visualTagsSchema;
+    if (!isJsonObject(schema))
+        return [];
+    const data = isJsonObject(schema.Data) ? schema.Data : schema;
+    const tagsList = isJsonObject(data) && isJsonObject(data.visualTags) ? data.visualTags.tags : undefined;
+    if (!Array.isArray(tagsList))
+        return [];
+    return tagsList.map((t) => cnameValue(t)).filter((t) => t !== undefined);
+}
+function findBlankAppearanceEntry(rootChunk) {
+    const apps = rootChunk.appearances;
+    if (!Array.isArray(apps) || apps.length !== 1)
+        return undefined;
+    const entry = apps[0];
+    if (!isJsonObject(entry))
+        return undefined;
+    return cnameValue(entry.appearanceName) === "" ? entry : undefined;
+}
+function hasSubstitutionComponents(rootChunk) {
+    return collectResourcePaths(rootChunk).some(({ path: p }) => p.includes("{"));
+}
+async function siblingEntFiles(ctx, file) {
+    const dir = path.dirname(file);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const others = entries.filter((e) => isEntJson(e) && path.join(dir, e) !== file).map((e) => path.join(dir, e));
+    others.sort((a, b) => Number(!/root/i.test(path.basename(b))) - Number(!/root/i.test(path.basename(a))));
+    return others;
+}
+export const GARMENT_ROOT_ENTITY_BLANK_APPEARANCE = {
+    id: "cp2077.garments.root-entity-blank-appearance",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "A dynamic appearance's root .ent has exactly one appearance entry with a blank appearanceName, and its .app has one entry with components deleted.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && isEntJson(f);
+    },
+    appliesToDescription: "every .ent.json file that carries the DynamicAppearance tag",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ROOT_BLANK_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const rootChunk = entRootChunk(parsed.root);
+        if (!rootChunk)
+            return [];
+        if (!visualTags(rootChunk).includes("DynamicAppearance"))
+            return [];
+        const findings = [];
+        const apps = Array.isArray(rootChunk.appearances) ? rootChunk.appearances : [];
+        if (apps.length !== 1) {
+            findings.push({
+                validatorId: this.id,
+                severity: "block",
+                file,
+                message: `This root entity carries DynamicAppearance but its appearances array has ${apps.length} entries, not exactly one.`,
+                fix: "A dynamic-appearance root entity keeps exactly one appearances[] entry, with all variant logic in the mesh entity file instead.",
+                evidence: ROOT_BLANK_EVIDENCE,
+            });
+        }
+        else {
+            const entry = apps[0];
+            const appearanceName = isJsonObject(entry) ? cnameValue(entry.appearanceName) : undefined;
+            if (appearanceName !== "") {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `The root entity's single appearance entry has appearanceName "${appearanceName ?? "?"}", not blank.`,
+                    fix: 'Set appearanceName to "" on the root entity\'s appearance entry; variant selection happens in the .app/mesh entity, not here.',
+                    evidence: ROOT_BLANK_EVIDENCE,
+                });
+            }
+            const appPath = isJsonObject(entry) ? resourcePathValue(entry.appearanceResource) : undefined;
+            const root = stagingRoot(ctx.project);
+            if (appPath && root) {
+                const abs = resolveDepotPath(root, appPath);
+                const appJson = await readStagedCr2wJson(ctx, abs);
+                if (appJson) {
+                    const appAppearances = collectKey(appJson.root, "appearances").flatMap((h) => (Array.isArray(h.value) ? h.value : []));
+                    if (appAppearances.length !== 1) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file: appJson.absPath,
+                            related: [file],
+                            message: `${path.basename(appJson.absPath)} has ${appAppearances.length} appearance entries; a dynamic appearance's .app keeps exactly one.`,
+                            fix: "Reduce the .app to one appearance entry matching the root entity's appearance name.",
+                            evidence: ROOT_BLANK_EVIDENCE,
+                        });
+                    }
+                    else {
+                        const def = appAppearances[0];
+                        const data = isJsonObject(def) && isJsonObject(def.Data) ? def.Data : def;
+                        const components = isJsonObject(data) ? data.components : undefined;
+                        if (Array.isArray(components) && components.length > 0) {
+                            findings.push({
+                                validatorId: this.id,
+                                severity: "block",
+                                file: appJson.absPath,
+                                related: [file],
+                                message: `${path.basename(appJson.absPath)}'s single appearance still has ${components.length} component(s); a dynamic appearance's .app has them deleted — all components live in the mesh entity file instead.`,
+                                fix: "Delete the components array entries from this .app's appearance definition.",
+                                evidence: ROOT_BLANK_EVIDENCE,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+export const GARMENT_DYNAMICAPPEARANCE_TAG_PRESENT = {
+    id: "cp2077.garments.dynamicappearance-tag-present",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "An entity whose mesh-entity component paths use {…} carries the DynamicAppearance visual tag on its root entity.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && isEntJson(f);
+    },
+    appliesToDescription: "every .ent.json file with at least one {…}-substituted component depotPath",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: DYNAMIC_TAG_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        const parsed = await readCr2wJson(ctx, file);
+        if (!parsed)
+            return [];
+        const rootChunk = entRootChunk(parsed.root);
+        if (!rootChunk || !hasSubstitutionComponents(rootChunk))
+            return [];
+        for (const sibling of await siblingEntFiles(ctx, file)) {
+            const siblingParsed = await readCr2wJson(ctx, sibling);
+            if (!siblingParsed)
+                continue;
+            const siblingChunk = entRootChunk(siblingParsed.root);
+            const looksLikeRoot = siblingChunk && (findBlankAppearanceEntry(siblingChunk) !== undefined || /root/i.test(path.basename(sibling)));
+            if (!siblingChunk || !looksLikeRoot)
+                continue;
+            if (visualTags(siblingChunk).includes("DynamicAppearance"))
+                return [];
+            return [
+                {
+                    validatorId: "cp2077.garments.dynamicappearance-tag-present",
+                    severity: "block",
+                    file: sibling,
+                    related: [file],
+                    message: `${path.basename(file)} substitutes {…} placeholders in a component depotPath, but its paired root entity ` +
+                        `${path.basename(sibling)} does not carry the DynamicAppearance visual tag.`,
+                    fix: "Add DynamicAppearance to the root entity's visualTagsSchema.Data.visualTags.tags.",
+                    evidence: DYNAMIC_TAG_EVIDENCE,
+                },
+            ];
+        }
+        return [];
+    },
+};
+const GENDER_SUFFIX_EVIDENCE = [
+    "cp2077.clothing.garments.gendered-appearance-name-suffix",
+    "cp2077.clothing.garments.unvalidated-variant-crashes",
+];
+export const GARMENT_GENDERED_APPEARANCE_SUFFIX = {
+    id: "cp2077.garments.gendered-appearance-suffix",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "When only one gender's meshes are staged, every .app appearance name carries &gender=w or &gender=m.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, when a {gender}-substituted component is staged for only one gender",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: GENDER_SUFFIX_EVIDENCE,
+    async run(ctx) {
+        const root = stagingRoot(ctx.project);
+        if (!root)
+            return [];
+        const manifests = await xlManifests(ctx);
+        const values = { ...ENUMERABLE_VALUES, body: bodyValueSet(manifests) };
+        const entFiles = await allFilesUnder(ctx.project, isEntJson);
+        const findings = [];
+        const checkedDirs = new Set();
+        for (const file of entFiles) {
+            const parsed = await readCr2wJson(ctx, file);
+            if (!parsed)
+                continue;
+            const genderPaths = collectResourcePaths(parsed.root).filter(({ path: p }) => p.startsWith("*") && placeholdersIn(p).includes("gender"));
+            if (genderPaths.length === 0)
+                continue;
+            const stagedGenders = new Set();
+            for (const { path: p } of genderPaths) {
+                const tokens = [...new Set(placeholdersIn(p))].filter((t) => t in values);
+                if (tokens.length === 0)
+                    continue;
+                const domains = tokens.map((t) => values[t]);
+                let combos = [[]];
+                for (const domain of domains)
+                    combos = combos.flatMap((prefix) => domain.map((v) => [...prefix, v]));
+                for (const combo of combos) {
+                    let resolved = p;
+                    tokens.forEach((t, i) => (resolved = resolved.split(`{${t}}`).join(combo[i])));
+                    if (await ctx.exists(resolveDepotPath(root, resolved))) {
+                        stagedGenders.add(combo[tokens.indexOf("gender")]);
+                    }
+                }
+            }
+            if (stagedGenders.size !== 1)
+                continue;
+            const [onlyGender] = [...stagedGenders];
+            const dir = path.dirname(file);
+            if (checkedDirs.has(dir))
+                continue;
+            checkedDirs.add(dir);
+            let entries;
+            try {
+                entries = await fs.readdir(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries.filter(isAppJson)) {
+                const appFile = path.join(dir, entry);
+                const appJson = await readCr2wJson(ctx, appFile);
+                if (!appJson)
+                    continue;
+                for (const hit of collectKey(appJson.root, "name")) {
+                    const name = cnameValue(hit.value);
+                    if (!name)
+                        continue;
+                    if (!name.includes(`&gender=${onlyGender}`)) {
+                        findings.push({
+                            validatorId: this.id,
+                            severity: "block",
+                            file: appFile,
+                            related: [file],
+                            message: `Only the "${onlyGender}" gender's meshes are staged for the component(s) in ${path.basename(file)}, ` +
+                                `but appearance name "${name}" at ${hit.jsonPath} does not carry "&gender=${onlyGender}". ` +
+                                "The game crashes if the item is equipped by the unsupported body gender.",
+                            fix: `Append "&gender=${onlyGender}" to this appearance's name.`,
+                            evidence: GENDER_SUFFIX_EVIDENCE,
+                        });
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+const XL_ENTRIES_EVIDENCE = [
+    "cp2077.archivexl.manifest-top-level-keys",
+    "cp2077.archivexl.factories-csv-paths",
+    "cp2077.archivexl.streaming-blocks-path",
+    "cp2077.world.loot-container.three-artifacts-must-deploy-together",
+];
+async function stagingLooksPartial(project) {
+    const root = stagingRoot(project);
+    if (!root)
+        return true;
+    const walked = await walk(root, { limit: 1000 });
+    const payload = walked.files.filter((f) => !isXlManifest(f));
+    return payload.length === 0;
+}
+function collectManifestPaths(manifest) {
+    const out = [];
+    const localization = manifest.localization;
+    if (isJsonObject(localization) && isJsonObject(localization.onscreens)) {
+        for (const [lang, value] of Object.entries(localization.onscreens)) {
+            if (typeof value === "string")
+                out.push({ label: `localization.onscreens.${lang}`, value });
+        }
+    }
+    if (Array.isArray(manifest.factories)) {
+        manifest.factories.forEach((v, i) => {
+            if (typeof v === "string")
+                out.push({ label: `factories[${i}]`, value: v });
+        });
+    }
+    const streaming = manifest.streaming;
+    if (isJsonObject(streaming) && Array.isArray(streaming.blocks)) {
+        streaming.blocks.forEach((v, i) => {
+            if (typeof v === "string")
+                out.push({ label: `streaming.blocks[${i}]`, value: v });
+        });
+    }
+    if (Array.isArray(manifest.animations)) {
+        manifest.animations.forEach((entry, i) => {
+            if (!isJsonObject(entry))
+                return;
+            if (typeof entry.set === "string")
+                out.push({ label: `animations[${i}].set`, value: entry.set });
+            if (typeof entry.entity === "string")
+                out.push({ label: `animations[${i}].entity`, value: entry.entity });
+            if (Array.isArray(entry.entity)) {
+                entry.entity.forEach((v, j) => {
+                    if (typeof v === "string")
+                        out.push({ label: `animations[${i}].entity[${j}]`, value: v });
+                });
+            }
+        });
+    }
+    const resource = manifest.resource;
+    if (isJsonObject(resource) && isJsonObject(resource.patch)) {
+        for (const key of Object.keys(resource.patch))
+            out.push({ label: `resource.patch["${key}"]`, value: key });
+    }
+    return out;
+}
+export const GARMENT_XL_ENTRIES_RESOLVE = {
+    id: "cp2077.garments.xl-entries-resolve",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit", "outfit-slot"],
+    summary: "Every path an .xl manifest declares resolves to a file staged under the archive-staging source or the vanilla archive index.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over every .archive.xl manifest in the project",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: XL_ENTRIES_EVIDENCE,
+    async run(ctx) {
+        const manifests = await xlManifests(ctx);
+        if (manifests.length === 0)
+            return [];
+        if (await stagingLooksPartial(ctx.project)) {
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "info",
+                    file: manifests[0].file,
+                    message: "The project's archive-staging source is missing or stages nothing beyond the manifest itself; " +
+                        "cp2077.garments.xl-entries-resolve cannot tell a genuinely missing entry from a fixture/partial tree and was not run. " +
+                        "Run this against the built archive-staging output.",
+                    evidence: XL_ENTRIES_EVIDENCE,
+                },
+            ];
+        }
+        const root = stagingRoot(ctx.project);
+        const findings = [];
+        for (const { file, manifest } of manifests) {
+            for (const { label, value } of collectManifestPaths(manifest)) {
+                const abs = resolveDepotPath(root, value);
+                if (!(await existsStagedOrVanilla(ctx, abs, value))) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file,
+                        message: `${label} = "${value}" does not resolve under the staged archive tree (expected at ${abs}) or the vanilla archive index.`,
+                        fix: `Stage the file at "${value}", or fix the path in ${path.basename(file)}.`,
+                        evidence: XL_ENTRIES_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const FACTORY_CSV_EVIDENCE = [
+    "cp2077.archivexl.factory-csv-appearance-mapping",
+    "cp2077.entities.entity-appearance-factory-resolution",
+    "cp2077.tweakdb.weapon-visuals-via-appearanceresourcename",
+];
+function parseCsvRows(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length === 0)
+        return [];
+    const header = lines[0].split(",").map((h) => h.trim());
+    return lines.slice(1).map((line) => {
+        const cells = line.split(",");
+        const row = {};
+        header.forEach((h, i) => (row[h] = (cells[i] ?? "").trim()));
+        return row;
+    });
+}
+async function appearanceResourceNames(ctx) {
+    const files = await allFilesUnder(ctx.project, isYamlFile);
+    const out = [];
+    for (const file of files) {
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch {
+            continue;
+        }
+        let records;
+        try {
+            records = parseTweakXLYaml(text, file);
+        }
+        catch {
+            continue;
+        }
+        for (const rec of records) {
+            const flat = rec.flats.find((f) => f.name === "appearanceResourceName");
+            if (flat && typeof flat.value === "string")
+                out.push({ name: flat.value, file });
+        }
+    }
+    return out;
+}
+export const GARMENT_FACTORY_CSV_ROWS = {
+    id: "cp2077.garments.factory-csv-rows",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "refit"],
+    summary: "Every appearance name a TweakXL item record names has a row in a registered factory CSV, that row's path is staged or resolves in the vanilla archive index, and a row no record names is reported.",
+    appliesTo: (t) => t.kind === "project",
+    appliesToDescription: "once per validation, over appearanceResourceName values against the .xl's registered factory CSVs",
+    needs: { project: true, toolchain: ["wolvenkit-cli"] },
+    cost: "build",
+    severity: "block",
+    evidence: FACTORY_CSV_EVIDENCE,
+    async run(ctx) {
+        const names = await appearanceResourceNames(ctx);
+        if (names.length === 0)
+            return [];
+        const root = stagingRoot(ctx.project);
+        const manifests = await xlManifests(ctx);
+        const csvPaths = manifests.flatMap(({ manifest }) => (Array.isArray(manifest.factories) ? manifest.factories.filter((f) => typeof f === "string") : []));
+        if (csvPaths.length === 0 || !root)
+            return [];
+        const findings = [];
+        const rows = [];
+        let anyCsvReadable = false;
+        for (const csvPath of csvPaths) {
+            const abs = resolveDepotPath(root, csvPath);
+            let text;
+            try {
+                text = await ctx.readText(abs);
+            }
+            catch {
+                text = undefined;
+            }
+            if (text !== undefined && /^\s*name\s*,\s*path/i.test(text)) {
+                rows.push(...parseCsvRows(text).map((cells) => ({ csv: abs, cells })));
+                anyCsvReadable = true;
+                continue;
+            }
+            const jsonSidecar = `${abs}.json`;
+            let jsonText;
+            try {
+                jsonText = await ctx.readText(jsonSidecar);
+            }
+            catch {
+                jsonText = undefined;
+            }
+            if (jsonText !== undefined) {
+                anyCsvReadable = true;
+                continue;
+            }
+            if (await ctx.exists(abs)) {
+                const wolvenkitSpec = TOOL_SPECS.find((s) => s.id === "wolvenkit-cli");
+                const wolvenkit = wolvenkitSpec ? await locateTool(wolvenkitSpec) : undefined;
+                if (!wolvenkit || !wolvenkit.found) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "info",
+                        file: abs,
+                        message: `${csvPath} is a compiled CR2W factory CSV with no text or .json intermediate on disk, and wolvenkit-cli was not located to serialize it; cp2077.garments.factory-csv-rows was not run for this CSV.`,
+                        evidence: FACTORY_CSV_EVIDENCE,
+                    });
+                    continue;
+                }
+                const result = await runTool(wolvenkit, {
+                    args: ["convert", "serialize", "-p", abs],
+                    timeoutMs: 60_000,
+                });
+                if (!result.ok) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "info",
+                        file: abs,
+                        message: `wolvenkit-cli convert serialize failed on ${csvPath} (${result.error?.message ?? "unknown error"}); cp2077.garments.factory-csv-rows was not run for this CSV.`,
+                        evidence: FACTORY_CSV_EVIDENCE,
+                    });
+                }
+                continue;
+            }
+        }
+        if (!anyCsvReadable) {
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "info",
+                    file: manifests[0].file,
+                    message: "None of this project's registered factory CSVs could be read as text or json (fixture/partial tree, or a compiled " +
+                        "binary this check cannot parse); cp2077.garments.factory-csv-rows was not run.",
+                    evidence: FACTORY_CSV_EVIDENCE,
+                },
+            ];
+        }
+        for (const { name, file } of names) {
+            const row = rows.find((r) => r.cells.name === name)?.cells;
+            if (!row) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `appearanceResourceName "${name}" has no row in any registered factory CSV.`,
+                    fix: `Add a row for "${name}" to the factory CSV registered in this project's .xl.`,
+                    evidence: FACTORY_CSV_EVIDENCE,
+                });
+                continue;
+            }
+            const rowPath = row.path;
+            if (!rowPath)
+                continue;
+            const abs = resolveDepotPath(root, rowPath);
+            if (!(await existsStagedOrVanilla(ctx, abs, rowPath))) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `Factory row "${name}" points at "${rowPath}", which is not staged (expected at ${abs}) or in the vanilla archive index.`,
+                    fix: `Stage the .app/.ent at "${rowPath}", or fix the factory row's path.`,
+                    evidence: FACTORY_CSV_EVIDENCE,
+                });
+            }
+        }
+        const named = new Set(names.map((n) => n.name));
+        for (const { csv, cells } of rows) {
+            if (!cells.name || named.has(cells.name))
+                continue;
+            findings.push({
+                validatorId: this.id,
+                severity: "info",
+                file: csv,
+                message: `Factory row "${cells.name}" is named by no TweakXL record's appearanceResourceName in this project's yaml, so nothing here uses it and its path ("${cells.path ?? ""}") is not checked.`,
+                fix: `Set appearanceResourceName: ${cells.name} on the record that should use it, or remove the row.`,
+                evidence: FACTORY_CSV_EVIDENCE,
+            });
+        }
+        return findings;
+    },
+};
+const EQUIPMENTEX_EVIDENCE = [
+    "cp2077.equipment-ex.slots.torso-layer-names",
+    "cp2077.equipment-ex.slots.legs-and-body-layer-names",
+    "cp2077.equipment-ex.slots.paired-left-right-naming",
+    "cp2077.equipment-ex.slots.placementslots-append-syntax",
+    "cp2077.equipment-ex.slots.auto-conversion-table",
+];
+export const GARMENT_EQUIPMENTEX_SLOT_KNOWN = {
+    id: "cp2077.garments.equipmentex-slot-known",
+    game: "cyberpunk2077",
+    groups: ["garments"],
+    modTypes: ["garment", "outfit-slot"],
+    summary: "placementSlots entries naming OutfitSlots.* are known Equipment-EX slot ids.",
+    appliesTo: (t) => {
+        const f = fileTarget(t);
+        return f !== undefined && isYamlFile(f);
+    },
+    appliesToDescription: "every .yaml/.yml file",
+    needs: {},
+    cost: "edit",
+    severity: "warn",
+    evidence: EQUIPMENTEX_EVIDENCE,
+    async run(ctx) {
+        const file = fileTarget(ctx.target);
+        if (!file)
+            return [];
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch {
+            return [];
+        }
+        let records;
+        try {
+            records = parseTweakXLYaml(text, file);
+        }
+        catch {
+            return [];
+        }
+        const findings = [];
+        for (const rec of records) {
+            const flat = rec.flats.find((f) => f.name === "placementSlots");
+            if (!flat || !Array.isArray(flat.value))
+                continue;
+            for (const v of flat.value) {
+                if (typeof v !== "string" || !v.startsWith("OutfitSlots."))
+                    continue;
+                const slot = v.slice("OutfitSlots.".length);
+                if (KNOWN_OUTFIT_SLOTS.has(slot))
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file,
+                    line: rec.line,
+                    message: `${rec.name}'s placementSlots names "${v}", which is not a documented Equipment-EX outfit slot id.`,
+                    fix: `Check the slot name against Equipment-EX's outfit-slot table (e.g. "OutfitSlots.TorsoMiddle", not "${v}").`,
+                    evidence: EQUIPMENTEX_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const GARMENT_VALIDATORS = [
+    GARMENT_STAR_PREFIX,
+    GARMENT_PLACEHOLDER_KNOWN,
+    GARMENT_COMBINATION_RESOLVES,
+    GARMENT_BODY_TAG_REGISTRATION,
+    GARMENT_VISUAL_TAGS_RESOLVE,
+    GARMENT_ROOT_ENTITY_BLANK_APPEARANCE,
+    GARMENT_DYNAMICAPPEARANCE_TAG_PRESENT,
+    GARMENT_GENDERED_APPEARANCE_SUFFIX,
+    GARMENT_XL_ENTRIES_RESOLVE,
+    GARMENT_FACTORY_CSV_ROWS,
+    GARMENT_EQUIPMENTEX_SLOT_KNOWN,
+];