archetype-py 0.1.0__py3-none-any.whl

archetype/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype public package exports."""
+
+from archetype.init import *  # noqa: F401,F403

archetype/analysis/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype analysis subpackage."""
+
+from archetype.analysis.init import *  # noqa: F401,F403

archetype/analysis/ast_utils.py

@@ -0,0 +1,19 @@
+"""AST traversal helpers used by Archetype static analysis."""
+
+from __future__ import annotations
+
+import ast
+
+
+def get_class_names(tree: ast.AST) -> list[str]:
+    """Return all class names defined anywhere in the AST."""
+    return [node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)]
+
+
+def get_top_level_function_names(tree: ast.AST) -> list[str]:
+    """Return names of module-level functions only (excluding class methods)."""
+    return [
+        node.name
+        for node in getattr(tree, "body", [])
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ]

archetype/analysis/imports.py

@@ -0,0 +1,97 @@
+"""Import parsing and dependency graph construction from Python source files."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import networkx as nx
+
+
+def path_to_module(file_path: Path, project_root: Path) -> str:
+    """Convert a Python file path to its fully-qualified module path."""
+    relative = file_path.relative_to(project_root).with_suffix("")
+    parts = list(relative.parts)
+
+    if parts and parts[-1] in {"__init__", "init"}:
+        parts = parts[:-1]
+
+    return ".".join(parts)
+
+
+def resolve_relative_import(
+    current_module: str, imported_module: str | None, level: int
+) -> str:
+    """Resolve a relative import into an absolute module path."""
+    if level <= 0:
+        return imported_module or current_module
+
+    current_parts = [part for part in current_module.split(".") if part]
+    drop_count = min(level, len(current_parts))
+    base_parts = current_parts[:-drop_count]
+
+    if imported_module:
+        return ".".join(base_parts + imported_module.split("."))
+    return ".".join(base_parts)
+
+
+def build_import_graph(project_root: Path) -> nx.DiGraph:
+    """Build a directed import graph for local Python modules under project_root."""
+    graph = nx.DiGraph()
+    root = project_root.resolve()
+
+    def is_local_module(module_name: str) -> bool:
+        top_level = module_name.split(".", maxsplit=1)[0]
+        return (root / top_level).is_dir()
+
+    def add_import_edge(current_module: str, imported_module: str) -> None:
+        if imported_module and is_local_module(imported_module):
+            graph.add_node(imported_module)
+            graph.add_edge(current_module, imported_module)
+
+    for file_path in sorted(root.rglob("*.py")):
+        current_module = path_to_module(file_path, root)
+        if not current_module:
+            continue
+
+        graph.add_node(current_module)
+
+        source = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(file_path))
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    add_import_edge(current_module, alias.name)
+
+            if isinstance(node, ast.ImportFrom):
+                if node.level and node.level > 0:
+                    resolution_context = current_module
+                    if file_path.stem in {"__init__", "init"}:
+                        resolution_context = f"{current_module}.__init__"
+                    base_module = resolve_relative_import(
+                        resolution_context,
+                        node.module,
+                        node.level,
+                    )
+                else:
+                    base_module = node.module or ""
+
+                # Resolve imported names as potential submodules first.
+                # Example: `from simple_project import db` -> `simple_project.db`
+                # Example: `from . import utils` -> `<current_pkg>.utils`
+                resolved_submodule = False
+                for alias in node.names:
+                    if alias.name == "*":
+                        continue
+                    candidate = f"{base_module}.{alias.name}" if base_module else alias.name
+                    if candidate and is_local_module(candidate):
+                        resolved_submodule = True
+                        add_import_edge(current_module, candidate)
+
+                # Fall back to base module dependency when no concrete local
+                # submodule candidates were found (or for star imports).
+                if not resolved_submodule or any(alias.name == "*" for alias in node.names):
+                    add_import_edge(current_module, base_module)
+
+    return graph

archetype/analysis/init.py

@@ -0,0 +1 @@
+"""Static analysis utilities for building and inspecting module dependency graphs."""

archetype/analysis/models.py

@@ -0,0 +1,26 @@
+"""Data models representing modules, imports, and analysis results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Violation:
+    """Represents a single architectural rule violation."""
+
+    module: str
+    file: Path
+    line: int
+    message: str
+
+
+@dataclass
+class RuleResult:
+    """Represents the execution outcome for a single architecture rule."""
+
+    name: str
+    passed: bool
+    violations: list[Violation] = field(default_factory=list)
+    error: Exception | None = None

