docs: cookbook for adding a new language extractor

[mschreib28]

🔄 Rebased onto refactor colbymchenry#116 (per-language registry). The cookbook now teaches the post-refactor flow: one new file in src/extraction/languages/ instead of the previous 3-file mutation across types.ts / grammars.ts / CLAUDE.md. Sections 1, 2, 4, 6, 7, 8 and the reference table are unchanged.\n\n---\n\n## Summary\n\nAdds docs/ADDING-A-LANGUAGE.md — a cookbook for contributors adding a new language extractor. Closes colbymchenry#55.\n\nThe doc was prompted by @cfournel's question on colbymchenry#55 (they published tree-sitter-mql5 and asked how to plug it in), but applies equally to anyone adding HCL/Terraform, R, SQL, dbt, Scala, Vue, or any of the other language requests in the issue tracker. Now there's a single self-serve walkthrough.\n\n## What it covers\n\n1. Sourcing the wasm grammar — three real-world paths: already in tree-sitter-wasms, pre-built in a GitHub release / npm tarball, or built from source via tree-sitter-cli's bundled wasi-sdk (no Docker / local emcc needed).\n2. Probing the AST with a 15-line scratch script before writing any extractor code.\n3. Registering the language — one new file (src/extraction/languages/<name>.ts exporting a LanguageDef) plus a 2-line registry update; reflects the per-file registry pattern from colbymchenry#116.\n4. Type-check before extraction logic — catches wiring bugs early.\n5. Two extractor patterns plugged into the same LanguageDef:\n - LanguageExtractor config (procedural / OO — Python, Ruby, R)\n - Self-contained extractor class (declarative / template / non-OO — HCL, SQL, Liquid)\n6. NodeKind / EdgeKind mapping table so contributors don't introduce new kinds unnecessarily (those are cross-cutting).\n7. Test patterns with extractFromSource + the end-to-end CLI smoke recipe.\n8. PR description checklist including grammar-source provenance, sha256 for vendored wasms, and being honest about constructs the grammar can't parse.\n\nEach section points at concrete extractors in the repo as worked examples — R for the OO path, HCL / SQL / Liquid for the custom-class path, Pascal + DFM for the cross-format case.\n\n## Files changed\n\n| File | Change |\n|---|---|\n| docs/ADDING-A-LANGUAGE.md | New cookbook (~460 lines) |\n| README.md | Pointer to the cookbook from the "Supported Languages" section |\n| CLAUDE.md | Pointer from the "Supported Languages" architecture line so the LLM-readable doc stays in sync |\n\n## Test plan\n\n- [x] Reviewed the rendered Markdown locally\n- [x] Verified every code snippet against the actual code I just wrote across HCL (colbymchenry#92), R (colbymchenry#94), and SQL (colbymchenry#95) — these PRs followed exactly the steps the cookbook lays out\n- [x] Verified the tree-sitter-cli build --wasm workflow on the SQL grammar (the wasi-sdk path the doc recommends)\n\n🤖 Generated with Claude Code\n\n\n

---

Copied from colbymchenry/codegraph#97