@adhisang/minecraft-modding-mcp 3.1.0 → 3.2.0

package/dist/mixin-validator.js

@@ -133,6 +133,21 @@ function allMethodNames(members) {
 function allFieldNames(members) {
     return members.fields.map((m) => m.name);
 }
+function accessLevelFromFlags(accessFlags) {
+    if (accessFlags == null) {
+        return undefined;
+    }
+    if ((accessFlags & 0x0001) !== 0) {
+        return "public";
+    }
+    if ((accessFlags & 0x0004) !== 0) {
+        return "protected";
+    }
+    if ((accessFlags & 0x0002) !== 0) {
+        return "private";
+    }
+    return "package-private";
+}
 function computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence) {
     if (!healthReport)
         return undefined;
@@ -735,7 +750,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
 /* ------------------------------------------------------------------ */
 /*  Access Widener validation                                          */
 /* ------------------------------------------------------------------ */
-export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
+export function validateParsedAccessWidener(parsed, membersByClass, warnings, options) {
     warnings.push(...parsed.parseWarnings);
     const validatedEntries = [];
     let validCount = 0;
@@ -743,15 +758,29 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
     for (const entry of parsed.entries) {
         const ownerFqn = entry.target.replace(/\//g, ".");
         if (entry.targetKind === "class") {
-            if (membersByClass.has(ownerFqn)) {
-                validatedEntries.push({ ...entry, valid: true });
+            const members = membersByClass.get(ownerFqn);
+            if (members) {
+                const runtimeAccess = accessLevelFromFlags(members.classAccessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {})
+                        }
+                        : {})
+                });
                 validCount++;
             }
             else {
                 validatedEntries.push({
                     ...entry,
                     valid: false,
-                    issue: `Class "${ownerFqn}" not found in game jar.`
+                    issue: `Class "${ownerFqn}" not found in game jar.`,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
                 });
                 invalidCount++;
             }
@@ -763,16 +792,37 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
             validatedEntries.push({
                 ...entry,
                 valid: false,
-                issue: `Owner class "${ownerFqn}" not found in game jar.`
+                issue: `Owner class "${ownerFqn}" not found in game jar.`,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
             });
             invalidCount++;
             continue;
         }
         if (entry.targetKind === "method") {
             const methodNames = allMethodNames(members);
-            const found = members.methods.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor)) || members.constructors.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const matchedMember = members.methods.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor)) ?? members.constructors.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const found = matchedMember != null;
             if (found) {
-                validatedEntries.push({ ...entry, valid: true });
+                const runtimeMember = matchedMember;
+                const runtimeAccess = accessLevelFromFlags(runtimeMember.accessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {}),
+                            ...(runtimeMember.jvmDescriptor
+                                ? { resolvedRuntimeJvmDescriptor: runtimeMember.jvmDescriptor }
+                                : {}),
+                            ...(runtimeMember.javaSignature
+                                ? { resolvedRuntimeJavaSignature: runtimeMember.javaSignature }
+                                : {})
+                        }
+                        : {})
+                });
                 validCount++;
             }
             else {
@@ -781,7 +831,8 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
                     ...entry,
                     valid: false,
                     issue: `Method "${entry.name}" not found in class "${ownerFqn}".`,
-                    suggestions: suggestions.length > 0 ? suggestions : undefined
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
                 });
                 invalidCount++;
             }
@@ -789,9 +840,29 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
         else {
             // field
             const fieldNames = allFieldNames(members);
-            const found = members.fields.some((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const matchedMember = members.fields.find((m) => m.name === entry.name && (!entry.descriptor || m.jvmDescriptor === entry.descriptor));
+            const found = matchedMember != null;
             if (found) {
-                validatedEntries.push({ ...entry, valid: true });
+                const runtimeMember = matchedMember;
+                const runtimeAccess = accessLevelFromFlags(runtimeMember.accessFlags);
+                validatedEntries.push({
+                    ...entry,
+                    valid: true,
+                    ...(options?.includeRuntimeEvidence
+                        ? {
+                            resolvedInRuntime: true,
+                            ...(runtimeAccess
+                                ? { resolvedRuntimeAccess: runtimeAccess }
+                                : {}),
+                            ...(runtimeMember.jvmDescriptor
+                                ? { resolvedRuntimeJvmDescriptor: runtimeMember.jvmDescriptor }
+                                : {}),
+                            ...(runtimeMember.javaSignature
+                                ? { resolvedRuntimeJavaSignature: runtimeMember.javaSignature }
+                                : {})
+                        }
+                        : {})
+                });
                 validCount++;
             }
             else {
@@ -800,7 +871,8 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
                     ...entry,
                     valid: false,
                     issue: `Field "${entry.name}" not found in class "${ownerFqn}".`,
-                    suggestions: suggestions.length > 0 ? suggestions : undefined
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
                 });
                 invalidCount++;
             }
@@ -819,4 +891,118 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings) {
         warnings
     };
 }
+export function validateParsedAccessTransformer(parsed, membersByClass, warnings, options) {
+    warnings.push(...parsed.parseWarnings);
+    const validatedEntries = [];
+    let validCount = 0;
+    let invalidCount = 0;
+    for (const entry of parsed.entries) {
+        const ownerFqn = entry.owner;
+        const members = membersByClass.get(ownerFqn);
+        if (entry.targetKind === "class") {
+            if (!members) {
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Class "${ownerFqn}" not found in runtime jar.`,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
+            const runtimeAccess = accessLevelFromFlags(members.classAccessFlags);
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence
+                    ? {
+                        resolvedInRuntime: true,
+                        ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {})
+                    }
+                    : {})
+            });
+            validCount++;
+            continue;
+        }
+        if (!members) {
+            validatedEntries.push({
+                ...entry,
+                valid: false,
+                issue: `Owner class "${ownerFqn}" not found in runtime jar.`,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+            });
+            invalidCount++;
+            continue;
+        }
+        if (entry.targetKind === "field") {
+            const fieldNames = allFieldNames(members);
+            const matchedField = members.fields.find((member) => member.name === entry.name);
+            if (!matchedField) {
+                const suggestions = entry.name ? suggestSimilar(entry.name, fieldNames) : [];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Field "${entry.name}" not found in class "${ownerFqn}".`,
+                    ...(suggestions.length > 0 ? { suggestions } : {}),
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
+            const runtimeAccess = accessLevelFromFlags(matchedField.accessFlags);
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence
+                    ? {
+                        resolvedInRuntime: true,
+                        ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {}),
+                        ...(matchedField.jvmDescriptor ? { resolvedRuntimeJvmDescriptor: matchedField.jvmDescriptor } : {}),
+                        ...(matchedField.javaSignature ? { resolvedRuntimeJavaSignature: matchedField.javaSignature } : {})
+                    }
+                    : {})
+            });
+            validCount++;
+            continue;
+        }
+        const methodNames = allMethodNames(members);
+        const matchedMethod = members.methods.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor) ?? members.constructors.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor);
+        if (!matchedMethod) {
+            const suggestions = entry.name ? suggestSimilar(entry.name, methodNames) : [];
+            validatedEntries.push({
+                ...entry,
+                valid: false,
+                issue: `Method "${entry.name}" not found in class "${ownerFqn}".`,
+                ...(suggestions.length > 0 ? { suggestions } : {}),
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+            });
+            invalidCount++;
+            continue;
+        }
+        const runtimeAccess = accessLevelFromFlags(matchedMethod.accessFlags);
+        validatedEntries.push({
+            ...entry,
+            valid: true,
+            ...(options?.includeRuntimeEvidence
+                ? {
+                    resolvedInRuntime: true,
+                    ...(runtimeAccess ? { resolvedRuntimeAccess: runtimeAccess } : {}),
+                    ...(matchedMethod.jvmDescriptor ? { resolvedRuntimeJvmDescriptor: matchedMethod.jvmDescriptor } : {}),
+                    ...(matchedMethod.javaSignature ? { resolvedRuntimeJavaSignature: matchedMethod.javaSignature } : {})
+                }
+                : {})
+        });
+        validCount++;
+    }
+    return {
+        valid: invalidCount === 0,
+        entries: validatedEntries,
+        summary: {
+            total: parsed.entries.length,
+            valid: validCount,
+            invalid: invalidCount
+        },
+        warnings
+    };
+}
 //# sourceMappingURL=mixin-validator.js.map

package/dist/mod-analyzer.d.ts

@@ -15,6 +15,7 @@ export interface ModAnalysisResult {
     entrypoints?: Record<string, string[]>;
     mixinConfigs?: string[];
     accessWidener?: string;
+    accessTransformers?: string[];
     dependencies?: ModDependency[];
     classCount: number;
     classes?: string[];

package/dist/mod-analyzer.js

@@ -72,7 +72,8 @@ const forgeModsTomlSchema = z
         .passthrough())
         .optional(),
     dependencies: z.record(z.array(z.unknown())).optional(),
-    mixins: z.array(z.object({ config: z.string() }).passthrough()).optional()
+    mixins: z.array(z.object({ config: z.string() }).passthrough()).optional(),
+    accessTransformers: z.array(z.object({ file: z.string().optional() }).passthrough()).optional()
 })
     .passthrough();
 const legacyForgeSchema = z.array(z
@@ -214,6 +215,9 @@ function parseForgeMod(content, entries) {
     }
     // Mixin configs
     const mixinConfigs = toml.mixins?.map((m) => m.config);
+    const accessTransformers = toml.accessTransformers
+        ?.map((entry) => entry.file)
+        .filter((file) => typeof file === "string" && file.trim().length > 0);
     return {
         detectedLoader,
         modId: firstMod?.modId,
@@ -221,6 +225,7 @@ function parseForgeMod(content, entries) {
         modVersion: firstMod?.version,
         description: firstMod?.description,
         mixinConfigs: mixinConfigs && mixinConfigs.length > 0 ? mixinConfigs : undefined,
+        accessTransformers: accessTransformers && accessTransformers.length > 0 ? accessTransformers : undefined,
         dependencies: dependencies.length > 0 ? dependencies : undefined
     };
 }
@@ -288,6 +293,9 @@ export async function analyzeModJar(jarPath, options) {
     // Detect loader and parse metadata
     let loader = "unknown";
     let metadata = {};
+    const packagedAccessTransformers = [...new Set(entries.filter((entry) => /(^|\/)META-INF\/accesstransformer\.cfg$/i.test(entry) ||
+            /(^|\/)[^/]+_at\.cfg$/i.test(entry) ||
+            /(^|\/)accesstransformer[^/]*\.cfg$/i.test(entry)))].sort((left, right) => left.localeCompare(right));
     if (entries.includes("fabric.mod.json")) {
         loader = "fabric";
         try {
@@ -346,6 +354,14 @@ export async function analyzeModJar(jarPath, options) {
         loader,
         jarKind,
         ...metadata,
+        ...(packagedAccessTransformers.length > 0 || metadata.accessTransformers
+            ? {
+                accessTransformers: [...new Set([
+                        ...(metadata.accessTransformers ?? []),
+                        ...packagedAccessTransformers
+                    ])]
+            }
+            : {}),
         classCount,
         ...(classes !== undefined ? { classes } : {})
     };

package/dist/mod-decompile-service.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, join, resolve as resolvePath } from "node:path";
 import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
@@ -41,7 +41,7 @@ export class ModDecompileService {
             const targetFile = classNameToFilePath(input.className);
             const matched = files.find((f) => f === targetFile || f.endsWith(`/${targetFile}`) || f === input.className);
             if (matched) {
-                const content = readFileSync(join(outputDir, matched), "utf8");
+                const content = await readFile(join(outputDir, matched), "utf8");
                 sourceResult = {
                     className: filePathToClassName(matched),
                     content,
@@ -106,7 +106,7 @@ export class ModDecompileService {
                 details: { className, jarPath, availableCount: files.length }
             });
         }
-        const fullContent = readFileSync(join(outputDir, matched), "utf8");
+        const fullContent = await readFile(join(outputDir, matched), "utf8");
         const totalLines = fullContent.split("\n").length;
         let content = fullContent;
         let truncated;
@@ -131,7 +131,7 @@ export class ModDecompileService {
             const outPath = isAbsolute(input.outputFile)
                 ? input.outputFile
                 : resolvePath(input.outputFile);
-            writeFileSync(outPath, content, "utf8");
+            await writeFile(outPath, content, "utf8");
             outputFilePath = outPath;
             content = `[Written to ${outPath}]`;
         }

package/dist/mod-remap-service.js

@@ -8,7 +8,7 @@ import { resolveTinyMappingFile } from "./mapping-service.js";
 import { resolveMojangTinyFile } from "./mojang-tiny-mapping-service.js";
 import { analyzeModJar } from "./mod-analyzer.js";
 import { normalizePathForHost } from "./path-converter.js";
-import { listJarEntries, readJarEntryAsBuffer } from "./source-jar-reader.js";
+import { detectFabricLikeInputNamespace } from "./source-jar-reader.js";
 import { remapJar } from "./tiny-remapper-service.js";
 import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
 function normalizeTargetNamespace(target) {
@@ -36,59 +36,6 @@ function extractMinecraftVersion(dependencies) {
     const match = mcDep.versionRange.match(/(\d+\.\d+(?:\.\d+)?)/);
     return match?.[1];
 }
-function countMatches(input, pattern) {
-    const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
-    const globalPattern = new RegExp(pattern.source, flags);
-    let count = 0;
-    while (globalPattern.exec(input)) {
-        count += 1;
-    }
-    return count;
-}
-async function detectFabricLikeInputNamespace(inputJar) {
-    const warnings = [];
-    const classEntries = (await listJarEntries(inputJar))
-        .filter((entry) => entry.endsWith(".class"))
-        .slice(0, 24);
-    if (classEntries.length === 0) {
-        warnings.push("Could not inspect class entries to detect input mapping; assuming intermediary.");
-        return {
-            fromNamespace: "intermediary",
-            warnings
-        };
-    }
-    let mojangScore = 0;
-    let intermediaryScore = 0;
-    for (const entry of classEntries) {
-        let text = "";
-        try {
-            text = (await readJarEntryAsBuffer(inputJar, entry)).toString("latin1");
-        }
-        catch {
-            continue;
-        }
-        mojangScore += countMatches(text, /net\/minecraft\/(?:advancements|client|commands|core|data|gametest|nbt|network|recipe|resources|server|sounds|stats|tags|util|world)\//g) * 3;
-        intermediaryScore += countMatches(text, /net\/minecraft\/class_\d+/g) * 3;
-        intermediaryScore += countMatches(text, /\b(?:method|field)_\d+\b/g);
-    }
-    if (mojangScore > intermediaryScore && mojangScore > 0) {
-        return {
-            fromNamespace: "mojang",
-            warnings
-        };
-    }
-    if (intermediaryScore > mojangScore && intermediaryScore > 0) {
-        return {
-            fromNamespace: "intermediary",
-            warnings
-        };
-    }
-    warnings.push("Could not confidently detect whether the input jar uses intermediary or mojang names; assuming intermediary.");
-    return {
-        fromNamespace: "intermediary",
-        warnings
-    };
-}
 async function detectInputNamespaceForLoader(inputJar, loader) {
     if (loader === "fabric" || loader === "quilt") {
         return detectFabricLikeInputNamespace(inputJar);

package/dist/mod-search-service.d.ts

@@ -26,4 +26,5 @@ export declare class ModSearchService {
     constructor(modDecompileService: ModDecompileService);
     searchModSource(input: SearchModSourceInput): Promise<SearchModSourceOutput>;
     private searchSourceJarEntriesDirect;
+    private searchDecompiledClassFile;
 }

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/response-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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>;
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare function compactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** resolve-artifact compact: omit debug/diagnostic fields. */
+export declare function compactArtifactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Mapping tool compact: omit candidates only when provably redundant.
+ *
+ * Candidates are omitted when ALL of:
+ * 1. resolved === true
+ * 2. resolvedSymbol exists
+ * 3. candidates is an array of length 1
+ * 4. candidateCount === 1
+ * 5. candidatesTruncated is falsy
+ * 6. candidates[0].matchKind === "exact"
+ * 7. candidates[0].confidence is undefined or 1
+ */
+export declare function compactMappingResponse(obj: Record<string, unknown>): Record<string, unknown>;