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

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

@@ -0,0 +1,242 @@
+/**
+ * Der backend-neutrale Baumvertrag (`shared/syntax.ts`), nachgebaut ueber
+ * `SgNode`.
+ *
+ * WARUM DAS HIER TEURER IST ALS DER ANDERE WEG, und warum wir es trotzdem so
+ * bauen: ast-grep hat KEINE Cursor-API. Es gibt kein Gegenstueck zu
+ * `gotoFirstChild`/`gotoNextSibling`/`gotoParent`; jeder Abstieg geht ueber
+ * `children()`, und jedes `children()` baut ein frisches JS-Array aus
+ * Knotenwrappern. Gemessen an diesem Repositorium (721 Dateien, 1.143.212
+ * Knoten): tree-sitter-Cursor 1.703.642 Knoten/s gegen ast-grep 455.329
+ * Knoten/s — Faktor 3,74, Mehrkosten 1,61 us je Knoten. Das ist das Niveau des
+ * `.children`-Weges, den WP-95 abgeschafft hat.
+ *
+ * Deshalb: die JS/TS-Familie bleibt bei tree-sitter, und dieser Cursor ist der
+ * Weg fuer Sprachen, die es sonst GAR NICHT gaebe. Fuer sie ist der Aufpreis
+ * kein Rueckschritt — er ist der Eintrittspreis.
+ *
+ * WAS DIESER CURSOR TROTZDEM RICHTIG MACHT:
+ *   - Er ist ITERATIV. Ein Baum kann zehntausende Ebenen tief sein (eine lange
+ *     `a || b || c`-Kette genuegt); ein rekursiver Walk zerbricht daran mit
+ *     `RangeError: Maximum call stack size exceeded`, nachgemessen an 50.000
+ *     Gliedern.
+ *   - Er materialisiert die Kindliste je Ebene EINMAL, nicht je Zugriff.
+ *   - Er merkt sich den Bereich (`range()`) des aktuellen Knotens, weil
+ *     `rangeOfCursor` vier Werte daraus liest und ast-grep bei jedem Aufruf ein
+ *     verschachteltes Objekt neu baut.
+ *
+ * WAS ER NICHT KANN — und was der Adapter deshalb ehrlich sagen muss:
+ *   - `nodeIsMissing` gibt es bei ast-grep nicht. Hier steht eine HEURISTIK:
+ *     ein Blatt der Breite null. An diesem Repositorium war sie exakt (3 von 3
+ *     MISSING-Knoten), sie bleibt aber eine Heuristik. `create-adapter.ts`
+ *     schreibt das in JEDE davon erzeugte Diagnose.
+ *   - `currentFieldName` gibt es nicht als Rueckrichtung. Wir fragen die
+ *     Felder ab, die das Sprachprofil nennt, und vergleichen ueber `id()` —
+ *     prozesslokal gueltig, nie in Ergebnisdaten (siehe `napi.ts`).
+ */
+import type { SyntaxCursor, SyntaxNode, SyntaxPoint } from "../shared/syntax.js";
+
+import type { SgNode, SgPos } from "./napi.js";
+
+function pointOf(pos: SgPos): SyntaxPoint {
+  return { row: pos.line, column: pos.column };
+}
+
+/** Ein `SgNode` in der Form, die `shared/` erwartet. */
+export class AstGrepSyntaxNode implements SyntaxNode {
+  constructor(
+    /** Der rohe ast-grep-Knoten. Nur `syntax.ts` fasst ihn an. */
+    readonly sg: SgNode,
+    private readonly fieldNames: readonly string[],
+  ) {}
+
+  get type(): string {
+    return this.sg.kind();
+  }
+
+  get text(): string {
+    return this.sg.text();
+  }
+
+  get isNamed(): boolean {
+    return this.sg.isNamed();
+  }
+
+  get startIndex(): number {
+    return this.sg.range().start.index;
+  }
+
+  get endIndex(): number {
+    return this.sg.range().end.index;
+  }
+
+  get startPosition(): SyntaxPoint {
+    return pointOf(this.sg.range().start);
+  }
+
+  get endPosition(): SyntaxPoint {
+    return pointOf(this.sg.range().end);
+  }
+
+  get parent(): SyntaxNode | null {
+    const parent = this.sg.parent();
+    return parent === null ? null : new AstGrepSyntaxNode(parent, this.fieldNames);
+  }
+
+  get previousSibling(): SyntaxNode | null {
+    // Geprueft: ast-grep `prev()` liefert auch ANONYME Geschwister (das
+    // vorangehende `{` einer Blockklammer ebenso wie einen Kommentar). Waere
+    // es nur das vorherige benannte Geschwister, verschoebe sich die
+    // Doc-Bindung stillschweigend.
+    const previous = this.sg.prev();
+    return previous === null ? null : new AstGrepSyntaxNode(previous, this.fieldNames);
+  }
+
+  get children(): readonly SyntaxNode[] {
+    return this.sg.children().map((child) => new AstGrepSyntaxNode(child, this.fieldNames));
+  }
+
+  get namedChildCount(): number {
+    return this.sg.namedChildren().length;
+  }
+
+  namedChild(index: number): SyntaxNode | null {
+    const child = this.sg.namedChildren()[index];
+    return child === undefined ? null : new AstGrepSyntaxNode(child, this.fieldNames);
+  }
+
+  childForFieldName(fieldName: string): SyntaxNode | null {
+    // Ein unbekannter Feldname liefert bei ast-grep `null` (geprueft), wirft
+    // also nicht — ein Profil darf nach Feldern fragen, die es in dieser
+    // Grammatik nicht gibt.
+    const field = this.sg.field(fieldName);
+    return field === null ? null : new AstGrepSyntaxNode(field, this.fieldNames);
+  }
+
+  walk(): SyntaxCursor {
+    return new AstGrepCursor(this.sg, this.fieldNames);
+  }
+}
+
+/** Eine Ebene des Abstiegs: die Geschwisterliste und die Stelle darin. */
+interface CursorLevel {
+  siblings: SgNode[];
+  index: number;
+}
+
+export class AstGrepCursor implements SyntaxCursor {
+  private readonly levels: CursorLevel[] = [];
+  private rangeCacheNode: SgNode | null = null;
+  private rangeCacheValue: { start: SgPos; end: SgPos } | null = null;
+
+  constructor(
+    private readonly rootNode: SgNode,
+    private readonly fieldNames: readonly string[],
+  ) {}
+
+  private get node(): SgNode {
+    const level = this.levels[this.levels.length - 1];
+    if (level === undefined) return this.rootNode;
+    return level.siblings[level.index] as SgNode;
+  }
+
+  private get range(): { start: SgPos; end: SgPos } {
+    const node = this.node;
+    if (this.rangeCacheNode === node && this.rangeCacheValue !== null) return this.rangeCacheValue;
+    const value = node.range();
+    this.rangeCacheNode = node;
+    this.rangeCacheValue = value;
+    return value;
+  }
+
+  get nodeType(): string {
+    return this.node.kind();
+  }
+
+  get nodeText(): string {
+    return this.node.text();
+  }
+
+  get nodeIsMissing(): boolean {
+    // HEURISTIK, kein Messwert: ast-grep kennt `ts_node_is_missing` nicht.
+    // Ein von der Fehlerkorrektur eingefuegter Knoten hat die Breite null und
+    // keine Kinder; die Wurzel ist ausgenommen (eine leere Datei ist kein
+    // fehlender Knoten).
+    if (this.levels.length === 0) return false;
+    const range = this.range;
+    return range.start.index === range.end.index && this.node.isLeaf();
+  }
+
+  get currentFieldName(): string | undefined {
+    const parent = this.parentNode();
+    if (parent === null) return undefined;
+    const nodeId = this.node.id();
+    for (const fieldName of this.fieldNames) {
+      const field = parent.field(fieldName);
+      if (field !== null && field.id() === nodeId) return fieldName;
+    }
+    return undefined;
+  }
+
+  /** Der Elternknoten der aktuellen Position, oder `null` auf der Wurzel. */
+  private parentNode(): SgNode | null {
+    if (this.levels.length === 0) return null;
+    if (this.levels.length === 1) return this.rootNode;
+    const level = this.levels[this.levels.length - 2] as CursorLevel;
+    return level.siblings[level.index] as SgNode;
+  }
+
+  get currentNode(): SyntaxNode {
+    return new AstGrepSyntaxNode(this.node, this.fieldNames);
+  }
+
+  get startPosition(): SyntaxPoint {
+    return pointOf(this.range.start);
+  }
+
+  get endPosition(): SyntaxPoint {
+    return pointOf(this.range.end);
+  }
+
+  get startIndex(): number {
+    return this.range.start.index;
+  }
+
+  get endIndex(): number {
+    return this.range.end.index;
+  }
+
+  gotoParent(): boolean {
+    if (this.levels.length === 0) return false;
+    this.levels.pop();
+    return true;
+  }
+
+  gotoFirstChild(): boolean {
+    const children = this.node.children();
+    if (children.length === 0) return false;
+    this.levels.push({ siblings: children, index: 0 });
+    return true;
+  }
+
+  gotoLastChild(): boolean {
+    const children = this.node.children();
+    if (children.length === 0) return false;
+    this.levels.push({ siblings: children, index: children.length - 1 });
+    return true;
+  }
+
+  gotoNextSibling(): boolean {
+    const level = this.levels[this.levels.length - 1];
+    if (level === undefined || level.index + 1 >= level.siblings.length) return false;
+    level.index += 1;
+    return true;
+  }
+
+  gotoPreviousSibling(): boolean {
+    const level = this.levels[this.levels.length - 1];
+    if (level === undefined || level.index === 0) return false;
+    level.index -= 1;
+    return true;
+  }
+}

