Skip to main content

Crate vvv_engine

Crate vvv_engine 

Source
Expand description

The engine: a graph of the tree built from a Workspace and a language registry, and one entry point that runs a Command against it — a protocol intent or query, answering with the protocol type of the same name; a mutation answers with a Planned result that Apply writes.

Interfaces (CLI, TUI, JSON) talk only to Engine::run; they never touch a language or the file system directly. Each command lives with its components in its own module — rewrite, rename, move_file, answers, understanding, batch, history — as impl Command for <request>.

Re-exports§

pub use protocol::Answer;
pub use protocol::Batch;
pub use protocol::BatchIntent;
pub use protocol::Call;
pub use protocol::Confidence;
pub use protocol::Consumer;
pub use protocol::Dead;
pub use protocol::DeadQuery;
pub use protocol::Dep;
pub use protocol::Deps;
pub use protocol::DepsQuery;
pub use protocol::ErrorCode;
pub use protocol::ExplainQuery;
pub use protocol::Explanation;
pub use protocol::Exposed;
pub use protocol::Failure;
pub use protocol::File;
pub use protocol::FileChange;
pub use protocol::FileQuery;
pub use protocol::History;
pub use protocol::HistoryEntry;
pub use protocol::HistoryQuery;
pub use protocol::Impact;
pub use protocol::ImpactQuery;
pub use protocol::ImportSite;
pub use protocol::Importer;
pub use protocol::ImportsQuery;
pub use protocol::ImportsReport;
pub use protocol::Intent;
pub use protocol::Locations;
pub use protocol::Match;
pub use protocol::MatchId;
pub use protocol::Move;
pub use protocol::MoveIntent;
pub use protocol::MoveSymbol;
pub use protocol::MoveSymbolIntent;
pub use protocol::Mutation;
pub use protocol::Notice;
pub use protocol::NoticeKind;
pub use protocol::Occurrence;
pub use protocol::Outline;
pub use protocol::OutlineItem;
pub use protocol::OutlineQuery;
pub use protocol::Placed;
pub use protocol::Reach;
pub use protocol::Reason;
pub use protocol::References;
pub use protocol::ReferencesQuery;
pub use protocol::Rename;
pub use protocol::RenameIntent;
pub use protocol::Reply;
pub use protocol::Request;
pub use protocol::Respelling;
pub use protocol::Rewrite;
pub use protocol::RewriteIntent;
pub use protocol::RewriteOf;
pub use protocol::Search;
pub use protocol::Selection;
pub use protocol::SelectionError;
pub use protocol::Site;
pub use protocol::Skipped;
pub use protocol::Surface;
pub use protocol::SurfaceQuery;
pub use protocol::Template;
pub use protocol::TemplateError;
pub use protocol::Undo;
pub use protocol::UndoLast;
pub use protocol::Unreferenced;
pub use protocol::WhereQuery;

Modules§

protocol
The JSON contract. Anything printed by vvv --json is one of these types, so a client can rely on the shape independently of the CLI’s human output.
report
A command’s output as data: a list of Blocks per stream, which a View lays out. The vocabulary is deliberately small; the richness lives in the Lines a block carries.

Structs§

Address
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A position in a language’s namespace: the package it belongs to and the path within it — fff :: [grep, types] for a Rust module, path components for a TypeScript file. Prefix relations, which are what a move cares about, never hold across packages.
Apply
Write what was planned and record it as one history entry — one undo. A batch’s steps go in order, each checked against the state the previous one left; if a step fails, the ones before it are rolled back. Answers with the result marked applied.
Context
What a command runs against: the graph, brought up to date, and the workspace it was built from.
DiskVfs
Real file system. Walks respect .gitignore and skip hidden entries.
Edit
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Replace the bytes at span with replacement.
Engine
FilePreview
Highlight
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
ImportGroup
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a grouped entry sits, so a surgery can rewrite it in place or move it out of the group.
ImportRef
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. One path in one file. span covers exactly the text a rewrite replaces.
LanguageId
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Stable identifier of a language (rust, typescript, …).
Languages
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. The set of languages an engine knows about. Filled at startup; read-only after.
MemoryVfs
In-memory file tree. Paths are stored exactly as given. Every write and rename gives the file a fresh version, so stamps behave like mtimes.
Modifier
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A visibility modifier as it appears in the source.
ModulePath
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A path as spelled in source: its head and its segments, with the syntax that spells it. Serialises as the text, so the wire is what the user wrote.
Name
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. One identifier: a module, a declaration, a file stem. Compared by text.
PackageId
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. The name a package goes by in paths: a Rust crate’s lib name (fff, not fff-search), a TypeScript package’s name. The layout decides the spelling.
Planned
What a mutating command returns: the result as a preview — applied is false, files shows what would change — and, kept beside it, the plan(s) Apply writes. The plan never leaves the process: a result that crossed to a client has nothing to apply.
Position
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Zero-based line and character column. Columns count chars, not bytes, so they are safe to show to humans and editors.
Query
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
QueryBuilder
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Assemble a Query from optional parts (typically CLI flags).
Referent
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a declaration is: the file and the span of its name, both as the workspace spells them (relative paths).
RelPath
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A file’s path inside the workspace, spelled the way the project does: / on every platform.
Span
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Half-open byte range [start, end) inside a single file.
Stamp
A cheap witness of a file’s state: modification time and size on disk, a version counter in memory. Two equal stamps mean the contents could not have changed, which is what lets a warm corpus skip the read. Like make and git, it trusts the clock: an edit that keeps the length and lands within the same timestamp tick is invisible until the next one. Writes are never trusted to a stamp — Plan::apply checks content fingerprints.
Symbol
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A declaration found in one file.
Workspace

Enums§

ApplyError
CaptureValue
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. $A binds one node; $$$A binds a sequence.
EngineError
HighlightKind
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. The classes a display distinguishes. Coarse on purpose: enough to read code, not enough to argue about.
HistoryError
PathHead
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a path starts: the part before its segments that says what they are relative to.
PathSyntax
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. How a language spells paths: the separator between segments and the words it uses for a head. A grammar declares one; it parses import text into ModulePaths and spells them back.
QueryError
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
ReachKind
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What a visibility modifier means, relative to the declaring module.
Retention
How long an Engine keeps its graph.
Role
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What position a match occupies in its file: the declaration itself, a token inside an import statement, or any other use. Views lead with declarations and dim imports; the engine orders results by it.
SymbolKind
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What a declaration declares, in vocabulary shared by every language.
VfsError

Traits§

Command
One request and its answer. Implemented by the protocol’s intents and queries, each in the module that holds its components.
Oracle
The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Something that can say what an identifier refers to. Asked one token at a time, only for tokens the graph could not judge, and never trusted blindly: the engine maps the answer onto a declaration it knows before it counts. Implementations are free to answer None for anything.
Vfs