Kai Compiler (Self-Hosted Version)

Welcome to the clean, self-hosted version of the Kai systems programming language compiler!

---

This repository has been fully transitioned from the original Python bootstrap compiler. All compiler development, standard library modules, and feature enhancements are now written entirely in Kai and compiled by Kai itself.

---

1. Project Structure

The project has been restructured into clean subdirectories under src/:

• src/: The self-hosted compiler source code:
  • compiler.kai: Main compiler driver and command-line entrypoint.
  • compiler/: The frontend compilation phases:
    • lexer.kai: Converts source to token streams.
    • parser.kai: Parses tokens into expression and statement AST nodes.
    • ast_nodes.kai: Nodes defining the structure of AST.
    • token_defs.kai: Lexer token kinds and value structures.
    • types.kai: Language types and target type representation.
    • type_checker.kai: Resolves types, tracks mutability/moves, checks imports.
    • symbol_table.kai: Manages nested scopes and variable declarations.
    • imports.kai: Resolves imported modules from the local and std paths.
    • error_registry.kai: Error definitions and descriptive auto-fixes.
  • codegen/: The backend code emitters:
    • c_legacy.kai: Direct-emit transpiler mapping AST directly to raw C text (-c).
    • c_builder.kai: High-fidelity C-AST compiler tree builder (-CC).
    • c_printer.kai: Translates structured C-AST to pretty-printed C text.
    • llvm.kai: Native LLVM backend generating LLVM IR directly (-llvm).
  • tools/: Subcommand modules (init, build, fix, explain, etc.).
• std/: The standard library:
  • std/core/allocator.kai: Allocation routines (KaiAllocator, CAlloc).
  • std/collections/: Core collections (ArrayList, HashMap, StringBuilder).
  • std/io/: Output and file interaction.
• compiler_bootstrap.c: A verified C output of the compiler, used as the zero-dependency bootstrapper.

---

2. CLI Usage & Commands

Run ./CCkai (or the bootstrapped binary) to see all options:

Usage: kai <command> [options]

Commands:
  init [path]     Create a new Kai project
  build [args]    Build the project using build.kai
  check <file>    Type-check only (no code generation)
  run <file>      Compile and run a .kai file
  <file>          Compile and run (shorthand)
  patch <file>    Apply an operation-based edit
  explain <code>  Explain an error code (e.g., E0031)
  skills          List available agent skills
  fix <file>      Auto-fix diagnostics (--plan|--patch|--apply)
  graph <file>    Export or query the AST graph

Flags:
  --json          Output diagnostics in JSON format
  -o <file>       Specify output binary name
  -c              Emit C code only (no linking)
  -CC             Use builder-based C-AST codegen (experimental)
  -llvm           Use LLVM backend (experimental)
  -O0|-O1|-O2|-O3|-Os  Optimization level (default: -O2)

---

3. Language & Compiler Features

• Double-pass Import Resolution: Modules parse into a unified shared pool. Selective symbols are typechecked and validated without index integrity issues.
• Robust Memory Rules: Static validation of mutability, explicit allocators, compilation warnings for use-after-free and double-free scenarios.
• C-AST Builder Codegen (-CC): Rewrites complex patterns (nested try/catch, options, match, loops, slices, string interpolations) into structured, correct C-AST nodes, printing clean, robust C output.
• Direct LLVM IR Gen (-llvm): Targets native binary generation without a C compiler, handling numeric, string, array, struct, flow control, and inline assembly.

---

4. Bootstrapping & Building

Step 1: Compile the Bootstrap Binary

Build from compiler_bootstrap.c:

gcc -O2 compiler_bootstrap.c -o CCkai-bootstrap

Step 2: Compile compiler from source

Compile the compiler source using the bootstrap binary:

./CCkai-bootstrap -c -CC src/compiler.kai && gcc -O2 -o CCkai CCcompiler.c

Step 3: Self-Host Verification

Re-compile the compiler with the newly built compiler to verify complete identity:

./CCkai -c -CC src/compiler.kai && gcc -O2 -o CCkai-self CCcompiler.c
shasum CCcompiler.c

(C outputs of successive self-hosted stages match perfectly)

---

5. Cross-Compilation via Zig

To cross-compile the transpiled C compiler code for Windows or other platforms:

1. Translate C output to Zig (skipping C platform-specific helpers):

   zig translate-c -DNO_GET_EXE_DIR compiler.c > compiler.zig

2. Append the Windows compatibility imports:

   echo 'comptime { _ = @import("windows_compat.zig"); }' >> compiler.zig

3. Cross-compile:

   zig build-exe compiler.zig -target aarch64-windows-gnu -lc -femit-bin=compiler.exe
   zig build-exe compiler.zig -target x86_64-windows-gnu -lc -femit-bin=compiler.exe