@kernel-sig/console 0.1.0

package/backend/app/domain/review.py

@@ -0,0 +1,416 @@
+"""评审状态解析与合并门禁判定。
+
+AtomGit 的 PR 对象**不携带**评审关系，评审状态由标签与机器人评论承载。
+实测已合并 PR 的标签组合为：
+
+    ['openeuler-cla/yes', 'sig/Kernel', 'ci_successful', 'lgtm', 'approved']
+
+门禁链条：CLA → CI → 关联 Issue → LGTM → 可合入。
+
+``approved`` **不在**这条链上：实测 200 个 open PR 中 0 个带该标签，
+而 200 个已合并 PR 中 199 个带 —— 它是合入时补记的标记，不是前置条件。
+
+评审人身份同样不在标签里（PR 上用的是整体 ``lgtm``），
+而在人类的 ``/lgtm`` 评论与机器人的确认回执中。
+
+本模块把标签与评论解析为结构化的评审事件与门禁状态，
+是 SLA 统计、评审人工作量、等待时长等一切评审指标的基础。
+
+纯函数实现，不依赖数据库与网络，便于独立测试与在 worker 中复用。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+
+# ---------------------------------------------------------------------------
+# 标签解析
+# ---------------------------------------------------------------------------
+
+
+class EventType(StrEnum):
+    """评审事件类型。**全平台唯一的一份定义**。
+
+    数据库枚举、解析器与统计逻辑共用此枚举 ——
+    同一概念若在两处各写一份，取值集合必然漂移，
+    表现为"解析出的值写不进数据库"。
+    """
+
+    LGTM = "lgtm"
+    APPROVE = "approve"
+    ACK = "ack"
+    REJECT = "reject"
+    CI_PASS = "ci_pass"
+    CI_FAIL = "ci_fail"
+    CI_RUNNING = "ci_running"
+    CLA_SIGNED = "cla_signed"
+    CLA_DENIED = "cla_denied"
+    CLOSE = "close"
+    REOPEN = "reopen"
+    RETEST = "retest"
+    LABEL_ADDED = "label_added"
+    LABEL_REMOVED = "label_removed"
+
+
+class GateStage(StrEnum):
+    """PR 在评审流程中的阶段。"""
+
+    DRAFT = "draft"
+    CLA_PENDING = "cla_pending"
+    CLA_DENIED = "cla_denied"
+    CI_PENDING = "ci_pending"
+    CI_RUNNING = "ci_running"
+    CI_FAILED = "ci_failed"
+    NEEDS_ISSUE = "needs_issue"
+    REVIEW_PENDING = "review_pending"
+    REJECTED = "rejected"
+    READY_TO_MERGE = "ready_to_merge"
+    MERGED = "merged"
+    CLOSED = "closed"
+
+
+# 标签取值来自对真实仓库的实测统计（300 个 open PR 的标签分布），
+# 而非文档或猜测。注意 ``ci_failed`` 才是实际最常用的 CI 失败标签，
+# 仅处理 ci_must_go_failed / ci_block_force_merge 会把失败的 PR
+# 误判为"CI 未完成"，向维护者展示完全错误的阻塞原因。
+#
+# 顺序要求：具体规则必须排在通用规则之前，否则 lgtm-<user> 会被 lgtm 抢先匹配。
+LABEL_RULES: tuple[tuple[re.Pattern[str], EventType], ...] = (
+    (re.compile(r"^lgtm-(?P<user>.+)$"), EventType.LGTM),
+    (re.compile(r"^lgtm$"), EventType.LGTM),
+    (re.compile(r"^approved$"), EventType.APPROVE),
+    # Acked 是正向评审信号，但并非合并门禁的必需项
+    # （实测已合并 PR 的门禁为 cla + ci_successful + lgtm + approved），
+    # 因此单独记录而不计入 approved 判定。
+    (re.compile(r"^Acked$"), EventType.ACK),
+    (re.compile(r"^NACK$"), EventType.REJECT),
+    (re.compile(r"^openeuler-cla/yes$"), EventType.CLA_SIGNED),
+    (re.compile(r"^openeuler-cla/no$"), EventType.CLA_DENIED),
+    (re.compile(r"^ci_successful$"), EventType.CI_PASS),
+    (re.compile(r"^ci_failed$"), EventType.CI_FAIL),
+    (re.compile(r"^ci_must_go_failed$"), EventType.CI_FAIL),
+    (re.compile(r"^ci_block_force_merge$"), EventType.CI_FAIL),
+    (re.compile(r"^ci_processing$"), EventType.CI_RUNNING),
+    # 同义标签：连字符与下划线两种写法在仓库中并存
+    (re.compile(r"^ci-process$"), EventType.CI_RUNNING),
+)
+
+# 已知但与评审门禁无关的标签。
+# ``needs-issue`` 单独处理（它是门禁条件，不是可忽略的分类标签）。
+_IGNORED_LABEL_PREFIXES = ("sig/", "kind/", "ai-")
+
+# openEuler 硬规则：PR 必须至少关联一个 Issue（CI 机器人会明确提示）
+NEEDS_ISSUE_LABEL = "needs-issue"
+
+
+@dataclass(frozen=True)
+class ParsedEvent:
+    """从标签或评论解析出的一条评审事件。"""
+
+    event_type: EventType
+    actor_login: str
+    occurred_at: datetime
+    source: str  # "label" | "comment"
+    raw: str
+
+    @property
+    def actor(self) -> str:
+        """空 actor 表示"非特定人触发"（如整体 lgtm 标签）。"""
+        return self.actor_login
+
+
+@dataclass
+class MergeGate:
+    """合并门禁状态。
+
+    门禁链条：CLA → CI → 关联 Issue → LGTM → Approved。
+    全部满足才可合入；任一环节被显式否决（CLA 拒绝 / CI 失败 / NACK）
+    都优先于"未完成"展示 —— 维护者需要看到的是"出问题了"，
+    而不是"还在等"。
+    """
+
+    cla_signed: bool = False
+    cla_denied: bool = False
+    ci_passed: bool = False
+    ci_failed: bool = False
+    ci_running: bool = False
+    approved: bool = False
+    rejected: bool = False
+    needs_issue: bool = False
+    lgtm_actors: set[str] = field(default_factory=set)
+    has_plain_lgtm: bool = False
+    is_draft: bool = False
+    is_merged: bool = False
+    is_closed: bool = False
+
+    @property
+    def has_lgtm(self) -> bool:
+        """存在整体 lgtm 标签，或至少一位具名评审人给出 lgtm。"""
+        return self.has_plain_lgtm or bool(self.lgtm_actors)
+
+    @property
+    def ci_blocked(self) -> bool:
+        return self.ci_failed
+
+    @property
+    def ready_to_merge(self) -> bool:
+        """维护者当前即可合入。
+
+        **不要求 approved 标签**。实测数据：200 个 open PR 中 0 个带 approved，
+        而 200 个已合并 PR 中 199 个带 approved —— 说明 approved 是**合入时**
+        由机器人补记的标记，而非合入前需要等待的门禁条件。
+        若把它作为前置条件，"可合入"状态在 open PR 上永不可能出现，
+        维护者最需要的那份待办队列会直接失效。
+        """
+        return (
+            self.cla_signed
+            and not self.cla_denied
+            and self.ci_passed
+            and not self.ci_failed
+            and self.has_lgtm
+            and not self.rejected
+            and not self.needs_issue
+            and not self.is_draft
+        )
+
+    @property
+    def is_approved(self) -> bool:
+        """approved 标签是否已打上（合入前后的标记，非门禁前置条件）。"""
+        return self.approved
+
+    @property
+    def blocking_reasons(self) -> list[str]:
+        """按门禁链条顺序列出尚未满足的条件，供界面直接展示。"""
+        if self.is_merged or self.is_closed:
+            return []
+
+        reasons: list[str] = []
+        if self.is_draft:
+            reasons.append("草稿状态")
+        if self.cla_denied:
+            reasons.append("CLA 未通过")
+        elif not self.cla_signed:
+            reasons.append("CLA 未签署")
+
+        if self.ci_failed:
+            reasons.append("CI 未通过")
+        elif self.ci_running:
+            reasons.append("CI 进行中")
+        elif not self.ci_passed:
+            reasons.append("CI 未完成")
+
+        if self.needs_issue:
+            reasons.append("未关联 Issue")
+        if self.rejected:
+            reasons.append("已被 NACK")
+        if not self.has_lgtm:
+            reasons.append("缺少 LGTM")
+        return reasons
+
+    @property
+    def stage(self) -> GateStage:
+        if self.is_merged:
+            return GateStage.MERGED
+        if self.is_closed:
+            return GateStage.CLOSED
+        if self.is_draft:
+            return GateStage.DRAFT
+        if self.cla_denied:
+            return GateStage.CLA_DENIED
+        if not self.cla_signed:
+            return GateStage.CLA_PENDING
+        if self.ci_failed:
+            return GateStage.CI_FAILED
+        if self.ci_running:
+            return GateStage.CI_RUNNING
+        if not self.ci_passed:
+            return GateStage.CI_PENDING
+        if self.needs_issue:
+            return GateStage.NEEDS_ISSUE
+        if self.rejected:
+            return GateStage.REJECTED
+        if not self.has_lgtm:
+            return GateStage.REVIEW_PENDING
+        return GateStage.READY_TO_MERGE
+
+
+# ---------------------------------------------------------------------------
+# 机器人评论中的指令
+# ---------------------------------------------------------------------------
+
+# openEuler 的 CI 机器人响应这些指令，形如 "/lgtm"、"/approve"
+COMMAND_PATTERN = re.compile(r"^\s*/(?P<cmd>lgtm|approve|close|reopen|retest)\s*$", re.IGNORECASE)
+
+# 机器人账号识别。
+#
+# 仅匹配后缀不够：仓库里实际的机器人叫 devstation-robot、ci-robot1、
+# openeuler-infra-bot —— 前两者以 "robot" 而非 "bot" 结尾，只匹配后缀会漏掉
+# 合计 600 多个 PR 的自动化账号，让评审工作量与作者榜单失去意义。
+#
+# 但也不能放宽到"包含 robot 前缀"：那会把 robotics-team 这类正常名称误判。
+# 因此按分隔符切词，词段须**恰好**是 bot/robot 加可选数字。
+_BOT_SEGMENT_PATTERN = re.compile(r"^(?:bot|robot)\d*$")
+BOT_SUFFIXES = ("-bot", "_bot", "[bot]")
+
+
+def is_bot(login: str | None) -> bool:
+    if not login:
+        return False
+    lowered = login.lower()
+    if lowered.endswith(BOT_SUFFIXES):
+        return True
+    return any(
+        _BOT_SEGMENT_PATTERN.match(segment) for segment in re.split(r"[-_.\s]+", lowered) if segment
+    )
+
+
+def parse_label(name: str, actor_login: str, occurred_at: datetime) -> ParsedEvent | None:
+    """把单个标签解析为评审事件。无法识别时返回 None。"""
+    for pattern, kind in LABEL_RULES:
+        match = pattern.match(name)
+        if not match:
+            continue
+
+        # lgtm-<user> 的 actor 是标签里携带的用户名；
+        # 整体 lgtm 标签没有具体人（actor 记为空）
+        actor = match.groupdict().get("user") or actor_login
+
+        return ParsedEvent(
+            event_type=kind,
+            actor_login=actor or "",
+            occurred_at=occurred_at,
+            source="label",
+            raw=name,
+        )
+    return None
+
+
+def parse_comment_command(body: str, actor_login: str, occurred_at: datetime) -> ParsedEvent | None:
+    """解析评论中的机器人指令。
+
+    openEuler 的 CI 机器人接受 ``/lgtm`` ``/approve`` ``/close`` 等指令，
+    这些是评审动作的直接记录，比标签更精确地反映"谁在何时做了什么"。
+    """
+    for line in body.splitlines():
+        match = COMMAND_PATTERN.match(line)
+        if not match:
+            continue
+        cmd = match.group("cmd").lower()
+        mapping = {
+            "lgtm": EventType.LGTM,
+            "approve": EventType.APPROVE,
+            "close": EventType.CLOSE,
+            "reopen": EventType.REOPEN,
+            "retest": EventType.RETEST,
+        }
+        return ParsedEvent(
+            event_type=mapping[cmd],
+            actor_login=actor_login,
+            occurred_at=occurred_at,
+            source="comment",
+            raw=f"/{cmd}",
+        )
+    return None
+
+
+def parse_events(
+    labels: Iterable[tuple[str, datetime]],
+    comments: Iterable[tuple[str, str, datetime]],
+) -> list[ParsedEvent]:
+    """把标签与评论解析为按时间排序的事件列表。
+
+    Args:
+        labels: ``(标签名, 时间)`` 序列。标签本身不携带时间，
+            调用方应传入可获得的最近时间（如 PR 更新时间）。
+        comments: ``(正文, 作者, 时间)`` 序列。
+    """
+    events: list[ParsedEvent] = []
+
+    for name, occurred_at in labels:
+        event = parse_label(name, actor_login="", occurred_at=occurred_at)
+        if event is not None:
+            events.append(event)
+
+    for body, author, occurred_at in comments:
+        if is_bot(author):
+            # 机器人会复述用户指令（如 "LGTM" 回执），不能当作人类评审动作，
+            # 否则评审工作量会被系统性高估
+            continue
+        event = parse_comment_command(body, actor_login=author, occurred_at=occurred_at)
+        if event is not None:
+            events.append(event)
+
+    events.sort(key=lambda e: e.occurred_at)
+    return events
+
+
+def derive_gate(
+    label_names: Sequence[str],
+    *,
+    is_draft: bool = False,
+    state: str = "open",
+) -> MergeGate:
+    """从标签列表推导当前门禁状态。
+
+    这是"当前状态"的唯一判定入口；历史事件由 :func:`parse_events` 提供。
+    """
+    gate = MergeGate(
+        is_draft=is_draft,
+        is_merged=state == "merged",
+        is_closed=state == "closed",
+    )
+
+    for name in label_names:
+        if name == NEEDS_ISSUE_LABEL:
+            gate.needs_issue = True
+            continue
+
+        for pattern, kind in LABEL_RULES:
+            match = pattern.match(name)
+            if not match:
+                continue
+            if kind is EventType.LGTM:
+                actor = match.groupdict().get("user")
+                if actor:
+                    gate.lgtm_actors.add(actor)
+                else:
+                    gate.has_plain_lgtm = True
+            elif kind is EventType.APPROVE:
+                gate.approved = True
+            elif kind is EventType.REJECT:
+                gate.rejected = True
+            elif kind is EventType.CLA_SIGNED:
+                gate.cla_signed = True
+            elif kind is EventType.CLA_DENIED:
+                gate.cla_denied = True
+            elif kind is EventType.CI_PASS:
+                gate.ci_passed = True
+            elif kind is EventType.CI_FAIL:
+                gate.ci_failed = True
+            elif kind is EventType.CI_RUNNING:
+                gate.ci_running = True
+            break
+
+    return gate
+
+
+def unrecognized_labels(label_names: Iterable[str]) -> list[str]:
+    """返回既未匹配评审规则、也不属于已知无关类别的标签。
+
+    用于诊断：当社区新增标签时，能第一时间发现解析规则未覆盖，
+    而不是让评审状态静默出错。
+    """
+    result: list[str] = []
+    for name in label_names:
+        if name == NEEDS_ISSUE_LABEL:
+            continue
+        if any(pattern.match(name) for pattern, _ in LABEL_RULES):
+            continue
+        if name.startswith(_IGNORED_LABEL_PREFIXES):
+            continue
+        result.append(name)
+    return result

package/backend/app/domain/sig.py

@@ -0,0 +1,178 @@
+"""SIG 名单与模块归属的解析。
+
+来源是 ``openeuler/community`` 仓库的两份 Markdown：
+
+- ``sig/Kernel/README.md`` —— Maintainer 列表
+- ``sig/Kernel/committers.md`` —— 按模块划分的 Committer 表
+
+两份都是人维护的文档，格式会变。这里同样按"尽力而为"处理：解析不出来的行
+跳过，不让一处格式变化导致整份名单同步失败。
+
+一个容易被忽略的细节：表格里 ``[@handle](url)`` 的 handle 与 URL 末段的 id
+**经常不同**（形如 ``[@display-name](https://atomgit.com/account-id)``）。
+handle 是人写的展示名，URL 里才是平台账号。两者都保留 —— 用 handle 匹配
+PR 作者会漏，用 URL id 展示给人看又会认不出来是谁。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# | kernel | kernel/\* | [@display-name](https://atomgit.com/account-id) |
+_TABLE_ROW = re.compile(r"^\|(.+)\|\s*$")
+_SEPARATOR_ROW = re.compile(r"^\|[\s:|-]+\|\s*$")
+_SECTION = re.compile(r"^##\s+(.+?)\s*$")
+
+# [@handle](https://atomgit.com/real_id) / [@handle](https://gitee.com/real_id)
+_ACCOUNT = re.compile(r"\[@?([^\]\s]+)\]\(\s*(https?://[^)\s]+)\s*\)")
+
+# Markdown 里混进来的排版残留：<img width=40/>、<br/>、转义的 \*
+_HTML_TAG = re.compile(r"<[^>]+>")
+
+# README 的 Maintainer 行：- 显示名 [@handle](https://gitee.com/account-id)
+_MAINTAINER = re.compile(r"^[-*]\s*([^\[]+?)\s*\[@?([^\]]+)\]\(\s*(https?://[^)\s]+)\s*\)")
+
+_PLATFORM_HOSTS = {
+    "atomgit.com": "atomgit",
+    "gitee.com": "gitee",
+    "github.com": "github",
+}
+
+
+@dataclass
+class AccountRef:
+    """一个平台账号。"""
+
+    handle: str
+    """文档里显示的 handle。用于展示。"""
+
+    platform: str
+    """atomgit / gitee / github / unknown。"""
+
+    account_id: str
+    """URL 末段的账号 id。用于匹配数据。"""
+
+    url: str
+
+
+@dataclass
+class SubsystemRow:
+    module: str
+    section: str
+    paths: list[str] = field(default_factory=list)
+    committers: list[AccountRef] = field(default_factory=list)
+
+
+@dataclass
+class MemberEntry:
+    name: str
+    role: str
+    accounts: list[AccountRef] = field(default_factory=list)
+    email: str | None = None
+
+
+def parse_accounts(cell: str) -> list[AccountRef]:
+    """从表格单元格里抽出全部账号引用。"""
+    accounts: list[AccountRef] = []
+    for handle, url in _ACCOUNT.findall(cell):
+        host = re.sub(r"^https?://(?:www\.)?", "", url).split("/")[0].lower()
+        platform = _PLATFORM_HOSTS.get(host, "unknown")
+        tail = [part for part in url.rstrip("/").split("/") if part]
+        accounts.append(
+            AccountRef(
+                handle=handle.strip(),
+                platform=platform,
+                account_id=tail[-1] if tail else handle,
+                url=url,
+            )
+        )
+    return accounts
+
+
+def _cell_to_paths(cell: str) -> list[str]:
+    """把「文件」列拆成路径前缀列表。
+
+    上游用 ``<br/>`` 分隔多个路径，用 ``\\*`` 表示前缀通配，还会混进
+    ``<img>`` 这类排版残留。这些都是展示层的写法，落到数据上只需要
+    干净的路径前缀。
+    """
+    # <br/> 与 <img .../> 一并换成换行/空白，剩下的才是路径
+    text = _HTML_TAG.sub("\n", cell)
+    paths: list[str] = []
+    for chunk in re.split(r"[\n,]+", text):
+        # 去掉通配符后可能出现 `arch//include/...` 这样的空目录段 —— 通配符
+        # 本身代表一层目录，删掉它就留下了一个空段
+        path = chunk.strip().replace("\\*", "").replace("*", "").strip().strip("/")
+        path = re.sub(r"/{2,}", "/", path)
+        if not path or path.startswith("文件"):
+            continue
+        paths.append(f"{path}/")
+    return paths
+
+
+def parse_committers(text: str) -> list[SubsystemRow]:
+    """解析 committers.md 的模块表。"""
+    rows: list[SubsystemRow] = []
+    section = ""
+
+    for line in text.splitlines():
+        if match := _SECTION.match(line):
+            section = match.group(1).strip()
+            continue
+        if not _TABLE_ROW.match(line) or _SEPARATOR_ROW.match(line):
+            continue
+
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) < 3:
+            continue
+        module, files, committers = cells[0], cells[1], "|".join(cells[2:])
+
+        # 表头行。列名里带 <img> 排版标签，所以用包含匹配而不是相等。
+        if "模块" in module or module.lower() == "module":
+            continue
+
+        accounts = parse_accounts(committers)
+        if not module or not accounts:
+            # 没有 Committer 的行是说明行，不是归属关系
+            continue
+
+        rows.append(
+            SubsystemRow(
+                module=module,
+                section=section,
+                paths=_cell_to_paths(files),
+                committers=accounts,
+            )
+        )
+    return rows
+
+
+def parse_maintainers(text: str) -> list[MemberEntry]:
+    """解析 README 的 Maintainer 列表。
+
+    只认 ``### Maintainer列表`` 之后的那一段，避免把正文里出现的
+    其他 ``[@who](url)`` 当成名单。
+    """
+    entries: list[MemberEntry] = []
+    in_section = False
+
+    for line in text.splitlines():
+        if line.startswith("#"):
+            heading = line.lstrip("#").strip()
+            in_section = "maintainer" in heading.lower() or "maintainer" in heading
+            continue
+        if not in_section:
+            continue
+        match = _MAINTAINER.match(line.strip())
+        if match is None:
+            continue
+        name, handle, url = match.groups()
+        entries.append(
+            MemberEntry(
+                name=name.strip(),
+                role="maintainer",
+                accounts=parse_accounts(f"[@{handle}]({url})"),
+            )
+        )
+    return entries