lenneTech/check-Script-Ausführung

Das check-Skript ausführen

Dieses Skill ist die alleinige maßgebliche Quelle für die Ausführung des check-Skripts in package.json in lt-dev-Workflows. Jeder Reviewer, Rebaser und Orchestrator, der die Ausführbarkeit eines Projekts garantieren muss, muss dieses Verfahren wortwörtlich befolgen – das Duplizieren der Regeln über mehrere Agenten führt zu Abweichungen.

Ziel: Ein wirklich grüner check-Lauf (exit 0) ist eine nicht verhandelbare Voraussetzung dafür, dass ein Review oder ein Rebase als abgeschlossen gilt. Die einzig akzeptierte Ausnahme ist eine Upstream-Abhängigkeits-Schwachstelle, bei der die vollständige Eskalationsleiter ausgeschöpft wurde.

Wann dieses Skill verwendet wird

Aufrufer	Phase	Auslöser	Modus
/lt-dev:review	Phase 1.5	Bevor ein spezialisierter Reviewer gestartet wird	Advisory
lt-dev:code-reviewer	Phase 1.5	Vor dem Single-Pass-Review (überspringen, wenn der Orchestrator es bereits ausgeführt hat)	Advisory
lt-dev:test-reviewer	(Eingabe-Briefing)	Respektiert die hier definierten Skip-Semantiken	Advisory
/lt-dev:take-ticket	SCHRITT 8	Nachdem alle Test-Pillars grün sind	Blocking
/lt-dev:git:ship	SCHRITT 1, SCHRITT 4b	Pre-Flight und nach der erneuten Überprüfung nach dem Rebase	Blocking
/lt-dev:ticket-cycle	via take-ticket + git:ship	Gesamter Zyklus	Blocking
lt-dev:branch-rebaser	Phase 6.5	Nach Lint/Format, vor Tests	Blocking

Modi der Aufrufer

Das Verfahren ist in beiden Modi identisch. Nur das, was mit einem ungelösten Fehler passiert, unterscheidet sich, und genau dieser Unterschied ist der Kern der Unterscheidung:

• Advisory – Die Aufgabe des Aufrufers ist es, zu berichten. Ein roter check wird als kritischer Befund gemeldet, und der Workflow wird fortgesetzt, da der Benutzer dennoch den Rest des Reviews wünscht.
• Blocking – Die Aufgabe des Aufrufers ist es, auszuliefern. Ein roter check stoppt den Workflow. Es wird nichts gepusht, kein MR/PR erstellt, es wird nichts gemerged.

Jeder Pfad, der zu einem MR/PR oder einem Merge führt, läuft im Blocking-Modus. Ein roter check, der den Basis-Branch erreicht, kostet das gesamte Team: CI wird für alle rot, der nächste take-ticket zweigt von kaputtem Code ab, und die Person, die es schließlich repariert, hat keine Ahnung, welche Änderung es verursacht hat. Deshalb hat die Leiter in Schritt 3 keine Iterationsbegrenzung und warum die Residual-Liste in Schritt 5 so eng gefasst ist, wie sie ist.

Verfahren

Schritt 1 – check-Skripte finden

Verwende das dedizierte Hilfsskript (befindet sich im lt-dev-Plugin):

bash "${CLAUDE_PLUGIN_ROOT}/scripts/discover-check-scripts.sh"

Die Ausgabe ist TSV, ein Projekt pro Zeile:

<package.json Pfad>\t<check-Skript>\t<includes_tests:no|unit+api|yes>\t<Paketmanager>

includes_tests-Werte – die Aufrufer entscheiden, was mit jedem zu tun ist, das Discovery selbst schreibt kein Verhalten vor:

Wert	Bedeutung	Playwright-Abdeckung
no	Kein Test-Runner in der Check-Kette erkannt.	Nicht abgedeckt.
unit+api	Die check-Kette delegiert an den lt check.mjs-Wrapper, der Unit (app) + API (api) Test-Schritte ausführt und Playwright bewusst überspringt (Playwright läuft über lt dev test / CI – siehe scripts/check.mjs).	Nicht abgedeckt – Playwright muss bei Bedarf separat ausgeführt werden.
yes	Direkter Pattern-Match auf test, vitest, jest oder playwright in der Check-Kette (transitiv, eine Ebene der zusammengesetzten Auflösung). Der Umfang ist das, was das Skript definiert.	Unbekannt – Aufrufer sollten lokal überprüfen, ob Playwright-Abdeckung erforderlich ist.

