From 71451adcbd5d7d6cc7137f3391980a613f5b8da4 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 10:46:23 +0000 Subject: [PATCH 1/2] fork-ci: test list reads one line per test; doc-check fails closed (#789, #908) fork-ci-tests (#789): - readList refuses a file listed twice (a part and --run could read different lines). - The "cannot read" error reads plainly. - The list says a test the runner does not run (stage-preview-bundle, a plain python3 step) is not judged by its format word; fork-ci-tests.test.cjs now checks that word against the test's source. - The header says an ok-lines test's own count is trusted. doc-check (#908): - A symlink is checked as the file it points to (a change of type is a change); one out of the repository or to no file fails. - A file that is not UTF-8 or cannot be read fails, and its size is still checked. - Sizes are the bytes on disk, so CRLF counts. - With --base, a doc the change deletes or renames that an untouched file still links to fails. - Links in inline code, in a fence inside a list item, or with a ?query are no longer reported broken; the README says the workflow file is guarded by review only. Co-Authored-By: Claude Opus 5.5 --- .github/fork-ci-tests.txt | 9 +- .github/scripts/fork-ci-tests.cjs | 9 +- .github/scripts/fork-ci-tests.test.cjs | 43 ++++++ fork-ci/actions/doc-check/README.md | 16 ++- fork-ci/actions/doc-check/doc_check.py | 143 +++++++++++++++----- fork-ci/actions/doc-check/doc_check.test.py | 93 ++++++++++++- 6 files changed, 262 insertions(+), 51 deletions(-) diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index 15b760440079c..d47ded03a8674 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -15,7 +15,10 @@ # ... ok lines two) its format: its tests are unittest tests, counted through # fork-ci-unittest.py, or it prints ok lines, below. The runner judges # it by this word alone: a unittest test that wrote no plan line, or an -# ok-lines test without its end line, counts nothing +# ok-lines test without its end line, counts nothing. A test the runner +# does not run (upstream's, run by a plain step) is not judged by its +# word: fork-ci-tests.test.cjs checks the word against its source +# A test is listed once. # A test's own `fork-ci:` comment lines say more (the runner reads them): # fork-ci: run [as root] [with _TESTS=value ...] [only [.]] # an own run, by `fork-ci-tests.cjs --run ` in fork-tests.yml; @@ -35,7 +38,8 @@ # node through fork-ci-node-counts.cjs (a file that reports no test of its own, or stops # half-way, counts nothing); an ok-lines test (sh, or Python with "ok lines": `ok `, # `FAIL `, `skip [why]` on stdout) ends with "all passed: ok, skipped" -# (its own count), else it counts nothing. +# (its own count), else it counts nothing. Its count is trusted: one that prints a matching end +# line and stops before its other checks passes, so a new Python test is best a unittest test. # A present test that is not listed fails. A listed file that is not present yet # is a note; one that was present and then deleted fails. .github/scripts/fork-ci-tests.test.cjs ~11s @@ -162,6 +166,7 @@ fork-kit/schedule-kick/tests/late.test.py unittest .github/scripts/check-nightly-release.test.cjs run by .github/workflows/fork-tests.yml .github/scripts/mobile-preview-comment.test.cjs run by .github/workflows/fork-tests.yml .github/scripts/mobile-ios-preview-record.test.cjs run by .github/workflows/fork-tests.yml +# A plain `python3` step runs this one: its word is checked against its source, not by the runner. .github/scripts/stage-preview-bundle.test.py run by .github/workflows/fork-tests.yml unittest .github/scripts/test-delta.test.cjs run by .github/workflows/fork-tests.yml .github/scripts/vercel-deployment-output.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 e96c18608cbee..91da5cf8990ec 100644 --- a/.github/scripts/fork-ci-tests.cjs +++ b/.github/scripts/fork-ci-tests.cjs @@ -166,6 +166,7 @@ function plan(entries, present, ever, read = () => null, allowed = RUN_ELSEWHERE } function readList(text) { + const seen = new Set(); return text .split("\n") .map((line) => line.replace(/#.*/, "").trim()) @@ -176,9 +177,13 @@ function readList(text) { ); if (!match) throw new Error( - `${LIST}: cannot read "${line}" (expected "", " ~s" or " run by ", ` + - `a Python test's then ending in its format: "unittest" or "ok lines")`, + `${LIST}: cannot read "${line}" (expected "", " ~s" or " run by "; ` + + `a Python test's line then ends in its format: "unittest" or "ok lines")`, ); + // One line per test: two would let a part and `--run` each read a different one. + if (seen.has(match[1])) + throw new Error(`${LIST}: "${match[1]}" is listed twice (one line per test)`); + seen.add(match[1]); // A Python test has two formats (countTests()), and says which: none is read as the other. const python = match[1].endsWith(".py"); if (match[4] && !python) diff --git a/.github/scripts/fork-ci-tests.test.cjs b/.github/scripts/fork-ci-tests.test.cjs index 440da9ad940eb..740d82f0daec0 100644 --- a/.github/scripts/fork-ci-tests.test.cjs +++ b/.github/scripts/fork-ci-tests.test.cjs @@ -269,6 +269,49 @@ test("the list ignores comments and blank lines and reads `run by` and weights", "a.test.py Unittest", ]) assert.throws(() => readList(`${bad}\n`), /cannot read/, bad); + assert.throws( + () => readList("a.test.py unittest ~12s\n"), + /"; a Python test's line then ends in its format: "unittest" or "ok lines"\)$/, + ); + // One line per test: a second line for a file is refused, whatever it says (#789). + for (const twice of [ + "a.test.sh\nb.test.sh\na.test.sh\n", + "a.test.py unittest\na.test.py ok lines\n", + "a.test.py ~40s unittest\na.test.py run by c.yml unittest\n", + ]) + assert.throws( + () => readList(twice), + /"a\.test\.(sh|py)" is listed twice \(one line per test\)/, + twice, + ); +}); + +// A Python test the runner never runs (upstream's, which a plain step runs) leaves no record, so the runner never reads +// its format word: its word is checked here against its source instead (#789). +test("a listed Python test the runner does not judge says the format its source has", () => { + const root = path.resolve(__dirname, "../.."); + const read = (file) => fs.readFileSync(path.join(root, file), "utf8"); + const entries = readList(read(".github/fork-ci-tests.txt")); + const present = entries.map((e) => e.file).filter((file) => fs.existsSync(path.join(root, file))); + const keys = expectedKeys(entries, present, read); + const unjudged = entries.filter( + (e) => + e.format && + present.includes(e.file) && + !keys.some((key) => key === e.file || key.startsWith(`${e.file} --run`)), + ); + assert.ok(unjudged.some((e) => e.file === ".github/scripts/stage-preview-bundle.test.py")); + for (const { file, format } of unjudged) { + const text = read(file); + const unittest = /\bunittest\.main\(|\bunittest\.TestCase\b|\bTextTestRunner\b/.test(text); + const okLines = /all passed: /.test(text); + assert.equal(unittest !== okLines, true, `${file}: its source shows no single format`); + assert.equal( + format, + unittest ? "unittest" : "ok lines", + `${file}: its source is ${unittest ? "unittest" : "ok lines"}`, + ); + } }); test("the heaviest tests start first, tests without a weight before them, ties in list order", () => { diff --git a/fork-ci/actions/doc-check/README.md b/fork-ci/actions/doc-check/README.md index a63621a25c826..87dacf480fbfd 100644 --- a/fork-ci/actions/doc-check/README.md +++ b/fork-ci/actions/doc-check/README.md @@ -7,8 +7,11 @@ action fails a pull request that: - puts an instruction file over its **size budget** (lines or bytes; above `warn_at` of a budget it only warns, and says when this change moved the file past it); - writes **history** into an instruction file (a changelog block, an "is live on" claim, a dated "Updated" banner); -- has a **broken relative link** in a Markdown file it adds or changes (code fences skipped; `/x` is from the - repository root, as GitHub reads it; a link that leaves the repository is broken); +- has a **broken relative link** in a Markdown file it adds or changes (code fences and inline code skipped; `/x` is + from the repository root, as GitHub reads it; a link that leaves the repository is broken), or deletes or renames a + file that another Markdown file still links to; +- has a checked file that is **not UTF-8** or cannot be read, or is a **symlink** out of the repository or to no + file (a symlink is checked as the file it points to; sizes are the bytes on disk, CRLF included); - **adds** a file whose name looks like a dated report, handoff or review (those go in the pull request or an issue). The general rules this enforces, and the rest of the agent rules, are in @@ -76,11 +79,12 @@ comments. An unknown key, a value of the wrong type or a pattern that is not a r - `links`: `false` turns link checks off. The config is read at the base commit, never from the checkout, so a pull request cannot loosen the rules that judge -it: a change to the config applies from the next pull request. `mode: all` and `--files` read it from the checkout. +it through the config: a change to the config applies from the next pull request. `mode: all` and `--files` read it +from the checkout. The workflow that calls this action is not covered by that: GitHub runs a pull request's own +workflow file, so a change that edits the step or removes it is stopped only by review of `.github/workflows/`. ## Not covered -- A deleted or renamed file breaks the links that point to it from files the change did not touch; `mode: all` +- Anchors (`#section`) and queries (`?plain=1`) are not checked, and neither are backticked paths in the text. +- A broken link that was already on the base in a file the change does not touch is not this change's: `mode: all` finds those. -- Anchors (`#section`) are not checked, and neither are backticked paths in the text. -- A symlinked Markdown file is listed as a warning and not checked. diff --git a/fork-ci/actions/doc-check/doc_check.py b/fork-ci/actions/doc-check/doc_check.py index d3ba2ddf387de..27ec218013e66 100644 --- a/fork-ci/actions/doc-check/doc_check.py +++ b/fork-ci/actions/doc-check/doc_check.py @@ -4,15 +4,19 @@ * size budgets (lines and bytes) for instruction files, matched by glob, first match wins; above `warn_at` of a budget a WARN line that never fails; * no history in instruction files (changelog blocks, "is live on" claims, dated "Updated" banners); - * every relative link resolves to a file or folder in the repository (code fences are skipped; `/x` is from the - repository root, as GitHub reads it; a link that leaves the repository is broken); + * every relative link resolves to a file or folder in the repository (code fences and inline code are skipped; `/x` + is from the repository root, as GitHub reads it; a link that leaves the repository is broken); with --base, a + file the change deletes or renames away must have no link left to it in any file the config selects; * a newly added file whose name looks like a dated report, handoff or review belongs in the pull request or an - issue, not in the repository. + issue, not in the repository; + * a checked file is UTF-8 text that can be read (anything else fails, and its size is still checked); a symlink is + checked as the file it points to, which must be in the repository. Sizes are the bytes on disk (CRLF included). The rules come from the project's JSON config (README "Config"); every key is optional and a missing, empty or `{}` config means the defaults. With --base the config is read at the base commit, never from the checkout, so a change -cannot loosen the rules that judge it (a change to the config applies from the next change); with --all (or --files) it is read from the checkout. A config that is not -valid JSON, has an unknown key or a value of the wrong type is an error (exit 2), never a pass. +cannot loosen the rules that judge it through the config (a change to the config applies from the next change; the +calling workflow is the change's own, so only review guards it); with --all (or --files) it is read from the checkout. +A config that is not valid JSON, has an unknown key or a value of the wrong type is an error (exit 2), never a pass. python3 -I doc_check.py --base origin/main [--config .github/doc-check.json] # changed files (CI) python3 -I doc_check.py --all # every tracked .md file @@ -48,7 +52,9 @@ } FLAGS = {'i': re.I, 'm': re.M, 's': re.S} LINK = re.compile(r'\]\(\s*(?:<([^<>\n]+)>|([^()\s<>]+))(?:\s+(?:"[^"\n]*"|\'[^\'\n]*\'))?\s*\)') -FENCE = re.compile(r'^ {0,3}(`{3,}|~{3,})') +# Any indent: a fence inside a list item is indented more than three spaces. +FENCE = re.compile(r'^[ \t]*(`{3,}|~{3,})') +INLINE_CODE = re.compile(r'(`+)(?!`).*?(? 1: probs.append((path, None, f'{n} lines / {size} B, budget {b[1]} lines / {b[2]} B ({b[0]}): move ' 'sometimes-needed text into its own file (never raise the budget)')) @@ -230,7 +252,7 @@ def check(rules, path, text, added, root='.', base_text=None): probs.append((path, None, 'dated report, handoff or review file: put it in the pull request or an issue')) if rules['links']: for no, target in link_lines(text): - why = broken_link(path, target, root) + why = broken_link(links_from or path, target, root) if why: probs.append((path, no, f'broken link {target}: {why}')) return probs, warns @@ -241,16 +263,66 @@ def selected(rules, path): def changed_files(base): - """(merge base, [(path, added)]) of the files the change adds or modifies; renames count as added.""" + """(merge base, [(path, added)], [removed]): the files the change adds or modifies (a rename's new name counts as + added, and a change of type, such as a file turned into a symlink, as modified), and those it deletes (a rename's + old name).""" mb = git('merge-base', base, 'HEAD') if mb is None or not mb.strip(): raise ConfigError(f'no merge base of {base} and HEAD (check out with fetch-depth: 0)') mb = mb.strip() - out = git('diff', '--name-status', '--no-renames', '--diff-filter=AM', '-z', mb, 'HEAD') + out = git('diff', '--name-status', '--no-renames', '--diff-filter=AMTD', '-z', mb, 'HEAD') if out is None: raise ConfigError(f'git diff {mb}..HEAD failed') parts = out.split('\0') - return mb, [(parts[i + 1], parts[i] == 'A') for i in range(0, len(parts) - 1, 2)] + pairs = [(parts[i], parts[i + 1]) for i in range(0, len(parts) - 1, 2)] + return (mb, [(path, kind == 'A') for kind, path in pairs if kind != 'D'], + [path for kind, path in pairs if kind == 'D']) + + +def read_doc(path, root='.'): + """(exact text, links_from, problem) of a file to check. Undecodable bytes are kept (surrogateescape), so its + size is still checked; a symlink is read as the file it points to, which must be in the repository.""" + links_from = None + if os.path.islink(path): + real, real_root = os.path.realpath(path), os.path.realpath(root) + if os.path.commonpath([real_root, real]) != real_root: + return None, None, 'a symlink that points outside the repository: make it a file' + if not os.path.isfile(real): + return None, None, 'a symlink that points to no file: make it a file' + links_from = os.path.relpath(real, real_root) + try: + with open(path, 'rb') as f: + raw = f.read() + except OSError as e: + return None, None, f'cannot read it ({e.__class__.__name__})' + try: + return raw.decode('utf-8'), links_from, None + except UnicodeDecodeError as e: + return raw.decode('utf-8', 'surrogateescape'), links_from, f'not UTF-8 text (byte {e.start}): save it as UTF-8' + + +def links_to_removed(rules, removed, checked, root='.'): + """Problems for links, in selected tracked files this run did not check, to a file the change removed (or into a + folder it emptied) that no longer resolves.""" + gone = {os.path.normpath(p) for p in removed} + if not gone or not rules['links']: + return [] + out = git('ls-files', '-z') + if out is None: + raise ConfigError('git ls-files failed (run from the repository root)') + probs = [] + for path in out.split('\0'): + if not path or path in checked or not selected(rules, path) or not os.path.isfile(path): + continue + text, links_from, _ = read_doc(path, root) + for no, target in link_lines(lf(text or '')): + full = link_path(links_from or path, target, root) + if full is None or broken_link(links_from or path, target, root) is None: + continue + rel = os.path.relpath(full, root) + if rel in gone or any(g.startswith(rel + os.sep) for g in gone): + probs.append((path, no, f'broken link {target}: this change removed {rel}')) + return probs def annotate(kind, path, line, msg): @@ -272,10 +344,10 @@ def main(argv=None): if not a.base.strip(): raise ConfigError('--base is empty: give the base commit, or use --all') rules, note = load_config(a.config, a.base) - mb, files = changed_files(a.base) + mb, files, removed = changed_files(a.base) else: rules, note = load_config(a.config) - mb = None + mb, removed = None, [] if a.all: out = git('ls-files', '-z') if out is None: @@ -288,27 +360,30 @@ def main(argv=None): annotate('error', a.config, None, f'doc-check: {e}') return 2 print(f'doc_check: {shown(note)}') - probs, warns, count = [], [], 0 + probs, warns, count, checked = [], [], 0, set() for path, added in files: - if not selected(rules, path) or not os.path.isfile(path): + # A symlink to no file is checked (and fails); another path that is not a file is skipped. + if not selected(rules, path) or not (os.path.isfile(path) or os.path.islink(path)): continue count += 1 - if os.path.islink(path): - warns.append((path, None, 'a symlink: not checked')) - continue - try: - with open(path, encoding='utf-8') as f: - text = f.read() - except (OSError, UnicodeDecodeError) as e: - warns.append((path, None, f'cannot read it ({e.__class__.__name__}): not checked')) - continue + checked.add(path) + text, links_from, problem = read_doc(path) + if problem: + probs.append((path, None, problem)) + if text is None: + continue base_text = None - if mb is not None and budget(rules, path) is not None: + if mb is not None and budget(rules, path) is not None and links_from is None: old = git('show', f'{mb}:{path}') base_text = old if old is not None else '' - p, w = check(rules, path, text, added, '.', base_text) + p, w = check(rules, path, text, added, '.', base_text, links_from) probs += p warns += w + try: + probs += links_to_removed(rules, removed, checked) + except ConfigError as e: + print(f'doc_check: ERROR {shown(e)}') + return 2 for path, line, msg in probs: print(f'DOC {shown(path)}{":" + str(line) if line else ""}: {shown(msg)}') annotate('error', path, line, msg) diff --git a/fork-ci/actions/doc-check/doc_check.test.py b/fork-ci/actions/doc-check/doc_check.test.py index 72c34fe1e16d5..edeb3922bf1a0 100644 --- a/fork-ci/actions/doc-check/doc_check.test.py +++ b/fork-ci/actions/doc-check/doc_check.test.py @@ -1,5 +1,6 @@ """doc_check.py: budgets, history, links and dated reports, on real git repositories; config missing, empty, broken -or loosened by the change itself; and the fork's own general agent rules page (docs/fork/agent-rules.md) passes. +or loosened by the change itself; docs removed while still linked; symlinks, bytes that are not UTF-8 and CRLF; and +the fork's own general agent rules page (docs/fork/agent-rules.md) passes. Run: python3 fork-ci/actions/doc-check/doc_check.test.py """ import contextlib, importlib.util, io, json, os, re, subprocess, sys, tempfile, unittest @@ -241,14 +242,92 @@ def test_all_mode_reads_every_tracked_file_and_the_checkout_config(self): self.assertNotIn('vendor/x.md', out) self.assertIn('rules from .github/doc-check.json', out) - def test_not_utf8_warns_and_rerun_is_identical(self): + def test_link_in_inline_code_or_with_a_query_and_a_fence_in_a_list_item(self): + text = ('Write `[x](nowhere.md)` or ``[y](`gone`.md)``; see [b](b.md?plain=1#L3).\n\n' + '- a step:\n\n ```md\n [z](missing.md)\n ```\n\n[real](missing.md)\n') + base = self.branch({'docs/a.md': text, 'docs/b.md': 'b\n'}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('DOC docs/a.md:9: broken link missing.md', out) + self.assertIn('1 problem(s)', out) # not the inline code, the query or the fenced one + + +class Removed(Repo): + """#908: a change that deletes or renames a doc another file links to fails, though it did not touch that file.""" + + def test_renamed_or_deleted_doc_still_linked_from_an_untouched_file(self): + self.commit({'docs/a.md': 'See [b](b.md) and [guide](guide/).\n', 'docs/b.md': 'b\n', + 'docs/guide/one.md': '1\n', 'docs/c.md': '[ok](a.md)\n'}) + self.git('checkout', '-q', '-b', 'change') + self.git('mv', 'docs/b.md', 'docs/b2.md') + self.git('rm', '-q', 'docs/guide/one.md') + self.git('commit', '-q', '-m', 'rename and delete') + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 1, out) + self.assertIn('DOC docs/a.md:1: broken link b.md: this change removed docs/b.md', out) + self.assertIn('DOC docs/a.md:1: broken link guide/: this change removed docs/guide', out) + self.assertIn('2 problem(s)', out) + + def test_an_old_broken_link_in_an_untouched_file_is_not_this_change(self): + self.commit({'docs/old.md': '[gone](never.md)\n', 'docs/b.md': 'b\n'}) + base = self.branch({'docs/b.md': None}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 0, out) + + +class FailClosed(Repo): + """#908: what used to pass unchecked now fails: a symlink to a large file, a byte that is not UTF-8, CRLF size.""" + + def test_agents_md_turned_into_a_symlink_to_a_large_file_is_checked_as_that_file(self): + self.commit({'AGENTS.md': 'short\n', 'docs/big.md': lines(200)}) + self.git('checkout', '-q', '-b', 'change') + os.remove('AGENTS.md') + os.symlink('docs/big.md', 'AGENTS.md') + self.commit({}) + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 1, out) + self.assertIn('DOC AGENTS.md: 200 lines / 2200 B, budget 150 lines', out) + + def test_a_symlink_out_of_the_repository_or_to_no_file_fails(self): + with open(os.path.join(self.tmp.name, 'outside.md'), 'w') as f: + f.write('x\n') + self.git('checkout', '-q', '-b', 'change') + os.symlink('../outside.md', 'AGENTS.md') + os.symlink('missing.md', 'CLAUDE.md') + self.commit({}) + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 1, out) + self.assertIn('DOC AGENTS.md: a symlink that points outside the repository', out) + self.assertIn('DOC CLAUDE.md: a symlink that points to no file', out) + + def test_a_byte_that_is_not_utf8_fails_and_the_size_is_still_checked(self): base = self.branch({'a.md': 'ok\n'}) - with open(os.path.join(self.root, 'a.md'), 'wb') as f: - f.write(b'\xff\xfe bad\n') + with open('AGENTS.md', 'wb') as f: + f.write(b'\xff\n' + lines(200).encode()) + with open('a.md', 'wb') as f: + f.write(b'\xfe bad\n') + self.commit({}) first = self.run_check('--base', base) - self.assertEqual(first[0], 0, first[1]) - self.assertIn('WARN a.md: cannot read it', first[1]) - self.assertEqual(first, self.run_check('--base', base)) + self.assertEqual(first[0], 1, first[1]) + self.assertIn('DOC AGENTS.md: not UTF-8 text (byte 0)', first[1]) + self.assertIn('DOC AGENTS.md: 201 lines / 2202 B', first[1]) + self.assertIn('DOC a.md: not UTF-8 text', first[1]) + self.assertEqual(first, self.run_check('--base', base)) # a re-run gives the same output + + def test_crlf_is_measured_as_its_bytes_on_disk(self): + base = self.branch({}) + with open('AGENTS.md', 'wb') as f: + f.write(b''.join(b'x' * 118 + b'\r\n' for _ in range(100))) # 12000 B on disk; 11900 read as LF + self.commit({}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 0, out) + self.assertIn('WARN AGENTS.md: 100 lines / 12000 B = 100%', out) + with open('AGENTS.md', 'ab') as f: + f.write(b'x\r\n') + self.commit({}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('DOC AGENTS.md: 101 lines / 12003 B, budget 150 lines / 12000 B', out) class AgentRulesPage(unittest.TestCase): From b02479e77316bd16d21351854d7dacf1efbd2f98 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 11:08:42 +0000 Subject: [PATCH 2/2] doc-check: untouched symlinks, CommonMark fences, .git targets; lint fix - A change that deletes, renames or moves away the file an untouched symlink points to fails in --base mode ("this change removed "). - A fence opens only with 0-3 spaces of indent, counted from the content of the list item it is in; 4+ spaces or a tab is no fence, so later links are still checked. A fence in a list item ends with the item. - A symlink's warning says when the change moved it past warn_at (the base is read through the symlink); a symlink whose target is checked in the same run reports what the target already reports once. - A symlink into .git fails; a link that is no path (%00) is a broken link, not a traceback. - action.yml lists the UTF-8 and symlink rules. - Drop the issue number from two test comments (no-low-value-comments). Co-Authored-By: Claude Opus 5.5 --- .github/scripts/fork-ci-tests.test.cjs | 4 +- fork-ci/actions/doc-check/README.md | 9 +- fork-ci/actions/doc-check/action.yml | 3 +- fork-ci/actions/doc-check/doc_check.py | 130 +++++++++++++++----- fork-ci/actions/doc-check/doc_check.test.py | 104 ++++++++++++++++ 5 files changed, 215 insertions(+), 35 deletions(-) diff --git a/.github/scripts/fork-ci-tests.test.cjs b/.github/scripts/fork-ci-tests.test.cjs index 740d82f0daec0..04ef82939e7b3 100644 --- a/.github/scripts/fork-ci-tests.test.cjs +++ b/.github/scripts/fork-ci-tests.test.cjs @@ -273,7 +273,7 @@ test("the list ignores comments and blank lines and reads `run by` and weights", () => readList("a.test.py unittest ~12s\n"), /"; a Python test's line then ends in its format: "unittest" or "ok lines"\)$/, ); - // One line per test: a second line for a file is refused, whatever it says (#789). + // One line per test: a second line for a file is refused, whatever it says. for (const twice of [ "a.test.sh\nb.test.sh\na.test.sh\n", "a.test.py unittest\na.test.py ok lines\n", @@ -287,7 +287,7 @@ test("the list ignores comments and blank lines and reads `run by` and weights", }); // A Python test the runner never runs (upstream's, which a plain step runs) leaves no record, so the runner never reads -// its format word: its word is checked here against its source instead (#789). +// its format word: its word is checked here against its source instead. test("a listed Python test the runner does not judge says the format its source has", () => { const root = path.resolve(__dirname, "../.."); const read = (file) => fs.readFileSync(path.join(root, file), "utf8"); diff --git a/fork-ci/actions/doc-check/README.md b/fork-ci/actions/doc-check/README.md index 87dacf480fbfd..a0ddb9fd5dd6e 100644 --- a/fork-ci/actions/doc-check/README.md +++ b/fork-ci/actions/doc-check/README.md @@ -7,11 +7,12 @@ action fails a pull request that: - puts an instruction file over its **size budget** (lines or bytes; above `warn_at` of a budget it only warns, and says when this change moved the file past it); - writes **history** into an instruction file (a changelog block, an "is live on" claim, a dated "Updated" banner); -- has a **broken relative link** in a Markdown file it adds or changes (code fences and inline code skipped; `/x` is - from the repository root, as GitHub reads it; a link that leaves the repository is broken), or deletes or renames a +- has a **broken relative link** in a Markdown file it adds or changes (code fences, opened as CommonMark does, and inline code + skipped; `/x` is from the repository root, as GitHub reads it; a link that leaves the repository is broken), or deletes or renames a file that another Markdown file still links to; -- has a checked file that is **not UTF-8** or cannot be read, or is a **symlink** out of the repository or to no - file (a symlink is checked as the file it points to; sizes are the bytes on disk, CRLF included); +- has a checked file that is **not UTF-8** or cannot be read, or is a **symlink** out of the repository, into + `.git` or to no file (a symlink is checked as the file it points to and reported once when its target is checked + too; sizes are the bytes on disk, CRLF included), or deletes, renames or moves away the file a symlink points to; - **adds** a file whose name looks like a dated report, handoff or review (those go in the pull request or an issue). The general rules this enforces, and the rest of the agent rules, are in diff --git a/fork-ci/actions/doc-check/action.yml b/fork-ci/actions/doc-check/action.yml index aeb08fa74a42f..bd773c4ddea4f 100644 --- a/fork-ci/actions/doc-check/action.yml +++ b/fork-ci/actions/doc-check/action.yml @@ -1,7 +1,8 @@ name: doc-check description: >- Doc rules for the Markdown files agents read: size budgets for instruction files, no history in them, every - relative link resolves, no dated reports added to the repository. Rules from the project's optional config, read at + relative link resolves, no dated reports added to the repository; a checked file is UTF-8, and a symlink is + checked as its target, which must be a file in the repository (not in .git). Rules from the project's optional config, read at the base commit. Fails on a broken rule; warns near a budget. Usage: README.md next to this file. inputs: config: diff --git a/fork-ci/actions/doc-check/doc_check.py b/fork-ci/actions/doc-check/doc_check.py index 27ec218013e66..9e8273d2f42f8 100644 --- a/fork-ci/actions/doc-check/doc_check.py +++ b/fork-ci/actions/doc-check/doc_check.py @@ -4,13 +4,14 @@ * size budgets (lines and bytes) for instruction files, matched by glob, first match wins; above `warn_at` of a budget a WARN line that never fails; * no history in instruction files (changelog blocks, "is live on" claims, dated "Updated" banners); - * every relative link resolves to a file or folder in the repository (code fences and inline code are skipped; `/x` - is from the repository root, as GitHub reads it; a link that leaves the repository is broken); with --base, a + * every relative link resolves to a file or folder in the repository (code fences, opened as CommonMark does, and + inline code are skipped; `/x` is from the repository root, as GitHub reads it; a link that leaves the repository is broken); with --base, a file the change deletes or renames away must have no link left to it in any file the config selects; * a newly added file whose name looks like a dated report, handoff or review belongs in the pull request or an issue, not in the repository; * a checked file is UTF-8 text that can be read (anything else fails, and its size is still checked); a symlink is - checked as the file it points to, which must be in the repository. Sizes are the bytes on disk (CRLF included). + checked as the file it points to, which must be in the repository and not in .git (with --base, a change that + removes the file an untouched symlink points to fails). Sizes are the bytes on disk (CRLF included). The rules come from the project's JSON config (README "Config"); every key is optional and a missing, empty or `{}` config means the defaults. With --base the config is read at the base commit, never from the checkout, so a change @@ -52,8 +53,9 @@ } FLAGS = {'i': re.I, 'm': re.M, 's': re.S} LINK = re.compile(r'\]\(\s*(?:<([^<>\n]+)>|([^()\s<>]+))(?:\s+(?:"[^"\n]*"|\'[^\'\n]*\'))?\s*\)') -# Any indent: a fence inside a list item is indented more than three spaces. -FENCE = re.compile(r'^[ \t]*(`{3,}|~{3,})') +# CommonMark: a fence opens or closes with 0-3 spaces of indent, counted from the content of the list item it is in. +FENCE = re.compile(r'(`{3,}|~{3,})') +LIST_ITEM = re.compile(r'([-*+]|\d{1,9}[.)])(?=[ \t]|$)') INLINE_CODE = re.compile(r'(`+)(?!`).*?(?= len(fence) and not line.strip()[len(mark):].strip(): + wide = line.expandtabs(4) + body = wide.lstrip(' ') + indent = len(wide) - len(body) + if body and fence is not None and indent < fence_col: + fence = None # the list item the fence was in has ended + if body: + while items and indent < items[-1]: + items.pop() + col = fence_col if fence is not None else (items[-1] if items else 0) + m = FENCE.match(body) if body and indent - col <= 3 else None + if fence is not None: + if m and m.group(1)[0] == fence[0] and len(m.group(1)) >= len(fence) and not body[len(m.group(1)):].strip(): fence = None continue + if m and not (m.group(1)[0] == '`' and '`' in body[len(m.group(1)):]): + fence, fence_col = m.group(1), col + continue + item = LIST_ITEM.match(body) if body and indent - col <= 3 else None + if item: + rest = body[item.end():] + gap = len(rest) - len(rest.lstrip(' ')) + items.append(indent + item.end() + (gap if rest.strip() and 1 <= gap <= 4 else 1)) if fence is None: for lm in LINK.finditer(INLINE_CODE.sub('', line)): target = re.split(r'[#?]', lm.group(1) or lm.group(2), maxsplit=1)[0] @@ -222,7 +240,11 @@ def broken_link(path, target, root): if full is None: return None real_root = os.path.realpath(root) - if os.path.commonpath([real_root, os.path.realpath(full)]) != real_root: + try: + real = os.path.realpath(full) + except (ValueError, OSError) as e: # a NUL byte (%00), for example + return f'not a path ({e.__class__.__name__})' + if os.path.commonpath([real_root, real]) != real_root: return 'points outside the repository' return None if os.path.exists(full) else 'no such file' @@ -287,6 +309,8 @@ def read_doc(path, root='.'): real, real_root = os.path.realpath(path), os.path.realpath(root) if os.path.commonpath([real_root, real]) != real_root: return None, None, 'a symlink that points outside the repository: make it a file' + if '.git' in os.path.relpath(real, real_root).split(os.sep): + return None, None, 'a symlink that points into .git: make it a file' if not os.path.isfile(real): return None, None, 'a symlink that points to no file: make it a file' links_from = os.path.relpath(real, real_root) @@ -301,21 +325,64 @@ def read_doc(path, root='.'): return raw.decode('utf-8', 'surrogateescape'), links_from, f'not UTF-8 text (byte {e.start}): save it as UTF-8' +def base_doc(mb, path): + """The text a path read at the merge base, through symlinks in the repository: '' when it was no file there (or + pointed to none), None when git cannot tell.""" + for _ in range(40): + out = git('ls-tree', '-z', mb, '--', path) + if out is None: + return None + if not out: + return '' + mode, kind, rest = out.split(' ', 2) + if kind != 'blob': + return '' + blob = git('cat-file', 'blob', rest.split('\t', 1)[0]) + if blob is None or mode != '120000': + return blob + path = os.path.normpath(os.path.join(os.path.dirname(path), blob)) + if os.path.isabs(path) or path.split(os.sep)[0] == '..': + return '' + return None + + +def removed_target(path, gone, root='.'): + """The path a symlink names (hop by hop, inside the repository) that the change removed, or None.""" + for _ in range(40): + target = os.path.normpath(os.path.join(os.path.dirname(path), os.readlink(path))) + rel = os.path.relpath(os.path.join(root, target), root) + if rel in gone or any(g.startswith(rel + os.sep) for g in gone): + return rel + if rel.split(os.sep)[0] == '..' or not os.path.islink(os.path.join(root, rel)): + return None + path = rel + return None + + def links_to_removed(rules, removed, checked, root='.'): - """Problems for links, in selected tracked files this run did not check, to a file the change removed (or into a - folder it emptied) that no longer resolves.""" + """Problems, in selected tracked files this run did not check, for a symlink to a file the change removed, and + (links on) for links to a file the change removed (or into a folder it emptied) that no longer resolve.""" gone = {os.path.normpath(p) for p in removed} - if not gone or not rules['links']: + if not gone: return [] out = git('ls-files', '-z') if out is None: raise ConfigError('git ls-files failed (run from the repository root)') probs = [] for path in out.split('\0'): - if not path or path in checked or not selected(rules, path) or not os.path.isfile(path): + if not path or path in checked or not selected(rules, path): + continue + if not (os.path.isfile(path) or os.path.islink(path)): + continue + text, links_from, problem = read_doc(path, root) + if text is None: + hit = os.path.islink(path) and removed_target(path, gone, root) + if hit: + probs.append((path, None, f'{problem}: this change removed {hit}')) continue - text, links_from, _ = read_doc(path, root) - for no, target in link_lines(lf(text or '')): + if not rules['links']: + continue + for no, target in link_lines(lf(text)): full = link_path(links_from or path, target, root) if full is None or broken_link(links_from or path, target, root) is None: continue @@ -360,7 +427,7 @@ def main(argv=None): annotate('error', a.config, None, f'doc-check: {e}') return 2 print(f'doc_check: {shown(note)}') - probs, warns, count, checked = [], [], 0, set() + probs, warns, count, checked, found = [], [], 0, set(), {} for path, added in files: # A symlink to no file is checked (and fails); another path that is not a file is skipped. if not selected(rules, path) or not (os.path.isfile(path) or os.path.islink(path)): @@ -368,15 +435,22 @@ def main(argv=None): count += 1 checked.add(path) text, links_from, problem = read_doc(path) - if problem: - probs.append((path, None, problem)) - if text is None: - continue + first = [(path, None, problem)] if problem else [] + if text is None: + probs += first + continue base_text = None - if mb is not None and budget(rules, path) is not None and links_from is None: - old = git('show', f'{mb}:{path}') - base_text = old if old is not None else '' + if mb is not None and budget(rules, path) is not None: + base_text = base_doc(mb, path) p, w = check(rules, path, text, added, '.', base_text, links_from) + found[path] = (links_from, first + p, w) + for path, (links_from, p, w) in found.items(): + # A symlink whose target this run also checked: what the target already reports (same budget, history, + # links) is said once, at the target. + if links_from is not None and links_from in found and links_from != path: + said = {(no, msg) for _, no, msg in found[links_from][1] + found[links_from][2]} + p = [x for x in p if x[1:] not in said] + w = [x for x in w if x[1:] not in said] probs += p warns += w try: diff --git a/fork-ci/actions/doc-check/doc_check.test.py b/fork-ci/actions/doc-check/doc_check.test.py index edeb3922bf1a0..aebf222c275aa 100644 --- a/fork-ci/actions/doc-check/doc_check.test.py +++ b/fork-ci/actions/doc-check/doc_check.test.py @@ -251,6 +251,31 @@ def test_link_in_inline_code_or_with_a_query_and_a_fence_in_a_list_item(self): self.assertIn('DOC docs/a.md:9: broken link missing.md', out) self.assertIn('1 problem(s)', out) # not the inline code, the query or the fenced one + def test_a_fence_opens_only_with_0_to_3_spaces_of_indent(self): + # CommonMark: indented 4 or more (a tab is 4), or with a backtick after a backtick fence, it is no fence, so + # the links after it are still checked; inside a list item the indent counts from the item's content. + for text in ['Shown:\n\n ```\n\n[gone](nope.md)\n', '\t~~~\n[gone](nope.md)\n', + '- item\n\n ```\n[gone](nope.md)\n', '```x```\n[gone](nope.md)\n']: + with self.subTest(text=text): + self.write({'docs/a.md': text}) + code, out = self.run_check('--files', 'docs/a.md') + self.assertEqual(code, 1, out) + self.assertIn('broken link nope.md: no such file', out) + text = '1. step\n\n ```\n [in](nope.md)\n ```\n2. next\n\n ~~~\n [in](nope.md)\n[after](nope.md)\n' + self.write({'docs/a.md': text}) # a fence in a list item ends with the item + code, out = self.run_check('--files', 'docs/a.md') + self.assertIn('DOC docs/a.md:10: broken link nope.md', out) + self.assertIn('1 problem(s)', out) + + def test_a_link_that_is_no_path_is_a_broken_link_not_a_traceback(self): + self.commit({'docs/a.md': '[nul](x%00.md)\n', 'docs/b.md': 'b\n'}) + base = self.branch({'docs/b.md': None}) # the removed-link scan reads the untouched a.md + code, out = self.run_check('--base', base) + self.assertEqual(code, 0, out) # an old broken link is not this change + code, out = self.run_check('--files', 'docs/a.md') + self.assertEqual(code, 1, out) + self.assertIn('DOC docs/a.md:1: broken link x%00.md: not a path (ValueError)', out) + class Removed(Repo): """#908: a change that deletes or renames a doc another file links to fails, though it did not touch that file.""" @@ -274,6 +299,40 @@ def test_an_old_broken_link_in_an_untouched_file_is_not_this_change(self): code, out = self.run_check('--base', base) self.assertEqual(code, 0, out) + def untouched_symlink_loses_its_target(self, how): + """Base: docs/AGENTS.md and CLAUDE.md -> docs/AGENTS.md; the change touches only the target.""" + self.commit({'docs/AGENTS.md': 'rules\n'}) + os.symlink('docs/AGENTS.md', 'CLAUDE.md') + self.commit({}) + self.git('checkout', '-q', '-b', 'change') + how() + self.git('add', '-A') + self.git('commit', '-q', '-m', 'change') + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 1, out) + self.assertRegex(out, r'DOC CLAUDE.md: a symlink that points [a-z ]+: make it a file: ' + r'this change removed docs/AGENTS.md') + + def test_the_target_of_an_untouched_symlink_deleted(self): + self.untouched_symlink_loses_its_target(lambda: os.remove('docs/AGENTS.md')) + + def test_the_target_of_an_untouched_symlink_renamed(self): + self.untouched_symlink_loses_its_target(lambda: os.rename('docs/AGENTS.md', 'docs/RULES.md')) + + def test_the_folder_of_an_untouched_symlinks_target_turned_into_a_symlink_out(self): + away = os.path.join(self.tmp.name, 'away') + def how(): + os.rename('docs', away) + os.symlink(away, 'docs') + self.untouched_symlink_loses_its_target(how) + + def test_a_symlink_already_dangling_on_the_base_is_not_this_change(self): + os.symlink('missing.md', 'CLAUDE.md') + self.commit({'docs/b.md': 'b\n'}) + base = self.branch({'docs/b.md': None}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 0, out) + class FailClosed(Repo): """#908: what used to pass unchecked now fails: a symlink to a large file, a byte that is not UTF-8, CRLF size.""" @@ -300,6 +359,51 @@ def test_a_symlink_out_of_the_repository_or_to_no_file_fails(self): self.assertIn('DOC AGENTS.md: a symlink that points outside the repository', out) self.assertIn('DOC CLAUDE.md: a symlink that points to no file', out) + def test_a_symlink_into_git_fails(self): + self.git('checkout', '-q', '-b', 'change') + os.symlink('.git/config', 'AGENTS.md') + self.commit({}) + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 1, out) + self.assertIn('DOC AGENTS.md: a symlink that points into .git', out) + self.assertNotIn('core', out) + + def test_a_symlink_warning_says_when_this_change_moved_it_past(self): + self.commit({'docs/a.md': lines(30), 'docs/b.md': lines(38), 'CLAUDE.md': 'x\n'}) + self.git('checkout', '-q', '-b', 'change') + os.remove('CLAUDE.md') + os.symlink('docs/b.md', 'CLAUDE.md') + self.commit({}) + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 0, out) + self.assertIn('WARN CLAUDE.md: 38 lines', out) + self.assertIn('this change moved it past 90%', out) + self.git('checkout', '-q', 'main') + self.git('merge', '-q', '--ff-only', 'change') + self.git('checkout', '-q', '-b', 'change2') + os.remove('CLAUDE.md') + os.symlink('docs/a.md', 'CLAUDE.md') + self.commit({'docs/a.md': lines(38)}) # already past 90% on the base (through its old target) + code, out = self.run_check('--base', 'main') + self.assertEqual(code, 0, out) + self.assertIn('WARN CLAUDE.md: 38 lines', out) + self.assertNotIn('moved it past', out) + + def test_all_reports_a_symlink_to_an_over_budget_file_once(self): + target = lines(300) + 'Updated: 2026-01-01\n[gone](nope.md)\n' + self.commit({'skills/one/SKILL.md': target, 'AGENTS.md': lines(60)}) + os.makedirs('vendor/one') + os.symlink('../../skills/one/SKILL.md', 'vendor/one/SKILL.md') + os.symlink('AGENTS.md', 'CLAUDE.md') + self.commit({}) + code, out = self.run_check('--all') + self.assertEqual(code, 1, out) + self.assertEqual(out.count('302 lines'), 1, out) + self.assertEqual(out.count('dated "Updated" banner'), 1, out) + self.assertEqual(out.count('broken link nope.md'), 1, out) + self.assertNotIn('vendor/one', out) + self.assertIn('DOC CLAUDE.md: 60 lines / 660 B, budget 40 lines', out) # its own, smaller budget + def test_a_byte_that_is_not_utf8_fails_and_the_size_is_still_checked(self): base = self.branch({'a.md': 'ok\n'}) with open('AGENTS.md', 'wb') as f: