python-checks 0.9.0__tar.gz → 0.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. {python_checks-0.9.0 → python_checks-0.10.0}/PKG-INFO +7 -4
  2. {python_checks-0.9.0 → python_checks-0.10.0}/README.md +5 -3
  3. {python_checks-0.9.0 → python_checks-0.10.0}/pyproject.toml +3 -1
  4. {python_checks-0.9.0 → python_checks-0.10.0}/pyproject.toml.orig +5 -1
  5. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/hygiene/__init__.py +4 -2
  6. python_checks-0.10.0/src/py_checks/checks/hygiene/_translations.py +169 -0
  7. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/__init__.py +2 -0
  8. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_doctor.py +37 -1
  9. python_checks-0.10.0/src/py_checks/cli/commands/_translations.py +98 -0
  10. python_checks-0.10.0/src/py_checks/translations/__init__.py +30 -0
  11. python_checks-0.10.0/src/py_checks/translations/_constants.py +15 -0
  12. python_checks-0.10.0/src/py_checks/translations/_errors.py +7 -0
  13. python_checks-0.10.0/src/py_checks/translations/_settings.py +22 -0
  14. python_checks-0.10.0/src/py_checks/translations/_stamp.py +59 -0
  15. python_checks-0.10.0/src/py_checks/translations/_tree.py +104 -0
  16. {python_checks-0.9.0 → python_checks-0.10.0}/LICENSE +0 -0
  17. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/__init__.py +0 -0
  18. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/__init__.py +0 -0
  19. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/_kind.py +0 -0
  20. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/_layout.py +0 -0
  21. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/_location.py +0 -0
  22. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/_names.py +0 -0
  23. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/api/__init__.py +0 -0
  24. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/api/_edge_declarations.py +0 -0
  25. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/api/_marker.py +0 -0
  26. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/calls/__init__.py +0 -0
  27. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/calls/_confined_functions.py +0 -0
  28. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/calls/_marker.py +0 -0
  29. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/__init__.py +0 -0
  30. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_bound_checks.py +0 -0
  31. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_confined_calls.py +0 -0
  32. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_marker.py +0 -0
  33. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_model_boundary.py +0 -0
  34. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_model_columns.py +0 -0
  35. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_raw_sql.py +0 -0
  36. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_schema_drift.py +0 -0
  37. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/database/_statement_keys.py +0 -0
  38. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/effects/__init__.py +0 -0
  39. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/effects/_determinism.py +0 -0
  40. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/effects/_log_events.py +0 -0
  41. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/effects/_marker.py +0 -0
  42. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/errors/__init__.py +0 -0
  43. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/errors/_marker.py +0 -0
  44. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/errors/_refusals.py +0 -0
  45. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/hygiene/_dependency_bounds.py +0 -0
  46. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/hygiene/_marker.py +0 -0
  47. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/imports/__init__.py +0 -0
  48. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/imports/_confined.py +0 -0
  49. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/imports/_marker.py +0 -0
  50. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/imports/_sealed.py +0 -0
  51. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/imports/_statements.py +0 -0
  52. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/__init__.py +0 -0
  53. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/_class_modules.py +0 -0
  54. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/_class_placement.py +0 -0
  55. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/_marker.py +0 -0
  56. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/_operation_shape.py +0 -0
  57. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/placement/_required_class.py +0 -0
  58. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/__init__.py +0 -0
  59. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_function_length.py +0 -0
  60. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_functions.py +0 -0
  61. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_keyword_only.py +0 -0
  62. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_marker.py +0 -0
  63. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_module_length.py +0 -0
  64. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_nesting.py +0 -0
  65. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/signatures/_signature_layout.py +0 -0
  66. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/__init__.py +0 -0
  67. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_annotation_shapes.py +0 -0
  68. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_config_fields.py +0 -0
  69. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_confined_types.py +0 -0
  70. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_constant_annotations.py +0 -0
  71. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_frozen_dataclasses.py +0 -0
  72. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/checks/types/_marker.py +0 -0
  73. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/__init__.py +0 -0
  74. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/_app.py +0 -0
  75. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/_protocols.py +0 -0
  76. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_explain.py +0 -0
  77. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_list.py +0 -0
  78. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_mutation.py +0 -0
  79. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_run.py +0 -0
  80. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_summary.py +0 -0
  81. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/cli/commands/_sync.py +0 -0
  82. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/__init__.py +0 -0
  83. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_base.py +0 -0
  84. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_config.py +0 -0
  85. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_constants.py +0 -0
  86. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_errors.py +0 -0
  87. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_loader.py +0 -0
  88. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/config/_toml.py +0 -0
  89. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/contracts/__init__.py +0 -0
  90. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/contracts/_constants.py +0 -0
  91. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/contracts/_layout.py +0 -0
  92. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/contracts/_render.py +0 -0
  93. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/contracts/_settings.py +0 -0
  94. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/__init__.py +0 -0
  95. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_constants.py +0 -0
  96. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_discovery.py +0 -0
  97. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_edit.py +0 -0
  98. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_errors.py +0 -0
  99. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_fixer.py +0 -0
  100. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_format.py +0 -0
  101. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_markers.py +0 -0
  102. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_paths.py +0 -0
  103. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_protocols.py +0 -0
  104. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_registry.py +0 -0
  105. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_report.py +0 -0
  106. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_runner.py +0 -0
  107. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_settings.py +0 -0
  108. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_source.py +0 -0
  109. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/core/_violation.py +0 -0
  110. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/environment/__init__.py +0 -0
  111. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/environment/_constants.py +0 -0
  112. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/environment/_render.py +0 -0
  113. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/environment/_settings.py +0 -0
  114. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/__init__.py +0 -0
  115. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_baseline.py +0 -0
  116. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_constants.py +0 -0
  117. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_errors.py +0 -0
  118. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_gate.py +0 -0
  119. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_mutmut.py +0 -0
  120. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_process.py +0 -0
  121. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_scope.py +0 -0
  122. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/mutation/_settings.py +0 -0
  123. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/py.typed +0 -0
  124. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/sync/__init__.py +0 -0
  125. {python_checks-0.9.0 → python_checks-0.10.0}/src/py_checks/sync/_sync.py +0 -0
