More/updated/specialized critics

[ai-review] / critic / c-types.md

# C Type System Validation Critic Framework (ISO/IEC JTC 1/SC 22)

This framework guides the Critic role when evaluating C programming code for type safety issues, proper type usage, and data representation correctness from the perspective of ISO/IEC JTC 1/SC 22, the committee responsible for programming languages including the ISO/IEC 9899:1999 (C99) standard. This critic focuses on type conversions, arithmetic safety, structure/union usage, alignment considerations, and the fundamental principles that ensure reliable, efficient, and maintainable C code through proper type system usage.

## C Type System Evaluation Areas

### 1. Type Conversions and Promotions
**What to Look For:**
- Correct use of fundamental and derived types
- Proper type conversions and promotions according to standard rules
- Appropriate use of explicit vs implicit conversions
- Safe handling of type conversion side effects
- Compliance with standard conversion rules

**Common Problems:**
- Implicit type conversions that change meaning or violate standard rules
- Loss of precision in floating-point conversions without explicit intent
- Unsafe integer type conversions that invoke undefined behavior
- Incorrect use of type casting operators
- Missing explicit conversions where standard requires them
- Violation of standard conversion rules

**Evaluation Questions:**
- Are type conversions explicit and intentional according to standard requirements?
- Do conversions preserve the intended meaning and comply with standard rules?
- Is precision loss handled appropriately and documented?
- Are implicit conversions used safely and in compliance with the standard?
- Is type casting done for the right reasons and in accordance with standard rules?

### 2. Signed vs Unsigned Arithmetic
**What to Look For:**
- Appropriate use of signed vs unsigned types according to standard specifications
- Safe mixing of signed and unsigned arithmetic that doesn't invoke undefined behavior
- Proper handling of integer overflow/underflow as defined by the standard
- Correct comparison between signed and unsigned values
- Compliance with standard arithmetic rules

**Common Problems:**
- Mixing signed and unsigned arithmetic inappropriately, invoking undefined behavior
- Integer overflow in signed arithmetic that violates standard requirements
- Unsigned underflow (wrapping) issues that may be unexpected
- Incorrect comparisons between signed and unsigned that violate standard rules
- Assumptions about integer representation that are implementation-defined

**Evaluation Questions:**
- Is the choice between signed and unsigned types appropriate for the standard requirements?
- Is signed/unsigned arithmetic mixed safely without invoking undefined behavior?
- Is integer overflow/underflow handled correctly according to standard specifications?
- Are comparisons between signed and unsigned values correct per standard rules?
- Are integer size assumptions documented and implementation-defined behaviors noted?

### 3. Structure and Union Usage
**What to Look For:**
- Correct structure padding and alignment considerations as defined by the standard
- Proper use of union types for type punning within standard constraints
- Safe structure member access and initialization according to standard rules
- Appropriate use of bit fields as specified by the standard
- Compliance with standard structure and union rules

**Common Problems:**
- Assumptions about structure layout and padding that are implementation-defined
- Incorrect use of unions for type punning that violates strict aliasing rules
- Uninitialized structure members that lead to undefined behavior
- Misaligned structure access that violates alignment requirements
- Incorrect bit field usage that doesn't comply with standard specifications

**Evaluation Questions:**
- Are structure layouts considered for portability across conforming implementations?
- Are union types used correctly for their intended purpose within standard constraints?
- Are structure members properly initialized according to standard requirements?
- Is structure alignment handled correctly and documented where implementation-defined?
- Are bit fields used appropriately and in compliance with standard specifications?

### 4. Alignment and Data Representation
**What to Look For:**
- Proper handling of data alignment requirements as specified by the standard
- Correct use of alignment specifiers where standard allows them
- Safe access to unaligned data that doesn't violate standard requirements
- Appropriate use of packed structures within standard constraints
- Compliance with standard data representation rules

**Common Problems:**
- Accessing data with incorrect alignment that violates standard requirements
- Missing alignment specifiers where standard requires them
- Incorrect assumptions about data representation that are implementation-defined
- Unsafe use of packed structures that may violate standard constraints
- Endianness-dependent code without proper handling for portability

**Evaluation Questions:**
- Is data alignment handled correctly according to standard specifications?
- Are alignment requirements documented where they are implementation-defined?
- Is endianness handled when necessary for portability across conforming implementations?
- Are packed structures used safely and in compliance with standard constraints?
- Is data representation portable across different conforming implementations?

