path: root/scripts/doc-linter.py

import os
import re
import ipaddress
import sys
import json

IPV4SEG  = r'(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])'
IPV4ADDR = r'\b(?:(?:' + IPV4SEG + r'\.){3,3}' + IPV4SEG + r')\b'
IPV6SEG  = r'(?:(?:[0-9a-fA-F]){1,4})'
IPV6GROUPS = (
    r'(?:' + IPV6SEG + r':){7,7}' + IPV6SEG,                  # 1:2:3:4:5:6:7:8
    r'\b(?:' + IPV6SEG + r':){1,7}:',                           # 1::                                 1:2:3:4:5:6:7::
    r'(?:' + IPV6SEG + r':){1,6}:' + IPV6SEG,                 # 1::8               1:2:3:4:5:6::8   1:2:3:4:5:6::8
    r'(?:' + IPV6SEG + r':){1,5}(?::' + IPV6SEG + r'){1,2}',  # 1::7:8             1:2:3:4:5::7:8   1:2:3:4:5::8
    r'(?:' + IPV6SEG + r':){1,4}(?::' + IPV6SEG + r'){1,3}',  # 1::6:7:8           1:2:3:4::6:7:8   1:2:3:4::8
    r'(?:' + IPV6SEG + r':){1,3}(?::' + IPV6SEG + r'){1,4}',  # 1::5:6:7:8         1:2:3::5:6:7:8   1:2:3::8
    r'(?:' + IPV6SEG + r':){1,2}(?::' + IPV6SEG + r'){1,5}',  # 1::4:5:6:7:8       1:2::4:5:6:7:8   1:2::8
    IPV6SEG + r':(?:(?::' + IPV6SEG + r'){1,6})',             # 1::3:4:5:6:7:8     1::3:4:5:6:7:8   1::8
    r':(?:(?::' + IPV6SEG + r'){1,7}|:)',                     # ::2:3:4:5:6:7:8    ::2:3:4:5:6:7:8  ::8       ::
    r'fe80:(?::' + IPV6SEG + r'){0,4}%[0-9a-zA-Z]{1,}',       # fe80::7:8%eth0     fe80::7:8%1  (link-local IPv6 addresses with zone index)
    r'::(?:ffff(?::0{1,4}){0,1}:){0,1}[^\s:]' + IPV4ADDR,     # ::255.255.255.255  ::ffff:255.255.255.255  ::ffff:0:255.255.255.255 (IPv4-mapped IPv6 addresses and IPv4-translated addresses)
    r'(?:' + IPV6SEG + r':){1,4}:[^\s:]' + IPV4ADDR,          # 2001:db8:3:4::192.0.2.33  64:ff9b::192.0.2.33 (IPv4-Embedded IPv6 Address)
)
IPV6ADDR = '|'.join(['(?:{})'.format(g) for g in IPV6GROUPS[::-1]])  # Reverse rows for greedy match

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'

# Subtrees under docs/ that are excluded from the build (per docs/conf.py)
# and therefore also excluded from lint.
DOCS_EXCLUDED_SUBDIRS = ('_build', '_rst_legacy')


def is_docs_path(path):
    """Return True iff `path` resolves under the repo's `docs/` tree AND
    is not inside one of the build-excluded subtrees (``_build``,
    ``_rst_legacy``).

    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.realpath(path)
    abs_docs = os.path.realpath(DOCS_ROOT)
    try:
        if os.path.commonpath([abs_path, abs_docs]) != abs_docs:
            return False
    except ValueError:
        # commonpath raises on mixed drives (Windows) or empty input.
        return False
    for excluded in DOCS_EXCLUDED_SUBDIRS:
        abs_excluded = os.path.realpath(os.path.join(DOCS_ROOT, excluded))
        try:
            if os.path.commonpath([abs_path, abs_excluded]) == abs_excluded:
                return False
        except ValueError:
            continue
    return True

# 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,})(.*)$')

# RST `.. code-block::` directive: leading whitespace + literal `.. code-block::`.
# Anchored to start-of-line so prose mentions like `\`\`.. code-block::\`\`` inside
# a Markdown paragraph (see docs/documentation.md) don't false-trigger the
# code-block tracker.
RST_CODEBLOCK_RE = re.compile(r'^(\s*)\.\.\s+code-block::')

# MyST directive names whose body is code-like — line-length exception applies.
# Anything else with a `{directive}` info string is treated as prose-bearing
# (`{note}`, `{warning}`, `{tip}`, `{deprecated}`, …); their content is normal
# Markdown and gets line-length checked. Plain fences with no info string OR a
# bare language tag (`python`, `bash`, `yaml`, …) are code blocks per
# CommonMark and always skip line-length.
CODE_BEARING_DIRECTIVES = frozenset({
    'code-block', 'code', 'sourcecode',
    'cfgcmd', 'opcmd', 'cmdinclude', 'cmdincludemd',
    'literalinclude', 'parsed-literal', 'raw',
    'command-output',
    'eval-rst',  # body is RST; its own line-length is handled via the
                 # `.. code-block::` tracker for nested code blocks.
})


def _fence_is_code(info):
    """Return True iff the fence opener `info` string designates a code-like block.

    Used to gate the line-length-check skip — only code-like fences should
    suppress line-length linting; prose-bearing directive fences like
    `{note}` / `{warning}` must still have their content checked.
    """
    info = info.strip()
    if not info:
        return True  # plain ``` is code per CommonMark
    if not info.startswith('{'):
        return True  # python, bash, yaml, text, etc.
    # `{code-block} python` -> `code-block`; `{note}` -> `note`.
    name = info[1:].split('}', 1)[0].strip()
    return name in CODE_BEARING_DIRECTIVES


SUPPRESSION_MARKER_RE = {
    'rst': {
        'stop': re.compile(r'^\s*\.\.\s+stop_vyoslinter\s*$'),
        'start': re.compile(r'^\s*\.\.\s+start_vyoslinter\s*$'),
    },
    'md': {
        'stop': re.compile(r'^\s*%\s+stop_vyoslinter\s*$'),
        'start': re.compile(r'^\s*%\s+start_vyoslinter\s*$'),
    },
}


def is_suppression_marker(line, kind, in_md_fence, in_rst_codeblock,
                          md_fence_is_eval_rst, file_ext):
    """Detect valid stop/start markers in the parser context where they apply.

    `% ...` is only valid in MyST Markdown (`.md`) at top level (outside any fence).
    `.. ...` is valid in `.rst`/`.txt` at top level (outside RST code-block) and
    in `.md` only when inside an `{eval-rst}` fence.
    """
    if SUPPRESSION_MARKER_RE['md'][kind].match(line):
        return file_ext == '.md' and not in_md_fence
    if not SUPPRESSION_MARKER_RE['rst'][kind].match(line):
        return False
    if in_rst_codeblock:
        return False
    if file_ext in ('.rst', '.txt'):
        return True
    if in_md_fence:
        return md_fence_is_eval_rst
    return False


def lint_ipv4(cnt, line):
    """Flag IPv4 addresses outside RFC 5737 / private / multicast ranges.

    Iterates over every IPv4 match on the line — a line with an
    allowed address followed by a real public address must not
    pass just because the first match is allowed.
    """
    for match in re.finditer(IPV4ADDR, line, re.I):
        ip = ipaddress.ip_address(match.group().strip(' '))
        # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_private
        if ip.is_private:
            continue
        if ip.is_multicast:
            continue
        if ip.is_global is False:
            continue
        return (f"Use IPv4 reserved for Documentation (RFC 5737) or private space: {ip}", cnt, 'error')
    return None


def lint_ipv6(cnt, line):
    """Flag IPv6 addresses outside RFC 3849 / private / multicast ranges.

    Iterates over every IPv6 match on the line — same all-matches
    discipline as `lint_ipv4`.
    """
    for match in re.finditer(IPV6ADDR, line, re.I):
        ip = ipaddress.ip_address(match.group().strip(' '))
        if ip.is_private:
            continue
        if ip.is_multicast:
            continue
        if ip.is_global is False:
            continue
        return (f"Use IPv6 reserved for Documentation (RFC 3849) or private space: {ip}", cnt, 'error')
    return None


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, is_code). Supports
    # nesting like `:::{note}` containing `::::{code-block}`, where the
    # inner opener does not close the outer note (CommonMark closing rule:
    # matching closer must have no info string after the fence chars).
    # `is_code` records whether THAT fence is a code-bearing one — gates the
    # line-length skip per the innermost (top-of-stack) entry.
    md_fence_stack = []
    md_fence_is_eval_rst = False
    in_rst_codeblock = False
    rst_codeblock_indent = 0
    start_vyoslinter = True
    cnt = 0

    with open(filepath) as fp:
        for cnt, line in enumerate(fp, start=1):
            # MD/MyST fenced code block tracking (``` or :::).
            fence_match = MD_FENCE_RE.match(line)
            if fence_match:
                fence = fence_match.group(2)
                fence_char = fence[0]
                fence_len = len(fence)
                info = fence_match.group(3).strip()
                # A closer matches the top of the stack (same char, len >=
                # opener) and has no info string. Anything else opens a new
                # (possibly nested) fence.
                is_closer = (
                    md_fence_stack
                    and not info
                    and fence_char == md_fence_stack[-1][0]
                    and fence_len >= md_fence_stack[-1][1]
                )
                if is_closer:
                    md_fence_stack.pop()
                    if not md_fence_stack:
                        md_fence_is_eval_rst = False
                else:
                    if not md_fence_stack:
                        md_fence_is_eval_rst = info.startswith('{eval-rst}')
                    md_fence_stack.append((fence_char, fence_len, _fence_is_code(info)))

            in_md_fence = bool(md_fence_stack)
            in_md_code_fence = bool(md_fence_stack) and md_fence_stack[-1][2]

            # RST `.. code-block::` tracking (existing semantics for .rst/.txt).
            # Each `.. code-block::` directive resets the tracked indent so a
            # later dedent past that column exits the block — even when the
            # directive itself appears inside an already-open outer block.
            #
            # Exit when the next non-blank line's leading-whitespace count is
            # <= the directive's column. The body of an RST code-block must
            # be indented MORE than the directive itself, so leading-ws at or
            # below `rst_codeblock_indent` signals the block has ended.
            #
            # Previously this used `len(line) > rst_codeblock_indent and not
            # line[rst_codeblock_indent].isspace()`, which silently skipped
            # the exit check on lines shorter than `rst_codeblock_indent + 1`
            # chars — e.g., a 3-char dedented line under a directive at
            # column 4 left the block open, suppressing line-length checks
            # downstream.
            if in_rst_codeblock and line.strip():
                leading = len(line) - len(line.lstrip())
                if leading <= rst_codeblock_indent:
                    in_rst_codeblock = False
            # Only treat `.. code-block::` as a directive opener in RST/TXT
            # files or inside an `{eval-rst}` MyST fence. In plain Markdown
            # the same characters can appear as prose (e.g., backtick-quoted
            # mentions of the directive name) and must not open a block.
            if file_ext in ('.rst', '.txt') or md_fence_is_eval_rst:
                rst_open = RST_CODEBLOCK_RE.match(line)
                if rst_open:
                    in_rst_codeblock = True
                    rst_codeblock_indent = len(rst_open.group(1))

            if is_suppression_marker(
                line, 'stop', in_md_fence, in_rst_codeblock,
                md_fence_is_eval_rst, file_ext,
            ):
                start_vyoslinter = False
            if is_suppression_marker(
                line, 'start', in_md_fence, in_rst_codeblock,
                md_fence_is_eval_rst, file_ext,
            ):
                start_vyoslinter = True

            if not start_vyoslinter:
                continue

            # Only code-bearing fences (plain ```python```, `{code-block}`,
            # `{cfgcmd}`, etc.) skip line-length. Prose-bearing directives
            # like `{note}` and `{warning}` have their content checked.
            test_line_length = not (in_md_code_fence or in_rst_codeblock)

            err_ip4 = lint_ipv4(cnt, line.strip())
            err_ip6 = lint_ipv6(cnt, line.strip())
            err_len = lint_linelen(cnt, line) if test_line_length else None
            for e in (err_ip4, err_ip6, err_len):
                if e:
                    errors.append(e)

        if not start_vyoslinter:
            errors.append(("Don't forget to turn linter back on", cnt, 'error'))

    if len(errors) > 0:
        '''
        "::{$type} file={$filename},line={$line},col=$column::{$log}"
        '''
        print(f"File: {filepath}")
        for error in errors:
            print(f"::{error[2]} file={filepath},line={error[1]}::{error[0]}")
        print('')
        return False


def main():
    """Entry point: lint the changed-file list from argv, or fall back to walking `docs/`."""
    bool_error = True
    # 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.
    #
    # Accepts one or more positional argv entries, each a JSON array of
    # paths (e.g., `'["foo.md", "bar.rst"]'`). Arrays are merged and
    # deduplicated before linting. CI passes `files_modified`,
    # `files_added`, etc. as separate args — see lint-doc.yml.
    if len(sys.argv) <= 1:
        files = None
    else:
        try:
            files = []
            for arg in sys.argv[1:]:
                if arg.strip():
                    files.extend(json.loads(arg))
            files = sorted(set(files))
        except (json.JSONDecodeError, TypeError):
            # Malformed input -> fall back to walking DOCS_ROOT.
            files = None

    if files is not None:
        for file in files:
            if (
                file.endswith(SUPPORTED_EXTS)
                and is_docs_path(file)
            ):
                if handle_file_action(file) is False:
                    bool_error = False
    else:
        # In-place dirs prune: skip descending into build-excluded subtrees.
        # is_docs_path() also rejects paths under those subtrees, so the
        # prune is an optimization (avoids walking thousands of archived
        # legacy RST files) and the filter is correctness.
        for root, dirs, files in os.walk(DOCS_ROOT):
            dirs[:] = [d for d in dirs if d not in DOCS_EXCLUDED_SUBDIRS]
            for file in files:
                filepath = os.path.join(root, file)
                if (
                    file.endswith(SUPPORTED_EXTS)
                    and is_docs_path(filepath)
                ):
                    if handle_file_action(filepath) is False:
                        bool_error = False

    return bool_error


if __name__ == "__main__":
    if main() == False:
        exit(1)