docs(tests): correct ownership and reader failure explanations

crates/frontend/tests/reader.rs

@@ -60,7 +60,7 @@ fn strings_and_split_utf8_streams_produce_the_same_ast_and_exact_text() {
     // Reader 不剥除 BOM，词法器看到原始开头字符后才决定是否接受。
     let bom = EndorReader::from_stream("<bom>", Cursor::new("\u{feff}1".as_bytes())).unwrap();
     assert_eq!(bom.text(), "\u{feff}1");
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // BOM 保留了三字节 UTF-8 编码，词法错误范围应恰好覆盖它，而不是 Reader 静默剥除。
     let error = lex_source(&bom).unwrap_err();
     assert_eq!(error.diagnostic.kind, DiagnosticKind::Lexical);
     assert_eq!(error.diagnostic.span.end, 3);
@@ -71,7 +71,7 @@ fn strings_and_split_utf8_streams_produce_the_same_ast_and_exact_text() {
 fn source_diagnostics_keep_session_names_unicode_locations_and_original_offsets() {
     // 建立带来源名的原文快照，后续错误必须定位这份文本而非临时转换后的内容。
     let source = EndorReader::from_text("<session:one/input:2>", "\"日\" + )");
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 右括号没有对应表达式，语法失败仍需按含日文字符的完整原文计算列号和跨度。
     let error = parse_source_expression(&source).unwrap_err();
     assert_eq!(error.location.line, 1);
     assert_eq!(error.location.column, 7);
@@ -87,7 +87,7 @@ fn source_diagnostics_keep_session_names_unicode_locations_and_original_offsets(
 
     // 建立带来源名的原文快照，后续错误必须定位这份文本而非临时转换后的内容。
     let source = EndorReader::from_text("<editor>", "\r\n\"日\\q\"");
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 第二行字符串含不支持的反斜杠转义，词法错误应保留 CRLF 后的行号和 Unicode 列。
     let error = lex_source(&source).unwrap_err();
     assert_eq!(error.diagnostic.kind, DiagnosticKind::Lexical);
     assert_eq!(error.location.line, 2);
@@ -100,7 +100,7 @@ fn source_diagnostics_keep_session_names_unicode_locations_and_original_offsets(
 fn incomplete_or_invalid_utf8_is_rejected_without_replacement_characters() {
     // 覆盖无效起始字节、不完整 UTF-8 序列，以及一个合法 ASCII 前缀后的错误。
     for bytes in [vec![0xff], vec![0xe6, 0x97], vec![b'a', 0xff]] {
-        // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+        // 即使每次只读一个字节，聚合后非法 UTF-8 仍须作为读取编码错误拒绝，不能交给 lexer。
         let error = EndorReader::from_stream("<bytes>", OneByte(Cursor::new(bytes))).unwrap_err();
         assert!(matches!(error.kind, SourceReadErrorKind::InvalidUtf8(_)));
         assert!(error.to_string().contains("<bytes>: invalid UTF-8 at byte"));
@@ -131,7 +131,7 @@ impl Read for FailingStream {
 #[test]
 /// 由 Rust 测试框架调用：读到一个有效字节后发生 IO 失败时仍整体失败，不向解析器提供半份快照。
 fn a_failed_stream_never_returns_partially_read_source() {
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 流先返回 x 后报错，Reader 必须整体传播 IO 失败，不能把已读前缀作为成功源码。
     let error = EndorReader::from_stream("<failed>", FailingStream(false)).unwrap_err();
     assert!(matches!(error.kind, SourceReadErrorKind::Io(_)));
     assert!(error.to_string().contains("stream failure"));
@@ -182,13 +182,13 @@ fn file_sources_preserve_the_path_and_read_errors_are_not_lexical_errors() {
     assert!(parse_source(&source).is_ok());
     // 单字节 0xff 不是 UTF-8，打开文件成功后应在解码阶段拒绝。
     let invalid = SourceFile::new(&[0xff]);
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 文件能打开但 0xff 无法解码，错误应带该文件路径并归为 InvalidUtf8。
     let error = EndorReader::from_file(&invalid.0).unwrap_err();
     assert!(matches!(error.kind, SourceReadErrorKind::InvalidUtf8(_)));
     assert!(error.to_string().contains(&invalid.0.display().to_string()));
     // 从基线路径换一个未创建的扩展名，验证文件不存在作为 IO 错误暴露。
     let missing = file.0.with_extension("missing");
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 未创建的路径应返回 NotFound IO 原因，不能误分类为词法或编码失败。
     let error = EndorReader::from_file(&missing).unwrap_err();
     // 必须能解构出原始 IO 错误，之后检查 NotFound 或 PermissionDenied 的具体种类。
     let SourceReadErrorKind::Io(error) = error.kind else {
@@ -282,7 +282,7 @@ fn uri_snapshots_require_a_revision_and_preserve_it_in_source_diagnostics() {
     };
     // 建立带来源名的原文快照，后续错误必须定位这份文本而非临时转换后的内容。
     let source = EndorReader::from_endor(uri, &provider).unwrap();
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 已解析 URI 的字节是 UTF-8 但函数语法无效，解析诊断仍须显示 rev-one 来源。
     let error = parse_source(&source).unwrap_err();
     assert_eq!(error.origin, source.origin().clone());
     assert!(error.to_string().contains("[revision rev-one]"));
@@ -302,7 +302,7 @@ fn uri_snapshots_require_a_revision_and_preserve_it_in_source_diagnostics() {
         // 借用测试静态字节，load 时复制给 Reader 解码。
         bytes: &[0xff],
     };
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 宿主已选择 rev-two 后才遇到非法 UTF-8，解码失败也必须保留该实际版本身份。
     let error = EndorReader::from_endor(uri, &invalid).unwrap_err();
     assert!(matches!(error.kind, SourceReadErrorKind::InvalidUtf8(_)));
     assert!(error.to_string().contains("[revision rev-two]"));
@@ -344,7 +344,7 @@ fn invalid_uris_do_not_call_the_provider_and_denials_do_not_fall_back_to_files()
         ));
     }
     assert_eq!(provider.calls.get(), 0);
-    // 当前用例要求此阶段失败，随后检查具体类别、来源或底层原因，避免仅接受任意错误。
+    // 基础 URI 合法但宿主拒绝访问，Reader 应保留 PermissionDenied，不尝试文件回退。
     let error = EndorReader::from_endor("endor:anywhere", &DeniedProvider).unwrap_err();
     // 必须能解构出原始 IO 错误，之后检查 NotFound 或 PermissionDenied 的具体种类。
     let SourceReadErrorKind::Io(error) = error.kind else {