@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/source/lifecycle/mapping-helpers.js

@@ -25,6 +25,22 @@ function looksLikeClassSegment(name) {
     const trimmed = name.trim();
     return /^[A-Z_$]/.test(trimmed);
 }
+/**
+ * Collapse N per-member remap failures into a single warning line. Preserves the
+ * original "Could not remap" / "Remap failed for" prefix so downstream classifiers
+ * (e.g. REMAP_WARNING_RE in validate-mixin, warningDetails coding) still recognise it,
+ * while bounding the per-member flood to one line plus a short sample of names.
+ */
+function pushAggregatedRemapWarning(warnings, prefix, names, kind, sourceMapping, targetMapping) {
+    if (names.length === 0) {
+        return;
+    }
+    const unique = [...new Set(names)];
+    const sample = unique.slice(0, 3).join(", ");
+    const more = unique.length > 3 ? `, +${unique.length - 3} more` : "";
+    const plural = names.length === 1 ? "" : "s";
+    warnings.push(`${prefix} ${names.length} ${kind}${plural} from ${sourceMapping} to ${targetMapping} (${sample}${more}).`);
+}
 export function rejectLifecycleClassLikeInput(svc, input) {
     void svc;
     if (!looksLikeClassSegment(input.methodName)) {
@@ -234,6 +250,13 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
         "resolveMethodMappingExact" in svc.mappingService &&
         typeof svc.mappingService.resolveMethodMappingExact === "function";
     const memberEntries = [...memberKeyToRemapped.entries()];
+    // Collect per-member remap failures and emit a SINGLE aggregated warning each
+    // after the loop instead of one line per member. On namespace mismatches a large
+    // class can fail to remap every one of its ~150 members, which previously flooded
+    // both warnings[] and the 1:1 warningDetails[] with hundreds of near-identical
+    // lines (the dominant token sink for these responses).
+    const unremappedNames = [];
+    const remapErrorNames = [];
     await Promise.all(memberEntries.map(async ([key, _sourceName]) => {
         const [ownerFqn, name, descriptor] = key.split("\0");
         try {
@@ -299,20 +322,22 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                     }
                 }
                 else {
-                    warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                    unremappedNames.push(name);
                     failedNames.add(name);
                 }
             }
             else {
-                warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                unremappedNames.push(name);
                 failedNames.add(name);
             }
         }
         catch {
-            warnings.push(`Remap failed for ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+            remapErrorNames.push(name);
             failedNames.add(name);
         }
     }));
+    pushAggregatedRemapWarning(warnings, "Could not remap", unremappedNames, kind, sourceMapping, targetMapping);
+    pushAggregatedRemapWarning(warnings, "Remap failed for", remapErrorNames, kind, sourceMapping, targetMapping);
     const isField = kind === "field";
     return {
         members: members.map((member) => {

package/dist/source/lifecycle/runtime-check.js

@@ -1,3 +1,4 @@
+import { ERROR_CODES, isAppError } from "../../errors.js";
 export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbackBase) {
     const version = input.version.trim();
     const name = input.name.trim();
@@ -50,16 +51,25 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         signature = await svc.explorerService.getSignature({
             fqn: targetClass,
             jarPath,
-            access: "all"
+            access: "all",
+            // Method existence is asked relative to the owner type, so inherited methods count:
+            // `level.getGameTime()` exists on Level even though it is declared on a supertype.
+            // Scoped to methods only: fields already resolved correctly without an inheritance
+            // walk, and including inherited fields would let a shadowed field name match twice
+            // and flip a previously-resolved field to "ambiguous".
+            includeInherited: input.kind === "method"
         });
     }
-    catch {
+    catch (error) {
+        const classMissing = isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND;
         return {
             ...fallbackBase,
             querySymbol,
             warnings: [
                 ...fallbackBase.warnings,
-                `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
+                classMissing
+                    ? `Class "${targetClass}" was not found in the Minecraft ${version} runtime jar; it does not exist (or is not in this jar).`
+                    : `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
             ]
         };
     }
@@ -114,9 +124,13 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         });
     }
     const methodCandidates = signature.methods.filter((method) => method.name === name);
-    if (input.signatureMode === "name-only") {
-        if (methodCandidates.length !== 1) {
-            return buildUnresolved(methodCandidates.length > 1 ? "ambiguous" : "not_found");
+    const signatureMode = input.signatureMode ?? "name-only";
+    if (signatureMode === "name-only") {
+        // Existence semantics: any overload with this name means the method exists. Multiple
+        // overloads are not "ambiguous" for a name-only existence check — only zero matches
+        // is not_found. (Use signatureMode: "exact" with a descriptor to pin one overload.)
+        if (methodCandidates.length === 0) {
+            return buildUnresolved("not_found");
         }
         return buildResolved({
             kind: "method",

package/dist/source/search.d.ts

@@ -44,7 +44,7 @@ export declare function searchClassSource(svc: SourceService, input: SearchClass
 export declare function searchSymbolIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
 export declare function searchTextIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
 export declare function searchPathIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
-export declare function searchTextIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchTextIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void, onWarning?: (warning: string) => void): void;
 export declare function searchPathIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
 export declare function findSymbolHits(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined): IndexedSymbolHit[];
 export declare function indexedCandidateLimit(svc: SourceService): number;

package/dist/source/search.js

@@ -65,11 +65,13 @@ export function buildGlobRegex(pattern) {
     while (i < pattern.length) {
         const ch = pattern[i];
         if (ch === "*" && pattern[i + 1] === "*") {
-            result += ".*";
-            i += 2;
-            if (pattern[i] === "/") {
-                result += "(?:/)?";
-                i += 1;
+            if (pattern[i + 2] === "/") {
+                result += "(?:.*/)?";
+                i += 3;
+            }
+            else {
+                result += ".*";
+                i += 2;
             }
         }
         else if (ch === "*") {
@@ -182,6 +184,11 @@ export function findContentMatchIndex(content, query, match, pattern) {
     }
     const normalizedContent = toLower(content);
     const normalizedQuery = toLower(query);
+    // Both "contains" and "prefix" map to a substring search here. For free-text
+    // content, `prefix` is intentionally treated as "contains": file bodies are
+    // searched grep-style and the default match for intent=text resolves to
+    // "prefix" (see normalizeMatch), so anchoring at the start of the file would
+    // yield almost no hits. Symbol/path prefix anchoring lives in findMatchIndex.
     return normalizedContent.indexOf(normalizedQuery);
 }
 export function scoreSymbolMatch(match, index, symbolKind) {
@@ -296,6 +303,9 @@ export async function searchClassSource(svc, input) {
                     searchWarnings.push(`queryNamespace=${input.queryNamespace}: translation failed (${caughtError instanceof Error ? caughtError.message : String(caughtError)}); running literal search instead.`);
                 }
             }
+            else if (intent === "symbol") {
+                searchWarnings.push(`queryNamespace=${input.queryNamespace} requires a fully-qualified class name for translation; running literal search in ${artifactMapping} instead. Resolve "${originalQuery}" to an FQCN with find-class or find-mapping first.`);
+            }
             else if (intent === "text" || intent === "path") {
                 searchWarnings.push(`queryNamespace=${input.queryNamespace} has no effect when intent="${intent}" — ${intent} search is a literal match against the artifact's ${artifactMapping} index. Use intent="symbol" for namespace translation.`);
             }
@@ -336,6 +346,10 @@ export async function searchClassSource(svc, input) {
         });
         const decodedCursor = decodeSearchCursor(input.cursor);
         const cursor = decodedCursor?.contextKey === cursorContext ? decodedCursor : undefined;
+        // A provided cursor that did not decode, or whose context key does not match
+        // this query, is silently dropped and the scan restarts from page one. Flag
+        // it so callers do not assume they are continuing a previous page.
+        const cursorIgnored = input.cursor != null && cursor == null;
         const accumulator = createSearchHitAccumulator(limit, cursor);
         const indexedSearchEnabled = svc.config.indexedSearchEnabled !== false;
         if (match === "regex") {
@@ -345,13 +359,16 @@ export async function searchClassSource(svc, input) {
         const recordHit = (hit) => {
             accumulator.add(hit);
         };
+        const recordWarning = (warning) => {
+            searchWarnings.push(warning);
+        };
         const tokenOnlyTextIntent = intent === "text" && queryMode === "token";
         if (intent === "symbol") {
             searchSymbolIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
         }
         else if (queryMode === "literal" && intent === "text") {
             svc.metrics.recordSearchFallback();
-            searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
+            searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit, recordWarning);
         }
         else if (!indexedSearchEnabled) {
             svc.metrics.recordIndexedDisabled();
@@ -361,7 +378,7 @@ export async function searchClassSource(svc, input) {
                     searchPathIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
                 }
                 else {
-                    searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
+                    searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit, recordWarning);
                 }
             }
         }
@@ -388,7 +405,7 @@ export async function searchClassSource(svc, input) {
                         searchPathIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
                     }
                     else {
-                        searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
+                        searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit, recordWarning);
                     }
                 }
             }
