Skip to content

docs: add supported-languages reference and README section #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sunerpy merged 1 commit into from
Jun 25, 2026
Merged

docs: add supported-languages reference and README section #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

27 changes: 24 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,9 +334,9 @@ accept the project path as a positional argument or `-p/--path`; `query`/`files`

## What CodeGraph Does (and Doesn't)

**Does:** deterministic code-structure extraction across ~29 languages (TypeScript,
**Does:** deterministic code-structure extraction across 32 languages (TypeScript,
Python, Go, Rust, Java, C/C++, C#, Vue, Svelte, GDScript, and more — see
[`docs/grammar-manifest.md`](docs/grammar-manifest.md)), cross-file resolution,
[`docs/languages.md`](docs/languages.md)), cross-file resolution,
graph traversal, FTS5 search, whole-graph export with deterministic PageRank
centrality, MCP/CLI surfaces, and golden byte-stable output.

Expand All @@ -346,16 +346,37 @@ beyond the fixed `LANGUAGES` set.

---

## Supported Languages

CodeGraph supports **32 languages** grouped by extraction depth:

**Tier 1 — Full symbol extraction (23):** TypeScript, TSX, JavaScript, JSX,
Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Scala, Lua,
Luau, Objective-C, R, GDScript, Pascal.

**Tier 2 — Embedded / template extraction (6):** Vue (delegates `<script>` to
TS/JS), Svelte (delegates script blocks), Astro, Razor/`.cshtml`, Liquid
(Shopify templates + sections), XML/MyBatis mapper.

**Tier 3 — File-level only (3):** YAML, Twig, Properties — indexed as file
nodes; no symbol extraction.

Full list with extensions and per-language notes: [`docs/languages.md`](docs/languages.md).

---

## Documentation

- [`docs/architecture.md`](docs/architecture.md) — crate dependency graph,
extraction/resolution/traversal/search pipelines, daemon/watch lifecycle.
- [`docs/data-model.md`](docs/data-model.md) — SQLite/FTS5 storage contract.
- [`docs/equivalence.md`](docs/equivalence.md) — the 3-tier equivalence oracle,
golden regeneration, `KNOWN_DIFFS.md` format.
- [`docs/languages.md`](docs/languages.md) — full supported-language list grouped
by extraction depth.
- [`docs/grammar-manifest.md`](docs/grammar-manifest.md) /
[`docs/embedded-extraction.md`](docs/embedded-extraction.md) — language support
and extraction tiers.
and extraction tiers (engineering ABI detail).
- [`docs/cli.md`](docs/cli.md) — full CLI subcommand reference (22 subcommands,
all flags).
- [`docs/mcp.md`](docs/mcp.md) — MCP server protocol, all 10 tools, JSON-RPC
Expand Down
105 changes: 105 additions & 0 deletions docs/languages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Supported Languages

CodeGraph extracts code structure deterministically using tree-sitter grammars and custom
embedded extractors. No AI, vectors, or embeddings are involved. The output is byte-stable
across runs.

**32 concrete languages** are supported, grouped into three extraction tiers based on what
the extractor produces.

> **Note on TypeScript/JavaScript variants:** `typescript` and `tsx`, and `javascript` and
> `jsx`, are distinct grammar variants internally (separate `Language` enum entries). They
> share grammars but handle different file-extension sets. The table lists each variant
> separately so the extension mapping is unambiguous.

---

## Tier 1 — Full symbol extraction (23 languages)

Tree-sitter parses the file and extracts all symbols (functions, classes, structs, methods,
variables, imports, etc.) plus call and dependency edges. This is the richest extraction
level.

