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
Roleto 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’sTheme); 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§
- Apply
Plan Query - Batch
vvv batch: several intents planned in sequence and applied as one.- Batch
Intent - 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 whateveridthe caller chose, echoed on theReply. - Capability
- Check
Command - Check
Failure - Check
Output - Check
Result - Consumer
- Content
Id - Digest of complete file contents, independent of their path.
- Context
Budget - Context
Candidate - Context
Item - Context
Omissions - Context
Page - Context
Page Query - Context
Query - Context
Reply - Context
Unresolved - Context
Work - Continue
Query - Cursor
- Dead
dead [--lang]: declarations nothing in the workspace refers to, with how many tokens might.- Dead
Query vvv dead: declarations nothing in the workspace refers to.- Definition
Candidate - Definition
Location - Enough information to select, open, or request context for a declaration.
- Definition
Preview - 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.- Deps
Query 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).
- Diff
Line - 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. - Discard
Plan Query - Discovery
- Discovery
Query - Expand
Query - Expansion
- Explain
Query 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.
- File
Change - One file a plan touches: its edits and the whole-file diff.
- File
Query - One file as it is now, with its syntax colouring: what a picker shows.
- History
vvv history.- History
Entry - 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.- Impact
Query vvv impact <name>: who would feel a change to a declaration.- Import
Site - Importer
- A file that imports from the one asked about.
- Imports
Query vvv imports [path]: import statements worth a look.- Imports
Report imports [path]: import statements worth a look — unused, unresolved, or the same target twice.- Inspect
Plan Query - Line
Range - Lines a hunk covers in one file:
startis the first line (1-based) andlenhow many it spans.len == 0is an insertion between lines. - Locations
where <name>: wherenameis 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
searchcan drive a later command. - Navigation
Query - Navigation
Reply - 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.- Outline
Item - Outline
Query vvv outline <path>: what a file declares.- Output
Limit - Page
Budget - Paged
Context Item - 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.
- Plan
Receipt - Plan
Review - Plan
Review Cursor - A plan-store cursor. It cannot be used with source-query continue or expand.
- Plan
Review Page - Prepare
Move Intent - Workspace-relative source and destination for a retained file/directory move.
- Prepare
Move Query - Prepare
Move Symbol Intent - Workspace-relative selected declaration move between existing files.
- Prepare
Move Symbol Query - Prepare
Rename Query - Prepare
Rewrite Query - Query
Limits - Recovery
- A recovery result; unknown states are separate from confirmed residual effects.
- Recovery
Effect - Recovery
Issue - Recovery
Unverified - References
references <name>: the declarations callednameand every token that spells it, each judged against the declaration meant.- References
Query - The declaration(s) called
name, and every identifier that spells it, each judged against the declaration meant. Whatrenamegathers before it plans, and whatreferencesanswers on its own. - Relationship
- Relationship
Budget - Relationship
Coverage - Relationships
- Relationships
Query - Reply
- The reply to a
Call: itsid, then the usual envelope. - Resolution
Evidence - Resolution
Query - Compact resolution with the same origin and selection semantics as navigation.
- Resolution
Reply - 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.
- Review
Plan Query - Review
Totals - Rewrite
vvv rewrite: one edit per selected match.- Rewrite
Intent - Replace every selected match of
querywithtemplate. - Rewrite
Of - The rewrite
intentmakes ofmatchesalready 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.- Search
Page - Search
Page Item - Search
Page Query - Search
Query - A structural or symbolic search with a typed engine answer. Plugin predicates remain separate from engine-owned workspace filters.
- Search
Scope - 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.
- Snapshot
Id - Opaque identity of captured source and project inputs; not a disk transaction.
- Source
Anchor - Surface
surface [package]: what a package offers to everyone, and who takes it.- Surface
Query vvv surface [package]: what a package offers to everyone.- Symbol
Move Candidate - Symbol
Move Candidates - Symbol
Move Candidates Query - Symbol
Move Piece - Symbol
Ref - 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
- Validate
Plan Query - Validation
Budget - Validation
Report - Where
Query vvv where <name> [--from <file>]: where a name is declared, and the import that reaches each site fromfrom.- Work
Budget - Workspace
Files - Workspace
Files Query - 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. - Check
Operation - Check
Outcome - Command
- Confidence
- How sure a rename is that an occurrence refers to its target declaration.
- Context
Detail - Source detail requested for every context item. Bodies remain the default.
- Context
Outcome - Context
Relation - Context
Signature - Present only for signature requests; absence preserves the body contract.
- Continuation
Recovery - A recovery action clients can branch on without parsing the error message.
- Diff
Kind - What a diff line does to the file.
- Error
Code - 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.
- Mutation
Answer - The result of a mutation intent. Queries have no variant here.
- Mutation
State - The lifecycle of a mutation result, with a history id exactly when applied.
Serializes as
appliedplus the optionalhistory_id. - Navigation
Origin - Navigation
Outcome - Notice
Kind - Page
Reply - Plan
Preview - Plan
Review Item - Metadata uses the corresponding ordinary preview record shape. Text fields replaced by empty strings are reconstructed by following JSON-pointer chunks.
- Plan
Review Kind - Plan
Review Reply - Plan
Status - 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. - Recovery
Operation - Recovery
State - Relationship
Kind - Relationship
Limit - Relationship
Limitation - Relationship
Resolution - Request
- One request, tagged by
command. A mutation carries the same fields as itsIntentplusapply: false previews, true writes and records one undo — exactly what the CLI’s--applydoes. - Resolution
Outcome - Response
- Top-level envelope of every
--jsonresponse. - Review
Mutation - Review
Section - Selection
- Which matches of a search a later command acts on.
- Selection
Error - Symbol
Move Ownership - Symbol
Move Unsupported - Template
Error - Unavailable
Reason - Validation
Source State
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: