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

code_atlas/contracts/__init__.py

@@ -0,0 +1,38 @@
+"""Contratos de domínio do Code Atlas (modelos, enums, ports).
+
+O domínio não importa CLI, web, MCP, UI ou bancos externos.
+"""
+
+from code_atlas.contracts.enums import (
+    ConfidenceClass,
+    EdgeKind,
+    NodeKind,
+    ResolutionStatus,
+    SnapshotStatus,
+)
+from code_atlas.contracts.models import (
+    DomainSourceFile,
+    Evidence,
+    IndexJob,
+    LogicalSymbol,
+    Relation,
+    Repository,
+    Snapshot,
+    SymbolOccurrence,
+)
+
+__all__ = [
+    "ConfidenceClass",
+    "DomainSourceFile",
+    "EdgeKind",
+    "Evidence",
+    "IndexJob",
+    "LogicalSymbol",
+    "NodeKind",
+    "Relation",
+    "Repository",
+    "ResolutionStatus",
+    "Snapshot",
+    "SnapshotStatus",
+    "SymbolOccurrence",
+]

code_atlas/contracts/enums.py

@@ -0,0 +1,67 @@
+"""Vocabulário canônico do domínio (Blueprint §5).
+
+Valores devem casar exatamente com o Blueprint — não renomear nem estender
+sem ADR. Valores futuros documentados (READS_FROM etc.) ficam de fora até
+existir produtor real.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class NodeKind(StrEnum):
+    """Tipos de nó do grafo (Blueprint §5 "Tipos iniciais")."""
+
+    REPOSITORY = "repository"
+    PACKAGE = "package"
+    MODULE = "module"
+    FILE = "file"
+    CLASS = "class"
+    INTERFACE = "interface"
+    FUNCTION = "function"
+    METHOD = "method"
+    SYMBOL = "symbol"
+    CONFIG = "config"
+    UNKNOWN = "unknown"
+
+
+class EdgeKind(StrEnum):
+    """Vocabulário de arestas (Blueprint §5)."""
+
+    CONTAINS = "CONTAINS"
+    DEFINES = "DEFINES"
+    IMPORTS = "IMPORTS"
+    CALLS = "CALLS"
+    IMPLEMENTS = "IMPLEMENTS"
+    EXTENDS = "EXTENDS"
+    REFERENCES = "REFERENCES"
+    CONFIGURES = "CONFIGURES"
+    TESTS = "TESTS"
+
+
+class ConfidenceClass(StrEnum):
+    """Classe de confiança da evidência — não é probabilidade (Blueprint §5)."""
+
+    RESOLVED = "resolved"
+    SYNTACTIC = "syntactic"
+    HEURISTIC = "heuristic"
+    INFERRED = "inferred"
+
+
+class ResolutionStatus(StrEnum):
+    """Status de resolução de um alvo de relação (Blueprint §5)."""
+
+    RESOLVED = "resolved"
+    AMBIGUOUS = "ambiguous"
+    UNRESOLVED = "unresolved"
+    EXTERNAL = "external"
+
+
+class SnapshotStatus(StrEnum):
+    """Estados do ciclo de vida de um snapshot (Blueprint §5)."""
+
+    BUILDING = "BUILDING"
+    READY = "READY"
+    FAILED = "FAILED"
+    STALE = "STALE"

code_atlas/contracts/models.py

@@ -0,0 +1,175 @@
+"""Modelos de domínio do Code Atlas (Blueprint §5).
+
+Dataclasses stdlib, imutáveis onde possível. Campos de enum aceitam o valor
+string ou o enum e são validados em ``__post_init__`` — valores fora do
+vocabulário levantam ``ValueError``. ``id=None`` significa "a persistir".
+
+Identidade lógica (``LogicalSymbol``, ``SourceFile``) é separada da
+ocorrência por snapshot (``SymbolOccurrence``, ``file_inventory``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from code_atlas.contracts.enums import (
+    ConfidenceClass,
+    EdgeKind,
+    NodeKind,
+    ResolutionStatus,
+    SnapshotStatus,
+)
+
+
+def _coerce(enum_cls: type, value: object, field_name: str) -> object:
+    try:
+        return enum_cls(value)
+    except ValueError as exc:
+        raise ValueError(f"invalid {field_name}: {value!r}") from exc
+
+
+@dataclass(frozen=True)
+class Repository:
+    """Repositório indexado; `id` independe do pathname local."""
+
+    root_handle: str
+    id: int | None = None
+    origin: str = ""
+    git_provider: str = ""
+    default_branch: str = ""
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """Ocorrência imutável de um estado do repositório."""
+
+    repository_id: int
+    worktree_digest: str
+    id: int | None = None
+    git_ref: str = ""
+    commit_sha: str | None = None
+    dirty: bool = False  # lf-0021: conteúdo diverge do commit_sha
+    analyzer_versions: Mapping[str, str] = field(default_factory=dict)
+    parent_snapshot_id: int | None = None
+    status: SnapshotStatus = SnapshotStatus.BUILDING
+    created_at: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "status", _coerce(SnapshotStatus, self.status, "status")
+        )
+
+
+@dataclass(frozen=True)
+class LogicalSymbol:
+    """Símbolo com identidade lógica estável por repositório."""
+
+    repository_id: int
+    language: str
+    qualified_name: str
+    kind: NodeKind
+    id: int | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "kind", _coerce(NodeKind, self.kind, "kind"))
+
+
+@dataclass(frozen=True)
+class DomainSourceFile:
+    """Arquivo-fonte com identidade por (repo, relative_path)."""
+
+    repository_id: int
+    relative_path: str
+    language: str
+    id: int | None = None
+    sha256: str | None = None
+    size_bytes: int = 0
+    ignored: bool = False
+
+
+@dataclass(frozen=True)
+class SymbolOccurrence:
+    """Ocorrência de um símbolo num snapshot (span/hash são da ocorrência)."""
+
+    snapshot_id: int
+    logical_symbol_id: int
+    source_file_id: int
+    id: int | None = None
+    span_start: int | None = None
+    span_end: int | None = None
+    line: int | None = None
+    col: int | None = None
+    content_hash: str | None = None
+    parse_status: str = "parsed"
+
+
+@dataclass(frozen=True)
+class Relation:
+    """Aresta tipada com proveniência obrigatória (Blueprint ADR-012)."""
+
+    snapshot_id: int
+    from_id: int
+    relation_type: EdgeKind
+    resolver: str
+    confidence_class: ConfidenceClass
+    resolution_status: ResolutionStatus
+    id: int | None = None
+    to_id: int | None = None
+    to_unresolved: str | None = None
+    evidence_ids: tuple[int, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "relation_type", _coerce(EdgeKind, self.relation_type, "relation_type")
+        )
+        object.__setattr__(
+            self,
+            "confidence_class",
+            _coerce(ConfidenceClass, self.confidence_class, "confidence_class"),
+        )
+        object.__setattr__(
+            self,
+            "resolution_status",
+            _coerce(ResolutionStatus, self.resolution_status, "resolution_status"),
+        )
+        if self.to_id is None and not self.to_unresolved:
+            raise ValueError("relation requires to_id or to_unresolved target")
+        if not self.resolver:
+            raise ValueError("relation requires resolver provenance")
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """Trecho observável que sustenta um fato (extrator + versão + hash)."""
+
+    snapshot_id: int
+    source_file_id: int
+    path: str
+    content_hash: str
+    extractor: str
+    extractor_version: str
+    id: int | None = None
+    span: str | None = None
+    notes: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.content_hash:
+            raise ValueError("evidence requires content_hash")
+        if not self.extractor or not self.extractor_version:
+            raise ValueError("evidence requires extractor + extractor_version")
+
+
+@dataclass(frozen=True)
+class IndexJob:
+    """Registro de uma tentativa de indexação (diagnóstico)."""
+
+    repository_id: int
+    status: str  # running | success | failed | noop
+    id: int | None = None
+    snapshot_id: int | None = None
+    started_at: str = ""
+    finished_at: str = ""
+    counts: Mapping[str, int] = field(default_factory=dict)
+    failures: tuple[str, ...] = ()
+    manifest_hash: str = ""

