@adhisang/minecraft-modding-mcp 3.1.1 → 4.0.0

package/dist/mod-search-service.js

@@ -1,5 +1,6 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
 import { validateAndNormalizeJarPath } from "./path-resolver.js";
@@ -9,6 +10,7 @@ const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 200;
 const MAX_QUERY_LENGTH = 200;
 const CONTEXT_LINES = 1;
+const DECOMPILED_JAVA_READ_CONCURRENCY = 8;
 const METHOD_PATTERN = /^\s*(public|private|protected)\s+.*\(/;
 const FIELD_PATTERN = /^\s*(public|private|protected)\s+(?:static\s+)?(?:final\s+)?[\w<>,\[\]?]+\s+\w+\s*[;=]/;
 function buildRegex(query) {
@@ -41,6 +43,9 @@ function extractContext(lines, lineIndex) {
 function filePathToClassName(filePath) {
     return filePath.replace(/\.java$/, "").replaceAll("/", ".");
 }
+function cloneRegex(regex) {
+    return new RegExp(regex.source, regex.flags);
+}
 export class ModSearchService {
     modDecompileService;
     constructor(modDecompileService) {
@@ -112,65 +117,40 @@ export class ModSearchService {
         const hits = [];
         let totalHits = 0;
         let reachedLimit = false;
-        for (const className of classNames) {
+        for (let batchStartIndex = 0; batchStartIndex < classNames.length; batchStartIndex += DECOMPILED_JAVA_READ_CONCURRENCY) {
             if (hits.length >= limit) {
                 reachedLimit = true;
                 break;
             }
-            const filePath = className.replaceAll(".", "/") + ".java";
-            // Class name search: check if the simple class name matches
-            if (searchType === "class" || searchType === "all") {
-                const simpleClassName = className.split(".").pop() ?? className;
-                regex.lastIndex = 0;
-                if (regex.test(simpleClassName)) {
-                    totalHits++;
-                    if (hits.length < limit) {
-                        hits.push({
-                            type: "class",
-                            name: className,
-                            file: filePath
-                        });
-                    }
-                    // If searching only classes, skip content search for this file
-                    if (searchType === "class")
-                        continue;
-                }
-            }
-            // Content/method/field search: read and scan the file
-            if (searchType === "method" || searchType === "field" || searchType === "content" || searchType === "all") {
-                let content;
-                try {
-                    content = readFileSync(join(outputDir, filePath), "utf8");
+            const batchClassNames = classNames.slice(batchStartIndex, batchStartIndex + DECOMPILED_JAVA_READ_CONCURRENCY);
+            const batchHitLimit = Math.max(1, limit - hits.length);
+            const fileResults = await mapWithConcurrencyLimit(batchClassNames, DECOMPILED_JAVA_READ_CONCURRENCY, async (className) => this.searchDecompiledClassFile({
+                className,
+                outputDir,
+                searchType,
+                regex: cloneRegex(regex),
+                maxHits: batchHitLimit
+            }));
+            for (const fileResult of fileResults) {
+                if (hits.length >= limit) {
+                    reachedLimit = true;
+                    break;
                 }
-                catch {
-                    // File might not exist at the expected path, skip
+                if (fileResult.hits.length === 0) {
                     continue;
                 }
-                const lines = content.split("\n");
-                for (let i = 0; i < lines.length; i++) {
-                    if (hits.length >= limit) {
-                        reachedLimit = true;
-                        break;
-                    }
-                    regex.lastIndex = 0;
-                    if (!regex.test(lines[i]))
-                        continue;
-                    const lineType = classifyLine(lines[i]);
-                    // Filter by search type
-                    if (searchType !== "all" && searchType !== lineType)
-                        continue;
-                    totalHits++;
-                    if (hits.length < limit) {
-                        hits.push({
-                            type: lineType,
-                            name: lineType === "content" ? className : extractSymbolName(lines[i], lineType),
-                            file: filePath,
-                            line: i + 1,
-                            context: extractContext(lines, i)
-                        });
-                    }
+                const remaining = limit - hits.length;
+                const acceptedHits = fileResult.hits.slice(0, remaining);
+                hits.push(...acceptedHits);
+                totalHits += acceptedHits.length;
+                if (hits.length >= limit || fileResult.hits.length > remaining) {
+                    reachedLimit = true;
+                    break;
                 }
             }
+            if (reachedLimit) {
+                break;
+            }
         }
         log("info", "mod-search.done", {
             jarPath,
@@ -255,6 +235,59 @@ export class ModSearchService {
             warnings
         };
     }
+    async searchDecompiledClassFile(input) {
+        const hits = [];
+        const filePath = input.className.replaceAll(".", "/") + ".java";
+        if (input.searchType === "class" || input.searchType === "all") {
+            const simpleClassName = input.className.split(".").pop() ?? input.className;
+            input.regex.lastIndex = 0;
+            if (input.regex.test(simpleClassName)) {
+                hits.push({
+                    type: "class",
+                    name: input.className,
+                    file: filePath
+                });
+                if (input.searchType === "class" || hits.length >= input.maxHits) {
+                    return { hits };
+                }
+            }
+        }
+        if (input.searchType !== "method" &&
+            input.searchType !== "field" &&
+            input.searchType !== "content" &&
+            input.searchType !== "all") {
+            return { hits };
+        }
+        let content;
+        try {
+            content = await readFile(join(input.outputDir, filePath), "utf8");
+        }
+        catch {
+            return { hits };
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (hits.length >= input.maxHits) {
+                break;
+            }
+            input.regex.lastIndex = 0;
+            if (!input.regex.test(lines[i])) {
+                continue;
+            }
+            const lineType = classifyLine(lines[i]);
+            if (input.searchType !== "all" && input.searchType !== lineType) {
+                continue;
+            }
+            hits.push({
+                type: lineType,
+                name: lineType === "content" ? input.className : extractSymbolName(lines[i], lineType),
+                file: filePath,
+                line: i + 1,
+                context: extractContext(lines, i)
+            });
+        }
+        return { hits };
+    }
 }
 function extractSymbolName(line, type) {
     const trimmed = line.trim();

package/dist/observability.d.ts

@@ -22,6 +22,7 @@ export interface RuntimeMetricSnapshot {
     get_file_duration_ms: MetricTimingSnapshot;
     list_files_duration_ms: MetricTimingSnapshot;
     decompile_duration_ms: MetricTimingSnapshot;
+    binary_remap_duration_ms: MetricTimingSnapshot;
     search_intent_symbol_duration_ms: MetricTimingSnapshot;
     search_intent_text_duration_ms: MetricTimingSnapshot;
     search_intent_path_duration_ms: MetricTimingSnapshot;
@@ -47,8 +48,13 @@ export interface RuntimeMetricSnapshot {
     cache_artifact_bytes_lru: CacheArtifactByteAccountingRow[];
     cache_hit_rate: number;
     repo_failover_count: number;
+    tool_call_counts: Record<string, number>;
+    tool_call_duration_ms: Record<string, MetricTimingSnapshot>;
+    mapping_resolution_cache_hits: number;
+    mapping_resolution_cache_misses: number;
+    mapping_resolution_cache_size: number;
 }
-type DurationMetricName = keyof Pick<RuntimeMetricSnapshot, "resolve_duration_ms" | "search_duration_ms" | "get_file_duration_ms" | "list_files_duration_ms" | "decompile_duration_ms" | "search_intent_symbol_duration_ms" | "search_intent_text_duration_ms" | "search_intent_path_duration_ms">;
+type DurationMetricName = keyof Pick<RuntimeMetricSnapshot, "resolve_duration_ms" | "search_duration_ms" | "get_file_duration_ms" | "list_files_duration_ms" | "decompile_duration_ms" | "binary_remap_duration_ms" | "search_intent_symbol_duration_ms" | "search_intent_text_duration_ms" | "search_intent_path_duration_ms">;
 export declare class RuntimeMetrics {
     private readonly timings;
     private cacheHits;
@@ -74,6 +80,11 @@ export declare class RuntimeMetrics {
     private cacheEntries;
     private cacheTotalContentBytes;
     private cacheArtifactBytesLruRef;
+    private toolCallCounts;
+    private toolCallTimings;
+    private mappingResolutionCacheHits;
+    private mappingResolutionCacheMisses;
+    private mappingResolutionCacheSize;
     constructor();
     recordDuration(name: DurationMetricName, durationMs: number): void;
     recordArtifactCacheHit(): void;
@@ -97,6 +108,12 @@ export declare class RuntimeMetrics {
     setCacheEntries(entries: number): void;
     setCacheTotalContentBytes(totalBytes: number): void;
     setCacheArtifactByteAccountingRef(entries: ReadonlyArray<CacheArtifactByteAccountingRefRow>): void;
+    recordToolCall(tool: string, durationMs: number): void;
+    setMappingResolutionCacheStats(stats: {
+        hits: number;
+        misses: number;
+        size: number;
+    }): void;
     snapshot(): RuntimeMetricSnapshot;
     private toSnapshot;
     private resolveCacheHitRate;

package/dist/observability.js

@@ -32,6 +32,11 @@ export class RuntimeMetrics {
     cacheEntries = 0;
     cacheTotalContentBytes = 0;
     cacheArtifactBytesLruRef = [];
+    toolCallCounts = new Map();
+    toolCallTimings = new Map();
+    mappingResolutionCacheHits = 0;
+    mappingResolutionCacheMisses = 0;
+    mappingResolutionCacheSize = 0;
     constructor() {
         const names = [
             "resolve_duration_ms",
@@ -39,6 +44,7 @@ export class RuntimeMetrics {
             "get_file_duration_ms",
             "list_files_duration_ms",
             "decompile_duration_ms",
+            "binary_remap_duration_ms",
             "search_intent_symbol_duration_ms",
             "search_intent_text_duration_ms",
             "search_intent_path_duration_ms"
@@ -140,6 +146,27 @@ export class RuntimeMetrics {
     setCacheArtifactByteAccountingRef(entries) {
         this.cacheArtifactBytesLruRef = entries;
     }
+    recordToolCall(tool, durationMs) {
+        this.toolCallCounts.set(tool, (this.toolCallCounts.get(tool) ?? 0) + 1);
+        let timing = this.toolCallTimings.get(tool);
+        if (!timing) {
+            timing = { count: 0, totalMs: 0, lastMs: 0, samples: [] };
+            this.toolCallTimings.set(tool, timing);
+        }
+        const normalizedDuration = Math.max(0, Math.trunc(durationMs));
+        timing.count += 1;
+        timing.totalMs += normalizedDuration;
+        timing.lastMs = normalizedDuration;
+        timing.samples.push(normalizedDuration);
+        if (timing.samples.length > MAX_TIMING_SAMPLES) {
+            timing.samples.shift();
+        }
+    }
+    setMappingResolutionCacheStats(stats) {
+        this.mappingResolutionCacheHits = stats.hits;
+        this.mappingResolutionCacheMisses = stats.misses;
+        this.mappingResolutionCacheSize = stats.size;
+    }
     snapshot() {
         return {
             resolve_duration_ms: this.toSnapshot("resolve_duration_ms"),
@@ -147,6 +174,7 @@ export class RuntimeMetrics {
             get_file_duration_ms: this.toSnapshot("get_file_duration_ms"),
             list_files_duration_ms: this.toSnapshot("list_files_duration_ms"),
             decompile_duration_ms: this.toSnapshot("decompile_duration_ms"),
+            binary_remap_duration_ms: this.toSnapshot("binary_remap_duration_ms"),
             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"),
@@ -175,7 +203,22 @@ export class RuntimeMetrics {
                 updated_at: entry.updatedAt
             })),
             cache_hit_rate: this.resolveCacheHitRate(),
-            repo_failover_count: this.repoFailoverCount
+            repo_failover_count: this.repoFailoverCount,
+            tool_call_counts: Object.fromEntries(this.toolCallCounts),
+            tool_call_duration_ms: Object.fromEntries([...this.toolCallTimings].map(([tool, timing]) => [
+                tool,
+                {
+                    count: timing.count,
+                    totalMs: timing.totalMs,
+                    avgMs: timing.count > 0 ? timing.totalMs / timing.count : 0,
+                    lastMs: timing.lastMs,
+                    p95Ms: percentile(timing.samples, 95),
+                    p99Ms: percentile(timing.samples, 99)
+                }
+            ])),
+            mapping_resolution_cache_hits: this.mappingResolutionCacheHits,
+            mapping_resolution_cache_misses: this.mappingResolutionCacheMisses,
+            mapping_resolution_cache_size: this.mappingResolutionCacheSize
         };
     }
     toSnapshot(name) {

package/dist/response-utils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Compact-mode response utilities.
+ *
+ * Applied at the public boundary (runTool) only — internal service types are never modified.
+ */
+/** Tools that accept the `compact` parameter. */
+export declare const COMPACT_ENABLED_TOOL_NAMES: Set<string>;
+/** Mapping-oriented tools that get additional field projection via compactMappingResponse. */
+export declare const COMPACT_MAPPING_TOOL_NAMES: Set<string>;
+/** Source-oriented tools (get-class-source) that get compactSourceResponse projection. */
+export declare const COMPACT_SOURCE_TOOL_NAMES: Set<string>;
+/** Member-listing tools (get-class-members) that get compactMembersResponse projection. */
+export declare const COMPACT_MEMBERS_TOOL_NAMES: Set<string>;
+/**
+ * Tools that only need the light artifactContents projection (search hits,
+ * file listing). The primary payload is already small; the projection just
+ * drops the artifact-level summary that callers rarely consume.
+ */
+export declare const COMPACT_LIGHT_TOOL_NAMES: Set<string>;
+/**
+ * Double-gated compact check: tool must be in the allowlist AND parsedInput.compact must be true.
+ * Prevents activation on passthrough schemas where Zod doesn't strip unknown keys.
+ */
+export declare function isCompactEnabled(tool: string, parsedInput: unknown): boolean;
+/**
+ * Primary-payload keys that compact mode must preserve per tool, even when
+ * the value is an empty array (no hits, no files, no members). Without this
+ * the generic {@link compactResponse} path would strip `hits: []` / `items: []`
+ * from successful zero-result responses and callers could not distinguish
+ * "empty success" from "field missing".
+ *
+ * Only tools whose primary payload can legitimately be an empty array need
+ * an entry here. `get-class-source` returns `sourceText: string` which is
+ * never stripped by compactResponse.
+ */
+export declare const TOOL_PRESERVE_PAYLOAD_KEYS: Record<string, ReadonlySet<string>>;
+/**
+ * Shallow-strip empty values from a response object.
+ * Only operates on the top level — nested structures are preserved as-is.
+ * Non-plain objects (Date, Map, class instances) are never treated as empty.
+ *
+ * `preserveKeys` names keys whose values MUST survive the strip even if
+ * empty (used by tools whose primary payload is an array that can legitimately
+ * be empty — e.g. zero-hit search, empty file listing). `null` / `undefined`
+ * values are still dropped even for preserved keys, so absent optional
+ * payload fields do not leak through as explicit nulls.
+ */
+export declare function compactResponse(obj: Record<string, unknown>, preserveKeys?: ReadonlySet<string>): Record<string, unknown>;
+/** resolve-artifact compact: omit debug/diagnostic fields. */
+export declare function compactArtifactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** get-class-source compact: drop provenance, artifactContents, qualityFlags. */
+export declare function compactSourceResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** get-class-members compact: drop provenance, artifactContents, qualityFlags, context. */
+export declare function compactMembersResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** Light compact projection: drop the artifactContents summary only. */
+export declare function compactLightResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Mapping tool compact: project candidates for size reduction.
+ *
+ * Resolved-exact path: omit candidates entirely when provably redundant.
+ *   All of: resolved===true, resolvedSymbol exists, single exact candidate, not truncated,
+ *           confidence missing or 1.
+ *
+ * Unresolved/ambiguous path: keep top {@link UNRESOLVED_FULL_DETAIL_LIMIT} candidates with full
+ *   metadata, slim the tail to {kind,symbol,owner,name,descriptor,confidence,matchKind}, and
+ *   surface `candidatesTruncated:true` + `totalCandidateCount` so the caller knows what it's
+ *   seeing.
+ */
+export declare function compactMappingResponse(obj: Record<string, unknown>): Record<string, unknown>;

package/dist/response-utils.js

@@ -0,0 +1,227 @@
+/**
+ * Compact-mode response utilities.
+ *
+ * Applied at the public boundary (runTool) only — internal service types are never modified.
+ */
+/** Tools that accept the `compact` parameter. */
+export const COMPACT_ENABLED_TOOL_NAMES = new Set([
+    "resolve-artifact",
+    "find-mapping",
+    "resolve-method-mapping-exact",
+    "resolve-workspace-symbol",
+    "check-symbol-exists",
+    "get-class-source",
+    "get-class-members",
+    "search-class-source",
+    "list-artifact-files"
+]);
+/** Mapping-oriented tools that get additional field projection via compactMappingResponse. */
+export const COMPACT_MAPPING_TOOL_NAMES = new Set([
+    "find-mapping",
+    "resolve-method-mapping-exact",
+    "resolve-workspace-symbol",
+    "check-symbol-exists"
+]);
+/** Source-oriented tools (get-class-source) that get compactSourceResponse projection. */
+export const COMPACT_SOURCE_TOOL_NAMES = new Set([
+    "get-class-source"
+]);
+/** Member-listing tools (get-class-members) that get compactMembersResponse projection. */
+export const COMPACT_MEMBERS_TOOL_NAMES = new Set([
+    "get-class-members"
+]);
+/**
+ * Tools that only need the light artifactContents projection (search hits,
+ * file listing). The primary payload is already small; the projection just
+ * drops the artifact-level summary that callers rarely consume.
+ */
+export const COMPACT_LIGHT_TOOL_NAMES = new Set([
+    "search-class-source",
+    "list-artifact-files"
+]);
+/**
+ * Double-gated compact check: tool must be in the allowlist AND parsedInput.compact must be true.
+ * Prevents activation on passthrough schemas where Zod doesn't strip unknown keys.
+ */
+export function isCompactEnabled(tool, parsedInput) {
+    if (!COMPACT_ENABLED_TOOL_NAMES.has(tool))
+        return false;
+    if (parsedInput &&
+        typeof parsedInput === "object" &&
+        !Array.isArray(parsedInput) &&
+        parsedInput.compact === true) {
+        return true;
+    }
+    return false;
+}
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Primary-payload keys that compact mode must preserve per tool, even when
+ * the value is an empty array (no hits, no files, no members). Without this
+ * the generic {@link compactResponse} path would strip `hits: []` / `items: []`
+ * from successful zero-result responses and callers could not distinguish
+ * "empty success" from "field missing".
+ *
+ * Only tools whose primary payload can legitimately be an empty array need
+ * an entry here. `get-class-source` returns `sourceText: string` which is
+ * never stripped by compactResponse.
+ */
+export const TOOL_PRESERVE_PAYLOAD_KEYS = {
+    "search-class-source": new Set(["hits"]),
+    "list-artifact-files": new Set(["items"]),
+    "get-class-members": new Set(["members", "counts", "decompiledFallback", "decompiledMemberCounts"])
+};
+/**
+ * Shallow-strip empty values from a response object.
+ * Only operates on the top level — nested structures are preserved as-is.
+ * Non-plain objects (Date, Map, class instances) are never treated as empty.
+ *
+ * `preserveKeys` names keys whose values MUST survive the strip even if
+ * empty (used by tools whose primary payload is an array that can legitimately
+ * be empty — e.g. zero-hit search, empty file listing). `null` / `undefined`
+ * values are still dropped even for preserved keys, so absent optional
+ * payload fields do not leak through as explicit nulls.
+ */
+export function compactResponse(obj, preserveKeys) {
+    if (!isPlainObject(obj))
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (preserveKeys?.has(key)) {
+            result[key] = value;
+            continue;
+        }
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        if (isPlainObject(value) && Object.keys(value).length === 0)
+            continue;
+        result[key] = value;
+    }
+    return result;
+}
+function projectOmitKeys(obj, omit) {
+    const projected = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (omit.has(key))
+            continue;
+        projected[key] = value;
+    }
+    return projected;
+}
+/** Fields to omit from resolve-artifact in compact mode. */
+const ARTIFACT_COMPACT_OMIT_KEYS = new Set([
+    "provenance",
+    "artifactContents",
+    "sampleEntries",
+    "adjacentSourceCandidates",
+    "binaryJarPath",
+    "coordinate",
+    "repoUrl",
+    "resolvedSourceJarPath"
+]);
+/** resolve-artifact compact: omit debug/diagnostic fields. */
+export function compactArtifactResponse(obj) {
+    return projectOmitKeys(obj, ARTIFACT_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from get-class-source in compact mode. */
+const SOURCE_COMPACT_OMIT_KEYS = new Set([
+    "provenance",
+    "artifactContents",
+    "qualityFlags"
+]);
+/** get-class-source compact: drop provenance, artifactContents, qualityFlags. */
+export function compactSourceResponse(obj) {
+    return projectOmitKeys(obj, SOURCE_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from get-class-members in compact mode. */
+const MEMBERS_COMPACT_OMIT_KEYS = new Set([
+    "provenance",
+    "artifactContents",
+    "qualityFlags",
+    "context"
+]);
+/** get-class-members compact: drop provenance, artifactContents, qualityFlags, context. */
+export function compactMembersResponse(obj) {
+    return projectOmitKeys(obj, MEMBERS_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from search-class-source / list-artifact-files in compact mode. */
+const LIGHT_COMPACT_OMIT_KEYS = new Set([
+    "artifactContents"
+]);
+/** Light compact projection: drop the artifactContents summary only. */
+export function compactLightResponse(obj) {
+    return projectOmitKeys(obj, LIGHT_COMPACT_OMIT_KEYS);
+}
+/** Max number of unresolved candidates that get full metadata in compact mode. */
+const UNRESOLVED_FULL_DETAIL_LIMIT = 3;
+/**
+ * Slim projection of a candidate: retains only identification + confidence fields.
+ *
+ * `kind` and `symbol` are part of the public `SymbolReference` / candidate contract that
+ * clients branch on and use as rendering keys, so they MUST survive the slim. The heavy
+ * fields removed here are the cycle-local diagnostic metadata (provenance, context,
+ * ambiguityReasons, warnings on the candidate, etc.) — not the identity fields.
+ */
+function slimCandidate(candidate) {
+    if (!isPlainObject(candidate))
+        return candidate;
+    const picked = {};
+    for (const key of ["kind", "symbol", "owner", "name", "descriptor", "confidence", "matchKind"]) {
+        if (candidate[key] !== undefined) {
+            picked[key] = candidate[key];
+        }
+    }
+    return picked;
+}
+/**
+ * Mapping tool compact: project candidates for size reduction.
+ *
+ * Resolved-exact path: omit candidates entirely when provably redundant.
+ *   All of: resolved===true, resolvedSymbol exists, single exact candidate, not truncated,
+ *           confidence missing or 1.
+ *
+ * Unresolved/ambiguous path: keep top {@link UNRESOLVED_FULL_DETAIL_LIMIT} candidates with full
+ *   metadata, slim the tail to {kind,symbol,owner,name,descriptor,confidence,matchKind}, and
+ *   surface `candidatesTruncated:true` + `totalCandidateCount` so the caller knows what it's
+ *   seeing.
+ */
+export function compactMappingResponse(obj) {
+    const projected = { ...obj };
+    const candidates = projected.candidates;
+    if (projected.resolved === true &&
+        projected.resolvedSymbol !== undefined &&
+        Array.isArray(candidates) &&
+        candidates.length === 1 &&
+        projected.candidateCount === 1 &&
+        !projected.candidatesTruncated) {
+        const candidate = candidates[0];
+        if (candidate &&
+            candidate.matchKind === "exact" &&
+            (candidate.confidence === undefined || candidate.confidence === 1)) {
+            delete projected.candidates;
+            return projected;
+        }
+    }
+    if (projected.resolved === false &&
+        Array.isArray(candidates) &&
+        candidates.length > UNRESOLVED_FULL_DETAIL_LIMIT) {
+        const head = candidates.slice(0, UNRESOLVED_FULL_DETAIL_LIMIT);
+        const tail = candidates.slice(UNRESOLVED_FULL_DETAIL_LIMIT).map(slimCandidate);
+        projected.candidates = [...head, ...tail];
+        // Tail slimming keeps the full candidate array; only metadata was dropped. Use a
+        // dedicated `candidateDetailsTruncated` signal so clients do not confuse it with the
+        // existing `candidatesTruncated` semantics ("more candidates exist than this response
+        // contains"). If the upstream already reported list-level truncation via
+        // `candidatesTruncated`, that value is preserved unchanged.
+        projected.candidateDetailsTruncated = true;
+    }
+    return projected;
+}
+//# sourceMappingURL=response-utils.js.map

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

@@ -2,12 +2,28 @@ export interface JavaEntryText {
     filePath: string;
     content: string;
 }
+export interface JarEntryText {
+    filePath: string;
+    content: string;
+}
+export interface CollectMatchedJarEntriesOptions {
+    maxBytes?: number;
+    maxEntries?: number;
+    continueOnError?: boolean;
+}
+export declare function hasJavaSourceExtension(entryPath: string): boolean;
 export declare class EntryTooLargeError extends Error {
     constructor(entryPath: string, jarPath: string, maxBytes: number);
 }
 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>;
 export declare function readJarEntryAsUtf8(jarPath: string, entryPath: string): Promise<string>;
 export declare function readJarEntryAsBuffer(jarPath: string, entryPath: string): Promise<Buffer>;
+export declare function collectMatchedJarEntriesAsUtf8(jarPath: string, predicate: (entryPath: string) => boolean, options?: CollectMatchedJarEntriesOptions): Promise<JarEntryText[]>;
 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): Promise<{
+    fromNamespace: "intermediary" | "mojang";
+    warnings: string[];
+}>;