1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
//! **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:
//!
//! ```text
//! 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:
//!
//! ```text
//! 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
//!
//! ```no_run
//! 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());
//! # Ok::<(), zoning::ordinance::Fault>(())
//! ```
pub use ;
use ;
/// The enclosing worktree, so zoning works from source or from an installed binary.
///
/// Falls back to `start` when there is no repository above it: a directory with a
/// contract in it is still worth judging, and refusing to run outside version control
/// would make the tool useless in exactly the sandboxes people test it in.