@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

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 {};

package/dist/source-jar-reader.js

@@ -3,6 +3,15 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
 import { isSecureJarEntryPath } from "./path-resolver.js";
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+// Test-only instrumentation: counts real jar opens at the single openZipFile
+// chokepoint so perf tests can assert N-opens-per-call collapses to 1.
+let zipOpenCount = 0;
+export function __getZipOpenCount() {
+    return zipOpenCount;
+}
+export function __resetZipOpenCount() {
+    zipOpenCount = 0;
+}
 function toErrorMessage(value) {
     if (value instanceof Error) {
         return value.message;
@@ -23,7 +32,7 @@ export function hasJavaSourceExtension(entryPath) {
     }
     return true;
 }
-function openZipFile(jarPath) {
+export function openZipFile(jarPath) {
     return new Promise((resolve, reject) => {
         yauzl.open(jarPath, {
             lazyEntries: true,
@@ -33,6 +42,7 @@ function openZipFile(jarPath) {
                 reject(new Error(`Failed to read jar "${jarPath}": ${toErrorMessage(error)}`));
                 return;
             }
+            zipOpenCount += 1;
             resolve(zipFile);
         });
     });
@@ -193,6 +203,66 @@ export async function readJarEntryAsBuffer(jarPath, entryPath) {
         }
     });
 }
+/**
+ * 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 async function createJarEntryReader(jarPath) {
+    const zipFile = await openZipFile(jarPath);
+    let closed = false;
+    const index = new Map();
+    try {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!index.has(entry.fileName)) {
+                index.set(entry.fileName, entry);
+            }
+        }
+    }
+    catch (error) {
+        zipFile.close();
+        throw error;
+    }
+    return {
+        async getEntryBuffer(entryPath) {
+            const normalizedTargetPath = entryPath.replaceAll("\\", "/");
+            if (!isSecureJarEntryPath(normalizedTargetPath)) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Entry path "${normalizedTargetPath}" is not allowed.`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            const entry = index.get(normalizedTargetPath);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            return readEntryStream(zipFile, entry, jarPath);
+        },
+        close() {
+            if (!closed) {
+                closed = true;
+                zipFile.close();
+            }
+        }
+    };
+}
 export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options = {}) {
     return withZipFile(jarPath, async (zipFile) => {
         const entries = [];
@@ -226,6 +296,48 @@ export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options
         }
     });
 }
+/**
+ * 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 async function collectMatchedJarEntriesAsBuffers(jarPath, predicate, options = {}, deps = {}) {
+    const open = deps.openZipFile ?? openZipFile;
+    const zipFile = await open(jarPath);
+    try {
+        const entries = [];
+        const maxEntries = options.maxEntries == null ? undefined : Math.max(1, Math.trunc(options.maxEntries));
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                return entries;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!predicate(entry.fileName)) {
+                continue;
+            }
+            try {
+                const contentBuffer = await readEntryStream(zipFile, entry, jarPath, options.maxBytes);
+                entries.push({ filePath: entry.fileName, content: contentBuffer });
+                if (maxEntries != null && entries.length >= maxEntries) {
+                    return entries;
+                }
+            }
+            catch (error) {
+                if (!options.continueOnError) {
+                    throw error;
+                }
+            }
+        }
+    }
+    finally {
+        zipFile.close();
+    }
+}
 export async function* iterateJavaEntriesAsUtf8(jarPath, maxBytes) {
     const zipFile = await openZipFile(jarPath);
     try {
@@ -285,7 +397,7 @@ function countMatches(input, pattern) {
     }
     return count;
 }
-export async function detectFabricLikeInputNamespace(inputJar) {
+export async function detectFabricLikeInputNamespace(inputJar, deps = {}) {
     const warnings = [];
     const classEntries = (await listJarEntries(inputJar))
         .filter((entry) => entry.endsWith(".class"))
@@ -297,16 +409,15 @@ export async function detectFabricLikeInputNamespace(inputJar) {
             warnings
         };
     }
+    // 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.
+    const sampleSet = new Set(classEntries);
+    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), { continueOnError: true }, deps);
     let mojangScore = 0;
     let intermediaryScore = 0;
-    for (const entry of classEntries) {
-        let text = "";
-        try {
-            text = (await readJarEntryAsBuffer(inputJar, entry)).toString("latin1");
-        }
-        catch {
-            continue;
-        }
+    for (const { content } of matched) {
+        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;
         intermediaryScore += countMatches(text, /\b(?:method|field)_\d+\b/g);

package/dist/source-service.d.ts

@@ -11,6 +11,7 @@ import * as indexer from "./source/indexer.js";
 import * as workspaceTarget from "./source/workspace-target.js";
 import * as validateMixinModule from "./source/validate-mixin.js";
 import * as artifactResolver from "./source/artifact-resolver.js";
+import type { WireMembersBlock } from "./source/class-source/members-builder.js";
 import { type StageEmitter } from "./stage-emitter.js";
 import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
@@ -30,7 +31,8 @@ export type ResolveArtifactInput = {
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
-    compact?: boolean;
+    /** When true, compute the optional `sampleEntries` listing (detail=full / include=samples). */
+    includeSampleEntries?: boolean;
 };
 export type ResolveArtifactOutput = {
     artifactId: string;
@@ -112,6 +114,8 @@ export type SearchClassSourceInput = {
 export type SearchClassSourceOutput = {
     hits: SearchSourceHit[];
     nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored (results restart from page one). */
+    cursorIgnored?: boolean;
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
@@ -205,6 +209,10 @@ export type GetClassSourceOutput = {
     };
     truncated: boolean;
     charsTruncated?: boolean;
+    /** True when startLine begins past EOF; the returned range is empty (not clamped). */
+    outOfRange?: boolean;
+    /** First not-yet-returned line when truncated; pass back as startLine to continue. */
+    nextStartLine?: number;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
     requestedMapping: SourceMapping;
@@ -213,6 +221,11 @@ export type GetClassSourceOutput = {
     provenance: ArtifactProvenance;
     qualityFlags: string[];
     artifactContents: ArtifactContentsSummary;
+    /** Replayable get-class-source call that reads from nextStartLine (truncated, non-file output only). */
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
     outputFile?: string;
     warnings: string[];
 };
@@ -245,11 +258,14 @@ export type GetClassMembersInput = {
     includeInherited?: boolean;
     memberPattern?: string;
     maxMembers?: number;
+    cursor?: string;
     projectPath?: string;
     gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
+    /** When true, keep jvmDescriptor on FIELD members (always kept on methods/constructors). */
+    includeDescriptors?: boolean;
 };
 export type DecompiledMember = {
     name: string;
@@ -265,11 +281,7 @@ export type DecompiledFallback = {
 export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
-    members: {
-        constructors: SignatureMember[];
-        fields: SignatureMember[];
-        methods: SignatureMember[];
-    };
+    members: WireMembersBlock;
     counts: {
         constructors: number;
         fields: number;
@@ -277,6 +289,10 @@ export type GetClassMembersOutput = {
         total: number;
     };
     truncated: boolean;
+    /** Continuation cursor when more members remain; pass back as cursor to fetch the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     context: ExplorerResponseContext;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
@@ -420,7 +436,12 @@ export type ValidateMixinInput = {
         path: string;
     };
     sourceRoots?: string[];
-    version: string;
+    /**
+     * Optional when input.mode='project', or preferProjectVersion=true with a
+     * projectPath set: the dispatcher detects the Minecraft version from
+     * gradle.properties before any version-dependent stage runs.
+     */
+    version?: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     scope?: ArtifactScope;