@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.0

package/dist/mapping-service.js

@@ -1,1003 +1,25 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import fastGlob from "fast-glob";
+import { buildSuggestedCall } from "./build-suggested-call.js";
 import { createError, ERROR_CODES } from "./errors.js";
-import { buildVersionSourceSearchRoots, normalizeOptionalProjectPath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
+import { buildSymbolKey, createClassSymbolRecord, mergeDirectionIndexes, normalizeMappedSymbolOutput } from "./mapping/parsers/symbol-records.js";
+import { buildAdjacency, buildTargetRecordIndex, pairKey } from "./mapping/parsers/normalize.js";
+import { MATCH_RANK, MAX_CANDIDATES } from "./mapping/internal-types.js";
+import { applyDisambiguationHints, clampRowLimit, collectTargetRecords, effectiveLoomSearchProjectPath, inferAmbiguityReasons, invalidInputError, limitResolutionCandidates, lookupCandidates, mappingPriorityFromInput, mappingSourceOrder, namespacePath, normalizeIncludedKinds, normalizeQuerySymbol, pathToTransformChain, pathUsesSource, projectLookupCandidateDescriptor, requiresOnlyObfuscatedMojangGraph, toLookupCandidate, toResolutionCandidate } from "./mapping/lookup.js";
+import { loadMojangPairs } from "./mapping/loaders/mojang.js";
+import { loadTinyPairsFromLoom } from "./mapping/loaders/tiny-loom.js";
+import { loadTinyPairsFromMaven } from "./mapping/loaders/tiny-maven.js";
 const SUPPORTED_MAPPINGS = new Set([
     "obfuscated",
     "mojang",
     "intermediary",
     "yarn"
 ]);
-const MATCH_RANK = {
-    exact: 3,
-    normalized: 2,
-    "simple-name": 1
-};
-const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
-const MAX_CANDIDATES = 200;
-const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
-function createDirectionIndex() {
-    return {
-        exact: new Map(),
-        normalized: new Map(),
-        simple: new Map(),
-        records: new Map()
-    };
-}
-function addToSetMap(map, key, value) {
-    const normalizedKey = key.trim();
-    if (!normalizedKey) {
-        return;
-    }
-    const existing = map.get(normalizedKey) ?? new Set();
-    existing.add(value);
-    map.set(normalizedKey, existing);
-}
-function normalizedVariants(symbol) {
-    const variants = [symbol];
-    let dotted;
-    if (symbol.includes("/")) {
-        dotted = symbol.replace(/\//g, ".");
-        if (dotted !== symbol) {
-            variants.push(dotted);
-        }
-    }
-    if (symbol.includes(".")) {
-        const slashed = symbol.replace(/\./g, "/");
-        if (slashed !== symbol && slashed !== dotted) {
-            variants.push(slashed);
-        }
-    }
-    return variants;
-}
-function simpleName(symbol) {
-    const trimmed = symbol.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    const withoutDescriptor = trimmed.includes("(") ? trimmed.slice(0, trimmed.indexOf("(")) : trimmed;
-    const base = withoutDescriptor.split(/[./]/).at(-1)?.trim();
-    return base || undefined;
-}
-function normalizeMappedSymbolOutput(symbol) {
-    return symbol.replace(/\//g, ".");
-}
-function splitOwnerAndName(symbol) {
-    const trimmed = symbol.trim();
-    const separatorIndex = Math.max(trimmed.lastIndexOf("."), trimmed.lastIndexOf("/"));
-    if (separatorIndex <= 0 || separatorIndex >= trimmed.length - 1) {
-        return undefined;
-    }
-    return {
-        owner: trimmed.slice(0, separatorIndex),
-        name: trimmed.slice(separatorIndex + 1)
-    };
-}
-function stripLineInfo(input) {
-    let value = input.trim();
-    while (/^\d+:\d+:/.test(value)) {
-        value = value.replace(/^\d+:\d+:/, "");
-    }
-    return value.replace(/:\d+:\d+$/, "").trim();
-}
-function parseMethodName(value) {
-    const match = /^(.+?)\s+([^\s(]+)\((.*)\)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    return match[2]?.trim() || undefined;
-}
-function parseFieldName(value) {
-    const match = /^(.+?)\s+([^\s]+)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    return match[2]?.trim() || undefined;
-}
-function buildSymbolKey(record) {
-    return `${record.kind}|${record.owner ?? ""}|${record.name}|${record.descriptor ?? ""}`;
-}
-function classNameParts(classFqn) {
-    const separatorIndex = classFqn.lastIndexOf(".");
-    if (separatorIndex <= 0 || separatorIndex >= classFqn.length - 1) {
-        return {
-            owner: undefined,
-            name: classFqn
-        };
-    }
-    return {
-        owner: classFqn.slice(0, separatorIndex),
-        name: classFqn.slice(separatorIndex + 1)
-    };
-}
-function createClassSymbolRecord(className) {
-    const symbol = normalizeMappedSymbolOutput(className.trim());
-    const parts = classNameParts(symbol);
-    return {
-        kind: "class",
-        symbol,
-        owner: parts.owner,
-        name: parts.name
-    };
-}
-function createFieldSymbolRecord(owner, fieldName) {
-    const normalizedOwner = normalizeMappedSymbolOutput(owner.trim());
-    const normalizedName = fieldName.trim();
-    return {
-        kind: "field",
-        symbol: `${normalizedOwner}.${normalizedName}`,
-        owner: normalizedOwner,
-        name: normalizedName
-    };
-}
-function createMethodSymbolRecord(owner, methodName, descriptor) {
-    const normalizedOwner = normalizeMappedSymbolOutput(owner.trim());
-    const normalizedName = methodName.trim();
-    const normalizedDescriptor = descriptor?.trim() || undefined;
-    return {
-        kind: "method",
-        symbol: `${normalizedOwner}.${normalizedName}${normalizedDescriptor ?? ""}`,
-        owner: normalizedOwner,
-        name: normalizedName,
-        descriptor: normalizedDescriptor
-    };
-}
-function parseInputSymbol(symbol) {
-    const trimmed = symbol.trim();
-    if (!trimmed || /\s/.test(trimmed)) {
-        return undefined;
-    }
-    const openIndex = trimmed.indexOf("(");
-    if (openIndex >= 0) {
-        const closeIndex = trimmed.indexOf(")", openIndex);
-        if (closeIndex < 0) {
-            return undefined;
-        }
-        const ownerAndMethod = splitOwnerAndName(trimmed.slice(0, openIndex));
-        if (!ownerAndMethod) {
-            return undefined;
-        }
-        const descriptor = trimmed.slice(openIndex);
-        return createMethodSymbolRecord(ownerAndMethod.owner, ownerAndMethod.name, descriptor);
-    }
-    const ownerAndName = splitOwnerAndName(trimmed);
-    if (!ownerAndName) {
-        return createClassSymbolRecord(trimmed);
-    }
-    if (/^[A-Z$]/.test(ownerAndName.name)) {
-        return createClassSymbolRecord(trimmed);
-    }
-    return createFieldSymbolRecord(ownerAndName.owner, ownerAndName.name);
-}
-function exactLookupKeys(record) {
-    const keys = new Set([record.symbol]);
-    if (record.kind === "method" && record.owner && record.descriptor) {
-        keys.add(`${record.owner}.${record.name}`);
-    }
-    return [...keys];
-}
-function simpleLookupKeys(record) {
-    if (record.kind === "class") {
-        return [record.name];
-    }
-    if (record.kind === "field") {
-        return [record.name];
-    }
-    if (record.descriptor) {
-        return [record.name, `${record.name}${record.descriptor}`];
-    }
-    return [record.name];
-}
-function registerRecord(index, record) {
-    const key = buildSymbolKey(record);
-    if (!index.records.has(key)) {
-        index.records.set(key, record);
-    }
-    return key;
-}
-function addLookupEntries(index, fromRecord, toRecord) {
-    if (!fromRecord.symbol || !toRecord.symbol) {
-        return;
-    }
-    const targetKey = registerRecord(index, toRecord);
-    for (const key of exactLookupKeys(fromRecord)) {
-        addToSetMap(index.exact, key, targetKey);
-        for (const variant of normalizedVariants(key)) {
-            if (variant !== key) {
-                addToSetMap(index.normalized, variant, targetKey);
-            }
-        }
-    }
-    for (const key of simpleLookupKeys(fromRecord)) {
-        addToSetMap(index.simple, key, targetKey);
-    }
-}
-function mergeDirectionIndexes(target, source) {
-    const mergeMap = (targetMap, sourceMap) => {
-        for (const [key, values] of sourceMap.entries()) {
-            const existing = targetMap.get(key) ?? new Set();
-            for (const value of values) {
-                existing.add(value);
-            }
-            targetMap.set(key, existing);
-        }
-    };
-    mergeMap(target.exact, source.exact);
-    mergeMap(target.normalized, source.normalized);
-    mergeMap(target.simple, source.simple);
-    for (const [key, value] of source.records.entries()) {
-        if (!target.records.has(key)) {
-            target.records.set(key, value);
-        }
-    }
-}
-function pairKey(sourceMapping, targetMapping) {
-    return `${sourceMapping}->${targetMapping}`;
-}
-function parsePairKey(key) {
-    const separator = key.indexOf("->");
-    const source = separator >= 0 ? key.slice(0, separator) : key;
-    const target = separator >= 0 ? key.slice(separator + 2) : "";
-    return {
-        sourceMapping: source,
-        targetMapping: target
-    };
-}
-function buildAdjacency(pairs) {
-    const adjacency = new Map();
-    for (const key of pairs.keys()) {
-        const { sourceMapping, targetMapping } = parsePairKey(key);
-        let neighbors = adjacency.get(sourceMapping);
-        if (!neighbors) {
-            neighbors = new Set();
-            adjacency.set(sourceMapping, neighbors);
-        }
-        neighbors.add(targetMapping);
-    }
-    return new Map([...adjacency.entries()].map(([mapping, neighbors]) => [mapping, [...neighbors]]));
-}
-function buildTargetRecordIndex(pairs) {
-    const recordsByTarget = new Map();
-    for (const [key, pair] of pairs.entries()) {
-        const { targetMapping } = parsePairKey(key);
-        let bucket = recordsByTarget.get(targetMapping);
-        if (!bucket) {
-            bucket = new Map();
-            recordsByTarget.set(targetMapping, bucket);
-        }
-        for (const record of pair.index.records.values()) {
-            bucket.set(buildSymbolKey(record), record);
-        }
-    }
-    return new Map([...recordsByTarget.entries()].map(([mapping, records]) => [mapping, [...records.values()]]));
-}
-function ensurePairIndex(indexes, from, to) {
-    const key = pairKey(from, to);
-    const existing = indexes.get(key);
-    if (existing) {
-        return existing;
-    }
-    const created = createDirectionIndex();
-    indexes.set(key, created);
-    return created;
-}
-/** Map of proguard primitive type names to JVM type characters. */
-const PROGUARD_PRIMITIVES = {
-    void: "V", boolean: "Z", byte: "B", char: "C",
-    short: "S", int: "I", long: "J", float: "F", double: "D"
-};
-/**
- * Convert a single proguard type (e.g. "int", "net.minecraft.Foo", "int[][]")
- * to JVM notation (e.g. "I", "Lnet/minecraft/Foo;", "[[I").
- * `classLookup` maps mojang class names → obfuscated class names (for the obfuscated descriptor).
- * Pass `undefined` to skip class name translation (for mojang descriptors).
- */
-function proguardTypeToJvm(type, classLookup) {
-    let arrayDepth = 0;
-    let base = type;
-    while (base.endsWith("[]")) {
-        arrayDepth += 1;
-        base = base.slice(0, -2);
-    }
-    const prefix = "[".repeat(arrayDepth);
-    const primitive = PROGUARD_PRIMITIVES[base];
-    if (primitive) {
-        return `${prefix}${primitive}`;
-    }
-    const translated = classLookup ? (classLookup.get(base) ?? base) : base;
-    return `${prefix}L${translated.replace(/\./g, "/")};`;
-}
-/**
- * Parse a proguard method signature (after stripLineInfo) into a JVM descriptor.
- * Input format: "returnType methodName(paramType1,paramType2,...)"
- * Returns `{ name, descriptor }` or `undefined` if parsing fails.
- */
-function parseProguardMethod(value, classLookup) {
-    const match = /^(.+?)\s+([^\s(]+)\((.*)\)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    const returnType = match[1].trim();
-    const name = match[2].trim();
-    const params = match[3].trim();
-    if (!name) {
-        return undefined;
-    }
-    const paramParts = params ? params.split(",").map((p) => p.trim()) : [];
-    const paramDescriptor = paramParts.map((p) => proguardTypeToJvm(p, classLookup)).join("");
-    const returnDescriptor = proguardTypeToJvm(returnType, classLookup);
-    return { name, descriptor: `(${paramDescriptor})${returnDescriptor}` };
-}
-function parseClientMappings(text) {
-    const obfuscatedToMojang = createDirectionIndex();
-    const mojangToObfuscated = createDirectionIndex();
-    // Two-pass parsing: first collect class name mappings, then parse members with descriptors.
-    const lines = text.split(/\r?\n/);
-    // Pass 1: collect class name mappings (mojang → obfuscated)
-    const mojangToObfuscatedClass = new Map();
-    let classCount = 0;
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
-        if (classMatch) {
-            const mojangClass = classMatch[1]?.trim() ?? "";
-            const obfuscatedClass = classMatch[2]?.trim() ?? "";
-            if (mojangClass && obfuscatedClass) {
-                mojangToObfuscatedClass.set(mojangClass, obfuscatedClass);
-                classCount += 1;
-            }
-        }
-    }
-    if (classCount === 0) {
-        throw createError({
-            code: ERROR_CODES.MAPPING_UNAVAILABLE,
-            message: "No class mappings could be parsed from client mappings."
-        });
-    }
-    // Pass 2: build full index with descriptors
-    let currentClass;
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
-        if (classMatch) {
-            const mojangClass = classMatch[1]?.trim() ?? "";
-            const obfuscatedClass = classMatch[2]?.trim() ?? "";
-            if (!mojangClass || !obfuscatedClass) {
-                currentClass = undefined;
-                continue;
-            }
-            currentClass = {
-                obfuscated: obfuscatedClass,
-                mojang: mojangClass
-            };
-            addLookupEntries(obfuscatedToMojang, createClassSymbolRecord(obfuscatedClass), createClassSymbolRecord(mojangClass));
-            addLookupEntries(mojangToObfuscated, createClassSymbolRecord(mojangClass), createClassSymbolRecord(obfuscatedClass));
-            continue;
-        }
-        if (!currentClass) {
-            continue;
-        }
-        const arrowIndex = line.indexOf(" -> ");
-        if (arrowIndex < 0) {
-            continue;
-        }
-        const leftRaw = line.slice(0, arrowIndex).trim();
-        const rightRaw = line.slice(arrowIndex + 4).trim();
-        if (!leftRaw || !rightRaw) {
-            continue;
-        }
-        const mojangMemberSignature = stripLineInfo(leftRaw);
-        // Try method parsing with JVM descriptor
-        const obfuscatedMethod = parseProguardMethod(mojangMemberSignature, mojangToObfuscatedClass);
-        if (obfuscatedMethod) {
-            const mojangMethod = parseProguardMethod(mojangMemberSignature, undefined);
-            const obfuscatedDescriptor = obfuscatedMethod.descriptor;
-            const mojangDescriptor = mojangMethod?.descriptor;
-            addLookupEntries(obfuscatedToMojang, createMethodSymbolRecord(currentClass.obfuscated, rightRaw, obfuscatedDescriptor), createMethodSymbolRecord(currentClass.mojang, obfuscatedMethod.name, mojangDescriptor));
-            addLookupEntries(mojangToObfuscated, createMethodSymbolRecord(currentClass.mojang, obfuscatedMethod.name, mojangDescriptor), createMethodSymbolRecord(currentClass.obfuscated, rightRaw, obfuscatedDescriptor));
-            continue;
-        }
-        const fieldName = parseFieldName(mojangMemberSignature);
-        if (!fieldName) {
-            continue;
-        }
-        addLookupEntries(obfuscatedToMojang, createFieldSymbolRecord(currentClass.obfuscated, rightRaw), createFieldSymbolRecord(currentClass.mojang, fieldName));
-        addLookupEntries(mojangToObfuscated, createFieldSymbolRecord(currentClass.mojang, fieldName), createFieldSymbolRecord(currentClass.obfuscated, rightRaw));
-    }
-    const result = new Map();
-    result.set(pairKey("obfuscated", "mojang"), obfuscatedToMojang);
-    result.set(pairKey("mojang", "obfuscated"), mojangToObfuscated);
-    return result;
-}
-function normalizeTinyNamespace(namespace) {
-    const normalized = namespace.trim().toLowerCase();
-    if (normalized === "obfuscated" || normalized === "official") {
-        return "obfuscated";
-    }
-    if (normalized === "mojang") {
-        return "mojang";
-    }
-    if (normalized === "intermediary") {
-        return "intermediary";
-    }
-    if (normalized === "named" || normalized === "yarn") {
-        return "yarn";
-    }
-    return undefined;
-}
-function addPairRecords(target, records) {
-    for (const [sourceMapping, sourceRecord] of records.entries()) {
-        for (const [targetMapping, targetRecord] of records.entries()) {
-            if (sourceMapping === targetMapping) {
-                continue;
-            }
-            addLookupEntries(ensurePairIndex(target, sourceMapping, targetMapping), sourceRecord, targetRecord);
-        }
-    }
-}
-function parseTinyMappings(text) {
-    const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
-    if (lines.length === 0) {
-        return new Map();
-    }
-    const header = lines[0].split("\t");
-    if (header.length < 5 || header[0] !== "tiny" || header[1] !== "2") {
-        return new Map();
-    }
-    const namespaceColumns = header.slice(3).map((namespace, index) => ({
-        mapping: normalizeTinyNamespace(namespace),
-        columnIndex: index + 1
-    }));
-    const recognized = namespaceColumns.filter((entry) => entry.mapping != null);
-    if (recognized.length < 2) {
-        return new Map();
-    }
-    const result = new Map();
-    const currentClassNames = new Map();
-    for (const line of lines.slice(1)) {
-        const columns = line.split("\t");
-        if (columns[0] === "c") {
-            const classRecords = new Map();
-            for (const namespace of recognized) {
-                const value = columns[namespace.columnIndex]?.trim() ?? "";
-                if (!value) {
-                    continue;
-                }
-                currentClassNames.set(namespace.mapping, value);
-                classRecords.set(namespace.mapping, createClassSymbolRecord(value));
-            }
-            addPairRecords(result, classRecords);
-            continue;
-        }
-        if (columns[0] === "" && columns[1] === "f") {
-            const fieldRecords = new Map();
-            for (const namespace of recognized) {
-                const owner = currentClassNames.get(namespace.mapping);
-                const value = columns[namespace.columnIndex + 2]?.trim() ?? "";
-                if (!owner || !value) {
-                    continue;
-                }
-                fieldRecords.set(namespace.mapping, createFieldSymbolRecord(owner, value));
-            }
-            addPairRecords(result, fieldRecords);
-            continue;
-        }
-        if (columns[0] === "" && columns[1] === "m") {
-            const descriptor = columns[2]?.trim() || undefined;
-            const methodRecords = new Map();
-            for (const namespace of recognized) {
-                const owner = currentClassNames.get(namespace.mapping);
-                const value = columns[namespace.columnIndex + 2]?.trim() ?? "";
-                if (!owner || !value) {
-                    continue;
-                }
-                methodRecords.set(namespace.mapping, createMethodSymbolRecord(owner, value, descriptor));
-            }
-            addPairRecords(result, methodRecords);
-        }
-    }
-    return result;
-}
-function addCandidates(target, index, symbols, kind, confidence) {
-    if (!symbols || symbols.size === 0) {
-        return;
-    }
-    const rank = MATCH_RANK[kind];
-    for (const key of symbols) {
-        const record = index.records.get(key);
-        if (!record) {
-            continue;
-        }
-        const current = target.get(key);
-        if (!current || rank > current.rank || (rank === current.rank && confidence > current.confidence)) {
-            target.set(key, {
-                key,
-                record,
-                matchKind: kind,
-                confidence,
-                rank
-            });
-        }
-    }
-}
-function lookupCandidates(index, query) {
-    const trimmedQuery = query.symbol.trim();
-    const collected = new Map();
-    addCandidates(collected, index, index.exact.get(trimmedQuery), "exact", 1);
-    for (const variant of normalizedVariants(trimmedQuery)) {
-        addCandidates(collected, index, index.normalized.get(variant), "normalized", 0.9);
-    }
-    if (query.kind === "method" && query.owner && query.descriptor) {
-        const descriptorlessKey = `${query.owner}.${query.name}`;
-        addCandidates(collected, index, index.exact.get(descriptorlessKey), "normalized", DESCRIPTOR_FALLBACK_CONFIDENCE);
-        for (const variant of normalizedVariants(descriptorlessKey)) {
-            addCandidates(collected, index, index.normalized.get(variant), "normalized", DESCRIPTOR_FALLBACK_CONFIDENCE);
-        }
-    }
-    const simpleKeys = new Set();
-    const shortName = simpleName(trimmedQuery);
-    if (shortName) {
-        simpleKeys.add(shortName);
-    }
-    if (query.kind !== "class") {
-        simpleKeys.add(query.name);
-    }
-    if (query.kind === "method" && query.descriptor) {
-        simpleKeys.add(`${query.name}${query.descriptor}`);
-    }
-    for (const key of simpleKeys) {
-        addCandidates(collected, index, index.simple.get(key), "simple-name", 0.75);
-    }
-    return [...collected.values()]
-        .sort((left, right) => {
-        if (right.confidence !== left.confidence) {
-            return right.confidence - left.confidence;
-        }
-        if (right.rank !== left.rank) {
-            return right.rank - left.rank;
-        }
-        return left.record.symbol.localeCompare(right.record.symbol);
-    })
-        .slice(0, MAX_CANDIDATES)
-        .map(({ record, matchKind, confidence }) => ({
-        symbol: record.symbol,
-        matchKind,
-        confidence,
-        kind: record.kind,
-        owner: record.owner,
-        name: record.name,
-        descriptor: record.descriptor
-    }));
-}
-function mappingPriorityFromInput(configPriority, override) {
-    if (override === "loom-first" || override === "maven-first") {
-        return override;
-    }
-    return configPriority;
-}
-function mappingSourceOrder(priority) {
-    if (priority === "maven-first") {
-        return ["maven", "loom-cache"];
-    }
-    return ["loom-cache", "maven"];
-}
-function requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) {
-    return sourceMapping !== "intermediary" &&
-        sourceMapping !== "yarn" &&
-        targetMapping !== "intermediary" &&
-        targetMapping !== "yarn";
-}
-function namespacePath(graph, sourceMapping, targetMapping) {
-    if (sourceMapping === targetMapping) {
-        return [sourceMapping];
-    }
-    const key = pairKey(sourceMapping, targetMapping);
-    if (graph.pathCache.has(key)) {
-        return graph.pathCache.get(key);
-    }
-    const { adjacency } = graph;
-    const queue = [sourceMapping];
-    let queueIndex = 0;
-    const parent = new Map([[sourceMapping, undefined]]);
-    while (queueIndex < queue.length) {
-        const current = queue[queueIndex];
-        queueIndex += 1;
-        if (current === targetMapping) {
-            break;
-        }
-        const neighbors = adjacency.get(current);
-        if (!neighbors) {
-            continue;
-        }
-        for (const neighbor of neighbors) {
-            if (parent.has(neighbor)) {
-                continue;
-            }
-            parent.set(neighbor, current);
-            queue.push(neighbor);
-        }
-    }
-    if (!parent.has(targetMapping)) {
-        graph.pathCache.set(key, undefined);
-        return undefined;
-    }
-    const reversedPath = [];
-    let cursor = targetMapping;
-    while (cursor) {
-        reversedPath.push(cursor);
-        cursor = parent.get(cursor);
-    }
-    const path = reversedPath.reverse();
-    graph.pathCache.set(key, path);
-    return path;
-}
-function pathUsesSource(pairs, path, source) {
-    for (let index = 0; index < path.length - 1; index += 1) {
-        const hop = pairs.get(pairKey(path[index], path[index + 1]));
-        if (hop?.source === source) {
-            return true;
-        }
-    }
-    return false;
-}
-function pathToTransformChain(path) {
-    if (path.length <= 1) {
-        return [];
-    }
-    const transform = [];
-    for (let index = 0; index < path.length - 1; index += 1) {
-        transform.push(`mapping:${path[index]}->${path[index + 1]}`);
-    }
-    return transform;
-}
-function toLookupCandidate(record) {
-    return {
-        symbol: record.symbol,
-        matchKind: "exact",
-        confidence: 1,
-        kind: record.kind,
-        owner: record.owner,
-        name: record.name,
-        descriptor: record.descriptor
-    };
-}
-function toSymbolReference(record) {
-    return {
-        kind: record.kind,
-        name: record.kind === "class" ? record.symbol : record.name,
-        owner: record.kind === "class" ? undefined : record.owner,
-        descriptor: record.kind === "method" ? record.descriptor : undefined,
-        symbol: record.symbol
-    };
-}
-function toResolutionCandidate(candidate) {
-    return {
-        kind: candidate.kind,
-        name: candidate.kind === "class" ? candidate.symbol : candidate.name,
-        owner: candidate.kind === "class" ? undefined : candidate.owner,
-        descriptor: candidate.kind === "method" ? candidate.descriptor : undefined,
-        symbol: candidate.symbol,
-        matchKind: candidate.matchKind,
-        confidence: candidate.confidence
-    };
-}
-function invalidInputError(message, details) {
-    return createError({
-        code: ERROR_CODES.INVALID_INPUT,
-        message,
-        details
-    });
-}
-function normalizeMemberName(name) {
-    const normalized = name.trim();
-    if (!normalized || /[\s./()]/.test(normalized)) {
-        throw invalidInputError("name must be a simple member name without separators when kind is field or method.", {
-            name
-        });
-    }
-    return normalized;
-}
-/**
- * Validate a JVM method descriptor such as `(I)V`, `()Lfoo/Bar;`, `(Lfoo/Bar;[I)V`.
- * Rejects empty strings, missing/mis-positioned parens, empty return type, and invalid base
- * type tokens so "(" or "()" style half-descriptors surface as ERR_INVALID_INPUT instead of
- * being silently accepted.
- */
-function normalizeMethodDescriptor(descriptor) {
-    const normalized = descriptor?.trim() ?? "";
-    if (!normalized) {
-        throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
-            descriptor
-        });
-    }
-    if (!isValidMethodDescriptor(normalized)) {
-        throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
-            descriptor
-        });
-    }
-    return normalized;
-}
-function isValidMethodDescriptor(descriptor) {
-    if (!descriptor.startsWith("("))
-        return false;
-    const closingIndex = descriptor.indexOf(")");
-    if (closingIndex < 0)
-        return false;
-    const argsSection = descriptor.slice(1, closingIndex);
-    const returnSection = descriptor.slice(closingIndex + 1);
-    if (returnSection.length === 0)
-        return false;
-    let cursor = 0;
-    while (cursor < argsSection.length) {
-        const next = consumeFieldType(argsSection, cursor, /*allowVoid*/ false);
-        if (next < 0)
-            return false;
-        cursor = next;
-    }
-    const returnEnd = consumeFieldType(returnSection, 0, /*allowVoid*/ true);
-    return returnEnd === returnSection.length;
-}
-/**
- * JVM specification §4.3.2: "An array type descriptor is valid only if it represents a type
- * with 255 or fewer dimensions." Matches the `multianewarray` / field-signature limit.
- */
-const JVM_MAX_ARRAY_DIMENSIONS = 255;
-function consumeFieldType(descriptor, position, allowVoid) {
-    // Arrays are handled iteratively so pathological inputs such as `(` + "[".repeat(20000) + `I)V`
-    // cannot blow the call stack. After consuming every leading `[`, only the element type token
-    // is dispatched through the switch below. Dimensions above the JVM limit are rejected rather
-    // than merely accepted as "syntactically valid but semantically absurd" — clients must not be
-    // able to push a 20000-dimension descriptor through cache-key construction.
-    let cursor = position;
-    let arrayDimensions = 0;
-    while (cursor < descriptor.length && descriptor[cursor] === "[") {
-        cursor += 1;
-        arrayDimensions += 1;
-        if (arrayDimensions > JVM_MAX_ARRAY_DIMENSIONS)
-            return -1;
-    }
-    if (cursor >= descriptor.length)
-        return -1;
-    // Void is only valid at the outermost position — inside an array element it is illegal.
-    const elementAllowsVoid = cursor === position && allowVoid;
-    const token = descriptor[cursor];
-    switch (token) {
-        case "B":
-        case "C":
-        case "D":
-        case "F":
-        case "I":
-        case "J":
-        case "S":
-        case "Z":
-            return cursor + 1;
-        case "V":
-            return elementAllowsVoid ? cursor + 1 : -1;
-        case "L": {
-            const end = descriptor.indexOf(";", cursor);
-            // Reject empty class names like L; and unterminated references.
-            if (end < 0 || end === cursor + 1)
-                return -1;
-            return end + 1;
-        }
-        default:
-            return -1;
-    }
-}
-function normalizeQuerySymbol(input, signatureMode, options) {
-    if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
-        throw invalidInputError('kind must be one of "class", "field", or "method".', {
-            kind: input.kind
-        });
-    }
-    const normalizedName = input.name?.trim() ?? "";
-    if (!normalizedName) {
-        throw invalidInputError("name must be a non-empty string.", {
-            name: input.name
-        });
-    }
-    if (input.kind === "class") {
-        const owner = input.owner?.trim();
-        if (owner) {
-            throw invalidInputError("owner is not allowed when kind=class. Use name as FQCN.", {
-                owner: input.owner,
-                nextAction: 'Provide class as name, e.g. "net.minecraft.server.Main".'
-            });
-        }
-        if (input.descriptor?.trim()) {
-            throw invalidInputError("descriptor is not allowed when kind=class.", {
-                descriptor: input.descriptor
-            });
-        }
-        const className = normalizeMappedSymbolOutput(normalizedName);
-        if (!className.includes(".") && !options?.allowShortClassName) {
-            throw invalidInputError("name must be a fully qualified class name when kind=class.", {
-                name: input.name
-            });
-        }
-        const record = createClassSymbolRecord(className);
-        return {
-            record,
-            querySymbol: toSymbolReference(record)
-        };
-    }
-    const owner = normalizeMappedSymbolOutput(input.owner?.trim() ?? "");
-    if (!owner) {
-        throw invalidInputError("owner is required when kind is field or method.", {
-            owner: input.owner,
-            kind: input.kind
-        });
-    }
-    if (input.kind === "field") {
-        if (input.descriptor?.trim()) {
-            throw invalidInputError("descriptor is not allowed when kind=field.", {
-                descriptor: input.descriptor
-            });
-        }
-        const record = createFieldSymbolRecord(owner, normalizeMemberName(normalizedName));
-        return {
-            record,
-            querySymbol: toSymbolReference(record)
-        };
-    }
-    let descriptor;
-    if (signatureMode === "name-only") {
-        // name-only matches by owner+name only; a supplied descriptor is validated (so malformed
-        // input still surfaces as ERR_INVALID_INPUT) but discarded afterwards so downstream
-        // projection / filtering treats the query as "no descriptor".
-        if (input.descriptor?.trim()) {
-            normalizeMethodDescriptor(input.descriptor);
-        }
-        descriptor = "";
-    }
-    else {
-        descriptor = normalizeMethodDescriptor(input.descriptor);
-    }
-    const record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), descriptor);
-    return {
-        record,
-        querySymbol: toSymbolReference(record)
-    };
-}
-function normalizeOwnerHint(ownerHint) {
-    const normalized = ownerHint?.trim();
-    if (!normalized) {
-        return undefined;
-    }
-    return normalizeMappedSymbolOutput(normalized);
-}
-function normalizeDescriptorHint(descriptorHint) {
-    const normalized = descriptorHint?.trim();
-    return normalized || undefined;
-}
-function applyDisambiguationHints(candidates, disambiguation) {
-    if (!disambiguation || candidates.length <= 1) {
-        return candidates;
-    }
-    let filtered = [...candidates];
-    const ownerHint = normalizeOwnerHint(disambiguation.ownerHint);
-    if (ownerHint) {
-        const ownerMatched = filtered.filter((candidate) => {
-            if (candidate.owner) {
-                return normalizeMappedSymbolOutput(candidate.owner) === ownerHint;
-            }
-            const normalizedSymbol = normalizeMappedSymbolOutput(candidate.symbol);
-            return normalizedSymbol.startsWith(`${ownerHint}.`);
-        });
-        if (ownerMatched.length > 0) {
-            filtered = ownerMatched;
-        }
-    }
-    const descriptorHint = normalizeDescriptorHint(disambiguation.descriptorHint);
-    if (descriptorHint) {
-        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor != null && candidate.descriptor === descriptorHint);
-        if (descriptorMatched.length > 0) {
-            filtered = descriptorMatched;
-        }
-    }
-    return filtered;
-}
-function projectLookupCandidateDescriptor(candidate, sourceDescriptor, targetDescriptor) {
-    // Tiny mappings preserve method descriptors verbatim, so single-hop tiny paths often
-    // return the source descriptor even though the final symbol is already in the target
-    // namespace. Multi-hop paths that already produced a target-side descriptor are left
-    // unchanged by design.
-    if (candidate.kind !== "method" ||
-        !candidate.descriptor ||
-        !targetDescriptor ||
-        candidate.descriptor !== sourceDescriptor) {
-        return candidate;
-    }
-    return {
-        ...candidate,
-        descriptor: targetDescriptor
-    };
-}
-function effectiveLoomSearchProjectPath(projectPath) {
-    return normalizeOptionalProjectPath(projectPath) ?? normalizeOptionalProjectPath(process.cwd());
-}
-function collectTargetRecords(graph, targetMapping) {
-    return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
-}
-function normalizeIncludedKinds(inputKinds) {
-    const normalized = new Set();
-    const kinds = inputKinds ?? ["class", "field", "method"];
-    for (const kind of kinds) {
-        if (kind === "class" || kind === "field" || kind === "method") {
-            normalized.add(kind);
-        }
-    }
-    if (normalized.size === 0) {
-        normalized.add("class");
-        normalized.add("field");
-        normalized.add("method");
-    }
-    return normalized;
-}
-function inferAmbiguityReasons(candidates, usedMojangClientMappings) {
-    if (candidates.length <= 1) {
-        return [];
-    }
-    const reasons = [];
-    const owners = [...new Set(candidates.map((c) => c.owner).filter(Boolean))];
-    if (owners.length > 1) {
-        reasons.push(`Multiple owner classes matched: ${owners.join(", ")}`);
-    }
-    const matchKinds = [...new Set(candidates.map((c) => c.matchKind))];
-    if (matchKinds.length > 1) {
-        reasons.push(`Candidates matched at different precision levels: ${matchKinds.join(", ")}`);
-    }
-    if (usedMojangClientMappings) {
-        const hasDescriptor = candidates.some((c) => c.descriptor);
-        const missingDescriptor = candidates.some((c) => !c.descriptor);
-        if (hasDescriptor && missingDescriptor) {
-            reasons.push("Method descriptor was lost through mojang-client-mappings path, causing broader matching.");
-        }
-    }
-    if (owners.length <= 1) {
-        const descriptors = [...new Set(candidates.map((c) => c.descriptor).filter(Boolean))];
-        if (descriptors.length > 1) {
-            reasons.push(`Overloaded method: ${descriptors.length} variants`);
-        }
-    }
-    if (reasons.length === 0) {
-        reasons.push(`${candidates.length} candidates matched with similar confidence scores.`);
-    }
-    return reasons;
-}
-function clampCandidateLimit(limit) {
-    if (!Number.isFinite(limit) || limit == null) {
-        return MAX_CANDIDATES;
-    }
-    return Math.max(1, Math.min(MAX_CANDIDATES, Math.trunc(limit)));
-}
-function limitResolutionCandidates(candidates, requestedLimit) {
-    const candidateCount = candidates.length;
-    const limit = clampCandidateLimit(requestedLimit);
-    const limitedCandidates = candidateCount > limit ? candidates.slice(0, limit) : candidates;
-    return {
-        candidates: limitedCandidates,
-        candidateCount,
-        ...(limitedCandidates.length < candidateCount ? { candidatesTruncated: true } : {})
-    };
-}
-function clampRowLimit(limit) {
-    if (!Number.isFinite(limit) || limit == null) {
-        return undefined;
-    }
-    return Math.max(1, Math.min(5000, Math.trunc(limit)));
-}
+/* parsers extracted to src/mapping/parsers/{symbol-records,normalize,proguard,tiny}.ts */
 export class MappingService {
     config;
     versionService;
@@ -1244,7 +266,7 @@ export class MappingService {
                     targetMapping,
                     sourcePriority: priority,
                     nextAction: "Try mapping=obfuscated which is always available.",
-                    suggestedCall: { tool: "resolve-artifact", params: { mapping: "obfuscated" } }
+                    ...buildSuggestedCall({ tool: "resolve-artifact", params: { mapping: "obfuscated" } })
                 }
             });
         }
