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

github_pages_auditor/__init__.py

@@ -0,0 +1,12 @@
+"""github-pages-auditor: auditor CLI de repositorios, GitHub Pages y releases."""
+
+__version__ = "1.2.0"
+NOMBRE_PROGRAMA = "github-pages-auditor"
+AUTOR = "Alberto Ortiz"
+URL_GITHUB = "https://github.com/alberto2005-coder/"
+URL_WEB = "https://albertoortiz.is-a.dev/"
+
+
+def creditos(sep: str = " · ") -> str:
+    """Línea de créditos que se muestra en --help, --version, consola e informe."""
+    return f"Desarrollado por {AUTOR}{sep}GitHub: {URL_GITHUB}{sep}Web: {URL_WEB}"

github_pages_auditor/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

github_pages_auditor/audit.py

@@ -0,0 +1,79 @@
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import requests
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn, TimeRemainingColumn
+
+from .config import Config
+from .errors import ErrorAuditoria
+from .github_api import GitHubAPIProvider
+from .github_web import GitHubWebProvider
+from .http import crear_sesion_http
+from .models import AuditReport, RepoInfo
+
+
+def crear_proveedor(config: Config, session):
+    if config.usa_api:
+        return (GitHubAPIProvider(config.usuario, config.dominio_web, session, token=config.github_token),
+                "API REST de GitHub (Autenticado)")
+    return (GitHubWebProvider(config.usuario, config.dominio_web, session),
+            "Scraping Web Público (Sin API)")
+
+
+def ejecutar_auditoria(config: Config, session=None, console: Console = None) -> AuditReport:
+    """Audita todos los repos. Un fallo de red en un repo se anota en ``RepoInfo.error``
+    sin tumbar el resto; los errores globales (usuario inexistente, token inválido,
+    límite de tasa) se propagan como ``ErrorAuditoria``.
+    """
+    session = session or crear_sesion_http(timeout=config.timeout)
+    console = console or Console(no_color=config.sin_color)
+    provider, nombre_proveedor = crear_proveedor(config, session)
+
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"),
+                  transient=True, console=console) as progress:
+        task_list = progress.add_task(
+            description=f"🔍 Escaneando repositorios de [bold yellow]{config.usuario}[/bold yellow]...", total=None)
+
+        def actualizar_progreso(pagina: int, encontrados: int):
+            progress.update(task_list, description=(
+                f"🔍 Escaneando página [bold cyan]{pagina}[/bold cyan]... "
+                f"([bold green]{encontrados}[/bold green] repositorios encontrados)"))
+
+        try:
+            repos_base = provider.obtener_repositorios(on_progress=actualizar_progreso)
+        except requests.RequestException as e:
+            raise ErrorAuditoria(f"Error de red al listar los repositorios: {e}") from e
+
+    repos_base = [
+        r for r in repos_base
+        if not (config.excluir_forks and r.es_fork) and not (config.excluir_archivados and r.esta_archivado)
+    ]
+    informe = AuditReport(usuario=config.usuario, dominio_base=config.dominio_web, proveedor=nombre_proveedor,
+                          modo="api" if config.usa_api else "web")
+    if not repos_base:
+        return informe
+
+    def trabajo(repo: RepoInfo) -> RepoInfo:
+        try:
+            return provider.enriquecer_repo(repo)
+        except requests.RequestException as e:
+            repo.error = str(e)
+            return repo
+
+    resultados = [None] * len(repos_base)
+    with Progress(SpinnerColumn(), TextColumn("[bold cyan]Auditando código:[/bold cyan]"), BarColumn(bar_width=35),
+                  TaskProgressColumn(), TextColumn("[yellow]({task.completed}/{task.total})[/yellow]"),
+                  TimeRemainingColumn(), console=console) as progress:
+        task_audit = progress.add_task("audit", total=len(repos_base))
+        with ThreadPoolExecutor(max_workers=config.max_workers) as executor:
+            futuros = {executor.submit(trabajo, repo): i for i, repo in enumerate(repos_base)}
+            try:
+                for futuro in as_completed(futuros):
+                    resultados[futuros[futuro]] = futuro.result()
+                    progress.advance(task_audit)
+            except BaseException:
+                executor.shutdown(wait=False, cancel_futures=True)
+                raise
+
+    informe.repos = resultados  # mismo orden que el listado: informe determinista
+    return informe

github_pages_auditor/config.py

