modwright 0.1.0

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

@@ -0,0 +1,790 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+import { parseLsx, walkLsxNodes } from "../index/parsers/lsx.js";
+function posix(p) {
+    return p.split(path.sep).join("/");
+}
+function lower(p) {
+    return posix(p).toLowerCase();
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+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 fileTarget(match) {
+    return (target) => target.kind === "file" && match(lower(target.path));
+}
+function finding(validatorId, severity, file, message, evidence, extra) {
+    return { validatorId, severity, file, message, evidence, ...extra };
+}
+const isGoalFile = (p) => p.endsWith(".txt") && p.includes("/goals/");
+const isJournalLsx = (p) => p.endsWith(".lsx") && p.includes("/journals/");
+const isOriginsLsx = (p) => /^origins(\..+)?\.lsx$/.test(path.posix.basename(p));
+const isTagsLsx = (p) => path.posix.basename(p) === "tags.lsx" || p.includes("/tags/");
+const isDialogLsj = (p) => p.endsWith(".lsj") && p.includes("/story/dialog");
+const isDialogBankLsx = (p) => p.endsWith(".lsx") && p.includes("dialogbank");
+const SECTION_NAMES = ["INIT", "KB", "EXIT"];
+const CALL_RE = /\b(DB_[A-Za-z0-9_]+|QRY_[A-Za-z0-9_]+|PROC_[A-Za-z0-9_]+|QuestUpdate|QuestAdd|QuestClose|GoalCompleted|SysClear)\s*\(([^)]*)\)/g;
+function splitArgs(raw) {
+    return raw.split(",").map((s) => s.trim());
+}
+function parseGoalFile(text, file) {
+    const normalized = stripBom(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const lines = normalized.split("\n");
+    const parentMatch = /^\s*\/\/\s*Parent:\s*(\S+)/im.exec(normalized);
+    const goal = {
+        file,
+        text: normalized,
+        lines,
+        sectionOrder: [],
+        parent: parentMatch?.[1],
+        definedDb: new Set(),
+        checkedDb: [],
+        definedQryProc: new Set(),
+        calledQryProc: [],
+        sysClearInKb: [],
+        questAddClose: [],
+        questUpdateCalls: [],
+        goalCompletedCount: 0,
+    };
+    const boundaries = [];
+    lines.forEach((raw, i) => {
+        const t = raw.trim();
+        if (t === "INIT" || t === "KB" || t === "EXIT") {
+            boundaries.push({ section: t, start: i });
+            goal.sectionOrder.push(t);
+        }
+    });
+    for (let b = 0; b < boundaries.length; b++) {
+        const section = boundaries[b].section;
+        const start = boundaries[b].start + 1;
+        const end = b + 1 < boundaries.length ? boundaries[b + 1].start : lines.length;
+        processSection(goal, section, start, end);
+    }
+    return goal;
+}
+function processSection(goal, section, start, end) {
+    let blockStart = start;
+    for (let i = start; i <= end; i++) {
+        const raw = goal.lines[i];
+        const isBlank = i === end || (raw ?? "").trim().length === 0;
+        if (isBlank) {
+            if (i > blockStart)
+                processBlock(goal, section, blockStart, i);
+            blockStart = i + 1;
+        }
+    }
+}
+function processBlock(goal, section, start, end) {
+    const blockLines = [];
+    for (let i = start; i < end; i++) {
+        const t = (goal.lines[i] ?? "").trim();
+        if (t.length === 0 || t.startsWith("//"))
+            continue;
+        blockLines.push({ i, text: t });
+    }
+    if (blockLines.length === 0)
+        return;
+    const thenIdx = blockLines.findIndex((l) => l.text === "THEN");
+    const ifIdx = blockLines.findIndex((l) => l.text === "IF");
+    const hasThen = thenIdx !== -1;
+    const hasIf = ifIdx !== -1;
+    const conditionLines = hasThen ? blockLines.slice(hasIf ? ifIdx + 1 : 0, thenIdx) : hasIf ? blockLines.slice(ifIdx + 1) : [];
+    const actionLines = hasThen ? blockLines.slice(thenIdx + 1) : hasIf ? [] : blockLines;
+    let firstCall = true;
+    const scan = (group, isCondition) => {
+        for (const { i, text } of group) {
+            CALL_RE.lastIndex = 0;
+            let m;
+            while ((m = CALL_RE.exec(text))) {
+                const name = m[1];
+                const line = i + 1;
+                if (name.startsWith("DB_")) {
+                    if (isCondition)
+                        goal.checkedDb.push({ name, line });
+                    else
+                        goal.definedDb.add(name);
+                }
+                else if (name.startsWith("QRY_") || name.startsWith("PROC_")) {
+                    if (hasThen && isCondition && firstCall)
+                        goal.definedQryProc.add(name);
+                    else
+                        goal.calledQryProc.push({ name, line });
+                }
+                else if (name === "QuestUpdate") {
+                    goal.questUpdateCalls.push({ args: splitArgs(m[2] ?? ""), line });
+                }
+                else if (name === "QuestAdd" || name === "QuestClose") {
+                    goal.questAddClose.push({ name, line });
+                }
+                else if (name === "GoalCompleted") {
+                    goal.goalCompletedCount++;
+                }
+                else if (name === "SysClear") {
+                    if (section === "KB")
+                        goal.sysClearInKb.push({ name, line });
+                }
+                firstCall = false;
+            }
+        }
+    };
+    scan(conditionLines, true);
+    scan(actionLines, false);
+}
+const ENGINE_SET_DBS = new Set(["DB_QuestIsAccepted", "DB_QuestIsOpened", "DB_QuestIsClosed"]);
+async function loadGoalFiles(project) {
+    const files = await projectFiles(project, isGoalFile);
+    const out = [];
+    for (const f of files) {
+        const { promises: fs } = await import("node:fs");
+        try {
+            out.push(parseGoalFile(await fs.readFile(f, "utf8"), f));
+        }
+        catch {
+        }
+    }
+    return out;
+}
+const osirisSymbolDefined = {
+    id: "bg3.story.osiris-symbol-defined",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "dialogue"],
+    summary: "Every DB_ symbol checked in KB is defined in INIT or a THEN block somewhere in the project; every QRY_/PROC_ called resolves to a definition.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script (a .txt file under a Goals/ directory)",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.dialogue.osiris-goals.db-checked-but-never-defined-error",
+        "bg3.dialogue.osiris-goals.qry-proc-color-coding",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const allGoals = await loadGoalFiles(ctx.project);
+        const definedDb = new Set();
+        const definedQryProc = new Set();
+        for (const g of allGoals) {
+            for (const d of g.definedDb)
+                definedDb.add(d);
+            for (const d of g.definedQryProc)
+                definedQryProc.add(d);
+        }
+        const text = await ctx.readText(ctx.target.path);
+        const goal = parseGoalFile(text, ctx.target.path);
+        const findings = [];
+        for (const { name, line } of goal.checkedDb) {
+            if (ENGINE_SET_DBS.has(name))
+                continue;
+            if (definedDb.has(name))
+                continue;
+            findings.push(finding(osirisSymbolDefined.id, "block", ctx.target.path, `'${name}' is checked here but is never defined in INIT or a THEN block anywhere in this project. ` +
+                `Vanilla story symbols were not checked (ModWright does not extract the vanilla .osi story), so this ` +
+                `is reported only against the project's own goals; if '${name}' is a vanilla database this finding is wrong and should be suppressed.`, osirisSymbolDefined.evidence, { line, fix: `Define ${name} in this goal's INIT section or in a THEN block, or remove the check.` }));
+        }
+        for (const { name, line } of goal.calledQryProc) {
+            if (definedQryProc.has(name))
+                continue;
+            findings.push(finding(osirisSymbolDefined.id, "block", ctx.target.path, `'${name}' is called here but no goal in this project defines it (a rule whose head is '${name}'). ` +
+                `The Story Editor reports this as "Could not find any complete/correct definition of Osiris User Query/Procedure".`, osirisSymbolDefined.evidence, { line }));
+        }
+        return findings;
+    },
+};
+const osirisNamingConvention = {
+    id: "bg3.story.osiris-naming-convention",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "dialogue"],
+    summary: "User-defined facts/queries/procs carry the DB_/QRY_/PROC_ prefix; new goal files follow Act_Region_Situation.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script (a .txt file under a Goals/ directory)",
+    needs: {},
+    cost: "edit",
+    severity: "info",
+    evidence: [
+        "bg3.dialogue.osiris-goals.act-region-situation-naming-convention",
+        "bg3.dialogue.osiris-goals.qry-proc-color-coding",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const findings = [];
+        const base = path.posix.basename(lower(ctx.target.path), ".txt");
+        if (!/^[a-z0-9]+(_[a-z0-9]+){2,}$/i.test(base)) {
+            findings.push(finding(osirisNamingConvention.id, "info", ctx.target.path, `Goal file name '${path.basename(ctx.target.path)}' does not obviously follow the Act_Region_Situation convention. ` +
+                `This is a naming convention, not a known build failure — no fact in knowledge/baldursgate3/ confirms a missing ` +
+                `prefix disables the story component (still an open question), so this stays informational.`, osirisNamingConvention.evidence));
+        }
+        const text = stripBom(await ctx.readText(ctx.target.path)).replace(/\r\n/g, "\n");
+        const badPrefixRe = /\b(?!DB_|QRY_|PROC_)([A-Za-z][A-Za-z0-9_]*)\s*\(/g;
+        let m;
+        const seen = new Set();
+        while ((m = badPrefixRe.exec(text))) {
+            const name = m[1];
+            if (seen.has(name))
+                continue;
+            if (!/_/.test(name))
+                continue;
+            if (["GoalCompleted", "SysClear", "QuestUpdate", "QuestAdd", "QuestClose"].includes(name))
+                continue;
+            seen.add(name);
+            findings.push(finding(osirisNamingConvention.id, "info", ctx.target.path, `'${name}' does not carry the DB_/QRY_/PROC_ prefix convention.`, osirisNamingConvention.evidence));
+        }
+        return findings;
+    },
+};
+const osirisSectionStructure = {
+    id: "bg3.story.osiris-section-structure",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "dialogue"],
+    summary: "Every goal file has INIT, KB and EXIT sections in that order; SysClear of a goal DB belongs in EXIT, not KB.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script (a .txt file under a Goals/ directory)",
+    needs: {},
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.dialogue.osiris-goals.init-kb-exit-sections", "bg3.dialogue.osiris-goals.exit-clears-databases"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const goal = parseGoalFile(text, ctx.target.path);
+        const findings = [];
+        const missing = SECTION_NAMES.filter((s) => !goal.sectionOrder.includes(s));
+        if (missing.length > 0) {
+            findings.push(finding(osirisSectionStructure.id, "block", ctx.target.path, `Missing section(s): ${missing.join(", ")}. Every goal script needs INIT, KB and EXIT in that order.`, osirisSectionStructure.evidence));
+        }
+        else {
+            const order = goal.sectionOrder.filter((s, i, arr) => arr.indexOf(s) === i);
+            if (order.join(",") !== "INIT,KB,EXIT") {
+                findings.push(finding(osirisSectionStructure.id, "block", ctx.target.path, `Sections appear out of order (${goal.sectionOrder.join(" -> ")}). Expected INIT, then KB, then EXIT.`, osirisSectionStructure.evidence));
+            }
+        }
+        for (const occ of goal.sysClearInKb) {
+            findings.push(finding(osirisSectionStructure.id, "info", ctx.target.path, `SysClear(...) in KB (line ${occ.line}) is conventionally placed in EXIT — KB stops being evaluated once EXIT runs, so a KB-section SysClear is unusual placement, not a build error.`, osirisSectionStructure.evidence, { line: occ.line }));
+        }
+        return findings;
+    },
+};
+const goalParentCompletes = {
+    id: "bg3.story.goal-parent-completes",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "dialogue"],
+    summary: "A goal nested under a project-authored parent must have some path where that parent calls GoalCompleted.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script that declares a '// Parent: <Goal>' header authored in this project",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: [
+        "bg3.dialogue.osiris-goals.parent-goal-must-complete-before-children-activate",
+        "bg3.dialogue.osiris-goals.goals-execute-top-to-bottom",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const goal = parseGoalFile(text, ctx.target.path);
+        if (!goal.parent)
+            return [];
+        const allGoals = await loadGoalFiles(ctx.project);
+        const parentGoal = allGoals.find((g) => path.posix.basename(lower(g.file), ".txt") === goal.parent.toLowerCase());
+        if (!parentGoal)
+            return [];
+        if (parentGoal.goalCompletedCount === 0) {
+            return [
+                finding(goalParentCompletes.id, "warn", ctx.target.path, `This goal declares parent '${goal.parent}', but that parent goal (${path.basename(parentGoal.file)}) never calls GoalCompleted anywhere — a child goal under a parent that never completes never activates.`, goalParentCompletes.evidence, { related: [parentGoal.file] }),
+            ];
+        }
+        return [];
+    },
+};
+function collectJournal(doc) {
+    const topLevelQuestIds = new Set();
+    const subQuestIds = new Set();
+    const entryIds = new Set();
+    for (const region of doc.regions) {
+        walkLsxNodes(region.root, (node, breadcrumb) => {
+            if (node.id === "Category") {
+                const name = node.attributes.Name?.value;
+                if (name)
+                    topLevelQuestIds.add(name);
+            }
+            else if (node.id === "SubQuest") {
+                const name = node.attributes.Name?.value;
+                if (name)
+                    subQuestIds.add(name);
+            }
+            else if (node.id === "Entry") {
+                const idAttr = node.attributes.ID?.value;
+                if (idAttr)
+                    entryIds.add(idAttr);
+            }
+            void breadcrumb;
+        });
+    }
+    return { topLevelQuestIds, subQuestIds, entryIds };
+}
+async function loadJournal(project, ctx) {
+    const files = await projectFiles(project, isJournalLsx);
+    if (files.length === 0)
+        return undefined;
+    const index = { topLevelQuestIds: new Set(), subQuestIds: new Set(), entryIds: new Set() };
+    for (const f of files) {
+        try {
+            const text = await ctx.readText(f);
+            const partial = collectJournal(parseLsx(text, f));
+            for (const v of partial.topLevelQuestIds)
+                index.topLevelQuestIds.add(v);
+            for (const v of partial.subQuestIds)
+                index.subQuestIds.add(v);
+            for (const v of partial.entryIds)
+                index.entryIds.add(v);
+        }
+        catch {
+        }
+    }
+    return index;
+}
+function literalArg(arg) {
+    const m = /^"([^"]*)"$/.exec(arg.trim());
+    return m?.[1];
+}
+const questUpdateParentId = {
+    id: "bg3.story.questupdate-parent-id",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "journal"],
+    summary: "QuestUpdate's _QuestID names a top-level quest, never a subquest id, even when updating a subquest entry.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script that calls QuestUpdate with a literal _QuestID argument",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.journal.quests.questupdate-requires-parent-quest-id",
+        "bg3.journal.quests.questupdateunlocked-reports-top-level-quest-id",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const journal = await loadJournal(ctx.project, ctx);
+        if (!journal)
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const goal = parseGoalFile(text, ctx.target.path);
+        const findings = [];
+        for (const call of goal.questUpdateCalls) {
+            const questIdArg = call.args.length >= 3 ? call.args[1] : call.args[0];
+            const questId = questIdArg ? literalArg(questIdArg) : undefined;
+            if (questId === undefined)
+                continue;
+            if (journal.subQuestIds.has(questId) && !journal.topLevelQuestIds.has(questId)) {
+                findings.push(finding(questUpdateParentId.id, "block", ctx.target.path, `QuestUpdate's _QuestID is '${questId}', which is a subquest id in the journal, not a top-level quest id. ` +
+                    `QuestUpdate always requires the parent quest's own ID, even when updating a subquest entry.`, questUpdateParentId.evidence, { line: call.line }));
+            }
+        }
+        return findings;
+    },
+};
+const questEntryExists = {
+    id: "bg3.story.quest-entry-exists",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "journal"],
+    summary: "Every _EntryID / _Update / _Step / _NewStep resolves to a journal node in the mod's journal LSX or the vanilla index.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script that references a journal entry id",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.journal.quests.db-questdef-state-reacts-to-flag",
+        "bg3.journal.quests.db-questdef-chainedstate-links-entries",
+        "bg3.journal.quests.db-questdef-conditionalstate-defined-multiple-times",
+        "bg3.journal.quests.questupdate-does-not-emit-a-journal-entry-by-itself",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const journal = await loadJournal(ctx.project, ctx);
+        if (!journal)
+            return [];
+        const targetPath = ctx.target.path;
+        const text = await ctx.readText(targetPath);
+        const goal = parseGoalFile(text, targetPath);
+        const findings = [];
+        const checkEntry = async (entryId, line, calledFrom) => {
+            if (journal.entryIds.has(entryId))
+                return;
+            const vanilla = await ctx.lookup("guid", { name: entryId });
+            if (vanilla.count > 0)
+                return;
+            findings.push(finding(questEntryExists.id, "block", targetPath, `${calledFrom}: entry id '${entryId}' does not resolve to a journal node in this project's journal LSX or the vanilla index.`, questEntryExists.evidence, { line }));
+        };
+        for (const call of goal.questUpdateCalls) {
+            const entryArg = call.args[call.args.length - 1];
+            const entryId = entryArg ? literalArg(entryArg) : undefined;
+            if (entryId !== undefined)
+                await checkEntry(entryId, call.line, "QuestUpdate");
+        }
+        const dbRe = /(DB_QuestDef_(?:State|ChainedState|ConditionalState))\s*\(([^)]*)\)/g;
+        let m;
+        while ((m = dbRe.exec(goal.text))) {
+            const args = splitArgs(m[2] ?? "");
+            const line = goal.text.slice(0, m.index).split("\n").length;
+            for (const raw of args.slice(1)) {
+                const lit = literalArg(raw);
+                if (lit !== undefined && !/^[0-9a-fA-F-]{8,}$/.test(lit)) {
+                    await checkEntry(lit, line, m[1]);
+                }
+            }
+        }
+        return findings;
+    },
+};
+const questAddQuestCloseDiscouraged = {
+    id: "bg3.story.questadd-questclose-discouraged",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["quest", "journal"],
+    summary: "QuestAdd/QuestClose exist but the documentation recommends QuestUpdate instead.",
+    appliesTo: fileTarget(isGoalFile),
+    appliesToDescription: "every Osiris goal script that calls QuestAdd or QuestClose",
+    needs: {},
+    cost: "edit",
+    severity: "info",
+    evidence: ["bg3.journal.quests.questadd-questclose-should-be-avoided"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const targetPath = ctx.target.path;
+        const text = await ctx.readText(targetPath);
+        const goal = parseGoalFile(text, targetPath);
+        return goal.questAddClose.map((occ) => finding(questAddQuestCloseDiscouraged.id, "info", targetPath, `${occ.name}(...) is used here. The documentation recommends relying on QuestUpdate instead of manually adding/closing quests.`, questAddQuestCloseDiscouraged.evidence, { line: occ.line }));
+    },
+};
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function collectOrigins(doc) {
+    const origins = [];
+    for (const region of doc.regions) {
+        walkLsxNodes(region.root, (node) => {
+            if (node.id !== "Origin")
+                return;
+            const tagUuids = [];
+            const reallyTags = node.children.find((c) => c.id === "ReallyTags");
+            for (const obj of reallyTags?.children ?? []) {
+                const v = obj.attributes.Object?.value;
+                if (v)
+                    tagUuids.push(v);
+            }
+            origins.push({ name: node.attributes.Name?.value, tagUuids });
+        });
+    }
+    return origins;
+}
+function collectTagUuids(doc) {
+    const uuids = new Set();
+    for (const region of doc.regions) {
+        walkLsxNodes(region.root, (node) => {
+            if (node.id !== "Tag")
+                return;
+            const v = node.attributes.UUID?.value;
+            if (v)
+                uuids.add(v);
+        });
+    }
+    return uuids;
+}
+const originsTagsDefined = {
+    id: "bg3.story.origins-tags-defined",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["origin"],
+    summary: "Every ReallyTags UUID in Origins.lsx is defined in the mod's Tags.lsx or resolves in the vanilla index.",
+    appliesTo: fileTarget(isOriginsLsx),
+    appliesToDescription: "the project's Origins.lsx",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.crash.dangling-tag-guid",
+        "bg3.origins.companions.origins-lsx-tag-must-be-a-real-origin-tag",
+    ],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const origins = collectOrigins(parseLsx(text, ctx.target.path));
+        const tagFiles = await projectFiles(ctx.project, isTagsLsx);
+        const projectTags = new Set();
+        for (const f of tagFiles) {
+            try {
+                for (const uuid of collectTagUuids(parseLsx(await ctx.readText(f), f)))
+                    projectTags.add(uuid);
+            }
+            catch {
+            }
+        }
+        const findings = [];
+        for (const origin of origins) {
+            for (const uuid of origin.tagUuids) {
+                if (projectTags.has(uuid))
+                    continue;
+                const vanilla = await ctx.lookup("guid", { uuid });
+                if (vanilla.count > 0)
+                    continue;
+                findings.push(finding(originsTagsDefined.id, "block", ctx.target.path, `Origin '${origin.name ?? "?"}' names tag ${uuid} in ReallyTags, but no Tags.lsx in this project defines it and it does not resolve in the vanilla index. ` +
+                    `This is believed (unverified) to null-deref tag lookup on character select; a first-hand crash report exists for the same shape of bug, so the severity stays at block even though the specific fact is unverified.`, originsTagsDefined.evidence, { fix: `Define ${uuid} in this project's Tags.lsx, or use a vanilla/existing origin's tag UUID instead.` }));
+            }
+        }
+        return findings;
+    },
+};
+const originRequiredFiles = {
+    id: "bg3.story.origin-required-files",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["origin"],
+    summary: "A project defining an origin ships the Origins.lsx entry, a CC preset template and a world-character file for it.",
+    appliesTo: fileTarget(isOriginsLsx),
+    appliesToDescription: "the project's Origins.lsx",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.origins.companions.crash-without-worldcharacter-equivalent-file"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const origins = collectOrigins(parseLsx(text, ctx.target.path));
+        if (origins.length === 0)
+            return [];
+        const allFiles = await projectFiles(ctx.project, () => true);
+        const findings = [];
+        for (const origin of origins) {
+            if (!origin.name)
+                continue;
+            const ccPreset = allFiles.some((f) => lower(f).endsWith(`${origin.name.toLowerCase()}_ccpreset.lsx`));
+            const worldCharacter = allFiles.some((f) => lower(f).endsWith(`${origin.name.toLowerCase()}_worldcharacter.lsx`));
+            if (!ccPreset) {
+                findings.push(finding(originRequiredFiles.id, "block", ctx.target.path, `Origin '${origin.name}' has no matching CC preset template (<Name>_CCPreset.lsx) anywhere in this project.`, originRequiredFiles.evidence));
+            }
+            if (!worldCharacter) {
+                findings.push(finding(originRequiredFiles.id, "block", ctx.target.path, `Origin '${origin.name}' has no matching world-character file (<Name>_WorldCharacter.lsx) anywhere in this project. The custom-origin tutorial reports a crash when this file was omitted, even though its exact necessity was not fully understood by the tutorial's author.`, originRequiredFiles.evidence));
+            }
+        }
+        return findings;
+    },
+};
+const originTemplatePlaceholderLeft = {
+    id: "bg3.story.origin-template-placeholder-left",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["origin"],
+    summary: "A UUID still carrying the custom-origin template's 'Regenerate this!' marker comment is present.",
+    appliesTo: fileTarget((p) => p.endsWith(".lsx") && (isOriginsLsx(p) || p.includes("/origins/"))),
+    appliesToDescription: "Origins.lsx and other LSX files under an Origins/ directory",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.origins.companions.regenerate-uuid-find-replace-warning"],
+    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 findings = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (!/Regenerate this!/i.test(lines[i] ?? ""))
+                continue;
+            const window = lines.slice(i, Math.min(lines.length, i + 3)).join("\n");
+            const uuid = /value="([0-9a-fA-F-]{36})"/.exec(window);
+            if (uuid) {
+                findings.push(finding(originTemplatePlaceholderLeft.id, "warn", ctx.target.path, `Placeholder UUID ${uuid[1]} still carries the custom-origin template's "Regenerate this!" marker. Replace every occurrence of this UUID across the whole template.`, originTemplatePlaceholderLeft.evidence, { line: i + 1 }));
+            }
+        }
+        return findings;
+    },
+};
+function parseDialogLsj(json) {
+    const obj = json;
+    const save = (obj?.save ?? {});
+    const v = save.version;
+    const version = v
+        ? {
+            major: Number(v.major ?? 0),
+            minor: Number(v.minor ?? 0),
+            revision: Number(v.revision ?? 0),
+            build: Number(v.build ?? 0),
+        }
+        : undefined;
+    const regions = (save.regions ?? {});
+    return { version, hasEditorData: Object.prototype.hasOwnProperty.call(regions, "editorData") };
+}
+const EDITOR_VERSION = { major: 4, minor: 5, revision: 0, build: 500 };
+function sameVersion(a, b) {
+    return a.major === b.major && a.minor === b.minor && a.revision === b.revision && a.build === b.build;
+}
+const dialogueSourceVersion = {
+    id: "bg3.story.dialogue-source-version",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["dialogue"],
+    summary: "A shipped dialogue override is binary-derived (save version 4.6.0.1, no top-level editorData region), never the editor .lsj.",
+    appliesTo: fileTarget(isDialogLsj),
+    appliesToDescription: "a .lsj file under a Story/Dialog(s) path — the divine-converted intermediate of a DialogsBinary .lsf (no toolchain hook exists in ValidationContext, so this reads that intermediate directly rather than invoking divine)",
+    needs: { project: true, toolchain: ["divine"] },
+    cost: "build",
+    severity: "block",
+    evidence: ["bg3.dialogue.binary-source-not-editor", "bg3.dialogue.override-packing-rule-was-wrong"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        let parsed;
+        try {
+            parsed = parseDialogLsj(JSON.parse(await ctx.readText(ctx.target.path)));
+        }
+        catch {
+            return [];
+        }
+        const findings = [];
+        if (parsed.hasEditorData) {
+            findings.push(finding(dialogueSourceVersion.id, "block", ctx.target.path, `This dialogue file carries a top-level 'editorData' region, which only the editor-exported .lsj has. ` +
+                `Never patch the shipped editor .lsj under Mods/<ns>/Story/Dialogs/ — extract the vanilla DialogsBinary .lsf, ` +
+                `convert lsf->lsj, patch that, then convert back.`, dialogueSourceVersion.evidence));
+        }
+        if (parsed.version && sameVersion(parsed.version, EDITOR_VERSION)) {
+            findings.push(finding(dialogueSourceVersion.id, "block", ctx.target.path, `This dialogue file's save version is ${EDITOR_VERSION.major}.${EDITOR_VERSION.minor}.${EDITOR_VERSION.revision}.${EDITOR_VERSION.build}, ` +
+                `the editor's version, not the binary's 4.6.0.1. Divine bakes this version into the converted .lsf, which is the root cause behind ` +
+                `the original (now-corrected) "dialog overrides cannot be packed" belief.`, dialogueSourceVersion.evidence));
+        }
+        return findings;
+    },
+};
+function collectBankResources(doc) {
+    const out = [];
+    for (const region of doc.regions) {
+        walkLsxNodes(region.root, (node) => {
+            if (node.id !== "Resource")
+                return;
+            out.push({
+                id: node.attributes.ID?.value,
+                name: node.attributes.Name?.value,
+                sourceFile: node.attributes.SourceFile?.value,
+                speakerSlots: node.attributes.SpeakerSlotsWithLines?.value,
+                flags: node.attributes.Flags?.value,
+            });
+        });
+    }
+    return out;
+}
+const dialogbankSourcefileRepoint = {
+    id: "bg3.story.dialogbank-sourcefile-repoint",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["dialogue"],
+    summary: "In the namespaced DialogBank pattern, only SourceFile is re-pointed; ID/Name/Flags/SpeakerSlotsWithLines keep the vanilla values.",
+    appliesTo: fileTarget(isDialogBankLsx),
+    appliesToDescription: "a DialogBank descriptor LSX (a divine-converted _merged.lsx twin) whose Resource nodes re-point SourceFile into this project's Story/Dialogs tree",
+    needs: { project: true, index: true, toolchain: ["divine"] },
+    cost: "build",
+    severity: "warn",
+    evidence: ["bg3.dialogue.dialogbank-namespaced-pattern"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        let resources;
+        try {
+            resources = collectBankResources(parseLsx(text, ctx.target.path));
+        }
+        catch {
+            return [];
+        }
+        const findings = [];
+        for (const res of resources) {
+            if (!res.sourceFile || !res.id)
+                continue;
+            if (!lower(res.sourceFile).includes("/story/dialogs/"))
+                continue;
+            const vanilla = await ctx.lookup("guid", { uuid: res.id });
+            if (vanilla.count === 0)
+                continue;
+            const row = vanilla.rows[0];
+            const vanillaName = row.name ?? undefined;
+            if (vanillaName && res.name && vanillaName !== res.name) {
+                findings.push(finding(dialogbankSourcefileRepoint.id, "warn", ctx.target.path, `Resource ${res.id} has Name '${res.name}' but the vanilla entry is named '${vanillaName}'. Only SourceFile should be re-pointed; Name should be a byte-for-byte copy.`, dialogbankSourcefileRepoint.evidence));
+            }
+        }
+        return findings;
+    },
+};
+const dialogueFlagGuidResolves = {
+    id: "bg3.story.dialogue-flag-guid-resolves",
+    game: "baldursgate3",
+    groups: ["story"],
+    modTypes: ["dialogue"],
+    summary: "Flag GUIDs referenced from dialogue nodes resolve to a Public/*/Flags/<guid>.lsf definition in the mod or vanilla.",
+    appliesTo: fileTarget(isDialogLsj),
+    appliesToDescription: "a dialogue .lsj that references flags by 'Name_GUID' and this project ships its own Public/*/Flags/ tree",
+    needs: { project: true, index: true, toolchain: ["divine"] },
+    cost: "build",
+    severity: "warn",
+    evidence: ["bg3.dialogue.flags-guid-definitions"],
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const flagFiles = await projectFiles(ctx.project, (p) => p.includes("/flags/") && (p.endsWith(".lsf") || p.endsWith(".lsx")));
+        if (flagFiles.length === 0)
+            return [];
+        const definedGuids = new Set(flagFiles.map((f) => path.posix.basename(lower(f), path.extname(f)).toLowerCase()));
+        const text = await ctx.readText(ctx.target.path);
+        const nameGuidRe = /"Name"\s*:\s*"[^"]*_([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"/g;
+        const findings = [];
+        let m;
+        while ((m = nameGuidRe.exec(text))) {
+            const guid = m[1].toLowerCase();
+            if (definedGuids.has(guid))
+                continue;
+            const vanilla = await ctx.lookup("guid", { uuid: guid });
+            if (vanilla.count > 0)
+                continue;
+            findings.push(finding(dialogueFlagGuidResolves.id, "warn", ctx.target.path, `Flag GUID ${guid} referenced here has no matching Public/*/Flags/${guid}.lsf in this project's own Flags/ tree.`, dialogueFlagGuidResolves.evidence));
+        }
+        return findings;
+    },
+};
+export const STORY_VALIDATORS = [
+    osirisSymbolDefined,
+    osirisNamingConvention,
+    osirisSectionStructure,
+    goalParentCompletes,
+    questUpdateParentId,
+    questEntryExists,
+    questAddQuestCloseDiscouraged,
+    originsTagsDefined,
+    originRequiredFiles,
+    originTemplatePlaceholderLeft,
+    dialogueSourceVersion,
+    dialogbankSourcefileRepoint,
+    dialogueFlagGuidResolves,
+];