Coverage for src/governed_harness/application/clarification_loader.py: 73%

73 statements  

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

1from __future__ import annotations 

2 

3import json 

4from pathlib import Path 

5from typing import Any, Literal, cast 

6 

7import yaml 

8 

9from governed_harness.domain.errors import ConfigurationError 

10from governed_harness.domain.ids import new_id 

11from governed_harness.domain.models import AcceptanceCriterion, Requirement 

12from governed_harness.intake import ClarificationInput 

13 

14from .task_loader import _first, _required_text 

15 

16_KNOWN_FIELDS = frozenset( 

17 {"answers", "replaceCriteria", "addCriteria", "addRequirements", "contract", "confirmContract"} 

18) 

19 

20 

21def _criterion(item: Any, *, require_id: bool, where: str) -> AcceptanceCriterion: 

22 if isinstance(item, str) and not require_id: 22 ↛ 23line 22 didn't jump to line 23 because the condition on line 22 was never true

23 if not item.strip(): 

24 raise ConfigurationError(f"{where} requires a non-empty text") 

25 return AcceptanceCriterion(criterion_id=new_id("ac"), text=item) 

26 if not isinstance(item, dict): 26 ↛ 27line 26 didn't jump to line 27 because the condition on line 26 was never true

27 raise ConfigurationError(f"{where} must be an object with criterionId and text") 

28 criterion_id = _first(item, "criterionId", "criterion_id", "id") 

29 if criterion_id is None and require_id: 

30 raise ConfigurationError(f"{where} requires the criterionId it replaces") 

31 try: 

32 return AcceptanceCriterion( 

33 criterion_id=str(criterion_id) if criterion_id is not None else new_id("ac"), 

34 text=_required_text(item, "text", where), 

35 verification_hint=_first(item, "verificationHint", "verification_hint"), 

36 priority=cast( 

37 Literal["MUST", "SHOULD", "COULD"], 

38 str(_first(item, "priority", default="MUST")).upper(), 

39 ), 

40 ) 

41 except ConfigurationError: 

42 raise 

43 except Exception as error: 

44 raise ConfigurationError(f"invalid {where}: {error}") from error 

45 

46 

47def _requirement(item: Any) -> Requirement: 

48 if isinstance(item, str): 48 ↛ 52line 48 didn't jump to line 52 because the condition on line 48 was always true

49 if not item.strip(): 49 ↛ 50line 49 didn't jump to line 50 because the condition on line 49 was never true

50 raise ConfigurationError("an added requirement requires a non-empty text") 

51 return Requirement(requirement_id=new_id("req"), text=item, source="clarification") 

52 if not isinstance(item, dict): 

53 raise ConfigurationError("added requirements must be strings or objects") 

54 return Requirement( 

55 requirement_id=str( 

56 _first(item, "requirementId", "requirement_id", "id", default=new_id("req")) 

57 ), 

58 text=_required_text(item, "text", "an added requirement"), 

59 source="clarification", 

60 ) 

61 

62 

63def _list(raw: dict[str, Any], name: str) -> list[Any]: 

64 value = raw.get(name) or [] 

65 if not isinstance(value, list): 65 ↛ 66line 65 didn't jump to line 66 because the condition on line 65 was never true

66 raise ConfigurationError(f"{name} must be a list") 

67 return value 

68 

69 

70def _read_answers(path: Path) -> dict[str, Any]: 

71 """The answers file as an object of known fields.""" 

72 try: 

73 if path.suffix.lower() == ".json": 

74 raw = json.loads(path.read_text(encoding="utf-8")) 

75 else: 

76 raw = yaml.safe_load(path.read_text(encoding="utf-8")) 

77 except Exception as error: 

78 raise ConfigurationError(f"cannot parse answers file {path}: {error}") from error 

79 if not isinstance(raw, dict): 79 ↛ 80line 79 didn't jump to line 80 because the condition on line 79 was never true

80 raise ConfigurationError("answers file must contain an object") 

81 unknown = sorted(set(raw) - _KNOWN_FIELDS) 

82 if unknown: 

83 raise ConfigurationError(f"unknown answers-file field(s): {', '.join(unknown)}") 

84 return raw 

85 

86 

87def _answer_texts(raw: dict[str, Any]) -> dict[str, str]: 

88 """The answers by question id (a file with only contract values has none).""" 

89 answers = raw.get("answers") 

90 contract = raw.get("contract") 

91 if contract is not None and not isinstance(contract, dict): 91 ↛ 92line 91 didn't jump to line 92 because the condition on line 91 was never true

92 raise ConfigurationError("contract must be a map of contract item to value") 

93 if answers is None and contract: 

94 answers = {} 

95 if not isinstance(answers, dict) or (not answers and not contract): 

96 raise ConfigurationError("answers file requires 'answers': a map of question id to text") 

97 texts: dict[str, str] = {} 

98 for question_id, text in answers.items(): 

99 if text is None or not isinstance(text, str | int | float): 

100 raise ConfigurationError(f"empty answer(s): {question_id}") 

101 texts[str(question_id)] = str(text) 

102 return texts 

103 

104 

105def load_clarification_file(path: Path) -> ClarificationInput: 

106 """Read an answers file (YAML or JSON). 

107 

108 ``answers`` maps question ids to answer text. Optional task changes: 

109 ``replaceCriteria`` (objects with the ``criterionId`` they replace), ``addCriteria`` and 

110 ``addRequirements`` (strings or objects; added requirements get source 

111 ``clarification``).""" 

112 raw = _read_answers(path) 

113 texts = _answer_texts(raw) 

114 contract = raw.get("contract") 

115 return ClarificationInput( 

116 answers=texts, 

117 replace_criteria=tuple( 

118 _criterion(item, require_id=True, where="a replaced criterion") 

119 for item in _list(raw, "replaceCriteria") 

120 ), 

121 add_criteria=tuple( 

122 _criterion(item, require_id=False, where="an added criterion") 

123 for item in _list(raw, "addCriteria") 

124 ), 

125 add_requirements=tuple(_requirement(item) for item in _list(raw, "addRequirements")), 

126 contract=dict(contract) if contract else None, 

127 confirm_contract=bool(raw.get("confirmContract")), 

128 )