@@ -1,12 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-checks
3
- Version: 0.9.0
3
+ Version: 0.10.0
4
4
  Summary: Проверки архитектурных соглашений проекта
5
5
  Author: Armontex
6
6
  Author-email: Armontex <windle1337@gmail.com>
7
7
  License-Expression: MIT
8
8
  License-File: LICENSE
9
9
  Requires-Dist: libcst>=1.9,<2
10
+ Requires-Dist: pathspec>=1.1,<2
10
11
  Requires-Dist: pydantic>=2.13.5,<3
11
12
  Requires-Dist: pydantic-settings>=2.15.0,<3
12
13
  Requires-Dist: rich>=14.0.0,<16.0.0
@@ -144,10 +145,10 @@ Twenty-eight rules in nine groups:
144
145
  | `api` | what an entrance declares about itself |
145
146
  | `errors` | the code a refusal carries |
146
147
  | `calls` | a function whose call sites can be listed |
147
- | `hygiene` | a ceiling on a dependency |
148
+ | `hygiene` | a ceiling on a dependency, a translation that kept up |
148
149
 
149
150
  <details>
150
- <summary>All twenty-eight</summary>
151
+ <summary>All thirty</summary>
151
152
 
152
153
  | Code | What fails | Scope |
153
154
  |---|---|:-:|
@@ -180,6 +181,7 @@ Twenty-eight rules in nine groups:
180
181
  | `refusals` | a no nobody can branch on | file |
181
182
  | `confined-functions` | a named function was called from somewhere it may not be | file |
182
183
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
184
+ | `translations` | a translated document is missing or no longer matches its source | project |
183
185
 
184
186
  </details>
185
187
 
@@ -206,7 +208,7 @@ text("SELECT 1") # db-ok: raw-sql: a liveness probe, there is no ORM form of it
206
208
 
207
209
  The canonical form is `# check-ok: <code>: <reason>`, and it lifts exactly one
208
210
  rule. Every group has a short word of its own (`# db-ok`, `# type-ok`,
209
- `# signature-ok`, …): a person remembers the group, not twenty-eight codes.
211
+ `# signature-ok`, …): a person remembers the group, not thirty codes.
210
212
 
211
213
  A line may carry several marks — a signature written in a column gathers them
212
214
  on its last line:
@@ -354,6 +356,7 @@ obeys `ignore`, and is lifted by a mark.
354
356
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
355
357
  | `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
356
358
  | `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
359
+ | `py-checks translations stamp <path>…` | stamp a translation with its source's fingerprint, after translating |
357
360
 
