hoi4-agent-tools 3.8.1 → 3.10.0

package/dist/hoi4_agent_tools/reference/script-validation.js

@@ -2,9 +2,158 @@ import path from 'node:path';
 import { hashCanonical } from '../core/canonical.js';
 import { ServiceError } from '../core/result.js';
 import { locationFor, parseClausewitz, } from '../core/source/index.js';
+import { repeatedPopupFindings } from './event-popups.js';
+import { playerTextFindings, playerTextPosition } from './player-text.js';
 import { editDistance } from './suggestions.js';
 import { publicReferenceSection } from './service.js';
 const MAX_COMMANDS = 256;
+const MAX_FILE_COMMANDS = 50_000;
+/** A block whose scope the file's structure does not determine; scope checks are skipped. */
+const UNKNOWN_SCOPE = 'unknown';
+/**
+ * Scope links from the wiki Scopes page: the scopes each link is usable in and the scope it
+ * enters. The engine accepts these keys in any letter case.
+ */
+const scopeLinks = {
+    owner: { from: ['state', 'character', 'combatant'], to: 'country' },
+    controller: { from: ['state'], to: 'country' },
+    capital_scope: { from: ['country'], to: 'state' },
+    overlord: { from: ['country'], to: 'country' },
+    faction_leader: { from: ['country'], to: 'country' },
+};
+const eventScopes = {
+    country_event: 'country',
+    news_event: 'country',
+    state_event: 'state',
+    unit_leader_event: 'character',
+    operative_leader_event: 'character',
+};
+const optionMetadata = new Set([
+    'name',
+    'ai_chance',
+    'original_recipient_only',
+    'highlight_states',
+    'is_triggered_only',
+]);
+const decisionTriggers = new Set([
+    'allowed',
+    'visible',
+    'available',
+    'cancel_trigger',
+    'remove_trigger',
+    'activation',
+]);
+const decisionEffects = new Set([
+    'complete_effect',
+    'remove_effect',
+    'timeout_effect',
+    'cancel_effect',
+]);
+const focusTriggers = new Set(['available', 'bypass', 'cancel', 'allow_branch']);
+const focusEffects = new Set([
+    'completion_reward',
+    'select_effect',
+    'cancel_effect',
+    'bypass_effect',
+]);
+function blockOf(entry) {
+    return entry.type === 'assignment' && entry.value.type === 'block' ? entry.value : undefined;
+}
+/**
+ * The effect and trigger bodies of a mod file, with the scope its structure fixes. Families
+ * whose scope depends on the caller, such as scripted helpers and on actions, are checked
+ * without scope rules. An unrecognized family yields no roots.
+ */
+export function scriptRoots(relativePath, document) {
+    const file = relativePath.replaceAll('\\', '/').toLowerCase();
+    const roots = [];
+    const add = (block, kind, scope) => {
+        if (block !== undefined)
+            roots.push({ block, kind, scope });
+    };
+    const top = document.root.entries.filter((entry) => entry.type === 'assignment');
+    if (file.startsWith('events/')) {
+        for (const event of top) {
+            const scope = eventScopes[event.key.value];
+            const body = blockOf(event);
+            if (scope === undefined || body === undefined)
+                continue;
+            for (const entry of body.entries) {
+                if (entry.type !== 'assignment')
+                    continue;
+                const key = entry.key.value;
+                if (key === 'trigger' || key === 'show_major')
+                    add(blockOf(entry), 'trigger', scope);
+                else if (key === 'immediate' || key === 'after')
+                    add(blockOf(entry), 'effect', scope);
+                else if (key === 'option') {
+                    const option = blockOf(entry);
+                    if (option === undefined)
+                        continue;
+                    const effects = option.entries.filter((child) => child.type !== 'assignment' ||
+                        (child.key.value !== 'trigger' && !optionMetadata.has(child.key.value)));
+                    for (const child of option.entries)
+                        if (child.type === 'assignment' && child.key.value === 'trigger')
+                            add(blockOf(child), 'trigger', scope);
+                    if (effects.length > 0)
+                        add({ ...option, entries: effects }, 'effect', scope);
+                }
+            }
+        }
+        return { family: 'events', roots };
+    }
+    if (file.startsWith('common/decisions/') && !file.startsWith('common/decisions/categories/')) {
+        for (const category of top)
+            for (const decision of blockOf(category)?.entries ?? []) {
+                const body = blockOf(decision);
+                if (body === undefined)
+                    continue;
+                for (const entry of body.entries) {
+                    if (entry.type !== 'assignment')
+                        continue;
+                    if (decisionTriggers.has(entry.key.value))
+                        add(blockOf(entry), 'trigger', 'country');
+                    else if (entry.key.value === 'target_trigger')
+                        add(blockOf(entry), 'trigger', UNKNOWN_SCOPE);
+                    else if (decisionEffects.has(entry.key.value))
+                        add(blockOf(entry), 'effect', 'country');
+                }
+            }
+        return { family: 'decisions', roots };
+    }
+    if (file.startsWith('common/national_focus/')) {
+        const focuses = top.flatMap((entry) => entry.key.value === 'shared_focus'
+            ? [entry]
+            : entry.key.value === 'focus_tree'
+                ? (blockOf(entry)?.entries ?? []).filter((child) => child.type === 'assignment' && child.key.value === 'focus')
+                : []);
+        for (const focus of focuses)
+            for (const entry of blockOf(focus)?.entries ?? []) {
+                if (entry.type !== 'assignment')
+                    continue;
+                if (focusTriggers.has(entry.key.value))
+                    add(blockOf(entry), 'trigger', 'country');
+                else if (focusEffects.has(entry.key.value))
+                    add(blockOf(entry), 'effect', 'country');
+            }
+        return { family: 'national_focus', roots };
+    }
+    if (file.startsWith('common/scripted_effects/') || file.startsWith('common/scripted_triggers/')) {
+        const kind = file.startsWith('common/scripted_effects/') ? 'effect' : 'trigger';
+        for (const helper of top)
+            add(blockOf(helper), kind, UNKNOWN_SCOPE);
+        return { family: kind === 'effect' ? 'scripted_effects' : 'scripted_triggers', roots };
+    }
+    if (file.startsWith('common/on_actions/')) {
+        for (const container of top)
+            for (const action of blockOf(container)?.entries ?? [])
+                for (const entry of blockOf(action)?.entries ?? [])
+                    if (entry.type === 'assignment' && entry.key.value === 'effect')
+                        add(blockOf(entry), 'effect', UNKNOWN_SCOPE);
+        return { family: 'on_actions', roots };
+    }
+    return { family: 'unsupported', roots };
+}
 const booleanCommands = new Set(['AND', 'OR', 'NOT', 'XOR', 'NAND', 'NOR']);
 const containers = new Set([
     'and',
@@ -24,14 +173,21 @@ const iteratorParameters = new Set([
     'count',
 ]);
 /** Check only rules explicitly available from one selected documentation authority. */
-export async function validateScript(references, workspace, input, signal) {
-    if (Buffer.byteLength(input.source, 'utf8') > 64_000)
+export async function validateScript(references, workspace, input, signal, file) {
+    if (file === undefined && Buffer.byteLength(input.source ?? '', 'utf8') > 64_000)
         throw new ServiceError('SCRIPT_SOURCE_TOO_LARGE', 'Snippet exceeds 64000 UTF-8 bytes');
     const inventory = await references.inventory(workspace, signal, [input.documentation]);
     const catalogs = { effect: new Map(), trigger: new Map() };
     const sources = new Map();
+    const dynamicVariables = new Set();
+    // Generic triggers such as `building_count_trigger` are written with a listed name as the
+    // key (`arms_factory > 2`); each listed name checks as that documented trigger.
+    const implicitNames = new Map();
     for (const section of inventory.sections) {
         const filename = path.basename(section.path).toLowerCase();
+        if (filename === 'dynamic_variables_documentation.md' &&
+            /^[a-z_][a-z0-9_]{0,255}$/u.test(section.heading))
+            dynamicVariables.add(section.heading);
         const match = /^(effects?|triggers?)_(?:documentation|docs)\.(?:md|log)$/u.exec(filename);
         if (match === null)
             continue;
@@ -48,6 +204,12 @@ export async function validateScript(references, workspace, input, signal) {
                 .filter(Boolean)),
         ].sort();
         const kind = match[1].startsWith('effect') ? 'effect' : 'trigger';
+        const body = section.lines.join('\n');
+        const listed = /^Supported (?!Scopes|Targets)[A-Za-z ]+:\s*([a-z0-9_,\s]+?)\.?\s*$/mu.exec(body);
+        if (kind === 'trigger' && listed !== null && /^Usage:\s*<[A-Za-z]+>/mu.test(body))
+            for (const name of listed[1].split(/[,\s]+/u).filter(Boolean))
+                if (!implicitNames.has(name))
+                    implicitNames.set(name, section.heading);
         const previous = catalogs[kind].get(section.heading);
         const reference = publicReferenceSection(section);
         if (previous !== undefined) {
@@ -56,7 +218,15 @@ export async function validateScript(references, workspace, input, signal) {
         else
             catalogs[kind].set(section.heading, { reference, scopes, conflict: false });
     }
-    const document = parseClausewitz(Buffer.from(input.source, 'utf8'), 'snippet');
+    for (const [name, heading] of [...implicitNames, ...(file?.implicitTriggers ?? [])]) {
+        const signature = catalogs.trigger.get(heading);
+        if (signature !== undefined && !catalogs.trigger.has(name))
+            catalogs.trigger.set(name, signature);
+    }
+    const documentPath = file?.path ?? 'snippet';
+    const document = parseClausewitz(file?.bytes ?? Buffer.from(input.source ?? '', 'utf8'), documentPath);
+    const commandLimit = file === undefined ? MAX_COMMANDS : MAX_FILE_COMMANDS;
+    let rootScope = input.scope ?? UNKNOWN_SCOPE;
     const findings = [];
     let visited = 0;
     let checkedCommands = 0;
@@ -71,7 +241,11 @@ export async function validateScript(references, workspace, input, signal) {
         bindings.set(binding.name, binding.scope);
     }
     const report = (entry, kind, scope, details) => {
-        const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+        const position = locationFor(documentPath, document.lineIndex, entry.start, entry.end).start;
+        // A file check lists only problems; matching commands are counted, not itemized.
+        if (file !== undefined &&
+            (details.status === 'supported' || details.code === 'SCRIPT_ARGUMENT_BLOCK_UNCHECKED'))
+            return;
         findings.push({
             ...details,
             command: entry.key.value.slice(0, 256),
@@ -86,8 +260,8 @@ export async function validateScript(references, workspace, input, signal) {
             code: diagnostic.code,
             status: 'error',
             command: '',
-            kind: input.kind,
-            scope: input.scope,
+            kind: input.kind ?? 'effect',
+            scope: input.scope ?? UNKNOWN_SCOPE,
             line: diagnostic.location?.start.line ?? 1,
             column: diagnostic.location?.start.column ?? 1,
             message: diagnostic.message.slice(0, 500),
@@ -96,11 +270,11 @@ export async function validateScript(references, workspace, input, signal) {
     const walk = (block, kind, scope, previous) => {
         for (const entry of block.entries) {
             signal?.throwIfAborted();
-            if (++visited > MAX_COMMANDS) {
+            if (++visited > commandLimit) {
                 return;
             }
             if (entry.type !== 'assignment') {
-                const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+                const position = locationFor(documentPath, document.lineIndex, entry.start, entry.end).start;
                 findings.push({
                     code: 'SCRIPT_EXPECTED_COMMAND',
                     status: 'error',
@@ -119,7 +293,7 @@ export async function validateScript(references, workspace, input, signal) {
                 continue;
             const name = booleanCommands.has(raw) ? raw.toLowerCase() : raw;
             const explicitScope = raw === 'ROOT'
-                ? input.scope
+                ? rootScope
                 : raw === 'THIS'
                     ? scope
                     : raw === 'PREV'
@@ -136,8 +310,57 @@ export async function validateScript(references, workspace, input, signal) {
                 walk(entry.value, kind, explicitScope ?? fixedScope, scope);
                 continue;
             }
+            const link = entry.value.type === 'block' ? scopeLinks[raw.toLowerCase()] : undefined;
+            if (link !== undefined && entry.value.type === 'block') {
+                checkedCommands++;
+                if (scope !== UNKNOWN_SCOPE && !link.from.includes(scope))
+                    report(entry, kind, scope, {
+                        code: 'SCRIPT_SCOPE_LINK_WRONG_SCOPE',
+                        status: 'error',
+                        message: `${raw} is usable only within ${link.from.join(', ')} scope`,
+                        suggestions: [],
+                    });
+                walk(entry.value, kind, link.to, scope);
+                continue;
+            }
+            // A file has no caller to declare FROM, chained links or targets; their blocks are
+            // still checked for command kinds, without scope rules.
+            if (file !== undefined &&
+                entry.value.type === 'block' &&
+                (/^(?:root|this|prev|from)(?:\.(?:root|this|prev|from))*$/iu.test(raw) ||
+                    /^(?:event_target|var|mio|sp):/u.test(raw))) {
+                const keyword = raw.toUpperCase();
+                walk(entry.value, kind, keyword === 'ROOT'
+                    ? rootScope
+                    : keyword === 'THIS'
+                        ? scope
+                        : keyword === 'PREV'
+                            ? (previous ?? UNKNOWN_SCOPE)
+                            : UNKNOWN_SCOPE, scope);
+                continue;
+            }
             const signature = catalogs[kind].get(name);
-            if (signature === undefined) {
+            if (signature === undefined && file?.helpers[kind].has(name) === true) {
+                // A scripted helper of the mod; its own file is checked separately.
+                checkedCommands++;
+                continue;
+            }
+            // Only a scalar comparison (`num_owned_states > 1`) misuses a dynamic variable; a block
+            // with that key is a scope or helper the catalog does not describe.
+            if (signature === undefined &&
+                kind === 'trigger' &&
+                entry.value.type !== 'block' &&
+                dynamicVariables.has(name)) {
+                report(entry, kind, scope, {
+                    code: 'SCRIPT_DYNAMIC_VARIABLE_AS_TRIGGER',
+                    status: 'error',
+                    message: `${name} is a documented dynamic variable, not a trigger; compare it with check_variable`,
+                    suggestions: ['check_variable'],
+                });
+                continue;
+            }
+            // else_if and else are control flow even where the documentation lists only `if`.
+            if (signature === undefined && !conditionals.has(name) && !containers.has(name)) {
                 const other = catalogs[kind === 'effect' ? 'trigger' : 'effect'].get(name);
                 const suggestions = name.length > 128
                     ? []
@@ -161,22 +384,26 @@ export async function validateScript(references, workspace, input, signal) {
                 continue;
             }
             checkedCommands++;
-            const wrongScope = !signature.scopes.includes('any') && !signature.scopes.includes(scope);
-            report(entry, kind, scope, {
-                code: signature.conflict
-                    ? 'SCRIPT_DOCUMENTATION_CONFLICT'
-                    : wrongScope
-                        ? 'SCRIPT_COMMAND_WRONG_SCOPE'
-                        : 'SCRIPT_COMMAND_SUPPORTED',
-                status: signature.conflict ? 'unresolved' : wrongScope ? 'error' : 'supported',
-                suggestions: [],
-                reference: signature.reference,
-                message: signature.conflict
-                    ? 'Conflicting supported scopes in the selected documentation'
-                    : wrongScope
-                        ? `Supported scopes: ${signature.scopes.join(', ')}`
-                        : 'Command kind and declared scope match the selected documentation',
-            });
+            if (signature !== undefined) {
+                const wrongScope = scope !== UNKNOWN_SCOPE &&
+                    !signature.scopes.includes('any') &&
+                    !signature.scopes.includes(scope);
+                report(entry, kind, scope, {
+                    code: signature.conflict
+                        ? 'SCRIPT_DOCUMENTATION_CONFLICT'
+                        : wrongScope
+                            ? 'SCRIPT_COMMAND_WRONG_SCOPE'
+                            : 'SCRIPT_COMMAND_SUPPORTED',
+                    status: signature.conflict ? 'unresolved' : wrongScope ? 'error' : 'supported',
+                    suggestions: [],
+                    reference: signature.reference,
+                    message: signature.conflict
+                        ? 'Conflicting supported scopes in the selected documentation'
+                        : wrongScope
+                            ? `Supported scopes: ${signature.scopes.join(', ')}`
+                            : 'Command kind and declared scope match the selected documentation',
+                });
+            }
             const iterator = /^(?:every|random|any|all)_(?:(?:owned|controlled|neighbor)_)?(state|country)$/u.exec(name);
             if (entry.value.type !== 'block') {
                 if (containers.has(name) || conditionals.has(name) || iterator !== null)
@@ -185,7 +412,7 @@ export async function validateScript(references, workspace, input, signal) {
                         status: 'error',
                         message: 'This control command requires a block',
                         suggestions: [],
-                        reference: signature.reference,
+                        ...(signature === undefined ? {} : { reference: signature.reference }),
                     });
                 continue;
             }
@@ -223,25 +450,70 @@ export async function validateScript(references, workspace, input, signal) {
                     status: 'unresolved',
                     message: 'Native argument block is not validated from prose documentation; read the cited syntax before use',
                     suggestions: [],
-                    reference: signature.reference,
+                    ...(signature === undefined ? {} : { reference: signature.reference }),
                 });
             }
         }
     };
+    const plan = file === undefined
+        ? {
+            family: 'snippet',
+            roots: [{ block: document.root, kind: input.kind, scope: input.scope }],
+        }
+        : scriptRoots(file.relativePath, document);
     if (document.diagnostics.every(({ severity }) => severity !== 'error' && severity !== 'blocker'))
-        walk(document.root, input.kind, input.scope);
+        for (const root of plan.roots) {
+            rootScope = root.scope;
+            walk(root.block, root.kind, root.scope);
+        }
+    const playerText = plan.family === 'snippet' ? undefined : file?.playerText;
+    const playerTextChecked = playerText !== undefined;
+    const eventPopups = plan.family === 'snippet' ? undefined : file?.eventPopups;
+    const warnings = [
+        ...(playerText === undefined ? [] : playerTextFindings(plan.family, document, playerText)),
+        ...(eventPopups === undefined ? [] : repeatedPopupFindings(document, eventPopups)),
+    ];
+    for (const finding of warnings) {
+        const position = playerTextPosition(documentPath, document.lineIndex, finding);
+        findings.push({
+            code: finding.code,
+            status: 'warning',
+            command: finding.command.slice(0, 256),
+            kind: finding.code === 'SCRIPT_FLAG_TOOLTIP_UNLOCALISED'
+                ? 'trigger'
+                : finding.code === 'SCRIPT_EVENT_POPUP_REPEATED'
+                    ? 'effect'
+                    : 'text',
+            scope: UNKNOWN_SCOPE,
+            line: position.line,
+            column: position.column,
+            message: finding.message,
+            suggestions: [],
+        });
+    }
     const unresolvedCount = findings.filter(({ status }) => status === 'unresolved').length;
     const invalid = findings.some(({ status }) => status === 'error');
-    const truncated = visited > MAX_COMMANDS;
-    const incomplete = unresolvedCount > 0 || truncated || inventory.skipped > 0 || catalogs[input.kind].size === 0;
-    const order = { error: 0, unresolved: 1, supported: 2 };
+    const truncated = visited > commandLimit;
+    const unknownScopeRoots = plan.roots.filter(({ scope }) => scope === UNKNOWN_SCOPE).length;
+    const incomplete = unresolvedCount > 0 ||
+        truncated ||
+        inventory.skipped > 0 ||
+        (file === undefined ? catalogs[input.kind].size === 0 : plan.roots.length === 0) ||
+        unknownScopeRoots > 0;
+    const order = { error: 0, unresolved: 1, warning: 2, supported: 3 };
     findings.sort((a, b) => order[a.status] - order[b.status] ||
         a.line - b.line ||
         a.column - b.column ||
         a.code.localeCompare(b.code, 'en'));
     const result = {
         valid: invalid ? false : incomplete ? null : true,
-        checksPerformed: ['syntax', 'command_kind', 'declared_scope'],
+        checksPerformed: [
+            'syntax',
+            'command_kind',
+            'declared_scope',
+            ...(playerTextChecked ? ['player_text'] : []),
+            ...(eventPopups === undefined ? [] : ['event_popups']),
+        ],
         parametersChecked: false,
         documentation: {
             source: input.documentation,
@@ -257,6 +529,16 @@ export async function validateScript(references, workspace, input, signal) {
         unresolvedCount,
         truncated,
         argumentBlocksUnchecked,
+        ...(file === undefined
+            ? {}
+            : {
+                file: {
+                    path: file.path,
+                    family: plan.family,
+                    roots: plan.roots.length,
+                    unknownScopeRoots,
+                },
+            }),
     };
     while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 16_000 && result.findings.length > 1)
         result.findings.pop();

package/dist/hoi4_agent_tools/reference/source-locate.js

@@ -19,7 +19,7 @@ function samePath(left, right) {
     return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 /** Resolve a display, relative, or absolute path to one scanned file, preferring the active layer. */
-function selectFile(snapshot, requested) {
+export function selectFile(snapshot, requested) {
     const normalized = requested.replaceAll('\\', '/').replace(/^\.\//u, '');
     const absolute = path.isAbsolute(requested) ? path.resolve(requested) : undefined;
     const candidates = [...snapshot.index.files.values()].filter((file) => file.displayPath === normalized ||

package/dist/hoi4_agent_tools/schemas/gui-requests.js

@@ -8,7 +8,21 @@ import { backgroundRequestKeySchema, workspaceIdSchema, workspaceRelativePathSch
 function compact(schema, description) {
     return z.unknown().describe(description).pipe(schema);
 }
-const compactGuiScenarioSchema = compact(GuiPreviewScenarioSchema, 'GUI preview scenario; optional date and controls {stateId: controllerTag}.');
+/**
+ * Published scenario shape: the required `id` and the fields that decide visibility, with the
+ * rest named in the description. Every field is validated by the full scenario schema.
+ */
+const compactGuiScenarioSchema = z
+    .looseObject({
+    id: z.string(),
+    date: z.string().optional(),
+    closedFlags: z.boolean().optional(),
+})
+    .describe('Also flags {name: bool}, variables {name: number}, controls {stateId: tag}, values, visibility (docs/gui.md). closedFlags: undeclared flags are unset.')
+    .transform((value) => value)
+    .pipe(GuiPreviewScenarioSchema);
+/** Related and comparison scenarios repeat the primary scenario's published shape. */
+const compactRelatedScenarioSchema = compact(GuiPreviewScenarioSchema, 'Same shape as scenario.');
 const compactGeneratedScenarioOptionsSchema = compact(GuiGeneratedScenarioOptionsSchema, 'GUI generated-scenario options.');
 const compactGuiHelperSchema = compact(GuiHelperDocumentSchema, 'GUI helper document.');
 export const guiPreviewStateSchema = z.enum([
@@ -32,7 +46,7 @@ export const guiInspectRequestSchema = z
     workspaceId: workspaceIdSchema,
     windowName: z.string().min(1).max(256).optional(),
     scenario: compactGuiScenarioSchema.optional(),
-    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    relatedScenarios: z.array(compactRelatedScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
 })
     .strict()
@@ -79,9 +93,9 @@ export const guiRenderRequestSchema = z
     scenario: compactGuiScenarioSchema,
     states: z.array(guiPreviewStateSchema).max(14).optional(),
     resolutions: z.array(guiResolutionSchema).min(1).max(16).optional(),
-    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    relatedScenarios: z.array(compactRelatedScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
-    comparisonScenario: compactGuiScenarioSchema.optional(),
+    comparisonScenario: compactRelatedScenarioSchema.optional(),
     sourceBaseline: z
         .object({
         relativePath: workspaceRelativePathSchema,

package/dist/hoi4_agent_tools/schemas/script-validation.js

@@ -18,9 +18,12 @@ const scope = z.enum([
 export const scriptValidateRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
-    source: z.string().min(1).max(64_000),
-    kind: z.enum(['effect', 'trigger']),
-    scope,
+    /** Snippet mode: an effect or trigger body checked under `kind` and `scope`. */
+    source: z.string().min(1).max(64_000).optional(),
+    /** File mode: a scanned mod file whose blocks are checked under the scope its structure fixes. */
+    path: z.string().trim().min(1).max(4096).optional(),
+    kind: z.enum(['effect', 'trigger']).optional(),
+    scope: scope.optional(),
     documentation: z.enum(['game_doc', 'script_doc']).default('game_doc'),
     bindings: z
         .array(z.object({ name: z.string().min(1).max(256), scope }).strict())
@@ -28,11 +31,32 @@ export const scriptValidateRequestSchema = z
         .default([]),
     limit: z.number().int().min(1).max(32).default(12),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    if ((value.source === undefined) === (value.path === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['source'],
+            message: 'Provide either source with kind and scope, or a mod file path',
+        });
+    if (value.source !== undefined && (value.kind === undefined || value.scope === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['kind'],
+            message: 'A snippet check requires kind and scope',
+        });
+    if (value.path !== undefined &&
+        (value.kind !== undefined || value.scope !== undefined || value.bindings.length > 0))
+        context.addIssue({
+            code: 'custom',
+            path: ['path'],
+            message: 'A file check infers kinds and scopes from the file structure',
+        });
+});
 export const scriptValidateDataSchema = z
     .object({
     valid: z.boolean().nullable(),
-    checksPerformed: z.array(z.enum(['syntax', 'command_kind', 'declared_scope'])),
+    checksPerformed: z.array(z.enum(['syntax', 'command_kind', 'declared_scope', 'player_text', 'event_popups'])),
     parametersChecked: z.literal(false),
     documentation: z
         .object({
@@ -47,9 +71,9 @@ export const scriptValidateDataSchema = z
         .array(z
         .object({
         code: z.string().max(80),
-        status: z.enum(['supported', 'error', 'unresolved']),
+        status: z.enum(['supported', 'error', 'unresolved', 'warning']),
         command: z.string().max(256),
-        kind: z.enum(['effect', 'trigger']),
+        kind: z.enum(['effect', 'trigger', 'text']),
         scope: z.string().max(64),
         line: z.number().int().min(1),
         column: z.number().int().min(1),
@@ -65,5 +89,14 @@ export const scriptValidateDataSchema = z
     unresolvedCount: z.number().int().min(0),
     truncated: z.boolean(),
     argumentBlocksUnchecked: z.number().int().min(0),
+    file: z
+        .object({
+        path: z.string().max(4096),
+        family: z.string().max(64),
+        roots: z.number().int().min(0),
+        unknownScopeRoots: z.number().int().min(0),
+    })
+        .strict()
+        .optional(),
 })
     .strict();

package/dist/hoi4_agent_tools/schemas/technology.js

@@ -143,14 +143,16 @@ export const technologyRenderRequestSchema = z
     refresh: z.boolean().optional(),
 })
     .strict()
-    .superRefine((value, context) => {
+    .superRefine(validateTechnologyRenderRequest);
+/** Shared by the request schema and the published tool input, so clients see the same rule. */
+export function validateTechnologyRenderRequest(value, context) {
     if (value.view === 'folder' && value.folderId === undefined)
         context.addIssue({
             code: 'custom',
             path: ['folderId'],
             message: 'Folder view requires folderId',
         });
-});
+}
 export function validateTechnologyCompareRequest(value, context) {
     if (value.after !== undefined && value.proposedSources !== undefined)
         context.addIssue({

package/dist/hoi4_agent_tools/technology/service.js

@@ -880,6 +880,13 @@ export class TechnologyTreeViewer {
         input.signal?.throwIfAborted();
         if (input.proposedSources !== undefined)
             assertProposedBounds(input.proposedSources);
+        // Without references the comparison uses the previous cached revision; with none cached,
+        // say so before scanning the workspace.
+        if (input.before === undefined &&
+            input.after === undefined &&
+            input.proposedSources === undefined &&
+            (this.#state.history.get(input.workspaceId)?.size ?? 0) === 0)
+            throw new ServiceError('TECH_COMPARISON_BASELINE_REQUIRED', 'Provide a cached revision, graph artifact, or proposed source overlay');
         const current = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.proposedSources !== undefined,
             ...(input.principal === undefined ? {} : { principal: input.principal }),

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '3.8.1';
+export const PACKAGE_VERSION = '3.10.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;