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

code_atlas/parsers/registry.py

@@ -0,0 +1,51 @@
+"""Registro de adaptadores: linguagem e extensão → adapter.
+
+Linguagens não suportadas retornam ``None`` — nunca exceção. O registry
+padrão cobre Python, TypeScript e TSX (Cycle 2); novos adaptadores se
+registram sem tocar no registry (Open/Closed).
+"""
+
+from __future__ import annotations
+
+from code_atlas.parsers.contracts import ParserAdapter
+
+
+class ParserRegistry:
+    """Mapa imutável-por-convenção de adaptadores disponíveis."""
+
+    def __init__(self) -> None:
+        self._by_language: dict[str, ParserAdapter] = {}
+        self._by_ext: dict[str, ParserAdapter] = {}
+
+    def register(self, adapter: ParserAdapter) -> None:
+        self._by_language[adapter.language] = adapter
+        for ext in adapter.extensions:
+            self._by_ext[ext.lower()] = adapter
+
+    def for_language(self, language: str) -> ParserAdapter | None:
+        return self._by_language.get(language)
+
+    def for_path(self, rel_path: str) -> ParserAdapter | None:
+        """Adapter pela extensão do caminho (``.tsx`` antes de ``.ts``)."""
+        lower = rel_path.lower()
+        # extensões multi-part primeiro (.d.ts)
+        for ext in sorted(self._by_ext, key=len, reverse=True):
+            if lower.endswith(ext):
+                return self._by_ext[ext]
+        return None
+
+    @property
+    def languages(self) -> tuple[str, ...]:
+        return tuple(sorted(self._by_language))
+
+    @classmethod
+    def default(cls) -> ParserRegistry:
+        """Registry completo do Cycle 2: python, typescript, tsx."""
+        from code_atlas.parsers.languages.python import PythonAdapter
+        from code_atlas.parsers.languages.tsx import TsxAdapter
+        from code_atlas.parsers.languages.typescript import TypeScriptAdapter
+
+        reg = cls()
+        for adapter in (PythonAdapter(), TypeScriptAdapter(), TsxAdapter()):
+            reg.register(adapter)
+        return reg

code_atlas/parsers/tree_sitter_runtime.py

