Project

.{
    // Package identifier following Zig naming conventions
    .name = .workspace_dashboard,
    
    // Semantic version for this workspace (major.minor.patch)
    .version = "0.1.0",
    
    // Minimum Zig compiler version required to build this project
    .minimum_zig_version = "0.15.2",
    
    // Explicit list of paths included in the package for distribution and source tracking
    // This controls what gets packaged when this project is published or vendored
    .paths = .{
        "build.zig",        // Main build script
        "build.zig.zon",    // This manifest file
        "deps.zig",         // Centralized dependency configuration
        "app",              // Application entry point and executable code
        "packages",         // Local workspace packages (libA, libB)
        "vendor",           // Vendored third-party dependencies (palette)
    },
    
    // External dependencies fetched from remote sources
    // Empty in this workspace as all dependencies are local/vendored
    .dependencies = .{},
    
    // Cryptographic hash for integrity verification of the package manifest
    // Automatically computed by the Zig build system
    .fingerprint = 0x88b8c5fe06a5c6a1,
}

// Import the standard library for build system types and utilities
const std = @import("std");

// Container struct that holds references to project modules
// This allows centralized access to all workspace modules
pub const Modules = struct {
    libA: *std.Build.Module,
    libB: *std.Build.Module,
};

// Creates and configures all project modules with their dependencies
// This function sets up the module dependency graph for the workspace:
// - palette: vendored external dependency
// - libA: internal package with no dependencies
// - libB: internal package that depends on both libA and palette
//
// Parameters:
//   b: Build instance used to create modules
//   target: Compilation target (architecture, OS, ABI)
//   optimize: Optimization mode (Debug, ReleaseSafe, ReleaseFast, ReleaseSmall)
//
// Returns: Modules struct containing references to libA and libB
pub fn addModules(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
) Modules {
    // Create module for the vendored palette library
    // Located in vendor directory as an external dependency
    const palette_mod = b.createModule(.{
        .root_source_file = b.path("vendor/palette/palette.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Create module for libA (analytics functionality)
    // This is a standalone library with no external dependencies
    const lib_a = b.addModule("libA", .{
        .root_source_file = b.path("packages/libA/analytics.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Create module for libB (report functionality)
    // Depends on both libA and palette, establishing the dependency chain
    const lib_b = b.addModule("libB", .{
        .root_source_file = b.path("packages/libB/report.zig"),
        .target = target,
        .optimize = optimize,
        // Import declarations allow libB to access libA and palette modules
        .imports = &.{
            .{ .name = "libA", .module = lib_a },
            .{ .name = "palette", .module = palette_mod },
        },
    });

    // Return configured modules for use in build scripts
    return Modules{
        .libA = lib_a,
        .libB = lib_b,
    };
}

const std = @import("std");
const deps = @import("deps.zig");

/// Build script for a multi-package workspace demonstrating dependency management.
/// Orchestrates compilation of an executable that depends on local packages (libA, libB)
/// and a vendored dependency (palette), plus provides test and documentation steps.
pub fn build(b: *std.Build) void {
    // Parse target platform and optimization level from command-line options
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Load all workspace modules (libA, libB, palette) via deps.zig
    // This centralizes dependency configuration and makes modules available for import
    const modules = deps.addModules(b, target, optimize);

    // Create the root module for the main executable
    // Explicitly declares dependencies on libA and libB, making them importable
    const root_module = b.createModule(.{
        .root_source_file = b.path("app/main.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            // Map import names to actual modules loaded from deps.zig
            .{ .name = "libA", .module = modules.libA },
            .{ .name = "libB", .module = modules.libB },
        },
    });

    // Define the executable artifact using the configured root module
    const exe = b.addExecutable(.{
        .name = "workspace-dashboard",
        .root_module = root_module,
    });

    // Register the executable for installation into zig-out/bin
    b.installArtifact(exe);

    // Create a command to run the built executable
    const run_cmd = b.addRunArtifact(exe);
    // Forward any extra command-line arguments to the executable
    if (b.args) |args| run_cmd.addArgs(args);

    // Register "zig build run" step to compile and execute the dashboard
    const run_step = b.step("run", "Run the latency dashboard");
    run_step.dependOn(&run_cmd.step);

    // Create test executables for each library module
    // These will run any tests defined in the respective library source files
    const lib_a_tests = b.addTest(.{ .root_module = modules.libA });
    const lib_b_tests = b.addTest(.{ .root_module = modules.libB });

    // Register "zig build test" step to run all library test suites
    const tests_step = b.step("test", "Run library test suites");
    tests_step.dependOn(&b.addRunArtifact(lib_a_tests).step);
    tests_step.dependOn(&b.addRunArtifact(lib_b_tests).step);

    // Generate a text file documenting the workspace module structure
    // This serves as human-readable documentation of the dependency graph
    const mapping = b.addNamedWriteFiles("workspace-artifacts");
    _ = mapping.add("dependency-map.txt",
        \\Modules registered in build.zig:
        \\  libA      -> packages/libA/analytics.zig
        \\  libB      -> packages/libB/report.zig (imports libA, palette)
        \\  palette   -> vendor/palette/palette.zig (anonymous)
        \\  executable -> app/main.zig
    );

    // Install the generated documentation into zig-out/workspace-artifacts
    const install_map = b.addInstallDirectory(.{
        .source_dir = mapping.getDirectory(),
        .install_dir = .prefix,
        .install_subdir = "workspace-artifacts",
    });

    // Register "zig build map" step to generate and install dependency documentation
    const map_step = b.step("map", "Emit dependency map to zig-out");
    map_step.dependOn(&install_map.step);
}

/// Statistical summary of a numerical dataset.
/// Contains computed statistics including central tendency, spread, and sample size.
const std = @import("std");

pub const Stats = struct {
    sample_count: usize,
    min: f64,
    max: f64,
    mean: f64,
    variance: f64,

    /// Calculates the range (difference between maximum and minimum values).
    pub fn range(self: Stats) f64 {
        return self.max - self.min;
    }

    /// Calculates the coefficient of variation (range divided by mean).
    /// Returns 0 if mean is 0 to avoid division by zero.
    pub fn relativeSpread(self: Stats) f64 {
        return if (self.mean == 0) 0 else self.range() / self.mean;
    }
};

/// Computes descriptive statistics for a slice of floating-point values.
/// Uses Welford's online algorithm for numerically stable variance calculation.
/// Panics if the input slice is empty.
pub fn analyze(values: []const f64) Stats {
    std.debug.assert(values.len > 0);

    var min_value: f64 = values[0];
    var max_value: f64 = values[0];
    var mean_value: f64 = 0.0;
    // M2 is the sum of squares of differences from the current mean (Welford's algorithm)
    var m2: f64 = 0.0;
    var index: usize = 0;

    while (index < values.len) : (index += 1) {
        const value = values[index];
        // Track minimum and maximum values
        if (value < min_value) min_value = value;
        if (value > max_value) max_value = value;

        // Welford's online algorithm for mean and variance
        const count = index + 1;
        const delta = value - mean_value;
        mean_value += delta / @as(f64, @floatFromInt(count));
        const delta2 = value - mean_value;
        m2 += delta * delta2;
    }

    // Calculate sample variance using Bessel's correction (n-1)
    const count_f = @as(f64, @floatFromInt(values.len));
    const variance_value = if (values.len > 1)
        m2 / (count_f - 1.0)
    else
        0.0;

    return Stats{
        .sample_count = values.len,
        .min = min_value,
        .max = max_value,
        .mean = mean_value,
        .variance = variance_value,
    };
}

/// Computes the sample standard deviation from precomputed statistics.
/// Standard deviation is the square root of variance.
pub fn sampleStdDev(stats: Stats) f64 {
    return std.math.sqrt(stats.variance);
}

/// Calculates the z-score (standard score) for a given value.
/// Measures how many standard deviations a value is from the mean.
/// Returns 0 if standard deviation is 0 to avoid division by zero.
pub fn zScore(value: f64, stats: Stats) f64 {
    const dev = sampleStdDev(stats);
    if (dev == 0.0) return 0.0;
    return (value - stats.mean) / dev;
}

test "analyze returns correct statistics" {
    const data = [_]f64{ 12.0, 13.5, 11.8, 12.2, 12.0 };
    const stats = analyze(&data);

    try std.testing.expectEqual(@as(usize, data.len), stats.sample_count);
    try std.testing.expectApproxEqRel(12.3, stats.mean, 1e-6);
    try std.testing.expectApproxEqAbs(1.7, stats.range(), 1e-6);
}

// Import standard library for testing utilities
const std = @import("std");
// Import analytics package (libA) for statistical analysis
const analytics = @import("libA");
// Import palette package for theming and styled output
const palette = @import("palette");

/// Represents a named collection of numerical data points for analysis
pub const Dataset = struct {
    name: []const u8,
    values: []const f64,
};

/// Re-export Theme from palette package for consistent theming across reports
pub const Theme = palette.Theme;

/// Defines threshold values that determine status classification
/// based on statistical spread of data
pub const Thresholds = struct {
    watch: f64,  // Threshold for watch status (lower severity)
    alert: f64,  // Threshold for alert status (higher severity)
};

/// Represents the health status of a dataset based on its statistical spread
pub const Status = enum { stable, watch, alert };

/// Determines the status of a dataset by comparing its relative spread
/// against defined thresholds
pub fn status(stats: analytics.Stats, thresholds: Thresholds) Status {
    const spread = stats.relativeSpread();
    // Check against alert threshold first (highest severity)
    if (spread >= thresholds.alert) return .alert;
    // Then check watch threshold (medium severity)
    if (spread >= thresholds.watch) return .watch;
    // Default to stable if below all thresholds
    return .stable;
}

/// Returns the default theme from the palette package
pub fn defaultTheme() Theme {
    return palette.defaultTheme();
}

/// Maps a Status value to its corresponding palette Tone for styling
pub fn tone(status_value: Status) palette.Tone {
    return switch (status_value) {
        .stable => .stable,
        .watch => .watch,
        .alert => .alert,
    };
}

/// Converts a Status value to its string representation
pub fn label(status_value: Status) []const u8 {
    return switch (status_value) {
        .stable => "stable",
        .watch => "watch",
        .alert => "alert",
    };
}

/// Renders a formatted table displaying statistical analysis of multiple datasets
/// with color-coded status indicators based on thresholds
pub fn renderTable(
    writer: anytype,
    data_sets: []const Dataset,
    thresholds: Thresholds,
    theme: Theme,
) !void {
    // Print table header with column names
    try writer.print("{s: <12} {s: <10} {s: <10} {s: <10} {s}\n", .{
        "dataset", "status", "mean", "range", "samples",
    });
    // Print separator line
    try writer.print("{s}\n", .{"-----------------------------------------------"});

    // Process and display each dataset
    for (data_sets) |data| {
        // Compute statistics for current dataset
        const stats = analytics.analyze(data.values);
        const status_value = status(stats, thresholds);

        // Print dataset name
        try writer.print("{s: <12} ", .{data.name});
        // Print styled status label with theme-appropriate color
        try palette.writeStyled(theme, tone(status_value), writer, label(status_value));
        // Print statistical values: mean, range, and sample count
        try writer.print(
            " {d: <10.2} {d: <10.2} {d: <10}\n",
            .{ stats.mean, stats.range(), stats.sample_count },
        );
    }
}

// Verifies that status classification correctly responds to different
// levels of data spread relative to defined thresholds
test "status thresholds" {
    const thresholds = Thresholds{ .watch = 0.05, .alert = 0.12 };

    // Test with tightly clustered values (low spread) - should be stable
    const tight = analytics.analyze(&.{ 99.8, 100.1, 100.0 });
    try std.testing.expectEqual(Status.stable, status(tight, thresholds));

    // Test with widely spread values (high spread) - should trigger alert
    const drift = analytics.analyze(&.{ 100.0, 112.0, 96.0 });
    try std.testing.expectEqual(Status.alert, status(drift, thresholds));
}

// Import the standard library for testing utilities
const std = @import("std");

// Defines the three tonal categories for styled output
pub const Tone = enum { stable, watch, alert };

// Represents a color theme with ANSI escape codes for different tones
// Each tone has a start sequence and there's a shared reset sequence
pub const Theme = struct {
    stable_start: []const u8,
    watch_start: []const u8,
    alert_start: []const u8,
    reset: []const u8,

    // Returns the appropriate ANSI start sequence for the given tone
    pub fn start(self: Theme, tone: Tone) []const u8 {
        return switch (tone) {
            .stable => self.stable_start,
            .watch => self.watch_start,
            .alert => self.alert_start,
        };
    }
};

// Creates a default theme with standard terminal colors:
// stable (green), watch (yellow), alert (red)
pub fn defaultTheme() Theme {
    return Theme{
        .stable_start = "\x1b[32m", // green
        .watch_start = "\x1b[33m",  // yellow
        .alert_start = "\x1b[31m",  // red
        .reset = "\x1b[0m",
    };
}

// Writes styled text to the provided writer by wrapping it with
// ANSI color codes based on the theme and tone
pub fn writeStyled(theme: Theme, tone: Tone, writer: anytype, text: []const u8) !void {
    try writer.print("{s}{s}{s}", .{ theme.start(tone), text, theme.reset });
}

// Verifies that the default theme returns correct ANSI escape codes
test "default theme colors" {
    const theme = defaultTheme();
    try std.testing.expectEqualStrings("\x1b[32m", theme.start(.stable));
    try std.testing.expectEqualStrings("\x1b[0m", theme.reset);
}