@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.1

package/dist/mapping-service.js

@@ -420,7 +420,7 @@ function parseClientMappings(text) {
 }
 function normalizeTinyNamespace(namespace) {
     const normalized = namespace.trim().toLowerCase();
-    if (normalized === "obfuscated") {
+    if (normalized === "obfuscated" || normalized === "official") {
         return "obfuscated";
     }
     if (normalized === "mojang") {
@@ -590,6 +590,12 @@ function mappingSourceOrder(priority) {
     }
     return ["loom-cache", "maven"];
 }
+function requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) {
+    return sourceMapping !== "intermediary" &&
+        sourceMapping !== "yarn" &&
+        targetMapping !== "intermediary" &&
+        targetMapping !== "yarn";
+}
 function namespacePath(graph, sourceMapping, targetMapping) {
     if (sourceMapping === targetMapping) {
         return [sourceMapping];
@@ -709,7 +715,7 @@ function normalizeMethodDescriptor(descriptor) {
     }
     return normalized;
 }
-function normalizeQuerySymbol(input, signatureMode) {
+function normalizeQuerySymbol(input, signatureMode, options) {
     if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
         throw invalidInputError('kind must be one of "class", "field", or "method".', {
             kind: input.kind
@@ -735,7 +741,7 @@ function normalizeQuerySymbol(input, signatureMode) {
             });
         }
         const className = normalizeMappedSymbolOutput(normalizedName);
-        if (!className.includes(".")) {
+        if (!className.includes(".") && !options?.allowShortClassName) {
             throw invalidInputError("name must be a fully qualified class name when kind=class.", {
                 name: input.name
             });
@@ -905,7 +911,9 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode, {
+            allowShortClassName: input.kind === "class" && input.sourceMapping === "obfuscated"
+        });
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -945,7 +953,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1029,7 +1037,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
@@ -1113,7 +1121,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1214,7 +1222,7 @@ export class MappingService {
             });
         }
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, "full");
         const warnings = [...graph.warnings];
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
         const pathCache = new Map();
@@ -1246,7 +1254,7 @@ export class MappingService {
                 classByMapping[mapping] = mapped[0];
             }
         }
-        const baseMapping = classByMapping.obfuscated ? "obfuscated" : classNameMapping;
+        const baseMapping = classNameMapping;
         const baseClass = classByMapping[baseMapping];
         if (!baseClass) {
             return {
@@ -1435,7 +1443,7 @@ export class MappingService {
                     querySymbol
                 };
             })();
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full");
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
@@ -1640,7 +1648,7 @@ export class MappingService {
         const degradations = [];
         let graph;
         try {
-            graph = await this.loadGraph(input.version, priority);
+            graph = await this.loadGraph(input.version, priority, "full");
         }
         catch {
             return {
@@ -1684,8 +1692,8 @@ export class MappingService {
             degradations
         };
     }
-    async loadGraph(version, priority) {
-        const cacheKey = `${version}|${priority}`;
+    async loadGraph(version, priority, mode) {
+        const cacheKey = `${version}|${priority}|${mode}`;
         const cached = this.graphCache.get(cacheKey);
         if (cached) {
             this.graphCache.delete(cacheKey);
@@ -1696,7 +1704,7 @@ export class MappingService {
         if (existingLock) {
             return existingLock;
         }
-        const buildPromise = this.buildGraph(version, priority);
+        const buildPromise = this.buildGraph(version, priority, mode);
         this.buildLocks.set(cacheKey, buildPromise);
         try {
             const built = await buildPromise;
@@ -1708,11 +1716,12 @@ export class MappingService {
             this.buildLocks.delete(cacheKey);
         }
     }
-    async buildGraph(version, priority) {
+    async buildGraph(version, priority, mode) {
         if (isUnobfuscatedVersion(version)) {
             return {
                 version,
                 priority,
+                mode,
                 pairs: new Map(),
                 adjacency: new Map(),
                 pathCache: new Map(),
@@ -1725,6 +1734,7 @@ export class MappingService {
         const graph = {
             version,
             priority,
+            mode,
             pairs: new Map(),
             adjacency: new Map(),
             pathCache: new Map(),
@@ -1734,27 +1744,29 @@ export class MappingService {
         const mojangLoad = await this.loadMojangPairs(version);
         graph.warnings.push(...mojangLoad.warnings);
         this.mergePairs(graph.pairs, mojangLoad.pairs, "mojang-client-mappings", mojangLoad.mappingArtifact);
-        let tinyLoaded = false;
-        const deferredTinyWarnings = [];
-        for (const source of mappingSourceOrder(priority)) {
-            const tinyLoad = source === "loom-cache"
-                ? await this.loadTinyPairsFromLoom(version)
-                : await this.loadTinyPairsFromMaven(version);
-            if (tinyLoad.pairs.size === 0) {
-                deferredTinyWarnings.push(...tinyLoad.warnings);
-                continue;
+        if (mode === "full") {
+            let tinyLoaded = false;
+            const deferredTinyWarnings = [];
+            for (const source of mappingSourceOrder(priority)) {
+                const tinyLoad = source === "loom-cache"
+                    ? await this.loadTinyPairsFromLoom(version)
+                    : await this.loadTinyPairsFromMaven(version);
+                if (tinyLoad.pairs.size === 0) {
+                    deferredTinyWarnings.push(...tinyLoad.warnings);
+                    continue;
+                }
+                tinyLoaded = true;
+                this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
+                graph.warnings.push(...tinyLoad.warnings);
+                if (deferredTinyWarnings.length > 0) {
+                    graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+                }
+                break;
             }
-            tinyLoaded = true;
-            this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
-            graph.warnings.push(...tinyLoad.warnings);
-            if (deferredTinyWarnings.length > 0) {
-                graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+            if (!tinyLoaded) {
+                graph.warnings.push(...deferredTinyWarnings);
+                graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
             }
-            break;
-        }
-        if (!tinyLoaded) {
-            graph.warnings.push(...deferredTinyWarnings);
-            graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
         }
         graph.adjacency = buildAdjacency(graph.pairs);
         graph.recordsByTarget = buildTargetRecordIndex(graph.pairs);
@@ -1990,6 +2002,15 @@ export class MappingService {
             this.graphCache.delete(oldestKey);
         }
     }
+    releaseGraphCacheEntry(version, sourcePriority) {
+        const normalizedVersion = version.trim();
+        if (!normalizedVersion) {
+            return;
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, sourcePriority);
+        this.graphCache.delete(`${normalizedVersion}|${priority}|full`);
+        this.graphCache.delete(`${normalizedVersion}|${priority}|obfuscated-mojang-only`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Standalone: Tiny v2 mapping file resolution for remapping

package/dist/observability.d.ts

@@ -3,12 +3,19 @@ export interface MetricTimingSnapshot {
     totalMs: number;
     avgMs: number;
     lastMs: number;
+    p95Ms: number;
+    p99Ms: number;
 }
 export interface CacheArtifactByteAccountingRow {
     artifact_id: string;
     content_bytes: number;
     updated_at: string;
 }
+type CacheArtifactByteAccountingRefRow = {
+    artifactId: string;
+    totalContentBytes: number;
+    updatedAt: string;
+};
 export interface RuntimeMetricSnapshot {
     resolve_duration_ms: MetricTimingSnapshot;
     search_duration_ms: MetricTimingSnapshot;
@@ -18,6 +25,10 @@ export interface RuntimeMetricSnapshot {
     search_intent_symbol_duration_ms: MetricTimingSnapshot;
     search_intent_text_duration_ms: MetricTimingSnapshot;
     search_intent_path_duration_ms: MetricTimingSnapshot;
+    search_query_mode_auto_count: number;
+    search_query_mode_token_count: number;
+    search_query_mode_literal_count: number;
+    search_literal_explicit_count: number;
     search_regex_fallback_count: number;
     search_token_bytes_returned: number;
     onehop_expand_count: number;
@@ -43,6 +54,10 @@ export declare class RuntimeMetrics {
     private cacheHits;
     private cacheMisses;
     private repoFailoverCount;
+    private searchQueryModeAutoCount;
+    private searchQueryModeTokenCount;
+    private searchQueryModeLiteralCount;
+    private searchLiteralExplicitCount;
     private searchRegexFallbackCount;
     private searchTokenBytesReturned;
     private oneHopExpandCount;
@@ -58,12 +73,13 @@ export declare class RuntimeMetrics {
     private cacheEvictions;
     private cacheEntries;
     private cacheTotalContentBytes;
-    private cacheArtifactBytesLru;
+    private cacheArtifactBytesLruRef;
     constructor();
     recordDuration(name: DurationMetricName, durationMs: number): void;
     recordArtifactCacheHit(): void;
     recordArtifactCacheMiss(): void;
     recordRepoFailover(): void;
+    recordSearchQueryMode(mode: "auto" | "token" | "literal"): void;
     recordSearchIntentDuration(intent: "symbol" | "text" | "path", durationMs: number): void;
     recordSearchRegexFallback(): void;
     recordSearchTokenBytesReturned(tokenBytes: number): void;
@@ -80,7 +96,7 @@ export declare class RuntimeMetrics {
     recordCacheEviction(count?: number): void;
     setCacheEntries(entries: number): void;
     setCacheTotalContentBytes(totalBytes: number): void;
-    setCacheArtifactByteAccounting(entries: CacheArtifactByteAccountingRow[]): void;
+    setCacheArtifactByteAccountingRef(entries: ReadonlyArray<CacheArtifactByteAccountingRefRow>): void;
     snapshot(): RuntimeMetricSnapshot;
     private toSnapshot;
     private resolveCacheHitRate;

package/dist/observability.js

@@ -1,8 +1,21 @@
+const MAX_TIMING_SAMPLES = 512;
+function percentile(samples, p) {
+    if (samples.length === 0) {
+        return 0;
+    }
+    const sorted = [...samples].sort((left, right) => left - right);
+    const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[index] ?? 0;
+}
 export class RuntimeMetrics {
     timings = new Map();
     cacheHits = 0;
     cacheMisses = 0;
     repoFailoverCount = 0;
+    searchQueryModeAutoCount = 0;
+    searchQueryModeTokenCount = 0;
+    searchQueryModeLiteralCount = 0;
+    searchLiteralExplicitCount = 0;
     searchRegexFallbackCount = 0;
     searchTokenBytesReturned = 0;
     oneHopExpandCount = 0;
@@ -18,7 +31,7 @@ export class RuntimeMetrics {
     cacheEvictions = 0;
     cacheEntries = 0;
     cacheTotalContentBytes = 0;
-    cacheArtifactBytesLru = [];
+    cacheArtifactBytesLruRef = [];
     constructor() {
         const names = [
             "resolve_duration_ms",
@@ -31,7 +44,7 @@ export class RuntimeMetrics {
             "search_intent_path_duration_ms"
         ];
         for (const name of names) {
-            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0 });
+            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0, samples: [] });
         }
     }
     recordDuration(name, durationMs) {
@@ -43,6 +56,10 @@ export class RuntimeMetrics {
         timing.count += 1;
         timing.totalMs += normalizedDuration;
         timing.lastMs = normalizedDuration;
+        timing.samples.push(normalizedDuration);
+        if (timing.samples.length > MAX_TIMING_SAMPLES) {
+            timing.samples.shift();
+        }
     }
     recordArtifactCacheHit() {
         this.cacheHits += 1;
@@ -53,6 +70,20 @@ export class RuntimeMetrics {
     recordRepoFailover() {
         this.repoFailoverCount += 1;
     }
+    recordSearchQueryMode(mode) {
+        switch (mode) {
+            case "auto":
+                this.searchQueryModeAutoCount += 1;
+                break;
+            case "token":
+                this.searchQueryModeTokenCount += 1;
+                break;
+            case "literal":
+                this.searchQueryModeLiteralCount += 1;
+                this.searchLiteralExplicitCount += 1;
+                break;
+        }
+    }
     recordSearchIntentDuration(intent, durationMs) {
         const metricName = intent === "symbol"
             ? "search_intent_symbol_duration_ms"
@@ -106,12 +137,8 @@ export class RuntimeMetrics {
     setCacheTotalContentBytes(totalBytes) {
         this.cacheTotalContentBytes = Math.max(0, Math.trunc(totalBytes));
     }
-    setCacheArtifactByteAccounting(entries) {
-        this.cacheArtifactBytesLru = entries.map((entry) => ({
-            artifact_id: entry.artifact_id,
-            content_bytes: Math.max(0, Math.trunc(entry.content_bytes)),
-            updated_at: entry.updated_at
-        }));
+    setCacheArtifactByteAccountingRef(entries) {
+        this.cacheArtifactBytesLruRef = entries;
     }
     snapshot() {
         return {
@@ -123,6 +150,10 @@ export class RuntimeMetrics {
             search_intent_symbol_duration_ms: this.toSnapshot("search_intent_symbol_duration_ms"),
             search_intent_text_duration_ms: this.toSnapshot("search_intent_text_duration_ms"),
             search_intent_path_duration_ms: this.toSnapshot("search_intent_path_duration_ms"),
+            search_query_mode_auto_count: this.searchQueryModeAutoCount,
+            search_query_mode_token_count: this.searchQueryModeTokenCount,
+            search_query_mode_literal_count: this.searchQueryModeLiteralCount,
+            search_literal_explicit_count: this.searchLiteralExplicitCount,
             search_regex_fallback_count: this.searchRegexFallbackCount,
             search_token_bytes_returned: this.searchTokenBytesReturned,
             onehop_expand_count: this.oneHopExpandCount,
@@ -138,7 +169,11 @@ export class RuntimeMetrics {
             cache_evictions: this.cacheEvictions,
             cache_entries: this.cacheEntries,
             cache_total_content_bytes: this.cacheTotalContentBytes,
-            cache_artifact_bytes_lru: this.cacheArtifactBytesLru,
+            cache_artifact_bytes_lru: this.cacheArtifactBytesLruRef.map((entry) => ({
+                artifact_id: entry.artifactId,
+                content_bytes: Math.max(0, Math.trunc(entry.totalContentBytes)),
+                updated_at: entry.updatedAt
+            })),
             cache_hit_rate: this.resolveCacheHitRate(),
             repo_failover_count: this.repoFailoverCount
         };
@@ -151,7 +186,9 @@ export class RuntimeMetrics {
             count,
             totalMs,
             avgMs: count > 0 ? totalMs / count : 0,
-            lastMs: timing?.lastMs ?? 0
+            lastMs: timing?.lastMs ?? 0,
+            p95Ms: percentile(timing?.samples ?? [], 95),
+            p99Ms: percentile(timing?.samples ?? [], 99)
         };
     }
     resolveCacheHitRate() {

package/dist/source-service.d.ts

@@ -488,7 +488,6 @@ export declare class SourceService {
     private searchTextIntent;
     private searchPathIntent;
     private findSymbolHits;
-    private loadScopedFilePaths;
     private indexedCandidateLimit;
     private indexedCandidateLimitForMatch;
     private extractClassMetadata;
@@ -498,6 +497,8 @@ export declare class SourceService {
     private buildFallbackProvenance;
     private resolveClassNameForLookup;
     private buildClassSourceNotFoundError;
+    private rejectLifecycleClassLikeInput;
+    private releaseLifecycleMappingGraph;
     private resolveToObfuscatedClassName;
     private resolveToObfuscatedMemberName;
     private remapSignatureMembers;