theus-cli-linux-arm64 1.2.1 → 1.3.0

package/vendor/higiene-motor/PARCHES.md

@@ -0,0 +1,244 @@
+# Parches del motor de Higiene respecto del original
+
+Este directorio es una **copia vendorizada** del motor de higiene de ficheros
+(Python, biblioteca estándar pura) que vive en el árbol de referencia
+`watermarks-remover-upstream/service/scripts/`. Los 28 ficheros `.py` de aquí
+son ese motor, y **siete de ellos llevan parches**. El resto son copias byte a
+byte.
+
+El motivo de escribir esta lista: el día que se actualice el motor de origen,
+la copia se rehará y estos parches hay que **reaplicarlos uno a uno**. Sin este
+fichero se pierden en silencio y el CLI vuelve a los mismos tres fallos.
+
+## Regla de oro
+
+El motor **no se refactoriza aquí**. Cada parche es la mínima intervención que
+arregla un fallo verificado en esta máquina, y lleva un comentario en el propio
+código que empieza por `PARCHE Theus` para que se pueda encontrar con:
+
+```bash
+grep -rn "PARCHE Theus" theuscode/vendor/higiene-motor/
+```
+
+## Entorno objetivo
+
+**Python 3.9.** No es una elección: el `python3` de serie de macOS es 3.9.6
+(verificado en esta máquina), el motor se invoca con el intérprete que haya y
+Theus no embarca uno propio. Todo lo que sea sintaxis o API de 3.10+ revienta en
+la máquina de un usuario que no tenga nada instalado — que es el caso normal.
+
+---
+
+## Parche 1 · `container_meta.py` — falta `from __future__ import annotations`
+
+**Fallo:** el fichero usa anotaciones `X | None` en firmas de nivel de módulo,
+que en 3.9 se evalúan de verdad al importar. Sin el `__future__`, importar el
+módulo aborta:
+
+```
+File "container_meta.py", line 158, in <module>
+  def detect_container_format(path: Path, data: bytes | None = None) -> str:
+TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
+```
+
+`container_meta` es la tubería de PDF, DOCX, ODT, EPUB, SVG, HTML y Markdown —
+o sea, media Higiene — y además lo importan `format_dispatch`, `inspect_file`,
+`clean_file` y `server`. Con esto roto no arranca **nada** del motor.
+
+**Parche:** `from __future__ import annotations` como primera sentencia tras el
+docstring, exactamente igual que en los otros 27 ficheros.
+
+**Cómo comprobar que sigue puesto:**
+
+```bash
+cd theuscode/vendor/higiene-motor && PYTHONPATH=. python3 -c "import container_meta"
+```
+
+**Ojo al reaplicar:** el árbol de referencia de esta máquina ya tiene el arreglo
+metido a mano (mtime posterior al del resto de ficheros), así que un `diff`
+contra él NO muestra este parche. Contra el origen de verdad sí. Los otros 27
+ficheros lo traen de fábrica; la comprobación que vale es que **los 28** importen
+en 3.9, no el diff.
+
+---
+
+## Parche 2 · `audit_lib.py` y `rewrite_text.py` — APIs de 3.10+
+
+### 2a · `zip(..., strict=False)` (audit_lib.py, dos veces)
+
+`strict=` es parámetro de `zip()` desde **3.10**; en 3.9 es `TypeError`.
+
+Se quita, sin más: `strict=False` era **el comportamiento por defecto** de
+`zip()` de toda la vida (parar en la secuencia más corta), así que quitarlo es
+equivalente exacto, no una degradación. Lo que no se puede hacer es cambiarlo por
+`strict=True`, que sería otra semántica.
+
+Aparece en el formateador de texto del informe (línea ~208) y en el generador de
+SARIF (línea ~280). Son rutas de salida, no de análisis: el fallo no se veía al
+importar, solo al pedir un informe.
+
+### 2b · `itertools.pairwise` (rewrite_text.py, una vez)
+
+`itertools.pairwise` es de **3.10**. Está dentro de `_bigrams()`, que alimenta la
+divergencia léxica de la reescritura, así que no fallaba al importar sino al
+usarlo — peor, porque pasa el arranque y muere en caliente.
+
+Se sustituye por `zip(tokens, tokens[1:])`, que sobre una lista da exactamente
+los mismos pares y en el mismo orden.
+
+`import itertools` se deja en su sitio aunque quede sin uso: mantener el diff
+mínimo vale más que ahorrar una línea, y ningún linter del repo mira este
+directorio.
+
+---
+
+## Parche 3 · `format_dispatch.py` — la tabla de extensiones de texto
+
+**Fallo:** `TEXT_EXTS` tenía **trece** extensiones:
+
+```
+.txt .text .css .js .py .rs .go .json .yaml .yml .toml .csv
+```
+
+Ni `.ts` ni `.tsx`. Pasado sobre el repo del CLI de Theus, que está escrito
+entero en TypeScript, clasificaba **271 de 275 ficheros como `unknown`** — y
+`clean_file.py` se niega, con razón, a tocar un `unknown`. Una herramienta de
+higiene de código que no reconoce el lenguaje del producto no mira dentro de
+ningún fichero y siempre informa «limpio».
+
+**Parche:** `TEXT_EXTS` pasa a **141 extensiones**, generadas como la unión de
+`EXT_CODIGO` y `EXT_PROSA` de
+`theuscode/services/higiene/clasificador.ts`, menos lo que ya reclaman
+`IMAGE_EXTS`, `CONTAINER_EXTS` y `AV_EXTS` de este mismo fichero.
+
+Se añade además `TEXT_NAMES` (28 entradas: `makefile`, `dockerfile`,
+`jenkinsfile`, `.bashrc`, `.prettierrc`…), consultada por `classify()` **antes**
+que la extensión, porque son ficheros de texto sin extensión que si no caían en
+`unknown`. `classify_bytes()` no la usa: recibe un sufijo, no un nombre, y no
+puede saber cómo se llama el fichero.
+
+**Lo que a propósito NO se tocó:**
+
+- `CONTAINER_EXTS` sigue como en el original. `clasificador.ts` incluye `.ods` y
+  `.odp`, pero `detect_container_format()` no sabe abrirlos: meterlos aquí los
+  enrutaría a una tubería que devuelve `unknown` y no ganaríamos nada.
+- `AV_EXTS` (en `av_meta.py`) sigue con siete extensiones. `clasificador.ts`
+  lista trece — `.aac`, `.ogg`, `.opus`, `.webm`, `.mkv`, `.avi` de más — pero
+  el motor solo sabe leer ISOBMFF, WAV, MP3 y FLAC. Es una divergencia
+  **conocida y deliberada**: la parte nativa sabe que un `.webm` es audiovisual
+  y no lo trata como texto; el motor auxiliar simplemente no tiene nada que
+  decir sobre él.
+- El orden de comprobación de `classify()`/`classify_bytes()`: imagen →
+  contenedor → texto → audiovisual. Por eso `.md`, `.html` y `.svg` siguen
+  yendo a la tubería de **contenedor** aunque `clasificador.ts` los llame prosa:
+  llevan portada y metadatos además del cuerpo textual y hay que mirarlos aparte.
+
+**Invariante que hay que mantener:** `TEXT_EXTS` y `clasificador.ts` son la misma
+decisión escrita dos veces. Si se toca una, hay que regenerar la otra, o se
+pudren por separado y el enganche nativo y el motor auxiliar dejan de estar de
+acuerdo sobre qué es texto.
+
+---
+
+## Parche 4 · `common.py`, `clean_file.py`, `clean_image.py`, `clean_text.py` — el `.bak` preexistente destruía el original
+
+**Fallo:** `backup_path()` conserva un `.bak` que ya estuviera al lado y
+devuelve `created=False` (fallo #172: la segunda pasada de un enganche
+auto-corrector respaldaba la salida ya limpiada encima del original). Conservarlo
+es correcto; **quedarse ahí, no**. Ninguno de los tres llamadores miraba
+`created`, y las consecuencias eran distintas y las dos malas:
+
+- `clean_text.py` tiraba el valor de retorno entero. Con un `.bak` al lado, el
+  texto que se iba a sobrescribir no quedaba copiado en ninguna parte.
+- `clean_file.py --in-place` y `clean_image.py --in-place` hacen `src = bak`:
+  limpian **desde** el respaldo. Con un `.bak` ajeno, lo que se limpiaba era el
+  fichero ajeno y el resultado se renombraba encima del original — sustitución
+  silenciosa del contenido, no solo pérdida. Reproducido: `p.png` (1x1, 70 B)
+  con un `p.png.bak` ajeno (2x2, 78 B) al lado salía de la pasada siendo el 2x2
+  limpiado, byte a byte, y el 1x1 no estaba en ningún sitio.
+- `clean_image.py` además desempaquetaba mal: `bak = backup_path(...)` ataba la
+  **tupla** a `src`.
+
+**Parche:**
+
+1. `common.py` · `backup_path(src, unique=False) -> tuple[Path, bool]`. Con
+   `unique`, busca el primer nombre libre (`.bak`, `.bak.2`, `.bak.3`…) con tope
+   de 1.000; agotado devuelve `created=False` para que el llamador se niegue.
+   Espeja `respaldoUnico` de `services/higiene/io.ts`.
+2. Los tres llamadores: si `created` es `False`, reintento con `unique=True`. Se
+   eligió **caer a nombre único, no abortar**: Higiene tiene que fallar abierto y
+   negarse a limpiar cada vez que hay un `.bak` al lado deja clavado justo el
+   bucle del que salió el #172. Así se cumplen las dos cosas — el `.bak` pristino
+   sigue intacto y el contenido actual va a `.bak.2`.
+3. `clean_file.py` gana `finalize()`, que estampa en el JSON de las cuatro
+   tuberías (texto/imagen/av/contenedor) dos cosas que el consumidor no puede
+   deducir: `backup` (la ruta real; con un `.bak` previo es `.bak.2`) y `input`
+   corregido a la ruta que pidió el usuario, porque `--in-place` limpia desde el
+   sidecar y los sub-limpiadores devolvían su ruta.
+
+**Invariante que hay que mantener:** el par «no se pisa un respaldo previo» +
+«los bytes que se sobrescriben quedan copiados» solo se cumple con las dos
+mitades. Un llamador nuevo de `backup_path()` que ignore `created` reabre el
+fallo. La clave `backup` del JSON es lo que `services/higiene/motor.ts` lee para
+que el informe del CLI no prometa un respaldo que no existe: si desaparece, el
+CLI vuelve a deducir `${ruta}.bak` y a mentir.
+
+**Cómo se comprueba:**
+
+```bash
+cd theuscode/vendor/higiene-motor
+d=$(mktemp -d); printf 'ORIGINAL\n' > "$d/a.txt"; printf 'AJENO\n' > "$d/a.txt.bak"
+python3 clean_file.py "$d/a.txt" --in-place --json | grep '"backup"'
+grep -l ORIGINAL "$d"/*   # el original tiene que seguir existiendo en algún fichero
+cat "$d/a.txt.bak"        # y el ajeno, intacto
+```
+
+---
+
+## Verificación completa tras reaplicar
+
+```bash
+cd theuscode/vendor/higiene-motor
+# 1) los 28 módulos importan en el Python de serie
+for f in *.py; do PYTHONPATH=. python3 -c "import ${f%.py}" || echo "FALLA $f"; done
+# 2) la tabla de texto reconoce TypeScript
+PYTHONPATH=. python3 -c "from format_dispatch import TEXT_EXTS, TEXT_NAMES; \
+  assert '.ts' in TEXT_EXTS and '.tsx' in TEXT_EXTS; \
+  assert 'makefile' in TEXT_NAMES; print(len(TEXT_EXTS), len(TEXT_NAMES))"
+# 3) el puente del CLI, que es quien lo usa de verdad
+cd ../../.. && bun run theuscode/services/higiene/pruebaMotor.ts
+```
+
+## Lo que NO se copió del origen
+
+`bench_synthid_text.py` y los `requirements-*.txt` / `setup_*.sh` / `setup_*.ps1`.
+Los primeros exigen `torch` y `transformers`; los segundos instalan esas
+dependencias pesadas. Nada de Higiene los invoca: el motor vendorizado es
+**biblioteca estándar pura** y ese es su rasgo de diseño más valioso, porque es
+lo que permite ejecutarlo con el `python3` que el usuario ya tiene sin instalarle
+nada.
+
+Cuatro de los ficheros que sí se copiaron —`score_stylometry.py`,
+`text_detectors.py`, `detect_text_watermark.py`, `markdiffusion_harness.py`— y
+`score_synthid.py` **importan** en 3.9 sin dependencias, pero algunas de sus
+funciones sí las piden en caliente. Se copian porque son la referencia de la capa
+B; el puente del CLI (`services/higiene/motor.ts`) no los invoca.
+
+## Herramientas externas opcionales
+
+El motor no las necesita para arrancar, pero **sí cambian lo que puede afirmar**:
+
+| Herramienta | Para qué | Sin ella |
+| --- | --- | --- |
+| `exiftool` | quitar metadatos de PDF e imágenes | limpieza de PDF «al mejor esfuerzo» |
+| `qpdf` | reescritura estructural del PDF | los bytes de metadatos que `exiftool` libera siguen siendo recuperables |
+| `ghostscript` (`gs`) | pasada profunda: metadatos dentro de imágenes incrustadas en el PDF | los metadatos de las imágenes incrustadas sobreviven |
+| `c2patool` | leer manifiestos C2PA reales | **el motor no puede decir «limpio» de C2PA, solo «no concluyente»** |
+
+La última fila es la importante y tiene función propia en el motor,
+`c2patool_probe_note()` (`common.py:429`): `c2patool` sale con código distinto de
+cero **tanto** si el fichero no tiene manifiesto **como** si el binario falló, así
+que quien solo lea `has_manifest` no distingue «este fichero está limpio» de «la
+sonda nunca corrió». Informar lo segundo como lo primero es la dirección
+peligrosa. El puente respeta esa distinción: ver `c2paConcluyente` en
+`services/higiene/motor.ts`.

package/vendor/higiene-motor/audit_dir.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Aggregate AI-provenance audit over a directory tree.
+
+Recursively inspects supported text/image/container files and emits one
+summary plus a per-file finding list with confidence classifications.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from audit_lib import aggregate, format_sarif, print_human_report, scan_file
+from common import EXIT_PARTIAL, MAX_INPUT_BYTES, emit_json, eprint
+
+DEFAULT_SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    ".next",
+    "target",
+    ".cache",
+}
+
+
+def walk_files(root: Path, skip_dirs: set[str]):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in skip_dirs and not d.startswith("."))
+        for fn in sorted(filenames):
+            path = Path(dirpath) / fn
+            if path.is_file():
+                yield path
+
+
+def _scan_worker(path: Path, check_stylometry: bool) -> tuple[dict | None, dict | None]:
+    try:
+        if path.stat().st_size > MAX_INPUT_BYTES:
+            return None, {"path": str(path), "reason": "too large"}
+        return scan_file(path, check_stylometry=check_stylometry), None
+    except Exception as e:  # keep the audit going on one bad file
+        return None, {"path": str(path), "reason": str(e)}
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("path", type=Path, help="Directory to audit recursively")
+    p.add_argument(
+        "--format",
+        choices=["human", "json", "sarif"],
+        default="human",
+        help="Output format (default: human)",
+    )
+    p.add_argument(
+        "--json", action="store_true", help="Emit a JSON report (alias for --format json)"
+    )
+    p.add_argument(
+        "--sarif",
+        action="store_true",
+        help="Emit an OASIS SARIF 2.1.0 report (alias for --format sarif)",
+    )
+    p.add_argument(
+        "-j",
+        "--jobs",
+        type=int,
+        default=min(32, (os.cpu_count() or 1) + 4),
+        help="Number of concurrent worker threads (default: CPU cores + 4)",
+    )
+    p.add_argument(
+        "--check-stylometry",
+        action="store_true",
+        help="Also evaluate text files for AI statistical & stylometric signals",
+    )
+    p.add_argument(
+        "--skip",
+        default="",
+        help="Comma-separated extra directory names to skip",
+    )
+    args = p.parse_args()
+
+    root = args.path
+    if not root.is_dir():
+        eprint(f"not a directory: {root}")
+        return 2
+
+    skip_dirs = set(DEFAULT_SKIP_DIRS)
+    for raw_part in args.skip.split(","):
+        part = raw_part.strip()
+        if part:
+            skip_dirs.add(part)
+
+    paths = list(walk_files(root, skip_dirs))
+    files: list[dict] = []
+    skipped: list[dict] = []
+
+    if args.jobs <= 1:
+        for path in paths:
+            f, s = _scan_worker(path, args.check_stylometry)
+            if f is not None:
+                files.append(f)
+            if s is not None:
+                skipped.append(s)
+    else:
+        with ThreadPoolExecutor(max_workers=args.jobs) as pool:
+            futures = [pool.submit(_scan_worker, p, args.check_stylometry) for p in paths]
+            for fut in futures:
+                f, s = fut.result()
+                if f is not None:
+                    files.append(f)
+                if s is not None:
+                    skipped.append(s)
+
+    files.sort(key=lambda x: str(x.get("path", "")))
+    skipped.sort(key=lambda x: str(x.get("path", "")))
+
+    summary = aggregate(files)
+    report = {
+        "root": str(root),
+        "files_scanned": len(files),
+        "files_skipped": skipped,
+        "summary": summary,
+        "files": files,
+    }
+
+    out_format = args.format
+    if args.json:
+        out_format = "json"
+    elif args.sarif:
+        out_format = "sarif"
+
+    if out_format == "json":
+        emit_json(report)
+    elif out_format == "sarif":
+        sarif_doc = format_sarif(report)
+        emit_json(sarif_doc)
+    else:
+        print_human_report(
+            files,
+            summary,
+            extra_header={
+                "Root": report["root"],
+                "Files skipped": str(len(skipped)),
+            },
+        )
+
+    # A partial scan (one or more files could not be scanned) is reported
+    # with a distinct code in every output format: incomplete audits are
+    # the more important CI signal and take precedence over actionable.
+    return EXIT_PARTIAL if skipped else (1 if summary["actionable_files"] else 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())