@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

package/dist/source/class-source.js

@@ -5,7 +5,8 @@ import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import * as artifactResolver from "./artifact-resolver.js";
 import * as classSourceHelpers from "./class-source-helpers.js";
 import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
-import { remapAndCountMembers, sliceMembersWithLimit } from "./class-source/members-builder.js";
+import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire } from "./class-source/members-builder.js";
+import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 const MEMBERS_STATUS_LEGACY = process.env.MEMBERS_STATUS_LEGACY === "1";
 function normalizeStrictPositiveInt(value, field) {
@@ -257,6 +258,9 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
         }
     };
 }
+// The class-like symbol kinds findClass returns. MUST stay in sync with the JS-side
+// isTypeSymbol checks below; pushed down to SQL so non-type rows are never fetched.
+const TYPE_SYMBOL_KINDS = ["class", "interface", "enum", "record"];
 export function findClass(svc, input) {
     const className = input.className.trim();
     if (!className) {
@@ -278,12 +282,20 @@ export function findClass(svc, input) {
     const warnings = [];
     const isQualified = className.includes(".");
     if (isQualified) {
-        const classPath = className.replace(/\./g, "/");
+        // The innermost simple name (handles both dot- and $-separated inner types).
+        const simpleName = className.split(/[.$]/).at(-1) ?? className;
+        const directPath = `${classNameToClassPath(className)}.java`;
+        // The extractor stores ONE (outer) qualifiedName per file, so a nested type's
+        // FQCN never equals any stored qualifiedName and its synthetic file path
+        // (pkg/Outer/Inner.java) does not exist. resolveClassFilePath maps the FQCN —
+        // inner classes included — to the real outer file, which we match on.
+        const resolvedFilePath = resolveClassFilePath(svc, artifactId, className);
         const result = svc.symbolsRepo.findScopedSymbols({
             artifactId,
-            query: className.split(".").at(-1) ?? className,
+            query: simpleName,
             match: "exact",
-            limit: 5000
+            symbolKinds: TYPE_SYMBOL_KINDS,
+            limit: limit * 5
         });
         const matches = result.items
             .filter((row) => {
@@ -292,14 +304,22 @@ export function findClass(svc, input) {
             if (!isTypeSymbol)
                 return false;
             const rowQualified = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
-            return rowQualified === className || row.filePath === `${classPath}.java`;
+            return (rowQualified === className ||
+                row.filePath === directPath ||
+                (resolvedFilePath != null && row.filePath === resolvedFilePath));
+        })
+            .map((row) => {
+            const rowQualified = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+            // For an inner-class match the stored qualifiedName is the outer type; the
+            // caller asked for the full nested FQCN, so report that.
+            const isInnerMatch = rowQualified !== className && row.filePath !== directPath;
+            return {
+                qualifiedName: isInnerMatch ? className : rowQualified,
+                filePath: row.filePath,
+                line: row.line,
+                symbolKind: row.symbolKind
+            };
         })
-            .map((row) => ({
-            qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
-            filePath: row.filePath,
-            line: row.line,
-            symbolKind: row.symbolKind
-        }))
             .slice(0, limit);
         const partialVanillaLookup = hasPartialNetMinecraftCoverage(artifact.qualityFlags) && looksLikeDeobfuscatedClassName(className);
         const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
@@ -317,6 +337,7 @@ export function findClass(svc, input) {
         artifactId,
         query: className,
         match: "exact",
+        symbolKinds: TYPE_SYMBOL_KINDS,
         limit: limit * 5
     });
     const matches = [];
@@ -587,6 +608,27 @@ export async function getClassSource(svc, input) {
             requestedMapping,
             mappingApplied: activeMappingApplied
         });
+    const nextStartLine = snippet.nextStartLine;
+    // Continuation guidance: when output was truncated and was not redirected to
+    // a file, hand the caller the next line to read plus a replayable call that
+    // re-reads from the already-resolved artifact (no re-resolution needed).
+    // nextStartLine is only set for snippet/full mode, so `mode` here is never
+    // "metadata". The caller's original endLine window is preserved so the
+    // continuation never reads past the requested range.
+    const continuation = nextStartLine != null && !resolvedOutputFile
+        ? buildSuggestedCall({
+            tool: "get-class-source",
+            params: {
+                className,
+                target: { kind: "artifact", artifactId: activeArtifactId },
+                mode,
+                startLine: nextStartLine,
+                ...(input.endLine != null ? { endLine: input.endLine } : {}),
+                ...(input.maxLines != null ? { maxLines: input.maxLines } : {}),
+                ...(input.maxChars != null ? { maxChars: input.maxChars } : {})
+            }
+        })
+        : undefined;
     return {
         className,
         mode,
@@ -598,6 +640,8 @@ export async function getClassSource(svc, input) {
         },
         truncated,
         ...(charsTruncated ? { charsTruncated } : {}),
+        ...(snippet.outOfRange ? { outOfRange: true } : {}),
+        ...(nextStartLine != null ? { nextStartLine } : {}),
         origin: activeOrigin,
         artifactId: activeArtifactId,
         requestedMapping,
@@ -611,6 +655,7 @@ export async function getClassSource(svc, input) {
             isDecompiled: activeOrigin === "decompiled",
             qualityFlags: activeQualityFlags
         }),
+        ...(continuation?.suggestedCall ? { suggestedCall: continuation.suggestedCall } : {}),
         ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
         warnings
     };
@@ -629,7 +674,7 @@ export async function getClassMembers(svc, input) {
     const includeInherited = input.includeInherited ?? false;
     const memberPattern = normalizeOptionalString(input.memberPattern);
     const parsedMaxMembers = normalizeStrictPositiveInt(input.maxMembers, "maxMembers");
-    const maxMembers = parsedMaxMembers == null ? 500 : Math.min(parsedMaxMembers, 5000);
+    const maxMembers = parsedMaxMembers == null ? 150 : Math.min(parsedMaxMembers, 5000);
     const normalizedArtifactId = normalizeOptionalString(input.artifactId);
     if (normalizedArtifactId && input.target) {
         throw createError({
@@ -759,7 +804,23 @@ export async function getClassMembers(svc, input) {
     }
     catch (error) {
         if (isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND) {
-            throw error;
+            // Re-raise with the shared recovery shape (find-class/api-matrix
+            // suggestedCall, namespace + scope hints) instead of the sparse bytecode
+            // error, so members and source agree on CLASS_NOT_FOUND guidance.
+            throw buildClassSourceNotFoundError(svc, {
+                artifactId,
+                className,
+                lookupClassName,
+                mappingApplied,
+                requestedMapping,
+                qualityFlags,
+                attemptedBinaryFallback: true,
+                targetKind: input.target?.kind,
+                targetValue: input.target && "value" in input.target ? input.target.value : undefined,
+                scope: input.scope,
+                projectPath: input.projectPath,
+                version
+            });
         }
         binaryExtractionFailed = true;
         binaryExtractionFailureReason = error instanceof Error ? error.message : String(error);
@@ -787,11 +848,29 @@ export async function getClassMembers(svc, input) {
         warnings
     });
     const counts = remapped.counts;
-    const sliced = sliceMembersWithLimit(remapped, counts.total, maxMembers, warnings);
+    // Offset cursor over the flat [constructors, fields, methods] member sequence.
+    // The context key ties a cursor to this exact query so a stale cursor restarts.
+    const memberCursorContext = buildPageContextKey([
+        artifactId,
+        lookupClassName,
+        requestedMapping,
+        mappingApplied,
+        access,
+        includeSynthetic,
+        includeInherited,
+        memberPattern
+    ]);
+    const { offset: memberOffset, cursorIgnored: memberCursorIgnored } = resolveCursorOffset(input.cursor, memberCursorContext);
+    const sliced = sliceMembersWithLimit(remapped, counts.total, maxMembers, warnings, memberOffset);
     const constructors = sliced.constructors;
     const fields = sliced.fields;
     const methods = sliced.methods;
+    // Slim the wire member shape: hoist a shared ownerFqn, drop accessFlags, omit
+    // isSynthetic:false, and drop FIELD jvmDescriptor unless includeDescriptors.
+    // Internal SignatureMember arrays above stay intact.
+    const projectedMembers = projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false);
     const truncated = sliced.truncated;
+    const nextCursor = sliced.nextOffset != null ? encodeOffsetCursor(sliced.nextOffset, memberCursorContext) : undefined;
     const normalizedProvenance = provenance ??
         buildFallbackProvenance(svc, {
             artifactId,
@@ -843,7 +922,7 @@ export async function getClassMembers(svc, input) {
             suggestedCall = buildSuggestedCall({
                 tool: "get-class-source",
                 params: {
-                    target: { type: "artifact", artifactId },
+                    target: { kind: "artifact", artifactId },
                     className,
                     mode: "snippet",
                     mapping: requestedMapping
@@ -861,13 +940,11 @@ export async function getClassMembers(svc, input) {
     }
     return {
         className,
-        members: {
-            constructors,
-            fields,
-            methods
-        },
+        members: projectedMembers,
         counts,
         truncated,
+        ...(nextCursor ? { nextCursor } : {}),
+        ...(memberCursorIgnored ? { cursorIgnored: true } : {}),
         context: signatureContext,
         origin,
         artifactId,

package/dist/source/indexer.js

@@ -43,8 +43,8 @@ export async function indexArtifact(svc, input) {
     }
     const artifact = svc.getArtifact(artifactId);
     const force = input.force ?? false;
-    const hasFiles = svc.filesRepo.listFiles(artifact.artifactId, { limit: 1 }).items.length > 0;
     const meta = svc.indexMetaRepo.get(artifact.artifactId);
+    const hasFiles = meta ? meta.filesCount > 0 : false;
     const expectedSignature = artifact.artifactSignature ?? fallbackArtifactSignature(artifact.artifactId);
     const reason = resolveIndexRebuildReason({
         force,
@@ -291,8 +291,11 @@ export function getArtifact(svc, artifactId) {
 }
 export async function ingestIfNeeded(svc, resolved) {
     const existing = svc.artifactsRepo.getArtifact(resolved.artifactId);
-    const hasFiles = svc.filesRepo.listFiles(resolved.artifactId, { limit: 1 }).items.length > 0;
     const meta = svc.indexMetaRepo.get(resolved.artifactId);
+    // Derive hasFiles from meta instead of a separate listFiles probe: when meta is
+    // absent the reason is "missing_meta" regardless of hasFiles, and when present
+    // meta.filesCount is the authoritative count written alongside the file rows.
+    const hasFiles = meta ? meta.filesCount > 0 : false;
     const reason = resolveIndexRebuildReason({
         force: false,
         expectedSignature: resolved.artifactSignature,

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

@@ -182,6 +182,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) {
@@ -336,6 +341,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 +354,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 +373,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 +400,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 +412,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 +427,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 +547,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)) {
+            if (!passesScope(row.filePath)) {
                 continue;
             }
-            if (glob && !glob.test(row.filePath)) {
-                continue;
+            if (scannedBytes >= byteBudget) {
+                truncated = true;
+                break outer;
             }
-            const contentIndex = match === "regex"
-                ? matchRegexIndex(row.content, regexPattern)
-                : findContentMatchIndex(row.content, query, match);
-            if (contentIndex < 0) {
-                continue;
-            }
-            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);

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

@@ -256,15 +256,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 {};