wastech-mdlint
Linting déterministe du Markdown que lisent vos agents.
wastech-mdlint est une CLI et une bibliothèque TypeScript qui vérifient le contexte Markdown de votre dépôt, d’AGENTS.md et CLAUDE.md jusqu’à l’arborescence de la documentation. Chaque vérification s’exécute en local, sans appel réseau et sans modèle dans la boucle, et les mêmes fichiers donnent donc toujours le même résultat.
Pourquoi ce projet est ici
Pour obtenir du bon travail des agents, il faut notamment tenir en ordre les fichiers qu’ils lisent, et j’ai écrit cet outil pour cela. Il fonctionne en local et en CI, et je l’utilise dans mes propres produits, dont Wastime et ce site. Une configuration qui fonctionne se trouve dans le dépôt public de wastech-orchestrator.
Problème
Les fichiers que lisent vos agents changent avec le code, et si rien ne les vérifie, des liens cessent de fonctionner après le déplacement d’un fichier et les fichiers de contexte dépassent la taille qu’un modèle lit bien. Aucun test n’échoue quand cela arrive. Le premier signe peut alors être un agent qui travaille moins bien, et il est facile de l’attribuer au modèle.
Solution
wastech-mdlint traite le Markdown destiné aux agents comme du code source. Il fournit 22 règles intégrées, des cibles de liens aux colonnes obligatoires des tableaux, ainsi que des règles de budget qui plafonnent la taille du contexte. Les règles personnalisées s’écrivent en configuration à partir d’un ensemble fermé d’assertions, si bien que rien d’arbitraire ne s’exécute dans votre CI.
- Une fois les règles activées dans une configuration, les liens internes cassés et les tableaux qui dérivent font échouer une vérification en CI ou en local.
- Un budget de tokens pour le contexte devient une limite que la CI peut vérifier.
- Les règles personnalisées ne sont que des données, et les lancer dans la CI de quelqu’un d’autre n’exécute aucun code.
Fonctionnalités clés
- 22 règles intégréesDes catégories pour les tableaux, les sections et la structure, les références, la qualité du contenu et l’intégrité du graphe.
- Hygiène du contexte pour les LLMDes budgets en octets, en lignes et en tokens, plus un budget d’imports eager pour les fichiers de contexte.
- Règles personnalisées déclarativesUn vocabulaire fermé d’assertions combinées dans la configuration, sans recompilation ni exécution de code dans votre CI.
Exemples d’exécution
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.mdPour qui
- Les équipes qui maintiennent un grand volume de documentation et de contexte destiné aux agents.
- Toute personne qui garde CLAUDE.md / AGENTS.md / SKILL.md dans un dépôt.
Stack technique
- Langage
- TypeScript
- Environnement d’exécution
- Node.js 24 LTS
- Structure
- Monorepo avec npm workspaces
- TypeScript project references
- Intégration IA
- Model Context Protocol (stdio)
Installation
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Limites
- Les liens HTTP externes ne sont pas vérifiés, ce qui garde chaque exécution locale et déterministe.
- Les règles personnalisées sont uniquement des données, sans configuration en TypeScript ou JavaScript ni plugins de code utilisateur.
- Le graphe de contexte est reconstruit à chaque exécution, sans cache incrémental pour l’instant.