@adhisang/minecraft-modding-mcp 6.1.1 → 6.2.0

package/dist/source/indexer.js

@@ -7,6 +7,7 @@ import { decompileBinaryJar } from "../decompiler/vineflower.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { log } from "../logger.js";
 import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
+import { detectShellJarInventory } from "./nested-jars.js";
 import { iterateJavaEntriesAsUtf8 } from "../source-jar-reader.js";
 import { extractSymbolsFromSource } from "../symbols/symbol-extractor.js";
 import { remapJar } from "../tiny-remapper-service.js";
@@ -44,7 +45,11 @@ export async function indexArtifact(svc, input) {
     const artifact = svc.getArtifact(artifactId);
     const force = input.force ?? false;
     const meta = svc.indexMetaRepo.get(artifact.artifactId);
-    const hasFiles = meta ? meta.filesCount > 0 : false;
+    // Shell jars legitimately index zero files; without force they count as
+    // current instead of re-running shell detection on every reindex call.
+    const hasFiles = meta
+        ? meta.filesCount > 0 || artifact.qualityFlags.includes("shell-jar")
+        : false;
     const expectedSignature = artifact.artifactSignature ?? fallbackArtifactSignature(artifact.artifactId);
     const reason = resolveIndexRebuildReason({
         force,
@@ -180,8 +185,56 @@ export async function buildRebuiltArtifactData(svc, resolved) {
     let files = [];
     if (resolved.sourceJarPath) {
         files = await loadFromSourceJar(svc, resolved.sourceJarPath);
+        // Loom split-source pairs (common/clientOnly) publish the version across
+        // two sources jars; index the companion half too so neither side's
+        // classes go missing. The primary jar wins on duplicate paths. Note the
+        // artifact signature derives from the primary jar only: a regenerated
+        // companion lands at a new hash-addressed path, so persisted provenance
+        // can point at a deleted companion — that must degrade to a primary-only
+        // index, never fail the primary rebuild.
+        for (const companion of resolved.provenance?.companionSourceJars ?? []) {
+            let extra;
+            try {
+                extra = await loadFromSourceJar(svc, companion);
+            }
+            catch (companionError) {
+                log("warn", "index.companion_source_skipped", {
+                    artifactId: resolved.artifactId,
+                    companion,
+                    reason: companionError instanceof Error ? companionError.message : String(companionError)
+                });
+                continue;
+            }
+            const seenPaths = new Set(files.map((file) => file.filePath));
+            files.push(...extra.filter((file) => !seenPaths.has(file.filePath)));
+        }
     }
     else if (resolved.binaryJarPath) {
+        // Jar-in-Jar shells (near-zero own classes, all content in nested jars)
+        // would decompile to zero Java files and dead-end in
+        // ERR_DECOMPILER_FAILED. Detect them before remap/decompile: the artifact
+        // is created with an empty file index, the nested-jar inventory persisted
+        // in provenance, and class-family lookups redirect into the nested jars.
+        const shellInventory = await detectShellJarInventory(resolved.binaryJarPath);
+        if (shellInventory) {
+            const qualityFlags = resolved.qualityFlags ?? [];
+            resolved.qualityFlags = qualityFlags.includes("shell-jar")
+                ? qualityFlags
+                : [...qualityFlags, "shell-jar"];
+            if (resolved.provenance) {
+                // Mutate in place: resolveArtifact holds a reference to this object
+                // for its response, mirroring the binaryJarPath swap below.
+                resolved.provenance.nestedJars = shellInventory;
+            }
+            resolved.isDecompiled = false;
+            return {
+                files: [],
+                symbols: [],
+                totalContentBytes: 0,
+                indexedAt: new Date().toISOString(),
+                indexDurationMs: Date.now() - indexStartedAt
+            };
+        }
         const decompileInputJarPath = await maybeRemapBinaryForMojang(svc, resolved);
         // When the binary jar was remapped from obfuscated to mojang, swap the resolved
         // artifact's binaryJarPath to the remapped jar so downstream bytecode consumers
@@ -298,7 +351,11 @@ export async function ingestIfNeeded(svc, resolved) {
     // 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;
+    // Shell jars legitimately index zero files (their content lives in nested
+    // jars), so their empty index counts as current instead of forcing a
+    // re-detection rebuild on every warm resolve.
+    const existingIsShell = existing?.qualityFlags.includes("shell-jar") ?? false;
+    const hasFiles = meta ? meta.filesCount > 0 || existingIsShell : false;
     const reason = resolveIndexRebuildReason({
         force: false,
         expectedSignature: resolved.artifactSignature,
@@ -306,6 +363,19 @@ export async function ingestIfNeeded(svc, resolved) {
         meta
     });
     if (existing && reason === "already_current") {
+        if (existingIsShell) {
+            // Reconcile shell state onto the freshly-resolved object so warm-cache
+            // responses carry the same flag and inventory as the first resolve.
+            const qualityFlags = resolved.qualityFlags ?? [];
+            if (!qualityFlags.includes("shell-jar")) {
+                resolved.qualityFlags = [...qualityFlags, "shell-jar"];
+            }
+            const persistedInventory = existing.provenance?.nestedJars;
+            if (resolved.provenance && persistedInventory && !resolved.provenance.nestedJars) {
+                resolved.provenance.nestedJars = persistedInventory;
+            }
+            resolved.isDecompiled = false;
+        }
         // Mojang binary-remap reconciliation on the warm cache hit path:
         // resolveSourceTargetInternal always returns the original binary jar
         // (resolver does not know about prior remap output), so without this

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

@@ -73,13 +73,16 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
             ]
         };
     }
-    const warnings = [
-        ...fallbackBase.warnings,
-        ...signature.warnings,
-        `Version ${version} is unobfuscated; validated symbol existence against runtime bytecode.`
-    ];
+    const warnings = [...fallbackBase.warnings, ...signature.warnings];
+    // Runtime validation is reported as the structured
+    // mappingContext.runtimeValidated flag instead of a per-response sentence.
+    const runtimeValidatedContext = {
+        ...fallbackBase.mappingContext,
+        runtimeValidated: true
+    };
     const buildResolved = (resolvedSymbol) => ({
         ...fallbackBase,
+        mappingContext: runtimeValidatedContext,
         querySymbol,
         resolved: true,
         status: "resolved",
@@ -96,6 +99,7 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
     });
     const buildUnresolved = (status) => ({
         ...fallbackBase,
+        mappingContext: runtimeValidatedContext,
         querySymbol,
         resolved: false,
         status,

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

@@ -0,0 +1,59 @@
+/**
+ * A jar with at most this many own `.class` entries can qualify as a
+ * Jar-in-Jar shell. Real Fabric API umbrella jars carry zero to a handful of
+ * marker classes while every API class lives in META-INF/jars.
+ */
+export declare const SHELL_JAR_MAX_OUTER_CLASSES = 8;
+export declare const NESTED_JAR_CACHE_DIRNAME = "nested-jars";
+export interface NestedJarMatch {
+    entryName: string;
+    extractedPath: string;
+}
+/**
+ * Shell detection with both required signals: near-zero own classes AND
+ * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"
+ * declarations that really exist in the archive). Returns the inventory for
+ * shells and undefined for every regular jar.
+ */
+export declare function detectShellJarInventory(jarPath: string): Promise<string[] | undefined>;
+/**
+ * Content-addressed on-disk location of an extracted nested jar. The digest
+ * covers the outer jar path, its signature, and the entry name, so the same
+ * shell always maps to the same extracted file and re-resolution reuses it.
+ */
+export declare function nestedJarCachePath(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string): string;
+/**
+ * Extracts one nested jar to the content-addressed cache (no-op when already
+ * present). Entry-name safety is enforced by readJarEntryAsBuffer, and the
+ * on-disk name is the digest — never derived from the entry name — so a
+ * hostile entry name cannot escape the cache directory.
+ */
+export declare function extractNestedJar(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string): Promise<string>;
+/**
+ * Finds every nested jar of a shell that contains the class. Zero matches
+ * means the class genuinely is not bundled; more than one means the caller
+ * must return candidates instead of picking silently.
+ *
+ * The lookup is deliberately single-level: it inspects each nested jar's own
+ * class list only. A nested jar that is itself a shell surfaces its content
+ * when resolved directly as its own artifact.
+ */
+export declare function findNestedJarsContainingClass(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerSignature: string;
+    inventory: string[];
+    internalName: string;
+}): Promise<NestedJarMatch[]>;
+/**
+ * Resolves the single nested jar containing a class. Zero matches returns
+ * undefined (the caller keeps its not-found contract); several matches throw
+ * candidates instead of picking one silently.
+ */
+export declare function resolveUniqueNestedJarForClass(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerArtifactId: string;
+    inventory: string[];
+    className: string;
+}): Promise<NestedJarMatch | undefined>;

package/dist/source/nested-jars.js

@@ -0,0 +1,198 @@
+import { createHash, randomBytes } from "node:crypto";
+import { access, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { ERROR_CODES, createError } from "../errors.js";
+import { collectNestedJars } from "../mod-analyzer.js";
+import { listJarEntries, readJarEntryAsBuffer, readJarEntryAsUtf8 } from "../source-jar-reader.js";
+/**
+ * A jar with at most this many own `.class` entries can qualify as a
+ * Jar-in-Jar shell. Real Fabric API umbrella jars carry zero to a handful of
+ * marker classes while every API class lives in META-INF/jars.
+ */
+export const SHELL_JAR_MAX_OUTER_CLASSES = 8;
+export const NESTED_JAR_CACHE_DIRNAME = "nested-jars";
+// In-process cache of class listings per extracted nested jar, so repeated
+// class lookups against the same shell never re-open its nested jars. The
+// shell's own inventory is persisted with the artifact record; this cache is
+// only the per-nested-jar class membership.
+const classSetCache = new Map();
+const CLASS_SET_CACHE_MAX = 32;
+function rememberClassSet(key, value) {
+    classSetCache.delete(key);
+    classSetCache.set(key, value);
+    while (classSetCache.size > CLASS_SET_CACHE_MAX) {
+        const oldest = classSetCache.keys().next().value;
+        if (oldest === undefined) {
+            break;
+        }
+        classSetCache.delete(oldest);
+    }
+}
+/**
+ * Shell detection with both required signals: near-zero own classes AND
+ * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"
+ * declarations that really exist in the archive). Returns the inventory for
+ * shells and undefined for every regular jar.
+ */
+export async function detectShellJarInventory(jarPath) {
+    let entries;
+    try {
+        entries = await listJarEntries(jarPath);
+    }
+    catch {
+        return undefined;
+    }
+    let ownClassCount = 0;
+    for (const entry of entries) {
+        if (entry.endsWith(".class")) {
+            ownClassCount += 1;
+            if (ownClassCount > SHELL_JAR_MAX_OUTER_CLASSES) {
+                return undefined;
+            }
+        }
+    }
+    let declared;
+    if (entries.includes("fabric.mod.json")) {
+        try {
+            const parsed = JSON.parse(await readJarEntryAsUtf8(jarPath, "fabric.mod.json"));
+            const jars = parsed?.jars;
+            if (Array.isArray(jars)) {
+                declared = jars
+                    .map((entry) => entry?.file)
+                    .filter((file) => typeof file === "string");
+            }
+        }
+        catch {
+            // Unreadable metadata leaves only the META-INF/jars scan signal.
+        }
+    }
+    const inventory = collectNestedJars(entries, declared);
+    return inventory.length > 0 ? inventory : undefined;
+}
+/**
+ * Content-addressed on-disk location of an extracted nested jar. The digest
+ * covers the outer jar path, its signature, and the entry name, so the same
+ * shell always maps to the same extracted file and re-resolution reuses it.
+ */
+export function nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entryName) {
+    const digest = createHash("sha256")
+        .update(`${outerJarPath}|${outerSignature}|${entryName}`)
+        .digest("hex");
+    return join(cacheDir, NESTED_JAR_CACHE_DIRNAME, `${digest}.jar`);
+}
+/**
+ * Extracts one nested jar to the content-addressed cache (no-op when already
+ * present). Entry-name safety is enforced by readJarEntryAsBuffer, and the
+ * on-disk name is the digest — never derived from the entry name — so a
+ * hostile entry name cannot escape the cache directory.
+ */
+export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, entryName) {
+    const finalPath = nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entryName);
+    try {
+        await access(finalPath);
+        return finalPath;
+    }
+    catch {
+        // fall through to extraction
+    }
+    const bytes = await readJarEntryAsBuffer(outerJarPath, entryName);
+    await mkdir(dirname(finalPath), { recursive: true });
+    const tempPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${randomBytes(6).toString("hex")}`;
+    await writeFile(tempPath, bytes);
+    try {
+        await rename(tempPath, finalPath);
+    }
+    catch (renameError) {
+        // A concurrent extraction of the same entry may have won the rename.
+        // The content-addressed final file being present makes this call a
+        // success; anything else is a real failure.
+        try {
+            await access(finalPath);
+        }
+        catch {
+            throw renameError;
+        }
+        await rm(tempPath, { force: true });
+    }
+    return finalPath;
+}
+/**
+ * Finds every nested jar of a shell that contains the class. Zero matches
+ * means the class genuinely is not bundled; more than one means the caller
+ * must return candidates instead of picking silently.
+ *
+ * The lookup is deliberately single-level: it inspects each nested jar's own
+ * class list only. A nested jar that is itself a shell surfaces its content
+ * when resolved directly as its own artifact.
+ */
+export async function findNestedJarsContainingClass(args) {
+    const classEntry = `${args.internalName}.class`;
+    const matches = [];
+    for (const entryName of args.inventory) {
+        let extractedPath;
+        try {
+            extractedPath = await extractNestedJar(args.cacheDir, args.outerJarPath, args.outerSignature, entryName);
+        }
+        catch {
+            // Unsafe or unreadable nested entries never become candidates.
+            continue;
+        }
+        let classSet = classSetCache.get(extractedPath);
+        if (!classSet) {
+            try {
+                const entries = await listJarEntries(extractedPath);
+                classSet = new Set(entries.filter((entry) => entry.endsWith(".class")));
+            }
+            catch {
+                continue;
+            }
+            rememberClassSet(extractedPath, classSet);
+        }
+        if (classSet.has(classEntry)) {
+            matches.push({ entryName, extractedPath });
+        }
+    }
+    return matches;
+}
+/**
+ * Resolves the single nested jar containing a class. Zero matches returns
+ * undefined (the caller keeps its not-found contract); several matches throw
+ * candidates instead of picking one silently.
+ */
+export async function resolveUniqueNestedJarForClass(args) {
+    const internalName = args.className.replace(/\./g, "/");
+    const matches = await findNestedJarsContainingClass({
+        cacheDir: args.cacheDir,
+        outerJarPath: args.outerJarPath,
+        outerSignature: args.outerArtifactId,
+        inventory: args.inventory,
+        internalName
+    });
+    if (matches.length === 0) {
+        return undefined;
+    }
+    const single = matches.length === 1 ? matches[0] : undefined;
+    if (single) {
+        return single;
+    }
+    throw createError({
+        code: ERROR_CODES.NESTED_JAR_AMBIGUOUS,
+        message: `Class "${args.className}" exists in ${matches.length} nested jars bundled by this shell jar; refusing to pick one automatically.`,
+        details: {
+            className: args.className,
+            shellArtifactId: args.outerArtifactId,
+            nestedJarCandidates: matches.map((match) => match.entryName),
+            nextAction: "Resolve the intended nested jar as its own artifact, then query the class against that artifactId.",
+            ...buildSuggestedCall({
+                tool: "resolve-artifact",
+                params: undefined,
+                examples: matches.map((match) => ({
+                    params: { target: { kind: "jar", value: match.extractedPath } },
+                    reason: `Query classes inside "${match.entryName}" directly.`
+                }))
+            })
+        }
+    });
+}
+//# sourceMappingURL=nested-jars.js.map

package/dist/source/workspace-target.js

@@ -243,7 +243,7 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             ? `Multiple cached versions for ${group}:${name} in ~/.gradle/caches/modules-2 (${result.candidatesSeen.join(", ")}); refusing to pick without project-specific evidence.`
             : `Could not resolve a version for dependency ${group}:${name} from gradle.properties or modules-2 cache.`;
         const nextAction = ambiguous
-            ? `Set ${name}_version (or another supported gradle.properties key) so the project's intended version is unambiguous, or pass an explicit version on the dependency target.`
+            ? `Set ${name}_version (or another supported gradle.properties key) so the project's intended version is unambiguous, pass an explicit version on the dependency target, or declare the umbrella version property so the cached umbrella POM can supply the submodule version.`
             : "Provide an explicit version on the dependency target, or add a property to gradle.properties so detectDependencyVersion can find it.";
         throw createError({
             code: ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED,
@@ -305,7 +305,10 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             source: result.source,
             candidatesSeen: result.candidatesSeen,
             attempts: result.attempts,
-            cacheHit: false
+            cacheHit: false,
+            ...(result.submoduleVersionSource
+                ? { submoduleVersionSource: result.submoduleVersionSource }
+                : {})
         }
     };
 }

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

@@ -3,6 +3,7 @@ export declare function __getZipOpenCount(): number;
 export declare function __resetZipOpenCount(): void;
 interface ZipEntry {
     fileName: string;
+    uncompressedSize: number;
 }
 export interface ZipFile {
     readEntry(): void;
@@ -38,6 +39,21 @@ 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 CappedJarEntry {
+    /** At most the requested byte budget of the entry (empty when maxBytes<=0). */
+    buffer: Buffer;
+    /** Full uncompressed size from the zip metadata, independent of the cap. */
+    entrySize: number;
+}
+/**
+ * Reads at most maxBytes of one entry, reporting the full uncompressed size
+ * from the zip metadata. Unlike readJarEntryAsBuffer, an oversized entry is
+ * never fully materialized: the stream is destroyed once the budget is
+ * exceeded and the collected prefix is returned. maxBytes<=0 skips the read
+ * entirely (metadata-only probe).
+ */
+export declare function readJarEntryCapped(jarPath: string, entryPath: string, maxBytes: number): Promise<CappedJarEntry>;
+export declare function decodeJarEntryUtf8OrThrow(contentBuffer: Buffer, jarPath: string, entryPath: string): string;
 export interface JarEntryReader {
     getEntryBuffer(entryPath: string): Promise<Buffer>;
     close(): void;

package/dist/source-jar-reader.js

@@ -203,6 +203,88 @@ export async function readJarEntryAsBuffer(jarPath, entryPath) {
         }
     });
 }
+/**
+ * Reads at most maxBytes of one entry, reporting the full uncompressed size
+ * from the zip metadata. Unlike readJarEntryAsBuffer, an oversized entry is
+ * never fully materialized: the stream is destroyed once the budget is
+ * exceeded and the collected prefix is returned. maxBytes<=0 skips the read
+ * entirely (metadata-only probe).
+ */
+export async function readJarEntryCapped(jarPath, entryPath, maxBytes) {
+    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 }
+        });
+    }
+    return withZipFile(jarPath, async (zipFile) => {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (entry.fileName !== normalizedTargetPath) {
+                continue;
+            }
+            const entrySize = entry.uncompressedSize;
+            if (maxBytes <= 0) {
+                return { buffer: Buffer.alloc(0), entrySize };
+            }
+            const buffer = await readEntryStreamPrefix(zipFile, entry, jarPath, maxBytes);
+            return { buffer: buffer.length > maxBytes ? buffer.slice(0, maxBytes) : buffer, entrySize };
+        }
+    });
+}
+/** Like readEntryStream, but resolves with the collected prefix instead of rejecting when the budget is exceeded. */
+function readEntryStreamPrefix(zipFile, entry, jarPath, maxBytes) {
+    return new Promise((resolve, reject) => {
+        zipFile.openReadStream(entry, (error, stream) => {
+            if (error || !stream) {
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(error)}`));
+                return;
+            }
+            let settled = false;
+            let totalBytes = 0;
+            const chunks = [];
+            stream.on("data", (chunk) => {
+                if (settled)
+                    return;
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalBytes += buf.length;
+                chunks.push(buf);
+                if (totalBytes >= maxBytes) {
+                    settled = true;
+                    stream.destroy();
+                    resolve(Buffer.concat(chunks));
+                }
+            });
+            stream.once("error", (streamError) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(streamError)}`));
+            });
+            stream.once("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(Buffer.concat(chunks));
+            });
+        });
+    });
+}
+export function decodeJarEntryUtf8OrThrow(contentBuffer, jarPath, entryPath) {
+    return decodeUtf8OrThrow(contentBuffer, 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

package/dist/source-service.d.ts

@@ -140,6 +140,35 @@ export type GetArtifactFileOutput = {
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
+    /**
+     * Present when the file was served directly from the backing jar instead of
+     * the source index (non-indexed assets/ and data/ text files).
+     */
+    deliveryMode?: "jar-read-through";
+    /** Set when content was withheld (e.g. a binary entry); explains why. */
+    contentOmittedReason?: string;
+};
+export type GetModClassMembersInput = {
+    jarPath: string;
+    className: string;
+};
+export type GetModClassMembersOutput = {
+    className: string;
+    jarPath: string;
+    members: {
+        constructors: SignatureMember[];
+        fields: SignatureMember[];
+        methods: SignatureMember[];
+    };
+    counts: {
+        constructors: number;
+        fields: number;
+        methods: number;
+        total: number;
+    };
+    /** Members are read from bytecode; no decompiler runs on this path. */
+    extractionMethod: "bytecode-only";
+    warnings: string[];
 };
 export type ListArtifactFilesInput = {
     artifactId: string;
@@ -256,6 +285,7 @@ export type GetClassMembersInput = {
     access?: MemberAccess;
     includeSynthetic?: boolean;
     includeInherited?: boolean;
+    includeAnnotations?: boolean;
     memberPattern?: string;
     maxMembers?: number;
     cursor?: string;
@@ -623,6 +653,12 @@ export declare class SourceService {
     getRegistryData(input: GetRegistryDataInput): Promise<GetRegistryDataOutput>;
     compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
     decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
+    /**
+     * Member-level view of a third-party mod jar class, read from bytecode
+     * only — no decompiler is involved on this path, so it answers in
+     * milliseconds where a decompile-backed lookup costs a full Vineflower run.
+     */
+    getModClassMembers(input: GetModClassMembersInput): Promise<GetModClassMembersOutput>;
     getModClassSource(input: GetModClassSourceInput): Promise<GetModClassSourceOutput>;
     searchModSource(input: SearchModSourceInput): Promise<SearchModSourceOutput>;
     findMapping(input: FindMappingInput): Promise<FindMappingOutput>;

package/dist/source-service.js

@@ -1,4 +1,6 @@
 import { loadConfig } from "./config.js";
+import { ERROR_CODES, createError } from "./errors.js";
+import { validateAndNormalizeJarPath } from "./path-resolver.js";
 import { MinecraftExplorerService } from "./minecraft-explorer-service.js";
 import { MappingService } from "./mapping-service.js";
 import { openDatabase } from "./storage/db.js";
@@ -124,6 +126,47 @@ export class SourceService {
     async decompileModJar(input) {
         return this.modDecompileService.decompileModJar(input);
     }
+    /**
+     * Member-level view of a third-party mod jar class, read from bytecode
+     * only — no decompiler is involved on this path, so it answers in
+     * milliseconds where a decompile-backed lookup costs a full Vineflower run.
+     */
+    async getModClassMembers(input) {
+        const jarPath = validateAndNormalizeJarPath(input.jarPath);
+        const className = input.className.trim();
+        if (!className) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "className must be non-empty."
+            });
+        }
+        const signature = await this.explorerService.getSignature({
+            fqn: className,
+            jarPath,
+            access: "all"
+        });
+        const counts = {
+            constructors: signature.constructors.length,
+            fields: signature.fields.length,
+            methods: signature.methods.length,
+            total: signature.constructors.length + signature.fields.length + signature.methods.length
+        };
+        // No context block: contextForJar derives minecraftVersion/namespace from
+        // the jar path, which for an arbitrary mod jar greps the MOD's own
+        // version (e.g. geckolib-fabric-26.2.jar -> "26.2") — misleading here.
+        return {
+            className,
+            jarPath,
+            members: {
+                constructors: signature.constructors,
+                fields: signature.fields,
+                methods: signature.methods
+            },
+            counts,
+            extractionMethod: "bytecode-only",
+            warnings: signature.warnings
+        };
+    }
     async getModClassSource(input) {
         return this.modDecompileService.getModClassSource(input);
     }
@@ -143,12 +186,12 @@ export class SourceService {
         const result = await this.mappingService.checkSymbolExists(input);
         // On unobfuscated versions the mapping graph is empty, so the mapping service can
         // only ever report symbols as missing. We then validate against runtime bytecode.
-        // Classes/fields surface as `mapping_unavailable` when the graph yields nothing, but
-        // a method query with a non-empty graph returns `not_found` (empty member lookup) —
-        // which previously skipped the runtime fallback and produced false negatives for
-        // methods that genuinely exist. Treat `not_found` methods as fallback-eligible.
-        const fallbackEligible = result.status === "mapping_unavailable" ||
-            (result.status === "not_found" && input.kind === "method");
+        // A non-empty graph that simply lacks the queried record returns `not_found` for
+        // ANY kind — methods, fields, and classes alike — and skipping the runtime check
+        // produced false negatives (e.g. a real EntityType.ITEM field reported missing).
+        // Every `not_found` is therefore fallback-eligible alongside `mapping_unavailable`;
+        // the runtime check itself keeps genuinely-missing symbols `not_found`.
+        const fallbackEligible = result.status === "mapping_unavailable" || result.status === "not_found";
         if (!fallbackEligible ||
             !isUnobfuscatedVersion(input.version) ||
             (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {