attocode-code-intel 0.1.0__py3-none-any.whl

attocode_intel/_internal/integrations/context/architecture_drift.py

@@ -0,0 +1,354 @@
+"""Architecture drift detection.
+
+Compares actual file dependencies against declared architecture boundaries
+to detect layering violations, circular dependencies, and unauthorized imports.
+
+Loads rules from ``.attocode/architecture.yaml`` and checks them against the
+real dependency graph built by the AST service.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ArchViolation:
+    """A single architecture boundary violation."""
+
+    source_file: str  # file that has the import
+    target_file: str  # file being imported
+    source_layer: str  # layer the source belongs to
+    target_layer: str  # layer the target belongs to
+    rule: str  # human-readable rule description
+    severity: str = "high"  # high for deny violations, medium for unlisted
+
+
+@dataclass(slots=True)
+class ArchReport:
+    """Architecture drift detection report."""
+
+    violations: list[ArchViolation]
+    layers_defined: int
+    rules_defined: int
+    files_checked: int
+    compliant_files: int
+
+
+@dataclass
+class ArchLayer:
+    """A named architecture layer with path patterns."""
+
+    name: str
+    paths: list[str]
+
+    def matches(self, file_path: str) -> bool:
+        """Check if a file belongs to this layer.
+
+        Uses forward-slash normalised prefix matching so that OS-specific
+        separators do not cause false negatives.
+        """
+        normalised = file_path.replace(os.sep, "/")
+        for path_prefix in self.paths:
+            prefix = path_prefix.replace(os.sep, "/")
+            if normalised.startswith(prefix):
+                return True
+        return False
+
+
+@dataclass
+class ArchRule:
+    """A dependency rule between layers."""
+
+    from_layer: str
+    allowed: list[str] = field(default_factory=list)
+    denied: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+
+
+def load_architecture(
+    project_dir: str,
+) -> tuple[list[ArchLayer], list[ArchRule], dict[str, list[str]]]:
+    """Load architecture definitions from ``.attocode/architecture.yaml``.
+
+    Returns:
+        A 3-tuple of ``(layers, rules, exceptions)`` where *exceptions* maps
+        a source file path to a list of explicitly-allowed target paths.
+
+    If the YAML file does not exist or PyYAML is not installed the function
+    returns empty collections without raising.
+    """
+    config_path = os.path.join(project_dir, ".attocode", "architecture.yaml")
+    if not os.path.isfile(config_path):
+        logger.debug("Architecture config not found: %s", config_path)
+        return [], [], {}
+
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        logger.warning(
+            "PyYAML is not installed -- cannot load architecture config.  "
+            "Install it with: pip install pyyaml"
+        )
+        return [], [], {}
+
+    try:
+        with open(config_path, encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except Exception as exc:
+        logger.warning("Failed to parse architecture config: %s", exc)
+        return [], [], {}
+
+    # --- Layers ---
+    layers: list[ArchLayer] = []
+    for entry in data.get("layers", []):
+        name = entry.get("name", "")
+        paths = entry.get("paths", [])
+        if name and paths:
+            layers.append(ArchLayer(name=name, paths=paths))
+
+    # --- Rules ---
+    rules: list[ArchRule] = []
+    for entry in data.get("rules", []):
+        from_layer = entry.get("from", "")
+        if not from_layer:
+            continue
+        allowed = entry.get("to", [])
+        denied = entry.get("deny", [])
+        rules.append(ArchRule(from_layer=from_layer, allowed=allowed, denied=denied))
+
+    # --- Exceptions ---
+    exceptions: dict[str, list[str]] = {}
+    for entry in data.get("exceptions", []):
+        src = entry.get("file", "")
+        allowed_targets = entry.get("allowed", [])
+        if src and allowed_targets:
+            exceptions[src] = allowed_targets
+
+    return layers, rules, exceptions
+
+
+# ---------------------------------------------------------------------------
+# Classification
+# ---------------------------------------------------------------------------
+
+
+def classify_file(file_path: str, layers: list[ArchLayer]) -> str:
+    """Determine which layer *file_path* belongs to.
+
+    Returns the layer name, or ``""`` if the file does not match any layer.
+    Matches are evaluated in order; the first matching layer wins.
+    """
+    for layer in layers:
+        if layer.matches(file_path):
+            return layer.name
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Core check
+# ---------------------------------------------------------------------------
+
+
+def _build_deps_from_index(project_dir: str) -> dict[str, set[str]]:
+    """Build a dependency map from the AST service's CrossRefIndex."""
+    try:
+        from attocode_intel._internal.integrations.context.ast_service import ASTService
+
+        svc = ASTService.get_instance(project_dir)
+        if not svc.initialized:
+            svc.initialize_skeleton(indexing_depth="auto")
+        return dict(svc.index.file_dependencies)
+    except Exception as exc:
+        logger.debug("Could not build dependency map from AST index: %s", exc)
+        return {}
+
+
+def check_drift(
+    project_dir: str,
+    dependencies: dict[str, set[str]] | None = None,
+) -> ArchReport:
+    """Check actual dependencies against architecture rules.
+
+    Args:
+        project_dir: Project root.
+        dependencies: Optional pre-computed dependency map
+            (file -> set of imported files).  If *None*, will build from
+            the AST service's ``CrossRefIndex.file_dependencies``.
+
+    Returns:
+        An :class:`ArchReport` summarising all violations found.
+    """
+    layers, rules, exceptions = load_architecture(project_dir)
+    if not layers:
+        return ArchReport(
+            violations=[],
+            layers_defined=0,
+            rules_defined=0,
+            files_checked=0,
+            compliant_files=0,
+        )
+
+    if dependencies is None:
+        dependencies = _build_deps_from_index(project_dir)
+
+    # Build a quick rule lookup: from_layer -> ArchRule
+    rule_map: dict[str, ArchRule] = {}
+    for rule in rules:
+        rule_map[rule.from_layer] = rule
+
+    violations: list[ArchViolation] = []
+    files_checked = 0
+    compliant_files = 0
+
+    for source_file, targets in dependencies.items():
+        source_layer = classify_file(source_file, layers)
+        if not source_layer:
+            # File is outside any declared layer -- skip
+            continue
+
+        files_checked += 1
+        file_has_violation = False
+
+        for target_file in targets:
+            target_layer = classify_file(target_file, layers)
+            if not target_layer:
+                # Target outside all layers -- nothing to enforce
+                continue
+            if source_layer == target_layer:
+                # Intra-layer dependency -- always allowed
+                continue
+
+            # Check file-level exceptions
+            exception_list = exceptions.get(source_file, [])
+            if target_file in exception_list:
+                continue
+
+            rule = rule_map.get(source_layer)
+            if rule is None:
+                # No rule defined for this layer -- nothing to enforce
+                continue
+
+            # Check explicit deny list first (high severity)
+            if target_layer in rule.denied:
+                violations.append(
+                    ArchViolation(
+                        source_file=source_file,
+                        target_file=target_file,
+                        source_layer=source_layer,
+                        target_layer=target_layer,
+                        rule=(
+                            f"Layer '{source_layer}' must NOT depend on "
+                            f"'{target_layer}' (deny rule)"
+                        ),
+                        severity="high",
+                    )
+                )
+                file_has_violation = True
+                continue
+
+            # Check allowed list (medium severity if not explicitly listed)
+            if rule.allowed and target_layer not in rule.allowed:
+                violations.append(
+                    ArchViolation(
+                        source_file=source_file,
+                        target_file=target_file,
+                        source_layer=source_layer,
+                        target_layer=target_layer,
+                        rule=(
+                            f"Layer '{source_layer}' does not list "
+                            f"'{target_layer}' as an allowed dependency"
+                        ),
+                        severity="medium",
+                    )
+                )
+                file_has_violation = True
+
+        if not file_has_violation:
+            compliant_files += 1
+
+    # Sort: high severity first, then by source file for stability
+    _severity_order = {"high": 0, "medium": 1, "low": 2}
+    violations.sort(
+        key=lambda v: (_severity_order.get(v.severity, 9), v.source_file, v.target_file)
+    )
+
+    return ArchReport(
+        violations=violations,
+        layers_defined=len(layers),
+        rules_defined=len(rules),
+        files_checked=files_checked,
+        compliant_files=compliant_files,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Formatting
+# ---------------------------------------------------------------------------
+
+
+def format_report(report: ArchReport) -> str:
+    """Format an :class:`ArchReport` as human-readable text."""
+    lines: list[str] = []
+    lines.append("# Architecture Drift Report\n")
+
+    lines.append(
+        f"Layers defined: {report.layers_defined}  |  "
+        f"Rules defined: {report.rules_defined}"
+    )
+    lines.append(
+        f"Files checked: {report.files_checked}  |  "
+        f"Compliant: {report.compliant_files}"
+    )
+
+    if not report.violations:
+        lines.append("\nNo architecture violations detected. All checked files comply.")
+        return "\n".join(lines)
+
+    # Group by severity
+    high: list[ArchViolation] = []
+    medium: list[ArchViolation] = []
+    other: list[ArchViolation] = []
+    for v in report.violations:
+        if v.severity == "high":
+            high.append(v)
+        elif v.severity == "medium":
+            medium.append(v)
+        else:
+            other.append(v)
+
+    total = len(report.violations)
+    lines.append(f"\n{total} violation(s) found.\n")
+
+    if high:
+        lines.append(f"## HIGH severity ({len(high)})\n")
+        for v in high:
+            lines.append(f"  {v.source_file} -> {v.target_file}")
+            lines.append(f"    [{v.source_layer} -> {v.target_layer}] {v.rule}")
+
+    if medium:
+        lines.append(f"\n## MEDIUM severity ({len(medium)})\n")
+        for v in medium:
+            lines.append(f"  {v.source_file} -> {v.target_file}")
+            lines.append(f"    [{v.source_layer} -> {v.target_layer}] {v.rule}")
+
+    if other:
+        lines.append(f"\n## OTHER ({len(other)})\n")
+        for v in other:
+            lines.append(f"  {v.source_file} -> {v.target_file}")
+            lines.append(f"    [{v.source_layer} -> {v.target_layer}] {v.rule}")
+
+    return "\n".join(lines)

attocode_intel/_internal/integrations/context/ast_chunker.py

@@ -0,0 +1,202 @@
+"""AST-aware code chunking for semantic search.
+
+Produces structural chunks at function/method/class boundaries that include
+actual source code, not just metadata summaries. This significantly improves
+search recall for code-understanding queries (cAST paper: +4.3pts Recall@5).
+
+Used by ``SemanticSearchManager`` in two-stage retrieval mode.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class CodeChunk:
+    """A structural code chunk extracted from AST boundaries."""
+
+    id: str  # unique chunk ID (e.g. "func:path:name")
+    file_path: str  # relative path
+    chunk_type: str  # "file", "function", "class", "method"
+    name: str  # symbol name
+    text: str  # actual code content (for embedding)
+    start_line: int
+    end_line: int
+    metadata: str  # additional context (imports, params, bases)
+
+
+def chunk_file(
+    file_path: str,
+    relative_path: str,
+    content: str | None = None,
+    max_chunk_lines: int = 80,
+) -> list[CodeChunk]:
+    """Extract structural code chunks from a file using AST boundaries.
+
+    Chunks at function, method, and class boundaries. Each chunk includes
+    the actual source code (truncated to ``max_chunk_lines``) plus metadata
+    (imports, parameters, return types, base classes).
+
+    Args:
+        file_path: Absolute path to the source file.
+        relative_path: Relative path for chunk IDs.
+        content: Optional file content (read from disk if not provided).
+        max_chunk_lines: Maximum lines of code to include per chunk.
+
+    Returns:
+        List of CodeChunk objects.
+    """
+    if content is None:
+        try:
+            content = Path(file_path).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return []
+
+    from attocode_intel._internal.integrations.context.codebase_ast import parse_file
+
+    try:
+        ast = parse_file(file_path, content=content)
+    except Exception:
+        return []
+
+    lines = content.splitlines()
+    chunks: list[CodeChunk] = []
+
+    # File-level chunk: imports + top-level summary
+    imports = [imp.module for imp in ast.imports[:15]]
+    symbols = ast.get_symbols()[:15]
+    file_meta_parts = []
+    if imports:
+        file_meta_parts.append(f"imports: {', '.join(imports)}")
+    if symbols:
+        file_meta_parts.append(f"defines: {', '.join(symbols)}")
+
+    # Take first N lines as file overview (docstring + imports area)
+    file_preview_end = min(40, len(lines))
+    file_text = "\n".join(lines[:file_preview_end])
+    if len(lines) > file_preview_end:
+        file_text += f"\n... ({len(lines) - file_preview_end} more lines)"
+
+    chunks.append(CodeChunk(
+        id=f"file:{relative_path}",
+        file_path=relative_path,
+        chunk_type="file",
+        name=os.path.basename(relative_path),
+        text=file_text,
+        start_line=1,
+        end_line=len(lines),
+        metadata=" | ".join(file_meta_parts),
+    ))
+
+    # Function-level chunks
+    for func in ast.functions:
+        start = max(0, func.start_line - 1)
+        end = min(len(lines), func.end_line)
+        code_lines = lines[start:end]
+        if len(code_lines) > max_chunk_lines:
+            code_lines = code_lines[:max_chunk_lines]
+            code_lines.append(f"    # ... ({func.end_line - func.start_line - max_chunk_lines} more lines)")
+
+        params = ", ".join(p.name for p in func.parameters[:8])
+        meta_parts = [f"function {func.name}({params})"]
+        if func.return_type:
+            meta_parts.append(f"-> {func.return_type}")
+        if func.decorators:
+            meta_parts.append(f"decorators: {', '.join(func.decorators[:3])}")
+
+        chunks.append(CodeChunk(
+            id=f"func:{relative_path}:{func.name}",
+            file_path=relative_path,
+            chunk_type="function",
+            name=func.name,
+            text="\n".join(code_lines),
+            start_line=func.start_line,
+            end_line=func.end_line,
+            metadata=" | ".join(meta_parts),
+        ))
+
+    # Class-level chunks
+    for cls in ast.classes:
+        start = max(0, cls.start_line - 1)
+        end = min(len(lines), cls.end_line)
+        code_lines = lines[start:end]
+        if len(code_lines) > max_chunk_lines:
+            code_lines = code_lines[:max_chunk_lines]
+            code_lines.append(f"    # ... ({cls.end_line - cls.start_line - max_chunk_lines} more lines)")
+
+        meta_parts = [f"class {cls.name}"]
+        if cls.bases:
+            meta_parts.append(f"extends: {', '.join(cls.bases[:5])}")
+        methods = [m.name for m in cls.methods[:10]]
+        if methods:
+            meta_parts.append(f"methods: {', '.join(methods)}")
+
+        chunks.append(CodeChunk(
+            id=f"cls:{relative_path}:{cls.name}",
+            file_path=relative_path,
+            chunk_type="class",
+            name=cls.name,
+            text="\n".join(code_lines),
+            start_line=cls.start_line,
+            end_line=cls.end_line,
+            metadata=" | ".join(meta_parts),
+        ))
+
+        # Method-level chunks for large classes
+        for method in cls.methods:
+            m_start = max(0, method.start_line - 1)
+            m_end = min(len(lines), method.end_line)
+            m_lines = lines[m_start:m_end]
+            if len(m_lines) > max_chunk_lines:
+                m_lines = m_lines[:max_chunk_lines]
+                m_lines.append(f"        # ... ({method.end_line - method.start_line - max_chunk_lines} more lines)")
+
+            m_params = ", ".join(p.name for p in method.parameters[:8])
+            m_meta_parts = [f"method {cls.name}.{method.name}({m_params})"]
+            if method.return_type:
+                m_meta_parts.append(f"-> {method.return_type}")
+
+            chunks.append(CodeChunk(
+                id=f"method:{relative_path}:{cls.name}.{method.name}",
+                file_path=relative_path,
+                chunk_type="method",
+                name=f"{cls.name}.{method.name}",
+                text="\n".join(m_lines),
+                start_line=method.start_line,
+                end_line=method.end_line,
+                metadata=" | ".join(m_meta_parts),
+            ))
+
+    return chunks
+
+
+def reciprocal_rank_fusion(
+    *result_lists: list[tuple[str, float]],
+    k: int = 60,
+) -> list[tuple[str, float]]:
+    """Merge multiple ranked result lists using Reciprocal Rank Fusion.
+
+    Each input is a list of (id, score) tuples sorted by score descending.
+    Returns a merged list sorted by fused score descending.
+
+    Args:
+        *result_lists: Variable number of ranked result lists.
+        k: RRF constant (default 60, standard from literature).
+
+    Returns:
+        Merged list of (id, fused_score) sorted by score descending.
+    """
+    fused: dict[str, float] = {}
+
+    for results in result_lists:
+        for rank, (item_id, _score) in enumerate(results):
+            fused[item_id] = fused.get(item_id, 0.0) + 1.0 / (k + rank + 1)
+
+    sorted_results = sorted(fused.items(), key=lambda x: x[1], reverse=True)
+    return sorted_results