ruststream 0.4.0

Async messaging framework for Rust: broker-agnostic traits, router, codecs, and a conformance harness for broker authors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

#!/usr/bin/env python3
"""Forbid inline Rust fences in docs/.

Every ```rust fence must either embed a compiled snippet (a --8<-- include) or be
explicitly exempted by an HTML comment on the line directly above it:

    <!-- inline-rust: <why this cannot come from a compiled example> -->
    ```rust

The justification is mandatory. Exemptions are for code that has no compilable home in
this repository: simplified trait sketches (the real signatures are RPITIT with long doc
comments) and walk-throughs of another crate's internals.
"""

import re
import sys
from pathlib import Path

FENCE = re.compile(r"^```rust\b")
SNIPPET = re.compile(r"--8<--")
EXEMPT = re.compile(r"<!--\s*inline-rust:\s*\S")

def lint(path: Path) -> list[str]:
    errors = []
    lines = path.read_text().splitlines()
    inside = False
    fence_line = 0
    exempt = False
    has_snippet = False
    for n, line in enumerate(lines, 1):
        if not inside and FENCE.match(line.strip()):
            inside = True
            fence_line = n
            exempt = n > 1 and bool(EXEMPT.search(lines[n - 2]))
            has_snippet = False
        elif inside:
            if SNIPPET.search(line):
                has_snippet = True
            if line.strip() == "```":
                inside = False
                if not has_snippet and not exempt:
                    errors.append(
                        f"{path}:{fence_line}: inline rust fence - embed a compiled"
                        " snippet (--8<--) or add an `<!-- inline-rust: why -->`"
                        " justification on the previous line"
                    )
    return errors

def main() -> int:
    docs = Path(__file__).resolve().parent.parent / "docs"
    errors = []
    for path in sorted(docs.rglob("*.md")):
        errors.extend(lint(path))
    for error in errors:
        print(error, file=sys.stderr)
    if errors:
        print(f"{len(errors)} inline rust fence(s)", file=sys.stderr)
    return 1 if errors else 0

if __name__ == "__main__":
    raise SystemExit(main())