路径/URI 与输出截断辅助工具的 utility crate 测试

fn truncate_bytes_less_than_placeholder_returns_placeholder()

作用：检查当按字节限制，而且限制小到连完整提示都放不下时，程序仍然能给出一个固定格式的截断提示。这样用户至少知道内容被删减了，而不是看到一段莫名其妙的残缺文字。

数据流：输入是一小段文字“example output”和一个非常小的字节上限。测试把它交给格式化截断流程，再用断言比较结果。出来的结果应该是带警告、原始 token 数、行数，以及“截掉了多少字符”的文本。

调用关系：这个测试由 Rust 测试框架在测试阶段调用。它主要把期望结果和实际结果交给 assert_eq! 做比较，用来守住“极小字节预算”这个边界。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_tokens_less_than_placeholder_returns_placeholder()

作用：检查当按 token 限制，而且限制小于提示文本本身需要的空间时，截断结果仍然清楚可读。token 可以理解成模型处理文字时的大致文字块。

数据流：进去的是“example output”和 1 个 token 的限制。测试让截断逻辑处理它，然后比较输出。出来的文本应该保留一点开头和结尾，并明确写出中间省略了 3 个 token。

调用关系：它在测试套件中覆盖“token 预算极低”的情况。实际判断交给 assert_eq!，确保被测代码的输出格式没有悄悄变化。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_tokens_under_limit_returns_original()

作用：确认文本在 token 数没有超过限制时，不会被多此一举地改写。这个测试防止正常短输出被错误加上警告或省略号。

数据流：输入是一段短文本和足够大的 token 上限。截断流程检查后应发现不需要处理。输出应该和原始文本一模一样，没有任何额外说明。

调用关系：测试框架运行它时，它只做一件事：用 assert_eq! 比较原文和处理后的结果，证明“没超限就不动”。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_bytes_under_limit_returns_original()

作用：确认按字节数限制时，如果内容本来就够短，程序会原样返回。这样可以避免用户看到不必要的截断警告。

数据流：进去的是“example output”和 20 字节的上限。被测逻辑判断内容在范围内，于是输出仍是原文。测试用断言确认前后没有变化。

调用关系：它和 token 版本的短文本测试互相补充，覆盖按字节计算的正常路径。最后由 assert_eq! 判断是否完全一致。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_tokens_over_limit_returns_truncated()

作用：检查按 token 限制时，长文本真的会被截短，并且提示用户原文有多大、中间省略了多少。它保证超限时不会偷偷丢内容而不说明。

数据流：输入是一句较长的英文和 5 个 token 的限制。截断流程估算原始 token 数，保留文本开头和结尾，把中间替换成“10 tokens truncated”这样的提示。测试比较最终完整字符串。

调用关系：这个测试覆盖 token 截断的主要场景。它通过 assert_eq! 固定住输出格式，避免以后修改时改变用户能看到的警告内容。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_bytes_over_limit_returns_truncated()

作用：检查按字节限制时，长文本会被截短成“前半段 + 省略提示 + 后半段”。这能让用户看到两头的上下文，同时知道中间少了多少字符。

数据流：输入是一段较长文字和 30 字节上限。截断逻辑按字节预算取前后内容，计算中间省略的字符数量，再输出带警告的格式化文本。测试把它和预期字符串比较。

调用关系：它是字节截断的核心行为测试。运行时由测试框架触发，最后靠 assert_eq! 验证实际结果和约定格式一致。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_bytes_reports_original_line_count_when_truncated()

作用：确认多行文本被按字节截断后，提示里报告的是原始总行数，而不是截断后剩下的行数。这样用户知道原来输出有几行。

数据流：进去的是两行长文本和 30 字节限制。截断流程删掉中间一大段，但仍统计原文有 2 行，并把这个数字写进警告。输出应该包含保留下来的开头、结尾和正确行数。

调用关系：它补充验证字节截断里的统计信息。assert_eq! 负责确认行数提示和截断文本都没有偏差。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_tokens_reports_original_line_count_when_truncated()

作用：确认按 token 截断多行文本时，警告里仍然显示原始行数。这个细节能帮助用户判断被省略内容的大致规模。

数据流：输入是两行文字和 10 个 token 的限制。截断逻辑计算原文 token 数和行数，再生成带省略提示的文本。输出应说明总行数是 2，并显示省略了 11 个 token。

调用关系：它和按字节的行数测试成对出现，保证两种截断策略都遵守同一条用户可见规则。结果由 assert_eq! 检查。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_middle_bytes_handles_utf8_content()

作用：检查截断含有 emoji 的文字时不会把字符切坏。UTF-8 是一种常见文字编码，一个 emoji 可能占多个字节，所以从错误位置切会产生乱码。

数据流：输入是一串 emoji 加普通文字，以及 20 字节的限制。测试调用 truncate_text 做实际截断。输出应保留完整 emoji 和正常文字，中间用“21 chars truncated”说明删减，没有半个 emoji 或乱码。

调用关系：这个测试直接调用 truncate_text，并用 Bytes 创建按字节的策略。它把最容易出编码问题的场景交给底层截断函数，再由 assert_eq! 验证结果。

调用图：外部调用 3 个（assert_eq!, truncate_text, Bytes）。

fn truncates_across_multiple_under_limit_texts_and_reports_omitted()

作用：检查一组函数输出内容整体超限时，程序会按整组内容来截断，而不是只看单个文本块。它还确认被整个跳过的文本块会被汇总说明。