archetype/check.py

@@ -0,0 +1,70 @@
+"""Command-line entry points and orchestration for running architecture checks."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import uuid
+from pathlib import Path
+
+import click
+
+from archetype.dsl.query import load_project
+from archetype.reporter import print_results
+from archetype.rule import registry
+
+
+@click.group()
+def cli() -> None:
+    """Archetype CLI."""
+
+
+@cli.command("check")
+@click.argument(
+    "path",
+    required=False,
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+def check(path: Path) -> None:
+    """Run architecture rules against a Python project."""
+    project_path = path.resolve()
+    architecture_file = project_path / "architecture.py"
+
+    if not architecture_file.is_file():
+        click.echo(
+            f"Error: architecture.py not found. Looked for: {architecture_file}",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    registry.clear()
+    load_project(project_path)
+
+    module_name = f"_archetype_user_architecture_{uuid.uuid4().hex}"
+    spec = importlib.util.spec_from_file_location(module_name, architecture_file)
+    if spec is None or spec.loader is None:
+        click.echo(
+            f"Error: could not load architecture module from: {architecture_file}",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    original_sys_path = list(sys.path)
+    try:
+        sys.path.insert(0, str(project_path))
+        spec.loader.exec_module(module)
+    except Exception as exc:  # noqa: BLE001
+        click.echo(
+            f"Error: failed to import architecture.py from {architecture_file}: {exc}",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+    finally:
+        sys.path = original_sys_path
+
+    results = registry.run_all()
+    passed = sum(1 for result in results if result.passed)
+    print_results(results)
+    raise SystemExit(0 if passed == len(results) else 1)

archetype/dsl/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype DSL subpackage."""
+
+from archetype.dsl.init import *  # noqa: F401,F403

archetype/dsl/init.py

@@ -0,0 +1 @@
+"""Domain-specific language components for expressing architecture rules."""

archetype/dsl/query.py

