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 --jsonis 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 aViewlays out. The vocabulary is deliberately small; the richness lives in theLines 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
.gitignoreand 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
spanwithreplacement. - Engine
- File
Preview - Highlight
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
- Import
Group - 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.
- Import
Ref - 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.
spancovers exactly the text a rewrite replaces. - Language
Id - 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.
- Memory
Vfs - 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.
- Module
Path - 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.
- Package
Id - 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, notfff-search), a TypeScript package’s name. The layout decides the spelling. - Planned
- What a mutating command returns: the result as a preview —
appliedis false,filesshows what would change — and, kept beside it, the plan(s)Applywrites. 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.
- Query
Builder - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Assemble a
Queryfrom 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
makeandgit, 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::applychecks 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§
- Apply
Error - Capture
Value - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
$Abinds one node;$$$Abinds a sequence. - Engine
Error - Highlight
Kind - 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.
- History
Error - Path
Head - 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.
- Path
Syntax - 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. - Query
Error - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
- Reach
Kind - 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
Enginekeeps 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.
- Symbol
Kind - 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
Nonefor anything. - Vfs