Preflight

Una regla sabe cómo comprobar algo. Su política decide si se ejecuta, sus parámetros, gravedad y comportamiento de bloqueo. Dos proyectos usan el mismo assembly con límites de tamaño distintos, sin bifurcar el código. La lógica se prueba por separado y los requisitos pueden cambiar sin recompilar la herramienta.

{
    "schemaVersion": 1,
    "pipeline": "projecta",
    "rules": {
        "core.presubmit.large-file": {
            "settings": {
                "maxBytes": 5242880
            }
        }
    },
    "targets": {
        "win64": {
            "rules": {
                "core.presubmit.large-file": {
                    "settings": {
                        "maxBytes": 2621440
                    }
                }
            }
        }
    }
}

Las reglas declaran dependencias y se ejecutan por niveles topológicos. Las comprobaciones independientes comparten un nivel; los siguientes esperan sus requisitos. Si falla la comprobación de la toolchain, una sonda de compilación dependiente puede omitirse en lugar de producir otro fallo previsible.

La atribución de causa raíz recorre la cadena atravesando omisiones intermedias. El mensaje final apunta a la toolchain ausente, dando un problema que resolver en lugar de una lista de síntomas. La etapa selecciona las raíces del grafo sin descartar dependencias de otras etapas.

Elegí una barrera entre niveles para simplificar la propagación de fallos y la coordinación. Una regla lenta retrasa el siguiente nivel aunque parte de él pudiera empezar. Es un coste deliberado: la ejecución es más fácil de auditar y el informe se ordena por nivel e ID, sin depender de qué tarea termina primero.

Una convención de nombres puede bloquear un submit sin volver inútil la compilación. Una sonda opcional puede ser un requisito técnico aunque su fallo no deba rechazar el envío. Un único booleano no expresa ambos casos. Preflight separa blocking, que afecta al resultado y al código de salida, de gating, que detiene reglas dependientes. La gravedad sigue siendo el nivel de comunicación.

Las políticas heredan parámetros, aplican destinos explícitos de plataforma/configuración y sellan claves contra cambios posteriores. Los sellos se acumulan en la cadena de herencia, impidiendo que un proyecto retire silenciosamente una restricción de la organización. Los overlays locales quedan fuera de CI.

El comando explain registra el origen de los valores efectivos: paquete, archivo, línea y valores reemplazados. Los ejes de destino deben indicarse explícitamente para coincidir con un bloque. Así, una configuración predeterminada no elige silenciosamente otra política de producción.

La precedencia debe ser visible porque un valor JSON no explica por sí solo la configuración efectiva. Sin procedencia, investigar diferencias entre una máquina y CI obligaría a reconstruir la herencia manualmente. preflight explain aporta esos datos desde la propia resolución.

Las reglas implementan IValidationRule mediante Preflight.Abstractions. El acceso a archivos, procesos, cambios y políticas llega por los servicios de RuleContext, permitiendo pruebas sin el workspace real. El assembly de reglas integradas no tiene una dependencia privilegiada de Core.

Los plugins se cargan en contextos de assembly separados y recolectables, compartiendo el contrato con el host. Las versiones de dependencias pueden coexistir; los IDs duplicados y contratos incompatibles se rechazan explícitamente. Es aislamiento de dependencias, no una sandbox de seguridad: los plugins siguen siendo código confiado por el responsable del pipeline.

Un paquete contiene política, assemblies de reglas y un manifiesto con SHA-256 por archivo y un rango de contrato compatible. El orden estable de las entradas y las fechas fijas hacen reproducibles sus bytes. La instalación verifica el paquete antes de confirmarlo en el almacén instalado.

El checkout declara un rango de versiones aceptadas; una máquina puede fijar una versión para volver atrás. Instalar un paquete no cambia ese pin. Preflight no busca actualizaciones por su cuenta: la distribución usa el canal de artefactos del estudio sin cambiar las reglas por sorpresa.

Passed, Warning, Failed, Errored, Skipped y NotApplicable tienen significados distintos. Una regla sin elementos aplicables no afirma éxito; un fallo de la regla se distingue de un defecto del workspace. Consola, JSON y SARIF presentan los mismos datos. Los códigos de salida diferencian un cambio bloqueado de una configuración inválida y un error interno.

El historial es NDJSON local append-only; las estadísticas de duración requieren suficientes observaciones. La herramienta puede medir un comando de build, pero medir su duración no demuestra que fue validado ni que el software funcione.

El determinismo se aplica al veredicto y al orden de hallazgos con entradas iguales, incluyendo entorno inspeccionado y versión de pipeline. La duración y el runId varían por diseño; comparar bytes exige controlar esos campos. La misma política en máquinas con SDK diferentes puede producir correctamente resultados distintos.

La caché se activa explícitamente y solo admite reglas que proporcionan una huella de sus entradas. La clave incluye también la política efectiva, etapa, destino, generación del contrato e identidad del assembly. Cambiar un límite o recompilar un plugin invalida el resultado anterior. Los resultados en caché se identifican sin presentarlos como nuevas comprobaciones.

La decisión exige que el autor describa las entradas relevantes de su regla. Para una sonda incapaz de representar su entorno de forma fiable, repetir la ejecución es preferible a reutilizar evidencia incompleta. La caché está desactivada por defecto.