Lyx Compiler — KI-Integration (WP-KI-01 / WP-KI-02)

Zwei neue Compiler-Flags ermöglichen maschinenlesbare JSON-Ausgabe für KI-Agenten, Language-Server, IDEs und Build-Tooling: --ast-json exportiert den vollständigen Parser-AST, --error-json liefert strukturierte Fehler-Records statt Freitext.

→ Tools & Compiler · Compiler-Parameter

Reihenfolge im Compile-Ablauf:

• --ast-json / --ast-json-pretty: endet nach dem Parsen, vor der Semantic Analysis. Sema und Codegen laufen nicht.
• --error-json: läuft durch alle Passes; bei Sema-Fehler wird JSON ausgegeben und mit Exit 1 beendet. Bei Erfolg kein JSON-Output.

Implementiert in src/backend/ast_json.lyx (Klasse AstJson).

# Kompakter AST eines Lyx-Programms
lyxc main.lyx --ast-json > ast.json

# Lesbar formatiert (2-Leerzeichen-Einrückung)
lyxc main.lyx --ast-json-pretty > ast.json

# AST pipen und mit jq auswerten
lyxc main.lyx --ast-json | jq '.[].kind'
lyxc main.lyx --ast-json | jq '[.[] | select(.kind=="NK_FUNC_DECL") | .sval]'

Die Ausgabe ist ein JSON-Array der Top-Level-Knoten (Deklarationen). Jeder Knoten ist ein Objekt mit folgenden Feldern:

Sonderfall extern fn: Wenn ein NK_FUNC_DECL-Knoten keinen Body hat (extern-Deklaration), ist c2 = -1 und das Feld c3 entfällt. Stattdessen erscheint libSpan mit dem Integer-Wert des Library-Identifiers.

Für pub fn Add(a: int64, b: int64): int64 { return a + b; }:

[
  {
    "kind": "NK_FUNC_DECL",
    "kindId": 2,
    "line": 1,
    "col": 7,
    "sval": "Add",
    "pub": true,
    "c0": [
      {"kind": "NK_PARAM", "kindId": 3, "line": 1, "col": 11, "sval": "a",
       "c0": [{"kind": "NK_TYPE_NAME", "kindId": 60, "line": 1, "col": 14, "sval": "int64",
               "c0": null, "c1": null, "c2": null, "c3": null}],
       "c1": null, "c2": null, "c3": null},
      {"kind": "NK_PARAM", "kindId": 3, "line": 1, "col": 23, "sval": "b",
       "c0": [{"kind": "NK_TYPE_NAME", "kindId": 60, "line": 1, "col": 26, "sval": "int64",
               "c0": null, "c1": null, "c2": null, "c3": null}],
       "c1": null, "c2": null, "c3": null}
    ],
    "c1": [{"kind": "NK_TYPE_NAME", "kindId": 60, "line": 1, "col": 40, "sval": "int64",
            "c0": null, "c1": null, "c2": null, "c3": null}],
    "c2": null,
    "c3": [
      {"kind": "NK_BLOCK", "kindId": 20, "line": 1, "col": 47,
       "c0": [{"kind": "NK_RETURN", "kindId": 23, ...}],
       "c1": null, "c2": null, "c3": null}
    ]
  }
]

Vollständige Tabelle aller 116 Parser-Knotentypen:

Deklarationen

Statements

Ausdrücke

Typen

Pattern-Matching

LFD (Qt-UI-Builder)

Compiler-Direktiven

Jeder Parser-Knoten belegt 88 Bytes im internen nodes-Buffer:

Token-Records sind 40 Bytes; Zeile bei +32, Start-Position (für col) bei +8.

Die Klasse ist in src/backend/ast_json.lyx als pub type AstJson definiert:

Intern: Write-Batch-Buffer (4096 Bytes) reduziert sys_write-Aufrufe. Dezimal-Konvertierung über 24-Byte Scratch-Buffer.

Implementiert in src/error_collector.lyx (Klasse ErrorCollector) und in src/sema.lyx (errColl-Integration).

# Fehler als JSON ausgeben statt Freitext
lyxc main.lyx --error-json

# In CI: JSON in Datei speichern, Exit-Code auswerten
lyxc main.lyx --error-json > errors.json
echo "Exit: $?"   # 0 = ok, 1 = Sema-Fehler

# Mit jq: nur Fehler-Messages extrahieren
lyxc main.lyx --error-json | jq '.errors[].message'

{
  "errors": [
    {
      "errorId": "LYX-S0001",
      "category": "sema",
      "severity": "error",
      "message": "Unbekannter Bezeichner 'foo'",
      "locations": [{"file": "main.lyx", "line": 42, "col": 0}],
      "expected": null,
      "actual": null,
      "suggestion": null,
      "astPath": null
    },
    {
      "errorId": "LYX-W0001",
      "category": "sema",
      "severity": "warning",
      "message": "Variable 'x' wird nie gelesen",
      "locations": [{"file": "main.lyx", "line": 7, "col": 0}],
      "expected": null,
      "actual": null,
      "suggestion": null,
      "astPath": null
    }
  ],
  "errorCount": 1,
  "warningCount": 1
}

Toplevel-Felder:

Pro Eintrag:

Sequenznummern sind getrennt für Fehler (errSeq) und Warnungen (warnSeq) und beginnen bei 1. Fehler-IDs sind daher innerhalb einer Compiler-Sitzung eindeutig.

• –error-json aktiviert den ErrorCollector nur für die Semantic Analysis. Parse-Fehler werden weiterhin als Text ausgegeben (der Collector wird erst nach dem Parsen initialisiert).
• Bei Sema-Fehlern: JSON auf stdout, Exit-Code 1.
• Bei Erfolg (kein Fehler): kein JSON-Output, Compilation läuft normal weiter.
• col ist derzeit immer 0 (Spalten-Information aus sema nicht weitergeleitet).
• file ist null für das Root-Modul; Dateiname bei via import eingebundenen Modulen.

Die Klasse ist in src/error_collector.lyx als pub type ErrorCollector definiert:

Konstanten (pub con):

Error-Record-Layout (80 Bytes, flat buffer):

--ast-json und --error-json schließen sich aus: --ast-json beendet vor der Sema, daher gibt es keine Sema-Fehler zu sammeln. Für Linting mit strukturierter Ausgabe:

# Nur Sema-Prüfung mit JSON-Fehlerausgabe (kein Binary)
lyxc main.lyx --error-json --lint-only

# AST ausgeben und anschließend separat auf Fehler prüfen
lyxc main.lyx --ast-json > ast.json
lyxc main.lyx --error-json > errors.json || true

lyxc server.lyx --ast-json | jq -r '
  .[] | select(.kind == "NK_FUNC_DECL") | .sval
'

lyxc server.lyx --ast-json | jq -r '
  [.[] | select(.kind == "NK_FUNC_DECL" and .pub == true) | .sval] | join("\n")
'

lyxc main.lyx --error-json 2>/dev/null | jq '
  .errors[] | {
    file: .locations[0].file,
    line: .locations[0].line,
    severity: .severity,
    message: .message
  }
'

result=$(lyxc main.lyx --error-json 2>/dev/null)
echo $result | jq '"Fehler: \(.errorCount), Warnungen: \(.warningCount)"'

Letzte Aktualisierung: 2026-06-13