basstler-rules 4.2.0__tar.gz → 4.2.2__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 (67) hide show
  1. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/PKG-INFO +3 -3
  2. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/command_line.py +1 -6
  3. basstler_rules-4.2.2/src/basstler/code_rules/package_boundaries.py +594 -0
  4. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/rules/project.py +3 -1
  5. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_package_boundaries.py +172 -6
  6. basstler_rules-4.2.0/src/basstler/code_rules/package_boundaries.py +0 -344
  7. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/.gitignore +0 -0
  8. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/LICENSE +0 -0
  9. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/NOTICE +0 -0
  10. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/pyproject.toml +0 -0
  11. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/__init__.py +0 -0
  12. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/actions.py +0 -0
  13. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/exceptions.py +0 -0
  14. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/file_actions.py +0 -0
  15. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/module_relocation.py +0 -0
  16. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/patterns.py +0 -0
  17. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/positions.py +0 -0
  18. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/references.py +0 -0
  19. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/source_file.py +0 -0
  20. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/source_tree.py +0 -0
  21. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/specification.py +0 -0
  22. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_modification/syntax.py +0 -0
  23. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/__init__.py +0 -0
  24. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/address_building.py +0 -0
  25. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/bash_by_name.py +0 -0
  26. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/checker.py +0 -0
  27. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/commands.py +0 -0
  28. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/docstring_presence.py +0 -0
  29. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/exceptions.py +0 -0
  30. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/fixes.py +0 -0
  31. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/instructions.py +0 -0
  32. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/locale_encoding.py +0 -0
  33. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/prose_length.py +0 -0
  34. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/rule.py +0 -0
  35. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/rule_module.py +0 -0
  36. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/rules/__init__.py +0 -0
  37. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/rules/code_quality.py +0 -0
  38. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/subprocess_function.py +0 -0
  39. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/syntax_tree_checker.py +0 -0
  40. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/text_file_usage.py +0 -0
  41. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/code_rules/tree_removal.py +0 -0
  42. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/src/basstler/templates/agents.md.jinja +0 -0
  43. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/__init__.py +0 -0
  44. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/__init__.py +0 -0
  45. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_actions.py +0 -0
  46. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_file_actions.py +0 -0
  47. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_module_relocation.py +0 -0
  48. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_patterns.py +0 -0
  49. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_references.py +0 -0
  50. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_specification.py +0 -0
  51. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_modification/test_syntax.py +0 -0
  52. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/__init__.py +0 -0
  53. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/conftest.py +0 -0
  54. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/fix_example.py +0 -0
  55. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/marked_snippet.py +0 -0
  56. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_address_building.py +0 -0
  57. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_bash_by_name.py +0 -0
  58. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_checker.py +0 -0
  59. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_command_line.py +0 -0
  60. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_docstring_presence.py +0 -0
  61. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_fixes.py +0 -0
  62. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_instructions.py +0 -0
  63. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_locale_encoding.py +0 -0
  64. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_prose_length.py +0 -0
  65. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_text_file_usage.py +0 -0
  66. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/code_rules/test_tree_removal.py +0 -0
  67. {basstler_rules-4.2.0 → basstler_rules-4.2.2}/tests/conftest.py +0 -0
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: basstler-rules
3
- Version: 4.2.0
3
+ Version: 4.2.2
4
4
  Summary: The code rules, their checkers and fixes, and the generated AGENTS.md.
5
5
  Project-URL: Source, https://github.com/KAOS-repositories/basstler
6
6
  Project-URL: Bug Tracker, https://github.com/KAOS-repositories/basstler/issues
7
7
  Author-email: Abdelrhman Bassiouny <bido.bassuny@gmail.com>
8
8
  License-Expression: Apache-2.0
9
9
  Requires-Python: >=3.12
10
- Requires-Dist: basstler-core==4.2.0
11
- Requires-Dist: basstler-git==4.2.0
10
+ Requires-Dist: basstler-core==4.2.2
11
+ Requires-Dist: basstler-git==4.2.2
12
12
  Requires-Dist: cyclopts>=5.3
13
13
  Requires-Dist: libcst>=1.8
@@ -132,12 +132,7 @@ def report_new_crossings(base_commit: str) -> CodeRulesExitCode:
132
132
  renames = checker.module_renames(git, base_commit)
133
133
  added = checker.package_crossings().added_since(base_crossings.renamed(renames))
134
134
  for crossing in added:
