@adhisang/minecraft-modding-mcp 1.1.0 → 1.2.0

package/dist/mapping-service.js

@@ -246,12 +246,85 @@ function ensurePairIndex(indexes, from, to) {
     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 → official class names (for the official 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 officialToMojang = createDirectionIndex();
     const mojangToOfficial = 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 → official)
+    const mojangToOfficialClass = 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 officialClass = classMatch[2]?.trim() ?? "";
+            if (mojangClass && officialClass) {
+                mojangToOfficialClass.set(mojangClass, officialClass);
+                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 text.split(/\r?\n/)) {
+    for (const rawLine of lines) {
         const line = rawLine.trim();
         if (!line || line.startsWith("#")) {
             continue;
@@ -264,7 +337,6 @@ function parseClientMappings(text) {
                 currentClass = undefined;
                 continue;
             }
-            classCount += 1;
             currentClass = {
                 official: officialClass,
                 mojang: mojangClass
@@ -286,10 +358,14 @@ function parseClientMappings(text) {
             continue;
         }
         const mojangMemberSignature = stripLineInfo(leftRaw);
-        const methodName = parseMethodName(mojangMemberSignature);
-        if (methodName) {
-            addLookupEntries(officialToMojang, createMethodSymbolRecord(currentClass.official, rightRaw, undefined), createMethodSymbolRecord(currentClass.mojang, methodName, undefined));
-            addLookupEntries(mojangToOfficial, createMethodSymbolRecord(currentClass.mojang, methodName, undefined), createMethodSymbolRecord(currentClass.official, rightRaw, undefined));
+        // Try method parsing with JVM descriptor
+        const officialMethod = parseProguardMethod(mojangMemberSignature, mojangToOfficialClass);
+        if (officialMethod) {
+            const mojangMethod = parseProguardMethod(mojangMemberSignature, undefined);
+            const officialDescriptor = officialMethod.descriptor;
+            const mojangDescriptor = mojangMethod?.descriptor;
+            addLookupEntries(officialToMojang, createMethodSymbolRecord(currentClass.official, rightRaw, officialDescriptor), createMethodSymbolRecord(currentClass.mojang, officialMethod.name, mojangDescriptor));
+            addLookupEntries(mojangToOfficial, createMethodSymbolRecord(currentClass.mojang, officialMethod.name, mojangDescriptor), createMethodSymbolRecord(currentClass.official, rightRaw, officialDescriptor));
             continue;
         }
         const fieldName = parseFieldName(mojangMemberSignature);
@@ -299,12 +375,6 @@ function parseClientMappings(text) {
         addLookupEntries(officialToMojang, createFieldSymbolRecord(currentClass.official, rightRaw), createFieldSymbolRecord(currentClass.mojang, fieldName));
         addLookupEntries(mojangToOfficial, createFieldSymbolRecord(currentClass.mojang, fieldName), createFieldSymbolRecord(currentClass.official, rightRaw));
     }
-    if (classCount === 0) {
-        throw createError({
-            code: ERROR_CODES.MAPPING_UNAVAILABLE,
-            message: "No class mappings could be parsed from client mappings."
-        });
-    }
     const result = new Map();
     result.set(pairKey("official", "mojang"), officialToMojang);
     result.set(pairKey("mojang", "official"), mojangToOfficial);
@@ -591,7 +661,7 @@ function normalizeMethodDescriptor(descriptor) {
     }
     return normalized;
 }
-function normalizeQuerySymbol(input) {
+function normalizeQuerySymbol(input, signatureMode) {
     if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
         throw invalidInputError('kind must be one of "class", "field", or "method".', {
             kind: input.kind
@@ -647,12 +717,53 @@ function normalizeQuerySymbol(input) {
             querySymbol: toSymbolReference(record)
         };
     }
-    const record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), normalizeMethodDescriptor(input.descriptor));
+    const descriptor = signatureMode === "name-only"
+        ? (input.descriptor?.trim() || "")
+        : 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 === descriptorHint);
+        if (descriptorMatched.length > 0) {
+            filtered = descriptorMatched;
+        }
+    }
+    return filtered;
+}
 function collectTargetRecords(graph, targetMapping) {
     const merged = new Map();
     for (const [key, pair] of graph.pairs.entries()) {
@@ -681,6 +792,37 @@ function normalizeIncludedKinds(inputKinds) {
     }
     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;
+}
 export class MappingService {
     config;
     versionService;
@@ -755,17 +897,28 @@ export class MappingService {
             };
         }
         const rawCandidates = this.mapCandidatesAlongPath(graph, path, queryRecord);
-        const candidates = rawCandidates.map(toResolutionCandidate);
         const warnings = [];
+        const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation);
+        if (rawCandidates.length > disambiguatedCandidates.length) {
+            warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
+        }
+        const candidates = disambiguatedCandidates.map(toResolutionCandidate);
         if (queryRecord.kind === "method" &&
             queryRecord.descriptor &&
-            pathUsesSource(graph.pairs, path, "mojang-client-mappings")) {
+            pathUsesSource(graph.pairs, path, "mojang-client-mappings") &&
+            candidates.length !== 1) {
             warnings.push("Method descriptor could not be preserved through mojang-client-mappings and may have used name-based fallback.");
         }
         if (candidates.length === 0) {
             warnings.push("No mapping candidate matched the input symbol.");
         }
+        else if (candidates.length > 1) {
+            warnings.push(`Ambiguous mapping: ${candidates.length} candidates matched. Provide a stricter symbol input or disambiguation hints.`);
+        }
         const status = candidates.length === 0 ? "not_found" : candidates.length === 1 ? "resolved" : "ambiguous";
+        const ambiguityReasons = candidates.length > 1
+            ? inferAmbiguityReasons(candidates, pathUsesSource(graph.pairs, path, "mojang-client-mappings"))
+            : undefined;
         return {
             querySymbol,
             mappingContext,
@@ -774,7 +927,8 @@ export class MappingService {
             resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
             candidates,
             warnings,
-            provenance: this.provenanceForPath(graph, path)
+            provenance: this.provenanceForPath(graph, path),
+            ambiguityReasons
         };
     }
     async ensureMappingAvailable(input) {
@@ -818,7 +972,9 @@ export class MappingService {
                     version,
                     sourceMapping,
                     targetMapping,
-                    sourcePriority: priority
+                    sourcePriority: priority,
+                    nextAction: "Try mapping=official which is always available.",
+                    suggestedCall: { tool: "resolve-artifact", params: { mapping: "official" } }
                 }
             });
         }
@@ -996,7 +1152,8 @@ export class MappingService {
             }
             const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping]);
             if (mapped.length > 1) {
-                warnings.push(`Class identity mapping to ${mapping} is ambiguous for "${className}".`);
+                const competing = mapped.slice(0, 5).map((c) => c.symbol);
+                warnings.push(`Class identity mapping to ${mapping} is ambiguous for "${className}": competing=[${competing.join(", ")}].`);
             }
             if (mapped.length > 0) {
                 classByMapping[mapping] = mapped[0];
@@ -1032,6 +1189,7 @@ export class MappingService {
             return includeKinds.has("method");
         });
         const rows = [];
