|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""Linter: verify that list entries within each section of README.md are alphabetically sorted.""" |
| 3 | + |
| 4 | +import re |
| 5 | +import sys |
| 6 | +from pathlib import Path |
| 7 | + |
| 8 | + |
| 9 | +def extract_sections(filepath: str) -> list[tuple[str, str, list[str]]]: |
| 10 | + """Extract sections and their list items from a markdown file. |
| 11 | +
|
| 12 | + Returns list of (section_heading, context, items) where items are the display text. |
| 13 | + """ |
| 14 | + content = Path(filepath).read_text() |
| 15 | + lines = content.split("\n") |
| 16 | + |
| 17 | + sections = [] |
| 18 | + current_heading = None |
| 19 | + current_items: list[tuple[str, int]] = [] # (display_text, line_number) |
| 20 | + |
| 21 | + # Regex for markdown list items with links: "- [Display Text](url) - description" |
| 22 | + # Also handles plain list items: "- Display Text - description" |
| 23 | + item_re = re.compile(r"^- \[([^\]]+)\]\([^)]+\)", re.IGNORECASE) |
| 24 | + |
| 25 | + for i, line in enumerate(lines, 1): |
| 26 | + # Detect section headers (## or ###) |
| 27 | + heading_match = re.match(r"^(#{2,3})\s+(.+)", line) |
| 28 | + # Also detect <summary> tags as section boundaries inside <details> |
| 29 | + summary_match = re.match(r"<summary>(.+)</summary>", line.strip()) |
| 30 | + |
| 31 | + if heading_match: |
| 32 | + # Save previous section if it has items |
| 33 | + if current_heading and current_items: |
| 34 | + sections.append((current_heading, [t for t, _ in current_items])) |
| 35 | + current_heading = heading_match.group(2).strip() |
| 36 | + current_items = [] |
| 37 | + elif summary_match: |
| 38 | + if current_heading and current_items: |
| 39 | + sections.append((current_heading, [t for t, _ in current_items])) |
| 40 | + current_heading = f"[{summary_match.group(1).strip()}]" |
| 41 | + current_items = [] |
| 42 | + elif item_re.match(line): |
| 43 | + display_text = item_re.match(line).group(1) |
| 44 | + current_items.append((display_text.lower(), i)) |
| 45 | + |
| 46 | + # Don't forget the last section |
| 47 | + if current_heading and current_items: |
| 48 | + sections.append((current_heading, [t for t, _ in current_items])) |
| 49 | + |
| 50 | + return sections |
| 51 | + |
| 52 | + |
| 53 | +def check_sorted(items: list[str]) -> bool: |
| 54 | + """Return True if items are alphabetically sorted.""" |
| 55 | + return all(items[i] <= items[i + 1] for i in range(len(items) - 1)) |
| 56 | + |
| 57 | + |
| 58 | +def main(): |
| 59 | + readme = sys.argv[1] if len(sys.argv) > 1 else "README.md" |
| 60 | + |
| 61 | + if not Path(readme).exists(): |
| 62 | + print(f"ERROR: {readme} not found") |
| 63 | + sys.exit(1) |
| 64 | + |
| 65 | + sections = extract_sections(readme) |
| 66 | + errors = 0 |
| 67 | + |
| 68 | + skip_sections = {"Contents"} # TOC follows document order, not alphabetical |
| 69 | + |
| 70 | + for heading, items in sections: |
| 71 | + if not items or heading in skip_sections: |
| 72 | + continue |
| 73 | + if not check_sorted(items): |
| 74 | + sorted_items = sorted(items) |
| 75 | + print(f"FAIL: Section '{heading}' is not alphabetically sorted.") |
| 76 | + print(f" Current order: {', '.join(items)}") |
| 77 | + print(f" Expected order: {', '.join(sorted_items)}") |
| 78 | + errors += 1 |
| 79 | + else: |
| 80 | + print(f"OK: '{heading}' ({len(items)} items)") |
| 81 | + |
| 82 | + if errors: |
| 83 | + print(f"\n{errors} section(s) failed alphabetical check.") |
| 84 | + sys.exit(1) |
| 85 | + else: |
| 86 | + print("\nAll sections are alphabetically sorted.") |
| 87 | + sys.exit(0) |
| 88 | + |
| 89 | + |
| 90 | +if __name__ == "__main__": |
| 91 | + main() |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments