@adhisang/minecraft-modding-mcp 4.1.0 → 4.2.0

package/dist/mapping/types.d.ts

@@ -60,6 +60,7 @@ export type FindMappingInput = {
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     disambiguation?: {
         ownerHint?: string;
         descriptorHint?: string;
@@ -73,6 +74,7 @@ export type EnsureMappingAvailableInput = {
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
 };
 export type EnsureMappingAvailableOutput = {
     transformChain: string[];
@@ -88,6 +90,7 @@ export type ResolveMethodMappingExactInput = {
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     maxCandidates?: number;
 };
 export type ResolveMethodMappingExactOutput = SymbolResolutionOutput;
@@ -97,6 +100,7 @@ export type ClassApiMatrixInput = {
     className: string;
     classNameMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
     includeKinds?: ClassApiMatrixKind[];
     maxRows?: number;
 };
@@ -134,6 +138,7 @@ export type SymbolExistenceInput = {
     descriptor?: string;
     sourceMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
     nameMode?: "fqcn" | "auto";
     signatureMode?: "exact" | "name-only";
     maxCandidates?: number;

package/dist/mapping-service.d.ts

@@ -31,12 +31,17 @@ export declare class MappingService {
     private provenanceForPath;
     /**
      * Probe the mapping graph health for a given version.
-     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     *
+     * `tinyMappingsAvailable` reports whether Tiny is sufficient for the
+     * request: `true` when Tiny is not required (obfuscated/mojang) or is
+     * loaded, `false` only when intermediary/yarn was requested and Tiny is
+     * unavailable.
      */
     checkMappingHealth(input: {
         version: string;
         requestedMapping: SourceMapping;
         sourcePriority?: MappingSourcePriority;
+        gradleUserHome?: string;
     }): Promise<{
         mojangMappingsAvailable: boolean;
         tinyMappingsAvailable: boolean;

package/dist/mapping-service.js

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { createError, ERROR_CODES } from "./errors.js";
+import { resolveGradleUserHomePath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
@@ -112,7 +113,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -254,7 +255,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
@@ -338,7 +339,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -448,7 +449,7 @@ export class MappingService {
             });
         }
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
-        const graph = await this.loadGraph(version, priority, "full");
+        const graph = await this.loadGraph(version, priority, "full", undefined, input.gradleUserHome);
         const warnings = [...graph.warnings];
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
         const pathCache = new Map();
@@ -669,7 +670,7 @@ export class MappingService {
                     querySymbol
                 };
             })();
-        const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full", undefined, input.gradleUserHome);
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
@@ -926,11 +927,16 @@ export class MappingService {
     }
     /**
      * Probe the mapping graph health for a given version.
-     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     *
+     * `tinyMappingsAvailable` reports whether Tiny is sufficient for the
+     * request: `true` when Tiny is not required (obfuscated/mojang) or is
+     * loaded, `false` only when intermediary/yarn was requested and Tiny is
+     * unavailable.
      */
     async checkMappingHealth(input) {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const degradations = [];
+        const needsTinyMappings = input.requestedMapping === "intermediary" || input.requestedMapping === "yarn";
         if (isUnobfuscatedVersion(input.version)) {
             const requestFulfillable = input.requestedMapping === "obfuscated" || input.requestedMapping === "mojang";
             if (!requestFulfillable) {
@@ -938,19 +944,19 @@ export class MappingService {
             }
             return {
                 mojangMappingsAvailable: true,
-                tinyMappingsAvailable: false,
+                tinyMappingsAvailable: !needsTinyMappings,
                 memberRemapAvailable: requestFulfillable,
                 degradations
             };
         }
         let graph;
         try {
-            graph = await this.loadGraph(input.version, priority, "full");
+            graph = await this.loadGraph(input.version, priority, needsTinyMappings ? "full" : "obfuscated-mojang-only", undefined, input.gradleUserHome);
         }
         catch {
             return {
                 mojangMappingsAvailable: false,
-                tinyMappingsAvailable: false,
+                tinyMappingsAvailable: !needsTinyMappings,
                 memberRemapAvailable: false,
                 degradations: ["Mapping graph could not be loaded."]
             };
@@ -967,7 +973,7 @@ export class MappingService {
         if (!mojangAvailable) {
             degradations.push("Mojang client mappings are not available for this version.");
         }
-        if (!tinyAvailable) {
+        if (needsTinyMappings && !tinyAvailable) {
             degradations.push("No intermediary/yarn tiny mappings were found for this version.");
         }
         // Check if member remap path exists (requestedMapping → obfuscated)
@@ -984,14 +990,15 @@ export class MappingService {
         }
         return {
             mojangMappingsAvailable: mojangAvailable,
-            tinyMappingsAvailable: tinyAvailable,
+            tinyMappingsAvailable: needsTinyMappings ? tinyAvailable : true,
             memberRemapAvailable,
             degradations
         };
     }
-    async loadGraph(version, priority, mode, projectPath) {
+    async loadGraph(version, priority, mode, projectPath, gradleUserHome) {
         const effectiveProjectPath = effectiveLoomSearchProjectPath(projectPath);
-        const cacheKey = `${version}|${priority}|${mode}|${effectiveProjectPath ?? ""}`;
+        const effectiveGradleUserHome = resolveGradleUserHomePath(gradleUserHome);
+        const cacheKey = `${version}|${priority}|${mode}|${effectiveProjectPath ?? ""}|${effectiveGradleUserHome}`;
         const cached = this.graphCache.get(cacheKey);
         if (cached) {
             this.graphCache.delete(cacheKey);
@@ -1002,7 +1009,7 @@ export class MappingService {
         if (existingLock) {
             return existingLock;
         }
-        const buildPromise = this.buildGraph(version, priority, mode, effectiveProjectPath);
+        const buildPromise = this.buildGraph(version, priority, mode, effectiveProjectPath, effectiveGradleUserHome);
         this.buildLocks.set(cacheKey, buildPromise);
         try {
             const built = await buildPromise;
@@ -1014,7 +1021,7 @@ export class MappingService {
             this.buildLocks.delete(cacheKey);
         }
     }
-    async buildGraph(version, priority, mode, projectPath) {
+    async buildGraph(version, priority, mode, projectPath, gradleUserHome) {
         if (isUnobfuscatedVersion(version)) {
             return {
                 version,
@@ -1047,7 +1054,7 @@ export class MappingService {
             const deferredTinyWarnings = [];
             for (const source of mappingSourceOrder(priority)) {
                 const tinyLoad = source === "loom-cache"
-                    ? await this.loadTinyPairsFromLoom(version, projectPath)
+                    ? await this.loadTinyPairsFromLoom(version, projectPath, gradleUserHome)
                     : await this.loadTinyPairsFromMaven(version);
                 if (tinyLoad.pairs.size === 0) {
                     deferredTinyWarnings.push(...tinyLoad.warnings);
@@ -1090,8 +1097,8 @@ export class MappingService {
     async loadMojangPairs(version) {
         return loadMojangPairs(this.loaderDeps(), version);
     }
-    async loadTinyPairsFromLoom(version, projectPath) {
-        return loadTinyPairsFromLoom(version, projectPath);
+    async loadTinyPairsFromLoom(version, projectPath, gradleUserHome) {
+        return loadTinyPairsFromLoom(version, projectPath, gradleUserHome);
     }
     async loadTinyPairsFromMaven(version) {
         return loadTinyPairsFromMaven(this.loaderDeps(), version);
@@ -1147,6 +1154,7 @@ export class MappingService {
             input.targetMapping,
             input.sourcePriority ?? "",
             effectiveLoomSearchProjectPath(input.projectPath) ?? "",
+            resolveGradleUserHomePath(input.gradleUserHome),
             effectiveSignatureMode,
             String(input.maxCandidates ?? ""),
             JSON.stringify(input.disambiguation ?? "")

package/dist/mixin-validator.d.ts

@@ -1,7 +1,7 @@
 /**
  * Public barrel for the mixin validation engine. The implementation lives
  * under `src/mixin/`; this file preserves the historical entry point used
- * by source-service, entry tools, and tests.
+ * by source-service, top-level workflow tools, and tests.
  */
 export type { AccessTransformerValidationResult, AccessWidenerValidationResult, AggregatedWarningGroup, ConfidenceBreakdown, ConfidencePenalty, IssueCategory, IssueConfidence, MappingHealthReport, MixinStageBudgets, MixinValidationProvenance, MixinValidationResult, ResolutionPath, ResolvedMember, ResolvedTargetMembers, StructuredWarning, TargetOutcome, ValidationIssue, ValidationStatus, ValidationSummary } from "./mixin/types.js";
 export { loadMixinStageBudgets } from "./mixin/types.js";

package/dist/mixin-validator.js

@@ -1,7 +1,7 @@
 /**
  * Public barrel for the mixin validation engine. The implementation lives
  * under `src/mixin/`; this file preserves the historical entry point used
- * by source-service, entry tools, and tests.
+ * by source-service, top-level workflow tools, and tests.
  */
 export { loadMixinStageBudgets } from "./mixin/types.js";
 export { accessLevelFromFlags, buildQuickSummary, computeConfidenceBreakdown, computeFalsePositiveRisk, computeValidationStatus, extractMethodDescriptor, extractMethodName, levenshteinDistance, refreshMixinValidationOutcome, suggestSimilar, summarizeResolvedMembers } from "./mixin/helpers.js";

package/dist/source/access-validate.js

@@ -56,6 +56,7 @@ export async function validateAccessWidener(svc, input) {
             version,
             awNamespace,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion
         });
@@ -85,7 +86,8 @@ export async function validateAccessWidener(svc, input) {
                     sourceMapping: awNamespace,
                     targetMapping: lookupMapping,
                     sourcePriority: input.sourcePriority,
-                    projectPath: input.projectPath
+                    projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
                     lookupFqn = mapped.resolvedSymbol.name;
@@ -110,9 +112,9 @@ export async function validateAccessWidener(svc, input) {
             let fields = sig.fields;
             if (needsLookupMapping) {
                 const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                    svc.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath),
-                    svc.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath),
-                    svc.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath)
+                    svc.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome)
                 ]);
                 constructors = ctorResult.members;
                 methods = methodResult.members;
@@ -163,6 +165,7 @@ export async function validateAccessTransformer(svc, input) {
             version,
             atNamespace,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion
         });
@@ -197,7 +200,8 @@ export async function validateAccessTransformer(svc, input) {
                         sourceMapping: atNamespace,
                         targetMapping: lookupMapping,
                         sourcePriority: input.sourcePriority,
-                        projectPath: input.projectPath
+                        projectPath: input.projectPath,
+                        gradleUserHome: input.gradleUserHome
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
                         lookupFqn = mapped.resolvedSymbol.name;
@@ -223,9 +227,9 @@ export async function validateAccessTransformer(svc, input) {
             let fields = sig.fields;
             if (needsLookupMapping && isSourceMappingNamespace(atNamespace) && isSourceMappingNamespace(lookupMapping)) {
                 const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                    svc.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath),
-                    svc.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath),
-                    svc.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath)
+                    svc.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath, input.gradleUserHome)
                 ]);
                 constructors = ctorResult.members;
                 methods = methodResult.members;

package/dist/source/artifact-resolver.d.ts

@@ -1,5 +1,5 @@
 import type { SourceService } from "../source-service.js";
-import type { ArtifactContentsSummary, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
+import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeValidationProvenance, SourceMapping } from "../types.js";
 import type { WorkspaceProjectLoader } from "../workspace-mapping-service.js";
 export type VersionSourceDiscovery = {
@@ -32,10 +32,13 @@ export declare function hasExactVersionToken(path: string, version: string): boo
 export declare function discoverVersionSourceJar(_svc: SourceService, input: {
     version: string;
     projectPath?: string;
+    gradleUserHome?: string;
 }): Promise<VersionSourceDiscovery>;
+export declare function probeMinecraftArtifact(svc: SourceService, input: ProbeMinecraftArtifactInput): Promise<ProbeMinecraftArtifactOutput>;
 export declare function discoverAccessWidenerRuntimeCandidates(_svc: SourceService, input: {
     version: string;
     projectPath?: string;
+    gradleUserHome?: string;
     requestedScope: ArtifactScope;
 }): Promise<{
     searchedPaths: string[];
@@ -45,6 +48,7 @@ export declare function discoverAccessWidenerRuntimeCandidates(_svc: SourceServi
 export declare function discoverAccessTransformerRuntimeCandidates(_svc: SourceService, input: {
     version: string;
     projectPath?: string;
+    gradleUserHome?: string;
     requestedScope: ArtifactScope;
     atNamespace: AccessTransformerNamespace;
     loader: WorkspaceProjectLoader | "unknown";
@@ -57,6 +61,7 @@ export declare function resolveAccessWidenerRuntimeArtifact(svc: SourceService,
     version: string;
     awNamespace: SourceMapping;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
 }): Promise<RuntimeValidationProvenance<SourceMapping>>;
@@ -68,6 +73,7 @@ export declare function resolveAccessTransformerRuntimeArtifact(svc: SourceServi
     version: string;
     atNamespace: AccessTransformerNamespace;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
 }): Promise<RuntimeValidationProvenance<AccessTransformerNamespace>>;

package/dist/source/artifact-resolver.js

@@ -7,8 +7,9 @@ import { log } from "../logger.js";
 import { applyMappingPipeline } from "../mapping-pipeline-service.js";
 import { parseCoordinate } from "../maven-resolver.js";
 import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
+import { artifactSignatureFromFile } from "../path-resolver.js";
 import { detectFabricLikeInputNamespace, listJavaEntries } from "../source-jar-reader.js";
-import { resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
+import { artifactIdForJar, resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
 import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
@@ -137,7 +138,10 @@ function buildProvenance(input) {
 }
 export async function discoverVersionSourceJar(_svc, input) {
     const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
-    const searchRoots = buildVersionSourceSearchRoots(normalizedProjectPath);
+    const searchRoots = buildVersionSourceSearchRoots({
+        projectPath: normalizedProjectPath,
+        gradleUserHome: input.gradleUserHome
+    });
     const searchedPaths = [];
     const candidates = [];
     const seen = new Set();
@@ -209,12 +213,112 @@ export async function discoverVersionSourceJar(_svc, input) {
         selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace
     };
 }
+export async function probeMinecraftArtifact(svc, input) {
+    let value = input.target.value.trim();
+    const warnings = [];
+    const requestedMapping = normalizeMapping(input.mapping);
+    if (input.preferProjectVersion && input.projectPath) {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+        if (detected && detected !== value) {
+            warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
+        }
+        value = detected ?? value;
+    }
+    if (!value) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "target.value must be non-empty.",
+            details: { target: input.target }
+        });
+    }
+    const versionJar = await svc.versionService.resolveVersionJar(value);
+    const resolvedVersion = versionJar.version;
+    const runtimeNamesUnobfuscated = isUnobfuscatedVersion(resolvedVersion);
+    warnings.push(`Resolved Minecraft ${versionJar.version} from ${versionJar.clientJarUrl}.`);
+    let effectiveMapping = requestedMapping;
+    if ((requestedMapping === "intermediary" || requestedMapping === "yarn") &&
+        runtimeNamesUnobfuscated) {
+        warnings.push(`Version ${resolvedVersion} is unobfuscated; ${requestedMapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
+        effectiveMapping = "obfuscated";
+    }
+    if ((effectiveMapping === "intermediary" || effectiveMapping === "yarn") &&
+        !runtimeNamesUnobfuscated) {
+        throw createError({
+            code: ERROR_CODES.MAPPING_NOT_APPLIED,
+            message: `Lightweight artifact probe cannot verify ${effectiveMapping} mapping availability without running the full resolver.`,
+            details: {
+                requestedMapping: effectiveMapping,
+                version: resolvedVersion,
+                nextAction: "Use a direct validation task for mapping-sensitive checks, or use mapping=obfuscated for the project-summary artifact probe."
+            }
+        });
+    }
+    if (effectiveMapping === "mojang" && !runtimeNamesUnobfuscated) {
+        // Match validate-mixin's resolve stage: omitted scope defaults to vanilla,
+        // avoiding a workspace-wide source-jar scan that validate-mixin would skip.
+        const effectiveScope = input.scope ?? "vanilla";
+        if (effectiveScope === "vanilla") {
+            throw createError({
+                code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                message: "Lightweight artifact probe cannot verify mojang mapping with scope=vanilla on obfuscated runtime versions.",
+                details: {
+                    requestedMapping: effectiveMapping,
+                    version: resolvedVersion,
+                    nextAction: "Retry with scope=merged and projectPath so the probe can use a Loom source jar, or use mapping=obfuscated."
+                }
+            });
+        }
+        const versionSourceDiscovery = await svc.discoverVersionSourceJar({
+            version: resolvedVersion,
+            projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome
+        });
+        if (!versionSourceDiscovery.selectedSourceJarPath) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                message: "Lightweight artifact probe cannot verify mojang mapping without a source-backed Loom artifact.",
+                details: {
+                    requestedMapping: effectiveMapping,
+                    version: resolvedVersion,
+                    searchedPaths: versionSourceDiscovery.searchedPaths,
+                    candidateArtifacts: versionSourceDiscovery.candidateArtifacts,
+                    nextAction: "Use mapping=obfuscated for project-summary, or run a direct validation task when full source resolution is required."
+                }
+            });
+        }
+        const selectedSourceJarPath = versionSourceDiscovery.selectedSourceJarPath;
+        const sourceSignature = artifactSignatureFromFile(selectedSourceJarPath).signature;
+        const artifactId = artifactIdForJar("jar", selectedSourceJarPath, sourceSignature);
+        warnings.push(`Resolved source-backed artifact from Loom cache candidate: ${selectedSourceJarPath}.`);
+        if (versionSourceDiscovery.selectedHasMinecraftNamespace === false) {
+            warnings.push(`Source coverage does not include net.minecraft for ${selectedSourceJarPath}; class lookups may fall back to the binary artifact.`);
+        }
+        if (!hasExactVersionToken(selectedSourceJarPath, value)) {
+            warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${selectedSourceJarPath}`);
+        }
+        return {
+            artifactId,
+            mappingApplied: "mojang",
+            ...(warnings.length > 0 ? { warnings } : {})
+        };
+    }
+    const binarySignature = artifactSignatureFromFile(versionJar.jarPath).signature;
+    const artifactId = artifactIdForJar("jar", versionJar.jarPath, `${binarySignature}:decompile`);
+    return {
+        artifactId,
+        mappingApplied: effectiveMapping,
+        ...(warnings.length > 0 ? { warnings } : {})
+    };
+}
 export async function discoverAccessWidenerRuntimeCandidates(_svc, input) {
     const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
     const normalizedProjectPathLower = normalizedProjectPath
         ? normalizePathStyle(normalizedProjectPath).toLowerCase()
         : undefined;
-    const searchRoots = buildVersionSourceSearchRoots(normalizedProjectPath);
+    const searchRoots = buildVersionSourceSearchRoots({
+        projectPath: normalizedProjectPath,
+        gradleUserHome: input.gradleUserHome
+    });
     const searchedPaths = [];
     const candidates = [];
     const seen = new Set();
@@ -284,7 +388,10 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
     const normalizedProjectPathLower = normalizedProjectPath
         ? normalizePathStyle(normalizedProjectPath).toLowerCase()
         : undefined;
-    const searchRoots = buildLoaderRuntimeSearchRoots(normalizedProjectPath);
+    const searchRoots = buildLoaderRuntimeSearchRoots({
+        projectPath: normalizedProjectPath,
+        gradleUserHome: input.gradleUserHome
+    });
     const searchedPaths = [];
     const candidates = [];
     const seen = new Set();
@@ -394,6 +501,7 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
     const discovery = await svc.discoverAccessWidenerRuntimeCandidates({
         version,
         projectPath: normalizedProjectPath,
+        gradleUserHome: input.gradleUserHome,
         requestedScope
     });
     if (!discovery.selected) {
@@ -525,6 +633,7 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
     const discovery = await svc.discoverAccessTransformerRuntimeCandidates({
         version,
         projectPath: normalizedProjectPath,
+        gradleUserHome: input.gradleUserHome,
         requestedScope,
         atNamespace: input.atNamespace,
         loader
@@ -693,7 +802,8 @@ async function computeBinaryRemapGate(svc, input) {
         const health = await svc.mappingService.checkMappingHealth({
             version: input.version,
             requestedMapping: "mojang",
-            sourcePriority: input.sourcePriority
+            sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome
         });
         mojangAvailable = health.mojangMappingsAvailable;
     }
@@ -929,7 +1039,8 @@ export async function resolveArtifact(svc, input) {
             scope !== "vanilla") {
             versionSourceDiscovery = await svc.discoverVersionSourceJar({
                 version: resolvedVersion,
-                projectPath: input.projectPath
+                projectPath: input.projectPath,
+                gradleUserHome: input.gradleUserHome
             });
             if (versionSourceDiscovery.selectedSourceJarPath) {
                 resolvedTarget = {
@@ -948,6 +1059,7 @@ export async function resolveArtifact(svc, input) {
                 version: resolvedVersion,
                 targetKind: kind,
                 sourcePriority: input.sourcePriority,
+                gradleUserHome: input.gradleUserHome,
                 forceBinaryRemapDisabled: dependencyOrigin
             });
         if (binaryRemapGate.warnings.length > 0) {
@@ -1040,7 +1152,8 @@ export async function resolveArtifact(svc, input) {
                 version: resolved.version,
                 sourceMapping: "obfuscated",
                 targetMapping: effectiveMapping,
-                sourcePriority: input.sourcePriority
+                sourcePriority: input.sourcePriority,
+                gradleUserHome: input.gradleUserHome
             });
             additionalTransformChain.push(...mappingAvailability.transformChain);
             if (mappingAvailability.warnings.length > 0) {

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

@@ -20,6 +20,7 @@ export type RemapMembersInput = {
     mappingApplied: SourceMapping;
     requestedMapping: SourceMapping;
     sourcePriority: MappingSourcePriority | undefined;
+    gradleUserHome?: string;
     memberPattern: string | undefined;
     warnings: string[];
 };

package/dist/source/class-source/members-builder.js

@@ -3,7 +3,7 @@ export async function remapAndCountMembers(svc, input) {
         if (input.version == null) {
             return members;
         }
-        const result = await svc.remapSignatureMembers(members, kind, input.version, input.mappingApplied, input.requestedMapping, input.sourcePriority, input.warnings);
+        const result = await svc.remapSignatureMembers(members, kind, input.version, input.mappingApplied, input.requestedMapping, input.sourcePriority, input.warnings, undefined, input.gradleUserHome);
         return result.members;
     };
     let constructors = await remap(input.signatureConstructors, "method");

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

@@ -9,6 +9,7 @@ export declare function resolveClassNameForLookup(svc: SourceService, input: {
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority: MappingSourcePriority | undefined;
+    gradleUserHome?: string;
     warnings: string[];
     context: string;
 }): Promise<string>;

package/dist/source/class-source.js

@@ -108,7 +108,8 @@ export async function resolveClassNameForLookup(svc, input) {
             name: input.className,
             sourceMapping: input.sourceMapping,
             targetMapping: input.targetMapping,
-            sourcePriority: input.sourcePriority
+            sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome
         });
         if (mapped.resolved && mapped.resolvedSymbol) {
             return mapped.resolvedSymbol.name;
@@ -401,6 +402,7 @@ export async function getClassSource(svc, input) {
             sourcePriority: input.sourcePriority,
             allowDecompile: input.allowDecompile,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion,
             strictVersion: input.strictVersion
@@ -488,6 +490,7 @@ export async function getClassSource(svc, input) {
         sourceMapping: requestedMapping,
         targetMapping: activeMappingApplied,
         sourcePriority: input.sourcePriority,
+        gradleUserHome: input.gradleUserHome,
         warnings,
         context: "source lookup"
     });
@@ -499,6 +502,7 @@ export async function getClassSource(svc, input) {
             sourceMapping: requestedMapping,
             targetMapping: activeMappingApplied,
             sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome,
             warnings,
             context: "source lookup"
         });
@@ -528,6 +532,7 @@ export async function getClassSource(svc, input) {
             sourceMapping: requestedMapping,
             targetMapping: activeMappingApplied,
             sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome,
             warnings,
             context: "source lookup"
         });
@@ -659,6 +664,7 @@ export async function getClassMembers(svc, input) {
             sourcePriority: input.sourcePriority,
             allowDecompile: input.allowDecompile,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion,
             strictVersion: input.strictVersion
@@ -726,6 +732,7 @@ export async function getClassMembers(svc, input) {
         sourceMapping: requestedMapping,
         targetMapping: mappingApplied,
         sourcePriority: input.sourcePriority,
+        gradleUserHome: input.gradleUserHome,
         warnings,
         context: "binary lookup"
     });
@@ -775,6 +782,7 @@ export async function getClassMembers(svc, input) {
         mappingApplied,
         requestedMapping,
         sourcePriority: input.sourcePriority,
+        gradleUserHome: input.gradleUserHome,
         memberPattern,
         warnings
     });