@adhisang/minecraft-modding-mcp 7.1.0 → 7.1.1

package/dist/mod-decompile-service.js

@@ -135,7 +135,17 @@ export class ModDecompileService {
             const outPath = isAbsolute(input.outputFile)
                 ? input.outputFile
                 : resolvePath(input.outputFile);
-            await writeFile(outPath, content, "utf8");
+            try {
+                await writeFile(outPath, content, "utf8");
+            }
+            catch (writeError) {
+                const errno = writeError?.code;
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `outputFile "${outPath}" could not be written (${errno ?? "unknown error"}).`,
+                    details: { field: "outputFile", value: outPath, osErrorCode: errno }
+                });
+            }
             outputFilePath = outPath;
             content = `[Written to ${outPath}]`;
         }

package/dist/mod-remap-service.js

@@ -149,13 +149,13 @@ export async function remapModJar(input, config, deps = {}) {
     mkdirSync(cacheDir, { recursive: true });
     const cachedOutput = join(cacheDir, `${cacheKey}.jar`);
     if (!input.forceRemap && existsSync(cachedOutput)) {
-        const cacheHitOutputJar = input.outputJar
-            ? outputJar
-            : cachedOutput;
-        copyJarToDestination(cachedOutput, cacheHitOutputJar);
-        log("info", "remap.cache-hit", { inputJar: normalizedInput, outputJar: cacheHitOutputJar });
+        // Always copy to the same `outputJar` location a cold run would use (the
+        // caller-supplied path, or resolveOutputJarPath's "next to input" default),
+        // so a cache hit and a cold run return the same path convention.
+        copyJarToDestination(cachedOutput, outputJar);
+        log("info", "remap.cache-hit", { inputJar: normalizedInput, outputJar });
         return {
-            outputJar: cacheHitOutputJar,
+            outputJar,
             mcVersion,
             fromMapping: fromNamespace,
             targetMapping: input.targetMapping,

package/dist/nbt/java-nbt-codec.js

@@ -480,7 +480,13 @@ export function decodeJavaNbt(buffer) {
                 throw error;
             }
         }
-        throw parseError("Failed to decode Java NBT payload.");
+        // Unlike every other parseError() call site in this module, nothing here
+        // has an offset to report - do not inherit PARSE_NEXT_ACTION's "at the
+        // reported offset" promise.
+        throw parseError("Failed to decode Java NBT payload.", {
+            nextAction: "The payload is not a well-formed Java NBT stream. Check that nbtBase64 holds the whole " +
+                'file and that compression matches how it was written (use compression "auto" to detect gzip).'
+        });
     }
 }
 export function encodeJavaNbt(document) {

package/dist/source/access-validate.js

@@ -80,6 +80,16 @@ export async function validateAccessWidener(svc, input) {
     if (!content.trim()) {
         throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "content must be non-empty." });
     }
+    // Fabric Loader also reads the classTweaker format; it is out of scope here rather than an
+    // accessWidener file with a bad header, so it gets no verdict.
+    const header = content.split(/\r?\n/).map((line) => line.trim()).find((line) => line && !line.startsWith("#"));
+    if (header && /^classTweaker(\s|$)/.test(header)) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `The classTweaker format is not supported (header "${header}"); only accessWidener v1/v2 files can be validated.`,
+            details: { unsupportedFormat: "classTweaker", header }
+        });
+    }
     const warnings = [];
     const parsed = parseAccessWidener(content);
     const headerNamespaceRaw = normalizeOptionalString(parsed.namespace);

package/dist/source/artifact-resolver.d.ts