358
361
  ## Development
359
362
 
@@ -121,10 +121,10 @@ Twenty-eight rules in nine groups:
121
121
  | `api` | what an entrance declares about itself |
122
122
  | `errors` | the code a refusal carries |
123
123
  | `calls` | a function whose call sites can be listed |
124
- | `hygiene` | a ceiling on a dependency |
124
+ | `hygiene` | a ceiling on a dependency, a translation that kept up |
125
125
 
126
126
  <details>
127
- <summary>All twenty-eight</summary>
127
+ <summary>All thirty</summary>
128
128
 
129
129
  | Code | What fails | Scope |
130
130
  |---|---|:-:|
@@ -157,6 +157,7 @@ Twenty-eight rules in nine groups:
157
157
  | `refusals` | a no nobody can branch on | file |
158
158
  | `confined-functions` | a named function was called from somewhere it may not be | file |
159
159
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
160
+ | `translations` | a translated document is missing or no longer matches its source | project |
160
161
 
161
162
  </details>
162
163
 
@@ -183,7 +184,7 @@ text("SELECT 1") # db-ok: raw-sql: a liveness probe, there is no ORM form of it
183
184
 
184
185
  The canonical form is `# check-ok: <code>: <reason>`, and it lifts exactly one
185
186
  rule. Every group has a short word of its own (`# db-ok`, `# type-ok`,
186
- `# signature-ok`, …): a person remembers the group, not twenty-eight codes.
187
+ `# signature-ok`, …): a person remembers the group, not thirty codes.
187
188
 
188
189
  A line may carry several marks — a signature written in a column gathers them
189
190
  on its last line:
@@ -331,6 +332,7 @@ obeys `ignore`, and is lifted by a mark.
331
332
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
332
333
  | `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
333
334
  | `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
335
+ | `py-checks translations stamp <path>…` | stamp a translation with its source's fingerprint, after translating |
334
336
 
335
337
  ## Development
336
338
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.9.0"
3
+ version = "0.10.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -8,6 +8,7 @@ license-files = ["LICENSE"]
8
8
  requires-python = ">=3.14"