@@ -0,0 +1,152 @@
+"""Configuración: parámetros de consola > variables de entorno (.env opcional) > defecto."""
+import argparse
+import os
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from dotenv import find_dotenv, load_dotenv
+
+from . import NOMBRE_PROGRAMA, __version__, creditos
+from .rules import TODAS, parsear_fail_on
+
+SALIDA_BASE = "paginas_github"
+WORKERS_DEFECTO = 15
+TIMEOUT_DEFECTO = 10.0
+FORMATOS = ("txt", "json", "md")
+
+
+@dataclass
+class Config:
+    usuario: str
+    dominio_web: str
+    github_token: Optional[str]
+    archivo_salida: Optional[str]  # None = no escribir informe; "-" = stdout
+    max_workers: int
+    forzar_web: bool
+    sin_color: bool
+    timeout: float = TIMEOUT_DEFECTO
+    formato: str = "txt"
+    fail_on: Tuple[str, ...] = ()
+    excluir_forks: bool = False
+    excluir_archivados: bool = False
+    inject: Optional[str] = None
+    quiet: bool = False
+
+    @property
+    def usa_api(self) -> bool:
+        return bool(self.github_token) and not self.forzar_web
+
+    @property
+    def salida_estandar(self) -> bool:
+        return self.archivo_salida == "-"
+
+
+def normalizar_dominio(dominio: Optional[str], usuario: str) -> str:
+    dominio = (dominio or "").strip()
+    if not dominio:
+        return f"https://{usuario}.github.io"
+    if not dominio.lower().startswith(("http://", "https://")):
+        dominio = f"https://{dominio}"
+    return dominio.rstrip("/")
+
+
+def _fail_on(texto: str):
+    try:
+        return parsear_fail_on(texto)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(str(e))
+
+
+def crear_parser() -> argparse.ArgumentParser:
+    env = lambda k, d=None: (os.getenv(k) or "").strip() or d  # noqa: E731  (vacío == no definido)
+
+    parser = argparse.ArgumentParser(
+        prog=NOMBRE_PROGRAMA,
+        description="Auditor CLI para repositorios, GitHub Pages y releases de un usuario de GitHub.\n"
+                    "Funciona solo con parámetros: el archivo .env y el token de la API son opcionales.",
+        epilog=(
+            "Prioridad de configuración: parámetros > variables de entorno/.env > valores por defecto.\n"
+            "Variables de entorno: USUARIO_GITHUB, DOMINIO_WEB, GITHUB_TOKEN, ARCHIVO_SALIDA.\n"
+            "Códigos de salida: 0 ok, 1 --fail-on disparado, 2 error, 3 sin repositorios, 130 Ctrl+C.\n\n"
+            + creditos(sep="\n")
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("-u", "--usuario", "--user", dest="usuario", default=env("USUARIO_GITHUB"),
+                        help="Nombre de usuario de GitHub (obligatorio).")
+    parser.add_argument("-w", "--web", "--dominio", dest="dominio_web", default=env("DOMINIO_WEB"),
+                        help="Dominio base de tu sitio web o GitHub Pages (por defecto https://<usuario>.github.io).")
+    parser.add_argument("-k", "--key", "--token", dest="github_token", default=env("GITHUB_TOKEN"),
+                        help="GitHub Personal Access Token (opcional). Con token se usa la API; sin él, el modo web. "
+                             "Más seguro: variable GITHUB_TOKEN (un parámetro queda en el historial del shell).")
+    parser.add_argument("-o", "--output", dest="archivo_salida", default=env("ARCHIVO_SALIDA"),
+                        help=f"Archivo del informe (por defecto {SALIDA_BASE}.<formato>). Usa '-' para escribirlo "
+                             "en la salida estándar (la interfaz pasa a stderr).")
+    parser.add_argument("-f", "--format", dest="formato", choices=FORMATOS, default="txt",
+                        help="Formato del informe: txt (por defecto), json (contrato versionado) o md "
+                             "(tabla de demos en vivo para tu README).")
+    parser.add_argument("--fail-on", dest="fail_on", type=_fail_on, default=(), metavar="REGLAS",
+                        help="Sale con código 1 si hay hallazgos en estas reglas (separadas por comas): "
+                             f"{', '.join(TODAS)}, o 'any'.")
+    parser.add_argument("--exclude-forks", dest="excluir_forks", action="store_true",
+                        help="Ignora los repositorios que son forks.")
+    parser.add_argument("--exclude-archived", dest="excluir_archivados", action="store_true",
+                        help="Ignora los repositorios archivados.")
+    parser.add_argument("--inject", dest="inject", metavar="ARCHIVO",
+                        help="Actualiza la tabla de demos dentro de ARCHIVO (p. ej. README.md), entre los marcadores "
+                             "<!-- github-pages-auditor:start --> y <!-- github-pages-auditor:end -->.")
+    parser.add_argument("-q", "--quiet", dest="quiet", action="store_true",
+                        help="No muestra tablas ni progreso (solo errores).")
+    parser.add_argument("--workers", dest="max_workers", type=int, default=WORKERS_DEFECTO,
+                        help=f"Número máximo de hilos concurrentes (por defecto {WORKERS_DEFECTO}).")
+    parser.add_argument("--timeout", dest="timeout", type=float, default=TIMEOUT_DEFECTO,
+                        help=f"Timeout por petición en segundos (por defecto {TIMEOUT_DEFECTO:g}).")
+    parser.add_argument("--no-api", dest="forzar_web", action="store_true",
+                        help="Forzar scraping web omitiendo la API aunque haya token.")
+    parser.add_argument("--no-color", dest="sin_color", action="store_true",
+                        help="Desactivar colores en la consola.")
+    parser.add_argument("--no-env", dest="no_env", action="store_true",
+                        help="No leer el archivo .env.")
+    parser.add_argument("-V", "--version", action="version",
+                        version=f"%(prog)s {__version__}\n" + creditos(sep="\n"))
+    return parser
+
+
+def parse_args(args=None) -> Config:
+    # El .env se carga ANTES de construir los valores por defecto del parser.
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--no-env", action="store_true")
+    if not pre.parse_known_args(args)[0].no_env:
+        load_dotenv(find_dotenv(usecwd=True))  # busca el .env en el directorio actual
+
+    parser = crear_parser()
+    parsed = parser.parse_args(args)
+
+    usuario = (parsed.usuario or "").strip()
+    if not usuario:
+        parser.error("El usuario de GitHub es obligatorio. Usa -u <usuario> o define USUARIO_GITHUB.")
+    if parsed.max_workers < 1:
+        parser.error("--workers debe ser >= 1.")
+    if parsed.timeout <= 0:
+        parser.error("--timeout debe ser > 0.")
+
+    salida = (parsed.archivo_salida or "").strip() or None
+    if salida is None and not parsed.inject:
+        salida = f"{SALIDA_BASE}.{parsed.formato}"  # con --inject solo se escribe informe si se pide con -o
+
+    return Config(
+        usuario=usuario,
+        dominio_web=normalizar_dominio(parsed.dominio_web, usuario),
+        github_token=(parsed.github_token or "").strip() or None,
+        archivo_salida=salida,
+        max_workers=parsed.max_workers,
+        forzar_web=parsed.forzar_web,
+        sin_color=parsed.sin_color,
+        timeout=parsed.timeout,
+        formato=parsed.formato,
+        fail_on=tuple(parsed.fail_on),
+        excluir_forks=parsed.excluir_forks,
+        excluir_archivados=parsed.excluir_archivados,
+        inject=parsed.inject,
+        quiet=parsed.quiet,
+    )

github_pages_auditor/errors.py

@@ -0,0 +1,21 @@
+"""Excepciones propias: errores globales que detienen la auditoría."""
+
+
+class ErrorAuditoria(Exception):
+    """Error base de la herramienta."""
+
+
+class UsuarioNoEncontrado(ErrorAuditoria):
+    """El usuario de GitHub no existe."""
+
+
+class LimiteDeTasa(ErrorAuditoria):
+    """GitHub ha limitado las peticiones."""
+
+
+class TokenInvalido(ErrorAuditoria):
+    """GitHub rechazó el token (401)."""
+
+
+class ErrorSalida(ErrorAuditoria):
+    """No se puede generar o escribir la salida pedida (p. ej. --inject sin marcadores)."""

github_pages_auditor/formatters.py

@@ -0,0 +1,112 @@
+"""Serializadores de salida: JSON (contrato versionado) y Markdown (índice de demos)."""
+import json
+import re
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Sequence
+
+from . import NOMBRE_PROGRAMA, URL_GITHUB, __version__
+from .errors import ErrorSalida
+from .models import AuditReport, RepoInfo
+
+SCHEMA_VERSION = 1
+MARCA_INICIO = "<!-- github-pages-auditor:start -->"
+MARCA_FIN = "<!-- github-pages-auditor:end -->"
+
+
+# ----------------------------------------------------------------- JSON
+def _repo_a_dict(r: RepoInfo) -> dict:
+    s = r.pages_salud
+    return {
+        "name": r.nombre,
+        "description": r.descripcion,
+        "fork": r.es_fork,
+        "archived": r.esta_archivado,
+        "has_pages": r.tiene_pages,
+        "pages": None if s is None else {
+            "status": s.estado,
+            "url": r.url_pages,
+            "http_status": s.http_status,
+            "response_ms": s.ms,
+            "title": s.titulo,
+            "problems": s.problemas,
+            "warnings": s.avisos,
+        },
+        "pages_url": r.url_pages,
+        "has_releases": r.tiene_releases,
+        "has_readme": r.tiene_readme,
+        "has_license": r.tiene_licencia,
+        "has_gitignore": r.tiene_gitignore,
+        "has_description": r.tiene_descripcion,
+        "error": r.error,
+    }
+
+
+def a_dict(report: AuditReport, hallazgos: Dict[str, List[str]], fail_on: Sequence[str],
+           disparadas: Sequence[str], ahora: Optional[datetime] = None) -> dict:
+    ahora = ahora or datetime.now(timezone.utc)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "tool": {"name": NOMBRE_PROGRAMA, "version": __version__, "url": URL_GITHUB},
+        "generated_at": ahora.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "user": report.usuario,
+        "mode": report.modo,
+        "domain": report.dominio_base,
+        "summary": {
+            "total": report.total_repos,
+            "analyzed": report.total_repos - len(report.con_error),
+            "pages_live": len(report.con_pages),
+            "pages_broken": len(report.pages_rotas),
+            "releases": len(report.con_releases),
+            "no_pages_no_releases": len(report.sin_nada),
+            "missing_readme": len(report.sin_readme),
+            "missing_license": len(report.sin_licencia),
+            "missing_gitignore": len(report.sin_gitignore),
+            "missing_description": len(report.sin_descripcion),
+            "forks": len(report.forks),
+            "archived": len(report.archivados),
+            "errors": len(report.con_error),
+        },
+        "findings": hallazgos,
+        "fail_on": {"rules": list(fail_on), "triggered": list(disparadas)},
+        "repos": [_repo_a_dict(r) for r in report.repos],
+    }
+
+
+def a_json(report: AuditReport, hallazgos, fail_on, disparadas, ahora=None, solo_ascii=False) -> str:
+    return json.dumps(a_dict(report, hallazgos, fail_on, disparadas, ahora),
+                      indent=2, ensure_ascii=solo_ascii) + "\n"
+
+
+# ------------------------------------------------------------- Markdown
+def _celda(texto: Optional[str]) -> str:
+    return " ".join((texto or "").replace("|", "\\|").split())
+
+
+def bloque_markdown(report: AuditReport, incluir_forks: bool = False) -> str:
+    """Tabla de demos en vivo, entre marcadores, lista para un README de perfil."""
+    vivas = sorted(
+        (r for r in report.con_pages if incluir_forks or not r.es_fork),
+        key=lambda r: r.nombre.lower(),
+    )
+    lineas = [MARCA_INICIO, "## Demos en vivo", ""]
+    if vivas:
+        lineas += ["| Proyecto | Demo | Descripción |", "| --- | --- | --- |"]
+        for r in vivas:
+            desc = r.descripcion or (r.pages_salud.titulo if r.pages_salud else "")
+            lineas.append(f"| [{_celda(r.nombre)}](https://github.com/{report.usuario}/{r.nombre}) "
+                          f"| [Abrir]({r.url_pages}) | {_celda(desc)} |")
+    else:
+        lineas.append("_Todavía no hay demos publicadas._")
+    lineas += ["", f"<sub>Generado con [{NOMBRE_PROGRAMA}]({URL_GITHUB}) v{__version__}</sub>", MARCA_FIN]
+    return "\n".join(lineas) + "\n"
+
+
+def inyectar(texto: str, bloque: str) -> str:
+    """Sustituye lo que haya entre los marcadores; falla si no existen (no adivina dónde escribir)."""
+    patron = re.compile(re.escape(MARCA_INICIO) + r".*?" + re.escape(MARCA_FIN) + r"\n?", re.DOTALL)
+    if not patron.search(texto):
+        raise ErrorSalida(
+            f"El archivo no contiene los marcadores {MARCA_INICIO} ... {MARCA_FIN}. "
+            "Añádelos donde quieras la tabla y vuelve a ejecutar."
+        )
+    return patron.sub(lambda _m: bloque, texto, count=1)

github_pages_auditor/github_api.py

@@ -0,0 +1,122 @@
+"""Proveedor CON token: API REST oficial de GitHub (5.000 peticiones/hora)."""
+from typing import List, Optional
+
+import requests
+
+from . import pages, pages_health
+from .errors import ErrorAuditoria, LimiteDeTasa, TokenInvalido, UsuarioNoEncontrado
+from .models import ESTADO_ROTA, RepoInfo
+
+API = "https://api.github.com"
+POR_PAGINA = 100
+MAX_PAGINAS = 100
+PREFIJOS_LICENCIA = ("license", "licence", "copying")
+
+
+class GitHubAPIProvider:
+    def __init__(self, usuario: str, dominio: str, session: requests.Session, token: Optional[str] = None):
+        self.usuario = usuario
+        self.dominio = dominio
+        self.session = session
+        # El token solo se envía a api.github.com, nunca a otros hosts.
+        self._headers = {"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28"}
+        if token:
+            self._headers["Authorization"] = f"Bearer {token}"
+
+    def _get(self, ruta: str, **kwargs):
+        res = self.session.get(f"{API}{ruta}", headers=self._headers, **kwargs)
+        if res.status_code == 401:
+            raise TokenInvalido("GitHub rechazó el token (401). Comprueba que sea válido y no haya caducado.")
+        if res.status_code in (403, 429):
+            headers = getattr(res, "headers", {}) or {}
+            if res.status_code == 429 or headers.get("X-RateLimit-Remaining") == "0" or "Retry-After" in headers:
+                raise LimiteDeTasa("Se agotó el límite de la API de GitHub. Espera a que se restablezca o usa un token.")
+        return res
+
+    def obtener_repositorios(self, on_progress=None) -> List[RepoInfo]:
+        repos: List[RepoInfo] = []
+        for page in range(1, MAX_PAGINAS + 1):
+            if on_progress:
+                on_progress(page, len(repos))
+            res = self._get(f"/users/{self.usuario}/repos", params={"per_page": POR_PAGINA, "page": page})
+            if res.status_code == 404:
+                raise UsuarioNoEncontrado(f"El usuario '{self.usuario}' no existe.")
+            if res.status_code != 200:
+                raise ErrorAuditoria(f"La API de GitHub respondió {res.status_code} al listar los repositorios.")
+
+            data = res.json()
+            if not isinstance(data, list):
+                break
+            for raw in data:
+                nombre = raw.get("name")
+                if not nombre:
+                    continue
+                tiene_pages = bool(raw.get("has_pages", False))
+                repos.append(RepoInfo(
+                    nombre=nombre,
+                    tiene_pages=tiene_pages,
+                    url_pages=pages.construir_url_pages(self.usuario, nombre, self.dominio) if tiene_pages else None,
+                    tiene_licencia=raw.get("license") is not None,
+                    tiene_descripcion=bool((raw.get("description") or "").strip()),
+                    descripcion=(raw.get("description") or "").strip() or None,
+                    es_fork=bool(raw.get("fork", False)),
+                    esta_archivado=bool(raw.get("archived", False)),
+                ))
+            if len(data) < POR_PAGINA:
+                break
+        return repos
+
+    def _archivos_raiz(self, nombre: str) -> List[str]:
+        res = self._get(f"/repos/{self.usuario}/{nombre}/contents/")
+        if res.status_code != 200:  # 404 = repositorio vacío
+            return []
+        datos = res.json()
+        return [f.get("name", "").lower() for f in datos] if isinstance(datos, list) else []
+
+    def enriquecer_repo(self, repo: RepoInfo) -> RepoInfo:
+        # Releases vía feed Atom: no consume cuota de la API.
+        atom = self.session.get(f"https://github.com/{self.usuario}/{repo.nombre}/releases.atom")
+        repo.tiene_releases = atom.status_code == 200 and "<entry>" in atom.text
+
+        # README, LICENSE y .gitignore con una sola llamada al contenido raíz.
+        archivos = self._archivos_raiz(repo.nombre)
+        repo.tiene_readme = any(n.startswith("readme") for n in archivos)
+        repo.tiene_gitignore = ".gitignore" in archivos
+        repo.tiene_licencia = repo.tiene_licencia or any(n.startswith(PREFIJOS_LICENCIA) for n in archivos)
+
+        if repo.tiene_pages:
+            self._comprobar_pages(repo)
+        return repo
+
+    def _datos_pages(self, nombre: str) -> Optional[dict]:
+        res = self._get(f"/repos/{self.usuario}/{nombre}/pages")
+        if res.status_code != 200:
+            return None
+        datos = res.json()
+        return datos if isinstance(datos, dict) else None
+
+    def _comprobar_pages(self, repo: RepoInfo) -> None:
+        """Pages activadas según la API: aquí cualquier fallo de la web es una Pages ROTA."""
+        datos = self._datos_pages(repo.nombre) or {}
+        url = datos.get("html_url") or repo.url_pages
+        if url and pages.es_raiz(self.usuario, repo.nombre):
+            url = url.rstrip("/")
+        salud = None
+        if url and url.startswith("http://"):
+            # La API devuelve http:// si HTTPS no está forzado; preferimos https si la web responde bien.
+            https = "https://" + url[len("http://"):]
+            candidata = pages_health.inspeccionar(self.session, https, esperada=True)
+            if not candidata.problemas:
+                salud, url = candidata, https
+        if salud is None:
+            salud = pages_health.inspeccionar(self.session, url, esperada=True)
+        if datos.get("status") == "errored":
+            salud.problemas.append("build-fallido")
+        elif datos.get("status") == "building":
+            salud.avisos.append("build-en-curso")
+        if datos.get("https_enforced") is False:
+            salud.avisos.append("https-no-forzado")
+        if salud.problemas:
+            salud.estado = ESTADO_ROTA
+        repo.pages_salud = salud
+        repo.url_pages = salud.url_final or url

github_pages_auditor/github_web.py

@@ -0,0 +1,116 @@
+"""Proveedor SIN token: páginas públicas de GitHub (HTML, raw y feeds Atom).
+
+Es un modo de "mejor esfuerzo": depende del marcado público de GitHub, que puede
+cambiar. Para resultados más fiables usa la API con token.
+"""
+import re
+from typing import Any, Dict, List, Optional
+
+import requests
+
+import html as _html
+
+from . import pages, pages_health
+from .errors import ErrorAuditoria, LimiteDeTasa, UsuarioNoEncontrado
+from .models import RepoInfo
+
+URL = "https://github.com"
+RAW = "https://raw.githubusercontent.com"
+MAX_PAGINAS = 100
+CANDIDATOS_README = ("README.md", "README", "README.rst", "README.txt", "readme.md")
+CANDIDATOS_LICENCIA = ("LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING")
+
+
+def _texto_descripcion(bloque: str) -> Optional[str]:
+    m = re.search(r'itemprop="description"[^>]*>(.*?)</p>', bloque, re.DOTALL)
+    if not m:
+        return None
+    texto = " ".join(_html.unescape(re.sub(r"<[^>]+>", "", m.group(1))).split())
+    return texto or None
+
+
+def parsear_listado(html: str, usuario: str) -> List[Dict[str, Any]]:
+    """Extrae los repos de una página del perfil con descripción/fork/archivado.
+
+    Si no se reconoce el marcado por repositorio, devuelve solo los nombres con
+    los metadatos a ``None`` (desconocidos).
+    """
+    patron = re.compile(
+        r'href="/' + re.escape(usuario) + r'/([^"/?#]+)"[^>]*itemprop="name codeRepository"',
+        re.IGNORECASE,
+    )
+    repos: List[Dict[str, Any]] = []
+    for bloque in re.split(r'<li\b[^>]*itemprop="owns"', html)[1:]:
+        m = patron.search(bloque)
+        if m:
+            repos.append({
+                "nombre": m.group(1),
+                "descripcion_texto": _texto_descripcion(bloque),
+                "descripcion": 'itemprop="description"' in bloque,
+                "fork": "Forked from" in bloque,
+                "archivado": re.search(r">\s*Archived\s*<", bloque) is not None,
+            })
+    if repos:
+        return repos
+    return [
+        {"nombre": n, "descripcion": None, "fork": None, "archivado": None, "descripcion_texto": None}
+        for n in dict.fromkeys(patron.findall(html))
+    ]
+
+
+class GitHubWebProvider:
+    def __init__(self, usuario: str, dominio: str, session: requests.Session):
+        self.usuario = usuario
+        self.dominio = dominio
+        self.session = session
+
+    def obtener_repositorios(self, on_progress=None) -> List[RepoInfo]:
+        vistos: Dict[str, Dict[str, Any]] = {}
+        for page in range(1, MAX_PAGINAS + 1):
+            if on_progress:
+                on_progress(page, len(vistos))
+            res = self.session.get(f"{URL}/{self.usuario}", params={"page": page, "tab": "repositories"})
+            if res.status_code == 404 and page == 1:
+                raise UsuarioNoEncontrado(f"El usuario '{self.usuario}' no existe.")
+            if res.status_code == 429:
+                raise LimiteDeTasa("GitHub limitó las peticiones (429). Prueba más tarde o usa un token (-k).")
+            if res.status_code != 200:
+                if page == 1:
+                    raise ErrorAuditoria(f"GitHub respondió {res.status_code} al listar los repositorios.")
+                break
+            nuevos = [x for x in parsear_listado(res.text, self.usuario) if x["nombre"] not in vistos]
+            if not nuevos:
+                break
+            for x in nuevos:
+                vistos[x["nombre"]] = x
+
+        return [
+            RepoInfo(
+                nombre=x["nombre"],
+                tiene_descripcion=x["descripcion"],
+                descripcion=x.get("descripcion_texto"),
+                es_fork=x["fork"],
+                esta_archivado=x["archivado"],
+            )
+            for x in vistos.values()
+        ]
+
+    def _existe(self, url: str) -> bool:
+        return self.session.head(url, allow_redirects=True).status_code == 200
+
+    def enriquecer_repo(self, repo: RepoInfo) -> RepoInfo:
+        atom = self.session.get(f"{URL}/{self.usuario}/{repo.nombre}/releases.atom")
+        repo.tiene_releases = atom.status_code == 200 and "<entry>" in atom.text
+
+        raw = f"{RAW}/{self.usuario}/{repo.nombre}/HEAD/"
+        repo.tiene_readme = any(self._existe(raw + f) for f in CANDIDATOS_README)
+        repo.tiene_licencia = any(self._existe(raw + f) for f in CANDIDATOS_LICENCIA)
+        repo.tiene_gitignore = self._existe(raw + ".gitignore")
+
+        # La comprobación de Pages se hace aquí (en paralelo), no al listar.
+        url = pages.construir_url_pages(self.usuario, repo.nombre, self.dominio)
+        salud = pages_health.inspeccionar(self.session, url, esperada=False)
+        repo.tiene_pages = salud.ok
+        repo.url_pages = salud.url_final if salud.ok else None
+        repo.pages_salud = salud if salud.ok else None
+        return repo

github_pages_auditor/http.py

@@ -0,0 +1,44 @@
+"""Sesión HTTP con reintentos y timeout por defecto.
+
+IMPORTANTE: la sesión NO lleva credenciales. El token de GitHub se añade
+únicamente en las peticiones a api.github.com (ver github_api.py), de modo que
+nunca viaja a github.com, raw.githubusercontent.com ni a tu dominio.
+"""
+from __future__ import annotations
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from . import __version__
+
+USER_AGENT = f"Mozilla/5.0 (compatible; github-pages-auditor/{__version__}; +https://github.com/alberto2005-coder/github-pages-auditor)"
+
+
+class SesionHttp(requests.Session):
+    """requests.Session que aplica un timeout por defecto a todas las peticiones."""
+
+    def __init__(self, timeout: float = 10.0) -> None:
+        super().__init__()
+        self.request_timeout = timeout
+
+    def request(self, method, url, **kwargs):
+        kwargs.setdefault("timeout", self.request_timeout)
+        return super().request(method, url, **kwargs)
+
+
+def crear_sesion_http(timeout: float = 10.0, pool: int = 50) -> SesionHttp:
+    session = SesionHttp(timeout=timeout)
+    retries = Retry(
+        total=3,
+        backoff_factor=1.0,
+        status_forcelist=[429, 500, 502, 503, 504],
+        allowed_methods=["GET", "HEAD"],
+        respect_retry_after_header=True,
+        raise_on_status=False,  # devolver la última respuesta en vez de lanzar RetryError
+    )
+    adapter = HTTPAdapter(max_retries=retries, pool_connections=pool, pool_maxsize=pool)
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    session.headers["User-Agent"] = USER_AGENT
+    return session