@adhisang/minecraft-modding-mcp 7.0.0-rc.3 → 7.1.0

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

@@ -1,5 +1,18 @@
 import { ERROR_CODES, isAppError } from "../../errors.js";
+/**
+ * check-symbol-exists's runtime fallback: the result of `runUnobfuscatedRuntimeCheck`
+ * alone. Its callers keep the fallback base's status whenever the check could not be
+ * performed, so they need no `verified` flag.
+ */
 export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbackBase) {
+    return (await runUnobfuscatedRuntimeCheck(svc, input, fallbackBase))?.result;
+}
+/**
+ * Checks a symbol against the Minecraft runtime jar of an unobfuscated version, whose
+ * names are the Mojang names. Undefined when the version or name is empty or the
+ * runtime jar cannot be resolved.
+ */
+export async function runUnobfuscatedRuntimeCheck(svc, input, fallbackBase) {
     const version = input.version.trim();
     const name = input.name.trim();
     const owner = input.owner?.trim();
@@ -8,11 +21,14 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
     }
     if (input.kind === "class" && input.nameMode !== "fqcn" && !name.includes(".")) {
         return {
-            ...fallbackBase,
-            warnings: [
-                ...fallbackBase.warnings,
-                `Version ${version} is unobfuscated, but short class name "${name}" could not be checked against runtime bytecode without a fully-qualified name.`
-            ]
+            verified: false,
+            result: {
+                ...fallbackBase,
+                warnings: [
+                    ...fallbackBase.warnings,
+                    `Version ${version} is unobfuscated, but short class name "${name}" could not be checked against runtime bytecode without a fully-qualified name.`
+                ]
+            }
         };
     }
     const querySymbol = input.kind === "class"
@@ -37,7 +53,7 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
             };
     const targetClass = input.kind === "class" ? name : owner;
     if (!targetClass) {
-        return fallbackBase;
+        return { verified: false, result: fallbackBase };
     }
     let jarPath;
     try {
@@ -61,16 +77,20 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         });
     }
     catch (error) {
+        // Only CLASS_NOT_FOUND is an answer; any other failure means the lookup never completed.
         const classMissing = isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND;
         return {
-            ...fallbackBase,
-            querySymbol,
-            warnings: [
-                ...fallbackBase.warnings,
-                classMissing
-                    ? `Class "${targetClass}" was not found in the Minecraft ${version} runtime jar; it does not exist (or is not in this jar).`
-                    : `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
-            ]
+            verified: classMissing,
+            result: {
+                ...fallbackBase,
+                querySymbol,
+                warnings: [
+                    ...fallbackBase.warnings,
+                    classMissing
+                        ? `Class "${targetClass}" was not found in the Minecraft ${version} runtime jar; it does not exist (or is not in this jar).`
+                        : `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
+                ]
+            }
         };
     }
     const warnings = [...fallbackBase.warnings, ...signature.warnings];
@@ -80,33 +100,40 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         ...fallbackBase.mappingContext,
         runtimeValidated: true
     };
+    // From here on the class loaded, so every answer below is a completed lookup.
     const buildResolved = (resolvedSymbol) => ({
-        ...fallbackBase,
-        mappingContext: runtimeValidatedContext,
-        querySymbol,
-        resolved: true,
-        status: "resolved",
-        resolvedSymbol,
-        candidates: resolvedSymbol
-            ? [{
-                    ...resolvedSymbol,
-                    matchKind: "exact",
-                    confidence: 1
-                }]
-            : [],
-        candidateCount: resolvedSymbol ? 1 : 0,
-        warnings
+        verified: true,
+        result: {
+            ...fallbackBase,
+            mappingContext: runtimeValidatedContext,
+            querySymbol,
+            resolved: true,
+            status: "resolved",
+            resolvedSymbol,
+            candidates: resolvedSymbol
+                ? [{
+                        ...resolvedSymbol,
+                        matchKind: "exact",
+                        confidence: 1
+                    }]
+                : [],
+            candidateCount: resolvedSymbol ? 1 : 0,
+            warnings
+        }
     });
     const buildUnresolved = (status) => ({
-        ...fallbackBase,
-        mappingContext: runtimeValidatedContext,
-        querySymbol,
-        resolved: false,
-        status,
-        resolvedSymbol: undefined,
-        candidates: [],
-        candidateCount: 0,
-        warnings
+        verified: true,
+        result: {
+            ...fallbackBase,
+            mappingContext: runtimeValidatedContext,
+            querySymbol,
+            resolved: false,
+            status,
+            resolvedSymbol: undefined,
+            candidates: [],
+            candidateCount: 0,
+            warnings
+        }
     });
     if (input.kind === "class") {
         return buildResolved({
@@ -127,7 +154,9 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
             symbol: `${owner}.${name}`
         });
     }
