@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/mixin/annotation-validators.js

@@ -1,19 +1,70 @@
 import { allFieldNames, allMethodNames, computeFalsePositiveRisk, extractMethodDescriptor, extractMethodName, suggestSimilar } from "./helpers.js";
+// Mixin regex target selector: "/pattern/" or "owner=/…/ name=/…/ desc=/…/".
+const REGEX_SELECTOR_RE = /^(?:(?:owner|name|desc)\s*=\s*)?\//;
+// Trailing target-selector quantifier. For the brace form, group 1 is the minimum,
+// group 2 the comma (open or explicit maximum) and group 3 the maximum.
+const QUANTIFIER_RE = /(?:\*|\+|\{(\d*)(?:(,)(\d*))?\})$/;
 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);
+        if (REGEX_SELECTOR_RE.test(inj.method.trim())) {
+            // Regex selectors ("/pattern/", "name=/pattern/ desc=/pattern/") match by pattern,
+            // which the name lookup below cannot evaluate; unverifiable.
+            resolvedMembers.push({
+                annotation: `@${inj.annotation}`,
+                name: inj.method,
+                line: inj.line,
+                status: "skipped"
+            });
+            continue;
+        }
+        // Mixin strips all whitespace from a selector before parsing it ("tick{1, 3}").
+        const selector = inj.method.replace(/\s+/g, "");
         // Strip owner prefix and JVM descriptor from the method reference
-        const rawMethodName = extractMethodName(inj.method);
-        // Strip a trailing target-selector quantifier (e.g. "tick*", "tick+", "tick{2,3}")
-        const quantifier = /(?:\*|\+|\{\d+(?:,\d+)?\})$/.exec(rawMethodName)?.[0];
+        const rawMethodName = extractMethodName(selector);
+        // Strip a trailing target-selector quantifier (e.g. "tick*", "tick+", "tick{2,3}").
+        // As in Mixin, the quantifier only bounds how many members the EXACT name (and
+        // descriptor, when given) must match; it never turns the name into a prefix glob.
+        const quantifierMatch = QUANTIFIER_RE.exec(rawMethodName);
+        const quantifier = quantifierMatch?.[0];
         const methodName = quantifier
             ? rawMethodName.slice(0, rawMethodName.length - quantifier.length)
             : rawMethodName;
-        if (quantifier && methodName === "") {
-            // Bare wildcard selector (e.g. method = "*") matches everything; unverifiable.
+        let minMatches = quantifier === "+" ? 1 : 0;
+        if (quantifierMatch && quantifier !== "*" && quantifier !== "+") {
+            minMatches = quantifierMatch[1] ? Number.parseInt(quantifierMatch[1], 10) : 0;
+            const maxMatches = quantifierMatch[2] === undefined
+                ? minMatches
+                : quantifierMatch[3]
+                    ? Number.parseInt(quantifierMatch[3], 10)
+                    : Number.POSITIVE_INFINITY;
+            // Mixin clamps a max below the min up to the min ("{3,1}" acts as "{3}"), so only a
+            // quantifier whose clamped max is 0 ("{}", "{0}") allows no match; Mixin rejects it.
+            if (Math.max(minMatches, maxMatches) === 0) {
+                issues.push({
+                    severity: "warning",
+                    kind: "method-not-found",
+                    annotation: `@${inj.annotation}`,
+                    target: `${targetName}#${inj.method}`,
+                    message: `Selector "${rawMethodName}" has a malformed quantifier "${quantifier}" (it allows no match); Mixin rejects it.`,
+                    line: inj.line,
+                    confidence: "likely"
+                });
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: rawMethodName,
+                    line: inj.line,
+                    status: "not-found"
+                });
+                continue;
+            }
+        }
+        const anyName = quantifier !== undefined && methodName === "";
+        if (anyName && minMatches === 0 && !extractMethodDescriptor(selector)) {
+            // A bare "*" matches any method, or none at all; there is nothing to check.
             resolvedMembers.push({
                 annotation: `@${inj.annotation}`,
                 name: rawMethodName,
@@ -22,12 +73,12 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             });
             continue;
         }
-        const matched = (quantifier === "*" || quantifier === "+")
-            ? methodNames.some((n) => n.startsWith(methodName))
-            : methodNames.includes(methodName);
+        // An empty name with a quantifier ("*(I)V", "+", "{2}") matches any method name; its
+        // descriptor and count still apply below.
+        const matched = anyName || methodNames.includes(methodName);
         if (!matched) {
             const suggestions = suggestSimilar(methodName, methodNames);
-            const descriptor = extractMethodDescriptor(inj.method);
+            const descriptor = extractMethodDescriptor(selector);
             const descriptorHint = descriptor ? ` (descriptor: ${descriptor})` : "";
             // Determine if this is a remap artifact or signature unavailability
             const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
@@ -64,31 +115,39 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             // Name matched. If the reference carries a JVM descriptor, require an
             // overload to match it; otherwise a wrong-signature target (e.g. tick(D)V
             // when only tick(I)V exists) is silently reported as resolved.
-            const refDescriptor = quantifier ? undefined : extractMethodDescriptor(inj.method);
-            const sameNameMembers = [...members.constructors, ...members.methods].filter((member) => member.name === methodName);
-            if (refDescriptor &&
-                sameNameMembers.length > 0 &&
-                !sameNameMembers.some((member) => member.jvmDescriptor === refDescriptor)) {
-                const available = [...new Set(sameNameMembers.map((member) => member.jvmDescriptor))];
-                const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
-                const isSigFailed = signatureFailedTargets?.has(targetName);
-                // Only a healthy mapping lets us trust that the user-written descriptor is
-                // byte-equal to the runtime descriptor; otherwise downgrade to a warning.
-                const mappingDegraded = Boolean(isRemapFailed) || Boolean(isSigFailed) || healthReport?.overallHealthy === false;
-                const resolutionPath = isRemapFailed
-                    ? "member-remap-failed"
-                    : isSigFailed
-                        ? "source-signature-unavailable"
-                        : undefined;
-                const issueConfidence = mappingDegraded
-                    ? "uncertain"
-                    : confidence ?? "definite";
+            const refDescriptor = extractMethodDescriptor(selector);
+            const sameNameMembers = anyName
+                ? members.methods
+                : [...members.constructors, ...members.methods].filter((member) => member.name === methodName);
+            const displayName = anyName ? rawMethodName : methodName;
+            const matchCount = refDescriptor
+                ? sameNameMembers.filter((member) => member.jvmDescriptor === refDescriptor).length
+                : sameNameMembers.length;
+            const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
+            const isSigFailed = signatureFailedTargets?.has(targetName);
+            // Only a healthy mapping lets us trust that the user-written descriptor (and the
+            // overload count) is byte-equal to the runtime one; otherwise downgrade to a warning.
+            const mappingDegraded = Boolean(isRemapFailed) || Boolean(isSigFailed) || healthReport?.overallHealthy === false;
+            const resolutionPath = isRemapFailed
+                ? "member-remap-failed"
+                : isSigFailed
+                    ? "source-signature-unavailable"
+                    : undefined;
+            const issueConfidence = mappingDegraded
+                ? "uncertain"
+                : confidence ?? "definite";
+            if (refDescriptor && matchCount === 0 && (anyName || sameNameMembers.length > 0)) {
+                const available = anyName
+                    ? []
+                    : [...new Set(sameNameMembers.map((member) => member.jvmDescriptor))];
                 issues.push({
                     severity: mappingDegraded ? "warning" : "error",
                     kind: "descriptor-mismatch",
                     annotation: `@${inj.annotation}`,
                     target: `${targetName}#${inj.method}`,
-                    message: `Method "${methodName}" exists in "${targetName}" but no overload matches descriptor ${refDescriptor} (available: ${available.join(", ")}).${mappingDegraded ? " (mapping degraded; may be a remap artifact)" : ""}`,
+                    message: `${anyName
+                        ? `No method in "${targetName}" matches descriptor ${refDescriptor}.`
+                        : `Method "${methodName}" exists in "${targetName}" but no overload matches descriptor ${refDescriptor} (available: ${available.join(", ")}).`}${mappingDegraded ? " (mapping degraded; may be a remap artifact)" : ""}`,
                     suggestions: available.length > 0 ? available : undefined,
                     line: inj.line,
                     confidence: issueConfidence,
@@ -100,7 +159,31 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
                 });
                 resolvedMembers.push({
                     annotation: `@${inj.annotation}`,
-                    name: methodName,
+                    name: displayName,
+                    line: inj.line,
+                    status: "not-found"
+                });
+            }
+            else if (matchCount < minMatches) {
+                // "+" and "{n}"/"{n,}"/"{n,m}" demand at least n matching members. A shortfall stays
+                // uncertain: if a remap ran, a member whose name could not be remapped may not be counted.
+                issues.push({
+                    severity: "warning",
+                    kind: "method-not-found",
+                    annotation: `@${inj.annotation}`,
+                    target: `${targetName}#${inj.method}`,
+                    message: `Selector "${rawMethodName}" requires at least ${minMatches} matching method(s)${anyName ? "" : ` named "${methodName}"`} in target class "${targetName}" but found ${matchCount}.${mappingDegraded ? " (mapping degraded; may be a remap artifact)" : ""}`,
+                    line: inj.line,
+                    confidence: "uncertain",
+                    confidenceReason: mappingDegraded
+                        ? `Member remap/signature degraded; the overload count may be a tooling artifact.`
+                        : `Counted from the listed members; a member whose name could not be remapped, if any, is not counted.`,
+                    resolutionPath,
+                    falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, "uncertain")
+                });
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: displayName,
                     line: inj.line,
                     status: "not-found"
                 });
@@ -108,9 +191,9 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             else {
                 resolvedMembers.push({
                     annotation: `@${inj.annotation}`,
-                    name: methodName,
+                    name: displayName,
                     line: inj.line,
-                    resolvedTo: `${targetName}#${methodName}`,
+                    resolvedTo: `${targetName}#${displayName}`,
                     status: "resolved"
                 });
             }
@@ -118,11 +201,20 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
     }
 }
 export function validateShadow(shadow, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
+    // A @Shadow method declared as `<prefix>name` refers to `name` in the target; a
+    // @Shadow field's targetName is its declared name unchanged, since fields are not
+    // prefixed. `aliases` adds fallback names. Messages keep the declared name so they
+    // stay recognisable in the mixin source.
+    const effectiveName = shadow.targetName ?? shadow.name;
+    const candidateNames = [effectiveName, ...(shadow.aliases ?? [])];
+    const prefixHint = effectiveName !== shadow.name
+        ? ` (resolved to "${effectiveName}" after @Shadow prefix removal)`
+        : "";
     for (const targetName of targetNames) {
         const members = targetMembers.get(targetName);
         if (!members)
             continue;
-        const isRemapFailed = remapFailedMembers?.get(targetName)?.has(shadow.name);
+        const isRemapFailed = remapFailedMembers?.get(targetName)?.has(effectiveName);
         const isSigFailed = signatureFailedTargets?.has(targetName);
         const issueConfidence = isRemapFailed ? "uncertain" : confidence;
         const issueConfidenceReason = isRemapFailed
@@ -134,14 +226,15 @@ export function validateShadow(shadow, targetMembers, targetNames, issues, resol
         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);
+            const matchedName = candidateNames.find((candidate) => fieldNames.includes(candidate));
+            if (matchedName === undefined) {
+                const suggestions = suggestSimilar(effectiveName, 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)" : ""}`,
+                    target: `${targetName}#${effectiveName}`,
+                    message: `Field "${shadow.name}" not found in target class "${targetName}" (${fieldNames.length} field(s) available).${prefixHint}${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
                     suggestions: suggestions.length > 0 ? suggestions : undefined,
                     line: shadow.line,
                     confidence: issueConfidence,
@@ -152,19 +245,20 @@ export function validateShadow(shadow, targetMembers, targetNames, issues, resol
                 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" });
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, resolvedTo: `${targetName}#${matchedName}`, status: "resolved" });
             }
         }
         else {
             const methodNames = allMethodNames(members);
-            if (!methodNames.includes(shadow.name)) {
-                const suggestions = suggestSimilar(shadow.name, methodNames);
+            const matchedName = candidateNames.find((candidate) => methodNames.includes(candidate));
+            if (matchedName === undefined) {
+                const suggestions = suggestSimilar(effectiveName, 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)" : ""}`,
+                    target: `${targetName}#${effectiveName}`,
+                    message: `Method "${shadow.name}" not found in target class "${targetName}" (${methodNames.length} method(s) available).${prefixHint}${memberDegraded ? " (infrastructure degraded; may be false positive)" : ""}`,
                     suggestions: suggestions.length > 0 ? suggestions : undefined,
                     line: shadow.line,
                     confidence: issueConfidence,
@@ -175,7 +269,7 @@ export function validateShadow(shadow, targetMembers, targetNames, issues, resol
                 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" });
+                resolvedMembers.push({ annotation: "@Shadow", name: shadow.name, line: shadow.line, resolvedTo: `${targetName}#${matchedName}`, status: "resolved" });
             }
         }
     }

package/dist/mixin/parsed-validator.js

@@ -4,6 +4,20 @@ import { validateAccessor, validateInjection, validateShadow } from "./annotatio
 export function validateParsedMixin(parsed, targetMembers, warnings, provenance, confidence, mappingFailedTargets, explain, remapFailedMembers, signatureFailedTargets, suggestedCallContext, warningMode, healthReport, symbolExistsButSignatureFailed, deferredBudgetTargets) {
     const issues = [];
     const targetNames = parsed.targets.map((t) => t.className);
+    // A member is checked only against the targets of the @Mixin class that owns it; a member
+    // without an owner is checked against every target.
+    const ownerTargets = (parsed.mixins ?? []).map((mixin) => new Set(mixin.targets.map((t) => t.className)));
+    const targetsOf = (member, names) => {
+        const owned = member.mixinIndex === undefined ? undefined : ownerTargets[member.mixinIndex];
+        return owned ? names.filter((name) => owned.has(name)) : names;
+    };
+    // The members that a failed target leaves unvalidated: those whose owner targets it.
+    const membersOf = (targetName) => ({
+        ...parsed,
+        injections: parsed.injections.filter((member) => targetsOf(member, [targetName]).length > 0),
+        shadows: parsed.shadows.filter((member) => targetsOf(member, [targetName]).length > 0),
+        accessors: parsed.accessors.filter((member) => targetsOf(member, [targetName]).length > 0)
+    });
     const confidenceReason = confidence === "uncertain"
         ? `Mapping fallback: requested "${provenance?.requestedMapping}" but applied "${provenance?.mappingApplied}".`
         : confidence === "likely"
@@ -27,7 +41,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     resolutionPath: "target-mapping-failed",
                     falsePositiveRisk: healthReport?.overallHealthy === false ? "high" : "medium"
                 });
-                addSkippedMembers(parsed, resolvedMembers);
+                addSkippedMembers(membersOf(target.className), resolvedMembers);
             }
             else if (symbolExistsButSignatureFailed?.has(target.className)) {
                 // Symbol exists in mapping graph but getSignature failed — tool limitation, not code issue
@@ -44,12 +58,12 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     issueOrigin: "tool_issue",
                     falsePositiveRisk: "high"
                 });
-                addSkippedMembers(parsed, resolvedMembers);
+                addSkippedMembers(membersOf(target.className), resolvedMembers);
             }
             else if (deferredBudgetTargets?.has(target.className)) {
                 // Deferred by stage budget; the targetOutcomes entry already records
                 // this, so skip member validation rather than emit a not-found error.
-                addSkippedMembers(parsed, resolvedMembers);
+                addSkippedMembers(membersOf(target.className), resolvedMembers);
             }
             else if (signatureFailedTargets?.has(target.className)) {
                 issues.push({
@@ -65,7 +79,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     issueOrigin: "tool_issue",
                     falsePositiveRisk: "high"
                 });
-                addSkippedMembers(parsed, resolvedMembers);
+                addSkippedMembers(membersOf(target.className), resolvedMembers);
             }
             else {
                 issues.push({
@@ -85,13 +99,13 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
     // 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, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
+        validateInjection(inj, targetMembers, targetsOf(inj, resolvedTargetNames), issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
     }
     for (const shadow of parsed.shadows) {
-        validateShadow(shadow, targetMembers, resolvedTargetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
+        validateShadow(shadow, targetMembers, targetsOf(shadow, resolvedTargetNames), issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
     }
     for (const accessor of parsed.accessors) {
-        validateAccessor(accessor, targetMembers, resolvedTargetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
+        validateAccessor(accessor, targetMembers, targetsOf(accessor, resolvedTargetNames), issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport);
     }
     // Add parse warnings — escalate @Accessor/@Invoker/@Shadow parse failures to issues
     for (const pw of parsed.parseWarnings) {

package/dist/mixin-parser.d.ts

@@ -5,26 +5,71 @@
 export type ParsedMixinTarget = {
     className: string;
 };
+/**
+ * One `@Mixin`-annotated class in the file. A file can hold several (nested or top-level),
+ * and each member is validated only against the targets of the class that owns it.
+ */
+export type ParsedMixinClass = {
+    /** Simple name of the annotated class. */
+    className: string;
+    /** Targets named by this class's own `@Mixin` annotation. */
+    targets: ParsedMixinTarget[];
+    /** 1-based line of the `@Mixin` annotation. */
+    startLine: number;
+    /** 1-based line of the brace that closes the class body. */
+    endLine: number;
+    /**
+     * Simple names from the file's top-level type down to this class (`["Outer", "Inner"]`, the
+     * nesting a mixins-config entry `Outer$Inner` names). Absent for a class declared inside a
+     * method, initializer or anonymous class body, which no such entry can name.
+     */
+    classPath?: string[];
+    /** This class's own `@Mixin(priority = ...)`, when given. */
+    priority?: number;
+};
 export type ParsedInjection = {
     annotation: string;
     method: string;
     line: number;
+    /**
+     * Index into `ParsedMixin.mixins` of the innermost `@Mixin` class enclosing this member
+     * (a member of a nested non-mixin class belongs to the nearest enclosing `@Mixin` class).
+     * Absent when no `@Mixin` class encloses it; such a member is checked against every target.
+     */
+    mixinIndex?: number;
 };
 export type ParsedShadow = {
     kind: "field" | "method";
     name: string;
+    /**
+     * The member looked up in the target: for a method, the declared name with the @Shadow
+     * prefix removed; for a field, the declared name unchanged (fields are not prefixed).
+     */
+    targetName?: string;
+    /** Alternative target names from `@Shadow(aliases = {...})`. */
+    aliases?: string[];
     descriptor?: string;
     line: number;
+    /** Owning `@Mixin` class; see `ParsedInjection.mixinIndex`. */
+    mixinIndex?: number;
 };
 export type ParsedAccessor = {
     annotation: "Accessor" | "Invoker";
     name: string;
     targetName: string;
     line: number;
+    /** Owning `@Mixin` class; see `ParsedInjection.mixinIndex`. */
+    mixinIndex?: number;
 };
 export type ParsedMixin = {
     className: string;
+    /** Every target named by any `@Mixin` annotation in the file, first occurrence first. */
     targets: ParsedMixinTarget[];
+    /**
+     * Each `@Mixin` class whose body could be located, in source order. Absent on a parse
+     * result built without ownership, whose members are then checked against every target.
+     */
+    mixins?: ParsedMixinClass[];
     priority?: number;
     imports: Map<string, string>;
     injections: ParsedInjection[];
@@ -33,3 +78,10 @@ export type ParsedMixin = {
     parseWarnings: string[];
 };
 export declare function parseMixinSource(source: string): ParsedMixin;
+/**
+ * `parsed` narrowed to the nested `@Mixin` class at `classPath` (see `ParsedMixinClass.classPath`;
+ * `["Outer", "Inner"]` for a config entry `Outer$Inner`): its own targets and priority, and only
+ * the members and line-numbered parse warnings it owns. Undefined when no `@Mixin` class sits at
+ * that path.
+ */
+export declare function selectNestedMixin(parsed: ParsedMixin, classPath: readonly string[]): ParsedMixin | undefined;