archunitpython 1.0.0__py3-none-any.whl

archunitpython/metrics/calculation/distance.py

@@ -0,0 +1,110 @@
+"""Robert C. Martin's distance metrics: Abstractness, Instability, Distance."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.metrics.common.types import FileAnalysisResult
+
+
+@dataclass
+class DistanceMetrics:
+    """Distance metrics for a file/module."""
+
+    abstractness: float  # A = Na / N
+    instability: float  # I = Ce / (Ca + Ce)
+    distance: float  # D = |A + I - 1|
+    coupling_factor: float  # CF
+    normalized_distance: float
+    in_zone_of_pain: bool
+    in_zone_of_uselessness: bool
+
+
+@dataclass
+class ProjectDistanceMetrics:
+    """Project-wide distance metric summary."""
+
+    average_abstractness: float
+    average_instability: float
+    average_distance: float
+    files_in_zone_of_pain: int
+    files_in_zone_of_uselessness: int
+    total_files: int
+
+
+def calculate_file_distance_metrics(
+    file_analysis: FileAnalysisResult,
+    all_files: list[FileAnalysisResult],
+) -> DistanceMetrics:
+    """Calculate distance metrics for a single file.
+
+    Args:
+        file_analysis: Analysis result for the target file.
+        all_files: All file analysis results (for coupling calculation).
+    """
+    # Abstractness: ratio of abstract types to total types
+    total_types = file_analysis.total_types
+    abstract_types = file_analysis.abstract_classes + file_analysis.protocols
+
+    abstractness = abstract_types / total_types if total_types > 0 else 0.0
+
+    # Coupling: count files that depend on this file (Ca) and
+    # files this file depends on (Ce)
+    # For simplicity, use class count as proxy for coupling
+    ce = sum(c.efferent_coupling for c in file_analysis.classes)
+    ca = sum(c.afferent_coupling for c in file_analysis.classes)
+    total_coupling = ca + ce
+
+    instability = ce / total_coupling if total_coupling > 0 else 0.5
+
+    # Distance from main sequence
+    distance = abs(abstractness + instability - 1)
+
+    # Coupling factor
+    max_coupling = max(1, len(all_files) - 1) * 2
+    coupling_factor = total_coupling / max_coupling if max_coupling > 0 else 0.0
+
+    # Normalized distance
+    normalized_distance = distance
+
+    # Zone detection
+    in_zone_of_pain = abstractness < 0.25 and instability < 0.25
+    in_zone_of_uselessness = abstractness > 0.75 and instability > 0.75
+
+    return DistanceMetrics(
+        abstractness=abstractness,
+        instability=instability,
+        distance=distance,
+        coupling_factor=coupling_factor,
+        normalized_distance=normalized_distance,
+        in_zone_of_pain=in_zone_of_pain,
+        in_zone_of_uselessness=in_zone_of_uselessness,
+    )
+
+
+def calculate_distance_metrics_for_project(
+    files: list[FileAnalysisResult],
+) -> ProjectDistanceMetrics:
+    """Calculate project-wide distance metric summary."""
+    if not files:
+        return ProjectDistanceMetrics(
+            average_abstractness=0,
+            average_instability=0,
+            average_distance=0,
+            files_in_zone_of_pain=0,
+            files_in_zone_of_uselessness=0,
+            total_files=0,
+        )
+
+    metrics = [calculate_file_distance_metrics(f, files) for f in files]
+
+    return ProjectDistanceMetrics(
+        average_abstractness=sum(m.abstractness for m in metrics) / len(metrics),
+        average_instability=sum(m.instability for m in metrics) / len(metrics),
+        average_distance=sum(m.distance for m in metrics) / len(metrics),
+        files_in_zone_of_pain=sum(1 for m in metrics if m.in_zone_of_pain),
+        files_in_zone_of_uselessness=sum(
+            1 for m in metrics if m.in_zone_of_uselessness
+        ),
+        total_files=len(files),
+    )

archunitpython/metrics/calculation/lcom.py

@@ -0,0 +1,177 @@
+"""LCOM (Lack of Cohesion of Methods) metrics - 8 variants."""
+
+from __future__ import annotations
+
+from archunitpython.metrics.common.types import ClassInfo
+
+
+class LCOM96a:
+    """LCOM96a: (1/(1-m)) * ((1/a) * sum(mu(Ai)) - m)."""
+
+    name = "LCOM96a"
+    description = "Lack of Cohesion of Methods (96a variant)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        a = len(class_info.fields)
+        if m <= 1 or a == 0:
+            return 0.0
+
+        total_mu = sum(len(f.accessed_by) for f in class_info.fields)
+        return (1 / (1 - m)) * ((1 / a) * total_mu - m)
+
+
+class LCOM96b:
+    """LCOM96b: (1/a) * sum((1/m) * (m - mu(Ai))). Normalized to [0,1]."""
+
+    name = "LCOM96b"
+    description = "Lack of Cohesion of Methods (96b variant, 0-1 normalized)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        a = len(class_info.fields)
+        if m == 0 or a == 0:
+            return 0.0
+
+        total = 0.0
+        for field in class_info.fields:
+            mu_a = len(field.accessed_by)
+            total += (1 / m) * (m - mu_a)
+
+        return total / a
+
+
+class LCOM1:
+    """LCOM1: |P| - |Q| where P = non-sharing pairs, Q = sharing pairs."""
+
+    name = "LCOM1"
+    description = "Lack of Cohesion of Methods (LCOM1)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        methods = class_info.methods
+        m = len(methods)
+        if m <= 1:
+            return 0.0
+
+        p = 0  # Non-sharing pairs
+        q = 0  # Sharing pairs
+
+        for i in range(m):
+            for j in range(i + 1, m):
+                fields_i = set(methods[i].accessed_fields)
+                fields_j = set(methods[j].accessed_fields)
+                if fields_i & fields_j:
+                    q += 1
+                else:
+                    p += 1
+
+        return float(max(0, p - q))
+
+
+class LCOM2:
+    """LCOM2: 1 - (sum(MF) / (M * F)) where MF = methods accessing field f."""
+
+    name = "LCOM2"
+    description = "Lack of Cohesion of Methods (LCOM2)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        f = len(class_info.fields)
+        if m == 0 or f == 0:
+            return 0.0
+
+        total_mf = sum(len(field.accessed_by) for field in class_info.fields)
+        return 1 - (total_mf / (m * f))
+
+
+class LCOM3:
+    """LCOM3: (M - sum(MF)/F) / (M - 1)."""
+
+    name = "LCOM3"
+    description = "Lack of Cohesion of Methods (LCOM3)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        f = len(class_info.fields)
+        if m <= 1 or f == 0:
+            return 0.0
+
+        total_mf = sum(len(field.accessed_by) for field in class_info.fields)
+        return (m - total_mf / f) / (m - 1)
+
+
+class LCOM4:
+    """LCOM4: Number of connected components in method-field access graph."""
+
+    name = "LCOM4"
+    description = "Lack of Cohesion of Methods (LCOM4, connected components)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        methods = class_info.methods
+        if not methods:
+            return 0.0
+
+        # Build adjacency: two methods are connected if they share a field
+        n = len(methods)
+        parent = list(range(n))
+
+        def find(x: int) -> int:
+            while parent[x] != x:
+                parent[x] = parent[parent[x]]
+                x = parent[x]
+            return x
+
+        def union(x: int, y: int) -> None:
+            px, py = find(x), find(y)
+            if px != py:
+                parent[px] = py
+
+        for i in range(n):
+            for j in range(i + 1, n):
+                fields_i = set(methods[i].accessed_fields)
+                fields_j = set(methods[j].accessed_fields)
+                if fields_i & fields_j:
+                    union(i, j)
+
+        components = len(set(find(i) for i in range(n)))
+        return float(components)
+
+
+class LCOM5:
+    """LCOM5: (a - mu * sum(mA)) / (a - mu) adjusted by method count."""
+
+    name = "LCOM5"
+    description = "Lack of Cohesion of Methods (LCOM5)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        a = len(class_info.fields)
+        if m <= 1 or a == 0:
+            return 0.0
+
+        total_mf = sum(len(field.accessed_by) for field in class_info.fields)
+        avg_mf = total_mf / a if a > 0 else 0
+
+        denominator = m - 1
+        if denominator == 0:
+            return 0.0
+
+        return (m - avg_mf) / denominator
+
+
+class LCOMStar:
+    """LCOM* (Henderson-Sellers variant): based on method pair sharing ratio."""
+
+    name = "LCOMStar"
+    description = "Lack of Cohesion of Methods (Henderson-Sellers variant)"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        m = len(class_info.methods)
+        a = len(class_info.fields)
+        if m <= 1 or a == 0:
+            return 0.0
+
+        total_mu = sum(len(f.accessed_by) for f in class_info.fields)
+        avg_mu = total_mu / a
+
+        return (m - avg_mu) / (m - 1)

archunitpython/metrics/common/__init__.py

@@ -0,0 +1,19 @@
+from archunitpython.metrics.common.types import (
+    ClassInfo,
+    EnhancedClassInfo,
+    FieldInfo,
+    FileAnalysisResult,
+    MethodInfo,
+    Metric,
+    MetricComparison,
+)
+
+__all__ = [
+    "ClassInfo",
+    "EnhancedClassInfo",
+    "FieldInfo",
+    "FileAnalysisResult",
+    "Metric",
+    "MetricComparison",
+    "MethodInfo",
+]

archunitpython/metrics/common/types.py

@@ -0,0 +1,67 @@
+"""Common types for the metrics module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Protocol
+
+
+@dataclass
+class MethodInfo:
+    """Information about a class method."""
+
+    name: str
+    accessed_fields: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FieldInfo:
+    """Information about a class field."""
+
+    name: str
+    accessed_by: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ClassInfo:
+    """Information about a class extracted from source code."""
+
+    name: str
+    file_path: str
+    methods: list[MethodInfo] = field(default_factory=list)
+    fields: list[FieldInfo] = field(default_factory=list)
+
+
+@dataclass
+class EnhancedClassInfo(ClassInfo):
+    """Extended class info with abstractness and dependency data."""
+
+    is_abstract: bool = False
+    is_protocol: bool = False
+    abstract_methods: list[str] = field(default_factory=list)
+    efferent_coupling: int = 0  # Ce: outgoing dependencies
+    afferent_coupling: int = 0  # Ca: incoming dependencies
+
+
+@dataclass
+class FileAnalysisResult:
+    """Analysis result for a single Python file."""
+
+    file_path: str
+    classes: list[EnhancedClassInfo] = field(default_factory=list)
+    protocols: int = 0
+    abstract_classes: int = 0
+    concrete_classes: int = 0
+    total_types: int = 0
+
+
+MetricComparison = Literal["below", "above", "equal", "above_equal", "below_equal"]
+
+
+class Metric(Protocol):
+    """Protocol for class-level metrics."""
+
+    name: str
+    description: str
+
+    def calculate(self, class_info: ClassInfo) -> float: ...

