@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.1

package/dist/source/class-source.js

@@ -10,7 +10,7 @@ import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
 import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
-import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+import { dedupeQualityFlags, inheritArtifactMapping, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 const MEMBERS_STATUS_LEGACY = process.env.MEMBERS_STATUS_LEGACY === "1";
 /**
@@ -82,13 +82,35 @@ function obfuscatedNamespaceHint(className) {
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
+/**
+ * Whether "this artifact is indexed in obfuscated names, ask for mapping=mojang"
+ * is TRUE for this artifact, from the pieces of it the caller sees.
+ *
+ * Two artifact kinds report `mappingApplied: "obfuscated"` without being an
+ * obfuscated Minecraft index, and the hint is simply false for them:
+ *  - a native dependency artifact, where the resolver SUBSTITUTES "obfuscated"
+ *    after the mapping pipeline declines (its class names are already the
+ *    library's own, so no mapping exists to ask for), and
+ *  - a shell jar, which holds no classes at all — its content lives in the
+ *    nested jars, and no mapping choice can change that.
+ *
+ * `looksLikeDeobfuscatedClassName` matches any capitalized simple name, so
+ * without these exclusions an ordinary library class such as "GameTest"
+ * qualifies and the caller is told to remap a jar that was never obfuscated.
+ */
+function isObfuscatedNamespaceHintTrue(input) {
+    return (input.mappingApplied === "obfuscated" &&
+        !input.nativeDependency &&
+        !input.qualityFlags.includes("shell-jar") &&
+        looksLikeDeobfuscatedClassName(input.className));
+}
 function shouldSuggestObfuscatedMapping(artifact, className) {
-    const nativeDependency = artifact.provenance?.dependencyResolution != null;
-    const shellArtifact = artifact.qualityFlags.includes("shell-jar");
-    return (artifact.mappingApplied === "obfuscated" &&
-        !nativeDependency &&
-        !shellArtifact &&
-        looksLikeDeobfuscatedClassName(className));
+    return isObfuscatedNamespaceHintTrue({
+        mappingApplied: artifact.mappingApplied,
+        qualityFlags: artifact.qualityFlags,
+        nativeDependency: artifact.provenance?.dependencyResolution != null,
+        className
+    });
 }
 function classNameToClassPath(className) {
     const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
@@ -175,10 +197,26 @@ export function buildFallbackProvenance(svc, input) {
         transformChain
     };
 }
+/**
+ * Near-miss candidates from the requested artifact's index followed by any the
+ * lookup's final artifact contributes, deduplicated by FQN so a class present in
+ * both is reported once, under the requested artifact.
+ */
+function unionDidYouMeanCandidates(svc, requestedArtifactId, endedOnArtifactId, className) {
+    const requested = collectDidYouMeanCandidates(svc, requestedArtifactId, className);
+    if (endedOnArtifactId === requestedArtifactId) {
+        return requested;
+    }
+    const seen = new Set(requested.map((candidate) => candidate.className));
+    const fromFallback = collectDidYouMeanCandidates(svc, endedOnArtifactId, className, endedOnArtifactId).filter((candidate) => !seen.has(candidate.className));
+    return [...requested, ...fromFallback];
+}
 export function buildClassSourceNotFoundError(svc, input) {
     const simpleName = input.className.split(/[.$]/).at(-1) ?? input.className;
+    const requestedArtifactId = input.requestedArtifactId ?? input.artifactId;
     const details = {
-        artifactId: input.artifactId,
+        artifactId: requestedArtifactId,
+        ...(input.artifactId !== requestedArtifactId ? { fallbackArtifactId: input.artifactId } : {}),
         className: input.className,
         mapping: input.mappingApplied,
         qualityFlags: input.qualityFlags,
@@ -191,12 +229,18 @@ export function buildClassSourceNotFoundError(svc, input) {
         ...(input.nestedJars && input.nestedJars.length > 0 ? { nestedJars: input.nestedJars } : {}),
         // Candidates are hints from the symbol index, never assertions that the
         // class exists at the suggested location; empty when nothing usable.
-        didYouMean: collectDidYouMeanCandidates(svc, input.artifactId, input.className)
+        //
+        // Both indexes are consulted, requested artifact first. Collecting from the
+        // requested artifact ALONE is empty by construction in the scenario the
+        // partial-source fallback exists to serve: that artifact is the one without
+        // net.minecraft symbols, which is why the fallback fired and indexed the other
+        // jar. Candidates from the artifact the caller did not name carry its id.
+        didYouMean: unionDidYouMeanCandidates(svc, requestedArtifactId, input.artifactId, input.className)
     };
     let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
     let suggestionSpec = {
         tool: "find-class",
-        params: { className: simpleName, artifactId: input.artifactId }
+        params: { className: simpleName, artifactId: requestedArtifactId }
     };
     if (input.targetKind === "version" && input.scope && input.scope !== "merged" && !input.projectPath) {
         nextAction +=
@@ -225,11 +269,32 @@ export function buildClassSourceNotFoundError(svc, input) {
         else {
             suggestionSpec = {
                 tool: "find-class",
-                params: { className: simpleName, artifactId: input.artifactId }
+                params: { className: simpleName, artifactId: requestedArtifactId }
             };
         }
     }
-    if (input.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(input.className)) {
+    // Two gates, because the hint fails in two independent ways.
+    //
+    // `isObfuscatedNamespaceHintTrue` decides whether the claim is even true of
+    // this artifact — a dependency jar or a shell jar reports "obfuscated"
+    // without being an obfuscated index, and used to be told to remap itself.
+    //
+    // The second gate is about the ASK, not the claim: the hint ends in
+    // `mapping="mojang"`, so firing it at a caller who already sent a
+    // non-obfuscated mapping asks for the argument they just supplied and sends
+    // them round the same call again. The generic backstop in
+    // `dropSatisfiedParameterAsks` cannot rescue this one — it matches an
+    // imperative "Provide/Pass mapping", and the sentence is concatenated into
+    // the same `nextAction` string as the find-class guidance, which is published
+    // as a single hint that no mid-string excision can repair.
+    const callerAskedForNonObfuscatedMapping = input.callerSuppliedMapping != null && input.callerSuppliedMapping !== "obfuscated";
+    if (!callerAskedForNonObfuscatedMapping &&
+        isObfuscatedNamespaceHintTrue({
+            mappingApplied: input.mappingApplied,
+            qualityFlags: input.qualityFlags,
+            nativeDependency: input.nativeDependency === true,
+            className: input.className
+        })) {
         nextAction += ` ${obfuscatedNamespaceHint(input.className)}`;
     }
     details.nextAction = nextAction;
@@ -403,13 +468,14 @@ export function findClass(svc, input) {
         const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
             ? []
             : matches;
-        if (filteredMatches.length === 0 && partialVanillaLookup) {
-            warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
-        }
-        if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
-            warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
-        }
-        return { matches: filteredMatches, total: filteredMatches.length, warnings };
+        return finishFindClass(svc, {
+            artifact,
+            artifactId,
+            className,
+            matches: filteredMatches,
+            partialVanillaLookup,
+            warnings
+        });
     }
     const result = svc.symbolsRepo.findScopedSymbols({
         artifactId,
@@ -418,32 +484,82 @@ export function findClass(svc, input) {
         symbolKinds: TYPE_SYMBOL_KINDS,
         limit: limit * 5
     });
-    const matches = [];
+    // The extractor stores ONE qualifiedName per FILE (the top-level type), so a
+    // nested type's row carries its OUTER type's FQN. Reporting that verbatim
+    // returned a qualifiedName that did not contain the searched token at all —
+    // feeding match[0] into get-class-source then fetched the wrong class.
+    const candidates = [];
     for (const row of result.items) {
-        if (matches.length >= limit)
-            break;
         const isTypeSymbol = row.symbolKind === "class" || row.symbolKind === "interface" ||
             row.symbolKind === "enum" || row.symbolKind === "record";
         if (!isTypeSymbol)
             continue;
-        matches.push({
-            qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
+        const enclosingQualifiedName = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+        const enclosingSimpleName = enclosingQualifiedName.split(".").at(-1) ?? enclosingQualifiedName;
+        const nested = enclosingSimpleName !== row.symbolName;
+        candidates.push({
+            qualifiedName: nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName,
             filePath: row.filePath,
             line: row.line,
-            symbolKind: row.symbolKind
+            symbolKind: row.symbolKind,
+            ...(nested ? { nested: true, enclosingClass: enclosingQualifiedName } : {})
         });
     }
+    // A top-level type named exactly like the query is what the caller almost
+    // always means; a nested type that merely shares the simple name comes after.
+    candidates.sort((left, right) => {
+        const leftNested = left.nested === true ? 1 : 0;
+        const rightNested = right.nested === true ? 1 : 0;
+        if (leftNested !== rightNested)
+            return leftNested - rightNested;
+        return left.qualifiedName.localeCompare(right.qualifiedName);
+    });
+    const matches = candidates.slice(0, limit);
     const partialVanillaLookup = hasPartialNetMinecraftCoverage(artifact.qualityFlags) && looksLikeDeobfuscatedClassName(className);
     const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
         ? []
         : matches;
-    if (filteredMatches.length === 0 && partialVanillaLookup) {
+    return finishFindClass(svc, {
+        artifact,
+        artifactId,
+        className,
+        matches: filteredMatches,
+        partialVanillaLookup,
+        warnings
+    });
+}
+/**
+ * Shared tail for both findClass branches: coverage/namespace warnings plus a
+ * machine-usable recovery route.
+ *
+ * An empty result on an artifact whose index excludes net.minecraft is
+ * internally consistent but externally contradictory — get-class-source answers
+ * the SAME class from the binary fallback. The caller therefore gets both the
+ * reason and the exact call that works.
+ */
+function finishFindClass(svc, input) {
+    const { artifact, artifactId, className, matches, partialVanillaLookup, warnings } = input;
+    let suggestedCall;
+    if (matches.length === 0 && partialVanillaLookup) {
         warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
+        suggestedCall = buildSuggestedCall({
+            tool: "get-class-source",
+            params: {
+                className,
+                target: { kind: "artifact", artifactId },
+                mode: "metadata"
+            }
+        }).suggestedCall;
     }
-    if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
+    if (matches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
         warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
     }
-    return { matches: filteredMatches, total: filteredMatches.length, warnings };
+    return {
+        matches,
+        total: matches.length,
+        warnings,
+        ...(suggestedCall ? { suggestedCall } : {})
+    };
 }
 export async function findClassIncludingNested(svc, input) {
     const indexed = findClass(svc, input);
@@ -507,6 +623,9 @@ export async function getClassSource(svc, input) {
     }
     let artifactId = normalizedArtifactId;
     let origin = "local-jar";
+    // Derivation, tracked separately from origin: whether the indexed text was
+    // produced by decompiling bytecode. Only the persisted flag answers that.
+    let isDecompiled = false;
     let warnings = [];
     let requestedMapping = normalizeMapping(input.mapping);
     let mappingApplied = requestedMapping;
@@ -536,6 +655,7 @@ export async function getClassSource(svc, input) {
         });
         artifactId = resolved.artifactId;
         origin = resolved.origin;
+        isDecompiled = resolved.isDecompiled;
         warnings = [...resolved.warnings];
         requestedMapping = resolved.requestedMapping;
         mappingApplied = resolved.mappingApplied;
@@ -550,7 +670,8 @@ export async function getClassSource(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
-        requestedMapping = input.mapping != null ? requestedMapping : (artifact.requestedMapping ?? requestedMapping);
+        isDecompiled = artifact.isDecompiled;
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -570,6 +691,7 @@ export async function getClassSource(svc, input) {
     mappingApplied = reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied);
     let activeArtifactId = artifactId;
     let activeOrigin = origin;
+    let activeIsDecompiled = isDecompiled;
     let activeProvenance = provenance;
     let activeQualityFlags = [...qualityFlags];
     let activeMappingApplied = mappingApplied;
@@ -595,13 +717,18 @@ export async function getClassSource(svc, input) {
             requestedMapping,
             mappingApplied,
             provenance: activeProvenance,
-            qualityFlags: activeQualityFlags
+            qualityFlags: activeQualityFlags,
+            // A caller who declined decompilation must not pay for one here: the
+            // fallback used to hardcode allowDecompile:true and silently ran a full
+            // Vineflower pass on the binary jar.
+            allowDecompile: input.allowDecompile
         });
         if (!fallbackResolved || fallbackResolved.artifactId === activeArtifactId) {
             return false;
         }
         activeArtifactId = fallbackResolved.artifactId;
         activeOrigin = fallbackResolved.origin;
+        activeIsDecompiled = fallbackResolved.isDecompiled;
         activeMappingApplied = fallbackResolved.mappingApplied ?? activeMappingApplied;
         activeProvenance = fallbackResolved.provenance ?? activeProvenance;
         activeQualityFlags = dedupeQualityFlags([...(fallbackResolved.qualityFlags ?? []), "binary-fallback"]);
@@ -644,6 +771,9 @@ export async function getClassSource(svc, input) {
         });
         activeArtifactId = redirectResolved.artifactId;
         activeOrigin = redirectResolved.origin;
+        // The INNER jar's derivation: the shell that bundled it holds no source of
+        // its own, so its flag says nothing about the text being returned here.
+        activeIsDecompiled = redirectResolved.isDecompiled;
         activeMappingApplied = redirectResolved.mappingApplied ?? activeMappingApplied;
         activeProvenance = redirectResolved.provenance
             ? {
@@ -689,11 +819,17 @@ export async function getClassSource(svc, input) {
     if (!filePath) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
+            callerSuppliedMapping: input.mapping,
+            nativeDependency: provenance?.dependencyResolution != null,
             attemptedBinaryFallback,
             targetKind: input.target?.kind,
             targetValue: input.target && "value" in input.target ? input.target.value : undefined,
@@ -728,11 +864,17 @@ export async function getClassSource(svc, input) {
     if (!row) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
+            callerSuppliedMapping: input.mapping,
+            nativeDependency: provenance?.dependencyResolution != null,
             attemptedBinaryFallback,
             filePath,
             targetKind: input.target?.kind,
@@ -800,7 +942,16 @@ export async function getClassSource(svc, input) {
     // decompiled source vs `gameRenderState()` in the runtime jar). Flag it so
     // callers verify names against get-class-members (bytecode-derived) before
     // copying signatures out of this source.
-    if (activeOrigin === "decompiled") {
+    //
+    // The gate is the persisted `isDecompiled` flag, never `origin === "decompiled"`:
+    // origin records WHERE the bytes came from, derivation records WHETHER the text
+    // was decompiled, and the two disagree. A Jar-in-Jar shell keeps the origin the
+    // resolver chose while ingest clears its derivation flag (src/source/indexer.ts),
+    // so an origin-keyed gate warned about decompiled signatures for a jar that holds
+    // no source at all. file-access, search, artifact-resolver and the mapping
+    // pipeline all read the boolean; do not "restore consistency" by keying this
+    // back on the origin.
+    if (activeIsDecompiled) {
         activeQualityFlags = dedupeQualityFlags([
             ...activeQualityFlags,
             "decompiled-source-signatures-unverified"
@@ -832,7 +983,7 @@ export async function getClassSource(svc, input) {
         artifactContents: svc.buildArtifactContentsSummary({
             origin: activeOrigin,
             sourceJarPath: activeSourceJarPath,
-            isDecompiled: activeOrigin === "decompiled",
+            isDecompiled: activeIsDecompiled,
             qualityFlags: activeQualityFlags
         }),
         ...(continuation?.suggestedCall ? { suggestedCall: continuation.suggestedCall } : {}),
@@ -865,6 +1016,8 @@ export async function getClassMembers(svc, input) {
     }
     let artifactId = normalizedArtifactId;
     let origin = "local-jar";
+    // See getClassSource: derivation is the persisted flag, not the origin.
+    let isDecompiled = false;
     let warnings = [];
     let mappingApplied = requestedMapping;
     let provenance;
@@ -896,6 +1049,7 @@ export async function getClassMembers(svc, input) {
         });
         artifactId = resolved.artifactId;
         origin = resolved.origin;
+        isDecompiled = resolved.isDecompiled;
         warnings.push(...resolved.warnings);
         requestedMapping = resolved.requestedMapping;
         mappingApplied = resolved.mappingApplied;
@@ -910,6 +1064,8 @@ export async function getClassMembers(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
+        isDecompiled = artifact.isDecompiled;
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -939,12 +1095,27 @@ export async function getClassMembers(svc, input) {
         });
     }
     if (!binaryJarPath) {
+        // The override below applies only when the TOOL picked this artifact
+        // without the caller expressing an opinion on it: a version/coordinate
+        // target, or falling through the workspace/dependency shapes. A caller who
+        // passed `artifactId` directly, or `target: { kind: "jar", ... }`, named
+        // the exact artifact/jar themselves - having no binary companion is then
+        // exactly the input they can change.
+        const artifactWasCallerNamed = Boolean(normalizedArtifactId) || input.target?.kind === "jar";
         throw createError({
             code: ERROR_CODES.CONTEXT_UNRESOLVED,
             message: `Class members require a binary jar, but artifact "${artifactId}" has no binaryJarPath.`,
             details: {
                 artifactId,
                 className,
+                // `ERR_CONTEXT_UNRESOLVED` classifies as `code_issue` by code, which is
+                // right for the sibling case (a caller naming a version no artifact
+                // carries) and wrong when the artifact was resolved by the TOOL, since
+                // whether it carries a binary jar is not something that request could
+                // express. Published as caller-fixable it invites an endless retry of
+                // an input that was never at fault, so this site overrides the default
+                // for the tool-resolved case only.
+                issueOrigin: artifactWasCallerNamed ? undefined : "tool_issue",
                 nextAction: "Resolve with target: { kind: \"jar\" | \"version\", value: ... } or use an artifact that has a binary jar."
             }
         });
@@ -1037,6 +1208,8 @@ export async function getClassMembers(svc, input) {
                 mappingApplied,
                 requestedMapping,
                 qualityFlags,
+                callerSuppliedMapping: input.mapping,
+                nativeDependency: provenance?.dependencyResolution != null,
                 attemptedBinaryFallback: true,
                 targetKind: input.target?.kind,
                 targetValue: input.target && "value" in input.target ? input.target.value : undefined,
@@ -1179,7 +1352,18 @@ export async function getClassMembers(svc, input) {
         truncated,
         ...(nextCursor ? { nextCursor } : {}),
         ...(memberCursorIgnored ? { cursorIgnored: true } : {}),
-        context: signatureContext,
+        context: {
+            ...signatureContext,
+            // The jar-derived context describes the BYTECODE the reader opened. The
+            // members handed back have already been remapped into requestedMapping,
+            // so echoing the jar namespace here contradicted `returnedNamespace` in
+            // the same payload. Report what the response actually contains, and fill
+            // the version the resolver established when the jar path yielded none.
+            ...(signatureContext.minecraftVersion === "unknown" && version
+                ? { minecraftVersion: version }
+                : {}),
+            mappingNamespace: requestedMapping
+        },
         origin,
         artifactId,
         requestedMapping,
@@ -1190,7 +1374,7 @@ export async function getClassMembers(svc, input) {
         artifactContents: svc.buildArtifactContentsSummary({
             origin,
             sourceJarPath,
-            isDecompiled: origin === "decompiled",
+            isDecompiled,
             qualityFlags: fallbackQualityFlags
         }),
         ...(decompiledFallback ? { decompiledFallback } : {}),

package/dist/source/did-you-mean.d.ts

@@ -2,6 +2,13 @@ import type { SourceService } from "../source-service.js";
 export interface DidYouMeanCandidate {
     className: string;
     matchReason: string;
+    /**
+     * Set only when the candidate was found in an artifact OTHER than the one the caller
+     * named — today, the internal binary fallback or nested-jar redirect the lookup ended
+     * on. An unattributed candidate always means "in the artifact you asked about", so the
+     * field marks the exception rather than restating the common case on every entry.
+     */
+    artifactId?: string;
 }
 /**
  * Collects ranked near-miss class candidates from the artifact's symbol
@@ -10,5 +17,9 @@ export interface DidYouMeanCandidate {
  * edit-distance suggestions. Candidates are hints, never assertions that the
  * class exists at the suggested location. Returns an empty array when the
  * index has nothing usable.
+ *
+ * `attributeTo` stamps every produced candidate with that artifact id; pass it when
+ * collecting from an artifact the caller did not name, and leave it unset for the
+ * requested artifact.
  */
-export declare function collectDidYouMeanCandidates(svc: SourceService, artifactId: string, className: string): DidYouMeanCandidate[];
+export declare function collectDidYouMeanCandidates(svc: SourceService, artifactId: string, className: string, attributeTo?: string): DidYouMeanCandidate[];

package/dist/source/did-you-mean.js

@@ -15,8 +15,12 @@ function fqnOfRow(row) {
  * edit-distance suggestions. Candidates are hints, never assertions that the
  * class exists at the suggested location. Returns an empty array when the
  * index has nothing usable.
+ *
+ * `attributeTo` stamps every produced candidate with that artifact id; pass it when
+ * collecting from an artifact the caller did not name, and leave it unset for the
+ * requested artifact.
  */
-export function collectDidYouMeanCandidates(svc, artifactId, className) {
+export function collectDidYouMeanCandidates(svc, artifactId, className, attributeTo) {
     try {
         const simpleName = className.split(/[.$]/).at(-1) ?? className;
         if (!simpleName) {
@@ -29,7 +33,7 @@ export function collectDidYouMeanCandidates(svc, artifactId, className) {
                 return;
             }
             seen.add(fqn);
-            out.push({ className: fqn, matchReason });
+            out.push({ className: fqn, matchReason, ...(attributeTo ? { artifactId: attributeTo } : {}) });
         };
         const exact = svc.symbolsRepo.findScopedSymbols({
             artifactId,