github-pages-auditor 1.2.0__py3-none-any.whl

github_pages_auditor/main.py

@@ -0,0 +1,104 @@
+import os
+import sys
+
+from rich.console import Console
+
+from . import creditos
+from .audit import ejecutar_auditoria
+from .config import Config, parse_args
+from .errors import ErrorAuditoria
+from .formatters import a_json, bloque_markdown, inyectar
+from .report import generar_txt, renderizar_consola
+from .rules import disparadas, evaluar
+
+EXIT_OK, EXIT_HALLAZGOS, EXIT_ERROR, EXIT_SIN_REPOS, EXIT_CTRL_C = 0, 1, 2, 3, 130
+
+
+def _contenido(config: Config, reporte, hallazgos, activadas) -> str:
+    if config.formato == "json":
+        # En stdout, JSON solo ASCII: sobrevive a cualquier codificación de consola (p. ej. cp1252 en Windows).
+        return a_json(reporte, hallazgos, config.fail_on, activadas, solo_ascii=config.salida_estandar)
+    if config.formato == "md":
+        return bloque_markdown(reporte)
+    return generar_txt(reporte)
+
+
+def _escribir_stdout(texto: str) -> None:
+    """Escribe en UTF-8 aunque la consola use otra codificación (cp1252, etc.)."""
+    buffer = getattr(sys.stdout, "buffer", None)
+    if buffer is not None:
+        buffer.write(texto.encode("utf-8"))
+        buffer.flush()
+    else:  # stdout sustituido (tests)
+        sys.stdout.write(texto)
+        sys.stdout.flush()
+
+
+def _carpeta_ok(ruta: str) -> bool:
+    return os.path.isdir(os.path.dirname(os.path.abspath(ruta)))
+
+
+def main(args=None) -> int:
+    """Devuelve 0 (ok), 1 (--fail-on disparado), 2 (error), 3 (sin repositorios) o 130 (Ctrl+C)."""
+    config = parse_args(args)  # --help, --version y errores de uso salen aquí
+    # Con '-o -' el informe va a stdout y TODA la interfaz pasa a stderr (stdout queda limpio para pipes).
+    console = Console(no_color=config.sin_color, stderr=config.salida_estandar, quiet=config.quiet)
+    err = Console(stderr=True, no_color=config.sin_color)
+
+    if config.archivo_salida and not config.salida_estandar and not _carpeta_ok(config.archivo_salida):
+        carpeta = os.path.dirname(os.path.abspath(config.archivo_salida))
+        err.print(f"[bold red]❌ La carpeta de salida no existe: '{carpeta}'[/bold red]")
+        return EXIT_ERROR
+    if config.inject and not os.path.isfile(config.inject):
+        err.print(f"[bold red]❌ No existe el archivo para --inject: '{config.inject}'[/bold red]")
+        return EXIT_ERROR
+
+    try:
+        reporte = ejecutar_auditoria(config, console=console)
+    except ErrorAuditoria as e:
+        err.print(f"[bold red]❌ {e}[/bold red]")
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        err.print("\n[bold yellow]⚠️ Operación cancelada por el usuario.[/bold yellow]")
+        return EXIT_CTRL_C
+
+    if not reporte.repos:
+        err.print("[bold red]❌ No hay repositorios que analizar (usuario sin repos públicos o todos filtrados).[/bold red]")
+        return EXIT_SIN_REPOS
+
+    hallazgos = evaluar(reporte.repos)
+    activadas = disparadas(hallazgos, config.fail_on)
+
+    renderizar_consola(reporte, console=console)
+    try:
+        if config.archivo_salida:
+            contenido = _contenido(config, reporte, hallazgos, activadas)
+            if config.salida_estandar:
+                _escribir_stdout(contenido)
+            else:
+                with open(config.archivo_salida, "w", encoding="utf-8") as f:
+                    f.write(contenido)
+                console.print(f"\n[bold green]✅ Reporte exportado a '[white]{config.archivo_salida}[/white]'[/bold green]")
+        if config.inject:
+            with open(config.inject, encoding="utf-8") as f:
+                original = f.read()
+            nuevo = inyectar(original, bloque_markdown(reporte, incluir_forks=False))
+            with open(config.inject, "w", encoding="utf-8") as f:
+                f.write(nuevo)
+            console.print(f"[bold green]✅ Tabla de demos actualizada en '[white]{config.inject}[/white]'[/bold green]")
+    except ErrorAuditoria as e:
+        err.print(f"[bold red]❌ {e}[/bold red]")
+        return EXIT_ERROR
+    except OSError as e:
+        err.print(f"[bold red]❌ No se pudo escribir la salida: {e}[/bold red]")
+        return EXIT_ERROR
+
+    console.print(f"[dim]{creditos()}[/dim]", highlight=False, soft_wrap=True)
+    if activadas:
+        err.print(f"[bold red]❌ --fail-on disparado por: {', '.join(activadas)}[/bold red]")
+        return EXIT_HALLAZGOS
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

