EugineKosenko/majordom

org-lint

Linter für Prosa-Formatierungsregeln von Org-/Md-Dateien, dokumentiert in ~/.claude/rules/org-babel.md. Ziel ist es, nicht jedes Mal auf das Gedächtnis für jede einzelne Regel angewiesen zu sein (daher das Risiko: die gerade genannte Regel korrigieren und den Rest übersehen), sondern den Text durch eine explizite Liste zu jagen.

Wann anwenden

• Direkt nach dem Bearbeiten oder Schreiben eines neuen Prosaabsatzes in einer .org/.md-Datei (anstatt jede Regel manuell aus dem Gedächtnis zu prüfen) – bevor das Ergebnis dem Benutzer gezeigt wird.
• Auf explizite Anfrage des Benutzers („Überprüfe Org-Regeln“, „Führe Lint aus“, Vergleich mit clippy usw.).
• Nicht anwenden auf Inhalte von #+begin_src/#+begin_example-Blöcken (Code) – nur auf Prosaabsätze und Überschriften.

Schritt 1 – Mechanische Prüfung

Führe das Skript für die bearbeitete(n) Datei(en) aus:

python3 ~/.claude/skills/org-lint/scripts/lint.py PFAD/ZUR/DATEI.org

Das Skript erkennt per Regex:

