Function resolveJvmImport

src/resolution/import-resolver.ts:1242–1274

(
  ref: UnresolvedRef,
  context: ResolutionContext
)

 * package_declaration namespace wrappers in the extractor.
 */
export function resolveJvmImport(
  ref: UnresolvedRef,
  context: ResolutionContext
): ResolvedRef | null {
  if (ref.referenceKind !== 'imports') return null;
  if (ref.language !== 'java' && ref.language !== 'kotlin') return null;

  const fqn = ref.referenceName;
  const lastDot = fqn.lastIndexOf('.');
  if (lastDot <= 0) return null;
  const pkg = fqn.substring(0, lastDot);
  const sym = fqn.substring(lastDot + 1);
  // Wildcard imports (`com.example.*`) deliberately punt to name-matcher.
  if (sym === '*') return null;

  const candidates = context.getNodesByQualifiedName(`${pkg}::${sym}`);
  if (candidates.length === 0) return null;

  // Kotlin Multiplatform: an `expect` declaration and its `actual`s share one
  // FQN across source sets (commonMain / androidMain / appleMain). Taking the
  // first candidate let a single platform `actual` absorb every common-side
  // import, so the `expect` (the canonical API a commonMain file imports)
  // looked unused. Prefer the candidate CLOSEST to the importing file by
  // directory proximity — a commonMain import resolves to the commonMain
  // declaration — with the `expect` side as a tiebreak.
  const best = candidates.length === 1 ? candidates[0]! : pickClosestJvmCandidate(candidates, ref.filePath);
  return {
    original: ref,
    targetNodeId: best.id,
    confidence: 0.95,
    resolvedBy: 'import',
  };
}

/**
 * Pick the same-FQN candidate closest to `fromPath` by shared directory