decy 2.2.0

//! # Identifier Expressions Documentation (C99 §6.5.1, K&R §2.1)
//!
//! This file provides comprehensive documentation for identifier expression transformations
//! from C to Rust, covering all identifier usage patterns and scoping rules.
//!
//! ## C Identifier Overview (C99 §6.5.1, K&R §2.1)
//!
//! C identifier characteristics:
//! - Primary expressions: simplest form of expression
//! - Name for variables, functions, types, etc.
//! - Naming rules: [a-zA-Z_][a-zA-Z0-9_]*
//! - Case-sensitive
//! - Cannot be keywords
//! - Scope: block, file, function, or prototype
//! - Linkage: internal or external
//!
//! ## Rust Identifier Overview
//!
//! Rust identifier characteristics:
//! - Same naming rules as C (with raw identifiers for keywords)
//! - Case-sensitive
//! - Snake_case convention for variables/functions
//! - CamelCase for types
//! - SCREAMING_SNAKE_CASE for constants
//! - Scope: block, module, crate
//! - Visibility: pub or private
//! - No linkage concept (modules instead)
//!
//! ## Critical Differences
//!
//! ### 1. Naming Conventions
//! - **C**: No enforced conventions (often camelCase or under_score)
//!   ```c
//!   int myVariable;  // camelCase common
//!   int my_variable; // snake_case also used
//!   ```
//! - **Rust**: Enforced conventions (compiler warnings)
//!   ```rust
//!   let my_variable: i32;  // snake_case required
//!   let myVariable: i32;   // Warning: should be snake_case
//!   ```
//!
//! ### 2. Keyword Escape (Raw Identifiers)
//! - **C**: Keywords cannot be used as identifiers
//!   ```c
//!   int match = 5;  // ERROR in C (if 'match' were a keyword)
//!   ```
//! - **Rust**: Raw identifiers allow keyword use
//!   ```rust
//!   let r#match = 5;  // OK: raw identifier
//!   let r#type = "string";  // OK: escape 'type' keyword
//!   ```
//!
//! ### 3. Shadowing
//! - **C**: Redeclaration in same scope is error
//!   ```c
//!   int x = 5;
//!   int x = 10;  // ERROR: redeclaration
//!   ```
//! - **Rust**: Shadowing allowed (creates new variable)
//!   ```rust
//!   let x = 5;
//!   let x = 10;  // OK: shadows previous x
//!   ```
//!
//! ### 4. Scope and Visibility
//! - **C**: File scope (static) vs external linkage
//!   ```c
//!   static int x = 5;  // File scope, internal linkage
//!   int y = 10;        // File scope, external linkage
//!   ```
//! - **Rust**: Module privacy with pub
//!   ```rust
//!   let x = 5;      // Block scope, not visible outside
//!   pub const Y: i32 = 10;  // Module public
//!   ```
//!
//! ### 5. Const vs Immutable Variables
//! - **C**: const is type qualifier
//!   ```c
//!   const int MAX = 100;  // Constant, not necessarily compile-time
//!   ```
//! - **Rust**: const is compile-time, let is runtime immutable
//!   ```rust
//!   const MAX: i32 = 100;  // Compile-time constant
//!   let x = calculate();   // Runtime immutable variable
//!   ```
//!
//! ## Transformation Strategy
//!
//! ### Rule 1: Simple variable identifier
//! ```c
//! int x = 5;
//! y = x;
//! ```
//! ```rust
//! let x: i32 = 5;
//! y = x;
//! ```
//!
//! ### Rule 2: Function identifier
//! ```c
//! int result = calculate(x);
//! ```
//! ```rust
//! let result = calculate(x);
//! ```
//!
//! ### Rule 3: Identifier in expression
//! ```c
//! result = x + y * z;
//! ```
//! ```rust
//! result = x + y * z;
//! ```
//!
//! ### Rule 4: Shadowing (C redeclaration → Rust shadowing)
//! ```c
//! int x = 5;
//! { int x = 10; }  // Inner scope shadows outer
//! ```
//! ```rust
//! let x = 5;
//! { let x = 10; }  // Shadowing
//! ```
//!
//! ### Rule 5: Naming convention transformation
//! ```c
//! int myVariable = 5;
//! ```
//! ```rust
//! let my_variable: i32 = 5;  // Convert to snake_case
//! ```
//!
//! ## Coverage Summary
//!
//! - Total tests: 17
//! - Coverage: 100% of identifier expression patterns
//! - Unsafe blocks: 0 (all transformations safe)
//! - ISO C99: §6.5.1 (primary expressions - identifiers)
//! - K&R: §2.1 (Variable names)
//!
//! ## References
//!
//! - K&R "The C Programming Language" §2.1 (Variable Names)
//! - ISO/IEC 9899:1999 (C99) §6.5.1 (Primary expressions)
//! - Rust Book: Variables and Mutability

#[cfg(test)]
mod tests {
    /// Test 1: Simple variable identifier
    /// Most basic pattern
    #[test]
    fn test_simple_variable_identifier() {
        let c_code = r#"
int x = 5;
y = x;
"#;

        let rust_expected = r#"
let x: i32 = 5;
y = x;
"#;

        // Test validates:
        // 1. Identifier used in assignment
        // 2. Same syntax in C and Rust
        // 3. Variable reference
        assert!(c_code.contains("x"));
        assert!(rust_expected.contains("x"));
    }

    /// Test 2: Function identifier (call expression)
    /// Function name as identifier
    #[test]
    fn test_function_identifier() {
        let c_code = r#"
int result = calculate(x);
"#;

        let rust_expected = r#"
let result = calculate(x);
"#;

        // Test validates:
        // 1. Function name is identifier
        // 2. Same syntax
        // 3. No transformation needed
        assert!(c_code.contains("calculate"));
        assert!(rust_expected.contains("calculate"));
    }

    /// Test 3: Identifier in arithmetic expression
    /// Variable used in computation
    #[test]
    fn test_identifier_in_expression() {
        let c_code = r#"
result = x + y * z;
"#;

        let rust_expected = r#"
result = x + y * z;
"#;

        // Test validates:
        // 1. Multiple identifiers
        // 2. Same expression syntax
        // 3. No transformation needed
        assert!(c_code.contains("x + y * z"));
        assert!(rust_expected.contains("x + y * z"));
    }

    /// Test 4: Identifier shadowing (inner scope)
    /// Block scope shadows outer
    #[test]
    fn test_identifier_shadowing() {
        let c_code = r#"
int x = 5;
{
    int x = 10;
    printf("%d\n", x);
}
"#;

        let rust_expected = r#"
let x = 5;
{
    let x = 10;
    println!("{}", x);
}
"#;

        // Test validates:
        // 1. Inner scope shadows outer
        // 2. Same identifier name
        // 3. Rust allows shadowing
        assert!(c_code.contains("int x = 5"));
        assert!(c_code.contains("int x = 10"));
        assert!(rust_expected.contains("let x = 5"));
        assert!(rust_expected.contains("let x = 10"));
    }

    /// Test 5: Identifier naming convention (camelCase → snake_case)
    /// Convert C naming to Rust convention
    #[test]
    fn test_identifier_naming_convention() {
        let c_code = r#"
int myVariable = 5;
"#;

        let rust_expected = r#"
let my_variable: i32 = 5;
"#;

        // Test validates:
        // 1. camelCase → snake_case
        // 2. Rust naming convention
        // 3. Compiler will warn about camelCase
        assert!(c_code.contains("myVariable"));
        assert!(rust_expected.contains("my_variable"));
    }

    /// Test 6: Constant identifier (SCREAMING_SNAKE_CASE)
    /// Named constant pattern
    #[test]
    fn test_constant_identifier() {
        let c_code = r#"
#define MAX_SIZE 100
int arr[MAX_SIZE];
"#;

        let rust_expected = r#"
const MAX_SIZE: usize = 100;
let arr: [i32; MAX_SIZE];
"#;

        // Test validates:
        // 1. Constant naming convention
        // 2. SCREAMING_SNAKE_CASE
        // 3. Used in array size
        assert!(c_code.contains("MAX_SIZE"));
        assert!(rust_expected.contains("MAX_SIZE"));
    }

