解析 Cargo 显式工作区文档规则引用并核验路径边界

Author: loong10k

README.md

@@ -1103,4 +1103,4 @@ Native Clippy documentation findings now receive specific Errors/Panics/Safety r
 
 Cargo documentation discovery now records manifest levels for five exact native lints per build root, bound to the observed manifest digest. Inheritance, groups, source attributes and absent declarations remain unresolved. Initialization stores details in the profile and retains AGENTS summaries/references; it does not add rules or qualify detailed documentation. See [declaration acceptance](tests/acceptance/cargo-documentation-declarations.md).
 
-Cargo documentation discovery now associates an opted-in member with its nearest observed workspace lint declarations, retaining both manifest identities and the original member configuration reference. Unreadable or changed candidates are incomplete; nearer invalid/missing rules are not replaced with farther rules. Explicit workspace references and full membership/effective coverage remain unresolved. This candidate association grants no production qualification.
+Cargo documentation discovery now associates an opted-in member with its nearest observed workspace lint declarations, retaining both manifest identities and the original member configuration reference. Unreadable or changed candidates are incomplete; nearer invalid/missing rules are not replaced with farther rules. Project-local portable relative package.workspace references now select only their declared source, with bounded traversal and digest checks; absolute/nonportable references and full membership/effective coverage remain unresolved. This candidate association grants no production qualification.

README.zh-CN.md