@@ -2066,225 +1088,21 @@ export class MappingService {
         }
     }
     async loadMojangPairs(version) {
-        const warnings = [];
-        let metadata;
-        try {
-            metadata = await this.versionService.resolveVersionMappings(version);
-        }
-        catch (caughtError) {
-            return {
-                pairs: new Map(),
-                warnings: [
-                    `Failed to resolve version metadata for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`
-                ],
-                mappingArtifact: `version:${version}`
-            };
-        }
-        const clientMappingsUrl = metadata.clientMappingsUrl ?? metadata.mappingsUrl;
-        if (!clientMappingsUrl) {
-            warnings.push(`Minecraft version "${version}" does not expose client mappings URL.`);
-            return {
-                pairs: new Map(),
-                warnings,
-                mappingArtifact: metadata.versionDetailUrl
-            };
-        }
-        const mappingsPath = join(this.config.cacheDir, "mappings", version, "client_mappings.txt");
-        if (!existsSync(mappingsPath)) {
-            await mkdir(dirname(mappingsPath), { recursive: true });
-            const downloaded = await downloadToCache(clientMappingsUrl, mappingsPath, {
-                fetchFn: this.fetchFn,
-                retries: this.config.fetchRetries,
-                timeoutMs: this.config.fetchTimeoutMs
-            });
-            if (!downloaded.ok || !downloaded.path) {
-                warnings.push(`Failed to download client mappings from "${clientMappingsUrl}" (status: ${downloaded.statusCode ?? "unknown"}).`);
-                return {
-                    pairs: new Map(),
-                    warnings,
-                    mappingArtifact: clientMappingsUrl
-                };
-            }
-        }
-        try {
-            const content = await readFile(mappingsPath, "utf8");
-            return {
-                pairs: parseClientMappings(content),
-                warnings,
-                mappingArtifact: clientMappingsUrl
-            };
-        }
-        catch (caughtError) {
-            warnings.push(`Failed to parse client mappings for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
-            return {
-                pairs: new Map(),
-                warnings,
-                mappingArtifact: clientMappingsUrl
-            };
-        }
+        return loadMojangPairs(this.loaderDeps(), version);
     }
     async loadTinyPairsFromLoom(version, projectPath) {
-        const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
-        const merged = new Map();
-        const discoveredPaths = new Set();
-        for (const root of searchRoots) {
-            let discovered = [];
-            const versionRoot = join(root, version);
-            try {
-                discovered = existsSync(versionRoot)
-                    ? await fastGlob.glob(["**/*.tiny", "**/*.tinyv2"], {
-                        cwd: versionRoot,
-                        absolute: true,
-                        onlyFiles: true
-                    })
-                    : await fastGlob.glob([`${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tiny`, `${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tinyv2`], {
-                        cwd: root,
-                        absolute: true,
-                        onlyFiles: true
-                    });
-            }
-            catch {
-                continue;
-            }
-            const byVersion = discovered
-                .filter((path) => path.replaceAll("\\", "/").includes(`/${version}/`))
-                .sort((left, right) => left.localeCompare(right));
-            if (byVersion.length === 0) {
-                continue;
-            }
-            for (const path of byVersion) {
-                discoveredPaths.add(path);
-                try {
-                    const content = await readFile(path, "utf8");
-                    const parsed = parseTinyMappings(content);
-                    for (const [key, index] of parsed.entries()) {
-                        const existing = merged.get(key);
-                        if (!existing) {
-                            merged.set(key, index);
-                        }
-                        else {
-                            mergeDirectionIndexes(existing, index);
-                        }
-                    }
-                }
-                catch {
-                    // best effort: skip unreadable or invalid files
-                }
-            }
-        }
-        const orderedPaths = [...discoveredPaths].sort((left, right) => left.localeCompare(right));
-        if (orderedPaths.length > 0) {
-            return {
-                pairs: merged,
-                warnings: [],
-                mappingArtifact: orderedPaths[0]
-            };
-        }
-        return {
-            pairs: new Map(),
-            warnings: [`No Loom tiny mapping files matched version "${version}".`],
-            mappingArtifact: "loom-cache:none"
-        };
+        return loadTinyPairsFromLoom(version, projectPath);
     }
     async loadTinyPairsFromMaven(version) {
-        const warnings = [];
-        const merged = new Map();
-        const repos = this.config.sourceRepos;
-        const intermediaryUrls = [];
-        const yarnUrls = [];
-        const repoBases = repos.map((repo) => repo.replace(/\/+$/, ""));
-        const yarnCoordinatesByRepo = await Promise.all(repoBases.map(async (base) => ({
-            base,
-            yarnCoordinates: await this.fetchYarnCoordinates(base, version)
-        })));
-        for (const { base, yarnCoordinates } of yarnCoordinatesByRepo) {
-            intermediaryUrls.push(`${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`, `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`);
-            for (const coordinate of yarnCoordinates) {
-                yarnUrls.push(`${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`, `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`);
-            }
-        }
-        const allUrls = [...intermediaryUrls, ...yarnUrls];
-        const parsedResults = await Promise.allSettled(allUrls.map(async (url) => {
-            const downloaded = await downloadToCache(url, defaultDownloadPath(this.config.cacheDir, url), {
-                fetchFn: this.fetchFn,
-                retries: this.config.fetchRetries,
-                timeoutMs: this.config.fetchTimeoutMs
-            });
-            if (!downloaded.ok || !downloaded.path) {
-                return undefined;
-            }
-            return this.parseTinyFromJar(downloaded.path);
-        }));
-        for (const result of parsedResults) {
-            if (result.status !== "fulfilled" || !result.value) {
-                continue;
-            }
-            for (const [key, index] of result.value.entries()) {
-                const existing = merged.get(key);
-                if (!existing) {
-                    merged.set(key, index);
-                }
-                else {
-                    mergeDirectionIndexes(existing, index);
-                }
-            }
-        }
-        if (merged.size === 0) {
-            warnings.push(`No Maven tiny mappings could be loaded for "${version}".`);
-        }
+        return loadTinyPairsFromMaven(this.loaderDeps(), version);
+    }
+    loaderDeps() {
         return {
-            pairs: merged,
-            warnings,
-            mappingArtifact: allUrls[0] ?? "maven:none"
+            config: this.config,
+            fetchFn: this.fetchFn,
+            versionService: this.versionService
         };
     }
-    async parseTinyFromJar(jarPath) {
-        const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
-        const merged = new Map();
-        for (const entry of tinyEntries) {
-            try {
-                const parsed = parseTinyMappings(entry.content);
-                for (const [key, index] of parsed.entries()) {
-                    const existing = merged.get(key);
-                    if (!existing) {
-                        merged.set(key, index);
-                    }
-                    else {
-                        mergeDirectionIndexes(existing, index);
-                    }
-                }
-            }
-            catch {
-                // skip malformed tiny entries
-            }
-        }
-        return merged;
-    }
-    async fetchYarnCoordinates(repoBase, version) {
-        const metadataUrl = `${repoBase}/net/fabricmc/yarn/maven-metadata.xml`;
-        try {
-            const response = await this.fetchFn(metadataUrl);
-            if (!response.ok) {
-                return [];
-            }
-            const xml = await response.text();
-            const versions = [...xml.matchAll(/<version>([^<]+)<\/version>/g)]
-                .map((match) => match[1]?.trim() ?? "")
-                .filter((value) => value.startsWith(`${version}+build.`));
-            const sorted = versions.sort((left, right) => {
-                const leftBuild = Number.parseInt(left.split("+build.")[1] ?? "0", 10);
-                const rightBuild = Number.parseInt(right.split("+build.")[1] ?? "0", 10);
-                return rightBuild - leftBuild;
-            });
-            if (sorted.length > 0) {
-                return sorted.slice(0, 3);
-            }
-            return [version];
-        }
-        catch {
-            return [version];
-        }
-    }
     trimGraphCache() {
         const maxEntries = Math.max(1, this.config.maxMappingGraphCache ?? 16);
         while (this.graphCache.size > maxEntries) {