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

package/src/languages/shared/node-kinds.ts

@@ -0,0 +1,153 @@
+/**
+ * tree-sitter node `.type` string constants shared by the JS/TS grammar
+ * family (tree-sitter-javascript, tree-sitter-typescript `typescript` and
+ * `tsx` dialects). Verified against each grammar's `src/node-types.json`
+ * (see package README, "Grammatik-Wahl").
+ *
+ * A set may list a node kind that a particular dialect's grammar never
+ * actually produces (e.g. `public_field_definition` never appears in a
+ * plain JavaScript tree) — that is harmless: `Set#has` on a type string the
+ * grammar never emits simply never matches.
+ */
+
+/**
+ * Nodes whose entire subtree collapses to ONE operand/literal token (do not
+ * recurse into children). `template_string` is deliberately EXCLUDED here
+ * even though it is a literal: `${expr}` interpolations can contain calls,
+ * identifiers and decisions that must still be walked (verified against the
+ * grammar: a `template_string` node's children are `` ` ``, `string_fragment`,
+ * `escape_sequence` and `template_substitution` — see `TEMPLATE_TEXT_LEAF_TYPES`
+ * below, and the `` ` ``/`${` delimiters folded into `IGNORED_PUNCTUATION_TYPES`,
+ * for how its non-substitution parts are classified instead).
+ */
+export const LITERAL_CONTAINER_STOP_TYPES: ReadonlySet<string> = new Set(["string", "regex"]);
+
+/** Static-text leaves inside a `template_string` (its non-`${}` content) — operands. */
+export const TEMPLATE_TEXT_LEAF_TYPES: ReadonlySet<string> = new Set([
+  "string_fragment",
+  "escape_sequence",
+]);
+
+/** Leaf node types that are identifier occurrences (operands). */
+export const IDENTIFIER_LEAF_TYPES: ReadonlySet<string> = new Set([
+  "identifier",
+  "property_identifier",
+  "type_identifier",
+  "private_property_identifier",
+  "shorthand_property_identifier",
+  "shorthand_property_identifier_pattern",
+  "statement_identifier",
+  "this",
+  "super",
+]);
+
+/** Leaf node types that are simple (non-container) literals. */
+export const SIMPLE_LITERAL_LEAF_TYPES: ReadonlySet<string> = new Set([
+  "number",
+  "true",
+  "false",
+  "null",
+  "undefined",
+]);
+
+/** Punctuation leaves that count neither as operator nor operand (pure structure). */
+export const IGNORED_PUNCTUATION_TYPES: ReadonlySet<string> = new Set([
+  "(",
+  ")",
+  "{",
+  "}",
+  "[",
+  "]",
+  ",",
+  ";",
+  ".",
+  "`",
+  "${",
+]);
+
+/** Function-shaped scope node types (produce ExtractedSymbol kind "function"). */
+export const FUNCTION_LIKE_TYPES: ReadonlySet<string> = new Set([
+  "function_declaration",
+  "generator_function_declaration",
+  "function_expression",
+  "generator_function",
+  "arrow_function",
+]);
+
+export const METHOD_TYPE = "method_definition";
+export const CLASS_TYPES: ReadonlySet<string> = new Set([
+  "class_declaration",
+  "abstract_class_declaration",
+  "class",
+]);
+export const INTERFACE_TYPE = "interface_declaration";
+export const TYPE_ALIAS_TYPE = "type_alias_declaration";
+export const ENUM_TYPE = "enum_declaration";
+export const NAMESPACE_TYPE = "internal_module";
+export const FIELD_TYPES: ReadonlySet<string> = new Set([
+  "field_definition",
+  "public_field_definition",
+]);
+
+/**
+ * `static { ... }` initialization block inside a class body. NOT a scope
+ * opener (it declares no symbol and has no name to build a stable scope id
+ * from) — but it carries executable content, so `chunks.ts` models it as an
+ * explicit child region of its class so its bytes become a real content
+ * chunk instead of falling through the chunker's member walk (spec.md §8.4:
+ * no silent data loss).
+ */
+export const CLASS_STATIC_BLOCK_TYPE = "class_static_block";
+
+/** All node types that open a new symbol scope (superset across dialects). */
+export const SCOPE_OPENING_TYPES: ReadonlySet<string> = new Set([
+  ...FUNCTION_LIKE_TYPES,
+  METHOD_TYPE,
+  ...CLASS_TYPES,
+  INTERFACE_TYPE,
+  TYPE_ALIAS_TYPE,
+  ENUM_TYPE,
+  NAMESPACE_TYPE,
+  ...FIELD_TYPES,
+]);
+
+/** Decision-bearing node types (spec.md §16.2-16.3). */
+export const IF_STATEMENT = "if_statement";
+export const LOOP_TYPES: ReadonlySet<string> = new Set([
+  "for_statement",
+  "for_in_statement",
+  "while_statement",
+  "do_statement",
+]);
+export const CATCH_CLAUSE = "catch_clause";
+export const TERNARY_EXPRESSION = "ternary_expression";
+export const SWITCH_CASE = "switch_case";
+export const SWITCH_STATEMENT = "switch_statement";
+export const BINARY_EXPRESSION = "binary_expression";
+export const AUGMENTED_ASSIGNMENT = "augmented_assignment_expression";
+
+/** Jump statements used by the guard-clause heuristic. */
+export const JUMP_STATEMENT_TYPES: ReadonlySet<string> = new Set([
+  "return_statement",
+  "throw_statement",
+  "break_statement",
+  "continue_statement",
+]);
+
+export const COMMENT_TYPE = "comment";
+export const DECORATOR_TYPE = "decorator";
+
+/** Import/export related node types (architecture.md §6.5, spec.md §14.2). */
+export const IMPORT_STATEMENT = "import_statement";
+export const IMPORT_CLAUSE = "import_clause";
+export const IMPORT_REQUIRE_CLAUSE = "import_require_clause"; // TS only: `import x = require(...)`
+export const NAMED_IMPORTS = "named_imports";
+export const NAMESPACE_IMPORT = "namespace_import";
+export const IMPORT_SPECIFIER = "import_specifier";
+export const EXPORT_STATEMENT = "export_statement";
+export const EXPORT_CLAUSE = "export_clause";
+export const EXPORT_SPECIFIER = "export_specifier";
+export const CALL_EXPRESSION = "call_expression";
+export const NEW_EXPRESSION = "new_expression";
+export const MEMBER_EXPRESSION = "member_expression";
+export const IMPORT_KEYWORD_NODE = "import"; // the bare `import` token used in `import(...)` dynamic import

