hoi4-agent-tools 3.6.0 → 3.8.0

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

@@ -1,21 +1,96 @@
 import { ServiceError } from '../core/result.js';
 import { decodeSource } from '../core/source/encoding.js';
-import { readBoundedLines } from './lines.js';
+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) {
-    const snapshot = await engine.scan(workspaceId, {}, principal, signal);
+    const narrowPatterns = {
+        event: ['events/**/*.txt'],
+        scripted_effect: ['common/scripted_effects/**/*.txt'],
+        scripted_trigger: ['common/scripted_triggers/**/*.txt'],
+    };
+    const patterns = input.kind === 'event' && input.includeReferences
+        ? [
+            'events/**/*.txt',
+            'common/national_focus/**/*.txt',
+            'common/continuous_focus/**/*.txt',
+            'common/decisions/**/*.txt',
+            'common/ideas/**/*.txt',
+            'common/technologies/**/*.txt',
+            'common/scripted_effects/**/*.txt',
+            'common/scripted_triggers/**/*.txt',
+            'common/scripted_guis/**/*.txt',
+            'common/on_actions/**/*.txt',
+        ]
+        : 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 definitions = snapshot.index.symbols
-        .filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind))
-        .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder)
-        .slice(0, input.maxDefinitions)
+    const navigating = input.keyPath !== undefined || input.view === 'structure';
+    const matchedDefinitions = snapshot.index.symbols
+        .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');
+    const definitions = matchedDefinitions
+        .slice(0, navigating ? 1 : input.maxDefinitions)
         .map((entry, index) => {
         const source = snapshot.index.files.get(entry.path);
         const start = entry.location?.start.line;
         const end = entry.location?.end.line;
+        const navigation = navigating
+            ? (() => {
+                if (source === undefined ||
+                    entry.location === undefined ||
+                    /\.ya?ml$/iu.test(entry.path))
+                    throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Nested navigation requires an indexed Clausewitz definition');
+                return navigateSource(parseClausewitz(source.bytes, source.displayPath), {
+                    start: entry.location.start.offset,
+                    end: entry.location.end.offset,
+                }, input.keyPath ?? [], {
+                    structure: input.view === 'structure',
+                    maxChildren: input.maxChildren,
+                    childOffset: input.childOffset,
+                    maxLines: input.maxLines,
+                    ...(index === 0 && input.fromLine !== undefined
+                        ? { fromLine: input.fromLine }
+                        : {}),
+                    ...(index === 0 && input.fromColumn !== undefined
+                        ? { fromColumn: input.fromColumn }
+                        : {}),
+                });
+            })()
+            : undefined;
         const fromLine = index === 0 ? (input.fromLine ?? start) : start;
         if (fromLine !== undefined &&
             start !== undefined &&
@@ -30,7 +105,7 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
                 .slice((start ?? fromLine) - 1, end);
         const selected = fromLine === undefined || lines.length === 0
             ? null
-            : readBoundedLines(lines, start ?? fromLine, fromLine, index === 0 ? (input.fromColumn ?? 1) : 1, input.maxLines, 2_000);
+            : readBoundedJsonLines(lines, start ?? fromLine, fromLine, index === 0 ? (input.fromColumn ?? 1) : 1, input.maxLines, 2_000, 4_096);
         return {
             kind: entry.kind,
             id: entry.id,
@@ -41,20 +116,23 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
             sourceShadowed: entry.sourceShadowed,
             startLine: start ?? null,
             endLine: end ?? null,
-            fromLine: fromLine ?? null,
-            toLine: selected?.endLine ?? null,
-            nextLine: selected?.nextLine ?? null,
-            nextColumn: selected?.nextColumn ?? null,
-            text: selected?.text ?? '',
+            fromLine: navigation?.fromLine ?? fromLine ?? null,
+            toLine: navigation?.endLine ?? selected?.endLine ?? null,
+            nextLine: navigation === undefined ? (selected?.nextLine ?? null) : navigation.nextLine,
+            nextColumn: navigation === undefined ? (selected?.nextColumn ?? null) : navigation.nextColumn,
+            text: navigation?.text ?? selected?.text ?? '',
+            ...(navigation === undefined ? {} : { navigation: navigation.navigation }),
         };
     });
-    const semantic = input.includeReferences
-        ? scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true })
-        : undefined;
+    let semantic = input.includeReferences ? semanticCache.get(snapshot) : undefined;
+    if (input.includeReferences && semantic === undefined) {
+        semantic = scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true });
+        semanticCache.set(snapshot, semantic);
+    }
     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))
