reponexia 0.1.0__py3-none-any.whl

reponexia/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

reponexia/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

reponexia/ask.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from .render import render_markdown, render_mermaid
+from .summarize.litellm_impl import LiteLLMSummarizer
+
+
+# Contexto compacto do grafo para responder perguntas sem mandar código bruto.
+def build_context(graph: dict) -> str:
+    lines = [f"Repositorio com {len(graph.get('files', []))} arquivos."]
+    languages = ", ".join(graph.get("languages", [])) or "nenhuma"
+    lines.append(f"Linguagens: {languages}")
+
+    entries = graph.get("entry_points", [])
+    if entries:
+        lines.append("Entry points: " + ", ".join(e["path"] for e in entries))
+
+    metrics = sorted(
+        graph.get("metrics", []), key=lambda m: (-m["page_rank"], m["path"])
+    )[:10]
+    if metrics:
+        lines.append(
+            "Arquivos centrais: "
+            + ", ".join(f"{m['path']} (rank {m['page_rank']})" for m in metrics)
+        )
+
+    symbols = graph.get("symbols", [])[:50]
+    if symbols:
+        lines.append(
+            "Simbolos: "
+            + ", ".join(f"{s['name']}@{s['file']}:{s['line']}" for s in symbols)
+        )
+
+    edges = graph.get("edges", [])[:50]
+    if edges:
+        lines.append(
+            "Dependencias: "
+            + "; ".join(f"{e['from']} -> {e['to']}" for e in edges)
+        )
+
+    return "\n".join(lines)
+
+
+def ask(graph: dict, question: str, model: str, *, max_tokens: int = 1_000_000) -> str:
+    summarizer = LiteLLMSummarizer(model, max_tokens=max_tokens)
+    prompt = (
+        f"Contexto do repositorio:\n{build_context(graph)}\n\n"
+        f"Pergunta: {question}\n\n"
+        "Responda citando arquivo quando possivel. Nao invente fatos."
+    )
+    return summarizer._complete(prompt)

reponexia/cache.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from hashlib import sha256
+from pathlib import Path
+
+
+def cache_key(*parts: str) -> str:
+    hasher = sha256()
+    for part in parts:
+        hasher.update(part.encode("utf-8"))
+        hasher.update(b"\x00")  # separador evita colisão entre campos
+    return hasher.hexdigest()
+
+
+# Cache local em JSON: map de chave -> resumo.
+# Chave inclui repo/conteúdo do módulo + modelo, então rodar sem mudança = 0 chamadas.
+class Cache:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self._data = self._load()
+
+    def _load(self) -> dict[str, str]:
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {}
+
+    def get(self, key: str) -> str | None:
+        return self._data.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        self._data[key] = value
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(self._data, indent=2, sort_keys=True, ensure_ascii=False),
+            encoding="utf-8",
+        )

