Coverage for src/governed_harness/validators/review.py: 100%

61 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1from __future__ import annotations 

2 

3import re 

4from collections.abc import Iterator 

5from dataclasses import dataclass 

6from datetime import UTC, datetime 

7 

8from governed_harness.domain.enums import ActorType, FindingSeverity, ResultStatus, ValidationKind 

9from governed_harness.domain.ids import new_id 

10from governed_harness.domain.models import Actor, Finding, FindingLocation, ValidationResult 

11from governed_harness.validators.base import ValidationContext, ValidatorOutput 

12 

13 

14@dataclass(frozen=True) 

15class ReviewRule: 

16 rule_id: str 

17 category: str 

18 severity: FindingSeverity 

19 pattern: re.Pattern[str] 

20 message: str 

21 recommendation: str 

22 

23 

24RULES = ( 

25 ReviewRule( 

26 "review.possible-secret", 

27 "security", 

28 FindingSeverity.CRITICAL, 

29 re.compile( 

30 r"(?i)(github_pat_|gh[pousr]_|AKIA[A-Z0-9]{16}|password\s*[:=]\s*['\"][^'\"]{4,})" 

31 ), 

32 "The added content appears to contain a credential or secret.", 

33 "Remove the secret, rotate it when applicable, and use an approved secret handle.", 

34 ), 

35 ReviewRule( 

36 "review.shell-true", 

37 "security", 

38 FindingSeverity.HIGH, 

39 re.compile(r"\bshell\s*=\s*True\b"), 

40 "A subprocess is executed through a shell.", 

41 "Use an argv vector with shell disabled and validate every argument.", 

42 ), 

43 ReviewRule( 

44 "review.dynamic-eval", 

45 "security", 

46 FindingSeverity.HIGH, 

47 re.compile(r"\b(?:eval|exec)\s*\("), 

48 "Dynamic code execution was added.", 

49 "Replace dynamic execution with a constrained parser or explicit dispatch table.", 

50 ), 

51 ReviewRule( 

52 "review.todo", 

53 "maintainability", 

54 FindingSeverity.MEDIUM, 

55 re.compile(r"\b(?:TODO|FIXME)\b"), 

56 "A TODO or FIXME was introduced in changed code.", 

57 "Resolve it now or link it to a tracked, owned follow-up with rationale.", 

58 ), 

59) 

60 

61 

62class IndependentReviewValidator: 

63 validator_id = "review.independent" 

64 

65 def __init__(self, skip_rules: frozenset[str] = frozenset()) -> None: 

66 # verification.secrets: context replaces the style-dependent secret pattern with the 

67 # context-aware check of VERIFICATION, so the review does not report it twice. 

68 self.skip_rules = skip_rules 

69 

70 def execute(self, context: ValidationContext) -> ValidatorOutput: 

71 actor = Actor( 

72 actor_type=ActorType.TOOL, actor_id="validator.independent-review", version="1" 

73 ) 

74 started = datetime.now(UTC) 

75 if context.raw_diff is not None: 

76 diff = context.raw_diff 

77 else: 

78 # Backward-compatible fallback for callers that do not provide an 

79 # ephemeral raw diff. Persisted evidence may be redacted, so the 

80 # orchestration engine should always supply raw_diff for security review. 

81 diff_bytes = context.artifact_store.get(context.change_set.diff_ref) 

82 diff = diff_bytes.decode("utf-8", "replace") 

83 findings = list(self._scan(diff, context, actor)) 

84 source_changed = any( 

85 change.path.startswith(("src/", "lib/", "app/")) for change in context.change_set.files 

86 ) 

87 tests_changed = any( 

88 change.path.startswith(("test/", "tests/")) 

89 or "/test/" in change.path 

90 or "/tests/" in change.path 

91 for change in context.change_set.files 

92 ) 

93 if source_changed and not tests_changed: 

