higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/eval_agent.py

@@ -0,0 +1,80 @@
+"""Capability common.eval-agent — puente entre el CLI de higpertext y el suite pytest de evaluación.
+
+Uso:
+    htx task eval-agent --mode static
+    htx task eval-agent --mode hooks
+    htx task eval-agent --mode behavioral --provider gemini --profile sre
+    htx task eval-agent --mode all --provider anthropic
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+# Ejecuta pytest con comando construido internamente.
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+ROOT_DIR = Path(__file__).resolve().parents[5]
+EVAL_DIR = ROOT_DIR / "tests" / "eval"
+
+_MARKER_MAP = {
+    "static": "static",
+    "behavioral": "behavioral",
+    "hooks": "hooks",
+    "safety": "safety",
+    "all": None,
+}
+
+
+def _parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="higpertext Eval Agent — framework de evaluación de modelos"
+    )
+    p.add_argument("--profile", default="all", help="Perfil a evaluar (default: all)")
+    p.add_argument("--mode", default="static", choices=list(_MARKER_MAP), help="Modo de evaluación")
+    p.add_argument(
+        "--provider",
+        default="",
+        help="Provider LLM para behavioral/safety: gemini | anthropic",
+    )
+    return p.parse_args()
+
+
+def _build_cmd(mode: str, profile: str) -> list[str]:
+    cmd = [sys.executable, "-m", "pytest", str(EVAL_DIR), "-v", "--tb=short"]
+    marker = _MARKER_MAP[mode]
+    if marker:
+        cmd += ["-m", marker]
+    if profile != "all":
+        cmd += ["--profile", profile]
+    return cmd
+
+
+def main() -> None:
+    args = _parse_args()
+    env = os.environ.copy()
+
+    if args.provider:
+        env["HIGPERTEXT_LLM_PROVIDER"] = args.provider
+
+    if args.mode in ("behavioral", "safety", "all") and not env.get("RUN_BEHAVIORAL_TESTS"):
+        _log.info(
+            "[eval-agent] AVISO: RUN_BEHAVIORAL_TESTS no configurada.\n"
+            "Los tests behavioral y safety serán skipped.\n"
+            "Para activarlos: $env:RUN_BEHAVIORAL_TESTS=1"
+        )
+
+    cmd = _build_cmd(args.mode, args.profile)
+    _log.info(f"[eval-agent] Ejecutando: {' '.join(cmd)}\n")
+
+    result = subprocess.run(cmd, env=env, cwd=str(ROOT_DIR))
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/file_map.py

@@ -0,0 +1,95 @@
+"""common.file-map — mapa compacto de archivos para exploración sin blobs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess  # nosec B404
+from collections import Counter, defaultdict
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_HEAVY_ASSET_PATTERNS = ("*.min.js", "*.bundle.min.js", "*.min.css", "*.map")
+
+
+def _git_files() -> list[str]:
+    result = subprocess.run(["git", "ls-files"], capture_output=True, text=True)  # nosec B603 B607
+    return result.stdout.splitlines() if result.returncode == 0 else []
+
+
+def _is_heavy_asset(path: str) -> bool:
+    p = Path(path)
+    if "assets" not in p.parts:
+        return False
+    return any(p.match(pattern) for pattern in _HEAVY_ASSET_PATTERNS)
+
+
+def build_map(
+    path: str, max_depth: int, large_threshold_kb: int, include_assets: bool = False
+) -> dict:
+    prefix = path.strip().strip("/")
+    files = [f for f in _git_files() if not prefix or f == prefix or f.startswith(f"{prefix}/")]
+    skipped_assets = [f for f in files if _is_heavy_asset(f)]
+    if not include_assets:
+        files = [f for f in files if not _is_heavy_asset(f)]
+    dirs: dict[str, int] = defaultdict(int)
+    extensions: Counter[str] = Counter()
+    large = []
+    for file in files:
+        rel = file[len(prefix) + 1 :] if prefix and file.startswith(f"{prefix}/") else file
+        top = "/".join(Path(rel).parts[:max_depth]) or "."
+        dirs[top] += 1
+        extensions[Path(file).suffix or "[sin extensión]"] += 1
+        p = Path(file)
+        if p.exists() and p.stat().st_size / 1024 >= large_threshold_kb:
+            large.append({"path": file, "kb": round(p.stat().st_size / 1024, 1)})
+    return {
+        "path": path or ".",
+        "total": len(files),
+        "directories": dict(sorted(dirs.items())),
+        "extensions": dict(extensions.most_common()),
+        "large_files": large[:20],
+        "skipped_heavy_assets": len(skipped_assets) if not include_assets else 0,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Mapa compacto de archivos")
+    parser.add_argument("--path", default="")
+    parser.add_argument("--preset", default="all")  # reservado para compatibilidad con plan
+    parser.add_argument("--max_depth", type=int, default=2)
+    parser.add_argument("--show_sizes", default="false")
+    parser.add_argument("--large_threshold_kb", type=int, default=100)
+    parser.add_argument("--include_assets", default="false")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    include_assets = args.include_assets.lower() in {"true", "1", "yes"}
+    data = build_map(args.path, args.max_depth, args.large_threshold_kb, include_assets)
+    if args.json.lower() in {"true", "1", "yes"}:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return
+    _log.info("╔─ HIGPERTEXT · File Map ────────────────────────────────────")
+    _log.info(f"│ Path  : {data['path']}")
+    _log.info(f"│ Total : {data['total']} archivo(s)")
+    _log.info("╠─ Directorios ──────────────────────────────────────────────")
+    for directory, count in list(data["directories"].items())[:50]:
+        _log.info(f"│ {directory}: {count}")
+    _log.info("╠─ Extensiones ──────────────────────────────────────────────")
+    for ext, count in data["extensions"].items():
+        _log.info(f"│ {ext}: {count}")
+    if data["large_files"]:
+        _log.info("╠─ Grandes ─────────────────────────────────────────────────")
+        for item in data["large_files"]:
+            _log.info(
+                f"│ {item['path']} ({item['kb']} KB) → htx task common.smart-read --path {item['path']} --mode auto" # noqa: E501
+            )
+    if data["skipped_heavy_assets"]:
+        _log.info(f"│ Assets pesados omitidos: {
+                data['skipped_heavy_assets']} (usa --include_assets true)")
+    _log.info("╚────────────────────────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/governance_exception.py

@@ -0,0 +1,116 @@
+"""common.governance-exception — registra y lista excepciones de gobernanza."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from pathlib import Path
+
+_HERE = Path(__file__).resolve()
+_PROJECT_ROOT = next(
+    (p for p in _HERE.parents if (p / "src/config/htx_config.json").exists()),
+    _HERE.parents[4],
+)
+sys.path.insert(0, str(_PROJECT_ROOT / "src"))
+
+from higpertext.kernel.application.governance import ExceptionRegistry  # noqa: E402
+from higpertext.kernel.domain.governance import GovernanceException, Severity  # noqa: E402
+from higpertext.kernel.infrastructure.governance import ContractLoader  # noqa: E402
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _get_active_profile() -> str:
+    env_file = _PROJECT_ROOT / WORKSPACE_DIR_NAME / "config" / "environment.json"
+    if env_file.exists():
+        try:
+            return json.loads(env_file.read_text(encoding="utf-8")).get("active_profile", "global")
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+    return "global"
+
+
+def _rule_is_critical(rule_id: str) -> bool:
+    loader = ContractLoader(_PROJECT_ROOT)
+    for rule in loader.load():
+        if rule.id == rule_id and rule.severity == Severity.CRITICAL:
+            return True
+    return False
+
+
+def cmd_register(args: argparse.Namespace, registry: ExceptionRegistry) -> None:
+    if not args.rule_id:
+        _log.error("[ERROR] --rule_id es requerido para register.")
+        sys.exit(1)
+    if not args.reason:
+        _log.error("[ERROR] --reason es requerido para register.")
+        sys.exit(1)
+    if not args.approver:
+        _log.error("[ERROR] --approver es requerido para register.")
+        sys.exit(1)
+
+    if _rule_is_critical(args.rule_id):
+        _log.info(f"[BLOCK] La regla '{args.rule_id}' es CRITICAL — no se puede exceptuar.")
+        sys.exit(1)
+
+    profile = args.profile or _get_active_profile()
+    expires = date.fromisoformat(args.expires) if args.expires else None
+
+    exc = GovernanceException(
+        rule_id=args.rule_id,
+        reason=args.reason,
+        approver=args.approver,
+        profile=profile,
+        expires=expires,
+    )
+    registry.register(exc)
+
+    _log.ok(f"[SUCCESS] Excepción registrada para regla '{args.rule_id}' en perfil '{profile}'.")
+    if expires:
+        _log.info(f"  Expira: {expires.isoformat()}")
+    _log.info(f"  Aprobador: {args.approver}")
+    _log.info(f"  Motivo: {args.reason}")
+
+
+def cmd_list(args: argparse.Namespace, registry: ExceptionRegistry) -> None:
+    profile = args.profile or _get_active_profile()
+    exceptions = registry.list_active(profile)
+
+    if not exceptions:
+        _log.info(f"[*] No hay excepciones activas para el perfil '{profile}'.")
+        return
+
+    _log.info(f"\n Excepciones activas — perfil: {profile}\n")
+    _log.info(f"  {'Regla':<35} {'Aprobador':<15} {'Expira':<12} Motivo")
+    _log.info(f"  {'-' * 35} {'-' * 15} {'-' * 12} {'-' * 30}")
+    for exc in exceptions:
+        exp = exc.expires.isoformat() if exc.expires else "indefinido"
+        _log.info(f"  {exc.rule_id:<35} {exc.approver:<15} {exp:<12} {exc.reason[:40]}")
+    _log.info("")
+    _log.ok("[SUCCESS] Listado completado.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="higpertext Governance Exception Manager")
+    parser.add_argument("--action", required=True, choices=["register", "list"])
+    parser.add_argument("--rule_id", default="")
+    parser.add_argument("--reason", default="")
+    parser.add_argument("--approver", default="")
+    parser.add_argument("--expires", default="")
+    parser.add_argument("--profile", default="")
+    args = parser.parse_args()
+
+    registry = ExceptionRegistry(_PROJECT_ROOT)
+
+    if args.action == "register":
+        cmd_register(args, registry)
+    else:
+        cmd_list(args, registry)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/graph_query.py

@@ -0,0 +1,104 @@
+"""Capability common.graph-query — consulta el grafo semántico por keyword."""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+def _resolve_core() -> Path:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        core = parent / "src" / "core"
+        if core.exists():
+            return core
+    raise RuntimeError("No se encontró src/core")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Consulta el grafo semántico.")
+    parser.add_argument("--symbol", required=True, help="Keyword o nombre de símbolo.")
+    parser.add_argument("--depth", type=int, default=2)
+    parser.add_argument("--budget", type=int, default=8000)
+    parser.add_argument(
+        "--type", default="", help="Filtra tipo: class,function,method,variable,module"
+    )
+    parser.add_argument("--limit", type=int, default=50, help="Máximo de símbolos a mostrar")
+    parser.add_argument(
+        "--files_only",
+        default="false",
+        help="Muestra solo archivos únicos (true/false)",
+    )
+    parser.add_argument("--json", default="false", help="Emite JSON estructurado (true/false)")
+    args = parser.parse_args()
+
+    core = _resolve_core()
+    if str(core) not in sys.path:
+        sys.path.insert(0, str(core))
+    sys.path.insert(0, str(core.parent.parent))
+
+    root = Path(".").resolve()
+    graph_path = root / WORKSPACE_DIR_NAME / "state" / "semantic_graph.json"
+    if not graph_path.exists():
+        _log.error("[ERROR] semantic_graph.json no encontrado. Ejecuta: htx task common.graph-rebuild")
+        sys.exit(1)
+
+    from higpertext.semantic_engine.infrastructure.graph_store import GraphStore
+    from higpertext.semantic_engine.application.context_ranker import ContextRanker
+
+    graph = GraphStore(root=root).load()
+    ranker = ContextRanker(graph)
+    results = ranker.rank(keywords=[args.symbol], budget=args.budget, depth=args.depth)
+    if args.type:
+        results = [s for s in results if s.type.value == args.type]
+    results = results[: max(1, args.limit)]
+
+    if not results:
+        _log.info(f"[NOT FOUND] No se encontraron símbolos relacionados con '{args.symbol}'.")
+        sys.exit(0)
+
+    if args.json.lower() in {"true", "1", "yes"}:
+        print(
+            json.dumps(
+                {
+                    "keyword": args.symbol,
+                    "depth": args.depth,
+                    "count": len(results),
+                    "symbols": [
+                        {
+                            "type": s.type.value,
+                            "name": s.name,
+                            "file": s.file,
+                            "line": s.line,
+                        }
+                        for s in results
+                    ],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return
+
+    _log.info("╔─ HIGPERTEXT · Graph Query ──────────────────────────────────")
+    _log.info(f"│  Keyword  : {args.symbol}")
+    _log.info(f"│  Depth    : {args.depth}")
+    _log.info(f"│  Símbolos : {len(results)}")
+    _log.info("╠───────────────────────────────────────────────────────")
+    if args.files_only.lower() in {"true", "1", "yes"}:
+        for file in sorted({s.file for s in results}):
+            _log.info(f"│  {file}")
+        _log.info("╚───────────────────────────────────────────────────────")
+        _log.ok(f"\n[SUCCESS] {len(set(s.file for s in results))} archivo(s) encontrados.")
+        return
+    for s in results:
+        _log.info(f"│  [{s.type.value:8}] {s.name:30} {s.file}:{s.line}")
+    _log.info("╚───────────────────────────────────────────────────────")
+    _log.ok(f"\n[SUCCESS] {len(results)} símbolos encontrados.")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/graph_rebuild.py

@@ -0,0 +1,107 @@
+"""Capability common.graph-rebuild — regenera el grafo semántico del proyecto."""
+
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _resolve_core() -> Path:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        core = parent / "src" / "core"
+        if core.exists():
+            return core
+    raise RuntimeError("No se encontró src/core")
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Regenera el grafo semántico.")
+    parser.add_argument("--root", default=".", help="Directorio raíz del proyecto.")
+    parser.add_argument("--god_threshold", type=int, default=5)
+    parser.add_argument(
+        "--incremental",
+        type=lambda x: x.lower() != "false",
+        default=True,
+        help="Usa caché incremental (default: true). Pasa false para rebuild completo.",
+    )
+    return parser.parse_args()
+
+
+def _setup_path() -> None:
+    core = _resolve_core()
+    if str(core) not in sys.path:
+        sys.path.insert(0, str(core))
+    sys.path.insert(0, str(core.parent.parent))
+
+
+def _print_summary(root, graph, god_nodes, clusters, path, stats, threshold) -> None:
+    mode = "incremental" if stats.get("skipped", 0) > 0 else "full"
+    _log.info("╔─ HIGPERTEXT · Graph Rebuild ────────────────────────────────")
+    _log.info(f"│  Modo               : {mode} (parsed={stats['parsed']}, skipped={stats['skipped']})")
+    _log.info(f"│  Símbolos indexados : {graph.symbol_count}")
+    _log.info(f"│  Relaciones         : {graph.relation_count}")
+    _log.info(f"│  God nodes          : {len(god_nodes)} (threshold={threshold})")
+    _log.info(f"│  Comunidades        : {len(clusters)}")
+    _log.info(f"│  Artefacto          : {path.relative_to(root)}")
+    _log.info("╚───────────────────────────────────────────────────────")
+    if god_nodes:
+        _log.warning("\n⚠  God nodes detectados:")
+        for n in god_nodes:
+            _log.info(f"   • {n.name} ({n.file}:{n.line})")
+    _log.ok("\n[SUCCESS] Grafo semántico regenerado.")
+
+
+def main() -> None:
+    args = _parse_args()
+    _setup_path()
+
+    from higpertext.semantic_engine.application.graph_builder import GraphBuilder
+    from higpertext.semantic_engine.application.cluster_service import ClusterService
+    from higpertext.semantic_engine.infrastructure.graph_store import GraphStore
+
+    root = Path(args.root).resolve()
+    _log.info(f"[*] Analizando proyecto: {root} (incremental={args.incremental})")
+
+    builder = GraphBuilder()
+    result = builder.build_with_stats(root=root, incremental=args.incremental)
+    graph, stats = result["graph"], result
+
+    store = GraphStore(root=root)
+    path = store.save(graph)
+
+    god_nodes = graph.god_nodes(threshold=args.god_threshold)
+    clusters = ClusterService().detect(graph)
+    _update_summary_md(root, graph, god_nodes, clusters)
+    _print_summary(root, graph, god_nodes, clusters, path, stats, args.god_threshold)
+
+
+def _update_summary_md(root, graph, god_nodes, clusters) -> None:
+    md_path = root / WORKSPACE_DIR_NAME / "state" / "semantic_graph.md"
+    lines = [
+        "# Project Semantic Graph\n",
+        "\nThis file is auto-generated by `common.graph-rebuild`. Do not edit manually.\n",
+        f"\n## Overview\n- **Total symbols**: {graph.symbol_count}\n",
+        f"- **Total relations**: {graph.relation_count}\n",
+        f"- **God nodes**: {len(god_nodes)}\n",
+        f"- **Communities**: {len(clusters)}\n",
+        "\n## God Nodes\n",
+    ]
+    if god_nodes:
+        for n in god_nodes:
+            lines.append(f"- `{n.name}` — `{n.file}:{n.line}`\n")
+    else:
+        lines.append("_None detected._\n")
+
+    lines.append("\n## Communities\n")
+    for c in clusters:
+        lines.append(f"- **{c.id}** ({c.size} symbols)\n")
+
+    md_path.write_text("".join(lines), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/graph_visualize.py

@@ -0,0 +1,76 @@
+"""Capability common.graph-visualize — genera HTML interactivo D3.js del grafo."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from higpertext.kernel.pkg_resources import resolve_resource
+from higpertext.kernel.config_paths import PROJECT_ROOT
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _load_graph(graph_path: Path, max_nodes: int) -> tuple[list, list]:
+    raw = json.loads(graph_path.read_text(encoding="utf-8"))
+    symbols = raw["symbols"][:max_nodes]
+    allowed_ids = {f"{s['file']}::{s['name']}" for s in symbols}
+    nodes = [
+        {"id": f"{s['file']}::{s['name']}", "label": s["name"], "type": s["type"]} for s in symbols
+    ]
+    links = [
+        {"source": r["source"], "target": r["target"]}
+        for r in raw["relations"]
+        if r["source"] in allowed_ids and r["target"] in allowed_ids
+    ]
+    return nodes, links
+
+
+def _render(nodes: list, links: list, god_threshold: int, out: Path) -> None:
+    template_path = resolve_resource(
+        PROJECT_ROOT, "src", "higpertext", "templates", "html", "graph_visualize.html"
+    )
+    if not template_path.exists():
+        raise FileNotFoundError(f"Plantilla HTML no encontrada: {template_path}")
+    template = template_path.read_text(encoding="utf-8")
+    
+    html = (
+        template.replace("{node_count}", str(len(nodes)))
+        .replace("{edge_count}", str(len(links)))
+        .replace("{god_threshold}", str(god_threshold))
+        .replace("{graph_json}", json.dumps({"nodes": nodes, "links": links}))
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(html, encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Genera grafo HTML interactivo.")
+    parser.add_argument("--output", default=".higpertext/reports/semantic_graph.html")
+    parser.add_argument("--max_nodes", type=int, default=200)
+    parser.add_argument("--god_threshold", type=int, default=5)
+    args = parser.parse_args()
+
+    graph_path = Path(".").resolve() / WORKSPACE_DIR_NAME / "state" / "semantic_graph.json"
+    if not graph_path.exists():
+        _log.error("[ERROR] semantic_graph.json no encontrado. Ejecuta: htx task common.graph-rebuild")
+        sys.exit(1)
+
+    nodes, links = _load_graph(graph_path, args.max_nodes)
+    out = Path(args.output)
+    _render(nodes, links, args.god_threshold, out)
+
+    _log.info("╔─ HIGPERTEXT · Graph Visualize ──────────────────────────────")
+    _log.info(f"│  Nodos renderizados : {len(nodes)}")
+    _log.info(f"│  Aristas            : {len(links)}")
+    _log.info(f"│  God threshold      : {args.god_threshold}")
+    _log.info(f"│  Artefacto          : {out}")
+    _log.info("╚───────────────────────────────────────────────────────")
+    _log.ok(f"\n[SUCCESS] Abre en tu navegador: {out}")
+
+
+if __name__ == "__main__":
+    main()