Skip to main content

Crate raf_source

Crate raf_source 

Source
Expand description

The workspace source index: packages and targets, the module tree of each target, a symbol index and a use-alias resolver, over a Tree seam with a disk and a memory backend and under canonical path containment.

Load a workspace from a real directory and ask where a path is defined. The block needs a real tree, so it is compiled and not run:

use raf_source::{DiskTree, Workspace};

let ws = Workspace::load(&DiskTree::new(".")?, &["crates"])?;
let resolution = ws.resolve("raf_okf::Document")?;
for site in &resolution.sites {
    let item = ws.item(*site).expect("a site is an item of this workspace");
    println!("{} at {}:{}", item.path, item.file, item.name_line);
}
for target in ws.targets().filter(|t| !t.shipping) {
    println!("{} is a non-shipping target", target.name);
}

Workspace::exported_items lists the public surface of a library or a binary: the items another crate can name through its crate root, each under the path it is exported by and with the item that defines it, and the public re-exports of other crates, which are not items of the target. Over a real tree, each library’s surface maps every exported path back to its definition. The block needs a real tree, so it is compiled and not run:

use raf_source::{DiskTree, TargetKind, Workspace};

let ws = Workspace::load(&DiskTree::new(".")?, &["crates"])?;
for id in ws.target_ids() {
    let target = ws.target(id).expect("an id of this workspace");
    if target.kind != TargetKind::Lib {
        continue;
    }
    let exports = ws.exported_items(id)?;
    for export in &exports.items {
        let item = ws.item(export.item).expect("an item of this workspace");
        println!("{} is {} in {}", export.path, item.path, export.file);
    }
    for reexport in &exports.reexports {
        println!("{} re-exports {}", reexport.path, reexport.written);
    }
}

With MemoryTree a fixture needs no disk:

use raf_source::{MemoryTree, Workspace};

let tree = MemoryTree::from([
    ("Cargo.toml", "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n"),
    ("src/lib.rs", "mod inner;\npub use inner::go as run;\n"),
    ("src/inner.rs", "pub fn go() {}\n"),
]);
let ws = Workspace::load(&tree, &["."])?;
assert_eq!(ws.resolve("demo::run")?.path, "demo::inner::go");

A pub item of a private module is exported only through a pub re-export:

use raf_source::{MemoryTree, Workspace};

let tree = MemoryTree::from([
    ("Cargo.toml", "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n"),
    ("src/lib.rs", "mod inner;\npub use inner::go as run;\npub(crate) fn helper() {}\n"),
    ("src/inner.rs", "pub fn go() {}\npub fn unused() {}\n"),
]);
let ws = Workspace::load(&tree, &["."])?;
let lib = ws.target_ids().next().expect("the library");
let exports = ws.exported_items(lib)?;
assert_eq!(exports.items.len(), 1);
assert_eq!(exports.items[0].path, "demo::run");
assert_eq!(
    ws.item(exports.items[0].item).map(|item| item.path.as_str()),
    Some("demo::inner::go")
);

Every file the crate looks at goes through Tree. DiskTree reads a directory on disk and refuses anything that leads out of its root, or is not a regular file, or is larger than the caller allows. MemoryTree holds the same contents in a map so that a fixture needs no disk:

use raf_source::{EntryKind, MemoryTree, RelPath, Tree, TreeError};

let tree = MemoryTree::from([("src/lib.rs", "pub fn go() {}\n")]);
let lib = RelPath::new("src/lib.rs")?;
assert_eq!(tree.read(&lib, 1024)?, "pub fn go() {}\n");
assert_eq!(tree.entry(&RelPath::new("src")?)?, Some(EntryKind::Dir));
assert!(matches!(
    tree.read(&RelPath::new("src/missing.rs")?, 1024),
    Err(TreeError::NotFound { .. })
));

parse_source parses Rust text under bounds. A token pre-scan refuses a file that passes a recursion Budget before syn sees it, and the parse and a caller’s visitor then run on a thread named after the file, with a stack of PARSE_STACK_BYTES:

