@adhisang/minecraft-modding-mcp 1.1.0 → 1.2.0

package/dist/mixin-parser.js

@@ -5,21 +5,29 @@
 /* ------------------------------------------------------------------ */
 /*  Regex patterns                                                     */
 /* ------------------------------------------------------------------ */
-const CLASS_DECL_RE = /(?:public\s+)?(?:abstract\s+)?class\s+(\w+)/;
+const CLASS_DECL_RE = /(?:public\s+)?(?:abstract\s+)?(?:class|interface)\s+(\w+)/;
+// import statements for FQCN resolution
+const IMPORT_RE = /^\s*import\s+([\w.]+)\s*;/;
 // @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+)/;
+// String-form targets: @Mixin(targets = "pkg.Class") or @Mixin(targets = {"pkg.A", "pkg.B"})
+const MIXIN_TARGETS_STRING_RE = /targets\s*=\s*(?:\{([^}]+)\}|"([^"]+)")/;
+const MIXIN_TARGETS_STRING_ITEM_RE = /"([^"]+)"/g;
 // Injection annotations: @Inject, @Redirect, @ModifyArg, @ModifyVariable, @ModifyConstant, @ModifyExpressionValue
-const INJECTION_ANNOTATION_RE = /^\s*@(Inject|Redirect|ModifyArg|ModifyVariable|ModifyConstant|ModifyExpressionValue)\s*\(/;
+// Also MixinExtras: @WrapOperation, @WrapWithCondition, @ModifyReturnValue
+const INJECTION_ANNOTATION_RE = /^\s*@(Inject|Redirect|ModifyArg|ModifyVariable|ModifyConstant|ModifyExpressionValue|WrapOperation|WrapWithCondition|ModifyReturnValue)\s*\(/;
 const METHOD_ATTR_RE = /method\s*=\s*"([^"]+)"/;
+const METHOD_ATTR_ARRAY_RE = /method\s*=\s*\{([^}]+)\}/;
+const METHOD_ATTR_ITEM_RE = /"([^"]+)"/g;
 // @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*\(/;
+const FIELD_DECL_RE = /(?:private|protected|public)?\s*(?:static\s+)?(?:final\s+)?(?:volatile\s+)?([\w.][\w<>,.\s?\[\]]*?)\s+([\w$]+)\s*[;=]/;
+const METHOD_DECL_RE = /(?:private|protected|public)?\s*(?:default\s+)?(?:static\s+)?(?:synchronized\s+)?(?:abstract\s+)?(?:native\s+)?(?:<[\w<>,.\s?&\[\]]+>\s+)?([\w.][\w<>,.\s?\[\]]*?)\s+([\w$]+)\s*\(/;
 // @Accessor / @Invoker
-const ACCESSOR_ANNOTATION_RE = /^\s*@(Accessor|Invoker)\s*(?:\(\s*"([^"]+)"\s*\))?\s*$/;
+const ACCESSOR_ANNOTATION_RE = /^\s*@(Accessor|Invoker)\s*(?:\(\s*\)|\(\s*(?:value\s*=\s*)?"([^"]+)"\s*(?:,\s*\w+\s*=\s*(?:\w+|"[^"]*")\s*)*\))?(?:\s|$)/;
 const ACCESSOR_ANNOTATION_START_RE = /^\s*@(Accessor|Invoker)\s*\(/;
 const ACCESSOR_EXPLICIT_RE = /"([^"]+)"/;
 // Naming conventions for accessor/invoker target inference
@@ -47,6 +55,57 @@ function collectMultilineAnnotation(lines, startIndex) {
     }
     return { text, endIndex: lines.length - 1 };
 }