Das Hilfsskript:

• Verwendet git ls-files „package.json“ „**/package.json“, sodass es .gitignore respektiert und node_modules überspringt
• Analysiert JSON über jq → node -e → grep+sed Fallback-Kette (funktioniert auch ohne installiertes jq)
• Löst einstufige zusammengesetzte Skripte auf („check“: „pnpm run ci“ → sucht ci)
• Erkennt den Paketmanager pro Projekt über die Lockdatei (pnpm-lock.yaml → pnpm, etc.; Standard pnpm)

Wenn das Hilfsskript nichts zurückgibt → kein Projekt definiert check → den Rest dieses Skills überspringen.

Schritt 1a – Keine oxlint-Fix-Vorschläge

oxlint --fix-suggestions wendet Korrekturen an, die oxlint selbst als möglicherweise verhaltensändernd markiert: sein no-console-Vorschlag löscht den Aufruf. --fix-dangerously geht noch weiter. Aktuelle Templates übergeben keines von beiden, aber Projekte von älteren tun dies immer noch im Check-Wrapper, in lint:fix, in lint-staged oder in einem eigenen scripts/check.mjs des Projekts. lt fullstack update entfernt sie im Workspace-Root und in der App (nur getrackte, saubere Dateien); das API-Projekt behält seine eigenen Dateien, daher wird ein Treffer dort von Hand oder durch Übernehmen der aktuellen nest-server-starter-Datei entfernt. Beobachtet in nest-server (2026-09, claude-code PR #10): Ein Commit-Hook verwandelte ein console.log in einen leeren Funktionsrumpf und meldete dennoch „bestanden“. Vor Schritt 2 nach einer Verwendung eines der Flags suchen; eine Erwähnung in einem Kommentar zählt nicht:

git grep -n -E "(^|[[:space:]\"'])--fix-(suggestions|dangerously)" -- '*package.json' '*.lintstagedrc*' '*lint-staged.config.*' '*scripts/check.mjs' \
  | grep -v -E '^[^:]+:[0-9]+:[[:space:]]*(//|/?\*|#)'

Der zweite Filter entfernt Kommentarzeilen: Der aktuelle nest-server-starter-Wrapper erklärt in einem Kommentar, warum er nur einfaches --fix übergibt.

Bei einem Treffer läuft der Check ohne automatische Korrektur:

• Führe den lt-Wrapper als schreibgeschütztes Gate aus: <pm> run check --no-fix (npm: npm run check -- --no-fix). Jeder Wrapper, der noch eines der Flags übergibt, kennt bereits --no-fix. Wenn die eigene Kette eines Projekts lint:fix aufruft, oder sein eigenes scripts/check.mjs einer der Treffer ist, führe die Schritte dieses Projekts mit lint anstelle von lint:fix aus.
• Behebe Lint-Funde von Hand oder mit einfachem oxlint --fix; formatiere mit dem projektspezifischen Formatierer wie gewohnt.
• Nenne jeden Treffer (Datei:Zeile) im Schritt-8-Bericht mit seiner Abhilfe: lt fullstack update für das Root und die App, Entfernen des Flags von Hand (oder der aktuellen nest-server-starter-Datei) für das API-Projekt.

Schritt 2 – check pro Projekt ausführen

Gehe für jedes gefundene Projekt in dessen Verzeichnis und führe das check-Skript mit dem erkannten Paketmanager aus:

cd "$(dirname <package.json Pfad>)"
<Paketmanager> run check

Erfasse stdout, stderr und Exit-Code. Verfolge einen Iterationszähler, der bei 1 beginnt.

Schritt 3 – Automatische Korrekturschleife (iterieren, bis wirklich grün)

Wenn der check eines Projekts mit einem Exit-Code ungleich Null beendet wird:

1. Analysiere alle Fehler aus dem aktuellen Lauf (Typecheck, Lint, Build, fehlende Imports, Typkonflikte, ungenutzte Symbole, Audit-Funde usw.)
2. Behebe jeden Fehler an der Ursache via Read + Edit. Bereits vorhandene Fehler werden ebenfalls behoben – ob ein Fehler von diesem Diff stammt oder bereits vorhanden war, macht für die Ausführbarkeit des Projekts keinen Unterschied, und ein roter check blockiert die nächste Person genauso hart. Scope-Grenzen gelten nicht für die Ausführbarkeit. Die eine Frage, die hier alles entscheidet, ist „Kann das behoben werden?“, und solange die Antwort „Ja“ lautet, wird es behoben.
3. Führe check von Grund auf neu aus. Vertraue niemals einem teilweisen Zustand.
4. Fahre mit der Iteration fort, bis eine dieser terminalen Bedingungen erreicht ist:
   • (a) GRÜN – check verlässt mit 0 → für dieses Projekt erledigt
   • (b) FESTGEFAHREN – eine vollständige Iteration hat zu keiner Netto-Reduktion der Fehleranzahl geführt
5. Keine harte Iterationsbegrenzung. Solange jede Iteration die Fehleranzahl strikt reduziert, weitermachen. Das Ziel ist ein echtes Grün.

Eine enge Ausnahme, und es geht um Kollision, nicht um Scope. Punkt 2 bleibt bestehen: Ein bereits vorhandener Fehler wird behoben, weil ein roter check die nächste Person unabhängig davon blockiert, wer ihn geschrieben hat. Was Punkt 2 nicht abdeckt, ist ein Fehler innerhalb von nicht festgeschriebener Arbeit, an der eine andere aktive Sitzung gerade mitten im Schnitt arbeitet – das umzuformen ist keine Scope-Frage, sondern zwei Sitzungen, die eine Datei bearbeiten, und der Kollege kehrt zu einem umgeschriebenen Refactoring zurück und hat mehr Zeit verloren, als die Korrektur eingespart hätte. Wenn der Baum schmutzig ist und bash "${CLAUDE_PLUGIN_ROOT}/scripts/change-provenance.sh" den fehlschlagenden Pfad einem aktiven Kollegen zuordnet: Behebe es, wenn es trivial und in sich geschlossen ist (ein fehlender Import, ein Formatverstoß, ein verirrtes console.log), und melde es ansonsten als Blocker unter Nennung des Autors, plus einer GELÖST-Notiz mit der Diagnose, damit er seine eigene Arbeit in einem Schritt beheben kann. Niemand aktiv, oder nichts zurechenbar: Punkt 2 gilt unverändert.

FESTGEFAHREN ist ein Signal, den Ansatz zu ändern, nicht die Erlaubnis aufzuhören. Die Zählung hört auf zu fallen, wenn derselbe Fix wiederholt wird, also muss die nächste Iteration den Fehler anders angehen: Die fehlschlagende Datei vollständig lesen, anstatt nur um die gemeldete Zeile herum zu patchen, prüfen, ob zwei Fehler eine gemeinsame Ursache haben, nachsehen, wie ein funktionierendes Schwestermodul dasselbe löst, den fehlschlagenden Schritt allein ausführen, um die Ausgabe zu sehen, die der Gesamtlauf verschluckt hat, prüfen, ob es sich um eine der bekannten Gefahren in den Schritten 6.5 bis 6.8 handelt. Erst wenn ein wirklich anderer Ansatz versucht wurde und die Zählung immer noch hält, greift die Residual-Klassifizierung in Schritt 5 – und im Blocking-Modus stoppt alles außer einer ausgeschöpften Abhängigkeits-Schwachstelle den Workflow.

Schritt 4 – Audit-Funde: Eskalationsleiter für obligatorische Korrekturen

Wenn pnpm audit / npm audit / yarn audit (durch check aufgerufen) eine Schwachstelle meldet, durchlaufe diese Leiter, bevor der Fund als Akzeptiert eingestuft wird. Führe check nach jedem Schritt erneut aus.

#	Schritt	Befehl (pnpm / npm / yarn)
1	Update auf die neueste kompatible Version	pnpm update <pkg> / npm update <pkg> / yarn upgrade <pkg>
2	Automatische Behebung	pnpm audit --fix / npm audit fix / yarn audit --fix
3	Erzwungenes Semver-Major-Upgrade	pnpm audit --fix --force / npm audit fix --force
4	Direkte Abhängigkeit auf die nächste Major-Version anheben, wenn der Advisory dort einen Fix listet	pnpm add <pkg>@<major> / npm install <pkg>@<major> / yarn add <pkg>@<major>
5	Eine transitive Abhängigkeitsversion erzwingen	pnpm.overrides / resolutions (yarn) / overrides (npm) Block in package.json, dann neu installieren
6	Den VERBRAUCHER anheben, nicht das anfällige Paket	die direkte Abhängigkeit, die es einzieht, und das lt-Framework, wenn das Framework es pinnt (@lenne.tech/nest-server / @lenne.tech/nuxt-extensions) – ein vollständiges /lt-dev:maintenance:maintain ist die gründliche Form
7	Den Verbraucher patchen – nur unter den unten stehenden Bedingungen	pnpm patch <pkg> → patchedDependencies
8	Das Paket ersetzen	Wechsel zu einer gewarteten Alternative, wenn es aufgegeben wurde

Schritt 6 ist die Sprosse, die übersprungen wird, und es ist diejenige, die am häufigsten funktioniert. Die Schritte 1 bis 5 schieben alle das anfällige Paket nach vorne. Wenn das fehlschlägt, liegt der Grund normalerweise nicht am anfälligen Paket selbst – es ist der Verbraucher, der es zurückhält, indem er einen anfälligen Bereich pinnt oder eine API verwendet, die das gepatchte Major entfernt hat. Die zu stellende Frage ist also „Wer hält diese Version hier?“, und die Antwort ist eine direkte Abhängigkeit oder ein Framework, dessen Pin ein Override nicht überbieten kann. Ein Override ist ein Pin, und ein Pin ist strikt schlechter als ein echter Versionssprung: Er treibt den Baum von dem weg, was Upstream testet, und er fault still vor sich hin. Nimm den Sprung, wo einer existiert.

Schritt 7 (Patchen) ist bewusst eng gefasst, und diese Enge ist der Punkt. Wenn das gepatchte Major nur beim Laden fehlschlägt – ein entfernter Standard-Export, ein umbenannter Einstiegspunkt – dann sieht ein Einzeiler-Patch so aus, als würde er den Advisory ordnungsgemäß schließen, anstatt ihn zu unterdrücken. Manchmal tut er das. Drei Bedingungen müssen zuerst erfüllt sein, und die dritte ist die, die normalerweise fehlschlägt:

1. Der Patch zielt auf einen stabilen Pfad im anfälligen Paket und ist auf eine genaue Version gepinnt. Was einen Patch zerbricht, ist nicht dist/ als solches – veröffentlichte Pakete liefern dist/ und nichts anderes –, sondern ein Pfad, der sich zwischen Releases bewegt. dist/chunks/<hash>.mjs wird vom nächsten Build umbenannt und der Patch schlägt dann für alle im Team fehl; dist/index.mjs ist der eigene Einstiegspunkt des Pakets und bleibt bestehen. Ein Patch, der ein minifiziertes Symbol benennt, ist immer noch akzeptabel mit dem Version-Pin, weil der Pin das Risiko in einen lauten pnpm install-Fehler anstelle einer stillen Fehlanwendung des Patches verwandelt. Patche die anfällige Abhängigkeit, nicht einen Verbraucher, der sie zufällig importiert – siehe den gemessenen Fall unten, wo die erste Bewertung auf den Chunk des Verbrauchers schaute und die Sprosse aus diesem Grund ablehnte.
2. Wiege den Produktions-Closure gegen die Wartungskosten ab. Ein Patch ist eine dauerhafte Verpflichtung bei jedem zukünftigen Update, also kann er für einen Dev-Tooling-Pfad, der nicht in die Produktion gelangen kann, leicht mehr ausgeben, als er einbringt – in einem einzelnen Projekt. Eine TEMPLATE-Vorlage dreht diese Rechnung um: Jedes generierte Projekt erbt einen Patch, während ein Residuum in jedem von ihnen neu diskutiert werden müsste. Dies ist ein Urteil, kein Veto; die Bedingungen 1 und 3 sind die harten.
3. Laden ist nicht dasselbe wie Funktionieren. Ein Major, das einen Export entfernt hat, hat normalerweise auch das Verhalten geändert, also lässt ein gepatchter Import das Modul importieren, während der Verbraucher gegen eine API läuft, auf der er nie getestet wurde. Wenn du nicht sagen kannst, was sich sonst in diesem Major geändert hat und warum es hier keine Rolle spielt, ist der Patch eine Vermutung im Kostüm einer Reparatur.

Patche das ANFÄLLIGE Paket, nicht den Verbraucher. Das ist die Unterscheidung, die entscheidet, ob die Sprosse funktioniert, und es ist leicht, sie falsch zu machen, weil der Fehler auf den Verbraucher zeigt. Gemessen, lt-crm 2026-10-06: @nuxt/[email protected] macht import Git from 'simple-git', und das Anheben von simple-git auf die einzige behobene Zeile (4.x, die diesen Standard-Export fallen gelassen hat) ließ nuxt prepare mit does not provide an export named 'default'' abbrechen. Die erste Bewertung schaute auf das eigene dist/chunks/module-main.mjs von devtools, fand den Import dort und lehnte das Patchen basierend auf Bedingung 1 ab – ein kompilierter Chunk – was das richtige Urteil über die falsche Datei war. Der Patch gehört eine Ebene tiefer, in simple-git's eigenem dist/index.mjs, wo eine einzelne hinzugefügte Zeile den Standard-Export (default) wiederherstellt, den das Modul bereits als benannten Export simpleGit exportiert. An der gehärteten Codebasis ändert sich nichts; nur die Oberfläche des Moduls kommt zurück.

Damit sind alle drei Bedingungen erfüllt: Es handelt sich um das anfällige Paket und nicht um ein Artefakt des Verbrauchers, es ist auf eine genaue Version gepinnt (patchedDependencies: {'[email protected]': …} plus das Override-Ziel), und die API, die devtools tatsächlich aufruft – branch, revparse, raw, log – ist im Export des gepinnten Pakets vollständig vorhanden. Der Patch ändert nichts an der Logik; er stellt nur eine Export-Oberfläche wieder her.

Schritt 4a – Sicherheitshinweis: Keine automatische Eskalation

Benachrichtige keinen Menschen über Audit-Funde. Allein die Automatisierung führt die Leiter durch. Wenn eine Schwachstelle nach Leiter-Schritt 8 bestehen bleibt und das Projekt in einem Advisory-Kontext läuft, klassifiziere sie als „Akzeptiert: Eskalationsleiter ausgeschöpft“ – mit einem Link zu jedem Advisory und der Notiz, welche Sprosse erreicht wurde. In einem Blocking-Kontext: Stoppe den Workflow und gib die vollständige Leiter-Diagnose aus, damit ein Mensch entscheiden kann.

Schritt 5 – Sprint-Residuen (nur Advisory-Modus)

Wenn die automatische Schleife in Schritt 3 feststeckt und der Aufruf Advisory ist: Der letzte Lauf war rot, kein Residuen-Management zur Folge. Der rote check wird als Kritischer Befund im Review-Bericht gemeldet. Der Kritische Befund enthält ein Residuen-Array mit Einträgen, die einen dieser Typ-Tags tragen – alles andere muss auf Schritt 3 iteriert werden, bis es gelöst oder feststeckt (leeres Residuen-Array = festgesteckter Lauf; die Lücke wird eine in Schritt 3>5 geschlossen, die andere in den Sprint selbst).

Tag	Bedingung	Bedeutung
dependency-vulnerability-exhausted	Die Eskalationsleiter in Schritt 4 wurde für einen bestimmten Advisory bis zum Ende durchlaufen.	Obwohl Schwachstellen normalerweise behoben werden müssen, ist dieser Advisory nicht reparabel, ohne die Codebasis grundlegend zu ändern. Der Bericht muss auf den Advisory und die erreichte Sprosse verweisen. Nur gültig, wenn die Leiter bis Schritt 8 durchlaufen wurde.
upstream-issue	Der Fehler liegt in einem Drittanbieter-Paket / Framework / Tool und wurde dort gemeldet (Link erforderlich).	Das Team kann nichts tun, außer zu warten, dass der Fix veröffentlicht wird. Der Bericht muss einen Link zum Issue enthalten.
environment-flaky	Der Fehler tritt nur in dieser Umgebung auf (CI-Spezifikum, plattformspezifisches Verhalten).	Das Team kann sich entscheiden, den Check in CI anders zu konfigurieren, wenn es gewünscht ist. Der Bericht muss die Umweltdetails dokumentieren.
out-of-scope-hard-blocker	Der Fehler liegt nicht in den Dateien, die vom aktuellen Workflow betroffen sind, und er blockiert einen Check, den dieses Ticket nicht adressieren kann.	Der Bericht leitet das Problem an das entsprechende Team weiter. Ein separates Ticket muss erstellt werden, bevor dieses Ticket als erledigt betrachtet werden kann. Kein Kommentar hier, aber ein gültiger Tag für die Residuen-Ausgabe.

Blockierender Modus: Wenn der check im Blocking-Kontext rot ist und keine ausgeschöpfte Abhängigkeits-Schwachstelle vorliegt, wird der Workflow gestoppt. Die obigen Tags gelten nicht als Ausnahmen; sie sind nur für den Advisory-Modus relevant. Die Iteration muss fortgesetzt werden, bis das Problem grün ist oder ein Mensch eingreift.

Schritt 6 – Führe die Befehle nacheinander aus

Führe die Schritte in der folgenden Reihenfolge aus:

1. Führe die discover-check-scripts.sh-Erkennung aus (Schritt 1).
2. Führe check für jedes gefundene Projekt aus (Schritt 2).
3. Wende die automatische Reparaturschleife (Schritt 3) auf jedes fehlschlagende Projekt an.
4. Eskaliere Audit-Funde entlang der Leiter (Schritt 4).
5. Klassifiziere Residuen (Schritt 5), wenn der Aufruf im Advisory-Modus erfolgt.

In jedem Schritt muss der gesamte Workflow des Schritts abgeschlossen sein, bevor mit dem nächsten fortgefahren wird.

Wenn ein Schritt das Projekt grün macht (exit 0), sind nachfolgende Schritte für dieses Projekt nicht mehr erforderlich.

Wenn ein Schritt fehlschlägt (exit != 0), ohne dass die Ausnahmen in Schritt 5 zutreffen, fahre mit dem nächsten Schritt fort (falls vorhanden), ABER unter Beibehaltung des roten Status des Projekts.

Wenn alle Projekte abgeschlossen sind:

• Advisory-Modus: Erstelle einen Bericht mit dem Status jedes Projekts (grün/rot) und den angewendeten Korrekturen. Wenn Residuen vorhanden sind, füge sie bei.
• Blockierender Modus: Wenn alle Projekte grün sind, fahre fort. Wenn eines rot ist, stoppe den Workflow mit einer klaren Meldung darüber, welches Projekt fehlgeschlagen ist und warum.

Schritt 6.5 – Bekanntes Problem: tsconfig nicht gefunden (@lenne.tech/nest-server)

Bestimmte @lenne.tech/nest-server-Versionen geben einen kryptischen TypeScript-Fehler aus, bei dem aussieht, als fehle die tsconfig.json. Die häufigste Ursache ist ein veralteter Symlink im Workspace-Root. Das Problem zu erkennen und zu beheben:

# Erkenne es: Fehler wie „Cannot find tsconfig.json“ oder seltsame TypeScript-Lade-Fehler
test -L "tsconfig.json" && echo "Symlink" || echo "Echte Datei"

# Behebe es: Entferne den Symlink und führe pnpm install erneut aus
rm tsconfig.json && pnpm install

Nachdem pnpm install erneut ausgeführt wurde, sollte die TypeScript-Konfiguration korrekt aufgelöst werden.

Schritt 6.6 – Bekanntes Problem: postinstall-Skript-Fehler (node_modules/ beschädigt)

Manchmal erzeugt ein teilweise fehlgeschlagener postinstall-Hook node_modules/ in einem ungültigen Zustand. Erkenne und behebe es:

# Erkenne es: Installationsfehler ohne klare Paketkonflikte
ls node_modules/.package-lock.json || echo "Keine node_modules vorhanden oder beschädigt"

# Behebe es: Vollständige Neuinstallation
rm -rf node_modules
git checkout node_modules/.gitkeep node_modules/.gitignore 2>/dev/null; true
pnpm install

Pro-Tipp: Manchmal weigern sich Arbeiter-Knoten, nach einer bestimmten Anzahl von CI-Läufen Pakete zu installieren. Trenne die Verbindung und verbinde sie erneut – die Wiederverbindung behebt das Problem fast immer.

Schritt 6.7 – Bekanntes Problem: Prisma falsche Client-Generierung

Fehler im Zusammenhang mit Prisma deuten normalerweise auf einen generierten Client hin, der nicht mit dem Schema synchron ist – etwas, das häufig nach einem Branch-Wechsel oder einer Schema-Änderung passiert, wenn die Generierung nicht ausgeführt wurde. Außerdem scheitert der check-Befehl in einem Prisma-Projekt, wenn Prisma seine Client-Generierung nicht ausführen kann.

# Erkenne es: Fehler im Zusammenhang mit Prisma oder SQL-Client
# Behebe es: Generiere den Prisma-Client neu
npx prisma generate

Wenn das nicht funktioniert, versuche zuerst pnpm install erneut auszuführen, um sicherzustellen, dass alle Abhängigkeiten vorhanden sind:

pnpm install
npx prisma generate

Wenn der Fehler weiterhin besteht, kann es sich um ein Problem mit Prisma-Grenzen handeln:

rm -rf node_modules/.prisma
npx prisma generate

Schritt 6.8 – Bekanntes Problem: Framework-Kompatibilitäts-Updates

Füge .npmrc-Inhalte für ältere Nuxt-/Vue-Projekte hinzu. Wenn das Projekt Legacy-Builds verwendet, muss möglicherweise NODE_OPTIONS gesetzt werden, um Kompatibilitätsprobleme zu umgehen – besonders auf neueren Node.js-Versionen (>= 18):

# Erkenne es: Fehler beim Laden von nativen Modulen oder Build-Verhalten, die darauf hindeuten, dass OpenSSL nicht verfügbar ist
# Behebe es: Füge NODE_OPTIONS hinzu, um den Legacy-Provider zu verwenden
export NODE_OPTIONS="--openssl-legacy-provider"

# Führe den Check dann erneut aus
"$PKG_MANAGER" run check

Dauerhaftere Lösung (für CI/CD):

# Füge diese Zeile zu .npmrc hinzu, wenn sie nicht vorhanden ist
echo "NODE_OPTIONS=--openssl-legacy-provider" >> .npmrc

Schritt 7 – Wiederherstellung von Änderungen zur Fehlerbehebung

Während der automatischen Schleife (Schritt 3) getätigte Änderungen müssen rückgängig gemacht werden, wenn der Workflow fehlschlägt.

Für jeden Fehlerbehebungsversuch, der während des check-Workflows vorgenommen wurde:

1. Verfolge jede vorgenommene Änderung (Datei, ursprünglicher Inhalt, neuer Inhalt)
2. Bei Workflow-Fehlschlag: Kehre jede Änderung auf ihren ursprünglichen Zustand zurück, bevor der Workflow beendet wird
3. Bei erfolgreichem Abschluss: Behalte die Änderungen und fahre mit dem nächsten Schritt fort

Ausnahme: Wenn die Änderung ein bereits vorhandener Fehler ist, der keine Beziehung zum aktuellen Ticket hat und die Workflow-Anforderungen nicht blockiert (nur Advisory-Modus), dann kann die Änderung beibehalten werden, nachdem das Problem im Bericht dokumentiert wurde.

Wichtig: Die Wiederherstellung gilt NUR für Änderungen, die während dieses spezifischen check-Workflows vorgenommen wurden. Es darf niemals Auswirkungen auf nicht zusammenhängende Dateien haben.

Schritt 8 – Berichterstattung (Advisory-Modus) oder Ergebnis (Blocking-Modus)

• Advisory-Modus: Gib den check-Status und ggf. die Liste der Residuen aus.
• Blocking-Modus: Gib bei Erfolg „Projekt status: Grüner Check – Ausführbarkeit bestätigt“ aus. Gib bei Misserfolg das Residuen-Array aus, das dokumentiert, warum der Check fehlschlug, und beende den aktuellen Befehl mit dem Status-Code 1.

Gib check-Ergebnisse im folgenden JSON-Format aus. Dieses Format ist für maschinelles Parsen und menschliche Lesbarkeit optimiert:

{
  "skill": "running-check-script",
  "mode": "<advisory|blocking>",
  "projects": {
    "<project-path>": {
      "status": "<green|red>",
      "errors_count": <number>,
      "iterations": <number>,
      "residuals": [
        {
          "type": "<residual-tag>",
          "description": "<Kurzbeschreibung>",
          "location": "<Datei:Zeile>",
          "details": "<Detaillierte Erklärung oder Link zum Issue>"
        }
      ],
      "fixes_applied": [
        {
          "step": "<fix|audit>",
          "description": "<Beschreibung der angewendeten Korrektur>",
          "file": "<dateiname oder ‚verschiedene‘>"
        }
      ]
    }
  },
  "audit_trail": [
    "<Schrittweise Liste der Aktionen, die während des Workflows ausgeführt wurden – optional aber empfohlen>"
  ]
}