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

code_atlas/observability/__init__.py

@@ -0,0 +1,19 @@
+"""Logging estruturado e redaction (sem telemetria, sem egress)."""
+
+from code_atlas.observability.logging import (
+    JsonFormatter,
+    RedactionFilter,
+    get_logger,
+    log_if_slow,
+    slow_ms,
+    timed,
+)
+
+__all__ = [
+    "JsonFormatter",
+    "RedactionFilter",
+    "get_logger",
+    "log_if_slow",
+    "slow_ms",
+    "timed",
+]

code_atlas/observability/logging.py

@@ -0,0 +1,199 @@
+"""Logging estruturado com redaction (Blueprint §9, ADR-014).
+
+Sem telemetria, sem egress — logs vão apenas para stderr local.
+Formato: texto simples por padrão, JSON-lines com ``CODE_ATLAS_LOG_FORMAT=json``.
+Nível: ``CODE_ATLAS_LOG_LEVEL`` (default WARNING).
+
+O filtro de redaction mascara: (a) caminhos absolutos dentro de $HOME,
+(b) padrões de segredo (tokens, chaves, assignments sensíveis).
+
+Slow-query guard (lf-0141, Cycle 8 Phase 15): ``CODE_ATLAS_SLOW_MS``
+define um teto de latência em milissegundos; chamadas instrumentadas
+que o excedem emitem ``DEBUG`` via :func:`log_if_slow` / :func:`timed`.
+Ausente, inválido ou ``<=0`` = guard desligado com custo zero (um
+``os.environ.get`` por chamada, nenhum clock extra além do já medido).
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import logging
+import os
+import re
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import ParamSpec, TypeVar
+
+ENV_FORMAT = "CODE_ATLAS_LOG_FORMAT"
+ENV_LEVEL = "CODE_ATLAS_LOG_LEVEL"
+ENV_SLOW_MS = "CODE_ATLAS_SLOW_MS"
+
+_TOKEN_RE = re.compile(
+    r"(?i)(api[_-]?key|token|secret|password|passwd|authorization|bearer|"
+    r"aws[_-]?access|private[_-]?key|credential)\s*[:=]\s*\S+"
+)
+_LONG_SECRET_RE = re.compile(r"\b[A-Za-z0-9+/=_\-]{40,}\b")
+_PEM_RE = re.compile(r"-----BEGIN [A-Z ]+PRIVATE KEY-----.*?-----END [A-Z ]+PRIVATE KEY-----",
+                     re.DOTALL)
+# Controles C0/C1/DEL → escape ``\xNN`` (lf-0153, cycle-8.1 Phase 10):
+# linha de request hostil (``GET /\x1b[31m``) ou filename com ``\n``
+# podiam forjar linhas/sequências ANSI no stderr — logs são single-line
+# por contrato, então TODO caractere de controle vira escape visível.
+_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+
+def escape_control(text: str) -> str:
+    """Caracteres de controle viram ``\\xNN`` — anti log-injection."""
+    return _CONTROL_RE.sub(lambda m: f"\\x{ord(m.group(0)):02x}", text)
+
+
+def _redact_text(text: str, home: str) -> str:
+    """Aplica as regras de mascaramento a uma string."""
+    text = escape_control(text)
+    if home and home in text:
+        text = text.replace(home, "~")
+    text = _PEM_RE.sub("<REDACTED:pem>", text)
+    text = _TOKEN_RE.sub(lambda m: m.group(1) + "=<REDACTED>", text)
+    # Sequências longas tipo chave/token só mascaram se parecerem segredo.
+    text = _LONG_SECRET_RE.sub(lambda m: "<REDACTED>", text)
+    return text
+
+
+class RedactionFilter(logging.Filter):
+    """Remove home paths e segredos de todos os records emitidos."""
+
+    def __init__(self, home: str | None = None) -> None:
+        super().__init__()
+        self._home = home or str(Path.home())
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.msg, str):
+            record.msg = _redact_text(record.msg, self._home)
+        if record.args:
+            record.args = tuple(
+                _redact_text(str(a), self._home) if isinstance(a, (str, Path)) else a
+                for a in record.args
+            ) if isinstance(record.args, tuple) else record.args
+        if record.exc_info and record.exc_text is None:
+            # lf-0153: traceback text contorna msg/args — pré-renderiza
+            # escapado para que o Formatter não emita controles crus
+            # (filename ``a\nb.py`` numa exceção forjaria linhas).
+            record.exc_text = escape_control(
+                logging.Formatter().formatException(record.exc_info))
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    """Serializa records como JSON-lines (uma linha por evento)."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Logger configurado com redaction; idempotente por nome."""
+    logger = logging.getLogger(name)
+    if getattr(logger, "_atlas_configured", False):
+        return logger
+    logger.setLevel(os.environ.get(ENV_LEVEL, "WARNING").upper())
+    handler = logging.StreamHandler()
+    handler.addFilter(RedactionFilter())
+    if os.environ.get(ENV_FORMAT, "").lower() == "json":
+        handler.setFormatter(JsonFormatter())
+    else:
+        handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
+    logger.addHandler(handler)
+    logger.propagate = False
+    logger._atlas_configured = True  # type: ignore[attr-defined]
+    return logger
+
+
+# --- slow-query guard (lf-0141) -----------------------------------------
+#
+# Guard opt-in por env: ``CODE_ATLAS_SLOW_MS`` é o teto em ms. As
+# fronteiras instrumentadas (despacho HTTP em ``api.handlers.handle``,
+# ``SearchEngine.search_scoped``) medem com ``time.monotonic`` — o
+# guard só decide se o valor já medido vira uma linha DEBUG.
+
+def slow_ms(env: dict[str, str] | None = None) -> float | None:
+    """Teto do slow-query guard em ms; ``None`` = desligado.
+
+    ``CODE_ATLAS_SLOW_MS`` ausente/vazio, não-numérico ou ``<= 0``
+    desliga o guard — opt-in explícito, default de custo zero.
+    """
+    raw = (env if env is not None else os.environ).get(ENV_SLOW_MS, "")
+    if not raw:
+        return None
+    try:
+        ms = float(raw)
+    except ValueError:
+        return None
+    return ms if ms > 0 else None
+
+
+def log_if_slow(
+    logger: logging.Logger, label: str, t0: float, detail: str = ""
+) -> None:
+    """Emite ``DEBUG`` quando ``time.monotonic() - t0`` excede o teto.
+
+    ``detail`` é contexto da chamada (rota, estratégia) — passa pelo
+    ``RedactionFilter`` do logger como qualquer mensagem.
+    """
+    ms = slow_ms()
+    if ms is None:
+        return
+    elapsed = (time.monotonic() - t0) * 1000
+    # Windows: clock monotônico tem resolução ~15.6ms — elapsed=0 pode
+    # ser "instantâneo" ou "menor que um tick". Somar a resolução torna
+    # o guard conservador: só garante não-slow quando mesmo o pior caso
+    # dentro da granularidade ficaria abaixo do teto.
+    res_ms = time.get_clock_info("monotonic").resolution * 1000
+    if elapsed + res_ms > ms:
+        suffix = f" {detail}" if detail else ""
+        logger.debug("slow %s elapsed_ms=%.1f threshold_ms=%.0f%s",
+                     label, elapsed, ms, suffix)
+
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def timed(label: str) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
+    """Decorator do slow-query guard — mede a chamada e delega a
+    ``log_if_slow``. O logger é ``code_atlas.<label>`` (mesmo filtro
+    de redaction de qualquer ``get_logger``)."""
+    logger = get_logger(f"code_atlas.{label}")
+
+    def deco(fn: Callable[_P, _R]) -> Callable[_P, _R]:
+        @functools.wraps(fn)
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+            t0 = time.monotonic()
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                log_if_slow(logger, label, t0)
+
+        return wrapper
+
+    return deco
+
+
+__all__ = [
+    "JsonFormatter",
+    "RedactionFilter",
+    "escape_control",
+    "get_logger",
+    "log_if_slow",
+    "slow_ms",
+    "timed",
+]

