hoi4-agent-tools 4.2.0 → 4.4.0

package/dist/hoi4_agent_tools/event/source-analysis.js

@@ -216,8 +216,11 @@ const NATIVE_EFFECT_CONTAINERS = new Set([
     'while_loop_effect',
 ]);
 /** Inside a native effect such as `add_building_construction`, `key = yes` is an argument. */
-function isNativeArgumentBlock(normalizedKey) {
-    return (nativeEffectKeys.has(normalizedKey) &&
+function isNativeEffect(normalizedKey, documented) {
+    return nativeEffectKeys.has(normalizedKey) || documented?.has(normalizedKey) === true;
+}
+function isNativeArgumentBlock(normalizedKey, documented) {
+    return (isNativeEffect(normalizedKey, documented) &&
         !NATIVE_EFFECT_CONTAINERS.has(normalizedKey) &&
         !CONTROL_BLOCKS.has(normalizedKey) &&
         SCOPE_BLOCKS[normalizedKey] === undefined &&
@@ -285,10 +288,10 @@ function localisationKeysFromValue(value) {
     }
     return [...new Set(keys)].sort(compareCodeUnits);
 }
-function missingHelperCandidate(key, value, effectContext) {
+function missingHelperCandidate(key, value, effectContext, documented) {
     const normalizedKey = key.toLowerCase();
     if (!effectContext ||
-        nativeEffectKeys.has(normalizedKey) ||
+        isNativeEffect(normalizedKey, documented) ||
         NON_HELPER_BLOCKS.has(normalizedKey) ||
         SCOPE_BLOCKS[normalizedKey] !== undefined ||
         STATE_RULES[normalizedKey] !== undefined ||
@@ -993,7 +996,7 @@ class FragmentAnalyzer {
             if (this.context.inventoryComplete !== false &&
                 context.nativeArguments !== true &&
                 context.inferMissingHelpers !== false &&
-                missingHelperCandidate(key, entry.value, effectContext)) {
+                missingHelperCandidate(key, entry.value, effectContext, this.context.documentedEffectKeys)) {
                 const target = this.unresolvedNode('missing_helper', key, entry, context.ownerId, semanticPath);
                 this.addEdge(context.ownerId, target, 'scripted_effect_call', entry, context.conditions, {
                     phase: context.phase,
@@ -1122,7 +1125,8 @@ class FragmentAnalyzer {
                 effectContext: NON_EXECUTING_BLOCKS.has(normalizedKey) || isTriggerIterator(normalizedKey)
                     ? false
                     : effectContext,
-                nativeArguments: context.nativeArguments === true || isNativeArgumentBlock(normalizedKey),
+                nativeArguments: context.nativeArguments === true ||
+                    isNativeArgumentBlock(normalizedKey, this.context.documentedEffectKeys),
                 ...(context.inferMissingHelpers === false && isConventionalEffectBlock(normalizedKey)
                     ? { inferMissingHelpers: true }
                     : {}),

package/dist/hoi4_agent_tools/focus/importer.js

@@ -135,9 +135,9 @@ function isFormableDecision(target, options) {
         return false;
     return /(?:^form_|formable|form_country)/iu.test(target);
 }
-function isEffectContainer(key) {
+function isEffectContainer(key, nativeEffects) {
     return (effectContainerKeys.has(key) ||
-        (nativeFocusEffectKeys.has(key) &&
+        ((nativeFocusEffectKeys.has(key) || nativeEffects?.has(key) === true) &&
             /^(?:(?:global_)?every|ordered|random)_[a-z0-9_]+$/u.test(key)));
 }
 function isScopeKey(key, knownLeaders) {
@@ -342,6 +342,7 @@ function referenceLinks(document, block, options) {
     const links = [];
     const knownHelpers = catalogValues(options, 'helper');
     const knownLeaders = catalogValues(options, 'leader');
+    const isNative = (key) => nativeFocusEffectKeys.has(key) || options.nativeEffects?.has(key) === true;
     function recordReference(assignment, specification) {
         for (const target of referenceTargets(assignment, specification)) {
             const kind = specification.kind === 'decision' && isFormableDecision(target, options)
@@ -364,7 +365,8 @@ function referenceLinks(document, block, options) {
             recordReference(assignment, reference);
             if (assignment.value.type === 'block') {
                 for (const nested of assignments(assignment.value)) {
-                    if (nested.value.type === 'block' && isEffectContainer(nested.key.value.toLowerCase())) {
+                    if (nested.value.type === 'block' &&
+                        isEffectContainer(nested.key.value.toLowerCase(), options.nativeEffects)) {
                         effectAssignment(nested, new Set());
                     }
                 }
@@ -373,7 +375,7 @@ function referenceLinks(document, block, options) {
         }
         if (knownHelpers.has(key) &&
             !effectContainerKeys.has(normalizedKey) &&
-            !nativeFocusEffectKeys.has(normalizedKey)) {
+            !isNative(normalizedKey)) {
             links.push({
                 kind: 'helper',
                 target: key,
@@ -381,7 +383,7 @@ function referenceLinks(document, block, options) {
             });
             return;
         }
-        if (isEffectContainer(normalizedKey)) {
+        if (isEffectContainer(normalizedKey, options.nativeEffects)) {
             if (assignment.value.type !== 'block')
                 return;
             if (normalizedKey === 'random_list') {
@@ -397,7 +399,7 @@ function referenceLinks(document, block, options) {
             }
             return;
         }
-        if (nativeFocusEffectKeys.has(normalizedKey))
+        if (isNative(normalizedKey))
             return;
         if (assignment.value.type === 'block' && isScopeKey(key, knownLeaders)) {
             effectWalk(assignment.value, new Set());

package/dist/hoi4_agent_tools/focus/native-effects.js

@@ -2,7 +2,9 @@
  * Native effect identifiers used to distinguish direct scripted-effect calls
  * from engine effects while importing focus completion rewards.
  *
- * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10.
+ * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10. This is the
+ * fallback list; analysis also accepts every effect the installed game documents in
+ * documentation/effects_documentation.md, so effects added by later patches are recognized.
  * Keep this list synchronized during compatibility reviews.
  */
 export const nativeEffectKeys = new Set([

package/dist/hoi4_agent_tools/focus/tool-support.js

@@ -40,7 +40,7 @@ export function activeSidecar(snapshot, focusFile) {
 }
 export function importFocusFile(snapshot, file, palettes) {
     const document = parseClausewitz(file.bytes, file.displayPath);
-    const imported = importFocusTrees(document, { references: referenceCatalog(snapshot) });
+    const imported = importFocusTrees(document, focusImportOptions(snapshot));
     const sidecar = activeSidecar(snapshot, file);
     imported.plans = imported.plans.map((plan) => {
         const enriched = sidecar === undefined
@@ -89,6 +89,15 @@ export function selectContinuousPlan(result, paletteId) {
         throw new ServiceError('CONTINUOUS_FOCUS_PALETTE_NOT_FOUND', `Continuous focus palette was not found: ${paletteId}`);
     return plan;
 }
+/** Import options from a scan: its reference catalog and the installed game's documented effects. */
+export function focusImportOptions(snapshot) {
+    return {
+        references: referenceCatalog(snapshot),
+        ...(snapshot.documentedEffects === undefined
+            ? {}
+            : { nativeEffects: snapshot.documentedEffects.names }),
+    };
+}
 export function referenceCatalog(snapshot) {
     const identifiers = (kind) => [
         ...new Set(snapshot.index