smelt-cli 0.1.0__py3-none-any.whl

smelt/analysis/imports.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import ast
+import sys
+from collections import defaultdict
+from dataclasses import dataclass
+from importlib.machinery import PathFinder
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import grimp
+from grimp.application.config import settings as grimp_settings
+from grimp.application.ports.modulefinder import (
+    AbstractModuleFinder,
+    FoundPackage,
+    ModuleFile,
+)
+from grimp.application.ports.packagefinder import AbstractPackageFinder
+from grimp.domain.valueobjects import Module
+from grimp.exceptions import SourceSyntaxError
+
+from smelt.analysis.parsing import (
+    AnalysisError,
+    AstCache,
+    python_note,
+    resolve_relative,
+    type_checking_lines,
+)
+from smelt.model import is_within
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from grimp.application.ports.filesystem import AbstractFileSystem
+
+    from smelt.analysis.files import FileIndex
+
+
+@dataclass(frozen=True, slots=True)
+class ImportDetail:
+    importer: str
+    # Grimp's resolved target; external packages are squashed to their top level.
+    imported: str
+    line: int
+    line_contents: str
+    # Fully qualified names the statement imports, e.g. ``sqlalchemy.orm.Session``.
+    names: tuple[str, ...]
+    type_checking: bool
+    external: bool
+    column: int
+    end_column: int
+
+    @property
+    def top_level(self) -> str:
+        return self.imported.split(".")[0]
+
+
+def is_stdlib(module: str) -> bool:
+    return module.split(".", maxsplit=1)[0] in sys.stdlib_module_names
+
+
+class _SourceRootPackageFinder(AbstractPackageFinder):
+    def __init__(self, search_paths: list[str]) -> None:
+        self._search_paths = search_paths
+
+    def determine_package_directories(
+        self, package_name: str, file_system: AbstractFileSystem
+    ) -> set[str]:
+        spec = PathFinder.find_spec(package_name, self._search_paths)
+        if spec is None or not spec.submodule_search_locations:
+            msg = f"Could not find package '{package_name}'."
+            raise ValueError(msg)
+        return set(spec.submodule_search_locations)
+
+
+class _IndexedModuleFinder(AbstractModuleFinder):
+    """Give Grimp the same modules and namespace packages as Smelt's file index."""
+
+    def __init__(self, files: FileIndex) -> None:
+        self._files = files
+
+    def find_package(
+        self,
+        package_name: str,
+        package_directory: str,
+        file_system: AbstractFileSystem,
+    ) -> FoundPackage:
+        directory = Path(package_directory)
+        module_files = frozenset(
+            ModuleFile(
+                Module(source.module), file_system.get_mtime(str(source.absolute))
+            )
+            for source in self._files.sources.values()
+            if is_within(source.module, package_name)
+            and source.absolute.is_relative_to(directory)
+        )
+        namespace_packages = frozenset(
+            package.module
+            for package in self._files.packages.values()
+            if is_within(package.module, package_name)
+            and not package.has_init
+            and (self._files.root / package.path).is_relative_to(directory)
+        )
+        return FoundPackage(
+            name=package_name,
+            directory=package_directory,
+            module_files=module_files,
+            namespace_packages=namespace_packages,
+        )
+
+
+class ImportIndex:
+    def __init__(
+        self, graph: grimp.ImportGraph, files: FileIndex, asts: AstCache
+    ) -> None:
+        self.graph = graph
+        self.files = files
+        self._asts = asts
+        roots = files.config.project.root_packages
+        self.first_party = frozenset(
+            m for m in graph.modules if any(is_within(m, r) for r in roots)
+        )
+        self._outgoing: dict[str, list[ImportDetail]] = {}
+        self._incoming: dict[str, list[ImportDetail]] | None = None
+
+    @classmethod
+    def build(cls, files: FileIndex, asts: AstCache) -> ImportIndex:
+        project = files.config.project
+        packages = [
+            p for p in project.root_packages if p not in files.missing_root_packages
+        ]
+        if not packages:
+            msg = "none of project.root_packages were found under project.source_roots"
+            raise AnalysisError(msg)
+        search_paths = [
+            str((files.root / root).resolve()) for root in project.source_roots
+        ]
+        previous_package_finder = grimp_settings.PACKAGE_FINDER
+        previous_module_finder = grimp_settings.MODULE_FINDER
+        grimp_settings.configure(
+            PACKAGE_FINDER=_SourceRootPackageFinder(search_paths),
+            MODULE_FINDER=_IndexedModuleFinder(files),
+        )
+        try:
+            graph = grimp.build_graph(
+                packages[0],
+                *packages[1:],
+                include_external_packages=True,
+                cache_dir=None,
+            )
+        except SourceSyntaxError as exc:
+            raise AnalysisError(str(exc) + python_note(files.root)) from exc
+        finally:
+            grimp_settings.configure(
+                PACKAGE_FINDER=previous_package_finder,
+                MODULE_FINDER=previous_module_finder,
+            )
+        for module in list(graph.modules):
+            if (
+                any(is_within(module, p) for p in packages)
+                and module not in files.sources
+                and module not in files.packages
+            ):
+                graph.remove_module(module)
+        missing = files.sources.keys() - graph.modules
+        if missing:
+            examples = ", ".join(sorted(missing)[:3])
+            raise AnalysisError(
+                f"import graph omitted {len(missing)} source module(s): {examples}"
+            )
+        return cls(graph, files, asts)
+
+    def is_external(self, module: str) -> bool:
+        return module not in self.first_party
+
+    def modules(self) -> list[str]:
+        return sorted(m for m in self.first_party if m in self.files.sources)
+
+    def imports_of(self, module: str) -> list[ImportDetail]:
+        cached = self._outgoing.get(module)
+        if cached is None:
+            cached = self._details_for(module)
+            self._outgoing[module] = cached
+        return cached
+
+    def importers_of(self, module: str) -> list[ImportDetail]:
+        if self._incoming is None:
+            incoming: dict[str, list[ImportDetail]] = defaultdict(list)
+            for detail in self.all_imports():
+                incoming[detail.imported].append(detail)
+            self._incoming = dict(incoming)
+        return self._incoming.get(module, [])
+
+    def all_imports(self) -> Iterator[ImportDetail]:
+        for module in self.modules():
+            yield from self.imports_of(module)
+
+    def first_party_edges(
+        self, *, include_type_checking: bool = True
+    ) -> dict[str, set[str]]:
+        adjacency: dict[str, set[str]] = defaultdict(set)
+        for detail in self.all_imports():
+            if detail.external or (detail.type_checking and not include_type_checking):
+                continue
+            adjacency[detail.importer].add(detail.imported)
+        return adjacency
+
+    def _details_for(self, module: str) -> list[ImportDetail]:
+        source = self.files.sources.get(module)
+        if source is None or module not in self.first_party:
+            return []
+        tree = self._asts.parse(source.path)
+        statements = _statements_by_line(tree)
+        guarded = type_checking_lines(tree)
+        details: list[ImportDetail] = []
+        for imported in sorted(self.graph.find_modules_directly_imported_by(module)):
+            external = imported not in self.first_party
+            for raw in self.graph.get_import_details(
+                importer=module, imported=imported
+            ):
+                line = int(raw["line_number"])
+                node = statements.get(line)
+                names, column, end_column = _describe(
+                    node, module, source.is_package, imported, raw["line_contents"]
+                )
+                details.append(
+                    ImportDetail(
+                        importer=module,
+                        imported=imported,
+                        line=line,
+                        line_contents=str(raw["line_contents"]),
+                        names=names,
+                        type_checking=line in guarded,
+                        external=external,
+                        column=column,
+                        end_column=end_column,
+                    )
+                )
+        details.sort(key=lambda d: (d.line, d.column, d.imported))
+        return details
+
+
+def _statements_by_line(tree: ast.Module) -> dict[int, ast.Import | ast.ImportFrom]:
+    return {
+        node.lineno: node
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Import | ast.ImportFrom)
+    }
+
+
+def _describe(
+    node: ast.Import | ast.ImportFrom | None,
+    module: str,
+    is_package: bool,
+    imported: str,
+    line_contents: str,
+) -> tuple[tuple[str, ...], int, int]:
+    """Imported names and the 1-based column span to underline on the first line."""
+    if node is None:
+        return (imported,), 1, len(line_contents) + 1
+    if isinstance(node, ast.Import):
+        return _describe_import(node, imported, line_contents)
+    return _describe_import_from(node, module, is_package, imported)
+
+
+def _describe_import(
+    node: ast.Import, imported: str, line_contents: str
+) -> tuple[tuple[str, ...], int, int]:
+    first_line_end = (
+        node.end_col_offset if node.end_lineno == node.lineno else len(line_contents)
+    )
+    names: tuple[str, ...] = (imported,)
+    span = (node.col_offset + 1, (first_line_end or 0) + 1)
+    for alias in node.names:
+        if is_within(alias.name, imported) or is_within(imported, alias.name):
+            names = (alias.name,)
+            if alias.lineno == node.lineno:
+                span = (alias.col_offset + 1, (alias.end_col_offset or 0) + 1)
+            break
+    return names, *span
+
+
+def _describe_import_from(
+    node: ast.ImportFrom, module: str, is_package: bool, imported: str
+) -> tuple[tuple[str, ...], int, int]:
+    base = resolve_relative(
+        module, is_package=is_package, level=node.level, target=node.module
+    )
+    names = tuple(
+        f"{base}.{alias.name}" if base else alias.name for alias in node.names
+    )
+    for alias, name in zip(node.names, names, strict=True):
+        if name == imported and alias.lineno == node.lineno:
+            return (name,), alias.col_offset + 1, (alias.end_col_offset or 0) + 1
+    matching = tuple(
+        n for n in names if is_within(n, imported) or is_within(imported, n)
+    )
+    if len(node.names) == 1 and node.names[0].lineno == node.lineno:
+        alias = node.names[0]
+        return matching or names, alias.col_offset + 1, (alias.end_col_offset or 0) + 1
+    start = node.col_offset + len("from ")
+    text = "." * node.level + (node.module or "")
+    return matching or names, start + 1, start + len(text) + 1

