python-checks 0.9.0__tar.gz → 0.11.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 (129) hide show
  1. {python_checks-0.9.0 → python_checks-0.11.0}/PKG-INFO +8 -4
  2. {python_checks-0.9.0 → python_checks-0.11.0}/README.md +5 -3
  3. {python_checks-0.9.0 → python_checks-0.11.0}/pyproject.toml +4 -1
  4. {python_checks-0.9.0 → python_checks-0.11.0}/pyproject.toml.orig +9 -1
  5. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/_layout.py +4 -0
  6. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/hygiene/__init__.py +4 -2
  7. python_checks-0.11.0/src/py_checks/checks/hygiene/_translations.py +169 -0
  8. python_checks-0.11.0/src/py_checks/checks/signatures/_callers.py +442 -0
  9. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_keyword_only.py +113 -16
  10. python_checks-0.11.0/src/py_checks/checks/signatures/_stops.py +173 -0
  11. python_checks-0.11.0/src/py_checks/checks/signatures/_targets.py +265 -0
  12. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/__init__.py +2 -0
  13. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_doctor.py +45 -3
  14. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_run.py +16 -3
  15. python_checks-0.11.0/src/py_checks/cli/commands/_translations.py +98 -0
  16. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/__init__.py +4 -1
  17. python_checks-0.11.0/src/py_checks/core/_fixer.py +172 -0
  18. python_checks-0.11.0/src/py_checks/translations/__init__.py +30 -0
  19. python_checks-0.11.0/src/py_checks/translations/_constants.py +15 -0
  20. python_checks-0.11.0/src/py_checks/translations/_errors.py +7 -0
  21. python_checks-0.11.0/src/py_checks/translations/_settings.py +22 -0
  22. python_checks-0.11.0/src/py_checks/translations/_stamp.py +59 -0
  23. python_checks-0.11.0/src/py_checks/translations/_tree.py +104 -0
  24. python_checks-0.9.0/src/py_checks/core/_fixer.py +0 -55
  25. {python_checks-0.9.0 → python_checks-0.11.0}/LICENSE +0 -0
  26. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/__init__.py +0 -0
  27. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/__init__.py +0 -0
  28. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/_kind.py +0 -0
  29. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/_location.py +0 -0
  30. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/_names.py +0 -0
  31. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/api/__init__.py +0 -0
  32. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/api/_edge_declarations.py +0 -0
  33. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/api/_marker.py +0 -0
  34. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/calls/__init__.py +0 -0
  35. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/calls/_confined_functions.py +0 -0
  36. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/calls/_marker.py +0 -0
  37. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/__init__.py +0 -0
  38. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_bound_checks.py +0 -0
  39. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_confined_calls.py +0 -0
  40. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_marker.py +0 -0
  41. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_model_boundary.py +0 -0
  42. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_model_columns.py +0 -0
  43. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_raw_sql.py +0 -0
  44. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_schema_drift.py +0 -0
  45. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/database/_statement_keys.py +0 -0
  46. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/effects/__init__.py +0 -0
  47. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/effects/_determinism.py +0 -0
  48. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/effects/_log_events.py +0 -0
  49. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/effects/_marker.py +0 -0
  50. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/errors/__init__.py +0 -0
  51. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/errors/_marker.py +0 -0
  52. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/errors/_refusals.py +0 -0
  53. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/hygiene/_dependency_bounds.py +0 -0
  54. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/hygiene/_marker.py +0 -0
  55. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/imports/__init__.py +0 -0
  56. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/imports/_confined.py +0 -0
  57. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/imports/_marker.py +0 -0
  58. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/imports/_sealed.py +0 -0
  59. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/imports/_statements.py +0 -0
  60. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/__init__.py +0 -0
  61. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/_class_modules.py +0 -0
  62. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/_class_placement.py +0 -0
  63. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/_marker.py +0 -0
  64. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/_operation_shape.py +0 -0
  65. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/placement/_required_class.py +0 -0
  66. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/__init__.py +0 -0
  67. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_function_length.py +0 -0
  68. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_functions.py +0 -0
  69. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_marker.py +0 -0
  70. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_module_length.py +0 -0
  71. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_nesting.py +0 -0
  72. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/signatures/_signature_layout.py +0 -0
  73. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/__init__.py +0 -0
  74. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_annotation_shapes.py +0 -0
  75. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_config_fields.py +0 -0
  76. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_confined_types.py +0 -0
  77. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_constant_annotations.py +0 -0
  78. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_frozen_dataclasses.py +0 -0
  79. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/checks/types/_marker.py +0 -0
  80. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/__init__.py +0 -0
  81. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/_app.py +0 -0
  82. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/_protocols.py +0 -0
  83. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_explain.py +0 -0
  84. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_list.py +0 -0
  85. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_mutation.py +0 -0
  86. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_summary.py +0 -0
  87. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/cli/commands/_sync.py +0 -0
  88. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/__init__.py +0 -0
  89. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_base.py +0 -0
  90. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_config.py +0 -0
  91. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_constants.py +0 -0
  92. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_errors.py +0 -0
  93. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_loader.py +0 -0
  94. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/config/_toml.py +0 -0
  95. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/contracts/__init__.py +0 -0
  96. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/contracts/_constants.py +0 -0
  97. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/contracts/_layout.py +0 -0
  98. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/contracts/_render.py +0 -0
  99. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/contracts/_settings.py +0 -0
  100. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_constants.py +0 -0
  101. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_discovery.py +0 -0
  102. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_edit.py +0 -0
  103. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_errors.py +0 -0
  104. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_format.py +0 -0
  105. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_markers.py +0 -0
  106. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_paths.py +0 -0
  107. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_protocols.py +0 -0
  108. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_registry.py +0 -0
  109. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_report.py +0 -0
  110. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_runner.py +0 -0
  111. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_settings.py +0 -0
  112. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_source.py +0 -0
  113. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/core/_violation.py +0 -0
  114. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/environment/__init__.py +0 -0
  115. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/environment/_constants.py +0 -0
  116. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/environment/_render.py +0 -0
  117. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/environment/_settings.py +0 -0
  118. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/__init__.py +0 -0
  119. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_baseline.py +0 -0
  120. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_constants.py +0 -0
  121. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_errors.py +0 -0
  122. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_gate.py +0 -0
  123. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_mutmut.py +0 -0
  124. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_process.py +0 -0
  125. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_scope.py +0 -0
  126. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/mutation/_settings.py +0 -0
  127. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/py.typed +0 -0
  128. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/sync/__init__.py +0 -0
  129. {python_checks-0.9.0 → python_checks-0.11.0}/src/py_checks/sync/_sync.py +0 -0
