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:
| Module | Question it owns |
|---|---|
ordinance | What does this contract say, and is it believable? |
survey | What does the code actually import? |
judge | Where do those two disagree? |
draft | What contract would this graph already obey? |
report | How 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
.zoneauthoring. - 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
zoningexecutable. - 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
zoningcan fail.
Functions§
- repo_
root - The enclosing worktree, so zoning works from source or from an installed binary.