from __future__ import annotations
import ast
import cProfile
import functools
import os
import pstats
import re
import sys
import time
from dataclasses import dataclass

from engine.schema import FlameNode, FunctionNode
from engine.harness import _build_user_globals, _load_code, _restore_argv, _scrub_argv_for_user_code, load_source


@dataclass
class StructureResult:
    functions: list
    flame: FlameNode


# ──────────────────────────────────────────────────────────────────────────────
# 内部测试代码识别 + 量化噪声过滤
# ──────────────────────────────────────────────────────────────────────────────
#
# 用户原话：「软件内部的测试部分默认百分百过滤掉,不在统计范围内容。完全不显示。」
# —— 所以测试代码 + tottime=0 的帧默认不进 result.json / functions[] / flame。
#
# 这是 v5 才加的过滤。在 App 入口(filterAnalysis)也有一份,这里再加一份是为了
# 「不打开 UI 也想看干净数据」的场景:用户拿 result.json 跑自己的聚合脚本时,
# 拿到的就是过滤后的数据,而不是 774 帧 + 90% 是噪声。
#
# 跟 App 层契约一致:只匹配 CONTEXT(文件路径 / 模块路径) + 引擎内部硬编码白名单,
# 完全不看函数名 —— TS 端 isInternalTest 的同样设计原则,误伤 = bug。

import re as _re_noise

# 文件名是 test_*.py / *_test.py —— 任意位置都算测试代码（pytest 文件命名约定）
_INTERNAL_TEST_FILE_RE = _re_noise.compile(r'[\\/](?:test_[^\\/]+|[^\\/]+_test)\.py$')
# 在 tests/ / test/ / __tests__/ **直接下面**的文件 —— pytest 目录约定。
# 收紧到要求「tests/ 后面紧接一个文件名,不能再有 / 子目录」:
#   * tests/foo.py              → 算 (foo.py 直接在 tests/ 下)
#   * tests/fixtures/foo.py     → 不算 (fixtures 是子目录,foo.py 不直接挂在 tests/ 下)
# 之前用 `[\\/](tests?|__tests__)[\\/]` 任何含 `/tests/` 的路径都中招,把 fixtures 这类
# 测试数据夹具也当成测试代码误伤 —— 用户脚本只要住在带 tests/ 子目录的路径下,
# 函数表直接被过滤成 0 行。
_INTERNAL_TEST_DIR_RE = _re_noise.compile(r'[\\/](tests?|__tests__)[\\/][^\\/]+$')
_INTERNAL_TEST_MODULE_RE = _re_noise.compile(r'^(tests?|__tests__)([._]|$)')
_INTERNAL_NAMES: frozenset = frozenset(["_pyrof_calib"])


def _is_internal_test(name: str, file: str, module: str) -> bool:
    """Python 版的 isInternalTest —— 命中即视作「噪声帧」,不进 functions[]。

    设计原则(同 TS 版 utils/origin.ts):
    - 只看语境(文件 / 模块 / 引擎白名单),不看函数名 —— 函数名匹配太容易误伤
      (test_helper() / TestCase.test_login() 都是合法业务函数)
    - 引擎内部硬编码白名单(_pyrof_calib)是兜底防御,任何情况下都不该出现在用户 stats 里
    """
    if name in _INTERNAL_NAMES:
        return True
    # 文件名是 test_*.py / *_test.py —— 任意位置
    if _INTERNAL_TEST_FILE_RE.search(file):
        return True
    # 在 tests/ / test/ / __tests__/ 直接下面的文件（不能是子目录）
    if _INTERNAL_TEST_DIR_RE.search(file):
        return True
    # module 一定非空（_top_module 不会返回空字符串），不用做 truthy 兜底
    if _INTERNAL_TEST_MODULE_RE.match(module):
        return True
    return False


def _extract_user_imports(src: str) -> set:
    """从用户脚本源码里抽出顶层显式 import 的模块名集合。

    只看模块级 Import / ImportFrom —— 函数/类内部的 import 是延迟副作用,不是
    「我需要分析的目标」。返回集合里保留顶级包名(numpy / json / os 等),不展开
    as 后的别名(as np → numpy 也在集合里,别名不进集合)。

    解析失败(syntax error 等)时返回空集合 —— 调用方已经独立做了 compile 预检,
    走到 profile_and_measure 的代码一定是合法 Python,这里只是防御。
    """
    try:
        tree = ast.parse(src)
    except SyntaxError:
        return set()
    modules: set = set()
    for node in tree.body:
        if isinstance(node, ast.Import):
            for alias in node.names:
                # 'import a.b.c' → 'a' 就够了;子包自然跟着顶级包一起保留。
                modules.add(alias.name.split(".")[0])
        elif isinstance(node, ast.ImportFrom):
            # 'from . import x' 的 level > 0 是相对导入,跳过 —— 它们依附于某个
            # 已知包(用户脚本 / 已导入的第三方),不展开根模块。
            # node.level 是 int(0/1/2/...),0 是 falsy,这里只需 if node.level。
            if node.level:
                continue
            if node.module:
                modules.add(node.module.split(".")[0])
    return modules


def _fid(func):
    file, line, name = func
    return f"{file}:{line}:{name}"


@functools.lru_cache(maxsize=4096)
def _norm(path):
    """规范化路径 —— Windows NTFS 大小写不敏感 + 跨斜杠风格统一。

    包 lru_cache：典型 profile 5000 帧 / 50 unique file path —— 之前每个
    frame 都跑 abspath + normcase,scope=user 的 hot loop 里反复调;
    缓存后只有 50 次真正的 abspath。同一路径跨多次 _top_module /
    _classify_origin / _make_frame_filter 复用同一结果。
    maxsize=4096 覆盖任何真实 profile 看不到的 unique file 数。
    """
    try:
        return os.path.normcase(os.path.abspath(path))
    except Exception:
        return path


def _make_frame_filter(script_path, scope="user"):
    """构造帧过滤器。

    scope=user（默认）：只保留用户脚本里的函数 — 历史上一直如此。
    scope=all：保留所有非 cProfile 内部帧（包含标准库和第三方包）— 让耗时
    可以"进入到 import 的包里"，否则 `pandas.read_csv` 永远是一个黑盒，
    看到 3s 也不知道是序列化慢、IO 慢还是解析慢。

    `~` 帧的过滤有讲究 —— 之前一刀切 file == '~' 都丢,实际上：
    - cProfile 用 `~` 作为**所有 C 函数帧**的文件名（time.sleep / numpy C 核
      / json 加速 / re 等），丢这些直接打瞎 scope=all
    - 真正的 cProfile 内部帧靠 name 区分:`'_lsprof.Profiler'` /
      `'Profiler' / '<method 'disable' of '_lsprof.Profiler' objects>'` 之类
    只剔除 name 含 '_lsprof.Profiler' 的帧,其它 C 函数保留 —— schema 里
    origin='builtin' / module='<built-in>' 也终于能命中真实 builtin 帧。
    """
    target = _norm(script_path)

    def _is_kept(func):
        file, _, name = func
        # cProfile 内部帧 —— file='~',name 含 "_lsprof.Profiler" 子串
        # （实际形态：'Profiler' / '_lsprof.Profiler' /
        # "<method 'disable' of '_lsprof.Profiler' objects>"）
        if file == "~" and ("_lsprof.Profiler" in name or name == "Profiler"):
            return False
        if scope == "all":
            return True
        # 虚拟路径（<frozen ...> / <built-in ...> / <string> 等）不可能是用户脚本,
        # 直接 False 省一次 _norm —— _norm("<frozen ...>") 会跑 abspath 拼成
        # "<cwd>/<frozen ...>" 然后 normcase,跟用户脚本路径比必然不等,但白做一次
        # 文件系统查询。~ 在 cProfile 内部已上面短路,这里同等处理。
        if file.startswith("<") or file == "~":
            return False
        return _norm(file) == target

    return _is_kept


def _top_module(file_path: str, user_script_path: str, user_script_norm: str | None = None) -> str:
    """把 cProfile 给的 file 路径归类成「顶层模块名」，给 UI 做分类用。

    输出样例：
    - 用户脚本（==user_script_path） → "<user>"
    - "/usr/lib/python3.11/json/decoder.py" → "json"
    - "C:\\Python39\\Lib\\json\\decoder.py" → "json"
    - "C:\\Python39\\Lib\\functools.py" → "functools"  ← 顶层 .py 必须剥掉后缀
    - "/.../site-packages/numpy/core/array.py" → "numpy"
    - "<frozen importlib._bootstrap>" → "<frozen>"
    - "<built-in method xxx>" → "<built-in>"
    - 其他 → 取倒数第二个目录段作 fallback（基本不会走到）

    user_script_norm: 调用方预计算的 `_norm(user_script_path)` —— 同一进程内
    同一脚本会查几百次,提到外面省 abspath；不传则本函数内现算（保持单点调用方兼容）。
    """
    if file_path == "~":
        # C 函数（time.sleep / numpy 加速 / json C decoder 等）：
        # file==~ + name 是 "<built-in method ...>"
        # 之前丢光后这里 dead code,现在 _make_frame_filter 不再丢 C 帧,
        # module 字段需要给出有意义分类 —— 用 "<built-in>" 跟 origin 字段对齐。
        return "<built-in>"
    if _norm(file_path) == (user_script_norm if user_script_norm is not None else _norm(user_script_path)):
        return "<user>"
    # frozen / built-in / <string> 这种「虚拟」文件：整段作为标签
    if file_path.startswith("<"):
        if file_path.startswith("<frozen"):
            return "<frozen>"
        if file_path.startswith("<built-in"):
            return "<built-in>"
        return file_path
    # 路径规范化：跨平台 + 跨斜杠
    norm = file_path.replace("\\", "/")
    parts = [p for p in norm.split("/") if p]
    # site-packages / dist-packages：标记之后的第一个目录段就是包名
    for marker in ("site-packages", "dist-packages"):
        if marker in parts:
            idx = parts.index(marker) + 1
            if idx < len(parts):
                return parts[idx]
    # 标准库（Windows 安装布局）：C:\Python39\Lib\<pkg>\... 或顶层 .py
    # `Lib\\functools.py` → "functools"（不是 "functools.py"），用 _strip_py 兜底
    if "Lib" in parts:
        idx = parts.index("Lib") + 1
        if idx < len(parts):
            return _strip_py(parts[idx])
    # 标准库（Linux / macOS 安装布局）：/usr/lib/python3.X/<pkg>\...
    # 之前用 p.startswith("python") + p[6:7].isdigit() 太松散 —— "python3-extra"
    # 这种目录会被误识别；收紧到严格的 `pythonX(.Y)?` 形式。
    for i, p in enumerate(parts):
        if re.fullmatch(r"python\d+(\.\d+)?", p):
            if i + 1 < len(parts):
                return _strip_py(parts[i + 1])
    # 兜底：取倒数第二个目录段（例如 ".../myproj/src/utils/helper.py" → "utils"）
    if len(parts) >= 2:
        return _strip_py(parts[-2])
    return _strip_py(file_path)


def _strip_py(name: str) -> str:
    """顶层 .py 文件剥掉扩展名 —— `functools.py` → `functools`。

    只剥 `.py` 后缀；其它段（'__init__'、'site-packages' 等）原样保留。
    非顶层文件不会被这个函数触碰 —— _top_module 把它包在 `parts[idx]` 之外的位置时
    返回的就是 `parts[-2]` 这种目录段，永远不带 `.py`；只有顶层 `<name>.py` 才走到这里。"""
    if name.endswith(".py"):
        return name[:-3]
    return name


# sys.stdlib_module_names 是 3.10+ 才有的；3.9 及之前要走路径兜底。
# 提前 frozen 一次 —— 同一进程内不变，反复判 in 走 frozenset 是 O(1)。
_STDLIB_MODULES: frozenset | None
try:
    _STDLIB_MODULES = frozenset(getattr(sys, "stdlib_module_names", set()))
except Exception:
    _STDLIB_MODULES = None


