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.

David König

David König ist seit über 20 Jahren in der IT aktiv. Viele Jahre hat ihn das Thema Workplace-Management und Infrastruktur als Berater beschäftigt, bevor er in die Entwicklung gegangen ist, um sich intensiv mit den Themen Produkt-Management und DevOps auseinanderzusetzen. Nachdem er den Schaffensprozess von Software von allen Seiten kennengelernt hat und neben der IT-Community auch in der Heim- und Handcommunity aktiv ist, versteht er die Entwicklung und den Betrieb von Software weniger als Wissenschaft, sondern als Handwerk. Dieser Gedanke treibt ihn und er versucht immer wieder, Parallelen zwischen Handwerk und Softwareentwicklung aufzuzeigen. Heute betreibt David Softwareentwicklung in der Automotive-Branche bei der adesso SE und zusammen mit vielen weiteren Kollegen IoT-Projekte und die pragmatische Vision der Softwareentwicklung als Handwerk vor allem im AI-Bereich.

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.

Test-Setup: Astrogon als Grundlage für das Linting-System

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.

Astrogon eignet sich deshalb als Demo-Basis, weil es:

1. Verschiedene Dateitypen enthält: .astro, .tsx, .js, .md, .mdx, .css
2. Realistische Komplexität bietet: ein echtes Projekt mit authentischen Herausforderungen
3. Einen modernen Stack verwendet: aktuelle Technologien, die typisch für moderne Webprojekte sind
4. Gut strukturiert ist: klare Ordnerstruktur für effektives Linting
5. Content-fokussiert arbeitet: viel Text-Content für Prosa-Linting

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

# Create a fork (via GitHub.com)

#  Clone repository
git clone https://github.com/YOURACCOUNTNAME/my-linting-project.git
cd my-linting-project

# Install dependencies
npm install

# Fix existing vulnerabilities
npm audit fix

# Start development server
npm run dev

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

my-linting-project/
├── docs/ # Documentation
├── public/ # Static public viewable resources
├── src/
│ ├── assets/ # Pictures, icons,...
│ ├── components/ # reusable components
│ ├── content/ # Markdown/MDX content collections
│ ├── lib/ # Utility functions
│ ├── pages/ # Astro-pages (Routing)
│ ├── styles/ # CSS/SCSS files
│ ├── types/ # TypeScript type-definitions
│ ├── content.config.ts # Content Collections configuration
│ └── env.d.ts # Environment variables types
├── .editorconfig # Editor-configuration
├── .prettierrc # Preconfigured prettier
├── .markdownlint.json # Preconfigured markdownlot
├── astro.config.mjs # Astro configuration
├── package.json # Dependencies and scripts
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript Configuration
└── wrangler.jsonc # Cloudflare workers configuration

Integration der Linter in den Stack

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:

npm init @eslint/config@latest

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
  },
  env: {
    node: true,
    browser: true,
    es2022: true,
  },
  rules: {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-empty-interface": "off",
  },
  overrides: [
    {
      files: ["*.astro"],
      extends: ["plugin:astro/recommended"],
      parser: "astro-eslint-parser",
      parserOptions: {
        parser: "@typescript-eslint/parser",
        extraFileExtensions: [".astro"],
      },
    },
  ],
};

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

{
  "scripts": {
    "lint": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro --fix",
    "lint:check": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro"
  }
}

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:

npm install -D prettier prettier-plugin-astro prettier-plugin-tailwindcss

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

{
  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "useTabs": false,
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": ["*.astro"],
      "options": {
        "parser": "astro"
      }
    },
    {
      "files": ["*.md", "*.mdx"],
      "options": {
        "printWidth": 100,
        "proseWrap": "always"
      }
    }
  ]
}

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

{
  "scripts": {
      ...
      ...
    "format": "prettier --write ./src --log-level silent",
    "format:check": "prettier --check ./src --log-level silent"
  }
}

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.

# Linux/macOS
chmod +x .vale/install-vale.sh
./.vale/install-vale.sh

# Windows
powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1

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

my-linting-project/
├── .vale/
  ├── dictionaries
  │    ├── de_DE.aff
  │    ├── de_DE.dic
  ├── styles
       ├── Base
       │    ├── accept.txt
	   │    ├── reject.txt
       │    ├── Microsoft/
       │    ├── write-good/ 
  ├── install-vale.ps1
  ├── install-vale.sh
  └── vale

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

# Vale binary (install with npm run install-vale)
.vale/dictionaries
.vale/styles/Microsoft
.vale/styles/write-good
.vale/vale
.vale/vale.exe

