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,975 @@
1
+ """Conservative use evidence for module functions and direct class helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ast
6
+ from dataclasses import dataclass, field, replace
7
+ from functools import cached_property, partial
8
+ from typing import TYPE_CHECKING, Literal
9
+
10
+ from pydantic import TypeAdapter
11
+
12
+ from smelt.analysis.exports import Namespace, resolve_dotted, resolve_export
13
+ from smelt.analysis.function_usage import (
14
+ definition_bindings,
15
+ explicit_exports,
16
+ reference_names,
17
+ )
18
+ from smelt.analysis.member_state import (
19
+ MEMBER_STATE,
20
+ MemberIndexState,
21
+ MemberSummary,
22
+ update_members,
23
+ )
24
+ from smelt.analysis.retained import current
25
+
26
+ if TYPE_CHECKING:
27
+ from collections.abc import Iterator
28
+
29
+ from smelt.analysis.syntax import ModuleSyntax, SyntaxIndex
30
+ from smelt.analysis.test_syntax import TestSyntaxIndex
31
+
32
+ type Function = ast.FunctionDef | ast.AsyncFunctionDef
33
+ _REFLECTION_ARGUMENTS = 2
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class Definition:
38
+ name: str
39
+ lineno: int
40
+ col_offset: int
41
+
42
+ @classmethod
43
+ def of(cls, node: Function | ast.ClassDef) -> Definition:
44
+ return cls(node.name, node.lineno, node.col_offset)
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class Member:
49
+ module: str
50
+ path: str
51
+ owner: Definition | None
52
+ node: Definition
53
+ kind: Literal["function", "method", "staticmethod"]
54
+ internal_references: tuple[int, ...]
55
+ external_use: bool
56
+ production_external_use: bool = False
57
+ class_dependencies: bool = False
58
+ occupied_names: frozenset[str] = frozenset()
59
+ module_names: frozenset[str] = frozenset()
60
+
61
+
62
+ @dataclass(frozen=True)
63
+ class _AttributeUse:
64
+ module: str
65
+ path: str
66
+ line: int
67
+ owner: ast.ClassDef | None
68
+ internal: bool
69
+ definition: ast.Attribute | None = None
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class AttributeMember:
74
+ module: str
75
+ path: str
76
+ owner: Definition
77
+ node: Definition
78
+ name: str
79
+ kind: Literal["instance-attribute", "class-attribute"]
80
+ internal_references: tuple[int, ...]
81
+ occupied_names: frozenset[str]
82
+
83
+
84
+ @dataclass
85
+ class _UsageEvidence:
86
+ module_uses: dict[tuple[str, str | None], set[str]]
87
+ production_uses: dict[tuple[str, str | None], set[str]]
88
+ attributes: dict[str, list[tuple[str, int, int | None, bool, bool]]]
89
+ inherited: set[tuple[str, str | None]]
90
+
91
+
92
+ @dataclass
93
+ class _FileFacts:
94
+ module: str
95
+ path: str
96
+ production: bool
97
+ candidates: list[Member]
98
+ references: tuple[list[str], list[str], list[str]]
99
+ attributes: dict[str, list[tuple[int, int | None, bool]]]
100
+ bases: list[str]
101
+ attribute_candidates: list[AttributeMember] = field(default_factory=list)
102
+
103
+
104
+ _FACTS = TypeAdapter(_FileFacts)
105
+
106
+
107
+ @dataclass
108
+ class _ResolvedReferences:
109
+ targets: list[tuple[str, str | None]]
110
+ inherited: list[tuple[str, str | None]]
111
+ dependencies: dict[str, tuple[str, str, bool] | None]
112
+
113
+
114
+ _REFERENCES = TypeAdapter(_ResolvedReferences)
115
+ _MEMBERS = TypeAdapter(list[Member])
116
+ type MemberState = tuple[bool, bool, tuple[int, ...], bool]
117
+
118
+
119
+ class MemberUsageIndex:
120
+ def __init__(self, syntax: SyntaxIndex) -> None:
121
+ self._syntax = syntax
122
+ self._decision_keys: dict[str, str] = {}
123
+
124
+ @property
125
+ def usage_scope(self) -> dict[str, object]:
126
+ project = self._syntax.files.config.project
127
+ return {
128
+ "root_packages": list(project.root_packages),
129
+ "source_roots": list(project.source_roots),
130
+ "test_roots": list(project.test_roots),
131
+ "excluded_paths": project.exclude_patterns,
132
+ "unassessed_consumers": [
133
+ "excluded files (including maintainer scripts)",
134
+ "files outside selected packages and roots",
135
+ "external consumers and arbitrary dynamic access",
136
+ ],
137
+ }
138
+
139
+ @cached_property
140
+ def _local_state(self) -> MemberIndexState:
141
+ syntax = self._syntax
142
+ cache = syntax.cache
143
+ if cache is None:
144
+ raise ValueError("member dependency state requires a fact cache")
145
+ key = cache.key(
146
+ "member-state",
147
+ [str(syntax.files.root), syntax.files.config.model_dump(mode="json")],
148
+ )
149
+ retained = current()
150
+ state_key = str(cache.directory), key
151
+ previous = retained.take(state_key) if retained is not None else None
152
+ previous = previous or cache.read(key, MEMBER_STATE) or MemberIndexState()
153
+ identities = {
154
+ path: self._fact_key(path)
155
+ for path in sorted(set(syntax.files.by_path) | syntax.files.tests.keys())
156
+ }
157
+ namespaces = {
158
+ name: self._namespace_identity(name)
159
+ for name in syntax.files.sources.keys() | syntax.files.packages.keys()
160
+ }
161
+
162
+ def decision(summary: MemberSummary, totals: dict[str, int]) -> str:
163
+ return cache.key(
164
+ "member-decision",
165
+ [summary.identity, [totals.get(query, 0) for query in summary.queries]],
166
+ )
167
+
168
+ state = update_members(
169
+ previous, identities, namespaces, self._summary, decision
170
+ )
171
+ cache.write(key, state, MEMBER_STATE)
172
+ if retained is not None:
173
+ retained.put(state_key, state, size=len(MEMBER_STATE.dump_json(state)))
174
+ return state
175
+
176
+ def local_paths(self) -> Iterator[str]:
177
+ """Yield decisions without deserializing unchanged definition objects."""
178
+ for path, summary in self._local_state.files.items():
179
+ if summary.has_members:
180
+ yield path
181
+
182
+ def members_for_path(self, path: str) -> list[Member]:
183
+ cache = self._syntax.cache
184
+ if cache is None:
185
+ return self.member_files.get(path, [])
186
+ state = self._local_state
187
+ key = state.files[path].decision
188
+
189
+ def build() -> list[Member]:
190
+ file = self._facts(path)
191
+ states: list[MemberState] = []
192
+ for candidate in file.candidates:
193
+ owner = candidate.owner
194
+ if owner is None:
195
+ states.append(
196
+ (
197
+ self._counted_external(file.module, candidate.node.name),
198
+ self._counted_external(
199
+ file.module, candidate.node.name, production=True
200
+ ),
201
+ candidate.internal_references,
202
+ False,
203
+ )
204
+ )
205
+ continue
206
+ local = [
207
+ line
208
+ for line, line_owner, internal in file.attributes.get(
209
+ candidate.node.name, []
210
+ )
211
+ if line_owner == owner.lineno and internal
212
+ ]
213
+ name = candidate.node.name
214
+ states.append(
215
+ (
216
+ state.totals.get(f"a:{name}", 0) > len(local),
217
+ state.totals.get(f"p:{name}", 0) > len(local),
218
+ tuple(sorted(set(local))),
219
+ bool(state.totals.get(f"i:{file.module}:{owner.name}", 0)),
220
+ )
221
+ )
222
+ return self._resolve_file(file, states)
223
+
224
+ return cache.get("member-values", key, _MEMBERS, build)
225
+
226
+ def _counted_external(
227
+ self, module: str, name: str, *, production: bool = False
228
+ ) -> bool:
229
+ totals = self._local_state.totals
230
+ prefix = "pf" if production else "f"
231
+ return any(
232
+ totals.get(f"{prefix}:{target}", 0)
233
+ > totals.get(f"{prefix}:{target}:{module}", 0)
234
+ for target in _function_targets(module, name)
235
+ )
236
+
237
+ def _summary(self, path: str) -> MemberSummary:
238
+ file = self._facts(path)
239
+ references = self._references(file)
240
+ contributions: dict[str, int] = {}
241
+ for module, name in set(references.targets):
242
+ target = f"{module}:{name or ''}"
243
+ for prefix in ("f", "pf") if file.production else ("f",):
244
+ contributions[f"{prefix}:{target}"] = 1
245
+ contributions[f"{prefix}:{target}:{file.module}"] = 1
246
+ for module, name in set(references.inherited):
247
+ contributions[f"i:{module}:{name}"] = 1
248
+ for name, uses in file.attributes.items():
249
+ contributions[f"a:{name}"] = len(uses)
250
+ if file.production:
251
+ contributions[f"p:{name}"] = len(uses)
252
+ queries: set[str] = set()
253
+ for candidate in file.candidates:
254
+ if candidate.owner is None:
255
+ for target in _function_targets(file.module, candidate.node.name):
256
+ for prefix in ("f", "pf"):
257
+ queries.update(
258
+ (f"{prefix}:{target}", f"{prefix}:{target}:{file.module}")
259
+ )
260
+ else:
261
+ queries.update(
262
+ (
263
+ f"a:{candidate.node.name}",
264
+ f"p:{candidate.node.name}",
265
+ f"i:{file.module}:{candidate.owner.name}",
266
+ )
267
+ )
268
+ return MemberSummary(
269
+ self._fact_key(path),
270
+ references.dependencies,
271
+ contributions,
272
+ sorted(queries),
273
+ bool(file.candidates),
274
+ )
275
+
276
+ @cached_property
277
+ def _files(self) -> list[_FileFacts]:
278
+ syntax = self._syntax
279
+ paths = sorted(
280
+ {s.path for s in syntax.files.sources.values()} | set(syntax.files.tests)
281
+ )
282
+ missing = (
283
+ None
284
+ if syntax.cache is None
285
+ else syntax.cache.missing([self._fact_key(path) for path in paths])
286
+ )
287
+ syntax.files.store.prefetch(
288
+ syntax.files.root / path
289
+ for path in paths
290
+ if missing is None or self._fact_key(path) in missing
291
+ )
292
+ return [self._facts(path) for path in paths]
293
+
294
+ @cached_property
295
+ def _evidence(self) -> _UsageEvidence:
296
+ evidence = _UsageEvidence({}, {}, {}, set())
297
+ for file in self._files:
298
+ references = self._references(file)
299
+ for target in references.targets:
300
+ evidence.module_uses.setdefault(target, set()).add(file.module)
301
+ if file.production:
302
+ evidence.production_uses.setdefault(target, set()).add(file.module)
303
+ for name, uses in file.attributes.items():
304
+ evidence.attributes.setdefault(name, []).extend(
305
+ (file.module, line, owner, internal, file.production)
306
+ for line, owner, internal in uses
307
+ )
308
+ evidence.inherited.update(references.inherited)
309
+ return evidence
310
+
311
+ def _namespace_identity(self, module: str) -> tuple[str, str, bool] | None:
312
+ files = self._syntax.files
313
+ source = files.sources.get(module)
314
+ if source is not None:
315
+ return source.path, files.content_id(source.path), source.is_package
316
+ package = files.packages.get(module)
317
+ return (package.path, "namespace", False) if package is not None else None
318
+
319
+ def _references(self, file: _FileFacts) -> _ResolvedReferences:
320
+ syntax = self._syntax
321
+ cache = syntax.cache
322
+ key = (
323
+ cache.key(
324
+ "member-references",
325
+ [
326
+ file.module,
327
+ file.path,
328
+ file.production,
329
+ syntax.files.content_id(file.path),
330
+ ],
331
+ )
332
+ if cache
333
+ else None
334
+ )
335
+ cached = cache.read(key, _REFERENCES) if cache and key else None
336
+ if cached is not None and all(
337
+ self._namespace_identity(module) == identity
338
+ for module, identity in cached.dependencies.items()
339
+ ):
340
+ return cached
341
+ dependencies: dict[str, tuple[str, str, bool] | None] = {}
342
+
343
+ def namespace(module: str) -> Namespace | None:
344
+ dependencies[module] = self._namespace_identity(module)
345
+ return syntax.namespace(module)
346
+
347
+ resolved: dict[str, tuple[str, str | None] | None] = {}
348
+
349
+ def resolve(name: str) -> tuple[str, str | None] | None:
350
+ if name not in resolved:
351
+ resolved[name] = resolve_dotted(name, namespace)
352
+ return resolved[name]
353
+
354
+ imports, loads, stars = file.references
355
+ targets: list[tuple[str, str | None]] = [(star, None) for star in stars]
356
+ targets.extend(
357
+ target
358
+ for name in imports
359
+ if (target := resolve(name)) is not None and target[1] is not None
360
+ )
361
+ targets.extend(
362
+ target for name in loads if (target := resolve(name)) is not None
363
+ )
364
+ inherited = [
365
+ target
366
+ for name in file.bases
367
+ if (target := resolve(name)) is not None and target[1] is not None
368
+ ]
369
+ result = _ResolvedReferences(targets, inherited, dependencies)
370
+ if cache and key:
371
+ cache.write(key, result, _REFERENCES)
372
+ return result
373
+
374
+ @cached_property
375
+ def _attribute_counts(self) -> dict[str, tuple[int, int]]:
376
+ return {
377
+ name: (len(uses), sum(production for _, _, _, _, production in uses))
378
+ for name, uses in self._evidence.attributes.items()
379
+ }
380
+
381
+ @cached_property
382
+ def members(self) -> list[Member]:
383
+ evidence = self._evidence
384
+ members: list[Member] = []
385
+ for file in self._files:
386
+ states: list[MemberState] = []
387
+ for candidate in file.candidates:
388
+ owner = candidate.owner
389
+ if owner is None:
390
+ external = self._function_external(file.module, candidate.node.name)
391
+ production_external = self._function_external(
392
+ file.module, candidate.node.name, production=True
393
+ )
394
+ references = candidate.internal_references
395
+ inherited = False
396
+ else:
397
+ inherited = (file.module, owner.name) in evidence.inherited
398
+ local = [
399
+ line
400
+ for line, line_owner, internal in file.attributes.get(
401
+ candidate.node.name, []
402
+ )
403
+ if line_owner == owner.lineno and internal
404
+ ]
405
+ references = tuple(sorted(set(local)))
406
+ total, production = self._attribute_counts.get(
407
+ candidate.node.name, (0, 0)
408
+ )
409
+ external = total > len(local)
410
+ production_external = production > len(local)
411
+ states.append((external, production_external, references, inherited))
412
+ cache = self._syntax.cache
413
+ if cache is None:
414
+ members.extend(self._resolve_file(file, states))
415
+ else:
416
+ inputs = [
417
+ file.module,
418
+ file.path,
419
+ file.production,
420
+ self._syntax.files.content_id(file.path),
421
+ states,
422
+ ]
423
+ self._decision_keys[file.path] = cache.key("resolved-members", inputs)
424
+ cached_members = cache.get(
425
+ "resolved-members",
426
+ inputs,
427
+ _MEMBERS,
428
+ partial(self._resolve_file, file, states),
429
+ )
430
+ members.extend(cached_members)
431
+ return members
432
+
433
+ @cached_property
434
+ def member_files(self) -> dict[str, list[Member]]:
435
+ groups: dict[str, list[Member]] = {}
436
+ for member in self.members:
437
+ groups.setdefault(member.path, []).append(member)
438
+ return groups
439
+
440
+ def decision_key(self, path: str) -> str:
441
+ if self._syntax.cache is not None:
442
+ return self._local_state.files[path].decision
443
+ return self._decision_keys[path]
444
+
445
+ def test_only_functions(
446
+ self, tests: TestSyntaxIndex
447
+ ) -> Iterator[tuple[Member, tuple[tuple[str, int], ...]]]:
448
+ references: dict[tuple[str, str | None], set[tuple[str, int]]] = {}
449
+ for path, test in tests.references():
450
+ for line, qualified in [
451
+ *test.imports,
452
+ *((line, name) for line, name, _ in test.attributes),
453
+ ]:
454
+ target = resolve_dotted(qualified, self._syntax.namespace)
455
+ if target is not None:
456
+ references.setdefault(target, set()).add((path, line))
457
+ for member in self.members:
458
+ if (
459
+ member.kind == "function"
460
+ and not member.node.name.startswith("_")
461
+ and not member.production_external_use
462
+ and (uses := references.get((member.module, member.node.name)))
463
+ ):
464
+ yield member, tuple(sorted(uses))
465
+
466
+ def _resolve_file(
467
+ self, file: _FileFacts, states: list[MemberState]
468
+ ) -> list[Member]:
469
+ return [
470
+ replace(
471
+ candidate,
472
+ external_use=external,
473
+ production_external_use=production,
474
+ internal_references=references,
475
+ )
476
+ for candidate, (external, production, references, inherited) in zip(
477
+ file.candidates, states, strict=True
478
+ )
479
+ if not inherited
480
+ ]
481
+
482
+ def _facts(self, path: str) -> _FileFacts:
483
+ syntax = self._syntax
484
+ source = syntax.files.source_for_path(path)
485
+
486
+ def build() -> _FileFacts:
487
+ module = syntax.for_path(path)
488
+ if module is None:
489
+ raise ValueError(f"missing syntax for indexed file: {path}")
490
+ return _file_facts(module, syntax, production=source is not None)
491
+
492
+ if syntax.cache is None:
493
+ return build()
494
+ key = self._fact_key(path)
495
+ cached = syntax.cache.read(key, _FACTS)
496
+ if cached is not None:
497
+ return cached
498
+ result = build()
499
+ syntax.cache.write(key, result, _FACTS)
500
+ return result
501
+
502
+ def _fact_key(self, path: str) -> str:
503
+ syntax = self._syntax
504
+ source = syntax.files.source_for_path(path)
505
+ if syntax.cache is None:
506
+ return ""
507
+ return syntax.cache.key(
508
+ "members",
509
+ [
510
+ path,
511
+ source.module if source else None,
512
+ source.is_package if source else False,
513
+ syntax.files.content_id(path),
514
+ ],
515
+ )
516
+
517
+ def _function_external(
518
+ self, module: str, name: str, *, production: bool = False
519
+ ) -> bool:
520
+ parts = module.split(".")
521
+ targets = [
522
+ (module, name),
523
+ *((".".join(parts[:end]), None) for end in range(1, len(parts) + 1)),
524
+ ]
525
+ uses = (
526
+ self._evidence.production_uses if production else self._evidence.module_uses
527
+ )
528
+ return any(
529
+ users and (len(users) > 1 or module not in users)
530
+ for target in targets
531
+ if (users := uses.get(target))
532
+ )
533
+
534
+ @cached_property
535
+ def attributes(self) -> list[AttributeMember]:
536
+ result: list[AttributeMember] = []
537
+ for file in self._files:
538
+ for candidate in file.attribute_candidates:
539
+ if (file.module, candidate.owner.name) in self._evidence.inherited:
540
+ continue
541
+ local = sum(
542
+ owner == candidate.owner.lineno and internal
543
+ for _, owner, internal in file.attributes.get(candidate.name, [])
544
+ )
545
+ _, production = self._attribute_counts.get(candidate.name, (0, 0))
546
+ if production > local:
547
+ continue
548
+ result.append(candidate)
549
+ return result
550
+
551
+ def test_only_attributes(
552
+ self, tests: TestSyntaxIndex
553
+ ) -> Iterator[tuple[AttributeMember, tuple[tuple[str, int], ...]]]:
554
+ references: dict[tuple[str, str, str], set[tuple[str, int]]] = {}
555
+ for path, test in tests.references():
556
+ for line, qualified, load in [*test.attributes, *test.instance_attributes]:
557
+ if not load:
558
+ continue
559
+ owner_name, _, name = qualified.rpartition(".")
560
+ module, _, owner = owner_name.rpartition(".")
561
+ target = resolve_export(module, owner, self._syntax.namespace)
562
+ if target and target[1]:
563
+ references.setdefault((target[0], target[1], name), set()).add(
564
+ (path, line)
565
+ )
566
+ for member in self.attributes:
567
+ if uses := references.get((member.module, member.owner.name, member.name)):
568
+ yield member, tuple(sorted(uses))
569
+
570
+
571
+ def _function_targets(module: str, name: str) -> Iterator[str]:
572
+ yield f"{module}:{name}"
573
+ parts = module.split(".")
574
+ for end in range(1, len(parts) + 1):
575
+ yield f"{'.'.join(parts[:end])}:"
576
+
577
+
578
+ def _file_facts(
579
+ module: ModuleSyntax, syntax: SyntaxIndex, *, production: bool
580
+ ) -> _FileFacts:
581
+ visitor = _UseVisitor(module)
582
+ visitor.visit(module.tree)
583
+ nodes = list(ast.walk(module.tree))
584
+ result = _FileFacts(
585
+ module.module,
586
+ module.path,
587
+ production,
588
+ [],
589
+ reference_names(module),
590
+ {
591
+ name: [
592
+ (use.line, use.owner.lineno if use.owner else None, use.internal)
593
+ for use in uses
594
+ ]
595
+ for name, uses in visitor.attributes.items()
596
+ },
597
+ [
598
+ qualified
599
+ for node in nodes
600
+ if isinstance(node, ast.ClassDef)
601
+ for base in node.bases
602
+ if (qualified := _qualified(base, module)) is not None
603
+ ],
604
+ )
605
+ if not production:
606
+ return result
607
+ definitions = definition_bindings(module.tree)
608
+ namespace = syntax.namespace(module.module)
609
+ occupied = (
610
+ namespace.defined | frozenset(namespace.imported) if namespace else frozenset()
611
+ )
612
+ exports = explicit_exports(module.tree)
613
+ loads: dict[str, set[int]] = {}
614
+ for node in nodes:
615
+ if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
616
+ loads.setdefault(node.id, set()).add(node.lineno)
617
+ for node in module.tree.body:
618
+ if definitions.get(getattr(node, "name", "")) != [node]:
619
+ continue
620
+ if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
621
+ if (
622
+ not node.decorator_list
623
+ and exports is not None
624
+ and node.name not in exports
625
+ ):
626
+ result.candidates.append(
627
+ Member(
628
+ module.module,
629
+ module.path,
630
+ None,
631
+ Definition.of(node),
632
+ "function",
633
+ tuple(sorted(loads.get(node.name, ()))),
634
+ False,
635
+ occupied_names=occupied,
636
+ module_names=occupied,
637
+ )
638
+ )
639
+ elif isinstance(node, ast.ClassDef) and (
640
+ not node.decorator_list
641
+ and not node.keywords
642
+ and all(
643
+ _qualified(base, module) in {"object", "builtins.object"}
644
+ for base in node.bases
645
+ )
646
+ ):
647
+ result.candidates.extend(_methods_in(node, module, visitor, occupied))
648
+ result.attribute_candidates.extend(
649
+ _attribute_candidates(node, module, visitor)
650
+ )
651
+ return result
652
+
653
+
654
+ def _methods_in(
655
+ owner: ast.ClassDef,
656
+ module: ModuleSyntax,
657
+ visitor: _UseVisitor,
658
+ module_names: frozenset[str],
659
+ ) -> Iterator[Member]:
660
+ definitions = definition_bindings(ast.Module(body=owner.body, type_ignores=[]))
661
+ occupied = frozenset(definitions) | frozenset(
662
+ name
663
+ for name, uses in visitor.attributes.items()
664
+ if any(use.owner is owner and use.internal for use in uses)
665
+ )
666
+ shadows = _shadows_staticmethod(owner, module)
667
+ for node in owner.body:
668
+ if not isinstance(
669
+ node, ast.FunctionDef | ast.AsyncFunctionDef
670
+ ) or definitions.get(node.name) != [node]:
671
+ continue
672
+ decorators = [
673
+ _qualified(decorator, module) for decorator in node.decorator_list
674
+ ]
675
+ if not decorators and (node.args.posonlyargs or node.args.args):
676
+ kind: Literal["method", "staticmethod"] = "method"
677
+ elif (
678
+ len(decorators) == 1
679
+ and decorators[0] in {"staticmethod", "builtins.staticmethod"}
680
+ and not shadows
681
+ ):
682
+ kind = "staticmethod"
683
+ else:
684
+ continue
685
+ yield Member(
686
+ module.module,
687
+ module.path,
688
+ Definition.of(owner),
689
+ Definition.of(node),
690
+ kind,
691
+ (),
692
+ False,
693
+ False,
694
+ kind == "staticmethod" and _class_dependencies(node, owner),
695
+ occupied,
696
+ module_names,
697
+ )
698
+
699
+
700
+ def _qualified(node: ast.AST, module: ModuleSyntax) -> str | None:
701
+ if isinstance(node, ast.Name):
702
+ return module.bindings.get(
703
+ node.id,
704
+ f"{module.module}.{node.id}"
705
+ if any(
706
+ isinstance(item, ast.ClassDef) and item.name == node.id
707
+ for item in module.tree.body
708
+ )
709
+ else node.id,
710
+ )
711
+ if isinstance(node, ast.Attribute):
712
+ parent = _qualified(node.value, module)
713
+ return f"{parent}.{node.attr}" if parent else None
714
+ if isinstance(node, ast.Subscript):
715
+ return _qualified(node.value, module)
716
+ return None
717
+
718
+
719
+ def _shadows_staticmethod(owner: ast.ClassDef, module: ModuleSyntax) -> bool:
720
+ return any(
721
+ (
722
+ isinstance(node, ast.Name)
723
+ and isinstance(node.ctx, ast.Store | ast.Del)
724
+ and node.id == "staticmethod"
725
+ )
726
+ or (
727
+ isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
728
+ and node.name == "staticmethod"
729
+ )
730
+ for root in [module.tree, owner]
731
+ for node in ast.walk(root)
732
+ )
733
+
734
+
735
+ def _class_dependencies(node: Function, owner: ast.ClassDef) -> bool:
736
+ names = {"__class__", "super", owner.name}
737
+ names.update(
738
+ parameter.name
739
+ for parameter in owner.type_params
740
+ if isinstance(parameter, ast.TypeVar | ast.ParamSpec | ast.TypeVarTuple)
741
+ )
742
+ names.update(
743
+ statement.name
744
+ for statement in owner.body
745
+ if isinstance(statement, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
746
+ )
747
+ names.update(
748
+ child.id
749
+ for statement in owner.body
750
+ if not isinstance(statement, ast.FunctionDef | ast.AsyncFunctionDef)
751
+ for child in ast.walk(statement)
752
+ if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store)
753
+ )
754
+ return any(
755
+ isinstance(child, ast.Name)
756
+ and isinstance(child.ctx, ast.Load)
757
+ and child.id in names
758
+ for child in ast.walk(node)
759
+ )
760
+
761
+
762
+ class _UseVisitor(ast.NodeVisitor):
763
+ def __init__(self, module: ModuleSyntax) -> None:
764
+ self.module = module.module
765
+ self.syntax = module
766
+ self.owner: ast.ClassDef | None = None
767
+ self.roots: set[str] = set()
768
+ self.depth = 0
769
+ self.instance: str | None = None
770
+ self.attributes: dict[str, list[_AttributeUse]] = {}
771
+
772
+ def visit_ClassDef(self, node: ast.ClassDef) -> None:
773
+ owner, roots, depth, instance = (
774
+ self.owner,
775
+ self.roots,
776
+ self.depth,
777
+ self.instance,
778
+ )
779
+ self.owner = node
780
+ self.roots = set()
781
+ self.depth = 0
782
+ self.instance = None
783
+ self.generic_visit(node)
784
+ self.owner = owner
785
+ self.roots = roots
786
+ self.depth = depth
787
+ self.instance = instance
788
+
789
+ def visit_FunctionDef(self, node: Function) -> None:
790
+ previous = self.roots
791
+ previous_instance = self.instance
792
+ args = [*node.args.posonlyargs, *node.args.args]
793
+ bound = set(definition_bindings(ast.Module(body=node.body, type_ignores=[])))
794
+ arguments = [
795
+ *args,
796
+ *node.args.kwonlyargs,
797
+ *(arg for arg in (node.args.vararg, node.args.kwarg) if arg),
798
+ ]
799
+ roots = {self.owner.name} if self.owner and not self.depth else set(previous)
800
+ roots.difference_update(arg.arg for arg in arguments)
801
+ roots.difference_update(bound)
802
+ decorators = {
803
+ _qualified(decorator, self.syntax) for decorator in node.decorator_list
804
+ }
805
+ if (
806
+ self.owner
807
+ and not self.depth
808
+ and args
809
+ and not decorators.intersection({"staticmethod", "builtins.staticmethod"})
810
+ and args[0].arg not in bound
811
+ ):
812
+ roots.add(args[0].arg)
813
+ self.roots = roots
814
+ self.instance = (
815
+ args[0].arg
816
+ if self.owner and not self.depth and args and not decorators
817
+ else None
818
+ )
819
+ self.depth += 1
820
+ self.generic_visit(node)
821
+ self.depth -= 1
822
+ self.roots = previous
823
+ self.instance = previous_instance
824
+
825
+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
826
+ self.visit_FunctionDef(node)
827
+
828
+ def visit_Lambda(self, node: ast.Lambda) -> None:
829
+ previous = self.roots
830
+ arguments = [
831
+ *node.args.posonlyargs,
832
+ *node.args.args,
833
+ *node.args.kwonlyargs,
834
+ *(arg for arg in (node.args.vararg, node.args.kwarg) if arg),
835
+ ]
836
+ self.roots = previous - {arg.arg for arg in arguments}
837
+ self.generic_visit(node)
838
+ self.roots = previous
839
+
840
+ def visit_ListComp(
841
+ self, node: ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp
842
+ ) -> None:
843
+ previous = self.roots
844
+ bound = {
845
+ item.id
846
+ for generator in node.generators
847
+ for item in ast.walk(generator.target)
848
+ if isinstance(item, ast.Name)
849
+ }
850
+ self.roots = previous - bound
851
+ self.generic_visit(node)
852
+ self.roots = previous
853
+
854
+ def visit_SetComp(self, node: ast.SetComp) -> None:
855
+ self.visit_ListComp(node)
856
+
857
+ def visit_DictComp(self, node: ast.DictComp) -> None:
858
+ self.visit_ListComp(node)
859
+
860
+ def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
861
+ self.visit_ListComp(node)
862
+
863
+ def visit_Attribute(self, node: ast.Attribute) -> None:
864
+ definition = (
865
+ node
866
+ if isinstance(node.ctx, ast.Store)
867
+ and isinstance(node.value, ast.Name)
868
+ and node.value.id == self.instance
869
+ and node.value.id in self.roots
870
+ else None
871
+ )
872
+ self._record(node.attr, node.value, node.lineno, definition)
873
+ self.generic_visit(node)
874
+
875
+ def visit_Call(self, node: ast.Call) -> None:
876
+ if (
877
+ isinstance(node.func, ast.Name)
878
+ and node.func.id in {"getattr", "setattr", "hasattr", "delattr"}
879
+ and len(node.args) >= _REFLECTION_ARGUMENTS
880
+ ):
881
+ name = node.args[1]
882
+ if isinstance(name, ast.Constant) and isinstance(name.value, str):
883
+ self._record(name.value, node.args[0], node.lineno)
884
+ self.generic_visit(node)
885
+
886
+ def _record(
887
+ self,
888
+ name: str,
889
+ expression: ast.expr,
890
+ line: int,
891
+ definition: ast.Attribute | None = None,
892
+ ) -> None:
893
+ self.attributes.setdefault(name, []).append(
894
+ _AttributeUse(
895
+ self.module,
896
+ self.syntax.path,
897
+ line,
898
+ self.owner,
899
+ isinstance(expression, ast.Name) and expression.id in self.roots,
900
+ definition,
901
+ )
902
+ )
903
+
904
+
905
+ def _attribute_candidates(
906
+ owner: ast.ClassDef, module: ModuleSyntax, visitor: _UseVisitor
907
+ ) -> Iterator[AttributeMember]:
908
+ definitions = definition_bindings(ast.Module(body=owner.body, type_ignores=[]))
909
+ # Slots and custom attribute hooks make renaming a field a runtime contract.
910
+ if {
911
+ "__slots__",
912
+ "__getattribute__",
913
+ "__getattr__",
914
+ "__setattr__",
915
+ "__delattr__",
916
+ }.intersection(definitions):
917
+ return
918
+ candidates: dict[
919
+ str,
920
+ tuple[
921
+ ast.Attribute | ast.Name,
922
+ Literal["instance-attribute", "class-attribute"],
923
+ ],
924
+ ] = {}
925
+ for name, uses in visitor.attributes.items():
926
+ for use in uses:
927
+ if (
928
+ use.owner is owner
929
+ and use.definition is not None
930
+ and name not in definitions
931
+ ):
932
+ candidates.setdefault(name, (use.definition, "instance-attribute"))
933
+ for statement in owner.body:
934
+ if not isinstance(statement, ast.Assign | ast.AnnAssign):
935
+ continue
936
+ # A call may construct a descriptor rather than ordinary class data.
937
+ if statement.value is not None and not isinstance(
938
+ statement.value,
939
+ ast.Constant | ast.List | ast.Tuple | ast.Set | ast.Dict,
940
+ ):
941
+ continue
942
+ targets = (
943
+ statement.targets
944
+ if isinstance(statement, ast.Assign)
945
+ else [statement.target]
946
+ )
947
+ for target in targets:
948
+ if isinstance(target, ast.Name) and definitions.get(target.id) == [target]:
949
+ candidates.setdefault(target.id, (target, "class-attribute"))
950
+ occupied = frozenset(definitions) | frozenset(
951
+ name
952
+ for name, uses in visitor.attributes.items()
953
+ if any(use.owner is owner and use.internal for use in uses)
954
+ )
955
+ for name, (node, kind) in candidates.items():
956
+ if name.startswith("_"):
957
+ continue
958
+ yield AttributeMember(
959
+ module.module,
960
+ module.path,
961
+ Definition.of(owner),
962
+ Definition(name, node.lineno, node.col_offset),
963
+ name,
964
+ kind,
965
+ tuple(
966
+ sorted(
967
+ {
968
+ use.line
969
+ for use in visitor.attributes.get(name, [])
970
+ if use.owner is owner and use.internal
971
+ }
972
+ )
973
+ ),
974
+ occupied,
975
+ )