@adhisang/minecraft-modding-mcp 1.0.0

package/dist/mixin-parser.js

@@ -0,0 +1,194 @@
+/**
+ * Lightweight regex-based parser for Fabric Mixin Java sources.
+ * No AST required — pattern-matches annotations and member declarations.
+ */
+/* ------------------------------------------------------------------ */
+/*  Regex patterns                                                     */
+/* ------------------------------------------------------------------ */
+const CLASS_DECL_RE = /(?:public\s+)?(?:abstract\s+)?class\s+(\w+)/;
+// @Mixin(Foo.class)  or  @Mixin({Foo.class, Bar.class})  or  @Mixin(value = Foo.class)
+// Also handles  @Mixin(value = {Foo.class, Bar.class}, priority = 900)
+const MIXIN_ANNOTATION_START_RE = /^\s*@Mixin\s*\(/;
+const MIXIN_TARGET_RE = /(\w[\w.]*?)\.class/g;
+const MIXIN_PRIORITY_RE = /priority\s*=\s*(\d+)/;
+// Injection annotations: @Inject, @Redirect, @ModifyArg, @ModifyVariable, @ModifyConstant, @ModifyExpressionValue
+const INJECTION_ANNOTATION_RE = /^\s*@(Inject|Redirect|ModifyArg|ModifyVariable|ModifyConstant|ModifyExpressionValue)\s*\(/;
+const METHOD_ATTR_RE = /method\s*=\s*"([^"]+)"/;
+// @Shadow field / method
+const SHADOW_ANNOTATION_RE = /^\s*@Shadow\b/;
+const FIELD_DECL_RE = /(?:private|protected|public)?\s*(?:static\s+)?(?:final\s+)?(\w[\w<>,\s]*?)\s+(\w+)\s*[;=]/;
+const METHOD_DECL_RE = /(?:private|protected|public)?\s*(?:static\s+)?(?:abstract\s+)?(?:native\s+)?(\w[\w<>,\s]*?)\s+(\w+)\s*\(/;
+// @Accessor / @Invoker
+const ACCESSOR_ANNOTATION_RE = /^\s*@(Accessor|Invoker)\s*(?:\(\s*"([^"]+)"\s*\))?\s*$/;
+const ACCESSOR_ANNOTATION_START_RE = /^\s*@(Accessor|Invoker)\s*\(/;
+const ACCESSOR_EXPLICIT_RE = /"([^"]+)"/;
+// Naming conventions for accessor/invoker target inference
+const GETTER_PREFIX_RE = /^(?:get|is)([A-Z].*)/;
+const SETTER_PREFIX_RE = /^set([A-Z].*)/;
+const INVOKER_PREFIX_RE = /^(?:invoke|call)([A-Z].*)/;
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+function collectMultilineAnnotation(lines, startIndex) {
+    let depth = 0;
+    let text = "";
+    for (let i = startIndex; i < lines.length; i++) {
+        const line = lines[i];
+        text += (i === startIndex ? "" : "\n") + line;
+        for (const ch of line) {
+            if (ch === "(")
+                depth++;
+            if (ch === ")")
+                depth--;
+        }
+        if (depth <= 0) {
+            return { text, endIndex: i };
+        }
+    }
+    return { text, endIndex: lines.length - 1 };
+}
+function inferAccessorTarget(methodName) {
+    const getterMatch = GETTER_PREFIX_RE.exec(methodName);
+    if (getterMatch) {
+        return getterMatch[1].charAt(0).toLowerCase() + getterMatch[1].slice(1);
+    }
+    const setterMatch = SETTER_PREFIX_RE.exec(methodName);
+    if (setterMatch) {
+        return setterMatch[1].charAt(0).toLowerCase() + setterMatch[1].slice(1);
+    }
+    const invokerMatch = INVOKER_PREFIX_RE.exec(methodName);
+    if (invokerMatch) {
+        return invokerMatch[1].charAt(0).toLowerCase() + invokerMatch[1].slice(1);
+    }
+    return methodName;
+}
+/* ------------------------------------------------------------------ */
+/*  Main parser                                                        */
+/* ------------------------------------------------------------------ */
+export function parseMixinSource(source) {
+    const lines = source.split(/\r?\n/);
+    const parseWarnings = [];
+    const targets = [];
+    const injections = [];
+    const shadows = [];
+    const accessors = [];
+    let className = "";
+    let priority;
+    // --- Pass 1: find @Mixin annotation and class name ---
+    let i = 0;
+    while (i < lines.length) {
+        if (MIXIN_ANNOTATION_START_RE.test(lines[i])) {
+            const { text: mixinText, endIndex } = collectMultilineAnnotation(lines, i);
+            MIXIN_TARGET_RE.lastIndex = 0;
+            let match;
+            while ((match = MIXIN_TARGET_RE.exec(mixinText)) !== null) {
+                targets.push({ className: match[1] });
+            }
+            const priorityMatch = MIXIN_PRIORITY_RE.exec(mixinText);
+            if (priorityMatch) {
+                priority = parseInt(priorityMatch[1], 10);
+            }
+            i = endIndex + 1;
+            continue;
+        }
+        const classMatch = CLASS_DECL_RE.exec(lines[i]);
+        if (classMatch && !className) {
+            className = classMatch[1];
+        }
+        i++;
+    }
+    if (targets.length === 0) {
+        parseWarnings.push("No @Mixin annotation target found.");
+    }
+    // --- Pass 2: scan member annotations ---
+    i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        // --- @Inject / @Redirect / @ModifyArg etc. ---
+        const injMatch = INJECTION_ANNOTATION_RE.exec(line);
+        if (injMatch) {
+            const annotation = injMatch[1];
+            const { text: fullAnnotation, endIndex } = collectMultilineAnnotation(lines, i);
+            const methodMatch = METHOD_ATTR_RE.exec(fullAnnotation);
+            if (methodMatch) {
+                injections.push({ annotation, method: methodMatch[1], line: lineNum });
+            }
+            else {
+                parseWarnings.push(`Line ${lineNum}: @${annotation} missing method attribute.`);
+            }
+            i = endIndex + 1;
+            continue;
+        }
+        // --- @Shadow ---
+        if (SHADOW_ANNOTATION_RE.test(line)) {
+            // Advance past @Shadow line to find the declaration
+            let declLine = i + 1;
+            // Skip additional annotations between @Shadow and declaration
+            while (declLine < lines.length && /^\s*@/.test(lines[declLine])) {
+                declLine++;
+            }
+            if (declLine < lines.length) {
+                const declText = lines[declLine];
+                const methodDeclMatch = METHOD_DECL_RE.exec(declText);
+                const fieldDeclMatch = FIELD_DECL_RE.exec(declText);
+                // Method if it has parentheses
+                if (declText.includes("(") && methodDeclMatch) {
+                    shadows.push({ kind: "method", name: methodDeclMatch[2], line: lineNum });
+                }
+                else if (fieldDeclMatch) {
+                    shadows.push({ kind: "field", name: fieldDeclMatch[2], line: lineNum });
+                }
+                else {
+                    parseWarnings.push(`Line ${lineNum}: Could not parse @Shadow member declaration.`);
+                }
+            }
+            i = declLine + 1;
+            continue;
+        }
+        // --- @Accessor / @Invoker ---
+        const accessorMatch = ACCESSOR_ANNOTATION_RE.exec(line);
+        const accessorStartMatch = !accessorMatch ? ACCESSOR_ANNOTATION_START_RE.exec(line) : null;
+        if (accessorMatch || accessorStartMatch) {
+            const annotation = (accessorMatch?.[1] ?? accessorStartMatch?.[1]);
+            let explicitTarget = accessorMatch?.[2];
+            if (!explicitTarget && accessorStartMatch) {
+                const { text: fullAnnotation, endIndex } = collectMultilineAnnotation(lines, i);
+                const explicitMatch = ACCESSOR_EXPLICIT_RE.exec(fullAnnotation);
+                if (explicitMatch) {
+                    explicitTarget = explicitMatch[1];
+                }
+                i = endIndex;
+            }
+            // Find the method declaration following the annotation
+            let methodLine = i + 1;
+            while (methodLine < lines.length && /^\s*@/.test(lines[methodLine])) {
+                methodLine++;
+            }
+            if (methodLine < lines.length) {
+                const methodDeclMatch = METHOD_DECL_RE.exec(lines[methodLine]);
+                if (methodDeclMatch) {
+                    const methodName = methodDeclMatch[2];
+                    const targetName = explicitTarget ?? inferAccessorTarget(methodName);
+                    accessors.push({ annotation, name: methodName, targetName, line: lineNum });
+                }
+                else {
+                    parseWarnings.push(`Line ${lineNum}: Could not parse @${annotation} method declaration.`);
+                }
+            }
+            i = methodLine + 1;
+            continue;
+        }
+        i++;
+    }
+    return {
+        className,
+        targets,
+        priority,
+        injections,
+        shadows,
+        accessors,
+        parseWarnings
+    };
+}
+//# sourceMappingURL=mixin-parser.js.map

