Skip to main content

Crate vvv_engine

Crate vvv_engine 

Source
Expand description

The engine: typed capabilities over a workspace and a language registry. Engine::run dispatches a Request and returns an in-process Execution. Queries answer with concrete data; mutations retain Planned results until Apply writes and commits their history entry. Intent is the mutation description shared by history and batch.

Typed clients call capability-owned execute, plan, or apply methods, and Ledger owns history and undo. The dispatcher orchestrates those bodies; interfaces consume Execution::into_answer only at a reporting boundary.

Mutation capability types have one canonical public path, at the crate root:

use vvv_engine::{Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent};
let _: Option<(Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent)> = None;

They are not aliases in protocol:

ⓘ
use vvv_engine::protocol::{Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent};

Their owning capability modules are private:

ⓘ
use vvv_engine::capabilities::rename::Rename;

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::Definitions;
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::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::Mutation;
pub use protocol::MutationAnswer;
pub use protocol::MutationState;
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::Recovery;
pub use protocol::RecoveryEffect;
pub use protocol::RecoveryIssue;
pub use protocol::RecoveryOperation;
pub use protocol::RecoveryState;
pub use protocol::RecoveryUnverified;
pub use protocol::References;
pub use protocol::ReferencesQuery;
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::SearchQuery;
pub use protocol::SearchScope;
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::Unreferenced;
pub use protocol::WhereQuery;
pub use protocol::WorkspaceFiles;
pub use protocol::WorkspaceFilesQuery;
pub use protocol::ContentId;
pub use protocol::DefinitionCandidate;
pub use protocol::DefinitionPreview;
pub use protocol::NavigationOrigin;
pub use protocol::NavigationOutcome;
pub use protocol::NavigationQuery;
pub use protocol::NavigationReply;
pub use protocol::ResolutionEvidence;
pub use protocol::SnapshotId;
pub use protocol::SourceAnchor;
pub use protocol::SymbolRef;
pub use protocol::UnavailableReason;
pub use protocol::ContextBudget;
pub use protocol::ContextCandidate;
pub use protocol::ContextDetail;
pub use protocol::ContextItem;
pub use protocol::ContextOmissions;
pub use protocol::ContextOutcome;
pub use protocol::ContextQuery;
pub use protocol::ContextRelation;
pub use protocol::ContextReply;
pub use protocol::ContextSignature;
pub use protocol::Capability;
pub use protocol::Discovery;
pub use protocol::DiscoveryQuery;
pub use protocol::OutputLimit;
pub use protocol::Command;
pub use protocol::ContextPage;
pub use protocol::ContextPageQuery;
pub use protocol::ContextUnresolved;
pub use protocol::ContextWork;
pub use protocol::ContinuationRecovery;
pub use protocol::ContinueQuery;
pub use protocol::Cursor;
pub use protocol::ExpandQuery;
pub use protocol::Expansion;
pub use protocol::PageBudget;
pub use protocol::PageReply;
pub use protocol::PagedContextItem;
pub use protocol::QueryLimits;
pub use protocol::SearchPage;
pub use protocol::SearchPageItem;
pub use protocol::SearchPageQuery;
pub use protocol::WorkBudget;
pub use protocol::DefinitionLocation;
pub use protocol::ResolutionOutcome;
pub use protocol::ResolutionQuery;
pub use protocol::ResolutionReply;
pub use protocol::ApplyPlanQuery;
pub use protocol::DiscardPlanQuery;
pub use protocol::InspectPlanQuery;
pub use protocol::PlanId;
pub use protocol::PlanPreview;
pub use protocol::PlanReceipt;
pub use protocol::PlanReview;
pub use protocol::PlanReviewCursor;
pub use protocol::PlanReviewItem;
pub use protocol::PlanReviewKind;
pub use protocol::PlanReviewPage;
pub use protocol::PlanReviewReply;
pub use protocol::PlanStatus;
pub use protocol::PrepareMoveIntent;
pub use protocol::PrepareMoveQuery;
pub use protocol::PrepareMoveSymbolIntent;
pub use protocol::PrepareMoveSymbolQuery;
pub use protocol::PrepareRenameQuery;
pub use protocol::PrepareRewriteQuery;
pub use protocol::ReviewMutation;
pub use protocol::ReviewPlanQuery;
pub use protocol::ReviewSection;
pub use protocol::ReviewTotals;

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
Shared report vocabulary. Capabilities compose answers into Documents; a View lays those facts out as rows. Composition stays on Document, implemented beside each capability’s execution. No report is serialized.

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.
Applied
A successful apply with the required id of its committed history entry. Construction is private and result access is immutable.
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. Query answers cannot be applied:
CheckCommand
CheckFailure
CheckOutput
CheckResult
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.
Ledger
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.
Move
vvv move: a file or directory moved, its importers respelled.
MoveError
MoveIntent
Move a file and make every reference to it follow.
MoveSymbol
vvv move --symbol: one declaration moved between files.
MoveSymbolIntent
Move one declaration — with what belongs to it in the text, and for Rust its impl blocks — from the file declaring it to another file of the same language, and make every reference follow.
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.
NavigationCancellation
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.
ParentCreation
Parent directories created before a file mutation, including partial failure.
PlanLimits
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. Session plan handles reference it without accepting executable edits back from a client; an ordinary serialized mutation result has no apply handle. Queries cannot carry executable plans:
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.
ProviderVersion
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).
ReadCancellation
A single-use cancellation handle for reads and explicit validation. Clones cancel the same call. Cancellation stops at the next engine checkpoint, not within a parser invocation.
RecoveryError
A failed mutation whose effects could not all be restored and verified.
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.
Relationship
RelationshipBudget
RelationshipCoverage
Relationships
RelationshipsQuery
Rename
vvv rename: the declaration and every occurrence, each judged.
RenameIntent
Rename the declaration(s) called name and every identifier that spells it.
SemanticReply
SemanticRequest
SourceVersion
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.
SymbolMoveCandidate
SymbolMoveCandidates
SymbolMoveCandidatesQuery
SymbolMovePiece
ValidatePlanQuery
ValidationBudget
ValidationReport
Workspace

Enums§

ApplyError
CallKind
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.
CheckOperation
CheckOutcome
EngineError
EntryKind
Execution
An in-process result. Only mutation previews carry executable plans.
ExecutionKind
The kind of retained result requested by an in-process caller.
ExtractionError
Invalid declaration extents or edits in the text selected for a move.
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
MoveState
The file effects of a failed move. Unknown outcomes require observation.
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.
RelationshipKind
RelationshipLimit
RelationshipLimitation
RelationshipResolution
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.
SemanticFailure
SemanticTarget
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.
SymbolMoveOwnership
SymbolMoveUnsupported
ValidationSourceState
VfsError

Traits§

NavigationProvider
A provider revision must change whenever any semantic input changes, including build options and external dependencies. Providers must be bounded, cooperate with cancellation, and must not re-enter this engine while answering.
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