• / ohne Leerzeichen um ~...~/=...= (~a~/~b~ statt ~a~ / ~b~) – SICHERER VERSTOSS.
• [[file:../ – Verweis relativ zum aktuellen Verzeichnis statt Abkürzung root: – SICHERER VERSTOSS.
• Fehlender abschließender Zeilenumbruch in der Datei – SICHERER VERSTOSS.
• Akronym in Großbuchstaben innerhalb von =...= (z.B. =CSS=) – erfordert Bestätigung (seltene Ausnahmen erlaubt).
• Kursiv /Wort/ – erfordert Prüfung: Handelt es sich wirklich um einen Begriff des Projektglossars (gibt es einen Abschnitt in spcfctn/glossary.org? Steht bei der ersten Erwähnung in dieser Datei ein Link darauf?), oder handelt es sich fälschlicherweise um einen NICHT konvertierten Verweis auf einen Abschnitt/eine Datei (sollte [[*Abschnitt][...]] sein).
• Erwähnung einer Datei als =pfad/datei.org= – erfordert Prüfung: Sollte dies stattdessen ein echter [[file:...]]-Link sein?
• Wort „Parameter“/„Parameters“/… – erfordert Prüfung: Wenn es sich um Eigenschaften einer Rust/Yew-Komponente handelt (struct ...Props), ist die korrekte Übersetzung „Eigenschaften“/„Eigenschaft“, nicht „Parameter“/„Parameter“ (veralteter Begriff). Außerhalb von Yew-Komponenten (Funktionsparameter, CLI, REST-Prozeduren usw.) ist „Parameter“ OK, nicht ändern.
• Block :noweb-ref Definition steht vor Block :noweb-ref Deklarationen – erfordert Prüfung: Die Deklaration muss zuerst kommen, in der Lesereihenfolge der Datei von oben nach unten (siehe org-babel.md).
• Mehrere #+begin_src-Blöcke mit GLEICHEM :tangle PFAD und ohne :noweb yes/<<...>> in der Datei – SICHERER VERSTOSS (veraltete Verkettung, wie im alten gitignore.org – siehe org-babel.md). Umwandeln in einen Container-Block :tangle+:noweb yes mit <<Name>>-Platzhalter(n) und Abschnitte mit :noweb-ref Name.
• Datei wird in MEHRERE verschiedene Zieldateien getangelt, von denen MINDESTENS ZWEI selbst noweb konsumieren (haben :noweb yes auf einem Skelett-#+begin_src, z.B. config.org → .env.example + parameters.php), aber mindestens ein :noweb-ref/<<...>>-Block wurde OHNE Zielpräfix benannt (Name statt env:Name) – SICHERER VERSTOSS (siehe org-babel.md, Regel zu Präfixen in Multi-Target-Org-Dateien). Für Dateien mit EINER Zieldatei sowie für Dateien, in denen NUR EIN Ziel noweb konsumiert und die restlichen eigenständige Ein-Block-:tangle-Ziele ohne <<...>> sind (z.B. gitignore.org: 5 :tangle-Ziele, aber nur das root .gitignore via noweb-Skelett) – kein Präfix nötig, da keine tatsächliche Mehrdeutigkeit besteht.
• Parameter im Header von #+begin_src in falscher Reihenfolge – SICHERER VERSTOSS. Korrekte Reihenfolge: Block-Typ → :noweb yes → :noweb-sep "..." → restliche Parameter → :tangle PFAD oder :noweb-ref Name (ganz am Ende, siehe org-babel.md).
• Datei heißt cargo.org – SICHERER VERSTOSS (veralteter Name für Rust-Projekte; umbenennen in config.org, siehe org-babel.md).
• :tangle zeigt auf einen absoluten Pfad (/..., ~/...) oder über aufsteigendes .. – SICHERER VERSTOSS (siehe org-babel.md); das Ziel muss ein rein absteigender relativer Pfad von der Org-Datei sein. Wenn das Ziel tatsächlich außerhalb des Quellbaums liegt, ist ein Symlink oder eine andere Verzeichnisstruktur erforderlich, nicht ../absoluter Pfad (Episode: farba-override → farba-theme via ../farba-theme/..., Task FS-1085).
• Großschreibung außerhalb von =...= (z.B. NICHT, NUR) – erfordert Prüfung: Wenn dies eine Hervorhebung eines Wortes ist und kein Akronym/Abkürzung, ersetze durch Org bold (*nicht*), nicht Großschreibung.
• Wort „Hook“/„Hook“ (Übersetzung von „hook“, React/Yew) – veraltet; korrekte Übersetzung ist „Haken“ (betrifft nur Prosa, nicht Code-Identifikatoren wie use_effect_with).
• Prosa-Zeilen, die länger als 105 Zeichen sind – erfordert fill-paragraph via emacsclient (siehe unten).

„SICHERE“ Funde immer korrigieren. „Erfordert manuelle Prüfung“ – jede einzeln prüfen, aber nicht alle sind Fehler (z.B. =rest=/=forge-yew= – legitime Abkürzung/Crate-Name, kein Verstoß).

Schritt 2 – Manuelle Checkliste (was das Skript nicht erkennt)

• Code-Identifikatoren/Typen/Funktionen/Variablen/Module – und beliebige Code-Fragmente oder -Ausdrücke (z.B. id=1, value == 0, items()) – Tilde ~...~. Abkürzungen/Akronyme und die „öffentliche“ Form des Crate-/Bibliotheksnamens (mit Bindestrich) – Gleichheitszeichen =...=. Qualifizierter Pfad crate::Typ – das ist ein Typname aus dem Code, daher komplett in die Tilde, auch mit Crate-Präfix.
• Abkürzungen/Akronyme – klein geschrieben innerhalb eines Satzes, nur der erste Buchstabe groß am Satzanfang (keine vollständige Großschreibung), außer bei seltenen etablierten Ausnahmen.
• Verweis auf einen Abschnitt in derselben Datei – [[*Überschriftname][Name]], nicht kursiv und nicht nur Text. Verweis auf eine Datei im selben Verzeichnis – einfach [[file:nachbar.org][beschreibung]]; auf eine Datei in einem anderen Verzeichnis (erst recht in einem anderen Git-Repository innerhalb des gemeinsamen Arbeitsverzeichnisses) – via Abkürzung root: ([[root:code/ads-back/datei.org::N][beschreibung]]), nicht ../../../ relativ zum aktuellen Verzeichnis. Die Abkürzung wird in .dir-locals.el im Wurzelverzeichnis des Arbeitsverzeichnisses deklariert (eval-Form mit locate-dominating-file) – falls noch nicht im Projekt vorhanden, erstellen.
• Kursiv /.../ – nur für Begriffe des Projektglossars (mit Übersetzung (/translation/) unmittelbar danach); bei erster Erwähnung des Begriffs in jeder Datei – [[file:.../spcfctn/glossary.org::*Begriff][...]] auf den entsprechenden Abschnitt, nicht Wiederholung der Definition.

Schritt 3 – Umbruch

Rufe für jeden bearbeiteten Absatz den echten fill-paragraph über emacsclient --eval auf, anstatt manuell umzubrechen (siehe entsprechende Regel in org-babel.md). Schreibe den Text des Absatzes in new_string/beim Erstellen der Datei als eine Zeile, ohne selbst Umbrüche zu erraten – dieser bestimmt ohnehin vollständig, was fill-paragraph tut.

Rufe (font-lock-ensure) VOR org-fill-paragraph auf: Ein im Headless-Modus über find-file-noselect geöffneter Puffer durchläuft keine Fontifizierung, daher sind Org-Links [[pfad][beschreibung]] noch nicht auf den kurzen, sichtbaren Text beschreibung „eingeklappt“ – ohne font-lock-ensure berechnet fill-paragraph den Umbruch basierend auf der langen Rohdarstellung des Links, nicht auf seiner sichtbaren Breite, und das Ergebnis weicht von dem ab, was M-q in einem lebendigen interaktiven Emacs liefert. Beispiel:

emacsclient --eval '
(let ((buf (find-file-noselect "PFAD/ZUR/DATEI.org")))
  (with-current-buffer buf
    (org-mode)
    (font-lock-ensure)
    (goto-char (point-min))
    (search-forward "eindeutiges Fragment des Absatzes")
    (org-fill-paragraph)
    (save-buffer)))
'