package/src/languages/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Central builtin-language registration point.
+ *
+ * Dateibesitz (BUILD_PLAN §4): every path under `packages/parser-registry/`
+ * belongs to WP-06, EXCEPT `src/languages/python/**` and "the registration
+ * line" in this file, both owned by WP-09 (a later wave). WP-09 adds its
+ * import and ONE `registry.register(createPythonAdapter());` line below,
+ * without touching any line above it — that is the whole contract for
+ * adding a language without editing existing files/lines.
+ */
+import type { LazyParserRegistry } from "../registry.js";
+
+import {
+  createBreadthAdapters,
+  createGoAdapter,
+  createRustAdapter,
+} from "./astgrep-backend/index.js";
+import { createJavaScriptAdapter } from "./javascript/index.js";
+import { createJsxAdapter } from "./jsx/index.js";
+import { createProseAdapter } from "./prose/index.js";
+import { createPythonAdapter } from "./python/index.js";
+import { createStructuredTextAdapter } from "./structured-text/index.js";
+import { createTsxAdapter } from "./tsx/index.js";
+import { createTypeScriptAdapter } from "./typescript/index.js";
+import { createVueAdapter } from "./vue/index.js";
+
+/** Registers every builtin language adapter. Registration is cheap and lazy — see `registry.ts`'s doc comment. */
+export function registerBuiltinLanguages(registry: LazyParserRegistry): void {
+  registry.register(createTypeScriptAdapter());
+  registry.register(createJavaScriptAdapter());
+  registry.register(createTsxAdapter());
+  registry.register(createJsxAdapter());
+  registry.register(createVueAdapter());
+  registry.register(createPythonAdapter());
+  // WP-110/WP-217: Prosa und strukturierte Daten sind Stufe `text`, nicht
+  // `unsupported_language` (vision.md §1c, spec.md §7.2). Beide Adapter
+  // laden keine Grammatik und kosten bei der Registrierung nichts.
+  registry.register(createProseAdapter());
+  registry.register(createStructuredTextAdapter());
+  // WP-220: Go und Rust laufen ueber das ast-grep-Backend
+  // (`languages/astgrep-backend/README.md` sagt, warum GENAU diese Sprachen
+  // dort laufen und die JS/TS-Familie nicht). Die Anmeldung kostet nichts:
+  // weder `@ast-grep/napi` noch eine Grammatik wird dabei geladen — das
+  // passiert erst beim ersten Parse einer dieser Sprachen.
+  registry.register(createGoAdapter());
+  registry.register(createRustAdapter());
+  // WP-86: neun weitere Sprachen ueber DASSELBE Backend und DIESELBE
+  // Tabellenform — Java, C#, Ruby, PHP, Kotlin, C, C++, Swift, Bash. Auch sie
+  // laden beim Registrieren nichts.
+  for (const adapter of createBreadthAdapters()) {
+    registry.register(adapter);
+  }
+}