github_pages_auditor/models.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+ESTADO_OK = "ok"        # la web responde y parece una página real
+ESTADO_ROTA = "roto"    # se esperaba una web (Pages activadas) pero falla
+ESTADO_NINGUNA = "ninguna"  # no hay Pages (o no se pueden afirmar)
+
+
+@dataclass
+class PagesHealth:
+    """Resultado de inspeccionar una URL de GitHub Pages."""
+
+    estado: str
+    url: str
+    url_final: Optional[str] = None
+    http_status: Optional[int] = None
+    ms: Optional[int] = None
+    titulo: Optional[str] = None
+    problemas: List[str] = field(default_factory=list)  # errores: la página está rota
+    avisos: List[str] = field(default_factory=list)     # avisos: funciona pero mejorable
+
+    @property
+    def ok(self) -> bool:
+        return self.estado == ESTADO_OK
+
+
+@dataclass
+class RepoInfo:
+    """Resultado de auditar un repositorio.
+
+    ``tiene_descripcion``, ``es_fork`` y ``esta_archivado`` valen ``None`` cuando
+    no se han podido determinar (no se listan en el informe).
+    """
+
+    nombre: str
+    tiene_pages: bool = False
+    url_pages: Optional[str] = None
+    tiene_releases: bool = False
+    tiene_readme: bool = False
+    tiene_licencia: bool = False
+    tiene_gitignore: bool = False
+    tiene_descripcion: Optional[bool] = None
+    es_fork: Optional[bool] = None
+    esta_archivado: Optional[bool] = None
+    descripcion: Optional[str] = None
+    pages_salud: Optional[PagesHealth] = None
+    error: Optional[str] = None
+
+    @property
+    def pages_rota(self) -> bool:
+        return self.pages_salud is not None and self.pages_salud.estado == ESTADO_ROTA
+
+    @property
+    def pages_viva(self) -> bool:
+        if not self.tiene_pages or not self.url_pages:
+            return False
+        return self.pages_salud is None or self.pages_salud.ok
+
+
+@dataclass
+class AuditReport:
+    usuario: str
+    dominio_base: str
+    proveedor: str
+    repos: List[RepoInfo] = field(default_factory=list)
+    modo: str = "web"  # "api" | "web" (identificador estable para el JSON)
+
+    @property
+    def total_repos(self) -> int:
+        return len(self.repos)
+
+    @property
+    def _analizados(self) -> List[RepoInfo]:
+        """Repos sin error: de un repo que falló no se puede afirmar nada."""
+        return [r for r in self.repos if not r.error]
+
+    @property
+    def con_error(self) -> List[RepoInfo]:
+        return [r for r in self.repos if r.error]
+
+    @property
+    def con_pages(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.pages_viva]
+
+    @property
+    def pages_con_avisos(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.pages_viva and r.pages_salud and r.pages_salud.avisos]
+
+    @property
+    def pages_rotas(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.pages_rota]
+
+    @property
+    def con_releases(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.tiene_releases]
+
+    @property
+    def sin_nada(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if not r.tiene_pages and not r.tiene_releases]
+
+    @property
+    def sin_readme(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if not r.tiene_readme]
+
+    @property
+    def sin_licencia(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if not r.tiene_licencia]
+
+    @property
+    def sin_gitignore(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if not r.tiene_gitignore]
+
+    @property
+    def sin_descripcion(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.tiene_descripcion is False]
+
+    @property
+    def forks(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.es_fork]
+
+    @property
+    def archivados(self) -> List[RepoInfo]:
+        return [r for r in self._analizados if r.esta_archivado]

github_pages_auditor/pages.py