94 findings.append( 

95 Finding( 

96 finding_id=new_id("finding"), 

97 execution_id=context.execution_id, 

98 validator_id=self.validator_id, 

99 rule_id="review.source-without-test-change", 

100 category="tests", 

101 severity=FindingSeverity.MEDIUM, 

102 message="Production source changed without a corresponding test-file change.", 

103 recommendation="Confirm existing tests cover the behavior or add a targeted regression test.", 

104 evidence_refs=(context.change_set.diff_ref,), 

105 introduced=True, 

106 provenance=context.provenance.model_copy(update={"actor": actor}), 

107 ) 

108 ) 

109 report = context.artifact_store.put_json( 

110 { 

111 "validatorId": self.validator_id, 

112 "changeSetDigest": context.change_set.digest, 

113 "findingIds": [finding.finding_id for finding in findings], 

114 "rulesEvaluated": [ 

115 rule.rule_id for rule in RULES if rule.rule_id not in self.skip_rules 

116 ] 

117 + ["review.source-without-test-change"], 

118 }, 

119 metadata={"kind": "independent-review"}, 

120 ) 

121 result = ValidationResult( 

122 validation_result_id=new_id("validation"), 

123 execution_id=context.execution_id, 

124 validator_id=self.validator_id, 

125 change_set_digest=context.change_set.digest, 

126 status=ResultStatus.PASSED, 

127 kind=ValidationKind.SUCCESS, 

128 mandatory=True, 

129 summary=f"Independent review completed with {len(findings)} finding(s)", 

130 finding_ids=tuple(finding.finding_id for finding in findings), 

131 evidence_refs=(context.change_set.diff_ref, report.uri), 

132 started_at=started, 

133 finished_at=datetime.now(UTC), 

134 provenance=context.provenance.model_copy(update={"actor": actor}), 

135 ) 

136 return ValidatorOutput(result, tuple(findings)) 

137 

138 def _scan(self, diff: str, context: ValidationContext, actor: Actor) -> Iterator[Finding]: 

139 current_path: str | None = None 

140 current_line = 0 

141 for raw_line in diff.splitlines(): 

142 if raw_line.startswith("+++ b/"): 

143 current_path = raw_line[6:] 

144 continue 

145 if raw_line.startswith("@@"): 

146 current_line = _hunk_start(raw_line) 

147 continue 

148 if raw_line.startswith("+") and not raw_line.startswith("+++"): 

149 yield from self._line_findings( 

150 raw_line[1:], current_path, current_line, context, actor 

151 ) 

152 current_line += 1 

153 elif raw_line.startswith(" "): 

154 current_line += 1 

155 

156 def _line_findings( 

157 self, 

158 content: str, 

159 path: str | None, 

160 line: int, 

161 context: ValidationContext, 

162 actor: Actor, 

163 ) -> Iterator[Finding]: 

164 """The findings of the rules that match one added line.""" 

165 for rule in RULES: 

166 if rule.rule_id in self.skip_rules: 

167 continue 

168 if rule.pattern.search(content): 

169 yield Finding( 

170 finding_id=new_id("finding"), 

171 execution_id=context.execution_id, 

172 validator_id=self.validator_id, 

173 rule_id=rule.rule_id, 

174 category=rule.category, 

175 severity=rule.severity, 

176 message=rule.message, 

177 location=FindingLocation( 

178 path=path, 

179 start_line=line or None, 

180 end_line=line or None, 

181 ), 

182 evidence_refs=(context.change_set.diff_ref,), 

183 recommendation=rule.recommendation, 

184 introduced=True, 

185 provenance=context.provenance.model_copy(update={"actor": actor}), 

186 ) 

187 

188 

189def _hunk_start(header: str) -> int: 

190 """The first new-file line of a ``@@`` hunk header; 0 without one.""" 

191 match = re.search(r"\+(\d+)", header) 

192 return int(match.group(1)) if match else 0