数据流：进去的是多段文本、一张图片和一个按 token 算出的总限制。测试先用 approx_token_count 估算一段文本的大小，再构造内容列表。截断后，前两段短文本和中间图片应保留，长文本应被缩短，最后还应追加一段说明，告诉用户有 2 个文本项被省略。

调用关系：这是多内容项截断的综合测试。它调用 truncate_function_output_items_with_policy 来处理整组输出，必要时用 panic! 报告项目类型不符合预期，并用 assert!、assert_eq! 检查长度、图片保留和省略提示。

调用图：外部调用 7 个（assert!, assert_eq!, approx_token_count, truncate_function_output_items_with_policy, panic!, Tokens, vec!）。

fn formatted_truncate_text_content_items_with_policy_returns_original_under_limit()

作用：确认一组文本内容总大小没有超限时，格式化截断函数会原样返回这些内容。它也确认这时不会报告“原始 token 数”，因为根本没有发生截断。

数据流：输入是三个文本项，其中一个是空字符串，以及 32 字节限制。函数检查后认为整体在范围内，于是输出仍是原来的列表，附带的 original_token_count 是 None，表示没有截断统计需要说明。

调用关系：这个测试调用 formatted_truncate_text_content_items_with_policy，它关注的是带警告格式的内容项处理。Bytes 创建限制策略，vec! 构造输入列表，assert_eq! 验证输出和统计值。

调用图：外部调用 4 个（assert_eq!, formatted_truncate_text_content_items_with_policy, Bytes, vec!）。

fn formatted_truncate_text_content_items_with_policy_preserves_empty_leading_text_behavior()

作用：检查开头有空文本、后面才有内容时，截断后的行为仍然稳定。这个边界情况容易让行数、开头内容或省略提示算错。

数据流：输入是一个空文本项加一个“abc”文本项，字节限制为 0。函数会把可截断的文本合并考虑，发现必须全部压缩成提示。输出只剩一个带警告的文本项，说明原始 token 数为 1、总行数为 1、删掉了 3 个字符。

调用关系：它专门验证 formatted_truncate_text_content_items_with_policy 对空开头文本的兼容性。测试用 Bytes 设定极小预算，用 assert_eq! 同时检查输出列表和返回的 token 统计。

调用图：外部调用 4 个（assert_eq!, formatted_truncate_text_content_items_with_policy, Bytes, vec!）。

fn formatted_truncate_text_content_items_with_policy_merges_text_and_appends_images()

作用：确认多段文本夹着图片时，文本会合并后统一截断，而图片不会丢失，并且会跟在截断后的文本后面。这样既控制文字长度，又保留非文字内容。

数据流：输入是文本“abcd”、一张图片、两段文本“efgh”“ijkl”和另一张图片，限制是 8 字节。函数把所有文本按顺序合并计算，生成一个带警告的截断文本；两张图片作为独立内容保留下来并追加在后面。返回的 original_token_count 是 Some(4)，表示确实发生了截断。

调用关系：这个测试覆盖混合内容的格式化截断。它调用 formatted_truncate_text_content_items_with_policy，输入由 vec! 组成，最后用 assert_eq! 确认文本合并、图片保留和统计值都符合约定。

调用图：外部调用 4 个（assert_eq!, formatted_truncate_text_content_items_with_policy, Bytes, vec!）。

fn formatted_truncate_text_content_items_with_policy_preserves_encrypted_content()

作用：检查内容里有加密数据时，截断只动普通文本，不改加密内容。加密内容可以理解成一段不能拆开看的密封包，改一个字都可能失效。

数据流：输入是一段普通文本和一个 EncryptedContent，加 2 字节限制。函数把普通文本格式化截短，生成带警告的文本项；加密字符串“enc_opaque”原封不动地跟在后面。返回的 token 统计说明发生了截断。

调用关系：它验证 formatted_truncate_text_content_items_with_policy 在处理敏感或不透明内容时不会乱改。Bytes 提供限制，assert_eq! 确认文本被截断而加密项保持原样。

调用图：外部调用 4 个（assert_eq!, formatted_truncate_text_content_items_with_policy, Bytes, vec!）。

fn truncate_function_output_items_with_policy_preserves_encrypted_content()

作用：检查普通的函数输出截断也会保留加密内容，不会尝试裁剪或重写它。它和格式化版本的测试一起防止加密数据被破坏。

数据流：输入是一段“abcdefgh”和一个加密内容项，限制是 2 字节。truncate_function_output_items_with_policy 会把普通文本变成“a…6 chars truncated…h”，同时让加密内容保持完全不变。输出是处理后的内容列表。

调用关系：这个测试直接覆盖非格式化的内容项截断路径。它调用 truncate_function_output_items_with_policy，使用 Bytes 策略，再用 assert_eq! 验证只改了普通文本。

调用图：外部调用 4 个（assert_eq!, truncate_function_output_items_with_policy, Bytes, vec!）。

fn formatted_truncate_text_content_items_with_policy_merges_all_text_for_token_budget()

作用：确认按 token 限制时，多段文本会先合并成一个整体来算预算。这样不会因为每一段单独看都还行，合起来却超了而漏截。

数据流：输入是两段各 8 个字符的文本，限制是 2 个 token。函数把两段文本按顺序合并，计算原始约 5 个 token，然后生成一个带警告的截断文本，保留开头“abcd”和结尾“mnop”，中间说明省略了 3 个 token。

