From 5e77619d37cd08dd6efe9d3ca972393ec20f1db8 Mon Sep 17 00:00:00 2001 From: Jorge Date: Tue, 5 May 2026 12:42:58 +0200 Subject: [PATCH] =?UTF-8?q?feat(commands):=20a=C3=B1adir=20/md-lint=20y=20?= =?UTF-8?q?aplicarlo=20a=20docs=20existentes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Crea el slash command `/md-lint` para barrer cualquier `.md` del repo contra un set mínimo de reglas (MD004, MD030, MD031, MD032, MD036, MD040, MD026, MD047, MD034) sin añadir markdownlint-cli2 como devDep. Aplica el primer pase: 7 fences sin lenguaje declarado pasan a `text` en check.md, md-lint.md, SKILL.md, EVENTS-RABBITMQ.md y HOUSE-STYLE.md. Co-Authored-By: Claude Opus 4.7 --- .../skills/sf-backend-architecture/SKILL.md | 4 +- .../references/EVENTS-RABBITMQ.md | 2 +- .../references/HOUSE-STYLE.md | 2 +- .claude/commands/check.md | 4 +- .claude/commands/md-lint.md | 73 +++++++++++++++++++ 5 files changed, 79 insertions(+), 6 deletions(-) create mode 100644 .claude/commands/md-lint.md diff --git a/.agents/skills/sf-backend-architecture/SKILL.md b/.agents/skills/sf-backend-architecture/SKILL.md index 93376a9..4456c6d 100644 --- a/.agents/skills/sf-backend-architecture/SKILL.md +++ b/.agents/skills/sf-backend-architecture/SKILL.md @@ -100,7 +100,7 @@ async activate(args: { iccid: string }): Promise { ## La regla central: dependencias hacia dentro -``` +```text infrastructure → aplication → domain (adapters) (use cases) (núcleo) ``` @@ -236,7 +236,7 @@ Lista de cambios concretos, en orden de prioridad. Cada acción referencia archi ### ¿Dónde va este código? -``` +```text ¿Qué es? ├─ Lógica de negocio pura, sin I/O → domain/ ├─ Orquesta dominio + tiene side effects → aplication/ (usecase) diff --git a/.agents/skills/sf-backend-architecture/references/EVENTS-RABBITMQ.md b/.agents/skills/sf-backend-architecture/references/EVENTS-RABBITMQ.md index 95da2a1..08d627d 100644 --- a/.agents/skills/sf-backend-architecture/references/EVENTS-RABBITMQ.md +++ b/.agents/skills/sf-backend-architecture/references/EVENTS-RABBITMQ.md @@ -76,7 +76,7 @@ Ejemplos válidos: `sim.alai.activate`, `sim.nos.cancel`, `sim.objenious.pause`. ## Topología de RabbitMQ -``` +```text ┌─────────────────┐ │ sim.exchange │ ← topic, exchange principal (DURABLE) │ (publish) │ diff --git a/.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md b/.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md index 68b1d37..68202de 100644 --- a/.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md +++ b/.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md @@ -20,7 +20,7 @@ Si algo no aparece en ninguno de los dos, asume las defaults razonables de Hexag ## Estructura de carpetas -``` +```text packages/ ├── _template/ # Plantilla para crear servicios nuevos ├── sim-shared/ # Tipos, ports, adapters compartidos diff --git a/.claude/commands/check.md b/.claude/commands/check.md index c7b96e2..5e3e3db 100644 --- a/.claude/commands/check.md +++ b/.claude/commands/check.md @@ -36,7 +36,7 @@ Ejecuta los comandos en paralelo cuando sean independientes; reporta los resulta Resumen breve, por comprobación: -``` +```text typecheck: 47 errores (estado del repo, no necesariamente de tu cambio) lint: 132 errores, 89 warnings (idem) format: 3 ficheros con formato incorrecto @@ -45,7 +45,7 @@ tests: ✅ 24/24 passing Si has hecho cambios en esta sesión y puedes correlacionar errores con esos cambios, sepáralos: -``` +```text typecheck: - 1 error nuevo en packages/sim-shared/domain/Order.ts:42 (introducido por este cambio) - 46 errores preexistentes (sin cambios) diff --git a/.claude/commands/md-lint.md b/.claude/commands/md-lint.md new file mode 100644 index 0000000..436bd1b --- /dev/null +++ b/.claude/commands/md-lint.md @@ -0,0 +1,73 @@ +--- +description: Revisa y corrige avisos comunes de markdownlint en ficheros .md del repo (raíz, .claude, .agents, packages...). No hay devDep ni CI; el repaso es manual y se invoca a demanda. +--- + +# /md-lint — limpieza de markdown + +Aplica un repaso de estilo a los `.md` del repo según las reglas que más se cuelan en este proyecto. No hay `markdownlint-cli2` instalado y no se quiere añadir como devDep — el barrido es manual contra el set de reglas de abajo. + +## Argumento + +`$ARGUMENTS` opcional. Si está, acota el barrido a esa ruta (fichero concreto, carpeta, glob). Si no, barre todo el repo excluyendo: + +- `node_modules/` +- `dist/` +- `.git/` +- `coverage/` + +Para listar candidatos: + +```bash +find . -name "*.md" -not -path "./node_modules/*" -not -path "./dist/*" -not -path "./.git/*" -not -path "*/coverage/*" +``` + +## Reglas que se revisan + +Set mínimo, alineado con lo que el editor del usuario marca y con el estilo ya presente en `README.md` y `CLAUDE.md`: + +- **MD004 — list-style:** listas con `-`, no con `*`. +- **MD030 — list-marker-space:** un único espacio tras `-` o `1.` (no `* ` ni `1. `). +- **MD032 — blanks-around-lists:** una línea en blanco antes y después de cada lista. +- **MD031 — blanks-around-fences:** una línea en blanco antes y después de cada bloque ` ``` `. +- **MD036 — no-emphasis-as-heading:** `**Sección:**` en línea propia → heading real (`####`). Si la línea es la firma del documento o contenido decorativo (no es un encabezado lógico), convertir a texto plano en vez de inventar un heading. +- **MD040 — fenced-code-language:** todo bloque ` ``` ` debe declarar lenguaje (`text`, `bash`, `ts`, `json`...). +- **MD026 — no-trailing-punctuation-in-heading:** headings sin `:` ni `.` al final. +- **MD047 — single-trailing-newline:** el fichero termina con un único `\n` final. +- **MD034 — no-bare-urls:** URLs en texto deben ir en `<...>` o como link `[texto](url)`. + +No se tocan: + +- Contenido (typos, gramática, redacción) — solo formato. Excepción: si encuentras un typo obvio en un encabezado o una frase muy corta, repórtalo al final pero no lo arregles sin permiso. +- Longitud de línea (MD013): el repo no la fuerza. +- Estilo de heading ATX vs Setext: ya está unificado en ATX (`#`). + +## Cómo proceder + +1. Resuelve la lista de ficheros (`$ARGUMENTS` o barrido completo). +2. Si son más de ~5 ficheros, despacha el trabajo a subagentes en paralelo agrupando por carpeta (ver skill `dispatching-parallel-agents`). Cada subagente recibe un grupo y este mismo set de reglas. +3. Para cada fichero, lee y aplica las reglas con `Edit`. No reescribas el fichero entero con `Write` salvo que el delta sea masivo. +4. No introduzcas cambios fuera del set de reglas. No reordenes secciones, no añadas contenido. + +## Formato de reporte + +Tabla resumen al terminar: + +```text +fichero cambios +----------------------------- ------- +CONTRIBUTING.md 12 (MD004, MD030, MD036, typo) +.claude/rules/code-style.md 0 +.agents/skills/.../HOUSE.md 3 (MD031, MD040) +``` + +Si encontraste typos o problemas de contenido que no arreglaste (por estar fuera de scope), lístalos en una sección **Sugerencias** al final para que el usuario decida. + +## Cuándo invocarlo + +Es opcional, no hay CI que lo ejecute. Casos típicos: + +- Tras editar varios `.md` seguidos y que el editor empiece a marcar avisos. +- Antes de un PR que toca documentación. +- Limpieza periódica si el repo arrastra inconsistencias. + +No lo invoques de oficio.