hoi4-agent-tools 2.2.0 → 2.3.3

package/dist/hoi4_agent_tools/probability/value-evaluator.js

@@ -0,0 +1,357 @@
+import { assignments, astPathFor, nodeLocation, } from '../core/source/index.js';
+import { Rational } from './rational.js';
+import { evaluateTriggerBlock } from './trigger-evaluator.js';
+function appendReference(evaluated, reference) {
+    return {
+        ...evaluated,
+        referencedProvenance: [reference, ...(evaluated.referencedProvenance ?? [])],
+    };
+}
+function interval(value) {
+    return { min: value, max: value };
+}
+function nodeProvenance(candidate, node, symbol) {
+    const source = candidate.provenance[0];
+    if (source === undefined || candidate.document === undefined)
+        return source;
+    const astPath = astPathFor(candidate.document, node);
+    return {
+        ...source,
+        location: nodeLocation(candidate.document, node, symbol),
+        ...(astPath === undefined ? {} : { astPath }),
+        ...(symbol === undefined ? {} : { symbol }),
+    };
+}
+function conditionSignature(block) {
+    const encode = (value) => assignments(value).map((assignment) => [
+        assignment.key.value,
+        assignment.operator.text,
+        assignment.value.type === 'scalar' ? assignment.value.value : encode(assignment.value),
+    ]);
+    const encoded = encode(block);
+    return encoded.length === 0 ? 'always' : JSON.stringify(encoded);
+}
+function multiplyIntervals(left, right) {
+    const products = [
+        left.min.multiply(right.min),
+        left.min.multiply(right.max),
+        left.max.multiply(right.min),
+        left.max.multiply(right.max),
+    ].sort((a, b) => a.compare(b));
+    return { min: products[0], max: products.at(-1) };
+}
+function addIntervals(left, right) {
+    return { min: left.min.add(right.min), max: left.max.add(right.max) };
+}
+function scenarioNumber(scenario, expression) {
+    if (Object.hasOwn(scenario.state, expression))
+        return scenario.state[expression];
+    if (Object.hasOwn(scenario.state, `variable.${expression}`))
+        return scenario.state[`variable.${expression}`];
+    if (expression.startsWith('var:') &&
+        Object.hasOwn(scenario.state, `variable.${expression.slice(4)}`))
+        return scenario.state[`variable.${expression.slice(4)}`];
+    return undefined;
+}
+function expressionValue(expression, candidate, scenario, definitions, mtthStack) {
+    const numeric = Rational.parse(expression);
+    if (numeric !== undefined && Number.isFinite(numeric.toNumber()))
+        return { value: numeric, interval: interval(numeric), trace: [], unresolved: [] };
+    if (numeric !== undefined || /^(?:[+-]?(?:inf(?:inity)?|nan))$/iu.test(expression.trim()))
+        return {
+            trace: [],
+            unresolved: [
+                {
+                    code: 'VALUE_NON_FINITE',
+                    message: `Numeric expression ${expression} is outside finite analyzer range`,
+                    path: expression,
+                    candidateId: candidate.id,
+                    ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
+                },
+            ],
+        };
+    if (expression.startsWith('@')) {
+        const definition = definitions.localConstants
+            .get(candidate.provenance[0]?.path ?? '')
+            ?.get(expression);
+        if (definition !== undefined)
+            return appendReference(expressionValue(definition.value, candidate, scenario, definitions, mtthStack), {
+                path: definition.file.displayPath,
+                rootKind: definition.file.rootKind,
+                loadOrder: definition.file.loadOrder,
+                sourceHash: definition.file.sha256,
+                location: nodeLocation(definition.document, definition.node, expression),
+                ...(astPathFor(definition.document, definition.node) === undefined
+                    ? {}
+                    : { astPath: astPathFor(definition.document, definition.node) }),
+                symbol: expression,
+            });
+        const inline = candidate.document === undefined
+            ? undefined
+            : assignments(candidate.document.root, expression).find(({ value }) => value.type === 'scalar');
+        if (inline?.value.type === 'scalar')
+            return appendReference(expressionValue(inline.value.value, candidate, scenario, definitions, mtthStack), {
+                path: candidate.provenance[0]?.path ?? 'proposed:inline-probability-source.txt',
+                rootKind: candidate.provenance[0]?.rootKind ?? 'fixture',
+                loadOrder: candidate.provenance[0]?.loadOrder ?? 0,
+                sourceHash: candidate.provenance[0]?.sourceHash ?? '',
+                location: nodeLocation(candidate.document, inline, expression),
+                ...(astPathFor(candidate.document, inline) === undefined
+                    ? {}
+                    : { astPath: astPathFor(candidate.document, inline) }),
+                symbol: expression,
+            });
+    }
+    if (expression.startsWith('constant:')) {
+        const id = expression.slice('constant:'.length);
+        const definition = definitions.scriptConstants.get(id);
+        if (definition !== undefined)
+            return appendReference(expressionValue(definition.value, candidate, scenario, definitions, mtthStack), {
+                path: definition.file.displayPath,
+                rootKind: definition.file.rootKind,
+                loadOrder: definition.file.loadOrder,
+                sourceHash: definition.file.sha256,
+                location: nodeLocation(definition.document, definition.node, id),
+                ...(astPathFor(definition.document, definition.node) === undefined
+                    ? {}
+                    : { astPath: astPathFor(definition.document, definition.node) }),
+                symbol: id,
+            });
+    }
+    if (expression.startsWith('mtth:')) {
+        const id = expression.slice('mtth:'.length);
+        const definition = definitions.mtthVariables.get(id);
+        if (definition !== undefined && !mtthStack.includes(id)) {
+            const definitionCandidate = {
+                ...candidate,
+                document: definition.document,
+                provenance: [
+                    {
+                        path: definition.file.displayPath,
+                        rootKind: definition.file.rootKind,
+                        loadOrder: definition.file.loadOrder,
+                        sourceHash: definition.file.sha256,
+                        location: nodeLocation(definition.document, definition.node, id),
+                        ...(astPathFor(definition.document, definition.node) === undefined
+                            ? {}
+                            : { astPath: astPathFor(definition.document, definition.node) }),
+                        symbol: id,
+                        helperChain: [...mtthStack, id],
+                    },
+                    ...candidate.provenance,
+                ],
+            };
+            return appendReference(evaluateValueBlock(definition.value, definitionCandidate, scenario, definitions, Rational.one, [...mtthStack, id]), definitionCandidate.provenance[0]);
+        }
+        if (mtthStack.includes(id))
+            return {
+                trace: [],
+                unresolved: [
+                    {
+                        code: 'MTTH_RECURSION',
+                        message: `MTTH variable recursion detected at ${id}`,
+                        candidateId: candidate.id,
+                        ...(candidate.provenance[0] === undefined
+                            ? {}
+                            : { provenance: candidate.provenance[0] }),
+                    },
+                ],
+            };
+    }
+    const declared = scenarioNumber(scenario, expression);
+    if (typeof declared === 'number' || typeof declared === 'string') {
+        const parsed = Rational.parse(declared);
+        if (parsed !== undefined)
+            return { value: parsed, interval: interval(parsed), trace: [], unresolved: [] };
+    }
+    return {
+        trace: [],
+        unresolved: [
+            {
+                code: 'VALUE_UNRESOLVED',
+                message: `Scenario or source definitions do not resolve numeric expression ${expression}`,
+                path: expression,
+                candidateId: candidate.id,
+                ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
+            },
+        ],
+    };
+}
+function conditionBlock(block) {
+    const operationKeys = new Set(['base', 'add', 'factor', 'days', 'months', 'years']);
+    return {
+        ...block,
+        entries: block.entries.filter((entry) => entry.type !== 'assignment' || !operationKeys.has(entry.key.value)),
+    };
+}
+function applyOperation(current, operation, operand) {
+    if (operation === 'base')
+        return operand;
+    return operation === 'add' ? addIntervals(current, operand) : multiplyIntervals(current, operand);
+}
+export function evaluateValueBlock(block, candidate, scenario, definitions, initial, mtthStack = []) {
+    let current = interval(initial);
+    const trace = [];
+    const unresolved = [];
+    const referencedProvenance = [];
+    if (block === undefined)
+        return { value: initial, interval: current, trace, unresolved };
+    for (const assignment of assignments(block)) {
+        if (assignment.value.type === 'scalar') {
+            let operation;
+            let unit = Rational.one;
+            if (assignment.key.value === 'base')
+                operation = 'base';
+            else if (assignment.key.value === 'add')
+                operation = 'add';
+            else if (assignment.key.value === 'factor')
+                operation = 'factor';
+            else if (assignment.key.value === 'days')
+                operation = 'add';
+            else if (assignment.key.value === 'months') {
+                operation = 'add';
+                unit = new Rational(30n);
+            }
+            else if (assignment.key.value === 'years') {
+                operation = 'add';
+                unit = new Rational(365n);
+            }
+            if (operation === undefined)
+                continue;
+            const operand = expressionValue(assignment.value.value, candidate, scenario, definitions, mtthStack);
+            unresolved.push(...operand.unresolved);
+            referencedProvenance.push(...(operand.referencedProvenance ?? []));
+            if (operand.interval === undefined)
+                continue;
+            const scaled = multiplyIntervals(operand.interval, interval(unit));
+            const before = current;
+            current = applyOperation(current, operation, scaled);
+            if (!Number.isFinite(current.min.toNumber()) || !Number.isFinite(current.max.toNumber())) {
+                unresolved.push({
+                    code: 'VALUE_NON_FINITE',
+                    message: `${candidate.id} modifier chain exceeds finite analyzer range`,
+                    candidateId: candidate.id,
+                    ...(nodeProvenance(candidate, assignment, assignment.key.value) === undefined
+                        ? {}
+                        : { provenance: nodeProvenance(candidate, assignment, assignment.key.value) }),
+                });
+                return { trace, unresolved, referencedProvenance };
+            }
+            trace.push({
+                operation,
+                expression: assignment.value.value,
+                applied: 'true',
+                ...(scaled.min.compare(scaled.max) === 0 ? { value: scaled.min.toJSON() } : {}),
+                ...(before.min.compare(before.max) === 0 ? { before: before.min.toJSON() } : {}),
+                ...(current.min.compare(current.max) === 0 ? { after: current.min.toJSON() } : {}),
+                ...(nodeProvenance(candidate, assignment, assignment.key.value) === undefined
+                    ? {}
+                    : { provenance: nodeProvenance(candidate, assignment, assignment.key.value) }),
+            });
+            continue;
+        }
+        if (assignment.key.value !== 'modifier')
+            continue;
+        const modifier = assignment.value;
+        const condition = evaluateTriggerBlock(conditionBlock(modifier), scenario, candidate, definitions);
+        const conditionExpression = conditionSignature(conditionBlock(modifier));
+        unresolved.push(...condition.unresolved);
+        referencedProvenance.push(...(condition.helperProvenance ?? []));
+        for (const modifierAssignment of assignments(modifier)) {
+            if (modifierAssignment.value.type !== 'scalar' ||
+                !['base', 'add', 'factor'].includes(modifierAssignment.key.value))
+                continue;
+            const operation = modifierAssignment.key.value;
+            const expression = modifierAssignment.value.value;
+            const operand = expressionValue(expression, candidate, scenario, definitions, mtthStack);
+            unresolved.push(...operand.unresolved);
+            referencedProvenance.push(...(operand.referencedProvenance ?? []));
+            if (operand.interval === undefined || condition.state === 'false') {
+                trace.push({
+                    operation,
+                    expression,
+                    applied: condition.state,
+                    conditionExpression,
+                    ...(nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value) ===
+                        undefined
+                        ? {}
+                        : {
+                            provenance: nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value),
+                        }),
+                });
+                continue;
+            }
+            const before = current;
+            const applied = applyOperation(current, operation, operand.interval);
+            current =
+                condition.state === 'true'
+                    ? applied
+                    : {
+                        min: current.min.min(applied.min),
+                        max: current.max.max(applied.max),
+                    };
+            if (!Number.isFinite(current.min.toNumber()) || !Number.isFinite(current.max.toNumber())) {
+                unresolved.push({
+                    code: 'VALUE_NON_FINITE',
+                    message: `${candidate.id} modifier chain exceeds finite analyzer range`,
+                    candidateId: candidate.id,
+                    ...(nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value) ===
+                        undefined
+                        ? {}
+                        : {
+                            provenance: nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value),
+                        }),
+                });
+                return { trace, unresolved, referencedProvenance };
+            }
+            trace.push({
+                operation,
+                expression,
+                applied: condition.state,
+                conditionExpression,
+                ...(condition.helperProvenance?.length
+                    ? {
+                        note: `Condition helper chain: ${condition.helperProvenance
+                            .map(({ symbol }) => symbol)
+                            .filter(Boolean)
+                            .join(' -> ')}`,
+                    }
+                    : {}),
+                ...(operand.interval.min.compare(operand.interval.max) === 0
+                    ? { value: operand.interval.min.toJSON() }
+                    : {}),
+                ...(before.min.compare(before.max) === 0 ? { before: before.min.toJSON() } : {}),
+                ...(current.min.compare(current.max) === 0 ? { after: current.min.toJSON() } : {}),
+                ...(nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value) ===
+                    undefined
+                    ? {}
+                    : {
+                        provenance: nodeProvenance(candidate, modifierAssignment, modifierAssignment.key.value),
+                    }),
+            });
+        }
+    }
+    return {
+        ...(current.min.compare(current.max) === 0 ? { value: current.min } : {}),
+        interval: current,
+        trace,
+        unresolved,
+        ...(referencedProvenance.length === 0 ? {} : { referencedProvenance }),
+    };
+}
+export function evaluateCandidateValue(candidate, scenario, definitions) {
+    const initialExpression = candidate.valueExpression ?? candidate.defaultValue;
+    const initial = expressionValue(initialExpression, candidate, scenario, definitions, []);
+    if (initial.interval === undefined)
+        return initial;
+    const evaluated = evaluateValueBlock(candidate.weightBlock, candidate, scenario, definitions, initial.interval.min);
+    return {
+        ...evaluated,
+        trace: [...initial.trace, ...evaluated.trace],
+        unresolved: [...initial.unresolved, ...evaluated.unresolved],
+        referencedProvenance: [
+            ...(initial.referencedProvenance ?? []),
+            ...(evaluated.referencedProvenance ?? []),
+        ],
+    };
+}

