notes · · 7 min · updated 2026-10-27

Zig Under the Microscope: Selected Results from a 67-Tool AST Suite on the Self-Hosted Compiler and Standard Library

Historical Zig compiler and standard library analysis with prod-code: source distribution, x86_64 codegen clones, errdefer patterns, and a remote ZLS refactoring example. Zig is now hosted on Codeberg.

On this page · 4 sections
  1. Subsystem Architecture, Self-Hosted Compiler, and Standard Library Topology
  2. Code Generation Clone Groups and x86_64 Instruction Selection Duplication
  3. Structural AST Patterns: Error Propagation and Deterministic Deferral
  4. Remote Refactoring Proposal and a Cluster-Backed ZLS Check

First published on 2026-09-30. The measurements reported in this article are historical and have not been re-run for this revision.

Systems programming languages demand precise compiler behavior. Zig is a general-purpose language and toolchain with comptime execution, explicit error handling, and allocator-based memory management. The project moved from GitHub to Codeberg; its canonical repository is codeberg.org/ziglang/zig.

The self-hosted Zig compiler, code-generation backends, standard library, and tests provide varied inputs for AST parsing, duplicate detection, and refactoring proposals. We used selected operations from prod-code’s 67-tool suite against a Zig checkout identified in the original post as ziglang/zig, with analysis and ZLS diagnostics running remotely. The local client still handles synchronization, requests, and results.

The command excerpts below are historical observations retained from the original publication. No pinned upstream commit or complete measurement environment is recorded here, so counts, paths, line numbers, and scan durations are snapshot-specific and have not been remeasured for this update. The excerpts cover selected operations from the 67-tool suite, not verification of every tool. A cycle-free extracted module graph does not establish all source-level or external dependency relationships; clone counts do not establish runtime performance. Analyzer diagnostics are not a compiler build or test result.

$ git ls-files '*.zig' | wc -l
2950
$ git ls-files -z '*.zig' | xargs -0 wc -l | tail -n 1
1357479 total
$ git ls-files | awk -F. '{if (NF>1) print $NF}' | sort | uniq -c | sort -nr | head -n 6
11492 h
 2950 zig
 2653 def
 2322 c
  216 s
  209 cpp

The captured inventory reports 1,357,479 Zig lines in 2,950 files and 11,492 headers. It does not establish exhaustive semantic coverage or local hardware usage.

Subsystem Architecture, Self-Hosted Compiler, and Standard Library Topology

The Zig repository contains three primary architectural layers: the self-hosted compiler frontend and backend (src/), the batteries-included standard library (lib/std/), and the compiler runtime library (lib/compiler/), along with comprehensive behavior, safety, and linking test suites (test/). Measuring the line distribution across these subsystems reveals the structural balance of the project:

$ for dir in src lib/std lib/compiler test; do
    echo -n "$dir: files="; git ls-files "$dir/*.zig" "$dir/**/*.zig" | wc -l;
    echo -n "$dir: lines="; git ls-files -z "$dir/*.zig" "$dir/**/*.zig" | xargs -0 wc -l | tail -n 1;
  done
src: files=168
src: lines=517489 total
lib/std: files=550
lib/std: lines=435138 total
lib/compiler: files=110
lib/compiler: lines=125865 total
test: files=1492
test: lines=133047 total

The self-hosted compiler core accounts for 517,489 lines across 168 files, encapsulating tokenizer routines, AST generation (AstGen.zig), semantic analysis (Sema.zig), intermediate representations (Air.zig and Lir.zig), register allocation, and machine-code emission. The standard library comprises 435,138 lines across 550 files, providing OS-agnostic IO, memory allocators, hash maps, cryptographic primitives, and formatters.

The build configuration is anchored by build.zig (1,471 lines) and build.zig.zon. We ran prod-code dependencies across the tree to verify package topology:

$ prod-code dependencies
⚡ prod-code Architecture & Dependency Graph Report
────────────────────────────────────────────────────
Scope: modules | Nodes: 2 | Dependencies: 2

✓ Zero circular dependencies detected. Architecture graph is a clean DAG.

The captured dependency scan reports two nodes and no cycles. That limited extraction does not establish a complete compiler or build dependency graph.

Code Generation Clone Groups and x86_64 Instruction Selection Duplication

Instruction selection and machine-code generation frequently require repetitive operand encoding logic across hundreds of assembly opcodes. We ran prod-code duplicates across the repository to locate structural clone groups:

$ prod-code duplicates --path /tmp/zig-eval --min-lines 10
⚡ prod-code Clone & Duplication Harvester Report
────────────────────────────────────────────────────
Files Scanned: 5488 | Lines: 1569444 | Clone Groups: 20 | Duplication: 7.0%

Discovered Clone Groups:

[Clone Group #37663] 10 lines | 2052 occurrences (Type-2 (Parameterized))
  • Occurrence 1: src/codegen/x86_64/CodeGen.zig:2398-2407
  • Occurrence 2: src/codegen/x86_64/CodeGen.zig:2431-2440
  • Occurrence 3: src/codegen/x86_64/CodeGen.zig:2513-2522
  • Occurrence 4: src/codegen/x86_64/CodeGen.zig:2546-2555
  • Occurrence 5: src/codegen/x86_64/CodeGen.zig:2579-2588
  ...

The clone report lists Clone Group #37663 as a candidate group of 2,052 occurrences of a 10-line Type-2 parameterized pattern; the five occurrences it prints all lie in src/codegen/x86_64/CodeGen.zig, and where the other 2,047 lie is not shown. Lowering instructions in an x86_64 backend generally involves repetitive register constraint checks, memory operand validation, and immediate bitwidth truncation, but whether this group is such code is not shown.

The captured scan reports 7.0% duplication across 1,569,444 lines. The excerpt prints file and line ranges only, no code, so what the repeated pattern does is not visible in it, and the report does not measure dispatch overhead or compiler throughput.

Correction, 2026-10-27. As published on 2026-09-30, this section placed the whole 2,052-member cluster “in src/codegen/x86_64/CodeGen.zig”; the revision of 2026-10-01 added that repeated instruction-lowering patterns “are visible in the examples”. The excerpt shows a total and five locations in that file, without code bodies. The count stands as reported; the placement of every member and the claim that the pattern’s meaning is visible are withdrawn.

Structural AST Patterns: Error Propagation and Deterministic Deferral

Zig uses error union types (!T), try, and scope-based cleanup through defer and errdefer. We deployed prod-code structural-search to inspect how the compiler frontend utilizes these primitives:

$ prod-code structural-search --path src/main.zig 'try $A'
⚡ prod-code Structural AST Search: `try $A`
────────────────────────────────────────────────────
488 match(es) in 1 file(s) (1 scanned in 7612.65ms)

  • src/main.zig:190:18  try process
    └─ [$A = process]
  • src/main.zig:200:25  try fs
    └─ [$A = fs]
  • src/main.zig:233:9   try env_map
    └─ [$A = env_map]
  • src/main.zig:241:35  try arena
    └─ [$A = arena]
  ... and 463 more match(es)

The search reports 488 try $A matches in src/main.zig. The excerpt is abridged: it prints four matches and a line for 463 more, which accounts for 467, so 21 matches are not represented in what was published. A match is a try expression, not necessarily a distinct call site, and the four shown bind $A only to a leading identifier (process, fs, env_map, arena), so the excerpt does not show which errors they propagate.

Correction, 2026-10-27. As published on 2026-09-30, this paragraph called the 488 matches “call sites” that propagate CLI parsing, filesystem configuration and target setup errors. The excerpt above is kept exactly as published; its rows add up to 467, not 488, and its matches are try expressions whose bound text does not show what they propagate. The excerpt is now labelled abridged; the call-site classification and the description of what they propagate are withdrawn.

Next, we searched across the entire compiler frontend (src/) for Zig’s specialized error-unwinding statement errdefer $A:

$ prod-code structural-search --path src/ 'errdefer $A'
⚡ prod-code Structural AST Search: `errdefer $A`
────────────────────────────────────────────────────
480 match(es) in 56 file(s) (174 scanned in 19675.12ms)

  • src/Air/Liveness.zig:159:5  errdefer gpa
    └─ [$A = gpa]
  • src/Compilation.zig:511:9   errdefer gpa
    └─ [$A = gpa]
  • src/Compilation.zig:1189:17 errdefer {
    └─ [$A = {
            for (file_names.values()) |file_name| gpa.free(file_name);
            file_names.deinit(gpa);
        }]

Across 56 files in src/, the captured search reports 480 errdefer matches. These identify cleanup paths; they do not prove the absence of leaks. The excerpt shows two single-identifier bindings, where $A is gpa, the allocator, rather than a deallocation call, and one multiline block with nested iteration whose body does show free and deinit calls. It contains no errdefer arena match. It illustrates metavariable binding on these three rows, not accurate capture of the deferred statements.

Correction, 2026-10-27. As published on 2026-09-30, this sentence said the query “accurately captured” simple identifier deallocations, errdefer gpa and errdefer arena. An allocator identifier is not a deallocation, no arena row appears in the excerpt, and the two gpa rows show only the leading identifier of the deferred expression. The accuracy claim and the errdefer arena example are withdrawn.

The original post also reported 4,279 assert(...) calls (2,203 in compiler src/ and 2,076 in lib/std/). The command and output behind that count are not shown, so it is an author-reported figure. An assertion checks its invariant only on paths that actually execute, and only in build modes with runtime safety; the count says how many assertions are written, not how much runtime validation takes place.

Correction, 2026-10-27. As published on 2026-09-30, this paragraph said the count showed defensive programming “enforced systematically” with “deep runtime self-validation during debug builds”. No census method or output is published, and Zig’s std.debug.assert, as cited by the archive review at 0.15.1, is if (!ok) unreachable;, checked at runtime only where safety checks are enabled. The numbers are kept as author-reported; the systematic and deep-validation conclusions are withdrawn.

Remote Refactoring Proposal and a Cluster-Backed ZLS Check

Refactoring systems software ultimately needs a compiler build and tests: an extracted function must match calling conventions, parameter typing, and return semantics without introducing subtle lifetime or allocation defects. The section below shows a dry-run proposal and an analyzer report, not that verification.

In lib/std/ascii.zig, the character classification and conversion functions perform bitwise manipulation. In toUpper, the case-conversion mask calculation operates directly on byte values:

pub fn toUpper(c: u8) u8 {
    const mask = @as(u8, @intFromBool(isLower(c))) << 5;
    return c ^ mask;
}

We used prod-code extract-function to propose isolating the bitmask logic into a dedicated helper caseMask, as a dry run, with the Zig Language Server (zls 0.16.0, as the article reports) running on our remote cluster checking the result:

$ prod-code extract-function --name caseMask --to 187:1 lib/std/ascii.zig 186 5
`fn caseMask` extracted (lib/std/ascii.zig); the selection now reads `const mask = caseMask(c);`
- no other place in the file has the selection's text

--- a/lib/std/ascii.zig
+++ b/lib/std/ascii.zig
@@ -184,4 +184,9 @@
 /// Uppercases the character and returns it as-is if already uppercase or not a letter.
-pub fn toUpper(c: u8) u8 {
+fn caseMask(c: u8) u8 {
     const mask = @as(u8, @intFromBool(isLower(c))) << 5;
+    return mask;
+}
+
+pub fn toUpper(c: u8) u8 {
+        const mask = caseMask(c);
     return c ^ mask;

the analyzer accepts the result: 0 errors

nothing was written; pass `apply: true` to make this edit

The refactoring pipeline recognized primitive scalar types (u8), deduced the parameter type c: u8 and return type u8, synthesized the proper Zig function header fn caseMask(c: u8) u8, and updated the call site to const mask = caseMask(c);. The excerpt reports 0 errors from the remote analyzer on this dry run. ZLS documents its semantic analysis as incomplete, and the excerpt does not show the paired Zig version, the diagnostic settings or the diagnostic exchange, so this is an analyzer-reported zero, not a semantic verification. No compiler build, tests, or local CPU measurement is shown.

The proposal also has a defect the original post did not point out: the diff leaves toUpper’s doc comment, “Uppercases the character and returns it as-is if already uppercase or not a letter.”, directly above fn caseMask, which returns a mask of 0 or 32, not a character, and leaves toUpper without its documentation. Applied as shown, the helper would carry the wrong comment.

Correction, 2026-10-27. As published on 2026-09-30, this section described the proposal as verified by ZLS 0.16.0 and said the analyzer “confirmed” 0 errors. The ZLS 0.16.0 README, as cited by the archive review, describes comptime and semantic analysis as work in progress; zero reported diagnostics do not establish compiler acceptance or semantic correctness. The section is narrowed to a dry-run proposal with zero analyzer-reported errors, and the misplaced doc comment in the shown diff is now called out. The excerpt is kept exactly as published.

The captured examples demonstrate selected query and refactoring proposals on Zig syntax. They do not verify every construct or all 67 tools.

Correction, 2026-10-27. As published on 2026-09-30, the title read “What 67 Remote AST Tools Found Inside the Self-Hosted Compiler and Standard Library”, which implies every tool in the suite contributed a finding. The article shows selected operations from the 67-tool suite; the title now says so. The publication date and the reported results are unchanged.

Use cleanup counts to find review sites; use compiler builds and tests to assess the proposed changes.

Cite this article
Citation
Alexander Panasenko (2026-09-30). Zig Under the Microscope: Selected Results from a 67-Tool AST Suite on the Self-Hosted Compiler and Standard Library. https://prod.codes/blog/zig-under-the-microscope-67-ast-tools/