@@ -140,8 +140,16 @@ export declare function hasLoaderRuntimeVersionToken(path: string, mcVersion: st
 /**
  * Minecraft version a runtime jar path carries, or undefined when the path
  * names none. Loom lays its cache out as
- * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
- * of the path is the version the jar was built for.
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first token of the
+ * tool-written part of the path ({@link runtimeJarLayoutTail}; the whole path
+ * when it enters no layout root) that names a Minecraft version is the version the jar was built for — in
+ * either id family, and a pre-release names itself and not the release it
+ * precedes. Reading only `1.x[.y]` left every 26.x jar versionless, so no
+ * approximation was ever reported for one.
+ *
+ * A legacy `1.x` token is self-identifying; a 26.1+ token shares its shape with
+ * every loader's own version number, so it additionally has to sit where
+ * {@link tokenPositionNamesMinecraft} says Minecraft's version sits.
  */
 export declare function inferRuntimeJarMinecraftVersion(path: string): string | undefined;
 /**
@@ -177,7 +185,9 @@ export declare function inferRuntimeJarLoader(path: string): RuntimeLoader;
  * `version` becomes the version the SERVED jar carries; the caller's original
  * request is preserved under `requestedVersion` and flagged. A served loader
  * that contradicts a KNOWN expected loader is flagged too — never silently
- * dropped.
+ * dropped. When the jar's path names no version at all, the request stands as
+ * the answer and nothing is flagged: there is no served version to contradict
+ * it with.
  */
 export declare function describeServedRuntimeJar(input: {
     jarPath: string;

package/dist/source/artifact-resolver.js

@@ -170,16 +170,30 @@ export function looksLikeMinecraftArtifactPath(path) {
 function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
     return hasMinecraftNamespace || looksLikeMinecraftArtifactPath(path);
 }
+/**
+ * What a Minecraft version id may be FOLLOWED by and still be the same id:
+ * nothing. A pre-release suffix extends the id rather than decorating it —
+ * `26.1-pre-1` is its own version and not `26.1` — so the hyphen forms Mojang
+ * publishes (`-pre1`, `-rc1`, `-pre-6`, `-rc-2`, `-snapshot-6`) have to close
+ * the token as firmly as a trailing digit does. Any OTHER hyphen is ordinary
+ * path decoration (`minecraft-1.21.1-merged.jar`) and must keep matching.
+ *
+ * The suffix grammar is `isUnobfuscatedVersion`'s in version-service.ts; the
+ * two are read together whenever either changes.
+ */
+const VERSION_ID_SUFFIX_LOOKAHEAD = "-(?:pre|rc)[0-9]|-(?:pre|rc|snapshot)-[0-9]";
 export function hasExactVersionToken(path, version) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     const normalizedVersion = version.trim().toLowerCase();
     if (!normalizedVersion) {
         return false;
     }
-    // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
-    const cached = VERSION_TOKEN_REGEX_CACHE.get(normalizedVersion);
+    // Avoid prefix false-positives like "1.21.1" matching "1.21.10", and
+    // pre-release false-positives like "26.1" matching "26.1-pre-1".
+    const cacheKey = normalizedVersion;
+    const cached = VERSION_TOKEN_REGEX_CACHE.get(cacheKey);
     const pattern = cached
-        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
+        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9]|${VERSION_ID_SUFFIX_LOOKAHEAD})`, "i"));
     return pattern.test(normalizedPath);
 }
 /**
@@ -209,15 +223,85 @@ export function hasLoaderRuntimeVersionToken(path, mcVersion) {
         ?? rememberCachedRegex(LOADER_VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z.])${minor}\\.${patch}\\.\\d`, "i"));
     return pattern.test(normalizedPath);
 }
