build.zig

const std = @import("std");
const utils = @import("build/utils.zig");

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

    // CI option - enables CI-specific behavior
    const ci = b.option(bool, "ci", "Enable CI-specific behavior") orelse false;

    // Strip option - omit debug symbols for smaller release binaries
    const strip = b.option(bool, "strip", "Omit debug symbols") orelse false;

    // Validate utilities exist before building
    utils.validateUtilities() catch |err| {
        std.log.err("Utility validation failed: {}", .{err});
        return; // Abort build configuration
    };

    // Build options with version from build.zig.zon using safe parser
    const build_options = b.addOptions();

    const version = utils.parseVersion(b.allocator) catch |err| {
        std.log.err("Failed to parse version from build.zig.zon: {}", .{err});
        std.log.err("Ensure build.zig.zon exists and contains a valid .version field", .{});
        return; // Abort build configuration
    };
    defer b.allocator.free(version); // Free the allocated version string

    build_options.addOption([]const u8, "version", version);

    // Create build_options module once and reuse it
    const build_options_module = build_options.createModule();

    // Common library module
    const common = b.addModule("common", .{
        .root_source_file = b.path("src/common/lib.zig"),
        .imports = &.{
            .{ .name = "build_options", .module = build_options_module },
        },
    });

    // Build utilities using metadata-driven approach
    for (utils.utilities) |util| {
        buildUtility(b, util, target, optimize, strip, common, build_options_module) catch |err| {
            std.log.err("Failed to build utility {s}: {}", .{ util.name, err });
            return; // Abort build configuration
        };
    }

    // Unit tests
    buildTests(b, target, optimize, common, build_options_module) catch |err| {
        std.log.err("Failed to configure tests: {}", .{err});
        return; // Abort build configuration
    };

    // Add additional build steps
    addFormatSteps(b);
    addCleanStep(b);
    addCIValidateStep(b, ci);
    addDocsStep(b, target, optimize, common, build_options_module);
    addCoverageStep(b, target, common, build_options_module);
}

/// Build a single utility with proper error handling
/// Creates executable, links necessary libraries, and sets up run steps
/// Returns error if build configuration fails
fn buildUtility(
    b: *std.Build,
    util: utils.UtilityMeta,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    strip: bool,
    common: *std.Build.Module,
    build_options_module: *std.Build.Module,
) !void {
    const exe = b.addExecutable(.{
        .name = util.name,
        .root_module = b.createModule(.{
            .root_source_file = b.path(util.path),
            .target = target,
            .optimize = optimize,
            .strip = if (strip) true else null,
        }),
    });

    // Add imports
    exe.root_module.addImport("common", common);
    exe.root_module.addImport("build_options", build_options_module);

    // Metadata-driven library linking
    if (util.needs_libc) {
        exe.linkLibC();
    }

    // Add C source files if specified
    for (util.c_sources) |c_src| {
        exe.addCSourceFile(.{ .file = b.path(c_src) });
    }

    b.installArtifact(exe);

    // Create run step with error handling
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

    const run_step_name = b.fmt("run-{s}", .{util.name});
    const run_step_desc = b.fmt("Run {s} - {s}", .{ util.name, util.description });
    const run_step = b.step(run_step_name, run_step_desc);
    run_step.dependOn(&run_cmd.step);
}

