decy-parser 2.2.0

C AST parsing using clang-sys for Decy transpiler
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
//! Type, struct, enum, typedef, variable, and macro extraction from clang cursors.


use crate::ast_types::*;
use clang_sys::*;
use std::ffi::CStr;
use std::ptr;


use super::visit_statement;
use super::expressions::visit_variable_initializer;

pub(crate) fn extract_function(cursor: CXCursor) -> Option<Function> {
    // SAFETY: Getting cursor spelling (function name)
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // SAFETY: Getting return type
    let cx_type = unsafe { clang_getCursorType(cursor) };
    let return_cx_type = unsafe { clang_getResultType(cx_type) };
    let return_type = convert_type(return_cx_type)?;

    // Extract parameters
    let num_args = unsafe { clang_Cursor_getNumArguments(cursor) };
    let mut parameters = Vec::new();

    for i in 0..num_args {
        // SAFETY: Getting argument cursor
        let arg_cursor = unsafe { clang_Cursor_getArgument(cursor, i as u32) };

        // Get parameter name
        let param_name_cxstring = unsafe { clang_getCursorSpelling(arg_cursor) };
        let param_name = unsafe {
            let c_str = CStr::from_ptr(clang_getCString(param_name_cxstring));
            let name = c_str.to_string_lossy().into_owned();
            clang_disposeString(param_name_cxstring);
            name
        };

        // Get parameter type
        let param_cx_type = unsafe { clang_getCursorType(arg_cursor) };
        if let Some(param_type) = convert_type(param_cx_type) {
            // DECY-135: Check if this is a pointer with const-qualified pointee
            let is_pointee_const = unsafe {
                if param_cx_type.kind == clang_sys::CXType_Pointer {
                    let pointee = clang_sys::clang_getPointeeType(param_cx_type);
                    clang_isConstQualifiedType(pointee) != 0
                } else {
                    false
                }
            };
            parameters.push(Parameter::new_with_const(param_name, param_type, is_pointee_const));
        }
    }

    // Extract function body by visiting children
    let mut body = Vec::new();
    let body_ptr = &mut body as *mut Vec<Statement>;

    unsafe {
        clang_visitChildren(cursor, visit_statement, body_ptr as CXClientData);
    }

    // DECY-199: Detect CUDA qualifiers by visiting function attributes
    let mut cuda_qualifier = None;
    let cuda_qual_ptr = &mut cuda_qualifier as *mut Option<CudaQualifier>;
    unsafe {
        clang_visitChildren(cursor, visit_cuda_attrs, cuda_qual_ptr as CXClientData);
    }

    let mut func = Function::new_with_body(name, return_type, parameters, body);
    func.cuda_qualifier = cuda_qualifier;
    Some(func)
}

/// Visitor callback to detect CUDA function attributes (DECY-199).
///
/// Checks for CXCursor_CUDAGlobalAttr (414), CUDADeviceAttr (413),
/// CUDAHostAttr (415) among the function's children.
extern "C" fn visit_cuda_attrs(
    cursor: CXCursor,
    _parent: CXCursor,
    client_data: CXClientData,
) -> CXChildVisitResult {
    let kind = unsafe { clang_getCursorKind(cursor) };
    let qual_ptr = client_data as *mut Option<CudaQualifier>;

    // clang-sys cursor kinds for CUDA attributes:
    // CXCursor_CUDADeviceAttr = 413
    // CXCursor_CUDAGlobalAttr = 414
    // CXCursor_CUDAHostAttr = 415
    match kind {
        414 => {
            // __global__
            unsafe { *qual_ptr = Some(CudaQualifier::Global) };
        }
        413 => {
            // __device__ - could combine with __host__
            unsafe {
                *qual_ptr = match *qual_ptr {
                    Some(CudaQualifier::Host) => Some(CudaQualifier::HostDevice),
                    _ => Some(CudaQualifier::Device),
                };
            }
        }
        415 => {
            // __host__ - could combine with __device__
            unsafe {
                *qual_ptr = match *qual_ptr {
                    Some(CudaQualifier::Device) => Some(CudaQualifier::HostDevice),
                    _ => Some(CudaQualifier::Host),
                };
            }
        }
        _ => {}
    }

    CXChildVisit_Continue
}

