@adhisang/minecraft-modding-mcp 7.1.0 → 7.1.1

package/dist/source/validate-mixin/pipeline/mapping-health.js

@@ -1,4 +1,23 @@
 import { existsSync } from "node:fs";
+/**
+ * Whether the mapping data required by `requestedMapping` is present.
+ *
+ * Mojang mappings are only on the resolution path for `"mojang"` requests.
+ * `"yarn"`/`"intermediary"` requests resolve through Tiny mappings instead
+ * and never touch Mojang mappings. `"obfuscated"` requests need neither —
+ * the jar itself (checked separately via `jarAvailable`) is sufficient.
+ */
+function requiredMappingHealthy(requestedMapping, health) {
+    switch (requestedMapping) {
+        case "mojang":
+            return health.mojangMappingsAvailable;
+        case "yarn":
+        case "intermediary":
+            return health.tinyMappingsAvailable;
+        case "obfuscated":
+            return true;
+    }
+}
 export async function runMappingHealthStage(svc, ctx) {
     const mappingHealthStartedAt = await ctx.enterStage("mapping-health");
     try {
@@ -15,7 +34,7 @@ export async function runMappingHealthStage(svc, ctx) {
             mojangMappingsAvailable: health.mojangMappingsAvailable,
             tinyMappingsAvailable: health.tinyMappingsAvailable,
             memberRemapAvailable: health.memberRemapAvailable,
-            overallHealthy: jarAvailable && health.mojangMappingsAvailable,
+            overallHealthy: jarAvailable && requiredMappingHealthy(ctx.requestedMapping, health),
             degradations: [
                 ...(jarAvailable ? [] : ["Game jar not found."]),
                 ...health.degradations

package/dist/source/validate-mixin/pipeline/target-lookup.js

@@ -101,10 +101,13 @@ export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
         }
     }
     try {
+        // Mixin can target synthetic members (lambda bodies, bridges, $VALUES, this$0) and counts
+        // synthetic methods in quantifiers.
         const sig = await svc.explorerService.getSignature({
             fqn: obfuscatedName,
             jarPath: ctx.jarPath,
-            access: "all"
+            access: "all",
+            includeSynthetic: true
         });
         ctx.warnings.push(...sig.warnings);
         ctx.resolutionTrace?.push({ target: target.className, step: "signature", input: obfuscatedName, output: `${sig.methods.length} methods, ${sig.fields.length} fields`, success: true });
@@ -112,15 +115,21 @@ export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
         let methods = sig.methods;
         let fields = sig.fields;
         if (ctx.requestedMapping !== ctx.signatureLookupMapping) {
+            const remap = (members, kind, warnings) => svc.remapSignatureMembers(members, kind, ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, warnings, ctx.input.projectPath, ctx.input.gradleUserHome);
+            // Unnamed lambdas routinely have no mapping; a synthetic member that fails to remap
+            // stays listed under its source name without degrading the target or the result.
+            const syntheticWarnings = [];
             try {
-                const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                    svc.remapSignatureMembers(sig.constructors, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome),
-                    svc.remapSignatureMembers(sig.methods, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome),
-                    svc.remapSignatureMembers(sig.fields, "field", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome)
+                const [ctorResult, methodResult, fieldResult, syntheticMethodResult, syntheticFieldResult] = await Promise.all([
+                    remap(sig.constructors, "method", ctx.warnings),
+                    remap(sig.methods.filter((member) => !member.isSynthetic), "method", ctx.warnings),
+                    remap(sig.fields.filter((member) => !member.isSynthetic), "field", ctx.warnings),
+                    remap(sig.methods.filter((member) => member.isSynthetic), "method", syntheticWarnings),
+                    remap(sig.fields.filter((member) => member.isSynthetic), "field", syntheticWarnings)
                 ]);
                 constructors = ctorResult.members;
-                methods = methodResult.members;
-                fields = fieldResult.members;
+                methods = [...methodResult.members, ...syntheticMethodResult.members];
+                fields = [...fieldResult.members, ...syntheticFieldResult.members];
                 const targetFailed = new Set();
                 for (const n of ctorResult.failedNames)
                     targetFailed.add(n);

package/dist/source/validate-mixin.d.ts

@@ -8,6 +8,11 @@ export type ValidateMixinSingleInput = Omit<ValidateMixinInput, "input" | "versi
     version: string;
     source?: string;
     sourcePath?: string;
+    /**
+     * Validate only the `@Mixin` class at this simple-name path from the source's top-level class
+     * down (`["Outer"]` for a config entry `Outer`, `["Outer", "Inner"]` for `Outer$Inner`).
+     */
+    nestedClassPath?: string[];
     batchCaches?: {
         classMappings: Map<string, Promise<MappingFindMappingOutput>>;
     };

package/dist/source/validate-mixin.js

@@ -4,6 +4,7 @@ import { performance } from "node:perf_hooks";
 import fastGlob from "fast-glob";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { loadMixinStageBudgets, refreshMixinValidationOutcome, validateParsedMixin } from "../mixin-validator.js";
+import { selectNestedMixin } from "../mixin-parser.js";
 import { normalizePathForHost } from "../path-converter.js";
 import { NOOP_STAGE_EMITTER } from "../stage-emitter.js";
 import { createMixinPipelineContext } from "./validate-mixin/pipeline-context.js";
@@ -262,11 +263,12 @@ async function runValidateMixinDispatcher(svc, rawInput, options = {}) {
     return validateMixinMany(svc, mode, configSources.map((entry) => ({
         source: {
             kind: "config",
-            label: entry.sourcePath,
+            label: (entry.nestedClassPath?.length ?? 0) > 1 ? `${entry.sourcePath} (${entry.entry})` : entry.sourcePath,
             path: entry.sourcePath,
             configPath: entry.configPath
         },
-        sourcePath: entry.sourcePath
+        sourcePath: entry.sourcePath,
+        nestedClassPath: entry.nestedClassPath
     })), resolvedInput, configWarnings, sharedSingleOptions);
 }
 async function createProjectValidateMixinConfigInput(input) {
@@ -299,7 +301,7 @@ async function createProjectValidateMixinConfigInput(input) {
         }
     };
 }
-function shouldRetryValidateMixinWithMavenFirst(svc, input, result) {
+function shouldRetryValidateMixinWithMavenFirst(svc, input, result, eligibilityIssues) {
     const initialPriority = input.retryState?.initialSourcePriority ?? input.sourcePriority ?? svc.config.mappingSourcePriority;
     if (input.retryState?.attempted || initialPriority !== "loom-first") {
         return false;
@@ -316,7 +318,9 @@ function shouldRetryValidateMixinWithMavenFirst(svc, input, result) {
     if (result.summary.membersSkipped > 0) {
         return true;
     }
-    return result.issues.some((issue) => issue.resolutionPath === "source-signature-unavailable" ||
+    // eligibilityIssues is the pre-category-filter issue list: a display
+    // filter (warningCategoryFilter) must not change whether a retry happens.
+    return eligibilityIssues.some((issue) => issue.resolutionPath === "source-signature-unavailable" ||
         issue.resolutionPath === "target-mapping-failed" ||
         issue.resolutionPath === "member-remap-failed");
 }
@@ -401,6 +405,20 @@ async function runValidateMixinPipeline(svc, seed) {
     await runResolveStage(svc, ctx);
     await runMappingHealthStage(svc, ctx);
     await runParseStage(ctx);
+    const nestedClassPath = ctx.input.nestedClassPath;
+    if (nestedClassPath) {
+        const nested = selectNestedMixin(ctx.parsed, nestedClassPath);
+        // A top-level entry whose file has no located @Mixin class keeps the whole-file result.
+        const wholeFile = nestedClassPath.length === 1 && (ctx.parsed.mixins ?? []).length === 0;
+        if (!nested && !wholeFile) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `No @Mixin class "${nestedClassPath.join("$")}" is declared in "${ctx.input.sourcePath ?? "<source>"}".`,
+                details: { failedStage: "parse" }
+            });
+        }
+        ctx.parsed = nested ?? ctx.parsed;
+    }
     await runTargetLookupStage(svc, ctx);
     return finalizeValidateMixinPipeline(svc, ctx);
 }
@@ -498,7 +516,25 @@ async function finalizeValidateMixinPipeline(svc, ctx) {
         };
         result.unfilteredSummary = unfilteredSummary;
     }
-    if (input.warningCategoryFilter && input.warningCategoryFilter.length > 0) {
+    // Recompute the outcome as the severity/uncertainty filters above leave it
+    // (a no-op when neither minSeverity nor hideUncertain was set), BEFORE any
+    // category filtering narrows things further. This is the baseline a
+    // warningCategoryFilter must reproduce exactly: valid, validationStatus and
+    // quickSummary must come out identical with or without the category
+    // filter, and retry eligibility must be decided from this same
+    // pre-category-filter issue list (see work items: warningCategoryFilter
+    // must not report a target-not-found mixin as valid:true, and must not
+    // change maven-first retry eligibility).
+    refreshMixinValidationOutcome(result);
+    const issuesForRetryEligibility = result.issues;
+    const preCategoryFilterValid = result.valid;
+    const preCategoryFilterValidationStatus = result.validationStatus;
+    const preCategoryFilterQuickSummary = result.quickSummary;
+    const categoryFilterApplied = !!(input.warningCategoryFilter && input.warningCategoryFilter.length > 0);
+    if (categoryFilterApplied) {
+        if (!result.unfilteredSummary) {
+            result.unfilteredSummary = { ...result.summary };
+        }
         const allowedCategories = new Set(input.warningCategoryFilter);
         result.issues = result.issues.filter((i) => i.category && allowedCategories.has(i.category));
         if (result.structuredWarnings) {
@@ -540,7 +576,15 @@ async function finalizeValidateMixinPipeline(svc, ctx) {
     else {
         refreshMixinValidationOutcome(result);
     }
-    if (shouldRetryValidateMixinWithMavenFirst(svc, input, result)) {
+    if (categoryFilterApplied) {
+        // refreshMixinValidationOutcome above recomputed valid/validationStatus/
+        // quickSummary from the category-filtered summary; restore the true
+        // (pre-category-filter) verdict now that member-count bookkeeping is done.
+        result.valid = preCategoryFilterValid;
+        result.validationStatus = preCategoryFilterValidationStatus;
+        result.quickSummary = preCategoryFilterQuickSummary;
+    }
+    if (shouldRetryValidateMixinWithMavenFirst(svc, input, result, issuesForRetryEligibility)) {
         const retryWarning = `Retrying validate-mixin with sourcePriority="maven-first" after partial validation using "${currentSourcePriority}".`;
         try {
             const retried = await svc.validateMixinSingle({
@@ -588,10 +632,10 @@ async function resolveMixinConfigSources(input) {
     const warnings = [];
     for (const rawConfigPath of input.input.configPaths) {
         const resolvedConfigPath = resolveMixinInputPath(rawConfigPath, "configPath");
-        let configJson;
+        let parsedConfig;
         try {
             const raw = await readFile(resolvedConfigPath, "utf-8");
-            configJson = JSON.parse(raw);
+            parsedConfig = JSON.parse(raw);
         }
         catch (err) {
             throw createError({
@@ -600,6 +644,44 @@ async function resolveMixinConfigSources(input) {
                 details: { failedStage: "input-validation" }
             });
         }
+        if (parsedConfig === null || typeof parsedConfig !== "object" || Array.isArray(parsedConfig)) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Mixin config "${rawConfigPath}" must contain a JSON object.`,
+                details: { failedStage: "input-validation" }
+            });
+        }
+        const configRecord = parsedConfig;
+        for (const key of ["mixins", "client", "server"]) {
+            const fieldValue = configRecord[key];
+            if (fieldValue === undefined) {
+                continue;
+            }
+            if (!Array.isArray(fieldValue)) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Mixin config "${rawConfigPath}" field "${key}" must be an array of class names.`,
+                    details: { failedStage: "input-validation" }
+                });
+            }
+            for (let i = 0; i < fieldValue.length; i++) {
+                if (typeof fieldValue[i] !== "string") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: `Mixin config "${rawConfigPath}" field "${key}" element at index ${i} must be a string.`,
+                        details: { failedStage: "input-validation" }
+                    });
+                }
+            }
+        }
+        if (configRecord.package !== undefined && typeof configRecord.package !== "string") {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Mixin config "${rawConfigPath}" field "package" must be a string.`,
+                details: { failedStage: "input-validation" }
+            });
+        }
+        const configJson = configRecord;
         const pkg = configJson.package ?? "";
         const classNames = [
             ...(configJson.mixins ?? []),
@@ -622,10 +704,13 @@ async function resolveMixinConfigSources(input) {
             for (const candidateRoot of COMMON_SOURCE_ROOTS) {
                 let foundInRoot = false;
                 for (const className of classNames) {
-                    const fqcn = pkg ? `${pkg}.${className}` : className;
-                    const relative = fqcn.replace(/\./g, "/") + ".java";
-                    if (await pathExists(resolvePath(projectBase, candidateRoot, relative))) {
-                        foundInRoot = true;
+                    for (const candidate of configEntrySourceCandidates(pkg, className)) {
+                        if (await pathExists(resolvePath(projectBase, candidateRoot, candidate.relativePath))) {
+                            foundInRoot = true;
+                            break;
+                        }
+                    }
+                    if (foundInRoot) {
                         break;
                     }
                 }
@@ -636,19 +721,27 @@ async function resolveMixinConfigSources(input) {
             sourceRootCandidates = detected.length > 0 ? detected : ["src/main/java"];
         }
         for (const cls of classNames) {
-            const fqcn = pkg ? `${pkg}.${cls}` : cls;
-            const relativePath = fqcn.replace(/\./g, "/") + ".java";
-            let sourcePath = resolvePath(projectBase, sourceRootCandidates[0], relativePath);
-            for (const root of sourceRootCandidates) {
-                const candidate = resolvePath(projectBase, root, relativePath);
-                if (await pathExists(candidate)) {
-                    sourcePath = candidate;
+            // The entry's own file wins; a `$`-qualified entry without one is a nested class
+            // validated inside its outer file. An entry found nowhere keeps its own path.
+            const candidates = configEntrySourceCandidates(pkg, cls);
+            let resolved;
+            for (const candidate of candidates) {
+                for (const root of sourceRootCandidates) {
+                    const sourcePath = resolvePath(projectBase, root, candidate.relativePath);
+                    if (await pathExists(sourcePath)) {
+                        resolved = { sourcePath, nestedClassPath: candidate.nestedClassPath };
+                        break;
+                    }
+                }
+                if (resolved) {
                     break;
                 }
             }
             results.push({
-                sourcePath,
-                configPath: resolvedConfigPath
+                sourcePath: resolved?.sourcePath ?? resolvePath(projectBase, sourceRootCandidates[0], candidates[0].relativePath),
+                configPath: resolvedConfigPath,
+                nestedClassPath: resolved?.nestedClassPath,
+                entry: cls
             });
         }
     }
@@ -657,6 +750,27 @@ async function resolveMixinConfigSources(input) {
         warnings
     };
 }
+/**
+ * Source files a mixins-config entry may live in, in lookup order, each with the simple-name path
+ * of the entry's class inside it: the entry's own file (a one-element path, so nested mixins in
+ * that file are left to their own entries), then for a nested entry (`Outer$Inner`,
+ * `Outer$Mid$Inner`) the outer class's file.
+ */
+function configEntrySourceCandidates(pkg, cls) {
+    const fqcn = pkg ? `${pkg}.${cls}` : cls;
+    const lastDot = fqcn.lastIndexOf(".");
+    const candidates = [
+        { relativePath: fqcn.replace(/\./g, "/") + ".java", nestedClassPath: [fqcn.slice(lastDot + 1)] }
+    ];
+    const classPath = fqcn.slice(lastDot + 1).split("$");
+    if (classPath.length > 1 && classPath.every((name) => name !== "")) {
+        candidates.push({
+            relativePath: `${fqcn.slice(0, lastDot + 1).replace(/\./g, "/")}${classPath[0]}.java`,
+            nestedClassPath: classPath
+        });
+    }
+    return candidates;
+}
 async function validateMixinMany(svc, mode, entries, input, additionalWarnings, extras = {}) {
     const results = [];
     const batchWarningMode = input.warningMode ?? "aggregated";
@@ -670,6 +784,7 @@ async function validateMixinMany(svc, mode, entries, input, additionalWarnings,
             const singleResult = await svc.validateMixinSingle({
                 ...sharedInput,
                 sourcePath: entry.sourcePath,
+                nestedClassPath: entry.nestedClassPath,
                 warningMode: batchWarningMode,
                 batchCaches,
                 stageEmitter,

package/dist/source/workspace-target.js

@@ -1,15 +1,39 @@
+import { resolve as resolvePath } from "node:path";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError } from "../errors.js";
+import { normalizeOptionalProjectPath } from "../gradle-paths.js";
 import { describeSafeMavenSegmentRule, isSafeMavenSegment } from "../maven-token.js";
+import { computeWorkspaceContextFingerprint } from "../workspace-context-cache.js";
 import { normalizeMapping } from "./shared-utils.js";
 // Env toggles are read at call time, not at module load: tests dynamically
 // re-import source-service.ts with a cache-busting query to flip the flag,
 // but cannot bust this module's cache through that path.
+/**
+ * The root-level files `detectProjectMinecraftVersion`/`detectCompileMapping`/
+ * `detectProjectLoader` (src/workspace-mapping-service.ts) are guaranteed to
+ * read (or attempt to read) for every project, independent of what detection
+ * finds: `gradle.properties` by exact path, and `build.gradle`/`build.gradle.kts`
+ * by exact path as the first two entries of the build-script glob those two
+ * methods both run before descending into subdirectories. `settings.gradle(.kts)`
+ * and `libs.versions.toml` are not read by any of the three, so they are not
+ * listed here - see the coverage note on `fingerprintPaths` below.
+ */
+function fixedDetectionFilenames() {
+    return ["gradle.properties", "build.gradle", "build.gradle.kts"];
+}
 export async function loadOrDetectWorkspaceContext(svc, projectPath) {
     const cached = svc.workspaceContextCache.read(projectPath);
     if (cached && !cached.partial) {
         return cached;
     }
+    const projectRoot = resolvePath(projectPath);
+    // Snapshotted BEFORE detection runs, not after: an edit that lands while
+    // detection is mid-read (racing the very call below) must still show up as
+    // a stat difference on the next read. Fingerprinting after detection would
+    // record whatever is on disk at that later point - which could already be
+    // the edit that should have invalidated the entry, silently absorbing the
+    // race into a "the cache is fresh" fingerprint instead of catching it.
+    const fixedFingerprint = computeWorkspaceContextFingerprint(fixedDetectionFilenames().map((filename) => resolvePath(projectRoot, filename)));
     const [minecraftVersion, mappingResult, loaderResult] = await Promise.all([
         svc.workspaceMappingService.detectProjectMinecraftVersion(projectPath),
         svc.workspaceMappingService.detectCompileMapping({ projectPath }).catch(() => undefined),
@@ -38,6 +62,39 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         });
     }
     const latest = svc.workspaceContextCache.read(projectPath);
+    // Fingerprint the files this detection actually read (or, for the fixed
+    // root set above, attempted to read regardless of outcome), so a later
+    // cache hit can catch an edit made within the TTL instead of serving a
+    // stale minecraftVersion/mapping/loader for up to five more minutes.
+    //
+    // Coverage: `fixedFingerprint` above (taken pre-detection) covers
+    // gradle.properties and a root-level build.gradle/build.gradle.kts,
+    // present or not - editing, creating, or deleting any of those three
+    // always invalidates. mapping/loader detection also globs subproject
+    // build scripts (`**/build.gradle(.kts)`) and, for the loader, mod
+    // descriptor files (`fabric.mod.json`, `quilt.mod.json`,
+    // `META-INF/{mods,neoforge.mods}.toml`) anywhere under the project; only
+    // the ones that actually produced a mapping/loader declaration are known
+    // here (as `evidence[].filePath`) and fingerprinted below. A subproject
+    // build script or descriptor that was scanned but declared nothing is NOT
+    // covered - editing one to newly declare a mapping/loader is not caught
+    // until the TTL expires, same as before this fingerprint existed.
+    // settings.gradle(.kts) and libs.versions.toml are not read by detection
+    // at all, so they are never fingerprinted.
+    const fixedPaths = new Set(fixedFingerprint.map((entry) => entry.path));
+    const evidencePaths = [
+        ...(mappingResult?.evidence.map((entry) => entry.filePath) ?? []),
+        ...(loaderResult?.evidence.map((entry) => entry.filePath) ?? [])
+    ].filter((path) => !fixedPaths.has(resolvePath(path)));
+    const fingerprint = [
+        ...fixedFingerprint,
+        // A path already covered by fixedFingerprint above (taken pre-detection)
+        // is skipped here rather than re-stat-ed post-detection: keeping only
+        // the earlier snapshot is what makes that entry catch a mid-detection
+        // race at all, and a second, later entry for the same path would just
+        // add a redundant stat on every read without changing the result.
+        ...computeWorkspaceContextFingerprint(evidencePaths)
+    ];
     const ctx = {
         projectPath,
         minecraftVersion,
@@ -46,7 +103,8 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         detectedAt: Date.now(),
         evidence,
         dependencyVersions: latest?.dependencyVersions ?? cached?.dependencyVersions ?? new Map(),
-        partial: false
+        partial: false,
+        fingerprint
     };
     svc.workspaceContextCache.write(ctx);
     return ctx;
@@ -61,7 +119,11 @@ export async function synthesizeWorkspaceTarget(svc, input, workspace) {
             }
         });
     }
-    const projectPath = input.projectPath?.trim();
+    // Normalized once, here, and used for everything below: the workspace-context
+    // cache key, the detection reads and the provenance all have to name the same
+    // path. Trimming alone left a Windows-spelled path unreadable on a WSL host
+    // for this target kind while the sibling routes resolved it.
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
@@ -86,10 +148,16 @@ export async function synthesizeWorkspaceTarget(svc, input, workspace) {
                 nextAction: "Set minecraft_version in gradle.properties or pass target.kind=\"version\" with an explicit Minecraft version.",
                 ...buildSuggestedCall({
                     tool: "resolve-artifact",
-                    params: {
-                        target: { kind: "version", value: "<your-mc-version>" },
-                        projectPath
-                    }
+                    params: undefined,
+                    examples: [
+                        {
+                            params: {
+                                target: { kind: "version", value: "<your-mc-version>" },
+                                projectPath
+                            },
+                            reason: "Replace <your-mc-version> with the Minecraft version, or set minecraft_version in gradle.properties."
+                        }
+                    ]
                 })
             }
         });
@@ -226,7 +294,7 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             }
         });
     }
-    const projectPath = input.projectPath?.trim();
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,

package/dist/source-jar-reader.d.ts

@@ -142,6 +142,20 @@ export interface JarEntryBuffer {
 export interface JarReaderOpenDeps {
     openZipFile?: (jarPath: string) => Promise<ZipFile>;
 }
+export interface CollectMatchedJarEntriesAsBuffersOptions extends CollectMatchedJarEntriesOptions {
+    /**
+     * Checked only after an entry has been SUCCESSFULLY read and pushed onto the
+     * result (the success path), with the result array so far; returning true
+     * stops the walk immediately, alongside `maxEntries` (whichever triggers
+     * first). Unlike a predicate — which runs before a read is even attempted —
+     * this lets a caller implement a stop condition that depends on which reads
+     * actually succeeded, e.g. "stop once every distinct wanted name has at
+     * least one successful read", so one unreadable copy of a duplicate-named
+     * entry (with `continueOnError: true`) does not block a later readable copy
+     * of the same name from ever being tried.
+     */
+    stopWhen?: (collected: readonly JarEntryBuffer[]) => boolean;
+}
 /**
  * Raw-buffer counterpart of {@link collectMatchedJarEntriesAsUtf8}: opens the jar
  * ONCE and returns the matched entries as raw Buffers (no UTF-8 decode), so binary
@@ -149,7 +163,7 @@ export interface JarReaderOpenDeps {
  * sampled entry. Mirrors the sibling's maxBytes/maxEntries/continueOnError semantics
  * and its finally-close, but takes an injectable open seam for open-count assertions.
  */
-export declare function collectMatchedJarEntriesAsBuffers(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesOptions, deps?: JarReaderOpenDeps): Promise<JarEntryBuffer[]>;
+export declare function collectMatchedJarEntriesAsBuffers(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesAsBuffersOptions, deps?: JarReaderOpenDeps): Promise<JarEntryBuffer[]>;
 export declare function iterateJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): AsyncGenerator<JavaEntryText>;
 export declare function readAllJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): Promise<JavaEntryText[]>;
 export declare function detectFabricLikeInputNamespace(inputJar: string, deps?: JarReaderOpenDeps): Promise<{

package/dist/source-jar-reader.js

@@ -497,6 +497,9 @@ export async function collectMatchedJarEntriesAsBuffers(jarPath, predicate, opti
                 if (maxEntries != null && entries.length >= maxEntries) {
                     return entries;
                 }
+                if (options.stopWhen?.(entries)) {
+                    return entries;
+                }
             }
             catch (error) {
                 if (!options.continueOnError) {
@@ -582,12 +585,41 @@ export async function detectFabricLikeInputNamespace(inputJar, deps = {}) {
     }
     // Read all sampled class entries in a SINGLE jar open instead of re-opening the
     // jar once per entry. The sample set and latin1 decode are unchanged, so scores —
-    // and therefore the detected namespace — are identical.
+    // and therefore the detected namespace — are identical. The walk stops as soon
+    // as every sampled entry has been found instead of always scanning the rest of
+    // the jar.
+    //
+    // The predicate only checks name membership (not distinctness), so a readable
+    // duplicate-named entry can still be pushed. Stopping is instead driven by
+    // `stopWhen`, which runs only in the SUCCESS path (after a read has actually
+    // completed) and tracks distinct COLLECTED names there — not in the predicate,
+    // which runs before a read is attempted. A predicate-based dedup would mark a
+    // name "collected" optimistically before knowing whether its read succeeds; if
+    // the first copy of a duplicate name is unreadable (with `continueOnError:
+    // true`), that would permanently block a later, readable copy of the same name
+    // from ever being tried. The walk still stops once every distinct sampled name
+    // has at least one successful read, or the jar is exhausted.
     const sampleSet = new Set(classEntries);
-    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), { continueOnError: true }, deps);
+    const collectedNames = new Set();
+    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), {
+        continueOnError: true,
+        stopWhen: (collected) => {
+            collectedNames.add(collected[collected.length - 1].filePath);
+            return collectedNames.size >= sampleSet.size;
+        }
+    }, deps);
+    // A readable duplicate of an already-collected name can still have been
+    // pushed above (the predicate does not dedupe); keep only the first
+    // successfully-read copy of each distinct name so each sampled class
+    // contributes to the score exactly once.
+    const seenForScoring = new Set();
     let mojangScore = 0;
     let intermediaryScore = 0;
-    for (const { content } of matched) {
+    for (const { filePath, content } of matched) {
+        if (seenForScoring.has(filePath)) {
+            continue;
+        }
+        seenForScoring.add(filePath);
         const text = content.toString("latin1");
         mojangScore += countMatches(text, /net\/minecraft\/(?:advancements|client|commands|core|data|gametest|nbt|network|recipe|resources|server|sounds|stats|tags|util|world)\//g) * 3;
         intermediaryScore += countMatches(text, /net\/minecraft\/class_\d+/g) * 3;

package/dist/source-resolver.js

@@ -1,8 +1,8 @@
 import { readdir } from "node:fs/promises";
 import { basename, dirname, join, resolve as resolvePath, sep } from "node:path";
-import { homedir } from "node:os";
 import fastGlob from "fast-glob";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
+import { resolveGradleUserHomePath } from "./gradle-paths.js";
 import { buildRemoteBinaryUrls, buildRemoteSourceUrls, groupToPath, hasExistingJar, isMutableMavenCoordinate, parseCoordinate, normalizedCoordinateValue } from "./maven-resolver.js";
 import { defaultDownloadPath, discardCachedDownload, resolveCachedDownload } from "./repo-downloader.js";
 import { normalizeJarPath } from "./path-resolver.js";
@@ -344,16 +344,9 @@ async function firstReadableJarArchive(candidates) {
     }
     return undefined;
 }
-function resolveGradleUserHome() {
-    const configured = process.env.GRADLE_USER_HOME?.trim();
-    if (configured) {
-        return configured;
-    }
-    return resolvePath(homedir(), ".gradle");
-}
 async function resolveGradleCacheCoordinateCandidate(coordinate) {
     const parsed = parseCoordinate(coordinate);
-    const baseDir = resolvePath(resolveGradleUserHome(), "caches", "modules-2", "files-2.1", parsed.groupId, parsed.artifactId, parsed.version);
+    const baseDir = resolvePath(resolveGradleUserHomePath(), "caches", "modules-2", "files-2.1", parsed.groupId, parsed.artifactId, parsed.version);
     const base = `${parsed.artifactId}-${parsed.version}`;
     const classifierSuffix = parsed.classifier ? `-${parsed.classifier}` : "";
     const preferredSourceNames = [

package/dist/stdio-supervisor.d.ts

@@ -204,6 +204,15 @@ export declare class StdioSupervisor {
     private readonly unresolvedTreeTokens;
     private readonly restartBackoff;
     private readonly terminalChildren;
+    /**
+     * Workers started by the DEFAULT spawner on POSIX, which spawns them
+     * detached — so each one leads its own process group and `-pid` names
+     * exactly that group. Only these are group-signalled after an unexpected
+     * exit: a child handed in by an injected spawner carries no such guarantee,
+     * and its pid may not be a group id this supervisor owns.
+     */
+    private readonly processGroupLeaders;
+    private readonly spawnsProcessGroupLeaders;
     /**
      * Monotonic worker-generation counter (incremented per successful spawn).
      * Recorded into finality tombstones so retention can be bounded per
@@ -310,7 +319,8 @@ export declare class StdioSupervisor {
      * Number of queued requests that arrived before an initial initialize while
      * the worker was unavailable. Only era-neutral modern discovers can occupy
      * this prefix; readiness forwards it before initialize, then keeps the queue
-     * suffix gated until the initialization response.
+     * suffix gated until the initialization response. A RE-initialize (the era
+     * is already legacy) has no prefix at all: nothing queued may overtake it.
      */
     private initializePredecessorCount;
     private clientInitialized;
@@ -739,6 +749,30 @@ export declare class StdioSupervisor {
     private adoptActiveChild;
     private invalidateCurrentChild;
     private detachCurrentChild;
+    /**
+     * Signals the process group of a worker that exited UNEXPECTEDLY, so the
+     * descendants it leaves behind (a Java grandchild above all) are not
+     * orphaned.
+     *
+     * PID reuse: this runs from the worker's `exit` event, after the worker
+     * itself was reaped, so its pid is free again. The kernel still refuses to
+     * hand that number out as a new pid or pgid while ANY member of the old
+     * group is alive — so while there is something left to reap, `-pid` names
+     * exactly that group. The residual race (the group already empty AND the
+     * number reused by a new group leader in between) is accepted as negligible.
+     * pidfd-based group signalling would close it but needs Linux 6.9+.
+     *
+     * Fire-and-forget by design: it is not recorded as an in-flight cleanup, so
+     * it never occupies a live-generation slot or delays the replacement.
+     *
+     * Windows: `taskkill /T` walks the tree from its root, and the root has
+     * already exited here, so there is nothing it can find. Descendants of a
+     * crashed worker are not reaped on Windows (known limitation).
+     *
+     * Logged `result`: "signalled" (the group had members and was signalled),
+     * "group-empty" (ESRCH — nothing was left), or "failed".
+     */
+    private reapExitedWorkerGroup;
     private recoverTimedOutWorker;
     private beginTreeTermination;
     private finishTreeTermination;