package/src/languages/javascript/index.ts

@@ -0,0 +1,9 @@
+import type { LanguageAdapter } from "@untangle-code/domain";
+
+import { createTreeSitterAdapter } from "../shared/create-adapter.js";
+import { JAVASCRIPT_DIALECT } from "../shared/dialect.js";
+
+/** JavaScript `LanguageAdapter` (`.js`, `.mjs`, `.cjs`), support level "deep" (spec.md §7.2). */
+export function createJavaScriptAdapter(): LanguageAdapter {
+  return createTreeSitterAdapter(JAVASCRIPT_DIALECT);
+}

package/src/languages/jsx/index.ts

@@ -0,0 +1,9 @@
+import type { LanguageAdapter } from "@untangle-code/domain";
+
+import { createTreeSitterAdapter } from "../shared/create-adapter.js";
+import { JSX_DIALECT } from "../shared/dialect.js";
+
+/** JSX `LanguageAdapter` (`.jsx`), support level "deep" (spec.md §7.2). */
+export function createJsxAdapter(): LanguageAdapter {
+  return createTreeSitterAdapter(JSX_DIALECT);
+}

package/src/languages/prose/index.ts

@@ -0,0 +1,270 @@
+/**
+ * Prosa-`LanguageAdapter` (vision.md §1c, WP-110/WP-217).
+ *
+ * WAS ER LOEST
+ *
+ * Vor ihm kannte `getAdapterForPath("spec.md")` nur `null`. Jede Stelle, die
+ * das fragt — `untangle complexity`, der Watcher, der Selbstanalyse-Report —
+ * schrieb daraufhin `unsupported_language` ins Skip-Ledger. Bei der ersten
+ * Selbstanalyse dieses Repositories waren das allein 35 Markdown-Dateien,
+ * bei 654 KB Markdown gegen 2.006 KB TypeScript. vision.md §1c sagt genau
+ * das Gegenteil: Prosa ist erstklassiger Inhalt, und `text` ist kein
+ * abgeschwaechtes `deep`.
+ *
+ * WAS ER LIEFERT — UND WAS BEWUSST NICHT
+ *
+ * - `extractChunks` liefert ueberschriftenbewusste Abschnitte mit
+ *   Breadcrumb. Die Gliederung ist NICHT neu gebaut: es ist dieselbe
+ *   `outlineMarkdown()`, die `@untangle-code/context-artifacts` schon fuer
+ *   konfigurierte Markdown-Artefakte benutzt hat (WP-110 hat sie nach
+ *   domain gehoben). Damit bekommt eine gewoehnliche `.md`-Datei im Chunker
+ *   die AST-Strategie statt `line_fallback` — statt willkuerlicher
+ *   Zeilenfenster also dieselben semantischen Einheiten wie eine
+ *   konfigurierte.
+ * - `extractSymbols` liefert je Abschnitt ein Symbol der Art `"section"`.
+ *   Das ist die Zuordnung, ueber die der Chunker `symbolId`/`symbolFqn` an
+ *   jeden Abschnitt und an jedes Fragment eines zu grossen Abschnitts
+ *   haengt (spec.md §8.5).
+ * - `extractImports` liefert relative Dateiverweise. Ein Verweis von
+ *   `vision.md` auf `spec.md` IST eine Kante im Dateigraphen; sie zu
+ *   verschweigen waere derselbe Verlust wie ein verschwiegener Import.
+ * - `extractCalls` liefert NICHTS. Prosa hat keine Aufrufe.
+ * - `computeComplexity` liefert LEERE Facts: keine `symbolScopes`, keine
+ *   `decisions`. Das ist der Kern von WP-217 und keine Nachlaessigkeit —
+ *   zyklomatische Komplexitaet ueber ein Dokument ist keine schlechte Zahl,
+ *   sondern gar keine. Wer Prosa messen will, nimmt die Prosa-Metriken aus
+ *   `@untangle-code/complexity` (`computeProseMetrics`), die als eigene
+ *   Metrikfamilie (`ProseNumberV1`) gefuehrt werden und deshalb strukturell
+ *   nie in eine Code-Summe geraten koennen.
+ * - `tokenizeForHalstead` liefert NICHTS: Halstead zaehlt Operatoren und
+ *   Operanden; in Prosa gibt es beides nicht.
+ *
+ * `parse()` kann nicht scheitern. Markdown hat keine Syntaxfehler — jeder
+ * Text ist gueltiges Markdown —, deshalb ist `parseQuality` immer
+ * `"complete"` und `ast` nie `null`. Das ist eine Aussage ueber das Format,
+ * keine Beschoenigung.
+ */
+import type {
+  AstRegion,
+  ComplexityFacts,
+  ExtractedSymbol,
+  HalsteadTokens,
+  LanguageAdapter,
+  MarkdownSectionV1,
+  ParsedAst,
+  ParseResult,
+  RawCall,
+  RawImport,
+  SourceFile,
+  SourceRange,
+} from "@untangle-code/domain";
+import {
+  classifyLinkTarget,
+  findMarkdownLinks,
+  outlineMarkdown,
+  sha256Hex,
+  textFormatExtensions,
+} from "@untangle-code/domain";
+
+import { buildLineByteIndex, rangeForLines, type LineByteIndex } from "./line-bytes.js";
+
+/** Sprachkennung dieses Adapters; identisch mit der Scanner-Klassifikation fuer `.md`. */
+export const PROSE_LANGUAGE_ID = "markdown";
+
+/** Symbolart eines Prosa-Abschnitts. Ein Abschnitt ist keine Funktion und heisst auch nicht so. */
+export const PROSE_SYMBOL_KIND = "section";
+
+/** Name des Abschnitts vor der ersten Ueberschrift. */
+const PREAMBLE_NAME = "(Vorspann)";
+
+/** Der in `ParsedAst.root` abgelegte Nutzinhalt; nur dieser Adapter sieht hinein. */
+interface ProseAstRoot {
+  readonly fileId: string;
+  readonly lines: readonly string[];
+  readonly index: LineByteIndex;
+  readonly sections: readonly ProseSection[];
+}
+
+interface ProseSection extends MarkdownSectionV1 {
+  /** Eindeutiger Name innerhalb des Dokuments (siehe `uniqueName`). */
+  readonly qualifiedName: string;
+  readonly range: SourceRange;
+}
+
+/**
+ * Physische Zeilen ohne Zeilenende. Ein abschliessendes `\r` faellt weg,
+ * damit die Ueberschriften- und Verweiserkennung nicht daran scheitert.
+ */
+function splitLines(content: string): string[] {
+  return content.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+}
+
+/**
+ * Zwei Abschnitte koennen denselben Breadcrumb tragen (zweimal dieselbe
+ * Ueberschrift unter demselben Elternteil). Der Chunker schluesselt Symbole
+ * ueber `qualifiedName` in einer `Map`; ohne Vereindeutigung wuerde der
+ * zweite Abschnitt den ersten ueberschreiben und beide dieselbe `symbolId`
+ * bekommen. Angehaengt wird deshalb eine laufende Nummer — sichtbar, nicht
+ * still.
+ */
+function uniqueName(breadcrumb: string, seen: Map<string, number>): string {
+  const base = breadcrumb === "" ? PREAMBLE_NAME : breadcrumb;
+  const count = (seen.get(base) ?? 0) + 1;
+  seen.set(base, count);
+  return count === 1 ? base : `${base} (${String(count)})`;
+}
+
+function buildSections(lines: readonly string[], index: LineByteIndex): ProseSection[] {
+  const seen = new Map<string, number>();
+  return outlineMarkdown(lines).map((section) => ({
+    ...section,
+    qualifiedName: uniqueName(section.breadcrumb, seen),
+    range: rangeForLines(index, section.startLine, section.endLine),
+  }));
+}
+
+function rootOf(ast: ParsedAst): ProseAstRoot {
+  return ast.root as ProseAstRoot;
+}
+
+function sectionContent(root: ProseAstRoot, section: ProseSection): string {
+  return root.lines.slice(section.startLine - 1, section.endLine).join("\n");
+}
+
+function headingTextOf(section: ProseSection): string {
+  return section.level === 0 ? PREAMBLE_NAME : `${"#".repeat(section.level)} ${section.title}`;
+}
+
+function symbolOf(root: ProseAstRoot, section: ProseSection): ExtractedSymbol {
+  return {
+    name: section.level === 0 ? PREAMBLE_NAME : section.title,
+    qualifiedName: section.qualifiedName,
+    kind: PROSE_SYMBOL_KIND,
+    signature: headingTextOf(section),
+    // Die "Signatur" eines Abschnitts ist seine Ueberschriftenebene plus
+    // Pfad: was ihn im Dokument identifiziert, unabhaengig von seiner Zeile.
+    normalizedSignature: `h${String(section.level)} ${section.qualifiedName}`,
+    range: section.range,
+    exportedNames: [],
+    // Formhash: Ebene und Pfad — aendert sich, wenn der Abschnitt umbenannt
+    // oder verschoben wird, nicht wenn sein Text sich aendert.
+    astHash: sha256Hex(`prose-section ${String(section.level)} ${section.qualifiedName}`),
+    // Inhaltshash: der Rohtext des Abschnitts.
+    tokenFingerprint: sha256Hex(sectionContent(root, section)),
+  };
+}
+
+export function createProseAdapter(): LanguageAdapter {
+  return {
+    languageId: PROSE_LANGUAGE_ID,
+    extensions: textFormatExtensions("prose"),
+    supportLevel: "text",
+
+    parse(source: SourceFile): ParseResult {
+      const lines = splitLines(source.content);
+      const index = buildLineByteIndex(source.content);
+      const root: ProseAstRoot = {
+        fileId: source.fileId,
+        lines,
+        index,
+        sections: buildSections(lines, index),
+      };
+      const ast: ParsedAst = {
+        languageId: PROSE_LANGUAGE_ID,
+        parseQuality: "complete",
+        root,
+        diagnostics: [],
+      };
+      return {
+        parseQuality: "complete",
+        ast,
+        diagnostics: [],
+        errorNodeCount: 0,
+        missingNodeCount: 0,
+      };
+    },
+
+    extractChunks(ast: ParsedAst): AstRegion[] {
+      const root = rootOf(ast);
+      const children: AstRegion[] = root.sections.map((section) => ({
+        // Der Vorspann vor der ersten Ueberschrift ist genau das, was
+        // `file_preamble` beschreibt; alles Weitere ist ein Prosa-Abschnitt.
+        chunkKind: section.level === 0 ? "file_preamble" : "prose_section",
+        range: section.range,
+        scopeId: `${root.fileId}#${section.qualifiedName}`,
+        symbolFqn: section.qualifiedName,
+        headerText:
+          section.level === 0
+            ? PREAMBLE_NAME
+            : `${"#".repeat(section.level)} ${section.breadcrumb}`,
+        // Ein Abschnitt hat keine feineren AST-Grenzen; ist er zu gross,
+        // teilt der Chunker ihn an Tokengrenzen in `symbol_fragment`s, die
+        // seine `symbolId` erben (spec.md §8.5).
+        splittable: false,
+      }));
+      return [
+        {
+          chunkKind: "module",
+          range: {
+            startLine: 1,
+            endLine: root.index.lineCount,
+            startByte: 0,
+            endByte: root.index.totalBytes,
+          },
+          scopeId: root.fileId,
+          splittable: children.length > 0,
+          ...(children.length > 0 ? { children } : {}),
+        },
+      ];
+    },
+
+    extractSymbols(ast: ParsedAst): ExtractedSymbol[] {
+      const root = rootOf(ast);
+      return root.sections.map((section) => symbolOf(root, section));
+    },
+
+    extractImports(ast: ParsedAst): RawImport[] {
+      const root = rootOf(ast);
+      const imports: RawImport[] = [];
+      for (const link of findMarkdownLinks(root.lines)) {
+        if (classifyLinkTarget(link.target) !== "relative_file") continue;
+        imports.push({
+          specifier: link.target,
+          importKind: "import",
+          range: rangeForLines(root.index, link.line, link.line),
+        });
+      }
+      return imports;
+    },
+
+    extractCalls(_ast: ParsedAst): RawCall[] {
+      // Prosa hat keine Aufrufe. Eine leere Liste ist hier die vollstaendige
+      // Antwort, keine Abstufung.
+      return [];
+    },
+
+    computeComplexity(ast: ParsedAst): ComplexityFacts {
+      // KEINE `symbolScopes` und KEINE `decisions` — siehe Kopfkommentar.
+      // Stuende hier je Abschnitt ein Scope, rechnete jede
+      // Code-Metrik-Pipeline anschliessend `cyclomatic = 1` je Ueberschrift
+      // und addierte das zur Summe des Repositories. Genau das verhindert
+      // diese leere Antwort.
+      return {
+        symbolScopes: [],
+        decisions: [],
+        nestingEvents: [],
+        operators: [],
+        operands: [],
+        nodeKinds: [],
+        comments: [],
+        identifiers: [],
+        literals: [],
+        parseDiagnostics: ast.diagnostics,
+      };
+    },
+
+    tokenizeForHalstead(_ast: ParsedAst): HalsteadTokens {
+      return { operators: [], operands: [] };
+    },
+  };
+}

