libeulix Public API
This page lists the functions and types that libeulix exposes, shows how they fit together, and gives runnable examples.
Crate / path:
libeulix/src/
Language: Rust
Status: stable
Last verified against:923a577
Overview
Everything in libeulix is a plain function that takes its input by reference and returns owned data. There is no engine object to create, no global state, and no async runtime to set up. That makes the library easy to embed: you call a function, you get a value back.
The public surface is split across four modules. grammar_files parses files, analyze computes relationships, struc holds the data types, and utils offers a file walker and a parse-error checker. This page walks through them in the order you will usually need them.
A note on older docs. The previous
libeulix/README.mdlists a few names that do not exist in the code, such asgrammar_files::parse_file,entry_points::find,dependencies::analyze,indices::generate,summary::generateandmetrics::generate. The names below are the real ones, taken from the source.
Why It Exists
A small, predictable API is what lets four different tools share one engine. Because the functions are pure (same input, same output, no side effects), the parser binary can run them in parallel, the language server can run them on a single edited file, and tests can call them directly with hand-built data.
How It Works
A typical program uses the API in three steps: parse, collect, analyze. Parsing is done per file, so you can run it on as many threads as you like. Collecting just means putting each FileData into a map keyed by relative path. Analysis then takes that map, or a full KnowledgeBase, and adds relationships to it.
Main Components
| Function | Module | What it does |
|---|---|---|
parse_source(path, src) |
grammar_files |
Parses one in-memory source file into a FileData. Returns Result<(String, FileData), String>, where the string is the file’s relative path. |
Language::detect(path) |
grammar_files::language |
Maps a path to a Language, using the extension first and then well-known file names. No file is read. |
Language::extensions() |
grammar_files::language |
Lists the extensions registered for a language. |
analyze_and_build(kb, verbose, prism) |
analyze::pipeline |
Runs every pass in one call. Deprecated since 0.9.0 and scheduled for removal in 1.0.0. |
prism_v1::resolve_call_locations(&mut kb) |
analyze::call_graph |
v1 pre-pass. Rewrites each call’s callee to a definition id. Must run before build_call_graph. |
prism_v1::build_call_graph(&structure) |
analyze::call_graph |
Builds the v1 call graph. |
prism_v1::populate_called_by(&mut kb) |
analyze::call_graph |
Fills each function’s called_by list for v1. |
prism_v2::build_call_graph_v2(&structure) |
analyze::call_graph |
Builds the v2 call graph with default options. |
prism_v2::build_with(&structure, &opts) |
analyze::call_graph |
Builds the v2 call graph with your own CallGraphOptions. |
prism_v2::populate_called_by_from_graph(&mut kb) |
analyze::call_graph |
Fills each function’s called_by list from a finished call graph. |
find_entry_points(&kb) |
analyze::entry_points |
Finds main-style functions, HTTP routes and CLI commands. |
analyze_external_deps(&kb) |
analyze::dependencies |
Lists third-party and standard-library imports with usage counts. |
detect_patterns(&kb) |
analyze::patterns |
Guesses naming convention, project layout and architecture style. |
generate_indices_view(&kb) |
analyze::indices |
Builds borrowed lookup indices (by name, by tag, by category, callers). |
generate_metrics(&kb, k) |
analyze::metrics |
Returns the top k functions ranked by complexity. |
generate_summary(&kb) |
analyze::summary |
Builds a ProjectSummary of the whole project. |
FileWalker |
utils::file_walker |
Walks a directory honouring .euignore, and can compute a project hash. |
syntax::inspect(&tree) |
utils::syntax |
Counts Tree-sitter ERROR and MISSING nodes in a parsed tree. |
The input to the call-graph functions is &BTreeMap<String, FileData>, which is the type of KnowledgeBase::structure. Both PRISM builders take that map, not a whole knowledge base.
Data In, Data Out
parse_source returns a String error, not a typed error. The most common reasons are an unsupported language ("Unsupported language: ...") and, for .inc files, a missing PHP opening tag ("not PHP: a .inc file without a PHP opening tag").
The call-graph builders return a CallGraph with nodes and edges. Nodes carry an id, a type (function, method or class), the file, an entry-point flag and a call-count estimate. Edges carry the caller id, the callee id, an edge_type (call or inheritance), a conditional flag and the line of the call site. See Knowledge Base Schema.
Key Algorithms
Choosing a language
The problem. A file name is the only hint about the language, but .h could be C or C++, and .inc could be PHP, C or assembler.
The approach. A single table maps extensions and a few special file names to a Language. The lookup tries the exact extension first, then a lowercase version, then the file name. .h maps to C. For two extensions parse_source then looks at the text: a .h file with C++-only syntax outside comments and strings (a class with a body or base list, a namespace, a template, an access specifier, the :: scope operator) goes to the C++ parser, and an .inc file is accepted as PHP only if it contains a PHP opening tag.
Why this way. Keeping one table as the single source of truth means the detector and Language::extensions() can never disagree.
Walking a project and hashing it
The problem. Callers need a list of source files that respects ignore rules, and a cheap way to tell whether a project has changed since the last run.
The approach. FileWalker uses the ignore crate, reads .euignore files (or a path set with with_euignore) and deliberately turns off .gitignore handling. The project hash is built from each file’s relative path, size and modification time, sorted by path, so it changes when files are added, removed or touched, without ever reading file contents.
Why this way. Hashing metadata instead of contents keeps change detection fast on very large repositories.
Configuration
| Setting | Where | Default | What it does and when to change it |
|---|---|---|---|
FileWalker::with_threads(n) |
builder method | available parallelism, or 4 | Sets how many threads the walk uses. |
FileWalker::with_euignore(path) |
builder method | <root>/.euignore |
Adds an extra ignore file on top of the per-directory .euignore files. |
CallGraphOptions |
struct | see Overview | Controls PRISM v2 strictness. |
Usage Examples
Parse many files and build a call graph
use std::collections::BTreeMap;
use std::path::PathBuf;
use libeulix::analyze::call_graph::prism_v2::{self, CallGraphOptions};
use libeulix::grammar_files;
use libeulix::struc::kb_struct::FileData;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let files: Vec<PathBuf> = vec!["src/lib.rs".into(), "src/main.rs".into()];
let mut structure: BTreeMap<String, FileData> = BTreeMap::new();
for path in &files {
let src = std::fs::read_to_string(path)?;
let (rel, data) = grammar_files::parse_source(path, &src)?;
structure.insert(rel, data);
}
let graph = prism_v2::build_with(&structure, &CallGraphOptions::default());
println!("{} nodes, {} edges", graph.nodes.len(), graph.edges.len());
Ok(())
}
Expected result: a single line with the node and edge counts. Note that the map must be a BTreeMap, not a HashMap, because that is what the schema and both builders use.
Use PRISM v1 correctly
use libeulix::analyze::call_graph::prism_v1;
// `kb` is a KnowledgeBase whose `structure` is already filled in.
prism_v1::resolve_call_locations(&mut kb); // 1. must come first
kb.call_graph = prism_v1::build_call_graph(&kb.structure); // 2. build
prism_v1::populate_called_by(&mut kb); // 3. reverse edges
The order matters. Without the first step, v1 cannot resolve bare call names, as explained in PRISM v1.
Run the remaining passes by hand
Because analyze_and_build is deprecated, new code should call the passes directly:
use libeulix::analyze::{dependencies, entry_points, patterns};
kb.patterns = patterns::detect_patterns(&kb);
kb.entry_points = entry_points::find_entry_points(&kb);
kb.external_dependencies = dependencies::analyze_external_deps(&kb);
Limitations
| Limitation | Why it happens | Workaround |
|---|---|---|
| The library is not completely free of side effects. | FileWalker::walk_and_project_hash writes a checksum file to the directory you pass in. |
Use walk_paths or project_hash if you want no writes. |
analyze_and_build prints to stdout when verbose is true. |
It uses println! directly. |
Pass false, or call the passes yourself. |
analyze_and_build skips the call graph above 100,000 files. |
A memory guard. | Call the PRISM builders directly. |
Two PRISM runs leave kb.structure in different states. |
v1’s pre-pass rewrites each call’s callee; v2 does not. |
Decide on one version before reading calls. |
Related Docs
- Overview: how the pieces fit together.
- Knowledge Base Schema: the types these functions return.
- Analysis Passes: what each
analyzefunction computes.