basstler-rules 4.2.0__py3-none-any.whl

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 (40) hide show
  1. basstler/code_modification/__init__.py +7 -0
  2. basstler/code_modification/actions.py +171 -0
  3. basstler/code_modification/exceptions.py +127 -0
  4. basstler/code_modification/file_actions.py +141 -0
  5. basstler/code_modification/module_relocation.py +256 -0
  6. basstler/code_modification/patterns.py +86 -0
  7. basstler/code_modification/positions.py +39 -0
  8. basstler/code_modification/references.py +45 -0
  9. basstler/code_modification/source_file.py +27 -0
  10. basstler/code_modification/source_tree.py +107 -0
  11. basstler/code_modification/specification.py +41 -0
  12. basstler/code_modification/syntax.py +209 -0
  13. basstler/code_rules/__init__.py +4 -0
  14. basstler/code_rules/address_building.py +94 -0
  15. basstler/code_rules/bash_by_name.py +103 -0
  16. basstler/code_rules/checker.py +163 -0
  17. basstler/code_rules/command_line.py +165 -0
  18. basstler/code_rules/commands.py +47 -0
  19. basstler/code_rules/docstring_presence.py +255 -0
  20. basstler/code_rules/exceptions.py +34 -0
  21. basstler/code_rules/fixes.py +307 -0
  22. basstler/code_rules/instructions.py +80 -0
  23. basstler/code_rules/locale_encoding.py +315 -0
  24. basstler/code_rules/package_boundaries.py +344 -0
  25. basstler/code_rules/prose_length.py +220 -0
  26. basstler/code_rules/rule.py +158 -0
  27. basstler/code_rules/rule_module.py +84 -0
  28. basstler/code_rules/rules/__init__.py +3 -0
  29. basstler/code_rules/rules/code_quality.py +848 -0
  30. basstler/code_rules/rules/project.py +171 -0
  31. basstler/code_rules/subprocess_function.py +26 -0
  32. basstler/code_rules/syntax_tree_checker.py +38 -0
  33. basstler/code_rules/text_file_usage.py +146 -0
  34. basstler/code_rules/tree_removal.py +64 -0
  35. basstler/templates/agents.md.jinja +16 -0
  36. basstler_rules-4.2.0.dist-info/METADATA +15 -0
  37. basstler_rules-4.2.0.dist-info/RECORD +40 -0
  38. basstler_rules-4.2.0.dist-info/WHEEL +4 -0
  39. basstler_rules-4.2.0.dist-info/licenses/LICENSE +202 -0
  40. basstler_rules-4.2.0.dist-info/licenses/NOTICE +13 -0
