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

code_atlas/resolvers/scip/decoder.py

@@ -0,0 +1,216 @@
+"""Decoder protobuf wire-format mínimo para índices SCIP (lf-0017).
+
+Decisão (grill): decoder stdlib próprio — zero dependências. Implementa o
+wire format completo do Protocol Buffers: varints (incl. >32 bits),
+zigzag, fixed32/64, campos length-delimited, packed repeated varints e
+skip de campos desconhecidos. Erros carregam o field-path para diagnóstico.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Any
+
+WIRE_VARINT = 0
+WIRE_FIXED64 = 1
+WIRE_LEN = 2
+WIRE_SGROUP = 3   # deprecated — rejeitado explicitamente
+WIRE_EGROUP = 4
+WIRE_FIXED32 = 5
+
+
+class DecodeError(ValueError):
+    """Bytes malformados/truncados — sempre com field-path."""
+
+
+def _zigzag(v: int) -> int:
+    return (v >> 1) ^ -(v & 1)
+
+
+class Reader:
+    """Cursor de leitura sobre um buffer protobuf."""
+
+    __slots__ = ("_buf", "_end", "_path", "_pos")
+
+    def __init__(self, buf: bytes, path: str = "") -> None:
+        self._buf = buf
+        self._pos = 0
+        self._end = len(buf)
+        self._path = path
+
+    def eof(self) -> bool:
+        return self._pos >= self._end
+
+    def _err(self, msg: str) -> DecodeError:
+        return DecodeError(f"{self._path or '<root>'}: {msg}")
+
+    def varint(self) -> int:
+        """LEB128 — até 10 bytes; truncamento/overflow → erro."""
+        result = 0
+        shift = 0
+        for _ in range(10):
+            if self._pos >= self._end:
+                raise self._err("truncated varint")
+            b = self._buf[self._pos]
+            self._pos += 1
+            result |= (b & 0x7F) << shift
+            if not (b & 0x80):
+                return result
+            shift += 7
+        raise self._err("varint overflow (>10 bytes)")
+
+    def tag(self) -> tuple[int, int]:
+        """(field_number, wire_type); field 0 e tipos inválidos → erro."""
+        v = self.varint()
+        field_no, wire = v >> 3, v & 0x7
+        if field_no == 0:
+            raise self._err("field number 0")
+        if wire in (WIRE_SGROUP, WIRE_EGROUP):
+            raise self._err(f"deprecated group wire type {wire}")
+        if wire > WIRE_FIXED32:
+            raise self._err(f"invalid wire type {wire}")
+        return field_no, wire
+
+    def _take(self, n: int) -> bytes:
+        if n < 0 or self._pos + n > self._end:
+            raise self._err(f"truncated field (need {n} bytes)")
+        out = self._buf[self._pos : self._pos + n]
+        self._pos += n
+        return out
+
+    def fixed32(self) -> int:
+        v: int = struct.unpack("<I", self._take(4))[0]
+        return v
+
+    def fixed64(self) -> int:
+        v: int = struct.unpack("<Q", self._take(8))[0]
+        return v
+
+    def sfixed32(self) -> int:
+        v: int = struct.unpack("<i", self._take(4))[0]
+        return v
+
+    def sfixed64(self) -> int:
+        v: int = struct.unpack("<q", self._take(8))[0]
+        return v
+
+    def sint(self) -> int:
+        return _zigzag(self.varint())
+
+    def int32(self) -> int:
+        v = self.varint()
+        # int32 negativos viajam como varint de 10 bytes (complemento 64)
+        if v >= 1 << 63:
+            v -= 1 << 64
+        elif v >= 1 << 31:
+            v -= 1 << 32
+        return v
+
+    def bool_(self) -> bool:
+        return self.varint() != 0
+
+    def double(self) -> float:
+        v: float = struct.unpack("<d", self._take(8))[0]
+        return v
+
+    def float_(self) -> float:
+        v: float = struct.unpack("<f", self._take(4))[0]
+        return v
+
+    def bytes_(self) -> bytes:
+        return self._take(self.varint())
+
+    def string(self) -> str:
+        try:
+            return self.bytes_().decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise self._err(f"invalid utf-8 string: {exc}") from exc
+
+    def packed_int32(self) -> list[int]:
+        """Campo repeated int32 packed (wire LEN)."""
+        data = self.bytes_()
+        sub = Reader(data, path=f"{self._path}<packed>")
+        out: list[int] = []
+        while not sub.eof():
+            out.append(sub.int32())
+        return out
+
+    def packed_enum(self) -> list[int]:
+        data = self.bytes_()
+        sub = Reader(data, path=f"{self._path}<packed>")
+        out: list[int] = []
+        while not sub.eof():
+            out.append(sub.varint())
+        return out
+
+    def sub(self, path: str) -> Reader:
+        """Sub-reader para um campo length-delimited (mensagem)."""
+        return Reader(self.bytes_(), path=path)
+
+    def skip(self, wire: int) -> None:
+        """Consome um campo de tipo desconhecido."""
+        if wire == WIRE_VARINT:
+            self.varint()
+        elif wire == WIRE_FIXED64:
+            self._take(8)
+        elif wire == WIRE_LEN:
+            self._take(self.varint())
+        elif wire == WIRE_FIXED32:
+            self._take(4)
+        else:  # pragma: no cover — tag() já rejeita
+            raise self._err(f"cannot skip wire type {wire}")
+
+
+def decode_message(buf: bytes, spec: dict[int, tuple[str, Any]],
+                   path: str = "") -> dict[str, Any]:
+    """Decodifica uma mensagem conforme `spec` {field_no: (name, kind)}.
+
+    `kind` é um string-dispatch: "varint","int32","sint","bool","fixed32",
+    "fixed64","sfixed32","sfixed64","double","float","bytes","string",
+    "packed_int32","packed_enum", uma tupla (spec, "message") para
+    mensagem aninhada, ou ("repeated", inner_kind) para campos repetidos.
+    Campos não mapeados são skipados preservando o wire type.
+    """
+    r = Reader(buf, path=path)
+    out: dict[str, Any] = {}
+    while not r.eof():
+        field_no, wire = r.tag()
+        entry = spec.get(field_no)
+        if entry is None:
+            r.skip(wire)
+            continue
+        name, kind = entry
+        val = _read_field(r, kind, wire, f"{path}.{name}" if path else name)
+        if _is_repeated(kind):
+            out.setdefault(name, []).extend(val)
+        else:
+            out[name] = val
+    return out
+
+
+def _is_repeated(kind: Any) -> bool:
+    return isinstance(kind, tuple) and bool(kind) and kind[0] == "repeated"
+
+
+def _read_field(r: Reader, kind: Any, wire: int, path: str) -> Any:
+    if isinstance(kind, tuple) and kind and kind[0] == "repeated":
+        inner = kind[1]
+        # packed só para escalares varint — len-delimited acumula valores
+        if wire == WIRE_LEN and inner in ("int32", "packed_int32"):
+            return r.packed_int32()
+        return [_read_field(r, inner, wire, path)]
+    if isinstance(kind, tuple) and len(kind) == 2 and kind[1] == "message":
+        return decode_message(r.bytes_(), kind[0], path=path)
+
+    readers: dict[str, Any] = {
+        "varint": r.varint, "int32": r.int32, "sint": r.sint,
+        "bool": r.bool_, "fixed32": r.fixed32, "fixed64": r.fixed64,
+        "sfixed32": r.sfixed32, "sfixed64": r.sfixed64,
+        "double": r.double, "float": r.float_, "bytes": r.bytes_,
+        "string": r.string,
+        "packed_int32": r.packed_int32, "packed_enum": r.packed_enum,
+    }
+    fn = readers.get(kind)
+    if fn is None:
+        raise DecodeError(f"{path}: unknown field kind {kind!r}")
+    return fn()

code_atlas/resolvers/scip/importer.py

@@ -0,0 +1,248 @@
+"""Importador de índices SCIP — bytes protobuf → modelo tipado (lf-0017).
+
+Cobertura do schema (scip.proto oficial):
+- Index{metadata, documents, external_symbols}
+- Metadata{version, tool_info, project_root, text_document_encoding}
+- Document{language, relative_path, occurrences, symbols, position_encoding}
+- Occurrence{range(deprec.), single_line_range, multi_line_range, symbol,
+  symbol_roles, override_documentation}
+- SymbolInformation{symbol, documentation, relationships, kind}
+- Relationship{symbol, is_reference, is_implementation, is_type_definition,
+  is_definition}
+Campos não listados são skipados preservando wire type (forward-compat).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from code_atlas.resolvers.scip.decoder import DecodeError, decode_message
+
+SpecMap = dict[int, tuple[str, Any]]
+
+ROLE_DEFINITION = 0x1
+ROLE_IMPORT = 0x2
+ROLE_WRITE_ACCESS = 0x4
+ROLE_READ_ACCESS = 0x8
+ROLE_GENERATED = 0x10
+ROLE_TEST = 0x20
+ROLE_FORWARD = 0x1000000
+
+TOOL_INFO_SPEC: SpecMap = {
+    1: ("name", "string"),
+    2: ("version", "string"),
+    3: ("arguments", ("repeated", "string")),
+}
+METADATA_SPEC: SpecMap = {
+    1: ("version", "varint"),
+    2: ("tool_info", (TOOL_INFO_SPEC, "message")),
+    3: ("project_root", "string"),
+    4: ("text_document_encoding", "varint"),
+}
+SLR_SPEC: SpecMap = {
+    1: ("line", "int32"),
+    2: ("start_character", "int32"),
+    3: ("end_character", "int32"),
+}
+MLR_SPEC: SpecMap = {
+    1: ("start_line", "int32"),
+    2: ("start_character", "int32"),
+    3: ("end_line", "int32"),
+    4: ("end_character", "int32"),
+}
+OCCURRENCE_SPEC: SpecMap = {
+    1: ("range", ("repeated", "int32")),
+    2: ("symbol", "string"),
+    3: ("symbol_roles", "int32"),
+    4: ("override_documentation", ("repeated", "string")),
+    5: ("syntax_kind", "varint"),
+    6: ("diagnostics", ("repeated", ("repeated", "string"))),  # skip-ish
+    7: ("enclosing_range", ("repeated", "int32")),
+    8: ("single_line_range", (SLR_SPEC, "message")),
+    9: ("multi_line_range", (MLR_SPEC, "message")),
+}
+RELATIONSHIP_SPEC: SpecMap = {
+    1: ("symbol", "string"),
+    2: ("is_reference", "bool"),
+    3: ("is_implementation", "bool"),
+    4: ("is_type_definition", "bool"),
+    5: ("is_definition", "bool"),
+}
+SYMBOL_INFO_SPEC: SpecMap = {
+    1: ("symbol", "string"),
+    3: ("documentation", ("repeated", "string")),
+    4: ("relationships", ("repeated", (RELATIONSHIP_SPEC, "message"))),
+    5: ("kind", "varint"),
+    6: ("display_name", "string"),
+    7: ("signature_documentation", ("repeated", "string")),
+    9: ("enclosing_symbol", "string"),
+}
+DOCUMENT_SPEC: SpecMap = {
+    1: ("relative_path", "string"),
+    2: ("occurrences", ("repeated", (OCCURRENCE_SPEC, "message"))),
+    3: ("symbols", ("repeated", (SYMBOL_INFO_SPEC, "message"))),
+    4: ("language", "string"),
+    5: ("text", "string"),
+    6: ("position_encoding", "varint"),
+}
+INDEX_SPEC: SpecMap = {
+    1: ("metadata", (METADATA_SPEC, "message")),
+    2: ("documents", ("repeated", (DOCUMENT_SPEC, "message"))),
+    3: ("external_symbols", ("repeated", (SYMBOL_INFO_SPEC, "message"))),
+}
+
+
+@dataclass(frozen=True)
+class ScipRange:
+    """Range normalizado (sempre multilinha: start/end line+char)."""
+
+    start_line: int
+    start_char: int
+    end_line: int
+    end_char: int
+
+
+@dataclass(frozen=True)
+class ScipOccurrence:
+    symbol: str
+    roles: int
+    range: ScipRange | None
+
+    @property
+    def is_definition(self) -> bool:
+        return bool(self.roles & ROLE_DEFINITION)
+
+
+@dataclass(frozen=True)
+class ScipRelationship:
+    symbol: str
+    is_reference: bool = False
+    is_implementation: bool = False
+    is_type_definition: bool = False
+    is_definition: bool = False
+
+
+@dataclass(frozen=True)
+class ScipSymbolInfo:
+    symbol: str
+    kind: int = 0
+    documentation: tuple[str, ...] = ()
+    relationships: tuple[ScipRelationship, ...] = ()
+    enclosing_symbol: str = ""
+
+
+@dataclass(frozen=True)
+class ScipDocument:
+    relative_path: str
+    language: str
+    occurrences: tuple[ScipOccurrence, ...] = ()
+    symbols: tuple[ScipSymbolInfo, ...] = ()
+    position_encoding: int = 0
+
+
+@dataclass(frozen=True)
+class ScipIndex:
+    """Índice SCIP decodificado — modelo interno do Atlas."""
+
+    project_root: str = ""
+    tool_name: str = ""
+    tool_version: str = ""
+    text_document_encoding: int = 0
+    documents: tuple[ScipDocument, ...] = ()
+    external_symbols: tuple[ScipSymbolInfo, ...] = ()
+    raw_metadata: dict[str, Any] = field(default_factory=dict)
+
+
+def _to_range(msg: dict[str, Any]) -> ScipRange | None:
+    slr = msg.get("single_line_range")
+    if slr is not None:
+        return ScipRange(
+            start_line=slr.get("line", 0),
+            start_char=slr.get("start_character", 0),
+            end_line=slr.get("line", 0),
+            end_char=slr.get("end_character", 0),
+        )
+    mlr = msg.get("multi_line_range")
+    if mlr is not None:
+        return ScipRange(
+            start_line=mlr.get("start_line", 0),
+            start_char=mlr.get("start_character", 0),
+            end_line=mlr.get("end_line", 0),
+            end_char=mlr.get("end_character", 0),
+        )
+    rng = msg.get("range") or []
+    if len(rng) >= 4:
+        return ScipRange(rng[0], rng[1], rng[2], rng[3])
+    if len(rng) == 3:
+        return ScipRange(rng[0], rng[1], rng[0], rng[2])
+    return None
+
+
+def _to_relationship(msg: dict[str, Any]) -> ScipRelationship:
+    return ScipRelationship(
+        symbol=msg.get("symbol", ""),
+        is_reference=bool(msg.get("is_reference", False)),
+        is_implementation=bool(msg.get("is_implementation", False)),
+        is_type_definition=bool(msg.get("is_type_definition", False)),
+        is_definition=bool(msg.get("is_definition", False)),
+    )
+
+
+def _to_symbol_info(msg: dict[str, Any]) -> ScipSymbolInfo:
+    return ScipSymbolInfo(
+        symbol=msg.get("symbol", ""),
+        kind=msg.get("kind", 0),
+        documentation=tuple(msg.get("documentation", [])),
+        relationships=tuple(
+            _to_relationship(r) for r in msg.get("relationships", [])),
+        enclosing_symbol=msg.get("enclosing_symbol", ""),
+    )
+
+
+def _to_document(msg: dict[str, Any]) -> ScipDocument:
+    return ScipDocument(
+        relative_path=msg.get("relative_path", ""),
+        language=msg.get("language", ""),
+        occurrences=tuple(
+            ScipOccurrence(
+                symbol=o.get("symbol", ""),
+                roles=o.get("symbol_roles", 0),
+                range=_to_range(o),
+            )
+            for o in msg.get("occurrences", [])
+        ),
+        symbols=tuple(_to_symbol_info(s) for s in msg.get("symbols", [])),
+        position_encoding=msg.get("position_encoding", 0),
+    )
+
+
+def parse_index(data: bytes) -> ScipIndex:
+    """Decodifica bytes protobuf de um .scip → ScipIndex tipado."""
+    msg = decode_message(data, INDEX_SPEC, path="Index")
+    meta = msg.get("metadata") or {}
+    tool = meta.get("tool_info") or {}
+    docs = [_to_document(d) for d in msg.get("documents", [])]
+    return ScipIndex(
+        project_root=meta.get("project_root", ""),
+        tool_name=tool.get("name", ""),
+        tool_version=tool.get("version", ""),
+        text_document_encoding=meta.get("text_document_encoding", 0),
+        documents=tuple(docs),
+        external_symbols=tuple(
+            _to_symbol_info(s) for s in msg.get("external_symbols", [])),
+        raw_metadata=meta,
+    )
+
+
+__all__ = [
+    "ROLE_DEFINITION",
+    "DecodeError",
+    "ScipDocument",
+    "ScipIndex",
+    "ScipOccurrence",
+    "ScipRange",
+    "ScipRelationship",
+    "ScipSymbolInfo",
+    "parse_index",
+]

