Project Structure

The Turf compiler is written in C++20 and uses LLVM 22 as its backend, with llama.cpp vendored as a submodule for the --smart diagnostics pipeline.

Root directory

• include/ — header files for the compiler.
• src/ — source files for the compiler implementation.
• lib/std/ — the standard library, written entirely in Turf (.tr files).
• tests/ — the regression test suite, organized by feature area.
• scripts/ — build, run, and test-runner utilities.
• showcase/ — larger, real-world-shaped example programs.
• docs/ — the language reference, architecture docs, and planning documents this site is generated from.
• grammars/ — the GBNF grammar(s) constraining SLM output for --smart.
• models/ — the quantized local model(s) --smart loads via llama.cpp.
• external/llama.cpp — the vendored llama.cpp submodule.

Header files (include/)

The compiler is split across many small, single-responsibility headers rather than a few large ones. Notable groupings:

• Frontend: Lexer.h, Parser.h — tokenizing and recursive-descent parsing.
• AST: AST.h, ASTDecl.h, ASTExpr.h, ASTStmt.h, ASTAccess.h, ASTVisitor.h, ASTPrinter.h, ASTDiff.h — the node hierarchy and its printer/diff/visitor infrastructure.
• Semantic analysis: Resolver.h plus its supporting tables (ResolverScopeTable.h, ResolverSymbolTable.h, ResolverModuleTable.h, ResolverTypeRegistry.h, ResolverSymbolBase.h), and TypeChecker.h.
• Types & symbols: Types.h, SymbolTable.h.
• Codegen: Codegen.h.
• Static analysis: CFG.h (control-flow graph construction), Analysis.h, AliasAnalysis.h, ValueRange.h, CallGraph.h, Lint.h.
• Diagnostics: Errors.h plus category-specific headers (ErrorsArray.h, ErrorsFlow.h, ErrorsLex.h, ErrorsMemory.h, ErrorsModule.h, ErrorsScope.h, ErrorsStruct.h, ErrorsType.h), ErrorCategory.h, ErrorCodes.h, SuggestionIndex.h (“did you mean?” matching), Colors.h (terminal color codes).
• --smart pipeline: SLMEngine.h (the llama.cpp binding), SLMIntegration.h (wiring the pipeline into the diagnostic flow), Sandbox.h (speculative re-parse/re-validate of a suggested fix), CompileBuffer.h.
• Misc: Algorithms.h (Damerau-Levenshtein and friends).

Source files (src/)

Mirrors the header split, with large subsystems further divided by concern rather than kept in one file:

• main.cpp — entry point and CLI argument handling.
• Lexer.cpp, ParserCore.cpp / ParserDecl.cpp / ParserStmt.cpp / ParserLiteral.cpp / ParserModule.cpp (+ ParserInternal.h) — frontend.
• ResolverCore.cpp / ResolverDecl.cpp / ResolverStmt.cpp / ResolverExpr.cpp / ResolverCall.cpp / ResolverModuleTable.cpp / ResolverScopeTable.cpp / ResolverSymbolTable.cpp / ResolverTypeRegistry.cpp (+ ResolverInternal.h) — the Resolver pass.
• TypeCheckerCore.cpp / TypeCheckerDecl.cpp / TypeCheckerStmt.cpp / TypeCheckerExpr.cpp / TypeCheckerCall.cpp (+ TypeCheckerInternal.h) — the TypeChecker pass.
• CodegenCore.cpp / CodegenFunc.cpp / CodegenVar.cpp / CodegenExpr.cpp / CodegenControlFlow.cpp / CodegenArray.cpp / CodegenStruct.cpp (+ CodegenInternal.h) — LLVM IR generation.
• CFG.cpp, Analysis.cpp, AliasAnalysis.cpp, ValueRange.cpp, CallGraph.cpp, Lint.cpp — the compile-time static-analysis passes described in Tooling.
• SLMEngine.cpp, SLMIntegration.cpp, Sandbox.cpp, CompileBuffer.cpp — the --smart pipeline (see SLM Integration).
• SymbolTable.cpp, Types.cpp, Algorithms.cpp, Builtins.cpp — shared infrastructure.

Standard library (lib/std/)

One directory per module family, each an ordinary .tr source tree with no compiler special-casing: core/ (prelude — int/double/bool/char/strings/array), collections/ (List/Stack/Queue/Map/Set), io/, mem/, math/, time/, random/, fs/, http/, json/, os/, testing/. See Standard Library for the full per-module breakdown.

Docs (docs/)

• docs/reference/ — the language reference this site’s Language Tour and Standard Library pages are grounded in, one topic per page, plus stdlib/ for per-module function references.
• docs/architecture/ — deep internals references: the module/:: system, pointers/unsafe/&T, error handling/recover, the memory model, and the full compiler pipeline.
• docs/errors/codes/ — the per-error-code explanation text turf --explain reads from.
• docs/slm/ — prompt-construction reference material for the --smart pipeline.
• docs/planning/ — ROADMAP_v1.0.0_COMPLETE.md (the completed v1.0.0 tracker), FUTURE.md (what’s next), LIMITATIONS.md (confirmed open generics gaps), DESIGN_NOTES.md (long-form design rationale).

Tests (tests/)

Organized by compiler stage and feature area (01_syntax, 02_resolver, 03_typechecker, 04_control_flow, 05_arrays_pointers_ffi, and onward through the full feature set — structs, enums, generics, error handling, state machines, stdlib modules). scripts/test_runner.sh runs the full suite from the repo root.

Scripts (scripts/)

• cmake_build.sh — builds the turf compiler from source (detects CPU cores, builds llama.cpp on first run if needed).
• compile_and_run.sh — compiles a .tr file, runs it, and cleans up the produced binary.
• test_runner.sh — runs the regression test suite.
• test_ai.sh — exercises the --smart pipeline specifically.