-const RUNTIME_JAR_VERSION_REGEX = /(?:^|[^0-9.])(1\.\d+(?:\.\d+)?)(?![0-9.])/;
+/**
+ * Every version-SHAPED token a path carries, in both id families: `<a>.<b>[.<c>]`
+ * with an optional pre-release suffix, and the `YYwNNa` snapshot form. Shape
+ * only — `inferRuntimeJarMinecraftVersion` decides which of them is Minecraft's.
+ *
+ * The alternatives are greedy, so the LONGEST token at a position is the one
+ * offered, suffix included. What closes it is another version component — a
+ * digit, or a dot that starts one — and nothing else: a dot that starts a file
+ * extension ends the token instead. Refusing every following dot made
+ * `minecraft-merged-26.1.jar` name no version and made
+ * `minecraft-merged-26.2-pre-6.jar` backtrack off its own suffix down to
+ * "26.2", the release that jar is not.
+ */
+const RUNTIME_JAR_VERSION_TOKEN_REGEX = /(?:^|[^0-9.])(\d+\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?|\d{2}w\d{2}[a-z])(?![0-9]|\.[0-9])/g;
+/** The legacy obfuscated line, `1.21` / `1.21.10` / `1.14.4-pre7`. */
+const LEGACY_MINECRAFT_VERSION_REGEX = /^1\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?$/;
+/** Loom's cache root: the directory whose immediate children are Minecraft versions. */
+const LOOM_CACHE_ROOT_SEGMENT_REGEX = /^(?:fabric-loom|loom-cache)$/;
+/**
+ * Does the path POSITION a 26.1+ token sits at vouch for it being Minecraft's
+ * version?
+ *
+ * The new-format grammar is only a shape: `isUnobfuscatedVersion` accepts any
+ * id from year 26 up, and Forge's own versions have long since passed it
+ * (`forge-47.3.0-srg.jar`), so the token needs the same kind of corroboration
+ * the loader-version exclusions elsewhere in this file rely on. Three positions
+ * carry it, and they are the layouts the discovery helpers already walk: the
+ * artifact itself names Minecraft (`minecraft-merged-26.1.jar`), the entry
+ * directly inside the version directory does (neoformruntime's
+ * `<version>/minecraft-joined.jar`), or the version directory is a child of
+ * Loom's cache root (`<...>/fabric-loom/<mcVersion>/`).
+ *
+ * Only the token's own neighbourhood counts, never an ancestor — for the reason
+ * `runtimeJarLayoutRelativePath` exists: a checkout under `~/dev/minecraft/`
+ * names the user's directory, not the jar.
+ */
+function tokenPositionNamesMinecraft(segments, index) {
+    return ((segments[index]?.includes("minecraft") ?? false) ||
+        (segments[index + 1]?.includes("minecraft") ?? false) ||
+        LOOM_CACHE_ROOT_SEGMENT_REGEX.test(segments[index - 1] ?? ""));
+}
 /**
  * Minecraft version a runtime jar path carries, or undefined when the path
  * names none. Loom lays its cache out as
- * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
- * of the path is the version the jar was built for.
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first token of the
+ * tool-written part of the path ({@link runtimeJarLayoutTail}; the whole path
+ * when it enters no layout root) that names a Minecraft version is the version the jar was built for — in
+ * either id family, and a pre-release names itself and not the release it
+ * precedes. Reading only `1.x[.y]` left every 26.x jar versionless, so no
+ * approximation was ever reported for one.
+ *
+ * A legacy `1.x` token is self-identifying; a 26.1+ token shares its shape with
+ * every loader's own version number, so it additionally has to sit where
+ * {@link tokenPositionNamesMinecraft} says Minecraft's version sits.
  */
 export function inferRuntimeJarMinecraftVersion(path) {
-    return RUNTIME_JAR_VERSION_REGEX.exec(normalizePathStyle(path))?.[1];
+    // A path that enters no layout root, such as a custom Gradle home's `loom-cache`, is read whole.
+    const normalizedPath = runtimeJarLayoutTail(path) ?? normalizePathStyle(path).toLowerCase();
+    const segments = normalizedPath.split("/");
+    for (const match of normalizedPath.matchAll(RUNTIME_JAR_VERSION_TOKEN_REGEX)) {
+        const token = match[1];
+        if (!token) {
+            continue;
+        }
+        if (LEGACY_MINECRAFT_VERSION_REGEX.test(token)) {
+            return token;
+        }
+        if (!isUnobfuscatedVersion(token)) {
+            continue;
+        }
+        // `match[0]` carries the leading boundary character, so the token starts at
+        // its end minus the token's own length.
+        const tokenStart = (match.index ?? 0) + match[0].length - token.length;
+        const segmentIndex = normalizedPath.slice(0, tokenStart).split("/").length - 1;
+        if (tokenPositionNamesMinecraft(segments, segmentIndex)) {
+            return token;
+        }
+    }
+    return undefined;
 }
 /**
  * The Minecraft version a `kind: "jar"` target PROVES it is the unobfuscated
@@ -271,6 +355,10 @@ const RUNTIME_JAR_LAYOUT_ROOT_RE = /^(?:\.[^/]*|caches|build)$/;
  * loader for an artifact that names none.
  */
 function runtimeJarLayoutRelativePath(path) {
+    return runtimeJarLayoutTail(path) ?? normalizePathStyle(path).toLowerCase().split("/").filter(Boolean).at(-1) ?? "";
+}
+/** Everything below the deepest layout root, or undefined when the path enters none. */
+function runtimeJarLayoutTail(path) {
     const segments = normalizePathStyle(path)
         .toLowerCase()
         .split("/")
@@ -280,7 +368,7 @@ function runtimeJarLayoutRelativePath(path) {
             return segments.slice(index + 1).join("/");
         }
     }
