Coverage for src/pullapprove/config.py: 94%

604 statements  

« prev     ^ index     » next       coverage.py v7.14.1, created at 2026-11-08 21:06 -0600

1from __future__ import annotations 

2 

3import os 

4import posixpath 

5import re 

6import tomllib 

7import warnings 

8 

9with warnings.catch_warnings(): 

10 warnings.simplefilter("ignore", DeprecationWarning) 

11 import sre_parse 

12from collections.abc import Generator, Iterable 

13from enum import StrEnum 

14from pathlib import Path 

15from typing import Any, Self 

16 

17from pydantic import ( 

18 BaseModel, 

19 ConfigDict, 

20 Field, 

21 RootModel, 

22 field_validator, 

23 model_validator, 

24) 

25from wcmatch import glob 

26 

27from .checklists import Checklist 

28 

29 

30def _resolve_config_filename_prefix() -> str: 

31 """The name every config file starts with, for this process. 

32 

33 Defaults to CODEREVIEW. An instance can rename it with 

34 PULLAPPROVE_CONFIG_PREFIX, which renames the config file itself 

35 (REVIEW -> REVIEW.toml, REVIEW.template.toml). Because discovery matches 

36 on this prefix, an instance only ever sees files named for its own prefix 

37 -- so two instances can watch the same repo without seeing each other's 

38 configs, which is how unreleased config features get tried out on a repo 

39 that production also watches. 

40 

41 Read once at import: this is a per-process constant, not runtime state. 

42 

43 Two operational constraints this doesn't (and can't) enforce: 

44 

45 Prefixes must not be prefixes of one another. Matching is `startswith` 

46 (see is_config_filename), and a suffix after the prefix is legitimate -- 

47 CODEREVIEW.template.toml and CODEREVIEW-BASE.toml are both real config 

48 names -- so a REVIEW instance would also pick up REVIEW_DEV.toml. An 

49 instance only knows its own prefix, so pick names that don't overlap 

50 (REVIEW and DEV_REVIEW, not REVIEW and REVIEW_DEV). 

51 

52 Changing the prefix on a live instance means clearing its cached configs. 

53 Config rows are keyed by (repo, sha) with no record of which prefix 

54 discovered them, so a sha already processed under the old prefix keeps 

55 serving from cache and the new prefix's files are never fetched. 

56 """ 

57 # `or` rather than a get() default: an explicitly empty value 

58 # (`PULLAPPROVE_CONFIG_PREFIX=` in a .env or compose file -- a normal way to 

59 # write "unset") is not a missing key, and would name the config ".toml". 

60 prefix = os.environ.get("PULLAPPROVE_CONFIG_PREFIX", "").strip() or "CODEREVIEW" 

61 

62 # A bad prefix would silently match nothing (i.e. every repo looks 

63 # unconfigured), so refuse to start instead. 

64 if prefix.endswith(".toml"): 

65 raise ValueError( 

66 f"PULLAPPROVE_CONFIG_PREFIX should be a name without an extension, not {prefix!r}. " 

67 f"The config file is named after it (e.g. {prefix[: -len('.toml')]!r} -> {prefix!r})." 

68 ) 

69 if "\\" in prefix or prefix != posixpath.basename(prefix): 

70 raise ValueError( 

71 f"PULLAPPROVE_CONFIG_PREFIX should be a filename prefix, not a path: {prefix!r}" 

72 ) 

73 

74 return prefix 

75 

76 

77CONFIG_FILENAME_PREFIX = _resolve_config_filename_prefix() 

78CONFIG_FILENAME = f"{CONFIG_FILENAME_PREFIX}.toml" 

79 

80 

81def is_config_filename(basename: str) -> bool: 

82 """Whether a filename is a config file (CODEREVIEW.toml, 

83 CODEREVIEW.template.toml). 

84 

85 The prefix half is what isolates instances: an instance running a renamed 

86 prefix (see PULLAPPROVE_CONFIG_PREFIX) never even discovers another 

87 instance's configs. The extension half keeps a neighbor like CODEREVIEW.md 

88 from being treated as one. 

89 """ 

90 return basename.startswith(CONFIG_FILENAME_PREFIX) and basename.endswith(".toml") 

91 

92 

93def is_config_path(path: str) -> bool: 

94 """Whether a repo-relative path names a config file.""" 

95 return is_config_filename(posixpath.basename(path)) 

96 

97 

98_REPEAT_OPS = {sre_parse.MAX_REPEAT, sre_parse.MIN_REPEAT} 

99 

100 

101def _has_nested_quantifiers(data: Any) -> bool: 

102 """Detect patterns like (a+)+ that cause catastrophic backtracking.""" 

103 for op, av in data: 

104 if op in _REPEAT_OPS: 

105 if _contains_quantifier(av[2]): 

106 return True 

107 elif op == sre_parse.SUBPATTERN: 

108 if _has_nested_quantifiers(av[-1]): 

109 return True 

110 elif op == sre_parse.BRANCH: # noqa: SIM102 

111 if any(_has_nested_quantifiers(branch) for branch in av[1]): 

112 return True 

113 return False 

114 

115 

116def _contains_quantifier(data: Any) -> bool: 

117 for op, av in data: 

118 if op in _REPEAT_OPS: 

119 return True 

120 elif op == sre_parse.SUBPATTERN: 

121 if _contains_quantifier(av[-1]): 

122 return True 

123 elif op == sre_parse.BRANCH: # noqa: SIM102 

124 if any(_contains_quantifier(branch) for branch in av[1]): 

125 return True 

126 return False 

127 

128 

129_TEAM_REF_SEGMENT = r"[a-zA-Z0-9][a-zA-Z0-9\-_.]*" 

130_TEAM_REF_RE = re.compile(rf"^{_TEAM_REF_SEGMENT}(/{_TEAM_REF_SEGMENT})+$") 

131 

132# Fields that hold reviewer identities (plain usernames, `$aliases`, and 

133# `@team` refs) rather than paths/code/labels. Team refs only expand here. 

134USER_LIST_FIELDS = ("authors", "reviewers", "alternates", "cc") 

135 

136# Roster fields where "!" performs compile-time subtraction (remove from the 

137# resolved list) rather than surviving as a match-time predicate. `authors` 

138# is deliberately excluded — its "!" entries are consumed by `matches_author`. 

139ROSTER_FIELDS = ("reviewers", "alternates", "cc") 

140 

141 

142def _split_team_ref(value: str) -> tuple[str, str] | None: 

143 """Split a value into `(prefix, ref)` if it has team-reference shape 

144 (`@org/team` or `!@org/team`), `prefix` being `"!"` or `""`. Returns 

145 `None` for anything else, so callers fall back to their own handling of 

146 plain values. 

147 """ 

148 if value.startswith("!@"): 

149 return "!", value[2:] 

150 if value.startswith("@"): 

151 return "", value[1:] 

152 return None 

153 

154 

155def is_unexpanded_ref(value: str) -> bool: 

156 """True if the value is a `$alias` or `@team` reference (optionally 

157 negated with a leading `!`) that has not been expanded — as opposed to a 

158 plain username. Only an offline compile (`teams=None`) leaves such values 

159 in user-list fields. 

160 """ 

161 return value.removeprefix("!").startswith(("$", "@")) 

162 

163 

164def _validate_team_refs(values: list[str]) -> list[str]: 

165 """Team references (`@org/team`, `!@org/team`) need at least two 

166 slash-separated segments. This only checks shape — membership is resolved 

167 later, at compile time, against the caller-provided `teams` mapping. 

168 

169 Any other value containing "@" is rejected too — that shape is reserved 

170 for team references (and, in future, email-style identifiers), so it 

171 can't be confused with a plain username. 

172 """ 

