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

code_atlas/resolvers/scip/mapper.py

@@ -0,0 +1,271 @@
+"""Correlação explícita SCIP ↔ Atlas (lf-0017).
+
+Símbolos SCIP NÃO são ids internos do Atlas — este módulo faz a ponte:
+
+- ``parse_symbol``: string scip → partes (scheme, package, descriptors).
+  Gramática oficial (scip.proto):
+    ``<scheme> ' ' <manager> ' ' <name> ' ' <version> ' ' <descriptors>``
+    ou ``local <id>`` para símbolos confinados ao documento.
+- ``symbol_to_qname``: descriptors → qname estilo Atlas
+  (``ns.Class.method``), preservando sufixos de descriptor.
+- ``ScipCorrelator``: resolve occurrence→(path → símbolo Atlas), usando os
+  ``ScopeUniverse``/qnames montados pelo builder — associação por qname,
+  nunca por id posicional.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from code_atlas.resolvers.syntactic.resolver import ScopeUniverse
+
+# sufixo de descriptor → separador qname
+_SUFFIX_SEP = {
+    1: "/",   # Namespace
+    2: "#",   # Type
+    3: ".",   # Term
+    4: ".",   # Method (com disambiguator)
+    5: "[]",  # TypeParameter
+    6: "()",  # Parameter
+    7: ":",   # Meta
+    8: ".",   # Local
+    9: "!",   # Macro
+}
+
+
+@dataclass(frozen=True)
+class Descriptor:
+    name: str
+    disambiguator: str
+    suffix: int  # Descriptor.Suffix
+
+
+@dataclass(frozen=True)
+class ScipSymbol:
+    """Símbolo SCIP decomposto — nunca usado como id Atlas direto."""
+
+    scheme: str
+    manager: str
+    package_name: str
+    package_version: str
+    descriptors: tuple[Descriptor, ...]
+    local_id: str = ""  # preenchido só para 'local N'
+
+    @property
+    def is_local(self) -> bool:
+        return bool(self.local_id)
+
+    @property
+    def is_external(self) -> bool:
+        """Símbolo de pacote externo (manager/pacote preenchidos e
+        não-locais podem ser locais-do-repo também — externo de fato é
+        decidido pelo correlator via presença no universo)."""
+        return False
+
+
+_SYMBOL_RE = re.compile(
+    r"^(?P<scheme>\S+)\s+(?P<manager>\S+)\s+(?P<pkg>\S+)\s+"
+    r"(?P<ver>\S+)\s+(?P<desc>.+)$"
+)
+_LOCAL_RE = re.compile(r"^local\s+(?P<id>\S+)$")
+
+# um descriptor termina em: '/', '#', '.', ':', '!', '].', ').', '[]'
+_DESC_TOKEN_RE = re.compile(
+    r"(?P<name>`(?:[^`]|``)*`|[^\s/.#!:\[\]()`]+|`[^`]*`)"
+    r"(?P<disambig>(?:\([^)]*\))?)"
+    r"(?P<suffix>/|#|\.|:|!|\]|\))"
+)
+
+
+def parse_symbol(raw: str) -> ScipSymbol | None:
+    """String scip → ScipSymbol; None quando malformado."""
+    raw = raw.strip()
+    if not raw:
+        return None
+    m = _LOCAL_RE.match(raw)
+    if m:
+        return ScipSymbol(
+            scheme="", manager="", package_name="", package_version="",
+            descriptors=(), local_id=m.group("id"),
+        )
+    m = _SYMBOL_RE.match(raw)
+    if not m:
+        return None
+    descriptors = _parse_descriptors(m.group("desc"))
+    if descriptors is None:
+        return None
+    return ScipSymbol(
+        scheme=m.group("scheme"), manager=m.group("manager"),
+        package_name=m.group("pkg"), package_version=m.group("ver"),
+        descriptors=tuple(descriptors),
+    )
+
+
+def _parse_descriptors(text: str) -> list[Descriptor] | None:
+    """Separa a cadeia de descriptors em tokens (name+disambig+suffix)."""
+    out: list[Descriptor] = []
+    i = 0
+    n = len(text)
+    while i < n:
+        parsed = _read_name(text, i)
+        if parsed is None:
+            return None
+        name, i = parsed
+        disambig = ""
+        if i < n and text[i] == "(":  # method: name(disambig).
+            j = text.find(")", i)
+            if j == -1:
+                return None
+            disambig = text[i + 1 : j]
+            i = j  # consome ')' abaixo
+        if i >= n:
+            return None
+        end = _read_suffix(text, i)
+        if end is None:
+            return None
+        suffix, i = end
+        if not name:
+            return None
+        clean = name[1:-1] if name.startswith("`") and name.endswith("`") \
+            else name
+        out.append(Descriptor(name=clean, disambiguator=disambig,
+                              suffix=suffix))
+    return out
+
+
+def _read_name(text: str, i: int) -> tuple[str, int] | None:
+    """Lê um name (identifier ou `escaped`) a partir de i → (name, next)."""
+    n = len(text)
+    if text[i] == "`":  # escaped identifier — `` = escape
+        j = i + 1
+        while j < n:
+            if text[j] == "`":
+                if j + 1 < n and text[j + 1] == "`":
+                    j += 2
+                    continue
+                break
+            j += 1
+        if j >= n:
+            return None  # backtick não fechado
+        return text[i : j + 1], j + 1
+    j = i
+    while j < n and text[j] not in "/#.:(![`":
+        j += 1
+    return text[i:j], j
+
+
+def _read_suffix(text: str, i: int) -> tuple[int, int] | None:
+    """Lê o terminador de descriptor a partir de i → (suffix, next)."""
+    ch = text[i]
+    if ch == ")":  # fecha method descriptor (pode vir seguido de '.')
+        i += 1
+        if i < len(text) and text[i] == ".":
+            i += 1
+        return 4, i
+    if ch == "[":
+        j = text.find("]", i)
+        if j == -1:
+            return None
+        return 5, j + 1  # ']' termina o descriptor type-param
+    suffix = {"/": 1, "#": 2, ".": 3, ":": 7, "!": 9}.get(ch)
+    if suffix is None:
+        return None
+    return suffix, i + 1
+
+
+def symbol_to_qname(sym: ScipSymbol) -> str:
+    """Converte descriptors scip → qname estilo Atlas (pkg.Class.method).
+
+    Namespace e Type/Terms são concatenados com '.'; Method recebe '()';
+    TypeParameter/Parameter são sufixados ao termo anterior.
+    """
+    if sym.is_local:
+        return f"local:{sym.local_id}"
+    parts: list[str] = []
+    for d in sym.descriptors:
+        if d.suffix in (5, 6):  # type-param / parameter — suffixo inline
+            if parts:
+                parts[-1] += f"[{d.name}]" if d.suffix == 5 else f"({d.name})"
+            continue
+        name = d.name
+        if d.suffix == 4:  # method
+            name = f"{name}({d.disambiguator})" if d.disambiguator else name
+        parts.append(name)
+    return ".".join(parts)
+
+
+def symbol_parts(sym: ScipSymbol) -> tuple[str, tuple[str, ...]]:
+    """Decompõe descriptors em (doc_path candidato, nomes de membros).
+
+    Indexadores SCIP usam o path do documento como descriptor Namespace
+    (ex.: `` `pkg/util.py`/helper(). ``). Membros = descriptors
+    não-namespace, com disambiguator/parens removidos.
+    """
+    if sym.is_local:
+        return "", ()
+    ns_parts = [d.name for d in sym.descriptors if d.suffix == 1]
+    members = tuple(
+        d.name for d in sym.descriptors if d.suffix != 1
+    )
+    doc = "/".join(ns_parts)
+    return doc, members
+
+
+class ScipCorrelator:
+    """Mapa occurrence→nó Atlas dentro de um ``ScopeUniverse``.
+
+    Associação por (path do documento → módulo ctx) + (qname do símbolo →
+    ``qname_nid``); nunca assume que o id scip é o id interno.
+    """
+
+    def __init__(self, universe: ScopeUniverse) -> None:
+        self._u = universe
+
+    def module_for_document(self, relative_path: str) -> str | None:
+        """Document scip → nid do módulo Atlas com mesmo path."""
+        return self._u.by_path.get(relative_path)
+
+    def node_for_symbol(self, raw: str, path: str) -> str | None:
+        """String scip → nid de símbolo no snapshot (ou None).
+
+        Estratégia: (1) doc-path do namespace → ctx do módulo + membro
+        final; (2) leaf global como fallback; (3) qname direto. Só
+        retorna nid quando a identidade é única.
+        """
+        sym = parse_symbol(raw)
+        if sym is None or sym.is_local:
+            return None
+        doc, members = symbol_parts(sym)
+        hits = self._match(sym, doc, members, path)
+        return hits[0] if len(hits) == 1 else None
+
+    def _match(
+        self,
+        sym: ScipSymbol,
+        doc: str,
+        members: tuple[str, ...],
+        path: str,
+    ) -> list[str]:
+        if doc:
+            ctx = self._u.ctx_for_path(doc)
+            if ctx is not None:
+                if not members:
+                    return [ctx.nid]
+                hits = sorted(set(ctx.defines.get(members[-1], [])))
+                if hits:
+                    return hits
+        if members:
+            hits = sorted(set(self._u.leaf.get(members[-1], [])))
+            if hits:
+                return hits
+        qname = symbol_to_qname(sym)
+        return sorted(set(self._u.qname_nid.get(qname, [])))
+
+    def candidates_for_symbol(self, raw: str) -> tuple[str, ...]:
+        sym = parse_symbol(raw)
+        if sym is None or sym.is_local:
+            return ()
+        doc, members = symbol_parts(sym)
+        hits = self._match(sym, doc, members, "")
+        return tuple(sorted(set(hits)))

code_atlas/resolvers/scip/provenance.py

@@ -0,0 +1,211 @@
+"""Contrato de proveniência + revision safety do índice SCIP (lf-0028).
+
+``project_root`` bater não basta: um índice pode ser de outro repo com
+o mesmo path, estar velho (arquivos modificados/removidos depois da
+indexação) ou simplesmente incompleto. ``IndexProvenance`` é o modelo
+interno — não presume que o .scip contenha todos os campos; o que não
+pode ser provado fica explicitamente marcado.
+
+``validation_status``:
+- ``current``: todas as verificações passaram.
+- ``degraded``: índice utilizável, mas evidência de revisão
+  insuficiente — relações derivadas NUNCA são promovidas como
+  comprovadas (confidence capado em ``heuristic`` no resolver).
+- ``rejected``: incompatível — o resolver não produz resolução
+  nenhuma (índice incompatível nunca contamina snapshot READY).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from code_atlas.resolvers.scip.importer import ScipDocument, ScipIndex
+from code_atlas.resolvers.scip.validation import project_root_matches
+
+# position_encoding válido no mapper: UTF-32 (3) ou não-declarado (0
+# — protobuf enum zero/default); outros encodings tornam spans
+# não-confiáveis → degraded (o mapper não re-decodifica).
+TRUSTED_ENCODINGS = frozenset({0, 3})
+
+STATUS_CURRENT = "current"
+STATUS_DEGRADED = "degraded"
+STATUS_REJECTED = "rejected"
+
+
+@dataclass(frozen=True)
+class IndexProvenance:
+    """Proveniência de um índice externo — inspecionável e serializável."""
+
+    index_format: str = "scip"
+    index_sha256: str = ""          # sha256 dos bytes do arquivo
+    producer_name: str = ""         # metadata.tool_info.name
+    producer_version: str = ""      # metadata.tool_info.version
+    repository_identity: str = ""   # metadata.project_root (URI)
+    source_revision: str = ""       # revisão do repo indexado, se provável
+    worktree_digest: str = ""       # digest dos arquivos indexados vistos
+    indexed_at: str = ""            # mtime do arquivo .scip (evidência host)
+    validation_status: str = STATUS_REJECTED
+    validation_evidence: tuple[str, ...] = ()
+
+    def summary(self) -> str:
+        """Resumo one-line para evidence notes / diagnósticos."""
+        return (
+            f"scip-provenance status={self.validation_status} "
+            f"sha256={self.index_sha256[:12]} "
+            f"producer={self.producer_name}@{self.producer_version} "
+            f"revision={self.source_revision or 'unknown'}"
+        )
+
+
+@dataclass(frozen=True)
+class RevisionAssessment:
+    """Resultado do assessment: proveniência + erros + avisos."""
+
+    provenance: IndexProvenance
+    errors: tuple[str, ...] = ()
+    warnings: tuple[str, ...] = ()
+
+
+def assess_revision(
+    index: ScipIndex,
+    index_path: Path,
+    workspace_root: Path,
+    *,
+    raw_bytes: bytes | None = None,
+) -> RevisionAssessment:
+    """Verifica o índice contra o worktree atual.
+
+    Sinais sem executar nada do repo: identidade (``project_root`` ↔
+    workspace), staleness, paths, spans vs fim de arquivo,
+    ``position_encoding``, completude de metadata, símbolos duplicados.
+    """
+    if raw_bytes is None:
+        try:
+            raw_bytes = index_path.read_bytes()
+        except OSError as exc:
+            return RevisionAssessment(
+                IndexProvenance(validation_status=STATUS_REJECTED),
+                errors=(f"cannot read index for provenance: {exc}",),
+            )
+    sha = hashlib.sha256(raw_bytes).hexdigest()
+    index_mtime, indexed_at = _index_stamp(index_path)
+    base = dict(
+        index_sha256=sha,
+        producer_name=index.tool_name,
+        producer_version=index.tool_version,
+        repository_identity=index.project_root,
+        indexed_at=indexed_at,
+    )
+    if not project_root_matches(index, workspace_root):
+        return RevisionAssessment(
+            IndexProvenance(
+                **base,
+                validation_status=STATUS_REJECTED,
+                validation_evidence=("project_root mismatch",),
+            ),
+            errors=(
+                f"index project_root {index.project_root!r} does not "
+                f"identify workspace {workspace_root}",
+            ),
+        )
+    degraded, digest = _check_docs(
+        index, Path(workspace_root).resolve(), index_mtime)
+    degraded += _check_completeness(index, index_mtime)
+    status = STATUS_DEGRADED if degraded else STATUS_CURRENT
+    return RevisionAssessment(
+        IndexProvenance(
+            **base,
+            source_revision="",  # scip metadata não prova commit
+            worktree_digest=digest,
+            validation_status=status,
+            validation_evidence=(
+                "project_root matches workspace", *degraded),
+        ),
+        warnings=tuple(degraded)
+        + (() if index_mtime else ("index mtime unavailable",)),
+    )
+
+
+def _index_stamp(index_path: Path) -> tuple[float, str]:
+    try:
+        mtime = index_path.stat().st_mtime
+    except OSError:
+        return 0.0, ""
+    return mtime, datetime.fromtimestamp(
+        mtime, tz=UTC).isoformat()
+
+
+def _check_docs(
+    index: ScipIndex, root: Path, index_mtime: float
+) -> tuple[list[str], str]:
+    """staleness + paths + spans + encoding + símbolos duplicados."""
+    degraded: list[str] = []
+    defined_in: dict[str, str] = {}
+    digest_parts: list[str] = []
+    for doc in index.documents:
+        p = doc.relative_path
+        if "\\" in p or "//" in p or p.startswith("./"):
+            degraded.append(f"non-normalized path: {p!r}")
+        if doc.position_encoding not in TRUSTED_ENCODINGS:
+            degraded.append(f"doc {p}: position_encoding="
+                            f"{doc.position_encoding} untrusted")
+        for s in doc.symbols:
+            prev = defined_in.get(s.symbol)
+            if prev is not None and prev != p:
+                degraded.append(
+                    f"symbol {s.symbol!r} defined in {prev} and {p}")
+            else:
+                defined_in[s.symbol] = p
+        degraded += _check_doc_file(doc, root / p, index_mtime,
+                                    digest_parts)
+    digest = hashlib.sha256(
+        "\n".join(sorted(digest_parts)).encode()).hexdigest()
+    return degraded, digest
+
+
+def _check_doc_file(
+    doc: ScipDocument, target: Path, index_mtime: float,
+    digest_parts: list[str],
+) -> list[str]:
+    """staleness e spans de um documento contra o arquivo atual."""
+    p = doc.relative_path
+    if not target.is_file():
+        digest_parts.append(f"{p}:absent")
+        return [f"indexed file missing: {p}"]
+    try:
+        fst = target.stat()
+    except OSError:
+        return [f"cannot stat {p}"]
+    digest_parts.append(f"{p}:{fst.st_size}")
+    out: list[str] = []
+    if index_mtime and fst.st_mtime > index_mtime:
+        out.append(f"file newer than index: {p}")
+    if doc.occurrences:
+        try:
+            n_lines = len(
+                target.read_text(encoding="utf-8").splitlines())
+        except (OSError, UnicodeDecodeError):
+            n_lines = -1
+        if n_lines >= 0:
+            max_line = max(
+                (o.range.start_line if o.range else 0)
+                for o in doc.occurrences)
+            if max_line > n_lines:
+                out.append(f"doc {p}: occurrence span line {max_line} "
+                           f"beyond file end {n_lines}")
+    return out
+
+
+def _check_completeness(index: ScipIndex, index_mtime: float) -> list[str]:
+    """índice válido ≠ índice completo."""
+    out: list[str] = []
+    if not index.tool_version:
+        out.append("metadata.tool_info.version missing")
+    if not index.documents:
+        out.append("index has no documents")
+    if not index_mtime:
+        out.append("index timestamp unknown")
+    return out