@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.1

package/dist/mixin/access-validators.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedAccessTransformer } from "../access-transformer-parser.js";
+import type { ParsedAccessWidener } from "../access-widener-parser.js";
+import type { AccessTransformerValidationResult, AccessWidenerValidationResult, ResolvedTargetMembers } from "./types.js";
+export declare function validateParsedAccessWidener(parsed: ParsedAccessWidener, membersByClass: Map<string, ResolvedTargetMembers>, warnings: string[], options?: {
+    includeRuntimeEvidence?: boolean;
+}): AccessWidenerValidationResult;
+export declare function validateParsedAccessTransformer(parsed: ParsedAccessTransformer, membersByClass: Map<string, ResolvedTargetMembers>, warnings: string[], options?: {
+    includeRuntimeEvidence?: boolean;
+}): AccessTransformerValidationResult;

package/dist/mixin/access-validators.js

@@ -0,0 +1,257 @@
+import { accessLevelFromFlags, allFieldNames, allMethodNames, suggestSimilar } from "./helpers.js";
+export function validateParsedAccessWidener(parsed, membersByClass, warnings, options) {
+    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") {
+            const members = membersByClass.get(ownerFqn);
+            if (members) {
+                const runtimeAccess = accessLevelFromFlags(members.classAccessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {})
+                        }
+                        : {})
+                });
+                validCount++;
+            }
+            else {
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Class "${ownerFqn}" not found in game jar.`,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                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.`,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+            });
+            invalidCount++;
+            continue;
+        }
+        if (entry.targetKind === "method") {
+            const methodNames = allMethodNames(members);
+            const matchedMember = members.methods.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor)) ?? members.constructors.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const found = matchedMember != null;
+            if (found) {
+                const runtimeMember = matchedMember;
+                const runtimeAccess = accessLevelFromFlags(runtimeMember.accessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {}),
+                            ...(runtimeMember.jvmDescriptor
+                                ? { resolvedRuntimeJvmDescriptor: runtimeMember.jvmDescriptor }
+                                : {}),
+                            ...(runtimeMember.javaSignature
+                                ? { resolvedRuntimeJavaSignature: runtimeMember.javaSignature }
+                                : {})
+                        }
+                        : {})
+                });
+                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,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+            }
+        }
+        else {
+            // field
+            const fieldNames = allFieldNames(members);
+            const matchedMember = members.fields.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const found = matchedMember != null;
+            if (found) {
+                const runtimeMember = matchedMember;
+                const runtimeAccess = accessLevelFromFlags(runtimeMember.accessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {}),
+                            ...(runtimeMember.jvmDescriptor
+                                ? { resolvedRuntimeJvmDescriptor: runtimeMember.jvmDescriptor }
+                                : {}),
+                            ...(runtimeMember.javaSignature
+                                ? { resolvedRuntimeJavaSignature: runtimeMember.javaSignature }
+                                : {})
+                        }
+                        : {})
+                });
+                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,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+            }
+        }
+    }
+    return {
+        headerVersion: parsed.headerVersion,
+        namespace: parsed.namespace,
+        valid: invalidCount === 0,
+        entries: validatedEntries,
+        summary: {
+            total: parsed.entries.length,
+            valid: validCount,
+            invalid: invalidCount
+        },
+        warnings
+    };
+}
+export function validateParsedAccessTransformer(parsed, membersByClass, warnings, options) {
+    warnings.push(...parsed.parseWarnings);
+    const validatedEntries = [];
+    let validCount = 0;
+    let invalidCount = 0;
+    for (const entry of parsed.entries) {
+        const ownerFqn = entry.owner;
+        const members = membersByClass.get(ownerFqn);
+        if (entry.targetKind === "class") {
+            if (!members) {
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Class "${ownerFqn}" not found in runtime jar.`,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
+            const runtimeAccess = accessLevelFromFlags(members.classAccessFlags);
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence
+                    ? {
+                        resolvedInRuntime: true,
+                        ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {})
+                    }
+                    : {})
+            });
+            validCount++;
+            continue;
+        }
+        if (!members) {
+            validatedEntries.push({
+                ...entry,
+                valid: false,
+                issue: `Owner class "${ownerFqn}" not found in runtime jar.`,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+            });
+            invalidCount++;
+            continue;
+        }
+        if (entry.targetKind === "field") {
+            const fieldNames = allFieldNames(members);
+            const matchedField = members.fields.find((member) => member.name === entry.name);
+            if (!matchedField) {
+                const suggestions = entry.name ? suggestSimilar(entry.name, fieldNames) : [];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Field "${entry.name}" not found in class "${ownerFqn}".`,
+                    ...(suggestions.length > 0 ? { suggestions } : {}),
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
+            const runtimeAccess = accessLevelFromFlags(matchedField.accessFlags);
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence
+                    ? {
+                        resolvedInRuntime: true,
+                        ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {}),
+                        ...(matchedField.jvmDescriptor ? { resolvedRuntimeJvmDescriptor: matchedField.jvmDescriptor } : {}),
+                        ...(matchedField.javaSignature ? { resolvedRuntimeJavaSignature: matchedField.javaSignature } : {})
+                    }
+                    : {})
+            });
+            validCount++;
+            continue;
+        }
+        const methodNames = allMethodNames(members);
+        const matchedMethod = members.methods.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor) ?? members.constructors.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor);
+        if (!matchedMethod) {
+            const suggestions = entry.name ? suggestSimilar(entry.name, methodNames) : [];
+            validatedEntries.push({
+                ...entry,
+                valid: false,
+                issue: `Method "${entry.name}" not found in class "${ownerFqn}".`,
+                ...(suggestions.length > 0 ? { suggestions } : {}),
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+            });
+            invalidCount++;
+            continue;
+        }
+        const runtimeAccess = accessLevelFromFlags(matchedMethod.accessFlags);
+        validatedEntries.push({
+            ...entry,
+            valid: true,
+            ...(options?.includeRuntimeEvidence
+                ? {
+                    resolvedInRuntime: true,
+                    ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {}),
+                    ...(matchedMethod.jvmDescriptor ? { resolvedRuntimeJvmDescriptor: matchedMethod.jvmDescriptor } : {}),
+                    ...(matchedMethod.javaSignature ? { resolvedRuntimeJavaSignature: matchedMethod.javaSignature } : {})
+                }
+                : {})
+        });
+        validCount++;
+    }
+    return {
+        valid: invalidCount === 0,
+        entries: validatedEntries,
+        summary: {
+            total: parsed.entries.length,
+            valid: validCount,
+            invalid: invalidCount
+        },
+        warnings
+    };
+}
+//# sourceMappingURL=access-validators.js.map

package/dist/mixin/annotation-validators.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedAccessor, ParsedInjection, ParsedShadow } from "../mixin-parser.js";
+import type { IssueConfidence, MappingHealthReport, ResolvedMember, ResolvedTargetMembers, ValidationIssue } from "./types.js";
+export declare function validateInjection(inj: ParsedInjection, targetMembers: Map<string, ResolvedTargetMembers>, targetNames: string[], issues: ValidationIssue[], resolvedMembers: ResolvedMember[], confidence?: IssueConfidence, confidenceReason?: string, remapFailedMembers?: Map<string, Set<string>>, signatureFailedTargets?: Set<string>, healthReport?: MappingHealthReport): void;
+export declare function validateShadow(shadow: ParsedShadow, targetMembers: Map<string, ResolvedTargetMembers>, targetNames: string[], issues: ValidationIssue[], resolvedMembers: ResolvedMember[], confidence?: IssueConfidence, confidenceReason?: string, remapFailedMembers?: Map<string, Set<string>>, signatureFailedTargets?: Set<string>, healthReport?: MappingHealthReport): void;
+export declare function validateAccessor(accessor: ParsedAccessor, targetMembers: Map<string, ResolvedTargetMembers>, targetNames: string[], issues: ValidationIssue[], resolvedMembers: ResolvedMember[], confidence?: IssueConfidence, confidenceReason?: string, remapFailedMembers?: Map<string, Set<string>>, signatureFailedTargets?: Set<string>, healthReport?: MappingHealthReport): void;

package/dist/mixin/annotation-validators.js