调用关系：它测试 formatted_truncate_text_content_items_with_policy 的 token 预算路径。Tokens 创建限制策略，vec! 构造文本列表，assert_eq! 确认合并、截断提示和 original_token_count 都正确。

调用图：外部调用 4 个（assert_eq!, formatted_truncate_text_content_items_with_policy, Tokens, vec!）。

fn byte_count_conversion_clamps_non_positive_values()

作用：检查把字节数粗略换算成 token 数时，负数和零不会产生奇怪结果，而是都当成 0。这样上层传入异常大小时，估算函数也不会报出不合理的 token 数。

数据流：输入分别是 -1、0 和 5 这三个字节数。测试调用换算逻辑并比较结果：非正数变成 0，5 字节大约换成 2 个 token。输出没有保存状态，只是验证返回值。

调用关系：这是底层估算规则的边界测试。它通过 assert_eq! 固定 approx_tokens_from_byte_count_i64 的行为，帮助其他截断测试依赖稳定的 token 估算。

调用图：外部调用 1 个（assert_eq!）。

fn file_uri_round_trips_an_absolute_path()

作用：检查一个当前系统上的绝对路径，变成 file URI 后还能原样变回路径。这样能保证最常见的路径转换不会把空格、目录名或文件名弄坏。

数据流：输入是当前目录加上“a path/file.rs”这个路径 → 测试把它交给 PathUri::from_abs_path 转成 URI 字符串，再用 PathUri::parse 读回来，并调用 to_abs_path 转回本地路径 → 输出是几次断言：URI 以 file: 开头、空格被正确写成 %20、重新解析后相等、转回的路径也相等。

调用关系：这是 PathUri 最基础的往返测试。它先用 current_dir 拿到真实绝对路径，再把主要工作交给 from_abs_path、parse 和 to_abs_path，最后用断言确认整条链路闭合。

调用图：调用 2 个内部函数（current_dir, from_abs_path）；外部调用 2 个（assert!, assert_eq!）。

fn non_native_uri_io_conversion_is_invalid_input()

作用：确认“看起来合法但不适合当前操作系统”的 file URI，不能被硬转成本机路径。这样可以避免在 Unix 上误收 Windows 网络路径，或在 Windows 上误收 Unix 路径。

数据流：输入是按平台选择的一条异系统 URI → 测试先解析成 PathUri，再尝试 to_abs_path → 结果应该是 InvalidInput 错误，并且错误信息说明这个 URI 在当前操作系统上无效。

调用关系：它验证 parse 只负责识别 URI 是否格式合法，而 to_abs_path 还要判断能不能变成本机路径；两层检查各司其职。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_parses_a_windows_path_on_any_host()

作用：确认 Windows 盘符形式的 file URI 在任何系统上都能被解析。即使当前机器不是 Windows，也应该能读懂这种外来地址。

数据流：输入是 file:///C:/Users/Alice%20Smith/src/main.rs → parse 生成 PathUri → 测试读取编码后的路径、文件名和重新输出的字符串 → 结果应保留 C: 盘符、正确解出 main.rs，并保持规范写法。

调用关系：它主要检查 PathUri::parse 的跨平台理解能力，后续 basename 和 to_string 的行为都建立在这个解析结果上。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn infers_path_conventions_from_uri_shape()

作用：检查 PathUri 能不能从 URI 的外形猜出它更像 Unix 路径还是 Windows 路径。这个判断对显示、转换外来路径很有用。

数据流：输入是一组不同形状的 file URI，包括根目录、盘符、服务器共享路径和备用编码路径 → 每个都先 parse，再调用 infer_path_convention → 输出是 Some(Posix)、Some(Windows) 或 None，表示猜到的路径习惯或猜不出来。

调用关系：这个测试把 parse 当作入口，再验证 infer_path_convention 这个判断器；它覆盖普通 URI 和特殊 fallback URI，防止规则只在简单路径上有效。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn drive_shaped_posix_uri_is_intentionally_inferred_as_windows()

作用：说明一个有意设计：像 /C:/... 这样的 URI 虽然在 Unix 上也可能是普通路径，但这里会优先当作 Windows 路径。这样更符合大多数跨系统场景。

数据流：输入是 file:///C:/actually/a/posix/path → parse 后调用 infer_path_convention → 输出应为 Windows，而不是 Posix。

调用关系：它补充说明上一条推断规则的边界：当路径形状像 Windows 盘符时，PathUri 会把使用者更常见的需求放在前面。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_falls_back_for_windows_prefixes_without_a_uri_representation()

作用：在 Windows 上，检查一些特殊系统路径无法正常写成标准 file URI 时，会走备用编码。这样这些路径仍然可以被安全保存和恢复。

数据流：输入是 Windows 的设备路径或命名空间路径 → from_absolute_path_checked 先确认它们是绝对路径，from_abs_path 再转成 URI → 输出应是以特殊 bad path 前缀开头的编码 URI，并且重新 parse 后 to_abs_path 能还原原路径。

调用关系：这个测试只在 Windows 编译运行。它验证 from_abs_path 的兜底路线，也验证 parse 和 to_abs_path 能把这条兜底路线接回来。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 1 个（assert_eq!）。

fn file_uri_fallback_round_trips_non_unicode_windows_paths()

作用：在 Windows 上，确认不是合法 Unicode 文字的路径也能通过备用编码来回转换。这样不会因为文件名含有奇怪底层字符就丢失路径。

数据流：输入是手工构造的一段 Windows UTF-16 路径，其中包含无效代理码 → 它被做成 PathBuf 并检查为绝对路径，再转为 PathUri、转成字符串、重新 parse → 输出应以 bad path 前缀开头，并且解回的绝对路径和原来完全一样。

调用关系：它把 from_wide 构造出的非常规路径交给 from_abs_path，随后用 parse 和 to_abs_path 检查备用编码方案是否真的无损。

调用图：调用 3 个内部函数（from_absolute_path_checked, from_abs_path, parse）；外部调用 4 个（from_wide, from, assert!, assert_eq!）。

fn file_uri_falls_back_for_posix_paths_with_null_bytes()

作用：在 Unix 上，检查包含空字节或非 UTF-8 字节的路径会使用备用编码。普通 URI 放不下这些内容，所以必须有安全兜底。

数据流：输入是字节形式的 Unix 路径 /tmp/null-\0-\xff-byte → 它被转成绝对路径，再由 from_abs_path 变成特殊 fallback URI → 输出要等于预期 URI；序列化成 JSON 后再反序列化，也要保持相同，并且能解回原路径。

调用关系：这个测试串起了 from_abs_path、serde_json 的 to_string/from_str、PathUri::parse 和 to_abs_path，证明备用路径不仅能转换，也能存进 JSON 再读出。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 5 个（from, assert_eq!, from_str, to_string, from_vec）。

fn ordinary_bad_path_uri_is_not_decoded_as_a_fallback()

作用：确认普通路径里如果刚好长得像 bad/path 编码片段，不会被误认为备用编码。这样真实文件夹名不会被系统擅自“解码”。

数据流：输入是 Unix 上的普通绝对路径 /bad/path/L3RtcC9udWxsLQAt_y1ieXRl → from_abs_path 生成正常 file URI → to_abs_path 再转回来 → 结果应按字面意思处理，而不是当作 fallback 内容。

调用关系：它保护 fallback 机制的边界：只有带有特定前缀的 URI 才会被特殊处理，普通 from_abs_path 结果仍走普通路径逻辑。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 1 个（assert_eq!）。

fn malformed_bad_path_uris_are_rejected()

作用：检查各种写坏的备用编码 URI 会被拒绝。这样系统不会吞下半截编码、非法字符或伪装路径。

数据流：输入是一组格式不完整或编码不规范的 bad path URI 字符串 → 逐个交给 PathUri::parse → 输出都应是 InvalidFileUriPath 错误，并带上原始路径内容。

调用关系：它专门守住 parse 的入口，确保 fallback URI 只有符合严格格式时才会进入后续转换流程。

调用图：外部调用 1 个（assert_eq!）。

fn structurally_valid_bad_path_uri_with_invalid_native_payload_fails_conversion()

作用：确认一个格式看似正确、但里面编码出来不是合法本机绝对路径的 fallback URI，解析可以过，转换成本地路径必须失败。

数据流：输入是 file:///%00/bad/path/YQ → parse 接受它为规范 base64 fallback URI → to_abs_path 尝试解成路径 → 输出应是 InvalidInput 错误，因为内容不构成合法绝对路径。

调用关系：它区分了两件事：parse 只看 URI 外壳和编码格式，to_abs_path 才检查里面的路径对当前系统是否真的可用。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn bad_path_uris_are_opaque_to_lexical_operations()

作用：确认 fallback URI 对普通路径操作是不透明的，也就是不能随便取文件名、取父目录或拼子路径。因为它里面是编码包，不是真正的目录层级。

数据流：输入是一个 fallback URI → parse 后分别调用 basename、parent 和 join → 输出应是没有文件名、没有父目录；拼空字符串可以保持原样，拼 child 会报 InvalidFileUriPath。

调用关系：它验证 PathUri 的路径小工具不会误拆 fallback 编码内容；join 只有在不改变它时才允许通过。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_parses_a_posix_path_on_any_host()

作用：确认 Unix 风格的 file URI 在任何系统上都能被解析。这样 Windows 主机也可以读懂来自 Unix 的路径地址。

数据流：输入是 file:///home/alice/src/main.rs → parse 生成 PathUri → 测试检查 encoded_path、basename 和 to_string → 输出应保持原路径层级，并得到 main.rs 这个文件名。

调用关系：它和 Windows 路径测试成对出现，说明 PathUri 的解析目标是跨平台，而不是只服务当前操作系统。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_preserves_paths_that_resemble_windows_paths()

作用：确认像 /C:/Project 这种长得像 Windows 盘符的 URI，在字符串层面不会被改写。这样解析和重新输出不会偷偷改变用户写的路径。

数据流：输入是 file:///C:/Project 和 file:///C: → parse 后再 to_string 并重新 parse → 输出的 encoded_path 要保持 /C:/Project 或 /C:，重新解析后也和原对象相等。

调用关系：它补充 Windows 形状路径的处理规则：可以推断为 Windows，但 URI 的原始层级仍要稳定保留。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_accepts_non_utf8_posix_paths()

作用：在 Unix 上，确认包含非 UTF-8 字节的路径也能被转换和解析。Unix 文件名可以是任意字节，不能假设它一定是正常文字。

数据流：输入是字节路径 /tmp/non-utf8-\xff → from_absolute_path_checked 确认为绝对路径，from_abs_path 转成 URI → to_abs_path 应还原原路径，URI 字符串重新 parse 后也应相等。

调用关系：它测试 Unix 路径字节和 URI 百分号编码之间的衔接，主要覆盖 from_abs_path、to_abs_path 和 parse 的无损往返。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 3 个（from, assert_eq!, from_vec）。

fn file_uri_round_trips_literal_percent_characters()

作用：确认文件路径里的真实百分号不会在解析和输出时被弄错。URI 里百分号有转义含义，所以这里很容易出错。

数据流：输入是 file:///tmp/100%25/file，其中 %25 表示真实的百分号 → parse 后检查 to_string、encoded_path 和 basename → 输出应仍保留 %25，并且文件名是 file。

调用关系：它验证 parse 不会把百分号转义处理过头，也验证 to_string 会保持规范编码。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_round_trips_windows_unc_paths()

作用：在 Windows 上，检查网络共享路径，也就是 UNC 路径，能正确变成 file URI 并转回去。UNC 路径类似 \\server\share\file，是 Windows 常见的网络文件地址。

数据流：输入是 \\server\share\src\main.rs → from_absolute_path_checked 确认为绝对 UNC 路径，from_abs_path 转成 URI → encoded_path 应是 /share/src/main.rs，to_abs_path 应恢复原 UNC 路径。

调用关系：它只在 Windows 上运行，专门覆盖 from_abs_path 对 UNC authority，也就是服务器名部分的处理。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 1 个（assert_eq!）。

fn file_uri_retains_unc_authority()

作用：确认 file URI 里的服务器名不会丢失。对于 file://server/share 这种地址，server 是关键位置。

数据流：输入是 file://server/share/src/main.rs → parse 成 PathUri → 检查 encoded_path 和 to_string → 输出应保留 /share/src/main.rs，也保留 file://server 这个服务器部分。

调用关系：它测试 parse 和 to_string 对 UNC authority 的保存，和 Windows UNC 本地路径转换测试互相补充。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn file_uri_spelling_aliases_have_one_canonical_form()

作用：确认几种等价写法会被统一成一种标准写法。这样后续比较 URI 时，不会因为大小写或 localhost 写法不同而误判不同。

数据流：输入包括 FILE:///workspace/src、file:/workspace/src、file://localhost/... 等别名 → parse 后转成字符串 → 输出都应该是 file:///workspace/src。

调用关系：它验证 PathUri::parse 的规范化能力：入口可以宽容接受常见写法，但内部和输出统一使用标准形式。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn unsupported_schemes_are_rejected_at_construction()

作用：确认 PathUri 只接受文件路径 URI，不接受 http、ssh、artifact 等其他协议。这样这个类型不会被误用来表示远程地址或非文件资源。

数据流：输入是一组非 file 开头的 URI → 逐个调用 PathUri::parse → 输出都应失败，并返回 UnsupportedScheme，错误里带着实际协议名。

调用关系：它守住 PathUri 的创建入口，保证后面的路径函数只面对本地文件语义，不需要处理网络或编辑器临时文档协议。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert!）。

fn path_uri_serializes_as_a_string()

作用：确认 PathUri 存成 JSON 时就是一个字符串，读回来还是同一个 PathUri。这样配置、缓存或接口里保存它会很直观。

数据流：输入是 file:///workspace/src/lib.rs → 通过字符串解析成 PathUri，再用 serde_json 转成 JSON 字符串，之后再从 JSON 读回 → 输出 JSON 应是带引号的 URI 字符串，反序列化结果应和原对象相等。

调用关系：它验证 PathUri 和 serde_json 的配合，说明序列化层不会发明额外结构，只把 PathUri 交给字符串格式保存。

调用图：外部调用 3 个（assert_eq!, from_str, to_string）。

fn path_uri_deserializes_legacy_absolute_paths()

作用：确认老格式里的绝对本地路径仍能被当成 PathUri 读进来。这样升级代码后，旧数据不会立刻坏掉。

数据流：输入是当前目录下的 workspace/src 绝对路径，并先按旧方式序列化成 JSON → serde_json 再把它读成 PathUri → 输出应等于 PathUri::from_abs_path 对同一路径生成的结果。

调用关系：它连接了旧的 AbsolutePathBuf JSON 格式和新的 PathUri 格式，是兼容性测试；current_dir 提供真实绝对基准，from_abs_path 提供期望值。

调用图：调用 1 个内部函数（current_dir）；外部调用 3 个（assert_eq!, from_str, to_string）。

fn path_uri_rejects_relative_native_paths()

作用：确认相对路径不能直接变成 PathUri。PathUri 表示的是明确位置，不能是“从当前目录算起”的模糊地址。

数据流：输入是 src/lib.rs 这个相对路径 → 调用 PathUri::from_path → 输出应是 InvalidInput 错误。

调用关系：它测试 from_path 的入口校验，防止调用者把不稳定的相对路径混进 PathUri 系统。

调用图：调用 1 个内部函数（from_path）；外部调用 1 个（assert_eq!）。

fn path_uri_rejects_legacy_relative_paths_with_absolute_path_guard()

作用：确认即使在兼容旧 JSON 路径格式时，相对路径也会被拒绝。这样旧格式兼容不会降低安全和明确性要求。

数据流：输入是 JSON 字符串 "src/lib.rs"，同时用 AbsolutePathBufGuard 设置当前绝对路径检查环境 → 反序列化成 PathUri 应失败 → 错误信息应包含“path is not absolute”。

调用关系：它针对反序列化入口做防护测试；AbsolutePathBufGuard 像临时检查员，确保 legacy 路径也必须通过绝对路径规则。

调用图：调用 2 个内部函数（current_dir, new）；外部调用 1 个（assert!）。

fn unsupported_scheme_is_rejected_during_deserialization()

作用：确认从 JSON 读 PathUri 时，也会拒绝不支持的协议。不能只在手动 parse 时检查。

数据流：输入是 JSON 字符串 "artifact://store/object-1" → serde_json 尝试反序列化成 PathUri → 输出应失败，错误文字里说明 artifact 协议不支持。

调用关系：它覆盖 serde_json 这条入口，保证反序列化内部也会走和 PathUri::parse 一致的协议限制。

调用图：外部调用 1 个（assert!）。

fn known_path_uris_reject_queries_and_fragments()

作用：确认 file URI 不能带查询参数或片段。路径 URI 只表示文件位置，不表示版本号、网页锚点或行号。

数据流：输入分别是带 ?version=1 和带 #L1 的 file URI → 调用 PathUri::parse → 输出分别应是 QueryNotAllowed 和 FragmentNotAllowed 错误。

调用关系：它守住 parse 的语义边界，防止 URI 元数据被误当作文件名的一部分，或被后续路径操作忽略。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert!）。

fn path_uris_reject_encoded_null_bytes()

作用：确认普通 file URI 里不能出现编码后的空字节 %00。空字节在很多系统接口里有特殊危险含义。

数据流：输入是 file:///tmp/%00 → 调用 PathUri::parse → 输出应是错误，而不是一个可用 PathUri。

调用关系：它和 fallback URI 测试形成对比：特殊空字节只能在严格的备用编码通道里出现，普通路径通道必须拒绝。

调用图：外部调用 1 个（assert!）。

fn encoded_filename_characters_round_trip_without_becoming_uri_metadata()

作用：确认文件名里的问号、井号和百分号，如果已经按 URI 规则编码，就仍然只是文件名文字，不会变成查询参数或片段。

数据流：输入是 file:///tmp/a%3Fb%23c%25d → parse 后检查 to_string、encoded_path 和 basename → 输出应保持编码形式，文件名解码后是 a?b#c%d。

调用关系：它验证 parse 能区分“URI 结构里的 ?/#”和“文件名里编码后的 ?/#”，避免误拆文件名。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn double_encoded_separator_remains_filename_text()

作用：确认双重编码的斜杠不会被当作目录分隔符。这样文件名里写着 %2F 时，不会被错误拆成两级目录。

数据流：输入是 file:///tmp/a%252Fb，其中 %25 解开后才是百分号 → parse 后检查字符串、编码路径和 basename → 输出的文件名应是 a%2Fb，而不是 a/b。

调用关系：它测试 URI 解码只做该做的一层，不把已经作为文件名文本的内容继续当路径结构处理。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn basename_uses_decoded_uri_segments()

作用：确认 basename 取到的是最后一段路径，并且会把 URI 编码解成人能读的文字。basename 就是“最后的文件名或目录名”。

数据流：输入是一组 file URI，包括根目录、普通文件、带空格编码的文件、Windows 盘符和服务器共享路径 → parse 后调用 basename → 输出应是 None 或解码后的最后一段名称。

调用关系：它验证 PathUri::basename 依赖 parse 后的路径层级，并使用解码后的段名给调用者更自然的结果。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn parent_uses_uri_hierarchy_and_preserves_authority()

作用：确认 parent 能按 URI 层级取父路径，并且不会丢掉服务器名。parent 就像问“这个文件上一层文件夹是哪一个”。

数据流：输入是一组本地和 UNC file URI → 每个 parse 后调用 parent，并把预期父 URI 也 parse 成 PathUri → 输出应和预期相等；根目录没有父级。

调用关系：它测试 PathUri::parent 的层级规则，尤其是 file://server/... 这种带 authority 的 URI，确保向上走一层时仍留在同一台服务器下。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn join_normalizes_relative_uri_segments()

作用：确认 join 可以把相对路径接到基础 URI 后面，并整理 .. 这样的上级目录符号。join 就像从一个文件夹出发，按相对路线走到新位置。

数据流：输入是一组基础 file URI、相对路径和预期结果 → 基础 URI 与预期 URI 都先 parse，随后 base.join(relative) → 输出应等于预期，并且特殊字符会被正确编码。

调用关系：它验证 PathUri::join 是构建子路径和相邻路径的主要工具；parse 提供起点和对照结果，join 负责规范化相对层级。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn join_rejects_absolute_and_null_paths()

作用：确认 join 只接受相对路径，不接受以 / 开头的绝对路径，也不接受带空字节的路径。这样拼接时不会突然跳到别的位置或引入危险字符。

数据流：输入是基础 URI file:///workspace，以及两个非法待拼接字符串 /src 和 src\0file → parse 得到基础 PathUri，再调用 join → 输出分别应是 JoinPathMustBeRelative 错误和 InvalidFileUriPath 错误。

调用关系：它补充 join 的失败场景，和前一个正常 join 测试一起说明：join 可以整理相对路线，但不会接受越界或非法输入。

调用图：调用 1 个内部函数（parse）；外部调用 2 个（assert!, assert_eq!）。

fn to_url_returns_the_validated_url()

作用：确认 PathUri 可以拿出内部已经校验过的 Url 对象。Url 是通用 URI/URL 类型，这里要保证拿出来的是规范后的 file URL。

数据流：输入是 file://localhost/workspace/a%20file.rs → parse 会把 localhost 规范化为本地 file URI → 调用 to_url → 输出应等于 Url::parse 得到的 file:///workspace/a%20file.rs。

调用关系：它验证 PathUri 和底层 Url 类型的连接点：PathUri 先负责校验和规范化，to_url 再把这个安全结果交给需要通用 Url 的代码。

调用图：调用 1 个内部函数（parse）；外部调用 1 个（assert_eq!）。

fn round_trips(
        uri: &'static str,
        convention: PathConvention,
        rendered: &'static str,
    ) -> Self

作用：这个小工具用来创建一种测试案例：一个 URI 转成普通路径后，还应该能原样转回同一个 URI。也就是测试“来回翻译不走样”。

数据流：进去的是 URI 文本、路径约定，以及期待渲染出的普通路径文本。它把这些信息装进一个 RenderCase，并把期待结果标成 RoundTrip。出来的是一个完整测试用例，后面的主测试会用它来做双向检查。

调用关系：它主要服务于 renders_native_paths_from_shared_cases。测试数据表里大量正常案例都用它创建；主测试拿到这些案例后，会调用 parse 把 URI 读成 PathUri，再调用 from_path_uri 渲染，并在成功后尝试反向解析。

调用图：外部调用 1 个（RoundTrip）。

