Measure the complexity limit in CI, and split the one function over it

CLAUDE.md sets cyclomatic complexity at 10 and names radon, but nothing
ran it. The whole package had one function over the limit, so the limit
is cheap to hold: the Triggers tab's combine handler now delegates to a
Qt-free children_to_combine() that has its own tests, and a test runs
radon over the package. radon joins dev_requirements and the CI install
so the gate runs there instead of skipping.

Author: JE-Chen

.github/workflows/quality.yml

@@ -139,7 +139,7 @@ jobs:
         shell: bash
         # Quoted: `--only-binary :all:` puts a colon-space inside the
         # scalar, which YAML reads as a mapping and refuses.
-        run: "pip install --only-binary :all: ruff==0.15.22 bandit==1.9.4 pytest==9.1.1 pytest-timeout==2.4.0 pytest-rerunfailures==15.1 coverage==7.15.4 PySide6==6.11.1"
+        run: "pip install --only-binary :all: ruff==0.15.22 bandit==1.9.4 pytest==9.1.1 pytest-timeout==2.4.0 pytest-rerunfailures==15.1 coverage==7.15.4 PySide6==6.11.1 radon==6.0.1"
 
       # Paths come from `testpaths` in pyproject.toml. Do NOT pass an explicit
       # path here: an argument overrides testpaths, which previously meant the

CLAUDE.md

@@ -123,7 +123,7 @@ Anything agreed but not done — deferred follow-ups, known gaps, half-delivered
 
 Cyclomatic complexity ≤ 10 · cognitive complexity ≤ 15 · function ≤ 75 lines · parameters ≤ 7 · nesting ≤ 4 · file ≤ 750 lines · line ≤ 120 chars · no duplicated block ≥ 10 lines.
 
-**What actually enforces these.** `quality.yml` has five jobs — `lint` (ruff), `security` (bandit), `pytest-headless` (the suite plus the coverage floor), `typing-stable-api` (mypy) and `dependency-review`. Of the limits in this section, line length is rejected by ruff (`[tool.ruff] line-length = 120` with `E501`; it exempts a line ending in a pragma, which cannot wrap), and the file-length limit by `test/unit_test/headless/test_file_length_budget.py`, which reads the exemption list in `Progress.md` and fails on a file over the limit that is not listed, on a listed file that grew past its recorded ceiling, and on a row whose file is now under the limit. Complexity is measured by `radon cc -nc` in the pre-commit list below and read by a human — that part is a review standard, not a gate.
+**What actually enforces these.** `quality.yml` has five jobs — `lint` (ruff), `security` (bandit), `pytest-headless` (the suite plus the coverage floor), `typing-stable-api` (mypy) and `dependency-review`. Of the limits in this section, line length is rejected by ruff (`[tool.ruff] line-length = 120` with `E501`; it exempts a line ending in a pragma, which cannot wrap), and the file-length limit by `test/unit_test/headless/test_file_length_budget.py`, which reads the exemption list in `Progress.md` and fails on a file over the limit that is not listed, on a listed file that grew past its recorded ceiling, and on a row whose file is now under the limit. Cyclomatic complexity is measured with the same `radon` the pre-commit list below names, by `test/unit_test/headless/test_complexity_budget.py`; the whole package was one function over the limit when that gate went in. Cognitive complexity, function length, parameter count and nesting depth are still review standards rather than gates.
 
 **Scope of the file-length limit.** It applies to:
 

architecture_explore.md

@@ -20,7 +20,7 @@ iOS（WebDriverAgent）。核心能力是滑鼠／鍵盤控制、影像辨識、
 | 指標 | 數值 |
 | --- | ---: |
 | Python 模組總數（含周邊子專案） | 1,043 |
-| 程式碼總行數 | 142,003 |
+| 程式碼總行數 | 142,022 |
 | `je_auto_control/utils/` 子套件數 | 310 |
 | `AC_*` 動作指令數（`known_commands()` 實測） | 773 |
 | 套件門面 `__all__` 公開名稱數 | 1,238 |
@@ -1056,7 +1056,7 @@ socket 預設綁 `127.0.0.1`；資源一律用 `with`。
 
 | 層／子系統 | 檔案數 | 行數 |
 | --- | ---: | ---: |