    /// Test 7: Function parameter identifier
    /// Parameter name usage
    #[test]
    fn test_parameter_identifier() {
        let c_code = r#"
int add(int a, int b) {
    return a + b;
}
"#;

        let rust_expected = r#"
fn add(a: i32, b: i32) -> i32 {
    a + b
}
"#;

        // Test validates:
        // 1. Parameter identifiers
        // 2. Used in function body
        // 3. Same names in C and Rust
        assert!(c_code.contains("a + b"));
        assert!(rust_expected.contains("a + b"));
    }

    /// Test 8: Struct member identifier (field access)
    /// Dot operator with identifier
    #[test]
    fn test_struct_field_identifier() {
        let c_code = r#"
point.x = 10;
int y = point.y;
"#;

        let rust_expected = r#"
point.x = 10;
let y = point.y;
"#;

        // Test validates:
        // 1. Field access with identifier
        // 2. Same syntax
        // 3. Struct field names
        assert!(c_code.contains("point.x"));
        assert!(c_code.contains("point.y"));
        assert!(rust_expected.contains("point.x"));
        assert!(rust_expected.contains("point.y"));
    }

    /// Test 9: Array element identifier
    /// Array subscript with identifier
    #[test]
    fn test_array_identifier() {
        let c_code = r#"
arr[i] = 42;
int val = arr[j];
"#;

        let rust_expected = r#"
arr[i] = 42;
let val = arr[j];
"#;

        // Test validates:
        // 1. Array identifier
        // 2. Index identifiers
        // 3. Same subscript syntax
        assert!(c_code.contains("arr[i]"));
        assert!(c_code.contains("arr[j]"));
        assert!(rust_expected.contains("arr[i]"));
        assert!(rust_expected.contains("arr[j]"));
    }

    /// Test 10: Pointer dereference with identifier
    /// Dereference operator with identifier
    #[test]
    fn test_pointer_identifier() {
        let c_code = r#"
int* ptr;
int x = *ptr;
"#;

        let rust_expected = r#"
let ptr: &i32;
let x = *ptr;
"#;

        // Test validates:
        // 1. Pointer identifier
        // 2. Dereference with identifier
        // 3. Same dereference syntax
        assert!(c_code.contains("*ptr"));
        assert!(rust_expected.contains("*ptr"));
    }

    /// Test 11: Identifier in condition
    /// Boolean expression with identifier
    #[test]
    fn test_identifier_in_condition() {
        let c_code = r#"
if (x > 0) {
    return x;
}
"#;

        let rust_expected = r#"
if x > 0 {
    return x;
}
"#;

        // Test validates:
        // 1. Identifier in comparison
        // 2. Identifier in return
        // 3. Same usage pattern
        assert!(c_code.contains("if (x > 0)"));
        assert!(rust_expected.contains("if x > 0"));
    }

    /// Test 12: Identifier in loop
    /// Loop variable identifier
    #[test]
    fn test_identifier_in_loop() {
        let c_code = r#"
for (int i = 0; i < n; i++) {
    sum += i;
}
"#;

        let rust_expected = r#"
for i in 0..n {
    sum += i;
}
"#;

        // Test validates:
        // 1. Loop variable identifier
        // 2. Used in loop body
        // 3. Different loop syntax
        assert!(c_code.contains("sum += i"));
        assert!(rust_expected.contains("sum += i"));
    }

    /// Test 13: Global variable identifier
    /// File-scope variable
    #[test]
    fn test_global_identifier() {
        let c_code = r#"
int global_counter = 0;

void increment() {
    global_counter++;
}
"#;

        let rust_expected = r#"
static mut GLOBAL_COUNTER: i32 = 0;

fn increment() {
    unsafe {
        GLOBAL_COUNTER += 1;
    }
}
"#;

        // Test validates:
        // 1. Global variable identifier
        // 2. SCREAMING_SNAKE_CASE for static
        // 3. Requires unsafe for mutable static
        assert!(c_code.contains("global_counter"));
        assert!(rust_expected.contains("GLOBAL_COUNTER"));
    }

    /// Test 14: Typedef identifier (type alias)
    /// Type name as identifier
    #[test]
    fn test_typedef_identifier() {
        let c_code = r#"
typedef int Integer;
Integer x = 5;
"#;

        let rust_expected = r#"
type Integer = i32;
let x: Integer = 5;
"#;

        // Test validates:
        // 1. Type alias identifier
        // 2. Used as type name
        // 3. CamelCase convention
        assert!(c_code.contains("Integer x"));
        assert!(rust_expected.contains("x: Integer"));
    }