+/**
+ * Skip past annotations (including multi-line ones) starting at `startIndex`.
+ * Returns the index of the first non-annotation line.
+ * Lines with inline annotation + declaration (e.g. `@Nullable private int x;`)
+ * are treated as declaration lines (not skipped).
+ */
+function skipAnnotations(lines, startIndex) {
+    let idx = startIndex;
+    while (idx < lines.length && /^\s*@/.test(lines[idx])) {
+        if (lines[idx].includes("(")) {
+            // Check if parentheses are unbalanced (multi-line annotation) — always skip
+            let depth = 0;
+            for (const ch of lines[idx]) {
+                if (ch === "(")
+                    depth++;
+                if (ch === ")")
+                    depth--;
+            }
+            if (depth > 0) {
+                // Multi-line annotation — skip to its end
+                const { endIndex } = collectMultilineAnnotation(lines, idx);
+                idx = endIndex + 1;
+                continue;
+            }
+            // Single-line annotation with parens: check if declaration text remains
+            const stripped = stripInlineAnnotations(lines[idx]);
+            if (stripped === "") {
+                idx++;
+            }
+            else {
+                break; // declaration with inline annotation
+            }
+        }
+        else {
+            // Simple annotation like `@Final` — check for trailing declaration
+            const stripped = lines[idx].replace(/^\s*@[\w$.]+\s*/, "").trim();
+            if (stripped === "") {
+                idx++;
+            }
+            else {
+                break; // e.g. `@Deprecated public abstract void foo();`
+            }
+        }
+    }
+    return idx;
+}
+/** Strip inline annotations (e.g. `@Final @Nullable`) from a declaration line. */
+const INLINE_ANNOTATION_RE = /\s*@[\w$.]+(?:\([^)]*\))?\s*/g;
+function stripInlineAnnotations(line) {
+    return line.replace(INLINE_ANNOTATION_RE, " ").trim();
+}
 function inferAccessorTarget(methodName) {
     const getterMatch = GETTER_PREFIX_RE.exec(methodName);
     if (getterMatch) {
@@ -72,8 +131,21 @@ export function parseMixinSource(source) {
     const injections = [];
     const shadows = [];
     const accessors = [];
+    const imports = new Map();
     let className = "";
     let priority;
+    // --- Pass 0: extract imports ---
+    for (const line of lines) {
+        const importMatch = IMPORT_RE.exec(line);
+        if (importMatch) {
+            const fqcn = importMatch[1];
+            // Skip wildcard imports (e.g. import java.util.*)
+            if (!fqcn.endsWith("*")) {
+                const simpleName = fqcn.substring(fqcn.lastIndexOf(".") + 1);
+                imports.set(simpleName, fqcn);
+            }
+        }
+    }
     // --- Pass 1: find @Mixin annotation and class name ---
     let i = 0;
     while (i < lines.length) {
@@ -84,6 +156,24 @@ export function parseMixinSource(source) {
             while ((match = MIXIN_TARGET_RE.exec(mixinText)) !== null) {
                 targets.push({ className: match[1] });
             }
+            // Fallback: parse targets = "..." or targets = {"a", "b"} string form
+            if (targets.length === 0) {
+                const targetsStringMatch = MIXIN_TARGETS_STRING_RE.exec(mixinText);
+                if (targetsStringMatch) {
+                    const arrayContent = targetsStringMatch[1]; // {..."..."...} content
+                    const singleTarget = targetsStringMatch[2]; // single "..." content
+                    if (arrayContent) {
+                        MIXIN_TARGETS_STRING_ITEM_RE.lastIndex = 0;
+                        let itemMatch;
+                        while ((itemMatch = MIXIN_TARGETS_STRING_ITEM_RE.exec(arrayContent)) !== null) {
+                            targets.push({ className: itemMatch[1] });
+                        }
+                    }
+                    else if (singleTarget) {
+                        targets.push({ className: singleTarget });
+                    }
+                }
+            }
             const priorityMatch = MIXIN_PRIORITY_RE.exec(mixinText);
             if (priorityMatch) {
                 priority = parseInt(priorityMatch[1], 10);
@@ -115,21 +205,50 @@ export function parseMixinSource(source) {
                 injections.push({ annotation, method: methodMatch[1], line: lineNum });
             }
             else {
-                parseWarnings.push(`Line ${lineNum}: @${annotation} missing method attribute.`);
+                // Try array form: method = {"m1", "m2"}
+                const arrayMatch = METHOD_ATTR_ARRAY_RE.exec(fullAnnotation);
+                if (arrayMatch) {
+                    const inner = arrayMatch[1];
+                    METHOD_ATTR_ITEM_RE.lastIndex = 0;
+                    let itemMatch;
+                    let found = false;
+                    while ((itemMatch = METHOD_ATTR_ITEM_RE.exec(inner)) !== null) {
+                        injections.push({ annotation, method: itemMatch[1], line: lineNum });
+                        found = true;
+                    }
+                    if (!found) {
+                        parseWarnings.push(`Line ${lineNum}: @${annotation} method array is empty.`);
+                    }
+                }
+                else {
+                    parseWarnings.push(`Line ${lineNum}: @${annotation} missing method attribute.`);
+                }
             }
             i = endIndex + 1;
             continue;
         }
         // --- @Shadow ---
         if (SHADOW_ANNOTATION_RE.test(line)) {
+            // Try same-line declaration first (e.g. `@Shadow @Final private int x;`)
+            const inlineDecl = stripInlineAnnotations(line);
+            const inlineMethodMatch = inlineDecl.includes("(") ? METHOD_DECL_RE.exec(inlineDecl) : null;
+            const inlineFieldMatch = !inlineMethodMatch ? FIELD_DECL_RE.exec(inlineDecl) : null;
+            if (inlineMethodMatch) {
+                shadows.push({ kind: "method", name: inlineMethodMatch[2], line: lineNum });
+                i++;
+                continue;
+            }
+            else if (inlineFieldMatch) {
+                shadows.push({ kind: "field", name: inlineFieldMatch[2], line: lineNum });
+                i++;
+                continue;
+            }
             // 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++;
-            }
+            // Skip additional annotations between @Shadow and declaration (including multi-line)
+            declLine = skipAnnotations(lines, declLine);
             if (declLine < lines.length) {
-                const declText = lines[declLine];
+                const declText = stripInlineAnnotations(lines[declLine]);
                 const methodDeclMatch = METHOD_DECL_RE.exec(declText);
                 const fieldDeclMatch = FIELD_DECL_RE.exec(declText);
                 // Method if it has parentheses
@@ -160,13 +279,11 @@ export function parseMixinSource(source) {
                 }
                 i = endIndex;
             }
-            // Find the method declaration following the annotation
+            // Find the method declaration following the annotation (skip multi-line annotations)
             let methodLine = i + 1;
-            while (methodLine < lines.length && /^\s*@/.test(lines[methodLine])) {
-                methodLine++;
-            }
+            methodLine = skipAnnotations(lines, methodLine);
             if (methodLine < lines.length) {
-                const methodDeclMatch = METHOD_DECL_RE.exec(lines[methodLine]);
+                const methodDeclMatch = METHOD_DECL_RE.exec(stripInlineAnnotations(lines[methodLine]));
                 if (methodDeclMatch) {
                     const methodName = methodDeclMatch[2];
                     const targetName = explicitTarget ?? inferAccessorTarget(methodName);
@@ -185,6 +302,7 @@ export function parseMixinSource(source) {
         className,
         targets,
         priority,
+        imports,
         injections,
         shadows,
         accessors,

package/dist/mixin-validator.d.ts

@@ -5,14 +5,37 @@
 import type { SignatureMember } from "./minecraft-explorer-service.js";
 import type { ParsedMixin } from "./mixin-parser.js";
 import type { ParsedAccessWidener, AccessWidenerEntry } from "./access-widener-parser.js";
+import type { SourceMapping } from "./types.js";
+export type MappingHealthReport = {
+    jarAvailable: boolean;
+    jarPath: string;
+    mojangMappingsAvailable: boolean;
+    tinyMappingsAvailable: boolean;
+    memberRemapAvailable: boolean;
+    overallHealthy: boolean;
+    degradations: string[];
+};
+export type IssueConfidence = "definite" | "likely" | "uncertain";
+export type ResolutionPath = "member-remap-failed" | "target-mapping-failed" | "target-class-missing" | "source-signature-unavailable";
 export type ValidationIssue = {
     severity: "error" | "warning";
-    kind: "target-not-found" | "method-not-found" | "field-not-found" | "descriptor-mismatch" | "access-mismatch" | "unknown-annotation";
+    kind: "target-not-found" | "target-mapping-failed" | "method-not-found" | "field-not-found" | "descriptor-mismatch" | "access-mismatch" | "unknown-annotation";
     annotation: string;
     target: string;
     message: string;
     suggestions?: string[];
     line?: number;
+    confidence?: IssueConfidence;
+    confidenceReason?: string;
+    category?: IssueCategory;
+    resolutionPath?: ResolutionPath;
+    explanation?: string;
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
+    falsePositiveRisk?: "high" | "medium" | "low";
+    issueOrigin?: "code_issue" | "tool_issue" | "parser_limitation";
 };
 export type ValidationSummary = {
     injections: number;
@@ -21,6 +44,52 @@ export type ValidationSummary = {
     total: number;
     errors: number;
     warnings: number;
+    definiteErrors: number;
+    uncertainErrors: number;
+    resolutionErrors: number;
+    parseWarnings: number;
+};
+export type MixinValidationProvenance = {
+    version: string;
+    jarPath: string;
+    requestedMapping: SourceMapping;
+    mappingApplied: SourceMapping;
+    resolutionNotes?: string[];
+    jarType?: "vanilla-client" | "merged" | "unknown";
+    mappingChain?: string[];
+    remapFailures?: number;
+    mappingAutoDetected?: boolean;
+    scopeFallback?: {
+        requested: string;
+        applied: string;
+        reason: string;
+    };
+    resolutionTrace?: Array<{
+        target: string;
+        step: "mapping" | "signature" | "remap" | "fallback-check";
+        input: string;
+        output: string;
+        success: boolean;
+        detail?: string;
+    }>;
+};
+export type IssueCategory = "mapping" | "configuration" | "validation" | "resolution" | "parse";
+export type StructuredWarning = {
+    severity: "info" | "warning";
+    message: string;
+    category?: IssueCategory;
+};
+export type ResolvedMember = {
+    annotation: string;
+    name: string;
+    line?: number;
+    resolvedTo?: string;
+    status: "resolved" | "not-found" | "skipped";
+};
+export type AggregatedWarningGroup = {
+    category: IssueCategory;
+    count: number;
+    samples: string[];
 };
 export type MixinValidationResult = {
     className: string;
@@ -29,7 +98,15 @@ export type MixinValidationResult = {
     valid: boolean;
     issues: ValidationIssue[];
     summary: ValidationSummary;
+    unfilteredSummary?: ValidationSummary;
+    provenance?: MixinValidationProvenance;
     warnings: string[];
+    structuredWarnings?: StructuredWarning[];
+    aggregatedWarnings?: AggregatedWarningGroup[];
+    resolvedMembers?: ResolvedMember[];
+    toolHealth?: MappingHealthReport;
+    confidenceScore?: number;
+    quickSummary?: string;
 };
 export type ResolvedTargetMembers = {
     className: string;
@@ -55,5 +132,19 @@ export type AccessWidenerValidationResult = {
 };
 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 extractMethodName(ref: string): string;
+/**
+ * Extract the JVM descriptor portion from a method reference, if present.
+ *
+ * Examples:
+ *   "playerTouch(Lnet/minecraft/world/entity/player/Player;)V" → "(Lnet/minecraft/world/entity/player/Player;)V"
+ *   "tick"                                                      → undefined
+ */
+export declare function extractMethodDescriptor(ref: string): string | undefined;
+export declare function validateParsedMixin(parsed: ParsedMixin, targetMembers: Map<string, ResolvedTargetMembers>, warnings: string[], provenance?: MixinValidationProvenance, confidence?: IssueConfidence, mappingFailedTargets?: Set<string>, explain?: boolean, remapFailedMembers?: Map<string, Set<string>>, signatureFailedTargets?: Set<string>, suggestedCallContext?: {
+    scope?: string;
+    sourcePriority?: string;
+    projectPath?: string;
+    mapping?: string;
+}, warningMode?: "full" | "aggregated", healthReport?: MappingHealthReport, symbolExistsButSignatureFailed?: Set<string>): MixinValidationResult;
 export declare function validateParsedAccessWidener(parsed: ParsedAccessWidener, membersByClass: Map<string, ResolvedTargetMembers>, warnings: string[]): AccessWidenerValidationResult;