-    const methodCandidates = signature.methods.filter((method) => method.name === name);
+    // The bytecode reader lists constructors apart from methods (and only the owner's
+    // own: constructors are not inherited), so "<init>" is answered from them.
+    const methodCandidates = (name === "<init>" ? signature.constructors : signature.methods).filter((method) => method.name === name);
     const signatureMode = input.signatureMode ?? "name-only";
     if (signatureMode === "name-only") {
         // Existence semantics: any overload with this name means the method exists. Multiple

package/dist/source/symbol-resolver.js

@@ -1,4 +1,83 @@
 import { ERROR_CODES, createError } from "../errors.js";
+import { isUnobfuscatedVersion } from "../version-service.js";
+import { runUnobfuscatedRuntimeCheck } from "./lifecycle/runtime-check.js";
+/**
+ * Minecraft 26.1+ ships its runtime in Mojang names, so a Loom project for it has no
+ * `mappings` declaration: it compiles against the runtime names directly. Resolving a
+ * workspace symbol there is an identity lookup, checked against runtime bytecode the
+ * same way checkSymbolExists validates unobfuscated versions.
+ */
+async function resolveUnobfuscatedWorkspaceSymbol(svc, input, context) {
+    const { version, querySymbol, sourcePriorityApplied } = context;
+    const workspaceDetection = {
+        resolved: true,
+        mappingApplied: "mojang",
+        evidence: [],
+        warnings: [
+            `Minecraft ${version} is unobfuscated; no mappings declaration is needed — symbols are resolved against runtime (Mojang) names.`
+        ]
+    };
+    // The requested/defaulted sourceMapping label is echoed unchanged: on 26.1+ an
+    // "obfuscated" label already means the as-shipped Mojang names, and rewriting it to
+    // "mojang" would break callers that compare namespace labels for equality.
+    const base = {
+        querySymbol,
+        mappingContext: {
+            version,
+            sourceMapping: input.sourceMapping,
+            targetMapping: "mojang",
+            sourcePriorityApplied,
+            unobfuscatedRuntime: true
+        },
+        resolved: false,
+        status: "not_found",
+        candidates: [],
+        candidateCount: 0,
+        warnings: [...workspaceDetection.warnings]
+    };
+    // The runtime names are both the "obfuscated" (as-shipped) and the Mojang names;
+    // intermediary and yarn names do not exist for these versions.
+    if (input.sourceMapping !== "obfuscated" && input.sourceMapping !== "mojang") {
+        return {
+            ...base,
+            status: "mapping_unavailable",
+            workspaceDetection,
+            warnings: [
+                ...base.warnings,
+                `sourceMapping "${input.sourceMapping}" has no names on unobfuscated Minecraft ${version}; pass sourceMapping "mojang" (or "obfuscated") to resolve against runtime names.`
+            ]
+        };
+    }
+    const runtime = await runUnobfuscatedRuntimeCheck(svc, {
+        version,
+        kind: querySymbol.kind,
+        name: querySymbol.name,
+        owner: querySymbol.owner,
+        descriptor: querySymbol.descriptor,
+        sourceMapping: input.sourceMapping,
+        signatureMode: "exact"
+    }, base);
+    if (!runtime) {
+        // Mirrors checkSymbolExists: a symbol that could not be checked is not reported missing.
+        return {
+            ...base,
+            status: "mapping_unavailable",
+            workspaceDetection,
+            warnings: [
+                ...base.warnings,
+                `Minecraft ${version} runtime jar could not be resolved; symbol existence was not verified.`
+            ]
+        };
+    }
+    if (!runtime.verified) {
+        // The jar was reached but did not answer (short class name, class that failed to
+        // load for a reason other than being absent): the result carries the reason, and
+        // an unanswered lookup is not a definitive miss. `not_found` stays reserved for a
+        // class confirmed missing or a member lookup that completed without a match.
+        return { ...runtime.result, status: "mapping_unavailable", workspaceDetection };
+    }
+    return { ...runtime.result, workspaceDetection };
+}
 export async function resolveWorkspaceSymbol(svc, input) {
     const projectPath = input.projectPath?.trim();
     const version = input.version?.trim();
@@ -77,6 +156,15 @@ export async function resolveWorkspaceSymbol(svc, input) {
     const workspaceDetection = await svc.workspaceMappingService.detectCompileMapping({
         projectPath
     });
+    // No evidence also means no build script was found at all (a missing, mistyped or
+    // empty projectPath). Only a build that was read and declares no mappings is a
+    // 26.1+ Loom project compiling against the runtime names.
+    if (!workspaceDetection.resolved &&
+        workspaceDetection.evidence.length === 0 &&
+        isUnobfuscatedVersion(version) &&
+        (await svc.workspaceMappingService.hasReadableBuildScript(projectPath))) {
+        return resolveUnobfuscatedWorkspaceSymbol(svc, input, { version, querySymbol, sourcePriorityApplied });
+    }
     const warnings = [...workspaceDetection.warnings];
     if (!workspaceDetection.resolved || !workspaceDetection.mappingApplied) {
         return {

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

@@ -53,6 +53,39 @@ export declare class EntryTooLargeError extends Error {
 export declare function listJarEntries(jarPath: string): Promise<string[]>;
 export declare function listJavaEntries(jarPath: string): Promise<string[]>;
 export declare function hasAnyJarEntry(jarPath: string, predicate: (entryPath: string) => boolean): Promise<boolean>;
+/** Root entry in which a Minecraft runtime jar names its own release (`"id": "26.2"`). */
+export declare const MINECRAFT_VERSION_JSON_ENTRY = "version.json";
+/** Class every Minecraft runtime jar ships, under its Mojang name, from 26.1 on. */
+export declare const MINECRAFT_SHARED_CONSTANTS_ENTRY = "net/minecraft/SharedConstants.class";
+/**
+ * What an archive walk saw that bears on "is this the Minecraft runtime jar?".
+ * Raw observations only: judging them is the resolver's job.
+ */
+export interface MinecraftRuntimeJarSignals {
+    hasSharedConstantsClass: boolean;
+    /**
+     * Text of the root `version.json`; absent when the entry is missing, larger
+     * than the bound, unreadable, or not UTF-8.
+     */
+    versionJsonText?: string;
+}
+export interface JavaSourceScan {
+    hasJavaSources: boolean;
+    /** Set only when the walk reached the end without meeting a `.java` entry. */
+    minecraftRuntimeSignals?: MinecraftRuntimeJarSignals;
+}
+/**
+ * `hasAnyJarEntry(jarPath, hasJavaSourceExtension)` that also collects the
+ * Minecraft runtime signals on the same walk.
+ *
+ * A jar without sources is already walked to its last entry to prove it has none,
+ * so noting two entry names on the way costs no extra open and no extra pass. The
+ * one entry read, `version.json`, uses the handle that is already open. A failure
+ * to read it only withholds the signal: it is evidence for a mapping decision, not
+ * the archive's verdict, so it never fails the scan. Errors opening or walking the
+ * archive propagate exactly as they do from `hasAnyJarEntry`.
+ */
+export declare function scanJarForJavaSources(jarPath: string): Promise<JavaSourceScan>;
 export declare function readJarEntryAsUtf8(jarPath: string, entryPath: string): Promise<string>;
 /**
  * Reads one entry fully into memory. `maxBytes` bounds that materialization and

package/dist/source-jar-reader.js

@@ -183,6 +183,64 @@ export async function hasAnyJarEntry(jarPath, predicate) {
         }
     });
 }
+/** Root entry in which a Minecraft runtime jar names its own release (`"id": "26.2"`). */
+export const MINECRAFT_VERSION_JSON_ENTRY = "version.json";
+/** Class every Minecraft runtime jar ships, under its Mojang name, from 26.1 on. */
+export const MINECRAFT_SHARED_CONSTANTS_ENTRY = "net/minecraft/SharedConstants.class";
+/** The real file is under 1 KiB; anything far larger is not the file this looks for. */
+const MAX_VERSION_JSON_BYTES = 64 * 1024;
+/**
+ * `hasAnyJarEntry(jarPath, hasJavaSourceExtension)` that also collects the
+ * Minecraft runtime signals on the same walk.
+ *
+ * A jar without sources is already walked to its last entry to prove it has none,
+ * so noting two entry names on the way costs no extra open and no extra pass. The
+ * one entry read, `version.json`, uses the handle that is already open. A failure
+ * to read it only withholds the signal: it is evidence for a mapping decision, not
+ * the archive's verdict, so it never fails the scan. Errors opening or walking the
+ * archive propagate exactly as they do from `hasAnyJarEntry`.
+ */
+export async function scanJarForJavaSources(jarPath) {
+    return withZipFile(jarPath, async (zipFile) => {
+        let hasSharedConstantsClass = false;
+        let versionJsonEntry;
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (hasJavaSourceExtension(entry.fileName)) {
+                return { hasJavaSources: true };
+            }
+            if (entry.fileName === MINECRAFT_SHARED_CONSTANTS_ENTRY) {
+                hasSharedConstantsClass = true;
+            }
+            else if (entry.fileName === MINECRAFT_VERSION_JSON_ENTRY) {
+                versionJsonEntry = entry;
+            }
+        }
+        let versionJsonText;
+        if (versionJsonEntry && versionJsonEntry.uncompressedSize <= MAX_VERSION_JSON_BYTES) {
+            try {
+                const buffer = await readEntryStream(zipFile, versionJsonEntry, jarPath, MAX_VERSION_JSON_BYTES);
+                versionJsonText = UTF8_DECODER.decode(buffer);
+            }
+            catch {
+                versionJsonText = undefined;
+            }
+        }
+        return {
+            hasJavaSources: false,
+            minecraftRuntimeSignals: {
+                hasSharedConstantsClass,
+                ...(versionJsonText !== undefined ? { versionJsonText } : {})
+            }
+        };
+    });
+}
 export async function readJarEntryAsUtf8(jarPath, entryPath) {
     const contentBuffer = await readJarEntryAsBuffer(jarPath, entryPath);
     return decodeUtf8OrThrow(contentBuffer, jarPath, entryPath);

package/dist/source-resolver.d.ts

@@ -1,5 +1,6 @@
 import type { Config, MappingVariant, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
 import { type MavenCoordinate } from "./maven-resolver.js";
+import { type JavaSourceScan } from "./source-jar-reader.js";
 /**
  * Every `~/.m2` path a coordinate could name, before any of them is checked
  * against the filesystem.
@@ -59,6 +60,12 @@ export interface ResolveSourceTargetOptions {
      * legacy hash for obfuscated and source-backed artifacts.
      */
     mappingVariant?: MappingVariant;
+    /**
+     * Receives the result of walking the jar a `kind: "jar"` request names, once,
+     * when that walk ran. The resolver uses it to recognise a Minecraft runtime jar
+     * from its contents without walking the archive a second time.
+     */
+    onSubjectJarScanned?: (scan: JavaSourceScan) => void;
     onRepoFailover?: (event: {
         stage: "source" | "binary";
         repoUrl: string;

package/dist/source-resolver.js

@@ -7,15 +7,16 @@ import { buildRemoteBinaryUrls, buildRemoteSourceUrls, groupToPath, hasExistingJ
 import { defaultDownloadPath, discardCachedDownload, resolveCachedDownload } from "./repo-downloader.js";
 import { normalizeJarPath } from "./path-resolver.js";
 import { composeArtifactId, contentDigestSignature, contentSignature, jarArtifactIdentity, DECOMPILE_SIGNATURE_QUALIFIER } from "./artifact-identity.js";
-import { hasAnyJarEntry, hasJavaSourceExtension } from "./source-jar-reader.js";
+import { hasAnyJarEntry, hasJavaSourceExtension, scanJarForJavaSources } from "./source-jar-reader.js";
 /**
  * Whether a jar contains java sources, with archive errors deliberately
  * propagating.
  *
  * This is the check for a jar that IS the subject of the request - the
- * `input.kind === "jar"` branch of `resolveSourceTarget` calling it on
- * `resolvedJarPath`. What propagates is the reader's refusal to OPEN the
- * archive: a truncated file, a non-zip file, an unreadable central directory,
+ * `input.kind === "jar"` branch of `resolveSourceTarget` runs it on
+ * `resolvedJarPath` as `scanSubjectJarForJavaSources`, the same walk that also
+ * collects Minecraft runtime signals. What propagates is the reader's refusal
+ * to OPEN the archive: a truncated file, a non-zip file, an unreadable central directory,
  * an I/O failure. On the subject jar that refusal is the verdict itself, and
  * swallowing it would downgrade "this archive could not be read" into "this
  * archive has no sources" - handing back a sibling `-sources.jar` as if the
@@ -73,6 +74,18 @@ async function candidateHasJavaSources(jarPath) {
         return false;
     }
 }
+/**
+ * `hasJavaSources` for the subject jar of a `kind: "jar"` request, returning the
+ * Minecraft runtime signals the same walk collected. Same contract on both counts
+ * that matter: an absent file answers "no sources" without opening anything, and
+ * an archive that cannot be opened propagates.
+ */
+async function scanSubjectJarForJavaSources(jarPath) {
+    if (!hasExistingJar(jarPath)) {
+        return { hasJavaSources: false };
+    }
+    return await scanJarForJavaSources(jarPath);
+}
 function resolveExactJarSourceCandidate(inputJarPath) {
     const directory = dirname(inputJarPath);
     const jarName = basename(inputJarPath);
@@ -526,7 +539,9 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
         const adjacentSourceCandidates = await listAdjacentJarSourceCandidates(resolvedJarPath);
         const maybeAdjacentSourceCandidates = adjacentSourceCandidates.length > 0 ? adjacentSourceCandidates : undefined;
         const preferBinaryOnly = options.preferBinaryOnly ?? false;
-        if (await hasJavaSources(resolvedJarPath)) {
+        const subjectScan = await scanSubjectJarForJavaSources(resolvedJarPath);
+        options.onSubjectJarScanned?.(subjectScan);
+        if (subjectScan.hasJavaSources) {
             const siblingBinaryJarPath = resolveSiblingBinaryJarCandidate(resolvedJarPath);
             const binaryJarPath = siblingBinaryJarPath ??
                 (basename(resolvedJarPath).endsWith("-sources.jar") ? undefined : resolvedJarPath);

package/dist/source-service.d.ts

@@ -671,6 +671,11 @@ export declare class SourceService {
     listVersions(input?: ListVersionsInput): Promise<ListVersionsOutput>;
     getRegistryData(input: GetRegistryDataInput): Promise<GetRegistryDataOutput>;
     compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
+    /**
+     * Thin passthrough so entry tools (migration-overview) can diff a version
+     * pair's `libraries` without reaching into VersionService directly.
+     */
+    getVersionLibraries(version: string): Promise<string[]>;
     decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
     /**
      * Member-level view of a third-party mod jar class, read from bytecode

package/dist/source-service.js

@@ -123,6 +123,13 @@ export class SourceService {
     async compareVersions(input) {
         return this.versionDiffService.compareVersions(input);
     }
+    /**
+     * Thin passthrough so entry tools (migration-overview) can diff a version
+     * pair's `libraries` without reaching into VersionService directly.
+     */
+    async getVersionLibraries(version) {
+        return this.versionService.getVersionLibraries(version);
+    }
     async decompileModJar(input) {
         return this.modDecompileService.decompileModJar(input);
     }