135
- logger.error(
136
- "basstler.%s newly imports basstler.%s across a distribution boundary; "
137
- "move the code or the import",
138
- crossing.importing_module,
139
- crossing.imported_module,
140
- )
135
+ logger.error(crossing.new_import_message())
141
136
  if added:
142
137
  return CodeRulesExitCode.CHANGES_NEEDED
143
138
  return CodeRulesExitCode.SUCCESS
@@ -0,0 +1,594 @@
1
+ """
2
+ Finds imports that cross from one distribution into another it does not list, or into a
3
+ third-party library it does not require.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import importlib.metadata
9
+ import re
10
+ import sys
11
+ import tempfile
12
+ from abc import ABC, abstractmethod
13
+ from collections.abc import Iterable, Iterator, Mapping
14
+ from dataclasses import dataclass, field
15
+ from functools import cached_property
16
+ from pathlib import Path
17
+ from types import TracebackType
18
+
19
+ import libcst
20
+ from libcst.helpers import get_full_name_for_node
21
+
22
+ from basstler.code_modification.patterns import Occurrence
23
+ from basstler.code_modification.positions import PositionedModule
24
+ from basstler.code_modification.source_file import PythonSourceFile
25
+ from basstler.code_rules.checker import CodeRuleChecker, CodeRuleViolation
26
+ from basstler.directory_tree import DirectoryTree
27
+ from basstler.git.commands import GitCommandRunner
28
+ from basstler.locations import PackageLocation, WorkspaceLocation
29
+ from basstler.module import Module
30
+ from basstler.package_map import REQUIREMENT_NAME, Workspace
31
+
32
+ # %% imports
33
+
34
+
35
+ @dataclass(frozen=True, order=True)
36
+ class HasImportedModule:
37
+ """
38
+ Something that names a module of a distribution another module imports.
39
+ """
40
+
41
+ imported_module: Module
42
+ """
43
+ The module imported, relative to ``basstler``.
44
+ """
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class ImportStatement(Occurrence):
49
+ """
50
+ An absolute import statement, for one imported module.
51
+ """
52
+
53
+ module: Module
54
+ """
55
+ The module imported, or read from, as the statement spells it.
56
+ """
57
+
58
+ names: tuple[str, ...]
59
+ """
60
+ The names a ``from`` import takes from :attr:`module`; none for a plain import.
61
+ """
62
+
63
+
64
+ @dataclass(frozen=True)
65
+ class ModuleImport(HasImportedModule):
66
+ """
67
+ One module of the package that an import statement imports.
68
+ """
69
+
70
+ statement: ImportStatement
71
+ """
72
+ The statement importing it.
73
+ """
74
+
75
+
76
+ @dataclass(frozen=True, order=True)
77
+ class ImportCrossing(ABC):
78
+ """
79
+ A module importing something its own distribution may not.
80
+ """
81
+
82
+ importing_module: Module
83
+ """
84
+ The module holding the import, relative to ``basstler``.
85
+ """
86
+
87
+ @abstractmethod
88
+ def new_import_message(self) -> str:
89
+ """
90
+ :return: The error reporting that the module newly holds this import.
91
+ """
92
+
93
+
94
+ @dataclass(frozen=True, order=True)
95
+ class BoundaryCrossing(HasImportedModule, ImportCrossing):
96
+ """
97
+ A module importing a module of a distribution its own distribution does not list.
98
+ """
99
+
100
+ def new_import_message(self) -> str:
101
+ return (
102
+ f"{self.importing_module.absolute} newly imports "
103
+ f"{self.imported_module.absolute} across a distribution boundary; "
104
+ "move the code or the import"
105
+ )
106
+
107
+
108
+ @dataclass(frozen=True, order=True)
109
+ class LibraryCrossing(ImportCrossing):
110
+ """
111
+ A module importing a third-party library its own distribution does not require.
112
+ """
113
+
114
+ imported_library: Module
115
+ """
116
+ The top-level package imported.
117
+ """
118
+
119
+ def new_import_message(self) -> str:
120
+ return (
121
+ f"{self.importing_module.absolute} newly imports the library "
122
+ f"{self.imported_library}, which its distribution does not require; "
123
+ "require it in the distribution's pyproject.toml or move the import"
124
+ )
125
+
126
+
127
+ @dataclass(frozen=True)
128
+ class ModuleRenames:
129
+ """
130
+ The modules of the package a change moved.
131
+ """
132
+
133
+ new_module_by_old_module: Mapping[Module, Module]
134
+ """
135
+ Each moved module, relative to ``basstler``, as it was before the change and as it
136
+ is after.
137
+ """
138
+
139
+ def current_module(self, module: Module) -> Module:
140
+ """
141
+ :param module: A module as it was before the change.
142
+ :return: It as it is after the change; *module* itself when it did not move.
143
+ """
144
+ return self.new_module_by_old_module.get(module, module)
145
+
146
+
147
+ @dataclass(frozen=True)
148
+ class PackageCrossings:
149
+ """
150
+ Every boundary crossing of one checkout of the package.
151
+ """
152
+
153
+ crossings: tuple[BoundaryCrossing, ...]
154
+ """
155
+ The crossings of distributions, each once, ordered by importing and then imported
156
+ module.
157
+ """
158
+
159
+ library_crossings: tuple[LibraryCrossing, ...] = ()
160
+ """
161
+ The crossings of libraries, each once, ordered by importing module and then library.
162
+ """
163
+
164
+ @property
165
+ def all_crossings(self) -> tuple[ImportCrossing, ...]:
166
+ """
167
+ The crossings of distributions, then those of libraries.
168
+ """
169
+ return (*self.crossings, *self.library_crossings)
170
+
171
+ def added_since(self, base: PackageCrossings) -> tuple[ImportCrossing, ...]:
172
+ """
173
+ :param base: The crossings of the checkout this one is compared with.
174
+ :return: The crossings this checkout has and *base* does not.
175
+ """
176
+ return tuple(
177
+ crossing
178
+ for crossing in self.all_crossings
179
+ if crossing not in base.all_crossings
180
+ )
181
+
182
+ def renamed(self, renames: ModuleRenames) -> PackageCrossings:
183
+ """
184
+ :param renames: The modules a change moved.
185
+ :return: These crossings, with each module named as it is after the change.
186
+ """
187
+ return PackageCrossings(
188
+ crossings=tuple(
189
+ BoundaryCrossing(
190
+ importing_module=renames.current_module(crossing.importing_module),
191
+ imported_module=renames.current_module(crossing.imported_module),
192
+ )
193
+ for crossing in self.crossings
194
+ ),
195
+ library_crossings=tuple(
196
+ LibraryCrossing(
197
+ importing_module=renames.current_module(crossing.importing_module),
198
+ imported_library=crossing.imported_library,
199
+ )
200
+ for crossing in self.library_crossings
201
+ ),
202
+ )
203
+
204
+
205
+ # %% installed libraries
206
+
207
+ EXTRA_MARKER = re.compile(r"\bextra\s*==")
208
+ """
209
+ The environment marker of a requirement that only an extra brings in.
210
+ """
211
+
212
+
213
+ @dataclass(frozen=True)
214
+ class InstalledLibraries:
215
+ """
216
+ The distributions installed in the running environment and what each requires.
217
+ """
218
+
219
+ @staticmethod
220
+ def canonical_distribution_name(name: str) -> str:
221
+ """
222
+ :param name: A distribution's name as any requirement or metadata spells it.
223
+ :return: The name with runs of ``-``, ``_`` and ``.`` read as one ``-``, in lower
224
+ case.
225
+ """
226
+ return re.sub(r"[-_.]+", "-", name).lower()
227
+
228
+ @cached_property
229
+ def distributions_by_package(self) -> Mapping[str, frozenset[str]]:
230
+ """
231
+ The names of the distributions providing each top-level importable package.
232
+ """
233
+ return {
234
+ package: frozenset(map(self.canonical_distribution_name, names))
235
+ for package, names in importlib.metadata.packages_distributions().items()
236
+ }
237
+
238
+ @cached_property
239
+ def requirements_by_distribution(self) -> Mapping[str, frozenset[str]]:
240
+ """
241
+ The names of the distributions each installed distribution requires, without
242
+ those only an extra requires.
243
+ """
244
+ return {
245
+ self.canonical_distribution_name(distribution.metadata["Name"]): frozenset(
246
+ self.canonical_distribution_name(
247
+ REQUIREMENT_NAME.match(requirement).group()
248
+ )
249
+ for requirement in distribution.requires or ()
250
+ if not EXTRA_MARKER.search(requirement)
251
+ )
252
+ for distribution in importlib.metadata.distributions()
253
+ }
254
+
255
+ def distributions_providing_package(self, package: Module) -> frozenset[str]:
256
+ """
257
+ :param package: A top-level importable package.
258
+ :return: The distributions providing it; none when it is installed nowhere.
259
+ """
260
+ return self.distributions_by_package.get(str(package), frozenset())
261
+
262
+ def resolve_required_distributions(self, names: Iterable[str]) -> frozenset[str]:
263
+ """
264
+ :param names: Names of distributions, as a ``pyproject.toml`` spells them.
265
+ :return: Them and every distribution they require in turn, each canonically
266
+ named.
267
+ """
268
+ closure: set[str] = set()
269
+ pending = [self.canonical_distribution_name(name) for name in names]
270
+ while pending:
271
+ name = pending.pop()
272
+ if name in closure:
273
+ continue
274
+ closure.add(name)
275
+ pending.extend(self.requirements_by_distribution.get(name, ()))
276
+ return frozenset(closure)
277
+
278
+
279
+ # %% the checker
280
+
281
+
282
+ @dataclass(frozen=True)
283
+ class PackageBoundaryChecker(CodeRuleChecker):
284
+ """
285
+ Reports an import of a distribution the importing module's distribution does not
286
+ list.
287
+ """
288
+
289
+ workspace: Workspace = field(
290
+ default_factory=lambda: Workspace(PackageLocation.SOURCE_TREE.value)
291
+ )
292
+ """
293
+ The distributions checked; files outside their parts of ``basstler`` are not.
294
+ """
295
+
296
+ installed_libraries: InstalledLibraries = field(default_factory=InstalledLibraries)
297
+ """
298
+ The libraries installed, which the imported ones are mapped to.
299
+ """
300
+
301
+ @cached_property
302
+ def namespace_root(self) -> Module:
303
+ """
304
+ The package every distribution's modules lie in.
305
+ """
306
+ return Module.from_dotted_name(PackageLocation.DIRECTORY.name)
307
+
308
+ def violations(self, path: Path) -> Iterator[CodeRuleViolation]:
309
+ module = self.module_of_file(path)
310
+ if module is None:
311
+ return
312
+ importing = self.workspace.package_map.claiming(module.dotted_name)
313
+ for crossing in self.crossings(path):
314
+ imported = self.workspace.package_map.claiming(
315
+ crossing.imported_module.dotted_name
316
+ )
317
+ yield CodeRuleViolation(
318
+ path,
319
+ crossing.statement.location.start.line,
320
+ crossing.statement.location.end.line,
321
+ f"{importing.distribution} imports {crossing.imported_module.absolute} "
322
+ f"from {imported.distribution}, which its pyproject.toml does not list; "
323
+ "move the code or the import",
324
+ )
325
+ for statement in self.library_crossings(path):
326
+ yield CodeRuleViolation(
327
+ path,
328
+ statement.location.start.line,
329
+ statement.location.end.line,
330
+ f"{importing.distribution} imports {statement.module.top_level_package}"
331
+ ", which neither its pyproject.toml nor a distribution it lists "
332
+ "requires; require it there or move the import",
333
+ )
334
+
335
+ def package_crossings(self) -> PackageCrossings:
336
+ """
337
+ :return: The crossings of every module of :attr:`workspace`.
338
+ """
339
+ paths = {
340
+ path: module
341
+ for directory in self.workspace.namespace_package.directories
342
+ for path in directory.rglob("*.py")
343
+ if (module := self.module_of_file(path)) is not None
344
+ }
345
+ return PackageCrossings(
346
+ crossings=tuple(
347
+ sorted(
348
+ {
349
+ BoundaryCrossing(module, crossing.imported_module)
350
+ for path, module in paths.items()
351
+ for crossing in self.crossings(path)
352
+ }
353
+ )
354
+ ),
355
+ library_crossings=tuple(
356
+ sorted(
357
+ {
358
+ LibraryCrossing(module, crossing.module.top_level_package)
359
+ for path, module in paths.items()
360
+ for crossing in self.library_crossings(path)
361
+ }
362
+ )
363
+ ),
364
+ )
365
+
366
+ def module_renames(self, git: GitCommandRunner, base_commit: str) -> ModuleRenames:
367
+ """
368
+ :param git: The checkout of the package.
369
+ :param base_commit: The commit the checked out package is compared with.
370
+ :return: The modules of :attr:`workspace` git detects as moved since
371
+ *base_commit*.
372
+ """
373
+ listing = git.run(
374
+ "diff",
375
+ "--name-status",
376
+ "--find-renames",
377
+ "--diff-filter=R",
378
+ "--relative",
379
+ base_commit,
380
+ "HEAD",
381
+ "--",
382
+ str(self.workspace.root / WorkspaceLocation.PACKAGES),
383
+ )
384
+ new_module_by_old_module = {}
385
+ for line in listing.splitlines():
386
+ _, old_path, new_path = line.split("\t")
387
+ old_module = self.module_of_file(git.working_directory / old_path)
388
+ new_module = self.module_of_file(git.working_directory / new_path)
389
+ if old_path.endswith(".py") and old_module and new_module:
390
+ new_module_by_old_module[old_module] = new_module
391
+ return ModuleRenames(new_module_by_old_module)
392
+
393
+ def module_of_file(self, path: Path) -> Module | None:
394
+ """
395
+ :param path: A Python source file.
396
+ :return: The module it holds, relative to ``basstler``; none for a file outside
397
+ every distribution's part of it.
398
+ """
399
+ source = path.resolve()
400
+ directory = next(
401
+ (
402
+ directory.resolve()
403
+ for directory in self.workspace.namespace_package.directories
404
+ if source.is_relative_to(directory.resolve())
405
+ ),
406
+ None,
407
+ )
408
+ if directory is None:
409
+ return None
410
+ parts = source.relative_to(directory).with_suffix("").parts
411
+ return Module(
412
+ parts[:-1] if parts[-1] == "__init__" else parts, self.namespace_root
413
+ )
414
+
415
+ def crossings(self, path: Path) -> Iterator[ModuleImport]:
416
+ """
417
+ :param path: A source file of a module some distribution claims.
418
+ :return: Every import in it of a module of a distribution the module's own
419
+ distribution does not list.
420
+ """
421
+ importing = self.workspace.package_map.claiming(
422
+ self.module_of_file(path).dotted_name
423
+ )
424
+ allowed = {importing.distribution, *importing.dependencies}
425
+ for module_import in self.module_imports(path):
426
+ imported = self.workspace.package_map.claiming(
427
+ module_import.imported_module.dotted_name
428
+ )
429
+ if imported is None or imported.distribution in allowed:
430
+ continue
431
+ yield module_import
432
+
433
+ def library_crossings(self, path: Path) -> Iterator[ImportStatement]:
434
+ """
435
+ :param path: A source file of a module some distribution claims.
436
+ :return: Every import in it of a library neither its own distribution nor a
437
+ distribution it lists requires, directly or through what they require.
438
+ """
439
+ importing = self.workspace.package_map.claiming(
440
+ self.module_of_file(path).dotted_name
441
+ )
442
+ allowed = self.installed_libraries.resolve_required_distributions(
443
+ self.workspace.package_map.libraries_required_by_distribution(
444
+ importing.distribution
445
+ )
446
+ )
447
+ for statement in self.library_imports(path):
448
+ providers = self.installed_libraries.distributions_providing_package(
449
+ statement.module.top_level_package
450
+ )
451
+ if not providers & allowed:
452
+ yield statement
453
+
454
+ def library_imports(self, path: Path) -> Iterator[ImportStatement]:
455
+ """
456
+ :param path: A Python source file.
457
+ :return: Every import in it of a package that is neither the standard library
458
+ nor ``basstler``.
459
+ """
460
+ for statement in self.import_statements(path):
461
+ package = statement.module.top_level_package
462
+ if package != self.namespace_root and str(package) not in (
463
+ sys.stdlib_module_names
464
+ ):
465
+ yield statement
466
+
467
+ def module_imports(self, path: Path) -> Iterator[ModuleImport]:
468
+ """
469
+ :param path: A Python source file.
470
+ :return: Every import in it of a module of the package.
471
+ """
472
+ for statement in self.import_statements(path):
473
+ if not statement.module.is_within(self.namespace_root):
474
+ continue
475
+ package = statement.module.relative_to(self.namespace_root)
476
+ if not statement.names and package.parts:
477
+ yield ModuleImport(package, statement)
478
+ for name in statement.names:
479
+ yield ModuleImport(
480
+ self.resolve_imported_module(package, name), statement
481
+ )
482
+
483
+ def import_statements(self, path: Path) -> Iterator[ImportStatement]:
484
+ """
485
+ :param path: A Python source file.
486
+ :return: Each of its absolute imports, one per imported module.
487
+ """
488
+ module = PositionedModule(PythonSourceFile(path).parse())
489
+ for statement, location in module.positions.items():
490
+ if isinstance(statement, libcst.Import):
491
+ for alias in statement.names:
492
+ yield ImportStatement(
493
+ statement, location, self.spelled_module(alias.name), ()
494
+ )
495
+ if isinstance(statement, libcst.ImportFrom) and not statement.relative:
496
+ names = (
497
+ ["*"]
498
+ if isinstance(statement.names, libcst.ImportStar)
499
+ else [
500
+ str(self.spelled_module(alias.name))
501
+ for alias in statement.names
502
+ ]
503
+ )
504
+ yield ImportStatement(
505
+ statement,
506
+ location,
507
+ self.spelled_module(statement.module),
508
+ tuple(names),
509
+ )
510
+
511
+ @staticmethod
512
+ def spelled_module(name: libcst.Attribute | libcst.Name | None) -> Module:
513
+ """
514
+ :return: The module *name* spells; the module without parts where there is none.
515
+ """
516
+ return Module.from_dotted_name(
517
+ get_full_name_for_node(name) or "" if name is not None else ""
518
+ )
519
+
520
+ def resolve_imported_module(self, package: Module, name: str) -> Module:
521
+ """
522
+ :param package: The module, relative to ``basstler``, a ``from`` import reads
523
+ from.
524
+ :param name: A name it imports.
525
+ :return: The module *name* is, when it is one, else *package*.
526
+ """
527
+ candidate = Module((*package.parts, name), package.root)
528
+ namespace_package = self.workspace.namespace_package
529
+ if namespace_package.every(candidate.path) or namespace_package.every(
530
+ candidate.path.with_suffix(".py")
531
+ ):
532
+ return candidate
533
+ return package
534
+
535
+
536
+ # %% the package at another commit
537
+
538
+
539
+ @dataclass
540
+ class PackageAtCommit:
541
+ """
542
+ The workspace as one commit holds it, in a detached worktree removed on exit.
543
+ """
544
+
545
+ git: GitCommandRunner
546
+ """
547
+ The checkout the worktree is added to.
548
+ """
549
+
550
+ commit: str
551
+ """
552
+ The commit checked out.
553
+ """
554
+
555
+ workspace_root: Path
556
+ """
557
+ The workspace's root in :attr:`git`'s checkout.
558
+ """
559
+
560
+ directory: Path = field(init=False)
561
+ """
562
+ The worktree's root, once entered.
563
+ """
564
+
565
+ def __enter__(self) -> PackageBoundaryChecker | None:
566
+ """
567
+ :return: A checker of the workspace at :attr:`commit`, under the package map
568
+ its distributions declare there; none when it holds no distributions.
569
+ """
570
+ self.directory = Path(tempfile.mkdtemp())
571
+ self.git.run(
572
+ "worktree", "add", "--detach", "--quiet", str(self.directory), self.commit
573
+ )
574
+ workspace = Workspace(
575
+ self.directory
576
+ / self.workspace_root.resolve().relative_to(
577
+ self.git.working_directory.resolve()
578
+ )
579
+ )
580
+ if not workspace.package_directories:
581
+ return None
582
+ return PackageBoundaryChecker(workspace)
583
+
584
+ def __exit__(
585
+ self,
586
+ exception_type: type[BaseException] | None,
587
+ exception: BaseException | None,
588
+ traceback: TracebackType | None,
589
+ ) -> None:
590
+ """
591
+ Remove the worktree, whether or not the workspace was read.
592
+ """
593
+ self.git.attempt("worktree", "remove", "--force", str(self.directory))
594
+ DirectoryTree(self.directory).remove()
@@ -66,7 +66,9 @@ class PackageAndPluginRules(Section):
66
66
  "A package imports only the basstler packages its pyproject lists: every "
67
67
  "module belongs to the distribution whose `packages/<part>` folder holds it, "
68
68
  "and imports only from that distribution and the ones its `pyproject.toml` "
69
- f"lists, which {CodeReference(package_map).path} reads into layers",
69
+ f"lists, which {CodeReference(package_map).path} reads into layers; it imports "
70
+ "only the third-party libraries that `pyproject.toml` or a distribution it "
71
+ "lists requires, directly or through what those libraries require",
70
72
  (),
71
73
  PackageBoundaryChecker(),
72
74
  )