@@ -1,12 +1,14 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-checks
3
- Version: 0.9.0
3
+ Version: 0.11.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
+ Requires-Dist: jedi>=0.19.2,<0.20
9
10
  Requires-Dist: libcst>=1.9,<2
11
+ Requires-Dist: pathspec>=1.1,<2
10
12
  Requires-Dist: pydantic>=2.13.5,<3
11
13
  Requires-Dist: pydantic-settings>=2.15.0,<3
12
14
  Requires-Dist: rich>=14.0.0,<16.0.0
@@ -144,10 +146,10 @@ Twenty-eight rules in nine groups:
144
146
  | `api` | what an entrance declares about itself |
145
147
  | `errors` | the code a refusal carries |
146
148
  | `calls` | a function whose call sites can be listed |
147
- | `hygiene` | a ceiling on a dependency |
149
+ | `hygiene` | a ceiling on a dependency, a translation that kept up |
148
150
 
149
151
  <details>
150
- <summary>All twenty-eight</summary>
152
+ <summary>All thirty</summary>
151
153
 
152
154
  | Code | What fails | Scope |
153
155
  |---|---|:-:|
@@ -180,6 +182,7 @@ Twenty-eight rules in nine groups:
180
182
  | `refusals` | a no nobody can branch on | file |
181
183
  | `confined-functions` | a named function was called from somewhere it may not be | file |
182
184
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
185
+ | `translations` | a translated document is missing or no longer matches its source | project |
183
186
 
184
187
  </details>
185
188
 
@@ -206,7 +209,7 @@ text("SELECT 1") # db-ok: raw-sql: a liveness probe, there is no ORM form of it
206
209
 
207
210
  The canonical form is `# check-ok: <code>: <reason>`, and it lifts exactly one
