Complexity analysis

README.md

@@ -231,20 +231,55 @@ See [website/docs/specifications/mlir.md](website/docs/specifications/mlir.md) f
 ## CLI Usage
 
 ```bash
-# Lex (tokenize) a file
-./zig-out/bin/ora lex contract.ora
+# Compile to EVM bytecode (default)
+./zig-out/bin/ora contract.ora
 
-# Parse and show AST
-./zig-out/bin/ora parse contract.ora
+# Compilation stages
+./zig-out/bin/ora --emit-tokens contract.ora    # Stop after lexing
+./zig-out/bin/ora --emit-ast contract.ora       # Stop after parsing
+./zig-out/bin/ora --emit-mlir contract.ora      # Stop after MLIR generation
+./zig-out/bin/ora --emit-yul contract.ora       # Stop after Yul lowering
 
-# Generate AST JSON
-./zig-out/bin/ora -o build ast contract.ora
+# Optimization levels
+./zig-out/bin/ora -O0 contract.ora              # No optimization
+./zig-out/bin/ora -O1 contract.ora              # Basic optimizations
+./zig-out/bin/ora -O2 contract.ora              # Aggressive optimizations
 
-# Compile (when Yul backend is complete)
-./zig-out/bin/ora compile contract.ora
+# Code analysis
+./zig-out/bin/ora --analyze-complexity contract.ora  # Analyze function complexity
+
+# Output control
+./zig-out/bin/ora -o build/ contract.ora        # Output to directory
+./zig-out/bin/ora --save-all contract.ora       # Save all intermediate stages
+
+# Examples
+./zig-out/bin/ora ora-example/smoke.ora                           # Compile example
+./zig-out/bin/ora --analyze-complexity ora-example/complexity_example.ora  # Analyze complexity
+
+# Showcase: Analyze a realistic DeFi contract (400+ lines)
+./zig-out/bin/ora --analyze-complexity ora-example/defi_lending_pool.ora
+```
+
+Run `./zig-out/bin/ora --help` for complete options.
+
+### 🎯 Complexity Analysis Showcase
+
+Want to see the power of Ora's analysis tools? Try analyzing our realistic DeFi lending pool contract:
+
+```bash
+./zig-out/bin/ora --analyze-complexity ora-example/defi_lending_pool.ora
 ```
 
-See [website/docs/specifications/api.md](website/docs/specifications/api.md) for complete CLI reference.
+This 400+ line contract demonstrates:
+- **15 functions** with varying complexity levels
+- **73% simple functions** - optimal for performance
+- **26% moderate functions** - well-structured business logic
+- Real-world DeFi patterns: lending, borrowing, liquidations, interest calculations
+
+The analysis helps you:
+- ✓ Identify functions suitable for `inline` optimization
+- ○ Ensure moderate complexity stays maintainable  
+- ✗ Catch overly complex functions before they become technical debt
 
 ## Roadmap to ASUKA Release
 

ora-example/README.md

@@ -48,6 +48,33 @@ The following examples use syntax not yet fully implemented:
 - `storage/storage_test_3.ora` - Complex storage operations
 - `max_features.ora` - Comprehensive feature showcase (various advanced features)
 
+## 🔍 Analysis & Development Tools
+
+### Complexity Analysis Examples
+
+- `complexity_example.ora` - Simple example demonstrating different function complexity levels
+  ```bash
+  ./zig-out/bin/ora --analyze-complexity ora-example/complexity_example.ora
+  ```
+
+- `defi_lending_pool.ora` - **Some what of a realistic DeFi lending pool contract** (700+ lines)
+  - Complete lending/borrowing implementation with enums and switch statements
+  - Interest rate calculations
+  - Health factor monitoring
+  - Liquidation mechanics
+  - 21 functions demonstrating full complexity spectrum:
+    * ✓ 76% Simple functions (perfect for inline)
+    * ○ 19% Moderate functions (well-structured)
+    * ✗ 4% Complex functions (needs refactoring)
+  ```bash
+  ./zig-out/bin/ora --analyze-complexity ora-example/defi_lending_pool.ora
+  ```
+
+  **Complexity Distribution:**
+  - ✓ 11 Simple functions (73%) - Optimal for performance
+  - ○ 4 Moderate functions (26%) - Well-structured business logic
+  - Perfect example of maintainable smart contract design!
+
 ## Testing Examples
 
 To validate all examples:

ora-example/complexity_example.ora

@@ -0,0 +1,57 @@
+contract ComplexityTest {
+    storage var balance: u256;
+
+    // Simple function
+    pub fn simple_add(a: u256, b: u256) -> u256
+        requires(a < u128_MAX)
+        requires(b < u128_MAX)
+    {
+        return a + b;
+    }
+
+    // Moderate function
+    pub fn moderate_transfer(recipient: address, amount: u256) -> bool
+        requires(balance >= amount)
+        requires(recipient != std.constants.ZERO_ADDRESS)
+    {
+        if (amount == 0) {
+            return false;
+        }
+
+        balance -= amount;
+        log Transfer(std.transaction.sender, recipient, amount);
+        return true;
+    }
+
+    // Complex function with nested blocks
+    inline fn complex_process(data: u256) -> u256 {
+        var result: u256 = 0;
+
+        if (data > 100) {
+            if (data > 1000) {
+                result = data * 2;
+            } else {
+                result = data + 100;
+            }
+        } else {
+            if (data > 10) {
+                result = data / 2;
+            } else {
+                result = data + 1;
+            }
+        }
+
+        var i: u256 = 0;
+        while (i < 10) {
+            if (result > 50) {
+                result -= 1;
+            } else {
+                result += 1;
+            }
+            i += 1;
+        }
+
+        return result;
+    }
+}
+