@adhisang/minecraft-modding-mcp 2.0.0 → 2.1.0

package/dist/mixin-validator.js

@@ -2,6 +2,27 @@
  * Validation engine for parsed Mixin sources and Access Widener files.
  * Compares parsed annotations against resolved Minecraft bytecode signatures.
  */
+const TOOL_RESOLUTION_PATHS = [
+    "target-mapping-failed",
+    "member-remap-failed",
+    "source-signature-unavailable"
+];
+const MAPPING_WARNING_RE = /(?:mapping|remap|fallback|could not map)/i;
+const CONFIG_WARNING_RE = /(?:version|gradle|jar\b|properties|project)/i;
+const PARSE_WARNING_RE = /(?:could not parse|parse\s+warning|missing method attribute)/i;
+function classifyStructuredWarning(message) {
+    return {
+        severity: MAPPING_WARNING_RE.test(message) ? "warning" : PARSE_WARNING_RE.test(message) ? "warning" : "info",
+        message,
+        category: MAPPING_WARNING_RE.test(message)
+            ? "mapping"
+            : PARSE_WARNING_RE.test(message)
+                ? "parse"
+                : CONFIG_WARNING_RE.test(message)
+                    ? "configuration"
+                    : "validation"
+    };
+}
 /* ------------------------------------------------------------------ */
 /*  Levenshtein distance                                               */
 /* ------------------------------------------------------------------ */
@@ -33,9 +54,14 @@ export function levenshteinDistance(a, b) {
     return prev[lb];
 }
 export function suggestSimilar(name, candidates, maxDistance = 3, maxResults = 3) {
+    const normalizedName = name.toLowerCase();
     const scored = [];
     for (const candidate of candidates) {
-        const distance = levenshteinDistance(name.toLowerCase(), candidate.toLowerCase());
+        const normalizedCandidate = candidate.toLowerCase();
+        if (Math.abs(normalizedName.length - normalizedCandidate.length) > maxDistance) {
+            continue;
+        }
+        const distance = levenshteinDistance(normalizedName, normalizedCandidate);
         if (distance <= maxDistance && distance > 0) {
             scored.push({ candidate, distance });
         }
@@ -127,22 +153,111 @@ function computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
     }
     return undefined;
 }
