Make IR file-scoped and add source_path metadata

Refactor the bindgen IR to be file-scoped: IRModule now holds a files: Dict[path, IRFile] map (IRFile groups types/enums/functions/classes/constants/aliases). Add source_path metadata to IR nodes (fields, structs, enums, aliases, functions, methods, classes, constants) and collect entities into per-file buckets in the normalizer. Normalize now detects cursor file paths, handles lvalue/rvalue references and elaborated/unexposed types, records class fields/bases, constructors/destructors, and filters out operators. Serializer now emits the files map, codegen context exposes files, file_paths and flattened lists, and example README/template and header discovery sorting were updated accordingly.

Author: lijy91

tools/bindgen/README.md

@@ -102,44 +102,68 @@ C++ Headers
 
 ### 模块（IRModule）
 
-- headers
-- types
-- functions
-- classes
-- constants
-- aliases
+- IR 输出为 `path -> IRFile` 的 map（不再包含 `headers` 节点）
+- `IRFile` 结构包含：
+  - types
+  - enums
+  - functions
+  - classes
+  - constants
+  - aliases
+- `source_path`：结构体/枚举/函数/别名/常量/类/方法/字段所在头文件路径（如 `src/foundation/color.h`）
 
 ### IR JSON 示例（最小）
 
 ```json
 {
-  "headers": ["include/nativeapi.h"],
-  "types": [
-    {
-      "kind": "struct",
-      "name": "Point",
-      "fields": [
-        {"name": "x", "type": {"kind": "float32"}},
-        {"name": "y", "type": {"kind": "float32"}}
-      ]
-    }
-  ],
-  "functions": [
-    {
-      "name": "na_distance",
-      "return_type": {"kind": "float32"},
-      "params": [
-        {"name": "a", "type": {"kind": "pointer", "to": {"kind": "struct", "name": "Point"}}, "nullable": false},
-        {"name": "b", "type": {"kind": "pointer", "to": {"kind": "struct", "name": "Point"}}, "nullable": false}
-      ]
-    }
-  ],
-  "constants": [
-    {"name": "NA_OK", "type": {"kind": "int32"}, "value": 0}
-  ],
-  "aliases": [
-    {"name": "NAHandle", "target": {"kind": "uintptr"}}
-  ]
+  "src/foundation/geometry.h": {
+    "types": [
+      {
+        "kind": "struct",
+        "name": "Point",
+        "source_path": "src/foundation/geometry.h",
+        "fields": [
+          {"name": "x", "type": {"kind": "float32"}, "source_path": "src/foundation/geometry.h"},
+          {"name": "y", "type": {"kind": "float32"}, "source_path": "src/foundation/geometry.h"}
+        ]
+      }
+    ],
+    "functions": [
+      {
+        "name": "na_distance",
+        "source_path": "src/foundation/geometry.h",
+        "return_type": {"kind": "float32"},
+        "params": [
+          {"name": "a", "type": {"kind": "pointer", "to": {"kind": "struct", "name": "Point"}}, "nullable": false},
+          {"name": "b", "type": {"kind": "pointer", "to": {"kind": "struct", "name": "Point"}}, "nullable": false}
+        ]
+      }
+    ],
+    "enums": [],
+    "classes": [],
+    "constants": [],
+    "aliases": []
+  },
+  "src/foundation/error.h": {
+    "types": [],
+    "enums": [],
+    "functions": [],
+    "classes": [],
+    "constants": [
+      {"name": "NA_OK", "type": {"kind": "int32"}, "value": 0, "source_path": "src/foundation/error.h"}
+    ],
+    "aliases": []
+  },
+  "src/foundation/types.h": {
+    "types": [],
+    "enums": [],
+    "functions": [],
+    "classes": [],
+    "constants": [],
+    "aliases": [
+      {"name": "NAHandle", "target": {"kind": "uintptr"}, "source_path": "src/foundation/types.h"}
+    ]
+  }
 }
 ```
 
@@ -207,11 +231,13 @@ render_to_files(templates, context, out_dir)
 
 **模板上下文约定（建议）**
 
-- `module`: 当前模块信息（headers, namespaces）
-- `types`: 结构体/枚举/别名列表（已排序）
-- `functions`: 函数列表（已过滤）
+- `module`: 当前模块信息（含 `files`）
+- `files`: path -> IRFile 的 map
+- `file_paths`: 排序后的文件路径列表
+- `types`: 结构体/枚举/别名列表（已扁平化并排序）
+- `functions`: 函数列表（已过滤并扁平化）
 - `classes`: C++ 类/struct 列表（public methods）