# 路径兜底"是不是真的在 stdlib 根下"用 sysconfig —— sysconfig.get_paths() 是
# Python 官方给出的 stdlib 根解析工具,远比手算 <prefix> + 'Lib' / '<prefix>/lib/pythonX.Y'
# 靠谱（venv / embed / framework 几种安装布局都覆盖）。
#
# M5 fix:之前只看路径里是否含 "/Lib/" 或 "/lib/pythonX.Y/" —— 用户项目
# 里有 `myproject/Lib/foo.py` 这种就会被错认成 stdlib。现在锚到 sysconfig
# 算出的真 stdlib 根上:不是真正的 Python 安装根下面的,一律不算 stdlib。
#
# 一次性算好缓存,frozen 之后 hot path 上 O(1) prefix 比对。
def _stdlib_roots() -> tuple:
    roots: list = []
    try:
        import sysconfig
        stdlib_path = sysconfig.get_paths().get("stdlib", "")
        if stdlib_path:
            roots.append(_norm(stdlib_path))
    except Exception:
        pass
    # 兜底再放 sys.prefix/Lib —— 有些 embedded 安装 sysconfig 拿不到
    fallback = os.path.join(sys.prefix, "Lib")
    roots.append(_norm(fallback))
    return tuple(roots)


_STDLIB_ROOTS_NORM: tuple = _stdlib_roots()


def _is_under_real_stdlib(file_path: str) -> bool:
    """判断 file_path 是否在真正的 Python stdlib 根下。

    只走"路径兜底"分支 (3.9 / 未知模块名 兜底),已有 _STDLIB_MODULES 命中时不调用本函数,无谓开销。
    """
    fp = _norm(file_path)
    for root in _STDLIB_ROOTS_NORM:
        if fp == root or fp.startswith(root + os.sep):
            return True
    return False


def _classify_origin(file_path: str, user_script_path: str, module_name: str, user_script_norm: str | None = None) -> str:
    """给一帧函数归类来源（v3 新增字段 origin）。

    返回值（即 JSON 里的字面量，UI 端按这个 group）:
      "user"        用户脚本（路径与 user_script_path 一致）
      "frozen"      <frozen importlib._bootstrap> 等冻结帧
      "builtin"     <built-in method exec> 等 C 实现的 builtin
      "stdlib"      Python 标准库（按 sys.stdlib_module_names 校准；3.10+
                    才生效，老版本退化为路径启发式）
      "third_party" site-packages / dist-packages 下的第三方包
      "other"       兜底 —— 例如 <string>、未匹配任何已知布局的奇怪路径

    顺序很关键：
      1) user / frozen / builtin 用文件路径前缀直接判，O(1)
      2) stdlib 先查 sys.stdlib_module_names（权威），命中即返回
      3) 路径里出现 site-packages / dist-packages → third_party
      4) 路径里出现 /Lib/ 或 /lib/pythonX.Y/ → stdlib（启发式兜底）
      5) 其它 → other

    user_script_norm: 调用方预计算的 `_norm(user_script_path)` —— 同 _top_module,
    热路径上几百次调用,提到外面省一次 abspath。
    """
    # C 扩展函数（time.sleep / numpy C 核 / json C 加速器 等）cProfile 把 file 标成 "~"。
    # _top_module 已经把 module 字段定为 "<built-in>"（与 origin 字段对齐的契约见那里），
    # 这里也要走 builtin 分支,否则 origin = "other" 与 module = "<built-in>" 错位,UI
    # 端按 origin 分组时这条帧会落到别的桶里 —— 之前一直漏到这里。
    if file_path == "~":
        return "builtin"
    # 虚拟文件路径（<frozen ...> / <built-in ...> / <string> 等）优先短路 —— 之前
    # 先 _norm 再判 < 是浪费 abspath,而且 "<..." 这种路径跟用户脚本路径无论如何
    # 都不可能相等,白调一次 norm。顺序调成「<... 优先」后 hot path 上少 100+
    # 次 _norm 调用（典型 scope=all 的 profile 里 <frozen>/<built-in> 帧占大头）。
    if file_path.startswith("<"):
        if file_path.startswith("<frozen"):
            return "frozen"
        if file_path.startswith("<built-in"):
            return "builtin"
        return "other"
    if _norm(file_path) == (user_script_norm if user_script_norm is not None else _norm(user_script_path)):
        return "user"

    # sys.stdlib_module_names 校准：module_name 已由 _top_module 算好，
    # 直接问「这个包名是不是 stdlib」。
    if _STDLIB_MODULES is not None and module_name in _STDLIB_MODULES:
        return "stdlib"

    # 路径兜底（兼容 3.9 + 处理 _STDLIB_MODULES 偶发漏判的边角包）
    norm = file_path.replace("\\", "/")
    if "site-packages" in norm or "dist-packages" in norm:
        return "third_party"
    # 必须锚到真正的 stdlib 根下 —— 之前只看 "Lib/" 子串会把用户项目里的
    # /home/x/myproject/Lib/foo.py 误认成 stdlib。
    # 锚点用 sysconfig.get_paths()['stdlib'] (官方权威,覆盖 venv/framework/embed),
    # 拿不到时回退到 sys.prefix + "Lib"。
    if _is_under_real_stdlib(file_path):
        return "stdlib"

    return "other"


