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())