smelt/analysis/parsing.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import ast
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from smelt.analysis.files import FileIndex
+
+
+class AnalysisError(Exception):
+    """The project cannot be analyzed (missing packages, syntax errors, ...)."""
+
+
+@dataclass
+class AstCache:
+    files: FileIndex
+    _trees: dict[str, ast.Module] = field(default_factory=dict)
+
+    def parse(self, path: str) -> ast.Module:
+        tree = self._trees.get(path)
+        if tree is None:
+            source = self.files.read_text(path)
+            try:
+                tree = ast.parse(source, filename=path)
+            except SyntaxError as exc:
+                msg = f"{path}:{exc.lineno}: syntax error: {exc.msg}"
+                raise AnalysisError(msg + python_note(self.files.root)) from exc
+            self._trees[path] = tree
+        return tree
+
+
+_VERSION_BOUND = re.compile(r"(?:>=|~=|==)\s*3\.(\d+)")
+
+
+def python_note(root: Path) -> str:
+    """Explain a syntax error that may just be newer syntax than the running Python.
+
+    ``ast`` only knows the grammar of the interpreter smelt runs on, so a 3.14
+    project checked by smelt on 3.12 fails on ``except A, B:`` or t-strings.
+    """
+    running = sys.version_info[:2]
+    note = f" (parsed by Python {running[0]}.{running[1]})"
+    target = _target_python(root)
+    if target is not None and target > running:
+        version = f"{target[0]}.{target[1]}"
+        note += (
+            f"; the project targets Python {version}, so run smelt on it, "
+            f"e.g. `uvx -p {version} --from smelt-cli smelt check`"
+        )
+    return note
+
+
+def _target_python(root: Path) -> tuple[int, int] | None:
+    found: list[tuple[int, int]] = []
+    try:
+        data = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        data = {}
+    requires = data.get("project", {}).get("requires-python", "")
+    if isinstance(requires, str) and (match := _VERSION_BOUND.search(requires)):
+        found.append((3, int(match.group(1))))
+    try:
+        pinned = (root / ".python-version").read_text(encoding="utf-8").split()
+    except OSError:
+        pinned = []
+    if pinned and (match := re.match(r"3\.(\d+)", pinned[0])):
+        found.append((3, int(match.group(1))))
+    return max(found, default=None)
+
+
+def type_checking_lines(tree: ast.Module) -> frozenset[int]:
+    """Line numbers inside ``if TYPE_CHECKING:`` blocks."""
+    lines: set[int] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If) and _is_type_checking_test(node.test):
+            for child in node.body:
+                end = child.end_lineno or child.lineno
+                lines.update(range(child.lineno, end + 1))
+    return frozenset(lines)
+
+
+def _is_type_checking_test(test: ast.expr) -> bool:
+    if isinstance(test, ast.Name):
+        return test.id == "TYPE_CHECKING"
+    if isinstance(test, ast.Attribute):
+        return test.attr == "TYPE_CHECKING"
+    return False
+
+
+def resolve_relative(
+    module: str, *, is_package: bool, level: int, target: str | None
+) -> str:
+    """Resolve ``from <level dots><target> import ...`` inside ``module``."""
+    if level == 0:
+        return target or ""
+    parts = module.split(".")
+    if not is_package:
+        parts = parts[:-1]
+    if level > 1:
+        parts = parts[: len(parts) - (level - 1)]
+    base = ".".join(parts)
+    if target:
+        return f"{base}.{target}" if base else target
+    return base

