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

code_atlas/domains/api/common.py

@@ -0,0 +1,308 @@
+"""Helpers compartilhados do adapter ``domains.api`` (lf-0114).
+
+Utilitários puros de texto/sintaxe: extração de lista de argumentos a
+partir de uma posição de call-site (span do callee vindo do Tree-sitter
+via ``ParseResult``), classificação de literais de string (Python/TS),
+split de URL **sem** ``urllib`` (barrado fora de ``code_atlas.api`` pela
+auditoria de rede lf-0086), nomes de módulo derivados de path e spans de
+linha. Nenhuma I/O, nenhuma importação de ``tree_sitter``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from code_atlas.parsers.contracts import SourceSpan
+
+_ARGS_MAX = 16_384
+_ARGS_MAX_ITEMS = 64
+
+PY_MODULE_SUFFIXES = (".py", ".pyi")
+TS_MODULE_SUFFIXES = (".d.ts", ".tsx", ".ts", ".jsx", ".mjs", ".cjs", ".js")
+
+
+# -- módulos / nomes ----------------------------------------------------
+
+
+def module_name(path: str, suffixes: tuple[str, ...]) -> str:
+    """``app/routers.py`` → ``app.routers``; ``web/x.d.ts`` → ``web.x``."""
+    p = path
+    for suf in suffixes:
+        if p.endswith(suf):
+            p = p[: -len(suf)]
+            break
+    parts = [seg for seg in p.split("/") if seg]
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts) or path
+
+
+def slugify(text: str) -> str:
+    """Slug determinístico para nomes de serviço (``Pet Store`` → ``pet-store``)."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug[:64]
+
+
+def join_paths(prefix: str, path: str) -> str:
+    """Junta prefixo + path de endpoint sem duplicar ``/``."""
+    if not prefix:
+        return path or "/"
+    if not path:
+        return prefix
+    return prefix.rstrip("/") + "/" + path.lstrip("/")
+
+
+# -- offsets / spans ------------------------------------------------------
+
+
+def line_offsets(text: str) -> list[int]:
+    """Offset de **char** do início de cada linha (1-based pelo índice)."""
+    offs = [0]
+    for i, ch in enumerate(text):
+        if ch == "\n":
+            offs.append(i + 1)
+    return offs
+
+
+def byte_offsets(text: str) -> list[int]:
+    """Offset de **byte UTF-8** do início de cada linha (alinhado a SourceSpan)."""
+    offs = [0]
+    total = 0
+    for raw in text.splitlines(keepends=True):
+        total += len(raw.encode("utf-8"))
+        offs.append(total)
+    return offs
+
+
+def line_span(text: str, byte_offs: list[int], lineno: int) -> SourceSpan | None:
+    """``SourceSpan`` da linha inteira (sem o ``\\n``); None se fora de faixa."""
+    if lineno < 1 or lineno > len(byte_offs):
+        return None
+    start = byte_offs[lineno - 1]
+    lines = text.splitlines()
+    if lineno > len(lines):
+        return None
+    raw = lines[lineno - 1]
+    end = start + len(raw.encode("utf-8"))
+    ncols = len(raw.encode("utf-8"))
+    return SourceSpan(
+        start_byte=start, end_byte=end,
+        start_line=lineno, start_col=0,
+        end_line=lineno, end_col=ncols,
+    )
+
+
+def byte_to_char(text: str, byte_off: int) -> int:
+    """Converte offset de byte UTF-8 em offset de char ``str``.
+
+    Necessário porque spans do Tree-sitter são byte offsets e o fatiamento
+    de argumentos opera sobre ``str`` decodificado.
+    """
+    return len(text.encode("utf-8")[:byte_off].decode("utf-8", "replace"))
+
+
+# -- argumentos de call-site -------------------------------------------------
+
+
+def _quote_step(ch: str, quote: str) -> tuple[bool, str]:
+    """Passo de scan dentro de aspas → ``(escapou?, quote_atual)``."""
+    if ch == "\\":
+        return True, quote
+    if ch == quote:
+        return False, ""
+    return False, quote
+
+
+def scan_args(text: str, open_paren: int) -> str | None:
+    """Conteúdo interno de ``(...)`` começando em ``open_paren``.
+
+    Balanceado e ciente de aspas (``'`` ``"`` `` ` ``) com escapes —
+    não é um parser de expressões: cobre o caso comum de call-sites de
+    rota/cliente. Limitado a ``_ARGS_MAX`` chars; None se desbalanceado
+    ou além do limite.
+    """
+    if open_paren >= len(text) or text[open_paren] != "(":
+        return None
+    depth = 0
+    quote = ""
+    esc = False
+    i = open_paren
+    while i < len(text) and i - open_paren <= _ARGS_MAX:
+        ch = text[i]
+        if esc:
+            esc = False
+        elif quote:
+            esc, quote = _quote_step(ch, quote)
+        elif ch in "'\"`":
+            quote = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+            if depth == 0:
+                return text[open_paren + 1:i]
+        i += 1
+    return None
+
+
+def args_after(text: str, pos: int) -> str | None:
+    """Argumentos logo após ``pos`` (fim do callee): pula espaço, exige ``(``."""
+    i = pos
+    while i < len(text) and text[i] in " \t":
+        i += 1
+    if i < len(text) and text[i] == "(":
+        return scan_args(text, i)
+    return None
+
+
+def iter_args(args: str) -> Iterator[str]:
+    """Itera argumentos top-level — ciente de aspas e profundidade."""
+    depth = 0
+    quote = ""
+    esc = False
+    emitted = False
+    cur: list[str] = []
+    for ch in args:
+        if esc:
+            cur.append(ch)
+            esc = False
+            continue
+        if quote:
+            cur.append(ch)
+            esc, quote = _quote_step(ch, quote)
+            continue
+        if ch in "'\"`":
+            quote = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            emitted = True
+            yield "".join(cur).strip()
+            cur = []
+            continue
+        cur.append(ch)
+    tail = "".join(cur).strip()
+    if tail or emitted:
+        yield tail
+
+
+def split_args(args: str) -> list[str]:
+    """Split top-level por vírgula — limitado a ``_ARGS_MAX_ITEMS``."""
+    out: list[str] = []
+    for a in iter_args(args):
+        out.append(a)
+        if len(out) >= _ARGS_MAX_ITEMS:
+            break
+    return out
+
+
+def kwarg(args: list[str], name: str) -> str | None:
+    """Valor textual de ``name=...`` numa lista de argumentos."""
+    prefix = f"{name}="
+    for a in args:
+        a = a.strip()
+        if a.startswith(prefix):
+            return a[len(prefix):].strip()
+    return None
+
+
+# -- literais de string -----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class StrLiteral:
+    """Literal de string classificado."""
+
+    value: str
+    dynamic: bool  # f-string com ``{}`` ou template ``${}`` — nunca resolve
+
+
+_PY_STR = re.compile(r"^([rRbBfFuU]{0,3})('''|\"\"\"|'|\")", re.S)
+
+
+def _quoted_end(tok: str, start: int, quote: str) -> int:
+    """Índice do primeiro ``quote`` não-escapado >= start; -1 se ausente."""
+    i = start
+    while i < len(tok):
+        if tok[i] == "\\":
+            i += 2
+            continue
+        if tok.startswith(quote, i):
+            return i
+        i += 1
+    return -1
+
+
+def parse_str_literal(tok: str, *, lang: str) -> StrLiteral | None:
+    """Classifica um token como literal de string.
+
+    ``lang`` = ``"py"`` (prefixos r/b/f/u, aspas simples/duplas/triplas)
+    ou ``"ts"`` (aspas simples/duplas/backtick). Devolve ``StrLiteral`` —
+    ``dynamic=True`` quando o literal carrega interpolação (``f".."`` /
+    template ``${}``); None quando o token não é literal puro —
+    identificador, expressão, concatenação (``"a" + "b"`` não é literal
+    estático e nunca deve ser resolvido como URL).
+    """
+    tok = tok.strip()
+    if not tok:
+        return None
+    if lang == "py":
+        m = _PY_STR.match(tok)
+        if not m:
+            return None
+        prefix, quote = m.group(1).lower(), m.group(2)
+        if "b" in prefix:
+            return None  # bytes literal — não é URL
+        close = _quoted_end(tok, m.end(), quote)
+        if close < 0 or tok[close + len(quote):].strip():
+            return None  # sem fechamento, ou concatenação após o literal
+        body = tok[m.end():close]
+        dynamic = "f" in prefix and ("{" in body)
+        return StrLiteral(value=body, dynamic=dynamic)
+    # ts
+    q = tok[0]
+    if q in ("'", '"', "`"):
+        close = _quoted_end(tok, 1, q)
+        if close < 0 or tok[close + 1:].strip():
+            return None
+        body = tok[1:close]
+        return StrLiteral(value=body, dynamic=(q == "`" and "${" in body))
+    return None
+
+
+# -- URLs (sem urllib — fronteira lf-0086) ----------------------------------
+
+
+_SCHEME_RE = re.compile(r"^([a-zA-Z][a-zA-Z0-9+.-]*)://(.*)$")
+
+
+def url_path(url: str) -> str:
+    """Componente de path de uma URL absoluta/relativa.
+
+    Split mínimo por string — ``urllib.parse`` é proibido fora de
+    ``code_atlas.api`` (auditoria lf-0086). URLs com ``{var}`` (templates
+    de servidor OpenAPI) passam intactas.
+    """
+    s = url.strip()
+    m = _SCHEME_RE.match(s)
+    if m:
+        rest = m.group(2)
+        slash = rest.find("/")
+        path = rest[slash:] if slash >= 0 else "/"
+    else:
+        path = s
+    for sep in ("?", "#"):
+        cut = path.find(sep)
+        if cut >= 0:
+            path = path[:cut]
+    return path or "/"
+
+
+def is_absolute_url(url: str) -> bool:
+    """True para ``scheme://`` absoluta (http/https/ws)."""
+    m = _SCHEME_RE.match(url.strip())
+    return bool(m and m.group(1).lower() in ("http", "https", "ws", "wss"))

