@adhisang/minecraft-modding-mcp 6.2.0 → 7.0.0-rc.0

package/dist/source/class-source.js

@@ -8,9 +8,9 @@ import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
 import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
 import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
-import { resolveUniqueNestedJarForClass } from "./nested-jars.js";
+import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
-import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+import { dedupeQualityFlags, inheritArtifactMapping, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 const MEMBERS_STATUS_LEGACY = process.env.MEMBERS_STATUS_LEGACY === "1";
 /**
@@ -82,6 +82,14 @@ function obfuscatedNamespaceHint(className) {
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
+function shouldSuggestObfuscatedMapping(artifact, className) {
+    const nativeDependency = artifact.provenance?.dependencyResolution != null;
+    const shellArtifact = artifact.qualityFlags.includes("shell-jar");
+    return (artifact.mappingApplied === "obfuscated" &&
+        !nativeDependency &&
+        !shellArtifact &&
+        looksLikeDeobfuscatedClassName(className));
+}
 function classNameToClassPath(className) {
     const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
     const segments = normalized.split(".").filter((segment) => segment.length > 0);
@@ -167,10 +175,26 @@ export function buildFallbackProvenance(svc, input) {
         transformChain
     };
 }
+/**
+ * Near-miss candidates from the requested artifact's index followed by any the
+ * lookup's final artifact contributes, deduplicated by FQN so a class present in
+ * both is reported once, under the requested artifact.
+ */
+function unionDidYouMeanCandidates(svc, requestedArtifactId, endedOnArtifactId, className) {
+    const requested = collectDidYouMeanCandidates(svc, requestedArtifactId, className);
+    if (endedOnArtifactId === requestedArtifactId) {
+        return requested;
+    }
+    const seen = new Set(requested.map((candidate) => candidate.className));
+    const fromFallback = collectDidYouMeanCandidates(svc, endedOnArtifactId, className, endedOnArtifactId).filter((candidate) => !seen.has(candidate.className));
+    return [...requested, ...fromFallback];
+}
 export function buildClassSourceNotFoundError(svc, input) {
     const simpleName = input.className.split(/[.$]/).at(-1) ?? input.className;
+    const requestedArtifactId = input.requestedArtifactId ?? input.artifactId;
     const details = {
-        artifactId: input.artifactId,
+        artifactId: requestedArtifactId,
+        ...(input.artifactId !== requestedArtifactId ? { fallbackArtifactId: input.artifactId } : {}),
         className: input.className,
         mapping: input.mappingApplied,
         qualityFlags: input.qualityFlags,
@@ -183,12 +207,18 @@ export function buildClassSourceNotFoundError(svc, input) {
         ...(input.nestedJars && input.nestedJars.length > 0 ? { nestedJars: input.nestedJars } : {}),
         // Candidates are hints from the symbol index, never assertions that the
         // class exists at the suggested location; empty when nothing usable.
-        didYouMean: collectDidYouMeanCandidates(svc, input.artifactId, input.className)
+        //
+        // Both indexes are consulted, requested artifact first. Collecting from the
+        // requested artifact ALONE is empty by construction in the scenario the
+        // partial-source fallback exists to serve: that artifact is the one without
+        // net.minecraft symbols, which is why the fallback fired and indexed the other
+        // jar. Candidates from the artifact the caller did not name carry its id.
+        didYouMean: unionDidYouMeanCandidates(svc, requestedArtifactId, input.artifactId, input.className)
     };
     let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
     let suggestionSpec = {
         tool: "find-class",
-        params: { className: simpleName, artifactId: input.artifactId }
+        params: { className: simpleName, artifactId: requestedArtifactId }
     };
     if (input.targetKind === "version" && input.scope && input.scope !== "merged" && !input.projectPath) {
         nextAction +=
@@ -217,7 +247,7 @@ export function buildClassSourceNotFoundError(svc, input) {
         else {
             suggestionSpec = {
                 tool: "find-class",
-                params: { className: simpleName, artifactId: input.artifactId }
+                params: { className: simpleName, artifactId: requestedArtifactId }
             };
         }
     }
@@ -395,13 +425,14 @@ export function findClass(svc, input) {
         const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
             ? []
             : matches;
-        if (filteredMatches.length === 0 && partialVanillaLookup) {
-            warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
-        }
-        if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
-            warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
-        }
-        return { matches: filteredMatches, total: filteredMatches.length, warnings };
+        return finishFindClass(svc, {
+            artifact,
+            artifactId,
+            className,
+            matches: filteredMatches,
+            partialVanillaLookup,
+            warnings
+        });
     }
     const result = svc.symbolsRepo.findScopedSymbols({
         artifactId,
@@ -410,32 +441,110 @@ export function findClass(svc, input) {
         symbolKinds: TYPE_SYMBOL_KINDS,
         limit: limit * 5
     });
-    const matches = [];
+    // The extractor stores ONE qualifiedName per FILE (the top-level type), so a
+    // nested type's row carries its OUTER type's FQN. Reporting that verbatim
+    // returned a qualifiedName that did not contain the searched token at all —
+    // feeding match[0] into get-class-source then fetched the wrong class.
+    const candidates = [];
     for (const row of result.items) {
-        if (matches.length >= limit)
-            break;
         const isTypeSymbol = row.symbolKind === "class" || row.symbolKind === "interface" ||
             row.symbolKind === "enum" || row.symbolKind === "record";
         if (!isTypeSymbol)
             continue;
-        matches.push({
-            qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
+        const enclosingQualifiedName = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+        const enclosingSimpleName = enclosingQualifiedName.split(".").at(-1) ?? enclosingQualifiedName;
+        const nested = enclosingSimpleName !== row.symbolName;
+        candidates.push({
+            qualifiedName: nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName,
             filePath: row.filePath,
             line: row.line,
-            symbolKind: row.symbolKind
+            symbolKind: row.symbolKind,
+            ...(nested ? { nested: true, enclosingClass: enclosingQualifiedName } : {})
         });
     }
+    // A top-level type named exactly like the query is what the caller almost
+    // always means; a nested type that merely shares the simple name comes after.
+    candidates.sort((left, right) => {
+        const leftNested = left.nested === true ? 1 : 0;
+        const rightNested = right.nested === true ? 1 : 0;
+        if (leftNested !== rightNested)
+            return leftNested - rightNested;
+        return left.qualifiedName.localeCompare(right.qualifiedName);
+    });
+    const matches = candidates.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."))
         ? []
         : matches;
-    if (filteredMatches.length === 0 && partialVanillaLookup) {
+    return finishFindClass(svc, {
+        artifact,
+        artifactId,
+        className,
+        matches: filteredMatches,
+        partialVanillaLookup,
+        warnings
+    });
+}
+/**
+ * Shared tail for both findClass branches: coverage/namespace warnings plus a
+ * machine-usable recovery route.
+ *
+ * An empty result on an artifact whose index excludes net.minecraft is
+ * internally consistent but externally contradictory — get-class-source answers
+ * the SAME class from the binary fallback. The caller therefore gets both the
+ * reason and the exact call that works.
+ */
+function finishFindClass(svc, input) {
+    const { artifact, artifactId, className, matches, partialVanillaLookup, warnings } = input;
+    let suggestedCall;
+    if (matches.length === 0 && partialVanillaLookup) {
         warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
+        suggestedCall = buildSuggestedCall({
+            tool: "get-class-source",
+            params: {
+                className,
+                target: { kind: "artifact", artifactId },
+                mode: "metadata"
+            }
+        }).suggestedCall;
     }
-    if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+    if (matches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
         warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
     }
-    return { matches: filteredMatches, total: filteredMatches.length, warnings };
+    return {
+        matches,
+        total: matches.length,
+        warnings,
+        ...(suggestedCall ? { suggestedCall } : {})
+    };
+}
+export async function findClassIncludingNested(svc, input) {
+    const indexed = findClass(svc, input);
+    if (indexed.total > 0) {
+        return indexed;
+    }
+    const artifact = svc.getArtifact(input.artifactId.trim());
+    const inventory = artifact.provenance?.nestedJars;
+    if (!artifact.qualityFlags.includes("shell-jar") ||
+        !artifact.binaryJarPath ||
+        !inventory ||
+        inventory.length === 0) {
+        return indexed;
+    }
+    const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
+    const matches = await findNestedJarClasses({
+        cacheDir: svc.config.cacheDir,
+        outerJarPath: artifact.binaryJarPath,
+        outerSignature: artifact.artifactId,
+        inventory,
+        className: input.className,
+        limit
+    });
+    return {
+        matches,
+        total: matches.length,
+        warnings: indexed.warnings
+    };
 }
 export async function getClassSource(svc, input) {
     const className = input.className.trim();
@@ -514,7 +623,7 @@ export async function getClassSource(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
-        requestedMapping = input.mapping != null ? requestedMapping : (artifact.requestedMapping ?? requestedMapping);
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -559,7 +668,11 @@ export async function getClassSource(svc, input) {
             requestedMapping,
             mappingApplied,
             provenance: activeProvenance,
-            qualityFlags: activeQualityFlags
+            qualityFlags: activeQualityFlags,
+            // A caller who declined decompilation must not pay for one here: the
+            // fallback used to hardcode allowDecompile:true and silently ran a full
+            // Vineflower pass on the binary jar.
+            allowDecompile: input.allowDecompile
         });
         if (!fallbackResolved || fallbackResolved.artifactId === activeArtifactId) {
             return false;
@@ -653,11 +766,15 @@ export async function getClassSource(svc, input) {
     if (!filePath) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
             attemptedBinaryFallback,
             targetKind: input.target?.kind,
             targetValue: input.target && "value" in input.target ? input.target.value : undefined,
@@ -692,11 +809,15 @@ export async function getClassSource(svc, input) {
     if (!row) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
             attemptedBinaryFallback,
             filePath,
             targetKind: input.target?.kind,
@@ -874,6 +995,7 @@ export async function getClassMembers(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -1143,7 +1265,18 @@ export async function getClassMembers(svc, input) {
         truncated,
         ...(nextCursor ? { nextCursor } : {}),
         ...(memberCursorIgnored ? { cursorIgnored: true } : {}),
-        context: signatureContext,
+        context: {
+            ...signatureContext,
+            // The jar-derived context describes the BYTECODE the reader opened. The
+            // members handed back have already been remapped into requestedMapping,
+            // so echoing the jar namespace here contradicted `returnedNamespace` in
+            // the same payload. Report what the response actually contains, and fill
+            // the version the resolver established when the jar path yielded none.
+            ...(signatureContext.minecraftVersion === "unknown" && version
+                ? { minecraftVersion: version }
+                : {}),
+            mappingNamespace: requestedMapping
+        },
         origin,
         artifactId,
         requestedMapping,

package/dist/source/did-you-mean.d.ts

@@ -2,6 +2,13 @@ import type { SourceService } from "../source-service.js";
 export interface DidYouMeanCandidate {
     className: string;
     matchReason: string;
+    /**
+     * Set only when the candidate was found in an artifact OTHER than the one the caller
+     * named — today, the internal binary fallback or nested-jar redirect the lookup ended
+     * on. An unattributed candidate always means "in the artifact you asked about", so the
+     * field marks the exception rather than restating the common case on every entry.
+     */
+    artifactId?: string;
 }
 /**
  * Collects ranked near-miss class candidates from the artifact's symbol
@@ -10,5 +17,9 @@ export interface DidYouMeanCandidate {
  * edit-distance suggestions. Candidates are hints, never assertions that the
  * class exists at the suggested location. Returns an empty array when the
  * index has nothing usable.
+ *
+ * `attributeTo` stamps every produced candidate with that artifact id; pass it when
+ * collecting from an artifact the caller did not name, and leave it unset for the
+ * requested artifact.
  */
-export declare function collectDidYouMeanCandidates(svc: SourceService, artifactId: string, className: string): DidYouMeanCandidate[];
+export declare function collectDidYouMeanCandidates(svc: SourceService, artifactId: string, className: string, attributeTo?: string): DidYouMeanCandidate[];

package/dist/source/did-you-mean.js

@@ -15,8 +15,12 @@ function fqnOfRow(row) {
  * edit-distance suggestions. Candidates are hints, never assertions that the
  * class exists at the suggested location. Returns an empty array when the
  * index has nothing usable.
+ *
+ * `attributeTo` stamps every produced candidate with that artifact id; pass it when
+ * collecting from an artifact the caller did not name, and leave it unset for the
+ * requested artifact.
  */
-export function collectDidYouMeanCandidates(svc, artifactId, className) {
+export function collectDidYouMeanCandidates(svc, artifactId, className, attributeTo) {
     try {
         const simpleName = className.split(/[.$]/).at(-1) ?? className;
         if (!simpleName) {
@@ -29,7 +33,7 @@ export function collectDidYouMeanCandidates(svc, artifactId, className) {
                 return;
             }
             seen.add(fqn);
-            out.push({ className: fqn, matchReason });
+            out.push({ className: fqn, matchReason, ...(attributeTo ? { artifactId: attributeTo } : {}) });
         };
         const exact = svc.symbolsRepo.findScopedSymbols({
             artifactId,

package/dist/source/file-access.js

@@ -1,13 +1,19 @@
 import { basename } from "node:path";
+import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { log } from "../logger.js";
 import { decodeJarEntryUtf8OrThrow, listJarEntries, readJarEntryCapped } from "../source-jar-reader.js";
 import { normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
-// Read-through delivery for non-indexed jar resources: text files under these
-// prefixes are served directly from the backing jar when the source index has
-// no row for them. The per-file cap bounds response size; binary entries
-// answer with metadata only.
-const READ_THROUGH_PREFIXES = ["assets/", "data/"];
+// Read-through delivery for non-indexed jar resources: any entry of the
+// backing jar is served directly when the source index has no row for it.
+//
+// Delivery used to be gated on an `assets/`+`data/` path prefix, which made the
+// two entries an agent reaches for FIRST when inspecting a mod jar —
+// `fabric.mod.json` at the archive root and `META-INF/MANIFEST.MF` — permanently
+// unreachable (ERR_FILE_NOT_FOUND) even though `assets/**` read-through proved
+// the mechanism worked. The prefix carries no safety value: the real guards are
+// the traversal-shaped path rejection, the per-file byte cap, and the
+// text/binary classification below, and all three apply to every entry alike.
 const READ_THROUGH_MAX_BYTES = 512 * 1024;
 const READ_THROUGH_TEXT_EXTENSIONS = new Set([
     ".json",
@@ -24,23 +30,104 @@ const READ_THROUGH_TEXT_EXTENSIONS = new Set([
     ".md",
     ".fsh",
     ".vsh",
-    ".glsl"
+    ".glsl",
+    // Loader metadata that lives outside assets/ and data/.
+    ".mf",
+    ".accesswidener",
+    ".xml"
+]);
+/**
+ * Extensions known to hold non-text payloads. Listing them keeps the common
+ * case a metadata-only probe: no bytes are read at all.
+ */
+const READ_THROUGH_BINARY_EXTENSIONS = new Set([
+    ".class",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".ico",
+    ".jar",
+    ".zip",
+    ".gz",
+    ".tar",
+    ".ogg",
+    ".wav",
+    ".mp3",
+    ".nbt",
+    ".dat",
+    ".bin",
+    ".so",
+    ".dll",
+    ".dylib",
+    ".ttf",
+    ".otf",
+    ".woff",
+    ".woff2",
+    ".pack",
+    ".mca",
+    ".rsa",
+    ".dsa"
 ]);
 const NEARBY_PATH_HINT_LIMIT = 5;
+/** Ratio of C0 control bytes above which a sniffed entry counts as binary. */
+const SNIFF_MAX_CONTROL_RATIO = 0.05;
 function isTraversalShapedPath(filePath) {
     return (filePath.startsWith("/") ||
         filePath.includes("\u0000") ||
         filePath.split(/[\\/]/).includes(".."));
 }
-function hasReadThroughPrefix(filePath) {
-    return READ_THROUGH_PREFIXES.some((prefix) => filePath.startsWith(prefix));
-}
-function readThroughTextExtension(filePath) {
+function classifyReadThroughEntry(filePath) {
     const dot = filePath.lastIndexOf(".");
-    if (dot < 0) {
-        return false;
+    const slash = filePath.lastIndexOf("/");
+    if (dot < 0 || dot < slash) {
+        return "unknown";
+    }
+    const extension = filePath.slice(dot).toLowerCase();
+    if (READ_THROUGH_TEXT_EXTENSIONS.has(extension)) {
+        return "text";
+    }
+    if (READ_THROUGH_BINARY_EXTENSIONS.has(extension)) {
+        return "binary";
+    }
+    return "unknown";
+}
+/**
+ * Decodes a capped buffer when it really is UTF-8 text, else reports binary.
+ * A NUL byte, a strict-UTF-8 decode failure, or a high C0 control-byte ratio
+ * all mean "do not hand this back as text".
+ */
+function sniffUtf8Text(buffer) {
+    if (buffer.length === 0) {
+        return "";
+    }
+    if (buffer.includes(0)) {
+        return undefined;
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    }
+    catch {
+        return undefined;
+    }
+    let control = 0;
+    for (const byte of buffer) {
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d) {
+            control += 1;
+        }
+    }
+    return control / buffer.length > SNIFF_MAX_CONTROL_RATIO ? undefined : decoded;
+}
+/** Trims a capped buffer back to a UTF-8 character boundary at `limit`. */
+function trimToUtf8Boundary(buffer, limit) {
+    let cut = Math.min(limit, buffer.length);
+    while (cut > 0 && ((buffer[cut] ?? 0) & 0xc0) === 0x80) {
+        cut -= 1;
     }
-    return READ_THROUGH_TEXT_EXTENSIONS.has(filePath.slice(dot).toLowerCase());
+    return buffer.subarray(0, cut);
 }
 /**
  * Same-basename entries elsewhere in the jar, for not-found hints. Covers
@@ -52,7 +139,7 @@ async function collectNearbyPaths(binaryJarPath, missingPath) {
         const wanted = basename(missingPath);
         const entries = await listJarEntries(binaryJarPath);
         return entries
-            .filter((entry) => hasReadThroughPrefix(entry) && basename(entry) === wanted)
+            .filter((entry) => basename(entry) === wanted)
             .slice(0, NEARBY_PATH_HINT_LIMIT);
     }
     catch {
@@ -95,7 +182,7 @@ export async function getArtifactFile(svc, input) {
         const artifact = svc.getArtifact(input.artifactId);
         const normalizedPath = normalizePathStyle(input.filePath);
         const row = svc.filesRepo.getFileContent(artifact.artifactId, normalizedPath);
-        if (!row && hasReadThroughPrefix(normalizedPath) && artifact.binaryJarPath) {
+        if (!row && artifact.binaryJarPath) {
             return await readFileThroughJar(svc, {
                 artifact,
                 binaryJarPath: artifact.binaryJarPath,
@@ -108,7 +195,15 @@ export async function getArtifactFile(svc, input) {
             throw createError({
                 code: ERROR_CODES.FILE_NOT_FOUND,
                 message: `Source file "${input.filePath}" was not found.`,
-                details: { artifactId: input.artifactId, filePath: input.filePath }
+                details: {
+                    artifactId: input.artifactId,
+                    filePath: input.filePath,
+                    nextAction: "This artifact has no backing binary jar, so only indexed source files are reachable. List what is indexed with list-artifact-files.",
+                    ...buildSuggestedCall({
+                        tool: "list-artifact-files",
+                        params: { artifactId: input.artifactId, limit: 50 }
+                    })
+                }
             });
         }
         const maxBytes = clampLimit(input.maxBytes, svc.config.maxContentBytes, Number.MAX_SAFE_INTEGER);
@@ -145,16 +240,16 @@ export async function getArtifactFile(svc, input) {
 }
 async function readFileThroughJar(svc, args) {
     const { artifact, binaryJarPath, filePath, artifactId } = args;
-    const isText = readThroughTextExtension(filePath);
-    const cap = isText
-        ? Math.min(clampLimit(args.maxBytes, svc.config.maxContentBytes, Number.MAX_SAFE_INTEGER), READ_THROUGH_MAX_BYTES)
-        : 0;
+    const kind = classifyReadThroughEntry(filePath);
+    const cap = kind === "binary"
+        ? 0
+        : Math.min(clampLimit(args.maxBytes, svc.config.maxContentBytes, Number.MAX_SAFE_INTEGER), READ_THROUGH_MAX_BYTES);
     let capped;
     try {
         // Read at most the cap (+ slack to trim back to a UTF-8 boundary); an
-        // oversized entry is never fully materialized in memory. Binary entries
-        // are metadata-only probes (no content read at all).
-        capped = await readJarEntryCapped(binaryJarPath, filePath, isText ? cap + 4 : 0);
+        // oversized entry is never fully materialized in memory. Known-binary
+        // entries are metadata-only probes (no content read at all).
+        capped = await readJarEntryCapped(binaryJarPath, filePath, kind === "binary" ? 0 : cap + 4);
     }
     catch (error) {
         if (!isAppError(error) || error.code !== ERROR_CODES.SOURCE_NOT_FOUND) {
@@ -190,30 +285,37 @@ async function readFileThroughJar(svc, args) {
         }),
         deliveryMode: "jar-read-through"
     };
-    if (!isText) {
+    const omitBinary = (reason) => ({
+        ...base,
+        content: "",
+        contentBytes: capped.entrySize,
+        truncated: false,
+        contentOmittedReason: reason
+    });
+    if (kind === "binary") {
+        return omitBinary("Entry is not a known text format; binary content is not delivered. Size and existence are reported instead.");
+    }
+    const truncated = capped.entrySize > cap;
+    // Trim the capped prefix back to a UTF-8 character boundary before decoding;
+    // the tail past the cap is dropped by design.
+    const trimmed = truncated ? trimToUtf8Boundary(capped.buffer, cap) : capped.buffer;
+    if (kind === "unknown") {
+        // No extension to go on: decide from the bytes rather than refuse a text
+        // entry (META-INF/services/*, LICENSE files) on the strength of its name.
+        const sniffed = sniffUtf8Text(trimmed);
+        if (sniffed === undefined) {
+            return omitBinary("Entry has no known text extension and its bytes are not UTF-8 text; binary content is not delivered. Size and existence are reported instead.");
+        }
         return {
             ...base,
-            content: "",
+            content: sniffed,
             contentBytes: capped.entrySize,
-            truncated: false,
-            contentOmittedReason: "Entry is not a known text format; binary content is not delivered. Size and existence are reported instead."
+            truncated
         };
     }
-    const truncated = capped.entrySize > cap;
-    let content;
-    if (truncated) {
-        // Trim the capped prefix back to a UTF-8 character boundary before
-        // decoding; the tail past the cap is dropped by design.
-        const buffer = capped.buffer;
-        let cut = Math.min(cap, buffer.length);
-        while (cut > 0 && ((buffer[cut] ?? 0) & 0xc0) === 0x80) {
-            cut -= 1;
-        }
-        content = buffer.slice(0, cut).toString("utf8");
-    }
-    else {
-        content = decodeJarEntryUtf8OrThrow(capped.buffer, binaryJarPath, filePath);
-    }
+    const content = truncated
+        ? trimmed.toString("utf8")
+        : decodeJarEntryUtf8OrThrow(capped.buffer, binaryJarPath, filePath);
     return {
         ...base,
         content,
@@ -234,10 +336,12 @@ export async function listArtifactFiles(svc, input) {
             prefix
         });
         const normalizedPrefix = normalizeOptionalString(prefix);
-        if (normalizedPrefix &&
-            page.items.length === 0 &&
-            (normalizedPrefix.startsWith("assets/") || normalizedPrefix.startsWith("data/"))) {
-            warnings.push("Indexed artifacts currently include Java source only; non-Java resources are not indexed. Text files under assets/ and data/ are served directly from the backing jar — request them by exact path with get-artifact-file (read-through delivery).");
+        // A prefix that matched nothing is the exact moment read-through is worth
+        // naming: the index holds Java source only, while EVERY jar entry —
+        // archive-root files such as fabric.mod.json and META-INF/** included — is
+        // reachable by exact path.
+        if (normalizedPrefix && page.items.length === 0 && artifact.binaryJarPath) {
+            warnings.push("Indexed artifacts currently include Java source only; non-Java resources are not indexed. Any text entry of the backing jar — including archive-root files such as fabric.mod.json and META-INF/** — is served directly by exact path with get-artifact-file (read-through delivery).");
         }
         return {
             items: page.items,

package/dist/source/indexer.js

@@ -252,6 +252,7 @@ export async function buildRebuiltArtifactData(svc, resolved) {
                 vineflowerJarPath: vineflowerPath,
                 artifactIdCandidate: resolved.artifactId,
                 timeoutMs: 120_000,
+                maxMemoryMb: svc.config.decompileMaxMemoryMb,
                 signature: resolved.artifactId
             });
             files = decompileResult.javaFiles.map((entry) => ({

package/dist/source/nested-jars.d.ts

@@ -9,6 +9,25 @@ export interface NestedJarMatch {
     entryName: string;
     extractedPath: string;
 }
+export interface NestedClassMatch {
+    qualifiedName: string;
+    filePath: string;
+    line: number;
+    symbolKind: "class";
+}
+/**
+ * Finds exact class-name matches across a shell's nested bytecode inventory.
+ * Results use the same binary-backed class representation as entry-tool search:
+ * an inferred outer Java path, line 1, and the broad class symbol kind.
+ */
+export declare function findNestedJarClasses(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerSignature: string;
+    inventory: string[];
+    className: string;
+    limit: number;
+}): Promise<NestedClassMatch[]>;
 /**
  * Shell detection with both required signals: near-zero own classes AND
  * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"