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

code_atlas/domains/terraform/refs.py

@@ -0,0 +1,181 @@
+"""Varredura de referências + sanitização/Redaction (lf-0115).
+
+Regras de segurança (inespeciáveis):
+
+- **segredos nunca saem**: qualquer valor cuja chave case com
+  ``password|secret|token|key|credential`` (case-insensitive) é
+  substituído por ``[REDACTED]`` — o valor bruto nunca entra em
+  entidades, atributos, evidência ou ``to_unresolved``;
+- **interpolação não é valor**: todo ``${…}`` vira o marcador
+  ``${dynamic}`` — nunca avaliamos nem copiamos a expressão interna
+  para metadados persistidos;
+- **count/for_each não expandem**: multiplicidade declarada é
+  registrada como ``dynamic`` — nunca fabricamos instâncias;
+- referências ``var.``/``local.``/``each.``/``count.``/``self.``/
+  ``path.``/``terraform.`` não viram arestas (não são entidades de
+  domínio).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Chaves sensíveis — spec lf-0115: password|secret|token|key|credential.
+SECRET_KEY_RE = re.compile(
+    r"password|secret|token|key|credential", re.IGNORECASE
+)
+
+REDACTED = "[REDACTED]"
+DYNAMIC = "${dynamic}"
+
+# ``aws_s3_bucket.logs`` — primeiro segmento DEVE conter ``_`` (tipos de
+# recurso sempre têm provider_nome); lookbehind impede match em
+# ``var.foo_bar.x``, ``local.a_b`` e dentro de ``module.x.aws_y_z``.
+RESOURCE_REF_RE = re.compile(
+    r"(?<![.\w])([A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+)"
+    r"\.([A-Za-z0-9_-]+)(?![\w-]*\()"
+)
+
+# ``data.aws_x.y`` — fontes de dados (leitura, não managed).
+DATA_REF_RE = re.compile(
+    r"(?<![.\w])data\.([A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+)"
+    r"\.([A-Za-z0-9_-]+)"
+)
+
+# ``module.name.attr`` — referência a output de módulo.
+MODULE_REF_RE = re.compile(
+    r"(?<![.\w])module\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)"
+)
+
+# ARNs literais — recursos externos ao snapshot (REFERENCES external).
+ARN_RE = re.compile(r"arn:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:[0-9]*:[^\s\"'\\)]+")
+
+# ``${…}`` superficial — sanitização de valores antes de armazenar.
+_INTERP_START_RE = re.compile(r"\$\{")
+
+# Formatos de credencial de alta precisão — um valor que *parece* segredo
+# vaza mesmo sob chave benigna (``description = "AKIA…"``, env-var
+# ``stage = "ghp_…"``). O trecho casa só marcadores inequívocos de
+# provedores conhecidos; nunca classifica texto comum (lf-c8 F5).
+SECRET_VALUE_RE = re.compile(
+    r"AKIA[0-9A-Z]{16}"            # AWS access key id
+    r"|ASIA[0-9A-Z]{16}"           # AWS temporary access key id
+    r"|-----BEGIN [A-Z0-9 ]{0,32}PRIVATE KEY-----"
+    r"|github_pat_[A-Za-z0-9_]{22,}"
+    r"|gh[pousr]_[A-Za-z0-9]{36,}"  # ghp_/gho_/ghu_/ghs_/ghr_
+    r"|xox[baprs]-[A-Za-z0-9-]{10,}"  # Slack tokens
+    r"|AIza[0-9A-Za-z_-]{35}"      # GCP API key
+    r"|sk_live_[A-Za-z0-9]{16,}"   # Stripe live secret
+    r"|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"  # JWT
+)
+
+
+def is_sensitive_name(name: str) -> bool:
+    """True se a chave/nome casa o padrão de segredos (spec)."""
+    return bool(SECRET_KEY_RE.search(name))
+
+
+def looks_like_secret_value(text: str) -> bool:
+    """True se ``text`` contém trecho com formato de credencial conhecida."""
+    return bool(SECRET_VALUE_RE.search(text))
+
+
+def mask_secret_values(text: str) -> str:
+    """Redige trechos com formato de credencial — defesa em profundidade
+    para valores sob chaves benignas."""
+    return SECRET_VALUE_RE.sub(REDACTED, text)
+
+
+def sanitize_value(text: str, *, max_len: int = 200) -> str:
+    """Substitui ``${…}`` balanceados por ``${dynamic}`` e trunca.
+
+    Nunca avalia a expressão — o conteúdo interpolado é descartado e
+    substituído pelo marcador dinâmico (spec: "dynamic marker, not
+    concrete value").
+    """
+    out: list[str] = []
+    i, n = 0, len(text)
+    while i < n:
+        m = _INTERP_START_RE.search(text, i)
+        if m is None:
+            out.append(text[i:])
+            break
+        out.append(text[i:m.start()])
+        depth = 1
+        j = m.end()
+        while j < n and depth:
+            if text[j] == "{":
+                depth += 1
+            elif text[j] == "}":
+                depth -= 1
+            j += 1
+        out.append(DYNAMIC)
+        i = j
+    s = "".join(out).strip()
+    return mask_secret_values(s[:max_len])
+
+
+def redact_if_sensitive(key: str, value: str) -> str:
+    """``value`` sanitizado, ou ``[REDACTED]`` se ``key`` é sensível."""
+    if is_sensitive_name(key):
+        return REDACTED
+    return sanitize_value(value)
+
+
+@dataclass(frozen=True)
+class RefMatch:
+    """Referência encontrada num texto — offset em bytes do arquivo."""
+
+    kind: str          # resource | data | module | arn
+    type_name: str     # "aws_s3_bucket" | "module" | "data" | "arn"
+    name: str          # label do alvo ("logs") ou texto do ARN
+    start: int         # byte offset do início do match
+    end: int
+
+
+def _byte_offsets(text: str, start_char: int, end_char: int) -> tuple[int, int]:
+    """Char offsets → byte offsets UTF-8 (trechos curtos, barato)."""
+    return (
+        len(text[:start_char].encode("utf-8")),
+        len(text[:end_char].encode("utf-8")),
+    )
+
+
+def scan_refs(text: str, *, base_byte: int = 0) -> list[RefMatch]:
+    """Todas as referências terraform em ``text`` (ordem de posição).
+
+    ``base_byte`` soma-se aos offsets quando ``text`` é um slice do
+    arquivo (corpo de bloco). Inclui refs a recursos managed
+    (``aws_x.y``), data sources (``data.aws_x.y``), saídas de módulo
+    (``module.a.b``) e ARNs literais.
+    """
+    out: list[RefMatch] = []
+    for m in DATA_REF_RE.finditer(text):
+        s, e = _byte_offsets(text, m.start(), m.end())
+        out.append(
+            RefMatch("data", m.group(1), m.group(2), base_byte + s, base_byte + e)
+        )
+    for m in RESOURCE_REF_RE.finditer(text):
+        s, e = _byte_offsets(text, m.start(), m.end())
+        out.append(
+            RefMatch(
+                "resource", m.group(1), m.group(2),
+                base_byte + s, base_byte + e,
+            )
+        )
+    for m in MODULE_REF_RE.finditer(text):
+        s, e = _byte_offsets(text, m.start(), m.end())
+        out.append(
+            RefMatch(
+                "module", "module", m.group(1),
+                base_byte + s, base_byte + e,
+            )
+        )
+    for m in ARN_RE.finditer(text):
+        s, e = _byte_offsets(text, m.start(), m.end())
+        out.append(
+            RefMatch("arn", "arn", m.group(0), base_byte + s, base_byte + e)
+        )
+    out.sort(key=lambda r: r.start)
+    return out

code_atlas/domains/terraform/tfjson.py

@@ -0,0 +1,163 @@
+"""Leitura estrutural de ``.tf.json`` (lf-0115).
+
+Terraform aceita configuração em JSON: ``{"resource": {"aws_x":
+{"name": {…attrs…}}}}``. Este leitor converte o objeto em
+``HclBlock`` equivalentes — ``body`` é a serialização JSON do objeto
+do bloco e os ``value_span`` dos atributos são offsets **dentro do
+body** (body_start=0), mantendo a classificação de referências
+(``depends_on`` explícito, atributo de documento) consistente no
+mesmo espaço de coordenadas.
+
+Spans de entidade/evidência: o JSON stdlib não expõe offsets —
+aproximamos pelo token ``"<name>"`` no texto real do arquivo
+(``_key_span``); evidência aponta para conteúdo do inventário, com
+precisão declarada como aproximada.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from code_atlas.domains.terraform.hcl import HclAttribute, HclBlock, HclDiagnostic
+from code_atlas.parsers.contracts import SourceSpan
+
+_ZERO = SourceSpan(0, 0, 0, 0, 0, 0)
+
+
+@dataclass(frozen=True)
+class TfJsonFile:
+    blocks: tuple[HclBlock, ...] = ()
+    diagnostics: tuple[HclDiagnostic, ...] = ()
+
+
+def _key_span(text: str, key: str) -> SourceSpan | None:
+    """Span aproximado do token ``"<key>"`` no texto do arquivo."""
+    needle = json.dumps(key, ensure_ascii=False)
+    idx = text.find(needle)
+    if idx < 0:
+        return None
+    start_b = len(text[:idx].encode("utf-8"))
+    end_b = start_b + len(needle.encode("utf-8"))
+    line = text.count("\n", 0, idx) + 1
+    line_start = text.rfind("\n", 0, idx) + 1
+    col = len(text[line_start:idx].encode("utf-8"))
+    return SourceSpan(
+        start_byte=start_b, end_byte=end_b,
+        start_line=line, start_col=col,
+        end_line=line, end_col=col + (end_b - start_b),
+    )
+
+
+def _body_span(start: int, end: int) -> SourceSpan:
+    """Span em coordenadas do corpo serializado (linha 1 fictícia)."""
+    return SourceSpan(
+        start_byte=start, end_byte=end,
+        start_line=1, start_col=start, end_line=1, end_col=end,
+    )
+
+
+def _attrs_of_body(body_text: str, obj: object) -> tuple[HclAttribute, ...]:
+    """``{k: v}`` → atributos; ``value_span`` em offsets do ``body``.
+
+    A região do valor vai do fim do token ``"k"`` até o início da
+    próxima chave irmã (ordem preservada pelo ``json``) — aproximação
+    contendo o valor serializado inteiro.
+    """
+    if not isinstance(obj, dict):
+        return ()
+    out: list[HclAttribute] = []
+    positions: list[tuple[str, int]] = []
+    cursor = 0
+    for k in obj:
+        token = json.dumps(str(k), ensure_ascii=False)
+        idx = body_text.find(token, cursor)
+        if idx < 0:
+            idx = body_text.find(token)
+        if idx >= 0:
+            positions.append((str(k), idx))
+            cursor = idx + len(token)
+        else:
+            positions.append((str(k), -1))
+    for i, (key, idx) in enumerate(positions):
+        raw = json.dumps(obj[key], ensure_ascii=False)
+        if idx < 0:
+            span = _ZERO
+        else:
+            vstart = idx + len(json.dumps(str(k), ensure_ascii=False)) + 1
+            vend = (
+                positions[i + 1][1]
+                if i + 1 < len(positions) and positions[i + 1][1] > vstart
+                else len(body_text)
+            )
+            span = _body_span(vstart, vend)
+        out.append(
+            HclAttribute(name=key, value=raw, span=span, value_span=span)
+        )
+    return tuple(out)
+
+
+def _block(
+    text: str,
+    btype: str,
+    labels: tuple[str, ...],
+    name_key: str,
+    body: object,
+) -> HclBlock:
+    body_text = json.dumps(body, ensure_ascii=False)
+    span = _key_span(text, name_key)
+    return HclBlock(
+        type=btype, labels=labels,
+        attributes=_attrs_of_body(body_text, body),
+        body=body_text, body_start=0,
+        span=span, header_span=span,
+    )
+
+
+def _section_blocks(
+    text: str, section: str, content: dict[str, object]
+) -> list[HclBlock]:
+    """Uma seção top-level → blocos ``HclBlock`` equivalentes."""
+    out: list[HclBlock] = []
+    if section in ("resource", "data"):
+        # {"resource": {"aws_x": {"name": {…}}}}
+        for rtype, named in content.items():
+            if not isinstance(named, dict):
+                continue
+            for name, body in named.items():
+                out.append(
+                    _block(
+                        text, section,
+                        (str(rtype), str(name)), str(name), body,
+                    )
+                )
+    elif section in ("module", "variable", "output", "provider"):
+        for name, body in content.items():
+            out.append(_block(text, section, (str(name),), str(name), body))
+    else:
+        # locals / terraform / seções desconhecidas — bloco anônimo
+        out.append(_block(text, section, (), section, content))
+    return out
+
+
+def parse_tfjson(text: str) -> TfJsonFile:
+    """Parse estrutural de ``*.tf.json`` — nunca levanta."""
+    try:
+        data = json.loads(text)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return TfJsonFile(
+            diagnostics=(HclDiagnostic("json-parse-error", str(exc)),)
+        )
+    if not isinstance(data, dict):
+        return TfJsonFile(
+            diagnostics=(
+                HclDiagnostic(
+                    "json-parse-error", "tf.json root must be an object"
+                ),
+            )
+        )
+    blocks: list[HclBlock] = []
+    for section, content in data.items():
+        if isinstance(content, dict):
+            blocks.extend(_section_blocks(text, str(section), content))
+    return TfJsonFile(blocks=tuple(blocks))

code_atlas/domains/terraform/tfvars.py

@@ -0,0 +1,98 @@
+"""Leitura estrutural de ``.tfvars`` / ``.tfvars.json`` (lf-0115).
+
+tfvars é HCL restrito a atribuições top-level — reusa ``parse_hcl``
+sem nenhum caminho de execução. ``.tfvars.json`` é JSON puro.
+
+Segurança: valores cuja chave casa o padrão de segredos nunca são
+devolvidos — o caller recebe o marcador ``[REDACTED]``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from code_atlas.domains.terraform.hcl import HclDiagnostic, parse_hcl
+from code_atlas.domains.terraform.refs import (
+    REDACTED,
+    is_sensitive_name,
+    looks_like_secret_value,
+    sanitize_value,
+)
+
+
+@dataclass(frozen=True)
+class TfvarsAssignment:
+    """Atribuição ``name = value`` de um arquivo tfvars."""
+
+    name: str
+    value: str          # texto bruto (sanitizado/redigido pelo caller via flags)
+    redacted: bool      # True quando a chave é sensível — value == "[REDACTED]"
+    line: int = 0
+
+
+@dataclass(frozen=True)
+class TfvarsFile:
+    assignments: tuple[TfvarsAssignment, ...] = ()
+    diagnostics: tuple[HclDiagnostic, ...] = ()
+
+
+def _unquote(value: str) -> str:
+    v = value.strip()
+    if len(v) >= 2 and v.startswith('"') and v.endswith('"'):
+        return v[1:-1]
+    return v
+
+
+def _assignment(name: str, raw: str, line: int) -> TfvarsAssignment:
+    if is_sensitive_name(name):
+        return TfvarsAssignment(name, REDACTED, True, line)
+    # valor com formato de credencial sob chave benigna — mesma redação
+    # que chave sensível; nunca entra em env-hints nem atributos (F5).
+    if looks_like_secret_value(_unquote(raw)):
+        return TfvarsAssignment(name, REDACTED, True, line)
+    return TfvarsAssignment(name, sanitize_value(_unquote(raw)), False, line)
+
+
+def parse_tfvars(text: str) -> TfvarsFile:
+    """Parse de ``*.tfvars`` (HCL assignments) — nunca levanta."""
+    hcl = parse_hcl(text)
+    out = [
+        _assignment(a.name, a.value, a.span.start_line)
+        for a in hcl.attributes
+    ]
+    diags = list(hcl.diagnostics)
+    for b in hcl.blocks:  # tfvars não tem blocos — honesto, não crash
+        diags.append(
+            HclDiagnostic(
+                code="unexpected-block",
+                message=f"block {b.type!r} in tfvars file",
+                line=(b.header_span.start_line if b.header_span else 0),
+            )
+        )
+    return TfvarsFile(assignments=tuple(out), diagnostics=tuple(diags))
+
+
+def parse_tfvars_json(text: str) -> TfvarsFile:
+    """Parse de ``*.tfvars.json`` — objeto JSON chave→valor."""
+    try:
+        data = json.loads(text)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return TfvarsFile(
+            diagnostics=(
+                HclDiagnostic("json-parse-error", str(exc)),
+            )
+        )
+    if not isinstance(data, dict):
+        return TfvarsFile(
+            diagnostics=(
+                HclDiagnostic(
+                    "json-parse-error", "tfvars.json root must be an object"
+                ),
+            )
+        )
+    out = [
+        _assignment(str(k), json.dumps(v, ensure_ascii=False), 0)
+        for k, v in data.items()
+    ]
+    return TfvarsFile(assignments=tuple(out))

code_atlas/domains/validation.py

@@ -0,0 +1,120 @@
+"""Validação de saída de adapters de domínio (lf-0110).
+
+Espelha ``graph.validation``: retorna lista de violações (vazia = ok),
+nunca levanta. Checagens:
+
+- ``result.domain_id``/``adapter_version`` casam com o adapter;
+- kinds de entidade/relação ⊆ vocabulário declarado pelo adapter;
+- identidades das entidades têm ``domain`` == adapter e repositório ==
+  request;
+- confiança declarada respeita o ``ConfidenceModel`` (teto + inferência);
+- índices de evidência em faixa; invariantes de ``DomainResolution``
+  (inferred nunca resolved — reforço: o dataclass já garante, aqui
+  reporta-se como violação, não exceção).
+"""
+
+from __future__ import annotations
+
+from code_atlas.contracts.enums import ConfidenceClass, ResolutionStatus
+from code_atlas.domains.contracts import (
+    DOMAIN_CONTRACT_VERSION,
+    DomainAdapter,
+    DomainExtractionRequest,
+    DomainExtractionResult,
+)
+from code_atlas.domains.model import DOMAIN_RELATION_TYPES
+
+
+def _check_envelope(
+    adapter: DomainAdapter, result: DomainExtractionResult
+) -> list[str]:
+    errors: list[str] = []
+    if result.schema_version != DOMAIN_CONTRACT_VERSION:
+        errors.append(f"schema_version mismatch: {result.schema_version}")
+    if result.domain_id != adapter.domain_id:
+        errors.append(
+            f"result.domain_id {result.domain_id!r} != adapter "
+            f"{adapter.domain_id!r}"
+        )
+    if result.adapter_version != adapter.adapter_version:
+        errors.append(
+            f"result.adapter_version {result.adapter_version!r} != adapter "
+            f"{adapter.adapter_version!r}"
+        )
+    return errors
+
+
+def _check_entities(
+    adapter: DomainAdapter,
+    request: DomainExtractionRequest,
+    result: DomainExtractionResult,
+) -> list[str]:
+    errors: list[str] = []
+    declared = adapter.entity_kinds()
+    evi_len = len(result.evidence)
+    identities: set[str] = set()
+    for e in result.entities:
+        key = e.identity.canonical_key()
+        if key in identities:
+            errors.append(f"duplicate entity identity: {e.identity.display()}")
+        identities.add(key)
+        if e.kind not in declared:
+            errors.append(f"undeclared entity kind: {e.kind}")
+        if e.identity.domain != adapter.domain_id:
+            errors.append(
+                f"entity domain {e.identity.domain!r} != adapter "
+                f"{adapter.domain_id!r}"
+            )
+        if e.identity.repository != request.repository:
+            errors.append(
+                f"entity repository {e.identity.repository!r} != request "
+                f"{request.repository!r}"
+            )
+        for i in e.evidence:
+            if not 0 <= i < evi_len:
+                errors.append(f"entity evidence index out of range: {i}")
+    return errors
+
+
+def _check_relations(
+    adapter: DomainAdapter, result: DomainExtractionResult
+) -> list[str]:
+    errors: list[str] = []
+    declared = adapter.relation_kinds()
+    confidence = adapter.confidence_model()
+    evi_len = len(result.evidence)
+    for r in result.relations:
+        if r.relation_type not in DOMAIN_RELATION_TYPES:
+            errors.append(f"invalid relation_type: {r.relation_type!r}")
+        elif r.relation_type not in declared:
+            errors.append(f"undeclared relation kind: {r.relation_type!r}")
+        if r.to_identity is None and not r.to_symbol and not r.to_unresolved:
+            errors.append("relation without target")
+        res = r.resolution
+        if res is not None:
+            if (
+                res.confidence_class is ConfidenceClass.INFERRED
+                and res.status is ResolutionStatus.RESOLVED
+            ):
+                errors.append("inferred confidence reported resolved")
+            if not confidence.admits(res.confidence_class):
+                errors.append(
+                    f"confidence {res.confidence_class} exceeds adapter "
+                    f"ceiling {confidence.ceiling}"
+                )
+        for i in r.evidence:
+            if not 0 <= i < evi_len:
+                errors.append(f"relation evidence index out of range: {i}")
+    return errors
+
+
+def validate_extraction(
+    adapter: DomainAdapter,
+    request: DomainExtractionRequest,
+    result: DomainExtractionResult,
+) -> list[str]:
+    """Violações do resultado contra o contrato declarado do adapter."""
+    errors = _check_envelope(adapter, result)
+    errors.extend(_check_entities(adapter, request, result))
+    errors.extend(_check_relations(adapter, result))
+    return errors

code_atlas/env_override.py

@@ -0,0 +1,27 @@
+"""Contexto de override temporário de variáveis de ambiente.
+
+Fora dos pacotes ``domains/``/``federation/``/``eval/`` — o sweep de
+segurança proíbe ``import os`` nesses diretórios (portabilidade de
+paths); manipulação de ambiente vive aqui.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+@contextmanager
+def patched_env(overrides: dict[str, str]) -> Iterator[None]:
+    """Aplica ``overrides`` e restaura o ambiente anterior ao sair."""
+    old = {k: os.environ.get(k) for k in overrides}
+    os.environ.update(overrides)
+    try:
+        yield
+    finally:
+        for k, v in old.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v

code_atlas/eval/__init__.py

@@ -0,0 +1,26 @@
+"""Evaluation metrics — métricas de retrieval matematicamente
+validadas (lf-0048). Sem dependências; determinístico."""
+
+from code_atlas.eval.metrics import (
+    MetricRecord,
+    aggregate,
+    average_precision_at_k,
+    diversity,
+    hit_rate_at_k,
+    mrr,
+    ndcg_at_k,
+    precision_at_k,
+    recall_at_k,
+)
+
+__all__ = [
+    "MetricRecord",
+    "aggregate",
+    "average_precision_at_k",
+    "diversity",
+    "hit_rate_at_k",
+    "mrr",
+    "ndcg_at_k",
+    "precision_at_k",
+    "recall_at_k",
+]