| Language | Extensions | Extraction | Notes |
| ----------- | ------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------- |
| TypeScript | `.ts` `.mts` `.cts` | Full tree-sitter | |
| TSX | `.tsx` | Full tree-sitter | TypeScript grammar, JSX syntax |
| JavaScript | `.js` `.mjs` `.cjs` `.xsjs` `.xsjslib` | Full tree-sitter | |
| JSX | `.jsx` | Full tree-sitter | JavaScript grammar, JSX syntax |
| Python | `.py` `.pyw` | Full tree-sitter | |
| Go | `.go` | Full tree-sitter | |
| Rust | `.rs` | Full tree-sitter | |
| Java | `.java` | Full tree-sitter | |
| C | `.c` `.h` | Full tree-sitter | `.h` may be promoted to C++ or Objective-C by heuristics |
| C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hxx` | Full tree-sitter | |
| C# | `.cs` | Full tree-sitter | |
| PHP | `.php` `.module` `.install` `.theme` `.inc` | Full tree-sitter | |
| Ruby | `.rb` `.rake` | Full tree-sitter | |
| Swift | `.swift` | Full tree-sitter | |
| Kotlin | `.kt` `.kts` | Full tree-sitter | |
| Dart | `.dart` | Full tree-sitter | |
| Scala | `.scala` `.sc` | Full tree-sitter | |
| Lua | `.lua` | Full tree-sitter | |
| Luau | `.luau` | Full tree-sitter | Roblox Luau dialect |
| Objective-C | `.m` `.mm` | Full tree-sitter | |
| R | `.r` | Full tree-sitter | |
| GDScript | `.gd` | Full tree-sitter | Godot scripting; extracts functions, classes, enums, variables, signals, extends, preload |
| Pascal | `.pas` `.dpr` `.dpk` `.lpr` `.dfm` `.fmx` | Full tree-sitter / custom | `.dfm`/`.fmx` form files use a custom path |

---

## Tier 2 — Embedded / template extraction (6 languages)

These languages wrap or embed code in another language (or use a custom extractor). The
host file gets its own node; inner code is delegated to the appropriate Tier-1 grammar
and merged back into the parent result.

| Language | Extensions | Extraction | Notes |
| ------------- | ------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------- |
| Vue | `.vue` | Embedded (delegates to TS/JS) | `<script>` and `<script setup>` blocks delegated; `lang="ts"` selects TypeScript grammar |
| Svelte | `.svelte` | Embedded (delegates to TS/JS) | Script blocks extracted and delegated; component node created for the file |
| Astro | `.astro` | Embedded | Detected via embedded pre-pass only (not in the built-in extension map) |
| Razor | `.razor` `.cshtml` | Embedded (custom) | Detected via embedded pre-pass only; C# snippets extracted from `.cshtml`/`.razor` files |
| Liquid | `.liquid`, `templates/*.json`, `sections/*.json` | Custom regex extractor | Shopify template support; path-based `.json` detection for templates and sections |
| XML (MyBatis) | `.xml` | Custom (MyBatis mapper) | Extracts SQL-mapper nodes from MyBatis XML files; generic XML gets a file node only |

---

## Tier 3 — File-level only (3 languages)

These files are indexed as file nodes so they appear in the graph and are searchable, but
no symbol extraction is performed. They contribute to traversal and impact analysis at the
file level.

| Language | Extensions | Extraction | Notes |
| ---------- | -------------- | -------------- | -------------------- |
| YAML | `.yml` `.yaml` | File node only | No symbol extraction |
| Twig | `.twig` | File node only | No symbol extraction |
| Properties | `.properties` | File node only | No symbol extraction |

---

## Adding custom extension mappings

Non-standard extensions can be mapped to any supported language via `.codegraph/codegraph.json`:

```jsonc
{
"extensions": {
".x": "lua",
".blade": "php",
},
}
```

Keys are dot-stripped and lowercased before matching. Unknown language names are silently
skipped. The nearest config up the directory tree wins.

---

## See also

- [`docs/grammar-manifest.md`](grammar-manifest.md) — engineering ABI manifest: per-language
grammar crate, tier policy, and ABI smoke status (for contributors and grammar maintainers).
- [`docs/embedded-extraction.md`](embedded-extraction.md) — detailed description of the
embedded extraction pipeline: region detection, line-number remapping, and node merging.
26 changes: 23 additions & 3 deletions docs/readme/README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -352,22 +352,42 @@ Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete

## CodeGraph 的能力范围

**做什么：** 确定性代码结构提取，支持约 29 种语言（TypeScript、Python、Go、Rust、
**做什么：** 确定性代码结构提取，支持 32 种语言（TypeScript、Python、Go、Rust、
Java、C/C++、C#、Vue、Svelte、GDScript 等——详见
[`../grammar-manifest.md`](../grammar-manifest.md)），跨文件解析，图遍历，FTS5 检索，
[`../languages.md`](../languages.md)），跨文件解析，图遍历，FTS5 检索，
全图导出（含确定性 PageRank 中心性），MCP/CLI 表面，golden 字节稳定输出。

**不做什么：** 二进制内部无任何 AI/向量/嵌入/LLM（硬约束，`scripts/guardrail.sh`
强制执行）；无语义检索；不新增固定 `LANGUAGES` 集以外的语言。

---

## 支持的语言

CodeGraph 支持 **32 种语言**，按提取深度分为三个层级：

**Tier 1 — 完整符号提取（23 种）：** TypeScript、TSX、JavaScript、JSX、
Python、Go、Rust、Java、C、C++、C#、PHP、Ruby、Swift、Kotlin、Dart、Scala、Lua、
Luau、Objective-C、R、GDScript、Pascal。

**Tier 2 — 嵌入式 / 模板提取（6 种）：** Vue（`<script>` 委托给 TS/JS）、
Svelte（脚本块委托）、Astro、Razor/`.cshtml`、Liquid（Shopify 模板与 sections）、
XML/MyBatis mapper。

**Tier 3 — 仅文件级索引（3 种）：** YAML、Twig、Properties——作为文件节点
索引，不提取符号。

完整列表（含各语言扩展名和说明）：[`../languages.md`](../languages.md)。

---

## 文档

- [`../architecture.md`](../architecture.md) — crate 依赖图、提取/解析/遍历/检索流水线、daemon/watch 生命周期。
- [`../data-model.md`](../data-model.md) — SQLite/FTS5 存储契约。
- [`../equivalence.md`](../equivalence.md) — 3 层等价预言机、golden 再生流程、KNOWN_DIFFS 规则格式。
- [`../grammar-manifest.md`](../grammar-manifest.md) / [`../embedded-extraction.md`](../embedded-extraction.md) — 语言支持与提取层级。
- [`../languages.md`](../languages.md) — 支持语言完整列表，按提取深度分层。
- [`../grammar-manifest.md`](../grammar-manifest.md) / [`../embedded-extraction.md`](../embedded-extraction.md) — 语言支持与提取层级（工程 ABI 细节）。
- [`../cli.md`](../cli.md) — 完整 CLI 子命令参考（22 个子命令，所有标志）。
- [`../mcp.md`](../mcp.md) — MCP 服务器协议、全部 10 个工具、JSON-RPC 详情。
- [`../../examples/`](../../examples/) — codegraph + LLM 编排示例。
Expand Down