feat: 区分项目本地原生工具候选与安装建议

Author: loong10k

crates/codeguard-adapters/src/eslint_config_state.rs

@@ -0,0 +1,10 @@
+/// ESLint 原配置的只读观察状态；静态存在不等于原生配置有效。
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum EslintConfigState {
+    /// 已观察到配置文件，动态加载和规则仍待原生核验。
+    Observed,
+    /// 配置文件或其声明已确定无效。
+    Invalid,
+    /// 配置尚未可判定。
+    Unknown,
+}

crates/codeguard-adapters/src/eslint_local_candidate.rs

@@ -0,0 +1,12 @@
+/// 项目本地 ESLint 的只读准备候选；不能单独授权执行或证明 lint 覆盖。
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct EslintLocalCandidate {
+    /// 结构化候选状态，绝不把 PATH 不可见等同工具缺失。
+    pub state: &'static str,
+    /// 根 package.json 中的原始 ESLint 版本声明（如有）。
+    pub declared_spec: Option<String>,
+    /// 项目本地 ESLint package.json 中的具体版本（如有效）。
+    pub observed_version: Option<String>,
+    /// 供智能体继续核验的具体动作，不是自动安装指令。
+    pub next_action: &'static str,
+}

crates/codeguard-adapters/src/eslint_local_readiness.rs

@@ -0,0 +1,186 @@
+use codeguard_core::ObservedPathKind;
+use serde_json::Value;
+
+use crate::{EslintConfigState, EslintLocalCandidate, strict_json::parse_unique_json};
+
+/// 只读核对项目声明、本地包身份、原生入口与配置状态；不搜索 PATH 或执行 JS。
+/// 输入由调用方有界读取并分类；返回候选，不证明 Node 或 ESLint 本轮执行成功。
+pub fn inspect_eslint_local_candidate(
+    project_manifest: Option<&[u8]>,
+    local_manifest: Option<&[u8]>,
+    entry_kind: Option<ObservedPathKind>,
+    config: EslintConfigState,
+) -> EslintLocalCandidate {
+    let declared_spec = match project_manifest.map(parse_project_declaration).transpose() {
+        Ok(value) => value.flatten(),
+        Err(()) => {
+            return candidate(
+                "project_manifest_invalid",
+                None,
+                None,
+                "修正项目 package.json 的 JSON 或 ESLint 依赖声明后重查本地工具身份",
+            );
+        }
+    };
+    let observed_version = match local_manifest.map(parse_local_identity).transpose() {
+        Ok(value) => value,
+        Err(()) => {
+            return candidate(
+                "local_package_identity_invalid",
+                declared_spec,
+                None,
+                "核对项目本地 ESLint package.json、版本和 bin 入口；不要把损坏制品说成源码违规",
+            );
+        }
+    };
+    if config == EslintConfigState::Invalid {
+        return candidate(
+            "configuration_invalid",
+            declared_spec,
+            observed_version,
+            "修正项目原 ESLint 配置后用已发现的原生工具复检",
+        );
+    }
+    if matches!(
+        entry_kind,
+        Some(ObservedPathKind::Symlink | ObservedPathKind::Directory | ObservedPathKind::Other)
+    ) {
+        return candidate(
+            "local_entry_untrusted",
+            declared_spec,
+            observed_version,
+            "核对项目本地 ESLint 入口的真实类型与来源，不跟随未知链接执行",
+        );
+    }
+    if entry_kind == Some(ObservedPathKind::File) {
+        return match observed_version {
+            Some(version)
+                if declared_spec
+                    .as_deref()
+                    .and_then(|spec| semver::Version::parse(spec).ok())
+                    .is_some_and(|exact| exact.to_string() != version) =>
+            {
+                candidate(
+                    "local_version_conflicts_with_declaration",
+                    declared_spec,
+                    Some(version),
+                    "核对项目固定声明与本地 ESLint 包版本，按原项目依赖方案恢复一致后原生复检",
+                )
+            }
+            Some(version) if supported_version(&version) => candidate(
+                "local_candidate_requires_native_probe",
+                declared_spec,
+                Some(version),
+                "用明确的 Node 路径、项目本地 ESLint 入口及原配置执行版本和规则核验",
+            ),
+            Some(version) => candidate(
+                "local_version_not_supported_by_adapter",
+                declared_spec,
+                Some(version),
+                "核对项目实际 ESLint 版本并补齐相应原生适配器，不按旧版结果放行",
+            ),
+            None => candidate(
+                "local_entry_identity_unknown",
+                declared_spec,
+                None,
+                "读取并核对项目本地 ESLint 包清单和入口版本后再执行，不根据 PATH 猜测",
+            ),
+        };
+    }
+    if declared_spec.is_some() || observed_version.is_some() {
+        candidate(
+            "declared_local_entry_unobserved",
+            declared_spec,
+            observed_version,
+            "核对项目本地入口、包管理器布局或显式工具路径；不能仅凭 PATH 判定未安装",
+        )
+    } else {
+        candidate(
+            "unknown",
+            None,
+            None,
+            "确认项目是否要求 ESLint，以及其本地或显式原生工具位置与配置",
+        )
+    }
+}
+
+fn parse_project_declaration(raw: &[u8]) -> Result<Option<String>, ()> {
+    let object = parsed_object(raw)?;
+    let mut declared: Option<&str> = None;
+    for field in [
+        "dependencies",
+        "devDependencies",
+        "optionalDependencies",
+        "peerDependencies",
+    ] {
+        let Some(group) = object.get(field) else {
+            continue;
+        };
+        let dependencies = group.as_object().ok_or(())?;
+        if let Some(raw_spec) = dependencies.get("eslint") {
+            let spec = raw_spec
+                .as_str()
+                .filter(|value| valid_spec(value))
+                .ok_or(())?;
+            if declared.is_some_and(|previous| previous != spec) {
+                return Err(());
+            }
+            declared = Some(spec);
+        }
+    }
+    Ok(declared.map(str::to_owned))
+}
+
+fn parse_local_identity(raw: &[u8]) -> Result<String, ()> {
+    let object = parsed_object(raw)?;
+    if object.get("name").and_then(Value::as_str) != Some("eslint") {
+        return Err(());
+    }
+    let version = object.get("version").and_then(Value::as_str).ok_or(())?;
+    let parsed = semver::Version::parse(version).map_err(|_| ())?;
+    if !parsed.pre.is_empty() || !parsed.build.is_empty() {
+        return Err(());
+    }
+    let entry = match object.get("bin") {
+        Some(Value::String(path)) => Some(path.as_str()),
+        Some(Value::Object(bins)) => bins.get("eslint").and_then(Value::as_str),
+        _ => None,
+    };
+    if entry != Some("bin/eslint.js") {
+        return Err(());
+    }
+    Ok(version.into())
+}
+
+fn parsed_object(raw: &[u8]) -> Result<serde_json::Map<String, Value>, ()> {
+    if raw.is_empty() || raw.len() > 256 * 1024 {
+        return Err(());
+    }
+    parse_unique_json(raw)
+        .map_err(|_| ())?
+        .as_object()
+        .cloned()
+        .ok_or(())
+}
+
+fn valid_spec(value: &str) -> bool {
+    !value.trim().is_empty() && value.len() <= 256 && !value.chars().any(char::is_control)
+}
+
+fn supported_version(version: &str) -> bool {
+    semver::Version::parse(version).is_ok_and(|parsed| parsed.major == 10)
+}
+
+fn candidate(
+    state: &'static str,
+    declared_spec: Option<String>,
+    observed_version: Option<String>,
+    next_action: &'static str,
+) -> EslintLocalCandidate {
+    EslintLocalCandidate {
+        state,
+        declared_spec,
+        observed_version,
+        next_action,
+    }
+}

