icb_rustc/lib.rs
1#![cfg_attr(feature = "nightly", feature(rustc_private))]
2
3//! # ICB Rustc Backend
4//!
5//! This crate provides a precise analysis of Rust source code by leveraging
6//! the `rustc` compiler's internal APIs. Unlike tree‑sitter, which only
7//! performs syntactic parsing, this backend resolves all semantic
8//! information (traits, generics, macro expansions, etc.) and produces a
9//! list of facts suitable for constructing a Code Property Graph.
10//!
11//! # Architecture
12//!
13//! The entry point is [`parse_rust_crate`]. When the `nightly` feature is
14//! enabled it calls into [`driver::run_analysis`] which starts a `rustc`
15//! session, obtains the HIR, and invokes the HIR visitor implemented in
16//! [`visitor`]. The visitor records functions, methods, trait/struct/enum
17//! declarations, impl blocks, and call expressions as [`RawNode`] facts.
18//!
19//! # Feature flags
20//!
21//! * `nightly` – enables the `rustc_interface` linkage. Without this flag
22//! the crate compiles as a stub that always returns an empty result.
23//! Alternatively set `RUSTC_BOOTSTRAP=1` to use the internal APIs on a
24//! nightly toolchain without the feature flag.
25//!
26//! # Limitations
27//!
28//! * The backend requires a nightly compiler or `RUSTC_BOOTSTRAP=1`.
29//! * Procedural macros are not expanded by the visitor; only the expanded
30//! code is visible.
31//! * The analysis is per‑crate; multi‑crate projects need to be handled at
32//! the workspace level (see [`icb_graph::builder`]).
33
34#[cfg(feature = "nightly")]
35extern crate rustc_interface;
36
37#[cfg(feature = "nightly")]
38extern crate rustc_driver;
39
40#[cfg(feature = "nightly")]
41extern crate rustc_session;
42
43#[cfg(feature = "nightly")]
44extern crate rustc_hir;
45
46#[cfg(feature = "nightly")]
47extern crate rustc_middle;
48
49#[cfg(feature = "nightly")]
50extern crate rustc_span;
51
52#[cfg(feature = "nightly")]
53pub mod driver;
54
55#[cfg(feature = "nightly")]
56pub mod visitor;
57
58use anyhow::Result;
59use icb_parser::facts::RawNode;
60use std::path::Path;
61
62pub fn parse_rust_crate(_crate_root: &Path, _args: &[String]) -> Result<Vec<RawNode>> {
63 #[cfg(feature = "nightly")]
64 {
65 driver::run_analysis(_crate_root, _args)
66 }
67 #[cfg(not(feature = "nightly"))]
68 {
69 log::warn!("icb-rustc backend requires the `nightly` feature (or RUSTC_BOOTSTRAP=1)");
70 Ok(vec![])
71 }
72}