@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/source/validate-mixin.js

@@ -4,6 +4,7 @@ import { performance } from "node:perf_hooks";
 import fastGlob from "fast-glob";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { loadMixinStageBudgets, refreshMixinValidationOutcome, validateParsedMixin } from "../mixin-validator.js";
+import { selectNestedMixin } from "../mixin-parser.js";
 import { normalizePathForHost } from "../path-converter.js";
 import { NOOP_STAGE_EMITTER } from "../stage-emitter.js";
 import { createMixinPipelineContext } from "./validate-mixin/pipeline-context.js";
@@ -262,11 +263,12 @@ async function runValidateMixinDispatcher(svc, rawInput, options = {}) {
     return validateMixinMany(svc, mode, configSources.map((entry) => ({
         source: {
             kind: "config",
-            label: entry.sourcePath,
+            label: (entry.nestedClassPath?.length ?? 0) > 1 ? `${entry.sourcePath} (${entry.entry})` : entry.sourcePath,
             path: entry.sourcePath,
             configPath: entry.configPath
         },
-        sourcePath: entry.sourcePath
+        sourcePath: entry.sourcePath,
+        nestedClassPath: entry.nestedClassPath
     })), resolvedInput, configWarnings, sharedSingleOptions);
 }
 async function createProjectValidateMixinConfigInput(input) {
@@ -299,7 +301,7 @@ async function createProjectValidateMixinConfigInput(input) {
         }
     };
 }
-function shouldRetryValidateMixinWithMavenFirst(svc, input, result) {
+function shouldRetryValidateMixinWithMavenFirst(svc, input, result, eligibilityIssues) {
     const initialPriority = input.retryState?.initialSourcePriority ?? input.sourcePriority ?? svc.config.mappingSourcePriority;
     if (input.retryState?.attempted || initialPriority !== "loom-first") {
         return false;
@@ -316,7 +318,9 @@ function shouldRetryValidateMixinWithMavenFirst(svc, input, result) {
     if (result.summary.membersSkipped > 0) {
         return true;
     }
-    return result.issues.some((issue) => issue.resolutionPath === "source-signature-unavailable" ||
+    // eligibilityIssues is the pre-category-filter issue list: a display
+    // filter (warningCategoryFilter) must not change whether a retry happens.
+    return eligibilityIssues.some((issue) => issue.resolutionPath === "source-signature-unavailable" ||
         issue.resolutionPath === "target-mapping-failed" ||
         issue.resolutionPath === "member-remap-failed");
 }
@@ -401,6 +405,20 @@ async function runValidateMixinPipeline(svc, seed) {
     await runResolveStage(svc, ctx);
     await runMappingHealthStage(svc, ctx);
     await runParseStage(ctx);
+    const nestedClassPath = ctx.input.nestedClassPath;
+    if (nestedClassPath) {
+        const nested = selectNestedMixin(ctx.parsed, nestedClassPath);
+        // A top-level entry whose file has no located @Mixin class keeps the whole-file result.
+        const wholeFile = nestedClassPath.length === 1 && (ctx.parsed.mixins ?? []).length === 0;
+        if (!nested && !wholeFile) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `No @Mixin class "${nestedClassPath.join("$")}" is declared in "${ctx.input.sourcePath ?? "<source>"}".`,
+                details: { failedStage: "parse" }
+            });
+        }
+        ctx.parsed = nested ?? ctx.parsed;
+    }
     await runTargetLookupStage(svc, ctx);
     return finalizeValidateMixinPipeline(svc, ctx);
 }
@@ -498,7 +516,25 @@ async function finalizeValidateMixinPipeline(svc, ctx) {
         };
         result.unfilteredSummary = unfilteredSummary;
     }
-    if (input.warningCategoryFilter && input.warningCategoryFilter.length > 0) {
+    // Recompute the outcome as the severity/uncertainty filters above leave it
+    // (a no-op when neither minSeverity nor hideUncertain was set), BEFORE any
+    // category filtering narrows things further. This is the baseline a
+    // warningCategoryFilter must reproduce exactly: valid, validationStatus and
+    // quickSummary must come out identical with or without the category
+    // filter, and retry eligibility must be decided from this same
+    // pre-category-filter issue list (see work items: warningCategoryFilter
+    // must not report a target-not-found mixin as valid:true, and must not
+    // change maven-first retry eligibility).
+    refreshMixinValidationOutcome(result);
+    const issuesForRetryEligibility = result.issues;
+    const preCategoryFilterValid = result.valid;
+    const preCategoryFilterValidationStatus = result.validationStatus;
+    const preCategoryFilterQuickSummary = result.quickSummary;
+    const categoryFilterApplied = !!(input.warningCategoryFilter && input.warningCategoryFilter.length > 0);
+    if (categoryFilterApplied) {
+        if (!result.unfilteredSummary) {
+            result.unfilteredSummary = { ...result.summary };
+        }
         const allowedCategories = new Set(input.warningCategoryFilter);
         result.issues = result.issues.filter((i) => i.category && allowedCategories.has(i.category));
         if (result.structuredWarnings) {
@@ -540,7 +576,15 @@ async function finalizeValidateMixinPipeline(svc, ctx) {
     else {
         refreshMixinValidationOutcome(result);
     }
-    if (shouldRetryValidateMixinWithMavenFirst(svc, input, result)) {
+    if (categoryFilterApplied) {
+        // refreshMixinValidationOutcome above recomputed valid/validationStatus/
+        // quickSummary from the category-filtered summary; restore the true
+        // (pre-category-filter) verdict now that member-count bookkeeping is done.
+        result.valid = preCategoryFilterValid;
+        result.validationStatus = preCategoryFilterValidationStatus;
+        result.quickSummary = preCategoryFilterQuickSummary;
+    }
+    if (shouldRetryValidateMixinWithMavenFirst(svc, input, result, issuesForRetryEligibility)) {
         const retryWarning = `Retrying validate-mixin with sourcePriority="maven-first" after partial validation using "${currentSourcePriority}".`;
         try {
             const retried = await svc.validateMixinSingle({
@@ -588,10 +632,10 @@ async function resolveMixinConfigSources(input) {
     const warnings = [];
     for (const rawConfigPath of input.input.configPaths) {
         const resolvedConfigPath = resolveMixinInputPath(rawConfigPath, "configPath");
-        let configJson;
+        let parsedConfig;
         try {
             const raw = await readFile(resolvedConfigPath, "utf-8");
-            configJson = JSON.parse(raw);
+            parsedConfig = JSON.parse(raw);
         }
         catch (err) {
             throw createError({
@@ -600,6 +644,44 @@ async function resolveMixinConfigSources(input) {
                 details: { failedStage: "input-validation" }
             });
         }
+        if (parsedConfig === null || typeof parsedConfig !== "object" || Array.isArray(parsedConfig)) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Mixin config "${rawConfigPath}" must contain a JSON object.`,
+                details: { failedStage: "input-validation" }
+            });
+        }
+        const configRecord = parsedConfig;
+        for (const key of ["mixins", "client", "server"]) {
+            const fieldValue = configRecord[key];
+            if (fieldValue === undefined) {
+                continue;
+            }
+            if (!Array.isArray(fieldValue)) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Mixin config "${rawConfigPath}" field "${key}" must be an array of class names.`,
+                    details: { failedStage: "input-validation" }
+                });
+            }
+            for (let i = 0; i < fieldValue.length; i++) {
+                if (typeof fieldValue[i] !== "string") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: `Mixin config "${rawConfigPath}" field "${key}" element at index ${i} must be a string.`,
+                        details: { failedStage: "input-validation" }
+                    });
+                }
+            }
+        }
+        if (configRecord.package !== undefined && typeof configRecord.package !== "string") {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Mixin config "${rawConfigPath}" field "package" must be a string.`,
+                details: { failedStage: "input-validation" }
+            });
+        }
+        const configJson = configRecord;
         const pkg = configJson.package ?? "";
         const classNames = [
             ...(configJson.mixins ?? []),
@@ -622,10 +704,13 @@ async function resolveMixinConfigSources(input) {
             for (const candidateRoot of COMMON_SOURCE_ROOTS) {
                 let foundInRoot = false;
                 for (const className of classNames) {
-                    const fqcn = pkg ? `${pkg}.${className}` : className;
-                    const relative = fqcn.replace(/\./g, "/") + ".java";
-                    if (await pathExists(resolvePath(projectBase, candidateRoot, relative))) {
-                        foundInRoot = true;
+                    for (const candidate of configEntrySourceCandidates(pkg, className)) {
+                        if (await pathExists(resolvePath(projectBase, candidateRoot, candidate.relativePath))) {
+                            foundInRoot = true;
+                            break;
+                        }
+                    }
+                    if (foundInRoot) {
                         break;
                     }
                 }
@@ -636,19 +721,27 @@ async function resolveMixinConfigSources(input) {
             sourceRootCandidates = detected.length > 0 ? detected : ["src/main/java"];
         }
         for (const cls of classNames) {
-            const fqcn = pkg ? `${pkg}.${cls}` : cls;
-            const relativePath = fqcn.replace(/\./g, "/") + ".java";
-            let sourcePath = resolvePath(projectBase, sourceRootCandidates[0], relativePath);
-            for (const root of sourceRootCandidates) {
-                const candidate = resolvePath(projectBase, root, relativePath);
-                if (await pathExists(candidate)) {
-                    sourcePath = candidate;
+            // The entry's own file wins; a `$`-qualified entry without one is a nested class
+            // validated inside its outer file. An entry found nowhere keeps its own path.
+            const candidates = configEntrySourceCandidates(pkg, cls);
+            let resolved;
+            for (const candidate of candidates) {
+                for (const root of sourceRootCandidates) {
+                    const sourcePath = resolvePath(projectBase, root, candidate.relativePath);
+                    if (await pathExists(sourcePath)) {
+                        resolved = { sourcePath, nestedClassPath: candidate.nestedClassPath };
+                        break;
+                    }
+                }
+                if (resolved) {
                     break;
                 }
             }
             results.push({
-                sourcePath,
-                configPath: resolvedConfigPath
+                sourcePath: resolved?.sourcePath ?? resolvePath(projectBase, sourceRootCandidates[0], candidates[0].relativePath),
+                configPath: resolvedConfigPath,
+                nestedClassPath: resolved?.nestedClassPath,
+                entry: cls
             });
         }
     }
@@ -657,6 +750,27 @@ async function resolveMixinConfigSources(input) {
         warnings
     };
 }
+/**
+ * Source files a mixins-config entry may live in, in lookup order, each with the simple-name path
+ * of the entry's class inside it: the entry's own file (a one-element path, so nested mixins in
+ * that file are left to their own entries), then for a nested entry (`Outer$Inner`,
+ * `Outer$Mid$Inner`) the outer class's file.
+ */
+function configEntrySourceCandidates(pkg, cls) {
+    const fqcn = pkg ? `${pkg}.${cls}` : cls;
+    const lastDot = fqcn.lastIndexOf(".");
+    const candidates = [
+        { relativePath: fqcn.replace(/\./g, "/") + ".java", nestedClassPath: [fqcn.slice(lastDot + 1)] }
+    ];
+    const classPath = fqcn.slice(lastDot + 1).split("$");
+    if (classPath.length > 1 && classPath.every((name) => name !== "")) {
+        candidates.push({
+            relativePath: `${fqcn.slice(0, lastDot + 1).replace(/\./g, "/")}${classPath[0]}.java`,
+            nestedClassPath: classPath
+        });
+    }
+    return candidates;
+}
 async function validateMixinMany(svc, mode, entries, input, additionalWarnings, extras = {}) {
     const results = [];
     const batchWarningMode = input.warningMode ?? "aggregated";
@@ -670,6 +784,7 @@ async function validateMixinMany(svc, mode, entries, input, additionalWarnings,
             const singleResult = await svc.validateMixinSingle({
                 ...sharedInput,
                 sourcePath: entry.sourcePath,
+                nestedClassPath: entry.nestedClassPath,
                 warningMode: batchWarningMode,
                 batchCaches,
                 stageEmitter,

package/dist/source/workspace-target.js

@@ -1,15 +1,39 @@
+import { resolve as resolvePath } from "node:path";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError } from "../errors.js";
+import { normalizeOptionalProjectPath } from "../gradle-paths.js";
 import { describeSafeMavenSegmentRule, isSafeMavenSegment } from "../maven-token.js";
+import { computeWorkspaceContextFingerprint } from "../workspace-context-cache.js";
 import { normalizeMapping } from "./shared-utils.js";
 // Env toggles are read at call time, not at module load: tests dynamically
 // re-import source-service.ts with a cache-busting query to flip the flag,
 // but cannot bust this module's cache through that path.
+/**
+ * The root-level files `detectProjectMinecraftVersion`/`detectCompileMapping`/
+ * `detectProjectLoader` (src/workspace-mapping-service.ts) are guaranteed to
+ * read (or attempt to read) for every project, independent of what detection
+ * finds: `gradle.properties` by exact path, and `build.gradle`/`build.gradle.kts`
+ * by exact path as the first two entries of the build-script glob those two
+ * methods both run before descending into subdirectories. `settings.gradle(.kts)`
+ * and `libs.versions.toml` are not read by any of the three, so they are not
+ * listed here - see the coverage note on `fingerprintPaths` below.
+ */
+function fixedDetectionFilenames() {
+    return ["gradle.properties", "build.gradle", "build.gradle.kts"];
+}
 export async function loadOrDetectWorkspaceContext(svc, projectPath) {
     const cached = svc.workspaceContextCache.read(projectPath);
     if (cached && !cached.partial) {
         return cached;
     }
+    const projectRoot = resolvePath(projectPath);
+    // Snapshotted BEFORE detection runs, not after: an edit that lands while
+    // detection is mid-read (racing the very call below) must still show up as
+    // a stat difference on the next read. Fingerprinting after detection would
+    // record whatever is on disk at that later point - which could already be
+    // the edit that should have invalidated the entry, silently absorbing the
+    // race into a "the cache is fresh" fingerprint instead of catching it.
+    const fixedFingerprint = computeWorkspaceContextFingerprint(fixedDetectionFilenames().map((filename) => resolvePath(projectRoot, filename)));
     const [minecraftVersion, mappingResult, loaderResult] = await Promise.all([
         svc.workspaceMappingService.detectProjectMinecraftVersion(projectPath),
         svc.workspaceMappingService.detectCompileMapping({ projectPath }).catch(() => undefined),
@@ -38,6 +62,39 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         });
     }
     const latest = svc.workspaceContextCache.read(projectPath);
+    // Fingerprint the files this detection actually read (or, for the fixed
+    // root set above, attempted to read regardless of outcome), so a later
+    // cache hit can catch an edit made within the TTL instead of serving a
+    // stale minecraftVersion/mapping/loader for up to five more minutes.
+    //
+    // Coverage: `fixedFingerprint` above (taken pre-detection) covers
+    // gradle.properties and a root-level build.gradle/build.gradle.kts,
+    // present or not - editing, creating, or deleting any of those three
+    // always invalidates. mapping/loader detection also globs subproject
+    // build scripts (`**/build.gradle(.kts)`) and, for the loader, mod
+    // descriptor files (`fabric.mod.json`, `quilt.mod.json`,
+    // `META-INF/{mods,neoforge.mods}.toml`) anywhere under the project; only
+    // the ones that actually produced a mapping/loader declaration are known
+    // here (as `evidence[].filePath`) and fingerprinted below. A subproject
+    // build script or descriptor that was scanned but declared nothing is NOT
+    // covered - editing one to newly declare a mapping/loader is not caught
+    // until the TTL expires, same as before this fingerprint existed.
+    // settings.gradle(.kts) and libs.versions.toml are not read by detection
+    // at all, so they are never fingerprinted.
+    const fixedPaths = new Set(fixedFingerprint.map((entry) => entry.path));
+    const evidencePaths = [
+        ...(mappingResult?.evidence.map((entry) => entry.filePath) ?? []),
+        ...(loaderResult?.evidence.map((entry) => entry.filePath) ?? [])
+    ].filter((path) => !fixedPaths.has(resolvePath(path)));
+    const fingerprint = [
+        ...fixedFingerprint,
+        // A path already covered by fixedFingerprint above (taken pre-detection)
+        // is skipped here rather than re-stat-ed post-detection: keeping only
+        // the earlier snapshot is what makes that entry catch a mid-detection
+        // race at all, and a second, later entry for the same path would just
+        // add a redundant stat on every read without changing the result.
+        ...computeWorkspaceContextFingerprint(evidencePaths)
+    ];
     const ctx = {
         projectPath,
         minecraftVersion,
@@ -46,7 +103,8 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         detectedAt: Date.now(),
         evidence,
         dependencyVersions: latest?.dependencyVersions ?? cached?.dependencyVersions ?? new Map(),
-        partial: false
+        partial: false,
+        fingerprint
     };
     svc.workspaceContextCache.write(ctx);
     return ctx;
@@ -61,7 +119,11 @@ export async function synthesizeWorkspaceTarget(svc, input, workspace) {
             }
         });
     }
-    const projectPath = input.projectPath?.trim();
+    // Normalized once, here, and used for everything below: the workspace-context
+    // cache key, the detection reads and the provenance all have to name the same
+    // path. Trimming alone left a Windows-spelled path unreadable on a WSL host
+    // for this target kind while the sibling routes resolved it.
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
@@ -86,10 +148,16 @@ export async function synthesizeWorkspaceTarget(svc, input, workspace) {
                 nextAction: "Set minecraft_version in gradle.properties or pass target.kind=\"version\" with an explicit Minecraft version.",
                 ...buildSuggestedCall({
                     tool: "resolve-artifact",
-                    params: {
-                        target: { kind: "version", value: "<your-mc-version>" },
-                        projectPath
-                    }
+                    params: undefined,
+                    examples: [
+                        {
+                            params: {
+                                target: { kind: "version", value: "<your-mc-version>" },
+                                projectPath
+                            },
+                            reason: "Replace <your-mc-version> with the Minecraft version, or set minecraft_version in gradle.properties."
+                        }
+                    ]
                 })
             }
         });
@@ -226,7 +294,7 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             }
         });
     }
-    const projectPath = input.projectPath?.trim();
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,

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
@@ -109,6 +142,20 @@ export interface JarEntryBuffer {
 export interface JarReaderOpenDeps {
     openZipFile?: (jarPath: string) => Promise<ZipFile>;
 }
+export interface CollectMatchedJarEntriesAsBuffersOptions extends CollectMatchedJarEntriesOptions {
+    /**
+     * Checked only after an entry has been SUCCESSFULLY read and pushed onto the
+     * result (the success path), with the result array so far; returning true
+     * stops the walk immediately, alongside `maxEntries` (whichever triggers
+     * first). Unlike a predicate — which runs before a read is even attempted —
+     * this lets a caller implement a stop condition that depends on which reads
+     * actually succeeded, e.g. "stop once every distinct wanted name has at
+     * least one successful read", so one unreadable copy of a duplicate-named
+     * entry (with `continueOnError: true`) does not block a later readable copy
+     * of the same name from ever being tried.
+     */
+    stopWhen?: (collected: readonly JarEntryBuffer[]) => boolean;
+}
 /**
  * Raw-buffer counterpart of {@link collectMatchedJarEntriesAsUtf8}: opens the jar
  * ONCE and returns the matched entries as raw Buffers (no UTF-8 decode), so binary
@@ -116,7 +163,7 @@ export interface JarReaderOpenDeps {
  * sampled entry. Mirrors the sibling's maxBytes/maxEntries/continueOnError semantics
  * and its finally-close, but takes an injectable open seam for open-count assertions.
  */
-export declare function collectMatchedJarEntriesAsBuffers(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesOptions, deps?: JarReaderOpenDeps): Promise<JarEntryBuffer[]>;
+export declare function collectMatchedJarEntriesAsBuffers(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesAsBuffersOptions, deps?: JarReaderOpenDeps): Promise<JarEntryBuffer[]>;
 export declare function iterateJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): AsyncGenerator<JavaEntryText>;
 export declare function readAllJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): Promise<JavaEntryText[]>;
 export declare function detectFabricLikeInputNamespace(inputJar: string, deps?: JarReaderOpenDeps): Promise<{

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);
@@ -439,6 +497,9 @@ export async function collectMatchedJarEntriesAsBuffers(jarPath, predicate, opti
                 if (maxEntries != null && entries.length >= maxEntries) {
                     return entries;
                 }
+                if (options.stopWhen?.(entries)) {
+                    return entries;
+                }
             }
             catch (error) {
                 if (!options.continueOnError) {
@@ -524,12 +585,41 @@ export async function detectFabricLikeInputNamespace(inputJar, deps = {}) {
     }
     // Read all sampled class entries in a SINGLE jar open instead of re-opening the
     // jar once per entry. The sample set and latin1 decode are unchanged, so scores —
-    // and therefore the detected namespace — are identical.
+    // and therefore the detected namespace — are identical. The walk stops as soon
+    // as every sampled entry has been found instead of always scanning the rest of
+    // the jar.
+    //
+    // The predicate only checks name membership (not distinctness), so a readable
+    // duplicate-named entry can still be pushed. Stopping is instead driven by
+    // `stopWhen`, which runs only in the SUCCESS path (after a read has actually
+    // completed) and tracks distinct COLLECTED names there — not in the predicate,
+    // which runs before a read is attempted. A predicate-based dedup would mark a
+    // name "collected" optimistically before knowing whether its read succeeds; if
+    // the first copy of a duplicate name is unreadable (with `continueOnError:
+    // true`), that would permanently block a later, readable copy of the same name
+    // from ever being tried. The walk still stops once every distinct sampled name
+    // has at least one successful read, or the jar is exhausted.
     const sampleSet = new Set(classEntries);
-    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), { continueOnError: true }, deps);
+    const collectedNames = new Set();
+    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), {
+        continueOnError: true,
+        stopWhen: (collected) => {
+            collectedNames.add(collected[collected.length - 1].filePath);
+            return collectedNames.size >= sampleSet.size;
+        }
+    }, deps);
+    // A readable duplicate of an already-collected name can still have been
+    // pushed above (the predicate does not dedupe); keep only the first
+    // successfully-read copy of each distinct name so each sampled class
+    // contributes to the score exactly once.
+    const seenForScoring = new Set();
     let mojangScore = 0;
     let intermediaryScore = 0;
-    for (const { content } of matched) {
+    for (const { filePath, content } of matched) {
+        if (seenForScoring.has(filePath)) {
+            continue;
+        }
+        seenForScoring.add(filePath);
         const text = content.toString("latin1");
         mojangScore += countMatches(text, /net\/minecraft\/(?:advancements|client|commands|core|data|gametest|nbt|network|recipe|resources|server|sounds|stats|tags|util|world)\//g) * 3;
         intermediaryScore += countMatches(text, /net\/minecraft\/class_\d+/g) * 3;

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;