figma-ios-listview-recognition

Figma ListView 识别与生成

⛔ 硬规则（红线，违反即视为交付失败）

这一节优先级高于下文所有"识别条件"。任何与本节冲突的判定，以本节为准。

红线 1：audit.json.list_containers / index.json.by_role.list_container 全部必须 UICollectionView

两处来源等价：

• {data_dir}/audit.json 的 list_containers[]（推荐，自带 must_use/forbidden 提示）
• {data_dir}/index.json 的 by_role.list_container[]

强制规则：

• 这两处列出的每一个 node_id，在生成代码里必须有对应的 UICollectionView（不是 UIScrollView，不是 UIStackView，不是手摆 UIView）
• 即使该节点的父节点 export.is_export_asset == true，也禁止把父节点整组切图——切图会吃掉列表，列表的语义子节点必须保留为 cell（详见 figma-ios-vector-vs-code 红线规则）
• 即使该节点 children 全是 IMAGE 节点，也仍然是列表 cell——cell 内容是图就用 UIImageView 当 cell 内容，不要把整个列表退化成 N 张 ImageView

自检脚本（生成完代码后必跑）：

data_dir=<data_dir>
out_file=<your_generated.swift>

python3 - <<PY
import json, sys
audit = json.load(open(f"$data_dir/audit.json"))
src_raw = open("$out_file").read()

# 剔除文件顶部连续的"节点树注释块"（常见形态：Figma 代码生成器会在文件开头 dump
# 一整棵树的 `// ├ 341:xxx  INSTANCE  ...`，如果不剔除，每个 node_id 的"第一次出现"
# 其实都在注释里，后续窗口扫描会串到其他节点的代码上造成误判）。
# 规则：从文件起始连续的 `空行` 或 `//` 开头行视为注释块，遇到第一个非注释非空行停止。
lines = src_raw.splitlines(keepends=True)
i = 0
while i < len(lines) and (not lines[i].strip() or lines[i].lstrip().startswith("//")):
    i += 1
src = "".join(lines[i:])
fail = []

# 1) list_containers：必须 UICollectionView（同构列表红线）
for it in audit.get("list_containers", []):
    nid = it["node_id"]
    if nid not in src:
        fail.append(f"❌ list_container {nid} '{it['name']}' 未在代码中出现（可能被父切图吃掉）")
        continue
    window = src.split(nid, 1)[1][:2000]
    if "UICollectionView" not in window and "CollectionView" not in window:
        fail.append(f"❌ list_container {nid} '{it['name']}' 没用 UICollectionView（scroll_axis={it['scroll_axis']}, cell_count={it['cell_count']}）")

# 2) list_keyword_hits（scroll_intent=True）：子节点异构仍要 UIScrollView，禁止降到 UIView
for it in audit.get("list_keyword_hits", []):
    if not it.get("scroll_intent"):
        continue  # 集合语义不检查
    nid = it["node_id"]
    if nid not in src:
        continue  # 节点可能属于 list_containers（已在 1 校验）
    window = src.split(nid, 1)[1][:2000]
    has_scroll = any(k in window for k in ("UICollectionView", "CollectionView", "UIScrollView", "ScrollView"))
    if not has_scroll:
        fail.append(
            f"❌ 滚动语义节点 {nid} '{it['name']}'（matched={it['matched_keyword']!r}）"
            f"没用 UICollectionView 或 UIScrollView，禁止降到 UIView"
        )

# 3) chip_group_hits（红线 2）：父异构 + 子段连续 ≥4 同构 INSTANCE/COMPONENT/FRAME，必 UICollectionView
#    注意：不能简单用 "cell_id 附近出现 UICollectionView" 判断。
#    同一文件里如果有其他 CV（例如 categoryCollectionView），cell_id 的位置会撞到那个 CV
#    导致假阴性。下面用两条判据：
#      (a) 反模式正则：[UIView]/[UIButton]/[UILabel]/[UIImageView] 数组声明后 1500 char 内
#          覆盖了 run 中过半 cell id → 典型的"chip 被做成 view 数组"事故（如 rankChipViews: [UIView]）
#      (b) 距离兜底：每个 cell id 距离任何 UICollectionView/Cell/register 声明 >600 char
#          → 大概率根本没用 UICollectionView 承载
import re
_chip_anti_array = re.compile(
    r"(?:lazy\s+var|var|let)\s+(\w+)\s*:\s*\[UI(?:View|Button|Label|ImageView)\]"
)
_chip_cv_sign = re.compile(
    r"UICollectionView(?:Cell|FlowLayout|DataSource|Delegate)?|register\s*\("
)
_cv_region_starts = [m.start() for m in _chip_cv_sign.finditer(src)]
for it in audit.get("chip_group_hits", []):
    run_ids = it.get("run_node_ids") or []
    present = [nid for nid in run_ids if nid in src]
    if not present:
        fail.append(
            f"❌ chip_group parent={it['parent_id']} '{it['parent_name']}' 的 "
            f"{it['run_length']} 个 cell 全部未在代码中出现（可能被整组切图吃掉）"
        )
        continue

    # 判据 (a)：反模式正则
    caught = False
    for m in _chip_anti_array.finditer(src):
        tail = src[m.end(): m.end()+1500]
        hits = [nid for nid in run_ids if nid in tail]
        if len(hits) >= max(2, len(run_ids)//2):
            fail.append(
                f"❌ chip_group {it['parent_id']} '{it['parent_name']}' 命中反模式 "
                f"`{m.group()}`（覆盖 {len(hits)}/{len(run_ids)} 个 cell）— "
                f"chip 群必须 UICollectionView + cell 承载，不能做成 view 数组"
            )
            caught = True
            break
    if caught:
        continue

    # 判据 (b)：距离兜底
    too_far = False
    for nid in present:
        nid_pos = src.find(nid)
        nearest = min((abs(nid_pos - s) for s in _cv_region_starts), default=10**9)
        if nearest > 600:
            too_far = True
            break
    if too_far:
        fail.append(
            f"❌ chip_group {it['parent_id']} '{it['parent_name']}' "
            f"(run_length={it['run_length']}, layout={it['layout_hint']}) 的 cell "
            f"离任何 UICollectionView 声明都 >600 char，大概率没用 CV 承载 — "
            f"对照 must_use：{it['must_use']}"
        )

if fail:
    print("\n".join(fail))
    sys.exit(1)
print("✅ list_containers / scroll_intent / chip_group_hits 节点都已用滚动容器")

# 注：判据 (b) 的 600 char 阈值是经验值；如真实代码里 cell id 挨着某个无关 CV 声明（偶发的假阴性），
# 请在代码评审中人工确认；大多数情况下此脚本能钉住 rankChipViews 这类事故形态。
PY