code_atlas/parsers/__init__.py

@@ -0,0 +1,43 @@
+"""Subsistema de parsing por adaptadores (Cycle 2 — Phases 1+2).
+
+Boundary: apenas ``parsers/`` pode importar ``tree_sitter``. Código de
+domínio (contracts, discovery, storage, graph) consome os contratos
+tipados daqui sem conhecer a implementação concreta.
+"""
+
+from code_atlas.parsers.contracts import (
+    EvidenceRecord,
+    ExtractedReference,
+    ExtractedRelation,
+    ExtractedSymbol,
+    GraphBuildResult,
+    GraphEdge,
+    GraphNode,
+    ParseDiagnostic,
+    ParserAdapter,
+    ParserCapability,
+    ParseRequest,
+    ParseResult,
+    SourceSpan,
+)
+from code_atlas.parsers.engine import ParseEngine, ParseLimits
+from code_atlas.parsers.registry import ParserRegistry
+
+__all__ = [
+    "EvidenceRecord",
+    "ExtractedReference",
+    "ExtractedRelation",
+    "ExtractedSymbol",
+    "GraphBuildResult",
+    "GraphEdge",
+    "GraphNode",
+    "ParseDiagnostic",
+    "ParseEngine",
+    "ParseLimits",
+    "ParseRequest",
+    "ParseResult",
+    "ParserAdapter",
+    "ParserCapability",
+    "ParserRegistry",
+    "SourceSpan",
+]

