@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.1

package/dist/source/artifact-resolver.js

@@ -14,6 +14,7 @@ import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 const VERSION_TOKEN_REGEX_CACHE = new Map();
+const LOADER_VERSION_TOKEN_REGEX_CACHE = new Map();
 const MAX_HELPER_REGEX_CACHE = 128;
 function rememberCachedRegex(cache, key, regex) {
     if (cache.size >= MAX_HELPER_REGEX_CACHE) {
@@ -57,6 +58,97 @@ export function hasExactVersionToken(path, version) {
         ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
     return pattern.test(normalizedPath);
 }
+/**
+ * True when a path carries the NeoForge/Forge loader version that corresponds
+ * 1:1 to `mcVersion`.
+ *
+ * ModDevGradle names every artifact after the LOADER version and never after
+ * Minecraft: MC 1.21.11 produces `build/moddev/artifacts/neoforge-21.11.38-beta-merged.jar`.
+ * A plain `hasExactVersionToken(path, "1.21.11")` therefore rejected every
+ * artifact of the canonical NeoForge workspace, which made
+ * validate-access-transformer unusable there.
+ *
+ * NeoForge derives its version from Minecraft as `<minor>.<patch>.<build>`, so
+ * `1.21.11` -> `21.11.<build>` and `1.21` -> `21.0.<build>`. The trailing dot
+ * before the build number keeps `21.1.` from matching `21.10.5`.
+ */
+export function hasLoaderRuntimeVersionToken(path, mcVersion) {
+    const match = /^1\.(\d+)(?:\.(\d+))?$/.exec(mcVersion.trim());
+    if (!match) {
+        return false;
+    }
+    const minor = match[1];
+    const patch = match[2] ?? "0";
+    const normalizedPath = normalizePathStyle(path).toLowerCase();
+    const cacheKey = `loader:${minor}.${patch}`;
+    const pattern = LOADER_VERSION_TOKEN_REGEX_CACHE.get(cacheKey)
+        ?? rememberCachedRegex(LOADER_VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z.])${minor}\\.${patch}\\.\\d`, "i"));
+    return pattern.test(normalizedPath);
+}
+const RUNTIME_JAR_VERSION_REGEX = /(?:^|[^0-9.])(1\.\d+(?:\.\d+)?)(?![0-9.])/;
+/**
+ * Minecraft version a runtime jar path carries, or undefined when the path
+ * names none. Loom lays its cache out as
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
+ * of the path is the version the jar was built for.
+ */
+export function inferRuntimeJarMinecraftVersion(path) {
+    return RUNTIME_JAR_VERSION_REGEX.exec(normalizePathStyle(path))?.[1];
+}
+/**
+ * Loader a runtime jar belongs to, read from its path.
+ *
+ * A Loom cache holds NeoForge-patched jars under a `/neoforge/` segment
+ * (`caches/fabric-loom/1.21.10/neoforge/21.10.50-beta/minecraft-merged-mojang-at-patched.jar`).
+ * Serving one of those to a Fabric workspace silently validated a Fabric access
+ * widener against NeoForge bytecode, so the loader has to travel with the jar.
+ */
+export function inferRuntimeJarLoader(path) {
+    const lower = normalizePathStyle(path).toLowerCase();
+    if (lower.includes("neoforge") || lower.includes("neoform") || lower.includes("moddev")) {
+        return "neoforge";
+    }
+    if (/(^|[/\-_])forge([/\-_.]|$)/.test(lower) || lower.includes("forge_gradle") || lower.includes("srg")) {
+        return "forge";
+    }
+    if (lower.includes("fabric-loom") || lower.includes("loom-cache") || lower.includes("intermediary")) {
+        return "fabric";
+    }
+    return "unknown";
+}
+/**
+ * Fills in the truthful version/loader half of a runtime provenance record.
+ *
+ * `version` becomes the version the SERVED jar carries; the caller's original
+ * request is preserved under `requestedVersion` and flagged. A served loader
+ * that contradicts a KNOWN expected loader is flagged too — never silently
+ * dropped.
+ */
+export function describeServedRuntimeJar(input) {
+    const notes = [];
+    const servedVersion = inferRuntimeJarMinecraftVersion(input.jarPath);
+    const versionApproximated = servedVersion !== undefined && servedVersion !== input.requestedVersion.trim();
+    const servedLoader = inferRuntimeJarLoader(input.jarPath);
+    const expectedLoader = input.expectedLoader;
+    const loaderMismatch = expectedLoader !== undefined &&
+        expectedLoader !== "unknown" &&
+        servedLoader !== "unknown" &&
+        servedLoader !== expectedLoader;
+    if (versionApproximated) {
+        notes.push(`Runtime jar is Minecraft ${servedVersion}, not the requested ${input.requestedVersion}; results are approximate.`);
+    }
+    if (loaderMismatch) {
+        notes.push(`Runtime jar is a ${servedLoader} artifact while the workspace is ${expectedLoader}; its bytecode differs from the ${expectedLoader} runtime.`);
+    }
+    return {
+        version: versionApproximated && servedVersion ? servedVersion : input.requestedVersion,
+        ...(versionApproximated ? { requestedVersion: input.requestedVersion, versionApproximated: true } : {}),
+        servedLoader,
+        ...(expectedLoader ? { expectedLoader } : {}),
+        ...(loaderMismatch ? { loaderMismatch: true } : {}),
+        notes
+    };
+}
 function inferMergedRuntimeNamespaceHint(path) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     if (normalizedPath.includes("merged-intermediary-v2") ||
@@ -407,6 +499,11 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
     const normalizedProjectPathLower = normalizedProjectPath
         ? normalizePathStyle(normalizedProjectPath).toLowerCase()
         : undefined;
+    // A jar inside the caller's own build directory belongs to the version that
+    // workspace declares, whatever its filename says.
+    const projectAnchorAllowed = normalizedProjectPathLower !== undefined &&
+        input.projectMinecraftVersion !== undefined &&
+        input.projectMinecraftVersion.trim() === input.version.trim();
     const searchRoots = buildLoaderRuntimeSearchRoots({
         projectPath: normalizedProjectPath,
         gradleUserHome: input.gradleUserHome
@@ -449,7 +546,17 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
             }
             seen.add(normalizedPath);
             const lower = normalizedPath.toLowerCase();
-            if (!hasExactVersionToken(normalizedPath, input.version)) {
+            const insideProject = normalizedProjectPathLower !== undefined && lower.startsWith(normalizedProjectPathLower);
+            // Positive version evidence is REQUIRED; the three forms are ranked so a
+            // verbatim Minecraft version always beats an inferred one.
+            const versionEvidence = hasExactVersionToken(normalizedPath, input.version)
+                ? "exact-token"
+                : hasLoaderRuntimeVersionToken(normalizedPath, input.version)
+                    ? "loader-token"
+                    : projectAnchorAllowed && insideProject
+                        ? "project-anchored"
+                        : undefined;
+            if (!versionEvidence) {
                 continue;
             }
             const looksMerged = lower.includes("merged");
@@ -457,6 +564,11 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
             const looksForge = lower.includes("forge");
             const looksNeoForge = lower.includes("neoforge") || lower.includes("moddev") || lower.includes("neoform");
             const looksPatchedRuntime = lower.includes("patched") || lower.includes("client-extra") || lower.includes("joined");
+            // client-extra / *-minecraft-resources jars carry resources ONLY, so they
+            // can never answer a class lookup. They stay selectable (a workspace that
+            // has nothing else still gets an answer) but must lose to any real
+            // classes jar.
+            const looksResourcesOnly = lower.includes("client-extra") || lower.includes("minecraft-resources");
             const appliedScope = looksMerged
                 ? "merged"
                 : "loader";
@@ -470,18 +582,21 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
                 continue;
             }
             const score = 10_000 +
-                (normalizedProjectPathLower && lower.startsWith(normalizedProjectPathLower) ? 4_000 : 0) +
+                (versionEvidence === "exact-token" ? 5_000 : versionEvidence === "loader-token" ? 3_500 : 3_000) +
+                (insideProject ? 4_000 : 0) +
                 (looksPatchedRuntime ? 3_000 : 0) +
                 (looksSrg ? 2_500 : 0) +
                 (input.loader === "forge" && looksForge ? 1_500 : 0) +
                 (input.loader === "neoforge" && looksNeoForge ? 1_500 : 0) +
                 (input.requestedScope === appliedScope ? 1_000 : 0) +
-                (looksMerged ? -500 : 0);
+                (looksMerged ? -500 : 0) +
+                (looksResourcesOnly ? -6_000 : 0);
             candidates.push({
                 jarPath: normalizedPath,
                 score,
                 appliedScope,
-                origin: "local-jar"
+                origin: "local-jar",
+                versionEvidence
             });
         }
     }
@@ -504,6 +619,9 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
         const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
         version = detected ?? version;
     }
+    const expectedLoader = normalizedProjectPath
+        ? await detectWorkspaceRuntimeLoader(svc, normalizedProjectPath)
+        : undefined;
     const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
     if (requestedScope === "vanilla") {
         const versionJar = await svc.versionService.resolveVersionJar(version);
@@ -574,9 +692,21 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
             notes.push(...detection.warnings);
         }
     }
+    // Provenance must describe the jar that was SERVED, never the request.
+    const served = describeServedRuntimeJar({
+        jarPath: discovery.selected.jarPath,
+        requestedVersion: version,
+        expectedLoader
+    });
+    notes.push(...served.notes);
     return {
-        version,
+        version: served.version,
         jarPath: discovery.selected.jarPath,
+        ...(served.requestedVersion ? { requestedVersion: served.requestedVersion } : {}),
+        ...(served.versionApproximated ? { versionApproximated: true } : {}),
+        servedLoader: served.servedLoader,
+        ...(served.expectedLoader ? { expectedLoader: served.expectedLoader } : {}),
+        ...(served.loaderMismatch ? { loaderMismatch: true } : {}),
         requestedScope,
         appliedScope,
         requestedMapping: input.awNamespace,
@@ -586,6 +716,28 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
         scopeFallback
     };
 }
+/**
+ * Loader a workspace declares, normalized onto {@link RuntimeLoader}. Quilt is
+ * Fabric-compatible for runtime-jar purposes; anything undetected stays
+ * "unknown" so no mismatch is ever asserted on a guess.
+ */
+async function detectWorkspaceRuntimeLoader(svc, projectPath) {
+    const detection = await svc.workspaceMappingService.detectProjectLoader(projectPath);
+    if (!detection.resolved) {
+        return "unknown";
+    }
+    switch (detection.loader) {
+        case "fabric":
+        case "quilt":
+            return "fabric";
+        case "forge":
+            return "forge";
+        case "neoforge":
+            return "neoforge";
+        default:
+            return "unknown";
+    }
+}
 export async function resolveAccessTransformerNamespace(svc, input) {
     const explicit = normalizeAccessTransformerNamespace(input.atNamespace);
     if (explicit) {
@@ -622,9 +774,15 @@ export async function resolveAccessTransformerNamespace(svc, input) {
 export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
     const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
     let version = input.version;
-    if (input.preferProjectVersion && normalizedProjectPath) {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
-        version = detected ?? version;
+    // The workspace's own declared version is read whenever a project is given:
+    // preferProjectVersion decides whether it OVERRIDES the requested version,
+    // but discovery needs it either way to anchor project-local artifacts whose
+    // filenames carry only a loader version.
+    const projectMinecraftVersion = normalizedProjectPath
+        ? await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath)
+        : undefined;
+    if (input.preferProjectVersion && projectMinecraftVersion) {
+        version = projectMinecraftVersion;
     }
     const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
     if (requestedScope === "vanilla") {
@@ -655,7 +813,8 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
         gradleUserHome: input.gradleUserHome,
         requestedScope,
         atNamespace: input.atNamespace,
-        loader
+        loader,
+        projectMinecraftVersion
     });
     if (!discovery.selected) {
         throw createError({
@@ -670,7 +829,13 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
                 candidateArtifacts: discovery.candidateArtifacts,
                 loaderEvidence: loaderDetection.evidence,
                 loaderWarnings: loaderDetection.warnings,
-                nextAction: "Provide projectPath for a Forge/NeoForge workspace with generated runtime jars, or run the Gradle tasks that populate transformed runtime artifacts before retrying."
+                ...(projectMinecraftVersion ? { projectMinecraftVersion } : {}),
+                // An error must never ask for something the caller already sent.
+                nextAction: normalizedProjectPath
+                    ? `Searched the workspace "${normalizedProjectPath}" and the Gradle caches but found no runtime jar for Minecraft ${version}${projectMinecraftVersion && projectMinecraftVersion !== version
+                        ? ` (the workspace declares ${projectMinecraftVersion}; retry with version="${projectMinecraftVersion}" or preferProjectVersion=true)`
+                        : ""}. Run the Gradle task that populates transformed runtime artifacts (NeoForge/ModDevGradle writes them under build/moddev/artifacts), then retry.`
+                    : "Provide projectPath for a Forge/NeoForge workspace with generated runtime jars, or run the Gradle tasks that populate transformed runtime artifacts before retrying."
             }
         });
     }
@@ -690,15 +855,38 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
                 : "Resolved the closest transformed runtime artifact for validation."
         }
         : undefined;
+    const resolutionNotes = [
+        ...(scopeFallback ? [scopeFallback.reason] : []),
+        ...(selected.versionEvidence && selected.versionEvidence !== "exact-token"
+            ? [
+                selected.versionEvidence === "loader-token"
+                    ? `Runtime jar matched Minecraft ${version} through its loader version token (ModDevGradle names artifacts after the loader, not Minecraft).`
+                    : `Runtime jar matched Minecraft ${version} because it lives in the workspace build directory of a project declaring that version.`
+            ]
+            : [])
+    ];
+    const servedAt = describeServedRuntimeJar({
+        jarPath: selected.jarPath,
+        requestedVersion: version,
+        // An access transformer is a Forge/NeoForge artifact; the workspace loader
+        // refines that when it is known.
+        expectedLoader: loader === "forge" ? "forge" : loader === "neoforge" ? "neoforge" : undefined
+    });
+    resolutionNotes.push(...servedAt.notes);
     return {
-        version,
+        version: servedAt.version,
         jarPath: selected.jarPath,
+        ...(servedAt.requestedVersion ? { requestedVersion: servedAt.requestedVersion } : {}),
+        ...(servedAt.versionApproximated ? { versionApproximated: true } : {}),
+        servedLoader: servedAt.servedLoader,
+        ...(servedAt.expectedLoader ? { expectedLoader: servedAt.expectedLoader } : {}),
+        ...(servedAt.loaderMismatch ? { loaderMismatch: true } : {}),
         requestedScope,
         appliedScope: selected.appliedScope,
         requestedMapping: input.atNamespace,
         mappingApplied,
         origin: selected.origin,
-        resolutionNotes: scopeFallback ? [scopeFallback.reason] : undefined,
+        resolutionNotes: resolutionNotes.length > 0 ? resolutionNotes : undefined,
         scopeFallback
     };
 }
@@ -748,7 +936,7 @@ export async function resolveBinaryFallbackArtifact(svc, input) {
         return undefined;
     }
     try {
-        const fallbackResolved = await resolveSourceTargetInternal({ kind: "jar", value: binaryJarPath }, { allowDecompile: true, preferBinaryOnly: true }, svc.config);
+        const fallbackResolved = await resolveSourceTargetInternal({ kind: "jar", value: binaryJarPath }, { allowDecompile: input.allowDecompile ?? true, preferBinaryOnly: true }, svc.config);
         fallbackResolved.version = fallbackResolved.version ?? input.version;
         fallbackResolved.coordinate = fallbackResolved.coordinate ?? input.coordinate;
         fallbackResolved.requestedMapping = input.requestedMapping;
@@ -844,8 +1032,19 @@ async function computeBinaryRemapGate(svc, input) {
         warnings: baseline.warnings
     };
 }
+/**
+ * Describe what an artifact's indexed contents are.
+ *
+ * `sourceKind` is a derivation question — was the text produced by decompiling
+ * bytecode? — and only the persisted `isDecompiled` flag answers it. `origin`
+ * records provenance (where the bytes came from) and is deliberately not read:
+ * the two axes disagree in practice, most visibly for a Jar-in-Jar shell, whose
+ * row keeps origin "decompiled" while ingest clears the derivation flag. It
+ * stays in the input shape only because every caller already carries it
+ * alongside the fields that are read.
+ */
 export function buildArtifactContentsSummary(_svc, input) {
-    const sourceKind = input.isDecompiled || input.origin === "decompiled" || !normalizeOptionalString(input.sourceJarPath)
+    const sourceKind = input.isDecompiled || !normalizeOptionalString(input.sourceJarPath)
         ? "decompiled-binary"
         : "source-jar";
     const sourceCoverage = hasPartialNetMinecraftCoverage(input.qualityFlags) ? "partial" : "full";
@@ -1233,7 +1432,20 @@ export async function resolveArtifact(svc, input) {
                     });
                 }
                 resolved.qualityFlags.push("version-approximated");
-                warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}`);
+                // Provenance must name the version that was SERVED. Echoing the request
+                // here made a fallback indistinguishable from an exact hit, and left
+                // downstream version context pointing at a version the jar is not.
+                const servedVersion = inferRuntimeJarMinecraftVersion(versionSourceDiscovery.selectedSourceJarPath);
+                provenance.versionApproximation = {
+                    requestedVersion: value,
+                    ...(servedVersion ? { servedVersion } : {}),
+                    sourceJarPath: versionSourceDiscovery.selectedSourceJarPath
+                };
+                if (servedVersion) {
+                    provenance.resolvedFrom.version = servedVersion;
+                }
+                warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}` +
+                    (servedVersion ? ` (serving Minecraft ${servedVersion})` : ""));
             }
         }
         resolved.qualityFlags = dedupeQualityFlags(resolved.qualityFlags);

package/dist/source/class-source.d.ts

@@ -40,10 +40,46 @@ export declare function buildFallbackProvenance(svc: SourceService, input: {
 export declare function buildClassSourceNotFoundError(svc: SourceService, input: {
     className: string;
     lookupClassName: string;
+    /**
+     * Artifact the lookup ended on. TWO internal paths move it off the requested
+     * artifact: the binary fallback, and the nested-jar redirect that follows a
+     * shell jar's bundled inner jar.
+     */
     artifactId: string;
+    /**
+     * Artifact the caller actually asked about. Both internal redirects swap the
+     * active artifact mid-lookup, but the error must keep answering about the
+     * requested one: reporting the redirect target sends the caller to an artifact
+     * they never named. Defaults to `artifactId` for paths with no redirect.
+     */
+    requestedArtifactId?: string;
+    /**
+     * Mapping and quality flags OF THE REQUESTED ARTIFACT. `details.artifactId`
+     * names the requested artifact, so `details.mapping` (which reaches
+     * `error.context` through the allowlist) and `details.qualityFlags` have to
+     * describe that same artifact. The nested-jar redirect REPLACES the active
+     * values with the inner jar's, which would otherwise publish one artifact's
+     * identity beside another's namespace and quality — and point the
+     * `suggestedCall` at an index holding neither the class nor its siblings.
+     */
     mappingApplied: SourceMapping;
     requestedMapping: SourceMapping;
     qualityFlags: string[];
+    /**
+     * The mapping the CALLER wrote in the request, undefined when they omitted it.
+     * Distinct from `requestedMapping`, which falls back to the artifact's own
+     * namespace: only the caller-supplied value can tell whether the obfuscated
+     * namespace hint would be re-asking for an argument that is already present.
+     */
+    callerSuppliedMapping?: SourceMapping;
+    /**
+     * Whether the REQUESTED artifact is a native dependency, i.e. its provenance
+     * carries `dependencyResolution`. Such artifacts are handed
+     * `mappingApplied: "obfuscated"` by substitution rather than by being an
+     * obfuscated index, which the obfuscated namespace hint must not mistake for
+     * a missing mapping argument.
+     */
+    nativeDependency?: boolean;
     attemptedBinaryFallback: boolean;
     filePath?: string;
     targetKind?: string;