173 for value in values: 

174 split = _split_team_ref(value) 

175 if split is None: 

176 if "@" in value: 

177 raise ValueError( 

178 f"Invalid value '{value}': email addresses are not " 

179 "supported here — use the platform username" 

180 ) 

181 continue 

182 

183 _prefix, ref = split 

184 if not _TEAM_REF_RE.match(ref): 

185 raise ValueError( 

186 f"Invalid team reference '{value}': team references need the " 

187 "'org/team' form" 

188 ) 

189 return values 

190 

191 

192def _expand_team_ref( 

193 ref: str, teams: dict[str, list[str]] | None, prefix: str 

194) -> list[str]: 

195 """Expand a single team reference (without its `@`/`!@`) to member usernames. 

196 

197 `teams=None` is the offline/CLI mode: the library never calls out to 

198 GitHub/GitLab itself, so with no mapping provided the reference passes 

199 through unexpanded rather than erroring. With a `teams` mapping (even an 

200 empty one), an unresolvable ref is a loud config error, matching how 

201 unknown `$aliases` are handled. 

202 """ 

203 if teams is None: 

204 return [f"{prefix}@{ref}"] 

205 

206 members = teams.get(ref.lower()) 

207 if members is None: 

208 raise ValueError(f"Unknown team: {prefix}@{ref}") 

209 

210 return [f"{prefix}{member}" for member in members] 

211 

212 

213def _expand_aliases( 

214 values: list[str], 

215 aliases: dict[str, list[str]], 

216 teams: dict[str, list[str]] | None = None, 

217 expand_teams: bool = False, 

218 _seen: set[str] | None = None, 

219 _path: list[str] | None = None, 

220) -> list[str]: 

221 """Replace alias references in a list with their mapped values recursively. 

222 

223 Team references (`@org/team`) are only expanded when `expand_teams` is 

224 True — user-list fields (reviewers, alternates, authors, cc). Elsewhere 

225 (paths, code, labels) a leading `@` is a literal string, e.g. npm-style 

226 scoped path patterns like `@vendor/pkg/**`. Teams are always leaf nodes — 

227 their values are plain usernames, never other refs — so expanding one 

228 never recurses further. 

229 """ 

230 if _seen is None: 

231 _seen = set() 

232 if _path is None: 

233 _path = [] 

234 

235 expanded: list[str] = [] 

236 for value in values: 

237 # Support negated aliases like "!$team" -> ["!alice", "!bob"] 

238 if value.startswith("!$"): 

239 prefix = "!" 

240 alias_ref = value[2:] 

241 elif value.startswith("$"): 

242 prefix = "" 

243 alias_ref = value[1:] 

244 elif expand_teams and (team_ref := _split_team_ref(value)) is not None: 

245 team_prefix, ref = team_ref 

246 expanded.extend(_expand_team_ref(ref=ref, teams=teams, prefix=team_prefix)) 

247 continue 

248 else: 

249 expanded.append(value) 

250 continue 

251 

252 if alias_ref in _seen: 

253 # Cycle detected, raise an error with the cycle path 

254 cycle_path = _path[_path.index(alias_ref) :] + [alias_ref] 

255 raise ValueError( 

256 f"Circular reference detected in aliases: {' -> '.join(cycle_path)}" 

257 ) 

258 if alias_ref in aliases: 

259 _seen.add(alias_ref) 

260 _path.append(alias_ref) 

261 # Recursively expand the alias values 

262 nested_expanded = _expand_aliases( 

263 aliases[alias_ref], 

264 aliases=aliases, 

265 teams=teams, 

266 expand_teams=expand_teams, 

267 _seen=_seen, 

268 _path=_path, 

269 ) 

270 if prefix: 

271 expanded.extend(prefix + v for v in nested_expanded) 

272 else: 

273 expanded.extend(nested_expanded) 

274 _path.pop() 

275 _seen.remove(alias_ref) 

276 else: 

277 # Unknown alias — surface it loudly instead of silently dropping the 

278 # reference (a typo'd alias would otherwise vanish reviewers/paths). 

279 raise ValueError(f"Unknown alias: {prefix}${alias_ref}") 

280 

281 # Remove duplicates while preserving order 

282 return list(dict.fromkeys(expanded)) 

283 

284 

285def _apply_negations(values: list[str]) -> list[str]: 

286 """Compile-time subtraction for roster fields (`ROSTER_FIELDS`): a "!name" 

287 entry removes "name" from the resolved list instead of surviving as a 

288 match-time rule (contrast `authors`, handled by `matches_author`). 

289 

290 A list still holding an unexpanded `@team` ref (offline compile, i.e. 

291 teams=None) is returned untouched — it isn't fully resolved yet, so 

292 subtraction can't run, and the partially-resolved config must round-trip 

293 unchanged. `$aliases` must already be expanded by the caller. 

294 

295 The wildcard+negation error fires BEFORE that early return: it's a check 

296 on the written form (`"*"` alongside any `"!"` entry, team ref or not), 

297 so an offline compile must reject it the same way the server will — a 

298 `pullapprove check` that passes locally can't then error in production. 

299 """ 

300 if "*" in values and any(v.startswith("!") for v in values): 

301 raise ValueError( 

302 'Negation cannot be combined with "*" in reviewers/alternates/cc ' 

303 "(wildcard exclusion is not supported)" 

304 ) 

305 

306 if any(_split_team_ref(v) is not None for v in values): 

307 return values 

308 

309 negations = {v[1:].lower() for v in values if v.startswith("!")} 

310 return [v for v in values if not v.startswith("!") and v.lower() not in negations] 

311 

312 

313def _validate_review_counts(label: str, data: dict[str, Any]) -> None: 

314 """Compile-time rejection of negative require/request/author_value. 

315 Shared by scopes and large_scale_change (which has no author_value — 

316 the `.get` default passes trivially there). 

317 

318 These are compile-time checks (not field validators) because negative 

319 values were previously accepted, so compiled configs stored inside old 

320 processing results must keep parsing (where they keep their old 

321 behavior: a negative require always passed, a negative request 

322 requested nobody). 

323 """ 

324 for field in ("require", "request", "author_value"): 

325 if data.get(field, 0) < 0: 

326 raise ValueError(f"{label}: {field} cannot be negative") 

327 

328 

329def _validate_global_require(*, label: str, scope: dict[str, Any]) -> None: 

330 """Global scopes need require >= 1: a satisfied global scope passes every 

331 file it matches, and require = 0 (the default) is satisfied before anyone 

332 reviews. Compile-time, like _validate_review_counts, so compiled configs 

333 stored inside old processing results keep parsing. 

334 """ 

335 if ( 

336 scope.get("ownership") == OwnershipChoices.GLOBAL 

337 and scope.get("require", 0) < 1 

338 ): 

339 raise ValueError( 

340 f"{label}: global scopes need require >= 1 " 

341 "(0 would pass every file it matches)" 

342 ) 

343 

344 

345# How directly a config points at a person, most specific first. Which one 

346# wins is decided in `_resolve_reviewer_alternate_overlap`. 

347_MENTIONED_BY_USERNAME = 3 

348_MENTIONED_BY_ALIAS = 2 

349_MENTIONED_BY_TEAM = 1 

350 

351 

352def _mentions_by_username_or_alias( 

353 values: list[str], *, aliases: dict[str, list[str]] 

354) -> dict[str, int]: 

355 """Each login a user list, as written, mentions by username or through an 

356 alias, keyed by lowercased login, with its most specific mention. 

357 

358 Team refs are skipped, whether written in the field or inside an alias: 

359 a team mention is the lowest level, so it never needs looking up. Negated 

360 entries are subtractions, not mentions. 

361 """ 