/// Configure tests with proper error handling
fn buildTests(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    common: *std.Build.Module,
    build_options_module: *std.Build.Module,
) !void {
    const test_step = b.step("test", "Run unit tests");

    // Test each utility
    for (utils.utilities) |util| {
        const util_tests = b.addTest(.{
            .root_module = b.createModule(.{
                .root_source_file = b.path(util.path),
                .target = target,
                .optimize = optimize,
            }),
        });

        util_tests.root_module.addImport("common", common);
        util_tests.root_module.addImport("build_options", build_options_module);

        // Metadata-driven library linking for tests
        if (util.needs_libc) {
            util_tests.linkLibC();
        }

        // Add C source files if specified
        for (util.c_sources) |c_src| {
            util_tests.addCSourceFile(.{ .file = b.path(c_src) });
        }

        const run_util_tests = b.addRunArtifact(util_tests);
        test_step.dependOn(&run_util_tests.step);
    }

    // Common library tests
    const common_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/common/lib.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    common_tests.root_module.addImport("build_options", build_options_module);

    const run_common_tests = b.addRunArtifact(common_tests);
    test_step.dependOn(&run_common_tests.step);

    // Create a separate privileged test step
    const privileged_test_step = b.step("test-privileged", "Run tests that require privilege simulation (run under fakeroot)");

    // Run privileged tests only - filter for tests starting with "privileged:"
    // Chain tests sequentially to avoid FileBusy race conditions in parallel execution
    // See: https://github.com/ziglang/zig/issues/9439
    var prev_run_step: ?*std.Build.Step = null;

    for (utils.utilities) |util| {
        const util_tests = b.addTest(.{
            .root_module = b.createModule(.{
                .root_source_file = b.path(util.path),
                .target = target,
                .optimize = optimize,
            }),
            .filters = &.{"privileged:"}, // Only run tests starting with "privileged:"
            .name = b.fmt("{s}_privileged_test", .{util.name}), // Unique name to avoid conflicts
        });

        util_tests.root_module.addImport("common", common);
        util_tests.root_module.addImport("build_options", build_options_module);

        if (util.needs_libc) {
            util_tests.linkLibC();
        }

        // Add C source files if specified
        for (util.c_sources) |c_src| {
            util_tests.addCSourceFile(.{ .file = b.path(c_src) });
        }

        // WORKAROUND: The --listen=- flag breaks under fakeroot
        // See: https://github.com/ziglang/zig/issues/15091
        // Run tests directly without the server mode
        const install_util_tests = b.addInstallArtifact(util_tests, .{});
        const run_util_tests = b.addSystemCommand(&.{
            b.getInstallPath(install_util_tests.dest_dir.?, util_tests.out_filename),
        });
        run_util_tests.step.dependOn(&install_util_tests.step);

        // Chain each test to run after the previous one completes
        if (prev_run_step) |prev| {
            run_util_tests.step.dependOn(prev);
        }
        prev_run_step = &run_util_tests.step;

        privileged_test_step.dependOn(&run_util_tests.step);
    }

    // Also add common library privileged tests if any
    const common_tests_priv = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/common/lib.zig"),
            .target = target,
            .optimize = optimize,
        }),
        .filters = &.{"privileged:"}, // Only run tests starting with "privileged:"
        .name = "common_privileged_test", // Unique name to avoid conflicts
    });
    common_tests_priv.root_module.addImport("build_options", build_options_module);

    // Same workaround as above for common library tests
    const install_common_tests_priv = b.addInstallArtifact(common_tests_priv, .{});
    const run_common_tests_priv = b.addSystemCommand(&.{
        b.getInstallPath(install_common_tests_priv.dest_dir.?, common_tests_priv.out_filename),
    });
    run_common_tests_priv.step.dependOn(&install_common_tests_priv.step);

    // Chain common tests to run after all utility tests
    if (prev_run_step) |prev| {
        run_common_tests_priv.step.dependOn(prev);
    }

    privileged_test_step.dependOn(&run_common_tests_priv.step);

    // Integration tests
    buildIntegrationTests(b, target, optimize, common, build_options_module) catch |err| {
        std.log.err("Failed to configure integration tests: {}", .{err});
        return; // Abort build configuration
    };
}

