#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""写回缓存空闲 flush（vol_idle_sync）的主机侧纯逻辑单元测试运行器（纯标准库）。

做什么：
    用本机 MSVC 编译 test/host/vol_idle_sync/vol_idle_sync_test.c（它以 #include
    纳入**生产源文件** App/fs/vol_idle_sync.c），在 PC 上离线跑就绪门控 / 节流边界 /
    卷忙跳过 / 失败边沿 latch / 成对放锁 / tick 回绕，失败即非 0 退出。
    零硬件、零烧录、毫秒级。

    工具链探测 / INCLUDE-LIB 拼接 / 编译运行 / 退出码判定全部委托给通用 harness
    `test/host/common/unit_test_harness.py`（本文件只做声明）。

为什么要主机侧单测（而不是只用台架）：
    本模块是「掉电窗口兜底网」——掉电与脏页驻留窗在台架上都不可按需复现；卷忙 /
    ioctl 失败 / 32 位 tick 回绕这些分支在真机上构造成本极高。门控、节流、latch
    全是纯状态逻辑，主机侧一次钉死。

用法（仓库根目录）：
    python test/host/vol_idle_sync/run_unit_test.py

退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

设计依据：App/fs/vol_idle_sync.h 文件头（含「无掉电检测硬件」边界声明）；
创建日期：2026-10-25
"""
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(HERE)))
# harness 位于 test/host/common/
sys.path.insert(0, os.path.join(ROOT, "test", "host", "common"))

from unit_test_harness import TestBuild, run_host_unit_test  # noqa: E402

# 顺序敏感：stub 目录必须**先于**生产目录，才能覆盖 test_config.h / cmsis_os(_2).h /
# FreeRTOS.h / task.h / dbg_log.h（真实头会拖入整套 FreeRTOS/CMSIS/HAL）。
# ff.h / diskio.h / vol_lock.h / sys_events.h 用**真实头**（接口契约与就绪位数值
# 原汁，同 lftpd_io / nand_port 先例；本模块经真实 sys_events.h 拿就绪位定义）。
BUILD = TestBuild(
    name="Volume Idle Sync Tests",
    src=os.path.join(HERE, "vol_idle_sync_test.c"),
    include_dirs=[
        os.path.join(HERE, "stub"),
        os.path.join(ROOT, "App", "fs"),
        os.path.join(ROOT, "App", "app"),
        os.path.join(ROOT, "Lib", "FatFs"),
        HERE,
    ],
    summary_marker="=== Volume Idle Sync Tests:",
)

if __name__ == "__main__":
    sys.exit(run_host_unit_test(BUILD))