@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/lru-list.d.ts

@@ -0,0 +1,31 @@
+/**
+ * O(1) doubly-linked list + Map LRU.
+ * head = oldest, tail = newest.
+ */
+export declare class LruList<T> {
+    private map;
+    private head;
+    private tail;
+    get size(): number;
+    /** O(1) — move to tail (most recent), return value reference. */
+    touch(key: string): T | undefined;
+    /** O(1) — insert or update + move to tail. Returns previous value if existed. */
+    upsert(key: string, value: T): T | undefined;
+    /** O(1) — remove by key, return removed value. */
+    remove(key: string): T | undefined;
+    /** O(1) — peek at oldest (head) without removing. */
+    peekOldest(): {
+        key: string;
+        value: T;
+    } | undefined;
+    /** O(1) — clear all entries. */
+    clear(): void;
+    /** O(n) — iterate oldest → newest. */
+    toArray(): Array<{
+        key: string;
+        value: T;
+    }>;
+    private unlink;
+    private appendToTail;
+    private moveToTail;
+}

package/dist/lru-list.js

@@ -0,0 +1,102 @@
+/**
+ * O(1) doubly-linked list + Map LRU.
+ * head = oldest, tail = newest.
+ */
+export class LruList {
+    map = new Map();
+    head = null;
+    tail = null;
+    get size() {
+        return this.map.size;
+    }
+    /** O(1) — move to tail (most recent), return value reference. */
+    touch(key) {
+        const node = this.map.get(key);
+        if (!node) {
+            return undefined;
+        }
+        this.moveToTail(node);
+        return node.value;
+    }
+    /** O(1) — insert or update + move to tail. Returns previous value if existed. */
+    upsert(key, value) {
+        const existing = this.map.get(key);
+        if (existing) {
+            const prev = existing.value;
+            existing.value = value;
+            this.moveToTail(existing);
+            return prev;
+        }
+        const node = { key, value, prev: null, next: null };
+        this.map.set(key, node);
+        this.appendToTail(node);
+        return undefined;
+    }
+    /** O(1) — remove by key, return removed value. */
+    remove(key) {
+        const node = this.map.get(key);
+        if (!node) {
+            return undefined;
+        }
+        this.unlink(node);
+        this.map.delete(key);
+        return node.value;
+    }
+    /** O(1) — peek at oldest (head) without removing. */
+    peekOldest() {
+        if (!this.head) {
+            return undefined;
+        }
+        return { key: this.head.key, value: this.head.value };
+    }
+    /** O(1) — clear all entries. */
+    clear() {
+        this.map.clear();
+        this.head = null;
+        this.tail = null;
+    }
+    /** O(n) — iterate oldest → newest. */
+    toArray() {
+        const result = [];
+        let current = this.head;
+        while (current) {
+            result.push({ key: current.key, value: current.value });
+            current = current.next;
+        }
+        return result;
+    }
+    unlink(node) {
+        if (node.prev) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+        node.prev = null;
+        node.next = null;
+    }
+    appendToTail(node) {
+        if (!this.tail) {
+            this.head = node;
+            this.tail = node;
+            return;
+        }
+        node.prev = this.tail;
+        this.tail.next = node;
+        this.tail = node;
+    }
+    moveToTail(node) {
+        if (node === this.tail) {
+            return;
+        }
+        this.unlink(node);
+        this.appendToTail(node);
+    }
+}
+//# sourceMappingURL=lru-list.js.map

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

@@ -0,0 +1,54 @@
+/**
+ * Internal types shared between the MappingService class and the parser
+ * modules under `src/mapping/parsers/`. Public mapping API types live in
+ * `src/mapping-service.ts`; this file is intentionally limited to types
+ * the parsers need to operate on indexes.
+ */
+import type { SourceMapping } from "../types.js";
+export type PairKey = `${SourceMapping}->${SourceMapping}`;
+export type MappingSymbolKind = "class" | "field" | "method";
+export type MappingSymbolRecord = {
+    kind: MappingSymbolKind;
+    symbol: string;
+    owner?: string;
+    name: string;
+    descriptor?: string;
+};
+export type DirectionIndex = {
+    exact: Map<string, Set<string>>;
+    normalized: Map<string, Set<string>>;
+    simple: Map<string, Set<string>>;
+    records: Map<string, MappingSymbolRecord>;
+};
+export type MappingLookupSource = "loom-cache" | "maven" | "mojang-client-mappings";
+export type PairRecord = {
+    index: DirectionIndex;
+    source: MappingLookupSource;
+    mappingArtifact: string;
+};
+export declare const MATCH_RANK: {
+    readonly exact: 3;
+    readonly normalized: 2;
+    readonly "simple-name": 1;
+};
+export declare const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
+export declare const MAX_CANDIDATES = 200;
+export type MatchRankKey = keyof typeof MATCH_RANK;
+export type GraphLoadMode = "full" | "obfuscated-mojang-only";
+export type CandidateAccumulator = {
+    key: string;
+    record: MappingSymbolRecord;
+    matchKind: import("./types.js").MappingMatchKind;
+    confidence: number;
+    rank: number;
+};
+export type LoadedGraph = {
+    version: string;
+    priority: import("../types.js").MappingSourcePriority;
+    mode: GraphLoadMode;
+    pairs: Map<PairKey, PairRecord>;
+    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[]>;
+    warnings: string[];
+};