208
211
  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.
212
+ `# signature-ok`, …): a person remembers the group, not thirty codes.
210
213
 
211
214
  A line may carry several marks — a signature written in a column gathers them
212
215
  on its last line:
@@ -354,6 +357,7 @@ obeys `ignore`, and is lifted by a mark.
354
357
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
355
358
  | `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
356
359
  | `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
360
+ | `py-checks translations stamp <path>…` | stamp a translation with its source's fingerprint, after translating |
357
361
 
358
362
  ## Development
359
363
 
@@ -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,13 +1,15 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.9.0"
3
+ version = "0.11.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
7
7
  license-files = ["LICENSE"]
8
8
  requires-python = ">=3.14"
9
9
  dependencies = [
10
+ "jedi>=0.19.2,<0.20",
10
11
  "libcst>=1.9,<2",
12
+ "pathspec>=1.1,<2",
11
13
  "pydantic>=2.13.5,<3",
12
14
  "pydantic-settings>=2.15.0,<3",
13
15
  "rich>=14.0.0,<16.0.0",
@@ -61,6 +63,7 @@ schema-drift = "py_checks.checks.database:SchemaDrift"
61
63
  sealed-imports = "py_checks.checks.imports:SealedImports"
62
64
  signature-layout = "py_checks.checks.signatures:SignatureLayout"
63
65
  statement-keys = "py_checks.checks.database:StatementKeys"
66
+ translations = "py_checks.checks.hygiene:Translations"
64
67
 
65
68
  [tool.uv.build-backend]
66
69
  module-name = "py_checks"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.9.0"
3
+ version = "0.11.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -8,7 +8,14 @@ license-files = ["LICENSE"]
8
8
  authors = [{ name = "Armontex", email = "windle1337@gmail.com" }]
9
9
  requires-python = ">=3.14"
10
10
  dependencies = [
11
+ # `--fix` у keyword-only-arguments: чей это вызов — наш, чужой или ничей.
12
+ # Без вывода типов `self._repo.get(x)` не отличить от `dict.get`, а вызов,
13
+ # который не разрешился, останавливает правку, а не ломает его.
14
+ "jedi>=0.19.2,<0.20",
11
15
  "libcst>=1.9,<2",
16
+ # gitignore-шаблоны `[translations].files`: `**`, ведущий `/`, директории и
17
+ # отрицание — краёв столько, что самописный разбор ошибся бы на части из них.
18
+ "pathspec>=1.1,<2",
12
19
  "pydantic>=2.13.5,<3",
13
20
  "pydantic-settings>=2.15.0,<3",
14
21
  # Floor low, ceiling at the next major: what is used here is `Console` and
@@ -68,6 +75,7 @@ schema-drift = "py_checks.checks.database:SchemaDrift"
68
75
  sealed-imports = "py_checks.checks.imports:SealedImports"
69
76
  signature-layout = "py_checks.checks.signatures:SignatureLayout"
70
77
  statement-keys = "py_checks.checks.database:StatementKeys"
78
+ translations = "py_checks.checks.hygiene:Translations"
71
79
 
72
80
  # Дистрибутив зовётся иначе, чем пакет: имя `py-checks` на PyPI занял сосед.
73
81
  # Сборщик выводит модуль из имени дистрибутива, поэтому имя пакета названо тут.
@@ -114,6 +114,9 @@ class Directory(CheckSettings):
114
114
  `operation` — the shape of an operation, if operations are kept here.
115
115
  `orm` — what the directory is to an ORM model: its home or where it is built.
116
116
  `base` — the base class by which a model is recognised in the models' home.
117
+ `optional` — the directory may not exist yet: the block says where code
118
+ goes, not where it already is, and `doctor` does not ask the tree for it.
119
+ The rules judge it as soon as a file turns up there.
117
120
  """
118
121
 
119
122
  only: tuple[Kind, ...] = ()
@@ -125,6 +128,7 @@ class Directory(CheckSettings):
125
128
  operation: Operation | None = None
126
129
  orm: Orm | None = None
127
130
  base: str | None = None
131
+ optional: bool = False
128
132
 
129
133
  @property
130
134
  def restricted(self) -> bool:
@@ -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
+ )