# RustLeaf Specification Consistency Issues
**Analysis Date:** 2025-07-18
**Specifications Version:** 1.0
**Total Issues Found:** 19 distinct issues
## Summary
This document catalogs internal consistency issues, contradictions, and gaps discovered during a comprehensive review of the RustLeaf language specifications. Issues are categorized by severity and numbered sequentially for easy reference.
## Issue Categories
### 🔴 Critical Issues (Require Immediate Resolution)
### 🟡 Medium Issues (Should Be Addressed)
### 🔵 Minor Issues (Good to Fix)
---
## Issue 1: 🟡 Pattern Matching Syntax Inconsistencies
**Files Affected:** `08-pattern-matching.md`, `18-appendices.md`
**Location:** Section 8.7 vs Appendix A
**In prose (8.7):**
```
RangePattern = IntegerLiteral ".." IntegerLiteral
```
**In grammar (Appendix A):**
```
RangePattern ::= Expression ".." Expression
| Expression "..=" Expression
```
**Issues:**
1. Grammar allows expressions, prose only allows integer literals
2. Grammar includes `..=` syntax not mentioned in prose
3. Inclusive vs exclusive range semantics unclear
---
## Issue 2: 🟡 Iterator Protocol Implementation Gaps
**Files Affected:** `12-standard-library.md`, `06-statements.md`
**Location:** Section 12.5
**Problem:** The iterator protocol requires checking for unit values, but the type system prohibits unit in boolean contexts.
**From 12.5:**
```
op_next() must return unit (not null) when iteration is complete
Use is_unit() to test for completion (unit cannot be used in boolean contexts)
```
**But examples show:**
```
var next = iter.op_next()
if is_unit(next) { // Correct way
break
}
```
**Missing Details:**
1. What exactly qualifies as "unit"?
2. How is unit distinguished from null in the value system?
3. Performance implications of `is_unit()` checks
---
## Issue 3: 🟡 Built-in Iterator Implementations Underspecified
**Files Affected:** `12-standard-library.md`
**Location:** Section 12.5
The specification states that strings, lists, and dicts implement the iterator protocol but doesn't specify:
1. Whether `"hello".op_iter()` returns a separate iterator object
2. What happens with nested iteration over the same collection
3. Whether iterators maintain state when the underlying collection is modified
**Impact:** Implementation inconsistencies for basic language features.
**Recommendation:** Specify exact behavior for built-in iterator implementations.
---
## Issue 4: 🟡 Module System Path Resolution Ambiguities
**Files Affected:** `10-modules.md`
**Location:** Section 10.4
**Ambiguous Specifications:**
The module resolution algorithm mentions both:
1. "Relative paths resolve from current module's directory (default)"
2. References to `root::` syntax that's not fully explained
**Examples showing confusion:**
```
use math::geometry // Relative to what?
use super::utils // Clear
use root::utils::Logger // What is root exactly?
```
**Missing Specifications:**
1. What exactly constitutes the "project root"?
2. How does `root::` interact with file system structure?
3. What happens with symbolic links or complex directory structures?
---
## Issue 5: 🟡 Circular Dependency Detection Details
**Files Affected:** `10-modules.md`
**Location:** Section 10.6
**Underspecified Behavior:**
```
Runtime error: "Circular dependency detected: module_a → module_b → module_a"
```
**Missing Details:**
1. At what point exactly is the cycle detected?
2. Can cycles be resolved through conditional imports?
3. What about cycles through re-exports?
**Impact:** Unclear module loading behavior in complex scenarios.
**Recommendation:** Define exact circular dependency detection algorithm.
---
## Issue 6: 🔵 Built-in Function Documentation Inconsistencies
**Files Affected:** `11-built-in-functions.md`, `18-appendices.md`
**Location:** Chapter 11 vs Appendix D
**Example Discrepancies:**
**Chapter 11:**
```
range(start, end, step=1) → list
```
**Appendix D:**
```
range(start: int, end: int, step?: int) -> Range
```
**Issues:**
1. Return type differs (list vs Range)
2. Parameter notation differs
3. Multiple functions show similar inconsistencies
---
## Issue 7: 🔵 Missing Built-in Function Specifications
**Files Affected:** Multiple chapters
**Location:** Various sections
**Functions mentioned but not fully specified:**
- `get_doc()` - Mentioned in documentation chapter but not in built-ins
- `callable()` - Mentioned in various examples but signature unclear
- `hash()` - In appendix but not main built-ins chapter
**Impact:** Incomplete function specifications cause implementation uncertainty.
**Recommendation:** Add complete specifications for all mentioned functions.
---
## Issue 8: 🔵 Error Handling Specification Gaps
**Files Affected:** `09-error-handling.md`, `18-appendices.md`
**Location:** Section 9.3 vs Statement/Expression chapters
**Problem:** Try-catch is described as both statement and expression with identical syntax:
```
TryExpression = "try" Block "catch" Pattern Block
TryStatement = "try" Block "catch" Pattern Block
```
**Missing:**
1. How does parser distinguish between statement and expression contexts?
2. Are there syntax differences?
3. What about try without catch (mentioned but not specified)?
---
## Issue 9: 🔵 Error Code Consistency
**Files Affected:** `09-error-handling.md`, `18-appendices.md`
**Location:** Appendix E
**Issues:**
1. Some error examples in main text don't match error codes in appendix
2. Error object structure varies between sections
3. User-defined error code ranges (6000+) not consistently explained
**Impact:** Inconsistent error handling across implementations.
**Recommendation:** Standardize error codes and object structures.
---
## Issue 10: 🔵 Memory Model and Resource Management Gaps
**Files Affected:** `14-memory-model.md`
**Location:** Section 14.4
**Underspecified:**
1. What exactly constitutes a "resource"?
2. What if `close()` method throws an error?
3. Order of cleanup when exceptions occur in cleanup code itself
4. Interaction between garbage collection and resource cleanup
---
## Issue 11: 🔵 Reference vs Value Semantics Edge Cases
**Files Affected:** `14-memory-model.md`
**Location:** Section 14.1 vs 14.2
**Missing specifications:**
1. What happens with string concatenation and memory?
2. How do closures interact with reference semantics?
3. Performance implications of value copying
**Impact:** Memory behavior unclear in edge cases.
**Recommendation:** Define precise memory semantics for all value types.
---
## Issue 12: 🔵 Macro System Specification Gaps
**Files Affected:** `17-macros.md`
**Location:** Section 17.5
**Problems:**
1. AST node structure examples are incomplete
2. How macros access module-level variables not clearly defined
3. Error handling during macro processing underspecified
---
## Issue 13: 🔵 Macro Processing Order Ambiguities
**Files Affected:** `17-macros.md`
**Location:** Section 17.7
**Unclear scenarios:**
1. What happens when macros modify import statements?
2. How do macro dependencies work across modules?
3. Performance implications of macro processing
**Impact:** Unpredictable macro behavior in complex scenarios.
**Recommendation:** Define complete macro processing semantics.
---
## Issue 14: 🔵 Type System Edge Cases
**Files Affected:** `03-types.md`, `16-rustvalue-integration.md`
**Location:** Section 16.2
**Missing specifications:**
1. How RustValue types interact with pattern matching
2. Whether RustValue can implement iterator protocol
3. Memory management for RustValue with native resources
---
## Issue 15: 🔵 Type Coercion Rules Incomplete
**Files Affected:** `03-types.md`
**Location:** Section 3.6
**Gaps:**
1. String interpolation conversion rules not fully specified
2. Operator overloading interaction with type system
3. What constitutes "compatible types" for operations
**Impact:** Ambiguous type conversion behavior.
**Recommendation:** Define complete type coercion rules.
---
## Issue 16: 🔵 Standard Library Method Consistency
**Files Affected:** `12-standard-library.md`
**Location:** Various subsections
**Inconsistencies:**
1. Some methods return `self` for chaining, others don't
2. Error behavior varies between similar methods
3. Mutating vs non-mutating method distinctions unclear
**Examples:**
```
list.append(item) → self // Returns self
list.pop() → value // Returns value
list.remove(item) → self // Returns self
list.index(item) → int // Returns int but could throw
```
---
## Issue 17: 🔵 Collection Method Error Handling
**Files Affected:** `12-standard-library.md`
**Location:** Section 12.2, 12.3
**Inconsistent error behavior:**
- `list.pop()` on empty list - error
- `dict.pop(key)` with missing key - returns default or error?
- `list.remove(item)` with missing item - error
**Impact:** Inconsistent method behavior expectations.
**Recommendation:** Standardize error handling patterns across all collection methods.
---
## Issue 18: 🔵 Documentation and Comments Specification Gaps
**Files Affected:** `13-documentation-comments.md`
**Location:** Section 13.9
**Problems:**
1. `get_doc()` function not defined in built-ins
2. Performance implications of runtime documentation access
3. How documentation relates to source file locations
---
## Issue 19: 🔵 Documentation Format Validation
**Files Affected:** `13-documentation-comments.md`
**Location:** Section 13.8
**Missing:**
1. How are malformed documentation comments handled?
2. What happens with conflicting documentation formats?
3. Tool integration specifications incomplete
**Impact:** Unclear documentation processing behavior.
**Recommendation:** Define complete documentation validation and processing rules.
---
## Recommendations for Resolution
### Immediate Priority (Critical Issues)
1. **Resolve null vs unit semantics** - Define clear rules for when each is used
2. **Fix keyword consistency** - Remove undefined keywords or define their syntax
3. **Complete ternary operator specification** - Add missing syntax documentation
4. **Clarify assignment statement/expression distinction** - Remove confusing deprecation notes
### Medium Priority
1. **Standardize pattern matching syntax** - Align grammar with prose
2. **Complete iterator protocol specification** - Add implementation details
3. **Clarify module resolution algorithm** - Define exact path resolution rules
4. **Align built-in function documentation** - Ensure consistency between chapters
### Lower Priority
1. **Add missing error specifications** - Complete error handling details
2. **Expand memory model details** - Add edge case behaviors
3. **Complete macro system specification** - Add AST and processing details
4. **Standardize method return behaviors** - Ensure consistent patterns
## Conclusion
The RustLeaf specification is comprehensive but contains several internal consistency issues that could lead to implementation divergence and developer confusion. Addressing the critical issues first will ensure a solid foundation for language implementation, while the medium and lower priority issues will improve the overall quality and completeness of the specification.
Most issues stem from:
1. **Incomplete specification transfers** - Features mentioned but not fully defined
2. **Copy-paste inconsistencies** - Similar concepts with slight variations
3. **Missing cross-references** - Changes in one section not reflected in others
4. **Underspecified edge cases** - Common scenarios not covered
Resolving these issues will significantly improve the specification's utility for implementers and users of the RustLeaf language.