Module const_eval 

Const evaluation for annotation metadata() handlers

This module provides compile-time evaluation of Shape expressions. Only a subset of expressions are allowed (literals, object/array construction, annotation parameters, and const arithmetic).

Purpose

Const evaluation enables:

• LSP to extract metadata without runtime execution - Show code lenses, hover info
• Compiler optimizations based on static metadata (pure functions, cacheable results)
• Static analysis and documentation generation

How It Works

When the LSP encounters an annotation ... { ... } definition, it:

1. Parses the annotation definition (from current file or imports)
2. Finds the metadata() handler in the handlers list
3. Const-evaluates the handler body using this module
4. Extracts special properties from the result:
   • code_lens: [...] → Creates IDE action buttons
   • pure: true → Marks for compiler optimization
   • Custom properties → Stored for user’s own tooling

Example:

annotation strategy() {
    metadata() {
        {
            is_strategy: true,              // Custom metadata
            code_lens: [                    // Special: IDE integration
                { title: "▶ Run", command: "shape.runBacktest" }
            ]
        }
    }
}

When a function has @strategy, the LSP:

1. Looks up the @strategy annotation definition
2. Const-evaluates metadata() → { is_strategy: true, code_lens: [...] }
3. Creates a “▶ Run” button above the function

Allowed Constructs

• Literals: 42, "hello", true, null
• Objects: { key: value, ... }
• Arrays: [1, 2, 3]
• Annotation parameters (captured in scope)
• Const arithmetic: 2 + 2, "a" + "b"

Not Allowed

• Function calls (runtime dependency)
• Variable references (except annotation parameters)
• ctx or fn access (runtime state)
• Side effects
• Non-const conditionals

Structs

ConstEvaluator

Const evaluator for metadata() handlers