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

code_atlas/search/hybrid.py

@@ -0,0 +1,151 @@
+"""Fusão híbrida de candidatos — Reciprocal Rank Fusion (lf-0038 /
+Cycle 4 Ph5).
+
+Pipeline: lexical + structural + graph (vetorial quando existir) →
+dedup por identidade canônica do símbolo (``qualified_name``)
+preservando a participação e as ocorrências de cada estratégia →
+score RRF → página.
+
+- ``RRF_K = 60``: constante padrão da literatura (Cormack et al. 2009)
+  — documentada; variantes só com evidência de ganho.
+- Scores crus de backends distintos NUNCA são comparados — RRF opera
+  sobre POSIÇÕES (rank), não sobre score.
+- Sem provider vetorial, ``hybrid`` funciona sobre as 3 estratégias
+  reais — degradação honesta, declarada no hit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from code_atlas.search.contracts import SearchHit
+from code_atlas.search.intent import QueryIntent
+
+RRF_K = 60
+RANKING_VERSION_HYBRID = "rrf-k60-v2"
+
+# Fatores do rerank task-aware (lf-0050) — constantes documentadas,
+# NUNCA arbitrárias: qualquer alteração exige benchmark em
+# eval-report (comparação v1-vs-v2 no mesmo dataset).
+BOOST_EXACT_QNAME = 1.5   # último segmento do qname == query (locate)
+BOOST_DIRECTION = 1.25    # evidência de passo na direção do intent
+DEMOTE_NO_EVIDENCE = 0.9  # hit sem nenhuma evidência explicável
+
+
+def canonical_key(h: SearchHit) -> str:
+    """Identidade canônica do símbolo (lf-0050).
+
+    Não basta ``qualified_name``: identidades diferentes com o mesmo
+    nome (linguagem/kind distintos) NÃO podem fundir. ``qname`` já
+    carrega escopo (path/módulo); repo+snapshot são fixos por
+    consulta (isolamento garantido a montante)."""
+    return f"{h.language}:{h.kind}:{h.qualified_name}"
+
+
+@dataclass(frozen=True)
+class FusedCandidate:
+    """Símbolo deduplicado com participação por estratégia."""
+
+    symbol_key: str   # canonical_key composta (lang:kind:qname)
+    qualified_name: str
+    hits: tuple[SearchHit, ...]        # ocorrências por estratégia
+    ranks: dict[str, int]              # strategy → melhor posição (1-based)
+    rrf_score: float
+    rerank_score: float = 0.0          # score final pós-rerank (0 = =rrf)
+    rerank_reasons: tuple[str, ...] = ()
+
+
+def fuse(
+    rankings: dict[str, list[SearchHit]],
+    *,
+    k: int = RRF_K,
+    weights: dict[str, float] | None = None,
+    intent: QueryIntent | None = None,
+    query: str = "",
+) -> list[FusedCandidate]:
+    """RRF sobre rankings de várias estratégias.
+
+    ``rankings``: strategy → hits ordenados (posição = rank).
+    Dedup por ``canonical_key`` preserva evidências: hits de todas as
+    estratégias ficam em ``hits`` (nunca descartados); o primário é o
+    de melhor rank (menor occurrence_id em empate — determinístico).
+    ``intent``/``query`` ativam o rerank task-aware — sem eles o
+    ranking é RRF puro (v1-compatível)."""
+    w = weights or {}
+    by_sym: dict[str, dict[str, int]] = {}
+    hits_by_sym: dict[str, list[SearchHit]] = {}
+    for strategy, hits in rankings.items():
+        for pos, h in enumerate(hits, start=1):
+            key = canonical_key(h)
+            ranks = by_sym.setdefault(key, {})
+            if pos < ranks.get(strategy, 1 << 30):
+                ranks[strategy] = pos
+            hits_by_sym.setdefault(key, []).append(h)
+    out: list[FusedCandidate] = []
+    for sym, ranks in by_sym.items():
+        score = sum(
+            w.get(s, 1.0) / (k + rank) for s, rank in ranks.items()
+        )
+        primaries = sorted(
+            hits_by_sym[sym],
+            key=lambda h: (min(ranks.values()), h.occurrence_id),
+        )
+        out.append(FusedCandidate(
+            symbol_key=sym,
+            qualified_name=primaries[0].qualified_name,
+            hits=tuple(primaries),
+            ranks=ranks,
+            rrf_score=score,
+        ))
+    ranked = [_rerank(c, intent, query) for c in out]
+    ranked.sort(key=lambda c: (
+        -(c.rerank_score or c.rrf_score), c.symbol_key))
+    return ranked
+
+
+def _rerank(
+    c: FusedCandidate, intent: QueryIntent | None, query: str,
+) -> FusedCandidate:
+    """Rerank task-aware — multiplicadores documentados, explicados
+    em ``rerank_reasons``. Sem intent → RRF puro inalterado."""
+    score = c.rrf_score
+    reasons: list[str] = []
+    primary = c.hits[0]
+    if query and primary.qualified_name.split(".")[-1] == query:
+        score *= BOOST_EXACT_QNAME
+        reasons.append(f"exact-qname x{BOOST_EXACT_QNAME}")
+    if intent is not None and intent.direction != "both":
+        for h in c.hits:
+            if any(f"dir={intent.direction}" in e for e in h.evidence):
+                score *= BOOST_DIRECTION
+                reasons.append(f"direction={intent.direction} "
+                               f"x{BOOST_DIRECTION}")
+                break
+    if not any(h.evidence for h in c.hits):
+        score *= DEMOTE_NO_EVIDENCE
+        reasons.append(f"no-evidence x{DEMOTE_NO_EVIDENCE}")
+    return replace(c, rerank_score=round(score, 9),
+                   rerank_reasons=tuple(reasons))
+
+
+def to_search_hit(c: FusedCandidate) -> SearchHit:
+    """Projeta o candidato fundido para ``SearchHit`` explicável."""
+    primary = c.hits[0]
+    strategies = tuple(sorted(c.ranks))
+    evidence = (
+        *(f"{s}:rank={c.ranks[s]}" for s in strategies),
+        f"rrf={c.rrf_score:.6f}",
+        *(f"rerank={r}" for r in c.rerank_reasons),
+    )
+    return SearchHit(
+        occurrence_id=primary.occurrence_id,
+        qualified_name=c.qualified_name,
+        kind=primary.kind,
+        language=primary.language,
+        path=primary.path,
+        span=primary.span,
+        score=round(c.rrf_score, 6),
+        strategy="hybrid",
+        matched_fields=strategies,
+        evidence=evidence,
+    )

code_atlas/search/intent.py

@@ -0,0 +1,48 @@
+"""Classificação determinística de intenção de consulta (lf-0049).
+
+Sem LLM — heurística por palavras-chave configurável. Produz o tipo
+de tarefa e a direção de travessia preferida no grafo:
+- "find-consumers" → incoming (quem chama/importa o símbolo)
+- "explain-dependencies" → outgoing (o que o símbolo usa)
+- demais → both (exploração simétrica)
+
+A classificação é deliberadamente conservadora: na dúvida, ``both``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# padrões → (task_type, direction). Ordem importa: primeiro match vence.
+_RULES: tuple[tuple[str, str, str], ...] = (
+    (r"\b(who calls|callers?|consumers?|referenc|usado por|"
+     r"quem chama|incoming)\b", "find-consumers", "incoming"),
+    (r"\b(depend\w*|import\w*|callee\w*|outgoing|delega\w*|"
+     r"o que .{0,20}usa)\b", "explain-dependencies", "outgoing"),
+    (r"\b(flow|fluxo|architect|arquitet|component|pipeline|"
+     r"camadas?)\b", "understand-component", "both"),
+    (r"\b(test|tests?|spec|coverage)\b", "find-tests", "incoming"),
+    (r"\b(bug|falha|fail|erro|crash|debug|defeito)\b",
+     "investigate-failure", "incoming"),
+)
+
+
+@dataclass(frozen=True)
+class QueryIntent:
+    """Intenção classificada — determinística, explicável."""
+
+    task_type: str           # find-consumers|explain-dependencies|...
+    direction: str           # incoming|outgoing|both
+    matched_rule: str        # padrão que casou (ou "" = default)
+
+
+def classify(query: str) -> QueryIntent:
+    """Classifica a consulta. Sem match → locate/both (default seguro)."""
+    q = query.lower()
+    for pattern, task, direction in _RULES:
+        if re.search(pattern, q):
+            return QueryIntent(task_type=task, direction=direction,
+                               matched_rule=pattern)
+    return QueryIntent(task_type="locate", direction="both",
+                       matched_rule="")

