|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# Copyright 2026 Google LLC |
| 3 | +# |
| 4 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +# you may not use this file except in compliance with the License. |
| 6 | +# You may obtain a copy of the License at |
| 7 | +# |
| 8 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +# |
| 10 | +# Unless required by applicable law or agreed to in writing, software |
| 11 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +# See the License for the specific language governing permissions and |
| 14 | +# limitations under the License. |
| 15 | + |
| 16 | +"""Lint verifying relative links and OSS URL hygiene in repository Markdown docs. |
| 17 | +
|
| 18 | +Scans tracked `*.md` files outside `.agents/` (which `check_agent_doc_paths.py` |
| 19 | +checks separately) and fails when: |
| 20 | +- A relative Markdown link target does not exist in the git index or escapes the repo. |
| 21 | +- A non-code Markdown line contains a `file://` URI, `corp.google.com` host, or |
| 22 | + `http(s)://go/...` / `//go/...` corporate shortlink. |
| 23 | +""" |
| 24 | + |
| 25 | +from __future__ import annotations |
| 26 | + |
| 27 | +import argparse |
| 28 | +import dataclasses |
| 29 | +import posixpath |
| 30 | +import re |
| 31 | +import sys |
| 32 | +from collections.abc import Iterator |
| 33 | +from pathlib import Path |
| 34 | +from typing import Any |
| 35 | +from urllib.parse import unquote |
| 36 | + |
| 37 | +_REPO_ROOT = Path(__file__).resolve().parents[2] |
| 38 | +if str(_REPO_ROOT) not in sys.path: |
| 39 | + sys.path.insert(0, str(_REPO_ROOT)) |
| 40 | + |
| 41 | +from tools.common.tool_utils import HandledError, run_tool # noqa: E402 |
| 42 | +from tools.lint.check_agent_doc_paths import ( # noqa: E402 |
| 43 | + INLINE_CODE_RE, |
| 44 | + closes_fence, |
| 45 | + list_tracked_files, |
| 46 | + opens_fence, |
| 47 | + tracked_paths, |
| 48 | +) |
| 49 | + |
| 50 | +_LINK_TAIL_RE = re.compile(r'^\s*(?:(?:"[^"]*"|\'[^\']*\')\s*)?\)') |
| 51 | +_REF_DEF_RE = re.compile(r"^\s{0,3}\[[^\]]+\]:\s*(<[^>]+>|[^\s]+)") |
| 52 | +_SCHEME_RE = re.compile(r"^[a-z][a-z0-9+.-]+:", re.IGNORECASE) |
| 53 | +_FORBIDDEN_URL_RE = re.compile( |
| 54 | + r"file://[^\s)>'\"]+|[A-Za-z0-9.-]*corp\.google\.com\b|(?:https?://|(?<![A-Za-z0-9:/])//)go/[A-Za-z0-9_./-]+", |
| 55 | + re.IGNORECASE, |
| 56 | +) |
| 57 | + |
| 58 | + |
| 59 | +@dataclasses.dataclass(frozen=True) |
| 60 | +class DocViolation: |
| 61 | + """A broken relative link or forbidden internal URL in a Markdown document.""" |
| 62 | + |
| 63 | + doc: str |
| 64 | + line: int |
| 65 | + kind: str |
| 66 | + target: str |
| 67 | + |
| 68 | + |
| 69 | +def is_checked_doc(path: str) -> bool: |
| 70 | + """Return whether a tracked path is a Markdown doc covered by this linter.""" |
| 71 | + return path.endswith(".md") and not path.startswith(".agents/") |
| 72 | + |
| 73 | + |
| 74 | +def iter_prose_lines(text: str) -> Iterator[tuple[int, str]]: |
| 75 | + """Yield (1-based line number, line without inline code) outside fenced blocks.""" |
| 76 | + opening = "" |
| 77 | + for lineno, line in enumerate(text.splitlines(), start=1): |
| 78 | + if opening: |
| 79 | + if closes_fence(line, opening): |
| 80 | + opening = "" |
| 81 | + continue |
| 82 | + opened = opens_fence(line) |
| 83 | + if opened: |
| 84 | + opening = opened |
| 85 | + continue |
| 86 | + yield lineno, INLINE_CODE_RE.sub("", line) |
| 87 | + |
| 88 | + |
| 89 | +def _parse_link_destination(prose: str, start: int) -> str | None: |
| 90 | + """Parse an inline Markdown link destination immediately following `](`.""" |
| 91 | + i = start |
| 92 | + while i < len(prose) and prose[i] in " \t": |
| 93 | + i += 1 |
| 94 | + if i < len(prose) and prose[i] == "<": |
| 95 | + end = prose.find(">", i + 1) |
| 96 | + if end == -1 or not _LINK_TAIL_RE.match(prose[end + 1 :]): |
| 97 | + return None |
| 98 | + return prose[i + 1 : end] |
| 99 | + depth = 0 |
| 100 | + j = i |
| 101 | + while j < len(prose): |
| 102 | + ch = prose[j] |
| 103 | + if ch in " \t": |
| 104 | + break |
| 105 | + if ch == "(": |
| 106 | + depth += 1 |
| 107 | + elif ch == ")": |
| 108 | + if depth == 0: |
| 109 | + return prose[i:j] if j > i else None |
| 110 | + depth -= 1 |
| 111 | + j += 1 |
| 112 | + if j > i and depth == 0 and _LINK_TAIL_RE.match(prose[j:]): |
| 113 | + return prose[i:j] |
| 114 | + return None |
| 115 | + |
| 116 | + |
| 117 | +def extract_link_targets(prose: str) -> list[str]: |
| 118 | + """Extract inline link, linked-image, and reference-definition targets from a line.""" |
| 119 | + targets: list[str] = [] |
| 120 | + pos = 0 |
| 121 | + while (idx := prose.find("](", pos)) != -1: |
| 122 | + dest = _parse_link_destination(prose, idx + 2) |
| 123 | + if dest is not None: |
| 124 | + targets.append(dest) |
| 125 | + pos = idx + 2 |
| 126 | + ref_match = _REF_DEF_RE.match(prose) |
| 127 | + if ref_match: |
| 128 | + targets.append(ref_match.group(1)) |
| 129 | + return targets |
| 130 | + |
| 131 | + |
| 132 | +def resolve_repo_target(doc: str, raw_target: str) -> tuple[str, str | None]: |
| 133 | + """Resolve a Markdown link target relative to doc. |
| 134 | +
|
| 135 | + Returns: |
| 136 | + Tuple of (resolved_repo_path, error_kind) where error_kind is None if |
| 137 | + the link is external, anchor-only, or resolves cleanly within the repo. |
| 138 | + """ |
| 139 | + stripped = raw_target.strip("<>") |
| 140 | + if not stripped or stripped.startswith("#"): |
| 141 | + return "", None |
| 142 | + if stripped.lower().startswith("file://"): |
| 143 | + return stripped.rstrip(".,;:"), "forbidden_url" |
| 144 | + if stripped.startswith("//") or _SCHEME_RE.match(stripped): |
| 145 | + return "", None |
| 146 | + path_part = unquote(stripped.split("#", 1)[0].split("?", 1)[0]) |
| 147 | + if not path_part: |
| 148 | + return "", None |
| 149 | + if path_part.startswith("/"): |
| 150 | + joined = posixpath.normpath(path_part.lstrip("/")) |
| 151 | + else: |
| 152 | + doc_dir = posixpath.dirname(doc) |
| 153 | + joined = posixpath.normpath(posixpath.join(doc_dir, path_part) if doc_dir else path_part) |
| 154 | + if joined == ".." or joined.startswith("../"): |
| 155 | + return joined, "escapes_repo" |
| 156 | + return ("" if joined == "." else joined), None |
| 157 | + |
| 158 | + |
| 159 | +def find_line_violations( |
| 160 | + doc: str, lineno: int, prose: str, existing: frozenset[str] |
| 161 | +) -> list[DocViolation]: |
| 162 | + """Collect broken-link and forbidden-URL violations from a single prose line.""" |
| 163 | + violations: list[DocViolation] = [] |
| 164 | + for raw_target in extract_link_targets(prose): |
| 165 | + resolved, err_kind = resolve_repo_target(doc, raw_target) |
| 166 | + if err_kind is not None: |
| 167 | + violations.append(DocViolation(doc=doc, line=lineno, kind=err_kind, target=resolved)) |
| 168 | + elif resolved and resolved not in existing: |
| 169 | + violations.append( |
| 170 | + DocViolation(doc=doc, line=lineno, kind="missing_target", target=resolved) |
| 171 | + ) |
| 172 | + for url_match in _FORBIDDEN_URL_RE.finditer(prose): |
| 173 | + url = url_match.group(0).rstrip(".,;:") |
| 174 | + if not any(v.target == url and v.line == lineno for v in violations): |
| 175 | + violations.append(DocViolation(doc=doc, line=lineno, kind="forbidden_url", target=url)) |
| 176 | + return violations |
| 177 | + |
| 178 | + |
| 179 | +def scan_docs(repo_root: Path, docs: list[str], existing: frozenset[str]) -> list[DocViolation]: |
| 180 | + """Scan all tracked Markdown docs outside `.agents/` for link and URL issues.""" |
| 181 | + violations: list[DocViolation] = [] |
| 182 | + for doc in docs: |
| 183 | + doc_path = repo_root / doc |
| 184 | + if not doc_path.is_file(): |
| 185 | + continue |
| 186 | + text = doc_path.read_text(encoding="utf-8", errors="replace") |
| 187 | + for lineno, prose in iter_prose_lines(text): |
| 188 | + violations.extend(find_line_violations(doc, lineno, prose, existing)) |
| 189 | + return violations |
| 190 | + |
| 191 | + |
| 192 | +def check_doc_links(args: argparse.Namespace) -> dict[str, Any]: |
| 193 | + """Validate relative links and public URL hygiene in repository Markdown docs.""" |
| 194 | + repo_root = Path(args.repo_root).resolve() |
| 195 | + files = list_tracked_files(repo_root) |
| 196 | + docs = sorted(f for f in files if is_checked_doc(f)) |
| 197 | + violations = scan_docs(repo_root, docs, tracked_paths(files)) |
| 198 | + if violations: |
| 199 | + raise HandledError( |
| 200 | + f"Found {len(violations)} broken Markdown link(s) or internal URL(s).", |
| 201 | + "Fix broken relative Markdown links against tracked files/directories and remove " |
| 202 | + "local file:// or corporate URLs.", |
| 203 | + details={"violations": [dataclasses.asdict(v) for v in violations]}, |
| 204 | + ) |
| 205 | + return {"docs_scanned": len(docs), "violations": 0} |
| 206 | + |
| 207 | + |
| 208 | +def main() -> None: |
| 209 | + """CLI entrypoint.""" |
| 210 | + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) |
| 211 | + parser.add_argument("--repo-root", default=str(_REPO_ROOT), help="Repository root.") |
| 212 | + run_tool(parser, check_doc_links) |
| 213 | + |
| 214 | + |
| 215 | +if __name__ == "__main__": |
| 216 | + main() |
0 commit comments