modwright 0.1.0

package/dist/surfaces/valheim/validators/plugins.js

@@ -0,0 +1,287 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { compareVersions, parseVersion } from "../../../core/compat/version.js";
+import { parseDependencyString, parseThunderstoreManifest } from "../packaging.js";
+import { BEPINPLUGIN_GUID_RE, COMPATIBILITY_LEVELS, packageNameMatchesGuid, scanCfg, scanPluginSource, SEMVER_RE, SYSTEM_VERSION_RE, VERSION_STRICTNESS } from "../plugins.js";
+import { PACKAGE_SOURCE_KIND } from "./packaging.js";
+export const SOURCE_SOURCE_KIND = "source";
+const PLUGIN_EVIDENCE = ["valheim.bepinex.plugins.bepinplugin-attribute-contract", "valheim.bepinex.plugins.valheim-pack-allows-semver-versions"];
+const DEPENDENCY_EVIDENCE = ["valheim.bepinex.plugins.dependency-attributes", "valheim.bepinex.plugins.missing-hard-dependency-lines", "valheim.thunderstore.packaging.dependency-string-format", "valheim.toolchain.build.guid-to-package-name-has-no-registry"];
+const HARMONY_EVIDENCE = ["valheim.bepinex.plugins.never-unpatchall-with-null", "valheim.bepinex.plugins.harmony-version-and-patch-shape"];
+const NETWORK_EVIDENCE = ["valheim.jotunn.library.networkcompatibility-attribute"];
+const CFG_EVIDENCE = ["valheim.bepinex.loader.bepinex-cfg-keys"];
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isCsUnderSource(target, project) {
+    if (target.kind !== "file" || path.extname(target.path).toLowerCase() !== ".cs")
+        return false;
+    return project.sources.some((s) => s.exists && s.kind === SOURCE_SOURCE_KIND && isWithin(s.absPath, target.path));
+}
+const CS_APPLIES = `every .cs file under a project source of kind "${SOURCE_SOURCE_KIND}"`;
+async function scan(ctx, file) {
+    return scanPluginSource(await ctx.readText(file));
+}
+const bepInPlugin = {
+    id: "valheim.plugins.bepinplugin",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak", "packaging"],
+    summary: "A class deriving from BaseUnityPlugin carries exactly one [BepInPlugin]; its GUID matches BepInEx's allowed pattern and its version parses (System.Version, or SemVer under the Valheim pack); a [BepInPlugin] on a class that is not a BaseUnityPlugin is ignored by the chainloader.",
+    appliesTo: isCsUnderSource,
+    appliesToDescription: CS_APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: PLUGIN_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const s = await scan(ctx, file);
+        const findings = [];
+        if (s.baseUnityPluginClasses.length > 0 && s.plugins.length === 0) {
+            for (const c of s.baseUnityPluginClasses) {
+                findings.push({ validatorId: this.id, severity: "block", file, line: c.line, message: `${c.name} in ${name} derives from BaseUnityPlugin but carries no [BepInPlugin(GUID, Name, Version)]; BepInEx ignores the type entirely.`, fix: "Add [BepInPlugin(\"com.example.mod\", \"Mod Name\", \"1.0.0\")] above the class.", evidence: PLUGIN_EVIDENCE });
+            }
+        }
+        if (s.plugins.length > 1 && s.baseUnityPluginClasses.length <= 1) {
+            findings.push({ validatorId: this.id, severity: "block", file, line: s.plugins[1].line, message: `${name} carries ${s.plugins.length} [BepInPlugin] attributes for ${s.baseUnityPluginClasses.length} BaseUnityPlugin class${s.baseUnityPluginClasses.length === 1 ? "" : "es"}; each plugin class carries exactly one.`, evidence: PLUGIN_EVIDENCE });
+        }
+        if (s.plugins.length > 0 && s.baseUnityPluginClasses.length === 0) {
+            findings.push({ validatorId: this.id, severity: "warn", file, line: s.plugins[0].line, message: `${name} has a [BepInPlugin] but no class in this file derives from BaseUnityPlugin; the chainloader only loads BaseUnityPlugin subclasses, so if the class is declared here it will be skipped.`, evidence: PLUGIN_EVIDENCE });
+        }
+        for (const p of s.plugins) {
+            if (p.unresolved.length > 0) {
+                findings.push({ validatorId: this.id, severity: "info", file, line: p.line, message: `[BepInPlugin] in ${name} has argument${p.unresolved.length === 1 ? "" : "s"} ${p.unresolved.map((u) => `'${u}'`).join(", ")} not resolvable from this file (not a string literal or a same-file const string), so the GUID and version were not checked.`, evidence: PLUGIN_EVIDENCE });
+            }
+            if (p.guid !== undefined && !BEPINPLUGIN_GUID_RE.test(p.guid)) {
+                findings.push({ validatorId: this.id, severity: "block", file, line: p.line, message: `GUID "${p.guid}" in ${name} is not of BepInEx's allowed form (letters, digits, '.', '_', '-'); the chainloader logs "Skipping type ... because its GUID ... is of an illegal format" and never loads it.`, fix: "Use reverse-domain notation, e.g. com.author.modname.", evidence: PLUGIN_EVIDENCE });
+            }
+            if (p.version !== undefined && !SYSTEM_VERSION_RE.test(p.version)) {
+                if (SEMVER_RE.test(p.version)) {
+                    findings.push({ validatorId: this.id, severity: "info", file, line: p.line, message: `Version "${p.version}" in ${name} is SemVer with a suffix: accepted by denikson's BepInExPack_Valheim, rejected by stock BepInEx 5 ("Skipping type ... because its version is invalid").`, evidence: PLUGIN_EVIDENCE });
+                }
+                else {
+                    findings.push({ validatorId: this.id, severity: "block", file, line: p.line, message: `Version "${p.version}" in ${name} is neither a System.Version (2-4 integers) nor SemVer; BepInEx skips the plugin with "its version is invalid".`, evidence: PLUGIN_EVIDENCE });
+                }
+            }
+            if (p.name !== undefined && p.name.trim().length === 0) {
+                findings.push({ validatorId: this.id, severity: "warn", file, line: p.line, message: `[BepInPlugin] in ${name} has an empty Name. BepInEx loads it — only a null name is skipped — but Name is the plugin's log source and its display name, so its LogOutput.log lines arrive as "[Info   :          ]" with nothing to attribute them to, and Jötunn's mismatch panel names it as blank.`, fix: 'Give it a human-readable name, e.g. [BepInPlugin("com.example.mod", "Mod Name", "1.0.0")].', evidence: PLUGIN_EVIDENCE });
+            }
+        }
+        return findings;
+    },
+};
+async function manifestDependencies(ctx) {
+    const out = [];
+    for (const s of ctx.project.sources) {
+        if (!s.exists || s.kind !== PACKAGE_SOURCE_KIND)
+            continue;
+        const file = path.join(s.absPath, "manifest.json");
+        let text;
+        try {
+            text = await fs.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        try {
+            const { manifest } = parseThunderstoreManifest(text);
+            const packages = (manifest.dependencies ?? []).flatMap((raw) => {
+                const parsed = parseDependencyString(raw);
+                return parsed ? [{ ...parsed, raw }] : [];
+            });
+            out.push({ file, packages });
+        }
+        catch {
+        }
+    }
+    return out;
+}
+const LOADER_PACKAGES = new Set(["bepinexpack_valheim", "bepinexpack"]);
+const dependencyCrossCheck = {
+    id: "valheim.plugins.dependency-crosscheck",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak", "packaging"],
+    summary: "Every hard [BepInDependency] GUID has a matching package in manifest.json's dependencies (by name), and every manifest dependency other than the loader pack is named by some [BepInDependency]; the managers install the manifest's list, BepInEx orders by the attribute's.",
+    appliesTo: (target, project) => isCsUnderSource(target, project) && project.sources.some((s) => s.exists && s.kind === PACKAGE_SOURCE_KIND),
+    appliesToDescription: `${CS_APPLIES}, when the project also has a "${PACKAGE_SOURCE_KIND}" source`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: DEPENDENCY_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const s = await scan(ctx, file);
+        if (s.dependencies.length === 0 && s.plugins.length === 0)
+            return [];
+        const manifests = await manifestDependencies(ctx);
+        if (manifests.length === 0)
+            return [];
+        const findings = [];
+        const allPackages = manifests.flatMap((m) => m.packages.map((p) => ({ ...p, manifest: m.file })));
+        for (const d of s.dependencies) {
+            if (d.guid === undefined) {
+                if (d.unresolved.length > 0)
+                    findings.push({ validatorId: this.id, severity: "info", file, line: d.line, message: `[BepInDependency] in ${name} names its GUID as '${d.unresolved[0]}', not resolvable from this file, so it was not cross-checked.`, evidence: DEPENDENCY_EVIDENCE });
+                continue;
+            }
+            if (d.kind === "soft")
+                continue;
+            const match = allPackages.find((p) => packageNameMatchesGuid(p.name, d.guid));
+            if (!match) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file,
+                    line: d.line,
+                    message: `${name} declares a hard [BepInDependency] on "${d.guid}", and no dependency in manifest.json (${allPackages.map((p) => p.raw).join(", ") || "none"}) has a package name matching it; if it is a Thunderstore package the managers will not install it, and BepInEx then logs "Could not load [...] because it has missing dependencies: ${d.guid}".`,
+                    fix: "Add the package's {team}-{package}-{version} string to manifest.json's dependencies (or make the attribute a SoftDependency if the mod works without it). The match is by name and may miss a package whose name differs from its GUID.",
+                    evidence: DEPENDENCY_EVIDENCE,
+                    related: manifests.map((m) => m.file),
+                });
+            }
+            else if (d.minimumVersion !== undefined && parseVersion(d.minimumVersion) !== undefined && parseVersion(match.version) !== undefined) {
+                if (compareVersions(match.version, d.minimumVersion) < 0) {
+                    findings.push({ validatorId: this.id, severity: "warn", file, line: d.line, message: `${name} requires "${d.guid}" at ${d.minimumVersion} or newer, but manifest.json pins ${match.raw}, which is older; the managers install the pinned version and BepInEx refuses the plugin.`, fix: `Raise the manifest dependency to ${match.team}-${match.name}-${d.minimumVersion} or lower the attribute's minimum.`, evidence: DEPENDENCY_EVIDENCE, related: [match.manifest] });
+                }
+            }
+        }
+        if (s.plugins.length > 0) {
+            const guids = s.dependencies.map((d) => d.guid).filter((g) => g !== undefined);
+            for (const p of allPackages) {
+                if (LOADER_PACKAGES.has(p.name.toLowerCase()))
+                    continue;
+                if (guids.some((g) => packageNameMatchesGuid(p.name, g)))
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "info",
+                    file: p.manifest,
+                    message: `manifest.json depends on ${p.raw}, and no [BepInDependency] in ${name} names a GUID matching "${p.name}"; the managers install it, but BepInEx will not order this plugin after it, so it may run before its dependency has loaded.`,
+                    fix: `Add [BepInDependency("<its GUID>")] to the plugin class, or drop the manifest entry if it is not a plugin dependency. The match is by name and may miss a package whose name differs from its GUID.`,
+                    evidence: DEPENDENCY_EVIDENCE,
+                    related: [file],
+                });
+            }
+        }
+        return findings;
+    },
+};
+const harmony = {
+    id: "valheim.plugins.harmony-calls",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak"],
+    summary: "UnpatchAll() with no id (or null) is never called: it removes every mod's patches and the community records save corruption from it. Parameterless PatchAll() is noted: its assembly comes from the calling stack frame, which inlining can get wrong.",
+    appliesTo: isCsUnderSource,
+    appliesToDescription: CS_APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: HARMONY_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const s = await scan(ctx, file);
+        const findings = [];
+        for (const u of s.unpatchAllWithoutId) {
+            findings.push({ validatorId: this.id, severity: "block", file, line: u.line, message: `${name} calls UnpatchAll() with no Harmony id: that removes every plugin's patches, BepInEx logs "UnpatchAll has been called - This will remove ALL HARMONY PATCHES.", and the Valheim wiki records save corruption from it.`, fix: 'Call harmony.UnpatchSelf() or UnpatchAll("your.harmony.id"), and not on game shutdown at all.', evidence: HARMONY_EVIDENCE });
+        }
+        for (const p of s.patchAllParameterless) {
+            findings.push({ validatorId: this.id, severity: "info", file, line: p.line, message: `${name} calls PatchAll() with no assembly; Harmony resolves it from the calling stack frame and its own documentation warns that inlining can pick the wrong one.`, fix: "Prefer PatchAll(Assembly.GetExecutingAssembly()) or Harmony.CreateAndPatchAll(typeof(Plugin).Assembly, id).", evidence: HARMONY_EVIDENCE });
+        }
+        return findings;
+    },
+};
+const networkCompatibility = {
+    id: "valheim.plugins.network-compatibility",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak"],
+    summary: `[NetworkCompatibility] names a CompatibilityLevel (${COMPATIBILITY_LEVELS.join(", ")}) and a VersionStrictness (${VERSION_STRICTNESS.join(", ")}); a mod enforcing EveryoneMustHaveMod or ServerMustHaveMod needs deploying to the server too.`,
+    appliesTo: isCsUnderSource,
+    appliesToDescription: CS_APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: NETWORK_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const s = await scan(ctx, file);
+        const findings = [];
+        for (const n of s.networkCompatibility) {
+            if (n.level !== undefined && !COMPATIBILITY_LEVELS.includes(n.level)) {
+                findings.push({ validatorId: this.id, severity: "warn", file, line: n.line, message: `[NetworkCompatibility] in ${name} names CompatibilityLevel.${n.level}, which is not a member (${COMPATIBILITY_LEVELS.join(", ")}).`, evidence: NETWORK_EVIDENCE });
+            }
+            if (n.strictness !== undefined && !VERSION_STRICTNESS.includes(n.strictness)) {
+                findings.push({ validatorId: this.id, severity: "warn", file, line: n.line, message: `[NetworkCompatibility] in ${name} names VersionStrictness.${n.strictness}, which is not a member (${VERSION_STRICTNESS.join(", ")}).`, evidence: NETWORK_EVIDENCE });
+            }
+            if (n.level === "EveryoneMustHaveMod" || n.level === "ServerMustHaveMod") {
+                const clientOnly = s.bepInProcesses.some((p) => p.name?.toLowerCase() === "valheim.exe") && !s.bepInProcesses.some((p) => p.name?.toLowerCase() === "valheim_server.exe");
+                if (clientOnly) {
+                    findings.push({ validatorId: this.id, severity: "warn", file, line: n.line, message: `${name} enforces CompatibilityLevel.${n.level} but its [BepInProcess] restricts it to valheim.exe, so it can never be loaded on the server it requires itself on; every client would be refused with Jötunn's "Missing Mods" panel.`, fix: "Drop the [BepInProcess] restriction or add one for valheim_server.exe.", evidence: NETWORK_EVIDENCE });
+                }
+                else {
+                    findings.push({ validatorId: this.id, severity: "info", file, line: n.line, message: `${name} enforces CompatibilityLevel.${n.level}: the dedicated server must run this exact plugin (to ${n.strictness ?? "the declared"} strictness) or clients are disconnected into Jötunn's mismatch panel; deploy it to the server install too.`, evidence: NETWORK_EVIDENCE });
+                }
+            }
+        }
+        return findings;
+    },
+};
+function isCfgUnderSource(target, project) {
+    if (target.kind !== "file" || path.extname(target.path).toLowerCase() !== ".cfg")
+        return false;
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, target.path));
+}
+const cfgSyntax = {
+    id: "valheim.plugins.config-syntax",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak", "packaging"],
+    summary: "A shipped .cfg is in BepInEx's ConfigFile shape ([Section] headers, Key = Value, # comments) with no duplicate key in a section; a plugin config is named <GUID>.cfg.",
+    appliesTo: isCfgUnderSource,
+    appliesToDescription: "every .cfg under a project source",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: CFG_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const s = scanCfg(await ctx.readText(file));
+        const findings = [];
+        for (const m of s.malformed) {
+            findings.push({ validatorId: this.id, severity: "warn", file, line: m.line, message: `${name} line ${m.line} is neither a [Section], a Key = Value pair nor a # comment: "${m.text}"; BepInEx's ConfigFile skips it.`, evidence: CFG_EVIDENCE });
+        }
+        for (const d of s.duplicates) {
+            findings.push({ validatorId: this.id, severity: "warn", file, line: d.lines[d.lines.length - 1], message: `${name} sets "${d.key}" ${d.lines.length} times in [${d.section || "(no section)"}] (lines ${d.lines.join(", ")}); only one value survives.`, evidence: CFG_EVIDENCE });
+        }
+        if (s.entries.some((e) => e.section === "")) {
+            findings.push({ validatorId: this.id, severity: "warn", file, line: s.entries.find((e) => e.section === "").line, message: `${name} has Key = Value lines before any [Section]; BepInEx's ConfigFile keys every entry by section, so these belong to none.`, evidence: CFG_EVIDENCE });
+        }
+        if (name.toLowerCase() !== "bepinex.cfg") {
+            const guid = name.slice(0, -".cfg".length);
+            if (!BEPINPLUGIN_GUID_RE.test(guid) || !guid.includes(".")) {
+                findings.push({ validatorId: this.id, severity: "info", file, message: `${name} is not named like a plugin config: BepInEx writes a plugin's config as <GUID>.cfg (reverse-domain GUID), and a shipped file under config/ only takes effect under that name.`, evidence: CFG_EVIDENCE });
+            }
+        }
+        return findings;
+    },
+};
+export const PLUGIN_VALIDATORS = [bepInPlugin, dependencyCrossCheck, harmony, networkCompatibility, cfgSyntax];

