code-atlas-forge 1.1.0__py3-none-any.whl

code_atlas/resolvers/coordinator.py

@@ -0,0 +1,96 @@
+"""Coordenador de resolução — cadeia por precedência de evidência.
+
+Política (documentada): itera resolvedores em ordem de ``EvidenceTier``
+crescente (índice semântico → LSP → sintático → heurístico). Para no
+primeiro resultado ``resolved`` inequívoco — tiers mais baixos não
+aprimoram um resultado já confirmado. Se nenhum resolver devolve
+``resolved``, o resultado do **tier mais alto disponível** é devolvido
+com seu status honesto (ambiguous/unresolved/external) — nunca promovido.
+Exceções de resolvedor viram diagnóstico, não crash.
+"""
+
+from __future__ import annotations
+
+from code_atlas.resolvers.contracts import (
+    ResolutionDiagnostic,
+    ResolutionRequest,
+    ResolutionResult,
+    SemanticResolver,
+    relation_for_kind,
+)
+from code_atlas.resolvers.registry import ResolverRegistry
+
+
+class ResolverCoordinator:
+    """Encadeia resolvers registrados por ordem de evidência."""
+
+    def __init__(self, registry: ResolverRegistry) -> None:
+        self._registry = registry
+
+    def candidates(
+        self, request: ResolutionRequest
+    ) -> list[SemanticResolver]:
+        """Resolvers que cobrem o pedido, em ordem de evidência."""
+        rel = relation_for_kind(request.kind)
+        return self._registry.capable(request.language, rel)
+
+    def resolve(
+        self,
+        request: ResolutionRequest,
+        *,
+        above_tier: int | None = None,
+    ) -> ResolutionResult:
+        """Resolve seguindo a cadeia de evidência; nunca levanta.
+
+        ``above_tier`` (lf-0035): quando informado, só consulta
+        resolvedores com ``tier < above_tier`` — usado para verificar
+        uma resolução existente contra evidência estritamente superior
+        (política de precedência determinística)."""
+        diagnostics: list[ResolutionDiagnostic] = []
+        best: ResolutionResult | None = None
+        for resolver in self.candidates(request):
+            if (
+                above_tier is not None
+                and resolver.capabilities().tier >= above_tier
+            ):
+                continue
+            try:
+                result = resolver.resolve(request)
+            except Exception as exc:  # resolvedor isolado → diagnóstico
+                diagnostics.append(
+                    ResolutionDiagnostic(
+                        code="resolver-error",
+                        severity="warning",
+                        message=f"{resolver.resolver_id}: {exc}",
+                        resolver_id=resolver.resolver_id,
+                    )
+                )
+                continue
+            diagnostics.extend(result.diagnostics)
+            ref = result.reference
+            if ref is not None and ref.status == "resolved":
+                return ResolutionResult(
+                    request=request,
+                    reference=ref,
+                    diagnostics=tuple(diagnostics),
+                )
+            if best is None:
+                best = result  # tier mais alto que respondeu
+        if best is not None:
+            return ResolutionResult(
+                request=request,
+                reference=best.reference,
+                definitions=best.definitions,
+                diagnostics=tuple(diagnostics),
+            )
+        return ResolutionResult(
+            request=request,
+            diagnostics=tuple(diagnostics) or (
+                ResolutionDiagnostic(
+                    code="no-resolver",
+                    severity="warning",
+                    message=f"no resolver covers '{request.kind}' "
+                            f"for '{request.language or '*'}'",
+                ),
+            ),
+        )

code_atlas/resolvers/enrichment.py

