接入公开文档命令的同次原生占位反馈及协议回归

Author: loong10k

crates/codeguard-cli/src/c_family_comments_command.rs

@@ -18,7 +18,7 @@ pub fn run(args: &[String]) -> ExitCode {
         }
     };
     let deadline = Instant::now() + Duration::from_millis(request.timeout_ms);
-    let report = match observe(&request, deadline, &AtomicBool::new(false), true) {
+    let report = match observe_policy(&request, deadline, &AtomicBool::new(false), true, true) {
         Ok(report) => report,
         Err(reason) => {
             eprintln!("{reason}");
@@ -59,6 +59,17 @@ pub fn run(args: &[String]) -> ExitCode {
                 row["structure_status"]
             );
         }
+        for row in report["documentation_placeholders"]["observation"]["positions"]
+            .as_array()
+            .into_iter()
+            .flatten()
+            .take(8)
+        {
+            println!(
+                "自有占位规则：{}:{}:{}；组件 {}",
+                report["path"], row["line"], row["column_byte"], row["component"]
+            );
+        }
         if !report["workbench"].is_null() {
             println!(
                 "工作台 {}；任务 {}",
@@ -103,6 +114,16 @@ pub(crate) fn observe(
     deadline: Instant,
     cancellation: &AtomicBool,
     persist: bool,
+) -> Result<Value, String> {
+    observe_policy(request, deadline, cancellation, persist, false)
+}
+
+fn observe_policy(
+    request: &crate::syntax_lint_arguments::SyntaxLintArguments,
+    deadline: Instant,
+    cancellation: &AtomicBool,
+    persist: bool,
+    placeholders: bool,
 ) -> Result<Value, String> {
     let workspace = match crate::c_family_comments_workbench::resolve_root(
         &request.source,
@@ -134,6 +155,8 @@ pub(crate) fn observe(
     let mut native = json!({"status":"incomplete","reason":"clang_source_scope_unavailable","version":null,"tool_sha256":null,"diagnostics":[]});
     let mut source_sha256 = Value::Null;
     let mut structure = json!({"status":"incomplete","reason":"clang_structure_unavailable","observation":null,"native_raw_diagnostic_count":null});
+    let mut placeholder =
+        json!({"status":"incomplete","reason":"clang_placeholder_unavailable","observation":null});
     let source_observation = crate::plain_syntax_source::read_plain_source(&request.source);
     if let Ok(source) = &source_observation {
         let extension = path.extension().and_then(|extension| extension.to_str());
@@ -146,20 +169,23 @@ pub(crate) fn observe(
         };
         if applicable {
             source_sha256 = json!(format!("{:x}", Sha256::digest(source)));
-            (native, structure) = crate::clang_syntax_probe::observe_documentation_with_structure(
-                request.clang_tool.as_deref().expect("工具上下文已校验"),
-                &request.language,
-                request.standard.as_deref().expect("标准上下文已校验"),
-                source,
-                deadline,
-                cancellation,
-            );
+            (native, structure, placeholder) =
+                crate::clang_syntax_probe::observe_documentation_with_placeholders(
+                    request.clang_tool.as_deref().expect("工具上下文已校验"),
+                    &request.language,
+                    request.standard.as_deref().expect("标准上下文已校验"),
+                    source,
+                    deadline,
+                    cancellation,
+                    placeholders,
+                );
             if !crate::plain_syntax_source::read_plain_source(&request.source)
                 .is_ok_and(|current| current == *source)
             {
                 native["status"] = json!("incomplete");
                 native["reason"] = json!("clang_source_changed");
                 native["diagnostics"] = json!([]);
+                placeholder = json!({"status":"incomplete","reason":"clang_source_changed","observation":null});
                 structure = json!({"status":"incomplete","reason":"clang_source_changed","observation":null,"native_raw_diagnostic_count":null});
             }
         }
@@ -176,6 +202,7 @@ pub(crate) fn observe(
             "clang_execution_incomplete"
         });
         native["diagnostics"] = json!([]);
+        placeholder = json!({"status":"incomplete","reason":if cancelled {"request_cancelled"}else{"clang_execution_incomplete"},"observation":null});
         structure = json!({"status":"incomplete","reason":if cancelled {"request_cancelled"}else{"clang_execution_incomplete"},"observation":null,"native_raw_diagnostic_count":null});
     }
     let mut documentation_findings = Vec::new();
@@ -241,5 +268,11 @@ pub(crate) fn observe(
         report["structural_task_workflow_status"] = json!("not_integrated");
     }
     report["next_actions"].as_array_mut().expect("固定反馈动作").push(json!("读取原生AST结构观察中的缺失文档/用途/参数/返回组件并依据真实API补充说明；已初始化工作区可读取结构任务的当前定位并运行原工具task verify；受控尝试记录已接入，可信关闭仍待接线，不把非空说明当准确性或关闭证据。"));
+    if placeholders {
+        report["schema_version"] = json!("0.10.0");
+        report["documentation_placeholders"] = placeholder;
+        report["placeholder_task_workflow_status"] = json!("not_integrated");
+        report["next_actions"].as_array_mut().expect("固定反馈动作").push(json!("按占位观察的位置和组件补充真实用途、参数或返回说明，再以本报告原工具与标准复扫；占位规则稳定任务与专用复检尚未接入，不以结构任务消失关闭占位问题。"));
+    }
     Ok(report)
 }

crates/codeguard-cli/src/clang_syntax_probe.rs

@@ -119,8 +119,11 @@ fn observe_profile(
                 env: BTreeMap::new(),
                 stdin,
                 deadline,
-                output_limit_bytes: if matches!(profile, NativeClangProfile::DocumentationStructure)
-                {
+                output_limit_bytes: if matches!(
+                    profile,
+                    NativeClangProfile::DocumentationStructure
+                        | NativeClangProfile::DocumentationPlaceholders
+                ) {
                     8 * 1024 * 1024
                 } else {
                     64 * 1024
@@ -164,7 +167,10 @@ fn observe_profile(
     let mut args: Vec<OsString> = flags.into_iter().map(OsString::from).collect();
     args.insert(1, OsString::from(format!("-std={standard}")));
     args.splice(7..7, profile.warning_flags().iter().map(OsString::from));
-    if matches!(profile, NativeClangProfile::DocumentationStructure) {
+    if matches!(
+        profile,
+        NativeClangProfile::DocumentationStructure | NativeClangProfile::DocumentationPlaceholders
+    ) {
         args.splice(
             1..1,
             [OsString::from("-Xclang"), OsString::from("-ast-dump=json")],
@@ -183,7 +189,11 @@ fn observe_profile(
         report["reason"] = json!("clang_execution_incomplete");
         return report;
     }
-    if !matches!(profile, NativeClangProfile::DocumentationStructure) && !output.stdout.is_empty() {
+    if !matches!(
+        profile,
+        NativeClangProfile::DocumentationStructure | NativeClangProfile::DocumentationPlaceholders
+    ) && !output.stdout.is_empty()
+    {
         report["reason"] = json!("clang_report_invalid");
         return report;
     }
@@ -193,7 +203,11 @@ fn observe_profile(
         output.termination == Termination::Exited(0),
     ) {
         Ok(mut rows) => {
-            if matches!(profile, NativeClangProfile::DocumentationStructure) {
+            if matches!(
+                profile,
+                NativeClangProfile::DocumentationStructure
+                    | NativeClangProfile::DocumentationPlaceholders
+            ) {
                 report["structure_raw_diagnostic_count"] = json!(rows.len());
                 // AST输出可触发Clang重新读取注释；按脱敏规则/行列/等级归并并保留原条数。
                 let mut seen = BTreeSet::new();
@@ -213,18 +227,33 @@ fn observe_profile(
         }
         Err(reason) => report["reason"] = json!(reason),
     }
-    if matches!(profile, NativeClangProfile::DocumentationStructure)
-        && matches!(
-            report["status"].as_str(),
-            Some("completed" | "diagnostics_observed")
-        )
-        && output.termination == Termination::Exited(0)
+    if matches!(
+        profile,
+        NativeClangProfile::DocumentationStructure | NativeClangProfile::DocumentationPlaceholders
+    ) && matches!(
+        report["status"].as_str(),
+        Some("completed" | "diagnostics_observed")
+    ) && output.termination == Termination::Exited(0)
         && !report["diagnostics"]
             .as_array()
             .into_iter()
             .flatten()
             .any(|row| row["level"] == "error")
     {
+        if matches!(profile, NativeClangProfile::DocumentationPlaceholders) {
+            report["placeholder_observation"] =
+                match codeguard_adapters::parse_clang_documentation_placeholders(
+                    &output.stdout,
+                    source,
+                ) {
+                    Ok(observation) => {
+                        json!({"status":"observed","reason":"clang_placeholder_observed","observation":observation})
+                    }
+                    Err(_) => {
+                        json!({"status":"incomplete","reason":"clang_placeholder_report_invalid","observation":null})
+                    }
+                };
+        }
         report["structure_observation"] = match codeguard_adapters::parse_clang_documentation_ast(
             &output.stdout,
             source,
@@ -250,19 +279,40 @@ pub(crate) fn observe_documentation_with_structure(
     deadline: Instant,
     cancelled: &AtomicBool,
 ) -> (Value, Value) {
+    let (native, structure, _) = observe_documentation_with_placeholders(
+        tool, language, standard, source, deadline, cancelled, false,
+    );
+    (native, structure)
+}
+
+/// 同次原生扫描的独立占位策略观察；enable为false时不执行新增解析，不改变历史消费协议。
+pub(crate) fn observe_documentation_with_placeholders(
+    tool: &Path,
+    language: &str,
+    standard: &str,
+    source: &[u8],
+    deadline: Instant,
+    cancelled: &AtomicBool,
+    enable: bool,
+) -> (Value, Value, Value) {
     let mut native = observe_profile(
         tool,
         language,
         standard,
         source,
         deadline,
         cancelled,
-        NativeClangProfile::DocumentationStructure,
+        if enable {
+            NativeClangProfile::DocumentationPlaceholders
+        } else {
+            NativeClangProfile::DocumentationStructure
+        },
     );
     let mut structure=native.as_object_mut().and_then(|n|n.remove("structure_observation")).unwrap_or(json!({"status":"incomplete","reason":"clang_structure_unavailable","observation":null}));
     structure["native_raw_diagnostic_count"] = native
         .as_object_mut()
         .and_then(|n| n.remove("structure_raw_diagnostic_count"))
         .unwrap_or(Value::Null);
-    (native, structure)
+    let placeholder = native.as_object_mut().and_then(|n| n.remove("placeholder_observation")).unwrap_or(json!({"status":"incomplete","reason":"clang_placeholder_unavailable","observation":null}));
+    (native, structure, placeholder)
 }

crates/codeguard-cli/src/native_clang_profile.rs

@@ -9,15 +9,17 @@ pub(crate) enum NativeClangProfile {
     Documentation,
     /// 同次原生扫描输出警告和函数文档AST，结构事实不冒充原警告或完整政策。
     DocumentationStructure,
+    /// 公开单文件文档反馈同次AST的独立占位策略，不修改历史结构协议。
+    DocumentationPlaceholders,
 }
 impl NativeClangProfile {
     /// 返回固定原生警告参数；无运行输入，返回静态字面argv列表。
     pub(crate) fn warning_flags(self) -> &'static [&'static str] {
         match self {
             Self::Syntax => &["-Wall", "-Wextra", "-Wpedantic"],
-            Self::Documentation | Self::DocumentationStructure => {
-                &["-Wdocumentation", "-Wdocumentation-pedantic"]
-            }
+            Self::Documentation
+            | Self::DocumentationStructure
+            | Self::DocumentationPlaceholders => &["-Wdocumentation", "-Wdocumentation-pedantic"],
         }
     }
 }

crates/codeguard-cli/tests/c_family_comments_structure_cli.rs

@@ -54,7 +54,7 @@ fn public_comments_exposes_absent_empty_and_valid_structural_descriptions() {
             assert_eq!(out.status.code(), Some(3));
             let report: Value = serde_json::from_slice(&out.stdout).unwrap();
             assert_eq!(report["documentation_structure"]["status"], "observed");
-            assert_eq!(report["schema_version"], "0.5.0");
+            assert_eq!(report["schema_version"], "0.10.0");
             assert_eq!(
                 report["documentation_structure"]["observation"]["functions"][0]["missing_components"],
                 json!(expected)
@@ -96,7 +96,7 @@ fn public_comments_exposes_absent_empty_and_valid_structural_descriptions() {
                 .unwrap();
             assert_eq!(out.status.code(), Some(3));
             let report: Value = serde_json::from_slice(&out.stdout).unwrap();
-            assert_eq!(report["schema_version"], "0.9.0");
+            assert_eq!(report["schema_version"], "0.10.0");
             assert_eq!(report["workspace_binding"], "bound");
             assert_eq!(report["structural_task_workflow_status"], "partial");
             if missing_tool {

crates/codeguard-cli/tests/c_family_comments_workbench.rs

@@ -211,7 +211,7 @@ fn linked_source_cannot_redirect_observation_storage_into_another_project() {
         .unwrap();
     assert_eq!(out.status.code(), Some(3));
     let r: Value = serde_json::from_slice(&out.stdout).unwrap();
-    assert_eq!(r["schema_version"], "0.5.0");
+    assert_eq!(r["schema_version"], "0.10.0");
     assert_eq!(r["workspace_binding"], "not_bound");
     assert_eq!(r["documentation_findings"], json!([]));
     assert_eq!(

crates/codeguard-cli/tests/c_family_placeholder_cli.rs

@@ -0,0 +1,84 @@
+use serde_json::Value;
+use std::{fs, process::Command};
+
+#[test]
+#[ignore = "requires explicit existing Clang via CODEGUARD_CLANG_BIN"]
+fn public_comments_exposes_same_scan_placeholder_policy_and_withdraws_on_failure() {
+    let tool = std::env::var("CODEGUARD_CLANG_BIN").unwrap();
+    let root = std::env::temp_dir().join(format!(
+        "cg-placeholder-cli-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    ));
+    fs::create_dir(&root).unwrap();
+    let root = root.canonicalize().unwrap();
+    struct Cleanup(std::path::PathBuf);
+    impl Drop for Cleanup {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.0);
+        }
+    }
+    let _cleanup = Cleanup(root.clone());
+    let source = root.join("api.c");
+    fs::write(
+        &source,
+        "/// TODO.\n/// @param x TBD\n/// @return FIXME!\nint f(int x);\n",
+    )
+    .unwrap();
+    let scan = |selected: &str| {
+        let out = Command::new(env!("CARGO_BIN_EXE_codeguard"))
+            .args(["comments", "c"])
+            .arg(&source)
+            .args([
+                "--clang-tool",
+                selected,
+                "--standard",
+                "c11",
+                "--format=json",
+            ])
+            .output()
+            .unwrap();
+        assert_eq!(out.status.code(), Some(3));
+        serde_json::from_slice::<Value>(&out.stdout).unwrap()
+    };
+    let first = scan(&tool);
+    assert_eq!(first["schema_version"], "0.10.0");
+    assert_eq!(first["documentation_placeholders"]["status"], "observed");
+    assert_eq!(
+        first["documentation_placeholders"]["observation"]["positions"]
+            .as_array()
+            .unwrap()
+            .len(),
+        3
+    );
+    assert_eq!(
+        first["documentation_placeholders"]["observation"]["authority"],
+        "codeguard_structural_policy"
+    );
+    assert_eq!(first["placeholder_task_workflow_status"], "not_integrated");
+    assert!(!root.join(".codeguard").exists());
+    fs::write(&source,"/// Explain TODO queue processing.\n/// @param x The input value.\n/// @return The input unchanged.\nint f(int x);\n").unwrap();
+    let repaired = scan(&tool);
+    assert_eq!(
+        repaired["documentation_placeholders"]["observation"]["positions"],
+        serde_json::json!([])
+    );
+    assert_eq!(repaired["detailed_contract_qualification"], "not_granted");
+    let missing = scan(root.join("missing-clang").to_str().unwrap());
+    assert_eq!(
+        missing["documentation_placeholders"]["status"],
+        "incomplete"
+    );
+    assert!(missing["documentation_placeholders"]["observation"].is_null());
+    if let Ok(destination) = std::env::var("CODEGUARD_PLACEHOLDER_CLI_EVIDENCE") {
+        assert!(std::path::Path::new(&destination).is_absolute());
+        fs::write(
+            destination,
+            serde_json::to_vec_pretty(&serde_json::json!([first, repaired, missing])).unwrap(),
+        )
+        .unwrap();
+    }
+}

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

@@ -1282,3 +1282,13 @@ The adapter SHALL expose a separately versioned, source-associated placeholder o
 - **THEN** the observation SHALL retain the precise function position and component without copying comment text
 - **WHEN** TODO appears within an explanatory sentence or a void return is not applicable
 - **THEN** this rule SHALL not invent a placeholder or required return finding
+
+### Requirement: Public standalone comments SHALL expose same-scan placeholder observations without false task coverage
+
+The standalone comments entry SHALL use the original frozen stdin Clang AST for a separately versioned placeholder observation. It SHALL NOT launch another compiler scan. Source instability, tool failure, cancellation or expired deadline SHALL withdraw that observation. Feedback SHALL distinguish this Codeguard policy from native warnings and retain exact function/component positions and original-tool re-scan guidance. Historical shared check/hook and stored structural protocols SHALL remain unchanged until their own integration is accepted. Until stable placeholder tasks and original-task verification are implemented, feedback SHALL explicitly report placeholder_task_workflow_status=not_integrated and SHALL NOT equate absence of structural tasks with resolution of a placeholder issue.
+
+#### Scenario: The native compiler emits no warning for a placeholder description
+- **WHEN** public comments reads a supported full description consisting of an explicit placeholder
+- **THEN** separately versioned feedback SHALL expose the policy positions without inventing a native diagnostic or claiming detailed qualification
+- **WHEN** the original tool is unavailable or the source changes during scanning
+- **THEN** placeholder observation SHALL be incomplete with no usable positions