/// Configure integration tests for the privilege framework
fn buildIntegrationTests(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    common: *std.Build.Module,
    build_options_module: *std.Build.Module,
) !void {
    const integration_test_step = b.step("test-integration", "Run privilege framework integration tests");

    // Core infrastructure integration tests
    const core_integration_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/common/privilege_test_integration.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    core_integration_tests.root_module.addImport("build_options", build_options_module);

    const run_core_integration = b.addRunArtifact(core_integration_tests);
    integration_test_step.dependOn(&run_core_integration.step);

    // Workflow integration tests
    const workflow_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("tests/privilege_integration/workflow_test.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    workflow_tests.root_module.addImport("common", common);

    const run_workflow_tests = b.addRunArtifact(workflow_tests);
    integration_test_step.dependOn(&run_workflow_tests.step);

    // File operations integration tests
    const file_ops_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("tests/privilege_integration/file_ops_test.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    file_ops_tests.root_module.addImport("common", common);

    const run_file_ops_tests = b.addRunArtifact(file_ops_tests);
    integration_test_step.dependOn(&run_file_ops_tests.step);
}

/// Add format and format-check steps
fn addFormatSteps(b: *std.Build) void {
    // Format step - formats all source files
    const fmt_step = b.step("fmt", "Format all source files");
    const fmt_cmd = b.addSystemCommand(&.{ "zig", "fmt", "src/", "build.zig", "build/" });
    fmt_step.dependOn(&fmt_cmd.step);

    // Format check step - checks if files are properly formatted
    const fmt_check_step = b.step("fmt-check", "Check if source files are properly formatted");
    const fmt_check_cmd = b.addSystemCommand(&.{ "zig", "fmt", "--check", "src/", "build.zig", "build/" });
    fmt_check_step.dependOn(&fmt_check_cmd.step);
}

/// Add clean step
fn addCleanStep(b: *std.Build) void {
    const clean_step = b.step("clean", "Remove build artifacts");

    // Remove zig-cache directory
    const rm_cache = b.addRemoveDirTree(b.path("zig-cache"));
    clean_step.dependOn(&rm_cache.step);

    // Remove zig-out directory
    const rm_out = b.addRemoveDirTree(b.path("zig-out"));
    clean_step.dependOn(&rm_out.step);
}

/// Add CI validation step
fn addCIValidateStep(b: *std.Build, ci: bool) void {
    const ci_validate_step = b.step("ci-validate", "Validate project for CI");

    // Run CI validation script
    const validate_cmd = b.addSystemCommand(&.{"scripts/ci-validate.sh"});
    if (ci) {
        validate_cmd.setEnvironmentVariable("CI", "true");
    }
    ci_validate_step.dependOn(&validate_cmd.step);
}

/// Add documentation generation step
fn addDocsStep(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    common: *std.Build.Module,
    build_options_module: *std.Build.Module,
) void {
    const docs_step = b.step("docs", "Generate documentation");

    // Generate documentation for the common module
    // We need to create a dummy executable that imports the common module
    // to generate its documentation
    const common_docs_exe = b.addLibrary(.{
        .name = "common-docs",
        .linkage = .static,
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/common/lib.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    common_docs_exe.root_module.addImport("build_options", build_options_module);

    // Get the emitted docs for the common module
    const common_docs = common_docs_exe.getEmittedDocs();
    const install_common_docs = b.addInstallDirectory(.{
        .source_dir = common_docs,
        .install_dir = .prefix,
        .install_subdir = "docs/common",
    });
    docs_step.dependOn(&install_common_docs.step);

    // Generate documentation for each utility
    for (utils.utilities) |util| {
        const util_exe = b.addExecutable(.{
            .name = util.name,
            .root_module = b.createModule(.{
                .root_source_file = b.path(util.path),
                .target = target,
                .optimize = optimize,
            }),
        });

        // Add imports needed for the utility
        util_exe.root_module.addImport("common", common);
        util_exe.root_module.addImport("build_options", build_options_module);

        if (util.needs_libc) {
            util_exe.linkLibC();
        }

        // Add C source files if specified
        for (util.c_sources) |c_src| {
            util_exe.addCSourceFile(.{ .file = b.path(c_src) });
        }

        // Get the emitted docs for this utility
        const util_docs = util_exe.getEmittedDocs();
        const install_util_docs = b.addInstallDirectory(.{
            .source_dir = util_docs,
            .install_dir = .prefix,
            .install_subdir = b.fmt("docs/{s}", .{util.name}),
        });
        docs_step.dependOn(&install_util_docs.step);
    }

    // Add a completion message (without circular dependency)
    // This is just informational and doesn't need to be part of the step chain
}

/// Add coverage step - builds test binaries with LLVM backend for kcov
/// Binaries are installed to zig-out/bin/tests/ but NOT run.
/// Use scripts/coverage.sh to run them under kcov.
fn addCoverageStep(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    common: *std.Build.Module,
    build_options_module: *std.Build.Module,
) void {
    const coverage_step = b.step("coverage", "Build test binaries with LLVM backend for coverage analysis");

    // Build test binary for each utility
    for (utils.utilities) |util| {
        const util_tests = b.addTest(.{
            .root_module = b.createModule(.{
                .root_source_file = b.path(util.path),
                .target = target,
                .optimize = .Debug,
            }),
            .use_llvm = true,
            .name = b.fmt("{s}_test", .{util.name}),
        });

        util_tests.root_module.addImport("common", common);
        util_tests.root_module.addImport("build_options", build_options_module);

        if (util.needs_libc) {
            util_tests.linkLibC();
        }

        for (util.c_sources) |c_src| {
            util_tests.addCSourceFile(.{ .file = b.path(c_src) });
        }

        // Install binary to zig-out/bin/tests/ without running
        const install = b.addInstallArtifact(util_tests, .{
            .dest_dir = .{ .override = .{ .custom = "bin/tests" } },
        });
        coverage_step.dependOn(&install.step);
    }

    // Build test binary for common library
    const common_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/common/lib.zig"),
            .target = target,
            .optimize = .Debug,
        }),
        .use_llvm = true,
        .name = "common_test",
    });
    common_tests.root_module.addImport("build_options", build_options_module);

    const install_common = b.addInstallArtifact(common_tests, .{
        .dest_dir = .{ .override = .{ .custom = "bin/tests" } },
    });
    coverage_step.dependOn(&install_common.step);
}