package/dist/mixin-validator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Validation engine for parsed Mixin sources and Access Widener files.
+ * Compares parsed annotations against resolved Minecraft bytecode signatures.
+ */
+import type { SignatureMember } from "./minecraft-explorer-service.js";
+import type { ParsedMixin } from "./mixin-parser.js";
+import type { ParsedAccessWidener, AccessWidenerEntry } from "./access-widener-parser.js";
+export type ValidationIssue = {
+    severity: "error" | "warning";
+    kind: "target-not-found" | "method-not-found" | "field-not-found" | "descriptor-mismatch" | "access-mismatch" | "unknown-annotation";
+    annotation: string;
+    target: string;
+    message: string;
+    suggestions?: string[];
+    line?: number;
+};
+export type ValidationSummary = {
+    injections: number;
+    shadows: number;
+    accessors: number;
+    total: number;
+    errors: number;
+    warnings: number;
+};
+export type MixinValidationResult = {
+    className: string;
+    targets: string[];
+    priority?: number;
+    valid: boolean;
+    issues: ValidationIssue[];
+    summary: ValidationSummary;
+    warnings: string[];
+};
+export type ResolvedTargetMembers = {
+    className: string;
+    constructors: SignatureMember[];
+    methods: SignatureMember[];
+    fields: SignatureMember[];
+};
+export type AccessWidenerValidationResult = {
+    headerVersion: string;
+    namespace: string;
+    valid: boolean;
+    entries: Array<AccessWidenerEntry & {
+        valid: boolean;
+        issue?: string;
+        suggestions?: string[];
+    }>;
+    summary: {
+        total: number;
+        valid: number;
+        invalid: number;
+    };
+    warnings: string[];
+};
+export declare function levenshteinDistance(a: string, b: string): number;
+export declare function suggestSimilar(name: string, candidates: string[], maxDistance?: number, maxResults?: number): string[];
+export declare function validateParsedMixin(parsed: ParsedMixin, targetMembers: Map<string, ResolvedTargetMembers>, warnings: string[]): MixinValidationResult;
+export declare function validateParsedAccessWidener(parsed: ParsedAccessWidener, membersByClass: Map<string, ResolvedTargetMembers>, warnings: string[]): AccessWidenerValidationResult;