-function computeConfidenceScore(healthReport, provenance, remapFailureCount) {
-    let score = 100;
+function computeConfidenceBreakdown(healthReport, provenance, remapFailureCount, skippedMemberCount) {
+    const baseScore = 100;
+    const penalties = [];
+    let score = baseScore;
     if (healthReport) {
-        if (!healthReport.overallHealthy)
+        if (!healthReport.overallHealthy) {
+            penalties.push({ reason: "mapping-health", points: 30 });
             score -= 30;
-        if (!healthReport.tinyMappingsAvailable)
+        }
+        if (!healthReport.tinyMappingsAvailable) {
+            penalties.push({ reason: "tiny-mappings-unavailable", points: 20 });
             score -= 20;
-        if (!healthReport.memberRemapAvailable)
+        }
+        if (!healthReport.memberRemapAvailable) {
+            penalties.push({ reason: "member-remap-unavailable", points: 15 });
             score -= 15;
+        }
     }
-    if (provenance?.scopeFallback)
+    if (provenance?.scopeFallback) {
+        penalties.push({ reason: "scope-fallback", points: 10 });
         score -= 10;
-    if (provenance && provenance.requestedMapping !== provenance.mappingApplied)
+    }
+    if (provenance && provenance.requestedMapping !== provenance.mappingApplied) {
+        penalties.push({ reason: "mapping-mismatch", points: 15 });
         score -= 15;
-    score -= Math.min(remapFailureCount * 2, 20);
-    return Math.max(score, 0);
+    }
+    if (skippedMemberCount > 0) {
+        penalties.push({ reason: "members-skipped", points: 25 });
+        score -= 25;
+    }
+    const remapPenalty = Math.min(remapFailureCount * 2, 20);
+    if (remapPenalty > 0) {
+        penalties.push({ reason: "remap-failures", points: remapPenalty });
+        score -= remapPenalty;
+    }
+    return {
+        baseScore,
+        score: Math.max(score, 0),
+        penalties
+    };
+}
+function summarizeResolvedMembers(resolvedMembers) {
+    return {
+        membersValidated: resolvedMembers.filter((member) => member.status === "resolved").length,
+        membersSkipped: resolvedMembers.filter((member) => member.status === "skipped").length,
+        membersMissing: resolvedMembers.filter((member) => member.status === "not-found").length
+    };
+}
+function computeValidationStatus(summary) {
+    if (summary.errors > 0 || summary.definiteErrors > 0) {
+        return "invalid";
+    }
+    if (summary.warnings > 0 || summary.membersSkipped > 0) {
+        return "partial";
+    }
+    return "full";
+}
+function buildQuickSummary(status, summary) {
+    if (status === "full") {
+        return `${summary.membersValidated} member(s) validated successfully.`;
+    }
+    return `${summary.definiteErrors} error(s), ${summary.uncertainErrors} uncertain, ${summary.warnings} warning(s). ${summary.membersValidated} validated, ${summary.membersSkipped} member(s) skipped, ${summary.membersMissing} member(s) missing.`;
+}
+function addSkippedMembers(parsed, resolvedMembers) {
+    for (const inj of parsed.injections) {
+        resolvedMembers.push({
+            annotation: `@${inj.annotation}`,
+            name: extractMethodName(inj.method),
+            line: inj.line,
+            status: "skipped"
+        });
+    }
+    for (const shadow of parsed.shadows) {
+        resolvedMembers.push({
+            annotation: "@Shadow",
+            name: shadow.name,
+            line: shadow.line,
+            status: "skipped"
+        });
+    }
+    for (const accessor of parsed.accessors) {
+        resolvedMembers.push({
+            annotation: `@${accessor.annotation}`,
+            name: accessor.targetName,
+            line: accessor.line,
+            status: "skipped"
+        });
+    }
+}
+export function refreshMixinValidationOutcome(result) {
+    const memberSummary = result.resolvedMembers
+        ? summarizeResolvedMembers(result.resolvedMembers)
+        : {
+            membersValidated: result.summary.membersValidated,
+            membersSkipped: result.summary.membersSkipped,
+            membersMissing: result.summary.membersMissing
+        };
+    result.summary = {
+        ...result.summary,
+        ...memberSummary
+    };
+    result.validationStatus = computeValidationStatus(result.summary);
+    result.valid = result.summary.definiteErrors === 0;
+    result.quickSummary = buildQuickSummary(result.validationStatus, result.summary);
+    return result;
 }
 function validateInjection(inj, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
     for (const targetName of targetNames) {
@@ -335,7 +450,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                 // Symbol exists in mapping graph but getSignature failed — tool limitation, not code issue
                 issues.push({
                     severity: "warning",
-                    kind: "target-not-found",
+                    kind: "validation-incomplete",
                     annotation: "@Mixin",
                     target: target.className,
                     message: `Target class "${target.className}" exists in mapping data but could not be loaded from game jar (tool limitation). Members not validated.`,
@@ -346,49 +461,23 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     issueOrigin: "tool_issue",
                     falsePositiveRisk: "high"
                 });
-                // Skip member validation for this target — add skipped entries for each declared member
-                for (const inj of parsed.injections) {
-                    const methodName = extractMethodName(inj.method);
-                    resolvedMembers.push({
-                        annotation: `@${inj.annotation}`,
-                        name: methodName,
-                        line: inj.line,
-                        status: "skipped"
-                    });
-                }
-                for (const shadow of parsed.shadows) {
-                    resolvedMembers.push({
-                        annotation: "@Shadow",
-                        name: shadow.name,
-                        line: shadow.line,
-                        status: "skipped"
-                    });
-                }
-                for (const accessor of parsed.accessors) {
-                    resolvedMembers.push({
-                        annotation: `@${accessor.annotation}`,
-                        name: accessor.targetName,
-                        line: accessor.line,
-                        status: "skipped"
-                    });
-                }
+                addSkippedMembers(parsed, resolvedMembers);
             }
             else if (signatureFailedTargets?.has(target.className)) {
-                const degraded = healthReport?.overallHealthy === false;
                 issues.push({
-                    severity: degraded ? "warning" : "error",
-                    kind: "target-not-found",
+                    severity: "warning",
+                    kind: "validation-incomplete",
                     annotation: "@Mixin",
                     target: target.className,
-                    message: `Target class "${target.className}" not found in game jar.${degraded ? " (infrastructure degraded; may be false positive)" : ""}`,
-                    confidence: degraded ? "uncertain" : confidence,
-                    confidenceReason: degraded
-                        ? "Mapping infrastructure is degraded; result may be inaccurate."
-                        : confidenceReason,
+                    message: `Target class "${target.className}" could not load enough target metadata for reliable validation. Members were not validated.`,
+                    confidence: "uncertain",
+                    confidenceReason: "Target bytecode could not be loaded and fallback existence checks were unavailable.",
                     category: "resolution",
                     resolutionPath: "source-signature-unavailable",
-                    falsePositiveRisk: degraded ? "high" : undefined
+                    issueOrigin: "tool_issue",
+                    falsePositiveRisk: "high"
                 });
+                addSkippedMembers(parsed, resolvedMembers);
             }
             else {
                 issues.push({
@@ -439,20 +528,22 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
         }
     }
     // Contradiction detection: if some same-annotation members resolved OK but parse failed for others, note it
-    const resolvedAnnotations = new Set(resolvedMembers.filter((m) => m.status === "resolved").map((m) => m.annotation));
+    const resolvedAnnotations = new Set();
+    for (const member of resolvedMembers) {
+        if (member.status === "resolved") {
+            resolvedAnnotations.add(member.annotation);
+        }
+    }
+    let errorCount = 0;
+    let warningCount = 0;
+    let definiteErrors = 0;
+    let uncertainErrors = 0;
+    let resolutionErrors = 0;
+    let parseWarningCount = 0;
     for (const issue of issues) {
         if (issue.category === "parse" && resolvedAnnotations.has(issue.annotation)) {
             issue.message += " (Note: other members with the same annotation resolved successfully.)";
         }
-    }
-    const errorCount = issues.filter((i) => i.severity === "error").length;
-    const warningCount = issues.filter((i) => i.severity === "warning").length;
-    const definiteErrors = issues.filter((i) => i.severity === "error" && i.confidence !== "uncertain").length;
-    const uncertainErrors = issues.filter((i) => i.severity === "error" && i.confidence === "uncertain").length;
-    const resolutionErrors = issues.filter((i) => i.resolutionPath != null).length;
-    const parseWarningCount = issues.filter((i) => i.category === "parse").length;
-    // Assign category and issueOrigin to issues that don't have them yet
-    for (const issue of issues) {
         if (!issue.category) {
             issue.category = issue.resolutionPath ? "resolution" : "validation";
         }
@@ -461,27 +552,47 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                 issue.issueOrigin = "parser_limitation";
             }
             else {
-                const toolPaths = ["target-mapping-failed", "member-remap-failed", "source-signature-unavailable"];
-                issue.issueOrigin = issue.resolutionPath && toolPaths.includes(issue.resolutionPath)
+                issue.issueOrigin = issue.resolutionPath && TOOL_RESOLUTION_PATHS.includes(issue.resolutionPath)
                     ? "tool_issue"
                     : "code_issue";
             }
         }
+        if (issue.severity === "error") {
+            errorCount++;
+            if (issue.confidence === "uncertain") {
+                uncertainErrors++;
+            }
+            else {
+                definiteErrors++;
+            }
+        }
+        else {
+            warningCount++;
+        }
+        if (issue.resolutionPath != null) {
+            resolutionErrors++;
+        }
+        if (issue.category === "parse") {
+            parseWarningCount++;
+        }
     }
     // Enrich issues with explanations and suggested calls when explain=true
     if (explain) {
         const version = provenance?.version;
         const mapping = provenance?.requestedMapping;
-        // Build context fields to spread into suggestedCall params
-        const ctx = {};
+        const symbolLookupContext = {};
+        if (suggestedCallContext?.sourcePriority) {
+            symbolLookupContext.sourcePriority = suggestedCallContext.sourcePriority;
+        }
+        const classSourceContext = {};
         if (suggestedCallContext?.scope)
-            ctx.scope = suggestedCallContext.scope;
+            classSourceContext.scope = suggestedCallContext.scope;
         if (suggestedCallContext?.sourcePriority)
-            ctx.sourcePriority = suggestedCallContext.sourcePriority;
+            classSourceContext.sourcePriority = suggestedCallContext.sourcePriority;
         if (suggestedCallContext?.projectPath)
-            ctx.projectPath = suggestedCallContext.projectPath;
+            classSourceContext.projectPath = suggestedCallContext.projectPath;
         if (suggestedCallContext?.mapping)
-            ctx.mapping = suggestedCallContext.mapping;
+            classSourceContext.mapping = suggestedCallContext.mapping;
         for (const issue of issues) {
             switch (issue.kind) {
                 case "target-not-found":
@@ -489,7 +600,22 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version && mapping) {
                         issue.suggestedCall = {
                             tool: "check-symbol-exists",
-                            params: { kind: "class", name: issue.target, version, sourceMapping: mapping, nameMode: "auto", ...ctx }
+                            params: { kind: "class", name: issue.target, version, sourceMapping: mapping, nameMode: "auto", ...symbolLookupContext }
+                        };
+                    }
+                    break;
+                case "validation-incomplete":
+                    issue.explanation = `Target metadata for "${issue.target}" could not be loaded reliably, so validation was only partial. This usually indicates a tool or environment limitation rather than a confirmed code error.`;
+                    if (version) {
+                        issue.suggestedCall = {
+                            tool: "get-class-source",
+                            params: {
+                                className: issue.target,
+                                target: { type: "resolve", kind: "version", value: version },
+                                ...(mapping ? { mapping } : {}),
+                                mode: "metadata",
+                                ...classSourceContext
+                            }
                         };
                     }
                     break;
@@ -498,7 +624,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version && mapping) {
                         issue.suggestedCall = {
                             tool: "check-symbol-exists",
-                            params: { kind: "class", name: issue.target, version, sourceMapping: mapping, nameMode: "auto", ...ctx }
+                            params: { kind: "class", name: issue.target, version, sourceMapping: mapping, nameMode: "auto", ...symbolLookupContext }
                         };
                     }
                     break;
@@ -509,7 +635,13 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version) {
                         issue.suggestedCall = {
                             tool: "get-class-source",
-                            params: { className, targetKind: "version", targetValue: version, ...(mapping ? { mapping } : {}), mode: "metadata", ...ctx }
+                            params: {
+                                className,
+                                target: { type: "resolve", kind: "version", value: version },
+                                ...(mapping ? { mapping } : {}),
+                                mode: "metadata",
+                                ...classSourceContext
+                            }
                         };
                     }
                     break;
@@ -522,7 +654,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version && mapping) {
                         issue.suggestedCall = {
                             tool: "check-symbol-exists",
-                            params: { kind: "field", owner: ownerName, name: fieldName, version, sourceMapping: mapping, ...ctx }
+                            params: { kind: "field", owner: ownerName, name: fieldName, version, sourceMapping: mapping, ...symbolLookupContext }
                         };
                     }
                     break;
