Skip to main content

Crate zoning

Crate zoning 

Source
Expand description

zoning — declare where a package’s imports may go, then judge the real graph.

Most languages give you some boundary: Go has internal/, Python has a package graph, TypeScript has an exports map, Rust has pub(crate). Inside a single Zig package there is nothing at all — every import is a filesystem path, any file may name any other, and because analysis is lazy a genuine import cycle compiles clean. Architecture there is convention with nothing behind it.

A package opts in by writing <name>.zone at its own root, beside the manifest and every other file that configures it:

package acme {
    root   src
    facade root.zig
}

zones {                        // low to high; an import may not point up
    portal   portal.zig
    math     core/math/**
    parser   core/parser/**
}

seal core/parser through parser.zig     // enter a deep module by its door
keep surface/api.zig to root.zig        // and this region has a guest list

limit  reach to 5 hops
forbid cycles across directories

variance zone a.zig -> b.zig because "…and here is what retires it"

Seven laws, one exception mechanism, and every exception must say how it gets retired — a variance that stops matching is a hard failure, so paying the debt forces deleting the entry. Exception lists shrink instead of accreting.

Ten packages in one tree would be ten copies of the first four lines, so a file above them may claim them and say the shared part once:

workspace {
    member   libs/kernels/*
    root     src
    language zig
    facade   root.zig
    limit    reach to 1 hop
}

The link points down, the way [workspace] members and [tool.uv.workspace] do, and a member’s own contract keeps only what makes it different. Anything it declares wins, so inheritance can delete a line somebody had to repeat but never change the meaning of one they wrote.

§The shape of the tool

Five modules, each deep enough to be worth its boundary:

ModuleQuestion it owns
ordinanceWhat does this contract say, and is it believable?
surveyWhat does the code actually import?
judgeWhere do those two disagree?
draftWhat contract would this graph already obey?
reportHow does a person or a machine read the answer?

survey is where languages beyond Zig arrive: a survey::Dialect carries only what genuinely varies — extensions, how an import is spelled, whether a spec names something local, which modules the language hands out for free — while resolution, the graph, and all seven laws stay shared. Two dialects cannot disagree about what a cycle is. A contract names its own language, so one run judges a polyglot repository.

§As a library

use std::path::Path;
use zoning::{judge, ordinance::Ordinance, survey::{Ask, Survey}};

let zig = zoning::survey::dialect("zig").expect("the zig dialect ships in-tree");
let contract = Ordinance::read(Path::new("acme.zone"), zig)?;
let repo = Path::new(".");
let found = Survey::of(&Ask {
    repo_root: repo,
    module_root: &contract.module_root,
    exclude: &contract.exclude,
    dialect: contract.dialect,
    package: &contract.package,
    tracked: None,
});
let verdict = judge::judge(&found, &contract);
assert!(verdict.ok());

Modules§

draft
The inverse of judging: read a graph, write the contract it already obeys.
judge
The bench: six laws, judged against a resolved survey.
lsp
Language Server Protocol support for .zone authoring.
ordinance
The ordinance: a package’s declared import topology, as the laws will read it.
pattern
Path globs, with the semantics every other language’s linter already agreed on.
report
Turning a verdict into bytes somebody reads.
setup
Idempotent editor integration setup owned by the zoning executable.
spinner
A terminal progress indicator for work with no useful percentage.
survey
The survey: what the code actually does, before anyone judges it.

Enums§

Error
Every way running zoning can fail.

Functions§

repo_root
The enclosing worktree, so zoning works from source or from an installed binary.

Type Aliases§

Result
Shorthand for a Result whose error is Error.