code_atlas/parsers/contracts.py

@@ -0,0 +1,209 @@
+"""Contratos tipados do subsistema de parsing (Cycle 2 Phase 1).
+
+Separação dura: parsing sintático ≠ resolução semântica. Tudo que um
+adaptador produz é sintático — resolução de alvos é responsabilidade do
+graph builder e de resolvers futuros (SCIP/LSP, Cycle 3).
+
+Convenções de span: ``line`` é 1-based (humanos/editores), ``col`` é a
+coluna em bytes 0-based do Tree-sitter; offsets em bytes sobre UTF-8.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    """Localização de um nó no arquivo-fonte."""
+
+    start_byte: int
+    end_byte: int
+    start_line: int  # 1-based
+    start_col: int  # byte offset 0-based
+    end_line: int
+    end_col: int
+
+
+@dataclass(frozen=True)
+class ParseDiagnostic:
+    """Problema estruturado registrado durante parsing/extração."""
+
+    code: str  # ex.: "error-node", "missing-node", "file-too-large", "timeout"
+    severity: str  # "error" | "warning" | "info"
+    message: str
+    span: SourceSpan | None = None
+
+
+@dataclass(frozen=True)
+class ParserCapability:
+    """Capacidades declaradas de um adaptador (capability matrix)."""
+
+    symbols: bool = True
+    signatures: bool = True
+    docstrings: bool = True
+    imports: bool = True
+    calls: bool = True
+    decorators: bool = False
+    inheritance: bool = True
+    interfaces: bool = False
+
+
+@dataclass(frozen=True)
+class ParseRequest:
+    """Entrada de parsing: bytes UTF-8 + metadados. Nunca executa o alvo."""
+
+    path: str  # rel POSIX dentro do repositório
+    language: str  # id resolvido pelo registry
+    content: bytes
+    timeout_us: int = 2_000_000
+
+
+@dataclass(frozen=True)
+class ExtractedSymbol:
+    """Símbolo estrutural extraído — ligação lógica fica para o grafo."""
+
+    language: str
+    kind: str  # NodeKind string: module|class|interface|function|method|symbol
+    name: str
+    qualified_name: str  # module.scope.name — nunca usa nº de linha
+    span: SourceSpan
+    name_span: SourceSpan | None = None
+    scope_path: tuple[str, ...] = ()  # nomes dos escopos léxicos externos
+    signature: str | None = None
+    params: tuple[str, ...] = ()  # nomes dos parâmetros, em ordem
+    docstring: str | None = None
+    decorators: tuple[str, ...] = ()
+    bases: tuple[str, ...] = ()  # extends declarado
+    implements: tuple[str, ...] = ()  # implements declarado (TS)
+    modifiers: tuple[str, ...] = ()  # async|export|default|static|abstract...
+
+
+@dataclass(frozen=True)
+class ExtractedReference:
+    """Menção sintática a um nome — alvo textual preservado."""
+
+    name: str  # texto do alvo (ex.: "foo", "pkg.mod", "obj.method")
+    context: str  # call|import|import-member|extends|implements|decorator|type-ref|jsx
+    span: SourceSpan
+    scope_path: tuple[str, ...] = ()
+    target: str = ""  # import-member: "modulo.membro" do símbolo importado
+
+
+@dataclass(frozen=True)
+class ExtractedRelation:
+    """Relação sintática candidata extraída pelo adaptador."""
+
+    type: str  # EdgeKind string
+    from_name: str  # qualified name da origem
+    to_name: str  # alvo textual — resolução é do graph builder
+    span: SourceSpan
+    confidence_class: str = "syntactic"
+    resolution_status: str = "unresolved"
+
+
+@dataclass(frozen=True)
+class ParseResult:
+    """Saída de um arquivo parseado — real, sem mocks."""
+
+    path: str
+    language: str
+    parser: str  # id do adaptador (ex.: "tree-sitter-python")
+    parser_version: str
+    grammar_version: str
+    content_hash: str  # sha256 do conteúdo — casa com a evidência
+    has_error: bool = False
+    error_node_count: int = 0
+    missing_node_count: int = 0
+    node_count: int = 0
+    diagnostics: tuple[ParseDiagnostic, ...] = ()
+    symbols: tuple[ExtractedSymbol, ...] = ()
+    references: tuple[ExtractedReference, ...] = ()
+    relations: tuple[ExtractedRelation, ...] = ()
+    supported: bool = True
+
+
+class ParserAdapter(Protocol):
+    """Adaptador concreto de linguagem (implementado por Tree-sitter)."""
+
+    language: str
+    extensions: tuple[str, ...]
+    capabilities: ParserCapability
+
+    @property
+    def adapter_id(self) -> str:
+        """Ex.: ``tree-sitter-python`` — entra em analyzer_versions."""
+        ...
+
+    @property
+    def parser_version(self) -> str: ...
+
+    @property
+    def grammar_version(self) -> str: ...
+
+    def parse(self, request: ParseRequest) -> ParseResult: ...
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+    """Proveniência de uma relação/nó persistido (Blueprint §5)."""
+
+    path: str  # arquivo de origem
+    span: SourceSpan | None
+    content_hash: str
+    extractor: str  # adapter_id
+    extractor_version: str  # "parserX.Y+grammarZ.W"
+    notes: str = ""
+    # Proveniência de resolvedor (lf-0035) — opcionais; "" quando a
+    # evidência veio do parser e não de um resolvedor semântico.
+    resolver_id: str = ""
+    resolver_version: str = ""
+    evidence_tier: int = 0  # EvidenceTier (0 = não-resolver)
+    index_hash: str = ""    # sha do índice externo (ex.: SCIP), se houver
+    validation_status: str = ""  # ex.: "confirmed", "conflict"
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    """Nó tipado do grafo canônico (saída do builder)."""
+
+    node_id: str  # identidade determinística — nunca nº de linha
+    kind: str  # NodeKind
+    name: str
+    qualified_name: str
+    language: str = ""
+    path: str = ""  # rel path (file/module/package nodes)
+    span: SourceSpan | None = None
+    content_hash: str = ""
+    signature: str | None = None
+    params: tuple[str, ...] = ()
+    docstring: str | None = None
+    modifiers: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class GraphEdge:
+    """Aresta tipada com proveniência completa."""
+
+    type: str  # EdgeKind
+    from_id: str  # GraphNode.node_id
+    to_id: str | None = None  # None quando alvo não resolveu para nó
+    to_text: str = ""  # alvo textual preservado (unresolved/ambiguous)
+    resolution_status: str = "unresolved"
+    confidence_class: str = "syntactic"
+    resolver: str = ""  # id do resolver/extrator
+    evidence_index: tuple[int, ...] = ()  # índices em GraphBuildResult.evidence
+    span: SourceSpan | None = None
+    source_path: str = ""  # arquivo de origem da aresta (lf-0027)
+
+
+@dataclass(frozen=True)
+class GraphBuildResult:
+    """Saída determinística do graph builder (hand-off para storage)."""
+
+    nodes: tuple[GraphNode, ...] = ()
+    edges: tuple[GraphEdge, ...] = ()
+    evidence: tuple[EvidenceRecord, ...] = ()
+    diagnostics: tuple[ParseDiagnostic, ...] = ()
+    stats: dict[str, int] = field(default_factory=dict)

code_atlas/parsers/engine.py

@@ -0,0 +1,125 @@
+"""Motor de parsing: orquestra requests, limites e isolamento de falhas.
+
+Política de erro (Phase 2): falha por arquivo é registrada em
+``ParseResult.diagnostics`` e nunca derruba o batch. Erros recuperáveis
+(file-too-large, unsupported, timeout, parse-error) viram resultado com
+``supported``/``has_error`` marcados; erro fatal = bug no adaptador —
+isolado por arquivo como diagnóstico ``adapter-crash``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from code_atlas.parsers.contracts import (
+    ParseDiagnostic,
+    ParseRequest,
+    ParseResult,
+    SourceSpan,
+)
+from code_atlas.parsers.registry import ParserRegistry
+
+
+@dataclass(frozen=True)
+class ParseLimits:
+    """Limites por arquivo — proteção contra conteúdo hostil."""
+
+    max_file_size: int = 1 << 20  # 1 MiB
+    timeout_us: int = 2_000_000
+    max_diagnostics: int = 50
+
+
+def _empty_result(
+    path: str,
+    language: str,
+    content: bytes,
+    diagnostic: ParseDiagnostic,
+) -> ParseResult:
+    return ParseResult(
+        path=path,
+        language=language,
+        parser="",
+        parser_version="",
+        grammar_version="",
+        content_hash=hashlib.sha256(content).hexdigest(),
+        diagnostics=(diagnostic,),
+        supported=False,
+    )
+
+
+class ParseEngine:
+    """Orquestra ParseRequests via registry. Sem estado mutável exposto."""
+
+    def __init__(
+        self, registry: ParserRegistry | None = None, limits: ParseLimits | None = None
+    ) -> None:
+        self.registry = registry or ParserRegistry.default()
+        self.limits = limits or ParseLimits()
+
+    def parse(self, rel_path: str, content: bytes) -> ParseResult:
+        """Parse de um arquivo; falhas viram diagnósticos, não exceções."""
+        adapter = self.registry.for_path(rel_path)
+        if adapter is None:
+            return _empty_result(
+                rel_path,
+                "",
+                content,
+                ParseDiagnostic(
+                    code="unsupported-language",
+                    severity="info",
+                    message="no parser adapter for this path",
+                ),
+            )
+        if len(content) > self.limits.max_file_size:
+            return _empty_result(
+                rel_path,
+                adapter.language,
+                content,
+                ParseDiagnostic(
+                    code="file-too-large",
+                    severity="warning",
+                    message=f"{len(content)} bytes exceeds limit {self.limits.max_file_size}",
+                ),
+            )
+        request = ParseRequest(
+            path=rel_path,
+            language=adapter.language,
+            content=content,
+            timeout_us=self.limits.timeout_us,
+        )
+        try:
+            result = adapter.parse(request)
+        except Exception as exc:
+            return _empty_result(
+                rel_path,
+                adapter.language,
+                content,
+                ParseDiagnostic(
+                    code="adapter-crash",
+                    severity="error",
+                    message=f"{type(exc).__name__}: {exc}",
+                ),
+            )
+        if len(result.diagnostics) > self.limits.max_diagnostics:
+            result = ParseResult(
+                **{
+                    **result.__dict__,
+                    "diagnostics": result.diagnostics[: self.limits.max_diagnostics],
+                }
+            )
+        return result
+
+    def parse_batch(
+        self, items: Iterable[tuple[str, bytes]]
+    ) -> list[ParseResult]:
+        """Parse de lote — isolamento garantido por arquivo."""
+        return [self.parse(path, content) for path, content in items]
+
+
+def span_of_point(
+    start_byte: int, end_byte: int, line: int, col: int, end_line: int, end_col: int
+) -> SourceSpan:
+    """Helper de construção de span para testes."""
+    return SourceSpan(start_byte, end_byte, line, col, end_line, end_col)

code_atlas/parsers/languages/__init__.py

@@ -0,0 +1 @@
+"""Adaptadores concretos de linguagem (Tree-sitter)."""