hoi4-agent-tools 3.5.1 → 3.7.0

package/dist/hoi4_agent_tools/reference/service.js

@@ -1,15 +1,29 @@
-import { open, realpath, stat } from 'node:fs/promises';
+import { realpath } from 'node:fs/promises';
 import path from 'node:path';
-import fg from 'fast-glob';
+import { globFiles } from '../core/file-glob.js';
 import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
 import { ServiceError } from '../core/result.js';
 import { isWithin } from '../core/workspace.js';
-import { readBoundedLines } from './lines.js';
-import { readBoundedFile } from '../core/scanner.js';
+import { prepareSource, verifySource, readBoundedFile, } from '../core/scanner.js';
+import { decodeSource } from '../core/source/encoding.js';
+import { readBoundedJsonLines } from './lines.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;
+function referenceText(bytes) {
+    if (bytes.length >= 2 &&
+        ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff))) {
+        const payload = Buffer.from(bytes.subarray(2));
+        if (payload.length % 2 !== 0)
+            throw new ServiceError('REFERENCE_ENCODING_INVALID', 'UTF-16 reference text has an incomplete code unit');
+        if (bytes[0] === 0xfe)
+            payload.swap16();
+        return payload.toString('utf16le');
+    }
+    return decodeSource(bytes).text;
+}
 const searchStopWords = new Set([
     'a',
     'an',
@@ -78,7 +92,7 @@ function sectionize(root, filePath, content, revision) {
     const relative = path.relative(root.root, filePath).replaceAll('\\', '/');
     const title = path
         .basename(filePath)
-        .replace(/\.(md|log)$/u, '')
+        .replace(/\.(md|log)$/iu, '')
         .replaceAll('_', ' ')
         .replace(/ - Hearts of Iron 4 Wiki$/u, '');
     const headings = [];
@@ -95,7 +109,7 @@ function sectionize(root, filePath, content, revision) {
         if (match)
             headings.push({ heading: match[2].replace(/<a\b[^>]*><\/a>/gu, '').trim(), start: index });
         else if (root.kind === 'script_doc' &&
-            filePath.endsWith('.log') &&
+            filePath.toLowerCase().endsWith('.log') &&
             /^[A-Za-z_][A-Za-z0-9_.:-]*$/u.test(line.trim()) &&
             !/^\s/u.test(line) &&
             /^\s+\S/u.test(lines[index + 1] ?? '')) {
@@ -222,16 +236,33 @@ export class ReferenceService {
             this.#cacheBytes -= oldest[1].bytes;
         }
     }
-    async inventory(workspace, signal) {
+    async inventory(workspace, signal, sources) {
         const sections = [];
         const coverage = {
-            game_doc: { files: 0, sections: 0, unavailable: true },
-            wiki: { files: 0, sections: 0, unavailable: true },
-            script_doc: { files: 0, sections: 0, unavailable: true },
+            game_doc: {
+                files: 0,
+                sections: 0,
+                unavailable: true,
+                included: sources === undefined || sources.includes('game_doc'),
+            },
+            wiki: {
+                files: 0,
+                sections: 0,
+                unavailable: true,
+                included: sources === undefined || sources.includes('wiki'),
+            },
+            script_doc: {
+                files: 0,
+                sections: 0,
+                unavailable: true,
+                included: sources === undefined || sources.includes('script_doc'),
+            },
         };
         let skipped = 0;
         let bytes = 0;
         for (const root of sourceRoots(workspace)) {
+            if (sources !== undefined && !sources.includes(root.kind))
+                continue;
             signal?.throwIfAborted();
             let canonicalRoot;
             try {
@@ -250,80 +281,104 @@ export class ReferenceService {
                 throw new ServiceError('REFERENCE_ROOT_ESCAPE', 'Reference root resolves outside its configured workspace');
             }
             coverage[root.kind].unavailable = false;
-            const names = await fg(root.patterns, {
+            const names = await globFiles(root.patterns, {
                 cwd: canonicalRoot,
-                onlyFiles: true,
-                followSymbolicLinks: false,
-                dot: false,
+                caseSensitive: false,
+                ...(signal === undefined ? {} : { signal }),
             });
             names.sort(compareCodeUnits);
-            for (const name of names) {
+            for (let offset = 0; offset < names.length; offset += 8) {
                 signal?.throwIfAborted();
                 if (coverage[root.kind].files >= MAX_FILES || sections.length >= MAX_SECTIONS) {
-                    skipped++;
-                    continue;
-                }
-                const candidate = path.join(canonicalRoot, name);
-                const canonical = await realpath(candidate);
-                if (!isWithin(canonicalRoot, canonical)) {
-                    skipped++;
-                    continue;
-                }
-                const metadata = await stat(canonical);
-                if (metadata.size > MAX_FILE_BYTES || bytes + metadata.size > MAX_TOTAL_BYTES) {
-                    skipped++;
-                    continue;
+                    skipped += names.length - offset;
+                    break;
                 }
-                bytes += metadata.size;
-                coverage[root.kind].files++;
-                const key = `${root.kind}:${canonicalRoot}:${canonical}`;
-                const handle = await open(canonical, 'r');
-                let content;
+                const readRoot = { path: canonicalRoot };
+                const prepared = await Promise.allSettled(names.slice(offset, offset + 8).map((name) => prepareSource(readRoot, name, signal)));
+                const opened = prepared.flatMap((entry) => entry.status === 'fulfilled' ? [entry.value] : []);
                 try {
-                    const opened = await handle.stat();
-                    const resolvedAfterOpen = await realpath(canonical);
-                    const current = await stat(resolvedAfterOpen);
-                    if (!opened.isFile() ||
-                        !isWithin(canonicalRoot, resolvedAfterOpen) ||
-                        opened.dev !== current.dev ||
-                        opened.ino !== current.ino) {
+                    signal?.throwIfAborted();
+                    for (const entry of prepared) {
+                        if (entry.status !== 'rejected')
+                            continue;
+                        if (entry.reason instanceof ServiceError && entry.reason.code === 'SCAN_ROOT_ESCAPE') {
+                            skipped++;
+                            continue;
+                        }
                         throw new ServiceError('REFERENCE_SOURCE_CHANGED', 'Reference path changed while opening it; retry the request');
                     }
-                    content = await readBoundedFile(handle, Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - bytes + metadata.size), signal);
+                    const admittedSources = [];
+                    for (const source of opened) {
+                        if (!source.metadata.isFile() ||
+                            source.metadata.size > MAX_FILE_BYTES ||
+                            bytes + source.metadata.size > MAX_TOTAL_BYTES ||
+                            coverage[root.kind].files >= MAX_FILES) {
+                            skipped++;
+                            continue;
+                        }
+                        bytes += source.metadata.size;
+                        coverage[root.kind].files++;
+                        admittedSources.push(source);
+                    }
+                    const reads = await Promise.allSettled(admittedSources.map(async (source) => {
+                        const content = await readBoundedFile(source.handle, source.metadata.size, signal);
+                        await verifySource(readRoot, source);
+                        if (content.length !== source.metadata.size)
+                            throw new ServiceError('REFERENCE_SOURCE_CHANGED', 'Reference changed while it was being read; retry the request');
+                        return content;
+                    }));
+                    signal?.throwIfAborted();
+                    const failed = reads.find((entry) => entry.status === 'rejected');
+                    if (failed?.status === 'rejected')
+                        throw new ServiceError('REFERENCE_SOURCE_CHANGED', 'Reference changed while it was being read; retry the request');
+                    for (const [index, read] of reads.entries()) {
+                        if (read.status !== 'fulfilled')
+                            continue;
+                        const canonical = admittedSources[index].canonicalPath;
+                        const content = read.value;
+                        const key = `${root.kind}:${canonicalRoot}:${canonical}`;
+                        const revision = sha256Bytes(content);
+                        let cached = this.#cache.get(key);
+                        if (cached?.revision !== revision)
+                            cached = {
+                                revision,
+                                bytes: content.length,
+                                sections: sectionize(root, canonical, referenceText(content), revision),
+                            };
+                        this.retain(key, cached);
+                        const admitted = cached.sections.slice(0, MAX_SECTIONS - sections.length);
+                        if (admitted.length < cached.sections.length)
+                            skipped++;
+                        sections.push(...admitted);
+                        coverage[root.kind].sections += admitted.length;
+                    }
                 }
                 finally {
-                    await handle.close();
+                    await Promise.all(opened.map(({ handle }) => handle.close()));
                 }
-                bytes += content.length - metadata.size;
-                const revision = sha256Bytes(content);
-                let cached = this.#cache.get(key);
-                if (cached?.revision !== revision) {
-                    cached = {
-                        revision,
-                        bytes: content.length,
-                        sections: sectionize(root, canonical, content.toString('utf8'), revision),
-                    };
-                }
-                this.retain(key, cached);
-                const admitted = cached.sections.slice(0, MAX_SECTIONS - sections.length);
-                if (admitted.length < cached.sections.length)
-                    skipped++;
-                sections.push(...admitted);
-                coverage[root.kind].sections += admitted.length;
             }
         }
         return { sections, coverage, skipped };
     }
     async search(workspace, input, signal) {
-        const inventory = await this.inventory(workspace, 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 requested = results.length;
+        while (Buffer.byteLength(JSON.stringify(results), 'utf8') > MAX_REFERENCE_METADATA_BYTES &&
+            results.length > 1)
+            results.pop();
+        if (Buffer.byteLength(JSON.stringify(results), 'utf8') > MAX_REFERENCE_METADATA_BYTES)
+            throw new ServiceError('REFERENCE_RESPONSE_TOO_LARGE', 'Reference metadata exceeds the bounded reply');
         return {
-            results: matches.slice(0, input.limit).map(({ section, score, excerpt }) => ({
-                ...this.publicSection(section),
-                score,
-                excerpt,
-            })),
+            results,
             total: matches.length,
+            omitted: matches.length - results.length,
+            limitedByBytes: results.length < requested,
             coverage: inventory.coverage,
             skipped: inventory.skipped,
         };
@@ -364,7 +419,17 @@ export class ReferenceService {
             left.section.startLine - right.section.startLine);
     }
     async read(workspace, input, signal) {
-        const inventory = await this.inventory(workspace, signal);
+        let source = input.source;
+        if (source === undefined) {
+            for (const cached of this.#cache.values()) {
+                const section = cached.sections.find(({ id }) => id === input.id);
+                if (section !== undefined) {
+                    source = section.source;
+                    break;
+                }
+            }
+        }
+        const inventory = await this.inventory(workspace, signal, source === undefined ? undefined : [source]);
         const section = inventory.sections.find(({ id }) => id === input.id);
         if (section === undefined)
             throw new ServiceError('REFERENCE_SECTION_UNKNOWN', 'Reference section is not in this workspace');
@@ -373,7 +438,7 @@ export class ReferenceService {
                 currentRevision: section.revision,
             });
         const startLine = input.startLine ?? section.startLine;
-        const selected = readBoundedLines(section.lines, section.startLine, startLine, input.startColumn ?? 1, input.maxLines, 8_000);
+        const selected = readBoundedJsonLines(section.lines, section.startLine, startLine, input.startColumn ?? 1, input.maxLines, 8_000, 8_192);
         return {
             ...this.publicSection(section),
             sectionStartLine: section.startLine,
@@ -422,13 +487,20 @@ export class ReferenceService {
             return true;
         });
         const selected = prioritized.slice(0, input.limit);
+        const requestedCount = selected.length;
+        while (Buffer.byteLength(JSON.stringify(selected.map((section) => this.publicSection(section))), 'utf8') > MAX_REFERENCE_METADATA_BYTES &&
+            selected.length > 1)
+            selected.pop();
+        if (Buffer.byteLength(JSON.stringify(selected.map((section) => this.publicSection(section))), 'utf8') > MAX_REFERENCE_METADATA_BYTES)
+            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,
             })),
-            omitted: Math.max(0, prioritized.length - input.limit),
+            omitted: Math.max(0, prioritized.length - selected.length),
+            limitedByBytes: selected.length < requestedCount,
             omittedSources: required
                 .filter(({ section }) => !selected.some((entry) => entry.path === section.path && entry.source === section.source))
                 .map(({ name }) => name),

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

@@ -1,21 +1,72 @@
 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';
+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.includeReferences || input.kind === undefined
+            ? undefined
+            : narrowPatterns[input.kind];
+    const snapshot = await engine.scan(workspaceId, patterns === undefined ? {} : { patterns }, principal, signal);
     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
+    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))
-        .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder)
-        .slice(0, input.maxDefinitions)
+        .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 +81,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,16 +92,19 @@ 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 ?? [])]
@@ -70,11 +124,19 @@ 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,
+        definitionsTruncated: matchedDefinitions.length > definitions.length,
         definitions,
         references,
         referencesIncluded: input.includeReferences,
@@ -87,4 +149,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,
+        },
+    };
+}