Build And Profiling

Build Dependency Chain & Profiling

Build Dependency Chain

When changing Rust code, rebuild downstream artifacts in order:

verter_compiler + verter_semantic + verter_session + verter_ffi (Rust crates)
    ↓ cargo build
verter_napi (NAPI-RS cdylib)    verter_lsp (LSP binary)    verter_wasm (wasm-bindgen cdylib)
    ↓ pnpm run build:native         ↓ pnpm run build:lsp       ↓ pnpm run build:wasm (dev, no wasm-opt)
@verter/native (.node binary)   verter-lsp (target/<triple>/debug/)  or `pnpm --filter @verter/wasm build`
    ↓                                ↓                       (publication lane: + cached wasm-opt)
@verter/unplugin (bundler)      verter-vscode (F5/VSIX)         ↓
    ↓                                                       @verter/playground (browser, via its own
playground build (Vite)                                     `sync:wasm` — no implicit copy from @verter/wasm)
    ↓
playground E2E tests

pnpm build (host developer build) is native + lsp + ts only — it never touches WASM. pnpm dist (publication-ready artifacts) adds the full WASM lane (bindgen + cached wasm-opt via scripts/wasm-opt-cache.mjs). See CLAUDE.md → Build.

Common Rebuild Sequences

Key Details

• @verter/unplugin depends on @verter/native — compiles .vue files at build time via the Rust native binary
• @verter/playground uses @verter/unplugin (devDep) for Vue SFC compilation, and @verter/wasm (dep) for the in-browser editor
• Native binary lives in packages/native/dist/ after build:native
• LSP binary lives in target/<host-triple>/debug/verter-lsp (or .../release/verter-lsp with build:lsp:release) — pnpm run build:lsp/build:lsp:release and build-host.mjs all pass an explicit --target <host-triple> (see the "one explicit host target" build-lane rule), so the output is triple-qualified, not the bare target/debug//target/release/ a plain cargo build (no --target) would produce
• Clear Vite cache (node_modules/.vite) when rebuilding playground after native changes

Canonical gate build telemetry

node scripts/gate.mjs capability-probes Cargo's stable HTML timings and, when supported, adds --timings only to the dev cargo nextest archive, shipped-cfg cargo check, and package-scoped shipped contract cargo nextest run. It never adds the flag to archive-backed Surface 1 and never launches a second build/run for telemetry. The dev archive reads the front target timing source; shipped check and contract read their isolated shipped-lane target source sequentially. Each overwrite-prone report is cleared at its exact file, validated after each producing command settles, and snapshotted immediately under gate-work/cargo-timings/. The source must be proven absent before launch, or—if exact-file deletion fails—have a changed pre/post SHA-256 content identity; unchanged or ambiguous sources are refused. Version/help probe budgets share a separate hard aggregate startup-reporting deadline and hard-terminate their direct child. The canonical build/test deadline begins only after startup collection settles; reporting failures warn and mark telemetry partial without changing the gate verdict.

The terminal gate-work/gate-telemetry-v1.{log,json} pair records a bounded tool/host fingerprint, stable build/test phase durations, cold/empty/warm target state, lane layout/policy, and the maximum same-snapshot aggregate live-forest RSS with its total process count and per-lane contributions. Use these artifacts when comparing build-job or test-thread configurations; do not infer build cost from per-test summed seconds. After the one archive/list and all post-list preconditions, Surface 1 overlaps the serial shipped check -> contract lane in separate Cargo targets. The shipped target is intentionally cold relative to the front archive target; its check warms the contract. One supervisor retains the absolute whole-gate deadline, aggregate stall vector, and one aggregate memory ceiling, and raw output is replayed once in Surface/check/contract order. The bare local gate cancels shipped after a hard Surface receipt and may omit the remaining shipped phases; use node scripts/gate.mjs --exhaustive for every comparable full-run benchmark. A truncated local report is correctly partial and must not be compared against an exhaustive baseline as a performance improvement.

The current independently measured policy caps at 12 Cargo build jobs and 12 nextest threads. Both are CPU-clamped; omitted build jobs are also memory-tiered from the effective child-tree ceiling (12 jobs at >=16 GiB, 8 at >=12 GiB, otherwise 4). On the 32-logical-CPU / 127.17-GiB Windows reference host, cold target-absent dev archives measured 422.775s / 283.920s / 234.792s at 4/8/12 jobs, with peak RSS 7.72 / 9.90 / 11.60 GiB. Identical-inventory Surface 1 runs measured 695.769s / 426.028s / 357.825s at 4/8/12 threads, with peak RSS 1.85 / 3.08 / 3.84 GiB. The global memory rule remains unchanged. The tier matters on the documented 24-GiB host: its 12-GiB default ceiling selects 8 jobs, because the measured 12-job peak was already 11.60 GiB; 8 jobs peaked at 9.90 GiB. Explicit positive resource overrides are never clamped, so future comparisons can retest either axis independently. Windows has no serialized max-threads = 1 test groups; retain the exact hang-protection overrides while using full configured capacity during every comparison.

--prepare may reuse an already-built archive target as a first-launch check. On Windows, proc-macro test harnesses need the host runtime DLL search path; the prepare launcher derives it from each suite's nextest list metadata and prepends it to the sanitized child PATH. Do not copy DLLs, filter proc-macro suites, or treat loader exits as warmed: missing metadata and every non-zero launch remain strict setup failures.

IDE editor archives

The IDE release uses .github/workflows/editor-packages.yml to build Lapce and Zed WASM plugins and package them alongside the Neovim Lua and Helix configuration archives. The same reusable workflow runs on pull requests affecting these files. To reproduce it locally from the repository root:

node --test scripts/package-editor-integrations.test.mjs
cargo build --locked --manifest-path extensions/lapce/Cargo.toml --target wasm32-wasip1 --release
cargo build --locked --manifest-path extensions/zed/Cargo.toml --target wasm32-wasip2 --release
node scripts/package-editor-integrations.mjs --output .agent-run/editor-integrations

Install both WASI targets first (rustup target add wasm32-wasip1 wasm32-wasip2). Packaging requires tar and an output directory without existing archive names. The script checks the editor version against the VS Code manifest, validates WASM formats, and excludes development files. It does not bump versions or publish. See docs/contributing/ci-cd.md and each editor's README for the release/install contract. Native servers are separate, platform-specific release assets.

Quick Rebuild (Native)

# Quick rebuild native + copy
cargo build --release --package verter_napi && rm -f packages/native/dist/verter-native.win32-x64-msvc.node && cp target/release/verter_napi.dll packages/native/dist/verter-native.win32-x64-msvc.node

Profiling with Hotpath

The hotpath feature flag enables #[hotpath::measure] annotations on key functions for timing/allocation profiling. Propagates across 7 crates:

verter_bench --features hotpath
  ├── verter_compiler/hotpath         (compile_inner, generate_ide_script, generate_ide_template)
  ├── verter_session/hotpath         (upsert_via_scheduler, ensure_compiled, compile_entry, execute_source)
    │   ├── verter_semantic/hotpath (build_script_analysis_with_scope)
  │   ├── verter_scheduler/hotpath (execute_source_stage)
  │   └── verter_workspace/hotpath      (read_file, resolve_import)
  └── verter_diagnostics/hotpath  (lint_inner)