hoi4-agent-tools 3.10.0 → 4.0.0

package/dist/hoi4_agent_tools/reference/known-mistakes.js

@@ -0,0 +1,307 @@
+import { z } from 'zod/v4';
+import rulesFile from './known-mistakes.json' with { type: 'json' };
+/**
+ * Known mistakes: a reviewed, source-cited list of script errors that the game accepts silently
+ * or reports with an unhelpful message. The list ships with the server as `known-mistakes.json`;
+ * it is changed only by reviewed edits to that file, never at run time. Each active rule has a
+ * detector below that flags the mistake in a checked file, and a rule that no longer applies
+ * stays in the file as `resolved` with the reason, so the history is kept and it is no longer
+ * applied.
+ */
+const sourceSchema = z
+    .object({
+    kind: z.enum(['wiki', 'game_doc']),
+    page: z.string().min(1),
+    heading: z.string().min(1),
+    item: z.string().min(1),
+})
+    .strict();
+const ruleSchema = z
+    .object({
+    id: z.string().regex(/^[a-z][a-z0-9_]{2,63}$/u),
+    status: z.enum(['active', 'resolved']),
+    severity: z.enum(['error', 'warning']),
+    surfaces: z
+        .array(z.enum([
+        'event',
+        'decision',
+        'idea',
+        'focus',
+        'technology',
+        'gui',
+        'map',
+        'localisation',
+        'ai',
+    ]))
+        .min(1),
+    title: z.string().min(1).max(120),
+    mistake: z.string().min(1).max(300),
+    symptom: z.string().min(1).max(400),
+    fix: z.string().min(1).max(300),
+    sources: z.array(sourceSchema).min(1),
+    /** A regular expression for the game's own log message about the mistake. */
+    logPattern: z.string().min(1).max(200).optional(),
+    /** Required when `status` is `resolved`: why the rule no longer applies. */
+    resolution: z
+        .object({ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/u), note: z.string().min(1).max(300) })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((rule, context) => {
+    if ((rule.status === 'resolved') !== (rule.resolution !== undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['resolution'],
+            message: 'A resolved rule needs a resolution; an active rule must not have one',
+        });
+});
+const rulesSchema = z
+    .object({
+    version: z.literal(1),
+    reviewed: z.string().regex(/^\d{4}-\d{2}-\d{2}$/u),
+    rules: z.array(ruleSchema).min(1),
+})
+    .strict();
+/** The reviewed rule list, validated once; a malformed file fails when the server loads. */
+export const knownMistakeRules = rulesSchema.parse(rulesFile).rules;
+/** Rules that are applied: resolved rules stay in the file as history only. */
+export function activeKnownMistakes(surface, rules = knownMistakeRules) {
+    return rules.filter((rule) => rule.status === 'active' &&
+        (surface === undefined || surface === 'general' || rule.surfaces.some((s) => s === surface)));
+}
+/** The rule whose logged message `message` is, so a log entry can name its documented fix. */
+export function knownMistakeForLogMessage(message, rules = knownMistakeRules) {
+    return activeKnownMistakes(undefined, rules).find((rule) => rule.logPattern !== undefined && new RegExp(rule.logPattern, 'iu').test(message));
+}
+function assignmentsOf(block) {
+    return block.entries.filter((entry) => entry.type === 'assignment');
+}
+function field(block, key) {
+    return assignmentsOf(block).find((entry) => entry.key.value === key);
+}
+function scalarField(block, key) {
+    const entry = field(block, key);
+    return entry?.value.type === 'scalar' ? entry.value.value : undefined;
+}
+const eventKeys = new Set([
+    'country_event',
+    'news_event',
+    'state_event',
+    'unit_leader_event',
+    'operative_leader_event',
+]);
+/** The event definitions of a file: the assignment, its block and its id. */
+function eventsOf(document) {
+    const events = [];
+    for (const node of assignmentsOf(document.root))
+        if (eventKeys.has(node.key.value) && node.value.type === 'block')
+            events.push({ node, body: node.value, id: scalarField(node.value, 'id') });
+    return events;
+}
+/** `days` of a `mean_time_to_happen` block when it is a plain number. */
+function baseMeanDays(timer) {
+    if (timer.value.type !== 'block')
+        return undefined;
+    const days = scalarField(timer.value, 'days');
+    const months = scalarField(timer.value, 'months');
+    const years = scalarField(timer.value, 'years');
+    const unit = (value, factor) => value === undefined ? 0 : /^-?\d+(?:\.\d+)?$/u.test(value) ? Number(value) * factor : undefined;
+    const parts = [unit(days, 1), unit(months, 30), unit(years, 365)];
+    let total = 0;
+    for (const part of parts) {
+        if (part === undefined)
+            return undefined;
+        total += part;
+    }
+    return total;
+}
+/** Days from a `Y.M.D` or `Y.M.D.H` date, ignoring leap days as the game does. */
+function dayNumber(date) {
+    const match = /^(\d{1,4})\.(\d{1,2})\.(\d{1,2})(?:\.\d{1,2})?$/u.exec(date);
+    if (match === null)
+        return undefined;
+    const monthDays = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334];
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    if (month < 1 || month > 12)
+        return undefined;
+    return year * 365 + monthDays[month - 1] + day;
+}
+/** Date bounds directly inside a trigger block, with `OR`/`NOT` branches left out. */
+function dateBounds(trigger) {
+    const bounds = {};
+    for (const entry of assignmentsOf(trigger)) {
+        if (entry.key.value !== 'date' || entry.value.type !== 'scalar')
+            continue;
+        const day = dayNumber(entry.value.value);
+        if (day === undefined)
+            continue;
+        if (entry.operator.text === '>' || entry.operator.text === '>=')
+            bounds.lower = Math.max(bounds.lower ?? day, day);
+        else if (entry.operator.text === '<' || entry.operator.text === '<=')
+            bounds.upper = Math.min(bounds.upper ?? day, day);
+    }
+    return bounds;
+}
+const TRIGGER_CHECK_DAYS = 20;
+const detectors = {
+    event_triggered_only_with_mtth: (document) => eventsOf(document).flatMap(({ body }) => {
+        const timer = field(body, 'mean_time_to_happen');
+        return timer !== undefined && scalarField(body, 'is_triggered_only') === 'yes'
+            ? [{ node: timer }]
+            : [];
+    }),
+    event_fires_every_day: (document) => eventsOf(document).flatMap(({ node, body }) => {
+        if (scalarField(body, 'is_triggered_only') === 'yes')
+            return [];
+        if (scalarField(body, 'fire_only_once') === 'yes')
+            return [];
+        const timer = field(body, 'mean_time_to_happen');
+        if (timer === undefined)
+            return [{ node }];
+        const days = baseMeanDays(timer);
+        return days !== undefined && days <= 1 ? [{ node: timer }] : [];
+    }),
+    news_event_not_major: (document) => eventsOf(document).flatMap(({ node, body }) => {
+        if (node.key.value !== 'news_event')
+            return [];
+        if (scalarField(body, 'major') !== 'yes')
+            return [{ node }];
+        const once = field(body, 'fire_only_once');
+        return once !== undefined && scalarField(body, 'fire_only_once') === 'yes'
+            ? [{ node: once }]
+            : [];
+    }),
+    event_date_window_too_tight: (document) => eventsOf(document).flatMap(({ body }) => {
+        if (scalarField(body, 'is_triggered_only') === 'yes')
+            return [];
+        const trigger = field(body, 'trigger');
+        if (trigger?.value.type !== 'block')
+            return [];
+        const { lower, upper } = dateBounds(trigger.value);
+        return lower !== undefined && upper !== undefined && upper - lower < TRIGGER_CHECK_DAYS
+            ? [{ node: trigger }]
+            : [];
+    }),
+    event_namespace_missing: (document, _family, context) => {
+        const declared = new Set(context.eventNamespaces ?? []);
+        for (const node of assignmentsOf(document.root))
+            if (node.key.value === 'add_namespace' && node.value.type === 'scalar')
+                declared.add(node.value.value);
+        return eventsOf(document).flatMap(({ body, id }) => {
+            const idNode = field(body, 'id');
+            const dot = id?.lastIndexOf('.') ?? -1;
+            if (idNode === undefined || id === undefined || dot < 1)
+                return [];
+            const namespace = id.slice(0, dot);
+            return declared.has(namespace)
+                ? []
+                : [
+                    {
+                        node: idNode,
+                        message: `${id} uses namespace ${namespace}, which no events file declares with add_namespace`,
+                    },
+                ];
+        });
+    },
+    event_numeric_id_invalid: (document) => eventsOf(document).flatMap(({ body, id }) => {
+        const idNode = field(body, 'id');
+        const dot = id?.lastIndexOf('.') ?? -1;
+        if (idNode === undefined || id === undefined || dot < 1)
+            return [];
+        const number = id.slice(dot + 1);
+        if (/^\d+$/u.test(number) && Number(number) < 100_000)
+            return [];
+        return [
+            {
+                node: idNode,
+                message: `${id} ends in "${number}", which is not a whole number from 0 to 99999`,
+            },
+        ];
+    }),
+    temp_variable_scope_prefix: (document) => {
+        const temporary = new Set();
+        const regular = new Set();
+        const names = [];
+        const setters = /^(?:set|add_to|subtract_from|multiply|divide|modulo|round|clamp|set_to_random|clear)_(temp_)?variable$/u;
+        const visit = (block) => {
+            for (const entry of block.entries) {
+                if (entry.type === 'block') {
+                    visit(entry);
+                    continue;
+                }
+                if (entry.type !== 'assignment')
+                    continue;
+                const setter = setters.exec(entry.key.value);
+                if (setter !== null && entry.value.type === 'block')
+                    for (const child of assignmentsOf(entry.value)) {
+                        if (child.key.value === 'var' && child.value.type === 'scalar')
+                            (setter[1] === undefined ? regular : temporary).add(child.value.value);
+                        else if (child.key.value !== 'value' &&
+                            child.key.value !== 'tooltip' &&
+                            child.key.value !== 'min' &&
+                            child.key.value !== 'max' &&
+                            child.key.value !== 'integer')
+                            (setter[1] === undefined ? regular : temporary).add(child.key.value);
+                    }
+                else if (setter !== null && entry.value.type === 'scalar')
+                    (setter[1] === undefined ? regular : temporary).add(entry.value.value);
+                if (entry.value.type === 'scalar' && entry.value.value.includes('.'))
+                    names.push({ node: entry, token: entry.value.value });
+                if (entry.value.type === 'block')
+                    visit(entry.value);
+            }
+        };
+        visit(document.root);
+        const findings = [];
+        for (const { node, token } of names) {
+            const name = token.slice(token.lastIndexOf('.') + 1);
+            if (!temporary.has(name) || regular.has(name))
+                continue;
+            if (!/^(?:[A-Za-z_][\w]*|[a-z_]+:[\w]+)(?:\.[A-Za-z_][\w]*)+$/u.test(token))
+                continue;
+            findings.push({
+                node,
+                message: `${token} reads the temporary variable ${name} through a scope; temporary variables are unscoped, so read ${name} directly`,
+            });
+        }
+        return findings;
+    },
+};
+/** The rule ids that have a detector. */
+export const knownMistakeDetectorIds = Object.keys(detectors);
+/** The families each rule's detector runs in; others do not hold the construct. */
+const ruleFamilies = {
+    event_triggered_only_with_mtth: ['events'],
+    event_fires_every_day: ['events'],
+    news_event_not_major: ['events'],
+    event_date_window_too_tight: ['events'],
+    event_namespace_missing: ['events'],
+    event_numeric_id_invalid: ['events'],
+    temp_variable_scope_prefix: 'any',
+};
+/**
+ * Flags the known mistakes in one checked file. Resolved rules are not applied. Each finding
+ * names the rule, the symptom and the documented fix, in the finding's own message.
+ */
+export function knownMistakeFindings(family, document, context = {}, rules = knownMistakeRules) {
+    const findings = [];
+    for (const rule of activeKnownMistakes(undefined, rules)) {
+        const detector = detectors[rule.id];
+        const families = ruleFamilies[rule.id];
+        if (detector === undefined || families === undefined)
+            continue;
+        if (families !== 'any' && !families.includes(family))
+            continue;
+        for (const hit of detector(document, family, context))
+            findings.push({
+                code: `KNOWN_MISTAKE_${rule.id.toUpperCase()}`,
+                command: hit.node.key.value,
+                offset: hit.node.start,
+                end: hit.node.end,
+                message: `${hit.message ?? rule.title}. ${rule.symptom} Fix: ${rule.fix}`.slice(0, 500),
+                rule,
+            });
+    }
+    return findings;
+}

