reponexia 0.1.0__tar.gz

reponexia-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RepoNexia contributors
+
+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.

reponexia-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: reponexia
+Version: 0.1.0
+Summary: CLI que explica um repositório desconhecido
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rhyan05/reponexia
+Project-URL: Repository, https://github.com/rhyan05/reponexia
+Project-URL: Issues, https://github.com/rhyan05/reponexia/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: reponexia-core==0.1.*
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: litellm; extra == "llm"
+Dynamic: license-file
+
+# RepoNexia
+
+CLI que explica um repositório desconhecido: mapeia arquitetura, entry points e
+dependências críticas, e gera um onboarding doc.
+
+Motor em Rust (`reponexia-core`) faz o scan/parse e monta o grafo; o orquestrador
+em Python chama o LLM e renderiza a documentação. A fronteira é um JSON
+versionado (`src/reponexia/graph.schema.json`).
+
+## Build e instalação
+
+**Via PyPI** (após o release):
+```bash
+pip install reponexia
+pip install "reponexia[llm]"      # LLM real (litellm)
+```
+
+**A partir do código-fonte** (clone):
+```bash
+python -m venv .venv
+# .venv\Scripts\Activate.ps1  (Windows) | source .venv/bin/activate (Unix)
+
+pip install -e .                  # usa o wheel publicado do core (sem Rust)
+# ou, para compilar/testar o core local:
+pip install ./core
+pip install -e ".[llm]"
+```
+
+O Python descobre o binário nesta ordem: `REPONEXIA_CORE` → `Scripts/bin` do
+ambiente → `PATH` → `core/target/{release,debug}`.
+
+## Uso
+
+```bash
+reponexia guia                           # guia de uso no terminal
+reponexia map <path>                     # só o core; imprime o graph.json
+reponexia graph <path> --format mermaid  # exporta o grafo (json|mermaid)
+reponexia explain <path> --dry-run       # esqueleto estrutural, sem LLM
+reponexia explain <path> --model openai/gpt-4o-mini
+reponexia ask <path> "onde fica a autenticação?"
+```
+
+O mesmo guia está em [`docs/USAGE.md`](docs/USAGE.md) (gerado por
+`reponexia guia --markdown`).
+
+No modo real o modelo vem de `--model` ou `REPONEXIA_MODEL`. `--max-tokens`
+limita o orçamento; sem mudança no repo, o cache evita novas chamadas LLM.
+
+Saída padrão em `<path>/.reponexia/`: `graph.json`, `ONBOARDING.md` e
+`architecture.mmd` (`--out` sobrescreve o diretório).
+
+Exemplo de saída: [`examples/ONBOARDING.md`](examples/ONBOARDING.md).
+
+## Segurança
+
+Antes de qualquer chamada LLM, snippets passam por `redact.py` (AWS, OpenAI,
+GitHub, Slack, chave privada e connection strings). O scan ignora `.gitignore`,
+dotfiles e `.reponexia`.
+
+## Testes
+
+```bash
+cargo test --manifest-path core/Cargo.toml
+pytest
+```

reponexia-0.1.0/README.md

@@ -0,0 +1,65 @@
+# RepoNexia
+
+CLI que explica um repositório desconhecido: mapeia arquitetura, entry points e
+dependências críticas, e gera um onboarding doc.
+
+Motor em Rust (`reponexia-core`) faz o scan/parse e monta o grafo; o orquestrador
+em Python chama o LLM e renderiza a documentação. A fronteira é um JSON
+versionado (`src/reponexia/graph.schema.json`).
+
+## Build e instalação
+
+**Via PyPI** (após o release):
+```bash
+pip install reponexia
+pip install "reponexia[llm]"      # LLM real (litellm)
+```
+
+**A partir do código-fonte** (clone):
+```bash
+python -m venv .venv
+# .venv\Scripts\Activate.ps1  (Windows) | source .venv/bin/activate (Unix)
+
+pip install -e .                  # usa o wheel publicado do core (sem Rust)
+# ou, para compilar/testar o core local:
+pip install ./core
+pip install -e ".[llm]"
+```
+
+O Python descobre o binário nesta ordem: `REPONEXIA_CORE` → `Scripts/bin` do
+ambiente → `PATH` → `core/target/{release,debug}`.
+
+## Uso
+
+```bash
+reponexia guia                           # guia de uso no terminal
+reponexia map <path>                     # só o core; imprime o graph.json
+reponexia graph <path> --format mermaid  # exporta o grafo (json|mermaid)
+reponexia explain <path> --dry-run       # esqueleto estrutural, sem LLM
+reponexia explain <path> --model openai/gpt-4o-mini
+reponexia ask <path> "onde fica a autenticação?"
+```
+
+O mesmo guia está em [`docs/USAGE.md`](docs/USAGE.md) (gerado por
+`reponexia guia --markdown`).
+
+No modo real o modelo vem de `--model` ou `REPONEXIA_MODEL`. `--max-tokens`
+limita o orçamento; sem mudança no repo, o cache evita novas chamadas LLM.
+
+Saída padrão em `<path>/.reponexia/`: `graph.json`, `ONBOARDING.md` e
+`architecture.mmd` (`--out` sobrescreve o diretório).
+
+Exemplo de saída: [`examples/ONBOARDING.md`](examples/ONBOARDING.md).
+
+## Segurança
+
+Antes de qualquer chamada LLM, snippets passam por `redact.py` (AWS, OpenAI,
+GitHub, Slack, chave privada e connection strings). O scan ignora `.gitignore`,
+dotfiles e `.reponexia`.
+
+## Testes
+
+```bash
+cargo test --manifest-path core/Cargo.toml
+pytest
+```

reponexia-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reponexia"
+version = "0.1.0"
+description = "CLI que explica um repositório desconhecido"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "jsonschema>=4.0",
+    "reponexia-core==0.1.*",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Topic :: Software Development :: Documentation",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+reponexia = "reponexia.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/rhyan05/reponexia"
+Repository = "https://github.com/rhyan05/reponexia"
+Issues = "https://github.com/rhyan05/reponexia/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+reponexia = ["graph.schema.json"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+llm = ["litellm"]

reponexia-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

reponexia-0.1.0/src/reponexia/__init__.py

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

reponexia-0.1.0/src/reponexia/__main__.py

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

reponexia-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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