@@ -530,18 +662,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
             }
         }
     }
-    // Build structuredWarnings — classify by severity and category
-    const MAPPING_WARNING_RE = /(?:mapping|remap|fallback|could not map)/i;
-    const CONFIG_WARNING_RE = /(?:version|gradle|jar\b|properties|project)/i;
-    const PARSE_WARNING_RE = /(?:could not parse|parse\s+warning|missing method attribute)/i;
-    const structuredWarnings = warnings.map((msg) => ({
-        severity: MAPPING_WARNING_RE.test(msg) ? "warning" : PARSE_WARNING_RE.test(msg) ? "warning" : "info",
-        message: msg,
-        category: MAPPING_WARNING_RE.test(msg) ? "mapping"
-            : PARSE_WARNING_RE.test(msg) ? "parse"
-                : CONFIG_WARNING_RE.test(msg) ? "configuration"
-                    : "validation"
-    }));
+    const structuredWarnings = warnings.map(classifyStructuredWarning);
     // Warning aggregation mode
     let aggregatedWarnings;
     let outputWarnings = warnings;
@@ -571,32 +692,35 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
     }
     // Compute confidence score
     const remapFailureCount = provenance?.remapFailures ?? 0;
-    const confidenceScore = healthReport
-        ? computeConfidenceScore(healthReport, provenance, remapFailureCount)
+    const memberSummary = summarizeResolvedMembers(resolvedMembers);
+    const confidenceBreakdown = healthReport
+        ? computeConfidenceBreakdown(healthReport, provenance, remapFailureCount, memberSummary.membersSkipped)
         : undefined;
