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

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

@@ -0,0 +1,240 @@
+/**
+ * Die Adapterfabrik des ast-grep-Backends.
+ *
+ * Sie baut aus einer Sprachtabelle (`shared/table-profile.ts`) einen
+ * vollstaendigen `LanguageAdapter` (domain `analysis.ts`) — mit DEMSELBEN
+ * Walk, DENSELBEN Diagnosen, DENSELBEN Fingerabdruecken und DEMSELBEN
+ * Regionenbau wie der tree-sitter-Weg. `chunker`, `complexity`, `file-graph`
+ * und `symbol-graph` koennen nicht erkennen, welches Backend gelaufen ist;
+ * genau das ist die Zusage.
+ *
+ * WAS SICH ZWISCHEN DEN BACKENDS UNTERSCHEIDET, und wo es steht:
+ *
+ *  1. GROESSENGRENZE. Die 32-KiB-Puffergrenze der nativen tree-sitter-Bindung
+ *     (`shared/parse-limits.ts`, WP-215) gibt es hier NICHT: ast-grep nimmt
+ *     84 KB, 167 KB, 1 MB und 4 MB ohne jede Option. Dafuer kostet der Walk
+ *     mehr Speicher, also gilt eine EIGENE, niedrigere Obergrenze
+ *     ({@link MAX_ASTGREP_SOURCE_BYTES}) — begruendet unten.
+ *
+ *  2. FEHLENDE KNOTEN. tree-sitter misst sie (`nodeIsMissing`), ast-grep hat
+ *     dafuer nichts. Der Cursor liefert hier eine Heuristik, und JEDE daraus
+ *     entstehende Diagnose sagt das in ihrem Text
+ *     (`collectParseDiagnostics(..., "heuristic")`). `missingNodeCount` bleibt
+ *     eine Zahl — aber eine, deren Herkunft in der Ausgabe steht (E4).
+ *
+ *  3. VERSIONIERUNG. Ein anderer Parser erzeugt eine andere AST-Form und damit
+ *     andere Chunk-IDs und Fingerabdruecke. Sichtbar wird das ueber
+ *     `parserVersionForLanguage` (domain `versions.ts`), das fuer jede
+ *     ast-grep-Sprache eine eigene `parser_version` liefert. Ohne sie lieferten
+ *     die inhaltsadressierten Caches aus WP-100 stillschweigend Altes.
+ */
+import type {
+  AstRegion,
+  ComplexityFacts,
+  HalsteadTokens,
+  LanguageAdapter,
+  ParsedAst,
+  ParseResult,
+  RawCall,
+  RawImport,
+  SourceFile,
+} from "@untangle-code/domain";
+import { AdapterParseError } from "@untangle-code/domain";
+
+import { buildByteOffsetTable } from "../../text/byte-offset-table.js";
+import { buildFileRegion } from "../shared/chunks.js";
+import type { AnalysisResult } from "../shared/engine.js";
+import { analyzeTree } from "../shared/engine.js";
+import { extractedSymbolsOf } from "../shared/extract-symbols.js";
+import type { FileTextContext } from "../shared/node-utils.js";
+import { collectParseDiagnostics } from "../shared/parse-diagnostics.js";
+import type { LanguageProfile } from "../shared/profile.js";
+import type { SyntaxNode } from "../shared/syntax.js";
+import type { LanguageKindTable } from "../shared/table-profile.js";
+import { createTableProfile, fieldNamesOf } from "../shared/table-profile.js";
+
+import { astGrepParse, registerAstGrepLanguage } from "./napi.js";
+import { AstGrepSyntaxNode } from "./syntax.js";
+
+/**
+ * Obergrenze fuer eine einzelne Quelldatei, in Bytes — 5 MiB.
+ *
+ * WARUM NIEDRIGER ALS BEIM TREE-SITTER-WEG (8 MiB, `shared/parse-limits.ts`):
+ * der Walk kostet hier mehr Speicher, weil jeder Abstieg ueber `children()`
+ * geht und dabei je Knoten JS-Wrapper entstehen. SELBST GEMESSEN ueber diesen
+ * Adapter (`parse()` + `computeComplexity()`, generierter Go-Quelltext, je
+ * Groesse ein EIGENER Prozess, `maxRSS` aus `process.resourceUsage()`,
+ * darwin/arm64, Node 26.7.0):
+ *
+ *     Bytes     Knoten      parse     walk      Spitzen-RSS
+ *     1 MiB       490.959   1.897 ms  12.289 ms   1.048 MiB
+ *     2 MiB       976.521   3.087 ms  11.699 ms   2.719 MiB
+ *     4 MiB     1.937.712   5.803 ms  45.863 ms   2.098 MiB
+ *
+ * Die RSS-Spalte ist ERKENNBAR VERRAUSCHT (4 MiB unter 2 MiB), weil die
+ * napi-Finalisierer auf der Ereignisschleife laufen und ein synchroner Lauf
+ * sie nicht drankommen laesst — dieselbe Beobachtung machte die Erkundung.
+ * Verlaesslich ist nur die Groessenordnung: rund ein Gigabyte je Megabyte
+ * Quelltext, und damit rund das Vierfache des tree-sitter-Weges.
+ *
+ * DIE GRENZE IST DESHALB DIE SCANNERGRENZE: 5 MiB, genau die Vorgabe aus
+ * `packages/scanner/src/discovery.ts`. Damit ist der Parser bei
+ * Standardkonfiguration NIE die engere, unausgesprochene Grenze — jede Datei,
+ * die der Scanner durchlaesst, nimmt er auch an —, und zugleich bleibt der
+ * Speicherbedarf im messbaren Bereich. Wer die Scannergrenze bewusst anhebt,
+ * bekommt hier einen benannten Grund (`file_too_large`) statt eines Absturzes.
+ *
+ * NICHT GELOEST, und hier ausdruecklich vermerkt: 12 bis 46 Sekunden Walk je
+ * Megabyte sind ein eigener Leistungsdefekt dieses Weges (der tree-sitter-Weg
+ * misst an vergleichbarer Stelle rund sechs Sekunden je Megabyte). Diese
+ * Grenze verhindert nur, dass er in einen Speicherabsturz umschlaegt.
+ */
+export const MAX_ASTGREP_SOURCE_BYTES = 5 * 1024 * 1024;
+
+/** Der undurchsichtige Inhalt von `ParsedAst.root` fuer dieses Backend. */
+interface AstGrepAstRoot {
+  root: AstGrepSyntaxNode;
+  ctx: FileTextContext;
+  fileId: string;
+  profile: LanguageProfile;
+}
+
+const analysisCache = new WeakMap<ParsedAst, AnalysisResult>();
+
+/**
+ * Wie in `shared/create-adapter.ts`: `ComplexityFacts.parseDiagnostics` ist der
+ * EINZIGE Kanal, ueber den nachgelagerte Rechnungen von einem beschaedigten
+ * Baum erfahren. `analyzeTree` sieht die Diagnosen nicht — sie entstehen in
+ * `parse()` und haengen am `ParsedAst`.
+ */
+function getAnalysis(ast: ParsedAst): AnalysisResult {
+  const cached = analysisCache.get(ast);
+  if (cached !== undefined) return cached;
+  const root = ast.root as AstGrepAstRoot;
+  const analyzed = analyzeTree(root.root, root.ctx, root.fileId, root.profile);
+  const result: AnalysisResult = {
+    ...analyzed,
+    facts: { ...analyzed.facts, parseDiagnostics: ast.diagnostics },
+  };
+  analysisCache.set(ast, result);
+  return result;
+}
+
+/** Welches npm-Paket die Grammatik einer Sprache liefert. */
+export interface AstGrepLanguageSource {
+  /** Name, unter dem ast-grep die Sprache fuehrt (`parse(name, ...)`). */
+  languageName: string;
+  /** Sprachpaket, EINZELN aufgenommen — nie eine Sammelabhaengigkeit (450 MB fuer 22 Sprachen). */
+  moduleName: string;
+}
+
+/**
+ * Haken fuer eine Sprache, deren Regeln eine Tabelle NICHT ausdrueckt.
+ *
+ * WOFUER, an einem echten Fall: Python bindet den Doc-Kommentar nicht an ein
+ * Kommentarzeichen, sondern an die erste Anweisung des Rumpfes; seine
+ * Sichtbarkeit steht in einer Namenskonvention statt in einem Modifikator;
+ * und `__all__` gilt je DATEI, nicht je Knoten. Das erste und zweite koennte
+ * eine Tabelle notfalls noch beschreiben, das dritte nicht: es braucht einen
+ * Zustand, den es erst gibt, wenn die Datei geparst ist.
+ *
+ * Deshalb DIESER Zuschnitt und kein anderer: der Haken bekommt das fertige
+ * Tabellenprofil, den Wurzelknoten und die Datei und darf daraus ein
+ * VERFEINERTES Profil bauen. Er laeuft genau einmal je Parse — nicht je
+ * Knoten —, und wer ihn nicht setzt, bezahlt nichts.
+ */
+export interface AstGrepAdapterHooks {
+  readonly profileForFile?: (
+    base: LanguageProfile,
+    root: SyntaxNode,
+    file: SourceFile,
+  ) => LanguageProfile;
+}
+
+/**
+ * Baut einen `LanguageAdapter` ueber ast-grep. Die Anmeldung der Sprache
+ * kostet hier nichts: kein `require`, keine Grammatik, kein natives Modul —
+ * das passiert erst beim ersten `parse()` einer ast-grep-Sprache, und dann
+ * fuer alle angemeldeten auf einmal (`napi.ts`, Eigenheit 1).
+ */
+export function createAstGrepAdapter(
+  table: LanguageKindTable,
+  source: AstGrepLanguageSource,
+  hooks: AstGrepAdapterHooks = {},
+): LanguageAdapter {
+  const profile = createTableProfile(table);
+  const fieldNames = fieldNamesOf(table);
+  registerAstGrepLanguage(source.languageName, source.moduleName);
+
+  return {
+    languageId: table.languageId,
+    extensions: [...table.extensions],
+    supportLevel: table.supportLevel,
+
+    parse(file: SourceFile): ParseResult {
+      const byteLength = Buffer.byteLength(file.content, "utf8");
+      if (byteLength > MAX_ASTGREP_SOURCE_BYTES) {
+        throw new AdapterParseError(
+          "file_too_large",
+          `Source text with ${String(byteLength)} bytes exceeds the ast-grep parser limit of ` +
+            `${String(MAX_ASTGREP_SOURCE_BYTES)} Bytes.`,
+          {
+            measurements: { sizeBytes: byteLength, limitBytes: MAX_ASTGREP_SOURCE_BYTES },
+          },
+        );
+      }
+
+      // KEIN `bufferSize` und keine 32-KiB-Grenze: die gibt es nur in der
+      // nativen tree-sitter-Bindung (`shared/parse-limits.ts`). Nachgeprueft
+      // an 84 KB, 167 KB, 1 MB und 4 MB — ast-grep nimmt sie ohne Option an.
+      const rootNode = astGrepParse(source.languageName, file.content);
+      const root = new AstGrepSyntaxNode(rootNode, fieldNames);
+
+      const byteTable = buildByteOffsetTable(file.content);
+      const ctx: FileTextContext = { sourceText: file.content, byteTable };
+      const { parseQuality, diagnostics, errorNodeCount, missingNodeCount } =
+        collectParseDiagnostics(root, ctx, "heuristic");
+
+      if (parseQuality === "failed") {
+        return { parseQuality, ast: null, diagnostics, errorNodeCount, missingNodeCount };
+      }
+
+      const fileProfile = hooks.profileForFile?.(profile, root, file) ?? profile;
+      const astRoot: AstGrepAstRoot = { root, ctx, fileId: file.fileId, profile: fileProfile };
+      return {
+        parseQuality,
+        ast: { languageId: table.languageId, parseQuality, root: astRoot, diagnostics },
+        diagnostics,
+        errorNodeCount,
+        missingNodeCount,
+      };
+    },
+
+    extractChunks(ast): AstRegion[] {
+      const { scopeTree } = getAnalysis(ast);
+      const root = ast.root as AstGrepAstRoot;
+      return [buildFileRegion(scopeTree, root.ctx, root.profile)];
+    },
+
+    extractSymbols(ast) {
+      return extractedSymbolsOf(getAnalysis(ast).scopeTree);
+    },
+
+    extractImports(ast): RawImport[] {
+      return getAnalysis(ast).imports;
+    },
+
+    extractCalls(ast): RawCall[] {
+      return getAnalysis(ast).calls;
+    },
+
+    computeComplexity(ast): ComplexityFacts {
+      return getAnalysis(ast).facts;
+    },
+
+    tokenizeForHalstead(ast): HalsteadTokens {
+      const { facts } = getAnalysis(ast);
+      return { operators: facts.operators, operands: facts.operands };
+    },
+  };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Oeffentliche Einstiegspunkte des ast-grep-Backends.
+ *
+ * WELCHE SPRACHE UEBER WELCHEN WEG LAEUFT, steht in `README.md` neben dieser
+ * Datei — mit der Messung, auf der die Aufteilung beruht.
+ */
+import type { LanguageAdapter } from "@untangle-code/domain";
+
+import { createAstGrepAdapter } from "./adapter.js";
+import { AST_GREP_LANGUAGES } from "./lang/index.js";
+import { GO_SOURCE, GO_TABLE, RUST_SOURCE, RUST_TABLE } from "./languages.js";
+
+export { createAstGrepAdapter, MAX_ASTGREP_SOURCE_BYTES } from "./adapter.js";
+export type { AstGrepAdapterHooks, AstGrepLanguageSource } from "./adapter.js";
+export { GO_SOURCE, GO_TABLE, RUST_SOURCE, RUST_TABLE } from "./languages.js";
+export { AST_GREP_LANGUAGES } from "./lang/index.js";
+export type { AstGrepLanguage } from "./lang/index.js";
+export { astGrepLanguageStates, astGrepLanguageStatus } from "./napi.js";
+export type { AstGrepLanguageStatus } from "./napi.js";
+
+/** Go-Adapter ueber ast-grep (`@ast-grep/lang-go`). */
+export function createGoAdapter(): LanguageAdapter {
+  return createAstGrepAdapter(GO_TABLE, GO_SOURCE);
+}
+
+/** Rust-Adapter ueber ast-grep (`@ast-grep/lang-rust`). */
+export function createRustAdapter(): LanguageAdapter {
+  return createAstGrepAdapter(RUST_TABLE, RUST_SOURCE);
+}
+
+/**
+ * Die WEITEREN Sprachen aus WP-86 (Java, C#, Ruby, PHP, Kotlin, C, C++, Swift,
+ * Bash) — je eine Tabelle unter `lang/`, kein Motor.
+ *
+ * Sie kommen als LISTE und nicht als neun einzelne Fabriken, damit
+ * `languages/index.ts` mit EINER Schleife auskommt: wer die zehnte Sprache
+ * aufnimmt, schreibt eine Tabelle und eine Zeile in `lang/index.ts` — und
+ * faesst weder diese Datei noch die Registrierung an.
+ */
+export function createBreadthAdapters(): LanguageAdapter[] {
+  return AST_GREP_LANGUAGES.map((language) =>
+    createAstGrepAdapter(language.table, language.source),
+  );
+}

package/src/languages/astgrep-backend/lang/README.md

@@ -0,0 +1,115 @@
+<a id="sprachbreite-über-ast-grep-wp-86"></a>
+
+# Language breadth through ast-grep (WP-86)
+
+Nine languages, one table each, no new engine. This file is the **countercheck for the ratchet**
+in `vision.md` §1b: if adding a language costs 800 lines, nothing has been gained.
+
+<a id="was-eine-sprache-gekostet-hat--nachgezählt-nicht-geschätzt"></a>
+
+## Cost per language — counted, not estimated
+
+`wc -l` over tables. "Code only" excludes comments and blank lines; comments explain the
+interpretation and are intentional, not incidental.
+
+| Language | File | Total lines | Code only |
+|---|---|---:|---:|
+| C++ | `cpp.ts` | 65 | 39 |
+| Bash | `bash.ts` | 78 | 42 |
+| Ruby | `ruby.ts` | 105 | 70 |
+| PHP | `php.ts` | 105 | 84 |
+| Java | `java.ts` | 115 | 86 |
+| Swift | `swift.ts` | 118 | 83 |
+| C | `c.ts` | 119 | 85 |
+| C# | `csharp.ts` | 125 | 96 |
+| Kotlin | `kotlin.ts` | 133 | 81 |
+| **Nine-language total** | | **963** | **666** |
+| Registration of all nine | `index.ts` | 61 | 46 |
+
+**Median per language: 115 lines, including 84 code lines.** Exploration estimated 200–400 lines
+per language, more than twice the measured cost.
+
+`cpp.ts` explains why: **C++ costs 39 code lines** because its grammar extends C and the table
+specifies only the **difference**: classes, namespaces, `try`/`catch`, lambdas. Related languages
+must not pay twice for the same thing; doing so means the table boundary is wrong.
+
+<a id="was-einmalig-dazukam"></a>
+
+## One-time additions
+
+`shared/table-profile.ts` grew from **659 to 911 lines (+252)**. Those 252 lines support **all
+eleven** ast-grep languages, not just WP-86's nine:
+
+| Addition | Purpose |
+|---|---|
+| `caseExcludeChildKinds`, `caseExcludeFirstChildText` | Catch-all arms do not count; Java, C, C# and Bash use the SAME node kind for `case` and `default` |
+| `elseIfKinds` | Ruby `elsif`, PHP `else_if_clause` and Bash `elif_clause` have separate node kinds |
+| `guardKinds` | Swift `guard` is a dedicated early-return keyword |
+| `patternAlternativeKinds`, `shortCircuitKinds` | Rust `Some(1) \| Some(2)` and `?` |
+| `anonymousOperatorKinds` | Kotlin, Swift and Bash store `&&`/`\|\|` as anonymous children rather than fields |
+| `nameKindPath`, `nameDescend` | C# fields (`variable_declaration > variable_declarator.name`), C declarator chains (`*ring_new`), PHP/Kotlin/Swift properties |
+| `parentKinds` | `var i = 0` in function bodies is NOT a symbol (Kotlin, Swift) |
+| `visibilityWords` | Java `modifiers` stores `private final static` in ONE node |
+| `receiverField`, `acceptCall` | Separate Java/Ruby receivers; Swift `items["a"]` is indexing, not a call |
+
+**Overall:** 963 table lines + 252 one-time extension lines = **1,215 lines for nine languages**,
+or **135 lines per language**. For comparison, the package's handwritten Python adapter has
+5,604 lines for **one** language.
+
+<a id="was-gemessen-ist-und-was-nicht"></a>
+
+## What was and was not measured
+
+**Measured** (`golden.test.ts`, 21 tests, all passing): one real example file per language,
+pinning parse quality (`complete`, zero error nodes), the full symbol list by qualified name and
+kind, counts per decision kind, comments, imports and sampled calls. Eight languages additionally
+verify that `switch`/`match`/`case` catch-all arms do **not** count; Rust `?` contributes to extended
+but not classic complexity.
+
+**Not measured:** none of these grammars ran against a real project in its language. Example
+files are 53–93 lines, handwritten to expose language characteristics. They support the
+interpretation, not robustness across 100,000 lines of external code. `@ast-grep/lang-swift` is
+version 0.0.8 and carries the greatest risk here.
+
+<a id="lizenzen-und-plattformen"></a>
+
+## Licenses and platforms
+
+Embedded tree-sitter grammars, their authors and platforms **without** prebuilds are documented in
+`../GRAMMARS.md`, NOT `THIRD_PARTY_LICENSES.md`. That file is generated from production dependencies;
+grammars are `devDependencies` *inside* language packages, invisible to the generator.
+
+<a id="die-auslegung-der-entscheidungspunkte--wo-sie-nicht-gleich-ist"></a>
+
+## Decision-point interpretation — where languages differ
+
+Rules are **not** identical across languages. Each table's header explains deviations; overview:
+
+| Construct | Interpretation | Rationale location |
+|---|---|---|
+| Catch-all arm (`default`, `_`, `else ->`, `*)`) | **Never** counts | Every table |
+| Go `select` | Each `communication_case` counts, a real runtime branch | `../languages.ts` |
+| Rust `match` | Each arm counts except catch-all `_` | `../languages.ts` |
+| Rust `?` | `short_circuit`, **extended only**, never classic | `../languages.ts` |
+| `finally`/`ensure` | Does **not** count; always runs, no branch | `java.ts`, `ruby.ts` |
+| Ruby postfix forms (`x if y`) | Count like their long form | `ruby.ts` |
+| C preprocessor (`#ifdef`) | Does **not** count; compilation, not runtime branching | `c.ts` |
+| C#/Ruby `?.` and `&.` | Do **not** count; null safety, not case distinction | `csharp.ts`, `ruby.ts` |
+| Bash pipes (`\|`) | Do **not** count; chaining, not branching | `bash.ts` |
+| Kotlin `else if` | **Not** recognized as continuation; cognitive readings are higher | `kotlin.ts` |
+
+<a id="bekannte-ungenauigkeiten-benannt-statt-verschwiegen"></a>
+
+## Known inaccuracies, stated explicitly
+
+- **Kotlin and Swift:** grammars provide no field names. `normalizedSignature` uses the first
+  line rather than the header up to the body; `IdentifierFact.role` is always `reference` because
+  a declaration classification would be guessed.
+- **C++:** constructors have the same node kind as other methods and appear as `function`, not
+  `constructor`.
+- **Ruby:** no visibility (`private` is a call, not a symbol modifier) and no imports (`require`
+  is an ordinary method call, appearing in `extractCalls`).
+- **Bash:** no imports (`source` is a command); `set`, `return` and other built-ins appear as calls.
+- **Kotlin:** `companion object` members appear flat on the class.
+- **PHP:** with semicolon-form `namespace App\Billing;`, following classes are NOT nested under
+  the namespace because the grammar does not nest them.

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

@@ -0,0 +1,78 @@
+/**
+ * Bash (WP-86).
+ *
+ * WAS EINE SHELL AN SYMBOLEN HAT: Funktionen. Mehr nicht — keine Klassen,
+ * keine Typen, keine Namensraeume. Das ist kein Mangel des Adapters, sondern
+ * der Sprache, und deshalb steht hier eine kurze Tabelle statt einer
+ * erfundenen Struktur.
+ *
+ * VARIABLENZUWEISUNGEN AUF OBERSTER EBENE SIND KEINE SYMBOLE. In einer Shell
+ * ist jede Zuweisung eine Anweisung; die Grenze zwischen "Konstante" und
+ * "Zwischenwert" steht nicht im Syntaxbaum. `MAX_RETRIES=3` und
+ * `attempt=$((attempt + 1))` als gleichrangige Symbole zu fuehren waere eine
+ * falsche Aussage ueber die Datei.
+ *
+ * ENTSCHEIDUNGSPUNKTE (spec.md §16.2/§16.3):
+ *   - `while_statement` deckt AUCH `until` ab — dieselbe Knotenart mit anderem
+ *     Schluesselwort.
+ *   - `elif_clause` ist eine eigene Knotenart und damit direkt ein `else_if`.
+ *   - `case_item` zaehlt als `case`. Der Auffangzweig `*)` zaehlt NICHT: sein
+ *     Muster ist genau `*` (`caseExcludeFirstChildText`).
+ *   - `&&`/`||` zwischen Kommandos stehen in einem `list`-Knoten und tragen
+ *     den Operator als anonymes Kind (`anonymousOperatorKinds`). Sie zaehlen
+ *     nur ERWEITERT. In der Shell ist `cmd || exit 1` idiomatisch ein
+ *     Fehlerpfad und kein reiner Kurzschluss; die konservative Auslegung haelt
+ *     die Zahl mit den anderen zehn Sprachen vergleichbar.
+ *   - PIPES (`|`) zaehlen NICHT: sie verketten, sie verzweigen nicht.
+ *
+ * IMPORTE: `source datei` und `. datei` sind gewoehnliche Kommandos, keine
+ * eigene Knotenart. Die Tabelle koennte sie nicht von einer selbstgeschriebenen
+ * Funktion gleichen Namens unterscheiden — dieser Adapter meldet deshalb KEINE
+ * Importe. Wer sie braucht, sieht sie in `extractCalls` als Aufruf von
+ * `source`.
+ */
+import type { LanguageKindTable } from "../../shared/table-profile.js";
+import type { AstGrepLanguageSource } from "../adapter.js";
+
+export const BASH_SOURCE: AstGrepLanguageSource = {
+  languageName: "bash",
+  moduleName: "@ast-grep/lang-bash",
+};
+
+export const BASH_TABLE: LanguageKindTable = {
+  languageId: "shell",
+  extensions: [".sh", ".bash", ".zsh", ".ksh"],
+  supportLevel: "deep",
+  commentKinds: ["comment"],
+  stringContainerKinds: ["string", "raw_string", "ansi_c_string", "heredoc_body"],
+  identifierLeafKinds: [
+    "variable_name",
+    "special_variable_name",
+    "word",
+    "extglob_pattern",
+    "simple_expansion",
+  ],
+  numberLeafKinds: ["number"],
+  scopes: [{ kinds: ["function_definition"], scopeKind: "function", nameKinds: ["word"] }],
+  decisions: {
+    ifKinds: ["if_statement"],
+    elseIfKinds: ["elif_clause"],
+    loopKinds: ["while_statement", "for_statement", "c_style_for_statement"],
+    switchKinds: ["case_statement"],
+    caseKinds: ["case_item"],
+    caseExcludeFirstChildText: "*",
+    anonymousOperatorKinds: ["list"],
+    logicalAndOperators: ["&&"],
+    logicalOrOperators: ["||"],
+    jumpKinds: [],
+    blockKinds: ["compound_statement", "do_group"],
+  },
+  // Siehe Modulkopf: die Shell hat keine Importanweisung.
+  imports: { kinds: [] },
+  calls: {
+    kinds: ["command"],
+    functionField: "name",
+  },
+  declarationParentKinds: [],
+  fieldNames: ["name"],
+};

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

@@ -0,0 +1,119 @@
+/**
+ * C (WP-86).
+ *
+ * DER EINE BESONDERE PUNKT: C schreibt den Namen einer Funktion nicht in ein
+ * `name`-Feld, sondern in eine Kette von Deklaratoren.
+ * `ring_t *ring_new(size_t cap)` ergibt
+ * `function_definition.declarator` -> `pointer_declarator.declarator`
+ * -> `function_declarator.declarator` -> `identifier`. Dafuer gibt es
+ * `nameDescend`: demselben Feld folgen, solange es weiterfuehrt. Ohne das
+ * hiesse jede zeigerwertige Funktion `*ring_new(size_t cap)`.
+ *
+ * ABBILDUNGEN: `struct`/`union` -> `class`, `typedef` -> `type`.
+ *
+ * ENTSCHEIDUNGSPUNKTE (spec.md §16.2/§16.3):
+ *   - `case_statement` traegt `case X:` UND `default:` — nur die `case`-Form
+ *     zaehlt (`caseExcludeChildKinds`).
+ *   - C hat kein `try`/`catch`; die Art `catch` entsteht in C-Dateien nie.
+ *   - PRAEPROZESSORZWEIGE (`#ifdef`, `#if`) zaehlen NICHT. Sie sind
+ *     Uebersetzungs-, nicht Laufzeitverzweigungen: die uebersetzte Datei
+ *     enthaelt genau EINEN der Zweige. Beide zu zaehlen ergaebe eine Zahl, die
+ *     kein ausgefuehrter Pfad je erreicht. Das ist die konservative Auslegung;
+ *     sie UNTERSCHAETZT Dateien, die schwer per `#ifdef` verzweigen, und das
+ *     steht hier, damit niemand es aus der Zahl erraten muss.
+ *   - Es gibt keine Sichtbarkeit im Baum: `static` ist eine Speicherklasse,
+ *     kein Zugriffsmodifikator. `exportedNames` bleibt deshalb leer, ausser
+ *     bei einer Funktion OHNE `static` — die ist aus der Uebersetzungseinheit
+ *     heraus sichtbar, und das ist die einzige Aussage, die der Baum hergibt.
+ */
+import type { LanguageKindTable } from "../../shared/table-profile.js";
+import type { AstGrepLanguageSource } from "../adapter.js";
+
+export const C_SOURCE: AstGrepLanguageSource = {
+  languageName: "c",
+  moduleName: "@ast-grep/lang-c",
+};
+
+export const C_TABLE: LanguageKindTable = {
+  languageId: "c",
+  extensions: [".c", ".h"],
+  supportLevel: "deep",
+  commentKinds: ["comment"],
+  stringContainerKinds: ["string_literal", "char_literal", "system_lib_string"],
+  identifierLeafKinds: [
+    "identifier",
+    "field_identifier",
+    "type_identifier",
+    "primitive_type",
+    "statement_identifier",
+  ],
+  numberLeafKinds: ["number_literal"],
+  booleanLeafKinds: ["true", "false"],
+  nullLeafKinds: ["null"],
+  scopes: [
+    {
+      kinds: ["function_definition"],
+      scopeKind: "function",
+      nameField: "declarator",
+      nameDescend: true,
+    },
+    { kinds: ["struct_specifier", "union_specifier"], scopeKind: "class" },
+    { kinds: ["enum_specifier"], scopeKind: "enum" },
+    {
+      kinds: ["type_definition"],
+      scopeKind: "type",
+      nameField: "declarator",
+      nameDescend: true,
+    },
+    {
+      kinds: ["field_declaration"],
+      scopeKind: "property",
+      nameField: "declarator",
+      nameDescend: true,
+    },
+  ],
+  decisions: {
+    ifKinds: ["if_statement"],
+    elseIfParentKinds: ["else_clause"],
+    loopKinds: ["for_statement", "while_statement", "do_statement"],
+    ternaryKinds: ["conditional_expression"],
+    switchKinds: ["switch_statement"],
+    caseKinds: ["case_statement"],
+    caseExcludeChildKinds: ["default"],
+    binaryKinds: ["binary_expression"],
+    operatorField: "operator",
+    logicalAndOperators: ["&&"],
+    logicalOrOperators: ["||"],
+    jumpKinds: ["return_statement", "break_statement", "continue_statement", "goto_statement"],
+    blockKinds: ["compound_statement"],
+    consequenceField: "consequence",
+    alternativeField: "alternative",
+  },
+  imports: {
+    kinds: ["preproc_include"],
+    // Der Spezifizierer behaelt seine SPITZEN KLAMMERN: `<stdlib.h>` ist eine
+    // Systemeinbindung, `"ring.h"` eine im Projekt. Die Klammern hier zu
+    // entfernen wuerde die beiden Faelle ununterscheidbar machen — und die
+    // Aufloesung im `file-graph` haengt genau daran.
+    pathField: "path",
+  },
+  calls: {
+    kinds: ["call_expression"],
+    functionField: "function",
+    argumentsField: "arguments",
+    memberKinds: ["field_expression"],
+  },
+  declarationParentKinds: [
+    "struct_specifier",
+    "union_specifier",
+    "enum_specifier",
+    "enumerator",
+    "function_declarator",
+  ],
+  bodyField: "body",
+  isExported: (_name, node) =>
+    !node.children.some(
+      (child) => child.type === "storage_class_specifier" && child.text === "static",
+    ),
+  fieldNames: ["name", "declarator"],
+};

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

@@ -0,0 +1,65 @@
+/**
+ * C++ (WP-86) — DER BELEG FUER DIE RATSCHE.
+ *
+ * Die C++-Grammatik ist eine ERWEITERUNG der C-Grammatik: jede Knotenart aus
+ * `c.ts` kommt in C++ genauso vor. Deshalb steht hier keine zweite Tabelle,
+ * sondern die DIFFERENZ — Klassen, Namensraeume, `try`/`catch`, Lambdas,
+ * bereichsbasierte `for`-Schleifen. Elf Sprachen ergaenzen heisst nicht elfmal
+ * dieselbe Arbeit; wo zwei Sprachen verwandt sind, muss die zweite billiger
+ * sein als die erste, sonst haben wir nichts gewonnen.
+ *
+ * ABBILDUNGEN ZUSAETZLICH ZU C: `class` -> `class`, `namespace` ->
+ * `namespace`. `template_declaration` ist KEIN eigenes Symbol: es umhuellt
+ * die Funktion oder Klasse, die es parametrisiert, und die ist der Scope.
+ *
+ * ENTSCHEIDUNGSPUNKTE ZUSAETZLICH ZU C: `catch_clause` zaehlt als `catch`,
+ * `for_range_loop` als Schleife. `co_await`/`co_yield` zaehlen NICHT — sie
+ * unterbrechen den Ablauf, verzweigen ihn aber nicht.
+ *
+ * SICHTBARKEIT: C++ fuehrt sie als ABSCHNITTSMARKE (`access_specifier`
+ * `public:`), nicht am Mitglied. Sie ist damit ohne Positionsvergleich nicht
+ * am Symbol ablesbar — der Adapter meldet deshalb keine, statt eine zu raten.
+ */
+import type { LanguageKindTable } from "../../shared/table-profile.js";
+import type { AstGrepLanguageSource } from "../adapter.js";
+
+import { C_TABLE } from "./c.js";
+
+export const CPP_SOURCE: AstGrepLanguageSource = {
+  languageName: "cpp",
+  moduleName: "@ast-grep/lang-cpp",
+};
+
+const { isExported: _cIsExported, ...C_TABLE_WITHOUT_EXPORT } = C_TABLE;
+
+export const CPP_TABLE: LanguageKindTable = {
+  ...C_TABLE_WITHOUT_EXPORT,
+  languageId: "cpp",
+  extensions: [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx"],
+  identifierLeafKinds: [
+    ...C_TABLE.identifierLeafKinds,
+    "namespace_identifier",
+    "qualified_identifier",
+    "this",
+    "destructor_name",
+    "operator_name",
+  ],
+  nullLeafKinds: [...(C_TABLE.nullLeafKinds ?? []), "nullptr"],
+  scopes: [
+    ...C_TABLE.scopes,
+    { kinds: ["class_specifier"], scopeKind: "class" },
+    { kinds: ["namespace_definition"], scopeKind: "namespace" },
+  ],
+  decisions: {
+    ...C_TABLE.decisions,
+    catchKinds: ["catch_clause"],
+    loopKinds: [...C_TABLE.decisions.loopKinds, "for_range_loop"],
+    jumpKinds: [...(C_TABLE.decisions.jumpKinds ?? []), "throw_statement"],
+  },
+  declarationParentKinds: [
+    ...C_TABLE.declarationParentKinds,
+    "class_specifier",
+    "namespace_definition",
+    "type_parameter_declaration",
+  ],
+};