code_atlas/search/lexical.py

@@ -0,0 +1,176 @@
+"""Busca lexical snapshot-scoped via FTS5 ``fts_occurrences`` (lf-0036).
+
+- Rowid do FTS = id da ``symbol_occurrences`` → join direto para
+  span/path/símbolo lógico.
+- ``snapshot_id`` UNINDEXED garante isolamento: só o snapshot READY
+  corrente é consultado.
+- Coluna ``terms`` carrega identificadores pré-tokenizados
+  (``search/tokenizer.py``) — camelCase/snake_case recuperáveis por
+  fragmento.
+- Ranking: ``bm25`` nativo do FTS5 com pesos por coluna
+  (name > terms > signature > docstring > path).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from code_atlas.search.contracts import (
+    SearchDiagnostic,
+    SearchHit,
+    SearchRequest,
+)
+from code_atlas.search.tokenizer import fts_escape, split_identifier
+
+# Pesos bm25 por coluna indexada (ordem do CREATE VIRTUAL TABLE):
+# snapshot_id(unindexed), name, terms, signature, docstring, path,
+# language(unindexed), kind(unindexed) → 8 posições.
+_BM25_WEIGHTS = "0.0, 10.0, 6.0, 2.0, 1.0, 1.0, 0.0, 0.0"
+
+_MAX_LIMIT = 200
+
+
+def fts_query(query: str) -> str | None:
+    """Monta a expressão MATCH: fragmentos tokenizados OU exato cru.
+
+    - ``foo*`` → prefixo em ``terms``
+    - ``pkg.util.helper`` → tokens por segmento (FTS já separa pontos)
+    - ``processCustomerOrders`` → exato em ``name`` + fragmentos em
+      ``terms``
+    """
+    q = query.strip()
+    if not q:
+        return None
+    if q.endswith("*") and len(q) > 1:
+        stem = q[:-1]
+        toks = split_identifier(stem)
+        if toks:
+            return f"terms : {fts_escape(toks[-1])}*"
+        return f"terms : {fts_escape(stem)}*"
+    toks = split_identifier(q)
+    if not toks:
+        return None
+    or_terms = " OR ".join(fts_escape(t) for t in toks)
+    return (
+        f"{{name terms signature docstring}} : ({or_terms})"
+        f" OR name : {fts_escape(q)}"
+    )
+
+
+class LexicalSearch:
+    """Engine lexical — só lê; erros viram diagnósticos, nunca raise."""
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def search(
+        self,
+        req: SearchRequest,
+        snapshot_id: int,
+        offset: int = 0,
+    ) -> tuple[tuple[SearchHit, ...], int, tuple[SearchDiagnostic, ...]]:
+        """Retorna (hits, total_estimado, diagnostics)."""
+        match = fts_query(req.query)
+        if match is None:
+            return (), 0, (
+                SearchDiagnostic(
+                    code="empty-query",
+                    severity="warning",
+                    message="query vazia após tokenização",
+                ),
+            )
+        limit = max(1, min(req.limit or 20, _MAX_LIMIT))
+        where = [
+            "fts_occurrences MATCH ?",
+            "f.snapshot_id = ?",
+        ]
+        params: list[object] = [match, snapshot_id]
+        if req.language:
+            where.append("f.language = ?")
+            params.append(req.language)
+        if req.kind:
+            where.append("f.kind = ?")
+            params.append(req.kind)
+        if req.path:
+            where.append("sf.relative_path LIKE ? ESCAPE '\\'")
+            params.append(f"%{_esc_like(req.path)}%")
+        base = (
+            "FROM fts_occurrences f"
+            " JOIN symbol_occurrences o ON o.id = f.rowid"
+            " JOIN source_files sf ON sf.id = o.source_file_id"
+            " JOIN symbols s ON s.id = o.logical_symbol_id"
+        )
+        where_sql = " AND ".join(where)
+        # SQL composto em variável nomeada — auditoria AST exige que o
+        # primeiro arg de execute() seja nome/literal, nunca expressão.
+        count_sql = "SELECT COUNT(*) " + base + " WHERE " + where_sql
+        select_sql = (
+            "SELECT f.rowid AS occ_id, s.qualified_name, f.kind,"
+            " f.language, sf.relative_path,"
+            " o.span_start, o.span_end, o.line, o.col,"
+            f" bm25(fts_occurrences, {_BM25_WEIGHTS}) AS score "
+            + base
+            + " WHERE "
+            + where_sql
+            + " ORDER BY score LIMIT ? OFFSET ?"
+        )
+        try:
+            total = int(
+                self._conn.execute(count_sql, params).fetchone()[0]
+            )
+            rows = self._conn.execute(
+                select_sql, [*params, limit, offset]
+            ).fetchall()
+        except sqlite3.OperationalError as exc:
+            return (), 0, (
+                SearchDiagnostic(
+                    code="fts-query-error",
+                    severity="error",
+                    message=f"MATCH inválida: {exc}",
+                ),
+            )
+        hits = tuple(
+            SearchHit(
+                occurrence_id=int(r["occ_id"]),
+                qualified_name=str(r["qualified_name"]),
+                kind=str(r["kind"]),
+                language=str(r["language"]),
+                path=str(r["relative_path"]),
+                span=(
+                    {
+                        "start_byte": r["span_start"],
+                        "end_byte": r["span_end"],
+                        "line": r["line"],
+                        "col": r["col"],
+                    }
+                    if r["span_start"] is not None
+                    else None
+                ),
+                score=round(-float(r["score"]), 6),  # bm25 menor = melhor
+                strategy="lexical",
+                matched_fields=_matched_fields(req.query, r),
+                evidence=(f"occ:{int(r['occ_id'])}",),
+            )
+            for r in rows
+        )
+        return hits, total, ()
+
+
+def _matched_fields(query: str, row: sqlite3.Row) -> tuple[str, ...]:
+    """Explicação aproximada: quais campos contêm tokens da query.
+
+    Honesta: é um pós-checagem em Python, não o highlight do FTS —
+    serve para explicar o hit sem custo de ``highlight()`` por linha.
+    """
+    toks = set(split_identifier(query))
+    if not toks:
+        return ()
+    fields: list[str] = []
+    qname_toks = set(split_identifier(str(row["qualified_name"])))
+    if toks & qname_toks:
+        fields.append("qualified_name")
+    return tuple(fields)
+
+
+def _esc_like(term: str) -> str:
+    return term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")