Coverage for src/governed_harness/standards/packs.py: 93%

274 statements  

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

1"""Language standards packs (#56): rule cards for the agent and the tools that verify them. 

2 

3A pack is two files shipped as package resources, ``standards/<pack>/cards.yaml`` and 

4``standards/<pack>/tools.yaml``: 

5 

6* a **card** is one short rule with an id, the rule, its rationale, explicit exceptions, the 

7 files it applies to (globs) and what verifies it: tool rule ids (``ruff:B006``, 

8 ``eslint:eqeqeq``) or ``review`` when only a reviewer can judge it; 

9* a **tool** is a linter or analyzer with the configuration files that show the repository uses 

10 it, the command that runs it with machine-readable output, the parser of that output and a 

11 recommended configuration (documentation; the harness never writes or installs it); 

12* the pack also declares how to detect its language (marker files, extensions, dependencies), 

13 its test and BDD runners and the BDD frameworks it recognizes. 

14 

15The repository's own standards take precedence: ``<standards.path>/<pack>/cards.yaml`` replaces 

16cards with the same id, adds new ones and may list ``disabled`` ids; ``tools.yaml`` there 

17replaces tools by id. A directory there with an id no pack has is a pack of the repository.""" 

18 

19from __future__ import annotations 

20 

21import fnmatch 

22import json 

23import re 

24from dataclasses import dataclass, field 

25from functools import lru_cache 

26from importlib import resources 

27from pathlib import Path 

28from typing import Any 

29 

30import yaml 

31from pydantic import BaseModel, ConfigDict, Field, field_validator 

32 

33from governed_harness.domain.errors import ConfigurationError 

34from governed_harness.evidence.hashing import sha256_json 

35from governed_harness.runtime.workspace import DEFAULT_EXCLUDES 

36 

37BUILTIN_PACKS: tuple[str, ...] = ( 

38 "python", 

39 "javascript", 

40 "typescript", 

41 "node", 

42 "react", 

43 "angular", 

44 "vue", 

45 "java", 

46 "kotlin", 

47 "go", 

48 "rust", 

49 "swift", 

50 "csharp", 

51 "php", 

52 "ruby", 

53) 

54"""The packs shipped with the harness, in the order their cards are listed.""" 

55 

56_CARD_ID = re.compile(r"^[a-z][a-z0-9-]*\.[a-z0-9][a-z0-9.-]*$") 

57_MAX_WALK_FILES = 20_000 

58_MAX_MANIFEST_BYTES = 400_000 

59 

60 

61class _Model(BaseModel): 

62 model_config = ConfigDict(extra="forbid", populate_by_name=True, frozen=True) 

63 

64 

65class Card(_Model): 

66 card_id: str = Field(alias="id") 

67 title: str 

68 rule: str 

69 rationale: str = "" 

70 exceptions: tuple[str, ...] = () 

71 applies_to: tuple[str, ...] = Field(alias="appliesTo", min_length=1) 

72 verified_by: tuple[str, ...] = Field(alias="verifiedBy", min_length=1) 

73 principle: str | None = None 

74 

75 @field_validator("card_id") 

76 @classmethod 

77 def _id(cls, value: str) -> str: 

78 if not _CARD_ID.match(value): 78 ↛ 79line 78 didn't jump to line 79 because the condition on line 78 was never true

79 raise ValueError(f"card id must be <pack>.<name> in lower case: {value!r}") 

80 return value 

81 

82 @property 

83 def needs_review(self) -> bool: 

84 """A card no tool verifies: the reviewer checks it.""" 

85 return "review" in self.verified_by 

86 

87 def applies(self, path: str) -> bool: 

88 return any(_glob_match(path, pattern) for pattern in self.applies_to) 

89 

90 def compact(self) -> dict[str, Any]: 

91 """What an agent receives: id, rule and exceptions (no rationale, to save tokens).""" 

92 value: dict[str, Any] = {"id": self.card_id, "rule": self.rule} 

93 if self.exceptions: 

94 value["exceptions"] = list(self.exceptions) 

95 return value 

96 

97 

98class PackTool(_Model): 

99 tool_id: str = Field(alias="id") 

100 title: str = "" 

101 config_files: tuple[str, ...] = Field(default=(), alias="configFiles") 

102 """Files that show the repository uses the tool; ``file#section`` also requires the 

103 section text in the file (``pyproject.toml#[tool.ruff``).""" 

104 command: tuple[str, ...] | None = None 

105 parser: str | None = None 

106 covered_by: tuple[str, ...] = Field(default=(), alias="coveredBy") 

107 """Profile validators that already run the tool: it is not added twice.""" 

108 principles: tuple[str, ...] = () 

109 """Engineering principles the tool's rules give evidence of (``yagni``, ``kiss``...).""" 

110 recommended: str | None = None 

111 """Recommended configuration, for the documentation and ``harness standards show``.""" 

112 

113 

114class Detection(_Model): 

115 markers: tuple[str, ...] = () 

116 extensions: tuple[str, ...] = () 

117 dependencies: tuple[str, ...] = () 

118 """Names that must appear in a dependency manifest (package.json, pyproject.toml...).""" 

119 requires: tuple[str, ...] = () 

120 """Packs that must also be detected (a framework pack needs its language).""" 

121 

122 

123class Runner(_Model): 

124 test: tuple[str, ...] | None = None 

125 test_files: bool = Field(default=False, alias="testFiles") 

126 """Whether the test runner accepts test file paths as arguments.""" 

127 bdd: tuple[str, ...] | None = None 

128 

129 

130class BddFramework(_Model): 

131 name: str 

132 markers: tuple[str, ...] = () 

133 dependencies: tuple[str, ...] = () 

134 

135 

136class Pack(_Model): 

137 pack_id: str = Field(alias="pack") 

138 title: str 

139 extends: tuple[str, ...] = () 

140 detect: Detection = Field(default_factory=Detection) 

141 runner: Runner = Field(default_factory=Runner) 

142 bdd_frameworks: tuple[BddFramework, ...] = Field(default=(), alias="bddFrameworks") 

143 tools: tuple[PackTool, ...] = () 

144 cards: tuple[Card, ...] = () 

145 source: str = "builtin" 

146 

147 @property 

148 def digest(self) -> str: 

149 return sha256_json(self.model_dump(mode="json", by_alias=True)) 

150 

151 

152def _glob_match(path: str, pattern: str) -> bool: 

153 path = path.replace("\\", "/") 

154 if fnmatch.fnmatchcase(path, pattern): 

155 return True 

156 # "**/*.py" also matches a file at the root. 

157 return pattern.startswith("**/") and fnmatch.fnmatchcase(path, pattern[3:]) 

158 

159 

160# ----- loading -------------------------------------------------------------------------------- 

161_CARDS_FILE = "cards.yaml" 

162_TOOLS_FILE = "tools.yaml" 

163 

164 

165def _resource_yaml(pack: str, name: str) -> dict[str, Any]: 

166 target = resources.files("governed_harness.resources").joinpath("standards", pack, name) 

167 if not target.is_file(): 167 ↛ 168line 167 didn't jump to line 168 because the condition on line 167 was never true

168 return {} 

169 value = yaml.safe_load(target.read_text(encoding="utf-8")) 

170 return value if isinstance(value, dict) else {} 

171 

172 

173@lru_cache(maxsize=64) 

174def builtin_pack(pack: str) -> Pack: 

175 if pack not in BUILTIN_PACKS: 175 ↛ 176line 175 didn't jump to line 176 because the condition on line 175 was never true

176 raise ConfigurationError( 

177 f"unknown standards pack {pack!r}; known: {', '.join(BUILTIN_PACKS)}" 

178 ) 

179 cards = _resource_yaml(pack, _CARDS_FILE) 

180 tools = _resource_yaml(pack, _TOOLS_FILE) 

181 return Pack.model_validate({**tools, **cards, "pack": pack}) 

182 

183 

184def _read_yaml(path: Path) -> dict[str, Any]: 

185 try: 

186 value = yaml.safe_load(path.read_text(encoding="utf-8")) 

187 except (OSError, yaml.YAMLError) as error: 

188 raise ConfigurationError(f"cannot read standards file {path}: {error}") from error 

189 if value is None: 189 ↛ 190line 189 didn't jump to line 190 because the condition on line 189 was never true

190 return {} 

191 if not isinstance(value, dict): 191 ↛ 192line 191 didn't jump to line 192 because the condition on line 191 was never true

192 raise ConfigurationError(f"standards file {path} must be a mapping") 

193 return value 

194 

195 

196def load_pack( 

197 pack: str, 

198 workspace: Path | None = None, 

199 overrides: str | None = None, 

200 disabled: tuple[str, ...] = (), 

201) -> Pack: 

202 """A pack with the repository's overrides applied (repository > pack).""" 

203 directory = (workspace / overrides / pack) if workspace is not None and overrides else None 

204 local_cards = _local_yaml(directory, _CARDS_FILE) 

205 local_tools = _local_yaml(directory, _TOOLS_FILE) 

206 if pack in BUILTIN_PACKS: 

207 base = builtin_pack(pack) 

208 elif local_cards or local_tools: 

209 base = _repository_pack(pack, local_cards, local_tools) 

210 local_cards, local_tools = {}, {} 

211 else: 

212 raise ConfigurationError( 

213 f"unknown standards pack {pack!r}; known: {', '.join(BUILTIN_PACKS)}" 

214 ) 

215 local_card_items, local_tool_items = _local_items(pack, local_cards, local_tools) 

216 off = set(disabled) | set(local_cards.get("disabled") or []) 

217 cards: dict[str, Card] = {item.card_id: item for item in base.cards} 

218 cards.update({item.card_id: item for item in local_card_items}) 

219 tools: dict[str, PackTool] = {item.tool_id: item for item in base.tools} 

220 tools.update({item.tool_id: item for item in local_tool_items}) 

221 changed = bool(local_card_items or local_tool_items or off & set(cards)) 

222 return base.model_copy( 

223 update={ 

224 "cards": tuple(item for item in cards.values() if item.card_id not in off), 

225 "tools": tuple(tools.values()), 

226 "source": "builtin+repository" if changed and base.source == "builtin" else base.source, 

227 } 

228 ) 

229 

230 

231def _local_yaml(directory: Path | None, name: str) -> dict[str, Any]: 

232 """A file of the repository's overrides of a pack, empty when there is none.""" 

233 if directory is None or not (directory / name).is_file(): 

234 return {} 

235 return _read_yaml(directory / name) 

236 

237 

238def _repository_pack(pack: str, local_cards: dict[str, Any], local_tools: dict[str, Any]) -> Pack: 

239 """A pack the repository defines on its own (no built-in pack of that name).""" 

240 try: 

241 return Pack.model_validate( 

242 { 

243 "title": pack, 

244 **{k: v for k, v in local_tools.items() if k != "disabled"}, 

245 **{k: v for k, v in local_cards.items() if k != "disabled"}, 

246 "pack": pack, 

247 "source": "repository", 

248 } 

249 ) 

250 except ValueError as error: 

251 raise ConfigurationError(f"invalid repository pack {pack}: {error}") from error 

252 

253 

254def _local_items( 

255 pack: str, local_cards: dict[str, Any], local_tools: dict[str, Any] 

256) -> tuple[list[Card], list[PackTool]]: 

257 try: 

258 cards = [Card.model_validate(item) for item in local_cards.get("cards") or []] 

259 tools = [PackTool.model_validate(item) for item in local_tools.get("tools") or []] 

260 except ValueError as error: 

261 raise ConfigurationError(f"invalid repository standards for {pack}: {error}") from error 

262 return cards, tools 

263 

264 

265# ----- detection ------------------------------------------------------------------------------ 

266@dataclass 

267class WorkspaceFacts: 

268 """What detection reads from a workspace, once: file names, extensions, manifests.""" 

269 

270 files: list[str] = field(default_factory=list) 

271 extensions: dict[str, int] = field(default_factory=dict) 

272 manifests: str = "" 

273 

274 @classmethod 

275 def read(cls, workspace: Path) -> WorkspaceFacts: 

276 facts = cls() 

277 root = workspace.resolve() 

278 manifests: list[str] = [] 

279 for path in _walk(root): 

280 relative = path.relative_to(root).as_posix() 

281 facts.files.append(relative) 

282 suffix = path.suffix.lower() 

283 if suffix: 

284 facts.extensions[suffix] = facts.extensions.get(suffix, 0) + 1 

285 if _is_manifest(path.name): 

286 try: 

