// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>
// SPDX-License-Identifier: MIT

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Email messages, which this library reads and writes but deliberately
    // does not parse: <https://git.jcollie.dev/jeff/zig-mime>. A maildir is a
    // naming convention over a directory, and what it stores is somebody
    // else's subject.
    const mime = b.dependency("mime", .{
        .target = target,
        .optimize = optimize,
    });

    const mod = b.addModule("maildir", .{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .imports = &.{.{ .name = "mime", .module = mime.module("mime") }},
    });

    // The command-line tool, which exists to show what the library looks like
    // from outside and to give the NixOS tests a second program to point at a
    // maildir Dovecot is also looking at.
    const exe = b.addExecutable(.{
        .name = "zig-maildir",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "maildir", .module = mod },
                .{ .name = "mime", .module = mime.module("mime") },
            },
        }),
    });
    b.installArtifact(exe);

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    run_cmd.stdio = .inherit;
    if (b.args) |args| run_cmd.addArgs(args);
    const run_step = b.step("run", "Run the command-line tool");
    run_step.dependOn(&run_cmd.step);

    // A test executable covers one module, so each needs its own. Missing one
    // out would not fail: its tests would simply never run.
    const test_step = b.step("test", "Run tests");
    for ([_]*std.Build.Module{ mod, exe.root_module }) |m| {
        test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = m })).step);
    }

    // What the library does to a real directory: delivery, flags, folders and
    // the quota ledger, all against a temporary maildir. A module of its own
    // so that `zig build test` runs them and a consumer never compiles them.
    const e2e_mod = b.createModule(.{
        .root_source_file = b.path("tests/e2e.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "maildir", .module = mod },
            .{ .name = "mime", .module = mime.module("mime") },
        },
    });
    test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = e2e_mod })).step);

    // The fuzz targets: what the name, flag, folder and quota parsers must do
    // with input nobody wrote. They are ordinary tests as well as fuzz
    // targets, so `zig build test` exercises the same properties on the seeds
    // checked in beside them.
    const fuzz_mod = b.createModule(.{
        .root_source_file = b.path("tests/fuzz.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "maildir", .module = mod }},
    });
    // Zig's fuzzer takes one test at a time and keeps a coverage file per
    // test, so naming a target is what you want when a finding is being
    // chased: `zig build fuzz --fuzz -Dfuzz-filter=name`.
    const fuzz_filter = b.option(
        []const u8,
        "fuzz-filter",
        "Fuzz or test only the targets whose name contains this",
    );
    const fuzz_tests = b.addTest(.{
        .root_module = fuzz_mod,
        .filters = if (fuzz_filter) |f| &.{f} else &.{},
    });
    test_step.dependOn(&b.addRunArtifact(fuzz_tests).step);

    // A step of its own for `zig build fuzz --fuzz`, which needs a run step
    // holding nothing else: the fuzzer takes over the terminal and runs until
    // it is stopped, so it must not be reached by `zig build test`.
    const fuzz_step = b.step("fuzz", "The fuzz targets: add --fuzz to fuzz them");
    fuzz_step.dependOn(&b.addRunArtifact(fuzz_tests).step);

    // The loop that drives those same targets without Zig's fuzzer, which
    // this toolchain cannot usefully run: `tools/fuzz.zig` says why, and the
    // short version is that the coverage table comes back empty. Optimised,
    // because a fuzzer's whole job is how many inputs it gets through, and
    // ReleaseSafe keeps every check that makes a failure a failure.
    const fuzz_run = b.addExecutable(.{
        .name = "zig-maildir-fuzz",
        .root_module = b.createModule(.{
            .root_source_file = b.path("tools/fuzz.zig"),
            .target = b.graph.host,
            .optimize = .ReleaseSafe,
            .imports = &.{.{ .name = "fuzz_targets", .module = fuzz_mod }},
        }),
    });
    const run_fuzz = b.addRunArtifact(fuzz_run);
    run_fuzz.stdio = .inherit;
    if (b.args) |a| run_fuzz.addArgs(a);
    const fuzz_run_step = b.step("fuzz-run", "Fuzz the targets with a loop of our own");
    fuzz_run_step.dependOn(&run_fuzz.step);

    // Nothing else builds the fuzz driver, so without this it could stop
    // compiling and `zig build test` would not notice.
    const check_step = b.step("check", "Compile everything without running it");
    check_step.dependOn(&fuzz_run.step);

    // -- documentation -------------------------------------------------------
    //
    // Zig emits the API documentation as a side effect of compiling, so the
    // module is built as a library purely to get at it. What comes out is not
    // a page but a program: a WebAssembly viewer, its javascript, and a tar of
    // the sources it reads from.
    const library = b.addLibrary(.{ .name = "maildir", .root_module = mod });
    const install_docs = b.addInstallDirectory(.{
        .source_dir = library.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "docs",
    });
    const docs_step = b.step("docs", "Build the API documentation into zig-out/docs");
    docs_step.dependOn(&install_docs.step);

    // That viewer fetches `sources.tar` and `main.wasm` at runtime, which a
    // browser refuses to do from a `file://` page, so reading the docs
    // locally means serving them. It is the same reason `zig std` runs a
    // server rather than opening a file.
    const docs_port = b.option(u16, "docs-port", "Port for `zig build docs-serve` (default 8000)") orelse 8000;

    const docs_server = b.addExecutable(.{
        .name = "docs-server",
        .root_module = b.createModule(.{
            .root_source_file = b.path("tools/docs_server.zig"),
            // Always built for the machine running the build, never for
            // whatever -Dtarget the library is being built for.
            .target = b.graph.host,
            .optimize = .Debug,
        }),
    });

    const run_docs_server = b.addRunArtifact(docs_server);
    run_docs_server.step.dependOn(&install_docs.step);
    run_docs_server.addArg(b.getInstallPath(.prefix, "docs"));
    run_docs_server.addArg(b.fmt("{d}", .{docs_port}));
    // The server runs until interrupted, so its output has to reach the
    // terminal rather than being captured by the build runner.
    run_docs_server.stdio = .inherit;

    const docs_serve_step = b.step("docs-serve", "Serve the API documentation over HTTP");
    docs_serve_step.dependOn(&run_docs_server.step);

    // The server has tests of its own; without this they would never run.
    test_step.dependOn(&b.addRunArtifact(
        b.addTest(.{ .root_module = docs_server.root_module }),
    ).step);
    check_step.dependOn(&docs_server.step);
}