guanlan-src/scripts/check_portability.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
r"""跨平台/相对路径 门禁 (2026-09-11 用户令) —— 换电脑、换盘、Windows↔Linux 之前先跑它。

## 三条硬规则 (ERROR = 必须修)

1. **不许出现机器相关绝对路径**: `/Users/…`、`/Volumes/…`、`/home/<某人>/…`、`C:\…`/`D:\…`/`F:\…`。
   部署到另一台电脑/另一个盘时它们必然失配 —— 这类 bug 是**静默**的 (某块页面取不到数, 不报错)。
2. **不许出现 cwd 相对路径字面量**: `Path('outputs/…')`、`open('data/…')` 这类。
   相对路径必须相对**安装根**, 由 `src/paths.py` 解析 (`P.store()` / `P.rel()`); 相对 cwd 会随调用位置漂移。
3. **不许用 `os.sep` 拼库存字符串**: 写进产物/清单/页面的要用 POSIX 形式 (`P.rel()`);
   `os.sep` 只允许出现在"给人看"的显示函数里。

## 其余是 WARN (不阻塞, 但列出来慢慢收敛)

4. 运行期仍写死 `ROOT / 'outputs/<场名>/…'` → 建议改 `src/paths.py` 的对应函数;
5. 交付侧离线工具 (`scripts/guanlan_cloud_*` 等) 里的同类写法。

## 例外必须**具名**登记

`ALLOW` 里每一项都要写清"为什么可以例外"; 行内特例用注释 `# portability-allow: 原因`。

用法:
    python scripts/check_portability.py            # 全量扫描 (默认扫运行期 + 交付侧)
    python scripts/check_portability.py --runtime  # 只扫运行期 (交付门禁用这个)
"""
from __future__ import annotations

import argparse
import pathlib
import re
import sys

ROOT = pathlib.Path(__file__).resolve().parents[1]

# 运行期代码 (服务、门禁、启动器、安装器、配置)
RUNTIME = ['guanlan.py', 'install.ps1', 'install.sh']
RUNTIME_GLOBS = ['src/**/*.py', 'scripts/*.py']
# 交付侧 (离线工具; 不进服务路径, 但仍应相对、无机器路径)
DELIVERY_GLOBS = ['scripts/sim_hub/*.py']

# 机器相关绝对路径 (盘符形式要求前面是空白/引号/括号 —— 否则 'explanation:\n' 这种转义会被误判成 "n:\")
RE_ABS = re.compile(r"""(/Users/[A-Za-z0-9_.\-]+|/Volumes/[A-Za-z0-9_\- ]+|/home/[a-z][A-Za-z0-9_.\-]*|(?<=[\s'"(\[=])[A-Za-z]:[\\/](?![\\/]))""")
# cwd 相对路径字面量 (相对当前工作目录 —— 必须改成经 paths 解析)
RE_CWD = re.compile(r"""(?:open|Path|pathlib\.Path)\(\s*['"](outputs|data|release|configs|src|scripts|reference|resources|logs|run|wheels|vendor)/""")
# os.sep 出现在"拼字符串"里 (显示函数除外)
RE_OSSEP = re.compile(r"""\+\s*os\.sep""")

ALLOW = {
    'src/sop/farm_paths.py': '它本身就是"win 盘符 → POSIX 盘"的映射表 (自带用例), 路径即测试数据',
    'src/sop/validate_pair.py': '其它场站 (华电/肥城) 的配置样例值, 非本场运行期路径',
    'scripts/build_oem_lexicon.py': 'OEM 资料盘路径样例 (离线词库构建), 非运行期',
    'scripts/ingest_ops_2025.py': '注释/文档里保留历史 mac 路径; 代码已改为 env + 安装目录相对默认',
    'src/windscada/data_tpl_en.py': '英文映射表的**键**是页面显示形 (<安装目录>\\data\\raw\\…), 不是路径用法',
    'src/windscada/deid_public.py': '文档字符串举例说明"产物里带着源文件路径"这一问题本身',
    'src/windscada/maint/framework.py': '注释说明判据来源 (厂商培训分册), 非路径用法',
    'src/sop/discriminators.py': '证据文本里引用复跑脚本位置 (留痕), 非路径用法',
    'src/sop/vib_confidence.py': '证据文本 (与 discriminators 同源)',
    'src/ontology/retrieval.py': '文档字符串说明索引落盘位置',
    'src/ontology/seed_rudong29.py': '文档字符串说明产物位置',
    'src/windscada/ui/snapshot.py': '对外快照的**归一化改写规则** (outputs/rudong → outputs/<site>), 相对模式',
    'src/windscada/fast_agent.py': '注释里的实测记录出处',
    'src/paths.py': '本模块的文档字符串在讲这条约定本身',
    'scripts/check_portability.py': '本门禁自己 (规则里必须写出这些模式)',
}
DELIVERY_ALLOW = {
    'scripts/sim_hub/': '开发期仿真合页生成器 (mac 检出路径), 不进交付/运行路径',
    'outputs/rudong/sop/': '历史装配脚本随包留档 (含 mac 死路径), 非运行期; 已在文档标注',
}


def scan(globs, extra_files=()):
    hits = []
    files = []
    for g in globs:
        files += sorted(ROOT.glob(g))
    files += [ROOT / f for f in extra_files if (ROOT / f).exists()]
    for f in files:
        rel = f.relative_to(ROOT).as_posix()
        if rel in ALLOW or any(rel.startswith(k) for k in DELIVERY_ALLOW):
            continue
        try:
            lines = f.read_text(encoding='utf-8').splitlines()
        except Exception:
            continue
        for i, line in enumerate(lines, 1):
            if 'portability-allow' in line or line.lstrip().startswith('#'):
                continue                      # 行内已具名登记 / 纯注释行 (说明性文字不算路径用法)
            for kind, rx in (('机器绝对路径', RE_ABS), ('cwd 相对路径', RE_CWD), ('os.sep 拼串', RE_OSSEP)):
                m = rx.search(line)
                if m:
                    hits.append((kind, rel, i, m.group(0)[:60], line.strip()[:90]))
    return hits


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument('--runtime', action='store_true', help='只扫运行期 (交付门禁)')
    a = ap.parse_args()

    print(f'根目录: {ROOT}')
    print(f'扫描: {"运行期" if a.runtime else "运行期 + 交付侧"}\n')
    errs = scan(RUNTIME_GLOBS, RUNTIME)
    if not a.runtime:
        errs += scan(DELIVERY_GLOBS)

    if not errs:
        print('  ✔ 无机器相关绝对路径、无 cwd 相对路径、未用 os.sep 拼库存字符串')
    else:
        for kind, rel, i, found, line in errs:
            print(f'  [ERROR] {kind:12s} {rel}:{i}  ← {found}')
            print(f'          {line}')
    print(f'\n例外登记 (ALLOW, 共 {len(ALLOW)} 项 + {len(DELIVERY_ALLOW)} 类): 见本文件注释, 每项都写了理由')
    if errs:
        print(f'\n结论: {len(errs)} 处 ERROR —— 换机部署前必须清零')
        return 1
    print('\n结论: 通过 ✔ (路径可移植: 只有相对路径 + 经 src/paths.py 解析)')
    return 0


if __name__ == '__main__':
    sys.exit(main())