From 52f6aeb65523676fea250359303c854b2e47c755 Mon Sep 17 00:00:00 2001 From: Harsh Date: Thu, 12 Nov 2026 17:43:01 -0800 Subject: [PATCH 1/4] CI: fail-closed fast path for prose-only docs changes (#188) --- .github/workflows/ci.yml | 144 ++++++++++++++--- CONTRIBUTING.md | 1 + scripts/ci-docs-check.py | 255 ++++++++++++++++++++++++++++++ scripts/ci-docs-classify.py | 211 ++++++++++++++++++++++++ scripts/ci-docs-fastpath.test.mjs | 194 +++++++++++++++++++++++ 5 files changed, 783 insertions(+), 22 deletions(-) create mode 100644 scripts/ci-docs-check.py create mode 100644 scripts/ci-docs-classify.py create mode 100644 scripts/ci-docs-fastpath.test.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6461d23..835dcf4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,8 +10,50 @@ permissions: contents: read jobs: + # Fail-closed docs classifier (issue #188). Outputs docs_only=true only when + # every PR change is on the prose allowlist; any doubt, error, or non-PR + # event yields docs_only=false so the full checks below still run. Required + # job names are unchanged, so branch protection is unaffected. + classify: + timeout-minutes: 5 + runs-on: ubuntu-latest + outputs: + docs_only: ${{ steps.classify.outputs.docs_only }} + docs_files: ${{ steps.classify.outputs.docs_files }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 24 + - name: Test the docs fast-path classifier + run: node --test scripts/ci-docs-fastpath.test.mjs + - id: classify + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + python3 scripts/ci-docs-classify.py --base "${{ github.event.pull_request.base.sha }}" --head HEAD + else + echo "docs_only=false" >> "$GITHUB_OUTPUT" + echo "docs_files=[]" >> "$GITHUB_OUTPUT" + echo "reason=non-PR event runs full checks" >> "$GITHUB_OUTPUT" + echo "docs_only=false" + fi + + docs: + timeout-minutes: 5 + runs-on: ubuntu-latest + needs: [classify] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Validate changed Markdown links and anchors + env: + DOCS_FILES: ${{ needs.classify.outputs.docs_files }} + run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" + runtime: timeout-minutes: 20 + needs: [classify] strategy: fail-fast: false matrix: @@ -19,36 +61,54 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Validate changed docs links (docs-only fast path) + if: needs.classify.outputs.docs_only == 'true' + env: + DOCS_FILES: ${{ needs.classify.outputs.docs_files }} + run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 + if: needs.classify.outputs.docs_only != 'true' with: go-version: 1.27.x cache: true - - run: go test ./... - - if: matrix.os == 'ubuntu-latest' + - if: needs.classify.outputs.docs_only != 'true' + run: go test ./... + - if: matrix.os == 'ubuntu-latest' && needs.classify.outputs.docs_only != 'true' run: go test -race -count=1 ./... - - run: go vet ./... - - run: go build ./cmd/agentintercom - - run: go build ./cmd/agentintercom-conformance - - run: go run ./cmd/agentintercom demo + - if: needs.classify.outputs.docs_only != 'true' + run: go vet ./... + - if: needs.classify.outputs.docs_only != 'true' + run: go build ./cmd/agentintercom + - if: needs.classify.outputs.docs_only != 'true' + run: go build ./cmd/agentintercom-conformance + - if: needs.classify.outputs.docs_only != 'true' + run: go run ./cmd/agentintercom demo - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + if: needs.classify.outputs.docs_only != 'true' with: node-version: 24 cache: npm cache-dependency-path: sdk/typescript/package-lock.json - - run: npm ci --ignore-scripts + - if: needs.classify.outputs.docs_only != 'true' + run: npm ci --ignore-scripts working-directory: sdk/typescript - - if: matrix.os == 'ubuntu-latest' + - if: matrix.os == 'ubuntu-latest' && needs.classify.outputs.docs_only != 'true' run: node --test scripts/managed-runtime-manifest.test.mjs - - run: npm run build:native + - if: needs.classify.outputs.docs_only != 'true' + run: npm run build:native working-directory: sdk/typescript - - run: npm run pack:distribution + - if: needs.classify.outputs.docs_only != 'true' + run: npm run pack:distribution working-directory: sdk/typescript - - run: npm run test:distribution + - if: needs.classify.outputs.docs_only != 'true' + run: npm run test:distribution working-directory: sdk/typescript npm-platforms: timeout-minutes: 20 runs-on: ubuntu-latest + needs: [classify] + if: needs.classify.outputs.docs_only != 'true' steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 @@ -64,23 +124,37 @@ jobs: typescript-sdk: timeout-minutes: 10 runs-on: ubuntu-latest + needs: [classify] defaults: run: working-directory: sdk/typescript steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Validate changed docs links (docs-only fast path) + if: needs.classify.outputs.docs_only == 'true' + env: + DOCS_FILES: ${{ needs.classify.outputs.docs_files }} + run: python3 "$GITHUB_WORKSPACE/scripts/ci-docs-check.py" --files-json "$DOCS_FILES" --repo "$GITHUB_WORKSPACE" - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + if: needs.classify.outputs.docs_only != 'true' with: node-version: 24 cache: npm cache-dependency-path: sdk/typescript/package-lock.json - - run: npm ci - - run: npm run typecheck - - run: npm run build - - run: npm run test:errors - - run: npm run test:release - - run: node --test ../../scripts/verification-bundle.test.mjs - - run: npm audit --audit-level=high + - if: needs.classify.outputs.docs_only != 'true' + run: npm ci + - if: needs.classify.outputs.docs_only != 'true' + run: npm run typecheck + - if: needs.classify.outputs.docs_only != 'true' + run: npm run build + - if: needs.classify.outputs.docs_only != 'true' + run: npm run test:errors + - if: needs.classify.outputs.docs_only != 'true' + run: npm run test:release + - if: needs.classify.outputs.docs_only != 'true' + run: node --test ../../scripts/verification-bundle.test.mjs + - if: needs.classify.outputs.docs_only != 'true' + run: npm audit --audit-level=high node-compatibility: timeout-minutes: 10 @@ -89,6 +163,8 @@ jobs: matrix: node: [20, 22] runs-on: ubuntu-latest + needs: [classify] + if: needs.classify.outputs.docs_only != 'true' steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 @@ -102,23 +178,35 @@ jobs: interoperability: timeout-minutes: 10 runs-on: ubuntu-latest + needs: [classify] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Validate changed docs links (docs-only fast path) + if: needs.classify.outputs.docs_only == 'true' + env: + DOCS_FILES: ${{ needs.classify.outputs.docs_files }} + run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 + if: needs.classify.outputs.docs_only != 'true' with: go-version: 1.27.x cache: true - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + if: needs.classify.outputs.docs_only != 'true' with: node-version: 24 cache: npm cache-dependency-path: sdk/typescript/package-lock.json - - run: go build -o /tmp/agentintercom ./cmd/agentintercom - - run: npm ci + - if: needs.classify.outputs.docs_only != 'true' + run: go build -o /tmp/agentintercom ./cmd/agentintercom + - if: needs.classify.outputs.docs_only != 'true' + run: npm ci working-directory: sdk/typescript - - run: npm run build + - if: needs.classify.outputs.docs_only != 'true' + run: npm run build working-directory: sdk/typescript - - run: npm run test:integration + - if: needs.classify.outputs.docs_only != 'true' + run: npm run test:integration working-directory: sdk/typescript env: OCTOBER_BUS_BINARY: /tmp/agentintercom @@ -126,6 +214,8 @@ jobs: hosted: timeout-minutes: 20 runs-on: ubuntu-latest + needs: [classify] + if: needs.classify.outputs.docs_only != 'true' services: postgres: image: postgres:17@sha256:b8faeff7712663c2773a190181e1246e37e364b887611c04658c28b44e2408fe @@ -158,6 +248,8 @@ jobs: workspace-ui: timeout-minutes: 15 runs-on: ubuntu-latest + needs: [classify] + if: needs.classify.outputs.docs_only != 'true' defaults: run: working-directory: web @@ -178,8 +270,16 @@ jobs: vulnerabilities: timeout-minutes: 10 runs-on: ubuntu-latest + needs: [classify] steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Validate changed docs links (docs-only fast path) + if: needs.classify.outputs.docs_only == 'true' + env: + DOCS_FILES: ${{ needs.classify.outputs.docs_files }} + run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" - uses: golang/govulncheck-action@032d45514ae346b1db93c04b0c90b841c370344f # v1 + if: needs.classify.outputs.docs_only != 'true' with: go-version-input: 1.27.x go-package: ./... diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87aef8d..70e9925 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,7 @@ New adapters should keep registration, heartbeat, credential handling, and clean - Protocol, runtime, dependency, security, and workflow changes require code-owner review. - Resolve review conversations and request a new review after material changes. - Never merge with a failed, skipped, or incomplete required check. +- Pull requests that touch only the prose allowlist (`README.md`, root contributor docs, `docs/releases.md`, `docs/release-notes-*.md`) take a fast path: every required check still runs and passes, but validates documentation links/anchors instead of the runtime matrix. Any other change, or any classifier doubt, runs the full checks. - Changes to a pinned dependency must update the public pin record in the same pull request. - Release tags are created only from reviewed commits with passing checks. diff --git a/scripts/ci-docs-check.py b/scripts/ci-docs-check.py new file mode 100644 index 0000000..ecf1076 --- /dev/null +++ b/scripts/ci-docs-check.py @@ -0,0 +1,255 @@ +#!/usr/bin/env python3 +"""Local Markdown link and anchor checker for the CI docs fast path (#188). + +Validates outgoing links from a given set of Markdown files without any +network access: relative file targets must exist inside the repository, +``#anchor`` targets must match a GitHub-style heading slug in the target +document, and reference definitions must resolve. Absolute URLs, ``mailto:`` +links, and other URI schemes are skipped (never fetched). + +Usage:: + + python3 scripts/ci-docs-check.py --files-json '["README.md"]' [--repo DIR] + +Exits 0 when every check passes (or there is nothing to check) and 1 with +``file:line: message`` diagnostics otherwise. +""" + +import json +import os +import re +import sys + +INLINE_LINK = re.compile(r"(!?)\[([^\]]*)\]\(([^)]*)\)") +REFERENCE_USE = re.compile(r"(!?)\[([^\]]+)\]\[([^\]]*)\]") +REFERENCE_DEF = re.compile(r"^[ ]{0,3}\[([^\]]+)\]:[ \t]*(\S+)[ \t]*(\"([^\"]*)\"|'([^']*)'|\(([^)]*)\))?[ \t]*$") +AUTOLINK = re.compile(r"<((?:\./|\../|[A-Za-z0-9])[^\s<>]*)>") +HEADING = re.compile(r"^(#{1,6})\s+(.+?)[ \t]*#*[ \t]*$") +FENCED = re.compile(r"^(```|~~~)") +SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:") +HTML_ANCHOR = re.compile(r']*?(?:id|name)\s*=\s*["\']([^"\']+)["\']', re.IGNORECASE) +HTML_TAG = re.compile(r"]*)?/?>") + + +def github_slug(heading): + """Best-effort GitHub heading slug (lowercase, punctuation stripped).""" + text = re.sub(r"`([^`]*)`", r"\1", heading).strip().lower() + text = re.sub(r"[^\w\s\-]", "", text, flags=re.UNICODE) + return re.sub(r"\s+", "-", text) + + +def document_anchors(lines): + """Collect anchor slugs defined by headings and explicit HTML anchors.""" + anchors = set() + counts = {} + for line in lines: + match = HEADING.match(line) + if match: + slug = github_slug(match.group(2)) + seen = counts.get(slug, 0) + counts[slug] = seen + 1 + anchors.add(slug if seen == 0 else "%s-%d" % (slug, seen)) + for anchor in HTML_ANCHOR.findall(line): + anchors.add(anchor) + return anchors + + +def blank_spans(text): + """Blank CommonMark-style code spans, which may cross line breaks. + + A run of N backticks is closed by the next run of exactly N backticks. + An unmatched run is literal text. Wrongly pairing two literal backticks + only hides text from validation (lenient), never flags valid docs. + """ + out = list(text) + index = 0 + while index < len(text): + if text[index] != "`": + index += 1 + continue + end = index + while end < len(text) and text[end] == "`": + end += 1 + run = text[index:end] + close = text.find(run, end) + if close == -1: + index = end + continue + for pos in range(index, close + len(run)): + if out[pos] != "\n": + out[pos] = " " + index = close + len(run) + return "".join(out) + + +def strip_code(lines): + """Blank fenced blocks and code spans so they are never link-checked.""" + out = [] + fence = None + for line in lines: + match = FENCED.match(line.lstrip()) + if match: + marker = match.group(1) + if fence is None: + fence = marker + elif fence == marker: + fence = None + out.append("") + continue + out.append("" if fence else line) + return blank_spans("\n".join(out)).split("\n") + + +def split_target(raw): + """Split a raw link destination into (path, anchor).""" + raw = raw.strip() + if raw.startswith("<") and raw.endswith(">") and len(raw) >= 2: + raw = raw[1:-1].strip() + else: + raw = raw.split()[0] if raw.split() else "" + if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ("'", '"'): + raw = raw[1:-1] + if "#" in raw: + path, anchor = raw.split("#", 1) + return path.strip(), anchor.strip() + return raw, "" + + +def check_file(repo, relpath, cache): + """Return a list of ``relpath:line: message`` errors for one document.""" + errors = [] + full = os.path.join(repo, relpath) + try: + with open(full, "r", encoding="utf-8") as handle: + lines = handle.read().splitlines() + except (OSError, UnicodeDecodeError) as exc: + return ["%s: cannot read file: %s" % (relpath, exc)] + visible = strip_code(lines) + definitions = {} + for line in visible: + match = REFERENCE_DEF.match(line) + if match: + key = " ".join(match.group(1).split()).lower() + definitions.setdefault(key, match.group(2)) + + def resolve(path, anchor, lineno, note): + if not path: + if anchor and anchor not in cache[relpath]: + errors.append("%s:%d: unknown anchor '#%s' %s" % (relpath, lineno, anchor, note)) + return + if SCHEME.match(path): + return # Remote or special schemes are never fetched. + if path.startswith("/"): + target = os.path.normpath(os.path.join(repo, path.lstrip("/"))) + else: + target = os.path.normpath(os.path.join(repo, os.path.dirname(relpath), path)) + if target != repo and not target.startswith(repo + os.sep): + errors.append("%s:%d: link escapes repository: %s" % (relpath, lineno, path)) + return + if not os.path.exists(target): + errors.append("%s:%d: missing link target: %s" % (relpath, lineno, path)) + return + if anchor and os.path.isfile(target) and target.endswith(".md"): + target_rel = os.path.relpath(target, repo) + if target_rel not in cache: + try: + with open(target, "r", encoding="utf-8") as handle: + cache[target_rel] = document_anchors(handle.read().splitlines()) + except (OSError, UnicodeDecodeError): + errors.append("%s:%d: cannot read link target: %s" % (relpath, lineno, path)) + return + if anchor not in cache[target_rel]: + errors.append( + "%s:%d: unknown anchor '#%s' in %s" % (relpath, lineno, anchor, path) + ) + + for lineno, line in enumerate(visible, 1): + if REFERENCE_DEF.match(line): + continue + scan = HTML_TAG.sub("", line) # Never mistake markup for autolinks. + for match in INLINE_LINK.finditer(scan): + path, anchor = split_target(match.group(3)) + if not path and not anchor: + continue + resolve(path, anchor, lineno, "in '%s'" % match.group(0)[:60]) + for match in REFERENCE_USE.finditer(scan): + label = match.group(3) or match.group(2) + key = " ".join(label.split()).lower() + if key not in definitions: + # Ignore bare [brackets] with no matching definition. + if match.group(3) == "" and match.group(0).endswith("[]"): + errors.append("%s:%d: undefined reference '[%s]'" % (relpath, lineno, label)) + elif match.group(3) != "": + errors.append("%s:%d: undefined reference '[%s]'" % (relpath, lineno, label)) + continue + path, anchor = split_target(definitions[key]) + if not path and not anchor: + continue + resolve(path, anchor, lineno, "for reference '[%s]'" % label) + for match in AUTOLINK.finditer(scan): + raw = match.group(1) + if SCHEME.match(raw): + continue # Remote or special schemes are never fetched. + path, anchor = split_target(raw) + if not path and not anchor: + continue + resolve(path, anchor, lineno, "in autolink") + return errors + + +def main(argv): + files_json = None + repo = os.getcwd() + index = 0 + while index < len(argv): + arg = argv[index] + if arg == "--files-json" and index + 1 < len(argv): + files_json = argv[index + 1] + index += 2 + elif arg == "--repo" and index + 1 < len(argv): + repo = argv[index + 1] + index += 2 + else: + print("error: unknown argument: %s" % arg, file=sys.stderr) + return 2 + if files_json is None: + print("error: need --files-json", file=sys.stderr) + return 2 + try: + files = json.loads(files_json) + except ValueError as exc: + print("error: invalid --files-json: %s" % exc, file=sys.stderr) + return 2 + if not isinstance(files, list): + print("error: --files-json must be a list", file=sys.stderr) + return 2 + repo = os.path.realpath(repo) + cache = {} + errors = [] + for relpath in sorted(set(files)): + if not isinstance(relpath, str) or not relpath.endswith(".md"): + continue + full = os.path.normpath(os.path.join(repo, relpath)) + if full != repo and not full.startswith(repo + os.sep): + errors.append("%s: path escapes repository" % relpath) + continue + if not os.path.isfile(full): + continue # Deleted or renamed-away files have no links to check. + try: + with open(full, "r", encoding="utf-8") as handle: + cache[relpath] = document_anchors(handle.read().splitlines()) + except (OSError, UnicodeDecodeError) as exc: + errors.append("%s: cannot read file: %s" % (relpath, exc)) + continue + errors.extend(check_file(repo, relpath, cache)) + for error in errors: + print(error) + if errors: + print("%d broken docs link(s) found" % len(errors), file=sys.stderr) + return 1 + print("docs link check passed (%d file(s))" % len(cache)) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/ci-docs-classify.py b/scripts/ci-docs-classify.py new file mode 100644 index 0000000..0ea3cc2 --- /dev/null +++ b/scripts/ci-docs-classify.py @@ -0,0 +1,211 @@ +#!/usr/bin/env python3 +"""Fail-closed classifier for the CI documentation fast path (issue #188). + +Decides whether every change in a pull request is confined to an explicit, +small allowlist of prose-only Markdown files. Anything else -- code, +workflows, scripts, specs, schemas, manifests, examples, dependencies, +unknown statuses, renames crossing the allowlist boundary, empty changesets, +or any classification error -- resolves to ``docs_only=false`` so the full +CI checks run. + +The allowlist is deliberately exact paths plus one narrow release-notes glob: + +* ``README.md``, ``CONTRIBUTING.md``, ``CODE_OF_CONDUCT.md``, ``SECURITY.md``, + ``CHANGELOG.md``, ``ROADMAP.md`` (root contributor/community prose) +* ``docs/releases.md`` and ``docs/release-notes-*.md`` (release prose) + +Everything under ``docs/`` that describes protocol surface, dependencies, +operations, or architecture is intentionally excluded: those PRs still run +the full checks. + +Usage (CI, pull_request events only):: + + python3 scripts/ci-docs-classify.py --base --head + +writes ``docs_only``, ``docs_files`` (JSON list of changed ``.md`` files +present at head, for the link checker) and ``reason`` to ``$GITHUB_OUTPUT`` +and prints them to stdout. ``--entries-json`` accepts canned diff entries +for the self-test (see ``scripts/ci-docs-fastpath.test.mjs``) instead of +running git. +""" + +import json +import os +import subprocess +import sys + +ALLOWLIST_EXACT = frozenset( + { + "README.md", + "CONTRIBUTING.md", + "CODE_OF_CONDUCT.md", + "SECURITY.md", + "CHANGELOG.md", + "ROADMAP.md", + "docs/releases.md", + } +) +ALLOWLIST_RELEASE_NOTES_PREFIX = "docs/release-notes-" + + +def is_allowlisted(path): + """True only for prose-only Markdown paths on the explicit allowlist.""" + if not path or not isinstance(path, str): + return False + if "\\" in path or path.startswith("/") or path != os.path.normpath(path): + return False + if path.startswith(".") or ".." in path.split("/"): + return False + if path in ALLOWLIST_EXACT: + return True + if ( + path.startswith(ALLOWLIST_RELEASE_NOTES_PREFIX) + and path.endswith(".md") + and "/" not in path[len(ALLOWLIST_RELEASE_NOTES_PREFIX):] + ): + return True + return False + + +def classify_entries(entries): + """Classify canned ``(status, [paths])`` diff entries. + + Returns ``(docs_only, reason, docs_files)``. Every unknown input fails + closed to ``docs_only=False``. + """ + if not entries: + return False, "empty changeset runs full checks", [] + docs_files = [] + for entry in entries: + if not isinstance(entry, (list, tuple)) or len(entry) != 2: + return False, "unparseable diff entry runs full checks", [] + status, paths = entry + if not isinstance(status, str) or not status: + return False, "unparseable diff status runs full checks", [] + if not isinstance(paths, list) or not paths: + return False, "unparseable diff paths run full checks", [] + kind = status[0] + if kind in ("A", "M", "D"): + if len(paths) != 1: + return False, "malformed diff entry runs full checks", [] + if not is_allowlisted(paths[0]): + return False, "non-docs change runs full checks: %s" % paths[0], [] + if kind in ("A", "M") and paths[0] not in docs_files: + docs_files.append(paths[0]) + elif kind == "R": + # Both sides of a rename must stay inside the allowlist. + if len(paths) != 2: + return False, "malformed rename runs full checks", [] + old, new = paths + if not is_allowlisted(old) or not is_allowlisted(new): + return False, "rename crossing docs boundary runs full checks", [] + if new not in docs_files: + docs_files.append(new) + else: + # Type changes, copies, unmerged, unknown, or anything else. + return False, "unrecognized change runs full checks: %s" % status, [] + return True, "all changes are allowlisted prose docs", sorted(docs_files) + + +def git_name_status(repo, base, head): + """Return ``(status, [paths])`` entries from ``git diff --name-status -z``.""" + proc = subprocess.run( + ["git", "diff", "--name-status", "-z", "%s...%s" % (base, head)], + cwd=repo or os.getcwd(), + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + check=False, + ) + if proc.returncode != 0: + raise RuntimeError("git diff failed: %s" % proc.stderr.decode("utf-8", "replace").strip()) + tokens = proc.stdout.split(b"\0") + entries = [] + index = 0 + while index < len(tokens): + status = tokens[index].decode("utf-8", "strict") + index += 1 + if status == "": + continue + if not tokens[index:]: + raise RuntimeError("truncated git diff output") + if status[0] in ("R", "C"): + if len(tokens) - index < 2: + raise RuntimeError("truncated git diff output") + old = tokens[index].decode("utf-8", "strict") + new = tokens[index + 1].decode("utf-8", "strict") + index += 2 + entries.append((status, [old, new])) + else: + path = tokens[index].decode("utf-8", "strict") + index += 1 + entries.append((status, [path])) + return entries + + +def write_output(docs_only, reason, docs_files): + line = "docs_only=%s" % ("true" if docs_only else "false") + files = "docs_files=%s" % json.dumps(sorted(docs_files)) + clean_reason = " ".join(reason.split()) + print(line) + print(files) + print("reason=%s" % clean_reason) + output_path = os.environ.get("GITHUB_OUTPUT") + if output_path: + with open(output_path, "a", encoding="utf-8") as handle: + handle.write(line + "\n") + handle.write(files + "\n") + handle.write("reason=%s\n" % clean_reason) + + +def main(argv): + base = None + head = None + repo = None + entries_json = None + index = 0 + while index < len(argv): + arg = argv[index] + if arg == "--base" and index + 1 < len(argv): + base = argv[index + 1] + index += 2 + elif arg == "--head" and index + 1 < len(argv): + head = argv[index + 1] + index += 2 + elif arg == "--repo" and index + 1 < len(argv): + repo = argv[index + 1] + index += 2 + elif arg == "--entries-json" and index + 1 < len(argv): + entries_json = argv[index + 1] + index += 2 + else: + print("error: unknown argument: %s" % arg, file=sys.stderr) + return 2 + try: + if entries_json is not None: + entries = json.loads(entries_json) + if not isinstance(entries, list): + raise ValueError("entries JSON must be a list") + docs_only, reason, docs_files = classify_entries( + [(status, paths) for status, paths in entries] + ) + elif base and head: + try: + entries = git_name_status(repo, base, head) + except Exception as exc: + # A diff we cannot compute is not a docs-only diff: run + # everything rather than failing the whole workflow open. + write_output(False, "diff unavailable runs full checks: %s" % exc, []) + return 0 + docs_only, reason, docs_files = classify_entries(entries) + else: + print("error: need --base/--head or --entries-json", file=sys.stderr) + return 2 + except Exception as exc: # noqa: BLE001 - fail closed with a loud error. + print("error: classifier failed closed: %s" % exc, file=sys.stderr) + return 1 + write_output(docs_only, reason, docs_files) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/ci-docs-fastpath.test.mjs b/scripts/ci-docs-fastpath.test.mjs new file mode 100644 index 0000000..77cd096 --- /dev/null +++ b/scripts/ci-docs-fastpath.test.mjs @@ -0,0 +1,194 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { execFileSync } from 'node:child_process' +import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' + +const root = join(dirname(fileURLToPath(import.meta.url)), '..') +const classify = join(root, 'scripts', 'ci-docs-classify.py') +const check = join(root, 'scripts', 'ci-docs-check.py') + +const classifyEntries = (entries) => { + const out = execFileSync('python3', [classify, '--entries-json', JSON.stringify(entries)], { + cwd: root, + encoding: 'utf8' + }) + const docsOnly = /^docs_only=(true|false)$/m.exec(out)?.[1] === 'true' + const docsFiles = JSON.parse(/^docs_files=(.+)$/m.exec(out)?.[1] ?? 'null') + return { docsOnly, docsFiles, out } +} + +test('classifier fast-paths only the prose allowlist', () => { + assert.equal(classifyEntries([['M', ['README.md']]]).docsOnly, true) + const all = classifyEntries([ + ['M', ['README.md']], + ['M', ['CONTRIBUTING.md']], + ['M', ['CODE_OF_CONDUCT.md']], + ['M', ['SECURITY.md']], + ['M', ['CHANGELOG.md']], + ['M', ['ROADMAP.md']], + ['A', ['docs/releases.md']], + ['A', ['docs/release-notes-9.9.9.md']] + ]) + assert.equal(all.docsOnly, true) + assert.deepEqual(all.docsFiles, [ + 'CHANGELOG.md', + 'CODE_OF_CONDUCT.md', + 'CONTRIBUTING.md', + 'README.md', + 'ROADMAP.md', + 'SECURITY.md', + 'docs/release-notes-9.9.9.md', + 'docs/releases.md' + ]) +}) + +test('classifier fails closed on code, mixed, and sensitive paths', () => { + const closed = [ + [['M', ['bus/store.go']]], + [['M', ['README.md']], ['M', ['bus/store.go']]], + [['M', ['.github/workflows/ci.yml']]], + [['M', ['scripts/ci-docs-check.py']]], + [['M', ['spec/README.md']]], + [['M', ['examples/demo/main.go']]], + [['M', ['go.mod']]], + [['M', ['go.sum']]], + [['M', ['sdk/typescript/package-lock.json']]], + [['M', ['manifest.json']]], + [['M', ['adapters/demo/adapter.json']]], + [['M', ['docs/dependencies.md']]], + [['M', ['docs/protocol-surface.md']]], + [['M', ['docs/threat-model.md']]], + [['M', ['docs/architecture/storage-backends.md']]], + [['M', ['assets/agent-intercom-banner.png']]], + [['M', ['README.md']], ['A', ['assets/new.png']]], + [['M', ['docs/release-notes-9.9.9.txt']]], + [['M', ['docs/nested/release-notes-1.md']]], + [['M', ['../escape.md']]], + [['M', ['/abs/path.md']]], + [['M', ['docs\\windows.md']]], + [], + [[['M'], ['README.md']]], + [['U', ['README.md']]], + [['X', ['README.md']]], + [['T', ['README.md']]], + [['C123', ['README.md', 'CONTRIBUTING.md']]], + [['M', ['README.md', 'CONTRIBUTING.md']]] + ] + for (const entries of closed) { + assert.equal(classifyEntries(entries).docsOnly, false, JSON.stringify(entries)) + } +}) + +test('classifier handles renames and deletions conservatively', () => { + assert.equal(classifyEntries([['D', ['README.md']]]).docsOnly, true) + assert.equal(classifyEntries([['D', ['bus/store.go']]]).docsOnly, false) + assert.equal(classifyEntries([['R100', ['README.md', 'CONTRIBUTING.md']]]).docsOnly, true) + assert.equal(classifyEntries([['R100', ['README.md', 'docs/protocol-surface.md']]]).docsOnly, false) + assert.equal(classifyEntries([['R100', ['bus/a.go', 'bus/b.go']]]).docsOnly, false) + assert.equal(classifyEntries([['R100', ['README.md']]]).docsOnly, false) +}) + +test('classifier rejects malformed input loudly', () => { + assert.throws(() => classifyEntries({}), /failed closed|non-zero|Command failed/) + assert.throws(() => execFileSync('python3', [classify, '--bogus'], { cwd: root }), /Command failed/) + assert.throws(() => execFileSync('python3', [classify], { cwd: root }), /Command failed/) +}) + +test('classifier resolves --base/--head diffs end to end in git', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-classify-test-')) + try { + const git = (args) => execFileSync('git', args, { cwd: repo, encoding: 'utf8' }) + git(['init', '-q']) + git(['config', 'user.email', 'test@example.invalid']) + git(['config', 'user.name', 'Classifier test']) + git(['config', 'commit.gpgsign', 'false']) + writeFileSync(join(repo, 'README.md'), '# Hi\n') + writeFileSync(join(repo, 'main.go'), 'package main\n') + git(['add', '.']) + git(['commit', '-qm', 'base']) + const base = git(['rev-parse', 'HEAD']).trim() + writeFileSync(join(repo, 'README.md'), '# Hi there\n') + git(['commit', '-qam', 'docs']) + const docsOnly = git(['rev-parse', 'HEAD']).trim() + writeFileSync(join(repo, 'main.go'), 'package main\n// change\n') + git(['commit', '-qam', 'code']) + const code = git(['rev-parse', 'HEAD']).trim() + + const run = (head, env = {}) => + execFileSync('python3', [classify, '--base', base, '--head', head, '--repo', repo], { + cwd: root, + encoding: 'utf8', + env: { ...process.env, ...env } + }) + assert.match(run(docsOnly), /^docs_only=true$/m) + assert.match(run(docsOnly), /"README\.md"/) + assert.match(run(code), /^docs_only=false$/m) + // Unknown revisions fail closed to full checks without failing the job. + assert.match(run('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef'), /^docs_only=false$/m) + + const outputFile = join(repo, 'github-output') + writeFileSync(outputFile, '') + run(docsOnly, { GITHUB_OUTPUT: outputFile }) + const written = readFileSync(outputFile, 'utf8') + assert.match(written, /^docs_only=true$/m) + assert.match(written, /^docs_files=\[/m) + assert.match(written, /^reason=.+$/m) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +const checkFiles = (repo, files) => { + try { + const out = execFileSync('python3', [check, '--files-json', JSON.stringify(files), '--repo', repo], { + encoding: 'utf8' + }) + return { ok: true, out } + } catch (error) { + return { ok: false, out: `${error.stdout ?? ''}\n${error.stderr ?? ''}` } + } +} + +test('docs checker validates links and anchors without network', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docscheck-test-')) + try { + mkdirSync(join(repo, 'docs'), { recursive: true }) + writeFileSync(join(repo, 'docs', 'target.md'), '# Getting Started\n\nBody.\n\n# Getting Started\n\nDup.\n') + writeFileSync( + join(repo, 'README.md'), + '# Title\n\nSee [target](docs/target.md) and [anchor](docs/target.md#getting-started) ' + + 'and [dup](docs/target.md#getting-started-1) and [self](#title).\n\n' + + 'Remote [web](https://example.invalid/x) and [mail](mailto:a@example.invalid) skipped.\n\n' + + '```md\n[broken](nope.md)\n```\n\nInline `[code](#nope)` ignored.\n\n' + + '[ref][guide] and [collapsed][] work.\n\n[guide]: docs/target.md\n[collapsed]: #title\n\n' + + '

\n
\n

\n\n' + + 'A `--flag ` code span is ignored.\n' + ) + const good = checkFiles(repo, ['README.md']) + assert.equal(good.ok, true, good.out) + + writeFileSync(join(repo, 'BAD.md'), '# Bad\n\n[missing](docs/nope.md) [anchor](#nope) ![img](img.png)\n') + const bad = checkFiles(repo, ['BAD.md']) + assert.equal(bad.ok, false) + assert.match(bad.out, /BAD\.md:\d+: missing link target: docs\/nope\.md/) + assert.match(bad.out, /BAD\.md:\d+: unknown anchor '#nope'/) + assert.match(bad.out, /BAD\.md:\d+: missing link target: img\.png/) + + writeFileSync(join(repo, 'REF.md'), '# Ref\n\n[undef][nope] and [shortcut].\n\n[shortcut]: #ref\n') + const ref = checkFiles(repo, ['REF.md']) + assert.equal(ref.ok, false, ref.out) + assert.match(ref.out, /undefined reference '\[nope\]'/) + + // Deleted files, non-markdown input, and empty sets pass trivially. + assert.equal(checkFiles(repo, ['GONE.md']).ok, true) + assert.equal(checkFiles(repo, ['main.go']).ok, true) + assert.equal(checkFiles(repo, []).ok, true) + // Escapes and unreadable targets fail rather than pass silently. + assert.equal(checkFiles(repo, ['../escape.md']).ok, false) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) From 49bcf2058032e0854e3726eb791a176d86cd9e07 Mon Sep 17 00:00:00 2001 From: Harsh Date: Fri, 13 Nov 2026 01:53:04 -0800 Subject: [PATCH 2/4] Redesign docs fast path per round-1 audit: single Ubuntu validation, fail-closed gates - Run the docs link check once in classify over all tracked Markdown (--all) instead of pasting a validator step into every required job; nothing docs-related executes on Windows/macOS anymore. - Checker now follows HTML href/src/srcset and own-repo blob/tree/raw page URLs, validates inbound links across the repo, drops the false autolink branch, and slugs headings exactly like GitHub (each space becomes a hyphen). Fenced code no longer defines anchors. - Required jobs get if: !cancelled() plus a gate step that fails when classify did not succeed, so a classifier failure blocks by design rather than by skipped-check side effect. Removed the no-op docs job and the docs_files plumbing; base SHA passed via env; govulncheck reuses the existing checkout. --- .github/workflows/ci.yml | 71 ++++++------ CONTRIBUTING.md | 2 +- scripts/ci-docs-check.py | 173 +++++++++++++++++++++++------- scripts/ci-docs-fastpath.test.mjs | 119 ++++++++++++++++++++ 4 files changed, 291 insertions(+), 74 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 835dcf4..1c2c013 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,14 +12,16 @@ permissions: jobs: # Fail-closed docs classifier (issue #188). Outputs docs_only=true only when # every PR change is on the prose allowlist; any doubt, error, or non-PR - # event yields docs_only=false so the full checks below still run. Required - # job names are unchanged, so branch protection is unaffected. + # event yields docs_only=false so the full checks below still run. The docs + # link validation runs once, here on Ubuntu, over all tracked Markdown on + # every PR (never on Windows/macOS); required jobs gate on this job's + # result instead of running the validator themselves. Required job names + # are unchanged, so branch protection is unaffected. classify: timeout-minutes: 5 runs-on: ubuntu-latest outputs: docs_only: ${{ steps.classify.outputs.docs_only }} - docs_files: ${{ steps.classify.outputs.docs_files }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -30,30 +32,23 @@ jobs: - name: Test the docs fast-path classifier run: node --test scripts/ci-docs-fastpath.test.mjs - id: classify + env: + PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} run: | if [ "${{ github.event_name }}" = "pull_request" ]; then - python3 scripts/ci-docs-classify.py --base "${{ github.event.pull_request.base.sha }}" --head HEAD + python3 scripts/ci-docs-classify.py --base "$PR_BASE_SHA" --head HEAD else echo "docs_only=false" >> "$GITHUB_OUTPUT" - echo "docs_files=[]" >> "$GITHUB_OUTPUT" echo "reason=non-PR event runs full checks" >> "$GITHUB_OUTPUT" echo "docs_only=false" fi - - docs: - timeout-minutes: 5 - runs-on: ubuntu-latest - needs: [classify] - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Validate changed Markdown links and anchors - env: - DOCS_FILES: ${{ needs.classify.outputs.docs_files }} - run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" + - name: Validate all tracked Markdown links and anchors + run: python3 scripts/ci-docs-check.py --all runtime: timeout-minutes: 20 needs: [classify] + if: ${{ !cancelled() }} strategy: fail-fast: false matrix: @@ -61,11 +56,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Validate changed docs links (docs-only fast path) - if: needs.classify.outputs.docs_only == 'true' - env: - DOCS_FILES: ${{ needs.classify.outputs.docs_files }} - run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" + - name: Fail closed when docs classification did not succeed + if: ${{ needs.classify.result != 'success' }} + run: | + echo "docs classification did not succeed; failing closed." + exit 1 - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 if: needs.classify.outputs.docs_only != 'true' with: @@ -125,16 +120,17 @@ jobs: timeout-minutes: 10 runs-on: ubuntu-latest needs: [classify] + if: ${{ !cancelled() }} defaults: run: working-directory: sdk/typescript steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Validate changed docs links (docs-only fast path) - if: needs.classify.outputs.docs_only == 'true' - env: - DOCS_FILES: ${{ needs.classify.outputs.docs_files }} - run: python3 "$GITHUB_WORKSPACE/scripts/ci-docs-check.py" --files-json "$DOCS_FILES" --repo "$GITHUB_WORKSPACE" + - name: Fail closed when docs classification did not succeed + if: ${{ needs.classify.result != 'success' }} + run: | + echo "docs classification did not succeed; failing closed." + exit 1 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 if: needs.classify.outputs.docs_only != 'true' with: @@ -179,13 +175,14 @@ jobs: timeout-minutes: 10 runs-on: ubuntu-latest needs: [classify] + if: ${{ !cancelled() }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Validate changed docs links (docs-only fast path) - if: needs.classify.outputs.docs_only == 'true' - env: - DOCS_FILES: ${{ needs.classify.outputs.docs_files }} - run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" + - name: Fail closed when docs classification did not succeed + if: ${{ needs.classify.result != 'success' }} + run: | + echo "docs classification did not succeed; failing closed." + exit 1 - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 if: needs.classify.outputs.docs_only != 'true' with: @@ -271,15 +268,17 @@ jobs: timeout-minutes: 10 runs-on: ubuntu-latest needs: [classify] + if: ${{ !cancelled() }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Validate changed docs links (docs-only fast path) - if: needs.classify.outputs.docs_only == 'true' - env: - DOCS_FILES: ${{ needs.classify.outputs.docs_files }} - run: python3 scripts/ci-docs-check.py --files-json "$DOCS_FILES" + - name: Fail closed when docs classification did not succeed + if: ${{ needs.classify.result != 'success' }} + run: | + echo "docs classification did not succeed; failing closed." + exit 1 - uses: golang/govulncheck-action@032d45514ae346b1db93c04b0c90b841c370344f # v1 if: needs.classify.outputs.docs_only != 'true' with: go-version-input: 1.27.x go-package: ./... + repo-checkout: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70e9925..d9e004f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,7 +59,7 @@ New adapters should keep registration, heartbeat, credential handling, and clean - Protocol, runtime, dependency, security, and workflow changes require code-owner review. - Resolve review conversations and request a new review after material changes. - Never merge with a failed, skipped, or incomplete required check. -- Pull requests that touch only the prose allowlist (`README.md`, root contributor docs, `docs/releases.md`, `docs/release-notes-*.md`) take a fast path: every required check still runs and passes, but validates documentation links/anchors instead of the runtime matrix. Any other change, or any classifier doubt, runs the full checks. +- Pull requests that touch only the prose allowlist (`README.md`, root contributor docs, `docs/releases.md`, `docs/release-notes-*.md`) take a fast path: documentation links/anchors across all tracked Markdown are validated once, and every required check still runs, gating on that result instead of the runtime matrix. Any other change, or any classifier doubt, runs the full checks. - Changes to a pinned dependency must update the public pin record in the same pull request. - Release tags are created only from reviewed commits with passing checks. diff --git a/scripts/ci-docs-check.py b/scripts/ci-docs-check.py index ecf1076..500f90a 100644 --- a/scripts/ci-docs-check.py +++ b/scripts/ci-docs-check.py @@ -1,14 +1,21 @@ #!/usr/bin/env python3 """Local Markdown link and anchor checker for the CI docs fast path (#188). -Validates outgoing links from a given set of Markdown files without any -network access: relative file targets must exist inside the repository, -``#anchor`` targets must match a GitHub-style heading slug in the target -document, and reference definitions must resolve. Absolute URLs, ``mailto:`` -links, and other URI schemes are skipped (never fetched). +Validates outgoing links from Markdown files without any network access: +relative file targets must exist inside the repository, ``#anchor`` targets +must match a GitHub-style heading slug in the target document, and reference +definitions must resolve. HTML ``href``/``src``/``srcset`` attributes and +links to our own repository's ``blob``/``tree``/``raw`` pages are checked the +same way. Anything else with a URI scheme is skipped (never fetched). + +Kept dependency-free on purpose: the check must run on a pristine runner +with only CPython and git, stay fully offline, and match GitHub's heading +slugs exactly, without a version-pinned third-party install. Covered by +``scripts/ci-docs-fastpath.test.mjs``. Usage:: + python3 scripts/ci-docs-check.py --all [--repo DIR] python3 scripts/ci-docs-check.py --files-json '["README.md"]' [--repo DIR] Exits 0 when every check passes (or there is nothing to check) and 1 with @@ -18,24 +25,66 @@ import json import os import re +import subprocess import sys INLINE_LINK = re.compile(r"(!?)\[([^\]]*)\]\(([^)]*)\)") REFERENCE_USE = re.compile(r"(!?)\[([^\]]+)\]\[([^\]]*)\]") REFERENCE_DEF = re.compile(r"^[ ]{0,3}\[([^\]]+)\]:[ \t]*(\S+)[ \t]*(\"([^\"]*)\"|'([^']*)'|\(([^)]*)\))?[ \t]*$") -AUTOLINK = re.compile(r"<((?:\./|\../|[A-Za-z0-9])[^\s<>]*)>") HEADING = re.compile(r"^(#{1,6})\s+(.+?)[ \t]*#*[ \t]*$") FENCED = re.compile(r"^(```|~~~)") SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:") HTML_ANCHOR = re.compile(r']*?(?:id|name)\s*=\s*["\']([^"\']+)["\']', re.IGNORECASE) HTML_TAG = re.compile(r"]*)?/?>") +HTML_LINK_ATTR = re.compile( + r"(?]+))", + re.IGNORECASE, +) +HTML_SRCSET_ATTR = re.compile( + r"(?]+))", + re.IGNORECASE, +) +# Only default-branch pages are rewritten: pinned commits and feature +# branches cannot be validated against the checkout, so those stay remote +# (skipped, never fetched). october-bus is the repository's legacy name. +OWN_REPO_PAGE = re.compile( + r"^https?://github\.com/october-dev/(?:agentintercom|october-bus)" + r"/(?:blob|tree)/(?:main|master|HEAD)/(.+?)/?$" +) +OWN_REPO_RAW = re.compile( + r"^https?://raw\.githubusercontent\.com/october-dev/(?:agentintercom|october-bus)" + r"/(?:main|master|HEAD)/(.+?)/?$" +) +LINE_ANCHOR = re.compile(r"^L\d+") def github_slug(heading): - """Best-effort GitHub heading slug (lowercase, punctuation stripped).""" + """GitHub heading slug: lowercase, punctuation stripped, each space a hyphen.""" text = re.sub(r"`([^`]*)`", r"\1", heading).strip().lower() - text = re.sub(r"[^\w\s\-]", "", text, flags=re.UNICODE) - return re.sub(r"\s+", "-", text) + text = re.sub(r"[^\w \-]", "", text, flags=re.UNICODE) + return text.replace(" ", "-") + + +def rewrite_own_repo_url(path): + """Map our own repo's blob/tree/raw page URLs to repo-relative paths.""" + bare = path.split("?", 1)[0] + for pattern in (OWN_REPO_PAGE, OWN_REPO_RAW): + match = pattern.match(bare) + if match: + return match.group(1) + return path + + +def srcset_candidates(value): + """Split a srcset attribute into candidate URLs (descriptors dropped).""" + if value.strip().lower().startswith("data:"): + return [] + candidates = [] + for chunk in value.split(","): + token = chunk.strip().split() + if token: + candidates.append(token[0]) + return candidates def document_anchors(lines): @@ -82,8 +131,8 @@ def blank_spans(text): return "".join(out) -def strip_code(lines): - """Blank fenced blocks and code spans so they are never link-checked.""" +def strip_fences(lines): + """Blank fenced code blocks; inline code spans are left intact.""" out = [] fence = None for line in lines: @@ -97,7 +146,12 @@ def strip_code(lines): out.append("") continue out.append("" if fence else line) - return blank_spans("\n".join(out)).split("\n") + return out + + +def strip_code(lines): + """Blank fenced blocks and code spans so they are never link-checked.""" + return blank_spans("\n".join(strip_fences(lines))).split("\n") def split_target(raw): @@ -133,6 +187,9 @@ def check_file(repo, relpath, cache): definitions.setdefault(key, match.group(2)) def resolve(path, anchor, lineno, note): + path = rewrite_own_repo_url(path) + if anchor and LINE_ANCHOR.match(anchor): + anchor = "" # Pinned line links (#L10) have no heading slug. if not path: if anchor and anchor not in cache[relpath]: errors.append("%s:%d: unknown anchor '#%s' %s" % (relpath, lineno, anchor, note)) @@ -154,7 +211,9 @@ def resolve(path, anchor, lineno, note): if target_rel not in cache: try: with open(target, "r", encoding="utf-8") as handle: - cache[target_rel] = document_anchors(handle.read().splitlines()) + cache[target_rel] = document_anchors( + strip_fences(handle.read().splitlines()) + ) except (OSError, UnicodeDecodeError): errors.append("%s:%d: cannot read link target: %s" % (relpath, lineno, path)) return @@ -166,7 +225,21 @@ def resolve(path, anchor, lineno, note): for lineno, line in enumerate(visible, 1): if REFERENCE_DEF.match(line): continue - scan = HTML_TAG.sub("", line) # Never mistake markup for autolinks. + for tag in HTML_TAG.findall(line): + for match in HTML_LINK_ATTR.finditer(tag): + value = match.group(1) or match.group(2) or match.group(3) or "" + path, anchor = split_target(value) + if not path and not anchor: + continue + resolve(path, anchor, lineno, "in '%s'" % tag[:60]) + for match in HTML_SRCSET_ATTR.finditer(tag): + value = match.group(1) or match.group(2) or match.group(3) or "" + for candidate in srcset_candidates(value): + path, anchor = split_target(candidate) + if not path and not anchor: + continue + resolve(path, anchor, lineno, "in srcset '%s'" % tag[:60]) + scan = HTML_TAG.sub("", line) # Never mistake markup for links. for match in INLINE_LINK.finditer(scan): path, anchor = split_target(match.group(3)) if not path and not anchor: @@ -176,29 +249,42 @@ def resolve(path, anchor, lineno, note): label = match.group(3) or match.group(2) key = " ".join(label.split()).lower() if key not in definitions: - # Ignore bare [brackets] with no matching definition. - if match.group(3) == "" and match.group(0).endswith("[]"): - errors.append("%s:%d: undefined reference '[%s]'" % (relpath, lineno, label)) - elif match.group(3) != "": - errors.append("%s:%d: undefined reference '[%s]'" % (relpath, lineno, label)) + # Single [brackets] never match this pattern, so anything here + # is a real [text][label] or [label][] reference: undefined. + errors.append("%s:%d: undefined reference '[%s]'" % (relpath, lineno, label)) continue path, anchor = split_target(definitions[key]) if not path and not anchor: continue resolve(path, anchor, lineno, "for reference '[%s]'" % label) - for match in AUTOLINK.finditer(scan): - raw = match.group(1) - if SCHEME.match(raw): - continue # Remote or special schemes are never fetched. - path, anchor = split_target(raw) - if not path and not anchor: - continue - resolve(path, anchor, lineno, "in autolink") + # No autolink branch: CommonMark only autolinks absolute URIs (skipped + # above when they carry a scheme) and email addresses, so bare + # and are plain text, not files. return errors +def tracked_markdown(repo): + """List tracked Markdown files via git, failing closed when unavailable.""" + proc = subprocess.run( + ["git", "ls-files", "-z", "*.md"], + cwd=repo, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + check=False, + ) + if proc.returncode != 0: + raise RuntimeError( + "git ls-files failed: %s" % proc.stderr.decode("utf-8", "replace").strip() + ) + try: + return [token.decode("utf-8", "strict") for token in proc.stdout.split(b"\0") if token] + except UnicodeDecodeError as exc: + raise RuntimeError("undecodable tracked filename: %s" % exc) + + def main(argv): files_json = None + all_tracked = False repo = os.getcwd() index = 0 while index < len(argv): @@ -206,24 +292,37 @@ def main(argv): if arg == "--files-json" and index + 1 < len(argv): files_json = argv[index + 1] index += 2 + elif arg == "--all": + all_tracked = True + index += 1 elif arg == "--repo" and index + 1 < len(argv): repo = argv[index + 1] index += 2 else: print("error: unknown argument: %s" % arg, file=sys.stderr) return 2 - if files_json is None: - print("error: need --files-json", file=sys.stderr) - return 2 - try: - files = json.loads(files_json) - except ValueError as exc: - print("error: invalid --files-json: %s" % exc, file=sys.stderr) + if all_tracked and files_json is not None: + print("error: --all and --files-json are mutually exclusive", file=sys.stderr) return 2 - if not isinstance(files, list): - print("error: --files-json must be a list", file=sys.stderr) + if not all_tracked and files_json is None: + print("error: need --all or --files-json", file=sys.stderr) return 2 repo = os.path.realpath(repo) + if all_tracked: + try: + files = tracked_markdown(repo) + except RuntimeError as exc: + print("error: %s" % exc, file=sys.stderr) + return 1 + else: + try: + files = json.loads(files_json) + except ValueError as exc: + print("error: invalid --files-json: %s" % exc, file=sys.stderr) + return 2 + if not isinstance(files, list): + print("error: --files-json must be a list", file=sys.stderr) + return 2 cache = {} errors = [] for relpath in sorted(set(files)): @@ -237,7 +336,7 @@ def main(argv): continue # Deleted or renamed-away files have no links to check. try: with open(full, "r", encoding="utf-8") as handle: - cache[relpath] = document_anchors(handle.read().splitlines()) + cache[relpath] = document_anchors(strip_fences(handle.read().splitlines())) except (OSError, UnicodeDecodeError) as exc: errors.append("%s: cannot read file: %s" % (relpath, exc)) continue diff --git a/scripts/ci-docs-fastpath.test.mjs b/scripts/ci-docs-fastpath.test.mjs index 77cd096..b480afe 100644 --- a/scripts/ci-docs-fastpath.test.mjs +++ b/scripts/ci-docs-fastpath.test.mjs @@ -152,6 +152,17 @@ const checkFiles = (repo, files) => { } } +const checkAll = (repo) => { + try { + const out = execFileSync('python3', [check, '--all', '--repo', repo], { + encoding: 'utf8' + }) + return { ok: true, out } + } catch (error) { + return { ok: false, out: `${error.stdout ?? ''}\n${error.stderr ?? ''}` } + } +} + test('docs checker validates links and anchors without network', { timeout: 60_000 }, () => { const repo = mkdtempSync(join(tmpdir(), 'october-docscheck-test-')) try { @@ -192,3 +203,111 @@ test('docs checker validates links and anchors without network', { timeout: 60_0 rmSync(repo, { recursive: true, force: true }) } }) + +test('docs checker follows HTML links and own-repo blob URLs', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docshtml-test-')) + try { + mkdirSync(join(repo, 'docs'), { recursive: true }) + mkdirSync(join(repo, 'assets'), { recursive: true }) + writeFileSync(join(repo, 'docs', 'target.md'), '# Getting Started\n') + writeFileSync(join(repo, 'assets', 'logo.svg'), '\n') + const blob = 'https://github.com/october-dev/agentintercom/blob/main/docs/target.md' + writeFileSync( + join(repo, 'README.md'), + '# Title\n\n' + + 'nav rel\n\n' + + 'logo\n\n' + + '\n\n' + + `[page](${blob}) and [frag](${blob}#getting-started).\n\n` + + 'Pinned [old](https://github.com/october-dev/october-bus/blob/7fc501ac58a1e1cda8195a70ba02f2e9a9ba8ad1/spec/0.1/mcp.md#L44) skipped.\n\n' + + 'Foreign [x](https://github.com/other/repo/blob/main/x.md) skipped.\n' + ) + const good = checkFiles(repo, ['README.md']) + assert.equal(good.ok, true, good.out) + + writeFileSync( + join(repo, 'BROKEN.md'), + '# Broken\n\n' + + 'nav\n\n' + + '\n\n' + + '\n\n' + + '[gone](https://github.com/october-dev/agentintercom/blob/main/docs/gone.md)\n\n' + + `[badfrag](${blob}#no-such-anchor)\n` + ) + const bad = checkFiles(repo, ['BROKEN.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /BROKEN\.md:\d+: unknown anchor '#missing'/) + assert.match(bad.out, /BROKEN\.md:\d+: missing link target: assets\/gone\.svg/) + assert.match(bad.out, /BROKEN\.md:\d+: missing link target: assets\/gone2\.svg/) + assert.match(bad.out, /BROKEN\.md:\d+: missing link target: docs\/gone\.md/) + assert.match(bad.out, /BROKEN\.md:\d+: unknown anchor '#no-such-anchor' in docs\/target\.md/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +test('docs checker ignores autolink-like text and slugs headings like GitHub', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docsslug-test-')) + try { + writeFileSync( + join(repo, 'NOTE.md'), + '# A & B\n\n' + + 'Contact or edit and .\n\n' + + 'Ampersand [ok](#a--b) works.\n\n' + + '```md\n# fenced-heading\n```\n' + ) + const good = checkFiles(repo, ['NOTE.md']) + assert.equal(good.ok, true, good.out) + + writeFileSync( + join(repo, 'SLUG-BAD.md'), + '# A & B\n\n' + + 'Single [hyphen](#a-b) does not exist on GitHub.\n\n' + + '```md\n# fenced-heading\n```\n\n' + + 'Fenced [ghost](#fenced-heading) is not a heading.\n' + ) + const bad = checkFiles(repo, ['SLUG-BAD.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /SLUG-BAD\.md:\d+: unknown anchor '#a-b'/) + assert.match(bad.out, /SLUG-BAD\.md:\d+: unknown anchor '#fenced-heading'/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +test('docs checker --all validates every tracked Markdown file', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docsall-test-')) + try { + const git = (args) => execFileSync('git', args, { cwd: repo, encoding: 'utf8' }) + git(['init', '-q']) + git(['config', 'user.email', 'test@example.invalid']) + git(['config', 'user.name', 'Docs check test']) + git(['config', 'commit.gpgsign', 'false']) + writeFileSync(join(repo, 'README.md'), '# Hi\n\n[ok](#hi)\n') + mkdirSync(join(repo, 'docs'), { recursive: true }) + writeFileSync(join(repo, 'docs', 'other.md'), '# Other\n\n[back](../README.md#hi)\n') + git(['add', '.']) + git(['commit', '-qm', 'base']) + const good = checkAll(repo) + assert.equal(good.ok, true, good.out) + assert.match(good.out, /docs link check passed \(2 file\(s\)\)/) + + // A broken inbound link in any tracked file fails the whole check ... + writeFileSync(join(repo, 'docs', 'other.md'), '# Other\n\n[back](../README.md#renamed-away)\n') + git(['commit', '-qam', 'break']) + const bad = checkAll(repo) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /other\.md:\d+: unknown anchor '#renamed-away' in \.\.\/README\.md/) + + // ... while untracked scratch files are invisible to --all. + writeFileSync(join(repo, 'SCRATCH.md'), '# Scratch\n\n[nope](#nope)\n') + const bad2 = checkAll(repo) + assert.equal(bad2.ok, false, bad2.out) + assert.doesNotMatch(bad2.out, /SCRATCH/) + + // Conflicting inputs are a usage error, not a silent default. + assert.throws(() => execFileSync('python3', [check, '--all', '--files-json', '[]'], { cwd: root }), /Command failed/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) From 43e1bda7e716671a685d8d8bb180c3d7abb615ad Mon Sep 17 00:00:00 2001 From: Harsh Date: Fri, 13 Nov 2026 05:47:24 -0800 Subject: [PATCH 3/4] Fix docs checker per round-2 audit: root-anchored URLs, parser hardening - Resolve own-repo blob/tree/raw URLs from the repo root ('/' prefix) - Slugs from rendered heading text (emphasis/link/image/HTML stripped) - Setext headings, github-slugger duplicate suffixes, exact-run code spans - Longer fences, indented code blocks, and HTML comments never checked - Backslash escapes, ?query strip, %XX decode, protocol-relative skip - Drop unused docs_files classifier output; gate message points at classify - CONTRIBUTING: validation runs on every PR + local command --- .github/workflows/ci.yml | 8 +- CONTRIBUTING.md | 2 +- scripts/ci-docs-check.py | 211 ++++++++++++++++++++++++------ scripts/ci-docs-classify.py | 53 ++++---- scripts/ci-docs-fastpath.test.mjs | 134 ++++++++++++++++--- 5 files changed, 317 insertions(+), 91 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1c2c013..b2b211a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,7 +59,7 @@ jobs: - name: Fail closed when docs classification did not succeed if: ${{ needs.classify.result != 'success' }} run: | - echo "docs classification did not succeed; failing closed." + echo "Docs fast-path classify job did not succeed (see the classify job log); failing closed." exit 1 - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 if: needs.classify.outputs.docs_only != 'true' @@ -129,7 +129,7 @@ jobs: - name: Fail closed when docs classification did not succeed if: ${{ needs.classify.result != 'success' }} run: | - echo "docs classification did not succeed; failing closed." + echo "Docs fast-path classify job did not succeed (see the classify job log); failing closed." exit 1 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 if: needs.classify.outputs.docs_only != 'true' @@ -181,7 +181,7 @@ jobs: - name: Fail closed when docs classification did not succeed if: ${{ needs.classify.result != 'success' }} run: | - echo "docs classification did not succeed; failing closed." + echo "Docs fast-path classify job did not succeed (see the classify job log); failing closed." exit 1 - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 if: needs.classify.outputs.docs_only != 'true' @@ -274,7 +274,7 @@ jobs: - name: Fail closed when docs classification did not succeed if: ${{ needs.classify.result != 'success' }} run: | - echo "docs classification did not succeed; failing closed." + echo "Docs fast-path classify job did not succeed (see the classify job log); failing closed." exit 1 - uses: golang/govulncheck-action@032d45514ae346b1db93c04b0c90b841c370344f # v1 if: needs.classify.outputs.docs_only != 'true' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9e004f..2073335 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,7 +59,7 @@ New adapters should keep registration, heartbeat, credential handling, and clean - Protocol, runtime, dependency, security, and workflow changes require code-owner review. - Resolve review conversations and request a new review after material changes. - Never merge with a failed, skipped, or incomplete required check. -- Pull requests that touch only the prose allowlist (`README.md`, root contributor docs, `docs/releases.md`, `docs/release-notes-*.md`) take a fast path: documentation links/anchors across all tracked Markdown are validated once, and every required check still runs, gating on that result instead of the runtime matrix. Any other change, or any classifier doubt, runs the full checks. +- Pull requests that touch only the prose allowlist (`README.md`, root contributor docs, `docs/releases.md`, `docs/release-notes-*.md`) take a fast path: documentation links/anchors across all tracked Markdown are validated once, and every required check still runs, gating on that result instead of the runtime matrix. Any other change, or any classifier doubt, runs the full checks. Link validation runs on every pull request, including code and mixed ones; run it locally with `python3 scripts/ci-docs-check.py --all`. - Changes to a pinned dependency must update the public pin record in the same pull request. - Release tags are created only from reviewed commits with passing checks. diff --git a/scripts/ci-docs-check.py b/scripts/ci-docs-check.py index 500f90a..8edc50c 100644 --- a/scripts/ci-docs-check.py +++ b/scripts/ci-docs-check.py @@ -9,9 +9,16 @@ same way. Anything else with a URI scheme is skipped (never fetched). Kept dependency-free on purpose: the check must run on a pristine runner -with only CPython and git, stay fully offline, and match GitHub's heading -slugs exactly, without a version-pinned third-party install. Covered by -``scripts/ci-docs-fastpath.test.mjs``. +with only CPython and git, stay fully offline, and approximate GitHub's +heading slugs closely, without a version-pinned third-party install. +Covered by ``scripts/ci-docs-fastpath.test.mjs``. + +Deliberate policy (reported, not skipped): links that escape the +repository (``../../issues``), anchors with no matching heading +(including ``#top``), and ``[text][label]`` uses with no matching +definition. Fenced blocks, indented code, HTML comments, and code spans +are never link-checked; uncertain cases stay lenient (hidden) rather +than failing valid documents. Usage:: @@ -27,12 +34,15 @@ import re import subprocess import sys +from urllib.parse import unquote INLINE_LINK = re.compile(r"(!?)\[([^\]]*)\]\(([^)]*)\)") REFERENCE_USE = re.compile(r"(!?)\[([^\]]+)\]\[([^\]]*)\]") REFERENCE_DEF = re.compile(r"^[ ]{0,3}\[([^\]]+)\]:[ \t]*(\S+)[ \t]*(\"([^\"]*)\"|'([^']*)'|\(([^)]*)\))?[ \t]*$") HEADING = re.compile(r"^(#{1,6})\s+(.+?)[ \t]*#*[ \t]*$") -FENCED = re.compile(r"^(```|~~~)") +SETEXT = re.compile(r"^(=+|-+)[ \t]*$") +FENCED = re.compile(r"^(```+|~~~+)") +ESCAPED_PUNCT = re.compile(r"\\([!\"#$%&'()*+,\-./:;<=>?@\[\\\]^_`{|}~])") SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:") HTML_ANCHOR = re.compile(r']*?(?:id|name)\s*=\s*["\']([^"\']+)["\']', re.IGNORECASE) HTML_TAG = re.compile(r"]*)?/?>") @@ -59,19 +69,39 @@ def github_slug(heading): - """GitHub heading slug: lowercase, punctuation stripped, each space a hyphen.""" - text = re.sub(r"`([^`]*)`", r"\1", heading).strip().lower() + """GitHub-style heading slug from the heading's rendered text. + + Inline formatting is removed the way GitHub's renderer consumes it + before the slug rules (lowercase, punctuation stripped, each space a + hyphen): code spans keep their content, links keep their text, images + and HTML tags contribute nothing, and emphasis delimiters are dropped + while intra-word underscores survive. An approximation for exotic + nesting; covered by regression tests for the common forms. + """ + text = re.sub(r"`+([^`]*)`+", r"\1", heading) # code spans + text = re.sub(r"!\[([^\]]*)\]\([^)]*\)", "", text) # images: no text + text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text) # inline links + text = re.sub(r"\[([^\]]+)\]\[[^\]]*\]", r"\1", text) # reference links + text = re.sub(r"<([^<>@]*@[^<>]*)>", r"\1", text) # email autolinks + text = re.sub(r"]*>", "", text) # remaining HTML tags + text = re.sub(r"(?", "-", "*", "+", "`", "~")) + or re.match(r"\d+[.)]\s", stripped) + or REFERENCE_DEF.match(line) + ): + prev = None # blank, block markup, list item, or definition + else: + prev = stripped return anchors def blank_spans(text): """Blank CommonMark-style code spans, which may cross line breaks. - A run of N backticks is closed by the next run of exactly N backticks. - An unmatched run is literal text. Wrongly pairing two literal backticks - only hides text from validation (lenient), never flags valid docs. + A run of N backticks is closed by the next run of exactly N backticks; + longer or shorter runs are span content. An unmatched run is literal + text. Wrongly pairing two literal backticks only hides text from + validation (lenient), never flags valid docs. """ out = list(text) + total = len(text) index = 0 - while index < len(text): + while index < total: if text[index] != "`": index += 1 continue end = index - while end < len(text) and text[end] == "`": + while end < total and text[end] == "`": end += 1 - run = text[index:end] - close = text.find(run, end) - if close == -1: + run_len = end - index + pos = end + closed = -1 + while pos < total: + found = text.find("`", pos) + if found == -1: + break + found_end = found + while found_end < total and text[found_end] == "`": + found_end += 1 + if found_end - found == run_len: + closed = found + break + pos = found_end + if closed == -1: index = end continue - for pos in range(index, close + len(run)): + for blank_pos in range(index, closed + run_len): + if out[blank_pos] != "\n": + out[blank_pos] = " " + index = closed + run_len + return "".join(out) + + +def blank_comments(text): + """Blank HTML comments, which may span lines; unclosed runs to the end.""" + out = list(text) + index = 0 + while True: + start = text.find("", start) + end = len(text) if end == -1 else end + 3 + for pos in range(start, end): if out[pos] != "\n": out[pos] = " " - index = close + len(run) + index = end return "".join(out) def strip_fences(lines): - """Blank fenced code blocks; inline code spans are left intact.""" + """Blank fenced and indented code blocks; code spans are left intact. + + A fence closes only on the same marker character with at least as many + backticks/tildes and nothing else on the line, so a longer fence can + hold a shorter example. Four-space-indented lines are code when they + start a block (previous line blank) or continue one; indented lines + directly under list or paragraph content stay visible so their links + are still checked. + """ out = [] - fence = None + fence = None # (marker char, opening run length) + prev_blank = True + indent_code = False for line in lines: - match = FENCED.match(line.lstrip()) - if match: - marker = match.group(1) - if fence is None: - fence = marker - elif fence == marker: - fence = None + stripped = line.lstrip() + if not stripped: + out.append("" if fence else line) + prev_blank = True + continue + indented = line.startswith(" ") or line.startswith("\t") + if fence is None and indented and (prev_blank or indent_code): out.append("") + indent_code = True + prev_blank = False continue - out.append("" if fence else line) + indent_code = False + match = FENCED.match(stripped) + if match and fence is None: + info = stripped[match.end():] + if match.group(1)[0] == "`" and "`" in info: + out.append(line) # info string with backtick: not a fence + else: + fence = (match.group(1)[0], len(match.group(1))) + out.append("") + elif ( + match + and fence is not None + and match.group(1)[0] == fence[0] + and len(match.group(1)) >= fence[1] + and stripped[match.end():].strip() == "" + ): + fence = None + out.append("") + prev_blank = True # a fence boundary starts a fresh block + continue + else: + out.append("" if fence else line) + prev_blank = False return out def strip_code(lines): - """Blank fenced blocks and code spans so they are never link-checked.""" - return blank_spans("\n".join(strip_fences(lines))).split("\n") + """Blank code blocks, HTML comments, and code spans: never link-checked.""" + return blank_spans(blank_comments("\n".join(strip_fences(lines)))).split("\n") def split_target(raw): @@ -190,12 +316,15 @@ def resolve(path, anchor, lineno, note): path = rewrite_own_repo_url(path) if anchor and LINE_ANCHOR.match(anchor): anchor = "" # Pinned line links (#L10) have no heading slug. + if SCHEME.match(path) or path.startswith("//"): + return # Remote, protocol-relative, or special URLs: never fetched. + # Relative links may carry a query (?raw=1) or percent-escapes + # (my%20file.md); both are resolved the way GitHub serves them. + path = unquote(path.split("?", 1)[0]) if not path: if anchor and anchor not in cache[relpath]: errors.append("%s:%d: unknown anchor '#%s' %s" % (relpath, lineno, anchor, note)) return - if SCHEME.match(path): - return # Remote or special schemes are never fetched. if path.startswith("/"): target = os.path.normpath(os.path.join(repo, path.lstrip("/"))) else: @@ -239,7 +368,9 @@ def resolve(path, anchor, lineno, note): if not path and not anchor: continue resolve(path, anchor, lineno, "in srcset '%s'" % tag[:60]) - scan = HTML_TAG.sub("", line) # Never mistake markup for links. + # Never mistake markup for links; backslash-escaped punctuation is + # literal text, so `\[x\](y)` is not a link. + scan = ESCAPED_PUNCT.sub(" ", HTML_TAG.sub("", line)) for match in INLINE_LINK.finditer(scan): path, anchor = split_target(match.group(3)) if not path and not anchor: diff --git a/scripts/ci-docs-classify.py b/scripts/ci-docs-classify.py index 0ea3cc2..d053208 100644 --- a/scripts/ci-docs-classify.py +++ b/scripts/ci-docs-classify.py @@ -22,11 +22,12 @@ python3 scripts/ci-docs-classify.py --base --head -writes ``docs_only``, ``docs_files`` (JSON list of changed ``.md`` files -present at head, for the link checker) and ``reason`` to ``$GITHUB_OUTPUT`` -and prints them to stdout. ``--entries-json`` accepts canned diff entries -for the self-test (see ``scripts/ci-docs-fastpath.test.mjs``) instead of -running git. +writes ``docs_only`` and ``reason`` to ``$GITHUB_OUTPUT`` and prints them +to stdout. (Link validation runs separately over all tracked Markdown via +``ci-docs-check.py --all``; the classifier only decides fast path versus +full checks.) ``--entries-json`` accepts canned diff entries for the +self-test (see ``scripts/ci-docs-fastpath.test.mjs``) instead of running +git. """ import json @@ -70,41 +71,36 @@ def is_allowlisted(path): def classify_entries(entries): """Classify canned ``(status, [paths])`` diff entries. - Returns ``(docs_only, reason, docs_files)``. Every unknown input fails - closed to ``docs_only=False``. + Returns ``(docs_only, reason)``. Every unknown input fails closed to + ``docs_only=False``. """ if not entries: - return False, "empty changeset runs full checks", [] - docs_files = [] + return False, "empty changeset runs full checks" for entry in entries: if not isinstance(entry, (list, tuple)) or len(entry) != 2: - return False, "unparseable diff entry runs full checks", [] + return False, "unparseable diff entry runs full checks" status, paths = entry if not isinstance(status, str) or not status: - return False, "unparseable diff status runs full checks", [] + return False, "unparseable diff status runs full checks" if not isinstance(paths, list) or not paths: - return False, "unparseable diff paths run full checks", [] + return False, "unparseable diff paths run full checks" kind = status[0] if kind in ("A", "M", "D"): if len(paths) != 1: - return False, "malformed diff entry runs full checks", [] + return False, "malformed diff entry runs full checks" if not is_allowlisted(paths[0]): - return False, "non-docs change runs full checks: %s" % paths[0], [] - if kind in ("A", "M") and paths[0] not in docs_files: - docs_files.append(paths[0]) + return False, "non-docs change runs full checks: %s" % paths[0] elif kind == "R": # Both sides of a rename must stay inside the allowlist. if len(paths) != 2: - return False, "malformed rename runs full checks", [] + return False, "malformed rename runs full checks" old, new = paths if not is_allowlisted(old) or not is_allowlisted(new): - return False, "rename crossing docs boundary runs full checks", [] - if new not in docs_files: - docs_files.append(new) + return False, "rename crossing docs boundary runs full checks" else: # Type changes, copies, unmerged, unknown, or anything else. - return False, "unrecognized change runs full checks: %s" % status, [] - return True, "all changes are allowlisted prose docs", sorted(docs_files) + return False, "unrecognized change runs full checks: %s" % status + return True, "all changes are allowlisted prose docs" def git_name_status(repo, base, head): @@ -142,18 +138,15 @@ def git_name_status(repo, base, head): return entries -def write_output(docs_only, reason, docs_files): +def write_output(docs_only, reason): line = "docs_only=%s" % ("true" if docs_only else "false") - files = "docs_files=%s" % json.dumps(sorted(docs_files)) clean_reason = " ".join(reason.split()) print(line) - print(files) print("reason=%s" % clean_reason) output_path = os.environ.get("GITHUB_OUTPUT") if output_path: with open(output_path, "a", encoding="utf-8") as handle: handle.write(line + "\n") - handle.write(files + "\n") handle.write("reason=%s\n" % clean_reason) @@ -185,7 +178,7 @@ def main(argv): entries = json.loads(entries_json) if not isinstance(entries, list): raise ValueError("entries JSON must be a list") - docs_only, reason, docs_files = classify_entries( + docs_only, reason = classify_entries( [(status, paths) for status, paths in entries] ) elif base and head: @@ -194,16 +187,16 @@ def main(argv): except Exception as exc: # A diff we cannot compute is not a docs-only diff: run # everything rather than failing the whole workflow open. - write_output(False, "diff unavailable runs full checks: %s" % exc, []) + write_output(False, "diff unavailable runs full checks: %s" % exc) return 0 - docs_only, reason, docs_files = classify_entries(entries) + docs_only, reason = classify_entries(entries) else: print("error: need --base/--head or --entries-json", file=sys.stderr) return 2 except Exception as exc: # noqa: BLE001 - fail closed with a loud error. print("error: classifier failed closed: %s" % exc, file=sys.stderr) return 1 - write_output(docs_only, reason, docs_files) + write_output(docs_only, reason) return 0 diff --git a/scripts/ci-docs-fastpath.test.mjs b/scripts/ci-docs-fastpath.test.mjs index b480afe..36f32e6 100644 --- a/scripts/ci-docs-fastpath.test.mjs +++ b/scripts/ci-docs-fastpath.test.mjs @@ -16,8 +16,7 @@ const classifyEntries = (entries) => { encoding: 'utf8' }) const docsOnly = /^docs_only=(true|false)$/m.exec(out)?.[1] === 'true' - const docsFiles = JSON.parse(/^docs_files=(.+)$/m.exec(out)?.[1] ?? 'null') - return { docsOnly, docsFiles, out } + return { docsOnly, out } } test('classifier fast-paths only the prose allowlist', () => { @@ -33,16 +32,6 @@ test('classifier fast-paths only the prose allowlist', () => { ['A', ['docs/release-notes-9.9.9.md']] ]) assert.equal(all.docsOnly, true) - assert.deepEqual(all.docsFiles, [ - 'CHANGELOG.md', - 'CODE_OF_CONDUCT.md', - 'CONTRIBUTING.md', - 'README.md', - 'ROADMAP.md', - 'SECURITY.md', - 'docs/release-notes-9.9.9.md', - 'docs/releases.md' - ]) }) test('classifier fails closed on code, mixed, and sensitive paths', () => { @@ -124,7 +113,6 @@ test('classifier resolves --base/--head diffs end to end in git', { timeout: 60_ env: { ...process.env, ...env } }) assert.match(run(docsOnly), /^docs_only=true$/m) - assert.match(run(docsOnly), /"README\.md"/) assert.match(run(code), /^docs_only=false$/m) // Unknown revisions fail closed to full checks without failing the job. assert.match(run('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef'), /^docs_only=false$/m) @@ -134,7 +122,6 @@ test('classifier resolves --base/--head diffs end to end in git', { timeout: 60_ run(docsOnly, { GITHUB_OUTPUT: outputFile }) const written = readFileSync(outputFile, 'utf8') assert.match(written, /^docs_only=true$/m) - assert.match(written, /^docs_files=\[/m) assert.match(written, /^reason=.+$/m) } finally { rmSync(repo, { recursive: true, force: true }) @@ -239,8 +226,8 @@ test('docs checker follows HTML links and own-repo blob URLs', { timeout: 60_000 assert.match(bad.out, /BROKEN\.md:\d+: unknown anchor '#missing'/) assert.match(bad.out, /BROKEN\.md:\d+: missing link target: assets\/gone\.svg/) assert.match(bad.out, /BROKEN\.md:\d+: missing link target: assets\/gone2\.svg/) - assert.match(bad.out, /BROKEN\.md:\d+: missing link target: docs\/gone\.md/) - assert.match(bad.out, /BROKEN\.md:\d+: unknown anchor '#no-such-anchor' in docs\/target\.md/) + assert.match(bad.out, /BROKEN\.md:\d+: missing link target: \/docs\/gone\.md/) + assert.match(bad.out, /BROKEN\.md:\d+: unknown anchor '#no-such-anchor' in \/docs\/target\.md/) } finally { rmSync(repo, { recursive: true, force: true }) } @@ -311,3 +298,118 @@ test('docs checker --all validates every tracked Markdown file', { timeout: 60_0 rmSync(repo, { recursive: true, force: true }) } }) + +test('docs checker resolves own-repo URLs from the repository root', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docsroot-test-')) + try { + mkdirSync(join(repo, 'docs'), { recursive: true }) + mkdirSync(join(repo, 'assets'), { recursive: true }) + writeFileSync(join(repo, 'docs', 'target.md'), '# Getting Started\n') + writeFileSync(join(repo, 'assets', 'logo.svg'), '\n') + writeFileSync( + join(repo, 'docs', 'page.md'), + '# Page\n\n' + + '[nested blob](https://github.com/october-dev/agentintercom/blob/main/docs/target.md) ' + + '[frag](https://github.com/october-dev/agentintercom/blob/main/docs/target.md#getting-started) ' + + '![raw](https://raw.githubusercontent.com/october-dev/agentintercom/main/assets/logo.svg)\n' + ) + const good = checkFiles(repo, ['docs/page.md']) + assert.equal(good.ok, true, good.out) + + // A root target that does not exist must fail even when a same-named + // file sits beside the linking document (resolving from docs/ would + // wrongly pass). + writeFileSync( + join(repo, 'docs', 'nasty.md'), + '# Nasty\n\n[wrong dir](https://github.com/october-dev/agentintercom/blob/main/target.md)\n' + ) + const bad = checkFiles(repo, ['docs/nasty.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /nasty\.md:\d+: missing link target: \/target\.md/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +test('docs checker slugs formatted, setext, and duplicate headings like GitHub', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docshead-test-')) + try { + writeFileSync(join(repo, 'guide.md'), '# Guide\n') + writeFileSync( + join(repo, 'HEADS.md'), + '# _Quickstart_\n\n[emphasis](#quickstart) and [ident](#agent_id-keeps-underscores).\n\n' + + '# agent_id keeps underscores\n\n' + + '# See the [Guide](guide.md)\n\n[linked](#see-the-guide).\n\n' + + 'Big Title\n=========\n\n[setext h1](#big-title).\n\n' + + 'Small Title\n-----------\n\n[setext h2](#small-title).\n\n' + + '# Setup\n\n# Setup\n\n# Setup-1\n\n[dup](#setup-1-1).\n' + ) + const good = checkFiles(repo, ['HEADS.md']) + assert.equal(good.ok, true, good.out) + + writeFileSync(join(repo, 'DUP-BAD.md'), '# Setup\n\n# Setup\n\n# Setup-1\n\n[nope](#setup-1-2).\n') + const bad = checkFiles(repo, ['DUP-BAD.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /DUP-BAD\.md:\d+: unknown anchor '#setup-1-2'/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +test('docs checker ignores longer fences, indented code, and HTML comments', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docscode-test-')) + try { + writeFileSync( + join(repo, 'CODE.md'), + '# Code\n\n````md\nExample fence:\n\n```md\n[example](missing.md)\n```\n````\n\n' + + 'Paragraph.\n\n [indented](missing.md)\n\n' + + '\n\n\n' + ) + const good = checkFiles(repo, ['CODE.md']) + assert.equal(good.ok, true, good.out) + + // A real broken link after a long fence still fails, as does an + // indented link that belongs to list content rather than a code block. + writeFileSync( + join(repo, 'CODE-BAD.md'), + '# Bad\n\n````\n```\n[example](missing.md)\n```\n````\n\n[broken](missing.md)\n' + ) + const bad = checkFiles(repo, ['CODE-BAD.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /CODE-BAD\.md:\d+: missing link target: missing\.md/) + writeFileSync(join(repo, 'LIST.md'), '# List\n\n- item\n [broken](missing.md)\n') + const listed = checkFiles(repo, ['LIST.md']) + assert.equal(listed.ok, false, listed.out) + assert.match(listed.out, /LIST\.md:\d+: missing link target: missing\.md/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + +test('docs checker handles escapes, queries, spans, and remote URLs', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docsedge-test-')) + try { + writeFileSync(join(repo, 'target.md'), '# Target\n') + writeFileSync(join(repo, 'my file.md'), '# Spaced\n') + writeFileSync( + join(repo, 'EDGE.md'), + '# Edge\n\n' + + '`a ``` [example](missing.md)` is one span.\n\n' + + 'Not a link: \\[example\\](missing.md).\n\n' + + '[spaced](my%20file.md) and [query](target.md?plain=1).\n\n' + + '[proto-relative](//cdn.example.invalid/y.md) is remote.\n' + ) + const good = checkFiles(repo, ['EDGE.md']) + assert.equal(good.ok, true, good.out) + + // Queries and escapes decode before the existence check, so genuinely + // missing decoded targets still fail. + writeFileSync(join(repo, 'EDGE-BAD.md'), '# Bad\n\n[q](gone.md?x=1) [s](other%20gone.md)\n') + const bad = checkFiles(repo, ['EDGE-BAD.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /EDGE-BAD\.md:\d+: missing link target: gone\.md/) + assert.match(bad.out, /EDGE-BAD\.md:\d+: missing link target: other gone\.md/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) From 3c2772fa4fb1cb4e45df9cd80a54ba499cc30226 Mon Sep 17 00:00:00 2001 From: Harsh Date: Fri, 13 Nov 2026 08:23:36 -0800 Subject: [PATCH 4/4] Fix docs checker per round-3 audit: literal code spans, formatted setext Code spans are stashed before markup substitution so underscores inside them survive the emphasis strip (`_meta` keeps its slug); bullet markers only count as list items with following whitespace so *Quickstart* and code-span-led lines stay setext candidates. Adds the five positive and two wrong-anchor regressions (14 tests). --all still passes (93 files). --- scripts/ci-docs-check.py | 22 +++++++++++++++++++--- scripts/ci-docs-fastpath.test.mjs | 30 ++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/scripts/ci-docs-check.py b/scripts/ci-docs-check.py index 8edc50c..1cfb716 100644 --- a/scripts/ci-docs-check.py +++ b/scripts/ci-docs-check.py @@ -78,13 +78,24 @@ def github_slug(heading): while intra-word underscores survive. An approximation for exotic nesting; covered by regression tests for the common forms. """ - text = re.sub(r"`+([^`]*)`+", r"\1", heading) # code spans + spans = [] + + def stash(match): + spans.append(match.group(1)) + return "\0span%d\0" % (len(spans) - 1) + + # Code spans are stashed before the markup substitutions: their + # contents are literal, so underscores inside them (`` `_meta` ``) + # must not be treated as emphasis delimiters below. + text = re.sub(r"`+([^`]*)`+", stash, heading) text = re.sub(r"!\[([^\]]*)\]\([^)]*\)", "", text) # images: no text text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text) # inline links text = re.sub(r"\[([^\]]+)\]\[[^\]]*\]", r"\1", text) # reference links text = re.sub(r"<([^<>@]*@[^<>]*)>", r"\1", text) # email autolinks text = re.sub(r"]*>", "", text) # remaining HTML tags text = re.sub(r"(?", "-", "*", "+", "`", "~")) + or stripped.startswith(("#", ">")) + or re.match(r"[-*+](\s|$)", stripped) or re.match(r"\d+[.)]\s", stripped) or REFERENCE_DEF.match(line) ): - prev = None # blank, block markup, list item, or definition + # Blank, block markup, list item, or definition. Bullet and + # numbered markers only count as list items with the whitespace + # CommonMark requires, so *Quickstart* and `config` options stay + # setext candidates; fences never reach this function unblanked. + prev = None else: prev = stripped return anchors diff --git a/scripts/ci-docs-fastpath.test.mjs b/scripts/ci-docs-fastpath.test.mjs index 36f32e6..729cdee 100644 --- a/scripts/ci-docs-fastpath.test.mjs +++ b/scripts/ci-docs-fastpath.test.mjs @@ -356,6 +356,36 @@ test('docs checker slugs formatted, setext, and duplicate headings like GitHub', } }) +test('docs checker keeps code-span text literal and reads formatted setext subjects', { timeout: 60_000 }, () => { + const repo = mkdtempSync(join(tmpdir(), 'october-docsspan-test-')) + try { + writeFileSync( + join(repo, 'SPANS.md'), + '## The `_meta` field\n\n[meta](#the-_meta-field).\n\n' + + '## The `OCTOBER_BUS_*` variables\n\n[busvars](#the-october_bus_-variables).\n\n' + + '## The `__init__` method\n\n[init](#the-__init__-method).\n\n' + + '*Quickstart*\n===========\n\n[emphsetext](#quickstart).\n\n' + + '`config` options\n--------------\n\n[cfg](#config-options).\n' + ) + const good = checkFiles(repo, ['SPANS.md']) + assert.equal(good.ok, true, good.out) + + // Near-miss anchors against the same headings must still fail: the + // unprotected slug, and a duplicate suffix that was never generated. + writeFileSync( + join(repo, 'SPANS-BAD.md'), + '## The `_meta` field\n\n[nope](#the-meta-field).\n\n' + + '*Quickstart*\n===========\n\n[nope](#quickstart-1).\n' + ) + const bad = checkFiles(repo, ['SPANS-BAD.md']) + assert.equal(bad.ok, false, bad.out) + assert.match(bad.out, /SPANS-BAD\.md:\d+: unknown anchor '#the-meta-field'/) + assert.match(bad.out, /SPANS-BAD\.md:\d+: unknown anchor '#quickstart-1'/) + } finally { + rmSync(repo, { recursive: true, force: true }) + } +}) + test('docs checker ignores longer fences, indented code, and HTML comments', { timeout: 60_000 }, () => { const repo = mkdtempSync(join(tmpdir(), 'october-docscode-test-')) try {