Skip to main content

Module protocol

Module protocol 

Source
Expand description

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.

Data only: nothing here reads a file or takes a Workspace. A client that only speaks JSON depends on this crate alone.

Modules§

display
A styled line as data: the words and their roles, no colours. An interface maps a Role to its own style and renders the line, so the composition of a row — what is written, in what order, which part is the hit — lives once, in the protocol.
vocabulary
How the answers are read: the output vocabulary of glyphs and words, how an intent is named, how a count and a time are said. Every interface renders these — colour is the renderer’s (the CLI’s Palette, the picker’s Theme); this is what is being coloured, and it lives with the shapes it describes so a client reads them the way the CLI prints them.

Structs§

ApplyPlanQuery
Batch
vvv batch: several intents planned in sequence and applied as one.
BatchIntent
Several intents planned in sequence, each against the state the previous one leaves, and applied as one.
Call
A request on a session’s wire (vvv serve): the request with whatever id the caller chose, echoed on the Reply.
Capability
CheckCommand
CheckFailure
CheckOutput
CheckResult
Consumer
ContentId
Digest of complete file contents, independent of their path.
ContextBudget
ContextCandidate
ContextItem
ContextOmissions
ContextPage
ContextPageQuery
ContextQuery
ContextReply
ContextUnresolved
ContextWork
ContinueQuery
Cursor
Dead
dead [--lang]: declarations nothing in the workspace refers to, with how many tokens might.
DeadQuery
vvv dead: declarations nothing in the workspace refers to.
DefinitionCandidate
DefinitionLocation
Enough information to select, open, or request context for a declaration.
DefinitionPreview
Definitions
Reference evidence kept separately for each possible definition of a name.
Dep
One import statement in the file and, when the layout can follow it, where it leads.
Deps
deps <path>: what a file imports and who imports it.
DepsQuery
vvv deps <path>: what a file imports and who imports it.
Diff
One file’s change: the unified diff text (the wire) and its hunks (the model).
DiffLine
One line of a hunk: its kind and its text, without the +/-/space marker. Its number is implied by the hunk’s range and the lines before it.
DiscardPlanQuery
Discovery
DiscoveryQuery
ExpandQuery
Expansion
ExplainQuery
vvv explain <path>:<line>:<col>: what is at a position.
Explanation
explain <path>:<line>:<column>: what is at a position.
Exposed
Failure
A failed request, as the wire carries it.
File
One file as it is, with syntax colouring and declaration ranges.
FileChange
One file a plan touches: its edits and the whole-file diff.
FileQuery
One file as it is now, with its syntax colouring: what a picker shows.
History
vvv history.
HistoryEntry
One apply that can still be undone.
Hunk
One @@ block: the lines it covers in each file, and the lines themselves.
Impact
impact <name>: every module that would feel a change to a declaration — those importing it, then those importing them, outward.
ImpactQuery
vvv impact <name>: who would feel a change to a declaration.
ImportSite
Importer
A file that imports from the one asked about.
ImportsQuery
vvv imports [path]: import statements worth a look.
ImportsReport
imports [path]: import statements worth a look — unused, unresolved, or the same target twice.
InspectPlanQuery
LineRange
Lines a hunk covers in one file: start is the first line (1-based) and len how many it spans. len == 0 is an insertion between lines.
Locations
where <name>: where name is declared and how to reach each site.
Match
MatchId
Content-derived identifier: the same file, range and text yield the same id across runs, so a selection made from one search can drive a later command.
NavigationQuery
NavigationReply
Notice
Something a plan could not do and a human should look at. Never fatal: the rest of the plan is still valid. Data only; the display layer words it.
Occurrence
A token spelling the renamed name, with what the imports could tell.
Outline
outline <path>: what a file declares, in order.
OutlineItem
OutlineQuery
vvv outline <path>: what a file declares.
OutputLimit
PageBudget
PagedContextItem
Placed
A declaration as the graph holds it: placed, with its reach.
PlanId
Opaque handle scoped to an engine session, not a serializable edit plan.
PlanReceipt
PlanReview
PlanReviewCursor
A plan-store cursor. It cannot be used with source-query continue or expand.
PlanReviewPage
PrepareMoveIntent
Workspace-relative source and destination for a retained file/directory move.
PrepareMoveQuery
PrepareMoveSymbolIntent
Workspace-relative selected declaration move between existing files.
PrepareMoveSymbolQuery
PrepareRenameQuery
PrepareRewriteQuery
QueryLimits
Recovery
A recovery result; unknown states are separate from confirmed residual effects.
RecoveryEffect
RecoveryIssue
RecoveryUnverified
References
references <name>: the declarations called name and every token that spells it, each judged against the declaration meant.
ReferencesQuery
The declaration(s) called name, and every identifier that spells it, each judged against the declaration meant. What rename gathers before it plans, and what references answers on its own.
Relationship
RelationshipBudget
RelationshipCoverage
Relationships
RelationshipsQuery
Reply
The reply to a Call: its id, then the usual envelope.
ResolutionEvidence
ResolutionQuery
Compact resolution with the same origin and selection semantics as navigation.
ResolutionReply
Respelling
A reference a move re-spelled in place: where it is, what it said and what it says now. A preview lists these as one row each instead of a diff hunk; an edit no respelling accounts for is structural and shows as a hunk.
ReviewPlanQuery
ReviewTotals
Rewrite
vvv rewrite: one edit per selected match.
RewriteIntent
Replace every selected match of query with template.
RewriteOf
The rewrite intent makes of matches already found: a caller that keeps the matches supplies its selection; selected matches are revalidated against the source before their coordinates and captures are used.
Search
vvv search: what was found, and which languages could not be asked.
SearchPage
SearchPageItem
SearchPageQuery
SearchQuery
A structural or symbolic search with a typed engine answer. Plugin predicates remain separate from engine-owned workspace filters.
SearchScope
Explicit file/directory prefixes and owning package names or IDs. Alternatives within each list are ORed; the two lists are intersected.
Site
Skipped
A language a search left out, and why: its grammar could not compile the query (a Rust pattern on a TypeScript tree). Never fatal; the other languages’ matches are complete. Data only; the display layer words it.
SnapshotId
Opaque identity of captured source and project inputs; not a disk transaction.
SourceAnchor
Surface
surface [package]: what a package offers to everyone, and who takes it.
SurfaceQuery
vvv surface [package]: what a package offers to everyone.
SymbolMoveCandidate
SymbolMoveCandidates
SymbolMoveCandidatesQuery
SymbolMovePiece
SymbolRef
A declaration in one source version, not an identity across edits.
Template
Replacement text with meta-variable holes: bar($$$ARGS), $NAME_v2.
Undo
vvv undo.
Unreferenced
ValidatePlanQuery
ValidationBudget
ValidationReport
WhereQuery
vvv where <name> [--from <file>]: where a name is declared, and the import that reaches each site from from.
WorkBudget
WorkspaceFiles
WorkspaceFilesQuery
The workspace’s visible files, independent of registered languages.

Enums§

Answer
The answer to a Request: the result type of the command asked. On the wire it is that type’s shape alone — a client knows what it asked — so it serialises without a tag and is read back by the command’s type.
CheckOperation
CheckOutcome
Command
Confidence
How sure a rename is that an occurrence refers to its target declaration.
ContextDetail
Source detail requested for every context item. Bodies remain the default.
ContextOutcome
ContextRelation
ContextSignature
Present only for signature requests; absence preserves the body contract.
ContinuationRecovery
A recovery action clients can branch on without parsing the error message.
DiffKind
What a diff line does to the file.
ErrorCode
The kind of failure, stable across releases; the message is not.
Intent
Any mutating request, as one value: what history records, what a summary renders, what a remote client sends.
MutationAnswer
The result of a mutation intent. Queries have no variant here.
MutationState
The lifecycle of a mutation result, with a history id exactly when applied. Serializes as applied plus the optional history_id.
NavigationOrigin
NavigationOutcome
NoticeKind
PageReply
PlanPreview
PlanReviewItem
Metadata uses the corresponding ordinary preview record shape. Text fields replaced by empty strings are reconstructed by following JSON-pointer chunks.
PlanReviewKind
PlanReviewReply
PlanStatus
Reach
The set of modules that may name a declaration: a kind applied to the declaring module’s address. Never declared, always computed.
Reason
What the file’s imports and paths said about an occurrence: the ground for its Confidence. Views tag ? and ✗ sections with it.
RecoveryOperation
RecoveryState
RelationshipKind
RelationshipLimit
RelationshipLimitation
RelationshipResolution
Request
One request, tagged by command. A mutation carries the same fields as its Intent plus apply: false previews, true writes and records one undo — exactly what the CLI’s --apply does.
ResolutionOutcome
Response
Top-level envelope of every --json response.
ReviewMutation
ReviewSection
Selection
Which matches of a search a later command acts on.
SelectionError
SymbolMoveOwnership
SymbolMoveUnsupported
TemplateError
UnavailableReason
ValidationSourceState

Constants§

SCHEMA
The shape of this contract. Bumped when a field changes meaning or goes away; adding fields does not bump it.

Traits§

Mutation
The closed set of mutation payloads an executable plan can carry. External payloads cannot authorize writes: