jinghui/hermes-webui
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ci: docs-only fast-path + minimal docs CI (#6279)

Browse Source 
* ci: docs-only fast path + minimal docs CI

Skip the full pytest matrix + browser smoke on docs/CHANGELOG/README-only PRs
(required checks still report green fast via a fail-safe 'changes' gate job), and
add a lightweight Docs CI: critical_markdown_check.py (rendering-breaks only, not
style) + lychee broken-link check. Detection fails safe (any uncertainty or any
non-doc path -> full suite runs).

* ci: tighten docs-only detection — extension/type wins over name

A code file whose NAME contains README/CHANGELOG (scripts/CHANGELOG_stamp.py,
static/README_renderer.js) was wrongly classified docs-only, which would SKIP the
test suite on a real code change. Now a path is docs only by doc extension, exact
doc basename, or non-code file under docs/. Verified against 16 cases incl. every
code-with-docs-name trap.

* ci: fix all Fable+Codex gate findings on docs-only fast path

- BLOCKER: drop *.txt from is_docs (requirements.txt is a dep manifest — a bump
  would have skipped the whole test matrix). docs = *.md/.markdown/.rst + bare
  doc basenames only; strict allowlist, no docs/** denylist.
- Rename hole: use 'git diff --name-only --no-renames' so a rename src/app.py ->
  docs.md reveals the code-side deletion instead of collapsing to the doc dest.
- SECURITY: docs-ci.yml no longer interpolates untrusted fork-PR filenames into
  run: via ${{ }} (which executes $() in a crafted name). File list flows through
  a file + mapfile-as-args; lychee gets a fixed glob, not the attacker list.
  Added permissions: contents: read.
- Wedge belt-and-suspenders: 'if: ${{ always() }}' on the required test +
  browser-smoke jobs so a failed 'changes' job can't skip them; step guards treat
  missing/empty docs_only as run-full.
- critical_markdown_check.py: corrected the core rule — a newline in the whitespace
  AROUND a link destination is valid CommonMark (was a false positive); only a
  newline INSIDE the destination token, or an unclosed inline link, breaks
  rendering. Verified full agreement with the markdown-it-py reference parser +
  0 false positives on all 43 repo docs. Also blank 4-space indented code + multi
  backtick spans. Reworded 'block the merge' -> 'break rendering' (non-required).

* ci: address Codex re-gate — lint always() + markdown title/unclosed cases

- Add if: always() to the lint job too (not currently required, but future-proof
  against the wedge class if it's ever promoted).
- critical_markdown_check.py: handle two more CommonMark cases Codex found —
  a newline inside a "title" string is legal (skip), and a newline-terminated
  unclosed dest ([x](url\n at EOF/EOL with no close) is broken (flag). After the
  destination token ends, valid continuations are ')' or a title opener (" ' ();
  bare text after the newline is the real break. Verified full agreement with
  markdown-it-py across 13 cases + 0 FP on all 43 repo docs.

* ci: model the CommonMark inline-dest grammar (root-cause fix for markdown checker)

Round-3 gate found the title heuristic caused sibling regressions: a parenthesized
multi-line title (url (a\nb)) was falsely flagged, and a quote glued into the URL
(exa"part) was wrongly treated as a title-start and skipped. Rather than patch more
heuristics, replace the ad-hoc newline logic with _scan_inline_dest(), which walks
the actual grammar: skip leading ws -> bare dest (balanced parens, ends at ws or the
depth-0 ')') or <angle> dest -> after ws the next char must be ')' or a real title
opener (" ' () -> else the destination is split across the line (broken). Verified
FULL agreement with markdown-it-py across 20 adversarial cases (incl. both round-3
regressions, balanced parens, angle dests, multiline titles) + 0 FP on all 43 docs.

* test: pytest suite for critical_markdown_check (42 cases)

Durable, repeatable verification for the docs-CI markdown checker: 19 verdict cases
+ 19 cross-checked against the markdown-it-py CommonMark reference (skips cleanly if
the lib is absent) + 3 code-span-safety cases + empty/no-link inputs. Covers both
round-3 regressions (parenthesized multi-line title valid; quote-glued-in-URL broken),
balanced parens, angle destinations, and multiline titles. 42 passed.

* ci: fix 2 grammar edges from Codex round-4 (escaped-> in angle dest, unbalanced bare-dest parens)

- Angle dest <...> now honors backslash escapes: [x](<foo\>bar>) renders (the \> is
  escaped), was a false positive.
- Bare dest must have BALANCED parens: [x](foo(\n)) does not render (a '(' stays open
  when whitespace ends the token) — now returns split, was a false negative.
Both verified against markdown-it-py + added as pytest cases. 46 passed, 0 FP on 43 docs.

* ci: escaped-newline in angle dest is still a raw newline (Codex round-5)

<...> escape handling skipped the char after backslash including a newline, so
[x](<foo\<nl>>) returned ok but doesn't render (blockquote on line 2). An escaped
newline inside an angle destination is still a raw newline -> split. Preserves
[x](<foo\>bar>). Added regression case. 48 pytest cases pass, 0 FP on 43 docs.

* ci: mirror escaped-newline guard to bare dest (Codex round-6, GFM-correct)

The angle branch already treated backslash-newline as split; the bare branch skipped
it, so [x](foo\<nl>bar) returned ok. GFM/CommonMark forbid line endings in bare
destinations (GitHub's cmark-gfm won't render it), though markdown-it-py permissively
does. Since these docs are GitHub-rendered we follow GFM: flag it. Added as a
SPEC_DIVERGENT test case (verdict-asserted, excluded from the permissive parser
cross-check). 49 pytest pass, escaped paren/space still valid, 0 FP on 43 docs.

* ci: delimiter-aware title scan (Codex round-7 unclosed-link false negatives)

Naive text.find(')') matched the TITLE's own ')' not the link's outer ')', so
[x](foo (title), [x](<foo> (title), [x](foo "title" all returned ok despite being
unclosed links. Now parse the title to its actual closing delimiter ("..", '..',
or a (..) that forbids nested unescaped '(' per CommonMark), then require the link's
own ')' after optional whitespace. Also catches the nested-paren-title break
[x](foo (a (b) c)). Verified vs markdown-it-py; escaped parens + single-quoted
titles containing parens still valid. 61 pytest pass, 0 FP on 43 docs.

* ci: remove unused variable (ruff F841 in critical_markdown_check)

The CI lint gate (ruff forward E9+F+B on new lines) caught a dead 'stripped =
line.lstrip()' leftover from an earlier refactor in _blank_code — the fence
detection matches on the raw line. Removed. No behavior change (61 pytest pass).

---------

Co-authored-by: nesquena-hermes <nesquena-hermes@users.noreply.github.com>
This commit is contained in:
nesquena-hermesandnesquena-hermes authored and GitHub committed 2026-07-18 23:24:23 +00:00
1 parent 94514458d9
commit 2ea0cc6ed2
5 files changed
+677 -6
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

scripts/critical_markdown_check.py
+224
View File
@@ -0,0 +1,224 @@
#!/usr/bin/env python3
"""critical_markdown_check.py — catch ONLY catastrophic Markdown rendering breaks.
Deliberately minimal (Nathan, 2026-07-18): "only pretty critical, borderline
catastrophic Markdown issues, like there is a new line in a link that would prevent
the link from rendering." This is NOT a style linter and NOT a prose scanner. It
flags ONLY two constructs that genuinely break how the document renders, verified
against the CommonMark reference parser (markdown-it-py), and which do not occur in
normal prose:
1. A newline INSIDE an inline-link destination TOKEN — `[label](https://exa\\nmple.com)`.
The destination is a single token; a newline splitting it (non-space, newline,
non-space, before any closing `)`) makes CommonMark NOT render the link.
IMPORTANT: a newline in the *whitespace* around the destination —
`[label](\\nhttps://x)`, `[label](https://x\\n)`, or inside a `"title"` — is
LEGAL CommonMark and renders fine, so those are NOT flagged (verified).
2. A single-line inline link/image whose destination is never closed —
`[label](https://x` with no `)` before end of line. Renders broken.
Code spans (fenced ``` / ~~~ blocks, 4-space indented code, and inline `code`) are
blanked first so an example of "bad" Markdown shown inside code is never flagged.
Exit 1 only on one of the two defects above. Anything ambiguous is NOT flagged — a
false positive on a docs PR is worse than missing a cosmetic issue. Dead external
links are handled separately by the lychee step, not here.
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
def _blank_code(text: str) -> str:
"""Blank fenced blocks, 4-space indented code, and inline code — keep line count."""
out = []
in_fence = False
fence_marker = ""
for line in text.split("\n"):
# Fence open/close. A closing fence must be at least as long and same char.
m = re.match(r"^(\s*)(`{3,}|~{3,})", line)
if not in_fence and m:
in_fence = True
fence_marker = m.group(2)[0] * len(m.group(2))
out.append("")
continue
if in_fence:
cm = re.match(r"^\s*(`{3,}|~{3,})", line)
if cm and cm.group(1)[0] == fence_marker[0] and len(cm.group(1)) >= len(fence_marker):
in_fence = False
out.append("")
continue
# 4-space (or tab) indented code line → blank it.
if re.match(r"^(?: {4}|\t)", line):
out.append("")
continue
# inline `code` (including multi-backtick) → blank spans on this line.
out.append(re.sub(r"(`+)(?:.*?)\1", lambda mm: " " * len(mm.group(0)), line))
return "\n".join(out)
def _scan_inline_dest(text: str, i: int) -> str:
"""Given the index right after a link/image `[label](`, decide whether the inline
destination renders. Models the CommonMark inline-link grammar closely enough to
catch the two catastrophic shapes without false positives:
after '(': [ws] destination [ws title] [ws] ')'
where destination is either `<...>` (angle, no raw newline) or a bare run of
non-whitespace with BALANCED parens, and title is "...", '...', or (...) (may span
newlines). Returns 'ok', 'split' (a newline breaks the destination token), or
'unclosed' (no closing ')').
"""
n = len(text)
def skip_ws(j: int) -> int:
while j < n and text[j] in " \t\n":
j += 1
return j
j = skip_ws(i) # leading ws (incl newline) before dest is legal
if j >= n:
return "unclosed"
# Angle-bracket destination <...> — a raw newline inside it is invalid, but a
# backslash-escaped '>' does NOT terminate it. Scan honoring escapes.
if text[j] == "<":
k = j + 1
while k < n and text[k] not in ">\n":
if text[k] == "\\" and k + 1 < n:
# An escaped char doesn't terminate the angle dest — but an escaped
# NEWLINE is still a raw newline inside <...>, which is invalid.
if text[k + 1] == "\n":
return "split"
k += 2
else:
k += 1
if k >= n:
return "unclosed"
if text[k] == "\n":
return "split"
j = k + 1
else:
# Bare destination: run of non-whitespace with balanced parens. It ends at the
# first whitespace, or at the ')' that closes the link (depth 0).
depth = 0
while j < n:
c = text[j]
if c == "\\" and j + 1 < n:
# An escaped char doesn't end the destination — but an escaped NEWLINE
# is still a raw line ending, which GFM/CommonMark forbid in a bare
# destination (GitHub's cmark-gfm won't render it). Treat as split.
if text[j + 1] == "\n":
return "split"
j += 2
continue
if c in " \t\n":
break # whitespace terminates the destination token
if c == "(":
depth += 1
elif c == ")":
if depth == 0:
return "ok" # this ')' closes the link — complete
depth -= 1
j += 1
else:
return "unclosed" # ran off the end with no closing ')'
# Whitespace ended the bare destination. A bare dest must have BALANCED parens;
# if a '(' is still open, the destination is malformed and won't render.
if depth > 0:
return "split"
# Destination token ended at whitespace. Skip it (a single newline here is legal),
# then the next non-whitespace must be the close ')' or a title opener.
j = skip_ws(j)
if j >= n:
return "unclosed"
c = text[j]
if c == ")":
return "ok"
if c in "\"'(":
# A title is present. It ends at its matching delimiter — `"..."`, `'...'`, or
# a balanced `(...)`. Titles may span newlines. After the title, whitespace is
# allowed and then the link's OWN closing ')' MUST follow; otherwise the link
# is unclosed (e.g. `[x](foo (title)` — the sole ')' closes the title, not the
# link). Walk the title body honoring escapes.
openc = c
k = j + 1
if openc == "(":
# A parenthesized title must NOT contain an unescaped '(' — CommonMark
# forbids it, so `(a (b) c)` is not a valid title and the link won't render.
while k < n:
ch = text[k]
if ch == "\\" and k + 1 < n:
k += 2
continue
if ch == "(":
return "unclosed" # nested unescaped '(' → invalid title
if ch == ")":
break
k += 1
if k >= n:
return "unclosed" # parenthesized title never closed
else:
closec = openc # matching " or '
while k < n and text[k] != closec:
if text[k] == "\\" and k + 1 < n:
k += 2
else:
k += 1
if k >= n:
return "unclosed" # quoted title never closed
# k is at the title's closing delimiter. After it: optional ws then the link ')'.
k = skip_ws(k + 1)
if k < n and text[k] == ")":
return "ok"
return "unclosed"
# Anything else after the destination + whitespace is bare text → the inline link is
# malformed and renders as literal characters. This is the catastrophic split, e.g.
# `[x](https://exa\nmple.com)` or `[x](url\nmore)`.
return "split"
def check_file(path: Path) -> list[str]:
problems: list[str] = []
raw = path.read_text(encoding="utf-8", errors="replace")
text = _blank_code(raw)
# Locate each inline link/image opener `[label](` (label has no unescaped ] or newline).
for m in re.finditer(r"!?\[(?:[^\]\n\\]|\\.)*\]\(", text):
line_no = text.count("\n", 0, m.start()) + 1
verdict = _scan_inline_dest(text, m.end())
if verdict == "split":
problems.append(
f"{path}:{line_no}: newline inside a link destination — the link will not render")
elif verdict == "unclosed":
problems.append(
f"{path}:{line_no}: link/image destination never closed with ')' — renders broken")
return problems
def main(argv: list[str]) -> int:
files = [Path(a) for a in argv[1:] if a.strip()]
if not files:
print("critical_markdown_check: no files to check (ok)")
return 0
all_problems: list[str] = []
scanned = 0
for f in files:
if not f.is_file():
continue
scanned += 1
try:
all_problems.extend(check_file(f))
except Exception as e: # never crash the gate on an odd file
print(f"warning: could not scan {f}: {e!r}")
if all_problems:
print("Critical Markdown problems (fix these — they break rendering):")
for p in all_problems:
print(f" ✗ {p}")
return 1
print(f"critical_markdown_check: {scanned} file(s) OK — no catastrophic Markdown issues")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv))
scripts/test_critical_markdown_check.py
+135
View File
@@ -0,0 +1,135 @@
#!/usr/bin/env python3
"""Tests for scripts/critical_markdown_check.py — the docs-CI critical-markdown gate.
The checker must flag ONLY catastrophic rendering breaks (a newline that splits an
inline-link destination, or an unclosed inline link) and nothing that renders fine.
Each case is asserted against the intended CommonMark behavior. Where markdown-it-py
is installed the test additionally cross-checks the checker's verdict against the
reference parser; when it isn't, the hand-labeled expectations still run.
Run: pytest scripts/test_critical_markdown_check.py -v
"""
import importlib.util
import tempfile
from pathlib import Path
import pytest
_spec = importlib.util.spec_from_file_location(
"critical_markdown_check",
str(Path(__file__).with_name("critical_markdown_check.py")),
)
cmc = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(cmc)
try:
from markdown_it import MarkdownIt
_MD = MarkdownIt("commonmark")
except Exception: # optional; hand labels still assert
_MD = None
def _flags(src: str) -> bool:
with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False) as tf:
tf.write(src)
p = Path(tf.name)
try:
return len(cmc.check_file(p)) > 0
finally:
p.unlink()
def _renders(src: str) -> bool:
html = _MD.render(src)
return "<a href" in html or "<img" in html
# (name, source, should_flag). should_flag=True means the checker MUST report it broken.
CASES = [
# legal constructs — must NOT flag (render fine)
("newline-before-dest", "[l](\nhttps://x.com)", False),
("newline-after-dest", "[l](https://x.com\n)", False),
("newline-in-dq-title", '[l](https://x.com "a\nb")', False),
("title-separator-nl", '[x](https://a\n"t")', False),
("single-quote-title-ml", "[x](url\n'a\nb')", False),
("paren-title-multiline", "[x](url (multi\nline))", False),
("balanced-parens-dest", "[x](https://x.com/foo(bar)baz)", False),
("angle-dest", "[x](<https://x.com>)", False),
("angle-escaped-gt", "[x](<foo\\>bar>)", False),
("dq-title-inline", '[x](url "title")', False),
("paren-title-closed", "[x](foo (title))", False),
("dq-title-then-close", '[x](foo "title")', False),
("empty-dest", "[x]()", False),
("plain-good", "[l](https://x.com)", False),
("two-links-line", "[a](x) and [b](y)\n", False),
# catastrophic breaks — MUST flag (do not render as links)
("newline-inside-dest", "[l](https://ex\nam.com)", True),
("img-newline-inside", "![a](img\nf.png)", True),
("bare-text-after-nl", "[x](url\nmore)", True),
("quote-glued-in-url", '[x](exa"part\nmple.com)', True),
("bare-unbalanced-paren", "[x](foo(\n))", True),
("unclosed-at-eof", "[x](https://a", True),
("unclosed-newline-term", "[x](https://a\n", True),
("angle-dest-split", "[x](<https://x\n.com>)", True),
("angle-escaped-newline", "[x](<foo\\\n>)", True),
("paren-title-unclosed", "[x](foo (title)", True),
("angle-title-unclosed", "[x](<foo> (title)", True),
("dq-title-unclosed", '[x](foo "title"', True),
("nested-paren-title", "[x](foo (a (b) c))", True),
]
# Bad markdown INSIDE code must never be flagged (it's an intentional example).
CODE_SAFE = [
("fenced-example", "```\n[x](\ny)\n```\n"),
("indented-example", "text\n\n [x](\n y)\n"),
("inline-code", "Use `[x](` in prose\n"),
]
# Cases where the FORMAL CommonMark/GFM grammar (what GitHub's cmark-gfm renders)
# disagrees with markdown-it-py, which is permissive. We follow the formal spec /
# GitHub behavior (these docs are GitHub-rendered), so these are verdict-asserted but
# excluded from the markdown-it-py cross-check.
SPEC_DIVERGENT = [
# An escaped newline inside a bare destination is a raw line ending — GFM forbids
# it (GitHub won't render the link) though markdown-it-py permissively renders it.
("bare-escaped-newline", "[x](foo\\\nbar)", True),
]
@pytest.mark.parametrize("name,src,should_flag", CASES, ids=[c[0] for c in CASES])
def test_checker_verdict(name, src, should_flag):
assert _flags(src) is should_flag
@pytest.mark.parametrize("name,src,should_flag", SPEC_DIVERGENT,
ids=[c[0] for c in SPEC_DIVERGENT])
def test_spec_divergent_verdict(name, src, should_flag):
# Follow the formal GFM grammar / GitHub rendering, not markdown-it-py's permissive
# behavior — so these are asserted by hand, not cross-checked against the parser.
assert _flags(src) is should_flag
@pytest.mark.parametrize("name,src,should_flag", CASES, ids=[c[0] for c in CASES])
def test_agrees_with_commonmark(name, src, should_flag):
if _MD is None:
pytest.skip("markdown-it-py not installed")
# The checker should flag exactly the cases that do NOT render as a link/image.
assert _flags(src) is (not _renders(src))
@pytest.mark.parametrize("name,src", CODE_SAFE, ids=[c[0] for c in CODE_SAFE])
def test_code_spans_never_flagged(name, src):
assert _flags(src) is False
def test_empty_and_missing_inputs():
# No files -> ok (exit 0 path).
assert cmc.main(["prog"]) == 0
# A file with no links -> no problems.
with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False) as tf:
tf.write("# Title\n\nJust prose, no links.\n")
p = Path(tf.name)
try:
assert cmc.check_file(p) == []
finally:
p.unlink()