Esta guía es para quien decide cuál es el estándar. Una regla es una sección del estándar en inglés, importada al analizador y traducida desde ahí. Nada se copia dentro de un proyecto, así que la regla que escribes hoy es la regla que mañana lee cada asistente conectado, sin que nadie actualice nada de su lado.
1. Escribe la regla en inglés
Los estándares viven en docs/coding-standards/en/, un archivo por estándar. Agrega tu regla como un encabezado dentro de ## Rules, en el archivo al que pertenece.
Escribe tres cosas:
- Un nombre lo bastante corto para leerse en un hallazgo, porque ahí es donde aparece.
- Qué revisa, en una o dos frases, redactado como instrucción.
- Por qué existe. Una regla sin motivo no se puede discutir, así que se rodea en lugar de seguirse.
Después muestra el código incorrecto y el correcto, en ese orden. Casi toda la utilidad de una regla para quien la lee está en ese ejemplo.
Cuando la revisión automática es más angosta que la redacción —reporta una forma del error y no la otra— dilo dentro de la regla. Quien sabe qué alcanza la revisión deja de esperar que le atrapen el resto.
2. Marca una sección que no es una regla
Un estándar también tiene secciones que quien lee necesita y que ninguna revisión puede ejecutar: la introducción de un capítulo, la repetición de una regla escrita en otro lado, una nota sobre qué no reportar. Márcalas con un comentario y la importación las deja fuera:
<!-- not-a-rule -->
La sección se queda en el estándar y se queda en la página pública. Simplemente nunca se convierte en una regla con un veredicto encima.
3. Impórtala
php artisan get:analyzers
La importación lee cada estándar y sincroniza las reglas contra él: qué se creó, qué cambió y qué ya no existe en el Markdown y por lo tanto se eliminó.
Para ver esa lista sin escribir nada:
php artisan get:analyzers --dry-run
4. Dale una revisión, o acepta que se lee y no se ejecuta
Una regla se analiza solo cuando una revisión determinista puede decidirla con el archivo que tiene enfrente. La importación reporta las demás como pendientes de una clase de regla: quedan publicadas y legibles, y nunca producen un hallazgo.
Eso es un estado real y no una falla. Algunas reglas se pueden probar desde un archivo y otras no, y las cuatro que nunca podrán están en Lo que el analizador no puede revisar.
Lo que nunca es aceptable es reportar una regla leída por una persona como una pasada del analizador. Son cosas distintas y se reportan como cosas distintas.
5. Prueba la revisión contra archivos reales
Antes de que una revisión nueva o cambiada llegue a nadie, mira qué habría dicho de archivos que el analizador ya juzgó. En el panel de administración, abre Validador de reglas en el menú lateral (/admin/rule_automation_lab). Solo lista reglas enlazadas a una clase de revisión que existe; Tipo de automatización las acota a las clases con process(), con preprocess() o con las dos, y Tipo de regla y Regla eligen la que vas a probar.
La página muestra la clase enlazada a la regla, el texto de la regla, y cuántas veces ha corrido, pasado y fallado hasta ahora. En Ejemplos reales toma hasta veinte archivos distintos del historial, balanceados entre ejecuciones que pasaron y que fallaron y repartidos en el tiempo. Probar ejemplos corre la clase actual sobre cada uno y pone su veredicto junto al que se registró en su momento: Estatus original, Estatus del test y Coincide — Sí cuando coinciden, No cuando no, y No aplica cuando la clase no decidió. Abre un archivo para comparar la respuesta original con la repetición, y para ver qué conservó preprocess() de él.
Un No vale la pena leerlo antes de publicar la revisión: o el veredicto viejo estaba mal, o la clase nueva lo está. La prueba no guarda nada, así que córrela cada vez que cambies la clase.
6. Tradúcela
php artisan standards:translate
Cada regla traducida lleva una huella del inglés del que salió, así que una ejecución solo traduce lo nuevo y lo que cambió desde la anterior. Acótala a un solo estándar con --type="Laravel Models", traduce todo otra vez con --force, o mira qué pasaría con --dry-run.
Después verifica el resultado:
php artisan standards:check
Lista cada regla que falta, que quedó desfasada o que sobró de una regla en inglés que ya no existe. Compara huellas en lugar de preguntarle a un modelo, así que no cuesta nada y puede correr en cada commit.
7. Corregir una traducción
Reescribir el español para que se lea como escrito y no como traducido es bienvenido. Cambiar lo que dice no lo es: los dos idiomas son una sola regla, y quien lee no tiene manera de saber cuál versión es la verdadera cuando se contradicen.
Cuando lo que tiene que cambiar es el contenido, cambia el inglés y vuelve a traducir. La fuente se mueve primero, siempre. Una regla corregida a mano la reporta la verificación. La siguiente traducción la conserva mientras su inglés no haya cambiado; solo se reemplaza cuando el inglés se mueve o cuando vuelves a traducir con --force, y entonces el comando nombra cada corrección a mano que reemplazó.
8. Barre lo que ya existe
Una regla nueva casi siempre encuentra algo en código escrito antes que ella. Pásala por todo antes de anunciarla:
php artisan validate:project --rule="Meaningful Scopes"
Eso recorre el proyecto donde se ejecuta y reporta los archivos que toca la regla, con --all para listar también los que pasan y --fresh para volver a evaluar cada regla en lugar de reutilizar un veredicto guardado. En otro proyecto el barrido le toca a tu asistente: apúntalo al área que cubre la regla y pídele que revise cada archivo, como se describe en Analizar un archivo.
9. Cambiar una regla que ya existe
El mismo camino y en el mismo orden: edita el inglés, importa, traduce, verifica. La huella marca la traducción como desfasada en cuanto se mueve el inglés, así que nada depende de que te acuerdes de cuáles reglas tocaste.
Una regla que se dispara con código correcto, o que se queda callada con código que debería atrapar, es un defecto de la regla y no algo que cada proyecto tenga que rodear. Arréglala en la fuente y cada proyecto recibe la regla corregida en su siguiente llamada.