syn-sem

An experimental semantic analyzer for a subset of Rust.

syn-sem builds on the syn crate to perform deep semantic analysis of Rust source code, including type inference, constant evaluation, trait resolution, and monomorphization of generic code.

Status

This is an early-stage experimental library (0.0.1). The API is unstable and subject to significant change.

Features

• Path tree construction — builds a hierarchical namespace tree representing the full module structure of a crate
• Type inference — infers types of expressions across items
• Constant evaluation — evaluates compile-time constants and const generics
• Trait resolution — resolves trait implementations using logic-based reasoning
• Monomorphization — instantiates generic code with concrete type arguments
• Module resolution — resolves mod and use statements across files
• Virtual files — analyze in-memory source code without writing to disk

Supported Rust Subset

Items

• Modules (mod, inline and file-based)
• Functions (fn) with generics and trait bounds
• Structs with fields and generics
• Traits with associated types and const generics
• Type aliases
• Constants and associated constants
• Enums with variants
• use statements
• impl blocks (with monomorphization support)

Types

• Scalar primitives
• Named path types
• Tuples
• Arrays (fixed and generic length)
• References (&T, &mut T)
• Unit type ()

Usage

Add syn-sem to your Cargo.toml:

[dependencies]
syn-sem = "0.0.1"

Analyzing physical files

Physical-file analysis reads .rs files from disk starting at an entry path relative to the current working directory. All mod declarations are followed automatically and their corresponding files are loaded.

use syn_sem::{pitem, AnalysisSession};

// "src/lib.rs" is resolved relative to the current working directory.
// The crate name is derived from the entry file name:
// e.g. "src/lib.rs" → "lib", "src/main.rs" → "main".
let analyzed = AnalysisSession::default()
    .run(|analyzer| analyzer.analyze("src/lib.rs"))
    .unwrap();

let ptree = &analyzed.sem.ptree;
let crate_name = ptree.crate_name();

// Items are looked up by their fully-qualified path.
let item = pitem!(ptree, "{crate_name}::my_module::MyStruct");
let _struct_item = item.as_struct().unwrap();

Analyzing virtual (in-memory) files

Virtual files let you analyze Rust code without writing to disk. Pass source code as strings — the registered paths must match how the entry module resolves mod declarations (e.g. mod utils in "lib.rs" resolves to "utils.rs").

use syn_sem::{pitem, AnalysisSession};

let analyzed = AnalysisSession::default()
    .run(|mut analyzer| {
        // Entry module declares a submodule.
        analyzer.add_virtual_file("lib.rs", "pub mod utils;");

        // Submodule file — path matches the `mod utils` declaration in lib.rs.
        analyzer.add_virtual_file("utils.rs", "
            pub struct Config {
                pub value: u32,
            }

            pub fn default_config() -> Config {
                Config { value: 42 }
            }
        ");

        analyzer.analyze("lib.rs")
    })
    .unwrap();

let ptree = &analyzed.sem.ptree;
let crate_name = ptree.crate_name();

// Struct item
let item = pitem!(ptree, "{crate_name}::utils::Config");
assert!(item.as_struct().is_some());

// Function item
let item = pitem!(ptree, "{crate_name}::utils::default_config");
assert!(item.as_fn().is_some());

API Overview

Entry point

Type	Description
AnalysisSession	Configures and runs semantic analysis
Analyzer	Builder passed to the session closure; use it to register files and trigger analysis
Semantics	Analysis results
Config / ConfigLoad	Controls which standard libraries are loaded (core, std)

Analysis results

Field	Type	Description
sem.ptree	PathTree	Hierarchical namespace tree of all items
sem.stree	SyntaxTree	Original parsed syntax tree
sem.evaluated	Evaluated	Evaluated compile-time constants
sem.logic	Logic	Trait resolution logic engine

Path tree macros

Macro	Description
pitem!(ptree, path)	Look up an item by path, panic if not found
pid!(ptree, path)	Get the PathId for a path
pnode!(ptree, path)	Get the NodeIndex for a path

Item types (syn_sem::item)

Block, Const, Field, Fn, Local, Mod, Param, Struct, Trait, TypeAlias, Use

Value types (syn_sem::value)

ConstGeneric, Enum, Field, Fn, Scalar, Value

Type system

Type	Description
Type	Enum of all type forms
TypeScalar	Scalar primitive types
TypePath	Named path types
TypeArray	Array types with ArrayLen (fixed or generic)
TypeRef / TypeMut	Reference types
TypeTuple	Tuple types
TypeId	Unique identifier for a type

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.