Vipeye — Static Type Checker and Language Server for Viper

Vipeye is a full-featured, standards-based static type checker and language server for Viper, written in TypeScript. It is designed for high performance and can be used with large Viper source bases.

Vipeye ships in three forms:

• a language server (vipeye-langserver) speaking LSP over stdin/stdout;
• a command-line type checker (vipeye);
• an extension for Visual Studio Code (vscode-vipeye), which bundles both the LSP client and the Viper core UI (project / toolchain).

It is built on the Pyright codebase, adapted from the ground up to Viper semantics (AOT compilation, C-style type system, pointer and memory semantics). Python analysis is no longer supported — only the Viper dialect is checked.

What is Viper

Viper is an ahead-of-time (AOT) compiled language whose syntax is modeled on CPython but whose semantics are entirely different:

• TPC — the seed compiler, itself based on CPython, used to bootstrap the toolchain.
• TPV — the first self-hosted compiler, written in Viper. Once tpv --lsp lands, it will replace the Pyright-derived analyzer in this repository.

Vipeye exists to provide type checking, diagnostics and editor intelligence for .vp / .vpi sources while TPV's own language server is under development.

Capabilities

Viper language semantics

• C-style type system: t.CPtr, t.CArray, t.CVoid, t.CTypedef, t.CDefine, t.CEnum, t.REnum, plus the compiler built-ins char, double and rawptr (a raw-pointer typedef).
• Pointer and memory semantics: CPtr[T] / rawptr[T], c.Deref, address-of, pointer arithmetic and indexing; a __new__ returning a raw pointer is auto-wrapped into CPtr[T].
• C declaration modifiers (t.CInline, t.CStatic, t.CConst …) are filtered out during type merging — only the underlying data type is kept.
• Declaration modifiers on functions, with fn / fun / func / function as aliases of def.
• struct / union / enum / rnum, including nested t.REnum variants destructured by field order.
• Variadic *args bound as va_list in the function body (va_arg, and pointer passthrough such as vsnprintf(buf, size, fmt, args)).
• Implicit conversion rules: integer/float convert in all directions (safe narrowing, lossless widening); integer → float requires float width ≥ integer width; float → integer is rejected; pointers of the same level may convert, different levels may not; explicit casts are always allowed.
• Global/local variable rules: reading a global never errors; assigning an undeclared global without global does; a local redeclaration shadows the global; and so on.
• Type representations: bool / t.CBool map to i1; str / bytes are i8*, while str | t.CPtr / bytes | t.CPtr are i8**.
• PEP 695 syntax is pre-processed for Viper: type parameter lists are stripped and unknown T | t.CPtr unions are folded to i8*.
• Fail-fast analysis: missing type information is reported as an error instead of silently degrading to i8* / void / i32.

Editor features

• Diagnostics with human-readable messages, plus Viper-tuned semantic highlighting (keywords, decorators, t.CDefine constants, and undefined symbols rendered in white).
• Completion, hover, go-to-definition, find references, rename, document symbols, and Organize Imports.
• Activity-bar UI (Project / Toolchain / Settings), .vpj project files with a dedicated custom editor, and a status-bar compiler indicator.
• Import resolution over VIPER_HOME (stdlib), viperconfig.json extra paths, the workspace root, and recursively discovered child project configurations.

Packages

• packages/vipeye-internal — Core analysis engine: parser, binder, type evaluator, checker, and language service. All logic lives here.
• packages/vipeye — CLI wrapper. Bundles vipeye-internal into a distributable npm package with vipeye and vipeye-langserver entry points.
• packages/vipeye-typeserver — Type server process for long-running editor sessions.
• packages/vscode-vipeye — VS Code extension client (Vipeye LSP), with the Viper core source (packages/viper) bundled at build time.
• packages/viper — Viper core source library: project (.vpj) management, toolchain, and the activity bar UI (Project / Toolchain / Settings).

Relationship to Pyright

• Viper dialect: viperconfig.json instead of pyrightconfig.json; configuration namespace viper.* instead of python.analysis.* / pyright.*.
• Viper stdlib stubs bundled in packages/vipeye-internal/vipershed-fallback.
• Type semantics follow Viper rules: implicit conversions, pointer types (CPtr / CArray), t.CTypedef / t.CDefine / t.CEnum / t.REnum, T | t.CPtr pointer folding, global-variable access rules, and more.
• Diagnostics and semantic highlighting are tailored to Viper syntax.

Building and Testing

# Install all packages (from repo root)
npm install

# Build the core library
cd packages/vipeye-internal && npm run build

# Run all tests (rebuilds the test server first)
cd packages/vipeye-internal && npm test

# Run tests without rebuilding the test server (faster iteration)
cd packages/vipeye-internal && npm run test:norebuild

# Build the CLI / VS Code extension bundles (from repo root)
npm run build:cli:dev
npm run build:extension:dev

See docs/build-debug.md for details.

Documentation

Refer to the documentation for installation, configuration, and usage details.

Environment variables

If Vipeye fails to create a temporary directory (for example in remote/server environments where the OS temp directory doesn't exist or isn't writable), you can override the temp directory root:

• VIPEYE_TMPDIR: Absolute path to a directory that Vipeye can use for temporary files/directories. Vipeye will create it if needed.

Vipeye otherwise relies on the platform temp directory (for example TMPDIR, TMP, TEMP, or the OS default).

License

MIT