Zig 0.16 · v0.0.2 preview

Architecture and design boundaries

ArchUnitZig isolates language-specific extraction from pure graph projection and policy logic. The public facade assembles domains; internal domains do not reach back through it.

One directional pipeline

Zig project
    ↓
discovery → AST/token extraction → path & module resolution → normalized Graph
                                                              ↓
                           matching → projection → domain policy → Violation values
                                                              ↓
                                        testing / reports / metrics exporters

The extractor is the Zig boundary. Pattern matching, cycle detection, projections, layer and slice policies, and rendering operate on owned data with caller-supplied allocation.

Production module boundaries

root.zig
  ├── files ─────┐
  ├── layers ────┤
  ├── slices ────┼──→ common
  ├── graph ─────┤
  ├── metrics ───┤
  └── testing ───┘

common owns extraction, matching, projection, violations, errors, check contracts, and logging. Each policy domain depends on common but not on another policy domain. Testing formats common/domain results. root.zig is the public facade, and production internals never import it.

The normalized graph contract

Graph identifiers are project-relative with / separators. Every discovered Zig file receives a synthetic self-edge so import-free files remain nodes. Equal source/target pairs merge their import kinds, classifications, availability facts, and unique locations. Graph and edge clones own independent storage.

Projection keeps raw evidence

A map callback turns raw edges into optional borrowed labels. Projection immediately clones labels and underlying edges, merges equal label pairs, and sorts results. Node projections exclude external targets by default while keeping the internal source's outgoing evidence. Cycle results are owned, closed directed paths.

Policy and presentation do not collapse together

Rules return an owned closed union of violation facts. The kernel does not choose final prose. The testing/report boundary formats every known variant exhaustively, which makes a new policy evidence shape a deliberate cross-module change instead of a hidden string convention.

Executable architecture documentation

The repository's dogfood suite imports only the public archunit package and analyzes src/** as a consumer would. It enforces common/domain separation, the testing boundary, facade direction, named layers, folder ownership, and production acyclicity. Every rule has a deliberately stricter negative control that proves concrete evidence reaches the formatter.

Review the rationale

The repository keeps its detailed trade-offs in docs/decisions.md and its current boundary description in docs/architecture.md. The API reference is generated by Zig from the same public module compiled by tests.