362 flattened: list[tuple[str, int]] = [] 

363 for value in values: 

364 if value.startswith("$"): 

365 # An alias flattens to usernames, plus any team refs and 

366 # negations written inside it. 

367 flattened.extend( 

368 (alias_value, _MENTIONED_BY_ALIAS) 

369 for alias_value in _expand_aliases([value], aliases) 

370 ) 

371 else: 

372 flattened.append((value, _MENTIONED_BY_USERNAME)) 

373 

374 mentions: dict[str, int] = {} 

375 for value, level in flattened: 

376 if value.startswith("!") or _split_team_ref(value) is not None: 

377 continue 

378 key = value.lower() 

379 mentions[key] = max(mentions.get(key, 0), level) 

380 return mentions 

381 

382 

383def _resolve_reviewer_alternate_overlap( 

384 *, 

385 entry: dict[str, Any], 

386 written: dict[str, list[str]], 

387 aliases: dict[str, list[str]], 

388) -> None: 

389 """Someone in both `reviewers` and `alternates` is requested only if 

390 `reviewers` mentions them at least as specifically as `alternates` does: 

391 a username beats an alias, an alias beats a team, and a tie leaves them 

392 a reviewer. Whoever `alternates` outranks is dropped from the compiled 

393 `reviewers`, so for this scope they are an alternate: they count, but 

394 are never requested. 

395 

396 The compiled lists decide who is in both. `written`, the two fields 

397 before expansion, decides how specifically each one mentions them. An 

398 unexpanded team ref left by an offline compile is not a login, so it is 

399 never dropped. 

400 """ 

401 if not entry.get("reviewers") or not entry.get("alternates"): 

402 return 

403 

404 reviewer_mentions = _mentions_by_username_or_alias( 

405 written["reviewers"], aliases=aliases 

406 ) 

407 alternate_mentions = _mentions_by_username_or_alias( 

408 written["alternates"], aliases=aliases 

409 ) 

410 

411 # A reviewer with no username or alias mention got there through a team. 

412 # Only a username or alias mention in `alternates` can outrank that. 

413 compiled_alternates = {login.lower() for login in entry["alternates"]} 

414 outranked = { 

415 login 

416 for login, level in alternate_mentions.items() 

417 if login in compiled_alternates 

418 and level > reviewer_mentions.get(login, _MENTIONED_BY_TEAM) 

419 } 

420 if not outranked: 

421 return 

422 

423 entry["reviewers"] = [ 

424 login for login in entry["reviewers"] if login.lower() not in outranked 

425 ] 

426 

427 

428def _compile_review_fields( 

429 *, 

430 entry: dict[str, Any], 

431 label: str, 

432 aliases: dict[str, list[str]], 

433 teams: dict[str, list[str]] | None, 

434) -> None: 

435 """Compile a raw scope, or the large-scale change, in place: expand 

436 aliases, apply "!" subtraction, reject what can never work, and settle 

437 who is both a reviewer and an alternate. Only the fields the entry has 

438 are touched. `label` names it in error messages ("Scope 'app'", 

439 "large_scale_change"). 

440 """ 

441 # Reviewers and alternates as written: once expanded, a list no longer 

442 # says whether a login was typed in or came from an alias or a team. 

443 written = { 

444 field: entry[field] for field in ("reviewers", "alternates") if field in entry 

445 } 

446 

447 # Team refs only expand in user-list fields — paths/code/labels keep a 

448 # leading "@" literal. 

449 for field in ( 

450 "paths", 

451 "code", 

452 "authors", 

453 "reviewers", 

454 "alternates", 

455 "cc", 

456 "labels", 

457 ): 

458 if field in entry: 

459 entry[field] = _expand_aliases( 

460 entry[field], 

461 aliases, 

462 teams=teams, 

463 expand_teams=field in USER_LIST_FIELDS, 

464 ) 

465 

466 # Apply compile-time "!" subtraction to roster fields. 

467 # `_apply_negations` leaves a field with an unexpanded team ref 

468 # (offline compile, i.e. teams=None) untouched. 

469 for field in ROSTER_FIELDS: 

470 if field in entry: 

471 entry[field] = _apply_negations(entry[field]) 

472 _reject_bot_reviewers(entry[field], where=f"{label} {field}") 

473 

474 # The "*" wildcard is only meaningful in `reviewers` — everywhere 

475 # else it's matched as a literal username and silently does 

476 # nothing: in `alternates` the scope stays pending forever, in 

477 # `authors` the scope never applies to any PR, in `cc` nobody is 

478 # notified. Reject it at compile time (after alias expansion, so 

479 # `$alias` indirection can't smuggle it in) rather than as a 

480 # ScopeModel validator, because compiled configs stored inside 

481 # old processing results must keep parsing. 

482 # Messages must stay under ~130 chars: they become the git-host 

483 # commit status description, which the adapters slice to 140. 

484 for field, hint in ( 

485 ( 

486 "authors", 

487 "remove it (a scope with no authors applies to any author)", 

488 ), 

489 ( 

490 "alternates", 

491 "add it to reviewers instead (wildcard reviewers are never auto-requested)", 

492 ), 

493 ("cc", "remove it"), 

494 ): 

495 if "*" in entry.get(field, []): 

496 raise ValueError(f'{label}: "*" is not supported in {field} — {hint}') 

497 

498 _validate_review_counts(label, entry) 

499 

500 _resolve_reviewer_alternate_overlap(entry=entry, written=written, aliases=aliases) 

501 

502 

503def _roster_shortfall( 

504 *, reviewers: list[str], alternates: list[str], require: int 

505) -> str | None: 

506 """Why `require` approvals can never come from these reviewers and 

507 alternates, or None if they can.""" 

508 all_reviewers = reviewers + alternates 

509 

510 # Skip if wildcard - anyone can review 

511 if "*" in all_reviewers: 

512 return None 

513 

514 # Skip if aliases or team refs (possibly negated with "!") are not yet 

515 # expanded. Re-validation after compilation only re-checks refs that 

516 # actually resolve — an offline compile (teams=None) leaves refs 

517 # unexpanded, so this same skip fires again there too. 

518 if any(is_unexpanded_ref(r) for r in all_reviewers): 

519 return None 

520 

521 if len(all_reviewers) < require: 

522 return f"has require={require} but only {len(all_reviewers)} reviewers/alternates specified" 

523 

524 return None 

525 

526 

527def _resolve_extends_path(extending_path: str, extends_ref: str) -> str: 

528 """Resolve an `extends` reference to a canonical repo-relative config key. 

529 

530 - `/x` is repo-root-relative. 

531 - everything else (`../x`, `dir/x`, bare `x`) is relative to the extending 

532 file's directory. 

533 

534 Raises if the reference escapes above the repo root. 

535 """ 

536 if extends_ref.startswith("/"): 

537 resolved = posixpath.normpath(extends_ref.lstrip("/")) 

538 else: 

539 base_dir = posixpath.dirname(extending_path) 

540 resolved = posixpath.normpath(posixpath.join(base_dir, extends_ref)) 

541 

542 if resolved == ".." or resolved.startswith("../"): 

543 raise ValueError( 

544 f"Invalid extends path: '{extends_ref}' points above the repo root" 

545 ) 

546 

547 return resolved 

548 

549 

550def scope_line_range(*, content: str, scope_name: str) -> tuple[int, int] | None: 

551 """The first and last line (1-indexed) of the `[[scopes]]` table that 

552 declares a scope, or None when it isn't written as its own table (an 

553 inline `scopes = [...]`, say). 

554 

555 TOML parsers don't report positions, so this splits the text at its table 

556 headers and parses each `[[scopes]]` block on its own. 

557 """ 

