Practical workflows

Run these examples from the repository root. Build with go build -o bin/zy.exe . on Windows, or replace bin/zy.exe below with go run . while developing. The examples read local files and report results without applying network changes.

Network inventory checker

.\bin\zy.exe examples/workflows/network-inventory.zy examples/workflows/fixtures/inventory-valid.json
.\bin\zy.exe examples/workflows/network-inventory.zy examples/workflows/fixtures/inventory-invalid.json --json

Input is an object with allowed_cidrs (nonempty list of IPv4 CIDR strings) and devices (list of objects with nonempty name and dotted IPv4 ip). Every device must belong to an allowed network.

The valid fixture prints a PASS line and exits 0. The invalid fixture returns two violations: /devices/0/ip fails address-membership, and /devices/1/ip fails ip-format. Each includes a suggested correction. It exits 1.

Subnet planner

.\bin\zy.exe examples/workflows/subnet-planner.zy examples/workflows/fixtures/planner-valid.json
.\bin\zy.exe examples/workflows/subnet-planner.zy examples/workflows/fixtures/planner-invalid.json --json

Input supplies an IPv4 parent CIDR and requests, each with a unique nonempty name and integer prefix. Blocks are allocated largest first to avoid fragmentation; results remain in request order. No partial allocations are reported after a validation failure.

Expected successful allocations:

guests: 10.20.0.64/27
apps: 10.20.0.0/26
management: 10.20.0.96/28

The invalid fixture requests two /24 blocks inside one /24 and fails the /requests capacity rule. The allocator also rejects prefixes outside the parent bounds and guarantees no overlap between successful allocations.

Service configuration validator

.\bin\zy.exe examples/workflows/config-validator.zy examples/workflows/fixtures/config-valid.json
.\bin\zy.exe examples/workflows/config-validator.zy examples/workflows/fixtures/config-invalid.json --json

The example validates a nonempty name, one of three sample region values, integer port in 1–65535, integer replicas in 1–100, and a valid service_ip inside allowed_cidr. These are example policies; adjust them for your environment.

The invalid fixture produces four violations at /region, /port, /replicas, and /service_ip and exits 1.

Reporting contract

Default output is a concise human-readable report. With --json, stdout contains one compact JSON document with workflow, source, ok, and violations. Each violation has path (a JSON pointer into the input), rule, and an actionable message. Planner reports also include allocations.

Successful validation exits 0. A report with violations exits 1 and writes a source-aware summary to stderr. File-access, malformed-JSON, or resource-limit failures exit 1 with a diagnostic on stderr; they may occur before a report exists. Invalid interpreter invocation exits 2.

Six valid/invalid fixtures are in examples/workflows/fixtures. Automated tests check both output modes, exit codes, violation counts, allocation results, and deterministic JSON. User trials with at least three network engineers/operators are still pending; passing tests does not establish adoption or usability.