GVSDS/ViperC
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(tpv): R11 注释与 docstring 英文化并压缩到 2 行内

Browse Source 
按 wiki/新规范：注释只讲作用、不掺杂历史原因、避免超长、尽可能英文（含三引号 __doc__）。全文 79 个 .vp：# 注释 16269 行（中文 13808）与 docstring（中文 1381 处）全部改英文；超 2 行的注释块（2093）与 docstring（397）全部压到 2 行。运行时可见文本未动（fatal_error/VLogger 的中文报错文案、stdio.printf 的横幅格式串）。校验：屏蔽注释与三引号后逐行比对各文件代码骨架，0 漂移。验证：自举重建 153.48s 通过（跨模块内联完成）；TPV 顺序回归 77/77 全通过。
This commit is contained in:
TermiNexus committed 2026-10-05 13:38:22 +08:00
1 parent a2874a14e6
commit 0f4aeeceff
79 files changed
+10090 -20352
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

App/lib/Stub/StubMerger/StubMergerBuild.vp
+69 -123
View File
@@ -25,16 +25,10 @@ import lib.Stub.StubMerger.StubMergerTopo as StubMergerTopo
import lib.Stub.StubMerger.StubMergerIR as StubMergerIR
import lib.Stub.StubMerger as StubMerger
# ============================================================
# _IsAppModule - 模块名是否为 App 源文件（store 条目 incdir 为空）
#
# 依赖图 BFS 中识别 App 中间节点：App 文件不入 reachable_set（Phase B
# 已编译其 .obj），但其 includes 依赖必须继续展开。App 条目由 App 扫描
# 阶段用 AppendToSha1MapStore 登记（incdir 留空）；includes 条目用
# AddIncludeToSha1MapStore 登记（incdir 非空）。
# _IsAppModule - whether a module name is an App source file (store entry with empty incdir)
# ============================================================
def _IsAppModule(mod_name: str) -> int:
"""mod_name 是否为 App 源文件（store 命中且 incdir 为空）"""
"""Return whether mod_name is an App source file (store hit with empty incdir)."""
if mod_name is None: return 0
if StubMerger._sha1_store_arr is None or StubMerger._sha1_store_mod is None: return 0
for i in range(StubMerger._sha1_store_count):
@@ -44,15 +38,8 @@ def _IsAppModule(mod_name: str) -> int:
if StubMerger._sha1_store_incdir[iidx] == '\0': return 1
return 0
return 0
# ============================================================
# _AppendDepsToWorklist - 追加空格分隔模块名到 worklist（逐模块去重）
#
# worklist 是 BFS 队列（空格分隔）；deps_str 中的模块若已在 worklist/processed 中则不重复追加，
# 否则 BFS 沿共享依赖（builtins/stdlib 等）反复累积会致 REACH_WORKLIST_BUF 溢出。
#
# Args: worklist 队列缓冲（原地修改）；wl_len 当前长度（值）；deps_str 要追加的模块名（空格分隔）；processed 已处理集合（空格分隔，查重）
# Returns: 追加后的新长度（>=0）；溢出/参数错误返回 -1（调用方 fail-fast）
# ============================================================
# _AppendDepsToWorklist - append space-separated module names to the worklist (dedup against worklist/processed).
# Returns the new length (>=0), or -1 on overflow/arg error (caller fail-fast).
def _AppendDepsToWorklist(worklist: bytes, wl_len: sizet, deps_str: str, processed: str) -> int:
if worklist is None or deps_str is None: return -1
cur_len: sizet = wl_len
@@ -90,20 +77,10 @@ def _AppendDepsToWorklist(worklist: bytes, wl_len: sizet, deps_str: str, process
stdlib.free(dmod)
return int(cur_len)
# ============================================================
# _BuildReachableSha1Set - 构建可达 SHA1 集合（依赖图按需扫描；未引用的 includes 从不读取）
#
# App 优先模型：从 app_deps 出发 BFS，对每个模块名按文件系统解析到 includes 文件（ResolveModuleToPath），只对可达 includes
# 读文件 + 算 SHA1 + 解析 import，补充依赖图并登记 Sha1Store/deps 存储器/写 deps.txt；Phase 1b / Phase B+ 只处理可达集合中的文件。
#
# 算法（工作列表 BFS）：1) App 扫描（app_deps 为空时）递归扫 source_dir，declare_only=2 解析 import（相对导入 resolve 成绝对模块名）
# + 容器注入（_list/_dict）→ worklist 初始队列，App 文件登记 store（incdir 空）+ 填 deps；2) builtins 预加入队列；3) BFS 直到闭包。
#
# Args: mb 内存池；source_dir App 源文件目录（Config.SourceDir）；temp_dir 临时目录（deps.txt 所在位置）；reachable_set 输出参数，可达 SHA1 集合缓冲区（MAX_INCLUDES_SHA1 * 17 字节）；app_deps App 源文件直接依赖模块名（空格分隔），非空则跳过 App 扫描；includes_dirs includes 根目录（空格分隔）
# Returns: 可达 SHA1 数量（>0 成功；0 无 includes 依赖；<0 失败）
# ============================================================
# _BuildReachableSha1Set - build the reachable SHA1 set (on-demand dep-graph scan; unreferenced includes are never read).
# BFS from app_deps: resolve each module to an includes file and read+hash+parse only reachable ones; returns count (>0 ok, 0 none, <0 fail).
def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str, reachable_set: str, app_deps: str = None, includes_dirs: str = None) -> int:
"""构建可达 SHA1 集合（依赖图按需扫描，App 优先）"""
"""Build the reachable SHA1 set by on-demand dependency-graph scanning."""
if source_dir is None or temp_dir is None or reachable_set is None: return -1
if includes_dirs is None:
VLogger.error("includes_dirs 缺失，无法按需解析依赖图", "Reachable")
@@ -111,13 +88,13 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
SRC_BUF_SIZE_R: sizet = 1048576
# 工作列表（空格分隔的模块名）
# Worklist (space-separated module names)
worklist: bytes = stdlib.malloc(StubMerger.REACH_WORKLIST_BUF)
if worklist is None: return -1
worklist[0] = '\0'
wl_len: sizet = 0
# 1. App 扫描（app_deps 非空时跳过，直接用调用方提供的初始队列）
# 1. App scan (skipped when app_deps is non-empty; use the caller-provided initial queue directly)
if app_deps is None or app_deps[0] == '\0':
VLogger.info("App 扫描：解析 source_dir 的 import 依赖", "Reachable")
scan_res_r: rawptr[IncludesScanner.ScanResult] = IncludesScanner.scan_includes(mb, source_dir)
@@ -126,7 +103,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
for e_i_r in range(scan_res_r.Count):
e_r: rawptr[IncludesScanner.FileEntry] = rawptr[IncludesScanner.FileEntry](uint64(scan_res_r.Entries) + uint64(e_i_r) * es_r)
if e_r is None or e_r.Path is None: continue
# 文件级 mark：parse 完立即回收 AST（App 全量 parse 驻留会 OOM）
# File-level mark: reclaim the AST right after parsing (keeping all App ASTs resident would OOM)
app_mark: sizet = mb.mark()
sbuf: bytes = Utils.read_file_to_buf(e_r.Path, SRC_BUF_SIZE_R)
if sbuf is None:
@@ -142,8 +119,8 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
tr: rawptr[HandlesTranslator.Translator] = HandlesTranslator.Translator()
if tr is not None:
tr._declare_only = 2
# 源文件包名：用 RelPath（相对 source_dir，支持子目录），
# 保证 from .xxx import 相对导入解析正确
# Source package name from RelPath (relative to source_dir, supports subdirs),
# so relative imports like `from .xxx` resolve correctly
tr.CurrentPackage = GenApi.compute_package_from_relpath(mb, e_r.RelPath)
GenApi.set_current_file_type(e_r.Path)
GenApi.set_current_file_imports(e_r.Path)
@@ -153,16 +130,14 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
GenApi.reset_visible_structs(mb, 0)
ret_a: int = tr.translate(tree)
if ret_a == 0:
# 容器使用检测：App 文件用 list/dict（裸名注解/构造）
# 时注入 _list/_dict 依赖（对齐原实现）
# Container use detection: inject _list/_dict deps when an App file uses list/dict (bare annotation/ctor)
tr._inject_auto_container_visibility(mb, tree)
# App 文件登记 store（incdir 空）+ 填 deps：
# BFS 展开 App 中间节点的 includes 依赖时经
# LookupIncludesDeps(app_sha1) 读取
# Register the App file in the store (empty incdir) and fill deps; read by
# LookupIncludesDeps(app_sha1) when BFS expands its includes deps
if e_r.Sha1 is not None:
StubMergerStore.AppendToSha1MapStore(e_r.Sha1, e_r.RelPath)
StubMergerStore.PopulateIncludesDeps(e_r.Sha1, tr._imported_modules)
# 收集 deps 到初始队列（逐模块去重）
# Collect deps into the initial queue (dedup per module)
if tr._imported_modules is not None:
im_len_a: sizet = string.strlen(tr._imported_modules)
im_pos_a: sizet = 0
@@ -189,13 +164,13 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
wl_len += 1
worklist[wl_len] = '\0'
stdlib.free(im_buf_a)
# 释放 Translator 资源
# Release Translator resources
if tr._global_names is not None: stdlib.free(tr._global_names)
if tr._nonlocal_names is not None: stdlib.free(tr._nonlocal_names)
stdlib.free(sbuf)
mb.reset_to(app_mark)
else:
# app_deps 已提供（Phase2 场景）：直接作为初始队列
# app_deps already provided (Phase2): use it directly as the initial queue
ad_len: sizet = string.strlen(app_deps)
if ad_len > 0 and ad_len < StubMerger.REACH_WORKLIST_BUF:
string.strcpy(worklist, app_deps)
@@ -205,25 +180,20 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(worklist)
return -1
# 去掉末尾多余空格
# Trim the trailing extra space
if wl_len > 0 and worklist[wl_len - 1] == ' ':
worklist[wl_len - 1] = '\0'
wl_len -= 1
# 2. 预加入基础模块（builtins）
# builtins（内置函数模块）始终纳入编译链。_list/_dict 仅在显式
# list/dict 注解/构造时经 _inject_auto_container_visibility 注入
# （list 字面量赋给 t.CArray 走数组初始化，不触发 _list）。
# processed 尚未分配，此处传 None 仅按 worklist 查重。
# 2. Pre-add base modules (builtins): builtins is always compiled in; _list/_dict are injected only for
# explicit list/dict annotations/ctors (list literals to t.CArray are array init and do not trigger _list).
wl_len = _AppendDepsToWorklist(worklist, wl_len, "builtins", None)
if wl_len < 0:
stdlib.free(worklist)
return -1
# 2b. --traceback: force the traceback runtime module into the reachable set
# (TPC: used_includes.add('traceback')). Its Install() symbol and the
# @llvm.global_ctors ctor are only produced by compiling this module, so a
# missing file is fail-fast rather than a silent "feature off" build.
# 2b. --traceback: force the traceback runtime module into the reachable set (TPC: used_includes.add('traceback')).
# Its Install() symbol and the @llvm.global_ctors ctor come only from compiling this module, so a missing file is fail-fast.
if BuildPipeline._traceback_mode != 0:
tb_abs: t.CPtr = stdlib.malloc(8)
tb_rel: t.CPtr = stdlib.malloc(8)
@@ -250,7 +220,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
return -1
wl_len = sizet(tb_wl)
# 3. 工作列表 BFS：模块名 → 文件系统解析 → 读+hash+parse import
# 3. Worklist BFS: module name -> filesystem resolution -> read+hash+parse imports
processed: bytes = stdlib.malloc(StubMerger.REACH_WORKLIST_BUF)
if processed is None:
stdlib.free(worklist)
@@ -268,7 +238,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
while wl_pos_slot[0] < wl_len:
pos: sizet = wl_pos_slot[0]
# 提取一个模块名（到空格或末尾）
# Extract one module name (up to a space or the end)
name_start: sizet = pos
while pos < wl_len and worklist[pos] != ' ': pos += 1
name_len: sizet = pos - name_start
@@ -276,17 +246,17 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
wl_pos_slot[0] = pos
if name_len == 0: continue
# 复制模块名
# Copy the module name
mod_buf: bytes = stdlib.malloc(name_len + 1)
if mod_buf is None: continue
string.strncpy(mod_buf, worklist + name_start, name_len)
mod_buf[name_len] = '\0'
# 已处理去重
# Dedup against already processed
if GenApi.is_module_imported(processed, mod_buf) != 0:
stdlib.free(mod_buf)
continue
# 加入 processed
# Add to processed
if proc_len + name_len + 1 < StubMerger.REACH_WORKLIST_BUF:
string.strcpy(processed + proc_len, mod_buf)
proc_len = proc_len + name_len
@@ -298,8 +268,8 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(mod_buf)
continue
# App 中间节点：只展开其 includes 依赖，不入 reachable_set
# （Phase B 已编译 App 的 .obj，加入会导致 Phase B+ 重复编译 → 重复符号）
# App intermediate node: only expand its includes deps, do not add to reachable_set
# (Phase B already compiled its .obj; adding it would recompile and duplicate symbols)
if _IsAppModule(mod_buf) != 0:
app_sha1: str = StubMergerStore.LookupSha1ByModName(mod_buf)
if app_sha1 is not None:
@@ -316,7 +286,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(mod_buf)
continue
# includes：按文件系统按需解析（未引用的 includes 根本不触碰）
# includes: resolve on demand via the filesystem (unreferenced includes are never touched)
out_abs: t.CPtr = stdlib.malloc(8)
out_rel: t.CPtr = stdlib.malloc(8)
out_inc: t.CPtr = stdlib.malloc(8)
@@ -326,12 +296,8 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
if out_inc is not None: stdlib.free(out_inc)
stdlib.free(mod_buf)
continue
# 输出槽防御性初始化（成功路径必全写；未找到/未命中时仅 free 槽本身）
# 槽联合必须用 (sizet*)：t.CPtr* 会被折叠成 t.CPtr，
# [0] 变成 1 字节访问 → 指针被截断（0x2e 崩溃根因）。CSizeT 成员为
# 8 字节：写侧 sizet(ptr)，读侧必须用 rawptr(slot[0]) 做 u64→
# 指针转换；str(slot[0]) 是内置"数字转字符串"（snprintf 到栈缓冲并返回
# 该栈地址），拿到的是十进制文本+栈指针 → free 即 bad-free。
# Defensive init of the output slots (the success path always writes all). The slot union must use (sizet*):
# t.CPtr* collapses to t.CPtr and [0] becomes a 1-byte access, truncating the pointer (0x2e crash root cause).
abs_slot: sizet* = (sizet*)(out_abs)
rel_slot: sizet* = (sizet*)(out_rel)
inc_slot: sizet* = (sizet*)(out_inc)
@@ -340,7 +306,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
inc_slot[0] = 0
rcode: int = IncludesScanner.ResolveModuleToPath(includes_dirs, mod_buf, out_abs, out_rel, out_inc)
if rcode != 0:
# 内建模块（t/c/builtins 等内部库）或未找到：静默跳过
# Builtin module (t/c/builtins internal libs) or not found: silently skip
stdlib.free(out_abs)
stdlib.free(out_rel)
stdlib.free(out_inc)
@@ -350,7 +316,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
rel_path: str = rawptr(rel_slot[0])
inc_dir: str = rawptr(inc_slot[0])
# 读文件 + 计算 SHA1（CRLF→LF，与 IncludesScanner 一致）
# Read the file and compute SHA1 (CRLF->LF, matching IncludesScanner)
sha1_r2: str = IncludesScanner.compute_file_sha1(mb, abs_path)
if sha1_r2 is None:
stdlib.free(abs_path)
@@ -362,7 +328,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(mod_buf)
continue
# 已在可达集合（前序 BFS 已 parse 过）：只展开其 deps
# Already in the reachable set (parsed by an earlier BFS): only expand its deps
if StubMergerCollect._is_in_sha1_set(sha1_r2, reachable_set, reachable_count) != 0:
deps_ex: str = StubMergerStore.LookupIncludesDeps(sha1_r2)
if deps_ex is not None:
@@ -389,12 +355,12 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(mod_buf)
continue
# 加入可达集合 + 登记 Sha1Store（仅可达 includes）
# Add to the reachable set and register in Sha1Store (reachable includes only)
reachable_count = StubMergerIR._AddSha1ToSet(reachable_set, reachable_count, sha1_r2)
StubMergerStore.AddIncludeToSha1MapStore(sha1_r2, rel_path, inc_dir, mod_buf)
# 文件级 mark：parse import 后立即回收 AST（可达 includes 全量
# parse 的 AST 若驻留 → 主池 OOM）
# File-level mark: reclaim the AST right after parsing imports (keeping all reachable includes
# ASTs resident would OOM the main pool)
scan_mark_r: sizet = mb.mark()
sbuf_r: bytes = Utils.read_file_to_buf(abs_path, SRC_BUF_SIZE_R)
if sbuf_r is None:
@@ -414,9 +380,8 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
tokens_r: ast.Token* = ast.tokenize(lx_r)
tree_r = ast.parse_tokens(mb, tokens_r)
if tree_r is None:
# parse_tokens keeps the error detail (line/col/message) in the global
# channel only, so print the unified parse traceback before the one-line
# log; without it a reachable-includes syntax error is undiagnosable.
# parse_tokens keeps the error detail (line/col/message) only in the global channel, so print the unified
# parse traceback before the one-line log; without it a reachable-includes syntax error is undiagnosable.
GenApi.dump_parse_traceback(abs_path)
VLogger.error(f"可达 includes 解析失败: {abs_path}", "Reachable")
stdlib.free(abs_path)
@@ -446,7 +411,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
continue
tr_r2.ModuleSha1 = sha1_r2
tr_r2._declare_only = 2
# 包名：相对 includes 根目录的 RelPath（支持 from .xxx import 相对导入）
# Package name: RelPath relative to the includes root (supports relative imports like `from .xxx`)
tr_r2.CurrentPackage = GenApi.compute_package_from_relpath(mb, rel_path)
GenApi.set_current_file_type(abs_path)
GenApi.set_current_file_imports(abs_path)
@@ -472,11 +437,11 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(wl_pos)
mb.reset_to(scan_mark_r)
return -1
# 容器按需注入（includes 用 list/dict 泛型时追加 _list/_dict 到依赖，
# 对齐 App 层 _inject_auto_container_visibility；内联破环防 _list/_dict 环）
# Inject containers on demand (append _list/_dict when includes use list/dict generics);
# inlined to break the _list/_dict cycle
tr_r2._inject_auto_container_visibility(mb, tree_r)
# 填内存依赖 + 写 deps.txt（供依赖图展开与 Phase B 按需加载）
# Fill in-memory deps and write deps.txt (for dep-graph expansion and on-demand Phase B loading)
deps_r2: str = tr_r2._imported_modules
StubMergerStore.PopulateIncludesDeps(sha1_r2, deps_r2)
if deps_r2 is not None:
@@ -489,7 +454,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
if dl_w > 0: df_w.write(deps_r2, dl_w)
df_w.close()
stdlib.free(deps_path_w)
# 追加依赖到 worklist（去重防溢出）
# Append deps to the worklist (dedup to prevent overflow)
ret_w: int = _AppendDepsToWorklist(worklist, wl_len, deps_r2, processed)
if ret_w < 0:
stdlib.free(abs_path)
@@ -508,7 +473,7 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
wl_len = sizet(ret_w)
else: VLogger.debug(f"无依赖: {rel_path}", "Reachable")
# 释放 Translator 的 C malloc 资源 + 回收本文件 AST
# Free the Translator's C malloc resources and reclaim this file's AST
if tr_r2._global_names is not None: stdlib.free(tr_r2._global_names)
if tr_r2._nonlocal_names is not None: stdlib.free(tr_r2._nonlocal_names)
stdlib.free(sbuf_r)
@@ -527,16 +492,10 @@ def _BuildReachableSha1Set(mb: memhub.MemBuddy*, source_dir: str, temp_dir: str,
stdlib.free(wl_pos)
return reachable_count
# ============================================================
# LoadFullIR - 读 {temp_dir}/{sha1}.full.ll 到 out_buf（④-c：合并期改用在线 FULL 产物）
#
# 契约：返回写入长度（sizet；0=失败），out_buf 以 '\0' 结尾。
# full.ll 由翻译点在模型在线时 dump_ir(OUTPUT_FULL) 产出 —— 自足的单模块 IR
# （类型定义 + external 声明 + 定义 + DI 一次齐全，类型定义天然在声明之前），
# 无需再把 stub + 依赖 stub/text 文本合并。
# ============================================================
# LoadFullIR - read {temp_dir}/{sha1}.full.ll into out_buf (④-c: merge phase uses the online FULL artifact).
# Contract: returns bytes written (sizet; 0=failure); out_buf is '\0'-terminated. full.ll is a self-contained single-module IR.
def LoadFullIR(temp_dir: str, sha1: str, out_buf: bytes, out_size: sizet) -> sizet:
"""读取 {sha1}.full.ll 到 out_buf；返回长度（0=失败）"""
"""Read {sha1}.full.ll into out_buf; returns the length (0 on failure)."""
if temp_dir is None or sha1 is None or out_buf is None or out_size == 0: return 0
td_len: sizet = string.strlen(temp_dir)
p: str = StubMergerCollect._sliced_path(temp_dir, td_len, sha1, "full.ll")
@@ -555,77 +514,64 @@ def LoadFullIR(temp_dir: str, sha1: str, out_buf: bytes, out_size: sizet) -> siz
out_buf[rd] = '\0'
return sizet(rd)
# ============================================================
# LoadDepVpiIntoModule - 加载依赖模块的 .vpi 文件，注入 declare 到当前模块
#
# 遍历 imported_modules（空格分隔的模块名）：LookupSha1ByModName 取 SHA1 → _sliced_path 构造 .vpi 路径 → VpiReader.ParseVpiIntoModule 解析并注入 declare。
#
# 必须在 _translate_module_level 中、Import 处理完成后、translate_children 之前调用，确保跨模块函数调用时 declare 已存在。
#
# Args: pool 内存池；mod 当前 LLVM 模块；imported_modules 已导入模块名字符串（空格分隔）；from_imports from-import 映射字符串（"name:module name:module" 格式）；temp_dir temp 目录路径；trans 翻译器对象
# Returns: 成功加载的 .vpi 文件数
# ============================================================
# LoadDepVpiIntoModule - load dependency modules' .vpi files and inject their declares into the current module.
# Call after Import handling and before translate_children; returns the number of successfully loaded .vpi files.
def LoadDepVpiIntoModule(pool: memhub.MemBuddy*, mod: mlirlite.LLVMModule*, imported_modules: str, from_imports: str, temp_dir: str, trans: rawptr[HandlesTranslator.Translator]) -> int:
"""加载依赖模块的 .vpi 文件，将函数声明注入到当前模块"""
"""Load dependency modules' .vpi files and inject their declares into the current module."""
if pool is None or mod is None or temp_dir is None or trans is None: return 0
if imported_modules is None: return 0
# 每个模块的 stub 注入前重置 typedef 递归注册的防环标记：
# CTypedef 表每文件隔离（translate 前 clear），visited 若跨模块残留会
# 导致 stdint 等 typedef 只注册一次、后续模块注入再次解析时表里为空
# → 参数类型退化 i8_ptr_ty → 整数实参误报 CastError（FuncTest 根因）。
# Reset the typedef recursion guard before injecting each module's stub: the CTypedef table is
# per-file, so stale visited state registers stdint typedefs only once and degrades param types (FuncTest root cause).
VpiReader.ResetVpiTypedefVisited()
# 按需注入防重入表同周期重置：注入目标 mod 每模块不同，跨模块沿用会让
# 后续模块命中缓存、拿不到本模块需要的 declare（包重导出按需注入用）。
# Reset the on-demand injection reentry table too: the target mod differs per module, so carrying it
# over would cache-hit and miss the declares this module needs.
VpiReader.ResetVpiInjectVisited()
td_len: sizet = string.strlen(temp_dir)
total_len: sizet = string.strlen(imported_modules)
success_count: int = 0
# 遍历 imported_modules 中的每个模块名（空格分隔）
# Iterate each module name in imported_modules (space-separated)
ci: sizet = 0
while ci < total_len:
# 跳过前导空格
# Skip leading spaces
while ci < total_len and imported_modules[ci] == ' ': ci += 1
if ci >= total_len: break
# 提取模块名（到下一个空格或字符串末尾）
# Extract the module name (up to the next space or end of string)
word_start: sizet = ci
while ci < total_len and imported_modules[ci] != ' ': ci += 1
word_len: sizet = ci - word_start
if word_len == 0: continue
# 复制模块名到临时缓冲区并 null 终止
# Copy the module name into a temp buffer and null-terminate it
mod_nm_buf: str = stdlib.malloc(word_len + 1)
if mod_nm_buf is None: continue
string.strncpy(mod_nm_buf, imported_modules + word_start, word_len)
mod_nm_buf[word_len] = '\0'
# 用 LookupSha1ByModName 查找模块的 SHA1
# Look up the module's SHA1 via LookupSha1ByModName
sha1_val: str = StubMergerStore.LookupSha1ByModName(mod_nm_buf)
# 改名别名（import X as Y，如 HT→lib.core.Handles.HandlesTranslator）：
# 精确/包名回退均失败时从 from_imports 查别名映射再查 SHA1，
# 否则该类模块的 vpi/stub 不注入 → 跨模块符号解析失败
# Import alias (import X as Y, e.g. HT->lib.core.Handles.HandlesTranslator): when exact/package
# lookups fail, resolve the alias via from_imports; otherwise its vpi/stub is not injected and cross-module symbols fail.
if sha1_val is None and from_imports is not None: sha1_val = StubMergerStore.LookupSha1ByAlias(from_imports, mod_nm_buf)
# 如果精确查找失败，尝试包名回退（如 "ast" → "ast.__init__"）
# LookupSha1ByModName 内部已处理包名回退，此处无需重复
# Exact lookup failed: package fallback (e.g. "ast" -> "ast.__init__") is already handled inside LookupSha1ByModName
if sha1_val is not None:
# 构造 .vpi 文件路径
# Build the .vpi file path
vpi_path: str = StubMergerCollect._sliced_path(temp_dir, td_len, sha1_val, "vpi")
if vpi_path is not None:
# 检查 .vpi 文件是否存在（可读）
# Check that the .vpi file exists (is readable)
vf: rawptr[fileio.File] = fileio.File(vpi_path, fileio.MODE.R)
if not vf.closed:
vf.close()
# 调用 VpiReader 解析 .vpi 并注入 declare
# （错误上下文帧由调用方 HandlesTranslator 维护）
# Parse the .vpi via VpiReader and inject declares (the error context frame is kept by the caller HandlesTranslator)
ret: int = VpiReader.ParseVpiIntoModule(pool, mod, vpi_path, trans)
if ret == 1: success_count += 1
stdlib.free(vpi_path)
# sha1_val 指向内部存储，无需 free
# sha1_val points into internal storage, no free needed
stdlib.free(mod_nm_buf)