code_atlas/contracts/ports.py

@@ -0,0 +1,70 @@
+"""Ports hexagonais do domínio (Blueprint §3).
+
+Interfaces ``Protocol`` — apenas assinaturas. Implementações reais do
+Cycle 1: ``RepositoryScanner`` (discovery.scan), ``GraphStore`` parcial
+(storage), ``IndexCoordinator`` (indexing). As demais são contrato para
+ciclos futuros e não têm implementação placebo.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from code_atlas.contracts.enums import ResolutionStatus
+from code_atlas.contracts.models import Snapshot, SymbolOccurrence
+from code_atlas.discovery.models import ScanOptions, ScanResult
+
+
+class RepositoryScanner(Protocol):
+    """Produz o inventário de arquivos de uma raiz (implementado: discovery)."""
+
+    def scan(
+        self, root: Path, options: ScanOptions | None = None
+    ) -> ScanResult: ...
+
+
+class ParserAdapter(Protocol):
+    """Adaptador AST (Tree-sitter, Cycle 2) com capability matrix declarada."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def version(self) -> str: ...
+
+    def languages(self) -> frozenset[str]: ...
+
+    def capabilities(self) -> frozenset[str]:
+        """Ex.: ``symbols``, ``imports``, ``calls``, ``docstrings``."""
+        ...
+
+
+class SymbolResolver(Protocol):
+    """Resolve ocorrências para alvos canônicos (SCIP/LSP, Cycle 3)."""
+
+    @property
+    def name(self) -> str: ...
+
+    def resolve(self, occurrence: SymbolOccurrence) -> ResolutionStatus: ...
+
+
+class GraphStore(Protocol):
+    """Persistência do grafo tipado (implementado parcialmente: storage)."""
+
+    def latest_ready_snapshot(self, repository_id: int) -> Snapshot | None: ...
+
+    def snapshot_by_id(self, snapshot_id: int) -> Snapshot | None: ...
+
+
+class SearchPort(Protocol):
+    """Busca lexical/estrutural (FTS5, Cycle 4)."""
+
+    def search(self, query: str, limit: int = 20) -> Sequence[object]: ...
+
+
+class IndexCoordinator(Protocol):
+    """Orquestra scan → snapshot → publicação atômica (implementado: indexing)."""
+
+    def index(self, root: Path) -> Snapshot: ...

