@untangle-code/parser-registry 0.0.0-stage → 0.1.1

package/src/languages/astgrep-backend/lang/swift.ts

@@ -0,0 +1,118 @@
+/**
+ * Swift (WP-86).
+ *
+ * WIE KOTLIN OHNE FELDNAMEN — mit denselben zwei Folgen (Signatur = erste
+ * Zeile, `IdentifierFact.role` immer `reference`); die Begruendung steht im
+ * Kopf von `kotlin.ts` und wird hier nicht wiederholt.
+ *
+ * ABBILDUNGEN: `class_declaration` traegt in Swift AUCH `struct`, `enum`,
+ * `actor` und `extension` — unterschieden ueber das Schluesselwortkind.
+ * `extension` -> `namespace`: eine Erweiterung ist kein neuer Typ, sondern ein
+ * benannter Ort fuer weitere Mitglieder eines bestehenden.
+ * `protocol_declaration` -> `interface`.
+ *
+ * ENTSCHEIDUNGSPUNKTE (spec.md §16.2/§16.3):
+ *   - `guard_statement` zaehlt als `guard` — es IST die vorzeitige Rueckkehr,
+ *     fuer die die Art gedacht ist (`guardKinds`).
+ *   - `switch_entry` ist ein `case`; der `default`-Arm zaehlt nicht
+ *     (`caseExcludeChildKinds: ["default_keyword"]`).
+ *   - `catch_block` zaehlt als `catch`.
+ *   - `??` zaehlt als `short_circuit`, nur erweitert.
+ *   - `try?`/`try!` zaehlen NICHT: anders als Rusts `?` kehren sie nicht
+ *     zurueck, sondern liefern `nil` beziehungsweise brechen ab. Der Zweig
+ *     entsteht am `catch_block`, und der wird gezaehlt.
+ *
+ * EINE MESSGRENZE, AUSDRUECKLICH: `@ast-grep/lang-swift` steht bei Version
+ * 0.0.8. Geprueft ist die Grammatik an der Golden-Datei dieses Pakets
+ * (0 Fehlerknoten); an grossen echten Swift-Projekten ist sie hier NICHT
+ * erprobt.
+ */
+import type { LanguageKindTable } from "../../shared/table-profile.js";
+import type { AstGrepLanguageSource } from "../adapter.js";
+
+export const SWIFT_SOURCE: AstGrepLanguageSource = {
+  languageName: "swift",
+  moduleName: "@ast-grep/lang-swift",
+};
+
+export const SWIFT_TABLE: LanguageKindTable = {
+  languageId: "swift",
+  extensions: [".swift"],
+  supportLevel: "deep",
+  commentKinds: ["comment", "multiline_comment"],
+  stringContainerKinds: ["line_string_literal", "multi_line_string_literal", "raw_string_literal"],
+  identifierLeafKinds: ["simple_identifier", "type_identifier", "self_expression"],
+  numberLeafKinds: ["integer_literal", "hex_literal", "oct_literal", "bin_literal", "real_literal"],
+  booleanLeafKinds: ["boolean_literal"],
+  nullLeafKinds: ["nil"],
+  scopes: [
+    {
+      kinds: ["class_declaration"],
+      scopeKind: "class",
+      nameKinds: ["type_identifier", "user_type"],
+      refine: [
+        { childKinds: ["enum"], scopeKind: "enum" },
+        { childKinds: ["extension"], scopeKind: "namespace" },
+      ],
+    },
+    {
+      kinds: ["protocol_declaration"],
+      scopeKind: "interface",
+      nameKinds: ["type_identifier"],
+    },
+    {
+      kinds: ["function_declaration", "protocol_function_declaration"],
+      scopeKind: "function",
+      nameKinds: ["simple_identifier"],
+    },
+    { kinds: ["init_declaration"], scopeKind: "constructor", nameKinds: ["init"] },
+    {
+      kinds: ["property_declaration"],
+      scopeKind: "property",
+      nameKindPath: ["pattern"],
+      nameKinds: ["simple_identifier"],
+      // Wie in Kotlin: `var i = 0` in einem Funktionsrumpf ist kein Symbol.
+      parentKinds: ["class_body", "protocol_body", "enum_class_body", "source_file"],
+    },
+  ],
+  decisions: {
+    ifKinds: ["if_statement"],
+    elseIfParentKinds: ["if_statement"],
+    guardKinds: ["guard_statement"],
+    loopKinds: ["for_statement", "while_statement", "repeat_while_statement"],
+    catchKinds: ["catch_block"],
+    ternaryKinds: ["ternary_expression"],
+    switchKinds: ["switch_statement"],
+    caseKinds: ["switch_entry"],
+    caseExcludeChildKinds: ["default_keyword"],
+    anonymousOperatorKinds: [
+      "conjunction_expression",
+      "disjunction_expression",
+      "nil_coalescing_expression",
+    ],
+    logicalAndOperators: ["&&"],
+    logicalOrOperators: ["||"],
+    shortCircuitOperators: ["??"],
+    jumpKinds: ["control_transfer_statement"],
+    blockKinds: ["statements"],
+  },
+  imports: {
+    kinds: ["import_declaration"],
+    pathKinds: ["identifier"],
+  },
+  calls: {
+    kinds: ["call_expression"],
+    memberKinds: ["navigation_expression"],
+    // Swift benutzt `call_expression` AUCH fuer Indexzugriffe: `items["a"]`
+    // waere sonst ein Aufruf von `items`. Nur ein Anhang, der mit `(` beginnt,
+    // ist ein Aufruf.
+    acceptCall: (node) => {
+      const last = node.children[node.children.length - 1];
+      return last !== undefined && last.text.trimStart().startsWith("(");
+    },
+  },
+  declarationParentKinds: [],
+  visibilityKinds: ["modifiers"],
+  visibilityWords: ["public", "internal", "fileprivate", "private", "open"],
+  fieldNames: ["name"],
+};