/// Extract a C++ class from a CXCursor_ClassDecl cursor (DECY-200).
///
/// Visits class children to find fields, methods, constructors, and destructors.
/// Maps to AST `Class` struct for downstream conversion to Rust struct + impl.
pub(crate) fn extract_class(cursor: CXCursor) -> Option<Class> {
    contract_pre_class_to_struct!();
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let n = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        n
    };

    // Skip anonymous classes
    if name.is_empty() {
        return None;
    }

    let mut class = Class::new(name);
    let class_ptr = &mut class as *mut Class;

    unsafe {
        clang_visitChildren(cursor, visit_class_children, class_ptr as CXClientData);
    }

    Some(class)
}

/// Visitor callback for C++ class children (DECY-200).
///
/// Handles: CXCursor_FieldDecl, CXCursor_CXXMethod, CXCursor_Constructor,
/// CXCursor_Destructor, CXCursor_CXXAccessSpecifier.
extern "C" fn visit_class_children(
    cursor: CXCursor,
    _parent: CXCursor,
    client_data: CXClientData,
) -> CXChildVisitResult {
    let class = unsafe { &mut *(client_data as *mut Class) };
    let kind = unsafe { clang_getCursorKind(cursor) };

    match kind {
        // CXCursor_FieldDecl = 6
        6 => {
            let field_name_cx = unsafe { clang_getCursorSpelling(cursor) };
            let field_name = unsafe {
                let c_str = CStr::from_ptr(clang_getCString(field_name_cx));
                let n = c_str.to_string_lossy().into_owned();
                clang_disposeString(field_name_cx);
                n
            };
            let field_type = unsafe { clang_getCursorType(cursor) };
            if let Some(ft) = convert_type(field_type) {
                class.fields.push(StructField::new(field_name, ft));
            }
        }
        // CXCursor_CXXMethod = 21
        21 => {
            if let Some(func) = extract_function(cursor) {
                let is_const = unsafe { clang_CXXMethod_isConst(cursor) != 0 };
                let is_static = unsafe { clang_CXXMethod_isStatic(cursor) != 0 };
                let is_virtual = unsafe { clang_CXXMethod_isVirtual(cursor) != 0 };
                // DECY-208: Detect overloaded operators from function name
                let operator_kind = detect_operator_kind(&func.name);
                class.methods.push(Method {
                    function: func,
                    access: AccessSpecifier::Public,
                    is_const,
                    is_static,
                    is_virtual,
                    operator_kind,
                });
            }
        }
        // CXCursor_Constructor = 24
        24 => {
            // Extract constructor parameters
            let num_args = unsafe { clang_Cursor_getNumArguments(cursor) };
            let mut params = Vec::new();
            for i in 0..num_args {
                let arg_cursor = unsafe { clang_Cursor_getArgument(cursor, i as u32) };
                let param_name_cx = unsafe { clang_getCursorSpelling(arg_cursor) };
                let param_name = unsafe {
                    let c_str = CStr::from_ptr(clang_getCString(param_name_cx));
                    let n = c_str.to_string_lossy().into_owned();
                    clang_disposeString(param_name_cx);
                    n
                };
                let param_type = unsafe { clang_getCursorType(arg_cursor) };
                if let Some(pt) = convert_type(param_type) {
                    params.push(Parameter::new(param_name, pt));
                }
            }
            // Store first constructor's params (primary constructor)
            if class.constructor_params.is_empty() {
                class.constructor_params = params;
            }
        }
        // CXCursor_Destructor = 25
        25 => {
            class.has_destructor = true;
        }
        // CXCursor_CXXBaseSpecifier = 44 (DECY-209: single inheritance)
        44 => {
            let base_name_cx = unsafe { clang_getCursorSpelling(cursor) };
            let base_name = unsafe {
                let c_str = CStr::from_ptr(clang_getCString(base_name_cx));
                let n = c_str.to_string_lossy().into_owned();
                clang_disposeString(base_name_cx);
                n
            };
            // clang spells base specifiers as "class BaseClass" or "struct BaseClass"
            // DECY-220: Also strip namespace qualifiers (vecmath::Vec2 -> Vec2)
            let stripped = base_name
                .strip_prefix("class ")
                .or_else(|| base_name.strip_prefix("struct "))
                .unwrap_or(&base_name);
            let clean_name = stripped
                .rsplit("::")
                .next()
                .unwrap_or(stripped)
                .to_string();
            if !clean_name.is_empty() {
                class.base_class = Some(clean_name);
            }
        }
        _ => {}
    }

    CXChildVisit_Continue
}

