补充语法初检状态聚合及误报边界测试

Author: loong10k

crates/codeguard-core/src/lib.rs

@@ -14,6 +14,11 @@ mod native_checker_binding;
 mod obligation_result;
 mod observation_port;
 mod repository_path_safety;
+mod syntax_file_observation;
+mod syntax_file_state;
+mod syntax_precheck;
+mod syntax_precheck_outcome;
+mod syntax_precheck_status;
 mod syntax_recovery_anchor;
 mod task_graph;
 mod task_node;
@@ -44,6 +49,11 @@ pub use native_checker_binding::NativeCheckerBinding;
 pub use obligation_result::ObligationResult;
 pub use observation_port::{ObservationPort, ObservedPathKind};
 pub use repository_path_safety::{RepositoryPathViolation, check_repository_paths};
+pub use syntax_file_observation::SyntaxFileObservation;
+pub use syntax_file_state::SyntaxFileState;
+pub use syntax_precheck::assess_syntax_precheck;
+pub use syntax_precheck_outcome::SyntaxPrecheckOutcome;
+pub use syntax_precheck_status::SyntaxPrecheckStatus;
 pub use syntax_recovery_anchor::SyntaxRecoveryAnchor;
 pub use task_graph::{TaskGraph, TaskGraphError};
 pub use task_node::TaskNode;

crates/codeguard-core/src/syntax_file_observation.rs

@@ -0,0 +1,12 @@
+use serde::Serialize;
+
+use crate::SyntaxFileState;
+
+/// 已选范围中一个文件的观察，path 为工作区相对路径。
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+pub struct SyntaxFileObservation {
+    /// 文件的工作区相对路径。
+    pub path: String,
+    /// 该文件的实际解析状态。
+    pub state: SyntaxFileState,
+}

crates/codeguard-core/src/syntax_file_state.rs

@@ -0,0 +1,26 @@
+use serde::Serialize;
+
+/// 单个已选源码文件的语法初检观察；不表示原生 lint 或编译结果。
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(tag = "status", rename_all = "snake_case")]
+pub enum SyntaxFileState {
+    /// 已解析；grammar_qualified 仅表示该文件的版本与方言已被验收。
+    Checked {
+        /// ERROR/MISSING 原始恢复节点数，尚未确认是否为源码违规。
+        recoveries: usize,
+        /// 该文件版本与方言是否落在已验收范围内。
+        grammar_qualified: bool,
+        /// 恢复节点或遍历预算是否截断。
+        truncated: bool,
+    },
+    /// 解析、位置映射、预算或输入身份等未能完成。
+    Incomplete {
+        /// 具体失败原因。
+        reason: String,
+    },
+    /// 不支持的文件、语言区域或方言。
+    Unsupported {
+        /// 具体不支持原因。
+        reason: String,
+    },
+}

crates/codeguard-core/src/syntax_precheck.rs