-    // Build quick summary
+    const confidenceScore = confidenceBreakdown?.score;
     const total = parsed.injections.length + parsed.shadows.length + parsed.accessors.length;
-    const quickSummary = issues.length === 0
-        ? `${total} member(s) validated successfully.`
-        : `${definiteErrors} error(s), ${uncertainErrors} uncertain, ${warningCount} warning(s).`;
+    const summary = {
+        injections: parsed.injections.length,
+        shadows: parsed.shadows.length,
+        accessors: parsed.accessors.length,
+        total,
+        ...memberSummary,
+        errors: errorCount,
+        warnings: warningCount,
+        definiteErrors,
+        uncertainErrors,
+        resolutionErrors,
+        parseWarnings: parseWarningCount
+    };
+    const validationStatus = computeValidationStatus(summary);
+    const quickSummary = buildQuickSummary(validationStatus, summary);
     return {
         className: parsed.className,
         targets: targetNames,
         priority: parsed.priority,
         valid: definiteErrors === 0,
+        validationStatus,
         issues,
-        summary: {
-            injections: parsed.injections.length,
-            shadows: parsed.shadows.length,
-            accessors: parsed.accessors.length,
-            total,
-            errors: errorCount,
-            warnings: warningCount,
-            definiteErrors,
-            uncertainErrors,
-            resolutionErrors,
-            parseWarnings: parseWarningCount
-        },
+        summary,
         provenance,
         warnings: outputWarnings,
         structuredWarnings: outputStructuredWarnings,
@@ -604,6 +728,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
         resolvedMembers: resolvedMembers.length > 0 ? resolvedMembers : undefined,
         toolHealth: healthReport,
         confidenceScore,
+        confidenceBreakdown,
         quickSummary
     };
 }