@@ -0,0 +1,114 @@
+"""Query API for selecting modules and asserting dependency constraints."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import networkx as nx
+
+from archetype.analysis.imports import build_import_graph
+from archetype.analysis.models import Violation
+
+_current_graph: nx.DiGraph | None = None
+_current_root: Path | None = None
+
+
+def _matches_pattern(module_name: str, pattern: str) -> bool:
+    return module_name == pattern or module_name.startswith(f"{pattern}.")
+
+
+def load_project(project_root: Path) -> None:
+    """Load a project's import graph into DSL runtime state."""
+    global _current_graph, _current_root
+    resolved_root = project_root.resolve()
+    _current_graph = build_import_graph(resolved_root)
+    _current_root = resolved_root
+
+
+class ImportQuery:
+    """Query object for evaluating import constraints on matched modules."""
+
+    def __init__(self, pattern: str) -> None:
+        self.pattern = pattern
+        if _current_graph is None:
+            raise RuntimeError(
+                "No project graph is loaded. Call load_project(path) before using imports()."
+            )
+        self.graph = _current_graph
+        self.matched_nodes = [
+            node for node in self.graph.nodes if _matches_pattern(node, pattern)
+        ]
+
+    def must_not_import(self, target_pattern: str) -> None:
+        """Assert that matched source modules do not import modules matching target."""
+        violations: list[Violation] = []
+
+        for source in self.matched_nodes:
+            for target in self.graph.successors(source):
+                if _matches_pattern(target, target_pattern):
+                    violations.append(
+                        Violation(
+                            module=source,
+                            file=Path("<unknown>"),
+                            line=0,
+                            message=(
+                                f"Module '{source}' must not import '{target_pattern}' "
+                                f"(found import to '{target}')."
+                            ),
+                        )
+                    )
+
+        if violations:
+            exc = AssertionError(
+                f"Forbidden imports found: {len(violations)} edge(s) from "
+                f"'{self.pattern}' to '{target_pattern}'."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+    def has_no_cycles(self) -> None:
+        """Assert that the matched module set has no directed import cycles."""
+        subgraph = self.graph.subgraph(self.matched_nodes)
+        try:
+            cycle_edges = nx.find_cycle(subgraph, orientation="original")
+        except nx.NetworkXNoCycle:
+            return
+
+        cycle_nodes = [edge[0] for edge in cycle_edges]
+        cycle_nodes.append(cycle_edges[0][0])
+        chain = " -> ".join(cycle_nodes)
+        raise AssertionError(f"Import cycle detected: {chain}")
+
+    def must_only_import_from(self, *allowed_patterns: str) -> None:
+        """Assert that matched source modules import only from allowed targets."""
+        violations: list[Violation] = []
+
+        for source in self.matched_nodes:
+            for target in self.graph.successors(source):
+                if not any(
+                    _matches_pattern(target, allowed_pattern)
+                    for allowed_pattern in allowed_patterns
+                ):
+                    violations.append(
+                        Violation(
+                            module=source,
+                            file=Path("<unknown>"),
+                            line=0,
+                            message=(
+                                f"Module '{source}' imports '{target}', which is outside "
+                                f"the allowed set: {allowed_patterns}."
+                            ),
+                        )
+                    )
+
+        if violations:
+            exc = AssertionError(
+                f"Disallowed imports found for '{self.pattern}': {len(violations)} edge(s)."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+
+def imports(pattern: str) -> ImportQuery:
+    """Create an import query rooted at the provided module/package pattern."""
+    return ImportQuery(pattern)

archetype/init.py

@@ -0,0 +1,8 @@
+"""Top-level package metadata and public exports for Archetype."""
+
+from archetype.dsl.query import imports, load_project
+from archetype.rule import registry, rule
+
+module = None
+
+__all__ = ["rule", "registry", "imports", "load_project", "module"]

archetype/plugin/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype plugin subpackage."""
+
+from archetype.plugin.init import *  # noqa: F401,F403

archetype/plugin/init.py

@@ -0,0 +1 @@
+"""Pytest plugin package for integrating Archetype rules into test runs."""

archetype/plugin/pytest_plugin.py

@@ -0,0 +1,75 @@
+"""Pytest plugin hooks for auto-discovering and executing architecture rules."""
+
+from __future__ import annotations
+
+import importlib.util
+import uuid
+from pathlib import Path
+
+import pytest
+
+from archetype.dsl.query import load_project
+from archetype.reporter import format_violation
+from archetype.rule import registry
+
+
+def pytest_collect_file(file_path: Path, parent: pytest.Collector):  # type: ignore[override]
+    """Collect only architecture.py files as Archetype rule containers."""
+    if file_path.name == "architecture.py":
+        return ArchetypeFile.from_parent(parent, path=file_path)
+    return None
+
+
+class ArchetypeFile(pytest.File):
+    """Custom collector for architecture.py files."""
+
+    def collect(self):
+        registry.clear()
+        project_root = self.path.parent
+        load_project(project_root)
+
+        module_name = f"_archetype_pytest_architecture_{uuid.uuid4().hex}"
+        spec = importlib.util.spec_from_file_location(module_name, self.path)
+        if spec is None or spec.loader is None:
+            raise RuntimeError(f"Could not load architecture module at {self.path}")
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        for rule_func in registry._rules:
+            rule_name = getattr(rule_func, "_rule_name", rule_func.__name__)
+            yield ArchetypeItem.from_parent(
+                self, name=rule_name, rule_func=rule_func, file_path=self.path
+            )
+
+
+class ArchetypeItem(pytest.Item):
+    """Custom pytest test item wrapping a single architecture rule callable."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        parent: pytest.Collector,
+        rule_func,
+        file_path: Path,
+    ) -> None:
+        super().__init__(name=name, parent=parent)
+        self.rule_func = rule_func
+        self.file_path = file_path
+
+    def runtest(self) -> None:
+        self.rule_func()
+
+    def repr_failure(self, excinfo, style=None):  # type: ignore[override]
+        err = excinfo.value
+        if isinstance(err, AssertionError):
+            violations = getattr(err, "violations", None)
+            if violations:
+                lines = [f"Rule '{self.name}' violations:"]
+                lines.extend(f"  - {format_violation(violation)}" for violation in violations)
+                return "\n".join(lines)
+        return super().repr_failure(excinfo, style=style)
+
+    def reportinfo(self):
+        return self.file_path, None, self.name

archetype/reporter.py

@@ -0,0 +1,65 @@
+"""Shared formatting and output utilities for Archetype rule results."""
+
+from __future__ import annotations
+
+import re
+
+from rich.console import Console
+
+from archetype.analysis.models import RuleResult, Violation
+
+
+def _extract_target(violation: Violation) -> str:
+    quoted = re.findall(r"'([^']+)'", violation.message)
+    if quoted:
+        return quoted[-1]
+    return "<unknown>"
+
+
+def format_violation(violation: Violation) -> str:
+    """Format a violation into a concise, actionable message."""
+    target = _extract_target(violation)
+    return f"{violation.module} -> {target}: {violation.message}"
+
+
+def format_results(results: list[RuleResult]) -> str:
+    """Build a complete plain-text report for rule execution results."""
+    lines: list[str] = []
+    passed = sum(1 for result in results if result.passed)
+    failed = len(results) - passed
+
+    for result in results:
+        symbol = "✓" if result.passed else "✗"
+        lines.append(f"{symbol} {result.name}")
+        if not result.passed:
+            for violation in result.violations:
+                lines.append(f"  - {format_violation(violation)}")
+            if result.error is not None:
+                lines.append(f"  - Rule error: {result.error}")
+
+    lines.append(
+        f"Summary: {passed} passed, {failed} failed, {len(results)} total rules."
+    )
+    return "\n".join(lines)
+
+
+def print_results(results: list[RuleResult]) -> None:
+    """Print rule results using rich colors for pass/fail states."""
+    console = Console()
+    passed = sum(1 for result in results if result.passed)
+    failed = len(results) - passed
+
+    for result in results:
+        if result.passed:
+            console.print(f"[green]✓ {result.name}[/green]")
+            continue
+
+        console.print(f"[red]✗ {result.name}[/red]")
+        for violation in result.violations:
+            console.print(f"[red]  - {format_violation(violation)}[/red]")
+        if result.error is not None:
+            console.print(f"[red]  - Rule error: {result.error}[/red]")
+
+    summary = f"Summary: {passed} passed, {failed} failed, {len(results)} total rules."
+    summary_color = "green" if failed == 0 else "red"
+    console.print(f"[{summary_color}]{summary}[/{summary_color}]")

archetype/rule.py

@@ -0,0 +1,61 @@
+"""Rule decorator and rule registration primitives for architecture checks."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Callable
+
+from archetype.analysis.models import RuleResult
+
+
+RuleFn = Callable[[], None]
+
+
+class RuleRegistry:
+    """In-memory registry for architecture rule callables."""
+
+    def __init__(self) -> None:
+        self._rules: list[RuleFn] = []
+
+    def register(self, func: RuleFn) -> None:
+        """Register a rule function."""
+        self._rules.append(func)
+
+    def clear(self) -> None:
+        """Remove all registered rule functions."""
+        self._rules.clear()
+
+    def run_all(self) -> list[RuleResult]:
+        """Execute all registered rules and collect results."""
+        results: list[RuleResult] = []
+        for func in self._rules:
+            rule_name = getattr(func, "_rule_name", func.__name__)
+            try:
+                func()
+                results.append(RuleResult(name=rule_name, passed=True))
+            except AssertionError as exc:
+                violations = getattr(exc, "violations", [])
+                results.append(
+                    RuleResult(name=rule_name, passed=False, violations=violations)
+                )
+            except Exception as exc:  # noqa: BLE001
+                results.append(RuleResult(name=rule_name, passed=False, error=exc))
+        return results
+
+
+registry = RuleRegistry()
+
+
+def rule(name: str) -> Callable[[RuleFn], RuleFn]:
+    """Decorator for registering architecture rules with a display name."""
+
+    def decorator(func: RuleFn) -> RuleFn:
+        @wraps(func)
+        def wrapped() -> None:
+            return func()
+
+        setattr(wrapped, "_rule_name", name)
+        registry.register(wrapped)
+        return wrapped
+
+    return decorator

archetype/rules/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in architecture rules shipped with Archetype."""
+
+from archetype.rules.layers import layers
+from archetype.rules.boundaries import module
+from archetype.rules.naming import classes_in, functions_in
+from archetype.rules.cycles import no_cycles
+
+__all__ = ["layers", "module", "classes_in", "functions_in", "no_cycles"]

archetype/rules/boundaries.py

@@ -0,0 +1,57 @@
+"""Built-in module boundary rule for protecting internal module access."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import archetype.dsl.query as query_module
+from archetype.analysis.models import Violation
+
+
+def _matches_pattern(module_name: str, pattern: str) -> bool:
+    return module_name == pattern or module_name.startswith(f"{pattern}.")
+
+
+class ModuleBoundaryRule:
+    """Rule object for enforcing module import boundaries."""
+
+    def __init__(self, protected_pattern: str) -> None:
+        graph = query_module._current_graph
+        if graph is None:
+            raise RuntimeError(
+                "No project graph is loaded. Call load_project(path) before evaluating module() boundaries."
+            )
+        self.graph = graph
+        self.protected_pattern = protected_pattern
+
+    def only_imported_within(self, parent_pattern: str) -> None:
+        """Assert protected modules are imported only from inside parent_pattern."""
+        violations: list[Violation] = []
+
+        for source, target in self.graph.edges:
+            source_in_parent = _matches_pattern(source, parent_pattern)
+            target_is_protected = _matches_pattern(target, self.protected_pattern)
+            if not source_in_parent and target_is_protected:
+                violations.append(
+                    Violation(
+                        module=source,
+                        file=Path("<unknown>"),
+                        line=0,
+                        message=(
+                            f"Boundary violation: outside module '{source}' imports protected "
+                            f"module '{target}' (allowed only within '{parent_pattern}')."
+                        ),
+                    )
+                )
+
+        if violations:
+            exc = AssertionError(
+                f"Module boundary violated by {len(violations)} import(s) into '{self.protected_pattern}'."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+
+def module(protected_pattern: str) -> ModuleBoundaryRule:
+    """Create a module boundary rule for a protected module pattern."""
+    return ModuleBoundaryRule(protected_pattern)

archetype/rules/cycles.py

@@ -0,0 +1,69 @@
+"""Built-in rule for detecting circular imports in the project graph."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import networkx as nx
+
+import archetype.dsl.query as query_module
+from archetype.analysis.models import Violation
+
+
+def _matches_pattern(module_name: str, pattern: str) -> bool:
+    return module_name == pattern or module_name.startswith(f"{pattern}.")
+
+
+def _normalize_cycle(cycle: list[str]) -> tuple[str, ...]:
+    """Normalize a cycle by rotating to its alphabetically first module."""
+    if not cycle:
+        return ()
+    min_module = min(cycle)
+    min_index = cycle.index(min_module)
+    rotated = cycle[min_index:] + cycle[:min_index]
+    return tuple(rotated)
+
+
+def no_cycles(module_pattern: str | None = None) -> None:
+    """Assert that no import cycles exist globally or inside a module pattern."""
+    graph = query_module._current_graph
+    if graph is None:
+        raise RuntimeError(
+            "No project graph is loaded. Call load_project(path) before evaluating no_cycles()."
+        )
+
+    if module_pattern is None:
+        target_graph = graph
+    else:
+        matched_nodes = [
+            node for node in graph.nodes if _matches_pattern(node, module_pattern)
+        ]
+        target_graph = graph.subgraph(matched_nodes).copy()
+
+    raw_cycles = list(nx.simple_cycles(target_graph))
+    if not raw_cycles:
+        return
+
+    seen: set[tuple[str, ...]] = set()
+    violations: list[Violation] = []
+
+    for cycle in raw_cycles:
+        normalized = _normalize_cycle(cycle)
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+
+        chain_nodes = list(normalized) + [normalized[0]]
+        chain = " imports ".join(chain_nodes)
+        violations.append(
+            Violation(
+                module=normalized[0],
+                file=Path("<unknown>"),
+                line=0,
+                message=chain,
+            )
+        )
+
+    exc = AssertionError(f"Detected {len(violations)} circular import cycle(s).")
+    setattr(exc, "violations", violations)
+    raise exc

archetype/rules/layers.py

@@ -0,0 +1,69 @@
+"""Built-in layering rule for enforcing top-down architectural dependencies."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import archetype.dsl.query as query_module
+from archetype.analysis.models import Violation
+
+
+def _matches_pattern(module_name: str, pattern: str) -> bool:
+    return module_name == pattern or module_name.startswith(f"{pattern}.")
+
+
+class LayerOrderRule:
+    """Rule object that validates import directions across declared layers."""
+
+    def __init__(self, layer_patterns: list[str]) -> None:
+        self.layer_patterns = layer_patterns
+
+    def are_ordered(self) -> None:
+        """Assert that lower layers do not import upper layers."""
+        graph = query_module._current_graph
+        if graph is None:
+            raise RuntimeError(
+                "No project graph is loaded. Call load_project(path) before evaluating layers()."
+            )
+
+        violations: list[Violation] = []
+        for upper_index, upper_pattern in enumerate(self.layer_patterns):
+            for lower_pattern in self.layer_patterns[upper_index + 1 :]:
+                lower_nodes = [
+                    node
+                    for node in graph.nodes
+                    if _matches_pattern(node, lower_pattern)
+                ]
+                upper_nodes = {
+                    node
+                    for node in graph.nodes
+                    if _matches_pattern(node, upper_pattern)
+                }
+
+                for source in lower_nodes:
+                    for target in graph.successors(source):
+                        if target in upper_nodes:
+                            violations.append(
+                                Violation(
+                                    module=source,
+                                    file=Path("<unknown>"),
+                                    line=0,
+                                    message=(
+                                        f"Layering violation (upward dependency): lower layer "
+                                        f"'{lower_pattern}' module '{source}' imports upper layer "
+                                        f"'{upper_pattern}' module '{target}'."
+                                    ),
+                                )
+                            )
+
+        if violations:
+            exc = AssertionError(
+                f"Layer ordering violated by {len(violations)} upward import(s)."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+
+def layers(layer_patterns: list[str]) -> LayerOrderRule:
+    """Create a layer-order rule for modules listed top-to-bottom."""
+    return LayerOrderRule(layer_patterns)

archetype/rules/naming.py

@@ -0,0 +1,116 @@
+"""Built-in naming convention rules based on static AST inspection."""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+import archetype.dsl.query as query_module
+from archetype.analysis.ast_utils import (
+    get_class_names,
+    get_top_level_function_names,
+)
+from archetype.analysis.imports import path_to_module
+from archetype.analysis.models import Violation
+
+
+def _matches_pattern(module_name: str, pattern: str) -> bool:
+    return module_name == pattern or module_name.startswith(f"{pattern}.")
+
+
+def _matched_python_files(module_pattern: str) -> list[Path]:
+    root = query_module._current_root
+    if root is None:
+        raise RuntimeError(
+            "No project root is loaded. Call load_project(path) before evaluating naming rules."
+        )
+
+    matched: list[Path] = []
+    for file_path in sorted(root.rglob("*.py")):
+        module_name = path_to_module(file_path, root)
+        if module_name and _matches_pattern(module_name, module_pattern):
+            matched.append(file_path)
+    return matched
+
+
+class ClassesInQuery:
+    """Naming query for class definitions in matched modules."""
+
+    def __init__(self, module_pattern: str) -> None:
+        self.module_pattern = module_pattern
+        self.files = _matched_python_files(module_pattern)
+
+    def all_match(self, name_pattern: str) -> None:
+        """Assert all class names in matched files satisfy a regex."""
+        violations: list[Violation] = []
+        regex = re.compile(name_pattern)
+
+        for file_path in self.files:
+            tree = ast.parse(file_path.read_text(encoding="utf-8"), filename=str(file_path))
+            for class_name in get_class_names(tree):
+                if not regex.fullmatch(class_name):
+                    violations.append(
+                        Violation(
+                            module=self.module_pattern,
+                            file=file_path,
+                            line=0,
+                            message=(
+                                f"Class '{class_name}' in '{file_path}' does not match "
+                                f"required pattern '{name_pattern}'."
+                            ),
+                        )
+                    )
+
+        if violations:
+            exc = AssertionError(
+                f"Naming rule failed: {len(violations)} class name violation(s)."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+
+class FunctionsInQuery:
+    """Naming query for required module-level function presence."""
+
+    def __init__(self, module_pattern: str) -> None:
+        self.module_pattern = module_pattern
+        self.files = _matched_python_files(module_pattern)
+
+    def must_include(self, function_name: str) -> None:
+        """Assert each matched file defines the required top-level function."""
+        violations: list[Violation] = []
+
+        for file_path in self.files:
+            tree = ast.parse(file_path.read_text(encoding="utf-8"), filename=str(file_path))
+            top_level_functions = get_top_level_function_names(tree)
+            if function_name not in top_level_functions:
+                violations.append(
+                    Violation(
+                        module=self.module_pattern,
+                        file=file_path,
+                        line=0,
+                        message=(
+                            f"File '{file_path}' is missing required top-level function "
+                            f"'{function_name}'."
+                        ),
+                    )
+                )
+
+        if violations:
+            exc = AssertionError(
+                f"Naming rule failed: required function '{function_name}' missing in "
+                f"{len(violations)} file(s)."
+            )
+            setattr(exc, "violations", violations)
+            raise exc
+
+
+def classes_in(module_pattern: str) -> ClassesInQuery:
+    """Create a class-naming query for modules matching module_pattern."""
+    return ClassesInQuery(module_pattern)
+
+
+def functions_in(module_pattern: str) -> FunctionsInQuery:
+    """Create a function-presence query for modules matching module_pattern."""
+    return FunctionsInQuery(module_pattern)

archetype_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: archetype-py
+Version: 0.1.0
+Summary: Archetype statically analyzes Python projects to enforce architectural rules as code.
+Project-URL: Homepage, https://github.com/your-org/your-repo
+Project-URL: Documentation, https://github.com/your-org/your-repo
+Author-email: Mossab Arektout <mossabarektout2000@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: networkx
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![PyPI](https://img.shields.io/pypi/v/archetype) ![Python](https://img.shields.io/pypi/pyversions/archetype) ![License](https://img.shields.io/badge/license-MIT-green) ![CI](https://img.shields.io/github/actions/workflow/status/your-org/your-repo/ci.yml?branch=main)
+
+## Architectural rules should not live in people’s heads
+Architectural rules usually exist in engineers’ heads but nowhere in the codebase.
+Archetype turns those rules into executable Python checks that run in `archetype check` and `pytest`.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+
+@rule("services only import db")
+def services_only_db() -> None:
+    imports("myapp.services").must_only_import_from("myapp.db")
+```
+
+```text
+$ archetype check .
+✓ api does not import db
+✗ services only import db
+  - myapp.services.user -> myapp.cache: Module 'myapp.services.user' imports 'myapp.cache', which is outside the allowed set: ('myapp.db',).
+Summary: 1 passed, 1 failed, 2 total rules.
+```
+
+## Installation
+```bash
+pip install archetype-py
+```
+
+## Quickstart
+1. Install Archetype.
+
+```bash
+pip install archetype-py
+```
+
+2. Create `architecture.py` in your project root.
+
+```bash
+touch architecture.py
+```
+
+3. Add your first rule with the imports DSL.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+```
+
+4. Run the checker.
+
+```bash
+archetype check .
+```
+
+5. Read the output and fix violations.
+
+```text
+✓ api does not import db
+Summary: 1 passed, 0 failed, 1 total rules.
+```
+
+If your project already runs `pytest`, running `pytest` is sufficient because Archetype rules are collected and executed by the pytest plugin.
+
+## Why Archetype exists
+Style tools enforce how code looks. Type tools enforce what values can flow through code. Architectural tools enforce which parts of the system are allowed to depend on which other parts.
+
+Pylint and similar linters are strong at local code quality checks, and Mypy is strong at static type correctness. Neither is designed to express team-level dependency contracts like “API cannot import DB” or “internal modules are private outside their package boundary.”
+
+Archetype keeps rules in `architecture.py` as normal Python functions, not static YAML declarations. That makes rules executable, reviewable, testable, and easy to evolve with the codebase using the same language and tooling your team already uses.
+
+## Built-in rules reference
+### `layers`
+Enforces that lower layers do not import upper layers.
+
+```python
+from archetype import rule
+from archetype.rules import layers
+
+@rule("layers are ordered")
+def layer_order() -> None:
+    layers(["myapp.api", "myapp.services", "myapp.db"]).are_ordered()
+```
+
+### `module` (module boundaries)
+Enforces that a protected internal module is only imported from an allowed parent scope.
+
+```python
+from archetype import rule
+from archetype.rules import module
+
+@rule("internal auth is private")
+def auth_boundary() -> None:
+    module("myapp.auth.internal").only_imported_within("myapp.auth")
+```
+
+### `classes_in` and `functions_in` (naming conventions)
+Enforces class naming patterns and required top-level functions in matched modules.
+
+```python
+from archetype import rule
+from archetype.rules import classes_in, functions_in
+
+@rule("service classes end with Service")
+def class_names() -> None:
+    classes_in("myapp.services").all_match(r".*Service$")
+
+@rule("api modules expose handle")
+def api_handle_exists() -> None:
+    functions_in("myapp.api").must_include("handle")
+```
+
+### `no_cycles`
+Enforces that there are no import cycles in the whole project or in a selected module scope.
+
+```python
+from archetype import rule
+from archetype.rules import no_cycles
+
+@rule("no cycles in services")
+def services_no_cycles() -> None:
+    no_cycles("myapp.services")
+```
+
+## Writing custom rules
+```python
+from archetype import imports, rule
+
+@rule("custom architecture policy")
+def custom_policy() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+    imports("myapp.services").has_no_cycles()
+    imports("myapp.services").must_only_import_from("myapp.db", "myapp.shared")
+```
+
+Any Python function decorated with `@rule` that returns without raising is a passing rule. Rules can use the full Python language, so you can encode architecture constraints that do not fit generic linters or static config.
+
+## CI integration
+```yaml
+name: Archetype Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  archetype:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install archetype-py
+      - run: archetype check .
+```
+
+If your CI already runs `pytest`, no additional CI configuration is required.
+
+## Contributing
+Source code and issue tracking are in the GitHub repository: `https://github.com/your-org/your-repo`.
+Contributions are welcome; open an issue first to discuss scope before submitting a pull request.

archetype_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+archetype/__init__.py,sha256=hdeNvlViCB5xKoNfvr_LYy1xhRFwWbhIfwe3Ib3CLi8,89
+archetype/check.py,sha256=aqTYaYdLkQ5XJvwfxTB-ZsxyzDx7Tp3FPYVNK6vkCpc,1983
+archetype/init.py,sha256=0Wu_DzyHEcIzL_oHVshHI_OwX60TYTBBHja5t_vrq9U,248
+archetype/reporter.py,sha256=OsAiAuPWrkHm_b0cxYsnUpMHOMyc6nvntA6Mw25BS3w,2248
+archetype/rule.py,sha256=tC8FiT44LotPykcx45FnBm4cySZjsrvesFWI8MLhRnQ,1798
+archetype/analysis/__init__.py,sha256=r45MIo4x7I73HH34o4lR_mqYHXhz_RvQc1rGAoUNKBQ,95
+archetype/analysis/ast_utils.py,sha256=PAwj7NbcgV3VImY33MyPWmSuOGUppvop7yPHttzAw-8,605
+archetype/analysis/imports.py,sha256=OhzzaCFgx-ZHN4kAZx2LrvJWO_QYvV0XjyITpQxiBD4,3711
+archetype/analysis/init.py,sha256=vecxj2nNQfqgrcxup1ULS_Hk7-qbjONd0HBq19p-ld8,86
+archetype/analysis/models.py,sha256=tHQnZ5ioIkO_3ZpChnGuQfhLA03bAqDM3fe4Yd1O7Hc,562
+archetype/dsl/__init__.py,sha256=4Q5io9-AHo0BZKPCsObe__Dnjo3F2000-sZNgnwqwl8,85
+archetype/dsl/init.py,sha256=sKS0sR0cGWG-fk4DCqucwPJw_h6bGcQnWlfrQajDzbA,77
+archetype/dsl/query.py,sha256=vi6speYWSML_n8hinU3r0lM3mq2H3bOItt0sM1mgrAA,4252
+archetype/plugin/__init__.py,sha256=CYj1c8Kpg73hdNXLSziC0PvuqakbAi4VplMUeI8KNV4,91
+archetype/plugin/init.py,sha256=Dv0sc34LZCGTLfucTesFjJklNMFTGrFYrw93voj92Xg,76
+archetype/plugin/pytest_plugin.py,sha256=fKwNBZ2U9AHACMho4ax5odAiE06slQ5xzdTmwi0Ax50,2483
+archetype/rules/__init__.py,sha256=UC3mqs6cWqXt7bWGrQWqC9-6S6AByj9y5XQOolezZOk,327
+archetype/rules/boundaries.py,sha256=fxXy34bCKpkz4k_JVjFwjsLxK2t2_MU0yziO87Yo2JU,2182
+archetype/rules/cycles.py,sha256=RWvBlQtYcTZhz2it0vwr-BUtodnyLKAkc3anyMDJ6EI,2074
+archetype/rules/layers.py,sha256=fktxE3VWyrP8ZrJIKchV7K8ATNCP3-oerwVnQmtF3nE,2669
+archetype/rules/naming.py,sha256=dqusL4mUN58we8c4vGJ4Qp6DdXepO7h6fNTunVEG1KY,4218
+archetype_py-0.1.0.dist-info/METADATA,sha256=JmlJKAbtRNRXuyiY5UnFtr51ePADvr_a_eX5NBFP_p8,6109
+archetype_py-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+archetype_py-0.1.0.dist-info/entry_points.txt,sha256=HQNYKeWAHr8jm8GOJSMx5vyEJCKsSqZ8CT-c7VShHp4,105
+archetype_py-0.1.0.dist-info/licenses/LICENSE,sha256=OG7RJA70iDz95BX5vw32rRMwm3ms3Jy3V6wxoC2zAbM,1072
+archetype_py-0.1.0.dist-info/RECORD,,

archetype_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

archetype_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+archetype = archetype.check:cli
+
+[pytest11]
+archetype = archetype.plugin.pytest_plugin

archetype_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [YEAR] [AUTHOR NAME]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.