smelt-cli 0.2.0__py3-none-win_amd64.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 (133) hide show
  1. smelt/__init__.py +6 -0
  2. smelt/__main__.py +5 -0
  3. smelt/analysis/__init__.py +45 -0
  4. smelt/analysis/annotations.py +105 -0
  5. smelt/analysis/cache.py +168 -0
  6. smelt/analysis/context.py +147 -0
  7. smelt/analysis/contracts.py +210 -0
  8. smelt/analysis/coverage.py +377 -0
  9. smelt/analysis/definition_blocks.py +569 -0
  10. smelt/analysis/enum_values.py +217 -0
  11. smelt/analysis/errors.py +11 -0
  12. smelt/analysis/exports.py +166 -0
  13. smelt/analysis/files.py +279 -0
  14. smelt/analysis/function_usage.py +123 -0
  15. smelt/analysis/graphs.py +77 -0
  16. smelt/analysis/identity.py +64 -0
  17. smelt/analysis/import_cache.py +98 -0
  18. smelt/analysis/imports.py +452 -0
  19. smelt/analysis/literals.py +17 -0
  20. smelt/analysis/member_state.py +108 -0
  21. smelt/analysis/members.py +975 -0
  22. smelt/analysis/ordering.py +399 -0
  23. smelt/analysis/ordering_rewrite.py +232 -0
  24. smelt/analysis/package_exports.py +58 -0
  25. smelt/analysis/parsing.py +126 -0
  26. smelt/analysis/python_version.py +164 -0
  27. smelt/analysis/retained.py +84 -0
  28. smelt/analysis/syntax.py +109 -0
  29. smelt/analysis/test_awaits.py +91 -0
  30. smelt/analysis/test_cases.py +84 -0
  31. smelt/analysis/test_deadlines.py +90 -0
  32. smelt/analysis/test_outcomes.py +71 -0
  33. smelt/analysis/test_subprocesses.py +107 -0
  34. smelt/analysis/test_syntax.py +1425 -0
  35. smelt/analysis/test_timing.py +76 -0
  36. smelt/analysis/type_dispatch.py +193 -0
  37. smelt/analysis/workspace.py +146 -0
  38. smelt/cli/__init__.py +3 -0
  39. smelt/cli/app.py +300 -0
  40. smelt/cli/commands/__init__.py +62 -0
  41. smelt/cli/commands/adopt.py +274 -0
  42. smelt/cli/commands/check.py +151 -0
  43. smelt/cli/commands/discover.py +51 -0
  44. smelt/cli/commands/info.py +112 -0
  45. smelt/cli/session.py +163 -0
  46. smelt/cli/session_slots.py +43 -0
  47. smelt/cli/support.py +90 -0
  48. smelt/config/__init__.py +36 -0
  49. smelt/config/discovery.py +93 -0
  50. smelt/config/errors.py +51 -0
  51. smelt/config/loader.py +282 -0
  52. smelt/config/models.py +717 -0
  53. smelt/config/patterns.py +47 -0
  54. smelt/config/schema.py +23 -0
  55. smelt/config/source.py +56 -0
  56. smelt/config/validation.py +180 -0
  57. smelt/diagnostics/__init__.py +0 -0
  58. smelt/diagnostics/debt.py +226 -0
  59. smelt/diagnostics/dedupe.py +41 -0
  60. smelt/diagnostics/groups.py +109 -0
  61. smelt/diagnostics/render/__init__.py +0 -0
  62. smelt/diagnostics/render/machine.py +237 -0
  63. smelt/diagnostics/render/text.py +321 -0
  64. smelt/diagnostics/report.py +104 -0
  65. smelt/diagnostics/suppressions.py +80 -0
  66. smelt/diagnostics/violation.py +120 -0
  67. smelt/docs.py +98 -0
  68. smelt/engine/__init__.py +0 -0
  69. smelt/engine/briefing.py +630 -0
  70. smelt/engine/cache.py +65 -0
  71. smelt/engine/changes.py +260 -0
  72. smelt/engine/check.py +724 -0
  73. smelt/engine/coverage.py +151 -0
  74. smelt/engine/evaluation.py +291 -0
  75. smelt/engine/file_checks.py +94 -0
  76. smelt/engine/git_source.py +140 -0
  77. smelt/engine/inference.py +854 -0
  78. smelt/engine/mirror_inference.py +95 -0
  79. smelt/engine/native_git.py +190 -0
  80. smelt/engine/ordering_fixes.py +132 -0
  81. smelt/engine/paths.py +163 -0
  82. smelt/engine/result_cache.py +208 -0
  83. smelt/engine/rule_settings.py +164 -0
  84. smelt/engine/schema.py +58 -0
  85. smelt/engine/staged.py +75 -0
  86. smelt/engine/workspace.py +5 -0
  87. smelt/model/__init__.py +9 -0
  88. smelt/model/architecture.py +234 -0
  89. smelt/py.typed +0 -0
  90. smelt/rules/__init__.py +0 -0
  91. smelt/rules/activation.py +129 -0
  92. smelt/rules/base.py +131 -0
  93. smelt/rules/catalog.json +600 -0
  94. smelt/rules/common.py +164 -0
  95. smelt/rules/dependencies/__init__.py +0 -0
  96. smelt/rules/dependencies/composition_root.py +86 -0
  97. smelt/rules/dependencies/cycles.py +329 -0
  98. smelt/rules/dependencies/fanout.py +81 -0
  99. smelt/rules/dependencies/features.py +165 -0
  100. smelt/rules/dependencies/interfaces.py +84 -0
  101. smelt/rules/dependencies/layers.py +138 -0
  102. smelt/rules/dependencies/third_party.py +132 -0
  103. smelt/rules/member_names.py +13 -0
  104. smelt/rules/meta.py +74 -0
  105. smelt/rules/registry.py +132 -0
  106. smelt/rules/structure/__init__.py +0 -0
  107. smelt/rules/structure/assignments.py +114 -0
  108. smelt/rules/structure/contracts.py +71 -0
  109. smelt/rules/structure/coverage.py +100 -0
  110. smelt/rules/structure/enum_values.py +50 -0
  111. smelt/rules/structure/headers.py +143 -0
  112. smelt/rules/structure/import_style.py +145 -0
  113. smelt/rules/structure/layout.py +202 -0
  114. smelt/rules/structure/members.py +116 -0
  115. smelt/rules/structure/naming.py +132 -0
  116. smelt/rules/structure/ordering.py +83 -0
  117. smelt/rules/structure/package_imports.py +117 -0
  118. smelt/rules/structure/type_dispatch.py +79 -0
  119. smelt/rules/testing/__init__.py +0 -0
  120. smelt/rules/testing/awaits.py +46 -0
  121. smelt/rules/testing/cases.py +47 -0
  122. smelt/rules/testing/location.py +537 -0
  123. smelt/rules/testing/mocking.py +140 -0
  124. smelt/rules/testing/outcomes.py +119 -0
  125. smelt/rules/testing/private_access.py +93 -0
  126. smelt/rules/testing/public_attributes.py +62 -0
  127. smelt/rules/testing/public_functions.py +52 -0
  128. smelt/rules/testing/timing.py +62 -0
  129. smelt_cli-0.2.0.data/scripts/smelt.exe +0 -0
  130. smelt_cli-0.2.0.dist-info/METADATA +103 -0
  131. smelt_cli-0.2.0.dist-info/RECORD +133 -0
  132. smelt_cli-0.2.0.dist-info/WHEEL +4 -0
  133. smelt_cli-0.2.0.dist-info/sboms/smelt-cli.cyclonedx.json +5462 -0
