How vercel-labs/zero works
1. This repository is a multi-part language platform centered on the Zero programming language. The core product is not a single app, but a toolchain: compiler, CLI, standard-library surface, documentation, tests, examples, and editor support.
2. There are two compiler implementations in the repo. native/zero-c/ is the native compiler/runtime implementation in C, including lexing, parsing, checking, IR, target emission, filesystem/web support, and target manifests. compiler-zero/ is a Zero-authored compiler codebase that mirrors the same pipeline in .0 sources and appears to be used as a self-hosting or bootstrapping path.
3. The main language pipeline is conventional but language-specific: source files are lexed, parsed, type-checked, lowered into an intermediate representation, and then emitted for different targets. The native compiler directory makes that split explicit with modules like lexer, parser, checker, MIR/IR, runtime, and WASM/backend emitters.
4. The CLI is the primary user-facing boundary. The README shows commands like zero check, zero run, zero build, zero graph, zero size, zero routes, and zero doctor. That means the CLI is both a compiler front-end and a project/package inspection tool, not just a build command.
5. Packages and manifests are a first-class architectural boundary. Many examples and conformance fixtures contain zero.json, which defines package structure, dependencies, targets, and entry points. The repo therefore models compilation around packages/modules rather than loose single files only.
6. The examples/ tree is a curated set of runnable language samples organized by feature and application shape: tiny snippets, CLI tools, package/module examples, web examples, C interop, memory/ownership examples, and target-specific demos. These examples serve as both documentation and smoke tests for the language/runtime surface.
7. conformance/ is the behavior contract layer. It contains pass/fail fixtures for parsing, type checking, diagnostics, native semantics, packaging, and C interop. This is where the repo encodes expected compiler behavior, error shapes, and target restrictions. It is a key boundary between “language spec intent” and implementation.
8. docs-site/ is a separate web application for the project documentation. It includes article content, doc routing, search, chat, Open Graph image generation, highlighting, and a browser playground. The docs site also embeds a WASM compiler artifact (public/playground/zeroc-zero.wasm), so the browser documentation experience is tied directly to a compiled compiler/runtime build.
9. The docs site is not just static content: it has server-side API routes for search and docs chat, and libraries for search indexing, rate limiting, GitHub integration, and Zero WASM loading. That makes it a hybrid content/app layer sitting on top of the language project’s artifacts and metadata.
10. extensions/vscode/ provides editor integration for .0 files. The contents are focused on language configuration, syntax highlighting, snippets, and extension tests, so this layer is about developer ergonomics rather than compilation.
11. scripts/ and tests/ are the repo’s orchestration and validation layer. Scripts cover native smoke tests, browser/WASM smoke tests, benchmark runs, provenance guardrails, CLI contract checks, and reliability/sanitizer checks. tests/ adds TypeScript-level CLI tests, indicating the project validates the installed command interface from the outside.
12. The repository is designed around multiple execution targets. Evidence in the tree and fixtures points to native execution, WebAssembly, and target-specific compilation constraints, with separate tests for unsupported targets and compatibility checks. The architecture therefore branches from the compiler into backends rather than assuming one universal runtime.
13. The overall data flow is: user source code and manifests enter through the CLI, the compiler pipeline produces diagnostics or artifacts, target backends emit native/WASM outputs, and the docs site plus examples/conformance fixtures continuously validate and demonstrate the behavior of that toolchain. The repo’s boundaries are organized more by toolchain stage and validation surface than by frontend/backend application layers.
Main entry points: zero-c Native compiler · docs-site Docs site · conformance Conformance · examples Examples
Components 22
Toolchain
Language implementation, CLI entrypoints, and target emission.
- Zero CLI · Primary entrypoint for check, run, build, graph, size, routes, and doctor.
bin/zero - Native compiler · Native Zero compiler/runtime implementation and backend emission pipeline.
native/zero-c - Lex/parse · Tokenization and syntax analysis for Zero source.
native/zero-c/src/lexer.c - Type check · Name resolution, type checking, and language rule enforcement.
native/zero-c/src/checker.c - IR lower · Intermediate representation used between analysis and emission.
native/zero-c/src/ir.c - Emit targets · Native and WASM/object emitters plus target-specific output formats.
native/zero-c/src/emit_wasm.c - Platform IO · Filesystem and web-facing support used by the native toolchain.
native/zero-c/src/fs.c - Self-hosted compiler · Zero-authored compiler implementation mirroring the same pipeline.
compiler-zero - Lexer · Zero-language lexer for the self-hosted compiler.
compiler-zero/src/lexer.0 - Parser · Zero-language parser for the self-hosted compiler.
compiler-zero/src/parser.0 - Checker · Zero-language semantic analysis and validation.
compiler-zero/src/checker.0 - MIR · Lowered intermediate form used by the self-hosted compiler.
compiler-zero/src/mir.0 - WASM emit · WASM-oriented emission path in the self-hosted compiler.
compiler-zero/src/wasm.0 - Package manifests · zero.json package boundaries, targets, dependencies, and entrypoints.
examples/web/hello/zero.json
Validation
Conformance suites, benchmarks, and smoke tests.
- Conformance · Pass/fail fixtures capturing parser, checker, native semantics, and packaging expectations.
conformance - Scripts · Benchmarks, smoke tests, contract checks, sandboxing, and reliability automation.
scripts - CLI tests · TypeScript tests that validate the installed zero command from the outside.
tests/zero-cli.test.ts
Experience
Documentation site and editor integration.
- Docs site · Documentation application with articles, routing, search, chat, playground, and OG images.
docs-site - Docs libs · Search, highlighting, page metadata, GitHub integration, rate limiting, and WASM loading.
docs-site/lib/search-index.js - Playground WASM · Browser-ready compiler artifact embedded in the docs site.
docs-site/public/playground/zeroc-zero.wasm - VS Code ext · Language support for .0 files: config, syntax, snippets, and extension tests.
extensions/vscode
Samples
Runnable examples and package fixtures.
- Examples · Curated runnable language samples across CLI, package, web, and interop scenarios.
examples
Connections 24
- Zero CLI → Native compiler: drives · The CLI invokes the native compiler for checking, building, running, and inspection.
- Zero CLI → Package manifests: reads · Commands resolve package layout and targets from zero.json manifests.
- Native compiler → Lex/parse: starts with · Native compilation begins by lexing and parsing source text.
- Lex/parse → Type check: feeds · Parsed syntax flows into semantic validation and type checking.
- Type check → IR lower: lowers to · Checked programs are lowered into an intermediate representation.
- IR lower → Emit targets: emits · IR is turned into native, ELF, Mach-O, COFF, or WASM outputs.
- Platform IO → Native compiler: supports · Filesystem and web helpers extend runtime and toolchain capabilities.
- Self-hosted compiler → Lexer: contains · The Zero-authored compiler is organized as source modules.
- Lexer → Parser: feeds · Lexed tokens are parsed into syntax structures.
- Parser → Checker: feeds · ASTs are semantically checked and validated.
- Checker → MIR: lowers to · The self-hosted compiler lowers checked code into MIR.
- MIR → WASM emit: emits · MIR is used to generate target output, including WASM.
- Package manifests → Examples: organizes · Examples demonstrate package boundaries, entrypoints, and target declarations.
- Package manifests → Conformance: anchors · Conformance cases encode manifest and dependency behavior.
- Examples → Conformance: mirrors · Examples and fixtures overlap to exercise language and runtime behavior.
- Conformance → Native compiler: validates · Fixtures verify parser, checker, runtime, and backend behavior against the native implementation.
- Docs site → Docs libs: uses · The docs app is built from reusable site logic and data helpers.
- Docs site → Playground WASM: embeds · The browser playground runs a compiled compiler artifact.
- Docs site → Examples: documents · Articles and pages explain the example suite and language surface.
- VS Code ext → Examples: supports · The editor extension helps author the same .0 language used throughout the repo.
- Scripts → Native compiler: smokes · Automation covers native build, runtime, sanitizer, and sandbox checks.
- Scripts → Docs site: smokes · Automation includes browser and playground checks for the docs experience.
- Scripts → Conformance: runs · Scripts orchestrate conformance and contract validation workflows.
- CLI tests → Zero CLI: asserts · External tests verify the installed command interface.