Vale-Styleguides auswählen und installieren

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:

Google

• Starker Fokus auf technische Konsistenz und Präzision für Entwickler.
• Große Ausnahmeliste für Akronyme und Begriffe aus APIs.
• Substitutionslisten mit Google-typischer Terminologie.
• Stil: direkt, technisch, an Entwickler gerichtet, prägnant, präzise.
• Quelle Git, Quelle Style-Guide

Microsoft

• Sehr starke Gewichtung auf Inklusivität und Barrierefreiheit.
• Klare Satzlängen- und Limits für Wörter.
• Hunderte produkt- und communityspezifische Begriffe.
• Stil: freundlich, inklusiv, leserorientiert, markengerecht, barrierefrei.
• Quelle Git, Quelle Style-Guide

Red Hat

• Strikte Regeln zu „Open Source“-neutraler Sprache und Kollaboration.
• Erlaubt keinen Produkt-Bias, eigene Accessibility- und Bias-Listen.
• Regeln für CLI-Beispiele, Dateipfade und produktneutrale Formulierungen.
• Bevorzugt kollaborativen Duktus und Community-Perspektive.
• Stil: offen, kollaborativ, communitygetrieben, produktneutral, inklusiv.
• Quelle Git, Quelle Style-Guide

Write-good

• Fokussiert sich rein auf sprachliche Klarheit und verbessert Lesbarkeit und Stil, ohne produkt- oder technikspezifische Prüfkriterien.
• In modernen Dokumentations-Workflows eignen sich Write-Good-Regeln ergänzend, um die sprachliche Qualität unabhängig von der Plattform zu verbessern.
• Write-Good Vale Style-Guide

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:

Microsoft Style Guide: Unternehmensstandards für technische Dokumentation

write-good: allgemeine Regeln für klares Schreiben

Vale Core: grundlegende Prosa-Regeln

MDX: Prüfung der Sprache innerhalb von JSX Tags

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:

---
title: "Using Feature Y"
author: "Adesso"
---

# Feature Y Benefits

You will be able to use this feature very effectively. It was developed by adeso and their team.

<MyWarn type="warning">
  DO NOT use this feature if your environment isn't set correctly.
</MyWarn>

Step 1: Initializing the data source
Step 2 Call the performOperation() function
Step 3: Confirm the output's accuracy

> Note: The process can be slow. It is important that you wait patiently.

For details, check our doc [documentation](htp://example.com/feature-y).

Die Ergebnisse des Lintings fasst die folgende Tabelle zusammen:

Die korrigierte MDX-Datei sieht nach der Regelprüfung dann wie folgt aus:

---
title: "Using Feature Y"
author: "adesso"
---

# Feature Y Benefits

You can use this feature effectively, adesso and their team developed it.

<MyAlert type="warning">
  Do not use this feature if your environment is not set correctly.
</MyAlert>

- Step 1: Initialize the data source
- Step 2: Call the performOperation() function
- Step 3: Confirm the output's accuracy

> Note: The process can be slow. Please wait patiently.

For details, check our [documentation](http://example.com/feature-y).

Mithin ergeben sich folgende Einschränkungen:

• Die Vale-Style-Guides sind nur für englischen Text optimiert, eine Anpassung an Deutsch oder andere Sprachen scheint bisher nicht vorgesehen zu sein.
• Die Style-Guides basieren auf klassischen Regular Expressions. Wer KI-basierte Ansätze erwartet, wird enttäuscht.
• Speziell in größeren Projekten empfiehlt es sich einen eigenen Style-Guide aufzubauen. Die Konfiguration von Vale erfordert eine kontinuierliche Anpassung an die Bedürfnisse des Projekts.

Konfigurieren und Anpassen von Vale (.vale.ini)

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.

# Vale configuration file
# See: https://vale.sh/docs/topics/config/
Packages = MDX

StylesPath = .vale/styles
# Add dictionary path for German dictionaries
DictionaryPath = .vale/dictionaries

MinAlertLevel = error

# File type associations - English content (excluding German docs)
[src/content/**]{.md,.mdx}

# Enable/disable specific styles for English content
BasedOnStyles = Vale, write-good, Microsoft

# Enable rules
Vale.Terms = YES  # Disables term-based checks. Example: Avoid using "jargon".
Vale.Spelling = YES  # Disables spelling checks. Example: "recieve" instead of "receive".
Vale.Vocab = YES  # Disables vocabulary checks. Example: Using "utilize" instead of "use".
Vale.Repetition = YES  # Disables repetition checks. Example: "very very good".
Vale.Wordiness = YES  # Disables wordiness checks. Example: "in order to" instead of "to".

# Write-good rules (English-specific)
write-good.Weasel = YES  # Disables detection of weasel words. Example: "some people say".
write-good.TooWordy = YES  # Disables detection of overly wordy phrases. Example: "due to the fact that".
write-good.So = YES  # Disables detection of sentences starting with "so". Example: "So, we decided to...".
write-good.ThereIs = YES  # Disables detection of "there is/are" constructions. Example: "There is a need for...".
write-good.Passive = YES  # Disables detection of passive voice. Example: "The ball was thrown by John".
write-good.Adverbs = YES  # Disables detection of adverbs. Example: "He ran quickly".
write-good.Cliches = YES  # Disables detection of cliches. Example: "Think outside the box".
write-good.E-Prime = YES  # Disables detection of E-Prime violations. Example: "He is a teacher".
write-good.Illusions = YES  # Disables detection of ambiguous phrases. Example: "The results were significant".

# Microsoft style rules (English-specific)
Microsoft.Gender = YES  # Ensures gender-neutral language is used. Example: Use "they" instead of "he/she".
Microsoft.PassiveVoice = YES  # Flags sentences written in passive voice. Example: "The report was written by Sarah".
Microsoft.Cliches = YES  # Detects overused phrases and cliches. Example: "At the end of the day".
Microsoft.Jargon = YES  # Highlights technical jargon that may confuse readers. Example: "Leverage synergies".
Microsoft.Complexity = YES  # Identifies sentences that are overly complex or difficult to read. Example: "The implementation of the solution was carried out in a manner that ensured...".
Microsoft.Redundancy = YES  # Flags redundant phrases or words. Example: "Free gift".
Microsoft.Spelling = YES  # Checks for spelling errors based on Microsoft's style guide. Example: "color" vs. "colour".
Microsoft.Spacing = YES  # Disables because of D2 diagrams - Allows ignoring spacing-related issues. Example: "word  word".
Microsoft.Contracting = YES  # Allows ignoring contracting-related issues. Example: "isn't" vs. "is not".
Microsoft.Quotes = YES  # Allows ignoring quotes-related issues. Example: "'single quotes' vs. "double quotes".
Microsoft.Contractions = YES  # Allows ignoring contractions-related issues. Example: "can't" vs. "cannot".
Microsoft.Foreign = YES  # Allows ignoring foreign phrases and words. Example: "et cetera".
Microsoft.Plurals = YES  # Allows ignoring pluralization-related issues. Example: "criterias" vs. "criteria".
Microsoft.Auto = YES  # Disables automatic suggestions for corrections. Example: "autocorrect".
Microsoft.AMPM = YES  # Allows ignoring AM/PM formatting issues. Example: "2 PM" vs. "14:00".
Microsoft.DateOrder = YES  # Allows ignoring date order-related issues. Example: "MM/DD/YYYY" vs. "DD/MM/YYYY".
Microsoft.Dashes = YES  # Allows ignoring dash-related issues. Example: "em-dash" vs. "en-dash".
Microsoft.DateFormat = YES  # Allows ignoring date format-related issues. Example: "2025-10-01" vs. "01/10/2025".
Microsoft.Units = YES  # Allows ignoring unit-related issues. Example: "5kg" vs. "5 kg".
Microsoft.Avoid = YES  # Allows ignoring "avoid" suggestions. Example: "Avoid using passive voice".
Microsoft.Negative = YES  # Allows ignoring negative phrasing suggestions. Example: "Not bad" vs. "Good".

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

{
  "scripts": {
	  ...
	  ...
    "postinstall": "npm run install-vale",
	"install-vale": "node -e \"const cmd = process.platform === 'win32' ? 'powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1' : 'bash .vale/install-vale.sh'; require('child_process').exec(cmd, (err, stdout, stderr) => { if (err) { console.error(stderr); process.exit(1); } console.log(stdout); })\"",
    "prose": "node -e \"const vale = process.platform === 'win32' ? './.vale/vale.exe' : './.vale/vale'; const { exec } = require('child_process'); exec(vale + ' --config=.vale.ini src/content', (err, stdout, stderr) => { console.log(stdout); if (stderr) console.error(stderr); if (err) process.exit(1); });\""
  }
}

• postinstall: Wird automatisch aufgerufen, wenn npm install ausgeführt wird
• install-vale: Ruft je nach Plattform die richtigen Installationsscripte auf
• prose: Ruft das Linting auf und gibt Fehler in der Kategorie „error“, „warning“ und „information“ aus

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:

 src/content/blog/myfile.mdx
 188:52  error  Don't start a sentence with     write-good.So 
                'So '.                                        

✖ 1 error, 0 warnings and 0 suggestions in 38 files.

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

{/* <!-- vale off --> */}

So the experiment failed because the measurements were taken incorrectly

{/* <!-- vale on --> */}

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:

[formats]
mdx = md

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:

{/* <!-- vale write-good.So = NO --> */}

So the experiment failed because the measurements were taken incorrectly

{/* <!-- vale write-good.So = YES --> */}

Integration mit Husky Pre-Commit Hooks

Sind alle Linter konfiguriert, müssen diese jeweils einzeln aufgerufen werden. Entwicklerinnen und Entwickler sollten nicht vergessen, die Linting-Schritte auch auszuführen:

npm run lint:check
npm run format:check
npm run prose

Diese Arbeit kann alternativ auch ein Pre-Commit-Hook erledigen. Im Falle eines Node-Projektes steht dafür das Tool Husky parat. Es ermöglicht, alle drei Linting-Stufen automatisch vor jedem Commit auszuführen. Die Installation erfolgt über:

npm install -D husky
npx husky install

Das prepare-Skript in der Datei package.json stellt sicher, dass Husky nach der Installation mit npm install automatisch konfiguriert wird:

{
  "scripts": {
    "prepare": "husky install"
  }
}

Nach der Installation steht das Verzeichnis .husky im Root-Verzeichnis des Repository zur Verfügung. Darin findet sich ein Unterverzeichnis, das als Namen nur den Unterstrich _ trägt. Seit Version 8 verwendet Husky nicht mehr die normalen Hooks im Verzeichnis .git/hooks, sondern es setzt die git-Variable core.hooksPath auf das Verzeichnis .husky.

Darüber hinaus ist eine Datei pre-commit im Verzeichnis .husky mit folgendem Inhalt anzulegen:

#!/usr/bin/env sh
.

echo ""
echo "🚀 Pre-commit Quality Checks"
echo "=============================="
echo ""

echo "💎 Running Prettier (Code Formatting)..."
echo "   ↳ Ensuring consistent code style across all files"
npm run format

if [ $? -ne 0 ]; then
  echo ""
  echo "❌ PRETTIER failed!"
  echo "   ↳ Code formatting could not be applied automatically"
  echo "   💡 Try running 'npm run format' manually to see the error"
  echo ""
  exit 1
fi

echo "   ✅ Code formatting completed successfully"
echo ""

echo "🔍 Running ESLint (Code Quality & Best Practices)..."
echo "   ↳ Checking for code quality issues and potential bugs"
npm run lint:check

if [ $? -ne 0 ]; then
  echo ""
  echo "❌ ESLINT failed!"
  echo "   ↳ Code quality issues found that need manual attention"
  echo "   💡 Run 'npm run lint' to automatically fix some issues"
  echo "   📋 Review the errors above and fix them before committing"
  echo ""
  exit 1
fi

echo "   ✅ Code quality checks passed successfully"
echo ""

echo "📝 Running Vale (Prose Linting)..."
echo "   ↳ Checking documentation and content for style consistency"

# Check if Vale binary exists, if not provide helpful message
if [ -f "./tools/vale" ] || [ -f "./tools/vale.exe" ]; then
  npm run prose:check
  
  if [ $? -ne 0 ]; then
    echo ""
    echo "❌ VALE failed!"
    echo "   ↳ Prose style issues found in documentation"
    echo "   💡 Review the suggestions above and edit the content manually"
    echo "   📋 Vale cannot auto-fix - manual review required"
    echo ""
    exit 1
  fi
  
  echo "   ✅ Prose style checks passed successfully"
else
  echo "   ⚠️  Vale binary not found - skipping prose checks"
  echo "   💡 Run 'npm run install-vale' to install Vale for prose linting"
fi

echo ""

echo "🎉 All quality checks passed! Ready to commit."
echo "   ↳ Your code is formatted, follows best practices, and prose is well-written"
echo ""

Abschließend ist die Datei noch als ausführbar zu markieren chmod +x ./husky/pre-commit. Beim Ausführen eines git commit werden dann automatisch alle drei Linter-Prüfungen durchgeführt. Sollte dabei einer der Linter auf einen Fehler laufen, wird der Commit abgebrochen. In Ausnahmefällen – etwa bei zeitkritischen Hotfixes oder bei Migrationen von Legacy-Code – kann es notwendig sein zu comitten, auch wenn einer der Linter fehlschlägt. Dies lässt sich mit dem Schalter --no-verify erreichen:

git commit -m "YOUR MESSAGE" --no-verify

CI/CD-Integration mit GitHub Actions

Während Pre-Commit Hooks lokale Qualitätskontrollen gewährleisten, sorgen GitHub Actions für zusätzliche Sicherheit in der CI/CD-Pipeline. Warum sollte aber eine zusätzliche CI/CD-Pipeline eingerichtet werden, wenn doch in den Pre-Commit Hooks bereits alles gecheckt wird? Zum einen ist möglich, den Pre-Commit Hook zu umgehen, andererseits können sich neue Situationen ergeben, wenn beispielsweise zwei oder mehr einzelne Branches, die jeder für sich erfolgreich geprüft wurden, zusammengeführt werden.

Das folgende Workflow-Skript wird bei jedem Pull-Request ausgeführt:

name: Pull request checks
on:
  pull_request:
    types: [ opened, synchronize, reopened ]
    
jobs:
  pull-request-checks:
    runs-on: [self-hosted, frickeldave-main]
    steps:
      - name: Print branch information
        run: |
          echo "Target branch: ${{ github.base_ref }}"
          echo "Source branch: ${{ github.head_ref }}"

      - name: Skip if not targeting 'main' or 'dev'
        if: github.base_ref != 'main' && github.base_ref != 'dev'
        run: |
          echo "ℹ️  This workflow only applies to PRs targeting 'dev' and 'main' branch."
          echo "Current target: '${{ github.base_ref }}' - skipping checks."
          echo "✅ This PR is not targeting 'dev' or 'main', so it passes."

      - name: Prevent any attempt to merge a branch other than 'dev' into 'main'.
        if: github.base_ref == 'main' && github.head_ref != 'dev'
        run: |
          echo "❌ Merges into 'main' are only allowed from the 'dev' branch."
          echo "❌ Your source branch is '${{ github.head_ref }}'."
          echo "❌ Target branch is '${{ github.base_ref }}'."
          exit 1
          
      - name: Allow merge from dev->main or from any other branch->dev
        if:  (github.base_ref == 'main' && github.head_ref == 'dev') || (github.base_ref == 'dev')
        run: |
          echo "✅ Merging into '${{ github.base_ref }}'. Start linting process..."

          # Install dependencies
          echo "--------------------------------------"
          echo "➕ Install dependencies"
          echo "--------------------------------------"
          echo "Downloading and installing nvm..."
          curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
          export NVM_DIR="$HOME/.nvm"
          [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
          
          export NODE_OPTIONS="--max-old-space-size=8192"
          source ~/.bashrc
          nvm install --lts
          npm ci || { echo "❌ Installation of dependencies failed"; exit 1; }

          # Run ESLint check
          echo "--------------------------------------"
          echo "🔍 Running ESLint check..."
          echo "--------------------------------------"
          npm run lint:check || { echo "❌ ESLint check failed"; exit 1; }
          
          # Run Prettier check
          echo "--------------------------------------"
          echo "✨ Running Prettier check..."
          echo "--------------------------------------"
          npm run format:check || { echo "❌ Prettier check failed"; exit 1; }
          
          # Run Vale prose check
          echo "--------------------------------------"
          echo "📝 Running Vale prose check..."
          echo "--------------------------------------"
          npm run prose || { echo "❌ Vale prose check failed"; exit 1; }
          
          echo "✅ All linting checks passed!"

Darüber hinaus lässt sich das erfolgreiche Ausführen des Skripts auch noch in den Branch-Protection-Regeln eintragen (siehe Abbildung 1).

Fazit: Verbessertes Qualitätsmanagement durch mehrstufiges Linting

Das mehrstufige Linting-System für Astro-Projekte zeigt, wie ein moderner Entwicklungsworkflow mit Fokus auf das Qualitätsmanagement aussehen kann. Die Kombination von Code-Qualität, Formatierung und Prosa-Linting schafft einen ganzheitlichen Ansatz, der sowohl zu technischen als auch kommunikativen Verbesserungen führt.

Zudem bleibt der Stack offen für weitere Anpassungen: KI-gestütztes Prosa Linting, automatische Übersetzungen oder kontextuelle Verbesserungsvorschläge lassen sich auf Basis der vorgestellten Implementierung hinzufügen.

Dieses Setup empfiehlt sich als Grundlage für professionelle Dokumentationsprojekte und zeigt, dass moderne Entwicklungstools nicht nur die Produktivität steigern, sondern auch zu höherer Qualität der Endprodukte führen.

(map)