@@ -0,0 +1,51 @@
+from typing import Optional
+from urllib.parse import urlparse
+
+import requests
+
+
+def es_raiz(usuario: str, nombre_repo: str) -> bool:
+    """Solo ``<usuario>.github.io`` es el sitio raíz.
+
+    Un repo llamado igual que el usuario es el README del perfil, no un sitio.
+    """
+    return nombre_repo.lower() == f"{usuario.lower()}.github.io"
+
+
+def construir_url_pages(usuario: str, nombre_repo: str, dominio_base: str) -> str:
+    dominio_base = dominio_base.rstrip("/")
+    if es_raiz(usuario, nombre_repo):
+        return dominio_base
+    return f"{dominio_base}/{nombre_repo}/"
+
+
+def resolver_pages(session: requests.Session, url: str) -> Optional[str]:
+    """Devuelve la URL efectiva de la página si existe, o ``None``.
+
+    - Respuesta 200 en el mismo dominio: la URL pedida.
+    - Redirección desde ``*.github.io`` a otro dominio con 200: es el dominio
+      personalizado que GitHub tiene configurado en esas Pages, y se devuelve
+      la URL final (así se descubre el dominio real sin indicarlo con -w).
+    - Cualquier otra redirección a otro dominio se descarta (p. ej. parking).
+    """
+    try:
+        response = session.get(url, allow_redirects=True, stream=True)
+    except requests.RequestException:
+        return None
+    try:
+        if response.status_code != 200:
+            return None
+        final = getattr(response, "url", None) or url
+        host_pedido = urlparse(url).netloc.lower()
+        host_final = urlparse(final).netloc.lower()
+        if host_final == host_pedido:
+            return url
+        if host_pedido.endswith(".github.io"):
+            return final
+        return None
+    finally:
+        response.close()
+
+
+def comprobar_pages(session: requests.Session, url: str) -> bool:
+    return resolver_pages(session, url) is not None

github_pages_auditor/pages_health.py

@@ -0,0 +1,101 @@
+"""Salud de GitHub Pages: más allá de "responde 200".
+
+Detecta 404 / sin ``index.html``, errores TLS, timeouts, redirecciones a otro
+dominio o en bucle, páginas vacías o que no son HTML, y lentitud.
+
+``esperada=True`` significa "sabemos que estas Pages deberían existir"
+(modo API: ``has_pages``). Entonces cualquier fallo es ``roto``. Con
+``esperada=False`` (modo web) un fallo solo significa "no hay Pages".
+"""
+import html as _html
+import re
+import time
+from typing import Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .models import ESTADO_NINGUNA, ESTADO_OK, ESTADO_ROTA, PagesHealth
+
+LIMITE_BYTES = 65536
+MAX_REDIRECCIONES = 5
+UMBRAL_LENTA_MS = 3000
+
+_TITULO = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+_HTML = re.compile(r"<(!doctype\s+html|html|head|body)\b", re.IGNORECASE)
+
+
+def _leer_inicio(response) -> str:
+    """Lee solo el primer fragmento del cuerpo (no descarga páginas enormes)."""
+    try:
+        trozo = next(iter(response.iter_content(LIMITE_BYTES)), b"")
+    except (AttributeError, StopIteration, requests.RequestException):
+        trozo = (getattr(response, "text", "") or "")[:LIMITE_BYTES]
+    return trozo.decode("utf-8", "replace") if isinstance(trozo, bytes) else str(trozo)
+
+
+def _titulo(cuerpo: str) -> Optional[str]:
+    m = _TITULO.search(cuerpo)
+    if not m:
+        return None
+    texto = " ".join(_html.unescape(m.group(1)).split())
+    return texto[:120] or None
+
+
+def _fallo(url: str, esperada: bool, problema: str) -> PagesHealth:
+    return PagesHealth(
+        estado=ESTADO_ROTA if esperada else ESTADO_NINGUNA, url=url, problemas=[problema]
+    )
+
+
+def inspeccionar(session, url: str, esperada: bool = False) -> PagesHealth:
+    inicio = time.monotonic()
+    try:
+        response = session.get(url, allow_redirects=True, stream=True)
+    except requests.exceptions.SSLError:
+        return _fallo(url, esperada, "tls-error")
+    except requests.exceptions.Timeout:
+        return _fallo(url, esperada, "timeout")
+    except requests.exceptions.TooManyRedirects:
+        return _fallo(url, esperada, "bucle-de-redirecciones")
+    except requests.RequestException:
+        return _fallo(url, esperada, "sin-conexion")
+
+    ms = int((time.monotonic() - inicio) * 1000)
+    problemas, avisos = [], []
+    titulo = None
+    try:
+        status = response.status_code
+        final = getattr(response, "url", None) or url
+        saltos = len(getattr(response, "history", None) or [])
+        host_pedido = urlparse(url).netloc.lower()
+        host_final = urlparse(final).netloc.lower()
+
+        if status != 200:
+            problemas.append("404" if status == 404 else f"http-{status}")
+        else:
+            if host_final != host_pedido and not host_pedido.endswith(".github.io"):
+                problemas.append("redireccion-externa")  # dominio aparcado, etc.
+            if saltos > MAX_REDIRECCIONES:
+                problemas.append("demasiadas-redirecciones")
+            cuerpo = _leer_inicio(response)
+            if not cuerpo.strip():
+                problemas.append("cuerpo-vacio")
+            elif not _HTML.search(cuerpo):
+                avisos.append("sin-html")
+            titulo = _titulo(cuerpo)
+            if ms > UMBRAL_LENTA_MS:
+                avisos.append("lenta")
+    finally:
+        response.close()
+
+    if not problemas:
+        estado = ESTADO_OK
+    else:
+        estado = ESTADO_ROTA if esperada else ESTADO_NINGUNA
+    # URL efectiva: la pedida, o el dominio personalizado al que GitHub redirige.
+    url_final = url if host_final == host_pedido else final
+    return PagesHealth(
+        estado=estado, url=url, url_final=url_final if estado == ESTADO_OK or esperada else None,
+        http_status=status, ms=ms, titulo=titulo, problemas=problemas, avisos=avisos,
+    )

