From ce481c1fb2695046b5353ea6765d94ba9671bbd5 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:15:49 +0000 Subject: [PATCH 1/5] fork-ci: docs-scope composite action (docs-only gate and per-job path scope) A composite action that says whether a CI run's change is docs-only and which configured jobs it reaches. The rules (docs globs, docs a build reads, per-job paths, paths listed in a JSON registry) are a config read from the base commit; the code runs from the action's folder at the caller's pinned SHA, so a pull request cannot loosen what judges it. Anything unclear means a full run, and every skip prints why. fork-ci-tests.cjs now also finds tests under fork-ci/. Co-Authored-By: Claude Opus 5.5 --- .github/fork-ci-tests.txt | 3 +- .github/scripts/fork-ci-tests.cjs | 11 +- .github/scripts/fork-ci-tests.test.cjs | 6 +- .github/workflows/fork-tests.yml | 4 +- fork-ci/actions/docs-scope/README.md | 124 ++++++ fork-ci/actions/docs-scope/action.yml | 39 ++ fork-ci/actions/docs-scope/docs-scope.test.py | 387 ++++++++++++++++++ fork-ci/actions/docs-scope/docs_scope.py | 254 ++++++++++++ 8 files changed, 821 insertions(+), 7 deletions(-) create mode 100644 fork-ci/actions/docs-scope/README.md create mode 100644 fork-ci/actions/docs-scope/action.yml create mode 100644 fork-ci/actions/docs-scope/docs-scope.test.py create mode 100644 fork-ci/actions/docs-scope/docs_scope.py diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index 76cefd07c8701..703a769df63d0 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -1,4 +1,4 @@ -# Every test file under .github/scripts (*.test.*, subdirectories included) and +# Every test file under .github/scripts and fork-ci (*.test.*, subdirectories included) and # where it runs (.github/scripts/fork-ci-tests.cjs checks this list). # run by the workflows job, by extension (sh, py, cjs, mjs, js) # run by run by , which must name the test's path (not one @@ -15,6 +15,7 @@ .github/scripts/fork-test-shards.test.cjs .github/scripts/fork-tests-drift.test.cjs .github/scripts/fork-workflow-triggers.test.cjs +fork-ci/actions/docs-scope/docs-scope.test.py # Upstream's tests, run where fork-tests.yml follows upstream's ci.yml. .github/scripts/check-nightly-release.test.cjs run by .github/workflows/fork-tests.yml diff --git a/.github/scripts/fork-ci-tests.cjs b/.github/scripts/fork-ci-tests.cjs index 2bca87ed6b6eb..c30d0ec004076 100644 --- a/.github/scripts/fork-ci-tests.cjs +++ b/.github/scripts/fork-ci-tests.cjs @@ -1,4 +1,4 @@ -// Fork only: every `*.test.*` under .github/scripts must be listed in .github/fork-ci-tests.txt. +// Fork only: every `*.test.*` under .github/scripts and fork-ci must be listed in .github/fork-ci-tests.txt. // A plain entry runs here by its extension (RUNNER); ` run by ` is run by that file, // which must name the test and cannot be a (disabled) upstream workflow. Unlisted or runner-less // tests fail; a listed test that is gone fails once the tested history had it, a note before. @@ -8,7 +8,7 @@ const path = require("node:path"); const ROOT = path.resolve(__dirname, "../.."); const LIST = ".github/fork-ci-tests.txt"; -const SCRIPTS = ".github/scripts"; +const TEST_DIRS = [".github/scripts", "fork-ci"]; const TEST_FILE = /\.test\.([^./]+)$/; const RUNNER = { sh: ["bash"], @@ -113,7 +113,10 @@ function readFile(file) { function main() { const entries = readList(fs.readFileSync(path.join(ROOT, LIST), "utf8")); - const result = plan(entries, findTests(SCRIPTS), everInHistory, readFile); + const present = TEST_DIRS.filter((dir) => fs.existsSync(path.join(ROOT, dir))).flatMap((dir) => + findTests(dir), + ); + const result = plan(entries, present, everInHistory, readFile); const rows = []; let failed = result.unlisted.length + result.deleted.length + result.noRunner.length + result.notRun.length; @@ -167,6 +170,6 @@ function main() { if (failed) process.exitCode = 1; } -module.exports = { plan, readList, findTests }; +module.exports = { plan, readList, findTests, TEST_DIRS }; if (require.main === module) main(); diff --git a/.github/scripts/fork-ci-tests.test.cjs b/.github/scripts/fork-ci-tests.test.cjs index 28c72efa155b6..15ded173bf97b 100644 --- a/.github/scripts/fork-ci-tests.test.cjs +++ b/.github/scripts/fork-ci-tests.test.cjs @@ -4,7 +4,7 @@ const os = require("node:os"); const path = require("node:path"); const test = require("node:test"); -const { plan, readList, findTests } = require("./fork-ci-tests.cjs"); +const { plan, readList, findTests, TEST_DIRS } = require("./fork-ci-tests.cjs"); const never = () => false; const here = (...files) => files.map((file) => ({ file, runBy: null })); @@ -96,3 +96,7 @@ test("finds every *.test.* file, subdirectories included", () => { fs.rmSync(root, { recursive: true, force: true }); } }); + +test("the composite actions' tests under fork-ci are found too", () => { + assert.deepEqual(TEST_DIRS, [".github/scripts", "fork-ci"]); +}); diff --git a/.github/workflows/fork-tests.yml b/.github/workflows/fork-tests.yml index 72e5e25e1a1a7..cb7b1ad104668 100644 --- a/.github/workflows/fork-tests.yml +++ b/.github/workflows/fork-tests.yml @@ -176,12 +176,14 @@ jobs: timeout-minutes: 5 steps: # scripts/: some tests are run by a script there (.github/fork-ci-tests.txt). + # fork-ci/: the composite actions and their tests. - name: Checkout uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 with: ref: ${{ needs.changes.outputs.sha }} sparse-checkout: | /.github/ + /fork-ci/ /scripts/ sparse-checkout-cone-mode: false @@ -199,7 +201,7 @@ jobs: tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" actionlint "$RUNNER_TEMP/actionlint" -color .github/workflows/fork-*.yml - # Every test under .github/scripts, checked against .github/fork-ci-tests.txt: + # Every test under .github/scripts and fork-ci, checked against .github/fork-ci-tests.txt: # the fork's tests run here, the others must be named by the job or script # that runs them. An unlisted test, or a listed one deleted from history, # fails; a listed one whose pull request has not merged yet is a note. diff --git a/fork-ci/actions/docs-scope/README.md b/fork-ci/actions/docs-scope/README.md new file mode 100644 index 0000000000000..4ddb3484adc7a --- /dev/null +++ b/fork-ci/actions/docs-scope/README.md @@ -0,0 +1,124 @@ +# docs-scope + +A composite action that answers two questions about the change a CI run tests: + +- **Is it docs-only?** Then the build and test jobs can pass at once. +- **Which jobs does it reach?** A job runs only when a changed file that is not docs matches its paths. + +It is the general half of a docs-only gate. The project half (which files are docs, which docs a build or test +reads, which folders each job builds) is a JSON config in the calling repository. + +## Usage + +Pin the action by full SHA (the tagged one, so a rebase of this fork cannot orphan it): + +```yaml +jobs: + build: + steps: + - uses: actions/checkout@ # pull_request: GitHub's merge commit, refs/pull/N/merge + with: { fetch-depth: 0 } # the merge base must be there + - id: scope + uses: scuttletoby/t3code/fork-ci/actions/docs-scope@ # ci/vN + with: + config: .github/docs-scope.json # default + base: ${{ github.event_name == 'push' && github.event.before || '' }} # optional, see below + - if: steps.scope.outputs.docs_only != 'true' + run: ./gradlew build + - if: fromJSON(steps.scope.outputs.jobs).engine != 'false' + run: ./gradlew :engine:test +``` + +Always test `!= 'true'` and `!= 'false'`, never `== 'false'` or `== 'true'`: a missing or empty output then means +"run". `jobs` is `{}` when the change or the config is unknown, so every job reads as "run". + +### Outputs + +| Output | Value | +| ----------- | -------------------------------------------------------------------------- | +| `docs_only` | `true` only when every changed file is docs and the event may be docs-only | +| `jobs` | JSON `{"": "true" \| "false"}`; `{}` when unknown | +| `reason` | one line: why (every skip and every full run says why) | + +The step log also prints one line per job: `job engine: run (engine/A.java matches its paths)` or +`job engine: skip (...)`. + +## What "the change" is + +- **pull_request:** the union of two diffs without rename detection (a rename is its old and its new path): + merge base .. PR head (every push of the PR together, never the last push alone) and base .. GitHub's merge commit. + HEAD must be that merge commit. +- **Any other event** (push, merge_group, workflow_dispatch): `base` .. HEAD, only when the caller gives `base`. + Without it the run is a full run. Such an event is docs-only only when `docs_only_events` names it; its `jobs` are + read either way, so a docs-only push to main can still skip the build jobs. + +## Config + +```json +{ + "docs": ["**/*.md"], + "never_docs": [ + { "glob": "**/src/**", "why": "inside a source set (packed into jars)" }, + { "glob": "**/tests/**", "why": "inside a test folder" }, + { "glob": "tools/CLAIMS.md", "why": "read by the release tool" } + ], + "never_docs_from": [ + { + "file": "tools/modules.json", + "list": "modules", + "field": "inputs", + "label": "id", + "why": "a module input" + } + ], + "docs_only_events": ["pull_request"], + "jobs": { + "engine": { + "paths": ["engine/**", "shared/items/**"], + "paths_from": [ + { + "file": "tools/modules.json", + "list": "modules", + "where": { "kind": "engine-module" }, + "field": ["paths", "inputs"], + "label": "id" + } + ] + } + } +} +``` + +- `docs` (required): globs of docs files. `**/` is any number of folders, `**` anything, `*` and `?` stay in one name. +- `never_docs`: files that match `docs` but that a build, test or tool reads; each says why. +- `never_docs_from` / `paths_from`: paths listed in a JSON file of the repository. `list` is a dotted key to a list + of objects (none: the file itself), `where` keeps the objects whose keys equal these values, `field` names the key + (or keys) holding a path or a list of paths, `label` names an object in the log. An entry matches a path exactly or + as a folder. The file is read at the base and at the head; an entry at either counts, so a pull request cannot + free a file by removing it from the list. +- `docs_only_events`: events that may be docs-only (default `["pull_request"]`). +- `jobs`: per job, `paths` globs and `paths_from` lists. Docs files never run a job; a `never_docs` file does. + +Unknown keys are an error (a typo such as `never_doc` must not drop a rule quietly), and an error means a full run. + +## Why a pull request cannot loosen it + +- The script runs from the action's own folder, at the SHA the caller pins: never a copy from the checkout. +- The config is read from the base commit with `git show`, never from the working tree. A pull request that changes + the config is a full run (the config file is never docs). + +What it cannot stop: a `pull_request` run uses the workflow file from the pull request, so a pull request that edits +the `uses:` line chooses the code that judges it. That edit is a change to a non-docs file, so every correct version +runs in full for it; pin only SHAs that this fork's CI tested and tagged. + +## Fails closed + +A full run (and `jobs` = `{}`) for: an event without a base, a pull_request HEAD that is not a two-parent merge +commit, no merge base (shallow checkout), a base that is not a commit, a git error, an empty change, no config at +the base, a config that does not parse or has unknown keys, a `*_from` file at neither side or not readable as +configured. A symlink or submodule is never docs. A crash fails the step, so the job is red. + +## Tests + +`docs-scope.test.py` builds real git repositories with GitHub-style merge commits. It runs in the fork's CI +(`.github/fork-ci-tests.txt`): `python3 fork-ci/actions/docs-scope/docs-scope.test.py`. diff --git a/fork-ci/actions/docs-scope/action.yml b/fork-ci/actions/docs-scope/action.yml new file mode 100644 index 0000000000000..0b44c944084c6 --- /dev/null +++ b/fork-ci/actions/docs-scope/action.yml @@ -0,0 +1,39 @@ +name: docs-scope +description: >- + Is this change docs-only, and which configured jobs does it reach? Reads its rules from the base + commit and runs its own code at the pinned SHA, so a pull request cannot loosen what judges it. + Anything unclear means a full run. Usage: README.md next to this file. +inputs: + config: + description: The JSON config, a path in the repository; read at the base commit, never from the checkout. + required: false + default: .github/docs-scope.json + base: + description: >- + Events other than pull_request only: the commit to compare HEAD with (for example the last + main commit whose run passed). Empty: such runs run in full. + required: false + default: "" +outputs: + docs_only: + description: "'true' only when every changed file is docs and the event may be docs-only; test != 'true'." + value: ${{ steps.scope.outputs.docs_only }} + jobs: + description: >- + JSON {"": "true"|"false"}; {} when the change or the config is unknown. Read a job as + fromJSON(steps..outputs.jobs). != 'false', so a missing job runs. + value: ${{ steps.scope.outputs.jobs }} + reason: + description: One line saying why. + value: ${{ steps.scope.outputs.reason }} +runs: + using: composite + steps: + # Only code from this action's folder (the caller's pinned SHA) runs; nothing from the checkout. + - id: scope + shell: bash + env: + CONFIG: ${{ inputs.config }} + BASE: ${{ inputs.base }} + EVENT: ${{ github.event_name }} + run: python3 -I "$GITHUB_ACTION_PATH/docs_scope.py" --config "$CONFIG" --event "$EVENT" --base "$BASE" diff --git a/fork-ci/actions/docs-scope/docs-scope.test.py b/fork-ci/actions/docs-scope/docs-scope.test.py new file mode 100644 index 0000000000000..666121de31c2b --- /dev/null +++ b/fork-ci/actions/docs-scope/docs-scope.test.py @@ -0,0 +1,387 @@ +"""docs_scope.py: a docs-only change builds and tests nothing; jobs run only for the files that reach them. +Real git repos: GitHub's refs/pull/N/merge is a merge commit (HEAD^1 = the base, HEAD^2 = the PR head), built here +with `git merge --no-ff`. Anything unclear must mean a full run. +Run: python3 fork-ci/actions/docs-scope/docs-scope.test.py +""" +import json, os, re, shutil, subprocess, sys, tempfile, unittest + +sys.dont_write_bytecode = True # the Globs test imports docs_scope.py: leave no __pycache__ in the action folder + +HERE = os.path.dirname(os.path.abspath(__file__)) +SCRIPT = os.path.join(HERE, 'docs_scope.py') +ACTION = os.path.join(HERE, 'action.yml') +CONFIG_PATH = '.github/docs-scope.json' +ENV = {'GIT_AUTHOR_NAME': 't', 'GIT_AUTHOR_EMAIL': 't@t', 'GIT_COMMITTER_NAME': 't', 'GIT_COMMITTER_EMAIL': 't@t', + 'GIT_CONFIG_GLOBAL': os.devnull, 'GIT_CONFIG_NOSYSTEM': '1'} +REGISTRY_PATH = 'tools/registry.json' +REGISTRY = {'modules': [ + {'id': 'site', 'kind': 'plugin', 'inputs': ['net/site/README.md']}, + {'id': 'content-locale', 'kind': 'engine-module', 'inputs': ['plugins/locale/common/src/main/java/Wire.java']}, + {'id': 'content-travel', 'kind': 'engine-module', 'inputs': ['plugins/travel/common/src/main/java']}, +]} +# A project's rules, as a caller would write them (the general half of a docs-only gate). +CONFIG = { + 'docs': ['**/*.md'], + 'never_docs': [ + {'glob': 'src/**', 'why': 'inside a source set'}, + {'glob': '**/src/**', 'why': 'inside a source set'}, + {'glob': 'resources/**', 'why': 'inside a resources folder'}, + {'glob': '**/resources/**', 'why': 'inside a resources folder'}, + {'glob': '**/tests/**', 'why': 'inside a test folder'}, + {'glob': '**/test/**', 'why': 'inside a test folder'}, + {'glob': '**/fixtures/**', 'why': 'inside a fixture folder'}, + {'glob': 'skills/review/SKILL.md', 'why': 'read by a tooling test'}, + {'glob': 'plugins/RELEASE-CLAIMS.md', 'why': 'read by the release tool'}, + ], + 'never_docs_from': [{'file': REGISTRY_PATH, 'list': 'modules', 'field': 'inputs', 'label': 'id', + 'why': 'listed in the registry'}], + 'jobs': { + 'plugins': {'paths': ['plugins/**']}, + 'engine': {'paths': ['engine/**', 'plugins/items/**'], + 'paths_from': [{'file': REGISTRY_PATH, 'list': 'modules', 'where': {'kind': 'engine-module'}, + 'field': 'inputs', 'label': 'id'}]}, + }, +} + + +class Repo(unittest.TestCase): + config = CONFIG + + def setUp(self): + self.d = tempfile.mkdtemp(prefix='docs-scope-') + self.addCleanup(shutil.rmtree, self.d, True) + self.git('init', '-q', '-b', 'main') + self.write({'README.md': 'x', 'app/Main.java': 'class Main {}', REGISTRY_PATH: json.dumps(REGISTRY), + CONFIG_PATH: json.dumps(self.config)}) + self.base = self.commit('base') + + def git(self, *a): + r = subprocess.run(['git', *a], cwd=self.d, text=True, capture_output=True, env={**os.environ, **ENV}) + if r.returncode: + raise RuntimeError(f'git {a}: {r.stderr}') + return r.stdout.strip() + + def write(self, files): + for path, text in files.items(): + full = os.path.join(self.d, path) + if text is None: + os.remove(full) + continue + os.makedirs(os.path.dirname(full), exist_ok=True) + with open(full, 'w') as f: + f.write(text) + + def commit(self, msg='c', files=None): + if files: + self.write(files) + self.git('add', '-A') + self.git('commit', '-q', '--allow-empty', '-m', msg) + return self.git('rev-parse', 'HEAD') + + def pr(self, *pushes, main_after=None): + """The PR branch gets one commit per push ({path: text, None = delete}); main may move on; then GitHub's + merge commit (main + PR head) is checked out.""" + self.git('checkout', '-q', '-b', 'pr', self.base) + for files in pushes: + self.commit('push', files) + self.git('checkout', '-q', 'main') + if main_after: + self.commit('main moved', main_after) + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') + + def scope(self, event='pull_request', base=''): + """(docs_only, jobs, stdout).""" + out = os.path.join(self.d, '.output') + r = subprocess.run([sys.executable, '-I', SCRIPT, '--config', CONFIG_PATH, '--event', event, '--base', base], + cwd=self.d, text=True, capture_output=True, env={**os.environ, **ENV, 'GITHUB_OUTPUT': out}) + self.assertEqual(r.returncode, 0, r.stderr) + with open(out) as f: + written = f.read() + os.remove(out) + m = re.fullmatch(r'docs_only=(true|false)\njobs=(\{.*\})\nreason=([^\n]+)\n', written) + self.assertTrue(m, written) + self.assertEqual(r.stdout.startswith('docs-only: '), m[1] == 'true', r.stdout) + self.assertEqual(m[3], r.stdout.splitlines()[0]) + return m[1] == 'true', json.loads(m[2]), r.stdout + + def assertDocsOnly(self, expected): + docs, _, out = self.scope() + self.assertEqual(docs, expected, out) + return out + + +class DocsOnly(Repo): + def test_only_md_files_is_docs_only(self): + self.pr({'README.md': 'y', 'docs/guide.md': 'new'}) + self.assertDocsOnly(True) + + def test_md_and_code_is_a_full_run(self): + self.pr({'README.md': 'y', 'app/Main.java': 'class Main { int x; }'}) + self.assertDocsOnly(False) + + def test_main_moving_on_with_code_does_not_count_against_the_pr(self): # base..merge = the PR's change only + self.pr({'README.md': 'y'}, main_after={'app/Main.java': 'class Main { int y; }'}) + self.assertDocsOnly(True) + + +class EveryPushCounts(Repo): + def test_a_code_push_then_a_docs_push_is_a_full_run(self): # never the last push alone + self.pr({'app/Util.java': 'class Util {}'}, {'README.md': 'y'}) + self.assertDocsOnly(False) + + def test_code_added_and_removed_again_leaves_a_docs_only_change(self): # the whole change is what merges + self.pr({'app/Util.java': 'class Util {}'}, {'app/Util.java': None, 'README.md': 'y'}) + self.assertDocsOnly(True) + + def test_a_rename_from_java_to_md_is_a_full_run(self): # --no-renames: the deleted .java is listed + self.pr({'app/Main.java': None, 'app/Main.md': 'class Main {}'}) + self.assertIn('app/Main.java', self.assertDocsOnly(False)) + + def test_a_code_change_main_already_has_still_counts(self): # base..merge misses it; merge base..PR head has it + same = {'app/Main.java': 'class Main { int same; }'} + self.pr({**same, 'README.md': 'y'}, main_after=same) + self.assertDocsOnly(False) + + +class BuildAndTestInputs(Repo): + def check(self, path): + self.pr({path: 'doc'}) + self.assertIn('build or test input', self.assertDocsOnly(False), path) + + def test_md_in_a_source_set(self): + self.check('plugins/x/src/main/resources/help.md') + + def test_md_in_a_top_level_source_set(self): + self.check('src/help.md') + + def test_md_in_a_resources_folder(self): + self.check('net/resources/motd.md') + + def test_md_in_a_test_folder(self): + self.check('net/testing/livelike/tests/fixture.md') + + def test_md_in_a_fixtures_folder(self): + self.check('x/fixtures/case.md') + + def test_a_named_file_read_by_a_test(self): + self.check('skills/review/SKILL.md') + + def test_a_named_file_read_by_a_tool(self): + self.check('plugins/RELEASE-CLAIMS.md') + + def test_an_md_listed_in_the_registry(self): + self.check('net/site/README.md') + + def test_an_md_newly_listed_in_the_registry_by_main(self): # read at the base too, not only the head + self.pr({'docs/new.md': 'doc'}, main_after={REGISTRY_PATH: json.dumps( + {'modules': [{'id': 'docs-site', 'inputs': ['docs/']}]})}) + self.assertDocsOnly(False) + + def test_a_pr_that_drops_a_registry_input_does_not_free_it(self): # the base's entry still counts + self.pr({REGISTRY_PATH: json.dumps({'modules': []}), 'net/site/README.md': 'y'}) + self.assertDocsOnly(False) + + +class FailsClosed(Repo): + def test_events_without_a_base_are_full_runs(self): + self.pr({'README.md': 'y'}) + for event in ('push', 'workflow_dispatch', ''): + docs, jobs, out = self.scope(event) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('without a base', out) + + def test_a_head_that_is_not_a_merge_commit(self): + self.commit('docs on main', {'README.md': 'y'}) + self.assertIn('not a two-parent merge commit', self.assertDocsOnly(False)) + + def test_no_merge_base(self): + self.git('checkout', '-q', '--orphan', 'pr') + self.git('rm', '-rqf', '.') + self.commit('unrelated', {'README.md': 'z'}) + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '--allow-unrelated-histories', '-X', 'theirs', '-m', 'merge', 'pr') + self.assertIn('no merge base', self.assertDocsOnly(False)) + + def test_an_empty_change(self): + self.pr({}) + self.assertIn('touches no file', self.assertDocsOnly(False)) + + def test_an_md_symlink(self): + self.git('checkout', '-q', '-b', 'pr') + os.symlink('app/Main.java', os.path.join(self.d, 'link.md')) + self.commit('symlink') + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') + self.assertIn('symlink', self.assertDocsOnly(False)) + + def test_a_registry_at_neither_side(self): + self.git('checkout', '-q', '-b', 'pr2', self.base) + self.git('rm', '-q', REGISTRY_PATH) + main = self.commit('no registry on this side branch') + self.git('checkout', '-q', '-b', 'pr3', main) + self.commit('docs', {'README.md': 'w'}) + self.git('checkout', '-q', 'pr2') + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr3') + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('neither the base nor the head', out) + + def test_a_registry_that_does_not_parse_as_configured(self): + self.pr({'README.md': 'y'}, main_after={REGISTRY_PATH: json.dumps({'mods': []})}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('cannot be read as configured', out) + + +class ConfigAtTheBase(Repo): + """The rules come from the base commit and the code from the action's pinned folder, so a pull request cannot + loosen what judges it (the general half of a gate that ran the PR's own copy).""" + + def test_a_pr_that_loosens_its_own_config_still_runs_in_full(self): + self.pr({CONFIG_PATH: json.dumps({'docs': ['**'], 'jobs': {}}), 'engine/A.java': 'class A {}'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'false', 'engine': 'true'}), out) # the base's jobs + + def test_no_config_at_the_base(self): # the PR that adds the config runs in full + self.git('rm', '-q', CONFIG_PATH) + self.base = self.commit('no config') + self.pr({'README.md': 'y', CONFIG_PATH: json.dumps(CONFIG)}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('no config', out) + + def test_a_bad_config_at_the_base(self): + for bad in ('{', '[]', json.dumps({'docs': ['**/*.md'], 'never_doc': []}), # a typo drops no rule quietly + json.dumps({'never_docs': []}), json.dumps({'docs': '**/*.md'}), + json.dumps({'docs': ['*.md'], 'never_docs': [{'glob': 'x'}]}), + json.dumps({'docs': ['*.md'], 'never_docs_from': [{'file': 'r.json', 'field': 'f'}]}), + json.dumps({'docs': ['*.md'], 'jobs': {'j': {'path': ['x/**']}}})): + with self.subTest(bad=bad): + self.git('checkout', '-q', 'main') + self.git('reset', '-q', '--hard', self.base) + self.git('branch', '-q', '-D', 'pr') if self.git('branch', '--list', 'pr') else None + self.commit('bad config', {CONFIG_PATH: bad}) + self.git('checkout', '-q', '-b', 'pr') + self.commit('docs', {'README.md': bad}) + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('config', out) + + +class LooseConfig(Repo): + config = {'docs': ['**']} # everything is docs, except the config itself + + def test_the_config_file_is_never_docs(self): + self.pr({CONFIG_PATH: json.dumps({'docs': ['**'], 'jobs': {}})}) + self.assertIn('the docs-scope config', self.assertDocsOnly(False)) + + +class Jobs(Repo): + def test_a_job_runs_for_its_paths_and_skips_otherwise(self): + self.pr({'plugins/a/src/main/java/A.java': 'class A {}'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'false'}), out) + self.assertIn('job engine: skip', out) + + def test_docs_in_a_job_folder_do_not_run_it(self): # code elsewhere makes it a full run, not an engine build + self.pr({'engine/README.md': 'y', 'app/Main.java': 'class Main { int x; }'}) + self.assertEqual(self.scope()[1], {'plugins': 'false', 'engine': 'false'}) + + def test_an_md_input_in_a_job_folder_runs_it(self): + self.pr({'engine/core/src/main/resources/help.md': 'y'}) + self.assertEqual(self.scope()[1]['engine'], 'true') + + def test_docs_only_skips_every_job(self): + self.pr({'README.md': 'y'}) + self.assertEqual(self.scope()[:2], (True, {'plugins': 'false', 'engine': 'false'})) + + def test_a_folder_added_to_a_jobs_paths_runs_it(self): # a shared folder another job builds against + self.pr({'plugins/items/common/Item.java': 'class Item {}'}) + self.assertEqual(self.scope()[1]['engine'], 'true') + + def test_a_jobs_paths_from_a_registry_filtered_by_kind(self): # the registry names what a module compiles + for path, runs in (('plugins/locale/common/src/main/java/Wire.java', 'true'), + ('plugins/locale/common/src/main/java/Other.java', 'false'), + ('plugins/travel/common/src/main/java/a/Leg.java', 'true')): + with self.subTest(path=path): + self.git('checkout', '-q', 'main') + self.git('reset', '-q', '--hard', self.base) + self.git('branch', '-q', '-D', 'pr') if self.git('branch', '--list', 'pr') else None + self.pr({path: 'class X {}'}) + docs, jobs, out = self.scope() + self.assertEqual(jobs['engine'], runs, out) + + def test_a_registry_entry_of_another_kind_does_not_run_the_job(self): + self.pr({'net/site/README.md': 'y'}) # an input of a "plugin", not of an "engine-module" + self.assertEqual(self.scope()[1]['engine'], 'false') + + +class OtherEvents(Repo): + def test_a_push_with_a_base_reads_its_jobs_and_is_never_docs_only(self): + self.commit('code', {'engine/A.java': 'class A {}'}) + docs, jobs, out = self.scope('push', self.base) + self.assertEqual((docs, jobs), (False, {'plugins': 'false', 'engine': 'true'}), out) + + def test_a_docs_push_skips_every_job_but_is_not_docs_only(self): + self.commit('docs', {'plugins/README.md': 'y'}) + docs, jobs, out = self.scope('push', self.base) + self.assertEqual((docs, jobs), (False, {'plugins': 'false', 'engine': 'false'}), out) + self.assertIn('not in docs_only_events', out) + + def test_docs_only_events_can_name_push(self): + cfg = {**CONFIG, 'docs_only_events': ['pull_request', 'push']} + self.base = self.commit('push may be docs-only', {CONFIG_PATH: json.dumps(cfg)}) + self.commit('docs', {'README.md': 'y'}) + self.assertTrue(self.scope('push', self.base)[0]) + + def test_a_base_that_is_not_a_commit(self): + self.commit('docs', {'README.md': 'y'}) + docs, jobs, out = self.scope('push', '0' * 40) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('not a commit here', out) + + +class Globs(unittest.TestCase): + def test_globs(self): + sys.path.insert(0, HERE) + try: + from docs_scope import glob_re + finally: + sys.path.remove(HERE) + for pattern, yes, no in ( + ('**/*.md', ['a.md', 'x/y/a.md'], ['a.mdx', 'a.md/b']), + ('*.md', ['a.md'], ['x/a.md']), + ('**/test/**', ['test/a', 'x/test/b/c'], ['x/tests/a', 'xtest/a']), + ('src/**', ['src/a', 'src/a/b'], ['x/src/a', 'srcx/a']), + ('a?.md', ['ab.md'], ['a/.md', 'abc.md']), + ('a.b+c', ['a.b+c'], ['aXb+c'])): + for p in yes: + self.assertTrue(glob_re(pattern).match(p), (pattern, p)) + for p in no: + self.assertFalse(glob_re(pattern).match(p), (pattern, p)) + + +class Action(unittest.TestCase): + """action.yml runs only this folder's script (the caller's pinned SHA), never a file from the checkout.""" + text = open(ACTION).read() + + def test_runs_only_its_own_script(self): + runs = re.findall(r'^\s*run: (.*)$', self.text, re.M) + self.assertEqual(runs, ['python3 -I "$GITHUB_ACTION_PATH/docs_scope.py" --config "$CONFIG" ' + '--event "$EVENT" --base "$BASE"']) + self.assertNotIn('uses:', self.text) + self.assertIn('using: composite', self.text) + + def test_inputs_reach_the_script_by_env_only(self): # never ${{ }} inside run: (script injection) + run = re.search(r'^\s*run: (.*)$', self.text, re.M)[1] + self.assertNotIn('${{', run) + + def test_declares_every_output_the_script_writes(self): + for name in ('docs_only', 'jobs', 'reason'): + self.assertIn(f'value: ${{{{ steps.scope.outputs.{name} }}}}', self.text) + + +if __name__ == '__main__': + unittest.main(verbosity=1) diff --git a/fork-ci/actions/docs-scope/docs_scope.py b/fork-ci/actions/docs-scope/docs_scope.py new file mode 100644 index 0000000000000..b602045fa7649 --- /dev/null +++ b/fork-ci/actions/docs-scope/docs_scope.py @@ -0,0 +1,254 @@ +#!/usr/bin/env python3 +"""docs-scope: is this change docs-only, and which of the configured jobs does it reach? + +The change: + - pull_request: the union of two diffs, both without rename detection (a rename lists its old and its new path): + merge base of the base and the PR head .. the PR head (every push together, never the last one alone), and + base .. GitHub's merge commit (what merging changes on the base it was tested with). HEAD must be GitHub's merge + commit (refs/pull/N/merge): HEAD^1 is the base, HEAD^2 the PR head. + - any other event: --base .. HEAD, only when the caller gives --base (for example the last main commit that passed). + +A path is docs when it is a plain file (no symlink or submodule), matches a `docs` glob, is not the config file, and +matches no `never_docs` glob or `never_docs_from` entry. The change is docs-only when every path is docs and the event +is in `docs_only_events`. A job runs when a path that is not docs matches its `paths` or `paths_from`. + +The config is read from the BASE commit, never from the checkout, and this script runs from the action's own folder +at the caller's pinned SHA: a pull request cannot loosen the rules or the code that judge it. `*_from` files are read +at the base and the head; an entry at either counts. + +Fails closed: anything unclear means docs_only=false and every job runs, with the reason printed. Jobs missing from +the `jobs` output (config unreadable) must be read as "run": callers test `!= 'false'`. + + python3 -I docs_scope.py --config .github/docs-scope.json --event "$GITHUB_EVENT_NAME" [--base SHA] +Writes docs_only=true|false, jobs= and reason= to $GITHUB_OUTPUT. +""" +import argparse, json, os, re, subprocess, sys + +PLAIN_MODES = ('100644', '100755', '000000') # a regular file, or (000000) the side where it does not exist +KEYS = {'docs', 'never_docs', 'never_docs_from', 'docs_only_events', 'jobs'} +SOURCE_KEYS = {'file', 'list', 'where', 'field', 'label', 'why'} + + +class Unclear(Exception): + """Anything that makes the answer unknown: the run is full and this is the reason.""" + + +def git(*args): + """stdout, or None when git fails.""" + r = subprocess.run(['git', *args], capture_output=True, text=True) + return r.stdout if r.returncode == 0 else None + + +def glob_re(pattern): + """A glob from the repository root: `**/` is any number of folders (none too), `**` anything, `*` and `?` stay + inside one name.""" + i, out = 0, [] + while i < len(pattern): + if pattern.startswith('**/', i): + out.append('(?:[^/]+/)*'); i += 3 + elif pattern.startswith('**', i): + out.append('.*'); i += 2 + elif pattern[i] in '*?': + out.append('[^/]*' if pattern[i] == '*' else '[^/]'); i += 1 + else: + out.append(re.escape(pattern[i])); i += 1 + return re.compile(''.join(out) + r'\Z') + + +def changes(a, b, run=git): + """[(path, old mode, new mode)] between commits a and b, renames as delete + add; None on a git error.""" + out = run('diff', '--raw', '--no-renames', '--no-abbrev', '-z', a, b) + if out is None: + return None + parts, rows = out.split('\0'), [] + for i in range(0, len(parts) - 1, 2): + meta, path = parts[i], parts[i + 1] + if not meta.startswith(':'): + return None # not the format we expect: say "unclear" + fields = meta[1:].split() + rows.append((path, fields[0], fields[1])) + return rows + + +def the_change(event, head, base, run=git): + """(rows, the commit the config is read at, what was compared); Unclear when the change is unknown.""" + if event == 'pull_request': + line = (run('rev-list', '--parents', '-n', '1', head) or '').split() + if len(line) != 3: + raise Unclear(f"{head} is not a two-parent merge commit (GitHub's refs/pull/N/merge): the PR diff is unknown") + _, base, pr = line + mb = (run('merge-base', base, pr) or '').strip() + if not mb: + raise Unclear(f'no merge base between the base {base[:10]} and the PR head {pr[:10]}') + pairs, what = ((mb, pr), (base, head)), f'the merge base {mb[:10]}' + elif not base: + raise Unclear(f'a {event or "unknown"} run without a base runs in full') + else: + resolved = (run('rev-parse', '-q', '--verify', f'{base}^{{commit}}') or '').strip() + if not resolved: + raise Unclear(f'the base {base} is not a commit here (shallow checkout or force push?)') + base, pairs, what = resolved, ((resolved, head),), f'the base {resolved[:10]}' + rows = [] + for a, b in pairs: + got = changes(a, b, run) + if got is None: + raise Unclear(f'git diff {a[:10]} {b[:10]} failed') + rows += got + if not rows: + raise Unclear('the change touches no file') + return rows, base, what + + +def strings(value, where): + if not isinstance(value, list) or not all(isinstance(x, str) and x for x in value): + raise Unclear(f'config: {where} must be a list of non-empty strings') + return value + + +def sources(value, where, need_why=False): + if not isinstance(value, list) or not all(isinstance(s, dict) for s in value): + raise Unclear(f'config: {where} must be a list of objects') + for s in value: + extra = set(s) - SOURCE_KEYS + if extra or not isinstance(s.get('file'), str) or 'field' not in s or (need_why and 'why' not in s): + raise Unclear(f'config: {where} entry {json.dumps(s)[:80]} needs file and field' + f'{" and why" if need_why else ""} (and no other keys than {sorted(SOURCE_KEYS)})') + return value + + +def load_config(path, ref, run=git): + text = run('show', f'{ref}:{path}') + if text is None: + raise Unclear(f'no config {path} at the base {ref[:10]} (a PR that adds it runs in full)') + try: + c = json.loads(text) + except ValueError as e: + raise Unclear(f'config {path} at {ref[:10]} is not JSON: {e}') + if not isinstance(c, dict) or set(c) - KEYS or 'docs' not in c: + raise Unclear(f'config {path}: needs "docs", and no other keys than {sorted(KEYS)}') + strings(c['docs'], 'docs') + for i, n in enumerate(c.setdefault('never_docs', [])): + if not isinstance(n, dict) or set(n) != {'glob', 'why'}: + raise Unclear(f'config: never_docs[{i}] must be {{"glob", "why"}}') + sources(c.setdefault('never_docs_from', []), 'never_docs_from', need_why=True) + strings(c.setdefault('docs_only_events', ['pull_request']), 'docs_only_events') + jobs = c.setdefault('jobs', {}) + if not isinstance(jobs, dict): + raise Unclear('config: jobs must be an object') + for name, j in jobs.items(): + if not isinstance(j, dict) or set(j) - {'paths', 'paths_from'} or not j: + raise Unclear(f'config: jobs.{name} takes "paths" and/or "paths_from"') + strings(j.setdefault('paths', []), f'jobs.{name}.paths') + sources(j.setdefault('paths_from', []), f'jobs.{name}.paths_from') + return c + + +def read_entries(src, refs, run=git): + """{path prefix: label} of every entry the source names at any ref; Unclear if no ref has the file or one is + malformed. Entries match a path exactly or as a folder.""" + found, read = {}, False + fields = src['field'] if isinstance(src['field'], list) else [src['field']] + for ref in refs: + text = run('show', f'{ref}:{src["file"]}') + if text is None: + continue + try: + items = json.loads(text) + for key in (src.get('list') or '').split('.') if src.get('list') else []: + items = items[key] + items = items if isinstance(items, list) else [items] + for item in items: + if any(item.get(k) != v for k, v in (src.get('where') or {}).items()): + continue + label = item.get(src['label'], '?') if src.get('label') else src['file'] + for f in fields: + value = item.get(f) or [] + for x in value if isinstance(value, list) else [value]: + if not isinstance(x, str) or not x.strip('/'): + raise TypeError(f'{f}: {x!r} is not a path') + found[x.rstrip('/')] = f'{label} {f}' + except (ValueError, KeyError, IndexError, AttributeError, TypeError) as e: + raise Unclear(f'{src["file"]} at {ref[:10]} cannot be read as configured: {e}') + read = True + if not read: + raise Unclear(f'{src["file"]} is at neither the base nor the head: its entries are unknown') + return found + + +def entry_match(path, entries): + for x, label in entries.items(): + if path == x or path.startswith(x + '/'): + return x, label + return None + + +def decide(event, config_path, head='HEAD', base='', run=git): + """(docs_only, {job: 'true'|'false'}, [reason lines]); the first line is the overall reason.""" + try: + rows, cbase, what = the_change(event, head, base, run) + c = load_config(config_path, cbase, run) + refs = (cbase, head) + never_from = [(s, read_entries(s, refs, run)) for s in c['never_docs_from']] + jobs = {n: ([glob_re(g) for g in j['paths']], [read_entries(s, refs, run) for s in j['paths_from']]) + for n, j in c['jobs'].items()} + except Unclear as e: + return False, {}, [f'full run: {e}'] + docs_globs = [glob_re(g) for g in c['docs']] + never = [(glob_re(n['glob']), f'{n["why"]} ({n["glob"]})') for n in c['never_docs']] + odd = {p for p, old, new in rows if old not in PLAIN_MODES or new not in PLAIN_MODES} + not_docs = {} # path -> why it is not docs + for p in sorted({p for p, _, _ in rows}): + if p in odd: + not_docs[p] = 'a symlink or submodule, not a plain file' + elif not any(g.match(p) for g in docs_globs): + not_docs[p] = 'not a docs file' + elif p == config_path: + not_docs[p] = 'the docs-scope config' + else: + why = next((w for g, w in never if g.match(p)), None) + for s, entries in never_from: + hit = why is None and entry_match(p, entries) + if hit: + why = f'{s["why"]} ({hit[1]}: {hit[0]})' + if why: + not_docs[p] = f'a build or test input: {why}' + lines = [] + if not not_docs and event in c['docs_only_events']: + lines.append(f'docs-only: {len({p for p, _, _ in rows})} docs file(s) changed against {what}') + return True, {n: 'false' for n in jobs}, lines + [f'job {n}: skip (docs-only)' for n in jobs] + if not_docs: + first = next(iter(not_docs)) + more = f' and {len(not_docs) - 1} more' if len(not_docs) > 1 else '' + lines.append(f'full run: {first} is {not_docs[first]}{more}') + else: + lines.append(f'full run: only docs changed, but a {event or "unknown"} run is not in docs_only_events') + out = {} + for n, (globs, froms) in jobs.items(): + hit = next(((p, 'its paths') for p in not_docs if any(g.match(p) for g in globs)), None) or next( + ((p, f'{m[1]}: {m[0]}') for p in not_docs for e in froms for m in [entry_match(p, e)] if m), None) + out[n] = 'true' if hit else 'false' + lines.append(f'job {n}: run ({hit[0]} matches {hit[1]})' if hit + else f'job {n}: skip (no changed file that is not docs matches its paths)') + return False, out, lines + + +def main(argv=None, run=git): + p = argparse.ArgumentParser(description=__doc__.split('\n')[0]) + p.add_argument('--config', required=True) + p.add_argument('--event', required=True) + p.add_argument('--head', default='HEAD') + p.add_argument('--base', default='') + a = p.parse_args(argv) + docs_only, jobs, lines = decide(a.event, a.config, a.head, a.base, run) + print('\n'.join(lines)) + out = os.environ.get('GITHUB_OUTPUT') + if out: + reason = ' '.join(lines[0].split()) # one line, whatever a path holds + with open(out, 'a') as f: + f.write(f'docs_only={"true" if docs_only else "false"}\n' + f'jobs={json.dumps(jobs, separators=(",", ":"))}\nreason={reason}\n') + return 0 + + +if __name__ == '__main__': + sys.exit(main()) From 64604221d7faa954b0b54b3bbf0a749a52ab60ef Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:34:01 +0000 Subject: [PATCH 2/5] fork-ci docs-scope: verify the merge commit, never crash, fail closed on unclear lists - pull_request: HEAD must be $GITHUB_SHA and HEAD^2 the event's pull_request.head.sha before HEAD^1 is trusted as the base (a PR-head checkout that merged main in made code docs-only and read the config from the PR). Other events check $GITHUB_SHA too. - git output decoded with surrogateescape, JSON read as bytes, RecursionError caught, and main() turns any error into a full run with outputs (no crash, no missing outputs). - `**` matches across a newline; a name with a control character or non-UTF-8 bytes is never docs; printed lines escape control characters (no workflow-command injection). - *_from lists: a kept object without the field, a field no kept object has, or an entry that is not a plain path is a full run; source and never_docs value types checked. - A non-docs file no job names, or a config change, runs every job; a config path that is not plain is a full run. - README: the push base is the last green commit, never github.event.before (why). - fork-ci-tests: presentTests() and a real test of the fork-ci folder scan. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/fork-ci-tests.cjs | 15 +- .github/scripts/fork-ci-tests.test.cjs | 18 +- fork-ci/actions/docs-scope/README.md | 67 ++++- fork-ci/actions/docs-scope/action.yml | 8 +- fork-ci/actions/docs-scope/docs-scope.test.py | 275 +++++++++++++++--- fork-ci/actions/docs-scope/docs_scope.py | 154 +++++++--- 6 files changed, 431 insertions(+), 106 deletions(-) diff --git a/.github/scripts/fork-ci-tests.cjs b/.github/scripts/fork-ci-tests.cjs index c30d0ec004076..f3de52e0bd593 100644 --- a/.github/scripts/fork-ci-tests.cjs +++ b/.github/scripts/fork-ci-tests.cjs @@ -83,6 +83,14 @@ function findTests(dir, root = ROOT) { return out.toSorted(); } +// Every test file under TEST_DIRS. A folder that is not there adds none: a listed test in it is then +// missing, which plan() reports (a failure once the tested history had it). +function presentTests(root = ROOT) { + return TEST_DIRS.filter((dir) => fs.existsSync(path.join(root, dir))).flatMap((dir) => + findTests(dir, root), + ); +} + function git(args) { return childProcess.execFileSync("git", args, { cwd: ROOT, encoding: "utf8" }).trim(); } @@ -113,10 +121,7 @@ function readFile(file) { function main() { const entries = readList(fs.readFileSync(path.join(ROOT, LIST), "utf8")); - const present = TEST_DIRS.filter((dir) => fs.existsSync(path.join(ROOT, dir))).flatMap((dir) => - findTests(dir), - ); - const result = plan(entries, present, everInHistory, readFile); + const result = plan(entries, presentTests(), everInHistory, readFile); const rows = []; let failed = result.unlisted.length + result.deleted.length + result.noRunner.length + result.notRun.length; @@ -170,6 +175,6 @@ function main() { if (failed) process.exitCode = 1; } -module.exports = { plan, readList, findTests, TEST_DIRS }; +module.exports = { plan, readList, findTests, presentTests }; if (require.main === module) main(); diff --git a/.github/scripts/fork-ci-tests.test.cjs b/.github/scripts/fork-ci-tests.test.cjs index 15ded173bf97b..3ce9bf2e938b0 100644 --- a/.github/scripts/fork-ci-tests.test.cjs +++ b/.github/scripts/fork-ci-tests.test.cjs @@ -4,7 +4,7 @@ const os = require("node:os"); const path = require("node:path"); const test = require("node:test"); -const { plan, readList, findTests, TEST_DIRS } = require("./fork-ci-tests.cjs"); +const { plan, readList, findTests, presentTests } = require("./fork-ci-tests.cjs"); const never = () => false; const here = (...files) => files.map((file) => ({ file, runBy: null })); @@ -97,6 +97,18 @@ test("finds every *.test.* file, subdirectories included", () => { } }); -test("the composite actions' tests under fork-ci are found too", () => { - assert.deepEqual(TEST_DIRS, [".github/scripts", "fork-ci"]); +test("the composite actions' tests under fork-ci are found too, and a missing folder adds none", () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "fork-ci-tests-")); + const files = [".github/scripts/a.test.cjs", "fork-ci/actions/x/b.test.py", "other/c.test.py"]; + try { + for (const file of files) { + fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true }); + fs.writeFileSync(path.join(root, file), ""); + } + assert.deepEqual(presentTests(root), files.slice(0, 2)); + fs.rmSync(path.join(root, "fork-ci"), { recursive: true }); + assert.deepEqual(presentTests(root), files.slice(0, 1)); + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } }); diff --git a/fork-ci/actions/docs-scope/README.md b/fork-ci/actions/docs-scope/README.md index 4ddb3484adc7a..21c0745b0c9f5 100644 --- a/fork-ci/actions/docs-scope/README.md +++ b/fork-ci/actions/docs-scope/README.md @@ -3,7 +3,8 @@ A composite action that answers two questions about the change a CI run tests: - **Is it docs-only?** Then the build and test jobs can pass at once. -- **Which jobs does it reach?** A job runs only when a changed file that is not docs matches its paths. +- **Which jobs does it reach?** A job runs when a changed file that is not docs matches its paths. A file that is + not docs but that no job names (a root build file, a workflow), or a change to the config, runs every job. It is the general half of a docs-only gate. The project half (which files are docs, which docs a build or test reads, which folders each job builds) is a JSON config in the calling repository. @@ -16,13 +17,21 @@ Pin the action by full SHA (the tagged one, so a rebase of this fork cannot orph jobs: build: steps: - - uses: actions/checkout@ # pull_request: GitHub's merge commit, refs/pull/N/merge + - uses: actions/checkout@ # the default ref: on pull_request GitHub's merge commit ($GITHUB_SHA) with: { fetch-depth: 0 } # the merge base must be there + # Optional, push only: the last commit whose run of this workflow passed (see "The base on push"). + - id: green + if: github.event_name == 'push' + env: { GH_TOKEN: "${{ github.token }}" } # needs `actions: read` + run: | + sha=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?branch=main&status=success&per_page=1" \ + --jq '.workflow_runs[0].head_sha // ""') || sha="" + echo "sha=$sha" >> "$GITHUB_OUTPUT" - id: scope uses: scuttletoby/t3code/fork-ci/actions/docs-scope@ # ci/vN with: config: .github/docs-scope.json # default - base: ${{ github.event_name == 'push' && github.event.before || '' }} # optional, see below + base: ${{ steps.green.outputs.sha }} # empty: a full run - if: steps.scope.outputs.docs_only != 'true' run: ./gradlew build - if: fromJSON(steps.scope.outputs.jobs).engine != 'false' @@ -32,6 +41,10 @@ jobs: Always test `!= 'true'` and `!= 'false'`, never `== 'false'` or `== 'true'`: a missing or empty output then means "run". `jobs` is `{}` when the change or the config is unknown, so every job reads as "run". +Run it as a step of the jobs it gates, as above. If it runs in a job of its own that others `need`, a failure of that +job skips them, and GitHub counts a skipped required job as passing: gate them with +`if: ${{ !cancelled() && (needs.scope.result != 'success' || fromJSON(needs.scope.outputs.jobs).engine != 'false') }}`. + ### Outputs | Output | Value | @@ -41,16 +54,29 @@ Always test `!= 'true'` and `!= 'false'`, never `== 'false'` or `== 'true'`: a m | `reason` | one line: why (every skip and every full run says why) | The step log also prints one line per job: `job engine: run (engine/A.java matches its paths)` or -`job engine: skip (...)`. +`job engine: skip (...)`. Control characters, line separators and bytes that are not UTF-8 in a file name are +printed escaped (`\n`, `\udcff`), so a file name can neither start a `::workflow-command::` line nor add an output. ## What "the change" is - **pull_request:** the union of two diffs without rename detection (a rename is its old and its new path): merge base .. PR head (every push of the PR together, never the last push alone) and base .. GitHub's merge commit. - HEAD must be that merge commit. -- **Any other event** (push, merge_group, workflow_dispatch): `base` .. HEAD, only when the caller gives `base`. - Without it the run is a full run. Such an event is docs-only only when `docs_only_events` names it; its `jobs` are - read either way, so a docs-only push to main can still skip the build jobs. + HEAD must be that merge commit: HEAD == `$GITHUB_SHA`, it has two parents, and HEAD^2 is the event's + `pull_request.head.sha`. Only then is HEAD^1 trusted as the base. A checkout of the PR head is a full run: if its + last commit merged main in, HEAD^1 would be the PR's own commit, the PR's code would drop out of both diffs and the + config would be read from the PR. +- **Any other event** (push, merge_group, workflow_dispatch): `base` .. HEAD, only when the caller gives `base` and + HEAD == `$GITHUB_SHA`. Without a base the run is a full run. Such an event is docs-only only when + `docs_only_events` names it; its `jobs` are read either way, so a docs-only push to main can still skip the build + jobs. + +### The base on push + +Pass the last commit whose run of the workflow **passed**, or nothing (a full run). Never `github.event.before`: if +push A (code) went red or was cancelled (for example by `concurrency`), push B (docs) diffs B against A, every job +reads `false`, and main turns green with A's code never tested; a rerun of B gives the same answer. Against the last +green commit, A's code is in the diff until a run that tests it passes. Any commit works as a base, an ancestor or +not, because the diff compares trees; one that is not in the checkout is a full run. ## Config @@ -89,17 +115,23 @@ The step log also prints one line per job: `job engine: run (engine/A.java match } ``` -- `docs` (required): globs of docs files. `**/` is any number of folders, `**` anything, `*` and `?` stay in one name. +- `docs` (required): globs of docs files. `**/` is any number of folders, `**` anything (a newline in a name too), + `*` and `?` stay in one name. A name with a control character or bytes that are not UTF-8 is never docs. - `never_docs`: files that match `docs` but that a build, test or tool reads; each says why. - `never_docs_from` / `paths_from`: paths listed in a JSON file of the repository. `list` is a dotted key to a list of objects (none: the file itself), `where` keeps the objects whose keys equal these values, `field` names the key (or keys) holding a path or a list of paths, `label` names an object in the log. An entry matches a path exactly or as a folder. The file is read at the base and at the head; an entry at either counts, so a pull request cannot - free a file by removing it from the list. + free a file by removing it from the list. A list that could drop a rule quietly is an error: a kept object with + none of the `field` keys, a `field` key no kept object has (a typo, or a `where` that keeps nothing), or an entry + that is not a plain repository path (`./x`, `/x`, `x/../y`, `x//y`, a wildcard), which could never match. - `docs_only_events`: events that may be docs-only (default `["pull_request"]`). -- `jobs`: per job, `paths` globs and `paths_from` lists. Docs files never run a job; a `never_docs` file does. +- `jobs`: per job, `paths` globs and `paths_from` lists. Docs files never run a job; a `never_docs` file does. A + file that is not docs and that no job names runs every job, and so does a change to the config. -Unknown keys are an error (a typo such as `never_doc` must not drop a rule quietly), and an error means a full run. +Unknown keys and wrong types are an error (a typo such as `never_doc` must not drop a rule quietly), and an error +means a full run that names it. The `config` input must be a plain repository path (no `./`, `..` or leading `/`), +so the "config is never docs" rule cannot be dodged by spelling. ## Why a pull request cannot loosen it @@ -113,10 +145,13 @@ runs in full for it; pin only SHAs that this fork's CI tested and tagged. ## Fails closed -A full run (and `jobs` = `{}`) for: an event without a base, a pull_request HEAD that is not a two-parent merge -commit, no merge base (shallow checkout), a base that is not a commit, a git error, an empty change, no config at -the base, a config that does not parse or has unknown keys, a `*_from` file at neither side or not readable as -configured. A symlink or submodule is never docs. A crash fails the step, so the job is red. +A full run (and `jobs` = `{}`) for: an event without a base, HEAD that is not `$GITHUB_SHA`, a pull_request HEAD +that is not GitHub's merge commit (two parents, HEAD^2 = the event's PR head; no event file), no merge base (shallow +checkout), a base that is not a commit, a git error, an empty change, a config path that is not plain, no config at +the base, a config that does not parse or has unknown keys or wrong types, a `*_from` file at neither side or not +readable as configured (not UTF-8, nested too deep, a missing field, an entry that is not a plain path). Any other +error is caught too and gives a full run with its message, never a step without outputs. A symlink or submodule is +never docs. ## Tests diff --git a/fork-ci/actions/docs-scope/action.yml b/fork-ci/actions/docs-scope/action.yml index 0b44c944084c6..5e76b2883554d 100644 --- a/fork-ci/actions/docs-scope/action.yml +++ b/fork-ci/actions/docs-scope/action.yml @@ -5,13 +5,14 @@ description: >- Anything unclear means a full run. Usage: README.md next to this file. inputs: config: - description: The JSON config, a path in the repository; read at the base commit, never from the checkout. + description: >- + The JSON config, a plain path in the repository (no ./); read at the base commit, never from the checkout. required: false default: .github/docs-scope.json base: description: >- - Events other than pull_request only: the commit to compare HEAD with (for example the last - main commit whose run passed). Empty: such runs run in full. + Events other than pull_request only: the commit to compare HEAD with, the last commit whose + run passed (never github.event.before: see README). Empty: such runs run in full. required: false default: "" outputs: @@ -30,6 +31,7 @@ runs: using: composite steps: # Only code from this action's folder (the caller's pinned SHA) runs; nothing from the checkout. + # The script also reads the runner's GITHUB_SHA and GITHUB_EVENT_PATH (HEAD must be the run's commit). - id: scope shell: bash env: diff --git a/fork-ci/actions/docs-scope/docs-scope.test.py b/fork-ci/actions/docs-scope/docs-scope.test.py index 666121de31c2b..8c8a294e878a8 100644 --- a/fork-ci/actions/docs-scope/docs-scope.test.py +++ b/fork-ci/actions/docs-scope/docs-scope.test.py @@ -3,7 +3,7 @@ with `git merge --no-ff`. Anything unclear must mean a full run. Run: python3 fork-ci/actions/docs-scope/docs-scope.test.py """ -import json, os, re, shutil, subprocess, sys, tempfile, unittest +import contextlib, json, os, re, shutil, subprocess, sys, tempfile, unittest sys.dont_write_bytecode = True # the Globs test imports docs_scope.py: leave no __pycache__ in the action folder @@ -15,7 +15,7 @@ 'GIT_CONFIG_GLOBAL': os.devnull, 'GIT_CONFIG_NOSYSTEM': '1'} REGISTRY_PATH = 'tools/registry.json' REGISTRY = {'modules': [ - {'id': 'site', 'kind': 'plugin', 'inputs': ['net/site/README.md']}, + {'id': 'site', 'kind': 'plugin', 'inputs': ['plugins/site/README.md']}, {'id': 'content-locale', 'kind': 'engine-module', 'inputs': ['plugins/locale/common/src/main/java/Wire.java']}, {'id': 'content-travel', 'kind': 'engine-module', 'inputs': ['plugins/travel/common/src/main/java']}, ]} @@ -62,14 +62,14 @@ def git(self, *a): return r.stdout.strip() def write(self, files): - for path, text in files.items(): - full = os.path.join(self.d, path) + for path, text in files.items(): # a bytes path or text is written as those bytes + full = os.path.join(os.fsencode(self.d), os.fsencode(path)) if text is None: os.remove(full) continue os.makedirs(os.path.dirname(full), exist_ok=True) - with open(full, 'w') as f: - f.write(text) + with open(full, 'wb') as f: + f.write(text if isinstance(text, bytes) else text.encode()) def commit(self, msg='c', files=None): if files: @@ -89,20 +89,40 @@ def pr(self, *pushes, main_after=None): self.commit('main moved', main_after) self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') - def scope(self, event='pull_request', base=''): - """(docs_only, jobs, stdout).""" - out = os.path.join(self.d, '.output') - r = subprocess.run([sys.executable, '-I', SCRIPT, '--config', CONFIG_PATH, '--event', event, '--base', base], - cwd=self.d, text=True, capture_output=True, env={**os.environ, **ENV, 'GITHUB_OUTPUT': out}) - self.assertEqual(r.returncode, 0, r.stderr) - with open(out) as f: - written = f.read() - os.remove(out) + def scope(self, event='pull_request', base='', config=CONFIG_PATH, sha=None, head_sha=None): + """(docs_only, jobs, stdout). The runner's view: $GITHUB_SHA is HEAD and the event's pull_request.head.sha + is HEAD^2 (HEAD for a commit that is not a merge), unless the test says otherwise ('' = unset).""" + out, event_path = os.path.join(self.d, '.output'), os.path.join(self.d, '.event.json') + head = self.git('rev-parse', 'HEAD') + parents = self.git('rev-list', '--parents', '-n', '1', 'HEAD').split() + head_sha = (parents[2] if len(parents) == 3 else head) if head_sha is None else head_sha + env = {**os.environ, **ENV, 'GITHUB_OUTPUT': out, 'GITHUB_SHA': head if sha is None else sha} + if head_sha: + with open(event_path, 'w') as f: + json.dump({'pull_request': {'head': {'sha': head_sha}}}, f) + env['GITHUB_EVENT_PATH'] = event_path + r = subprocess.run([sys.executable, '-I', SCRIPT, '--config', config, '--event', event, '--base', base], + cwd=self.d, capture_output=True, env=env) + stdout = r.stdout.decode() # strict: the script prints UTF-8 only, whatever the file names hold + self.assertEqual(r.returncode, 0, r.stderr.decode()) + with open(out, 'rb') as f: + written = f.read().decode() + for f in (out, event_path): + os.remove(f) if os.path.exists(f) else None m = re.fullmatch(r'docs_only=(true|false)\njobs=(\{.*\})\nreason=([^\n]+)\n', written) self.assertTrue(m, written) - self.assertEqual(r.stdout.startswith('docs-only: '), m[1] == 'true', r.stdout) - self.assertEqual(m[3], r.stdout.splitlines()[0]) - return m[1] == 'true', json.loads(m[2]), r.stdout + self.assertEqual(stdout.startswith('docs-only: '), m[1] == 'true', stdout) + self.assertEqual(m[3], stdout.splitlines()[0]) + for line in stdout.splitlines(): # a file name never starts a line: no ::workflow-command:: + self.assertRegex(line, r'^(docs-only|full run|not docs-only|job [^:]+):', stdout) + self.assertTrue(line.isprintable(), repr(line)) + return m[1] == 'true', json.loads(m[2]), stdout + + def reset(self): + self.git('checkout', '-q', '-f', 'main') + self.git('reset', '-q', '--hard', self.base) + for b in ('pr', 'pr-real'): + self.git('branch', '-q', '-D', b) if self.git('branch', '--list', b) else None def assertDocsOnly(self, expected): docs, _, out = self.scope() @@ -170,16 +190,32 @@ def test_a_named_file_read_by_a_tool(self): self.check('plugins/RELEASE-CLAIMS.md') def test_an_md_listed_in_the_registry(self): - self.check('net/site/README.md') + self.check('plugins/site/README.md') def test_an_md_newly_listed_in_the_registry_by_main(self): # read at the base too, not only the head self.pr({'docs/new.md': 'doc'}, main_after={REGISTRY_PATH: json.dumps( - {'modules': [{'id': 'docs-site', 'inputs': ['docs/']}]})}) - self.assertDocsOnly(False) + {'modules': REGISTRY['modules'] + [{'id': 'docs-site', 'inputs': ['docs/']}]})}) + self.assertIn('docs-site inputs: docs', self.assertDocsOnly(False)) - def test_a_pr_that_drops_a_registry_input_does_not_free_it(self): # the base's entry still counts - self.pr({REGISTRY_PATH: json.dumps({'modules': []}), 'net/site/README.md': 'y'}) - self.assertDocsOnly(False) + +class RegistryAtTheBase(Repo): + """A pull request cannot free a file by deleting its entry: the base's entries count. Here the registry change + itself does not decide (it is docs, or a job's own path), so only the base read can.""" + config = {'docs': ['**'], 'never_docs_from': CONFIG['never_docs_from'], + 'jobs': {'plugins': {'paths': ['plugins/**', 'tools/**']}, 'engine': CONFIG['jobs']['engine']}} + + def drop(self, module_id): + return json.dumps({'modules': [m for m in REGISTRY['modules'] if m['id'] != module_id]}) + + def test_a_pr_that_drops_a_never_docs_entry_does_not_free_the_file(self): + self.pr({REGISTRY_PATH: self.drop('site'), 'plugins/site/README.md': 'y'}) + docs, _, out = self.scope() + self.assertFalse(docs, out) + self.assertIn('site inputs: plugins/site/README.md', out) + + def test_a_pr_that_drops_a_jobs_entry_still_runs_the_job(self): + self.pr({REGISTRY_PATH: self.drop('content-locale'), 'plugins/locale/common/src/main/java/Wire.java': 'x'}) + self.assertEqual(self.scope()[1], {'plugins': 'true', 'engine': 'true'}) class FailsClosed(Repo): @@ -232,6 +268,135 @@ def test_a_registry_that_does_not_parse_as_configured(self): self.assertEqual((docs, jobs), (False, {}), out) self.assertIn('cannot be read as configured', out) + def test_registry_entries_that_could_never_match_are_a_full_run(self): # never fail open on a list + site = {'id': 'site', 'kind': 'plugin', 'inputs': ['plugins/site/README.md']} + for name, modules in ( + ('a renamed field', [{**site, 'inputs': None, 'input': ['plugins/site/README.md']}]), + ('an object without the field', [site, {'id': 'other', 'kind': 'plugin'}]), + ('./', [{**site, 'inputs': ['./plugins/site/README.md']}]), + ('a leading /', [{**site, 'inputs': ['/plugins/site/README.md']}]), + ('..', [{**site, 'inputs': ['plugins/../plugins/site/README.md']}]), + ('a wildcard', [{**site, 'inputs': ['plugins/**/*.md']}]), + ('a number', [{**site, 'inputs': [5]}]), + ('no object of the kind a job keeps', None)): + with self.subTest(name): + self.reset() + engine = [m for m in REGISTRY['modules'] if m['kind'] == 'engine-module'] if modules else [] + modules = [{k: v for k, v in m.items() if v is not None} for m in modules or [site]] + engine + self.base = self.commit('registry', {REGISTRY_PATH: json.dumps({'modules': modules})}) + self.pr({'plugins/site/README.md': 'y'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('cannot be read as configured', out) + + +class MergeCommit(Repo): + """On pull_request, HEAD must be GitHub's merge commit before HEAD^1 is trusted as the base: a checkout of a PR + head whose last commit merged main in would make the PR's code vanish from both diffs and read the config from + the PR.""" + + def setUp(self): + super().setUp() + self.git('checkout', '-q', '-b', 'pr', self.base) + self.commit('code + a looser config', {'app/Main.java': 'class Main { int x; }', + CONFIG_PATH: json.dumps({'docs': ['**']})}) + self.git('checkout', '-q', 'main') + self.commit('docs on main', {'README.md': 'y'}) + self.git('checkout', '-q', 'pr') + self.git('merge', '-q', '--no-ff', '-m', 'merge main into pr', 'main') + self.pr_head = self.git('rev-parse', 'HEAD') + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') + self.github_sha = self.git('rev-parse', 'HEAD') # what GitHub's refs/pull/N/merge would hold + self.git('checkout', '-q', '--detach', self.pr_head) # but the caller checked out the PR head + + def test_the_real_merge_commit_is_a_full_run(self): # the check does not refuse the right checkout + self.git('checkout', '-q', '--detach', self.github_sha) + self.assertEqual(self.scope(head_sha=self.pr_head)[:2], (False, {'plugins': 'true', 'engine': 'true'})) + + def test_a_pr_head_checkout_is_a_full_run(self): + docs, jobs, out = self.scope(sha=self.github_sha, head_sha=self.pr_head) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('is not the commit this run is for', out) + + def test_a_merge_whose_second_parent_is_not_the_pr_head_is_a_full_run(self): + docs, jobs, out = self.scope(sha=self.pr_head, head_sha=self.pr_head) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn("not the event's pull_request.head.sha", out) + + def test_no_github_sha_or_event_is_a_full_run(self): + self.git('checkout', '-q', '--detach', self.github_sha) + for sha, head_sha, why in (('', self.pr_head, 'unset'), (None, '', 'event file')): + with self.subTest(why): + docs, jobs, out = self.scope(sha=sha, head_sha=head_sha) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn(why, out) + + def test_a_push_run_checks_github_sha_too(self): + self.git('checkout', '-q', 'main') + docs, jobs, out = self.scope('push', self.base, sha=self.pr_head) + self.assertEqual((docs, jobs), (False, {}), out) + + +class NeverCrashes(Repo): + """Every error is a full run with outputs. A crash leaves no outputs: a `needs:` job that is skipped reads as + passing on a required check.""" + + def test_a_file_name_that_is_not_utf8(self): + self.pr({b'docs/\xff.md': 'x'}) + docs, jobs, out = self.scope() + self.assertFalse(docs, out) + self.assertIn('not UTF-8', out) + self.assertIn('docs/\\udcff.md', out) + + def test_a_registry_at_the_head_that_is_not_utf8_or_too_deep(self): + for name, text in (('not utf-8', b'\xff'), ('too deep', '[' * 200000)): + with self.subTest(name): + self.reset() + self.pr({REGISTRY_PATH: text, 'README.md': 'y'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('cannot be read as configured', out) + + def test_an_error_nobody_foresaw(self): # the last net: main() turns any exception into a full run + sys.path.insert(0, HERE) + try: + import docs_scope + finally: + sys.path.remove(HERE) + out = os.path.join(self.d, '.output') + + def broken(*a): + raise RuntimeError('boom') + old = os.environ.get('GITHUB_OUTPUT') + os.environ['GITHUB_OUTPUT'] = out + try: + with open(os.devnull, 'w') as devnull, contextlib.redirect_stdout(devnull): + self.assertEqual(docs_scope.main(['--config', CONFIG_PATH, '--event', 'pull_request'], run=broken), 0) + finally: + os.environ.pop('GITHUB_OUTPUT') if old is None else os.environ.__setitem__('GITHUB_OUTPUT', old) + with open(out) as f: + self.assertEqual(f.read(), 'docs_only=false\njobs={}\nreason=full run: docs-scope failed ' + '(RuntimeError: boom)\n') + + +class OddNames(Repo): + def test_a_newline_name_in_a_source_set_is_not_docs(self): + self.pr({'p/src/main/resources/he\nlp.md': 'x'}) + self.assertDocsOnly(False) + + def test_a_newline_name_in_a_job_folder_runs_that_job_by_its_paths(self): + self.pr({'plugins/x\ny.java': 'x'}) + docs, jobs, out = self.scope() + self.assertEqual(jobs, {'plugins': 'true', 'engine': 'false'}, out) + self.assertIn('matches its paths', out) + + def test_a_name_cannot_inject_a_workflow_command_or_an_output(self): # scope() checks every line + self.pr({'a\ndocs_only=true\njobs={}\n::warning::injected\n.java': 'x', 'README.md': 'y'}) + docs, _, out = self.scope() + self.assertFalse(docs, out) + self.assertIn('a\\ndocs_only=true', out) + class ConfigAtTheBase(Repo): """The rules come from the base commit and the code from the action's pinned folder, so a pull request cannot @@ -240,7 +405,7 @@ class ConfigAtTheBase(Repo): def test_a_pr_that_loosens_its_own_config_still_runs_in_full(self): self.pr({CONFIG_PATH: json.dumps({'docs': ['**'], 'jobs': {}}), 'engine/A.java': 'class A {}'}) docs, jobs, out = self.scope() - self.assertEqual((docs, jobs), (False, {'plugins': 'false', 'engine': 'true'}), out) # the base's jobs + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'true'}), out) # the base's jobs, all def test_no_config_at_the_base(self): # the PR that adds the config runs in full self.git('rm', '-q', CONFIG_PATH) @@ -255,11 +420,10 @@ def test_a_bad_config_at_the_base(self): json.dumps({'never_docs': []}), json.dumps({'docs': '**/*.md'}), json.dumps({'docs': ['*.md'], 'never_docs': [{'glob': 'x'}]}), json.dumps({'docs': ['*.md'], 'never_docs_from': [{'file': 'r.json', 'field': 'f'}]}), - json.dumps({'docs': ['*.md'], 'jobs': {'j': {'path': ['x/**']}}})): + json.dumps({'docs': ['*.md'], 'jobs': {'j': {'path': ['x/**']}}}), + json.dumps({'docs': ['*.md'], 'never_docs': [{'glob': 5, 'why': 'x'}]})): # was a crash with self.subTest(bad=bad): - self.git('checkout', '-q', 'main') - self.git('reset', '-q', '--hard', self.base) - self.git('branch', '-q', '-D', 'pr') if self.git('branch', '--list', 'pr') else None + self.reset() self.commit('bad config', {CONFIG_PATH: bad}) self.git('checkout', '-q', '-b', 'pr') self.commit('docs', {'README.md': bad}) @@ -270,6 +434,22 @@ def test_a_bad_config_at_the_base(self): self.assertIn('config', out) + def test_a_bad_source_entry_names_itself(self): # wrong types and typos in a *_from entry: a full run, why + source = CONFIG['never_docs_from'][0] + for bad, why in (({'field': 5}, 'needs a plain file path'), ({'field': []}, 'needs a plain file path'), + ({'where': ['kind']}, 'needs a plain file path'), ({'label': 3}, 'needs a plain file path'), + ({'list': None}, 'needs a plain file path'), ({'file': './' + REGISTRY_PATH}, 'needs a plain'), + ({'field': ['inputs', 'inptus']}, "no kept object has the field(s) ['inptus']"), + ({'where': {'kind': 'plugn'}}, "no kept object has the field(s) ['inputs']")): + with self.subTest(bad=bad): + self.reset() + self.commit('bad source', {CONFIG_PATH: json.dumps({**CONFIG, 'never_docs_from': [{**source, **bad}]})}) + self.pr({'README.md': 'y'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn(why, out) + + class LooseConfig(Repo): config = {'docs': ['**']} # everything is docs, except the config itself @@ -277,6 +457,14 @@ def test_the_config_file_is_never_docs(self): self.pr({CONFIG_PATH: json.dumps({'docs': ['**'], 'jobs': {}})}) self.assertIn('the docs-scope config', self.assertDocsOnly(False)) + def test_a_config_path_that_is_not_plain_is_a_full_run(self): # ./x would dodge "the config is never docs" + self.pr({CONFIG_PATH: json.dumps({'docs': ['**'], 'jobs': {}})}) + for config in ('./' + CONFIG_PATH, '.github//docs-scope.json', '/' + CONFIG_PATH): + with self.subTest(config): + docs, jobs, out = self.scope(config=config) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('not a plain repository path', out) + class Jobs(Repo): def test_a_job_runs_for_its_paths_and_skips_otherwise(self): @@ -286,8 +474,23 @@ def test_a_job_runs_for_its_paths_and_skips_otherwise(self): self.assertIn('job engine: skip', out) def test_docs_in_a_job_folder_do_not_run_it(self): # code elsewhere makes it a full run, not an engine build - self.pr({'engine/README.md': 'y', 'app/Main.java': 'class Main { int x; }'}) - self.assertEqual(self.scope()[1], {'plugins': 'false', 'engine': 'false'}) + self.pr({'engine/README.md': 'y', 'plugins/a/A.java': 'class A {}'}) + self.assertEqual(self.scope()[1], {'plugins': 'true', 'engine': 'false'}) + + def test_a_file_no_job_names_runs_every_job(self): # unclear which job it reaches: all of them + for path in ('app/Main.java', '.github/workflows/ci.yml', CONFIG_PATH): + with self.subTest(path): + self.reset() + self.pr({path: json.dumps(CONFIG) + ' '}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'true'}), out) + self.assertIn('every job runs', out.splitlines()[0]) + + def test_a_config_change_runs_every_job_even_if_a_job_names_it(self): + cfg = {**CONFIG, 'jobs': {**CONFIG['jobs'], 'plugins': {'paths': ['plugins/**', '.github/**']}}} + self.base = self.commit('a job names .github', {CONFIG_PATH: json.dumps(cfg)}) + self.pr({CONFIG_PATH: json.dumps(cfg) + ' '}) + self.assertEqual(self.scope()[1], {'plugins': 'true', 'engine': 'true'}) def test_an_md_input_in_a_job_folder_runs_it(self): self.pr({'engine/core/src/main/resources/help.md': 'y'}) @@ -306,15 +509,13 @@ def test_a_jobs_paths_from_a_registry_filtered_by_kind(self): # the registry n ('plugins/locale/common/src/main/java/Other.java', 'false'), ('plugins/travel/common/src/main/java/a/Leg.java', 'true')): with self.subTest(path=path): - self.git('checkout', '-q', 'main') - self.git('reset', '-q', '--hard', self.base) - self.git('branch', '-q', '-D', 'pr') if self.git('branch', '--list', 'pr') else None + self.reset() self.pr({path: 'class X {}'}) docs, jobs, out = self.scope() self.assertEqual(jobs['engine'], runs, out) def test_a_registry_entry_of_another_kind_does_not_run_the_job(self): - self.pr({'net/site/README.md': 'y'}) # an input of a "plugin", not of an "engine-module" + self.pr({'plugins/site/README.md': 'y'}) # an input of a "plugin", not of an "engine-module" self.assertEqual(self.scope()[1]['engine'], 'false') @@ -356,7 +557,9 @@ def test_globs(self): ('**/test/**', ['test/a', 'x/test/b/c'], ['x/tests/a', 'xtest/a']), ('src/**', ['src/a', 'src/a/b'], ['x/src/a', 'srcx/a']), ('a?.md', ['ab.md'], ['a/.md', 'abc.md']), - ('a.b+c', ['a.b+c'], ['aXb+c'])): + ('a.b+c', ['a.b+c'], ['aXb+c']), + ('**/src/**', ['p/src/a\nb.md'], ['p/s\nrc/a']), # ** crosses a newline in a name + ('app/**', ['app/x\ny.java'], ['ap\np/x'])): for p in yes: self.assertTrue(glob_re(pattern).match(p), (pattern, p)) for p in no: diff --git a/fork-ci/actions/docs-scope/docs_scope.py b/fork-ci/actions/docs-scope/docs_scope.py index b602045fa7649..171a213e659fa 100644 --- a/fork-ci/actions/docs-scope/docs_scope.py +++ b/fork-ci/actions/docs-scope/docs_scope.py @@ -5,21 +5,26 @@ - pull_request: the union of two diffs, both without rename detection (a rename lists its old and its new path): merge base of the base and the PR head .. the PR head (every push together, never the last one alone), and base .. GitHub's merge commit (what merging changes on the base it was tested with). HEAD must be GitHub's merge - commit (refs/pull/N/merge): HEAD^1 is the base, HEAD^2 the PR head. - - any other event: --base .. HEAD, only when the caller gives --base (for example the last main commit that passed). + commit (refs/pull/N/merge): HEAD == $GITHUB_SHA, two parents, and HEAD^2 == the event's pull_request.head.sha. + Only then is HEAD^1 the base (a checkout of a PR head that merged main in would otherwise pose as one). + - any other event: --base .. HEAD, only when the caller gives --base (the last commit whose run passed; never + github.event.before, see README) and HEAD == $GITHUB_SHA. A path is docs when it is a plain file (no symlink or submodule), matches a `docs` glob, is not the config file, and -matches no `never_docs` glob or `never_docs_from` entry. The change is docs-only when every path is docs and the event -is in `docs_only_events`. A job runs when a path that is not docs matches its `paths` or `paths_from`. +matches no `never_docs` glob or `never_docs_from` entry, and its name has no control character and is UTF-8. The change +is docs-only when every path is docs and the event is in `docs_only_events`. A job runs when a path that is not docs +matches its `paths` or `paths_from`; every job runs when such a path matches no job, or when the config changed. The config is read from the BASE commit, never from the checkout, and this script runs from the action's own folder at the caller's pinned SHA: a pull request cannot loosen the rules or the code that judge it. `*_from` files are read at the base and the head; an entry at either counts. -Fails closed: anything unclear means docs_only=false and every job runs, with the reason printed. Jobs missing from -the `jobs` output (config unreadable) must be read as "run": callers test `!= 'false'`. +Fails closed: anything unclear, including an error this script did not foresee, means docs_only=false and every job +runs, with the reason printed. Jobs missing from the `jobs` output (config unreadable) must be read as "run": callers +test `!= 'false'`. Printed lines escape control characters, so a file name cannot inject a workflow command. python3 -I docs_scope.py --config .github/docs-scope.json --event "$GITHUB_EVENT_NAME" [--base SHA] +Reads $GITHUB_SHA and $GITHUB_EVENT_PATH (set by the runner). Writes docs_only=true|false, jobs= and reason= to $GITHUB_OUTPUT. """ import argparse, json, os, re, subprocess, sys @@ -27,6 +32,7 @@ PLAIN_MODES = ('100644', '100755', '000000') # a regular file, or (000000) the side where it does not exist KEYS = {'docs', 'never_docs', 'never_docs_from', 'docs_only_events', 'jobs'} SOURCE_KEYS = {'file', 'list', 'where', 'field', 'label', 'why'} +ODD_NAME = re.compile(r'[\x00-\x1f\x7f-\x9f\ud800-\udfff]') # a control character, or a byte that is not UTF-8 class Unclear(Exception): @@ -34,9 +40,21 @@ class Unclear(Exception): def git(*args): - """stdout, or None when git fails.""" - r = subprocess.run(['git', *args], capture_output=True, text=True) - return r.stdout if r.returncode == 0 else None + """stdout, or None when git fails. Bytes that are not UTF-8 survive as lone surrogates (never a crash).""" + r = subprocess.run(['git', *args], capture_output=True) + return r.stdout.decode('utf-8', 'surrogateescape') if r.returncode == 0 else None + + +def shown(text): + """One printable line: control characters, line separators and non-UTF-8 bytes escaped.""" + return ''.join(c if c.isprintable() else ascii(c)[1:-1] for c in text) + + +def plain_path(x): + """A repository path as git prints it: no ./, .., //, leading / or glob character (a trailing / is a folder).""" + if not isinstance(x, str) or ODD_NAME.search(x) or re.search(r'[*?\[\]{}\\]', x): + return False + return all(p not in ('', '.', '..') for p in (x[:-1] if x.endswith('/') else x).split('/')) def glob_re(pattern): @@ -52,7 +70,7 @@ def glob_re(pattern): out.append('[^/]*' if pattern[i] == '*' else '[^/]'); i += 1 else: out.append(re.escape(pattern[i])); i += 1 - return re.compile(''.join(out) + r'\Z') + return re.compile(''.join(out) + r'\Z', re.DOTALL) # `**` crosses a newline in a name too def changes(a, b, run=git): @@ -70,13 +88,31 @@ def changes(a, b, run=git): return rows -def the_change(event, head, base, run=git): +def event_head_sha(event_path): + """pull_request.head.sha from the runner's event file; Unclear when it is not there.""" + try: + with open(event_path or '', 'rb') as f: + sha = json.load(f)['pull_request']['head']['sha'] + except (OSError, ValueError, KeyError, TypeError) as e: + raise Unclear(f'cannot read pull_request.head.sha from the event file ({type(e).__name__}): the PR is unknown') + if not isinstance(sha, str) or not re.fullmatch(r'[0-9a-f]{40,64}', sha): + raise Unclear('the event file has no pull_request.head.sha: the PR is unknown') + return sha + + +def the_change(event, head, base, run=git, sha='', event_path=''): """(rows, the commit the config is read at, what was compared); Unclear when the change is unknown.""" + head_sha = (run('rev-parse', '-q', '--verify', f'{head}^{{commit}}') or '').strip() + if not head_sha or head_sha != sha: + raise Unclear(f'HEAD {head_sha[:10] or "?"} is not the commit this run is for ($GITHUB_SHA ' + f'{sha[:10] or "unset"}): the change is unknown') if event == 'pull_request': line = (run('rev-list', '--parents', '-n', '1', head) or '').split() if len(line) != 3: raise Unclear(f"{head} is not a two-parent merge commit (GitHub's refs/pull/N/merge): the PR diff is unknown") _, base, pr = line + if pr != event_head_sha(event_path): + raise Unclear(f"HEAD^2 {pr[:10]} is not the event's pull_request.head.sha: HEAD is not GitHub's merge commit") mb = (run('merge-base', base, pr) or '').strip() if not mb: raise Unclear(f'no merge base between the base {base[:10]} and the PR head {pr[:10]}') @@ -109,10 +145,15 @@ def sources(value, where, need_why=False): if not isinstance(value, list) or not all(isinstance(s, dict) for s in value): raise Unclear(f'config: {where} must be a list of objects') for s in value: - extra = set(s) - SOURCE_KEYS - if extra or not isinstance(s.get('file'), str) or 'field' not in s or (need_why and 'why' not in s): - raise Unclear(f'config: {where} entry {json.dumps(s)[:80]} needs file and field' - f'{" and why" if need_why else ""} (and no other keys than {sorted(SOURCE_KEYS)})') + field = s.get('field') + fields = field if isinstance(field, list) else [field] + ok = (not set(s) - SOURCE_KEYS and isinstance(s.get('file'), str) and plain_path(s['file']) + and fields and all(isinstance(f, str) and f for f in fields) + and all(isinstance(s.get(k, 'x'), str) and s.get(k, 'x') for k in ('list', 'label', 'why')) + and isinstance(s.get('where', {}), dict) and (not need_why or 'why' in s)) + if not ok: + raise Unclear(f'config: {where} entry {json.dumps(s)[:80]} needs a plain file path and field (strings)' + f'{" and why" if need_why else ""}, where an object, no other keys than {sorted(SOURCE_KEYS)}') return value @@ -121,15 +162,16 @@ def load_config(path, ref, run=git): if text is None: raise Unclear(f'no config {path} at the base {ref[:10]} (a PR that adds it runs in full)') try: - c = json.loads(text) - except ValueError as e: + c = json.loads(text.encode('utf-8', 'surrogateescape')) + except (ValueError, RecursionError) as e: raise Unclear(f'config {path} at {ref[:10]} is not JSON: {e}') if not isinstance(c, dict) or set(c) - KEYS or 'docs' not in c: raise Unclear(f'config {path}: needs "docs", and no other keys than {sorted(KEYS)}') strings(c['docs'], 'docs') for i, n in enumerate(c.setdefault('never_docs', [])): - if not isinstance(n, dict) or set(n) != {'glob', 'why'}: - raise Unclear(f'config: never_docs[{i}] must be {{"glob", "why"}}') + if not isinstance(n, dict) or set(n) != {'glob', 'why'} or not all( + isinstance(n[k], str) and n[k] for k in ('glob', 'why')): + raise Unclear(f'config: never_docs[{i}] must be {{"glob", "why"}}, both non-empty strings') sources(c.setdefault('never_docs_from', []), 'never_docs_from', need_why=True) strings(c.setdefault('docs_only_events', ['pull_request']), 'docs_only_events') jobs = c.setdefault('jobs', {}) @@ -144,8 +186,9 @@ def load_config(path, ref, run=git): def read_entries(src, refs, run=git): - """{path prefix: label} of every entry the source names at any ref; Unclear if no ref has the file or one is - malformed. Entries match a path exactly or as a folder.""" + """{path prefix: label} of every entry the source names at any ref; Unclear if no ref has the file, or one is + malformed: an object without any named field, a field no kept object has (a typo; none kept), or an entry that is + not a plain path (./, /, .., a wildcard) and so could never match. Entries match a path exactly or as a folder.""" found, read = {}, False fields = src['field'] if isinstance(src['field'], list) else [src['field']] for ref in refs: @@ -153,21 +196,27 @@ def read_entries(src, refs, run=git): if text is None: continue try: - items = json.loads(text) - for key in (src.get('list') or '').split('.') if src.get('list') else []: + items = json.loads(text.encode('utf-8', 'surrogateescape')) + for key in src['list'].split('.') if 'list' in src else []: items = items[key] items = items if isinstance(items, list) else [items] + seen = set() for item in items: - if any(item.get(k) != v for k, v in (src.get('where') or {}).items()): + if any(item.get(k) != v for k, v in src.get('where', {}).items()): continue - label = item.get(src['label'], '?') if src.get('label') else src['file'] - for f in fields: - value = item.get(f) or [] + label = item.get(src['label'], '?') if 'label' in src else src['file'] + if not any(f in item for f in fields): + raise KeyError(f'an object ({shown(str(label))[:40]}) has none of the fields {fields}') + for f in (f for f in fields if f in item): + seen.add(f) + value = item[f] for x in value if isinstance(value, list) else [value]: - if not isinstance(x, str) or not x.strip('/'): - raise TypeError(f'{f}: {x!r} is not a path') + if not isinstance(x, str) or not plain_path(x): + raise TypeError(f'{f}: {shown(repr(x))[:80]} is not a plain repository path') found[x.rstrip('/')] = f'{label} {f}' - except (ValueError, KeyError, IndexError, AttributeError, TypeError) as e: + if set(fields) - seen: # a typo, an empty list, or a "where" that keeps nothing + raise KeyError(f'no kept object has the field(s) {sorted(set(fields) - seen)}') + except (ValueError, KeyError, IndexError, AttributeError, TypeError, RecursionError) as e: raise Unclear(f'{src["file"]} at {ref[:10]} cannot be read as configured: {e}') read = True if not read: @@ -182,10 +231,12 @@ def entry_match(path, entries): return None -def decide(event, config_path, head='HEAD', base='', run=git): +def decide(event, config_path, head='HEAD', base='', run=git, sha='', event_path=''): """(docs_only, {job: 'true'|'false'}, [reason lines]); the first line is the overall reason.""" try: - rows, cbase, what = the_change(event, head, base, run) + if not plain_path(config_path) or config_path.endswith('/'): + raise Unclear(f'the config path {config_path} is not a plain repository path (no ./, .., leading /)') + rows, cbase, what = the_change(event, head, base, run, sha, event_path) c = load_config(config_path, cbase, run) refs = (cbase, head) never_from = [(s, read_entries(s, refs, run)) for s in c['never_docs_from']] @@ -200,6 +251,8 @@ def decide(event, config_path, head='HEAD', base='', run=git): for p in sorted({p for p, _, _ in rows}): if p in odd: not_docs[p] = 'a symlink or submodule, not a plain file' + elif ODD_NAME.search(p): + not_docs[p] = 'a name with a control character or bytes that are not UTF-8' elif not any(g.match(p) for g in docs_globs): not_docs[p] = 'not a docs file' elif p == config_path: @@ -216,19 +269,30 @@ def decide(event, config_path, head='HEAD', base='', run=git): if not not_docs and event in c['docs_only_events']: lines.append(f'docs-only: {len({p for p, _, _ in rows})} docs file(s) changed against {what}') return True, {n: 'false' for n in jobs}, lines + [f'job {n}: skip (docs-only)' for n in jobs] + + def job_hit(p, globs, froms): + if any(g.match(p) for g in globs): + return 'its paths' + return next((f'{m[1]}: {m[0]}' for e in froms for m in [entry_match(p, e)] if m), None) + + # A file that is not docs but that no job names (a root build file, a workflow, the config): every job runs. + every = (config_path if config_path in not_docs else + next((p for p in not_docs if not any(job_hit(p, *j) for j in jobs.values())), None)) if not_docs: - first = next(iter(not_docs)) + first = every or next(iter(not_docs)) more = f' and {len(not_docs) - 1} more' if len(not_docs) > 1 else '' - lines.append(f'full run: {first} is {not_docs[first]}{more}') + tail = ', which no job names: every job runs' if every and every != config_path else ( + ': every job runs' if every else '') + lines.append(f'full run: {first} is {not_docs[first]}{more}{tail}') else: - lines.append(f'full run: only docs changed, but a {event or "unknown"} run is not in docs_only_events') + lines.append(f'not docs-only: only docs changed, but a {event or "unknown"} run is not in docs_only_events') out = {} for n, (globs, froms) in jobs.items(): - hit = next(((p, 'its paths') for p in not_docs if any(g.match(p) for g in globs)), None) or next( - ((p, f'{m[1]}: {m[0]}') for p in not_docs for e in froms for m in [entry_match(p, e)] if m), None) - out[n] = 'true' if hit else 'false' - lines.append(f'job {n}: run ({hit[0]} matches {hit[1]})' if hit - else f'job {n}: skip (no changed file that is not docs matches its paths)') + hit = None if every else next(((p, h) for p in not_docs for h in [job_hit(p, globs, froms)] if h), None) + out[n] = 'true' if every or hit else 'false' + lines.append(f'job {n}: run (every job runs for {every})' if every else + f'job {n}: run ({hit[0]} matches {hit[1]})' if hit else + f'job {n}: skip (no changed file that is not docs matches its paths)') return False, out, lines @@ -239,14 +303,18 @@ def main(argv=None, run=git): p.add_argument('--head', default='HEAD') p.add_argument('--base', default='') a = p.parse_args(argv) - docs_only, jobs, lines = decide(a.event, a.config, a.head, a.base, run) + try: + docs_only, jobs, lines = decide(a.event, a.config, a.head, a.base, run, os.environ.get('GITHUB_SHA', ''), + os.environ.get('GITHUB_EVENT_PATH', '')) + except Exception as e: # an error nobody foresaw is "unclear" too: a full run, never a crash without outputs + docs_only, jobs, lines = False, {}, [f'full run: docs-scope failed ({type(e).__name__}: {e})'] + lines = [shown(line) for line in lines] # a file name cannot start a line, so no ::workflow-command:: print('\n'.join(lines)) out = os.environ.get('GITHUB_OUTPUT') if out: - reason = ' '.join(lines[0].split()) # one line, whatever a path holds with open(out, 'a') as f: f.write(f'docs_only={"true" if docs_only else "false"}\n' - f'jobs={json.dumps(jobs, separators=(",", ":"))}\nreason={reason}\n') + f'jobs={json.dumps(jobs, separators=(",", ":"))}\nreason={lines[0]}\n') return 0 From a19a2eafa929d8e051cfa4921ef169776b84b774 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:08:22 +0000 Subject: [PATCH 3/5] fork-ci docs-scope: base rules decide the full run, push runs only as base, no hidden gitlinks - "A file no job names runs every job" is judged by the base's *_from entries only; the PR's own entries can add a job but never cancel the full run (a new module listing a root file did). - A base off HEAD's first-parent line is a full run, and the README's last-green query takes push runs only (event=push): a fork PR from a branch called main no longer counts as a tested main commit. - git diff --ignore-submodules=none: .gitmodules ignore=all or diff.ignoreSubmodules cannot hide a gitlink bump. - The reason says "scoped run" when jobs are scoped, "full run" only when every job runs. - Tests for unknown keys in never_docs_from and paths_from entries. Co-Authored-By: Claude Opus 5.5 --- fork-ci/actions/docs-scope/README.md | 47 ++++---- fork-ci/actions/docs-scope/action.yml | 3 +- fork-ci/actions/docs-scope/docs-scope.test.py | 105 +++++++++++++++++- fork-ci/actions/docs-scope/docs_scope.py | 54 ++++++--- 4 files changed, 169 insertions(+), 40 deletions(-) diff --git a/fork-ci/actions/docs-scope/README.md b/fork-ci/actions/docs-scope/README.md index 21c0745b0c9f5..2f181b0f9164e 100644 --- a/fork-ci/actions/docs-scope/README.md +++ b/fork-ci/actions/docs-scope/README.md @@ -19,12 +19,12 @@ jobs: steps: - uses: actions/checkout@ # the default ref: on pull_request GitHub's merge commit ($GITHUB_SHA) with: { fetch-depth: 0 } # the merge base must be there - # Optional, push only: the last commit whose run of this workflow passed (see "The base on push"). + # Optional, push only: the last commit whose push run of this workflow passed (see "The base on push"). - id: green if: github.event_name == 'push' env: { GH_TOKEN: "${{ github.token }}" } # needs `actions: read` run: | - sha=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?branch=main&status=success&per_page=1" \ + sha=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?branch=main&event=push&status=success&per_page=1" \ --jq '.workflow_runs[0].head_sha // ""') || sha="" echo "sha=$sha" >> "$GITHUB_OUTPUT" - id: scope @@ -47,11 +47,11 @@ job skips them, and GitHub counts a skipped required job as passing: gate them w ### Outputs -| Output | Value | -| ----------- | -------------------------------------------------------------------------- | -| `docs_only` | `true` only when every changed file is docs and the event may be docs-only | -| `jobs` | JSON `{"": "true" \| "false"}`; `{}` when unknown | -| `reason` | one line: why (every skip and every full run says why) | +| Output | Value | +| ----------- | ------------------------------------------------------------------------------ | +| `docs_only` | `true` only when every changed file is docs and the event may be docs-only | +| `jobs` | JSON `{"": "true" \| "false"}`; `{}` when unknown | +| `reason` | one line: `docs-only:`, `full run:`, `scoped run:` or `not docs-only:` and why | The step log also prints one line per job: `job engine: run (engine/A.java matches its paths)` or `job engine: skip (...)`. Control characters, line separators and bytes that are not UTF-8 in a file name are @@ -66,17 +66,23 @@ printed escaped (`\n`, `\udcff`), so a file name can neither start a `::workflow last commit merged main in, HEAD^1 would be the PR's own commit, the PR's code would drop out of both diffs and the config would be read from the PR. - **Any other event** (push, merge_group, workflow_dispatch): `base` .. HEAD, only when the caller gives `base` and - HEAD == `$GITHUB_SHA`. Without a base the run is a full run. Such an event is docs-only only when + HEAD == `$GITHUB_SHA`, and the base must be on HEAD's first-parent line. Without a base the run is a full run. Such an event is docs-only only when `docs_only_events` names it; its `jobs` are read either way, so a docs-only push to main can still skip the build jobs. ### The base on push -Pass the last commit whose run of the workflow **passed**, or nothing (a full run). Never `github.event.before`: if -push A (code) went red or was cancelled (for example by `concurrency`), push B (docs) diffs B against A, every job -reads `false`, and main turns green with A's code never tested; a rerun of B gives the same answer. Against the last -green commit, A's code is in the diff until a run that tests it passes. Any commit works as a base, an ancestor or -not, because the diff compares trees; one that is not in the checkout is a full run. +Pass the last commit whose **push** run of the workflow on main **passed**, or nothing (a full run). Never +`github.event.before`: if push A (code) went red or was cancelled (for example by `concurrency`), push B (docs) diffs +B against A, every job reads `false`, and main turns green with A's code never tested; a rerun of B gives the same +answer. Against the last green commit, A's code is in the diff until a run that tests it passes. + +Keep `event=push` in the query: `branch` matches a run's head branch, so without it a passing `pull_request` run from +a fork whose branch is also called `main` counts, and its head commit is a PR head that no run tested as main (the PR +run tested GitHub's merge commit). The action enforces the same rule: the base must be on HEAD's first-parent line +(main's own pushes), so a merged branch's commit, another branch or a force-pushed-away commit is a full run, and so +is a base that is not in the checkout. A rerun can see a newer green base than the first run did; that only shrinks +the diff to commits a passing push run already tested. ## Config @@ -121,8 +127,10 @@ not, because the diff compares trees; one that is not in the checkout is a full - `never_docs_from` / `paths_from`: paths listed in a JSON file of the repository. `list` is a dotted key to a list of objects (none: the file itself), `where` keeps the objects whose keys equal these values, `field` names the key (or keys) holding a path or a list of paths, `label` names an object in the log. An entry matches a path exactly or - as a folder. The file is read at the base and at the head; an entry at either counts, so a pull request cannot - free a file by removing it from the list. A list that could drop a rule quietly is an error: a kept object with + as a folder. The file is read at the base and at the head; an entry at either makes a file not docs or runs a + job, so a pull request cannot free a file by removing it from the list. Whether a file is named by no job (so + every job runs) is judged by the base's entries only: a pull request that adds an entry for a root file, even with + a new module, adds that job but cannot stop the full run. A list that could drop a rule quietly is an error: a kept object with none of the `field` keys, a `field` key no kept object has (a typo, or a `where` that keeps nothing), or an entry that is not a plain repository path (`./x`, `/x`, `x/../y`, `x//y`, a wildcard), which could never match. - `docs_only_events`: events that may be docs-only (default `["pull_request"]`). @@ -145,13 +153,14 @@ runs in full for it; pin only SHAs that this fork's CI tested and tagged. ## Fails closed -A full run (and `jobs` = `{}`) for: an event without a base, HEAD that is not `$GITHUB_SHA`, a pull_request HEAD -that is not GitHub's merge commit (two parents, HEAD^2 = the event's PR head; no event file), no merge base (shallow -checkout), a base that is not a commit, a git error, an empty change, a config path that is not plain, no config at +A full run (and `jobs` = `{}`) for: an event without a base, a base off HEAD's first-parent line, HEAD that is not +`$GITHUB_SHA`, a pull_request HEAD that is not GitHub's merge commit (two parents, HEAD^2 = the event's PR head; no +event file), no merge base (shallow checkout), a base that is not a commit, a git error, an empty change, a config path that is not plain, no config at the base, a config that does not parse or has unknown keys or wrong types, a `*_from` file at neither side or not readable as configured (not UTF-8, nested too deep, a missing field, an entry that is not a plain path). Any other error is caught too and gives a full run with its message, never a step without outputs. A symlink or submodule is -never docs. +never docs, and the diff uses `--ignore-submodules=none`, so neither `ignore = all` in `.gitmodules` nor the runner's +`diff.ignoreSubmodules` can hide a gitlink bump. ## Tests diff --git a/fork-ci/actions/docs-scope/action.yml b/fork-ci/actions/docs-scope/action.yml index 5e76b2883554d..6a0e7dc90f0a1 100644 --- a/fork-ci/actions/docs-scope/action.yml +++ b/fork-ci/actions/docs-scope/action.yml @@ -12,7 +12,8 @@ inputs: base: description: >- Events other than pull_request only: the commit to compare HEAD with, the last commit whose - run passed (never github.event.before: see README). Empty: such runs run in full. + push run passed (event=push; never github.event.before: see README), on HEAD's first-parent + line. Empty or off that line: such runs run in full. required: false default: "" outputs: diff --git a/fork-ci/actions/docs-scope/docs-scope.test.py b/fork-ci/actions/docs-scope/docs-scope.test.py index 8c8a294e878a8..e69ad4d30ff48 100644 --- a/fork-ci/actions/docs-scope/docs-scope.test.py +++ b/fork-ci/actions/docs-scope/docs-scope.test.py @@ -10,6 +10,7 @@ HERE = os.path.dirname(os.path.abspath(__file__)) SCRIPT = os.path.join(HERE, 'docs_scope.py') ACTION = os.path.join(HERE, 'action.yml') +README = os.path.join(HERE, 'README.md') CONFIG_PATH = '.github/docs-scope.json' ENV = {'GIT_AUTHOR_NAME': 't', 'GIT_AUTHOR_EMAIL': 't@t', 'GIT_COMMITTER_NAME': 't', 'GIT_COMMITTER_EMAIL': 't@t', 'GIT_CONFIG_GLOBAL': os.devnull, 'GIT_CONFIG_NOSYSTEM': '1'} @@ -114,7 +115,7 @@ def scope(self, event='pull_request', base='', config=CONFIG_PATH, sha=None, hea self.assertEqual(stdout.startswith('docs-only: '), m[1] == 'true', stdout) self.assertEqual(m[3], stdout.splitlines()[0]) for line in stdout.splitlines(): # a file name never starts a line: no ::workflow-command:: - self.assertRegex(line, r'^(docs-only|full run|not docs-only|job [^:]+):', stdout) + self.assertRegex(line, r'^(docs-only|full run|scoped run|not docs-only|job [^:]+):', stdout) self.assertTrue(line.isprintable(), repr(line)) return m[1] == 'true', json.loads(m[2]), stdout @@ -218,6 +219,63 @@ def test_a_pr_that_drops_a_jobs_entry_still_runs_the_job(self): self.assertEqual(self.scope()[1], {'plugins': 'true', 'engine': 'true'}) +class RegistryAtTheHead(Repo): + """The PR's own registry entries may add a job, never cancel "a file no job names runs every job": the rules that + judge a PR come from the base. The registry sits in a job's paths (the common case), so its change alone does not + run every job.""" + config = {**CONFIG, 'jobs': {'plugins': {'paths': ['plugins/**']}, + 'engine': {**CONFIG['jobs']['engine'], 'paths': ['engine/**', 'tools/**']}}} + + def add(self, *modules): + return json.dumps({'modules': REGISTRY['modules'] + list(modules)}) + + def test_a_head_only_entry_cannot_claim_a_file_no_job_names(self): # even innocently: a new module lists it + self.pr({REGISTRY_PATH: self.add({'id': 'root', 'kind': 'engine-module', 'inputs': ['build.gradle']}), + 'build.gradle': 'x'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'true'}), out) + self.assertIn('full run: build.gradle is not a docs file', out.splitlines()[0]) + self.assertIn('which no job names at the base: every job runs', out.splitlines()[0]) + + def test_a_head_only_entry_still_adds_its_job(self): + self.pr({REGISTRY_PATH: self.add({'id': 'new', 'kind': 'engine-module', 'inputs': ['plugins/new/X.java']}), + 'plugins/new/X.java': 'x'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'true'}), out) + self.assertIn('job engine: run (plugins/new/X.java matches new inputs', out) + + +class Submodules(Repo): + """A gitlink bump is never docs, whatever .gitmodules (at the base, so in the checkout) or the runner's git config + says about ignoring submodules.""" + + def setUp(self): + super().setUp() + os.makedirs(os.path.join(self.d, 'lib')) # an uninitialised submodule: an empty folder + self.write({'.gitmodules': '[submodule "lib"]\n\tpath = lib\n\turl = ./lib\n\tignore = all\n'}) + self.git('update-index', '--add', '--cacheinfo', f'160000,{"1" * 40},lib') + self.base = self.commit('a submodule that .gitmodules ignores') + + def bump(self): + self.git('checkout', '-q', '-b', 'pr', self.base) + self.git('update-index', '--cacheinfo', f'160000,{"2" * 40},lib') + self.commit('bump lib', {'README.md': 'y'}) + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '-m', 'merge', 'pr') + + def test_a_submodule_bump_with_ignore_all_in_gitmodules(self): + self.bump() + self.assertIn('lib is a symlink or submodule', self.assertDocsOnly(False)) + + def test_a_submodule_bump_with_diff_ignore_submodules_in_the_git_config(self): + self.write({'.gitmodules': None}) # only the runner's config hides it now (the base still has .gitmodules) + self.git('rm', '-q', '--cached', '.gitmodules') + self.base = self.commit('no .gitmodules') + self.git('config', 'diff.ignoreSubmodules', 'all') + self.bump() + self.assertIn('lib is a symlink or submodule', self.assertDocsOnly(False)) + + class FailsClosed(Repo): def test_events_without_a_base_are_full_runs(self): self.pr({'README.md': 'y'}) @@ -440,7 +498,8 @@ def test_a_bad_source_entry_names_itself(self): # wrong types and typos in a * ({'where': ['kind']}, 'needs a plain file path'), ({'label': 3}, 'needs a plain file path'), ({'list': None}, 'needs a plain file path'), ({'file': './' + REGISTRY_PATH}, 'needs a plain'), ({'field': ['inputs', 'inptus']}, "no kept object has the field(s) ['inptus']"), - ({'where': {'kind': 'plugn'}}, "no kept object has the field(s) ['inputs']")): + ({'where': {'kind': 'plugn'}}, "no kept object has the field(s) ['inputs']"), + ({'wehre': {'kind': 'plugin'}}, 'no other keys than')): # a typo key drops no filter with self.subTest(bad=bad): self.reset() self.commit('bad source', {CONFIG_PATH: json.dumps({**CONFIG, 'never_docs_from': [{**source, **bad}]})}) @@ -449,6 +508,16 @@ def test_a_bad_source_entry_names_itself(self): # wrong types and typos in a * self.assertEqual((docs, jobs), (False, {}), out) self.assertIn(why, out) + def test_an_unknown_key_in_a_paths_from_entry(self): # "wehre" would drop the kind filter: the job runs more + engine = CONFIG['jobs']['engine'] + source = {**{k: v for k, v in engine['paths_from'][0].items() if k != 'where'}, 'wehre': {'kind': 'x'}} + self.commit('typo', {CONFIG_PATH: json.dumps( + {**CONFIG, 'jobs': {**CONFIG['jobs'], 'engine': {**engine, 'paths_from': [source]}}})}) + self.pr({'README.md': 'y'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('jobs.engine.paths_from entry', out) + class LooseConfig(Repo): config = {'docs': ['**']} # everything is docs, except the config itself @@ -496,6 +565,17 @@ def test_an_md_input_in_a_job_folder_runs_it(self): self.pr({'engine/core/src/main/resources/help.md': 'y'}) self.assertEqual(self.scope()[1]['engine'], 'true') + def test_a_scoped_run_says_so_and_a_full_run_says_full(self): # the reason matches what the jobs do + self.pr({'engine/A.java': 'class A {}'}) + docs, jobs, out = self.scope() + self.assertEqual(jobs, {'plugins': 'false', 'engine': 'true'}, out) + self.assertTrue(out.startswith('scoped run: engine/A.java is not a docs file; only the jobs'), out) + self.reset() + self.pr({'engine/A.java': 'class A {}', 'app/Main.java': 'x'}) + docs, jobs, out = self.scope() + self.assertEqual(jobs, {'plugins': 'true', 'engine': 'true'}, out) + self.assertTrue(out.startswith('full run: app/Main.java is not a docs file and 1 more, which no job'), out) + def test_docs_only_skips_every_job(self): self.pr({'README.md': 'y'}) self.assertEqual(self.scope()[:2], (True, {'plugins': 'false', 'engine': 'false'})) @@ -537,6 +617,18 @@ def test_docs_only_events_can_name_push(self): self.commit('docs', {'README.md': 'y'}) self.assertTrue(self.scope('push', self.base)[0]) + def test_a_base_off_the_first_parent_line_is_a_full_run(self): # a merged fork PR's head was never tested + self.commit('code A (its run went red)', {'engine/A.java': 'class A {}'}) + self.git('checkout', '-q', '-b', 'fork-main') + fork_pr_head = self.commit('docs (its pull_request run passed)', {'README.md': 'y'}) + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--no-ff', '-m', 'merge the fork PR', 'fork-main') + self.commit('docs push', {'docs/a.md': 'z'}) + docs, jobs, out = self.scope('push', fork_pr_head) + self.assertEqual((docs, jobs), (False, {}), out) + self.assertIn('not on the first-parent line', out) + self.assertEqual(self.scope('push', self.base)[1], {'plugins': 'false', 'engine': 'true'}) # main's green + def test_a_base_that_is_not_a_commit(self): self.commit('docs', {'README.md': 'y'}) docs, jobs, out = self.scope('push', '0' * 40) @@ -566,6 +658,15 @@ def test_globs(self): self.assertFalse(glob_re(pattern).match(p), (pattern, p)) +class Readme(unittest.TestCase): + def test_the_last_green_query_takes_push_runs_only(self): # `branch` matches a fork PR's head branch "main" too + with open(README) as f: + queries = re.findall(r'/runs\?([^"\s]*)', f.read()) + self.assertTrue(queries) + for q in queries: + self.assertLessEqual({'branch=main', 'status=success', 'event=push'}, set(q.split('&')), q) + + class Action(unittest.TestCase): """action.yml runs only this folder's script (the caller's pinned SHA), never a file from the checkout.""" text = open(ACTION).read() diff --git a/fork-ci/actions/docs-scope/docs_scope.py b/fork-ci/actions/docs-scope/docs_scope.py index 171a213e659fa..31626eae2b683 100644 --- a/fork-ci/actions/docs-scope/docs_scope.py +++ b/fork-ci/actions/docs-scope/docs_scope.py @@ -7,17 +7,20 @@ base .. GitHub's merge commit (what merging changes on the base it was tested with). HEAD must be GitHub's merge commit (refs/pull/N/merge): HEAD == $GITHUB_SHA, two parents, and HEAD^2 == the event's pull_request.head.sha. Only then is HEAD^1 the base (a checkout of a PR head that merged main in would otherwise pose as one). - - any other event: --base .. HEAD, only when the caller gives --base (the last commit whose run passed; never - github.event.before, see README) and HEAD == $GITHUB_SHA. + - any other event: --base .. HEAD, only when the caller gives --base (the last commit whose push run passed; never + github.event.before, see README), HEAD == $GITHUB_SHA and the base is on HEAD's first-parent line (a commit that + reached the branch through a merge's second parent, such as a fork PR's head, was never tested as the branch). A path is docs when it is a plain file (no symlink or submodule), matches a `docs` glob, is not the config file, and matches no `never_docs` glob or `never_docs_from` entry, and its name has no control character and is UTF-8. The change is docs-only when every path is docs and the event is in `docs_only_events`. A job runs when a path that is not docs matches its `paths` or `paths_from`; every job runs when such a path matches no job, or when the config changed. +"Matches no job" is judged by the base's entries only: a head-only `*_from` entry can add a job, never stop a full run. The config is read from the BASE commit, never from the checkout, and this script runs from the action's own folder at the caller's pinned SHA: a pull request cannot loosen the rules or the code that judge it. `*_from` files are read -at the base and the head; an entry at either counts. +at the base and the head: an entry at either makes a file not docs or runs a job, but only the base's entries can keep +a file that no job names from running every job. Fails closed: anything unclear, including an error this script did not foresee, means docs_only=false and every job runs, with the reason printed. Jobs missing from the `jobs` output (config unreadable) must be read as "run": callers @@ -75,7 +78,8 @@ def glob_re(pattern): def changes(a, b, run=git): """[(path, old mode, new mode)] between commits a and b, renames as delete + add; None on a git error.""" - out = run('diff', '--raw', '--no-renames', '--no-abbrev', '-z', a, b) + # --ignore-submodules=none: a .gitmodules `ignore = all` or a runner's diff.ignoreSubmodules hides no gitlink bump + out = run('diff', '--raw', '--no-renames', '--no-abbrev', '--ignore-submodules=none', '-z', a, b) if out is None: return None parts, rows = out.split('\0'), [] @@ -123,6 +127,9 @@ def the_change(event, head, base, run=git, sha='', event_path=''): resolved = (run('rev-parse', '-q', '--verify', f'{base}^{{commit}}') or '').strip() if not resolved: raise Unclear(f'the base {base} is not a commit here (shallow checkout or force push?)') + if resolved not in (run('rev-list', '--first-parent', head) or '').split(): + raise Unclear(f'the base {resolved[:10]} is not on the first-parent line of {head} (a merged branch\'s ' + f'commit, another branch, or a force push): it was never tested as this branch') base, pairs, what = resolved, ((resolved, head),), f'the base {resolved[:10]}' rows = [] for a, b in pairs: @@ -186,12 +193,14 @@ def load_config(path, ref, run=git): def read_entries(src, refs, run=git): - """{path prefix: label} of every entry the source names at any ref; Unclear if no ref has the file, or one is + """[{path prefix: label} per ref, {} where the file is not]; Unclear if no ref has the file, or one is malformed: an object without any named field, a field no kept object has (a typo; none kept), or an entry that is not a plain path (./, /, .., a wildcard) and so could never match. Entries match a path exactly or as a folder.""" - found, read = {}, False + per_ref, read = [], False fields = src['field'] if isinstance(src['field'], list) else [src['field']] for ref in refs: + found = {} + per_ref.append(found) text = run('show', f'{ref}:{src["file"]}') if text is None: continue @@ -221,7 +230,11 @@ def read_entries(src, refs, run=git): read = True if not read: raise Unclear(f'{src["file"]} is at neither the base nor the head: its entries are unknown') - return found + return per_ref + + +def union(per_ref): + return {k: v for found in per_ref for k, v in found.items()} def entry_match(path, entries): @@ -239,9 +252,11 @@ def decide(event, config_path, head='HEAD', base='', run=git, sha='', event_path rows, cbase, what = the_change(event, head, base, run, sha, event_path) c = load_config(config_path, cbase, run) refs = (cbase, head) - never_from = [(s, read_entries(s, refs, run)) for s in c['never_docs_from']] - jobs = {n: ([glob_re(g) for g in j['paths']], [read_entries(s, refs, run) for s in j['paths_from']]) - for n, j in c['jobs'].items()} + never_from = [(s, union(read_entries(s, refs, run))) for s in c['never_docs_from']] + jobs = {} # name -> (globs, entries at the base or the head (run the job), entries at the base (judge "every")) + for n, j in c['jobs'].items(): + per = [read_entries(s, refs, run) for s in j['paths_from']] + jobs[n] = ([glob_re(g) for g in j['paths']], [union(p) for p in per], [p[0] for p in per]) except Unclear as e: return False, {}, [f'full run: {e}'] docs_globs = [glob_re(g) for g in c['docs']] @@ -276,18 +291,21 @@ def job_hit(p, globs, froms): return next((f'{m[1]}: {m[0]}' for e in froms for m in [entry_match(p, e)] if m), None) # A file that is not docs but that no job names (a root build file, a workflow, the config): every job runs. + # "Names" by the base's rules only: the PR's own registry entries may add a job, never cancel the full run. every = (config_path if config_path in not_docs else - next((p for p in not_docs if not any(job_hit(p, *j) for j in jobs.values())), None)) - if not_docs: - first = every or next(iter(not_docs)) - more = f' and {len(not_docs) - 1} more' if len(not_docs) > 1 else '' - tail = ', which no job names: every job runs' if every and every != config_path else ( - ': every job runs' if every else '') - lines.append(f'full run: {first} is {not_docs[first]}{more}{tail}') + next((p for p in not_docs if not any(job_hit(p, globs, base_froms) + for globs, _, base_froms in jobs.values())), None)) + more = f' and {len(not_docs) - 1} more' if len(not_docs) > 1 else '' + if every: + tail = ': every job runs' if every == config_path else ', which no job names at the base: every job runs' + lines.append(f'full run: {every} is {not_docs[every]}{more}{tail}') + elif not_docs: + first = next(iter(not_docs)) + lines.append(f'scoped run: {first} is {not_docs[first]}{more}; only the jobs these files reach run') else: lines.append(f'not docs-only: only docs changed, but a {event or "unknown"} run is not in docs_only_events') out = {} - for n, (globs, froms) in jobs.items(): + for n, (globs, froms, _) in jobs.items(): hit = None if every else next(((p, h) for p in not_docs for h in [job_hit(p, globs, froms)] if h), None) out[n] = 'true' if every or hit else 'false' lines.append(f'job {n}: run (every job runs for {every})' if every else From 044948aac69ad79ec3e87d6ea2953866f76dde9b Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:25:13 +0000 Subject: [PATCH 4/5] fork-ci docs-scope: test that never_docs_from is read at the PR head too; wrap three README lines A PR that adds a registry entry for docs/manual.md and edits that file runs every job. Reading never_docs_from at the base only turns this test red (docs-only, every job skipped). Co-Authored-By: Claude Opus 5.5 --- fork-ci/actions/docs-scope/README.md | 31 ++++++++++--------- fork-ci/actions/docs-scope/docs-scope.test.py | 11 ++++++- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/fork-ci/actions/docs-scope/README.md b/fork-ci/actions/docs-scope/README.md index 2f181b0f9164e..b42889b6ae15c 100644 --- a/fork-ci/actions/docs-scope/README.md +++ b/fork-ci/actions/docs-scope/README.md @@ -66,9 +66,9 @@ printed escaped (`\n`, `\udcff`), so a file name can neither start a `::workflow last commit merged main in, HEAD^1 would be the PR's own commit, the PR's code would drop out of both diffs and the config would be read from the PR. - **Any other event** (push, merge_group, workflow_dispatch): `base` .. HEAD, only when the caller gives `base` and - HEAD == `$GITHUB_SHA`, and the base must be on HEAD's first-parent line. Without a base the run is a full run. Such an event is docs-only only when - `docs_only_events` names it; its `jobs` are read either way, so a docs-only push to main can still skip the build - jobs. + HEAD == `$GITHUB_SHA`, and the base must be on HEAD's first-parent line. Without a base the run is a full run. Such + an event is docs-only only when `docs_only_events` names it; its `jobs` are read either way, so a docs-only push to + main can still skip the build jobs. ### The base on push @@ -127,12 +127,13 @@ the diff to commits a passing push run already tested. - `never_docs_from` / `paths_from`: paths listed in a JSON file of the repository. `list` is a dotted key to a list of objects (none: the file itself), `where` keeps the objects whose keys equal these values, `field` names the key (or keys) holding a path or a list of paths, `label` names an object in the log. An entry matches a path exactly or - as a folder. The file is read at the base and at the head; an entry at either makes a file not docs or runs a - job, so a pull request cannot free a file by removing it from the list. Whether a file is named by no job (so - every job runs) is judged by the base's entries only: a pull request that adds an entry for a root file, even with - a new module, adds that job but cannot stop the full run. A list that could drop a rule quietly is an error: a kept object with - none of the `field` keys, a `field` key no kept object has (a typo, or a `where` that keeps nothing), or an entry - that is not a plain repository path (`./x`, `/x`, `x/../y`, `x//y`, a wildcard), which could never match. + as a folder. The file is read at the base and at the head; an entry at either makes a file not docs or runs a job, + so a pull request cannot free a file by removing it from the list. Whether a file is named by no job (so every job + runs) is judged by the base's entries only: a pull request that adds an entry for a root file, even with a new + module, adds that job but cannot stop the full run. A list that could drop a rule quietly is an error: a kept + object with none of the `field` keys, a `field` key no kept object has (a typo, or a `where` that keeps nothing), + or an entry that is not a plain repository path (`./x`, `/x`, `x/../y`, `x//y`, a wildcard), which could never + match. - `docs_only_events`: events that may be docs-only (default `["pull_request"]`). - `jobs`: per job, `paths` globs and `paths_from` lists. Docs files never run a job; a `never_docs` file does. A file that is not docs and that no job names runs every job, and so does a change to the config. @@ -155,12 +156,12 @@ runs in full for it; pin only SHAs that this fork's CI tested and tagged. A full run (and `jobs` = `{}`) for: an event without a base, a base off HEAD's first-parent line, HEAD that is not `$GITHUB_SHA`, a pull_request HEAD that is not GitHub's merge commit (two parents, HEAD^2 = the event's PR head; no -event file), no merge base (shallow checkout), a base that is not a commit, a git error, an empty change, a config path that is not plain, no config at -the base, a config that does not parse or has unknown keys or wrong types, a `*_from` file at neither side or not -readable as configured (not UTF-8, nested too deep, a missing field, an entry that is not a plain path). Any other -error is caught too and gives a full run with its message, never a step without outputs. A symlink or submodule is -never docs, and the diff uses `--ignore-submodules=none`, so neither `ignore = all` in `.gitmodules` nor the runner's -`diff.ignoreSubmodules` can hide a gitlink bump. +event file), no merge base (shallow checkout), a base that is not a commit, a git error, an empty change, a config +path that is not plain, no config at the base, a config that does not parse or has unknown keys or wrong types, a +`*_from` file at neither side or not readable as configured (not UTF-8, nested too deep, a missing field, an entry +that is not a plain path). Any other error is caught too and gives a full run with its message, never a step without +outputs. A symlink or submodule is never docs, and the diff uses `--ignore-submodules=none`, so neither +`ignore = all` in `.gitmodules` nor the runner's `diff.ignoreSubmodules` can hide a gitlink bump. ## Tests diff --git a/fork-ci/actions/docs-scope/docs-scope.test.py b/fork-ci/actions/docs-scope/docs-scope.test.py index e69ad4d30ff48..ce3d787c8ff99 100644 --- a/fork-ci/actions/docs-scope/docs-scope.test.py +++ b/fork-ci/actions/docs-scope/docs-scope.test.py @@ -201,7 +201,8 @@ def test_an_md_newly_listed_in_the_registry_by_main(self): # read at the base class RegistryAtTheBase(Repo): """A pull request cannot free a file by deleting its entry: the base's entries count. Here the registry change - itself does not decide (it is docs, or a job's own path), so only the base read can.""" + itself does not decide (it is docs, or a job's own path), so only the registry read can (an entry the PR adds + counts too: never_docs_from is read at the head as well).""" config = {'docs': ['**'], 'never_docs_from': CONFIG['never_docs_from'], 'jobs': {'plugins': {'paths': ['plugins/**', 'tools/**']}, 'engine': CONFIG['jobs']['engine']}} @@ -218,6 +219,14 @@ def test_a_pr_that_drops_a_jobs_entry_still_runs_the_job(self): self.pr({REGISTRY_PATH: self.drop('content-locale'), 'plugins/locale/common/src/main/java/Wire.java': 'x'}) self.assertEqual(self.scope()[1], {'plugins': 'true', 'engine': 'true'}) + def test_a_pr_that_adds_a_never_docs_entry_counts_it_at_the_head(self): # never_docs_from read at both sides + self.pr({REGISTRY_PATH: json.dumps({'modules': REGISTRY['modules'] + [{'id': 'manual', + 'inputs': ['docs/manual.md']}]}), + 'docs/manual.md': 'y'}) + docs, jobs, out = self.scope() + self.assertEqual((docs, jobs), (False, {'plugins': 'true', 'engine': 'true'}), out) + self.assertIn('manual inputs: docs/manual.md', out) + class RegistryAtTheHead(Repo): """The PR's own registry entries may add a job, never cancel "a file no job names runs every job": the rules that From 467079923b2d9d71ae5b9cd6b0237bb1085a4571 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:14:36 +0000 Subject: [PATCH 5/5] fork-ci docs-scope: every test starts with no GITHUB_* variable (the runner's event file leaked in) test_no_github_sha_or_event_is_a_full_run [event file] failed on fork CI run 43452154314: scope() built the script's env from os.environ and set GITHUB_EVENT_PATH only when the test gave a head sha, so the job's own event file stood in for the unset one. A CleanEnv base class now strips every GITHUB_* key from os.environ for each test (restored after); Repo, Globs, Readme and Action derive from it. Red with GITHUB_EVENT_PATH set to a real event file before, green after. Co-Authored-By: Claude Opus 5.5 --- fork-ci/actions/docs-scope/docs-scope.test.py | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/fork-ci/actions/docs-scope/docs-scope.test.py b/fork-ci/actions/docs-scope/docs-scope.test.py index ce3d787c8ff99..f8164a2a27e08 100644 --- a/fork-ci/actions/docs-scope/docs-scope.test.py +++ b/fork-ci/actions/docs-scope/docs-scope.test.py @@ -4,6 +4,7 @@ Run: python3 fork-ci/actions/docs-scope/docs-scope.test.py """ import contextlib, json, os, re, shutil, subprocess, sys, tempfile, unittest +from unittest import mock sys.dont_write_bytecode = True # the Globs test imports docs_scope.py: leave no __pycache__ in the action folder @@ -45,10 +46,24 @@ } -class Repo(unittest.TestCase): +class CleanEnv(unittest.TestCase): + """Every test starts with no GITHUB_* variable. On a runner the job's own GITHUB_EVENT_PATH, GITHUB_SHA and + GITHUB_OUTPUT would otherwise reach the script (fork CI run 43452154314: the job's event file stood in for the + one a test leaves unset). os.environ is restored after each test.""" + + def setUp(self): + patcher = mock.patch.dict(os.environ) + patcher.start() + self.addCleanup(patcher.stop) + for key in [k for k in os.environ if k.startswith('GITHUB_')]: + del os.environ[key] + + +class Repo(CleanEnv): config = CONFIG def setUp(self): + super().setUp() self.d = tempfile.mkdtemp(prefix='docs-scope-') self.addCleanup(shutil.rmtree, self.d, True) self.git('init', '-q', '-b', 'main') @@ -645,7 +660,7 @@ def test_a_base_that_is_not_a_commit(self): self.assertIn('not a commit here', out) -class Globs(unittest.TestCase): +class Globs(CleanEnv): def test_globs(self): sys.path.insert(0, HERE) try: @@ -667,7 +682,7 @@ def test_globs(self): self.assertFalse(glob_re(pattern).match(p), (pattern, p)) -class Readme(unittest.TestCase): +class Readme(CleanEnv): def test_the_last_green_query_takes_push_runs_only(self): # `branch` matches a fork PR's head branch "main" too with open(README) as f: queries = re.findall(r'/runs\?([^"\s]*)', f.read()) @@ -676,7 +691,7 @@ def test_the_last_green_query_takes_push_runs_only(self): # `branch` matches a self.assertLessEqual({'branch=main', 'status=success', 'event=push'}, set(q.split('&')), q) -class Action(unittest.TestCase): +class Action(CleanEnv): """action.yml runs only this folder's script (the caller's pinned SHA), never a file from the checkout.""" text = open(ACTION).read()