/// Detect C++ operator kind from method name (DECY-208).
///
/// Clang spells overloaded operators as "operator+", "operator==", etc.
fn detect_operator_kind(name: &str) -> Option<CxxOperatorKind> {
    contract_pre_operator_to_trait!();
    match name {
        "operator+" => Some(CxxOperatorKind::Add),
        "operator-" => Some(CxxOperatorKind::Sub),
        "operator*" => Some(CxxOperatorKind::Mul),
        "operator/" => Some(CxxOperatorKind::Div),
        "operator%" => Some(CxxOperatorKind::Rem),
        "operator==" => Some(CxxOperatorKind::Equal),
        "operator!=" => Some(CxxOperatorKind::NotEqual),
        "operator<" => Some(CxxOperatorKind::Less),
        "operator<=" => Some(CxxOperatorKind::LessEqual),
        "operator>" => Some(CxxOperatorKind::Greater),
        "operator>=" => Some(CxxOperatorKind::GreaterEqual),
        "operator[]" => Some(CxxOperatorKind::Index),
        "operator<<" => Some(CxxOperatorKind::Shl),
        "operator>>" => Some(CxxOperatorKind::Shr),
        "operator+=" => Some(CxxOperatorKind::AddAssign),
        "operator-=" => Some(CxxOperatorKind::SubAssign),
        _ => None,
    }
}

/// Extract a C++ namespace from a CXCursor_Namespace cursor (DECY-201).
///
/// Visits namespace children to collect functions, structs, classes, and nested namespaces.
/// Maps to Rust `mod` block in codegen.
pub(crate) fn extract_namespace(cursor: CXCursor) -> Option<Namespace> {
    contract_pre_namespace_to_mod!();
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let n = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        n
    };

    let mut ns = Namespace::new(name);
    let ns_ptr = &mut ns as *mut Namespace;

    unsafe {
        clang_visitChildren(cursor, visit_namespace_children, ns_ptr as CXClientData);
    }

    Some(ns)
}

/// Visitor callback for C++ namespace children (DECY-201).
///
/// Handles: FunctionDecl, StructDecl, ClassDecl, Namespace (nested).
extern "C" fn visit_namespace_children(
    cursor: CXCursor,
    _parent: CXCursor,
    client_data: CXClientData,
) -> CXChildVisitResult {
    let ns = unsafe { &mut *(client_data as *mut Namespace) };
    let kind = unsafe { clang_getCursorKind(cursor) };

    if kind == CXCursor_FunctionDecl {
        if let Some(func) = extract_function(cursor) {
            ns.functions.push(func);
        }
    } else if kind == CXCursor_StructDecl {
        if let Some(s) = extract_struct(cursor) {
            ns.structs.push(s);
        }
    } else if kind == 4 {
        // CXCursor_ClassDecl = 4
        if let Some(class) = extract_class(cursor) {
            ns.classes.push(class);
        }
    } else if kind == 22 {
        // CXCursor_Namespace = 22 (nested namespace)
        if let Some(nested) = extract_namespace(cursor) {
            ns.namespaces.push(nested);
        }
    }

    CXChildVisit_Continue
}