package/dist/hoi4_agent_tools/reference/known-mistakes.json

@@ -0,0 +1,154 @@
+{
+    "version": 1,
+    "reviewed": "2026-10-10",
+    "rules": [
+        {
+            "id": "event_triggered_only_with_mtth",
+            "status": "active",
+            "severity": "warning",
+            "surfaces": ["event"],
+            "title": "mean_time_to_happen on a triggered-only event",
+            "mistake": "The event sets is_triggered_only = yes and also mean_time_to_happen.",
+            "symptom": "The game logs \"Event is triggered only, but does not have a 1 base-factor\", and the timer never runs.",
+            "fix": "Remove mean_time_to_happen, or remove is_triggered_only if the event is meant to fire by itself.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unintuitive logged errors",
+                    "item": "Event is triggered only, but does not have a 1 base-factor."
+                }
+            ],
+            "logPattern": "Event is triggered only, but does not have a 1 base-factor"
+        },
+        {
+            "id": "event_fires_every_day",
+            "status": "active",
+            "severity": "warning",
+            "surfaces": ["event"],
+            "title": "Automatic event with a one-day timer",
+            "mistake": "The event can fire by itself, can repeat, and has no mean_time_to_happen or one of 1 day or less.",
+            "symptom": "The game logs \"Event is set to trigger every day\"; once its trigger is true the event can fire daily.",
+            "fix": "Add is_triggered_only = yes and fire the event from an effect or on action, add fire_only_once = yes, or give it a longer mean_time_to_happen.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unintuitive logged errors",
+                    "item": "Event is set to trigger every day."
+                }
+            ],
+            "logPattern": "Event is set to trigger every day"
+        },
+        {
+            "id": "news_event_not_major",
+            "status": "active",
+            "severity": "warning",
+            "surfaces": ["event"],
+            "title": "News event that reaches one country",
+            "mistake": "A news_event lacks major = yes, or combines major = yes with fire_only_once = yes.",
+            "symptom": "Only the first country receives the news event; fire_only_once cancels the effect of major.",
+            "fix": "Set major = yes and remove fire_only_once. Use show_major to limit which countries see it.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unlogged errors",
+                    "item": "Setting a news event to fire only once or not setting one as major"
+                }
+            ]
+        },
+        {
+            "id": "event_date_window_too_tight",
+            "status": "active",
+            "severity": "warning",
+            "surfaces": ["event"],
+            "title": "Date window shorter than the 20-day trigger check",
+            "mistake": "An event that fires by itself bounds date on both sides less than 20 days apart in its trigger.",
+            "symptom": "The trigger is checked about every 20 days, so the window can fall between two checks and the event never fires.",
+            "fix": "Make the event is_triggered_only = yes and fire it with a delay from on_startup or another effect, or widen the window to at least 20 days.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unlogged errors",
+                    "item": "Tight bounds on date triggers"
+                }
+            ]
+        },
+        {
+            "id": "event_namespace_missing",
+            "status": "active",
+            "severity": "error",
+            "surfaces": ["event"],
+            "title": "Event id without add_namespace",
+            "mistake": "An event id uses a namespace that no events file declares with add_namespace.",
+            "symptom": "The game logs \"Malformed token\" at the id line and the event does not work.",
+            "fix": "Add add_namespace = <namespace> outside any event, before the first event that uses it.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "ID rules",
+                    "item": "A namespace must be first created before defining any events that use it."
+                },
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unintuitive logged errors",
+                    "item": "Malformed token: event_id.123, near line"
+                }
+            ],
+            "logPattern": "Malformed token: [\\w.]+\\.\\d+"
+        },
+        {
+            "id": "event_numeric_id_invalid",
+            "status": "active",
+            "severity": "error",
+            "surfaces": ["event"],
+            "title": "Event number that is not a whole number below 100000",
+            "mistake": "The part of an event id after the last dot is not an integer, or is 100000 or more.",
+            "symptom": "Every non-integer id becomes number 0, and numbers from 100000 reach the next namespace, so events share one internal id and one fires the other (\"Failed to create id ... Already exists in game\").",
+            "fix": "End the id with a whole number from 0 to 99999, unique within its namespace.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "ID rules",
+                    "item": "the ID of the event after the namespace must be an integer"
+                },
+                {
+                    "kind": "wiki",
+                    "page": "Event modding",
+                    "heading": "Common mistakes > Unintuitive logged errors",
+                    "item": "Failed to create id 12300000 50. Already exists in game."
+                }
+            ],
+            "logPattern": "Failed to create id \\d+ 50\\. Already exists in game"
+        },
+        {
+            "id": "temp_variable_scope_prefix",
+            "status": "active",
+            "severity": "warning",
+            "surfaces": ["event", "decision", "focus"],
+            "title": "Scope prefix on a temporary variable",
+            "mistake": "A temporary variable is read through a scope, such as ROOT.my_temp, in a file that only ever sets it as a temporary variable.",
+            "symptom": "Temporary variables have no scope, so the prefix does nothing useful and the read does not find the variable the author meant.",
+            "fix": "Read the temporary variable by its plain name, or store the value in a regular variable on the scope that needs it.",
+            "sources": [
+                {
+                    "kind": "wiki",
+                    "page": "Data structures",
+                    "heading": "Variables > Variable types",
+                    "item": "Temporary variables are unscoped"
+                },
+                {
+                    "kind": "wiki",
+                    "page": "Data structures",
+                    "heading": "Variables > Scoping",
+                    "item": "Scoping only exists for regular variables."
+                }
+            ]
+        }
+    ]
+}

