wastech-mdlint
Deterministyczne lintowanie Markdownu, który czytają twoi agenci.
wastech-mdlint to CLI i biblioteka w TypeScripcie, które sprawdzają kontekst w Markdownie w twoim repozytorium, od AGENTS.md i CLAUDE.md po całe drzewo dokumentacji. Każda kontrola działa lokalnie, bez zapytań sieciowych i bez modelu w pętli, więc te same pliki zawsze dają ten sam wynik.
Dlaczego tu jest
Dobra praca agentów zależy między innymi od porządku w plikach, które czytają, i właśnie do tego napisałem to narzędzie. Działa lokalnie i w CI, a używam go we własnych produktach, między innymi w Wastime i na tej stronie. Działającą konfigurację można zobaczyć w publicznym repozytorium wastech-orchestrator.
Problem
Pliki, które czytają twoi agenci, zmieniają się razem z kodem i jeśli nic ich nie sprawdza, linki przestają działać po przeniesieniu pliku, a pliki kontekstu rosną ponad rozmiar, który model dobrze czyta. Żaden test wtedy nie pada, więc pierwszym sygnałem może być to, że agent pracuje gorzej, a łatwo zrzucić to na model.
Rozwiązanie
wastech-mdlint traktuje Markdown dla agentów jak kod źródłowy. Ma 22 wbudowane reguły, od celów linków po wymagane kolumny tabel, oraz reguły budżetu, które ograniczają rozmiar kontekstu. Własne reguły zapisuje się jako konfigurację z zamkniętego zestawu asercji, więc w twoim CI nie uruchamia się żaden dowolny kod.
- Gdy konfiguracja włącza reguły, zepsute linki wewnętrzne i rozjechane tabele oblewają kontrolę w CI albo przy lokalnym uruchomieniu.
- Budżet tokenów na kontekst staje się limitem, który CI może sprawdzić.
- Własne reguły to zwykłe dane, więc uruchomienie ich w cudzym CI nie wykonuje żadnego kodu.
Najważniejsze funkcje
- 22 wbudowane regułyKategorie dla tabel, sekcji i struktury, odwołań, jakości treści i spójności grafu.
- Higiena kontekstu dla LLMBudżety bajtów, linii i tokenów oraz budżet importów eager dla plików kontekstu.
- Deklaratywne własne regułyZamknięty słownik asercji składanych w konfiguracji – bez przebudowy i bez wykonywania kodu w twoim CI.
Przykładowe uruchomienia
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.mdDla kogo
- Zespoły, które utrzymują dużo dokumentacji i kontekstu dla agentów.
- Każdy, kto trzyma CLAUDE.md / AGENTS.md / SKILL.md w repozytorium.
Technologie
- Język
- TypeScript
- Środowisko uruchomieniowe
- Node.js 24 LTS
- Struktura
- Monorepo na npm workspaces
- TypeScript project references
- Integracja z AI
- Model Context Protocol (stdio)
Instalacja
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Ograniczenia
- Zewnętrzne linki HTTP nie są sprawdzane, dzięki czemu każde uruchomienie pozostaje lokalne i deterministyczne.
- Własne reguły to wyłącznie dane, bez konfiguracji w TypeScripcie czy JavaScripcie i bez wtyczek z kodem użytkownika.
- Graf kontekstu jest budowany od nowa przy każdym uruchomieniu, na razie bez przyrostowej pamięci podręcznej.