use raf_source::{Budget, LoadErrorKind, RelPath, parse_source};

let file = RelPath::new("src/lib.rs")?;
let items = parse_source(&file, "pub fn go() {}\n", |tree| tree.items.len())?;
assert_eq!(items, 1);

let deep = format!("type T = {}u8{};", "A<".repeat(65), ">".repeat(65));
let refused = parse_source(&file, &deep, |_| ()).unwrap_err();
assert!(matches!(
    refused.kind,
    LoadErrorKind::Budget { budget: Budget::Angles, limit: 64 }
));

Workspace::load takes explicit roots, finds the packages and targets under them, and follows every target’s mod declarations as rustc does:

use raf_source::{MemoryTree, TargetKind, Workspace};

let tree = MemoryTree::from([
    ("Cargo.toml", "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n"),
    ("src/lib.rs", "mod inner;\n"),
    ("src/inner.rs", "pub fn go() {}\n"),
    ("tests/it.rs", "fn case() {}\n"),
]);
let ws = Workspace::load(&tree, &["."])?;
let targets: Vec<_> = ws.targets().map(|t| (t.kind, t.crate_path.as_str())).collect();
assert_eq!(
    targets,
    [(TargetKind::Lib, "demo"), (TargetKind::Test, "demo::test_crate::it")]
);
assert_eq!(ws.files().count(), 3);

Only TreeError::NotFound means that nothing is there. Every other error is a refusal or a failure and is never read as absence.

Re-exports§

pub use syn;

Modules§

git
Native read-only repository and object access, without executable helpers. Native read-only Git access. No API starts a process or writes repository state.

Structs§

