modwright 0.1.0

package/dist/surfaces/baldursgate3/validators/stats.js

@@ -0,0 +1,1076 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+import { parseLoca } from "../index/parsers/loca.js";
+import { parseStats } from "../index/parsers/stats.js";
+import { attr, child, children, collectProjectLsx, collectRootTemplates } from "./items.js";
+function posix(p) {
+    return p.split(path.sep).join("/");
+}
+function lower(p) {
+    return posix(p).toLowerCase();
+}
+const STATS_PATH_RE = /\/stats\/generated\/data\/[^/]+\.txt$/;
+const isStatsFile = (p) => STATS_PATH_RE.test(p);
+const isLocaXml = (p) => p.endsWith(".xml") && p.includes("/localization/");
+function fileTarget(match) {
+    return (target) => target.kind === "file" && match(lower(target.path));
+}
+function projectTarget() {
+    return (target) => target.kind === "project";
+}
+function finding(validatorId, severity, file, message, evidence, extra) {
+    return { validatorId, severity, file, message, evidence, ...extra };
+}
+async function projectFiles(project, match) {
+    const out = [];
+    for (const src of project.sources) {
+        if (!src.exists)
+            continue;
+        const { files } = await walk(src.absPath, { limit: 20000 });
+        for (const f of files) {
+            const abs = path.join(src.absPath, f);
+            if (match(lower(abs)))
+                out.push(abs);
+        }
+    }
+    return out;
+}
+function statMapKey(type, name) {
+    return `${type.toLowerCase()}::${name.toLowerCase()}`;
+}
+async function buildProjectStatMap(ctx) {
+    const files = await projectFiles(ctx.project, isStatsFile);
+    const map = new Map();
+    for (const f of files) {
+        try {
+            const text = await ctx.readText(f);
+            for (const entry of parseStats(text, f))
+                map.set(statMapKey(entry.type, entry.name), entry);
+        }
+        catch {
+        }
+    }
+    return map;
+}
+function lookupStat(map, name, preferType) {
+    if (preferType) {
+        const preferred = map.get(statMapKey(preferType, name));
+        if (preferred)
+            return preferred;
+    }
+    const lowerName = name.toLowerCase();
+    let found;
+    for (const entry of map.values()) {
+        if (entry.name.toLowerCase() === lowerName)
+            found = entry;
+    }
+    return found;
+}
+async function vanillaStat(ctx, name) {
+    const res = await ctx.lookup("stat", { name, limit: 1 });
+    const row = res.rows[0];
+    return row;
+}
+async function resolveInChain(ctx, projectMap, startUsing, field, preferType, cap = 10) {
+    let current = startUsing;
+    const seen = new Set();
+    let depth = 0;
+    while (current && depth < cap && !seen.has(current)) {
+        seen.add(current);
+        const proj = lookupStat(projectMap, current, preferType);
+        if (proj) {
+            if (proj.fields[field])
+                return true;
+            current = proj.using;
+        }
+        else {
+            const row = await vanillaStat(ctx, current);
+            if (!row)
+                return false;
+            if (row.fields[field])
+                return true;
+            current = row.using ?? undefined;
+        }
+        depth++;
+    }
+    return false;
+}
+async function statExists(ctx, projectMap, name) {
+    if (lookupStat(projectMap, name))
+        return true;
+    const row = await vanillaStat(ctx, name);
+    return row !== undefined;
+}
+const EXPLOSION_CALL_RE = /\bCreateExplosion(?:AtPosition)?\s*\(([^)]*)\)/g;
+async function projectExplosionCallArgs(ctx) {
+    const out = [];
+    for (const src of ctx.project.sources) {
+        if (!src.exists)
+            continue;
+        if (src.kind !== "mods" && src.kind !== "scriptextender")
+            continue;
+        const { files } = await walk(src.absPath, { limit: 20000 });
+        for (const f of files) {
+            if (!f.toLowerCase().endsWith(".lua"))
+                continue;
+            try {
+                const text = await ctx.readText(path.join(src.absPath, f));
+                EXPLOSION_CALL_RE.lastIndex = 0;
+                let m;
+                while ((m = EXPLOSION_CALL_RE.exec(text)))
+                    out.push(m[1] ?? "");
+            }
+            catch {
+            }
+        }
+    }
+    return out;
+}
+function isExplosionOnlyInvoked(explosionCallArgs, spellName) {
+    return explosionCallArgs.some((args) => args.includes(spellName));
+}
+const spellanimationPresent = {
+    id: "bg3.history.spellanimation-present",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "Every SpellData entry has SpellAnimation, or a using parent that does — otherwise the spell 'casts' and never resolves.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.crash.spell-missing-spellanimation"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const spellEntries = entries.filter((e) => e.type === "SpellData");
+        if (spellEntries.length === 0)
+            return [];
+        const projectMap = await buildProjectStatMap(ctx);
+        let explosionCallArgs;
+        const findings = [];
+        for (const entry of spellEntries) {
+            if (entry.fields.SpellAnimation)
+                continue;
+            const inherited = await resolveInChain(ctx, projectMap, entry.using, "SpellAnimation", "SpellData");
+            if (inherited)
+                continue;
+            explosionCallArgs ??= await projectExplosionCallArgs(ctx);
+            if (isExplosionOnlyInvoked(explosionCallArgs, entry.name)) {
+                findings.push(finding(spellanimationPresent.id, "info", ctx.target.path, `SpellData '${entry.name}' has no SpellAnimation, but is exempted: it is invoked only via a project Osi.CreateExplosion(AtPosition)(...) Lua call, which never fires the CastTextEvent "Cast" keyframe a SpellAnimation would be for. Vanilla ships the same shape (e.g. Projectile_MAG_ChargedLightning_EnsnaringShock_Explosion) with no SpellAnimation.`, spellanimationPresent.evidence, { line: entry.line }));
+                continue;
+            }
+            findings.push(finding(spellanimationPresent.id, "block", ctx.target.path, `SpellData '${entry.name}' has no SpellAnimation, and no 'using' parent supplies one. The CastTextEvent "Cast" keyframe never fires: the spell "casts" but never resolves, with no error logged.`, spellanimationPresent.evidence, { line: entry.line, fix: `Add data "SpellAnimation" "<value>" to '${entry.name}', or give it a using parent that has one.` }));
+        }
+        return findings;
+    },
+};
+const islinkedspellcontainerLinks = {
+    id: "bg3.history.islinkedspellcontainer-links",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "SpellFlags carrying IsLinkedSpellContainer requires a non-empty ContainerSpells, or it is an instant null-deref crash.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.crash.islinkedspellcontainer-unlinked"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            const flags = (entry.fields.SpellFlags ?? "").split(";").map((s) => s.trim());
+            if (!flags.includes("IsLinkedSpellContainer"))
+                continue;
+            const container = (entry.fields.ContainerSpells ?? "").trim();
+            if (container.length > 0)
+                continue;
+            findings.push(finding(islinkedspellcontainerLinks.id, "block", ctx.target.path, `'${entry.name}' carries SpellFlags "IsLinkedSpellContainer" with no (or an empty) ContainerSpells. This is an instant null-deref crash. Use vanilla-proven flags (e.g. "HasSomaticComponent;HasVerbalComponent") instead, or populate ContainerSpells.`, islinkedspellcontainerLinks.evidence, { line: entry.line }));
+        }
+        return findings;
+    },
+};
+const boostcontextInitialEvent = {
+    id: "bg3.history.boostcontext-initial-event",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "On PassiveData, a BoostContext omitting the initial-evaluation event (OnCreate) was observed never to apply at all, with no error — unless it exactly matches an attested vanilla combination. A StatusData boost was observed in game (2026-09-08) to apply on ApplyStatus regardless of BoostContext, so that assumption is confirmed for PassiveData only; verify per entry type.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.boosts.boostcontext-evaluation-events", "observed in game (2026-09-08): a StatusData boost applied on ApplyStatus regardless of BoostContext"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            const raw = entry.fields.BoostContext;
+            if (!raw)
+                continue;
+            const events = raw.split(";").map((s) => s.trim());
+            if (events.includes("OnCreate"))
+                continue;
+            const isStatusData = entry.type === "StatusData";
+            if (isStatusData) {
+                findings.push(finding(boostcontextInitialEvent.id, "info", ctx.target.path, `'${entry.name}' (StatusData) has BoostContext "${raw}" with no OnCreate. A Boosts field on a StatusData entry was observed in game (2026-09-08) to evaluate at ApplyStatus independent of BoostContext, so the "no OnCreate -> never applies" rule — confirmed only for PassiveData — does not hold the same way here. Recorded for visibility only; verify this entry's actual in-game behavior rather than relying on this check.`, boostcontextInitialEvent.evidence, { line: entry.line }));
+                continue;
+            }
+            const census = await ctx.lookup("field", { field: "BoostContext" });
+            const attested = census.rows.some((r) => String(r.value) === raw);
+            if (attested) {
+                findings.push(finding(boostcontextInitialEvent.id, "warn", ctx.target.path, `'${entry.name}' has BoostContext "${raw}" with no OnCreate, but this exact combination is attested in vanilla (e.g. a bloodied-style buff deliberately off until damaged). If this boost should be live the moment its source exists, add OnCreate. (This entry type is ${entry.type || "unrecorded"}; the "no OnCreate" behavior below is confirmed for PassiveData, not for StatusData — verify per entry type.)`, boostcontextInitialEvent.evidence, { line: entry.line }));
+            }
+            else {
+                findings.push(finding(boostcontextInitialEvent.id, "block", ctx.target.path, `'${entry.name}' has BoostContext "${raw}" with no OnCreate and no vanilla precedent for this exact combination. On PassiveData, a BoostContext missing OnCreate was observed to never apply at all, with no error (~42 of ~46 vanilla usages include OnCreate; observed first in a test mod). It was observed not to hold for StatusData, so this warning assumes PassiveData semantics — this entry's type is ${entry.type || "unrecorded"}; verify per entry type. Add OnCreate, or omit BoostContext/BoostConditions entirely if the boost should always be live.`, boostcontextInitialEvent.evidence, { line: entry.line, fix: `Add OnCreate to BoostContext on '${entry.name}'.` }));
+            }
+        }
+        return findings;
+    },
+};
+const KNOWN_INVALID = [
+    {
+        field: "Conditions",
+        qualifier: "context.Source",
+        functor: /HasHPPercentageLessThan/,
+        types: ["PassiveData"],
+        evidence: ["bg3.boosts.context-source-invalid-hp-percent"],
+    },
+    {
+        field: "Conditions",
+        qualifier: "context.Observer",
+        types: ["PassiveData"],
+        evidence: ["bg3.boosts.context-observer-invalid-oncast-self", "bg3.stats.interrupt-observer-context"],
+    },
+];
+const KNOWN_VALID = [
+    {
+        field: "Conditions",
+        type: "InterruptData",
+        qualifiers: ["context.Source", "context.Observer", "context.Target"],
+        evidence: ["bg3.stats.interrupt-observer-context"],
+    },
+];
+const QUALIFIER_RE = /context\.(Source|Observer|Target)/g;
+const HIGH_STAKES_FIELDS = new Set(["Conditions", "BoostConditions"]);
+const contextQualifierValidity = {
+    id: "bg3.history.context-qualifier-validity",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "A context.Source/Observer/Target qualifier is valid only for the specific field + functor context it appears in.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.boosts.context-observer-invalid-oncast-self",
+        "bg3.boosts.context-source-invalid-hp-percent",
+        "bg3.boosts.context-qualifier-field-specific",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            for (const [field, value] of Object.entries(entry.fields)) {
+                QUALIFIER_RE.lastIndex = 0;
+                let m;
+                const seenQualifiers = new Set();
+                while ((m = QUALIFIER_RE.exec(value))) {
+                    const qualifier = `context.${m[1]}`;
+                    if (seenQualifiers.has(qualifier))
+                        continue;
+                    seenQualifiers.add(qualifier);
+                    if (KNOWN_VALID.some((k) => k.field === field && k.type === entry.type && k.qualifiers.includes(qualifier)))
+                        continue;
+                    const known = KNOWN_INVALID.find((k) => k.field === field &&
+                        k.qualifier === qualifier &&
+                        (!k.functor || k.functor.test(value)) &&
+                        (!k.types || k.types.includes(entry.type)));
+                    if (known) {
+                        findings.push(finding(contextQualifierValidity.id, "block", ctx.target.path, `'${entry.name}'.${field} uses ${qualifier}, which is a known-invalid qualifier in this field context: the whole condition string evaluates false and every functor gated by it silently never fires.`, [...contextQualifierValidity.evidence, ...known.evidence], { line: entry.line }));
+                        continue;
+                    }
+                    const precedent = await ctx.lookup("precedent", { field, token: qualifier });
+                    if (precedent.count === 0) {
+                        const severity = HIGH_STAKES_FIELDS.has(field) ? "block" : "warn";
+                        findings.push(finding(contextQualifierValidity.id, severity, ctx.target.path, `'${entry.name}'.${field} uses ${qualifier}, which has zero vanilla precedents in this field. A context qualifier proven valid in one field+functor context is not automatically valid in another; run a field-by-field vanilla census before relying on it.`, contextQualifierValidity.evidence, { line: entry.line }));
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+const G_HANDLE_RE = /^h[0-9a-f]{8}g[0-9a-f]{4}g[0-9a-f]{4}g[0-9a-f]{4}g[0-9a-f]{12};\d+$/i;
+const DASH_HANDLE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(;\d+)?$/i;
+const G_FORM_FIELDS = ["DisplayName", "Description"];
+const DASH_FORM_FIELDS = ["TooltipUpcastDescription", "ExtraDescription"];
+const handleFormPerField = {
+    id: "bg3.history.handle-form-per-field",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "DisplayName/Description use the h..g..;<version> handle form; TooltipUpcastDescription/ExtraDescription use the raw dashed UUID.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: {},
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.loca.display-name-format", "bg3.loca.handle-is-uuid-with-g-separators"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            for (const field of G_FORM_FIELDS) {
+                const v = entry.fields[field];
+                if (v && DASH_HANDLE_RE.test(v)) {
+                    findings.push(finding(handleFormPerField.id, "block", ctx.target.path, `'${entry.name}'.${field} = "${v}" is the raw dash-UUID form; ${field} must use the h..g..;<version> handle form instead.`, handleFormPerField.evidence, { line: entry.line, fix: `Use "h" + uuid.replace(/-/g, "g") + ";<version>" for ${field}.` }));
+                }
+            }
+            for (const field of DASH_FORM_FIELDS) {
+                const v = entry.fields[field];
+                if (v && G_HANDLE_RE.test(v)) {
+                    findings.push(finding(handleFormPerField.id, "block", ctx.target.path, `'${entry.name}'.${field} = "${v}" is the h..g..;<version> handle form; ${field} must use the raw dashed UUID instead.`, handleFormPerField.evidence, { line: entry.line }));
+                }
+            }
+        }
+        return findings;
+    },
+};
+const HANDLE_FIELDS = [...G_FORM_FIELDS, ...DASH_FORM_FIELDS];
+function toHandleKey(raw) {
+    const trimmed = raw.trim();
+    const g = /^h[0-9a-f]{8}g[0-9a-f]{4}g[0-9a-f]{4}g[0-9a-f]{4}g[0-9a-f]{12}/i.exec(trimmed);
+    if (g)
+        return g[0].toLowerCase();
+    const dash = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i.exec(trimmed);
+    if (dash)
+        return `h${dash[1].replace(/-/g, "g")}`.toLowerCase();
+    return undefined;
+}
+const handleDefinedInLoca = {
+    id: "bg3.history.handle-defined-in-loca",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "Every handle referenced from stats, or from a TranslatedString attribute in a project .lsx, resolves to a <content contentuid> in this project's Localization XML or the vanilla index.",
+    appliesTo: projectTarget(),
+    appliesToDescription: "the whole project (every Stats/Generated/Data/*.txt and every TranslatedString attribute in a project .lsx, against every Localization/**/*.xml)",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.loca.xml-location-and-format", "bg3.loca.handle-is-uuid-with-g-separators"],
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const statFiles = await projectFiles(ctx.project, isStatsFile);
+        const references = [];
+        for (const f of statFiles) {
+            let entries;
+            try {
+                entries = parseStats(await ctx.readText(f), f);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                for (const field of HANDLE_FIELDS) {
+                    const raw = entry.fields[field];
+                    if (!raw)
+                        continue;
+                    const key = toHandleKey(raw);
+                    if (key)
+                        references.push({ key, file: f, line: entry.line, field });
+                }
+            }
+        }
+        const lsx = await collectProjectLsx(ctx);
+        for (const refs of lsx.byId.values()) {
+            for (const ref of refs) {
+                for (const [attrId, attribute] of Object.entries(ref.node.attributes)) {
+                    if (attribute.type !== "TranslatedString" || !attribute.handle)
+                        continue;
+                    const key = toHandleKey(attribute.handle);
+                    if (key)
+                        references.push({ key, file: ref.file, field: `${ref.node.id}.${attrId}` });
+                }
+            }
+        }
+        if (references.length === 0)
+            return [];
+        const locaFiles = await projectFiles(ctx.project, isLocaXml);
+        const defined = new Set();
+        for (const f of locaFiles) {
+            try {
+                for (const e of parseLoca(await ctx.readText(f), f))
+                    defined.add(e.handle.replace(/;\d+$/, "").toLowerCase());
+            }
+            catch {
+            }
+        }
+        const unresolved = [];
+        for (const ref of references) {
+            if (defined.has(ref.key))
+                continue;
+            const vanilla = await ctx.lookup("handle", { handle: ref.key });
+            if (vanilla.count > 0)
+                continue;
+            unresolved.push(ref);
+        }
+        if (unresolved.length === 0)
+            return [];
+        const ratio = unresolved.length / references.length;
+        if (ratio > 0.25) {
+            return [
+                finding(handleDefinedInLoca.id, "info", ctx.project.root, `${unresolved.length} of ${references.length} localization handles referenced from this project's stats and .lsx files do not resolve in its Localization XML or the vanilla index (${Math.round(ratio * 100)}%). ` +
+                    `This ratio is high enough that ModWright suspects a partial project tree rather than that many real missing translations, so these are reported informationally rather than as blocking findings. Unresolved: ${unresolved
+                        .slice(0, 10)
+                        .map((r) => r.key)
+                        .join(", ")}${unresolved.length > 10 ? ", ..." : ""}.`, handleDefinedInLoca.evidence),
+            ];
+        }
+        return unresolved.map((ref) => finding(handleDefinedInLoca.id, "block", ref.file, `${ref.field} handle '${ref.key}' does not resolve to a <content contentuid> in this project's Localization XML or the vanilla index. The game shows "Not Found" for it.`, handleDefinedInLoca.evidence, ref.line !== undefined ? { line: ref.line } : {}));
+    },
+};
+const ENUMERATION_MARKER_RE = /^[ \t]*#[ \t]*modwright:enumeration[ \t]+(\S+)[ \t]*$/;
+async function effectiveField(projectMap, name, field, cap = 10) {
+    let current = name;
+    const seen = new Set();
+    let depth = 0;
+    while (current && depth < cap && !seen.has(current)) {
+        seen.add(current);
+        const entry = lookupStat(projectMap, current, "SpellData");
+        if (!entry)
+            return undefined;
+        if (entry.fields[field] !== undefined)
+            return entry.fields[field];
+        current = entry.using;
+        depth++;
+    }
+    return undefined;
+}
+const spellidEnumerationDrift = {
+    id: "bg3.history.spellid-enumeration-drift",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "A '# modwright:enumeration <root>'-marked hardcoded SpellId() list still matches the effective UseCosts/RitualCosts set for that spell family.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file carrying a '# modwright:enumeration <root-spell-id>' marker comment",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.spells.spellid-guard-check", "bg3.spells.spellpowerlevel-reads-1-under-free-cast"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const lines = text.replace(/\r\n/g, "\n").split("\n");
+        const markers = [];
+        lines.forEach((raw, i) => {
+            const m = ENUMERATION_MARKER_RE.exec(raw);
+            if (m)
+                markers.push({ root: m[1], line: i + 1 });
+        });
+        if (markers.length === 0)
+            return [];
+        const projectMap = await buildProjectStatMap(ctx);
+        const findings = [];
+        for (const marker of markers) {
+            let valueLine;
+            let valueLineNo = marker.line;
+            for (let i = marker.line; i < lines.length; i++) {
+                const t = (lines[i] ?? "").trim();
+                if (t.length === 0)
+                    continue;
+                valueLine = t;
+                valueLineNo = i + 1;
+                break;
+            }
+            if (!valueLine)
+                continue;
+            const dataMatch = /^data "([^"]*)" "(.*)"$/.exec(valueLine);
+            if (!dataMatch)
+                continue;
+            const enumerated = new Set();
+            const spellIdRe = /SpellId\('([^']+)'\)/g;
+            let sm;
+            while ((sm = spellIdRe.exec(dataMatch[2] ?? "")))
+                enumerated.add(sm[1]);
+            const family = [...projectMap.values()].filter((e) => e.type === "SpellData" && (e.name === marker.root || e.fields.RootSpellID === marker.root));
+            const required = new Map();
+            for (const spell of family) {
+                const useCosts = await effectiveField(projectMap, spell.name, "UseCosts");
+                const ritualCosts = await effectiveField(projectMap, spell.name, "RitualCosts");
+                if (ritualCosts)
+                    continue;
+                const levelMatch = /SpellSlotsGroup:1:1:(\d+)/.exec(useCosts ?? "");
+                if (!levelMatch)
+                    continue;
+                required.set(spell.name, Number(levelMatch[1]));
+            }
+            for (const [name, level] of required) {
+                if (!enumerated.has(name)) {
+                    findings.push(finding(spellidEnumerationDrift.id, "warn", ctx.target.path, `The '# modwright:enumeration ${marker.root}' list is missing '${name}' (effective slot level ${level}). The enumeration has drifted from the current UseCosts.`, spellidEnumerationDrift.evidence, { line: valueLineNo }));
+                }
+            }
+            for (const name of enumerated) {
+                const isFamilyMember = name === marker.root || name.startsWith(`${marker.root}_`);
+                if (isFamilyMember && !required.has(name)) {
+                    findings.push(finding(spellidEnumerationDrift.id, "warn", ctx.target.path, `The '# modwright:enumeration ${marker.root}' list references '${name}', which is no longer a slot-costed non-ritual member of this spell family — stale entry.`, spellidEnumerationDrift.evidence, { line: valueLineNo }));
+                }
+            }
+        }
+        return findings;
+    },
+};
+const TARGET_KEYWORDS = new Set([
+    "SELF", "CASTER", "OWNER", "SWAP", "OBSERVER", "TARGET", "SOURCE",
+    "OBSERVER_OBSERVER", "OBSERVER_SOURCE", "OBSERVER_TARGET",
+]);
+const STATUS_CALL_RE = /(?:ApplyStatus|RemoveStatus)\(\s*([A-Za-z0-9_]+)\s*(?:,\s*([A-Za-z0-9_]+))?/g;
+const referenceIntegrity = {
+    id: "bg3.history.reference-integrity",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "The generalization of check_spelllists.py: using parents, ApplyStatus/RemoveStatus targets and RootSpellID resolve against the mod plus the vanilla index.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.practice.reference-checker-invaluable"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const projectMap = await buildProjectStatMap(ctx);
+        const findings = [];
+        for (const entry of entries) {
+            if (entry.using && !(await statExists(ctx, projectMap, entry.using))) {
+                findings.push(finding(referenceIntegrity.id, "block", ctx.target.path, `'${entry.name}' uses parent '${entry.using}', which does not exist in this project or the vanilla index.`, referenceIntegrity.evidence, { line: entry.line }));
+            }
+            const rootSpellId = entry.fields.RootSpellID;
+            if (rootSpellId && !(await statExists(ctx, projectMap, rootSpellId))) {
+                findings.push(finding(referenceIntegrity.id, "block", ctx.target.path, `'${entry.name}'.RootSpellID '${rootSpellId}' is not a defined SpellData in this project or vanilla.`, referenceIntegrity.evidence, { line: entry.line }));
+            }
+            for (const value of Object.values(entry.fields)) {
+                STATUS_CALL_RE.lastIndex = 0;
+                let m;
+                while ((m = STATUS_CALL_RE.exec(value))) {
+                    let statusName = m[1];
+                    if (TARGET_KEYWORDS.has(statusName) && m[2])
+                        statusName = m[2];
+                    if (statusName.startsWith("SG_") || TARGET_KEYWORDS.has(statusName))
+                        continue;
+                    if (!(await statExists(ctx, projectMap, statusName))) {
+                        findings.push(finding(referenceIntegrity.id, "block", ctx.target.path, `'${entry.name}' applies/removes status '${statusName}', which is not defined anywhere in this project or the vanilla index.`, referenceIntegrity.evidence, { line: entry.line }));
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+const EQUIPMENT_PATH_RE = /\/public\/[^/]+\/stats\/generated\/equipment\.txt$/;
+const isEquipmentFile = (p) => EQUIPMENT_PATH_RE.test(p);
+const KIT_ITEM_TYPES = ["Armor", "Weapon", "Object"];
+const KIT_NEW_RE = /^new equipment "([^"]*)"$/;
+const KIT_WEAPONSET_RE = /^add initialweaponset "([^"]*)"$/;
+const KIT_GROUP_RE = /^add equipmentgroup$/;
+const KIT_ENTRY_RE = /^add equipment entry "([^"]*)"$/;
+export function parseEquipmentKits(text, file) {
+    const normalized = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+    const blocks = [];
+    let current;
+    let pendingGroup = false;
+    normalized.split("\n").forEach((raw, i) => {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("//"))
+            return;
+        const start = KIT_NEW_RE.exec(line);
+        if (start) {
+            current = { name: start[1] ?? "", line: i + 1, file, entries: [] };
+            blocks.push(current);
+            pendingGroup = false;
+            return;
+        }
+        if (!current)
+            return;
+        const weaponSet = KIT_WEAPONSET_RE.exec(line);
+        if (weaponSet) {
+            current.initialWeaponSet = weaponSet[1] ?? "";
+            pendingGroup = false;
+            return;
+        }
+        if (KIT_GROUP_RE.test(line)) {
+            pendingGroup = true;
+            return;
+        }
+        const entry = KIT_ENTRY_RE.exec(line);
+        if (entry) {
+            current.entries.push({ name: entry[1] ?? "", line: i + 1, grouped: pendingGroup });
+        }
+        pendingGroup = false;
+    });
+    return blocks;
+}
+async function resolveKitItem(ctx, projectMap, name) {
+    for (const type of KIT_ITEM_TYPES) {
+        const proj = projectMap.get(statMapKey(type, name));
+        if (proj)
+            return { type: proj.type, using: proj.using, fields: proj.fields, where: "project" };
+    }
+    const any = lookupStat(projectMap, name);
+    if (any)
+        return { type: any.type, using: any.using, fields: any.fields, where: "project" };
+    const row = await vanillaStat(ctx, name);
+    if (row)
+        return { type: row.type, using: row.using ?? undefined, fields: row.fields, where: "vanilla" };
+    return undefined;
+}
+async function effectiveFieldAcross(ctx, projectMap, name, field, preferType, cap = 10) {
+    let current = name;
+    const seen = new Set();
+    let depth = 0;
+    while (current && depth < cap && !seen.has(current)) {
+        seen.add(current);
+        const proj = lookupStat(projectMap, current, preferType);
+        if (proj) {
+            if (proj.fields[field] !== undefined)
+                return proj.fields[field];
+            current = proj.using;
+        }
+        else {
+            const row = await vanillaStat(ctx, current);
+            if (!row)
+                return undefined;
+            if (row.fields[field] !== undefined)
+                return row.fields[field];
+            current = row.using ?? undefined;
+        }
+        depth++;
+    }
+    return undefined;
+}
+async function projectKitBlocks(ctx) {
+    const files = await projectFiles(ctx.project, isEquipmentFile);
+    const blocks = [];
+    for (const f of files) {
+        try {
+            blocks.push(...parseEquipmentKits(await ctx.readText(f), f));
+        }
+        catch {
+        }
+    }
+    return blocks;
+}
+const equipmentKitEntriesResolve = {
+    id: "bg3.stats.equipment-kit-entries-resolve",
+    game: "baldursgate3",
+    groups: ["stats"],
+    modTypes: ["class", "armor", "weapon"],
+    summary: "Every `add equipment entry` in a Stats/Generated/Equipment.txt kit resolves to an Armor/Weapon/Object stat in the project or vanilla, and each kit block has the vanilla shape: `add initialweaponset` plus one `add equipmentgroup` before every entry.",
+    appliesTo: projectTarget(),
+    appliesToDescription: "the whole project (every Public/<Mod>/Stats/Generated/Equipment.txt)",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.equipment.cc-kit-override-replaces-vanilla-entry", "bg3.practice.reference-checker-invaluable"],
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const blocks = await projectKitBlocks(ctx);
+        if (blocks.length === 0)
+            return [];
+        const projectMap = await buildProjectStatMap(ctx);
+        const findings = [];
+        for (const block of blocks) {
+            if (block.initialWeaponSet === undefined) {
+                findings.push(finding(equipmentKitEntriesResolve.id, "block", block.file, `Kit '${block.name}' has no 'add initialweaponset' line. Every vanilla EQP_CC_* kit opens with one (add initialweaponset "Melee") before its equipment groups.`, equipmentKitEntriesResolve.evidence, { line: block.line, fix: `Add 'add initialweaponset "Melee"' directly after 'new equipment "${block.name}"'.` }));
+            }
+            for (const entry of block.entries) {
+                if (!entry.grouped) {
+                    findings.push(finding(equipmentKitEntriesResolve.id, "block", block.file, `Kit '${block.name}' entry "${entry.name}" is not preceded by 'add equipmentgroup'. The vanilla shape is a repeated pair: 'add equipmentgroup' then 'add equipment entry "<stat>"', one group per entry.`, equipmentKitEntriesResolve.evidence, { line: entry.line, fix: `Insert 'add equipmentgroup' on the line before 'add equipment entry "${entry.name}"'.` }));
+                }
+                const item = await resolveKitItem(ctx, projectMap, entry.name);
+                if (!item) {
+                    findings.push(finding(equipmentKitEntriesResolve.id, "block", block.file, `Kit '${block.name}' entry "${entry.name}" does not resolve to any stat entry in this project or the vanilla index. The kit line hands out nothing (or fails to load) with no error logged.`, equipmentKitEntriesResolve.evidence, { line: entry.line }));
+                }
+                else if (!KIT_ITEM_TYPES.includes(item.type)) {
+                    findings.push(finding(equipmentKitEntriesResolve.id, "block", block.file, `Kit '${block.name}' entry "${entry.name}" resolves to a ${item.type || "typeless"} entry (${item.where}), not an Armor, Weapon or Object stat. A kit can only hand out items.`, equipmentKitEntriesResolve.evidence, { line: entry.line }));
+                }
+            }
+        }
+        return findings;
+    },
+};
+const equipmentKitOneBodyArmor = {
+    id: "bg3.stats.equipment-kit-one-body-armor",
+    game: "baldursgate3",
+    groups: ["stats"],
+    modTypes: ["class", "armor"],
+    summary: "A Stats/Generated/Equipment.txt kit carries at most one Breast-slot armor: with two, character creation draws the vanilla outfit and the custom one's body mask still hides the arms.",
+    appliesTo: projectTarget(),
+    appliesToDescription: "the whole project (every Public/<Mod>/Stats/Generated/Equipment.txt)",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: [
+        "bg3.equipment.cc-kit-one-body-item",
+        "bg3.equipment.cc-kit-override-replaces-vanilla-entry",
+        "bg3.items.visualbank.vertexcolormaskslots-underwear-fix",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const blocks = await projectKitBlocks(ctx);
+        if (blocks.length === 0)
+            return [];
+        const projectMap = await buildProjectStatMap(ctx);
+        const findings = [];
+        for (const block of blocks) {
+            const breast = [];
+            for (const entry of block.entries) {
+                const item = await resolveKitItem(ctx, projectMap, entry.name);
+                if (!item || item.type !== "Armor")
+                    continue;
+                const slot = await effectiveFieldAcross(ctx, projectMap, entry.name, "Slot", "Armor");
+                if ((slot ?? "").trim().toLowerCase() === "breast")
+                    breast.push({ entry, where: item.where });
+            }
+            if (breast.length < 2)
+                continue;
+            const names = breast.map((b) => `"${b.entry.name}" (${b.where}, line ${b.entry.line})`).join(", ");
+            findings.push(finding(equipmentKitOneBodyArmor.id, "warn", block.file, `Kit '${block.name}' carries ${breast.length} Breast-slot armors: ${names}. With two body items in a character-creation kit the preview drew the VANILLA outfit while the custom robe's VertexColorMaskSlots still applied, so the character's arms vanished (observed in a subclass mod, 2026-09-14). Keep exactly one body-slot armor per kit.`, equipmentKitOneBodyArmor.evidence, {
+                line: breast[0].entry.line,
+                fix: `Drop every Breast-slot entry but the intended one from '${block.name}' (usually the vanilla ARM_<Class> body item).`,
+            }));
+        }
+        return findings;
+    },
+};
+const APPLYSTATUS_SWAP_RE = /\bApplyStatus\(\s*SWAP\b/;
+const onattackSwapTargetsAttacker = {
+    id: "bg3.history.onattack-swap-targets-attacker",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "In an OnAttack PassiveData, ApplyStatus(SWAP,...) lands the status on the attacker (the wearer), not the struck enemy — almost always a mistake.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.boosts.onattack-functors-target-the-struck-creature-swap-flips-to-the-attacker"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            if (entry.type !== "PassiveData")
+                continue;
+            const context = (entry.fields.StatsFunctorContext ?? "").split(";").map((s) => s.trim());
+            if (!context.includes("OnAttack"))
+                continue;
+            const functors = entry.fields.StatsFunctors ?? "";
+            if (!APPLYSTATUS_SWAP_RE.test(functors))
+                continue;
+            findings.push(finding(onattackSwapTargetsAttacker.id, "warn", ctx.target.path, `PassiveData '${entry.name}' has StatsFunctorContext "OnAttack" and applies a status to SWAP. In OnAttack, the default target is the creature that was hit and SELF is the attacker, so SWAP sends the status to the ATTACKER (the wearer) — observed in game in a subclass mod (2026-09-19). Drop the SWAP specifier to land it on the struck enemy, or use SELF if the attacker is truly intended.`, onattackSwapTargetsAttacker.evidence, {
+                line: entry.line,
+                fix: `In '${entry.name}'.StatsFunctors, change ApplyStatus(SWAP,<status>,...) to ApplyStatus(<status>,...) to target the struck creature (vanilla UND_HARDWORK_TARGET, MAG_ELECTROCUTED).`,
+            }));
+        }
+        return findings;
+    },
+};
+const CONDITIONAL_DAMAGEBONUS_RE = /IF\s*\((?:[^()]|\([^()]*\))*\)\s*:\s*DamageBonus\s*\(/;
+const conditionalDamagebonusBareDice = {
+    id: "bg3.history.conditional-damagebonus-bare-dice-tooltip",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "A conditional DamageBonus written straight into an Armor/Weapon Boosts prints as a bare dice line with no sentence; move it to a PassiveData with a Description.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "Armor.txt and Weapon.txt",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.boosts.conditional-damagebonus-in-item-boosts-renders-as-bare-dice"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        if (!/\/(armor|weapon)\.txt$/.test(lower(ctx.target.path)))
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const entries = parseStats(text, ctx.target.path);
+        const findings = [];
+        for (const entry of entries) {
+            if (entry.type !== "Armor" && entry.type !== "Weapon")
+                continue;
+            for (const field of ["Boosts", "DefaultBoosts"]) {
+                const value = entry.fields[field];
+                if (!value || !CONDITIONAL_DAMAGEBONUS_RE.test(value))
+                    continue;
+                findings.push(finding(conditionalDamagebonusBareDice.id, "warn", ctx.target.path, `${entry.type} '${entry.name}' has a conditional DamageBonus in its ${field} (IF(...):DamageBonus(...)). This works mechanically but the item tooltip renders it as a bare dice line ("1d4") with no explanatory sentence. Vanilla keeps such riders in a PassiveData with a DisplayName/Description (SCL_MastiffPoachers_Ring_Passive) granted through PassivesOnEquip, so the tooltip shows a card instead.`, conditionalDamagebonusBareDice.evidence, {
+                    line: entry.line,
+                    fix: `Move the conditional DamageBonus out of '${entry.name}'.${field} into a PassiveData with a DisplayName/Description, and grant it with PassivesOnEquip "<passive>".`,
+                }));
+            }
+        }
+        return findings;
+    },
+};
+const createexplosionProjectileRenderChain = {
+    id: "bg3.history.createexplosion-projectile-needs-render-chain",
+    game: "baldursgate3",
+    groups: ["history"],
+    modTypes: ["dialogue"],
+    summary: "A from-scratch Projectile (no `using`) fired via CreateExplosion deals damage but renders nothing; base it on Projectile_Fireball to keep a rendering chain.",
+    appliesTo: fileTarget(isStatsFile),
+    appliesToDescription: "every Stats/Generated/Data/*.txt file",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.spells.createexplosion-projectile-needs-a-donor-with-a-rendering-effect-chain"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const projectiles = parseStats(text, ctx.target.path).filter((e) => e.type === "SpellData" && e.fields.SpellType === "Projectile" && !e.using);
+        if (projectiles.length === 0)
+            return [];
+        const explosionCallArgs = await projectExplosionCallArgs(ctx);
+        const findings = [];
+        for (const entry of projectiles) {
+            if (!isExplosionOnlyInvoked(explosionCallArgs, entry.name))
+                continue;
+            findings.push(finding(createexplosionProjectileRenderChain.id, "warn", ctx.target.path, `SpellData '${entry.name}' is a Projectile with no 'using' parent, fired from a project CreateExplosion(...) Lua call. A from-scratch projectile fired this way deals its damage silently — no effect, no sound (observed in a subclass mod, 2026-09-17). Base it on a donor whose CreateExplosion chain renders (using "Projectile_Fireball", with SpellRoll/SpellSuccess/SpellFail/UseCosts blanked and SpellProperties/ExplodeRadius/TargetConditions overridden) so Fireball's CastSound and HitEffect carry over.`, createexplosionProjectileRenderChain.evidence, {
+                line: entry.line,
+                fix: `Give '${entry.name}' a using parent with a confirmed rendering chain (using "Projectile_Fireball"), blanking SpellRoll/SpellSuccess/SpellFail/UseCosts and overriding SpellProperties/ExplodeRadius/TargetConditions.`,
+            }));
+        }
+        return findings;
+    },
+};
+const ITEMCOMBOS_PATH_RE = /\/public\/[^/]+\/stats\/generated\/itemcombos\.txt$/;
+const isItemCombosFile = (p) => ITEMCOMBOS_PATH_RE.test(p);
+const COMBO_NEW_RE = /^new ItemCombination "([^"]*)"$/;
+const COMBO_RESULT_NEW_RE = /^new ItemCombinationResult "([^"]*)"$/;
+const COMBO_DATA_RE = /^data "(Type|Object) (\d+)" "(.*)"$/;
+export function parseItemCombinations(text, file) {
+    const normalized = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+    const combos = [];
+    let current;
+    const ingredientAt = (combo, index, line) => {
+        let ing = combo.ingredients.find((i) => i.index === index);
+        if (!ing) {
+            ing = { index, line };
+            combo.ingredients.push(ing);
+        }
+        return ing;
+    };
+    normalized.split("\n").forEach((raw, i) => {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("//"))
+            return;
+        const start = COMBO_NEW_RE.exec(line);
+        if (start) {
+            current = { name: start[1] ?? "", line: i + 1, file, ingredients: [] };
+            combos.push(current);
+            return;
+        }
+        if (COMBO_RESULT_NEW_RE.test(line)) {
+            current = undefined;
+            return;
+        }
+        if (!current)
+            return;
+        const data = COMBO_DATA_RE.exec(line);
+        if (!data)
+            return;
+        const [, key, nStr, value] = data;
+        const index = Number(nStr);
+        const ing = ingredientAt(current, index, i + 1);
+        if (key === "Type")
+            ing.type = value;
+        else
+            ing.value = value;
+    });
+    for (const combo of combos)
+        combo.ingredients.sort((a, b) => a.index - b.index);
+    return combos;
+}
+async function collectItemCombinations(ctx) {
+    const files = await projectFiles(ctx.project, isItemCombosFile);
+    const out = [];
+    for (const f of files) {
+        try {
+            out.push(...parseItemCombinations(await ctx.readText(f), f));
+        }
+        catch {
+        }
+    }
+    return out;
+}
+function hasCombineAction(node) {
+    const peace = child(node, "OnUsePeaceActions");
+    if (!peace)
+        return false;
+    return children(peace, "Action").some((a) => attr(a, "ActionType") === "23");
+}
+const itemcomboCombineAction = {
+    id: "bg3.stats.itemcombo-combine-action",
+    game: "baldursgate3",
+    groups: ["stats"],
+    modTypes: ["dialogue"],
+    summary: "An ItemCombination Object ingredient whose RootTemplate chain has no ActionType 23 peace action gets no Combine context-menu entry, so the recipe is unreachable.",
+    appliesTo: projectTarget(),
+    appliesToDescription: "once per project, over Public/<Mod>/Stats/Generated/ItemCombos.txt",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.itemcombos.combine-menu-comes-from-the-template-peace-action-not-the-recipe"],
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const combos = await collectItemCombinations(ctx);
+        if (combos.length === 0)
+            return [];
+        const statMap = await buildProjectStatMap(ctx);
+        const idx = await collectProjectLsx(ctx);
+        const rootTemplates = await collectRootTemplates(idx);
+        const rtByMapKey = new Map(rootTemplates.map((rt) => [rt.mapKey, rt]));
+        const chainState = (startMapKey) => {
+            const visited = new Set();
+            let current = rtByMapKey.get(startMapKey);
+            while (current) {
+                if (visited.has(current.mapKey))
+                    return "absent";
+                visited.add(current.mapKey);
+                if (hasCombineAction(current.node))
+                    return "found";
+                if (!current.parentTemplateId)
+                    return "absent";
+                const parent = rtByMapKey.get(current.parentTemplateId);
+                if (!parent)
+                    return "external";
+                current = parent;
+            }
+            return "absent";
+        };
+        const findings = [];
+        for (const combo of combos) {
+            for (const ing of combo.ingredients) {
+                if (ing.type && ing.type !== "Object")
+                    continue;
+                const statName = ing.value;
+                if (!statName)
+                    continue;
+                const entry = lookupStat(statMap, statName);
+                if (!entry)
+                    continue;
+                const rtId = entry.fields.RootTemplate;
+                if (!rtId)
+                    continue;
+                if (!rtByMapKey.has(rtId))
+                    continue;
+                const state = chainState(rtId);
+                if (state === "found")
+                    continue;
+                const unreachable = state === "absent";
+                findings.push(finding(itemcomboCombineAction.id, unreachable ? "warn" : "info", combo.file, unreachable
+                    ? `ItemCombination '${combo.name}' ingredient '${statName}' resolves to a project RootTemplate whose chain carries no OnUsePeaceActions Action with ActionType 23. An item gets the "Combine" context-menu entry only from that peace action, never from a recipe alone (bisected in-game in a subclass mod, 2026-09-19), so this recipe is unreachable from the UI.`
+                    : `ItemCombination '${combo.name}' ingredient '${statName}' resolves to a project RootTemplate with no ActionType 23 peace action, but its ParentTemplateId leaves the project into a template ModWright cannot inspect here. If that vanilla parent is not itself combinable, the recipe is unreachable; verify it carries the Combine action or add one to '${statName}'.`, itemcomboCombineAction.evidence, {
+                    line: combo.line,
+                    fix: `Add an OnUsePeaceActions Action (ActionType 23; Attributes Animation "", CombineSlots 1 (int8), IsBase True) to '${statName}'s RootTemplate, as on the vanilla Broken Spear halves.`,
+                }));
+            }
+        }
+        return findings;
+    },
+};
+const itemcomboCategoryIsCombocategory = {
+    id: "bg3.stats.itemcombo-category-is-combocategory",
+    game: "baldursgate3",
+    groups: ["stats"],
+    modTypes: ["dialogue"],
+    summary: "A `Type N \"Category\"` ItemCombination ingredient whose value is a mod-defined ComboCategory never matches in-game; name the partner directly with `Type N \"Object\"`.",
+    appliesTo: projectTarget(),
+    appliesToDescription: "once per project, over Public/<Mod>/Stats/Generated/ItemCombos.txt",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.itemcombos.category-ingredient-reads-combocategory-and-custom-values-did-not-match"],
+    async run(ctx) {
+        if (ctx.target.kind !== "project")
+            return [];
+        const combos = await collectItemCombinations(ctx);
+        if (combos.length === 0)
+            return [];
+        const statMap = await buildProjectStatMap(ctx);
+        const projectComboCategories = new Set();
+        for (const entry of statMap.values()) {
+            const cc = entry.fields.ComboCategory;
+            if (cc)
+                for (const v of cc.split(";").map((s) => s.trim()))
+                    if (v)
+                        projectComboCategories.add(v);
+        }
+        const findings = [];
+        for (const combo of combos) {
+            for (const ing of combo.ingredients) {
+                if (ing.type !== "Category" || !ing.value)
+                    continue;
+                if (!projectComboCategories.has(ing.value))
+                    continue;
+                findings.push(finding(itemcomboCategoryIsCombocategory.id, "block", combo.file, `ItemCombination '${combo.name}' uses a Category ingredient "${ing.value}", which this project defines as a custom ComboCategory. A Category ingredient is matched against the vanilla ComboCategory field, and a mod-defined value never matched a Combine partner in-game (observed in a subclass mod, 2026-09-19), even though it read back correctly on server and client.`, itemcomboCategoryIsCombocategory.evidence, {
+                    line: combo.line,
+                    fix: `Replace the Category ingredient with Type "Object" naming the partner's stat entry directly (e.g. data "Type ${ing.index}" "Object"; data "Object ${ing.index}" "<statName>").`,
+                }));
+            }
+        }
+        return findings;
+    },
+};
+export const STATS_VALIDATORS = [
+    spellanimationPresent,
+    islinkedspellcontainerLinks,
+    boostcontextInitialEvent,
+    contextQualifierValidity,
+    handleFormPerField,
+    handleDefinedInLoca,
+    spellidEnumerationDrift,
+    referenceIntegrity,
+    equipmentKitEntriesResolve,
+    equipmentKitOneBodyArmor,
+    onattackSwapTargetsAttacker,
+    conditionalDamagebonusBareDice,
+    createexplosionProjectileRenderChain,
+    itemcomboCombineAction,
+    itemcomboCategoryIsCombocategory,
+];