@@ -0,0 +1,318 @@
+"""Enriquecimento semântico do grafo construído (lf-0027).
+
+Camada independente entre ``GraphBuilder.build`` e ``persist_graph``:
+re-resolve arestas não-resolvidas via ``ResolverCoordinator`` (ordem de
+``EvidenceTier``: scip → lsp → …) e promove a aresta SOMENTE quando o
+resultado é ``resolved`` e o alvo existe no snapshot atual.
+
+Regras invioláveis:
+
+- Uma aresta já ``resolved`` nunca é reescrita silenciosamente — só
+  pode ser VERIFICADA por evidência de tier estritamente superior
+  (lf-0035): mesmo alvo confirma e sobe a proveniência; alvo divergente
+  vira ``ambiguous`` + diagnóstico de conflito, preservando o alvo
+  original. Evidência externa nunca sobrescreve relação válida.
+- Resultado não-``resolved`` (ambiguous/unresolved/external/diagnóstico)
+  preserva a aresta original verbatim — nenhuma degradação.
+- O ``target_id`` retornado por um resolver precisa ser nó persistível
+  DESTE build — vínculo cross-snapshot é impossível por construção.
+- Projeção documentada: a primeira evidência ``resolved`` no tier mais
+  alto vence; demais respostas ficam como diagnósticos (coexistência
+  de evidências alternativas fica registrada, não projetada).
+- Exceções de resolver viram ``ParseDiagnostic`` — nunca crash.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+
+from code_atlas.contracts.enums import NodeKind
+from code_atlas.parsers.contracts import (
+    EvidenceRecord,
+    GraphBuildResult,
+    GraphEdge,
+    ParseDiagnostic,
+)
+from code_atlas.resolvers.capabilities import EvidenceTier
+from code_atlas.resolvers.contracts import (
+    ResolutionRequest,
+    ResolutionResult,
+)
+from code_atlas.resolvers.coordinator import ResolverCoordinator
+
+# Tipos de aresta elegíveis a enriquecimento → kind do ResolutionRequest.
+_EDGE_TO_KIND = {
+    "CALLS": "call",
+    "IMPORTS": "import",
+    "EXTENDS": "type-ref",
+    "IMPLEMENTS": "type-ref",
+    "REFERENCES": "reference",
+}
+
+# Kinds cujos nós viram ocorrências persistidas (espelha _PERSISTED_KINDS
+# de indexing/persist — manter alinhado: um alvo fora deste conjunto
+# seria descartado no persist, perdendo a aresta original).
+_NON_PERSISTED = frozenset({NodeKind.REPOSITORY, NodeKind.PACKAGE})
+
+
+def _edge_tier(resolver_label: str) -> int:
+    """Tier da evidência que produziu a resolução atual (lf-0035).
+
+    Labels persistidos: ``scip`` → índice semântico, ``lsp:*`` → LSP,
+    qualquer outro (``syntactic-scope-v1``, ``tree-sitter-*``) →
+    sintático. Desconhecido = sintático (conservador, nunca superestima).
+    """
+    if resolver_label == "scip" or resolver_label.startswith("resolver:scip"):
+        return int(EvidenceTier.SEMANTIC_INDEX)
+    if resolver_label.startswith("lsp:"):
+        return int(EvidenceTier.LSP)
+    return int(EvidenceTier.SYNTACTIC)
+
+
+class SemanticEnricher:
+    """Promove arestas não-resolvidas com evidência de resolvers opt-in."""
+
+    def __init__(self, coordinator: ResolverCoordinator) -> None:
+        self._coord = coordinator
+
+    def enrich(
+        self, build: GraphBuildResult
+    ) -> tuple[GraphBuildResult, dict[str, int]]:
+        """Devolve (build possivelmente enriquecido, stats).
+
+        Stats: ``semantic_attempted``, ``semantic_enriched``,
+        ``semantic_diagnostics``.
+        """
+        node_by_id = {n.node_id: n for n in build.nodes}
+        persistable = {
+            n.node_id for n in build.nodes
+            if n.kind not in _NON_PERSISTED and n.path
+        }
+        evidence: list[EvidenceRecord] = list(build.evidence)
+        diagnostics: list[ParseDiagnostic] = list(build.diagnostics)
+        stats = {
+            "semantic_attempted": 0,
+            "semantic_enriched": 0,
+            "semantic_verified": 0,
+            "semantic_confirmed": 0,
+            "semantic_conflicts": 0,
+            "semantic_diagnostics": 0,
+        }
+        edges: list[GraphEdge] = []
+        for e in build.edges:
+            new_edge = self._enrich_edge(
+                e, node_by_id, persistable, evidence, diagnostics, stats
+            )
+            edges.append(new_edge)
+        stats["semantic_diagnostics"] = (
+            len(diagnostics) - len(build.diagnostics)
+        )
+        enriched = dataclasses.replace(
+            build,
+            edges=tuple(edges),
+            evidence=tuple(evidence),
+            diagnostics=tuple(diagnostics),
+        )
+        return enriched, stats
+
+    # -- por aresta ------------------------------------------------------
+
+    def _enrich_edge(
+        self,
+        e: GraphEdge,
+        node_by_id: Mapping[str, object],
+        persistable: set[str],
+        evidence: list[EvidenceRecord],
+        diagnostics: list[ParseDiagnostic],
+        stats: dict[str, int],
+    ) -> GraphEdge:
+        kind = _EDGE_TO_KIND.get(str(e.type))
+        if kind is None:
+            return e
+        if e.resolution_status == "resolved":
+            return self._verify_edge(
+                e, kind, node_by_id, persistable, evidence,
+                diagnostics, stats,
+            )
+        src = node_by_id.get(e.from_id)
+        language = getattr(src, "language", "") if src is not None else ""
+        request = ResolutionRequest(
+            name=e.to_text,
+            kind=kind,
+            path=e.source_path,
+            language=str(language),
+            span=e.span,
+        )
+        if not request.name:
+            return e
+        stats["semantic_attempted"] += 1
+        result = self._coord.resolve(request)
+        self._diags(result, e, diagnostics)
+        ref = result.reference
+        if (
+            ref is None
+            or ref.status != "resolved"
+            or ref.target_id is None
+            or ref.target_id not in persistable
+        ):
+            return e
+        prov = ref.provenance
+        ev_idx = len(evidence)
+        evidence.append(
+            EvidenceRecord(
+                path=e.source_path,
+                span=e.span,
+                content_hash="",
+                extractor=f"resolver:{prov.resolver_id}",
+                extractor_version=prov.resolver_version,
+                notes=(
+                    f"semantic enrichment tier={prov.evidence_tier} "
+                    f"{prov.detail}".strip()
+                ),
+                resolver_id=prov.resolver_id,
+                resolver_version=prov.resolver_version,
+                evidence_tier=prov.evidence_tier,
+                index_hash=prov.index_hash,
+                validation_status="resolved",
+            )
+        )
+        stats["semantic_enriched"] += 1
+        return dataclasses.replace(
+            e,
+            to_id=ref.target_id,
+            resolution_status="resolved",
+            confidence_class=ref.confidence_class,
+            resolver=prov.resolver_id,
+            evidence_index=(*e.evidence_index, ev_idx),
+        )
+
+    def _verify_edge(
+        self,
+        e: GraphEdge,
+        kind: str,
+        node_by_id: Mapping[str, object],
+        persistable: set[str],
+        evidence: list[EvidenceRecord],
+        diagnostics: list[ParseDiagnostic],
+        stats: dict[str, int],
+    ) -> GraphEdge:
+        """Verifica aresta ``resolved`` contra tiers superiores (lf-0035).
+
+        Determinístico:
+        - Sem resolver acima do tier atual → aresta intacta.
+        - Tier superior confirma o MESMO alvo → proveniência sobe.
+        - Tier superior diverge (alvo persistível distinto) →
+          ``ambiguous`` + evidência ``conflict`` + diagnóstico; o alvo
+          original permanece (evidência externa nunca sobrescreve)."""
+        current_tier = _edge_tier(e.resolver)
+        if current_tier <= int(EvidenceTier.SEMANTIC_INDEX):
+            return e  # nada acima do tier mais alto
+        name = e.to_text
+        if not name:
+            tgt = node_by_id.get(e.to_id) if e.to_id else None
+            name = getattr(tgt, "name", "") if tgt is not None else ""
+        if not name:
+            return e
+        src = node_by_id.get(e.from_id)
+        language = getattr(src, "language", "") if src is not None else ""
+        request = ResolutionRequest(
+            name=name, kind=kind, path=e.source_path,
+            language=str(language), span=e.span,
+        )
+        above = [
+            r for r in self._coord.candidates(request)
+            if r.capabilities().tier < current_tier
+        ]
+        if not above:
+            return e  # sem resolvedor superior configurado — custo zero
+        stats["semantic_verified"] += 1
+        result = self._coord.resolve(request, above_tier=current_tier)
+        self._diags(result, e, diagnostics)
+        ref = result.reference
+        if ref is None or ref.status != "resolved" or ref.target_id is None:
+            return e
+        prov = ref.provenance
+        if ref.target_id == e.to_id:
+            ev_idx = len(evidence)
+            evidence.append(
+                EvidenceRecord(
+                    path=e.source_path, span=e.span, content_hash="",
+                    extractor=f"resolver:{prov.resolver_id}",
+                    extractor_version=prov.resolver_version,
+                    notes=(
+                        f"semantic confirmed tier={prov.evidence_tier} "
+                        f"{prov.detail}".strip()
+                    ),
+                    resolver_id=prov.resolver_id,
+                    resolver_version=prov.resolver_version,
+                    evidence_tier=prov.evidence_tier,
+                    index_hash=prov.index_hash,
+                    validation_status="confirmed",
+                )
+            )
+            stats["semantic_confirmed"] += 1
+            return dataclasses.replace(
+                e,
+                confidence_class=ref.confidence_class,
+                resolver=prov.resolver_id,
+                evidence_index=(*e.evidence_index, ev_idx),
+            )
+        if ref.target_id not in persistable:
+            return e  # alvo alternativo não existe no snapshot — ignora
+        ev_idx = len(evidence)
+        evidence.append(
+            EvidenceRecord(
+                path=e.source_path, span=e.span, content_hash="",
+                extractor=f"resolver:{prov.resolver_id}",
+                extractor_version=prov.resolver_version,
+                notes=(
+                    f"semantic conflict tier={prov.evidence_tier}: "
+                    f"kept={e.to_id} alternative={ref.target_id} "
+                    f"{prov.detail}".strip()
+                ),
+                resolver_id=prov.resolver_id,
+                resolver_version=prov.resolver_version,
+                evidence_tier=prov.evidence_tier,
+                index_hash=prov.index_hash,
+                validation_status="conflict",
+            )
+        )
+        diagnostics.append(
+            ParseDiagnostic(
+                code="semantic-conflict",
+                severity="warning",
+                message=(
+                    f"{e.source_path}: {e.type} {e.from_id} -> {e.to_id}: "
+                    f"resolver {prov.resolver_id} aponta {ref.target_id}"
+                ),
+                span=e.span,
+            )
+        )
+        stats["semantic_conflicts"] += 1
+        return dataclasses.replace(
+            e,
+            resolution_status="ambiguous",
+            evidence_index=(*e.evidence_index, ev_idx),
+        )
+
+    @staticmethod
+    def _diags(
+        result: ResolutionResult,
+        e: GraphEdge,
+        out: list[ParseDiagnostic],
+    ) -> None:
+        """Traduz ResolutionDiagnostics do resolver para ParseDiagnostic
+        — erros avisam; infos de `no-occurrence`/`no-resolver` só entram
+        quando severity ≥ warning para não inundar o snapshot."""
+        for d in result.diagnostics:
+            if d.severity == "info":
+                continue
+            out.append(
+                ParseDiagnostic(
+                    code=f"semantic:{d.resolver_id}:{d.code}",
+                    severity=d.severity,
+                    message=d.message,
+                    span=e.span,
+                )
+            )

code_atlas/resolvers/lsp/__init__.py

@@ -0,0 +1,26 @@
+"""Adapters LSP opt-in (lf-0018).
+
+- Nenhum servidor é instalado, baixado ou spawnado automaticamente.
+- Ativação exclusivamente por configuração explícita do usuário
+  (``config.toml [resolvers.lsp.servers.<name>]``) — wiring de CLI vem
+  no lf-0022.
+- Transporte: stdio apenas (sem TCP/socket). Todo request tem timeout
+  obrigatório + ``$/cancelRequest``.
+- ``spawn.py`` é o único site de subprocess (whitelist do audit).
+"""
+
+from code_atlas.resolvers.lsp.adapter import LspResolver
+from code_atlas.resolvers.lsp.lifecycle import LspClient, LspError, make_client
+from code_atlas.resolvers.lsp.spawn import LspServerSpec, SpawnError
+from code_atlas.resolvers.lsp.transport import JsonRpcTransport, TransportError
+
+__all__ = [
+    "JsonRpcTransport",
+    "LspClient",
+    "LspError",
+    "LspResolver",
+    "LspServerSpec",
+    "SpawnError",
+    "TransportError",
+    "make_client",
+]

code_atlas/resolvers/lsp/adapter.py

@@ -0,0 +1,256 @@
+"""LspResolver — resolvedor EvidenceTier.LSP (lf-0018).
+
+Envolve um ``LspClient`` ativo. Métodos LSP só são chamados quando o
+servidor anunciou a capability no handshake — caso contrário, diagnóstico
+``capability-unsupported`` e status honesto (nunca crash).
+
+Mapeamento de alvos: ``Location{uri,range}`` → path relativo ao
+``root_uri`` → nó de módulo do ``ScopeUniverse`` (identidade no nível de
+arquivo, verificável). Precisão símbolo-a-símbolo é trabalho futuro;
+quando o uri não pertence ao snapshot → ``external``/``unresolved``.
+
+Proveniência: ``lsp:<server-name>:<version>`` — distinta de SCIP.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+from code_atlas.resolvers.capabilities import EvidenceTier, ResolverCapability
+from code_atlas.resolvers.contracts import (
+    ResolutionDiagnostic,
+    ResolutionRequest,
+    ResolutionResult,
+    ResolvedDefinition,
+    ResolvedReference,
+    ResolverProvenance,
+)
+from code_atlas.resolvers.lsp.lifecycle import LspClient, LspError
+from code_atlas.resolvers.lsp.transport import TransportError
+from code_atlas.resolvers.syntactic.resolver import ScopeUniverse
+
+RESOLVER_ID_PREFIX = "lsp"
+RESOLVER_VERSION = "1.0.0"
+
+_KIND_TO_METHOD = {
+    "definition": "textDocument/definition",
+    "call": "textDocument/references",
+    "reference": "textDocument/references",
+    "type-ref": "textDocument/definition",
+    "import": "textDocument/definition",
+}
+
+
+class LspResolver:
+    """Implementa ``SemanticResolver`` sobre um LspClient ativo."""
+
+    def __init__(self, client: LspClient, universe: ScopeUniverse) -> None:
+        self._client = client
+        self._u = universe
+
+    @property
+    def resolver_id(self) -> str:
+        return f"{RESOLVER_ID_PREFIX}:{self._client.spec.name}"
+
+    @property
+    def resolver_version(self) -> str:
+        return RESOLVER_VERSION
+
+    def capabilities(self) -> ResolverCapability:
+        return ResolverCapability(
+            resolver_id=self.resolver_id,
+            tier=EvidenceTier.LSP,
+            languages=self._client.spec.languages,
+            relation_types=frozenset(
+                {"REFERENCES", "CALLS", "IMPORTS", "EXTENDS"}),
+            needs_external_process=True,
+            detail=f"stdio lsp server {self._client.spec.name}",
+        )
+
+    def _prov(self) -> ResolverProvenance:
+        caps = self._client.capabilities
+        detail = f"{caps.server_name}:{caps.server_version}".rstrip(":")
+        return ResolverProvenance(
+            resolver_id=self.resolver_id,
+            resolver_version=RESOLVER_VERSION,
+            evidence_tier=int(EvidenceTier.LSP),
+            detail=detail,
+        )
+
+    # -- contrato ----------------------------------------------------------
+
+    def resolve(self, request: ResolutionRequest) -> ResolutionResult:
+        method = _KIND_TO_METHOD.get(request.kind)
+        if method is None:
+            return self._with_diag(request, "kind-unsupported",
+                                   f"no LSP method for {request.kind}")
+        if not self._client.available:
+            return self._with_diag(request, "server-unavailable",
+                                   "lsp server not running")
+        if not self._client.capabilities.supports(method):
+            return self._with_diag(request, "capability-unsupported",
+                                   f"server did not advertise {method}")
+
+        span = request.span
+        if span is None:
+            return self._with_diag(request, "span-required",
+                                   "LSP requests need a source span")
+        params: dict[str, Any] = {
+            "textDocument": {"uri": self._doc_uri(request.path)},
+            "position": {"line": span.start_line - 1,
+                         "character": span.start_col},
+        }
+        if method == "textDocument/references":
+            params["context"] = {"includeDeclaration": False}
+        result = self._call(request, method, params)
+        if isinstance(result, ResolutionResult):
+            return result
+        result_diags = tuple(
+            ResolutionDiagnostic(
+                code="server-diagnostic",
+                severity="info",
+                message=str(d)[:200],
+                resolver_id=self.resolver_id,
+            )
+            for d in self._client.diagnostics_for(
+                self._doc_uri(request.path))
+        )
+        mapped = self._map_result(request, self._locations(result))
+        if result_diags:
+            mapped = dataclasses.replace(
+                mapped,
+                diagnostics=result_diags + mapped.diagnostics,
+            )
+        return mapped
+
+    def _call(
+        self, request: ResolutionRequest, method: str,
+        params: dict[str, Any],
+    ) -> Any:
+        """Request com recovery único embutido (lf-0029)."""
+        try:
+            return self._client.request(method, params)
+        except (TimeoutError, LspError, TransportError) as exc:
+            return self._recover_retry(request, method, params, exc)
+
+    def _recover_retry(
+        self, request: ResolutionRequest, method: str,
+        params: dict[str, Any], exc: Exception,
+    ) -> Any:
+        """lf-0029: recovery pós-falha — UM restart + UM retry.
+        Retorna o resultado do retry ou um ResolutionResult de erro
+        tipado (fallback sintático segue valendo)."""
+        if not self._try_restart():
+            code = ("request-timeout" if isinstance(exc, TimeoutError)
+                    else "server-error")
+            return self._with_diag(
+                request, code, f"{exc}; restart failed")
+        try:
+            return self._client.request(method, params)
+        except (TimeoutError, LspError, TransportError) as exc2:
+            return self._with_diag(
+                request, "server-error", f"{exc}; after restart: {exc2}")
+
+    def _try_restart(self) -> bool:
+        """Uma tentativa de recovery — nunca lança."""
+        try:
+            self._client.restart()
+        except Exception:
+            return False
+        return True
+
+    # -- mapeamento de resultado -------------------------------------------
+
+    def _map_result(
+        self, request: ResolutionRequest, locations: list[dict[str, Any]]
+    ) -> ResolutionResult:
+        if not locations:
+            return ResolutionResult(
+                request=request,
+                reference=ResolvedReference(
+                    status="unresolved",
+                    confidence_class="syntactic",
+                    provenance=self._prov(),
+                    target_text=request.name,
+                ),
+            )
+        nids: list[str] = []
+        foreign = False
+        for loc in locations:
+            path = self._rel_path(loc.get("uri", ""))
+            if path is None:
+                foreign = True
+                continue
+            nid = self._u.by_path.get(path)
+            if nid and nid not in nids:
+                nids.append(nid)
+        if len(nids) == 1:
+            status, conf = "resolved", "resolved"
+        elif len(nids) > 1:
+            status, conf = "ambiguous", "syntactic"
+        else:
+            status = "external" if foreign else "unresolved"
+            conf = "syntactic"
+        return ResolutionResult(
+            request=request,
+            reference=ResolvedReference(
+                status=status,
+                confidence_class=conf,
+                provenance=self._prov(),
+                target_id=nids[0] if len(nids) == 1 else None,
+                target_text=request.name,
+                candidates=tuple(sorted(nids)) if len(nids) > 1 else (),
+            ),
+            definitions=tuple(
+                ResolvedDefinition(
+                    symbol=request.name,
+                    path=self._rel_path(loc.get("uri", "")) or "",
+                    provenance=self._prov(),
+                )
+                for loc in locations
+            ),
+        )
+
+    # -- helpers -----------------------------------------------------------
+
+    def _doc_uri(self, path: str) -> str:
+        root = self._client.spec.root_uri.rstrip("/")
+        return f"{root}/{path}"
+
+    def _rel_path(self, uri: str) -> str | None:
+        """file:// URI → path relativo ao root_uri; None se fora do repo."""
+        root = self._client.spec.root_uri.rstrip("/") + "/"
+        if uri.startswith(root):
+            return uri[len(root):]
+        return None
+
+    @staticmethod
+    def _locations(result: object) -> list[dict[str, Any]]:
+        """definition/references → lista de Location (obj ou lista)."""
+        if result is None:
+            return []
+        if isinstance(result, dict):  # Location único ou LocationLink
+            if "targetUri" in result:
+                return [{"uri": result["targetUri"],
+                         "range": result.get("targetSelectionRange", {})}]
+            return [result] if "uri" in result else []
+        if isinstance(result, list):
+            return [r for r in result if isinstance(r, dict)]
+        return []
+
+    def _with_diag(
+        self, request: ResolutionRequest, code: str, message: str
+    ) -> ResolutionResult:
+        return ResolutionResult(
+            request=request,
+            reference=ResolvedReference(
+                status="unresolved",
+                confidence_class="syntactic",
+                provenance=self._prov(),
+                target_text=request.name,
+            ),
+            diagnostics=(ResolutionDiagnostic(
+                code=code, severity="warning", message=message,
+                resolver_id=self.resolver_id),),
+        )