//! Packaging-hygiene pins for the shipped source distribution.
//!
//! These are structural assertions over repository *files*, not over runtime
//! behavior: the release checklist items they encode (a license exists, the
//! license ships in the package, the scratch-file class stays ignored) are the
//! kind that rot silently because nothing executes them. Embedding the files
//! into the unit-test binary makes them compile-time facts instead — a
//! `zig build test` failure is the only way they can regress.
//!
//! The embedded files arrive as anonymous imports wired in build.zig's
//! `build_unit_test_module`, which builds a test-only module precisely so these
//! repo-root inputs never attach to the exported `zit` module: a consumer
//! fetching the package gets exactly `.paths`, and a public module depending on
//! a file outside `.paths` fails their build before it compiles a line.
//!
//! Deliberately NOT pinned here: the absence of any particular scratch file.
//! A comptime pin cannot assert a file is missing, and enumerating today's
//! stray filenames would be a list that goes stale. The versioned ignore-glob
//! asserted below is the durable mechanism for that class; `fossil extras`
//! before a commit is the operational check.
//!
//! Those two mechanisms trade against each other, deliberately: every pattern
//! added to the ignore-glob is a filename class `fossil extras` stops
//! reporting. `commit-description-*` is editor scratch that can only ever be
//! noise, so silencing it sharpens the check rather than blunting it — but the
//! next glob added deserves the same explicit judgment, not a reflex.
const std = @import("std");
const control_paths = @import("../control_paths.zig");
/// The repository root, wired in build.zig's `build_unit_test_module`. Only the
/// version-control pin below uses it; everything else here is a compile-time
/// fact about embedded file contents.
const repo_options = @import("repo_options");
/// The shipped files this module pins, embedded through build.zig's anonymous
/// imports (they live above `src/`, outside the module root).
const license_text = @embedFile("license_text");
const build_manifest = @embedFile("build_manifest");
const ignore_glob = @embedFile("ignore_glob");
const build_source = @embedFile("build_source");
/// `std.mem.indexOf` with a failure message that names what was missing and
/// where it was looked for. A bare `testing.expect(indexOf(..) != null)` prints
/// only `expected true`, which tells a future reader neither the file nor the
/// absent substring.
fn expect_contains(haystack: []const u8, needle: []const u8, where: []const u8) !void {
if (std.mem.indexOf(u8, haystack, needle) != null) return;
std.debug.print("\npackaging pin: {s} does not contain \"{s}\"\n", .{ where, needle });
return error.PackagingPinMissing;
}
/// True when `haystack` has a whole line equal to `needle`, ignoring leading
/// and trailing horizontal whitespace. An unanchored substring search would be
/// satisfied by a commented-out or partial line, which the consumer of the file
/// (fossil, here) does not honor.
fn contains_line(haystack: []const u8, needle: []const u8) bool {
var lines = std.mem.splitScalar(u8, haystack, '\n');
while (lines.next()) |line| {
if (std.mem.eql(u8, std.mem.trim(u8, line, " \t\r"), needle)) return true;
}
return false;
}
fn expect_line(haystack: []const u8, needle: []const u8, where: []const u8) !void {
if (contains_line(haystack, needle)) return;
std.debug.print("\npackaging pin: {s} has no line equal to \"{s}\"\n", .{ where, needle });
return error.PackagingPinMissing;
}
/// The interior of build.zig.zon's `.paths = .{ ... }` field, brace-matched.
/// Asserting against the whole manifest text would let a name that appears in a
/// comment, a dependency name, or any other field satisfy a `.paths` claim.
///
/// The matcher counts braces literally: it does not skip string literals or
/// `//` comments. A brace inside either, within the `.paths` block, would
/// mis-terminate the extracted region. That block holds only quoted path
/// entries today and a path containing a brace is not a thing we ship, so the
/// simpler matcher is the deliberate choice — stated here rather than assumed.
fn manifest_paths_block() ![]const u8 {
const marker_at = std.mem.indexOf(u8, build_manifest, ".paths") orelse {
std.debug.print("\npackaging pin: build.zig.zon has no `.paths` field\n", .{});
return error.PackagingPinMissing;
};
const open = std.mem.indexOfScalarPos(u8, build_manifest, marker_at, '{') orelse {
std.debug.print("\npackaging pin: build.zig.zon `.paths` has no opening brace\n", .{});
return error.PackagingPinMissing;
};
// Loop invariant carrying `depth`'s non-underflow: the scan starts *on* the
// opening brace, so the first iteration increments before any decrement can
// run. `indexOfScalarPos` guarantees it; assert rather than leave a future
// reader to re-derive it.
std.debug.assert(build_manifest[open] == '{');
var depth: usize = 0;
var i = open;
while (i < build_manifest.len) : (i += 1) {
switch (build_manifest[i]) {
'{' => depth += 1,
'}' => {
depth -= 1;
if (depth == 0) return build_manifest[open + 1 .. i];
},
else => {},
}
}
std.debug.print("\npackaging pin: build.zig.zon `.paths` block is unterminated\n", .{});
return error.PackagingPinMissing;
}
/// Repo-root entries build.zig may reference without being named in `.paths`,
/// because they feed the *test-only* module and never the exported `zit` one.
/// Anything reaching a shipped artifact must be in `.paths`; this is the
/// deliberate, reviewed set of exceptions.
/// Repo roots build.zig may embed WITHOUT their being shipped in `.paths`.
/// Each is test-only: consumed by a structural pin, never by the exported
/// `zit` module, so a consumer fetching the package never needs the files.
/// `www` holds the embedded documentation -- fossil's `/doc/<version>/<path>`
/// form, which the forge serves -- pinned by src/guards/reference_test.zig so a verb
/// cannot ship undocumented. Docs are for readers of the repository, not for
/// builders of the package, which is exactly why they are here and not there.
const test_only_roots = [_][]const u8{ ".fossil-settings", ".github", "www" };
/// Whether `haystack` contains `needle` starting at an identifier boundary —
/// the preceding byte must not itself be an identifier character. Plain
/// substring search finds `mod.addAnonymousImport` inside
/// `test_mod.addAnonymousImport`, which is the false positive this avoids.
///
/// `.` is deliberately NOT an identifier character here: build.zig reaches the
/// exported module as `env.mod` at nearly every use site, so treating the dot
/// as part of the identifier would make `env.mod.addAnonymousImport` — the form
/// a real regression would take — invisible to this matcher. Suffix matches
/// like `test_mod.` stay excluded by the explicit `_` term.
fn contains_at_word_start(haystack: []const u8, needle: []const u8) bool {
var scan: usize = 0;
while (std.mem.indexOfPos(u8, haystack, scan, needle)) |hit| {
scan = hit + 1;
if (hit == 0) return true;
const prev = haystack[hit - 1];
const is_ident = std.ascii.isAlphanumeric(prev) or prev == '_';
if (!is_ident) return true;
}
return false;
}
/// Iterates the `b.path("...")` literals build.zig declares, yielding each
/// referenced path. Two pins consume it — the `.paths` pin (does this ship?) and
/// the version-control pin (does this exist for anyone else?) — and a single
/// scanner is what keeps them asking about the same set of files.
///
/// Text matching, as everywhere in this module: a path assembled at runtime
/// rather than written as a literal is invisible here. build.zig writes them all
/// literally today.
const BuildPathScan = struct {
const marker = ".path(\"";
scan: usize = 0,
fn next(self: *BuildPathScan) !?[]const u8 {
const hit = std.mem.indexOfPos(u8, build_source, self.scan, marker) orelse return null;
const start = hit + marker.len;
const end = std.mem.indexOfScalarPos(u8, build_source, start, '"') orelse {
// Unreachable while build.zig compiles — an unterminated string
// literal would not survive the build that produced this test. Fail
// loudly anyway: returning null here would silently truncate the
// scan, and a truncation after a few passing checks slips past the
// vacuity guards its callers rely on.
std.debug.print("\npackaging pin: build.zig has an unterminated b.path(\"...) literal " ++
"at byte offset {d}; the scan cannot continue\n", .{start});
return error.PackagingPinMissing;
};
self.scan = end + 1;
return build_source[start..end];
}
};
/// The first path component of a build-graph path (`src/root.zig` → `src`);
/// `.paths` names roots, not individual files under them.
fn root_component(path: []const u8) []const u8 {
const slash = std.mem.indexOfScalar(u8, path, '/') orelse return path;
return path[0..slash];
}
test "LICENSE is BSD-2-Clause and carries the project copyright" {
try expect_contains(license_text, "BSD 2-Clause License", "LICENSE");
try expect_contains(license_text, "Copyright (c) 2026, Daniel Mestas", "LICENSE");
// The two substantive clauses and the warranty disclaimer, so a truncated
// or placeholder LICENSE cannot pass.
try expect_contains(license_text, "Redistributions of source code must retain", "LICENSE");
try expect_contains(license_text, "Redistributions in binary form must reproduce", "LICENSE");
try expect_contains(license_text, "AS IS", "LICENSE");
}
test "LICENSE ships in the package: build.zig.zon .paths names it" {
// A package consumer fetching the tarball gets exactly `.paths`; a license
// that exists in the repo but is absent from `.paths` does not ship. Scoped
// to the `.paths` block so the bare word LICENSE elsewhere in the manifest
// cannot stand in for the entry.
try expect_contains(try manifest_paths_block(), "\"LICENSE\"", "build.zig.zon `.paths`");
}
test "every repo-root path build.zig embeds is named in .paths" {
// The negative-space pin for the packaging class as a whole. A `b.path(...)`
// in build.zig reaching a file outside `.paths` builds fine in this tree and
// fails for every consumer fetching the package, with a cache-hash error
// naming the file but not the cause. Enumerating build.zig's own path
// references keeps the two files honest with each other; without this pin
// only the LICENSE entry was ever asserted.
const paths_block = try manifest_paths_block();
var scan: BuildPathScan = .{};
var checked: usize = 0;
while (try scan.next()) |path| {
const root = root_component(path);
for (test_only_roots) |allowed| {
if (std.mem.eql(u8, root, allowed)) break;
} else {
checked += 1;
var quoted_buf: [256]u8 = undefined;
const quoted = std.fmt.bufPrint("ed_buf, "\"{s}\"", .{root}) catch {
std.debug.print("\npackaging pin: build.zig references a path whose root component " ++
"is longer than {d} bytes (\"{s}\"); widen quoted_buf\n", .{ quoted_buf.len, root });
return error.PackagingPinMissing;
};
try expect_contains(paths_block, quoted, "build.zig.zon `.paths`");
}
}
// A scan that matched nothing would pass vacuously; build.zig references
// src/root.zig, src/main.zig, LICENSE and build.zig.zon at minimum.
if (checked < 4) {
std.debug.print("\npackaging pin: only {d} b.path(...) references found in build.zig; " ++
"the scan pattern has drifted from the source\n", .{checked});
return error.PackagingPinMissing;
}
}
/// True when `listing` — one path per line, as `fossil ls` prints it — has a
/// line naming exactly `path`.
fn listing_names(listing: []const u8, path: []const u8) bool {
var lines = std.mem.splitScalar(u8, listing, '\n');
while (lines.next()) |line| {
if (std.mem.eql(u8, std.mem.trim(u8, line, " \t\r"), path)) return true;
}
return false;
}
test "every path build.zig embeds is version-controlled" {
// The pin the `.paths` check above cannot make. `test_only_roots` grants a
// *packaging* exemption — "this file feeds the test module, so it need not
// ship in the tarball" — and nothing stopped that from being read as a
// *tracking* exemption too. It is not one: a build input that exists on one
// developer's disk and in no commit makes every clean checkout fail to
// build, with a `failed to check cache: ... FileNotFound` error that names
// the file but not the cause. That happened to .github/workflows/ci.yml.
//
// "Tracked" is a property of the repository, so unlike the rest of this
// module the check has to ask fossil rather than read an embedded file.
// `fossil ls` lists the checkout's files including ones added but not yet
// committed, which is what makes this usable as a pre-commit gate: the
// local commit guard runs `zig build test`, so an unadded build input fails
// the commit that would have introduced it.
//
// The check skips rather than fails where it cannot run — no fossil on
// PATH, or a working tree that is not a fossil checkout (GitHub Actions
// checks out git, so this pin is a local gate by construction). A skip is
// honest about what was verified; failing there would only teach people to
// ignore it.
// One constant, used by both the limit and the message that reports it
// breaching: two literals would let the diagnostic name a bound that is not
// the bound in force.
const listing_limit = 4 << 20;
const listing = blk: {
const result = std.process.run(std.testing.allocator, std.testing.io, .{
.argv = &.{ "fossil", "ls" },
.cwd = .{ .path = repo_options.root },
.stdout_limit = .limited(listing_limit),
}) catch |err| switch (err) {
// A listing larger than the limit is not "fossil is unavailable" —
// it is this check's own bound being wrong, and collapsing it into
// the skip below would turn the pin off permanently with no
// diagnostic. At 73 tracked files the headroom is ~1000x, so this
// is a tripwire rather than an expected path.
error.StreamTooLong => {
std.debug.print("\npackaging pin: `fossil ls` produced more than {d} bytes; " ++
"the repository outgrew this check's stdout_limit. Raise it — do not " ++
"let the version-control pin skip itself into silence.\n", .{listing_limit});
return error.PackagingPinMissing;
},
// The legitimate skip, and only it: no `fossil` on PATH, or a root
// that is not a directory. Those are the two ways "this machine
// cannot answer the question" actually presents (GitHub Actions
// checks out git, so this pin is a local gate by construction).
error.FileNotFound, error.NotDir => return error.SkipZigTest,
// Anything else is a fault in the check or the machine running it —
// OutOfMemory, a failed fork, a permissions problem. Folding those
// into the skip would disable the version-control pin exactly as
// quietly as a missing binary does, which is the failure mode the
// StreamTooLong arm above exists to refuse.
else => {
std.debug.print("\npackaging pin: `fossil ls` could not be run: {s}. That is not " ++
"\"fossil is unavailable\" — it is a fault in this check or the machine " ++
"running it, and skipping on it would turn the version-control pin off " ++
"silently.\n", .{@errorName(err)});
return error.PackagingPinMissing;
},
};
std.testing.allocator.free(result.stderr);
const clean = switch (result.term) {
.exited => |code| code == 0,
else => false,
};
if (!clean) {
std.testing.allocator.free(result.stdout);
return error.SkipZigTest;
}
break :blk result.stdout;
};
defer std.testing.allocator.free(listing);
// Vacuity guard, and the "is this really a checkout?" test in one: build.zig
// is the file this scan reads, so a listing without it is not this repo.
if (!listing_names(listing, "build.zig")) return error.SkipZigTest;
var scan: BuildPathScan = .{};
while (try scan.next()) |path| {
if (listing_names(listing, path)) continue;
std.debug.print("\npackaging pin: build.zig reads \"{s}\", which fossil does not track. " ++
"Every clean checkout of this commit fails to build with a cache error naming " ++
"that file. Run `fossil add {s}` (and note that bare `fossil extras` omits " ++
"dotfiles — use `fossil extras --dotfiles`).\n", .{ path, path });
return error.PackagingPinMissing;
}
}
test "the exported zit module takes no anonymous imports" {
// The pin above allowlists `.fossil-settings` by root component, so it
// cannot by itself catch the original blocker recurring: those embeds being
// re-attached to the exported `zit` module (`mod` in build.zig) instead of
// the test-only one. That shape builds green here and breaks every consumer.
// Pinning the attachment site directly is what closes the gap.
//
// What the matcher does and does not see, precisely: it fires on
// `mod.addAnonymousImport` preceded by a non-identifier byte, which covers
// both the bare receiver and the qualified `env.mod.` form build.zig
// actually uses at nearly every site. It stays silent if `mod` is renamed
// in build.zig, so pair it with the clean-`.paths`-copy build check when
// touching the module wiring.
//
// It can also misfire: a build.zig *comment* mentioning
// `mod.addAnonymousImport` trips it, since this is text matching, not
// parsing. That failure is loud and names the file, so diagnosing it costs
// one look at build.zig — an acceptable trade for a pin that would
// otherwise need a Zig parser to be exact.
if (contains_at_word_start(build_source, "mod.addAnonymousImport")) {
std.debug.print("\npackaging pin: build.zig attaches an anonymous import to the exported " ++
"`zit` module; repo-root embeds belong on the test-only module " ++
"(build_unit_test_module) or consumers fetching the package fail on " ++
"a file outside `.paths`\n", .{});
return error.PackagingPinMissing;
}
}
test ".paths ships the RFCs without dragging in the working-docs directory" {
// `.paths` names directories, and a Zig package is cut from the *working
// tree* — the fossil ignore-glob does not govern it. So a bare "docs" entry
// ships whatever happens to sit under docs/ at package time, including the
// ignore-glob'd docs/plans/*.md working documents, which are internal and
// must never leave the repository.
//
// Naming docs/rfcs directly is also what the repo convention already says
// (0ad7fa92c6: "docs/ is for the RFCs only"); this pin makes the manifest
// state that convention instead of relying on docs/ happening to stay clean.
const paths_block = try manifest_paths_block();
try expect_contains(paths_block, "\"docs/rfcs\"", "build.zig.zon `.paths`");
// Entries are one-per-line and trailing-comma'd; a bare "docs" line is the
// regression this pin exists to catch.
if (contains_line(paths_block, "\"docs\",")) {
std.debug.print("\npackaging pin: build.zig.zon `.paths` names bare \"docs\", which ships " ++
"the ignore-glob'd docs/plans working documents to package consumers; " ++
"name \"docs/rfcs\" instead\n", .{});
return error.PackagingPinMissing;
}
}
test "the commit-description scratch-file class is ignored" {
// `commit-description-<hex>.txt` files are editor leftovers from
// `fossil commit`; one of them was committed-adjacent at the repo root
// before 0.1.0. The versioned glob keeps the whole class out of
// `fossil extras` noise and out of an accidental `addremove`.
try expect_line(ignore_glob, "commit-description-*", ".fossil-settings/ignore-glob");
}
test "the editor-tooling classes are ignored" {
// Two working-tree classes that must never enter an append-only history.
//
// `.agent-config/` accumulates per-session editor tooling traces at the
// repo root. Being dotfiles, they are invisible to a bare `fossil extras`
// — it skips dotfiles unless `--dotfiles` is passed — so for most of this
// repository's life they were held out of commits by that default alone
// and not by any rule. That is an accident, not a guard: one
// `fossil addremove --dotfiles`, or any tool that does not share fossil's
// default, lands the whole directory permanently. The glob makes the
// intent explicit and survives a change to that default.
//
// `CLAUDE.local.md` carries this repository's working rules. It is
// deliberately uncommitted — it is checkout-local operator configuration,
// not a project artifact — and the same reasoning that keeps
// `docs/plans/*` out applies to it.
try expect_line(ignore_glob, ".agent-config/*", ".fossil-settings/ignore-glob");
try expect_line(ignore_glob, "CLAUDE.local.md", ".fossil-settings/ignore-glob");
}
test "the crash-leftover working files are ignored" {
// Two dotfile classes a run can leave behind when it dies partway. Both are
// invisible to a bare `fossil extras` (it skips dotfiles), which is exactly
// why they need a glob rather than vigilance.
//
// `.zit-dst-checkout-ws/` is the process directory `zig build dst` makes
// for the crash-recovery sweeps' throwaway workspaces (`src/dst.zig`,
// `checkout_root_name`). It is created at run start and removed by a
// `defer` at run end, so it exists only while a sweep is in flight — but a
// killed or crashed run leaves the whole tree, `.zit` stores and all.
//
// `.zit-tmp-pack` (`src/extras.zig`, `pack_tmp_filename`) is the fixed-name
// temp `pack` and `shun --force` write the new generation into before the
// atomic rename. The fixed name is deliberate — it is what stops temps
// accumulating, since the next run truncates it — but a run that dies
// between create and rename leaves one beside `.zit`.
try expect_line(ignore_glob, ".zit-dst-checkout-ws/*", ".fossil-settings/ignore-glob");
try expect_line(ignore_glob, ".zit-tmp-*", ".fossil-settings/ignore-glob");
// `.zit-cache/checkpoint` (`src/checkpoint.zig`) is the durable prefix
// checkpoint sidecar — advisory, regenerable, and pinned BEFORE any code
// could create it: fossil is append-only, so a sidecar committed once is
// committed forever.
try expect_line(ignore_glob, ".zit-cache/checkpoint", ".fossil-settings/ignore-glob");
}
test "every advisory and scratch registry entry has an ignore-glob line" {
// The registry is the authority on which names zit strews beside `.zit`;
// this pin makes "added a disposable file class, forgot the glob" a test
// failure instead of a stranger's surprise. Authoritative names are
// deliberately absent: those are the checkout's own state, and hiding
// them from fossil would be hiding the working copy from its VCS.
inline for (control_paths.reserved) |entry| {
switch (entry.tier) {
.advisory, .scratch => {
const exact = contains_line(ignore_glob, entry.name);
const starred = contains_line(ignore_glob, entry.name ++ "*");
if (!exact and !starred) {
std.debug.print("\nregistry entry \"{s}\" ({s}) has no ignore-glob line\n", .{ entry.name, @tagName(entry.tier) });
return error.PackagingPinMissing;
}
},
.authoritative => {},
}
}
}