@myagentroam/node 0.9.96 → 0.9.98

package/dist/service/workspace-code-navigation-service.js

@@ -1,18 +1,20 @@
-import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { constants, createReadStream, createWriteStream } from 'node:fs';
-import { access, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { access, open, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { posix, relative, resolve, sep } from 'node:path';
-import { createInterface } from 'node:readline';
-import { bundledCtagsPath, BUNDLED_CTAGS_VERSION } from '../ctags-binary.js';
+import { relative, resolve, sep } from 'node:path';
+import { supportsSymbolNavigationPath } from '@myagentroam/code-navigation/symbol-navigation';
+import { workspaceFileReferenceSchema } from '@myagentroam/protocol';
+import { bundledCtagsPath, BUNDLED_CTAGS_VERSION, repairBundledCtagsExecutable } from '../ctags-binary.js';
 import { nodeLog } from '../operational.js';
 import { normalizeWorkspacePath } from '../workspace.js';
+import { pathSpecifierResolver } from './code-navigation/navigation-resolution-registry.js';
+import { reparseFileReference } from './code-navigation/file-reference-parser.js';
+import { acquireBuild, buildIncrementalTags, ensurePrivateDirectory, manifestEntry, readManifest, removeInactiveGenerations, runCtags, sourceDelta, sourceFingerprint, tagsAvailable, tagsPath } from './code-navigation/ctags-index-storage.js';
+import { compareTagNames, firstTagOffset, parseTag, readTagLine } from './code-navigation/ctags-query.js';
+import { compareTargets, containsSymbol, sourceFileFingerprint, targetPreview, validatePathTarget, validateSymbolTarget } from './code-navigation/navigation-target-validator.js';
 const INDEX_SCHEMA_VERSION = 1;
 const INDEX_OPTIONS_VERSION = 2;
-const BUILD_TIMEOUT_MS = 120_000;
-const BUILD_QUEUE_LIMIT = 4;
-const BUILD_QUEUE_TIMEOUT_MS = 120_000;
 const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
 const MAX_INDEX_BYTES = 8 * 1024 * 1024 * 1024;
 const MAX_TAGS_BYTES = 512 * 1024 * 1024;
@@ -23,64 +25,6 @@ const MAX_TAG_LINE_BYTES = 16 * 1024;
 const READ_BLOCK_BYTES = 4096;
 const MAX_TARGET_LINE_SCAN_BYTES = MAX_SOURCE_BYTES;
 const MAX_TARGET_PREVIEW_CHARACTERS = 512;
-const NAVIGABLE_EXTENSIONS = new Set([
-    '.c',
-    '.cc',
-    '.cpp',
-    '.cs',
-    '.cxx',
-    '.dart',
-    '.ex',
-    '.exs',
-    '.fs',
-    '.fsx',
-    '.go',
-    '.h',
-    '.hh',
-    '.hpp',
-    '.hrl',
-    '.hs',
-    '.hxx',
-    '.java',
-    '.js',
-    '.jsx',
-    '.kt',
-    '.kts',
-    '.lua',
-    '.m',
-    '.mm',
-    '.php',
-    '.pl',
-    '.pm',
-    '.py',
-    '.pyw',
-    '.r',
-    '.rb',
-    '.rs',
-    '.scala',
-    '.scm',
-    '.sh',
-    '.sql',
-    '.swift',
-    '.ts',
-    '.tsx',
-    '.mts',
-    '.cts',
-    '.vb'
-]);
-const RELATIVE_SOURCE_SPECIFIER_HANDLERS = [
-    { importExtension: '.js', sourceExtensions: ['.ts', '.tsx'] },
-    { importExtension: '.jsx', sourceExtensions: ['.tsx'] },
-    { importExtension: '.mjs', sourceExtensions: ['.mts'] },
-    { importExtension: '.cjs', sourceExtensions: ['.cts'] }
-];
-const EXTENSIONLESS_RELATIVE_SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.py'];
-const DOTTED_PACKAGE_SPECIFIER_HANDLERS = [
-    { packageSuffixes: ['.java', '.kt', '.kts'] },
-    { packageSuffixes: ['.py', '.pyw', '/__init__.py'] }
-];
-let activeBuilds = 0;
-const buildWaiters = [];
 /**
  * Builds a demand-driven, standard u-ctags declaration index. It never keeps
  * a complete symbol table, watcher, or idle child process in memory.
@@ -100,7 +44,7 @@ export class WorkspaceCodeNavigationService {
     async prepare(workspace, input) {
         if (typeof input.path !== 'string' || input.path.length === 0 || input.path.length > 4096)
             throw new Error('SYMBOL_DEFINITION_INVALID');
-        if (!isNavigablePath(input.path))
+        if (!isCtagsSourcePath(input.path))
             return { state: 'READY' };
         if (!(await this.available()))
             return { state: 'UNAVAILABLE' };
@@ -143,17 +87,23 @@ export class WorkspaceCodeNavigationService {
     async definition(workspace, input) {
         const path = input.path;
         const symbol = input.symbol;
-        const specifier = input.specifier;
+        const reference = input.reference === undefined
+            ? undefined
+            : workspaceFileReferenceSchema.safeParse(input.reference);
         if (typeof path !== 'string' ||
             path.length === 0 ||
             path.length > 4096 ||
-            (typeof symbol === 'string' && typeof specifier === 'string') ||
-            (typeof symbol !== 'string' && typeof specifier !== 'string') ||
+            (typeof symbol === 'string' && reference !== undefined) ||
+            (typeof symbol !== 'string' && reference === undefined) ||
             (typeof symbol === 'string' && !isSymbol(symbol)) ||
-            (typeof specifier === 'string' && !isNavigableSpecifier(specifier)))
+            (reference !== undefined && !reference.success))
             throw new Error('SYMBOL_DEFINITION_INVALID');
-        if (typeof specifier === 'string')
-            return this.resolvePath(workspace, path, specifier);
+        if (reference !== undefined) {
+            const parsedReference = reparseFileReference(path, reference.data);
+            if (parsedReference === undefined)
+                return emptyDefinitionResult({ state: 'READY' });
+            return this.resolvePath(workspace, path, parsedReference);
+        }
         const requestedSymbol = symbol;
         if (!(await this.available()))
             return emptyDefinitionResult({ state: 'UNAVAILABLE' });
@@ -247,12 +197,22 @@ export class WorkspaceCodeNavigationService {
         this.forceFreshCandidates.set(workspaceId, (this.forceFreshCandidates.get(workspaceId) ?? 0) + 1);
     }
     async available() {
+        const executable = this.executable();
         try {
-            await access(this.executable(), constants.X_OK);
+            await access(executable, constants.X_OK);
             return true;
         }
         catch {
-            return false;
+            if (this.options.ctagsExecutable !== undefined)
+                return false;
+            try {
+                await repairBundledCtagsExecutable(this.options.platform ?? process.platform, this.options.architecture ?? process.arch);
+                await access(executable, constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
     }
     executable() {
@@ -276,7 +236,7 @@ export class WorkspaceCodeNavigationService {
         const entries = candidates
             .filter((entry) => entry.size !== null &&
             entry.size <= MAX_SOURCE_BYTES &&
-            isNavigablePath(entry.path) &&
+            isCtagsSourcePath(entry.path) &&
             !entry.path.includes('\n') &&
             !entry.path.includes('\r'))
             .sort((left, right) => left.path.localeCompare(right.path));
@@ -494,7 +454,7 @@ export class WorkspaceCodeNavigationService {
             }
             const valid = await Promise.all(records.map(async (record) => ({
                 record,
-                preview: await validateTarget(input.root, record, symbol, input.revalidateSourceFingerprint ? input.sourceFiles[record.path] : undefined)
+                preview: await validateSymbolTarget(input.root, record, symbol, input.revalidateSourceFingerprint ? input.sourceFiles[record.path] : undefined)
             })));
             return valid
                 .flatMap(({ record, preview }) => (preview === undefined ? [] : [{ ...record, preview }]))
@@ -525,7 +485,17 @@ export class WorkspaceCodeNavigationService {
             return { matches: [], truncated: false };
         }
     }
-    async resolvePath(workspace, currentPath, specifier) {
+    async resolvePath(workspace, currentPath, reference) {
+        const direct = await this.resolveDirectPathTargets(workspace, currentPath, reference);
+        if (direct.length > 0)
+            return {
+                state: 'READY',
+                targets: [],
+                references: [],
+                referenceTruncated: false,
+                paths: direct,
+                truncated: false
+            };
         const location = await this.indexLocation(workspace);
         this.locations.set(workspace.id, location);
         this.forgotten.delete(location.directory);
@@ -556,7 +526,7 @@ export class WorkspaceCodeNavigationService {
                 mustBuild: !current || forceRefreshGeneration !== undefined,
                 forceRefreshGeneration
             });
-        const resolved = await this.resolvePathTargets(input, currentPath, specifier);
+        const resolved = await this.resolvePathTargets(input, currentPath, reference);
         return {
             state: stale ? 'STALE' : 'READY',
             targets: [],
@@ -566,22 +536,42 @@ export class WorkspaceCodeNavigationService {
             truncated: input.truncated || resolved.truncated
         };
     }
-    async resolvePathTargets(input, currentPath, specifier) {
+    async resolveDirectPathTargets(workspace, currentPath, reference) {
+        const handler = pathSpecifierResolver(reference.languageId, reference.value);
+        const candidates = handler?.directCandidates?.(currentPath, reference.value) ?? [];
+        const targets = await Promise.all(candidates.slice(0, MAX_RESULTS).map(async (path) => {
+            const target = await validatePathTarget(workspace.path, path, undefined, reference.anchor, handler?.anchorLine);
+            return target === undefined
+                ? undefined
+                : {
+                    path,
+                    line: target.line,
+                    kind: 'file',
+                    ...(target.preview.length === 0 ? {} : { preview: targetPreview(target.preview) }),
+                    scope: undefined
+                };
+        }));
+        return targets.flatMap((target) => (target === undefined ? [] : [target]));
+    }
+    async resolvePathTargets(input, currentPath, reference) {
+        const handler = pathSpecifierResolver(reference.languageId, reference.value);
+        if (handler === undefined)
+            return { targets: [], truncated: false };
         const targets = input.entries
             .map((entry) => entry.path)
-            .filter((path) => isNavigablePath(path) && matchesSpecifier(path, currentPath, specifier))
-            .sort((left, right) => pathTargetScore(left, currentPath, specifier) -
-            pathTargetScore(right, currentPath, specifier))
+            .filter((path) => handler.matches(path, currentPath, reference.value))
+            .sort((left, right) => handler.score(left, currentPath, reference.value) -
+            handler.score(right, currentPath, reference.value))
             .slice(0, MAX_RESULTS);
         const resolved = await Promise.all(targets.map(async (path) => {
-            const preview = await validatePathTarget(input.root, path, input.revalidateSourceFingerprint ? input.sourceFiles[path] : undefined);
-            return preview === undefined
+            const target = await validatePathTarget(input.root, path, input.revalidateSourceFingerprint ? input.sourceFiles[path] : undefined, reference.anchor, handler.anchorLine);
+            return target === undefined
                 ? undefined
                 : {
                     path,
-                    line: 1,
+                    line: target.line,
                     kind: 'file',
-                    ...(preview.length === 0 ? {} : { preview: targetPreview(preview) }),
+                    ...(target.preview.length === 0 ? {} : { preview: targetPreview(target.preview) }),
                     scope: undefined
                 };
         }));
@@ -602,616 +592,12 @@ function emptyDefinitionResult(input) {
         ...(input.failureCode === undefined ? {} : { failureCode: input.failureCode })
     };
 }
-function sourceDelta(previous, current) {
-    const changed = Object.entries(current)
-        .filter(([path, fingerprint]) => previous[path] !== fingerprint)
-        .map(([path]) => path);
-    const removed = Object.keys(previous).filter((path) => current[path] === undefined);
-    return { changed, removed };
-}
-function manifestEntry(path, fingerprint) {
-    const match = /^([0-9]+):(-1|[0-9]+(?:\.[0-9]+)?)$/u.exec(fingerprint);
-    if (match === null)
-        return undefined;
-    const size = Number(match[1]);
-    const modifiedAt = match[2] === '-1' ? null : Number(match[2]);
-    if (!Number.isSafeInteger(size) ||
-        size < 0 ||
-        (modifiedAt !== null && !Number.isFinite(modifiedAt)))
-        return undefined;
-    return {
-        path,
-        name: path.slice(path.lastIndexOf('/') + 1),
-        kind: 'FILE',
-        size,
-        modifiedAt
-    };
-}
-function sourceFileFingerprint(size, modifiedAt) {
-    return `${size}:${modifiedAt ?? -1}`;
-}
-function sourceFingerprint(entries) {
-    const hash = createHash('sha256');
-    for (const entry of entries)
-        hash.update(`${entry.path}\0${sourceFileFingerprint(entry.size ?? -1, entry.modifiedAt)}\0`, 'utf8');
-    return hash.digest('hex');
-}
-async function buildIncrementalTags(executable, root, previousTags, delta, staging, destination) {
-    const changedTags = resolve(staging, 'changed.tags');
-    if (delta.changed.length > 0) {
-        const list = resolve(staging, 'changed.files.list');
-        await writeFile(list, delta.changed.join('\n'), { encoding: 'utf8', mode: 0o600 });
-        const release = await acquireBuild();
-        try {
-            const ctagsMs = await runCtags(executable, root, list, changedTags);
-            await mergeTags(previousTags, changedTags, new Set([...delta.changed, ...delta.removed]), destination);
-            return ctagsMs;
-        }
-        finally {
-            release();
-        }
-    }
-    else
-        await writeFile(changedTags, '', { encoding: 'utf8', mode: 0o600 });
-    await mergeTags(previousTags, changedTags, new Set([...delta.changed, ...delta.removed]), destination);
-    return 0;
-}
-async function mergeTags(previous, changed, replacedPaths, destination) {
-    const output = createWriteStream(destination, { encoding: 'utf8', mode: 0o600 });
-    const oldLines = tagLines(previous)[Symbol.asyncIterator]();
-    const changedLines = tagLines(changed)[Symbol.asyncIterator]();
-    const write = async (line) => {
-        if (!output.write(`${line}\n`))
-            await new Promise((resolvePromise) => output.once('drain', resolvePromise));
-    };
-    let old = await oldLines.next();
-    while (!old.done && old.value.startsWith('!_TAG_')) {
-        await write(old.value);
-        old = await oldLines.next();
-    }
-    let nextChanged = await nextDataTag(changedLines);
-    while (!old.done || nextChanged !== undefined) {
-        while (!old.done && tagPath(old.value) !== undefined && replacedPaths.has(tagPath(old.value)))
-            old = await oldLines.next();
-        if (old.done) {
-            await write(nextChanged);
-            nextChanged = await nextDataTag(changedLines);
-            continue;
-        }
-        if (nextChanged === undefined || compareTagLines(old.value, nextChanged) <= 0) {
-            await write(old.value);
-            old = await oldLines.next();
-        }
-        else {
-            await write(nextChanged);
-            nextChanged = await nextDataTag(changedLines);
-        }
-    }
-    await new Promise((resolvePromise, reject) => {
-        output.once('error', reject);
-        output.end(resolvePromise);
-    });
-}
-async function* tagLines(path) {
-    const input = createInterface({
-        input: createReadStream(path, { encoding: 'utf8' }),
-        crlfDelay: Infinity
-    });
-    for await (const line of input)
-        yield line;
-}
-async function nextDataTag(iterator) {
-    for (;;) {
-        const next = await iterator.next();
-        if (next.done)
-            return undefined;
-        if (!next.value.startsWith('!_TAG_'))
-            return next.value;
-    }
-}
-function tagPath(line) {
-    const second = line.indexOf('\t');
-    if (second < 0)
-        return undefined;
-    const third = line.indexOf('\t', second + 1);
-    return third < 0 ? undefined : line.slice(second + 1, third);
-}
-function compareTagLines(left, right) {
-    const leftName = left.slice(0, left.indexOf('\t'));
-    const rightName = right.slice(0, right.indexOf('\t'));
-    return (compareTagNames(leftName, rightName) || Buffer.compare(Buffer.from(left), Buffer.from(right)));
-}
-async function acquireBuild() {
-    if (activeBuilds >= 1) {
-        if (buildWaiters.length >= BUILD_QUEUE_LIMIT)
-            throw new Error('SYMBOL_INDEX_BUILD_FAILED');
-        await new Promise((resolvePromise, reject) => {
-            const resume = () => {
-                clearTimeout(timer);
-                resolvePromise();
-            };
-            const timer = setTimeout(() => {
-                const index = buildWaiters.indexOf(resume);
-                if (index >= 0)
-                    buildWaiters.splice(index, 1);
-                reject(new Error('SYMBOL_INDEX_BUILD_FAILED'));
-            }, BUILD_QUEUE_TIMEOUT_MS);
-            timer.unref();
-            buildWaiters.push(resume);
-        });
-    }
-    activeBuilds += 1;
-    return () => {
-        activeBuilds -= 1;
-        buildWaiters.shift()?.();
-    };
-}
-async function runCtags(executable, cwd, fileList, destination) {
-    const startedAt = Date.now();
-    await new Promise((resolvePromise, reject) => {
-        const child = spawn(executable, [
-            '--options=NONE',
-            '--output-format=u-ctags',
-            '--excmd=number',
-            '--sort=yes',
-            '--tag-relative=no',
-            '--pseudo-tags=-TAG_PROC_CWD',
-            '--fields=+nKS',
-            '--extras=+q',
-            '-L',
-            fileList,
-            '-f',
-            destination
-        ], {
-            cwd,
-            detached: process.platform !== 'win32',
-            windowsHide: true,
-            stdio: ['ignore', 'ignore', 'pipe']
-        });
-        let settled = false;
-        const settle = (callback) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            callback();
-        };
-        const terminate = () => {
-            if (child.pid !== undefined && process.platform !== 'win32') {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                    return;
-                }
-                catch {
-                    // Fall through to the direct process kill.
-                }
-            }
-            child.kill('SIGKILL');
-        };
-        const timer = setTimeout(() => {
-            terminate();
-            settle(() => reject(new Error('SYMBOL_INDEX_BUILD_FAILED')));
-        }, BUILD_TIMEOUT_MS);
-        timer.unref();
-        child.stderr.on('data', () => undefined);
-        child.once('error', () => settle(() => reject(new Error('SYMBOL_INDEX_BUILD_FAILED'))));
-        child.once('exit', (code) => settle(() => (code === 0 ? resolvePromise() : reject(new Error('SYMBOL_INDEX_BUILD_FAILED')))));
-    });
-    return Date.now() - startedAt;
-}
-async function ensurePrivateDirectory(path) {
-    await mkdir(path, { recursive: true, mode: 0o700 });
-    const metadata = await lstat(path);
-    if (!metadata.isDirectory() || metadata.isSymbolicLink())
-        throw new Error('SYMBOL_INDEX_UNAVAILABLE');
-}
-async function removeInactiveGenerations(directory, activeGeneration) {
-    const generations = await readdir(directory, { withFileTypes: true }).catch(() => []);
-    await Promise.all(generations
-        .filter((entry) => entry.isDirectory() &&
-        entry.name !== activeGeneration &&
-        /^[0-9a-f-]{36}(?:\.staging)?$/u.test(entry.name))
-        .map((entry) => rm(resolve(directory, entry.name), { recursive: true, force: true })));
-}
-async function readManifest(path) {
-    try {
-        const value = JSON.parse(await readFile(path, 'utf8'));
-        const sourceFiles = validManifestSourceFiles(value.sourceFiles) ? value.sourceFiles : undefined;
-        const schemaVersion = value.schemaVersion;
-        const optionsVersion = value.optionsVersion;
-        return typeof value === 'object' &&
-            value !== null &&
-            typeof schemaVersion === 'number' &&
-            Number.isInteger(schemaVersion) &&
-            schemaVersion >= 0 &&
-            typeof optionsVersion === 'number' &&
-            Number.isInteger(optionsVersion) &&
-            optionsVersion >= 0 &&
-            typeof value.ctagsVersion === 'string' &&
-            typeof value.sourceFingerprint === 'string' &&
-            /^[a-f0-9]{64}$/u.test(value.sourceFingerprint) &&
-            typeof value.truncated === 'boolean' &&
-            typeof value.generation === 'string' &&
-            /^[0-9a-f-]{36}$/u.test(value.generation)
-            ? {
-                schemaVersion,
-                optionsVersion,
-                ctagsVersion: value.ctagsVersion,
-                sourceFingerprint: value.sourceFingerprint,
-                ...(sourceFiles === undefined ? {} : { sourceFiles }),
-                truncated: value.truncated,
-                generation: value.generation
-            }
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function validManifestSourceFiles(value) {
-    if (value === undefined)
-        return false;
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-        return false;
-    const entries = Object.entries(value);
-    return (entries.length <= 100_000 &&
-        entries.every(([path, fingerprint]) => path.length > 0 &&
-            path.length <= 4096 &&
-            !path.includes('\0') &&
-            !path.includes('\\') &&
-            !path.startsWith('/') &&
-            !path.split('/').some((part) => part.length === 0 || part === '.' || part === '..') &&
-            typeof fingerprint === 'string' &&
-            /^[0-9]+:(?:-1|[0-9]+(?:\.[0-9]+)?)$/u.test(fingerprint)));
-}
-async function tagsPath(location, manifest) {
-    const path = resolve(location.generations, manifest.generation, 'tags');
-    if (relative(location.generations, path)
-        .split(sep)
-        .some((part) => part === '..'))
-        throw new Error('SYMBOL_INDEX_UNAVAILABLE');
-    return path;
-}
-async function tagsAvailable(path) {
-    try {
-        const metadata = await stat(path);
-        return metadata.isFile() && metadata.size <= MAX_TAGS_BYTES;
-    }
-    catch {
-        return false;
-    }
-}
-function isNavigablePath(path) {
-    const dot = path.lastIndexOf('.');
-    return dot >= 0 && NAVIGABLE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+function isCtagsSourcePath(path) {
+    return supportsSymbolNavigationPath(path);
 }
 function isSymbol(value) {
     return value.length > 0 && value.length <= 512 && /^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(value);
 }
-function isNavigableSpecifier(value) {
-    return (value.length > 0 &&
-        value.length <= 1024 &&
-        (/^(?:\.\.?\/)[A-Za-z0-9_./$-]+$/u.test(value) ||
-            /^[\p{L}_$][\p{L}\p{N}_$]*(?:\.[\p{L}_$][\p{L}\p{N}_$]*)+$/u.test(value) ||
-            /^(?:@?[A-Za-z0-9_$-]+)(?:\/[A-Za-z0-9_.$-]+)+$/u.test(value)));
-}
-function matchesSpecifier(path, currentPath, specifier) {
-    if (specifier.startsWith('.')) {
-        const resolved = resolveRelativeSpecifier(currentPath, specifier);
-        return (resolved !== undefined &&
-            relativeSpecifierCandidates(resolved).some((candidate) => path === candidate ||
-                path === `${candidate}/index.ts` ||
-                path === `${candidate}/index.tsx` ||
-                path === `${candidate}/index.js` ||
-                path === `${candidate}/index.jsx` ||
-                path === `${candidate}/__init__.py`));
-    }
-    if (specifier.includes('/'))
-        return sourceFileStem(path) === sourceFileStem(specifier);
-    if (specifier.includes('.')) {
-        const packagePath = specifier.replaceAll('.', '/');
-        return DOTTED_PACKAGE_SPECIFIER_HANDLERS.some((handler) => handler.packageSuffixes.some((suffix) => matchesPackagePath(path, `${packagePath}${suffix}`)));
-    }
-    return sourceFileStem(path) === sourceFileStem(specifier);
-}
-function matchesPackagePath(path, packagePath) {
-    return path === packagePath || path.endsWith(`/${packagePath}`);
-}
-function pathTargetScore(path, currentPath, specifier) {
-    if (!specifier.startsWith('.'))
-        return path.length;
-    const resolved = resolveRelativeSpecifier(currentPath, specifier);
-    if (resolved === undefined)
-        return Number.MAX_SAFE_INTEGER;
-    const candidates = relativeSpecifierCandidates(resolved);
-    const exact = candidates.indexOf(path);
-    if (exact >= 0)
-        return exact;
-    const index = candidates.findIndex((candidate) => path === `${candidate}/index.ts` ||
-        path === `${candidate}/index.tsx` ||
-        path === `${candidate}/index.js` ||
-        path === `${candidate}/index.jsx` ||
-        path === `${candidate}/__init__.py`);
-    return index >= 0 ? candidates.length + index : Number.MAX_SAFE_INTEGER;
-}
-function resolveRelativeSpecifier(currentPath, specifier) {
-    const resolved = posix.normalize(posix.join(posix.dirname(currentPath), specifier));
-    if (resolved.startsWith('../') || resolved === '..')
-        return undefined;
-    return resolved.replace(/^\.\//u, '');
-}
-function relativeSpecifierCandidates(path) {
-    const handler = RELATIVE_SOURCE_SPECIFIER_HANDLERS.find(({ importExtension }) => path.toLowerCase().endsWith(importExtension));
-    if (handler !== undefined) {
-        const sourceBase = path.slice(0, -handler.importExtension.length);
-        return [path, ...handler.sourceExtensions.map((extension) => `${sourceBase}${extension}`)];
-    }
-    return path.slice(path.lastIndexOf('/') + 1).includes('.')
-        ? [path]
-        : [path, ...EXTENSIONLESS_RELATIVE_SOURCE_EXTENSIONS.map((extension) => `${path}${extension}`)];
-}
-function sourceFileStem(path) {
-    const name = path.slice(path.lastIndexOf('/') + 1);
-    return name.replace(/(?:\.d)?\.[^.]+$/u, '');
-}
-async function firstTagOffset(handle, size, symbol) {
-    let low = 0;
-    let high = size;
-    while (low < high) {
-        const middle = Math.floor((low + high) / 2);
-        const start = await findTagLineStart(handle, middle);
-        if (start === undefined) {
-            high = middle;
-            continue;
-        }
-        const line = await readTagLine(handle, start, size);
-        if (line === undefined) {
-            high = middle;
-            continue;
-        }
-        const tag = parseTag(line.text);
-        if (tag === undefined || compareTagNames(tag.name, symbol) < 0)
-            low = line.nextOffset;
-        else
-            high = line.start;
-    }
-    return low;
-}
-async function findTagLineStart(handle, offset) {
-    let cursor = offset;
-    let scanned = 0;
-    while (cursor > 0 && scanned < MAX_TAG_LINE_BYTES) {
-        const start = Math.max(0, cursor - Math.min(READ_BLOCK_BYTES, MAX_TAG_LINE_BYTES - scanned));
-        const chunk = Buffer.alloc(cursor - start);
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, start);
-        if (bytesRead === 0)
-            return undefined;
-        const newline = chunk.subarray(0, bytesRead).lastIndexOf(0x0a);
-        if (newline >= 0)
-            return start + newline + 1;
-        cursor = start;
-        scanned += bytesRead;
-    }
-    return cursor === 0 ? 0 : undefined;
-}
-async function readTagLine(handle, offset, size) {
-    if (offset >= size)
-        return undefined;
-    let start = offset;
-    if (start > 0) {
-        const before = Buffer.alloc(1);
-        await handle.read(before, 0, 1, start - 1);
-        if (before[0] !== 0x0a) {
-            const aligned = await findNewline(handle, start, size, MAX_TAG_LINE_BYTES);
-            if (aligned === undefined)
-                return undefined;
-            start = aligned + 1;
-        }
-    }
-    if (start >= size)
-        return undefined;
-    const bytes = [];
-    let total = 0;
-    let cursor = start;
-    while (cursor < size && total <= MAX_TAG_LINE_BYTES) {
-        const chunk = Buffer.alloc(Math.min(READ_BLOCK_BYTES, size - cursor));
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, cursor);
-        if (bytesRead === 0)
-            break;
-        const content = chunk.subarray(0, bytesRead);
-        const newline = content.indexOf(0x0a);
-        const part = newline >= 0 ? content.subarray(0, newline) : content;
-        total += part.length;
-        if (total > MAX_TAG_LINE_BYTES)
-            return undefined;
-        bytes.push(part);
-        if (newline >= 0)
-            return {
-                start,
-                nextOffset: cursor + newline + 1,
-                text: Buffer.concat(bytes, total).toString('utf8')
-            };
-        cursor += bytesRead;
-    }
-    return undefined;
-}
-async function findNewline(handle, offset, size, limit) {
-    let cursor = offset;
-    let remaining = limit;
-    while (cursor < size && remaining > 0) {
-        const chunk = Buffer.alloc(Math.min(READ_BLOCK_BYTES, size - cursor, remaining));
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, cursor);
-        if (bytesRead === 0)
-            return undefined;
-        const newline = chunk.subarray(0, bytesRead).indexOf(0x0a);
-        if (newline >= 0)
-            return cursor + newline;
-        cursor += bytesRead;
-        remaining -= bytesRead;
-    }
-    return undefined;
-}
-function parseTag(text) {
-    if (text.length === 0 ||
-        text.startsWith('!_TAG_') ||
-        Buffer.byteLength(text) > MAX_TAG_LINE_BYTES)
-        return undefined;
-    const fields = text.split('\t');
-    if (fields.length < 3)
-        return undefined;
-    const [name, path, excmd, ...extensions] = fields;
-    if (name === undefined ||
-        path === undefined ||
-        excmd === undefined ||
-        name.length === 0 ||
-        path.length === 0 ||
-        path.startsWith('/') ||
-        path.includes('\\') ||
-        path.split('/').some((part) => part === '' || part === '.' || part === '..'))
-        return undefined;
-    const match = /^([1-9][0-9]*);?"?$/u.exec(excmd);
-    if (match === null)
-        return undefined;
-    const line = Number(match[1]);
-    if (!Number.isSafeInteger(line) || line < 1)
-        return undefined;
-    let kind;
-    let scope;
-    for (const extension of extensions) {
-        if (extension.length === 1)
-            kind ??= extension;
-        else if (extension.startsWith('kind:'))
-            kind ??= extension.slice('kind:'.length);
-        else if (extension.startsWith('scope:') ||
-            extension.startsWith('class:') ||
-            extension.startsWith('namespace:'))
-            scope ??= extension.slice(extension.indexOf(':') + 1);
-    }
-    return { name, path, line, kind, scope };
-}
-async function validateTarget(root, target, symbol, expectedFingerprint) {
-    const path = resolve(root, ...target.path.split('/'));
-    const pathMetadata = await lstat(path).catch(() => undefined);
-    if (pathMetadata === undefined ||
-        !pathMetadata.isFile() ||
-        pathMetadata.isSymbolicLink() ||
-        pathMetadata.size > MAX_SOURCE_BYTES)
-        return undefined;
-    const actual = await realpath(path).catch(() => undefined);
-    if (actual === undefined ||
-        relative(root, actual)
-            .split(sep)
-            .some((part) => part === '..'))
-        return undefined;
-    const metadata = await lstat(actual).catch(() => undefined);
-    if (metadata === undefined ||
-        !metadata.isFile() ||
-        metadata.isSymbolicLink() ||
-        metadata.size > MAX_SOURCE_BYTES)
-        return undefined;
-    if (expectedFingerprint !== undefined &&
-        sourceFileFingerprint(metadata.size, metadata.mtimeMs) !== expectedFingerprint)
-        return undefined;
-    const line = await lineAt(actual, target.line);
-    return line !== undefined && containsSymbol(line, symbol) ? targetPreview(line) : undefined;
-}
-async function validatePathTarget(root, path, expectedFingerprint) {
-    const requested = resolve(root, ...path.split('/'));
-    const requestedMetadata = await lstat(requested).catch(() => undefined);
-    if (requestedMetadata === undefined ||
-        !requestedMetadata.isFile() ||
-        requestedMetadata.isSymbolicLink() ||
-        requestedMetadata.size > MAX_SOURCE_BYTES)
-        return undefined;
-    const actual = await realpath(requested).catch(() => undefined);
-    if (actual === undefined ||
-        relative(root, actual)
-            .split(sep)
-            .some((part) => part === '..'))
-        return undefined;
-    const metadata = await lstat(actual).catch(() => undefined);
-    if (metadata === undefined ||
-        !metadata.isFile() ||
-        metadata.isSymbolicLink() ||
-        metadata.size > MAX_SOURCE_BYTES ||
-        (expectedFingerprint !== undefined &&
-            sourceFileFingerprint(metadata.size, metadata.mtimeMs) !== expectedFingerprint))
-        return undefined;
-    return lineAt(actual, 1);
-}
-function targetPreview(line) {
-    if (line.length <= MAX_TARGET_PREVIEW_CHARACTERS)
-        return line;
-    const end = line.charCodeAt(MAX_TARGET_PREVIEW_CHARACTERS - 1);
-    const safeEnd = end >= 0xd800 && end <= 0xdbff
-        ? MAX_TARGET_PREVIEW_CHARACTERS - 1
-        : MAX_TARGET_PREVIEW_CHARACTERS;
-    return `${line.slice(0, safeEnd)}…`;
-}
-async function lineAt(path, targetLine) {
-    const handle = await open(path, 'r');
-    try {
-        let offset = 0;
-        let line = 1;
-        let pending = Buffer.alloc(0);
-        while (offset < MAX_TARGET_LINE_SCAN_BYTES) {
-            const chunk = Buffer.alloc(READ_BLOCK_BYTES);
-            const { bytesRead } = await handle.read(chunk, 0, chunk.length, offset);
-            if (bytesRead === 0)
-                return line === targetLine ? pending.toString('utf8') : undefined;
-            offset += bytesRead;
-            let content = pending.length === 0
-                ? chunk.subarray(0, bytesRead)
-                : Buffer.concat([pending, chunk.subarray(0, bytesRead)]);
-            let newline;
-            while ((newline = content.indexOf(0x0a)) >= 0) {
-                if (line === targetLine)
-                    return content.subarray(0, newline).toString('utf8');
-                line += 1;
-                content = content.subarray(newline + 1);
-            }
-            pending = content;
-        }
-        return line === targetLine ? pending.toString('utf8') : undefined;
-    }
-    finally {
-        await handle.close();
-    }
-}
-function containsSymbol(line, symbol) {
-    const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    return new RegExp(`(?:^|[^\\p{L}\\p{N}_$])${escaped}(?![\\p{L}\\p{N}_$])`, 'u').test(line);
-}
-function compareTagNames(left, right) {
-    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
-}
-function compareTargets(left, right, currentPath) {
-    const leftScore = targetScore(left, currentPath);
-    const rightScore = targetScore(right, currentPath);
-    return (rightScore - leftScore ||
-        left.path.localeCompare(right.path) ||
-        left.line - right.line ||
-        (left.kind ?? '').localeCompare(right.kind ?? ''));
-}
-function targetScore(target, currentPath) {
-    if (target.path === currentPath)
-        return 100;
-    const currentDirectory = currentPath.includes('/')
-        ? currentPath.slice(0, currentPath.lastIndexOf('/'))
-        : '';
-    const targetDirectory = target.path.includes('/')
-        ? target.path.slice(0, target.path.lastIndexOf('/'))
-        : '';
-    return commonPathSegments(currentDirectory, targetDirectory);
-}
-function commonPathSegments(left, right) {
-    const leftParts = left === '' ? [] : left.split('/');
-    const rightParts = right === '' ? [] : right.split('/');
-    let count = 0;
-    while (count < leftParts.length && leftParts[count] === rightParts[count])
-        count += 1;
-    return count;
-}
 function buildFailure(error) {
     return error instanceof Error && error.message === 'SYMBOL_INDEX_LIMIT_EXCEEDED'
         ? 'SYMBOL_INDEX_LIMIT_EXCEEDED'