@@ -0,0 +1,89 @@
+use std::collections::BTreeSet;
+
+use crate::{SyntaxFileObservation, SyntaxFileState, SyntaxPrecheckOutcome, SyntaxPrecheckStatus};
+
+/// 按选定文件范围聚合语法初检；枚举中断、取消、未知版本和局部失败不能成为 clean。
+/// 参数为每个已选文件的唯一观察、范围是否完成及取消状态；返回初检状态或输入契约错误。
+pub fn assess_syntax_precheck(
+    files: &[SyntaxFileObservation],
+    scope_complete: bool,
+    cancelled: bool,
+) -> Result<SyntaxPrecheckOutcome, &'static str> {
+    let mut paths = BTreeSet::new();
+    let mut outcome = SyntaxPrecheckOutcome {
+        status: SyntaxPrecheckStatus::NotRun,
+        scope_complete,
+        cancelled,
+        selected_files: files.len(),
+        checked_files: 0,
+        incomplete_files: 0,
+        unsupported_files: 0,
+        unqualified_files: 0,
+        truncated_files: 0,
+        suspected_recoveries: 0,
+    };
+    for file in files {
+        if !valid_relative_path(&file.path) || !paths.insert(file.path.as_str()) {
+            return Err("syntax_scope_invalid_or_duplicate_path");
+        }
+        match &file.state {
+            SyntaxFileState::Checked {
+                recoveries,
+                grammar_qualified,
+                truncated,
+            } => {
+                outcome.checked_files += 1;
+                outcome.suspected_recoveries = outcome
+                    .suspected_recoveries
+                    .checked_add(*recoveries)
+                    .ok_or("syntax_recovery_count_overflow")?;
+                if !grammar_qualified {
+                    outcome.unqualified_files += 1;
+                }
+                if *truncated {
+                    outcome.truncated_files += 1;
+                }
+            }
+            SyntaxFileState::Incomplete { reason } => {
+                if reason.is_empty() {
+                    return Err("syntax_incomplete_reason_missing");
+                }
+                outcome.incomplete_files += 1;
+            }
+            SyntaxFileState::Unsupported { reason } => {
+                if reason.is_empty() {
+                    return Err("syntax_unsupported_reason_missing");
+                }
+                outcome.unsupported_files += 1;
+            }
+        }
+    }
+    outcome.status = if !scope_complete || cancelled {
+        SyntaxPrecheckStatus::Incomplete
+    } else if files.is_empty() {
+        SyntaxPrecheckStatus::NotRun
+    } else if outcome.unsupported_files == files.len() {
+        SyntaxPrecheckStatus::Unsupported
+    } else if outcome.incomplete_files > 0
+        || outcome.unsupported_files > 0
+        || outcome.unqualified_files > 0
+        || outcome.truncated_files > 0
+    {
+        SyntaxPrecheckStatus::Incomplete
+    } else if outcome.suspected_recoveries > 0 {
+        SyntaxPrecheckStatus::SuspectedIssue
+    } else {
+        SyntaxPrecheckStatus::Clean
+    };
+    Ok(outcome)
+}
+
+fn valid_relative_path(path: &str) -> bool {
+    !path.is_empty()
+        && !path.starts_with('/')
+        && !path.contains('\\')
+        && !path.chars().any(char::is_control)
+        && path
+            .split('/')
+            .all(|part| !part.is_empty() && part != "." && part != "..")
+}

crates/codeguard-core/src/syntax_precheck_outcome.rs

@@ -0,0 +1,28 @@
+use serde::Serialize;
+
+use crate::SyntaxPrecheckStatus;
+
+/// 选定文件集的纯领域聚合；不能作为 lint 通过或项目门禁依据。
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+pub struct SyntaxPrecheckOutcome {
+    /// 总体初检状态。
+    pub status: SyntaxPrecheckStatus,
+    /// 选定范围的枚举与输入核对是否完成。
+    pub scope_complete: bool,
+    /// 本次初检是否收到取消请求。
+    pub cancelled: bool,
+    /// 选定源码文件数。
+    pub selected_files: usize,
+    /// 已解析文件数，含版本/方言尚未验收者。
+    pub checked_files: usize,
+    /// 解析或输入核对未完成的文件数。
+    pub incomplete_files: usize,
+    /// 不支持的文件数。
+    pub unsupported_files: usize,
+    /// 虽已解析但 grammar 版本/方言未获验收的文件数。
+    pub unqualified_files: usize,
+    /// 恢复节点或遍历预算截断的文件数。
+    pub truncated_files: usize,
+    /// 已观察 ERROR/MISSING 数；疑似观察不等于原生违规。
+    pub suspected_recoveries: usize,
+}

crates/codeguard-core/src/syntax_precheck_status.rs

@@ -0,0 +1,17 @@
+use serde::Serialize;
+
+/// 语法初检的总体状态，与原生检查和交付结论分离。
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SyntaxPrecheckStatus {
+    /// 没有选定文件，初检没有执行。
+    NotRun,
+    /// 非空选定范围全部由已验收 grammar 检查，且无恢复节点。
+    Clean,
+    /// 完整初检观察到 ERROR/MISSING，仍需原生确认。
+    SuspectedIssue,
+    /// 有未完成或范围混合缺口；已观察疑似节点仍保留。
+    Incomplete,
+    /// 全部选定文件均不受支持。
+    Unsupported,
+}