package/dist/surfaces/valheim/validators/references.js

@@ -0,0 +1,169 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+import { scanReferences, translationKeys } from "../references.js";
+import { SOURCE_SOURCE_KIND } from "./plugins.js";
+const EVIDENCE = [
+    "valheim.jotunn.library.references-are-by-prefab-name-and-token",
+    "valheim.jotunn.library.jotunndoc-publishes-a-vanilla-index",
+    "valheim.jotunn.library.jotunndoc-table-shapes",
+];
+const APPLIES = `every .cs file under a project source of kind "${SOURCE_SOURCE_KIND}"`;
+const MAX_PER_FILE = 30;
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isCsUnderSource(target, project) {
+    if (target.kind !== "file" || path.extname(target.path).toLowerCase() !== ".cs")
+        return false;
+    return project.sources.some((s) => s.exists && s.kind === SOURCE_SOURCE_KIND && isWithin(s.absPath, target.path));
+}
+async function projectDeclarations(ctx) {
+    const out = { prefabs: new Set(), tokens: new Set(), pieceTables: new Set() };
+    for (const s of ctx.project.sources) {
+        if (!s.exists)
+            continue;
+        const { files } = await walk(s.absPath);
+        for (const rel of files) {
+            const lower = rel.toLowerCase();
+            const full = path.join(s.absPath, ...rel.split("/"));
+            if (s.kind === SOURCE_SOURCE_KIND && lower.endsWith(".cs")) {
+                try {
+                    const scan = scanReferences(await ctx.readText(full));
+                    for (const p of scan.declares.prefabs)
+                        out.prefabs.add(p.toLowerCase());
+                    for (const t of scan.declares.tokens)
+                        out.tokens.add(t.toLowerCase());
+                    for (const t of scan.declares.pieceTables)
+                        out.pieceTables.add(t.toLowerCase());
+                }
+                catch {
+                }
+            }
+            else if (lower.endsWith(".json") && /(^|\/)translations\//.test(lower)) {
+                try {
+                    for (const k of translationKeys(await ctx.readText(full)))
+                        out.tokens.add(k.toLowerCase());
+                }
+                catch {
+                }
+            }
+        }
+    }
+    return out;
+}
+function declaredByProject(declared, ref) {
+    const value = ref.value.toLowerCase();
+    switch (ref.kind) {
+        case "token":
+            return declared.tokens.has(value.replace(/^\$/, ""));
+        case "prefab":
+        case "requirement":
+            return declared.prefabs.has(value);
+        case "piece_table":
+            return declared.pieceTables.has(value) || declared.prefabs.has(value);
+        case "asset":
+            return false;
+    }
+}
+async function inIndex(ctx, ref) {
+    switch (ref.kind) {
+        case "prefab":
+        case "requirement": {
+            const r = await ctx.lookup("entry", { name: ref.value, limit: 1 });
+            return r.count > 0;
+        }
+        case "piece_table": {
+            const byName = await ctx.lookup("entry", { kind: "piece_table", name: ref.value, limit: 1 });
+            if (byName.count > 0)
+                return true;
+            const tables = await ctx.lookup("entry", { kind: "piece_table", limit: 200 });
+            return tables.rows.some((row) => {
+                const data = row.data;
+                return data !== undefined && Object.entries(data).some(([column, value]) => /alias/i.test(column) && value.toLowerCase() === ref.value.toLowerCase());
+            });
+        }
+        case "token": {
+            const r = await ctx.lookup("token", { token: ref.value, limit: 1 });
+            return r.count > 0;
+        }
+        case "asset": {
+            const r = await ctx.lookup("asset", { id: ref.value });
+            return r.count > 0;
+        }
+    }
+}
+const KIND_WORDS = {
+    prefab: "prefab",
+    requirement: "recipe item",
+    piece_table: "piece table",
+    token: "localization token",
+    asset: "AssetID",
+};
+function consequence(ref) {
+    switch (ref.kind) {
+        case "prefab":
+            return "Jötunn's tutorials say a clone source must be an existing prefab; a name that resolves nowhere leaves the item or piece unregistered at runtime.";
+        case "requirement":
+            return "Jötunn's tutorials say a recipe's crafted item and its requirements must name existing item prefabs; a name that resolves nowhere makes the recipe unfulfillable or drops it when Jötunn resolves it.";
+        case "piece_table":
+            return "a piece whose table does not exist is never shown in any build menu.";
+        case "token":
+            return "Jötunn's localization falls back to English and then to Valheim's own Translation class, so a token neither the mod nor the game defines reaches the player unresolved.";
+        case "asset":
+            return "Iron Gate's soft-reference layer keys on the AssetID, which \"will always stay the same for each asset even if it's moved or renamed\", so an ID no indexed asset carries names nothing in the vanilla data.";
+    }
+}
+const references = {
+    id: "valheim.plugins.vanilla-references",
+    game: "valheim",
+    groups: ["plugins"],
+    modTypes: ["gameplay-tweak", "item", "weapon", "armor"],
+    summary: "Every prefab a CustomItem/CustomPiece clones or GetPrefab fetches, every recipe requirement item, every literal piece table, every $token and every 32-hex AssetID in the plugin's source resolves in the vanilla index or is declared by the project; each miss is a warning, since the name may belong to another mod or the dumps may lag the game.",
+    appliesTo: isCsUnderSource,
+    appliesToDescription: APPLIES,
+    needs: { project: true, index: true },
+    cost: "build",
+    severity: "warn",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        const scan = scanReferences(await ctx.readText(file));
+        if (scan.refs.length === 0)
+            return [];
+        const declared = await projectDeclarations(ctx);
+        const findings = [];
+        const seen = new Set();
+        const refs = [...scan.refs].sort((a, b) => a.line - b.line);
+        for (const [i, ref] of refs.entries()) {
+            const key = `${ref.kind}:${ref.value.toLowerCase()}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (declaredByProject(declared, ref))
+                continue;
+            if (await inIndex(ctx, ref))
+                continue;
+            findings.push({
+                validatorId: this.id,
+                severity: "warn",
+                file,
+                line: ref.line,
+                message: `${name} references ${KIND_WORDS[ref.kind]} "${ref.value}" (${ref.via}), which is neither in the vanilla index nor declared by this project; ${consequence(ref)}`,
+                fix: ref.kind === "token"
+                    ? "Register the token with AddTranslation or a Translations/<Language>/*.json file, or use a vanilla token from the index (lookup kind token). The index carries the Token column of the JotunnDoc object lists, not Valheim's full translation table, so a vanilla token that belongs to no prefab, item or piece (a $menu_* or $msg_* string) warns here and is fine."
+                    : "Check the spelling against the index (lookup kind entry, or asset), or declare the name in this project; if it belongs to another installed mod, this warning is expected.",
+                evidence: EVIDENCE,
+            });
+            if (findings.length >= MAX_PER_FILE && i < refs.length - 1) {
+                findings.push({ validatorId: this.id, severity: "info", file, message: `More unresolved references in ${name} than this rule lists (${MAX_PER_FILE}); fix these first.`, evidence: EVIDENCE });
+                break;
+            }
+        }
+        return findings;
+    },
+};
+export const REFERENCE_VALIDATORS = [references];

package/knowledge/baldursgate3/animations.gr2.yaml

@@ -0,0 +1,166 @@
+game: baldursgate3
+topic: animations.gr2
+title: GR2 animation export (GLTF vs Collada) and Toolkit animation registration
+facts:
+  - id: bg3.animations.gr2.export-via-gltf-not-collada-for-animations
+    claim: When exporting a baked skeleton animation to .GR2 with Norbyte's DOS2/BG3 Collada Exporter
+      add-on, the documented path is "export via GLTF" specifically, "not via Collada" — the add-on
+      supports both, but the GLTF path is the one that correctly carries animation-bearing meshes
+      for BG3.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/CustomAnimationsBlender §How to correctly bake
+      and export your animation
+    tags:
+      - animation
+      - gr2
+      - gltf
+      - collada
+      - export
+  - id: bg3.animations.gr2.export-only-skeleton-not-control-rig-or-meshes
+    claim: "\"You only want to export the skeleton rig, not the control rig or any of the meshes\",
+      because \"While you do your animating on the control rig, the skeleton does not receive any
+      keyframes, it's being constrained (puppeteered) by the control rig\" — so the Action must
+      first be baked onto the skeleton (\"Go into Pose > Animation > Bake Action\") before export."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/CustomAnimationsBlender §How to correctly bake
+      and export your animation
+    tags:
+      - animation
+      - gr2
+      - bake-action
+      - control-rig
+      - export
+  - id: bg3.animations.gr2.bake-action-clear-constraints-disconnects-rig
+    claim: Baking Action on a skeleton rig with "clear constraints" checked disconnects the skeleton
+      from the control rig afterward (moving the control rig no longer moves the skeleton); leaving
+      that option unchecked keeps the skeleton connected to the control rig after baking.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/CustomAnimationsBlender §How to correctly bake
+      and export your animation
+    tags:
+      - animation
+      - bake-action
+      - control-rig
+  - id: bg3.animations.gr2.gr2-bones-are-joints-not-blender-bones
+    claim: GR2 bones function as single-point joints (like Maya), not two-ended Blender bones with a
+      head and tail; Blender's importer guesses a tail position using Blender's own primary axis
+      convention (Y) versus GR2/Maya's (X), which makes imported bones look "sideways" in Blender —
+      this is expected and exports back correctly, since only the joint/bone head position actually
+      matters.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/CustomAnimationsBlender §How to correctly bake
+      and export your animation
+    tags:
+      - animation
+      - gr2
+      - bones
+      - joints
+      - blender
+  - id: bg3.animations.gr2.filename-identity-required-between-custom-and-toolkit-gr2
+    claim: "\"It's important that your custom animation .GR2 is named the same as the file in the
+      Toolkit\": you open the animation resource's \"Source File\" path (minus the filename), then
+      \"replace the vanilla .GR2 file with your own in the folder you just opened up\"."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §Adding Poses to the
+      _Base
+    tags:
+      - animation
+      - gr2
+      - toolkit
+      - filename-identity
+      - silent-failure
+  - id: bg3.animations.gr2.body-type-base-fallback-to-hum-m-base
+    claim: If a specific body-type _Base AnimationSetResource doesn't have an animation registered, the
+      game falls back to whatever is registered in HUM_M_Base — "everyone gets to use the HUM_M_Base
+      ones" — so an animation added only to HUM_F_Base is usable only by BT1 (that body type)
+      characters, while one added to HUM_M_Base is available to all body types that don't have their
+      own override.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §Adding Poses to the
+      _Base ("Everything will default back to the HUM_M_Base if the other bases don't have an
+      animation set into them, (everyone gets to use the HUM_M_Base ones) if something is just in
+      the HUM_F_Base then only the BT1 characters can use those")
+    tags:
+      - animation
+      - animationset
+      - hum-m-base
+      - fallback
+  - id: bg3.animations.gr2.photomode-pose-mods-override-each-other
+    claim: Photomode pose/animation mods override one another rather than stacking, so only one such mod
+      can be active in a load order at a time — a constraint worth stating explicitly when
+      publishing.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit ("Currently,
+      photomode pose/animation mods override one another, so you can only have one in your load
+      order at a time")
+    tags:
+      - animation
+      - photomode
+      - load-order
+      - compatibility
+  - id: bg3.animations.gr2.larian-packs-multiple-poses-per-animation-file
+    claim: '"Instead of having one animation file for each static pose, Larian puts each pose in a
+      collection into one animation file. The timing for each pose is then set in the Object UUID
+      Editor."'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §2.4 EmoteCollections
+    tags:
+      - animation
+      - toolkit
+      - pose-collection
+  - id: bg3.animations.gr2.shortname-required-per-individual-pose
+    claim: In the Object UUID Editor's ShortNames, "you want to add an entry for each pose that you
+      have. Not for a collection/pack, but for every single animation" — so a file holding 10 static
+      poses needs 10 ShortName entries. One pose adjusted per body type can reuse a single ShortName
+      across each body-type's _Base ("HUM_F_Hugs_BT1 and the same pose adjusted for hight for
+      HUM_M_Hugs_BT1 can share the same shortname").
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §2.2 ShortNames
+    tags:
+      - animation
+      - shortnames
+      - toolkit
+      - uuid-object-editor
+  - id: bg3.animations.gr2.emoteposes-vs-emoteanimations-distinction
+    claim: A static pose is registered under EmotePoses; a moving animation follows "these same steps
+      but instead of adding 'EmotePoses', add 'EmoteAnimations' instead. The only difference is that
+      is doesn't have 'Timing' in the tab."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §2.3 EmotePoses and
+      EmoteAnimations
+    tags:
+      - animation
+      - emoteposes
+      - emoteanimations
+      - toolkit
+  - id: bg3.animations.gr2.toolkit-restart-needed-after-gr2-replacement
+    claim: After manually replacing a vanilla .GR2 file on disk with a custom one of the same name, the
+      Toolkit must be closed and reopened for the new animation to show correctly in the project
+      folder — it will not pick up the swapped file while still running.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit ("you have to close
+      down the Toolkit and open it again in order for your animations to show properly in the
+      project folder")
+    tags:
+      - animation
+      - toolkit
+      - gr2
+      - restart-required
+  - id: bg3.animations.gr2.publish-local-required-before-bg3mm-load-order
+    claim: After setting up an animation mod's project settings (Project > Project Settings, Ctrl+P) and
+      filling the mandatory fields plus author, the Toolkit's "Publish Local" step is what generates
+      the .pak into the local Mods folder, which is then added to a load order and exported to the
+      game in BG3 Mod Manager — this is a Toolkit-only publish step distinct from publishing to
+      mod.io.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Animations/Adding-Animations-In-Toolkit §Exporting Your Mod
+      ("Publish Local (automatically adds the mod to your Mods folder)")
+    tags:
+      - animation
+      - toolkit
+      - publish-local
+      - bg3mm
+    detail: Larian's own publishing doc describes Publish Local as writing a .pak "without uploading it
+      to mod.io" to a location you choose — see
+      bg3.publishing.toolkit-modio.publish-local-vs-publish-to-modio; this page's phrasing is the
+      animation workflow's shorthand for the same button.