558 # Only `\n` ends a line, as in git and editors (`splitlines` also splits 

559 # on characters like U+2028). 

560 lines = content.split("\n") 

561 

562 # Every table header starts a block, except a scope's own sub-tables 

563 # (`[[scopes.checklist.items]]`), which belong to the scope above them. A 

564 # line inside a multi-line string is never a header, whatever it starts 

565 # with. 

566 block_starts = [ 

567 index 

568 for index, starts_outside in enumerate(_lines_outside_strings(lines)) 

569 if starts_outside 

570 and _table_header(lines[index]) 

571 and not _table_header(lines[index]).startswith(("[scopes.", "[[scopes.")) 

572 ] 

573 block_ends = block_starts[1:] + [len(lines)] 

574 

575 for start, end in zip(block_starts, block_ends): 

576 if not _table_header(lines[start]).startswith("[[scopes]]"): 

577 continue 

578 try: 

579 block = tomllib.loads("\n".join(lines[start:end])) 

580 except tomllib.TOMLDecodeError: 

581 continue 

582 if block["scopes"][0].get("name") != scope_name: 

583 continue 

584 

585 # Blank lines and comments at the end lead into the next table. 

586 while end > start + 1 and ( 

587 not lines[end - 1].strip() or lines[end - 1].lstrip().startswith("#") 

588 ): 

589 end -= 1 

590 return start + 1, end 

591 

592 return None 

593 

594 

595def _table_header(line: str) -> str: 

596 """A table header line without the whitespace and quotes TOML allows in 

597 it (`[[ "scopes" ]]` is `[[scopes]]`), or "" for any other line.""" 

598 stripped = line.strip() 

599 if not stripped.startswith("["): 

600 return "" 

601 return re.sub(r"[\s\"']", "", stripped) 

602 

603 

604def _lines_outside_strings(lines: list[str]) -> list[bool]: 

605 """For each line, whether it starts outside a multi-line string. Comments 

606 and single-line strings are skipped, so a `\"\"\"` inside one of them 

607 doesn't open anything.""" 

608 starts_outside = [] 

609 open_multiline = "" # `"""` or `'''` while inside one 

610 for line in lines: 

611 starts_outside.append(not open_multiline) 

612 index = 0 

613 while index < len(line): 

614 if open_multiline == '"""': 

615 if line[index] == "\\": 

616 index += 2 

617 elif line.startswith('"""', index): 

618 open_multiline = "" 

619 # Up to two quotes may sit right before the delimiter. 

620 while line.startswith('"', index + 3): 

621 index += 1 

622 index += 3 

623 else: 

624 index += 1 

625 elif open_multiline == "'''": 

626 close = line.find("'''", index) 

627 if close == -1: 

628 break 

629 open_multiline = "" 

630 index = close + 3 

631 while line.startswith("'", index): 

632 index += 1 

633 elif line.startswith(('"""', "'''"), index): 

634 open_multiline = line[index : index + 3] 

635 index += 3 

636 elif line[index] == "#": 

637 break 

638 elif line[index] == '"': 

639 # A basic string ends at the next unescaped quote. 

640 index += 1 

641 while index < len(line) and line[index] != '"': 

642 index += 2 if line[index] == "\\" else 1 

643 index += 1 

644 elif line[index] == "'": 

645 # A literal string has no escapes. 

646 close = line.find("'", index + 1) 

647 index = len(line) if close == -1 else close + 1 

648 else: 

649 index += 1 

650 return starts_outside 

651 

652 

653def matches_path_patterns(*, path: Path, patterns: list[str]) -> bool: 

654 """Whether `path` matches any of the config's path globs. 

655 

656 The one definition of the config's glob semantics. 

657 """ 

658 # TODO paths shouldn't start with / 

659 return glob.globmatch( 

660 path, 

661 patterns, 

662 flags=glob.GLOBSTAR | glob.BRACE | glob.NEGATE | glob.IGNORECASE | glob.DOTGLOB, 

663 ) 

664 

665 

666def _anchor_path(base_dir: str, pattern: str) -> str: 

667 """Anchor a scope path glob at `base_dir` (the owning config's directory). 

668 

669 Scope paths are written relative to the config they live in. A leading `/` 

670 makes a pattern repo-root-absolute (escape hatch); a leading `!` negation is 

671 preserved. With an empty `base_dir` (root config) the pattern is unchanged. 

672 """ 

673 negate = pattern.startswith("!") 

674 if negate: 

675 pattern = pattern[1:] 

676 

677 if pattern.startswith("/"): 

678 anchored = pattern.lstrip("/") 

679 elif base_dir: 

680 anchored = f"{base_dir}/{pattern}" 

681 else: 

682 anchored = pattern 

683 

684 return f"!{anchored}" if negate else anchored 

685 

686 

687class OwnershipChoices(StrEnum): 

688 EMPTY = "" 

689 APPEND = "append" 

690 GLOBAL = "global" 

691 

692 

693# A GitHub App has two names: the login it posts as (`name[bot]`) and the slug 

694# that owns its check runs (`name`). The suffix is how the engine tells a bot 

695# from a person -- a `[bot]` account never counts as a human and never sits in 

696# a roster, no declaration needed. 

697BOT_LOGIN_SUFFIX = "[bot]" 

698 

699 

700def is_bot_login(username: str) -> bool: 

701 """The engine rule, in one place: a `[bot]` account is never a person.""" 

702 return username.lower().endswith(BOT_LOGIN_SUFFIX) 

703 

704 

705def _split_check_ref(ref: str) -> tuple[str, str]: 

706 """An `unless` ref as (producer slug lowercased, check name). 

707 

708 Split on the FIRST `/`: App slugs cannot contain one, check names can. 

709 Both parts are stripped -- the validator checks THIS function's output, so 

710 a ref that validates is exactly a ref that matches at runtime. 

711 """ 

712 producer, _, name = ref.partition("/") 

713 return producer.strip().lower(), name.strip() 

714 

715 

716def _reject_bot_reviewers(values: list[str], *, where: str) -> None: 

717 """Reject any `[bot]` account listed in a roster surface (a scope's 

718 reviewers/alternates/cc, or large_scale_change.reviewers/alternates). 

719 

720 A bot is never a person, so it can never sit in a roster: bots that open 

721 pull requests are routed with `authors`, and bots that attest are 

722 referenced from `unless`. Checked after alias expansion so `$alias` 

723 indirection can't smuggle one in. `where` names the surface; the message 

724 becomes the git-host commit status, so it stays under ~130 chars. 

725 """ 

726 for entry in values: 

727 if is_bot_login(entry): 

728 raise ValueError( 

729 f"{where}: '{entry}' is a bot and cannot be listed as a reviewer" 

730 ) 

731 

732 

733def _first_case_insensitive_duplicate(values: Iterable[str]) -> str | None: 

734 """The first value whose lowercased form was already seen, else None.""" 

735 seen: set[str] = set() 

736 for value in values: 

737 if value.lower() in seen: 

738 return value 

739 seen.add(value.lower()) 

740 return None 

741 

742 

743class ScopeModel(BaseModel): 

744 model_config = ConfigDict(extra="forbid") 

745 

746 # Required fields 

747 name: str = Field(min_length=1) 

748 paths: list[str] = Field(min_length=1) 

749 

750 # Optional fields 

751 

752 # Expanded version of lines could be dict 

753 # with fnmatch, regex, exclude patterns, etc? 

754 code: list[str] = [] 

755 

756 # This only filtering field that can't be used with raw diff/files... 

757 # If we get into that, the others are: 

758 # - labels 

759 # - ref 

760 # - statuses 

761 # - dates 

