build.zig

//! Copyright © 2026 [Star City Security Consulting, LLC (SC2)](https://sc2.in)
//! SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0 OR PolyForm-Internal-Use-1.0.0
const std = @import("std");
const Array = std.ArrayList;
const Allocator = std.mem.Allocator;
const tst = std.testing;
const math = std.math;

const zon = @import("build.zig.zon");

const ReportType = @import("src/control_report.zig").Report;

pub fn build(b: *std.Build) !void {
    var threaded: std.Io.Threaded = .init(b.allocator, .{});
    defer threaded.deinit();
    const io = threaded.io();

    const target = b.standardTargetOptions(.{
        .default_target = defaultTarget(io),
    });
    const optimize = b.standardOptimizeOption(.{});

    const tomlz = b.dependency("tomlz", .{
        .target = target,
        .optimize = optimize,
    });

    const mvzr = b.dependency("mvzr", .{
        .target = target,
        .optimize = optimize,
    });
    const clap = b.dependency("clap", .{
        .target = target,
        .optimize = optimize,
    });
    // const zetta_dep = b.dependency("zetta", .{
    //     .target = target,
    //     .optimize = optimize,
    // });
    // const zetta_mod = zetta_dep.module("zetta");

    const zigmark_dep = b.dependency("zigmark", .{
        .target = target,
        .optimize = optimize,
    });
    const zigmark_mod = zigmark_dep.module("zigmark");

    const pozeiden_dep = b.dependency("pozeiden", .{
        .target = target,
        .optimize = optimize,
    });
    const pozeiden_mod = pozeiden_dep.module("pozeiden");

    const config_mod = b.addModule("config_parser", .{
        .root_source_file = b.path("src/config.zig"),
        .target = target,
        .optimize = optimize,
    });
    config_mod.addImport("tomlz", tomlz.module("tomlz"));
    config_mod.addImport("zigmark", zigmark_mod);

    const utils_mod = b.addModule("utils", .{
        .root_source_file = b.path("src/utils.zig"),
        .target = target,
        .optimize = optimize,
    });
    utils_mod.addImport("mvzr", mvzr.module("mvzr"));
    utils_mod.addImport("zigmark", zigmark_mod);

    // config uses utils for Date/today and readAllAlloc helpers.
    config_mod.addImport("utils", utils_mod);

    // praxis control-join loader (src/praxis_join.zig): reads the
    // consumer-generated data/praxis-join.json (schema policypress/praxis-join/v1).
    // A leaf module — std only — wired into the engines that consume the join.
    const praxis_join_mod = b.addModule("praxis_join", .{
        .root_source_file = b.path("src/praxis_join.zig"),
        .target = target,
        .optimize = optimize,
    });

    // the executable from your call to exe_mod.addExecutable
    if (target.result.os.tag != .windows) {
        const zap = b.dependency("zap", .{
            .target = target,
            .optimize = optimize,
            .openssl = false, // set to true to enable TLS support
        });
        const server_mod = b.addModule("server", .{
            .root_source_file = b.path("src/server.zig"),
            .target = target,
            .optimize = optimize,
        });
        server_mod.addImport("zap", zap.module("zap"));
        server_mod.addImport("clap", clap.module("clap"));
        const server = b.addExecutable(.{
            .name = "http",
            .root_module = server_mod,
        });

        const run_server = b.addRunArtifact(server);
        if (b.args) |args| {
            run_server.addArgs(args);
        }

        const serve_step = b.step("preview", "Serve the zola output");
        serve_step.dependOn(&run_server.step);
    } else {
        _ = b.step("preview", "Serve the zola output (Not available on Windows. run `zola preview` instead.)");
    }

    // Plain data contract for the PDF control-coverage annex (#165). A leaf
    // module (std only) so both typst (consumer) and controls (producer) can
    // import it without a cycle — the same trick B3 used for the footnote
    // resolver value.
    const control_annex_mod = b.addModule("control_annex", .{
        .root_source_file = b.path("src/control_annex.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Typst PDF engine: markdown → zigmark → Typst markup (mermaid via
    // pozeiden) → `typst compile`.
    const typst_mod = b.addModule("typst_engine", .{
        .root_source_file = b.path("src/typst.zig"),
        .target = target,
        .optimize = optimize,
    });
    typst_mod.addImport("clap", clap.module("clap"));
    typst_mod.addImport("config", config_mod);
    typst_mod.addImport("utils", utils_mod);
    typst_mod.addImport("zigmark", zigmark_mod);
    typst_mod.addImport("pozeiden", pozeiden_mod);
    typst_mod.addImport("praxis_join", praxis_join_mod);
    typst_mod.addImport("control_annex", control_annex_mod);
    const typst_exe = b.addExecutable(.{
        .root_module = typst_mod,
        .name = "pdf_engine",
    });

    const pdf_step = b.step("pdf", "Compile a single policy to PDF via the typst engine");
    const pdf_run = b.addRunArtifact(typst_exe);
    if (b.args) |args| {
        pdf_run.addArgs(args);
    }
    pdf_step.dependOn(&pdf_run.step);

    const reports_mod = b.addModule("policy_report", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("src/control_report.zig"),
    });
    reports_mod.addImport("clap", clap.module("clap"));
    reports_mod.addImport("tomlz", tomlz.module("tomlz"));
    reports_mod.addImport("config", config_mod);
    reports_mod.addImport("zigmark", zigmark_mod);
    reports_mod.addImport("utils", utils_mod);
    reports_mod.addImport("typst", typst_mod);
    reports_mod.addImport("praxis_join", praxis_join_mod);

    // Control-ID join (src/controls.zig): binds the SCF catalog, the optional
    // praxis join, and a zigmark Library of the non-draft policies so inline
    // control footnotes resolve to title + spine status + covering policies.
    // Imports `reports` (which imports `typst`), so `typst` must NOT import
    // this module — the footnote resolver reaches typst.render() as a plain
    // `zigmark.footnotes.Resolver` value instead.
    const controls_mod = b.addModule("controls", .{
        .root_source_file = b.path("src/controls.zig"),
        .target = target,
        .optimize = optimize,
    });
    controls_mod.addImport("zigmark", zigmark_mod);
    controls_mod.addImport("reports", reports_mod);
    controls_mod.addImport("praxis_join", praxis_join_mod);
    controls_mod.addImport("config", config_mod);
    controls_mod.addImport("utils", utils_mod);
    controls_mod.addImport("mvzr", mvzr.module("mvzr"));
    controls_mod.addImport("control_annex", control_annex_mod);

    // Shared render helper for the golden Typst-markup snapshots (used by both
    // golden_test.zig and tools/golden_gen.zig).
    const golden_mod = b.addModule("golden", .{
        .root_source_file = b.path("src/golden.zig"),
        .target = target,
        .optimize = optimize,
    });
    golden_mod.addImport("config", config_mod);
    golden_mod.addImport("typst", typst_mod);
    golden_mod.addImport("reports", reports_mod);
    golden_mod.addImport("controls", controls_mod);

    const policypress_mod = b.addModule("policypress", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("src/main.zig"),
    });
    const build_opts = b.addOptions();
    build_opts.addOption([]const u8, "install_prefix", b.install_prefix);
    // The package version, stamped into the audit-bundle manifest.
    build_opts.addOption([]const u8, "version", zon.version);
    policypress_mod.addImport("build_options", build_opts.createModule());
    policypress_mod.addImport("clap", clap.module("clap"));
    // src/audit.zig (same module) parses policy front matter via zigmark.
    policypress_mod.addImport("zigmark", zigmark_mod);
    policypress_mod.addImport("config", config_mod);
    policypress_mod.addImport("typst", typst_mod);
    policypress_mod.addImport("reports", reports_mod);
    policypress_mod.addImport("utils", utils_mod);
    policypress_mod.addImport("praxis_join", praxis_join_mod);
    policypress_mod.addImport("controls", controls_mod);
    policypress_mod.addImport("control_annex", control_annex_mod);
    // Build-time mermaid rendering for the site (src/diagrams.zig, `render-diagrams`).
    policypress_mod.addImport("pozeiden", pozeiden_mod);
    const policypress_exe = b.addExecutable(.{
        .root_module = policypress_mod,
        .name = "policypress",
    });
    const run_policypress = b.addRunArtifact(policypress_exe);
    if (b.args) |args| {
        run_policypress.addArgs(args);
    }
    b.installArtifact(policypress_exe);
    b.default_step.dependOn(&policypress_exe.step);

    const run_step = b.step("run", "Run Policy Center");
    run_step.dependOn(&run_policypress.step);

    {
        var docs_step = b.step("docs", "Build Documentation");
        const docs_install = b.addInstallDirectory(.{
            .install_dir = .prefix,
            .install_subdir = "docs",
            .source_dir = policypress_exe.getEmittedDocs(),
        });
        docs_step.dependOn(&docs_install.step);
        b.default_step.dependOn(docs_step);
    }
    {
        const test_module = b.addModule("test", .{
            .root_source_file = b.path("src/test.zig"),
            .target = target,
            .optimize = optimize,
            .link_libc = true,
        });
        test_module.addImport("zigmark", zigmark_mod);
        test_module.addImport("utils", utils_mod);
        test_module.addImport("typst", typst_mod);
        test_module.addImport("config", config_mod);
        test_module.addImport("reports", reports_mod);
        test_module.addImport("praxis_join", praxis_join_mod);
        test_module.addImport("controls", controls_mod);
        test_module.addImport("mvzr", mvzr.module("mvzr"));
        // src/diagrams.zig (imported by src/test.zig) renders mermaid via pozeiden.
        test_module.addImport("pozeiden", pozeiden_mod);
        const unit_tests = b.addTest(.{
            .root_module = test_module,
        });
        const run_unit_tests = b.addRunArtifact(unit_tests);
        run_unit_tests.setCwd(b.path("."));
        const test_step = b.step("test", "Run unit tests");
        test_step.dependOn(&run_unit_tests.step);

        // Golden snapshots of the generated Typst markup. golden_test.zig sits
        // at the repo root so its @embedFile("tests/golden/…") resolves. Hangs
        // off the test step, so checks.test covers it with no new flake check.
        const golden_test_mod = b.createModule(.{
            .root_source_file = b.path("golden_test.zig"),
            .target = target,
            .optimize = optimize,
        });
        golden_test_mod.addImport("golden", golden_mod);
        const golden_tests = b.addTest(.{ .root_module = golden_test_mod });
        const run_golden_tests = b.addRunArtifact(golden_tests);
        run_golden_tests.setCwd(b.path("."));
        test_step.dependOn(&run_golden_tests.step);

        // Regression guard for the top-level `--version` / `--help` paths, which
        // segfaulted when runBuild built its stderr writer by taking `.interface`
        // off a temporary File.Writer (the parent struct went out of scope, so
        // the flush vtable dereferenced a dangling file handle). Runs the real
        // binary and asserts a clean exit with the expected output; neither path
        // reads config or touches the filesystem, so it is sandbox-safe.
        const cli_version = b.addRunArtifact(policypress_exe);
        cli_version.addArg("--version");
        cli_version.expectExitCode(0);
        cli_version.expectStdErrMatch(zon.version);
        test_step.dependOn(&cli_version.step);

        const cli_help = b.addRunArtifact(policypress_exe);
        cli_help.addArg("--help");
        cli_help.expectExitCode(0);
        cli_help.expectStdErrMatch("Usage: policypress");
        test_step.dependOn(&cli_help.step);
    }
    {
        // Fuzz harness for PolicyPress's own surfaces (src/fuzz.zig).
        //   zig build fuzz          — run each target once (smoke test)
        //   zig build fuzz --fuzz   — coverage-guided fuzzing
        const fuzz_module = b.addModule("fuzz", .{
            .root_source_file = b.path("src/fuzz.zig"),
            .target = target,
            .optimize = .Debug,
        });
        fuzz_module.addImport("config", config_mod);
        fuzz_module.addImport("utils", utils_mod);
        fuzz_module.addImport("zigmark", zigmark_mod);
        fuzz_module.addImport("tomlz", tomlz.module("tomlz"));
        const fuzz_tests = b.addTest(.{
            .root_module = fuzz_module,
            // The self-hosted backend omits sanitizer-coverage sections,
            // leaving the pcs array empty and panicking in Build/Fuzz.zig.
            // LLVM emits the required __sancov_pcs1/__sancov_cntrs sections.
            .use_llvm = true,
        });
        const run_fuzz = b.addRunArtifact(fuzz_tests);
        const fuzz_step = b.step("fuzz", "Run fuzz tests (append --fuzz for coverage-guided fuzzing)");
        fuzz_step.dependOn(&run_fuzz.step);
    }
    {
        // Regenerate the golden Typst baselines that golden_test.zig checks.
        // Run after an intentional rendering change; review the diff.
        //   zig build update-golden && git diff tests/golden/
        const golden_gen_mod = b.createModule(.{
            .root_source_file = b.path("tools/golden_gen.zig"),
            .target = target,
            .optimize = optimize,
        });
        golden_gen_mod.addImport("golden", golden_mod);
        golden_gen_mod.addImport("reports", reports_mod);
        const golden_gen = b.addExecutable(.{
            .name = "golden_gen",
            .root_module = golden_gen_mod,
        });

        const Baseline = struct { name: []const u8, fixture: []const u8, flag: ?[]const u8 };
        const baselines = [_]Baseline{
            .{ .name = "test_policy.typ", .fixture = "src/test/test_policy.md", .flag = null },
            .{ .name = "test_policy_redacted.typ", .fixture = "src/test/test_policy.md", .flag = "--redact" },
            .{ .name = "test_policy_draft.typ", .fixture = "src/test/test_policy.md", .flag = "--draft" },
            .{ .name = "test_policy_render.typ", .fixture = "src/test/test_policy_render.md", .flag = null },
            .{ .name = "test_policy_math.typ", .fixture = "src/test/test_policy_math.md", .flag = null },
            // Control-footnote fixture: rendered with a fixture-backed ControlJoin
            // context (`--controls`), so it shows native `#footnote[…]` with the
            // resolved title / spine / covering-policy text.
            .{ .name = "test_policy_controls.typ", .fixture = "--controls", .flag = null },
            .{ .name = "report_scf.typ", .fixture = "--report", .flag = "scf" },
            .{ .name = "report_soc2.typ", .fixture = "--report", .flag = "soc2" },
            .{ .name = "report_review.typ", .fixture = "--report", .flag = "review" },
        };

        const update_golden = b.addUpdateSourceFiles();
        for (baselines) |bl| {
            const run = b.addRunArtifact(golden_gen);
            run.setCwd(b.path("."));
            run.addArg(bl.fixture);
            if (bl.flag) |f| run.addArg(f);
            const out = run.captureStdOut(.{});
            update_golden.addCopyFileToSource(out, b.fmt("tests/golden/{s}", .{bl.name}));
        }
        const update_golden_step = b.step("update-golden", "Regenerate golden Typst baselines in tests/golden/");
        update_golden_step.dependOn(&update_golden.step);
    }
    {
        // `zig build check` - semantic analysis without emitting a binary.
        // Used by ZLS for IDE diagnostics and as a fast CI sanity check.
        const check_step = b.step("check", "Semantic analysis (no binary emitted, used by ZLS)");
        check_step.dependOn(&policypress_exe.step);
        check_step.dependOn(&typst_exe.step);
    }
    {
        // E2E test: run policypress against the starter/ template, mirroring
        // what action.yml does for real consumers.  Requires typst in PATH
        // (provided by the devshell / Nix flake check environment).
        const e2e_step = b.step("e2e", "Run end-to-end test against starter/");

        // Step 1: ensure starter/static/logo.png exists (required by config.toml).
        const copy_template = b.addSystemCommand(&.{
            "bash", "-c",
            "mkdir -p starter/static && " ++
                "{ cp -f static/logo.png starter/static/logo.png 2>/dev/null || " ++
                "touch starter/static/logo.png; }",
        });
        copy_template.setCwd(b.path("."));

        // Step 2: run policypress from starter/ - same working dir as a real consumer.
        const e2e_run = b.addRunArtifact(policypress_exe);
        e2e_run.addArgs(&.{
            "--config", "config.toml",
            "--output", "public/pdfs",
        });
        e2e_run.setCwd(b.path("starter"));
        e2e_run.step.dependOn(&copy_template.step);
        e2e_step.dependOn(&e2e_run.step);
    }
}

/// On NixOS there is no standard FHS layout, so Zig's native target detection
/// probes many non-existent paths which is slow. Detect NixOS and return an
/// explicit target query to skip the probing.
fn defaultTarget(io: std.Io) std.Target.Query {
    if (std.Io.Dir.accessAbsolute(io, "/etc/NIXOS", .{})) |_| {
        return .{
            .os_tag = .linux,
            .abi = .gnu,
        };
    } else |_| {}
    return .{};
}