package/dist/hoi4_agent_tools/runtime.js

@@ -1,4 +1,4 @@
-import { stat } from 'node:fs/promises';
+import { lstat, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
@@ -39,15 +39,117 @@ async function isFile(candidate) {
         return false;
     }
 }
+/**
+ * Standard content directories that can be the only content in a valid local
+ * mod. Keep this list limited to HOI4 roots so an arbitrary project directory
+ * is not mistaken for a mod just because it contains a generic `common`
+ * folder.
+ */
+const MOD_CONTENT_DIRECTORIES = [
+    'events',
+    'gfx',
+    'history',
+    'interface',
+    'localisation',
+    'localisation_synced',
+    'map',
+    'music',
+    'portraits',
+    'sound',
+];
+const MOD_CONTENT_EXTENSIONS = {
+    events: ['.txt'],
+    gfx: ['.dds', '.gfx', '.png', '.tga'],
+    history: ['.txt'],
+    interface: ['.gfx', '.gui', '.txt'],
+    localisation: ['.yml', '.yaml'],
+    localisation_synced: ['.yml', '.yaml'],
+    map: ['.bmp', '.csv', '.map', '.txt'],
+    music: ['.asset', '.ogg', '.txt', '.wav'],
+    portraits: ['.dds', '.jpg', '.jpeg', '.png', '.tga'],
+    sound: ['.asset', '.ogg', '.txt', '.wav'],
+};
+const MOD_COMMON_DIRECTORIES = [
+    'abilities',
+    'ai_focuses',
+    'ai_strategy',
+    'ai_strategy_plans',
+    'bop',
+    'buildings',
+    'characters',
+    'continuous_focus',
+    'decisions',
+    'doctrines',
+    'ideas',
+    'mtth',
+    'national_focus',
+    'on_actions',
+    'operations',
+    'raids',
+    'resistance_compliance_modifiers',
+    'script_constants',
+    'scripted_effects',
+    'scripted_guis',
+    'scripted_triggers',
+    'special_projects',
+    'technology_sharing',
+    'technologies',
+    'technology_tags',
+    'units',
+    'unit_tags',
+];
+async function hasEntries(candidate, extensions) {
+    try {
+        const entries = await readdir(candidate, { withFileTypes: true });
+        return entries.some((entry) => entry.isFile() &&
+            (extensions === undefined ||
+                extensions.some((extension) => entry.name.toLowerCase().endsWith(extension))));
+    }
+    catch {
+        return false;
+    }
+}
+async function isRealDirectory(candidate) {
+    try {
+        const metadata = await lstat(candidate);
+        return metadata.isDirectory() && !metadata.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function isLikelyGameRoot(candidate) {
+    // Vanilla installations have an executable or launcher marker that a mod
+    // root should never contain. The marker check also protects a nested cwd
+    // such as `<game>/common` when the server is started from there.
+    return ((await isFile(path.join(candidate, 'hoi4.exe'))) ||
+        (await isFile(path.join(candidate, 'run_hoi4'))) ||
+        (await isFile(path.join(candidate, 'steam_appid.txt'))));
+}
+async function isLikelyModRoot(candidate) {
+    if (await isFile(path.join(candidate, 'descriptor.mod')))
+        return true;
+    if (await isLikelyGameRoot(candidate))
+        return false;
+    for (const directory of MOD_COMMON_DIRECTORIES) {
+        if (await isRealDirectory(path.join(candidate, 'common', directory)))
+            return true;
+    }
+    if (await isFile(path.join(candidate, 'common', 'combat_tactics.txt')))
+        return true;
+    for (const directory of MOD_CONTENT_DIRECTORIES) {
+        if ((await isRealDirectory(path.join(candidate, directory))) &&
+            (await hasEntries(path.join(candidate, directory), MOD_CONTENT_EXTENSIONS[directory])))
+            return true;
+    }
+    return false;
+}
 async function findCurrentModRoot(start = process.cwd()) {
     for (let cursor = path.resolve(start);;) {
-        if ((await isFile(path.join(cursor, 'descriptor.mod'))) ||
-            ((await isDirectory(path.join(cursor, 'common'))) &&
-                ((await isDirectory(path.join(cursor, 'history'))) ||
-                    (await isDirectory(path.join(cursor, 'interface'))) ||
-                    (await isDirectory(path.join(cursor, 'map')))))) {
+        if (await isLikelyGameRoot(cursor))
+            break;
+        if (await isLikelyModRoot(cursor))
             return cursor;
-        }
         const parent = path.dirname(cursor);
         if (parent === cursor)
             break;