package/src/languages/prose/line-bytes.ts

@@ -0,0 +1,52 @@
+/**
+ * Zeilenanfaenge als UTF-8-Byte-Versaetze.
+ *
+ * `SourceRange` (domain `types/common.ts`) ist auf BYTES normativ; die
+ * Prosa-Gliederung arbeitet in ZEILEN. Diese Tabelle ist die Uebersetzung.
+ * Geschnitten wird ausschliesslich unmittelbar nach `\n` (0x0A) — ein
+ * Einzelbyte, nie ein UTF-8-Folgebyte —, damit jede erzeugte Grenze eine
+ * gueltige Zeichengrenze ist.
+ */
+
+export interface LineByteIndex {
+  /** Byte-Versatz jedes Zeilenanfangs, plus ein Schlusswaechter = Dateigroesse. */
+  readonly lineStarts: readonly number[];
+  /** Anzahl physischer Zeilen. */
+  readonly lineCount: number;
+  readonly totalBytes: number;
+}
+
+export function buildLineByteIndex(content: string): LineByteIndex {
+  const buffer = Buffer.from(content, "utf8");
+  const lineStarts: number[] = [0];
+  for (let i = 0; i < buffer.length; i += 1) {
+    if (buffer[i] === 0x0a) lineStarts.push(i + 1);
+  }
+  const lineCount = lineStarts.length;
+  lineStarts.push(buffer.length);
+  return { lineStarts, lineCount, totalBytes: buffer.length };
+}
+
+/** Byte-Versatz des Anfangs der 1-basierten Zeile `line`, geklemmt. */
+export function lineStartByte(index: LineByteIndex, line: number): number {
+  const clamped = Math.min(Math.max(line, 1), index.lineStarts.length);
+  return index.lineStarts[clamped - 1] ?? index.totalBytes;
+}
+
+/**
+ * `SourceRange` fuer die 1-basierte inklusive Zeilenspanne. `endByte` ist der
+ * Anfang der Zeile NACH `endLine`, also sind zwei benachbarte Spannen
+ * lueckenlos und ueberlappungsfrei.
+ */
+export function rangeForLines(
+  index: LineByteIndex,
+  startLine: number,
+  endLine: number,
+): { startLine: number; endLine: number; startByte: number; endByte: number } {
+  return {
+    startLine,
+    endLine,
+    startByte: lineStartByte(index, startLine),
+    endByte: lineStartByte(index, endLine + 1),
+  };
+}