reponexia/cli.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .ask import ask
+from .cache import Cache
+from .contract import ContractError
+from .core_runner import CoreNotFound, index
+from .guide import ORDER, render as render_guide
+from .pipeline import build_narrative
+from .render import render_markdown, render_mermaid
+from .summarize.litellm_impl import (
+    BudgetExceeded,
+    LiteLLMSummarizer,
+    SummarizerError,
+)
+
+
+def _model_from(args) -> str | None:
+    # Sem hardcode de provider: flag ou variável de ambiente.
+    return args.model or os.environ.get("REPONEXIA_MODEL")
+
+
+def _write(path: Path, text: str) -> None:
+    # UTF-8 + LF fixo para o artefato ser idêntico em qualquer SO.
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8", newline="\n") as file:
+        file.write(text)
+
+
+def _json(graph: dict) -> str:
+    return json.dumps(graph, indent=2, ensure_ascii=False) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+
+    parser = argparse.ArgumentParser(prog="reponexia")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    guia_cmd = sub.add_parser("guia", help="Guia de uso no terminal")
+    guia_cmd.add_argument(
+        "topico",
+        nargs="?",
+        help="instalacao | comandos | graph | llm | config | problemas",
+    )
+    guia_cmd.add_argument(
+        "--markdown", action="store_true", help="emite markdown (para docs/USAGE.md)"
+    )
+
+    map_cmd = sub.add_parser("map", help="Mostra a estrutura do repositório (sem LLM)")
+    map_cmd.add_argument("path")
+
+    explain_cmd = sub.add_parser(
+        "explain", help="Gera o onboarding do repositório (--dry-run = sem LLM)"
+    )
+    explain_cmd.add_argument("path")
+    explain_cmd.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Roda só o core e gera o esqueleto estrutural, sem LLM",
+    )
+    explain_cmd.add_argument("--model", help="ex.: openai/gpt-4o-mini, ollama/qwen2.5-coder")
+    explain_cmd.add_argument(
+        "--max-tokens", type=int, default=1_000_000, help="orçamento de tokens do run"
+    )
+    explain_cmd.add_argument("--out", help="diretório de saída (padrão: <path>/.reponexia)")
+    explain_cmd.add_argument("--verbose", action="store_true")
+
+    graph_cmd = sub.add_parser("graph", help="Exporta o grafo do repositório")
+    graph_cmd.add_argument("path")
+    graph_cmd.add_argument("--format", choices=["json", "mermaid"], default="json")
+    graph_cmd.add_argument("--out", help="arquivo de saída (padrão: stdout)")
+
+    ask_cmd = sub.add_parser("ask", help="Pergunta sobre o índice do repositório")
+    ask_cmd.add_argument("path")
+    ask_cmd.add_argument("question")
+    ask_cmd.add_argument("--model")
+    ask_cmd.add_argument("--max-tokens", type=int, default=1_000_000)
+
+    args = parser.parse_args(argv)
+
+    # Guia não toca no core nem exige path: é o comando de quem está perdido.
+    if args.command == "guia":
+        try:
+            print(render_guide(args.topico, markdown=args.markdown))
+        except KeyError:
+            print(f"topico desconhecido: {args.topico}", file=sys.stderr)
+            print("disponiveis: " + ", ".join(ORDER), file=sys.stderr)
+            return 1
+        return 0
+
+    if args.command == "map":
+        try:
+            graph = index(args.path)
+        except (CoreNotFound, ContractError) as err:
+            print(err, file=sys.stderr)
+            return 1
+        print(json.dumps(graph, indent=2, ensure_ascii=False))
+        return 0
+
+    if args.command == "graph":
+        try:
+            graph = index(args.path)
+        except (CoreNotFound, ContractError) as err:
+            print(err, file=sys.stderr)
+            return 1
+        text = _json(graph) if args.format == "json" else render_mermaid(graph)
+        if args.out:
+            _write(Path(args.out), text)
+        else:
+            sys.stdout.write(text)
+        return 0
+
+    if args.command == "ask":
+        model = _model_from(args)
+        if not model:
+            print("defina --model ou REPONEXIA_MODEL", file=sys.stderr)
+            return 1
+        try:
+            graph = index(args.path)
+            print(ask(graph, args.question, model, max_tokens=args.max_tokens))
+        except (CoreNotFound, ContractError, SummarizerError) as err:
+            print(err, file=sys.stderr)
+            return 1
+        return 0
+
+    if args.command == "explain":
+        # No modo real exigimos modelo antes de tocar no core.
+        model = None
+        if not args.dry_run:
+            model = _model_from(args)
+            if not model:
+                print("defina --model ou REPONEXIA_MODEL (ou use --dry-run)", file=sys.stderr)
+                return 1
+
+        try:
+            graph = index(args.path)
+        except (CoreNotFound, ContractError) as err:
+            print(err, file=sys.stderr)
+            return 1
+
+        out_dir = Path(args.out) if args.out else Path(args.path).resolve() / ".reponexia"
+
+        narrative = None
+        if not args.dry_run:
+            summarizer = LiteLLMSummarizer(model, max_tokens=args.max_tokens)
+            cache = Cache(out_dir / "cache.json")
+            try:
+                narrative = build_narrative(
+                    graph, summarizer, cache=cache, verbose=args.verbose
+                )
+            except (SummarizerError, BudgetExceeded) as err:
+                print(err, file=sys.stderr)
+                return 1
+            cache.save()
+            if args.verbose:
+                print(
+                    f"[verbose] ~{summarizer.spent} tokens gastos", file=sys.stderr
+                )
+
+        _write(out_dir / "graph.json", _json(graph))
+        onboarding = out_dir / "ONBOARDING.md"
+        _write(onboarding, render_markdown(graph, narrative))
+        architecture = out_dir / "architecture.mmd"
+        _write(architecture, render_mermaid(graph))
+
+        print(f"onboarding gerado em {onboarding}")
+        print(f"arquitetura gerada em {architecture}")
+        print(f"grafo gerado em {out_dir / 'graph.json'}")
+        return 0
+
+    return 1

reponexia/contract.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+import jsonschema
+
+
+class ContractError(ValueError):
+    """O graph.json produzido pelo core viola o contrato."""
+
+
+@lru_cache(maxsize=1)
+def load_schema() -> dict:
+    override = os.environ.get("REPONEXIA_CONTRACT")
+    if override:
+        path = Path(override)
+    else:
+        path = Path(__file__).with_name("graph.schema.json")
+
+    if not path.exists():
+        raise ContractError(f"schema do contrato nao encontrado em {path}")
+
+    with path.open(encoding="utf-8") as file:
+        try:
+            return json.load(file)
+        except json.JSONDecodeError as err:
+            raise ContractError(f"schema invalido em {path}: {err}") from err
+
+
+def validate(graph: dict) -> None:
+    schema = load_schema()
+
+    try:
+        jsonschema.validate(instance=graph, schema=schema)
+    except jsonschema.ValidationError as err:
+        raise ContractError(
+            f"graph.json invalido em {err.json_path}: {err.message}"
+        ) from err
+    except jsonschema.SchemaError as err:
+        raise ContractError(f"schema invalido: {err.message}") from err

reponexia/core_runner.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .contract import validate
+
+
+class CoreNotFound(RuntimeError):
+    pass
+
+
+def find_core() -> Path:
+    override = os.environ.get("REPONEXIA_CORE")
+    if override:
+        return Path(override)
+
+    exe = "reponexia-core.exe" if os.name == "nt" else "reponexia-core"
+
+    # 1. Binário instalado pelo pip no mesmo ambiente (Scripts/bin do venv).
+    #    Não depende do PATH estar ativo, o que falha quando o comando é
+    #    chamado por subprocess/serviço.
+    packaged = Path(sys.executable).parent / exe
+    if packaged.exists():
+        return packaged
+
+    # 2. Binário disponível no PATH.
+    on_path = shutil.which(exe)
+    if on_path:
+        return Path(on_path)
+
+    # 3. Build local a partir do código-fonte (modo desenvolvimento).
+    root = Path(__file__).resolve().parents[2]
+    for profile in ("release", "debug"):
+        candidate = root / "core" / "target" / profile / exe
+        if candidate.exists():
+            return candidate
+
+    raise CoreNotFound(
+        "reponexia-core não encontrado. Instale com `pip install ./core`, rode "
+        "`cargo build --release` em core/ ou defina a variável REPONEXIA_CORE."
+    )
+
+# Faz a indexação do path usando o core e retorna o grafo resultante
+def index(path: str | Path) -> dict:
+    core = find_core()
+    proc = subprocess.run(
+        [str(core), "index", str(path)],
+        capture_output=True,
+        check=True,
+    )
+    stdout = proc.stdout.decode("utf-8", errors="replace")
+    graph = json.loads(stdout)
+
+    # Valida o grafo retornado pelo core contra o contrato
+    validate(graph)
+    return graph

