pytest-fsd 0.2.0__py3-none-any.whl

pytest_fsd/__init__.py

@@ -0,0 +1,84 @@
+# src/pytest_fsd/__init__.py
+"""
+pytest-fsd: FSD Architecture Validation for Python Projects.
+
+Provides validate_fsd_architecture() — a single facade function
+that runs all FSD rules configured in pyproject.toml.
+"""
+
+from typing import List
+
+from ._lib.violations import Violation
+from .config import load_config
+from .rules import (
+    ambiguous_slice_names,
+    forbidden_imports,
+    no_cross_imports,
+    no_layer_public_api,
+    no_public_api_sidestep,
+    no_segmentless_slices,
+    no_segments_on_sliced_layers,
+    no_ui_in_app,
+    public_api,
+    repetitive_naming,
+    segments_by_purpose,
+    unknown_folders_in_root,
+)
+from .rules import (
+    excessive_slicing,
+    no_file_segments,
+    no_reserved_folder_names,
+    shared_lib_grouping,
+)
+
+# Базовые правила — всегда активны
+CORE_RULES = [
+    forbidden_imports,
+    no_cross_imports,
+    no_public_api_sidestep,
+    no_layer_public_api,
+    no_ui_in_app,
+    repetitive_naming,
+    no_segmentless_slices,
+    segments_by_purpose,
+    ambiguous_slice_names,
+    no_segments_on_sliced_layers,
+    public_api,
+    unknown_folders_in_root,
+]
+
+# Дополнительные правила — включаются через extra_rules в pyproject.toml
+EXTRA_RULES = {
+    "excessive-slicing": excessive_slicing,
+    "shared-lib-grouping": shared_lib_grouping,
+    "no-file-segments": no_file_segments,
+    "no-reserved-folder-names": no_reserved_folder_names,
+}
+
+
+def validate_fsd_architecture(project_root: str = ".") -> None:
+    """
+    Validate the project architecture against FSD rules.
+
+    Reads configuration from pyproject.toml -> [tool.pytest_fsd].
+    Runs all core rules + any extra_rules specified in config.
+    Raises AssertionError if any violations are found.
+    """
+    config = load_config(project_root)
+    all_violations: List[Violation] = []
+
+    # Запускаем базовые правила
+    for rule_module in CORE_RULES:
+        all_violations.extend(rule_module.check(config, project_root))
+
+    # Запускаем дополнительные правила, если они включены в конфиге
+    for extra_rule_name in config.extra_rules:
+        rule_module = EXTRA_RULES.get(extra_rule_name)
+        if rule_module is not None:
+            all_violations.extend(rule_module.check(config, project_root))
+
+    if all_violations:
+        error_msg = "FSD Architecture Validation failed:\n"
+        for v in all_violations:
+            error_msg += v.format() + "\n"
+        raise AssertionError(error_msg)