@@ -0,0 +1,118 @@
+"""Ponto único de contato com o runtime Tree-sitter.
+
+Somente módulos sob ``code_atlas.parsers`` podem importar ``tree_sitter``
+— a fronteira é verificada por teste de arquitetura. Aqui ficam: carga de
+gramáticas, criação de parsers com timeout, coleta de nós problema e
+versões declaradas via ``importlib.metadata``.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import threading
+import warnings
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+
+import tree_sitter
+from tree_sitter import Language, Node, Parser
+
+from code_atlas.parsers.contracts import SourceSpan
+
+
+@dataclass(frozen=True)
+class LanguageSpec:
+    """Gramática carregada + versões declaradas."""
+
+    language: Language
+    grammar_dist: str  # nome do pacote PyPI da gramática
+
+    @property
+    def grammar_version(self) -> str:
+        return _pkg_version(self.grammar_dist)
+
+
+_version_cache: dict[str, str] = {}
+_version_lock = threading.Lock()
+
+
+def _pkg_version(dist: str) -> str:
+    """Versão do pacote — memoizada com lock (thread-safe).
+
+    ``importlib.metadata.version`` não é segura no primeiro acesso
+    concorrente (leitura de METADATA sob threads → OSError); versões
+    de pacote são estáveis por processo, então o cache é correto.
+    """
+    cached = _version_cache.get(dist)
+    if cached is None:
+        with _version_lock:
+            cached = _version_cache.get(dist)
+            if cached is None:
+                try:
+                    cached = importlib.metadata.version(dist)
+                except importlib.metadata.PackageNotFoundError:
+                    cached = "unknown"
+                _version_cache[dist] = cached
+    return cached
+
+
+def parser_version() -> str:
+    """Versão do pacote ``tree-sitter`` instalado."""
+    return _pkg_version("tree-sitter")
+
+
+def load_language(factory: Callable[[], object], grammar_dist: str) -> LanguageSpec:
+    """Carrega uma gramática pelo capsule provider do pacote."""
+    return LanguageSpec(language=Language(factory()), grammar_dist=grammar_dist)
+
+
+def parse_bytes(
+    spec: LanguageSpec, content: bytes, timeout_us: int
+) -> tree_sitter.Tree | None:
+    """Parse real com deadline; None quando o timeout expira.
+
+    ``timeout_micros`` é usado apesar de deprecado em 0.25: o caminho
+    alternativo (callback read + ``progress_callback``) sofre segfault no
+    binding 0.25.2 — registrado como dívida técnica para revisão quando
+    a versão do binding subir. Nunca executa o código alvo.
+    """
+    parser = Parser(spec.language)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        # stub declara read-only; a API real aceita a atribuição (0.25.x)
+        parser.timeout_micros = timeout_us  # type: ignore[misc]
+    return parser.parse(content)
+
+
+def span_of(node: Node) -> SourceSpan:
+    """Converte Node do Tree-sitter para SourceSpan (linha 1-based)."""
+    return SourceSpan(
+        start_byte=node.start_byte,
+        end_byte=node.end_byte,
+        start_line=node.start_point.row + 1,
+        start_col=node.start_point.column,
+        end_line=node.end_point.row + 1,
+        end_col=node.end_point.column,
+    )
+
+
+def iter_problem_nodes(root: Node, limit: int = 50) -> Iterator[tuple[Node, bool]]:
+    """Percorre a árvore coletando (nó, is_missing) de ERROR/MISSING.
+
+    Bounded por ``limit`` para não produzir diagnósticos gigantescos.
+    """
+    count = 0
+    stack = [root]
+    while stack and count < limit:
+        node = stack.pop()
+        if node.is_error or node.is_missing:
+            yield node, node.is_missing
+            count += 1
+        # filhos ao final da pilha preservam ordem de visitação aproximada
+        stack.extend(reversed(node.children))
+    return
+
+
+def node_count(root: Node) -> int:
+    """Total de nós da árvore (métrica de diagnóstico)."""
+    return root.descendant_count + 1

code_atlas/resolvers/__init__.py

@@ -0,0 +1,33 @@
+"""Subsistema de resolução semântica (Cycle 3 Phase 1).
+
+Independente de parsers, storage e CLI: cada ``SemanticResolver`` declara
+capabilities e proveniência; o ``ResolverCoordinator`` encadeia por ordem
+de evidência (índice semântico > LSP > sintático > heurístico).
+"""
+
+from code_atlas.resolvers.capabilities import EvidenceTier, ResolverCapability
+from code_atlas.resolvers.contracts import (
+    ResolutionDiagnostic,
+    ResolutionRequest,
+    ResolutionResult,
+    ResolvedDefinition,
+    ResolvedReference,
+    ResolverProvenance,
+    SemanticResolver,
+)
+from code_atlas.resolvers.coordinator import ResolverCoordinator
+from code_atlas.resolvers.registry import ResolverRegistry
+
+__all__ = [
+    "EvidenceTier",
+    "ResolutionDiagnostic",
+    "ResolutionRequest",
+    "ResolutionResult",
+    "ResolvedDefinition",
+    "ResolvedReference",
+    "ResolverCapability",
+    "ResolverCoordinator",
+    "ResolverProvenance",
+    "ResolverRegistry",
+    "SemanticResolver",
+]

code_atlas/resolvers/bootstrap.py

@@ -0,0 +1,246 @@
+"""Bootstrap de resolvers opt-in a partir de ``config.toml`` (lf-0027).
+
+Tabela suportada (tudo opcional; ausente = nenhum resolver externo):
+
+.. code-block:: toml
+
+    [resolvers.scip]
+    index_path = "index.scip"          # relativo ao workspace ou absoluto
+    max_bytes = 67108864               # override opcional
+    allow_revision_mismatch = false    # opt-in explícito
+
+    [resolvers.lsp.servers.pyright]
+    command = ["pyright-langserver", "--stdio"]
+    languages = ["python"]
+    enabled = true
+    request_timeout_s = 10.0
+
+O bootstrap NUNCA executa nada do repositório indexado e NUNCA baixa
+indexers/servers — ``command`` vem exclusivamente da config do usuário.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from code_atlas.resolvers.contracts import SemanticResolver
+from code_atlas.resolvers.lsp.adapter import LspResolver
+from code_atlas.resolvers.lsp.lifecycle import make_client
+from code_atlas.resolvers.lsp.spawn import LspServerSpec
+from code_atlas.resolvers.scip.loader import load_index
+from code_atlas.resolvers.scip.provenance import assess_revision
+from code_atlas.resolvers.scip.resolver import ScipResolver
+from code_atlas.resolvers.syntactic.resolver import ScopeUniverse
+
+ResolverFactory = Callable[[ScopeUniverse], SemanticResolver]
+
+
+def resolver_factories(
+    table: Mapping[str, object] | None,
+    workspace_root: Path,
+    versions_out: dict[str, str] | None = None,
+) -> tuple[list[ResolverFactory], list[str]]:
+    """Traduz a tabela ``[resolvers]`` em fábricas + erros tipados.
+
+    Cada fábrica recebe o ``ScopeUniverse`` do build atual e devolve o
+    resolver concreto; falha dentro da fábrica vira diagnóstico no
+    enriquecimento (nunca crash).
+    """
+    factories: list[ResolverFactory] = []
+    errors: list[str] = []
+    if not table:
+        return factories, errors
+    scip = table.get("scip")
+    if isinstance(scip, Mapping):
+        _scip_factory(scip, workspace_root, factories, errors,
+                      versions_out)
+    lsp = table.get("lsp")
+    if isinstance(lsp, Mapping):
+        _lsp_factories(lsp, workspace_root, factories, errors)
+    return factories, errors
+
+
+def describe_resolvers(
+    table: Mapping[str, object] | None,
+    workspace_root: Path,
+) -> tuple[list[dict[str, object]], list[str]]:
+    """lf-0032: relatório installed/enabled por resolver — read-only.
+
+    ``installed`` = artefato presente (índice SCIP carrega; binário
+    LSP existe no PATH). ``enabled`` = produziria resolver ativo
+    (assessment não-rejected para SCIP; ``enabled=true`` para LSP).
+    Nenhum server LSP é spawnado aqui — ``shutil.which`` apenas.
+    """
+    import shutil
+
+    reports: list[dict[str, object]] = [
+        {
+            "id": "syntactic-scope-v1", "kind": "builtin",
+            "installed": True, "enabled": True,
+            "detail": "tree-sitter + scope analysis",
+        }
+    ]
+    errors: list[str] = []
+    scip = table.get("scip") if isinstance(table, Mapping) else None
+    if isinstance(scip, Mapping):
+        _describe_scip(scip, workspace_root, reports, errors)
+    lsp = table.get("lsp") if isinstance(table, Mapping) else None
+    if isinstance(lsp, Mapping):
+        servers = lsp.get("servers")
+        if isinstance(servers, Mapping):
+            for name, spec in sorted(servers.items()):
+                if not isinstance(spec, Mapping):
+                    errors.append(
+                        f"resolvers.lsp.servers.{name}: spec inválido")
+                    continue
+                cmd = spec.get("command")
+                binary = cmd[0] if isinstance(cmd, (list, tuple)) and cmd else None
+                reports.append({
+                    "id": f"lsp:{name}", "kind": "lsp",
+                    "command": " ".join(str(c) for c in cmd) if cmd else "",
+                    "installed": bool(
+                        binary and shutil.which(str(binary))),
+                    "enabled": bool(spec.get("enabled", False)),
+                })
+    return reports, errors
+
+
+def _describe_scip(
+    scip: Mapping[str, object],
+    root: Path,
+    reports: list[dict[str, object]],
+    errors: list[str],
+) -> None:
+    index_path = scip.get("index_path")
+    if not index_path or not isinstance(index_path, str):
+        errors.append("resolvers.scip: index_path ausente ou inválido")
+        return
+    path = Path(index_path)
+    if not path.is_absolute():
+        path = root / path
+    kwargs: dict[str, object] = {
+        "workspace_root": root,
+        "allow_revision_mismatch": bool(
+            scip.get("allow_revision_mismatch", False)),
+    }
+    max_bytes = scip.get("max_bytes")
+    if isinstance(max_bytes, int):
+        kwargs["max_bytes"] = max_bytes
+    load = load_index(path, **kwargs)  # type: ignore[arg-type]
+    installed = load.ok and load.index is not None
+    rev_status = "not-assessed"
+    enabled = False
+    if installed and load.index is not None:
+        a = assess_revision(load.index, path, root)
+        rev_status = a.provenance.validation_status
+        enabled = not a.errors
+        if a.provenance.validation_status == "degraded":
+            errors.append(
+                f"scip index {path}: degraded — "
+                f"{'; '.join(a.provenance.validation_evidence[:3])}")
+    else:
+        errors.append(
+            f"scip index {path}: "
+            f"{'; '.join(load.errors) or 'load failed'}")
+    reports.append({
+        "id": "scip", "kind": "scip",
+        "index_path": str(path),
+        "installed": installed, "enabled": enabled,
+        "revision_status": rev_status,
+    })
+
+
+def _scip_factory(
+    scip: Mapping[str, object],
+    root: Path,
+    factories: list[ResolverFactory],
+    errors: list[str],
+    versions_out: dict[str, str] | None = None,
+) -> None:
+    index_path = scip.get("index_path")
+    if not index_path or not isinstance(index_path, str):
+        errors.append("resolvers.scip: index_path ausente ou inválido")
+        return
+    path = Path(index_path)
+    if not path.is_absolute():
+        path = root / path
+    allow_mismatch = bool(scip.get("allow_revision_mismatch", False))
+    max_bytes = scip.get("max_bytes")
+    kwargs: dict[str, object] = {
+        "workspace_root": root,
+        "allow_revision_mismatch": allow_mismatch,
+    }
+    if isinstance(max_bytes, int):
+        kwargs["max_bytes"] = max_bytes
+    out = load_index(path, **kwargs)  # type: ignore[arg-type]
+    if not out.ok or out.index is None:
+        errors.append(
+            f"scip index {path}: {'; '.join(out.errors) or 'load failed'}"
+        )
+        return
+    index = out.index
+    # Revision safety (lf-0028): índice válido ≠ índice compatível.
+    # Rejected → erro e nenhuma factory; degraded → resolver marcado,
+    # nunca promove como comprovado.
+    assessment = assess_revision(index, path, root)
+    prov = assessment.provenance
+    if assessment.errors:
+        errors.append(
+            f"scip index {path}: {'; '.join(assessment.errors)}"
+        )
+        return
+    if prov.validation_status == "degraded":
+        errors.append(
+            f"scip index {path}: degraded — "
+            f"{'; '.join(prov.validation_evidence[:3])}"
+        )
+    if versions_out is not None:
+        # sha256 do índice na identidade do index — índice SCIP novo
+        # invalida relações (lf-0030 phase 6).
+        versions_out["resolver:scip"] = prov.index_sha256[:16]
+    factories.append(
+        lambda universe: ScipResolver(index, universe, prov)
+    )
+
+
+def _lsp_factories(
+    lsp: Mapping[str, object],
+    root: Path,
+    factories: list[ResolverFactory],
+    errors: list[str],
+) -> None:
+    servers = lsp.get("servers")
+    if not isinstance(servers, Mapping):
+        return
+    for name, spec in servers.items():
+        if not isinstance(spec, Mapping):
+            errors.append(f"resolvers.lsp.servers.{name}: spec inválido")
+            continue
+        cmd = spec.get("command")
+        if not isinstance(cmd, (list, tuple)) or not cmd:
+            errors.append(
+                f"resolvers.lsp.servers.{name}: command ausente/inválido"
+            )
+            continue
+        languages = spec.get("languages", ())
+        server = LspServerSpec(
+            name=str(name),
+            cmd=tuple(str(c) for c in cmd),
+            languages=frozenset(str(lang) for lang in languages)
+            if isinstance(languages, (list, tuple))
+            else frozenset(),
+            root_uri=root.as_uri(),
+            enabled=bool(spec.get("enabled", False)),
+            request_timeout_s=float(spec.get("request_timeout_s", 10.0)),
+        )
+        if not server.enabled:
+            continue
+        def _factory(universe: ScopeUniverse,
+                     _server: LspServerSpec = server) -> SemanticResolver:
+            client = make_client(_server)
+            if client is None:
+                raise RuntimeError(f"lsp {_server.name}: disabled")
+            return LspResolver(client, universe)
+
+        factories.append(_factory)