/// Extract typedef information from a clang cursor.
/// Returns (Option<Typedef>, Option<Struct>) - struct is Some when typedef is for anonymous struct.
pub(crate) fn extract_typedef(cursor: CXCursor) -> (Option<Typedef>, Option<Struct>) {
    // SAFETY: Getting typedef name
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // SAFETY: Getting underlying type of typedef
    let cx_type = unsafe { clang_getTypedefDeclUnderlyingType(cursor) };

    // DECY-147: Check if underlying type is anonymous struct
    // Anonymous struct pattern: typedef struct { ... } Name;
    let canonical = unsafe { clang_getCanonicalType(cx_type) };
    if canonical.kind == CXType_Record {
        let decl = unsafe { clang_getTypeDeclaration(canonical) };
        let struct_name_cxstring = unsafe { clang_getCursorSpelling(decl) };
        let struct_name = unsafe {
            let c_str = CStr::from_ptr(clang_getCString(struct_name_cxstring));
            let sn = c_str.to_string_lossy().into_owned();
            clang_disposeString(struct_name_cxstring);
            sn
        };

        // If struct name is empty, this is an anonymous struct typedef
        if struct_name.is_empty() {
            // Extract struct fields from the declaration
            let mut fields = Vec::new();
            let fields_ptr = &mut fields as *mut Vec<StructField>;

            unsafe {
                clang_visitChildren(decl, visit_struct_fields, fields_ptr as CXClientData);
            }

            // Return struct with typedef name, no typedef needed
            return (None, Some(Struct::new(name, fields)));
        }
    }

    let underlying_type = convert_type(cx_type);
    match underlying_type {
        Some(ut) => (Some(Typedef::new(name, ut)), None),
        None => (None, None),
    }
}

/// Extract struct information from a clang cursor.
pub(crate) fn extract_struct(cursor: CXCursor) -> Option<Struct> {
    // SAFETY: Getting struct name
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // Skip anonymous structs
    if name.is_empty() {
        return None;
    }

    // Extract struct fields by visiting children
    let mut fields = Vec::new();
    let fields_ptr = &mut fields as *mut Vec<StructField>;

    unsafe {
        clang_visitChildren(cursor, visit_struct_fields, fields_ptr as CXClientData);
    }

    Some(Struct::new(name, fields))
}

/// DECY-240: Extract enum information from a clang cursor.
///
/// Extracts C enum declarations, including explicit values.
pub(crate) fn extract_enum(cursor: CXCursor) -> Option<Enum> {
    // SAFETY: Getting enum name
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // Extract enum variants by visiting children
    let mut variants: Vec<EnumVariant> = Vec::new();
    let variants_ptr = &mut variants as *mut Vec<EnumVariant>;

    // Visitor callback for enum constants
    extern "C" fn visit_enum_constants(
        cursor: CXCursor,
        _parent: CXCursor,
        client_data: CXClientData,
    ) -> CXChildVisitResult {
        let variants = unsafe { &mut *(client_data as *mut Vec<EnumVariant>) };

        // SAFETY: Getting cursor kind
        let kind = unsafe { clang_getCursorKind(cursor) };

        // CXCursor_EnumConstantDecl = 7
        if kind == 7 {
            // Get variant name
            let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
            let variant_name = unsafe {
                let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
                let name = c_str.to_string_lossy().into_owned();
                clang_disposeString(name_cxstring);
                name
            };

            // Get variant value
            let value = unsafe { clang_getEnumConstantDeclValue(cursor) };

            variants.push(EnumVariant::new(variant_name, Some(value)));
        }

        CXChildVisit_Continue
    }

    unsafe {
        clang_visitChildren(cursor, visit_enum_constants, variants_ptr as CXClientData);
    }

    // Only return if there are variants (skip empty enums)
    if variants.is_empty() {
        return None;
    }

    Some(Enum::new(name, variants))
}