crates/codeguard-adapters/src/lib.rs

@@ -27,6 +27,9 @@ mod checkstyle_parsed;
 mod checkstyle_result;
 mod checkstyle_rule_binding;
 mod eslint_command;
+mod eslint_config_state;
+mod eslint_local_candidate;
+mod eslint_local_readiness;
 mod npm_audit_command;
 mod npm_locked_node;
 mod rustdoc_finding;
@@ -41,6 +44,9 @@ mod npm_audit_observation;
 mod source_map;
 mod source_mapped_recovery;
 mod strict_json;
+pub use eslint_config_state::EslintConfigState;
+pub use eslint_local_candidate::EslintLocalCandidate;
+pub use eslint_local_readiness::inspect_eslint_local_candidate;
 pub use npm_audit_component::NpmAuditComponent;
 pub use npm_audit_json::parse_npm_audit_json;
 pub use npm_audit_observation::NpmAuditObservation;
@@ -69,6 +75,8 @@ mod maven_dependency_pom;
 mod maven_dependency_tree;
 mod maven_javadoc_output;
 mod maven_module_model;
+mod maven_wrapper_candidate;
+mod maven_wrapper_readiness;
 mod owasp_dependency_check;
 mod owasp_maven_attribution;
 mod owasp_maven_pom;
@@ -126,6 +134,8 @@ pub use maven_javadoc_output::{
     MavenJavadocDiagnostic, MavenJavadocParseState, MavenJavadocParsed, parse_maven_javadoc_output,
 };
 pub use maven_module_model::MavenModuleModel;
+pub use maven_wrapper_candidate::MavenWrapperCandidate;
+pub use maven_wrapper_readiness::inspect_maven_wrapper_candidate;
 pub use owasp_dependency_check::{
     OwaspAdvisoryObservation, OwaspDependencyCheckReport, parse_owasp_dependency_check_json,
 };

