wastech-mdlint
Linting determinista del Markdown que leen tus agentes.
wastech-mdlint es una CLI y una biblioteca en TypeScript que comprueban el contexto Markdown de tu repositorio, desde AGENTS.md y CLAUDE.md hasta el árbol de documentación. Cada comprobación se ejecuta en local, sin llamadas de red y sin ningún modelo de por medio, así que los mismos archivos siempre dan el mismo resultado.
Por qué está aquí
Para obtener buen trabajo de los agentes hace falta, entre otras cosas, mantener en orden los archivos que leen, y escribí esta herramienta para eso. Funciona en local y en CI, y la uso en mis propios productos, entre ellos Wastime y este sitio. Hay una configuración que funciona en el repositorio público de wastech-orchestrator.
Problema
Los archivos que leen tus agentes cambian junto con el código, y si nada los comprueba, los enlaces dejan de funcionar cuando se mueve un archivo y los archivos de contexto crecen más allá del tamaño que un modelo lee bien. Ningún test falla cuando eso ocurre, así que la primera señal puede ser un agente que trabaja peor, y es fácil atribuírselo al modelo.
Solución
wastech-mdlint trata el Markdown para agentes como código fuente. Incluye 22 reglas integradas, desde los destinos de los enlaces hasta las columnas obligatorias de las tablas, además de reglas de presupuesto que ponen un límite al tamaño del contexto. Las reglas propias se escriben como configuración a partir de un conjunto cerrado de aserciones, de modo que en tu CI no se ejecuta nada arbitrario.
- Cuando una configuración activa las reglas, los enlaces internos rotos y las tablas que se desajustan hacen fallar una comprobación en CI o en una ejecución local.
- Un presupuesto de tokens para el contexto se convierte en un límite que la CI puede comprobar.
- Las reglas propias son solo datos, así que usarlas en la CI de otra persona no ejecuta ningún código.
Funcionalidades principales
- 22 reglas integradasCategorías para tablas, secciones y estructura, referencias, calidad del contenido e integridad del grafo.
- Higiene del contexto para LLMPresupuestos en bytes, líneas y tokens, además de un presupuesto de imports eager para los archivos de contexto.
- Reglas propias declarativasUn vocabulario cerrado de aserciones que se combinan en la configuración, sin recompilar ni ejecutar código en tu CI.
Ejemplos de ejecución
wastech-mdlint lint .broken.md 3:11 error Link target "missing.md" does not resolve to a file. REF-001✖ 1 problem (1 error, 0 warnings)wastech-mdlint graph .nodes: 8edges: 7cycles: 1entry points (3): design.md index.md orphan.mdtop hubs: (none: no document has 3 or more incoming references)cycles: cycle-a.md -> cycle-b.md -> cycle-a.mdclusters: cluster 1 (5 files): design.md glossary.md guide.md index.md requirements.md cluster 2 (2 files): cycle-a.md cycle-b.md cluster 3 (1 files): orphan.mdreading order (6): design.md index.md glossary.md guide.md orphan.md requirements.mdall 2 documents below sit in a cycle.excluded from reading order (2): cycle-a.md cycle-b.mdcoverage: nodes: 8 edges: 7 files outside corpus (1): appendix.mdPara quién es
- Equipos que mantienen un gran volumen de documentación y de contexto para agentes.
- Cualquiera que tenga CLAUDE.md / AGENTS.md / SKILL.md en un repositorio.
Stack tecnológico
- Lenguaje
- TypeScript
- Entorno de ejecución
- Node.js 24 LTS
- Estructura
- Monorepo con npm workspaces
- TypeScript project references
- Integración con IA
- Model Context Protocol (stdio)
Instalación
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Limitaciones
- Los enlaces HTTP externos no se comprueban, lo que mantiene cada ejecución local y determinista.
- Las reglas propias son solo datos, sin configuraciones en TypeScript o JavaScript ni plugins con código de usuario.
- El grafo de contexto se reconstruye en cada ejecución, todavía sin caché incremental.