Linting-Stack für Node-Projekte: Code-Qualität, Formatierung und Prosa-Linting

Nicht nur Code bestimmt die Softwarequalität, sondern auch die Art, wie Softwareentwicklerinnen und -entwickler ihn dokumentieren und präsentieren. In einer Zeit, in der viele Entwicklerteams vollständig remote arbeiten und die Codebase weiter kontinuierlich wächst, ist die konsistente und automatisierte Qualitätskontrolle eine Notwendigkeit.

Während meiner Arbeit an einem node-basierten Dokumentationsstack mit dem Static-Site-Generator Astro und Starlight, einem darauf aufbauenden Framework speziell für Dokumentationswebsites, bin ich auf die Herausforderung gestoßen, nicht nur sauberen Code, sondern auch hochwertige Prosa zu produzieren. Prosa kommt aus dem Lateinischen und bedeutet „geradeheraus reden“ – also ohne Schnörkel normal sprechen.

Im Rahmen einer Dokumentation bezeichnet Prosa den gesamten ausformulierten Textinhalt der technischen Dokumentation – alle Erklärungen, Anleitungen, Beschreibungen und Kommentare. Ziel ist es, dass Stil-Konsistenz, Grammatik, Wortwahl, Lesbarkeit und die Einhaltung von Dokumentationsrichtlinien sichergestellt sind und die technische Dokumentation nicht nur funktional korrekt, sondern auch verständlich, einheitlich und professionell geschrieben ist.

Die Lösung: Ein mehrstufiges Linting-System, das Code-Qualität, Formatierung und Prosa-Linting für englischsprachige Dokumentation geschickt miteinander verbindet und sich durch Git Pre-Commit Hooks sowie CI/CD-Pipelines automatisieren lässt. Prosa Linting für deutsche Texte ist nicht nativ integriert, lässt sich aber durch eigene Regeln integrieren. Hierbei kann die KI bei der Erstellung der Regeln gute Dienste tun. Eine gute Hilfestellung bietet hier auch der webbasierte Regelgenerator valegen.

Bevor es an die detaillierte Umsetzung des dreistufigen Linting-Konzepts geht, ist eine praktische Arbeitsumgebung einzurichten. Als grundlegendes Code- und Dokumentations-Beispiel dient Astrogon – ein vielseitiges Astro-Theme, das sich ideal für die Demonstration des Linting-Systems eignet. Astrogon ist ein schnell anpassbares, Mehrzweck-Website-Template, das auf Astro JS, Tailwind CSS und React basiert. So bildet es eine solide Grundlage für verschiedene Website-Typen – von Blogs über Dokumentationsseiten bis hin zu Portfolio-Websites.

Durch einen Fork des originalen Astrogon Repository, den man lokal klont, lässt sich das Projekt einfach aufsetzen.

Nach der Installation steht eine vollständig funktionsfähige Website mit folgender Struktur parat:

Modernes Linting geht weit über die reine Syntaxprüfung hinaus und umfasst drei komplementäre Dimensionen der Qualitätskontrolle: Code-Qualität für die Logik, Formatierung für die Konsistenz und Prosa-Linting für die menschliche Lesbarkeit. Für diese drei Aspekte kommen verschiedene Linter zum Einsatz: ESLint für die Code-Qualität, Prettier für die Formatierung und Vale für das Prosa-Linting.

Code-Qualität mit ESLint: ESLint bildet das Fundament des Linting-Stacks. Es analysiert TypeScript-, JavaScript- und Astro-Dateien auf potenzielle Fehler, Style-Inkonsistenzen und Best-Practice-Verletzungen. Die Installation leitet der folgende Befehl ein:

npm install -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser astro-eslint-parser eslint-plugin-astro

Im nächsten Schritt folgt das Anlegen der Datei .eslintrc.js, die die Konfiguration für die verschiedenen Dateitypen definiert. Dies gelingt am einfachsten über den offiziellen Konfigurations-Wizard von ESLint:

Anschließend sind die aufrufenden npm-Skripte in der Datei package.json zu hinterlegen.

Der Befehl npm run lint korrigiert dann automatisch behebbare Probleme, während npm run lint:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Code-Formatierung mit Prettier: Prettier sorgt für einheitliche Code-Formatierung und nimmt Entwicklern die Diskussion über Code-Style ab. Besonders in Astro-Projekten mit gemischten Dateitypen ist eine konsistente Formatierung essenziell. Prettier lässt sich mit folgendem Befehl installieren:

Die Konfiguration von .prettierrc\ im Root-Verzeichnis des Repository berücksichtigt die spezifischen Anforderungen von Astro-Projekten:

Sind die Abhängigkeiten installiert und die Konfiguration angelegt, werden die entsprechenden npm-Skripte in der Datei package.json eingefügt:

Der Befehl npm run format korrigiert anschließend automatisch behebbare Probleme, während npm run format:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Prosa-Linting mit Vale: Vale ist ein Open-Source-Tool für das Prosa-Linting, das wie ein Code-Linter funktioniert, aber Fließtext verarbeitet. Es prüft Texte auf stilistische Fehler, wiederkehrende Muster und Verstöße gegen vordefinierte oder eigene Stilrichtlinien. Es funktioniert mit Markdown, HTML, AsciiDoc oder reStructuredText und analysiert diese Formate anhand konfigurierter Regeln. Die Style-Guides, anhand derer Vale überprüft, können frei gewählt, angepasst oder erweitert werden – beispielsweise nach Vorbildern von Google, Microsoft oder eigenen Anforderungen.

Typische Regeln erkennen etwa unnötige Passiv-Konstruktionen, zu viele Wiederholungen, fehlende Oxford-Kommas – also das Komma vor der Konjunktion in einer Aufzählung, das helfen soll, Missverständnisse zu vermeiden – oder „Weak Words“ wie „viele“ oder „manchmal“. Die Ergebnisse zeigt Vale direkt im Editor, in der Kommandozeile oder als Teil automatisierter CI-Prozesse.

Vale erfordert eine plattformspezifische Installation sowie den Download der Style-Guides und LibreOffice-kompatibler Hunspell-Wörterbücher (.dic/.aff-Dateien) für die Rechtschreibprüfung in anderen Sprachen als Englisch. Ja, die Kombination von Prosa-Linting-Style-Guides (wie Vale, Google oder Microsoft Style Guides) mit einem deutschen Wörterbuch ist durchaus sinnvoll und funktioniert einwandfrei – Vale nutzt Hunspell-Dictionaries unabhängig voneinander für Rechtschreibung und Stilregeln. Rechtschreibprüfung prüft Wörter auf Korrektheit, während Prosa-Linting Stil, Lesbarkeit und Konventionen überwacht; beide ergänzen sich nahtlos in einem Workflow. Für das beispielhafte Repository habe ich entsprechende Linux/macOS- und Windows-Skripte angelegt, die das Setup erledigen. Getestet ist aktuell nur das Bash-Skript, das PowerShell-Skript wurde via KI automatisiert auf Basis des Bash-Skripts erstellt.

Abweichend von der standardmäßigen Vorgehensweise, bei der Probleme mit dem in Vale integrierten Installer vale sync auftraten, laden die Skripte die git-Repositories für die Styleguides manuell herunter und löschen alle git-spezifischen Inhalte.

Nach Ausführen der Skripte entsteht folgendes Verzeichnis im Root-Verzeichnis des Repositories:

Zu beachten ist dabei noch, alle dynamisch generierten Inhalte in die .gitignore-Datei aufzunehmen.

Das Installationsskript lädt nicht nur Vale herunter, sondern auch die benötigten Styleguides. Auf der Vale-Website sind, neben einigen weiteren spezifischen, vier wesentliche Style-Guides referenziert:

Im Folgenden kommt der „Microsoft Style Guide“ zum Einsatz – erweitert um die Style-Guides „write-good“, „MDX“ und „Vale Core“. Diese sind wie folgt charakterisiert:

Beim Einsatz unterschiedlicher Style-Guides in Kombination lässt sich in manchen Situationen schwer identifizieren, warum welche Regel benötigt wird. Ein Beispiel macht dies klarer. Gegeben ist folgende MDX-Datei:

Die Vale-Konfigurationsdatei gibt an, in welchen Verzeichnissen und mit welchen Style-Vorgaben das Tool den Text überprüfen soll. Für das Beispiel sei angenommen, dass sich der englische Content in den Unterverzeichnissen des Ordners /src/content befindet.

Nun sind noch die richtigen Cross-Platform npm-Skripte für Vale bereitzustellen, um den Linter zu installieren und aufzurufen.

Ausnahmen für Sonderfälle sind eigens zu definieren, etwa für Situationen, in denen Vale eine Regel bewusst ignorieren soll. Beispielsweise würde die Regel write-good.So für den Satz „So the experiment failed because the measurements were taken incorrectly“ normalerweise den folgenden Fehler melden:

Um für diesen spezifischen Fall die Prüfung abzuschalten, ist die entsprechende Zeile mit einem Kommentar zu umfassen:

Zu beachten ist dabei, dass die beiden Kommentar-Tags und die betroffene Zeile durch einen Zeilenumbruch getrennt sein müssen. Da es sich zudem um MDX-Dateien handelt, müssen die Zeilen erst mit einem JSX-Kommentarblock umschlossen werden, damit der Server nicht meckert, und anschließend mit einem HTML-Kommentarblock, damit Vale diesen erkennt. Darüber hinaus benötigt Vale – mit folgenden beiden Zeilen in der vale.ini – einen Hinweis, dass MDX-Dateien letztlich auch als Markdown-Dateien zu behandeln sind:

Im Falle kompletter Textblöcke oder wenn der Grund der Deaktivierung der Vale-Regel benannt werden soll, ist es ebenfalls möglich, nur einzelne Regeln abzuschalten:

Linting-Stack für Node-Projekte: Code-Qualität, Formatierung und Prosa-Linting

Ein dreistufiger Linting-Ansatz mit ESLint, Prettier und Vale verbessert Qualität von Code und Dokumentation in Astro-Projekten durch automatisiertes Prüfen.