crates/codeguard-adapters/src/maven_wrapper_candidate.rs

@@ -0,0 +1,10 @@
+/// Maven Wrapper 的只读准备状态；候选不表示已执行 Maven。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MavenWrapperCandidate {
+    /// 观察到的具体状态。
+    pub state: &'static str,
+    /// 从固定 distributionUrl 观察到的 Maven 版本。
+    pub observed_version: Option<String>,
+    /// 下一步核验或修复建议。
+    pub next_action: &'static str,
+}

crates/codeguard-adapters/src/maven_wrapper_readiness.rs

@@ -0,0 +1,109 @@
+use codeguard_core::ObservedPathKind;
+
+use crate::MavenWrapperCandidate;
+
+/// 只读核对 Maven Wrapper 脚本和配置；不查 PATH、不执行脚本，也不下载发行包。
+/// 参数是调用方分类后的脚本类型及有界读取的 properties；返回候选而非检查通过。
+pub fn inspect_maven_wrapper_candidate(
+    script_kind: Option<ObservedPathKind>,
+    properties: Option<&[u8]>,
+) -> MavenWrapperCandidate {
+    let version = match properties.map(parse_distribution_version).transpose() {
+        Ok(value) => value,
+        Err(()) => {
+            return candidate(
+                "wrapper_configuration_invalid",
+                None,
+                "修正 Maven Wrapper 的 distributionUrl 配置，再核对原生 Maven 版本",
+            );
+        }
+    };
+    if matches!(
+        script_kind,
+        Some(ObservedPathKind::Symlink | ObservedPathKind::Directory | ObservedPathKind::Other)
+    ) {
+        return candidate(
+            "wrapper_script_untrusted",
+            version,
+            "核对 Maven Wrapper 脚本的真实类型与来源，不跟随未知链接执行",
+        );
+    }
+    match (script_kind, version) {
+        (Some(ObservedPathKind::File), Some(version)) => {
+            let state = if semver::Version::parse(&version).is_ok_and(|parsed| parsed.major == 3) {
+                "wrapper_candidate_requires_native_probe"
+            } else {
+                "wrapper_version_not_supported_by_adapter"
+            };
+            let action = if state == "wrapper_candidate_requires_native_probe" {
+                "以受控方式执行项目 Maven Wrapper 的版本探针，再运行项目原生检查"
+            } else {
+                "核对项目 Maven 版本并补齐相应适配器，不按旧版结果放行"
+            };
+            candidate(state, Some(version), action)
+        }
+        (None, Some(version)) => candidate(
+            "wrapper_script_unobserved",
+            Some(version),
+            "核对项目 Maven Wrapper 脚本或显式 Maven 路径，不能仅凭 PATH 判定未安装",
+        ),
+        (Some(ObservedPathKind::File), None) => candidate(
+            "wrapper_configuration_unobserved",
+            None,
+            "核对 Maven Wrapper 配置或显式 Maven 路径，不能仅凭 PATH 判定未安装",
+        ),
+        (None, None) => candidate(
+            "unknown",
+            None,
+            "确认项目构建器、Wrapper 和显式 Maven 路径，再判断原生检查准备状态",
+        ),
+        _ => unreachable!("已处理全部非文件脚本类型"),
+    }
+}
+
+fn parse_distribution_version(raw: &[u8]) -> Result<String, ()> {
+    if raw.is_empty() || raw.len() > 64 * 1024 {
+        return Err(());
+    }
+    let text = std::str::from_utf8(raw).map_err(|_| ())?;
+    let mut distribution_url: Option<&str> = None;
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') || line.starts_with('!') {
+            continue;
+        }
+        let Some((key, value)) = line.split_once('=') else {
+            continue;
+        };
+        if key.trim() == "distributionUrl" {
+            if distribution_url.is_some() {
+                return Err(());
+            }
+            distribution_url = Some(value.trim());
+        }
+    }
+    let url = distribution_url.ok_or(())?.replace("\\:", ":");
+    let filename = url.rsplit('/').next().ok_or(())?;
+    let without_prefix = filename.strip_prefix("apache-maven-").ok_or(())?;
+    let version = without_prefix
+        .strip_suffix("-bin.zip")
+        .or_else(|| without_prefix.strip_suffix("-bin.tar.gz"))
+        .ok_or(())?;
+    let parsed = semver::Version::parse(version).map_err(|_| ())?;
+    if !parsed.pre.is_empty() || !parsed.build.is_empty() {
+        return Err(());
+    }
+    Ok(version.to_owned())
+}
+
+fn candidate(
+    state: &'static str,
+    observed_version: Option<String>,
+    next_action: &'static str,
+) -> MavenWrapperCandidate {
+    MavenWrapperCandidate {
+        state,
+        observed_version,
+        next_action,
+    }
+}