/// Extract macro definition from a clang cursor.
///
/// Extract variable declaration information from a clang cursor.
///
/// Extracts global and local variable declarations, including function pointers.
///
/// # Examples
///
/// Simple: `int x;`
/// Function pointer: `int (*callback)(int);`
pub(crate) fn extract_variable(cursor: CXCursor) -> Option<Variable> {
    // SAFETY: Getting cursor spelling (variable name)
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // SAFETY: Getting variable type
    let cx_type = unsafe { clang_getCursorType(cursor) };
    let var_type = convert_type(cx_type)?;

    // Extract storage class specifiers
    // CX_StorageClass values (from clang-sys):
    // CX_SC_Invalid = 0, CX_SC_None = 1, CX_SC_Extern = 2, CX_SC_Static = 3,
    // CX_SC_PrivateExtern = 4, CX_SC_OpenCLWorkGroupLocal = 5,
    // CX_SC_Auto = 6, CX_SC_Register = 7
    let storage_class = unsafe { clang_Cursor_getStorageClass(cursor) };
    let is_static = storage_class == 3; // CX_SC_Static
    let is_extern = storage_class == 2; // CX_SC_Extern

    // Check if type is const-qualified
    let is_const = unsafe { clang_isConstQualifiedType(cx_type) != 0 };

    // Extract initializer by visiting children
    let mut initializer: Option<Expression> = None;
    let initializer_ptr = &mut initializer as *mut Option<Expression>;

    unsafe {
        clang_visitChildren(cursor, visit_variable_initializer, initializer_ptr as CXClientData);
    }

    Some(Variable::new_with_storage_class(
        name,
        var_type,
        initializer,
        is_static,
        is_extern,
        is_const,
    ))
}

///
/// Object-like: `#define MAX 100`
/// Function-like: `#define SQR(x) ((x) * (x))`
pub(crate) fn extract_macro(cursor: CXCursor) -> Option<MacroDefinition> {
    // SAFETY: Getting macro name
    let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
    let name = unsafe {
        let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
        let name = c_str.to_string_lossy().into_owned();
        clang_disposeString(name_cxstring);
        name
    };

    // Skip empty macro names
    if name.is_empty() {
        return None;
    }

    // Get macro body using clang_Cursor_isMacroFunctionLike and clang token APIs
    // For now, we'll check if it's function-like and extract tokens
    let is_function_like = unsafe { clang_sys::clang_Cursor_isMacroFunctionLike(cursor) } != 0;

    // Get the source range and tokens for the macro
    let range = unsafe { clang_getCursorExtent(cursor) };
    let tu = unsafe { clang_Cursor_getTranslationUnit(cursor) };

    let mut tokens: *mut CXToken = ptr::null_mut();
    let mut num_tokens: u32 = 0;

    unsafe {
        clang_tokenize(tu, range, &mut tokens, &mut num_tokens);
    }

    // Extract macro body from tokens
    // Skip the first token (macro name) and extract the rest
    let mut parameters = Vec::new();
    let mut body_tokens = Vec::new();
    let mut in_params = false;

    for i in 0..num_tokens {
        let token = unsafe { *tokens.offset(i as isize) };
        let token_kind = unsafe { clang_getTokenKind(token) };
        let token_spelling = unsafe { clang_getTokenSpelling(tu, token) };
        let token_str = unsafe {
            let c_str = CStr::from_ptr(clang_getCString(token_spelling));
            let s = c_str.to_string_lossy().into_owned();
            clang_disposeString(token_spelling);
            s
        };

        // Skip the macro name (first token)
        if i == 0 {
            continue;
        }

        // Check for parameter list (function-like macros)
        if is_function_like && i == 1 && token_str == "(" {
            in_params = true;
            continue;
        }

        if in_params {
            if token_str == ")" {
                in_params = false;
                continue;
            } else if token_str != ","
                && (token_kind == CXToken_Identifier || token_kind == CXToken_Keyword)
            {
                // Accept both identifiers and keywords as parameter names
                // C allows keywords in macro parameter names since they're in macro scope
                parameters.push(token_str);
            }
        } else {
            body_tokens.push(token_str);
        }
    }

    // Clean up tokens
    unsafe {
        clang_disposeTokens(tu, tokens, num_tokens);
    }

    // Join body tokens without spaces (preserving original formatting)
    let body = body_tokens.join("");

    if is_function_like {
        Some(MacroDefinition::new_function_like(name, parameters, body))
    } else {
        Some(MacroDefinition::new_object_like(name, body))
    }
}