-| `gui/` | 91 | 26,772 |
+| `gui/` | 91 | 26,791 |
 | `utils/mcp_server/` | 31 | 17,473 |
 | `utils/remote_desktop/` | 56 | 12,039 |
 | `utils/executor/` | 6 | 9,081 |
@@ -1077,5 +1077,5 @@ socket 預設綁 `127.0.0.1`；資源一律用 `with`。
 | `autocontrol-lsp/` | 8 | 744 |
 | `utils/hotkey/` | 7 | 738 |
 | 其餘模組（約 286 個 `utils/` 子套件 + `android/`／`ios/`／周邊小工具） | 673 | 47,957 |
-| **總計** | **1,037** | **141,938** |
+| **總計** | **1,037** | **141,957** |
 

dev_requirements.txt

@@ -31,4 +31,7 @@ pytest-rerunfailures==15.1
 # `pytest --cov` under-reports by ~24 points. Measure with
 # `coverage run -m pytest`; see the comment in .github/workflows/quality.yml.
 coverage==7.15.4
+# The complexity limit in CLAUDE.md is measured by this, both in the
+# pre-commit list and by test/unit_test/headless/test_complexity_budget.py.
+radon==6.0.1
 mypy>=1.15

docs/updates/2026-09.md

@@ -220,3 +220,11 @@ Index and query commands: [README.md](README.md). New entries go at the end.
 - **Result / numbers**: 4 tests; `-k "file_length or webrtc or remote_desktop_gui or r3_gui"`: 496 passed, 4 skipped. `CLAUDE.md`'s "what actually enforces these" paragraph now names both gates (ruff for line length, this test for file length) and keeps complexity as the one that is still a review standard.
 - **Files**: `test/unit_test/headless/test_file_length_budget.py` (new), `je_auto_control/gui/remote_desktop/trusted_group.py` (new), `je_auto_control/gui/remote_desktop/webrtc_panel.py`, `CLAUDE.md`, `Progress.md`, `architecture_explore.md`.
 - **Open items**: none.