github_pages_auditor/report.py

@@ -0,0 +1,89 @@
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from . import __version__, creditos
+from .models import AuditReport
+
+
+def renderizar_consola(report: AuditReport, sin_color: bool = False, console: Console = None):
+    console = console or Console(no_color=sin_color)
+
+    console.print(Panel.fit(
+        f"[bold cyan]GitHub Profile & Pages Auditor[/bold cyan] [dim]v{__version__}[/dim]\n"
+        f"[dim]Usuario: [bold white]{report.usuario}[/bold white] | "
+        f"Dominio: [bold yellow]{report.dominio_base}[/bold yellow] | "
+        f"Proveedor: [bold green]{report.proveedor}[/bold green][/dim]",
+        border_style="cyan",
+    ))
+
+    t_pages = Table(title="🌐 GitHub Pages Activas", style="cyan", header_style="bold magenta")
+    t_pages.add_column("Repositorio", style="bold white", width=30)
+    t_pages.add_column("Enlace Desplegado", style="blue underline")
+    for r in report.con_pages:
+        t_pages.add_row(r.nombre, r.url_pages or "")
+    console.print(t_pages)
+
+    t = Table(title="🛡️ Resumen de Auditoría", style="green", header_style="bold yellow")
+    t.add_column("Métrica / Categoría", style="bold white")
+    t.add_column("Cantidad", justify="right", style="bold cyan")
+    t.add_column("Estado", style="bold")
+
+    def badge(lista, msg="faltantes"):
+        return f"[bold red]⚠️ {len(lista)} {msg}[/bold red]" if lista else "[bold green]✅ OK[/bold green]"
+
+    t.add_row("Total Repositorios", str(report.total_repos), "[bold blue]Analizados[/bold blue]")
+    t.add_row("GitHub Pages", str(len(report.con_pages)), "[bold green]Activas[/bold green]")
+    t.add_row("Releases Publicadas", str(len(report.con_releases)), "[bold green]Con Descargas[/bold green]")
+    t.add_row("Sin Web ni Releases", str(len(report.sin_nada)), badge(report.sin_nada, "inactivos"))
+    t.add_row("Sin README", str(len(report.sin_readme)), badge(report.sin_readme))
+    t.add_row("Sin Licencia", str(len(report.sin_licencia)), badge(report.sin_licencia))
+    t.add_row("Sin .gitignore", str(len(report.sin_gitignore)), badge(report.sin_gitignore))
+    t.add_row("Sin Descripción", str(len(report.sin_descripcion)), badge(report.sin_descripcion))
+    if report.pages_rotas:
+        t.add_row("Pages rotas", str(len(report.pages_rotas)), badge(report.pages_rotas, "rotas"))
+    if report.pages_con_avisos:
+        t.add_row("Pages con avisos", str(len(report.pages_con_avisos)), badge(report.pages_con_avisos, "avisos"))
+    t.add_row("Forks", str(len(report.forks)), "[dim]Externos[/dim]")
+    t.add_row("Archivados", str(len(report.archivados)), "[dim]Solo lectura[/dim]")
+    if report.con_error:
+        t.add_row("No analizados", str(len(report.con_error)), badge(report.con_error, "con error"))
+    console.print(t)
+
+
+def _seccion(titulo, nombres):
+    return ["", f"=== {titulo} ===", *([f"- {n}" for n in nombres] or ["Ninguno"])]
+
+
+def generar_txt(report: AuditReport) -> str:
+    lineas = [
+        f"=== ENLACES DE GITHUB PAGES PARA: {report.usuario} ===",
+        f"Dominio base: {report.dominio_base}",
+        f"Proveedor de datos: {report.proveedor}",
+        "",
+    ]
+    lineas += [f"- {r.nombre:<32} -> {r.url_pages}" for r in report.con_pages] or [
+        "No se encontraron repositorios con GitHub Pages."]
+    lineas += _seccion("REPOSITORIOS CON RELEASES", [r.nombre for r in report.con_releases])
+    lineas += _seccion("REPOSITORIOS SIN RELEASES NI GITHUB PAGES", [r.nombre for r in report.sin_nada])
+    lineas += _seccion("REPOSITORIOS SIN README", [r.nombre for r in report.sin_readme])
+    lineas += _seccion("REPOSITORIOS SIN LICENCIA", [r.nombre for r in report.sin_licencia])
+    lineas += _seccion("REPOSITORIOS SIN .GITIGNORE", [r.nombre for r in report.sin_gitignore])
+    lineas += _seccion("REPOSITORIOS SIN DESCRIPCIÓN (ABOUT)", [r.nombre for r in report.sin_descripcion])
+    lineas += _seccion("REPOSITORIOS QUE SON FORKS", [r.nombre for r in report.forks])
+    lineas += _seccion("REPOSITORIOS ARCHIVADOS", [r.nombre for r in report.archivados])
+    if report.pages_rotas:
+        lineas += _seccion("GITHUB PAGES ROTAS", [
+            f"{r.nombre}: {', '.join(r.pages_salud.problemas)}" for r in report.pages_rotas])
+    if report.pages_con_avisos:
+        lineas += _seccion("GITHUB PAGES CON AVISOS", [
+            f"{r.nombre}: {', '.join(r.pages_salud.avisos)}" for r in report.pages_con_avisos])
+    if report.con_error:
+        lineas += _seccion("REPOSITORIOS NO ANALIZADOS (ERROR DE RED)", [f"{r.nombre}: {r.error}" for r in report.con_error])
+    lineas += ["", "-" * 60, f"Generado con github-pages-auditor v{__version__}", creditos(sep="\n")]
+    return "\n".join(lineas) + "\n"
+
+
+def exportar_txt(report: AuditReport, ruta_salida: str):
+    with open(ruta_salida, "w", encoding="utf-8") as f:
+        f.write(generar_txt(report))

github_pages_auditor/rules.py

@@ -0,0 +1,40 @@
+"""Reglas evaluables para ``--fail-on`` (y para la sección ``findings`` del JSON)."""
+from typing import Callable, Dict, List, Sequence
+
+from .models import RepoInfo
+
+# id estable (parte del contrato público) -> (descripción, predicado "hay hallazgo")
+REGLAS: Dict[str, tuple] = {
+    "missing-readme": ("Repositorio sin README", lambda r: not r.tiene_readme),
+    "missing-license": ("Repositorio sin licencia", lambda r: not r.tiene_licencia),
+    "missing-gitignore": ("Repositorio sin .gitignore", lambda r: not r.tiene_gitignore),
+    "missing-description": ("Repositorio sin descripción (About)", lambda r: r.tiene_descripcion is False),
+    "broken-pages": ("GitHub Pages activadas pero rotas", lambda r: r.pages_rota),
+}
+REGLA_ERRORES = "analysis-errors"  # repos que no se pudieron analizar (red)
+TODAS = tuple(REGLAS) + (REGLA_ERRORES,)
+
+
+def parsear_fail_on(texto: str) -> Sequence[str]:
+    """'missing-license,broken-pages' | 'any' -> tupla validada de ids."""
+    ids = [t.strip().lower() for t in texto.split(",") if t.strip()]
+    if "any" in ids:
+        return TODAS
+    desconocidas = [i for i in ids if i not in TODAS]
+    if desconocidas:
+        raise ValueError(
+            f"reglas desconocidas: {', '.join(desconocidas)}. Válidas: any, {', '.join(TODAS)}"
+        )
+    return tuple(dict.fromkeys(ids))
+
+
+def evaluar(repos: List[RepoInfo]) -> Dict[str, List[str]]:
+    """Devuelve {regla: [repos con hallazgo]} para TODAS las reglas (listas vacías incluidas)."""
+    analizados = [r for r in repos if not r.error]
+    resultado = {rid: [r.nombre for r in analizados if pred(r)] for rid, (_, pred) in REGLAS.items()}
+    resultado[REGLA_ERRORES] = [r.nombre for r in repos if r.error]
+    return resultado
+
+
+def disparadas(hallazgos: Dict[str, List[str]], fail_on: Sequence[str]) -> List[str]:
+    return [rid for rid in fail_on if hallazgos.get(rid)]