hoi4-agent-tools 2.3.0 → 2.3.4

package/dist/hoi4_agent_tools/event/service.js

@@ -42,14 +42,19 @@ class BoundedEventFragmentCache {
         }
     }
 }
-function eventGraphCacheKey(workspaceId, projectHelpers) {
-    return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}`;
+function eventGraphCacheKey(workspaceId, projectHelpers, analysisMode = 'full') {
+    return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}\0${analysisMode}`;
+}
+function isGameBackedWorkspace(workspace) {
+    return workspace.roots.some(({ kind }) => kind === 'game');
 }
 const serviceState = new WeakMap();
 const EVENT_GRAPH_ARTIFACT_MAX_BYTES = 67_108_864;
 const EVENT_GRAPH_ARTIFACT_MAX_CHUNKS = 1_024;
 const EVENT_SCAN_FULL_GRAPH_RECORD_LIMIT = 100_000;
 const EVENT_SCAN_SUMMARY_SAMPLE_LIMIT = 100;
+const EVENT_FOCUSED_EVIDENCE_LIMIT = 2_000;
+const EVENT_FOCUSED_GRAPH_FILE_THRESHOLD = 1_000;
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const graphHashCache = new WeakMap();
 function groupedCounts(values, key) {
@@ -75,6 +80,7 @@ export function eventScanReport(graph, fullGraphRecordLimit = EVENT_SCAN_FULL_GR
         graphSummary: {
             schemaVersion: graph.schemaVersion,
             parserVersion: graph.parserVersion,
+            analysisMode: graph.analysisMode ?? 'full',
             workspaceId: graph.workspaceId,
             workspaceIdentity: graph.workspaceIdentity,
             revision: graph.revision,
@@ -116,7 +122,17 @@ function cachedEventGraphHash(graph, signal) {
     const cached = graphHashCache.get(graph);
     if (cached !== undefined)
         return cached;
-    const computed = eventGraphHash(graph, signal);
+    const computed = graph.analysisMode === 'focused'
+        ? hashCanonical({
+            schemaVersion: graph.schemaVersion,
+            parserVersion: graph.parserVersion,
+            analysisMode: graph.analysisMode ?? 'full',
+            workspaceIdentity: graph.workspaceIdentity,
+            revision: graph.revision,
+            statistics: graph.statistics,
+            sourceHashes: graph.sourceHashes,
+        })
+        : eventGraphHash(graph, signal);
     graphHashCache.set(graph, computed);
     return computed;
 }
@@ -135,6 +151,61 @@ function sharedState(engine) {
 function engineGeneration(engine, workspaceId) {
     return engine.generation(workspaceId);
 }
+function eventScanPatterns(workspace, focused = false) {
+    const roots = workspace.registration.roots;
+    const under = (values, glob) => values.map((root) => `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/${glob}`);
+    if (focused) {
+        return ['events/**/*.txt', 'common/on_actions/**/*.txt'].sort(compareCodeUnits);
+    }
+    return [
+        'events/**/*.txt',
+        'history/countries/**/*.txt',
+        ...under(roots.states, '**/*.txt'),
+        'common/continuous_focus/**/*.txt',
+        'common/decisions/**/*.txt',
+        'common/ideas/**/*.txt',
+        'common/characters/**/*.txt',
+        'common/operations/**/*.txt',
+        'common/raids/**/*.txt',
+        'common/bop/**/*.txt',
+        'common/resistance_compliance_modifiers/**/*.txt',
+        'common/abilities/**/*.txt',
+        'common/on_actions/**/*.txt',
+        'common/special_projects/**/*.txt',
+        'common/scripted_effects/**/*.txt',
+        ...under(roots.focus, '**/*.txt'),
+        ...under(roots.scriptedGui, '**/*.txt'),
+        ...under(roots.localisation, 'english/**/*.{yml,yaml}'),
+        ...under(roots.localisation, '*.{yml,yaml}'),
+    ].sort(compareCodeUnits);
+}
+async function scanEventSources(engine, workspaceId, workspace, focused = false, principal, signal) {
+    const patterns = eventScanPatterns(workspace, focused);
+    const gamePatterns = eventScanPatterns(workspace, focused);
+    const sourceKinds = ['mod', 'dependency', 'fixture'];
+    const scans = await Promise.all([
+        engine.scan(workspaceId, { patterns, rootKinds: sourceKinds }, principal, signal),
+        ...(workspace.roots.some(({ kind }) => kind === 'game')
+            ? [
+                engine.scan(workspaceId, { patterns: gamePatterns, rootKinds: ['game'] }, principal, signal),
+            ]
+            : []),
+    ]);
+    const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
+    recomputeShadowing(files);
+    files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+    const index = engine.indexFiles(files);
+    return {
+        workspaceId,
+        revision: snapshotRevision(files),
+        files,
+        index,
+        complete: scans.every(({ complete }) => complete) && index.complete,
+        skippedSourceCount: index.skippedSourceCount,
+        skippedSources: index.skippedSources,
+        diagnostics: [...scans.flatMap(({ diagnostics }) => diagnostics), ...index.diagnostics],
+    };
+}
 function rememberGraph(state, workspaceId, graph) {
     const history = state.history.get(workspaceId) ?? new Map();
     history.delete(graph.revision);
@@ -163,6 +234,20 @@ function eventIssueDiagnostic(issue) {
         },
     };
 }
+function boundedEvidence(values, limit = EVENT_FOCUSED_EVIDENCE_LIMIT) {
+    if (values.length <= limit)
+        return { values: [...values] };
+    return {
+        values: values.slice(0, limit),
+        inventory: { count: values.length, retainedCount: limit, truncated: true },
+    };
+}
+function boundedUnresolved(graph, selectedNodeIds) {
+    const relevant = selectedNodeIds === undefined
+        ? graph.unresolved
+        : graph.unresolved.filter(({ id, ownerId }) => selectedNodeIds.has(id) || (ownerId !== undefined && selectedNodeIds.has(ownerId)));
+    return boundedEvidence(relevant);
+}
 export function eventDiagnostics(graph) {
     const existing = new Set(graph.diagnostics.map(({ code, location }) => `${code}:${location?.path ?? ''}:${location?.start.offset ?? -1}`));
     return [
@@ -617,38 +702,63 @@ export class EventChainViewer {
         // principal bypass the resolver check for a later caller.
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = engineGeneration(this.engine, workspaceId);
-        const projectHelpers = options.projectHelpers ?? true;
-        const cacheKey = eventGraphCacheKey(workspaceId, projectHelpers);
+        const requestedProjectHelpers = options.projectHelpers ?? true;
+        const requestedAnalysisMode = options.analysisMode ?? 'full';
+        const autoFocused = isGameBackedWorkspace(workspace) && requestedAnalysisMode === 'full';
+        const cacheAnalysisMode = autoFocused ? 'focused' : requestedAnalysisMode;
+        const cacheProjectHelpers = cacheAnalysisMode === 'focused' ? false : requestedProjectHelpers;
+        const cacheKey = eventGraphCacheKey(workspaceId, cacheProjectHelpers, cacheAnalysisMode);
         const cached = this.#state.current.get(cacheKey);
         if (options.refresh !== true && cached?.generation === generation) {
             return cached.graph;
         }
-        const sibling = this.#state.current.get(eventGraphCacheKey(workspaceId, !projectHelpers));
+        const sibling = this.#state.current.get(eventGraphCacheKey(workspaceId, !cacheProjectHelpers, cacheAnalysisMode)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers, requestedAnalysisMode)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, !requestedProjectHelpers)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers));
+        const scanFocused = autoFocused || requestedAnalysisMode === 'focused';
         const snapshot = options.refresh !== true && sibling?.generation === generation
             ? sibling.snapshot
-            : await this.engine.scan(workspaceId, {}, options.principal, options.signal);
+            : await scanEventSources(this.engine, workspaceId, workspace, scanFocused, options.principal, options.signal);
         options.signal?.throwIfAborted();
         if (cached?.snapshot.revision === snapshot.revision && cached.generation === generation) {
             return cached.graph;
         }
+        const buildAnalysisMode = autoFocused || snapshot.files.length > EVENT_FOCUSED_GRAPH_FILE_THRESHOLD
+            ? 'focused'
+            : 'full';
+        const projectHelpers = buildAnalysisMode === 'focused' ? false : requestedProjectHelpers;
         const graph = buildEventGraph(snapshot, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             cache: this.#state.fragments,
             workspaceIdentity: workspace.workspaceIdentity,
             projectHelpers,
+            analysisMode: buildAnalysisMode,
         });
         this.#state.current.set(cacheKey, { generation, snapshot, graph });
-        rememberGraph(this.#state, workspaceId, graph);
+        if (buildAnalysisMode === 'full')
+            rememberGraph(this.#state, workspaceId, graph);
         return graph;
     }
     async inspect(input) {
         input.signal?.throwIfAborted();
-        const graph = await this.scan(input.workspaceId, {
+        const scannedGraph = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.mode === 'scan',
-            projectHelpers: input.mode !== 'scan' && input.mode !== 'roots',
+            // Focused routes traverse helper nodes directly and collapse only the
+            // selected path. Avoid materialising the full workspace projection first.
+            projectHelpers: input.mode !== 'scan' &&
+                input.mode !== 'roots' &&
+                input.mode !== 'trace' &&
+                input.mode !== 'explain_path',
+            ...(input.mode === 'trace' || input.mode === 'explain_path'
+                ? { analysisMode: 'focused' }
+                : {}),
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
+        // Keep the service result's graph identity distinct from a prior scan while
+        // reusing its structural cache and avoiding a second large graph build.
+        const graph = input.mode === 'trace' || input.mode === 'explain_path' ? { ...scannedGraph } : scannedGraph;
         const maxDepth = input.maxDepth ?? 8;
         const maxNodes = input.maxNodes ?? 500;
         const maxEdges = input.maxEdges ?? 2_000;
@@ -671,28 +781,41 @@ export class EventChainViewer {
                 report = eventScanReport(graph);
                 break;
             case 'roots':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    roots: discoverEventRoots(graph, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        roots: discoverEventRoots(graph, input.signal),
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'trace':
                 if (input.selector === undefined)
                     throw new ServiceError('EVENT_SELECTOR_REQUIRED', 'Trace requires a selector');
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    trace: traceSelectedEvents(graph, input.selector, {
+                {
+                    const trace = traceSelectedEvents(graph, input.selector, {
                         maxDepth,
                         maxNodes,
                         maxEdges,
                         direction: input.direction ?? 'both',
                         expandHelpers: input.expandHelpers ?? false,
-                    }, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                    }, input.signal);
+                    const unresolved = boundedUnresolved(graph, new Set(trace.nodes.map(({ id }) => id)));
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        trace,
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'explain_path':
                 if (input.from === undefined || input.to === undefined)
@@ -704,31 +827,54 @@ export class EventChainViewer {
                 };
                 break;
             case 'state_flow':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    flow: inspectEventStateFlow(graph, input.selector, input.stateSubject, input.signal),
-                    issues: lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE)/u.test(code)),
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE)/u.test(code)));
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        flow: inspectEventStateFlow(graph, input.selector, input.stateSubject, input.signal),
+                        issues: issues.values,
+                        unresolved: unresolved.values,
+                        ...(issues.inventory === undefined ? {} : { issueInventory: issues.inventory }),
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'lint':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    issues: lintEventGraph(graph, input.selector, input.signal),
-                    complete: graph.complete,
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal));
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        issues: issues.values,
+                        complete: graph.complete,
+                        unresolved: unresolved.values,
+                        ...(issues.inventory === undefined ? {} : { issueInventory: issues.inventory }),
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'impact':
                 if (input.impactSubject === undefined)
                     throw new ServiceError('EVENT_IMPACT_SUBJECT_REQUIRED', 'Impact analysis requires a subject');
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    impact: analyzeEventImpact(graph, input.impactSubject, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        impact: analyzeEventImpact(graph, input.impactSubject, input.signal),
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
         }
         const graphHash = cachedEventGraphHash(graph, input.signal);
@@ -742,7 +888,7 @@ export class EventChainViewer {
             : undefined;
         const artifactUnresolved = projectedScan
             ? graph.unresolved.slice(0, EVENT_SCAN_SUMMARY_SAMPLE_LIMIT)
-            : graph.unresolved;
+            : boundedUnresolved(graph).values;
         const reportJson = `${canonicalJson({
             schemaVersion: 'event-analysis.v1',
             graphSchemaVersion: graph.schemaVersion,
@@ -759,12 +905,12 @@ export class EventChainViewer {
             complete: graph.complete,
             filters: analysisFilters,
             unresolved: artifactUnresolved,
-            ...(projectedScan
+            ...(artifactUnresolved.length !== graph.unresolved.length
                 ? {
                     unresolvedInventory: {
                         count: graph.unresolved.length,
                         retainedCount: artifactUnresolved.length,
-                        truncated: artifactUnresolved.length !== graph.unresolved.length,
+                        truncated: true,
                     },
                 }
                 : {}),
@@ -950,7 +1096,15 @@ export class EventChainViewer {
                 includeHtml: input.includeHtml ?? false,
                 refresh: input.refresh ?? false,
             },
-            unresolved: graph.unresolved,
+            ...(() => {
+                const unresolved = boundedUnresolved(graph, new Set(render.selectedNodeIds));
+                return {
+                    unresolved: unresolved.values,
+                    ...(unresolved.inventory === undefined
+                        ? {}
+                        : { unresolvedInventory: unresolved.inventory }),
+                };
+            })(),
             resources: { ...resourceNames, artifacts: resourceLinks },
             overview: {
                 selectedNodeIds: render.selectedNodeIds,