archunitpython/metrics/extraction/extract_class_info.py

@@ -0,0 +1,246 @@
+"""Extract class information from Python source files using AST."""
+
+from __future__ import annotations
+
+import ast
+import os
+
+from archunitpython.common.extraction.extract_graph import _DEFAULT_EXCLUDE, _find_python_files
+from archunitpython.metrics.common.types import (
+    ClassInfo,
+    EnhancedClassInfo,
+    FieldInfo,
+    FileAnalysisResult,
+    MethodInfo,
+)
+
+
+def extract_class_info(
+    project_path: str | None = None,
+    *,
+    exclude_patterns: list[str] | None = None,
+) -> list[ClassInfo]:
+    """Extract class metadata from all Python files in a project.
+
+    Args:
+        project_path: Root directory to scan.
+        exclude_patterns: Directory/file names to exclude.
+
+    Returns:
+        List of ClassInfo for every class found.
+    """
+    if project_path is None:
+        project_path = os.getcwd()
+
+    project_path = os.path.abspath(project_path)
+    excludes = exclude_patterns if exclude_patterns is not None else _DEFAULT_EXCLUDE
+    py_files = _find_python_files(project_path, excludes)
+
+    classes: list[ClassInfo] = []
+    for file_path in py_files:
+        classes.extend(_process_source_file(file_path))
+
+    return classes
+
+
+def extract_enhanced_class_info(
+    project_path: str | None = None,
+    *,
+    exclude_patterns: list[str] | None = None,
+) -> list[FileAnalysisResult]:
+    """Enhanced extraction with abstractness and dependency information."""
+    if project_path is None:
+        project_path = os.getcwd()
+
+    project_path = os.path.abspath(project_path)
+    excludes = exclude_patterns if exclude_patterns is not None else _DEFAULT_EXCLUDE
+    py_files = _find_python_files(project_path, excludes)
+
+    results: list[FileAnalysisResult] = []
+    for file_path in py_files:
+        result = _process_source_file_enhanced(file_path)
+        if result.classes:
+            results.append(result)
+
+    return results
+
+
+def _process_source_file(file_path: str) -> list[ClassInfo]:
+    """Extract ClassInfo from a single Python file."""
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            source = f.read()
+    except (OSError, IOError):
+        return []
+
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+
+    classes: list[ClassInfo] = []
+    norm_path = file_path.replace("\\", "/")
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            class_info = _extract_class(node, norm_path)
+            classes.append(class_info)
+
+    return classes
+
+
+def _process_source_file_enhanced(file_path: str) -> FileAnalysisResult:
+    """Extract enhanced class info from a single Python file."""
+    norm_path = file_path.replace("\\", "/")
+    result = FileAnalysisResult(file_path=norm_path)
+
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            source = f.read()
+    except (OSError, IOError):
+        return result
+
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return result
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            enhanced = _extract_enhanced_class(node, norm_path)
+            result.classes.append(enhanced)
+            result.total_types += 1
+            if enhanced.is_protocol:
+                result.protocols += 1
+            elif enhanced.is_abstract:
+                result.abstract_classes += 1
+            else:
+                result.concrete_classes += 1
+
+    return result
+
+
+def _extract_class(node: ast.ClassDef, file_path: str) -> ClassInfo:
+    """Extract ClassInfo from a ClassDef AST node."""
+    methods: list[MethodInfo] = []
+    fields: dict[str, FieldInfo] = {}
+
+    # Find fields from __init__ and class body
+    for item in ast.walk(node):
+        if isinstance(item, ast.Assign):
+            for target in item.targets:
+                if isinstance(target, ast.Attribute) and isinstance(
+                    target.value, ast.Name
+                ):
+                    if target.value.id == "self":
+                        field_name = target.attr
+                        if field_name not in fields:
+                            fields[field_name] = FieldInfo(name=field_name)
+
+    # Extract methods and track field accesses
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            method_name = item.name
+            accessed = _find_field_accesses(item, set(fields.keys()))
+            methods.append(
+                MethodInfo(name=method_name, accessed_fields=accessed)
+            )
+            # Update field access tracking
+            for field_name in accessed:
+                if field_name in fields:
+                    if method_name not in fields[field_name].accessed_by:
+                        fields[field_name].accessed_by.append(method_name)
+
+    return ClassInfo(
+        name=node.name,
+        file_path=file_path,
+        methods=methods,
+        fields=list(fields.values()),
+    )
+
+
+def _extract_enhanced_class(
+    node: ast.ClassDef, file_path: str
+) -> EnhancedClassInfo:
+    """Extract EnhancedClassInfo from a ClassDef AST node."""
+    base = _extract_class(node, file_path)
+
+    is_abstract = _is_abstract_class(node)
+    is_protocol = _is_protocol_class(node)
+    abstract_methods = _find_abstract_methods(node)
+
+    return EnhancedClassInfo(
+        name=base.name,
+        file_path=base.file_path,
+        methods=base.methods,
+        fields=base.fields,
+        is_abstract=is_abstract,
+        is_protocol=is_protocol,
+        abstract_methods=abstract_methods,
+    )
+
+
+def _find_field_accesses(
+    func_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    known_fields: set[str],
+) -> list[str]:
+    """Find all self.field accesses within a method."""
+    accessed: list[str] = []
+    for node in ast.walk(func_node):
+        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
+            if node.value.id == "self" and node.attr in known_fields:
+                if node.attr not in accessed:
+                    accessed.append(node.attr)
+    return accessed
+
+
+def _is_abstract_class(node: ast.ClassDef) -> bool:
+    """Check if a class inherits from ABC or ABCMeta."""
+    for base in node.bases:
+        name = _get_name(base)
+        if name in ("ABC", "ABCMeta"):
+            return True
+    for keyword in node.keywords:
+        if keyword.arg == "metaclass":
+            name = _get_name(keyword.value)
+            if name == "ABCMeta":
+                return True
+    # Also check for @abstractmethod decorators
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in item.decorator_list:
+                name = _get_name(decorator)
+                if name == "abstractmethod":
+                    return True
+    return False
+
+
+def _is_protocol_class(node: ast.ClassDef) -> bool:
+    """Check if a class inherits from Protocol."""
+    for base in node.bases:
+        name = _get_name(base)
+        if name == "Protocol":
+            return True
+    return False
+
+
+def _find_abstract_methods(node: ast.ClassDef) -> list[str]:
+    """Find all methods with @abstractmethod decorator."""
+    abstract: list[str] = []
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in item.decorator_list:
+                name = _get_name(decorator)
+                if name == "abstractmethod":
+                    abstract.append(item.name)
+                    break
+    return abstract
+
+
+def _get_name(node: ast.expr) -> str:
+    """Extract a name from an AST node (handles Name and Attribute)."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""

archunitpython/metrics/fluentapi/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.metrics.fluentapi.metrics import metrics
+
+__all__ = ["metrics"]