pytest_fsd/_lib/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities for pytest-fsd rules."""

pytest_fsd/_lib/ast_utils.py

@@ -0,0 +1,54 @@
+# src/pytest_fsd/_lib/ast_utils.py
+"""Shared AST parsing utilities used by multiple rules."""
+
+import ast
+from typing import List, Tuple, Optional
+
+
+def get_imports_from_file(
+    filepath: str,
+) -> List[Tuple[int, Optional[str], int, List[str]]]:
+    """Return list of (line_number, full_module_path, level, imported_names).
+
+    Level represents relative imports:
+    0 = absolute import (e.g. `import foo` or `from foo import bar`)
+    1 = current directory (`from . import bar` -> module=None, level=1)
+    2 = parent directory (`from ..foo import bar` -> module='foo', level=2)
+    """
+    imports = []
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            tree = ast.parse(f.read(), filename=filepath)
+    except Exception:
+        return []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append((node.lineno, alias.name, 0, [alias.name]))
+        elif isinstance(node, ast.ImportFrom):
+            names = [alias.name for alias in node.names]
+            imports.append((node.lineno, node.module, node.level, names))
+
+    return imports
+
+
+def get_exported_names(filepath: str) -> Optional[List[str]]:
+    """Return the list of names exported in __all__ if defined, or None if not defined."""
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            tree = ast.parse(f.read(), filename=filepath)
+    except Exception:
+        return None
+
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and target.id == "__all__":
+                    if isinstance(node.value, (ast.List, ast.Tuple)):
+                        return [
+                            elt.value
+                            for elt in node.value.elts
+                            if getattr(elt, "value", None) is not None
+                        ]
+    return None

pytest_fsd/_lib/fs_utils.py

@@ -0,0 +1,31 @@
+# src/pytest_fsd/_lib/fs_utils.py
+"""Shared filesystem utilities used by multiple rules."""
+
+import os
+from typing import List
+
+from ..config import FsdConfig
+
+# Стандартные сегменты FSD для Python-проектов
+STANDARD_SEGMENTS = ("ui", "model", "api", "lib", "config")
+
+
+def get_sliced_layers(config: FsdConfig) -> List[str]:
+    """Return layers that contain slices (excluding app and shared)."""
+    return [
+        layer_name
+        for layer_name in config.layers
+        if layer_name not in ("app", "shared")
+    ]
+
+
+def get_slices(layer: str, base_path: str) -> List[str]:
+    """Return list of slice directory names inside a given layer."""
+    path = os.path.join(base_path, layer)
+    if not os.path.isdir(path):
+        return []
+    return [
+        d
+        for d in os.listdir(path)
+        if os.path.isdir(os.path.join(path, d)) and not d.startswith("_")
+    ]

pytest_fsd/_lib/violations.py

@@ -0,0 +1,22 @@
+# src/pytest_fsd/_lib/violations.py
+"""Unified violation dataclass for all FSD rules."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Violation:
+    """Represents a single FSD architecture violation."""
+
+    rule: str
+    file_path: str
+    message: str
+    line_number: Optional[int] = None
+
+    def format(self) -> str:
+        """Format the violation as a human-readable string."""
+        location = self.file_path
+        if self.line_number is not None:
+            location += f":{self.line_number}"
+        return f" - [{self.rule}] {location} -> {self.message}"

pytest_fsd/config.py

@@ -0,0 +1,62 @@
+import os
+
+from dataclasses import dataclass, field
+from typing import List
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+
+@dataclass
+class FsdConfig:
+    """Configuration for pytest-fsd, read from [tool.pytest_fsd] in pyproject.toml."""
+
+    base_path: str = "src"
+    layers: List[str] = field(
+        default_factory=lambda: [
+            "app",
+            "pages",
+            "widgets",
+            "features",
+            "entities",
+            "shared",
+        ]
+    )
+    ignore_paths: List[str] = field(default_factory=list)
+    extra_rules: List[str] = field(default_factory=list)
+
+
+# Доступные дополнительные правила
+AVAILABLE_EXTRA_RULES = {
+    "excessive-slicing",
+    "shared-lib-grouping",
+    "no-file-segments",
+    "no-reserved-folder-names",
+}
+
+
+def load_config(root_dir: str) -> FsdConfig:
+    """Загружает настройки [tool.pytest_fsd] из pyproject.toml."""
+    pyproject_path = os.path.join(root_dir, "pyproject.toml")
+
+    if not os.path.exists(pyproject_path):
+        return FsdConfig()
+
+    with open(pyproject_path, "rb") as f:
+        data = tomllib.load(f)
+
+    tool_config = data.get("tool", {}).get("pytest_fsd", {})
+
+    config = FsdConfig()
+    if "base_path" in tool_config:
+        config.base_path = tool_config["base_path"]
+    if "layers" in tool_config:
+        config.layers = tool_config["layers"]
+    if "ignore_paths" in tool_config:
+        config.ignore_paths = tool_config["ignore_paths"]
+    if "extra_rules" in tool_config:
+        config.extra_rules = tool_config["extra_rules"]
+
+    return config

pytest_fsd/rules/__init__.py

@@ -0,0 +1 @@
+"""Rules registry for pytest-fsd."""

pytest_fsd/rules/ambiguous_slice_names/README.md

@@ -0,0 +1,29 @@
+# `ambiguous-slice-names`
+
+Forbid slice names that match segment names in the `shared` layer. For example, if `shared/i18n` exists, having `features/i18n` is confusing.
+
+## Examples
+
+✅ Pass:
+
+```
+📂 shared/
+  📂 ui/
+  📂 i18n/
+📂 features/
+  📂 auth/          # OK: "auth" is not a shared segment
+```
+
+❌ Fail:
+
+```
+📂 shared/
+  📂 ui/
+  📂 i18n/
+📂 features/
+  📂 i18n/          # ❌ same name as shared/i18n
+```
+
+## Rationale
+
+When there is a segment in `shared` with the same name as a slice in another layer, it becomes ambiguous where new code should be written and obscures the search for existing code.

pytest_fsd/rules/ambiguous_slice_names/__init__.py

@@ -0,0 +1,70 @@
+# src/pytest_fsd/rules/ambiguous_slice_names/__init__.py
+"""
+[Rule: ambiguous-slice-names]
+Slice names should not match segment names in the shared layer.
+For example, if shared/i18n exists, having features/i18n is confusing.
+"""
+
+import os
+from typing import Dict, List
+
+from ..._lib.fs_utils import get_sliced_layers
+from ..._lib.violations import Violation
+from ...config import FsdConfig
+
+RULE_NAME = "ambiguous-slice-names"
+
+
+def check(config: FsdConfig, project_root: str) -> List[Violation]:
+    """Verify that slice names don't collide with shared segment names."""
+    violations = []
+    base_dir = os.path.join(project_root, config.base_path)
+
+    # Собираем имена сегментов из shared
+    shared_path = os.path.join(base_dir, "shared")
+    if not os.path.isdir(shared_path):
+        return violations
+
+    # Собираем имена компонентов (слайсов) внутри сегментов shared
+    # Например: shared/ui/button -> регистрируем 'button' (внутри сегмента 'ui')
+    shared_slices: Dict[str, str] = {}
+    for segment in os.listdir(shared_path):
+        segment_path = os.path.join(shared_path, segment)
+        if not os.path.isdir(segment_path) or segment.startswith("_"):
+            continue
+
+        for shared_slice in os.listdir(segment_path):
+            if os.path.isdir(
+                os.path.join(segment_path, shared_slice)
+            ) and not shared_slice.startswith("_"):
+                shared_slices[shared_slice] = segment
+
+    if not shared_slices:
+        return violations
+
+    # Проверяем слайсы во всех слоях
+    sliced_layers = get_sliced_layers(config)
+
+    for layer in sliced_layers:
+        layer_path = os.path.join(base_dir, layer)
+        if not os.path.isdir(layer_path):
+            continue
+
+        for slice_name in os.listdir(layer_path):
+            slice_path = os.path.join(layer_path, slice_name)
+            if not os.path.isdir(slice_path) or slice_name.startswith("_"):
+                continue
+
+            if slice_name in shared_slices:
+                conflict_segment = shared_slices[slice_name]
+                violations.append(
+                    Violation(
+                        rule=RULE_NAME,
+                        file_path=slice_path,
+                        message=f"Slice '{slice_name}' in layer '{layer}' has the same name as "
+                        f"component 'shared/{conflict_segment}/{slice_name}'. This creates ambiguity about "
+                        f"where new code should be placed.",
+                    )
+                )
+
+    return violations

pytest_fsd/rules/excessive_slicing/README.md

@@ -0,0 +1,41 @@
+# `excessive-slicing`
+
+> ⚡ **Optional rule.** Enable via `extra_rules = ["excessive-slicing"]` in `pyproject.toml`.
+
+Forbid having too many ungrouped slices in a single layer.
+
+**Threshold: 20 slices per layer** (as per Steiger defaults).
+
+## Configuration
+
+```toml
+[tool.pytest_fsd]
+extra_rules = ["excessive-slicing"]
+```
+
+## Examples
+
+✅ Pass:
+
+```text
+📂 features/
+  📂 auth/
+  📂 profile/
+  📂 settings/
+  # ... up to 20 slices is fine
+```
+
+❌ Fail:
+
+```text
+📂 features/        # ❌ 21+ slices
+  📂 comments/
+  📂 posts/
+  📂 users/
+  📂 cars/
+  📂 ... (21+ directories)
+```
+
+## Rationale
+
+Having too many slices in a layer makes it harder to discover features in a project and promotes excessive decomposition. Consider grouping related slices into nested folders.

pytest_fsd/rules/excessive_slicing/__init__.py

