@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.1

package/dist/source/lifecycle/diff.js

@@ -0,0 +1,265 @@
+import { buildSuggestedCall } from "../../build-suggested-call.js";
+import { ERROR_CODES, createError, isAppError } from "../../errors.js";
+import { compactDiffDelta, diffMembersByKey, emptyDiffDelta, sortDiffMembers } from "./diff-utils.js";
+import { normalizeMapping, resolveToObfuscatedClassName } from "./mapping-helpers.js";
+export async function diffClassSignatures(svc, input) {
+    const className = input.className.trim();
+    const fromVersion = input.fromVersion.trim();
+    const toVersion = input.toVersion.trim();
+    const includeFullDiff = input.includeFullDiff ?? true;
+    if (!className || !fromVersion || !toVersion) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "className, fromVersion, and toVersion must be non-empty strings.",
+            details: {
+                className: input.className,
+                fromVersion: input.fromVersion,
+                toVersion: input.toVersion
+            }
+        });
+    }
+    const mapping = normalizeMapping(input.mapping);
+    const manifestOrder = await svc.versionService.listVersionIds();
+    if (manifestOrder.length === 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: "No Minecraft versions were returned by manifest.",
+            details: {
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    const chronological = [...manifestOrder].reverse();
+    const fromIndex = chronological.indexOf(fromVersion);
+    const toIndex = chronological.indexOf(toVersion);
+    if (fromIndex < 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: `fromVersion "${fromVersion}" was not found in manifest.`,
+            details: {
+                fromVersion,
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    if (toIndex < 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: `toVersion "${toVersion}" was not found in manifest.`,
+            details: {
+                toVersion,
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    if (fromIndex > toIndex) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "fromVersion must be older than or equal to toVersion.",
+            details: { fromVersion, toVersion }
+        });
+    }
+    const mappingWarnings = [];
+    const obfuscatedFromClassName = await resolveToObfuscatedClassName(svc, className, fromVersion, mapping, input.sourcePriority, mappingWarnings);
+    const obfuscatedToClassName = fromVersion === toVersion
+        ? obfuscatedFromClassName
+        : await resolveToObfuscatedClassName(svc, className, toVersion, mapping, input.sourcePriority, mappingWarnings);
+    const [fromResolved, toResolved] = await Promise.all([
+        svc.versionService.resolveVersionJar(fromVersion),
+        svc.versionService.resolveVersionJar(toVersion)
+    ]);
+    const loadSignature = async (version, jarPath, obfuscatedClassName) => {
+        try {
+            const signature = await svc.explorerService.getSignature({
+                fqn: obfuscatedClassName,
+                jarPath,
+                access: "all",
+                includeSynthetic: false,
+                includeInherited: false
+            });
+            return {
+                constructors: signature.constructors,
+                fields: signature.fields,
+                methods: signature.methods,
+                warnings: signature.warnings
+            };
+        }
+        catch (caughtError) {
+            if (isAppError(caughtError) && caughtError.code === ERROR_CODES.CLASS_NOT_FOUND) {
+                return undefined;
+            }
+            throw caughtError;
+        }
+    };
+    const [fromSignature, toSignature] = await Promise.all([
+        loadSignature(fromVersion, fromResolved.jarPath, obfuscatedFromClassName),
+        loadSignature(toVersion, toResolved.jarPath, obfuscatedToClassName)
+    ]);
+    const warnings = [...mappingWarnings];
+    if (fromSignature) {
+        warnings.push(...fromSignature.warnings.map((warning) => `[${fromVersion}] ${warning}`));
+    }
+    if (toSignature) {
+        warnings.push(...toSignature.warnings.map((warning) => `[${toVersion}] ${warning}`));
+    }
+    let classChange = "present_in_both";
+    if (!fromSignature && !toSignature) {
+        classChange = "absent_in_both";
+        warnings.push(`Class "${className}" was not found in both versions.`);
+    }
+    else if (!fromSignature) {
+        classChange = "added";
+    }
+    else if (!toSignature) {
+        classChange = "removed";
+    }
+    const fromMembers = fromSignature ?? {
+        constructors: [],
+        fields: [],
+        methods: [],
+        warnings: []
+    };
+    const toMembers = toSignature ?? {
+        constructors: [],
+        fields: [],
+        methods: [],
+        warnings: []
+    };
+    const constructors = classChange === "added"
+        ? {
+            added: sortDiffMembers(toMembers.constructors),
+            removed: [],
+            modified: []
+        }
+        : classChange === "removed"
+            ? {
+                added: [],
+                removed: sortDiffMembers(fromMembers.constructors),
+                modified: []
+            }
+            : classChange === "absent_in_both"
+                ? emptyDiffDelta()
+                : diffMembersByKey(fromMembers.constructors, toMembers.constructors, (member) => member.jvmDescriptor, false);
+    const methods = classChange === "added"
+        ? {
+            added: sortDiffMembers(toMembers.methods),
+            removed: [],
+            modified: []
+        }
+        : classChange === "removed"
+            ? {
+                added: [],
+                removed: sortDiffMembers(fromMembers.methods),
+                modified: []
+            }
+            : classChange === "absent_in_both"
+                ? emptyDiffDelta()
+                : diffMembersByKey(fromMembers.methods, toMembers.methods, (member) => `${member.name}#${member.jvmDescriptor}`, false);
+    const fields = classChange === "added"
+        ? {
+            added: sortDiffMembers(toMembers.fields),
+            removed: [],
+            modified: []
+        }
+        : classChange === "removed"
+            ? {
+                added: [],
+                removed: sortDiffMembers(fromMembers.fields),
+                modified: []
+            }
+            : classChange === "absent_in_both"
+                ? emptyDiffDelta()
+                : diffMembersByKey(fromMembers.fields, toMembers.fields, (member) => member.name, true);
+    // Remap diff delta members for non-obfuscated mappings
+    const remapDelta = async (delta, kind) => {
+        const [addedResult, removedResult] = await Promise.all([
+            svc.remapSignatureMembers(delta.added, kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings),
+            svc.remapSignatureMembers(delta.removed, kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings)
+        ]);
+        const remappedModified = await Promise.all(delta.modified.map(async (change) => {
+            if (!change.from || !change.to) {
+                throw createError({
+                    code: ERROR_CODES.INTERNAL,
+                    message: "Modified diff members are missing before remap.",
+                    details: {
+                        key: change.key,
+                        kind,
+                        fromVersion,
+                        toVersion,
+                        mapping
+                    }
+                });
+            }
+            const [fromResult, toResult] = await Promise.all([
+                svc.remapSignatureMembers([change.from], kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings),
+                svc.remapSignatureMembers([change.to], kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings)
+            ]);
+            const fromMember = fromResult.members[0];
+            const toMember = toResult.members[0];
+            if (!fromMember || !toMember) {
+                throw createError({
+                    code: ERROR_CODES.INTERNAL,
+                    message: "Failed to remap modified diff members.",
+                    details: {
+                        key: change.key,
+                        kind,
+                        fromVersion,
+                        toVersion,
+                        mapping
+                    }
+                });
+            }
+            return { ...change, from: fromMember, to: toMember };
+        }));
+        return { added: addedResult.members, removed: removedResult.members, modified: remappedModified };
+    };
+    const [remappedConstructors, remappedMethods, remappedFields] = await Promise.all([
+        remapDelta(constructors, "method"),
+        remapDelta(methods, "method"),
+        remapDelta(fields, "field")
+    ]);
+    const summary = {
+        constructors: {
+            added: remappedConstructors.added.length,
+            removed: remappedConstructors.removed.length,
+            modified: remappedConstructors.modified.length
+        },
+        methods: {
+            added: remappedMethods.added.length,
+            removed: remappedMethods.removed.length,
+            modified: remappedMethods.modified.length
+        },
+        fields: {
+            added: remappedFields.added.length,
+            removed: remappedFields.removed.length,
+            modified: remappedFields.modified.length
+        },
+        total: {
+            added: remappedConstructors.added.length + remappedMethods.added.length + remappedFields.added.length,
+            removed: remappedConstructors.removed.length + remappedMethods.removed.length + remappedFields.removed.length,
+            modified: remappedConstructors.modified.length + remappedMethods.modified.length + remappedFields.modified.length
+        }
+    };
+    return {
+        query: {
+            className,
+            fromVersion,
+            toVersion,
+            mapping
+        },
+        range: {
+            fromVersion,
+            toVersion
+        },
+        classChange,
+        constructors: includeFullDiff ? remappedConstructors : compactDiffDelta(remappedConstructors),
+        methods: includeFullDiff ? remappedMethods : compactDiffDelta(remappedMethods),
+        fields: includeFullDiff ? remappedFields : compactDiffDelta(remappedFields),
+        summary,
+        warnings
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/source/lifecycle/mapping-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { SignatureMember } from "../../minecraft-explorer-service.js";
+import type { SourceService } from "../../source-service.js";
+import type { MappingSourcePriority, SourceMapping } from "../../types.js";
+export declare function normalizeMapping(mapping: SourceMapping | undefined): SourceMapping;
+export declare function rejectLifecycleClassLikeInput(svc: SourceService, input: {
+    symbol: string;
+    className: string;
+    methodName: string;
+    mapping: SourceMapping;
+    version?: string;
+    sourcePriority?: MappingSourcePriority;
+}): void;
+export declare function releaseLifecycleMappingGraph(svc: SourceService, version: string, sourcePriority: MappingSourcePriority | undefined): void;
+export declare function resolveToObfuscatedClassName(svc: SourceService, className: string, version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[]): Promise<string>;
+export declare function resolveToObfuscatedMemberName(svc: SourceService, name: string, ownerInSourceMapping: string, descriptor: string | undefined, kind: "field" | "method", version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[]): Promise<{
+    name: string;
+    descriptor?: string;
+}>;
+export declare function remapSignatureMembers(svc: SourceService, members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string): Promise<{
+    members: SignatureMember[];
+    failedNames: Set<string>;
+}>;

package/dist/source/lifecycle/mapping-helpers.js

@@ -0,0 +1,327 @@
+import { buildSuggestedCall } from "../../build-suggested-call.js";
+import { ERROR_CODES, createError } from "../../errors.js";
+import { rebuildJavaSignature, remapJvmDescriptor } from "../descriptor-utils.js";
+export function normalizeMapping(mapping) {
+    if (mapping == null) {
+        return "obfuscated";
+    }
+    if (mapping === "obfuscated" ||
+        mapping === "mojang" ||
+        mapping === "intermediary" ||
+        mapping === "yarn") {
+        return mapping;
+    }
+    throw createError({
+        code: ERROR_CODES.MAPPING_UNAVAILABLE,
+        message: `Unsupported mapping "${mapping}".`,
+        details: {
+            mapping,
+            nextAction: "Try mapping=obfuscated which is always available.",
+            ...buildSuggestedCall({ tool: "resolve-artifact", params: { mapping: "obfuscated" } })
+        }
+    });
+}
+function looksLikeClassSegment(name) {
+    const trimmed = name.trim();
+    return /^[A-Z_$]/.test(trimmed);
+}
+export function rejectLifecycleClassLikeInput(svc, input) {
+    void svc;
+    if (!looksLikeClassSegment(input.methodName)) {
+        return;
+    }
+    const classLikeSymbol = `${input.className}.${input.methodName}`;
+    throw createError({
+        code: ERROR_CODES.INVALID_INPUT,
+        message: `symbol must be in the form "fully.qualified.Class.method".`,
+        details: {
+            symbol: input.symbol,
+            classLikeSymbol,
+            nextAction: "Pass lifecycle input as Class.method and use the separate descriptor field for exact overload matching.",
+            ...(input.version
+                ? buildSuggestedCall({
+                    tool: "check-symbol-exists",
+                    params: {
+                        version: input.version,
+                        kind: "class",
+                        name: classLikeSymbol,
+                        sourceMapping: input.mapping
+                    }
+                })
+                : {})
+        }
+    });
+}
+export function releaseLifecycleMappingGraph(svc, version, sourcePriority) {
+    if ("releaseGraphCacheEntry" in svc.mappingService &&
+        typeof svc.mappingService.releaseGraphCacheEntry === "function") {
+        svc.mappingService.releaseGraphCacheEntry(version, sourcePriority);
+    }
+}
+export async function resolveToObfuscatedClassName(svc, className, version, mapping, sourcePriority, warnings) {
+    return svc.resolveClassNameForLookup({
+        className,
+        version,
+        sourceMapping: mapping,
+        targetMapping: "obfuscated",
+        sourcePriority,
+        warnings,
+        context: "bytecode lookup"
+    });
+}
+export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
+    if (mapping === "obfuscated") {
+        return {
+            name,
+            descriptor: kind === "method" ? descriptor : undefined
+        };
+    }
+    try {
+        const canResolveMethodExactly = kind === "method" &&
+            descriptor &&
+            "resolveMethodMappingExact" in svc.mappingService &&
+            typeof svc.mappingService.resolveMethodMappingExact === "function";
+        const mapped = canResolveMethodExactly
+            ? await svc.mappingService.resolveMethodMappingExact({
+                version,
+                owner: ownerInSourceMapping,
+                name,
+                descriptor,
+                sourceMapping: mapping,
+                targetMapping: "obfuscated",
+                sourcePriority
+            })
+            : await svc.mappingService.findMapping({
+                version,
+                kind,
+                name,
+                owner: ownerInSourceMapping,
+                descriptor,
+                // When we do have a descriptor this path is an exact lookup (the resolveMethodMappingExact
+                // fast path is chosen instead whenever possible). findMapping's service-layer default is
+                // "name-only" to match the public tool schema, so we must opt in to strict semantics here
+                // to preserve the descriptor-aware overload selection this caller relies on.
+                signatureMode: kind === "method"
+                    ? descriptor
+                        ? "exact"
+                        : "name-only"
+                    : undefined,
+                sourceMapping: mapping,
+                targetMapping: "obfuscated",
+                sourcePriority
+            });
+        warnings.push(...mapped.warnings);
+        if (mapped.resolved && mapped.resolvedSymbol) {
+            return {
+                name: mapped.resolvedSymbol.name,
+                descriptor: kind === "method" ? mapped.resolvedSymbol.descriptor ?? descriptor : undefined
+            };
+        }
+        if (canResolveMethodExactly && (mapped.status === "not_found" || mapped.status === "mapping_unavailable")) {
+            const fallbackMapped = await svc.mappingService.findMapping({
+                version,
+                kind,
+                name,
+                owner: ownerInSourceMapping,
+                descriptor,
+                signatureMode: "exact",
+                sourceMapping: mapping,
+                targetMapping: "obfuscated",
+                sourcePriority
+            });
+            warnings.push(...fallbackMapped.warnings);
+            if (fallbackMapped.resolved && fallbackMapped.resolvedSymbol) {
+                return {
+                    name: fallbackMapped.resolvedSymbol.name,
+                    descriptor: kind === "method" ? fallbackMapped.resolvedSymbol.descriptor ?? descriptor : undefined
+                };
+            }
+        }
+        warnings.push(`Could not map ${kind} "${name}" from ${mapping} to obfuscated.`);
+    }
+    catch (caughtError) {
+        warnings.push(`Mapping lookup failed for ${kind} "${name}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+    }
+    return {
+        name,
+        descriptor: kind === "method" ? descriptor : undefined
+    };
+}
+export async function remapSignatureMembers(svc, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath) {
+    const failedNames = new Set();
+    if (sourceMapping === targetMapping) {
+        return { members, failedNames };
+    }
+    const memberKeyToRemapped = new Map();
+    const memberDescriptorRemapped = new Map();
+    const ownerToRemapped = new Map();
+    for (const member of members) {
+        const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
+        if (!memberKeyToRemapped.has(memberKey)) {
+            memberKeyToRemapped.set(memberKey, member.name);
+        }
+        if (!ownerToRemapped.has(member.ownerFqn)) {
+            ownerToRemapped.set(member.ownerFqn, member.ownerFqn);
+        }
+    }
+    const ownerEntries = [...ownerToRemapped.entries()];
+    await Promise.all(ownerEntries.map(async ([obfuscatedFqn]) => {
+        try {
+            const mapped = await svc.mappingService.findMapping({
+                version,
+                kind: "class",
+                name: obfuscatedFqn,
+                sourceMapping,
+                targetMapping,
+                sourcePriority,
+                projectPath
+            });
+            if (mapped.resolved && mapped.resolvedSymbol) {
+                ownerToRemapped.set(obfuscatedFqn, mapped.resolvedSymbol.name);
+            }
+        }
+        catch {
+            // keep source FQN as fallback
+        }
+    }));
+    const descriptorClassRefs = new Set();
+    for (const member of members) {
+        for (const match of member.jvmDescriptor.matchAll(/L([^;]+);/g)) {
+            const dotFqn = match[1].replace(/\//g, ".");
+            if (!ownerToRemapped.has(dotFqn)) {
+                descriptorClassRefs.add(dotFqn);
+            }
+        }
+    }
+    if (descriptorClassRefs.size > 0) {
+        const refs = [...descriptorClassRefs];
+        for (const ref of refs) {
+            ownerToRemapped.set(ref, ref);
+        }
+        await Promise.all(refs.map(async (dotFqn) => {
+            try {
+                const mapped = await svc.mappingService.findMapping({
+                    version,
+                    kind: "class",
+                    name: dotFqn,
+                    sourceMapping,
+                    targetMapping,
+                    sourcePriority,
+                    projectPath
+                });
+                if (mapped.resolved && mapped.resolvedSymbol) {
+                    ownerToRemapped.set(dotFqn, mapped.resolvedSymbol.name);
+                }
+            }
+            catch {
+                // keep source name as fallback
+            }
+        }));
+    }
+    const classMap = new Map();
+    for (const [src, tgt] of ownerToRemapped) {
+        if (src !== tgt) {
+            classMap.set(src, tgt);
+        }
+    }
+    const canResolveMethodExactly = kind === "method" &&
+        "resolveMethodMappingExact" in svc.mappingService &&
+        typeof svc.mappingService.resolveMethodMappingExact === "function";
+    const memberEntries = [...memberKeyToRemapped.entries()];
+    await Promise.all(memberEntries.map(async ([key, _sourceName]) => {
+        const [ownerFqn, name, descriptor] = key.split("\0");
+        try {
+            const targetOwner = ownerToRemapped.get(ownerFqn) ?? ownerFqn;
+            if (canResolveMethodExactly && descriptor) {
+                try {
+                    const exactResult = await svc.mappingService.resolveMethodMappingExact({
+                        version,
+                        owner: ownerFqn,
+                        name: name,
+                        descriptor,
+                        sourceMapping,
+                        targetMapping,
+                        sourcePriority,
+                        projectPath
+                    });
+                    if (exactResult.resolved && exactResult.resolvedSymbol) {
+                        memberKeyToRemapped.set(key, exactResult.resolvedSymbol.name);
+                        if (exactResult.resolvedSymbol.descriptor) {
+                            memberDescriptorRemapped.set(key, exactResult.resolvedSymbol.descriptor);
+                        }
+                        return;
+                    }
+                }
+                catch (exactError) {
+                    warnings.push(`Exact method resolution failed for "${name}" (falling back to name-based lookup): ${exactError instanceof Error ? exactError.message : String(exactError)}`);
+                }
+            }
+            const remappedDescriptorHint = kind === "method" && descriptor
+                ? remapJvmDescriptor(descriptor, classMap)
+                : undefined;
+            const mapped = await svc.mappingService.findMapping({
+                version,
+                kind,
+                name,
+                owner: ownerFqn,
+                descriptor: kind === "method" ? descriptor : undefined,
+                signatureMode: kind === "method" && descriptor ? "exact" : undefined,
+                sourceMapping,
+                targetMapping,
+                sourcePriority,
+                projectPath,
+                disambiguation: {
+                    ownerHint: targetOwner,
+                    descriptorHint: remappedDescriptorHint
+                }
+            });
+            if (mapped.resolved && mapped.resolvedSymbol) {
+                memberKeyToRemapped.set(key, mapped.resolvedSymbol.name);
+                if (kind === "method" && mapped.resolvedSymbol.descriptor) {
+                    memberDescriptorRemapped.set(key, mapped.resolvedSymbol.descriptor);
+                }
+            }
+            else if (mapped.status === "ambiguous" && mapped.candidates && mapped.candidates.length > 0) {
+                const ownerMatched = mapped.candidates.filter((c) => c.owner === targetOwner);
+                const best = ownerMatched.length > 0 ? ownerMatched : mapped.candidates;
+                if (best.length > 0) {
+                    memberKeyToRemapped.set(key, best[0].name);
+                    if (best[0].confidence < 0.9) {
+                        failedNames.add(name);
+                    }
+                }
+                else {
+                    warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                    failedNames.add(name);
+                }
+            }
+            else {
+                warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                failedNames.add(name);
+            }
+        }
+        catch {
+            warnings.push(`Remap failed for ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+            failedNames.add(name);
+        }
+    }));
+    const isField = kind === "field";
+    return {
+        members: members.map((member) => {
+            const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
+            const remappedName = memberKeyToRemapped.get(memberKey) ?? member.name;
+            const remappedOwner = ownerToRemapped.get(member.ownerFqn) ?? member.ownerFqn;
+            const remappedDescriptor = memberDescriptorRemapped.get(memberKey)
+                ?? remapJvmDescriptor(member.jvmDescriptor, classMap);
+            return {
+                ...member,
+                name: remappedName,
+                ownerFqn: remappedOwner,
+                jvmDescriptor: remappedDescriptor,
+                javaSignature: rebuildJavaSignature({ name: remappedName, ownerFqn: remappedOwner, accessFlags: member.accessFlags }, remappedDescriptor, isField)
+            };
+        }),
+        failedNames
+    };
+}
+//# sourceMappingURL=mapping-helpers.js.map

package/dist/source/lifecycle/runtime-check.d.ts

@@ -0,0 +1,2 @@
+import type { CheckSymbolExistsInput, CheckSymbolExistsOutput, SourceService } from "../../source-service.js";
+export declare function checkSymbolExistsInUnobfuscatedRuntime(svc: SourceService, input: CheckSymbolExistsInput, fallbackBase: CheckSymbolExistsOutput): Promise<CheckSymbolExistsOutput | undefined>;