def profile_and_measure(
    script_path: str,
    scope: str = "user",
    hide_internal: bool = True,
    code=None,
    src: str | None = None,
) -> tuple:
    """v4 单跑架构：一次 exec(code) under cProfile，同时拿到函数归因和 instrumented wall-time。

    替代 v3 的两阶段执行（先裸跑测 wall_time 再 cProfile 跑）：
    - 用户脚本只 exec 一次 → plot / print / file-write 等副作用只发生一次
    - 返回的 instrumented_wall 含 cProfile 自身开销（典型 1.5~3x 膨胀）
    - 调用方需要配合 calibrate_cprofile_overhead 折算：wall_time = instrumented / ratio

    scope: "user"（默认）只归因用户脚本里的函数；"all" 包含所有非 cProfile 内部帧
    （标准库 + 第三方包 + 用户代码），让用户能下钻到 import 的包里。

    hide_internal (v5 新增,默认 True):过滤掉测试代码 + tottime=0 的量化噪声帧。
    - 测试代码：tests/ / test_*.py / _pyrof_calib 等(见 _is_internal_test)
    - tottime=0:scope=all 时 typing / inspect / functools 等内部展开常被 cProfile 量化精度截到 0,
      这些不是优化目标,默认剔除能让 result.json 干净到「只剩真正在跑的代码」
    - 设为 False 时不过滤 —— 给想排查调用栈 / 自定义聚合的用户留一条后路

    code / src:可选的预读 code object 和源码文本。runner.py 已经在做 syntax
    precheck 时 read + compile 过一份,这里直接复用 —— 避免重复 IO(原来
    profile_and_measure 自己又 read 两次 + AST parse 一次)。这两个参数
    给 None 时回退到「自己 load_source + compile」,供老调用方 / 单测继续工作。

    NOTE: 不在 cProfile exec 周围禁用 GC —— cProfile 应该看到真实的执行环境
    （包括 GC 暂停），折算后的 wall-time 才能反映真实耗时。calibration 那两次
    tight-loop 跑各跑各的 GC 策略（详见 harness.calibrate_cprofile_overhead）。
    """
    # 复用 caller 读好的 code / src —— runner.py 的 syntax precheck 已经 read+compile 过一次,
    # 再读一次等于把同样的字节流从磁盘捞 2 次 + AST parse 一次。None 时退回到旧的「自己读」路径。
    if code is None:
        code = _load_code(script_path)
    if src is None and hide_internal:
        src = load_source(script_path)
    g = _build_user_globals(script_path)
    saved_argv = _scrub_argv_for_user_code(script_path)
    pr = cProfile.Profile()
    pr.enable()
    try:
        t0 = time.perf_counter()
        exec(code, g)
        instrumented = time.perf_counter() - t0
    finally:
        pr.disable()
        _restore_argv(saved_argv)

    stats = pstats.Stats(pr)
    is_kept = _make_frame_filter(script_path, scope)
    # 规范化一次：每个函数帧都会把 file_path 与 script_path 比对；规范化结果
    # 与具体帧无关 —— 提到循环外,几百行的 functions 表能省几百次 abspath 调用。
    script_norm = _norm(script_path)
    # 解析用户脚本里显式 import 的模块集合。stdlib 内部帧如果来自「用户没
    # 显式 import 的包」(typing/inspect/functools/re/_py_warnings/...),
    # 一律视为 numpy/pandas 这类第三方包触发的「间接调用链」—— 用户无法优化,
    # 默认剔除。结果：scope=all 时 result.json 也只剩用户代码 + 显式导入的
    # 第三方包 + 真正大头的 stdlib 模块(json/os/etc.,用户写了 `import json`
    # 就看 json,否则不看)。
    # 之前无条件 ast.parse 整个 src —— 即便用户脚本 module 全是 "<user>"(scope=user)
    # 根本进不到这条 stdlib 过滤分支,几百行的 fixture 也走一遍 AST。改成只在真正会
    # 消费 user_imports 的组合里算(scope=all + hide_internal=True)。
    if hide_internal and scope == "all":
        user_imports = _extract_user_imports(src)
    else:
        user_imports = set()
    # file → (module, origin) 缓存：同一文件的多个函数帧（numpy 几百帧共享一个 file）
    # 只算一次 module + origin。_top_module 和 _classify_origin 各自又会再调一次
    # _norm(file),加 cache 后这两个调用也都省了 —— 典型 profile 5000 帧 / 50 文件,
    # _top_module 从 5000 次降到 50 次,_classify_origin 同。
    file_info_cache: dict[str, tuple] = {}
    def _classify_file(file_path: str) -> tuple:
        cached = file_info_cache.get(file_path)
        if cached is not None:
            return cached
        module = _top_module(file_path, script_path, script_norm)
        origin = _classify_origin(file_path, script_path, module, script_norm)
        cached = (module, origin)
        file_info_cache[file_path] = cached
        return cached

    # ── v6 「用户直接调用」过滤 ──
    # 用户原话:「只要代码的本身和import 调用的耗时统计,其他的不需要」/「目前好像
    # 仍然统计到内部测试的代码了,不合理」—— 之前虽然过滤掉了 stdlib 内部噪声帧
    # (typing/inspect/functools 等),但 487 帧里仍有:
    #   - numpy 内部 250+ 帧(np.array 调用的 _core.fromnumeric 等)→ 间接
    #   - <frozen> importlib._bootstrap 90 帧 → 间接导入机制
    #   - <built-in> C 函数 131 帧(len / numpy C 核 / _warnings / dict.keys 等)
    #   - _distutils_hack 2 帧、mkl 7 帧 → setup machinery,非用户调用
    # 用户其实只要:
    #   1) 自己写的函数(模块名 == "<user>")
    #   2) 自己「直接调用」的 import 入口(np.array / np.mean / json.dumps 等)
    # 实现:cProfile 的 callers 字段自带调用方信息。「某帧的 caller 含用户脚本
    # 里的帧」=「用户直接调用」。再加 origin 闸门:仅 third_party / 用户显式 import
    # 的 stdlib 才算「import 调用」—— builtin / frozen / other / 没显式 import 的
    # stdlib 一律不保留,即使技术上确实被用户代码调用到(len / print / numpy C 核)。
    # ──────────────────────────────────────────────────────────────────────────────
    functions = []
    if hide_internal:
        # Pass 1:收集用户帧 + 把通过基础过滤的帧的 (module, origin) 缓存下来。
        # 注意:这里不再做 tt <= 0 过滤 —— 用户代码 + import 入口里常有纯 C 分派的
        # 薄包装(np.random.rand / numpy.__getattr__ 等),cumtime 远大于 0 但 tottime
        # 恰好压在 cProfile 量化精度地板上,被滤掉就把"用户调用了哪个 API"这条信息丢了。
        # 用户代码 + import 入口自然就少,即便有 tt=0 也只是干净 user-function 占位,
        # 全保留就行。
        user_frames: set = set()
        func_info_cache: dict = {}
        for func, (cc, nc, tt, ct, callers) in stats.stats.items():
            if not is_kept(func):
                continue
            file = func[0]
            module_name, origin = _classify_file(file)
            if _is_internal_test(func[2], file, module_name):
                continue
            func_info_cache[func] = (module_name, origin)
            if module_name == "<user>":
                user_frames.add(func)

        # Pass 2:边判断「是不是 import_callee」边构造 FunctionNode(原版是分两个独立
        # pass 跑 import_callees 再跑 functions,合一遍能省掉一次 stats.stats 全量迭代。
        # import_callees 设单独 set 也不必要 —— 这里用 include 标志位本地决定,跳出本
        # 帧判断后立即 append / continue。
        for func, (cc, nc, tt, ct, callers) in stats.stats.items():
            info = func_info_cache.get(func)
            if info is None:
                continue  # pass 1 已过滤
            module_name, origin = info
            if func in user_frames:
                include = True
            else:
                include = False
                for caller in callers:
                    if caller in user_frames:
                        if origin == "third_party" or (
                            origin == "stdlib" and module_name in user_imports
                        ):
                            # 用户代码确实调到了这个 import 入口 —— 但还要看 ct:
                            # 低于 cProfile 量化精度(1µs)的「被调到的帧」(典型:
                            # numpy._mean_dispatcher 这种注册期被触发的辅助分发器,
                            # cProfile 把调用方记成 <module> 但实际不干活)是噪声。
                            # 用户代码写的空函数另算(user_frames 不受这条约束)。
                            include = ct >= 1e-6
                        break
            if not include:
                continue
            file = func[0]
            functions.append(
                FunctionNode(
                    id=_fid(func),
                    file=file,
                    line=func[1],
                    name=func[2],
                    cumtime=ct,
                    tottime=tt,
                    ncalls=nc,
                    percallTot=(tt / nc if nc else 0.0),
                    module=module_name,
                    origin=origin,
                )
            )
    else:
        # hide_internal=False:用户要的是全量原始数据 —— 不做 import_callee / 测试代码 / 零耗时过滤,
        # 直接把 is_kept 通过的帧全收下来。
        for func, (cc, nc, tt, ct, callers) in stats.stats.items():
            if not is_kept(func):
                continue
            file = func[0]
            module_name, origin = _classify_file(file)
            functions.append(
                FunctionNode(
                    id=_fid(func),
                    file=file,
                    line=func[1],
                    name=func[2],
                    cumtime=ct,
                    tottime=tt,
                    ncalls=nc,
                    percallTot=(tt / nc if nc else 0.0),
                    module=module_name,
                    origin=origin,
                )
            )

    functions.sort(key=lambda f: f.tottime, reverse=True)
    total = sum(f.tottime for f in functions)
    flame = _build_flame(functions, total)
    return StructureResult(functions=functions, flame=flame), instrumented


def profile_structure(
    script_path: str,
    scope: str = "user",
    hide_internal: bool = True,
) -> StructureResult:
    """Backward-compat shim：v3 时期暴露的「只拿归因、不读 wall-time」接口。

    v4 起实际工作在 profile_and_measure 里完成；保留这个包装是为了不破坏直接
    import engine.structure.profile_structure 的测试 / 旧调用方。语义跟 v3 一样：
    只跑一次 cProfile exec、返回 functions + flame。
    """
    result, _ = profile_and_measure(script_path, scope=scope, hide_internal=hide_internal)
    return result


def _build_flame(functions: list, total: float) -> FlameNode:
    """构造火焰图根节点。

    火焰图第一层有两个 layout 选项：
    - 单模块（scope=user 或刚好只 import 一个包）：保持扁平（函数列表），
      和 v2 之前完全一致，向后兼容。
    - 多模块（scope=all 且命中 ≥2 个不同的顶层模块）：按 module 聚合——
      用户问「时间花在了哪个包」时第一眼就能看到；点模块 tile 下钻看内部函数。
    """
    # 单模块时维持扁平 —— 同名兄弟不会被 module 节点挤占，截断阈值不变
    modules = {f.module for f in functions}
    if len(modules) <= 1:
        return FlameNode(
            name="root",
            value=total,
            children=[FlameNode(name=f.name, value=f.tottime) for f in functions],
        )

    # 多模块：按 module 聚合；模块自身 value 是该模块下所有函数 tottime 之和
    by_module: dict = {}
    for f in functions:
        node = by_module.get(f.module)
        if node is None:
            node = FlameNode(name=f.module, value=0.0, children=[])
            by_module[f.module] = node
        node.value += f.tottime
        node.children.append(FlameNode(name=f.name, value=f.tottime))
    # 模块按总 tottime 降序，让最贵的包排最左（icicle 布局的视觉约定）
    sorted_modules = sorted(by_module.values(), key=lambda m: m.value, reverse=True)
    return FlameNode(name="root", value=total, children=sorted_modules)