ActiveConfiguration
A package’s validated declared compilation context in a filtered index.
CapturedDirectory
A directory’s sorted entries and identity from one verified directory handle.
CapturedFile
A regular file’s bytes, permissions and identity from one verified handle.
CapturedLink
A lexical symbolic link, captured without opening or reading its target.
CargoLintManifest
Cargo manifest lint settings, including the workspace inheritance switch. The native TOML arena preserves dotted and inline tables alike.
CfgSelection
Retained complete declared cfg, admitted under the load’s original grant.
CodeResolver
Module-level code lookup with source-owned item/module/target association.
CommittedGitTree
A committed repository read by the native Git library, without checkout reads.
CompilerPlatform
Platform facts printed by the compiler for the actual selected Cargo target.
DeclaredCfg
A caller-declared complete target triple and cfg set, never inferred from this host.
DeclaredConfiguration
One selected compilation target and its complete enabled package features.
DependencyDeclaration
One package dependency declaration, including its unevaluated target condition.
DependencySpec
Written dependency constraints, not evidence of activation or source provenance.
DisabledSyntax
An opaque declaration proved disabled for every configuration.
DiskTree
A tree read from a directory on disk.
Entry
One entry of a directory listing.
ExportOptions
What Workspace::exported_items_with lists.
ExportedItem
One item of a target’s public surface, under one path that another crate can name it by.
Exports
The public surface of a target, as Workspace::exported_items returns it.
ExternLibrary
One actual admitted external library under a Rust name visible in the source model.
FileId
The identity of a file: two paths whose identities are equal name one file.
ForeignModulePath
An arrival through a module path attribute at a file that the package of the arriving target does not own.
ImplBlock
An impl block of a target, inherent or of a trait, once for each module path its file is reached under.
ImplId
The identity of an impl block within one loaded workspace: its place in the order of Workspace::impls, stable for the life of the index.
IndexedImport
One import in the module index, with its exact target and reading context.
InheritedDependency
The workspace entry inherited by a dependency, retaining its declaring base.
Item
One named item of the workspace.
ItemId
The identity of an item within one loaded workspace: a dense number that is stable for the life of the index.
LexedSource
Guarded source lexed on its existing scoped worker, before syntax parsing.
LoadError
A failure to load one file, naming the file.
LoadOptions
Limits a caller sets for one load.
LockedBinding
A source/manifest identity computed from a checked load, not from caller labels. Provenance alone does not imply active configuration; the separate optional configuration receipt records declared filtering, never provider policy.
LockedCatalog
A strict Cargo.lock version 3 or 4 package/edge profile.
LockedEdge
An exact declaration requested for source-qualified cross-package traversal.
LockedManifest
A candidate manifest/row association, verified by the locked load before use.
LockedPackage
One complete locked package identity and its uniquely selected outgoing edges.
LockedPackageId
A package row’s identity within one LockedCatalog, not a persistent key.
LockedPackageRoots
Candidate manifests beneath one sealed external source.
LockedSource
A complete source key whose equality never treats missing precision as a wildcard.
MemoryTree
A tree of files held in memory: a map of path to text.
Package
A package found under a root.
PackageId
The identity of a package within one loaded Workspace.
ParallelOptions
Independent scheduler ownership limits; source/index options remain unchanged.
ParallelUsage
Scheduler high-water counts, finalized only after every worker has joined.
ParsedSource
One explicitly selected source and its owned syntax tree.
PathSite
The path attribute through which the walk reached a file.
PinnedGitTree
The committed objects of one caller-declared commit, without a lock identity.
PreparedSource
An immutable source admitted by the caller-thread guard scan.
Reach
One way a file was reached.
Reachability
What Workspace::reachable found: every reached node once, in the order the walk reached them, breadth first from the roots in the order of their nodes.
Reached
One reached node, with the edge it was first reached by and the node that edge comes from (None for a root).
Reexport
A public re-export of a target that names nothing the target itself defines as an item of the index: an item of another crate of the workspace, a crate outside the workspace or one of its items, an enum variant (variants are not items of the index), or a path the index cannot follow, such as an item a macro generates. A public glob carries such a re-export of a module it reaches into the module that reads it, under the reader’s path.
ReferenceBinding
Manifest/lock identity retained for structural reference navigation.
ReferenceObservation
A read-only reference package whose manifest matches its selected lock identity.
ReferencePackageRoots
Explicit manifest associations in one actual structural reference context.
ReferenceRequest
One actual manifest declaration and its exact owning lock row.
RegistryArchiveTree
Immutable package files from one checksum-authenticated registry archive.
RegistryIndex
Explicit Cargo registry configuration supplied for one declaration selection.
RelPath
A path below a tree root: /-separated, UTF-8, never absolute and never leaving the root.
Resolution
What resolve found.
SharedStr
Text that the records of one load share: an item path, a name, a module path or a written type is stored once and every record that holds it points at that one copy.
SourceAuthorityId
A source authority within one load; this handle is not durable source proof.
SourceFile
A source file of the workspace, parsed once.
SourceTrees
A first-party tree and borrowed, independently rooted dependency trees.
SpanFact
A region of the file in lines and bytes.
SyntaxBound
The per-node and per-byte terms of a syntax-tree storage bound.
SyntaxHeld
A retained-tree estimate read from a parsed tree.
Target
One target of a package.
TargetId
Index of a target in Workspace::targets.
TestFn
A function marked #[test], with what cargo needs to select it.
TestPlatformGuard
A conservative necessary guard borrowed from a test’s retained source facts.
Unexpanded
An unexpanded item-producing macro invocation.
UnresolvedImpl
An inherent impl block whose self type names no struct, enum or union the index can see, once for each module path its file is reached under.
Usage
What a load spent against its budgets, as Workspace::usage reports it.
Workspace
The packages, targets and source files found under a set of roots.

Enums§