762 # - body 

763 # - title 

764 # - other scopes 

765 # (this is how I ended up with expressions... 

766 # I'm not trying to build a general purpose workflow tool, 

767 # but I do need to support the legit use cases and AI/bot review is one, so is team hierarchy) 

768 authors: list[str] = [] 

769 

770 # (defaults should be the "empty" values) 

771 description: str = "" 

772 reviewers: list[str] = [] 

773 alternates: list[str] = [] 

774 cc: list[str] = [] 

775 

776 # Review scoring 

777 # Negative values are rejected at compile time (_validate_review_counts) 

778 require: int = 0 

779 author_value: int = 0 

780 

781 # The checks that can attest this scope's review requirement away. Each ref 

782 # is "producer/check-name" -- the slug of the App that produces the check, 

783 # then the check run's name, split on the first "/". When every listed 

784 # check has completed successfully on the current head commit, the scope is 

785 # waived: its requirement drops to zero and the evidence is stored on the 

786 # result. Failed, skipped, pending, missing -- the requirement stands 

787 # unchanged; passing is the only state that subtracts. 

788 # 

789 # Deliberately placed next to the `require` it undermines, so reading a 

790 # scope always reveals whether its human review is removable. A list is 

791 # implicitly "all must pass" -- OR, thresholds, and 2-of-3 belong in the 

792 # producer, which can post one combined check. 

793 unless: list[str] = [] 

794 

795 # How scopes are combined 

796 ownership: OwnershipChoices = OwnershipChoices.EMPTY 

797 

798 # Actionable items 

799 request: int = 0 

800 labels: list[str] = [] 

801 instructions: str = "" 

802 

803 # Approval checklist 

804 checklist: Checklist | None = None 

805 

806 @field_validator("name", mode="after") 

807 @classmethod 

808 def validate_name(cls, name: str) -> str: 

809 if "," in name: 

810 raise ValueError("Scope name cannot contain commas") 

811 return name 

812 

813 @field_validator(*USER_LIST_FIELDS, mode="after") 

814 @classmethod 

815 def validate_team_ref_shape(cls, values: list[str]) -> list[str]: 

816 return _validate_team_refs(values) 

817 

818 @field_validator("unless", mode="after") 

819 @classmethod 

820 def validate_unless_refs(cls, values: list[str]) -> list[str]: 

821 """A check name alone is worthless -- any workflow with `checks: write` 

822 can post any name -- so a bare name is a parse error, not a default. 

823 Messages stay under ~130 chars: they become the git-host commit status. 

824 """ 

825 for ref in values: 

826 producer, name = _split_check_ref(ref) 

827 if "/" not in ref or not producer or not name: 

828 raise ValueError( 

829 f"unless: '{ref}' must be 'producer/check-name' -- the App " 

830 "slug that produces the check, then the check's name" 

831 ) 

832 # To most users PullApprove *is* "the check" on their PRs. 

833 # PullApprove never creates these checks, it only reads them -- and 

834 # a config waiting on our own status would deadlock politely. 

835 if producer == "pullapprove": 

836 raise ValueError( 

837 f"unless: '{ref}' references PullApprove itself -- " 

838 "PullApprove never creates checks, it only reads them" 

839 ) 

840 return values 

841 

842 @field_validator("code", mode="after") 

843 @classmethod 

844 def validate_code_patterns(cls, code: list[str]) -> list[str]: 

845 for pattern in code: 

846 try: 

847 parsed = sre_parse.parse(pattern) 

848 except re.error as e: 

849 raise ValueError(f"Invalid regex pattern '{pattern}': {e}") from None 

850 if _has_nested_quantifiers(parsed): 

851 raise ValueError( 

852 f"Regex pattern '{pattern}' contains nested quantifiers, " 

853 "which can cause catastrophic backtracking." 

854 ) 

855 return code 

856 

857 @model_validator(mode="after") 

858 def validate_reviewers_for_require(self) -> ScopeModel: 

859 if reason := _roster_shortfall( 

860 reviewers=self.reviewers, 

861 alternates=self.alternates, 

862 require=self.require, 

863 ): 

864 raise ValueError(reason) 

865 return self 

866 

867 def named_usernames(self) -> set[str]: 

868 """Everyone in `reviewers` or `alternates`, lowercased because every 

869 username comparison here is case-insensitive. A "*" entry is kept as 

870 is; it never matches a real username.""" 

871 return {r.lower() for r in self.reviewers + self.alternates} 

872 

873 def counts_toward(self, username: str) -> bool: 

874 """Whether this person's review counts for this scope. 

875 

876 Everyone it names, plus everybody when `reviewers` holds the 

877 wildcard. A wildcard in `alternates` does not count everybody: the 

878 wildcard describes the scope's `reviewers`, not its backups. 

879 """ 

880 if "*" in self.reviewers: 

881 return True 

882 return username.lower() in self.named_usernames() 

883 

884 def author_points(self, author_username: str) -> int: 

885 """`author_value` if the scope names the author, reviewer or 

886 alternate. Being covered by the wildcard earns nothing.""" 

887 if author_username.lower() in self.named_usernames(): 

888 return self.author_value 

889 return 0 

890 

891 def unless_refs(self) -> list[tuple[str, str]]: 

892 """Each `unless` entry as (producer slug lowercased, check name).""" 

893 return [_split_check_ref(ref) for ref in self.unless] 

894 

895 def unsolvable_reason(self, author_username: str) -> str | None: 

896 """ 

897 Explain why this scope can never pass for a PR authored by this user, 

898 or None if it can. 

899 

900 Messages must stay under ~130 chars: they flow into the git-host 

901 commit status description, which the adapters slice to 140. 

902 """ 

903 if "*" in self.reviewers: 

904 # Anyone can review, so any require is satisfiable 

905 return None 

906 

907 # Count eligible reviewers (excluding author who can't self-approve) 

908 eligible_reviewers = self.named_usernames() - {author_username.lower()} 

909 max_possible_points = len(eligible_reviewers) + self.author_points( 

910 author_username 

911 ) 

912 

913 if self.require > 0 and max_possible_points < self.require: 

914 if not eligible_reviewers: 

915 return ( 

916 "PR author is the only reviewer/alternate and cannot self-approve" 

917 ) 

918 return f"require={self.require} but only {max_possible_points} possible approvals (excluding author)" 

919 

920 return None 

921 

922 def ownership_marker(self) -> str: 

923 """The glyph a non-default ownership puts in front of the scope name. 

924 

925 Split out from printed_name so a renderer that styles the marker apart 

926 from the name doesn't have to know which glyph goes with which mode. 

927 """ 

928 match self.ownership: 

929 case OwnershipChoices.APPEND: 

930 return "+" 

931 case OwnershipChoices.GLOBAL: 

932 return "*" 

933 

934 return "" 

935 

936 def printed_name(self) -> str: 

937 return self.ownership_marker() + self.name 

938 

939 def __eq__(self, other: object) -> bool: 

940 if not isinstance(other, ScopeModel): 

941 return NotImplemented 

942 return self.name == other.name 

943 

944 def matches_path(self, path: Path) -> bool: 

945 return matches_path_patterns(path=path, patterns=self.paths) 

946 

947 def matches_code(self, code: str) -> Generator[dict[str, int]]: 

948 patterns = getattr(self, "_code_regex_patterns", []) 

949 if not patterns: 

950 patterns = [re.compile(pattern, re.MULTILINE) for pattern in self.code] 

951 self._code_regex_patterns = patterns 

952 

953 for pattern in patterns: 

954 for match in pattern.finditer(code): 

955 start_index = match.start() 

956 end_index = match.end() 

957 

958 start_line = code.count("\n", 0, start_index) + 1 

