higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/grep_search.py

@@ -0,0 +1,648 @@
+"""higpertext Grep Search — busca patrones en archivos del proyecto con salida estructurada."""
+
+import re
+import sys
+import json
+import argparse
+from fnmatch import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_SECRET_PATTERNS = (".env", "secrets.json", ".key", ".pem", ".pfx")
+_ALWAYS_EXCLUDES = {".venv", "venv", "__pycache__", ".git", "node_modules", ".tox"}
+_DEFAULT_EXTRA_EXCLUDES = {
+    "dist",
+    "build",
+    "coverage",
+    "logs",
+    "tmp",
+    "target",
+    "vendor",
+    "__cache__",
+    "reports",
+    ".agents",
+    ".gemini",
+    ".claude",
+    ".opencode",
+    ".antigravitycli",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".cache",
+    ".pytest_cache",
+    "*.min.js",
+    "*.bundle.min.js",
+    "*.min.css",
+    "*.map",
+}
+_TEST_PATH_PARTS = {"tests", "test", "__tests__", "spec", "specs"}
+_PRESET_GLOBS = {
+    "code": [
+        "*.py",
+        "*.js",
+        "*.jsx",
+        "*.ts",
+        "*.tsx",
+        "*.go",
+        "*.rs",
+        "*.java",
+        "*.cs",
+    ],
+    "python": ["*.py"],
+    "web": ["*.js", "*.jsx", "*.ts", "*.tsx", "*.css", "*.scss", "*.html"],
+    "docs": ["*.md", "*.txt", "*.rst"],
+    "config": ["*.json", "*.jsonc", "*.yaml", "*.yml", "*.toml", "*.ini"],
+    "all": ["*"],
+}
+_GRAPH_CANDIDATES = (
+    Path(".higpertext/state/semantic_graph.json"),
+    Path(".nexus/semantic_graph.json"),
+    Path(".nexus/semantic_graph.md"),
+)
+
+
+@dataclass
+class SearchSummary:
+    """Acumula métricas y resultados estructurados de búsqueda."""
+
+    found_count: list[int] = field(default_factory=lambda: [0])
+    files_matched: int = 0
+    json_matches: list[dict] = field(default_factory=list)
+
+
+def _is_secret_file(path: Path) -> bool:
+    """Verifica si el archivo es candidato a contener secretos."""
+    return any(path.name.endswith(pat) for pat in _SECRET_PATTERNS)
+
+
+def _is_binary_file(path: Path) -> bool:
+    """Verifica si el archivo es binario leyendo sus primeros bytes buscando bytes nulos."""
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(1024)
+            return b"\x00" in chunk
+    except OSError:
+        return True
+
+
+def _build_excludes(custom_excludes: set[str], include_all: bool) -> set[str]:
+    """Construye exclusiones seguras; --all conserva dependencias, secretos y binarios fuera."""
+    excludes = set(_ALWAYS_EXCLUDES) | custom_excludes
+    if not include_all:
+        excludes |= _DEFAULT_EXTRA_EXCLUDES
+    return excludes
+
+
+def _is_excluded(path: Path, excludes: set[str], root: Path) -> bool:
+    """Aplica exclusiones por parte de ruta, nombre exacto o glob simple."""
+    try:
+        scoped = path.relative_to(root)
+    except ValueError:
+        scoped = path
+    parts = set(scoped.parts)
+    if parts & excludes:
+        return True
+    as_posix = scoped.as_posix()
+    return any(fnmatch(path.name, item) or fnmatch(as_posix, item) for item in excludes)
+
+
+def _is_test_path(path: Path) -> bool:
+    """Detecta rutas de tests comunes para búsquedas enfocadas en código fuente."""
+    lower_parts = {part.lower() for part in path.parts}
+    return bool(lower_parts & _TEST_PATH_PARTS) or path.name.startswith("test_")
+
+
+def _collect_files(
+    search_path: Path,
+    include_globs: list[str],
+    excludes: set[str],
+    include_tests: bool = True,
+    max_file_size_kb: int = 1024,
+) -> list[Path]:
+    """Recopila archivos bajo search_path respetando filtros de inclusión y exclusión."""
+    results: list[Path] = []
+    if search_path.is_file():
+        if _is_secret_file(search_path) or _is_binary_file(search_path):
+            return []
+        if not include_tests and _is_test_path(search_path):
+            return []
+        if max_file_size_kb > 0 and search_path.stat().st_size > max_file_size_kb * 1024:
+            return []
+        return [search_path]
+
+    patterns = include_globs if include_globs else ["*"]
+    for pattern in patterns:
+        for f in search_path.rglob(pattern):
+            if not f.is_file():
+                continue
+            if _is_secret_file(f):
+                continue
+            if _is_excluded(f, excludes, search_path):
+                continue
+            if not include_tests and _is_test_path(f):
+                continue
+            if max_file_size_kb > 0 and f.stat().st_size > max_file_size_kb * 1024:
+                continue
+            if _is_binary_file(f):
+                continue
+            results.append(f)
+    return sorted(set(results))
+
+
+def _compile_pattern(pattern: str, is_regex: bool, case_sensitive: bool) -> re.Pattern:
+    """Compila el patrón de búsqueda según los flags solicitados."""
+    flags = 0 if case_sensitive else re.IGNORECASE
+    if not is_regex:
+        pattern = re.escape(pattern)
+    return re.compile(pattern, flags)
+
+
+def _format_path(path: Path, root: Path, absolute_paths: bool) -> str:
+    """Reduce ruido usando rutas relativas salvo que se pidan absolutas."""
+    if absolute_paths:
+        return str(path)
+    base = root if root.is_dir() else root.parent
+    try:
+        return f"./{path.relative_to(base).as_posix()}"
+    except ValueError:
+        return path.as_posix()
+
+
+def _shorten_line(line: str, limit: int) -> str:
+    """Limita líneas largas para proteger el contexto."""
+    if limit <= 0 or len(line) <= limit:
+        return line
+    return line[: max(0, limit - 3)] + "..."
+
+
+def _matching_lines(filepath: Path, compiled: re.Pattern) -> list[tuple[int, str]]:
+    """Devuelve coincidencias por línea para un archivo de texto."""
+    try:
+        raw_lines = filepath.read_text(encoding="utf-8", errors="ignore").splitlines()
+    except OSError:
+        return []
+    return [(i, line) for i, line in enumerate(raw_lines) if compiled.search(line)]
+
+
+def _semantic_graph_paths(root_path: Path) -> list[Path]:
+    """Localiza grafos semánticos conocidos de Higpertext/Nexus."""
+    root = root_path if root_path.is_dir() else root_path.parent
+    return [root / candidate for candidate in _GRAPH_CANDIDATES if (root / candidate).exists()]
+
+
+def _graph_entry_text(rel_path: str, file_data: dict) -> list[str]:
+    """Extrae texto indexado del grafo semántico para búsqueda simbólica."""
+    entries = [rel_path, file_data.get("summary", "")]
+    entries.extend(file_data.get("imports", []))
+    for item in file_data.get("classes", []):
+        entries.append(f"class {item.get('name', '')} {item.get('docstring', '')}")
+        for method in item.get("methods", []):
+            entries.append(f"def {method.get('name', '')} {method.get('docstring', '')}")
+    for item in file_data.get("functions", []):
+        entries.append(f"def {item.get('name', '')} {item.get('docstring', '')}")
+    return [entry for entry in entries if entry]
+
+
+def _search_semantic_graph(graph_path: Path, compiled: re.Pattern) -> list[str]:
+    """Busca en el grafo semántico sin exponer blobs completos."""
+    if graph_path.suffix == ".md":
+        hits = _matching_lines(graph_path, compiled)
+        return [f"  >>> L{line + 1:>4}: {text}" for line, text in hits]
+    try:
+        data = json.loads(graph_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    results: list[str] = []
+    for rel_path, file_data in data.get("files", {}).items():
+        for entry in _graph_entry_text(rel_path, file_data):
+            if compiled.search(entry):
+                results.append(f"  >>> [symbol] {rel_path}: {entry[:180]}")
+                break
+    return results
+
+
+def _search_file(
+    filepath: Path,
+    compiled: re.Pattern,
+    context_lines: int,
+    max_results: int,
+    max_per_file: int,
+    found_count: list[int],
+    files_only: bool,
+    count_only: bool = False,
+    display_path: str | None = None,
+    line_limit: int = 240,
+) -> list[str]:
+    """Busca el patrón en un archivo y retorna líneas de resultado formateadas."""
+    try:
+        raw_lines = filepath.read_text(encoding="utf-8", errors="ignore").splitlines()
+    except OSError:
+        return []
+
+    file_hits = [(i, line) for i, line in enumerate(raw_lines) if compiled.search(line)]
+
+    if not file_hits:
+        return []
+
+    output: list[str] = [f"\n### {display_path or str(filepath)}"]
+
+    if files_only or count_only:
+        found_count[0] += len(file_hits)
+        if count_only:
+            output.append(f"  {len(file_hits)} coincidencia(s)")
+        return output
+
+    for lineno, _ in file_hits[:max_per_file]:
+        if found_count[0] >= max_results:
+            output.append(f"  ... (límite de {max_results} resultados alcanzado)")
+            break
+        start = max(0, lineno - context_lines)
+        end = min(len(raw_lines), lineno + context_lines + 1)
+        for idx in range(start, end):
+            marker = ">>>" if idx == lineno else "   "
+            output.append(f"  {marker} L{idx + 1:>4}: {_shorten_line(raw_lines[idx], line_limit)}")
+        if context_lines > 0:
+            output.append("  ---")
+        found_count[0] += 1
+
+    if len(file_hits) > max_per_file and found_count[0] < max_results:
+        output.append(f"  ... y {
+                len(file_hits) -
+                max_per_file} coincidencia(s) más en este archivo")
+
+    return output
+
+
+def _parse_bool(value: str) -> bool:
+    """Convierte strings comunes de CLI a booleano."""
+    return value.lower() in ("true", "1", "yes")
+
+
+def _normalize_include_globs(include_source: str) -> list[str]:
+    """Normaliza extensiones simples y globs separados por coma."""
+    if not include_source:
+        return []
+    globs = [glob.strip() for glob in include_source.split(",") if glob.strip()]
+    return [glob if glob.startswith("*") else f"*.{glob.lstrip('.')}" for glob in globs]
+
+
+def _resolve_include_globs(include_source: str, preset: str) -> list[str]:
+    """Combina preset de búsqueda y globs explícitos."""
+    normalized = _normalize_include_globs(include_source)
+    if normalized:
+        return normalized
+    return _PRESET_GLOBS.get(preset, [])
+
+
+def _print_header(
+    pattern: str, mode: str, flags: str, path: Path, files_count: int, files_only: bool
+) -> None:
+    _log.info(f"[GREP SEARCH] pattern='{pattern}' ({mode}, {flags})")
+    _log.info(f"[*] Buscando en: {path} — {files_count} archivo(s) escaneados")
+    if files_only:
+        _log.info("[*] Modo files_only: se listan archivos; el total conserva coincidencias.")
+    _log.info("=" * 60)
+
+
+def _emit_semantic_matches(
+    paths: list[Path],
+    compiled: re.Pattern,
+    summary: SearchSummary,
+    max_results: int,
+    output_json: bool,
+) -> None:
+    for graph_path in paths:
+        graph_lines = _search_semantic_graph(graph_path, compiled)[:max_results]
+        if not graph_lines:
+            continue
+        summary.files_matched += 1
+        summary.found_count[0] += len(graph_lines)
+        if output_json:
+            summary.json_matches.append(
+                {
+                    "path": str(graph_path),
+                    "semantic": True,
+                    "matches": graph_lines,
+                }
+            )
+        else:
+            _log.info(f"\n### {graph_path} [semantic-graph]")
+            print("\n".join(graph_lines))
+
+
+def _rank_files(
+    files: list[Path], compiled: re.Pattern, sort_mode: str, source_first: bool
+) -> list[Path]:
+    """Ordena archivos para mostrar primero los más accionables."""
+    if sort_mode == "path" and not source_first:
+        return sorted(files)
+
+    def score(path: Path) -> tuple:
+        source_penalty = 1 if source_first and _is_test_path(path) else 0
+        if sort_mode == "relevance":
+            hits = len(_matching_lines(path, compiled))
+            return (source_penalty, -hits, len(path.parts), path.as_posix())
+        return (source_penalty, 0, 0, path.as_posix())
+
+    return sorted(files, key=score)
+
+
+def _emit_file_matches(
+    files: list[Path], compiled: re.Pattern, summary: SearchSummary, options: dict
+) -> None:
+    ranked_files = _rank_files(
+        files,
+        compiled,
+        options["sort"],
+        options["source_first"],
+    )
+    for filepath in ranked_files:
+        if summary.found_count[0] >= options["max_results"]:
+            break
+        lines = _search_file(
+            filepath,
+            compiled,
+            options["context_lines"],
+            options["max_results"],
+            options["max_per_file"],
+            summary.found_count,
+            options["files_only"],
+            options["count_only"],
+            display_path=_format_path(filepath, options["search_path"], options["absolute_paths"]),
+            line_limit=options["line_limit"],
+        )
+        if not lines:
+            continue
+        summary.files_matched += 1
+        if options["output_json"]:
+            summary.json_matches.append(
+                {
+                    "path": str(filepath),
+                    "semantic": False,
+                    "matches": lines[1:],
+                }
+            )
+        else:
+            print("\n".join(lines))
+
+
+def _print_json_summary(
+    pattern: str,
+    mode: str,
+    case_sensitive: bool,
+    files_count: int,
+    summary: SearchSummary,
+) -> None:
+    print(
+        json.dumps(
+            {
+                "pattern": pattern,
+                "mode": mode.lower(),
+                "case_sensitive": case_sensitive,
+                "files_scanned": files_count,
+                "files_matched": summary.files_matched,
+                "total_matches": summary.found_count[0],
+                "matches": summary.json_matches,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+
+
+def _print_text_summary(pattern: str, summary: SearchSummary) -> None:
+    _log.info("\n" + "=" * 60)
+    if summary.found_count[0] == 0:
+        _log.info(f"[NOT FOUND] No se encontraron coincidencias para: '{pattern}'")
+        return
+    _log.info(f"[FOUND] {summary.found_count[0]} coincidencia(s) encontrada(s)")
+    _log.info(f"[FILES] {summary.files_matched} archivo(s)/grafo(s) con coincidencias")
+
+
+def run_search(
+    pattern: str,
+    search_path: Path,
+    include_globs: list[str],
+    excludes: set[str],
+    is_regex: bool,
+    case_sensitive: bool,
+    context_lines: int,
+    max_results: int,
+    files_only: bool,
+    count_only: bool = False,
+    semantic: bool = False,
+    output_json: bool = False,
+    max_per_file: int = 20,
+    sort: str = "relevance",
+    include_tests: bool = True,
+    source_first: bool = True,
+    max_file_size_kb: int = 1024,
+    line_limit: int = 240,
+    absolute_paths: bool = False,
+) -> int:
+    """Ejecuta la búsqueda y devuelve el número total de coincidencias."""
+    try:
+        compiled = _compile_pattern(pattern, is_regex, case_sensitive)
+    except re.error as exc:
+        _log.error(f"[ERROR] Patrón regex inválido: {exc}")
+        sys.exit(2)
+
+    files = _collect_files(search_path, include_globs, excludes, include_tests, max_file_size_kb)
+    summary = SearchSummary()
+    header_mode = "REGEX" if is_regex else "LITERAL"
+    flags_str = "case-sensitive" if case_sensitive else "case-insensitive"
+    if not output_json:
+        _print_header(pattern, header_mode, flags_str, search_path, len(files), files_only)
+
+    if semantic:
+        _emit_semantic_matches(
+            _semantic_graph_paths(search_path),
+            compiled,
+            summary,
+            max_results,
+            output_json,
+        )
+
+    _emit_file_matches(
+        files,
+        compiled,
+        summary,
+        {
+            "context_lines": context_lines,
+            "max_results": max_results,
+            "max_per_file": max_per_file,
+            "files_only": files_only,
+            "count_only": count_only,
+            "output_json": output_json,
+            "sort": sort,
+            "source_first": source_first,
+            "search_path": search_path,
+            "absolute_paths": absolute_paths,
+            "line_limit": line_limit,
+        },
+    )
+
+    if output_json:
+        _print_json_summary(pattern, header_mode, case_sensitive, len(files), summary)
+        return summary.found_count[0]
+
+    _print_text_summary(pattern, summary)
+    return summary.found_count[0]
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("debe ser mayor que 0")
+    return parsed
+
+
+def _non_negative_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("no puede ser negativo")
+    return parsed
+
+
+def _sort_mode(value: str) -> str:
+    if value not in {"relevance", "path"}:
+        raise argparse.ArgumentTypeError("debe ser 'relevance' o 'path'")
+    return value
+
+
+def _preset(value: str) -> str:
+    if value not in _PRESET_GLOBS:
+        allowed = ", ".join(sorted(_PRESET_GLOBS))
+        raise argparse.ArgumentTypeError(f"preset inválido; usa uno de: {allowed}")
+    return value
+
+
+def main() -> None:
+    """Punto de entrada del grep search."""
+    parser = argparse.ArgumentParser(description="higpertext Grep Search")
+    parser.add_argument("--pattern", required=True, help="Patrón de búsqueda")
+    parser.add_argument("--path", default=".", help="Directorio o archivo donde buscar")
+    parser.add_argument("--include", default="", help="Globs a incluir (ej: *.py,*.ts)")
+    parser.add_argument(
+        "--extension", default="", help="Alias de --include (ej: py,ts o *.py,*.ts)"
+    )
+    parser.add_argument(
+        "--exclude",
+        default="",
+        help="Directorios/archivos a excluir (ej: __pycache__,.venv)",
+    )
+    parser.add_argument("--regex", default="false", help="Usar regex (true/false)")
+    parser.add_argument("--case_sensitive", default="false", help="Case-sensitive (true/false)")
+    parser.add_argument("--context", default="0", type=_non_negative_int, help="Líneas de contexto")
+    parser.add_argument(
+        "--before",
+        default=None,
+        type=_non_negative_int,
+        help="Líneas antes de cada match (alias específico)",
+    )
+    parser.add_argument(
+        "--after",
+        default=None,
+        type=_non_negative_int,
+        help="Líneas después de cada match; usa el mayor junto con --before",
+    )
+    parser.add_argument(
+        "--max_results", default="100", type=_positive_int, help="Máximo de resultados"
+    )
+    parser.add_argument(
+        "--max_per_file",
+        default="20",
+        type=_positive_int,
+        help="Máximo de resultados por archivo",
+    )
+    parser.add_argument(
+        "--line_limit",
+        default="240",
+        type=_non_negative_int,
+        help="Caracteres máximos por línea; 0 no trunca",
+    )
+    parser.add_argument(
+        "--max_file_size_kb",
+        default="1024",
+        type=_non_negative_int,
+        help="Ignora archivos mayores a este tamaño; 0 desactiva",
+    )
+    parser.add_argument(
+        "--sort", default="relevance", type=_sort_mode, help="Orden: relevance o path"
+    )
+    parser.add_argument(
+        "--preset",
+        default="all",
+        type=_preset,
+        help="Preset de includes: all, code, python, web, docs, config",
+    )
+    parser.add_argument("--include_tests", default="true", help="Incluye tests/specs (true/false)")
+    parser.add_argument(
+        "--source_first",
+        default="true",
+        help="Prioriza código fuente sobre tests al ordenar (true/false)",
+    )
+    parser.add_argument(
+        "--files_only", default="false", help="Solo nombres de archivo (true/false)"
+    )
+    parser.add_argument("--count", default="false", help="Muestra conteo por archivo (true/false)")
+    parser.add_argument(
+        "--semantic",
+        default="false",
+        help="Busca también en grafo semántico Nexus/Higpertext (true/false)",
+    )
+    parser.add_argument(
+        "--json", default="false", help="Emite salida JSON estructurada (true/false)"
+    )
+    parser.add_argument(
+        "--absolute_paths",
+        default="false",
+        help="Muestra rutas absolutas en vez de relativas (true/false)",
+    )
+    parser.add_argument(
+        "--all",
+        default="false",
+        help="Busca también en directorios de agentes/configuración excluidos por defecto (true/false)", # noqa: E501
+    )
+    args = parser.parse_args()
+
+    search_path = Path(args.path).resolve()
+    if not search_path.exists():
+        _log.error(f"[ERROR] El path no existe: {search_path}")
+        sys.exit(1)
+
+    include_globs = _resolve_include_globs(args.include or args.extension, args.preset)
+    custom_excludes = (
+        {e.strip() for e in args.exclude.split(",") if e.strip()} if args.exclude else set()
+    )
+    include_all = _parse_bool(args.all)
+    excludes = _build_excludes(custom_excludes, include_all)
+
+    run_search(
+        pattern=args.pattern,
+        search_path=search_path,
+        include_globs=include_globs,
+        excludes=excludes,
+        is_regex=_parse_bool(args.regex),
+        case_sensitive=_parse_bool(args.case_sensitive),
+        context_lines=max(args.context, args.before or 0, args.after or 0),
+        max_results=args.max_results,
+        files_only=_parse_bool(args.files_only),
+        count_only=_parse_bool(args.count),
+        semantic=_parse_bool(args.semantic),
+        output_json=_parse_bool(args.json),
+        max_per_file=args.max_per_file,
+        sort=args.sort,
+        include_tests=_parse_bool(args.include_tests),
+        source_first=_parse_bool(args.source_first),
+        max_file_size_kb=args.max_file_size_kb,
+        line_limit=args.line_limit,
+        absolute_paths=_parse_bool(args.absolute_paths),
+    )
+
+
+if __name__ == "__main__":
+    main()