code_atlas/resolvers/scip/loader.py

@@ -0,0 +1,90 @@
+"""Carregamento opt-in de índices SCIP do disco (lf-0017).
+
+Política do indexer externo:
+- Entrada é **somente um caminho de arquivo** — o Atlas nunca executa
+  o indexer nem qualquer comando.
+- Cap de tamanho configurável (default ``MAX_INDEX_BYTES``).
+- Conteúdo é tratado como untrusted: decodificação via wire-reader
+  próprio + validação estrutural + binding de revisão.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from code_atlas.resolvers.scip.decoder import DecodeError
+from code_atlas.resolvers.scip.importer import ScipIndex, parse_index
+from code_atlas.resolvers.scip.validation import (
+    MAX_INDEX_BYTES,
+    project_root_matches,
+    validate_index,
+)
+
+
+@dataclass(frozen=True)
+class LoadOutcome:
+    """Resultado honesto do load — nunca levanta por conteúdo ruim."""
+
+    index: ScipIndex | None
+    errors: tuple[str, ...] = ()
+    warnings: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return self.index is not None and not self.errors
+
+
+def load_index(
+    path: Path,
+    *,
+    workspace_root: Path | None = None,
+    max_bytes: int = MAX_INDEX_BYTES,
+    allow_revision_mismatch: bool = False,
+) -> LoadOutcome:
+    """Lê e valida um arquivo ``.scip``.
+
+    - Arquivo inexistente/ilegível, oversize ou bytes malformados →
+      ``errors`` populadas (nunca raise para input externo).
+    - ``workspace_root`` informado ativa o binding de revisão:
+      ``project_root`` divergente rejeita a associação salvo
+      ``allow_revision_mismatch=True`` (opt-in explícito do usuário).
+    """
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        return LoadOutcome(None, errors=(f"cannot stat {path}: {exc}",))
+    if size > max_bytes:
+        return LoadOutcome(
+            None, errors=(f"index too large: {size} > {max_bytes}",))
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        return LoadOutcome(None, errors=(f"cannot read {path}: {exc}",))
+    try:
+        index = parse_index(data)
+    except DecodeError as exc:
+        return LoadOutcome(None, errors=(f"decode error: {exc}",))
+
+    res = validate_index(index, size)
+    if not res.ok:
+        return LoadOutcome(None, errors=res.errors, warnings=res.warnings)
+
+    errors: list[str] = []
+    warnings = list(res.warnings)
+    if workspace_root is not None and not project_root_matches(
+        index, workspace_root
+    ):
+        msg = (
+            f"project_root {index.project_root!r} does not match "
+            f"workspace {workspace_root}"
+        )
+        if allow_revision_mismatch:
+            warnings.append(f"{msg} (allowed by flag)")
+        else:
+            errors.append(msg)
+    return LoadOutcome(
+        index if not errors else None,
+        errors=tuple(errors),
+        warnings=tuple(warnings),
+    )