Architecture

Unplugin Configuration (packages/unplugin/)

@verter/unplugin provides a VerterPluginOptions interface:

preCompile architecture:

• During buildStart(), scans the project root for .vue files (excluding node_modules and dot-directories)
• For each file: upserts it into the host, resolves external src attributes and macro type dependencies (e.g., import type { Props } from './types' used in defineProps<Props>()), then triggers compilation
• When another plugin modifies the file before transform(), the host detects the content change via internal hashing and recompiles
• Third-party .vue files in node_modules compile on-demand during transform() — no pre-compilation overhead

Macro type resolution invariant: cross-file macro type resolution must only follow imports reachable from the requested type's local declaration graph. Unrelated imports in the same file are out of scope for that traversal, and plain imports are not implicit re-exports.

Core TS Transformation Pipeline (packages/core/src/v5/)

Vue SFC → parser/ → process/script/plugins/ → TSX output
              ↓              ↓
         ParsedBlock    MagicString (preserves sourcemaps)

1. parser/ - Parses SFC into typed blocks

   • parser.ts - Main entry, uses @vue/compiler-sfc
   • types.ts - ParsedBlockScript, ParsedBlockTemplate, ParsedBlockUnknown
   • script/ - Extracts script AST items (ScriptItem, ScriptTypes)
   • template/ - Parses template expressions and bindings

2. process/ - Plugin-based transformation system

   • script/script.ts - Orchestrates plugin execution
   • types.ts - ProcessContext, ProcessPlugin, ProcessItemType

Plugin System (packages/core/src/v5/process/script/plugins/)

Plugins transform parsed SFC items into TSX. Each plugin can:

• Hook into pre/post phases
• Transform specific ScriptTypes via transformXxx methods
• Add items to context.items for downstream plugins

Plugin execution order: Controlled by enforce: "pre" | "post". Pre-plugins run first, then main transforms, then post-plugins.

TypeScript Code Patterns

Defining script plugins:

import { definePlugin, ScriptContext } from "../../types";
export const MyPlugin = definePlugin({
  name: "my-plugin",
  enforce: "pre", // or "post"
  pre(s, ctx) {
    /* runs before transforms */
  },
  transformFunctionCall(item, s, context) {
    /* transform specific type */
  },
  transformDeclaration(item, s, context) {
    /* another type */
  },
  post(s, context) {
    /* runs after all transforms */
  },
});

Type helper prefix convention:

• Internal helpers use ___VERTER___ prefix (see packages/core/)
• String-exported types use $V_ prefix for collision avoidance

Parser types (packages/core/src/v5/parser/):

• ParsedBlockScript, ParsedBlockTemplate - Block-specific parsed data
• ScriptItem, ScriptTypes - Categorized script AST items

Language Server Architecture (crates/verter_lsp/src/)

The LSP is a standalone Rust binary (verter-lsp) that communicates with VS Code over stdio.

main.rs (stdio transport + CLI args + provider selection)
    ↓
server.rs (LSP message loop, request dispatch)
    ↓
documents/       → Document tracking and synchronization
features/        → LSP feature handlers (see table below)
analysis/        → Static analysis integration
css/             → CSS-specific language features
tsgo/            → TSGO type provider integration (LSP protocol)
tsserver/        → tsserver type provider integration (JSON protocol)
capabilities.rs  → Server capability registration
config.rs        → Server configuration, ProjectConfig, ProjectRegistry, vite alias discovery
workspace_scanner.rs → Async priority-based workspace file scanner
sync_coordinator.rs  → Debounced type provider sync during typing

Per-Project Configuration (config.rs)

ProjectRegistry groups per-project config for multi-root workspaces. Each ProjectConfig has: root path, TsConfigPathResolver, ResolvedLintConfig, Linter instance, and optional vite_config_path/vite_config_deps. Tsconfig-backed projects use only tsconfig paths; fallback projects get Vite aliases via OXC static analysis (vite_config.rs) or trusted Node.js execution.

TypeProvider Trait (tsgo/traits.rs)

Both TSGO and tsserver implement the TypeProvider trait (14+ methods: hover, completions, diagnostics, definition, references, rename, signature help, code actions, semantic tokens, highlights, inlay hints, open/update/close file, shutdown). The trait is object-safe (dyn TypeProvider) so the server is backend-agnostic.

TSGO Module (tsgo/)

tsserver Module (tsserver/)

Provider Selection (main.rs)

CLI arg --type-provider=auto|tsgo|tsserver|off (from VS Code verter.typeProvider setting):

• auto: detect TS version in node_modules — TS 5.x/6.x → tsserver + recommend TSGO; else try TSGO
• tsgo/tsserver: explicit, no fallback
• off: verter-only mode

Only one provider runs at a time. Provider PID is sent to the extension via $/verter/typeProviderStarted notification for orphan cleanup.

