higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/infrastructure/logger.py

@@ -0,0 +1,303 @@
+"""Higpertext CLI Logger — infraestructura de logging para la CLI.
+
+Provee un logger estructurado con:
+- Salida a consola con colores ANSI (nivel configurable).
+- Rotación de archivo en .higpertext/logs/htx.log (sin dependencias externas).
+- Niveles semánticos: info, ok, warn, error, debug alineados con el estilo de la CLI.
+- `event_block()` — emite un bloque estructurado AI-legible en un solo call.
+- Factory `get_logger` para obtener la instancia singleton configurada.
+
+Formato de bloque (AI-legible):
+    ╔─ htx · <event> ─────────────────────────────────────────
+    │  status              : ok
+    │  sessions_analyzed   : 12
+    │  ...
+    ╚─────────────────────────────────────────────────────────
+
+Uso:
+    from higpertext.kernel.infrastructure.logger import get_logger
+    log = get_logger(project_root=root)
+    log.event_block("profile-learn", status="ok", fields={
+        "sessions_analyzed": 12,
+        "calibration_mode": "z-score",
+    })
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+# ── Constantes ────────────────────────────────────────────────────────────────
+
+from higpertext.kernel.app_config import LOGGER_NAME, LOG_FILE as _LOG_FILE
+_MAX_BYTES = 1_048_576  # 1 MB
+_BACKUP_COUNT = 3
+_DEFAULT_LEVEL = logging.INFO
+
+# Nivel personalizado OK (entre INFO y WARNING)
+_OK_LEVEL = 25
+logging.addLevelName(_OK_LEVEL, "OK")
+
+_BOX_WIDTH = 57  # ancho interior del bloque ╔─…╚─
+
+# ── Colores ANSI ──────────────────────────────────────────────────────────────
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+
+_COLORS: dict[int, str] = {
+    logging.DEBUG: "\033[36m",    # cyan
+    logging.INFO: "\033[34m",     # blue
+    _OK_LEVEL: "\033[32m",        # green
+    logging.WARNING: "\033[33m",  # yellow
+    logging.ERROR: "\033[31m",    # red
+    logging.CRITICAL: "\033[35m", # magenta
+}
+
+_PREFIX: dict[int, str] = {
+    logging.DEBUG: "[DBG]",
+    logging.INFO: "[*]  ",
+    _OK_LEVEL: "[OK] ",
+    logging.WARNING: "[!]  ",
+    logging.ERROR: "[ERR]",
+    logging.CRITICAL: "[!!!]",
+}
+
+_STATUS_ICON: dict[str, str] = {
+    "ok": "✓",
+    "error": "✗",
+    "warn": "⚠",
+    "skip": "—",
+}
+
+
+# ── Formatters ────────────────────────────────────────────────────────────────
+
+class _ColorFormatter(logging.Formatter):
+    """Formatter con colores ANSI para salida en consola."""
+
+    _use_color: bool = sys.stdout.isatty() and os.getenv("NO_COLOR") is None
+
+    def format(self, record: logging.LogRecord) -> str:
+        level = record.levelno
+        prefix = _PREFIX.get(level, "[?]  ")
+        msg = super().format(record)
+
+        if self._use_color:
+            color = _COLORS.get(level, "")
+            return f"{color}{_BOLD}{prefix}{_RESET} {msg}"
+        return f"{prefix} {msg}"
+
+
+class _PlainFormatter(logging.Formatter):
+    """Formatter sin colores para archivos de log."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        prefix = _PREFIX.get(record.levelno, "[?]  ")
+        return f"{prefix} {super().format(record)}"
+
+
+# ── Bloque estructurado ───────────────────────────────────────────────────────
+
+def _build_event_block(
+    event: str,
+    status: str,
+    fields: dict[str, Any],
+) -> str:
+    """Construye un bloque de texto estructurado AI-legible.
+
+    El formato es intencionalmente consistente con el banner de session_stop
+    para que el asistente pueda parsearlo mediante texto plano.
+
+        ╔─ htx · profile-learn ───────────────────────────────────
+        │  status              : ✓ ok
+        │  sessions_analyzed   : 12
+        │  calibration_mode    : z-score
+        │  adoption_pct        : 78%
+        ╚─────────────────────────────────────────────────────────
+    """
+    title = f"htx · {event}"
+    header_fill = "─" * max(0, _BOX_WIDTH - len(title) - 1)
+    header = f"╔─ {title} {header_fill}"
+
+    icon = _STATUS_ICON.get(status, status)
+    rows: list[str] = [f"│  {'status':<20}: {icon} {status}"]
+
+    # Calcula el ancho de la columna de claves
+    max_key = max((len(k) for k in fields), default=6)
+    col = max(max_key, 20)
+
+    for key, value in fields.items():
+        val_str = str(value) if value not in (None, "", []) else "—"
+        rows.append(f"│  {key:<{col}}: {val_str}")
+
+    footer = "╚" + "─" * (_BOX_WIDTH + 2)
+
+    return "\n".join([header, *rows, footer])
+
+
+# ── Caja genérica ─────────────────────────────────────────────────────────────
+
+def render_box(title: str, lines: list[str]) -> str:
+    """Construye un bloque de caja ╔─ … ╚─ como string.
+
+    Uso desde hooks/RuleResult (canal LLM) o cualquier código que necesite
+    el string antes de decidir cómo emitirlo.
+
+        render_box("HIGPERTEXT · Loop Guard · BLOQUEADO", [
+            f"│  Herramienta : {tool}",
+            "│  Acción      : cambia el enfoque",
+        ])
+    """
+    header_fill = "─" * max(0, _BOX_WIDTH - len(title) - 1)
+    header = f"╔─ {title} {header_fill}"
+    footer = "╚" + "─" * (_BOX_WIDTH + 2)
+    return "\n".join([header, *lines, footer])
+
+
+# ── Logger extendido ──────────────────────────────────────────────────────────
+
+class HtxLogger(logging.Logger):
+    """Logger con métodos semánticos y emisión de bloques estructurados."""
+
+    def ok(self, msg: str, *args: object, **kwargs: object) -> None:
+        """Emite un mensaje de nivel OK (verde)."""
+        if self.isEnabledFor(_OK_LEVEL):
+            self._log(_OK_LEVEL, msg, args, **kwargs)
+
+    def section(self, title: str) -> None:
+        """Imprime un separador de sección visible en consola."""
+        self.info("─" * 3 + f" {title} " + "─" * max(0, 48 - len(title)))
+
+    def box(self, title: str, lines: list[str], level: int = logging.INFO) -> None:
+        """Emite un bloque de caja ╔─ … ╚─ via el logger.
+
+        Equivalente a llamar render_box() y luego _log(level, ...).
+        Usar cuando el destinatario es el log interno (consola/archivo),
+        no el LLM (para eso usar render_box() + emit_block/RuleResult).
+        """
+        if self.isEnabledFor(level):
+            self._log(level, render_box(title, lines), ())
+
+    def event_block(
+        self,
+        event: str,
+        *,
+        status: str = "ok",
+        fields: dict[str, Any] | None = None,
+    ) -> None:
+        """Emite un bloque estructurado AI-legible en una sola llamada.
+
+        Elimina la repetición de múltiples `log.info()` para campos
+        relacionados. El bloque se emite completo en un solo mensaje,
+        lo que facilita el parseo por parte del asistente.
+
+        Args:
+            event:  Identificador del evento (ej: "profile-learn").
+            status: Estado del resultado: "ok" | "error" | "warn" | "skip".
+            fields: Diccionario ordenado de campo → valor a mostrar.
+
+        Example:
+            log.event_block("profile-learn", status="ok", fields={
+                "sessions_analyzed": 12,
+                "calibration_mode": "z-score",
+                "adoption_pct": "78%",
+                "strong_patterns": "hooks frecuentes, commits convencionales",
+                "weak_patterns": None,
+                "commit_topics": "refactor, api, test",
+            })
+        """
+        block = _build_event_block(event, status, fields or {})
+        level = _OK_LEVEL if status == "ok" else (
+            logging.WARNING if status == "warn" else
+            logging.ERROR if status == "error" else
+            logging.INFO
+        )
+        if self.isEnabledFor(level):
+            self._log(level, block, ())
+
+
+# ── Factory ───────────────────────────────────────────────────────────────────
+
+logging.setLoggerClass(HtxLogger)
+
+_instance: HtxLogger | None = None
+
+
+def get_logger(
+    project_root: Path | None = None,
+    *,
+    level: int = _DEFAULT_LEVEL,
+    file_logging: bool = True,
+) -> HtxLogger:
+    """Retorna la instancia singleton del logger higpertext.
+
+    Args:
+        project_root: Raíz del proyecto para calcular la ruta del archivo de log.
+                      Si es None, solo se emite a consola.
+        level: Nivel mínimo de logging (default: INFO).
+        file_logging: Si True, agrega un handler de archivo rotativo.
+    """
+    global _instance
+    if _instance is not None:
+        return _instance
+
+    logger: HtxLogger = logging.getLogger(LOGGER_NAME)  # type: ignore[assignment]
+    logger.setLevel(level)
+    logger.propagate = False
+
+    # ── Handler consola ───────────────────────────────────────────────────────
+    # Use a subclass that resolves sys.stdout dynamically so pytest capsys works.
+    class _DynamicStdoutHandler(logging.StreamHandler):
+        @property
+        def stream(self):  # type: ignore[override]
+            return sys.stdout
+
+        @stream.setter
+        def stream(self, value):  # type: ignore[override]
+            pass  # ignore the value set by StreamHandler.__init__
+
+    console = _DynamicStdoutHandler()
+    console.setLevel(level)
+    console.setFormatter(_ColorFormatter("%(message)s"))
+    logger.addHandler(console)
+
+    # ── Handler archivo (opcional) ────────────────────────────────────────────
+    if file_logging and project_root is not None:
+        log_dir = project_root / WORKSPACE_DIR_NAME / "logs"
+        try:
+            log_dir.mkdir(parents=True, exist_ok=True)
+            file_handler = logging.handlers.RotatingFileHandler(
+                log_dir / _LOG_FILE,
+                maxBytes=_MAX_BYTES,
+                backupCount=_BACKUP_COUNT,
+                encoding="utf-8",
+            )
+            file_handler.setLevel(logging.DEBUG)
+            file_handler.setFormatter(
+                _PlainFormatter(
+                    "%(asctime)s %(levelname)-8s %(message)s",
+                    datefmt="%Y-%m-%dT%H:%M:%S",
+                )
+            )
+            logger.addHandler(file_handler)
+        except OSError:
+            pass  # nosec — no bloquear si no se puede escribir el log
+
+    _instance = logger
+    return _instance
+
+
+def reset_logger() -> None:
+    """Limpia la instancia singleton (útil en tests)."""
+    global _instance
+    if _instance is not None:
+        _instance.handlers.clear()
+        _instance = None

higpertext/kernel/infrastructure/output_store.py

@@ -0,0 +1,70 @@
+"""OutputStore — persiste outputs de capabilities en .higpertext/reports/ con índice."""
+
+from __future__ import annotations
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.app_config import REPORTS_DIR as _REPORTS_DIR, INDEX_FILE as _INDEX_FILE
+
+
+def _canonical_name(capability_id: str) -> str:
+    """Convierte 'common.telemetry-report' → 'common_telemetry_report'."""
+    return re.sub(r"[.\-\s]+", "_", capability_id)
+
+
+class OutputStore:
+    """Persiste y recupera outputs de capabilities sin modificar su stdout.
+
+    El stdout al agente no se toca. Esta clase es una capa secundaria
+    de persistencia para que otras tools puedan leer outputs anteriores.
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        self._reports_dir = project_root / WORKSPACE_DIR_NAME / _REPORTS_DIR
+        self._index_path = self._reports_dir / _INDEX_FILE
+
+    def write(self, capability_id: str, content: str, fmt: str = "md") -> Path:
+        """Persiste el output de una capability y actualiza el índice."""
+        self._reports_dir.mkdir(parents=True, exist_ok=True)
+        filename = f"{_canonical_name(capability_id)}.{fmt}"
+        out_path = self._reports_dir / filename
+        out_path.write_text(content, encoding="utf-8")
+        self._update_index(capability_id, out_path, len(content))
+        return out_path
+
+    def read(self, capability_id: str) -> str | None:
+        """Retorna el último output persistido de una capability, o None."""
+        index = self._load_index()
+        entry = index.get(capability_id)
+        if not entry:
+            return None
+        path = Path(entry["path"])
+        if not path.exists():
+            return None
+        return path.read_text(encoding="utf-8")
+
+    def list(self) -> dict[str, dict]:
+        """Retorna el índice completo: {capability_id: {path, ts, size_bytes}}."""
+        return self._load_index()
+
+    def _update_index(self, capability_id: str, path: Path, size: int) -> None:
+        index = self._load_index()
+        index[capability_id] = {
+            "path": str(path),
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "size_bytes": size,
+        }
+        self._index_path.write_text(
+            json.dumps(index, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+
+    def _load_index(self) -> dict:
+        if not self._index_path.exists():
+            return {}
+        try:
+            return json.loads(self._index_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}

higpertext/kernel/infrastructure/parser/__init__.py

@@ -0,0 +1 @@
+# Infrastructure parser init

higpertext/kernel/infrastructure/parser/code_chunker.py

@@ -0,0 +1,144 @@
+"""CodeChunker - Divide archivos Python y Markdown en fragmentos semánticos."""
+
+from __future__ import annotations
+import ast
+from pathlib import Path
+from higpertext.kernel.domain.rag import DocumentChunk
+
+
+class CodeChunker:
+    """Divide archivos de código y documentación en bloques individuales."""
+
+    @staticmethod
+    def chunk_file(file_path: Path, max_chars: int = 1500) -> list[DocumentChunk]:
+        """Detecta la extensión e invoca al chunker especializado."""
+        if not file_path.exists() or file_path.is_dir():
+            return []
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return []
+
+        if file_path.suffix == ".py":
+            return CodeChunker._chunk_python(file_path, content)
+        elif file_path.suffix == ".md":
+            return CodeChunker._chunk_markdown(file_path, content)
+        else:
+            return CodeChunker._chunk_generic(file_path, content, max_chars)
+
+    @staticmethod
+    def _chunk_python(file_path: Path, content: str) -> list[DocumentChunk]:
+        chunks: list[DocumentChunk] = []
+        lines = content.splitlines()
+
+        try:
+            tree = ast.parse(content)
+        except SyntaxError:
+            # Fallback a segmentación genérica si hay error sintáctico
+            return CodeChunker._chunk_generic(file_path, content)
+
+        # Extraer módulos/clases/funciones
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+                start = node.lineno
+                # Intentar calcular línea final
+                end = getattr(node, "end_lineno", len(lines))
+                block_content = "\n".join(lines[start - 1 : end])
+                chunk_type = "class" if isinstance(node, ast.ClassDef) else "function"
+
+                chunks.append(
+                    DocumentChunk(
+                        file=str(file_path.resolve()),
+                        content=block_content,
+                        chunk_type=chunk_type,
+                        start_line=start,
+                        end_line=end,
+                        metadata={"name": node.name},
+                    )
+                )
+
+        # Si no se extrajeron bloques estructurales, o el archivo es pequeño, agregar todo el archivo
+        if not chunks:
+            chunks.append(
+                DocumentChunk(
+                    file=str(file_path.resolve()),
+                    content=content,
+                    chunk_type="general",
+                    start_line=1,
+                    end_line=len(lines),
+                )
+            )
+        return chunks
+
+    @staticmethod
+    def _chunk_markdown(file_path: Path, content: str) -> list[DocumentChunk]:
+        chunks: list[DocumentChunk] = []
+        lines = content.splitlines()
+        current_chunk_lines: list[str] = []
+        start_line = 1
+
+        for idx, line in enumerate(lines, 1):
+            if line.startswith("## ") or line.startswith("# "):
+                if current_chunk_lines:
+                    chunks.append(
+                        DocumentChunk(
+                            file=str(file_path.resolve()),
+                            content="\n".join(current_chunk_lines),
+                            chunk_type="markdown",
+                            start_line=start_line,
+                            end_line=idx - 1,
+                        )
+                    )
+                    current_chunk_lines = []
+                start_line = idx
+            current_chunk_lines.append(line)
+
+        if current_chunk_lines:
+            chunks.append(
+                DocumentChunk(
+                    file=str(file_path.resolve()),
+                    content="\n".join(current_chunk_lines),
+                    chunk_type="markdown",
+                    start_line=start_line,
+                    end_line=len(lines),
+                )
+            )
+        return chunks
+
+    @staticmethod
+    def _chunk_generic(file_path: Path, content: str, max_chars: int = 1500) -> list[DocumentChunk]:
+        chunks: list[DocumentChunk] = []
+        lines = content.splitlines()
+        current_lines: list[str] = []
+        current_len = 0
+        start_line = 1
+
+        for idx, line in enumerate(lines, 1):
+            current_lines.append(line)
+            current_len += len(line) + 1
+            if current_len >= max_chars:
+                chunks.append(
+                    DocumentChunk(
+                        file=str(file_path.resolve()),
+                        content="\n".join(current_lines),
+                        chunk_type="general",
+                        start_line=start_line,
+                        end_line=idx,
+                    )
+                )
+                current_lines = []
+                current_len = 0
+                start_line = idx + 1
+
+        if current_lines:
+            chunks.append(
+                DocumentChunk(
+                    file=str(file_path.resolve()),
+                    content="\n".join(current_lines),
+                    chunk_type="general",
+                    start_line=start_line,
+                    end_line=len(lines),
+                )
+            )
+        return chunks

higpertext/kernel/infrastructure/parser/language/__init__.py

@@ -0,0 +1,14 @@
+"""Shared language parsers — single source of truth for all file-type parsing."""
+
+from .base import LanguageParser, ParseResult
+from .python_parser import PythonParser
+from .typescript_parser import TypeScriptParser
+from .powershell_parser import PowerShellParser
+
+__all__ = [
+    "LanguageParser",
+    "ParseResult",
+    "PythonParser",
+    "TypeScriptParser",
+    "PowerShellParser",
+]

higpertext/kernel/infrastructure/parser/language/base.py

@@ -0,0 +1,41 @@
+"""Base contract for all language parsers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ParseResult:
+    """Canonical output of every LanguageParser."""
+
+    imports: list[str] = field(default_factory=list)
+    classes: list[dict] = field(default_factory=list)
+    functions: list[dict] = field(default_factory=list)
+    summary: str = ""
+    type: str = "unknown"
+    is_entry_point: bool = False
+    size: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "imports": self.imports,
+            "classes": self.classes,
+            "functions": self.functions,
+            "summary": self.summary,
+            "type": self.type,
+            "is_entry_point": self.is_entry_point,
+            "size": self.size,
+        }
+
+
+class LanguageParser(ABC):
+    """Contract: every language parser reads a file and returns a ParseResult."""
+
+    @abstractmethod
+    def parse_file(self, file_path: Path) -> ParseResult: ...
+
+    def empty(self, note: str = "", lang_type: str = "unknown") -> ParseResult:
+        return ParseResult(summary=note, type=lang_type)

higpertext/kernel/infrastructure/parser/language/powershell_parser.py

@@ -0,0 +1,35 @@
+"""PowerShell language parser."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .base import LanguageParser, ParseResult
+
+_PS_FUNC = re.compile(r"(?i)^\s*function\s+([a-zA-Z0-9_-]+)")
+_PS_USING = re.compile(r"(?i)^\s*using\s+module\s+([a-zA-Z0-9_\-\.]+)")
+
+
+class PowerShellParser(LanguageParser):
+    """Parses PowerShell files via regex line scanning."""
+
+    def parse_file(self, file_path: Path) -> ParseResult:
+        try:
+            lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            return self.empty(lang_type="powershell")
+
+        functions = [
+            {"name": m.group(1), "parameters": [], "docstring": ""}
+            for line in lines
+            for m in [_PS_FUNC.match(line)]
+            if m
+        ]
+        imports = [
+            m.group(1)
+            for line in lines
+            for m in [_PS_USING.match(line)]
+            if m
+        ]
+        return ParseResult(imports=imports, functions=functions, type="powershell")