9
9
  dependencies = [
10
10
  "libcst>=1.9,<2",
11
+ "pathspec>=1.1,<2",
11
12
  "pydantic>=2.13.5,<3",
12
13
  "pydantic-settings>=2.15.0,<3",
13
14
  "rich>=14.0.0,<16.0.0",
@@ -61,6 +62,7 @@ schema-drift = "py_checks.checks.database:SchemaDrift"
61
62
  sealed-imports = "py_checks.checks.imports:SealedImports"
62
63
  signature-layout = "py_checks.checks.signatures:SignatureLayout"
63
64
  statement-keys = "py_checks.checks.database:StatementKeys"
65
+ translations = "py_checks.checks.hygiene:Translations"
64
66
 
65
67
  [tool.uv.build-backend]
66
68
  module-name = "py_checks"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.9.0"
3
+ version = "0.10.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -9,6 +9,9 @@ authors = [{ name = "Armontex", email = "windle1337@gmail.com" }]
9
9
  requires-python = ">=3.14"
10
10
  dependencies = [
11
11
  "libcst>=1.9,<2",
12
+ # gitignore-шаблоны `[translations].files`: `**`, ведущий `/`, директории и
13
+ # отрицание — краёв столько, что самописный разбор ошибся бы на части из них.
14
+ "pathspec>=1.1,<2",
12
15
  "pydantic>=2.13.5,<3",
13
16
  "pydantic-settings>=2.15.0,<3",
14
17
  # Floor low, ceiling at the next major: what is used here is `Console` and
@@ -68,6 +71,7 @@ schema-drift = "py_checks.checks.database:SchemaDrift"
68
71
  sealed-imports = "py_checks.checks.imports:SealedImports"
69
72
  signature-layout = "py_checks.checks.signatures:SignatureLayout"
70
73
  statement-keys = "py_checks.checks.database:StatementKeys"
74
+ translations = "py_checks.checks.hygiene:Translations"
71
75
 
72
76
  # Дистрибутив зовётся иначе, чем пакет: имя `py-checks` на PyPI занял сосед.
73
77
  # Сборщик выводит модуль из имени дистрибутива, поэтому имя пакета названо тут.
@@ -1,7 +1,8 @@
1
1
  """Repository hygiene.
2
2
 
3
3
  A dependency declares a ceiling: without one the version is chosen by the
4
- resolver, not by a person. The rest of this group is covered by something
4
+ resolver, not by a person. A translated document still says what its English
5
+ source says. The rest of this group is covered by something
5
6
  other than checks — `.env.example` is generated from the settings models, and
6
7
  `CLAUDE.md` is a symlink to `AGENTS.md`.
7
8
  """
@@ -11,5 +12,6 @@ from py_checks.checks.hygiene._dependency_bounds import (
11
12
  DependencyBoundsSettings,
12
13
  )
13
14
  from py_checks.checks.hygiene._marker import MARKER
15
+ from py_checks.checks.hygiene._translations import Translations
14
16
 
15
- __all__ = ["MARKER", "DependencyBounds", "DependencyBoundsSettings"]
17
+ __all__ = ["MARKER", "DependencyBounds", "DependencyBoundsSettings", "Translations"]
@@ -0,0 +1,169 @@
1
+ """A translated document still says what its English source says."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING, ClassVar, Final
6
+
7
+ from py_checks.checks.hygiene._marker import MARKER
8
+ from py_checks.core import Scope, Violation, settings_as
9
+ from py_checks.translations import (
10
+ SECTION,
11
+ TranslationError,
12
+ TranslationsSettings,
13
+ fingerprint,
14
+ selected,
15
+ source_of,
16
+ stamped,
17
+ tracked,
18
+ translation_of,
19
+ )
20
+
21
+ if TYPE_CHECKING:
22
+ from collections.abc import Iterator
23
+ from pathlib import Path
24
+
25
+ from py_checks.config import CheckSettings
26
+
27
+ CODE: Final = SECTION
28
+
29
+ FIRST: Final = 1
30
+
31
+
32
+ class Translations:
33
+ """Fails when a translation is missing or no longer matches its source.
34
+
35
+ A translation goes stale the moment the English changes, and nothing
36
+ tells anyone: its reader reads a document that is no longer true. A
37
+ document nobody translated is the same problem one step earlier. So the
38
+ check refuses both, the way `py-checks sync --check` refuses a generated
39
+ file that no longer matches what it is built from.
40
+
41
+ English is the source, and each language mirrors the repository under
42
+ `docs/langs/<lang>/` by the same path: `docs/testing.md` is translated in
43
+ `docs/langs/ru/docs/testing.md`. The first line of a translation is the
44
+ SHA-256 of the source as it was when translated, written by
45
+ `py-checks translations stamp <translation>` — never by `run --fix`, which
46
+ would bless a translation nobody updated.
47
+
48
+ Refused: a selected file with no translation; a translation whose source
49
+ changed since; a translation whose source is gone or no longer selected;
50
+ a first line that is not a fingerprint.
51
+
52
+ Candidates are the files git knows and does not ignore, so `.venv/` never
53
+ needs excluding, and `docs/langs/` is never asked for its own translation.
54
+
55
+ Settings: `langs`, `files`.
56
+ """
57
+
58
+ code: ClassVar[str] = CODE
59
+ Settings: ClassVar[type[CheckSettings]] = TranslationsSettings
60
+ scope: ClassVar[Scope] = Scope.PROJECT
61
+ marker: ClassVar[str] = MARKER
62
+
63
+ @classmethod
64
+ def run(
65
+ cls,
66
+ *,
67
+ root: Path,
68
+ settings: CheckSettings,
69
+ ) -> Iterator[Violation]:
70
+ limits = settings_as(
71
+ settings=settings,
72
+ model=TranslationsSettings,
73
+ code=CODE,
74
+ )
75
+ if not limits.langs or not limits.files:
76
+ return
77
+ try:
78
+ paths = tracked(root=root)
79
+ except TranslationError as error:
80
+ yield cls._says(
81
+ path=root,
82
+ message=str(error),
83
+ )
84
+ return
85
+ sources = selected(
86
+ paths=paths,
87
+ files=limits.files,
88
+ )
89
+ for lang in limits.langs:
90
+ yield from cls._missing_or_stale(
91
+ root=root,
92
+ sources=sources,
93
+ lang=lang,
94
+ )
95
+ yield from cls._orphans(
96
+ root=root,
97
+ paths=paths,
98
+ sources=frozenset(sources),
99
+ lang=lang,
100
+ )
101
+
102
+ @classmethod
103
+ def _missing_or_stale(
104
+ cls,
105
+ *,
106
+ root: Path,
107
+ sources: list[str],
108
+ lang: str,
109
+ ) -> Iterator[Violation]:
110
+ """Every selected source: translated, and translated from what it says now."""
111
+ for source in sources:
112
+ translation = translation_of(
113
+ source=source,
114
+ lang=lang,
115
+ )
116
+ path = root / translation
117
+ if not path.is_file():
118
+ yield cls._says(
119
+ path=root / source,
120
+ message=f"{source} has no {lang} translation: {translation}",
121
+ )
122
+ continue
123
+ digest = stamped(path=path)
124
+ if digest is None:
125
+ yield cls._says(
126
+ path=path,
127
+ message=(
128
+ f"{translation}: the first line is not a fingerprint; after translating, "
129
+ f"run `py-checks translations stamp {translation}`"
130
+ ),
131
+ )
132
+ elif digest != fingerprint(path=root / source):
133
+ yield cls._says(
134
+ path=path,
135
+ message=f"{source} changed since {translation} was translated",
136
+ )
137
+
138
+ @classmethod
139
+ def _orphans(
140
+ cls,
141
+ *,
142
+ root: Path,
143
+ paths: list[str],
144
+ sources: frozenset[str],
145
+ lang: str,
146
+ ) -> Iterator[Violation]:
147
+ """A translation whose source is gone or no longer selected."""
148
+ for path in paths:
149
+ pair = source_of(translation=path)
150
+ if pair is None or pair[0] != lang or pair[1] in sources:
151
+ continue
152
+ yield cls._says(
153
+ path=root / path,
154
+ message=f"{path} translates nothing",
155
+ )
156
+
157
+ @staticmethod
158
+ def _says(
159
+ *,
160
+ path: Path,
161
+ message: str,
162
+ ) -> Violation:
163
+ return Violation(
164
+ path=path,
165
+ line=FIRST,
166
+ column=FIRST,
167
+ code=CODE,
168
+ message=message,
169
+ )
@@ -14,6 +14,7 @@ from py_checks.cli.commands._list import register as register_list
14
14
  from py_checks.cli.commands._mutation import register as register_mutation
15
15
  from py_checks.cli.commands._run import register as register_run
16
16
  from py_checks.cli.commands._sync import register as register_sync
17
+ from py_checks.cli.commands._translations import register as register_translations
17
18
 
18
19
  REGISTRARS: Final[tuple[Registrar, ...]] = (
19
20
  register_run,
@@ -22,6 +23,7 @@ REGISTRARS: Final[tuple[Registrar, ...]] = (
22
23
  register_sync,
23
24
  register_doctor,
24
25
  register_mutation,
26
+ register_translations,
25
27
  )
26
28
 
27
29
  __all__ = ["REGISTRARS", "Registrar"]
@@ -16,6 +16,8 @@ from py_checks.contracts import SECTION as CONTRACTS
16
16
  from py_checks.core import ANY, EXIT_OK, EXIT_VIOLATION, SEPARATOR, available, depth, section_of
17
17
  from py_checks.environment import SECTION as ENV_EXAMPLE
18
18
  from py_checks.mutation import SECTION as MUTATION
19
+ from py_checks.translations import SECTION as TRANSLATIONS
20
+ from py_checks.translations import TranslationError, TranslationsSettings, dead, tracked
19
21
 
20
22
  if TYPE_CHECKING:
21
23
  from collections.abc import Iterator
@@ -51,12 +53,17 @@ class Complaint:
51
53
 
52
54
  def doctor() -> None:
53
55
  """Check the settings themselves: typos, dead addresses, silent rules."""
54
- config = load(root=find_root(start=Path.cwd()))
56
+ root = find_root(start=Path.cwd())
57
+ config = load(root=root)
55
58
  found = [
56
59
  *_unknown(config=config),
57
60
  *_ignored(config=config),
58
61
  *_silent(config=config),
59
62
  *_nowhere(config=config),
63
+ *_idle(
64
+ config=config,
65
+ root=root,
66
+ ),
60
67
  ]
61
68
  # A long name is not broken mid-word: the reader will copy it.
62
69
  console = Console(soft_wrap=True)
@@ -266,6 +273,35 @@ def _answers(
266
273
  return True
267
274
 
268
275
 
276
+ def _idle(
277
+ *,
278
+ config: Config,
279
+ root: Path,
280
+ ) -> Iterator[Complaint]:
281
+ """A translation pattern that changes nothing: without it, the same files are selected.
282
+
283
+ It catches a pattern that selects nothing and a `!` that excludes nothing —
284
+ `!.github/` under a `*.md` takes the directory out, not the files in it.
285
+ """
286
+ table = config.checks.get(TRANSLATIONS)
287
+ if table is None:
288
+ return
289
+ try:
290
+ files = TranslationsSettings.model_validate(table).files
291
+ paths = tracked(root=root)
292
+ except ValueError, TranslationError:
293
+ return
294
+ named = prefix(source=config.origin)
295
+ for pattern in dead(
296
+ paths=paths,
297
+ files=files,
298
+ ):
299
+ yield Complaint(
300
+ said="pattern that changes nothing",
301
+ about=f"[{named}{TRANSLATIONS}] — {pattern!r} selects or excludes no file",
302
+ )
303
+
304
+
269
305
  def _addressed(*, config: Config) -> Iterator[tuple[str, str, bool]]:
270
306
  """The addresses written in the settings, and whether each is a zone.
271
307
 
@@ -0,0 +1,98 @@
1
+ """The `translations` command: `stamp` a translation with its source's fingerprint."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Annotated
7
+
8
+ import typer
9
+ from rich.console import Console
10
+
11
+ from py_checks.config import find_root
12
+ from py_checks.core import EXIT_OK, EXIT_VIOLATION
13
+ from py_checks.translations import TranslationError, stamp
14
+
15
+ Paths = Annotated[
16
+ list[Path],
17
+ typer.Argument(help="the translations to stamp, under docs/langs/<lang>/"),
18
+ ]
19
+
20
+ translations = typer.Typer(
21
+ no_args_is_help=True,
22
+ help="Translated documents: each one says which version of its source it was made from.",
23
+ )
24
+
25
+ console = Console(soft_wrap=True)
26
+ errors = Console(
27
+ stderr=True,
28
+ soft_wrap=True,
29
+ )
30
+
31
+
32
+ @translations.command("stamp")
33
+ def stamped( # check-ok: keyword-only-arguments: typer parses the command's signature
34
+ paths: Paths,
35
+ ) -> None:
36
+ """Write the fingerprint of each translation's source on its first line.
37
+
38
+ Only the translations named, and only ones that exist: the translator
39
+ writes the translation, then stamps it. `run --fix` never does this — a fix
40
+ that rewrote the hash would bless a translation nobody updated.
41
+ """
42
+ root = find_root(start=Path.cwd())
43
+ refused = 0
44
+ for path in paths:
45
+ try:
46
+ translation = _within(
47
+ root=root,
48
+ path=path,
49
+ )
50
+ stamp(
51
+ root=root,
52
+ translation=translation,
53
+ )
54
+ except TranslationError as error:
55
+ _say(
56
+ console=errors,
57
+ text=str(error),
58
+ )
59
+ refused += 1
60
+ continue
61
+ _say(
62
+ console=console,
63
+ text=f"stamped {translation}",
64
+ )
65
+ raise typer.Exit(EXIT_VIOLATION if refused else EXIT_OK)
66
+
67
+
68
+ def _within(
69
+ *,
70
+ root: Path,
71
+ path: Path,
72
+ ) -> str:
73
+ """The path from the repository's root, the way the check names it."""
74
+ try:
75
+ return path.resolve().relative_to(root.resolve()).as_posix()
76
+ except ValueError as error:
77
+ message = f"{path} lies outside the project at {root}"
78
+ raise TranslationError(message) from error
79
+
80
+
81
+ def _say(
82
+ *,
83
+ console: Console,
84
+ text: str,
85
+ ) -> None:
86
+ """Print as is: a line is a path, and brackets in it are not markup."""
87
+ console.print(
88
+ text,
89
+ markup=False,
90
+ highlight=False,
91
+ )
92
+
93
+
94
+ def register(*, app: typer.Typer) -> None:
95
+ app.add_typer(
96
+ translations,
97
+ name="translations",
98
+ )
@@ -0,0 +1,30 @@
1
+ """Translated documents and the English sources they were translated from.
2
+
3
+ English is the source. Each language mirrors the repository under
4
+ `docs/langs/<lang>/`, by the same path, so a translation's path alone says
5
+ which file it belongs to. Its first line is the SHA-256 of the source's bytes
6
+ as they were when it was translated: the hash changes exactly when the source
7
+ does, which is exactly when the translation goes stale. A date moves with
8
+ `touch` and a rebase, a commit with any change in the repository.
9
+ """
10
+
11
+ from py_checks.translations._constants import HOME, SECTION
12
+ from py_checks.translations._errors import TranslationError
13
+ from py_checks.translations._settings import TranslationsSettings
14
+ from py_checks.translations._stamp import fingerprint, stamp, stamped
15
+ from py_checks.translations._tree import dead, selected, source_of, tracked, translation_of
16
+
17
+ __all__ = [
18
+ "HOME",
19
+ "SECTION",
20
+ "TranslationError",
21
+ "TranslationsSettings",
22
+ "dead",
23
+ "fingerprint",
24
+ "selected",
25
+ "source_of",
26
+ "stamp",
27
+ "stamped",
28
+ "tracked",
29
+ "translation_of",
30
+ ]
@@ -0,0 +1,15 @@
1
+ """Names every module of the package knows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from typing import Final
7
+
8
+ SECTION: Final = "translations"
9
+
10
+ # Where the languages live, one directory each, mirroring the repository.
11
+ HOME: Final = "docs/langs"
12
+
13
+ # The first line of a translation: the hash of the source it was made from.
14
+ STAMP: Final = "<!-- sha256:{digest} -->"
15
+ STAMPED: Final = re.compile(r"^<!-- sha256:(?P<digest>[0-9a-f]{64}) -->$")
@@ -0,0 +1,7 @@
1
+ """What the package refuses with."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ class TranslationError(RuntimeError):
7
+ """A translation that cannot be judged or stamped, and why."""
@@ -0,0 +1,22 @@
1
+ """The `[translations]` section."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from py_checks.config import CheckSettings
6
+
7
+
8
+ class TranslationsSettings(CheckSettings):
9
+ """Which documents are translated, and into what.
10
+
11
+ `langs` — the languages, each a directory under `docs/langs/`.
12
+ `files` — the documents that need a translation, in gitignore syntax: the
13
+ last match wins, and `!` takes a file back out. A directory is excluded
14
+ with what is under it, `!.github/**`; `!.github/` excludes the directory
15
+ itself, and a `*.md` still matches every file inside it.
16
+
17
+ Either one empty, and the rule is silent: which documents a project
18
+ translates, and into what, only the project knows.
19
+ """
20
+
21
+ langs: tuple[str, ...] = ()
22
+ files: tuple[str, ...] = ()
@@ -0,0 +1,59 @@
1
+ """The fingerprint on a translation's first line."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ from typing import TYPE_CHECKING
7
+
8
+ from py_checks.translations._constants import STAMP, STAMPED
9
+ from py_checks.translations._errors import TranslationError
10
+ from py_checks.translations._tree import source_of
11
+
12
+ if TYPE_CHECKING:
13
+ from pathlib import Path
14
+
15
+
16
+ def fingerprint(*, path: Path) -> str:
17
+ """The SHA-256 of the file's raw bytes.
18
+
19
+ No normalisation: the end-of-file and whitespace hooks keep the bytes
20
+ stable, and a whitespace-only edit that asks for a re-stamp is a cheap
21
+ false alarm.
22
+ """
23
+ return hashlib.sha256(path.read_bytes()).hexdigest()
24
+
25
+
26
+ def stamped(*, path: Path) -> str | None:
27
+ """The digest on the first line; `None` if the first line is not a fingerprint."""
28
+ first = path.read_text(encoding="utf-8").partition("\n")[0]
29
+ found = STAMPED.match(first)
30
+ return None if found is None else found.group("digest")
31
+
32
+
33
+ def stamp(
34
+ *,
35
+ root: Path,
36
+ translation: str,
37
+ ) -> None:
38
+ """Write or refresh the fingerprint of one translation.
39
+
40
+ It never creates a translation: the translator writes it, then stamps it.
41
+ And it is never part of `run --fix`: a fix that rewrote the hash would
42
+ bless a translation nobody updated, the one thing the check exists to stop.
43
+ """
44
+ pair = source_of(translation=translation)
45
+ if pair is None:
46
+ message = f"{translation} is not a translation: it lies outside docs/langs/<lang>/"
47
+ raise TranslationError(message)
48
+ path = root / translation
49
+ source = root / pair[1]
50
+ if not path.is_file():
51
+ message = f"{translation} does not exist: write the translation, then stamp it"
52
+ raise TranslationError(message)
53
+ if not source.is_file():
54
+ message = f"{translation} translates nothing: {pair[1]} does not exist"
55
+ raise TranslationError(message)
56
+ text = path.read_text(encoding="utf-8")
57
+ body = text.partition("\n")[2] if stamped(path=path) is not None else text
58
+ line = STAMP.format(digest=fingerprint(path=source))
59
+ path.write_text(f"{line}\n{body}", encoding="utf-8")
@@ -0,0 +1,104 @@
1
+ """Which files need a translation, and which translation belongs to which file."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import subprocess
6
+ from typing import TYPE_CHECKING, Final
7
+
8
+ from pathspec import GitIgnoreSpec
9
+
10
+ from py_checks.translations._constants import HOME
11
+ from py_checks.translations._errors import TranslationError
12
+
13
+ if TYPE_CHECKING:
14
+ from collections.abc import Iterable
15
+ from pathlib import Path
16
+
17
+ SEPARATOR: Final = "/"
18
+
19
+ # Tracked files and new ones git has not been told to ignore: a document just
20
+ # written is judged before `git add`, and `.venv/` is never a candidate.
21
+ LISTED: Final = ("git", "ls-files", "--cached", "--others", "--exclude-standard", "-z")
22
+
23
+
24
+ def tracked(*, root: Path) -> list[str]:
25
+ """The repository's files, as paths from its root, that exist on disk.
26
+
27
+ A file deleted but not yet staged is still listed by git; it has nothing
28
+ to translate. A symlink is not a document of its own — `CLAUDE.md` pointing
29
+ at `AGENTS.md` is translated once, as `AGENTS.md`.
30
+ """
31
+ try:
32
+ finished = subprocess.run( # noqa: S603 — a fixed list of arguments, no shell
33
+ LISTED,
34
+ cwd=root,
35
+ capture_output=True,
36
+ check=True,
37
+ )
38
+ except (OSError, subprocess.CalledProcessError) as error:
39
+ message = f"{root} is not a git repository: translations are matched against its files"
40
+ raise TranslationError(message) from error
41
+ listed = finished.stdout.decode().split("\0")
42
+ return sorted(
43
+ path
44
+ for path in listed
45
+ if path and (root / path).is_file() and not (root / path).is_symlink()
46
+ )
47
+
48
+
49
+ def selected(
50
+ *,
51
+ paths: Iterable[str],
52
+ files: Iterable[str],
53
+ ) -> list[str]:
54
+ """The sources: the files the patterns select, never a translation itself."""
55
+ spec = GitIgnoreSpec.from_lines(files)
56
+ return [path for path in paths if not _translated(path=path) and spec.match_file(path)]
57
+
58
+
59
+ def dead(
60
+ *,
61
+ paths: Iterable[str],
62
+ files: tuple[str, ...],
63
+ ) -> list[str]:
64
+ """The patterns that change nothing: without one, the same files are selected.
65
+
66
+ One question covers both mistakes — a pattern that selects nothing, and a
67
+ `!` that excludes nothing, like `!.github/` under a `*.md`.
68
+ """
69
+ candidates = list(paths)
70
+ whole = selected(
71
+ paths=candidates,
72
+ files=files,
73
+ )
74
+ return [
75
+ pattern
76
+ for index, pattern in enumerate(files)
77
+ if selected(
78
+ paths=candidates,
79
+ files=files[:index] + files[index + 1 :],
80
+ )
81
+ == whole
82
+ ]
83
+
84
+
85
+ def translation_of(
86
+ *,
87
+ source: str,
88
+ lang: str,
89
+ ) -> str:
90
+ return f"{HOME}/{lang}/{source}"
91
+
92
+
93
+ def source_of(*, translation: str) -> tuple[str, str] | None:
94
+ """The language and the source of a translation; `None` — not one."""
95
+ if not _translated(path=translation):
96
+ return None
97
+ lang, _, source = translation.removeprefix(f"{HOME}/").partition(SEPARATOR)
98
+ if not lang or not source:
99
+ return None
100
+ return lang, source
101
+
102
+
103
+ def _translated(*, path: str) -> bool:
104
+ return path.startswith(f"{HOME}/")
File without changes