@j0hanz/filesystem-mcp 1.7.3 → 1.9.0

package/dist/lib/file-operations/metadata.js

@@ -0,0 +1,889 @@
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_LIST_MAX_ENTRIES, DEFAULT_MAX_DEPTH, DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, getMimeType, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../constants.js';
+import { isAbortError } from '../errors.js';
+import { assertNotAborted, getFileType, isHidden, processInParallel, readFile, readFileWithStats, withAbort, withTimedAbortSignal, } from '../fs-helpers.js';
+import { assertAllowedFileAccess, isPathWithinDirectories, isSensitivePath, normalizePath, toPosixPath, validateExistingDirectory, validateExistingPath, validateExistingPathDetailed, } from '../paths.js';
+import { applyIndexedErrors, applyIndexedValues, isEntryAccessibleByType, isIgnoredByGitignore, loadRootGitignore, needsStatsForSort, resolveEntryType, resolveStopReason, withOptionalStoppedReason, } from './core.js';
+import { globEntries } from './traversal.js';
+const PERM_STRINGS = [
+    '---',
+    '--x',
+    '-w-',
+    '-wx',
+    'r--',
+    'r-x',
+    'rw-',
+    'rwx',
+];
+const UNKNOWN_PATH = '(unknown)';
+function getPermissions(mode) {
+    const ownerIndex = (mode >> 6) & 0b111;
+    const groupIndex = (mode >> 3) & 0b111;
+    const otherIndex = mode & 0b111;
+    const owner = PERM_STRINGS[ownerIndex] ?? '---';
+    const group = PERM_STRINGS[groupIndex] ?? '---';
+    const other = PERM_STRINGS[otherIndex] ?? '---';
+    return `${owner}${group}${other}`;
+}
+function buildFileInfoResult(name, requestedPath, isSymlink, stats, mimeType, symlinkTarget) {
+    const tokenEstimate = stats.isFile() ? Math.ceil(stats.size / 4) : undefined;
+    return {
+        name,
+        path: requestedPath,
+        type: isSymlink ? 'symlink' : getFileType(stats),
+        size: stats.size,
+        ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
+        created: stats.birthtime,
+        modified: stats.mtime,
+        accessed: stats.atime,
+        permissions: getPermissions(stats.mode),
+        isHidden: isHidden(name),
+        ...(mimeType !== undefined ? { mimeType } : {}),
+        ...(symlinkTarget !== undefined ? { symlinkTarget } : {}),
+    };
+}
+async function getSymlinkTarget(pathToRead, signal) {
+    assertNotAborted(signal);
+    try {
+        return await withAbort(fsp.readlink(pathToRead), signal);
+    }
+    catch (error) {
+        if (isAbortError(error))
+            throw error;
+        return undefined;
+    }
+}
+export async function getFileInfo(filePath, options = {}) {
+    const { signal } = options;
+    assertNotAborted(signal);
+    const { requestedPath, resolvedPath, isSymlink } = await validateExistingPathDetailed(filePath, signal);
+    assertAllowedFileAccess(requestedPath, resolvedPath);
+    const name = path.basename(requestedPath);
+    const ext = path.extname(name).toLowerCase();
+    const includeMimeType = options.includeMimeType !== false;
+    const mimeType = includeMimeType && ext.length > 0 ? getMimeType(ext) : undefined;
+    const symlinkTarget = isSymlink
+        ? await getSymlinkTarget(requestedPath, signal)
+        : undefined;
+    const stats = await withAbort(fsp.stat(resolvedPath), signal);
+    return buildFileInfoResult(name, requestedPath, isSymlink, stats, mimeType, symlinkTarget);
+}
+function buildEmptyResult() {
+    return {
+        results: [],
+        summary: { total: 0, succeeded: 0, failed: 0, totalSize: 0 },
+    };
+}
+async function processFileInfo(filePath, options) {
+    const info = await getFileInfo(filePath, options);
+    return { path: filePath, info };
+}
+function buildIndexedPathTasks(paths) {
+    const tasks = [];
+    for (let index = 0; index < paths.length; index += 1) {
+        const filePath = paths[index];
+        if (filePath === undefined)
+            continue;
+        tasks.push({ filePath, index });
+    }
+    return tasks;
+}
+async function readFileInfoInParallel(paths, options) {
+    return processInParallel(buildIndexedPathTasks(paths), async ({ filePath, index }) => {
+        const value = await processFileInfo(filePath, options);
+        options.onProgress?.();
+        return { index, value };
+    }, PARALLEL_CONCURRENCY, options.signal);
+}
+function calculateSummary(results) {
+    let succeeded = 0;
+    let failed = 0;
+    let totalSize = 0;
+    for (const result of results) {
+        if (result.info !== undefined) {
+            succeeded++;
+            totalSize += result.info.size;
+        }
+        else {
+            failed++;
+        }
+    }
+    return {
+        total: results.length,
+        succeeded,
+        failed,
+        totalSize,
+    };
+}
+export async function getMultipleFileInfo(paths, options = {}) {
+    if (paths.length === 0)
+        return buildEmptyResult();
+    const output = new Array(paths.length);
+    for (let index = 0; index < paths.length; index += 1) {
+        output[index] = { path: paths[index] ?? UNKNOWN_PATH };
+    }
+    const { results, errors } = await readFileInfoInParallel(paths, options);
+    applyIndexedValues(output, results);
+    applyIndexedErrors({
+        output,
+        errors,
+        resolveIndex: (failureIndex) => failureIndex >= 0 && failureIndex < output.length
+            ? failureIndex
+            : undefined,
+        buildValue: (resolvedIndex, error) => ({
+            path: paths[resolvedIndex] ?? UNKNOWN_PATH,
+            error: error.message,
+        }),
+    });
+    return {
+        results: output,
+        summary: calculateSummary(output),
+    };
+}
+function normalizePattern(pattern) {
+    if (!pattern || pattern.length === 0)
+        return undefined;
+    return pattern;
+}
+function normalizeListOptions(options) {
+    const pattern = normalizePattern(options.pattern);
+    const normalized = {
+        includeHidden: options.includeHidden ?? false,
+        excludePatterns: options.excludePatterns ?? [],
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxEntries: options.maxEntries ?? DEFAULT_LIST_MAX_ENTRIES,
+        sortBy: options.sortBy ?? 'name',
+        includeSymlinkTargets: options.includeSymlinkTargets ?? false,
+        timeoutMs: options.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS,
+        ...(pattern !== undefined ? { pattern } : {}),
+    };
+    return normalized;
+}
+function sortEntries(entries, sortBy) {
+    const compare = {
+        name: (a, b) => a.name.localeCompare(b.name),
+        type: (a, b) => a.type.localeCompare(b.type),
+        size: (a, b) => (a.size ?? 0) - (b.size ?? 0),
+        modified: (a, b) => (a.modified?.getTime() ?? 0) - (b.modified?.getTime() ?? 0),
+    }[sortBy];
+    entries.sort(compare);
+}
+function resolveMaxDepth(normalized) {
+    if (!normalized.pattern) {
+        return 1;
+    }
+    return normalized.maxDepth;
+}
+async function* readDirectoryEntries(basePath, normalized, needsStats, signal) {
+    const dirents = await withAbort(fsp.readdir(basePath, { withFileTypes: true }), signal);
+    const entries = [];
+    for (const dirent of dirents) {
+        if (!normalized.includeHidden && isHidden(dirent.name)) {
+            continue;
+        }
+        entries.push({ dirent, entryPath: path.join(basePath, dirent.name) });
+    }
+    if (!needsStats) {
+        for (const entry of entries) {
+            yield {
+                path: entry.entryPath,
+                dirent: entry.dirent,
+            };
+        }
+        return;
+    }
+    const { results, errors } = await processInParallel(entries.map((_, index) => index), async (index) => {
+        const candidate = entries[index];
+        if (!candidate) {
+            throw new Error(`Entry index out of range: ${String(index)}`);
+        }
+        return {
+            index,
+            stats: await withAbort(fsp.lstat(candidate.entryPath), signal),
+        };
+    }, PARALLEL_CONCURRENCY, signal);
+    if (errors.length > 0) {
+        throw errors[0]?.error ?? new Error('Failed to read entry stats');
+    }
+    const statsByIndex = [];
+    for (const result of results) {
+        statsByIndex[result.index] = result.stats;
+    }
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (!entry)
+            continue;
+        const stats = statsByIndex[index];
+        yield {
+            path: entry.entryPath,
+            dirent: entry.dirent,
+            ...(stats ? { stats } : {}),
+        };
+    }
+}
+function createEntryStream(basePath, normalized, maxDepth, needsStats, signal) {
+    if (shouldUseFastPath(normalized, maxDepth)) {
+        return readDirectoryEntries(basePath, normalized, needsStats, signal);
+    }
+    return globEntries({
+        cwd: basePath,
+        pattern: normalized.pattern ?? '*',
+        excludePatterns: normalized.excludePatterns,
+        includeHidden: normalized.includeHidden,
+        baseNameMatch: false,
+        caseSensitiveMatch: true,
+        maxDepth,
+        followSymbolicLinks: false,
+        onlyFiles: false,
+        stats: needsStats,
+    });
+}
+function shouldUseFastPath(normalized, maxDepth) {
+    return (!normalized.pattern &&
+        normalized.excludePatterns.length === 0 &&
+        maxDepth === 1);
+}
+function resolveRelativePath(basePath, entryPath) {
+    return path.relative(basePath, entryPath) || path.basename(entryPath);
+}
+async function resolveSymlinkTarget(entryType, includeSymlinkTargets, entryPath) {
+    if (entryType !== 'symlink' || !includeSymlinkTargets) {
+        return undefined;
+    }
+    return fsp.readlink(entryPath).catch(() => undefined);
+}
+function updateTotals(entryType, totals) {
+    if (entryType === 'file')
+        totals.files += 1;
+    if (entryType === 'directory')
+        totals.directories += 1;
+}
+function buildDirectoryEntry(basePath, entry, entryType, needsStats, symlinkTarget) {
+    const size = needsStats && entry.stats?.isFile() ? entry.stats.size : undefined;
+    const modified = needsStats ? entry.stats?.mtime : undefined;
+    return {
+        name: path.basename(entry.path),
+        path: entry.path,
+        relativePath: resolveRelativePath(basePath, entry.path),
+        type: entryType,
+        ...(size !== undefined ? { size } : {}),
+        ...(modified !== undefined ? { modified } : {}),
+        ...(symlinkTarget !== undefined ? { symlinkTarget } : {}),
+    };
+}
+function trackSymlink(entryType, includeSymlinkTargets, counters) {
+    if (entryType === 'symlink' && !includeSymlinkTargets) {
+        counters.symlinksNotFollowed += 1;
+    }
+}
+function appendEntry(entry, entryType, symlinkTarget, ctx) {
+    updateTotals(entryType, ctx.totals);
+    ctx.entries.push(buildDirectoryEntry(ctx.basePath, entry, entryType, ctx.needsStats, symlinkTarget));
+}
+async function enqueueAppendEntry(entry, entryType, ctx, pending, flushPending) {
+    if (!ctx.includeSymlinkTargets) {
+        appendEntry(entry, entryType, undefined, ctx);
+        return;
+    }
+    // Preserve the original behavior: resolve symlink targets in parallel
+    // when includeSymlinkTargets is enabled (bounded by PARALLEL_CONCURRENCY).
+    const task = (async () => {
+        const symlinkTarget = await resolveSymlinkTarget(entryType, ctx.includeSymlinkTargets, entry.path);
+        appendEntry(entry, entryType, symlinkTarget, ctx);
+    })();
+    pending.push(task);
+    if (pending.length >= PARALLEL_CONCURRENCY) {
+        await flushPending();
+    }
+}
+function buildSummary(entries, totals, maxDepth, truncated, stoppedReason, counters) {
+    const summary = {
+        totalEntries: entries.length,
+        entriesScanned: entries.length,
+        entriesVisible: entries.length,
+        totalFiles: totals.files,
+        totalDirectories: totals.directories,
+        maxDepthReached: maxDepth,
+        truncated,
+        skippedInaccessible: counters.skippedInaccessible,
+        symlinksNotFollowed: counters.symlinksNotFollowed,
+    };
+    return withOptionalStoppedReason(summary, stoppedReason);
+}
+async function collectEntries(basePath, normalized, signal, needsStats, maxDepth) {
+    const entries = [];
+    const totals = { files: 0, directories: 0 };
+    const counters = { skippedInaccessible: 0, symlinksNotFollowed: 0 };
+    const basePathDirectories = [basePath];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
+    let truncated = false;
+    let stoppedReason;
+    const pending = [];
+    let acceptedCount = 0;
+    const stream = createEntryStream(basePath, normalized, maxDepth, needsStats, signal);
+    const flushPending = async () => {
+        if (pending.length === 0)
+            return;
+        await Promise.allSettled(pending.splice(0));
+    };
+    const appendCtx = {
+        basePath,
+        needsStats,
+        includeSymlinkTargets: normalized.includeSymlinkTargets,
+        totals,
+        entries,
+    };
+    for await (const entry of stream) {
+        const stopReason = resolveStopReason({
+            signal,
+            current: acceptedCount,
+            max: normalized.maxEntries,
+            abortedReason: 'aborted',
+            maxReason: 'maxEntries',
+        });
+        if (stopReason) {
+            truncated = true;
+            stoppedReason = stopReason;
+            break;
+        }
+        const entryType = resolveEntryType(entry.dirent);
+        trackSymlink(entryType, normalized.includeSymlinkTargets, counters);
+        const accessible = await isEntryAccessibleByType(entry.path, entryType, basePathDirectories, signal, accessDeps);
+        if (!accessible) {
+            counters.skippedInaccessible += 1;
+            continue;
+        }
+        acceptedCount += 1;
+        await enqueueAppendEntry(entry, entryType, appendCtx, pending, flushPending);
+    }
+    if (normalized.includeSymlinkTargets) {
+        await flushPending();
+    }
+    return { entries, totals, truncated, stoppedReason, counters };
+}
+async function executeListDirectory(basePath, normalized, signal) {
+    const needsStats = needsStatsForSort(normalized.sortBy);
+    const maxDepth = resolveMaxDepth(normalized);
+    const { entries, totals, truncated, stoppedReason, counters } = await collectEntries(basePath, normalized, signal, needsStats, maxDepth);
+    sortEntries(entries, normalized.sortBy);
+    return {
+        entries,
+        summary: buildSummary(entries, totals, maxDepth, truncated, stoppedReason, counters),
+    };
+}
+export async function listDirectory(dirPath, options = {}) {
+    const normalized = normalizeListOptions(options);
+    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
+        const basePath = await validateExistingDirectory(dirPath, signal);
+        const { entries, summary } = await executeListDirectory(basePath, normalized, signal);
+        return { path: basePath, entries, summary };
+    });
+}
+function toSafeNonNegativeInt(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const asInt = Math.floor(value);
+    return asInt >= 0 ? asInt : fallback;
+}
+function toSafePositiveInt(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const asInt = Math.floor(value);
+    return asInt > 0 ? asInt : fallback;
+}
+function toSafeBoolean(value, fallback) {
+    if (typeof value !== 'boolean')
+        return fallback;
+    return value;
+}
+function normalizeTreeOptions(options) {
+    return {
+        maxDepth: toSafeNonNegativeInt(options.maxDepth, 5),
+        maxEntries: toSafeNonNegativeInt(options.maxEntries, 1000),
+        includeHidden: toSafeBoolean(options.includeHidden, false),
+        includeIgnored: toSafeBoolean(options.includeIgnored, false),
+        timeoutMs: toSafePositiveInt(options.timeoutMs, DEFAULT_SEARCH_TIMEOUT_MS),
+    };
+}
+function ensureParentNodes(rootNode, nodeByPath, relativePath) {
+    const normalized = toPosixPath(relativePath);
+    if (normalized.length === 0 || normalized === '.')
+        return rootNode;
+    const segments = [];
+    for (const segment of normalized.split('/')) {
+        if (segment.length > 0) {
+            segments.push(segment);
+        }
+    }
+    const parentSegmentCount = Math.max(0, segments.length - 1);
+    let current = rootNode;
+    let currentPath = '';
+    for (let index = 0; index < parentSegmentCount; index += 1) {
+        const segment = segments[index];
+        if (!segment)
+            continue;
+        currentPath =
+            currentPath.length === 0
+                ? segment
+                : path.posix.join(currentPath, segment);
+        let child = nodeByPath.get(currentPath);
+        if (!child) {
+            child = {
+                name: segment,
+                type: 'directory',
+                relativePath: currentPath,
+                children: [],
+            };
+            nodeByPath.set(currentPath, child);
+            current.children ??= [];
+            current.children.push(child);
+        }
+        current = child;
+    }
+    return current;
+}
+function sortTree(node) {
+    if (!node.children)
+        return;
+    node.children.sort(compareTreeEntries);
+    for (const child of node.children) {
+        sortTree(child);
+    }
+}
+function compareTreeEntries(a, b) {
+    const diff = getTreeTypeRank(a.type) - getTreeTypeRank(b.type);
+    if (diff !== 0)
+        return diff;
+    return a.name.localeCompare(b.name);
+}
+function getTreeTypeRank(type) {
+    if (type === 'directory')
+        return 0;
+    if (type === 'file')
+        return 1;
+    return 2;
+}
+async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps) {
+    const type = resolveEntryType(entry.dirent);
+    const isAccessible = await isEntryAccessibleByType(entry.path, type, rootDirectories, signal, accessDeps);
+    if (!isAccessible) {
+        return null;
+    }
+    if (gitignoreMatcher &&
+        isIgnoredByGitignore(gitignoreMatcher, root, entry.path, {
+            isDirectory: type === 'directory',
+        })) {
+        return null;
+    }
+    const relative = path.relative(root, entry.path) || path.basename(entry.path);
+    const relativePosix = toPosixPath(relative);
+    const name = path.basename(entry.path);
+    return { type, relativePosix, name };
+}
+function upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent) {
+    const ensureDirectoryShape = (node) => {
+        if (node.type === 'directory') {
+            node.children ??= [];
+        }
+        else {
+            delete node.children;
+        }
+    };
+    const maybeUpdateType = (existing, nextType) => {
+        if (existing.type === nextType)
+            return;
+        const preservePopulatedDirectory = existing.type === 'directory' &&
+            Array.isArray(existing.children) &&
+            existing.children.length > 0;
+        if (preservePopulatedDirectory)
+            return;
+        existing.type = nextType;
+        ensureDirectoryShape(existing);
+    };
+    const attachChild = (child) => {
+        parent.children ??= [];
+        let seen = childPathIndexByParent.get(parent);
+        if (!seen) {
+            seen = new Set();
+            for (const entry of parent.children) {
+                seen.add(entry.relativePath);
+            }
+            childPathIndexByParent.set(parent, seen);
+        }
+        const key = child.relativePath;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        parent.children.push(child);
+    };
+    const existing = nodeByPath.get(resolved.relativePosix);
+    if (existing) {
+        // Avoid duplicate directory nodes when a child file is encountered before the directory entry.
+        // Prefer preserving an existing populated directory node over overwriting it.
+        maybeUpdateType(existing, resolved.type);
+        existing.name = resolved.name;
+        existing.relativePath = resolved.relativePosix;
+        ensureDirectoryShape(existing);
+        attachChild(existing);
+        return;
+    }
+    const node = {
+        name: resolved.name,
+        type: resolved.type,
+        relativePath: resolved.relativePosix,
+        ...(resolved.type === 'directory' ? { children: [] } : {}),
+    };
+    nodeByPath.set(resolved.relativePosix, node);
+    attachChild(node);
+}
+export function formatTreeAscii(tree) {
+    const lines = [];
+    const walk = (node, prefix, isLast, isRoot) => {
+        let connector = '';
+        let linePrefix = '';
+        if (!isRoot) {
+            connector = isLast ? '└── ' : '├── ';
+            linePrefix = prefix;
+        }
+        lines.push(`${linePrefix}${connector}${node.name}`);
+        if (!node.children || node.children.length === 0)
+            return;
+        let nextPrefix = '';
+        if (!isRoot) {
+            const continuation = isLast ? '    ' : '│   ';
+            nextPrefix = `${prefix}${continuation}`;
+        }
+        const count = node.children.length;
+        for (let index = 0; index < count; index += 1) {
+            const child = node.children[index];
+            if (child) {
+                walk(child, nextPrefix, index === count - 1, false);
+            }
+        }
+    };
+    walk(tree, '', true, true);
+    return lines.join('\n');
+}
+export async function treeDirectory(dirPath, options = {}) {
+    const normalized = normalizeTreeOptions(options);
+    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
+        const root = await validateExistingDirectory(dirPath, signal);
+        const rootNormalized = normalizePath(root);
+        const rootDirectories = [rootNormalized];
+        const accessDeps = {
+            normalizePath,
+            isPathWithinDirectories,
+            isSensitivePath,
+            validateSymlinkPath: validateExistingPathDetailed,
+        };
+        const excludePatterns = normalized.includeIgnored
+            ? []
+            : DEFAULT_EXCLUDE_PATTERNS;
+        const gitignoreMatcher = normalized.includeIgnored
+            ? null
+            : await loadRootGitignore(root, signal);
+        const rootNode = {
+            name: path.basename(root) || root,
+            type: 'directory',
+            relativePath: '.',
+            children: [],
+        };
+        const nodeByPath = new Map();
+        const childPathIndexByParent = new WeakMap();
+        let totalEntries = 0;
+        let truncated = false;
+        const stream = globEntries({
+            cwd: root,
+            pattern: '**/*',
+            excludePatterns,
+            includeHidden: normalized.includeHidden,
+            baseNameMatch: false,
+            caseSensitiveMatch: true,
+            maxDepth: normalized.maxDepth,
+            followSymbolicLinks: false,
+            onlyFiles: false,
+            stats: false,
+            suppressErrors: true,
+        });
+        for await (const entry of stream) {
+            const stopReason = resolveStopReason({
+                signal,
+                current: totalEntries,
+                max: normalized.maxEntries,
+                abortedReason: 'aborted',
+                maxReason: 'maxEntries',
+            });
+            if (stopReason) {
+                truncated = true;
+                break;
+            }
+            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps);
+            if (!resolved) {
+                continue;
+            }
+            const parent = ensureParentNodes(rootNode, nodeByPath, resolved.relativePosix);
+            upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent);
+            totalEntries += 1;
+            options.onProgress?.({ current: totalEntries });
+        }
+        sortTree(rootNode);
+        return {
+            root,
+            tree: rootNode,
+            truncated,
+            totalEntries,
+        };
+    });
+}
+function estimateReadSize(stats, maxSize) {
+    // `readFile`/`readFileWithStats` are always invoked with a `maxSize` cap, so the
+    // combined budget should reflect the maximum number of bytes we might actually read.
+    return Math.min(stats.size, maxSize);
+}
+function buildReadOptions(options) {
+    const readOptions = {
+        encoding: options.encoding,
+        maxSize: options.maxSize,
+    };
+    applyLineSelection(readOptions, options);
+    return readOptions;
+}
+function buildReadMultipleResult(filePath, result) {
+    const output = {
+        path: filePath,
+        content: result.content,
+        truncated: result.truncated,
+        readMode: result.readMode,
+    };
+    if (result.totalLines !== undefined)
+        output.totalLines = result.totalLines;
+    if (result.head !== undefined)
+        output.head = result.head;
+    if (result.startLine !== undefined)
+        output.startLine = result.startLine;
+    if (result.endLine !== undefined)
+        output.endLine = result.endLine;
+    if (result.linesRead !== undefined)
+        output.linesRead = result.linesRead;
+    if (result.hasMoreLines !== undefined) {
+        output.hasMoreLines = result.hasMoreLines;
+    }
+    return output;
+}
+async function readSingleFile(task, readOptions) {
+    const { filePath, index, validPath, stats } = task;
+    const result = validPath && stats
+        ? await readFileWithStats(filePath, validPath, stats, readOptions)
+        : await readFile(filePath, readOptions);
+    return {
+        index,
+        value: buildReadMultipleResult(filePath, result),
+    };
+}
+async function readFilesInParallel(filesToProcess, options, signal, onReadComplete) {
+    const readOptions = buildReadOptions(options);
+    if (signal) {
+        readOptions.signal = signal;
+    }
+    return processInParallel(filesToProcess, async (task) => {
+        const result = await readSingleFile(task, readOptions);
+        onReadComplete?.();
+        return result;
+    }, PARALLEL_CONCURRENCY, signal);
+}
+function normalizeReadMultipleOptions(options) {
+    const normalized = {
+        encoding: options.encoding ?? 'utf-8',
+        maxSize: Math.min(options.maxSize ?? MAX_TEXT_FILE_SIZE, MAX_TEXT_FILE_SIZE),
+        maxTotalSize: options.maxTotalSize ?? DEFAULT_READ_MANY_MAX_TOTAL_SIZE,
+    };
+    applyLineSelection(normalized, options);
+    return normalized;
+}
+function applyLineSelection(target, source) {
+    if (source.head !== undefined)
+        target.head = source.head;
+    if (source.startLine !== undefined)
+        target.startLine = source.startLine;
+    if (source.endLine !== undefined)
+        target.endLine = source.endLine;
+}
+function resolveListDirectoryNormalizedOptions(options) {
+    const { signal, ...rest } = options;
+    return {
+        normalized: normalizeReadMultipleOptions(rest),
+        ...(signal ? { signal } : {}),
+    };
+}
+async function validateFile(filePath, index, signal) {
+    const validPath = await validateExistingPath(filePath, signal);
+    const stats = await withAbort(fsp.stat(validPath), signal);
+    return { filePath, index, validPath, stats };
+}
+function markRemainingSkipped(startIndex, total, skippedBudget) {
+    for (let index = startIndex; index < total; index += 1) {
+        skippedBudget.add(index);
+    }
+}
+async function tryValidateFile(filePath, index, signal) {
+    try {
+        return await validateFile(filePath, index, signal);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function validateBatch(tasks, signal) {
+    if (tasks.length === 0)
+        return new Map();
+    const { results } = await processInParallel(tasks, async (task) => tryValidateFile(task.filePath, task.index, signal), PARALLEL_CONCURRENCY, signal);
+    const infos = new Map();
+    for (const info of results) {
+        if (!info)
+            continue;
+        infos.set(info.index, info);
+    }
+    return infos;
+}
+function applyBudgetForRange(options) {
+    const { batchStart, batchEnd, totalFiles, maxTotalSize, maxSize, validated, skippedBudget, totalSize: startingTotalSize, } = options;
+    let totalSize = startingTotalSize;
+    for (let index = batchStart; index < batchEnd; index += 1) {
+        const info = validated.get(index);
+        if (!info)
+            continue;
+        const { exceeded, totalSize: nextTotalSize } = applyBudget(totalSize, estimateReadSize(info.stats, maxSize), maxTotalSize, index, totalFiles, skippedBudget);
+        if (exceeded) {
+            return { totalSize, exceeded: true };
+        }
+        totalSize = nextTotalSize;
+    }
+    return { totalSize, exceeded: false };
+}
+async function collectFileBudget(filePaths, maxTotalSize, maxSize, signal) {
+    const skippedBudget = new Set();
+    const validated = new Map();
+    let totalSize = 0;
+    const totalFiles = filePaths.length;
+    for (let batchStart = 0; batchStart < totalFiles; batchStart += PARALLEL_CONCURRENCY) {
+        const batchTasks = [];
+        const batchEnd = Math.min(batchStart + PARALLEL_CONCURRENCY, totalFiles);
+        for (let index = batchStart; index < batchEnd; index += 1) {
+            const filePath = filePaths[index];
+            if (!filePath)
+                continue;
+            if (validated.has(index))
+                continue;
+            batchTasks.push({ filePath, index });
+        }
+        const batchInfos = await validateBatch(batchTasks, signal);
+        for (const [index, info] of batchInfos) {
+            validated.set(index, info);
+        }
+        const budgetResult = applyBudgetForRange({
+            batchStart,
+            batchEnd,
+            totalFiles,
+            maxTotalSize,
+            maxSize,
+            validated,
+            skippedBudget,
+            totalSize,
+        });
+        const { exceeded, totalSize: nextTotalSize } = budgetResult;
+        if (exceeded) {
+            return { skippedBudget, validated };
+        }
+        totalSize = nextTotalSize;
+    }
+    return { skippedBudget, validated };
+}
+function buildOutput(filePaths) {
+    const output = new Array(filePaths.length);
+    for (let index = 0; index < filePaths.length; index += 1) {
+        output[index] = { path: filePaths[index] ?? UNKNOWN_PATH };
+    }
+    return output;
+}
+function resolveErrorOriginalIndex(failureIndex, filesToProcess, totalInputFiles) {
+    // processInParallel implementations vary: some return error indices relative to
+    // the submitted batch (filesToProcess), others may forward the task/index.
+    const batchIndex = filesToProcess[failureIndex]?.index;
+    if (typeof batchIndex === 'number' &&
+        batchIndex >= 0 &&
+        batchIndex < totalInputFiles) {
+        return batchIndex;
+    }
+    if (failureIndex >= 0 && failureIndex < totalInputFiles) {
+        return failureIndex;
+    }
+    return undefined;
+}
+function buildFilesToProcess(filePaths, validated, skippedBudget) {
+    const filesToProcess = [];
+    for (let index = 0; index < filePaths.length; index += 1) {
+        if (skippedBudget.has(index))
+            continue;
+        const filePath = filePaths[index];
+        if (!filePath)
+            continue;
+        const cached = validated.get(index);
+        if (cached) {
+            filesToProcess.push({
+                filePath,
+                index,
+                validPath: cached.validPath,
+                stats: cached.stats,
+            });
+            continue;
+        }
+        filesToProcess.push({ filePath, index });
+    }
+    return filesToProcess;
+}
+function applyBudget(totalSize, estimatedSize, maxTotalSize, index, totalFiles, skippedBudget) {
+    if (totalSize + estimatedSize > maxTotalSize) {
+        skippedBudget.add(index);
+        markRemainingSkipped(index + 1, totalFiles, skippedBudget);
+        return { totalSize, exceeded: true };
+    }
+    return { totalSize: totalSize + estimatedSize, exceeded: false };
+}
+function applySkippedBudget(output, skippedBudget, filePaths, maxTotalSize) {
+    for (const index of skippedBudget) {
+        const filePath = filePaths[index];
+        if (!filePath)
+            continue;
+        output[index] = {
+            path: filePath,
+            error: `Skipped: combined estimated read would exceed maxTotalSize (${maxTotalSize} bytes)`,
+        };
+    }
+}
+export async function readMultipleFiles(filePaths, options = {}) {
+    if (filePaths.length === 0)
+        return [];
+    const { normalized, signal } = resolveListDirectoryNormalizedOptions(options);
+    const output = buildOutput(filePaths);
+    const { skippedBudget, validated } = await collectFileBudget(filePaths, normalized.maxTotalSize, normalized.maxSize, signal);
+    const filesToProcess = buildFilesToProcess(filePaths, validated, skippedBudget);
+    const { results, errors } = await readFilesInParallel(filesToProcess, normalized, signal, options.onReadComplete);
+    applyIndexedValues(output, results);
+    applyIndexedErrors({
+        output,
+        errors,
+        resolveIndex: (failureIndex) => resolveErrorOriginalIndex(failureIndex, filesToProcess, filePaths.length),
+        buildValue: (resolvedIndex, error) => ({
+            path: filePaths[resolvedIndex] ?? UNKNOWN_PATH,
+            error: error.message,
+        }),
+    });
+    applySkippedBudget(output, skippedBudget, filePaths, normalized.maxTotalSize);
+    return output;
+}