287 manifests.append( 

288 path.read_bytes()[:_MAX_MANIFEST_BYTES].decode("utf-8", "replace") 

289 ) 

290 except OSError: 

291 continue 

292 facts.manifests = "\n".join(manifests) 

293 return facts 

294 

295 def has(self, marker: str) -> bool: 

296 if any(char in marker for char in "*?["): 

297 return any(_glob_match(item, marker) for item in self.files) 

298 return marker in self.files or any( 

299 item.startswith(marker.rstrip("/") + "/") for item in self.files 

300 ) 

301 

302 def depends_on(self, name: str) -> bool: 

303 return re.search(rf"(?<![\w@/.-]){re.escape(name)}(?![\w-])", self.manifests) is not None 

304 

305 

306_MANIFESTS = ( 

307 "package.json", 

308 "pyproject.toml", 

309 "setup.cfg", 

310 "Pipfile", 

311 "Gemfile", 

312 "pom.xml", 

313 "build.gradle", 

314 "build.gradle.kts", 

315 "composer.json", 

316 "Cargo.toml", 

317 "go.mod", 

318 "Package.swift", 

319) 

320 

321 

322def _is_manifest(name: str) -> bool: 

323 return ( 

324 name in _MANIFESTS 

325 or name.endswith(".csproj") 

326 or (name.startswith("requirements") and name.endswith(".txt")) 

327 ) 

328 

329 

330def _walk(root: Path) -> list[Path]: 

331 found: list[Path] = [] 

332 stack = [root] 

333 while stack and len(found) < _MAX_WALK_FILES: 

334 directory = stack.pop() 

335 try: 

336 entries = sorted(directory.iterdir(), key=lambda item: item.name) 

337 except OSError: 

338 continue 

339 for entry in entries: 

340 if entry.name in DEFAULT_EXCLUDES or entry.is_symlink(): 

341 continue 

342 if entry.is_dir(): 

343 stack.append(entry) 

344 elif entry.is_file(): 344 ↛ 339line 344 didn't jump to line 339 because the condition on line 344 was always true

345 found.append(entry) 

346 return found 

347 

348 

349def detect_packs(workspace: Path, technologies: tuple[str, ...] = ()) -> list[str]: 

350 """The packs whose language the workspace uses, in ``BUILTIN_PACKS`` order. A profile 

351 technology (``python``, ``node``) selects its pack directly.""" 

352 facts = WorkspaceFacts.read(workspace) 

353 return detect_from_facts(facts, technologies) 

354 

355 

356def detect_from_facts(facts: WorkspaceFacts, technologies: tuple[str, ...] = ()) -> list[str]: 

357 found: list[str] = [] 

358 for pack_id in BUILTIN_PACKS: 

359 detection = builtin_pack(pack_id).detect 

360 hit = pack_id in technologies 

361 if not hit and detection.markers: 

362 hit = any(facts.has(marker) for marker in detection.markers) 

363 if not hit and detection.extensions: 

364 hit = any(facts.extensions.get(ext, 0) for ext in detection.extensions) 

365 if hit and detection.dependencies: 

366 hit = any(facts.depends_on(name) for name in detection.dependencies) 

367 if hit and detection.requires: 

368 hit = all(item in found for item in detection.requires) 

369 if hit: 

370 found.append(pack_id) 

371 return found 

372 

373 

374def bdd_frameworks(packs: list[Pack], facts: WorkspaceFacts) -> list[str]: 

375 """The BDD frameworks the repository shows (feature files alone count as ``gherkin``).""" 

376 names: list[str] = [] 

377 for pack in packs: 

378 for framework in pack.bdd_frameworks: 

379 marker_hit = any(facts.has(item) for item in framework.markers) 

380 dependency_hit = any(facts.depends_on(item) for item in framework.dependencies) 

381 if marker_hit or dependency_hit: 

382 names.append(framework.name) 

383 if not names and any(item.endswith(".feature") for item in facts.files): 383 ↛ 384line 383 didn't jump to line 384 because the condition on line 383 was never true

384 names.append("gherkin") 

385 return list(dict.fromkeys(names)) 

386 

387 

388# ----- the packs of a project ------------------------------------------------------------------ 

389@dataclass(frozen=True) 

390class ProjectStandards: 

