Coverage for src/governed_harness/friction/change_types.py: 100%
34 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"""The change type of a ChangeSet, from its paths only (#58, item 6).
3A file is *documentation* by its suffix (``.md``, ``.rst``, ``.adoc``, ``.txt``) or its
4conventional name (``LICENSE``, ``CHANGELOG``...), *configuration* by its suffix (``.yaml``,
5``.toml``, ``.ini``, ``.json``...) or its name (``.gitignore``, ``.editorconfig``...), and
6*code* otherwise, tests included. A ChangeSet whose files are all documentation is
7``documentation``, all configuration ``configuration``, a mix of the two
8``documentation-configuration`` and anything with a code file ``code``. Only the first three are
9exempt from requiring new tests and requirement traceability; every other check still runs (a
10configuration change that weakens a control is still found by the checks that look for it)."""
12from __future__ import annotations
14from collections.abc import Iterable
15from pathlib import PurePosixPath
16from typing import Literal
18ChangeType = Literal["documentation", "configuration", "documentation-configuration", "code"]
19PathKind = Literal["documentation", "configuration", "code"]
21_DOC_SUFFIXES = frozenset({".md", ".markdown", ".rst", ".adoc", ".txt", ".asciidoc"})
22_DOC_NAMES = frozenset(
23 {
24 "LICENSE",
25 "LICENCE",
26 "NOTICE",
27 "AUTHORS",
28 "CHANGELOG",
29 "CHANGES",
30 "CONTRIBUTORS",
31 "COPYING",
32 "README",
33 "HISTORY",
34 "CODEOWNERS",
35 }
36)
37_CONFIG_SUFFIXES = frozenset(
38 {".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", ".json", ".jsonc", ".properties"}
39)
40_CONFIG_NAMES = frozenset(
41 {
42 ".gitignore",
43 ".gitattributes",
44 ".editorconfig",
45 ".dockerignore",
46 ".prettierrc",
47 ".prettierignore",
48 ".eslintrc",
49 ".eslintignore",
50 ".npmrc",
51 ".nvmrc",
52 ".python-version",
53 ".tool-versions",
54 ".markdownlint",
55 ".env.example",
56 }
57)
58_EXEMPT: frozenset[ChangeType] = frozenset(
59 {"documentation", "configuration", "documentation-configuration"}
60)
63def path_kind(path: str) -> PathKind:
64 """Whether one workspace path is documentation, configuration or code."""
65 pure = PurePosixPath(path.replace("\\", "/"))
66 name = pure.name
67 suffix = pure.suffix.lower()
68 if suffix in _DOC_SUFFIXES:
69 return "documentation"
70 if name in _CONFIG_NAMES or suffix in _CONFIG_SUFFIXES:
71 return "configuration"
72 if not suffix and name.upper() in _DOC_NAMES:
73 return "documentation"
74 return "code"
77def change_type(paths: Iterable[str]) -> ChangeType:
78 """The change type of the ChangeSet made of ``paths`` (``code`` when it is empty)."""
79 kinds = {path_kind(path) for path in paths}
80 if not kinds or "code" in kinds:
81 return "code"
82 if kinds == {"documentation"}:
83 return "documentation"
84 if kinds == {"configuration"}:
85 return "configuration"
86 return "documentation-configuration"
89def exempt_from_tests(kind: ChangeType) -> bool:
90 """Whether a ChangeSet of this type needs no new tests and no requirement traceability."""
91 return kind in _EXEMPT
94__all__ = ["ChangeType", "PathKind", "change_type", "exempt_from_tests", "path_kind"]