@@ -0,0 +1,86 @@
1
+ """
2
+ The patterns a syntax tree is searched for, each declared once as a libcst matcher.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from abc import ABC, abstractmethod
8
+ from collections.abc import Iterator, Mapping, Sequence
9
+ from dataclasses import dataclass
10
+
11
+ import libcst
12
+ from libcst import matchers
13
+ from libcst.metadata import CodeRange, MetadataWrapper
14
+
15
+ from basstler.class_property import classproperty
16
+ from basstler.code_modification.positions import PositionedModule
17
+
18
+ # %% occurrences
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Occurrence:
23
+ """
24
+ A node that satisfies a pattern, and where it lies in its module.
25
+ """
26
+
27
+ node: libcst.CSTNode
28
+ """
29
+ The node.
30
+ """
31
+
32
+ location: CodeRange
33
+ """
34
+ The code range of :attr:`node`.
35
+ """
36
+
37
+
38
+ # %% patterns
39
+
40
+
41
+ class CodePattern(ABC):
42
+ """
43
+ A shape of code, which the nodes of a syntax tree either have or lack.
44
+ """
45
+
46
+ @classproperty
47
+ @abstractmethod
48
+ def matcher(cls) -> matchers.BaseMatcherNode | matchers.OneOf | matchers.AllOf:
49
+ """
50
+ The matcher the nodes of the pattern satisfy; one pattern builds on another
51
+ through the other's matcher.
52
+ """
53
+
54
+ @classmethod
55
+ def matches(
56
+ cls, node: libcst.CSTNode, metadata: MetadataWrapper | None = None
57
+ ) -> bool:
58
+ """
59
+ :param metadata: Resolves the metadata of *node*, which only a pattern matching
60
+ on metadata needs.
61
+ :return: Whether *node* has the shape of the pattern.
62
+ """
63
+ return matchers.matches(node, cls.matcher, metadata_resolver=metadata)
64
+
65
+ @classmethod
66
+ def captures(
67
+ cls, node: libcst.CSTNode, metadata: MetadataWrapper | None = None
68
+ ) -> Mapping[str, libcst.CSTNode | Sequence[libcst.CSTNode]] | None:
69
+ """
70
+ :param metadata: Resolves the metadata of *node*, which only a pattern matching
71
+ on metadata needs.
72
+ :return: The nodes *node* holds that the matcher saved by name; ``None`` where
73
+ *node* lacks the shape of the pattern.
74
+ """
75
+ return matchers.extract(node, cls.matcher, metadata_resolver=metadata)
76
+
77
+ @classmethod
78
+ def found_in(cls, module: PositionedModule) -> Iterator[Occurrence]:
79
+ """
80
+ :return: Every node of *module* with the shape of the pattern, in the order of
81
+ the source.
82
+ """
83
+ for node in matchers.findall(
84
+ module.module, cls.matcher, metadata_resolver=module.metadata
85
+ ):
86
+ yield Occurrence(node, module.positions[node])
@@ -0,0 +1,39 @@
1
+ """
2
+ A parsed Python module and where each of its nodes lies in its source.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from collections.abc import Mapping
8
+ from dataclasses import dataclass
9
+ from functools import cached_property
10
+
11
+ import libcst
12
+ from libcst.metadata import CodeRange, MetadataWrapper, PositionProvider
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class PositionedModule:
17
+ """
18
+ A module's concrete syntax tree, with the code range each of its nodes spans.
19
+ """
20
+
21
+ module: libcst.Module
22
+ """
23
+ The tree, which keeps every comment and all whitespace of the source.
24
+ """
25
+
26
+ @cached_property
27
+ def metadata(self) -> MetadataWrapper:
28
+ """
29
+ Resolves the metadata of the nodes of :attr:`module` itself, not of a copy.
30
+ """
31
+ return MetadataWrapper(self.module, unsafe_skip_copy=True)
32
+
33
+ @cached_property
34
+ def positions(self) -> Mapping[libcst.CSTNode, CodeRange]:
35
+ """
36
+ The code range of each node of :attr:`module`, keyed by the node itself; lines
37
+ count from one, columns from zero.
38
+ """
39
+ return self.metadata.resolve(PositionProvider)
@@ -0,0 +1,45 @@
1
+ """
2
+ The matcher of a name that refers to a given object, however the file imports it.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ from libcst import matchers
10
+ from libcst.metadata import QualifiedName, QualifiedNameProvider
11
+
12
+ # %% the reference
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class ReferenceTo:
17
+ """
18
+ A name or attribute that refers to a module, or to something in it, through the
19
+ imports of the file it is in.
20
+ """
21
+
22
+ qualified_name: str
23
+ """
24
+ The dotted name of the module, function or class referred to, as ``shutil.rmtree``.
25
+ """
26
+
27
+ @property
28
+ def matcher(self) -> matchers.MatchMetadataIfTrue:
29
+ """
30
+ The matcher a name or attribute satisfies when it refers to
31
+ :attr:`qualified_name` or to a member of it; a pattern using it is found with
32
+ the metadata of its module.
33
+ """
34
+ return matchers.MatchMetadataIfTrue(QualifiedNameProvider, self.is_referred_to)
35
+
36
+ def is_referred_to(self, names: set[QualifiedName]) -> bool:
37
+ """
38
+ :param names: The qualified names a node refers to.
39
+ :return: Whether one of them is :attr:`qualified_name` or a member of it.
40
+ """
41
+ return any(
42
+ name.name == self.qualified_name
43
+ or name.name.startswith(f"{self.qualified_name}.")
44
+ for name in names
45
+ )
@@ -0,0 +1,27 @@
1
+ """
2
+ Python source files and the concrete syntax trees parsed from them.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ import libcst
10
+
11
+ from basstler.text_file import TextFile
12
+
13
+ # %% the file
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class PythonSourceFile(TextFile):
18
+ """
19
+ A file holding a Python module's source.
20
+ """
21
+
22
+ def parse(self) -> libcst.Module:
23
+ """
24
+ :return: The module's concrete syntax tree, which keeps every comment and all
25
+ whitespace of the source.
26
+ """
27
+ return libcst.parse_module(self.read())
@@ -0,0 +1,107 @@
1
+ """
2
+ A snapshot of the files of a source tree, which actions change without touching disk.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import os
8
+ import stat
9
+ from collections.abc import Iterable, Mapping
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+
13
+ # %% the tree
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class SourceTree:
18
+ """
19
+ Every file of a tree and its content, by its path relative to the tree's root.
20
+ """
21
+
22
+ files: Mapping[Path, bytes]
23
+ """
24
+ The content of each file, by its path relative to the tree's root.
25
+ """
26
+
27
+ executable: frozenset[Path] = field(default_factory=frozenset)
28
+ """
29
+ The files of :attr:`files` that are executable.
30
+ """
31
+
32
+ @classmethod
33
+ def read(cls, root: Path, paths: Iterable[Path]) -> SourceTree:
34
+ """
35
+ :param root: The directory the tree is read from.
36
+ :param paths: The files to read, relative to *root*.
37
+ :return: The tree of those files as *root* holds them.
38
+ """
39
+ paths = tuple(paths)
40
+ return cls(
41
+ {path: (root / path).read_bytes() for path in paths},
42
+ frozenset(
43
+ path for path in paths if (root / path).stat().st_mode & stat.S_IXUSR
44
+ ),
45
+ )
46
+
47
+ @classmethod
48
+ def of_directory(cls, root: Path) -> SourceTree:
49
+ """
50
+ :param root: A directory.
51
+ :return: The tree of every file under *root*.
52
+ """
53
+ return cls.read(
54
+ root,
55
+ sorted(
56
+ path.relative_to(root) for path in root.rglob("*") if path.is_file()
57
+ ),
58
+ )
59
+
60
+ def with_files(
61
+ self,
62
+ added: Mapping[Path, bytes],
63
+ removed: Iterable[Path] = (),
64
+ executable: Iterable[Path] = (),
65
+ ) -> SourceTree:
66
+ """
67
+ :param added: Files to add or overwrite, with their content.
68
+ :param removed: Files to leave out.
69
+ :param executable: The files of *added* that are executable; a file overwritten
70
+ keeps whether it was.
71
+ :return: This tree with *removed* left out and *added* in place.
72
+ """
73
+ removed_paths = set(removed)
74
+ files = {
75
+ path: content
76
+ for path, content in self.files.items()
77
+ if path not in removed_paths
78
+ }
79
+ return SourceTree(
80
+ {**files, **added},
81
+ (self.executable - removed_paths) | frozenset(executable),
82
+ )
83
+
84
+ def write(self, root: Path, previous: SourceTree) -> None:
85
+ """
86
+ Turn the files *previous* describes under *root* into this tree, removing every
87
+ directory that leaves empty.
88
+
89
+ :param root: The directory *previous* describes.
90
+ :param previous: The tree *root* holds now.
91
+ """
92
+ for path in previous.files.keys() - self.files.keys():
93
+ (root / path).unlink()
94
+ for directory in (root / path).parents:
95
+ if directory == root or any(directory.iterdir()):
96
+ break
97
+ directory.rmdir()
98
+ for path, content in self.files.items():
99
+ if previous.files.get(path) != content:
100
+ (root / path).parent.mkdir(parents=True, exist_ok=True)
101
+ (root / path).write_bytes(content)
102
+ mode = (root / path).stat().st_mode
103
+ executable_bits = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
104
+ if path in self.executable:
105
+ os.chmod(root / path, mode | executable_bits)
106
+ else:
107
+ os.chmod(root / path, mode & ~executable_bits)
@@ -0,0 +1,41 @@
1
+ """
2
+ The base of every specification: what one place in a module must become.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ import libcst
10
+ from libcst.metadata import CodeRange
11
+
12
+
13
+ @dataclass(frozen=True)
14
+ class Specification:
15
+ """
16
+ One place in a module that has to change, as an analysis found it; a subclass adds
17
+ the facts the change depends on.
18
+ """
19
+
20
+ location: CodeRange
21
+ """
22
+ The code range of :attr:`node` in the module it was found in.
23
+ """
24
+
25
+ node: libcst.CSTNode
26
+ """
27
+ The node that has to change.
28
+ """
29
+
30
+ def overlaps(self, other: Specification) -> bool:
31
+ """
32
+ :return: Whether this place and *other* share any character, so that changing
33
+ one changes the other.
34
+ """
35
+ return (other.location.start.line, other.location.start.column) < (
36
+ self.location.end.line,
37
+ self.location.end.column,
38
+ ) and (self.location.start.line, self.location.start.column) < (
39
+ other.location.end.line,
40
+ other.location.end.column,
41
+ )
@@ -0,0 +1,209 @@
1
+ """
2
+ What an expression or a call says, read from its concrete syntax tree without running
3
+ it, and calls changed to pass other arguments.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from enum import StrEnum
10
+ from functools import cached_property
11
+
12
+ import libcst
13
+
14
+ # %% names
15
+
16
+
17
+ class ConstantName(StrEnum):
18
+ """
19
+ The names Python binds to constants rather than to variables.
20
+ """
21
+
22
+ TRUE = str(True)
23
+ """
24
+ The name of :data:`True`.
25
+ """
26
+
27
+ FALSE = str(False)
28
+ """
29
+ The name of :data:`False`.
30
+ """
31
+
32
+ NONE = str(None)
33
+ """
34
+ The name of :data:`None`.
35
+ """
36
+
37
+
38
+ # %% expressions
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class ExpressionSyntax:
43
+ """
44
+ An expression's syntax tree, and what it says.
45
+ """
46
+
47
+ expression: libcst.BaseExpression
48
+ """
49
+ The expression.
50
+ """
51
+
52
+ @property
53
+ def final_name(self) -> str | None:
54
+ """
55
+ The last name the expression refers to: ``read_text`` for ``path.read_text``,
56
+ ``dict`` for ``dict[str, int]``; ``None`` when it refers to no name.
57
+ """
58
+ expression = self.expression
59
+ if isinstance(expression, libcst.Name):
60
+ return expression.value
61
+ if isinstance(expression, libcst.Attribute):
62
+ return expression.attr.value
63
+ if isinstance(expression, libcst.Subscript):
64
+ return ExpressionSyntax(expression.value).final_name
65
+ return None
66
+
67
+ @property
68
+ def is_constant(self) -> bool:
69
+ """
70
+ Whether the expression is a literal number, string, bytes or ellipsis, or a
71
+ :class:`ConstantName`.
72
+ """
73
+ expression = self.expression
74
+ if isinstance(expression, libcst.Name):
75
+ return expression.value in tuple(ConstantName)
76
+ if isinstance(expression, libcst.ConcatenatedString):
77
+ return expression.evaluated_value is not None
78
+ return isinstance(
79
+ expression,
80
+ libcst.SimpleString
81
+ | libcst.Integer
82
+ | libcst.Float
83
+ | libcst.Imaginary
84
+ | libcst.Ellipsis,
85
+ )
86
+
87
+ @property
88
+ def literal_text(self) -> str | None:
89
+ """
90
+ The text a literal string expression evaluates to; ``None`` for any other
91
+ expression, a bytes literal and a formatted string included.
92
+ """
93
+ expression = self.expression
94
+ if not isinstance(expression, libcst.SimpleString | libcst.ConcatenatedString):
95
+ return None
96
+ value = expression.evaluated_value
97
+ return value if isinstance(value, str) else None
98
+
99
+
100
+ # %% calls
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class CallSyntax:
105
+ """
106
+ A call's syntax tree: the arguments it passes, and the call changed to pass others.
107
+ """
108
+
109
+ call: libcst.Call
110
+ """
111
+ The call.
112
+ """
113
+
114
+ @staticmethod
115
+ def keyword_argument(keyword: str, value: libcst.BaseExpression) -> libcst.Arg:
116
+ """
117
+ :return: The argument passing *value* as *keyword*, with no space around its
118
+ ``=``.
119
+ """
120
+ no_space = libcst.SimpleWhitespace("")
121
+ return libcst.Arg(
122
+ value,
123
+ keyword=libcst.Name(keyword),
124
+ equal=libcst.AssignEqual(
125
+ whitespace_before=no_space, whitespace_after=no_space
126
+ ),
127
+ )
128
+
129
+ def with_argument_appended(self, argument: libcst.Arg) -> libcst.Call:
130
+ """
131
+ :return: The call passing *argument* after its other arguments, laid out as
132
+ they are: where a trailing comma ends them, it ends *argument* instead.
133
+ """
134
+ arguments = self.call.args
135
+ if not arguments or not isinstance(arguments[-1].comma, libcst.Comma):
136
+ return self.call.with_changes(args=[*arguments, argument])
137
+ last = arguments[-1]
138
+ whitespace_before_last = (
139
+ arguments[-2].comma.whitespace_after
140
+ if len(arguments) > 1
141
+ else self.call.whitespace_before_args
142
+ )
143
+ return self.call.with_changes(
144
+ args=[
145
+ *arguments[:-1],
146
+ last.with_changes(
147
+ comma=last.comma.with_changes(
148
+ whitespace_after=whitespace_before_last
149
+ )
150
+ ),
151
+ argument.with_changes(comma=last.comma),
152
+ ]
153
+ )
154
+
155
+ def with_argument_replaced(
156
+ self, original: libcst.Arg, replacement: libcst.Arg
157
+ ) -> libcst.Call:
158
+ """
159
+ :param original: An argument of the call.
160
+ :return: The call passing *replacement* in place of *original*, keeping the
161
+ comma and whitespace around *original*.
162
+ """
163
+ return libcst.ensure_type(
164
+ self.call.deep_replace(
165
+ original,
166
+ original.with_changes(
167
+ keyword=replacement.keyword, value=replacement.value
168
+ ),
169
+ ),
170
+ libcst.Call,
171
+ )
172
+
173
+
174
+ # %% bodies
175
+
176
+
177
+ @dataclass(frozen=True)
178
+ class BodySyntax:
179
+ """
180
+ The statements of a module, class or function body, one by one.
181
+ """
182
+
183
+ body: libcst.Module | libcst.BaseSuite
184
+ """
185
+ The module, or the suite of a class or function.
186
+ """
187
+
188
+ @cached_property
189
+ def statements(self) -> tuple[libcst.CSTNode, ...]:
190
+ """
191
+ The statements of the body in order, those sharing a line included.
192
+ """
193
+ statements: list[libcst.CSTNode] = []
194
+ for statement in self.body.body:
195
+ if isinstance(statement, libcst.SimpleStatementLine):
196
+ statements.extend(statement.body)
197
+ continue
198
+ statements.append(statement)
199
+ return tuple(statements)
200
+
201
+ @staticmethod
202
+ def is_string(statement: libcst.CSTNode) -> bool:
203
+ """
204
+ :return: Whether *statement* is a bare string literal.
205
+ """
206
+ return (
207
+ isinstance(statement, libcst.Expr)
208
+ and ExpressionSyntax(statement.value).literal_text is not None
209
+ )
@@ -0,0 +1,4 @@
1
+ """
2
+ The rules agents follow in this repository, generated into ``AGENTS.md``, and the
3
+ checkers that enforce some of them.
4
+ """
@@ -0,0 +1,94 @@
1
+ """
2
+ Finds addresses appended to a repository's own address by hand, outside the class that
3
+ builds every address within a repository.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import ast
9
+ from collections.abc import Iterator
10
+ from dataclasses import dataclass
11
+ from enum import StrEnum
12
+ from pathlib import Path
13
+ from typing import override
14
+
15
+ from basstler.code_rules.checker import CodeRuleChecker, CodeRuleViolation
16
+ from basstler.locations import PackageLocation
17
+ from basstler.text_file import TextFile
18
+
19
+ # %% what is an address
20
+
21
+
22
+ class RepositoryAddress(StrEnum):
23
+ """
24
+ The attributes of a repository whose value is an address more is appended to.
25
+ """
26
+
27
+ API_PATH = "api_path"
28
+ """
29
+ The repository's REST path.
30
+ """
31
+
32
+ URL = "url"
33
+ """
34
+ The repository's page.
35
+ """
36
+
37
+ SETTINGS_URL = "settings_url"
38
+ """
39
+ The repository's settings page.
40
+ """
41
+
42
+
43
+ # %% the checker
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class HandBuiltAddressChecker(CodeRuleChecker):
48
+ """
49
+ Reports every f-string of the package that starts with a repository's address and
50
+ appends a path to it, outside :attr:`PackageLocation.GITHUB_REPOSITORY_MODULE`;
51
+ tests spell the addresses they pin.
52
+ """
53
+
54
+ package_directory: Path = PackageLocation.DIRECTORY
55
+ """
56
+ The directory whose sources are checked.
57
+ """
58
+
59
+ @override
60
+ def violations(self, path: Path) -> Iterator[CodeRuleViolation]:
61
+ source = path.resolve()
62
+ if source == PackageLocation.GITHUB_REPOSITORY_MODULE.resolve():
63
+ return
64
+ if not source.is_relative_to(self.package_directory.resolve()):
65
+ return
66
+ for node in ast.walk(ast.parse(TextFile(path).read())):
67
+ if isinstance(node, ast.JoinedStr) and self.appends_to_an_address(node):
68
+ yield CodeRuleViolation(
69
+ path,
70
+ node.lineno,
71
+ node.end_lineno or node.lineno,
72
+ "an address built by hand on a repository's address; build it "
73
+ "with a method of the class of what it addresses, such as "
74
+ "Repository",
75
+ )
76
+
77
+ @staticmethod
78
+ def appends_to_an_address(text: ast.JoinedStr) -> bool:
79
+ """
80
+ :param text: An f-string.
81
+ :return: Whether it starts with a repository's address and continues with a
82
+ path below it.
83
+ """
84
+ if len(text.values) < 2:
85
+ return False
86
+ first, second = text.values[0], text.values[1]
87
+ return (
88
+ isinstance(first, ast.FormattedValue)
89
+ and isinstance(first.value, ast.Attribute)
90
+ and first.value.attr in set(RepositoryAddress)
91
+ and isinstance(second, ast.Constant)
92
+ and isinstance(second.value, str)
93
+ and second.value.startswith("/")
94
+ )