-    return segments[segments.length - 1] ?? "";
+    return undefined;
 }
 /**
  * Loader a runtime jar belongs to, read from the tool-written part of its path.
@@ -320,7 +408,9 @@ export function inferRuntimeJarLoader(path) {
  * `version` becomes the version the SERVED jar carries; the caller's original
  * request is preserved under `requestedVersion` and flagged. A served loader
  * that contradicts a KNOWN expected loader is flagged too — never silently
- * dropped.
+ * dropped. When the jar's path names no version at all, the request stands as
+ * the answer and nothing is flagged: there is no served version to contradict
+ * it with.
  */
 export function describeServedRuntimeJar(input) {
     const notes = [];
@@ -527,8 +617,9 @@ export async function probeMinecraftArtifact(svc, input) {
     let value = input.target.value.trim();
     const warnings = [];
     const requestedMapping = normalizeMapping(input.mapping);
-    if (input.preferProjectVersion && input.projectPath) {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+    if (input.preferProjectVersion && normalizedProjectPath) {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
         if (detected && detected !== value) {
             warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
         }
@@ -580,7 +671,7 @@ export async function probeMinecraftArtifact(svc, input) {
         }
         const versionSourceDiscovery = await svc.discoverVersionSourceJar({
             version: resolvedVersion,
-            projectPath: input.projectPath,
+            projectPath: normalizedProjectPath,
             gradleUserHome: input.gradleUserHome
         });
         if (!versionSourceDiscovery.selectedSourceJarPath) {
@@ -1128,10 +1219,11 @@ export async function resolveVersionContext(svc, input) {
     if (inferredVersion) {
         return inferredVersion;
     }
-    if (!input.preferProjectVersion || !input.projectPath) {
+    const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+    if (!input.preferProjectVersion || !normalizedProjectPath) {
         return undefined;
     }
-    const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
     if (detected) {
         input.warnings.push(`Using project version "${detected}" from gradle.properties because the artifact metadata did not include a version.`);
     }
@@ -1268,7 +1360,7 @@ export async function buildMappingFallbackSuggestedCall(svc, args) {
     if (process.env.WORKSPACE_FALLBACK_LEGACY === "1") {
         return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath: input.projectPath });
     }
-    const projectPath = input.projectPath?.trim();
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath: undefined });
     }
@@ -1428,8 +1520,15 @@ export async function resolveArtifact(svc, input) {
     const mapping = normalizeMapping(input.mapping);
     const scope = input.scope;
     const warnings = [...synthesisWarnings];
-    if (input.preferProjectVersion && input.projectPath && kind === "version") {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    // Normalized only for the readers that need it: every other use of
+    // projectPath below reaches a helper that normalizes on its own, and doing it
+    // here unconditionally would newly refuse a malformed path on calls that
+    // never read one.
+    const preferProjectVersionPath = input.preferProjectVersion
+        ? normalizeOptionalProjectPath(input.projectPath)
+        : undefined;
+    if (preferProjectVersionPath && kind === "version") {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(preferProjectVersionPath);
         if (detected && detected !== value) {
             warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
         }
@@ -1640,9 +1739,21 @@ export async function resolveArtifact(svc, input) {
                         mapping: effectiveMapping,
                         target: { kind, value },
                         nextAction: "Use target: { kind: \"version\", value } or a versioned Maven coordinate so mapping artifacts can be resolved.",
+                        // This branch is reached precisely because no version is known, and
+                        // `value` is whatever the caller's own target carried - a jar path
+                        // for the kind that gets here. Replaying it as a version target
+                        // produced a `suggestedCall` that could never succeed, so the
+                        // version goes out as a placeholder the caller must fill in;
+                        // buildSuggestedCall routes such a template to exampleCalls.
                         ...buildSuggestedCall({
                             tool: "resolve-artifact",
-                            params: buildResolveArtifactParams({ kind: "version", value }, { ...(scope ? { scope } : {}) })
+                            params: undefined,
+                            examples: [
+                                {
+                                    params: buildResolveArtifactParams({ kind: "version", value: "<your-mc-version>" }, { ...(scope ? { scope } : {}) }),
+                                    reason: `Replace <your-mc-version> with the Minecraft version this artifact belongs to; ${effectiveMapping} mappings are resolved per version.`
+                                }
+                            ]
                         })
                     }
                 });

package/dist/source/class-source.js

@@ -626,7 +626,8 @@ export function findClass(svc, input) {
                 qualifiedName: isInnerMatch ? className : rowQualified,
                 filePath: row.filePath,
                 line: row.line,
-                symbolKind: row.symbolKind
+                symbolKind: row.symbolKind,
+                ...(isInnerMatch ? { nested: true, enclosingClass: rowQualified } : {})
             };
         })
             .slice(0, limit);
@@ -1115,7 +1116,17 @@ export async function getClassSource(svc, input) {
         const outputPath = isAbsolute(outputFile)
             ? outputFile
             : resolvePath(outputFile);
-        await writeFile(outputPath, sourceText, "utf8");
+        try {
+            await writeFile(outputPath, sourceText, "utf8");
+        }
+        catch (writeError) {
+            const errno = writeError?.code;
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `outputFile "${outputPath}" could not be written (${errno ?? "unknown error"}).`,
+                details: { field: "outputFile", value: outputPath, osErrorCode: errno }
+            });
+        }
         resolvedOutputFile = outputPath;
         sourceText = `[Written to ${outputPath}]`;
     }