package/src/languages/shared/node-utils.ts

@@ -0,0 +1,120 @@
+import type { SourceRange } from "@untangle-code/domain";
+
+import type { ByteOffsetTable } from "../../text/byte-offset-table.js";
+
+import type { SyntaxNode, SyntaxCursor } from "./syntax.js";
+
+/** Per-file context threaded through the analysis walk. */
+export interface FileTextContext {
+  sourceText: string;
+  byteTable: ByteOffsetTable;
+}
+
+export function rangeOf(node: SyntaxNode, ctx: FileTextContext): SourceRange {
+  return {
+    startLine: node.startPosition.row + 1,
+    endLine: node.endPosition.row + 1,
+    startByte: ctx.byteTable.toByteOffset(node.startIndex),
+    endByte: ctx.byteTable.toByteOffset(node.endIndex),
+  };
+}
+
+/**
+ * `rangeOf` for a cursor position — identical result, but WITHOUT
+ * materializing a `SyntaxNode` wrapper. `TreeCursor` exposes the same four
+ * values (`startPosition`, `endPosition`, `startIndex`, `endIndex`) with the
+ * same UTF-16 index convention as `SyntaxNode`, so the two functions are
+ * interchangeable per node (WP-95).
+ */
+export function rangeOfCursor(cursor: SyntaxCursor, ctx: FileTextContext): SourceRange {
+  return {
+    startLine: cursor.startPosition.row + 1,
+    endLine: cursor.endPosition.row + 1,
+    startByte: ctx.byteTable.toByteOffset(cursor.startIndex),
+    endByte: ctx.byteTable.toByteOffset(cursor.endIndex),
+  };
+}
+
+/**
+ * Kommentarknoten enden semantisch vor dem Zeilenumbruch. Manche Grammatiken
+ * halten sich daran nicht: Rusts `///` und `//!` reichen bis zum Anfang der
+ * Folgezeile. Da `SourceRange.endLine` INKLUSIV ist, wuerde diese Codezeile
+ * sonst als Kommentar gelten und aus SLOC herausfallen (WP-236).
+ */
+function withoutTrailingLineBreak(
+  range: SourceRange,
+  text: string,
+  endIndex: number,
+  ctx: FileTextContext,
+): SourceRange {
+  const suffixLength = text.endsWith("\r\n")
+    ? 2
+    : text.endsWith("\n") || text.endsWith("\r")
+      ? 1
+      : 0;
+  if (suffixLength === 0) return range;
+  return {
+    ...range,
+    endLine: Math.max(range.startLine, range.endLine - 1),
+    endByte: ctx.byteTable.toByteOffset(endIndex - suffixLength),
+  };
+}
+
+/** `rangeOf`, mit der sprachuebergreifenden Zeilenkommentar-Normalisierung. */
+export function commentRangeOf(node: SyntaxNode, ctx: FileTextContext): SourceRange {
+  return withoutTrailingLineBreak(rangeOf(node, ctx), node.text, node.endIndex, ctx);
+}
+
+/** Cursor-Fassung von {@link commentRangeOf}, ohne einen Knotenwrapper zu bauen. */
+export function commentRangeOfCursor(cursor: SyntaxCursor, ctx: FileTextContext): SourceRange {
+  return withoutTrailingLineBreak(
+    rangeOfCursor(cursor, ctx),
+    cursor.nodeText,
+    cursor.endIndex,
+    ctx,
+  );
+}
+
+/** Union of two ranges — the smallest range containing both. */
+export function unionRange(a: SourceRange, b: SourceRange): SourceRange {
+  return {
+    startLine: Math.min(a.startLine, b.startLine),
+    endLine: Math.max(a.endLine, b.endLine),
+    startByte: Math.min(a.startByte, b.startByte),
+    endByte: Math.max(a.endByte, b.endByte),
+  };
+}
+
+/** Strips surrounding string quotes (`"`, `'`, `` ` ``) from raw source text, when present. */
+export function unquote(text: string): string {
+  if (text.length >= 2) {
+    const first = text[0];
+    const last = text[text.length - 1];
+    if ((first === '"' || first === "'" || first === "`") && first === last) {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+/** Finds the nearest ancestor (excluding `node` itself) whose type is in `types`. */
+export function closestAncestorOfType(
+  node: SyntaxNode,
+  types: ReadonlySet<string>,
+): SyntaxNode | null {
+  let current = node.parent;
+  while (current !== null) {
+    if (types.has(current.type)) return current;
+    current = current.parent;
+  }
+  return null;
+}
+
+/** All direct children of `node` whose type equals `type` (named or anonymous). */
+export function directChildrenOfType(node: SyntaxNode, type: string): SyntaxNode[] {
+  return node.children.filter((child) => child.type === type);
+}
+
+export function hasDirectChildOfType(node: SyntaxNode, type: string): boolean {
+  return node.children.some((child) => child.type === type);
+}

package/src/languages/shared/parse-diagnostics.ts

@@ -0,0 +1,125 @@
+/**
+ * Parse-quality diagnostics (spec.md §7.3): counts and reports tree-sitter
+ * `ERROR` and "missing" nodes, and classifies overall `ParseQuality`.
+ *
+ * Threshold choice (documented WP-06 decision, no normative value given by
+ * spec.md/architecture.md): `failed` is reserved for trees where at least
+ * half of all nodes are broken — tree-sitter's error recovery almost always
+ * produces SOME usable tree, even for badly broken input, so a small
+ * absolute count of error/missing nodes is treated as `partial`
+ * (spec.md §7.3: "AST nutzbar, aber mit Fehlerknoten"), while a
+ * majority-broken tree is treated as unusable (`failed`, `ast: null` per
+ * domain `ParseResult` doc).
+ *
+ * TRAVERSIERUNG (WP-95): ueber die Cursor-API statt ueber `node.children` —
+ * derselbe Grund wie in `engine.ts` und `fingerprint.ts`. Die
+ * BESUCHSREIHENFOLGE ist absichtlich unveraendert geblieben: der fruehere
+ * Stapel (`stack.pop()` nach `push` aller Kinder) lief Vorordnung mit
+ * UMGEKEHRTER Kindfolge, und genau die stellen `gotoLastChild` /
+ * `gotoPreviousSibling` nach. Wer hier auf die natuerliche Kindfolge
+ * umstellt, aendert die Reihenfolge von `ParseDiagnostic[]` — sichtbar in
+ * jedem Bericht, der die erste Diagnose zeigt.
+ */
+import type { ParseDiagnostic, ParseQuality } from "@untangle-code/domain";
+
+import type { FileTextContext } from "./node-utils.js";
+import { rangeOfCursor } from "./node-utils.js";
+import type { SyntaxNode } from "./syntax.js";
+
+const ERROR_NODE_TYPE = "ERROR";
+const FAILED_RATIO_THRESHOLD = 0.5;
+
+/**
+ * Woher die Angabe "fehlender Knoten" stammt.
+ *
+ * `measured` — tree-sitter meldet `ts_node_is_missing`, ein Messwert der
+ * Fehlerkorrektur. `heuristic` — ast-grep hat dazu kein Gegenstueck; dort ist
+ * es ein Blatt der Breite null (siehe `languages/astgrep-backend/syntax.ts`).
+ * Der Unterschied gehoert in die DIAGNOSE, nicht in eine Fussnote: wer
+ * `missing_node_count` liest, muss wissen, ob die Zahl gemessen oder
+ * geschaetzt ist (E4).
+ */
+export type MissingNodeEvidence = "measured" | "heuristic";
+
+export interface ParseDiagnosticsResult {
+  parseQuality: ParseQuality;
+  diagnostics: ParseDiagnostic[];
+  errorNodeCount: number;
+  missingNodeCount: number;
+}
+
+export function collectParseDiagnostics(
+  root: SyntaxNode,
+  ctx: FileTextContext,
+  missingNodeEvidence: MissingNodeEvidence = "measured",
+): ParseDiagnosticsResult {
+  const diagnostics: ParseDiagnostic[] = [];
+  let errorNodeCount = 0;
+  let missingNodeCount = 0;
+  let totalNodeCount = 0;
+
+  // Iterativ, nicht rekursiv: ein Syntaxbaum kann tausende Ebenen tief sein
+  // (eine lange `a || b || c ...`-Kette genuegt), und ein Aufrufstapel darf
+  // daran nicht zerbrechen.
+  const cursor = root.walk();
+  let depth = 0;
+  for (;;) {
+    totalNodeCount += 1;
+    const nodeType = cursor.nodeType;
+
+    if (cursor.nodeIsMissing) {
+      missingNodeCount += 1;
+      diagnostics.push({
+        severity: "error",
+        kind: "missing_node",
+        message:
+          missingNodeEvidence === "measured"
+            ? `Missing "${nodeType}" node`
+            : `Missing "${nodeType}" node (heuristically detected as a zero-width node; ` +
+              `ast-grep has no nodeIsMissing API)`,
+        range: rangeOfCursor(cursor, ctx),
+      });
+    } else if (nodeType === ERROR_NODE_TYPE) {
+      // Frueher stand hier zusaetzlich `|| node.isError`. Das ist dieselbe
+      // Bedingung: `ts_node_is_error` prueft auf das eingebaute Fehlersymbol,
+      // und dessen Typname IST "ERROR" — ein eingebautes Symbol wird nie
+      // aliasiert. Der Cursor bietet kein `nodeIsError`, wohl aber `nodeType`.
+      errorNodeCount += 1;
+      diagnostics.push({
+        severity: "error",
+        kind: "error_node",
+        message: `Unexpected syntax near "${cursor.nodeText.slice(0, 40)}"`,
+        range: rangeOfCursor(cursor, ctx),
+      });
+    }
+
+    if (cursor.gotoLastChild()) {
+      depth += 1;
+      continue;
+    }
+    while (!cursor.gotoPreviousSibling()) {
+      if (depth === 0) {
+        return finish(diagnostics, errorNodeCount, missingNodeCount, totalNodeCount);
+      }
+      cursor.gotoParent();
+      depth -= 1;
+    }
+  }
+}
+
+function finish(
+  diagnostics: ParseDiagnostic[],
+  errorNodeCount: number,
+  missingNodeCount: number,
+  totalNodeCount: number,
+): ParseDiagnosticsResult {
+  const brokenRatio = totalNodeCount > 0 ? (errorNodeCount + missingNodeCount) / totalNodeCount : 0;
+  const parseQuality: ParseQuality =
+    errorNodeCount === 0 && missingNodeCount === 0
+      ? "complete"
+      : brokenRatio >= FAILED_RATIO_THRESHOLD
+        ? "failed"
+        : "partial";
+
+  return { parseQuality, diagnostics, errorNodeCount, missingNodeCount };
+}

package/src/languages/shared/parse-limits.ts

@@ -0,0 +1,147 @@
+/**
+ * Eingabepuffer und Groessengrenze fuer die native tree-sitter-Bindung
+ * (WP-215).
+ *
+ * DER DEFEKT: `Parser#parse(text)` reicht den Quelltext ueber eine
+ * Rueckruffunktion an die native Seite; die Bindung kopiert den
+ * zurueckgegebenen Abschnitt in einen Puffer FESTER Groesse. Ohne
+ * `options.bufferSize` ist dieser Puffer 32 KiB gross (`tree-sitter@0.21.1`,
+ * `binding.cc`). Eine Datei ueber 32 KiB passt nicht hinein und die Bindung
+ * wirft `Invalid argument` — ohne Zeile, ohne Spalte, ohne Hinweis auf die
+ * Groesse. Auf dem eigenen Repository scheiterten daran ACHT Dateien:
+ * `packages/complexity/src/scope-aggregate.ts` (31.246 B) wurde noch
+ * gerechnet, `packages/search/src/regex-safety.ts` (33.871 B) nicht mehr.
+ *
+ * DIE GEGENMASSNAHME: `bufferSize` proportional zur Eingabelaenge uebergeben.
+ * Gemessen im Paketkontext an `regex-safety.ts` (33.806 Zeichen / 33.871 Bytes):
+ *
+ *     ohne bufferSize:  FEHLER — Invalid argument
+ *     mit bufferSize:   OK, root program | Kinder 66 | hasError false
+ *
+ * WARUM EINE OBERGRENZE NOETIG IST: `bufferSize` waechst mit der Datei, der
+ * Syntaxbaum ebenfalls — nur schneller. Gemessen in ISOLIERTEN Prozessen
+ * (`maxRSS` aus `process.resourceUsage()`, tree-sitter-typescript, Node 26.7.0,
+ * darwin/arm64), erst das reine `parse()`:
+ *
+ *     Bytes        parse    Spitzen-RSS
+ *      1.082.765     62 ms    112 MiB
+ *      4.213.735    268 ms    252 MiB
+ *      8.396.927    495 ms    441 MiB
+ *     16.803.534    964 ms    683 MiB
+ *     33.576.525   3136 ms   1087 MiB
+ *     67.141.068   3814 ms   1545 MiB
+ *
+ * `parse()` allein ist aber NICHT, was der Aufrufer bezahlt. Der Adapter legt
+ * anschliessend `analyzeTree` darueber und materialisiert JS-Wrapper fuer jeden
+ * Knoten (bei 1 MiB Quelltext sind das 216.406 Knoten). Dieselbe Messung ueber
+ * die VOLLE Strecke `parse()` + `computeComplexity()`:
+ *
+ *     Bytes        gesamt    Spitzen-RSS   Scopes
+ *      1.082.765    8.899 ms    276 MiB     1.162
+ *      2.126.275   13.227 ms    389 MiB     2.280
+ *      4.213.735   22.990 ms    585 MiB     4.516
+ *      5.259.533   32.394 ms    673 MiB     5.634
+ *      8.316.481   50.179 ms    966 MiB     8.902
+ *
+ * Der bestimmende Posten ist also der BAUMLAUF, nicht das Parsen — rund sechs
+ * Sekunden je Megabyte. Wer diese Tabelle liest, soll die Grenze nicht fuer
+ * billig halten: eine Datei DICHT an der Grenze kostet eine knappe Minute und
+ * fast ein Gigabyte.
+ *
+ * DIE GRENZE: {@link MAX_PARSE_SOURCE_BYTES} = 8 MiB. Sie ist eine MAUER gegen
+ * den Speicher, kein Leistungsversprechen. Begruendung:
+ *   - Bei 8,3 MB liegt die gemessene Spitze bei 966 MiB und damit noch unter
+ *     einem Gigabyte; darueber ist der Prozess auf einem Entwicklerrechner
+ *     nicht mehr verlaesslich. Bei 33 MB kostet schon das blosse Parsen ueber
+ *     1 GiB, die volle Strecke waere weit jenseits davon.
+ *   - Sie liegt UEBER der Vorgabegrenze des Scanners (5 MiB, siehe
+ *     `packages/scanner/src/discovery.ts`), damit der Parser bei
+ *     Standardkonfiguration NIE die engere, unausgesprochene Grenze ist. Wer
+ *     hier abgewiesen wird, hat die Scannergrenze bewusst angehoben und
+ *     bekommt dafuer einen benannten Grund statt eines Absturzes.
+ *   - Die groesste echte Quelldatei dieses Repositorys hat 83.062 Bytes; die
+ *     Grenze ist damit rund das Hundertfache des real Vorkommenden. In der
+ *     Praxis reisst sie nur generierter Code oder ein gebuendeltes Artefakt.
+ *
+ * NICHT GELOEST, und hier ausdruecklich vermerkt: die sechs Sekunden je
+ * Megabyte im Baumlauf sind ein eigener Leistungsdefekt. Diese Grenze
+ * verhindert nur, dass er in einen Speicherabsturz umschlaegt.
+ *
+ * Eine Datei ueber der Grenze wird NICHT stillschweigend uebersprungen: der
+ * Adapter wirft `AdapterParseError` mit `kind: "file_too_large"` und der
+ * GEMESSENEN Groesse, woraus der Aufrufer einen Ledger-Eintrag mit genau
+ * diesem Grund baut (E4).
+ */
+import { AdapterParseError, classifyAdapterFailure } from "@untangle-code/domain";
+
+import type { TsParser, TsTree } from "./tree-sitter-types.js";
+
+/**
+ * Vorgabegroesse des Eingabepuffers der nativen Bindung, in Bytes.
+ * Alles darunter braucht `bufferSize` nicht — alles darueber schon.
+ * Nur dokumentarisch und fuer Tests; der Aufrufpfad uebergibt IMMER `bufferSize`.
+ */
+export const NATIVE_DEFAULT_BUFFER_BYTES = 32 * 1024;
+
+/** Gemessene Obergrenze fuer eine einzelne Quelldatei, in Bytes (Begruendung siehe Modulkopf). */
+export const MAX_PARSE_SOURCE_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Aufschlag auf die Eingabelaenge.
+ *
+ * Gemessen genuegte schon der Faktor 1,0 (`bufferSize === byteLength`) fuer
+ * jede gepruefte Groesse. Der Aufschlag von 25 % ist die Sicherheitsmarge
+ * gegen die Frage, ob die Bindung intern noch ein Terminierungszeichen oder
+ * eine Ausrichtung braucht — er kostet bei 8 MiB Eingabe 2 MiB und ist damit
+ * gegenueber den gemessenen 441 MiB Spitze nicht der bestimmende Posten.
+ */
+const BUFFER_HEADROOM = 1.25;
+
+/** Untergrenze: nie kleiner als die native Vorgabe, sonst wird eine kleine Datei schlechter gestellt. */
+const MIN_BUFFER_BYTES = NATIVE_DEFAULT_BUFFER_BYTES;
+
+/** Laenge des Quelltexts in UTF-8-Bytes — NICHT in Zeichen: die Bindung puffert Bytes. */
+export function sourceByteLength(source: string): number {
+  return Buffer.byteLength(source, "utf8");
+}
+
+/** Der `bufferSize`-Wert fuer eine Eingabe dieser Bytelaenge. */
+export function parseBufferSizeFor(byteLength: number): number {
+  return Math.max(MIN_BUFFER_BYTES, Math.ceil(byteLength * BUFFER_HEADROOM));
+}
+
+/**
+ * DER EINZIGE erlaubte Aufruf von `Parser#parse` in diesem Paket.
+ *
+ * Wer `parser.parse(text)` direkt aufruft, baut den 32-KiB-Defekt neu ein.
+ * Diese Funktion (a) prueft die Groessengrenze VOR dem Parsen, (b) uebergibt
+ * `bufferSize` und (c) verwandelt jede Ausnahme der Bindung in einen
+ * `AdapterParseError` mit benanntem Grund (WP-216), damit kein
+ * Bibliothekstext mehr als "Grund" durchgereicht wird.
+ */
+export function parseWithBuffer(parser: TsParser, source: string): TsTree {
+  const byteLength = sourceByteLength(source);
+
+  if (byteLength > MAX_PARSE_SOURCE_BYTES) {
+    throw new AdapterParseError(
+      "file_too_large",
+      `Source text with ${String(byteLength)} bytes exceeds the parser limit of ` +
+        `${String(MAX_PARSE_SOURCE_BYTES)} Bytes.`,
+      { measurements: { sizeBytes: byteLength, limitBytes: MAX_PARSE_SOURCE_BYTES } },
+    );
+  }
+
+  try {
+    return parser.parse(source, undefined, { bufferSize: parseBufferSizeFor(byteLength) });
+  } catch (error) {
+    const failure = classifyAdapterFailure(error, { sizeBytes: byteLength });
+    // Weitergereicht wird der ROHE Ausnahmetext, nicht `failure.detail`: der
+    // Aufrufer klassifiziert erneut, und ein bereits ausformuliertes Detail
+    // wuerde dabei ein zweites Mal in "(Ausnahmetext: …)" eingewickelt.
+    // Der benannte `kind` ueberlebt in der Klasse, nicht im Text.
+    throw new AdapterParseError(failure.kind, failure.rawMessage, {
+      measurements: { ...failure.measurements, bufferSize: parseBufferSizeFor(byteLength) },
+      cause: error,
+    });
+  }
+}