fn rejects(uri: &'static str, convention: PathConvention, error: ExpectedError) -> Self

作用：这个小工具用来创建一种测试案例：某个 URI 按指定系统风格解释时应该失败。它防止代码把明显不合适的路径强行当成合法路径。

数据流：进去的是 URI 文本、路径约定，以及期待的错误类型。它把这些信息装进 RenderCase，并把期待结果标成 Error。出来的是一个“应该报错”的测试用例。

调用关系：它被测试数据表用来描述边界和错误场景。renders_native_paths_from_shared_cases 遇到这类案例时，会检查 from_path_uri 返回的错误是不是 OpaqueFallback 或 IncompatibleConvention 这一类预期错误。

调用图：外部调用 1 个（Error）。

fn renders_lossily(
        uri: &'static str,
        convention: PathConvention,
        rendered: &'static str,
    ) -> Self

作用：这个小工具用来创建一种测试案例：URI 可以渲染成普通路径，但这个过程会丢掉一些原始信息，所以不要求再转回完全相同的 URI。

数据流：进去的是 URI 文本、路径约定，以及期待看到的普通路径文本。它把期待结果标成 RenderOnly。出来的是一个只检查“渲染结果”的测试用例，不做完整往返检查。

调用关系：它用于那些现实中能显示给用户看、但不能无损还原的路径，比如非法 UTF-8 字节被替换成 U+FFFD，或者 URI 里的转义斜杠变成了真正的路径分隔符。renders_native_paths_from_shared_cases 会只验证渲染结果，不再要求反向转换一致。

调用图：外部调用 1 个（RenderOnly）。

fn renders_native_paths_from_shared_cases()

作用：这是本文件最核心的测试。它把共享案例表里的每个 URI 都拿来试，检查它在 POSIX 或 Windows 规则下会变成什么普通路径，或者是否应该报错。

数据流：进去的是 RENDER_CASES 里预先写好的大量例子。每个例子先用 parse 变成 PathUri，再用 from_path_uri 按指定路径约定渲染成 LegacyAppPathString。然后它把实际结果和预期结果比较；如果这是 RoundTrip 案例，还会把普通路径从 JSON 字符串读回来，再转回 PathUri，确认没有变形。

调用关系：它串起了这个文件里最重要的验证链条：RenderCase::round_trips、RenderCase::rejects 和 RenderCase::renders_lossily 负责造数据；它负责执行；parse、from_path_uri、JSON 反序列化和断言负责证明路径翻译规则是对的。

调用图：调用 2 个内部函数（parse, from_path_uri）；外部调用 2 个（assert_eq!, json!）。

fn relative_api_path_serializes_and_deserializes_unchanged()

作用：这个测试确认相对路径，比如 subdir/file.rs，作为 API 字符串保存和读取时不会被改写。它关心的是“字符串本身别被动手脚”。

数据流：进去的是几个相对路径文本。测试把它们从 JSON 字符串读成 LegacyAppPathString，再写回 JSON。出来的 JSON 必须和原始文本完全一样，没有补斜杠、没有变成绝对路径、没有做系统风格判断。

调用关系：它只测试序列化和反序列化这条轻量路径，和后面“相对路径不能转成 PathUri”的测试配合：这里说明可以保存相对路径文本，后面说明不能把它当作绝对文件 URI 使用。

调用图：外部调用 2 个（assert_eq!, json!）。

fn relative_api_path_is_invalid_when_converted_to_a_path_uri()

作用：这个测试确认相对路径不能被转换成 PathUri。因为 PathUri 表示的是明确的文件位置，相对路径缺少“从哪里开始”的信息。

数据流：进去的是 raw_path = subdir。测试先从 JSON 读成 LegacyAppPathString，然后检查它推断不出绝对路径约定；接着尝试按 POSIX 转成 PathUri，结果应该是 InvalidNativePath 错误。它不会产出合法 URI，只产出预期错误。

调用关系：它验证 to_path_uri 的防线。relative_api_path_serializes_and_deserializes_unchanged 证明相对路径可以作为普通 API 文本存在；这个测试进一步证明，当代码需要绝对文件 URI 时，不会误收这种不完整路径。

调用图：外部调用 2 个（assert_eq!, json!）。

fn other_non_absolute_api_paths_cannot_be_converted_to_path_uris()

作用：这个测试检查一些看起来像路径、但其实不是绝对路径的 Windows 写法不能转成 PathUri。它防止半截路径被误当成真实文件位置。

数据流：进去的是 workspace\file.rs 和 C:file.rs 这类文本，以及 Windows 路径约定。测试把文本读成 LegacyAppPathString，确认推断不出绝对路径约定，再调用 to_path_uri。出来的结果必须是 InvalidNativePath 错误。

调用关系：它补充了相对路径的错误测试，专门覆盖 Windows 容易混淆的写法。它依赖 JSON 读入路径文本，再用 to_path_uri 触发合法性检查。

调用图：外部调用 2 个（assert_eq!, json!）。

fn infers_absolute_path_conventions_from_api_text()

作用：这个测试检查代码能不能只看一段路径文字，就判断它像 Windows 绝对路径、POSIX 绝对路径，还是根本不是绝对路径。

数据流：进去的是一组原始路径文本和期待判断结果，比如 C:\workspace\file.rs 应该是 Windows，/workspace/file.rs 应该是 POSIX，subdir/file.rs 应该是 None。测试把每个文本读成 LegacyAppPathString，再调用 infer_absolute_path_convention。出来的是 Some(Windows)、Some(Posix) 或 None，并和预期比较。

调用关系：它验证的是路径转换前的“识别步骤”。其他测试在真正转换前也会用到这种判断，特别是判断一个 API 字符串是否足够明确、能不能安全地转成 PathUri。

调用图：外部调用 2 个（assert_eq!, json!）。

fn foreign_absolute_syntax_deserializes_without_host_interpretation()

作用：这个测试确认 API 路径字符串读入时不会被当前运行机器擅自解释。比如在 Unix 机器上读到 Windows 路径，也应该原样保存。

数据流：进去的是 Windows 风格的 C:\workspace\file.rs 和 POSIX 风格的 /workspace/file.rs。测试从 JSON 读入后，检查 as_str 仍然等于原文，并检查能推断出对应的路径约定。出来的是原样保留的 LegacyAppPathString。

调用关系：它保护了跨平台场景：API 收到的路径可能来自别的系统。这个测试确保反序列化只保存文字，不会因为当前主机是 Windows 或 Unix 就改写含义。

调用图：外部调用 2 个（assert_eq!, json!）。

fn renders_an_absolute_path_using_the_host_convention()

作用：这个测试检查从本机的绝对路径对象转换成 API 路径字符串时，会按当前操作系统的自然写法显示。

数据流：进去的是根据编译平台选择的本机绝对路径：Unix 上是 /workspace/a file.rs，Windows 上是 C:\workspace\a file.rs。测试先用 from_absolute_path_checked 确认它真的是绝对路径，再转换成 LegacyAppPathString。出来的字符串应该和本机原始路径文字一致。

调用关系：它验证 From<AbsolutePathBuf> 这条转换入口。和从 PathUri 渲染的测试不同，这里直接从本机路径对象出发，确认给 API 的路径文本不会变成另一种平台风格。

调用图：调用 1 个内部函数（from_absolute_path_checked）；外部调用 1 个（assert_eq!）。

fn renders_native_non_unicode_windows_fallback_lossily()

作用：这是只在 Windows 上运行的测试，检查遇到不是正常 Unicode 文本的本机路径时，代码会用替代字符 U+FFFD 尽量显示，而不是崩溃。Unicode 可以理解成常用的文字编码规则；有些系统路径可能不完全符合它。

数据流：进去的是一个用 from_wide 手工造出的 Windows 路径，里面包含无效的 UTF-16 片段。测试把它变成 AbsolutePathBuf，再用 from_abs_path 渲染成 LegacyAppPathString，期望坏字符显示为 U+FFFD。接着它把同一路径变成 PathUri，再分别按 Windows 和 POSIX 规则渲染：Windows 下可以得到带 U+FFFD 的路径，POSIX 下应该返回 OpaqueFallback 错误。

调用关系：它覆盖普通测试数据不容易造出的 Windows 特殊情况。它调用 from_abs_path 和 PathUri::from_abs_path，说明当路径无法用干净文字表达时，系统会走“兜底表示”；from_path_uri 再决定这种兜底能否按指定平台还原。

调用图：调用 2 个内部函数（from_absolute_path_checked, from_abs_path）；外部调用 3 个（assert_eq!, from_wide, from）。

fn serializes_and_deserializes_as_a_string()

作用：这个测试确认 LegacyAppPathString 在 JSON 里就是一个普通字符串，而不是复杂对象。这样外部 API 使用起来更简单，也更容易兼容旧格式。

数据流：进去的是 file:///workspace/src/lib.rs 这个 URI。测试先 parse 成 PathUri，再用 from_path_uri 渲染成 POSIX 普通路径，然后用 to_string 写成 JSON 文本。出来的 JSON 应该是 "/workspace/src/lib.rs"；再从这个 JSON 读回来，也应该得到同一个 LegacyAppPathString。

调用关系：它验证 API 边界上的格式。前面的测试关心路径含义是否正确，这个测试关心传输形态是否简单稳定：路径对象经过 JSON 发送和接收后，不会丢失或变成别的结构。

调用图：调用 2 个内部函数（parse, from_path_uri）；外部调用 2 个（assert_eq!, to_string）。