dotscope 0.1.0__py3-none-any.whl

dotscope/passes/convention_parser.py

@@ -0,0 +1,223 @@
+"""Convention parser pass: map files to conventions and check rules."""
+
+import os
+import re
+from typing import Dict, List, Optional
+
+from ..models import ConventionNode, ConventionRule, FileAnalysis
+
+
+def parse_conventions(
+    ast_data: Dict[str, FileAnalysis],
+    conventions: List[ConventionRule],
+) -> List[ConventionNode]:
+    """Apply convention rules against AST data.
+
+    For each file, check if it matches any convention's criteria.
+    If matched, check rules and produce a ConventionNode.
+    """
+    nodes = []
+    for file_path, analysis in ast_data.items():
+        for rule in conventions:
+            if matches_convention(analysis, file_path, rule.match_criteria):
+                violations = check_convention_rules(analysis, file_path, rule.rules)
+                matched_by = _identify_matching_criteria(
+                    analysis, file_path, rule.match_criteria
+                )
+                nodes.append(ConventionNode(
+                    name=rule.name,
+                    file_path=file_path,
+                    target_name=(
+                        analysis.classes[0].name if analysis.classes
+                        else os.path.basename(file_path)
+                    ),
+                    violations=violations,
+                    matched_by=matched_by,
+                ))
+    return nodes
+
+
+def matches_convention(
+    analysis: FileAnalysis,
+    file_path: str,
+    match_criteria: dict,
+) -> bool:
+    """Flexible matching with any_of / all_of logic.
+
+    A file matches when:
+    - At least one criterion in any_of matches (OR)
+    - All criteria in all_of match (AND)
+    - If only one block is present, it determines the match alone
+    """
+    any_of = match_criteria.get("any_of", [])
+    all_of = match_criteria.get("all_of", [])
+
+    # Legacy flat format (no any_of/all_of) treated as all_of
+    if not any_of and not all_of:
+        all_of = [match_criteria] if match_criteria else []
+
+    any_passed = not any_of  # Vacuously true if empty
+    for criterion in any_of:
+        if _matches_single(analysis, file_path, criterion):
+            any_passed = True
+            break
+
+    all_passed = True
+    for criterion in all_of:
+        if not _matches_single(analysis, file_path, criterion):
+            all_passed = False
+            break
+
+    return any_passed and all_passed
+
+
+def _matches_single(
+    analysis: FileAnalysis,
+    file_path: str,
+    criterion: dict,
+) -> bool:
+    """Match a single criterion against a file."""
+    for key, value in criterion.items():
+        if key == "has_decorator":
+            decorators = analysis.decorators_used or []
+            if not any(re.search(value, d) for d in decorators):
+                return False
+        elif key == "file_path":
+            if not re.match(value, file_path):
+                return False
+        elif key == "class_ends_with":
+            if not any(c.name.endswith(value) for c in (analysis.classes or [])):
+                return False
+        elif key == "imports":
+            import_modules = _import_modules(analysis)
+            if not all(imp in import_modules for imp in value):
+                return False
+        elif key == "not_imports":
+            import_modules = _import_modules(analysis)
+            if any(imp in import_modules for imp in value):
+                return False
+        elif key == "base_class":
+            if not any(
+                value in (c.bases or [])
+                for c in (analysis.classes or [])
+            ):
+                return False
+        else:
+            return False  # Unknown criterion, fail safe
+    return True
+
+
+def check_convention_rules(
+    analysis: FileAnalysis,
+    file_path: str,
+    rules: dict,
+) -> List[str]:
+    """Check a file against its convention's rules."""
+    violations = []
+
+    if "prohibited_imports" in rules:
+        import_modules = _import_modules(analysis)
+        for imp in rules["prohibited_imports"]:
+            if imp in import_modules:
+                violations.append(f"Prohibited import: {imp}")
+
+    if "required_methods" in rules:
+        if analysis.classes:
+            methods = set(analysis.classes[0].methods)
+            for required in rules["required_methods"]:
+                if required not in methods:
+                    violations.append(f"Missing required method: {required}")
+
+    if "must_have_matching" in rules:
+        pattern = rules["must_have_matching"]
+        filename = os.path.splitext(os.path.basename(file_path))[0]
+        stem = _extract_stem(filename)
+
+        expected_pattern = (
+            pattern
+            .replace("{filename}", re.escape(filename))
+            .replace("{captured_stem}", re.escape(stem))
+        )
+
+        # Search for a matching file in the repo
+        repo_root = _guess_repo_root(file_path)
+        if repo_root:
+            found = False
+            for candidate in _walk_files(repo_root):
+                if re.match(expected_pattern, candidate):
+                    found = True
+                    break
+            if not found:
+                violations.append(
+                    f"Missing matching file: {pattern} (resolved: {expected_pattern})"
+                )
+
+    return violations
+
+
+def _identify_matching_criteria(
+    analysis: FileAnalysis,
+    file_path: str,
+    match_criteria: dict,
+) -> List[str]:
+    """Identify which criteria matched for diagnostics."""
+    matched = []
+    for block_name in ("any_of", "all_of"):
+        for criterion in match_criteria.get(block_name, []):
+            for key in criterion:
+                if _matches_single(analysis, file_path, {key: criterion[key]}):
+                    matched.append(key)
+    return matched
+
+
+def _import_modules(analysis: FileAnalysis) -> set:
+    """Extract all import module names from a FileAnalysis."""
+    modules = set()
+    for imp in (analysis.imports or []):
+        if imp.module:
+            modules.add(imp.module)
+        # Also add individual imported names for granular matching
+        for name in (imp.names or []):
+            if imp.module:
+                modules.add(f"{imp.module}.{name}")
+        if imp.raw:
+            modules.add(imp.raw)
+    return modules
+
+
+def _extract_stem(filename: str) -> str:
+    """Extract stem by stripping common suffixes.
+
+    "user_controller" -> "user"
+    "billing_repo" -> "billing"
+    "auth_service" -> "auth"
+    """
+    for suffix in ("_controller", "_service", "_repo", "_repository",
+                    "_handler", "_manager", "_factory", "_helper",
+                    "_view", "_model", "_test"):
+        if filename.endswith(suffix):
+            return filename[:-len(suffix)]
+    return filename
+
+
+def _guess_repo_root(file_path: str) -> Optional[str]:
+    """Walk up from file_path to find repo root (contains .git or .scopes)."""
+    current = os.path.dirname(os.path.abspath(file_path))
+    for _ in range(10):
+        if os.path.exists(os.path.join(current, ".git")) or \
+           os.path.exists(os.path.join(current, ".scopes")):
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+    return None
+
+
+def _walk_files(root: str):
+    """Yield relative file paths under root."""
+    skip = {"__pycache__", ".git", "node_modules", ".tox", ".mypy_cache", "venv", ".venv"}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in skip]
+        for fn in filenames:
+            yield os.path.relpath(os.path.join(dirpath, fn), root)