package/dist/mod-decompile-service.d.ts

@@ -2,6 +2,8 @@ import type { Config } from "./types.js";
 export type DecompileModJarInput = {
     jarPath: string;
     className?: string;
+    includeFiles?: boolean;
+    maxFiles?: number;
 };
 export type DecompileModJarOutput = {
     modId: string;
@@ -11,6 +13,9 @@ export type DecompileModJarOutput = {
     outputDir: string;
     fileCount: number;
     files?: string[];
+    returnedFileCount?: number;
+    filesTruncated?: boolean;
+    filesOmitted?: boolean;
     source?: {
         className: string;
         content: string;

package/dist/mod-decompile-service.js

@@ -17,6 +17,12 @@ function classNameToFilePath(className) {
 function filePathToClassName(filePath) {
     return filePath.replace(/\.java$/, "").replaceAll("/", ".");
 }
+function clampPositiveInt(value) {
+    if (!Number.isFinite(value) || value == null) {
+        return undefined;
+    }
+    return Math.max(1, Math.trunc(value));
+}
 export class ModDecompileService {
     config;
     // Cache: jarPath hash → decompiled output dir + file list
@@ -28,6 +34,8 @@ export class ModDecompileService {
         const jarPath = validateAndNormalizeJarPath(input.jarPath);
         const warnings = [];
         const { outputDir, files, analysis } = await this.ensureDecompiled(jarPath, warnings);
+        const includeFiles = input.includeFiles ?? true;
+        const maxFiles = clampPositiveInt(input.maxFiles);
         let sourceResult;
         if (input.className) {
             const targetFile = classNameToFilePath(input.className);
@@ -44,6 +52,25 @@ export class ModDecompileService {
                 warnings.push(`Class "${input.className}" not found in decompiled output. Use the files list to find available classes.`);
             }
         }
+        let returnedFiles;
+        let returnedFileCount;
+        let filesTruncated;
+        let filesOmitted;
+        if (!input.className) {
+            const classNames = files.map(filePathToClassName);
+            if (!includeFiles) {
+                returnedFileCount = 0;
+                filesOmitted = true;
+            }
+            else {
+                const limitedFiles = maxFiles != null && classNames.length > maxFiles
+                    ? classNames.slice(0, maxFiles)
+                    : classNames;
+                returnedFiles = limitedFiles;
+                returnedFileCount = limitedFiles.length;
+                filesTruncated = limitedFiles.length < classNames.length || undefined;
+            }
+        }
         return {
             modId: analysis.modId ?? "unknown",
             modName: analysis.modName,
@@ -51,7 +78,10 @@ export class ModDecompileService {
             loader: analysis.loader,
             outputDir,
             fileCount: files.length,
-            files: input.className ? undefined : files.map(filePathToClassName),
+            files: returnedFiles,
+            returnedFileCount,
+            filesTruncated,
+            filesOmitted,
             source: sourceResult,
             warnings
         };
@@ -119,8 +149,11 @@ export class ModDecompileService {
     async ensureDecompiled(jarPath, warnings) {
         const cacheKey = modDecompileCacheKey(jarPath);
         const cached = this.decompileCache.get(cacheKey);
-        if (cached)
+        if (cached) {
+            this.decompileCache.delete(cacheKey);
+            this.decompileCache.set(cacheKey, cached);
             return cached;
+        }
         log("info", "mod-decompile.start", { jarPath });
         const startedAt = Date.now();
         // Analyze mod metadata
@@ -152,10 +185,12 @@ export class ModDecompileService {
         };
         this.decompileCache.set(cacheKey, result);
         // Trim cache
-        if (this.decompileCache.size > 8) {
+        while (this.decompileCache.size > 8) {
             const oldest = this.decompileCache.keys().next().value;
-            if (oldest !== undefined)
-                this.decompileCache.delete(oldest);
+            if (oldest === undefined) {
+                break;
+            }
+            this.decompileCache.delete(oldest);
         }
         log("info", "mod-decompile.done", {
             jarPath,