reponexia/graph.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://reponexia.dev/contract/graph.schema.json",
+  "title": "RepoNexia graph",
+  "description": "Contrato entre o motor Rust e o orquestrador Python. Versão 1.0.",
+  "type": "object",
+  "required": ["schema_version", "root", "files"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+$"
+    },
+    "root": {
+      "type": "string",
+      "description": "Raiz absoluta do repositório analisado."
+    },
+    "repo_hash": {
+      "type": "string",
+      "description": "Hash do hash de todos os arquivos. Permite cache O(1)."
+    },
+    "languages": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "language", "loc", "hash"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Caminho relativo à raiz, sempre com '/' como separador."
+          },
+          "language": { "type": "string" },
+          "loc": { "type": "integer", "minimum": 0 },
+          "hash": { "type": "string" },
+          "parse_errors": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["message"],
+        "properties": {
+          "path": { "type": "string" },
+          "message": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "symbols":{
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "file", "name", "kind", "line", "exported"],
+        "properties": {
+          "id": { "type": "string" },
+          "file": { "type": "string" },
+          "name": { "type": "string" },
+          "kind": { "type": "string", "enum": ["function", "class", "method"] },
+          "line": { "type": "integer", "minimum": 1 },
+          "exported": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "edges":{
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind", "line"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "kind": { "type": "string", "enum": ["import", "call", "extends", "implements"] },
+          "symbol": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "metrics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "fan_in", "fan_out", "page_rank"],
+        "properties": {
+          "path": { "type": "string" },
+          "fan_in": { "type": "integer", "minimum": 0 },
+          "fan_out": { "type": "integer", "minimum": 0 },
+          "page_rank": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "entry_points": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind", "evidence"],
+        "properties": {
+          "path": { "type": "string" },
+          "kind": { "type": "string", "enum": ["main", "bin", "console_script","package_main"] },
+          "evidence": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": true
+}

reponexia/guide.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+# Fonte única do guia: o comando `reponexia guia` e docs/USAGE.md saem daqui.
+ORDER = ["instalacao", "comandos", "graph", "llm", "config", "problemas"]
+
+TOPICS: dict[str, str] = {
+    "instalacao": """## Instalação
+
+Via PyPI (pacote publicado):
+  pip install reponexia
+  pip install "reponexia[llm]"        # para usar o LLM real
+
+A partir do código-fonte (clone):
+  python -m venv .venv
+  .venv\\Scripts\\Activate.ps1          # Linux/macOS: source .venv/bin/activate
+
+  # Opção A (após publicar): usa o wheel do core, sem Rust
+  pip install -e .
+
+  # Opção B (testar o core local): compila o Rust
+  pip install ./core
+  pip install -e ".[llm]"
+
+O binário do motor é procurado nesta ordem:
+  REPONEXIA_CORE -> Scripts do ambiente -> PATH -> core/target/{release,debug}""",
+    "comandos": """## Comandos
+
+  reponexia guia [topico]               Este guia
+  reponexia map <path>                  Estrutura do repo (JSON, sem LLM)
+  reponexia graph <path> [--format]     Exporta o grafo (json|mermaid)
+  reponexia explain <path> --dry-run    Onboarding estrutural, sem LLM
+  reponexia explain <path> --model ...  Onboarding com LLM
+  reponexia ask <path> "pergunta"       Pergunta sobre o índice""",
+    "graph": """## Ver os dados do grafo
+
+  reponexia map .                                 JSON no terminal
+  reponexia graph . --out graph.json              salva JSON (UTF-8)
+  reponexia graph . --format mermaid --out architecture.mmd
+  reponexia explain . --dry-run                   gera .reponexia/{ONBOARDING.md,architecture.mmd,graph.json}
+  reponexia graph . | jq '.edges'                 filtra com jq (se instalado)
+
+Visualizar o Mermaid: https://mermaid.live ou extensão do VS Code.
+Atenção (PowerShell 5.1): `>` grava UTF-16; prefira `--out`.
+O graph.json contém só metadados (arquivos, símbolos, arestas, métricas), sem código.""",
+    "llm": """## LLM
+
+  reponexia explain . --model openai/gpt-4o-mini
+  REPONEXIA_MODEL=... reponexia explain .
+  --max-tokens N        teto de orçamento do run (estimativa)
+  Cache em .reponexia/cache.json: rodar sem mudança = 0 chamadas.
+
+Providers via litellm: OpenAI, Anthropic, Ollama, etc.
+Configure a env do provider (ex.: OPENAI_API_KEY, ANTHROPIC_API_KEY).
+Ollama local: --model ollama/qwen2.5-coder""",
+    "config": """## Configuração
+
+  REPONEXIA_CORE      caminho do binário do motor
+  REPONEXIA_MODEL     modelo padrão (usado quando --model não é passado)
+  REPONEXIA_CONTRACT  caminho alternativo do graph.schema.json
+  --out DIR           diretório de saída (padrão: <path>/.reponexia)""",
+    "problemas": """## Problemas comuns
+
+  "reponexia-core não encontrado"
+    -> pip install ./core  (ou cargo build --release em core/ e aponte REPONEXIA_CORE)
+
+  "defina --model ou REPONEXIA_MODEL"
+    -> passe --model ou use --dry-run
+
+  "graph.json invalido ... schema"
+    -> motor e orquestrador com versões diferentes; atualize os dois.
+
+  Mermaid vazio
+    -> não há dependências internas resolvidas; rode `reponexia map .` e veja `edges`.""",
+}
+
+
+def render(topic: str | None = None, *, markdown: bool = False) -> str:
+    if topic is None:
+        body = "\n\n".join(TOPICS[key] for key in ORDER)
+    else:
+        key = topic.strip().lower()
+        if key not in TOPICS:
+            raise KeyError(key)
+        body = TOPICS[key]
+
+    if markdown:
+        return f"# RepoNexia — Guia de uso\n\n{body}"
+    return body

reponexia/modules.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import PurePosixPath
+
+
+# Modulo = pai do arquivo, ou "(raiz)" se o arquivo estiver na raiz
+def module_of(path: str) -> str:
+    # Retorna o módulo pai do arquivo, ou "(raiz)" se o arquivo estiver na raiz
+    parent = str(PurePosixPath(path).parent)
+    return "(raiz)" if parent == "." else parent
+
+# Agrupa os arquivos por módulo, retornando um dicionário {modulo: [arquivos]}
+def group_files_by_module(files: list[dict]) -> dict[str,list[dict]]:
+    groups: dict[str, list[dict]] = defaultdict(list)
+    for file in files:
+        groups[module_of(file["path"])].append(file)
+    return {
+        name: sorted(members, key=lambda f: f["path"])
+        for name, members in groups.items()
+    }