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

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/shared-utils.d.ts

@@ -2,5 +2,26 @@ import type { SourceMapping } from "../types.js";
 export declare function normalizePathStyle(path: string): string;
 export declare function normalizeOptionalString(value: string | undefined): string | undefined;
 export declare function normalizeMapping(mapping: SourceMapping | undefined): SourceMapping;
+/**
+ * The mapping an artifact-targeted call runs in when the caller left `mapping`
+ * out.
+ *
+ * A stored artifact already carries the namespace it was resolved into, so a
+ * follow-up call that names it by `artifactId` must inherit that namespace
+ * instead of falling back to the version-target default ("obfuscated").
+ * Without this, `find-class` -> `get-class-source` -> `get-class-members`
+ * split across two namespaces: source came back in mojang names while members
+ * came back obfuscated (`ownerFqn: "dlp"`), for the same artifact and the same
+ * absent `mapping` argument.
+ *
+ * `requestedMapping` wins over `mappingApplied` so the echoed request keeps
+ * meaning "what was asked for" even on artifacts where the mapping could not
+ * be applied; `mappingApplied` is the fallback for rows stored before the
+ * requested namespace was persisted.
+ */
+export declare function inheritArtifactMapping(inputMapping: SourceMapping | undefined, artifact: {
+    requestedMapping?: SourceMapping;
+    mappingApplied?: SourceMapping;
+}): SourceMapping;
 export declare function pathExists(filePath: string): Promise<boolean>;
 export declare function dedupeQualityFlags(qualityFlags: readonly string[]): string[];

package/dist/source/shared-utils.js

@@ -31,6 +31,29 @@ export function normalizeMapping(mapping) {
         }
     });
 }
+/**
+ * The mapping an artifact-targeted call runs in when the caller left `mapping`
+ * out.
+ *
+ * A stored artifact already carries the namespace it was resolved into, so a
+ * follow-up call that names it by `artifactId` must inherit that namespace
+ * instead of falling back to the version-target default ("obfuscated").
+ * Without this, `find-class` -> `get-class-source` -> `get-class-members`
+ * split across two namespaces: source came back in mojang names while members
+ * came back obfuscated (`ownerFqn: "dlp"`), for the same artifact and the same
+ * absent `mapping` argument.
+ *
+ * `requestedMapping` wins over `mappingApplied` so the echoed request keeps
+ * meaning "what was asked for" even on artifacts where the mapping could not
+ * be applied; `mappingApplied` is the fallback for rows stored before the
+ * requested namespace was persisted.
+ */
+export function inheritArtifactMapping(inputMapping, artifact) {
+    if (inputMapping != null) {
+        return normalizeMapping(inputMapping);
+    }
+    return artifact.requestedMapping ?? artifact.mappingApplied ?? normalizeMapping(undefined);
+}
 export async function pathExists(filePath) {
     try {
         await access(filePath);

package/dist/source-service.d.ts

@@ -268,11 +268,20 @@ export type FindClassMatch = {
     filePath: string;
     line: number;
     symbolKind: string;
+    /** Set when the match is a type declared INSIDE another type. */
+    nested?: boolean;
+    /** The enclosing top-level type, present only on a nested match. */
+    enclosingClass?: string;
 };
 export type FindClassOutput = {
     matches: FindClassMatch[];
     total: number;
     warnings: string[];
+    /** Recovery route when the index legitimately cannot answer (partial coverage). */
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
 };
 type MemberAccess = "public" | "all";
 export type GetClassMembersInput = {
@@ -638,6 +647,7 @@ export declare class SourceService {
         requestedScope: ArtifactScope;
         atNamespace: AccessTransformerNamespace;
         loader: import("./workspace-mapping-service.js").WorkspaceProjectLoader | "unknown";
+        projectMinecraftVersion?: string;
     }): ReturnType<typeof artifactResolver.discoverAccessTransformerRuntimeCandidates>;
     buildMappingFallbackSuggestedCall(args: {
         input: ResolveArtifactInput;
@@ -702,6 +712,7 @@ export declare class SourceService {
         mappingApplied: SourceMapping;
         provenance?: ArtifactProvenance;
         qualityFlags: string[];
+        allowDecompile?: boolean;
     }): Promise<ResolvedSourceArtifact | undefined>;
     getArtifact(artifactId: string): ArtifactRow;
     ingestIfNeeded(resolved: ResolvedSourceArtifact): Promise<void>;