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§
- Active
Configuration - A package’s validated declared compilation context in a filtered index.
- Captured
Directory - A directory’s sorted entries and identity from one verified directory handle.
- Captured
File - A regular file’s bytes, permissions and identity from one verified handle.
- Captured
Link - A lexical symbolic link, captured without opening or reading its target.
- Cargo
Lint Manifest - 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.
- Code
Resolver - Module-level code lookup with source-owned item/module/target association.
- Committed
GitTree - A committed repository read by the native Git library, without checkout reads.
- Compiler
Platform - Platform facts printed by the compiler for the actual selected Cargo target.
- Declared
Cfg - A caller-declared complete target triple and cfg set, never inferred from this host.
- Declared
Configuration - One selected compilation target and its complete enabled package features.
- Dependency
Declaration - One package dependency declaration, including its unevaluated target condition.
- Dependency
Spec - Written dependency constraints, not evidence of activation or source provenance.
- Disabled
Syntax - An opaque declaration proved disabled for every configuration.
- Disk
Tree - A tree read from a directory on disk.
- Entry
- One entry of a directory listing.
- Export
Options - What
Workspace::exported_items_withlists. - Exported
Item - 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_itemsreturns it. - Extern
Library - 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.
- Foreign
Module Path - An arrival through a module
pathattribute at a file that the package of the arriving target does not own. - Impl
Block - An
implblock 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. - Indexed
Import - One import in the module index, with its exact target and reading context.
- Inherited
Dependency - 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.
- Lexed
Source - Guarded source lexed on its existing scoped worker, before syntax parsing.
- Load
Error - A failure to load one file, naming the file.
- Load
Options - Limits a caller sets for one load.
- Locked
Binding - 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.
- Locked
Catalog - A strict Cargo.lock version 3 or 4 package/edge profile.
- Locked
Edge - An exact declaration requested for source-qualified cross-package traversal.
- Locked
Manifest - A candidate manifest/row association, verified by the locked load before use.
- Locked
Package - One complete locked package identity and its uniquely selected outgoing edges.
- Locked
Package Id - A package row’s identity within one
LockedCatalog, not a persistent key. - Locked
Package Roots - Candidate manifests beneath one sealed external source.
- Locked
Source - A complete source key whose equality never treats missing precision as a wildcard.
- Memory
Tree - A tree of files held in memory: a map of path to text.
- Package
- A package found under a root.
- Package
Id - The identity of a package within one loaded
Workspace. - Parallel
Options - Independent scheduler ownership limits; source/index options remain unchanged.
- Parallel
Usage - Scheduler high-water counts, finalized only after every worker has joined.
- Parsed
Source - One explicitly selected source and its owned syntax tree.
- Path
Site - The
pathattribute through which the walk reached a file. - Pinned
GitTree - The committed objects of one caller-declared commit, without a lock identity.
- Prepared
Source - An immutable source admitted by the caller-thread guard scan.
- Reach
- One way a file was reached.
- Reachability
- What
Workspace::reachablefound: 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 (
Nonefor 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.
- Reference
Binding - Manifest/lock identity retained for structural reference navigation.
- Reference
Observation - A read-only reference package whose manifest matches its selected lock identity.
- Reference
Package Roots - Explicit manifest associations in one actual structural reference context.
- Reference
Request - One actual manifest declaration and its exact owning lock row.
- Registry
Archive Tree - Immutable package files from one checksum-authenticated registry archive.
- Registry
Index - 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
resolvefound. - Shared
Str - 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.
- Source
Authority Id - A source authority within one load; this handle is not durable source proof.
- Source
File - A source file of the workspace, parsed once.
- Source
Trees - A first-party tree and borrowed, independently rooted dependency trees.
- Span
Fact - A region of the file in lines and bytes.
- Syntax
Bound - The per-node and per-byte terms of a syntax-tree storage bound.
- Syntax
Held - A retained-tree estimate read from a parsed tree.
- Target
- One target of a package.
- Target
Id - Index of a target in
Workspace::targets. - TestFn
- A function marked
#[test], with what cargo needs to select it. - Test
Platform Guard - A conservative necessary guard borrowed from a test’s retained source facts.
- Unexpanded
- An unexpanded item-producing macro invocation.
- Unresolved
Impl - 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::usagereports 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.
- Code
Resolve Error - Failure to establish a reading context or resolve its module-level code path.
- Compiler
Platform Error - Why a compiler configuration cannot supply trustworthy platform facts.
- Dependency
Kind - The table a dependency is declared in.
- Edge
- The edge a node was first reached by.
- Entry
Kind - What a directory entry is, judged without following a final symlink.
- Export
Error - Why the public surface of a target could not be listed.
- Extern
Route Kind - The access route preserved by an admitted library receipt.
- Field
Shape - How a struct declares its fields. A unit or tuple struct also defines a name in the value namespace.
- Load
Error Kind - What went wrong while loading a file.
- Locked
GitReference - The requested Git reference, independent of its selected full revision.
- Locked
Source Kind - The source family named by an explicit lock source.
- Locked
Tree - 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_unseenfound at a path. - Opened
Bytes - What
DiskTree::read_unseen_bytesfound at a path. - Origin
- Where a failing file was reached from.
- Parallel
Options Error - Invalid worker-stack arithmetic or insufficient fixed scheduler ownership.
- Path
Error - Why an input is not a
RelPath. - Reach
Error - Why the reachability of a set of roots could not be given.
- Reference
Tree - The actual backend of a structural reference source.
- Resolution
Attempt - One canonical lookup and the actual indexed targets its missing routes read. Target identities are local to this workspace load, not provider authority.
- Resolve
Error - Why a path did not resolve.
- Self
Type - How the index placed the members of an impl block, by what its self type names.
- Symbol
Kind - What an indexed item is.
- Target
Kind - What a target is.
- Target
Problem - What is wrong with a package target.
- Test
Role - Whether, and how, an item belongs to test code.
- Trait
Key - How the trait of an impl that is not on a local type is named in a path.
- Tree
Error - Why a
Treecall 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::Recursiontakes 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§
- Parallel
Tree - 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
treedeclares, which a locked configuration must name to select that target. - parse_
source - Parse
textas a Rust file and runvisiton 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, whichsynhands 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.