### 5. Type Safety and Standard Compliance
**What to Look For:**
- Strict adherence to ISO/IEC 9899 type system specifications
- Proper use of standard types and their defined behaviors
- Correct implementation of type-related language features as defined
- Avoidance of type-related undefined behavior

**Common Problems:**
- Use of non-standard type extensions without proper guards
- Reliance on type-related undefined behavior (e.g., invalid pointer arithmetic)
- Incorrect assumptions about implementation-defined type behaviors
- Violation of type system syntax or semantic rules
- Missing or incorrect type-related standard library usage

**Evaluation Questions:**
- Does the type usage conform to the ISO C standard without relying on extensions?
- Are all type-related standard library functions used correctly according to specification?
- Is type-related undefined behavior properly avoided throughout the implementation?
- Are implementation-defined type behaviors documented and handled appropriately?
- Does the type system usage compile cleanly with standard-compliant compilers?

### 6. Performance and Type Efficiency
**What to Look For:**
- Efficient type usage that doesn't sacrifice correctness
- Minimal type conversion overhead where appropriate
- Cache-friendly type layouts and access patterns
- Proper use of type-related compiler optimization hints
- Avoidance of unnecessary type-related function call overhead

**Common Problems:**
- Inefficient type usage that impacts performance unnecessarily
- Excessive type conversions that add runtime overhead
- Poor cache locality in type-related data access
- Missing type-related optimization opportunities
- Premature or inappropriate type-related optimization

**Evaluation Questions:**
- Are the type choices appropriate for the performance requirements?
- Is type conversion overhead minimized and efficient?
- Are type-related data structures laid out for good cache performance?
- Are type-related optimization hints used appropriately?
- Is the type system optimized at the right level of abstraction?

## ISO/IEC Standards-Specific Type Criticism Process

### Step 1: Type System Conformance Analysis
1. **Check Type Compliance**: Does type usage conform to ISO C99/C11/C18 standards?
2. **Evaluate Type Library Usage**: Are standard type-related functions used correctly?
3. **Assess Type-Related Undefined Behavior**: Is type-related undefined behavior properly avoided?
4. **Review Type Implementation Dependencies**: Are implementation-defined type behaviors documented?

### Step 2: Type Safety Assessment
1. **Audit Type Conversions**: Are all type conversions safe and standard-compliant?
2. **Check Type Arithmetic**: Are all type-related arithmetic operations safe and defined?
3. **Evaluate Type Structure Safety**: Are type-related structure operations safe?
4. **Assess Type Resource Management**: Are type-related resources properly managed?

### Step 3: Type System Evaluation
1. **Review Type Usage**: Are types used appropriately and safely according to standard?
2. **Check Type Conversions**: Are type conversions explicit and correct per standard?
3. **Evaluate Type Arithmetic**: Is type-related arithmetic overflow/underflow handled?
4. **Assess Type Structure Layout**: Are type-related structure dependencies documented?

### Step 4: Type Error Handling Analysis
1. **Check Type Error Propagation**: Are type-related errors detected and reported consistently?
2. **Evaluate Type Recovery**: Can the program recover gracefully from type-related errors?
3. **Assess Type Resource Cleanup**: Are type-related resources cleaned up on error paths?
4. **Review Type Error Documentation**: Are type-related error conditions clearly documented?

## ISO/IEC Standards-Specific Type Criticism Guidelines

### Focus on Type Specification Compliance
**Good Criticism:**
- "This type conversion invokes undefined behavior by violating standard conversion rules"
- "The integer overflow here violates the standard's type arithmetic requirements"
- "This use of union type punning doesn't meet the standard's strict aliasing constraints"
- "The type declaration doesn't match the standard library type specification"

**Poor Criticism:**
- "This type usage doesn't look right"
- "This type conversion seems unsafe"
- "I don't like this type approach"

### Emphasize Type Portability and Correctness
**Good Criticism:**
- "This assumes int is 32 bits, which violates type portability requirements"
- "The structure padding assumptions here are implementation-dependent"
- "This endianness-dependent type code needs conditional compilation guards"
- "The type alignment requirements here are not guaranteed by the standard"

**Poor Criticism:**
- "This type usage won't work everywhere"
- "This type approach is not portable"
- "This type code might cause problems"

### Consider Type Implementation Quality
**Good Criticism:**
- "The type conversion checking here is incomplete - potential precision loss"
- "This type arithmetic doesn't validate bounds as required by standard"
- "The type conversion here loses precision without explicit intent"
- "The type-related resource cleanup on this error path is missing"

**Poor Criticism:**
- "This type code has bugs"
- "This type usage is unreliable"
- "This type code is bad"

## ISO/IEC Standards-Specific Type Problem Categories

### Type Standard Compliance Problems
- **Type Undefined Behavior**: Type usage that invokes undefined behavior according to the standard
- **Type Implementation Dependencies**: Unwarranted assumptions about type implementation details
- **Non-Standard Type Extensions**: Use of compiler-specific type features without proper guards
- **Type Library Misuse**: Incorrect usage of standard type-related library functions

### Type Safety Problems
- **Type Conversion Errors**: Unsafe type conversions that violate standard rules
- **Type Arithmetic Overflow**: Type-related arithmetic that exceeds type limits
- **Type Alignment Violations**: Accessing typed data with incorrect alignment
- **Type Union Misuse**: Incorrect use of unions for type punning

### Type Portability Problems
- **Type Size Assumptions**: Assuming specific sizes for fundamental types
- **Type Endianness Dependencies**: Type code that doesn't handle byte order correctly
- **Type Platform-Specific Code**: Unguarded use of platform-specific type features
- **Type Missing Feature Detection**: No checks for optional standard type features

### Type Error Handling Problems
- **Type Unchecked Errors**: Ignoring type-related function return values that indicate errors
- **Type Resource Leaks**: Failing to clean up type-related resources on error paths
- **Type Inconsistent Handling**: Different type error handling patterns in similar contexts
- **Type Poor Error Reporting**: Unclear or missing type-related error information

## ISO/IEC Standards-Specific Type Criticism Templates

### For Type Standard Compliance Issues
```
Type Standard Compliance Issue: [Specific standard type violation]
Standard Reference: [ISO/IEC 9899 section and paragraph]
Problem: [How this violates the type system specification]
Impact: [Undefined behavior, implementation dependency, or non-conformance]
Evidence: [Specific type code examples and standard citations]
Priority: [Critical/High/Medium/Low]
```

### For Type Safety Issues
```
Type Safety Issue: [Specific type safety problem]
Problem: [What makes this type usage unsafe or incorrect]
Impact: [Potential crashes, corruption, or security vulnerabilities]
Evidence: [Specific type code paths and failure scenarios]
Priority: [Critical/High/Medium/Low]
```

### For Type Portability Issues
```
Type Portability Issue: [Specific type portability problem]
Problem: [What type assumptions or dependencies limit portability]
Impact: [Platforms or implementations where this type usage will fail]
Evidence: [Specific type code examples and platform differences]
Priority: [High/Medium/Low]
```

## ISO/IEC Standards-Specific Type Criticism Best Practices

### Do's
- **Cite Standard References**: Always reference specific sections of ISO/IEC 9899 for type issues
- **Focus on Type Specification**: Evaluate against the formal type system specification
- **Consider All Type Implementations**: Think about conforming type implementations, not just one compiler
- **Emphasize Type Correctness**: Prioritize correct type behavior over performance or convenience
- **Document Type Dependencies**: Clearly identify any implementation-defined type behaviors

### Don'ts
- **Assume Specific Type Implementations**: Don't assume particular compiler type behaviors
- **Ignore Type Standard Library**: Don't overlook proper usage of standard type functions
- **Accept Type Undefined Behavior**: Don't tolerate type code that invokes undefined behavior
- **Skip Type Error Checking**: Don't ignore type-related error handling requirements
- **Overlook Type Portability**: Don't accept unnecessarily non-portable type code

## ISO/IEC Standards-Specific Type Criticism Checklist

### Type Standard Compliance Assessment
- [ ] Does the type usage conform to ISO C without relying on extensions?
- [ ] Are all uses of standard type-related library functions correct per specification?
- [ ] Is type-related undefined behavior avoided throughout?
- [ ] Are implementation-defined type behaviors documented?
- [ ] Does the type code compile with multiple conforming compilers?

### Type Safety Assessment
- [ ] Are all type conversions safe and standard-compliant?
- [ ] Are all type-related pointer operations safe and defined?
- [ ] Are type-related array bounds checked and respected?
- [ ] Are type-related resources properly managed on all code paths?
- [ ] Is type-related arithmetic performed safely?

### Type System Assessment
- [ ] Are type conversions explicit and intentional?
- [ ] Is type-related arithmetic overflow/underflow handled correctly?
- [ ] Are signed/unsigned types used appropriately?
- [ ] Are type-related structure layouts considered for portability?
- [ ] Are union types used correctly within standard constraints?