package/dist/hoi4_agent_tools/reference/mod-index.js

@@ -0,0 +1,101 @@
+import { ServiceError } from '../core/result.js';
+import { readModDescriptor } from '../core/workspace.js';
+const MAX_NAMESPACES = 200;
+const MAX_FOLDERS = 60;
+/** Event namespaces with their numbered range, from `namespace.N` event IDs. */
+function namespaces(symbols) {
+    const byNamespace = new Map();
+    for (const symbol of symbols) {
+        if (symbol.kind !== 'event')
+            continue;
+        const match = /^(.+)\.(\d{1,9})$/u.exec(symbol.id);
+        if (match === null)
+            continue;
+        const entry = byNamespace.get(match[1]) ?? { numbers: [], files: new Set() };
+        entry.numbers.push(Number(match[2]));
+        entry.files.add(symbol.path);
+        byNamespace.set(match[1], entry);
+    }
+    return [...byNamespace]
+        .map(([namespace, { numbers, files }]) => ({
+        namespace,
+        events: new Set(numbers).size,
+        lowest: Math.min(...numbers),
+        highest: Math.max(...numbers),
+        files: files.size,
+    }))
+        .sort((left, right) => left.namespace.localeCompare(right.namespace, 'en'));
+}
+export async function modIndex(engine, workspaceId, input, principal, signal) {
+    if (input.mode === 'next_id') {
+        const prefix = input.prefix ??
+            (input.namespace === undefined ? undefined : `${input.namespace.replace(/\.$/u, '')}.`);
+        if (prefix === undefined)
+            throw new ServiceError('MOD_INDEX_PREFIX_REQUIRED', 'next_id needs prefix or namespace');
+        // Every layer: a new identifier must not collide with game or dependency definitions.
+        const snapshot = await engine.scan(workspaceId, {}, principal, signal);
+        const used = new Set();
+        for (const symbol of snapshot.index.symbols) {
+            if (symbol.kind !== input.kind || !symbol.id.startsWith(prefix))
+                continue;
+            const suffix = symbol.id.slice(prefix.length);
+            if (/^\d{1,9}$/u.test(suffix))
+                used.add(Number(suffix));
+        }
+        const highest = used.size === 0 ? undefined : Math.max(...used);
+        let firstGap;
+        for (let number = 1; highest !== undefined && number < highest; number += 1)
+            if (!used.has(number)) {
+                firstGap = number;
+                break;
+            }
+        const next = (highest ?? 0) + 1;
+        return {
+            mode: 'next_id',
+            complete: snapshot.complete,
+            next: {
+                kind: input.kind,
+                prefix,
+                used: used.size,
+                ...(highest === undefined ? {} : { highest }),
+                nextId: `${prefix}${next}`,
+                ...(firstGap === undefined ? {} : { firstGapId: `${prefix}${firstGap}` }),
+            },
+        };
+    }
+    const snapshot = await engine.scan(workspaceId, input.layer === 'mod' ? { rootKinds: ['mod'] } : {}, principal, signal);
+    const symbols = snapshot.index.symbols.filter(({ overridden }) => !overridden);
+    const kinds = new Map();
+    for (const symbol of symbols)
+        kinds.set(symbol.kind, (kinds.get(symbol.kind) ?? 0) + 1);
+    const folders = new Map();
+    for (const file of snapshot.files) {
+        const parts = file.relativePath.split('/');
+        const folder = parts.length > 2 && parts[0] === 'common' ? parts.slice(0, 2).join('/') : parts[0];
+        const totals = folders.get(folder) ?? { files: 0, bytes: 0 };
+        totals.files += 1;
+        totals.bytes += file.size;
+        folders.set(folder, totals);
+    }
+    const allNamespaces = namespaces(symbols);
+    const modRoot = engine.resolver
+        .get(workspaceId, principal)
+        .roots.find(({ kind }) => kind === 'mod')?.path;
+    const descriptor = modRoot === undefined ? undefined : await readModDescriptor(modRoot);
+    return {
+        mode: 'overview',
+        layer: input.layer,
+        complete: snapshot.complete,
+        ...(descriptor === undefined ? {} : { descriptor }),
+        files: snapshot.files.length,
+        kinds: [...kinds]
+            .map(([kind, count]) => ({ kind, count }))
+            .sort((left, right) => right.count - left.count || left.kind.localeCompare(right.kind)),
+        folders: [...folders]
+            .map(([folder, totals]) => ({ folder, ...totals }))
+            .sort((left, right) => right.files - left.files || left.folder.localeCompare(right.folder))
+            .slice(0, MAX_FOLDERS),
+        namespaces: allNamespaces.slice(0, MAX_NAMESPACES),
+        omittedNamespaces: Math.max(0, allNamespaces.length - MAX_NAMESPACES),
+    };
+}