@@ -1080,4 +1080,4 @@ Rust 的详细文档任务现对原生 Clippy `missing_errors_doc`、`missing_pa
 
 Cargo 文档配置现在逐构建根记录五项精确 lint 的清单声明等级，绑定同次摘要；继承、组、源码属性和未声明均保留待核验。`init` 将详情写入项目画像，AGENTS 保留摘要与引用，不自行添加规则或授予详细文档合格。见[声明验收](tests/acceptance/cargo-documentation-declarations.md)。
 
-Cargo文档配置发现现可将明确选择继承的成员与最近已观察workspace规则关联，保留两份清单身份及原成员配置引用；候选不可读或变化保持发现不完整，最近规则缺失/非法不能借用更远规则。显式workspace引用、完整成员归属与生效覆盖仍待核验，这项候选关联不授予生产资格。
+Cargo文档配置发现现可将明确选择继承的成员与最近已观察workspace规则关联，保留两份清单身份及原成员配置引用；候选不可读或变化保持发现不完整，最近规则缺失/非法不能借用更远规则。项目内便携相对package.workspace引用现只选择声明来源并核验有界遍历及摘要；绝对/非便携引用、完整成员归属与生效覆盖仍待核验，这项候选关联不授予生产资格。

crates/codeguard-adapters/src/cargo_documentation_workspace.rs

@@ -1,9 +1,9 @@
 //! 工作区文档规则的候选来源关联；不计算 Cargo 成员归属或有效 lint 覆盖。
-use crate::{CheckerConfiguration, inspect_cargo_documentation_config};
+use crate::{CargoWorkspaceReference, CheckerConfiguration, inspect_cargo_documentation_config};
 
 /// 关联显式继承成员与一份已绑定摘要的工作区候选清单。
 /// 参数是成员/候选清单字节、成员构建根和两份来源；无 workspace 返回 None 以继续祖先搜索。
-/// 返回配置始终 unknown；显式 package.workspace、非法数据或缺规则均不能推断生效。
+/// 返回配置始终 unknown；显式引用必须匹配目标，非法数据或缺规则均不能推断生效。
 pub fn inspect_cargo_documentation_workspace(
     member: &[u8],
     candidate: &[u8],
@@ -19,15 +19,20 @@ pub fn inspect_cargo_documentation_workspace(
         return Some(rows);
     }
     let parsed_member = parse(member)?;
-    if parsed_member
-        .get("package")
-        .and_then(|p| p.get("workspace"))
-        .is_some()
-    {
-        for row in &mut rows {
-            row.reason = "cargo_doc_lints_explicit_workspace_reference_unresolved".into();
+    match CargoWorkspaceReference::observe(member, source) {
+        Ok(Some(reference)) if reference.manifest != workspace_source => {
+            for row in &mut rows {
+                row.reason = "cargo_doc_lints_explicit_workspace_reference_unresolved".into();
+            }
+            return Some(rows);
         }
-        return Some(rows);
+        Err(_) => {
+            for row in &mut rows {
+                row.reason = "cargo_doc_lints_explicit_workspace_reference_invalid".into();
+            }
+            return Some(rows);
+        }
+        _ => {}
     }
     let Some(parsed) = parse(candidate) else {
         for row in &mut rows {

crates/codeguard-adapters/src/cargo_workspace_reference.rs

@@ -0,0 +1,149 @@
+//! Cargo 显式工作区引用的有界路径计划；不访问文件系统或计算成员归属。
+
+/// 一份显式工作区目录引用的项目内候选路径及必须逐项核验的目录。
+#[derive(Debug, Eq, PartialEq)]
+pub struct CargoWorkspaceReference {
+    /// 项目根相对的候选清单；仅在全部遍历目录和当前摘要核验后可读取。
+    pub manifest: String,
+    /// 按遍历顺序保留目录，包括被父目录组件消除的路径；不能跳过缺失或链接。
+    pub traversal_directories: Vec<String>,
+}
+
+impl CargoWorkspaceReference {
+    /// 观察至多256KiB的成员清单和相对来源，返回显式引用路径计划或未声明。
+    /// 非UTF8/TOML、根与成员双角色、非法/绝对/非便携路径、越界和64组件预算返回未解析原因。
+    pub fn observe(member: &[u8], source: &str) -> Result<Option<Self>, &'static str> {
+        if member.len() > 256 * 1024 {
+            return Err("cargo_workspace_reference_manifest_invalid");
+        }
+        let parsed: toml::Value = std::str::from_utf8(member)
+            .ok()
+            .and_then(|s| s.parse().ok())
+            .ok_or("cargo_workspace_reference_manifest_invalid")?;
+        let Some(reference) = parsed.get("package").and_then(|p| p.get("workspace")) else {
+            return Ok(None);
+        };
+        if parsed.get("workspace").is_some() {
+            return Err("cargo_workspace_reference_conflicting_root");
+        }
+        let reference = reference
+            .as_str()
+            .filter(|s| portable_relative(s))
+            .ok_or("cargo_workspace_reference_invalid_path")?;
+        if !portable_relative(source) || source.rsplit('/').next() != Some("Cargo.toml") {
+            return Err("cargo_workspace_reference_invalid_source");
+        }
+        let mut segments: Vec<&str> = source.split('/').collect();
+        segments.pop();
+        if segments.iter().any(|s| matches!(*s, "" | "." | "..")) {
+            return Err("cargo_workspace_reference_invalid_source");
+        }
+        let reference_segments: Vec<&str> = reference.split('/').collect();
+        if segments.len() + reference_segments.len() > 64 {
+            return Err("cargo_workspace_reference_budget_exceeded");
+        }
+        let mut directories = vec![".".into()];
+        for end in 1..=segments.len() {
+            directories.push(segments[..end].join("/"));
+        }
+        for part in reference_segments {
+            match part {
+                "" | "." => {}
+                ".." => {
+                    if segments.pop().is_none() {
+                        return Err("cargo_workspace_reference_outside_project");
+                    }
+                }
+                part => segments.push(part),
+            }
+            directories.push(if segments.is_empty() {
+                ".".into()
+            } else {
+                segments.join("/")
+            });
+        }
+        let prefix = if segments.is_empty() {
+            String::new()
+        } else {
+            format!("{}/", segments.join("/"))
+        };
+        Ok(Some(Self {
+            manifest: format!("{prefix}Cargo.toml"),
+            traversal_directories: directories,
+        }))
+    }
+}
+
+fn portable_relative(path: &str) -> bool {
+    !path.is_empty()
+        && path.len() <= 4096
+        && !path.starts_with('/')
+        && !path.contains(['\\', ':'])
+        && !path.chars().any(char::is_control)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::CargoWorkspaceReference;
+    #[test]
+    fn explicit_reference_preserves_traversal_and_rejects_escape_or_bad_types() {
+        let manifest = |value: &str| format!("[package]\nname='a'\nworkspace={value}\n");
+        let bytes = manifest("'./missing/../shared/'");
+        let r = CargoWorkspaceReference::observe(bytes.as_bytes(), "member/Cargo.toml")
+            .unwrap()
+            .unwrap();
+        assert_eq!(r.manifest, "member/shared/Cargo.toml");
+        assert!(
+            r.traversal_directories
+                .iter()
+                .any(|d| d == "member/missing")
+        );
+        assert_eq!(
+            CargoWorkspaceReference::observe(
+                manifest("'../shared'").as_bytes(),
+                "member/Cargo.toml"
+            )
+            .unwrap()
+            .unwrap()
+            .manifest,
+            "shared/Cargo.toml"
+        );
+        for raw in [
+            "'../../outside'",
+            "'/absolute'",
+            "'C:/absolute'",
+            "true",
+            "[]",
+            "''",
+            "'a\\b'",
+        ] {
+            assert!(
+                CargoWorkspaceReference::observe(manifest(raw).as_bytes(), "member/Cargo.toml")
+                    .is_err(),
+                "{raw}"
+            );
+        }
+        assert!(
+            CargoWorkspaceReference::observe(
+                b"[package]\nworkspace='.'\n[workspace]\n",
+                "Cargo.toml"
+            )
+            .is_err()
+        );
+        assert!(
+            CargoWorkspaceReference::observe(manifest("'.'").as_bytes(), "../Cargo.toml").is_err()
+        );
+        assert!(
+            CargoWorkspaceReference::observe(
+                manifest(&format!("'{}'", "a/".repeat(65))).as_bytes(),
+                "member/Cargo.toml"
+            )
+            .is_err()
+        );
+        assert!(
+            CargoWorkspaceReference::observe(b"[package]\nname='a'\n", "Cargo.toml")
+                .unwrap()
+                .is_none()
+        );
+    }
+}

crates/codeguard-adapters/src/lib.rs

@@ -27,6 +27,7 @@ pub use cargo_build_parsed::CargoBuildParsed;
 mod cargo_clippy;
 mod cargo_documentation_config;
 mod cargo_documentation_workspace;
+mod cargo_workspace_reference;
 mod cargo_module_model;
 mod cargo_edition_declaration;
 mod cargo_rustdoc;
@@ -128,6 +129,7 @@ pub use capability_validation::validate_capability_inventory;
 pub use cargo_clippy::{ClippyFinding, ClippyParsed, parse_cargo_clippy_json};
 pub use cargo_documentation_config::inspect_cargo_documentation_config;
 pub use cargo_documentation_workspace::inspect_cargo_documentation_workspace;
+pub use cargo_workspace_reference::CargoWorkspaceReference;
 pub use cargo_module_model::CargoModuleModel;
 pub use cargo_edition_declaration::CargoEditionDeclaration;
 pub use cargo_rustdoc::parse_cargo_rustdoc_json;

crates/codeguard-cli/src/discovery.rs

@@ -381,6 +381,59 @@ fn inspect_cargo_documentation_context<P: ObservationPort>(
     let Some(member) = bytes else {
         return (original, None);
     };
+    match codeguard_adapters::CargoWorkspaceReference::observe(member, manifest) {
+        Err(reason) => {
+            let mut rows = original;
+            for row in &mut rows {
+                row.reason = "cargo_doc_lints_explicit_workspace_reference_invalid".into();
+                row.next_action = format!(
+                    "显式workspace引用未解析：{reason}；核验原成员清单，不回退祖先规则、不修改无关源码"
+                );
+            }
+            return (rows, None);
+        }
+        Ok(Some(reference)) => {
+            for directory in &reference.traversal_directories {
+                if !matches!(
+                    observation.classify(&root.join(directory)),
+                    Ok(ObservedPathKind::Directory)
+                ) {
+                    return (original, Some(directory.clone()));
+                }
+            }
+            let name = &reference.manifest;
+            if !hashes.contains_key(name)
+                || !matches!(
+                    observation.classify(&root.join(name)),
+                    Ok(ObservedPathKind::File)
+                )
+            {
+                return (original, Some(name.clone()));
+            }
+            let Ok(candidate) = observation.read_bounded(&root.join(name), MAX_MANIFEST_BYTES)
+            else {
+                return (original, Some(name.clone()));
+            };
+            if hashes.get(name) != Some(&format!("{:x}", Sha256::digest(&candidate))) {
+                return (original, Some(name.clone()));
+            }
+            let rows = codeguard_adapters::inspect_cargo_documentation_workspace(
+                member, &candidate, build_root, manifest, name,
+            )
+            .unwrap_or_else(|| {
+                let mut rows = original;
+                for row in &mut rows {
+                    row.reason = "cargo_doc_lints_explicit_workspace_not_defined".into();
+                    row.next_action = format!(
+                        "显式候选清单{name}未声明workspace；核验原package.workspace，不回退祖先规则"
+                    );
+                }
+                rows
+            });
+            return (rows, None);
+        }
+        Ok(None) => {}
+    }
     let mut parent = Path::new(manifest).parent();
     for _ in 0..64 {
         let Some(directory) = parent else {
@@ -878,6 +931,111 @@ mod tests {
         assert!(!rows[1].next_action.contains("missing_errors_doc=warn"));
     }
 
+    struct ExplicitWorkspaceObservation {
+        directory_kind: ObservedPathKind,
+        file_kind: ObservedPathKind,
+        bytes: Result<Vec<u8>, io::ErrorKind>,
+    }
+    impl ObservationPort for ExplicitWorkspaceObservation {
+        fn classify(&self, path: &Path) -> io::Result<ObservedPathKind> {
+            match path.to_str() {
+                Some("project/." | "project/external") => Ok(ObservedPathKind::Directory),
+                Some("project/shared") => Ok(self.directory_kind),
+                Some("project/shared/Cargo.toml") => Ok(self.file_kind),
+                _ => Err(io::Error::from(io::ErrorKind::NotFound)),
+            }
+        }
+        fn children(&self, _path: &Path) -> io::Result<Vec<PathBuf>> {
+            Ok(Vec::new())
+        }
+        fn read_bounded(&self, _path: &Path, _limit: u64) -> io::Result<Vec<u8>> {
+            self.bytes.clone().map_err(io::Error::from)
+        }
+    }
+
+    #[test]
+    fn explicit_cargo_workspace_identity_io_and_links_cannot_borrow_ancestor_rules() {
+        let member = b"[package]\nname='external'\nversion='0.1.0'\nworkspace='../shared'\n[lints]\nworkspace=true\n";
+        let workspace = b"[workspace]\nmembers=['../external']\n[workspace.lints.clippy]\nmissing_errors_doc='warn'\n";
+        let mut hashes = BTreeMap::from([
+            (
+                "external/Cargo.toml".into(),
+                format!("{:x}", Sha256::digest(member)),
+            ),
+            (
+                "shared/Cargo.toml".into(),
+                format!("{:x}", Sha256::digest(workspace)),
+            ),
+        ]);
+        for (directory_kind, file_kind, bytes, blocked) in [
+            (
+                ObservedPathKind::Directory,
+                ObservedPathKind::File,
+                Ok(workspace.to_vec()),
+                None,
+            ),
+            (
+                ObservedPathKind::Directory,
+                ObservedPathKind::File,
+                Ok(b"[workspace]\n".to_vec()),
+                Some("shared/Cargo.toml"),
+            ),
+            (
+                ObservedPathKind::Directory,
+                ObservedPathKind::File,
+                Err(io::ErrorKind::PermissionDenied),
+                Some("shared/Cargo.toml"),
+            ),
+            (
+                ObservedPathKind::Symlink,
+                ObservedPathKind::File,
+                Ok(workspace.to_vec()),
+                Some("shared"),
+            ),
+            (
+                ObservedPathKind::Directory,
+                ObservedPathKind::Symlink,
+                Ok(workspace.to_vec()),
+                Some("shared/Cargo.toml"),
+            ),
+        ] {
+            let port = ExplicitWorkspaceObservation {
+                directory_kind,
+                file_kind,
+                bytes,
+            };
+            let (rows, actual) = super::inspect_cargo_documentation_context(
+                Some(member),
+                "external",
+                "external/Cargo.toml",
+                Path::new("project"),
+                &hashes,
+                &port,
+            );
+            assert_eq!(actual.as_deref(), blocked);
+            assert!(rows.iter().all(|r| r.configuration == "unknown"));
+            assert_eq!(
+                rows[1].next_action.contains("missing_errors_doc=warn"),
+                blocked.is_none()
+            );
+        }
+        hashes.remove("shared/Cargo.toml");
+        let port = ExplicitWorkspaceObservation {
+            directory_kind: ObservedPathKind::Directory,
+            file_kind: ObservedPathKind::File,
+            bytes: Ok(workspace.to_vec()),
+        };
+        let (_, blocked) = super::inspect_cargo_documentation_context(
+            Some(member),
+            "external",
+            "external/Cargo.toml",
+            Path::new("project"),
+            &hashes,
+            &port,
+        );
+        assert_eq!(blocked.as_deref(), Some("shared/Cargo.toml"));
+    }
+
     struct ChangingCargoObservation(std::cell::Cell<usize>);
     impl ObservationPort for ChangingCargoObservation {
         fn classify(&self, path: &Path) -> io::Result<ObservedPathKind> {