Budget
A budget of a load.
CfgAtom
One explicitly enabled target cfg predicate; absence in a complete set is false.
CodeResolveError
Failure to establish a reading context or resolve its module-level code path.
CompilerPlatformError
Why a compiler configuration cannot supply trustworthy platform facts.
DependencyKind
The table a dependency is declared in.
Edge
The edge a node was first reached by.
EntryKind
What a directory entry is, judged without following a final symlink.
ExportError
Why the public surface of a target could not be listed.
ExternRouteKind
The access route preserved by an admitted library receipt.
FieldShape
How a struct declares its fields. A unit or tuple struct also defines a name in the value namespace.
LoadErrorKind
What went wrong while loading a file.
LockedGitReference
The requested Git reference, independent of its selected full revision.
LockedSourceKind
The source family named by an explicit lock source.
LockedTree
A sealed external source admitted to configured dependency resolution.
Namespace
A name space: the three in which a Rust path can name something.
Node
A node of the reachability graph: an item or an impl block.
Opened
What Tree::read_unseen found at a path.
OpenedBytes
What DiskTree::read_unseen_bytes found at a path.
Origin
Where a failing file was reached from.
ParallelOptionsError
Invalid worker-stack arithmetic or insufficient fixed scheduler ownership.
PathError
Why an input is not a RelPath.
ReachError
Why the reachability of a set of roots could not be given.
ReferenceTree
The actual backend of a structural reference source.
ResolutionAttempt
One canonical lookup and the actual indexed targets its missing routes read. Target identities are local to this workspace load, not provider authority.
ResolveError
Why a path did not resolve.
SelfType
How the index placed the members of an impl block, by what its self type names.
SymbolKind
What an indexed item is.
TargetKind
What a target is.
TargetProblem
What is wrong with a package target.
TestRole
Whether, and how, an item belongs to test code.
TraitKey
How the trait of an impl that is not on a local type is named in a path.
TreeError
Why a Tree call failed.
Vis
The declared visibility of an item.

Constants§

DEFAULT_MAX_FILE_BYTES
The default cap on one file: 8 MiB.
PARSE_BYTES_PER_TOKEN
Empirical peak bytes per token for the measured empty-statement shape.
PARSE_STACK_BYTES
The stack of the thread that parses, in bytes: 64 MiB.
RECURSION_UNIT_BYTES
The most stack of the parse thread that one unit of Budget::Recursion takes in a debug build, rounded up: parsing, reading the facts and dropping the syntax tree, measured on the costliest counted shape, generic arguments nested in a type (A<A<...>>), at 16,481 bytes a unit.
SYNTAX_BYTES_PER_BYTE_DEN
Denominator of the per-byte charge; see SYNTAX_BYTES_PER_BYTE_NUM.
SYNTAX_BYTES_PER_BYTE_NUM
Numerator of the bytes of syntax-tree storage charged per source byte.
SYNTAX_BYTES_PER_NODE
Measured peak bytes of syntax-tree storage per native token-tree node.
SYNTAX_NODE_SIZES
The node enums the retained-tree estimate counts, each with its size and the fewest native token-tree nodes that one element of the enum takes to parse (a statement or expression takes one, an item or a macro member three, a match arm four).

Traits§

ParallelTree
An explicitly selected Tree capability for native parallel parsing.
Tree
A read-only tree of UTF-8 text files below one root.

Functions§

discover_root
Find the workspace root containing start, relative to the supplied tree.
library_target_name
The name of the library target that the root manifest of tree declares, which a locked configuration must name to select that target.
parse_source
Parse text as a Rust file and run visit on the syntax tree.
parse_source_with_tokens
Parse once and give the visitor the syntax and its original native tokens.
parse_sources
Parse an explicit corpus once and give all its syntax trees to one visitor.
prepare_source
Check the default file-token and recursion guards without starting a worker.
syntax_held
Read the retained-tree estimate of tree. The walk allocates nothing, apart from one transient copy of each counted literal’s native spelling, which syn hands out only by value and which dies before the next node.
visit_grouped_import
Read the members of a grouped import represented by syn as verbatim tokens. The visitor receives the original attributes and spans, with an independent leading-colon flag for every member. Other token shapes return false.
visit_pattern_bindings
Visit syntactic identifier bindings of a pattern in source order. Type and expression subtrees are excluded. This observes syntax, not type inference or whether an otherwise ambiguous identifier denotes a resolved constant.