@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/mapping/internal-types.d.ts

@@ -20,6 +20,18 @@ export type DirectionIndex = {
     simple: Map<string, Set<string>>;
     records: Map<string, MappingSymbolRecord>;
 };
+/**
+ * O(1) exact-lookup index over a single target namespace's records, used by
+ * existence checks. `byKey` is keyed by `kind|owner|name` (owner empty for
+ * classes, which key on their FQCN symbol); `classBySimpleName` resolves the
+ * auto-class short-name path. Values are arrays so callers can still tell a
+ * unique match (resolved) from multiple (ambiguous).
+ */
+export type ExactRecordIndex = {
+    byKey: Map<string, MappingSymbolRecord[]>;
+    classBySimpleName: Map<string, MappingSymbolRecord[]>;
+    membersByOwner: Map<string, MappingSymbolRecord[]>;
+};
 export type MappingLookupSource = "loom-cache" | "maven" | "mojang-client-mappings";
 export type PairRecord = {
     index: DirectionIndex;
@@ -50,5 +62,17 @@ export type LoadedGraph = {
     adjacency: Map<import("../types.js").SourceMapping, import("../types.js").SourceMapping[]>;
     pathCache: Map<PairKey, import("../types.js").SourceMapping[] | undefined>;
     recordsByTarget: Map<import("../types.js").SourceMapping, MappingSymbolRecord[]>;
+    /**
+     * Graph-scoped, lazily-built exact-lookup indexes keyed by target namespace.
+     * Populated on first existence check for a namespace; dies with graph eviction.
+     */
+    exactRecordIndex: Map<import("../types.js").SourceMapping, ExactRecordIndex>;
+    /**
+     * Graph-scoped cache of class-to-class descriptor projections, keyed by
+     * `path.join(">") + NUL + internalName`. Value is the projected internal name,
+     * or `null` to memoize an unmapped/ambiguous class. Shared across all member
+     * lookups on this graph; dies with graph eviction.
+     */
+    classProjectionCache: Map<string, string | null>;
     warnings: string[];
 };

package/dist/mapping/loaders/tiny-maven.js

@@ -53,36 +53,62 @@ export async function loadTinyPairsFromMaven(deps, version) {
     const warnings = [];
     const merged = new Map();
     const repos = deps.config.sourceRepos;
-    const intermediaryUrls = [];
-    const yarnUrls = [];
+    const attemptedUrls = [];
     const repoBases = repos.map((repo) => repo.replace(/\/+$/, ""));
     const yarnCoordinatesByRepo = await Promise.all(repoBases.map(async (base) => ({
         base,
         yarnCoordinates: await fetchYarnCoordinates(deps.fetchFn, base, version)
     })));
+    const tryUrls = async (urls) => {
+        for (const url of urls) {
+            attemptedUrls.push(url);
+            try {
+                const downloaded = await downloadToCache(url, defaultDownloadPath(deps.config.cacheDir, url), {
+                    fetchFn: deps.fetchFn,
+                    retries: deps.config.fetchRetries,
+                    timeoutMs: deps.config.fetchTimeoutMs
+                });
+                if (!downloaded.ok || !downloaded.path) {
+                    continue;
+                }
+                const parsed = await parseTinyFromJar(downloaded.path);
+                if (parsed.size > 0) {
+                    return parsed;
+                }
+            }
+            catch {
+                // try the next candidate URL
+            }
+        }
+        return undefined;
+    };
+    let intermediaryParsed;
+    let yarnParsed;
     for (const { base, yarnCoordinates } of yarnCoordinatesByRepo) {
-        intermediaryUrls.push(`${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`, `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`);
+        if (!intermediaryParsed) {
+            intermediaryParsed = await tryUrls([
+                `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`,
+                `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`
+            ]);
+        }
         for (const coordinate of yarnCoordinates) {
-            yarnUrls.push(`${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`, `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`);
+            if (yarnParsed) {
+                break;
+            }
+            yarnParsed = await tryUrls([
+                `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`,
+                `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`
+            ]);
         }
-    }
-    const allUrls = [...intermediaryUrls, ...yarnUrls];
-    const parsedResults = await Promise.allSettled(allUrls.map(async (url) => {
-        const downloaded = await downloadToCache(url, defaultDownloadPath(deps.config.cacheDir, url), {
-            fetchFn: deps.fetchFn,
-            retries: deps.config.fetchRetries,
-            timeoutMs: deps.config.fetchTimeoutMs
-        });
-        if (!downloaded.ok || !downloaded.path) {
-            return undefined;
+        if (intermediaryParsed && yarnParsed) {
+            break;
         }
-        return parseTinyFromJar(downloaded.path);
-    }));
-    for (const result of parsedResults) {
-        if (result.status !== "fulfilled" || !result.value) {
+    }
+    for (const parsed of [intermediaryParsed, yarnParsed]) {
+        if (!parsed) {
             continue;
         }
-        for (const [key, index] of result.value.entries()) {
+        for (const [key, index] of parsed.entries()) {
             const existing = merged.get(key);
             if (!existing) {
                 merged.set(key, index);
@@ -98,7 +124,7 @@ export async function loadTinyPairsFromMaven(deps, version) {
     return {
         pairs: merged,
         warnings,
-        mappingArtifact: allUrls[0] ?? "maven:none"
+        mappingArtifact: attemptedUrls[0] ?? "maven:none"
     };
 }
 //# sourceMappingURL=tiny-maven.js.map

package/dist/mapping/lookup.d.ts

@@ -1,5 +1,5 @@
 import type { MappingSourcePriority, SourceMapping } from "../types.js";
-import type { CandidateAccumulator, DirectionIndex, LoadedGraph, MappingLookupSource, MappingSymbolRecord, MatchRankKey, PairKey, PairRecord } from "./internal-types.js";
+import type { CandidateAccumulator, DirectionIndex, ExactRecordIndex, LoadedGraph, MappingLookupSource, MappingSymbolRecord, MatchRankKey, PairKey, PairRecord } from "./internal-types.js";
 import { MAX_CANDIDATES } from "./internal-types.js";
 import type { ClassApiMatrixKind, DescriptorProjection, MappingLookupCandidate, ResolutionCandidate, SymbolQueryInput, SymbolReference } from "./types.js";
 export type { DescriptorProjection };
@@ -37,10 +37,21 @@ export declare function normalizeDescriptorHint(descriptorHint: string | undefin
 export declare function applyDisambiguationHints(candidates: MappingLookupCandidate[], disambiguation: {
     ownerHint?: string;
     descriptorHint?: string;
-} | undefined): MappingLookupCandidate[];
+} | undefined, warnings?: string[]): MappingLookupCandidate[];
 export declare function projectLookupCandidateDescriptor(candidate: MappingLookupCandidate, sourceDescriptor: string, targetDescriptor: string | undefined): MappingLookupCandidate;
 export declare function effectiveLoomSearchProjectPath(projectPath: string | undefined): string | undefined;
 export declare function collectTargetRecords(graph: LoadedGraph, targetMapping: SourceMapping): MappingSymbolRecord[];
+/**
+ * Lazily build (and memoize on the graph) an O(1) exact-lookup index for a
+ * target namespace. Classes key on their FQCN symbol (owner left empty) and are
+ * additionally indexed by simple name for the auto-class short-name path;
+ * fields/methods key on `kind|owner|name`.
+ */
+export declare function collectExactRecordIndex(graph: LoadedGraph, targetMapping: SourceMapping): ExactRecordIndex;
+export declare function lookupExactClassBySymbol(index: ExactRecordIndex, symbol: string): MappingSymbolRecord[];
+export declare function lookupExactMembersByOwner(index: ExactRecordIndex, owner: string): MappingSymbolRecord[];
+export declare function lookupExactClassBySimpleName(index: ExactRecordIndex, name: string): MappingSymbolRecord[];
+export declare function lookupExactMembers(index: ExactRecordIndex, kind: "field" | "method", owner: string, name: string): MappingSymbolRecord[];
 export declare function normalizeIncludedKinds(inputKinds: ClassApiMatrixKind[] | undefined): Set<ClassApiMatrixKind>;
 export declare function inferAmbiguityReasons(candidates: ResolutionCandidate[], usedMojangClientMappings: boolean): string[];
 export declare function clampCandidateLimit(limit: number | undefined): number;

package/dist/mapping/lookup.js

@@ -376,7 +376,7 @@ export function normalizeDescriptorHint(descriptorHint) {
     const normalized = descriptorHint?.trim();
     return normalized || undefined;
 }
-export function applyDisambiguationHints(candidates, disambiguation) {
+export function applyDisambiguationHints(candidates, disambiguation, warnings) {
     if (!disambiguation || candidates.length <= 1) {
         return candidates;
     }
@@ -400,6 +400,12 @@ export function applyDisambiguationHints(candidates, disambiguation) {
         if (descriptorMatched.length > 0) {
             filtered = descriptorMatched;
         }
+        else {
+            // Candidate descriptors are projected toward the target namespace, so a hint
+            // written in another namespace silently matches nothing. Surface that instead
+            // of leaving the ambiguity unexplained.
+            warnings?.push(`descriptorHint "${descriptorHint}" matched none of the ${filtered.length} candidate descriptor(s); it may be in a different mapping namespace. Hint ignored.`);
+        }
     }
     return filtered;
 }
@@ -423,7 +429,59 @@ export function effectiveLoomSearchProjectPath(projectPath) {
     return normalizeOptionalProjectPath(projectPath) ?? normalizeOptionalProjectPath(process.cwd());
 }
 export function collectTargetRecords(graph, targetMapping) {
-    return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
+    return graph.recordsByTarget.get(targetMapping) ?? [];
+}
+function exactRecordKey(kind, owner, name) {
+    return `${kind}|${owner}|${name}`;
+}
+/**
+ * Lazily build (and memoize on the graph) an O(1) exact-lookup index for a
+ * target namespace. Classes key on their FQCN symbol (owner left empty) and are
+ * additionally indexed by simple name for the auto-class short-name path;
+ * fields/methods key on `kind|owner|name`.
+ */
+export function collectExactRecordIndex(graph, targetMapping) {
+    const cached = graph.exactRecordIndex.get(targetMapping);
+    if (cached) {
+        return cached;
+    }
+    const byKey = new Map();
+    const classBySimpleName = new Map();
+    const membersByOwner = new Map();
+    const push = (map, key, record) => {
+        const bucket = map.get(key);
+        if (bucket) {
+            bucket.push(record);
+        }
+        else {
+            map.set(key, [record]);
+        }
+    };
+    for (const record of collectTargetRecords(graph, targetMapping)) {
+        if (record.kind === "class") {
+            push(byKey, exactRecordKey("class", "", record.symbol), record);
+            push(classBySimpleName, record.name, record);
+        }
+        else {
+            push(byKey, exactRecordKey(record.kind, record.owner ?? "", record.name), record);
+            push(membersByOwner, record.owner ?? "", record);
+        }
+    }
+    const index = { byKey, classBySimpleName, membersByOwner };
+    graph.exactRecordIndex.set(targetMapping, index);
+    return index;
+}
+export function lookupExactClassBySymbol(index, symbol) {
+    return index.byKey.get(exactRecordKey("class", "", symbol)) ?? [];
+}
+export function lookupExactMembersByOwner(index, owner) {
+    return index.membersByOwner.get(owner) ?? [];
+}
+export function lookupExactClassBySimpleName(index, name) {
+    return index.classBySimpleName.get(name) ?? [];
+}
+export function lookupExactMembers(index, kind, owner, name) {
+    return index.byKey.get(exactRecordKey(kind, owner, name)) ?? [];
 }
 export function normalizeIncludedKinds(inputKinds) {
     const normalized = new Set();

package/dist/mapping/types.d.ts

@@ -55,6 +55,7 @@ export type FindMappingInput = {
     name: string;
     owner?: string;
     descriptor?: string;
+    nameMode?: "fqcn" | "auto";
     signatureMode?: "exact" | "name-only";
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
@@ -103,6 +104,7 @@ export type ClassApiMatrixInput = {
     gradleUserHome?: string;
     includeKinds?: ClassApiMatrixKind[];
     maxRows?: number;
+    cursor?: string;
 };
 export type ClassApiMatrixEntry = {
     symbol: string;
@@ -127,6 +129,10 @@ export type ClassApiMatrixOutput = {
     rows: ClassApiMatrixRow[];
     rowCount: number;
     rowsTruncated?: boolean;
+    /** Continuation cursor when more rows remain; pass back as cursor for the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     warnings: string[];
     ambiguousRowCount?: number;
 };

package/dist/mapping-service.d.ts

@@ -14,11 +14,21 @@ export declare class MappingService {
     private static readonly RESOLUTION_CACHE_TTL_MS;
     private resolutionCacheHits;
     private resolutionCacheMisses;
+    private classProjectionComputes;
+    private apiMatrixRowMaps;
     get resolutionCacheStats(): {
         hits: number;
         misses: number;
         size: number;
     };
+    /** Test seam: counts genuine class-projection computes (cache misses). */
+    get classProjectionStats(): {
+        computes: number;
+    };
+    /** Test seam: counts genuine per-row cross-namespace path walks in getClassApiMatrix. */
+    get apiMatrixStats(): {
+        rowMaps: number;
+    };
     constructor(config: Config, versionService?: VersionMappingsResolver, fetchFn?: typeof fetch);
     findMapping(input: FindMappingInput): Promise<FindMappingOutput>;
     ensureMappingAvailable(input: EnsureMappingAvailableInput): Promise<EnsureMappingAvailableOutput>;
@@ -60,13 +70,27 @@ export declare class MappingService {
     private buildResolutionCacheKey;
     private trimResolutionCache;
 }
+export type ResolvedTinyMapping = {
+    path: string;
+    coordinate?: string;
+};
 /**
  * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.
  *
+ * Intermediary is version-keyed (immutable per release). Yarn is coordinate-keyed:
+ * Fabric publishes incrementing yarn builds for the same MC version, so the tiny
+ * is cached at `mappings/yarn/${coordinate}.tiny` and the newest coordinate is
+ * re-checked once per {@link YARN_METADATA_TTL_MS}. The resolved yarn coordinate
+ * is returned so callers can key their own caches on the actual mappings used.
+ *
  * @param version - Minecraft version (e.g. "1.20.4")
  * @param mapping - "intermediary" or "yarn"
  * @param cacheDir - The application cache directory
  * @param fetchFn - Optional fetch implementation for testing
- * @returns Path to the extracted Tiny v2 file
+ * @param options - forceRefresh bypasses the yarn metadata TTL; now overrides the clock (testing)
+ * @returns The extracted Tiny v2 path and, for yarn, the resolved build coordinate
  */
-export declare function resolveTinyMappingFile(version: string, mapping: "intermediary" | "yarn", cacheDir: string, fetchFn?: typeof fetch): Promise<string>;
+export declare function resolveTinyMappingFile(version: string, mapping: "intermediary" | "yarn", cacheDir: string, fetchFn?: typeof fetch, options?: {
+    forceRefresh?: boolean;
+    now?: () => number;
+}): Promise<ResolvedTinyMapping>;