Report the municipality behind a CEP that does not existHEADv0.2.0main

A CEP that fails to resolve is rarely a random number. It is almost always
someone who knows the city and guessed the digits, and the classic guess is
the -000 that 957 municipalities never received. The API now says so: a 404
carries an optional faixa block naming the municipality the number would have
belonged to, and answering "no such CEP in Areal/RJ, which has 118 of them" is
a great deal more useful than "not found".

It arrives through Diagnostics, which is where every other detail a Zig error
tag cannot carry already travels, and it is read with diag.faixa(). Like
message(), it lives in a fixed buffer inside the value and allocates nothing,
so no caller has to learn a new deinit for it.

The lookup still fails. faixa is context for the error, never an address, and
cep_ini/cep_fim are the smallest and largest CEP that actually exist there
rather than the bounds the Correios publish — for Areal the DNE's own start is
25845000, which is exactly the CEP that failed. The range is also sparse, 118
CEPs over ~4,900 numbers, so ceps is the count and the pair must never be
presented as a list. The doc comments and the README say all three, because
this field is easy to misread as a success.

Parsing is deliberately inert: a faixa that is missing, null, not an object,
nameless or oversized yields null, and an unreadable body is skipped. Nothing
about this field may promote a clean not-found into a parse failure.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/main.zig b/src/main.zig
index 6bb9777..77baae8 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -79,6 +79,13 @@ pub fn main(init: std.process.Init) !u8 {
     if (ceps.items.len == 1) {
         var address = client.lookup(ceps.items[0], .{ .diagnostics = &diag }) catch |err| {
             try out.print("{s}: {t}: {s}\n", .{ ceps.items[0], err, diag.message() });
+            // Not an address — the lookup failed. Only where the number would
+            // have landed, which is usually the useful thing to say back.
+            if (diag.faixa()) |faixa| {
+                try out.print("  would be in {s}/{s}, which has {d} CEPs between {s} and {s}\n", .{
+                    faixa.localidade, faixa.uf, faixa.ceps, faixa.cep_ini, faixa.cep_fim,
+                });
+            }
             return 1;
         };
         defer address.deinit(gpa);