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
« 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.
3A pack is two files shipped as package resources, ``standards/<pack>/cards.yaml`` and
4``standards/<pack>/tools.yaml``:
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.
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."""
19from __future__ import annotations
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
30import yaml
31from pydantic import BaseModel, ConfigDict, Field, field_validator
33from governed_harness.domain.errors import ConfigurationError
34from governed_harness.evidence.hashing import sha256_json
35from governed_harness.runtime.workspace import DEFAULT_EXCLUDES
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."""
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
61class _Model(BaseModel):
62 model_config = ConfigDict(extra="forbid", populate_by_name=True, frozen=True)
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
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
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
87 def applies(self, path: str) -> bool:
88 return any(_glob_match(path, pattern) for pattern in self.applies_to)
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
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``."""
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)."""
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
130class BddFramework(_Model):
131 name: str
132 markers: tuple[str, ...] = ()
133 dependencies: tuple[str, ...] = ()
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"
147 @property
148 def digest(self) -> str:
149 return sha256_json(self.model_dump(mode="json", by_alias=True))
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:])
160# ----- loading --------------------------------------------------------------------------------
161_CARDS_FILE = "cards.yaml"
162_TOOLS_FILE = "tools.yaml"
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 {}
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})
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
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 )
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)
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
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
265# ----- detection ------------------------------------------------------------------------------
266@dataclass
267class WorkspaceFacts:
268 """What detection reads from a workspace, once: file names, extensions, manifests."""
270 files: list[str] = field(default_factory=list)
271 extensions: dict[str, int] = field(default_factory=dict)
272 manifests: str = ""
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
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 )
302 def depends_on(self, name: str) -> bool:
303 return re.search(rf"(?<![\w@/.-]){re.escape(name)}(?![\w-])", self.manifests) is not None
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)
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 )
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
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)
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
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))
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
395 @property
396 def digest(self) -> str:
397 return sha256_json([item.digest for item in self.packs])
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)
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
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 ]
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 )
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
485def dumps(value: Any) -> str:
486 return json.dumps(value, sort_keys=True)
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]