package/dist/mixin-validator.js

@@ -0,0 +1,274 @@
+/**
+ * Validation engine for parsed Mixin sources and Access Widener files.
+ * Compares parsed annotations against resolved Minecraft bytecode signatures.
+ */
+/* ------------------------------------------------------------------ */
+/*  Levenshtein distance                                               */
+/* ------------------------------------------------------------------ */
+export function levenshteinDistance(a, b) {
+    const la = a.length;
+    const lb = b.length;
+    if (la === 0)
+        return lb;
+    if (lb === 0)
+        return la;
+    // Single-row DP
+    const prev = new Array(lb + 1);
+    for (let j = 0; j <= lb; j++)
+        prev[j] = j;
+    for (let i = 1; i <= la; i++) {
+        let diagPrev = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= lb; j++) {
+            const temp = prev[j];
+            if (a[i - 1] === b[j - 1]) {
+                prev[j] = diagPrev;
+            }
+            else {
+                prev[j] = 1 + Math.min(diagPrev, prev[j - 1], prev[j]);
+            }
+            diagPrev = temp;
+        }
+    }
+    return prev[lb];
+}
+export function suggestSimilar(name, candidates, maxDistance = 3, maxResults = 3) {
+    const scored = [];
+    for (const candidate of candidates) {
+        const distance = levenshteinDistance(name.toLowerCase(), candidate.toLowerCase());
+        if (distance <= maxDistance && distance > 0) {
+            scored.push({ candidate, distance });
+        }
+    }
+    scored.sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, maxResults).map((s) => s.candidate);
+}
+/* ------------------------------------------------------------------ */
+/*  Mixin validation                                                   */
+/* ------------------------------------------------------------------ */
+function allMethodNames(members) {
+    return [
+        ...members.constructors.map((m) => m.name),
+        ...members.methods.map((m) => m.name)
+    ];
+}
+function allFieldNames(members) {
+    return members.fields.map((m) => m.name);
+}
+function allMemberNames(members) {
+    return [...allMethodNames(members), ...allFieldNames(members)];
+}
+function validateInjection(inj, targetMembers, targetNames, issues) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        const methodNames = allMethodNames(members);
+        // Support method references like "<init>" and simple names
+        const methodRef = inj.method.replace(/<init>/g, "<init>");
+        if (!methodNames.includes(methodRef)) {
+            const suggestions = suggestSimilar(methodRef, methodNames);
+            issues.push({
+                severity: "error",
+                kind: "method-not-found",
+                annotation: `@${inj.annotation}`,
+                target: `${targetName}#${inj.method}`,
+                message: `Method "${inj.method}" not found in target class "${targetName}".`,
+                suggestions: suggestions.length > 0 ? suggestions : undefined,
+                line: inj.line
+            });
+        }
+    }
+}
+function validateShadow(shadow, targetMembers, targetNames, issues) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        if (shadow.kind === "field") {
+            const fieldNames = allFieldNames(members);
+            if (!fieldNames.includes(shadow.name)) {
+                const suggestions = suggestSimilar(shadow.name, fieldNames);
+                issues.push({
+                    severity: "error",
+                    kind: "field-not-found",
+                    annotation: "@Shadow",
+                    target: `${targetName}#${shadow.name}`,
+                    message: `Field "${shadow.name}" not found in target class "${targetName}".`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    line: shadow.line
+                });
+            }
+        }
+        else {
+            const methodNames = allMethodNames(members);
+            if (!methodNames.includes(shadow.name)) {
+                const suggestions = suggestSimilar(shadow.name, methodNames);
+                issues.push({
+                    severity: "error",
+                    kind: "method-not-found",
+                    annotation: "@Shadow",
+                    target: `${targetName}#${shadow.name}`,
+                    message: `Method "${shadow.name}" not found in target class "${targetName}".`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    line: shadow.line
+                });
+            }
+        }
+    }
+}
+function validateAccessor(accessor, targetMembers, targetNames, issues) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        const allNames = allMemberNames(members);
+        if (!allNames.includes(accessor.targetName)) {
+            const suggestions = suggestSimilar(accessor.targetName, allNames);
+            issues.push({
+                severity: "error",
+                kind: accessor.annotation === "Invoker" ? "method-not-found" : "field-not-found",
+                annotation: `@${accessor.annotation}`,
+                target: `${targetName}#${accessor.targetName}`,
+                message: `Target "${accessor.targetName}" (inferred from "${accessor.name}") not found in class "${targetName}".`,
+                suggestions: suggestions.length > 0 ? suggestions : undefined,
+                line: accessor.line
+            });
+        }
+    }
+}
+export function validateParsedMixin(parsed, targetMembers, warnings) {
+    const issues = [];
+    const targetNames = parsed.targets.map((t) => t.className);
+    // Check target classes exist
+    for (const target of parsed.targets) {
+        if (!targetMembers.has(target.className)) {
+            issues.push({
+                severity: "error",
+                kind: "target-not-found",
+                annotation: "@Mixin",
+                target: target.className,
+                message: `Target class "${target.className}" not found in game jar.`
+            });
+        }
+    }
+    // Only validate members against targets that were resolved
+    const resolvedTargetNames = targetNames.filter((t) => targetMembers.has(t));
+    for (const inj of parsed.injections) {
+        validateInjection(inj, targetMembers, resolvedTargetNames, issues);
+    }
+    for (const shadow of parsed.shadows) {
+        validateShadow(shadow, targetMembers, resolvedTargetNames, issues);
+    }
+    for (const accessor of parsed.accessors) {
+        validateAccessor(accessor, targetMembers, resolvedTargetNames, issues);
+    }
+    // Add parse warnings
+    warnings.push(...parsed.parseWarnings);
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warning").length;
+    return {
+        className: parsed.className,
+        targets: targetNames,
+        priority: parsed.priority,
+        valid: errorCount === 0,
+        issues,
+        summary: {
+            injections: parsed.injections.length,
+            shadows: parsed.shadows.length,
+            accessors: parsed.accessors.length,
+            total: parsed.injections.length + parsed.shadows.length + parsed.accessors.length,
+            errors: errorCount,
+            warnings: warningCount
+        },
+        warnings
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Access Widener validation                                          */
+/* ------------------------------------------------------------------ */
+export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
+    warnings.push(...parsed.parseWarnings);
+    const validatedEntries = [];
+    let validCount = 0;
+    let invalidCount = 0;
+    for (const entry of parsed.entries) {
+        const ownerFqn = entry.target.replace(/\//g, ".");
+        if (entry.targetKind === "class") {
+            if (membersByClass.has(ownerFqn)) {
+                validatedEntries.push({ ...entry, valid: true });
+                validCount++;
+            }
+            else {
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Class "${ownerFqn}" not found in game jar.`
+                });
+                invalidCount++;
+            }
+            continue;
+        }
+        // method or field
+        const members = membersByClass.get(ownerFqn);
+        if (!members) {
+            validatedEntries.push({
+                ...entry,
+                valid: false,
+                issue: `Owner class "${ownerFqn}" not found in game jar.`
+            });
+            invalidCount++;
+            continue;
+        }
+        if (entry.targetKind === "method") {
+            const methodNames = allMethodNames(members);
+            const found = members.methods.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor)) || members.constructors.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            if (found) {
+                validatedEntries.push({ ...entry, valid: true });
+                validCount++;
+            }
+            else {
+                const suggestions = entry.name ? suggestSimilar(entry.name, methodNames) : [];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Method "${entry.name}" not found in class "${ownerFqn}".`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined
+                });
+                invalidCount++;
+            }
+        }
+        else {
+            // field
+            const fieldNames = allFieldNames(members);
+            const found = members.fields.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            if (found) {
+                validatedEntries.push({ ...entry, valid: true });
+                validCount++;
+            }
+            else {
+                const suggestions = entry.name ? suggestSimilar(entry.name, fieldNames) : [];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Field "${entry.name}" not found in class "${ownerFqn}".`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined
+                });
+                invalidCount++;
+            }
+        }
+    }
+    return {
+        headerVersion: parsed.headerVersion,
+        namespace: parsed.namespace,
+        valid: invalidCount === 0,
+        entries: validatedEntries,
+        summary: {
+            total: parsed.entries.length,
+            valid: validCount,
+            invalid: invalidCount
+        },
+        warnings
+    };
+}
+//# sourceMappingURL=mixin-validator.js.map

package/dist/mod-analyzer.d.ts

@@ -0,0 +1,23 @@
+export type ModLoader = "fabric" | "quilt" | "forge" | "neoforge" | "unknown";
+export interface ModDependency {
+    modId: string;
+    versionRange?: string;
+    kind: "required" | "optional" | "recommends" | "conflicts";
+}
+export interface ModAnalysisResult {
+    loader: ModLoader;
+    modId?: string;
+    modName?: string;
+    modVersion?: string;
+    description?: string;
+    entrypoints?: Record<string, string[]>;
+    mixinConfigs?: string[];
+    accessWidener?: string;
+    dependencies?: ModDependency[];
+    classCount: number;
+    classes?: string[];
+}
+export interface AnalyzeModOptions {
+    includeClasses?: boolean;
+}
+export declare function analyzeModJar(jarPath: string, options?: AnalyzeModOptions): Promise<ModAnalysisResult>;