code_atlas/resolvers/capabilities.py

@@ -0,0 +1,33 @@
+"""Capabilities e tiers de evidência do subsistema de resolução."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class EvidenceTier(enum.IntEnum):
+    """Ordem de precedência de evidência (prompt Cycle 3 Phase 1)."""
+
+    SEMANTIC_INDEX = 1   # SCIP e afins — índice externo confiável
+    LSP = 2              # servidor de linguagem confirmado
+    SYNTACTIC = 3        # resolução sintática inequívoca
+    HEURISTIC = 4        # candidato heurístico
+
+
+@dataclass(frozen=True)
+class ResolverCapability:
+    """Declaração do que um resolvedor cobre."""
+
+    resolver_id: str
+    tier: EvidenceTier
+    languages: frozenset[str]           # vazio = qualquer linguagem
+    relation_types: frozenset[str]      # IMPORTS/CALLS/REFERENCES/...
+    needs_external_process: bool = False
+    needs_network: bool = False
+    detail: str = ""
+
+    def covers(self, language: str, relation_type: str) -> bool:
+        lang_ok = not self.languages or language in self.languages
+        rel_ok = not self.relation_types or relation_type in self.relation_types
+        return lang_ok and rel_ok

code_atlas/resolvers/contracts.py

@@ -0,0 +1,133 @@
+"""Contratos versionados do subsistema de resolução (lf-0016).
+
+Ordem conceitual de evidência (prompt Cycle 3 §Phase 1):
+
+1. Índice semântico confiável, consistente com a revisão (SCIP).
+2. LSP com definição/referência confirmada.
+3. Resolução sintática inequívoca.
+4. Candidato heurístico.
+5. Alvo ambíguo ou não resolvido.
+
+``confidence_class`` e ``resolution_status`` permanecem conceitos
+distintos: o primeiro descreve a força da evidência do resolvedor, o
+segundo o desfecho da tentativa (resolved/ambiguous/unresolved/external).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from code_atlas.parsers.contracts import SourceSpan
+from code_atlas.resolvers.capabilities import ResolverCapability
+
+RESOLUTION_SCHEMA_VERSION = 1
+
+# Buckets de kind aceitos pelo contrato — adapters SCIP/LSP/syntactic
+# mapeiam seus pedidos para este vocabulário.
+REQUEST_KINDS = frozenset(
+    {"call", "import", "type-ref", "reference", "definition"}
+)
+
+# kind do request → tipo de relação das capabilities (Registry filtra
+# resolvers por este vocabulário de grafo).
+KIND_TO_RELATION: dict[str, str] = {
+    "call": "CALLS",
+    "import": "IMPORTS",
+    "type-ref": "REFERENCES",
+    "reference": "REFERENCES",
+    "definition": "REFERENCES",
+}
+
+
+def relation_for_kind(kind: str) -> str:
+    """Mapeia kind de request → relation type; desconhecido → o próprio
+    kind em maiúsculas (resolvers podem declarar tipos extras)."""
+    return KIND_TO_RELATION.get(kind, kind.upper())
+
+
+@dataclass(frozen=True)
+class ResolverProvenance:
+    """Origem verificável de um resultado de resolução."""
+
+    resolver_id: str          # ex.: "syntactic", "scip", "lsp:pyright"
+    resolver_version: str     # versão do resolvedor (semver interno)
+    evidence_tier: int        # EvidenceTier — 1=semantic-index…4=heuristic
+    detail: str = ""          # indexer/server de origem, grammar, etc.
+    index_hash: str = ""      # sha256 do índice externo (lf-0035), se houver
+
+
+@dataclass(frozen=True)
+class ResolutionRequest:
+    """Pedido de resolução de um símbolo/referência textual."""
+
+    name: str                  # texto a resolver (callee, nome, import)
+    kind: str                  # call | import | type-ref | reference | definition
+    path: str                  # arquivo de origem (relativo ao repo)
+    language: str = ""
+    span: SourceSpan | None = None
+    module: str = ""           # qname do módulo de origem, se conhecido
+
+
+@dataclass(frozen=True)
+class ResolvedReference:
+    """Resultado de uma resolução de referência/call/import."""
+
+    status: str                       # resolved|ambiguous|unresolved|external
+    confidence_class: str             # resolved|syntactic|heuristic|inferred
+    provenance: ResolverProvenance
+    target_id: str | None = None      # node_id interno quando resolvido
+    target_text: str = ""             # texto preservado do alvo
+    candidates: tuple[str, ...] = ()  # alvos concorrentes quando ambiguous
+
+
+@dataclass(frozen=True)
+class ResolvedDefinition:
+    """Definição localizada de um símbolo (definition site)."""
+
+    symbol: str
+    path: str
+    provenance: ResolverProvenance
+    span: SourceSpan | None = None
+    kind: str = ""
+
+
+@dataclass(frozen=True)
+class ResolutionDiagnostic:
+    """Diagnóstico de um resolvedor (falha, timeout, rejeição)."""
+
+    code: str
+    severity: str  # info | warning | error
+    message: str
+    resolver_id: str = ""
+
+
+@dataclass(frozen=True)
+class ResolutionResult:
+    """Envelope versionado do resultado de ``SemanticResolver.resolve``."""
+
+    request: ResolutionRequest
+    schema_version: int = RESOLUTION_SCHEMA_VERSION
+    reference: ResolvedReference | None = None
+    definitions: tuple[ResolvedDefinition, ...] = ()
+    diagnostics: tuple[ResolutionDiagnostic, ...] = field(default_factory=tuple)
+
+
+@runtime_checkable
+class SemanticResolver(Protocol):
+    """Interface implementada por qualquer fonte de resolução."""
+
+    @property
+    def resolver_id(self) -> str: ...
+
+    @property
+    def resolver_version(self) -> str: ...
+
+    def capabilities(self) -> ResolverCapability:
+        """O que este resolvedor cobre (linguagens, relações, tier)."""
+        ...
+
+    def resolve(self, request: ResolutionRequest) -> ResolutionResult:
+        """Tenta resolver o pedido; nunca levanta — falhas viram
+        ``ResolutionDiagnostic`` no resultado."""
+        ...