package/src/languages/astgrep-backend/languages.ts

@@ -0,0 +1,238 @@
+/**
+ * Die Sprachtabellen des ast-grep-Backends.
+ *
+ * Jede Sprache ist EINE Tabelle (`shared/table-profile.ts`) plus die Angabe,
+ * aus welchem npm-Paket ihre Grammatik kommt. Kein Motor, keine
+ * Fallunterscheidung, keine zweite Traversierung. Wer eine Sprache
+ * hinzufuegt, schreibt eine Tabelle wie die beiden hier und eine
+ * Registrierungszeile in `languages/index.ts` — sonst nichts.
+ *
+ * DIE KNOTENARTEN SIND NACHGESEHEN, NICHT GERATEN: jede Zeichenkette hier
+ * stammt aus einem echten Baum, den `adapter.test.ts` mit demselben Quelltext
+ * wieder erzeugt. Wer eine Art aendert, ohne den Test zu bewegen, sieht es
+ * sofort.
+ *
+ * SPRACHPAKETE WERDEN EINZELN AUFGENOMMEN. Die 22 Sprachpakete von ast-grep
+ * belegen zusammen 450 MB; eine Sammelabhaengigkeit waere respektlos gegen
+ * jeden, der nur Go analysieren will.
+ */
+import type { LanguageKindTable } from "../shared/table-profile.js";
+
+import type { AstGrepLanguageSource } from "./adapter.js";
+
+/** Sprachpakete, wie ast-grep sie kennt (Name) und npm sie liefert (Paket). */
+export const GO_SOURCE: AstGrepLanguageSource = {
+  languageName: "go",
+  moduleName: "@ast-grep/lang-go",
+};
+
+export const RUST_SOURCE: AstGrepLanguageSource = {
+  languageName: "rust",
+  moduleName: "@ast-grep/lang-rust",
+};
+
+/**
+ * Go.
+ *
+ * Zwei Eigenheiten stehen in der Tabelle statt in einer Sonderbehandlung:
+ *  - `else if` ist in Go ein `if_statement` DIREKT unter einem `if_statement`
+ *    (kein `else_clause` wie in JS/Rust) — `elseIfParentKinds` sagt das.
+ *  - Ein Rumpf ist `block > statement_list`; die Guard-Clause-Erkennung muss
+ *    durch BEIDE Huellen hindurch (`blockKinds`).
+ *  - Sichtbarkeit steht nicht im Baum, sondern im Namen: Go exportiert, was
+ *    mit einem Grossbuchstaben beginnt.
+ */
+export const GO_TABLE: LanguageKindTable = {
+  languageId: "go",
+  extensions: [".go"],
+  supportLevel: "deep",
+  commentKinds: ["comment"],
+  stringContainerKinds: ["interpreted_string_literal", "raw_string_literal", "rune_literal"],
+  identifierLeafKinds: [
+    "identifier",
+    "field_identifier",
+    "package_identifier",
+    "type_identifier",
+    "label_name",
+  ],
+  numberLeafKinds: ["int_literal", "float_literal", "imaginary_literal"],
+  booleanLeafKinds: ["true", "false"],
+  nullLeafKinds: ["nil"],
+  scopes: [
+    { kinds: ["function_declaration"], scopeKind: "function" },
+    {
+      kinds: ["method_declaration"],
+      scopeKind: "method",
+      qualifierField: "receiver",
+      qualifierNameKinds: ["type_identifier"],
+    },
+    { kinds: ["method_elem"], scopeKind: "method" },
+    {
+      kinds: ["type_spec"],
+      scopeKind: "type",
+      refine: [
+        { childKinds: ["struct_type"], scopeKind: "class" },
+        { childKinds: ["interface_type"], scopeKind: "interface" },
+      ],
+    },
+  ],
+  decisions: {
+    ifKinds: ["if_statement"],
+    elseIfParentKinds: ["if_statement"],
+    loopKinds: ["for_statement"],
+    switchKinds: ["expression_switch_statement", "type_switch_statement", "select_statement"],
+    // WP-86: `default_case` steht hier NICHT mehr. Gos `select` ist zwar kein
+    // C-`switch` — jeder `communication_case` ist ein echter, zur Laufzeit
+    // gewaehlter Zweig und zaehlt deshalb —, aber der `default`-Zweig ist in
+    // beiden Formen der Fall, der uebrig bleibt. Er eroeffnet keinen
+    // zusaetzlichen unabhaengigen Pfad: ein `switch` mit drei `case` und einem
+    // `default` hat DREI Entscheidungen, nicht vier. Vorher zaehlte er mit und
+    // jede Go-Datei mit `default` bekam eine zyklomatische Zahl zu viel.
+    caseKinds: ["expression_case", "type_case", "communication_case"],
+    binaryKinds: ["binary_expression"],
+    operatorField: "operator",
+    logicalAndOperators: ["&&"],
+    logicalOrOperators: ["||"],
+    jumpKinds: ["return_statement", "break_statement", "continue_statement", "goto_statement"],
+    blockKinds: ["block", "statement_list"],
+    consequenceField: "consequence",
+    alternativeField: "alternative",
+  },
+  imports: {
+    kinds: ["import_declaration"],
+    specKinds: ["import_spec"],
+    pathField: "path",
+    aliasField: "name",
+  },
+  calls: {
+    kinds: ["call_expression"],
+    functionField: "function",
+    argumentsField: "arguments",
+    memberKinds: ["selector_expression"],
+  },
+  declarationParentKinds: [
+    "function_declaration",
+    "method_declaration",
+    "method_elem",
+    "type_spec",
+    "const_spec",
+    "var_spec",
+    "import_spec",
+    "field_declaration",
+  ],
+  bodyField: "body",
+  isExported: (name) => /^\p{Lu}/u.test(name),
+  fieldNames: ["name"],
+};
+
+/**
+ * Rust.
+ *
+ * Auch hier stehen die Eigenheiten in der Tabelle:
+ *  - Sichtbarkeit ist ein Knoten (`visibility_modifier`), kein Namensmuster.
+ *  - `use a::b as c` und `use a::{b, c}` werden ausgepackt, sonst stuende der
+ *    ganze Ausdruck als "Pfad" im Ergebnis.
+ *  - `impl Counter { ... }` oeffnet einen Scope der Art `class`, damit
+ *    Methoden `Counter.bump` heissen statt bloss `bump`. Dass eine Datei
+ *    dadurch `Counter` zweimal fuehren kann (einmal `struct_item`, einmal
+ *    `impl_item`), ist gewollt: es sind zwei Quelltextstellen, und die
+ *    Scope-Kennungen unterscheiden sich ueber die Ordnungszahl.
+ *
+ * BEKANNTE GRENZE: eine `fn` in einem `impl`-Block wird als `function`
+ * gefuehrt, nicht als `method` — die Knotenart ist in beiden Faellen
+ * `function_item`, und die Tabelle entscheidet nach Knotenart. Das ist eine
+ * Ungenauigkeit in der Symbolart, keine im Bereich oder in der Metrik.
+ */
+export const RUST_TABLE: LanguageKindTable = {
+  languageId: "rust",
+  extensions: [".rs"],
+  supportLevel: "deep",
+  commentKinds: ["line_comment", "block_comment"],
+  stringContainerKinds: ["string_literal", "raw_string_literal", "char_literal"],
+  identifierLeafKinds: [
+    "identifier",
+    "type_identifier",
+    "field_identifier",
+    "primitive_type",
+    "self",
+    "shorthand_field_identifier",
+  ],
+  numberLeafKinds: ["integer_literal", "float_literal"],
+  booleanLeafKinds: ["true", "false"],
+  scopes: [
+    { kinds: ["function_item"], scopeKind: "function" },
+    {
+      kinds: ["function_signature_item"],
+      scopeKind: "method",
+      ancestorKinds: ["trait_item"],
+    },
+    { kinds: ["struct_item", "union_item"], scopeKind: "class" },
+    { kinds: ["impl_item"], scopeKind: "class", nameField: "type" },
+    { kinds: ["trait_item"], scopeKind: "interface" },
+    { kinds: ["enum_item"], scopeKind: "enum" },
+    { kinds: ["type_item"], scopeKind: "type" },
+    { kinds: ["mod_item"], scopeKind: "namespace" },
+  ],
+  decisions: {
+    ifKinds: ["if_expression"],
+    elseIfParentKinds: ["else_clause"],
+    loopKinds: ["for_expression", "while_expression", "loop_expression"],
+    switchKinds: ["match_expression"],
+    // WP-86: gezaehlt wird das MUSTER, nicht der Arm — nur so ist der
+    // Auffangarm `_ => ...` zu erkennen (sein `match_pattern` besteht genau
+    // aus dem `_`). Er ist Rusts `default` und zaehlt nicht;
+    // `Some(_) => ...` zaehlt dagegen, weil es wirklich nur EINEN Fall abdeckt.
+    caseKinds: ["match_pattern"],
+    caseExcludeFirstChildText: "_",
+    // `Some(1) | Some(2)` ist eine Musteralternative — `DecisionKind`
+    // `pattern_alternative` existiert genau dafuer.
+    patternAlternativeKinds: ["or_pattern"],
+    // WP-86: der `?`-OPERATOR IST KONTROLLFLUSS — er kehrt bei `Err` sofort
+    // zurueck. Gezaehlt wird er KONSERVATIV als `short_circuit`, also nur
+    // ERWEITERT (spec.md §16.3), nicht klassisch (§16.2): `?` ist in
+    // idiomatischem Rust so haeufig wie ein Semikolon, und klassisch
+    // mitgezaehlt bekaeme jede Funktion, die drei Aufrufe weiterreicht,
+    // dieselbe Zahl wie eine mit drei `if`. Verschwiegen wird er nicht — die
+    // erweiterte Zahl zeigt ihn.
+    shortCircuitKinds: ["try_expression"],
+    binaryKinds: ["binary_expression"],
+    operatorField: "operator",
+    logicalAndOperators: ["&&"],
+    logicalOrOperators: ["||"],
+    jumpKinds: ["return_expression", "break_expression", "continue_expression"],
+    blockKinds: ["block"],
+    consequenceField: "consequence",
+    alternativeField: "alternative",
+  },
+  imports: {
+    kinds: ["use_declaration"],
+    pathField: "argument",
+    unwrap: [
+      { kinds: ["use_as_clause"], pathField: "path", aliasField: "alias" },
+      { kinds: ["scoped_use_list"], pathField: "path", namesField: "list" },
+    ],
+  },
+  calls: {
+    kinds: ["call_expression", "macro_invocation"],
+    functionField: "function",
+    argumentsField: "arguments",
+    memberKinds: ["field_expression", "scoped_identifier"],
+  },
+  declarationParentKinds: [
+    "function_item",
+    "function_signature_item",
+    "struct_item",
+    "enum_item",
+    "trait_item",
+    "mod_item",
+    "type_item",
+    "const_item",
+    "static_item",
+    "field_declaration",
+    "parameter",
+  ],
+  visibilityKinds: ["visibility_modifier"],
+  bodyField: "body",
+  isExported: (_name, node) => node.children.some((child) => child.type === "visibility_modifier"),
+  fieldNames: ["name", "type"],
+};

package/src/languages/astgrep-backend/napi.ts

@@ -0,0 +1,261 @@
+/**
+ * Der Zugang zu `@ast-grep/napi` — traege geladen, EINMAL registriert, und
+ * ohne stillen Ausfall.
+ *
+ * DREI EIGENHEITEN DIESER BIBLIOTHEK BESTIMMEN DIESE DATEI:
+ *
+ *  1. `registerDynamicLanguage` WIRKT GENAU EINMAL. Der zweite Aufruf wirft
+ *     nicht — er registriert schweigend nichts, und jeder spaetere
+ *     `parse("<sprache>", ...)` scheitert dann mit "not supported in napi".
+ *     Also: EINE Registrierung, aufgeschoben bis zum ersten Parse einer
+ *     dynamischen Sprache, mit ALLEN Sprachen, deren Adapter bis dahin
+ *     angemeldet wurden. Wer danach noch eine Sprache anmeldet, bekommt einen
+ *     Fehler statt einer stillen Wirkungslosigkeit ({@link registerAstGrepLanguage}).
+ *
+ *  2. EIN FEHLENDER PREBUILD SCHEITERT BEI DER INSTALLATION STILL. Die
+ *     `postinstall` der `@ast-grep/lang-*`-Pakete faengt den Baufehler und
+ *     endet mit Exit 0; npm/pnpm melden Erfolg. Erst `require("<paket>")
+ *     .libraryPath` wirft — ein Getter. Die Sprachpakete liefern Prebuilds nur
+ *     fuer macOS x64/arm64, Linux x64/arm64 (glibc) und Windows x64: auf
+ *     Alpine (musl), Windows ARM64 und Windows ia32 gibt es KEINEN. Deshalb
+ *     wird jede Sprache einzeln geprueft, der Ausfall benannt festgehalten
+ *     ({@link astGrepLanguageStatus}) und beim Parsen als
+ *     `grammar_unavailable` gemeldet — woraus der Aufrufer einen
+ *     Skip-Ledger-Eintrag mit Grund baut (E4). Kein Adapter tut so, als haette
+ *     er geparst.
+ *
+ *  3. `SgNode#id()` IST ADRESSABGELEITET. Innerhalb eines Prozesses taugt es
+ *     zum Vergleich zweier Knoten, ueber Prozesse hinweg zu gar nichts. Es
+ *     darf deshalb NIE in Ergebnisdaten stehen; genutzt wird es einzig in
+ *     `syntax.ts`, um den Feldnamen des aktuellen Knotens zu bestimmen.
+ *
+ * Der Kern (`@ast-grep/napi`) bringt TypeScript, TSX, JavaScript, HTML und CSS
+ * fest eingebaut mit. Wir benutzen davon NICHTS: die JS/TS-Familie laeuft
+ * weiter ueber tree-sitter (Begruendung in `README.md` dieses Verzeichnisses).
+ */
+import { createRequire } from "node:module";
+
+import { AdapterParseError } from "@untangle-code/domain";
+
+const require = createRequire(import.meta.url);
+
+/** Die Knotenform von ast-grep, auf die Teilmenge reduziert, die wir benutzen. */
+export interface SgNode {
+  id(): number;
+  kind(): string;
+  text(): string;
+  range(): { start: SgPos; end: SgPos };
+  isLeaf(): boolean;
+  isNamed(): boolean;
+  children(): SgNode[];
+  namedChildren(): SgNode[];
+  parent(): SgNode | null;
+  prev(): SgNode | null;
+  field(name: string): SgNode | null;
+}
+
+export interface SgPos {
+  /** 0-basierte Zeile. */
+  line: number;
+  /** 0-basierte Spalte, in UTF-16-Einheiten. */
+  column: number;
+  /**
+   * ENTGEGEN der Typdefinition von ast-grep ("byte offset") ein
+   * UTF-16-Offset — nachgemessen an Umlauten und Emoji. Die Umrechnung in
+   * Bytes macht ausschliesslich die `ByteOffsetTable`.
+   */
+  index: number;
+}
+
+export interface SgRoot {
+  root(): SgNode;
+}
+
+interface AstGrepModule {
+  parse(lang: string, source: string): SgRoot;
+  registerDynamicLanguage(langs: Record<string, LanguageRegistration>): void;
+}
+
+interface LanguageRegistration {
+  libraryPath: string;
+  extensions: string[];
+  languageSymbol?: string;
+  metaVarChar?: string;
+  expandoChar?: string;
+}
+
+/** Wie es einer angemeldeten Sprache ergangen ist. */
+export type AstGrepLanguageStatus =
+  | { readonly state: "pending" }
+  | { readonly state: "available" }
+  | { readonly state: "unavailable"; readonly reason: string };
+
+interface PendingLanguage {
+  /** Name, unter dem ast-grep die Sprache kennt (auch der `parse`-Parameter). */
+  languageName: string;
+  /** npm-Paket mit Prebuild und Registrierungsangaben. */
+  moduleName: string;
+}
+
+const pending = new Map<string, PendingLanguage>();
+const status = new Map<string, AstGrepLanguageStatus>();
+let registrationDone = false;
+let cachedModule: AstGrepModule | undefined;
+
+/**
+ * Meldet eine Sprache fuer die EINE spaetere Registrierung an. Kostet nichts:
+ * kein `require`, kein Laden einer Grammatik — genau wie die traege
+ * Registrierung der tree-sitter-Adapter (`registry.ts`).
+ */
+export function registerAstGrepLanguage(languageName: string, moduleName: string): void {
+  const already = pending.get(languageName);
+  if (already !== undefined && already.moduleName === moduleName) {
+    // DIESELBE Sprache aus DEMSELBEN Paket ein zweites Mal anzumelden ist
+    // harmlos und passiert im Normalbetrieb: `createParserRegistry()` baut
+    // jedes Mal frische Adapter, und ein Prozess darf mehr als eine Registry
+    // haben (die CLI tut es je Befehl). Der Eintrag ist bereits da, die
+    // Registrierung enthaelt die Sprache also — hier ist NICHTS zu tun und
+    // nichts zu melden. Ohne diese Ausnahme warf die zweite Registry, obwohl
+    // ihre Sprachen samt und sonders verfuegbar waren (WP-86).
+    return;
+  }
+  if (registrationDone) {
+    // Nach der Registrierung ist die Liste unveraenderlich (Eigenheit 1 im
+    // Modulkopf). Ein spaeterer Eintrag waere wirkungslos — und wirkungslos
+    // und unbemerkt ist genau das, was E4 verbietet.
+    throw new AdapterParseError(
+      "grammar_unavailable",
+      `Sprache "${languageName}" was registered after the one-time ast-grep registration. ` +
+        `registerDynamicLanguage only takes effect on its first call; the language would silently remain unavailable.`,
+    );
+  }
+  pending.set(languageName, { languageName, moduleName });
+  status.set(languageName, { state: "pending" });
+}
+
+function loadModule(): AstGrepModule {
+  if (cachedModule === undefined) {
+    cachedModule = require("@ast-grep/napi") as AstGrepModule;
+  }
+  return cachedModule;
+}
+
+/**
+ * Fuehrt die EINE Registrierung aus (idempotent). Jede Sprache, deren Paket
+ * fehlt oder deren Prebuild nicht gebaut wurde, faellt hier mit BENANNTEM
+ * Grund heraus, statt erst beim Parsen unverstaendlich zu scheitern.
+ */
+function ensureRegistered(): AstGrepModule {
+  const napi = loadModule();
+  if (registrationDone) return napi;
+  registrationDone = true;
+
+  const registrations: Record<string, LanguageRegistration> = {};
+  for (const language of pending.values()) {
+    try {
+      const registration = require(language.moduleName) as LanguageRegistration;
+      // `libraryPath` ist ein GETTER, der genau dann wirft, wenn weder ein
+      // Prebuild noch ein selbst gebauter Parser da ist. Der Zugriff hier ist
+      // die Pruefung, nicht ein beilaeufiges Lesen.
+      const libraryPath = registration.libraryPath;
+      registrations[language.languageName] = { ...registration, libraryPath };
+    } catch (error) {
+      status.set(language.languageName, {
+        state: "unavailable",
+        reason: `Package "${language.moduleName}" could not be loaded or has no built parser for ${process.platform}/${process.arch}: ${errorText(error)}`,
+      });
+    }
+  }
+
+  if (Object.keys(registrations).length > 0) {
+    try {
+      napi.registerDynamicLanguage(registrations);
+      for (const name of Object.keys(registrations)) {
+        status.set(name, { state: "available" });
+      }
+    } catch (error) {
+      for (const name of Object.keys(registrations)) {
+        status.set(name, {
+          state: "unavailable",
+          reason: `registerDynamicLanguage failed: ${errorText(error)}`,
+        });
+      }
+    }
+  }
+
+  return napi;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Zustand einer angemeldeten Sprache — fuer `doctor` und fuer Tests. Loest die
+ * Registrierung NICHT aus: wer nur fragt, soll keine Grammatik laden.
+ */
+export function astGrepLanguageStatus(languageName: string): AstGrepLanguageStatus | null {
+  return status.get(languageName) ?? null;
+}
+
+/** Alle angemeldeten Sprachen mit ihrem Zustand (Reihenfolge der Anmeldung). */
+export function astGrepLanguageStates(): { languageName: string; status: AstGrepLanguageStatus }[] {
+  return [...pending.keys()].map((languageName) => ({
+    languageName,
+    status: status.get(languageName) ?? { state: "pending" },
+  }));
+}
+
+/**
+ * Parst Quelltext mit ast-grep. Loest beim ERSTEN Aufruf die einmalige
+ * Registrierung aus (siehe Modulkopf) und wirft einen benannten
+ * `AdapterParseError`, wenn genau diese Sprache nicht verfuegbar ist.
+ */
+export function astGrepParse(languageName: string, source: string): SgNode {
+  let napi: AstGrepModule;
+  try {
+    napi = ensureRegistered();
+  } catch (error) {
+    throw new AdapterParseError(
+      "grammar_unavailable",
+      `Could not load @ast-grep/napi: ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+
+  const languageStatus = status.get(languageName);
+  if (languageStatus === undefined) {
+    throw new AdapterParseError(
+      "grammar_unavailable",
+      `Sprache "${languageName}" is not registered with this ast-grep backend.`,
+    );
+  }
+  if (languageStatus.state === "unavailable") {
+    throw new AdapterParseError(
+      "grammar_unavailable",
+      `Sprache "${languageName}" is unavailable: ${languageStatus.reason}`,
+    );
+  }
+
+  try {
+    return napi.parse(languageName, source).root();
+  } catch (error) {
+    throw new AdapterParseError(
+      "parser_internal_error",
+      `ast-grep could not parse "${languageName}" could not be parsed: ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * Nur fuer Tests: setzt Anmeldungen und Registrierungszustand zurueck. Der
+ * NATIVE Zustand laesst sich damit NICHT zuruecksetzen — `registerDynamicLanguage`
+ * bleibt im Prozess wirksam. Ein Test, der eine zweite, andere Registrierung
+ * erzwingen will, braucht einen eigenen Prozess.
+ */
+export function resetAstGrepRegistrationForTests(): void {
+  pending.clear();
+  status.clear();
+  registrationDone = false;
+}