接通Gradle原生Javadoc项目检查与保守反馈协议

Author: loong10k

README.md

@@ -1004,4 +1004,4 @@ Static discovery now retains every Maven/Groovy-Gradle/Kotlin-Gradle configurati
 
 `gradle_javadoc_probe::observe` captures the native model and reruns enabled official Javadoc tasks in one offline Gradle invocation. It preserves project doclint/doclet/access/source-set settings and fixes only the diagnostic JVM language. Rust validates selected source bytes and diagnostic locations; native failures, unknown diagnostics and input changes remain incomplete. Four observations within one real Gradle 8.10.2/JDK21 conditional test produce 3 missing-comment, 2 missing-tag, 2 empty-description, and 0 diagnostics. These are not an independent precision corpus or production acceptance. Empty output remains `empty_output_unverified` with `rule_configuration_complete=false` and `coverage_proven=false`.
 
-This internal service is not connected to public check quality tasks, agent feedback or repair closure. Existing check_feedback 0.62 still carries only the Gradle configuration model. Complete detailed documentation rules, JDK/source closure, multi-project/custom-doclet cases, both Maven/Gradle paths and per-language acceptance remain open. See [Gradle Javadoc acceptance](tests/acceptance/gradle-native-javadoc.md).
+The development `check java` / `check all` entry now accepts explicit `--gradle-javadoc` with `--gradle-bundle`, `--java-home`, and repeatable `--gradle-project-file` inputs including root settings/build and Java files. One scheduled `java.gradle.javadoc` job captures the model and executes original documentation tasks in one native invocation. Check feedback 0.63 preserves `native_results.java_gradle_javadoc`; it does not launch a second model invocation. Model-only requests retain 0.62; `lint all` rejects documentation options. SIGINT preserves cancellation observations, and check_aborted 0.17 preserves documentation observations before a sibling failure. Public quality feedback is connected; automatic task persistence, repair recheck/closure, complete rules and JDK/source closure, multi-project/custom-doclet and per-language qualification remain open. See [public Javadoc acceptance](tests/acceptance/gradle-public-javadoc-check.md).

README.zh-CN.md

@@ -987,4 +987,4 @@ flowchart LR
 
 新增 `gradle_javadoc_probe::observe` 在一次离线 Gradle 调用中采集模型并重跑已启用的官方 Javadoc 任务，使用原项目 doclint/doclet/访问范围/源集，只固定诊断 JVM 的英语语言。Rust 校验选定源码及诊断位置，原生失败、未知诊断、输入变化等保持未完成。真实 Gradle 8.10.2/JDK21 四组样例得到 3 条缺注释、2 条缺标签、2 条空标签描述、0 条诊断；这是一个原生条件测试中的四次观察，不是独立精度语料或生产验收。无诊断报告仍为 `empty_output_unverified`，`rule_configuration_complete=false`、`coverage_proven=false`。
 
-此服务尚未接入公开 check 的质量任务、智能体反馈及修复关闭；现有 check_feedback 0.62 仍仅记录 Gradle 配置模型。完整详细注释规则、完整 JDK/源码闭包、跨项目/自定义 doclet、Maven/Gradle 双路径及各语言验收仍待完成。见 [Gradle Javadoc 验收记录](tests/acceptance/gradle-native-javadoc.md)。
+开发期 `check java` / `check all` 现可显式追加 `--gradle-javadoc`，同时提供 `--gradle-bundle`、`--java-home` 和可重复的 `--gradle-project-file`（含根 settings/build 及 Java 文件）。统一调度只生成一个 `java.gradle.javadoc` 任务，单次原生调用完成模型/注释检查，check_feedback 0.63 在 `native_results.java_gradle_javadoc` 保存诊断；不额外调用配置模型。仅模型请求仍使用 0.62；`lint all` 拒绝文档参数。SIGINT 保留取消观察，check_aborted 0.17 保留兄弟异常之前的文档观察。公开质量反馈已接入，自动任务持久化、复检关闭、完整规则及完整 JDK/源码闭包和跨项目/custom doclet 验收仍待完成。见 [公开 Javadoc 入口验收](tests/acceptance/gradle-public-javadoc-check.md)。

crates/codeguard-cli/src/check_command.rs