dotscope/passes/graph_builder.py

@@ -0,0 +1,299 @@
+"""Dependency graph analysis: AST-powered import parsing, module boundary detection.
+
+Builds a file-level dependency graph with transitive closure support.
+"""
+
+import os
+from collections import defaultdict, deque
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+from ..ast_analyzer import (
+    analyze_file,
+    resolve_js_import,
+    resolve_python_import,
+)
+from ..constants import LANG_MAP, SKIP_DIRS
+from ..models.core import (
+    DependencyGraph,
+    FileNode,
+    ModuleBoundary,
+    ModuleAPI,
+)
+
+
+def build_graph(root: str) -> DependencyGraph:
+    """Build a dependency graph using AST analysis.
+
+    1. Walk all source files
+    2. AST-analyze each file for imports + API surface
+    3. Resolve imports to file paths
+    4. Detect module boundaries using directory cohesion
+    """
+    root = os.path.abspath(root)
+    graph = DependencyGraph(root=root)
+
+    source_files = _collect_source_files(root)
+
+    # AST analyze each file
+    for rel_path, language in source_files:
+        abs_path = os.path.join(root, rel_path)
+        api = analyze_file(abs_path, language)
+
+        resolved_imports = []
+        if api:
+            graph.apis[rel_path] = api
+            for imp in api.imports:
+                resolved = _resolve_import(imp, rel_path, root, language)
+                if resolved:
+                    resolved_imports.append(resolved)
+                    imp.resolved_path = resolved
+
+        node = FileNode(
+            path=rel_path,
+            language=language,
+            imports=resolved_imports,
+            api=api,
+        )
+        graph.files[rel_path] = node
+
+    # Build edge list and back-references
+    for path, node in graph.files.items():
+        for imp in node.imports:
+            graph.edges.append((path, imp))
+            if imp in graph.files:
+                graph.files[imp].imported_by.append(path)
+
+    graph.modules = _detect_modules(graph)
+    return graph
+
+
+def build_partial_graph(root: str, seed_files: List[str]) -> DependencyGraph:
+    """Build a graph containing only seed_files and their direct imports.
+
+    Used by lazy ingest to scope analysis to a single module.
+    Does NOT detect module boundaries (requires the full graph).
+
+    Args:
+        root: Repository root (absolute path)
+        seed_files: List of (relative_path, language) tuples
+    """
+    root = os.path.abspath(root)
+    graph = DependencyGraph(root=root)
+
+    # AST-analyze seed files
+    for rel_path, language in seed_files:
+        abs_path = os.path.join(root, rel_path)
+        api = analyze_file(abs_path, language)
+
+        resolved_imports = []
+        if api:
+            graph.apis[rel_path] = api
+            for imp in api.imports:
+                resolved = _resolve_import(imp, rel_path, root, language)
+                if resolved:
+                    resolved_imports.append(resolved)
+                    imp.resolved_path = resolved
+
+        node = FileNode(
+            path=rel_path,
+            language=language,
+            imports=resolved_imports,
+            api=api,
+        )
+        graph.files[rel_path] = node
+
+    # Follow direct imports one level deep
+    imports_to_add = []
+    for path, node in graph.files.items():
+        for imp in node.imports:
+            if imp not in graph.files:
+                imp_abs = os.path.join(root, imp)
+                if os.path.exists(imp_abs):
+                    ext = os.path.splitext(imp)[1]
+                    lang = LANG_MAP.get(ext)
+                    if lang:
+                        imports_to_add.append((imp, lang))
+
+    for rel_path, language in imports_to_add:
+        abs_path = os.path.join(root, rel_path)
+        api = analyze_file(abs_path, language)
+        if api:
+            graph.apis[rel_path] = api
+        node = FileNode(
+            path=rel_path,
+            language=language,
+            imports=[],
+            api=api,
+        )
+        graph.files[rel_path] = node
+
+    # Build edges
+    for path, node in graph.files.items():
+        for imp in node.imports:
+            graph.edges.append((path, imp))
+            if imp in graph.files:
+                graph.files[imp].imported_by.append(path)
+
+    return graph
+
+
+def transitive_deps(graph: DependencyGraph, file: str) -> Set[str]:
+    """BFS for all transitive dependencies of a file (cycle-safe)."""
+    visited = set()
+    queue = deque()
+
+    node = graph.files.get(file)
+    if not node:
+        return visited
+
+    for imp in node.imports:
+        queue.append(imp)
+
+    while queue:
+        current = queue.popleft()
+        if current in visited:
+            continue
+        visited.add(current)
+        dep_node = graph.files.get(current)
+        if dep_node:
+            for imp in dep_node.imports:
+                if imp not in visited:
+                    queue.append(imp)
+
+    return visited
+
+
+def transitive_dependents(graph: DependencyGraph, file: str) -> Set[str]:
+    """BFS for all transitive dependents of a file (who ultimately depends on this)."""
+    visited = set()
+    queue = deque()
+
+    node = graph.files.get(file)
+    if not node:
+        return visited
+
+    for imp_by in node.imported_by:
+        queue.append(imp_by)
+
+    while queue:
+        current = queue.popleft()
+        if current in visited:
+            continue
+        visited.add(current)
+        dep_node = graph.files.get(current)
+        if dep_node:
+            for imp_by in dep_node.imported_by:
+                if imp_by not in visited:
+                    queue.append(imp_by)
+
+    return visited
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+def _collect_source_files(root: str) -> List[Tuple[str, str]]:
+    """Walk the tree and collect (relative_path, language)."""
+    lang_map = {k: v.lower() for k, v in LANG_MAP.items()}
+    results = []
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for fn in filenames:
+            ext = os.path.splitext(fn)[1].lower()
+            if ext in lang_map:
+                rel = os.path.relpath(os.path.join(dirpath, fn), root)
+                results.append((rel, lang_map[ext]))
+
+    return sorted(results)
+
+
+def _resolve_import(imp, source_file: str, root: str, language: str):
+    """Resolve an import to a relative file path."""
+    if language == "python":
+        return resolve_python_import(imp, os.path.join(root, source_file), root)
+    elif language in ("javascript", "typescript"):
+        return resolve_js_import(imp, os.path.join(root, source_file), root)
+    elif language == "go":
+        from .lang.go import resolve_go_import
+        return resolve_go_import(imp, os.path.join(root, source_file), root)
+    return None
+
+
+def _detect_modules(graph: DependencyGraph) -> List[ModuleBoundary]:
+    """Detect module boundaries using directory structure + import cohesion.
+
+    Uses transitive coupling for more accurate cohesion scoring.
+    """
+    dir_files: Dict[str, List[str]] = defaultdict(list)
+    for rel_path in graph.files:
+        parts = Path(rel_path).parts
+        if len(parts) > 1:
+            dir_files[parts[0]].append(rel_path)
+
+    modules = []
+    for directory, files in sorted(dir_files.items()):
+        file_set = set(files)
+        internal = 0
+        external = 0
+        ext_deps: Set[str] = set()
+        dep_by: Set[str] = set()
+
+        for f in files:
+            # Use transitive deps for richer cohesion
+            all_deps = transitive_deps(graph, f)
+            for dep in all_deps:
+                if dep in file_set:
+                    internal += 1
+                else:
+                    external += 1
+                    dep_parts = Path(dep).parts
+                    if len(dep_parts) > 1:
+                        ext_deps.add(dep_parts[0])
+
+            all_dependents = transitive_dependents(graph, f)
+            for dep_by_file in all_dependents:
+                if dep_by_file not in file_set:
+                    dep_parts = Path(dep_by_file).parts
+                    if len(dep_parts) > 1:
+                        dep_by.add(dep_parts[0])
+
+        total = internal + external
+        cohesion = internal / total if total > 0 else 1.0
+
+        modules.append(ModuleBoundary(
+            directory=directory,
+            files=files,
+            internal_edges=internal,
+            external_edges=external,
+            external_deps=sorted(ext_deps - {directory}),
+            depended_on_by=sorted(dep_by - {directory}),
+            cohesion=round(cohesion, 3),
+        ))
+
+    modules.sort(key=lambda m: -len(m.files))
+    return modules
+
+
+def format_graph_summary(graph: DependencyGraph) -> str:
+    """Human-readable summary of the dependency graph."""
+    lines = [
+        f"Dependency Graph: {len(graph.files)} files, {len(graph.edges)} edges",
+        f"Detected {len(graph.modules)} module(s):",
+        "",
+    ]
+
+    for mod in graph.modules:
+        cohesion_bar = "█" * int(mod.cohesion * 10) + "░" * (10 - int(mod.cohesion * 10))
+        lines.append(
+            f"  {mod.directory}/ — {len(mod.files)} files, "
+            f"cohesion: {cohesion_bar} {mod.cohesion:.0%}"
+        )
+        if mod.external_deps:
+            lines.append(f"    depends on: {', '.join(mod.external_deps)}")
+        if mod.depended_on_by:
+            lines.append(f"    used by: {', '.join(mod.depended_on_by)}")
+
+    return "\n".join(lines)