@adhisang/minecraft-modding-mcp 2.0.0 → 3.0.0

package/dist/mapping-service.js

@@ -37,13 +37,21 @@ function addToSetMap(map, key, value) {
     map.set(normalizedKey, existing);
 }
 function normalizedVariants(symbol) {
-    const variants = new Set();
-    variants.add(symbol);
-    const dotted = symbol.replace(/\//g, ".");
-    variants.add(dotted);
-    const slashed = symbol.replace(/\./g, "/");
-    variants.add(slashed);
-    return [...variants];
+    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();
@@ -230,12 +238,42 @@ function pairKey(sourceMapping, targetMapping) {
     return `${sourceMapping}->${targetMapping}`;
 }
 function parsePairKey(key) {
-    const [source, target] = key.split("->");
+    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);
@@ -552,38 +590,48 @@ function mappingSourceOrder(priority) {
     }
     return ["loom-cache", "maven"];
 }
-function namespacePath(pairs, sourceMapping, targetMapping) {
+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 (queue.length > 0) {
-        const current = queue.shift();
+    while (queueIndex < queue.length) {
+        const current = queue[queueIndex];
+        queueIndex += 1;
         if (current === targetMapping) {
             break;
         }
-        for (const key of pairs.keys()) {
-            const parsed = parsePairKey(key);
-            if (parsed.sourceMapping !== current) {
-                continue;
-            }
-            if (parent.has(parsed.targetMapping)) {
+        const neighbors = adjacency.get(current);
+        if (!neighbors) {
+            continue;
+        }
+        for (const neighbor of neighbors) {
+            if (parent.has(neighbor)) {
                 continue;
             }
-            parent.set(parsed.targetMapping, current);
-            queue.push(parsed.targetMapping);
+            parent.set(neighbor, current);
+            queue.push(neighbor);
         }
     }
     if (!parent.has(targetMapping)) {
+        graph.pathCache.set(key, undefined);
         return undefined;
     }
-    const path = [];
+    const reversedPath = [];
     let cursor = targetMapping;
     while (cursor) {
-        path.unshift(cursor);
+        reversedPath.push(cursor);
         cursor = parent.get(cursor);
     }
+    const path = reversedPath.reverse();
+    graph.pathCache.set(key, path);
     return path;
 }
 function pathUsesSource(pairs, path, source) {
@@ -765,17 +813,7 @@ function applyDisambiguationHints(candidates, disambiguation) {
     return filtered;
 }
 function collectTargetRecords(graph, targetMapping) {
-    const merged = new Map();
-    for (const [key, pair] of graph.pairs.entries()) {
-        const parsed = parsePairKey(key);
-        if (parsed.targetMapping !== targetMapping) {
-            continue;
-        }
-        for (const record of pair.index.records.values()) {
-            merged.set(buildSymbolKey(record), record);
-        }
-    }
-    return [...merged.values()];
+    return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
 }
 function normalizeIncludedKinds(inputKinds) {
     const normalized = new Set();
@@ -823,6 +861,28 @@ function inferAmbiguityReasons(candidates, usedMojangClientMappings) {
     }
     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)));
+}
 export class MappingService {
     config;
     versionService;
@@ -845,7 +905,7 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -872,18 +932,21 @@ export class MappingService {
                 matchKind: "exact",
                 confidence: 1
             });
+            const limited = limitResolutionCandidates([identity], input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: querySymbol,
-                candidates: [identity],
+                candidates: limited.candidates,
+                candidateCount: limited.candidateCount,
+                candidatesTruncated: limited.candidatesTruncated,
                 warnings: []
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
                 querySymbol,
@@ -891,6 +954,7 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings: [
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
@@ -903,6 +967,7 @@ export class MappingService {
             warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
         }
         const candidates = disambiguatedCandidates.map(toResolutionCandidate);
+        const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         if (queryRecord.kind === "method" &&
             queryRecord.descriptor &&
             pathUsesSource(graph.pairs, path, "mojang-client-mappings") &&
@@ -925,7 +990,9 @@ export class MappingService {
             resolved: status === "resolved",
             status,
             resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
-            candidates,
+            candidates: limitedCandidates.candidates,
+            candidateCount: limitedCandidates.candidateCount,
+            candidatesTruncated: limitedCandidates.candidatesTruncated,
             warnings,
             provenance: this.provenanceForPath(graph, path),
             ambiguityReasons
@@ -963,7 +1030,7 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
                 code: ERROR_CODES.MAPPING_UNAVAILABLE,
@@ -1033,18 +1100,21 @@ export class MappingService {
                 matchKind: "exact",
                 confidence: 1
             });
+            const limited = limitResolutionCandidates([resolvedCandidate], input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: resolvedCandidate,
-                candidates: [resolvedCandidate],
+                candidates: limited.candidates,
+                candidateCount: limited.candidateCount,
+                candidatesTruncated: limited.candidatesTruncated,
                 warnings: []
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
                 querySymbol,
@@ -1052,6 +1122,7 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings: [
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
@@ -1062,6 +1133,7 @@ export class MappingService {
             .mapCandidatesAlongPath(graph, path, queryRecord)
             .filter((candidate) => candidate.kind === "method");
         const candidates = rawCandidates.map(toResolutionCandidate);
+        const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === descriptor);
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
@@ -1071,7 +1143,9 @@ export class MappingService {
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: resolved,
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1083,7 +1157,9 @@ export class MappingService {
                 mappingContext,
                 resolved: false,
                 status: "ambiguous",
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1095,7 +1171,9 @@ export class MappingService {
                 mappingContext,
                 resolved: false,
                 status: "mapping_unavailable",
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1105,7 +1183,9 @@ export class MappingService {
             mappingContext,
             resolved: false,
             status: "not_found",
-            candidates,
+            candidates: limitedCandidates.candidates,
+            candidateCount: limitedCandidates.candidateCount,
+            candidatesTruncated: limitedCandidates.candidatesTruncated,
             warnings,
             provenance: this.provenanceForPath(graph, path)
         };
@@ -1137,6 +1217,19 @@ export class MappingService {
         const graph = await this.loadGraph(version, priority);
         const warnings = [...graph.warnings];
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
+        const pathCache = new Map();
+        const resolvePath = (sourceMapping, targetMapping) => {
+            if (sourceMapping === targetMapping) {
+                return [sourceMapping];
+            }
+            const key = pairKey(sourceMapping, targetMapping);
+            if (pathCache.has(key)) {
+                return pathCache.get(key);
+            }
+            const path = namespacePath(graph, sourceMapping, targetMapping);
+            pathCache.set(key, path);
+            return path;
+        };
         const classByMapping = {
             [classNameMapping]: createClassSymbolRecord(className)
         };
@@ -1144,7 +1237,7 @@ export class MappingService {
             if (mapping === classNameMapping) {
                 continue;
             }
-            const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping]);
+            const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping], resolvePath(classNameMapping, mapping));
             if (mapped.length > 1) {
                 const competing = mapped.slice(0, 5).map((c) => c.symbol);
                 warnings.push(`Class identity mapping to ${mapping} is ambiguous for "${className}": competing=[${competing.join(", ")}].`);
@@ -1167,6 +1260,7 @@ export class MappingService {
                     yarn: classByMapping.yarn?.symbol
                 },
                 rows: [],
+                rowCount: 0,
                 warnings
             };
         }
@@ -1220,7 +1314,7 @@ export class MappingService {
                     resolved = baseRecord;
                 }
                 else {
-                    const mapped = this.mapRecordBetweenMappings(graph, baseMapping, mapping, baseRecord);
+                    const mapped = this.mapRecordBetweenMappings(graph, baseMapping, mapping, baseRecord, resolvePath(baseMapping, mapping));
                     let filtered = mapped;
                     if (baseRecord.kind !== "class" && classIdentity) {
                         filtered = filtered.filter((candidate) => candidate.owner === classIdentity.symbol);
@@ -1255,6 +1349,9 @@ export class MappingService {
                 ambiguousRowCount += 1;
             }
         }
+        const rowCount = rows.length;
+        const rowLimit = clampRowLimit(input.maxRows);
+        const limitedRows = rowLimit != null && rowCount > rowLimit ? rows.slice(0, rowLimit) : rows;
         return {
             version,
             className,
@@ -1265,7 +1362,9 @@ export class MappingService {
                 intermediary: classByMapping.intermediary?.symbol,
                 yarn: classByMapping.yarn?.symbol
             },
-            rows,
+            rows: limitedRows,
+            rowCount,
+            rowsTruncated: limitedRows.length < rowCount ? true : undefined,
             warnings,
             ambiguousRowCount: ambiguousRowCount > 0 ? ambiguousRowCount : undefined
         };
@@ -1346,18 +1445,22 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings
             };
         }
         const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
+            const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: status === "resolved",
                 status,
                 resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings
             };
         };
@@ -1408,11 +1511,11 @@ export class MappingService {
         }
         return buildOutput(querySymbol, [], "not_found");
     }
-    mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record) {
+    mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record, resolvedPath) {
         if (sourceMapping === targetMapping) {
             return [record];
         }
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = resolvedPath ?? namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return [];
         }
@@ -1568,7 +1671,7 @@ export class MappingService {
             memberRemapAvailable = true;
         }
         else {
-            const path = namespacePath(graph.pairs, input.requestedMapping, "obfuscated");
+            const path = namespacePath(graph, input.requestedMapping, "obfuscated");
             memberRemapAvailable = path != null && path.length > 1;
             if (!memberRemapAvailable) {
                 degradations.push(`No mapping path from ${input.requestedMapping} to obfuscated; member remap will fail.`);
@@ -1611,6 +1714,9 @@ export class MappingService {
                 version,
                 priority,
                 pairs: new Map(),
+                adjacency: new Map(),
+                pathCache: new Map(),
+                recordsByTarget: new Map(),
                 warnings: [
                     `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
                 ]
@@ -1620,27 +1726,38 @@ export class MappingService {
             version,
             priority,
             pairs: new Map(),
+            adjacency: new Map(),
+            pathCache: new Map(),
+            recordsByTarget: new Map(),
             warnings: []
         };
         const mojangLoad = await this.loadMojangPairs(version);
         graph.warnings.push(...mojangLoad.warnings);
         this.mergePairs(graph.pairs, mojangLoad.pairs, "mojang-client-mappings", mojangLoad.mappingArtifact);
         let tinyLoaded = false;
+        const deferredTinyWarnings = [];
         for (const source of mappingSourceOrder(priority)) {
             const tinyLoad = source === "loom-cache"
                 ? await this.loadTinyPairsFromLoom(version)
                 : await this.loadTinyPairsFromMaven(version);
-            graph.warnings.push(...tinyLoad.warnings);
             if (tinyLoad.pairs.size === 0) {
+                deferredTinyWarnings.push(...tinyLoad.warnings);
                 continue;
             }
             tinyLoaded = true;
             this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
+            graph.warnings.push(...tinyLoad.warnings);
+            if (deferredTinyWarnings.length > 0) {
+                graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+            }
             break;
         }
         if (!tinyLoaded) {
+            graph.warnings.push(...deferredTinyWarnings);
             graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
         }
+        graph.adjacency = buildAdjacency(graph.pairs);
+        graph.recordsByTarget = buildTargetRecordIndex(graph.pairs);
         return graph;
     }
     mergePairs(target, source, pairSource, mappingArtifact) {
@@ -1763,31 +1880,37 @@ export class MappingService {
     async loadTinyPairsFromMaven(version) {
         const warnings = [];
         const merged = new Map();
-        const attemptedArtifacts = [];
         const repos = this.config.sourceRepos;
         const intermediaryUrls = [];
         const yarnUrls = [];
-        for (const repo of repos) {
-            const base = repo.replace(/\/+$/, "");
+        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`);
-            const yarnCoordinates = await this.fetchYarnCoordinates(base, version);
             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];
-        for (const url of allUrls) {
-            attemptedArtifacts.push(url);
+        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;
             }
-            const parsed = await this.parseTinyFromJar(downloaded.path);
-            for (const [key, index] of parsed.entries()) {
+            for (const [key, index] of result.value.entries()) {
                 const existing = merged.get(key);
                 if (!existing) {
                     merged.set(key, index);
@@ -1803,7 +1926,7 @@ export class MappingService {
         return {
             pairs: merged,
             warnings,
-            mappingArtifact: attemptedArtifacts[0] ?? "maven:none"
+            mappingArtifact: allUrls[0] ?? "maven:none"
         };
     }
     async parseTinyFromJar(jarPath) {

package/dist/minecraft-explorer-service.d.ts

@@ -38,6 +38,5 @@ export declare class MinecraftExplorerService {
     getSignature(input: GetSignatureInput): Promise<GetSignatureOutput>;
     private contextForJar;
     private normalizeJarPathOrThrow;
-    private trimSignatureCache;
 }
 export {};