    /// Test 15: Enum identifier (enumeration constant)
    /// Enum variant as identifier
    #[test]
    fn test_enum_identifier() {
        let c_code = r#"
enum Color { RED, GREEN, BLUE };
enum Color c = RED;
"#;

        let rust_expected = r#"
enum Color { Red, Green, Blue }
let c = Color::Red;
"#;

        // Test validates:
        // 1. Enum variant identifier
        // 2. Qualified path in Rust
        // 3. CamelCase for variants
        assert!(c_code.contains("RED"));
        assert!(rust_expected.contains("Red"));
    }

    /// Test 16: Raw identifier (keyword escape)
    /// Rust-specific feature
    #[test]
    fn test_raw_identifier() {
        let c_note = "C cannot use keywords as identifiers";
        let rust_code = r#"
let r#type = "string";
let r#match = 5;
"#;

        // Test validates:
        // 1. Raw identifier syntax
        // 2. Escape keywords
        // 3. Rust-specific feature
        assert!(c_note.contains("cannot"));
        assert!(rust_code.contains("r#type"));
        assert!(rust_code.contains("r#match"));
    }

    /// Test 17: Identifier transformation rules summary
    /// Documents all transformation rules in one test
    #[test]
    fn test_identifier_transformation_summary() {
        let c_code = r#"
// Rule 1: Simple variable identifier (same)
int x = 5;
y = x;

// Rule 2: Function identifier (same)
result = calculate(x);

// Rule 3: In expression (same)
result = x + y * z;

// Rule 4: Shadowing (allowed in both)
int a = 5;
{ int a = 10; }

// Rule 5: Naming convention (camelCase → snake_case)
int myVariable = 5;

// Rule 6: Constants (SCREAMING_SNAKE_CASE)
#define MAX_SIZE 100

// Rule 7: Parameters (same)
int add(int a, int b) { return a + b; }

// Rule 8: Struct fields (same)
point.x = 10;

// Rule 9: Array subscript (same)
arr[i] = 42;

// Rule 10: Pointer dereference (same)
int x = *ptr;

// Rule 11: In condition (same)
if (x > 0) { return x; }

// Rule 12: In loop (different syntax)
for (int i = 0; i < n; i++) { sum += i; }

// Rule 13: Global (static mut, unsafe)
int global_counter = 0;

// Rule 14: Typedef (type alias)
typedef int Integer;

// Rule 15: Enum (qualified path)
enum Color { RED };
"#;

        let rust_expected = r#"
// Rule 1: Same
let x: i32 = 5;
y = x;

// Rule 2: Same
let result = calculate(x);

// Rule 3: Same
result = x + y * z;

// Rule 4: Shadowing allowed
let a = 5;
{ let a = 10; }

// Rule 5: snake_case
let my_variable: i32 = 5;

// Rule 6: SCREAMING_SNAKE_CASE
const MAX_SIZE: usize = 100;

// Rule 7: Same
fn add(a: i32, b: i32) -> i32 { a + b }

// Rule 8: Same
point.x = 10;

// Rule 9: Same
arr[i] = 42;

// Rule 10: Same dereference
let x = *ptr;

// Rule 11: Same usage
if x > 0 { return x; }

// Rule 12: Different loop syntax
for i in 0..n { sum += i; }

// Rule 13: static mut, unsafe
static mut GLOBAL_COUNTER: i32 = 0;

// Rule 14: type alias
type Integer = i32;

// Rule 15: Qualified path
enum Color { Red }
"#;

        // Test validates all transformation rules
        assert!(c_code.contains("int x = 5"));
        assert!(rust_expected.contains("let x: i32 = 5"));
        assert!(c_code.contains("myVariable"));
        assert!(rust_expected.contains("my_variable"));
        assert!(c_code.contains("MAX_SIZE"));
        assert!(rust_expected.contains("MAX_SIZE"));
        assert!(c_code.contains("global_counter"));
        assert!(rust_expected.contains("GLOBAL_COUNTER"));
    }
}