@adhisang/minecraft-modding-mcp 1.0.0

package/dist/minecraft-explorer-service.js

@@ -0,0 +1,562 @@
+import { createError, ERROR_CODES } from "./errors.js";
+import { loadConfig } from "./config.js";
+import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
+import { readJarEntryAsBuffer } from "./source-jar-reader.js";
+const CLASSFILE_MAGIC = 0xcafebabe;
+const MAX_INHERITANCE_DEPTH = 64;
+const ACC_PUBLIC = 0x0001;
+const ACC_PRIVATE = 0x0002;
+const ACC_PROTECTED = 0x0004;
+const ACC_STATIC = 0x0008;
+const ACC_FINAL = 0x0010;
+const ACC_SYNCHRONIZED = 0x0020;
+const ACC_VOLATILE = 0x0040;
+const ACC_BRIDGE = 0x0040;
+const ACC_TRANSIENT = 0x0080;
+const ACC_VARARGS = 0x0080;
+const ACC_NATIVE = 0x0100;
+const ACC_ABSTRACT = 0x0400;
+const ACC_STRICT = 0x0800;
+const ACC_SYNTHETIC = 0x1000;
+function lower(value) {
+    return value.toLocaleLowerCase();
+}
+function modifierPrefix(flags, category) {
+    const parts = [];
+    if ((flags & ACC_PUBLIC) !== 0) {
+        parts.push("public");
+    }
+    else if ((flags & ACC_PROTECTED) !== 0) {
+        parts.push("protected");
+    }
+    else if ((flags & ACC_PRIVATE) !== 0) {
+        parts.push("private");
+    }
+    if ((flags & ACC_STATIC) !== 0) {
+        parts.push("static");
+    }
+    if ((flags & ACC_FINAL) !== 0) {
+        parts.push("final");
+    }
+    if (category === "method") {
+        if ((flags & ACC_ABSTRACT) !== 0) {
+            parts.push("abstract");
+        }
+        if ((flags & ACC_SYNCHRONIZED) !== 0) {
+            parts.push("synchronized");
+        }
+        if ((flags & ACC_NATIVE) !== 0) {
+            parts.push("native");
+        }
+        if ((flags & ACC_STRICT) !== 0) {
+            parts.push("strictfp");
+        }
+        if ((flags & ACC_BRIDGE) !== 0) {
+            parts.push("bridge");
+        }
+        if ((flags & ACC_VARARGS) !== 0) {
+            parts.push("varargs");
+        }
+    }
+    else {
+        if ((flags & ACC_VOLATILE) !== 0) {
+            parts.push("volatile");
+        }
+        if ((flags & ACC_TRANSIENT) !== 0) {
+            parts.push("transient");
+        }
+    }
+    return parts.join(" ");
+}
+function parseFieldType(descriptor, position = 0) {
+    if (position >= descriptor.length) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "Unexpected end of descriptor.",
+            details: { descriptor, position }
+        });
+    }
+    const token = descriptor[position];
+    switch (token) {
+        case "B":
+            return { type: "byte", next: position + 1 };
+        case "C":
+            return { type: "char", next: position + 1 };
+        case "D":
+            return { type: "double", next: position + 1 };
+        case "F":
+            return { type: "float", next: position + 1 };
+        case "I":
+            return { type: "int", next: position + 1 };
+        case "J":
+            return { type: "long", next: position + 1 };
+        case "S":
+            return { type: "short", next: position + 1 };
+        case "Z":
+            return { type: "boolean", next: position + 1 };
+        case "V":
+            return { type: "void", next: position + 1 };
+        case "L": {
+            const end = descriptor.indexOf(";", position);
+            if (end < 0) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Invalid descriptor: ${descriptor}`,
+                    details: { descriptor, position }
+                });
+            }
+            const type = descriptor.slice(position + 1, end).replace(/\//g, ".");
+            return { type, next: end + 1 };
+        }
+        case "[": {
+            const inner = parseFieldType(descriptor, position + 1);
+            return { type: `${inner.type}[]`, next: inner.next };
+        }
+        default:
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Unsupported descriptor token "${token}" in "${descriptor}".`,
+                details: { descriptor, token, position }
+            });
+    }
+}
+function parseMethodDescriptor(descriptor) {
+    if (!descriptor.startsWith("(")) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Invalid method descriptor "${descriptor}".`,
+            details: { descriptor }
+        });
+    }
+    const args = [];
+    let cursor = 1;
+    while (cursor < descriptor.length && descriptor[cursor] !== ")") {
+        const parsed = parseFieldType(descriptor, cursor);
+        args.push(parsed.type);
+        cursor = parsed.next;
+    }
+    if (descriptor[cursor] !== ")") {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Invalid method descriptor "${descriptor}".`,
+            details: { descriptor, cursor }
+        });
+    }
+    const returnType = parseFieldType(descriptor, cursor + 1).type;
+    return { args, returnType };
+}
+function hasPublicVisibility(flags) {
+    return (flags & ACC_PUBLIC) !== 0 || (flags & ACC_PROTECTED) !== 0;
+}
+function toInternalName(fqn) {
+    return fqn.trim().replace(/\./g, "/");
+}
+function extractVersionFromPath(inputPath) {
+    return inputPath.match(/(\d+\.\d+(?:\.\d+)?)/)?.[1];
+}
+class ByteReader {
+    offset = 0;
+    buffer;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    readU1() {
+        const value = this.buffer.readUInt8(this.offset);
+        this.offset += 1;
+        return value;
+    }
+    readU2() {
+        const value = this.buffer.readUInt16BE(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    readU4() {
+        const value = this.buffer.readUInt32BE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    readBytes(length) {
+        const slice = this.buffer.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return slice;
+    }
+    skip(length) {
+        this.offset += length;
+    }
+}
+function readUtf8(cp, index) {
+    const entry = cp[index];
+    if (!entry || entry.tag !== 1) {
+        throw createError({
+            code: ERROR_CODES.CLASS_NOT_FOUND,
+            message: `Invalid UTF8 constant pool index ${index}. Class file may be corrupted.`,
+            details: { index }
+        });
+    }
+    return entry.value;
+}
+function readClassName(cp, index) {
+    const entry = cp[index];
+    if (!entry || entry.tag !== 7) {
+        throw createError({
+            code: ERROR_CODES.CLASS_NOT_FOUND,
+            message: `Invalid class constant pool index ${index}. Class file may be corrupted.`,
+            details: { index }
+        });
+    }
+    return readUtf8(cp, entry.index);
+}
+function readOptionalClassName(cp, index) {
+    if (index === 0) {
+        return undefined;
+    }
+    return readClassName(cp, index);
+}
+function readAttributes(reader, cp, count) {
+    const names = [];
+    for (let index = 0; index < count; index += 1) {
+        const nameIndex = reader.readU2();
+        const length = reader.readU4();
+        const attributeName = readUtf8(cp, nameIndex);
+        names.push(attributeName);
+        reader.skip(length);
+    }
+    return names;
+}
+function parseClassFile(buffer) {
+    const reader = new ByteReader(buffer);
+    if (reader.readU4() !== CLASSFILE_MAGIC) {
+        throw createError({
+            code: ERROR_CODES.INTERNAL,
+            message: "Invalid class file magic. File is not a valid Java class."
+        });
+    }
+    reader.readU2();
+    reader.readU2();
+    const cpCount = reader.readU2();
+    const cp = new Array(cpCount).fill(undefined);
+    for (let index = 1; index < cpCount; index += 1) {
+        const tag = reader.readU1();
+        switch (tag) {
+            case 1: {
+                const length = reader.readU2();
+                cp[index] = { tag: 1, value: reader.readBytes(length).toString("utf8") };
+                break;
+            }
+            case 3:
+            case 4:
+                reader.skip(4);
+                cp[index] = { tag };
+                break;
+            case 5:
+            case 6:
+                reader.skip(8);
+                cp[index] = { tag };
+                index += 1;
+                break;
+            case 7:
+            case 8:
+            case 16:
+            case 19:
+            case 20:
+                cp[index] = { tag, index: reader.readU2() };
+                break;
+            case 9:
+            case 10:
+            case 11:
+            case 12:
+            case 17:
+            case 18:
+                cp[index] = { tag, index1: reader.readU2(), index2: reader.readU2() };
+                break;
+            case 15:
+                cp[index] = { tag, refKind: reader.readU1(), refIndex: reader.readU2() };
+                break;
+            default:
+                throw createError({
+                    code: ERROR_CODES.INTERNAL,
+                    message: `Unsupported constant pool tag ${tag}. Class file may be corrupted.`,
+                    details: { tag, index }
+                });
+        }
+    }
+    reader.readU2();
+    const thisClassIndex = reader.readU2();
+    const superClassIndex = reader.readU2();
+    const interfacesCount = reader.readU2();
+    const interfaceInternalNames = [];
+    for (let index = 0; index < interfacesCount; index += 1) {
+        interfaceInternalNames.push(readClassName(cp, reader.readU2()));
+    }
+    const readMembers = () => {
+        const count = reader.readU2();
+        const members = [];
+        for (let index = 0; index < count; index += 1) {
+            const accessFlags = reader.readU2();
+            const nameIndex = reader.readU2();
+            const descriptorIndex = reader.readU2();
+            const attributesCount = reader.readU2();
+            const attributeNames = readAttributes(reader, cp, attributesCount);
+            members.push({
+                name: readUtf8(cp, nameIndex),
+                descriptor: readUtf8(cp, descriptorIndex),
+                accessFlags,
+                isSynthetic: (accessFlags & ACC_SYNTHETIC) !== 0 ||
+                    attributeNames.some((attributeName) => attributeName === "Synthetic")
+            });
+        }
+        return members;
+    };
+    const fields = readMembers();
+    const methods = readMembers();
+    const attributesCount = reader.readU2();
+    readAttributes(reader, cp, attributesCount);
+    return {
+        internalName: readClassName(cp, thisClassIndex),
+        superInternalName: readOptionalClassName(cp, superClassIndex),
+        interfaceInternalNames,
+        fields,
+        methods
+    };
+}
+export class MinecraftExplorerService {
+    config;
+    signatureCache = new Map();
+    constructor(explicitConfig) {
+        this.config = explicitConfig ?? loadConfig();
+    }
+    async getSignature(input) {
+        const jarPath = this.normalizeJarPathOrThrow(input.jarPath);
+        const fqn = input.fqn.trim();
+        if (!fqn) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "fqn must be a non-empty string."
+            });
+        }
+        const access = input.access ?? "public";
+        const includeSynthetic = input.includeSynthetic ?? false;
+        const includeInherited = input.includeInherited ?? false;
+        const memberPattern = input.memberPattern ? lower(input.memberPattern) : undefined;
+        const cacheKey = [
+            jarPath,
+            fqn,
+            access,
+            includeSynthetic ? "1" : "0",
+            includeInherited ? "1" : "0",
+            memberPattern ?? ""
+        ].join("|");
+        const cached = this.signatureCache.get(cacheKey);
+        if (cached) {
+            this.signatureCache.delete(cacheKey);
+            this.signatureCache.set(cacheKey, cached);
+            return {
+                ...cached,
+                context: this.contextForJar(jarPath)
+            };
+        }
+        const classEntryPath = `${toInternalName(fqn)}.class`;
+        let classBuffer;
+        try {
+            classBuffer = await readJarEntryAsBuffer(jarPath, classEntryPath);
+        }
+        catch {
+            throw createError({
+                code: ERROR_CODES.CLASS_NOT_FOUND,
+                message: `Class "${fqn}" was not found in "${jarPath}".`,
+                details: { fqn, jarPath, classEntryPath }
+            });
+        }
+        const parsed = parseClassFile(classBuffer);
+        const parsedClassCache = new Map([[parsed.internalName, parsed]]);
+        const warnings = [];
+        const warnMissingInheritedClass = (internalName, relation) => {
+            warnings.push(`Could not resolve ${relation} class "${internalName.replace(/\//g, ".")}" while expanding inherited members.`);
+        };
+        const readParsedClassByInternalName = async (internalName, relation) => {
+            const cachedParsed = parsedClassCache.get(internalName);
+            if (cachedParsed) {
+                return cachedParsed;
+            }
+            const classPath = `${internalName}.class`;
+            try {
+                const classBytes = await readJarEntryAsBuffer(jarPath, classPath);
+                const parsedClass = parseClassFile(classBytes);
+                parsedClassCache.set(parsedClass.internalName, parsedClass);
+                return parsedClass;
+            }
+            catch {
+                warnMissingInheritedClass(internalName, relation);
+                return undefined;
+            }
+        };
+        const hierarchyClasses = [parsed];
+        if (includeInherited) {
+            const visited = new Set([parsed.internalName]);
+            let currentSuper = parsed.superInternalName;
+            let depth = 0;
+            while (currentSuper) {
+                if (depth >= MAX_INHERITANCE_DEPTH) {
+                    warnings.push(`Stopped inherited member expansion at depth ${MAX_INHERITANCE_DEPTH} while resolving "${fqn}".`);
+                    break;
+                }
+                if (visited.has(currentSuper)) {
+                    warnings.push(`Detected class hierarchy cycle at "${currentSuper.replace(/\//g, ".")}".`);
+                    break;
+                }
+                const parsedSuper = await readParsedClassByInternalName(currentSuper, "super");
+                if (!parsedSuper) {
+                    break;
+                }
+                visited.add(parsedSuper.internalName);
+                hierarchyClasses.push(parsedSuper);
+                currentSuper = parsedSuper.superInternalName;
+                depth += 1;
+            }
+            const queue = [];
+            const queued = new Set();
+            const interfaceClasses = [];
+            const enqueueInterfaces = (classFile) => {
+                for (const interfaceInternalName of classFile.interfaceInternalNames) {
+                    if (visited.has(interfaceInternalName) || queued.has(interfaceInternalName)) {
+                        continue;
+                    }
+                    queue.push(interfaceInternalName);
+                    queued.add(interfaceInternalName);
+                }
+            };
+            for (const classFile of hierarchyClasses) {
+                enqueueInterfaces(classFile);
+            }
+            while (queue.length > 0) {
+                const interfaceInternalName = queue.shift();
+                queued.delete(interfaceInternalName);
+                if (visited.has(interfaceInternalName)) {
+                    continue;
+                }
+                const parsedInterface = await readParsedClassByInternalName(interfaceInternalName, "interface");
+                if (!parsedInterface) {
+                    continue;
+                }
+                visited.add(parsedInterface.internalName);
+                interfaceClasses.push(parsedInterface);
+                enqueueInterfaces(parsedInterface);
+            }
+            hierarchyClasses.push(...interfaceClasses);
+        }
+        const toSignatureMember = (ownerFqn, ownerSimpleClassName, member, category) => {
+            if (category === "field") {
+                const fieldType = parseFieldType(member.descriptor).type;
+                const modifiers = modifierPrefix(member.accessFlags, "field");
+                return {
+                    ownerFqn,
+                    name: member.name,
+                    javaSignature: `${modifiers ? `${modifiers} ` : ""}${fieldType} ${member.name}`.trim(),
+                    jvmDescriptor: member.descriptor,
+                    accessFlags: member.accessFlags,
+                    isSynthetic: member.isSynthetic
+                };
+            }
+            const parsedMethod = parseMethodDescriptor(member.descriptor);
+            const modifiers = modifierPrefix(member.accessFlags, "method");
+            const args = parsedMethod.args.join(", ");
+            if (member.name === "<init>") {
+                return {
+                    ownerFqn,
+                    name: member.name,
+                    javaSignature: `${modifiers ? `${modifiers} ` : ""}${ownerSimpleClassName}(${args})`.trim(),
+                    jvmDescriptor: member.descriptor,
+                    accessFlags: member.accessFlags,
+                    isSynthetic: member.isSynthetic
+                };
+            }
+            return {
+                ownerFqn,
+                name: member.name,
+                javaSignature: `${modifiers ? `${modifiers} ` : ""}${parsedMethod.returnType} ${member.name}(${args})`.trim(),
+                jvmDescriptor: member.descriptor,
+                accessFlags: member.accessFlags,
+                isSynthetic: member.isSynthetic
+            };
+        };
+        const shouldIncludeMember = (member) => {
+            if (!includeSynthetic && member.isSynthetic) {
+                return false;
+            }
+            if (access === "public" && !hasPublicVisibility(member.accessFlags)) {
+                return false;
+            }
+            if (memberPattern && !lower(member.name).includes(memberPattern)) {
+                return false;
+            }
+            return true;
+        };
+        const toMembers = (classFile, category, predicate) => {
+            const ownerFqn = classFile.internalName.replace(/\//g, ".");
+            const ownerSimpleClassName = ownerFqn.split(".").at(-1) ?? ownerFqn;
+            const sourceMembers = category === "field" ? classFile.fields : classFile.methods;
+            return sourceMembers
+                .filter(predicate)
+                .map((member) => toSignatureMember(ownerFqn, ownerSimpleClassName, member, category));
+        };
+        const dedupeMembers = (members) => {
+            const seen = new Set();
+            const result = [];
+            for (const member of members) {
+                const key = `${member.ownerFqn}|${member.name}|${member.jvmDescriptor}`;
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
+                result.push(member);
+            }
+            return result;
+        };
+        const targetClass = hierarchyClasses[0];
+        const constructors = toMembers(targetClass, "method", (member) => member.name === "<init>" && shouldIncludeMember(member));
+        const fields = dedupeMembers(hierarchyClasses.flatMap((classFile) => toMembers(classFile, "field", (member) => shouldIncludeMember(member))));
+        const methods = dedupeMembers(hierarchyClasses.flatMap((classFile) => toMembers(classFile, "method", (member) => member.name !== "<init>" && shouldIncludeMember(member))));
+        const output = {
+            constructors,
+            methods,
+            fields,
+            warnings,
+            context: this.contextForJar(jarPath)
+        };
+        this.signatureCache.set(cacheKey, output);
+        this.trimSignatureCache();
+        return output;
+    }
+    contextForJar(jarPath) {
+        return {
+            minecraftVersion: extractVersionFromPath(jarPath) ?? "unknown",
+            mappingType: "unknown",
+            mappingNamespace: "official",
+            jarHash: artifactSignatureFromFile(jarPath).sourceArtifactId,
+            generatedAt: new Date().toISOString()
+        };
+    }
+    normalizeJarPathOrThrow(jarPath) {
+        try {
+            return normalizeJarPath(jarPath);
+        }
+        catch (error) {
+            throw createError({
+                code: ERROR_CODES.JAR_NOT_FOUND,
+                message: error instanceof Error ? error.message : `Could not resolve jar "${jarPath}".`,
+                details: { jarPath }
+            });
+        }
+    }
+    trimSignatureCache() {
+        const maxEntries = Math.max(1, this.config.maxSignatureCache ?? 2_000);
+        while (this.signatureCache.size > maxEntries) {
+            const oldest = this.signatureCache.keys().next().value;
+            if (!oldest) {
+                return;
+            }
+            this.signatureCache.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=minecraft-explorer-service.js.map

package/dist/mixin-parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight regex-based parser for Fabric Mixin Java sources.
+ * No AST required — pattern-matches annotations and member declarations.
+ */
+export type ParsedMixinTarget = {
+    className: string;
+};
+export type ParsedInjection = {
+    annotation: string;
+    method: string;
+    line: number;
+};
+export type ParsedShadow = {
+    kind: "field" | "method";
+    name: string;
+    descriptor?: string;
+    line: number;
+};
+export type ParsedAccessor = {
+    annotation: "Accessor" | "Invoker";
+    name: string;
+    targetName: string;
+    line: number;
+};
+export type ParsedMixin = {
+    className: string;
+    targets: ParsedMixinTarget[];
+    priority?: number;
+    injections: ParsedInjection[];
+    shadows: ParsedShadow[];
+    accessors: ParsedAccessor[];
+    parseWarnings: string[];
+};
+export declare function parseMixinSource(source: string): ParsedMixin;