peeperlanguage/compiler

Purpose and Entry Points

Peeper is a Go-implemented compiler toolchain for the Peeper programming language, with package/project management and Language Server Protocol support. The primary executable starts at cmd/main.go; command dispatch and compiler-facing commands are in cmd/dispatch.go, cmd/build.go, and cmd/command.go. The compiler façade is internal/driver/compiler.go.

CLI, Projects, and Dependencies

The CLI handles build plus project lifecycle and dependency operations (init, get, update, remove, scanning/listing orphaned dependencies). Project manifests and lockfiles are modeled in pkg/manifest/manifest.go and pkg/manifest/lockfile.go. Dependency resolution/download boundaries are represented by pkg/remotes/remotes.go, pkg/registry/download.go, and pkg/registry/cache.go.

Project loading establishes module/import context before compilation: internal/project/context.go, internal/project/modules.go, and internal/project/imports.go. This layer separates filesystem/project topology from language analysis.

Frontend: Source to AST

Compilation begins by loading source files through the pipeline, lexing Peeper syntax, and parsing surface declarations/expressions into the AST. Core stages are internal/pipeline/loader.go, internal/frontend/lexer/lexer.go, and internal/frontend/parser/parser.go. The shared syntax model—including declarations, expressions, statements, metadata, and source locations—is in internal/frontend/ast/decl.go, internal/frontend/ast/expr.go, and internal/frontend/ast/stmt.go.

Semantic Analysis and Safety

Semantic passes build symbol/scope information, resolve names/types, validate control flow, and enforce Peeper’s ownership/reference rules. Key boundaries are collection/binding (internal/semantics/collector/collector.go, internal/semantics/binder/binder.go), resolution and typing (internal/semantics/resolver/resolver.go, internal/semantics/typechecker/typechecker.go), and ownership/place analysis (internal/semantics/ownership/ownership.go, internal/semantics/place/origin.go). CFG analysis supports flow-sensitive validation in internal/semantics/cfg/build.go and internal/semantics/cfg/analyze.go.

Diagnostics are accumulated and rendered independently of the compiler stages via internal/diagnostics/bag.go, internal/diagnostics/diagnostic.go, and internal/diagnostics/emitter.go.

IR Lowering and Code Generation

Validated AST is lowered through explicit intermediate representations: high-level IR in internal/ir/hir/model.go, HIR lowering in internal/ir/hir_lower/lower.go, then machine-oriented IR in internal/ir/mir/model.go and internal/ir/mir/lower.go. Constant folding spans this boundary in internal/ir/constfold.go.

The backend abstraction is internal/backend/backend.go; its concrete LLVM implementation lowers IR, types, calls, drops, and modules through internal/backend/llvm/lower_llvm.go, internal/backend/llvm/type_lowering.go, and internal/backend/llvm/module_emit.go. LLVM and target triples are material external/runtime dependencies, represented by internal/target/llvm_triple.go.

Runtime and Built-ins

Language-provided core functionality is compiled from Peeper source under _builtin_library/core/src, notably allocation and globals in _builtin_library/core/src/allocator.peep and _builtin_library/core/src/global.peep. Prelude integration is centralized in internal/prelude/prelude.go. This forms the boundary between user projects and compiler-supplied runtime/library code.

Language Server

The LSP server shares compiler/project concepts while maintaining workspace state for editor requests. Its JSON-RPC server boundary is internal/lsp/server.go and internal/lsp/jsonrpc.go; incremental document/workspace state lives in internal/lsp/state.go and internal/lsp/workspace.go. Editor features such as completion, hover, and navigation are implemented in internal/lsp/completion.go, internal/lsp/hover.go, and internal/lsp/navigation.go.