package/dist/source/nested-jars.d.ts

@@ -1,3 +1,4 @@
+import { rename } from "node:fs/promises";
 /**
  * A jar with at most this many own `.class` entries can qualify as a
  * Jar-in-Jar shell. Real Fabric API umbrella jars carry zero to a handful of
@@ -23,6 +24,10 @@ export interface NestedClassMatch {
     filePath: string;
     line: number;
     symbolKind: "class";
+    /** Set when the match is a type declared INSIDE another type. */
+    nested?: boolean;
+    /** The enclosing top-level type, present only on a nested match. */
+    enclosingClass?: string;
 }
 /**
  * Finds exact class-name matches across a shell's nested bytecode inventory.
@@ -50,6 +55,15 @@ export declare function detectShellJarInventory(jarPath: string): Promise<string
  * shell always maps to the same extracted file and re-resolution reuses it.
  */
 export declare function nestedJarCachePath(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string): string;
+/**
+ * Seam for injecting the temp->final rename primitive so tests can simulate a
+ * non-race rename failure (e.g. EBUSY/EPERM/ENOSPC), which cannot be provoked
+ * for real against a plain filesystem under the allowed test commands.
+ * Defaults to the module-level `rename` from node:fs/promises.
+ */
+export interface ExtractNestedJarDeps {
+    rename?: typeof rename;
+}
 /**
  * Extracts one nested jar to the content-addressed cache (no-op when already
  * present). Entry-name safety is enforced by readJarEntryAsBuffer, and the
@@ -62,7 +76,7 @@ export declare function nestedJarCachePath(cacheDir: string, outerJarPath: strin
  * one extraction with ERR_LIMIT_EXCEEDED — `loadNestedJarClassSet` swallows it
  * and keeps resolving the shell's other nested jars.
  */
