Manual de Referencia: spunkmeyer

Spunkmeyer — Detector de Antipatrones de Programación y Vicios Didácticos en C¶

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

La herramienta spunkmeyer 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:

2.2 Métodos de Instalación de spunkmeyer¶

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

2.3 Autocompletado en la Shell¶

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

# Configuración automática en Bash / Zsh / Fish
spunkmeyer --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:

spunkmeyer 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 spunkmeyer:

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
13
14
15
16
17
18
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>

void antipatrones_comunes(FILE *f) {
    // 1. Casteo de malloc innecesario en C
    int *v = (int*) malloc(sizeof(int) * 10);
    
    // 2. Comparación booleana redundante
    bool flag = true;
    if (flag == true) { /* ... */ }
    
    // 3. while(!feof) lee el último dato duplicado
    int x;
    while (!feof(f)) {
        fscanf(f, "%d", &x);
    }
}

Ejecución de la Herramienta¶

Ejecutá el análisis desde tu terminal:

spunkmeyer detect src/ include/

Salida Obtenida en Consola¶

⚠️ SPUNKMEYER DETECTÓ 3 ANTIPATRONES:
┌──────────────┬─────────────┬────────────────────────────────────────────────────────┐
│ Ubicación    │ Antipatrón  │ Corrección Pedagógica Recomendada                      │
├──────────────┼─────────────┼────────────────────────────────────────────────────────┤
│ app.c:6:14   │ MALLOC_CAST │ No castees el retorno de malloc() en C: 'int *v = mal…'│
│ app.c:10:9   │ BOOL_CMP    │ Simplificá 'if (flag == true)' por 'if (flag)'         │
│ app.c:14:5   │ WHILE_FEOF  │ 'while (!feof(f))' es erróneo. Validá el retorno de …  │
└──────────────┴─────────────┴────────────────────────────────────────────────────────┘

5. Ejercicios Prácticos y Desafíos¶

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

````{exercise} Desafío 2: Consulta de Explicación de while (!feof) :label: spunkmeyer-desafio-2 Leer el fundamento técnico de por qué feof no se activa antes de intentar leer.

Instrucción de ejecución:

spunkmeyer explain WHILE_FEOF

````{solution} spunkmeyer-desafio-2
```bash
spunkmeyer explain WHILE_FEOF
# Revisá el archivo generado o el informe en terminal para confirmar la resolución del problema.
```

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

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

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

.PHONY: check-spunkmeyer

Ejecutá make check-spunkmeyer 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 spunkmeyer implementa un motor de alta precisión basado en:

• Tecnología Núcleo: libclang AST Matcher + Antipattern Regex Classifier + Pedagogical Remediation Engine.

• 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¶

• daedalus (alertas tempranas)

• dredd (corrección) | Informes Markdown, diagnósticos Rich, JSON, actas | | Sincronización | ripley, gaff, esper | Validación cruzada, flags compartidos y autofix |

Pipeline de Integración Recomendado¶

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

# Pipeline de integración típico
spunkmeyer detect src/ && spunkmeyer fix src/

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

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

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