LSP features (features/):

LSP Feature Flow

Request (stdio) → server.rs → Find document in host cache → Feature handler → Response (stdio)

CSS Analysis & Selector Matching (crates/verter_analysis/src/)

CSS analysis uses a lightweight byte-level scanner (no external CSS parser dependency). The scanner extracts selectors, classes, IDs, custom properties, and at-rules from <style> blocks.

Module structure:

style.rs              # CSS scanner, structured selector parser, specificity computation
selector_match.rs     # Three-valued selector matching against template elements
template.rs           # Template element analysis, dynamic class extraction, :style CSS var extraction

Key types:

CSS Variable Analysis (three-block tracking):

• Style: scan_declarations() extracts AnalyzedCustomProperty (definitions with values/spans) and AnalyzedVarUsage (var() references). extract_var_references() handles nested var() fallbacks.
• Template: extract_dynamic_style_vars() extracts CSS vars from :style="{ '--color': val }". extract_static_style_vars() extracts from style="--color: red".
• Script: try_extract_css_var_manipulation() detects el.style.setProperty('--x', val), getPropertyValue('--x'), removeProperty('--x').
• Cross-component: ProjectIndex.css_var_flow(name) and VerterHost.css_var_flow(name) return CssVarFlow with all files defining/referencing/manipulating a variable.

Selector matching algorithm (match_selector()):

1. Match rightmost compound against target element
2. Walk left through combinators: Child checks parent_index, Descendant walks ancestor chain
3. Dynamic :class or component types → MaybeMatches (can't determine statically)
4. :not() inverts, :is()/:where() takes best match across alternatives

Position encoding for CSS spans: CssAnalysis spans (classes, IDs, selectors) are SFC-absolute byte offsets. The CSS scanner produces content-relative offsets internally, then CssAnalysis::make_spans_absolute(content_offset) is called at the host level (after optional SCSS remap) to convert all spans to SFC-absolute. Consumers use spans directly without adding any offset. StyleBlockAnalysis.content_offset is retained for documentation and slice operations.

Rust Compiler Architecture (crates/verter_core/src/)

The Rust compiler uses an AST-based pipeline. The compile() orchestrator drives a linear 5-phase pipeline:

Vue SFC Source
    ↓
[Tokenizer]  byte-level SFC tokenization (tokenizer/byte.rs)
    ↓
[Parser]     builds arena-based template AST + extracts script/style blocks (parser/)
    ↓
[Style]      v-bind() scan + CSS processing (style/ + css/)
    ↓
[Script]     macro expansion, binding extraction, component wrapper (script/)
    ↓
[Template]   render function codegen — VDOM or Vapor backends (template/)
    ↓
[Compile]    orchestrates the above, applies CodeTransform, emits output (compile.rs)

Module overview:

compile.rs                # Pipeline orchestrator, options, result types
tokenizer/
├── byte.rs               # Zero-copy byte-level SFC tokenizer (production)
├── helpers.rs            # Tokenizer utility functions
└── types.rs              # Event, QuoteType
parser/
├── mod.rs                # Syntax state machine (tokenizer events → AST)
└── types.rs              # RootNodeScript, RootNodeStyle, RootNodeTemplate
ast/
├── mod.rs                # TemplateAst (flat arena with O(1) navigation)
├── builder.rs            # TemplateAstBuilder (incremental AST construction)
└── types.rs              # AstNode, ElementNode, NodeId, pre-computed flags
script/
├── mod.rs                # generate_script() entry point
├── process.rs            # Script setup processing, companion script merging
├── macros.rs             # defineProps/Emits/Model/Slots/Expose/Options
└── css_vars.rs           # _useCssVars() injection for v-bind() in styles
template/
├── oxc/                  # OXC expression parsing for template bindings
│   ├── mod.rs            # parse_template_expressions()
│   └── types.rs          # OxcParsedAst, OxcParsedElement, OxcParsedExpression
└── code_gen/             # Render function codegen
    ├── mod.rs            # generate_template() entry point
    ├── walker.rs         # DFS tree walker (shared by all backends)
    ├── types.rs          # TemplateCodeGen trait, CodeGenOutput
    ├── binding.rs        # BindingResolver (_ctx./$setup. prefix resolution)
    ├── shared/           # Shared codegen helpers
    ├── vdom/             # VDOM render function output (_createElementVNode, etc.)
    └── vapor/            # Vapor mode output (_template, _renderEffect, etc.)
ide/                      # IDE codegen: TSX or JSX+JSDoc (for LSP/TSGO type checking)
├── mod.rs                # generate_ide_template() — Vue template → valid JSX; IdeScriptOptions, IdeTemplateOptions
├── script.rs             # generate_ide_script() — script block → TS or JS+JSDoc wrapper
├── condition.rs          # v-if/v-else-if/v-else condition chain codegen
└── template/
    ├── mod.rs            # walk_element/walk_node, cached directive removal, ref conversion
    ├── directives.rs     # v-if → ternary, v-for → .map(), v-show → style
    └── props.rs          # :prop → prop={}, @event → onEvent={}, v-bind spread
style/
├── mod.rs                # generate_style() entry point
└── v_bind.rs             # v-bind() scanning in CSS
css/
├── mod.rs                # process_style() — CSS pipeline entry point
├── prepass.rs            # Vue syntax → valid CSS markers (v-bind, :deep, :slotted)
├── scoped.rs             # Scoped CSS: insert [data-v-xxx] selectors
├── modules.rs            # CSS Modules: hash class names
├── walk.rs               # String-level CSS selector walking
└── types.rs              # ProcessStyleOptions, ProcessStyleResult
code_transform/
├── code_transform.rs     # Chunk-based deferred mutation engine (MagicString equivalent)
├── chunk.rs              # Chunk types (Original, Overwritten, Inserted, InsertedMapped)
└── source_map.rs         # Source map generation from chunk positions
utils/
├── oxc/                  # OXC parser utilities
│   ├── bindings/         # Expression binding extraction
│   └── vue/              # Vue-specific OXC helpers (macros, type resolution, v-for, v-slot)
└── vue/                  # Vue runtime helpers (tag detection, patch flags)

Arena-Based Template AST

The parser builds a flat Vec<AstNode> arena with O(1) navigation:

pub struct TemplateAst {
    nodes: Vec<AstNode>,        // flat arena
    root: RootNodeTemplate,
}

pub struct AstNode {
    kind: AstNodeKind,          // Element | Text | Comment | Interpolation
    parent: Option<NodeId>,     // O(1) parent lookup
    index_in_parent: usize,     // O(1) sibling lookup
}

ElementNode pre-computes metadata during parsing to avoid re-scanning in codegen:

• tag_type: Element / Component / SlotOutlet / Template
• prop_flag: Bitset of prop characteristics (has class, style, spread, etc.)
• children_flag: Bitset of children characteristics (has text, elements, v-if, etc.)
• children_mode: Enum for codegen branching (Empty, TextOnly, SingleElement, Mixed, etc.)
• Cached directives: v_condition, v_for, v_slot, v_once, v_ref

CodeTransform (Deferred Mutations)

All codegen phases use CodeTransform — a chunk-based deferred mutation engine:

let mut ct = CodeTransform::new(input, &allocator);
ct.overwrite(start, end, replacement);  // deferred
ct.prepend_left(pos, content);          // deferred
let output = ct.build_string();         // single-pass concatenation

Key features:

• cursor_hint: Accelerates forward-progressing access patterns to amortized O(1)
• output_delta: Incremental length tracking avoids full scan
• Pre-allocated chunk capacity: source_len / 13 (empirically tuned)

Binding Metadata Flow

1. script/process.rs parses <script setup> → walks AST → classifies bindings as BindingType (SetupConst, SetupRef, Props, etc.)
2. Bindings passed to template/code_gen/ via generate_template() parameter
3. BindingResolver determines correct accessor prefix (_ctx., $setup., __props.) and suffix (.value for refs)
4. Binding patches accumulated in CodeGenOutput, batch-applied to CodeTransform

Template Codegen Backends

Three backends implement the TemplateCodeGen trait, called by walker::walk_template() in DFS order:

• VDOM (vdom/): In-place source overwrites producing _createElementVNode() calls
• Vapor (vapor/): Replaces entire template block with direct DOM manipulation code

CSS Processing Pipeline

Style block content
    ↓ style/v_bind.rs     — scan v-bind() expressions
    ↓ css/prepass.rs       — replace Vue syntax with CSS markers
    ↓ lightningcss         — parse + normalize CSS
    ↓ css/modules.rs       — hash class names (CSS Modules)
    ↓ css/scoped.rs        — insert [data-v-xxx] attribute selectors

Cross-File Type Resolution

External types for macros like defineProps<ExternalType>() are pre-resolved by the host:

1. Host detects type dependencies from imports
2. Host resolves types from its file store
3. Host passes resolved types via VerterCompileOptions::external_types
4. script/process.rs merges external types with companion <script> types

The Rust compiler never does file I/O — all external resolution is the host's responsibility.

Resolver ownership rule: host-backed component-meta and analysis must share one cross-file resolver. Do not build separate resolver logic for script-setup macros, Options API metadata, compat wrappers, or consumer-specific adapters.

Resolver modes:

• Type mode: resolve the requested symbol and its canonical source location only. This is for tracking identity and navigation, not shape expansion.
• Expanded mode: use the same traversal and the same caches, then materialize the expanded shape / expanded text for metadata consumers.

Component-meta rule: all metadata-producing macro and Options API surfaces must go through the shared resolver in Expanded mode. That includes props, emits, slots, data, computed, and expose-style members.

Traversal rule: only follow the import graph reachable from the requested type's declaration graph. Unrelated imports in the same file are out of scope.

Caching rule: when parsing a .ts / .js / declaration file for type resolution, cache discovered symbol name → canonical location mappings. Cache direct re-exports, barrelled exports, and any discovered export * hops as well, because repeated wildcard-barrel scanning is expensive.

Component-meta cache rule: when changing verter_host, verter_resolver, verter_analysis, or packages/component-meta type paths, use cached lookup/eval state as the only source of truth after the cache-owning pass. Do not rewalk AST/source as a fallback to recover or expand types.

Component-meta publication rule: keep registry publication shallow and demand-driven. Publish and expand only the symbols required by the active metadata query; do not eagerly materialize unrelated owner-local or package-local helpers.

Component-meta target-selection rule: keep runtime/declaration companion selection shallow. Canonicalization may probe cached raw source existence, but must not build export analysis, snapshots, or eval envs just to choose a target file.

Component-meta imported-state rule: after shallow imported dependency seeding, resolver stages must consume only the imported dependency cache for imported file snapshots/envs/analysis. Do not bounce from alias or registry hydration back into raw snapshot/source builders for imported files.

Component-meta deepening rule: resolve one requested symbol/query path at a time. Do not let a file-level resolver widen into unrelated sibling symbols/files while chasing a single metadata request.

Component-meta projection rule: when projecting metadata/fallthrough from an already-resolved query, reuse that resolved state plus the captured store/session view. Do not bounce back out to a fresh top-level fallthrough/meta query.

Component-meta collection rule: imported-eval collection must stay lazy/BFS over the active symbol route. Do not add eager collector modes or source-text reparsing fallbacks in shared resolver code.

CompileTarget (Selective Pipeline)

CompileTarget (bitflags in verter_core::compile::types) controls which compilation steps run:

Presets:

Key API: VerterHost::ensure_compiled(canonical_id, profile) compiles with the given profile's target. Used by LSP and MCP to populate the cache. get_virtual_file() still exists for retrieving specific virtual file outputs.

Analysis MCP Server (verter_mcp)

The verter-mcp binary exposes Verter's full analysis, diagnostics, compilation, and scoring pipeline via MCP. It provides 33 tools for AI agents.

Key Architecture

• VerterMcpServer wraps VerterHost (with AnalysisScope::LSP for maximum analysis data), Linter, and ActionEngine
• Tools auto-load files from disk via ensure_loaded() — agents don't need to pre-load
• Template analysis requires a compilation pass — ensure_template_analysis() triggers it transparently
• Cross-file tools iterate all loaded files (no ProjectIndex exposed from host)
• Scoring engine computes composite 0-100 quality scores from a11y, lint, template complexity, API surface, CSS health, and reactivity dimensions

verter_analysis — Static Analysis Types

verter_analysis is independent from verter_core. The compilation crate produces RawTemplateData during compilation, which verter_host converts into verter_analysis types.

AnalysisScope

Bitflags (u32) controlling which analysis passes run during file upsert.

Script (bits 0-7)

Template (bits 8-15)

Style (bits 16-19)

Cross-file (bits 24-26)

Presets:

ScriptAnalysisSnapshot

Primary output of build_script_analysis(). Produced by a single OXC parse + AST walk.

ReactivityKind: None | Ref | Computed | Reactive | MaybeRef | Mutable

TemplateAnalysisSnapshot

Populated after compilation by converting RawTemplateData from verter_core.

ProjectIndex

Aggregates file-level usage into project-wide indexes:

• provide_index: provide key → files that call provide(key)
• inject_index: inject key → files that call inject(key)
• component_graph: file → components it uses (forward edges)
• component_reverse_index: component name → files that use it
• class_index: CSS class name → files that define it
• v_bind_css_index: v-bind CSS expression → files that use it
• custom_property_index: CSS custom property → files that define it

Data Flow

Vue SFC Source
    |
    v
verter_core::compile()
    |-- ScriptAnalysisSnapshot (from OXC parse during compilation)
    |-- RawTemplateData (spans, binding refs, component tags)
    |-- CssParsed* (v-bind spans, pseudo spans)
    |
    v
verter_host (conversion layer)
    |-- RawTemplateData --> TemplateAnalysisSnapshot
    |-- CssParsed*      --> StyleBlockAnalysis
    |-- Resolves import paths, populates resolved_canonical_id
    |-- Updates ProjectIndex with file usage
    |
    v
Consumers (LSP, build, linter) query snapshots + ProjectIndex

Key Files