-export declare function extractNestedJar(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string, maxEntryBytes?: number): Promise<string>;
+export declare function extractNestedJar(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string, maxEntryBytes?: number, deps?: ExtractNestedJarDeps): Promise<string>;
 /**
  * Finds every nested jar of a shell that contains the class. Zero matches
  * means the class genuinely is not bundled; more than one means the caller

package/dist/source/nested-jars.js

@@ -98,11 +98,17 @@ function nestedClassMatch(entry) {
     if (innerSegments.some((segment) => segment.length === 0 || /^\d/.test(segment))) {
         return undefined;
     }
+    // Mirror the indexed find-class branch's shape (class-source.ts): a `$`
+    // inner-class match reports `nested`/`enclosingClass` against its top-level
+    // enclosing type, exactly like an indexed lookup would.
+    const outerBinaryName = internalName.split("$")[0];
+    const isNested = innerSegments.length > 0;
     return {
         qualifiedName: internalName.replaceAll("/", ".").replaceAll("$", "."),
-        filePath: `${internalName.split("$")[0]}.java`,
+        filePath: `${outerBinaryName}.java`,
         line: 1,
-        symbolKind: "class"
+        symbolKind: "class",
+        ...(isNested ? { nested: true, enclosingClass: outerBinaryName.replaceAll("/", ".") } : {})
     };
 }
 /**
@@ -206,7 +212,8 @@ export function nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entry
  * one extraction with ERR_LIMIT_EXCEEDED — `loadNestedJarClassSet` swallows it
  * and keeps resolving the shell's other nested jars.
  */
