archdrift 0.1.0__py3-none-any.whl

archdrift/__init__.py

@@ -0,0 +1,17 @@
+"""
+archdrift — Contrato de arquitetura para agentes de código.
+
+API pública mínima: quem quiser usar como biblioteca (em vez de CLI)
+importa daqui. Tudo o mais em cli.py é considerado interno.
+"""
+
+from archdrift.cli import (
+    main,
+    cmd_generate,
+    cmd_check,
+    scan,
+    detect_stack,
+)
+
+__version__ = "0.1.0"
+__all__ = ["main", "cmd_generate", "cmd_check", "scan", "detect_stack"]

archdrift/__main__.py

@@ -0,0 +1,6 @@
+"""Permite executar como módulo: python -m archdrift generate ."""
+
+from archdrift.cli import main
+
+if __name__ == "__main__":
+    main()

archdrift/cli.py

@@ -0,0 +1,650 @@
+#!/usr/bin/env python3
+"""
+archdrift.py — Contrato de arquitetura para agentes de código.
+
+Gera e mantém um ARCHITECTURE.md que é ao mesmo tempo:
+  1. MAPA    -> árvore curada + stack detectada (regenerado pelo script)
+  2. CONTRATO -> tabela de responsabilidades editada por HUMANOS
+                 e validada em CI (drift detection)
+
+COMANDOS:
+  python archdrift.py generate <path>   # gera/atualiza preservando curadoria
+  python archdrift.py check <path>      # valida drift; exit 1 se divergiu (CI)
+  python archdrift.py <path>            # atalho para generate
+
+COMO FUNCIONA O MERGE:
+  O ARCHITECTURE.md tem seções GERENCIADAS, delimitadas por marcadores:
+
+      <!-- map:begin <nome> -->
+      ...conteúdo regenerado pelo script...
+      <!-- map:end <nome> -->
+
+  Tudo FORA dos marcadores é seu: notas, ADRs, diagramas, o que quiser.
+  O script nunca toca nesse texto.
+
+  A tabela de responsabilidades é caso especial: fica dentro de marcadores,
+  mas o MERGE preserva as descrições que você editou à mão. Prioridade:
+      descrição humana  >  heurística por nome (ROLE_HINTS)  >  "(preencher)"
+
+COMO FUNCIONA O CHECK (para CI):
+  Falha (exit 1) se qualquer uma destas condições for verdadeira:
+    a) a estrutura em disco mudou desde a última geração (hash divergente)
+    b) existe pasta relevante em disco SEM responsabilidade declarada
+    c) existe pasta documentada que NÃO existe mais em disco
+  Ou seja: o time é obrigado a manter o contrato vivo — exatamente o que
+  agentes de código precisam para confiar no arquivo.
+
+FILOSOFIA:
+  Tools como Repomix/CodeGraph são DESCRITIVOS: leem o código e dizem o que
+  existe. Este script é NORMATIVO: captura a INTENÇÃO do arquiteto e cobra
+  que o repo continue obedecendo. O agente lê a intenção; o CI valida.
+"""
+
+import sys
+import json
+import re
+import hashlib
+import argparse
+from pathlib import Path
+from collections import Counter
+
+# ---------------------------------------------------------------------------
+# CONFIGURAÇÃO
+# ---------------------------------------------------------------------------
+
+# Pastas que NÃO interessam ao agente (ruído). Ajuste à sua stack.
+IGNORE_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "env",
+    "dist", "build", ".next", ".nuxt", "target", "vendor",
+    ".idea", ".vscode", "coverage", ".pytest_cache", ".mypy_cache",
+    "bin", "obj", ".terraform", "tmp", ".turbo", ".cache",
+}
+
+# Arquivos ignorados na listagem (não mudam a arquitetura).
+# Inclui as próprias saídas do script, para não poluir execuções seguintes.
+IGNORE_FILES = {".DS_Store", "Thumbs.db", "desktop.ini",
+                "ARCHITECTURE.md", "structure.json"}
+
+# Dotfiles/dotdirs que SÃO relevantes para o agente entender o projeto.
+DOTFILE_WHITELIST = {
+    ".github", ".gitlab-ci.yml", ".env.example", ".env.sample",
+    ".gitignore", ".dockerignore", ".editorconfig", ".nvmrc",
+    ".eslintrc.json", ".eslintrc.js", ".prettierrc", ".babelrc",
+}
+
+# Profundidade máxima da ÁRVORE exibida. Além disso vira ruído.
+MAX_DEPTH = 4
+
+# Profundidade máxima do CONTRATO: pastas até este nível PRECISAM ter
+# responsabilidade declarada (o check cobra). Mais fundo que isso é detalhe
+# de implementação e não entra na tabela.
+DOC_DEPTH = 2
+
+# Máximo de arquivos de CÓDIGO listados individualmente por diretório.
+MAX_CODE_FILES_PER_DIR = 30
+
+# Placeholder para responsabilidade pendente. O check falha enquanto existir.
+PENDING = "_(preencher)_"
+
+# Extensões consideradas CÓDIGO/CONFIG -> listadas individualmente na árvore.
+CODE_EXTS = {
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".go", ".rs", ".java", ".kt", ".rb", ".php", ".cs", ".swift",
+    ".c", ".h", ".cpp", ".hpp", ".sql", ".sh", ".ps1",
+    ".vue", ".svelte", ".astro",
+    ".yml", ".yaml", ".toml", ".ini", ".env", ".tf",
+    ".html", ".css", ".scss", ".sass", ".graphql", ".proto", ".prisma",
+    ".md", ".mdx",
+}
+
+# Arquivos SEM extensão que importam (não são colapsados em grupo).
+IMPORTANT_BARE_NAMES = {
+    "Dockerfile", "Makefile", "Procfile", "Rakefile", "Gemfile",
+    "LICENSE", "CODEOWNERS",
+}
+
+# JSONs de config que importam; os demais .json são tratados como dados.
+IMPORTANT_JSON_NAMES = {
+    "package.json", "tsconfig.json", "composer.json", "deno.json",
+    "jsconfig.json", "lerna.json", "nx.json", "turbo.json",
+    "vercel.json", "firebase.json", "app.json", "manifest.json",
+}
+
+# Marcadores de stack: arquivo na raiz -> (stack, descrição).
+STACK_MARKERS = {
+    "package.json":        ("Node.js",       "manifesto de dependências npm"),
+    "tsconfig.json":       ("TypeScript",    "configuração do compilador TS"),
+    "pyproject.toml":      ("Python",        "manifesto do projeto Python"),
+    "requirements.txt":    ("Python",        "dependências pip"),
+    "Pipfile":             ("Python",        "dependências pipenv"),
+    "go.mod":              ("Go",            "módulo Go"),
+    "Cargo.toml":          ("Rust",          "manifesto Cargo"),
+    "pom.xml":             ("Java (Maven)",  "build Maven"),
+    "build.gradle":        ("Java/Kotlin (Gradle)", "build Gradle"),
+    "build.gradle.kts":    ("Kotlin (Gradle)", "build Gradle KTS"),
+    "composer.json":       ("PHP",           "dependências Composer"),
+    "Gemfile":             ("Ruby",          "dependências Bundler"),
+    "mix.exs":             ("Elixir",        "projeto Mix"),
+    "Dockerfile":          ("Docker",        "imagem de container"),
+    "docker-compose.yml":  ("Docker Compose","orquestração local"),
+    "docker-compose.yaml": ("Docker Compose","orquestração local"),
+    "serverless.yml":      ("Serverless",    "config Serverless Framework"),
+    "next.config.js":      ("Next.js",       "config Next.js"),
+    "next.config.mjs":     ("Next.js",       "config Next.js"),
+    "next.config.ts":      ("Next.js",       "config Next.js"),
+    "nuxt.config.ts":      ("Nuxt",          "config Nuxt"),
+    "vite.config.ts":      ("Vite",          "bundler Vite"),
+    "vite.config.js":      ("Vite",          "bundler Vite"),
+    "angular.json":        ("Angular",       "workspace Angular"),
+    "manage.py":           ("Django",        "entrypoint Django"),
+    "artisan":             ("Laravel",       "CLI Laravel"),
+    "main.tf":             ("Terraform",     "infraestrutura como código"),
+}
+
+# Heurísticas de responsabilidade por nome de pasta.
+# São apenas o CHUTE INICIAL: o merge preserva o que o humano escrever.
+ROLE_HINTS = {
+    "src":          "Código-fonte principal da aplicação",
+    "app":          "Ponto de entrada / camada de aplicação",
+    "api":          "Endpoints e rotas expostas",
+    "routes":       "Definição de rotas HTTP",
+    "controllers":  "Camada de controle (recebe request, orquestra)",
+    "services":     "Regras de negócio / lógica de domínio",
+    "models":       "Modelos de dados / entidades",
+    "entities":     "Entidades de domínio",
+    "repositories": "Acesso a dados (persistência)",
+    "db":           "Configuração e migrações de banco",
+    "database":     "Configuração e migrações de banco",
+    "migrations":   "Scripts de migração de schema",
+    "components":   "Componentes de UI reutilizáveis",
+    "pages":        "Páginas / telas da aplicação",
+    "views":        "Camada de apresentação",
+    "hooks":        "React hooks / lógica reutilizável de UI",
+    "utils":        "Funções utilitárias genéricas",
+    "helpers":      "Funções auxiliares",
+    "lib":          "Bibliotecas internas / wrappers",
+    "config":       "Configuração da aplicação",
+    "middleware":   "Middlewares (auth, logging, etc.)",
+    "middlewares":  "Middlewares (auth, logging, etc.)",
+    "tests":        "Testes automatizados",
+    "test":         "Testes automatizados",
+    "__tests__":    "Testes automatizados",
+    "e2e":          "Testes end-to-end",
+    "public":       "Assets estáticos servidos diretamente",
+    "assets":       "Imagens, fontes e mídia",
+    "static":       "Arquivos estáticos",
+    "styles":       "Folhas de estilo / temas",
+    "types":        "Definições de tipos (TS) / interfaces",
+    "interfaces":   "Contratos / interfaces",
+    "schemas":      "Schemas de validação",
+    "dto":          "Data Transfer Objects",
+    "docs":         "Documentação do projeto",
+    "scripts":      "Scripts de automação / build",
+    "store":        "Estado global (Redux/Zustand/etc.)",
+    "context":      "Contextos de estado (React Context)",
+    "guards":       "Proteção de rotas / autorização",
+    "workers":      "Jobs assíncronos / background workers",
+    "jobs":         "Jobs agendados / filas",
+    "events":       "Eventos de domínio / pub-sub",
+    "adapters":     "Adaptadores para serviços externos",
+    "infra":        "Infraestrutura (deploy, IaC)",
+    "shared":       "Código compartilhado entre módulos",
+    "core":         "Núcleo do domínio / kernel da aplicação",
+}
+
+# Marcadores das seções gerenciadas dentro do ARCHITECTURE.md.
+MARK_BEGIN = "<!-- map:begin {name} -->"
+MARK_END   = "<!-- map:end {name} -->"
+MARK_HASH  = "<!-- map:hash {value} -->"
+
+
+# ---------------------------------------------------------------------------
+# CLASSIFICAÇÃO
+# ---------------------------------------------------------------------------
+
+def infer_role(dirname: str) -> str:
+    """
+    Responsabilidade inferida pelo nome da pasta.
+    Matching exato primeiro; depois parcial por palavra
+    (ex: 'user-services' -> hint de 'services').
+    """
+    name = dirname.lower()
+    if name in ROLE_HINTS:
+        return ROLE_HINTS[name]
+    parts = set(name.replace("-", " ").replace("_", " ").replace(".", " ").split())
+    for hint, role in ROLE_HINTS.items():
+        if hint in parts:
+            return role
+    return ""
+
+
+def is_code_file(path: Path) -> bool:
+    """Código/config (listado um a um) vs. dado/asset (colapsado em grupo)."""
+    if path.name in IMPORTANT_BARE_NAMES:
+        return True
+    if path.name in DOTFILE_WHITELIST:
+        return True
+    if path.suffix.lower() == ".json":
+        return path.name in IMPORTANT_JSON_NAMES
+    return path.suffix.lower() in CODE_EXTS
+
+
+# ---------------------------------------------------------------------------
+# DETECÇÃO DE STACK
+# ---------------------------------------------------------------------------
+
+def detect_stack(root: Path):
+    """Procura arquivos marcadores na raiz. Retorna [(stack, arquivo, desc)]."""
+    found = []
+    for marker, (stack, desc) in STACK_MARKERS.items():
+        if (root / marker).exists():
+            found.append((stack, marker, desc))
+
+    workflows = root / ".github" / "workflows"
+    if workflows.is_dir():
+        n = sum(1 for f in workflows.iterdir() if f.suffix in (".yml", ".yaml"))
+        if n:
+            found.append(("GitHub Actions",
+                          f".github/workflows ({n} workflow(s))",
+                          "pipelines de CI/CD"))
+    return found
+
+
+# ---------------------------------------------------------------------------
+# VARREDURA DO FILESYSTEM
+# ---------------------------------------------------------------------------
+
+def scan(root: Path):
+    """
+    Percorre o projeto e retorna (nodes, edges, tree_lines).
+    IDs dos nós = caminho relativo à raiz ('.' para a raiz).
+    Cada nó de diretório carrega 'depth' para o contrato saber
+    quais pastas exigem documentação (depth <= DOC_DEPTH).
+    """
+    nodes, edges, tree_lines = [], [], []
+    root = root.resolve()
+    visited = set()  # (dev, inode) -> proteção contra loop de symlink
+
+    nodes.append({"id": ".", "name": root.name, "type": "dir",
+                  "role": "Raiz do projeto", "depth": 0})
+
+    def keep(entry: Path) -> bool:
+        """Filtro de ruído."""
+        name = entry.name
+        if entry.is_dir() and name in IGNORE_DIRS:
+            return False
+        if entry.is_file() and name in IGNORE_FILES:
+            return False
+        if name.startswith(".") and name not in DOTFILE_WHITELIST:
+            return False
+        return True
+
+    def walk(current: Path, parent_id: str, depth: int, prefix: str):
+        if depth > MAX_DEPTH:
+            return
+        try:
+            st = current.resolve().stat()
+            key = (st.st_dev, st.st_ino)
+        except OSError:
+            return
+        if key in visited:
+            return
+        visited.add(key)
+
+        try:
+            entries = sorted((e for e in current.iterdir() if keep(e)),
+                             key=lambda p: (p.is_file(), p.name.lower()))
+        except PermissionError:
+            return
+
+        dirs = [e for e in entries if e.is_dir()]
+        files = [e for e in entries if e.is_file()]
+
+        # Truncamento por tipo: código listado, dados colapsados por extensão
+        code_files = [f for f in files if is_code_file(f)]
+        data_files = [f for f in files if not is_code_file(f)]
+        shown_code = code_files[:MAX_CODE_FILES_PER_DIR]
+        hidden_code = len(code_files) - len(shown_code)
+        data_summary = Counter(
+            (f.suffix.lower() or "(sem extensão)") for f in data_files
+        ).most_common()
+
+        display = ([("dir", d) for d in dirs]
+                   + [("file", f) for f in shown_code]
+                   + ([("more", hidden_code)] if hidden_code else [])
+                   + [("summary", s) for s in data_summary])
+
+        for i, (kind, item) in enumerate(display):
+            last = (i == len(display) - 1)
+            connector = "└── " if last else "├── "
+            child_prefix = prefix + ("    " if last else "│   ")
+
+            if kind == "dir":
+                node_id = item.name if parent_id == "." else f"{parent_id}/{item.name}"
+                role = infer_role(item.name)
+                comment = f"  # {role}" if role else ""
+                tree_lines.append(f"{prefix}{connector}{item.name}/{comment}")
+                nodes.append({"id": node_id, "name": item.name, "type": "dir",
+                              "role": role, "depth": depth})
+                edges.append({"from": parent_id, "to": node_id, "rel": "contains"})
+                walk(item, node_id, depth + 1, child_prefix)
+
+            elif kind == "file":
+                node_id = item.name if parent_id == "." else f"{parent_id}/{item.name}"
+                tree_lines.append(f"{prefix}{connector}{item.name}")
+                nodes.append({"id": node_id, "name": item.name, "type": "file",
+                              "role": "", "depth": depth})
+                edges.append({"from": parent_id, "to": node_id, "rel": "contains"})
+
+            elif kind == "more":
+                tree_lines.append(f"{prefix}{connector}… (+{item} arquivos de código)")
+
+            elif kind == "summary":
+                ext, count = item
+                tree_lines.append(f"{prefix}{connector}({count} arquivo(s) {ext})")
+                node_id = f"*{ext}" if parent_id == "." else f"{parent_id}/*{ext}"
+                nodes.append({"id": node_id, "name": f"*{ext}", "type": "file_group",
+                              "role": "", "depth": depth, "count": count})
+                edges.append({"from": parent_id, "to": node_id, "rel": "contains"})
+
+    tree_lines.append(f"{root.name}/")
+    walk(root, ".", 1, "")
+    return nodes, edges, tree_lines
+
+
+def contract_dirs(nodes):
+    """Pastas que participam do CONTRATO (exigem responsabilidade declarada)."""
+    return [n for n in nodes
+            if n["type"] == "dir" and n["id"] != "." and n["depth"] <= DOC_DEPTH]
+
+
+def structure_hash(tree_lines, stack_info) -> str:
+    """
+    Hash da estrutura atual. Gravado no MD na geração; o check compara
+    com o recalculado para saber se o mapa está desatualizado.
+    """
+    payload = "\n".join(tree_lines) + "|" + json.dumps(sorted(stack_info))
+    return hashlib.sha1(payload.encode("utf-8")).hexdigest()[:12]
+
+
+# ---------------------------------------------------------------------------
+# PARSE DO ARCHITECTURE.md EXISTENTE (para merge e check)
+# ---------------------------------------------------------------------------
+
+def parse_existing(md_text: str):
+    """
+    Extrai do MD existente:
+      - roles: {pasta -> responsabilidade} (a curadoria humana)
+      - hash:  hash gravado na última geração (ou None)
+    Só linhas de tabela no formato `| `pasta` | descrição |` contam.
+    """
+    roles = {}
+    # Linhas de tabela cujo 1º campo é um caminho entre crases
+    for m in re.finditer(r"^\|\s*`([^`]+)`\s*\|\s*(.*?)\s*\|\s*$",
+                         md_text, re.MULTILINE):
+        path, desc = m.group(1), m.group(2)
+        # Ignora a linha de cabeçalho/separador acidentalmente casada
+        if set(desc) <= {"-", " "}:
+            continue
+        roles[path] = desc
+
+    hm = re.search(r"<!-- map:hash (\w+) -->", md_text)
+    return roles, (hm.group(1) if hm else None)
+
+
+def merge_roles(scanned_dirs, existing_roles):
+    """
+    O coração do merge: decide a responsabilidade final de cada pasta.
+      1. Se o humano escreveu algo (e não é o placeholder) -> preserva.
+      2. Senão, se há heurística por nome -> usa.
+      3. Senão -> placeholder pendente (o check vai cobrar).
+    Retorna ({pasta -> desc}, [pastas documentadas que sumiram do disco]).
+    """
+    merged = {}
+    scanned_ids = {n["id"] for n in scanned_dirs}
+
+    for n in scanned_dirs:
+        human = existing_roles.get(n["id"], "")
+        if human and human != PENDING:
+            merged[n["id"]] = human          # curadoria humana vence
+        elif n["role"]:
+            merged[n["id"]] = n["role"]      # heurística
+        else:
+            merged[n["id"]] = PENDING        # pendência explícita
+
+    # Pastas documentadas antes, mas que não existem mais (drift)
+    orphans = [p for p in existing_roles
+               if p not in scanned_ids and p != "."]
+    return merged, orphans
+
+
+# ---------------------------------------------------------------------------
+# GERAÇÃO DO MARKDOWN (com seções gerenciadas)
+# ---------------------------------------------------------------------------
+
+def render_section(name: str, body_lines) -> str:
+    """Envelopa um bloco de conteúdo nos marcadores de seção gerenciada."""
+    return "\n".join([MARK_BEGIN.format(name=name),
+                      *body_lines,
+                      MARK_END.format(name=name)])
+
+
+def render_stack(stack_info) -> str:
+    lines = ["## Stack detectada", ""]
+    if stack_info:
+        lines += ["| Tecnologia | Evidência | O que é |",
+                  "|------------|-----------|---------|"]
+        lines += [f"| {s} | `{m}` | {d} |" for s, m, d in stack_info]
+    else:
+        lines.append("_Nenhum marcador de stack encontrado na raiz._")
+    return render_section("stack", lines)
+
+
+def render_tree(tree_lines, hash_value: str) -> str:
+    lines = ["## Estrutura de pastas", "",
+             MARK_HASH.format(value=hash_value),
+             "```", *tree_lines, "```"]
+    return render_section("tree", lines)
+
+
+def render_contract(merged_roles) -> str:
+    lines = [
+        "## Responsabilidades das pastas",
+        "",
+        "<!-- Edite as descrições abaixo: elas são PRESERVADAS entre gerações. -->",
+        f"<!-- Linhas com {PENDING} são pendências: `check` falha até você preenchê-las. -->",
+        "",
+        "| Pasta | Responsabilidade |",
+        "|-------|------------------|",
+    ]
+    lines += [f"| `{p}` | {d} |" for p, d in sorted(merged_roles.items())]
+    return render_section("contract", lines)
+
+
+def build_new_markdown(root, stack_info, tree_lines, merged_roles, hash_value) -> str:
+    """Template completo — usado só quando o ARCHITECTURE.md ainda não existe."""
+    return "\n".join([
+        f"# Arquitetura — {root.name}",
+        "",
+        "> Contrato de arquitetura mantido por `archdrift.py`.",
+        "> Seções entre `<!-- map:begin/end -->` são regeneradas; o resto é seu.",
+        "",
+        render_stack(stack_info),
+        "",
+        render_tree(tree_lines, hash_value),
+        "",
+        render_contract(merged_roles),
+        "",
+        "## Notas",
+        "",
+        "_Espaço livre: decisões de arquitetura, convenções, ADRs. "
+        "O script nunca toca nesta seção._",
+        "",
+    ])
+
+
+def replace_section(md_text: str, name: str, new_block: str) -> str:
+    """
+    Substitui o conteúdo de uma seção gerenciada existente.
+    Se os marcadores não existirem (ex: MD antigo/da v1), o bloco é
+    anexado ao final — o usuário reorganiza a posição uma vez, se quiser.
+    """
+    begin = re.escape(MARK_BEGIN.format(name=name))
+    end = re.escape(MARK_END.format(name=name))
+    pattern = re.compile(begin + r".*?" + end, re.DOTALL)
+    if pattern.search(md_text):
+        # \g<0> não se aplica: substituímos o bloco inteiro pelo novo
+        return pattern.sub(lambda _: new_block, md_text)
+    return md_text.rstrip() + "\n\n" + new_block + "\n"
+
+
+# ---------------------------------------------------------------------------
+# COMANDOS
+# ---------------------------------------------------------------------------
+
+def cmd_generate(root: Path) -> int:
+    """Gera ou atualiza ARCHITECTURE.md + structure.json preservando curadoria."""
+    stack_info = detect_stack(root)
+    nodes, edges, tree_lines = scan(root)
+    cdirs = contract_dirs(nodes)
+    h = structure_hash(tree_lines, stack_info)
+
+    md_path = root / "ARCHITECTURE.md"
+    existing_roles, _ = ({}, None)
+    if md_path.exists():
+        existing_roles, _ = parse_existing(md_path.read_text(encoding="utf-8"))
+
+    merged, orphans = merge_roles(cdirs, existing_roles)
+
+    if md_path.exists():
+        # MERGE: só as seções gerenciadas mudam; o texto humano fica intacto
+        md = md_path.read_text(encoding="utf-8")
+        md = replace_section(md, "stack", render_stack(stack_info))
+        md = replace_section(md, "tree", render_tree(tree_lines, h))
+        md = replace_section(md, "contract", render_contract(merged))
+    else:
+        md = build_new_markdown(root, stack_info, tree_lines, merged, h)
+
+    md_path.write_text(md, encoding="utf-8")
+
+    # Grafo JSON com as responsabilidades FINAIS (pós-merge) aplicadas aos nós
+    for n in nodes:
+        if n["id"] in merged:
+            n["role"] = merged[n["id"]]
+    graph = {
+        "root": str(root),
+        "generated_by": "archdrift.py",
+        "hash": h,
+        "stack": [{"stack": s, "marker": m, "desc": d} for s, m, d in stack_info],
+        "nodes": nodes,
+        "edges": edges,
+    }
+    (root / "structure.json").write_text(
+        json.dumps(graph, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # Resumo no terminal
+    pending = [p for p, d in merged.items() if d == PENDING]
+    print(f"✓ {md_path} atualizado (hash {h})")
+    print(f"✓ {root / 'structure.json'} gerado ({len(edges)} arestas)")
+    if stack_info:
+        print(f"✓ Stack: {', '.join(sorted({s for s, _, _ in stack_info}))}")
+    if pending:
+        print(f"⚠ {len(pending)} pasta(s) sem responsabilidade declarada:")
+        for p in pending:
+            print(f"    - {p}")
+        print("  Edite a tabela no ARCHITECTURE.md. (`check` falha até resolver.)")
+    if orphans:
+        print(f"⚠ {len(orphans)} pasta(s) documentada(s) que não existem mais "
+              f"(removidas da tabela): {', '.join(orphans)}")
+    return 0
+
+
+def cmd_check(root: Path) -> int:
+    """
+    Valida o contrato. Pensado para CI:
+        python archdrift.py check .   # exit 1 em caso de drift
+    """
+    md_path = root / "ARCHITECTURE.md"
+    if not md_path.exists():
+        print("✗ ARCHITECTURE.md não existe. Rode `generate` primeiro.")
+        return 1
+
+    stack_info = detect_stack(root)
+    nodes, _, tree_lines = scan(root)
+    cdirs = contract_dirs(nodes)
+    current_hash = structure_hash(tree_lines, stack_info)
+
+    roles, saved_hash = parse_existing(md_path.read_text(encoding="utf-8"))
+    scanned_ids = {n["id"] for n in cdirs}
+
+    problems = []
+
+    # (a) Estrutura mudou e ninguém regenerou o mapa
+    if saved_hash is None:
+        problems.append("Mapa sem hash (formato antigo?). Rode `generate` para migrar.")
+    elif saved_hash != current_hash:
+        problems.append(
+            f"Estrutura em disco mudou desde a última geração "
+            f"(hash {saved_hash} -> {current_hash}). Rode `generate`.")
+
+    # (b) Pastas do contrato sem responsabilidade declarada
+    for n in cdirs:
+        desc = roles.get(n["id"], "")
+        if not desc or desc == PENDING:
+            problems.append(f"Pasta sem responsabilidade declarada: `{n['id']}`")
+
+    # (c) Pastas documentadas que sumiram do disco
+    for p in roles:
+        if p != "." and p not in scanned_ids:
+            problems.append(f"Pasta documentada mas inexistente em disco: `{p}`")
+
+    if problems:
+        print(f"✗ Drift de arquitetura detectado ({len(problems)} problema(s)):\n")
+        for p in problems:
+            print(f"  - {p}")
+        print("\nCorrija editando o ARCHITECTURE.md ou rode `generate` e revise o diff.")
+        return 1
+
+    print(f"✓ Arquitetura em conformidade (hash {current_hash}, "
+          f"{len(cdirs)} pastas documentadas).")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Contrato de arquitetura para agentes de código.")
+    sub = parser.add_subparsers(dest="command")
+
+    p_gen = sub.add_parser("generate", help="gera/atualiza preservando curadoria")
+    p_gen.add_argument("path", nargs="?", default=".")
+
+    p_chk = sub.add_parser("check", help="valida drift (exit 1 se divergiu)")
+    p_chk.add_argument("path", nargs="?", default=".")
+
+    # Retrocompatibilidade: `python archdrift.py <path>` == generate
+    argv = sys.argv[1:]
+    if argv and argv[0] not in ("generate", "check", "-h", "--help"):
+        argv = ["generate", *argv]
+
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"Caminho inválido ou não é diretório: {root}")
+        sys.exit(1)
+
+    if args.command == "generate":
+        sys.exit(cmd_generate(root.resolve()))
+    else:
+        sys.exit(cmd_check(root.resolve()))
+
+
+if __name__ == "__main__":
+    main()

archdrift-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: archdrift
+Version: 0.1.0
+Summary: Architecture contract for AI coding agents: a curated, human-edited ARCHITECTURE.md with drift detection in CI.
+Project-URL: Homepage, https://github.com/EvertDeveloper/archdrift
+Project-URL: Issues, https://github.com/EvertDeveloper/archdrift/issues
+Author: Everton Godoi
+License: MIT
+License-File: LICENSE
+Keywords: agents-md,ai-agents,architecture,claude-code,context-engineering,cursor,documentation,drift-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# archdrift
+
+**Architecture contract for AI coding agents.** A curated `ARCHITECTURE.md` that agents read, humans edit, and CI enforces — so your architecture docs never rot.
+
+[![CI](https://github.com/SEU_USUARIO/archdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/SEU_USUARIO/archdrift/actions)
+[![PyPI](https://img.shields.io/pypi/v/archdrift)](https://pypi.org/project/archdrift/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+---
+
+## The problem
+
+Tools like Repomix and CodeGraph are **descriptive**: they read your code and tell agents what exists. But no tool captures what your architecture is *supposed* to be — the intent behind it. So agents guess, `ARCHITECTURE.md` files rot within weeks, and nobody notices until an agent (or a new dev) builds on top of stale assumptions.
+
+## The idea
+
+`archdrift` makes your `ARCHITECTURE.md` **normative**:
+
+1. **Generated map** — folder tree, detected stack, responsibilities table. Curated for token efficiency: code files listed, assets collapsed.
+2. **Human curation that survives** — edit any description in the responsibilities table, add ADRs and notes anywhere outside the managed sections. Regeneration **never** destroys your edits.
+3. **Drift detection in CI** — `archdrift check` exits 1 when reality diverges from the documented contract. The doc can't rot, because rot breaks the build.
+
+```
+┌─────────────┐   generate    ┌─────────────────┐   read    ┌────────────┐
+│  Filesystem │ ────────────▶ │ ARCHITECTURE.md │ ────────▶ │  AI agent  │
+└─────────────┘               │  (you curate)   │           └────────────┘
+       ▲                      └─────────────────┘
+       │                               │ check (CI)
+       └───────── drift? exit 1 ◀──────┘
+```
+
+## Quick start
+
+```bash
+uvx archdrift .          # or: pipx run archdrift .
+```
+
+This generates `ARCHITECTURE.md` (the contract) and `structure.json` (the graph, for tooling). Folders without a known role get marked `_(preencher)_` — fill them in, they're preserved forever.
+
+Then enforce it in CI:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Architecture drift check
+  run: uvx archdrift check .
+```
+
+Now every PR that adds an undocumented folder, deletes a documented one, or changes structure without regenerating the map **fails the build** until someone updates the contract.
+
+## How merging works
+
+Managed sections are delimited by markers:
+
+```markdown
+<!-- map:begin tree -->
+...regenerated by the tool...
+<!-- map:end tree -->
+
+## ADR-001                      ← yours, never touched
+
+<!-- map:begin contract -->
+| Folder | Responsibility |
+| `src/models` | Prisma entities — NEVER import from controllers |  ← your edit, preserved
+<!-- map:end contract -->
+```
+
+Priority for each folder's description: **your edit** > name-based heuristic > pending placeholder.
+
+## Why not just use a repo packer / knowledge graph?
+
+Use both. Repomix, CodeGraph, aider's repo-map are excellent at telling agents *what the code is*. `archdrift` covers the piece they can't infer: *what the architecture is meant to be* — and keeps that promise honest via CI. It's `dependency-cruiser` energy, rethought for the agent era, in a single zero-dependency Python file.
+
+## Roadmap
+
+- [x] Managed sections + merge (human curation survives regeneration)
+- [x] `check` mode — drift detection with meaningful exit codes for CI
+- [x] Stack detection, token-efficient tree (type-aware truncation)
+- [ ] `AGENTS.md` integration (pointer section into the emerging convention)
+- [ ] Declarative rules (`src/controllers must-not-import src/repositories`)
+- [ ] MCP server mode
+- [ ] Semantic graph: declared dependencies vs. real imports — the diff is the product
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+MIT licensed. Issues and PRs welcome.

archdrift-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+archdrift/__init__.py,sha256=nsNQ-gNwMTbCJXQE5hxuAZsi8xB8L3GNNXT077Y8bEQ,401
+archdrift/__main__.py,sha256=0-ZTHY4-siqvXfUQB4gqCctmTfQRRuMp7uGG6nmpoSk,139
+archdrift/cli.py,sha256=wtN4M7eHuqrUpt8Awtje7l4vJZKq_XQLK5yQNtYMlzU,26459
+archdrift-0.1.0.dist-info/METADATA,sha256=JaVW_jTiA9yznZvyZS2SmZ_sDPs1DMkIaJAbKH0bMGk,5179
+archdrift-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+archdrift-0.1.0.dist-info/entry_points.txt,sha256=KOT9EKPWUJt-hgvseVUHKgetqeAy_AZpvRsLcJoIYk8,49
+archdrift-0.1.0.dist-info/licenses/LICENSE,sha256=wk-NfONivtJfZ1aaVCIbkAEC3scE2gJRRnPus141BqA,1065
+archdrift-0.1.0.dist-info/RECORD,,

archdrift-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

archdrift-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+archdrift = archdrift.cli:main

archdrift-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SEU_NOME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.