Reflection & Compile-Time Introspection Roadmap

A structured, compile-time reflection system for Cyrus to enable safe metaprogramming, code generation, type-driven diagnostics, and optional runtime metadata emission.

Goals

• Zero-cost unless explicitly used.
• Reflection available at compile-time as first-class values.
• Enable features like tuple validation, struct method resolution, automatic codegen (toString, serialization, etc.), and future tooling support.
• Runtime metadata generation should remain opt-in.

Phase Roadmap

Phase 1 — Core Type Introspection

• typeof(expr) / typeOf(expr) → returns type symbol at compile-time.
• typeName(T) → returns string name of type.
• Define internal TypeInfo enum in compiler.
• Add getTypeInfo(T) -> TypeInfo.
• Support basic kind checking: if comptime getTypeInfo(T).kind == STRUCT.

Enables: tuple validation, basic diagnostic improvements.

---

Phase 2 — Struct and Enum Metadata

• Expose .fields[] for struct types → { name, type, index, mutability }.

• Expose enum variant metadata → { name, tag/value }.

• Add:

  • hasField(T, "name")
  • hasMember(T, "name")
  • fieldAccess(value, "name") at comptime.

• Allow comptime for iteration over fields.

• Optional: attach visibility flags.

Enables: deriving toString, tuple export validation via reflection API instead of ad-hoc checks.

---

Phase 3 — Declaration-Level Reflection

• Introduce declsOf(ModuleOrStruct) → iterate top-level/public declarations.
• getDecl(container, "Symbol")
• Make reflection-powered method lookup possible for codegen and IDE support.

Enables: better tooling, semantic import suggestions, LSP integration hooks.

---

Phase 4 — Function Signature Introspection

• functionInfo(fn) → returns metadata: { params[], returnType, flags (extern/async/variadic) }.

Enables: auto-generating FFI wrappers, RPC bindings, DSL backends.

---

Phase 5 — Derive Hooks / Custom Codegen

• Introduce syntax-level hooks:

  • @derive(Debug) or derive Debug for StructName.
  • Compiler calls user-defined meta functions with TypeInfo(T) context.

• Acts as macro system without macros—pure reflection-driven codegen.

Enables: painless generation of Clone, Hash, Debug, user-defined traits.

---

Phase 6 — Optional Runtime Reflection Layer

• emitRuntimeTypeInfo(T) → compiler emits .rodata block with serialized TypeInfo.
• Only generated when explicitly requested.

Enables: REPL, scripting, runtime inspectors, CLI type explorers.

---

Compiler Action Items

• Implement internal TypeInfo enum structure.
• Expose basic getTypeInfo(T) + typeName builtins.
• Connect tuple export/type validation to reflection (eat own API).
• Implement struct fields reflection + hasField + fieldAccess.
• Expand TypeInfo with enum + function metadata.
• Design syntax for derive / reflection hooks.
• (Optional) Implement runtime metadata emission backend.