959 start_col = start_index - code.rfind("\n", 0, start_index) 

960 

961 end_line = code.count("\n", 0, end_index) + 1 

962 end_col = end_index - code.rfind("\n", 0, end_index) 

963 

964 yield { 

965 "start_line": start_line, 

966 "start_col": start_col, 

967 "end_line": end_line, 

968 "end_col": end_col, 

969 } 

970 

971 def matches_author(self, author_username: str) -> bool: 

972 if not self.authors: 

973 # No authors specified, so assume it matches 

974 return True 

975 

976 # An offline compile (teams=None) leaves `@org/team` refs as written, 

977 # and comparing a username to one would quietly give the wrong answer 

978 for author in self.authors: 

979 if is_unexpanded_ref(author): 

980 raise ValueError( 

981 f"Scope {self.name} lists {author} in authors, " 

982 "and its members haven't been looked up" 

983 ) 

984 

985 author_username_lower = author_username.lower() 

986 

987 negated_authors = [a[1:].lower() for a in self.authors if a.startswith("!")] 

988 authors = [a.lower() for a in self.authors if not a.startswith("!")] 

989 

990 if author_username_lower in negated_authors: 

991 # If the author is in the negated list, return False 

992 return False 

993 

994 if not authors: 

995 # Negation-only: everyone not negated matches 

996 return True 

997 

998 return author_username_lower in authors 

999 

1000 

1001# The scope a large-scale change is reviewed as (LargeScaleChangeModel.as_scope). 

1002LARGE_SCALE_CHANGE_SCOPE_NAME = "Large-scale change" 

1003 

1004 

1005class LargeScaleChangeModel(BaseModel): 

1006 model_config = ConfigDict(extra="forbid") 

1007 

1008 # Note, an LSC only applies to diffs, not raw files, 

1009 # because we have to know what *changed*. 

1010 

1011 # Reviewed as a scope (see as_scope), so each field means what it means 

1012 # on a scope. There has to be at least one reviewer, so a PR that turns 

1013 # out to be an LSC errors until the config names some. 

1014 # Negative values are rejected at compile time (_validate_review_counts) 

1015 require: int = 1 

1016 request: int = 0 

1017 reviewers: list[str] = [] 

1018 alternates: list[str] = [] 

1019 # min_paths: int = 300 

1020 # min_lines: int = 3000 

1021 labels: list[str] = [] 

1022 

1023 @field_validator("reviewers", "alternates", mode="after") 

1024 @classmethod 

1025 def validate_team_ref_shape(cls, values: list[str]) -> list[str]: 

1026 return _validate_team_refs(values) 

1027 

1028 def as_scope(self) -> ScopeModel: 

1029 """The scope a large-scale change is reviewed as, in place of the 

1030 scopes its diff was too large to match. It covers every path, and is 

1031 scored, requested and shown like any other scope. 

1032 

1033 Raises ValueError when no set of reviewers could ever approve it. 

1034 Messages must stay under ~130 chars: they become the git-host commit 

1035 status description. 

1036 """ 

1037 # A scope can get by on alternates alone, so this can too. 

1038 if not self.reviewers and not self.alternates: 

1039 raise ValueError( 

1040 "Large-scale change: configuration required (no reviewers defined)" 

1041 ) 

1042 

1043 # ScopeModel rejects this too, but its message wouldn't say where the 

1044 # problem is. 

1045 if reason := _roster_shortfall( 

1046 reviewers=self.reviewers, 

1047 alternates=self.alternates, 

1048 require=self.require, 

1049 ): 

1050 raise ValueError(f"Large-scale change: {reason}") 

1051 

1052 return ScopeModel( 

1053 name=LARGE_SCALE_CHANGE_SCOPE_NAME, 

1054 paths=["**/*"], 

1055 reviewers=self.reviewers, 

1056 alternates=self.alternates, 

1057 require=self.require, 

1058 request=self.request, 

1059 labels=self.labels, 

1060 ) 

1061 

1062 

1063class ConfigModel(BaseModel): 

1064 model_config = ConfigDict(extra="forbid") 

1065 

1066 # Nothing is technically required 

1067 extends: list[str] = [] 

1068 template: bool = False 

1069 aliases: dict[str, list[str]] = {} 

1070 large_scale_change: LargeScaleChangeModel | None = None 

1071 scopes: list[ScopeModel] = [] 

1072 

1073 @field_validator("scopes", mode="after") 

1074 @classmethod 

1075 def validate_unique_scope_names(cls, scopes: list[ScopeModel]) -> list[ScopeModel]: 

1076 if dup := _first_case_insensitive_duplicate(scope.name for scope in scopes): 

1077 raise ValueError(f"Duplicate scope name: {dup}") 

1078 return scopes 

1079 

1080 @field_validator("extends", mode="before") 

1081 @classmethod 

1082 def validate_extends(cls, extends: list[str]) -> list[str]: 

1083 for i, path in enumerate(extends): 

1084 basename = Path(path).name 

1085 if not basename.startswith(CONFIG_FILENAME_PREFIX): 

1086 raise ValueError( 

1087 f"Invalid extends path: {path}. It should start with '{CONFIG_FILENAME_PREFIX}'." 

1088 ) 

1089 return extends 

1090 

1091 def compiled_config( 

1092 self, 

1093 config_path: Path, 

1094 other_configs: ConfigModels, 

1095 teams: dict[str, list[str]] | None = None, 

1096 ) -> ConfigModel: 

1097 """ 

1098 Resolve `extends` and replace aliases, returning the effective config. 

1099 

1100 Two phases: flatten the whole extends chain into one merged (raw, 

1101 unexpanded) config, then expand aliases once. Expanding after the full 

1102 merge is what makes transitive inheritance and cross-chain alias 

1103 scoping work — an alias defined anywhere in the chain resolves anywhere. 

1104 

1105 `teams` maps team refs (any case, without the leading `@`) to member 

1106 usernames, and is only consulted for user-list fields (reviewers, 

1107 alternates, authors, cc, large_scale_change.reviewers/alternates). Keys are 

1108 lowercased here, so callers don't need to normalize case themselves. 

1109 With `teams=None` (the default), `@org/team` references in those 

1110 fields pass through unexpanded — the offline/CLI mode, since this 

1111 library never calls out to GitHub/GitLab itself. That 

1112 partially-resolved config is only sanctioned for offline use; 

1113 anything that needs real reviewer usernames must pass a `teams` 

1114 mapping. 

1115 

1116 Pure function of the raw `self` and `other_configs` (it never reads its 

1117 own anchored output), so it is safe to call uncached. 

1118 """ 

1119 

1120 if teams is not None: 

1121 teams = {key.lower(): members for key, members in teams.items()} 

1122 

1123 compiled_data = self._merged_data(config_path, other_configs) 

1124 

1125 # A large-scale change is reviewed as a scope, so it compiles by a 

1126 # scope's rules. 

1127 for scope in compiled_data["scopes"]: 

1128 label = f"Scope '{scope['name']}'" 

1129 _compile_review_fields( 

1130 entry=scope, 

1131 label=label, 

1132 aliases=compiled_data["aliases"], 

1133 teams=teams, 

1134 ) 

1135 _validate_global_require(label=label, scope=scope) 

1136 if large_scale_change := compiled_data.get("large_scale_change"): 

1137 _compile_review_fields( 

1138 entry=large_scale_change, 

1139 label="large_scale_change", 

1140 aliases=compiled_data["aliases"], 

1141 teams=teams, 

1142 ) 

1143 

1144 # Anchor each scope's paths at the directory tagged during flattening 

1145 # (after alias expansion, so any `$path-alias` is resolved first). The 

