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

package/src/languages/python/profile.ts

@@ -0,0 +1,341 @@
+/**
+ * Die Python-Regeln, die KEINE Tabelle ausdrueckt.
+ *
+ * Alles Uebrige — Entscheidungen, Nesting, Kommentare, Halstead-Token,
+ * Aufrufe, Scopes — kommt aus `table.ts` durch den gemeinsamen Motor
+ * (`shared/table-profile.ts`, `shared/engine.ts`). Hier steht nur, was
+ * Python anders macht als jede andere Sprache dieses Projekts:
+ *
+ *  1. DOCSTRINGS. Python bindet die Beschreibung nicht an einen Kommentar VOR
+ *     der Definition, sondern an die erste Anweisung IM Rumpf.
+ *  2. SICHTBARKEIT. Es gibt keinen Modifikator; sie steht in der
+ *     Namenskonvention (`_x` geschuetzt, `__x` privat, `__x__` oeffentlich).
+ *  3. `__all__`. Was eine Datei exportiert, steht in einer Zuweisung auf
+ *     Modulebene — also je DATEI, nicht je Knoten. Deshalb wird dieses Profil
+ *     je Parse gebaut (`AstGrepAdapterHooks.profileForFile`) und nicht einmal
+ *     je Adapter.
+ *  4. METHODE ODER FUNKTION. `def` ist beides; welches, sagt erst der
+ *     umgebende Knoten. Eine Tabelle bildet Knotenart auf Scope-Art ab und
+ *     kann das nicht.
+ *  5. IMPORTE. Eine Anweisung fuehrt mehrere Ziele mit je eigenem Alias
+ *     (`from a import b as c, d`) — `ImportRules` kennt genau eines.
+ *  6. SIGNATUREN. Die Normalform folgt `signature.ts` (Vorgabewerte fallen
+ *     weg, Annotationen bleiben) und nicht der Rohtextregel der Tabelle.
+ *  7. ZEICHENKETTEN. Ein `string` ist hier KEIN geschlossener Container
+ *     (siehe `table.ts`); seine Textblaetter muessen deshalb ausdruecklich
+ *     als Zeichenkettenliterale gelten.
+ */
+import type { LiteralFact, RawImport, SourceFile, SourceRange } from "@untangle-code/domain";
+
+import type { DecisionDetectionResult } from "../shared/decisions.js";
+import type { FileTextContext } from "../shared/node-utils.js";
+import { rangeOf } from "../shared/node-utils.js";
+import type { LanguageProfile, ModuleFactSink, ScopeSignature } from "../shared/profile.js";
+import type { ScopeNode } from "../shared/scope-model.js";
+import type { SyntaxNode } from "../shared/syntax.js";
+
+import { normalizeHeaderText, normalizeParameterList, normalizeReturnType } from "./signature.js";
+import { PYTHON_STRING_LEAF_KINDS } from "./table.js";
+
+const INIT_FILE_RE = /(^|\/)__init__\.pyi?$/;
+const STRING_LEAF_KINDS: ReadonlySet<string> = new Set(PYTHON_STRING_LEAF_KINDS);
+
+/** Knotenarten, die einen eigenen Namensraum aufmachen — die Grenze fuer "steht in einer Klasse". */
+const SCOPE_OPENING_KINDS: ReadonlySet<string> = new Set([
+  "function_definition",
+  "class_definition",
+  "lambda",
+]);
+
+// ---------------------------------------------------------------------------
+// 2. Sichtbarkeit aus der Namenskonvention (PEP 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * `__x__` ist das oeffentliche Protokoll (`__init__`, `__len__`) und bekommt
+ * deshalb GAR KEINE Angabe — nicht "public": das Feld ist optional, und
+ * "keine Angabe" ist die ehrliche Aussage ueber eine Sprache ohne
+ * Sichtbarkeitsmodifikatoren.
+ */
+function pythonVisibility(name: string): string | undefined {
+  if (name.startsWith("__") && name.endsWith("__") && name.length > 4) return undefined;
+  if (name.startsWith("__")) return "private";
+  if (name.startsWith("_")) return "protected";
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Docstrings
+// ---------------------------------------------------------------------------
+
+/** Der Text eines Zeichenkettenknotens ohne Anfuehrungszeichen (auch dreifache). */
+function stringLiteralText(node: SyntaxNode): string | null {
+  if (node.type !== "string") return null;
+  for (const child of node.children) {
+    if (child.type === "string_content") return child.text;
+  }
+  return "";
+}
+
+/**
+ * Der Docstring eines Scopes: die erste Anweisung des Rumpfes, wenn sie aus
+ * nichts als einem Zeichenkettenliteral besteht. Alles andere ist Code, und
+ * ein Stueck Code als Beschreibung auszugeben waere eine Erfindung.
+ */
+function docstringRange(
+  node: SyntaxNode,
+  ctx: FileTextContext,
+  bodyField: string,
+): SourceRange | undefined {
+  const body = node.childForFieldName(bodyField);
+  if (body === null) return undefined;
+  const first = body.namedChild(0);
+  if (first === null || first.type !== "expression_statement") return undefined;
+  const expression = first.namedChild(0);
+  if (expression === null || stringLiteralText(expression) === null) return undefined;
+  return rangeOf(expression, ctx);
+}
+
+// ---------------------------------------------------------------------------
+// 3. `__all__`
+// ---------------------------------------------------------------------------
+
+/**
+ * Die Namen aus `__all__ = [...]` auf Modulebene, oder `null`, wenn die Datei
+ * keines hat. `null` und nicht "leere Menge": ohne `__all__` gilt die
+ * Unterstrich-Konvention, mit leerem `__all__` exportiert die Datei nichts.
+ * Die beiden Faelle zu vermengen hiesse, jede Datei ohne `__all__` fuer
+ * exportlos zu erklaeren.
+ */
+function findDunderAll(root: SyntaxNode): ReadonlySet<string> | null {
+  for (const statement of root.children) {
+    if (statement.type !== "expression_statement") continue;
+    const assignment = statement.namedChild(0);
+    if (assignment === null || assignment.type !== "assignment") continue;
+    const left = assignment.childForFieldName("left");
+    if (left === null || left.type !== "identifier" || left.text !== "__all__") continue;
+    const right = assignment.childForFieldName("right");
+    if (
+      right === null ||
+      (right.type !== "list" && right.type !== "tuple" && right.type !== "set")
+    ) {
+      continue;
+    }
+    const names = new Set<string>();
+    for (const element of right.children) {
+      const text = stringLiteralText(element);
+      if (text !== null) names.add(text);
+    }
+    return names;
+  }
+  return null;
+}
+
+/** Steht dieser Knoten unmittelbar auf Modulebene (auch unter einem Dekorator)? */
+function isTopLevel(node: SyntaxNode): boolean {
+  const parent = node.parent;
+  if (parent === null) return false;
+  if (parent.type === "module") return true;
+  return parent.type === "decorated_definition" && parent.parent?.type === "module";
+}
+
+// ---------------------------------------------------------------------------
+// 4. Methode oder Funktion
+// ---------------------------------------------------------------------------
+
+/** Der naechste umschliessende Knoten, der selbst einen Namensraum oeffnet. */
+function enclosingScopeKind(node: SyntaxNode): string | null {
+  let current = node.parent;
+  while (current !== null) {
+    if (SCOPE_OPENING_KINDS.has(current.type)) return current.type;
+    current = current.parent;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 5. Importe
+// ---------------------------------------------------------------------------
+
+/** Ziel und Alias eines einzelnen Importeintrags (`os.path as osp`, `helper`). */
+function importEntryOf(node: SyntaxNode): { path: string; alias?: string } | null {
+  if (node.type === "dotted_name") return { path: node.text };
+  if (node.type !== "aliased_import") return null;
+  const path = node.childForFieldName("name");
+  const alias = node.childForFieldName("alias");
+  if (path === null) return null;
+  return { path: path.text, ...(alias === null ? {} : { alias: alias.text }) };
+}
+
+/**
+ * `import a, b as c` — jedes Ziel ist ein eigener Import mit eigenem Pfad.
+ * `from m import a, b as c` — EIN Pfad (`m`) mit mehreren gebundenen Namen.
+ * Zwei Formen, deshalb zwei Zweige und keine gemeinsame Schleife, die beide
+ * halb falsch bedient.
+ */
+function collectPythonImports(
+  node: SyntaxNode,
+  ctx: FileTextContext,
+  sink: ModuleFactSink,
+  isInitFile: boolean,
+): void {
+  const range = rangeOf(node, ctx);
+  // spec.md §6.2: was ein Paketkopf (`__init__.py`) auf oberster Ebene
+  // hereinholt, reicht er weiter — das ist ein Re-Export, kein Verbrauch.
+  const importKind: RawImport["importKind"] =
+    isInitFile && isTopLevel(node) ? "re_export" : "import";
+
+  if (node.type === "import_statement") {
+    for (const child of node.children) {
+      const entry = importEntryOf(child);
+      if (entry === null) continue;
+      sink.imports.push({
+        specifier: entry.path,
+        importKind,
+        range,
+        ...(entry.alias === undefined ? {} : { importedNames: [entry.alias] }),
+      });
+    }
+    return;
+  }
+
+  const moduleNode = node.childForFieldName("module_name");
+  if (moduleNode === null) return;
+  const importedNames: string[] = [];
+  // Die gebundenen Namen stehen NACH dem Schluesselwort `import`; davor steht
+  // der Modulpfad, der genauso aussieht. Ohne diese Schranke stuende
+  // `collections` bei `from collections import x` als importierter Name da.
+  let afterKeyword = false;
+  for (const child of node.children) {
+    if (child.type === "import") {
+      afterKeyword = true;
+      continue;
+    }
+    if (!afterKeyword) continue;
+    // `from m import *` bindet unbekannt viele Namen. KEINEN zu nennen ist
+    // die einzige ehrliche Antwort (domain `analysis.ts`: ein fehlendes Feld
+    // heisst "unbekannt").
+    const entry = importEntryOf(child);
+    if (entry !== null) importedNames.push(entry.alias ?? entry.path);
+  }
+  sink.imports.push({
+    specifier: moduleNode.text,
+    importKind,
+    range,
+    ...(importedNames.length > 0 ? { importedNames } : {}),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 6. Signaturen
+// ---------------------------------------------------------------------------
+
+function headerBeforeBody(node: SyntaxNode, bodyField: string): string {
+  const body = node.childForFieldName(bodyField);
+  if (body === null) return node.text.split("\n")[0]?.trim() ?? node.text;
+  return node.text.slice(0, Math.max(0, body.startIndex - node.startIndex)).trimEnd();
+}
+
+function pythonSignature(node: SyntaxNode, name: string, bodyField: string): ScopeSignature {
+  if (node.type === "class_definition") {
+    const raw = headerBeforeBody(node, bodyField);
+    return { raw, normalized: normalizeHeaderText(raw) };
+  }
+
+  const parameters = node.childForFieldName("parameters");
+  // `lambda_parameters` traegt KEINE Klammern; `parameters` traegt sie. Beide
+  // muessen als `(...)` in die Normalform, sonst zerfaellt die Aufteilung.
+  const parametersText =
+    parameters === null
+      ? "()"
+      : parameters.text.trim().startsWith("(")
+        ? parameters.text
+        : `(${parameters.text})`;
+  const returnType = node.childForFieldName("return_type");
+  // `async` ist ein anonymes Kind, kein Feld — und es gehoert zur
+  // Aufrufschnittstelle: eine Koroutine ist nicht dasselbe wie eine Funktion.
+  const isAsync = node.children.some((child) => child.type === "async");
+  const head = `${isAsync ? "async " : ""}${name}`;
+  const raw = `${head}${parametersText}${returnType === null ? "" : ` -> ${returnType.text}`}`;
+  const normalized = `${head}${normalizeParameterList(parametersText)}${normalizeReturnType(
+    returnType?.text,
+  )}`;
+  return { raw, normalized };
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Baut das Python-Profil ueber dem Tabellenprofil — EINMAL JE DATEI, weil
+ * `__all__` und `__init__.py` Dateieigenschaften sind.
+ */
+export function createPythonProfile(
+  base: LanguageProfile,
+  root: SyntaxNode,
+  file: SourceFile,
+): LanguageProfile {
+  const dunderAll = findDunderAll(root);
+  const isInitFile = INIT_FILE_RE.test(file.path.replace(/\\/g, "/"));
+  const bodyField = "body";
+
+  return {
+    ...base,
+
+    // 7. Zeichenkettenblaetter (siehe `table.ts`: `string` ist kein Container).
+    simpleLiteralLeafKinds: new Set([...base.simpleLiteralLeafKinds, ...STRING_LEAF_KINDS]),
+    simpleLiteralKind(kind: string): LiteralFact["literalKind"] {
+      return STRING_LEAF_KINDS.has(kind) ? "string" : base.simpleLiteralKind(kind);
+    },
+
+    // Der Dekorator gehoert zum Symbol: `@app.route(...)` steht ueber der
+    // Funktion und beschreibt sie. `chunks.ts` weitet den Bereich darauf aus.
+    exportWrapperKinds: new Set(["decorated_definition"]),
+
+    // 4. `def` ist Funktion, Methode oder Konstruktor.
+    scopeKindOf(node: SyntaxNode): ScopeNode["kind"] | null {
+      const kind = base.scopeKindOf(node);
+      if (kind !== "function" || node.type !== "function_definition") return kind;
+      if (enclosingScopeKind(node) !== "class_definition") return "function";
+      return base.scopeName(node) === "__init__" ? "constructor" : "method";
+    },
+
+    scopeSignature(node: SyntaxNode, _kind: ScopeNode["kind"], name: string): ScopeSignature {
+      return pythonSignature(node, name, bodyField);
+    },
+
+    docRange: (node, ctx) => docstringRange(node, ctx, bodyField),
+
+    visibility: (_node, name) => pythonVisibility(name),
+
+    // 3. `__all__` schlaegt die Unterstrich-Konvention. Beides gilt nur fuer
+    // Namen auf Modulebene: eine Methode wird nicht aus der Datei exportiert.
+    exportedNames(node: SyntaxNode, name: string): string[] {
+      if (!isTopLevel(node)) return [];
+      if (dunderAll !== null) return dunderAll.has(name) ? [name] : [];
+      return name.startsWith("_") ? [] : [name];
+    },
+
+    detectDecisionAndNesting(node: SyntaxNode): DecisionDetectionResult {
+      const detected = base.detectDecisionAndNesting(node);
+      // `union_pattern` ist FLACH: `case 1 | 2 | 3` ist EIN Knoten mit drei
+      // Zweigen, waehrend Rusts `or_pattern` fuer dasselbe zwei verschachtelte
+      // Knoten baut. Ohne diese Zahl kostete `1 | 2 | 3` so viel wie `1 | 2`.
+      if (node.type !== "union_pattern" || detected.decision === undefined) return detected;
+      const alternatives = node.namedChildCount;
+      if (alternatives <= 1) return detected;
+      return { ...detected, decision: { ...detected.decision, repeat: alternatives - 1 } };
+    },
+
+    collectModuleFacts(node, kind, callerScopeId, ctx, sink): void {
+      if (
+        kind === "import_statement" ||
+        kind === "import_from_statement" ||
+        kind === "future_import_statement"
+      ) {
+        collectPythonImports(node, ctx, sink, isInitFile);
+        return;
+      }
+      base.collectModuleFacts(node, kind, callerScopeId, ctx, sink);
+    },
+  };
+}

package/src/languages/python/signature.ts

@@ -0,0 +1,183 @@
+/**
+ * Signature text normalization for Python (spec.md §5.5).
+ *
+ * `normalizedSignature` feeds `buildSymbolId` and MUST be stable across
+ * formatting-only edits. Rules (documented WP-09 decision — Python has no
+ * `tree-sitter-python` grammar to reuse `languages/shared/signature.ts`'s
+ * `<`/`>`-as-bracket assumption from, which is wrong for Python anyway:
+ * `<`/`>` are ONLY comparison operators here, never generic brackets):
+ *
+ * 1. **Whitespace**: any run of spaces/tabs/newlines collapses to a single
+ *    space; spacing around `,`, `:` (annotation colon) and `=` (only for
+ *    an ANNOTATED parameter's default, per PEP 8 — `x: int = 1`, not
+ *    `x=1`) is canonicalized.
+ * 2. **Default values** (`= <expr>`) are STRIPPED from the identity
+ *    signature, exactly like the TS/JS adapters: a default value is a
+ *    call-site convenience, not a change to the parameter's name,
+ *    position, or `*`/`**` role — keeping it would change a symbol's id on
+ *    a body-only-feeling edit (`def f(a=1)` -> `def f(a=2)` should not look
+ *    like a new symbol). Unlike TypeScript, Python has no separate
+ *    "optional marker" syntax (`?`) that would otherwise carry the
+ *    "caller may omit this" information forward — that information is
+ *    simply not part of the normalized identity for Python, a documented
+ *    (not accidental) asymmetry with the TS/JS adapters.
+ * 3. **Type annotations** (`: <type>`) are kept verbatim (modulo whitespace
+ *    rules) — they are part of the observable call contract.
+ * 4. **`*args` / `**kwargs` / bare `*` (keyword-only marker) / `/`
+ *    (positional-only marker, PEP 570)**: their `*`/`**`/`/` marker is kept
+ *    exactly as written (it changes the call contract), only a following
+ *    default (impossible for `*args`/`**kwargs`/markers, but harmless to
+ *    guard) or its annotation spacing is normalized.
+ * 5. **Return type** (`-> <type>`) is kept verbatim (modulo whitespace),
+ *    canonicalized to always have exactly one space on each side of `->`.
+ *
+ * Known limitation (documented, not a defect, mirroring the TS/JS
+ * adapters' own documented limitation): default-value stripping uses a
+ * bracket-DEPTH scanner over `( [ {` (never `<`/`>` — see above), not a
+ * full expression parser. A default expression containing an unbalanced
+ * string literal with a comma/`=` inside is not specially protected either
+ * (rare enough in default-value position to accept as a scoping decision).
+ */
+
+const OPEN_BRACKETS = new Set(["(", "[", "{"]);
+const CLOSE_BRACKETS = new Set([")", "]", "}"]);
+
+/** Collapses whitespace runs to single spaces and trims. */
+export function normalizeSpacing(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/** Splits `content` on top-level `,` (depth 0 w.r.t. `( [ {`). */
+export function splitTopLevelComma(content: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  let inString: string | null = null;
+  for (let i = 0; i < content.length; i += 1) {
+    const ch = content[i] as string;
+    if (inString !== null) {
+      current += ch;
+      if (ch === "\\") {
+        i += 1;
+        if (i < content.length) current += content[i];
+      } else if (ch === inString) {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      current += ch;
+      continue;
+    }
+    if (OPEN_BRACKETS.has(ch)) depth += 1;
+    else if (CLOSE_BRACKETS.has(ch)) depth = Math.max(0, depth - 1);
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  parts.push(current);
+  return parts;
+}
+
+/** Index of the top-level `=` introducing a default value, or -1. Excludes `==`, `!=`, `<=`, `>=`, `:=`. */
+function findTopLevelDefaultEquals(text: string): number {
+  let depth = 0;
+  let inString: string | null = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (inString !== null) {
+      if (ch === "\\") i += 1;
+      else if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+    if (OPEN_BRACKETS.has(ch)) {
+      depth += 1;
+      continue;
+    }
+    if (CLOSE_BRACKETS.has(ch)) {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (ch === "=" && depth === 0) {
+      const prev = i > 0 ? text[i - 1] : "";
+      const next = i + 1 < text.length ? text[i + 1] : "";
+      const isCompoundOperator =
+        next === "=" ||
+        prev === "=" ||
+        prev === "!" ||
+        prev === "<" ||
+        prev === ">" ||
+        prev === ":";
+      if (!isCompoundOperator) return i;
+    }
+  }
+  return -1;
+}
+
+/** Strips one parameter entry's default value (`= <expr>`), keeping any annotation before it. */
+export function stripDefaultValue(entry: string): string {
+  const eqIndex = findTopLevelDefaultEquals(entry);
+  return eqIndex === -1 ? entry : entry.slice(0, eqIndex).trimEnd();
+}
+
+/** Canonicalizes one parameter entry's internal spacing: `a :int=1` -> `a: int`. */
+function normalizeParamEntry(entry: string): string {
+  const stripped = stripDefaultValue(entry);
+  const colonIndex = topLevelColonIndex(stripped);
+  if (colonIndex === -1) return normalizeSpacing(stripped);
+  const name = normalizeSpacing(stripped.slice(0, colonIndex));
+  const annotation = normalizeSpacing(stripped.slice(colonIndex + 1));
+  return `${name}: ${annotation}`;
+}
+
+function topLevelColonIndex(text: string): number {
+  let depth = 0;
+  let inString: string | null = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (inString !== null) {
+      if (ch === "\\") i += 1;
+      else if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+    if (OPEN_BRACKETS.has(ch)) depth += 1;
+    else if (CLOSE_BRACKETS.has(ch)) depth = Math.max(0, depth - 1);
+    else if (ch === ":" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Normalizes a parameter-list text INCLUDING its outer parens, e.g. `( a:int=1, *, b = 2 )` -> `(a: int, *, b)`. */
+export function normalizeParameterList(paramsText: string): string {
+  const trimmed = paramsText.trim();
+  const hasParens = trimmed.startsWith("(") && trimmed.endsWith(")");
+  const inner = hasParens ? trimmed.slice(1, -1) : trimmed;
+  const entries = splitTopLevelComma(inner)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  const normalizedEntries = entries.map(normalizeParamEntry);
+  return `(${normalizedEntries.join(", ")})`;
+}
+
+/** Normalizes a `-> ReturnType` suffix (or `""` when absent). */
+export function normalizeReturnType(returnTypeRaw: string | undefined): string {
+  if (returnTypeRaw === undefined || returnTypeRaw.trim().length === 0) return "";
+  return ` -> ${normalizeSpacing(returnTypeRaw)}`;
+}
+
+/** Normalizes a class/def header text with no parameter list (e.g. a bare `class Foo:`). */
+export function normalizeHeaderText(headerText: string): string {
+  return normalizeSpacing(headerText.replace(/:\s*$/, ""));
+}

package/src/languages/python/table.ts

@@ -0,0 +1,135 @@
+/**
+ * Die Sprachtabelle fuer Python — die zwoelfte Sprache des ast-grep-Backends.
+ *
+ * WAS HIER GESCHAH (WP-239): bis Welle 7 stand an dieser Stelle ein
+ * HANDGESCHRIEBENER Tokenizer, Parser und AST-Motor ueber 5.604 Zeilen. Sie
+ * entstanden nicht aus einer fachlichen Notwendigkeit, sondern weil eine zu
+ * enge Auftragsgrenze einem Agenten verbot, `package.json` anzufassen
+ * (dokumentiert in `docs/PARITY.md`). Die Grammatik, die es dafuer braucht,
+ * gibt es fertig und MIT-lizenziert: `@ast-grep/lang-python`.
+ *
+ * WAS DIE ABLOESUNG NEBENBEI BEHOBEN HAT — nicht durch eine Korrektur,
+ * sondern weil die Klasse von Fehlern verschwindet:
+ *
+ *   - WP-238: `with a() as x, b() as y:` liess im handgeschriebenen Parser die
+ *     GANZE Datei mit `parseQuality: "failed"` durchfallen. Die Grammatik legt
+ *     dafuer `with_clause > with_item*` an; es gibt nichts zu erkennen.
+ *   - WP-115: verschachtelte Ausdruecke in f-String-Formatangaben
+ *     (`f"{x:{w}.{p}}"`) gingen im Teil-Parse verloren. Hier sind sie
+ *     gewoehnliche `interpolation`/`format_expression`-Knoten im Baum —
+ *     deshalb steht `string` NICHT unter `stringContainerKinds` (siehe dort).
+ *   - WP-226: ein nachgestellter Kommentar vor dem Zeilenende verschluckte im
+ *     Tokenizer das NEWLINE. Ein `comment` ist hier ein Geschwister wie jedes
+ *     andere.
+ *
+ * WAS DIE TABELLE NICHT LEISTET, steht in `profile.ts` daneben: Docstrings,
+ * Sichtbarkeit aus der Namenskonvention, `__all__`, die Unterscheidung
+ * Funktion/Methode/Konstruktor und die Importformen sind Python-Regeln, die
+ * KEINE Tabelle ausdrueckt. Sie stehen als Verfeinerung ueber diesem Profil,
+ * nicht als Sonderfaelle im gemeinsamen Motor.
+ *
+ * DIE KNOTENARTEN SIND NACHGESEHEN, NICHT GERATEN: jede Zeichenkette hier
+ * stammt aus einem echten Baum, den `adapters.test.ts` mit demselben
+ * Quelltext wieder erzeugt.
+ */
+import type { AstGrepLanguageSource } from "../astgrep-backend/index.js";
+import type { LanguageKindTable } from "../shared/table-profile.js";
+import { DEFAULT_PUNCTUATION } from "../shared/table-profile.js";
+
+/** Woher die Grammatik kommt. MIT-lizenziert, siehe `THIRD_PARTY_LICENSES.md`. */
+export const PYTHON_SOURCE: AstGrepLanguageSource = {
+  languageName: "python",
+  moduleName: "@ast-grep/lang-python",
+};
+
+/**
+ * Zeichenkettenblaetter. Sie stehen NICHT unter `numberLeafKinds` und
+ * Verwandten, weil `simpleLiteralKind` daraus "number"/"boolean"/"null"
+ * ableitet; `profile.ts` haengt sie an und beantwortet sie mit "string".
+ */
+export const PYTHON_STRING_LEAF_KINDS: readonly string[] = ["string_content", "escape_sequence"];
+
+export const PYTHON_TABLE: LanguageKindTable = {
+  languageId: "python",
+  extensions: [".py", ".pyi"],
+  supportLevel: "deep",
+  commentKinds: ["comment"],
+
+  /**
+   * ABSICHTLICH LEER. Ein `string` waere in jeder anderen Sprache ein
+   * Container, dessen Teilbaum EIN Operand ist. In Python ist er das nicht:
+   * ein f-String traegt `interpolation`-Knoten mit vollwertigen Ausdruecken,
+   * und ein Aufruf darin ist ein Aufruf. Wer `string` hier eintraegt, macht
+   * WP-115 zum zweiten Mal — nur diesmal ohne Diagnose, weil der Walk gar
+   * nicht erst hineinsieht.
+   */
+  stringContainerKinds: [],
+
+  identifierLeafKinds: ["identifier"],
+  numberLeafKinds: ["integer", "float"],
+  booleanLeafKinds: ["true", "false"],
+  nullLeafKinds: ["none"],
+
+  // `string_start`/`string_end` tragen das Praefix und die Anfuehrungszeichen;
+  // sie sind Struktur, kein Operator. Ohne sie stuende `f"` als "Operator" in
+  // jeder Halstead-Rechnung.
+  punctuationKinds: [...DEFAULT_PUNCTUATION, "string_start", "string_end"],
+
+  scopes: [
+    { kinds: ["function_definition"], scopeKind: "function" },
+    { kinds: ["class_definition"], scopeKind: "class" },
+    // Ein `lambda` ist eine Ausfuehrungseinheit wie eine `def`: spec.md §16.1
+    // zaehlt Lambdas mit, und §16.4 verlangt fuer sie ein eigenes
+    // Nesting-Ereignis im umgebenden Scope. Beides haengt daran, dass es hier
+    // steht.
+    { kinds: ["lambda"], scopeKind: "function" },
+  ],
+
+  decisions: {
+    // `if_clause` ist BEIDES: der Filter einer Komprehension
+    // (`[x for x in a if p(x)]`) und der Waechter eines `case`. Beide sind
+    // eine echte Verzweigung, beide zaehlen — und beide heissen so.
+    ifKinds: ["if_statement", "if_clause"],
+    elseIfKinds: ["elif_clause"],
+    // `for_in_clause` ist die `for`-Klausel einer Komprehension. Sie ist eine
+    // Schleife, auch wenn sie keine Anweisung ist.
+    loopKinds: ["for_statement", "while_statement", "for_in_clause"],
+    catchKinds: ["except_clause", "except_group_clause"],
+    ternaryKinds: ["conditional_expression"],
+    switchKinds: ["match_statement"],
+    caseKinds: ["case_clause"],
+    // `case _:` zaehlt in Python MIT: anders als ein C-`default` ist `_` ein
+    // gewoehnliches Muster in der Reihenfolge, und ein `match` bricht ohne
+    // Treffer einfach ab. Deshalb steht hier KEIN `caseExcludeChildKinds`.
+    patternAlternativeKinds: ["union_pattern"],
+    binaryKinds: ["boolean_operator"],
+    operatorField: "operator",
+    logicalAndOperators: ["and"],
+    logicalOrOperators: ["or"],
+    jumpKinds: ["return_statement", "raise_statement", "break_statement", "continue_statement"],
+    blockKinds: ["block"],
+    consequenceField: "consequence",
+    // `elif_clause` UND `else_clause` stehen beide im Feld `alternative`.
+    // Genau deshalb ist ein `if` mit `elif` kein Waechter (`guard`), sondern
+    // ein `if` — was `adapters.test.ts` festhaelt.
+    alternativeField: "alternative",
+  },
+
+  // Die Importe wertet `profile.ts` aus: Python fuehrt in EINER Anweisung
+  // mehrere Ziele mit je eigenem Alias, und das druecken `ImportRules` nicht
+  // aus. Die Arten stehen hier, damit das Vorsieb (`needsNode`) sie kennt.
+  imports: {
+    kinds: ["import_statement", "import_from_statement", "future_import_statement"],
+  },
+
+  calls: {
+    kinds: ["call"],
+    functionField: "function",
+    argumentsField: "arguments",
+    memberKinds: ["attribute"],
+  },
+
+  declarationParentKinds: ["function_definition", "class_definition"],
+
+  bodyField: "body",
+};