agent-codinglanguage-mapper 1.0.0__py3-none-any.whl

agent_codinglanguage_mapper/indexer.py

@@ -0,0 +1,1102 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from collections import defaultdict
+from dataclasses import dataclass, field, replace
+from pathlib import Path, PurePosixPath
+import re
+from typing import Iterable, Mapping
+
+from .adapters import AdapterResult, DelphiAdapter, LanguageAdapter, adapter_for
+from .adapters.delphi_frontend.project_discovery import DelphiProjectDiscovery, discover_delphi_project
+from .discovery import discover_workspace, workspace_directory_inventory, workspace_inventory
+from .models import Language, Problem, Reference, Relation, Resolution, SourceFile, SourceRange, Symbol
+from .workspace import WorkspaceSnapshot, stable_id
+
+
+@dataclass
+class _CachedParse:
+    project_id: str
+    file_id: str
+    language: Language
+    source: str
+    source_digest: str
+    source_stamp: tuple[int, int, int] | None
+    context: tuple[str, ...]
+    adapter: LanguageAdapter
+    outline: AdapterResult
+    result: AdapterResult
+    dependency_stamps: tuple[tuple[str, tuple[int, int, int] | None], ...] = ()
+
+
+@dataclass(frozen=True)
+class _ImportRule:
+    project_id: str
+    path: str
+    language: Language
+    import_path: str
+    imported_symbols: tuple[tuple[str, str], ...]
+    module_alias: str
+    wildcard: bool
+    project_wide: bool
+
+
+@dataclass
+class WorkspaceIndexCache:
+    entries: dict[str, _CachedParse] = field(default_factory=dict)
+    inventory: tuple[tuple[str, int, int, str], ...] = ()
+    directories: tuple[tuple[str, int], ...] = ()
+
+    def sources_changed(self, root: Path) -> bool:
+        if any(
+            not _dependencies_unchanged(cached.dependency_stamps)
+            for cached in self.entries.values()
+        ):
+            return True
+        for relative, cached in self.entries.items():
+            path = root / relative
+            if _source_stamp(path) != cached.source_stamp:
+                return True
+        for relative, modified, size, digest in self.inventory:
+            if relative in self.entries:
+                continue
+            path = root / relative
+            if digest:
+                if _inventory_stamp(path) != (modified, size, digest):
+                    return True
+            elif (stamp := _source_stamp(path)) is None or stamp[:2] != (modified, size):
+                return True
+        if all(
+            _directory_stamp(root if relative == "." else root / relative) == modified
+            for relative, modified in self.directories
+        ):
+            return False
+        new_inventory = workspace_inventory(root)
+        self.directories = workspace_directory_inventory(root)
+        return new_inventory != self.inventory
+
+
+def build_workspace_snapshot(
+    root: str | Path,
+    languages: Iterable[Language] | None = None,
+    source_overrides: Mapping[str, str] | None = None,
+    detail_files: Iterable[str] | None = None,
+    base_snapshot: WorkspaceSnapshot | None = None,
+    index_cache: WorkspaceIndexCache | None = None,
+) -> WorkspaceSnapshot:
+    workspace = Path(root).expanduser().resolve()
+    discovery = discover_workspace(workspace, languages)
+    files: list[SourceFile] = []
+    symbols: list[Symbol] = []
+    references: list[Reference] = []
+    relations: list[Relation] = []
+    problems: list[Problem] = list(discovery.problems)
+    source_digests: list[tuple[str, str]] = []
+    base_digests = dict(base_snapshot.source_digests) if base_snapshot is not None else {}
+    projects_by_id = {item.project_id: item for item in discovery.projects}
+    delphi_configs: dict[str, DelphiProjectDiscovery] = {}
+    selected_detail_files = None if detail_files is None else {Path(item).as_posix() for item in detail_files}
+    incremental_detail = base_snapshot is not None and selected_detail_files is not None
+    base_files_by_path = (
+        {item.path: item for item in base_snapshot.files}
+        if incremental_detail and base_snapshot is not None
+        else {}
+    )
+    active_cache_paths: set[str] = set()
+    if incremental_detail and base_snapshot is not None:
+        problems.extend(
+            item
+            for item in base_snapshot.problems
+            if not _problem_source_path(item) and item not in problems
+        )
+
+    for found in discovery.files:
+        relative = found.path.relative_to(workspace).as_posix()
+        include_detail = (
+            (selected_detail_files is None or relative in selected_detail_files)
+            and found.path.suffix.casefold() != ".inc"
+        )
+        file_id = stable_id("file", found.project_id, relative)
+        project = projects_by_id[found.project_id]
+        if found.language is Language.DELPHI:
+            config = delphi_configs.get(project.project_id)
+            if config is None:
+                config = discover_delphi_project(
+                    project.root,
+                    project_file=_delphi_project_file(project.root, project.name),
+                    scan_workspace_sources=False,
+                )
+                delphi_configs[project.project_id] = config
+                problems.extend(
+                    Problem(
+                        f"delphi-project-{item.kind}",
+                        item.message,
+                        "warning",
+                        Language.DELPHI,
+                        metadata={"origin": item.origin},
+                    )
+                    for item in config.problems
+                )
+            candidate_adapter: LanguageAdapter = DelphiAdapter(
+                include_paths=(*config.include_paths, *config.search_paths),
+                defines=config.defines,
+                workspace_root=workspace,
+            )
+            adapter_context = (
+                found.language.value,
+                project.root,
+                *(str(item) for item in (*config.include_paths, *config.search_paths)),
+                "\0defines",
+                *config.defines,
+            )
+        else:
+            candidate_adapter = adapter_for(
+                found.language,
+                workspace_root=workspace,
+                include_paths=found.include_paths,
+            )
+            adapter_context = (
+                found.language.value,
+                str(workspace),
+                *(str(item) for item in found.include_paths),
+            )
+
+        has_override = source_overrides is not None and relative in source_overrides
+        source_override = source_overrides[relative] if has_override and source_overrides is not None else ""
+        if has_override:
+            adapter_context = (*adapter_context, "\0override", _source_digest(source_override))
+        current_stamp = None if has_override else _source_stamp(found.path)
+        cached = index_cache.entries.get(relative) if index_cache is not None else None
+        cache_matches = (
+            cached is not None
+            and cached.project_id == found.project_id
+            and cached.file_id == file_id
+            and cached.language is found.language
+            and cached.context == adapter_context
+            and (
+                cached.source_digest == _source_digest(source_override)
+                if has_override
+                else current_stamp is not None and cached.source_stamp == current_stamp
+            )
+            and _dependencies_unchanged(cached.dependency_stamps)
+        )
+        existing_file = base_files_by_path.get(relative)
+        if (
+            incremental_detail
+            and not include_detail
+            and base_snapshot is not None
+            and existing_file is not None
+            and existing_file.file_id == file_id
+            and existing_file.language is found.language
+            and existing_file.project_id == found.project_id
+            and cache_matches
+        ):
+            files.append(existing_file)
+            digest = base_digests.get(relative)
+            if digest is not None:
+                source_digests.append((relative, digest))
+            existing_symbols = base_snapshot.symbols_by_file.get(existing_file.file_id, ())
+            existing_symbol_ids = {item.target_id for item in existing_symbols}
+            symbols.extend(existing_symbols)
+            references.extend(item for item in base_snapshot.references if item.range.path == relative)
+            relations.extend(
+                item
+                for item in base_snapshot.relations
+                if item.source_id in existing_symbol_ids
+                or (not item.source_id and any(evidence.path == relative for evidence in item.evidence))
+            )
+            problems.extend(
+                item for item in base_snapshot.problems if _problem_source_path(item) == relative
+            )
+            if index_cache is not None and relative in index_cache.entries:
+                active_cache_paths.add(relative)
+            continue
+
+        files.append(SourceFile(file_id, relative, found.language, found.project_id))
+        if cache_matches and cached is not None:
+            source = cached.source
+            source_digest = cached.source_digest
+            adapter = cached.adapter
+            source_stamp = cached.source_stamp
+            outline = cached.outline
+        else:
+            try:
+                if has_override:
+                    source = source_override
+                    source_digest = _source_digest(source)
+                    source_stamp = None
+                else:
+                    source, source_digest, source_stamp = _read_stable_source(found.path)
+            except OSError as exc:
+                if index_cache is not None:
+                    index_cache.entries.pop(relative, None)
+                problems.append(
+                    Problem(
+                        "source-read-failed",
+                        f"Could not read {relative}: {exc}",
+                        "error",
+                        found.language,
+                        metadata={"path": relative, "error": type(exc).__name__},
+                    )
+                )
+                continue
+            adapter = candidate_adapter
+            outline = adapter.parse_outline(relative, source)
+        result = (
+            adapter.resolve(adapter.parse_detail(relative, source, outline))
+            if include_detail
+            else outline
+        )
+        if index_cache is not None:
+            index_cache.entries[relative] = _CachedParse(
+                found.project_id,
+                file_id,
+                found.language,
+                source,
+                source_digest,
+                source_stamp,
+                adapter_context,
+                adapter,
+                outline,
+                result,
+                _dependency_stamps(workspace, result.document),
+            )
+            active_cache_paths.add(relative)
+        source_digests.append((relative, source_digest))
+        normalized_symbols = tuple(
+            replace(
+                item,
+                range=_workspace_required_range(workspace, item.range),
+                name_range=_workspace_range(workspace, item.name_range),
+            )
+            for item in result.symbols
+        )
+        ids = {
+            item.target_id: _workspace_symbol_id(found.project_id, file_id, normalized)
+            for item, normalized in zip(result.symbols, normalized_symbols)
+        }
+        symbols.extend(
+            Symbol(
+                ids[item.target_id],
+                item.name,
+                item.qualified_name,
+                item.kind,
+                item.language,
+                normalized.range,
+                found.project_id,
+                file_id,
+                item.signature,
+                item.native_kind,
+                ids.get(item.parent_id, ""),
+                normalized.name_range,
+                item.role,
+            )
+            for item, normalized in zip(result.symbols, normalized_symbols)
+        )
+        references.extend(
+            replace(
+                item,
+                source_id=ids.get(item.source_id, ""),
+                target_id=ids.get(item.target_id, ""),
+                range=_workspace_required_range(workspace, item.range),
+            )
+            for item in result.references
+        )
+        local_symbols_by_id = {item.target_id: item for item in result.symbols}
+        for item in result.relations:
+            relation_library = item.target_library
+            relation_source = local_symbols_by_id.get(item.source_id)
+            if (
+                not relation_library
+                and item.kind == "ffi"
+                and relation_source is not None
+                and _is_abi_export_symbol(relation_source)
+                and len(found.output_names) == 1
+            ):
+                relation_library = found.output_names[0]
+            relations.append(
+                replace(
+                    item,
+                    source_id=ids.get(item.source_id, ""),
+                    target_id=ids.get(item.target_id, ""),
+                    target_library=relation_library,
+                    evidence=tuple(
+                        _workspace_required_range(workspace, value) for value in item.evidence
+                    ),
+                )
+            )
+        problems.extend(_workspace_problem(workspace, item, relative) for item in result.problems)
+
+    inventory = workspace_inventory(workspace)
+    if index_cache is not None:
+        for cached_path in set(index_cache.entries) - active_cache_paths:
+            del index_cache.entries[cached_path]
+        index_cache.inventory = inventory
+        index_cache.directories = workspace_directory_inventory(workspace)
+
+    symbols, references, relations = _discard_shadowed_fragment_results(
+        symbols,
+        references,
+        relations,
+        files,
+    )
+    problems = _deduplicate_problems(problems)
+    resolved_references, resolved_relations = _resolve_workspace(tuple(symbols), references, relations)
+    return WorkspaceSnapshot(
+        projects=discovery.projects,
+        files=tuple(files),
+        symbols=tuple(symbols),
+        references=resolved_references,
+        relations=resolved_relations,
+        problems=tuple(problems),
+        source_digests=tuple(source_digests),
+        metadata_digests=tuple(
+            (relative, digest)
+            for relative, _modified, _size, digest in inventory
+            if digest
+        ),
+    )
+
+
+def _source_digest(source: str) -> str:
+    return hashlib.sha256(source.encode("utf-8")).hexdigest()
+
+
+def _dependency_stamps(
+    workspace: Path,
+    document: object,
+) -> tuple[tuple[str, tuple[int, int, int] | None], ...]:
+    dependencies = getattr(document, "dependencies", ())
+    if not isinstance(dependencies, tuple):
+        return ()
+    stamped: list[tuple[str, tuple[int, int, int] | None]] = []
+    for value in dependencies:
+        if not isinstance(value, str):
+            continue
+        path = Path(value).expanduser()
+        if not path.is_absolute():
+            path = workspace / path
+        resolved = path.resolve()
+        stamped.append((str(resolved), _source_stamp(resolved)))
+    return tuple(stamped)
+
+
+def _dependencies_unchanged(
+    dependencies: tuple[tuple[str, tuple[int, int, int] | None], ...],
+) -> bool:
+    return all(_source_stamp(Path(path)) == stamp for path, stamp in dependencies)
+
+
+def _workspace_range(workspace: Path, value: SourceRange | None) -> SourceRange | None:
+    if value is None:
+        return None
+    path = _workspace_path(workspace, value.path)
+    return replace(value, path=path)
+
+
+def _workspace_path(workspace: Path, value: str) -> str:
+    source_path = Path(value).expanduser()
+    if source_path.is_absolute():
+        try:
+            return source_path.resolve().relative_to(workspace).as_posix()
+        except ValueError:
+            return str(source_path.resolve())
+    return source_path.as_posix()
+
+
+def _workspace_required_range(workspace: Path, value: SourceRange) -> SourceRange:
+    normalized = _workspace_range(workspace, value)
+    assert normalized is not None
+    return normalized
+
+
+def _workspace_problem(workspace: Path, problem: Problem, fallback_path: str) -> Problem:
+    metadata = dict(problem.metadata)
+    metadata_path = metadata.get("path")
+    if isinstance(metadata_path, str):
+        metadata["path"] = _workspace_path(workspace, metadata_path)
+    normalized = replace(
+        problem,
+        range=_workspace_range(workspace, problem.range),
+        metadata=metadata,
+    )
+    return _problem_for_file(normalized, fallback_path)
+
+
+def _discard_shadowed_fragment_results(
+    symbols: list[Symbol],
+    references: list[Reference],
+    relations: list[Relation],
+    files: list[SourceFile],
+) -> tuple[list[Symbol], list[Reference], list[Relation]]:
+    file_paths = {item.file_id: item.path for item in files}
+
+    def source_key(symbol: Symbol) -> tuple[object, ...]:
+        anchor = symbol.name_range or symbol.range
+        return (
+            symbol.project_id,
+            symbol.language,
+            symbol.qualified_name,
+            symbol.kind,
+            anchor.path,
+            anchor.start_line,
+            anchor.start_character,
+            anchor.end_line,
+            anchor.end_character,
+        )
+
+    contextual_keys = {
+        source_key(symbol)
+        for symbol in symbols
+        if file_paths.get(symbol.file_id, "") != (symbol.name_range or symbol.range).path
+    }
+    discarded_ids: set[str] = set()
+    for symbol in symbols:
+        anchor = symbol.name_range or symbol.range
+        owner_path = file_paths.get(symbol.file_id, "")
+        if (
+            Path(owner_path).suffix.casefold() == ".inc"
+            and owner_path == anchor.path
+            and (
+                source_key(symbol) in contextual_keys
+                or (
+                    symbol.language is Language.DELPHI
+                    and symbol.kind == "unit"
+                    and symbol.name_range is None
+                )
+            )
+        ):
+            discarded_ids.add(symbol.target_id)
+    kept_symbols = [item for item in symbols if item.target_id not in discarded_ids]
+    kept_references = [
+        item
+        for item in references
+        if item.source_id not in discarded_ids and item.target_id not in discarded_ids
+    ]
+    kept_relations = [
+        item
+        for item in relations
+        if item.source_id not in discarded_ids and item.target_id not in discarded_ids
+    ]
+    return kept_symbols, kept_references, kept_relations
+
+
+def _deduplicate_problems(problems: list[Problem]) -> list[Problem]:
+    selected: dict[tuple[object, ...], Problem] = {}
+    for problem in problems:
+        key = (
+            problem.code,
+            problem.message,
+            problem.severity,
+            problem.language,
+            problem.range,
+        )
+        selected.setdefault(key, problem)
+    return list(selected.values())
+
+
+def _read_stable_source(
+    path: Path,
+    *,
+    attempts: int = 3,
+) -> tuple[str, str, tuple[int, int, int]]:
+    for _ in range(attempts):
+        before = _source_stamp(path)
+        if before is None:
+            raise OSError(f"source is unavailable: {path}")
+        encoded = path.read_bytes()
+        after = _source_stamp(path)
+        if after is not None and before == after:
+            if _requires_source_byte_verification():
+                verified = path.read_bytes()
+                verified_stamp = _source_stamp(path)
+                if verified_stamp is None or after != verified_stamp or encoded != verified:
+                    continue
+                encoded = verified
+                after = verified_stamp
+            source = encoded.decode("utf-8-sig", "replace")
+            return source, _source_digest(source), after
+    raise OSError(f"source changed while it was being read: {path}")
+
+
+def _requires_source_byte_verification() -> bool:
+    return os.name == "nt"
+
+
+def _workspace_symbol_id(project_id: str, file_id: str, symbol: Symbol) -> str:
+    anchor = symbol.name_range or symbol.range
+    return stable_id(
+        "symbol",
+        project_id,
+        file_id,
+        symbol.qualified_name,
+        str(anchor.start_line),
+        str(anchor.start_character),
+    )
+
+
+def _source_stamp(path: Path) -> tuple[int, int, int] | None:
+    try:
+        stat = path.stat()
+    except OSError:
+        return None
+    change_time = _windows_change_time(path)
+    return stat.st_mtime_ns, stat.st_size, change_time if change_time is not None else stat.st_ctime_ns
+
+
+def _windows_change_time(path: Path) -> int | None:
+    if os.name != "nt":
+        return None
+    try:
+        import ctypes
+
+        class _FileBasicInfo(ctypes.Structure):
+            _fields_ = (
+                ("CreationTime", ctypes.c_longlong),
+                ("LastAccessTime", ctypes.c_longlong),
+                ("LastWriteTime", ctypes.c_longlong),
+                ("ChangeTime", ctypes.c_longlong),
+                ("FileAttributes", ctypes.c_ulong),
+            )
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+        create_file = kernel32.CreateFileW
+        create_file.argtypes = (
+            ctypes.c_wchar_p,
+            ctypes.c_ulong,
+            ctypes.c_ulong,
+            ctypes.c_void_p,
+            ctypes.c_ulong,
+            ctypes.c_ulong,
+            ctypes.c_void_p,
+        )
+        create_file.restype = ctypes.c_void_p
+        handle = create_file(str(path), 0, 0x7, None, 3, 0x02000000, None)
+        if handle in (None, ctypes.c_void_p(-1).value):
+            return None
+        try:
+            info = _FileBasicInfo()
+            get_info = kernel32.GetFileInformationByHandleEx
+            get_info.argtypes = (
+                ctypes.c_void_p,
+                ctypes.c_int,
+                ctypes.c_void_p,
+                ctypes.c_ulong,
+            )
+            get_info.restype = ctypes.c_int
+            if not get_info(handle, 0, ctypes.byref(info), ctypes.sizeof(info)):
+                return None
+            return int(info.ChangeTime)
+        finally:
+            close_handle = kernel32.CloseHandle
+            close_handle.argtypes = (ctypes.c_void_p,)
+            close_handle.restype = ctypes.c_int
+            close_handle(handle)
+    except (AttributeError, OSError):
+        return None
+
+
+def _inventory_stamp(path: Path) -> tuple[int, int, str] | None:
+    try:
+        stat = path.stat()
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+    return stat.st_mtime_ns, stat.st_size, digest
+
+
+def _directory_stamp(path: Path) -> int | None:
+    try:
+        return path.stat().st_mtime_ns
+    except OSError:
+        return None
+
+
+def _problem_for_file(problem: Problem, path: str) -> Problem:
+    if problem.range is not None or isinstance(problem.metadata.get("path"), str):
+        return problem
+    return replace(problem, metadata={**problem.metadata, "path": path})
+
+
+def _problem_source_path(problem: Problem) -> str:
+    if problem.range is not None:
+        return problem.range.path
+    path = problem.metadata.get("path")
+    return path if isinstance(path, str) else ""
+
+
+def _delphi_project_file(root: str, project_name: str) -> Path | None:
+    project_root = Path(root)
+    try:
+        entries = tuple(project_root.iterdir())
+    except OSError:
+        return None
+    for suffix in (".dpr", ".dpk"):
+        matches = sorted(
+            (
+                candidate
+                for candidate in entries
+                if candidate.is_file()
+                and candidate.stem.casefold() == project_name.casefold()
+                and candidate.suffix.casefold() == suffix
+            ),
+            key=lambda candidate: candidate.name,
+        )
+        if matches:
+            return matches[0]
+    return None
+
+
+def _resolve_workspace(
+    symbols: tuple[Symbol, ...],
+    references: list[Reference],
+    relations: list[Relation],
+) -> tuple[tuple[Reference, ...], tuple[Relation, ...]]:
+    by_name: dict[tuple[Language, str], list[Symbol]] = defaultdict(list)
+    by_id = {item.target_id: item for item in symbols}
+    for symbol in symbols:
+        if symbol.kind == "module":
+            continue
+        by_name[(symbol.language, _name_key(symbol.language, symbol.name))].append(symbol)
+        if symbol.qualified_name != symbol.name:
+            by_name[(symbol.language, _name_key(symbol.language, symbol.qualified_name))].append(symbol)
+
+    visibility = _workspace_visibility(references, by_id)
+
+    abi_exports: dict[tuple[str, str], list[Symbol]] = defaultdict(list)
+    for relation in relations:
+        source = by_id.get(relation.source_id)
+        if (
+            relation.kind == "ffi"
+            and relation.target_name
+            and source is not None
+            and _is_abi_export_symbol(source)
+            and all(
+                item.target_id != source.target_id
+                for item in abi_exports[
+                    (_normalize_library(relation.target_library), relation.target_name)
+                ]
+            )
+        ):
+            library = _normalize_library(relation.target_library)
+            if library:
+                abi_exports[(library, relation.target_name)].append(source)
+
+    resolved_references = tuple(
+        _resolve_reference(item, by_name, by_id, visibility) for item in references
+    )
+    resolved_relations = tuple(
+        _resolve_relation(item, by_name, abi_exports, by_id, visibility) for item in relations
+    )
+    return resolved_references, resolved_relations
+
+
+def _resolve_reference(
+    reference: Reference,
+    by_name: dict[tuple[Language, str], list[Symbol]],
+    by_id: dict[str, Symbol],
+    visibility: tuple[_ImportRule, ...],
+) -> Reference:
+    if reference.reference_kind == "import":
+        return replace(reference, target_id="", resolution=Resolution.UNRESOLVED)
+    if reference.target_id and reference.target_id in by_id:
+        return replace(reference, resolution=Resolution.COMPLETE)
+    if reference.target_id:
+        reference = replace(reference, target_id="", resolution=Resolution.UNRESOLVED)
+
+    source = by_id.get(reference.source_id)
+    if source is None or source.kind in {"module", "unit"}:
+        return replace(
+            reference,
+            target_id="",
+            resolution=_preserve_incomplete_resolution(
+                reference.resolution,
+                Resolution.UNRESOLVED,
+            ),
+        )
+
+    rules = _rules_for_source(source, visibility)
+    candidate_names = {reference.name}
+    candidate_names.update(
+        original
+        for rule in rules
+        for original, alias in rule.imported_symbols
+        if _identifier_equal(reference.language, alias, reference.name)
+    )
+    candidates = [
+        candidate
+        for name in candidate_names
+        for candidate in by_name.get(
+            (reference.language, _name_key(reference.language, name)),
+            [],
+        )
+    ]
+    visible = _visible_candidates(
+        source,
+        candidates,
+        rules,
+        by_id,
+        reference.name,
+        qualifier=reference.qualifier,
+    )
+    target = _unique_logical_candidate(visible)
+    if target is not None:
+        return replace(reference, target_id=target.target_id, resolution=Resolution.COMPLETE)
+    if len(visible) > 1:
+        return replace(reference, target_id="", resolution=Resolution.AMBIGUOUS)
+    return replace(
+        reference,
+        target_id="",
+        resolution=_preserve_incomplete_resolution(reference.resolution, Resolution.UNRESOLVED),
+    )
+
+
+def _resolve_relation(
+    relation: Relation,
+    by_name: dict[tuple[Language, str], list[Symbol]],
+    abi_exports: dict[tuple[str, str], list[Symbol]],
+    by_id: dict[str, Symbol],
+    visibility: tuple[_ImportRule, ...],
+) -> Relation:
+    if relation.kind == "ffi":
+        source = by_id.get(relation.source_id)
+        if source is not None and _is_abi_export_symbol(source):
+            return replace(
+                relation,
+                target_id="",
+                resolution=_preserve_incomplete_resolution(
+                    relation.resolution,
+                    Resolution.SOUND_PARTIAL,
+                ),
+            )
+        library = _normalize_library(relation.target_library)
+        candidates = abi_exports.get((library, relation.target_name), []) if library else []
+        if len(candidates) == 1:
+            return replace(
+                relation,
+                target_id=candidates[0].target_id,
+                resolution=Resolution.COMPLETE,
+            )
+        if len(candidates) > 1:
+            return replace(relation, target_id="", resolution=Resolution.AMBIGUOUS)
+        return replace(
+            relation,
+            target_id="",
+            resolution=_preserve_incomplete_resolution(
+                relation.resolution,
+                Resolution.SOUND_PARTIAL,
+            ),
+        )
+
+    target = by_id.get(relation.target_id)
+    if target is None and relation.target_name:
+        source = by_id.get(relation.source_id)
+        if source is not None:
+            candidates = by_name.get(
+                (source.language, _name_key(source.language, relation.target_name)),
+                [],
+            )
+            visible = _visible_candidates(
+                source,
+                candidates,
+                _rules_for_source(source, visibility),
+                by_id,
+                relation.target_name,
+                for_relation=True,
+            )
+            target = _unique_logical_candidate(visible)
+        else:
+            visible = []
+        if target is None and len(visible) > 1:
+            return replace(relation, target_id="", resolution=Resolution.AMBIGUOUS)
+    if target is None:
+        return replace(
+            relation,
+            target_id="",
+            resolution=_preserve_incomplete_resolution(
+                relation.resolution,
+                Resolution.UNRESOLVED,
+            ),
+        )
+    kind = "implements" if relation.kind == "inherits" and target.kind == "interface" else relation.kind
+    return replace(relation, target_id=target.target_id, kind=kind, resolution=Resolution.COMPLETE)
+
+
+def _workspace_visibility(
+    references: list[Reference],
+    by_id: dict[str, Symbol],
+) -> tuple[_ImportRule, ...]:
+    visibility: list[_ImportRule] = []
+    for reference in references:
+        owner = by_id.get(reference.source_id)
+        if (
+            owner is None
+            or reference.reference_kind != "import"
+            or owner.kind not in {"module", "namespace", "unit"}
+        ):
+            continue
+        visibility.append(
+            _ImportRule(
+                owner.project_id,
+                reference.range.path,
+                reference.language,
+                _scope_key(reference.language, reference.import_path),
+                reference.imported_symbols,
+                reference.module_alias,
+                reference.wildcard_import,
+                reference.project_wide,
+            )
+        )
+    return tuple(visibility)
+
+
+def _rules_for_source(
+    source: Symbol,
+    visibility: tuple[_ImportRule, ...],
+) -> tuple[_ImportRule, ...]:
+    return tuple(
+        rule
+        for rule in visibility
+        if rule.project_id == source.project_id
+        and rule.language is source.language
+        and (rule.project_wide or rule.path == source.range.path)
+    )
+
+
+def _visible_candidates(
+    source: Symbol,
+    candidates: Iterable[Symbol],
+    rules: tuple[_ImportRule, ...],
+    by_id: dict[str, Symbol],
+    reference_name: str,
+    *,
+    qualifier: str = "",
+    for_relation: bool = False,
+) -> list[Symbol]:
+    same_project = [item for item in candidates if item.project_id == source.project_id]
+    local = [item for item in same_project if item.file_id == source.file_id]
+    if local:
+        return local
+    if source.language is Language.CSHARP:
+        same_namespace = [
+            item
+            for item in same_project
+            if _csharp_same_namespace_visible(
+                source,
+                item,
+                by_id,
+                qualifier=qualifier,
+                for_relation=for_relation,
+            )
+        ]
+        if same_namespace:
+            return same_namespace
+    return [
+        item
+        for item in same_project
+        if any(
+            _rule_exposes_candidate(
+                rule,
+                item,
+                by_id,
+                reference_name,
+                qualifier=qualifier,
+                for_relation=for_relation,
+            )
+            for rule in rules
+        )
+    ]
+
+
+def _csharp_namespace(symbol: Symbol, by_id: dict[str, Symbol]) -> str:
+    current: Symbol | None = symbol
+    while current is not None:
+        if current.kind == "namespace":
+            qualified = current.qualified_name
+            module_prefix = f"{PurePosixPath(current.range.path).stem}."
+            return qualified[len(module_prefix):] if qualified.startswith(module_prefix) else qualified
+        current = by_id.get(current.parent_id)
+    return ""
+
+
+def _symbol_module_keys(symbol: Symbol) -> set[str]:
+    path = PurePosixPath(symbol.range.path)
+    without_suffix = path.with_suffix("").as_posix()
+    return {
+        _scope_key(symbol.language, value)
+        for value in {
+            path.name,
+            path.stem,
+            without_suffix,
+            without_suffix.replace("/", "."),
+        }
+        if value
+    }
+
+
+def _rule_exposes_candidate(
+    rule: _ImportRule,
+    candidate: Symbol,
+    by_id: dict[str, Symbol],
+    reference_name: str,
+    *,
+    qualifier: str,
+    for_relation: bool,
+) -> bool:
+    module_matches = _import_path_matches(rule, candidate, by_id)
+    for original, alias in rule.imported_symbols:
+        if (
+            _identifier_equal(rule.language, alias, reference_name)
+            and _identifier_equal(rule.language, original, candidate.name)
+            and module_matches
+        ):
+            return True
+
+    normalized_qualifier = _scope_key(rule.language, qualifier)
+    normalized_alias = _scope_key(rule.language, rule.module_alias)
+    if normalized_alias and normalized_qualifier:
+        qualifier_parts = normalized_qualifier.split(".")
+        alias_parts = normalized_alias.split(".")
+        if qualifier_parts[: len(alias_parts)] == alias_parts and module_matches:
+            remainder = ".".join(qualifier_parts[len(alias_parts):])
+            return not remainder or _candidate_parent_scope(candidate, by_id).endswith(remainder)
+
+    if not rule.wildcard or not module_matches:
+        return False
+    if rule.language is Language.DELPHI:
+        return candidate.role != "implementation"
+    if rule.language is not Language.CSHARP:
+        return True
+
+    candidate_parent = _candidate_parent_scope(candidate, by_id)
+    if normalized_qualifier:
+        expected_parent = ".".join(
+            part for part in (rule.import_path, normalized_qualifier) if part
+        )
+        return candidate_parent == expected_parent
+    if rule.module_alias:
+        return candidate_parent == rule.import_path
+    return for_relation and candidate.kind in {
+        "class",
+        "delegate",
+        "enum",
+        "interface",
+        "record",
+        "struct",
+    }
+
+
+def _import_path_matches(
+    rule: _ImportRule,
+    candidate: Symbol,
+    by_id: dict[str, Symbol],
+) -> bool:
+    if rule.language is Language.CSHARP:
+        scope = _candidate_scope(candidate, by_id)
+        return scope == rule.import_path or scope.startswith(f"{rule.import_path}.")
+    return rule.import_path in _symbol_module_keys(candidate)
+
+
+def _candidate_scope(symbol: Symbol, by_id: dict[str, Symbol]) -> str:
+    namespace = _csharp_namespace(symbol, by_id)
+    parents: list[str] = []
+    current = by_id.get(symbol.parent_id)
+    while current is not None and current.kind not in {"module", "namespace"}:
+        parents.append(current.name)
+        current = by_id.get(current.parent_id)
+    return ".".join(part for part in (namespace, *reversed(parents), symbol.name) if part)
+
+
+def _candidate_parent_scope(symbol: Symbol, by_id: dict[str, Symbol]) -> str:
+    scope = _candidate_scope(symbol, by_id)
+    return scope.rsplit(".", 1)[0] if "." in scope else ""
+
+
+def _csharp_same_namespace_visible(
+    source: Symbol,
+    candidate: Symbol,
+    by_id: dict[str, Symbol],
+    *,
+    qualifier: str,
+    for_relation: bool,
+) -> bool:
+    if _csharp_namespace(source, by_id) != _csharp_namespace(candidate, by_id):
+        return False
+    if for_relation:
+        return candidate.kind in {"class", "delegate", "enum", "interface", "record", "struct"}
+    if qualifier:
+        return _candidate_parent_scope(candidate, by_id).endswith(_scope_key(Language.CSHARP, qualifier))
+    return _candidate_parent_scope(source, by_id) == _candidate_parent_scope(candidate, by_id)
+
+
+def _scope_key(language: Language, value: str) -> str:
+    normalized = value.strip().strip(";<>\"'").replace("\\", "/")
+    normalized = normalized.replace("::", ".").replace("/", ".")
+    normalized = re.sub(r"^(?:crate|self)\.", "", normalized)
+    return _name_key(language, normalized.strip("."))
+
+
+def _identifier_equal(language: Language, left: str, right: str) -> bool:
+    return _name_key(language, left) == _name_key(language, right)
+
+
+def _unique_logical_candidate(candidates: Iterable[Symbol]) -> Symbol | None:
+    unique = {item.target_id: item for item in candidates}
+    if len(unique) == 1:
+        return next(iter(unique.values()))
+    values = list(unique.values())
+    if not values or any(item.language is not Language.DELPHI for item in values):
+        return None
+    logical_keys = {
+        (
+            item.project_id,
+            item.file_id,
+            item.qualified_name.casefold(),
+            item.kind,
+            " ".join(item.signature.casefold().split()),
+        )
+        for item in values
+    }
+    if len(logical_keys) != 1:
+        return None
+    role_order = {"declaration": 0, "definition": 1, "implementation": 2}
+    return min(
+        values,
+        key=lambda item: (
+            role_order.get(item.role, 3),
+            item.range.start_line,
+            item.range.start_character,
+        ),
+    )
+
+
+def _name_key(language: Language, name: str) -> str:
+    return name.casefold() if language is Language.DELPHI else name
+
+
+def _normalize_library(value: str) -> str:
+    name = PurePosixPath(value.replace("\\", "/")).name.casefold()
+    name = re.sub(r"\.(?:dll|dylib|so)(?:\.\d+)*$", "", name)
+    if name.startswith("lib") and len(name) > 3:
+        name = name[3:]
+    return name
+
+
+def _is_abi_export_symbol(symbol: Symbol) -> bool:
+    if symbol.language is Language.CPP:
+        return symbol.kind == "function" and symbol.native_kind == "function_definition"
+    if symbol.language is Language.RUST:
+        return symbol.kind == "function" and symbol.native_kind == "function_item"
+    if symbol.language is Language.DELPHI:
+        return symbol.kind in {"constructor", "destructor", "function", "method", "procedure"} and (
+            symbol.role == "implementation"
+        )
+    return False
+
+
+def _preserve_incomplete_resolution(
+    resolution: Resolution,
+    fallback: Resolution,
+) -> Resolution:
+    return fallback if resolution is Resolution.COMPLETE else resolution