1146 # transient tag is popped so it never reaches the model. 

1147 # Paths are relative to the config that owns the scope, `/` for 

1148 # repo-root-absolute. 

1149 for entry in compiled_data["scopes"]: 

1150 anchor_dir = entry.pop("_anchor_dir", "") 

1151 entry["paths"] = [_anchor_path(anchor_dir, p) for p in entry["paths"]] 

1152 entry.pop("_declared_in", None) 

1153 

1154 # The compiled config is the self-contained effective config: extends 

1155 # are already merged in and aliases already expanded, so drop both. This 

1156 # keeps stored results lean and makes the compiled form standalone (it 

1157 # can never dangle on a missing extends target or re-expand differently). 

1158 compiled_data["extends"] = [] 

1159 compiled_data["aliases"] = {} 

1160 

1161 return ConfigModel.from_data( 

1162 data=compiled_data, 

1163 path=config_path, 

1164 ) 

1165 

1166 def _merged_data( 

1167 self, 

1168 config_path: Path, 

1169 other_configs: ConfigModels, 

1170 _in_progress: list[str] | None = None, 

1171 _seen: set[str] | None = None, 

1172 ) -> dict[str, Any]: 

1173 """ 

1174 Flatten the `extends` chain into one merged, *unexpanded* config dict. 

1175 

1176 Parents are merged before this config (so a child can specialize), with 

1177 aliases unioned child-wins and the large-scale-change config taken from 

1178 the child if set else the first parent that defines one. 

1179 

1180 `_in_progress` is the current ancestor path, used to detect circular 

1181 extends. `_seen` is every config already merged into this flatten, used 

1182 to merge a shared ancestor only once (diamond dedup). 

1183 """ 

1184 if _in_progress is None: 

1185 _in_progress = [] 

1186 if _seen is None: 

1187 _seen = set() 

1188 

1189 config_path_str = str(config_path) 

1190 if config_path_str in _in_progress: 

1191 cycle = _in_progress[_in_progress.index(config_path_str) :] + [ 

1192 config_path_str 

1193 ] 

1194 raise ValueError( 

1195 f"Circular reference detected in extends: {' -> '.join(cycle)}" 

1196 ) 

1197 _in_progress.append(config_path_str) 

1198 

1199 inherited_scopes: list[dict[str, Any]] = [] 

1200 inherited_aliases: dict[str, list[str]] = {} 

1201 inherited_lsc: dict[str, Any] | None = None 

1202 

1203 for extend_path in self.extends: 

1204 resolved_path = _resolve_extends_path(config_path_str, extend_path) 

1205 if resolved_path not in other_configs: 

1206 raise ValueError( 

1207 f"Config not found: '{extend_path}' (resolved to '{resolved_path}')" 

1208 ) 

1209 if resolved_path in _seen: 

1210 # Already merged via another branch (diamond) — skip the dup. 

1211 continue 

1212 

1213 parent_data = other_configs[resolved_path]._merged_data( 

1214 Path(resolved_path), other_configs, _in_progress, _seen 

1215 ) 

1216 inherited_scopes = inherited_scopes + parent_data["scopes"] 

1217 inherited_aliases = inherited_aliases | parent_data["aliases"] 

1218 inherited_lsc = inherited_lsc or parent_data["large_scale_change"] 

1219 

1220 merged = self.model_dump() 

1221 # Which file each scope is written in (see `declaring_config_path`). 

1222 for entry in merged["scopes"]: 

1223 entry["_declared_in"] = config_path_str 

1224 merged["scopes"] = inherited_scopes + merged["scopes"] 

1225 merged["aliases"] = inherited_aliases | merged["aliases"] 

1226 merged["large_scale_change"] = merged["large_scale_change"] or inherited_lsc 

1227 

1228 # Tag each scope with the directory its paths should anchor at. A scope's 

1229 # paths are relative to the config that owns it, so the first 

1230 # non-template config to consume a scope claims it: a non-template's own 

1231 # scopes (and any it inherits from a template) anchor at its directory, 

1232 # while a template defers to its consumer. `setdefault` means an 

1233 # already-tagged scope (from a non-template ancestor) keeps its anchor. 

1234 if not self.template: 

1235 base_dir = posixpath.dirname(config_path_str) 

1236 for entry in merged["scopes"]: 

1237 entry.setdefault("_anchor_dir", base_dir) 

1238 

1239 _seen.add(config_path_str) 

1240 _in_progress.pop() 

1241 

1242 return merged 

1243 

1244 @classmethod 

1245 def from_filesystem(cls, path: Path | str) -> ConfigModel: 

1246 with open(path, "rb") as f: 

1247 return cls.from_data(tomllib.load(f), path) 

1248 

1249 @classmethod 

1250 def from_content(cls, content: str, path: Path | str) -> ConfigModel: 

1251 return cls.from_data(tomllib.loads(content), path) 

1252 

1253 @classmethod 

1254 def from_data(cls, data: dict[str, Any], path: Path | str) -> ConfigModel: 

1255 return cls(**data) 

1256 

1257 

1258class _ConfigModelsBase(RootModel): 

1259 """Shared storage and accessors for a set of configs keyed by repo path.""" 

1260 

1261 root: dict[str, ConfigModel] 

1262 

1263 @classmethod 

1264 def from_config_models(cls, models: dict[str, ConfigModel]) -> Self: 

1265 """Build from a dict of already-constructed configs keyed by path.""" 

1266 configs = cls(root={}) 

1267 for path, config_model in models.items(): 

1268 configs.root[str(Path(path))] = config_model 

1269 return configs 

1270 

1271 def get_config_models(self) -> dict[str, ConfigModel]: 

1272 return dict(self.root.items()) 

1273 

1274 def __bool__(self) -> bool: 

1275 return bool(self.root) 

1276 

1277 def __getitem__(self, key: str) -> ConfigModel: 

1278 return self.root[key] 

1279 

1280 def __contains__(self, key: str) -> bool: 

1281 return key in self.root 

1282 

1283 def __len__(self) -> int: 

1284 return len(self.root) 

1285 

1286 def closest_config_path(self, file_path: Path) -> str | None: 

1287 """The path of the closest non-template config governing this file, 

1288 or None when nothing governs it.""" 

1289 for parent in file_path.parents: 

1290 parent_config_path = str(parent / CONFIG_FILENAME) 

1291 config = self.root.get(parent_config_path) 

1292 if config is not None and not config.template: 

1293 return parent_config_path 

1294 return None 

1295 

1296 

1297class ConfigModels(_ConfigModelsBase): 

1298 """Configs exactly as loaded from the repo — extends unresolved, aliases 

1299 unexpanded, paths unanchored. Build the set up, then call `compiled()`.""" 

1300 

1301 def declared_check_names(self) -> set[str]: 

1302 """Every check-run name an effective (non-template) scope's `unless` 

1303 references, across the whole config set. 

1304 

1305 Collected from an offline compile (`teams=None`, the `team_refs` 

1306 precedent) so a template's refs count only where a consumer actually 

1307 inherits them -- an unconsumed template must not make every pull 

1308 request fetch (or error on) checks that nothing evaluates. `unless` 

1309 refs are literal strings (aliases and teams never expand inside 

1310 them), so the offline compile is exact. Empty for the common case (no 

1311 `unless` anywhere), which is what lets the processor skip fetching 

1312 check runs entirely. 

1313 """ 

1314 return { 

1315 name 

1316 for config in self.compiled().root.values() 

1317 if not config.template 

1318 for scope in config.scopes 

1319 for _, name in scope.unless_refs() 

1320 } 

1321 

1322 @classmethod 

1323 def from_configs_data(cls, data: dict[str, Any]) -> ConfigModels: 