@@ -70,11 +148,26 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
         path: entry.path,
         line: entry.location?.start.line ?? null,
     }));
-    return {
+    const result = {
+        sourceScope: input.kind === 'event'
+            ? input.includeReferences
+                ? 'event_consumers'
+                : 'event_definitions'
+            : patterns === undefined
+                ? 'workspace_index'
+                : 'helper_definitions',
         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,
@@ -87,4 +180,18 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
             matchedReferences.length <= references.length,
         unresolvedReferenceCount: semantic?.unresolved.length ?? 0,
     };
+    while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000 &&
+        result.references.length > 0) {
+        result.references.pop();
+        result.referencesTruncated = true;
+        result.referencesComplete = false;
+    }
+    while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000 &&
+        result.definitions.length > 1) {
+        result.definitions.pop();
+        result.definitionsTruncated = true;
+    }
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000)
+        throw new ServiceError('REFERENCE_RESPONSE_TOO_LARGE', 'Selected source metadata exceeds the bounded reply; use entry-index selectors for long nested keys');
+    return result;
 }

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

@@ -0,0 +1,130 @@
+import { ServiceError } from '../core/result.js';
+import { locationFor } from '../core/source/lexer.js';
+import { readBoundedJsonLines } from './lines.js';
+function preview(text, limit) {
+    let end = Math.min(text.length, limit);
+    if (end > 0 &&
+        /[\uD800-\uDBFF]/u.test(text[end - 1]) &&
+        /[\uDC00-\uDFFF]/u.test(text[end] ?? ''))
+        end--;
+    return { text: text.slice(0, end), truncated: end < text.length };
+}
+function findEntry(block, range) {
+    for (const entry of block.entries) {
+        if (entry.start === range.start && entry.end === range.end)
+            return entry;
+        const value = entry.type === 'assignment' ? entry.value : entry;
+        if (value.type !== 'block' || value.start > range.start || value.end < range.end)
+            continue;
+        if (value.start === range.start && value.end === range.end)
+            return value;
+        const found = findEntry(value, range);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** Navigate actual parser nodes, preserving duplicate keys and exact source boundaries. */
+export function navigateSource(document, range, keyPath, options) {
+    if (document.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'))
+        throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Cannot navigate a source document with parse errors');
+    const definition = findEntry(document.root, range);
+    if (definition === undefined)
+        throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Indexed definition does not identify an exact parser node');
+    let selected = definition;
+    const resolvedPath = [];
+    for (const step of keyPath) {
+        const value = selected.type === 'assignment' ? selected.value : selected;
+        if (value.type !== 'block')
+            throw new ServiceError('SOURCE_PATH_NOT_BLOCK', 'Cannot navigate inside a scalar source value', { keyPath: resolvedPath });
+        if ('index' in step) {
+            const child = value.entries[step.index];
+            if (child === undefined)
+                throw new ServiceError('SOURCE_INDEX_UNKNOWN', 'No source child exists at the requested entry index', { index: step.index });
+            selected = child;
+            resolvedPath.push({ index: step.index });
+            continue;
+        }
+        const matches = value.entries.filter((entry) => entry.type === 'assignment' && entry.key.value === step.key);
+        if (step.occurrence === undefined && matches.length > 1)
+            throw new ServiceError('SOURCE_PATH_AMBIGUOUS', 'Repeated key requires an explicit zero-based occurrence', { key: step.key, occurrences: matches.length });
+        const occurrence = step.occurrence ?? 0;
+        const child = matches[occurrence];
+        if (child === undefined)
+            throw new ServiceError('SOURCE_PATH_UNKNOWN', 'No source child matches the requested key and occurrence', { key: step.key, occurrence });
+        selected = child;
+        resolvedPath.push(Buffer.byteLength(step.key, 'utf8') > 128
+            ? { index: value.entries.indexOf(child) }
+            : { key: step.key, occurrence });
+    }
+    const location = locationFor(document.path, document.lineIndex, selected.start, selected.end);
+    const fromLine = options.fromLine ?? location.start.line;
+    const fromColumn = options.fromColumn ?? (fromLine === location.start.line ? location.start.column : 1);
+    if (fromLine < location.start.line ||
+        fromLine > location.end.line ||
+        (fromLine === location.start.line && fromColumn < location.start.column) ||
+        (fromLine === location.end.line && fromColumn > location.end.column))
+        throw new ServiceError('SOURCE_POSITION_OUTSIDE_SELECTION', 'Requested position is outside the selected parser node');
+    const lines = document.text.split(/\r?\n/u).slice(location.start.line - 1, location.end.line);
+    lines[lines.length - 1] = lines.at(-1).slice(0, location.end.column - 1);
+    const read = options.structure
+        ? { text: '', endLine: location.end.line, nextLine: null, nextColumn: null }
+        : readBoundedJsonLines(lines, location.start.line, fromLine, fromColumn, options.maxLines, 2000, 4096);
+    const value = selected.type === 'assignment' ? selected.value : selected;
+    const entries = options.structure && value.type === 'block' ? value.entries : [];
+    const occurrences = new Map();
+    if (options.structure && options.childOffset > entries.length)
+        throw new ServiceError('SOURCE_CHILD_OFFSET_OUTSIDE_SELECTION', 'Child offset exceeds the selected block');
+    for (const entry of entries.slice(0, options.childOffset)) {
+        const key = entry.type === 'assignment' ? entry.key.value : null;
+        occurrences.set(key, (occurrences.get(key) ?? 0) + 1);
+    }
+    const candidates = entries
+        .slice(options.childOffset, options.childOffset + options.maxChildren)
+        .map((entry, index) => {
+        const key = entry.type === 'assignment' ? entry.key.value : null;
+        const occurrence = occurrences.get(key) ?? 0;
+        occurrences.set(key, occurrence + 1);
+        const childValue = entry.type === 'assignment' ? entry.value : entry;
+        const childLocation = locationFor(document.path, document.lineIndex, entry.start, entry.end);
+        const keyPreview = key === null ? null : preview(key, 1024);
+        const valuePreview = childValue.type === 'scalar' ? preview(childValue.value, 120) : null;
+        return {
+            key: keyPreview?.text ?? null,
+            index: options.childOffset + index,
+            keyTruncated: keyPreview?.truncated ?? false,
+            occurrence,
+            kind: childValue.type,
+            value: valuePreview?.text ?? null,
+            valueTruncated: valuePreview?.truncated ?? false,
+            startLine: childLocation.start.line,
+            endLine: childLocation.end.line,
+            childCount: childValue.type === 'block' ? childValue.entries.length : 0,
+        };
+    });
+    const children = [];
+    let childBytes = 2;
+    for (const child of candidates) {
+        const bytes = Buffer.byteLength(JSON.stringify(child), 'utf8') + 1;
+        if (childBytes + bytes > 6000)
+            break;
+        children.push(child);
+        childBytes += bytes;
+    }
+    return {
+        ...read,
+        fromLine,
+        navigation: {
+            keyPath: resolvedPath,
+            startLine: location.start.line,
+            startColumn: location.start.column,
+            endLine: location.end.line,
+            endColumn: location.end.column,
+            children,
+            omittedChildren: Math.max(0, entries.length - options.childOffset - children.length),
+            nextChildOffset: options.childOffset + children.length < entries.length
+                ? options.childOffset + children.length
+                : null,
+        },
+    };
+}

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);
+}