sergio/takana

1#!/usr/bin/env python3
2# vigia-imagen.py — ¿qué le falta a una IMAGEN que su clausura no puede echar de menos?
3#
4# ══ EL PUNTO CIEGO QUE ESTE VIGÍA CUBRE ════════════════════════════════════════════════════════
5# `build-state.py` contesta «¿está sellado?» y `vigia-sonames.py` contesta «¿algún `.so` que pide
6# esta imagen no lo provee nadie?». Ninguno de los dos contesta la pregunta que se hace un usuario
7# al arrancar el escritorio: **¿se puede USAR?**
8#
9# Y hay dos formas de que no se pueda, las dos medidas el 2026-09-03 arrancando KDE en QEMU:
10#
11#  1. **DATA de runtime que ninguna arista de BUILD alcanza.** El panel de Plasma salía con el reloj
12#     y nada más. Los `.so` de todos los applets estaban instalados; lo que faltaba era el TEMA DE
13#     ICONOS — `kickoff`, `systemtray` y `showdesktop` SON un icono, así que sin tema quedan de ancho
14#     cero y el panel parece vacío. `breeze-icons` estaba sellada desde siempre y no la declaraba
15#     ningún perfil. Es la figura de las fuentes ([[gnome-sin-fuentes]]) y de `foot` (sway llegó a
16#     121/121 sin emulador de terminal): **la métrica de clausura mide lo DECLARADO**, y estas cosas
17#     no las declara nadie porque no son dep de build de nada.
18#
19#  2. **Una porción OPCIONAL de una librería que sí está.** El menú de aplicaciones no abría:
20#     `kcoreaddons.toml` pasaba `-DKCOREADDONS_USE_QML=OFF` ⇒ el módulo QML `org.kde.coreaddons` no
21#     existía ⇒ `kickoff` moría en el import. No falta una receta ni una librería: falta una FEATURE.
22#     Ninguna métrica basada en recetas puede verlo.
23#
24# ══ QUÉ MIDE, Y CONTRA QUÉ ═════════════════════════════════════════════════════════════════════
25# Recorre los ARTEFACTOS del cierre de cada perfil (no las recetas: el artefacto es lo que se
26# instala) y comprueba cinco invariantes de imagen usable:
27#
28#   iconos     ≥1 tema con `index.theme` Y ficheros de icono adentro. Un directorio sin `index.theme`
29#              NO es un tema: la búsqueda no lo recorre. `hicolor` se cuenta aparte porque es el
30#              FALLBACK obligatorio del estándar y no trae iconos propios: es el contrato, no el
31#              contenido.
32#   cursores   ≥1 tema con `cursors/` poblado. Con el cursor por software —obligatorio en virtio-gpu—
33#              sin tema el puntero se mueve INVISIBLE. A diferencia de los iconos, acá NO se exige
34#              `index.theme`: libXcursor abre `<tema>/cursors/<nombre>` directo.
35#   fuentes    ≥1 `.ttf/.otf/.ttc/.pfb`. fontconfig es el motor que BUSCA fuentes, no una fuente.
36#   terminal   ≥1 `.desktop` con `TerminalEmulator` en Categories. Un escritorio sin terminal no es
37#              uno incompleto: es uno del que no se puede salir cuando algo falla.
38#   qml        todo `import <módulo>` de los `.qml` INSTALADOS tiene un módulo con `qmldir` en el
39#              cierre. Así se caza la clase (2).
40#
41# ══ Y UN SEXTO DATO QUE ESTE VIGÍA NO MIDE: CUÁNTO TARDA EN VERSE ══════════════════════════════
42# Los cinco de arriba se miden sobre artefactos, en segundos, y contestan «¿está lo que hace falta?».
43# Ninguno contesta «¿y cuándo se ve?» — y esa pregunta ya cobró: el §6.10.ter del SDD 26 dio por
44# hecho que `atuq` «no pinta nunca» en la imagen arrancada CON ESTE VIGÍA EN ✓, y la medición
45# repetida mostró que pintaba a los +137…+204 s. Lo medido había sido la paciencia.
46# Y el 2026-09-14, peor: con DOS tarjetas DRM la ventana cae en cualquiera de las dos salidas, y las
47# capturas miraban UNA ⇒ el «3 de 13» que se publicó medía dónde apuntaba la cámara. Por eso el dato
48# que se lee acá trae en qué PANTALLA apareció, y las corridas ciegas (dos salidas, una captura) no
49# se cuentan.
50# Arrancar la imagen son ~15 min de QEMU sin KVM, así que no se hace acá: `scripts/cosmic/atuq-en-
51# imagen.py` lo mide y deja el número en `docs/state/primera-pintura.json`, y este vigía lo LEE y lo
52# dice con sus condiciones (lanzamiento, vídeo, RAM, vcpus) — el tiempo depende de la carga de la
53# anfitriona, y un número sin condiciones se lee como si fuera del producto. Sin medición, lo dice.
54#
55# ══ RUIDO LEGÍTIMO, para poder triar ═══════════════════════════════════════════════════════════
56# Hay módulos QML que NO se instalan en disco porque el binario los REGISTRA en runtime
57# (`org.kde.plasma.shell` lo registra plasmashell; los `Qt*` los trae el propio Qt en otra ruta).
58# No se excluyen por una lista escrita a mano —eso envejece y no dice por qué— sino comprobando que
59# el URI esté como literal en un ELF del cierre: ver `registrado_en_binario()`. Se reportan aparte,
60# nombrando al registrador. Todo lo demás que salga acá es accionable.
61#
62#   uso:  python3 scripts/vigia-imagen.py [perfil...] [--fail] [--qml]
63#         --fail  → exit 1 si algún invariante falla; exit 2 si NO SE PUDO medir (nodos del cierre
64#                   sin artefacto sellado). Los dos son accionables y no son lo mismo.
65#         --qml   → además del resumen, listar los imports sin módulo
66import os, sys, glob, subprocess, re, json
67
68sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__))))
69import yupana
70import targets as targets_mod
71
72ROOT = yupana.ROOT
73STORE = os.environ.get("HAMMER_STORE", str(ROOT / "store"))
74HAMMER = str(ROOT / "target/release/takana")
75
76# Invariantes que un perfil NO cumple A PROPÓSITO. Un ✗ permanente por una decisión ya tomada es
77# deuda fantasma —la misma figura que la terna GNOME que hubo que sacar de targets.toml para que el
78# grafo dejara de mentir—, así que se declaran acá CON EL MOTIVO y se imprimen como ⊘, no como fallo.
79EXCEPCIONES = {
80    ("escritorio-mirada", "iconos"):   "imagen SLIM a propósito: compositor + greeter, sin escritorio",
81    ("escritorio-mirada", "hicolor"):  "idem",
82    ("escritorio-mirada", "cursores"): "el greeter dibuja su propio puntero",
83    ("escritorio-mirada", "fuentes"):  "idem slim",
84    ("escritorio-mirada", "terminal"): "no es un escritorio de uso general",
85    ("escritorio-sway", "iconos"):     "ninguna de sus 4 apps gráficas pide iconos de tema y zathura "
86                                       "es GTK4 (iconos de UI compilados); un tema COMPLETO exige "
87                                       "promover adwaita o breeze al corpus — decisión, no olvido",
88}
89
90# (Acá vivía `QML_EN_RUNTIME`, una lista escrita a mano de módulos que nadie instala en disco. La
91# reemplaza `registrado_en_binario()`, que contesta lo mismo con evidencia y además NOMBRA al
92# registrador. Al vaciarla, los cuatro que tenía se resolvieron solos —y `org.kde.kwin.effect` ni
93# siquiera se importa en ningún cierre: era una entrada muerta que nadie podía saber que sobraba.)
94
95_cache = {}
96def artefacto(cola, nombre):
97    """Directorio del artefacto de (cola,nombre) en el store, o None. Mismo método que vigia-sonames:
98    `hammer hash` sobre la receta de HOY, sin construir — no heurística de mtime."""
99    if (cola, nombre) in _cache:
100        return _cache[(cola, nombre)]
101    receta = ROOT / ("recipes/%s.toml" % nombre if cola == "corpus"
102                     else "recipes/%s/%s.toml" % (cola, nombre))
103    d = None
104    if receta.exists():
105        r = subprocess.run([HAMMER, "--store", STORE, "hash", str(receta)],
106                           capture_output=True, text=True)
107        h = r.stdout.strip().replace("b3:", "")
108        if len(h) == 64:
109            cand = glob.glob(os.path.join(STORE, h + "-*"))
110            d = cand[0] if cand else None
111    _cache[(cola, nombre)] = d
112    return d
113
114
115ICONO_EXT = (".png", ".svg", ".svgz", ".xpm")
116FUENTE_EXT = (".ttf", ".otf", ".ttc", ".pfb", ".pcf", ".pcf.gz")
117
118
119def registrado_en_binario(uri, dirs):
120    """¿Algún ELF del cierre lleva `uri` como literal? Entonces lo registra en C++ y NO falta.
121
122    ── POR QUÉ HACE FALTA ──────────────────────────────────────────────────────────────────────
123    Un `import org.kde.kscreenlocker` no siempre se satisface con un directorio y su `qmldir`. El
124    greeter de la pantalla de bloqueo hace `qmlRegisterUncreatableType<PamAuthenticator>(
125    "org.kde.kscreenlocker", …)`: el módulo existe SÓLO dentro del proceso que carga ese `.qml`, y
126    en disco no hay nada que instalar. Buscar el módulo en el sistema de ficheros da ✗ y la imagen
127    está perfecta.
128
129    Medido el 2026-09-05: los DOS únicos ✗ de qml que reportaba este vigía eran de esta clase
130    —`org.kde.kscreenlocker` en `libexec/kscreenlocker_greet` y `org.kde.newstuff.core` en
131    `libnewstuffqmlplugin.so`— o sea que el 100% de sus hallazgos eran falsos. Y un guardián que
132    grita en falso no se endurece: se ignora. Antes esto se tapaba anotando el módulo a mano en
133    una lista escrita a mano, que envejece y no dice por qué.
134
135    El literal queda en `.rodata` del binario, así que la pregunta se contesta con evidencia. Se
136    miran primero los artefactos cuyo nombre comparte una palabra con el URI (`kscreenlocker` →
137    `kscreenlocker`), que es donde está casi siempre, y sólo si no aparece se recorre el resto.
138    """
139    aguja = uri.encode()
140    tokens = [t for t in re.split(r"[.\-_]", uri.lower()) if len(t) > 3]
141
142    def primero_los_parecidos(par):
143        return 0 if any(t in par[0].lower() for t in tokens) else 1
144
145    for nombre, d in sorted(dirs.items(), key=primero_los_parecidos):
146        for raiz, _, ficheros in os.walk(d):
147            for f in ficheros:
148                ruta = os.path.join(raiz, f)
149                try:
150                    if os.path.getsize(ruta) > 256 * 1024 * 1024:
151                        continue
152                    with open(ruta, "rb") as fh:
153                        if fh.read(4) != b"\x7fELF":
154                            continue
155                        fh.seek(0)
156                        if aguja in fh.read():
157                            return "%s (%s)" % (os.path.relpath(ruta, d), nombre)
158                except OSError:
159                    continue
160    return None
161
162
163def escanear(nodos):
164    """Recorre los artefactos del cierre una sola vez y junta los cinco hechos."""
165    temas, cursores, fuentes, terminales = {}, {}, 0, {}
166    qml_modulos, qml_imports = set(), {}
167    sin_artefacto = []
168    dirs = {}
169    for (cola, nombre) in sorted(nodos):
170        d = artefacto(cola, nombre)
171        if not d:
172            sin_artefacto.append(nombre)
173            continue
174        dirs[nombre] = d
175        # ── temas de iconos y de cursores ───────────────────────────────────────────────────────
176        base = os.path.join(d, "usr/share/icons")
177        if os.path.isdir(base):
178            for t in sorted(os.listdir(base)):
179                td = os.path.join(base, t)
180                # ⚠ ICONOS y CURSORES no se buscan igual, y medirlos con la misma regla dio un ✗
181                # falso el 2026-09-04: `adwaita-cursors` instalaba `Adwaita/cursors/` poblado y este
182                # vigía seguía diciendo «NINGÚN tema de cursor» porque el directorio no traía
183                # `index.theme`. Para un tema de ICONOS ese requisito es correcto —la búsqueda XDG
184                # recorre `Directories=` y sin el índice el tema no existe—, pero libXcursor y
185                # wlroots abren `<tema>/cursors/<nombre>` DIRECTO; `index.theme` sólo hace falta
186                # para seguir un `Inherits=`. Exigirlo también acá medía el invariante de al lado.
187                tiene_indice = os.path.exists(os.path.join(td, "index.theme"))
188                n_ico = n_cur = 0
189                for dp, _, fn in os.walk(td):
190                    for f in fn:
191                        if f.endswith(ICONO_EXT):
192                            n_ico += 1
193                        elif os.path.basename(dp) == "cursors":
194                            n_cur += 1
195                if n_ico and tiene_indice:
196                    temas.setdefault(t, (nombre, n_ico))
197                if n_cur:
198                    cursores.setdefault(t, (nombre, n_cur))
199                if t == "hicolor" and tiene_indice:
200                    temas.setdefault("hicolor", (nombre, n_ico))
201        # ── el resto, en UNA pasada por el árbol ────────────────────────────────────────────────
202        for dp, _, fn in os.walk(d):
203            for f in fn:
204                p = os.path.join(dp, f)
205                if f.endswith(FUENTE_EXT):
206                    fuentes += 1
207                elif f == "qmldir":
208                    # el módulo es la ruta relativa desde .../qml/ con puntos
209                    m = re.search(r"/qt\d*/qml/(.+)$", dp) or re.search(r"/qml/(.+)$", dp)
210                    if m:
211                        qml_modulos.add(m.group(1).replace("/", "."))
212                elif f.endswith(".qml"):
213                    # `designer/`: los `*Specifics.qml` de Qt son la integración con Qt Design Studio
214                    # (importan `HelperWidgets`, que sólo existe dentro de Qt Creator). Nunca se
215                    # cargan en runtime; contarlos era ruido puro.
216                    if "/designer/" in dp + "/":
217                        continue
218                    try:
219                        txt = open(p, encoding="utf-8", errors="replace").read()
220                    except OSError:
221                        continue
222                    # Y los imports DENTRO DE UN COMENTARIO no son imports: `QtMultimedia/Video.qml`
223                    # trae `import QtSystemInfo 5.0` en un bloque \qml de la documentación. Sin
224                    # despojar comentarios, el vigía reporta como hueco un ejemplo de un docstring.
225                    txt = re.sub(r"/\*.*?\*/", "", txt, flags=re.S)
226                    txt = re.sub(r"^\s*//.*$", "", txt, flags=re.M)
227                    for mod in re.findall(r"^\s*import\s+([A-Za-z][\w.]*)", txt, re.M):
228                        qml_imports.setdefault(mod, set()).add(nombre)
229                elif f.endswith(".desktop") and "/applications" in dp:
230                    try:
231                        txt = open(p, encoding="utf-8", errors="replace").read()
232                    except OSError:
233                        continue
234                    if re.search(r"^Categories=.*TerminalEmulator", txt, re.M):
235                        terminales.setdefault(f[:-8], nombre)
236    candidatos = {m: v for m, v in qml_imports.items()
237                  if m not in qml_modulos
238                  and not m.startswith(("QtQuick", "QtQml", "QtCore", "QtTest", "Qt5", "Qt."))
239                  and m != "Qt"}
240    # Último filtro, y el que decide: un módulo registrado en C++ no está «sin instalar».
241    faltan_qml, en_binario = {}, {}
242    for m, v in candidatos.items():
243        donde = registrado_en_binario(m, dirs)
244        if donde:
245            en_binario[m] = donde
246        else:
247            faltan_qml[m] = v
248    return temas, cursores, fuentes, terminales, faltan_qml, sin_artefacto, en_binario
249
250
251def informe_primera_pintura():
252    """El sexto dato: CUÁNTO TARDA la ventana en aparecer en la imagen ARRANCADA.
253
254    Los cinco invariantes de arriba se miden sobre artefactos y contestan «¿está lo que hace falta?».
255    Ninguno contesta «¿y cuándo se ve?», y esa pregunta ya cobró: el §6.10.ter del SDD 26 concluyó
256    que `atuq` «no pinta nunca» en la imagen con este vigía en ✓ — y la medición repetida mostró que
257    pintaba a los +137…+204 s, o sea que lo que se había medido era la paciencia del que miraba.
258
259    No se mide acá a propósito: arrancar la imagen son ~15 min de QEMU sin KVM y este guion corre en
260    segundos sobre el store. Lo que hace es LEER el número que dejó `scripts/cosmic/atuq-en-imagen.py`
261    y decirlo con sus condiciones —tiempo sin condiciones se lee como si fuera del producto, y
262    depende de la carga de la máquina anfitriona—. Si no hay medición, se dice; un hueco callado acá
263    es un ✓ que no se ganó.
264    """
265    ruta = os.path.join(str(ROOT), "docs/state/primera-pintura.json")
266    print("\n== primera pintura en la imagen arrancada  (no lo mide este vigía)")
267    if not os.path.exists(ruta):
268        print("   ⊘ sin medición — corré: scripts/cosmic/atuq-en-imagen.py --as-user --until-paint")
269        return False
270    try:
271        with open(ruta) as f:
272            corridas = json.load(f).get("corridas", [])
273    except (OSError, ValueError) as e:
274        print("   ⚠ %s ilegible: %s" % (ruta, e))
275        return False
276    if not corridas:
277        print("   ⊘ el fichero no tiene corridas")
278        return False
279
280    # Se informan TODAS las corridas y no la última, porque el fenómeno es INTERMITENTE. Y se separan
281    # por CUÁNTAS SALIDAS fotografió cada una: medido el 2026-09-14, con dos tarjetas DRM la ventana
282    # cae en cualquiera de las dos salidas, así que un ✗ de una corrida que sólo miró una pantalla NO
283    # dice que la ventana no esté: dice que no estaba EN ESA. Contarlos juntos fue lo que produjo un
284    # «3 de 13» que medía la cámara y no el producto.
285    ciegas = [c for c in corridas if c.get("pantallas_fotografiadas", 1) < 2
286              and "dos DRM" in (c.get("video") or "")
287              and c.get("segundos_primera_pintura") is None]
288    corridas = [c for c in corridas if c not in ciegas]
289    pintaron = [c["segundos_primera_pintura"] for c in corridas
290                if c.get("segundos_primera_pintura") is not None]
291    n, m = len(pintaron), len(corridas)
292    marca = "✓" if n == m else ("✗" if n == 0 else "⚠")
293    if ciegas:
294        marca = "⚠"      # con corridas ciegas de por medio, un 6/6 no es un ✓: es un «lo que se pudo medir»
295    if pintaron:
296        print("   %s pintaron %d de %d corridas CONCLUYENTES · primera pintura %s"
297              % (marca, n, m,
298                 ("+%ds" % pintaron[0]) if n == 1 else "+%d…+%ds" % (min(pintaron), max(pintaron))))
299    else:
300        print("   %s NINGUNA de %d corridas pintó" % (marca, m))
301    for c in corridas[-6:]:
302        seg = c.get("segundos_primera_pintura")
303        print("     %s %-9s %-10s %-22s %-26s %s"
304              % ("✓" if seg is not None else "✗",
305                 ("+%ds" % seg) if seg is not None else "—",
306                 (c.get("pantalla") or "")[:10],
307                 c.get("lanzamiento", "?"), c.get("video", "?"),
308                 (c.get("medido") or "")[:16]))
309    if ciegas:
310        print("     ⚠ %d corridas NO se cuentan: con dos salidas fotografiaron UNA sola, y su ✗ sólo"
311              " dice que la ventana no estaba en esa pantalla" % len(ciegas))
312    fallidas = [c for c in corridas if c.get("segundos_primera_pintura") is None]
313    if fallidas:
314        print("     ⚠ en las que NO pintó, el MOZ_LOG igual decía `mapped 1` + «has buffer» +"
315              " WaylandBufferSHM commiteado:")
316        print("       que Gecko commitee cuadros NO prueba que la ventana se vea. La evidencia es"
317              " el píxel, no el log.")
318    return n == 0
319
320
321def main():
322    args = [a for a in sys.argv[1:] if not a.startswith("--")]
323    fallar = "--fail" in sys.argv
324    detalle_qml = "--qml" in sys.argv
325    colas = yupana.cargar_colas()
326    perfiles = targets_mod.load()
327    memb = yupana.membresia(colas, perfiles)
328    quiero = args or [p for p in perfiles if p.startswith("escritorio")]
329    fallos = 0
330    parciales = set()
331    for perfil in quiero:
332        nodos = {n for n, ps in memb.items() if perfil in ps and n[0] != "wanted"}
333        if not nodos:
334            continue
335        temas, cursores, fuentes, terminales, faltan_qml, sin_art, en_binario = escanear(nodos)
336        reales = {t: v for t, v in temas.items() if t != "hicolor"}
337        print("== %-20s %3d nodos del cierre" % (perfil, len(nodos)))
338        parcial = bool(sin_art)
339        if parcial:
340            parciales.add(perfil)
341            # UN AUSENTE FALLA RUIDOSAMENTE: sin el artefacto no se puede afirmar NI que falta NI que
342            # está. Pasó al minuto de escribir este vigía: prender el QML de kcoreaddons dejó 71
343            # artefactos en deuda y el informe dijo «KDE no tiene terminal» teniendo konsole.
344            print("   ⚠ MEDICIÓN PARCIAL: %d de %d nodos sin artefacto sellado (deuda, o store "
345                  "incompleto) ⇒ los ✗ de abajo pueden ser de la deuda, no de la imagen"
346                  % (len(sin_art), len(nodos)))
347            print("     sin artefacto: %s%s" % (", ".join(sorted(sin_art)[:8]),
348                                                " …" if len(sin_art) > 8 else ""))
349
350        def linea(ok, etiqueta, texto):
351            nonlocal fallos
352            motivo = EXCEPCIONES.get((perfil, etiqueta))
353            if not ok and motivo:
354                print("   ⊘ %-10s %s" % (etiqueta, motivo))
355                return
356            if not ok and not parcial:
357                fallos += 1
358            print("   %s %-10s %s" % ("✓" if ok else "✗", etiqueta, texto))
359
360        linea(bool(reales), "iconos",
361              ", ".join("%s (%s, %d)" % (t, v[0], v[1]) for t, v in sorted(reales.items()))
362              or "NINGÚN tema con iconos — los applets/indicadores quedan de ancho cero")
363        linea("hicolor" in temas, "hicolor",
364              "presente" if "hicolor" in temas
365              else "FALTA el fallback freedesktop: los iconos que las apps instalan en "
366                   "usr/share/icons/hicolor son invisibles")
367        linea(bool(cursores), "cursores",
368              ", ".join("%s (%s)" % (t, v[0]) for t, v in sorted(cursores.items()))
369              or "NINGÚN tema de cursor — con cursor por software el puntero se mueve invisible")
370        linea(fuentes > 0, "fuentes",
371              "%d ficheros de fuente" % fuentes if fuentes
372              else "CERO fuentes (fontconfig es el motor que las busca, no una fuente)")
373        linea(bool(terminales), "terminal",
374              ", ".join("%s (%s)" % (k, v) for k, v in sorted(terminales.items()))
375              or "NINGÚN emulador de terminal — no se puede salir de un fallo")
376        nota = ""
377        if en_binario:
378            nota = " (%d registrado(s) en C++, no en disco)" % len(en_binario)
379        linea(not faltan_qml, "qml",
380              ("todos los import resuelven" + nota) if not faltan_qml
381              else "%d módulo(s) importado(s) y NO instalado(s)" % len(faltan_qml))
382        if en_binario and detalle_qml:
383            for m, donde in sorted(en_binario.items()):
384                print("        · %-38s lo registra: %s" % (m, donde))
385        if faltan_qml and (detalle_qml or True):
386            for m, quienes in sorted(faltan_qml.items()):
387                print("        FALTA %-34s ← lo importa: %s"
388                      % (m, ", ".join(sorted(quienes)[:4])))
389    fallo_pintura = informe_primera_pintura()
390    if parciales:
391        print("\n⚠ perfiles medidos a medias (deuda en el store): %s" % ", ".join(sorted(parciales)))
392    if fallar and (fallos or fallo_pintura):
393        return 1          # medí y FALTA
394    if fallar and parciales:
395        return 2          # NO pude medir — distinto de «está bien»
396    return 0
397
398
399if __name__ == "__main__":
400    sys.exit(main())