smelt/analysis/roles.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from smelt.analysis.syntax import ClassInfo, SyntaxIndex
+    from smelt.analysis.types import TypeIndex
+    from smelt.config.models import SmeltConfig
+
+# Subclassing a Protocol without listing Protocol again makes a concrete class.
+_DIRECT_ONLY_BASES = frozenset({"typing.Protocol", "typing_extensions.Protocol"})
+
+
+@dataclass(frozen=True, slots=True)
+class RoleMatch:
+    role: str
+    cls: ClassInfo
+
+
+class RoleIndex:
+    def __init__(
+        self,
+        config: SmeltConfig,
+        syntax: SyntaxIndex,
+        types: TypeIndex | None = None,
+    ) -> None:
+        self.config = config
+        self.syntax = syntax
+        self.types = types
+        self.by_class: dict[str, frozenset[str]] = self._detect()
+
+    def _detect(self) -> dict[str, frozenset[str]]:
+        roles: dict[str, set[str]] = defaultdict(set)
+        ancestors = {
+            name: self.syntax.ancestors(info)
+            for name, info in self.syntax.classes.items()
+        }
+        self._detect_by_base(roles, ancestors)
+        self._detect_by_ancestry(roles, ancestors)
+        if self.types is not None:
+            self._detect_structurally(roles)
+        return {name: frozenset(found) for name, found in roles.items() if found}
+
+    def _detect_by_base(
+        self, roles: dict[str, set[str]], ancestors: dict[str, list[str]]
+    ) -> None:
+        for role_name, role in self.config.architecture.roles.items():
+            base = role.detect.base
+            if base is None:
+                continue
+            for name, info in self.syntax.classes.items():
+                direct = {self.syntax.canonical(b) for b in info.bases if b}
+                wanted = direct if base in _DIRECT_ONLY_BASES else ancestors[name]
+                if base in wanted:
+                    roles[name].add(role_name)
+
+    def _detect_by_ancestry(
+        self, roles: dict[str, set[str]], ancestors: dict[str, list[str]]
+    ) -> None:
+        """Propagate ``implements`` roles down the inheritance chains, until stable."""
+        changed = True
+        while changed:
+            changed = False
+            for role_name, target in self._implement_roles():
+                for name in self.syntax.classes:
+                    if {role_name, target} & roles[name]:
+                        continue
+                    if any(target in roles.get(a, ()) for a in ancestors[name]):
+                        roles[name].add(role_name)
+                        changed = True
+
+    def _implement_roles(self) -> list[tuple[str, str]]:
+        return [
+            (name, role.detect.implements)
+            for name, role in self.config.architecture.roles.items()
+            if role.detect.implements is not None
+        ]
+
+    def _detect_structurally(self, roles: dict[str, set[str]]) -> None:
+        """With type information, a class can implement a port without inheriting it."""
+        types = self.types
+        if types is None:  # pragma: no cover - guarded by the caller
+            return
+        for role_name, target in self._implement_roles():
+            ports = sorted(name for name, found in roles.items() if target in found)
+            candidates = [
+                name
+                for name in self.syntax.classes
+                if not {role_name, target} & roles[name]
+            ]
+            pairs = [(name, port) for name in candidates for port in ports]
+            types.prepare(pairs)
+            for name, port in pairs:
+                if types.implements(name, port):
+                    roles[name].add(role_name)
+
+    def roles_of(self, qualname: str) -> frozenset[str]:
+        return self.by_class.get(qualname, frozenset())
+
+    def classes_with(self, role: str) -> list[ClassInfo]:
+        classes = self.syntax.classes
+        return [
+            classes[name]
+            for name, roles in sorted(self.by_class.items())
+            if role in roles
+        ]
+
+    def matches(self) -> list[RoleMatch]:
+        classes = self.syntax.classes
+        return [
+            RoleMatch(role, classes[name])
+            for name, roles in sorted(self.by_class.items())
+            for role in sorted(roles)
+        ]
+
+    def module_roles(self) -> dict[str, frozenset[str]]:
+        result: dict[str, set[str]] = defaultdict(set)
+        for match in self.matches():
+            result[match.cls.module].add(match.role)
+        return {module: frozenset(roles) for module, roles in result.items()}