code_atlas/discovery/__init__.py

@@ -0,0 +1,25 @@
+"""Discovery Git-aware: inventário de arquivos, fingerprints e manifest."""
+
+from code_atlas.discovery.models import (
+    GitInfo,
+    ScanMode,
+    ScanOptions,
+    ScanResult,
+    ScanWarning,
+    SourceFile,
+    WarningKind,
+)
+from code_atlas.discovery.scanner import probe_git, scan
+
+__all__ = [
+    "GitInfo",
+    "ScanMode",
+    "ScanOptions",
+    "ScanResult",
+    "ScanWarning",
+    "SourceFile",
+    "WarningKind",
+    "probe_git",
+    "scan",
+]
+

code_atlas/discovery/gitignore.py

@@ -0,0 +1,119 @@
+"""Parser mínimo de `.gitignore` (fallback sem git).
+
+Best-effort: suporta `*`, `?`, `[...]`, `**`, âncora `/`, negação `!` e
+padrões de diretório com `/` final. Escopo é o diretório do `.gitignore`.
+Semântica: a última regra que casa decide (ordem do arquivo, raiz → folha).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _translate(pattern: str) -> str:
+    """Converte um glob gitignore em regex sobre path relativo POSIX."""
+    out = []
+    i = 0
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "*":
+            if pattern[i : i + 2] == "**":
+                if pattern[i : i + 3] == "**/":
+                    out.append("(?:.*/)?")
+                    i += 3
+                    continue
+                out.append(".*")
+                i += 2
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c == "[":
+            j = pattern.find("]", i + 1)
+            if j == -1:
+                out.append(re.escape(c))
+            else:
+                out.append(pattern[i : j + 1])
+                i = j
+        else:
+            out.append(re.escape(c))
+        i += 1
+    return "".join(out)
+
+
+@dataclass(frozen=True)
+class _Rule:
+    regex: re.Pattern[str]
+    negate: bool
+    dir_only: bool
+
+
+class GitIgnoreScope:
+    """Regras de um único `.gitignore`, aplicáveis a paths relativos a seu dir."""
+
+    def __init__(self, base: str, rules: list[_Rule]) -> None:
+        self.base = base  # dir relativo POSIX onde o .gitignore vive ("" = raiz)
+        self.rules = rules
+
+    @classmethod
+    def parse(cls, base: str, text: str) -> GitIgnoreScope:
+        rules: list[_Rule] = []
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            negate = line.startswith("!")
+            if negate:
+                line = line[1:]
+            dir_only = line.endswith("/")
+            line = line.rstrip("/")
+            anchored = line.startswith("/")
+            line = line.lstrip("/")
+            if not line:
+                continue
+            if "/" not in line and not anchored:
+                # Sem barra: casa basename em qualquer profundidade do escopo.
+                regex = re.compile(rf"(?:^|/){_translate(line)}$")
+            else:
+                regex = re.compile(rf"^{_translate(line)}$")
+            rules.append(_Rule(regex=regex, negate=negate, dir_only=dir_only))
+        return cls(base=base, rules=rules)
+
+    def matches(self, path: str, is_dir: bool) -> bool | None:
+        """True/False se decidido por este escopo; None se nenhuma regra casa."""
+        rel = path[len(self.base) :].lstrip("/") if self.base else path
+        if not rel:
+            return None
+        decision: bool | None = None
+        for rule in self.rules:
+            if rule.dir_only and not is_dir:
+                continue
+            if rule.regex.match(rel):
+                decision = not rule.negate  # último match vence
+        return decision
+
+
+class GitIgnoreStack:
+    """Pilha de escopos `.gitignore`; a decisão mais profunda e tardia vence."""
+
+    def __init__(self) -> None:
+        self._scopes: list[GitIgnoreScope] = []
+
+    def add_file(self, base_dir: str, path: Path) -> None:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return
+        self._scopes.append(GitIgnoreScope.parse(base_dir, text))
+
+    def is_ignored(self, path: str, is_dir: bool) -> bool:
+        """True se ignorado; o escopo mais profundo que decide vence."""
+        for scope in reversed(self._scopes):
+            if scope.base and not path.startswith(scope.base + "/"):
+                continue
+            decision = scope.matches(path, is_dir)
+            if decision is not None:
+                return decision
+        return False

code_atlas/discovery/identity.py

@@ -0,0 +1,52 @@
+"""Identidade lógica do repositório (lf-0021).
+
+``repository_id`` é derivado de identidade **lógica**, nunca só do path:
+
+1. ``git-remote:<remote.origin.url>`` — repositório com remote;
+2. ``git-root:<sha do commit raiz>`` — repo git sem remote;
+3. ``path:<root resolvido>`` — último recurso (sem git).
+
+Realocar o diretório físico mantém a identidade (``root_handle`` passa a
+ser campo de diagnóstico atualizado a cada index). Dois checkouts do
+mesmo remote **compartilham** identidade — snapshots de ambos vivem sob
+o mesmo repo e se distinguem por ``worktree_digest``/revisão.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from code_atlas.discovery.models import GitInfo
+from code_atlas.discovery.scanner import probe_git
+
+
+def identity_key(git: GitInfo, root: Path) -> str:
+    """Chave de identidade estável do repositório.
+
+    lf-0058: raiz **abaixo** do toplevel git recebe sufixo
+    ``@<caminho relativo>`` — dois projetos num mesmo monorepo não
+    colidem mais (antes compartilhavam o remote → mesmo repo).
+    Raiz == toplevel mantém o formato legado (retrocompatível);
+    realocar o diretório preserva identidade pois o relpath é estável.
+    """
+    base = ""
+    if git.remote_url:
+        base = f"git-remote:{git.remote_url}"
+    elif git.root_commit:
+        base = f"git-root:{git.root_commit}"
+    else:
+        return f"path:{Path(root).resolve()}"
+    if git.toplevel:
+        try:
+            rel = Path(root).resolve().relative_to(
+                Path(git.toplevel).resolve())
+        except ValueError:
+            rel = None
+        if rel is not None and str(rel) not in ("", "."):
+            return f"{base}@{rel.as_posix()}"
+    return base
+
+
+def identity_key_for_root(root: Path) -> str:
+    """Identidade sem scan completo — usado por ``init`` (probe apenas)."""
+    return identity_key(probe_git(Path(root)), Path(root))