@@ -40,6 +40,7 @@ pub(crate) fn examples(command: &str) -> &'static [&'static str] {
         "check" => &[
             "codeguard check all . --timeout 60s --jobs 1 --format json",
             "codeguard check java . --gradle-bundle /absolute/gradle --java-home /absolute/jdk --gradle-project-file settings.gradle --gradle-project-file build.gradle --format json",
+            "codeguard check java . --gradle-javadoc --gradle-bundle /absolute/gradle --java-home /absolute/jdk21 --gradle-project-file settings.gradle --gradle-project-file build.gradle --gradle-project-file src/main/java/Example.java --format json",
             "codeguard check go . --go-tool /absolute/sdk/bin/go --format json",
             "codeguard check swift . --swift-tool /absolute/swift --format json",
             "codeguard check kotlin . --kotlinc-tool /absolute/kotlinc --format json",

crates/codeguard-cli/src/command_examples.rs

@@ -164,3 +164,241 @@ fn actual_gradle_javadoc_preserves_missing_comments_and_documented_counterexampl
         fs::write(path, serde_json::to_vec_pretty(&reports).unwrap()).unwrap();
     }
 }
+
+fn public_command(project: &Project, selection: &str) -> std::process::Command {
+    public_command_with_tools(
+        project,
+        selection,
+        std::path::Path::new("/unavailable/gradle"),
+        std::path::Path::new("/unavailable/jdk"),
+    )
+}
+fn public_command_with_tools(
+    project: &Project,
+    selection: &str,
+    bundle: &std::path::Path,
+    jdk: &std::path::Path,
+) -> std::process::Command {
+    let mut command = std::process::Command::new(env!("CARGO_BIN_EXE_codeguard"));
+    command
+        .args(["check", selection])
+        .arg(&project.0)
+        .args(["--gradle-javadoc", "--gradle-bundle"])
+        .arg(bundle)
+        .arg("--java-home")
+        .arg(jdk)
+        .args([
+            "--gradle-project-file",
+            "settings.gradle",
+            "--gradle-project-file",
+            "build.gradle",
+            "--gradle-project-file",
+            "src/main/java/Sample.java",
+            "--format=json",
+        ])
+        .env("PATH", "/no/tools");
+    command
+}
+#[test]
+fn public_check_schedules_one_documentation_job_and_preserves_incomplete_feedback() {
+    let project = Project::new("public class Sample {}\n");
+    for selection in ["java", "all"] {
+        let output = public_command(&project, selection).output().unwrap();
+        assert_eq!(output.status.code(), Some(3), "{output:?}");
+        let report: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+        assert_eq!(report["schema_version"], "0.63.0");
+        assert!(report["native_results"].get("java_gradle_model").is_none());
+        assert_eq!(
+            report["native_results"]["java_gradle_javadoc"]["native_status"],
+            "incomplete"
+        );
+        let gradle_jobs = report["execution_tasks"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter(|j| j["id"].as_str().unwrap().starts_with("java.gradle."))
+            .collect::<Vec<_>>();
+        assert_eq!(gradle_jobs.len(), 1);
+        assert_eq!(gradle_jobs[0]["id"], "java.gradle.javadoc");
+        assert_ne!(report["delivery_decision"], "allow");
+        if let Some(dir) = std::env::var_os("CODEGUARD_TEST_GRADLE_JAVADOC_PUBLIC_REPORTS") {
+            fs::create_dir_all(&dir).unwrap();
+            fs::write(
+                PathBuf::from(dir).join(format!("{selection}-incomplete.json")),
+                serde_json::to_vec_pretty(&report).unwrap(),
+            )
+            .unwrap();
+        }
+    }
+}
+
+#[test]
+fn public_javadoc_selection_rejects_missing_sources_duplicate_and_lint_scope() {
+    let project = Project::new("public class Sample {}\n");
+    for mut command in [
+        {
+            let mut c = public_command(&project, "java");
+            c.arg("--gradle-javadoc");
+            c
+        },
+        public_command(&project, "rust"),
+        {
+            let mut c = std::process::Command::new(env!("CARGO_BIN_EXE_codeguard"));
+            c.args(["check", "java"])
+                .arg(&project.0)
+                .arg("--gradle-javadoc");
+            c
+        },
+        {
+            let mut c = std::process::Command::new(env!("CARGO_BIN_EXE_codeguard"));
+            c.args(["lint", "all"])
+                .arg(&project.0)
+                .arg("--gradle-javadoc");
+            c
+        },
+        {
+            let mut c = std::process::Command::new(env!("CARGO_BIN_EXE_codeguard"));
+            c.args(["check", "java"]).arg(&project.0).args([
+                "--gradle-javadoc",
+                "--gradle-bundle",
+                "/unavailable/gradle",
+                "--java-home",
+                "/unavailable/jdk",
+                "--gradle-project-file",
+                "settings.gradle",
+                "--gradle-project-file",
+                "build.gradle",
+            ]);
+            c
+        },
+    ] {
+        let output = command.env("PATH", "/no/tools").output().unwrap();
+        assert_eq!(output.status.code(), Some(2), "{output:?}");
+        assert!(output.stdout.is_empty());
+    }
+}
+#[test]
+#[ignore = "requires explicit existing Gradle8.10.2/JDK21; never installs"]
+fn actual_public_check_preserves_native_documentation_findings_without_coverage_upgrade() {
+    let bundle =
+        PathBuf::from(std::env::var_os("CODEGUARD_TEST_GRADLE_BUNDLE").expect("existing Gradle"));
+    let jdk = PathBuf::from(std::env::var_os("CODEGUARD_TEST_JAVA_HOME").expect("existing JDK"));
+    for (name, source, expected_count, status) in [
+        (
+            "missing",
+            "public class Sample {\n    public Sample() {}\n    public int add(int value) { return value + 1; }\n}\n",
+            3,
+            "findings_observed_unverified",
+        ),
+        (
+            "documented",
+            "/** Provides an example. */\npublic class Sample {\n    /** Creates the example. */\n    public Sample() {}\n    /** Adds one.\n     * @param value input value\n     * @return incremented value\n     */\n    public int add(int value) { return value + 1; }\n}\n",
+            0,
+            "empty_output_unverified",
+        ),
+    ] {
+        let project = Project::new(source);
+        let output = public_command_with_tools(&project, "java", &bundle, &jdk)
+            .output()
+            .unwrap();
+        assert_eq!(output.status.code(), Some(3), "{output:?}");
+        let report: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+        assert_eq!(report["schema_version"], "0.63.0");
+        let native = &report["native_results"]["java_gradle_javadoc"];
+        assert_eq!(native["native_status"], status, "{report}");
+        assert_eq!(native["findings"].as_array().unwrap().len(), expected_count);
+        for finding in native["findings"].as_array().unwrap() {
+            assert_eq!(finding["rule_id"], "JavadocMissingComment");
+            assert_eq!(finding["path"], "src/main/java/Sample.java");
+        }
+        assert_eq!(native["coverage_proven"], false);
+        assert_eq!(native["rule_configuration_complete"], false);
+        assert_ne!(report["delivery_decision"], "allow");
+        assert!(report["native_results"].get("java_gradle_model").is_none());
+        assert_eq!(
+            report["execution_tasks"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .filter(|r| r["id"] == "java.gradle.javadoc")
+                .count(),
+            1
+        );
+        if let Some(dir) = std::env::var_os("CODEGUARD_TEST_GRADLE_JAVADOC_PUBLIC_REPORTS") {
+            fs::create_dir_all(&dir).unwrap();
+            fs::write(
+                PathBuf::from(dir).join(format!("{name}-native.json")),
+                serde_json::to_vec_pretty(&report).unwrap(),
+            )
+            .unwrap();
+        }
+    }
+}
+
+#[test]
+fn public_javadoc_sigint_preserves_cancelled_native_observation() {
+    use std::os::unix::fs::PermissionsExt;
+    let project = Project::new("public class Sample {}\n");
+    let bundle = project.0.join("native-gradle");
+    let jdk = project.0.join("native-jdk");
+    fs::create_dir_all(bundle.join("bin")).unwrap();
+    fs::create_dir_all(jdk.join("bin")).unwrap();
+    fs::write(jdk.join("bin/java"), "controlled fixture").unwrap();
+    fs::write(jdk.join("release"), "JAVA_VERSION=\"21\"\n").unwrap();
+    let marker = project.0.join("native-started");
+    fs::write(
+        bundle.join("bin/gradle"),
+        format!(
+            "#!/bin/sh\nprintf started > '{}'\nexec /bin/sleep 30\n",
+            marker.display()
+        ),
+    )
+    .unwrap();
+    fs::set_permissions(bundle.join("bin/gradle"), fs::Permissions::from_mode(0o700)).unwrap();
+    let child = public_command_with_tools(&project, "java", &bundle, &jdk)
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .spawn()
+        .unwrap();
+    let until = Instant::now() + Duration::from_secs(10);
+    while !marker.exists() && Instant::now() < until {
+        std::thread::sleep(Duration::from_millis(10));
+    }
+    assert!(marker.exists(), "native process did not start");
+    assert!(
+        std::process::Command::new("/bin/kill")
+            .args(["-INT", &child.id().to_string()])
+            .status()
+            .unwrap()
+            .success()
+    );
+    let output = child.wait_with_output().unwrap();
+    assert_eq!(output.status.code(), Some(130), "{output:?}");
+    let report: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+    assert_eq!(report["schema_version"], "0.63.0");
+    assert_eq!(
+        report["native_results"]["java_gradle_javadoc"]["reason"],
+        "request_cancelled"
+    );
+    assert!(
+        report["native_results"]["java_gradle_javadoc"]["findings"]
+            .as_array()
+            .unwrap()
+            .is_empty()
+    );
+    assert!(
+        report["execution_tasks"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .any(|r| r["id"] == "java.gradle.javadoc" && r["status"] == "cancelled")
+    );
+    if let Some(dir) = std::env::var_os("CODEGUARD_TEST_GRADLE_JAVADOC_PUBLIC_REPORTS") {
+        fs::create_dir_all(&dir).unwrap();
+        fs::write(
+            PathBuf::from(dir).join("sigint.json"),
+            serde_json::to_vec_pretty(&report).unwrap(),
+        )
+        .unwrap();
+    }
+}

crates/codeguard-cli/tests/gradle_javadoc_probe.rs

@@ -1410,4 +1410,4 @@ The development CLI now exposes this selected-input observation through `check j
 
 `gradle_javadoc_probe::observe` captures the native model and reruns enabled official Javadoc tasks in one offline Gradle invocation. It preserves project doclint/doclet/access/source-set settings and fixes only the diagnostic JVM language. Rust validates selected source bytes and diagnostic locations; native failures, unknown diagnostics and input changes remain incomplete. Four observations within one real Gradle 8.10.2/JDK21 conditional test produce 3 missing-comment, 2 missing-tag, 2 empty-description, and 0 diagnostics. These are not an independent precision corpus or production acceptance. Empty output remains `empty_output_unverified` with `rule_configuration_complete=false` and `coverage_proven=false`.
 
-This internal service is not connected to public check quality tasks, agent feedback or repair closure. Existing check_feedback 0.62 still carries only the Gradle configuration model. Complete detailed documentation rules, JDK/source closure, multi-project/custom-doclet cases, both Maven/Gradle paths and per-language acceptance remain open. See [Gradle Javadoc acceptance](../tests/acceptance/gradle-native-javadoc.md).
+The development `check java` / `check all` entry now accepts explicit `--gradle-javadoc` with `--gradle-bundle`, `--java-home`, and repeatable `--gradle-project-file` inputs including root settings/build and Java files. One scheduled `java.gradle.javadoc` job captures the model and executes original documentation tasks in one native invocation. Check feedback 0.63 preserves `native_results.java_gradle_javadoc`; it does not launch a second model invocation. Model-only requests retain 0.62; `lint all` rejects documentation options. SIGINT preserves cancellation observations, and check_aborted 0.17 preserves documentation observations before a sibling failure. Public quality feedback is connected; automatic task persistence, repair recheck/closure, complete rules and JDK/source closure, multi-project/custom-doclet and per-language qualification remain open. See [public Javadoc acceptance](../tests/acceptance/gradle-public-javadoc-check.md).

docs/Codeguard-Architecture.md

@@ -1410,4 +1410,4 @@ Rust 应用服务 `gradle_model_probe::observe` 可通过固定 init 脚本、
 
 新增 `gradle_javadoc_probe::observe` 在一次离线 Gradle 调用中采集模型并重跑已启用的官方 Javadoc 任务，使用原项目 doclint/doclet/访问范围/源集，只固定诊断 JVM 的英语语言。Rust 校验选定源码及诊断位置，原生失败、未知诊断、输入变化等保持未完成。真实 Gradle 8.10.2/JDK21 四组样例得到 3 条缺注释、2 条缺标签、2 条空标签描述、0 条诊断；这是一个原生条件测试中的四次观察，不是独立精度语料或生产验收。无诊断报告仍为 `empty_output_unverified`，`rule_configuration_complete=false`、`coverage_proven=false`。
 
-此服务尚未接入公开 check 的质量任务、智能体反馈及修复关闭；现有 check_feedback 0.62 仍仅记录 Gradle 配置模型。完整详细注释规则、完整 JDK/源码闭包、跨项目/自定义 doclet、Maven/Gradle 双路径及各语言验收仍待完成。见 [Gradle Javadoc 验收记录](../tests/acceptance/gradle-native-javadoc.md)。
+开发期 `check java` / `check all` 现可显式追加 `--gradle-javadoc`，同时提供 `--gradle-bundle`、`--java-home` 和可重复的 `--gradle-project-file`（含根 settings/build 及 Java 文件）。统一调度只生成一个 `java.gradle.javadoc` 任务，单次原生调用完成模型/注释检查，check_feedback 0.63 在 `native_results.java_gradle_javadoc` 保存诊断；不额外调用配置模型。仅模型请求仍使用 0.62；`lint all` 拒绝文档参数。SIGINT 保留取消观察，check_aborted 0.17 保留兄弟异常之前的文档观察。公开质量反馈已接入，自动任务持久化、复检关闭、完整规则及完整 JDK/源码闭包和跨项目/custom doclet 验收仍待完成。见 [公开 Javadoc 入口验收](../tests/acceptance/gradle-public-javadoc-check.md)。