Module com.darkcollective.relix.semantic

Package com.darkcollective.relix.semantic.internal

package com.darkcollective.relix.semantic.internal

The engine-side machinery behind com.darkcollective.relix.semantic: not exported by the published artifact. What follows describes the package as a whole, as it stood before the split. Five-phase semantic analysis pipeline for Relix scripts.

Overview

This package transforms a parsed Script AST into a validated SemanticModel that downstream tools (execution engines, optimisers, IDEs) can query. Analysis is orchestrated by SemanticAnalyzer and proceeds in five sequential phases:

1. Import Graph (ImportGraph) — resolves import statements depth-first and detects cycles.
2. Symbol Collection (SymbolCollector) — registers every relation and function declared in all reachable scripts into an InMemorySymbolTable.
3. Schema Inference (SchemaInferenceEngine) — walks each query body and annotates every RelNode with its inferred output Schema.
4. Validation (SemanticValidator) — checks predicate attribute references, rename arity, join conditions, and function existence/arity.
5. Model Assembly — produces a SemanticModel containing the namespace, symbol table, source declarations, schema annotations, and root query statements.

Key classes

SemanticAnalyzer

Entry point; call analyze(Script) to run the full pipeline.

SemanticResult

Returned by SemanticAnalyzer: carries errors and, on success, the SemanticModel.

SchemaAnnotations

Identity-keyed side-map from RelNode to inferred Schema.

FunctionCatalog

The functions a script may call, discovered from the installed libraries. A function enters the symbol table on first reference, so an analysed script carries the functions it calls rather than the whole library.

IrReport

Generates a concise ≤80 char/line IR report from a SemanticModel.

Error reporting

SemanticError carries a file path, line, column, message, and Severity. When AST nodes have been parsed with explicit source coordinates (via SourceLocation), errors are reported at the precise source position rather than the file level.

See Also:

• SemanticAnalyzer
• SemanticResult
• SemanticModel

Related Packages

Package	Description
com.darkcollective.relix.semantic	The result of analysing a script, and the seams analysis reads through.
com.darkcollective.relix.semantic.graph	Join-path resolution over the schema graph.
com.darkcollective.relix.semantic.json	The engine's JSON form of a heading, shared by the logical and physical plan writers.

Class	Description
BuiltinProvider	Hook for registering built-in symbols into the symbol table before any user-defined symbols are processed.
CatalogBuilder	Builds the read-only system catalog relations — the relix.* namespace that lets a script query the engine's own knowledge about itself (the information_schema analogue; see ADR-0007).
ComponentInventory	What is installed in this process, for the parts of it the engine cannot see.
ComponentInventory.Component	One installed thing.
DownsampleColumns	Which columns a DOWNSAMPLE consolidates, and what each one is called.
DownsampleColumns.Consolidation	One consolidated output column, and the input column reduced into it.
GeneratorCatalog	Supplies the schema of a generator source during semantic analysis — the seam through which the analyzer learns a generator's heading without the script declaring it (generator-owned schema).
ImportGraph	Directed dependency graph of all .relix files reachable from a root.
InMemoryScriptLoader	A ScriptLoader that serves pre-parsed Scripts from an in-memory map, keyed by path string.
IrReport	Produces a concise human-readable IR report from a SemanticModel.
LogicalPlanJson	Serializes a logical relational-algebra tree to JSON, annotating every node with its inferred Schema.
PredicateValidator	Validates attribute references and function calls within a predicate tree.
RelAlgebraValidator	Validates structural and semantic constraints over a single relational algebra expression tree.
RelationBoundedness	Answers one question about a named relation: is it finite? — the extent of relix.relations.boundedness.
RelationDeterminism	Answers one question about a relational expression: would evaluating it twice necessarily give the same relation?
ResolvedFunction	What a call site's function name resolved to — the symbols visible to the rest of the pipeline, and the catalogue definition behind them when there is one.
SchemaAnnotationsAccess	How the analyser records a node's schema in a SchemaAnnotations.
SchemaAnnotationsAccess.Writer	Records schema as node's schema in annotations.
SchemaInference	Public facade for running schema inference over an arbitrary RelNode tree outside the full five-phase analysis pipeline.
SchemaInferenceEngine	Orchestrates the schema-inference pass (Phase 4 of semantic analysis).
SchemaInferenceVisitor	Infers the output Schema of every node in a relational algebra tree.
SemanticAnalyzer	Entry point for semantic analysis — the engine's front door.
SemanticResult	The outcome of a semantic analysis run.
SemanticValidator	Orchestrates the validation pass (Phase 5 of semantic analysis).
SymbolCollector	Performs the symbol-collection pass over all files reachable from the root.