@@ -0,0 +1,162 @@
+import { allFieldNames, allMethodNames, computeFalsePositiveRisk, extractMethodDescriptor, extractMethodName, suggestSimilar } from "./helpers.js";
+export function validateInjection(inj, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        const methodNames = allMethodNames(members);
+        // Strip owner prefix and JVM descriptor from the method reference
+        const methodName = extractMethodName(inj.method);
+        if (!methodNames.includes(methodName)) {
+            const suggestions = suggestSimilar(methodName, methodNames);
+            const descriptor = extractMethodDescriptor(inj.method);
+            const descriptorHint = descriptor ? ` (descriptor: ${descriptor})` : "";
+            // Determine if this is a remap artifact or signature unavailability
+            const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
+            const isSigFailed = signatureFailedTargets?.has(targetName);
+            const issueConfidence = isRemapFailed ? "uncertain" : confidence;
+            const issueConfidenceReason = isRemapFailed
+                ? `Member remap from obfuscated→mapping failed; name mismatch may be a remap artifact, not a true missing member.`
+                : confidenceReason;
+            const resolutionPath = isRemapFailed
+                ? "member-remap-failed"
+                : isSigFailed ? "source-signature-unavailable" : undefined;
+            const memberDegraded = isRemapFailed && healthReport?.memberRemapAvailable === false;
+            issues.push({
+                severity: memberDegraded ? "warning" : "error",
+                kind: "method-not-found",
+                annotation: `@${inj.annotation}`,
+                target: `${targetName}#${inj.method}`,
+                message: `Method "${methodName}" not found in target class "${targetName}".${descriptorHint}${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
+                suggestions: suggestions.length > 0 ? suggestions : undefined,
+                line: inj.line,
+                confidence: issueConfidence,
+                confidenceReason: issueConfidenceReason,
+                resolutionPath,
+                falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+            });
+            resolvedMembers.push({
+                annotation: `@${inj.annotation}`,
+                name: methodName,
+                line: inj.line,
+                status: "not-found"
+            });
+        }
+        else {
+            resolvedMembers.push({
+                annotation: `@${inj.annotation}`,
+                name: methodName,
+                line: inj.line,
+                resolvedTo: `${targetName}#${methodName}`,
+                status: "resolved"
+            });
+        }
+    }
+}
+export function validateShadow(shadow, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        const isRemapFailed = remapFailedMembers?.get(targetName)?.has(shadow.name);
+        const isSigFailed = signatureFailedTargets?.has(targetName);
+        const issueConfidence = isRemapFailed ? "uncertain" : confidence;
+        const issueConfidenceReason = isRemapFailed
+            ? `Member remap from obfuscated→mapping failed; name mismatch may be a remap artifact, not a true missing member.`
+            : confidenceReason;
+        const resolutionPath = isRemapFailed
+            ? "member-remap-failed"
+            : isSigFailed ? "source-signature-unavailable" : undefined;
+        const memberDegraded = isRemapFailed && healthReport?.memberRemapAvailable === false;
+        if (shadow.kind === "field") {
+            const fieldNames = allFieldNames(members);
+            if (!fieldNames.includes(shadow.name)) {
+                const suggestions = suggestSimilar(shadow.name, fieldNames);
+                issues.push({
+                    severity: memberDegraded ? "warning" : "error",
+                    kind: "field-not-found",
+                    annotation: "@Shadow",
+                    target: `${targetName}#${shadow.name}`,
+                    message: `Field "${shadow.name}" not found in target class "${targetName}" (${fieldNames.length} field(s) available).${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    line: shadow.line,
+                    confidence: issueConfidence,
+                    confidenceReason: issueConfidenceReason,
+                    resolutionPath,
+                    falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+                });
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, status: "not-found" });
+            }
+            else {
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, resolvedTo: `${targetName}#${shadow.name}`, status: "resolved" });
+            }
+        }
+        else {
+            const methodNames = allMethodNames(members);
+            if (!methodNames.includes(shadow.name)) {
+                const suggestions = suggestSimilar(shadow.name, methodNames);
+                issues.push({
+                    severity: memberDegraded ? "warning" : "error",
+                    kind: "method-not-found",
+                    annotation: "@Shadow",
+                    target: `${targetName}#${shadow.name}`,
+                    message: `Method "${shadow.name}" not found in target class "${targetName}" (${methodNames.length} method(s) available).${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    line: shadow.line,
+                    confidence: issueConfidence,
+                    confidenceReason: issueConfidenceReason,
+                    resolutionPath,
+                    falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+                });
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, status: "not-found" });
+            }
+            else {
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, resolvedTo: `${targetName}#${shadow.name}`, status: "resolved" });
+            }
+        }
+    }
+}
+export function validateAccessor(accessor, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
+    for (const targetName of targetNames) {
+        const members = targetMembers.get(targetName);
+        if (!members)
+            continue;
+        const candidateNames = accessor.annotation === "Invoker"
+            ? allMethodNames(members)
+            : allFieldNames(members);
+        if (!candidateNames.includes(accessor.targetName)) {
+            const isRemapFailed = remapFailedMembers?.get(targetName)?.has(accessor.targetName);
+            const isSigFailed = signatureFailedTargets?.has(targetName);
+            const issueConfidence = isRemapFailed ? "uncertain" : confidence;
+            const issueConfidenceReason = isRemapFailed
+                ? `Member remap from obfuscated→mapping failed; name mismatch may be a remap artifact, not a true missing member.`
+                : confidenceReason;
+            const resolutionPath = isRemapFailed
+                ? "member-remap-failed"
+                : isSigFailed ? "source-signature-unavailable" : undefined;
+            const memberDegraded = isRemapFailed && healthReport?.memberRemapAvailable === false;
+            const suggestions = suggestSimilar(accessor.targetName, candidateNames);
+            const inferenceHint = accessor.targetName !== accessor.name
+                ? ` (inferred "${accessor.targetName}" from "${accessor.name}" via prefix removal)`
+                : "";
+            issues.push({
+                severity: memberDegraded ? "warning" : "error",
+                kind: accessor.annotation === "Invoker" ? "method-not-found" : "field-not-found",
+                annotation: `@${accessor.annotation}`,
+                target: `${targetName}#${accessor.targetName}`,
+                message: `Target "${accessor.targetName}" not found in class "${targetName}".${inferenceHint}${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
+                suggestions: suggestions.length > 0 ? suggestions : undefined,
+                line: accessor.line,
+                confidence: issueConfidence,
+                confidenceReason: issueConfidenceReason,
+                resolutionPath,
+                falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+            });
+            resolvedMembers.push({ annotation: `@${accessor.annotation}`, name: accessor.targetName, line: accessor.line, status: "not-found" });
+        }
+        else {
+            resolvedMembers.push({ annotation: `@${accessor.annotation}`, name: accessor.targetName, line: accessor.line, resolvedTo: `${targetName}#${accessor.targetName}`, status: "resolved" });
+        }
+    }
+}
+//# sourceMappingURL=annotation-validators.js.map

package/dist/mixin/helpers.d.ts

@@ -0,0 +1,28 @@
+import type { ParsedMixin } from "../mixin-parser.js";
+import type { ConfidenceBreakdown, IssueConfidence, MappingHealthReport, MixinValidationProvenance, MixinValidationResult, ResolutionPath, ResolvedMember, ResolvedTargetMembers, StructuredWarning, ValidationStatus, ValidationSummary } from "./types.js";
+export declare const TOOL_RESOLUTION_PATHS: ResolutionPath[];
+export declare function classifyStructuredWarning(message: string): StructuredWarning;
+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 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 allMethodNames(members: ResolvedTargetMembers): string[];
+export declare function allFieldNames(members: ResolvedTargetMembers): string[];
+export declare function accessLevelFromFlags(accessFlags: number | undefined): "public" | "protected" | "private" | "package-private" | undefined;
+export declare function computeFalsePositiveRisk(healthReport: MappingHealthReport | undefined, resolutionPath: ResolutionPath | undefined, issueConfidence: IssueConfidence | undefined): "high" | "medium" | "low" | undefined;
+export declare function computeConfidenceBreakdown(healthReport: MappingHealthReport | undefined, provenance: MixinValidationProvenance | undefined, remapFailureCount: number, skippedMemberCount: number): ConfidenceBreakdown;
+export declare function summarizeResolvedMembers(resolvedMembers: ResolvedMember[]): Pick<ValidationSummary, "membersValidated" | "membersSkipped" | "membersMissing">;
+export declare function computeValidationStatus(summary: ValidationSummary): ValidationStatus;
+export declare function buildQuickSummary(status: ValidationStatus, summary: ValidationSummary, context?: {
+    provenance?: MixinValidationProvenance;
+    healthReport?: MappingHealthReport;
+}): string;
+export declare function addSkippedMembers(parsed: ParsedMixin, resolvedMembers: ResolvedMember[]): void;
+export declare function refreshMixinValidationOutcome(result: MixinValidationResult): MixinValidationResult;