package/dist/mapping/internal-types.js

@@ -0,0 +1,14 @@
+/**
+ * Internal types shared between the MappingService class and the parser
+ * modules under `src/mapping/parsers/`. Public mapping API types live in
+ * `src/mapping-service.ts`; this file is intentionally limited to types
+ * the parsers need to operate on indexes.
+ */
+export const MATCH_RANK = {
+    exact: 3,
+    normalized: 2,
+    "simple-name": 1
+};
+export const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
+export const MAX_CANDIDATES = 200;
+//# sourceMappingURL=internal-types.js.map

package/dist/mapping/loaders/mojang.d.ts

@@ -0,0 +1,2 @@
+import type { MappingLoaderDeps, MappingLoaderResult } from "./types.js";
+export declare function loadMojangPairs(deps: MappingLoaderDeps, version: string): Promise<MappingLoaderResult>;

package/dist/mapping/loaders/mojang.js

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { downloadToCache } from "../../repo-downloader.js";
+import { parseClientMappings } from "../parsers/proguard.js";
+export async function loadMojangPairs(deps, version) {
+    const warnings = [];
+    let metadata;
+    try {
+        metadata = await deps.versionService.resolveVersionMappings(version);
+    }
+    catch (caughtError) {
+        return {
+            pairs: new Map(),
+            warnings: [
+                `Failed to resolve version metadata for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`
+            ],
+            mappingArtifact: `version:${version}`
+        };
+    }
+    const clientMappingsUrl = metadata.clientMappingsUrl ?? metadata.mappingsUrl;
+    if (!clientMappingsUrl) {
+        warnings.push(`Minecraft version "${version}" does not expose client mappings URL.`);
+        return {
+            pairs: new Map(),
+            warnings,
+            mappingArtifact: metadata.versionDetailUrl
+        };
+    }
+    const mappingsPath = join(deps.config.cacheDir, "mappings", version, "client_mappings.txt");
+    if (!existsSync(mappingsPath)) {
+        await mkdir(dirname(mappingsPath), { recursive: true });
+        const downloaded = await downloadToCache(clientMappingsUrl, mappingsPath, {
+            fetchFn: deps.fetchFn,
+            retries: deps.config.fetchRetries,
+            timeoutMs: deps.config.fetchTimeoutMs
+        });
+        if (!downloaded.ok || !downloaded.path) {
+            warnings.push(`Failed to download client mappings from "${clientMappingsUrl}" (status: ${downloaded.statusCode ?? "unknown"}).`);
+            return {
+                pairs: new Map(),
+                warnings,
+                mappingArtifact: clientMappingsUrl
+            };
+        }
+    }
+    try {
+        const content = await readFile(mappingsPath, "utf8");
+        return {
+            pairs: parseClientMappings(content),
+            warnings,
+            mappingArtifact: clientMappingsUrl
+        };
+    }
+    catch (caughtError) {
+        warnings.push(`Failed to parse client mappings for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+        return {
+            pairs: new Map(),
+            warnings,
+            mappingArtifact: clientMappingsUrl
+        };
+    }
+}
+//# sourceMappingURL=mojang.js.map

package/dist/mapping/loaders/tiny-loom.d.ts

@@ -0,0 +1,2 @@
+import type { MappingLoaderResult } from "./types.js";
+export declare function loadTinyPairsFromLoom(version: string, projectPath?: string): Promise<MappingLoaderResult>;

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

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import fastGlob from "fast-glob";
+import { buildVersionSourceSearchRoots } from "../../gradle-paths.js";
+import { effectiveLoomSearchProjectPath } from "../lookup.js";
+import { mergeDirectionIndexes } from "../parsers/symbol-records.js";
+import { parseTinyMappings } from "../parsers/tiny.js";
+const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
+export async function loadTinyPairsFromLoom(version, projectPath) {
+    const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
+    const merged = new Map();
+    const discoveredPaths = new Set();
+    for (const root of searchRoots) {
+        let discovered = [];
+        const versionRoot = join(root, version);
+        try {
+            discovered = existsSync(versionRoot)
+                ? await fastGlob.glob(["**/*.tiny", "**/*.tinyv2"], {
+                    cwd: versionRoot,
+                    absolute: true,
+                    onlyFiles: true
+                })
+                : await fastGlob.glob([`${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tiny`, `${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tinyv2`], {
+                    cwd: root,
+                    absolute: true,
+                    onlyFiles: true
+                });
+        }
+        catch {
+            continue;
+        }
+        const byVersion = discovered
+            .filter((path) => path.replaceAll("\\", "/").includes(`/${version}/`))
+            .sort((left, right) => left.localeCompare(right));
+        if (byVersion.length === 0) {
+            continue;
+        }
+        for (const path of byVersion) {
+            discoveredPaths.add(path);
+            try {
+                const content = await readFile(path, "utf8");
+                const parsed = parseTinyMappings(content);
+                for (const [key, index] of parsed.entries()) {
+                    const existing = merged.get(key);
+                    if (!existing) {
+                        merged.set(key, index);
+                    }
+                    else {
+                        mergeDirectionIndexes(existing, index);
+                    }
+                }
+            }
+            catch {
+                // best effort: skip unreadable or invalid files
+            }
+        }
+    }
+    const orderedPaths = [...discoveredPaths].sort((left, right) => left.localeCompare(right));
+    if (orderedPaths.length > 0) {
+        return {
+            pairs: merged,
+            warnings: [],
+            mappingArtifact: orderedPaths[0]
+        };
+    }
+    return {
+        pairs: new Map(),
+        warnings: [`No Loom tiny mapping files matched version "${version}".`],
+        mappingArtifact: "loom-cache:none"
+    };
+}
+//# sourceMappingURL=tiny-loom.js.map

package/dist/mapping/loaders/tiny-maven.d.ts

@@ -0,0 +1,2 @@
+import type { MappingLoaderDeps, MappingLoaderResult } from "./types.js";
+export declare function loadTinyPairsFromMaven(deps: MappingLoaderDeps, version: string): Promise<MappingLoaderResult>;

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

@@ -0,0 +1,104 @@
+import { defaultDownloadPath, downloadToCache } from "../../repo-downloader.js";
+import { collectMatchedJarEntriesAsUtf8 } from "../../source-jar-reader.js";
+import { mergeDirectionIndexes } from "../parsers/symbol-records.js";
+import { parseTinyMappings } from "../parsers/tiny.js";
+async function fetchYarnCoordinates(fetchFn, repoBase, version) {
+    const metadataUrl = `${repoBase}/net/fabricmc/yarn/maven-metadata.xml`;
+    try {
+        const response = await fetchFn(metadataUrl);
+        if (!response.ok) {
+            return [];
+        }
+        const xml = await response.text();
+        const versions = [...xml.matchAll(/<version>([^<]+)<\/version>/g)]
+            .map((match) => match[1]?.trim() ?? "")
+            .filter((value) => value.startsWith(`${version}+build.`));
+        const sorted = versions.sort((left, right) => {
+            const leftBuild = Number.parseInt(left.split("+build.")[1] ?? "0", 10);
+            const rightBuild = Number.parseInt(right.split("+build.")[1] ?? "0", 10);
+            return rightBuild - leftBuild;
+        });
+        if (sorted.length > 0) {
+            return sorted.slice(0, 3);
+        }
+        return [version];
+    }
+    catch {
+        return [version];
+    }
+}
+async function parseTinyFromJar(jarPath) {
+    const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
+    const merged = new Map();
+    for (const entry of tinyEntries) {
+        try {
+            const parsed = parseTinyMappings(entry.content);
+            for (const [key, index] of parsed.entries()) {
+                const existing = merged.get(key);
+                if (!existing) {
+                    merged.set(key, index);
+                }
+                else {
+                    mergeDirectionIndexes(existing, index);
+                }
+            }
+        }
+        catch {
+            // skip malformed tiny entries
+        }
+    }
+    return merged;
+}
+export async function loadTinyPairsFromMaven(deps, version) {
+    const warnings = [];
+    const merged = new Map();
+    const repos = deps.config.sourceRepos;
+    const intermediaryUrls = [];
+    const yarnUrls = [];
+    const repoBases = repos.map((repo) => repo.replace(/\/+$/, ""));
+    const yarnCoordinatesByRepo = await Promise.all(repoBases.map(async (base) => ({
+        base,
+        yarnCoordinates: await fetchYarnCoordinates(deps.fetchFn, base, version)
+    })));
+    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`);
+        for (const coordinate of yarnCoordinates) {
+            yarnUrls.push(`${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;
+        }
+        return parseTinyFromJar(downloaded.path);
+    }));
+    for (const result of parsedResults) {
+        if (result.status !== "fulfilled" || !result.value) {
+            continue;
+        }
+        for (const [key, index] of result.value.entries()) {
+            const existing = merged.get(key);
+            if (!existing) {
+                merged.set(key, index);
+            }
+            else {
+                mergeDirectionIndexes(existing, index);
+            }
+        }
+    }
+    if (merged.size === 0) {
+        warnings.push(`No Maven tiny mappings could be loaded for "${version}".`);
+    }
+    return {
+        pairs: merged,
+        warnings,
+        mappingArtifact: allUrls[0] ?? "maven:none"
+    };
+}
+//# sourceMappingURL=tiny-maven.js.map

package/dist/mapping/loaders/types.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from "../../types.js";
+import type { VersionService } from "../../version-service.js";
+import type { DirectionIndex, PairKey } from "../internal-types.js";
+export type VersionMappingsResolver = Pick<VersionService, "resolveVersionMappings">;
+export type MappingLoaderDeps = {
+    config: Config;
+    fetchFn: typeof fetch;
+    versionService: VersionMappingsResolver;
+};
+export type MappingLoaderResult = {
+    pairs: Map<PairKey, DirectionIndex>;
+    warnings: string[];
+    mappingArtifact: string;
+};

package/dist/mapping/loaders/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mapping/lookup.d.ts

@@ -0,0 +1,52 @@
+import type { MappingSourcePriority, SourceMapping } from "../types.js";
+import type { CandidateAccumulator, DirectionIndex, 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 };
+export { MAX_CANDIDATES };
+export declare function addCandidates(target: Map<string, CandidateAccumulator>, index: DirectionIndex, symbols: Set<string> | undefined, kind: MatchRankKey, confidence: number): void;
+export declare function lookupCandidates(index: DirectionIndex, query: MappingSymbolRecord): MappingLookupCandidate[];
+export declare function mappingPriorityFromInput(configPriority: MappingSourcePriority, override: MappingSourcePriority | undefined): MappingSourcePriority;
+export declare function mappingSourceOrder(priority: MappingSourcePriority): Array<"loom-cache" | "maven">;
+export declare function requiresOnlyObfuscatedMojangGraph(sourceMapping: SourceMapping, targetMapping?: SourceMapping): boolean;
+export declare function namespacePath(graph: LoadedGraph, sourceMapping: SourceMapping, targetMapping: SourceMapping): SourceMapping[] | undefined;
+export declare function pathUsesSource(pairs: Map<PairKey, PairRecord>, path: SourceMapping[], source: MappingLookupSource): boolean;
+export declare function pathToTransformChain(path: SourceMapping[]): string[];
+export declare function toLookupCandidate(record: MappingSymbolRecord): MappingLookupCandidate;
+export declare function toSymbolReference(record: MappingSymbolRecord): SymbolReference;
+export declare function toResolutionCandidate(candidate: MappingLookupCandidate): SymbolReference & Pick<MappingLookupCandidate, "matchKind" | "confidence">;
+export declare function invalidInputError(message: string, details: Record<string, unknown>): import("../errors.js").AppError;
+export declare function normalizeMemberName(name: string): string;
+/**
+ * Validate a JVM method descriptor such as `(I)V`, `()Lfoo/Bar;`, `(Lfoo/Bar;[I)V`.
+ * Rejects empty strings, missing/mis-positioned parens, empty return type, and invalid base
+ * type tokens so "(" or "()" style half-descriptors surface as ERR_INVALID_INPUT instead of
+ * being silently accepted.
+ */
+export declare function normalizeMethodDescriptor(descriptor: string | undefined): string;
+export declare function isValidMethodDescriptor(descriptor: string): boolean;
+export declare function consumeFieldType(descriptor: string, position: number, allowVoid: boolean): number;
+export declare function normalizeQuerySymbol(input: SymbolQueryInput, signatureMode?: "exact" | "name-only", options?: {
+    allowShortClassName?: boolean;
+}): {
+    record: MappingSymbolRecord;
+    querySymbol: SymbolReference;
+};
+export declare function normalizeOwnerHint(ownerHint: string | undefined): string | undefined;
+export declare function normalizeDescriptorHint(descriptorHint: string | undefined): string | undefined;
+export declare function applyDisambiguationHints(candidates: MappingLookupCandidate[], disambiguation: {
+    ownerHint?: string;
+    descriptorHint?: string;
+} | undefined): 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[];
+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;
+export declare function limitResolutionCandidates(candidates: ResolutionCandidate[], requestedLimit: number | undefined): {
+    candidates: ResolutionCandidate[];
+    candidateCount: number;
+    candidatesTruncated?: boolean;
+};
+export declare function clampRowLimit(limit: number | undefined): number | undefined;