Coverage for src/pullapprove/schemas.py: 100%

68 statements  

« prev     ^ index     » next       coverage.py v7.14.1, created at 2026-10-27 17:11 -0500

1""" 

2JSON shapes for matches, shared by `pullapprove match --json` and the 

3PullApprove API. 

4 

5These describe the match layer: which scopes, paths and code a set of 

6files or a diff matched, before any reviews are counted. The API's 

7per-PR results wrap these same shapes with a status, so the keys (scope 

8name, path, code location_id) line up between the two. 

9""" 

10 

11from __future__ import annotations 

12 

13from typing import TypedDict 

14 

15from .config import ScopeModel 

16from .matches import ChangeMatches, ScopeCodeMatch, ScopePathMatch 

17 

18# Bump when a change to these shapes would break someone reading them. 

19MATCHES_SCHEMA_VERSION = 1 

20 

21 

22class ScopeSchema(TypedDict): 

23 """The scope config behind a match.""" 

24 

25 name: str 

26 description: str 

27 ownership: str 

28 require: int 

29 reviewers: list[str] 

30 alternates: list[str] 

31 paths: list[str] 

32 code: list[str] 

33 checklist: bool 

34 

35 

36class PathMatchSchema(TypedDict): 

37 path: str 

38 scopes: list[str] 

39 

40 

41class CodeMatchSchema(TypedDict): 

42 path: str 

43 scopes: list[str] 

44 start_line: int 

45 end_line: int 

46 start_column: int 

47 end_column: int 

48 location_id: str 

49 

50 

51class ScopeMatchesSchema(TypedDict): 

52 """A scope and the paths and code (by location_id) it matched.""" 

53 

54 scope: ScopeSchema 

55 matched_paths: list[str] 

56 matched_code: list[str] 

57 

58 

59class MatchesSchema(TypedDict): 

60 version: int 

61 scopes: dict[str, ScopeMatchesSchema] 

62 paths: dict[str, PathMatchSchema] 

63 code: dict[str, CodeMatchSchema] 

64 

65 

66def scope_schema(scope: ScopeModel) -> ScopeSchema: 

67 return { 

68 "name": scope.name, 

69 "description": scope.description, 

70 "ownership": str(scope.ownership), 

71 "require": scope.require, 

72 "reviewers": scope.reviewers, 

73 "alternates": scope.alternates, 

74 "paths": scope.paths, 

75 "code": scope.code, 

76 "checklist": scope.checklist is not None, 

77 } 

78 

79 

80def path_match_schema(path_match: ScopePathMatch) -> PathMatchSchema: 

81 return { 

82 "path": path_match.path, 

83 "scopes": path_match.scopes, 

84 } 

85 

86 

87def code_match_schema(code_match: ScopeCodeMatch) -> CodeMatchSchema: 

88 return { 

89 "path": code_match.path, 

90 "scopes": code_match.scopes, 

91 "start_line": code_match.start_line, 

92 "end_line": code_match.end_line, 

93 "start_column": code_match.start_column, 

94 "end_column": code_match.end_column, 

95 "location_id": code_match.location_id, 

96 } 

97 

98 

99def matches_schema( 

100 *, 

101 matches: ChangeMatches, 

102 all_paths: list[str], 

103 scope_filter: tuple[str, ...] = (), 

104) -> MatchesSchema: 

105 """Everything a set of files or a diff matched. 

106 

107 `all_paths` is every file that was looked at, so files no scope owns 

108 show up in `paths` with empty `scopes`. A `scope_filter` narrows the 

109 output to those scopes and the files they touch. 

110 """ 

111 if scope_filter: 

112 all_paths = matches.paths_matching_scopes( 

113 paths=all_paths, scope_filter=scope_filter 

114 ) 

115 

116 paths: dict[str, PathMatchSchema] = {} 

117 for path in sorted(all_paths): 

118 if path in matches.paths: 

119 paths[path] = path_match_schema(matches.paths[path]) 

120 else: 

121 paths[path] = {"path": path, "scopes": []} 

122 

123 code_matches = sorted( 

124 matches.code.values(), 

125 key=lambda c: (c.path, c.start_line, c.start_column), 

126 ) 

127 code: dict[str, CodeMatchSchema] = {} 

128 for code_match in code_matches: 

129 if code_match.path in paths: 

130 code[code_match.location_id] = code_match_schema(code_match) 

131 

132 scopes: dict[str, ScopeMatchesSchema] = {} 

133 for scope in matches.scopes.values(): 

134 if scope_filter and scope.name not in scope_filter: 

135 continue 

136 scopes[scope.name] = { 

137 "scope": scope_schema(scope), 

138 "matched_paths": [], 

139 "matched_code": [], 

140 } 

141 

142 for path, path_match in paths.items(): 

143 for scope_name in path_match["scopes"]: 

144 if scope_name in scopes: 

145 scopes[scope_name]["matched_paths"].append(path) 

146 

147 for location_id, code_match in code.items(): 

148 for scope_name in code_match["scopes"]: 

149 if scope_name in scopes: 

150 scopes[scope_name]["matched_code"].append(location_id) 

151 

152 return { 

153 "version": MATCHES_SCHEMA_VERSION, 

154 "scopes": scopes, 

155 "paths": paths, 

156 "code": code, 

157 }