Module compiler 

Incremental project compiler.

This module is the canonical implementation of project::plan_sync()’s compile contract:

• The result of compilation is a crate::project::ir::graph::Project.
• The unit of incremental reuse is a logical database object (database.schema.object), not an entire project.
• Object-local work is evaluated independently and may run in parallel.
• Cross-object validation remains deterministic and is performed after all object-local results for the invocation are available.

Build Artifacts

Compiler state is scoped to the active configuration (profile name, optional suffix, and compile-time variable bindings). Each configuration gets an isolated namespace so caches never leak across profiles.

Within a namespace the compiler persists:

• file metadata and content hashes to avoid rereading unchanged files
• cached object artifacts for incremental reuse across invocations
• cached runtime typecheck artifacts for incremental dirty detection

All cached state is advisory. Missing, corrupt, or schema-incompatible entries are treated as cache misses and rebuilt from source.

Invalidation Rules

An object cache entry is reusable only when its fingerprint matches the current compile inputs for that object. The fingerprint includes:

• the logical object key
• every file variant that can affect active-variant resolution
• the full path of every file variant
• the cached content hash of those variants
• the compile-time variable map

As a result:

• editing any variant for an object invalidates that object’s cache entry
• changing variables invalidates every object whose fingerprint includes those variables
• changing the active profile or suffix moves compilation to a different namespace, isolating caches across profiles
• moving the same checkout to a different directory invalidates the cache because file paths are part of the fingerprint contract

This module does not currently perform dependency-directed invalidation. Downstream project-graph work is recomputed from the object set produced for the current invocation.

Correctness Guarantees

Cached object artifacts store a validated object payload. A cache hit must therefore produce the same object facts that object-local parsing and validation would produce from source while skipping revalidation.

Compilation must preserve these invariants:

• all object-local validation errors are reported exactly as if the object had been freshly compiled
• database- and schema-level mod statements are validated on every invocation; they are not cached independently
• schema-level checks (e.g., storage/computation separation, replacement schemas) are enforced after object artifacts are assembled, so they see the full current project
• final dependency extraction operates on a complete compiled project assembled for the current invocation

Modules

cache 🔒

SQLite-backed compiler cache shared by the writer and the reader.

cache_io 🔒

mod_statements 🔒

Validation for database and schema mod file statements.

object_validation 🔒

Object validation and compiled-project assembly.

typecheck 🔒

Runtime typechecking integrated with the project compiler.

Structs

CachedTypedObject 🔒

In-memory representation of a compiled object together with its location.

CompileStats 🔒

Counters for cache behavior during a single compilation run.

Discovery 🔒

Output of the discovery phase: everything needed to plan and compile objects.

ObjectDescriptor 🔒

A logical database object discovered on disk, not yet compiled.

VariantDescriptor 🔒

A single file variant contributing to an ObjectDescriptor.

Enums

ObjectCompileFailure 🔒

Internal error type for compile_object_uncached.

ObjectCompileResult 🔒

Result of compiling a single object from source.

ObjectPlanResult 🔒

Result of the planning phase for a single object.

ObjectPlanStage 🔒

Intermediate planner classification before cached SQL fragments are loaded.

Constants

COMPILER_DIR 🔒

Functions

artifact_to_compiled_object 🔒

Reconstruct a CachedTypedObject by re-parsing the cached SQL fragments.

build_cluster_name_map 🔒

Build a map from original cluster name to the suffixed cluster name for all clusters referenced by the compiled project.

compile_object 🔒

Compile a single object and wrap the result for cache persistence.

compile_object_uncached 🔒

Compile a single object from source files without consulting the cache.

compile_sync 🔒

Compile a project directory into a dependency-aware graph::Project.

compile_sync_with_stats 🔒

Internal entry point that returns compile statistics alongside the project.

compiled_object_to_artifact_data 🔒

Convert a freshly compiled object into the SQL-text shape persisted in the cache. Each AST node is rendered with a trailing semicolon so the inverse parse in artifact_to_compiled_object sees a self-contained statement.

discover_project 🔒

Walk the models/ directory tree and collect everything needed for compilation.

expect_comment 🔒

Extract a CommentStatement from a generic Statement, or Err(()).

expect_grant 🔒

Extract a GrantPrivilegesStatement from a generic Statement, or Err(()).

expect_index 🔒

Extract a CreateIndexStatement from a generic Statement, or Err(()).

expect_test 🔒

Extract an ExecuteUnitTestStatement from a generic Statement, or Err(()).

finalize_stage 🔒

Turn a fingerprint-level stage into a final ObjectPlanResult.

object_fingerprint 🔒

Compute a SHA-256 fingerprint for an object’s current compile inputs.

object_key 🔒

Build the canonical cache key for a logical object: "db.schema.object".

parse_main_statement 🔒

Parse a cached main statement SQL string into the project’s Statement enum.

parse_mod_statements 🔒

Parse mod statements from a SQL file, optionally rewriting database names.

parse_one_statement 🔒

Parse a SQL string that must contain exactly one statement.

parse_sql 🔒

Parse a SQL string into a list of raw AST statements.

parse_statement_list 🔒

Parse a list of SQL strings and downcast each to a specific statement type.

profile_namespace 🔒

Compute the cache namespace for a profile configuration.

stage_object 🔒

Classify a single object as a fingerprint-level Hit or Miss against the stored cache, without loading the cached SQL fragments.