modwright 0.1.0

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

@@ -0,0 +1,768 @@
+import * as path from "node:path";
+import * as YAML from "yaml";
+import { walk } from "../../../core/fsutil.js";
+import { parseTweakXLYaml } from "../index/parsers/tweakxl-yaml.js";
+const GAME = "cyberpunk2077";
+const GROUPS = ["tweaks"];
+const MOD_TYPES = ["gameplay-tweak", "weapon", "item", "loot"];
+function isYamlPath(p) {
+    return /\.ya?ml$/i.test(p);
+}
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isUnderTweaksSource(absPath, project) {
+    return project.sources.some((s) => s.kind === "tweaks" && s.exists && isWithin(s.absPath, absPath));
+}
+const APPLIES_DESC = 'every .yaml/.yml file under a source of kind "tweaks"';
+function appliesToYaml(target, project) {
+    return target.kind === "file" && isYamlPath(target.path) && isUnderTweaksSource(target.path, project);
+}
+async function findRecordsInFile(ctx, file) {
+    let text;
+    try {
+        text = await ctx.readText(file);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return parseTweakXLYaml(text, file);
+    }
+    catch {
+        return undefined;
+    }
+}
+const projectTweakDataCache = new WeakMap();
+async function collectTweaksSourceFiles(project) {
+    const files = [];
+    for (const source of project.sources) {
+        if (source.kind !== "tweaks" || !source.exists)
+            continue;
+        if (isYamlPath(source.absPath)) {
+            files.push(source.absPath);
+            continue;
+        }
+        const walked = await walk(source.absPath, { limit: 20_000 });
+        for (const rel of walked.files) {
+            if (isYamlPath(rel))
+                files.push(path.join(source.absPath, rel));
+        }
+    }
+    files.sort((a, b) => {
+        const an = path.basename(a);
+        const bn = path.basename(b);
+        return an < bn ? -1 : an > bn ? 1 : 0;
+    });
+    return files;
+}
+function getProjectTweakData(ctx) {
+    const cached = projectTweakDataCache.get(ctx.project);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        const files = await collectTweaksSourceFiles(ctx.project);
+        const namesDefined = new Set();
+        const allRecords = [];
+        for (const file of files) {
+            const records = await findRecordsInFile(ctx, file);
+            if (!records)
+                continue;
+            for (const r of records) {
+                namesDefined.add(r.name);
+                allRecords.push(r);
+            }
+        }
+        return { files, namesDefined, allRecords };
+    })();
+    projectTweakDataCache.set(ctx.project, promise);
+    return promise;
+}
+function finding(validatorId, severity, file, message, evidence, extra = {}) {
+    return { validatorId, severity, file, message, evidence, ...extra };
+}
+const YAML_LINT_ID = "cp2077.tweaks.yaml-lint";
+const YAML_LINT_EVIDENCE = [
+    "cp2077.tweakdb.melee.tweakxl-log-required-after-yaml-changes",
+];
+export const yamlLintValidator = {
+    id: YAML_LINT_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every .yaml under a tweaks source parses as YAML: no tab indentation, no duplicate mapping keys.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: YAML_LINT_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch (err) {
+            return [finding(YAML_LINT_ID, "block", file, `Could not read this file: ${err.message}`, YAML_LINT_EVIDENCE)];
+        }
+        const lineCounter = new YAML.LineCounter();
+        const doc = YAML.parseDocument(text, { lineCounter });
+        return doc.errors.map((err) => {
+            const pos = err.pos ? lineCounter.linePos(err.pos[0]) : undefined;
+            return finding(YAML_LINT_ID, "block", file, err.message.split("\n")[0] ?? err.message, YAML_LINT_EVIDENCE, {
+                line: pos?.line,
+                column: pos?.col,
+            });
+        });
+    },
+};
+const BASE_EXISTS_ID = "cp2077.tweaks.base-exists";
+const BASE_EXISTS_EVIDENCE = [
+    "cp2077.process.tweakdb-ground-truth",
+    "cp2077.tweakdb.melee.attack-records-live-in-per-family-packages",
+];
+export const baseExistsValidator = {
+    id: BASE_EXISTS_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every $base: value resolves to a record in the vanilla index or one this project's own tweak files define.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: BASE_EXISTS_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { namesDefined } = await getProjectTweakData(ctx);
+        const modDeps = (ctx.project.project.dependencies ?? []).filter((d) => d.kind === "mod");
+        const out = [];
+        for (const rec of records) {
+            if (!rec.base || namesDefined.has(rec.base))
+                continue;
+            const res = await ctx.lookup("record", { name: rec.base });
+            if (res.count > 0)
+                continue;
+            if (modDeps.length > 0) {
+                out.push(finding(BASE_EXISTS_ID, "warn", file, `$base: ${rec.base} (used by ${rec.name}) does not resolve in the vanilla index or this project's own tweak files. It may be defined by a declared mod dependency (${modDeps.map((d) => d.id).join(", ")}) — if not, this is a typo and TweakXL drops the whole record silently, logging only to TweakXL-<timestamp>.log.`, BASE_EXISTS_EVIDENCE, { line: rec.line }));
+            }
+            else {
+                out.push(finding(BASE_EXISTS_ID, "block", file, `$base: ${rec.base} (used by ${rec.name}) does not exist in the vanilla index or in this project's own tweak files. TweakXL drops the whole record and logs only to TweakXL-<timestamp>.log.`, BASE_EXISTS_EVIDENCE, { line: rec.line }));
+            }
+        }
+        return out;
+    },
+};
+const TYPE_KNOWN_ID = "cp2077.tweaks.type-known";
+const TYPE_KNOWN_EVIDENCE = ["ModWright research"];
+export const typeKnownValidator = {
+    id: TYPE_KNOWN_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every $type: value names a type attested in the vanilla corpus, as a record $type or an inline-struct $type.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: TYPE_KNOWN_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const out = [];
+        for (const rec of records) {
+            if (!rec.type)
+                continue;
+            const res = await ctx.lookup("type", { type: rec.type });
+            if (res.count > 0)
+                continue;
+            out.push(finding(TYPE_KNOWN_ID, "block", file, `$type: ${rec.type} (on ${rec.name}) is not attested anywhere in the vanilla corpus, as a record $type or an inline-struct $type.`, TYPE_KNOWN_EVIDENCE, { line: rec.line }));
+        }
+        return out;
+    },
+};
+const APPEND_LIST_ID = "cp2077.tweaks.append-on-list-flat";
+const APPEND_LIST_EVIDENCE = [
+    "cp2077.equipment-ex.slots.placementslots-append-syntax",
+    "cp2077.tweakdb.melee.iconic-quality-pattern-confirmed-across-mods",
+    "cp2077.loot.debug-recipe-list-registration",
+];
+async function chainFlatKind(ctx, baseName, flatName) {
+    const res = await ctx.lookup("chain", { name: baseName });
+    const row = res.rows[0];
+    return row?.flats?.find((f) => f.name === flatName)?.kind;
+}
+function isListKind(kind) {
+    return kind === "array" || kind.endsWith("[]");
+}
+export const appendOnListFlatValidator = {
+    id: APPEND_LIST_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "!append / !append-once / !remove are used only on a flat whose effective type on the $base chain is an array.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: APPEND_LIST_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { allRecords } = await getProjectTweakData(ctx);
+        const out = [];
+        for (const rec of records) {
+            for (const flat of rec.flats) {
+                if (flat.op === "set")
+                    continue;
+                const knownKind = rec.base ? await chainFlatKind(ctx, rec.base, flat.name) : undefined;
+                if (knownKind !== undefined) {
+                    if (!isListKind(knownKind)) {
+                        out.push(finding(APPEND_LIST_ID, "block", file, `"${flat.name}" is tagged !${flat.op} on ${rec.name}, but on its $base chain this flat is a ${knownKind}, not a list. TweakXL's append/remove tags only make sense on an array flat.`, APPEND_LIST_EVIDENCE, { line: rec.line }));
+                    }
+                    continue;
+                }
+                const declaredArrayElsewhere = allRecords.some((r) => r !== rec && r.flats.some((f) => f.name === flat.name && f.op === "set" && f.kind === "array"));
+                if (!declaredArrayElsewhere) {
+                    out.push(finding(APPEND_LIST_ID, "info", file, `Cannot tell whether "${flat.name}" (on ${rec.name}) is a list flat: its $base chain (${rec.base ?? "none — this record has no $base"}) is not in the vanilla index, and no plain array declaration of this flat exists elsewhere in this project.`, APPEND_LIST_EVIDENCE, { line: rec.line }));
+                }
+            }
+        }
+        return out;
+    },
+};
+const INSTANCES_ID = "cp2077.tweaks.instances-resolve";
+const INSTANCES_EVIDENCE = ["ModWright research"];
+const VAR_RE = /\$\(([^)]+)\)/g;
+function collectVarNamesFromText(text, out) {
+    for (const m of text.matchAll(VAR_RE))
+        out.add(m[1]);
+}
+function collectVarNamesFromNode(node, out) {
+    if (YAML.isScalar(node)) {
+        if (typeof node.value === "string")
+            collectVarNamesFromText(node.value, out);
+    }
+    else if (YAML.isSeq(node)) {
+        for (const item of node.items)
+            collectVarNamesFromNode(item, out);
+    }
+    else if (YAML.isMap(node)) {
+        for (const pair of node.items)
+            collectVarNamesFromNode(pair.value, out);
+    }
+}
+function substituteTemplateText(text, bindings) {
+    return text.replace(VAR_RE, (whole, name) => (name in bindings ? bindings[name] : whole));
+}
+export const instancesResolveValidator = {
+    id: INSTANCES_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every $(var) in an $instances template is bound by every instance entry, and the expansion produces distinct record names.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: {},
+    cost: "edit",
+    severity: "block",
+    evidence: INSTANCES_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch {
+            return [];
+        }
+        const doc = YAML.parseDocument(text);
+        if (doc.errors.length > 0)
+            return [];
+        const root = doc.contents;
+        if (!root || !YAML.isMap(root))
+            return [];
+        const out = [];
+        for (const pair of root.items) {
+            if (!YAML.isScalar(pair.key) || !YAML.isMap(pair.value))
+                continue;
+            const rawName = String(pair.key.value);
+            const instancesPair = pair.value.items.find((p) => YAML.isScalar(p.key) && String(p.key.value) === "$instances");
+            if (!instancesPair || !YAML.isSeq(instancesPair.value))
+                continue;
+            const bindingsList = [];
+            let malformed = false;
+            for (const entry of instancesPair.value.items) {
+                if (!YAML.isMap(entry)) {
+                    malformed = true;
+                    continue;
+                }
+                const bindings = {};
+                for (const p of entry.items) {
+                    if (!YAML.isScalar(p.key))
+                        continue;
+                    const key = String(p.key.value);
+                    bindings[key] = YAML.isScalar(p.value) && p.value.value !== null ? String(p.value.value) : "";
+                }
+                bindingsList.push(bindings);
+            }
+            if (malformed || bindingsList.length === 0)
+                continue;
+            const varNames = new Set();
+            collectVarNamesFromText(rawName, varNames);
+            for (const bodyPair of pair.value.items) {
+                if (YAML.isScalar(bodyPair.key) && String(bodyPair.key.value) === "$instances")
+                    continue;
+                collectVarNamesFromNode(bodyPair.value, varNames);
+            }
+            for (const v of varNames) {
+                const missingIn = bindingsList.filter((b) => !(v in b));
+                if (missingIn.length > 0) {
+                    out.push(finding(INSTANCES_ID, "block", file, `$(${v}) is used in the $instances template for "${rawName}" but ${missingIn.length} of ${bindingsList.length} instance entries do not define it — TweakXL leaves the literal "$(${v})" in the expanded name/value for those.`, INSTANCES_EVIDENCE));
+                }
+            }
+            const expandedNames = bindingsList.map((b) => substituteTemplateText(rawName, b));
+            const counts = new Map();
+            for (const name of expandedNames)
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+            for (const [name, count] of counts) {
+                if (count > 1) {
+                    out.push(finding(INSTANCES_ID, "warn", file, `The $instances expansion for "${rawName}" produces the record name "${name}" from ${count} different instance entries — TweakXL will make one overwrite the other.`, INSTANCES_EVIDENCE));
+                }
+            }
+        }
+        return out;
+    },
+};
+const FLAT_NAME_EXISTS_ID = "cp2077.tweaks.flat-name-exists";
+const FLAT_NAME_EXISTS_EVIDENCE = [
+    "cp2077.process.tweakdb-ground-truth",
+    "cp2077.tweakdb.melee.thermal-damage-flag-required-for-burn-application",
+];
+export const flatNameExistsValidator = {
+    id: FLAT_NAME_EXISTS_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every flat assigned on a record exists somewhere on that record's $base chain, unless the record declares its own $type.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: FLAT_NAME_EXISTS_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const out = [];
+        for (const rec of records) {
+            if (!rec.base)
+                continue;
+            const res = await ctx.lookup("chain", { name: rec.base });
+            const row = res.rows[0];
+            if (res.count === 0 || !row?.flats)
+                continue;
+            const chainFlatNames = new Set(row.flats.map((f) => f.name));
+            for (const flat of rec.flats) {
+                if (chainFlatNames.has(flat.name))
+                    continue;
+                const attested = await ctx.lookup("flat", { name: flat.name });
+                const attestedElsewhere = attested.rows.some((r) => r.record !== rec.name);
+                if (attestedElsewhere)
+                    continue;
+                out.push(finding(FLAT_NAME_EXISTS_ID, "warn", file, `Flat "${flat.name}" (on ${rec.name}) is not declared anywhere on the $base chain of ${rec.base}, nor attested on any other vanilla record. TweakXL creates the flat rather than rejecting the file, so a typo of an existing flat name is silent.`, FLAT_NAME_EXISTS_EVIDENCE, { line: rec.line }));
+            }
+        }
+        return out;
+    },
+};
+const RECORD_NAME_EXISTS_ID = "cp2077.tweaks.record-name-exists";
+const RECORD_NAME_EXISTS_EVIDENCE = [
+    "cp2077.tweakdb.melee.attack-lookup-by-state-plus-counter",
+    "cp2077.loot.player-prereq-tier-gating",
+    "cp2077.tweakdb.melee.attack-records-live-in-per-family-packages",
+];
+const DOTTED_TOKEN_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+$/;
+function collectDottedTokens(value, out) {
+    if (typeof value === "string") {
+        if (DOTTED_TOKEN_RE.test(value) && !value.startsWith("LocKey#"))
+            out.add(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectDottedTokens(item, out);
+    }
+    else if (value && typeof value === "object") {
+        for (const item of Object.values(value))
+            collectDottedTokens(item, out);
+    }
+}
+export const recordNameExistsValidator = {
+    id: RECORD_NAME_EXISTS_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Every dotted token used as a flat value resolves to a record in this project or the vanilla index, when its package is known.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: RECORD_NAME_EXISTS_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { namesDefined } = await getProjectTweakData(ctx);
+        const out = [];
+        for (const rec of records) {
+            const tokens = new Set();
+            for (const flat of rec.flats)
+                collectDottedTokens(flat.value, tokens);
+            for (const token of tokens) {
+                if (namesDefined.has(token))
+                    continue;
+                const pkg = token.slice(0, token.indexOf("."));
+                const pkgKnown = await ctx.lookup("record", { prefix: `${pkg}.`, limit: 1 });
+                if (pkgKnown.count === 0)
+                    continue;
+                const resolved = await ctx.lookup("record", { name: token });
+                if (resolved.count > 0)
+                    continue;
+                out.push(finding(RECORD_NAME_EXISTS_ID, "warn", file, `"${token}" (used on ${rec.name}) looks like a TweakDB record reference in a known package ("${pkg}") but resolves nowhere, in this project or the vanilla index.`, RECORD_NAME_EXISTS_EVIDENCE, { line: rec.line }));
+            }
+        }
+        return out;
+    },
+};
+const DOTTED_PATH_ID = "cp2077.tweaks.dotted-path-same-file";
+const DOTTED_PATH_EVIDENCE = ["cp2077.tweakdb.melee.dotted-path-mod-of-same-file-record-fails"];
+function scanFileForDottedEdits(text) {
+    const lineCounter = new YAML.LineCounter();
+    const doc = YAML.parseDocument(text, { lineCounter });
+    if (doc.errors.length > 0)
+        return undefined;
+    const definedNames = new Set();
+    const dottedEdits = [];
+    const root = doc.contents;
+    if (!root || !YAML.isMap(root))
+        return { definedNames, dottedEdits };
+    for (const pair of root.items) {
+        if (!YAML.isScalar(pair.key))
+            continue;
+        const rawName = String(pair.key.value);
+        const line = pair.key.range ? lineCounter.linePos(pair.key.range[0]).line : 1;
+        if (YAML.isMap(pair.value)) {
+            definedNames.add(rawName);
+            continue;
+        }
+        const dot = rawName.lastIndexOf(".");
+        if (dot === -1) {
+            definedNames.add(rawName);
+            continue;
+        }
+        dottedEdits.push({ owner: rawName.slice(0, dot), rawKey: rawName, line });
+    }
+    return { definedNames, dottedEdits };
+}
+export const dottedPathSameFileValidator = {
+    id: DOTTED_PATH_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A record modified via a dotted top-level path (Record.flat:) must not also be defined in the same file, and only from a file sorting after the one that defines it.",
+    appliesTo(target) {
+        return target.kind === "project";
+    },
+    appliesToDescription: 'every file under a project source of kind "tweaks", reasoned about together once per validation',
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: DOTTED_PATH_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const { files } = await getProjectTweakData(ctx);
+        const perFile = new Map();
+        for (const file of files) {
+            let text;
+            try {
+                text = await ctx.readText(file);
+            }
+            catch {
+                continue;
+            }
+            const info = scanFileForDottedEdits(text);
+            if (info)
+                perFile.set(file, info);
+        }
+        const out = [];
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const info = perFile.get(file);
+            if (!info)
+                continue;
+            for (const edit of info.dottedEdits) {
+                if (info.definedNames.has(edit.owner)) {
+                    out.push(finding(DOTTED_PATH_ID, "block", file, `"${edit.rawKey}:" edits ${edit.owner} by dotted path, but ${edit.owner} is also defined as a full record in this same file. TweakXL logs "Ambiguous definition" for exactly this shape; move this edit into a second file that sorts after this one.`, DOTTED_PATH_EVIDENCE, { line: edit.line }));
+                    continue;
+                }
+                for (let j = i + 1; j < files.length; j++) {
+                    const laterFile = files[j];
+                    if (perFile.get(laterFile)?.definedNames.has(edit.owner)) {
+                        out.push(finding(DOTTED_PATH_ID, "block", file, `"${edit.rawKey}:" edits ${edit.owner} by dotted path, but ${edit.owner} is defined in ${path.basename(laterFile)}, which sorts AFTER ${path.basename(file)}. TweakXL loads tweak files in name order, so the base record does not exist yet when this edit runs.`, DOTTED_PATH_EVIDENCE, { line: edit.line, related: [laterFile] }));
+                        break;
+                    }
+                }
+            }
+        }
+        return out;
+    },
+};
+const REPLACER_TEMPLATE_ID = "cp2077.tweaks.replacer-template-staged";
+const REPLACER_BASE = "Character.Player_Replacer_Puppet_Base";
+const REPLACER_TEMPLATE_EVIDENCE = [
+    "cp2077.player.control.replacers-are-other-player-bodies",
+    "cp2077.player.control.android-replacer-is-v-in-the-android-app",
+    "cyberpunk2077.tweakxl.missing-resource (triage pattern: `<record>.entityTemplatePath refers to a non-existent resource.`)",
+];
+async function derivesFromReplacerBase(ctx, start, projectBases) {
+    let current = start;
+    const seen = new Set();
+    for (;;) {
+        if (current === REPLACER_BASE)
+            return true;
+        const next = projectBases.get(current);
+        if (next === undefined)
+            break;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        current = next;
+    }
+    if (!ctx.store)
+        return false;
+    const res = await ctx.lookup("chain", { name: current });
+    const row = res.rows[0];
+    return Boolean(row?.chain?.some((c) => c.name === REPLACER_BASE));
+}
+export const replacerTemplateStagedValidator = {
+    id: REPLACER_TEMPLATE_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: [...MOD_TYPES, "player-replacer"],
+    summary: `A record deriving ${REPLACER_BASE} names an entityTemplatePath that ends in .ent and is staged, declared as a build step's output, or (a vanilla path) in the resource index.`,
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: REPLACER_TEMPLATE_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { allRecords } = await getProjectTweakData(ctx);
+        const projectBases = new Map();
+        for (const r of [...allRecords, ...records])
+            if (!projectBases.has(r.name) || r.base)
+                projectBases.set(r.name, r.base);
+        const stagings = ctx.project.sources.filter((s) => s.kind === "archive-staging").map((s) => s.absPath);
+        const declared = new Set();
+        for (const step of ctx.project.project.build?.steps ?? []) {
+            if (typeof step !== "object" || !("expectOutputs" in step) || !Array.isArray(step.expectOutputs))
+                continue;
+            for (const out of step.expectOutputs)
+                declared.add(path.resolve(ctx.project.root, out));
+        }
+        const out = [];
+        for (const rec of records) {
+            if (!(await derivesFromReplacerBase(ctx, rec.base ?? rec.name, projectBases)))
+                continue;
+            const flat = rec.flats.find((f) => f.name === "entityTemplatePath");
+            if (!flat || typeof flat.value !== "string" || flat.value === "")
+                continue;
+            const depotPath = flat.value.replace(/\//g, "\\");
+            const lineOpts = { line: rec.line };
+            if (!/\.ent$/i.test(depotPath)) {
+                out.push(finding(REPLACER_TEMPLATE_ID, "block", file, `${rec.name}.entityTemplatePath "${depotPath}" is not an .ent; a replacer body is an entity template.`, REPLACER_TEMPLATE_EVIDENCE, lineOpts));
+                continue;
+            }
+            if (/^(base|ep1)\\/i.test(depotPath)) {
+                if (ctx.store) {
+                    const res = await ctx.lookup("resource", { path: depotPath });
+                    if (res.count === 0) {
+                        out.push(finding(REPLACER_TEMPLATE_ID, "block", file, `${rec.name}.entityTemplatePath "${depotPath}" is not in the vanilla resource index.`, REPLACER_TEMPLATE_EVIDENCE, lineOpts));
+                    }
+                }
+                continue;
+            }
+            if (stagings.length === 0) {
+                out.push(finding(REPLACER_TEMPLATE_ID, "block", file, `${rec.name}.entityTemplatePath "${depotPath}" is a mod path, and the project declares no archive-staging source to find it under.`, REPLACER_TEMPLATE_EVIDENCE, {
+                    ...lineOpts,
+                    fix: "Declare the staged archive folder as a source of kind archive-staging in modwright.json.",
+                }));
+                continue;
+            }
+            const candidates = stagings.map((s) => path.join(s, ...depotPath.split("\\")));
+            let found = false;
+            for (const c of candidates) {
+                if (declared.has(path.resolve(c)) || (await ctx.exists(c))) {
+                    found = true;
+                    break;
+                }
+            }
+            if (found)
+                continue;
+            const abs = candidates[0];
+            out.push(finding(REPLACER_TEMPLATE_ID, "block", file, `${rec.name}.entityTemplatePath "${depotPath}" is not staged (expected at ${abs}) and no build step declares it as an output, so TweakXL would log that it refers to a non-existent resource and the body would never spawn.`, REPLACER_TEMPLATE_EVIDENCE, { ...lineOpts, fix: "Fix the path, or stage the entity there (the player-replacer scaffold's deserialize step writes it)." }));
+        }
+        return out;
+    },
+};
+const BASE_ORDER_ID = "cp2077.tweaks.base-defined-before-use";
+const BASE_ORDER_EVIDENCE = ["observed (2026-09-28): TweakXL read a folder in name order and a $base from a later file failed with \"Cannot clone ..., the record doesn't exist\"", "cp2077.tweakxl.yaml-syntax.files-read-in-name-order"];
+function loadKey(file) {
+    return path.basename(file);
+}
+export const baseDefinedBeforeUseValidator = {
+    id: BASE_ORDER_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "A $base this project defines is defined in a file TweakXL reads earlier (name order), not later.",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: BASE_ORDER_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { allRecords } = await getProjectTweakData(ctx);
+        const definedIn = new Map();
+        for (const r of allRecords) {
+            if (!definedIn.has(r.name))
+                definedIn.set(r.name, r.file);
+        }
+        const out = [];
+        for (const rec of records) {
+            if (!rec.base)
+                continue;
+            const home = definedIn.get(rec.base);
+            if (!home || path.resolve(home) === path.resolve(file))
+                continue;
+            if (loadKey(home) > loadKey(file)) {
+                out.push(finding(BASE_ORDER_ID, "block", file, `$base: ${rec.base} (used by ${rec.name}) is defined in ${loadKey(home)}, which TweakXL reads after ${loadKey(file)} (files are read in name order). TweakXL logs "Cannot clone ${rec.base}, the record doesn't exist" and drops ${rec.name}. Rename one file so the base's file sorts first, or move the record.`, BASE_ORDER_EVIDENCE, { line: rec.line }));
+            }
+        }
+        return out;
+    },
+};
+const INLINE_REF_ID = "cp2077.tweaks.inline-reference";
+const INLINE_REF_EVIDENCE = [
+    "cp2077.tweakxl.yaml-syntax.inline-record-as-base-is-bad-practice",
+    "cp2077.tweakdb.index-inline-names-can-differ-from-the-game",
+    "observed (2026-09-28): the index named a vehicle package _inline1 where the game names it _inline0",
+];
+const INLINE_NAME_RE = /^[A-Za-z_][\w]*\.[\w.]*_inline\d+$/;
+function recordNamesIn(value, out) {
+    if (typeof value === "string") {
+        if (INLINE_NAME_RE.test(value))
+            out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const v of value)
+            recordNamesIn(v, out);
+    }
+}
+export const inlineReferenceValidator = {
+    id: INLINE_REF_ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "No $base or value names a vanilla <Record>_inline<N> record (unstable names; the index's may differ from the game's).",
+    appliesTo: appliesToYaml,
+    appliesToDescription: APPLIES_DESC,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: INLINE_REF_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const records = await findRecordsInFile(ctx, file);
+        if (!records)
+            return [];
+        const { namesDefined } = await getProjectTweakData(ctx);
+        const out = [];
+        for (const rec of records) {
+            const refs = [];
+            if (rec.base && INLINE_NAME_RE.test(rec.base))
+                refs.push({ name: rec.base, where: "$base" });
+            for (const flat of rec.flats) {
+                const names = [];
+                recordNamesIn(flat.value, names);
+                for (const n of names)
+                    refs.push({ name: n, where: flat.name });
+            }
+            for (const ref of refs) {
+                if (namesDefined.has(ref.name))
+                    continue;
+                out.push(finding(INLINE_REF_ID, "warn", file, `${rec.name}: ${ref.where} names the vanilla inline record ${ref.name}. Inline names are positional and can change with a game update, and the index's may not be the game's (observed: the index's _inline1 for a vehicle package was a stat modifier in game). Verify it with a live TweakDB read, or use a named record.`, INLINE_REF_EVIDENCE, { line: rec.line }));
+            }
+        }
+        return out;
+    },
+};
+export const TWEAK_VALIDATORS = [
+    yamlLintValidator,
+    baseExistsValidator,
+    typeKnownValidator,
+    appendOnListFlatValidator,
+    instancesResolveValidator,
+    flatNameExistsValidator,
+    recordNameExistsValidator,
+    dottedPathSameFileValidator,
+    replacerTemplateStagedValidator,
+    baseDefinedBeforeUseValidator,
+    inlineReferenceValidator,
+];