From 52772cf027511abf508095090d85c3619d5f204c Mon Sep 17 00:00:00 2001 From: Tiance Wang <11400530+wangtiance@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:51:50 +0800 Subject: [PATCH] [ci] skip heavy checks for proven documentation-only PRs ## summary Classify the complete PR diff after shared static checks and skip heavy lanes only for an explicit nonempty documentation allowlist. - Retain code, mixed, renamed-code and unknown comparisons in the full gate, including all main pushes, manual runs and nightly callers. - Require successful static evidence and every skipped lane receipt in the stable aggregate; failures and cancellations remain blocking. - Exercise real Git ranges and aggregate execution, document the policy in both languages, and align the PR budget target to 30 minutes. --- .github/workflows/release-checks.yml | 15 ++- docs/development/validation.md | 22 ++-- scripts/ci/select_checks.py | 70 +++++++++++ scripts/ci/summarize_checks.py | 20 +++ tests/test_ci_scope.py | 175 +++++++++++++++++++++++++++ tests/test_ci_summary.py | 58 ++++++++- 6 files changed, 344 insertions(+), 16 deletions(-) create mode 100644 scripts/ci/select_checks.py create mode 100644 tests/test_ci_scope.py diff --git a/.github/workflows/release-checks.yml b/.github/workflows/release-checks.yml index c25df408..9a8ee450 100644 --- a/.github/workflows/release-checks.yml +++ b/.github/workflows/release-checks.yml @@ -24,6 +24,10 @@ jobs: if: inputs.static-checks runs-on: ubuntu-22.04 timeout-minutes: 10 + outputs: + run-heavy: ${{ steps.scope.outputs.run-heavy }} + scope-reason: ${{ steps.scope.outputs.scope-reason }} + changed-files: ${{ steps.scope.outputs.changed-files }} steps: - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0 with: @@ -47,10 +51,15 @@ jobs: else python -m pre_commit run --all-files fi + - id: scope + name: Select check scope / 判断检查范围 + env: + PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} + run: python scripts/ci/select_checks.py python: needs: static - if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }} + if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }} runs-on: ubuntu-22.04 timeout-minutes: 30 steps: @@ -114,7 +123,7 @@ jobs: frontend: needs: static - if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }} + if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }} runs-on: ubuntu-22.04 timeout-minutes: 30 steps: @@ -171,7 +180,7 @@ jobs: browser: needs: static - if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }} + if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }} runs-on: ubuntu-22.04 timeout-minutes: 30 strategy: diff --git a/docs/development/validation.md b/docs/development/validation.md index 9d856ec8..641691a8 100644 --- a/docs/development/validation.md +++ b/docs/development/validation.md @@ -42,7 +42,7 @@ This is the target contract for [#273](https://github.com/ThinkFlowLab/OpenDirec | Stage / 阶段 | Trigger / 触发 | Responsibility / 职责 | Target budget / 目标预算 | | --- | --- | --- | --- | | Local / 本地 | Before commit and PR creation / 提交及提出 PR 前 | One `.pre-commit-config.yaml` for staged-file hooks and an explicit whole-PR diff check, shared by users and agents. No ready tests. / 同一配置用于暂存文件 hook 和覆盖整个 PR 差异的显式检查,用户与 agent 共用;不跑 ready。 | Fast static feedback; measure warm runs separately from setup / 快速静态反馈,暖运行与初始化分别计时 | -| PR | Open, reopen and update, including drafts / 提出、重开及更新,包含 draft | CI repeats the same static configuration before ready: frontend units, Python ready, i18n, browser locale/manifest, imports, generated contracts, production build, wheel verification and browser gate including voice and assistant auxiliary panels. Every PR also runs security scanning. / 静态复核通过后跑 ready:前端单元、Python ready、国际化、浏览器语言与清单、分层导入、生成契约、构建、wheel 和包含语音及助手辅助面板的浏览器 gate;每个 PR 另跑安全扫描。 | Entire PR gate ≤15 min / 整个 PR 门禁 ≤15 分钟 | +| PR | Open, reopen and update, including drafts / 提出、重开及更新,包含 draft | CI repeats the same static configuration before ready: frontend units, Python ready, i18n, browser locale/manifest, imports, generated contracts, production build, wheel verification and browser gate including voice and assistant auxiliary panels. Every PR also runs security scanning. / 静态复核通过后跑 ready:前端单元、Python ready、国际化、浏览器语言与清单、分层导入、生成契约、构建、wheel 和包含语音及助手辅助面板的浏览器 gate;每个 PR 另跑安全扫描。 | Entire PR gate ≤30 min / 整个 PR 门禁 ≤30 分钟 | | Merge queue / 合并队列 | `merge_group: checks_requested`, before main changes / main 更新前 | Test latest main plus preceding queued PRs and this PR. Repeat PR checks and add Python merge; all required checks must succeed before merging. / 验证最新 main、前序排队 PR 与当前 PR 的组合;复跑 PR 检查并增加 Python merge,必需检查全部成功后才能合入。 | Entire queue gate ≤30 min / 整个队列门禁 ≤30 分钟 | | main | Push after successful queue merge / 队列成功合并后的 push | Collect merged SHA, successful queue checks and artifacts; prove they correspond to merged content. No routine full-suite rerun. Missing or unprovable evidence blocks release and requires checks on the exact main SHA. / 归集合并 SHA、成功队列检查与产物,证明其对应合并内容;常规不重跑完整套件。证据缺失或无法对应时阻止发布,对准确 main SHA 补跑。 | Evidence collection / 证据归集 | | Nightly / 夜间 | `0 18 * * *` UTC, next day 02:00 Asia/Shanghai; manual dispatch / 定时或手动 | Python nightly, flake watchlist, browser extended/extendedFixture, production, perf and daily benchmark. Advisory failures are tracked; no automatic tags. Do not repeat PR/queue suites except intentional watchlist reruns. / 运行 Python nightly、flake watchlist、浏览器扩展与独立 fixture、生产、性能及每日基准;advisory 失败须跟踪,不自动打 tag;除明确的 watchlist 重跑外,不重复 PR/队列套件。 | Extended ≤60; production ≤45; perf and benchmark each ≤30 min / 扩展 ≤60、生产 ≤45、性能与基准各 ≤30 分钟 | @@ -53,9 +53,9 @@ Budgets measure stage wall time, not the sum of parallel job limits, and never j ### 过渡与必需检查 / Transition and required checks -当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁,Python 仍跑全量;[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,但机型轴、安全扫描、docs-only 重任务跳过、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;15/30 分钟是目标阶段预算,不代表当前已强制执行。 +当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁;纯文档 PR 按下方白名单跳过重检查,其余仍跑全量 Python。[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,但机型轴、安全扫描、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;PR 和队列各 30 分钟是阶段目标,不代表已强制端到端总上限。 -Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes while Python still runs in full. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered; hardware tagging, security scanning, docs-only heavy-job skipping, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; the 15/30-minute stage budgets are targets, not existing enforcement. +Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes. Documentation-only PRs use the allowlist below to skip heavy checks; other changes retain full Python selection. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered; hardware tagging, security scanning, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; 30 minutes each for PR and queue are stage targets, not enforced end-to-end deadlines. - 本地 hook 可未安装或被绕过,不能在 GitHub 上普遍阻止 PR 创建。必需 CI 必须复核同一配置;静态失败阻止启动重测试,并使稳定汇总检查失败。/ Local hooks can be absent or bypassed and cannot universally prevent PR creation. Required CI repeats the same configuration; static failure blocks heavy jobs and fails the stable aggregate. - 纯文档变更可跳过重 Python/浏览器任务,但必须保留稳定的必需检查,报告跳过依据并成功结束。合并队列按整个 merge-group 差异判断,不能只看最后一个 PR;无法确定范围时执行完整门禁。/ Documentation-only changes may skip heavy Python/browser jobs, but a stable required check must report the reason and succeed. Queue filtering covers the whole merge-group diff, not only its last PR; uncertain scope runs the full gate. @@ -102,17 +102,21 @@ Checks cover YAML/JSON/TOML and Python syntax, conflict markers, Python debug st Local hooks can be absent or bypassed. PR and main Release checks run the same configuration in a separate static job. PRs compare base to tested merge HEAD; pushes compare before to HEAD. Only the static checkout needing a range comparison fetches full history; other jobs use shallow checkouts. Manual/initial-push full-file audits do not need full history. -静态通过后并行运行 Python(导入、契约、全量 pytest、bundled OpenCode 回归)、前端/构建/wheel 和浏览器检查。浏览器 isolated、voice、assistant 分为三个独立 matrix job,`fail-fast: false`,一条失败不取消其余旅程。每个 runner 独立安装依赖,复用现有 pip/npm 缓存;这会增加 runner 分钟数,墙钟耗时改善须以实际 CI 为准。 +静态通过后,范围检查仅对 PR 比较 base 与测试用合并 HEAD 的 merge-base 差异,保留整个 PR 的变更。只有非空差异全部属于根目录 `README.md`、`README.zh-CN.md`、`CONTRIBUTING.md`、`CHANGELOG.md`,或 `docs/` 内的 Markdown、PNG/JPEG/GIF/WebP,才跳过 Python、前端/构建/wheel 和全部 browser matrix。重命名同时检查旧、新路径;文档目录内的代码/配置、AGENTS/skill、工作流、测试、混合变更、空差异或比较失败都跑完整门禁。分类不会访问 PR API,路径使用 NUL 分隔,含空格或中文不会截断。 -After static success, Python (imports, contracts, full pytest and bundled OpenCode), frontend/build/wheel and browser checks run in parallel. Browser isolated, voice and assistant journeys use separate matrix jobs with fail-fast disabled. Each runner installs its own dependencies using existing pip/npm caches. This increases runner minutes; wall-clock improvements require actual CI measurements. +After static success, scope selection compares the PR base and tested merge HEAD from their merge base, retaining the whole PR diff. Heavy Python, frontend/build/wheel and all browser matrix jobs are skipped only for a nonempty diff entirely within root `README.md`, `README.zh-CN.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, or Markdown/PNG/JPEG/GIF/WebP under `docs/`. Renames check both old and new paths. Code/configuration under docs, AGENTS/skills, workflows, tests, mixed changes, empty diffs and unavailable comparisons keep the full gate. Selection needs no PR API; NUL-delimited paths preserve spaces and non-ASCII names. -最终 `checks` 汇总 job 保留现有必需检查名称,并始终读取各检查线结果;任何失败、取消、意外跳过或缺失回执均失败。只有调用方显式关闭静态检查时,static 的 skipped 才允许通过。静态失败不会启动重测试,但最终汇总仍失败,不能把依赖跳过误判为通过。 +main push、手动运行和 nightly 保持完整检查;本次不启用 `merge_group`,也不切换 Python ready 筛选。需要重检查时,Python(导入、契约、全量 pytest、bundled OpenCode)、前端/构建/wheel 和浏览器并行执行,browser `fail-fast: false`;一条失败不取消其余旅程。 -The final `checks` aggregate preserves the existing required-check name and always evaluates all lane results. Failure, cancellation, unexpected skips or missing receipts fail closed. A skipped static job is allowed only when the caller explicitly disabled static checks. Static failure prevents heavy test jobs from starting and still fails the aggregate. +Main pushes, manual runs and nightly retain full checks. This change enables neither `merge_group` nor Python ready selection. When heavy checks are required, Python (imports, contracts, full pytest and bundled OpenCode), frontend/build/wheel and browser jobs run in parallel with browser fail-fast disabled; one failure does not cancel other journeys. -可复用工作流的 `static-checks` 默认关闭,由 `ci.yml` 开启;nightly 不新增重复静态检查。CI 不提交自动修复:hook 修改文件视为失败,需在本地修复。当前静态 job 上限 10 分钟,Python、前端和每个浏览器 job 各 30 分钟,汇总 job 5 分钟;这是各 job 的限额,不是整个工作流的总上限。当前仍跑全量,暂不采用 PR ready 子集的 15 分钟目标;待子集切换或并行运行有足够耗时证据后再收紧。 +最终 `checks` 汇总保留现有必需检查名称并始终执行。只有 static 成功且提供明确的 `docs_only`、正数变更路径数、PR 事件和跳过决定时,才接受三条重检查线的 skipped;汇总会报告依据。任何失败、取消、意外跳过、无效决定或缺失回执仍失败。只有调用方显式关闭静态检查时,static 自身才允许 skipped,且此时必须跑重检查。静态失败造成的依赖跳过不能通过汇总。 -The reusable workflow's `static-checks` defaults to false and is enabled by `ci.yml`; nightly adds no duplicate static pass. CI never commits automatic fixes. Static has a 10-minute timeout; Python, frontend and each browser job have 30 minutes; the aggregate has 5 minutes. These are per-job limits, not a workflow-wide deadline. Full suites still run, so the 15-minute PR-ready target is deferred until subset activation or sufficient timing evidence from parallel runs. +The final `checks` aggregate preserves its required-check name and always runs. Only successful static checks with an explicit `docs_only` decision, a positive changed-path count and a PR event can authorize skipped heavy lanes; the summary reports that evidence. Failures, cancellations, unexpected skips, invalid decisions and missing receipts still fail. Only an explicitly disabled static lane may itself be skipped, in which case heavy lanes must run. Dependency skips after static failure cannot pass the aggregate. + +可复用工作流的 `static-checks` 默认关闭,由 `ci.yml` 开启;nightly 不重复静态检查。CI 不提交自动修复,hook 修改文件仍视为失败。PR 阶段预算先按 30 分钟;当前 static 上限 10 分钟,Python、前端和每个浏览器 job 各 30 分钟,汇总 5 分钟。这些仍是各 job 限额,不能相加或解释为已强制的阶段总上限;后续按实际测量改进端到端耗时。 + +The reusable workflow's `static-checks` defaults to false and is enabled by `ci.yml`; nightly does not duplicate static checks. CI never commits automatic fixes; hook edits remain failures. The PR stage budget is 30 minutes for now. Static has 10 minutes, Python/frontend/each browser job 30 minutes, and the aggregate 5 minutes. These remain per-job limits, not a summed or enforced workflow-wide deadline; improve end-to-end time using actual measurements. ## Python 分层与迁移 / Python layers and transition diff --git a/scripts/ci/select_checks.py b/scripts/ci/select_checks.py new file mode 100644 index 00000000..72d791c4 --- /dev/null +++ b/scripts/ci/select_checks.py @@ -0,0 +1,70 @@ +"""Skip heavy PR checks only for a proven, nonempty documentation-only diff.""" +import json +import os +from pathlib import Path, PurePosixPath +import re +import subprocess + + +ROOT_DOCUMENTS = {'README.md', 'README.zh-CN.md', 'CONTRIBUTING.md', 'CHANGELOG.md'} +DOCUMENT_SUFFIXES = {'.md', '.png', '.jpg', '.jpeg', '.gif', '.webp'} +REASONS = { + 'docs_only': 'Documentation only; heavy checks skipped / 纯文档,跳过重检查', + 'non_documentation': 'Code, configuration or other inputs changed / 代码、配置或其他输入有变更', + 'comparison_unavailable': 'Diff could not be proven; run full checks / 无法确认差异,运行完整检查', + 'empty_diff': 'Empty diff; run full checks / 差异为空,运行完整检查', + 'event_requires_full': 'Only pull requests may skip heavy checks / 仅 PR 可跳过重检查', +} + + +def documentation(path): + if path in ROOT_DOCUMENTS: + return True + if not path.startswith('docs/') or '\\' in path or any(part in {'', '.', '..'} for part in path.split('/')): + return False + return PurePosixPath(path).suffix.lower() in DOCUMENT_SUFFIXES + + +def select(event, base, *, repository=None): + result = {'run-heavy': 'true', 'scope-reason': 'event_requires_full', 'changed-files': '0'} + if event != 'pull_request': + return result + result['scope-reason'] = 'comparison_unavailable' + if not re.fullmatch(r'[0-9a-f]{40}', base or ''): + return result + try: + # Three dots match the pre-commit PR range. Disabling rename detection + # retains both old and new paths: code renamed into docs is still code. + diff = subprocess.check_output( + ['git', 'diff', '--no-ext-diff', '--no-renames', '--name-only', '-z', base + '...HEAD', '--'], + cwd=repository, stderr=subprocess.DEVNULL, timeout=30, + ) + if diff and not diff.endswith(b'\0'): + return result + paths = diff.decode('utf-8').rstrip('\0').split('\0') if diff else [] + except (OSError, subprocess.SubprocessError, UnicodeError): + return result + result['changed-files'] = str(len(paths)) + if not paths: + result['scope-reason'] = 'empty_diff' + elif all(documentation(path) for path in paths): + result.update({'run-heavy': 'false', 'scope-reason': 'docs_only'}) + else: + result['scope-reason'] = 'non_documentation' + return result + + +def main(): + result = select(os.environ.get('GITHUB_EVENT_NAME'), os.environ.get('PR_BASE_SHA')) + print(json.dumps(result)) + if path := os.environ.get('GITHUB_OUTPUT'): + with Path(path).open('a', encoding='utf-8') as output: + output.writelines(f'{key}={value}\n' for key, value in result.items()) + if path := os.environ.get('GITHUB_STEP_SUMMARY'): + with Path(path).open('a', encoding='utf-8') as output: + output.write('## Check scope / 检查范围\n\n' + REASONS[result['scope-reason']] + + '\n\nChanged paths / 变更路径数: ' + result['changed-files'] + '\n') + + +if __name__ == '__main__': + main() diff --git a/scripts/ci/summarize_checks.py b/scripts/ci/summarize_checks.py index fbfdecdd..94873b9e 100644 --- a/scripts/ci/summarize_checks.py +++ b/scripts/ci/summarize_checks.py @@ -12,11 +12,26 @@ def main(): expected = {'static', 'python', 'frontend', 'browser'} if set(results) != expected: raise SystemExit('Missing or unexpected release-check lanes') + scope = results['static'].get('outputs', {}) + heavy = scope.get('run-heavy', '') + if heavy not in {'', 'true', 'false'}: + raise SystemExit('Invalid check-scope decision / 检查范围判定无效') + docs_only = heavy == 'false' + if docs_only and not ( + static_enabled and results['static']['result'] == 'success' + and os.environ.get('GITHUB_EVENT_NAME') == 'pull_request' + and scope.get('scope-reason') == 'docs_only' + and str(scope.get('changed-files', '')).isdigit() + and int(scope['changed-files']) > 0 + ): + raise SystemExit('Unproven documentation-only skip / 无法证明纯文档跳过依据') rows = [] failed = [] for name in sorted(expected): result = results[name]['result'] allowed = {'success'} + if docs_only and name != 'static': + allowed = {'skipped'} if name == 'static' and not static_enabled: allowed.add('skipped') rows.append(f'| {name} | {result} |') @@ -24,6 +39,11 @@ def main(): failed.append(name) report = '\n'.join([ '## Release checks / 发布检查', '', + ('Documentation-only PR: static passed; heavy checks intentionally skipped. / ' + '纯文档 PR:静态通过,按明确范围跳过重检查。' if docs_only + else 'Full checks required / 需要完整检查'), + 'Scope / 范围: ' + str(scope.get('scope-reason', 'full')) + + '; changed paths / 变更路径数: ' + str(scope.get('changed-files', 'unknown')), '', '| Lane / 检查线 | Result / 结果 |', '| --- | --- |', *rows, '', ]) print(report) diff --git a/tests/test_ci_scope.py b/tests/test_ci_scope.py new file mode 100644 index 00000000..147559cb --- /dev/null +++ b/tests/test_ci_scope.py @@ -0,0 +1,175 @@ +"""Exercise the actual Git range: skips must never hide code or unknown scope.""" +import importlib.util +import json +import os +from pathlib import Path +import subprocess +import sys + +import pytest +import yaml + + +pytestmark = pytest.mark.ready +ROOT = Path(__file__).resolve().parents[1] +SCRIPT = ROOT / 'scripts/ci/select_checks.py' +spec = importlib.util.spec_from_file_location('check_scope', SCRIPT) +scope = importlib.util.module_from_spec(spec) +spec.loader.exec_module(scope) + + +def git(repo, *args): + return subprocess.check_output( + ['git', '-c', 'user.name=CI test', '-c', 'user.email=ci@example.invalid', *args], + cwd=repo, stderr=subprocess.DEVNULL, + ).decode('utf-8').strip() + + +@pytest.fixture +def repository(tmp_path): + git(tmp_path, 'init', '-q') + for name in ['README.md', 'src/app.py']: + path = tmp_path / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text('baseline\n', encoding='utf-8') + git(tmp_path, 'add', '.') + git(tmp_path, 'commit', '-qm', 'baseline') + return tmp_path, git(tmp_path, 'rev-parse', 'HEAD') + + +def commit(repo, *names): + for name in names: + path = repo / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text('changed\n', encoding='utf-8') + git(repo, 'add', '.') + git(repo, 'commit', '-qm', 'change') + + +@pytest.mark.parametrize('names,docs', [ + (['README.md', 'docs/development/validation.md'], True), + (['docs/guides/images/preview.png', 'docs/guide with spaces.md'], True), + (['docs/中文说明.md'], True), + (['docs/guide.md', 'src/app.py'], False), + (['.github/workflows/ci.yml'], False), + (['.pre-commit-config.yaml'], False), + (['requirements.txt'], False), + (['AGENTS.md'], False), + (['.agents/skills/example/SKILL.md'], False), + (['docs/helper.py'], False), + (['docs/config.json'], False), + (['tests/README.md'], False), +]) +def test_only_allowlisted_nonempty_documentation_can_skip(repository, names, docs): + repo, base = repository + commit(repo, *names) + decision = scope.select('pull_request', base, repository=repo) + assert decision['run-heavy'] == ('false' if docs else 'true') + assert decision['scope-reason'] == ('docs_only' if docs else 'non_documentation') + assert int(decision['changed-files']) == len(names) + + +def test_whole_pr_not_only_last_commit(repository): + repo, base = repository + commit(repo, 'src/app.py') + commit(repo, 'docs/guide.md') + assert scope.select('pull_request', base, repository=repo)['run-heavy'] == 'true' + + +def test_code_renamed_into_docs_is_still_code(repository): + repo, base = repository + (repo / 'docs').mkdir() + git(repo, 'mv', 'src/app.py', 'docs/guide.md') + git(repo, 'commit', '-qm', 'rename') + decision = scope.select('pull_request', base, repository=repo) + assert decision['run-heavy'] == 'true' + assert decision['changed-files'] == '2' + + +def test_deleted_document_is_documentation(repository): + repo, base = repository + git(repo, 'rm', 'README.md') + git(repo, 'commit', '-qm', 'remove') + assert scope.select('pull_request', base, repository=repo)['run-heavy'] == 'false' + + +def test_merge_base_excludes_unrelated_base_branch_changes(repository): + repo, base = repository + commit(repo, 'docs/guide.md') + tip = git(repo, 'rev-parse', 'HEAD') + git(repo, 'checkout', '-qb', 'base-update', base) + commit(repo, 'src/base-only.py') + updated_base = git(repo, 'rev-parse', 'HEAD') + git(repo, 'checkout', '-q', tip) + assert scope.select('pull_request', updated_base, repository=repo)['run-heavy'] == 'false' + + +@pytest.mark.parametrize('event', ['push', 'workflow_dispatch', 'schedule', 'merge_group', None]) +def test_other_events_always_keep_full_bar(repository, event): + repo, base = repository + commit(repo, 'docs/guide.md') + decision = scope.select(event, base, repository=repo) + assert decision['run-heavy'] == 'true' + assert decision['scope-reason'] == 'event_requires_full' + + +@pytest.mark.parametrize('base', [None, '', '0' * 40, '--output=unexpected']) +def test_missing_or_invalid_comparison_falls_back_to_full(repository, base): + repo, _ = repository + commit(repo, 'docs/guide.md') + decision = scope.select('pull_request', base, repository=repo) + assert decision['run-heavy'] == 'true' + assert decision['scope-reason'] == 'comparison_unavailable' + + +def test_empty_diff_does_not_authorize_skip(repository): + repo, base = repository + assert scope.select('pull_request', base, repository=repo)['scope-reason'] == 'empty_diff' + + +@pytest.mark.parametrize('failure', [OSError('git unavailable'), subprocess.TimeoutExpired('git', 30)]) +def test_git_execution_failure_keeps_full_checks(repository, monkeypatch, failure): + repo, base = repository + def failed(*_args, **_kwargs): + raise failure + monkeypatch.setattr(scope.subprocess, 'check_output', failed) + assert scope.select('pull_request', base, repository=repo)['scope-reason'] == 'comparison_unavailable' + + +@pytest.mark.parametrize('output', [b'docs/guide.md', b'docs/invalid-\xff.md\0']) +def test_unparseable_diff_keeps_full_checks(repository, monkeypatch, output): + repo, base = repository + monkeypatch.setattr(scope.subprocess, 'check_output', lambda *_args, **_kwargs: output) + assert scope.select('pull_request', base, repository=repo)['run-heavy'] == 'true' + + +def test_real_selector_outputs_drive_real_aggregate(repository, tmp_path): + repo, base = repository + commit(repo, 'docs/guide.md') + output, summary = tmp_path / 'outputs', tmp_path / 'summary' + env = {**os.environ, 'GITHUB_EVENT_NAME': 'pull_request', 'PR_BASE_SHA': base, + 'GITHUB_OUTPUT': str(output), 'GITHUB_STEP_SUMMARY': str(summary), 'PYTHONIOENCODING': 'utf-8'} + selected = subprocess.run([sys.executable, str(SCRIPT)], cwd=repo, env=env, + capture_output=True, text=True, encoding='utf-8', check=True) + decision = dict(line.split('=', 1) for line in output.read_text(encoding='utf-8').splitlines()) + assert decision == json.loads(selected.stdout) + results = {'static': {'result': 'success', 'outputs': decision}, + **{lane: {'result': 'skipped'} for lane in ['python', 'frontend', 'browser']}} + aggregated = subprocess.run([sys.executable, str(ROOT / 'scripts/ci/summarize_checks.py')], + env={**env, 'CHECK_RESULTS': json.dumps(results), 'STATIC_ENABLED': 'true'}, + capture_output=True, text=True, encoding='utf-8') + assert aggregated.returncode == 0, aggregated.stderr + assert 'Documentation-only PR' in summary.read_text(encoding='utf-8') + + +def test_workflow_wires_every_heavy_lane_to_successful_static_scope(): + jobs = yaml.safe_load((ROOT / '.github/workflows/release-checks.yml').read_text(encoding='utf-8'))['jobs'] + assert jobs['static']['steps'][-1]['id'] == 'scope' + assert jobs['static']['steps'][-1]['run'] == 'python scripts/ci/select_checks.py' + assert set(jobs['static']['outputs']) == {'run-heavy', 'scope-reason', 'changed-files'} + for lane in ['python', 'frontend', 'browser']: + assert jobs[lane]['needs'] == 'static' + assert "needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false'" in jobs[lane]['if'] + assert "!inputs.static-checks && needs.static.result == 'skipped'" in jobs[lane]['if'] + assert jobs['checks']['if'] == 'always()' + assert set(jobs['checks']['needs']) == {'static', 'python', 'frontend', 'browser'} diff --git a/tests/test_ci_summary.py b/tests/test_ci_summary.py index 28f3e2fc..c2c55f10 100644 --- a/tests/test_ci_summary.py +++ b/tests/test_ci_summary.py @@ -12,13 +12,15 @@ SCRIPT = Path(__file__).resolve().parents[1] / 'scripts/ci/summarize_checks.py' -def run_summary(tmp_path, statuses, enabled=True): +def run_summary(tmp_path, statuses, enabled=True, *, scope=None, event='pull_request'): summary = tmp_path / 'summary.md' + results = {lane: {'result': status} for lane, status in statuses.items()} + if scope is not None: + results['static']['outputs'] = scope result = subprocess.run( [sys.executable, str(SCRIPT)], - env={**os.environ, 'CHECK_RESULTS': json.dumps({ - lane: {'result': status} for lane, status in statuses.items() - }), 'STATIC_ENABLED': json.dumps(enabled), 'GITHUB_STEP_SUMMARY': str(summary), + env={**os.environ, 'CHECK_RESULTS': json.dumps(results), 'GITHUB_EVENT_NAME': event, + 'STATIC_ENABLED': json.dumps(enabled), 'GITHUB_STEP_SUMMARY': str(summary), 'PYTHONIOENCODING': 'utf-8'}, capture_output=True, text=True, encoding='utf-8', timeout=10, ) @@ -64,3 +66,51 @@ def test_missing_receipt_fails_closed(tmp_path, missing): del statuses[missing] result, _ = run_summary(tmp_path, statuses) assert result.returncode != 0 + + +DOC_SCOPE = {'run-heavy': 'false', 'scope-reason': 'docs_only', 'changed-files': '2'} +DOC_RESULTS = {'static': 'success', 'python': 'skipped', 'frontend': 'skipped', 'browser': 'skipped'} + + +def test_proven_docs_only_skip_succeeds_and_reports_reason(tmp_path): + result, summary = run_summary(tmp_path, DOC_RESULTS, scope=DOC_SCOPE) + assert result.returncode == 0, result.stderr + text = summary.read_text(encoding='utf-8') + assert 'Documentation-only PR' in text and 'docs_only' in text + assert '| browser | skipped |' in text + + +@pytest.mark.parametrize('lane', ['static', 'python', 'frontend', 'browser']) +@pytest.mark.parametrize('status', ['failure', 'cancelled']) +def test_docs_only_never_hides_failed_or_cancelled_jobs(tmp_path, lane, status): + result, _ = run_summary(tmp_path, {**DOC_RESULTS, lane: status}, scope=DOC_SCOPE) + assert result.returncode != 0 + + +@pytest.mark.parametrize('scope', [ + {}, {'run-heavy': 'false'}, {**DOC_SCOPE, 'scope-reason': 'comparison_unavailable'}, + {**DOC_SCOPE, 'changed-files': '0'}, {**DOC_SCOPE, 'changed-files': 'unknown'}, + {**DOC_SCOPE, 'run-heavy': 'invalid'}, +]) +def test_missing_or_invalid_skip_evidence_fails_closed(tmp_path, scope): + result, _ = run_summary(tmp_path, DOC_RESULTS, scope=scope) + assert result.returncode != 0 + + +@pytest.mark.parametrize('event', ['push', 'schedule', 'workflow_dispatch', 'merge_group']) +def test_other_events_cannot_claim_docs_only_skip(tmp_path, event): + result, _ = run_summary(tmp_path, DOC_RESULTS, scope=DOC_SCOPE, event=event) + assert result.returncode != 0 + + +def test_disabled_static_cannot_authorize_heavy_skip(tmp_path): + result, _ = run_summary(tmp_path, DOC_RESULTS, enabled=False, scope=DOC_SCOPE) + assert result.returncode != 0 + + +@pytest.mark.parametrize('missing', ['static', 'python', 'frontend', 'browser']) +def test_docs_only_still_requires_every_lane_receipt(tmp_path, missing): + statuses = dict(DOC_RESULTS) + del statuses[missing] + result, _ = run_summary(tmp_path, statuses, scope=DOC_SCOPE if missing != 'static' else None) + assert result.returncode != 0