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

code_atlas/impact/blast_radius.py

@@ -0,0 +1,171 @@
+"""Blast radius — BFS reverso de dependências (Phase 5).
+
+Aresta resolvida ``from → to`` significa "from depende de to"; para
+impacto, consumidores do símbolo alterado = arestas ``from`` cujo
+``to_id`` aponta para a ocorrência alterada. Uma aresta
+unresolved/ambiguous no caminho → ``fully_verified=False`` → impacto
+rebaixado para ``possible`` (nunca promovido).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections import deque
+from dataclasses import dataclass
+
+from code_atlas.impact.contracts import (
+    EvidenceStrength,
+    ImpactCandidate,
+    ImpactKind,
+    ImpactLimits,
+    ImpactPath,
+)
+
+_IN_SQL = (
+    "SELECT id, from_id, to_id, type, resolution_status"
+    " FROM relations WHERE snapshot_id = ? AND to_id = ?"
+    " ORDER BY id LIMIT ?"
+)
+_SYM_SQL = (
+    "SELECT s.qualified_name, s.language, s.kind, o.id AS occ_id,"
+    " f.relative_path FROM symbol_occurrences o"
+    " JOIN symbols s ON s.id = o.logical_symbol_id"
+    " JOIN source_files f ON f.id = o.source_file_id"
+    " WHERE o.id = ?"
+)
+
+
+@dataclass(frozen=True)
+class _Hit:
+    key: str
+    qname: str
+    language: str
+    kind: str
+    occ_id: int
+    path: str
+
+
+def _sym(conn: sqlite3.Connection, occ_id: int) -> _Hit | None:
+    row = conn.execute(_SYM_SQL, (occ_id,)).fetchone()
+    if row is None:
+        return None
+    key = f"{row['language']}:{row['kind']}:{row['qualified_name']}"
+    return _Hit(key, str(row["qualified_name"]), str(row["language"]),
+                str(row["kind"]), int(row["occ_id"]),
+                str(row["relative_path"]))
+
+
+def _frontier_pending(
+    conn: sqlite3.Connection, snapshot_id: int, occ: int,
+    origin_key: str, origins: dict[str, int],
+    visited: set[tuple[int, str]], limits: ImpactLimits,
+) -> bool:
+    """``True`` se o nó de fronteira (emitido em ``hops >= max_depth``,
+    nunca enfileirado) ainda tinha consumidor atravessável para a
+    origem — ou o scan de vizinhos excedeu ``max_nodes`` (sonda +1:
+    a cauda não-vista pode esconder trabalho, lf-0151)."""
+    rows = conn.execute(
+        _IN_SQL, (snapshot_id, occ, limits.max_nodes + 1)).fetchall()
+    if len(rows) > limits.max_nodes:
+        return True
+    for r in rows:
+        consumer_occ = int(r["from_id"])
+        if (consumer_occ, origin_key) in visited:
+            continue
+        hit = _sym(conn, consumer_occ)
+        if hit is None or hit.key in origins:
+            continue
+        return True
+    return False
+
+
+def blast(
+    conn: sqlite3.Connection, snapshot_id: int,
+    origins: dict[str, int],  # symbol_key → occurrence_id alterado
+    limits: ImpactLimits,
+    *,
+    reason_suffix: str = "",
+) -> tuple[tuple[ImpactCandidate, ...], bool]:
+    """BFS de consumidores; retorna (candidatos, truncated).
+
+    ``truncated`` é a união de todos os bounds que descartaram
+    trabalho (lf-0151): emissão no cap ``max_paths``, varredura de
+    vizinhos de um nó no cap ``max_nodes`` (prefixo ``ORDER BY id``
+    determinístico — rows além dele nunca vistas) e nós na fronteira
+    ``hops >= max_depth`` com consumidores ainda atravessáveis. A
+    discriminação por razão é exposta por
+    ``domain_traversal.blast``/``ImpactResult.truncation_reasons``.
+    """
+    conn.row_factory = sqlite3.Row
+    out: list[ImpactCandidate] = []
+    # lf-0079: visita por (nó, origem) — duas origens até o mesmo
+    # consumidor preservam caminhos alternativos; ciclo continua
+    # cortado por (nó visitado na mesma linha de origem).
+    visited: set[tuple[int, str]] = set()
+    queue: deque[tuple[int, str, list[int], list[str], list[str], int]] = (
+        deque())
+    for key, occ in origins.items():
+        queue.append((occ, key, [], [], [], 0))
+    edge_scan_capped = False
+    frontier: list[tuple[int, str]] = []
+
+    while queue:
+        occ, origin_key, rel_ids, mids, statuses, depth = queue.popleft()
+        vkey = (occ, origin_key)
+        if vkey in visited or depth > limits.max_depth:
+            continue
+        visited.add(vkey)
+        # +1 linha de sonda: distingue fit exato de overflow real —
+        # só o overflow descarta trabalho (lf-0151).
+        rows = conn.execute(
+            _IN_SQL, (snapshot_id, occ,
+                      limits.max_nodes + 1)).fetchall()
+        if len(rows) > limits.max_nodes:
+            edge_scan_capped = True
+            rows = rows[:limits.max_nodes]
+        for r in rows:
+            consumer_occ = int(r["from_id"])
+            if (consumer_occ, origin_key) in visited:
+                continue
+            hit = _sym(conn, consumer_occ)
+            if hit is None or hit.key in origins:
+                continue
+            new_rels = [*rel_ids, int(r["id"])]
+            new_mid = [*mids, hit.key]
+            new_st = [*statuses, str(r["resolution_status"])]
+            verified = all(s == "resolved" for s in new_st)
+            hops = len(new_rels)
+            kind = (ImpactKind.DIRECT if hops == 1 and verified
+                    else ImpactKind.TRANSITIVE if verified
+                    else ImpactKind.POSSIBLE)
+            strength = (EvidenceStrength.VERIFIED if verified
+                        else EvidenceStrength.POSSIBLE)
+            path = ImpactPath(
+                origin_symbol_key=origin_key,
+                affected_symbol_key=hit.key, hops=hops,
+                relation_ids=tuple(new_rels),
+                intermediate_keys=tuple(new_mid),
+                resolution_statuses=tuple(new_st),
+                fully_verified=verified,
+                reason=(f"{r['type']} via relation {r['id']}"
+                        + reason_suffix))
+            out.append(ImpactCandidate(
+                symbol_key=hit.key, qualified_name=hit.qname,
+                language=hit.language, kind=hit.kind, impact=kind,
+                strength=strength, path=path,
+                source_path=hit.path, occurrence_id=hit.occ_id))
+            if len(out) >= limits.max_paths:
+                return tuple(out), True
+            if hops < limits.max_depth:
+                queue.append((consumer_occ, origin_key,
+                              new_rels, new_mid, new_st, depth + 1))
+            else:
+                # fronteira de depth: emitido mas nunca expandido —
+                # sonda decide se o corte descartou trabalho.
+                frontier.append((consumer_occ, origin_key))
+
+    depth_cut = any(
+        _frontier_pending(conn, snapshot_id, occ, key, origins,
+                          visited, limits)
+        for occ, key in dict.fromkeys(frontier))
+    return tuple(out), edge_scan_capped or depth_cut

code_atlas/impact/contract_analyzer.py

@@ -0,0 +1,104 @@
+"""Análise de contratos públicos por assinatura (Phase 4).
+
+NÃO é type-checker: compara a *forma* da assinatura persistida
+(``fts_occurrences.signature``). Classificações determinísticas;
+"potentially incompatible" ≠ "quebra comprovada" — a quebra exige
+consumidor incompatível demonstrado separadamente (fora do escopo).
+"""
+
+from __future__ import annotations
+
+import re
+
+from code_atlas.impact.contracts import (
+    ContractChange,
+    EvidenceStrength,
+    SymbolChange,
+    SymbolChangeKind,
+)
+
+_PARAM_RE = re.compile(r"\((.*)\)")
+_OPT_RE = re.compile(r"[=?]|\w+\s*[:=]")
+
+
+def _params(sig: str) -> list[str]:
+    m = _PARAM_RE.search(sig)
+    if not m:
+        return []
+    return [p.strip() for p in m.group(1).split(",") if p.strip()
+            and p.strip() not in ("self", "cls")]
+
+
+def _required(params: list[str]) -> list[str]:
+    """Obrigatórios: sem ``=``, sem ``?`` (TS), não *args/**kwargs."""
+    out = []
+    for p in params:
+        if p.startswith(("*", "/")) or p.startswith("..."):
+            continue
+        name = p.split(":")[0].split("=")[0].strip().rstrip("?")
+        if "=" not in p and not p.rstrip().endswith("?"):
+            out.append(name)
+    return out
+
+
+def classify_change(
+    sc: SymbolChange,
+) -> ContractChange | None:
+    """Classifica uma SymbolChange c/ assinaturas; None se sem contrato."""
+    old, new = sc.old_signature or "", sc.new_signature or ""
+    if sc.change == SymbolChangeKind.REMOVED:
+        return ContractChange(
+            symbol_key=sc.symbol_key,
+            classification="public-symbol-removed",
+            compatibility="potential-risk",
+            old_signature=old or None, new_signature=None,
+            strength=sc.strength,
+            detail="símbolo removido do grafo alvo")
+    if sc.change == SymbolChangeKind.ADDED:
+        return None  # adição não quebra contrato existente
+    if sc.change != SymbolChangeKind.SIGNATURE_CHANGED:
+        return None
+
+    po, pn = _params(old), _params(new)
+    ro, rn = set(_required(po)), set(_required(pn))
+    cls, compat, detail = "signature-changed", "indeterminate", ""
+
+    added_req = sorted(rn - ro)
+    removed_req = sorted(ro - rn)
+    if added_req:
+        cls, compat = "required-parameter-added", "potential-risk"
+        detail = f"novos obrigatórios: {', '.join(added_req)}"
+    elif removed_req:
+        cls, compat = "required-parameter-removed", "likely-compatible"
+        detail = ("remoção de parâmetro obrigatório é compatível "
+                  "para chamadores que o passavam por nome")
+    elif len(pn) > len(po):
+        cls, compat = "optional-parameter-added", "likely-compatible"
+        detail = "apenas parâmetros opcionais adicionados"
+    elif len(pn) < len(po):
+        cls, compat = "parameter-removed", "potential-risk"
+        detail = "parâmetro removido pode quebrar chamadas posicionais"
+    elif po != pn:
+        cls, compat = "parameter-renamed", "potential-risk"
+        detail = "ordem/nome de parâmetros diverge"
+    else:
+        cls, compat = "no-contract-impact", "no-contract-impact"
+        detail = "mesma forma de parâmetros"
+    if old.lstrip().startswith("async") != new.lstrip().startswith("async"):
+        cls, compat = "async-changed", "potential-risk"
+        detail = "mudança sync↔async"
+    return ContractChange(
+        symbol_key=sc.symbol_key, classification=cls,
+        compatibility=compat, old_signature=old or None,
+        new_signature=new or None,
+        strength=(EvidenceStrength.VERIFIED
+                  if compat != "indeterminate"
+                  else EvidenceStrength.POSSIBLE),
+        detail=detail)
+
+
+def analyze(
+    changes: tuple[SymbolChange, ...],
+) -> tuple[ContractChange, ...]:
+    out = [c for c in (classify_change(s) for s in changes) if c]
+    return tuple(out)

code_atlas/impact/contracts.py

@@ -0,0 +1,315 @@
+"""Contratos do Impact Engine (Cycle 5 Phase 1).
+
+Dois eixos separados — nunca um único ``confidence``:
+- ``FindingKind``: o que o achado É (mudança, dependência, risco, teste).
+- ``EvidenceStrength``: quão comprovado está (verified > supported >
+  possible > unknown). Uma aresta incerta não promove a cadeia.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+IMPACT_SCHEMA_VERSION = 1
+ANALYZER_VERSION = "impact-v1"
+
+
+class FindingKind(StrEnum):
+    OBSERVED_CHANGE = "observed_change"
+    DEPENDENCY = "dependency"
+    COMPATIBILITY_RISK = "compatibility_risk"
+    TEST_RELEVANCE = "test_relevance"
+    UNKNOWN = "unknown"
+
+
+class EvidenceStrength(StrEnum):
+    VERIFIED = "verified"
+    SUPPORTED = "supported"
+    POSSIBLE = "possible"
+    UNKNOWN = "unknown"
+
+
+class ChangeKind(StrEnum):
+    """Tipos de mudança de arquivo/símbolo (Phase 2+3)."""
+
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    RENAMED = "renamed"
+    COPIED = "copied"
+    MODE_CHANGED = "mode_changed"
+    TYPE_CHANGED = "type_changed"
+    BINARY = "binary"
+    UNAVAILABLE = "unavailable"
+
+
+class SymbolChangeKind(StrEnum):
+    """Classificação semântica por símbolo (Phase 3)."""
+
+    ADDED = "added"
+    REMOVED = "removed"
+    RENAMED = "renamed"
+    MOVED = "moved"
+    SIGNATURE_CHANGED = "signature_changed"
+    BODY_CHANGED = "body_changed"
+    DOC_CHANGED = "doc_changed"
+    NO_SEMANTIC_CHANGE = "no_semantic_change"
+    UNKNOWN = "unknown"
+
+
+class ImpactKind(StrEnum):
+    DIRECT = "direct"
+    TRANSITIVE = "transitive"
+    POSSIBLE = "possible"
+    UNKNOWN = "unknown"
+
+
+class RiskCategory(StrEnum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"
+    CRITICAL = "critical"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class FileChange:
+    """Uma entrada do ChangeSet (Phase 2)."""
+
+    kind: ChangeKind
+    old_path: str | None
+    new_path: str | None
+    old_hash: str | None = None
+    new_hash: str | None = None
+    similarity: int | None = None   # 0-100 em renomes/cópias git
+    binary: bool = False
+
+
+@dataclass(frozen=True)
+class ChangeSet:
+    """Conjunto de alterações entre duas revisões (Phase 2)."""
+
+    base_revision: str
+    target_revision: str
+    files: tuple[FileChange, ...]
+    source: str = "git"             # git | snapshots | explicit
+    dirty_worktree: bool = False
+    commit_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class SymbolChange:
+    """Mudança detectada num símbolo entre dois snapshots (Phase 3)."""
+
+    symbol_key: str                 # lang:kind:qname (mesma forma do search)
+    qualified_name: str
+    language: str
+    kind: str
+    change: SymbolChangeKind
+    strength: EvidenceStrength
+    old_signature: str | None = None
+    new_signature: str | None = None
+    old_path: str | None = None
+    new_path: str | None = None
+    old_occurrence_id: int | None = None
+    new_occurrence_id: int | None = None
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class ContractChange:
+    """Alteração de contrato público classificada (Phase 4)."""
+
+    symbol_key: str
+    classification: str             # ex.: required-parameter-added
+    compatibility: str              # potential-risk | likely-compatible
+                                    # | no-contract-impact | indeterminate
+    old_signature: str | None
+    new_signature: str | None
+    strength: EvidenceStrength
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class ImpactPath:
+    """Cadeia auditável origem→afetado (Phase 5)."""
+
+    origin_symbol_key: str
+    affected_symbol_key: str
+    hops: int
+    relation_ids: tuple[int, ...]
+    intermediate_keys: tuple[str, ...]
+    resolution_statuses: tuple[str, ...]
+    fully_verified: bool
+    reason: str
+    # lf-0120: refs tipadas por hop ("rel:<id>" = relations,
+    # "dom:<id>" = domain_relations) — os ids numéricos das duas
+    # tabelas compartilham espaço, então o prefixo preserva a
+    # proveniência quando o caminho mistura código e domínio.
+    edge_refs: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ImpactCandidate:
+    """Símbolo/arquivo potencialmente impactado (Phase 5)."""
+
+    symbol_key: str
+    qualified_name: str
+    language: str
+    kind: str
+    impact: ImpactKind
+    strength: EvidenceStrength
+    path: ImpactPath | None
+    source_path: str | None = None
+    occurrence_id: int | None = None
+    # lf-0078: estado do consumidor histórico no destino
+    # ("" | still_present | also_removed | unresolved_in_target)
+    consumer_state: str = ""
+    # lf-0120 (Cycle 7 Phase 12): tipo do nó impactado — ``"symbol"``
+    # para símbolo de código, ``"domain"`` para entidade de domínio
+    # (o kind então carrega o ``DomainEntityKind``: data_table,
+    # spark_job…). ``symbol_key`` de entidade é a ``identity_key``
+    # canônica ``dom:…`` e ``language`` é o domínio produtor.
+    node_type: str = "symbol"
+    # Ocorrência de ``domain_entity_occurrences`` — espaço de ids
+    # separado de ``occurrence_id`` (que é sempre symbol_occurrences).
+    domain_occurrence_id: int | None = None
+    # Dependências não-traversáveis do nó (alvos ``unresolved`` /
+    # ``ambiguous`` / ``external`` sem endpoint concreto) — contam como
+    # incerteza, nunca como blast confirmado. Formas curtas estáveis:
+    # ``"WRITES_TO→<texto> (unresolved)"``.
+    uncertain_deps: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TestCandidate:
+    """Teste candidato relacionado à mudança (Phase 7)."""
+
+    test_file: str
+    test_symbol: str | None
+    relationship: str               # direct | transitive | heuristic | unknown
+    reason: str
+    strength: EvidenceStrength
+    occurrence_id: int | None = None
+    revision: str = ""              # lf-0080: "base" | "target" | ""
+
+
+@dataclass(frozen=True)
+class RiskAssessment:
+    """Avaliação determinística de risco (Phase 6)."""
+
+    category: RiskCategory
+    uncertainty: str                # low|moderate|high — separado do risco
+    reasons: tuple[str, ...]
+    formula_version: str = "risk-rules-v1"
+
+
+@dataclass(frozen=True)
+class ImpactDiagnostic:
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ImpactLimits:
+    """Limites da análise — cada um tem uma razão de truncamento.
+
+    Semântica medida (cycle-8.1, lf-0151): um bound que descarta
+    trabalho real é declarado em ``ImpactResult.truncation_reasons``
+    (e refletido em ``truncated``) — nunca silencioso.
+
+    - ``max_depth``: hops máximos por caminho. Um candidato emitido
+      exatamente na fronteira (``hops == max_depth``) não é expandido;
+      se ele ainda tem vizinhos atravessáveis (ou incerteza de domínio
+      não contada) o corte é declarado ``max-depth-frontier``.
+    - ``max_nodes``: cap de scan de vizinhos **por expansão** (rows de
+      ``relations``/``domain_relations`` lidas por nó, prefixo
+      determinístico ``ORDER BY id``). Quando a varredura de um nó
+      enche esse limite, rows além dele nunca são vistas — o corte é
+      ``max-nodes-edge-scan``. Não é um bound global de nós
+      visitados (o nome é preservado por compatibilidade).
+    - ``max_paths``: cap de emissão — o blast para quando
+      ``len(candidates) >= max_paths`` → ``max-paths``.
+    - ``max_changes``: cap do diff de símbolos → ``max-changes``.
+    """
+
+    max_depth: int = 4
+    max_nodes: int = 500
+    max_paths: int = 50
+    max_changes: int = 500
+
+
+@dataclass(frozen=True)
+class ImpactRequest:
+    """Pedido de análise — todas as superfícies (CLI/MCP) viram isto."""
+
+    repository_root: str
+    base_revision: str = ""         # HEAD~1, sha, branch, snapshot:N
+    target_revision: str = ""       # vazio = worktree
+    symbol: str | None = None       # seleção explícita (também aceita
+                                    # ref de entidade — ver ``entity``)
+    file: str | None = None
+    # lf-0120 (Cycle 7 Phase 12): seed de entidade de domínio — a
+    # análise passa a responder "se esta tabela/job/recurso mudar".
+    # Formas aceitas: ``identity_key`` canônica ``dom:…``, row id
+    # (``entity:N``/``id:N``/``N``), ``display()`` (ex.:
+    # ``pyspark:staging.orders``) ou nome qualificado
+    # (``staging.orders``, ``orders``). ``symbol`` também funciona como
+    # seed de entidade quando casa — fiação mínima para handlers que já
+    # expõem ``symbol`` (API/CLI/MCP não precisam mudar).
+    entity: str | None = None
+    base_snapshot_id: int | None = None
+    target_snapshot_id: int | None = None
+    include_possible: bool = True
+    known_only: bool = False
+    limits: ImpactLimits = field(default_factory=ImpactLimits)
+
+
+@dataclass(frozen=True)
+class ImpactResult:
+    """Resposta canônica — Phase 1 exige todos os campos identificáveis."""
+
+    schema_version: int
+    analyzer_version: str
+    repository: str
+    base_revision: str
+    target_revision: str
+    base_snapshot_id: int | None
+    target_snapshot_id: int | None
+    change_set: ChangeSet | None
+    symbol_changes: tuple[SymbolChange, ...]
+    contract_changes: tuple[ContractChange, ...]
+    impacts: tuple[ImpactCandidate, ...]
+    test_candidates: tuple[TestCandidate, ...]
+    risk: RiskAssessment
+    unknown_coverage: tuple[str, ...]
+    # ``truncated`` é a união de ``truncation_reasons``: True sse
+    # algum bound descartou trabalho real — nenhuma análise incompleta
+    # se apresenta como exaustiva (cycle-8.1 Phase 8 / lf-0151).
+    truncated: bool
+    diagnostics: tuple[ImpactDiagnostic, ...]
+    # Vocabulário estável e ordenado de bounds que cortaram a análise:
+    # - ``max-paths`` — emissão do blast atingiu ``max_paths``;
+    # - ``max-changes`` — diff de símbolos atingiu ``max_changes``;
+    # - ``max-nodes-edge-scan`` — scan de vizinhos de um nó encheu
+    #   ``max_nodes`` (prefixo determinístico ``ORDER BY id``);
+    # - ``max-depth-frontier`` — nó emitido em ``hops == max_depth``
+    #   ainda tinha trabalho atravessável e não foi expandido;
+    # - ``symbol-seed-limit`` — lookup de seed what-if atingiu o cap
+    #   de ocorrências;
+    # - ``test-candidates`` — seleção de testes atingiu o cap.
+    # ``truncation_reason``/``max_depth_reached``/``max_nodes_reached``
+    # do Phase 8 mapeiam aqui; ``max_edges``/``query_budget`` não
+    # existem como bounds separados no engine (documentado em
+    # ``docs/impact-truncation-integrity.md``). Aditivo — schema v1.
+    truncation_reasons: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ImpactReport:
+    """Envelope de relatório (Phase 9) — renderers JSON/MD/CLI."""
+
+    schema_version: int
+    result: ImpactResult
+    format: str                     # json | markdown | cli