-- `constants`: 常量列表
+- `constants`: 常量列表（扁平化）
 - `mapping`: 语言映射配置（types/conventions/naming）
 
 **优点**

tools/bindgen/codegen/context.py

@@ -6,13 +6,31 @@
 
 
 def build_context(module: IRModule, mapping: Dict) -> Dict:
+    files = module.files
+    sorted_paths = sorted(files.keys())
+    types = []
+    enums = []
+    functions = []
+    classes = []
+    constants = []
+    aliases = []
+    for path in sorted_paths:
+        bucket = files[path]
+        types.extend(bucket.types)
+        enums.extend(bucket.enums)
+        functions.extend(bucket.functions)
+        classes.extend(bucket.classes)
+        constants.extend(bucket.constants)
+        aliases.extend(bucket.aliases)
     return {
         "module": module,
-        "types": module.types,
-        "enums": module.enums,
-        "functions": module.functions,
-        "classes": module.classes,
-        "constants": module.constants,
-        "aliases": module.aliases,
+        "files": files,
+        "file_paths": sorted_paths,
+        "types": types,
+        "enums": enums,
+        "functions": functions,
+        "classes": classes,
+        "constants": constants,
+        "aliases": aliases,
         "mapping": mapping,
     }

tools/bindgen/example/bindgen/template/example.txt.j2

@@ -1,6 +1,6 @@
 Generated by bindgen example template.
 language={{ mapping.language | default("example") }}
-headers={{ module.headers|length }}
+files={{ file_paths|length }}
 structs={{ types|length }}
 enums={{ enums|length }}
 functions={{ functions|length }}

tools/bindgen/ir/model.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import List, Optional
+from typing import Dict, List, Optional
 
 
 @dataclass
@@ -19,13 +19,15 @@ class IRType:
 class IRField:
     name: str
     type: IRType
+    source_path: Optional[str] = None
 
 
 @dataclass
 class IRStruct:
     name: str
     fields: List[IRField]
     qualified_name: Optional[str] = None
+    source_path: Optional[str] = None
 
 
 @dataclass
@@ -40,12 +42,14 @@ class IREnum:
     values: List[IREnumValue]
     scoped: bool = False
     qualified_name: Optional[str] = None
+    source_path: Optional[str] = None
 
 
 @dataclass
 class IRAlias:
     name: str
     target: IRType
+    source_path: Optional[str] = None
 
 
 @dataclass
@@ -64,39 +68,50 @@ class IRFunction:
     callconv: Optional[str] = None
     variadic: bool = False
     qualified_name: Optional[str] = None
+    source_path: Optional[str] = None
 
 
 @dataclass
 class IRMethod:
     name: str
     return_type: IRType
     params: List[IRParam]
+    kind: str = "method"
     static: bool = False
     const: bool = False
     access: Optional[str] = None
     variadic: bool = False
+    source_path: Optional[str] = None
 
 
 @dataclass
 class IRClass:
     name: str
+    fields: List[IRField] = field(default_factory=list)
     methods: List[IRMethod] = field(default_factory=list)
+    bases: List[str] = field(default_factory=list)
     qualified_name: Optional[str] = None
+    source_path: Optional[str] = None
 
 
 @dataclass
 class IRConstant:
     name: str
     type: IRType
     value: int | float | str
+    source_path: Optional[str] = None
 
 
 @dataclass
-class IRModule:
-    headers: List[str]
+class IRFile:
     types: List[IRStruct] = field(default_factory=list)
     enums: List[IREnum] = field(default_factory=list)
     functions: List[IRFunction] = field(default_factory=list)
     classes: List[IRClass] = field(default_factory=list)
     constants: List[IRConstant] = field(default_factory=list)
     aliases: List[IRAlias] = field(default_factory=list)
+
+
+@dataclass
+class IRModule:
+    files: Dict[str, IRFile] = field(default_factory=dict)

tools/bindgen/ir/serializer.py

@@ -8,7 +8,7 @@
 
 
 def dump_ir_json(module: IRModule, path: Path) -> None:
-    payload = asdict(module)
+    payload = asdict(module)["files"]
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(
         json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"