### Type Error Handling Assessment
- [ ] Are all type-related error conditions detected and handled?
- [ ] Are type-related function return values checked when they can indicate errors?
- [ ] Is type-related errno used correctly for functions that set it?
- [ ] Are type-related error paths tested and resources cleaned up?
- [ ] Are type-related error conditions documented clearly?

### Type Portability Assessment
- [ ] Does the type code avoid assumptions about type sizes?
- [ ] Is type-related endianness handled correctly when necessary?
- [ ] Are type-related feature test macros used for conditional compilation?
- [ ] Is platform-specific type code properly abstracted?
- [ ] Are all type-related implementation dependencies documented?

## ISO/IEC Standards-Specific Type Evaluation Questions

### For Any C Code
1. **Does this type usage conform to the ISO C standard without extensions?**
2. **Are all potential sources of type-related undefined behavior eliminated?**
3. **Is type-related memory management correct and complete?**
4. **Are all type-related error conditions properly handled?**
5. **Is the type code portable across conforming implementations?**
6. **Are all type-related standard library functions used correctly?**
7. **Is the type usage safe and appropriate?**
8. **Are all type-related implementation dependencies documented?**
9. **Do all type-related code paths handle errors and cleanup resources?**
10. **Is the type code efficient without sacrificing correctness?**

### For Library Code
1. **Are all public type interfaces documented with preconditions and postconditions?**
2. **Is type-related thread safety clearly specified and implemented correctly?**
3. **Are all type-related parameters validated appropriately?**
4. **Is the type-related API design consistent with standard library conventions?**
5. **Are all type-related resources properly managed by the library?**

### For System Code
1. **Are all type-related system calls checked for errors?**
2. **Is type-related privilege escalation handled securely?**
3. **Are type-related buffer sizes validated before use?**
4. **Is type-related concurrency handled correctly?**
5. **Are all type-related security implications considered and addressed?**

## C99 Standard Type System Principles Applied

### "Provide a Portable Type System"
- Write type code that works across different conforming implementations
- Avoid reliance on implementation-specific type behaviors
- Use standard types and type-related functions for maximum portability

### "Keep the Type System Small and Simple"
- Use type system features appropriately for their intended purpose
- Avoid overly complex type constructs when simpler alternatives exist
- Prefer clear, readable type code over clever type implementations

### "Provide Only One Way to Do a Type Operation"
- Use standard type idioms and patterns consistently
- Avoid redundant or alternative approaches to the same type problem
- Follow established conventions for common type operations

### "Make Type Operations Fast"
- Write efficient type code that compiles to good machine code
- Understand the performance implications of type system features
- Optimize type usage appropriately without sacrificing correctness or clarity

### "Trust the Type System"
- Provide tools for experienced programmers to write efficient type code
- Allow low-level type control when necessary
- Don't prevent legitimate but potentially dangerous type operations

### "Don't Prevent the Programmer from Doing What Needs to be Done"
- Enable system programming and direct type-related hardware access
- Provide mechanisms for all necessary type operations
- Allow overriding type safety checks when explicitly requested

## C Standard Library Type System Evaluation Criteria

### Type-Related Memory Management Functions
- **malloc/free family**: Proper type pairing, error checking, alignment considerations
- **Type-related string functions**: Buffer bounds, null termination, overlap handling
- **Type-related memory functions**: Overlap restrictions, size calculations, pointer validity

### Type-Related Input/Output Functions
- **Type-related file operations**: Error checking, resource cleanup, mode specifications
- **Type-related formatted I/O**: Format string validation, buffer sizes, return value checking
- **Type-related character I/O**: EOF handling, error conditions, buffering implications

### Type-Related String and Character Functions
- **Type-related string manipulation**: Buffer sizes, null termination, locale considerations
- **Type-related character classification**: Locale dependencies, proper argument ranges
- **Type-related string conversion**: Error detection, overflow handling, locale awareness

### Type-Related Mathematical Functions
- **Type-related floating point**: Error handling, special values, precision considerations
- **Type-related integer arithmetic**: Overflow detection, signed/unsigned conversions
- **Type-related random numbers**: Seeding, distribution, thread safety

### Type-Related Time and Date Functions
- **Type-related time representation**: Overflow handling, timezone considerations, Y2038 issues
- **Type-related formatting**: Locale dependencies, buffer sizes, error conditions
- **Type-related conversion**: Precision loss, range validation, platform differences