391 packs: tuple[Pack, ...] 

392 detected: tuple[str, ...] 

393 configured: tuple[str, ...] | None 

394 

395 @property 

396 def digest(self) -> str: 

397 return sha256_json([item.digest for item in self.packs]) 

398 

399 def pack(self, pack_id: str) -> Pack | None: 

400 return next((item for item in self.packs if item.pack_id == pack_id), None) 

401 

402 

403def _with_extends(ids: list[str]) -> list[str]: 

404 ordered: list[str] = [] 

405 for pack_id in ids: 

406 if pack_id in BUILTIN_PACKS: 

407 for parent in builtin_pack(pack_id).extends: 

408 if parent not in ordered: 

409 ordered.append(parent) 

410 if pack_id not in ordered: 410 ↛ 405line 410 didn't jump to line 405 because the condition on line 410 was always true

411 ordered.append(pack_id) 

412 return ordered 

413 

414 

415def _repository_pack_ids(local: Path, packs: tuple[str, ...] | None) -> list[str]: 

416 """The repository-only packs (directories of the overrides that name no built-in pack) 

417 the configuration selects: all of them under ``auto`` or no list.""" 

418 if not local.is_dir(): 

419 return [] 

420 return [ 

421 directory.name 

422 for directory in sorted(local.iterdir()) 

423 if directory.is_dir() 

424 and directory.name not in BUILTIN_PACKS 

425 and (packs is None or "auto" in packs or directory.name in packs) 

426 ] 

427 

428 

429def project_standards( 

430 workspace: Path, 

431 *, 

432 packs: tuple[str, ...] | None, 

433 overrides: str | None, 

434 disabled: tuple[str, ...] = (), 

435 technologies: tuple[str, ...] = (), 

436) -> ProjectStandards: 

437 """The effective packs: configured ids (``auto`` expands to the detected ones) plus the 

438 packs they extend, with the repository's overrides and repository-only packs.""" 

439 detected = detect_packs(workspace, technologies) 

440 wanted: list[str] = [] 

441 for item in packs or ("auto",): 

442 if item == "auto": 

443 wanted.extend(detected) 

444 else: 

445 wanted.append(item) 

446 if overrides: 

447 wanted.extend(_repository_pack_ids(workspace / overrides, packs)) 

448 ids = _with_extends(list(dict.fromkeys(wanted))) 

449 return ProjectStandards( 

450 packs=tuple(load_pack(item, workspace, overrides, disabled) for item in ids), 

451 detected=tuple(detected), 

452 configured=packs, 

453 ) 

454 

455 

456def describe_pack(pack: Pack, *, include_cards: bool = True) -> dict[str, Any]: 

457 value: dict[str, Any] = { 

458 "pack": pack.pack_id, 

459 "title": pack.title, 

460 "source": pack.source, 

461 "digest": pack.digest, 

462 "extends": list(pack.extends), 

463 "runner": pack.runner.model_dump(mode="json", by_alias=True, exclude_none=True), 

464 "bddFrameworks": [item.name for item in pack.bdd_frameworks], 

465 "tools": [ 

466 { 

467 "id": item.tool_id, 

468 "configFiles": list(item.config_files), 

469 "command": list(item.command or ()), 

470 "parser": item.parser, 

471 "coveredBy": list(item.covered_by), 

472 "recommended": item.recommended, 

473 } 

474 for item in pack.tools 

475 ], 

476 "cards": len(pack.cards), 

477 } 

478 if include_cards: 

479 value["cards"] = [ 

480 item.model_dump(mode="json", by_alias=True, exclude_none=True) for item in pack.cards 

481 ] 

482 return value 

483 

484 

485def dumps(value: Any) -> str: 

486 return json.dumps(value, sort_keys=True) 

487 

488 

489__all__ = [ 

490 "BUILTIN_PACKS", 

491 "BddFramework", 

492 "Card", 

493 "Detection", 

494 "Pack", 

495 "PackTool", 

496 "ProjectStandards", 

497 "Runner", 

498 "WorkspaceFacts", 

499 "bdd_frameworks", 

500 "builtin_pack", 

501 "describe_pack", 

502 "detect_from_facts", 

503 "detect_packs", 

504 "load_pack", 

505 "project_standards", 

506]