hoi4-agent-tools 3.7.0 → 3.8.1

package/dist/hoi4_agent_tools/reference/service.js

@@ -7,11 +7,15 @@ import { isWithin } from '../core/workspace.js';
 import { prepareSource, verifySource, readBoundedFile, } from '../core/scanner.js';
 import { decodeSource } from '../core/source/encoding.js';
 import { readBoundedJsonLines } from './lines.js';
+import { RankingIndex, sectionTerms } from './ranking.js';
 const MAX_FILES = 512;
 const MAX_FILE_BYTES = 2_000_000;
 const MAX_TOTAL_BYTES = 32_000_000;
 const MAX_SECTIONS = 20_000;
 const MAX_REFERENCE_METADATA_BYTES = 24_000;
+const PHRASE_CANDIDATES = 60;
+const EXACT_HEADING_SCORE = 1000;
+const sourceOrder = { game_doc: 0, wiki: 1, script_doc: 2 };
 function referenceText(bytes) {
     if (bytes.length >= 2 &&
         ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff))) {
@@ -24,68 +28,30 @@ function referenceText(bytes) {
     }
     return decodeSource(bytes).text;
 }
-const searchStopWords = new Set([
-    'a',
-    'an',
-    'and',
-    'at',
-    'be',
-    'can',
-    'come',
-    'do',
-    'does',
-    'for',
-    'from',
-    'how',
-    'in',
-    'is',
-    'of',
-    'the',
-    'to',
-    'where',
-    'with',
-    'work',
-]);
-function normalizeTerm(term) {
-    if (term === 'dated')
-        return 'date';
-    if (term.endsWith('ies') && term.length > 5)
-        return `${term.slice(0, -3)}y`;
-    if (term.endsWith('ses') && term.length > 5)
-        return term.slice(0, -2);
-    if (term.endsWith('s') && term.length > 4)
-        return term.slice(0, -1);
-    return term;
+/** The citation fields of a section, without its indexed text or term statistics. */
+export function publicReferenceSection(section) {
+    const { lines: _lines, terms: _terms, ...citation } = section;
+    return citation;
 }
-function queryTerms(query) {
-    return [
-        ...new Set((query.toLowerCase().match(/[a-z0-9_.:-]+/gu) ?? [])
-            .map(normalizeTerm)
-            .filter((term) => /[a-z0-9]/u.test(term) && !searchStopWords.has(term))),
-    ];
-}
-function containsTerm(text, term) {
-    if (term.length > 2)
-        return text.includes(term);
-    const escaped = term.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    return new RegExp(`(^|[^a-z0-9_])${escaped}($|[^a-z0-9_])`, 'u').test(text);
-}
-function snippet(lines, terms = []) {
-    let matching = -1;
-    let best = -1;
-    for (const [index, line] of lines.entries()) {
-        const count = terms.filter((term) => containsTerm(line.toLowerCase(), term)).length;
-        if (count > best) {
-            matching = index;
-            best = count;
-        }
-    }
-    const selected = lines
-        .slice(Math.max(0, matching), Math.max(0, matching) + 3)
+/** Up to three non-empty lines from `first`, trimmed to the 300-character excerpt bound. */
+function snippet(lines, first = 0) {
+    return lines
+        .slice(first, first + 3)
         .map((line) => line.trim())
         .filter(Boolean)
-        .join(' ');
-    return selected.slice(0, 300);
+        .join(' ')
+        .slice(0, 300);
+}
+// A Markdown table row whose first cell names a command, trigger, modifier, or on action.
+const identifierRow = /^\|\s*`?([A-Za-z_][A-Za-z0-9_@.:]*)`?\s*\|/u;
+const tableSeparator = /^\|\s*:?-{3,}/u;
+/** A closing fence repeats the opening character at least as often and has no info string. */
+function fenceMarker(line) {
+    const match = /^\s*(`{3,}|~{3,})(.*)$/u.exec(line);
+    if (match === null)
+        return undefined;
+    const marker = match[1];
+    return { character: marker[0], length: marker.length, info: match[2].trim() };
 }
 function sectionize(root, filePath, content, revision) {
     const lines = content.replace(/^\uFEFF/u, '').split(/\r?\n/u);
@@ -96,15 +62,25 @@ function sectionize(root, filePath, content, revision) {
         .replaceAll('_', ' ')
         .replace(/ - Hearts of Iron 4 Wiki$/u, '');
     const headings = [];
-    let inFence = false;
+    const rows = [];
+    let fence;
     for (let index = 0; index < lines.length; index += 1) {
         const line = lines[index];
-        if (/^\s*(```|~~~)/u.test(line)) {
-            inFence = !inFence;
+        const marker = fenceMarker(line);
+        if (fence === undefined && marker !== undefined) {
+            fence = marker;
             continue;
         }
-        if (inFence)
+        if (fence !== undefined) {
+            if (marker?.character === fence.character &&
+                marker.length >= fence.length &&
+                marker.info === '')
+                fence = undefined;
             continue;
+        }
+        const row = identifierRow.exec(line);
+        if (row !== null && !tableSeparator.test(lines[index + 1] ?? ''))
+            rows.push({ heading: row[1], start: index });
         const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/u.exec(line);
         if (match)
             headings.push({ heading: match[2].replace(/<a\b[^>]*><\/a>/gu, '').trim(), start: index });
@@ -118,24 +94,30 @@ function sectionize(root, filePath, content, revision) {
     }
     if (headings.length === 0 || headings[0].start > 0)
         headings.unshift({ heading: title, start: 0 });
-    return headings.map((current, index) => {
-        const end = headings[index + 1]?.start ?? lines.length;
-        const sectionLines = lines.slice(current.start, end);
-        const id = sha256Bytes(Buffer.from(`${root.kind}\0${relative}\0${current.start + 1}\0${current.heading}`, 'utf8'));
+    const section = (heading, start, end) => {
+        const sectionLines = lines.slice(start, end);
+        const id = sha256Bytes(Buffer.from(`${root.kind}\0${relative}\0${start + 1}\0${heading}`, 'utf8'));
         return {
             id,
             revision,
             source: root.kind,
             title,
-            heading: current.heading.slice(0, 512),
+            heading: heading.slice(0, 512),
             path: filePath,
-            startLine: current.start + 1,
+            startLine: start + 1,
             endLine: end,
             excerpt: snippet(sectionLines),
             authority: root.authority,
             lines: sectionLines,
+            terms: sectionTerms(title, heading, sectionLines),
         };
-    });
+    };
+    // Heading sections come first, so a page's opening section still names the page. Table
+    // rows follow as one-line sections that cite one exact command or modifier entry.
+    return [
+        ...headings.map((current, index) => section(current.heading, current.start, headings[index + 1]?.start ?? lines.length)),
+        ...rows.map((row) => section(row.heading, row.start, row.start + 1)),
+    ];
 }
 function sourceRoots(workspace) {
     const gameRoot = workspace.gameRoot ?? (workspace.registration.kind === 'game' ? workspace.modRoot : undefined);
@@ -222,6 +204,7 @@ const gameDocNames = {
 /** A workspace-private, read-only reference index over explicitly known local roots. */
 export class ReferenceService {
     #cache = new Map();
+    #indexes = new Map();
     #cacheBytes = 0;
     retain(key, value) {
         this.#cacheBytes -= this.#cache.get(key)?.bytes ?? 0;
@@ -362,12 +345,11 @@ export class ReferenceService {
     }
     async search(workspace, input, signal) {
         const inventory = await this.inventory(workspace, signal, input.sources);
-        const matches = this.rank(inventory.sections, input.query, input.sources);
-        const results = matches.slice(0, input.limit).map(({ section, score, excerpt }) => ({
-            ...this.publicSection(section),
-            score,
-            excerpt,
-        }));
+        const { ranked: matches, describe } = this.rank(inventory.sections, input.query);
+        const results = matches.slice(0, input.limit).map((match) => {
+            const { section, score, excerpt, matchLine } = describe(match);
+            return { ...this.publicSection(section), score, excerpt, matchLine };
+        });
         const requested = results.length;
         while (Buffer.byteLength(JSON.stringify(results), 'utf8') > MAX_REFERENCE_METADATA_BYTES &&
             results.length > 1)
@@ -383,40 +365,91 @@ export class ReferenceService {
             skipped: inventory.skipped,
         };
     }
-    rank(sections, question, sources) {
-        const query = question.toLowerCase();
-        const terms = queryTerms(query);
-        return sections
-            .flatMap((section) => {
-            if (sources !== undefined && !sources.includes(section.source))
-                return [];
-            const title = section.title.toLowerCase();
-            const heading = section.heading.toLowerCase();
-            const body = section.lines.join('\n').toLowerCase();
-            let matched = 0;
-            let score = 0;
-            for (const term of terms) {
-                const inTitle = containsTerm(title, term);
-                const inHeading = containsTerm(heading, term);
-                const inBody = containsTerm(body, term);
-                if (!inTitle && !inHeading && !inBody)
-                    continue;
-                matched++;
-                score += (inTitle ? 24 : 0) + (inHeading ? 18 : 0) + (inBody ? 3 : 0);
-            }
-            if (matched < Math.max(1, Math.ceil(terms.length * 0.6)))
-                return [];
-            if (heading === query)
-                score += 100;
-            else if (heading.includes(query))
-                score += 70;
-            if (body.includes(query))
-                score += 30;
-            return [{ section, score, excerpt: snippet(section.lines, terms) }];
-        })
-            .sort((left, right) => right.score - left.score ||
+    /** One index per distinct set of section revisions; IDF depends on the whole inventory. */
+    rankingIndex(sections) {
+        const parts = [];
+        let previous;
+        for (const section of sections) {
+            if (previous?.path !== section.path || previous.revision !== section.revision)
+                parts.push(`${section.source}\0${section.path}\0${section.revision}`);
+            previous = section;
+        }
+        const key = sha256Bytes(Buffer.from(parts.join('\n'), 'utf8'));
+        const cached = this.#indexes.get(key);
+        if (cached !== undefined) {
+            this.#indexes.delete(key);
+            this.#indexes.set(key, cached);
+            return cached;
+        }
+        const index = new RankingIndex(sections.map(({ terms }) => terms));
+        this.#indexes.set(key, index);
+        while (this.#indexes.size > 4) {
+            const oldest = this.#indexes.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#indexes.delete(oldest);
+        }
+        return index;
+    }
+    rank(sections, question) {
+        const index = this.rankingIndex(sections);
+        const plan = index.plan(question);
+        const scored = [];
+        for (const section of sections) {
+            const score = index.score(plan, section.terms, section.heading);
+            if (score !== undefined)
+                scored.push({ section, score: Math.round(score * 1000) / 1000 });
+        }
+        // Installed documentation precedes the wiki when both describe a command equally well.
+        const order = (left, right) => right.score - left.score ||
+            sourceOrder[left.section.source] - sourceOrder[right.section.source] ||
             compareCodeUnits(left.section.path, right.section.path) ||
-            left.section.startLine - right.section.startLine);
+            left.section.startLine - right.section.startLine;
+        scored.sort(order);
+        // Phrase adjacency is costlier to measure, so it only reorders the leading candidates.
+        const leading = scored.slice(0, PHRASE_CANDIDATES);
+        for (const entry of leading)
+            entry.score =
+                Math.round((entry.score + index.phraseBonus(plan, entry.section.lines)) * 1000) / 1000;
+        leading.sort(order);
+        scored.splice(0, leading.length, ...leading);
+        // An exact table row ranked above the section containing it is the sharper citation.
+        const rows = new Map();
+        const ranked = scored.filter(({ section }) => {
+            const above = rows.get(section.path) ?? [];
+            if (section.lines.length > 1 &&
+                above.some((line) => line > section.startLine && line < section.endLine + 1))
+                return false;
+            if (section.lines.length === 1)
+                rows.set(section.path, [...above, section.startLine]);
+            return true;
+        });
+        // The same command documented in several sources says little new after its first
+        // citation. Later copies wait behind distinct answers unless they match exactly.
+        const named = new Set();
+        const distinct = [];
+        const repeated = [];
+        for (const entry of ranked) {
+            const key = entry.section.heading.toLowerCase();
+            if (named.has(key) && entry.score < EXACT_HEADING_SCORE)
+                repeated.push(entry);
+            else
+                distinct.push(entry);
+            named.add(key);
+        }
+        ranked.splice(0, ranked.length, ...distinct, ...repeated);
+        return {
+            ranked,
+            describe: ({ section, score }) => {
+                const offset = index.bestLine(plan, section.lines);
+                return {
+                    section,
+                    score,
+                    excerpt: snippet(section.lines, offset),
+                    matchLine: section.startLine + offset,
+                };
+            },
+        };
     }
     async read(workspace, input, signal) {
         let source = input.source;
@@ -451,7 +484,8 @@ export class ReferenceService {
     async context(workspace, input, signal) {
         const inventory = await this.inventory(workspace, signal);
         const wanted = surfaceNames[input.surface];
-        const ranked = input.question === undefined ? [] : this.rank(inventory.sections, input.question);
+        const ranking = input.question === undefined ? undefined : this.rank(inventory.sections, input.question);
+        const ranked = ranking?.ranked ?? [];
         const required = [];
         const missing = [];
         const includeRequired = (name, section) => {
@@ -495,10 +529,13 @@ export class ReferenceService {
             throw new ServiceError('REFERENCE_RESPONSE_TOO_LARGE', 'Reference metadata exceeds the bounded reply');
         return {
             surface: input.surface,
-            sections: selected.map((section) => ({
-                ...this.publicSection(section),
-                excerpt: ranked.find((entry) => entry.section.id === section.id)?.excerpt ?? section.excerpt,
-            })),
+            sections: selected.map((section) => {
+                const match = ranked.find((entry) => entry.section.id === section.id);
+                if (match === undefined || ranking === undefined)
+                    return this.publicSection(section);
+                const { excerpt, matchLine } = ranking.describe(match);
+                return { ...this.publicSection(section), excerpt, matchLine };
+            }),
             omitted: Math.max(0, prioritized.length - selected.length),
             limitedByBytes: selected.length < requestedCount,
             omittedSources: required
@@ -510,7 +547,6 @@ export class ReferenceService {
         };
     }
     publicSection(section) {
-        const { lines: _lines, ...publicSection } = section;
-        return publicSection;
+        return publicReferenceSection(section);
     }
 }

package/dist/hoi4_agent_tools/reference/source-locate.js

@@ -0,0 +1,156 @@
+/**
+ * Source position lookup: map a file and line to the indexed definitions that contain it and
+ * to the exact chain of Clausewitz assignments enclosing it.
+ *
+ * The returned `keyPath` is relative to the innermost containing definition, so an agent can
+ * pass that definition's `id`, `kind`, and `keyPath` to `hoi4.source_lookup` navigation. The
+ * chain is derived from parser nodes, preserving repeated keys through zero-based occurrences.
+ */
+import path from 'node:path';
+import { ServiceError } from '../core/result.js';
+import { isWithin } from '../core/workspace.js';
+import { positionAt } from '../core/source/lexer.js';
+import { parseClausewitz } from '../core/source/parser.js';
+const MAX_OWNERS = 8;
+const MAX_CHAIN = 24;
+const MAX_KEY_BYTES = 128;
+const MAX_LINE_TEXT = 300;
+function samePath(left, right) {
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+/** Resolve a display, relative, or absolute path to one scanned file, preferring the active layer. */
+function selectFile(snapshot, requested) {
+    const normalized = requested.replaceAll('\\', '/').replace(/^\.\//u, '');
+    const absolute = path.isAbsolute(requested) ? path.resolve(requested) : undefined;
+    const candidates = [...snapshot.index.files.values()].filter((file) => file.displayPath === normalized ||
+        file.relativePath.replaceAll('\\', '/') === normalized ||
+        (absolute !== undefined && samePath(path.resolve(file.absolutePath), absolute)));
+    if (candidates.length === 0)
+        throw new ServiceError('SOURCE_FILE_NOT_INDEXED', 'No indexed source file matches the path; use a mod-relative path such as events/example.txt');
+    return candidates.find(({ shadowedBy }) => shadowedBy === undefined) ?? candidates[0];
+}
+/**
+ * Scan only the requested file's folder family in every layer. Definitions and same-path
+ * overrides of a source position live beside it, so the whole workspace index is unnecessary.
+ */
+export function locatePatterns(engine, workspaceId, requested, principal) {
+    let relative = requested.replaceAll('\\', '/').replace(/^\.\//u, '');
+    if (path.isAbsolute(requested)) {
+        const absolute = path.resolve(requested);
+        const root = engine.resolver
+            .get(workspaceId, principal)
+            .roots.find((candidate) => isWithin(candidate.path, absolute));
+        if (root === undefined)
+            return undefined;
+        relative = path.relative(root.path, absolute).replaceAll('\\', '/');
+    }
+    else {
+        const label = /^[A-Za-z0-9_.-]+:(?!\/)(.+)$/u.exec(relative);
+        if (label !== null)
+            relative = label[1];
+    }
+    const extension = path.posix.extname(relative);
+    const directory = path.posix.dirname(relative);
+    if (relative.length === 0 ||
+        extension.length === 0 ||
+        /[*?[\]{}!]/u.test(relative) ||
+        relative.split('/').includes('..'))
+        return undefined;
+    return [directory === '.' ? `*${extension}` : `${directory}/**/*${extension}`];
+}
+function entryValue(entry) {
+    return entry.type === 'assignment' ? entry.value : entry;
+}
+export function locateSource(snapshot, requestedPath, line, requestedColumn) {
+    const file = selectFile(snapshot, requestedPath);
+    const document = parseClausewitz(file.bytes, file.displayPath);
+    const starts = document.lineIndex.lineStarts;
+    if (line > starts.length)
+        throw new ServiceError('SOURCE_LINE_OUTSIDE_FILE', 'Requested line is beyond the end of the file', {
+            lines: starts.length,
+        });
+    const lineStart = starts[line - 1];
+    const lineEnd = line < starts.length ? starts[line] : document.text.length;
+    const lineText = document.text.slice(lineStart, lineEnd).replace(/\r?\n$/u, '');
+    // Without a column, land on the first non-blank character so an indented line selects its
+    // own assignment rather than the enclosing block.
+    const column = requestedColumn ?? Math.max(1, lineText.search(/\S/u) + 1);
+    if (column > lineText.length + 1)
+        throw new ServiceError('SOURCE_COLUMN_OUTSIDE_LINE', 'Requested column is beyond the end of the line');
+    const offset = lineStart + column - 1;
+    const owners = snapshot.index.symbols
+        .filter((symbol) => symbol.path === file.displayPath &&
+        symbol.location !== undefined &&
+        symbol.location.start.offset <= offset &&
+        offset < Math.max(symbol.location.end.offset, symbol.location.start.offset + 1))
+        .sort((left, right) => left.location.end.offset -
+        left.location.start.offset -
+        (right.location.end.offset - right.location.start.offset) ||
+        right.location.start.offset - left.location.start.offset);
+    const structureAvailable = !document.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+    const steps = [];
+    if (structureAvailable) {
+        let block = document.root;
+        while (block !== undefined) {
+            const index = block.entries.findIndex((entry) => entry.start <= offset && offset < Math.max(entry.end, entry.start + 1));
+            if (index < 0)
+                break;
+            const entry = block.entries[index];
+            const key = entry.type === 'assignment' ? entry.key.value : null;
+            const occurrence = key === null
+                ? 0
+                : block.entries
+                    .slice(0, index)
+                    .filter((candidate) => candidate.type === 'assignment' && candidate.key.value === key)
+                    .length;
+            steps.push({ entry, key, occurrence, index });
+            const value = entryValue(entry);
+            block = value.type === 'block' && value !== block ? value : undefined;
+        }
+    }
+    const lineOf = (position) => positionAt(document.lineIndex, position).line;
+    const chain = steps.slice(0, MAX_CHAIN).map(({ entry, key, occurrence, index }) => ({
+        key: key !== null && Buffer.byteLength(key, 'utf8') <= MAX_KEY_BYTES ? key : null,
+        occurrence,
+        index,
+        startLine: lineOf(entry.start),
+        endLine: lineOf(Math.max(entry.start, entry.end - 1)),
+    }));
+    // The key path continues from the innermost definition that is itself a chain node.
+    let keyPath = null;
+    if (structureAvailable)
+        for (const owner of owners) {
+            const anchor = steps.findIndex(({ entry }) => entry.start === owner.location.start.offset && entry.end === owner.location.end.offset);
+            if (anchor < 0)
+                continue;
+            keyPath = steps
+                .slice(anchor + 1)
+                .map(({ key, occurrence, index }) => key !== null && Buffer.byteLength(key, 'utf8') <= MAX_KEY_BYTES
+                ? { key, occurrence }
+                : { index });
+            break;
+        }
+    let text = lineText.slice(0, MAX_LINE_TEXT);
+    if (/[\uD800-\uDBFF]$/u.test(text))
+        text = text.slice(0, -1);
+    return {
+        path: file.displayPath,
+        rootKind: file.rootKind,
+        loadOrder: file.loadOrder,
+        shadowed: file.shadowedBy !== undefined,
+        line,
+        column,
+        text,
+        owners: owners.slice(0, MAX_OWNERS).map((owner) => ({
+            kind: owner.kind,
+            id: owner.id.slice(0, 1024),
+            startLine: owner.location.start.line,
+            endLine: owner.location.end.line,
+            overridden: owner.overridden,
+        })),
+        chain,
+        chainTruncated: steps.length > chain.length,
+        keyPath: keyPath === null || keyPath.length > MAX_CHAIN ? null : keyPath,
+        structureAvailable,
+    };
+}

package/dist/hoi4_agent_tools/reference/source-lookup.js

@@ -4,6 +4,8 @@ import { readBoundedJsonLines } from './lines.js';
 import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
 import { parseClausewitz } from '../core/source/parser.js';
 import { navigateSource } from './source-navigation.js';
+import { locatePatterns, locateSource } from './source-locate.js';
+import { nearestNames } from './suggestions.js';
 const semanticCache = new WeakMap();
 /** Exact source definitions and usage over the existing shared Clausewitz index. */
 export async function sourceLookup(engine, workspaceId, input, principal, signal) {
@@ -25,16 +27,38 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
             'common/scripted_guis/**/*.txt',
             'common/on_actions/**/*.txt',
         ]
-        : input.includeReferences || input.kind === undefined
-            ? undefined
-            : narrowPatterns[input.kind];
+        : input.path !== undefined
+            ? locatePatterns(engine, workspaceId, input.path, principal)
+            : input.includeReferences || input.kind === undefined
+                ? undefined
+                : narrowPatterns[input.kind];
     const snapshot = await engine.scan(workspaceId, patterns === undefined ? {} : { patterns }, principal, signal);
+    if (input.path !== undefined && input.line !== undefined)
+        return {
+            sourceScope: 'source_location',
+            revision: snapshot.revision,
+            complete: snapshot.complete,
+            skippedSourceCount: snapshot.skippedSourceCount,
+            definitionCount: 0,
+            definitionsTruncated: false,
+            referencesIncluded: false,
+            referenceCount: 0,
+            referencesTruncated: false,
+            referencesComplete: false,
+            unresolvedReferenceCount: 0,
+            location: locateSource(snapshot, input.path, input.line, input.column),
+            definitions: [],
+            references: [],
+        };
+    const symbol = input.symbol;
+    if (symbol === undefined)
+        throw new ServiceError('SOURCE_LOOKUP_TARGET_REQUIRED', 'Provide a symbol, or path and line');
     if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision) {
         throw new ServiceError('SOURCE_REVISION_STALE', 'Indexed source changed; look up the symbol again', { currentRevision: snapshot.revision });
     }
     const navigating = input.keyPath !== undefined || input.view === 'structure';
     const matchedDefinitions = snapshot.index.symbols
-        .filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind))
+        .filter((entry) => entry.id === symbol && (input.kind === undefined || entry.kind === input.kind))
         .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder);
     if (navigating && new Set(matchedDefinitions.map(({ kind }) => kind)).size > 1)
         throw new ServiceError('SOURCE_KIND_AMBIGUOUS', 'Nested navigation requires kind when the identifier has multiple symbol kinds');
@@ -108,7 +132,7 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
     const referenceIdentities = new Set();
     const matchedReferences = input.includeReferences
         ? [...snapshot.index.references, ...(semantic?.references ?? [])]
-            .filter((entry) => entry.to === input.symbol && (input.kind === undefined || entry.toKind === input.kind))
+            .filter((entry) => entry.to === symbol && (input.kind === undefined || entry.toKind === input.kind))
             .filter((entry) => {
             const key = `${entry.path}:${entry.location?.start.offset ?? 0}:${entry.toKind}:${entry.to}:${entry.kind}`;
             if (referenceIdentities.has(key))
@@ -135,8 +159,15 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
         revision: snapshot.revision,
         complete: snapshot.complete,
         skippedSourceCount: snapshot.skippedSourceCount,
-        definitionCount: snapshot.index.symbols.filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind)).length,
+        definitionCount: snapshot.index.symbols.filter((entry) => entry.id === symbol && (input.kind === undefined || entry.kind === input.kind)).length,
         definitionsTruncated: matchedDefinitions.length > definitions.length,
+        ...(matchedDefinitions.length === 0
+            ? {
+                suggestions: nearestNames(symbol, new Set(snapshot.index.symbols
+                    .filter((entry) => input.kind === undefined || entry.kind === input.kind)
+                    .map(({ id }) => id))),
+            }
+            : {}),
         definitions,
         references,
         referencesIncluded: input.includeReferences,

package/dist/hoi4_agent_tools/reference/suggestions.js

@@ -0,0 +1,38 @@
+/** Near-miss identifier suggestions shared by source lookup and script checks. */
+const MAX_DISTANCE = 3;
+/** Levenshtein distance, cut off above three edits because larger distances are not suggested. */
+export function editDistance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 0; i < a.length; i++) {
+        const next = [i + 1];
+        for (let j = 0; j < b.length; j++)
+            next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + Number(a[i] !== b[j])));
+        if (Math.min(...next) > MAX_DISTANCE)
+            return MAX_DISTANCE + 1;
+        row = next;
+    }
+    return row[b.length];
+}
+/**
+ * The closest candidates within three edits, nearest first. `budget` bounds the number of
+ * distance computations, so a very large index cannot make a missed lookup expensive.
+ */
+export function nearestNames(target, candidates, options = {}) {
+    if (target.length > 128)
+        return [];
+    let budget = options.budget ?? 20_000;
+    const scored = [];
+    for (const candidate of candidates) {
+        if (candidate === target || Math.abs(candidate.length - target.length) > MAX_DISTANCE)
+            continue;
+        if (budget-- <= 0)
+            break;
+        const distance = editDistance(target, candidate);
+        if (distance <= MAX_DISTANCE)
+            scored.push({ candidate, distance });
+    }
+    return scored
+        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate, 'en'))
+        .slice(0, options.limit ?? 5)
+        .map(({ candidate }) => candidate);
+}