保留 Rust 聚合文档检查的双原生义务

Author: loong10k

README.md

@@ -1096,3 +1096,6 @@ The standalone C/C++ Clang entry now distinguishes literal/comment hashes and ra
 
 
 Native Clippy documentation findings now receive specific Errors/Panics/Safety repair guidance through stable tasks and original-tool suppression rechecks. The installed Clippy accepts bare headings: zero diagnostics do not qualify detailed documentation and facts remain open. Ordinary checks do not enable pedantic implicitly. `comments rust` remains a local Rustdoc probe; complete documentation contracts are not unified or qualified. See [acceptance and gaps](tests/acceptance/clippy-documentation-contract.md).
+
+
+`check rust/all` now retains a separate comments observation for the three native Clippy documentation rules alongside Rustdoc, preserving each tool obligation without another Clippy execution. Only exact known diagnostics participate; zero findings do not establish enabled or complete documentation contracts. See [aggregate acceptance](tests/acceptance/clippy-documentation-aggregate.md).

README.zh-CN.md

@@ -1073,3 +1073,6 @@ C/C++ 独立 Clang 入口已修复字符串、注释和原始字符串中的井
 
 
 Rust 的详细文档任务现对原生 Clippy `missing_errors_doc`、`missing_panics_doc`、`missing_safety_doc` 给出具体 Errors/Panics/Safety 修复指引，复用稳定任务及原工具抑制对照。已有 Clippy 实测接受空章节标题，因此零诊断不代表详细说明合格，事实继续 open；不会隐式启用 pedantic。`comments rust` 仍为 Rustdoc 局部探针，尚未统一完整文档契约。参见 [局部验收与缺口](tests/acceptance/clippy-documentation-contract.md)。
+
+
+`check rust/all` 现在把原生 Clippy 的三类文档诊断作为独立 comments 观察，与原 Rustdoc 行并存，不覆盖原工具阻塞或重复执行 Clippy；仅精确已知规则参与，零发现不证明详细契约启用。参见 [聚合验收](tests/acceptance/clippy-documentation-aggregate.md)。

crates/codeguard-cli/src/check_command.rs

@@ -1801,6 +1801,40 @@ fn run_scoped(args: &[String], lint_only: bool) -> ExitCode {
                     "ruff_d100_native_observation_incomplete"
                 });
             }
+            // 文档类原生发现来自两个独立服务；保留Rustdoc义务，不能用Clippy结果覆盖。
+            // 只分类精确已适配的原规则，空结果不证明这些规则启用或详细内容合格。
+            if rust_comments_selected
+                && rust_lint["findings"].as_array().is_some_and(|findings| {
+                    findings.iter().any(|finding| {
+                        matches!(
+                            finding["rule_id"].as_str(),
+                            Some(
+                                "clippy::missing_errors_doc"
+                                    | "clippy::missing_panics_doc"
+                                    | "clippy::missing_safety_doc"
+                            )
+                        )
+                    })
+                })
+            {
+                candidates.push(candidate.clone());
+                candidate["checker_id"] = json!("rust.cargo_clippy");
+                let complete = rust_task_outcome == Some(TaskOutcome::Succeeded)
+                    && rust_lint["local_scan_complete"] == true;
+                candidate["status"] = json!(if complete {
+                    "observed_unverified"
+                } else {
+                    "native_incomplete"
+                });
+                candidate["reason"] = json!(if complete {
+                    "trusted_policy_and_coverage_unavailable"
+                } else {
+                    "native_scan_incomplete"
+                });
+                candidate["next_action"] = json!(
+                    "读取 native_results.rust_lint 的原生 Errors/Panics/Safety 规则与稳定任务，说明实际契约并用原 Cargo 对原任务 task verify；空章节不能代替详细说明，Rustdoc 与完整文档覆盖仍须分别核验"
+                );
+            }
             if language == "python" && category == "cve" {
                 candidate["checker_id"] = json!("python.pip_audit");
                 candidate["next_action"] = json!(

crates/codeguard-cli/tests/check_all_rust_native.rs

@@ -74,6 +74,82 @@ impl Drop for Fixture {
     }
 }
 
+#[test]
+fn clippy_documentation_keeps_both_native_comment_obligations() {
+    for (rule, exit, doc_failed) in [
+        ("missing_errors_doc", 0, false),
+        ("missing_panics_doc", 0, false),
+        ("missing_safety_doc", 0, false),
+        ("missing_errors_doc", 101, false),
+        ("missing_errors_doc", 0, true),
+    ] {
+        let f = Fixture::new();
+        let warning = serde_json::json!({"reason":"compiler-message","message":{"level":"warning","code":{"code":format!("clippy::{rule}")},"spans":[{"file_name":"src/lib.rs","line_start":1,"column_start":1,"is_primary":true}]}});
+        let tool = f.tool(&format!(
+            "printf '%s\\n' '{}' '{{\"reason\":\"build-finished\",\"success\":{}}}'; exit {exit}",
+            warning,
+            exit == 0
+        ));
+        if doc_failed {
+            let script =
+                fs::read_to_string(&tool)
+                    .unwrap()
+                    .replacen("exit 0 ;; esac", "exit 1 ;; esac", 1);
+            fs::write(&tool, script).unwrap();
+        }
+        let (_, r) = f.check(&["--cargo-tool", tool.to_str().unwrap()]);
+        let rows: Vec<&Value> = r["category_candidates"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter(|c| c["language"] == "rust" && c["category"] == "comments")
+            .collect();
+        assert!(
+            rows.iter().any(|c| c["checker_id"] == "rust.cargo_rustdoc"),
+            "{r}"
+        );
+        let clippy = rows
+            .iter()
+            .find(|c| c["checker_id"] == "rust.cargo_clippy")
+            .expect("Clippy comments obligation");
+        assert_eq!(
+            clippy["status"],
+            if exit == 0 {
+                "observed_unverified"
+            } else {
+                "native_incomplete"
+            }
+        );
+        if doc_failed {
+            let rustdoc = rows
+                .iter()
+                .find(|c| c["checker_id"] == "rust.cargo_rustdoc")
+                .unwrap();
+            assert_eq!(rustdoc["status"], "native_incomplete");
+        }
+        assert!(clippy["next_action"].as_str().unwrap().contains("空章节"));
+        assert_eq!(r["delivery_decision"], "incomplete");
+    }
+    for rule in ["missing_errors_doc_unknown", "needless_return"] {
+        let f = Fixture::new();
+        let warning = serde_json::json!({"reason":"compiler-message","message":{"level":"warning","code":{"code":format!("clippy::{rule}")},"spans":[{"file_name":"src/lib.rs","line_start":1,"column_start":1,"is_primary":true}]}});
+        let tool = f.tool(&format!(
+            "printf '%s\\n' '{}' '{{\"reason\":\"build-finished\",\"success\":true}}'",
+            warning
+        ));
+        let (_, r) = f.check(&["--cargo-tool", tool.to_str().unwrap()]);
+        assert!(
+            !r["category_candidates"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .any(|c| c["language"] == "rust"
+                    && c["category"] == "comments"
+                    && c["checker_id"] == "rust.cargo_clippy")
+        );
+    }
+}
+
 #[test]
 fn check_all_schedules_native_cargo_type_check_and_keeps_compiler_error_separate() {
     let fixture = Fixture::new();

crates/codeguard-cli/tests/rust_clippy_documentation.rs

@@ -125,6 +125,22 @@ fn native_documentation_contracts_reuse_tasks_and_preserve_semantic_limits() {
         let verify = || p.invoke(&["task", "verify", id, "--cargo-tool", &tool, "--format=json"]);
         let present = verify();
         assert_eq!(present["observation"], "still_present", "{present}");
+        let aggregate = p.invoke(&["check", "rust", "--cargo-tool", &tool, "--format=json"]);
+        let rows = aggregate["category_candidates"].as_array().unwrap();
+        for checker in ["rust.cargo_clippy", "rust.cargo_rustdoc"] {
+            assert!(
+                rows.iter()
+                    .any(|r| r["category"] == "comments" && r["checker_id"] == checker),
+                "{aggregate}"
+            );
+        }
+        let observed = aggregate["native_results"]["rust_lint"]["findings"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|f| f["rule_id"] == native_rule)
+            .unwrap();
+        assert_eq!(observed["finding_id"], id);
         fs::write(
             p.0.join("src/lib.rs"),
             source("", &format!("#[allow(clippy::{rule})]")),
@@ -166,7 +182,7 @@ fn native_documentation_contracts_reuse_tasks_and_preserve_semantic_limits() {
         )
         .unwrap();
         assert_eq!(fact["state"], "open");
-        evidence.push(json!({"rule":native_rule,"first":first,"repeat":repeat,"present":present,"suppressed":suppressed,"bare_heading":bare,"repaired":repaired,"state":fact["state"]}));
+        evidence.push(json!({"rule":native_rule,"first":first,"repeat":repeat,"present":present,"aggregate":aggregate,"suppressed":suppressed,"bare_heading":bare,"repaired":repaired,"state":fact["state"]}));
     }
     let p = Project::new(
         3,

docs/Codeguard-Architecture.md

@@ -1507,3 +1507,6 @@ The standalone C/C++ Clang entry now distinguishes literal/comment hashes and ra
 
 
 Native Clippy documentation findings now receive specific Errors/Panics/Safety repair guidance through stable tasks and original-tool suppression rechecks. The installed Clippy accepts bare headings: zero diagnostics do not qualify detailed documentation and facts remain open. Ordinary checks do not enable pedantic implicitly. `comments rust` remains a local Rustdoc probe; complete documentation contracts are not unified or qualified. See [acceptance and gaps](../tests/acceptance/clippy-documentation-contract.md).
+
+
+`check rust/all` now retains a separate comments observation for the three native Clippy documentation rules alongside Rustdoc, preserving each tool obligation without another Clippy execution. Only exact known diagnostics participate; zero findings do not establish enabled or complete documentation contracts. See [aggregate acceptance](../tests/acceptance/clippy-documentation-aggregate.md).

docs/Codeguard-Architecture.zh_CN.md

@@ -1507,3 +1507,6 @@ C/C++ 独立 Clang 入口已修复字符串、注释和原始字符串中的井
 
 
 Rust 的详细文档任务现对原生 Clippy `missing_errors_doc`、`missing_panics_doc`、`missing_safety_doc` 给出具体 Errors/Panics/Safety 修复指引，复用稳定任务及原工具抑制对照。已有 Clippy 实测接受空章节标题，因此零诊断不代表详细说明合格，事实继续 open；不会隐式启用 pedantic。`comments rust` 仍为 Rustdoc 局部探针，尚未统一完整文档契约。参见 [局部验收与缺口](../tests/acceptance/clippy-documentation-contract.md)。
+
+
+`check rust/all` 现在把原生 Clippy 的三类文档诊断作为独立 comments 观察，与原 Rustdoc 行并存，不覆盖原工具阻塞或重复执行 Clippy；仅精确已知规则参与，零发现不证明详细契约启用。参见 [聚合验收](../tests/acceptance/clippy-documentation-aggregate.md)。

docs/Codeguard-Technical-Design.md

@@ -1980,3 +1980,6 @@ The standalone C/C++ Clang entry now distinguishes literal/comment hashes and ra
 
 
 Native Clippy documentation findings now receive specific Errors/Panics/Safety repair guidance through stable tasks and original-tool suppression rechecks. The installed Clippy accepts bare headings: zero diagnostics do not qualify detailed documentation and facts remain open. Ordinary checks do not enable pedantic implicitly. `comments rust` remains a local Rustdoc probe; complete documentation contracts are not unified or qualified. See [acceptance and gaps](../tests/acceptance/clippy-documentation-contract.md).
+
+
+`check rust/all` now retains a separate comments observation for the three native Clippy documentation rules alongside Rustdoc, preserving each tool obligation without another Clippy execution. Only exact known diagnostics participate; zero findings do not establish enabled or complete documentation contracts. See [aggregate acceptance](../tests/acceptance/clippy-documentation-aggregate.md).

docs/Codeguard-Technical-Design.zh_CN.md

@@ -1981,3 +1981,6 @@ C/C++ 独立 Clang 入口已修复字符串、注释和原始字符串中的井
 
 
 Rust 的详细文档任务现对原生 Clippy `missing_errors_doc`、`missing_panics_doc`、`missing_safety_doc` 给出具体 Errors/Panics/Safety 修复指引，复用稳定任务及原工具抑制对照。已有 Clippy 实测接受空章节标题，因此零诊断不代表详细说明合格，事实继续 open；不会隐式启用 pedantic。`comments rust` 仍为 Rustdoc 局部探针，尚未统一完整文档契约。参见 [局部验收与缺口](../tests/acceptance/clippy-documentation-contract.md)。
+
+
+`check rust/all` 现在把原生 Clippy 的三类文档诊断作为独立 comments 观察，与原 Rustdoc 行并存，不覆盖原工具阻塞或重复执行 Clippy；仅精确已知规则参与，零发现不证明详细契约启用。参见 [聚合验收](../tests/acceptance/clippy-documentation-aggregate.md)。

openspec/changes/introduce-rust-codeguard-cli/specs/native-tool-adapters/spec.md

@@ -125,6 +125,11 @@ Rustdoc逐问题反馈 MUST 提供问题证据、规则依据、允许修改的
 - **THEN** 保留原生规则和同一稳定任务，分别要求说明实际错误及条件、panic 条件或 unsafe 调用前置条件；不得改变 API 行为或关闭规则迎合检查，使用原工具 task verify 复检
 - **AND** 不为普通检查强制启用 pedantic 规则；抑制对照仍保持任务开放，空章节标题的原生零诊断不代表详细说明合格或完整文档验收
 
+#### Scenario: Aggregate Rust documentation preserves both native sources
+- **WHEN** check rust/all 收到三个已适配 Clippy 文档规则之一的原生发现
+- **THEN** comments 类别保留独立 Clippy 观察和原 Rustdoc 观察，不覆盖或丢失任一原工具义务；两者只提供局部未核验结果，任务仍复用原检查器身份
+- **AND** 原生失败后保留已有发现并标未完成；未知相似规则或零发现不能据此前缀声称详细文档规则完整启用
+
 #### Scenario: Standalone Rust lint has no native Cargo
 - **WHEN** 未显式选择Cargo且绝对PATH没有可用Cargo
 - **THEN** WASM构建对有界Rust源码提供候选初检并同步确认任务；发现候选或范围/运行未完成时必须准备原生工具，完整有界范围零候选时推荐准备；不安装工具、不把候选认定为源码违规；无WASM构建明确初检不可用