@@ -400,7 +417,7 @@ export async function searchClassSource(svc, input) {
                     searchPathIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
                 }
                 else {
-                    searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
+                    searchTextIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit, recordWarning);
                 }
             }
         }
@@ -415,6 +432,7 @@ export async function searchClassSource(svc, input) {
         return {
             hits: page,
             nextCursor,
+            ...(cursorIgnored ? { cursorIgnored: true } : {}),
             mappingApplied: artifact.mappingApplied ?? "obfuscated",
             returnedNamespace: artifact.mappingApplied ?? "obfuscated",
             artifactContents: svc.buildArtifactContentsSummary({
@@ -534,39 +552,98 @@ export function searchPathIntentIndexed(svc, artifactId, query, match, scope, on
         });
     }
 }
-export function searchTextIntent(svc, artifactId, query, match, scope, regexPattern, onHit) {
-    const pageSize = Math.max(1, svc.config.searchScanPageSize ?? 250);
+const ASCII_RE = /^[\x00-\x7F]*$/;
+/** True when every code unit is ASCII, so SQLite LIKE folds case identically to JS. */
+function isAsciiNeedle(query) {
+    return ASCII_RE.test(query);
+}
+function searchScanBudgetWarning(byteBudget) {
+    return `search scan budget of ${byteBudget} bytes reached; results may be incomplete. Narrow the query or scope (packagePrefix / fileGlob) to scan fewer files.`;
+}
+export function searchTextIntent(svc, artifactId, query, match, scope, regexPattern, onHit, onWarning) {
     const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
+    const byteBudget = Math.max(1, svc.config.searchScanMaxBytes ?? Number.MAX_SAFE_INTEGER);
+    let scannedBytes = 0;
+    let truncated = false;
+    const passesScope = (filePath) => checkPackagePrefix(filePath, scope?.packagePrefix) && (!glob || glob.test(filePath));
+    const emitIfMatch = (filePath, content) => {
+        const contentIndex = match === "regex"
+            ? matchRegexIndex(content, regexPattern)
+            : findContentMatchIndex(content, query, match);
+        if (contentIndex < 0) {
+            return;
+        }
+        onHit({
+            filePath,
+            score: scoreTextMatch(match, contentIndex),
+            matchedIn: "content",
+            reasonCodes: ["content_match", `text_${match}`]
+        });
+    };
+    // FAST PATH: an ASCII, non-regex needle narrows candidates via a content LIKE
+    // prefilter (a proven superset of the JS match), so only matching files are
+    // hydrated instead of scanning the whole corpus. The unchanged JS post-verify in
+    // emitIfMatch removes any over-included rows.
+    if (match !== "regex" && isAsciiNeedle(query)) {
+        const candidateLimit = indexedCandidateLimitForMatch(svc, match);
+        const { filePaths, scannedRows } = svc.filesRepo.searchContentLikeCandidatePaths(artifactId, query, candidateLimit);
+        svc.metrics.recordSearchDbRoundtrip();
+        svc.metrics.recordSearchRowsScanned(scannedRows);
+        // The prefilter caps candidates at candidateLimit ordered by file_path. Below the
+        // cap the candidate set is exhaustive, so the JS post-verify yields exactly the old
+        // full-scan hits. AT the cap more matches may exist beyond the path-ordered cut, and
+        // dropping them would change the scored top-K page and totalApprox/cursor — so fall
+        // through to the exhaustive paged scan below to preserve identical results.
+        if (scannedRows < candidateLimit) {
+            svc.metrics.recordSearchLikePrefilter();
+            const scopedPaths = filePaths.filter(passesScope);
+            const rows = svc.filesRepo.getFileContentsByPaths(artifactId, scopedPaths);
+            svc.metrics.recordSearchDbRoundtrip();
+            svc.metrics.recordSearchRowsScanned(rows.length);
+            for (const row of rows) {
+                if (scannedBytes >= byteBudget) {
+                    truncated = true;
+                    break;
+                }
+                scannedBytes += row.contentBytes;
+                emitIfMatch(row.filePath, row.content);
+            }
+            if (truncated) {
+                svc.metrics.recordSearchScanTruncated();
+                onWarning?.(searchScanBudgetWarning(byteBudget));
+            }
+            return;
+        }
+        // Cap overflow: fall through to the exhaustive scan (rare; only common-token queries).
+    }
+    // SLOW PATH: regex (cannot be pushed to SQL) or non-ASCII needles (SQLite LIKE
+    // would fold case differently than JS) scan the corpus page by page.
+    const pageSize = Math.max(1, svc.config.searchScanPageSize ?? 250);
     let cursor = undefined;
-    while (true) {
+    outer: while (true) {
         const page = svc.filesRepo.listFileRows(artifactId, { limit: pageSize, cursor });
         svc.metrics.recordSearchDbRoundtrip();
         svc.metrics.recordSearchRowsScanned(page.items.length);
         for (const row of page.items) {
-            if (!checkPackagePrefix(row.filePath, scope?.packagePrefix)) {
-                continue;
-            }
-            if (glob && !glob.test(row.filePath)) {
+            if (!passesScope(row.filePath)) {
                 continue;
             }
-            const contentIndex = match === "regex"
-                ? matchRegexIndex(row.content, regexPattern)
-                : findContentMatchIndex(row.content, query, match);
-            if (contentIndex < 0) {
-                continue;
+            if (scannedBytes >= byteBudget) {
+                truncated = true;
+                break outer;
             }
-            onHit({
-                filePath: row.filePath,
-                score: scoreTextMatch(match, contentIndex),
-                matchedIn: "content",
-                reasonCodes: ["content_match", `text_${match}`]
-            });
+            scannedBytes += row.contentBytes;
+            emitIfMatch(row.filePath, row.content);
         }
         if (!page.nextCursor) {
             break;
         }
         cursor = page.nextCursor;
     }
+    if (truncated) {
+        svc.metrics.recordSearchScanTruncated();
+        onWarning?.(searchScanBudgetWarning(byteBudget));
+    }
 }
 export function searchPathIntent(svc, artifactId, query, match, scope, regexPattern, onHit) {
     const pageSize = Math.max(1, svc.config.searchScanPageSize ?? 250);
@@ -604,7 +681,9 @@ export function searchPathIntent(svc, artifactId, query, match, scope, regexPatt
 }
 export function findSymbolHits(svc, artifactId, query, match, scope, regexPattern) {
     if (match !== "regex") {
-        const filePathLike = scope?.fileGlob ? globToSqlLike(normalizePathStyle(scope.fileGlob)) : undefined;
+        const filePathLike = scope?.fileGlob && !scope.fileGlob.includes("**")
+            ? globToSqlLike(normalizePathStyle(scope.fileGlob))
+            : undefined;
         const scoped = svc.symbolsRepo.findScopedSymbols({
             artifactId,
             query,
@@ -616,8 +695,12 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
         });
         svc.metrics.recordSearchDbRoundtrip();
         svc.metrics.recordSearchRowsScanned(scoped.items.length);
+        const globFilter = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
         const result = [];
         for (const symbol of scoped.items) {
+            if (globFilter && !globFilter.test(symbol.filePath)) {
+                continue;
+            }
             if (!isSymbolKind(symbol.symbolKind)) {
                 continue;
             }
@@ -633,12 +716,15 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
         }
         return result;
     }
-    const candidates = svc.symbolsRepo.listSymbolsForArtifact(artifactId, scope?.symbolKind);
+    // Stream rows instead of materializing every symbol: regex scans on large
+    // artifacts only keep matching rows in memory this way.
+    const candidates = svc.symbolsRepo.iterateSymbolsForArtifact(artifactId, scope?.symbolKind);
     svc.metrics.recordSearchDbRoundtrip();
-    svc.metrics.recordSearchRowsScanned(candidates.length);
+    let rowsScanned = 0;
     const result = [];
     const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
     for (const symbol of candidates) {
+        rowsScanned += 1;
         if (!checkPackagePrefix(symbol.filePath, scope?.packagePrefix)) {
             continue;
         }
@@ -660,6 +746,7 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
             matchIndex: index
         });
     }
+    svc.metrics.recordSearchRowsScanned(rowsScanned);
     return result;
 }
 export function indexedCandidateLimit(svc) {

package/dist/source/validate-mixin/pipeline/resolve.js

@@ -40,10 +40,22 @@ export async function runResolveStage(svc, ctx) {
                 scope: ctx.input.scope,
                 preferProjectVersion: false
             });
-            ctx.jarPath = ctx.resolvedArtifact.binaryJarPath ?? (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
             ctx.warnings.push(...ctx.resolvedArtifact.warnings);
-            ctx.mappingApplied = ctx.resolvedArtifact.mappingApplied;
-            ctx.signatureLookupMapping = ctx.resolvedArtifact.mappingApplied;
+            if (ctx.resolvedArtifact.binaryJarPath) {
+                ctx.jarPath = ctx.resolvedArtifact.binaryJarPath;
+                ctx.mappingApplied = ctx.resolvedArtifact.mappingApplied;
+                ctx.signatureLookupMapping = ctx.resolvedArtifact.mappingApplied;
+            }
+            else {
+                ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+                ctx.signatureLookupMapping = "obfuscated";
+                ctx.scopeFallback = {
+                    requested: ctx.input.scope,
+                    applied: "vanilla",
+                    reason: "Resolved artifact had no binary jar (sources only); falling back to vanilla client jar."
+                };
+                ctx.warnings.push(`Scope "${ctx.input.scope}" resolved without a binary jar; falling back to vanilla client jar.`);
+            }
             if (ctx.resolvedArtifact.version) {
                 ctx.version = ctx.resolvedArtifact.version;
             }
@@ -59,6 +71,14 @@ export async function runResolveStage(svc, ctx) {
         }
     }
     else {
+        if (ctx.input.scope && ctx.input.scope !== "vanilla") {
+            ctx.scopeFallback = {
+                requested: ctx.input.scope,
+                applied: "vanilla",
+                reason: "projectPath required for merged/loader scope; falling back to vanilla client jar."
+            };
+            ctx.warnings.push(`Scope "${ctx.input.scope}" requires projectPath; falling back to vanilla client jar.`);
+        }
         ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
     }
     if (ctx.jarPath.includes("-sources.jar")) {

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

@@ -4,7 +4,8 @@ import type { ValidateMixinInput, ValidateMixinOptions, ValidateMixinOutput } fr
 import { type StageEmitter } from "../stage-emitter.js";
 import type { MappingSourcePriority } from "../types.js";
 import type { FindMappingOutput as MappingFindMappingOutput } from "../mapping-service.js";
-export type ValidateMixinSingleInput = Omit<ValidateMixinInput, "input"> & {
+export type ValidateMixinSingleInput = Omit<ValidateMixinInput, "input" | "version"> & {
+    version: string;
     source?: string;
     sourcePath?: string;
     batchCaches?: {

package/dist/source/validate-mixin.js

@@ -159,7 +159,43 @@ export async function validateMixin(svc, input, options = {}) {
         throw annotateValidateMixinError(err, "input-validation");
     }
 }
-async function runValidateMixinDispatcher(svc, input, options = {}) {
+/**
+ * Resolve the Minecraft version for a validate-mixin request. Uses the explicit
+ * `version` when present; otherwise detects it from gradle.properties for
+ * project mode or when preferProjectVersion is set with a projectPath. Throws an
+ * actionable INVALID_INPUT error when no version can be determined.
+ */
+async function resolveRequestedMinecraftVersion(svc, input) {
+    const explicit = input.version?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    const projectPathCandidate = input.projectPath ?? (input.input.mode === "project" ? input.input.path : undefined);
+    if (projectPathCandidate) {
+        const normalizedProjectPath = resolveMixinInputPath(projectPathCandidate, "path");
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
+        if (detected?.trim()) {
+            return detected.trim();
+        }
+    }
+    throw createError({
+        code: ERROR_CODES.INVALID_INPUT,
+        message: "Could not detect a Minecraft version from the project. Pass version explicitly, or ensure gradle.properties declares minecraft_version.",
+        details: {
+            failedStage: "input-validation",
+            nextAction: 'Pass version (e.g. "1.21.10"), or set preferProjectVersion=true with a projectPath whose gradle.properties contains minecraft_version.'
+        }
+    });
+}
+async function runValidateMixinDispatcher(svc, rawInput, options = {}) {
+    const requestedVersion = await resolveRequestedMinecraftVersion(svc, rawInput);
+    // Service-level default so direct/internal/entry-tool callers (not just the MCP
+    // wire boundary, where Zod applies it) get the lean summary-first report shape.
+    const input = {
+        ...rawInput,
+        version: requestedVersion,
+        reportMode: rawInput.reportMode ?? "summary-first"
+    };
     const { input: sourceInput, ...sharedInput } = input;
     const mode = sourceInput.mode;
     const stageEmitter = options.stageEmitter ?? NOOP_STAGE_EMITTER;
@@ -495,7 +531,9 @@ async function finalizeValidateMixinPipeline(svc, ctx) {
         result.aggregatedWarnings = undefined;
         result.toolHealth = undefined;
         result.confidenceBreakdown = undefined;
-        if (result.provenance) {
+        // resolutionTrace only exists when explain=true; keep it then so explain still
+        // delivers the per-issue trace even under the compact report shape.
+        if (result.provenance && input.explain !== true) {
             result.provenance.resolutionTrace = undefined;
         }
     }
@@ -676,6 +714,9 @@ function applyValidateMixinOutputCompaction(output, input) {
         ? true
         : warningCandidates.every((entry) => sameStringArray(entry, warningCandidates[0]));
     if (input.reportMode === "summary-first") {
+        // explain=true keeps the per-result heavy detail (resolvedMembers/toolHealth)
+        // even under summary-first, so the diagnostic opt-in still works.
+        const keepHeavyDetail = input.explain === true;
         nextOutput = {
             ...nextOutput,
             results: nextOutput.results.map((entry) => (entry.result
@@ -686,8 +727,8 @@ function applyValidateMixinOutputCompaction(output, input) {
                         warnings: canHoistWarnings ? [] : entry.result.warnings,
                         structuredWarnings: undefined,
                         aggregatedWarnings: undefined,
-                        resolvedMembers: undefined,
-                        toolHealth: undefined,
+                        resolvedMembers: keepHeavyDetail ? entry.result.resolvedMembers : undefined,
+                        toolHealth: keepHeavyDetail ? entry.result.toolHealth : undefined,
                         confidenceBreakdown: undefined,
                         provenance: canHoistProvenance ? undefined : entry.result.provenance
                     }

package/dist/source/workspace-target.js

@@ -37,6 +37,7 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
             value: loaderResult.loader
         });
     }
+    const latest = svc.workspaceContextCache.read(projectPath);
     const ctx = {
         projectPath,
         minecraftVersion,
@@ -44,7 +45,7 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         loader: loaderResult?.resolved ? loaderResult.loader : undefined,
         detectedAt: Date.now(),
         evidence,
-        dependencyVersions: cached?.dependencyVersions ?? new Map(),
+        dependencyVersions: latest?.dependencyVersions ?? cached?.dependencyVersions ?? new Map(),
         partial: false
     };
     svc.workspaceContextCache.write(ctx);
@@ -256,15 +257,21 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
                 nextAction,
                 ...buildSuggestedCall({
                     tool: "resolve-artifact",
-                    params: {
-                        target: {
-                            kind: "dependency",
-                            group,
-                            name,
-                            version: "<your-version>"
-                        },
-                        projectPath
-                    }
+                    params: undefined,
+                    examples: [
+                        {
+                            params: {
+                                target: {
+                                    kind: "dependency",
+                                    group,
+                                    name,
+                                    version: "<your-version>"
+                                },
+                                projectPath
+                            },
+                            reason: "Replace <your-version> with the dependency version, or declare it in gradle.properties."
+                        }
+                    ]
                 })
             }
         });

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

@@ -1,3 +1,20 @@
+import type { Readable } from "node:stream";
+export declare function __getZipOpenCount(): number;
+export declare function __resetZipOpenCount(): void;
+interface ZipEntry {
+    fileName: string;
+}
+export interface ZipFile {
+    readEntry(): void;
+    close(): void;
+    once(event: "entry", listener: (entry: ZipEntry) => void): this;
+    once(event: "end", listener: () => void): this;
+    once(event: "error", listener: (error: Error) => void): this;
+    removeListener(event: "entry", listener: (entry: ZipEntry) => void): this;
+    removeListener(event: "end", listener: () => void): this;
+    removeListener(event: "error", listener: (error: Error) => void): this;
+    openReadStream(entry: ZipEntry, callback: (error: Error | null, stream: Readable | null) => void): void;
+}
 export interface JavaEntryText {
     filePath: string;
     content: string;
@@ -12,6 +29,7 @@ export interface CollectMatchedJarEntriesOptions {
     continueOnError?: boolean;
 }
 export declare function hasJavaSourceExtension(entryPath: string): boolean;
+export declare function openZipFile(jarPath: string): Promise<ZipFile>;
 export declare class EntryTooLargeError extends Error {
     constructor(entryPath: string, jarPath: string, maxBytes: number);
 }
@@ -20,10 +38,45 @@ export declare function listJavaEntries(jarPath: string): Promise<string[]>;
 export declare function hasAnyJarEntry(jarPath: string, predicate: (entryPath: string) => boolean): Promise<boolean>;
 export declare function readJarEntryAsUtf8(jarPath: string, entryPath: string): Promise<string>;
 export declare function readJarEntryAsBuffer(jarPath: string, entryPath: string): Promise<Buffer>;
+export interface JarEntryReader {
+    getEntryBuffer(entryPath: string): Promise<Buffer>;
+    close(): void;
+}
+/**
+ * Opens a jar ONCE, drains its central directory into a name->entry index, and
+ * serves repeated entry reads via O(1) lookup + openReadStream. Use this when a
+ * single logical operation reads many entries from the same jar (e.g. walking a
+ * class hierarchy) instead of calling {@link readJarEntryAsBuffer} per entry,
+ * which re-opens and re-scans the jar each time. Callers MUST close() the reader
+ * (in a finally) to release the file descriptor. getEntryBuffer throws the same
+ * INVALID_INPUT (unsafe path) / SOURCE_NOT_FOUND (missing entry) errors as
+ * readJarEntryAsBuffer; duplicate entry names resolve to the first occurrence.
+ */
+export declare function createJarEntryReader(jarPath: string): Promise<JarEntryReader>;
 export declare function collectMatchedJarEntriesAsUtf8(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesOptions): Promise<JarEntryText[]>;
+export interface JarEntryBuffer {
+    filePath: string;
+    content: Buffer;
+}
+/**
+ * Seam for injecting the jar-open primitive so callers/tests can count opens.
+ * Defaults to the module-level {@link openZipFile}.
+ */
+export interface JarReaderOpenDeps {
+    openZipFile?: (jarPath: string) => Promise<ZipFile>;
+}
+/**
+ * Raw-buffer counterpart of {@link collectMatchedJarEntriesAsUtf8}: opens the jar
+ * ONCE and returns the matched entries as raw Buffers (no UTF-8 decode), so binary
+ * inputs like `.class` bytes survive intact. Used to avoid re-opening the jar per
+ * 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 iterateJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): AsyncGenerator<JavaEntryText>;
 export declare function readAllJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): Promise<JavaEntryText[]>;
-export declare function detectFabricLikeInputNamespace(inputJar: string): Promise<{
+export declare function detectFabricLikeInputNamespace(inputJar: string, deps?: JarReaderOpenDeps): Promise<{
     fromNamespace: "intermediary" | "mojang";
     warnings: string[];
 }>;
+export {};