|
1 | 1 | #!/usr/bin/env python3 |
2 | | -"""Keep nine kinds of rot out of the published documentation. |
| 2 | +"""Keep ten kinds of rot out of the published documentation. |
3 | 3 |
|
4 | 4 | Why a second script rather than a mode of ``check_doc_anchors.py`` |
5 | 5 | ------------------------------------------------------------------ |
|
12 | 12 | and this one's offender list reads as a work list rather than as noise inside |
13 | 13 | another report. |
14 | 14 |
|
15 | | -The nine rules |
| 15 | +The ten rules |
16 | 16 | -------------- |
17 | 17 | 1. ``lane L<n>`` in a published page (``docs/pages/*.md``, ``README.md``). |
18 | 18 | A roadmap label is a promise about the future. Fifteen of them in |
|
107 | 107 | file's (R5 lane H-DOCGATES). A version framed as history (``since``, |
108 | 108 | ``was``, a release-notes link) is not a claim about this tree. |
109 | 109 |
|
| 110 | +10. The public selected-window section must name every ``PF_API`` function |
| 111 | + declared in ``selected_window.h`` and ``selected_window_plan.h`` and every |
| 112 | + option in ``run_json.py``'s selected-window argument block. Names come from |
| 113 | + the headers and the real ``add_argument`` calls, not a second inventory. |
| 114 | + A missing or duplicated section, unreadable source or unrecognised |
| 115 | + declaration/block is an offender too. Names elsewhere on the page, in |
| 116 | + comments or in fenced examples cannot stand in for the section. |
| 117 | +
|
110 | 118 | Exit status |
111 | 119 | ----------- |
112 | 120 | 0 when no offender is found, 1 otherwise. ``ci_preflight`` runs it as a |
|
115 | 123 | from __future__ import annotations |
116 | 124 |
|
117 | 125 | import argparse |
| 126 | +import ast |
118 | 127 | import re |
119 | 128 | import sys |
120 | 129 | from pathlib import Path |
|
127 | 136 | DOC_GLOBS = ('README.md', 'CONTRIBUTING.md', 'docs/*.md', 'docs/pages/*.md', |
128 | 137 | 'docs/adr/*.md', 'docs/design/*.md') |
129 | 138 |
|
| 139 | +SELECTED_WINDOW_PAGE = 'docs/pages/public-contract.md' |
| 140 | +SELECTED_WINDOW_SECTION = 'selected_windows_walk_forward' |
| 141 | +SELECTED_WINDOW_HEADERS = ('include/pineforge/selected_window.h', |
| 142 | + 'include/pineforge/selected_window_plan.h') |
| 143 | +SELECTED_WINDOW_CLI = 'docker/run_json.py' |
| 144 | + |
130 | 145 | VERIFIED = '<!-- verified HEAD -->' |
131 | 146 |
|
132 | 147 | LANE_RE = re.compile(r'\blane[s]?\s+L[0-9]') |
@@ -561,6 +576,116 @@ def verified_live_claims(page: Path, body: str, live_ns_families: dict[str, set[ |
561 | 576 | return out |
562 | 577 |
|
563 | 578 |
|
| 579 | +def selected_window_header_names(text: str) -> set[str]: |
| 580 | + """Read every complete PF_API function declaration from one public header.""" |
| 581 | + code = re.sub(r'/\*.*?\*/|//[^\n]*', '', text, flags=re.DOTALL) |
| 582 | + names = re.findall(r'^[ \t]*PF_API\b[^;{}]*?\b([A-Za-z_]\w*)\s*' |
| 583 | + r'\([^;{}]*\)\s*;', code, re.MULTILINE) |
| 584 | + declarations = len(re.findall(r'\bPF_API\b', code)) |
| 585 | + if (not declarations or len(names) != declarations |
| 586 | + or len(names) != len(set(names))): |
| 587 | + raise ValueError('expected complete, distinct PF_API function declarations') |
| 588 | + return set(names) |
| 589 | + |
| 590 | + |
| 591 | +def selected_window_options(text: str) -> set[str]: |
| 592 | + """Parse the real selected-window add_argument block without executing it.""" |
| 593 | + module = ast.parse(text) |
| 594 | + mains = [node for node in module.body |
| 595 | + if isinstance(node, ast.FunctionDef) and node.name == '_main'] |
| 596 | + if len(mains) != 1: |
| 597 | + raise ValueError('expected one _main function') |
| 598 | + main = mains[0] |
| 599 | + lines = text.splitlines() |
| 600 | + starts = [number for number, line in enumerate(lines, 1) |
| 601 | + if main.lineno < number < main.end_lineno |
| 602 | + and re.match(r'^\s*# Selected-window mode \(', line)] |
| 603 | + stops = [node.lineno for node in main.body |
| 604 | + if isinstance(node, ast.Assign) |
| 605 | + and any(isinstance(target, ast.Name) and target.id == 'pre_profile_long' |
| 606 | + for target in node.targets)] |
| 607 | + if len(starts) != 1 or len(stops) != 1 or starts[0] >= stops[0]: |
| 608 | + raise ValueError('cannot delimit the selected-window argument block') |
| 609 | + |
| 610 | + names: list[str] = [] |
| 611 | + for node in main.body: |
| 612 | + if not starts[0] < node.lineno < stops[0]: |
| 613 | + continue |
| 614 | + if (not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call) |
| 615 | + or not isinstance(node.value.func, ast.Attribute) |
| 616 | + or not isinstance(node.value.func.value, ast.Name) |
| 617 | + or node.value.func.value.id != 'ap' |
| 618 | + or node.value.func.attr != 'add_argument'): |
| 619 | + raise ValueError('expected only ap.add_argument calls in the selected-window block') |
| 620 | + if (not node.value.args |
| 621 | + or any(not isinstance(arg, ast.Constant) or not isinstance(arg.value, str) |
| 622 | + or re.fullmatch(r'--[A-Za-z][A-Za-z0-9-]*', arg.value) is None |
| 623 | + for arg in node.value.args)): |
| 624 | + raise ValueError('expected literal long option strings in selected-window block') |
| 625 | + names.extend(arg.value for arg in node.value.args) |
| 626 | + if not names or len(names) != len(set(names)): |
| 627 | + raise ValueError('expected nonempty, distinct selected-window options') |
| 628 | + return set(names) |
| 629 | + |
| 630 | + |
| 631 | +def selected_window_page_section(text: str) -> tuple[str, int]: |
| 632 | + """Return the anchored section with comments and fenced examples removed.""" |
| 633 | + body = re.sub(r'<!--.*?-->', |
| 634 | + lambda match: '\n' * match.group(0).count('\n'), |
| 635 | + masked(text), flags=re.DOTALL) |
| 636 | + lines = body.splitlines() |
| 637 | + anchor = re.compile(r'\{#' + re.escape(SELECTED_WINDOW_SECTION) + r'\}') |
| 638 | + headings: list[tuple[int, int]] = [] |
| 639 | + for index, line in enumerate(lines): |
| 640 | + match = re.match(r'^\s{0,3}(#{1,6})\s+', line) |
| 641 | + if match and anchor.search(line): |
| 642 | + headings.append((index, len(match.group(1)))) |
| 643 | + if len(headings) != 1: |
| 644 | + raise ValueError(f'expected one {{#{SELECTED_WINDOW_SECTION}}} section') |
| 645 | + |
| 646 | + start, level = headings[0] |
| 647 | + stop = len(lines) |
| 648 | + for index in range(start + 1, len(lines)): |
| 649 | + match = re.match(r'^\s{0,3}(#{1,6})\s+', lines[index]) |
| 650 | + if match and len(match.group(1)) <= level: |
| 651 | + stop = index |
| 652 | + break |
| 653 | + return '\n'.join(lines[start + 1:stop]), start + 1 |
| 654 | + |
| 655 | + |
| 656 | +def selected_window_contract(root: Path) -> list[Offender]: |
| 657 | + """Hold the public section to the headers and CLI, failing closed.""" |
| 658 | + page = root / SELECTED_WINDOW_PAGE |
| 659 | + found: list[Offender] = [] |
| 660 | + section: str | None = None |
| 661 | + first = 1 |
| 662 | + try: |
| 663 | + section, first = selected_window_page_section(page.read_text()) |
| 664 | + except (OSError, UnicodeError, ValueError) as error: |
| 665 | + found.append(Offender( |
| 666 | + page, first, 'selected-window-contract', SELECTED_WINDOW_SECTION, |
| 667 | + f'cannot read or parse the selected-window public section: {error}')) |
| 668 | + |
| 669 | + sources = [(rel, selected_window_header_names) for rel in SELECTED_WINDOW_HEADERS] |
| 670 | + sources.append((SELECTED_WINDOW_CLI, selected_window_options)) |
| 671 | + for rel, reader in sources: |
| 672 | + try: |
| 673 | + names = reader((root / rel).read_text()) |
| 674 | + except (OSError, UnicodeError, SyntaxError, ValueError) as error: |
| 675 | + found.append(Offender( |
| 676 | + page, first, 'selected-window-contract', rel, |
| 677 | + f'cannot read or parse selected-window source `{rel}`: {error}')) |
| 678 | + continue |
| 679 | + if section is None: |
| 680 | + continue |
| 681 | + for name in sorted(names): |
| 682 | + if re.search(r'(?<![\w-])' + re.escape(name) + r'(?![\w-])', section) is None: |
| 683 | + found.append(Offender( |
| 684 | + page, first, 'selected-window-contract', name, |
| 685 | + f'section omits `{name}` declared by `{rel}`')) |
| 686 | + return found |
| 687 | + |
| 688 | + |
564 | 689 | def check(root: Path) -> list[Offender]: |
565 | 690 | found: list[Offender] = [] |
566 | 691 | namespaces, domains = live_epochs(root) |
@@ -621,6 +746,7 @@ def check(root: Path) -> list[Offender]: |
621 | 746 | body = masked(text) |
622 | 747 | found.extend(stale_counts(page, body, counts)) |
623 | 748 | found.extend(verified_live_claims(page, body, live_ns_families, live_domain_families)) |
| 749 | + found.extend(selected_window_contract(root)) |
624 | 750 | found.sort(key=lambda o: (str(o.page), o.line, o.rule)) |
625 | 751 | return found |
626 | 752 |
|
@@ -672,7 +798,8 @@ def main(argv: list[str] | None = None) -> int: |
672 | 798 |
|
673 | 799 | if not found: |
674 | 800 | print('\nno lane labels, stale negatives, stale epochs, dead links, dead paths, ' |
675 | | - 'stale counts, stale ABI numbers or releases, or markers on a stale present') |
| 801 | + 'stale counts, stale ABI numbers or releases, or markers on a stale present, ' |
| 802 | + 'or selected-window contract omissions') |
676 | 803 | return 0 |
677 | 804 | print(f'\n{len(found)} offenders:') |
678 | 805 | for offender in found: |
|
0 commit comments