code_atlas/domains/api/consumers.py

@@ -0,0 +1,224 @@
+"""Chamadas HTTP cliente em código — consumidores de endpoints (lf-0114).
+
+Somente **literais estáticos** viram URL: ``fetch("/x")``,
+``requests.get("http://a/b")``, ``axios.post(...)``. Qualquer forma
+dinâmica (f-string, template ``${}``, variável, concatenação, objeto de
+config sem ``url`` literal) vira marcador ``dynamic:<expr>`` com status
+``unresolved`` — nunca resolvido, nunca inventado.
+
+Vínculo literal-URL ↔ contrato/endpoint local é da Phase 9
+(cross-domain resolution): aqui emitimos ``CALLS_ENDPOINT`` com status
+``unresolved`` (URL relativa) ou ``external`` (URL absoluta
+``http(s)://`` fora do snapshot) + ``candidates`` com endpoints locais
+cujo ``full_path`` casa textualmente — dado de pista, não resolução.
+
+Spans/callees vêm do ``ParseResult`` (AST real) para .py/.ts; ``.js`` usa
+regex-static por linha (``heuristic``). O método HTTP vai em ``notes``
+da evidência (``method=POST``) quando declarado literalmente.
+"""
+
+from __future__ import annotations
+
+import re
+
+from code_atlas.contracts.enums import ConfidenceClass, ResolutionStatus
+from code_atlas.domains.api import common
+from code_atlas.domains.api.emit import Emit
+from code_atlas.domains.identity import DomainIdentity
+from code_atlas.domains.model import DomainRelationKind
+from code_atlas.parsers.contracts import ParseResult, SourceSpan
+
+# callee → índice do argumento que carrega a URL.
+PY_URL_ARG: dict[str, int] = {
+    "requests.get": 0, "requests.post": 0, "requests.put": 0,
+    "requests.delete": 0, "requests.patch": 0, "requests.head": 0,
+    "requests.options": 0, "requests.request": 1,
+    "httpx.get": 0, "httpx.post": 0, "httpx.put": 0,
+    "httpx.delete": 0, "httpx.patch": 0, "httpx.head": 0,
+    "httpx.options": 0, "httpx.request": 1,
+    "urllib.request.urlopen": 0,
+}
+TS_URL_ARG: dict[str, int] = {
+    "fetch": 0, "axios": 0, "axios.request": 0,
+    "axios.get": 0, "axios.post": 0, "axios.put": 0,
+    "axios.delete": 0, "axios.patch": 0, "axios.head": 0,
+    "axios.options": 0,
+}
+_AXIOS_URL_PROP = re.compile(r"\burl\s*:\s*('([^']*)'|\"([^\"]*)\")")
+_METHOD_PROP = re.compile(r"\bmethod\s*:\s*['\"](\w+)['\"]")
+_JS_CALL = re.compile(r"\b(fetch|axios(?:\.\w+)?)\s*\(")
+
+
+def _method_note(callee: str, args: list[str], url_idx: int) -> str:
+    """Método HTTP declarado literalmente — vai em ``evidence.notes``."""
+    method = ""
+    if url_idx == 1 and args:  # requests.request("GET", url)
+        lit = common.parse_str_literal(args[0], lang="py")
+        if lit and not lit.dynamic:
+            method = lit.value.upper()
+    elif callee == "fetch" and len(args) > 1:
+        m = _METHOD_PROP.search(args[1])
+        if m:
+            method = m.group(1).upper()
+    elif callee.startswith("axios."):
+        method = callee.rsplit(".", 1)[-1].upper()
+        if method == "REQUEST":
+            method = ""
+    elif callee.startswith(("requests.", "httpx.")):
+        method = callee.rsplit(".", 1)[-1].upper()
+    return f"method={method}" if method else ""
+
+
+def _candidates(sink: Emit, url: str) -> tuple[DomainIdentity, ...]:
+    """Endpoints locais cujo path casa — pista para Phase 9, não resolução."""
+    path = common.url_path(url)
+    found: list[DomainIdentity] = []
+    seen: set[str] = set()
+    for ident in sink.endpoint_paths.get(path, ()):
+        key = ident.logical_key()
+        if key not in seen:
+            seen.add(key)
+            found.append(ident)
+    return tuple(found)
+
+
+def emit_call(
+    *,
+    sink: Emit,
+    path: str,
+    caller: str,
+    callee: str,
+    args_text: str | None,
+    url_idx: int,
+    span: SourceSpan | None,
+    content_hash: str,
+    confidence: ConfidenceClass,
+    lang: str,
+) -> None:
+    """Uma call-site HTTP → ``CALLS_ENDPOINT`` com estado honesto."""
+    args = common.split_args(args_text or "")
+    if len(args) <= url_idx:
+        sink.diag(
+            "call-args-unparsed", "info",
+            f"{callee}(...) without readable args at {path}",
+            path,
+        )
+        return
+    token = args[url_idx]
+    # axios({url: "/x", method: "post"}) — objeto de config com url literal.
+    if token.startswith("{") and callee.startswith("axios"):
+        m = _AXIOS_URL_PROP.search(token)
+        if m:
+            token = m.group(1)
+    lit = common.parse_str_literal(token, lang=lang)
+    notes = _method_note(callee, args, url_idx)
+    evi = sink.evi(path, content_hash, span, notes)
+
+    if lit is None or lit.dynamic:
+        marker = (lit.value if lit else token).strip()[:80]
+        sink.relation(
+            relation_type=DomainRelationKind.CALLS_ENDPOINT,
+            path=path,
+            from_symbol=caller,
+            to_unresolved=f"dynamic:{marker}",
+            resolution=sink.resolution(
+                ResolutionStatus.UNRESOLVED, ConfidenceClass.HEURISTIC,
+                unresolved_text=f"dynamic:{marker}",
+            ),
+            span=span,
+            evidence=(evi,),
+        )
+        sink.diag(
+            "dynamic-url", "info",
+            f"{callee} call with dynamic URL marker — never resolved "
+            f"({marker[:60]!r})",
+            path,
+        )
+        sink.bump("consumer_calls_dynamic")
+        return
+
+    url = lit.value
+    if not url.strip():
+        sink.diag(
+            "empty-url", "warning",
+            f"{callee} call with empty URL literal", path,
+        )
+        return
+    candidates = _candidates(sink, url)
+    if common.is_absolute_url(url):
+        status = ResolutionStatus.EXTERNAL
+    else:
+        status = ResolutionStatus.UNRESOLVED
+    sink.relation(
+        relation_type=DomainRelationKind.CALLS_ENDPOINT,
+        path=path,
+        from_symbol=caller,
+        to_unresolved=url,
+        resolution=sink.resolution(
+            status, confidence,
+            candidates=candidates,
+            unresolved_text=url,
+        ),
+        span=span,
+        evidence=(evi,),
+    )
+    sink.bump("consumer_calls")
+
+
+def extract_consumers(
+    *,
+    sink: Emit,
+    path: str,
+    text: str,
+    result: ParseResult,
+    module: str,
+    content_hash: str,
+    table: dict[str, int],
+    lang: str,
+    confidence: ConfidenceClass,
+) -> None:
+    """Call-sites HTTP a partir de refs ``call`` do AST real."""
+    for ref in result.references:
+        if ref.context != "call":
+            continue
+        callee = ref.name.strip()
+        url_idx = table.get(callee)
+        if url_idx is None:
+            continue
+        scope = ".".join(ref.scope_path)
+        caller = f"{module}.{scope}" if scope else module
+        emit_call(
+            sink=sink, path=path, caller=caller, callee=callee,
+            args_text=common.args_after(
+                text, common.byte_to_char(text, ref.span.end_byte)
+            ),
+            url_idx=url_idx, span=ref.span,
+            content_hash=content_hash,
+            confidence=confidence, lang=lang,
+        )
+
+
+def extract_js_consumers(
+    *,
+    sink: Emit,
+    path: str,
+    text: str,
+    module: str,
+    content_hash: str,
+) -> None:
+    """Regex-static por linha para .js — sem AST; ``heuristic``."""
+    byte_offs = common.byte_offsets(text)
+    for lineno, line in enumerate(text.splitlines(), 1):
+        for m in _JS_CALL.finditer(line):
+            callee = m.group(1)
+            url_idx = TS_URL_ARG.get(callee)
+            if url_idx is None:
+                continue
+            span = common.line_span(text, byte_offs, lineno)
+            emit_call(
+                sink=sink, path=path, caller=module, callee=callee,
+                args_text=common.scan_args(line, m.end() - 1),
+                url_idx=url_idx, span=span,
+                content_hash=content_hash,
+                confidence=ConfidenceClass.HEURISTIC, lang="ts",
+            )