ADR 0112 — El gestor de reglas escribe en la config del proyecto

Estado: aceptado · Fecha: 2026-11-08

Enmienda el alcance del ADR 0111: el panel de control también edita ESLint y cualquier herramienta cuyo formato se pueda leer y escribir con seguridad. La fuente de verdad sigue siendo la config del proyecto.

Contexto

Oxlint ya se activa y se desactiva desde la ficha. Falta ESLint, cuya config es JavaScript ejecutable: no hay una línea que borrar cuando la regla viene de un preset. También falta poder añadir una regla que no esté en el catálogo, no solo activar las recomendadas. Y el informe de .codarch puede quedar viejo si la config cambia por fuera, porque el checksum del árbol de código no cambia.

Decisión

La config del proyecto manda. El escritor lee y escribe el fichero real; .codarch/ solo guarda el informe de la última ejecución, nunca reglas activas ni preferencias.
Bloque gestionado en eslint.config.js. Las reglas que no se pueden quitar de una línea —porque vienen de un preset o de un spread— se escriben como overrides en un bloque con marcas estables:
```
// codarch:lint-rules:start
// Gestionado por CodArch. No editar a mano.
{ rules: { "no-console": "off" } }
// codarch:lint-rules:end
```
Si el bloque no existe, se inserta una vez en el array exportado con un AST; después solo se reescribe su contenido. Una regla explícita en la config del usuario se puede quitar o cambiar en su sitio; si no se encuentra con seguridad, se usa el bloque. Si el fichero no es analizable (funciones, valores calculados, sintaxis no soportada), se dice y no se toca.
Catálogo de reglas conocidas. Cada adaptador puede listar sus reglas para el menú de añadir:
- ESLint: las del núcleo y las de los plugins que resuelve la config del proyecto.
- Oxlint: las del esquema de la versión instalada.
- Checkstyle: un catálogo curado de módulos con su contenedor (Checker o TreeWalker); un módulo desconocido se rechaza porque no se puede adivinar dónde cuelga.
- Si una herramienta no puede enumerarlas, el menú solo ofrece las activas y las recomendadas y lo dice; no se inventa un catálogo.
La UI es un gestor. Las activas se quitan; las recomendadas y las del catálogo se añaden. El menú de añadir es buscable y agrupa por plugin; al añadir se elige la severidad (error o warn, por defecto error). Cada cambio se previsualiza sin tocar el disco y se confirma con fichero y diff; después se vuelve a lintar. La última escritura de cada config se puede deshacer desde el aviso: ese estado vive en memoria del servidor y nunca en .codarch/.

Las recomendadas parten de la base de la herramienta y añaden reglas por señales seguras del proyecto (React, TypeScript, pruebas). Si el catálogo real está disponible, las reglas extra se filtran contra él; no se recomienda una regla que la config no pueda resolver.
El informe no diverge. El artefacto gana una huella opcional de la config del lint (meta.config) dentro del contrato 1.3; un lector anterior la ignora y un artefacto sin ella se lee igual. Un cambio en un fichero de config fuerza una re-medida aunque el checksum del código no cambie, y al arrancar el live la primera pasada también es forzada. La huella sirve para auditar qué config produjo la foto, no para decidir qué reglas están activas.
Una herramienta, un escritor. El contrato LintRuleWriter recibe el sistema, la regla y la severidad, y devuelve la ruta y el diff. Oxlint JSON ya lo cumple; ESLint AST es el siguiente; Biome, Ruff y Checkstyle llegarán con su formato.

Consecuencias

Añadir una regla de ESLint será elegirla del menú, ver el cambio y aceptarlo; el npm run lint del proyecto ve exactamente lo mismo.
El bloque gestionado es visible y versionado: no hay una config oculta en .codarch/.
El informe se actualiza al cambiar la config; deja de ser una foto que puede envejecer en silencio.
Un eslint.config.js raro no se rompe: se rechaza la escritura con un motivo.

Alternativas descartadas

Guardar las reglas en .codarch/. Sería una segunda fuente de verdad y CI no las vería.
Un fichero aparte importado por la config. Añade una indirección que el usuario no pidió; el bloque gestionado se lee en el mismo sitio.
Buscar y reemplazar texto. Rompe configs con presets, spreads y overrides.
Enseñar solo las recomendadas. El usuario necesita añadir cualquier regla conocida.

Hoja de ruta

Sin fase nueva.

✅ La decisión: bloque gestionado y catálogo buscable.
✅ El escritor de ESLint con bloque gestionado y retirada de reglas explícitas.
✅ El catálogo de reglas por herramienta (ESLint núcleo y plugins; oxlint).
✅ El menú de añadir con búsqueda, severidad y confirmación.
✅ Re-medida al cambiar la config del lint.
✅ meta.config como huella opcional dentro de 1.3.
✅ El escritor de Biome en JSON.
✅ El escritor de Ruff en TOML, con ruff rule para el catálogo.
✅ Checkstyle: quitar módulos del XML y activar los de su catálogo curado en su contenedor.
✅ Previsualizar el cambio sin escribir, con diff, y deshacer la última escritura.
✅ Recomendaciones por señales del proyecto, filtradas contra el catálogo real.
✅ Ampliar el catálogo curado de Checkstyle; los módulos desconocidos siguen rechazándose.

El registro de lo hecho vive en el feed de la guía.