项目

.{
    // 遵循 Zig 命名约定的包标识符
    .name = .workspace_dashboard,
    
    // 此工作区的语义版本 (major.minor.patch)
    .version = "0.1.0",
    
    // 构建此项目所需的最低 Zig 编译器版本
    // 确保与语言特性和构建系统 API 的兼容性
    .minimum_zig_version = "0.15.2",
    
    // 包中包含的用于分发和源跟踪的显式路径列表
    // 这控制了当此项目发布或作为供应商提供时所打包的内容
    .paths = .{
        "build.zig",        // 主构建脚本
        "build.zig.zon",    // 此清单文件
        "deps.zig",         // 集中式依赖项配置
        "app",              // 应用程序入口点和可执行代码
        "packages",         // 本地工作区包 (libA, libB)
        "vendor",           // 供应商提供的第三方依赖项 (palette)
    },
    
    // 从远程源获取的外部依赖项
    // 此工作区中为空，因为所有依赖项都是本地/供应商提供的
    .dependencies = .{},
    
    // 用于包清单完整性验证的加密哈希
    // 由 Zig 构建系统自动计算
    .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
// - palette: 供应商提供的外部依赖项
// - libA: internal package with no dependencies
// - libA: 没有依赖项的内部包
// - libB: internal package that depends on both libA and palette
// - libB: 依赖于 libA 和 palette 的内部包
//
// Parameters:
// b: Build instance used to create modules
// b: 用于创建模块的构建实例
//   target: Compilation target (architecture, OS, ABI)
//   target: 编译目标 (架构, 操作系统, ABI)
// optimize: Optimization mode (Debug, ReleaseSafe, ReleaseFast, ReleaseSmall)
// optimize: 优化模式 (Debug, ReleaseSafe, ReleaseFast, ReleaseSmall)
//
// Returns: Modules struct containing references to libA and libB
// 返回: 包含 libA 和 libB 引用的 Modules 结构体
pub fn addModules(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
) Modules {
    // Create module for the vendored palette library
    // 为供应商提供的 palette 库创建模块
    // Located in vendor directory as an external dependency
    // 作为外部依赖项位于 vendor 目录中
    const palette_mod = b.createModule(.{
        .root_source_file = b.path("vendor/palette/palette.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Create module for libA (analytics functionality)
    // 为 libA (分析功能) 创建模块
    // 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)
    // 为 libB (报告功能) 创建模块
    // Depends on both libA and palette, establishing the dependency chain
    // 依赖于 libA 和 palette，建立依赖链
    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
        // 导入声明允许 libB 访问 libA 和 palette 模块
        .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");

/// 多包工作区的构建脚本，演示依赖项管理。
/// 编排依赖于本地包（libA、libB）
/// 和 vendored 依赖项（palette）的可执行文件的编译，并提供测试和文档步骤。
pub fn build(b: *std.Build) void {
    // 从命令行选项解析目标平台和优化级别
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 通过deps.zig加载所有工作区模块（libA、libB、palette）
    // 这集中了依赖项配置并使模块可用于导入
    const modules = deps.addModules(b, target, optimize);

    // 创建主可执行文件的根模块
    // 显式声明对libA和libB的依赖，使其可导入
    const root_module = b.createModule(.{
        .root_source_file = b.path("app/main.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            // 将导入名称映射到从deps.zig加载的实际模块
            .{ .name = "libA", .module = modules.libA },
            .{ .name = "libB", .module = modules.libB },
        },
    });

    // 使用配置的根模块定义可执行文件工件
    const exe = b.addExecutable(.{
        .name = "workspace-dashboard",
        .root_module = root_module,
    });

    // 注册可执行文件以安装到zig-out/bin
    b.installArtifact(exe);

    // 创建运行构建可执行文件的命令
    const run_cmd = b.addRunArtifact(exe);
    // 将任何额外的命令行参数转发到可执行文件
    if (b.args) |args| run_cmd.addArgs(args);

    // 注册"zig build run"步骤以编译并执行仪表板
    const run_step = b.step("run", "Run the latency dashboard");
    run_step.dependOn(&run_cmd.step);

    // 为每个库模块创建测试可执行文件
    // 这些将运行在相应库源文件中定义的任何测试
    const lib_a_tests = b.addTest(.{ .root_module = modules.libA });
    const lib_b_tests = b.addTest(.{ .root_module = modules.libB });

    // 注册"zig build test"步骤以运行所有库测试套件
    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);

    // 生成记录工作区模块结构的文本文件
    // 这作为依赖关系图的人类可读文档
    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
    );

    // 将生成的文档安装到zig-out/workspace-artifacts
    const install_map = b.addInstallDirectory(.{
        .source_dir = mapping.getDirectory(),
        .install_dir = .prefix,
        .install_subdir = "workspace-artifacts",
    });

    // 注册"zig build map"步骤以生成并安装依赖项文档
    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.
    // / 如果平均值为0则返回0以避免除零。
    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.
// / 使用 Welford 在线算法进行数值稳定的方差计算。
// / Panics if the input slice is empty.
// / 如果输入切片为空则 panic。
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 是当前均值平方差之和（Welford 算法）
    var m2: f64 = 0.0;
    var index: usize = 0;

    while (index < values.len) : (index += 1) {
        const value = values[index];
        // 追踪最小值和最大值
        if (value < min_value) min_value = value;
        if (value > max_value) max_value = value;

        // Welford 在线算法用于均值和方差
        const count = index + 1;
        const delta = value - mean_value;
        mean_value += delta / @as(f64, @floatFromInt(count));
        const delta2 = value - mean_value;
        m2 += delta * delta2;
    }

    // 使用 Bessel 校正（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,
    };
}

// / 从预计算的统计数据中计算样本标准差。
// / 标准差是方差的平方根。
pub fn sampleStdDev(stats: Stats) f64 {
    return std.math.sqrt(stats.variance);
}

// / 为给定值计算 z-score（标准分数）。
// / 衡量一个值与平均值相差多少个标准差。
// / 如果标准差为 0，则返回 0 以避免除零。
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
// 导入 analytics 包 (libA) 以进行统计分析
const analytics = @import("libA");
// Import palette package for theming and styled output
// 导入 palette 包以用于主题和样式输出
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
// / 从 palette 包重新导出 Theme，以便在报告中保持一致的主题
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
// / 从 palette 包返回默认主题
pub fn defaultTheme() Theme {
    return palette.defaultTheme();
}

// / Maps a Status value to its corresponding palette Tone for styling
// / 将状态值映射到其对应的 palette 调色板色调以进行样式设置
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
// 表示带有 ANSI 转义代码的颜色主题，用于不同的色调
// 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
    // 返回给定色调的相应 ANSI 开始序列
    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 颜色代码包装它，将样式化文本写入提供的写入器
// 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
// 验证默认主题返回正确的 ANSI 转义代码
test "default theme colors" {
    const theme = defaultTheme();
    try std.testing.expectEqualStrings("\x1b[32m", theme.start(.stable));
    try std.testing.expectEqualStrings("\x1b[0m", theme.reset);
}