+        let ambiguousRowCount = 0;
         const rowSeen = new Set();
         const rowKindOrder = {
             class: 0,
@@ -1055,6 +1213,7 @@ export class MappingService {
                 continue;
             }
             rowSeen.add(key);
+            let rowHadAmbiguity = false;
             const row = {
                 kind: baseRecord.kind,
                 descriptor: baseRecord.descriptor,
@@ -1079,7 +1238,9 @@ export class MappingService {
                         }
                     }
                     if (filtered.length > 1) {
-                        warnings.push(`Row mapping to ${mapping} is ambiguous for "${baseRecord.symbol}". Using highest-ranked candidate.`);
+                        const competing = filtered.slice(0, 5).map((c) => c.symbol);
+                        warnings.push(`Row mapping to ${mapping} is ambiguous for "${baseRecord.symbol}": competing=[${competing.join(", ")}]. Using highest-ranked candidate.`);
+                        rowHadAmbiguity = true;
                     }
                     resolved = filtered[0];
                 }
@@ -1096,6 +1257,9 @@ export class MappingService {
             }
             row.completeness = Boolean(row.official && row.mojang && row.intermediary && row.yarn);
             rows.push(row);
+            if (rowHadAmbiguity) {
+                ambiguousRowCount += 1;
+            }
         }
         return {
             version,
@@ -1108,7 +1272,8 @@ export class MappingService {
                 yarn: classByMapping.yarn?.symbol
             },
             rows,
-            warnings
+            warnings,
+            ambiguousRowCount: ambiguousRowCount > 0 ? ambiguousRowCount : undefined
         };
     }
     async checkSymbolExists(input) {
@@ -1122,7 +1287,6 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
         const sourceMapping = input.sourceMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping)) {
             throw createError({
@@ -1139,12 +1303,51 @@ export class MappingService {
             sourceMapping,
             sourcePriorityApplied: priority
         };
+        const classNameMode = input.nameMode === "auto" ? "auto" : "fqcn";
+        const normalizedQuery = input.kind === "class" && classNameMode === "auto"
+            ? (() => {
+                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 autoClassName = normalizeMappedSymbolOutput(input.name.trim());
+                if (!autoClassName) {
+                    throw invalidInputError("name must be a non-empty string.", {
+                        name: input.name
+                    });
+                }
+                return {
+                    mode: "auto-class",
+                    className: autoClassName,
+                    querySymbol: {
+                        kind: "class",
+                        name: autoClassName,
+                        symbol: autoClassName
+                    }
+                };
+            })()
+            : (() => {
+                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
+                return {
+                    mode: "strict",
+                    queryRecord,
+                    querySymbol
+                };
+            })();
         const graph = await this.loadGraph(version, priority);
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
             return {
-                querySymbol,
+                querySymbol: normalizedQuery.querySymbol,
                 mappingContext,
                 resolved: false,
                 status: "mapping_unavailable",
@@ -1152,7 +1355,7 @@ export class MappingService {
                 warnings
             };
         }
-        const buildOutput = (matched, status) => {
+        const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
             return {
                 querySymbol,
@@ -1164,29 +1367,52 @@ export class MappingService {
                 warnings
             };
         };
+        if (normalizedQuery.mode === "auto-class") {
+            const autoClassName = normalizedQuery.className;
+            if (autoClassName.includes(".")) {
+                const matched = records.filter((record) => record.kind === "class" && record.symbol === autoClassName);
+                const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
+                return buildOutput(normalizedQuery.querySymbol, matched, status);
+            }
+            const matched = records.filter((record) => record.kind === "class" && record.name === autoClassName);
+            const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
+            if (status === "ambiguous") {
+                warnings.push(`Multiple class symbols matched short name "${autoClassName}". Provide fully-qualified class name.`);
+            }
+            return buildOutput(normalizedQuery.querySymbol, matched, status);
+        }
+        const { queryRecord, querySymbol } = normalizedQuery;
         if (queryRecord.kind === "class") {
             const matched = records.filter((record) => record.kind === "class" && record.symbol === queryRecord.symbol);
             const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
-            return buildOutput(matched, status);
+            return buildOutput(querySymbol, matched, status);
         }
         if (queryRecord.kind === "field") {
             const matched = records.filter((record) => record.kind === "field" && record.owner === queryRecord.owner && record.name === queryRecord.name);
             const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
-            return buildOutput(matched, status);
+            return buildOutput(querySymbol, matched, status);
         }
         const methodCandidates = records.filter((record) => record.kind === "method" && record.owner === queryRecord.owner && record.name === queryRecord.name);
+        // name-only mode: skip descriptor matching, resolve by owner+name
+        if (input.signatureMode === "name-only") {
+            const status = methodCandidates.length === 1 ? "resolved" : methodCandidates.length > 1 ? "ambiguous" : "not_found";
+            if (status === "ambiguous") {
+                warnings.push(`Multiple method overloads matched name "${queryRecord.name}" in owner "${queryRecord.owner}". Provide descriptor for exact match.`);
+            }
+            return buildOutput(querySymbol, methodCandidates, status);
+        }
         const descriptorMatched = methodCandidates.filter((record) => record.descriptor === queryRecord.descriptor);
         if (descriptorMatched.length === 1) {
-            return buildOutput(descriptorMatched, "resolved");
+            return buildOutput(querySymbol, descriptorMatched, "resolved");
         }
         if (descriptorMatched.length > 1) {
-            return buildOutput(descriptorMatched, "ambiguous");
+            return buildOutput(querySymbol, descriptorMatched, "ambiguous");
         }
         if (methodCandidates.some((candidate) => candidate.descriptor == null)) {
             warnings.push("Descriptor-level existence checks are unavailable for descriptorless mapping entries.");
-            return buildOutput(methodCandidates, "mapping_unavailable");
+            return buildOutput(querySymbol, methodCandidates, "mapping_unavailable");
         }
-        return buildOutput([], "not_found");
+        return buildOutput(querySymbol, [], "not_found");
     }
     mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record) {
         if (sourceMapping === targetMapping) {
@@ -1308,6 +1534,59 @@ export class MappingService {
             priority: graph.priority
         };
     }
+    /**
+     * Probe the mapping graph health for a given version.
+     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     */
+    async checkMappingHealth(input) {
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        const degradations = [];
+        let graph;
+        try {
+            graph = await this.loadGraph(input.version, priority);
+        }
+        catch {
+            return {
+                mojangMappingsAvailable: false,
+                tinyMappingsAvailable: false,
+                memberRemapAvailable: false,
+                degradations: ["Mapping graph could not be loaded."]
+            };
+        }
+        // Check for mojang-client-mappings pairs
+        let mojangAvailable = false;
+        let tinyAvailable = false;
+        for (const [, record] of graph.pairs) {
+            if (record.source === "mojang-client-mappings")
+                mojangAvailable = true;
+            if (record.source === "loom-cache" || record.source === "maven")
+                tinyAvailable = true;
+        }
+        if (!mojangAvailable) {
+            degradations.push("Mojang client mappings are not available for this version.");
+        }
+        if (!tinyAvailable) {
+            degradations.push("No intermediary/yarn tiny mappings were found for this version.");
+        }
+        // Check if member remap path exists (requestedMapping → official)
+        let memberRemapAvailable = false;
+        if (input.requestedMapping === "official") {
+            memberRemapAvailable = true;
+        }
+        else {
+            const path = namespacePath(graph.pairs, input.requestedMapping, "official");
+            memberRemapAvailable = path != null && path.length > 1;
+            if (!memberRemapAvailable) {
+                degradations.push(`No mapping path from ${input.requestedMapping} to official; member remap will fail.`);
+            }
+        }
+        return {
+            mojangMappingsAvailable: mojangAvailable,
+            tinyMappingsAvailable: tinyAvailable,
+            memberRemapAvailable,
+            degradations
+        };
+    }
     async loadGraph(version, priority) {
         const cacheKey = `${version}|${priority}`;
         const cached = this.graphCache.get(cacheKey);

package/dist/mixin-parser.d.ts

@@ -26,6 +26,7 @@ export type ParsedMixin = {
     className: string;
     targets: ParsedMixinTarget[];
     priority?: number;
+    imports: Map<string, string>;
     injections: ParsedInjection[];
     shadows: ParsedShadow[];
     accessors: ParsedAccessor[];