@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/storage/files-repo.js

@@ -67,18 +67,21 @@ function parseSearchCursor(cursor) {
         });
     }
 }
-function nextCursorFromRows(rows) {
-    if (rows.length === 0) {
+function nextCursorFromRows(rows, limit) {
+    if (rows.length === 0 || rows.length < limit) {
         return undefined;
     }
     const last = rows[rows.length - 1];
     return buildCursor(last.file_path);
 }
+function compareFilePaths(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 function compareSearchOrdering(left, right) {
     if (right.score !== left.score) {
         return right.score - left.score;
     }
-    return left.filePath.localeCompare(right.filePath);
+    return compareFilePaths(left.filePath, right.filePath);
 }
 function isAfterSearchCursor(hit, cursor) {
     if (hit.score < cursor.score) {
@@ -87,7 +90,7 @@ function isAfterSearchCursor(hit, cursor) {
     if (hit.score > cursor.score) {
         return false;
     }
-    return hit.filePath.localeCompare(cursor.filePath) > 0;
+    return compareFilePaths(hit.filePath, cursor.filePath) > 0;
 }
 function buildPreview(content, query) {
     const normalizedQuery = query.toLowerCase();
@@ -121,6 +124,10 @@ function buildIndexedMatchQuery(query, match) {
         return token;
     }).join(" ");
 }
+/** Escape LIKE wildcards so the needle is matched literally under ESCAPE '\'. */
+function escapeLikeNeedle(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
 export class FilesRepo {
     db;
     deleteStmt;
@@ -129,9 +136,14 @@ export class FilesRepo {
     listStmt;
     listRowsStmt;
     searchPathStmt;
+    searchContentLikePathsStmt;
     searchFtsStmt;
     getByPathsStmtCache = new Map();
     classLookupStmtCache = new Map();
+    // Fixed-SQL statements built outside the constructor; cached (LRU by SQL text)
+    // so hot paths do not re-prepare per call.
+    dynamicStmtCache = new Map();
+    static DYNAMIC_STMT_CACHE_MAX = 64;
     constructor(db) {
         this.db = db;
         this.deleteStmt = this.db.prepare(`
@@ -150,14 +162,14 @@ export class FilesRepo {
         this.listStmt = this.db.prepare(`
       SELECT artifact_id, file_path
       FROM files
-      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY file_path ASC
       LIMIT ?
     `);
         this.listRowsStmt = this.db.prepare(`
       SELECT artifact_id, file_path, content, content_bytes, content_hash
       FROM files
-      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY file_path ASC
       LIMIT ?
     `);
@@ -167,6 +179,13 @@ export class FilesRepo {
       WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'
       ORDER BY file_path ASC
       LIMIT ?
+    `);
+        this.searchContentLikePathsStmt = this.db.prepare(`
+      SELECT file_path
+      FROM files
+      WHERE artifact_id = ? AND content LIKE ? ESCAPE '\\'
+      ORDER BY file_path ASC
+      LIMIT ?
     `);
         this.searchFtsStmt = this.db.prepare(`
       SELECT file_path, rank
@@ -176,6 +195,23 @@ export class FilesRepo {
       LIMIT ?
     `);
     }
+    prepareCached(sql) {
+        const cached = this.dynamicStmtCache.get(sql);
+        if (cached) {
+            // Refresh recency so hot statements survive eviction.
+            this.dynamicStmtCache.delete(sql);
+            this.dynamicStmtCache.set(sql, cached);
+            return cached;
+        }
+        const stmt = this.db.prepare(sql);
+        this.dynamicStmtCache.set(sql, stmt);
+        if (this.dynamicStmtCache.size > FilesRepo.DYNAMIC_STMT_CACHE_MAX) {
+            const oldest = this.dynamicStmtCache.keys().next().value;
+            if (oldest !== undefined)
+                this.dynamicStmtCache.delete(oldest);
+        }
+        return stmt;
+    }
     clearFilesForArtifact(artifactId) {
         this.deleteStmt.run([artifactId]);
     }
@@ -219,15 +255,15 @@ export class FilesRepo {
     }
     listFiles(artifactId, options) {
         const cursor = parseCursor(options.cursor);
-        const rows = this.listStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        const rows = this.listStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix != null ? `${escapeLikeNeedle(options.prefix)}%` : "", Math.max(1, options.limit));
         return {
             items: rows.map((row) => row.file_path),
-            nextCursor: nextCursorFromRows(rows)
+            nextCursor: nextCursorFromRows(rows, Math.max(1, options.limit))
         };
     }
     listFileRows(artifactId, options) {
         const cursor = parseCursor(options.cursor);
-        const rows = this.listRowsStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        const rows = this.listRowsStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix != null ? `${escapeLikeNeedle(options.prefix)}%` : "", Math.max(1, options.limit));
         return {
             items: rows.map((row) => ({
                 artifactId: row.artifact_id,
@@ -236,9 +272,21 @@ export class FilesRepo {
                 contentBytes: row.content_bytes,
                 contentHash: row.content_hash
             })),
-            nextCursor: nextCursorFromRows(rows)
+            nextCursor: nextCursorFromRows(rows, Math.max(1, options.limit))
         };
     }
+    /**
+     * Narrow the literal/contains text-scan candidate set without hydrating content:
+     * returns the file_paths whose content matches `content LIKE %needle%` (ASCII
+     * case-insensitive). The result is a SUPERSET of the JS contains/exact match set
+     * for an ASCII needle, so callers MUST still run the exact JS post-verify. Only
+     * file_path is selected — content stays in the DB until getFileContentsByPaths.
+     */
+    searchContentLikeCandidatePaths(artifactId, needle, limit) {
+        const pattern = `%${escapeLikeNeedle(needle)}%`;
+        const rows = this.searchContentLikePathsStmt.all(artifactId, pattern, Math.max(1, limit));
+        return { filePaths: rows.map((row) => row.file_path), scannedRows: rows.length };
+    }
     getFileContentsByPaths(artifactId, filePaths) {
         if (filePaths.length === 0) {
             return [];
@@ -264,7 +312,7 @@ export class FilesRepo {
             return { items: [], nextCursor: undefined, scannedRows: 0, dbRoundtrips: 0 };
         }
         const cursor = parseSearchCursor(options.cursor);
-        const likeQuery = `%${normalized}%`;
+        const likeQuery = `%${escapeLikeNeedle(normalized)}%`;
         const ftsQuery = buildIndexedMatchQuery(normalized, options.match);
         const mode = options.mode ?? "mixed";
         // Cursor-adaptive fetch limit: when no cursor, use a generous limit;
@@ -274,28 +322,11 @@ export class FilesRepo {
         const fetchLimit = baseFetchLimit;
         // When cursor score is below all possible bands, skip both queries
         const cursorExhausted = cursor != null && cursor.score < 100;
-        // Skip path query entirely when cursor is within the content-only tier
-        const cursorPastPath = cursor != null && cursor.score < 120;
-        const includePath = mode !== "text" && !cursorExhausted && !cursorPastPath;
+        const includePath = mode !== "text" && !cursorExhausted;
         const includeContent = mode !== "path" && !cursorExhausted;
-        // Path query: push cursor into SQL when cursor.score == 120 (within path tier)
-        let pathRows;
-        if (includePath && cursor && cursor.score === 120) {
-            // Cursor is within the path tier — only fetch paths after cursor.filePath
-            pathRows = this.db.prepare(`
-        SELECT file_path
-        FROM files
-        WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\' AND file_path > ?
-        ORDER BY file_path ASC
-        LIMIT ?
-      `).all(artifactId, likeQuery, cursor.filePath, fetchLimit);
-        }
-        else if (includePath) {
-            pathRows = this.searchPathStmt.all(artifactId, likeQuery, fetchLimit);
-        }
-        else {
-            pathRows = [];
-        }
+        const pathRows = includePath
+            ? this.searchPathStmt.all(artifactId, likeQuery, fetchLimit)
+            : [];
         const merged = pathRows.map((row) => ({
             filePath: row.file_path,
             score: 120,
@@ -393,7 +424,7 @@ export class FilesRepo {
             return 0;
         }
         try {
-            const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, ftsQuery);
+            const row = this.prepareCached(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, ftsQuery);
             return row?.cnt ?? 0;
         }
         catch {
@@ -409,8 +440,8 @@ export class FilesRepo {
         if (!normalized) {
             return 0;
         }
-        const likeQuery = `%${normalized}%`;
-        const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'`).get(artifactId, likeQuery);
+        const likeQuery = `%${escapeLikeNeedle(normalized)}%`;
+        const row = this.prepareCached(`SELECT COUNT(*) AS cnt FROM files WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'`).get(artifactId, likeQuery);
         return row?.cnt ?? 0;
     }
     findFirstFilePathByName(artifactId, fileName) {
@@ -418,8 +449,7 @@ export class FilesRepo {
         if (!normalized) {
             return undefined;
         }
-        const row = this.db
-            .prepare(`
+        const row = this.prepareCached(`
         SELECT file_path
         FROM files
         WHERE artifact_id = ?

package/dist/storage/symbols-repo.d.ts

@@ -22,6 +22,12 @@ export interface FindScopedSymbolsOptions {
     query: string;
     match: ScopedSymbolMatch;
     symbolKind?: string;
+    /**
+     * Restrict results to these symbol kinds via a bound `symbol_kind IN (...)` clause.
+     * Combined with the singular `symbolKind` it ANDs (both apply). An empty array is
+     * ignored (degrades to no kind filter) to avoid emitting an invalid `IN ()`.
+     */
+    symbolKinds?: string[];
     packagePrefix?: string;
     filePathLike?: string;
     limit?: number;
@@ -40,12 +46,21 @@ export declare class SymbolsRepo {
     private readonly listByArtifactStmt;
     private readonly listByArtifactKindStmt;
     private readonly listByFileStmt;
+    private readonly dynamicStmtCache;
+    private static readonly DYNAMIC_STMT_CACHE_MAX;
     constructor(db: SqliteDatabase);
+    private prepareCached;
     clearSymbolsForArtifact(artifactId: string): void;
     insertSymbolsForArtifact(artifactId: string, symbols: IndexedSymbol[]): void;
     replaceSymbolsForArtifact(artifactId: string, symbols: IndexedSymbol[]): void;
     findSymbols(options: FindSymbolsOptions): PagedResult<SymbolRow>;
     listSymbolsForArtifact(artifactId: string, symbolKind?: string): SymbolRow[];
+    /**
+     * Streaming variant of listSymbolsForArtifact: rows are mapped lazily so callers
+     * that filter (e.g. regex symbol search) never materialize the full symbol set.
+     * Do not run other statements on this connection while consuming the iterator.
+     */
+    iterateSymbolsForArtifact(artifactId: string, symbolKind?: string): IterableIterator<SymbolRow>;
     listSymbolsForFile(artifactId: string, filePath: string): SymbolRow[];
     listSymbolsForFiles(artifactId: string, filePaths: string[], symbolKind?: string): Map<string, SymbolRow[]>;
     findBySymbolNames(artifactId: string, symbolNames: string[]): SymbolRow[];

package/dist/storage/symbols-repo.js

@@ -60,6 +60,10 @@ export class SymbolsRepo {
     listByArtifactStmt;
     listByArtifactKindStmt;
     listByFileStmt;
+    // Dynamic WHERE-clause builders produce a small bounded set of SQL strings;
+    // cache their prepared statements (LRU by SQL text) instead of re-preparing per call.
+    dynamicStmtCache = new Map();
+    static DYNAMIC_STMT_CACHE_MAX = 64;
     constructor(db) {
         this.db = db;
         this.deleteStmt = this.db.prepare(`
@@ -106,6 +110,23 @@ export class SymbolsRepo {
       ORDER BY line ASC, symbol_name ASC
     `);
     }
+    prepareCached(sql) {
+        const cached = this.dynamicStmtCache.get(sql);
+        if (cached) {
+            // Refresh recency so hot statements survive eviction.
+            this.dynamicStmtCache.delete(sql);
+            this.dynamicStmtCache.set(sql, cached);
+            return cached;
+        }
+        const stmt = this.db.prepare(sql);
+        this.dynamicStmtCache.set(sql, stmt);
+        if (this.dynamicStmtCache.size > SymbolsRepo.DYNAMIC_STMT_CACHE_MAX) {
+            const oldest = this.dynamicStmtCache.keys().next().value;
+            if (oldest !== undefined)
+                this.dynamicStmtCache.delete(oldest);
+        }
+        return stmt;
+    }
     clearSymbolsForArtifact(artifactId) {
         this.deleteStmt.run([artifactId]);
     }
@@ -150,7 +171,7 @@ export class SymbolsRepo {
         LIMIT ?
       `;
             const nameParam = options.exact ? symbolName : `${symbolName}%`;
-            rows = this.db.prepare(sql).all(options.artifactId, options.symbolKind ?? "", options.symbolKind ?? "", nameParam, cursor.symbolName, cursor.symbolName, cursor.filePath, cursor.symbolName, cursor.filePath, cursor.line, Math.max(1, fetchLimit));
+            rows = this.prepareCached(sql).all(options.artifactId, options.symbolKind ?? "", options.symbolKind ?? "", nameParam, cursor.symbolName, cursor.symbolName, cursor.filePath, cursor.symbolName, cursor.filePath, cursor.line, Math.max(1, fetchLimit));
         }
         else {
             const queryRows = options.exact ? this.searchExactStmt : this.searchStmt;
@@ -173,16 +194,26 @@ export class SymbolsRepo {
         };
     }
     listSymbolsForArtifact(artifactId, symbolKind) {
+        return [...this.iterateSymbolsForArtifact(artifactId, symbolKind)];
+    }
+    /**
+     * Streaming variant of listSymbolsForArtifact: rows are mapped lazily so callers
+     * that filter (e.g. regex symbol search) never materialize the full symbol set.
+     * Do not run other statements on this connection while consuming the iterator.
+     */
+    *iterateSymbolsForArtifact(artifactId, symbolKind) {
         const rows = (symbolKind
-            ? this.listByArtifactKindStmt.all(artifactId, symbolKind)
-            : this.listByArtifactStmt.all(artifactId));
-        return rows.map((row) => toSymbolRow(artifactId, {
-            filePath: row.file_path,
-            symbolKind: row.symbol_kind,
-            symbolName: row.symbol_name,
-            qualifiedName: row.qualified_name ?? undefined,
-            line: row.line
-        }));
+            ? this.listByArtifactKindStmt.iterate(artifactId, symbolKind)
+            : this.listByArtifactStmt.iterate(artifactId));
+        for (const row of rows) {
+            yield toSymbolRow(artifactId, {
+                filePath: row.file_path,
+                symbolKind: row.symbol_kind,
+                symbolName: row.symbol_name,
+                qualifiedName: row.qualified_name ?? undefined,
+                line: row.line
+            });
+        }
     }
     listSymbolsForFile(artifactId, filePath) {
         const rows = this.listByFileStmt.all(artifactId, filePath);
@@ -209,7 +240,7 @@ export class SymbolsRepo {
       ORDER BY file_path ASC, line ASC, symbol_name ASC
     `;
         const params = symbolKind ? [artifactId, ...uniqueFilePaths, symbolKind] : [artifactId, ...uniqueFilePaths];
-        const rows = this.db.prepare(sql).all(...params);
+        const rows = this.prepareCached(sql).all(...params);
         const byFile = new Map();
         for (const row of rows) {
             const bucket = byFile.get(row.file_path) ?? [];
@@ -230,8 +261,7 @@ export class SymbolsRepo {
             return [];
         }
         const placeholders = unique.map(() => "?").join(", ");
-        const rows = this.db
-            .prepare(`
+        const rows = this.prepareCached(`
         SELECT file_path, symbol_kind, symbol_name, qualified_name, line
         FROM symbols
         WHERE artifact_id = ?
@@ -260,6 +290,12 @@ export class SymbolsRepo {
             where.push("symbol_kind = ?");
             params.push(options.symbolKind);
         }
+        const symbolKinds = options.symbolKinds;
+        if (symbolKinds && symbolKinds.length > 0) {
+            const placeholders = symbolKinds.map(() => "?").join(", ");
+            where.push(`symbol_kind IN (${placeholders})`);
+            params.push(...symbolKinds);
+        }
         if (options.packagePrefix?.trim()) {
             const normalizedPrefix = options.packagePrefix.replace(/\.+/g, "/").replace(/\/+$/, "");
             where.push("file_path LIKE ? ESCAPE '\\'");
@@ -300,7 +336,7 @@ export class SymbolsRepo {
       ORDER BY symbol_name ASC, file_path ASC, line ASC
       LIMIT ?
     `;
-        const rows = this.db.prepare(sql).all(...params);
+        const rows = this.prepareCached(sql).all(...params);
         const hasMore = rows.length > rawLimit;
         const page = hasMore ? rows.slice(0, rawLimit) : rows;
         const lastRow = page.length > 0 ? page[page.length - 1] : undefined;
@@ -354,12 +390,11 @@ export class SymbolsRepo {
       WHERE artifact_id = ?
       ${where.length > 0 ? `AND ${where.join("\n      AND ")}` : ""}
     `;
-        const row = this.db.prepare(sql).get(...params);
+        const row = this.prepareCached(sql).get(...params);
         return row?.cnt ?? 0;
     }
     listDistinctFilePathsByKind(artifactId, symbolKind) {
-        const rows = this.db
-            .prepare(`
+        const rows = this.prepareCached(`
         SELECT DISTINCT file_path
         FROM symbols
         WHERE artifact_id = ? AND symbol_kind = ?
@@ -374,8 +409,7 @@ export class SymbolsRepo {
         if (!normalizedClassName || !normalizedSimpleName) {
             return undefined;
         }
-        const row = this.db
-            .prepare(`
+        const row = this.prepareCached(`
         SELECT file_path
         FROM symbols
         WHERE artifact_id = ?

package/dist/symbols/symbol-extractor.js

@@ -1,6 +1,26 @@
-const CLASS_DECLARATION = /^(?:\s*@[\w.]+\s+)*(?:\s*(?:public|private|protected|abstract|final|sealed|non-sealed|static)\s+)*\s*(class|interface|enum|record)\s+([A-Za-z_$][\w$]*)/;
-const METHOD_DECLARATION = /^(?:\s*@[\w.]+\s+)*[^{;]*?\b([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?:\{|;)/;
-const FIELD_DECLARATION = /^(?:\s*@[\w.]+\s+)*[^\s][\w<>\[\],.?]+\s+([A-Za-z_$][\w$]*)\s*(?:=|;|,)/;
+// A type token may carry spaced generics (Map<String, Integer>), arrays (int[][]),
+// wildcards (List<? extends Foo>), and FQNs (java.util.Map). It must not contain "=".
+const TYPE_TOKEN = "[\\w.$][\\w.$<>\\[\\],?\\s]*";
+const MODIFIER = "(?:public|private|protected|abstract|final|static|native|synchronized|default|strictfp|transient|volatile|sealed|non-sealed)";
+const MODIFIER_OR_ANNOTATION_RUN = `(?:(?:@[\\w.]+|${MODIFIER})\\s+)*`;
+const TYPE_PARAMS = "(?:<[^>]+>\\s*)?";
+const THROWS_CLAUSE = "(?:\\s+throws\\s+[\\w.$,\\s]+)?";
+const CLASS_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}(class|interface|enum|record)\\s+([A-Za-z_$][\\w$]*)`);
+// Method/constructor with a body: return type is optional (constructors have none); ends with "{".
+const METHOD_BLOCK_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_PARAMS}(?:${TYPE_TOKEN}\\s+)?([A-Za-z_$][\\w$]*)\\s*\\([^)]*\\)${THROWS_CLAUSE}\\s*\\{`);
+// Abstract/interface method declaration: a return type is REQUIRED; ends with ";".
+// Requiring the return type is what separates "void onTick();" from a bare call "doThing();".
+const METHOD_ABSTRACT_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_PARAMS}${TYPE_TOKEN}\\s+([A-Za-z_$][\\w$]*)\\s*\\([^)]*\\)${THROWS_CLAUSE}\\s*;`);
+const FIELD_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_TOKEN}\\s+([A-Za-z_$][\\w$]*)\\s*(?:=|;|,)`);
+// Lines that begin with one of these keywords are statements, not declarations. They are
+// skipped wholesale so that "return helper();" / "for (...)" / "new Foo() {" never produce
+// phantom members. "default"/"synchronized" are intentionally excluded (they double as
+// member modifiers); the method regexes reject their statement forms structurally.
+const STATEMENT_LINE_KEYWORDS = new Set([
+    "if", "for", "while", "switch", "catch", "return", "throw", "else", "do",
+    "case", "break", "continue", "assert", "super", "this", "try", "new", "yield"
+]);
+// Defence-in-depth: even if a keyword is captured as a member name, drop it.
 const NOISE_TOKENS = new Set(["if", "for", "while", "switch", "catch", "return", "new", "throw"]);
 function normalizeLine(line) {
     return line.replace(/\s+/g, " ").trim();
@@ -8,6 +28,10 @@ function normalizeLine(line) {
 function isNoiseToken(token) {
     return NOISE_TOKENS.has(token);
 }
+function isStatementLine(line) {
+    const firstWord = /^([A-Za-z_$][\w$]*)/.exec(line)?.[1];
+    return firstWord != null && STATEMENT_LINE_KEYWORDS.has(firstWord);
+}
 function lineIndexToLine(lineNo) {
     return lineNo + 1;
 }
@@ -17,8 +41,13 @@ export function extractSymbolsFromSource(filePath, content) {
     const qualifiedName = filePath.replace(/\.java$/, "").replaceAll("/", ".");
     for (let index = 0; index < lines.length; index += 1) {
         const rawLine = lines[index] ?? "";
-        const line = normalizeLine(rawLine);
-        if (!line) {
+        const normalized = normalizeLine(rawLine);
+        if (!normalized) {
+            continue;
+        }
+        // Drop a single leading "}"/"{" so "} public void foo() {" still parses.
+        const line = normalized.replace(/^[}{]\s*/, "");
+        if (!line || isStatementLine(line)) {
             continue;
         }
         const classMatch = line.match(CLASS_DECLARATION);
@@ -35,7 +64,7 @@ export function extractSymbolsFromSource(filePath, content) {
             }
             continue;
         }
-        const methodMatch = line.match(METHOD_DECLARATION);
+        const methodMatch = line.match(METHOD_BLOCK_DECLARATION) ?? line.match(METHOD_ABSTRACT_DECLARATION);
         if (methodMatch) {
             const symbolName = methodMatch[1];
             if (symbolName && !isNoiseToken(symbolName)) {

package/dist/text-truncate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Slice `text` to at most `maxChars` UTF-16 code units without splitting a
+ * surrogate pair. A naive `text.slice(0, maxChars)` can leave a lone high
+ * surrogate at the boundary (e.g. when an emoji straddles the cut), producing
+ * an invalid string; this drops that dangling half so callers never emit one.
+ */
+export declare function sliceToMaxCharsSafe(text: string, maxChars: number): string;

package/dist/text-truncate.js

@@ -0,0 +1,21 @@
+/**
+ * Slice `text` to at most `maxChars` UTF-16 code units without splitting a
+ * surrogate pair. A naive `text.slice(0, maxChars)` can leave a lone high
+ * surrogate at the boundary (e.g. when an emoji straddles the cut), producing
+ * an invalid string; this drops that dangling half so callers never emit one.
+ */
+export function sliceToMaxCharsSafe(text, maxChars) {
+    if (maxChars <= 0) {
+        return "";
+    }
+    if (text.length <= maxChars) {
+        return text;
+    }
+    let cut = text.slice(0, maxChars);
+    const lastUnit = cut.charCodeAt(cut.length - 1);
+    if (lastUnit >= 0xd800 && lastUnit <= 0xdbff) {
+        cut = cut.slice(0, -1);
+    }
+    return cut;
+}
+//# sourceMappingURL=text-truncate.js.map

package/dist/tiny-remapper-resolver.js

@@ -15,6 +15,16 @@ function tinyRemapperDownloadUrl(version) {
 export async function resolveTinyRemapperJar(cacheDir, overridePath, fetchFn) {
     // 1. Environment / config override
     if (overridePath) {
+        if (!existsSync(overridePath)) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Configured tiny-remapper jar does not exist: ${overridePath}`,
+                details: {
+                    path: overridePath,
+                    nextAction: "Point tinyRemapperJarPath / MCP_TINY_REMAPPER_JAR at an existing fat jar, or unset it to download automatically."
+                }
+            });
+        }
         return overridePath;
     }
     const version = process.env.MCP_TINY_REMAPPER_VERSION ?? DEFAULT_VERSION;

package/dist/tool-contract-manifest.js

@@ -67,14 +67,14 @@ const SECTION_ROWS = {
     "mapping-symbols": {
         en: [
             "| `find-mapping` | Look up mapping candidates for class, field, or method symbols |",
-            "| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner, name, and descriptor matching |",
+            "| `resolve-method-mapping-exact` | Strict shortcut for `find-mapping` (kind=method, signatureMode=exact); requires the full owner+name+descriptor triple |",
             "| `get-class-api-matrix` | Show one class API across `obfuscated`, `mojang`, `intermediary`, and `yarn` |",
             "| `resolve-workspace-symbol` | Resolve compile-visible symbol names from a Gradle workspace |",
             "| `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |"
         ],
         ja: [
             "| `find-mapping` | クラス、フィールド、メソッドのシンボルに対するマッピング候補を調べる |",
-            "| `resolve-method-mapping-exact` | owner、name、descriptor の厳密一致で 1 つのメソッドマッピングを解決する |",
+            "| `resolve-method-mapping-exact` | `find-mapping`（kind=method, signatureMode=exact）の厳密版ショートカット。owner+name+descriptor の三つ組が必須 |",
             "| `get-class-api-matrix` | 1 つのクラス API を `obfuscated`、`mojang`、`intermediary`、`yarn` で見比べる |",
             "| `resolve-workspace-symbol` | Gradle ワークスペースからコンパイル時に見えるシンボル名を解決する |",
             "| `check-symbol-exists` | 名前空間内でクラス、フィールド、メソッドが存在するかを確認する |"

package/dist/tool-execution-gate.js

@@ -3,6 +3,13 @@ const DEFAULT_OPTIONS = {
     maxConcurrent: 1,
     maxQueue: 2
 };
+// Heavy tools that have a batch equivalent able to collapse many same-kind
+// queries into a single gated call. Used to point overflow guidance at the
+// right batch-* tool instead of just telling the caller to retry serially.
+const BATCH_EQUIVALENTS = {
+    "find-mapping": "batch-mappings",
+    "resolve-method-mapping-exact": "batch-mappings"
+};
 export class ToolExecutionGate {
     maxConcurrent;
     maxQueue;
@@ -17,6 +24,10 @@ export class ToolExecutionGate {
             return this.execute({ tool, task: task });
         }
         if (this.queue.length >= this.maxQueue) {
+            const batchTool = BATCH_EQUIVALENTS[tool];
+            const nextAction = batchTool
+                ? `Retry after the current heavy analysis request completes. To run many ${tool} queries efficiently, collapse them into a single ${batchTool} call instead of issuing them in parallel.`
+                : "Retry after the current heavy analysis request completes. Avoid sending multiple heavy mapping/version analysis tools in parallel.";
             return Promise.reject(createError({
                 code: ERROR_CODES.LIMIT_EXCEEDED,
                 message: `Heavy tool queue is full; "${tool}" was not started.`,
@@ -26,7 +37,7 @@ export class ToolExecutionGate {
                     queuedCount: this.queue.length,
                     maxConcurrent: this.maxConcurrent,
                     maxQueue: this.maxQueue,
-                    nextAction: "Retry after the current heavy analysis request completes. Avoid sending multiple heavy mapping/version analysis tools in parallel."
+                    nextAction
                 }
             }));
         }

package/dist/tool-guidance.d.ts

@@ -1,11 +1,15 @@
 import { ZodError } from "zod";
+import type { WarningDetail } from "./warning-details.js";
 import { type ExampleCall, type ProblemDetails, type ProblemFieldError, type SuggestedCall } from "./error-mapping.js";
 import type { SourceTargetInput } from "./types.js";
 export type ToolMeta = {
     requestId: string;
     tool: string;
     durationMs: number;
-    warnings: string[];
+    /** Omitted entirely when there are no warnings (token efficiency). */
+    warnings?: string[];
+    /** Structured companion to `warnings`: one classified entry per warning string, referencing its text via `warnings[detail.index]`. */
+    warningDetails?: WarningDetail[];
     detailApplied?: "summary" | "standard" | "full";
     includeApplied?: string[];
     truncated?: Record<string, unknown>;
@@ -29,7 +33,7 @@ export declare const SUGGESTED_CALL_DEFAULTS: {
     readonly explain: false;
     readonly preferProjectMapping: false;
     readonly minSeverity: "all";
-    readonly reportMode: "full";
+    readonly reportMode: "summary-first";
     readonly treatInfoAsWarning: true;
     readonly includeIssues: true;
 };