/// Visitor callback for struct fields.
///
/// # Safety
///
/// This function is called by clang_visitChildren and must follow C calling conventions.
pub(crate) extern "C" fn visit_struct_fields(
    cursor: CXCursor,
    _parent: CXCursor,
    client_data: CXClientData,
) -> CXChildVisitResult {
    // SAFETY: Converting client data back to fields vector pointer
    let fields = unsafe { &mut *(client_data as *mut Vec<StructField>) };

    // SAFETY: Getting cursor kind
    let kind = unsafe { clang_getCursorKind(cursor) };

    if kind == CXCursor_FieldDecl {
        // Get field name
        let name_cxstring = unsafe { clang_getCursorSpelling(cursor) };
        let name = unsafe {
            let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
            let name = c_str.to_string_lossy().into_owned();
            clang_disposeString(name_cxstring);
            name
        };

        // Get field type
        let cx_type = unsafe { clang_getCursorType(cursor) };
        if let Some(field_type) = convert_type(cx_type) {
            fields.push(StructField::new(name, field_type));
        }
    }

    CXChildVisit_Continue
}

pub(crate) fn convert_type(cx_type: CXType) -> Option<Type> {
    // SAFETY: Getting type kind
    match cx_type.kind {
        CXType_Void => Some(Type::Void),
        3 => Some(Type::Bool), // CXType_Bool = 3 — C99 _Bool
        CXType_Int => Some(Type::Int),
        CXType_UInt => Some(Type::UnsignedInt), // DECY-158: unsigned int → u32
        CXType_UChar => Some(Type::Char),       // unsigned char → u8 (DECY-057 fix)
        CXType_UShort => Some(Type::UnsignedInt), // unsigned short → u32 (safe approximation)
        CXType_ULong => Some(Type::UnsignedInt), // unsigned long → u32 (safe approximation)
        CXType_Short => Some(Type::Int),        // short → i32
        CXType_Long => Some(Type::Int),         // long → i32
        CXType_LongLong => Some(Type::Int),     // long long → i32 (simplified)
        CXType_ULongLong => Some(Type::UnsignedInt), // DECY-158: unsigned long long → u32
        CXType_Float => Some(Type::Float),
        CXType_Double => Some(Type::Double),
        23 => Some(Type::Double), // CXType_LongDouble → f64 (Rust has no long double)
        CXType_Char_S | CXType_Char_U => Some(Type::Char),
        14 => Some(Type::SignedChar), // CXType_SChar - explicitly signed char → i8 (DECY-250)
        CXType_Pointer => {
            // SAFETY: Getting pointee type
            let pointee = unsafe { clang_getPointeeType(cx_type) };

            // Check if the pointee is a function - this is a function pointer
            if pointee.kind == CXType_FunctionProto || pointee.kind == CXType_FunctionNoProto {
                // This is a function pointer type
                // Extract return type
                let return_cx_type = unsafe { clang_getResultType(pointee) };
                let return_type = convert_type(return_cx_type)?;

                // Extract parameter types
                let num_args = unsafe { clang_getNumArgTypes(pointee) };
                let mut param_types = Vec::new();

                for i in 0..num_args {
                    let arg_type = unsafe { clang_getArgType(pointee, i as u32) };
                    if let Some(param_type) = convert_type(arg_type) {
                        param_types.push(param_type);
                    }
                }

                return Some(Type::FunctionPointer {
                    param_types,
                    return_type: Box::new(return_type),
                });
            }

            // Regular pointer (not function pointer)
            convert_type(pointee).map(|t| Type::Pointer(Box::new(t)))
        }
        CXType_FunctionProto | CXType_FunctionNoProto => {
            // Function type (not a pointer to function, but the function type itself)
            // This can occur in typedefs like: typedef int Func(int);
            // Extract return type
            let return_cx_type = unsafe { clang_getResultType(cx_type) };
            let return_type = convert_type(return_cx_type)?;

            // Extract parameter types
            let num_args = unsafe { clang_getNumArgTypes(cx_type) };
            let mut param_types = Vec::new();

            for i in 0..num_args {
                let arg_type = unsafe { clang_getArgType(cx_type, i as u32) };
                if let Some(param_type) = convert_type(arg_type) {
                    param_types.push(param_type);
                }
            }

            Some(Type::FunctionPointer { param_types, return_type: Box::new(return_type) })
        }
        CXType_Record => {
            // SAFETY: Getting type declaration to extract struct name
            let decl = unsafe { clang_getTypeDeclaration(cx_type) };
            let name_cxstring = unsafe { clang_getCursorSpelling(decl) };
            let name = unsafe {
                let c_str = CStr::from_ptr(clang_getCString(name_cxstring));
                let struct_name = c_str.to_string_lossy().into_owned();
                clang_disposeString(name_cxstring);
                struct_name
            };
            Some(Type::Struct(name))
        }
        CXType_Elaborated => {
            // Elaborated types wrap other types (e.g., "struct Point" wraps the Record type)
            // Get the canonical type to unwrap it
            let canonical = unsafe { clang_getCanonicalType(cx_type) };
            convert_type(canonical)
        }
        CXType_Typedef => {
            // DECY-172: Get typedef name first to check for known type aliases
            let typedef_decl = unsafe { clang_getTypeDeclaration(cx_type) };
            let typedef_name_cxstring = unsafe { clang_getCursorSpelling(typedef_decl) };
            let typedef_name = unsafe {
                let c_str = CStr::from_ptr(clang_getCString(typedef_name_cxstring));
                let tn = c_str.to_string_lossy().into_owned();
                clang_disposeString(typedef_name_cxstring);
                tn
            };

            // DECY-172: Preserve size_t, ssize_t, ptrdiff_t as TypeAlias
            // These need to map to usize/isize in Rust for compatibility with .len() etc.
            match typedef_name.as_str() {
                "size_t" | "ssize_t" | "ptrdiff_t" => {
                    return Some(Type::TypeAlias(typedef_name));
                }
                _ => {}
            }

            // DECY-147: For typedefs to anonymous structs, use typedef name as struct name
            // Example: typedef struct { int x; } Point; → Type::Struct("Point")
            let canonical = unsafe { clang_getCanonicalType(cx_type) };

            // Check if this is a typedef to an anonymous struct
            if canonical.kind == CXType_Record {
                let decl = unsafe { clang_getTypeDeclaration(canonical) };
                let struct_name_cxstring = unsafe { clang_getCursorSpelling(decl) };
                let struct_name = unsafe {
                    let c_str = CStr::from_ptr(clang_getCString(struct_name_cxstring));
                    let sn = c_str.to_string_lossy().into_owned();
                    clang_disposeString(struct_name_cxstring);
                    sn
                };

                // If struct is anonymous, use the typedef name instead
                if struct_name.is_empty() {
                    return Some(Type::Struct(typedef_name));
                }
            }

            // Default: recursively convert the canonical type
            convert_type(canonical)
        }
        CXType_ConstantArray => {
            // Array type - extract element type and size
            let element_cx_type = unsafe { clang_getArrayElementType(cx_type) };
            let element_type = convert_type(element_cx_type)?;

            // Get array size
            let array_size = unsafe { clang_getArraySize(cx_type) };
            let size = if array_size >= 0 { Some(array_size) } else { None };

            Some(Type::Array { element_type: Box::new(element_type), size })
        }
        114 => {
            // CXType_IncompleteArray - flexible array member (C99 §6.7.2.1)
            // DECY-136: char data[] → Vec<u8>
            // Flexible array members have no size specified
            let element_cx_type = unsafe { clang_getArrayElementType(cx_type) };
            let element_type = convert_type(element_cx_type)?;

            // Generate as Array with size None (will be transformed to Vec in codegen)
            Some(Type::Array { element_type: Box::new(element_type), size: None })
        }
        106 => {
            // CXType_Enum - C enums are integers
            // DECY-240: Map enum types to i32 for Rust compatibility
            Some(Type::Int)
        }
        _ => None,
    }
}