-export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, entryName, maxEntryBytes) {
+export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, entryName, maxEntryBytes, deps = {}) {
+    const renameFn = deps.rename ?? rename;
     const finalPath = nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entryName);
     try {
         await access(finalPath);
@@ -243,16 +250,18 @@ export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, e
     const tempPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${randomBytes(6).toString("hex")}`;
     await writeFile(tempPath, bytes);
     try {
-        await rename(tempPath, finalPath);
+        await renameFn(tempPath, finalPath);
     }
     catch (renameError) {
         // A concurrent extraction of the same entry may have won the rename.
         // The content-addressed final file being present makes this call a
-        // success; anything else is a real failure.
+        // success; anything else is a real failure. Either way, best-effort
+        // remove the orphaned temp file before returning/rethrowing.
         try {
             await access(finalPath);
         }
         catch {
+            await rm(tempPath, { force: true }).catch(() => { });
             throw renameError;
         }
         await rm(tempPath, { force: true });

package/dist/source/search.d.ts

@@ -22,6 +22,14 @@ export declare function canUseIndexedSearchPath(indexedSearchEnabled: boolean, i
 export declare function buildGlobRegex(pattern: string): RegExp;
 export declare function globToSqlLike(pattern: string): string;
 export declare function checkPackagePrefix(filePath: string, packagePrefix?: string): boolean;
+/**
+ * A literal file_path prefix every path accepted by the scope starts with, or
+ * undefined when the scope implies none. The indexed candidate query matches it
+ * with an ASCII case-insensitive LIKE, a superset of checkPackagePrefix and the
+ * glob regex (indexed paths are stored with `/` separators), so both exact
+ * checks still run on every candidate.
+ */
+export declare function indexedScopePathPrefix(scope: SearchScope | undefined): string | undefined;
 export declare function buildSearchCursorContext(input: {
     artifactId: string;
     query: string;
@@ -42,8 +50,8 @@ export declare function scorePathMatch(match: SearchMatch, index: number): numbe
 export declare function matchRegexIndex(target: string, regex: RegExp): number;
 export declare function searchClassSource(svc: SourceService, input: SearchClassSourceInput): Promise<SearchClassSourceOutput>;
 export declare function searchSymbolIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
-export declare function searchTextIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
-export declare function searchPathIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchTextIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): boolean;
+export declare function searchPathIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): boolean;
 export declare function searchTextIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void, onWarning?: (warning: string) => void): void;
 export declare function searchPathIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
 export declare function findSymbolHits(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined): IndexedSymbolHit[];

package/dist/source/search.js

@@ -49,7 +49,9 @@ export function canUseIndexedSearchPath(indexedSearchEnabled, intent, match, _sc
     if (match === "regex") {
         return false;
     }
-    // packagePrefix and fileGlob are applied as post-filters on indexed candidates.
+    // packagePrefix and a fileGlob's literal directory prefix narrow the indexed
+    // candidate query (see indexedScopePathPrefix); both scope filters are also
+    // checked exactly on every candidate.
     return true;
 }
 export function buildGlobRegex(pattern) {
@@ -108,12 +110,36 @@ export function globToSqlLike(pattern) {
     }
     return result;
 }
+function packagePrefixPath(packagePrefix) {
+    return `${packagePrefix.replace(/\.+/g, "/").replace(/\/+$/, "")}/`;
+}
 export function checkPackagePrefix(filePath, packagePrefix) {
     if (!packagePrefix) {
         return true;
     }
-    const normalizedPrefix = packagePrefix.replace(/\.+/g, "/").replace(/\/+$/, "");
-    return normalizePathStyle(filePath).startsWith(`${normalizedPrefix}/`);
+    return normalizePathStyle(filePath).startsWith(packagePrefixPath(packagePrefix));
+}
+/**
+ * A literal file_path prefix every path accepted by the scope starts with, or
+ * undefined when the scope implies none. The indexed candidate query matches it
+ * with an ASCII case-insensitive LIKE, a superset of checkPackagePrefix and the
+ * glob regex (indexed paths are stored with `/` separators), so both exact
+ * checks still run on every candidate.
+ */
+export function indexedScopePathPrefix(scope) {
+    const packagePath = scope?.packagePrefix ? packagePrefixPath(scope.packagePrefix) : undefined;
+    let globPath;
+    if (scope?.fileGlob) {
+        // buildGlobRegex treats everything before the first `*`/`?` as literal.
+        const glob = normalizePathStyle(scope.fileGlob);
+        const wildcardIndex = glob.search(/[*?]/);
+        globPath = (wildcardIndex < 0 ? glob : glob.slice(0, wildcardIndex)) || undefined;
+    }
+    if (packagePath && globPath) {
+        // Keep the longer when one extends the other; otherwise either is a superset.
+        return globPath.startsWith(packagePath) ? globPath : packagePath;
+    }
+    return packagePath ?? globPath;
 }
 export function buildSearchCursorContext(input) {
     return JSON.stringify({
@@ -363,6 +389,7 @@ export async function searchClassSource(svc, input) {
             searchWarnings.push(warning);
         };
         const tokenOnlyTextIntent = intent === "text" && queryMode === "token";
+        let indexedWindowFull = false;
         if (intent === "symbol") {
             searchSymbolIntent(svc, artifact.artifactId, query, match, scope, regexPattern, recordHit);
         }
@@ -384,12 +411,9 @@ export async function searchClassSource(svc, input) {
         }
         else if (canUseIndexedSearchPath(indexedSearchEnabled, intent, match, scope)) {
             try {
-                if (intent === "path") {
-                    searchPathIntentIndexed(svc, artifact.artifactId, query, match, scope, recordHit);
-                }
-                else {
-                    searchTextIntentIndexed(svc, artifact.artifactId, query, match, scope, recordHit);
-                }
+                indexedWindowFull = intent === "path"
+                    ? searchPathIntentIndexed(svc, artifact.artifactId, query, match, scope, recordHit)
+                    : searchTextIntentIndexed(svc, artifact.artifactId, query, match, scope, recordHit);
                 svc.metrics.recordSearchIndexedHit();
             }
             catch (caughtError) {
@@ -424,6 +448,9 @@ export async function searchClassSource(svc, input) {
         svc.metrics.recordSearchIntentDuration(intent, Date.now() - intentStartedAt);
         const finalizedHits = accumulator.finalize();
         const page = finalizedHits.page;
+        if (indexedWindowFull && page.length < limit) {
+            searchWarnings.push(indexedCandidateWindowWarning(intent, indexedCandidateLimitForMatch(svc, match)));
+        }
         svc.metrics.recordSearchRowsReturned(page.length);
         const nextCursor = finalizedHits.nextCursorHit
             ? encodeSearchCursor(finalizedHits.nextCursorHit, cursorContext)
@@ -468,17 +495,19 @@ export function searchSymbolIntent(svc, artifactId, query, match, scope, regexPa
 }
 export function searchTextIntentIndexed(svc, artifactId, query, match, scope, onHit) {
     const candidateLimit = indexedCandidateLimitForMatch(svc, match);
+    const pathPrefix = indexedScopePathPrefix(scope);
     const indexed = svc.filesRepo.searchFileCandidates(artifactId, {
         query,
         match,
         limit: candidateLimit,
-        mode: "text"
+        mode: "text",
+        ...(pathPrefix ? { pathPrefix } : {})
     });
     svc.metrics.recordSearchDbRoundtrip(indexed.dbRoundtrips);
     svc.metrics.recordSearchRowsScanned(indexed.scannedRows);
     if (indexed.items.length === 0) {
         svc.metrics.recordSearchIndexedZeroShortcircuit();
-        return;
+        return false;
     }
     const globFilter = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
     const candidatePaths = indexed.items
@@ -508,19 +537,22 @@ export function searchTextIntentIndexed(svc, artifactId, query, match, scope, on
             reasonCodes: ["content_match", `text_${match}`, "indexed"]
         });
     }
+    return isCandidateWindowFull(indexed);
 }
 export function searchPathIntentIndexed(svc, artifactId, query, match, scope, onHit) {
     const candidateLimit = indexedCandidateLimitForMatch(svc, match);
+    const pathPrefix = indexedScopePathPrefix(scope);
     const indexed = svc.filesRepo.searchFileCandidates(artifactId, {
         query,
         limit: candidateLimit,
-        mode: "path"
+        mode: "path",
+        ...(pathPrefix ? { pathPrefix } : {})
     });
     svc.metrics.recordSearchDbRoundtrip(indexed.dbRoundtrips);
     svc.metrics.recordSearchRowsScanned(indexed.scannedRows);
     if (indexed.items.length === 0) {
         svc.metrics.recordSearchIndexedZeroShortcircuit();
-        return;
+        return false;
     }
     const globFilter = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
     const candidateRows = [];
@@ -551,6 +583,21 @@ export function searchPathIntentIndexed(svc, artifactId, query, match, scope, on
             reasonCodes: ["path_match", `path_${match}`, "indexed"]
         });
     }
+    return isCandidateWindowFull(indexed);
+}
+/**
+ * True when the index held more candidates than the window it returned: the
+ * repository reports that with a continuation cursor, which the single-window
+ * indexed search never follows.
+ */
+function isCandidateWindowFull(indexed) {
+    return indexed.nextCursor !== undefined;
+}
+function indexedCandidateWindowWarning(intent, candidateLimit) {
+    const fullScan = intent === "text"
+        ? 'queryMode="literal" for a full substring scan'
+        : 'match="regex" for a full path scan';
+    return `indexed ${intent} search examined only its candidate window (the first ${candidateLimit} index candidates) and more matched the index, so results may be incomplete. Use ${fullScan}, or narrow the scope with packagePrefix or a fileGlob that starts with a literal directory.`;
 }
 const ASCII_RE = /^[\x00-\x7F]*$/;
 /** True when every code unit is ASCII, so SQLite LIKE folds case identically to JS. */