@@ -0,0 +1,537 @@
1
+ from __future__ import annotations
2
+
3
+ import difflib
4
+ import posixpath
5
+ import re
6
+ from dataclasses import dataclass
7
+ from functools import cache
8
+ from typing import TYPE_CHECKING
9
+
10
+ from smelt.analysis.context import AnalysisContext, Index
11
+ from smelt.analysis.exports import resolve_dotted
12
+ from smelt.config.patterns import path_matches
13
+ from smelt.diagnostics.violation import Category, Severity, Violation
14
+ from smelt.model import is_within
15
+ from smelt.rules.activation import POLICIES
16
+ from smelt.rules.base import BaseRule, RuleDoc
17
+ from smelt.rules.common import display_module_path
18
+
19
+ if TYPE_CHECKING:
20
+ from collections.abc import Iterator
21
+
22
+ from smelt.analysis.files import TestFile
23
+ from smelt.analysis.syntax import ModuleSyntax
24
+
25
+
26
+ def _first_party_module(ctx: AnalysisContext, qualname: str) -> str | None:
27
+ """The longest source module that prefixes ``qualname``."""
28
+ parts = qualname.split(".")
29
+ for end in range(len(parts), 0, -1):
30
+ candidate = ".".join(parts[:end])
31
+ if candidate in ctx.files.sources:
32
+ return candidate
33
+ return None
34
+
35
+
36
+ @dataclass(frozen=True, slots=True)
37
+ class _Import:
38
+ """A first-party name a test imports and the module that defines it."""
39
+
40
+ name: str # ``ChannelCommands``, or the module for ``import``/``from . import x``
41
+ module: str
42
+ via: str | None = None # the package facade that re-exports it
43
+
44
+
45
+ def _resolved_imports(ctx: AnalysisContext, syntax: ModuleSyntax) -> list[_Import]:
46
+ """First-party imports, followed through package facades to their modules.
47
+
48
+ ``from app.channels.application import ChannelCommands`` names the package, but
49
+ the test exercises ``app/channels/application/commands/registry.py``.
50
+ """
51
+ found: list[_Import] = []
52
+ for target in syntax.bindings.values():
53
+ module = _first_party_module(ctx, target)
54
+ if module is None:
55
+ continue
56
+ item = _Import(target, module)
57
+ if target != module:
58
+ name = target[len(module) + 1 :]
59
+ item = _Import(name, module)
60
+ resolved = resolve_dotted(target, ctx.syntax.namespace)
61
+ if resolved is not None and resolved[0] != module:
62
+ item = _Import(name, resolved[0], via=module)
63
+ if item not in found:
64
+ found.append(item)
65
+ return found
66
+
67
+
68
+ def _modules(imports: list[_Import]) -> list[str]:
69
+ return list(dict.fromkeys(item.module for item in imports))
70
+
71
+
72
+ def _subject(name: str) -> str:
73
+ stem = name.removesuffix(".py")
74
+ return stem.removeprefix("test_").removesuffix("_test")
75
+
76
+
77
+ _PLACEHOLDER = re.compile(r"(\{path\}/|\{path\}|\{module\}|\{root\})")
78
+ _GROUPS = {
79
+ "{path}/": r"(?:(?P<path>[A-Za-z_]\w*(?:/[A-Za-z_]\w*)*)/)?",
80
+ "{path}": r"(?P<path>[A-Za-z_]\w*(?:/[A-Za-z_]\w*)*)?",
81
+ "{module}": r"(?P<module>[A-Za-z_]\w*)",
82
+ "{root}": r"(?P<root>[A-Za-z_]\w*)",
83
+ }
84
+
85
+
86
+ @cache
87
+ def _mirror_regex(pattern: str) -> re.Pattern[str]:
88
+ parts = _PLACEHOLDER.split(pattern)
89
+ return re.compile("".join(_GROUPS.get(part, re.escape(part)) for part in parts))
90
+
91
+
92
+ @dataclass(frozen=True, slots=True)
93
+ class _Mirror:
94
+ """What a test path says it mirrors: ``billing/test_invoice.py`` -> billing, invoice."""
95
+
96
+ directories: list[str]
97
+ module: str
98
+ root: str | None
99
+
100
+
101
+ def mirror_path(ctx: AnalysisContext, module: str) -> str | None:
102
+ """The mirrored test path of ``module`` under the test root of its package.
103
+
104
+ Segments may be placeholders such as ``<layer>``; they are kept as written.
105
+ """
106
+ root = module.split(".", 1)[0]
107
+ for test_root in ctx.config.project.test_roots:
108
+ if root in _member_roots(ctx, test_root.strip("/")):
109
+ return _mirror_target(ctx, test_root.strip("/"), module)
110
+ return None
111
+
112
+
113
+ def _mirror_parts(ctx: AnalysisContext, test: TestFile) -> _Mirror | None:
114
+ relative = test.path.removeprefix(f"{test.test_root}/")
115
+ match = _mirror_regex(ctx.config.tests.mirror).fullmatch(relative)
116
+ if match is None:
117
+ return None
118
+ path = match.group("path") if "path" in match.groupdict() else None
119
+ root = match.group("root") if "root" in match.groupdict() else None
120
+ return _Mirror(path.split("/") if path else [], match.group("module"), root)
121
+
122
+
123
+ def _roots(ctx: AnalysisContext, mirror: _Mirror, test_root: str) -> list[str]:
124
+ roots = _member_roots(ctx, test_root)
125
+ if mirror.root is None:
126
+ return roots
127
+ return [mirror.root] if mirror.root in roots else []
128
+
129
+
130
+ def _member_roots(ctx: AnalysisContext, test_root: str) -> list[str]:
131
+ """The root packages a test root belongs to.
132
+
133
+ In a workspace, ``libs/agent/tests`` tests the package under ``libs/agent/src``:
134
+ the source roots sharing the longest leading path with the test root win.
135
+ """
136
+ roots = ctx.config.project.root_packages
137
+ shared = {root: _common_depth(ctx, root, test_root) for root in roots}
138
+ best = max(shared.values(), default=0)
139
+ if best == 0:
140
+ return roots
141
+ return [root for root in roots if shared[root] == best]
142
+
143
+
144
+ def _common_depth(ctx: AnalysisContext, root: str, test_root: str) -> int:
145
+ package = ctx.files.packages.get(root)
146
+ if package is None:
147
+ return 0
148
+ depth = 0
149
+ for left, right in zip(
150
+ package.source_root.strip("/").split("/"), test_root.split("/"), strict=False
151
+ ):
152
+ if left != right or left in ("", "."):
153
+ break
154
+ depth += 1
155
+ return depth
156
+
157
+
158
+ def _subjects(subject: str, *, suffixes: bool) -> list[str]:
159
+ """The module names a test may cover: ``invoice_rounding`` -> also ``invoice``."""
160
+ if not suffixes:
161
+ return [subject]
162
+ parts = subject.split("_")
163
+ return ["_".join(parts[:end]) for end in range(len(parts), 0, -1)]
164
+
165
+
166
+ def _mirrors_source(ctx: AnalysisContext, mirror: _Mirror, test_root: str) -> bool:
167
+ files = ctx.files
168
+ for root in _roots(ctx, mirror, test_root):
169
+ package = ".".join([root, *mirror.directories])
170
+ package_name = mirror.directories[-1] if mirror.directories else root
171
+ for name in _subjects(mirror.module, suffixes=ctx.config.tests.mirror_suffixes):
172
+ source = files.sources.get(f"{package}.{name}")
173
+ if source is not None and not source.is_package:
174
+ return True
175
+ if name == package_name and package in files.packages:
176
+ return True
177
+ return False
178
+
179
+
180
+ def _missing_module(ctx: AnalysisContext, mirror: _Mirror, test_root: str) -> str:
181
+ root = (_roots(ctx, mirror, test_root) or _member_roots(ctx, test_root))[0]
182
+ return ".".join([root, *mirror.directories, mirror.module])
183
+
184
+
185
+ def _similar_module(ctx: AnalysisContext, module: str, imported: list[str]) -> str:
186
+ """`` (did you mean "fernet_token_cypher.py"?)`` for a typo next to a real module.
187
+
188
+ Names are compared without ``.py``, which made ``memory.py`` look like
189
+ ``errors.py``. Only a module the test imports can be the one it misspells: a
190
+ similar file name alone says nothing about what the test covers.
191
+ """
192
+ package, name = module.rsplit(".", 1)
193
+ siblings = [
194
+ source.module
195
+ for source in ctx.files.sources.values()
196
+ if not source.is_package
197
+ and source.module.rsplit(".", 1)[0] == package
198
+ and source.module in imported
199
+ ]
200
+ stems = [sibling.rsplit(".", 1)[1] for sibling in siblings]
201
+ # Typos score above 0.85 (invoise/invoice); spotify_service/spotify_search
202
+ # scores 0.83 and is another module, not a misspelling.
203
+ match = difflib.get_close_matches(name, stems, n=1, cutoff=0.85)
204
+ return f' (did you mean "{match[0]}.py"?)' if match else ""
205
+
206
+
207
+ def _named_package(
208
+ ctx: AnalysisContext, mirror: _Mirror, test_root: str, imported: list[str]
209
+ ) -> str | None:
210
+ """The package the test is named after, next to the mirrored path.
211
+
212
+ ``application/test_commands.py`` covers ``application/commands/``, unless it
213
+ imports first-party code and none of it from that package.
214
+ """
215
+ found = [
216
+ package
217
+ for root in _roots(ctx, mirror, test_root)
218
+ if (package := ".".join([root, *mirror.directories, mirror.module]))
219
+ in ctx.files.packages
220
+ ]
221
+ if len(found) != 1:
222
+ return None
223
+ if imported and not any(is_within(m, found[0]) for m in imported):
224
+ return None
225
+ return found[0]
226
+
227
+
228
+ def _suffix_hint(ctx: AnalysisContext) -> str:
229
+ if ctx.config.tests.mirror_suffixes:
230
+ return " Topic tests may add a suffix: test_<module>_<topic>.py."
231
+ return " tests.mirror_suffixes allows topic tests like test_<module>_<topic>.py."
232
+
233
+
234
+ def _suffix_sibling(
235
+ ctx: AnalysisContext, mirror: _Mirror, test_root: str, imported: list[str]
236
+ ) -> str | None:
237
+ """The module next to the mirrored path that the name ends with.
238
+
239
+ ``health/presentation/test_health_presentation_router.py`` mirrors
240
+ ``health/presentation/router.py`` once the prefix is dropped. Not when the test
241
+ imports another module of that package: ``test_..._event_mapper.py`` importing
242
+ ``presentation.rpc.mappers`` is not about ``presentation/mapper.py``.
243
+ """
244
+ found = [
245
+ source.module
246
+ for root in _roots(ctx, mirror, test_root)
247
+ for source in ctx.files.sources.values()
248
+ if not source.is_package
249
+ and source.module.rsplit(".", 1)[0] == ".".join([root, *mirror.directories])
250
+ and _spells_package_path(mirror.module, source.module)
251
+ ]
252
+ if len(found) != 1:
253
+ return None
254
+ package = found[0].rsplit(".", 1)[0]
255
+ others = [
256
+ m for m in imported if is_within(m, package) and m not in (package, found[0])
257
+ ]
258
+ return None if others else found[0]
259
+
260
+
261
+ def _root_pattern_hint(ctx: AnalysisContext, mirror: _Mirror, test_root: str) -> str:
262
+ """A hint when the test path starts with the root package the pattern leaves out."""
263
+ pattern = ctx.config.tests.mirror
264
+ if "{root}" in pattern or not mirror.directories:
265
+ return ""
266
+ root, *directories = mirror.directories
267
+ if root not in _member_roots(ctx, test_root):
268
+ return ""
269
+ if not _mirrors_source(ctx, _Mirror(directories, mirror.module, root), test_root):
270
+ return ""
271
+ return (
272
+ f' The test path starts with the root package "{root}"; if all tests do, '
273
+ f'set tests.mirror to "{{root}}/{pattern}".'
274
+ )
275
+
276
+
277
+ def _mirror_target(ctx: AnalysisContext, test_root: str, module: str) -> str:
278
+ """Where tests.mirror puts the test of ``module`` (a module, not a package)."""
279
+ root, *directories, name = module.split(".")
280
+ path = "/".join(directories)
281
+ relative = (
282
+ ctx.config.tests.mirror.replace("{path}/", f"{path}/" if path else "")
283
+ .replace("{path}", path)
284
+ .replace("{module}", name)
285
+ .replace("{root}", root)
286
+ )
287
+ return f"{test_root}/{relative}"
288
+
289
+
290
+ class MisplacedTestFile(BaseRule):
291
+ scope = "test"
292
+ activation = POLICIES["SMT401"]
293
+ code = "SMT401"
294
+ name = "test-location"
295
+ category = Category.TESTS
296
+ default_severity = Severity.ERROR
297
+ requires = frozenset({Index.FILES, Index.SYNTAX})
298
+ doc = RuleDoc(
299
+ summary="A test file does not live where tests.layout expects it.",
300
+ rationale=(
301
+ "A predictable test location lets readers and agents find the tests of a "
302
+ "module, and a test whose mirrored source no longer exists is left over from "
303
+ "a rename or move. With `layout: mirror` the path decides: "
304
+ "tests/billing/test_invoice.py needs app/billing/invoice.py, a package test "
305
+ "tests/billing/test_billing.py needs app/billing/. Not every module needs a "
306
+ "test. tests.mirror sets the convention, relative to the test root."
307
+ ),
308
+ bad="tests/test_invoice.py # layout: mirror, source app/billing/invoice.py",
309
+ good="tests/billing/test_invoice.py",
310
+ fix=(
311
+ "Move or rename the file so its path mirrors the module it tests, merge it "
312
+ "into that module's test, or list deliberately unmirrored tests "
313
+ "(behaviour, integration, e2e) in tests.unmirrored. A missing mirrored "
314
+ "source says nothing about whether the tested behaviour exists. Imports "
315
+ "through package facades count as imports of the defining module. A move "
316
+ "is suggested only when the test imports its subject (or is named exactly "
317
+ "after it, marked `evidence: name`); otherwise `expected.candidates` lists "
318
+ "the imported modules with their names and mirrored test paths to choose "
319
+ "from, and two imported modules of the test's name stay undecided."
320
+ ),
321
+ config=(
322
+ "tests.layout",
323
+ "tests.mirror",
324
+ "tests.unmirrored",
325
+ "tests.mirror_suffixes",
326
+ "project.test_roots",
327
+ ),
328
+ )
329
+
330
+ def check(self, ctx: AnalysisContext) -> Iterator[Violation]:
331
+ tests = ctx.config.tests
332
+ if tests.layout == "none":
333
+ return
334
+ for path, test in sorted(ctx.files.tests.items()):
335
+ if test.is_conftest:
336
+ continue
337
+ if not any(path_matches(p, path) for p in tests.unmirrored):
338
+ yield from self._check_mirror(ctx, test)
339
+
340
+ def _check_mirror(
341
+ self, ctx: AnalysisContext, test: TestFile
342
+ ) -> Iterator[Violation]:
343
+ mirror = _mirror_parts(ctx, test)
344
+ if mirror is not None and _mirrors_source(ctx, mirror, test.test_root):
345
+ return
346
+ syntax = ctx.syntax.for_path(test.path)
347
+ imports = _resolved_imports(ctx, syntax) if syntax is not None else []
348
+ modules = _modules(imports)
349
+ subject = mirror.module if mirror else _subject(test.name)
350
+ named = _named_modules(ctx, subject, modules)
351
+ tested = named[0] if len(named) == 1 else None
352
+ if not named and mirror is not None:
353
+ tested = _suffix_sibling(ctx, mirror, test.test_root, modules)
354
+ package = None
355
+ if not named and tested is None and mirror is not None:
356
+ package = _named_package(ctx, mirror, test.test_root, modules)
357
+ covered = tested or package
358
+ taken = ""
359
+ if covered is not None:
360
+ # A package's own test sits inside it: billing/stripe/test_stripe.py
361
+ target = covered if tested else f"{covered}.{subject}"
362
+ expected = _mirror_target(ctx, test.test_root, target)
363
+ if expected in ctx.files.tests and expected != test.path:
364
+ taken = f" {expected} already exists; merge the two tests."
365
+ elif expected != test.path:
366
+ yield self._misplaced(ctx, test, covered, expected, modules)
367
+ return
368
+ if mirror is None:
369
+ pattern = ctx.config.tests.mirror
370
+ yield self.violation(
371
+ f"{test.name} does not match tests.mirror ({pattern})",
372
+ path=test.path,
373
+ expected={"pattern": f"{test.test_root}/{pattern}"},
374
+ hint=_GENERIC_HINT + _suffix_hint(ctx) + taken,
375
+ )
376
+ return
377
+ module = _missing_module(ctx, mirror, test.test_root)
378
+ source = ctx.files.module_to_path(module)
379
+ info = ctx.model.info(module)
380
+ ranked = _ranked(ctx, test.test_root, module, named or modules)
381
+ candidates = _candidates(ctx, test.test_root, ranked, imports)
382
+ details: dict[str, object] = {"source": source}
383
+ message = f"{test.name} has no source module at its mirrored path {source}"
384
+ if len(named) <= 1:
385
+ message += _similar_module(ctx, module, modules)
386
+ if len(named) > 1:
387
+ message += f"; it imports {len(named)} modules named {subject}"
388
+ hint = (
389
+ f"It imports {_listing(ctx, ranked)}. Move it next to the one it tests, "
390
+ "split it, or list it in tests.unmirrored if it tests how they work "
391
+ "together."
392
+ )
393
+ details |= {"subject": "ambiguous", "candidates": candidates}
394
+ elif candidates:
395
+ hint = (
396
+ f"{_NO_SOURCE} It imports {_listing(ctx, ranked)}: rename or move it "
397
+ "to the test of the module it covers, merge it into that test, or list "
398
+ "it in tests.unmirrored if it tests behaviour across them."
399
+ )
400
+ details |= {"subject": "unknown", "candidates": candidates}
401
+ else:
402
+ hint = _GENERIC_HINT
403
+ yield self.violation(
404
+ message,
405
+ path=test.path,
406
+ feature=info.feature if info else None,
407
+ layer=info.layer if info else None,
408
+ expected=details,
409
+ hint=hint
410
+ + _suffix_hint(ctx)
411
+ + taken
412
+ + _root_pattern_hint(ctx, mirror, test.test_root),
413
+ )
414
+
415
+ def _misplaced(
416
+ self,
417
+ ctx: AnalysisContext,
418
+ test: TestFile,
419
+ module: str,
420
+ expected: str,
421
+ imported: list[str],
422
+ ) -> Violation:
423
+ directory = posixpath.dirname(expected)
424
+ if directory == posixpath.dirname(test.path):
425
+ message = f"{test.name} should be named {posixpath.basename(expected)}"
426
+ else:
427
+ message = f"{test.name} belongs in {directory}/"
428
+ info = ctx.model.info(module)
429
+ package = module in ctx.files.packages
430
+ source = ctx.files.module_to_path(module, package=package)
431
+ hint = f"Move the file to {expected}."
432
+ evidence = "imports"
433
+ if not any(is_within(m, module) for m in imported):
434
+ evidence = "name"
435
+ hint = (
436
+ f"Move the file to {expected}. Only its name points there: it imports "
437
+ f"no code of {source}, so check that it really tests it."
438
+ )
439
+ return self.violation(
440
+ message,
441
+ path=test.path,
442
+ feature=info.feature if info else None,
443
+ layer=info.layer if info else None,
444
+ expected={
445
+ "path": expected,
446
+ "source": source,
447
+ "subject": "package" if package else "module",
448
+ "evidence": evidence,
449
+ },
450
+ hint=hint,
451
+ )
452
+
453
+
454
+ def _named_modules(ctx: AnalysisContext, subject: str, modules: list[str]) -> list[str]:
455
+ """The imported modules the test is named after; several make it ambiguous."""
456
+ plain = [m for m in modules if m not in ctx.files.packages]
457
+ exact = [m for m in plain if m.rsplit(".", 1)[-1] == subject]
458
+ if exact:
459
+ return exact
460
+ # test_session_infrastructure_repository.py spells out the package path
461
+ suffixed = [m for m in plain if _spells_package_path(subject, m)]
462
+ return suffixed if len(suffixed) == 1 else []
463
+
464
+
465
+ def _spells_package_path(subject: str, module: str) -> bool:
466
+ """``session_infrastructure_repository`` names ``session.infrastructure.repository``.
467
+
468
+ The prefix must be the end of the module's package path: a topic such as
469
+ ``agent_workspace_update_events`` does not make a test about ``agent/events.py``.
470
+ """
471
+ *package, name = module.split(".")
472
+ if not subject.endswith(f"_{name}"):
473
+ return False
474
+ prefix = subject[: -len(name) - 1]
475
+ return any(prefix == "_".join(package[start:]) for start in range(len(package)))
476
+
477
+
478
+ _NO_SOURCE = (
479
+ "A path without a source module does not mean the tested behaviour is missing."
480
+ )
481
+ _GENERIC_HINT = (
482
+ f"{_NO_SOURCE} Move or rename the test to mirror the module it covers, merge it "
483
+ "into that module's test, delete it if the module is gone, or list a deliberate "
484
+ "behaviour or integration test in tests.unmirrored."
485
+ )
486
+ # Enough to choose from; the JSON says how many there are.
487
+ _MAX_CANDIDATES = 5
488
+
489
+
490
+ def _ranked(
491
+ ctx: AnalysisContext, test_root: str, missing: str, modules: list[str]
492
+ ) -> list[str]:
493
+ """Imported modules of the test's own member, nearest to its mirrored path first.
494
+
495
+ Within the mirrored package, names closer to the test's name come first; that
496
+ orders the evidence, it adds no module the test does not import.
497
+ """
498
+ roots = _member_roots(ctx, test_root)
499
+ package, name = missing.rsplit(".", 1)
500
+ return sorted(
501
+ (m for m in modules if m.split(".")[0] in roots),
502
+ key=lambda m: (
503
+ not is_within(m, package),
504
+ -difflib.SequenceMatcher(None, name, m.rsplit(".", 1)[-1]).ratio(),
505
+ m,
506
+ ),
507
+ )
508
+
509
+
510
+ def _candidates(
511
+ ctx: AnalysisContext, test_root: str, ranked: list[str], imports: list[_Import]
512
+ ) -> list[dict[str, object]]:
513
+ """The first ranked modules with what the test imports from them; none is a move."""
514
+ found: list[dict[str, object]] = []
515
+ for module in ranked[:_MAX_CANDIDATES]:
516
+ is_package = module in ctx.files.packages
517
+ target = f"{module}.{module.rsplit('.', 1)[-1]}" if is_package else module
518
+ found.append(
519
+ {
520
+ "module": module,
521
+ "kind": "package" if is_package else "module",
522
+ "source": ctx.files.module_to_path(module, package=is_package),
523
+ "test_path": _mirror_target(ctx, test_root, target),
524
+ "imports": sorted({i.name for i in imports if i.module == module}),
525
+ "via": sorted({i.via for i in imports if i.module == module and i.via}),
526
+ }
527
+ )
528
+ return found
529
+
530
+
531
+ def _listing(ctx: AnalysisContext, modules: list[str]) -> str:
532
+ shown = [
533
+ display_module_path(ctx.model, m, package=m in ctx.files.packages)
534
+ for m in modules[:3]
535
+ ]
536
+ more = len(modules) - len(shown)
537
+ return ", ".join(shown) + (f" and {more} more" if more else "")
@@ -0,0 +1,140 @@
1
+ from __future__ import annotations
2
+
3
+ import ast
4
+ from collections import Counter
5
+ from typing import TYPE_CHECKING
6
+
7
+ from smelt.analysis.context import AnalysisContext, Index
8
+ from smelt.config.patterns import path_matches
9
+ from smelt.diagnostics.violation import Category, Violation
10
+ from smelt.rules.activation import POLICIES
11
+ from smelt.rules.base import BaseRule, RuleDoc
12
+
13
+ if TYPE_CHECKING:
14
+ from collections.abc import Iterator
15
+
16
+
17
+ class ForbiddenTestMock(BaseRule):
18
+ test_local = True
19
+ scope = "test"
20
+ activation = POLICIES["SMT421"]
21
+ code = "SMT421"
22
+ name = "forbidden-test-mock"
23
+ category = Category.TESTS
24
+ requires = frozenset({Index.TESTS})
25
+ doc = RuleDoc(
26
+ summary="A recognized mocking operation occurs in a test path that forbids mocks.",
27
+ rationale="Domain tests can exercise real domain objects and injected fakes. This opt-in path policy rejects recognized unittest.mock constructors/patching, standard pytest-mock operations and pytest.MonkeyPatch setattr/delattr replacements, including setup fixtures. MonkeyPatch receivers can be the standard fixture, annotated instances, constructors, aliases or context() scopes. MonkeyPatch setenv/delenv, mapping and directory setup are not counted as collaborator replacements. It does not infer arbitrary test doubles or traverse fixture dependencies.",
28
+ bad="from unittest.mock import Mock\ndef test_rule():\n service = Mock()",
29
+ good="def test_rule():\n result = calculate_total([10, 20])\n assert result == 30",
30
+ fix="Use real domain objects or a small fake implementing the port. Keep boundary mocking in explicitly permitted test paths; use a reasoned suppression for an intentional exception.",
31
+ config=("tests.forbid_mocks_in", "tests.quality_exclude"),
32
+ )
33
+
34
+ def check(self, ctx: AnalysisContext) -> Iterator[Violation]:
35
+ patterns = ctx.config.tests.forbid_mocks_in
36
+ for module in ctx.test_syntax.modules.values():
37
+ if not any(path_matches(pattern, module.path) for pattern in patterns):
38
+ continue
39
+ for call in module.calls:
40
+ if call.mock:
41
+ yield self.violation(
42
+ f"mock operation {call.qualified} is forbidden in this test path",
43
+ path=module.path,
44
+ line=call.node.lineno,
45
+ column=call.node.col_offset + 1,
46
+ expected={
47
+ "forbid_mocks_in": patterns,
48
+ "operation": call.qualified,
49
+ "family": call.family,
50
+ "provenance": call.provenance,
51
+ },
52
+ hint="Exercise the domain with real values and an injected fake instead of a mock.",
53
+ )
54
+
55
+
56
+ class StringPatchTarget(BaseRule):
57
+ test_local = True
58
+ scope = "test"
59
+ code = "SMT422"
60
+ name = "string-patch-target"
61
+ category = Category.TESTS
62
+ requires = frozenset({Index.TESTS})
63
+ doc = RuleDoc(
64
+ summary="A recognized patch call or decorator uses a literal string target.",
65
+ rationale="String patch targets encode import paths that refactoring tools may not update. This opt-in convention checks unittest.mock and standard pytest-mock patch, patch.dict and patch.multiple literal targets, plus the dotted-target forms of pytest.MonkeyPatch setattr/delattr. Object/attribute forms are distinguished by their argument shape. It does not claim that object-based patching removes implementation coupling; variables and dynamically computed targets are outside this syntax check.",
66
+ bad='from unittest.mock import patch\n@patch("app.service.Repository")\ndef test_run(repository): ...',
67
+ good="def test_run():\n repository = InMemoryRepository()\n run(repository)\n assert repository.saved == [42]",
68
+ fix="Prefer an injected collaborator/fake. For deliberate boundary patching, use object-based patching where appropriate and patch the name looked up by the caller. No automatic rewrite is performed.",
69
+ config=("rules", "tests.quality_exclude"),
70
+ )
71
+
72
+ def check(self, ctx: AnalysisContext) -> Iterator[Violation]:
73
+ for module in ctx.test_syntax.modules.values():
74
+ for call in module.calls:
75
+ if call.string_target:
76
+ yield self.violation(
77
+ "patch uses a literal string target",
78
+ path=module.path,
79
+ line=call.node.lineno,
80
+ column=call.node.col_offset + 1,
81
+ expected={
82
+ "operation": call.qualified,
83
+ "family": call.family,
84
+ "provenance": call.provenance,
85
+ },
86
+ hint="Inject the collaborator, or review deliberate object-based boundary patching.",
87
+ )
88
+
89
+
90
+ class ExcessiveTestPatches(BaseRule):
91
+ test_local = True
92
+ scope = "test"
93
+ activation = POLICIES["SMT423"]
94
+ code = "SMT423"
95
+ name = "excessive-test-patches"
96
+ category = Category.TESTS
97
+ requires = frozenset({Index.TESTS})
98
+ doc = RuleDoc(
99
+ summary="A collected test exceeds its configured number of recognized patch calls.",
100
+ rationale="Many replacements can indicate a test coupled to construction and internal calls. Count patch operations in decorators and the test body once per syntactic call, including patch.object. Nested helper bodies, fixtures and transitive calls are not attributed to callers. The limit is a configurable convention, not a proof that a test is bad.",
101
+ bad='def test_run(mocker):\n mocker.patch("app.one")\n mocker.patch("app.two")',
102
+ good="def test_run():\n result = run(InMemoryRepository())\n assert result.status == 'active'",
103
+ fix="Reduce the scenario's dependencies or inject a fake. Keep a justified integration scenario with a reasoned exception rather than hiding patches inside helpers.",
104
+ config=("tests.max_patches_per_test", "tests.quality_exclude"),
105
+ )
106
+
107
+ def check(self, ctx: AnalysisContext) -> Iterator[Violation]:
108
+ maximum = ctx.config.tests.max_patches_per_test
109
+ if maximum is None:
110
+ return
111
+ for module in ctx.test_syntax.modules.values():
112
+ for test in module.tests:
113
+ patches = [call for call in test.calls if call.patch]
114
+ if len(patches) > maximum:
115
+ counts: Counter[str] = Counter()
116
+ edges: list[str] = []
117
+ for call in patches:
118
+ shape = ast.dump(call.node, include_attributes=False)
119
+ edges.append(f"{test.name}:{shape}#{counts[shape]}")
120
+ counts[shape] += 1
121
+ yield self.violation(
122
+ f"{test.name} has {len(patches)} patch calls; maximum is {maximum}",
123
+ path=module.path,
124
+ line=test.node.lineno,
125
+ expected={
126
+ "test": test.name,
127
+ "patch_edges": edges,
128
+ "max_patches_per_test": maximum,
129
+ "patches": [
130
+ {
131
+ "line": call.node.lineno,
132
+ "operation": call.qualified,
133
+ "family": call.family,
134
+ "provenance": call.provenance,
135
+ }
136
+ for call in patches
137
+ ],
138
+ },
139
+ hint="Exercise a smaller behavior or inject a fake instead of replacing internal collaborators.",
140
+ )