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..04ef82939e7b3 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. + 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. +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..a0ddb9fd5dd6e 100644 --- a/fork-ci/actions/doc-check/README.md +++ b/fork-ci/actions/doc-check/README.md @@ -7,8 +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 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, 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, 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 @@ -76,11 +80,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/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 d3ba2ddf387de..9e8273d2f42f8 100644 --- a/fork-ci/actions/doc-check/doc_check.py +++ b/fork-ci/actions/doc-check/doc_check.py @@ -4,15 +4,20 @@ * 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, 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. + 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 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 -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 +53,10 @@ } 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,})') +# 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(line): - target = (lm.group(1) or lm.group(2)).split('#', 1)[0] + for lm in LINK.finditer(INLINE_CODE.sub('', line)): + target = re.split(r'[#?]', lm.group(1) or lm.group(2), maxsplit=1)[0] if target: yield no, target -def broken_link(path, target, root): - """Why a relative link target is broken, or None when it resolves (or is no file link).""" +def link_path(path, target, root): + """The path a relative link target names (under root), or None when it is no file link.""" if SCHEME.match(target) or target.startswith('//'): return None target = unquote(target) - full = os.path.normpath(os.path.join(root, target.lstrip('/')) if target.startswith('/') + return os.path.normpath(os.path.join(root, target.lstrip('/')) if target.startswith('/') else os.path.join(root, os.path.dirname(path), target)) + + +def broken_link(path, target, root): + """Why a relative link target is broken, or None when it resolves (or is no file link).""" + full = link_path(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' -def check(rules, path, text, added, root='.', base_text=None): - """(problems, warnings) for one file's text. base_text: the file at the merge base ('' new, None unknown).""" +def check(rules, path, text, added, root='.', base_text=None, links_from=None): + """(problems, warnings) for one file's exact text. base_text: the file at the merge base ('' new, None unknown). + links_from: the path its links are relative to (a symlink's target), else the path.""" probs, warns = [], [] b = budget(rules, path) + exact, text = text, lf(text) if b is not None: - n, size, share = usage(b, text) + n, size, share = usage(b, exact) if share > 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 +274,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 +285,111 @@ 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 '.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) + 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 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, 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: + 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): + 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 + 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 + 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 +411,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 +427,37 @@ 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, found = [], [], 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')) + checked.add(path) + text, links_from, problem = read_doc(path) + 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: - old = git('show', f'{mb}:{path}') - base_text = old if old is not None else '' - p, w = check(rules, path, text, added, '.', base_text) + 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: + 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..aebf222c275aa 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,196 @@ 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 + + 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.""" + + 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) + + 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.""" + + 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_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(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):