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

1"""The change type of a ChangeSet, from its paths only (#58, item 6). 

2 

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).""" 

11 

12from __future__ import annotations 

13 

14from collections.abc import Iterable 

15from pathlib import PurePosixPath 

16from typing import Literal 

17 

18ChangeType = Literal["documentation", "configuration", "documentation-configuration", "code"] 

19PathKind = Literal["documentation", "configuration", "code"] 

20 

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) 

61 

62 

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" 

75 

76 

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" 

87 

88 

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 

92 

93 

94__all__ = ["ChangeType", "PathKind", "change_type", "exempt_from_tests", "path_kind"]