The type checker

Every Vibescript program is type checked before it runs, and a program with a type error does not compile (ADR-007). The checker also reports the spellings ADR-008 removed. The language guide describes the rules from an author’s side; this page describes the checker, its entry points and its diagnostics.

Every engine, the command line, the REPL, the language server and the test runner type check every compile; there is no mode without static types.

What it proves

A program that compiles has no type errors except at the edges where dynamic data enters. The checker proves that:

• every call names a function, method, namespace member, host function or capability that is in scope, and its positional arguments, keywords and block match one of the callee’s signatures;
• every value has the type its position expects: arguments, results, fields, collection elements, block results and assignments;
• optional values are tested before use and any values are narrowed;
• locals keep the type of their first assignment and are assigned on every path before they are read;
• instance variables are declared and assigned by initialize;
• shapes are read and written only at keys they declare;
• conditions and logical operands are bool;
• case over an enum or bool handles every value;
• every require names a literal module that resolves, and calls into it match its declarations.

At runtime the remaining checks are those at the edges: arguments a host passes to Script::call and its declared globals and capabilities, JSON.parse_as, checked casts with as, and the results of host capabilities with contracts. Builtins still raise on invalid values, such as a missing key passed to fetch, and every call still runs under its step, memory, recursion and time limits. Method visibility is checked statically too: calling a private method through a receiver, or a protected one from outside its class, is a compile error (V0208).

How it works

The checker reads the parsed program once, after the parser. It first collects every declaration, so the order of declarations does not matter: functions, classes with their properties and instance variables, enums, modules, type aliases, host functions with their published signatures, and the globals and capabilities the host declares. It resolves every signature and alias, then checks each function body once, from its own signature and the signatures of what it calls; it never reads a callee’s body. Required files named by literal require calls are checked the same way, and their exports’ declarations type the calls into them.

Types are interned, so comparing two types compares identifiers. A local’s type and its narrowing live on one flow state with a trail of changes, so branches and loops join in time proportional to what they changed rather than to the number of locals. Builtin members come from the signature table, src/signatures/builtins.vibe, whose generic members are instantiated at each call: array<T>#map binds T to the receiver’s element type and infers U from the block. An overloaded name selects its signature by the number of positional arguments, the keyword names and the presence and arity of a block, never by argument types.

The work is linear in the program. The checker counts it deterministically, and compilation charges that count to the step quota when it runs under limits, as a cold require inside a call does. Except on WASI, sources longer than 1 KiB are checked on a thread with a 64 MiB stack, because the checker recurses once per level of syntax, which the parser bounds to 1,024. WASI has no threads, so there the checker refuses syntax more than 128 levels tall with V0001 instead of exhausting the stack (see platform support).

The same pass also records the static type of every member call’s receiver. The removed-spelling rules use it, so that size on an array is reported and rewritten to length while a class’s own size method is left alone.

Entry points

• Engine::compile reports every diagnostic as a compile error; Error::diagnostics() returns them.
• Engine::type_check(source) checks without compiling and returns every diagnostic, warnings included, with the receiver types, and the types of the top-level locals and result, which a host continuing a session declares for its next script (see sessions).
• Engine::check_entry_arguments(source, function, count) checks that a command line can call function with count string arguments.
• vibes check FILE prints the diagnostics with their source lines; --json prints one JSON object per diagnostic. See the command line.
• vibes fix applies every machine-applicable fix and checks again until none applies.
• vibes lsp publishes the diagnostics as the document changes and offers the fixes as quick fixes.

Diagnostics

Each diagnostic has a stable code, a severity, a primary span, optional labelled spans such as the declaration a value is checked against, the expected and found types where they apply, and zero or more fixes. A fix is a set of text edits valid on its own, such as inserting the annotation the checker inferred, rewriting a removed spelling, or replacing x[i] with x.fetch(i); a diagnostic with more than one plausible repair offers none rather than guessing. A fix marked always may be applied without asking, and vibes fix applies only those. Codes keep their meaning across releases; the message text may improve.

Two diagnostics are warnings, which do not stop compilation: V0121, a nil test whose result the value’s type already decides, and V0120 when an is_type? test can never be true. Every other diagnostic is an error.

vibescript::diagnostic::codes() returns this registry, retired codes included and marked by CodeInfo::retired, and Diagnostic::to_json gives the JSON form vibes check --json prints:

{"code":"V0107","name":"optional-use","severity":"error","file":null,"span":{"start":24,"end":31,"line":2,"column":1,"end_line":2,"end_column":8},"message":"this value may be nil (array<int>?); test it with `!= nil` before indexing it","expected":null,"found":null,"labels":[],"fixes":[...]}

A deliberately invalid example in this documentation is fenced as ```vibe error=V0107, and tests/docs.rs checks that it fails with exactly those codes while every other example compiles cleanly.