@@ -0,0 +1,47 @@
+# src/pytest_fsd/rules/excessive_slicing/__init__.py
+"""
+[Rule: excessive-slicing] (optional)
+Forbid having too many slices in a single layer.
+Default threshold: 20 slices per layer.
+"""
+
+import os
+from typing import List
+
+from ..._lib.fs_utils import get_sliced_layers
+from ..._lib.violations import Violation
+from ...config import FsdConfig
+
+RULE_NAME = "excessive-slicing"
+DEFAULT_THRESHOLD = 20
+
+
+def check(config: FsdConfig, project_root: str) -> List[Violation]:
+    """Verify that no layer contains too many slices."""
+    violations = []
+    base_dir = os.path.join(project_root, config.base_path)
+    sliced_layers = get_sliced_layers(config)
+
+    for layer in sliced_layers:
+        layer_path = os.path.join(base_dir, layer)
+        if not os.path.isdir(layer_path):
+            continue
+
+        slices = [
+            d
+            for d in os.listdir(layer_path)
+            if os.path.isdir(os.path.join(layer_path, d)) and not d.startswith("_")
+        ]
+
+        if len(slices) > DEFAULT_THRESHOLD:
+            violations.append(
+                Violation(
+                    rule=RULE_NAME,
+                    file_path=layer_path,
+                    message=f"Layer '{layer}' contains {len(slices)} slices "
+                    f"(threshold: {DEFAULT_THRESHOLD}). Too many slices make navigation "
+                    f"difficult. Consider grouping related slices.",
+                )
+            )
+
+    return violations

pytest_fsd/rules/forbidden_imports/README.md

@@ -0,0 +1,37 @@
+# `forbidden-imports`
+
+Forbids imports from higher layers. This is in accordance with the FSD import rule on layers:
+
+> A module in a slice can only import other slices when they are located on layers strictly below.
+
+This rule maps to Steiger's `no-higher-level-imports`.
+
+## How it works
+
+Uses `pytest-archon` to dynamically verify that modules in each layer do not import from any layer above them in the configured hierarchy.
+
+For example, with default layers `["app", "windows", "widgets", "features", "entities", "shared"]`:
+
+- `features` can import from `entities` and `shared`
+- `features` **cannot** import from `widgets`, `windows`, or `app`
+
+## Examples
+
+✅ Pass:
+
+```python
+# src/features/auth/model/handler.py
+from src.entities.user import User        # OK: entities is below features
+from src.shared.lib.hash import hash_pw   # OK: shared is below features
+```
+
+❌ Fail:
+
+```python
+# src/features/auth/model/handler.py
+from src.pages.home import HomePage       # VIOLATION: pages is above features
+```
+
+## Rationale
+
+This is one of the main rules of Feature-Sliced Design. It ensures low coupling and predictability during refactoring.

pytest_fsd/rules/forbidden_imports/__init__.py

@@ -0,0 +1,61 @@
+# src/pytest_fsd/rules/forbidden_imports/__init__.py
+"""
+[Rule: forbidden-imports / no-higher-level-imports]
+Layers can only import from layers below them in the FSD hierarchy.
+Uses pytest-archon for dynamic runtime checking.
+"""
+
+import os
+from typing import List
+
+from pytest_archon import archrule
+
+from ..._lib.violations import Violation
+from ...config import FsdConfig
+
+RULE_NAME = "forbidden-imports"
+
+
+def check(config: FsdConfig, project_root: str) -> List[Violation]:
+    """Verify that each layer only imports from layers below it."""
+    violations = []
+    base_path = config.base_path
+    layers = config.layers
+
+    for i, current_layer in enumerate(layers):
+        layer_path = os.path.join(project_root, base_path, current_layer)
+        if not os.path.isdir(layer_path):
+            continue
+
+        # Проверяем наличие .py файлов в слое
+        has_python_files = False
+        for _, _, files in os.walk(layer_path):
+            if any(f.endswith(".py") and f != "__init__.py" for f in files):
+                has_python_files = True
+                break
+
+        if not has_python_files:
+            continue
+
+        forbidden_layers = layers[:i]
+        if forbidden_layers:
+            forbidden_modules = [f"{base_path}.{layer}.*" for layer in forbidden_layers]
+            try:
+                (
+                    archrule(
+                        f"[{current_layer.upper()}] must not import layers above it"
+                    )
+                    .match(f"{base_path}.{current_layer}.*")
+                    .should_not_import(*forbidden_modules)
+                    .check(base_path)
+                )
+            except BaseException as e:
+                violations.append(
+                    Violation(
+                        rule=RULE_NAME,
+                        file_path=current_layer,
+                        message=str(e).strip(),
+                    )
+                )
+
+    return violations

pytest_fsd/rules/import_locality/README.md

@@ -0,0 +1,44 @@
+# `import-locality`
+
+> 🔶 **Covered by Ruff.** This rule is NOT part of `pytest-fsd` core checks, but is fully enforceable via Ruff's `TID` (flake8-tidy-imports) plugin.
+
+Require that imports **within the same slice** be relative, and imports **from another slice** be absolute.
+
+## Ruff Configuration
+
+```toml
+[tool.ruff.lint]
+select = ["TID"]  # flake8-tidy-imports
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"  # Запрет relative imports из родительских пакетов
+```
+
+### What `TID` covers
+
+| Rule     | Description                                      |
+| -------- | ------------------------------------------------ |
+| `TID251` | Banned imports (configurable)                    |
+| `TID252` | Relative imports from parent packages are banned |
+
+## How it maps to FSD
+
+```python
+# src/entities/user/ui/avatar.py
+
+# ✅ Relative import within the same slice — OK
+from .styles import avatar_styles
+
+# ✅ Absolute import from another slice — OK
+from src.shared.ui import Button
+
+# ❌ Absolute self-import — wasteful
+from src.entities.user.ui.styles import avatar_styles
+
+# ❌ Relative import from another slice — fragile
+from ...shared.ui import Button
+```
+
+## Rationale
+
+Imports between slices should be absolute to stay stable during refactors. Imports within a slice should be relative to keep them short and because the public API should not need to expose internal modules.

pytest_fsd/rules/inconsistent_naming/README.md

@@ -0,0 +1,34 @@
+# `inconsistent-naming`
+
+> 🔶 **Covered by Ruff.** This rule is NOT part of `pytest-fsd` core checks, but is fully enforceable via Ruff's `N` (pep8-naming) plugin.
+
+Ensure that all modules and directories follow consistent naming conventions (`snake_case` for Python).
+
+In Steiger, this rule specifically checks consistency of **pluralization** in the `entities` layer (e.g., all entities should be either singular or plural, not mixed). In Python, `Ruff` handles the broader naming consistency problem via PEP 8 conventions.
+
+## Ruff Configuration
+
+```toml
+[tool.ruff.lint]
+select = ["N"]  # pep8-naming — enforces snake_case for modules, variables, functions
+```
+
+### What `N` covers
+
+| Rule   | Description                                     |
+| ------ | ----------------------------------------------- |
+| `N801` | Class names should use CapitalCase              |
+| `N802` | Function names should be lowercase              |
+| `N806` | Variable names should be lowercase              |
+| `N815` | Variable in class scope should not be camelCase |
+| `N999` | Invalid module name                             |
+
+## Steiger Equivalent
+
+```text
+📂 entities/
+  📂 users/      # Plural
+  📂 post/       # ❌ Singular — inconsistent with "users"
+```
+
+In Python FSD, use `snake_case` everywhere and pick one pluralization style for your entities layer. Ruff enforces the `snake_case` part; pluralization consistency is a team convention enforced via code review.

pytest_fsd/rules/insignificant_slice/README.md

@@ -0,0 +1,26 @@
+# `insignificant-slice`
+
+> 🟡 **Manual review only.** This rule requires full import graph analysis which is beyond the scope of `pytest-fsd`.
+
+Detects slices that have no references (unused) or only one reference (can be merged into the layer above).
+
+## Why not automated?
+
+This rule requires building a complete import graph of the project and counting how many other modules reference each slice. This is a complex analysis that:
+
+1. Requires resolving all import paths (including dynamic imports, `__init__.py` re-exports)
+2. Cannot be done with simple AST parsing — needs full module resolution
+3. Is potentially slow for large projects
+
+## How to check manually
+
+1. Use your IDE's "Find Usages" feature on a slice's `__init__.py`
+2. If a slice has 0 imports from other modules — it's dead code, remove it
+3. If a slice has exactly 1 import — consider merging it into the importing layer
+
+## Steiger Equivalent
+
+- Slices with **no references** → remove or archive
+- Slices with **one reference** → merge into the importing module
+- **Exception**: pages are allowed to have just 1 reference (from app/routing)
+- **Exception**: slices only used in `app` layer don't count (app shouldn't have UI)