hoi4-agent-tools 3.8.1 → 3.9.0

package/dist/hoi4_agent_tools/reference/operations.js

@@ -1,3 +1,5 @@
+import { hashCanonical } from '../core/canonical.js';
+import { parseClausewitz } from '../core/source/index.js';
 import { requireOperationScope, resolveOperationWorkspaceId, } from '../core/operation-context.js';
 import { emptyServiceResult } from '../core/result.js';
 import { toolResult } from '../core/operation-result.js';
@@ -6,6 +8,35 @@ import { ReferenceService } from './service.js';
 import { sourceLookup } from './source-lookup.js';
 import { scriptValidateDataSchema, scriptValidateRequestSchema, } from '../schemas/script-validation.js';
 import { validateScript } from './script-validation.js';
+import { eventPopupDefinitions } from './event-popups.js';
+import { locatePatterns, selectFile } from './source-locate.js';
+/**
+ * Database folders whose entry names are trigger keys: `<folder> = { <name> = { ... } }` in
+ * each file, checked as the documented generic trigger.
+ */
+const implicitTriggerSources = {
+    buildings: 'building_count_trigger',
+    ideologies: 'ideology_support_trigger',
+    resources: 'resource_count_trigger',
+};
+/** Building, ideology and resource names from every scanned source layer. */
+function implicitTriggerNames(snapshot) {
+    const names = new Map();
+    for (const file of snapshot.index.files.values()) {
+        const folder = /^common\/([a-z_]+)\/[^/]+\.txt$/u.exec(file.relativePath)?.[1];
+        const heading = folder === undefined ? undefined : implicitTriggerSources[folder];
+        if (heading === undefined)
+            continue;
+        for (const top of parseClausewitz(file.bytes, file.displayPath).root.entries) {
+            if (top.type !== 'assignment' || top.key.value !== folder || top.value.type !== 'block')
+                continue;
+            for (const entry of top.value.entries)
+                if (entry.type === 'assignment' && entry.value.type === 'block')
+                    names.set(entry.key.value, heading);
+        }
+    }
+    return names;
+}
 const schemas = {
     'hoi4.reference_search': referenceSearchRequestSchema,
     'hoi4.reference_read': referenceReadRequestSchema,
@@ -39,7 +70,7 @@ export class ReferenceToolService {
                 : name === 'hoi4.reference_context'
                     ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
                     : name === 'hoi4.script_validate'
-                        ? await validateScript(this.references, workspace, scriptValidateRequestSchema.parse(parsed), signal)
+                        ? await this.validateScript(workspaceId, workspace, scriptValidateRequestSchema.parse(parsed), context.principal, signal)
                         : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
         const result = emptyServiceResult(workspaceId, data);
         if (name === 'hoi4.script_validate') {
@@ -81,4 +112,123 @@ export class ReferenceToolService {
         }
         return toolResult(result);
     }
+    #eventPopups = new Map();
+    /** The latest player-text context of each workspace, keyed by its source files' hashes. */
+    #playerText = new Map();
+    /** File mode reads the scanned file and the mod's scripted helper names from one scan. */
+    async validateScript(workspaceId, workspace, request, principal, signal) {
+        if (request.path === undefined)
+            return validateScript(this.references, workspace, request, signal);
+        const snapshot = await this.engine.scan(workspaceId, {
+            patterns: [
+                ...(locatePatterns(this.engine, workspaceId, request.path, principal) ?? []),
+                'common/scripted_effects/**/*.txt',
+                'common/scripted_triggers/**/*.txt',
+                ...Object.keys(implicitTriggerSources).map((folder) => `common/${folder}/*.txt`),
+                // One scan serves every check: the engine keeps one snapshot per workspace.
+                ...playerTextPatterns,
+                'events/**/*.txt',
+            ],
+        }, principal, signal);
+        const file = selectFile(snapshot, request.path);
+        const playerText = playerTextFamily(file.relativePath)
+            ? this.playerTextContext(workspaceId, snapshot)
+            : undefined;
+        const helpers = (kind) => new Set(snapshot.index.symbols.filter((symbol) => symbol.kind === kind).map(({ id }) => id));
+        return validateScript(this.references, workspace, request, signal, {
+            path: file.displayPath,
+            relativePath: file.relativePath,
+            bytes: file.bytes,
+            helpers: { effect: helpers('scripted_effect'), trigger: helpers('scripted_trigger') },
+            implicitTriggers: implicitTriggerNames(snapshot),
+            ...(playerText === undefined ? {} : { playerText }),
+            eventPopups: this.eventPopupContext(workspaceId, snapshot),
+        });
+    }
+    /** Every active event definition, cached by the hashes of the events files. */
+    eventPopupContext(workspaceId, snapshot) {
+        const sources = [...snapshot.index.files.values()]
+            .filter(({ relativePath, shadowedBy }) => shadowedBy === undefined && relativePath.startsWith('events/'))
+            .sort((left, right) => left.loadOrder - right.loadOrder);
+        const cacheKey = hashCanonical(sources.map(({ displayPath, sha256 }) => [displayPath, sha256]));
+        const cached = this.#eventPopups.get(workspaceId);
+        if (cached?.key === cacheKey)
+            return cached.events;
+        const events = new Map();
+        for (const file of sources)
+            for (const [id, definition] of eventPopupDefinitions(file.bytes, file.displayPath))
+                events.set(id, definition);
+        this.#eventPopups.set(workspaceId, { key: cacheKey, events });
+        return events;
+    }
+    /** English localisation as the game resolves it, and the branches of scripted localisation. */
+    playerTextContext(workspaceId, snapshot) {
+        const sources = [...snapshot.index.files.values()].filter(({ relativePath }) => playerTextSource(relativePath));
+        const cacheKey = hashCanonical(sources.map(({ displayPath, sha256 }) => [displayPath, sha256]));
+        const cached = this.#playerText.get(workspaceId);
+        if (cached?.key === cacheKey)
+            return cached.context;
+        const localisation = new Map();
+        for (const symbol of snapshot.index.symbols) {
+            if (symbol.kind !== 'localisation' || !symbol.id.startsWith('l_english:'))
+                continue;
+            const key = symbol.id.slice('l_english:'.length);
+            const previous = localisation.get(key);
+            if (previous !== undefined && previous.loadOrder > symbol.loadOrder)
+                continue;
+            localisation.set(key, {
+                value: typeof symbol.metadata.value === 'string' ? symbol.metadata.value : '',
+                path: symbol.path,
+                line: symbol.location?.start.line ?? 1,
+                loadOrder: symbol.loadOrder,
+            });
+        }
+        const scriptedLocalisation = new Map();
+        for (const file of sources) {
+            if (!file.relativePath.startsWith('common/scripted_localisation/'))
+                continue;
+            for (const definition of parseClausewitz(file.bytes, file.displayPath).root.entries) {
+                if (definition.type !== 'assignment' ||
+                    definition.key.value !== 'defined_text' ||
+                    definition.value.type !== 'block')
+                    continue;
+                let name;
+                const keys = [];
+                for (const entry of definition.value.entries) {
+                    if (entry.type !== 'assignment')
+                        continue;
+                    if (entry.key.value === 'name' && entry.value.type === 'scalar')
+                        name = entry.value.value;
+                    if (entry.key.value !== 'text' || entry.value.type !== 'block')
+                        continue;
+                    for (const branch of entry.value.entries)
+                        if (branch.type === 'assignment' &&
+                            /^locali[sz]ation_key$/u.test(branch.key.value) &&
+                            branch.value.type === 'scalar')
+                            keys.push(branch.value.value);
+                }
+                if (name !== undefined)
+                    scriptedLocalisation.set(name, keys);
+            }
+        }
+        const context = { localisation, scriptedLocalisation };
+        this.#playerText.set(workspaceId, { key: cacheKey, context });
+        return context;
+    }
+}
+const playerTextPatterns = [
+    'localisation/**/*_l_english.yml',
+    'common/scripted_localisation/**/*.txt',
+];
+function playerTextSource(relativePath) {
+    const file = relativePath.replaceAll('\\', '/').toLowerCase();
+    return ((file.startsWith('localisation/') && file.endsWith('_l_english.yml')) ||
+        file.startsWith('common/scripted_localisation/'));
+}
+/** Files whose player-facing text and requirement tooltips file mode checks. */
+function playerTextFamily(relativePath) {
+    const file = relativePath.replaceAll('\\', '/').toLowerCase();
+    return (file.startsWith('events/') ||
+        file.startsWith('common/national_focus/') ||
+        (file.startsWith('common/decisions/') && !file.startsWith('common/decisions/categories/')));
 }

package/dist/hoi4_agent_tools/reference/player-text.js

@@ -0,0 +1,158 @@
+import { locationFor } from '../core/source/index.js';
+const flagTriggers = new Set(['has_country_flag', 'has_global_flag', 'has_state_flag']);
+/** Blocks whose triggers the game lists in requirement tooltips. */
+const tooltipTriggerBlocks = {
+    decisions: new Set(['available']),
+    national_focus: new Set(['available', 'bypass']),
+};
+/** Words that describe the mod's development rather than the game world. */
+const implementationWording = /\b(?:TODO|FIXME|TBD|hard-?coded|newly added|(?:has been|was|been) reworked|placeholder)\b/iu;
+const colourCode = /[§£]/u;
+function blockOf(entry) {
+    return entry.value.type === 'block' ? entry.value : undefined;
+}
+function scalarOf(entry) {
+    return entry.value.type === 'block' ? undefined : entry.value.value;
+}
+function assignmentsOf(block) {
+    return block.entries.filter((entry) => entry.type === 'assignment');
+}
+/** Localisation keys an event, decision or focus text field names: `key` or `{ text = key }`. */
+function textKeys(entry) {
+    const scalar = scalarOf(entry);
+    if (scalar !== undefined)
+        return [{ key: scalar, node: entry }];
+    return assignmentsOf(blockOf(entry))
+        .filter((child) => child.key.value === 'text' && scalarOf(child) !== undefined)
+        .map((child) => ({ key: scalarOf(child), node: child }));
+}
+/** Scripted localisation names a text calls, such as `GetStatus` in `[ROOT.GetStatus]`. */
+function scriptedTokens(value, context) {
+    const names = [];
+    for (const match of value.matchAll(/\[(?!\?)([A-Za-z0-9_.:]+)\]/gu)) {
+        const name = match[1].slice(match[1].lastIndexOf('.') + 1);
+        if (context.scriptedLocalisation.has(name))
+            names.push(name);
+    }
+    return names;
+}
+/**
+ * Player-facing text problems in an event, decision or focus file. News and report events
+ * carry no colour codes, directly or through scripted localisation; shown text has no
+ * development wording; and a flag trigger listed in a requirement tooltip has a localisation
+ * key, because the game prints the flag name as that tooltip's key.
+ */
+export function playerTextFindings(family, document, context) {
+    const findings = [];
+    const top = assignmentsOf(document.root);
+    const add = (node, code, message) => findings.push({
+        code,
+        command: node.key.value,
+        offset: node.start,
+        end: node.end,
+        message: message.slice(0, 500),
+    });
+    const where = (text) => `${text.path}:${text.line}`;
+    const checkText = (key, node, options) => {
+        const text = context.localisation.get(key);
+        if (text === undefined)
+            return;
+        if (implementationWording.test(text.value))
+            add(node, 'SCRIPT_TEXT_IMPLEMENTATION_WORDING', `${key} (${where(text)}) describes development rather than the game: "${implementationWording.exec(text.value)[0]}"`);
+        if (!options.colourFree)
+            return;
+        if (colourCode.test(text.value)) {
+            add(node, 'SCRIPT_NEWS_TEXT_COLOUR_CODE', `${key} (${where(text)}) uses a colour code in news or report event text`);
+            return;
+        }
+        for (const name of scriptedTokens(text.value, context))
+            for (const branchKey of context.scriptedLocalisation.get(name) ?? []) {
+                const branch = context.localisation.get(branchKey);
+                if (branch !== undefined && colourCode.test(branch.value)) {
+                    add(node, 'SCRIPT_NEWS_TEXT_COLOUR_CODE', `${key} (${where(text)}) shows [${name}], whose branch ${branchKey} (${where(branch)}) uses a colour code in news or report event text`);
+                    return;
+                }
+            }
+    };
+    if (family === 'events') {
+        for (const event of top) {
+            const body = blockOf(event);
+            if (body === undefined || !event.key.value.endsWith('_event'))
+                continue;
+            const fields = assignmentsOf(body);
+            const picture = fields.find(({ key }) => key.value === 'picture');
+            const colourFree = event.key.value === 'news_event' ||
+                /^GFX_report_event/iu.test((picture && scalarOf(picture)) ?? '');
+            for (const field of fields) {
+                if (field.key.value === 'title' || field.key.value === 'desc')
+                    for (const { key, node } of textKeys(field))
+                        checkText(key, node, { colourFree });
+                else if (field.key.value === 'option')
+                    for (const name of assignmentsOf(blockOf(field) ?? { ...body, entries: [] }))
+                        if (name.key.value === 'name' && scalarOf(name) !== undefined)
+                            checkText(scalarOf(name), name, { colourFree });
+            }
+        }
+        return findings;
+    }
+    const requirementBlocks = tooltipTriggerBlocks[family];
+    if (requirementBlocks === undefined)
+        return findings;
+    const visitTrigger = (block) => {
+        for (const entry of assignmentsOf(block)) {
+            const key = entry.key.value;
+            // These blocks hide their contents or replace them with their own tooltip.
+            if (key === 'hidden_trigger' || key === 'custom_trigger_tooltip')
+                continue;
+            if (flagTriggers.has(key)) {
+                const flag = scalarOf(entry) ??
+                    assignmentsOf(blockOf(entry))
+                        .filter(({ key: child }) => child.value === 'flag')
+                        .map(scalarOf)[0];
+                if (flag !== undefined && /^[A-Za-z0-9_]+$/u.test(flag) && !context.localisation.has(flag))
+                    add(entry, 'SCRIPT_FLAG_TOOLTIP_UNLOCALISED', `${flag} has no localisation key, so the requirement tooltip shows the raw flag name; localise it or wrap the check in hidden_trigger with a custom_trigger_tooltip`);
+                continue;
+            }
+            const child = blockOf(entry);
+            if (child !== undefined)
+                visitTrigger(child);
+        }
+    };
+    const visitDefinition = (definition, id) => {
+        const body = blockOf(definition);
+        if (body === undefined)
+            return;
+        if (id !== undefined) {
+            checkText(id, definition, { colourFree: false });
+            checkText(`${id}_desc`, definition, { colourFree: false });
+        }
+        for (const field of assignmentsOf(body)) {
+            const block = blockOf(field);
+            if (block !== undefined && requirementBlocks.has(field.key.value))
+                visitTrigger(block);
+        }
+    };
+    if (family === 'decisions') {
+        for (const category of top)
+            for (const decision of assignmentsOf(blockOf(category) ?? { ...document.root, entries: [] }))
+                visitDefinition(decision, decision.key.value);
+    }
+    else {
+        for (const entry of top) {
+            const focuses = entry.key.value === 'shared_focus'
+                ? [entry]
+                : entry.key.value === 'focus_tree'
+                    ? assignmentsOf(blockOf(entry) ?? { ...document.root, entries: [] }).filter(({ key }) => key.value === 'focus')
+                    : [];
+            for (const focus of focuses) {
+                const id = assignmentsOf(blockOf(focus) ?? { ...document.root, entries: [] }).find(({ key }) => key.value === 'id');
+                visitDefinition(focus, id === undefined ? undefined : scalarOf(id));
+            }
+        }
+    }
+    return findings;
+}
+/** Line and column of a finding in the checked file. */
+export function playerTextPosition(path, lineIndex, finding) {
+    return locationFor(path, lineIndex, finding.offset, finding.end).start;
+}