jarvis-ai-assistant 0.7.16__py3-none-any.whl → 1.0.2__py3-none-any.whl

jarvis/jarvis_c2rust/transpiler_generation.py

@@ -0,0 +1,278 @@
+# -*- coding: utf-8 -*-
+"""
+代码生成模块
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import List
+from typing import cast
+
+from jarvis.jarvis_utils.output import PrettyOutput
+
+from jarvis.jarvis_c2rust.models import FnRecord
+
+
+class GenerationManager:
+    """代码生成管理器"""
+
+    def __init__(
+        self,
+        project_root: Path,
+        crate_dir: Path,
+        data_dir: Path,
+        disabled_libraries: List[str],
+        extract_compile_flags_func,
+        append_additional_notes_func,
+        is_root_symbol_func,
+        get_generation_agent_func,
+        compose_prompt_with_context_func,
+        check_and_handle_test_deletion_func,
+        get_crate_commit_hash_func,
+        ensure_top_level_pub_mod_func,
+    ) -> None:
+        self.project_root = project_root
+        self.crate_dir = crate_dir
+        self.data_dir = data_dir
+        self.disabled_libraries = disabled_libraries
+        self.extract_compile_flags = extract_compile_flags_func
+        self.append_additional_notes = append_additional_notes_func
+        self.is_root_symbol = is_root_symbol_func
+        self.get_generation_agent = get_generation_agent_func
+        self.compose_prompt_with_context = compose_prompt_with_context_func
+        self.check_and_handle_test_deletion = check_and_handle_test_deletion_func
+        self.get_crate_commit_hash = get_crate_commit_hash_func
+        self.ensure_top_level_pub_mod = ensure_top_level_pub_mod_func
+
+    def build_generate_impl_prompt(
+        self,
+        rec: FnRecord,
+        c_code: str,
+        module: str,
+        rust_sig: str,
+        unresolved: List[str],
+    ) -> str:
+        """
+        构建代码生成提示词。
+
+        返回完整的提示词字符串。
+        """
+        symbols_path = str((self.data_dir / "symbols.jsonl").resolve())
+        is_root = self.is_root_symbol(rec)
+        # 获取 C 源文件位置信息
+        c_file_location = ""
+        if hasattr(rec, "file") and rec.file:
+            if (
+                hasattr(rec, "start_line")
+                and hasattr(rec, "end_line")
+                and rec.start_line
+                and rec.end_line
+            ):
+                c_file_location = f"{rec.file}:{rec.start_line}-{rec.end_line}"
+            else:
+                c_file_location = str(rec.file)
+
+        requirement_lines = [
+            f"目标：在 {module} 中，使用 TDD 方法为 C 函数 {rec.qname or rec.name} 生成 Rust 实现。",
+            f"函数签名：{rust_sig}",
+            f"crate 目录：{self.crate_dir.resolve()}",
+            f"C 工程目录：{self.project_root.resolve()}",
+            *([f"C 源文件位置：{c_file_location}"] if c_file_location else []),
+            *(
+                ["根符号要求：必须使用 `pub` 关键字，模块必须在 src/lib.rs 中导出"]
+                if is_root
+                else []
+            ),
+            "",
+            "【TDD 流程】",
+            "1. Red：先写测试（#[cfg(test)] mod tests），基于 C 函数行为设计测试用例",
+            "2. Green：编写实现使测试通过，确保与 C 语义等价",
+            "3. Refactor：优化代码，保持测试通过",
+            "   - 如果发现现有测试用例有错误，优先修复测试用例而不是删除",
+            "",
+            "【核心要求】",
+            "- 先写测试再写实现，测试必须可编译通过",
+            "- ⚠️ 重要：如果发现现有测试用例有错误（如测试逻辑错误、断言不正确、测试用例设计不当等），应该修复测试用例而不是删除它们。只有在测试用例完全重复、过时或确实不需要时才能删除。",
+            "- ⚠️ 重要：不要将正式代码写到测试区域。所有正式的函数实现、类型定义、常量等都应该写在 `#[cfg(test)] mod tests { ... }` 块之外。测试代码（测试函数、测试辅助函数等）才应该写在 `#[cfg(test)] mod tests { ... }` 块内部。",
+            "- ⚠️ 重要：测试用例必须尽可能完备，因为后续 review 阶段会检测测试用例完备性，避免返工。测试用例应该包括：",
+            "  * 主要功能路径的测试：覆盖函数的核心功能和预期行为",
+            "  * 边界情况测试：空输入（空字符串、空数组、空指针等）、极值输入（最大值、最小值、零值等）、边界值（数组边界、字符串长度边界等）、特殊值（负数、NaN、无穷大等，如果适用）",
+            "  * 错误情况测试：如果 C 实现有错误处理（如返回错误码、设置 errno 等），测试用例应该覆盖这些错误情况。如果 Rust 实现使用 Result<T, E> 或 Option<T> 处理错误，测试用例应该验证错误情况",
+            "  * 与 C 实现行为一致性：测试用例的预期结果应该与 C 实现的行为一致",
+            "  * 测试用例质量：测试名称清晰、断言适当、测试逻辑正确，能够真正验证函数的功能",
+            "  * 注意：如果函数是资源释放类函数（如 fclose、free 等），在 Rust 中通过 RAII 自动管理，测试用例可以非常简单（如仅验证函数可以调用而不崩溃），这是可以接受的",
+            "- 禁止使用 todo!/unimplemented!，必须实现完整功能",
+            "- 使用 Rust 原生类型（i32/u32、&str/String、&[T]/&mut [T]、Result<T,E>），避免 C 风格类型",
+            '- 禁止使用 extern "C"，使用标准 Rust 调用约定',
+            "- 保持最小变更，避免无关重构",
+            "- 注释使用中文，禁止 use ...::* 通配导入",
+            "- 资源释放类函数（fclose/free 等）可通过 RAII 自动管理，提供空实现并在文档中说明",
+            *(
+                [f"- 禁用库：{', '.join(self.disabled_libraries)}"]
+                if self.disabled_libraries
+                else []
+            ),
+            "",
+            "【依赖处理】",
+            "- 检查依赖函数是否已实现，未实现的需一并补齐（遵循 TDD：先测试后实现）",
+            "- 使用 read_symbols/read_code 获取 C 源码",
+            "- 优先处理底层依赖，确保所有测试通过",
+            "",
+            "【工具】",
+            f'- read_symbols: {{"symbols_file": "{symbols_path}", "symbols": [...]}}',
+            "- read_code: 读取 C 源码或 Rust 模块",
+            "",
+            *([f"未转换符号：{', '.join(unresolved)}"] if unresolved else []),
+            "",
+            "C 源码：",
+            "<C_SOURCE>",
+            c_code,
+            "</C_SOURCE>",
+            "",
+            "签名参考：",
+            json.dumps(
+                {
+                    "signature": getattr(rec, "signature", ""),
+                    "params": getattr(rec, "params", None),
+                },
+                ensure_ascii=False,
+                indent=2,
+            ),
+            "",
+            "仅输出补丁，不要解释。",
+        ]
+        # 若存在库替代上下文，则附加到实现提示中，便于生成器参考（多库组合、参考API、备注等）
+        librep_ctx = None
+        try:
+            librep_ctx = getattr(rec, "lib_replacement", None)
+        except Exception:
+            librep_ctx = None
+        if isinstance(librep_ctx, dict) and librep_ctx:
+            requirement_lines.extend(
+                [
+                    "",
+                    "库替代上下文（若存在）：",
+                    json.dumps(librep_ctx, ensure_ascii=False, indent=2),
+                    "",
+                ]
+            )
+        # 添加编译参数（如果存在）
+        compile_flags = None
+        if hasattr(rec, "file") and rec.file:
+            compile_flags = self.extract_compile_flags(rec.file)
+        if compile_flags:
+            requirement_lines.extend(
+                [
+                    "",
+                    "C文件编译参数（来自 compile_commands.json）：",
+                    compile_flags,
+                    "",
+                ]
+            )
+        prompt = "\n".join(requirement_lines)
+        return cast(str, self.append_additional_notes(prompt))
+
+    def extract_rust_fn_name_from_sig(self, rust_sig: str) -> str:
+        """
+        从 rust 签名中提取函数名，支持生命周期参数和泛型参数。
+        例如: 'pub fn foo(a: i32) -> i32 { ... }' -> 'foo'
+        例如: 'pub fn foo<'a>(bzf: &'a mut BzFile) -> Result<&'a [u8], BzError>' -> 'foo'
+        """
+        # 支持生命周期参数和泛型参数：fn name<'a, T>(...)
+        m = re.search(
+            r"\bfn\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]+>)?\s*\(", rust_sig or ""
+        )
+        return m.group(1) if m else ""
+
+    def codeagent_generate_impl(
+        self,
+        rec: FnRecord,
+        c_code: str,
+        module: str,
+        rust_sig: str,
+        unresolved: List[str],
+    ) -> None:
+        """
+        使用 CodeAgent 生成/更新目标模块中的函数实现。
+        约束：最小变更，生成可编译的占位实现，尽可能保留后续细化空间。
+        """
+        # 构建提示词
+        prompt = self.build_generate_impl_prompt(
+            rec, c_code, module, rust_sig, unresolved
+        )
+
+        # 确保目标模块文件存在（提高补丁应用与实现落盘的确定性）
+        try:
+            mp = Path(module)
+            if not mp.is_absolute():
+                mp = (self.crate_dir / module).resolve()
+            mp.parent.mkdir(parents=True, exist_ok=True)
+            if not mp.exists():
+                try:
+                    mp.write_text(
+                        "// Auto-created by c2rust transpiler\n", encoding="utf-8"
+                    )
+                    PrettyOutput.auto_print(
+                        f"✅ [c2rust-transpiler][gen] auto-created module file: {mp}"
+                    )
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+        # 由于 transpile() 开始时已切换到 crate 目录，此处无需再次切换
+        # 记录运行前的 commit
+        before_commit = self.get_crate_commit_hash()
+        # 使用生成 Agent（可以复用）
+        agent = self.get_generation_agent()
+        agent.run(
+            self.compose_prompt_with_context(prompt),
+            prefix="[c2rust-transpiler][gen]",
+            suffix="",
+        )
+
+        # 检测并处理测试代码删除
+        if self.check_and_handle_test_deletion(before_commit, agent):
+            # 如果回退了，需要重新运行 agent
+            PrettyOutput.auto_print(
+                "⚠️ [c2rust-transpiler][gen] 检测到测试代码删除问题，已回退，重新运行 agent"
+            )
+            before_commit = self.get_crate_commit_hash()
+            # 重试时使用相同的 prompt（已包含 C 源文件位置信息）
+            agent.run(
+                self.compose_prompt_with_context(prompt),
+                prefix="[c2rust-transpiler][gen][retry]",
+                suffix="",
+            )
+            # 再次检测
+            if self.check_and_handle_test_deletion(before_commit, agent):
+                PrettyOutput.auto_print(
+                    "❌ [c2rust-transpiler][gen] 再次检测到测试代码删除问题，已回退"
+                )
+
+        # 如果是根符号，确保其模块在 lib.rs 中被暴露
+        if self.is_root_symbol(rec):
+            try:
+                mp = Path(module)
+                crate_root = self.crate_dir.resolve()
+                rel = (
+                    mp.resolve().relative_to(crate_root)
+                    if mp.is_absolute()
+                    else Path(module)
+                )
+                rel_s = str(rel).replace("\\", "/")
+                if rel_s.startswith("./"):
+                    rel_s = rel_s[2:]
+                if rel_s.startswith("src/"):
+                    parts = rel_s[len("src/") :].strip("/").split("/")
+                    if parts and parts[0]:
+                        top_mod = parts[0]
+                        # 过滤掉 "mod" 关键字和 .rs 文件
+                        if top_mod != "mod" and not top_mod.endswith(".rs"):
+                            self.ensure_top_level_pub_mod(top_mod)
+                            PrettyOutput.auto_print(
+                                f"📋 [c2rust-transpiler][gen] 根符号 {rec.qname or rec.name} 的模块 {top_mod} 已在 lib.rs 中暴露"
+                            )
+            except Exception:
+                pass

jarvis/jarvis_c2rust/transpiler_git.py

@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""
+Git 操作模块
+"""
+
+import subprocess
+from typing import Optional
+
+from jarvis.jarvis_utils.git_utils import get_latest_commit_hash
+
+
+class GitManager:
+    """Git 操作管理器"""
+
+    def __init__(self, crate_dir: str) -> None:
+        self.crate_dir = crate_dir
+
+    def get_crate_commit_hash(self) -> Optional[str]:
+        """获取 crate 目录的当前 commit id"""
+        try:
+            # 由于 transpile() 开始时已切换到 crate 目录，此处无需再次切换
+            commit_hash = get_latest_commit_hash()
+            return commit_hash if commit_hash else None
+        except Exception:
+            return None
+
+    def get_git_diff(self, base_commit: Optional[str] = None) -> str:
+        """
+        获取 git diff，显示从 base_commit 到当前工作区的变更
+
+        参数:
+            base_commit: 基准 commit hash，如果为 None 则使用 HEAD
+
+        返回:
+            str: git diff 内容，如果获取失败则返回空字符串
+        """
+        try:
+            # 检查是否是 git 仓库
+            check_git_result = subprocess.run(
+                ["git", "rev-parse", "--git-dir"],
+                capture_output=True,
+                text=True,
+                check=False,
+                cwd=self.crate_dir,
+            )
+            if check_git_result.returncode != 0:
+                # 不是 git 仓库，无法获取 diff
+                return ""
+
+            if base_commit:
+                # 先检查 base_commit 是否存在
+                check_result = subprocess.run(
+                    ["git", "rev-parse", "--verify", base_commit],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    cwd=self.crate_dir,
+                )
+                if check_result.returncode != 0:
+                    # base_commit 不存在，使用 HEAD 作为基准
+                    base_commit = None
+
+            # 检查是否有 HEAD
+            head_check = subprocess.run(
+                ["git", "rev-parse", "--verify", "HEAD"],
+                capture_output=True,
+                text=True,
+                check=False,
+                cwd=self.crate_dir,
+            )
+            has_head = head_check.returncode == 0
+
+            # 临时暂存新增文件以便获取完整的 diff
+            subprocess.run(
+                ["git", "add", "-N", "."],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                cwd=self.crate_dir,
+            )
+
+            try:
+                if base_commit:
+                    # 获取从 base_commit 到当前工作区的差异
+                    result = subprocess.run(
+                        ["git", "diff", base_commit],
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        check=False,
+                        cwd=self.crate_dir,
+                    )
+                elif has_head:
+                    # 获取从 HEAD 到当前工作区的差异
+                    result = subprocess.run(
+                        ["git", "diff", "HEAD"],
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        check=False,
+                        cwd=self.crate_dir,
+                    )
+                else:
+                    # 空仓库，获取工作区差异
+                    result = subprocess.run(
+                        ["git", "diff"],
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        check=False,
+                        cwd=self.crate_dir,
+                    )
+
+                return result.stdout or "" if result.returncode == 0 else ""
+            finally:
+                # 重置暂存区
+                subprocess.run(
+                    ["git", "reset"],
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    cwd=self.crate_dir,
+                )
+        except Exception:
+            return ""
+
+    def reset_to_commit(self, commit_hash: str) -> bool:
+        """回退 crate 目录到指定的 commit"""
+        try:
+            # 由于 transpile() 开始时已切换到 crate 目录，此处无需再次切换
+            # 检查是否是 git 仓库
+            result = subprocess.run(
+                ["git", "rev-parse", "--git-dir"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                # 不是 git 仓库，无法回退
+                return False
+
+            # 执行硬重置
+            result = subprocess.run(
+                ["git", "reset", "--hard", commit_hash],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                # 清理未跟踪的文件
+                subprocess.run(
+                    ["git", "clean", "-fd"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                return True
+            return False
+        except Exception:
+            return False

jarvis/jarvis_c2rust/transpiler_mod_utils.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from jarvis.jarvis_utils.output import PrettyOutput
+
+
+def ensure_top_level_pub_mod(crate_dir: Path, mod_name: str) -> None:
+    """
+    在 src/lib.rs 中确保存在 `pub mod <mod_name>;`
+    - 如已存在 `pub mod`，不做改动
+    - 如存在 `mod <mod_name>;`，升级为 `pub mod <mod_name>;`
+    - 如都不存在，则在文件末尾追加一行 `pub mod <mod_name>;`
+    - 最小改动，不覆盖其他内容
+    """
+    try:
+        if not mod_name or mod_name in ("lib", "main", "mod"):
+            return
+        lib_rs = (crate_dir / "src" / "lib.rs").resolve()
+        lib_rs.parent.mkdir(parents=True, exist_ok=True)
+        if not lib_rs.exists():
+            try:
+                lib_rs.write_text(
+                    "// Auto-generated by c2rust transpiler\n", encoding="utf-8"
+                )
+                PrettyOutput.auto_print(
+                    f"✅ [c2rust-transpiler][mod] 已创建 src/lib.rs: {lib_rs}"
+                )
+            except Exception:
+                return
+        txt = lib_rs.read_text(encoding="utf-8", errors="replace")
+        pub_pat = re.compile(rf"(?m)^\s*pub\s+mod\s+{re.escape(mod_name)}\s*;\s*$")
+        mod_pat = re.compile(rf"(?m)^\s*mod\s+{re.escape(mod_name)}\s*;\s*$")
+        if pub_pat.search(txt):
+            return
+        if mod_pat.search(txt):
+            # 升级为 pub mod（保留原缩进）
+            def _repl(m):
+                line = m.group(0)
+                match = re.match(r"^(\s*)", line)
+                ws = match.group(1) if match is not None else ""
+                return f"{ws}pub mod {mod_name};"
+
+            new_txt = mod_pat.sub(_repl, txt, count=1)
+        else:
+            new_txt = txt.rstrip() + f"\npub mod {mod_name};\n"
+        lib_rs.write_text(new_txt, encoding="utf-8")
+        PrettyOutput.auto_print(
+            f"✅ [c2rust-transpiler][mod] updated src/lib.rs: ensured pub mod {mod_name}"
+        )
+    except Exception:
+        # 保持稳健，失败不阻塞主流程
+        pass
+
+
+def ensure_mod_rs_decl(dir_path: Path, child_mod: str) -> None:
+    """
+    在 dir_path/mod.rs 中确保存在 `pub mod <child_mod>;`
+    - 如存在 `mod <child_mod>;` 则升级为 `pub mod <child_mod>;`
+    - 如均不存在则在文件末尾追加 `pub mod <child_mod>;`
+    - 最小改动，不覆盖其他内容
+    """
+    try:
+        if not child_mod or child_mod in ("lib", "main", "mod"):
+            return
+        mod_rs = (dir_path / "mod.rs").resolve()
+        mod_rs.parent.mkdir(parents=True, exist_ok=True)
+        if not mod_rs.exists():
+            try:
+                mod_rs.write_text(
+                    "// Auto-generated by c2rust transpiler\n", encoding="utf-8"
+                )
+                PrettyOutput.auto_print(f"✅ [c2rust-transpiler][mod] 已创建 {mod_rs}")
+            except Exception:
+                return
+        txt = mod_rs.read_text(encoding="utf-8", errors="replace")
+        pub_pat = re.compile(rf"(?m)^\s*pub\s+mod\s+{re.escape(child_mod)}\s*;\s*$")
+        mod_pat = re.compile(rf"(?m)^\s*mod\s+{re.escape(child_mod)}\s*;\s*$")
+        if pub_pat.search(txt):
+            return
+        if mod_pat.search(txt):
+            # 升级为 pub mod（保留原缩进）
+            def _repl(m):
+                line = m.group(0)
+                match = re.match(r"^(\s*)", line)
+                ws = match.group(1) if match is not None else ""
+                return f"{ws}pub mod {child_mod};"
+
+            new_txt = mod_pat.sub(_repl, txt, count=1)
+        else:
+            new_txt = txt.rstrip() + f"\npub mod {child_mod};\n"
+        mod_rs.write_text(new_txt, encoding="utf-8")
+        PrettyOutput.auto_print(
+            f"✅ [c2rust-transpiler][mod] updated {mod_rs}: ensured pub mod {child_mod}"
+        )
+    except Exception:
+        pass
+
+
+def ensure_mod_chain_for_module(crate_dir: Path, module: str) -> None:
+    """
+    根据目标模块文件，补齐从该文件所在目录向上的 mod.rs 声明链：
+    - 对于 src/foo/bar.rs：在 src/foo/mod.rs 确保 `pub mod bar;`
+      并在上层 src/mod.rs（不修改）改为在 src/lib.rs 确保 `pub mod foo;`
+    - 对于 src/foo/bar/mod.rs：在 src/foo/mod.rs 确保 `pub mod bar;`
+    - 对于多级目录，逐级在上层 mod.rs 确保对子目录的 `pub mod <child>;`
+    """
+    try:
+        mp = Path(module)
+        base = mp
+        if not mp.is_absolute():
+            base = (crate_dir / module).resolve()
+        crate_root = crate_dir.resolve()
+        # 必须在 crate/src 下
+        rel = base.relative_to(crate_root)
+        rel_s = str(rel).replace("\\", "/")
+        if not rel_s.startswith("src/"):
+            return
+        # 计算起始目录与首个子模块名
+        inside = rel_s[len("src/") :].strip("/")
+        if not inside:
+            return
+        parts = [p for p in inside.split("/") if p]  # 过滤空字符串
+        if parts[-1].endswith(".rs"):
+            if parts[-1] in ("lib.rs", "main.rs"):
+                return
+            child = parts[-1][:-3]  # 去掉 .rs
+            # 过滤掉 "mod" 关键字
+            if child == "mod":
+                return
+            if len(parts) > 1:
+                start_dir = crate_root / "src" / "/".join(parts[:-1])
+            else:
+                start_dir = crate_root / "src"
+            # 确保 start_dir 在 crate/src 下
+            try:
+                start_dir_rel = start_dir.relative_to(crate_root)
+                if not str(start_dir_rel).replace("\\", "/").startswith("src/"):
+                    return
+            except ValueError:
+                return
+            # 在当前目录的 mod.rs 确保 pub mod <child>
+            if start_dir.name != "src":
+                ensure_mod_rs_decl(start_dir, child)
+            # 向上逐级确保父目录对当前目录的 pub mod 声明
+            cur_dir = start_dir
+        else:
+            # 末尾为目录（mod.rs 情况）：确保父目录对该目录 pub mod
+            if parts:
+                cur_dir = crate_root / "src" / "/".join(parts)
+                # 确保 cur_dir 在 crate/src 下
+                try:
+                    cur_dir_rel = cur_dir.relative_to(crate_root)
+                    if not str(cur_dir_rel).replace("\\", "/").startswith("src/"):
+                        return
+                except ValueError:
+                    return
+            else:
+                return
+        # 逐级向上到 src 根（不修改 src/mod.rs，顶层由 lib.rs 公开）
+        while True:
+            parent = cur_dir.parent
+            if not parent.exists():
+                break
+            # 确保不超过 crate 根目录
+            try:
+                parent.relative_to(crate_root)
+            except ValueError:
+                # parent 不在 crate_root 下，停止向上遍历
+                break
+            if parent.name == "src":
+                # 顶层由 ensure_top_level_pub_mod 负责
+                break
+            # 在 parent/mod.rs 确保 pub mod <cur_dir.name>
+            if cur_dir.name == "mod":
+                cur_dir = parent
+                continue
+            try:
+                parent_rel = parent.relative_to(crate_root)
+                if str(parent_rel).replace("\\", "/").startswith("src/"):
+                    ensure_mod_rs_decl(parent, cur_dir.name)
+            except (ValueError, Exception):
+                # parent 不在 crate/src 下，跳过
+                break
+            cur_dir = parent
+    except Exception:
+        pass
+
+
+def module_file_to_crate_path(crate_dir: Path, module: str) -> str:
+    """
+    将模块文件路径转换为 crate 路径前缀：
+    - src/lib.rs -> crate
+    - src/foo/mod.rs -> crate::foo
+    - src/foo/bar.rs -> crate::foo::bar
+    支持绝对路径：若 module 为绝对路径且位于 crate 根目录下，会自动转换为相对路径再解析；
+    其它（无法解析为 crate/src 下的路径）统一返回 'crate'
+    """
+    mod = str(module).strip()
+    # 若传入绝对路径且在 crate_dir 下，转换为相对路径以便后续按 src/ 前缀解析
+    try:
+        mp = Path(mod)
+        if mp.is_absolute():
+            try:
+                rel = mp.resolve().relative_to(crate_dir.resolve())
+                mod = str(rel).replace("\\", "/")
+            except Exception:
+                # 绝对路径不在 crate_dir 下，保持原样
+                pass
+    except Exception:
+        pass
+    # 规范化 ./ 前缀
+    if mod.startswith("./"):
+        mod = mod[2:]
+    # 仅处理位于 src/ 下的模块文件
+    if not mod.startswith("src/"):
+        return "crate"
+    p = mod[len("src/") :]
+    if p.endswith("mod.rs"):
+        p = p[: -len("mod.rs")]
+    elif p.endswith(".rs"):
+        p = p[: -len(".rs")]
+    p = p.strip("/")
+    return "crate" if not p else "crate::" + p.replace("/", "::")