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

package/src/boundaries/python.ts

@@ -0,0 +1,181 @@
+import type { HttpBoundaryFileFactsV1 } from "@untangle-code/domain";
+
+import type { FileTextContext } from "../languages/shared/node-utils.js";
+import { rangeOf } from "../languages/shared/node-utils.js";
+import type { SyntaxNode } from "../languages/shared/syntax.js";
+
+import { field, namedChildren, stringValue } from "./expression.js";
+import { scopeOf } from "./extract.js";
+
+const METHODS = new Set(["get", "post", "put", "delete", "patch", "head", "options", "trace"]);
+
+function keyword(node: SyntaxNode, name: string): SyntaxNode | null {
+  return (
+    namedChildren(node).find(
+      (child) => child.type === "keyword_argument" && field(child, "name")?.text === name,
+    ) ?? null
+  );
+}
+
+function prefix(node: SyntaxNode): string | null {
+  const value = keyword(node, "prefix");
+  return value === null ? "" : stringValue(field(value, "value"));
+}
+
+function importFacts(
+  nodes: readonly SyntaxNode[],
+  ctx: FileTextContext,
+  facts: HttpBoundaryFileFactsV1,
+): void {
+  for (const node of nodes) {
+    if (node.type !== "import_from_statement" || scopeOf(node) !== "module") continue;
+    const module = field(node, "module_name");
+    if (module === null) continue;
+    for (const child of namedChildren(node)) {
+      if (child.startIndex === module.startIndex) continue;
+      const name = child.type === "aliased_import" ? field(child, "name") : child;
+      const alias = child.type === "aliased_import" ? field(child, "alias") : child;
+      if (
+        name === null ||
+        alias === null ||
+        !["identifier", "dotted_name", "aliased_import"].includes(child.type)
+      )
+        continue;
+      facts.pythonImports.push({
+        module: module.text,
+        local: alias.text,
+        imported: name.text,
+        range: rangeOf(child, ctx),
+      });
+    }
+  }
+}
+
+function expandedIncludeTargets(node: SyntaxNode, target: SyntaxNode): string[] {
+  if (target.type !== "identifier") return [target.text];
+  let parent = node.parent;
+  while (parent !== null) {
+    if (parent.type === "for_statement" && field(parent, "left")?.text === target.text) {
+      const right = field(parent, "right");
+      if (right !== null && ["tuple", "list"].includes(right.type)) {
+        const items = namedChildren(right);
+        if (items.every((item) => item.type === "attribute" || item.type === "identifier"))
+          return items.map((item) => item.text);
+      }
+      return ["<dynamic-router-iteration>"];
+    }
+    if (parent.type === "function_definition") break;
+    parent = parent.parent;
+  }
+  return [target.text];
+}
+
+/** Only FastAPI-imported constructors, literal prefixes and actual decorated functions produce routes. */
+export function extractPythonHttpFacts(
+  nodes: readonly SyntaxNode[],
+  ctx: FileTextContext,
+  facts: HttpBoundaryFileFactsV1,
+): void {
+  importFacts(nodes, ctx, facts);
+  const constructorNames = new Map(
+    facts.pythonImports
+      .filter(
+        (item) =>
+          item.module === "fastapi" && ["FastAPI", "APIRouter"].includes(item.imported ?? ""),
+      )
+      .map((item) => [item.local, item.imported]),
+  );
+  for (const node of nodes) {
+    if (node.type === "assignment") {
+      const left = field(node, "left"),
+        right = field(node, "right");
+      if (left?.type !== "identifier" || right?.type !== "call") continue;
+      const kind = constructorNames.get(field(right, "function")?.text ?? "");
+      const args = field(right, "arguments");
+      if (kind === undefined || args === null) continue;
+      const constructorName = field(right, "function")?.text;
+      let scope = scopeOf(node);
+      let parameterShadow = false;
+      for (let depth = 0; depth < 30 && scope !== "module"; depth += 1) {
+        const fn = facts.functions.find((candidate) => candidate.scope === scope);
+        if (fn?.parameters.some((parameter) => parameter.name === constructorName))
+          parameterShadow = true;
+        scope = fn?.parentScope ?? "module";
+      }
+      if (
+        parameterShadow ||
+        facts.pythonImports.filter((item) => item.local === constructorName).length !== 1 ||
+        facts.bindings.some((binding) => binding.name === constructorName) ||
+        facts.functions.some((fn) => fn.name === constructorName)
+      ) {
+        facts.limitations.push(`FastAPI constructor ${constructorName ?? "<unknown>"} is shadowed`);
+        continue;
+      }
+      facts.routers.push({
+        name: left.text,
+        scope: scopeOf(node),
+        kind: kind === "FastAPI" ? "app" : "router",
+        prefix: prefix(args),
+        range: rangeOf(node, ctx),
+      });
+    }
+    if (node.type === "decorated_definition") {
+      const handler = namedChildren(node).find((child) => child.type === "function_definition");
+      if (handler === undefined) continue;
+      for (const decorator of namedChildren(node).filter((child) => child.type === "decorator")) {
+        const call = namedChildren(decorator)[0];
+        if (call?.type !== "call") continue;
+        const callee = field(call, "function");
+        if (callee?.type !== "attribute") continue;
+        const method = field(callee, "attribute")?.text;
+        const object = field(callee, "object");
+        const args = field(call, "arguments");
+        if (
+          method === undefined ||
+          !METHODS.has(method) ||
+          object?.type !== "identifier" ||
+          args === null
+        )
+          continue;
+        const first = namedChildren(args).find((arg) => arg.type !== "keyword_argument");
+        facts.routes.push({
+          router: object.text,
+          scope: scopeOf(node),
+          method: method.toUpperCase(),
+          path: stringValue(first ?? null),
+          handler: field(handler, "name")?.text ?? "<unnamed>",
+          range: rangeOf(decorator, ctx),
+          handlerRange: rangeOf(handler, ctx),
+        });
+      }
+    }
+    if (node.type === "call") {
+      const callee = field(node, "function");
+      if (callee?.type === "attribute" && field(callee, "attribute")?.text === "mount") {
+        facts.limitations.push(
+          "ASGI app.mount routing is unsupported; app entrypoints cannot be inferred",
+        );
+      }
+      if (callee?.type !== "attribute" || field(callee, "attribute")?.text !== "include_router")
+        continue;
+      const owner = field(callee, "object"),
+        args = field(node, "arguments");
+      if (owner?.type !== "identifier" || args === null) continue;
+      const target = namedChildren(args).find((arg) => arg.type !== "keyword_argument");
+      if (target === undefined) continue;
+      for (const router of expandedIncludeTargets(node, target))
+        facts.includes.push({
+          owner: owner.text,
+          scope: scopeOf(node),
+          router,
+          prefix: prefix(args),
+          range: rangeOf(node, ctx),
+        });
+    }
+  }
+  // A partial module graph remains visible; no app/include discovery is inferred from path names.
+  if (facts.routes.length > 0 && facts.routers.length === 0)
+    facts.limitations.push(
+      "Route decorators have no proven FastAPI router constructor in this file",
+    );
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @untangle-code/parser-registry — the ONLY public export of this package.
+ *
+ * `createParserRegistry()` returns a `ParserRegistry` (domain `ports.ts`)
+ * with the TypeScript/JavaScript/TSX/JSX `LanguageAdapter`s already
+ * registered. Registration is cheap: no grammar is loaded until the first
+ * `parse()` call for that language (see `registry.ts` / `languages/shared/grammar-loader.ts`).
+ *
+ * `@untangle-code/core` (WP-23)'s public `createParserRegistry(config)`
+ * facade (spec.md §22) wraps this factory.
+ */
+import type { ParserRegistry } from "@untangle-code/domain";
+
+import { registerBuiltinLanguages } from "./languages/index.js";
+import { LazyParserRegistry } from "./registry.js";
+export { extractHttpBoundaryFacts } from "./boundaries/extract.js";
+
+export function createParserRegistry(): ParserRegistry {
+  const registry = new LazyParserRegistry();
+  registerBuiltinLanguages(registry);
+  return registry;
+}
+
+export { LazyParserRegistry } from "./registry.js";
+export { createTypeScriptAdapter } from "./languages/typescript/index.js";
+export { createJavaScriptAdapter } from "./languages/javascript/index.js";
+export { createTsxAdapter } from "./languages/tsx/index.js";
+export { createJsxAdapter } from "./languages/jsx/index.js";
+export { createVueAdapter } from "./languages/vue/index.js";
+export { createPythonAdapter } from "./languages/python/index.js";
+export {
+  createProseAdapter,
+  PROSE_LANGUAGE_ID,
+  PROSE_SYMBOL_KIND,
+} from "./languages/prose/index.js";
+export {
+  createStructuredTextAdapter,
+  STRUCTURED_TEXT_LANGUAGE_ID,
+} from "./languages/structured-text/index.js";
+export {
+  astGrepLanguageStates,
+  astGrepLanguageStatus,
+  createAstGrepAdapter,
+  createGoAdapter,
+  createRustAdapter,
+  MAX_ASTGREP_SOURCE_BYTES,
+} from "./languages/astgrep-backend/index.js";
+export type {
+  AstGrepLanguageSource,
+  AstGrepLanguageStatus,
+} from "./languages/astgrep-backend/index.js";

package/src/languages/__golden__/javascript-basic.json

@@ -0,0 +1,32 @@
+{
+  "languageId": "javascript",
+  "path": "basic.js",
+  "source": "const EventEmitterLike = require(\"./emitter\");\n\nexport class Logger {\n  #level = \"info\";\n\n  log(message) {\n    if (this.#level === \"info\" || this.#level === \"debug\") {\n      console.log(message);\n    }\n  }\n}\n\nexport function createLogger() {\n  return new Logger();\n}\n",
+  "expectedSymbols": [
+    { "name": "Logger", "kind": "class", "qualifiedName": "Logger", "exportedNames": ["Logger"] },
+    {
+      "name": "#level",
+      "kind": "property",
+      "qualifiedName": "Logger.#level",
+      "exportedNames": [],
+      "visibility": "private"
+    },
+    {
+      "name": "log",
+      "kind": "method",
+      "qualifiedName": "Logger.log",
+      "normalizedSignature": "log(message)",
+      "exportedNames": []
+    },
+    {
+      "name": "createLogger",
+      "kind": "function",
+      "qualifiedName": "createLogger",
+      "normalizedSignature": "createLogger()",
+      "exportedNames": ["createLogger"]
+    }
+  ],
+  "expectedImports": [{ "specifier": "./emitter", "importKind": "import" }],
+  "expectedCalls": [{ "calleeName": "log", "qualifier": "console" }, { "calleeName": "Logger" }],
+  "expectedDecisionKinds": ["if", "logical_or"]
+}

package/src/languages/__golden__/tsx-basic.json

@@ -0,0 +1,19 @@
+{
+  "languageId": "tsx",
+  "path": "basic.tsx",
+  "source": "import { useState } from \"react\";\n\nexport function Counter({ start }: { start: number }) {\n  const [count, setCount] = useState(start);\n  return (\n    <button onClick={() => setCount(count + 1)}>\n      {count > 0 ? \"positive\" : \"zero or negative\"}\n    </button>\n  );\n}\n",
+  "expectedSymbols": [
+    {
+      "name": "Counter",
+      "kind": "function",
+      "qualifiedName": "Counter",
+      "normalizedSignature": "Counter({ start }: { start: number })",
+      "exportedNames": ["Counter"]
+    }
+  ],
+  "expectedImports": [
+    { "specifier": "react", "importKind": "import", "importedNames": ["useState"] }
+  ],
+  "expectedCalls": [{ "calleeName": "useState" }, { "calleeName": "setCount" }],
+  "expectedDecisionKinds": ["ternary"]
+}

package/src/languages/__golden__/typescript-basic.json

@@ -0,0 +1,37 @@
+{
+  "languageId": "typescript",
+  "path": "basic.ts",
+  "source": "import { readFile } from \"node:fs\";\nexport { helper } from \"./helper\";\n\n/** Adds two numbers together. */\nexport function add(a: number, b: number = 1): number {\n  if (a > 0 && b > 0) {\n    return a + b;\n  } else if (a < 0) {\n    return -1;\n  }\n  return 0;\n}\n\nexport interface Point {\n  x: number;\n  y: number;\n}\n\nexport class Box {\n  private width: number = 0;\n\n  resize(value: number): void {\n    this.width = value;\n  }\n}\n",
+  "expectedSymbols": [
+    {
+      "name": "add",
+      "kind": "function",
+      "qualifiedName": "add",
+      "normalizedSignature": "add(a: number, b: number): number",
+      "exportedNames": ["add"],
+      "hasDocRange": true
+    },
+    { "name": "Point", "kind": "interface", "qualifiedName": "Point", "exportedNames": ["Point"] },
+    { "name": "Box", "kind": "class", "qualifiedName": "Box", "exportedNames": ["Box"] },
+    {
+      "name": "width",
+      "kind": "property",
+      "qualifiedName": "Box.width",
+      "normalizedSignature": "private width: number",
+      "exportedNames": []
+    },
+    {
+      "name": "resize",
+      "kind": "method",
+      "qualifiedName": "Box.resize",
+      "normalizedSignature": "resize(value: number): void",
+      "exportedNames": []
+    }
+  ],
+  "expectedImports": [
+    { "specifier": "node:fs", "importKind": "import", "importedNames": ["readFile"] },
+    { "specifier": "./helper", "importKind": "re_export", "importedNames": ["helper"] }
+  ],
+  "expectedCallCount": 0,
+  "expectedDecisionKinds": ["if", "logical_and", "else_if"]
+}

package/src/languages/astgrep-backend/GRAMMARS.md

@@ -0,0 +1,86 @@
+<a id="die-eingebetteten-grammatiken--herkunft-und-lizenz"></a>
+
+# Embedded grammars — provenance and licensing
+
+**Why this file is maintained manually** while `THIRD_PARTY_LICENSES.md` is generated:
+`pnpm third-party-licenses` reads the **production dependency tree**. Grammars are absent there:
+they are `devDependencies` **inside** `@ast-grep/lang-*` packages, used to generate `src/parser.c`
+and `prebuilds/*/parser.so`. Neither the generator nor `scripts/check-licenses.mjs` can see them.
+
+**The language packages themselves do not identify them.** An `@ast-grep/lang-*` LICENSE lists
+only *ast-grep* as copyright holder despite shipping another tree-sitter grammar. Relying on it
+would omit the actual authors. This mapping was checked in each installed language package's
+`devDependencies` block in `node_modules`, not guessed.
+
+<a id="sprachpakete-optionale-peer-abhängigkeiten-von-untangle-codeparser-registry"></a>
+
+## Language packages (optional peers of `@untangle-code/parser-registry`)
+
+| Language package | Version | `package.json` license | `LICENSE` file license |
+|---|---|---|---|
+| `@ast-grep/lang-go` | 0.0.6 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-rust` | 0.0.7 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-java` | 0.0.7 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-csharp` | 0.0.6 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-ruby` | 0.0.7 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-php` | 0.0.7 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-kotlin` | 0.0.7 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-c` | 0.0.6 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-cpp` | 0.0.6 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-swift` | 0.0.8 | ISC | MIT (ast-grep) |
+| `@ast-grep/lang-bash` | 0.0.8 | ISC | MIT (ast-grep) |
+
+ISC and MIT are both allowed by `scripts/check-licenses.mjs` and compatible with AGPL-3.0-only.
+The disagreement between `package.json` and LICENSE is a package characteristic, recorded rather
+than smoothed over.
+
+<a id="die-tatsächlich-eingebetteten-grammatiken"></a>
+
+## Grammars actually embedded
+
+From each language package's `devDependencies`. Every grammar is a separate work with its own
+authors; its license continues to apply to shipped `parser.c` and derived `parser.so` files.
+
+| Language package | Embedded grammar | Version | License |
+|---|---|---|---|
+| `@ast-grep/lang-go` | `tree-sitter-go` | 0.25.0 | MIT |
+| `@ast-grep/lang-rust` | `tree-sitter-rust` | — | MIT |
+| `@ast-grep/lang-java` | `tree-sitter-java` | 0.23.5 | MIT |
+| `@ast-grep/lang-csharp` | `tree-sitter-c-sharp` | 0.23.1 | MIT |
+| `@ast-grep/lang-ruby` | `tree-sitter-ruby` | 0.23.1 | MIT |
+| `@ast-grep/lang-php` | `tree-sitter-php` | 0.24.2 | MIT |
+| `@ast-grep/lang-kotlin` | `tree-sitter-kotlin` | 0.3.8 | MIT |
+| `@ast-grep/lang-c` | `tree-sitter-c` | 0.24.1 | MIT |
+| `@ast-grep/lang-cpp` | `tree-sitter-cpp` | 0.23.4 | MIT |
+| `@ast-grep/lang-swift` | `tree-sitter-swift` | 0.7.1 | MIT |
+| `@ast-grep/lang-bash` | `tree-sitter-bash` | 0.25.1 | MIT |
+
+All eleven use **MIT**, compatible with AGPL. Checked on 2026-09-05 against the registry
+(`npm view <package> license`) and installed language packages' `devDependencies`.
+
+<a id="warum-die-sprachpakete-optionale-peer-abhängigkeiten-sind"></a>
+
+## Why language packages are OPTIONAL peers
+
+Together the eleven packages occupy **294 MB** (measured through
+`du -sh node_modules/.pnpm/@ast-grep+lang-*`; Swift alone is 69 MB, C# 62 MB, Kotlin 42 MB).
+Every package ships C source AND prebuilds for five platforms.
+
+Normal `dependencies` would force every Untangle installation to download all eleven, even for
+TypeScript-only use. As **optional peers**, users install only what they need. An absent grammar
+produces `grammar_unavailable` with a named reason on first parse; callers turn that into a
+skip-ledger entry (E4). No adapter pretends to have parsed.
+
+<a id="plattformen-ohne-prebuild"></a>
+
+## Platforms without prebuilds
+
+Core `@ast-grep/napi` covers nine targets. **Language packages** cover only five: macOS x64,
+macOS arm64, Linux x64 glibc, Linux arm64 glibc and Windows x64.
+
+**Missing: Linux musl (Alpine), Windows arm64, Windows ia32, FreeBSD.** There, installing a
+language package **silently** fails: `postinstall` catches the build error and exits 0, so npm
+and pnpm report success. It becomes visible only when `napi.ts` reads `libraryPath` on first parse.
+
+This claim is **derived from package contents**—the existing `prebuilds/` directories—not executed
+on those platforms. Every measurement here ran on darwin/arm64.

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

@@ -0,0 +1,112 @@
+<a id="ast-grep-backend-wp-220"></a>
+
+# ast-grep backend (WP-220)
+
+This directory is the parser registry's SECOND backend. It uses the same `LanguageAdapter`
+contract as tree-sitter: `chunker`, `complexity`, `file-graph` and `symbol-graph` cannot tell which
+backend ran.
+
+<a id="die-regel-welche-sprache-laeuft-wo"></a>
+
+## Rule: which language uses which backend
+
+| Language | Backend | Reason |
+|---|---|---|
+| TypeScript, JavaScript, TSX, JSX | **tree-sitter** | Measured 3.74× faster traversal, lower memory use, complete `nodeIsMissing`, unchanged golden tests |
+| Python | Custom parser | Unchanged; replacement is prepared, not performed (see Open work) |
+| Markdown/prose, structured data | Custom adapters | `text` support, no syntax tree needed |
+| **Go, Rust** | **ast-grep** | Ready-made MIT-licensed grammars; these languages would not exist here without this backend |
+
+The split follows measurement rather than preference. ast-grep has **no cursor API**: descent
+uses `children()`, creating a fresh JS array of node wrappers every time. Repository-wide
+measurement (721 files, 1,143,212 nodes, both versions in one process):
+
+```
+tree-sitter Cursor : parse 256 ms   walk  671 ms  =>  1,703,642 nodes/s
+ast-grep children(): parse 347 ms   walk 2511 ms  =>    455,329 nodes/s
+                                    Factor 3.74; overhead 1.61 us per node
+```
+
+This matches the `.children` approach removed by WP-95. Switching the JS/TS family would regress
+the exact area repaired in wave 6, while each current dialect costs only nine lines. For Go and
+Rust the overhead is not a regression: those languages would not otherwise exist here.
+
+<a id="was-dieses-backend-anders-macht--und-wo-es-steht"></a>
+
+## Backend differences and their locations
+
+| Aspect | tree-sitter | ast-grep | Location |
+|---|---|---|---|
+| Traversal | Native cursor API | Iterative stack-based cursor | `syntax.ts` |
+| 32-KiB buffer limit | Exists; needs `bufferSize` (WP-215) | Absent, tested to 4 MB without an option | `shared/parse-limits.ts`, `adapter.ts` |
+| Size limit | 8 MiB | **5 MiB**, traversal uses more memory | `adapter.ts` |
+| `missingNodeCount` | Measured through `nodeIsMissing` | **Heuristic**, zero-width leaf | `syntax.ts`, `shared/parse-diagnostics.ts` |
+| Node field name | `cursor.currentFieldName` | Lookup through parent fields | `syntax.ts` |
+| `parser_version` | `untangle-parser-v1` | `untangle-parser-astgrep-v1` | Domain `versions.ts` |
+
+EVERY diagnostic derived from heuristic `missingNodeCount` describes its source: heuristically
+detected zero-width nodes; ast-grep has no nodeIsMissing. Anyone reading the count sees its origin,
+the difference between an estimate and a silent assertion (E4).
+
+<a id="der-vereinheitlichte-walk-bedient-beide-wege"></a>
+
+## One traversal serves BOTH backends
+
+`languages/shared/` has been backend-neutral since WP-220:
+
+- `syntax.ts`: `SyntaxNode`/`SyntaxCursor` tree contracts. Native tree-sitter types satisfy them
+  STRUCTURALLY, without wrappers; the faster backend pays no abstraction cost, pinned in
+  `tree-sitter-types.ts`.
+- `profile.ts`: language profile describing node-kind meaning.
+- `js-family-profile.ts`: handwritten TS/JS/TSX/JSX profile, with unchanged behavior (golden tests).
+- `table-profile.ts`: table-driven profiles; a new language costs a table rather than another engine.
+
+Wave 6's comment-node defect (`cursor-walk.test.ts`) stays fixed: traversal descends from the ROOT
+and both fingerprints omit comments. The defect does not arise with ast-grep.
+
+<a id="eine-sprache-hinzufuegen"></a>
+
+## Adding a language
+
+1. Add its `@ast-grep/lang-<x>` package INDIVIDUALLY to `package.json`, never a bundle: 22 language
+   packages occupy 450 MB together.
+2. Write its table in `languages.ts`, following `GO_TABLE`/`RUST_TABLE`.
+3. Register the adapter in `languages/index.ts`.
+4. Extend `adapter.test.ts` with real source, not a ten-line snippet.
+
+<a id="bekannte-grenzen-e4"></a>
+
+## Known limits (E4)
+
+- **No prebuild on Alpine (Linux musl), Windows ARM64 or Windows ia32.** Language packages ship
+  prebuilds only for macOS x64/arm64, Linux x64/arm64 glibc and Windows x64. Missing-prebuild build
+  failures are caught and merely logged by `postinstall`, which exits 0, so installation REPORTS
+  SUCCESS. `napi.ts` therefore checks each language at registration and reports
+  `grammar_unavailable`, producing reasoned skip-ledger entries rather than silent zeros.
+- **One registration only.** `registerDynamicLanguage` runs once; a second call silently
+  registers nothing. Every enrolled language is therefore registered TOGETHER on first parse.
+  Subsequent enrollment throws rather than doing nothing.
+- **`SgNode#id()` is address-derived** and differs across processes. It serves only field-name
+  comparison within a traversal and appears in no result data. `adapter.test.ts` checks
+  determinism across two runs.
+- **`Pos.index` is a UTF-16 offset**, despite ast-grep's "byte offset" type documentation.
+  All byte ranges use `ByteOffsetTable`.
+- **Table-driven profiles are weaker than handwritten profiles.** Import bindings, call
+  qualifiers, signature normalization and Rust `fn` inside `impl` being `function` rather than
+  `method` are documented in `shared/table-profile.ts` and the tables themselves.
+- **`LanguageAdapter.parse` is synchronous.** Exploration recommended yielding the event loop per
+  file for napi finalizers, but that conflicts with domain `analysis.ts` and was NOT done. A lower
+  size limit is used instead; callers parsing many large files in one turn should account for this.
+
+<a id="offen-bewusst-nicht-getan"></a>
+
+## Open work (deliberately not performed)
+
+- **Python retains its custom parser.** Exploration recommends replacing it first, explicitly
+  conditional on running the 1,432 lines of Python tests—including WP-76's 20,000-clause `elif`—
+  against ast-grep BEFOREHAND. That did not happen, so nothing was deleted. Machinery is ready;
+  replacement is a separate work item with its own evidence.
+- **`doctor` does not yet report ast-grep availability.** `napi.ts` exposes per-language
+  `astGrepLanguageStates`; the command lacks its display.
+- **THIRD_PARTY_LICENSES.** Language packages ship external tree-sitter grammars while naming only
+  ast-grep in LICENSE. The license of EACH grammar needs to be added.

package/src/languages/astgrep-backend/__golden__/bash-basic.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Deploys the app.
+set -euo pipefail
+
+MAX_RETRIES=3
+readonly TARGET="${1:-staging}"
+
+source ./lib/common.sh
+. ./lib/log.sh
+
+log_info() {
+    printf '%s\n' "$*" >&2
+}
+
+function retry() {
+    local attempt=0
+    while [ "$attempt" -lt "$MAX_RETRIES" ]; do
+        if "$@"; then
+            return 0
+        elif [ "$attempt" -gt 1 ]; then
+            log_info "retrying"
+        fi
+        attempt=$((attempt + 1))
+    done
+    return 1
+}
+
+deploy() {
+    case "$TARGET" in
+        staging)
+            log_info "staging"
+            ;;
+        prod|production)
+            log_info "prod"
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+
+    for f in ./dist/*; do
+        [ -f "$f" ] || continue
+        if [ -x "$f" ] && [ -s "$f" ]; then
+            log_info "$f"
+        fi
+    done
+
+    until retry true; do
+        break
+    done
+}
+
+deploy

package/src/languages/astgrep-backend/__golden__/c-basic.c

@@ -0,0 +1,64 @@
+/* A ring buffer. */
+#include <stdlib.h>
+#include <string.h>
+#include "ring.h"
+
+#define RING_MAX 64
+
+typedef struct ring {
+    char *data;
+    size_t head;
+    size_t len;
+} ring_t;
+
+enum ring_state { RING_OK, RING_FULL };
+
+static size_t clamp(size_t v, size_t hi) {
+    return v > hi ? hi : v;
+}
+
+/* Creates a ring. */
+ring_t *ring_new(size_t cap) {
+    if (cap == 0 || cap > RING_MAX) {
+        return NULL;
+    }
+    ring_t *r = malloc(sizeof(ring_t));
+    if (!r) return NULL;
+    r->data = malloc(cap);
+    r->head = 0;
+    r->len = 0;
+    return r;
+}
+
+int ring_push(ring_t *r, const char *src, size_t n) {
+    if (r == NULL || src == NULL) {
+        return -1;
+    } else if (n == 0) {
+        return 0;
+    }
+    for (size_t i = 0; i < n; i++) {
+        while (r->len >= RING_MAX) {
+            r->len--;
+        }
+        switch (src[i]) {
+            case '\n':
+                r->head = 0;
+                break;
+            case '\0':
+                break;
+            default:
+                r->data[r->head++] = src[i];
+        }
+    }
+    do {
+        r->len = clamp(r->len, RING_MAX);
+    } while (0);
+    return (int)n;
+}
+
+void ring_free(ring_t *r) {
+    if (r) {
+        free(r->data);
+        free(r);
+    }
+}