From 65a8e9fc9394ff4c9e9fca4000b8ef2681e8d95c Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 13 May 2026 05:36:00 -0700 Subject: ci(doc-linter): scope to docs/ only — skip repo-root meta files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The linter targets published documentation sources; the auto-discover fallback already walks `docs/` only. CI was passing root-level meta files (README.md, AGENTS.md, .github/copilot-instructions.md — the last is a symlink to AGENTS.md) which forced docs-publication conventions (80-char wrap, RFC IP rules, suppression markers) onto project meta that has no business obeying them. Add an `is_docs_path()` guard in `main()` so the explicit-file-list path matches the auto-discover behavior — only files under `docs/` are linted. AGENTS.md and the Copilot-instruction symlink are now out of scope. Verified: - `python3 scripts/doc-linter.py "['AGENTS.md', 'README.md', '.github/copilot-instructions.md']"` → exit 0 (all skipped). - `python3 scripts/doc-linter.py "['docs/_test_lint.md']"` with a real public IP → still errors as expected. 🤖 Generated by [robots](https://vyos.io) --- scripts/doc-linter.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index 5ccff488..c86ff29a 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -29,6 +29,16 @@ NUMBER = r"([\s']\d+[\s'])" SUPPORTED_EXTS = ('.md', '.rst', '.txt') +# Linter only applies to published documentation sources under docs/. Repo-root +# files (README.md, AGENTS.md, .github/copilot-instructions.md) are project +# meta, not docs content, and are out of scope. +DOCS_ROOT = 'docs' + os.sep + + +def is_docs_path(path): + norm = os.path.normpath(path) + return norm == 'docs' or norm.startswith(DOCS_ROOT) + # MyST / Markdown fenced code block: leading whitespace + 3+ backticks or 3+ colons. # Same character and length-or-greater closes. MD_FENCE_RE = re.compile(r'^(\s*)(`{3,}|:{3,})(.*)$') @@ -220,7 +230,11 @@ def main(): try: files = ast.literal_eval(sys.argv[1]) for file in files: - if file.endswith(SUPPORTED_EXTS) and "_build" not in file: + if ( + file.endswith(SUPPORTED_EXTS) + and "_build" not in file + and is_docs_path(file) + ): if handle_file_action(file) is False: bool_error = False except Exception as e: -- cgit v1.2.3 From ab497bf93ecc769f621b59220d9df1c13d3d2fa1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 19:46:51 +0000 Subject: doc-linter: handle absolute paths in is_docs_path() CodeRabbit review on 28224f3 flagged that is_docs_path() introduced in 65a8e9f only matched repo-relative path strings. An absolute path to docs/... (e.g., from a local invocation that pre-resolves paths, or from tooling that uses git ls-files --full-path) would silently fail the docs/ check and the file would be skipped. Rewrite the helper to use os.path.commonpath against an absolute docs/ root computed on each call. Both inputs are normalized to absolute form, so repo-relative and absolute callers produce the same result. ValueError from commonpath (mixed Windows drives or empty input) is caught and treated as 'not a docs path'. abs_docs is recomputed per call rather than captured at import time so the helper picks up the actual cwd at invocation, matching the existing assumption that CI / local runs invoke the linter from the repo root. Verified against 12 edge cases: - repo-relative docs paths (docs, docs/foo.md, docs/sub/dir/foo.md, ./docs/foo.md) -> True. - repo-relative meta paths (AGENTS.md, README.md, .github/copilot-instructions.md, docs_other/foo.md) -> False. - absolute paths inside docs/ -> True; inside repo root but outside docs/ -> False. - traversal attempts (../other/foo.md, docs/../AGENTS.md) -> False. CI behavior unchanged: tj-actions/changed-files passes repo-relative paths, which were already handled by the previous logic. --- scripts/doc-linter.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index c86ff29a..f580fcdc 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -32,12 +32,23 @@ SUPPORTED_EXTS = ('.md', '.rst', '.txt') # Linter only applies to published documentation sources under docs/. Repo-root # files (README.md, AGENTS.md, .github/copilot-instructions.md) are project # meta, not docs content, and are out of scope. -DOCS_ROOT = 'docs' + os.sep +DOCS_ROOT = 'docs' def is_docs_path(path): - norm = os.path.normpath(path) - return norm == 'docs' or norm.startswith(DOCS_ROOT) + """Return True iff `path` resolves under the repo's `docs/` tree. + + Accepts both repo-relative and absolute paths. Paths are normalized + against the linter's working directory (CI invokes it from the repo + root; the same is expected for local runs). + """ + abs_path = os.path.abspath(path) + abs_docs = os.path.abspath(DOCS_ROOT) + try: + return os.path.commonpath([abs_path, abs_docs]) == abs_docs + except ValueError: + # commonpath raises on mixed drives (Windows) or empty input. + return False # MyST / Markdown fenced code block: leading whitespace + 3+ backticks or 3+ colons. # Same character and length-or-greater closes. -- cgit v1.2.3 From bad55da626f59fd84e85e8f6d9a826ae1f0b8860 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 13 May 2026 23:30:02 +0300 Subject: docs(linter): add one-line docstrings to clear coverage warning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit Pre-merge Docstring Coverage check reported 50% on scripts/doc-linter.py (threshold 80%). Add minimal one-line docstrings to each public function; no behavior change. 🤖 Generated by [robots](https://vyos.io) --- scripts/doc-linter.py | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index f580fcdc..9f1e6f57 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -88,6 +88,7 @@ def is_suppression_marker(line, kind, in_md_fence, in_rst_codeblock, def lint_mac(cnt, line): + """Flag MAC addresses outside the RFC 7042 documentation range.""" mac = re.search(MAC, line, re.I) if mac is not None: mac = mac.group() @@ -98,6 +99,7 @@ def lint_mac(cnt, line): def lint_ipv4(cnt, line): + """Flag IPv4 addresses outside RFC 5737 / private / multicast ranges.""" ip = re.search(IPV4ADDR, line, re.I) if ip is not None: ip = ipaddress.ip_address(ip.group().strip(' ')) @@ -112,6 +114,7 @@ def lint_ipv4(cnt, line): def lint_ipv6(cnt, line): + """Flag IPv6 addresses outside RFC 3849 / private / multicast ranges.""" ip = re.search(IPV6ADDR, line, re.I) if ip is not None: ip = ipaddress.ip_address(ip.group().strip(' ')) @@ -125,6 +128,7 @@ def lint_ipv6(cnt, line): def lint_AS(cnt, line): + """Placeholder for future AS-number documentation-range checks (RFC 5398).""" number = re.search(NUMBER, line, re.I) if number: pass @@ -132,11 +136,13 @@ def lint_AS(cnt, line): def lint_linelen(cnt, line): + """Warn when a line exceeds the 80-character docs convention.""" line = line.rstrip() if len(line) > 80: return (f"Line too long: len={len(line)}", cnt, 'warning') def handle_file_action(filepath): + """Run all lint checks on one file, respecting fence/code-block and suppression context.""" errors = [] file_ext = os.path.splitext(filepath)[1].lower() # Stack of open MD/MyST fences: (char, min_len). Supports nesting like @@ -236,6 +242,7 @@ def handle_file_action(filepath): def main(): + """Entry point: lint the changed-file list from argv, or fall back to walking `docs/`.""" bool_error = True print('start') try: -- cgit v1.2.3 From 5d1c2d74d1e18e80b788e5778b10b94053343c2c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 20:35:38 +0000 Subject: doc-linter: realpath() resolution, DOCS_ROOT in walker, indent fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three Copilot findings on ab497bf: 1. is_docs_path() docstring claimed paths 'resolve' under docs/, but the implementation only normalized via abspath() — a symlink under docs/ that points outside the tree would be treated as in-scope. Switch both inputs to os.path.realpath() so symlinks are followed to their real targets. The reverse case is also handled: if docs/ is itself a symlink (some CI checkouts), realpath() resolves it consistently for both sides of the commonpath comparison. Verified with a synthetic case: docs/poison.md -> /etc/hosts now returns False (with abspath() it returned True). 2. The auto-discover fallback in main() still hardcoded os.walk('docs') instead of using the new DOCS_ROOT constant. Use DOCS_ROOT in both paths so the docs root is configured in exactly one place. 3. Indentation inside 'for file in files:' was double-indented (8 spaces under the for, instead of 4) — pre-existing oddity from before 65a8e9f, preserved through the is_docs_path() addition. Normalize to a single indent level under the loop. CI behavior unchanged: tj-actions/changed-files passes repo-relative paths with no symlinks under docs/, which were already handled. The realpath() switch only changes behavior in the symlink-escape case, which was a bug. --- scripts/doc-linter.py | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index 9f1e6f57..c3304718 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -38,12 +38,17 @@ DOCS_ROOT = 'docs' def is_docs_path(path): """Return True iff `path` resolves under the repo's `docs/` tree. - Accepts both repo-relative and absolute paths. Paths are normalized - against the linter's working directory (CI invokes it from the repo - root; the same is expected for local runs). + Accepts both repo-relative and absolute paths. Both `path` and + `DOCS_ROOT` are resolved with `os.path.realpath`, so symlinks are + followed to their real targets — a symlink under `docs/` that + points outside the tree is correctly treated as out-of-scope, and + a `docs/` that is itself a symlink (e.g., in some CI checkouts) is + correctly treated as the docs root. Paths are normalized against + the linter's working directory (CI invokes it from the repo root; + the same is expected for local runs). """ - abs_path = os.path.abspath(path) - abs_docs = os.path.abspath(DOCS_ROOT) + abs_path = os.path.realpath(path) + abs_docs = os.path.realpath(DOCS_ROOT) try: return os.path.commonpath([abs_path, abs_docs]) == abs_docs except ValueError: @@ -248,15 +253,15 @@ def main(): try: files = ast.literal_eval(sys.argv[1]) for file in files: - if ( - file.endswith(SUPPORTED_EXTS) - and "_build" not in file - and is_docs_path(file) - ): - if handle_file_action(file) is False: - bool_error = False + if ( + file.endswith(SUPPORTED_EXTS) + and "_build" not in file + and is_docs_path(file) + ): + if handle_file_action(file) is False: + bool_error = False except Exception as e: - for root, dirs, files in os.walk("docs"): + for root, dirs, files in os.walk(DOCS_ROOT): path = root.split(os.sep) for file in files: if file.endswith(SUPPORTED_EXTS) and "_build" not in path: -- cgit v1.2.3 From 36d8f3ee1e0caa54b041e2ee1b16425cf7a3044a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 20:40:31 +0000 Subject: doc-linter: rename unused walker var to _dirs CodeRabbit nit (Ruff B007): the dirs variable from os.walk(DOCS_ROOT) in the auto-discover fallback is unused. Renaming to _dirs makes the intent explicit and silences the warning. --- scripts/doc-linter.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index c3304718..b1977f84 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -261,7 +261,7 @@ def main(): if handle_file_action(file) is False: bool_error = False except Exception as e: - for root, dirs, files in os.walk(DOCS_ROOT): + for root, _dirs, files in os.walk(DOCS_ROOT): path = root.split(os.sep) for file in files: if file.endswith(SUPPORTED_EXTS) and "_build" not in path: -- cgit v1.2.3 From 8be6993d1496b0cec62c3a485519f6f915a62ecf Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 20:45:14 +0000 Subject: doc-linter: narrow argv parsing exception scope to (IndexError, SyntaxError, ValueError) CodeRabbit / Ruff BLE001: the previous 'except Exception as e:' on the explicit-file-list path caught any error, masking runtime failures from handle_file_action() as silent fallback behavior. Only input validation errors from ast.literal_eval(sys.argv[1]) should trigger the fallback walk. Refactor: - Wrap only the parse step in try/except, catching just IndexError (missing argv[1]), SyntaxError (malformed literal), and ValueError (non-literal input). - On parse failure, set files = None and dispatch to the DOCS_ROOT walk via an explicit 'else' branch. - On parse success, run the file loop outside the try so any errors from handle_file_action() propagate normally and CI fails loudly. Also drops the unused 'as e' (Ruff BLE001 noise) and the implicit catch of TypeError (e.g. ast.literal_eval('42') returns an int and 'for file in 42:' would have been silently swallowed -> fallback walk; now it raises clearly). Verified scenarios: - explicit file list (CI normal path) -> exit 0. - no argv -> IndexError caught -> walks DOCS_ROOT. - malformed argv ('not-a-list') -> SyntaxError caught -> walks DOCS_ROOT. - explicit list with a non-existent file -> FileNotFoundError propagates (previously silently triggered a fallback walk). - explicit list with a non-list literal ('42') -> TypeError propagates (programming error stays visible). --- scripts/doc-linter.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/doc-linter.py b/scripts/doc-linter.py index b1977f84..8e74600f 100644 --- a/scripts/doc-linter.py +++ b/scripts/doc-linter.py @@ -250,8 +250,16 @@ def main(): """Entry point: lint the changed-file list from argv, or fall back to walking `docs/`.""" bool_error = True print('start') + # Only the argv-parsing step is wrapped in try/except. Errors raised by + # handle_file_action() must propagate so CI failures stay visible instead + # of silently triggering a full docs/ walk. try: files = ast.literal_eval(sys.argv[1]) + except (IndexError, SyntaxError, ValueError): + # No argv or malformed list -> fall back to walking DOCS_ROOT. + files = None + + if files is not None: for file in files: if ( file.endswith(SUPPORTED_EXTS) @@ -260,7 +268,7 @@ def main(): ): if handle_file_action(file) is False: bool_error = False - except Exception as e: + else: for root, _dirs, files in os.walk(DOCS_ROOT): path = root.split(os.sep) for file in files: -- cgit v1.2.3