hoi4-agent-tools 3.10.0 → 4.0.1

package/dist/hoi4_agent_tools/reference/operations.js

@@ -8,6 +8,9 @@ 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 { readErrorLog } from './error-log.js';
+import { modIndex } from './mod-index.js';
+import { errorLogDataSchema, errorLogRequestSchema, modIndexDataSchema, modIndexRequestSchema, } from '../schemas/mod-tools.js';
 import { eventPopupDefinitions } from './event-popups.js';
 import { locatePatterns, selectFile } from './source-locate.js';
 /**
@@ -43,6 +46,8 @@ const schemas = {
     'hoi4.reference_context': referenceContextRequestSchema,
     'hoi4.source_lookup': sourceLookupRequestSchema,
     'hoi4.script_validate': scriptValidateRequestSchema,
+    'hoi4.error_log': errorLogRequestSchema,
+    'hoi4.mod_index': modIndexRequestSchema,
 };
 export function isReferenceTool(name) {
     return Object.hasOwn(schemas, name);
@@ -69,10 +74,34 @@ export class ReferenceToolService {
                 ? await this.references.read(workspace, referenceReadRequestSchema.parse(parsed), signal)
                 : name === 'hoi4.reference_context'
                     ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
-                    : name === 'hoi4.script_validate'
-                        ? await this.validateScript(workspaceId, workspace, scriptValidateRequestSchema.parse(parsed), context.principal, signal)
-                        : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
+                    : name === 'hoi4.error_log'
+                        ? await readErrorLog(workspace, errorLogRequestSchema.parse(parsed), this.engine.resolver.config().gameUserRoot, signal)
+                        : name === 'hoi4.mod_index'
+                            ? await modIndex(this.engine, workspaceId, modIndexRequestSchema.parse(parsed), context.principal, signal)
+                            : name === 'hoi4.script_validate'
+                                ? 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.error_log') {
+            const log = errorLogDataSchema.parse(data);
+            result.code = 'ERROR_LOG_READ';
+            result.validation = {
+                passed: log.modEntries === 0,
+                checks: [
+                    {
+                        id: 'error-log-mod-entries',
+                        passed: log.modEntries === 0,
+                        message: log.modEntries === 0
+                            ? 'The last game launch logged no errors located in this mod'
+                            : `The last game launch logged ${log.modEntries} distinct errors located in this mod`,
+                    },
+                ],
+            };
+        }
+        if (name === 'hoi4.mod_index') {
+            const index = modIndexDataSchema.parse(data);
+            result.code = index.complete ? 'MOD_INDEXED' : 'MOD_INDEXED_PARTIAL';
+        }
         if (name === 'hoi4.script_validate') {
             const checked = scriptValidateDataSchema.parse(data);
             result.code = checked.valid === null ? 'SCRIPT_CHECK_PARTIAL' : 'SCRIPT_CHECKED';
@@ -117,20 +146,32 @@ export class ReferenceToolService {
     #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);
+        if (request.path === undefined) {
+            if (request.kind !== undefined)
+                return validateScript(this.references, workspace, request, signal);
+            // A snippet without a kind is checked as an effect and as a trigger; the reading with
+            // fewer errors and unresolved commands is the one the author meant.
+            const effect = await validateScript(this.references, workspace, { ...request, kind: 'effect' }, signal);
+            const trigger = await validateScript(this.references, workspace, { ...request, kind: 'trigger' }, signal);
+            const misses = (checked) => checked.findings.filter(({ status }) => status === 'error').length * 100_000 +
+                checked.unresolvedCount;
+            return misses(trigger) < misses(effect) ? trigger : effect;
+        }
+        // Every file check of the supported families shares one scan, so checking files across
+        // folders reuses one snapshot and its incremental index; other folders add their own.
+        const scan = (extra) => this.engine.scan(workspaceId, { patterns: [...fileCheckPatterns, ...extra] }, principal, signal);
+        let snapshot = await scan([]);
+        let file;
+        try {
+            file = selectFile(snapshot, request.path);
+        }
+        catch (error) {
+            const extra = locatePatterns(this.engine, workspaceId, request.path, principal);
+            if (extra === undefined)
+                throw error;
+            snapshot = await scan(extra);
+            file = selectFile(snapshot, request.path);
+        }
         const playerText = playerTextFamily(file.relativePath)
             ? this.playerTextContext(workspaceId, snapshot)
             : undefined;
@@ -143,8 +184,26 @@ export class ReferenceToolService {
             implicitTriggers: implicitTriggerNames(snapshot),
             ...(playerText === undefined ? {} : { playerText }),
             eventPopups: this.eventPopupContext(workspaceId, snapshot),
+            knownMistakes: { eventNamespaces: this.eventNamespaces(workspaceId, snapshot) },
         });
     }
+    #eventNamespaces = new Map();
+    /** Namespaces declared with `add_namespace` in every active events file, cached by hash. */
+    eventNamespaces(workspaceId, snapshot) {
+        const sources = [...snapshot.index.files.values()].filter(({ relativePath, shadowedBy }) => shadowedBy === undefined && relativePath.startsWith('events/'));
+        const cacheKey = hashCanonical(sources.map(({ displayPath, sha256 }) => [displayPath, sha256]));
+        const cached = this.#eventNamespaces.get(workspaceId);
+        if (cached?.key === cacheKey)
+            return cached.namespaces;
+        const namespaces = new Set();
+        for (const file of sources)
+            for (const match of file.bytes
+                .toString('utf8')
+                .matchAll(/^\s*add_namespace\s*=\s*"?([\w.]+)"?/gmu))
+                namespaces.add(match[1]);
+        this.#eventNamespaces.set(workspaceId, { key: cacheKey, namespaces });
+        return namespaces;
+    }
     /** Every active event definition, cached by the hashes of the events files. */
     eventPopupContext(workspaceId, snapshot) {
         const sources = [...snapshot.index.files.values()]
@@ -170,7 +229,9 @@ export class ReferenceToolService {
             return cached.context;
         const localisation = new Map();
         for (const symbol of snapshot.index.symbols) {
-            if (symbol.kind !== 'localisation' || !symbol.id.startsWith('l_english:'))
+            if (symbol.kind !== 'localisation' ||
+                symbol.sourceShadowed ||
+                !symbol.id.startsWith('l_english:'))
                 continue;
             const key = symbol.id.slice('l_english:'.length);
             const previous = localisation.get(key);
@@ -216,7 +277,15 @@ export class ReferenceToolService {
         return context;
     }
 }
-const playerTextPatterns = [
+/** The families file mode checks, the helpers and databases it resolves, and localisation. */
+const fileCheckPatterns = [
+    'events/**/*.txt',
+    'common/decisions/**/*.txt',
+    'common/national_focus/**/*.txt',
+    'common/on_actions/**/*.txt',
+    'common/scripted_effects/**/*.txt',
+    'common/scripted_triggers/**/*.txt',
+    ...Object.keys(implicitTriggerSources).map((folder) => `common/${folder}/*.txt`),
     'localisation/**/*_l_english.yml',
     'common/scripted_localisation/**/*.txt',
 ];

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

@@ -7,7 +7,8 @@ const tooltipTriggerBlocks = {
 };
 /** 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;
+/** Colour codes; text icons (£) are legible on parchment and stay allowed. */
+const colourCode = '§';
 function blockOf(entry) {
     return entry.value.type === 'block' ? entry.value : undefined;
 }
@@ -61,14 +62,14 @@ export function playerTextFindings(family, document, context) {
             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)) {
+        if (text.value.includes(colourCode)) {
             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)) {
+                if (branch?.value.includes(colourCode) === true) {
                     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;
                 }

package/dist/hoi4_agent_tools/reference/script-validation.js

@@ -4,6 +4,7 @@ import { ServiceError } from '../core/result.js';
 import { locationFor, parseClausewitz, } from '../core/source/index.js';
 import { repeatedPopupFindings } from './event-popups.js';
 import { playerTextFindings, playerTextPosition } from './player-text.js';
+import { knownMistakeFindings } from './known-mistakes.js';
 import { editDistance } from './suggestions.js';
 import { publicReferenceSection } from './service.js';
 const MAX_COMMANDS = 256;
@@ -487,10 +488,26 @@ export async function validateScript(references, workspace, input, signal, file)
             scope: UNKNOWN_SCOPE,
             line: position.line,
             column: position.column,
-            message: finding.message,
+            message: finding.message.slice(0, 500),
             suggestions: [],
         });
     }
+    const knownMistakes = plan.family === 'snippet' || plan.family === 'unsupported' ? undefined : file?.knownMistakes;
+    if (knownMistakes !== undefined)
+        for (const finding of knownMistakeFindings(plan.family, document, knownMistakes)) {
+            const position = playerTextPosition(documentPath, document.lineIndex, finding);
+            findings.push({
+                code: finding.code,
+                status: finding.rule.severity,
+                command: finding.command.slice(0, 256),
+                kind: 'definition',
+                scope: UNKNOWN_SCOPE,
+                line: position.line,
+                column: position.column,
+                message: finding.message.slice(0, 500),
+                suggestions: [],
+            });
+        }
     const unresolvedCount = findings.filter(({ status }) => status === 'unresolved').length;
     const invalid = findings.some(({ status }) => status === 'error');
     const truncated = visited > commandLimit;
@@ -513,6 +530,7 @@ export async function validateScript(references, workspace, input, signal, file)
             'declared_scope',
             ...(playerTextChecked ? ['player_text'] : []),
             ...(eventPopups === undefined ? [] : ['event_popups']),
+            ...(knownMistakes === undefined ? [] : ['known_mistakes']),
         ],
         parametersChecked: false,
         documentation: {

package/dist/hoi4_agent_tools/reference/service.js

@@ -6,6 +6,7 @@ import { ServiceError } from '../core/result.js';
 import { isWithin } from '../core/workspace.js';
 import { prepareSource, verifySource, readBoundedFile, } from '../core/scanner.js';
 import { decodeSource } from '../core/source/encoding.js';
+import { activeKnownMistakes } from './known-mistakes.js';
 import { readBoundedJsonLines } from './lines.js';
 import { RankingIndex, sectionTerms } from './ranking.js';
 const MAX_FILES = 512;
@@ -544,6 +545,11 @@ export class ReferenceService {
             missing,
             coverage: inventory.coverage,
             skipped: inventory.skipped,
+            knownMistakes: activeKnownMistakes(input.surface).map(({ id, title, fix }) => ({
+                id,
+                title,
+                fix,
+            })),
         };
     }
     publicSection(section) {

package/dist/hoi4_agent_tools/runtime.js

@@ -1,11 +1,12 @@
 import { lstat, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
 import { CoreEngine } from './core/engine.js';
 import { ServiceError } from './core/result.js';
 import { WorkspaceResolver } from './core/workspace.js';
 import { CONFIG_VERSION } from './version.js';
+import { sweepTemporaryDirectories } from './core/temporary-directories.js';
 export function defaultConfigurationPath() {
     const configRoot = process.env.APPDATA ?? process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
     return path.join(configRoot, 'hoi4-agent-tools', 'config.json');
@@ -236,6 +237,18 @@ export async function createEngine(configPath = configurationPath()) {
         configuration = await automaticConfiguration();
     }
     const resolver = await WorkspaceResolver.create(configuration);
+    await sweepTemporaryDirectories(tmpdir(), {
+        protectedRoots: [
+            ...resolver
+                .list()
+                .flatMap((workspace) => [
+                ...workspace.roots.map((root) => root.path),
+                workspace.artifactRoot,
+                workspace.cacheRoot,
+            ]),
+            ...(resolver.serverState() === undefined ? [] : [resolver.serverState().root]),
+        ],
+    }).catch(() => undefined);
     const engine = new CoreEngine(resolver);
     await engine.initialize();
     return engine;

package/dist/hoi4_agent_tools/schemas/event.js

@@ -112,25 +112,6 @@ export function validateEventInspectRequest(value, context) {
             message: 'Impact analysis requires impactSubject',
         });
 }
-export const eventInspectRequestSchema = z
-    .object({
-    workspaceId: workspaceIdSchema,
-    mode: eventInspectModeSchema,
-    selector: eventSelectorSchema.optional(),
-    from: eventSelectorSchema.optional(),
-    to: eventSelectorSchema.optional(),
-    direction: eventDirectionSchema.optional(),
-    maxDepth: z.number().int().min(1).max(64).optional(),
-    maxNodes: z.number().int().min(1).max(5_000).optional(),
-    maxEdges: z.number().int().min(1).max(20_000).optional(),
-    expandHelpers: z.boolean().optional(),
-    stateSubject: eventStateSubjectSchema.optional(),
-    impactSubject: eventImpactSubjectSchema.optional(),
-    helperExpansion: helperExpansionRequestSchema.optional(),
-    refresh: z.boolean().optional(),
-})
-    .strict()
-    .superRefine(validateEventInspectRequest);
 export const eventRenderRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
@@ -172,3 +153,81 @@ export const eventCompareRequestSchema = z
 })
     .strict()
     .superRefine(validateEventCompareRequest);
+export const eventInspectToolModeSchema = z.enum([...eventInspectModeSchema.options, 'compare']);
+const compareOnlyFields = [
+    'before',
+    'after',
+    'proposedSources',
+    'maxChainNodes',
+    'render',
+    'maxRenderNodes',
+];
+const inspectOnlyFields = [
+    'from',
+    'to',
+    'direction',
+    'maxDepth',
+    'maxNodes',
+    'maxEdges',
+    'expandHelpers',
+    'stateSubject',
+    'impactSubject',
+    'helperExpansion',
+];
+/**
+ * Inspection and comparison share one tool: mode compare diffs a cached, artifact or proposed
+ * event graph against another, every other mode analyzes the current graph.
+ */
+export const eventInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    mode: eventInspectToolModeSchema,
+    selector: eventSelectorSchema.optional(),
+    from: eventSelectorSchema.optional(),
+    to: eventSelectorSchema.optional(),
+    direction: eventDirectionSchema.optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(5_000).optional(),
+    maxEdges: z.number().int().min(1).max(20_000).optional(),
+    expandHelpers: z.boolean().optional(),
+    stateSubject: eventStateSubjectSchema.optional(),
+    impactSubject: eventImpactSubjectSchema.optional(),
+    helperExpansion: helperExpansionRequestSchema.optional(),
+    before: eventGraphReferenceSchema.optional(),
+    after: eventGraphReferenceSchema.optional(),
+    proposedSources: z.array(eventProposedSourceSchema).min(1).max(64).optional(),
+    maxChainNodes: z.number().int().min(1).max(5_000).optional(),
+    render: z.boolean().optional(),
+    maxRenderNodes: z.number().int().min(1).max(240).optional(),
+    refresh: z.boolean().optional(),
+})
+    .strict()
+    .superRefine(validateEventInspectToolRequest);
+export function validateEventInspectToolRequest(value, context) {
+    const compare = value.mode === 'compare';
+    for (const field of compare ? inspectOnlyFields : compareOnlyFields)
+        if (value[field] !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: [field],
+                message: compare
+                    ? `${field} is not used by mode compare`
+                    : `${field} is used only by mode compare`,
+            });
+    if (compare)
+        validateEventCompareRequest(value, context);
+    else
+        validateEventInspectRequest(value, context);
+}
+/** Split an inspect request into a comparison or an analysis of the current graph. */
+export function splitEventInspectRequest(input) {
+    const { mode, ...rest } = input;
+    if (mode === 'compare') {
+        const request = { workspaceId: rest.workspaceId };
+        for (const field of [...compareOnlyFields, 'selector', 'refresh'])
+            if (rest[field] !== undefined)
+                request[field] = rest[field];
+        return { compare: true, request: eventCompareRequestSchema.parse(request) };
+    }
+    return { compare: false, request: { ...rest, mode } };
+}

package/dist/hoi4_agent_tools/schemas/focus-requests.js

@@ -77,10 +77,20 @@ export const focusRenderRequestSchema = z
     cropFocusIds: z.array(z.string().min(1).max(256)).max(16).optional(),
     columns: z.number().int().min(1).max(12).optional(),
     padding: z.number().int().min(0).max(1000).optional(),
+    png: z
+        .boolean()
+        .optional()
+        .describe('Default true: add a PNG with decoded source icons. False returns only the faster HTML, SVG and JSON.'),
 })
     .strict()
     .superRefine((value, context) => {
     const mode = value.mode ?? 'national';
+    if (value.png === false && (value.cropFocusIds?.length ?? 0) > 0)
+        context.addIssue({
+            code: 'custom',
+            path: ['cropFocusIds'],
+            message: 'cropFocusIds produce PNG crops; omit png or set it to true',
+        });
     const invalid = mode === 'national'
         ? [
             ['paletteId', value.paletteId],