1324 """Load configs from a dict of parsed config data keyed by path.""" 

1325 configs = cls(root={}) 

1326 

1327 for path, config_data in data.items(): 

1328 config = ConfigModel.from_data(config_data, Path(path)) 

1329 configs.add_config(config, Path(path)) 

1330 

1331 return configs 

1332 

1333 @classmethod 

1334 def from_contents(cls, contents: dict[str, str]) -> ConfigModels: 

1335 """Load configs from a dict of raw TOML content keyed by path.""" 

1336 configs = cls(root={}) 

1337 

1338 for path, content in contents.items(): 

1339 configs.add_config(ConfigModel.from_content(content, path), Path(path)) 

1340 

1341 return configs 

1342 

1343 def add_config(self, config: ConfigModel, path: Path) -> None: 

1344 self.root[str(path)] = config 

1345 

1346 def declaring_config_path(self, *, config_path: str, scope_name: str) -> str | None: 

1347 """The config in `config_path`'s extends chain that declares a scope, 

1348 or None when nothing in the chain does.""" 

1349 merged = self.root[config_path]._merged_data(Path(config_path), self) 

1350 for entry in merged["scopes"]: 

1351 if entry["name"] == scope_name: 

1352 return entry["_declared_in"] 

1353 return None 

1354 

1355 def team_refs(self) -> set[str]: 

1356 """Collect every team ref (lowercase, no leading `@`/`!`) that 

1357 `compiled(teams=...)` would actually try to expand: refs written 

1358 directly in a user-list field (scopes' `USER_LIST_FIELDS` and 

1359 `large_scale_change.reviewers`/`alternates`), plus any refs reachable from those 

1360 fields through `$alias`/`!$alias` chains. 

1361 

1362 Meant for callers that need to know which teams to fetch/sync before 

1363 calling `compiled(teams=...)`. 

1364 

1365 Implemented as an offline compile (`teams=None`): aliases expand but 

1366 team refs pass through unexpanded, so whatever refs remain in the 

1367 compiled user-list fields are — by construction — exactly the refs a 

1368 real compile will try to expand. A ref that only appears in a 

1369 non-user-list field (e.g. an npm-style `@vendor/pkg/**` in `paths`) 

1370 or inside an alias nothing references never survives into a compiled 

1371 user-list field, so it is never collected. Raises the same config 

1372 errors `compiled()` would (unknown alias, circular refs, ...), just 

1373 earlier. 

1374 """ 

1375 # Cheap pre-check: a team ref can only enter a compile as a literal 

1376 # `@`/`!@` value in a user-list field or an alias value. Most repos 

1377 # have none, and skipping the compile keeps this near-free for them. 

1378 candidate_lists: list[list[str]] = [] 

1379 for config in self.root.values(): 

1380 candidate_lists.extend(config.aliases.values()) 

1381 for scope in config.scopes: 

1382 for field in USER_LIST_FIELDS: 

1383 candidate_lists.append(getattr(scope, field)) 

1384 if config.large_scale_change: 

1385 candidate_lists.append(config.large_scale_change.reviewers) 

1386 candidate_lists.append(config.large_scale_change.alternates) 

1387 if not any( 

1388 _split_team_ref(value) is not None 

1389 for values in candidate_lists 

1390 for value in values 

1391 ): 

1392 return set() 

1393 

1394 refs: set[str] = set() 

1395 

1396 def collect_refs(values: list[str]) -> None: 

1397 for value in values: 

1398 if (split := _split_team_ref(value)) is not None: 

1399 refs.add(split[1].lower()) 

1400 

1401 for config in self.compiled(teams=None).get_config_models().values(): 

1402 if config.template: 

1403 continue 

1404 for scope in config.scopes: 

1405 for field in USER_LIST_FIELDS: 

1406 collect_refs(getattr(scope, field)) 

1407 if config.large_scale_change: 

1408 collect_refs(config.large_scale_change.reviewers) 

1409 collect_refs(config.large_scale_change.alternates) 

1410 

1411 return refs 

1412 

1413 def compiled( 

1414 self, teams: dict[str, list[str]] | None = None 

1415 ) -> CompiledConfigModels: 

1416 """Resolve the whole set into its effective, PR-independent form. 

1417 

1418 Each non-template config is compiled once — extends merged, aliases 

1419 expanded, paths anchored. Templates are NOT compiled standalone: a 

1420 template scope may reference an alias the consuming config provides, and 

1421 its paths anchor at the consumer. They are carried through untouched 

1422 (folded into each consumer during that consumer's compile, and kept in 

1423 the set for display). 

1424 

1425 `teams` maps team refs (any case, without the leading `@`) to member 

1426 usernames; passed straight through to each config's `compiled_config` 

1427 (see there for case normalization and the `teams=None` vs provided 

1428 semantics). 

1429 

1430 The result is an immutable `CompiledConfigModels` — there is no way to 

1431 compile it again, so the non-idempotent path anchoring can never 

1432 double-apply. 

1433 """ 

1434 effective: dict[str, ConfigModel] = {} 

1435 for path, config in self.root.items(): 

1436 if config.template: 

1437 effective[path] = config 

1438 else: 

1439 effective[path] = config.compiled_config( 

1440 config_path=Path(path), other_configs=self, teams=teams 

1441 ) 

1442 

1443 return CompiledConfigModels.from_config_models(effective) 

1444 

1445 

1446class CompiledConfigModels(_ConfigModelsBase): 

1447 """The effective configs used for matching: every non-template config is 

1448 fully resolved. Produced by `ConfigModels.compiled()`; never recompiled.""" 

1449 

1450 def closest_config(self, file_path: Path) -> ConfigModel: 

1451 """Return the closest non-template config governing this file.""" 

1452 config_path = self.closest_config_path(file_path) 

1453 if config_path is None: 

1454 raise ValueError(f"No config found for {file_path}") 

1455 return self.root[config_path] 

1456 

1457 def get_default_large_scale_change(self) -> LargeScaleChangeModel: 

1458 """The primary (repo-root) config's large-scale-change section, if any. 

1459 

1460 The primary was compiled by `compiled()`, so its reviewers/labels are 

1461 already alias-expanded (e.g. ["$backend"] -> usernames). A `template = 

1462 true` repo root is a misconfiguration (templates are meant to be 

1463 extended, not be the primary); it is passed through uncompiled, so its 

1464 LSC would read with aliases unexpanded. 

1465 """ 

1466 if CONFIG_FILENAME in self.root and ( 

1467 lsc := self.root[CONFIG_FILENAME].large_scale_change 

1468 ): 

1469 return lsc 

1470 

1471 return LargeScaleChangeModel() 

1472 

1473 def filter_for_pullrequest(self, author_username: str) -> CompiledConfigModels: 

1474 """ 

1475 Overlay PR-dependent scope gating: drop scopes that author rules disable 

1476 for this pull request. 

1477 

1478 This is the only PR-dependent step. The configs are already compiled, so 

1479 each config's scopes are self-contained and dropping one is a plain list 

1480 filter — no re-inheritance. Templates are passed through (they are never 

1481 matched directly; their scopes already live in each consumer). 

1482 """ 

1483 effective: dict[str, ConfigModel] = {} 

1484 for config_path, config in self.root.items(): 

1485 if config.template: 

1486 # Templates are never matched directly; pass them through. 

1487 effective[config_path] = config 

1488 continue 

1489 

1490 kept_scopes = [ 

1491 scope 

1492 for scope in config.scopes 

1493 if scope.matches_author(author_username) 

1494 ] 

1495 effective[config_path] = config.model_copy(update={"scopes": kept_scopes}) 

1496 

1497 return CompiledConfigModels.from_config_models(effective)