+
+## U-20260923-12 · 2026-09-23 · Complexity limit measured in CI; the one function over it split · #done #quality
+
+- **What**: `CLAUDE.md` set cyclomatic complexity at 10 and named `radon cc -nc` as the tool, but nothing ran it — it sat in the pre-commit list, "read by a human", which is how the file-length list had drifted too (U-20260923-11). Measured across the package: exactly **one** function was over the limit, `gui/triggers_tab.py::TriggersTab._on_combine`. So the limit was cheap to hold, and `test/unit_test/headless/test_complexity_budget.py` now measures it with the same `radon` a developer runs (added to `dev_requirements.txt` and to `quality.yml`'s install line, so it is a gate in CI rather than a skip).
+- **The one function**: `_on_combine` read the selection, validated it, resolved ids to triggers, removed the originals and built the composite in one body. The selection is `_selected_ids`, the resolution is the module-level `children_to_combine(ids, triggers)` — no Qt, so the part worth testing is testable — and the mode-to-class mapping is the module constant `COMPOSITE_BY_MODE`. Behaviour is unchanged, including that ids the table still shows but the engine no longer has are dropped rather than raising.
+- **Result / numbers**: `test_triggers_tab_combine.py` (7 tests) covers the combining logic, which had none — the tab's only tests were of the trigger engine behind it. `test_complexity_budget.py` 2 tests, one a positive control on synthetic code so an empty result cannot mean the measurement stopped working.
+- **Files**: `je_auto_control/gui/triggers_tab.py`, `test/unit_test/headless/{test_complexity_budget,test_triggers_tab_combine}.py` (new), `dev_requirements.txt`, `.github/workflows/quality.yml`, `CLAUDE.md`, `architecture_explore.md`.
+- **Open items**: none. Cognitive complexity, function length, parameter count and nesting depth are still review standards; `radon` measures the first of those four only.

docs/updates/README.md

@@ -58,6 +58,7 @@ In the same commit: delete the item from `Progress.md`, add a `#done` entry here
 
 | ID | Date | Title | Tags | Batch |
 |---|---|---|---|---|
+| U-20260923-12 | 2026-09-23 | Complexity limit measured in CI; the one function over it split | #done #quality | [2026-09](2026-09.md) |
 | U-20260923-11 | 2026-09-23 | The 750-line limit is now a gate, and it caught one | #done #quality | [2026-09](2026-09.md) |
 | U-20260923-10 | 2026-09-23 | Review follow-ups: priming race, stub width, key-table contract | #done #review | [2026-09](2026-09.md) |
 | U-20260923-09 | 2026-09-23 | _handlers.py under the line limit: nine themed modules | #done #mcp | [2026-09](2026-09.md) |
@@ -116,7 +117,7 @@ In the same commit: delete the item from `Progress.md`, add a `#done` entry here
 
 | File | Period | Entries |
 |---|---|---:|
-| [2026-09.md](2026-09.md) | 2026-09 | 27 |
+| [2026-09.md](2026-09.md) | 2026-09 | 28 |
 | [2026-08-f.md](2026-08-f.md) | 2026-08 | 1 |
 | [2026-08-e.md](2026-08-e.md) | 2026-08 | 2 |
 | [2026-08-d.md](2026-08-d.md) | 2026-08 | 2 |

je_auto_control/gui/triggers_tab.py

@@ -1,5 +1,5 @@
 """Triggers tab: image / window / pixel / file event watchers."""
-from typing import Optional
+from typing import Any, Dict, Iterable, List, Optional, Sequence
 
 from PySide6.QtCore import QTimer
 from PySide6.QtWidgets import (
@@ -29,6 +29,24 @@ def _t(key: str) -> str:
 )
 
 
+#: Which composite trigger each "combine" button builds.
+COMPOSITE_BY_MODE: Dict[str, type] = {
+    "all": AllOfTrigger, "any": AnyOfTrigger, "sequence": SequenceTrigger,
+}
+
+
+def children_to_combine(ids: Sequence[str],
+                        triggers: Iterable[Any]) -> List[Any]:
+    """The triggers named by ``ids``, or ``[]`` when fewer than two resolve.
+
+    Ids that no longer name a trigger are dropped: the table can outlive a
+    removal, and combining one trigger with nothing is not a composite.
+    """
+    by_id = {trigger.trigger_id: trigger for trigger in triggers}
+    children = [by_id[tid] for tid in ids if tid in by_id]
+    return children if len(children) >= 2 else []
+
+
 class TriggersTab(TranslatableMixin, QWidget):
     """Build triggers, run the engine, inspect the table."""
 
@@ -256,27 +274,28 @@ def _on_remove(self) -> None:
         default_trigger_engine.remove(tid)
         self._refresh()
 
-    def _on_combine(self, mode: str) -> None:
+    def _selected_ids(self) -> List[str]:
+        """Trigger ids of the selected rows, in row order, without duplicates."""
         rows = sorted({idx.row() for idx in self._table.selectedIndexes()})
-        ids = [self._table.item(row, 0).text() for row in rows
-               if self._table.item(row, 0) is not None]
+        return [self._table.item(row, 0).text() for row in rows
+                if self._table.item(row, 0) is not None]
+
+    def _on_combine(self, mode: str) -> None:
+        ids = self._selected_ids()
         if len(ids) < 2:
             QMessageBox.warning(self, "Error", _t("tr_combine_need_two"))
             return
         script = self._script_input.text().strip()
         if not script:
             QMessageBox.warning(self, "Error", "Script path is required")
             return
-        by_id = {t.trigger_id: t
-                 for t in default_trigger_engine.list_triggers()}
-        children = [by_id[tid] for tid in ids if tid in by_id]
-        if len(children) < 2:
+        children = children_to_combine(
+            ids, default_trigger_engine.list_triggers())
+        if not children:
             return
         for tid in ids:
             default_trigger_engine.remove(tid)
-        composite_cls = {"all": AllOfTrigger, "any": AnyOfTrigger,
-                         "sequence": SequenceTrigger}[mode]
-        default_trigger_engine.add(composite_cls(
+        default_trigger_engine.add(COMPOSITE_BY_MODE[mode](
             trigger_id="", script_path=script,
             repeat=self._repeat_check.isChecked(), children=children,
         ))

test/unit_test/headless/test_complexity_budget.py

@@ -0,0 +1,53 @@
+"""No function in the package is over the documented complexity limit.
+
+``CLAUDE.md`` sets cyclomatic complexity at 10 and names ``radon cc -nc`` as
+the tool, but nothing ran it: it sat in the pre-commit list, "read by a human".
+Measured on 2026-09-23 the whole package had exactly **one** function above the
+limit, so the limit is cheap to hold — and a limit nobody measures is the one
+that drifts.
+
+``radon`` is the same tool the pre-commit list names, so the number here and
+the number a developer sees are the same number.
+"""
+from pathlib import Path
+
+import pytest
+
+radon_complexity = pytest.importorskip(
+    "radon.complexity", reason="pip install radon (see CLAUDE.md)")
+
+_PACKAGE = Path(__file__).resolve().parents[3] / "je_auto_control"
+
+#: ``CLAUDE.md`` § Size and complexity limits.
+LIMIT = 10
+
+
+def over_limit(source: str, limit: int = LIMIT):
+    """``(name, complexity)`` for every block above ``limit``."""
+    return [(block.fullname, block.complexity)
+            for block in radon_complexity.cc_visit(source)
+            if block.complexity > limit]
+
+
+def test_no_function_in_the_package_is_over_the_limit():
+    offenders = []
+    for path in sorted(_PACKAGE.rglob("*.py")):
+        if "__pycache__" in path.parts:
+            continue
+        for name, score in over_limit(path.read_text(encoding="utf-8")):
+            offenders.append(
+                f"{path.relative_to(_PACKAGE.parent).as_posix()}: {name} = {score}")
+    assert not offenders, (
+        f"cyclomatic complexity over {LIMIT} (split the function):\n"
+        + "\n".join(offenders))
+
+
+def test_the_measurement_sees_a_complex_function():
+    """Positive control: an empty result above must mean clean, not blind."""
+    branches = "\n".join(f"    if value == {index}:\n        return {index}"
+                         for index in range(12))
+    source = f"def busy(value):\n{branches}\n    return None\n"
+    found = over_limit(source)
+    assert [name for name, _ in found] == ["busy"]
+    assert found[0][1] > LIMIT
+    assert over_limit("def calm(value):\n    return value\n") == []

test/unit_test/headless/test_triggers_tab_combine.py

@@ -0,0 +1,48 @@
+"""The combining logic behind the Triggers tab's three combine buttons.
+
+``_on_combine`` was the one function in the package over the complexity limit,
+and the part worth testing — which selected ids become a composite's children —
+needed no Qt at all. It is a module function now, so this test does not build a
+widget; only the import needs PySide6.
+"""
+from dataclasses import dataclass
+
+import pytest
+
+pytest.importorskip("PySide6.QtWidgets", exc_type=ImportError)
+
+from je_auto_control.gui.triggers_tab import (  # noqa: E402
+    COMPOSITE_BY_MODE, children_to_combine,
+)
+from je_auto_control.utils.triggers.trigger_engine import (  # noqa: E402
+    AllOfTrigger, AnyOfTrigger, SequenceTrigger,
+)
+
+
+@dataclass
+class _Trigger:
+    trigger_id: str
+
+
+def test_selected_ids_become_children_in_the_order_given():
+    triggers = [_Trigger("a"), _Trigger("b"), _Trigger("c")]
+    children = children_to_combine(["c", "a"], triggers)
+    assert [child.trigger_id for child in children] == ["c", "a"]
+
+
+def test_an_id_that_no_longer_exists_is_dropped():
+    """The table can outlive a removal; the stale row must not raise."""
+    triggers = [_Trigger("a"), _Trigger("b")]
+    children = children_to_combine(["a", "gone", "b"], triggers)
+    assert [child.trigger_id for child in children] == ["a", "b"]
+
+
+@pytest.mark.parametrize("ids", [[], ["a"], ["a", "gone"], ["gone", "other"]])
+def test_fewer_than_two_resolved_triggers_combine_into_nothing(ids):
+    assert children_to_combine(ids, [_Trigger("a")]) == []
+
+
+def test_every_button_mode_maps_to_its_composite():
+    assert COMPOSITE_BY_MODE == {
+        "all": AllOfTrigger, "any": AnyOfTrigger, "sequence": SequenceTrigger,
+    }