field_ios

In-the-field app for Radroots on iOS
git clone https://radroots.dev/git/field_ios.git
Log | Files | Refs | README | LICENSE

maintainability_ratchet.py (14389B)


      1 #!/usr/bin/env python3
      2 """Fail-closed Swift/Python size and Python complexity ratchet."""
      3 
      4 from __future__ import annotations
      5 
      6 import argparse
      7 import ast
      8 import json
      9 import sys
     10 from pathlib import Path
     11 from typing import Any
     12 
     13 from authored_source_inventory import InventoryError, source_files
     14 
     15 MAX_BASELINE_BYTES = 256 * 1024
     16 BASELINE_PATH = Path("test-fixtures/maintainability-baseline.v1.json")
     17 
     18 # Approved pre-ratchet ceilings. Candidate baseline changes cannot enlarge them.
     19 APPROVED_EXCEPTIONS = {
     20     "swift_file_exception": {
     21         "Tera/Runtime/TeraGeneratedRuntimeBackend.swift": 1188,
     22         "Tera/Runtime/TeraRuntimeClient.swift": 820,
     23         "Tera/Runtime/TeraRuntimeModels.swift": 1154,
     24         "Tera/State/TeraAddStore.swift": 783,
     25         "Tera/State/TeraConfigurationStore.swift": 759,
     26         "TeraTests/TeraAddStoreTests.swift": 1366,
     27         "TeraTests/TeraStateMigrationTests.swift": 718,
     28         "TeraUITests/TeraRemoteQualificationUITests.swift": 1924,
     29     },
     30     "python_file_exception": {
     31         "scripts/local-social-fixture.py": 2626,
     32         "scripts/test_local_social_fixture.py": 1188,
     33     },
     34     "python_complexity_exception": {
     35         "scripts/local-social-fixture.py:FixtureState._publish_persona_event": 13,
     36         "scripts/local-social-fixture.py:FixtureState.upload": 14,
     37         "scripts/local-social-fixture.py:RelayHandler.handle": 26,
     38         "scripts/local-social-fixture.py:bounded_directory_inventory": 12,
     39         "scripts/local-social-fixture.py:directory_digest": 16,
     40         "scripts/local-social-fixture.py:exact_persona_test_node": 11,
     41         "scripts/local-social-fixture.py:load_exported_persona_attachments": 31,
     42         "scripts/local-social-fixture.py:matches": 22,
     43         "scripts/local-social-fixture.py:photo_attempt_matches": 12,
     44         "scripts/local-social-fixture.py:reconstruct_persona_result_v2": 66,
     45         "scripts/local-social-fixture.py:simulator_metadata": 23,
     46         "scripts/local-social-fixture.py:valid_blossom_authorization": 29,
     47         "scripts/local-social-fixture.py:valid_bud11_server_domain": 12,
     48         "scripts/local-social-fixture.py:valid_nostr_event": 16,
     49         "scripts/local-social-fixture.py:validate_persona_attempt_evidence": 59,
     50         "scripts/local-social-fixture.py:validate_persona_evidence": 31,
     51         "scripts/local-social-fixture.py:validate_persona_result": 43,
     52         "scripts/local-social-fixture.py:validate_persona_suite": 28,
     53         "scripts/local-social-fixture.py:verify_bip340": 11,
     54         "scripts/local-social-fixture.py:verify_persona": 18,
     55         "scripts/test_local_social_fixture.py:mutate_bud11_event": 29,
     56     },
     57 }
     58 ORIGINAL_BOUNDED_MODULES = frozenset(
     59     (
     60         "Tera/Runtime/TeraUserMessageClassifier.swift",
     61         "Tera/Runtime/TeraUserMessages.swift",
     62         "Tera/Views/TeraSupportSettingsSection.swift",
     63         "scripts/maintainability_ratchet.py",
     64         "scripts/package_contract.py",
     65         "scripts/package_privacy.py",
     66         "scripts/test_package_contract.py",
     67         "scripts/test_package_privacy.py",
     68     )
     69 )
     70 
     71 
     72 class MaintainabilityError(Exception):
     73     """Stable maintainability-policy rejection."""
     74 
     75 
     76 class _FunctionComplexity(ast.NodeVisitor):
     77     def __init__(self) -> None:
     78         self.value = 1
     79 
     80     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
     81         del node
     82 
     83     def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
     84         del node
     85 
     86     def visit_Lambda(self, node: ast.Lambda) -> None:
     87         del node
     88 
     89     def visit_If(self, node: ast.If) -> None:
     90         self.value += 1
     91         self.generic_visit(node)
     92 
     93     def visit_IfExp(self, node: ast.IfExp) -> None:
     94         self.value += 1
     95         self.generic_visit(node)
     96 
     97     def visit_For(self, node: ast.For) -> None:
     98         self.value += 1
     99         self.generic_visit(node)
    100 
    101     def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
    102         self.value += 1
    103         self.generic_visit(node)
    104 
    105     def visit_While(self, node: ast.While) -> None:
    106         self.value += 1
    107         self.generic_visit(node)
    108 
    109     def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
    110         self.value += 1
    111         self.generic_visit(node)
    112 
    113     def visit_BoolOp(self, node: ast.BoolOp) -> None:
    114         self.value += max(0, len(node.values) - 1)
    115         self.generic_visit(node)
    116 
    117     def visit_Match(self, node: ast.Match) -> None:
    118         self.value += len(node.cases)
    119         self.generic_visit(node)
    120 
    121     def visit_comprehension(self, node: ast.comprehension) -> None:
    122         self.value += 1 + len(node.ifs)
    123         self.generic_visit(node)
    124 
    125 
    126 class _DefinitionCollector(ast.NodeVisitor):
    127     def __init__(self, path: str) -> None:
    128         self.path = path
    129         self.scope: list[str] = []
    130         self.values: dict[str, int] = {}
    131 
    132     def visit_ClassDef(self, node: ast.ClassDef) -> None:
    133         self.scope.append(node.name)
    134         self.generic_visit(node)
    135         self.scope.pop()
    136 
    137     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
    138         self._record(node)
    139 
    140     def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
    141         self._record(node)
    142 
    143     def _record(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
    144         name = ".".join((*self.scope, node.name))
    145         key = f"{self.path}:{name}"
    146         if key in self.values:
    147             raise MaintainabilityError("Python function identity is duplicated")
    148         counter = _FunctionComplexity()
    149         for statement in node.body:
    150             counter.visit(statement)
    151         self.values[key] = counter.value
    152         self.scope.append(node.name)
    153         for statement in node.body:
    154             self.visit(statement)
    155         self.scope.pop()
    156 
    157 
    158 def _read_regular(path: Path, maximum: int = MAX_BASELINE_BYTES) -> bytes:
    159     try:
    160         if path.is_symlink() or not path.is_file():
    161             raise MaintainabilityError("maintainability input is not a regular file")
    162         size = path.stat().st_size
    163         if size < 1 or size > maximum:
    164             raise MaintainabilityError("maintainability input exceeds its byte bound")
    165         value = path.read_bytes()
    166     except OSError as error:
    167         raise MaintainabilityError("maintainability input cannot be read") from error
    168     if len(value) != size:
    169         raise MaintainabilityError("maintainability input changed while reading")
    170     return value
    171 
    172 
    173 def _load_baseline(repo_root: Path) -> dict[str, Any]:
    174     try:
    175         value = json.loads(_read_regular(repo_root / BASELINE_PATH))
    176     except (UnicodeDecodeError, json.JSONDecodeError) as error:
    177         raise MaintainabilityError("maintainability baseline is malformed") from error
    178     expected = {
    179         "schema",
    180         "schema_version",
    181         "source_revision",
    182         "thresholds",
    183         "swift_file_exception",
    184         "python_file_exception",
    185         "python_complexity_exception",
    186         "bounded_module",
    187     }
    188     if not isinstance(value, dict) or set(value) != expected:
    189         raise MaintainabilityError("maintainability baseline fields differ")
    190     if (
    191         value["schema"] != "radroots.ios.maintainability-baseline.v1"
    192         or value["schema_version"] != 1
    193         or value["source_revision"] != "c63002bcc4d3f6656e93aabe4fca6bd771376629"
    194     ):
    195         raise MaintainabilityError("maintainability baseline identity differs")
    196     return value
    197 
    198 
    199 def _source_files(repo_root: Path) -> tuple[list[Path], list[Path]]:
    200     try:
    201         return source_files(repo_root)
    202     except InventoryError as error:
    203         raise MaintainabilityError(
    204             "maintainability source inventory is invalid"
    205         ) from error
    206 
    207 
    208 def _line_inventory(repo_root: Path, paths: list[Path]) -> dict[str, int]:
    209     values: dict[str, int] = {}
    210     for path in paths:
    211         raw = _read_regular(path, 4 * 1024 * 1024)
    212         try:
    213             text = raw.decode("utf-8")
    214         except UnicodeDecodeError as error:
    215             raise MaintainabilityError("maintainability source is not UTF-8") from error
    216         relative = path.relative_to(repo_root).as_posix()
    217         values[relative] = len(text.splitlines())
    218     return values
    219 
    220 
    221 def _python_complexity(repo_root: Path, paths: list[Path]) -> dict[str, int]:
    222     values: dict[str, int] = {}
    223     for path in paths:
    224         relative = path.relative_to(repo_root).as_posix()
    225         try:
    226             tree = ast.parse(_read_regular(path, 4 * 1024 * 1024), filename=relative)
    227         except (SyntaxError, ValueError) as error:
    228             raise MaintainabilityError("Python source cannot be parsed") from error
    229         collector = _DefinitionCollector(relative)
    230         collector.visit(tree)
    231         overlap = set(values) & set(collector.values)
    232         if overlap:
    233             raise MaintainabilityError("Python function identity is duplicated")
    234         values.update(collector.values)
    235     return values
    236 
    237 
    238 def snapshot(repo_root: Path) -> dict[str, dict[str, int]]:
    239     swift, python = _source_files(repo_root)
    240     return {
    241         "swift_lines": _line_inventory(repo_root, swift),
    242         "python_lines": _line_inventory(repo_root, python),
    243         "python_complexity": _python_complexity(repo_root, python),
    244     }
    245 
    246 
    247 def _closed_exception_map(
    248     value: object,
    249     *,
    250     key_name: str,
    251     ceiling_name: str,
    252 ) -> dict[str, int]:
    253     if not isinstance(value, list):
    254         raise MaintainabilityError("maintainability exception inventory is invalid")
    255     result: dict[str, int] = {}
    256     for row in value:
    257         if (
    258             not isinstance(row, dict)
    259             or set(row) != {key_name, ceiling_name}
    260             or not isinstance(row[key_name], str)
    261             or not isinstance(row[ceiling_name], int)
    262             or row[ceiling_name] < 1
    263             or row[key_name] in result
    264         ):
    265             raise MaintainabilityError("maintainability exception row is invalid")
    266         result[row[key_name]] = row[ceiling_name]
    267     if list(result) != sorted(result):
    268         raise MaintainabilityError("maintainability exceptions are not ordered")
    269     return result
    270 
    271 
    272 def _verify_metric(
    273     observed: dict[str, int],
    274     exceptions: dict[str, int],
    275     threshold: int,
    276     label: str,
    277 ) -> None:
    278     expected_exceptions = {key for key, value in observed.items() if value > threshold}
    279     if set(exceptions) != expected_exceptions:
    280         raise MaintainabilityError(f"{label} exception inventory differs")
    281     for key, ceiling in exceptions.items():
    282         if ceiling <= threshold or observed[key] > ceiling:
    283             raise MaintainabilityError(f"{label} metric regressed")
    284 
    285 
    286 def _thresholds(baseline: dict[str, Any]) -> dict[str, int]:
    287     value = baseline["thresholds"]
    288     if (
    289         not isinstance(value, dict)
    290         or set(value)
    291         != {"swift_file_lines", "python_file_lines", "python_function_complexity"}
    292         or value["swift_file_lines"] != 600
    293         or value["python_file_lines"] != 800
    294         or value["python_function_complexity"] != 10
    295     ):
    296         raise MaintainabilityError("maintainability thresholds differ")
    297     return value
    298 
    299 
    300 def _verify_exception_ceilings(category: str, exceptions: dict[str, int]) -> None:
    301     approved = APPROVED_EXCEPTIONS[category]
    302     for identity, ceiling in exceptions.items():
    303         if identity not in approved or ceiling > approved[identity]:
    304             raise MaintainabilityError(
    305                 "approved exception inventory or ceiling regressed"
    306             )
    307 
    308 
    309 def _verify_observed_metrics(
    310     baseline: dict[str, Any],
    311     observed: dict[str, dict[str, int]],
    312     thresholds: dict[str, int],
    313 ) -> None:
    314     specifications = (
    315         (
    316             "swift_file_exception",
    317             "path",
    318             "maximum_lines",
    319             "swift_lines",
    320             "swift_file_lines",
    321             "Swift file",
    322         ),
    323         (
    324             "python_file_exception",
    325             "path",
    326             "maximum_lines",
    327             "python_lines",
    328             "python_file_lines",
    329             "Python file",
    330         ),
    331         (
    332             "python_complexity_exception",
    333             "function",
    334             "maximum_complexity",
    335             "python_complexity",
    336             "python_function_complexity",
    337             "Python complexity",
    338         ),
    339     )
    340     for baseline_key, identity, ceiling, metric, threshold, label in specifications:
    341         exceptions = _closed_exception_map(
    342             baseline[baseline_key], key_name=identity, ceiling_name=ceiling
    343         )
    344         _verify_exception_ceilings(baseline_key, exceptions)
    345         _verify_metric(observed[metric], exceptions, thresholds[threshold], label)
    346 
    347 
    348 def _verify_bounded_modules(
    349     baseline: dict[str, Any],
    350     observed: dict[str, dict[str, int]],
    351     thresholds: dict[str, int],
    352 ) -> None:
    353     modules = baseline["bounded_module"]
    354     if not isinstance(modules, list) or modules != sorted(set(modules)):
    355         raise MaintainabilityError("bounded module inventory differs")
    356     if not ORIGINAL_BOUNDED_MODULES <= set(modules):
    357         raise MaintainabilityError("original bounded module inventory regressed")
    358     all_lines = observed["swift_lines"] | observed["python_lines"]
    359     for path in modules:
    360         if path not in all_lines:
    361             raise MaintainabilityError("bounded module is absent")
    362         limit = thresholds[
    363             "swift_file_lines" if path.endswith(".swift") else "python_file_lines"
    364         ]
    365         if all_lines[path] > limit:
    366             raise MaintainabilityError("bounded module exceeds its threshold")
    367 
    368 
    369 def verify(repo_root: Path) -> None:
    370     baseline = _load_baseline(repo_root)
    371     thresholds = _thresholds(baseline)
    372     observed = snapshot(repo_root)
    373     _verify_observed_metrics(baseline, observed, thresholds)
    374     _verify_bounded_modules(baseline, observed, thresholds)
    375 
    376 
    377 def main() -> int:
    378     parser = argparse.ArgumentParser()
    379     parser.add_argument("command", choices=("verify", "snapshot"))
    380     parser.add_argument(
    381         "--repo-root", type=Path, default=Path(__file__).resolve().parent.parent
    382     )
    383     arguments = parser.parse_args()
    384     try:
    385         if arguments.command == "snapshot":
    386             print(json.dumps(snapshot(arguments.repo_root.resolve()), sort_keys=True))
    387         else:
    388             verify(arguments.repo_root.resolve())
    389             print("maintainability ratchet verified")
    390     except MaintainabilityError as error:
    391         print(f"maintainability: {error}", file=sys.stderr)
    392         return 1
    393     return 0
    394 
    395 
    396 if __name__ == "__main__":
    397     raise SystemExit(main())