Manual de Referencia: zhora

Zhora — Linter y Auditor de Seguridad en Macros del Preprocesador #define¶

1. Propósito y Filosofía Pedagógica¶

La herramienta zhora forma parte del ecosistema oficial de software de la cátedra. Su diseño sigue principios pedagógicos rigurosos:

1. Evidencia Técnica Directa: Todo diagnóstico se fundamenta en la norma ISO C (C11/C23), en el modelo de memoria del sistema o en convenciones arquitectónicas formales.

2. Acción Correctiva Concreta: Cada advertencia incluye la prescripción técnica inmediata para resolver el defecto sin recurrir a conjeturas.

3. Autonomía del Estudiante: Facilita la autoevaluación local antes de la entrega final del trabajo práctico.

4. Objetividad Docente: Estandariza la corrección automática removiendo discrepancias subjetivas en la evaluación.

2. Instalación y Verificación del Entorno¶

2.1 Requisitos Previos del Sistema¶

Instalá los paquetes del sistema requeridos según tu distribución o entorno:

1
2
3
4
5
6
7
8
9
10
11
12
sudo apt update && sudo apt install -y \
    build-essential \
    gcc \
    gdb \
    valgrind \
    clang-format \
    libclang-dev \
    bubblewrap \
    typst \
    graphviz \
    python3-pip \
    python3-venv

1
2
3
4
5
6
7
8
9
10
11
sudo pacman -S --needed \
    base-devel \
    gcc \
    gdb \
    valgrind \
    clang \
    bubblewrap \
    typst \
    graphviz \
    python-pip \
    uv

1
2
3
4
5
6
7
8
9
10
sudo dnf install -y \
    gcc \
    gcc-c++ \
    gdb \
    valgrind \
    clang-tools-extra \
    bubblewrap \
    typst \
    graphviz \
    python3-pip

brew install gcc gdb clang-format typst graphviz uv

1
2
3
4
5
6
# En WSL2 (Ubuntu): utilizar los paquetes de Ubuntu/Debian arriba.
# En MSYS2 MINGW64:
pacman -S --needed \
    mingw-w64-x86_64-gcc \
    mingw-w64-x86_64-gdb \
    mingw-w64-x86_64-clang-tools-extra

2.2 Métodos de Instalación de zhora¶

Podés instalar zhora mediante cualquiera de los siguientes métodos estándar:

# Instalación aislada de alta velocidad con uv
uv tool install . --editable

# O instalar todo el ecosistema de herramientas de la cátedra en lote:
source ./install_tools.sh

# Crear y activar un entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# Instalar en modo editable para desarrollo
pip install -e .

# Instalación global aislada en tu PATH
pipx install --editable .

2.3 Autocompletado en la Shell¶

La interfaz CLI de zhora cuenta con autocompletado nativo para comandos, flags y archivos. Para configurarlo permanentemente en tu shell:

# Configuración automática en Bash / Zsh / Fish
zhora --install-completion

# Para cargar el autocompletado en la sesión actual de inmediato:
source ./install_tools.sh

2.4 Verificación del Entorno con doctor¶

Toda herramienta del ecosistema cuenta con el subcomando unificado doctor. Ejecutalo para auditar el estado del entorno:

zhora doctor

Comprobaciones Ejecutadas por el Diagnóstico:¶

• Compilador C: Verifica disponibilidad de gcc o clang con soporte de estándares C11 y C23.

• Depurador y Core Dumps: Comprueba que gdb esté instalado y que ulimit -c permita generación de core dumps.

• Herramientas de Memoria: Valida la presencia de valgrind y librerías libasan/libubsan.

• Formateo y Estilo: Verifica el binario clang-format (versión 16+).

• Sandboxing de Kernel: Audita permisos no privilegiados de bwrap (Bubblewrap namespaces).

• Generador de Tipografía y Documentos: Comprueba typst ($\ge 0.11$) y dot (Graphviz).

Matriz de Resolución de Problemas:¶

3. Referencia Completa de Comandos CLI¶

A continuación se detallan los subcomandos principales disponibles en zhora:

4. Tutorial Paso a Paso con Ejemplos Reales¶

Caso de Estudio¶

Considerá el siguiente fragmento de código representativo:

1
2
3
4
5
6
7
8
9
10
11
12
// Macro insegura: falta de paréntesis y doble evaluación de argumentos
#define CUADRADO_MAL(x) x * x
#define MAX_MAL(a, b) ((a) > (b) ? (a) : (b))

// Invocaciones problemáticas:
// CUADRADO_MAL(1 + 2) expande a: 1 + 2 * 1 + 2 = 5 (esperado: 9)
// MAX_MAL(i++, j) evalúa 'i++' dos veces si 'a > b'

// Macro segura auditada por Zhora:
#define CUADRADO_BIEN(x) ((x) * (x))
// O preferiblemente función inline:
static inline int cuadrado(int x) { return x * x; }

Ejecución de la Herramienta¶

Ejecutá el análisis desde tu terminal:

zhora audit include/ src/

Salida Obtenida en Consola¶

1
2
3
4
5
6
7
8
9
10
⚠️ ZHORA PREPROCESSOR SECURITY REPORT:
┌─────────────────┬────────────────────────────────────────────────────────┐
│ Ubicación       │ Diagnóstico de Seguridad y Sugerencia                  │
├─────────────────┼────────────────────────────────────────────────────────┤
│ macros.h:2:9    │ Macro 'CUADRADO_MAL': Parámetro 'x' sin paréntesis.    │
│                 │ 'x * x' fallará ante expresiones compuestas (1 + 2).   │
│ macros.h:3:9    │ Macro 'MAX_MAL': Doble evaluación de 'a'. Riesgo grave │
│                 │ ante argumentos con efectos colaterales (i++).         │
└─────────────────┴────────────────────────────────────────────────────────┘
💡 Ejecutá 'zhora fix include/macros.h' para agregar paréntesis protectores.

5. Ejercicios Prácticos y Desafíos¶

Practicá el uso avanzado de zhora resolviendo los siguientes ejercicios:

6. Integración en el Flujo de Trabajo y Makefile¶

Para incorporar zhora de forma automática a tu flujo de desarrollo, agregá la siguiente regla en el Makefile de tu proyecto:

check-zhora:
	@echo "=== Ejecutando verificación con zhora ==="
	zhora check src/ include/

.PHONY: check-zhora

Ejecutá make check-zhora antes de cada commit para mantener que tu código conserve el estado de aprobación.

7. Arquitectura Interna y Mecanismo Técnico¶

La herramienta zhora implementa un motor de alta precisión basado en:

• Tecnología Núcleo: `Clang Macro Expander + Preprocessor Security Tokenizer

  • Inline Function Transformer`.

• Aislamiento y Determinismo: Diseñada para operar sin efectos colaterales en entornos de integración continua (CI), terminales de estudiantes y servidores docentes headless.

• Manejo de Errores Pedagógico: Todo fallo de sintaxis, memoria o lógica se traduce en una acción prescriptiva concreta con su respectiva justificación técnica.

8. Integración y Conexión con el Ecosistema¶

Diagrama de Flujo e Interoperabilidad¶

Matriz de Intercambio de Datos¶

• corbel (funciones inline tipadas) | Informes Markdown, diagnósticos Rich, JSON, actas | | Sincronización | ripley, corbel, gaff | Validación cruzada, flags compartidos y autofix |

Pipeline de Integración Recomendado¶

Podés encadenar zhora con otras herramientas del ecosistema en una única línea de comando:

# Pipeline de integración típico
zhora audit include/macros.h && zhora fix include/macros.h

9. Extensión, Desarrollo de Plugins y API Python¶

Para crear tus propias reglas, conectores de evaluación o integrar zhora programáticamente en pipelines de CI/CD:

• 👉 Consultá la guía completa: Guía de Extensión y Creación de Plugins