vibator/vibator

Configuración de vibator

Referencia: npx vibator docs configuration imprime el formato de configuración y npx vibator docs rules imprime cada regla con sus opciones y valores predeterminados. Esta habilidad es el flujo de trabajo; esos documentos son el contrato.

La configuración es una tarea de descubrimiento: la configuración correcta se determina por lo que el proyecto realmente contiene. Inspecciona primero, escribe segundo, ejecuta tercero.

Reglas básicas

• Nunca debilites una puerta para que pase. Desactivar una regla, ampliar su presupuesto o excluir un archivo porque actualmente falla oculta el problema en lugar de solucionarlo. Corrige el hallazgo, o deja la regla fallando y dilo. La única escapatoria por línea es // vibator-ignore: <razón>, y la razón es obligatoria.
• Configura solo lo que difiere de los valores predeterminados. Cada regla ya se ejecuta con su propia severidad predeterminada sin ninguna configuración. Una configuración que repite cada valor predeterminado entierra las líneas que importan.
• include y exclude reemplazan los valores predeterminados de una regla. No se fusionan. Copia los valores predeterminados que aún deseas antes de reducir.
• Nunca establezcas recommended: false para que una ejecución pase. Deshabilita todas las reglas que la configuración no nombra, incluso las que pasan. Existe para establecer una selección deliberada, y esa selección es decisión humana.
• Una configuración que el proyecto extiende no es tuya para editar. Un preset establece un estándar que comparten varios proyectos. Configura la diferencia localmente, o pide a un humano que cambie el preset. Nunca silencies un hallazgo editando un archivo bajo node_modules; la próxima instalación lo reemplaza de todas formas.

Pasos

1. Comienza desde un archivo válido. Si no existe vibator.json, ejecuta npx vibator init; escribe la línea $schema que da a los editores validación. Luego npx vibator list muestra cada regla y su valor predeterminado. Antes de escribir tus propias reglas, verifica si el proyecto ya extiende un preset, o si existe uno para extender (un paquete de estilo @scope/quality en package.json, o la misma configuración repetida en repositorios hermanos). Extenderlo es mejor que repetirlo; consulta "Construir sobre un preset compartido" a continuación.

2. Ejecuta una vez, sin configurar: npx vibator --reporter json. Esto muestra qué reglas pasan, cuáles fallan y cuáles fallaron por falta de opciones. Lee los recuentos antes que los diagnósticos; una regla con 400 hallazgos necesita una decisión, no 400 correcciones hoy (consulta el paso 6).

3. Descubre lo que necesitan las reglas desactivadas por defecto. Cada una está desactivada porque no puede actuar sin conocimiento del proyecto. Búscalo:

   • locale-parity: encuentra el directorio de idiomas (locales/, i18n/, public/locales/). Observa el diseño: un directorio por idioma (layout: "directory-per-locale") o un archivo por idioma ("file-per-locale"), y qué idioma es el origen.
   • codegen-drift: lee los scripts de package.json para generadores (db:generate, openapi, graphql-codegen) y encuentra las rutas que cada uno escribe. Configura una entrada por generador con name, command, paths.
   • banned-patterns: lee las convenciones de revisión del proyecto (CONTRIBUTING, documentos de estilo, comentarios de revisión recurrentes). Cada "nunca hagas X" con forma de patrón se convierte en una entrada con su propio message, expected y fix, escrito con tanto cuidado como una regla incorporada.
   • no-deprecated-apis: lista los tsconfigs; un monorepo quiere cada proyecto que deba verificarse en options.projects.

4. Conecta documentos existentes del proyecto con las reglas mediante guidelines. Si el repositorio tiene un AGENTS.md, CLAUDE.md o documento de estilo que indique un estándar que una regla aplica, mapealo: "guidelines": {"AGENTS.md": ["tsdoc-coverage"]}. Usa el campo docs por regla solo cuando el estándar del proyecto reemplaza la guía incluida en lugar de agregar contexto.

5. Usa la forma de array para estándares divididos. Una regla puede ejecutarse varias veces con diferentes globs y opciones:

   "max-file-size": [
     {"include": ["src/**"], "options": {"maxKb": 256}},
     {"include": ["assets/**"], "options": {"maxKb": 4096}}
   ]
   

6. Adopta incrementalmente en una base de código legacy con --changed, no debilitando. Verifica el trabajo nuevo inmediatamente (npx vibator --changed, o --since origin/main en CI para todo el diff del pull request) mientras la deuda técnica se reduce. Para reglas con muchos hallazgos, usa warn mientras tanto: los hallazgos siguen siendo visibles sin bloquear. No uses off para significar "más tarde".

7. Verifica el resultado. Ejecuta npx vibator y confirma: cada regla habilitada se ejecuta (una regla que falla es un error de configuración y su mensaje dice qué faltaba), los hallazgos restantes son reales, y npx vibator explain <rule> muestra la guía correcta para cualquier cosa que hayas anulado.

Construir sobre un preset compartido

extends toma una ruta que comienza con . o un especificador de paquete, resuelto contra el archivo que lo declara. Las entradas posteriores ganan sobre las anteriores, y la configuración del propio archivo gana sobre todas ellas.

{
  "extends": ["@acme/quality/vibator.json"],
  "rules": { "max-file-size": "warn" }
}

La fusión sigue a Biome, por lo que se comporta como esperan los usuarios de ese stack. Dos consecuencias a tener en cuenta:

• Una severidad simple mantiene todo lo demás. Escribir "max-file-size": "warn" sobre un preset que estableció maxKb e include cambia solo la severidad; el presupuesto y los globs se heredan. No necesitas repetirlos, y repetirlos es cómo un proyecto se desvía silenciosamente de su preset.
• Los arrays reemplazan, no concatenan. Para agregar una entrada a una lista allow o patterns heredada, escribe la lista completa que deseas. Esto es deliberado: hace posible eliminar una entrada heredada.

Escribe solo la diferencia. Una configuración que repite lo que el preset ya dice es indistinguible de una que discrepa de él, y la próxima actualización del preset no alcanzará los campos que copiaste.

Un preset construido como una selección curada establece "recommended": false y lista las reglas que desea. Bajo tal preset, las reglas no nombradas no se ejecutan, así que verifícalo antes de concluir que falta una regla.

Las rutas de guía se resuelven de la misma manera: las entradas docs y guidelines indicadas por un preset se resuelven contra el preset, por lo que los hallazgos apuntan a los documentos que vienen con él. Tus propias rutas aún se resuelven contra la raíz del proyecto.

Política de severidad

• error: reglas deterministas con casi cero falsos positivos.
• warn: reglas que pueden estar equivocadas sobre una base de código que no han visto (env-example-sync coincide con texto; prefer-array-methods no puede distinguir un array de un Set), y adopción provisional de reglas con una gran acumulación.
• off: solo para reglas que no aplican (sin idiomas significa sin locale-parity), nunca como una forma de pasar.

Errores comunes

• Escribir include y perder las exclusiones predeterminadas de la regla (pruebas, .d.ts).
• Repetir las opciones de un preset junto a una anulación de severidad, asumiendo que una severidad simple las descarta. No lo hace, y la copia deja de rastrear el preset.
• Habilitar codegen-drift con un generador que necesita servicios o secretos que el entorno no tiene. La regla ejecuta el comando de verdad.
• Mapear cada documento en cada regla en guidelines. Mapea solo documentos que realmente indican el estándar de esa regla.
• Editar la configuración para finalizar una ejecución fallida en lugar de corregir los hallazgos. Si un humano pidió la puerta, solo un humano decide bajarla.