Plan 03: Lexical Scope Tree & Symbol Object Model

Goal: Unify disjoint symbol tables into a polymorphic Symbol hierarchy, implement a first-class lexical Scope tree, and manage checking state via an RAII EnvironmentGuard. Inspiration: Go's go/types/object.go, go/types/scope.go, and go/types/check.go.

1. Problem Statement & Root Cause

Currently in compiler/kyna_typecheck/include/kyna/semantics/program_analyzer.hpp:

1. Symbols Bypassing Scope: Top-level symbols live in disconnected global maps:
   cpp

   cppCopy

   1std::map<std::string, FunctionDecl> functions;
   2std::map<std::string, ClassDecl> classes;
   3InterfaceCatalog interfaces;

   Functions and classes declared in nested blocks cannot be properly resolved or tracked.
2. Primitive Local Scope: Scope only maps names to TypeRef and bool:
   cpp

   cppCopy

   1struct Scope {
   2  std::map<std::string, TypeRef> types;
   3  std::map<std::string, bool> mutability;
   4  Scope* parent = nullptr;
   5};

   It has no child links, source spans, or symbol kind tags.
3. Fragile Mutable State Machine in Analyzer:
   cpp

   cppCopy

   1std::string currentClass;
   2TypeRef currentReturn;
   3bool inFunction = false;
   4std::vector<std::string> activeLoopLabels;
   5int switchDepth = 0;

   These fields are manually overwritten when checking nested classes/functions. If analysis encounters an error, state is corrupted.

2. Target Architecture

2.1 The Symbol (Object) Hierarchy

1namespace kyna::semantics {
2 
3enum class SymbolKind : uint8_t {
4  Variable,
5  Constant,
6  Function,
7  Class,
8  Interface,
9  Package,
10  TypeParam
11};
12 
13class Scope;
14 
15class Symbol {
16public:
17  virtual ~Symbol() = default;
18  virtual SymbolKind kind() const = 0;
19  virtual const std::string& name() const = 0;
20  virtual types::TypePtr type() const = 0;
21  virtual SourceLocation location() const = 0;
22  virtual Scope* parentScope() const = 0;
23  virtual bool isExported() const = 0;
24};
25 
26using SymbolPtr = std::shared_ptr<Symbol>;
27 
28class VarSymbol : public Symbol { /* ... */ };
29class FuncSymbol : public Symbol { /* ... */ };
30class ClassSymbol : public Symbol { /* ... */ };
31class InterfaceSymbol : public Symbol { /* ... */ };
32 
33} // namespace kyna::semantics

2.2 The Lexical Scope Tree

1class Scope {
2private:
3  Scope* parent_{nullptr};
4  std::vector<std::unique_ptr<Scope>> children_;
5  std::unordered_map<std::string, SymbolPtr> symbols_;
6  SourceSpan extent_;
7 
8public:
9  explicit Scope(Scope* parent = nullptr) : parent_(parent) {}
10 
11  Scope* parent() const { return parent_; }
12  Scope* createChild(SourceSpan extent = {});
13 
14  // Returns existing conflicting symbol if already defined in THIS scope
15  SymbolPtr insert(SymbolPtr symbol);
16 
17  // Looks up identifier, searching up the parent chain
18  SymbolPtr lookup(const std::string& name) const;
19 
20  // Looks up only in the immediate scope
21  SymbolPtr lookupLocal(const std::string& name) const;
22};

2.3 RAII EnvironmentGuard

1struct Environment {
2  SymbolPtr currentFunc{nullptr};
3  SymbolPtr currentClass{nullptr};
4  types::TypePtr expectedReturn{nullptr};
5  uint32_t loopDepth{0};
6  uint32_t switchDepth{0};
7  bool allowBreak{false};
8  bool allowContinue{false};
9};
10 
11class EnvironmentGuard {
12private:
13  Analyzer& analyzer_;
14  Environment previous_;
15 
16public:
17  EnvironmentGuard(Analyzer& analyzer, Environment newEnv)
18    : analyzer_(analyzer), previous_(analyzer.env_) {
19    analyzer_.env_ = std::move(newEnv);
20  }
21 
22  ~EnvironmentGuard() {
23    analyzer_.env_ = std::move(previous_);
24  }
25};

3. Implementation Steps

• Step 1: Create compiler/kyna_typecheck/include/kyna/semantics/symbol.hpp
  • Implement Symbol base interface and concrete VarSymbol, FuncSymbol, ClassSymbol.
• Step 2: Upgrade Scope in compiler/kyna_typecheck/include/kyna/semantics/scope.hpp
  • Implement Scope::insert(symbol) with duplicate detection.
  • Implement parent-walking Scope::lookup(name).
• Step 3: Implement EnvironmentGuard
  • Encapsulate mutable analyzer fields in Environment.
  • Guard all function, method, and loop checks with RAII guards.
• Step 4: Three-Color Cycle Detection for Declarations
  • Track Checker.declPath stack: mark White (unresolved), Grey (resolving), Black (resolved).
  • Detect circular class inheritance or type alias loops cleanly.

4. Verification Plan

1. Unit Tests:
   • Write tests for lexical scope shadowing, duplicate declaration diagnostics, and inheritance cycle detection.
2. Automated Verification:
   • Run ctest --test-dir build-debug -R semantic.
   • Run python3 build_tools/verify_repository_architecture.py.